Merge pull request #14941 from esphome/bump-2026.3.0

2026.3.0

.ai/instructions.md

@@ -286,6 +286,7 @@ This document provides essential context for AI models interacting with this pro
 *   **Documentation Contributions:**
     *   Documentation is hosted in the separate `esphome/esphome-docs` repository.
     *   The contribution workflow is the same as for the codebase.
+    *   When editing a component's documentation page, also update the corresponding component index page to ensure both pages remain in sync.
 
 *   **Best Practices:**
     *   **Component Development:** Keep dependencies minimal, provide clear error messages, and write comprehensive docstrings and tests.

.clang-tidy.hash

@@ -1 +1 @@
-ce05c28e9dc0b12c4f6e7454986ffea5123ac974a949da841be698c535f2083e
+8e48e836c6fc196d3da000d46eb09db243b87fe33518a74e49c8e009d756074a

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,8 +6,9 @@
 
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Developer breaking change (an API change that could break external components)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) — [policy](https://developers.esphome.io/contributing/code/#what-constitutes-a-c-breaking-change)
+- [ ] Developer breaking change (an API change that could break external components) — [policy](https://developers.esphome.io/contributing/code/#what-is-considered-public-c-api)
+- [ ] Undocumented C++ API change (removal or change of undocumented public methods that lambda users may depend on) — [policy](https://developers.esphome.io/contributing/code/#c-user-expectations)
 - [ ] Code quality improvements to existing code or addition of tests
 - [ ] Other
 
@@ -24,7 +25,7 @@
 - [ ] ESP32
 - [ ] ESP32 IDF
 - [ ] ESP8266
-- [ ] RP2040
+- [ ] RP2040/RP2350
 - [ ] BK72xx
 - [ ] RTL87xx
 - [ ] LN882x

.github/actions/build-image/action.yaml

@@ -47,7 +47,7 @@ runs:
 
     - name: Build and push to ghcr by digest
       id: build-ghcr
-      uses: docker/build-push-action@601a80b39c9405e50806ae38af30926f9d957c47 # v6.19.1
+      uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
       env:
         DOCKER_BUILD_SUMMARY: false
         DOCKER_BUILD_RECORD_UPLOAD: false
@@ -73,7 +73,7 @@ runs:
 
     - name: Build and push to dockerhub by digest
       id: build-dockerhub
-      uses: docker/build-push-action@601a80b39c9405e50806ae38af30926f9d957c47 # v6.19.1
+      uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
       env:
         DOCKER_BUILD_SUMMARY: false
         DOCKER_BUILD_RECORD_UPLOAD: false

.github/scripts/auto-label-pr/constants.js

@@ -14,6 +14,7 @@ module.exports = {
     'chained-pr',
     'core',
     'small-pr',
+    'medium-pr',
     'dashboard',
     'github-actions',
     'by-code-owner',
@@ -27,6 +28,7 @@ module.exports = {
     'new-feature',
     'breaking-change',
     'developer-breaking-change',
+    'undocumented-api-change',
     'code-quality',
     'deprecated-component'
   ],

.github/scripts/auto-label-pr/detectors.js

@@ -1,5 +1,13 @@
 const fs = require('fs');
 const { DOCS_PR_PATTERNS } = require('./constants');
+const {
+  COMPONENT_REGEX,
+  detectComponents,
+  hasCoreChanges,
+  hasDashboardChanges,
+  hasGitHubActionsChanges,
+} = require('../detect-tags');
+const { loadCodeowners, getEffectiveOwners } = require('../codeowners');
 
 // Strategy: Merge branch detection
 async function detectMergeBranch(context) {
@@ -20,15 +28,13 @@ async function detectMergeBranch(context) {
 // Strategy: Component and platform labeling
 async function detectComponentPlatforms(changedFiles, apiData) {
   const labels = new Set();
-  const componentRegex = /^esphome\/components\/([^\/]+)\//;
   const targetPlatformRegex = new RegExp(`^esphome\/components\/(${apiData.targetPlatforms.join('|')})/`);
 
-  for (const file of changedFiles) {
-    const componentMatch = file.match(componentRegex);
-    if (componentMatch) {
-      labels.add(`component: ${componentMatch[1]}`);
-    }
+  for (const comp of detectComponents(changedFiles)) {
+    labels.add(`component: ${comp}`);
+  }
 
+  for (const file of changedFiles) {
     const platformMatch = file.match(targetPlatformRegex);
     if (platformMatch) {
       labels.add(`platform: ${platformMatch[1]}`);
@@ -90,20 +96,14 @@ async function detectNewPlatforms(prFiles, apiData) {
 // Strategy: Core files detection
 async function detectCoreChanges(changedFiles) {
   const labels = new Set();
-  const coreFiles = changedFiles.filter(file =>
-    file.startsWith('esphome/core/') ||
-    (file.startsWith('esphome/') && file.split('/').length === 2)
-  );
-
-  if (coreFiles.length > 0) {
+  if (hasCoreChanges(changedFiles)) {
     labels.add('core');
   }
-
   return labels;
 }
 
 // Strategy: PR size detection
-async function detectPRSize(prFiles, totalAdditions, totalDeletions, totalChanges, isMegaPR, SMALL_PR_THRESHOLD, TOO_BIG_THRESHOLD) {
+async function detectPRSize(prFiles, totalAdditions, totalDeletions, totalChanges, isMegaPR, SMALL_PR_THRESHOLD, MEDIUM_PR_THRESHOLD, TOO_BIG_THRESHOLD) {
   const labels = new Set();
 
   if (totalChanges <= SMALL_PR_THRESHOLD) {
@@ -111,6 +111,11 @@ async function detectPRSize(prFiles, totalAdditions, totalDeletions, totalChange
     return labels;
   }
 
+  if (totalChanges <= MEDIUM_PR_THRESHOLD) {
+    labels.add('medium-pr');
+    return labels;
+  }
+
   const testAdditions = prFiles
     .filter(file => file.filename.startsWith('tests/'))
     .reduce((sum, file) => sum + (file.additions || 0), 0);
@@ -131,80 +136,33 @@ async function detectPRSize(prFiles, totalAdditions, totalDeletions, totalChange
 // Strategy: Dashboard changes
 async function detectDashboardChanges(changedFiles) {
   const labels = new Set();
-  const dashboardFiles = changedFiles.filter(file =>
-    file.startsWith('esphome/dashboard/') ||
-    file.startsWith('esphome/components/dashboard_import/')
-  );
-
-  if (dashboardFiles.length > 0) {
+  if (hasDashboardChanges(changedFiles)) {
     labels.add('dashboard');
   }
-
   return labels;
 }
 
 // Strategy: GitHub Actions changes
 async function detectGitHubActionsChanges(changedFiles) {
   const labels = new Set();
-  const githubActionsFiles = changedFiles.filter(file =>
-    file.startsWith('.github/workflows/')
-  );
-
-  if (githubActionsFiles.length > 0) {
+  if (hasGitHubActionsChanges(changedFiles)) {
     labels.add('github-actions');
   }
-
   return labels;
 }
 
 // Strategy: Code owner detection
 async function detectCodeOwner(github, context, changedFiles) {
   const labels = new Set();
-  const { owner, repo } = context.repo;
 
   try {
-    const { data: codeownersFile } = await github.rest.repos.getContent({
-      owner,
-      repo,
-      path: 'CODEOWNERS',
-    });
-
-    const codeownersContent = Buffer.from(codeownersFile.content, 'base64').toString('utf8');
+    const codeownersPatterns = loadCodeowners();
     const prAuthor = context.payload.pull_request.user.login;
 
-    const codeownersLines = codeownersContent.split('\n')
-      .map(line => line.trim())
-      .filter(line => line && !line.startsWith('#'));
-
-    const codeownersRegexes = codeownersLines.map(line => {
-      const parts = line.split(/\s+/);
-      const pattern = parts[0];
-      const owners = parts.slice(1);
-
-      let regex;
-      if (pattern.endsWith('*')) {
-        const dir = pattern.slice(0, -1);
-        regex = new RegExp(`^${dir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`);
-      } else if (pattern.includes('*')) {
-        // First escape all regex special chars except *, then replace * with .*
-        const regexPattern = pattern
-          .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
-          .replace(/\*/g, '.*');
-        regex = new RegExp(`^${regexPattern}$`);
-      } else {
-        regex = new RegExp(`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
-      }
-
-      return { regex, owners };
-    });
-
-    for (const file of changedFiles) {
-      for (const { regex, owners } of codeownersRegexes) {
-        if (regex.test(file) && owners.some(owner => owner === `@${prAuthor}`)) {
-          labels.add('by-code-owner');
-          return labels;
-        }
-      }
+    // Check if PR author is a codeowner of any changed file
+    const effective = getEffectiveOwners(changedFiles, codeownersPatterns);
+    if (effective.users.has(prAuthor)) {
+      labels.add('by-code-owner');
     }
   } catch (error) {
     console.log('Failed to read or parse CODEOWNERS file:', error.message);
@@ -238,6 +196,7 @@ async function detectPRTemplateCheckboxes(context) {
     { pattern: /- \[x\] New feature \(non-breaking change which adds functionality\)/i, label: 'new-feature' },
     { pattern: /- \[x\] Breaking change \(fix or feature that would cause existing functionality to not work as expected\)/i, label: 'breaking-change' },
     { pattern: /- \[x\] Developer breaking change \(an API change that could break external components\)/i, label: 'developer-breaking-change' },
+    { pattern: /- \[x\] Undocumented C\+\+ API change \(removal or change of undocumented public methods that lambda users may depend on\)/i, label: 'undocumented-api-change' },
     { pattern: /- \[x\] Code quality improvements to existing code or addition of tests/i, label: 'code-quality' }
   ];
 
@@ -258,7 +217,7 @@ async function detectDeprecatedComponents(github, context, changedFiles) {
   const { owner, repo } = context.repo;
 
   // Compile regex once for better performance
-  const componentFileRegex = /^esphome\/components\/([^\/]+)\//;
+  const componentFileRegex = COMPONENT_REGEX;
 
   // Get files that are modified or added in components directory
   const componentFiles = changedFiles.filter(file => componentFileRegex.test(file));

.github/scripts/auto-label-pr/index.js

@@ -35,6 +35,7 @@ async function fetchApiData() {
 module.exports = async ({ github, context }) => {
   // Environment variables
   const SMALL_PR_THRESHOLD = parseInt(process.env.SMALL_PR_THRESHOLD);
+  const MEDIUM_PR_THRESHOLD = parseInt(process.env.MEDIUM_PR_THRESHOLD);
   const MAX_LABELS = parseInt(process.env.MAX_LABELS);
   const TOO_BIG_THRESHOLD = parseInt(process.env.TOO_BIG_THRESHOLD);
   const COMPONENT_LABEL_THRESHOLD = parseInt(process.env.COMPONENT_LABEL_THRESHOLD);
@@ -120,7 +121,7 @@ module.exports = async ({ github, context }) => {
     detectNewComponents(prFiles),
     detectNewPlatforms(prFiles, apiData),
     detectCoreChanges(changedFiles),
-    detectPRSize(prFiles, totalAdditions, totalDeletions, totalChanges, isMegaPR, SMALL_PR_THRESHOLD, TOO_BIG_THRESHOLD),
+    detectPRSize(prFiles, totalAdditions, totalDeletions, totalChanges, isMegaPR, SMALL_PR_THRESHOLD, MEDIUM_PR_THRESHOLD, TOO_BIG_THRESHOLD),
     detectDashboardChanges(changedFiles),
     detectGitHubActionsChanges(changedFiles),
     detectCodeOwner(github, context, changedFiles),

.github/scripts/codeowners.js

@@ -0,0 +1,227 @@
+// Shared CODEOWNERS parsing and matching utilities.
+//
+// Used by:
+//   - codeowner-review-request.yml
+//   - codeowner-approved-label-update.yml
+//   - auto-label-pr/detectors.js (detectCodeOwner)
+
+/**
+ * Convert a CODEOWNERS glob pattern to a RegExp.
+ *
+ * Handles **, *, and ? wildcards after escaping regex-special characters.
+ */
+function globToRegex(pattern) {
+  let regexStr = pattern
+    .replace(/([.+^=!:${}()|[\]\\])/g, '\\$1')
+    .replace(/\*\*/g, '\x00GLOBSTAR\x00')  // protect ** from next replace
+    .replace(/\*/g, '[^/]*')               // single star
+    .replace(/\x00GLOBSTAR\x00/g, '.*')    // restore globstar
+    .replace(/\?/g, '.');
+  return new RegExp('^' + regexStr + '$');
+}
+
+/**
+ * Parse raw CODEOWNERS file content into an array of
+ * { pattern, regex, owners } objects.
+ *
+ * Each `owners` entry is the raw string from the file (e.g. "@user" or
+ * "@esphome/core").
+ */
+function parseCodeowners(content) {
+  const lines = content
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'));
+
+  const patterns = [];
+  for (const line of lines) {
+    const parts = line.split(/\s+/);
+    if (parts.length < 2) continue;
+
+    const pattern = parts[0];
+    const owners = parts.slice(1);
+    const regex = globToRegex(pattern);
+    patterns.push({ pattern, regex, owners });
+  }
+  return patterns;
+}
+
+/**
+ * Fetch and parse the CODEOWNERS file via the GitHub API.
+ *
+ * @param {object} github  - octokit instance from actions/github-script
+ * @param {string} owner   - repo owner
+ * @param {string} repo    - repo name
+ * @param {string} [ref]   - git ref (SHA / branch) to read from
+ * @returns {Array<{pattern: string, regex: RegExp, owners: string[]}>}
+ */
+async function fetchCodeowners(github, owner, repo, ref) {
+  const params = { owner, repo, path: 'CODEOWNERS' };
+  if (ref) params.ref = ref;
+
+  const { data: file } = await github.rest.repos.getContent(params);
+  const content = Buffer.from(file.content, 'base64').toString('utf8');
+  return parseCodeowners(content);
+}
+
+/**
+ * Classify raw owner strings into individual users and teams.
+ *
+ * @param {string[]} rawOwners - e.g. ["@user1", "@esphome/core"]
+ * @returns {{ users: string[], teams: string[] }}
+ *   users  – login names without "@"
+ *   teams  – team slugs without the "org/" prefix
+ */
+function classifyOwners(rawOwners) {
+  const users = [];
+  const teams = [];
+  for (const o of rawOwners) {
+    const clean = o.startsWith('@') ? o.slice(1) : o;
+    if (clean.includes('/')) {
+      teams.push(clean.split('/')[1]);
+    } else {
+      users.push(clean);
+    }
+  }
+  return { users, teams };
+}
+
+/**
+ * For each file, find its effective codeowners using GitHub's
+ * "last match wins" semantics, then union across all files.
+ *
+ * @param {string[]} files              - list of file paths
+ * @param {Array}    codeownersPatterns  - from parseCodeowners / fetchCodeowners
+ * @returns {{ users: Set<string>, teams: Set<string>, matchedFileCount: number }}
+ */
+function getEffectiveOwners(files, codeownersPatterns) {
+  const users = new Set();
+  const teams = new Set();
+  let matchedFileCount = 0;
+
+  for (const file of files) {
+    // Last matching pattern wins for each file
+    let effectiveOwners = null;
+    for (const { regex, owners } of codeownersPatterns) {
+      if (regex.test(file)) {
+        effectiveOwners = owners;
+      }
+    }
+    if (effectiveOwners) {
+      matchedFileCount++;
+      const classified = classifyOwners(effectiveOwners);
+      for (const u of classified.users) users.add(u);
+      for (const t of classified.teams) teams.add(t);
+    }
+  }
+
+  return { users, teams, matchedFileCount };
+}
+
+/**
+ * Read and parse the CODEOWNERS file from disk.
+ *
+ * Use this when the repo is already checked out (avoids an API call).
+ *
+ * @param {string} [repoRoot='.'] - path to the repo root
+ * @returns {Array<{pattern: string, regex: RegExp, owners: string[]}>}
+ */
+function loadCodeowners(repoRoot = '.') {
+  const fs = require('fs');
+  const path = require('path');
+  const content = fs.readFileSync(path.join(repoRoot, 'CODEOWNERS'), 'utf8');
+  return parseCodeowners(content);
+}
+
+/** Possible label actions returned by determineLabelAction. */
+const LabelAction = Object.freeze({
+  ADD: 'add',
+  REMOVE: 'remove',
+  NONE: 'none',
+});
+
+/**
+ * Determine what label action is needed for a PR based on codeowner approvals.
+ *
+ * Checks changed files against CODEOWNERS patterns, reviews, and current labels
+ * to decide if the label should be added, removed, or left unchanged.
+ *
+ * @param {object} github              - octokit instance from actions/github-script
+ * @param {string} owner               - repo owner
+ * @param {string} repo                - repo name
+ * @param {number} pr_number           - pull request number
+ * @param {Array}  codeownersPatterns   - from loadCodeowners / fetchCodeowners
+ * @param {string} labelName           - label to manage
+ * @returns {Promise<LabelAction>}
+ */
+async function determineLabelAction(github, owner, repo, pr_number, codeownersPatterns, labelName) {
+  // Get the list of changed files in this PR
+  const prFiles = await github.paginate(
+    github.rest.pulls.listFiles,
+    { owner, repo, pull_number: pr_number }
+  );
+
+  const changedFiles = prFiles.map(file => file.filename);
+  console.log(`Found ${changedFiles.length} changed files`);
+
+  if (changedFiles.length === 0) {
+    console.log('No changed files found');
+    return LabelAction.NONE;
+  }
+
+  // Get effective owners using last-match-wins semantics
+  const effective = getEffectiveOwners(changedFiles, codeownersPatterns);
+  const componentCodeowners = effective.users;
+
+  console.log(`Component-specific codeowners: ${Array.from(componentCodeowners).join(', ') || '(none)'}`);
+
+  // Get current labels
+  const { data: currentLabels } = await github.rest.issues.listLabelsOnIssue({
+    owner, repo, issue_number: pr_number
+  });
+  const hasLabel = currentLabels.some(label => label.name === labelName);
+
+  if (componentCodeowners.size === 0) {
+    console.log('No component-specific codeowners found');
+    return hasLabel ? LabelAction.REMOVE : LabelAction.NONE;
+  }
+
+  // Get all reviews and find latest per user
+  const reviews = await github.paginate(
+    github.rest.pulls.listReviews,
+    { owner, repo, pull_number: pr_number }
+  );
+
+  const latestReviewByUser = new Map();
+  for (const review of reviews) {
+    if (!review.user || review.user.type === 'Bot' || review.state === 'COMMENTED') continue;
+    latestReviewByUser.set(review.user.login, review);
+  }
+
+  // Check if any component-specific codeowner has an active approval
+  let hasCodeownerApproval = false;
+  for (const [login, review] of latestReviewByUser) {
+    if (review.state === 'APPROVED' && componentCodeowners.has(login)) {
+      console.log(`Codeowner '${login}' has approved`);
+      hasCodeownerApproval = true;
+      break;
+    }
+  }
+
+  if (hasCodeownerApproval && !hasLabel) return LabelAction.ADD;
+  if (!hasCodeownerApproval && hasLabel) return LabelAction.REMOVE;
+
+  console.log(`Label already ${hasLabel ? 'present' : 'absent'}, no change needed`);
+  return LabelAction.NONE;
+}
+
+module.exports = {
+  globToRegex,
+  parseCodeowners,
+  fetchCodeowners,
+  loadCodeowners,
+  classifyOwners,
+  getEffectiveOwners,
+  LabelAction,
+  determineLabelAction
+};

.github/scripts/detect-tags.js

@@ -0,0 +1,66 @@
+/**
+ * Shared tag detection from changed file paths.
+ * Used by pr-title-check and auto-label-pr workflows.
+ */
+
+const COMPONENT_REGEX = /^esphome\/components\/([^\/]+)\//;
+
+/**
+ * Detect component names from changed files.
+ * @param {string[]} changedFiles - List of changed file paths
+ * @returns {Set<string>} Set of component names
+ */
+function detectComponents(changedFiles) {
+  const components = new Set();
+  for (const file of changedFiles) {
+    const match = file.match(COMPONENT_REGEX);
+    if (match) {
+      components.add(match[1]);
+    }
+  }
+  return components;
+}
+
+/**
+ * Detect if core files were changed.
+ * Core files are in esphome/core/ or top-level esphome/ directory.
+ * @param {string[]} changedFiles - List of changed file paths
+ * @returns {boolean}
+ */
+function hasCoreChanges(changedFiles) {
+  return changedFiles.some(file =>
+    file.startsWith('esphome/core/') ||
+    (file.startsWith('esphome/') && file.split('/').length === 2)
+  );
+}
+
+/**
+ * Detect if dashboard files were changed.
+ * @param {string[]} changedFiles - List of changed file paths
+ * @returns {boolean}
+ */
+function hasDashboardChanges(changedFiles) {
+  return changedFiles.some(file =>
+    file.startsWith('esphome/dashboard/') ||
+    file.startsWith('esphome/components/dashboard_import/')
+  );
+}
+
+/**
+ * Detect if GitHub Actions files were changed.
+ * @param {string[]} changedFiles - List of changed file paths
+ * @returns {boolean}
+ */
+function hasGitHubActionsChanges(changedFiles) {
+  return changedFiles.some(file =>
+    file.startsWith('.github/workflows/')
+  );
+}
+
+module.exports = {
+  COMPONENT_REGEX,
+  detectComponents,
+  hasCoreChanges,
+  hasDashboardChanges,
+  hasGitHubActionsChanges,
+};

.github/workflows/auto-label-pr.yml

@@ -12,6 +12,7 @@ permissions:
 
 env:
   SMALL_PR_THRESHOLD: 30
+  MEDIUM_PR_THRESHOLD: 100
   MAX_LABELS: 15
   TOO_BIG_THRESHOLD: 1000
   COMPONENT_LABEL_THRESHOLD: 10

.github/workflows/ci-api-proto.yml

@@ -62,7 +62,7 @@ jobs:
         run: git diff
       - if: failure()
         name: Archive artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: generated-proto-files
           path: |

.github/workflows/ci-docker.yml

@@ -49,7 +49,7 @@ jobs:
         with:
           python-version: "3.11"
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Set TAG
         run: |

.github/workflows/ci.yml

@@ -686,7 +686,7 @@ jobs:
       ram_usage: ${{ steps.extract.outputs.ram_usage }}
       flash_usage: ${{ steps.extract.outputs.flash_usage }}
       cache_hit: ${{ steps.cache-memory-analysis.outputs.cache-hit }}
-      skip: ${{ steps.check-script.outputs.skip }}
+      skip: ${{ steps.check-script.outputs.skip || steps.check-tests.outputs.skip }}
     steps:
       - name: Check out target branch
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -705,10 +705,39 @@ jobs:
             echo "::warning::ci_memory_impact_extract.py not found on target branch, skipping memory impact analysis"
           fi
 
-      # All remaining steps only run if script exists
+      # Check if test files exist on the target branch for the requested
+      # components and platform. When a PR adds new test files for a platform,
+      # the target branch won't have them yet, so skip instead of failing.
+      # This check must be done here (not in determine-jobs.py) because
+      # determine-jobs runs on the PR branch and cannot see what the target
+      # branch has.
+      - name: Check for test files on target branch
+        id: check-tests
+        if: steps.check-script.outputs.skip != 'true'
+        run: |
+          components='${{ toJSON(fromJSON(needs.determine-jobs.outputs.memory_impact).components) }}'
+          platform="${{ fromJSON(needs.determine-jobs.outputs.memory_impact).platform }}"
+          found=false
+          for component in $(echo "$components" | jq -r '.[]'); do
+            # Check for test files matching the platform (test.platform.yaml or test-*.platform.yaml)
+            for f in tests/components/${component}/test*.${platform}.yaml; do
+              if [ -f "$f" ]; then
+                found=true
+                break 2
+              fi
+            done
+          done
+          if [ "$found" = false ]; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "::warning::No test files found on target branch for platform ${platform}, skipping memory impact analysis"
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+
+      # All remaining steps only run if script and tests exist
       - name: Generate cache key
         id: cache-key
-        if: steps.check-script.outputs.skip != 'true'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true'
         run: |
           # Get the commit SHA of the target branch
           target_sha=$(git rev-parse HEAD)
@@ -735,14 +764,14 @@ jobs:
 
       - name: Restore cached memory analysis
         id: cache-memory-analysis
-        if: steps.check-script.outputs.skip != 'true'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true'
         uses: actions/cache/restore@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         with:
           path: memory-analysis-target.json
           key: ${{ steps.cache-key.outputs.cache-key }}
 
       - name: Cache status
-        if: steps.check-script.outputs.skip != 'true'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true'
         run: |
           if [ "${{ steps.cache-memory-analysis.outputs.cache-hit }}" == "true" ]; then
             echo "✓ Cache hit! Using cached memory analysis results."
@@ -752,21 +781,21 @@ jobs:
           fi
 
       - name: Restore Python
-        if: steps.check-script.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true'
         uses: ./.github/actions/restore-python
         with:
           python-version: ${{ env.DEFAULT_PYTHON }}
           cache-key: ${{ needs.common.outputs.cache-key }}
 
       - name: Cache platformio
-        if: steps.check-script.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true'
         uses: actions/cache/restore@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         with:
           path: ~/.platformio
           key: platformio-memory-${{ fromJSON(needs.determine-jobs.outputs.memory_impact).platform }}-${{ hashFiles('platformio.ini') }}
 
       - name: Build, compile, and analyze memory
-        if: steps.check-script.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true'
         id: build
         run: |
           . venv/bin/activate
@@ -800,7 +829,7 @@ jobs:
             --platform "$platform"
 
       - name: Save memory analysis to cache
-        if: steps.check-script.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true' && steps.build.outcome == 'success'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true' && steps.cache-memory-analysis.outputs.cache-hit != 'true' && steps.build.outcome == 'success'
         uses: actions/cache/save@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         with:
           path: memory-analysis-target.json
@@ -808,7 +837,7 @@ jobs:
 
       - name: Extract memory usage for outputs
         id: extract
-        if: steps.check-script.outputs.skip != 'true'
+        if: steps.check-script.outputs.skip != 'true' && steps.check-tests.outputs.skip != 'true'
         run: |
           if [ -f memory-analysis-target.json ]; then
             ram=$(jq -r '.ram_bytes' memory-analysis-target.json)
@@ -822,7 +851,7 @@ jobs:
           fi
 
       - name: Upload memory analysis JSON
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: memory-analysis-target
           path: memory-analysis-target.json
@@ -886,7 +915,7 @@ jobs:
             --platform "$platform"
 
       - name: Upload memory analysis JSON
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: memory-analysis-pr
           path: memory-analysis-pr.json
@@ -916,13 +945,13 @@ jobs:
           python-version: ${{ env.DEFAULT_PYTHON }}
           cache-key: ${{ needs.common.outputs.cache-key }}
       - name: Download target analysis JSON
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
         with:
           name: memory-analysis-target
           path: ./memory-analysis
         continue-on-error: true
       - name: Download PR analysis JSON
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
         with:
           name: memory-analysis-pr
           path: ./memory-analysis

.github/workflows/codeowner-approved-label-update.yml

@@ -0,0 +1,78 @@
+# Adds/removes a 'code-owner-approved' label when a component-specific
+# codeowner approves (or dismisses) a PR.
+#
+# Uses pull_request_target so that fork PRs do not require workflow approval.
+# The label is reconciled on every PR update; for review events specifically,
+# this means the label is applied on the next push after a codeowner review.
+
+name: Codeowner Approved Label
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  issues: write
+  pull-requests: read
+  contents: read
+
+jobs:
+  codeowner-approved:
+    name: Run
+    if: ${{ github.repository == 'esphome/esphome' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout base branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          sparse-checkout: |
+            .github/scripts/codeowners.js
+            CODEOWNERS
+
+      - name: Check codeowner approval and update label
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        with:
+          script: |
+            const { loadCodeowners, determineLabelAction, LabelAction } = require('./.github/scripts/codeowners.js');
+
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const pr_number = parseInt(process.env.PR_NUMBER, 10);
+            const LABEL_NAME = 'code-owner-approved';
+
+            console.log(`Processing PR #${pr_number} for codeowner approval label`);
+
+            const codeownersPatterns = loadCodeowners();
+            const action = await determineLabelAction(
+              github, owner, repo, pr_number, codeownersPatterns, LABEL_NAME
+            );
+
+            if (action === LabelAction.NONE) {
+              console.log('No label change needed');
+              return;
+            }
+
+            try {
+              if (action === LabelAction.ADD) {
+                await github.rest.issues.addLabels({
+                  owner, repo, issue_number: pr_number, labels: [LABEL_NAME]
+                });
+                console.log(`Added '${LABEL_NAME}' label`);
+              } else if (action === LabelAction.REMOVE) {
+                await github.rest.issues.removeLabel({
+                  owner, repo, issue_number: pr_number, name: LABEL_NAME
+                });
+                console.log(`Removed '${LABEL_NAME}' label`);
+              }
+            } catch (error) {
+              if (error.status === 403) {
+                console.log(`Warning: insufficient permissions to update label (expected for fork PRs)`);
+              } else if (error.status === 404) {
+                console.log(`Label '${LABEL_NAME}' not present, nothing to remove`);
+              } else {
+                throw error;
+              }
+            }

.github/workflows/codeowner-review-request.yml

@@ -24,10 +24,17 @@ jobs:
     if: ${{ github.repository == 'esphome/esphome' && !github.event.pull_request.draft }}
     runs-on: ubuntu-latest
     steps:
+      - name: Checkout base branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+
       - name: Request reviews from component codeowners
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: |
+            const { loadCodeowners, getEffectiveOwners } = require('./.github/scripts/codeowners.js');
+
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const pr_number = context.payload.pull_request.number;
@@ -38,12 +45,15 @@ jobs:
             const BOT_COMMENT_MARKER = '<!-- codeowner-review-request-bot -->';
 
             try {
-              // Get the list of changed files in this PR
-              const { data: files } = await github.rest.pulls.listFiles({
-                owner,
-                repo,
-                pull_number: pr_number
-              });
+              // Get the list of changed files in this PR (with pagination)
+              const files = await github.paginate(
+                github.rest.pulls.listFiles,
+                {
+                  owner,
+                  repo,
+                  pull_number: pr_number
+                }
+              );
 
               const changedFiles = files.map(file => file.filename);
               console.log(`Found ${changedFiles.length} changed files`);
@@ -53,32 +63,10 @@ jobs:
                 return;
               }
 
-              // Fetch CODEOWNERS file from root
-              const { data: codeownersFile } = await github.rest.repos.getContent({
-                owner,
-                repo,
-                path: 'CODEOWNERS',
-                ref: context.payload.pull_request.base.sha
-              });
-              const codeownersContent = Buffer.from(codeownersFile.content, 'base64').toString('utf8');
+              // Parse CODEOWNERS from the checked-out base branch
+              const codeownersPatterns = loadCodeowners();
 
-              // Parse CODEOWNERS file to extract all patterns and their owners
-              const codeownersLines = codeownersContent.split('\n')
-                .map(line => line.trim())
-                .filter(line => line && !line.startsWith('#'));
-
-              const codeownersPatterns = [];
-
-              // Convert CODEOWNERS pattern to regex (robust glob handling)
-              function globToRegex(pattern) {
-                // Escape regex special characters except for glob wildcards
-                let regexStr = pattern
-                  .replace(/([.+^=!:${}()|[\]\\])/g, '\\$1') // escape regex chars
-                  .replace(/\*\*/g, '.*') // globstar
-                  .replace(/\*/g, '[^/]*') // single star
-                  .replace(/\?/g, '.'); // question mark
-                return new RegExp('^' + regexStr + '$');
-              }
+              console.log(`Parsed ${codeownersPatterns.length} codeowner patterns`);
 
               // Helper function to create comment body
               function createCommentBody(reviewersList, teamsList, matchedFileCount, isSuccessful = true) {
@@ -93,50 +81,11 @@ jobs:
                 }
               }
 
-              for (const line of codeownersLines) {
-                const parts = line.split(/\s+/);
-                if (parts.length < 2) continue;
-
-                const pattern = parts[0];
-                const owners = parts.slice(1);
-
-                // Use robust glob-to-regex conversion
-                const regex = globToRegex(pattern);
-                codeownersPatterns.push({ pattern, regex, owners });
-              }
-
-              console.log(`Parsed ${codeownersPatterns.length} codeowner patterns`);
-
-              // Match changed files against CODEOWNERS patterns
-              const matchedOwners = new Set();
-              const matchedTeams = new Set();
-              const fileMatches = new Map(); // Track which files matched which patterns
-
-              for (const file of changedFiles) {
-                for (const { pattern, regex, owners } of codeownersPatterns) {
-                  if (regex.test(file)) {
-                    console.log(`File '${file}' matches pattern '${pattern}' with owners: ${owners.join(', ')}`);
-
-                    if (!fileMatches.has(file)) {
-                      fileMatches.set(file, []);
-                    }
-                    fileMatches.get(file).push({ pattern, owners });
-
-                    // Add owners to the appropriate set (remove @ prefix)
-                    for (const owner of owners) {
-                      const cleanOwner = owner.startsWith('@') ? owner.slice(1) : owner;
-                      if (cleanOwner.includes('/')) {
-                        // Team mention (org/team-name)
-                        const teamName = cleanOwner.split('/')[1];
-                        matchedTeams.add(teamName);
-                      } else {
-                        // Individual user
-                        matchedOwners.add(cleanOwner);
-                      }
-                    }
-                  }
-                }
-              }
+              // Match changed files against CODEOWNERS patterns using last-match-wins semantics
+              const effective = getEffectiveOwners(changedFiles, codeownersPatterns);
+              const matchedOwners = effective.users;
+              const matchedTeams = effective.teams;
+              const matchedFileCount = effective.matchedFileCount;
 
               if (matchedOwners.size === 0 && matchedTeams.size === 0) {
                 console.log('No codeowners found for any changed files');
@@ -170,11 +119,14 @@ jobs:
               }
 
               // Check for completed reviews to avoid re-requesting users who have already reviewed
-              const { data: reviews } = await github.rest.pulls.listReviews({
-                owner,
-                repo,
-                pull_number: pr_number
-              });
+              const reviews = await github.paginate(
+                github.rest.pulls.listReviews,
+                {
+                  owner,
+                  repo,
+                  pull_number: pr_number
+                }
+              );
 
               const reviewedUsers = new Set();
               reviews.forEach(review => {
@@ -247,7 +199,7 @@ jobs:
               }
 
               const totalReviewers = reviewersList.length + teamsList.length;
-              console.log(`Requesting reviews from ${reviewersList.length} users and ${teamsList.length} teams for ${fileMatches.size} matched files`);
+              console.log(`Requesting reviews from ${reviewersList.length} users and ${teamsList.length} teams for ${matchedFileCount} matched files`);
 
               // Request reviews
               try {
@@ -279,7 +231,7 @@ jobs:
 
                 // Only add a comment if there are new codeowners to mention (not previously pinged)
                 if (reviewersList.length > 0 || teamsList.length > 0) {
-                  const commentBody = createCommentBody(reviewersList, teamsList, fileMatches.size, true);
+                  const commentBody = createCommentBody(reviewersList, teamsList, matchedFileCount, true);
 
                   await github.rest.issues.createComment({
                     owner,
@@ -297,7 +249,7 @@ jobs:
 
                   // Only try to add a comment if there are new codeowners to mention
                   if (reviewersList.length > 0 || teamsList.length > 0) {
-                    const commentBody = createCommentBody(reviewersList, teamsList, fileMatches.size, false);
+                    const commentBody = createCommentBody(reviewersList, teamsList, matchedFileCount, false);
 
                     try {
                       await github.rest.issues.createComment({

.github/workflows/codeql.yml

@@ -58,7 +58,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@45cbd0c69e560cd9e7cd7f8c32362050c9b7ded2 # v4.32.2
+        uses: github/codeql-action/init@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
@@ -86,6 +86,6 @@ jobs:
           exit 1
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@45cbd0c69e560cd9e7cd7f8c32362050c9b7ded2 # v4.32.2
+        uses: github/codeql-action/analyze@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6
         with:
           category: "/language:${{matrix.language}}"

.github/workflows/pr-title-check.yml

@@ -0,0 +1,81 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            const {
+              detectComponents,
+              hasCoreChanges,
+              hasDashboardChanges,
+              hasGitHubActionsChanges,
+            } = require('./.github/scripts/detect-tags.js');
+
+            const title = context.payload.pull_request.title;
+            const author = context.payload.pull_request.user.login;
+
+            // Skip bot PRs (e.g. dependabot) - they have their own title format
+            if (author === 'dependabot[bot]') {
+              return;
+            }
+
+            // Block titles starting with "word:" or "word(scope):" patterns
+            const commitStylePattern = /^\w+(\(.*?\))?[!]?\s*:/;
+            if (commitStylePattern.test(title)) {
+              core.setFailed(
+                `PR title should not start with a "prefix:" style format.\n` +
+                `Please use the format: [component] Brief description\n`
+              );
+              return;
+            }
+
+            // Get changed files to detect tags
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+            });
+            const filenames = files.map(f => f.filename);
+
+            // Detect tags from changed files using shared logic
+            const tags = new Set();
+
+            for (const comp of detectComponents(filenames)) {
+              tags.add(comp);
+            }
+            if (hasCoreChanges(filenames)) tags.add('core');
+            if (hasDashboardChanges(filenames)) tags.add('dashboard');
+            if (hasGitHubActionsChanges(filenames)) tags.add('ci');
+
+            if (tags.size === 0) {
+              return;
+            }
+
+            // Check title starts with [tag] prefix
+            const bracketPattern = /^\[\w+\]/;
+            if (!bracketPattern.test(title)) {
+              const suggestion = [...tags].map(c => `[${c}]`).join('');
+              // Skip if the suggested prefix would be too long for a readable title
+              if (suggestion.length > 40) {
+                return;
+              }
+              core.setFailed(
+                `PR modifies: ${[...tags].join(', ')}\n` +
+                `Title must start with a [tag] prefix.\n` +
+                `Suggested: ${suggestion} <description>`
+              );
+            }

.github/workflows/release.yml

@@ -99,15 +99,15 @@ jobs:
           python-version: "3.11"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Log in to docker hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           username: ${{ secrets.DOCKER_USER }}
           password: ${{ secrets.DOCKER_PASSWORD }}
       - name: Log in to the GitHub container registry
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -138,7 +138,7 @@ jobs:
       #     version: ${{ needs.init.outputs.tag }}
 
       - name: Upload digests
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: digests-${{ matrix.platform.arch }}
           path: /tmp/digests
@@ -171,24 +171,24 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Download digests
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
         with:
           pattern: digests-*
           path: /tmp/digests
           merge-multiple: true
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Log in to docker hub
         if: matrix.registry == 'dockerhub'
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           username: ${{ secrets.DOCKER_USER }}
           password: ${{ secrets.DOCKER_PASSWORD }}
       - name: Log in to the GitHub container registry
         if: matrix.registry == 'ghcr'
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

.github/workflows/stale.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Stale
-        uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
+        uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
         with:
           debug-only: ${{ github.ref != 'refs/heads/dev' }} # Dry-run when not run on dev branch
           remove-stale-when-updated: true

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ ci:
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.15.0
+    rev: v0.15.5
     hooks:
       # Run the linter.
       - id: ruff
@@ -37,7 +37,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.20.0
+    rev: v3.21.2
     hooks:
       - id: pyupgrade
         args: [--py311-plus]

CODEOWNERS

@@ -54,6 +54,8 @@ esphome/components/atm90e32/* @circuitsetup @descipher
 esphome/components/audio/* @kahrendt
 esphome/components/audio_adc/* @kbx81
 esphome/components/audio_dac/* @kbx81
+esphome/components/audio_file/* @kahrendt
+esphome/components/audio_file/media_source/* @kahrendt
 esphome/components/axs15231/* @clydebarrow
 esphome/components/b_parasite/* @rbaron
 esphome/components/ballu/* @bazuchan
@@ -130,6 +132,7 @@ esphome/components/dashboard_import/* @esphome/core
 esphome/components/datetime/* @jesserockz @rfdarter
 esphome/components/debug/* @esphome/core
 esphome/components/delonghi/* @grob6000
+esphome/components/dew_point/* @CFlix
 esphome/components/dfplayer/* @glmnet
 esphome/components/dfrobot_sen0395/* @niklasweber
 esphome/components/dht/* @OttoWinter
@@ -213,6 +216,7 @@ esphome/components/hbridge/light/* @DotNetDann
 esphome/components/hbridge/switch/* @dwmw2
 esphome/components/hc8/* @omartijn
 esphome/components/hdc2010/* @optimusprimespace @ssieb
+esphome/components/hdc302x/* @joshuasing
 esphome/components/he60r/* @clydebarrow
 esphome/components/heatpumpir/* @rob-deutsch
 esphome/components/hitachi_ac424/* @sourabhjaiswal
@@ -315,6 +319,7 @@ esphome/components/mcp9808/* @k7hpn
 esphome/components/md5/* @esphome/core
 esphome/components/mdns/* @esphome/core
 esphome/components/media_player/* @jesserockz
+esphome/components/media_source/* @kahrendt
 esphome/components/micro_wake_word/* @jesserockz @kahrendt
 esphome/components/micronova/* @edenhaus @jorre05
 esphome/components/microphone/* @jesserockz @kahrendt
@@ -406,11 +411,13 @@ esphome/components/restart/* @esphome/core
 esphome/components/rf_bridge/* @jesserockz
 esphome/components/rgbct/* @jesserockz
 esphome/components/rp2040/* @jesserockz
+esphome/components/rp2040_ble/* @bdraco
 esphome/components/rp2040_pio_led_strip/* @Papa-DMan
 esphome/components/rp2040_pwm/* @jesserockz
 esphome/components/rpi_dpi_rgb/* @clydebarrow
 esphome/components/rtl87xx/* @kuba2k2
-esphome/components/rtttl/* @glmnet
+esphome/components/rtttl/* @glmnet @ximex
+esphome/components/runtime_image/* @clydebarrow @guillempages @kahrendt
 esphome/components/runtime_stats/* @bdraco
 esphome/components/rx8130/* @beormund
 esphome/components/safe_mode/* @jsuanet @kbx81 @paulmonigatti
@@ -427,8 +434,10 @@ esphome/components/select/* @esphome/core
 esphome/components/sen0321/* @notjj
 esphome/components/sen21231/* @shreyaskarnik
 esphome/components/sen5x/* @martgras
+esphome/components/sen6x/* @martgras @mebner86 @mikelawrence @tuct
 esphome/components/sensirion_common/* @martgras
 esphome/components/sensor/* @esphome/core
+esphome/components/serial_proxy/* @kbx81
 esphome/components/sfa30/* @ghsensdev
 esphome/components/sgp40/* @SenexCrenshaw
 esphome/components/sgp4x/* @martgras @SenexCrenshaw
@@ -451,6 +460,7 @@ esphome/components/sonoff_d1/* @anatoly-savchenkov
 esphome/components/sound_level/* @kahrendt
 esphome/components/speaker/* @jesserockz @kahrendt
 esphome/components/speaker/media_player/* @kahrendt @synesthesiam
+esphome/components/speaker_source/* @kahrendt
 esphome/components/spi/* @clydebarrow @esphome/core
 esphome/components/spi_device/* @clydebarrow
 esphome/components/spi_led_strip/* @clydebarrow
@@ -581,6 +591,7 @@ esphome/components/xl9535/* @mreditor97
 esphome/components/xpt2046/touchscreen/* @nielsnl68 @numo68
 esphome/components/xxtea/* @clydebarrow
 esphome/components/zephyr/* @tomaszduda23
+esphome/components/zephyr_mcumgr/ota/* @tomaszduda23
 esphome/components/zhlt01/* @cfeenstra1024
 esphome/components/zigbee/* @tomaszduda23
 esphome/components/zio_ultrasonic/* @kahrendt

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = ESPHome
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2026.2.4
+PROJECT_NUMBER         = 2026.3.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

esphome/__main__.py

@@ -1,6 +1,7 @@
 # PYTHON_ARGCOMPLETE_OK
 import argparse
 from collections.abc import Callable
+from contextlib import suppress
 from datetime import datetime
 import functools
 import getpass
@@ -9,6 +10,8 @@ import logging
 import os
 from pathlib import Path
 import re
+import shutil
+import subprocess
 import sys
 import time
 from typing import Protocol
@@ -23,6 +26,7 @@ import esphome.codegen as cg
 from esphome.config import iter_component_configs, read_config, strip_default_ids
 from esphome.const import (
     ALLOWED_NAME_CHARS,
+    ARGUMENT_HELP_DEVICE,
     CONF_API,
     CONF_BAUD_RATE,
     CONF_BROKER,
@@ -43,7 +47,9 @@ from esphome.const import (
     CONF_SUBSTITUTIONS,
     CONF_TOPIC,
     ENV_NOGITIGNORE,
+    KEY_CORE,
     KEY_NATIVE_IDF,
+    KEY_TARGET_PLATFORM,
     PLATFORM_ESP32,
     PLATFORM_ESP8266,
     PLATFORM_RP2040,
@@ -55,7 +61,11 @@ from esphome.helpers import get_bool_env, indent, is_ip_address
 from esphome.log import AnsiFore, color, setup_log
 from esphome.types import ConfigType
 from esphome.util import (
+    PICOTOOL_PACKAGE,
+    detect_rp2040_bootsel,
+    get_picotool_path,
     get_serial_ports,
+    is_picotool_usb_permission_error,
     list_yaml_files,
     run_external_command,
     run_external_process,
@@ -64,9 +74,26 @@ from esphome.util import (
 
 _LOGGER = logging.getLogger(__name__)
 
+ESPHOME_COMMAND = [sys.executable, "-m", "esphome"]
+
 # Maximum buffer size for serial log reading to prevent unbounded memory growth
 SERIAL_BUFFER_MAX_SIZE = 65536
 
+_RP2040_BOOTSEL_INSTRUCTIONS = (
+    "To enter BOOTSEL mode:\n"
+    "  1. Unplug the device\n"
+    "  2. Hold the BOOT/BOOTSEL button\n"
+    "  3. Plug in the USB cable while holding the button\n"
+    "  4. Release the button - the device should appear as a USB drive (RPI-RP2)\n"
+    "Then run the upload command again."
+)
+
+_RP2040_UDEV_HINT = (
+    "You may need to add a udev rule for RP2040 devices. "
+    "See: https://github.com/raspberrypi/picotool"
+    "/blob/master/udev/60-picotool.rules"
+)
+
 # Special non-component keys that appear in configs
 _NON_COMPONENT_KEYS = frozenset(
     {
@@ -162,6 +189,7 @@ class PortType(StrEnum):
     NETWORK = "NETWORK"
     MQTT = "MQTT"
     MQTTIP = "MQTTIP"
+    BOOTSEL = "BOOTSEL"
 
 
 # Magic MQTT port types that require special handling
@@ -240,6 +268,19 @@ def choose_upload_log_host(
         (f"{port.path} ({port.description})", port.path) for port in get_serial_ports()
     ]
 
+    # Add RP2040 BOOTSEL device option when uploading
+    bootsel_permission_error = False
+    if (
+        purpose == Purpose.UPLOADING
+        and CORE.data.get(KEY_CORE, {}).get(KEY_TARGET_PLATFORM) == PLATFORM_RP2040
+        and (picotool := _find_picotool()) is not None
+    ):
+        bootsel = detect_rp2040_bootsel(picotool)
+        if bootsel.device_count > 0:
+            options.append(("RP2040 BOOTSEL (via picotool)", "BOOTSEL"))
+        elif bootsel.permission_error:
+            bootsel_permission_error = True
+
     if purpose == Purpose.LOGGING:
         if has_mqtt_logging():
             mqtt_config = CORE.config[CONF_MQTT]
@@ -257,6 +298,25 @@ def choose_upload_log_host(
         if has_mqtt_ip_lookup():
             options.append(("Over The Air (MQTT IP lookup)", "MQTTIP"))
 
+    # Show helpful BOOTSEL instructions for RP2040 when no BOOTSEL device is found
+    if (
+        purpose == Purpose.UPLOADING
+        and CORE.data.get(KEY_CORE, {}).get(KEY_TARGET_PLATFORM) == PLATFORM_RP2040
+        and not any(get_port_type(opt[1]) == PortType.BOOTSEL for opt in options)
+    ):
+        if bootsel_permission_error:
+            _LOGGER.warning(
+                "An RP2040 device in BOOTSEL mode was detected but could "
+                "not be accessed due to USB permissions."
+            )
+            if sys.platform.startswith("linux"):
+                _LOGGER.warning(_RP2040_UDEV_HINT)
+        if not options:
+            raise EsphomeError(
+                f"No RP2040 device found. {_RP2040_BOOTSEL_INSTRUCTIONS}"
+            )
+        _LOGGER.info("Tip: %s", _RP2040_BOOTSEL_INSTRUCTIONS)
+
     if check_default is not None and check_default in [opt[1] for opt in options]:
         return [check_default]
     return [choose_prompt(options, purpose=purpose)]
@@ -403,10 +463,13 @@ def get_port_type(port: str) -> PortType:
 
     Returns:
         PortType.SERIAL for serial ports (/dev/ttyUSB0, COM1, etc.)
+        PortType.BOOTSEL for RP2040 BOOTSEL upload via picotool
         PortType.MQTT for MQTT logging
         PortType.MQTTIP for MQTT IP lookup
         PortType.NETWORK for IP addresses, hostnames, or mDNS names
     """
+    if port == "BOOTSEL":
+        return PortType.BOOTSEL
     if port.startswith("/") or port.startswith("COM"):
         return PortType.SERIAL
     if port == "MQTT":
@@ -431,6 +494,14 @@ def run_miniterm(config: ConfigType, port: str, args) -> int:
         return 1
     _LOGGER.info("Starting log output from %s with baud rate %s", port, baud_rate)
 
+    process_stacktrace = None
+
+    try:
+        module = importlib.import_module("esphome.components." + CORE.target_platform)
+        process_stacktrace = getattr(module, "process_stacktrace")
+    except AttributeError:
+        pass
+
     backtrace_state = False
     ser = serial.Serial()
     ser.baudrate = baud_rate
@@ -472,9 +543,14 @@ def run_miniterm(config: ConfigType, port: str, args) -> int:
                             )
                             safe_print(parser.parse_line(line, time_str))
 
-                            backtrace_state = platformio_api.process_stacktrace(
-                                config, line, backtrace_state=backtrace_state
-                            )
+                            if process_stacktrace:
+                                backtrace_state = process_stacktrace(
+                                    config, line, backtrace_state
+                                )
+                            else:
+                                backtrace_state = platformio_api.process_stacktrace(
+                                    config, line, backtrace_state=backtrace_state
+                                )
                     except serial.SerialException:
                         _LOGGER.error("Serial port closed!")
                         return 0
@@ -614,6 +690,47 @@ def _check_and_emit_build_info() -> None:
     )
 
 
+def _get_configured_xtal_freq() -> int | None:
+    """Read the configured crystal frequency from the sdkconfig file."""
+    sdkconfig_path = CORE.relative_build_path(f"sdkconfig.{CORE.name}")
+    if not sdkconfig_path.is_file():
+        return None
+    with suppress(OSError, ValueError):
+        content = sdkconfig_path.read_text()
+        for line in content.splitlines():
+            if line.startswith("CONFIG_XTAL_FREQ="):
+                return int(line.split("=", 1)[1])
+    return None
+
+
+def _make_crystal_freq_callback(
+    configured_freq: int,
+) -> Callable[[str], str | None]:
+    """Create a callback that checks esptool crystal frequency output."""
+    crystal_re = re.compile(r"Crystal frequency:\s+(\d+)\s*MHz")
+
+    def check_crystal_line(line: str) -> str | None:
+        if not (match := crystal_re.search(line)):
+            return None
+        detected = int(match.group(1))
+        if detected == configured_freq:
+            return None
+        return (
+            f"\n\033[33mWARNING: Crystal frequency mismatch! "
+            f"Device reports {detected}MHz but firmware is configured "
+            f"for {configured_freq}MHz.\n"
+            f"UART logging and other clock-dependent features will not "
+            f"work correctly.\n"
+            f"Set the correct crystal frequency with sdkconfig_options:\n"
+            f"  esp32:\n"
+            f"    framework:\n"
+            f"      sdkconfig_options:\n"
+            f"        CONFIG_XTAL_FREQ_{detected}: 'y'\033[0m\n\n"
+        )
+
+    return check_crystal_line
+
+
 def upload_using_esptool(
     config: ConfigType, port: str, file: str, speed: int
 ) -> str | int:
@@ -642,6 +759,14 @@ def upload_using_esptool(
 
         mcu = get_esp32_variant().lower()
 
+    line_callbacks: list[Callable[[str], str | None]] = []
+    if (
+        CORE.is_esp32
+        and file is None
+        and (configured_freq := _get_configured_xtal_freq()) is not None
+    ):
+        line_callbacks.append(_make_crystal_freq_callback(configured_freq))
+
     def run_esptool(baud_rate):
         cmd = [
             "esptool",
@@ -666,9 +791,13 @@ def upload_using_esptool(
         if os.environ.get("ESPHOME_USE_SUBPROCESS") is None:
             import esptool
 
-            return run_external_command(esptool.main, *cmd)  # pylint: disable=no-member
+            return run_external_command(
+                esptool.main,  # pylint: disable=no-member
+                *cmd,
+                line_callbacks=line_callbacks,
+            )
 
-        return run_external_process(*cmd)
+        return run_external_process(*cmd, line_callbacks=line_callbacks)
 
     rc = run_esptool(first_baudrate)
     if rc == 0 or first_baudrate == 115200:
@@ -681,15 +810,140 @@ def upload_using_esptool(
     return run_esptool(115200)
 
 
-def upload_using_platformio(config: ConfigType, port: str):
+def upload_using_platformio(config: ConfigType, port: str) -> int:
     from esphome import platformio_api
 
+    # RP2040 platform-raspberrypi build recipe expects firmware.bin.signed for
+    # the upload target, but 'nobuild' skips the build phase that creates it.
+    # Create it here so the upload doesn't fail.
+    if CORE.data.get(KEY_CORE, {}).get(KEY_TARGET_PLATFORM) == PLATFORM_RP2040:
+        idedata = platformio_api.get_idedata(config)
+        build_dir = Path(idedata.firmware_elf_path).parent
+        firmware_bin = build_dir / "firmware.bin"
+        signed_bin = build_dir / "firmware.bin.signed"
+        if firmware_bin.is_file() and not signed_bin.is_file():
+            shutil.copy2(firmware_bin, signed_bin)
+
     upload_args = ["-t", "upload", "-t", "nobuild"]
     if port is not None:
         upload_args += ["--upload-port", port]
     return platformio_api.run_platformio_cli_run(config, CORE.verbose, *upload_args)
 
 
+def _find_picotool() -> Path | None:
+    """Find the picotool binary from PlatformIO packages."""
+    from esphome import platformio_api
+
+    try:
+        idedata = platformio_api.get_idedata(CORE.config)
+    except Exception:  # noqa: BLE001  # pylint: disable=broad-except
+        return None
+    return get_picotool_path(idedata.cc_path)
+
+
+def upload_using_picotool(config: ConfigType) -> int:
+    """Upload firmware to RP2040 in BOOTSEL mode using picotool.
+
+    Uses picotool to load the ELF firmware directly via USB, avoiding
+    the mass storage copy approach that causes "disk not ejected properly"
+    warnings on macOS.
+    """
+    from esphome import platformio_api
+
+    idedata = platformio_api.get_idedata(config)
+    firmware_elf = Path(idedata.firmware_elf_path)
+
+    if not firmware_elf.is_file():
+        _LOGGER.error(
+            "Firmware ELF file not found at %s. "
+            "Make sure the project has been compiled first.",
+            firmware_elf,
+        )
+        return 1
+
+    picotool = get_picotool_path(idedata.cc_path)
+    if picotool is None:
+        _LOGGER.error(
+            "picotool not found. Ensure the RP2040 PlatformIO platform "
+            "is installed (%s).",
+            PICOTOOL_PACKAGE,
+        )
+        return 1
+
+    _LOGGER.info("Uploading firmware to RP2040 via picotool...")
+    try:
+        # Don't capture stdout — let picotool write directly to the terminal
+        # so progress bars display in real-time with \r updates.
+        # Capture stderr only so we can detect permission errors.
+        result = subprocess.run(
+            [str(picotool), "load", "-v", "-x", str(firmware_elf)],
+            stderr=subprocess.PIPE,
+            timeout=60,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        _LOGGER.error("picotool upload timed out after 60 seconds.")
+        return 1
+    except OSError as err:
+        _LOGGER.error("Failed to run picotool: %s", err)
+        return 1
+
+    if result.returncode != 0:
+        stderr = result.stderr.decode("utf-8", errors="replace").strip()
+        if stderr:
+            for line in stderr.splitlines():
+                safe_print(line)
+        if is_picotool_usb_permission_error(stderr):
+            msg = "Permission denied accessing USB device."
+            if sys.platform.startswith("linux"):
+                msg += f" {_RP2040_UDEV_HINT}"
+            _LOGGER.error(msg)
+        else:
+            _LOGGER.error("picotool upload failed (exit code %d).", result.returncode)
+        return 1
+
+    return 0
+
+
+def _wait_for_serial_port(
+    port: str | None = None,
+    timeout: float = 30.0,
+    known_ports: set[str] | None = None,
+) -> None:
+    """Wait for a serial port to appear, e.g. after a device reboot.
+
+    USB-CDC devices disappear briefly after flashing while the device
+    reboots and re-enumerates on the USB bus.
+
+    If port is given, wait for that specific path. If known_ports is
+    given, wait for a new port that wasn't in the set. Otherwise wait
+    for any serial port to appear.
+    """
+
+    def _port_found() -> bool:
+        if port is not None:
+            if os.name == "posix":
+                return os.path.exists(port)
+            return any(p.path == port for p in get_serial_ports())
+        ports = get_serial_ports()
+        if known_ports is not None:
+            return any(p.path not in known_ports for p in ports)
+        return bool(ports)
+
+    if _port_found():
+        return
+    if port is not None:
+        _LOGGER.info("Waiting for %s to come online...", port)
+    else:
+        _LOGGER.info("Waiting for device to reboot...")
+    start = time.monotonic()
+    while time.monotonic() - start < timeout:
+        time.sleep(0.05)
+        if _port_found():
+            time.sleep(0.05)
+            return
+
+
 def check_permissions(port: str):
     if os.name == "posix" and get_port_type(port) == PortType.SERIAL:
         # Check if we can open selected serial port
@@ -719,7 +973,15 @@ def upload_program(
     except AttributeError:
         pass
 
-    if get_port_type(host) == PortType.SERIAL:
+    port_type = get_port_type(host)
+
+    if port_type == PortType.BOOTSEL:
+        exit_code = upload_using_picotool(config)
+        # Return None for device - BOOTSEL can't be used for logging,
+        # so command_run will show the interactive chooser for log source
+        return exit_code, None
+
+    if port_type == PortType.SERIAL:
         check_permissions(host)
 
         exit_code = 1
@@ -773,6 +1035,7 @@ def show_logs(config: ConfigType, args: ArgsProtocol, devices: list[str]) -> int
     port_type = get_port_type(port)
 
     if port_type == PortType.SERIAL:
+        _wait_for_serial_port(port)
         check_permissions(port)
         return run_miniterm(config, port, args)
 
@@ -911,6 +1174,9 @@ def command_run(args: ArgsProtocol, config: ConfigType) -> int | None:
         purpose=Purpose.UPLOADING,
     )
 
+    # Snapshot current serial ports before upload so we can detect new ones
+    pre_upload_ports = {p.path for p in get_serial_ports()}
+
     exit_code, successful_device = upload_program(config, args, devices)
     if exit_code == 0:
         _LOGGER.info("Successfully uploaded program.")
@@ -921,6 +1187,19 @@ def command_run(args: ArgsProtocol, config: ConfigType) -> int | None:
     if args.no_logs:
         return 0
 
+    # After BOOTSEL upload, wait for a new serial port to appear
+    # so it shows up in the log chooser
+    if (
+        successful_device is None
+        and CORE.data.get(KEY_CORE, {}).get(KEY_TARGET_PLATFORM) == PLATFORM_RP2040
+    ):
+        _wait_for_serial_port(known_ports=pre_upload_ports)
+        # If exactly one new serial port appeared, use it directly
+        serial_ports = get_serial_ports()
+        new_ports = [p for p in serial_ports if p.path not in pre_upload_ports]
+        if len(new_ports) == 1:
+            successful_device = new_ports[0].path
+
     # For logs, prefer the device we successfully uploaded to
     devices = choose_upload_log_host(
         default=successful_device,
@@ -1030,9 +1309,8 @@ def command_update_all(args: ArgsProtocol) -> int | None:
     files = list_yaml_files(args.configuration)
 
     def build_command(f):
-        if CORE.dashboard:
-            return ["esphome", "--dashboard", "run", f, "--no-logs", "--device", "OTA"]
-        return ["esphome", "run", f, "--no-logs", "--device", "OTA"]
+        dashboard = ["--dashboard"] if CORE.dashboard else []
+        return [*ESPHOME_COMMAND, *dashboard, "run", f, "--no-logs", "--device", "OTA"]
 
     return run_multiple_configs(files, build_command)
 
@@ -1181,7 +1459,7 @@ def command_rename(args: ArgsProtocol, config: ConfigType) -> int | None:
 
     new_path.write_text(new_raw, encoding="utf-8")
 
-    rc = run_external_process("esphome", "config", str(new_path))
+    rc = run_external_process(*ESPHOME_COMMAND, "config", str(new_path))
     if rc != 0:
         print(color(AnsiFore.BOLD_RED, "Rename failed. Reverting changes."))
         new_path.unlink()
@@ -1199,7 +1477,7 @@ def command_rename(args: ArgsProtocol, config: ConfigType) -> int | None:
         cli_args.insert(0, "--dashboard")
 
     try:
-        rc = run_external_process("esphome", *cli_args)
+        rc = run_external_process(*ESPHOME_COMMAND, *cli_args)
     except KeyboardInterrupt:
         rc = 1
     if rc != 0:
@@ -1354,7 +1632,7 @@ def parse_args(argv):
     parser_upload.add_argument(
         "--device",
         action="append",
-        help="Manually specify the serial port/address to use, for example /dev/ttyUSB0. Can be specified multiple times for fallback addresses.",
+        help=ARGUMENT_HELP_DEVICE,
     )
     parser_upload.add_argument(
         "--upload_speed",
@@ -1377,7 +1655,7 @@ def parse_args(argv):
     parser_logs.add_argument(
         "--device",
         action="append",
-        help="Manually specify the serial port/address to use, for example /dev/ttyUSB0. Can be specified multiple times for fallback addresses.",
+        help=ARGUMENT_HELP_DEVICE,
     )
     parser_logs.add_argument(
         "--reset",
@@ -1407,7 +1685,7 @@ def parse_args(argv):
     parser_run.add_argument(
         "--device",
         action="append",
-        help="Manually specify the serial port/address to use, for example /dev/ttyUSB0. Can be specified multiple times for fallback addresses.",
+        help=ARGUMENT_HELP_DEVICE,
     )
     parser_run.add_argument(
         "--upload_speed",
@@ -1596,7 +1874,7 @@ def run_esphome(argv):
         # argv[0] is the program path, skip it since we prefix with "esphome"
         def build_command(f):
             return (
-                ["esphome"]
+                [*ESPHOME_COMMAND]
                 + [arg for arg in argv[1:] if arg not in args.configuration]
                 + [str(f)]
             )

esphome/analyze_memory/const.py

@@ -256,7 +256,7 @@ SYMBOL_PATTERNS = {
     "ipv6_stack": ["nd6_", "ip6_", "mld6_", "icmp6_", "icmp6_input"],
     # Order matters! More specific categories must come before general ones.
     # mdns must come before bluetooth to avoid "_mdns_disable_pcb" matching "ble_" pattern
-    "mdns_lib": ["mdns"],
+    "mdns_lib": ["mdns", "packet$"],
     # memory_mgmt must come before wifi_stack to catch mmu_hal_* symbols
     "memory_mgmt": [
         "mem_",
@@ -794,7 +794,6 @@ SYMBOL_PATTERNS = {
         "s_dp",
         "s_ni",
         "s_reg_dump",
-        "packet$",
         "d_mult_table",
         "K",
         "fcstab",

esphome/automation.py

@@ -1,3 +1,5 @@
+import logging
+
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
@@ -57,8 +59,42 @@ def maybe_conf(conf, *validators):
     return validate
 
 
-def register_action(name: str, action_type: MockObjClass, schema: cv.Schema):
-    return ACTION_REGISTRY.register(name, action_type, schema)
+_LOGGER = logging.getLogger(__name__)
+
+
+def register_action(
+    name: str,
+    action_type: MockObjClass,
+    schema: cv.Schema,
+    *,
+    synchronous: bool | None = None,
+):
+    """Register an action type.
+
+    All callers must pass ``synchronous`` explicitly.
+
+    ``synchronous=True`` — the action never defers ``play_next_()`` to a
+    later point (callback, timer, or ``loop()``).  Trigger arguments are
+    only used during the initial call, so string args can use non-owning
+    StringRef for zero-copy access.
+
+    ``synchronous=False`` — the action defers ``play_next_()`` via a
+    callback, timer, or ``Component::loop()``.  Trigger arguments must
+    outlive the initial call, so string args use owning std::string to
+    prevent dangling references.
+    """
+    if synchronous is None:
+        _LOGGER.warning(
+            "register_action('%s', ...) is missing the synchronous= parameter. "
+            "Defaulting to synchronous=False (safe but prevents StringRef "
+            "optimization). Check the C++ class: use synchronous=False if "
+            "play_next_() is deferred to a callback, timer, or loop(); "
+            "use synchronous=True if play_next_() always runs before the "
+            "initial play/play_complex call returns",
+            name,
+        )
+        synchronous = False
+    return ACTION_REGISTRY.register(name, action_type, schema, synchronous=synchronous)
 
 
 def register_condition(name: str, condition_type: MockObjClass, schema: cv.Schema):
@@ -335,7 +371,10 @@ async def component_is_idle_condition_to_code(
 
 
 @register_action(
-    "delay", DelayAction, cv.templatable(cv.positive_time_period_milliseconds)
+    "delay",
+    DelayAction,
+    cv.templatable(cv.positive_time_period_milliseconds),
+    synchronous=False,
 )
 async def delay_action_to_code(
     config: ConfigType,
@@ -366,6 +405,7 @@ async def delay_action_to_code(
         cv.has_at_least_one_key(CONF_THEN, CONF_ELSE),
         cv.has_at_least_one_key(CONF_CONDITION, CONF_ANY, CONF_ALL),
     ),
+    synchronous=True,
 )
 async def if_action_to_code(
     config: ConfigType,
@@ -394,6 +434,7 @@ async def if_action_to_code(
             cv.Required(CONF_THEN): validate_action_list,
         }
     ),
+    synchronous=True,
 )
 async def while_action_to_code(
     config: ConfigType,
@@ -417,6 +458,7 @@ async def while_action_to_code(
             cv.Required(CONF_THEN): validate_action_list,
         }
     ),
+    synchronous=True,
 )
 async def repeat_action_to_code(
     config: ConfigType,
@@ -445,7 +487,7 @@ _validate_wait_until = cv.maybe_simple_value(
 )
 
 
-@register_action("wait_until", WaitUntilAction, _validate_wait_until)
+@register_action("wait_until", WaitUntilAction, _validate_wait_until, synchronous=False)
 async def wait_until_action_to_code(
     config: ConfigType,
     action_id: ID,
@@ -461,7 +503,12 @@ async def wait_until_action_to_code(
     return var
 
 
-@register_action("lambda", LambdaAction, cv.lambda_)
+# Lambda executes user C++ inline and returns — synchronous by execution model.
+# User code could theoretically store the StringRef for deferred use, but StringRef
+# is a view type and storing views beyond their scope is always unsafe regardless
+# of this optimization.  Marking non-synchronous would disable StringRef for nearly
+# all user services since most use lambda.
+@register_action("lambda", LambdaAction, cv.lambda_, synchronous=True)
 async def lambda_action_to_code(
     config: ConfigType,
     action_id: ID,
@@ -480,6 +527,7 @@ async def lambda_action_to_code(
             cv.Required(CONF_ID): cv.use_id(cg.PollingComponent),
         }
     ),
+    synchronous=True,
 )
 async def component_update_action_to_code(
     config: ConfigType,
@@ -499,6 +547,7 @@ async def component_update_action_to_code(
             cv.Required(CONF_ID): cv.use_id(cg.PollingComponent),
         }
     ),
+    synchronous=True,
 )
 async def component_suspend_action_to_code(
     config: ConfigType,
@@ -521,6 +570,7 @@ async def component_suspend_action_to_code(
             ),
         }
     ),
+    synchronous=True,
 )
 async def component_resume_action_to_code(
     config: ConfigType,
@@ -578,6 +628,27 @@ async def build_condition_list(
     return conditions
 
 
+def has_non_synchronous_actions(actions: ConfigType) -> bool:
+    """Check if a validated action list contains any non-synchronous actions.
+
+    Non-synchronous actions (delay, wait_until, script.wait, etc.) store
+    trigger args for later execution, making non-owning types like StringRef
+    unsafe.
+    """
+    if isinstance(actions, list):
+        return any(has_non_synchronous_actions(item) for item in actions)
+    if isinstance(actions, dict):
+        for key in actions:
+            if key in ACTION_REGISTRY and not ACTION_REGISTRY[key].synchronous:
+                return True
+        return any(
+            has_non_synchronous_actions(v)
+            for v in actions.values()
+            if isinstance(v, (list, dict))
+        )
+    return False
+
+
 async def build_automation(
     trigger: MockObj, args: TemplateArgsType, config: ConfigType
 ) -> MockObj:

esphome/build_gen/espidf.py

@@ -72,7 +72,7 @@ def get_component_cmakelists(minimal: bool = False) -> str:
 
     # Extract compile definitions from build flags (-DXXX -> XXX)
     compile_defs = [flag[2:] for flag in CORE.build_flags if flag.startswith("-D")]
-    compile_defs_str = "\n    ".join(compile_defs) if compile_defs else ""
+    compile_defs_str = "\n    ".join(sorted(compile_defs)) if compile_defs else ""
 
     # Extract compile options (-W flags, excluding linker flags)
     compile_opts = [
@@ -80,11 +80,11 @@ def get_component_cmakelists(minimal: bool = False) -> str:
         for flag in CORE.build_flags
         if flag.startswith("-W") and not flag.startswith("-Wl,")
     ]
-    compile_opts_str = "\n    ".join(compile_opts) if compile_opts else ""
+    compile_opts_str = "\n    ".join(sorted(compile_opts)) if compile_opts else ""
 
     # Extract linker options (-Wl, flags)
     link_opts = [flag for flag in CORE.build_flags if flag.startswith("-Wl,")]
-    link_opts_str = "\n    ".join(link_opts) if link_opts else ""
+    link_opts_str = "\n    ".join(sorted(link_opts)) if link_opts else ""
 
     return f"""\
 # Auto-generated by ESPHome

esphome/codegen.py

@@ -11,6 +11,7 @@
 from esphome.cpp_generator import (  # noqa: F401
     ArrayInitializer,
     Expression,
+    FlashStringLiteral,
     LineComment,
     LogStringLiteral,
     MockObj,

esphome/components/absolute_humidity/absolute_humidity.cpp

@@ -92,10 +92,7 @@ void AbsoluteHumidityComponent::loop() {
   // Calculate absolute humidity
   const float absolute_humidity = vapor_density(es, hr, temperature_k);
 
-  ESP_LOGD(TAG,
-           "Saturation vapor pressure %f kPa\n"
-           "Publishing absolute humidity %f g/m³",
-           es, absolute_humidity);
+  ESP_LOGD(TAG, "Saturation vapor pressure %f kPa, absolute humidity %f g/m³", es, absolute_humidity);
 
   // Publish absolute humidity
   this->status_clear_warning();

esphome/components/ac_dimmer/ac_dimmer.cpp

@@ -199,12 +199,19 @@ void AcDimmer::setup() {
   setTimer1Callback(&timer_interrupt);
 #endif
 #ifdef USE_ESP32
-  dimmer_timer = timer_begin(TIMER_FREQUENCY_HZ);
-  timer_attach_interrupt(dimmer_timer, &AcDimmerDataStore::s_timer_intr);
-  // For ESP32, we can't use dynamic interval calculation because the timerX functions
-  // are not callable from ISR (placed in flash storage).
-  // Here we just use an interrupt firing every 50 µs.
-  timer_alarm(dimmer_timer, TIMER_INTERVAL_US, true, 0);
+  if (dimmer_timer == nullptr) {
+    dimmer_timer = timer_begin(TIMER_FREQUENCY_HZ);
+    if (dimmer_timer == nullptr) {
+      ESP_LOGE(TAG, "Failed to create GPTimer for AC dimmer");
+      this->mark_failed();
+      return;
+    }
+    timer_attach_interrupt(dimmer_timer, &AcDimmerDataStore::s_timer_intr);
+    // For ESP32, we can't use dynamic interval calculation because the timerX functions
+    // are not callable from ISR (placed in flash storage).
+    // Here we just use an interrupt firing every 50 µs.
+    timer_alarm(dimmer_timer, TIMER_INTERVAL_US, true, 0);
+  }
 #endif
 }
 

esphome/components/adc/adc_sensor_rp2040.cpp

@@ -8,6 +8,13 @@
 #endif  // CYW43_USES_VSYS_PIN
 #include <hardware/adc.h>
 
+// PICO_VSYS_PIN is defined in pico-sdk board headers (e.g. boards/pico2.h),
+// but the Arduino framework's config_autogen.h includes a generic board header
+// that doesn't define it. Provide the standard value (pin 29) as a fallback.
+#ifndef PICO_VSYS_PIN
+#define PICO_VSYS_PIN 29  // NOLINT(cppcoreguidelines-macro-usage)
+#endif
+
 namespace esphome {
 namespace adc {
 

esphome/components/addressable_light/addressable_light_display.cpp

@@ -58,7 +58,10 @@ void HOT AddressableLightDisplay::draw_absolute_pixel_internal(int x, int y, Col
 
   if (this->pixel_mapper_f_.has_value()) {
     // Params are passed by reference, so they may be modified in call.
-    this->addressable_light_buffer_[(*this->pixel_mapper_f_)(x, y)] = color;
+    int index = (*this->pixel_mapper_f_)(x, y);
+    if (index < 0 || static_cast<size_t>(index) >= this->addressable_light_buffer_.size())
+      return;
+    this->addressable_light_buffer_[index] = color;
   } else {
     this->addressable_light_buffer_[y * this->get_width_internal() + x] = color;
   }

esphome/components/addressable_light/addressable_light_display.h

@@ -33,7 +33,7 @@ class AddressableLightDisplay : public display::DisplayBuffer {
         // - Save the current effect index.
         this->last_effect_index_ = light_state_->get_current_effect_index();
         // - Disable any current effect.
-        light_state_->make_call().set_effect(0).perform();
+        light_state_->make_call().set_effect(uint32_t{0}).perform();
       }
     }
     enabled_ = enabled;

esphome/components/ade7880/ade7880.cpp

@@ -121,7 +121,7 @@ void ADE7880::update() {
     this->update_sensor_from_s32_register16_(chan->forward_active_energy, AFWATTHR, [&chan](float val) {
       return chan->forward_active_energy_total += val / 14400.0f;
     });
-    this->update_sensor_from_s32_register16_(chan->reverse_active_energy, AFWATTHR, [&chan](float val) {
+    this->update_sensor_from_s32_register16_(chan->reverse_active_energy, ARWATTHR, [&chan](float val) {
       return chan->reverse_active_energy_total += val / 14400.0f;
     });
   }
@@ -137,7 +137,7 @@ void ADE7880::update() {
     this->update_sensor_from_s32_register16_(chan->forward_active_energy, BFWATTHR, [&chan](float val) {
       return chan->forward_active_energy_total += val / 14400.0f;
     });
-    this->update_sensor_from_s32_register16_(chan->reverse_active_energy, BFWATTHR, [&chan](float val) {
+    this->update_sensor_from_s32_register16_(chan->reverse_active_energy, BRWATTHR, [&chan](float val) {
       return chan->reverse_active_energy_total += val / 14400.0f;
     });
   }
@@ -153,7 +153,7 @@ void ADE7880::update() {
     this->update_sensor_from_s32_register16_(chan->forward_active_energy, CFWATTHR, [&chan](float val) {
       return chan->forward_active_energy_total += val / 14400.0f;
     });
-    this->update_sensor_from_s32_register16_(chan->reverse_active_energy, CFWATTHR, [&chan](float val) {
+    this->update_sensor_from_s32_register16_(chan->reverse_active_energy, CRWATTHR, [&chan](float val) {
       return chan->reverse_active_energy_total += val / 14400.0f;
     });
   }

esphome/components/ade7880/ade7880_registers.h

@@ -85,6 +85,9 @@ constexpr uint16_t CWATTHR = 0xE402;
 constexpr uint16_t AFWATTHR = 0xE403;
 constexpr uint16_t BFWATTHR = 0xE404;
 constexpr uint16_t CFWATTHR = 0xE405;
+constexpr uint16_t ARWATTHR = 0xE406;
+constexpr uint16_t BRWATTHR = 0xE407;
+constexpr uint16_t CRWATTHR = 0xE408;
 constexpr uint16_t AFVARHR = 0xE409;
 constexpr uint16_t BFVARHR = 0xE40A;
 constexpr uint16_t CFVARHR = 0xE40B;

esphome/components/ads1115/ads1115.cpp

@@ -173,19 +173,8 @@ float ADS1115Component::request_measurement(ADS1115Multiplexer multiplexer, ADS1
   }
 
   if (resolution == ADS1015_12_BITS) {
-    bool negative = (raw_conversion >> 15) == 1;
-
-    // shift raw_conversion as it's only 12-bits, left justified
-    raw_conversion = raw_conversion >> (16 - ADS1015_12_BITS);
-
-    // check if number was negative in order to keep the sign
-    if (negative) {
-      // the number was negative
-      // 1) set the negative bit back
-      raw_conversion |= 0x8000;
-      // 2) reset the former (shifted) negative bit
-      raw_conversion &= 0xF7FF;
-    }
+    // ADS1015 returns 12-bit value left-justified in 16 bits; shift right and sign-extend
+    raw_conversion = static_cast<uint16_t>(static_cast<int16_t>(raw_conversion) >> (16 - ADS1015_12_BITS));
   }
 
   auto signed_conversion = static_cast<int16_t>(raw_conversion);

esphome/components/ags10/sensor.py

@@ -92,6 +92,7 @@ AGS10_NEW_I2C_ADDRESS_SCHEMA = cv.maybe_simple_value(
     "ags10.new_i2c_address",
     AGS10NewI2cAddressAction,
     AGS10_NEW_I2C_ADDRESS_SCHEMA,
+    synchronous=True,
 )
 async def ags10newi2caddress_to_code(config, action_id, template_arg, args):
     var = cg.new_Pvariable(action_id, template_arg)
@@ -121,6 +122,7 @@ AGS10_SET_ZERO_POINT_SCHEMA = cv.Schema(
     "ags10.set_zero_point",
     AGS10SetZeroPointAction,
     AGS10_SET_ZERO_POINT_SCHEMA,
+    synchronous=True,
 )
 async def ags10setzeropoint_to_code(config, action_id, template_arg, args):
     var = cg.new_Pvariable(action_id, template_arg)

esphome/components/aic3204/audio_dac.py

@@ -34,7 +34,10 @@ SET_AUTO_MUTE_ACTION_SCHEMA = cv.maybe_simple_value(
 
 
 @automation.register_action(
-    "aic3204.set_auto_mute_mode", SetAutoMuteAction, SET_AUTO_MUTE_ACTION_SCHEMA
+    "aic3204.set_auto_mute_mode",
+    SetAutoMuteAction,
+    SET_AUTO_MUTE_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def aic3204_set_volume_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])

esphome/components/alarm_control_panel/__init__.py

@@ -186,8 +186,8 @@ ALARM_CONTROL_PANEL_CONDITION_SCHEMA = maybe_simple_id(
 )
 
 
+@setup_entity("alarm_control_panel")
 async def setup_alarm_control_panel_core_(var, config):
-    await setup_entity(var, config, "alarm_control_panel")
     for conf in config.get(CONF_ON_STATE, []):
         trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
         await automation.build_automation(trigger, [], conf)
@@ -243,7 +243,10 @@ async def new_alarm_control_panel(config, *args):
 
 
 @automation.register_action(
-    "alarm_control_panel.arm_away", ArmAwayAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.arm_away",
+    ArmAwayAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def alarm_action_arm_away_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
@@ -255,7 +258,10 @@ async def alarm_action_arm_away_to_code(config, action_id, template_arg, args):
 
 
 @automation.register_action(
-    "alarm_control_panel.arm_home", ArmHomeAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.arm_home",
+    ArmHomeAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def alarm_action_arm_home_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
@@ -267,7 +273,10 @@ async def alarm_action_arm_home_to_code(config, action_id, template_arg, args):
 
 
 @automation.register_action(
-    "alarm_control_panel.arm_night", ArmNightAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.arm_night",
+    ArmNightAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def alarm_action_arm_night_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
@@ -279,7 +288,10 @@ async def alarm_action_arm_night_to_code(config, action_id, template_arg, args):
 
 
 @automation.register_action(
-    "alarm_control_panel.disarm", DisarmAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.disarm",
+    DisarmAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def alarm_action_disarm_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
@@ -291,7 +303,10 @@ async def alarm_action_disarm_to_code(config, action_id, template_arg, args):
 
 
 @automation.register_action(
-    "alarm_control_panel.pending", PendingAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.pending",
+    PendingAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def alarm_action_pending_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
@@ -299,7 +314,10 @@ async def alarm_action_pending_to_code(config, action_id, template_arg, args):
 
 
 @automation.register_action(
-    "alarm_control_panel.triggered", TriggeredAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.triggered",
+    TriggeredAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def alarm_action_trigger_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
@@ -307,7 +325,10 @@ async def alarm_action_trigger_to_code(config, action_id, template_arg, args):
 
 
 @automation.register_action(
-    "alarm_control_panel.chime", ChimeAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.chime",
+    ChimeAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def alarm_action_chime_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
@@ -315,7 +336,10 @@ async def alarm_action_chime_to_code(config, action_id, template_arg, args):
 
 
 @automation.register_action(
-    "alarm_control_panel.ready", ReadyAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+    "alarm_control_panel.ready",
+    ReadyAction,
+    ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+    synchronous=True,
 )
 @automation.register_condition(
     "alarm_control_panel.ready",

esphome/components/alarm_control_panel/alarm_control_panel_call.cpp

@@ -12,7 +12,14 @@ AlarmControlPanelCall::AlarmControlPanelCall(AlarmControlPanel *parent) : parent
 
 AlarmControlPanelCall &AlarmControlPanelCall::set_code(const char *code) {
   if (code != nullptr) {
-    this->code_ = std::string(code);
+    return this->set_code(code, strlen(code));
+  }
+  return *this;
+}
+
+AlarmControlPanelCall &AlarmControlPanelCall::set_code(const char *code, size_t len) {
+  if (code != nullptr) {
+    this->code_ = std::string(code, len);
   }
   return *this;
 }

esphome/components/alarm_control_panel/alarm_control_panel_call.h

@@ -15,7 +15,8 @@ class AlarmControlPanelCall {
   AlarmControlPanelCall(AlarmControlPanel *parent);
 
   AlarmControlPanelCall &set_code(const char *code);
-  AlarmControlPanelCall &set_code(const std::string &code) { return this->set_code(code.c_str()); }
+  AlarmControlPanelCall &set_code(const char *code, size_t len);
+  AlarmControlPanelCall &set_code(const std::string &code) { return this->set_code(code.c_str(), code.size()); }
   AlarmControlPanelCall &arm_away();
   AlarmControlPanelCall &arm_home();
   AlarmControlPanelCall &arm_night();

esphome/components/alpha3/alpha3.cpp

@@ -125,7 +125,7 @@ void Alpha3::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc
         this->current_sensor_->publish_state(NAN);
       if (this->speed_sensor_ != nullptr)
         this->speed_sensor_->publish_state(NAN);
-      if (this->speed_sensor_ != nullptr)
+      if (this->voltage_sensor_ != nullptr)
         this->voltage_sensor_->publish_state(NAN);
       break;
     }

esphome/components/am43/cover/am43_cover.cpp

@@ -63,8 +63,9 @@ void Am43Component::control(const CoverCall &call) {
       ESP_LOGW(TAG, "[%s] Error writing stop command to device, error = %d", this->get_name().c_str(), status);
     }
   }
-  if (call.get_position().has_value()) {
-    auto pos = *call.get_position();
+  auto opt_pos = call.get_position();
+  if (opt_pos.has_value()) {
+    auto pos = *opt_pos;
 
     if (this->invert_position_)
       pos = 1 - pos;

esphome/components/am43/sensor/am43_sensor.h

@@ -35,7 +35,7 @@ class Am43 : public esphome::ble_client::BLEClientNode, public PollingComponent
   uint8_t current_sensor_;
   // The AM43 often gets into a state where it spams loads of battery update
   // notifications. Here we will limit to no more than every 10s.
-  uint8_t last_battery_update_;
+  uint32_t last_battery_update_;
 };
 
 }  // namespace am43

esphome/components/animation/__init__.py

@@ -69,9 +69,15 @@ SET_FRAME_SCHEMA = cv.Schema(
 )
 
 
-@automation.register_action("animation.next_frame", NextFrameAction, NEXT_FRAME_SCHEMA)
-@automation.register_action("animation.prev_frame", PrevFrameAction, PREV_FRAME_SCHEMA)
-@automation.register_action("animation.set_frame", SetFrameAction, SET_FRAME_SCHEMA)
+@automation.register_action(
+    "animation.next_frame", NextFrameAction, NEXT_FRAME_SCHEMA, synchronous=True
+)
+@automation.register_action(
+    "animation.prev_frame", PrevFrameAction, PREV_FRAME_SCHEMA, synchronous=True
+)
+@automation.register_action(
+    "animation.set_frame", SetFrameAction, SET_FRAME_SCHEMA, synchronous=True
+)
 async def animation_action_to_code(config, action_id, template_arg, args):
     paren = await cg.get_variable(config[CONF_ID])
     var = cg.new_Pvariable(action_id, template_arg, paren)

esphome/components/anova/anova.cpp

@@ -24,8 +24,9 @@ void Anova::loop() {
 }
 
 void Anova::control(const ClimateCall &call) {
-  if (call.get_mode().has_value()) {
-    ClimateMode mode = *call.get_mode();
+  auto mode_val = call.get_mode();
+  if (mode_val.has_value()) {
+    ClimateMode mode = *mode_val;
     AnovaPacket *pkt;
     switch (mode) {
       case climate::CLIMATE_MODE_OFF:
@@ -45,8 +46,9 @@ void Anova::control(const ClimateCall &call) {
       ESP_LOGW(TAG, "[%s] esp_ble_gattc_write_char failed, status=%d", this->parent_->address_str(), status);
     }
   }
-  if (call.get_target_temperature().has_value()) {
-    auto *pkt = this->codec_->get_set_target_temp_request(*call.get_target_temperature());
+  auto target_temp = call.get_target_temperature();
+  if (target_temp.has_value()) {
+    auto *pkt = this->codec_->get_set_target_temp_request(*target_temp);
     auto status =
         esp_ble_gattc_write_char(this->parent_->get_gattc_if(), this->parent_->get_conn_id(), this->char_handle_,
                                  pkt->length, pkt->data, ESP_GATT_WRITE_TYPE_NO_RSP, ESP_GATT_AUTH_REQ_NONE);
@@ -67,10 +69,8 @@ void Anova::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_
     case ESP_GATTC_SEARCH_CMPL_EVT: {
       auto *chr = this->parent_->get_characteristic(ANOVA_SERVICE_UUID, ANOVA_CHARACTERISTIC_UUID);
       if (chr == nullptr) {
-        ESP_LOGW(TAG,
-                 "[%s] No control service found at device, not an Anova..?\n"
-                 "[%s] Note, this component does not currently support Anova Nano.",
-                 this->get_name().c_str(), this->get_name().c_str());
+        ESP_LOGW(TAG, "[%s] No control service found at device, not an Anova..?", this->get_name().c_str());
+        ESP_LOGW(TAG, "[%s] Note, this component does not currently support Anova Nano.", this->get_name().c_str());
         break;
       }
       this->char_handle_ = chr->handle;
@@ -144,9 +144,12 @@ void Anova::update() {
     return;
 
   if (this->current_request_ < 2) {
-    auto *pkt = this->codec_->get_read_device_status_request();
-    if (this->current_request_ == 0)
-      this->codec_->get_set_unit_request(this->fahrenheit_ ? 'f' : 'c');
+    AnovaPacket *pkt;
+    if (this->current_request_ == 0) {
+      pkt = this->codec_->get_set_unit_request(this->fahrenheit_ ? 'f' : 'c');
+    } else {
+      pkt = this->codec_->get_read_device_status_request();
+    }
     auto status =
         esp_ble_gattc_write_char(this->parent_->get_gattc_if(), this->parent_->get_conn_id(), this->char_handle_,
                                  pkt->length, pkt->data, ESP_GATT_WRITE_TYPE_NO_RSP, ESP_GATT_AUTH_REQ_NONE);

esphome/components/apds9960/apds9960.cpp

@@ -251,11 +251,11 @@ void APDS9960::read_gesture_data_() {
 
   uint8_t buf[128];
   for (uint8_t pos = 0; pos < fifo_level * 4; pos += 32) {
-    // The ESP's i2c driver has a limited buffer size.
-    // This way of retrieving the data should be wrong according to the datasheet
-    // but it seems to work.
+    // Read in 32-byte chunks due to ESP8266 I2C buffer limit.
+    // Always read from 0xFC — the FIFO auto-increments through 0xFC-0xFF
+    // and advances its internal pointer after every 4th byte.
     uint8_t read = std::min(32, fifo_level * 4 - pos);
-    APDS9960_WARNING_CHECK(this->read_bytes(0xFC + pos, buf + pos, read), "Reading FIFO buffer failed.");
+    APDS9960_WARNING_CHECK(this->read_bytes(0xFC, buf + pos, read), "Reading FIFO buffer failed.");
   }
 
   if (millis() - this->gesture_start_ > 500) {

esphome/components/api/__init__.py

@@ -76,7 +76,7 @@ SERVICE_ARG_NATIVE_TYPES: dict[str, MockObj] = {
     "bool": cg.bool_,
     "int": cg.int32,
     "float": cg.float_,
-    "string": cg.std_string,
+    "string": cg.StringRef,
     "bool[]": cg.FixedVector.template(cg.bool_).operator("const").operator("ref"),
     "int[]": cg.FixedVector.template(cg.int32).operator("const").operator("ref"),
     "float[]": cg.FixedVector.template(cg.float_).operator("const").operator("ref"),
@@ -233,8 +233,8 @@ def _consume_api_sockets(config: ConfigType) -> ConfigType:
 
     # API needs 1 listening socket + typically 3 concurrent client connections
     # (not max_connections, which is the upper limit rarely reached)
-    sockets_needed = 1 + 3
-    socket.consume_sockets(sockets_needed, "api")(config)
+    socket.consume_sockets(3, "api")(config)
+    socket.consume_sockets(1, "api", socket.SocketType.TCP_LISTEN)(config)
     return config
 
 
@@ -380,9 +380,18 @@ async def to_code(config: ConfigType) -> None:
                 if is_optional:
                     func_args.append((cg.bool_, "return_response"))
 
+            # Check if action chain has non-synchronous actions that would make
+            # non-owning StringRef dangle (rx_buf_ reused after delay)
+            has_non_synchronous = automation.has_non_synchronous_actions(
+                conf.get(CONF_THEN, [])
+            )
+
             service_arg_names: list[str] = []
             for name, var_ in conf[CONF_VARIABLES].items():
                 native = SERVICE_ARG_NATIVE_TYPES[var_]
+                # Fall back to std::string for string args if non-synchronous actions exist
+                if has_non_synchronous and native is cg.StringRef:
+                    native = cg.std_string
                 service_template_args.append(native)
                 func_args.append((native, name))
                 service_arg_names.append(name)
@@ -444,7 +453,7 @@ async def to_code(config: ConfigType) -> None:
             # and plaintext disabled. Only a factory reset can remove it.
             cg.add_define("USE_API_PLAINTEXT")
         cg.add_define("USE_API_NOISE")
-        cg.add_library("esphome/noise-c", "0.1.10")
+        cg.add_library("esphome/noise-c", "0.1.11")
     else:
         cg.add_define("USE_API_PLAINTEXT")
 
@@ -509,11 +518,13 @@ HOMEASSISTANT_ACTION_ACTION_SCHEMA = cv.All(
     "homeassistant.action",
     HomeAssistantServiceCallAction,
     HOMEASSISTANT_ACTION_ACTION_SCHEMA,
+    synchronous=True,
 )
 @automation.register_action(
     "homeassistant.service",
     HomeAssistantServiceCallAction,
     HOMEASSISTANT_ACTION_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def homeassistant_service_to_code(
     config: ConfigType,
@@ -524,24 +535,31 @@ async def homeassistant_service_to_code(
     cg.add_define("USE_API_HOMEASSISTANT_SERVICES")
     serv = await cg.get_variable(config[CONF_ID])
     var = cg.new_Pvariable(action_id, template_arg, serv, False)
-    templ = await cg.templatable(config[CONF_ACTION], args, None)
+    templ = await cg.templatable(config[CONF_ACTION], args, cg.std_string)
     cg.add(var.set_service(templ))
 
     # Initialize FixedVectors with exact sizes from config
     cg.add(var.init_data(len(config[CONF_DATA])))
     for key, value in config[CONF_DATA].items():
+        # output_type=None because lambdas can return non-string types (int,
+        # float, char*) that TemplatableStringValue converts via to_string.
+        # Static strings are manually wrapped for PROGMEM on ESP8266.
         templ = await cg.templatable(value, args, None)
-        cg.add(var.add_data(key, templ))
+        if isinstance(templ, str):
+            templ = cg.FlashStringLiteral(templ)
+        cg.add(var.add_data(cg.FlashStringLiteral(key), templ))
 
     cg.add(var.init_data_template(len(config[CONF_DATA_TEMPLATE])))
     for key, value in config[CONF_DATA_TEMPLATE].items():
         templ = await cg.templatable(value, args, None)
-        cg.add(var.add_data_template(key, templ))
+        if isinstance(templ, str):
+            templ = cg.FlashStringLiteral(templ)
+        cg.add(var.add_data_template(cg.FlashStringLiteral(key), templ))
 
     cg.add(var.init_variables(len(config[CONF_VARIABLES])))
     for key, value in config[CONF_VARIABLES].items():
         templ = await cg.templatable(value, args, None)
-        cg.add(var.add_variable(key, templ))
+        cg.add(var.add_variable(cg.FlashStringLiteral(key), templ))
 
     if on_error := config.get(CONF_ON_ERROR):
         cg.add_define("USE_API_HOMEASSISTANT_ACTION_RESPONSES")
@@ -604,29 +622,37 @@ HOMEASSISTANT_EVENT_ACTION_SCHEMA = cv.Schema(
     "homeassistant.event",
     HomeAssistantServiceCallAction,
     HOMEASSISTANT_EVENT_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def homeassistant_event_to_code(config, action_id, template_arg, args):
     cg.add_define("USE_API_HOMEASSISTANT_SERVICES")
     serv = await cg.get_variable(config[CONF_ID])
     var = cg.new_Pvariable(action_id, template_arg, serv, True)
-    templ = await cg.templatable(config[CONF_EVENT], args, None)
+    templ = await cg.templatable(config[CONF_EVENT], args, cg.std_string)
     cg.add(var.set_service(templ))
 
     # Initialize FixedVectors with exact sizes from config
     cg.add(var.init_data(len(config[CONF_DATA])))
     for key, value in config[CONF_DATA].items():
+        # output_type=None because lambdas can return non-string types (int,
+        # float, char*) that TemplatableStringValue converts via to_string.
+        # Static strings are manually wrapped for PROGMEM on ESP8266.
         templ = await cg.templatable(value, args, None)
-        cg.add(var.add_data(key, templ))
+        if isinstance(templ, str):
+            templ = cg.FlashStringLiteral(templ)
+        cg.add(var.add_data(cg.FlashStringLiteral(key), templ))
 
     cg.add(var.init_data_template(len(config[CONF_DATA_TEMPLATE])))
     for key, value in config[CONF_DATA_TEMPLATE].items():
         templ = await cg.templatable(value, args, None)
-        cg.add(var.add_data_template(key, templ))
+        if isinstance(templ, str):
+            templ = cg.FlashStringLiteral(templ)
+        cg.add(var.add_data_template(cg.FlashStringLiteral(key), templ))
 
     cg.add(var.init_variables(len(config[CONF_VARIABLES])))
     for key, value in config[CONF_VARIABLES].items():
         templ = await cg.templatable(value, args, None)
-        cg.add(var.add_variable(key, templ))
+        cg.add(var.add_variable(cg.FlashStringLiteral(key), templ))
 
     return var
 
@@ -644,16 +670,17 @@ HOMEASSISTANT_TAG_SCANNED_ACTION_SCHEMA = cv.maybe_simple_value(
     "homeassistant.tag_scanned",
     HomeAssistantServiceCallAction,
     HOMEASSISTANT_TAG_SCANNED_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def homeassistant_tag_scanned_to_code(config, action_id, template_arg, args):
     cg.add_define("USE_API_HOMEASSISTANT_SERVICES")
     serv = await cg.get_variable(config[CONF_ID])
     var = cg.new_Pvariable(action_id, template_arg, serv, True)
-    cg.add(var.set_service("esphome.tag_scanned"))
+    cg.add(var.set_service(cg.FlashStringLiteral("esphome.tag_scanned")))
     # Initialize FixedVector with exact size (1 data field)
     cg.add(var.init_data(1))
     templ = await cg.templatable(config[CONF_TAG], args, cg.std_string)
-    cg.add(var.add_data("tag_id", templ))
+    cg.add(var.add_data(cg.FlashStringLiteral("tag_id"), templ))
     return var
 
 
@@ -685,6 +712,7 @@ API_RESPOND_ACTION_SCHEMA = cv.All(
     "api.respond",
     APIRespondAction,
     API_RESPOND_ACTION_SCHEMA,
+    synchronous=True,
 )
 async def api_respond_to_code(
     config: ConfigType,

esphome/components/api/api.proto

@@ -58,6 +58,7 @@ service APIConnection {
   rpc subscribe_bluetooth_connections_free(SubscribeBluetoothConnectionsFreeRequest) returns (BluetoothConnectionsFreeResponse) {}
   rpc unsubscribe_bluetooth_le_advertisements(UnsubscribeBluetoothLEAdvertisementsRequest) returns (void) {}
   rpc bluetooth_scanner_set_mode(BluetoothScannerSetModeRequest) returns (void) {}
+  rpc bluetooth_set_connection_params(BluetoothSetConnectionParamsRequest) returns (BluetoothSetConnectionParamsResponse) {}
 
   rpc subscribe_voice_assistant(SubscribeVoiceAssistantRequest) returns (void) {}
   rpc voice_assistant_get_configuration(VoiceAssistantConfigurationRequest) returns (VoiceAssistantConfigurationResponse) {}
@@ -69,6 +70,12 @@ service APIConnection {
   rpc zwave_proxy_request(ZWaveProxyRequest) returns (void) {}
 
   rpc infrared_rf_transmit_raw_timings(InfraredRFTransmitRawTimingsRequest) returns (void) {}
+
+  rpc serial_proxy_configure(SerialProxyConfigureRequest) returns (void) {}
+  rpc serial_proxy_write(SerialProxyWriteRequest) returns (void) {}
+  rpc serial_proxy_set_modem_pins(SerialProxySetModemPinsRequest) returns (void) {}
+  rpc serial_proxy_get_modem_pins(SerialProxyGetModemPinsRequest) returns (void) {}
+  rpc serial_proxy_request(SerialProxyRequest) returns (void) {}
 }
 
 
@@ -198,6 +205,17 @@ message DeviceInfo {
   uint32 area_id = 3;
 }
 
+enum SerialProxyPortType {
+  SERIAL_PROXY_PORT_TYPE_TTL = 0;
+  SERIAL_PROXY_PORT_TYPE_RS232 = 1;
+  SERIAL_PROXY_PORT_TYPE_RS485 = 2;
+}
+
+message SerialProxyInfo {
+  string name = 1;                    // Human-readable port name
+  SerialProxyPortType port_type = 2;  // Port type (RS232, RS485)
+}
+
 message DeviceInfoResponse {
   option (id) = 10;
   option (source) = SOURCE_SERVER;
@@ -260,6 +278,9 @@ message DeviceInfoResponse {
   // Indicates if Z-Wave proxy support is available and features supported
   uint32 zwave_proxy_feature_flags = 23 [(field_ifdef) = "USE_ZWAVE_PROXY"];
   uint32 zwave_home_id = 24 [(field_ifdef) = "USE_ZWAVE_PROXY"];
+
+  // Serial proxy instance metadata
+  repeated SerialProxyInfo serial_proxies = 25 [(field_ifdef) = "USE_SERIAL_PROXY", (fixed_array_size_define) = "SERIAL_PROXY_COUNT"];
 }
 
 message ListEntitiesRequest {
@@ -834,6 +855,33 @@ message GetTimeRequest {
   option (source) = SOURCE_SERVER;
 }
 
+enum DSTRuleType {
+  DST_RULE_TYPE_NONE = 0;
+  DST_RULE_TYPE_MONTH_WEEK_DAY = 1;
+  DST_RULE_TYPE_JULIAN_NO_LEAP = 2;
+  DST_RULE_TYPE_DAY_OF_YEAR = 3;
+}
+
+message DSTRule {
+  option (source) = SOURCE_CLIENT;
+
+  sint32 time_seconds = 1;
+  uint32 day = 2;
+  DSTRuleType type = 3;
+  uint32 month = 4;
+  uint32 week = 5;
+  uint32 day_of_week = 6;
+}
+
+message ParsedTimezone {
+  option (source) = SOURCE_CLIENT;
+
+  sint32 std_offset_seconds = 1;
+  sint32 dst_offset_seconds = 2;
+  DSTRule dst_start = 3;
+  DSTRule dst_end = 4;
+}
+
 message GetTimeResponse {
   option (id) = 37;
   option (source) = SOURCE_CLIENT;
@@ -841,6 +889,7 @@ message GetTimeResponse {
 
   fixed32 epoch_seconds = 1;
   string timezone = 2;
+  ParsedTimezone parsed_timezone = 3;
 }
 
 // ==================== USER-DEFINES SERVICES ====================
@@ -989,6 +1038,7 @@ enum ClimateAction {
   CLIMATE_ACTION_IDLE = 4;
   CLIMATE_ACTION_DRYING = 5;
   CLIMATE_ACTION_FAN = 6;
+  CLIMATE_ACTION_DEFROSTING = 7;
 }
 enum ClimatePreset {
   CLIMATE_PRESET_NONE = 0;
@@ -1554,11 +1604,11 @@ message BluetoothLEAdvertisementResponse {
 }
 
 message BluetoothLERawAdvertisement {
-  uint64 address = 1;
-  sint32 rssi = 2;
+  uint64 address = 1 [(force) = true];
+  sint32 rssi = 2 [(force) = true];
   uint32 address_type = 3;
 
-  bytes data = 4 [(fixed_array_size) = 62];
+  bytes data = 4 [(fixed_array_size) = 62, (force) = true];
 }
 
 message BluetoothLERawAdvertisementsResponse {
@@ -2488,3 +2538,134 @@ message InfraredRFReceiveEvent {
   fixed32 key = 2;                                    // Key identifying the receiver instance
   repeated sint32 timings = 3 [packed = true, (container_pointer_no_template) = "std::vector<int32_t>"];  // Raw timings in microseconds (zigzag-encoded): alternating mark/space periods
 }
+
+// ==================== SERIAL PROXY ====================
+
+enum SerialProxyParity {
+  SERIAL_PROXY_PARITY_NONE = 0;
+  SERIAL_PROXY_PARITY_EVEN = 1;
+  SERIAL_PROXY_PARITY_ODD = 2;
+}
+
+// Configure UART parameters for a serial proxy instance
+message SerialProxyConfigureRequest {
+  option (id) = 138;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;          // Instance index (0-based)
+  uint32 baudrate = 2;          // Baud rate in bits per second
+  bool flow_control = 3;        // Enable hardware flow control
+  SerialProxyParity parity = 4; // Parity setting
+  uint32 stop_bits = 5;         // Number of stop bits (1 or 2)
+  uint32 data_size = 6;         // Number of data bits (5-8)
+}
+
+// Data received from a serial device, forwarded to clients
+message SerialProxyDataReceived {
+  option (id) = 139;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_SERIAL_PROXY";
+  option (no_delay) = true;
+
+  uint32 instance = 1;          // Instance index (0-based)
+  bytes data = 2;               // Raw data received from the serial device
+}
+
+// Write data to a serial device
+message SerialProxyWriteRequest {
+  option (id) = 140;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_SERIAL_PROXY";
+  option (no_delay) = true;
+
+  uint32 instance = 1;          // Instance index (0-based)
+  bytes data = 2;               // Raw data to write to the serial device
+}
+
+// Set modem control pin states (RTS and DTR)
+message SerialProxySetModemPinsRequest {
+  option (id) = 141;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;          // Instance index (0-based)
+  uint32 line_states = 2;       // Bitmask of SerialProxyLineStateFlags
+}
+
+// Request current modem control pin states
+message SerialProxyGetModemPinsRequest {
+  option (id) = 142;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;          // Instance index (0-based)
+}
+
+// Response with current modem control pin states
+message SerialProxyGetModemPinsResponse {
+  option (id) = 143;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;          // Instance index (0-based)
+  uint32 line_states = 2;       // Bitmask of SerialProxyLineStateFlags
+}
+
+enum SerialProxyRequestType {
+  SERIAL_PROXY_REQUEST_TYPE_SUBSCRIBE = 0;   // Subscribe to receive data from this serial proxy instance
+  SERIAL_PROXY_REQUEST_TYPE_UNSUBSCRIBE = 1; // Unsubscribe from this serial proxy instance
+  SERIAL_PROXY_REQUEST_TYPE_FLUSH = 2;       // Flush the serial port (block until all TX data is sent)
+}
+
+enum SerialProxyStatus {
+  SERIAL_PROXY_STATUS_OK = 0;              // Completed successfully; TX drain confirmed
+  SERIAL_PROXY_STATUS_ASSUMED_SUCCESS = 1; // Platform cannot confirm TX drain; success assumed
+  SERIAL_PROXY_STATUS_ERROR = 2;           // Driver or hardware error
+  SERIAL_PROXY_STATUS_TIMEOUT = 3;         // Timed out before TX completed
+  SERIAL_PROXY_STATUS_NOT_SUPPORTED = 4;   // Request type not supported by this instance
+}
+
+// Generic request message for simple serial proxy operations
+message SerialProxyRequest {
+  option (id) = 144;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;                  // Instance index (0-based)
+  SerialProxyRequestType type = 2;      // Request type
+}
+
+// Response to a SerialProxyRequest (e.g. flush completion or failure)
+message SerialProxyRequestResponse {
+  option (id) = 147;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_SERIAL_PROXY";
+
+  uint32 instance = 1;                  // Instance index (0-based)
+  SerialProxyRequestType type = 2;      // Which request type this responds to
+  SerialProxyStatus status = 3;         // Result status
+  string error_message = 4;            // Additional detail on failure (optional)
+}
+
+// ==================== BLUETOOTH CONNECTION PARAMS ====================
+message BluetoothSetConnectionParamsRequest {
+  option (id) = 145;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_BLUETOOTH_PROXY";
+
+  uint64 address = 1;
+  uint32 min_interval = 2;  // units of 1.25ms
+  uint32 max_interval = 3;  // units of 1.25ms
+  uint32 latency = 4;
+  uint32 timeout = 5;       // units of 10ms
+}
+
+message BluetoothSetConnectionParamsResponse {
+  option (id) = 146;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_BLUETOOTH_PROXY";
+
+  uint64 address = 1;
+  int32 error = 2;
+}

esphome/components/api/api_buffer.cpp

@@ -0,0 +1,13 @@
+#include "api_buffer.h"
+
+namespace esphome::api {
+
+void APIBuffer::grow_(size_t n) {
+  auto new_data = make_buffer(n);
+  if (this->size_)
+    std::memcpy(new_data.get(), this->data_.get(), this->size_);
+  this->data_ = std::move(new_data);
+  this->capacity_ = n;
+}
+
+}  // namespace esphome::api

esphome/components/api/api_buffer.h

@@ -0,0 +1,67 @@
+#pragma once
+
+#include <cstdint>
+#include <cstring>
+#include <memory>
+
+#include "esphome/core/defines.h"
+#include "esphome/core/helpers.h"
+
+namespace esphome::api {
+
+/// Helper to use make_unique_for_overwrite where available (skips zero-fill),
+/// falling back to make_unique on older GCC (ESP8266, LibreTiny).
+inline std::unique_ptr<uint8_t[]> make_buffer(size_t n) {
+#if defined(USE_ESP8266) || defined(USE_LIBRETINY)
+  return std::make_unique<uint8_t[]>(n);
+#else
+  return std::make_unique_for_overwrite<uint8_t[]>(n);
+#endif
+}
+
+/// Byte buffer that skips zero-initialization on resize().
+///
+/// std::vector<uint8_t>::resize() zero-fills new bytes via memset. For the
+/// shared protobuf write buffer, every byte is overwritten by the encoder,
+/// making the zero-fill pure waste. For the receive buffer, bytes are
+/// overwritten by socket reads.
+///
+/// Designed for bulk clear/resize/overwrite patterns. grow_() allocates
+/// exactly the requested size (no growth factor) since callers resize to
+/// known sizes rather than appending incrementally.
+///
+/// Safe because: callers always write exactly the number of bytes they
+/// resize for. In the protobuf write path, debug_check_bounds_ validates
+/// writes in debug builds.
+class APIBuffer {
+ public:
+  void clear() { this->size_ = 0; }
+  inline void reserve(size_t n) ESPHOME_ALWAYS_INLINE {
+    if (n > this->capacity_)
+      this->grow_(n);
+  }
+  inline void resize(size_t n) ESPHOME_ALWAYS_INLINE {
+    this->reserve(n);
+    this->size_ = n;  // no zero-fill
+  }
+  uint8_t *data() { return this->data_.get(); }
+  const uint8_t *data() const { return this->data_.get(); }
+  size_t size() const { return this->size_; }
+  bool empty() const { return this->size_ == 0; }
+  uint8_t &operator[](size_t i) { return this->data_[i]; }
+  const uint8_t &operator[](size_t i) const { return this->data_[i]; }
+  /// Release all memory (equivalent to std::vector swap trick).
+  void release() {
+    this->data_.reset();
+    this->size_ = 0;
+    this->capacity_ = 0;
+  }
+
+ protected:
+  void grow_(size_t n);
+  std::unique_ptr<uint8_t[]> data_;
+  size_t size_{0};
+  size_t capacity_{0};
+};
+
+}  // namespace esphome::api