Merge branch 'dev' into socket-lwip-raw-udp

Co-authored-by: J. Nick Koston <nick@koston.org>
Co-authored-by: J. Nick Koston <nick@home-assistant.io>

.ai/instructions.md

@@ -1,230 +0,0 @@
-# ESPHome AI Collaboration Guide
-
-This document provides essential context for AI models interacting with this project. Adhering to these guidelines will ensure consistency and maintain code quality.
-
-## 1. Project Overview & Purpose
-
-*   **Primary Goal:** ESPHome is a system to configure microcontrollers (like ESP32, ESP8266, RP2040, and LibreTiny-based chips) using simple yet powerful YAML configuration files. It generates C++ firmware that can be compiled and flashed to these devices, allowing users to control them remotely through home automation systems.
-*   **Business Domain:** Internet of Things (IoT), Home Automation.
-
-## 2. Core Technologies & Stack
-
-*   **Languages:** Python (>=3.11), C++ (gnu++20)
-*   **Frameworks & Runtimes:** PlatformIO, Arduino, ESP-IDF.
-*   **Build Systems:** PlatformIO is the primary build system. CMake is used as an alternative.
-*   **Configuration:** YAML.
-*   **Key Libraries/Dependencies:**
-    *   **Python:** `voluptuous` (for configuration validation), `PyYAML` (for parsing configuration files), `paho-mqtt` (for MQTT communication), `tornado` (for the web server), `aioesphomeapi` (for the native API).
-    *   **C++:** `ArduinoJson` (for JSON serialization/deserialization), `AsyncMqttClient-esphome` (for MQTT), `ESPAsyncWebServer` (for the web server).
-*   **Package Manager(s):** `pip` (for Python dependencies), `platformio` (for C++/PlatformIO dependencies).
-*   **Communication Protocols:** Protobuf (for native API), MQTT, HTTP.
-
-## 3. Architectural Patterns
-
-*   **Overall Architecture:** The project follows a code-generation architecture. The Python code parses user-defined YAML configuration files and generates C++ source code. This C++ code is then compiled and flashed to the target microcontroller using PlatformIO.
-
-*   **Directory Structure Philosophy:**
-    *   `/esphome`: Contains the core Python source code for the ESPHome application.
-    *   `/esphome/components`: Contains the individual components that can be used in ESPHome configurations. Each component is a self-contained unit with its own C++ and Python code.
-    *   `/tests`: Contains all unit and integration tests for the Python code.
-    *   `/docker`: Contains Docker-related files for building and running ESPHome in a container.
-    *   `/script`: Contains helper scripts for development and maintenance.
-
-*   **Core Architectural Components:**
-    1.  **Configuration System** (`esphome/config*.py`): Handles YAML parsing and validation using Voluptuous, schema definitions, and multi-platform configurations.
-    2.  **Code Generation** (`esphome/codegen.py`, `esphome/cpp_generator.py`): Manages Python to C++ code generation, template processing, and build flag management.
-    3.  **Component System** (`esphome/components/`): Contains modular hardware and software components with platform-specific implementations and dependency management.
-    4.  **Core Framework** (`esphome/core/`): Manages the application lifecycle, hardware abstraction, and component registration.
-    5.  **Dashboard** (`esphome/dashboard/`): A web-based interface for device configuration, management, and OTA updates.
-
-*   **Platform Support:**
-    1.  **ESP32** (`components/esp32/`): Espressif ESP32 family. Supports multiple variants (Original, C2, C3, C5, C6, H2, P4, S2, S3) with ESP-IDF framework. Arduino framework supports only a subset of the variants (Original, C3, S2, S3).
-    2.  **ESP8266** (`components/esp8266/`): Espressif ESP8266. Arduino framework only, with memory constraints.
-    3.  **RP2040** (`components/rp2040/`): Raspberry Pi Pico/RP2040. Arduino framework with PIO (Programmable I/O) support.
-    4.  **LibreTiny** (`components/libretiny/`): Realtek and Beken chips. Supports multiple chip families and auto-generated components.
-
-## 4. Coding Conventions & Style Guide
-
-*   **Formatting:**
-    *   **Python:** Uses `ruff` and `flake8` for linting and formatting. Configuration is in `pyproject.toml`.
-    *   **C++:** Uses `clang-format` for formatting. Configuration is in `.clang-format`.
-
-*   **Naming Conventions:**
-    *   **Python:** Follows PEP 8. Use clear, descriptive names following snake_case.
-    *   **C++:** Follows the Google C++ Style Guide.
-
-*   **Component Structure:**
-    *   **Standard Files:**
-        ```
-        components/[component_name]/
-        ├── __init__.py          # Component configuration schema and code generation
-        ├── [component].h        # C++ header file (if needed)
-        ├── [component].cpp      # C++ implementation (if needed)
-        └── [platform]/          # Platform-specific implementations
-            ├── __init__.py      # Platform-specific configuration
-            ├── [platform].h     # Platform C++ header
-            └── [platform].cpp   # Platform C++ implementation
-        ```
-
-    *   **Component Metadata:**
-        - `DEPENDENCIES`: List of required components
-        - `AUTO_LOAD`: Components to automatically load
-        - `CONFLICTS_WITH`: Incompatible components
-        - `CODEOWNERS`: GitHub usernames responsible for maintenance
-        - `MULTI_CONF`: Whether multiple instances are allowed
-
-*   **Code Generation & Common Patterns:**
-    *   **Configuration Schema Pattern:**
-        ```python
-        import esphome.codegen as cg
-        import esphome.config_validation as cv
-        from esphome.const import CONF_KEY, CONF_ID
-
-        CONF_PARAM = "param"  # A constant that does not yet exist in esphome/const.py
-
-        my_component_ns = cg.esphome_ns.namespace("my_component")
-        MyComponent = my_component_ns.class_("MyComponent", cg.Component)
-
-        CONFIG_SCHEMA = cv.Schema({
-            cv.GenerateID(): cv.declare_id(MyComponent),
-            cv.Required(CONF_KEY): cv.string,
-            cv.Optional(CONF_PARAM, default=42): cv.int_,
-        }).extend(cv.COMPONENT_SCHEMA)
-
-        async def to_code(config):
-            var = cg.new_Pvariable(config[CONF_ID])
-            await cg.register_component(var, config)
-            cg.add(var.set_key(config[CONF_KEY]))
-            cg.add(var.set_param(config[CONF_PARAM]))
-        ```
-
-    *   **C++ Class Pattern:**
-        ```cpp
-        namespace esphome {
-        namespace my_component {
-
-        class MyComponent : public Component {
-         public:
-          void setup() override;
-          void loop() override;
-          void dump_config() override;
-
-          void set_key(const std::string &key) { this->key_ = key; }
-          void set_param(int param) { this->param_ = param; }
-
-         protected:
-          std::string key_;
-          int param_{0};
-        };
-
-        }  // namespace my_component
-        }  // namespace esphome
-        ```
-
-    *   **Common Component Examples:**
-        - **Sensor:**
-          ```python
-          from esphome.components import sensor
-          CONFIG_SCHEMA = sensor.sensor_schema(MySensor).extend(cv.polling_component_schema("60s"))
-          async def to_code(config):
-              var = await sensor.new_sensor(config)
-              await cg.register_component(var, config)
-          ```
-
-        - **Binary Sensor:**
-          ```python
-          from esphome.components import binary_sensor
-          CONFIG_SCHEMA = binary_sensor.binary_sensor_schema().extend({ ... })
-          async def to_code(config):
-              var = await binary_sensor.new_binary_sensor(config)
-          ```
-
-        - **Switch:**
-          ```python
-          from esphome.components import switch
-          CONFIG_SCHEMA = switch.switch_schema().extend({ ... })
-          async def to_code(config):
-              var = await switch.new_switch(config)
-          ```
-
-*   **Configuration Validation:**
-    *   **Common Validators:** `cv.int_`, `cv.float_`, `cv.string`, `cv.boolean`, `cv.int_range(min=0, max=100)`, `cv.positive_int`, `cv.percentage`.
-    *   **Complex Validation:** `cv.All(cv.string, cv.Length(min=1, max=50))`, `cv.Any(cv.int_, cv.string)`.
-    *   **Platform-Specific:** `cv.only_on(["esp32", "esp8266"])`, `esp32.only_on_variant(...)`, `cv.only_on_esp32`, `cv.only_on_esp8266`, `cv.only_on_rp2040`.
-    *   **Framework-Specific:** `cv.only_with_framework(...)`, `cv.only_with_arduino`, `cv.only_with_esp_idf`.
-    *   **Schema Extensions:**
-        ```python
-        CONFIG_SCHEMA = cv.Schema({ ... })
-         .extend(cv.COMPONENT_SCHEMA)
-         .extend(uart.UART_DEVICE_SCHEMA)
-         .extend(i2c.i2c_device_schema(0x48))
-         .extend(spi.spi_device_schema(cs_pin_required=True))
-        ```
-
-## 5. Key Files & Entrypoints
-
-*   **Main Entrypoint(s):** `esphome/__main__.py` is the main entrypoint for the ESPHome command-line interface.
-*   **Configuration:**
-    *   `pyproject.toml`: Defines the Python project metadata and dependencies.
-    *   `platformio.ini`: Configures the PlatformIO build environments for different microcontrollers.
-    *   `.pre-commit-config.yaml`: Configures the pre-commit hooks for linting and formatting.
-*   **CI/CD Pipeline:** Defined in `.github/workflows`.
-*   **Static Analysis & Development:**
-    *   `esphome/core/defines.h`: A comprehensive header file containing all `#define` directives that can be added by components using `cg.add_define()` in Python. This file is used exclusively for development, static analysis tools, and CI testing - it is not used during runtime compilation. When developing components that add new defines, they must be added to this file to ensure proper IDE support and static analysis coverage. The file includes feature flags, build configurations, and platform-specific defines that help static analyzers understand the complete codebase without needing to compile for specific platforms.
-
-## 6. Development & Testing Workflow
-
-*   **Local Development Environment:** Use the provided Docker container or create a Python virtual environment and install dependencies from `requirements_dev.txt`.
-*   **Running Commands:** Use the `script/run-in-env.py` script to execute commands within the project's virtual environment. For example, to run the linter: `python3 script/run-in-env.py pre-commit run`.
-*   **Testing:**
-    *   **Python:** Run unit tests with `pytest`.
-    *   **C++:** Use `clang-tidy` for static analysis.
-    *   **Component Tests:** YAML-based compilation tests are located in `tests/`. The structure is as follows:
-        ```
-        tests/
-        ├── test_build_components/ # Base test configurations
-        └── components/[component]/ # Component-specific tests
-        ```
-        Run them using `script/test_build_components`. Use `-c <component>` to test specific components and `-t <target>` for specific platforms.
-    *   **Testing All Components Together:** To verify that all components can be tested together without ID conflicts or configuration issues, use:
-        ```bash
-        ./script/test_component_grouping.py -e config --all
-        ```
-        This tests all components in a single build to catch conflicts that might not appear when testing components individually. Use `-e config` for fast configuration validation, or `-e compile` for full compilation testing.
-*   **Debugging and Troubleshooting:**
-    *   **Debug Tools:**
-        - `esphome config <file>.yaml` to validate configuration.
-        - `esphome compile <file>.yaml` to compile without uploading.
-        - Check the Dashboard for real-time logs.
-        - Use component-specific debug logging.
-    *   **Common Issues:**
-        - **Import Errors**: Check component dependencies and `PYTHONPATH`.
-        - **Validation Errors**: Review configuration schema definitions.
-        - **Build Errors**: Check platform compatibility and library versions.
-        - **Runtime Errors**: Review generated C++ code and component logic.
-
-## 7. Specific Instructions for AI Collaboration
-
-*   **Contribution Workflow (Pull Request Process):**
-    1.  **Fork & Branch:** Create a new branch in your fork.
-    2.  **Make Changes:** Adhere to all coding conventions and patterns.
-    3.  **Test:** Create component tests for all supported platforms and run the full test suite locally.
-    4.  **Lint:** Run `pre-commit` to ensure code is compliant.
-    5.  **Commit:** Commit your changes. There is no strict format for commit messages.
-    6.  **Pull Request:** Submit a PR against the `dev` branch. The Pull Request title should have a prefix of the component being worked on (e.g., `[display] Fix bug`, `[abc123] Add new component`). Update documentation, examples, and add `CODEOWNERS` entries as needed. Pull requests should always be made with the PULL_REQUEST_TEMPLATE.md template filled out correctly.
-
-*   **Documentation Contributions:**
-    *   Documentation is hosted in the separate `esphome/esphome-docs` repository.
-    *   The contribution workflow is the same as for the codebase.
-
-*   **Best Practices:**
-    *   **Component Development:** Keep dependencies minimal, provide clear error messages, and write comprehensive docstrings and tests.
-    *   **Code Generation:** Generate minimal and efficient C++ code. Validate all user inputs thoroughly. Support multiple platform variations.
-    *   **Configuration Design:** Aim for simplicity with sensible defaults, while allowing for advanced customization.
-
-*   **Security:** Be mindful of security when making changes to the API, web server, or any other network-related code. Do not hardcode secrets or keys.
-
-*   **Dependencies & Build System Integration:**
-    *   **Python:** When adding a new Python dependency, add it to the appropriate `requirements*.txt` file and `pyproject.toml`.
-    *   **C++ / PlatformIO:** When adding a new C++ dependency, add it to `platformio.ini` and use `cg.add_library`.
-    *   **Build Flags:** Use `cg.add_build_flag(...)` to add compiler flags.

.clang-tidy

@@ -5,24 +5,30 @@ Checks: >-
   -altera-*,
   -android-*,
   -boost-*,
+  -bugprone-derived-method-shadowing-base-method,
   -bugprone-easily-swappable-parameters,
   -bugprone-implicit-widening-of-multiplication-result,
+  -bugprone-invalid-enum-default-initialization,
   -bugprone-multi-level-implicit-pointer-conversion,
   -bugprone-narrowing-conversions,
+  -bugprone-tagged-union-member-count,
   -bugprone-signed-char-misuse,
   -bugprone-switch-missing-default-case,
   -cert-dcl50-cpp,
   -cert-err33-c,
   -cert-err58-cpp,
+  -cert-int09-c,
   -cert-oop57-cpp,
   -cert-str34-c,
   -clang-analyzer-optin.core.EnumCastOutOfRange,
   -clang-analyzer-optin.cplusplus.UninitializedObject,
   -clang-analyzer-osx.*,
+  -clang-analyzer-security.ArrayBound,
   -clang-diagnostic-delete-abstract-non-virtual-dtor,
   -clang-diagnostic-delete-non-abstract-non-virtual-dtor,
   -clang-diagnostic-deprecated-declarations,
   -clang-diagnostic-ignored-optimization-argument,
+  -clang-diagnostic-missing-designated-field-initializers,
   -clang-diagnostic-missing-field-initializers,
   -clang-diagnostic-shadow-field,
   -clang-diagnostic-unused-const-variable,
@@ -42,6 +48,7 @@ Checks: >-
   -cppcoreguidelines-owning-memory,
   -cppcoreguidelines-prefer-member-initializer,
   -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
+  -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access,
   -cppcoreguidelines-pro-bounds-constant-array-index,
   -cppcoreguidelines-pro-bounds-pointer-arithmetic,
   -cppcoreguidelines-pro-type-const-cast,
@@ -54,12 +61,13 @@ Checks: >-
   -cppcoreguidelines-rvalue-reference-param-not-moved,
   -cppcoreguidelines-special-member-functions,
   -cppcoreguidelines-use-default-member-init,
+  -cppcoreguidelines-use-enum-class,
   -cppcoreguidelines-virtual-class-destructor,
+  -fuchsia-default-arguments-calls,
+  -fuchsia-default-arguments-declarations,
   -fuchsia-multiple-inheritance,
   -fuchsia-overloaded-operator,
   -fuchsia-statically-constructed-objects,
-  -fuchsia-default-arguments-declarations,
-  -fuchsia-default-arguments-calls,
   -google-build-using-namespace,
   -google-explicit-constructor,
   -google-readability-braces-around-statements,
@@ -71,49 +79,64 @@ Checks: >-
   -llvm-else-after-return,
   -llvm-header-guard,
   -llvm-include-order,
+  -llvm-prefer-static-over-anonymous-namespace,
   -llvm-qualified-auto,
+  -llvm-use-ranges,
   -llvmlibc-*,
   -misc-const-correctness,
   -misc-include-cleaner,
+  -misc-multiple-inheritance,
   -misc-no-recursion,
   -misc-non-private-member-variables-in-classes,
+  -misc-override-with-different-visibility,
   -misc-unused-parameters,
   -misc-use-anonymous-namespace,
+  -misc-use-internal-linkage,
   -modernize-avoid-bind,
+  -modernize-avoid-variadic-functions,
   -modernize-avoid-c-arrays,
-  -modernize-concat-nested-namespaces,
+  -modernize-avoid-c-style-cast,
   -modernize-macro-to-enum,
   -modernize-return-braced-init-list,
   -modernize-type-traits,
   -modernize-use-auto,
   -modernize-use-constraints,
   -modernize-use-default-member-init,
+  -modernize-use-designated-initializers,
   -modernize-use-equals-default,
+  -modernize-use-integer-sign-comparison,
   -modernize-use-nodiscard,
   -modernize-use-nullptr,
-  -modernize-use-nodiscard,
-  -modernize-use-nullptr,
+  -modernize-use-ranges,
   -modernize-use-trailing-return-type,
   -mpi-*,
   -objc-*,
   -performance-enum-size,
+  -portability-avoid-pragma-once,
+  -portability-template-virtual-member-function,
+  -readability-ambiguous-smartptr-reset-call,
   -readability-avoid-nested-conditional-operator,
   -readability-container-contains,
   -readability-container-data-pointer,
   -readability-convert-member-functions-to-static,
   -readability-else-after-return,
+  -readability-enum-initial-value,
   -readability-function-cognitive-complexity,
   -readability-implicit-bool-conversion,
   -readability-isolate-declaration,
   -readability-magic-numbers,
   -readability-make-member-function-const,
+  -readability-math-missing-parentheses,
   -readability-named-parameter,
   -readability-redundant-casting,
   -readability-redundant-inline-specifier,
   -readability-redundant-member-init,
-  -readability-redundant-string-init,
+  -readability-redundant-parentheses,
+  -readability-redundant-typename,
   -readability-uppercase-literal-suffix,
   -readability-use-anyofallof,
+  -readability-use-std-min-max,
+  -readability-use-concise-preprocessor-directives,
 WarningsAsErrors: '*'
 FormatStyle:     google
 CheckOptions:

.clang-tidy.hash

@@ -1 +1 @@
-049d60eed541730efaa4c0dc5d337b4287bf29b6daa350b5dfc1f23915f1c52f
+593fd53fa09944a59af3f38521e31d87fe10b60326b8d82bb76413c5149b312c

.claude/skills/pr-workflow/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pr-workflow
+description: Create pull requests for esphome. Use when creating PRs, submitting changes, or preparing contributions.
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# ESPHome PR Workflow
+
+When creating a pull request for esphome, follow these steps:
+
+## 1. Create Branch from Upstream
+
+Always base your branch on **upstream** (not origin/fork) to ensure you have the latest code:
+
+```bash
+git fetch upstream
+git checkout -b <branch-name> upstream/dev
+```
+
+## 2. Read the PR Template
+
+Before creating a PR, read `.github/PULL_REQUEST_TEMPLATE.md` to understand required fields.
+
+## 3. Create the PR
+
+Use `gh pr create` with the **full template** filled in. Never skip or abbreviate sections.
+
+Required fields:
+- **What does this implement/fix?**: Brief description of changes
+- **Types of changes**: Check ONE appropriate box (Bugfix, New feature, Breaking change, etc.)
+- **Related issue**: Use `fixes <link>` syntax if applicable
+- **Pull request in esphome-docs**: Link if docs are needed
+- **Test Environment**: Check platforms you tested on
+- **Example config.yaml**: Include working example YAML
+- **Checklist**: Verify code is tested and tests added
+
+## 4. Example PR Body
+
+```markdown
+# What does this implement/fix?
+
+<describe your changes here>
+
+## Types of changes
+
+- [ ] Bugfix (non-breaking change which fixes an issue)
+- [x] 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)
+- [ ] Code quality improvements to existing code or addition of tests
+- [ ] Other
+
+**Related issue or feature (if applicable):**
+
+- fixes https://github.com/esphome/esphome/issues/XXX
+
+**Pull request in [esphome-docs](https://github.com/esphome/esphome-docs) with documentation (if applicable):**
+
+- esphome/esphome-docs#XXX
+
+## Test Environment
+
+- [x] ESP32
+- [x] ESP32 IDF
+- [ ] ESP8266
+- [ ] RP2040
+- [ ] BK72xx
+- [ ] RTL87xx
+- [ ] LN882x
+- [ ] nRF52840
+
+## Example entry for `config.yaml`:
+
+```yaml
+# Example config.yaml
+component_name:
+  id: my_component
+  option: value
+```
+
+## Checklist:
+  - [x] The code change is tested and works locally.
+  - [x] Tests have been added to verify that the new code works (under `tests/` folder).
+
+If user exposed functionality or configuration variables are added/changed:
+  - [ ] Documentation added/updated in [esphome-docs](https://github.com/esphome/esphome-docs).
+```
+
+## 5. Push and Create PR
+
+```bash
+git push -u origin <branch-name>
+gh pr create --repo esphome/esphome --base dev --title "[component] Brief description"
+```
+
+Title should be prefixed with the component name in brackets, e.g. `[safe_mode] Add feature`.

.coveragerc

@@ -1,4 +1,5 @@
 [run]
 omit =
     esphome/components/*
+    esphome/analyze_memory/*
     tests/integration/*

.devcontainer/devcontainer.json

@@ -12,7 +12,7 @@
     "--privileged",
     "-e",
     "GIT_EDITOR=code --wait"
-    // uncomment and edit the path in order to pass though local USB serial to the conatiner
+    // uncomment and edit the path in order to pass through local USB serial to the container
     // , "--device=/dev/ttyACM0"
   ],
   "appPort": 6052,

.dockerignore

@@ -115,4 +115,4 @@ examples/
 Dockerfile
 .git/
 tests/
-.*
+.?*

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,7 +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)
+- [ ] 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
 
@@ -23,9 +25,10 @@
 - [ ] ESP32
 - [ ] ESP32 IDF
 - [ ] ESP8266
-- [ ] RP2040
+- [ ] RP2040/RP2350
 - [ ] BK72xx
 - [ ] RTL87xx
+- [ ] LN882x
 - [ ] nRF52840
 
 ## Example entry for `config.yaml`:

.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@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.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@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
       env:
         DOCKER_BUILD_SUMMARY: false
         DOCKER_BUILD_RECORD_UPLOAD: false

.github/actions/restore-python/action.yml

@@ -17,12 +17,12 @@ runs:
   steps:
     - name: Set up Python ${{ inputs.python-version }}
       id: python
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       with:
         python-version: ${{ inputs.python-version }}
     - name: Restore Python virtual environment
       id: cache-venv
-      uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+      uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
       with:
         path: venv
         # yamllint disable-line rule:line-length

.github/copilot-instructions.md

@@ -1 +1 @@
-../.ai/instructions.md
+../AGENTS.md

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

@@ -0,0 +1,41 @@
+// Constants and markers for PR auto-labeling
+module.exports = {
+  BOT_COMMENT_MARKER: '<!-- auto-label-pr-bot -->',
+  CODEOWNERS_MARKER: '<!-- codeowners-request -->',
+  TOO_BIG_MARKER: '<!-- too-big-request -->',
+  DEPRECATED_COMPONENT_MARKER: '<!-- deprecated-component-request -->',
+  ORG_FORK_MARKER: '<!-- maintainer-access-warning -->',
+
+  MANAGED_LABELS: [
+    'new-component',
+    'new-platform',
+    'new-target-platform',
+    'merging-to-release',
+    'merging-to-beta',
+    'chained-pr',
+    'core',
+    'small-pr',
+    'medium-pr',
+    'dashboard',
+    'github-actions',
+    'by-code-owner',
+    'has-tests',
+    'needs-tests',
+    'needs-docs',
+    'needs-codeowners',
+    'too-big',
+    'labeller-recheck',
+    'bugfix',
+    'new-feature',
+    'breaking-change',
+    'developer-breaking-change',
+    'undocumented-api-change',
+    'code-quality',
+    'deprecated-component'
+  ],
+
+  DOCS_PR_PATTERNS: [
+    /https:\/\/github\.com\/esphome\/esphome-docs\/pull\/\d+/,
+    /esphome\/esphome-docs#\d+/
+  ]
+};

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

@@ -0,0 +1,395 @@
+const { DOCS_PR_PATTERNS } = require('./constants');
+const {
+  COMPONENT_REGEX,
+  detectComponents,
+  hasCoreChanges,
+  hasDashboardChanges,
+  hasGitHubActionsChanges,
+} = require('../detect-tags');
+const { loadCodeowners, getEffectiveOwners } = require('../codeowners');
+
+// Top-level `CONFIG_SCHEMA = ...` (assignment) or `CONFIG_SCHEMA: ConfigType = ...` (annotation).
+// Ruff/Black enforce exactly one space around `=` and no space before `:`,
+// so we can match strictly: `CONFIG_SCHEMA ` or `CONFIG_SCHEMA:`.
+const CONFIG_SCHEMA_REGEX = /^CONFIG_SCHEMA[ :]/m;
+
+// Fetch a file's contents from the PR head SHA via the GitHub API.
+// The auto-label workflow runs on `pull_request_target`, which checks out the
+// base branch — files added by the PR don't exist in the workspace, so we have
+// to fetch them from the head SHA. Returns null if the file can't be fetched.
+async function fetchPrFileContent(github, context, path) {
+  try {
+    const { owner, repo } = context.repo;
+    const { data } = await github.rest.repos.getContent({
+      owner,
+      repo,
+      path,
+      ref: context.payload.pull_request.head.sha,
+    });
+    return Buffer.from(data.content, 'base64').toString('utf8');
+  } catch (error) {
+    console.log(`Failed to fetch ${path} from PR head:`, error.message);
+    return null;
+  }
+}
+
+// Strategy: Merge branch detection
+async function detectMergeBranch(context) {
+  const labels = new Set();
+  const baseRef = context.payload.pull_request.base.ref;
+
+  if (baseRef === 'release') {
+    labels.add('merging-to-release');
+  } else if (baseRef === 'beta') {
+    labels.add('merging-to-beta');
+  } else if (baseRef !== 'dev') {
+    labels.add('chained-pr');
+  }
+
+  return labels;
+}
+
+// Strategy: Component and platform labeling
+async function detectComponentPlatforms(changedFiles, apiData) {
+  const labels = new Set();
+  const targetPlatformRegex = new RegExp(`^esphome\/components\/(${apiData.targetPlatforms.join('|')})/`);
+
+  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]}`);
+    }
+  }
+
+  return labels;
+}
+
+// Strategy: New component detection
+async function detectNewComponents(github, context, prFiles) {
+  const labels = new Set();
+  let hasYamlLoadable = false;
+  const addedFiles = prFiles.filter(file => file.status === 'added').map(file => file.filename);
+
+  for (const file of addedFiles) {
+    const componentMatch = file.match(/^esphome\/components\/([^\/]+)\/__init__\.py$/);
+    if (!componentMatch) continue;
+
+    labels.add('new-component');
+    const content = await fetchPrFileContent(github, context, file);
+    if (content === null) {
+      // Safe default: assume YAML-loadable so needs-docs behaviour is unchanged on fetch failure
+      hasYamlLoadable = true;
+      continue;
+    }
+    if (content.includes('IS_TARGET_PLATFORM = True')) {
+      labels.add('new-target-platform');
+    }
+    if (CONFIG_SCHEMA_REGEX.test(content)) {
+      hasYamlLoadable = true;
+    }
+  }
+
+  return { labels, hasYamlLoadable };
+}
+
+// Strategy: New platform detection
+async function detectNewPlatforms(github, context, prFiles, apiData) {
+  const labels = new Set();
+  let hasYamlLoadable = false;
+  const addedFiles = prFiles.filter(file => file.status === 'added').map(file => file.filename);
+
+  const platformPathPatterns = [
+    /^esphome\/components\/([^\/]+)\/([^\/]+)\.py$/,
+    /^esphome\/components\/([^\/]+)\/([^\/]+)\/__init__\.py$/,
+  ];
+
+  for (const file of addedFiles) {
+    for (const re of platformPathPatterns) {
+      const match = file.match(re);
+      if (!match) continue;
+      const platform = match[2];
+      if (!apiData.platformComponents.includes(platform)) break;
+
+      labels.add('new-platform');
+      const content = await fetchPrFileContent(github, context, file);
+      if (content === null) {
+        // Safe default: assume YAML-loadable so needs-docs behaviour is unchanged on fetch failure
+        hasYamlLoadable = true;
+      } else if (CONFIG_SCHEMA_REGEX.test(content)) {
+        hasYamlLoadable = true;
+      }
+      break;
+    }
+  }
+
+  return { labels, hasYamlLoadable };
+}
+
+// Strategy: Core files detection
+async function detectCoreChanges(changedFiles) {
+  const labels = new Set();
+  if (hasCoreChanges(changedFiles)) {
+    labels.add('core');
+  }
+  return labels;
+}
+
+// Strategy: PR size detection
+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) {
+    labels.add('small-pr');
+    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);
+  const testDeletions = prFiles
+    .filter(file => file.filename.startsWith('tests/'))
+    .reduce((sum, file) => sum + (file.deletions || 0), 0);
+
+  const nonTestChanges = (totalAdditions - testAdditions) - (totalDeletions - testDeletions);
+
+  // Don't add too-big if mega-pr label is already present
+  if (nonTestChanges > TOO_BIG_THRESHOLD && !isMegaPR) {
+    labels.add('too-big');
+  }
+
+  return labels;
+}
+
+// Strategy: Dashboard changes
+async function detectDashboardChanges(changedFiles) {
+  const labels = new Set();
+  if (hasDashboardChanges(changedFiles)) {
+    labels.add('dashboard');
+  }
+  return labels;
+}
+
+// Strategy: GitHub Actions changes
+async function detectGitHubActionsChanges(changedFiles) {
+  const labels = new Set();
+  if (hasGitHubActionsChanges(changedFiles)) {
+    labels.add('github-actions');
+  }
+  return labels;
+}
+
+// Strategy: Code owner detection
+async function detectCodeOwner(github, context, changedFiles) {
+  const labels = new Set();
+
+  try {
+    const codeownersPatterns = loadCodeowners();
+    const prAuthor = context.payload.pull_request.user.login;
+
+    // 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);
+  }
+
+  return labels;
+}
+
+// Strategy: Test detection
+async function detectTests(changedFiles) {
+  const labels = new Set();
+  const testFiles = changedFiles.filter(file => file.startsWith('tests/'));
+
+  if (testFiles.length > 0) {
+    labels.add('has-tests');
+  }
+
+  return labels;
+}
+
+// Strategy: PR Template Checkbox detection
+async function detectPRTemplateCheckboxes(context) {
+  const labels = new Set();
+  const prBody = context.payload.pull_request.body || '';
+
+  console.log('Checking PR template checkboxes...');
+
+  // Check for checked checkboxes in the "Types of changes" section
+  const checkboxPatterns = [
+    { pattern: /- \[x\] Bugfix \(non-breaking change which fixes an issue\)/i, label: 'bugfix' },
+    { 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' }
+  ];
+
+  for (const { pattern, label } of checkboxPatterns) {
+    if (pattern.test(prBody)) {
+      console.log(`Found checked checkbox for: ${label}`);
+      labels.add(label);
+    }
+  }
+
+  return labels;
+}
+
+// Strategy: Deprecated component detection
+async function detectDeprecatedComponents(github, context, changedFiles) {
+  const labels = new Set();
+  const deprecatedInfo = [];
+  const { owner, repo } = context.repo;
+
+  // Compile regex once for better performance
+  const componentFileRegex = COMPONENT_REGEX;
+
+  // Get files that are modified or added in components directory
+  const componentFiles = changedFiles.filter(file => componentFileRegex.test(file));
+
+  if (componentFiles.length === 0) {
+    return { labels, deprecatedInfo };
+  }
+
+  // Extract unique component names using the same regex
+  const components = new Set();
+  for (const file of componentFiles) {
+    const match = file.match(componentFileRegex);
+    if (match) {
+      components.add(match[1]);
+    }
+  }
+
+  // Get base branch ref to check if deprecation already exists for the component
+  // This prevents flagging a PR that simply adds deprecation
+  const baseRef = context.payload.pull_request.base.ref;
+
+  // Check each component's __init__.py for DEPRECATED_COMPONENT constant
+  for (const component of components) {
+    const initFile = `esphome/components/${component}/__init__.py`;
+    try {
+      // Fetch file content from base branch using GitHub API
+      const { data: fileData } = await github.rest.repos.getContent({
+        owner,
+        repo,
+        path: initFile,
+        ref: baseRef
+      });
+
+      // Decode base64 content
+      const content = Buffer.from(fileData.content, 'base64').toString('utf8');
+
+      // Look for DEPRECATED_COMPONENT = "message" or DEPRECATED_COMPONENT = 'message'
+      // Support single quotes, double quotes, and triple quotes (for multiline)
+      const doubleQuoteMatch = content.match(/DEPRECATED_COMPONENT\s*=\s*"""([\s\S]*?)"""/s) ||
+                              content.match(/DEPRECATED_COMPONENT\s*=\s*"((?:[^"\\]|\\.)*)"/);
+      const singleQuoteMatch = content.match(/DEPRECATED_COMPONENT\s*=\s*'''([\s\S]*?)'''/s) ||
+                              content.match(/DEPRECATED_COMPONENT\s*=\s*'((?:[^'\\]|\\.)*)'/);
+      const deprecatedMatch = doubleQuoteMatch || singleQuoteMatch;
+
+      if (deprecatedMatch) {
+        labels.add('deprecated-component');
+        deprecatedInfo.push({
+          component: component,
+          message: deprecatedMatch[1].trim()
+        });
+        console.log(`Found deprecated component: ${component}`);
+      }
+    } catch (error) {
+      // Only log if it's not a simple "file not found" error (404)
+      if (error.status !== 404) {
+        console.log(`Error reading ${initFile}:`, error.message);
+      }
+    }
+  }
+
+  return { labels, deprecatedInfo };
+}
+
+// Strategy: Detect when maintainers cannot modify the PR branch
+function detectMaintainerAccess(context) {
+  const pr = context.payload.pull_request;
+
+  // Only relevant for cross-repo PRs (forks)
+  if (!pr.head.repo || pr.head.repo.full_name === pr.base.repo.full_name) {
+    return null;
+  }
+
+  if (pr.maintainer_can_modify) {
+    return null;
+  }
+
+  const isOrgFork = pr.head.repo.owner.type === 'Organization';
+  console.log(`Maintainer cannot modify PR branch (${isOrgFork ? 'org fork: ' + pr.head.repo.owner.login : 'user disabled'})`);
+  return { isOrgFork, orgName: pr.head.repo.owner.login };
+}
+
+// Strategy: Requirements detection
+async function detectRequirements(allLabels, prFiles, context, hasYamlLoadable) {
+  const labels = new Set();
+
+  // Check for missing tests
+  if ((allLabels.has('new-component') || allLabels.has('new-platform') || allLabels.has('new-feature')) && !allLabels.has('has-tests')) {
+    labels.add('needs-tests');
+  }
+
+  // Check for missing docs.
+  // `new-feature` (PR-body checkbox) always counts. `new-component` / `new-platform`
+  // only count when at least one newly added file defines a top-level CONFIG_SCHEMA,
+  // i.e. the new component/platform is actually loadable from YAML.
+  const docsEligible =
+    allLabels.has('new-feature') ||
+    ((allLabels.has('new-component') || allLabels.has('new-platform')) && hasYamlLoadable);
+
+  if (docsEligible) {
+    const prBody = context.payload.pull_request.body || '';
+    const hasDocsLink = DOCS_PR_PATTERNS.some(pattern => pattern.test(prBody));
+
+    if (!hasDocsLink) {
+      labels.add('needs-docs');
+    }
+  }
+
+  // Check for missing CODEOWNERS
+  if (allLabels.has('new-component')) {
+    const codeownersModified = prFiles.some(file =>
+      file.filename === 'CODEOWNERS' &&
+      (file.status === 'modified' || file.status === 'added') &&
+      (file.additions || 0) > 0
+    );
+
+    if (!codeownersModified) {
+      labels.add('needs-codeowners');
+    }
+  }
+
+  return labels;
+}
+
+module.exports = {
+  detectMergeBranch,
+  detectComponentPlatforms,
+  detectNewComponents,
+  detectNewPlatforms,
+  detectCoreChanges,
+  detectPRSize,
+  detectDashboardChanges,
+  detectGitHubActionsChanges,
+  detectCodeOwner,
+  detectTests,
+  detectPRTemplateCheckboxes,
+  detectDeprecatedComponents,
+  detectMaintainerAccess,
+  detectRequirements
+};

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

@@ -0,0 +1,201 @@
+const { MANAGED_LABELS } = require('./constants');
+const {
+  detectMergeBranch,
+  detectComponentPlatforms,
+  detectNewComponents,
+  detectNewPlatforms,
+  detectCoreChanges,
+  detectPRSize,
+  detectDashboardChanges,
+  detectGitHubActionsChanges,
+  detectCodeOwner,
+  detectTests,
+  detectPRTemplateCheckboxes,
+  detectDeprecatedComponents,
+  detectMaintainerAccess,
+  detectRequirements
+} = require('./detectors');
+const { handleReviews, handleMaintainerAccessComment } = require('./reviews');
+const { applyLabels, removeOldLabels } = require('./labels');
+
+// Fetch API data
+async function fetchApiData() {
+  try {
+    const response = await fetch('https://data.esphome.io/components.json');
+    const componentsData = await response.json();
+    return {
+      targetPlatforms: componentsData.target_platforms || [],
+      platformComponents: componentsData.platform_components || []
+    };
+  } catch (error) {
+    console.log('Failed to fetch components data from API:', error.message);
+    return { targetPlatforms: [], platformComponents: [] };
+  }
+}
+
+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);
+
+  // Global state
+  const { owner, repo } = context.repo;
+  const pr_number = context.issue.number;
+
+  // Get current labels and PR data
+  const { data: currentLabelsData } = await github.rest.issues.listLabelsOnIssue({
+    owner,
+    repo,
+    issue_number: pr_number
+  });
+  const currentLabels = currentLabelsData.map(label => label.name);
+  const managedLabels = currentLabels.filter(label =>
+    label.startsWith('component: ') || MANAGED_LABELS.includes(label)
+  );
+
+  // Check for mega-PR early - if present, skip most automatic labeling
+  const isMegaPR = currentLabels.includes('mega-pr');
+
+  // Get all PR files with automatic pagination
+  const prFiles = await github.paginate(
+    github.rest.pulls.listFiles,
+    {
+      owner,
+      repo,
+      pull_number: pr_number
+    }
+  );
+
+  // Calculate data from PR files
+  const changedFiles = prFiles.map(file => file.filename);
+  const totalAdditions = prFiles.reduce((sum, file) => sum + (file.additions || 0), 0);
+  const totalDeletions = prFiles.reduce((sum, file) => sum + (file.deletions || 0), 0);
+  const totalChanges = totalAdditions + totalDeletions;
+
+  console.log('Current labels:', currentLabels.join(', '));
+  console.log('Changed files:', changedFiles.length);
+  console.log('Total changes:', totalChanges);
+  if (isMegaPR) {
+    console.log('Mega-PR detected - applying limited labeling logic');
+  }
+
+  // Fetch API data
+  const apiData = await fetchApiData();
+  const baseRef = context.payload.pull_request.base.ref;
+
+  // Early exit for release and beta branches only
+  if (baseRef === 'release' || baseRef === 'beta') {
+    const branchLabels = await detectMergeBranch(context);
+    const finalLabels = Array.from(branchLabels);
+
+    console.log('Computed labels (merge branch only):', finalLabels.join(', '));
+
+    // Apply labels
+    await applyLabels(github, context, finalLabels);
+
+    // Remove old managed labels
+    await removeOldLabels(github, context, managedLabels, finalLabels);
+
+    return;
+  }
+
+  // Run all strategies
+  const [
+    branchLabels,
+    componentLabels,
+    newComponentResult,
+    newPlatformResult,
+    coreLabels,
+    sizeLabels,
+    dashboardLabels,
+    actionsLabels,
+    codeOwnerLabels,
+    testLabels,
+    checkboxLabels,
+    deprecatedResult,
+    maintainerAccess
+  ] = await Promise.all([
+    detectMergeBranch(context),
+    detectComponentPlatforms(changedFiles, apiData),
+    detectNewComponents(github, context, prFiles),
+    detectNewPlatforms(github, context, prFiles, apiData),
+    detectCoreChanges(changedFiles),
+    detectPRSize(prFiles, totalAdditions, totalDeletions, totalChanges, isMegaPR, SMALL_PR_THRESHOLD, MEDIUM_PR_THRESHOLD, TOO_BIG_THRESHOLD),
+    detectDashboardChanges(changedFiles),
+    detectGitHubActionsChanges(changedFiles),
+    detectCodeOwner(github, context, changedFiles),
+    detectTests(changedFiles),
+    detectPRTemplateCheckboxes(context),
+    detectDeprecatedComponents(github, context, changedFiles),
+    detectMaintainerAccess(context)
+  ]);
+
+  // Extract new-component / new-platform results
+  const newComponentLabels = newComponentResult.labels;
+  const newPlatformLabels = newPlatformResult.labels;
+  // Eligible for needs-docs only if any newly added component or platform file
+  // defines a top-level CONFIG_SCHEMA (i.e. is actually loadable from YAML).
+  const hasYamlLoadable = newComponentResult.hasYamlLoadable || newPlatformResult.hasYamlLoadable;
+
+  // Extract deprecated component info
+  const deprecatedLabels = deprecatedResult.labels;
+  const deprecatedInfo = deprecatedResult.deprecatedInfo;
+
+  // Combine all labels
+  const allLabels = new Set([
+    ...branchLabels,
+    ...componentLabels,
+    ...newComponentLabels,
+    ...newPlatformLabels,
+    ...coreLabels,
+    ...sizeLabels,
+    ...dashboardLabels,
+    ...actionsLabels,
+    ...codeOwnerLabels,
+    ...testLabels,
+    ...checkboxLabels,
+    ...deprecatedLabels
+  ]);
+
+  // Detect requirements based on all other labels
+  const requirementLabels = await detectRequirements(allLabels, prFiles, context, hasYamlLoadable);
+  for (const label of requirementLabels) {
+    allLabels.add(label);
+  }
+
+  let finalLabels = Array.from(allLabels);
+
+  // For mega-PRs, exclude component labels if there are too many
+  if (isMegaPR) {
+    const componentLabels = finalLabels.filter(label => label.startsWith('component: '));
+    if (componentLabels.length > COMPONENT_LABEL_THRESHOLD) {
+      finalLabels = finalLabels.filter(label => !label.startsWith('component: '));
+      console.log(`Mega-PR detected - excluding ${componentLabels.length} component labels (threshold: ${COMPONENT_LABEL_THRESHOLD})`);
+    }
+  }
+
+  // Handle too many labels (only for non-mega PRs)
+  const tooManyLabels = finalLabels.length > MAX_LABELS;
+  const originalLabelCount = finalLabels.length;
+
+  if (tooManyLabels && !isMegaPR && !finalLabels.includes('too-big')) {
+    finalLabels = ['too-big'];
+  }
+
+  console.log('Computed labels:', finalLabels.join(', '));
+
+  // Handle reviews and org fork comment
+  await Promise.all([
+    handleReviews(github, context, finalLabels, originalLabelCount, deprecatedInfo, prFiles, totalAdditions, totalDeletions, MAX_LABELS, TOO_BIG_THRESHOLD),
+    handleMaintainerAccessComment(github, context, maintainerAccess)
+  ]);
+
+  // Apply labels
+  await applyLabels(github, context, finalLabels);
+
+  // Remove old managed labels
+  await removeOldLabels(github, context, managedLabels, finalLabels);
+};

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

@@ -0,0 +1,41 @@
+// Apply labels to PR
+async function applyLabels(github, context, finalLabels) {
+  const { owner, repo } = context.repo;
+  const pr_number = context.issue.number;
+
+  if (finalLabels.length > 0) {
+    console.log(`Adding labels: ${finalLabels.join(', ')}`);
+    await github.rest.issues.addLabels({
+      owner,
+      repo,
+      issue_number: pr_number,
+      labels: finalLabels
+    });
+  }
+}
+
+// Remove old managed labels
+async function removeOldLabels(github, context, managedLabels, finalLabels) {
+  const { owner, repo } = context.repo;
+  const pr_number = context.issue.number;
+
+  const labelsToRemove = managedLabels.filter(label => !finalLabels.includes(label));
+  for (const label of labelsToRemove) {
+    console.log(`Removing label: ${label}`);
+    try {
+      await github.rest.issues.removeLabel({
+        owner,
+        repo,
+        issue_number: pr_number,
+        name: label
+      });
+    } catch (error) {
+      console.log(`Failed to remove label ${label}:`, error.message);
+    }
+  }
+}
+
+module.exports = {
+  applyLabels,
+  removeOldLabels
+};

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

@@ -0,0 +1,219 @@
+const {
+  BOT_COMMENT_MARKER,
+  CODEOWNERS_MARKER,
+  TOO_BIG_MARKER,
+  DEPRECATED_COMPONENT_MARKER,
+  ORG_FORK_MARKER
+} = require('./constants');
+
+// Generate review messages
+function generateReviewMessages(finalLabels, originalLabelCount, deprecatedInfo, prFiles, totalAdditions, totalDeletions, prAuthor, MAX_LABELS, TOO_BIG_THRESHOLD) {
+  const messages = [];
+
+  // Deprecated component message
+  if (finalLabels.includes('deprecated-component') && deprecatedInfo && deprecatedInfo.length > 0) {
+    let message = `${DEPRECATED_COMPONENT_MARKER}\n### ⚠️ Deprecated Component\n\n`;
+    message += `Hey there @${prAuthor},\n`;
+    message += `This PR modifies one or more deprecated components. Please be aware:\n\n`;
+
+    for (const info of deprecatedInfo) {
+      message += `#### Component: \`${info.component}\`\n`;
+      message += `${info.message}\n\n`;
+    }
+
+    message += `Consider migrating to the recommended alternative if applicable.`;
+
+    messages.push(message);
+  }
+
+  // Too big message
+  if (finalLabels.includes('too-big')) {
+    const testAdditions = prFiles
+      .filter(file => file.filename.startsWith('tests/'))
+      .reduce((sum, file) => sum + (file.additions || 0), 0);
+    const testDeletions = prFiles
+      .filter(file => file.filename.startsWith('tests/'))
+      .reduce((sum, file) => sum + (file.deletions || 0), 0);
+    const nonTestChanges = (totalAdditions - testAdditions) - (totalDeletions - testDeletions);
+
+    const tooManyLabels = originalLabelCount > MAX_LABELS;
+    const tooManyChanges = nonTestChanges > TOO_BIG_THRESHOLD;
+
+    let message = `${TOO_BIG_MARKER}\n### 📦 Pull Request Size\n\n`;
+
+    message +=
+      `Hey @${prAuthor}, thanks for the contribution! Just a heads up, ` +
+      `this PR is on the large side `;
+
+    if (tooManyLabels && tooManyChanges) {
+      message +=
+        `(${nonTestChanges} line changes excluding tests, across ` +
+        `${originalLabelCount} different components/areas)`;
+    } else if (tooManyLabels) {
+      message +=
+        `(it touches ${originalLabelCount} different components/areas)`;
+    } else {
+      message += `(${nonTestChanges} line changes excluding tests)`;
+    }
+
+    message += `, which makes it harder for maintainers to review.\n\n`;
+    message +=
+      `Smaller, focused PRs tend to be reviewed much faster since they ` +
+      `fit into the short gaps between other maintainer work; large ones ` +
+      `often have to wait for a rare long uninterrupted block of time. ` +
+      `If you can break this up into smaller pieces that can be reviewed ` +
+      `independently, it will almost certainly land faster overall.\n\n`;
+    message +=
+      `Before putting more time in, it's also worth popping into ` +
+      `\`#devs\` on [Discord](https://esphome.io/chat) so we can help ` +
+      `you scope things and flag anything already in flight.\n\n`;
+    message +=
+      `For more details (including how to split the work up), see: ` +
+      `https://developers.esphome.io/contributing/submitting-your-work/` +
+      `#how-to-approach-large-submissions`;
+
+    messages.push(message);
+  }
+
+  // CODEOWNERS message
+  if (finalLabels.includes('needs-codeowners')) {
+    const message = `${CODEOWNERS_MARKER}\n### 👥 Code Ownership\n\n` +
+      `Hey there @${prAuthor},\n` +
+      `Thanks for submitting this pull request! Can you add yourself as a codeowner for this integration? ` +
+      `This way we can notify you if a bug report for this integration is reported.\n\n` +
+      `In \`__init__.py\` of the integration, please add:\n\n` +
+      `\`\`\`python\nCODEOWNERS = ["@${prAuthor}"]\n\`\`\`\n\n` +
+      `And run \`script/build_codeowners.py\``;
+
+    messages.push(message);
+  }
+
+  return messages;
+}
+
+// Handle reviews
+async function handleReviews(github, context, finalLabels, originalLabelCount, deprecatedInfo, prFiles, totalAdditions, totalDeletions, MAX_LABELS, TOO_BIG_THRESHOLD) {
+  const { owner, repo } = context.repo;
+  const pr_number = context.issue.number;
+  const prAuthor = context.payload.pull_request.user.login;
+
+  const reviewMessages = generateReviewMessages(finalLabels, originalLabelCount, deprecatedInfo, prFiles, totalAdditions, totalDeletions, prAuthor, MAX_LABELS, TOO_BIG_THRESHOLD);
+  const hasReviewableLabels = finalLabels.some(label =>
+    ['too-big', 'needs-codeowners', 'deprecated-component'].includes(label)
+  );
+
+  const { data: reviews } = await github.rest.pulls.listReviews({
+    owner,
+    repo,
+    pull_number: pr_number
+  });
+
+  const botReviews = reviews.filter(review =>
+    review.user.type === 'Bot' &&
+    review.state === 'CHANGES_REQUESTED' &&
+    review.body && review.body.includes(BOT_COMMENT_MARKER)
+  );
+
+  if (hasReviewableLabels) {
+    const reviewBody = `${BOT_COMMENT_MARKER}\n\n${reviewMessages.join('\n\n---\n\n')}`;
+
+    if (botReviews.length > 0) {
+      // Update existing review
+      await github.rest.pulls.updateReview({
+        owner,
+        repo,
+        pull_number: pr_number,
+        review_id: botReviews[0].id,
+        body: reviewBody
+      });
+      console.log('Updated existing bot review');
+    } else {
+      // Create new review
+      await github.rest.pulls.createReview({
+        owner,
+        repo,
+        pull_number: pr_number,
+        body: reviewBody,
+        event: 'REQUEST_CHANGES'
+      });
+      console.log('Created new bot review');
+    }
+  } else if (botReviews.length > 0) {
+    // Dismiss existing reviews
+    for (const review of botReviews) {
+      try {
+        await github.rest.pulls.dismissReview({
+          owner,
+          repo,
+          pull_number: pr_number,
+          review_id: review.id,
+          message: 'Review dismissed: All requirements have been met'
+        });
+        console.log(`Dismissed bot review ${review.id}`);
+      } catch (error) {
+        console.log(`Failed to dismiss review ${review.id}:`, error.message);
+      }
+    }
+  }
+}
+
+// Handle maintainer access warning comment
+async function handleMaintainerAccessComment(github, context, maintainerAccess) {
+  if (!maintainerAccess) {
+    return;
+  }
+
+  const { owner, repo } = context.repo;
+  const pr_number = context.issue.number;
+  const prAuthor = context.payload.pull_request.user.login;
+
+  // Check if we already posted the warning (iterate pages to exit early)
+  let existingComment;
+  for await (const { data: comments } of github.paginate.iterator(
+    github.rest.issues.listComments,
+    { owner, repo, issue_number: pr_number }
+  )) {
+    existingComment = comments.find(comment =>
+      comment.user.type === 'Bot' &&
+      comment.body && comment.body.includes(ORG_FORK_MARKER)
+    );
+    if (existingComment) {
+      break;
+    }
+  }
+
+  if (existingComment) {
+    console.log('Maintainer access warning comment already exists, skipping');
+    return;
+  }
+
+  let body;
+  if (maintainerAccess.isOrgFork) {
+    body = `${ORG_FORK_MARKER}\n### ⚠️ Organization Fork Detected\n\n` +
+      `Hey there @${prAuthor},\n` +
+      `It looks like this PR was submitted from a fork owned by the **${maintainerAccess.orgName}** organization. ` +
+      `GitHub does not allow maintainers to push changes to pull request branches when the fork is owned by an organization. ` +
+      `This means we won't be able to make small adjustments or fixups to your PR directly.\n\n` +
+      `To allow maintainer collaboration, please re-submit this PR from a personal fork instead.\n\n` +
+      `See: [Setting up the local repository](https://developers.esphome.io/contributing/development-environment/?h=org#set-up-the-local-repository) for more details.`;
+  } else {
+    body = `${ORG_FORK_MARKER}\n### ⚠️ Maintainer Access Disabled\n\n` +
+      `Hey there @${prAuthor},\n` +
+      `It looks like this PR does not have the "Allow edits from maintainers" option enabled. ` +
+      `This means we won't be able to make small adjustments or fixups to your PR directly.\n\n` +
+      `Please enable this option in the PR sidebar to allow maintainer collaboration.`;
+  }
+
+  await github.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: pr_number,
+    body
+  });
+  console.log('Created maintainer access warning comment');
+}
+
+module.exports = {
+  handleReviews,
+  handleMaintainerAccessComment
+};

.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

@@ -6,12 +6,14 @@ on:
   pull_request_target:
     types: [labeled, opened, reopened, synchronize, edited]
 
+# All PR/label/review writes are performed with the App token minted below,
+# so the workflow's GITHUB_TOKEN only needs read access for checkout.
 permissions:
-  pull-requests: write
-  contents: read
+  contents: read  # actions/checkout reads the workflow source
 
 env:
   SMALL_PR_THRESHOLD: 30
+  MEDIUM_PR_THRESHOLD: 100
   MAX_LABELS: 15
   TOO_BIG_THRESHOLD: 1000
   COMPONENT_LABEL_THRESHOLD: 10
@@ -19,644 +21,26 @@ env:
 jobs:
   label:
     runs-on: ubuntu-latest
-    if: github.event.action != 'labeled' || github.event.sender.type != 'Bot'
+    if: github.event.pull_request.state == 'open' && (github.event.action != 'labeled' || github.event.sender.type != 'Bot')
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Generate a token
         id: generate-token
-        uses: actions/create-github-app-token@67018539274d69449ef7c02e8e71183d1719ab42 # v2
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
         with:
-          app-id: ${{ secrets.ESPHOME_GITHUB_APP_ID }}
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
           private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          # Scope the minted App token to the minimum needed by auto-label-pr/*.js.
+          permission-contents: read       # repos.getContent for CODEOWNERS and file lookups in detectors.js
+          permission-issues: write        # listLabelsOnIssue, addLabels, removeLabel, list/createComment
+          permission-pull-requests: write  # pulls.listFiles, list/create/update/dismissReview
 
       - name: Auto Label PR
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.generate-token.outputs.token }}
           script: |
-            const fs = require('fs');
-
-            // Constants
-            const SMALL_PR_THRESHOLD = parseInt('${{ env.SMALL_PR_THRESHOLD }}');
-            const MAX_LABELS = parseInt('${{ env.MAX_LABELS }}');
-            const TOO_BIG_THRESHOLD = parseInt('${{ env.TOO_BIG_THRESHOLD }}');
-            const COMPONENT_LABEL_THRESHOLD = parseInt('${{ env.COMPONENT_LABEL_THRESHOLD }}');
-            const BOT_COMMENT_MARKER = '<!-- auto-label-pr-bot -->';
-            const CODEOWNERS_MARKER = '<!-- codeowners-request -->';
-            const TOO_BIG_MARKER = '<!-- too-big-request -->';
-
-            const MANAGED_LABELS = [
-              'new-component',
-              'new-platform',
-              'new-target-platform',
-              'merging-to-release',
-              'merging-to-beta',
-              'core',
-              'small-pr',
-              'dashboard',
-              'github-actions',
-              'by-code-owner',
-              'has-tests',
-              'needs-tests',
-              'needs-docs',
-              'needs-codeowners',
-              'too-big',
-              'labeller-recheck',
-              'bugfix',
-              'new-feature',
-              'breaking-change',
-              'code-quality'
-            ];
-
-            const DOCS_PR_PATTERNS = [
-              /https:\/\/github\.com\/esphome\/esphome-docs\/pull\/\d+/,
-              /esphome\/esphome-docs#\d+/
-            ];
-
-            // Global state
-            const { owner, repo } = context.repo;
-            const pr_number = context.issue.number;
-
-            // Get current labels and PR data
-            const { data: currentLabelsData } = await github.rest.issues.listLabelsOnIssue({
-              owner,
-              repo,
-              issue_number: pr_number
-            });
-            const currentLabels = currentLabelsData.map(label => label.name);
-            const managedLabels = currentLabels.filter(label =>
-              label.startsWith('component: ') || MANAGED_LABELS.includes(label)
-            );
-
-            // Check for mega-PR early - if present, skip most automatic labeling
-            const isMegaPR = currentLabels.includes('mega-pr');
-
-            // Get all PR files with automatic pagination
-            const prFiles = await github.paginate(
-              github.rest.pulls.listFiles,
-              {
-                owner,
-                repo,
-                pull_number: pr_number
-              }
-            );
-
-            // Calculate data from PR files
-            const changedFiles = prFiles.map(file => file.filename);
-            const totalAdditions = prFiles.reduce((sum, file) => sum + (file.additions || 0), 0);
-            const totalDeletions = prFiles.reduce((sum, file) => sum + (file.deletions || 0), 0);
-            const totalChanges = totalAdditions + totalDeletions;
-
-            console.log('Current labels:', currentLabels.join(', '));
-            console.log('Changed files:', changedFiles.length);
-            console.log('Total changes:', totalChanges);
-            if (isMegaPR) {
-              console.log('Mega-PR detected - applying limited labeling logic');
-            }
-
-            // Fetch API data
-            async function fetchApiData() {
-              try {
-                const response = await fetch('https://data.esphome.io/components.json');
-                const componentsData = await response.json();
-                return {
-                  targetPlatforms: componentsData.target_platforms || [],
-                  platformComponents: componentsData.platform_components || []
-                };
-              } catch (error) {
-                console.log('Failed to fetch components data from API:', error.message);
-                return { targetPlatforms: [], platformComponents: [] };
-              }
-            }
-
-            // Strategy: Merge branch detection
-            async function detectMergeBranch() {
-              const labels = new Set();
-              const baseRef = context.payload.pull_request.base.ref;
-
-              if (baseRef === 'release') {
-                labels.add('merging-to-release');
-              } else if (baseRef === 'beta') {
-                labels.add('merging-to-beta');
-              }
-
-              return labels;
-            }
-
-            // Strategy: Component and platform labeling
-            async function detectComponentPlatforms(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]}`);
-                }
-
-                const platformMatch = file.match(targetPlatformRegex);
-                if (platformMatch) {
-                  labels.add(`platform: ${platformMatch[1]}`);
-                }
-              }
-
-              return labels;
-            }
-
-            // Strategy: New component detection
-            async function detectNewComponents() {
-              const labels = new Set();
-              const addedFiles = prFiles.filter(file => file.status === 'added').map(file => file.filename);
-
-              for (const file of addedFiles) {
-                const componentMatch = file.match(/^esphome\/components\/([^\/]+)\/__init__\.py$/);
-                if (componentMatch) {
-                  try {
-                    const content = fs.readFileSync(file, 'utf8');
-                    if (content.includes('IS_TARGET_PLATFORM = True')) {
-                      labels.add('new-target-platform');
-                    }
-                  } catch (error) {
-                    console.log(`Failed to read content of ${file}:`, error.message);
-                  }
-                  labels.add('new-component');
-                }
-              }
-
-              return labels;
-            }
-
-            // Strategy: New platform detection
-            async function detectNewPlatforms(apiData) {
-              const labels = new Set();
-              const addedFiles = prFiles.filter(file => file.status === 'added').map(file => file.filename);
-
-              for (const file of addedFiles) {
-                const platformFileMatch = file.match(/^esphome\/components\/([^\/]+)\/([^\/]+)\.py$/);
-                if (platformFileMatch) {
-                  const [, component, platform] = platformFileMatch;
-                  if (apiData.platformComponents.includes(platform)) {
-                    labels.add('new-platform');
-                  }
-                }
-
-                const platformDirMatch = file.match(/^esphome\/components\/([^\/]+)\/([^\/]+)\/__init__\.py$/);
-                if (platformDirMatch) {
-                  const [, component, platform] = platformDirMatch;
-                  if (apiData.platformComponents.includes(platform)) {
-                    labels.add('new-platform');
-                  }
-                }
-              }
-
-              return labels;
-            }
-
-            // Strategy: Core files detection
-            async function detectCoreChanges() {
-              const labels = new Set();
-              const coreFiles = changedFiles.filter(file =>
-                file.startsWith('esphome/core/') ||
-                (file.startsWith('esphome/') && file.split('/').length === 2)
-              );
-
-              if (coreFiles.length > 0) {
-                labels.add('core');
-              }
-
-              return labels;
-            }
-
-            // Strategy: PR size detection
-            async function detectPRSize() {
-              const labels = new Set();
-
-              if (totalChanges <= SMALL_PR_THRESHOLD) {
-                labels.add('small-pr');
-                return labels;
-              }
-
-              const testAdditions = prFiles
-                .filter(file => file.filename.startsWith('tests/'))
-                .reduce((sum, file) => sum + (file.additions || 0), 0);
-              const testDeletions = prFiles
-                .filter(file => file.filename.startsWith('tests/'))
-                .reduce((sum, file) => sum + (file.deletions || 0), 0);
-
-              const nonTestChanges = (totalAdditions - testAdditions) - (totalDeletions - testDeletions);
-
-              // Don't add too-big if mega-pr label is already present
-              if (nonTestChanges > TOO_BIG_THRESHOLD && !isMegaPR) {
-                labels.add('too-big');
-              }
-
-              return labels;
-            }
-
-            // Strategy: Dashboard changes
-            async function detectDashboardChanges() {
-              const labels = new Set();
-              const dashboardFiles = changedFiles.filter(file =>
-                file.startsWith('esphome/dashboard/') ||
-                file.startsWith('esphome/components/dashboard_import/')
-              );
-
-              if (dashboardFiles.length > 0) {
-                labels.add('dashboard');
-              }
-
-              return labels;
-            }
-
-            // Strategy: GitHub Actions changes
-            async function detectGitHubActionsChanges() {
-              const labels = new Set();
-              const githubActionsFiles = changedFiles.filter(file =>
-                file.startsWith('.github/workflows/')
-              );
-
-              if (githubActionsFiles.length > 0) {
-                labels.add('github-actions');
-              }
-
-              return labels;
-            }
-
-            // Strategy: Code owner detection
-            async function detectCodeOwner() {
-              const labels = new Set();
-
-              try {
-                const { data: codeownersFile } = await github.rest.repos.getContent({
-                  owner,
-                  repo,
-                  path: 'CODEOWNERS',
-                });
-
-                const codeownersContent = Buffer.from(codeownersFile.content, 'base64').toString('utf8');
-                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;
-                    }
-                  }
-                }
-              } catch (error) {
-                console.log('Failed to read or parse CODEOWNERS file:', error.message);
-              }
-
-              return labels;
-            }
-
-            // Strategy: Test detection
-            async function detectTests() {
-              const labels = new Set();
-              const testFiles = changedFiles.filter(file => file.startsWith('tests/'));
-
-              if (testFiles.length > 0) {
-                labels.add('has-tests');
-              }
-
-              return labels;
-            }
-
-            // Strategy: PR Template Checkbox detection
-            async function detectPRTemplateCheckboxes() {
-              const labels = new Set();
-              const prBody = context.payload.pull_request.body || '';
-
-              console.log('Checking PR template checkboxes...');
-
-              // Check for checked checkboxes in the "Types of changes" section
-              const checkboxPatterns = [
-                { pattern: /- \[x\] Bugfix \(non-breaking change which fixes an issue\)/i, label: 'bugfix' },
-                { 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\] Code quality improvements to existing code or addition of tests/i, label: 'code-quality' }
-              ];
-
-              for (const { pattern, label } of checkboxPatterns) {
-                if (pattern.test(prBody)) {
-                  console.log(`Found checked checkbox for: ${label}`);
-                  labels.add(label);
-                }
-              }
-
-              return labels;
-            }
-
-            // Strategy: Requirements detection
-            async function detectRequirements(allLabels) {
-              const labels = new Set();
-
-              // Check for missing tests
-              if ((allLabels.has('new-component') || allLabels.has('new-platform') || allLabels.has('new-feature')) && !allLabels.has('has-tests')) {
-                labels.add('needs-tests');
-              }
-
-              // Check for missing docs
-              if (allLabels.has('new-component') || allLabels.has('new-platform') || allLabels.has('new-feature')) {
-                const prBody = context.payload.pull_request.body || '';
-                const hasDocsLink = DOCS_PR_PATTERNS.some(pattern => pattern.test(prBody));
-
-                if (!hasDocsLink) {
-                  labels.add('needs-docs');
-                }
-              }
-
-              // Check for missing CODEOWNERS
-              if (allLabels.has('new-component')) {
-                const codeownersModified = prFiles.some(file =>
-                  file.filename === 'CODEOWNERS' &&
-                  (file.status === 'modified' || file.status === 'added') &&
-                  (file.additions || 0) > 0
-                );
-
-                if (!codeownersModified) {
-                  labels.add('needs-codeowners');
-                }
-              }
-
-              return labels;
-            }
-
-            // Generate review messages
-            function generateReviewMessages(finalLabels) {
-              const messages = [];
-              const prAuthor = context.payload.pull_request.user.login;
-
-              // Too big message
-              if (finalLabels.includes('too-big')) {
-                const testAdditions = prFiles
-                  .filter(file => file.filename.startsWith('tests/'))
-                  .reduce((sum, file) => sum + (file.additions || 0), 0);
-                const testDeletions = prFiles
-                  .filter(file => file.filename.startsWith('tests/'))
-                  .reduce((sum, file) => sum + (file.deletions || 0), 0);
-                const nonTestChanges = (totalAdditions - testAdditions) - (totalDeletions - testDeletions);
-
-                const tooManyLabels = finalLabels.length > MAX_LABELS;
-                const tooManyChanges = nonTestChanges > TOO_BIG_THRESHOLD;
-
-                let message = `${TOO_BIG_MARKER}\n### 📦 Pull Request Size\n\n`;
-
-                if (tooManyLabels && tooManyChanges) {
-                  message += `This PR is too large with ${nonTestChanges} line changes (excluding tests) and affects ${finalLabels.length} different components/areas.`;
-                } else if (tooManyLabels) {
-                  message += `This PR affects ${finalLabels.length} different components/areas.`;
-                } else {
-                  message += `This PR is too large with ${nonTestChanges} line changes (excluding tests).`;
-                }
-
-                message += ` Please consider breaking it down into smaller, focused PRs to make review easier and reduce the risk of conflicts.\n\n`;
-                message += `For guidance on breaking down large PRs, see: https://developers.esphome.io/contributing/submitting-your-work/#how-to-approach-large-submissions`;
-
-                messages.push(message);
-              }
-
-              // CODEOWNERS message
-              if (finalLabels.includes('needs-codeowners')) {
-                const message = `${CODEOWNERS_MARKER}\n### 👥 Code Ownership\n\n` +
-                  `Hey there @${prAuthor},\n` +
-                  `Thanks for submitting this pull request! Can you add yourself as a codeowner for this integration? ` +
-                  `This way we can notify you if a bug report for this integration is reported.\n\n` +
-                  `In \`__init__.py\` of the integration, please add:\n\n` +
-                  `\`\`\`python\nCODEOWNERS = ["@${prAuthor}"]\n\`\`\`\n\n` +
-                  `And run \`script/build_codeowners.py\``;
-
-                messages.push(message);
-              }
-
-              return messages;
-            }
-
-            // Handle reviews
-            async function handleReviews(finalLabels) {
-              const reviewMessages = generateReviewMessages(finalLabels);
-              const hasReviewableLabels = finalLabels.some(label =>
-                ['too-big', 'needs-codeowners'].includes(label)
-              );
-
-              const { data: reviews } = await github.rest.pulls.listReviews({
-                owner,
-                repo,
-                pull_number: pr_number
-              });
-
-              const botReviews = reviews.filter(review =>
-                review.user.type === 'Bot' &&
-                review.state === 'CHANGES_REQUESTED' &&
-                review.body && review.body.includes(BOT_COMMENT_MARKER)
-              );
-
-              if (hasReviewableLabels) {
-                const reviewBody = `${BOT_COMMENT_MARKER}\n\n${reviewMessages.join('\n\n---\n\n')}`;
-
-                if (botReviews.length > 0) {
-                  // Update existing review
-                  await github.rest.pulls.updateReview({
-                    owner,
-                    repo,
-                    pull_number: pr_number,
-                    review_id: botReviews[0].id,
-                    body: reviewBody
-                  });
-                  console.log('Updated existing bot review');
-                } else {
-                  // Create new review
-                  await github.rest.pulls.createReview({
-                    owner,
-                    repo,
-                    pull_number: pr_number,
-                    body: reviewBody,
-                    event: 'REQUEST_CHANGES'
-                  });
-                  console.log('Created new bot review');
-                }
-              } else if (botReviews.length > 0) {
-                // Dismiss existing reviews
-                for (const review of botReviews) {
-                  try {
-                    await github.rest.pulls.dismissReview({
-                      owner,
-                      repo,
-                      pull_number: pr_number,
-                      review_id: review.id,
-                      message: 'Review dismissed: All requirements have been met'
-                    });
-                    console.log(`Dismissed bot review ${review.id}`);
-                  } catch (error) {
-                    console.log(`Failed to dismiss review ${review.id}:`, error.message);
-                  }
-                }
-              }
-            }
-
-            // Main execution
-            const apiData = await fetchApiData();
-            const baseRef = context.payload.pull_request.base.ref;
-
-            // Early exit for non-dev branches
-            if (baseRef !== 'dev') {
-              const branchLabels = await detectMergeBranch();
-              const finalLabels = Array.from(branchLabels);
-
-              console.log('Computed labels (merge branch only):', finalLabels.join(', '));
-
-              // Apply labels
-              if (finalLabels.length > 0) {
-                await github.rest.issues.addLabels({
-                  owner,
-                  repo,
-                  issue_number: pr_number,
-                  labels: finalLabels
-                });
-              }
-
-              // Remove old managed labels
-              const labelsToRemove = managedLabels.filter(label => !finalLabels.includes(label));
-              for (const label of labelsToRemove) {
-                try {
-                  await github.rest.issues.removeLabel({
-                    owner,
-                    repo,
-                    issue_number: pr_number,
-                    name: label
-                  });
-                } catch (error) {
-                  console.log(`Failed to remove label ${label}:`, error.message);
-                }
-              }
-
-              return;
-            }
-
-            // Run all strategies
-            const [
-              branchLabels,
-              componentLabels,
-              newComponentLabels,
-              newPlatformLabels,
-              coreLabels,
-              sizeLabels,
-              dashboardLabels,
-              actionsLabels,
-              codeOwnerLabels,
-              testLabels,
-              checkboxLabels
-            ] = await Promise.all([
-              detectMergeBranch(),
-              detectComponentPlatforms(apiData),
-              detectNewComponents(),
-              detectNewPlatforms(apiData),
-              detectCoreChanges(),
-              detectPRSize(),
-              detectDashboardChanges(),
-              detectGitHubActionsChanges(),
-              detectCodeOwner(),
-              detectTests(),
-              detectPRTemplateCheckboxes()
-            ]);
-
-            // Combine all labels
-            const allLabels = new Set([
-              ...branchLabels,
-              ...componentLabels,
-              ...newComponentLabels,
-              ...newPlatformLabels,
-              ...coreLabels,
-              ...sizeLabels,
-              ...dashboardLabels,
-              ...actionsLabels,
-              ...codeOwnerLabels,
-              ...testLabels,
-              ...checkboxLabels
-            ]);
-
-            // Detect requirements based on all other labels
-            const requirementLabels = await detectRequirements(allLabels);
-            for (const label of requirementLabels) {
-              allLabels.add(label);
-            }
-
-            let finalLabels = Array.from(allLabels);
-
-            // For mega-PRs, exclude component labels if there are too many
-            if (isMegaPR) {
-              const componentLabels = finalLabels.filter(label => label.startsWith('component: '));
-              if (componentLabels.length > COMPONENT_LABEL_THRESHOLD) {
-                finalLabels = finalLabels.filter(label => !label.startsWith('component: '));
-                console.log(`Mega-PR detected - excluding ${componentLabels.length} component labels (threshold: ${COMPONENT_LABEL_THRESHOLD})`);
-              }
-            }
-
-            // Handle too many labels (only for non-mega PRs)
-            const tooManyLabels = finalLabels.length > MAX_LABELS;
-
-            if (tooManyLabels && !isMegaPR && !finalLabels.includes('too-big')) {
-              finalLabels = ['too-big'];
-            }
-
-            console.log('Computed labels:', finalLabels.join(', '));
-
-            // Handle reviews
-            await handleReviews(finalLabels);
-
-            // Apply labels
-            if (finalLabels.length > 0) {
-              console.log(`Adding labels: ${finalLabels.join(', ')}`);
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number: pr_number,
-                labels: finalLabels
-              });
-            }
-
-            // Remove old managed labels
-            const labelsToRemove = managedLabels.filter(label => !finalLabels.includes(label));
-            for (const label of labelsToRemove) {
-              console.log(`Removing label: ${label}`);
-              try {
-                await github.rest.issues.removeLabel({
-                  owner,
-                  repo,
-                  issue_number: pr_number,
-                  name: label
-                });
-              } catch (error) {
-                console.log(`Failed to remove label ${label}:`, error.message);
-              }
-            }
+            const script = require('./.github/scripts/auto-label-pr/index.js');
+            await script({ github, context });

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

@@ -12,8 +12,8 @@ on:
       - ".github/workflows/ci-api-proto.yml"
 
 permissions:
-  contents: read
-  pull-requests: write
+  contents: read        # actions/checkout for the PR head
+  pull-requests: write  # pulls.createReview / listReviews / dismissReview when generated proto files are stale
 
 jobs:
   check:
@@ -21,9 +21,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up Python
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
 
@@ -47,7 +47,7 @@ jobs:
           fi
       - if: failure()
         name: Review PR
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             await github.rest.pulls.createReview({
@@ -62,7 +62,7 @@ jobs:
         run: git diff
       - if: failure()
         name: Archive artifacts
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: generated-proto-files
           path: |
@@ -70,7 +70,7 @@ jobs:
             esphome/components/api/api_pb2_service.*
       - if: success()
         name: Dismiss review
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             let reviews = await github.rest.pulls.listReviews({

.github/workflows/ci-clang-tidy-hash.yml

@@ -12,8 +12,8 @@ on:
       - ".github/workflows/ci-clang-tidy-hash.yml"
 
 permissions:
-  contents: read
-  pull-requests: write
+  contents: read        # actions/checkout for the PR head
+  pull-requests: write  # pulls.createReview / listReviews / dismissReview when the clang-tidy hash is out of date
 
 jobs:
   verify-hash:
@@ -21,10 +21,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Python
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
 
@@ -40,9 +40,9 @@ jobs:
           echo "You have modified clang-tidy configuration but have not updated the hash." | tee -a $GITHUB_STEP_SUMMARY
           echo "Please run 'script/clang_tidy_hash.py --update' and commit the changes." | tee -a $GITHUB_STEP_SUMMARY
 
-      - if: failure()
+      - if: failure() && github.event.pull_request.head.repo.full_name == github.repository
         name: Request changes
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             await github.rest.pulls.createReview({
@@ -53,9 +53,9 @@ jobs:
               body: 'You have modified clang-tidy configuration but have not updated the hash.\nPlease run `script/clang_tidy_hash.py --update` and commit the changes.'
             })
 
-      - if: success()
+      - if: success() && github.event.pull_request.head.repo.full_name == github.repository
         name: Dismiss review
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             let reviews = await github.rest.pulls.listReviews({

.github/workflows/ci-docker.yml

@@ -22,8 +22,7 @@ on:
       - "script/platformio_install_deps.py"
 
 permissions:
-  contents: read
-  packages: read
+  contents: read  # actions/checkout only; the build does not push images
 
 concurrency:
   # yamllint disable-line rule:line-length
@@ -43,13 +42,13 @@ jobs:
           - "docker"
           # - "lint"
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up Python
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Set TAG
         run: |

.github/workflows/ci-memory-impact-comment.yml

@@ -0,0 +1,111 @@
+---
+name: Memory Impact Comment (Forks)
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+permissions:
+  contents: read        # actions/checkout of the base repo at the PR's target branch
+  pull-requests: write  # gh api to look up the PR by head SHA and post/update the memory-impact comment
+  actions: read         # gh run download for the memory-analysis artifacts produced by the CI workflow run
+
+jobs:
+  memory-impact-comment:
+    name: Post memory impact comment (fork PRs only)
+    runs-on: ubuntu-24.04
+    # Only run for PRs from forks that had successful CI runs
+    if: >
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_repository.full_name != github.repository
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - name: Get PR details
+        id: pr
+        run: |
+          # Get PR details by searching for PR with matching head SHA
+          # The workflow_run.pull_requests field is often empty for forks
+          # Use paginate to handle repos with many open PRs
+          head_sha="${{ github.event.workflow_run.head_sha }}"
+          pr_data=$(gh api --paginate "/repos/${{ github.repository }}/pulls" \
+            --jq ".[] | select(.head.sha == \"$head_sha\") | {number: .number, base_ref: .base.ref}" \
+            | head -n 1)
+
+          if [ -z "$pr_data" ]; then
+            echo "No PR found for SHA $head_sha, skipping"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          pr_number=$(echo "$pr_data" | jq -r '.number')
+          base_ref=$(echo "$pr_data" | jq -r '.base_ref')
+
+          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
+          echo "base_ref=$base_ref" >> "$GITHUB_OUTPUT"
+          echo "Found PR #$pr_number targeting base branch: $base_ref"
+
+      - name: Check out code from base repository
+        if: steps.pr.outputs.skip != 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Always check out from the base repository (esphome/esphome), never from forks
+          # Use the PR's target branch to ensure we run trusted code from the main repo
+          repository: ${{ github.repository }}
+          ref: ${{ steps.pr.outputs.base_ref }}
+
+      - name: Restore Python
+        if: steps.pr.outputs.skip != 'true'
+        uses: ./.github/actions/restore-python
+        with:
+          python-version: "3.11"
+          cache-key: ${{ hashFiles('.cache-key') }}
+
+      - name: Download memory analysis artifacts
+        if: steps.pr.outputs.skip != 'true'
+        run: |
+          run_id="${{ github.event.workflow_run.id }}"
+          echo "Downloading artifacts from workflow run $run_id"
+
+          mkdir -p memory-analysis
+
+          # Download target analysis artifact
+          if gh run download --name "memory-analysis-target" --dir memory-analysis --repo "${{ github.repository }}" "$run_id"; then
+            echo "Downloaded memory-analysis-target artifact."
+          else
+            echo "No memory-analysis-target artifact found."
+          fi
+
+          # Download PR analysis artifact
+          if gh run download --name "memory-analysis-pr" --dir memory-analysis --repo "${{ github.repository }}" "$run_id"; then
+            echo "Downloaded memory-analysis-pr artifact."
+          else
+            echo "No memory-analysis-pr artifact found."
+          fi
+
+      - name: Check if artifacts exist
+        id: check
+        if: steps.pr.outputs.skip != 'true'
+        run: |
+          if [ -f ./memory-analysis/memory-analysis-target.json ] && [ -f ./memory-analysis/memory-analysis-pr.json ]; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+            echo "Memory analysis artifacts not found, skipping comment"
+          fi
+
+      - name: Post or update PR comment
+        if: steps.pr.outputs.skip != 'true' && steps.check.outputs.found == 'true'
+        env:
+          PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
+        run: |
+          . venv/bin/activate
+          # Pass PR number and JSON file paths directly to Python script
+          # Let Python parse the JSON to avoid shell injection risks
+          # The script will validate and sanitize all inputs
+          python script/ci_memory_impact_comment.py \
+            --pr-number "$PR_NUMBER" \
+            --target-json ./memory-analysis/memory-analysis-target.json \
+            --pr-json ./memory-analysis/memory-analysis-pr.json

.github/workflows/close-pr-from-fork-default-branch.yml

@@ -0,0 +1,72 @@
+name: Close PR From Fork Default Branch
+
+on:
+  # pull_request_target is required so we have permission to comment and close PRs from forks.
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  pull-requests: write  # pulls.update to close the PR opened from a fork's default branch
+  issues: write         # issues.createComment to explain to the contributor why the PR was closed
+
+jobs:
+  close:
+    name: Close PR opened from fork's default branch
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
+      && github.event.pull_request.head.ref == github.event.repository.default_branch
+    steps:
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const prNumber = context.payload.pull_request.number;
+            const author = context.payload.pull_request.user.login;
+            const defaultBranch = context.payload.repository.default_branch;
+            const headRepo = context.payload.pull_request.head.repo.full_name;
+
+            const body = [
+              `Hi @${author}, thanks for opening a pull request! :tada:`,
+              ``,
+              `It looks like this PR was opened from the \`${defaultBranch}\` branch of your fork (\`${headRepo}\`), which is the same name as this repository's default branch. Working directly on \`${defaultBranch}\` in your fork causes a few problems:`,
+              ``,
+              `- Your fork's \`${defaultBranch}\` branch will permanently diverge from \`esphome/esphome:${defaultBranch}\`, making it hard to keep your fork up to date.`,
+              `- Any additional commits you push to \`${defaultBranch}\` will be added to this PR, so you can't easily work on multiple changes at once.`,
+              `- Pushing maintainer fixes to your branch is awkward, since it means committing directly to your fork's default branch.`,
+              `- It makes local collaboration painful — \`${defaultBranch}\` in a checkout becomes ambiguous between upstream and your fork, and maintainers end up with naming collisions when fetching your branch.`,
+              ``,
+              `Please re-open this as a new PR from a dedicated feature branch. The usual flow looks like:`,
+              ``,
+              `\`\`\`bash`,
+              `# Make sure your fork's ${defaultBranch} is up to date with upstream`,
+              `git remote add upstream https://github.com/${owner}/${repo}.git  # if you haven't already`,
+              `git fetch upstream`,
+              `git checkout ${defaultBranch}`,
+              `git reset --hard upstream/${defaultBranch}`,
+              `git push --force-with-lease origin ${defaultBranch}`,
+              ``,
+              `# Create a new branch for your change and cherry-pick / re-apply your commits there`,
+              `git checkout -b my-feature-branch upstream/${defaultBranch}`,
+              `# ...re-apply your changes, then:`,
+              `git push origin my-feature-branch`,
+              `\`\`\``,
+              ``,
+              `Then open a new pull request from \`my-feature-branch\` into \`${owner}/${repo}:${defaultBranch}\`.`,
+              ``,
+              `Closing this PR for now — sorry for the friction, and thanks again for contributing! :heart:`,
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: prNumber,
+              body,
+            });
+
+            await github.rest.pulls.update({
+              owner,
+              repo,
+              pull_number: prNumber,
+              state: 'closed',
+            });

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

@@ -0,0 +1,81 @@
+# 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]
+    branches-ignore:
+      - release
+      - beta
+
+permissions:
+  issues: write       # issues.addLabels / removeLabel to manage the 'code-owner-approved' label on the PR
+  pull-requests: read  # listReviews to determine whether a codeowner has approved
+  contents: read       # actions/checkout to read CODEOWNERS and the shared codeowners.js helper
+
+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@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.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

@@ -13,21 +13,43 @@ on:
   # Needs to be pull_request_target to get write permissions
   pull_request_target:
     types: [opened, reopened, synchronize, ready_for_review]
+    branches-ignore:
+      - release
+      - beta
 
+# PR/review writes (requestReviewers, issues.createComment) are performed with the App token minted below,
+# so the workflow's GITHUB_TOKEN only needs read access for checkout.
 permissions:
-  pull-requests: write
-  contents: read
+  contents: read  # actions/checkout to read CODEOWNERS and the shared codeowners.js helper
 
 jobs:
   request-codeowner-reviews:
     name: Run
-    if: ${{ !github.event.pull_request.draft }}
+    if: ${{ github.repository == 'esphome/esphome' && !github.event.pull_request.draft }}
     runs-on: ubuntu-latest
     steps:
-      - name: Request reviews from component codeowners
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - name: Checkout base branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
+          ref: ${{ github.event.pull_request.base.sha }}
+
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          # Scope the minted App token to the minimum needed by the github-script step below.
+          permission-pull-requests: write  # pulls.listFiles, pulls.get, pulls.listReviews, pulls.requestReviewers
+          permission-issues: write         # issues.listComments and issues.createComment (PR comments use the issues API)
+
+      - name: Request reviews from component codeowners
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          github-token: ${{ steps.generate-token.outputs.token }}
           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 +60,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 +78,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 +96,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 +134,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 +214,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 +246,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 +264,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

@@ -16,6 +16,9 @@ on:
   schedule:
     - cron: "30 18 * * 4"
 
+# Deny by default; the analyze job opts in to exactly what it needs.
+permissions: {}
+
 jobs:
   analyze:
     name: Analyze (${{ matrix.language }})
@@ -26,15 +29,10 @@ jobs:
     # Consider using larger runners or machines with greater resources for possible analysis time improvements.
     runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
     permissions:
-      # required for all workflows
-      security-events: write
-
-      # required to fetch internal or private CodeQL packs
-      packages: read
-
-      # only required for workflows in private repositories
-      actions: read
-      contents: read
+      security-events: write  # upload CodeQL SARIF results to the Code Scanning API
+      packages: read          # fetch internal or private CodeQL query packs
+      actions: read           # required by codeql-action when run from a private repo
+      contents: read          # actions/checkout to scan the repository
 
     strategy:
       fail-fast: false
@@ -54,11 +52,11 @@ jobs:
             # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@e296a935590eb16afc0c0108289f68c87e2a89a5 # v4.30.7
+        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
@@ -86,6 +84,6 @@ jobs:
           exit 1
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@e296a935590eb16afc0c0108289f68c87e2a89a5 # v4.30.7
+        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           category: "/language:${{matrix.language}}"

.github/workflows/dashboard-deprecation-comment.yml

@@ -0,0 +1,113 @@
+name: Add Dashboard Deprecation Comment
+
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+
+# All API calls (pulls.listFiles + issues.{list,create,update}Comment) are performed with
+# the App token minted below, so the workflow's GITHUB_TOKEN does not need any scopes.
+permissions: {}
+
+jobs:
+  dashboard-deprecation-comment:
+    name: Dashboard deprecation comment
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          # pulls.listFiles + issues.{list,create,update}Comment on PRs. For PR resources
+          # the issues.*Comment APIs require the pull-requests scope, not issues.
+          permission-pull-requests: write
+
+      - name: Add dashboard deprecation comment
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          github-token: ${{ steps.generate-token.outputs.token }}
+          script: |
+            const commentMarker = "<!-- This comment was generated automatically by the dashboard-deprecation-comment workflow. -->";
+
+            const commentBody = `Thanks for opening this PR!
+
+            Heads up: the legacy ESPHome dashboard (\`esphome/dashboard/\` and \`tests/dashboard/\`) is **deprecated** and is being replaced by [ESPHome Device Builder](https://github.com/esphome/device-builder). We are not adding new features to the legacy dashboard and it will eventually be removed from this repository.
+
+            What this means for your PR:
+
+            - **New features / enhancements**: please port the change to [esphome/device-builder](https://github.com/esphome/device-builder) instead. We are unlikely to review or merge new dashboard features here.
+            - **Bug fixes**: small fixes may still be considered, but please check first whether the same issue exists in Device Builder, where the fix will have a longer life.
+            - **Security issues**: please do not file a public PR. Report privately via [GitHub security advisories](https://github.com/esphome/esphome/security/advisories/new) so we can coordinate a fix.
+
+            We appreciate the contribution and apologize for the friction; flagging this early so your time isn't spent on a change that may not land.
+
+            ---
+            (Added by the PR bot)
+
+            ${commentMarker}`;
+
+            async function getDashboardChanges(github, owner, repo, prNumber) {
+                const changedFiles = await github.paginate(
+                    github.rest.pulls.listFiles,
+                    {
+                        owner: owner,
+                        repo: repo,
+                        pull_number: prNumber,
+                        per_page: 100,
+                    }
+                );
+
+                return changedFiles.filter(file =>
+                    file.filename.startsWith('esphome/dashboard/') ||
+                    file.filename.startsWith('tests/dashboard/')
+                );
+            }
+
+            async function findBotComment(github, owner, repo, prNumber) {
+                const comments = await github.paginate(
+                    github.rest.issues.listComments,
+                    {
+                        owner: owner,
+                        repo: repo,
+                        issue_number: prNumber,
+                        per_page: 100,
+                    }
+                );
+
+                return comments.find(comment =>
+                    comment.body.includes(commentMarker) && comment.user.type === "Bot"
+                );
+            }
+
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            const dashboardChanges = await getDashboardChanges(github, owner, repo, prNumber);
+            const existingComment = await findBotComment(github, owner, repo, prNumber);
+
+            if (dashboardChanges.length === 0) {
+                // PR doesn't (or no longer) touches the legacy dashboard. If we previously
+                // commented (e.g. files were removed in a later push), leave the comment in
+                // place for history rather than thrash on edit/delete.
+                return;
+            }
+
+            if (existingComment) {
+                if (existingComment.body === commentBody) {
+                    return;
+                }
+                await github.rest.issues.updateComment({
+                    owner: owner,
+                    repo: repo,
+                    comment_id: existingComment.id,
+                    body: commentBody,
+                });
+            } else {
+                await github.rest.issues.createComment({
+                    owner: owner,
+                    repo: repo,
+                    issue_number: prNumber,
+                    body: commentBody,
+                });
+            }

.github/workflows/external-component-bot.yml

@@ -4,20 +4,29 @@ on:
   pull_request_target:
     types: [opened, synchronize]
 
-permissions:
-  contents: read       #  Needed to fetch PR details
-  issues: write        #  Needed to create and update comments (PR comments are managed via the issues REST API)
-  pull-requests: write  # also needed?
+# All API calls (pulls.listFiles + issues.{list,create,update}Comment) are performed with
+# the App token minted below, so the workflow's GITHUB_TOKEN does not need any scopes.
+permissions: {}
 
 jobs:
   external-comment:
     name: External component comment
     runs-on: ubuntu-latest
     steps:
-      - name: Add external component comment
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
         with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          # pulls.listFiles + issues.{list,create,update}Comment on PRs. For PR resources
+          # the issues.*Comment APIs require the pull-requests scope, not issues.
+          permission-pull-requests: write
+
+      - name: Add external component comment
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          github-token: ${{ steps.generate-token.outputs.token }}
           script: |
             // Generate external component usage instructions
             function generateExternalComponentInstructions(prNumber, componentNames, owner, repo) {

.github/workflows/issue-codeowner-notify.yml

@@ -9,8 +9,8 @@ on:
     types: [labeled]
 
 permissions:
-  issues: write
-  contents: read
+  issues: write   # issues.createComment to mention component codeowners on the newly labelled issue
+  contents: read  # repos.getContent to fetch CODEOWNERS from the default branch
 
 jobs:
   notify-codeowners:
@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Notify codeowners for component issues
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const owner = context.repo.owner;

.github/workflows/lock.yml

@@ -6,6 +6,12 @@ on:
     - cron: "30 0 * * *"  # Run daily at 00:30 UTC
   workflow_dispatch:
 
+# Deny by default; the lock job opts in to exactly what the reusable workflow needs.
+permissions: {}
+
 jobs:
   lock:
-    uses: esphome/workflows/.github/workflows/lock.yml@main
+    permissions:
+      issues: write         # issues.lock on closed issues
+      pull-requests: write  # issues.lock on closed pull requests
+    uses: esphome/workflows/.github/workflows/lock.yml@025a1e6255610c498ed590403b7e510b69e474df  # 2026.4.1

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

@@ -0,0 +1,96 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+    branches-ignore:
+      - release
+      - beta
+
+permissions:
+  contents: read       # actions/checkout to load detect-tags.js
+  pull-requests: read  # pulls.listFiles to map changed files to component/core/dashboard/ci tags
+
+jobs:
+  check:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.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 for angle brackets not wrapped in backticks.
+            // Astro docs MDX treats bare < as JSX component opening tags.
+            const stripped = title.replace(/`[^`]*`/g, '');
+            if (/[<>]/.test(stripped)) {
+              core.setFailed(
+                'PR title contains `<` or `>` not wrapped in backticks.\n' +
+                'Astro docs MDX interprets bare `<` as JSX components.\n' +
+                'Please wrap angle brackets with backticks, e.g.: [component] Add `<feature>` support'
+              );
+              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

@@ -9,7 +9,7 @@ on:
     - cron: "0 2 * * *"
 
 permissions:
-  contents: read
+  contents: read  # actions/checkout for all jobs; deploy jobs add their own scopes when they need to write
 
 jobs:
   init:
@@ -20,7 +20,7 @@ jobs:
       branch_build: ${{ steps.tag.outputs.branch_build }}
       deploy_env: ${{ steps.tag.outputs.deploy_env }}
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Get tag
         id: tag
         # yamllint disable rule:line-length
@@ -57,12 +57,12 @@ jobs:
     if: github.repository == 'esphome/esphome' && github.event_name == 'release'
     runs-on: ubuntu-latest
     permissions:
-      contents: read
-      id-token: write
+      contents: read   # actions/checkout to build the sdist/wheel
+      id-token: write  # OIDC token for PyPI Trusted Publishing (pypa/gh-action-pypi-publish)
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up Python
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.x"
       - name: Build
@@ -70,7 +70,7 @@ jobs:
           pip3 install build
           python3 -m build
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
         with:
           skip-existing: true
 
@@ -78,8 +78,8 @@ jobs:
     name: Build ESPHome ${{ matrix.platform.arch }}
     if: github.repository == 'esphome/esphome'
     permissions:
-      contents: read
-      packages: write
+      contents: read   # actions/checkout to load Dockerfile and build context
+      packages: write  # docker/login-action + build-push-action push image digests to ghcr.io
     runs-on: ${{ matrix.platform.os }}
     needs: [init]
     strategy:
@@ -92,22 +92,22 @@ jobs:
             os: "ubuntu-24.04-arm"
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up Python
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Log in to docker hub
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           username: ${{ secrets.DOCKER_USER }}
           password: ${{ secrets.DOCKER_PASSWORD }}
       - name: Log in to the GitHub container registry
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.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@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: digests-${{ matrix.platform.arch }}
           path: /tmp/digests
@@ -152,8 +152,8 @@ jobs:
       - deploy-docker
     if: github.repository == 'esphome/esphome'
     permissions:
-      contents: read
-      packages: write
+      contents: read   # actions/checkout to load Dockerfile and build context
+      packages: write  # docker/login-action + build-push-action push image digests to ghcr.io
     strategy:
       fail-fast: false
       matrix:
@@ -168,27 +168,27 @@ jobs:
           - ghcr
           - dockerhub
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Download digests
-        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: digests-*
           path: /tmp/digests
           merge-multiple: true
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Log in to docker hub
         if: matrix.registry == 'dockerhub'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.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@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -219,10 +219,20 @@ jobs:
       - init
       - deploy-manifest
     steps:
-      - name: Trigger Workflow
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
         with:
-          github-token: ${{ secrets.DEPLOY_HA_ADDON_REPO_TOKEN }}
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          owner: esphome
+          repositories: home-assistant-addon
+          permission-actions: write  # actions.createWorkflowDispatch on the target repo (only API call made with this token)
+
+      - name: Trigger Workflow
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          github-token: ${{ steps.generate-token.outputs.token }}
           script: |
             let description = "ESPHome";
             if (context.eventName == "release") {
@@ -245,10 +255,20 @@ jobs:
     needs: [init]
     environment: ${{ needs.init.outputs.deploy_env }}
     steps:
-      - name: Trigger Workflow
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
         with:
-          github-token: ${{ secrets.DEPLOY_ESPHOME_SCHEMA_REPO_TOKEN }}
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          owner: esphome
+          repositories: esphome-schema
+          permission-actions: write  # actions.createWorkflowDispatch on the target repo (only API call made with this token)
+
+      - name: Trigger Workflow
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          github-token: ${{ steps.generate-token.outputs.token }}
           script: |
             github.rest.actions.createWorkflowDispatch({
               owner: "esphome",
@@ -259,3 +279,35 @@ jobs:
                 version: "${{ needs.init.outputs.tag }}",
               }
             })
+
+  version-notifier:
+    if: github.repository == 'esphome/esphome' && needs.init.outputs.branch_build == 'false'
+    runs-on: ubuntu-latest
+    needs:
+      - init
+      - deploy-manifest
+    steps:
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          owner: esphome
+          repositories: version-notifier
+          permission-actions: write  # actions.createWorkflowDispatch on the target repo (only API call made with this token)
+
+      - name: Trigger Workflow
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          github-token: ${{ steps.generate-token.outputs.token }}
+          script: |
+            github.rest.actions.createWorkflowDispatch({
+              owner: "esphome",
+              repo: "version-notifier",
+              workflow_id: "notify.yml",
+              ref: "main",
+              inputs: {
+                version: "${{ needs.init.outputs.tag }}",
+              }
+            })

.github/workflows/stale.yml

@@ -7,8 +7,8 @@ on:
   workflow_dispatch:
 
 permissions:
-  issues: write
-  pull-requests: write
+  issues: write         # actions/stale labels, comments on, and closes stale issues
+  pull-requests: write  # actions/stale labels, comments on, and closes stale pull requests
 
 concurrency:
   group: lock
@@ -19,11 +19,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Stale
-        uses: actions/stale@5f858e3efba33a5ca4407a664cc011ad407f2008 # v10.1.0
+        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
-          operations-per-run: 150
+          operations-per-run: 400
 
           # The 90 day stale policy for PRs
           # - PRs

.github/workflows/status-check-labels.yml

@@ -2,29 +2,32 @@ name: Status check labels
 
 on:
   pull_request:
-    types: [labeled, unlabeled]
+    types: [opened, reopened, labeled, unlabeled, synchronize]
+
+permissions:
+  pull-requests: read  # issues.listLabelsOnIssue to detect blocking labels (needs-docs, merge-after-release, chained-pr)
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
 
 jobs:
   check:
-    name: Check ${{ matrix.label }}
+    name: Check blocking labels
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        label:
-          - needs-docs
-          - merge-after-release
     steps:
-      - name: Check for ${{ matrix.label }} label
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - name: Check for blocking labels
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
+            const blockingLabels = ['needs-docs', 'merge-after-release', 'chained-pr'];
             const { data: labels } = await github.rest.issues.listLabelsOnIssue({
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: context.issue.number
             });
-            const hasLabel = labels.find(label => label.name === '${{ matrix.label }}');
-            if (hasLabel) {
-              core.setFailed('Pull request cannot be merged, it is labeled as ${{ matrix.label }}');
+            const labelNames = labels.map(l => l.name);
+            const found = blockingLabels.filter(bl => labelNames.includes(bl));
+            if (found.length > 0) {
+              core.setFailed(`Pull request cannot be merged, it has blocking label(s): ${found.join(', ')}`);
             }

.github/workflows/sync-device-classes.yml

@@ -6,25 +6,40 @@ on:
   schedule:
     - cron: "45 6 * * *"
 
+# Repo writes (branch push, PR open) happen via the App token minted below,
+# so the workflow's GITHUB_TOKEN does not need any write scopes.
+permissions:
+  contents: read  # actions/checkout for this repo and home-assistant/core
+
 jobs:
   sync:
     name: Sync Device Classes
     runs-on: ubuntu-latest
     if: github.repository == 'esphome/esphome'
     steps:
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ vars.ESPHOME_GITHUB_APP_CLIENT_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+          # Scope the minted App token to the minimum needed by peter-evans/create-pull-request.
+          permission-contents: write       # git.createCommit + refs.create/update to push the sync/device-classes branch
+          permission-pull-requests: write  # pulls.create / pulls.update to open or refresh the sync PR
+
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Checkout Home Assistant
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: home-assistant/core
           path: lib/home-assistant
 
       - name: Setup Python
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
-          python-version: 3.13
+          python-version: "3.14"
 
       - name: Install Home Assistant
         run: |
@@ -41,7 +56,7 @@ jobs:
           python script/run-in-env.py pre-commit run --all-files
 
       - name: Commit changes
-        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           commit-message: "Synchronise Device Classes from Home Assistant"
           committer: esphomebot <esphome@openhomefoundation.org>
@@ -50,4 +65,4 @@ jobs:
           delete-branch: true
           title: "Synchronise Device Classes from Home Assistant"
           body-path: .github/PULL_REQUEST_TEMPLATE.md
-          token: ${{ secrets.DEVICE_CLASS_SYNC_TOKEN }}
+          token: ${{ steps.generate-token.outputs.token }}

.gitignore

@@ -91,6 +91,10 @@ venv-*/
 # mypy
 .mypy_cache/
 
+# nix
+/default.nix
+/shell.nix
+
 .pioenvs
 .piolibdeps
 .pio
@@ -142,5 +146,6 @@ sdkconfig.*
 
 /components
 /managed_components
+/dependencies.lock
 
 api-docs/

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ ci:
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.14.0
+    rev: v0.15.12
     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]
@@ -55,9 +55,10 @@ repos:
     hooks:
       - id: pylint
         name: pylint
-        entry: python3 script/run-in-env.py pylint
+        entry: python script/run-in-env.py pylint
         language: system
         types: [python]
+        files: ^esphome/.+\.py$
       - id: clang-tidy-hash
         name: Update clang-tidy hash
         entry: python script/clang_tidy_hash.py --update-if-changed
@@ -65,3 +66,7 @@ repos:
         files: ^(\.clang-tidy|platformio\.ini|requirements_dev\.txt)$
         pass_filenames: false
         additional_dependencies: []
+      - id: ci-custom
+        name: ci-custom
+        entry: python script/run-in-env.py script/ci-custom.py
+        language: system

AGENTS.md

@@ -0,0 +1,700 @@
+# ESPHome AI Collaboration Guide
+
+This document provides essential context for AI models interacting with this project. Adhering to these guidelines will ensure consistency and maintain code quality.
+
+## 1. Project Overview & Purpose
+
+*   **Primary Goal:** ESPHome is a system to configure microcontrollers (like ESP32, ESP8266, RP2040, and LibreTiny-based chips) using simple yet powerful YAML configuration files. It generates C++ firmware that can be compiled and flashed to these devices, allowing users to control them remotely through home automation systems.
+*   **Business Domain:** Internet of Things (IoT), Home Automation.
+
+## 2. Core Technologies & Stack
+
+*   **Languages:** Python (>=3.11), C++ (gnu++20)
+*   **Frameworks & Runtimes:** PlatformIO, Arduino, ESP-IDF.
+*   **Build Systems:** PlatformIO is the primary build system. CMake is used as an alternative.
+*   **Configuration:** YAML.
+*   **Key Libraries/Dependencies:**
+    *   **Python:** `voluptuous` (for configuration validation), `PyYAML` (for parsing configuration files), `paho-mqtt` (for MQTT communication), `tornado` (for the web server), `aioesphomeapi` (for the native API).
+    *   **C++:** `ArduinoJson` (for JSON serialization/deserialization), `AsyncMqttClient-esphome` (for MQTT), `ESPAsyncWebServer` (for the web server).
+*   **Package Manager(s):** `pip` (for Python dependencies), `platformio` (for C++/PlatformIO dependencies).
+*   **Communication Protocols:** Protobuf (for native API), MQTT, HTTP.
+
+## 3. Architectural Patterns
+
+*   **Overall Architecture:** The project follows a code-generation architecture. The Python code parses user-defined YAML configuration files and generates C++ source code. This C++ code is then compiled and flashed to the target microcontroller using PlatformIO.
+
+*   **Directory Structure Philosophy:**
+    *   `/esphome`: Contains the core Python source code for the ESPHome application.
+    *   `/esphome/components`: Contains the individual components that can be used in ESPHome configurations. Each component is a self-contained unit with its own C++ and Python code.
+    *   `/tests`: Contains all unit and integration tests for the Python code.
+    *   `/docker`: Contains Docker-related files for building and running ESPHome in a container.
+    *   `/script`: Contains helper scripts for development and maintenance.
+
+*   **Core Architectural Components:**
+    1.  **Configuration System** (`esphome/config*.py`): Handles YAML parsing and validation using Voluptuous, schema definitions, and multi-platform configurations.
+    2.  **Code Generation** (`esphome/codegen.py`, `esphome/cpp_generator.py`): Manages Python to C++ code generation, template processing, and build flag management.
+    3.  **Component System** (`esphome/components/`): Contains modular hardware and software components with platform-specific implementations and dependency management.
+    4.  **Core Framework** (`esphome/core/`): Manages the application lifecycle, hardware abstraction, and component registration.
+    5.  **Dashboard** (`esphome/dashboard/`): A web-based interface for device configuration, management, and OTA updates.
+
+*   **Platform Support:**
+    1.  **ESP32** (`components/esp32/`): Espressif ESP32 family. Supports multiple variants (Original, C2, C3, C5, C6, H2, P4, S2, S3) with ESP-IDF framework. Arduino framework supports only a subset of the variants (Original, C3, S2, S3).
+    2.  **ESP8266** (`components/esp8266/`): Espressif ESP8266. Arduino framework only, with memory constraints.
+    3.  **RP2040** (`components/rp2040/`): Raspberry Pi Pico/RP2040. Arduino framework with PIO (Programmable I/O) support.
+    4.  **LibreTiny** (`components/libretiny/`): Realtek and Beken chips. Supports multiple chip families and auto-generated components.
+
+## 4. Coding Conventions & Style Guide
+
+*   **Formatting:**
+    *   **Python:** Uses `ruff` and `flake8` for linting and formatting. Configuration is in `pyproject.toml`.
+    *   **C++:** Uses `clang-format` for formatting. Configuration is in `.clang-format`.
+
+*   **Naming Conventions:**
+    *   **Python:** Follows PEP 8. Use clear, descriptive names following snake_case.
+    *   **C++:** Follows the Google C++ Style Guide with these specifics (following clang-tidy conventions):
+        - Function, method, and variable names: `lower_snake_case`
+        - Class/struct/enum names: `UpperCamelCase`
+        - Top-level constants (global/namespace scope): `UPPER_SNAKE_CASE`
+        - Function-local constants: `lower_snake_case`
+        - Protected/private fields: `lower_snake_case_with_trailing_underscore_`
+        - Favor descriptive names over abbreviations
+
+*   **C++ Field Visibility:**
+    *   **Prefer `protected`:** Use `protected` for most class fields to enable extensibility and testing. Fields should be `lower_snake_case_with_trailing_underscore_`.
+    *   **Use `private` for safety-critical cases:** Use `private` visibility when direct field access could introduce bugs or violate invariants:
+        1. **Pointer lifetime issues:** When setters validate and store pointers from known lists to prevent dangling references.
+           ```cpp
+           // Helper to find matching string in vector and return its pointer
+           inline const char *vector_find(const std::vector<const char *> &vec, const char *value) {
+             for (const char *item : vec) {
+               if (strcmp(item, value) == 0)
+                 return item;
+             }
+             return nullptr;
+           }
+
+           class ClimateDevice {
+            public:
+             void set_custom_fan_modes(std::initializer_list<const char *> modes) {
+               this->custom_fan_modes_ = modes;
+               this->active_custom_fan_mode_ = nullptr;  // Reset when modes change
+             }
+             bool set_custom_fan_mode(const char *mode) {
+               // Find mode in supported list and store that pointer (not the input pointer)
+               const char *validated_mode = vector_find(this->custom_fan_modes_, mode);
+               if (validated_mode != nullptr) {
+                 this->active_custom_fan_mode_ = validated_mode;
+                 return true;
+               }
+               return false;
+             }
+            private:
+             std::vector<const char *> custom_fan_modes_;  // Pointers to string literals in flash
+             const char *active_custom_fan_mode_{nullptr};  // Must point to entry in custom_fan_modes_
+           };
+           ```
+        2. **Invariant coupling:** When multiple fields must remain synchronized to prevent buffer overflows or data corruption.
+           ```cpp
+           class Buffer {
+            public:
+             void resize(size_t new_size) {
+               auto new_data = std::make_unique<uint8_t[]>(new_size);
+               if (this->data_) {
+                 std::memcpy(new_data.get(), this->data_.get(), std::min(this->size_, new_size));
+               }
+               this->data_ = std::move(new_data);
+               this->size_ = new_size;  // Must stay in sync with data_
+             }
+            private:
+             std::unique_ptr<uint8_t[]> data_;
+             size_t size_{0};  // Must match allocated size of data_
+           };
+           ```
+        3. **Resource management:** When setters perform cleanup or registration operations that derived classes might skip.
+    *   **Provide `protected` accessor methods:** When derived classes need controlled access to `private` members.
+
+*   **C++ Preprocessor Directives:**
+    *   **Avoid `#define` for constants:** Using `#define` for constants is discouraged and should be replaced with `const` variables or enums.
+    *   **Use `#define` only for:**
+        - Conditional compilation (`#ifdef`, `#ifndef`)
+        - Compile-time sizes calculated during Python code generation (e.g., configuring `std::array` or `StaticVector` dimensions via `cg.add_define()`)
+
+*   **C++ Additional Conventions:**
+    *   **Member access:** Prefix all class member access with `this->` (e.g., `this->value_` not `value_`)
+    *   **Indentation:** Use spaces (two per indentation level), not tabs
+    *   **Type aliases:** Prefer `using type_t = int;` over `typedef int type_t;`
+    *   **Line length:** Wrap lines at no more than 120 characters
+    *   **Constructor parameters vs setters:** Component properties that are both **required** and **invariant**
+        (never change after construction) should be constructor parameters rather than set via setter methods.
+        This makes the dependency explicit and prevents use of the object in an incompletely-initialized state.
+        In code generation, when calling `cg.new_Pvariable()` or the relevant helper function to create the component, pass these as arguments.
+        ```cpp
+        // Good - required invariant dependency as constructor parameter
+        class SourceTextSensor : public text_sensor::TextSensor, public Component {
+         public:
+          explicit SourceTextSensor(text::Text *source) : source_(source) {}
+         protected:
+          text::Text *source_;
+        };
+        ```
+        ```cpp
+        // Bad - required invariant dependency as setter
+        class SourceTextSensor : public text_sensor::TextSensor, public Component {
+         public:
+          void set_source(text::Text *source) { this->source_ = source; }
+         protected:
+          text::Text *source_{nullptr};
+        };
+        ```
+
+*   **Component Structure:**
+    *   **Standard Files:**
+        ```
+        components/[component_name]/
+        ├── __init__.py          # Component configuration schema and code generation
+        ├── [component].h        # C++ header file (if needed)
+        ├── [component].cpp      # C++ implementation (if needed)
+        └── [platform]/          # Platform-specific implementations
+            ├── __init__.py      # Platform-specific configuration
+            ├── [platform].h     # Platform C++ header
+            └── [platform].cpp   # Platform C++ implementation
+        ```
+
+    *   **Component Metadata:**
+        - `DEPENDENCIES`: List of required components
+        - `AUTO_LOAD`: Components to automatically load
+        - `CONFLICTS_WITH`: Incompatible components
+        - `CODEOWNERS`: GitHub usernames responsible for maintenance
+        - `MULTI_CONF`: Whether multiple instances are allowed
+
+*   **Code Generation & Common Patterns:**
+    *   **Configuration Schema Pattern:**
+        ```python
+        import esphome.codegen as cg
+        import esphome.config_validation as cv
+        from esphome.const import CONF_KEY, CONF_ID
+
+        CONF_PARAM = "param"  # A constant that does not yet exist in esphome/const.py
+
+        my_component_ns = cg.esphome_ns.namespace("my_component")
+        MyComponent = my_component_ns.class_("MyComponent", cg.Component)
+
+        CONFIG_SCHEMA = cv.Schema({
+            cv.GenerateID(): cv.declare_id(MyComponent),
+            cv.Required(CONF_KEY): cv.string,
+            cv.Optional(CONF_PARAM, default=42): cv.int_,
+        }).extend(cv.COMPONENT_SCHEMA)
+
+        async def to_code(config):
+            var = cg.new_Pvariable(config[CONF_ID])
+            await cg.register_component(var, config)
+            cg.add(var.set_key(config[CONF_KEY]))
+            cg.add(var.set_param(config[CONF_PARAM]))
+        ```
+
+    *   **C++ Class Pattern:**
+        ```cpp
+        namespace esphome::my_component {
+
+        class MyComponent : public Component {
+         public:
+          void setup() override;
+          void loop() override;
+          void dump_config() override;
+
+          void set_key(const std::string &key) { this->key_ = key; }
+          void set_param(int param) { this->param_ = param; }
+
+         protected:
+          std::string key_;
+          int param_{0};
+        };
+
+        }  // namespace esphome::my_component
+        ```
+
+    *   **Common Component Examples:**
+        - **Sensor:**
+          ```python
+          from esphome.components import sensor
+          CONFIG_SCHEMA = sensor.sensor_schema(MySensor).extend(cv.polling_component_schema("60s"))
+          async def to_code(config):
+              var = await sensor.new_sensor(config)
+              await cg.register_component(var, config)
+          ```
+
+        - **Binary Sensor:**
+          ```python
+          from esphome.components import binary_sensor
+          CONFIG_SCHEMA = binary_sensor.binary_sensor_schema().extend({ ... })
+          async def to_code(config):
+              var = await binary_sensor.new_binary_sensor(config)
+          ```
+
+        - **Switch:**
+          ```python
+          from esphome.components import switch
+          CONFIG_SCHEMA = switch.switch_schema().extend({ ... })
+          async def to_code(config):
+              var = await switch.new_switch(config)
+          ```
+
+*   **Automations (Triggers, Actions, Conditions):**
+
+    Automations have three building blocks: **Triggers** (fire when something happens), **Actions** (do something), and **Conditions** (check if something is true).
+
+    *   **Triggers -- Callback method (preferred):**
+
+        Use `build_callback_automation()` for simple triggers. This eliminates the need for a C++ Trigger class by using a lightweight pointer-sized forwarder struct registered directly as a callback. No `CONF_TRIGGER_ID` in the schema.
+
+        **Python:**
+        ```python
+        from esphome import automation
+
+        CONFIG_SCHEMA = cv.Schema({
+            cv.GenerateID(): cv.declare_id(MyComponent),
+            cv.Optional(CONF_ON_STATE): automation.validate_automation({}),
+        }).extend(cv.COMPONENT_SCHEMA)
+
+        async def to_code(config):
+            var = cg.new_Pvariable(config[CONF_ID])
+            await cg.register_component(var, config)
+            for conf in config.get(CONF_ON_STATE, []):
+                await automation.build_callback_automation(
+                    var, "add_on_state_callback", [(bool, "x")], conf
+                )
+        ```
+
+        `build_callback_automation` arguments: `parent`, `callback_method` (C++ method name), `args` (template args as `[(type, name)]` tuples), `config`, and optional `forwarder` (defaults to `TriggerForwarder<Ts...>`).
+
+        For boolean filtering (e.g. `on_press`/`on_release`), use built-in forwarders with `args=[]`:
+        ```python
+        for conf_key, forwarder in (
+            (CONF_ON_PRESS, automation.TriggerOnTrueForwarder),
+            (CONF_ON_RELEASE, automation.TriggerOnFalseForwarder),
+        ):
+            for conf in config.get(conf_key, []):
+                await automation.build_callback_automation(
+                    var, "add_on_state_callback", [], conf, forwarder=forwarder
+                )
+        ```
+
+        **C++ -- no trigger class needed.** The callback registration method must be templatized to accept both `std::function` and lightweight forwarder structs (which avoid heap allocation):
+        ```cpp
+        class MyComponent : public Component {
+         public:
+          // Must be a template -- accepts both std::function and pointer-sized forwarder structs
+          template<typename F> void add_on_state_callback(F &&callback) {
+            this->state_callback_.add(std::forward<F>(callback));
+          }
+         protected:
+          // Use CallbackManager when callbacks are always registered (e.g. core components)
+          CallbackManager<void(bool)> state_callback_;
+          // Use LazyCallbackManager when callbacks are often not registered -- saves 8 bytes
+          // (nullptr vs empty std::vector) per instance when no callbacks are added
+          // LazyCallbackManager<void(bool)> state_callback_;
+        };
+        ```
+
+    *   **Triggers -- Trigger class method:**
+
+        Use `build_automation()` with a `Trigger<Ts...>` subclass only when the forwarder needs **mutable state beyond a single `Automation*` pointer** (e.g. edge detection tracking previous state, timing logic).
+
+        **Python:**
+        ```python
+        TurnOnTrigger = my_ns.class_("TurnOnTrigger", automation.Trigger.template())
+
+        CONFIG_SCHEMA = cv.Schema({
+            cv.Optional(CONF_ON_TURN_ON): automation.validate_automation(
+                {cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(TurnOnTrigger)}
+            ),
+        })
+
+        async def to_code(config):
+            for conf in config.get(CONF_ON_TURN_ON, []):
+                trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
+                await automation.build_automation(trigger, [], conf)
+        ```
+
+        **C++:**
+        ```cpp
+        class TurnOnTrigger : public Trigger<> {
+         public:
+          explicit TurnOnTrigger(MyComponent *parent) : last_on_{false} {
+            parent->add_on_state_callback([this](bool state) {
+              if (state && !this->last_on_)
+                this->trigger();
+              this->last_on_ = state;
+            });
+          }
+         protected:
+          bool last_on_;
+        };
+        ```
+
+    *   **Actions:**
+        ```cpp
+        template<typename... Ts> class MyAction : public Action<Ts...> {
+         public:
+          explicit MyAction(MyComponent *parent) : parent_(parent) {}
+          void play(const Ts &...) override { this->parent_->do_something(); }
+         protected:
+          MyComponent *parent_;
+        };
+        ```
+        Register with `@automation.register_action("my_component.do_something", MyAction, schema, synchronous=True)`. Use `synchronous=True` for actions that run to completion inside `play()` without deferring. Use `synchronous=False` if the action may suspend/defer execution (e.g. `delay`, `wait_until`, `script.wait`) or store trigger arguments for later use.
+
+    *   **Conditions:**
+        ```cpp
+        template<typename... Ts> class MyCondition : public Condition<Ts...> {
+         public:
+          explicit MyCondition(MyComponent *parent) : parent_(parent) {}
+          bool check(const Ts &...) override { return this->parent_->is_active(); }
+         protected:
+          MyComponent *parent_;
+        };
+        ```
+        Register with `@automation.register_condition("my_component.is_active", MyCondition, schema)`.
+
+*   **Configuration Validation:**
+    *   **Common Validators:** `cv.int_`, `cv.float_`, `cv.string`, `cv.boolean`, `cv.int_range(min=0, max=100)`, `cv.positive_int`, `cv.percentage`.
+    *   **Complex Validation:** `cv.All(cv.string, cv.Length(min=1, max=50))`, `cv.Any(cv.int_, cv.string)`.
+    *   **Platform-Specific:** `cv.only_on(["esp32", "esp8266"])`, `esp32.only_on_variant(...)`, `cv.only_on_esp32`, `cv.only_on_esp8266`, `cv.only_on_rp2040`.
+    *   **Framework-Specific:** `cv.only_with_framework(...)`, `cv.only_with_arduino`, `cv.only_with_esp_idf`.
+    *   **Schema Extensions:**
+        ```python
+        CONFIG_SCHEMA = cv.Schema({ ... })
+         .extend(cv.COMPONENT_SCHEMA)
+         .extend(uart.UART_DEVICE_SCHEMA)
+         .extend(i2c.i2c_device_schema(0x48))
+         .extend(spi.spi_device_schema(cs_pin_required=True))
+        ```
+
+## 5. Key Files & Entrypoints
+
+*   **Main Entrypoint(s):** `esphome/__main__.py` is the main entrypoint for the ESPHome command-line interface.
+*   **Configuration:**
+    *   `pyproject.toml`: Defines the Python project metadata and dependencies.
+    *   `platformio.ini`: Configures the PlatformIO build environments for different microcontrollers.
+    *   `.pre-commit-config.yaml`: Configures the pre-commit hooks for linting and formatting.
+*   **CI/CD Pipeline:** Defined in `.github/workflows`.
+*   **Static Analysis & Development:**
+    *   `esphome/core/defines.h`: A comprehensive header file containing all `#define` directives that can be added by components using `cg.add_define()` in Python. This file is used exclusively for development, static analysis tools, and CI testing - it is not used during runtime compilation. When developing components that add new defines, they must be added to this file to ensure proper IDE support and static analysis coverage. The file includes feature flags, build configurations, and platform-specific defines that help static analyzers understand the complete codebase without needing to compile for specific platforms.
+
+## 6. Development & Testing Workflow
+
+*   **Local Development Environment:** Use the provided Docker container or create a Python virtual environment and install dependencies from `requirements_dev.txt`.
+*   **Running Commands:** Use the `script/run-in-env.py` script to execute commands within the project's virtual environment. For example, to run the linter: `python3 script/run-in-env.py pre-commit run`.
+*   **Testing:**
+    *   **Python:** Run unit tests with `pytest`.
+    *   **C++:** Use `clang-tidy` for static analysis.
+    *   **Component Tests:** YAML-based compilation tests are located in `tests/`. The structure is as follows:
+        ```
+        tests/
+        ├── test_build_components/
+        │   └── common/          # Shared bus packages (uart, i2c, spi, etc.)
+        │       ├── uart/        # UART at default baud rate
+        │       ├── uart_115200/ # UART at 115200 baud
+        │       ├── i2c/         # I2C bus
+        │       └── spi/         # SPI bus
+        └── components/[component]/
+            ├── common.yaml          # Component-only config (no bus definitions)
+            ├── test.esp32-idf.yaml      # config + compile
+            ├── test.esp8266-ard.yaml    # config + compile
+            ├── test-variant.esp32-idf.yaml  # variant test, config + compile
+            ├── validate.esp32-idf.yaml      # config-only (never compiled)
+            └── validate-legacy.esp32-idf.yaml  # config-only variant
+        ```
+        Run them using `script/test_build_components`. Use `-c <component>` to test specific components and `-t <target>` for specific platforms.
+
+    *   **Config-only test files (`validate.*.yaml`):** Use this prefix when a YAML file only needs to exercise schema/validation paths and does not need to be compiled. CI runs `validate.*.yaml` files with `esphome config` only and skips them during compile. The grammar mirrors `test.*.yaml`:
+        - `validate.<platform>.yaml` — base config-only test
+        - `validate-<variant>.<platform>.yaml` — config-only variant
+
+        Use this for things like deprecated-syntax migration tests, schema edge cases, or platform-specific validation branches where building firmware adds no signal. A component may have any mix of `test.*.yaml` and `validate.*.yaml` files. Validate files never participate in bus-grouping; each one runs as its own `esphome config` invocation.
+
+        When a PR's only edits to a component are `validate.*.yaml` files (no source changes, no `test.*.yaml` changes, and the component isn't pulled in as a dependency of another changed component), CI skips the compile stage for that component entirely and only runs config validation. This is decided in `script/determine-jobs.py` via `_component_change_is_validate_only` and surfaced as the `validate_only_components` output that the `test-build-components-split` job consumes.
+
+    *   **Test Grouping with Packages:** Components that use shared bus packages can be grouped together in CI to reduce build count. **Never define buses (uart, i2c, spi, modbus) directly in test YAML files** — always use packages from `test_build_components/common/`:
+        ```yaml
+        # test.esp32-idf.yaml — use packages for buses
+        packages:
+          uart: !include ../../test_build_components/common/uart_115200/esp32-idf.yaml
+
+        <<: !include common.yaml
+        ```
+        ```yaml
+        # common.yaml — component config only, NO bus definitions
+        my_component:
+          id: my_instance
+
+        sensor:
+          - platform: my_component
+            name: My Sensor
+        ```
+        Components that define buses directly are flagged as "NEEDS MIGRATION" and cannot be grouped, increasing CI build time.
+
+    *   **Testing All Components Together:** To verify that all components can be tested together without ID conflicts or configuration issues, use:
+        ```bash
+        ./script/test_component_grouping.py -e config --all
+        ```
+        This tests all components in a single build to catch conflicts that might not appear when testing components individually. Use `-e config` for fast configuration validation, or `-e compile` for full compilation testing.
+*   **Debugging and Troubleshooting:**
+    *   **Debug Tools:**
+        - `esphome config <file>.yaml` to validate configuration.
+        - `esphome compile <file>.yaml` to compile without uploading.
+        - Check the Dashboard for real-time logs.
+        - Use component-specific debug logging.
+    *   **Common Issues:**
+        - **Import Errors**: Check component dependencies and `PYTHONPATH`.
+        - **Validation Errors**: Review configuration schema definitions.
+        - **Build Errors**: Check platform compatibility and library versions.
+        - **Runtime Errors**: Review generated C++ code and component logic.
+
+## 7. Specific Instructions for AI Collaboration
+
+*   **Contribution Workflow (Pull Request Process):**
+    1.  **Fork & Branch:** Create a new branch based on the `dev` branch (always use `git checkout -b <branch-name> dev` to ensure you're branching from `dev`, not the currently checked out branch).
+    2.  **Make Changes:** Adhere to all coding conventions and patterns.
+    3.  **Test:** Create component tests for all supported platforms and run the full test suite locally.
+    4.  **Lint:** Run `pre-commit` to ensure code is compliant.
+    5.  **Commit:** Commit your changes. There is no strict format for commit messages.
+    6.  **Pull Request:** Submit a PR against the `dev` branch. The Pull Request title should have a prefix of the component being worked on (e.g., `[display] Fix bug`, `[abc123] Add new component`). Update documentation, examples, and add `CODEOWNERS` entries as needed. Pull requests should always be made using the `.github/PULL_REQUEST_TEMPLATE.md` template - fill out all sections completely without removing any parts of the template.
+
+*   **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.
+    *   **Code Generation:** Generate minimal and efficient C++ code. Validate all user inputs thoroughly. Support multiple platform variations.
+    *   **Configuration Design:** Aim for simplicity with sensible defaults, while allowing for advanced customization.
+    *   **Embedded Systems Optimization:** ESPHome targets resource-constrained microcontrollers. Be mindful of flash size and RAM usage.
+
+        **Why Heap Allocation Matters:**
+
+        ESP devices run for months with small heaps shared between Wi-Fi, BLE, LWIP, and application code. Over time, repeated allocations of different sizes fragment the heap. Failures happen when the largest contiguous block shrinks, even if total free heap is still large. We have seen field crashes caused by this.
+
+        **Heap allocation after `setup()` should be avoided unless absolutely unavoidable.** Every allocation/deallocation cycle contributes to fragmentation. ESPHome treats runtime heap allocation as a long-term reliability bug, not a performance issue. Helpers that hide allocation (`std::string`, `std::to_string`, string-returning helpers) are being deprecated and replaced with buffer and view based APIs.
+
+        **STL Container Guidelines:**
+
+        ESPHome runs on embedded systems with limited resources. Choose containers carefully:
+
+        1. **Compile-time-known sizes:** Use `std::array` instead of `std::vector` when size is known at compile time.
+           ```cpp
+           // Bad - generates STL realloc code
+           std::vector<int> values;
+
+           // Good - no dynamic allocation
+           std::array<int, MAX_VALUES> values;
+           ```
+           Use `cg.add_define("MAX_VALUES", count)` to set the size from Python configuration.
+
+           **For byte buffers:** Avoid `std::vector<uint8_t>` unless the buffer needs to grow. Use `std::unique_ptr<uint8_t[]>` instead.
+
+           > **Note:** `std::unique_ptr<uint8_t[]>` does **not** provide bounds checking or iterator support like `std::vector<uint8_t>`. Use it only when you do not need these features and want minimal overhead.
+
+           ```cpp
+           // Bad - STL overhead for simple byte buffer
+           std::vector<uint8_t> buffer;
+           buffer.resize(256);
+
+           // Good - minimal overhead, single allocation
+           std::unique_ptr<uint8_t[]> buffer = std::make_unique<uint8_t[]>(256);
+           // Or if size is constant:
+           std::array<uint8_t, 256> buffer;
+           ```
+
+        2. **Compile-time-known fixed sizes with vector-like API:** Use `StaticVector` from `esphome/core/helpers.h` for compile-time fixed size with `push_back()` interface (no dynamic allocation).
+           ```cpp
+           // Bad - generates STL realloc code (_M_realloc_insert)
+           std::vector<ServiceRecord> services;
+           services.reserve(5);  // Still includes reallocation machinery
+
+           // Good - compile-time fixed size, no dynamic allocation
+           StaticVector<ServiceRecord, MAX_SERVICES> services;
+           services.push_back(record1);
+           ```
+           Use `cg.add_define("MAX_SERVICES", count)` to set the size from Python configuration.
+           Like `std::array` but with vector-like API (`push_back()`, `size()`) and no STL reallocation code.
+
+        3. **Runtime-known sizes:** Use `FixedVector` from `esphome/core/helpers.h` when the size is only known at runtime initialization.
+           ```cpp
+           // Bad - generates STL realloc code (_M_realloc_insert)
+           std::vector<TxtRecord> txt_records;
+           txt_records.reserve(5);  // Still includes reallocation machinery
+
+           // Good - runtime size, single allocation, no reallocation machinery
+           FixedVector<TxtRecord> txt_records;
+           txt_records.init(record_count);  // Initialize with exact size at runtime
+           ```
+           **Benefits:**
+           - Eliminates `_M_realloc_insert`, `_M_default_append` template instantiations (saves 200-500 bytes per instance)
+           - Single allocation, no upper bound needed
+           - No reallocation overhead
+           - Compatible with protobuf code generation when using `[(fixed_vector) = true]` option
+
+        4. **Small datasets (1-16 elements):** Use `std::vector` or `std::array` with simple structs instead of `std::map`/`std::set`/`std::unordered_map`.
+           ```cpp
+           // Bad - 2KB+ overhead for red-black tree/hash table
+           std::map<std::string, int> small_lookup;
+           std::unordered_map<int, std::string> tiny_map;
+
+           // Good - simple struct with linear search (std::vector is fine)
+           struct LookupEntry {
+             const char *key;
+             int value;
+           };
+           std::vector<LookupEntry> small_lookup = {
+             {"key1", 10},
+             {"key2", 20},
+             {"key3", 30},
+           };
+           // Or std::array if size is compile-time constant:
+           // std::array<LookupEntry, 3> small_lookup = {{ ... }};
+           ```
+           Linear search on small datasets (1-16 elements) is often faster than hashing/tree overhead, but this depends on lookup frequency and access patterns. For frequent lookups in hot code paths, the O(1) vs O(n) complexity difference may still matter even for small datasets. `std::vector` with simple structs is usually fine—it's the heavy containers (`map`, `set`, `unordered_map`) that should be avoided for small datasets unless profiling shows otherwise.
+
+        5. **Avoid `std::deque`:** It allocates in 512-byte blocks regardless of element size, guaranteeing at least 512 bytes of RAM usage immediately. This is a major source of crashes on memory-constrained devices.
+
+        6. **Detection:** Look for these patterns in compiler output:
+           - Large code sections with STL symbols (vector, map, set)
+           - `alloc`, `realloc`, `dealloc` in symbol names
+           - `_M_realloc_insert`, `_M_default_append` (vector reallocation)
+           - Red-black tree code (`rb_tree`, `_Rb_tree`)
+           - Hash table infrastructure (`unordered_map`, `hash`)
+
+        **Prioritize optimization effort for:**
+        - Core components (API, network, logger)
+        - Widely-used components (mdns, wifi, ble)
+        - Components causing flash size complaints
+
+        Note: Avoiding heap allocation after `setup()` is always required regardless of component type. The prioritization above is about the effort spent on container optimization (e.g., migrating from `std::vector` to `StaticVector`).
+
+        **Callback Managers:**
+
+        ESPHome provides two callback manager types in `esphome/core/helpers.h` for the observer pattern. Both support `std::function`, lambdas, and lightweight forwarder structs via their templatized `add()` method.
+
+        | Type | Idle overhead (32-bit) | When to use |
+        |------|----------------------|-------------|
+        | `CallbackManager<void(Ts...)>` | 12 bytes (empty `std::vector`) | Callbacks are always or almost always registered |
+        | `LazyCallbackManager<void(Ts...)>` | 4 bytes (`nullptr`) | Callbacks are often not registered (common case) |
+
+        `LazyCallbackManager` is a drop-in replacement for `CallbackManager` that defers allocation until the first callback is added. Prefer it for entity-level callbacks where most instances have no subscribers.
+
+        **Important:** Registration methods that add to a callback manager **must always be templatized** to accept both `std::function` and pointer-sized forwarder structs (used by `build_callback_automation`). Never use `std::function` in the method signature:
+        ```cpp
+        // Bad -- forces heap allocation for forwarder structs
+        void add_on_state_callback(std::function<void(bool)> &&callback) {
+          this->state_callback_.add(std::move(callback));
+        }
+
+        // Good -- accepts any callable without forcing std::function wrapping
+        template<typename F> void add_on_state_callback(F &&callback) {
+          this->state_callback_.add(std::forward<F>(callback));
+        }
+        ```
+
+    *   **State Management:** Use `CORE.data` for component state that needs to persist during configuration generation. Avoid module-level mutable globals.
+
+        **Bad Pattern (Module-Level Globals):**
+        ```python
+        # Don't do this - state persists between compilation runs
+        _component_state = []
+        _use_feature = None
+
+        def enable_feature():
+            global _use_feature
+            _use_feature = True
+        ```
+
+        **Bad Pattern (Flat Keys):**
+        ```python
+        # Don't do this - keys should be namespaced under component domain
+        MY_FEATURE_KEY = "my_component_feature"
+        CORE.data[MY_FEATURE_KEY] = True
+        ```
+
+        **Good Pattern (dataclass):**
+        ```python
+        from dataclasses import dataclass, field
+        from esphome.core import CORE
+
+        DOMAIN = "my_component"
+
+        @dataclass
+        class MyComponentData:
+            feature_enabled: bool = False
+            item_count: int = 0
+            items: list[str] = field(default_factory=list)
+
+        def _get_data() -> MyComponentData:
+            if DOMAIN not in CORE.data:
+                CORE.data[DOMAIN] = MyComponentData()
+            return CORE.data[DOMAIN]
+
+        def request_feature() -> None:
+            _get_data().feature_enabled = True
+
+        def add_item(item: str) -> None:
+            _get_data().items.append(item)
+        ```
+
+        If you need a real-world example, search for components that use `@dataclass` with `CORE.data` in the codebase. Note: Some components may use `TypedDict` for dictionary-based storage; both patterns are acceptable depending on your needs.
+
+        **Why this matters:**
+        - Module-level globals persist between compilation runs if the dashboard doesn't fork/exec
+        - `CORE.data` automatically clears between runs
+        - Namespacing under `DOMAIN` prevents key collisions between components
+        - `@dataclass` provides type safety and cleaner attribute access
+
+*   **Security:** Be mindful of security when making changes to the API, web server, or any other network-related code. Do not hardcode secrets or keys.
+
+*   **Dependencies & Build System Integration:**
+    *   **Python:** When adding a new Python dependency, add it to the appropriate `requirements*.txt` file and `pyproject.toml`.
+    *   **C++ / PlatformIO:** When adding a new C++ dependency, add it to `platformio.ini` and use `cg.add_library`.
+    *   **Build Flags:** Use `cg.add_build_flag(...)` to add compiler flags.
+
+## 8. Public API and Breaking Changes
+
+*   **Public C++ API:**
+    *   **Components**: Only documented features at [esphome.io](https://esphome.io) are public API. Undocumented `public` members are internal.
+    *   **Core/Base Classes** (`esphome/core/`, `Component`, `Sensor`, etc.): All `public` members are public API.
+    *   **Components with Global Accessors** (`global_api_server`, etc.): All `public` members are public API (except config setters).
+
+*   **Public Python API:**
+    *   All documented configuration options at [esphome.io](https://esphome.io) are public API.
+    *   Python code in `esphome/core/` actively used by existing core components is considered stable API.
+    *   Other Python code is internal unless explicitly documented for external component use.
+
+*   **Breaking Changes Policy:**
+    *   Aim for **6-month deprecation window** when possible
+    *   Clean breaks allowed for: signature changes, deep refactorings, resource constraints
+    *   Must document migration path in PR description (generates release notes)
+    *   Blog post required for core/base class changes or significant architectural changes
+    *   Full details: https://developers.esphome.io/contributing/code/#public-api-and-breaking-changes
+
+*   **Breaking Change Checklist:**
+    - [ ] Clear justification (RAM/flash savings, architectural improvement)
+    - [ ] Explored non-breaking alternatives
+    - [ ] Added deprecation warnings if possible (use `ESPDEPRECATED` macro for C++)
+    - [ ] Documented migration path in PR description with before/after examples
+    - [ ] Updated all internal usage and esphome-docs
+    - [ ] Tested backward compatibility during deprecation period
+
+*   **Deprecation Pattern (C++):**
+    ```cpp
+    // Remove before 2026.6.0
+    ESPDEPRECATED("Use new_method() instead. Removed in 2026.6.0", "2025.12.0")
+    void old_method() { this->new_method(); }
+    ```
+
+*   **Deprecation Pattern (Python):**
+    ```python
+    # Remove before 2026.6.0
+    if CONF_OLD_KEY in config:
+        _LOGGER.warning(f"'{CONF_OLD_KEY}' deprecated, use '{CONF_NEW_KEY}'. Removed in 2026.6.0")
+        config[CONF_NEW_KEY] = config.pop(CONF_OLD_KEY)  # Auto-migrate
+    ```

CLAUDE.md

@@ -1 +1 @@
-.ai/instructions.md
+AGENTS.md

CODEOWNERS

@@ -21,6 +21,7 @@ esphome/components/adc128s102/* @DeerMaximum
 esphome/components/addressable_light/* @justfalter
 esphome/components/ade7880/* @kpfleming
 esphome/components/ade7953/* @angelnu
+esphome/components/ade7953_base/* @angelnu
 esphome/components/ade7953_i2c/* @angelnu
 esphome/components/ade7953_spi/* @angelnu
 esphome/components/ads1118/* @solomondg1
@@ -41,6 +42,7 @@ esphome/components/animation/* @syndlex
 esphome/components/anova/* @buxtronix
 esphome/components/apds9306/* @aodrenah
 esphome/components/api/* @esphome/core
+esphome/components/aqi/* @freekode @jasstrong @ximex
 esphome/components/as5600/* @ammmze
 esphome/components/as5600/sensor/* @ammmze
 esphome/components/as7341/* @mrgnr
@@ -52,6 +54,9 @@ 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/audio_http/* @kahrendt
 esphome/components/axs15231/* @clydebarrow
 esphome/components/b_parasite/* @rbaron
 esphome/components/ballu/* @bazuchan
@@ -62,6 +67,7 @@ esphome/components/bedjet/fan/* @jhansche
 esphome/components/bedjet/sensor/* @javawizard @jhansche
 esphome/components/beken_spi_led_strip/* @Mat931
 esphome/components/bh1750/* @OttoWinter
+esphome/components/bh1900nux/* @B48D81EFCC
 esphome/components/binary_sensor/* @esphome/core
 esphome/components/bk72xx/* @kuba2k2
 esphome/components/bl0906/* @athom-tech @jesserockz @tarontop
@@ -69,7 +75,9 @@ esphome/components/bl0939/* @ziceva
 esphome/components/bl0940/* @dan-s-github @tobias-
 esphome/components/bl0942/* @dbuezas @dwmw2
 esphome/components/ble_client/* @buxtronix @clydebarrow
+esphome/components/ble_nus/* @tomaszduda23
 esphome/components/bluetooth_proxy/* @bdraco @jesserockz
+esphome/components/bm8563/* @abmantis
 esphome/components/bme280_base/* @esphome/core
 esphome/components/bme280_spi/* @apbodrov
 esphome/components/bme680_bsec/* @trvrnrth
@@ -83,9 +91,12 @@ esphome/components/bmp3xx/* @latonita
 esphome/components/bmp3xx_base/* @latonita @martgras
 esphome/components/bmp3xx_i2c/* @latonita
 esphome/components/bmp3xx_spi/* @latonita
-esphome/components/bmp581/* @kahrendt
+esphome/components/bmp581_base/* @danielkent-net @kahrendt
+esphome/components/bmp581_i2c/* @danielkent-net @kahrendt
+esphome/components/bmp581_spi/* @danielkent-net @kahrendt
 esphome/components/bp1658cj/* @Cossid
 esphome/components/bp5758d/* @Cossid
+esphome/components/bthome_mithermometer/* @nagyrobi
 esphome/components/button/* @esphome/core
 esphome/components/bytebuffer/* @clydebarrow
 esphome/components/camera/* @bdraco @DT-art1
@@ -93,9 +104,11 @@ esphome/components/camera_encoder/* @DT-art1
 esphome/components/canbus/* @danielschramm @mvturnho
 esphome/components/cap1188/* @mreditor97
 esphome/components/captive_portal/* @esphome/core
+esphome/components/cc1101/* @gabest11 @lygris
 esphome/components/ccs811/* @habbie
 esphome/components/cd74hc4067/* @asoehlke
 esphome/components/ch422g/* @clydebarrow @jesterret
+esphome/components/ch423/* @dwmw2
 esphome/components/chsc6x/* @kkosik20
 esphome/components/climate/* @esphome/core
 esphome/components/climate_ir/* @glmnet
@@ -121,19 +134,22 @@ 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
 esphome/components/display_menu_base/* @numo68
+esphome/components/dlms_meter/* @SimonFischer04
 esphome/components/dps310/* @kbx81
 esphome/components/ds1307/* @badbadc0ffee
 esphome/components/ds2484/* @mrk-its
-esphome/components/dsmr/* @glmnet @zuidwijk
+esphome/components/dsmr/* @glmnet @PolarGoose
 esphome/components/duty_time/* @dudanov
 esphome/components/ee895/* @Stock-M
 esphome/components/ektf2232/touchscreen/* @jesserockz
 esphome/components/emc2101/* @ellull
 esphome/components/emmeti/* @E440QF
+esphome/components/emontx/* @FredM67 @glynhudson @TrystanLea
 esphome/components/ens160/* @latonita
 esphome/components/ens160_base/* @latonita @vincentscode
 esphome/components/ens160_i2c/* @latonita
@@ -153,12 +169,14 @@ esphome/components/esp32_ble_tracker/* @bdraco
 esphome/components/esp32_camera_web_server/* @ayufan
 esphome/components/esp32_can/* @Sympatron
 esphome/components/esp32_hosted/* @swoboda1337
+esphome/components/esp32_hosted/update/* @swoboda1337
 esphome/components/esp32_improv/* @jesserockz
 esphome/components/esp32_rmt/* @jesserockz
 esphome/components/esp32_rmt_led_strip/* @jesserockz
 esphome/components/esp8266/* @esphome/core
 esphome/components/esp_ldo/* @clydebarrow
 esphome/components/espnow/* @jesserockz
+esphome/components/espnow/packet_transport/* @EasilyBoredEngineer
 esphome/components/ethernet_info/* @gtjadsonsantos
 esphome/components/event/* @nohat
 esphome/components/exposure_notifications/* @OttoWinter
@@ -177,13 +195,14 @@ esphome/components/gdk101/* @Szewcson
 esphome/components/gl_r01_i2c/* @pkejval
 esphome/components/globals/* @esphome/core
 esphome/components/gp2y1010au0f/* @zry98
-esphome/components/gp8403/* @jesserockz
+esphome/components/gp8403/* @jesserockz @sebydocky
 esphome/components/gpio/* @esphome/core
 esphome/components/gpio/one_wire/* @ssieb
 esphome/components/gps/* @coogle @ximex
 esphome/components/graph/* @synco
 esphome/components/graphical_display_menu/* @MrMDavidson
 esphome/components/gree/* @orestismers
+esphome/components/gree/switch/* @nagyrobi
 esphome/components/grove_gas_mc_v2/* @YorkshireIoT
 esphome/components/grove_tb6612fng/* @max246
 esphome/components/growatt_solar/* @leeuwte
@@ -198,11 +217,18 @@ esphome/components/havells_solar/* @sourabhjaiswal
 esphome/components/hbridge/fan/* @WeekendWarrior
 esphome/components/hbridge/light/* @DotNetDann
 esphome/components/hbridge/switch/* @dwmw2
+esphome/components/hc8/* @omartijn
+esphome/components/hdc2010/* @optimusprimespace @ssieb
+esphome/components/hdc2080/* @G-Pereira @jesserockz
+esphome/components/hdc302x/* @joshuasing
 esphome/components/he60r/* @clydebarrow
 esphome/components/heatpumpir/* @rob-deutsch
 esphome/components/hitachi_ac424/* @sourabhjaiswal
+esphome/components/hlk_fm22x/* @OnFreund
+esphome/components/hlw8032/* @rici4kubicek
 esphome/components/hm3301/* @freekode
 esphome/components/hmac_md5/* @dwmw2
+esphome/components/hmac_sha256/* @dwmw2
 esphome/components/homeassistant/* @esphome/core @OttoWinter
 esphome/components/homeassistant/number/* @landonr
 esphome/components/homeassistant/switch/* @Links2004
@@ -216,12 +242,12 @@ esphome/components/hte501/* @Stock-M
 esphome/components/http_request/ota/* @oarcher
 esphome/components/http_request/update/* @jesserockz
 esphome/components/htu31d/* @betterengineering
+esphome/components/hub75/* @stuartparmenter
 esphome/components/hydreon_rgxx/* @functionpointer
 esphome/components/hyt271/* @Philippe12
 esphome/components/i2c/* @esphome/core
 esphome/components/i2c_device/* @gabest11
 esphome/components/i2s_audio/* @jesserockz
-esphome/components/i2s_audio/media_player/* @jesserockz
 esphome/components/i2s_audio/microphone/* @jesserockz
 esphome/components/i2s_audio/speaker/* @jesserockz @kahrendt
 esphome/components/iaqcore/* @yozik04
@@ -233,11 +259,13 @@ esphome/components/ina260/* @mreditor97
 esphome/components/ina2xx_base/* @latonita
 esphome/components/ina2xx_i2c/* @latonita
 esphome/components/ina2xx_spi/* @latonita
+esphome/components/infrared/* @kbx81
 esphome/components/inkbird_ibsth1_mini/* @fkirill
 esphome/components/inkplate/* @jesserockz @JosipKuci
 esphome/components/integration/* @OttoWinter
 esphome/components/internal_temperature/* @Mat931
 esphome/components/interval/* @esphome/core
+esphome/components/ir_rf_proxy/* @kbx81
 esphome/components/jsn_sr04t/* @Mafus1
 esphome/components/json/* @esphome/core
 esphome/components/kamstrup_kmp/* @cfeenstra1024
@@ -285,6 +313,7 @@ esphome/components/mcp23x17_base/* @jesserockz
 esphome/components/mcp23xxx_base/* @jesserockz
 esphome/components/mcp2515/* @danielschramm @mvturnho
 esphome/components/mcp3204/* @rsumner
+esphome/components/mcp3221/* @philippderdiedas
 esphome/components/mcp4461/* @p1ngb4ck
 esphome/components/mcp4728/* @berfenger
 esphome/components/mcp47a1/* @jesserockz
@@ -293,8 +322,9 @@ 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/* @jorre05
+esphome/components/micronova/* @edenhaus @jorre05
 esphome/components/microphone/* @jesserockz @kahrendt
 esphome/components/mics_4514/* @jesserockz
 esphome/components/midea/* @dudanov
@@ -303,6 +333,7 @@ esphome/components/mipi_dsi/* @clydebarrow
 esphome/components/mipi_rgb/* @clydebarrow
 esphome/components/mipi_spi/* @clydebarrow
 esphome/components/mitsubishi/* @RubyBailey
+esphome/components/mitsubishi_cn105/* @crnjan
 esphome/components/mixer/speaker/* @kahrendt
 esphome/components/mlx90393/* @functionpointer
 esphome/components/mlx90614/* @jesserockz
@@ -316,6 +347,7 @@ esphome/components/modbus_controller/select/* @martgras @stegm
 esphome/components/modbus_controller/sensor/* @martgras
 esphome/components/modbus_controller/switch/* @martgras
 esphome/components/modbus_controller/text_sensor/* @martgras
+esphome/components/modbus_server/* @exciton
 esphome/components/mopeka_ble/* @Fabian-Schmidt @spbrogan
 esphome/components/mopeka_pro_check/* @spbrogan
 esphome/components/mopeka_std_check/* @Fabian-Schmidt
@@ -373,22 +405,28 @@ esphome/components/qmp6988/* @andrewpc
 esphome/components/qr_code/* @wjtje
 esphome/components/qspi_dbi/* @clydebarrow
 esphome/components/qwiic_pir/* @kahrendt
+esphome/components/radio_frequency/* @kbx81
 esphome/components/radon_eye_ble/* @jeffeb3
 esphome/components/radon_eye_rd200/* @jeffeb3
 esphome/components/rc522/* @glmnet
 esphome/components/rc522_i2c/* @glmnet
 esphome/components/rc522_spi/* @glmnet
+esphome/components/rd03d/* @jasstrong
 esphome/components/resampler/speaker/* @kahrendt
 esphome/components/restart/* @esphome/core
 esphome/components/rf_bridge/* @jesserockz
 esphome/components/rgbct/* @jesserockz
+esphome/components/ring_buffer/* @kahrendt
 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
 esphome/components/scd4x/* @martgras @sjtrny
 esphome/components/script/* @esphome/core
@@ -403,8 +441,15 @@ 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/sendspin/* @kahrendt
+esphome/components/sendspin/media_player/* @kahrendt
+esphome/components/sendspin/media_source/* @kahrendt
+esphome/components/sendspin/sensor/* @kahrendt
+esphome/components/sendspin/text_sensor/* @kahrendt
 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
@@ -425,8 +470,12 @@ esphome/components/sn74hc165/* @jesserockz
 esphome/components/socket/* @esphome/core
 esphome/components/sonoff_d1/* @anatoly-savchenkov
 esphome/components/sound_level/* @kahrendt
+esphome/components/spa06_base/* @danielkent-net
+esphome/components/spa06_i2c/* @danielkent-net
+esphome/components/spa06_spi/* @danielkent-net
 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
@@ -452,6 +501,7 @@ esphome/components/st7735/* @SenexCrenshaw
 esphome/components/st7789v/* @kbx81
 esphome/components/st7920/* @marsjan155
 esphome/components/statsd/* @Links2004
+esphome/components/stts22h/* @B48D81EFCC
 esphome/components/substitutions/* @esphome/core
 esphome/components/sun/* @OttoWinter
 esphome/components/sun_gtil2/* @Mat931
@@ -459,6 +509,7 @@ esphome/components/switch/* @esphome/core
 esphome/components/switch/binary_sensor/* @ssieb
 esphome/components/sx126x/* @swoboda1337
 esphome/components/sx127x/* @swoboda1337
+esphome/components/sy6970/* @linkedupbits
 esphome/components/syslog/* @clydebarrow
 esphome/components/t6615/* @tylermenezes
 esphome/components/tc74/* @sethgirvan
@@ -473,8 +524,10 @@ esphome/components/template/datetime/* @rfdarter
 esphome/components/template/event/* @nohat
 esphome/components/template/fan/* @ssieb
 esphome/components/text/* @mauritskorse
+esphome/components/thermopro_ble/* @sittner
 esphome/components/thermostat/* @kbx81
 esphome/components/time/* @esphome/core
+esphome/components/tinyusb/* @kbx81
 esphome/components/tlc5947/* @rnauber
 esphome/components/tlc5971/* @IJIJI
 esphome/components/tm1621/* @Philippe12
@@ -499,13 +552,15 @@ esphome/components/tuya/switch/* @jesserockz
 esphome/components/tuya/text_sensor/* @dentra
 esphome/components/uart/* @esphome/core
 esphome/components/uart/button/* @ssieb
+esphome/components/uart/event/* @eoasmxd
 esphome/components/uart/packet_transport/* @clydebarrow
 esphome/components/udp/* @clydebarrow
 esphome/components/ufire_ec/* @pvizeli
 esphome/components/ufire_ise/* @pvizeli
-esphome/components/ultrasonic/* @OttoWinter
+esphome/components/ultrasonic/* @ssieb @swoboda1337
 esphome/components/update/* @jesserockz
 esphome/components/uponor_smatrix/* @kroimon
+esphome/components/usb_cdc_acm/* @kbx81
 esphome/components/usb_host/* @clydebarrow
 esphome/components/usb_uart/* @clydebarrow
 esphome/components/valve/* @esphome/core
@@ -516,6 +571,7 @@ esphome/components/version/* @esphome/core
 esphome/components/voice_assistant/* @jesserockz @kahrendt
 esphome/components/wake_on_lan/* @clydebarrow @willwill2will54
 esphome/components/watchdog/* @oarcher
+esphome/components/water_heater/* @dhoeben
 esphome/components/waveshare_epaper/* @clydebarrow
 esphome/components/web_server/ota/* @esphome/core
 esphome/components/web_server_base/* @esphome/core
@@ -550,6 +606,8 @@ 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/* @luar123 @tomaszduda23
 esphome/components/zio_ultrasonic/* @kahrendt
 esphome/components/zwave_proxy/* @kbx81

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 We welcome contributions to the ESPHome suite of code and documentation!
 
-Please read our [contributing guide](https://esphome.io/guides/contributing.html) if you wish to contribute to the
+Please read our [contributing guide](https://developers.esphome.io/contributing/code/) if you wish to contribute to the
 project and be sure to join us on [Discord](https://discord.gg/KhAMKrd).
 
 **See also:**

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         = 2025.10.4
+PROJECT_NUMBER         = 2026.5.0-dev
 
 # 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

GEMINI.md

@@ -1 +1 @@
-.ai/instructions.md
+AGENTS.md

MANIFEST.in

@@ -1,6 +1,8 @@
 include LICENSE
 include README.md
 include requirements.txt
+recursive-include esphome *.yaml
 recursive-include esphome *.cpp *.h *.tcc *.c
 recursive-include esphome *.py.script
+recursive-include esphome *.jinja
 recursive-include esphome LICENSE.txt

README.md

@@ -1,9 +1,9 @@
-# ESPHome [![Discord Chat](https://img.shields.io/discord/429907082951524364.svg)](https://discord.gg/KhAMKrd) [![GitHub release](https://img.shields.io/github/release/esphome/esphome.svg)](https://GitHub.com/esphome/esphome/releases/)
+# ESPHome [![Discord Chat](https://img.shields.io/discord/429907082951524364.svg)](https://discord.gg/KhAMKrd) [![GitHub release](https://img.shields.io/github/release/esphome/esphome.svg)](https://GitHub.com/esphome/esphome/releases/) [![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/esphome/esphome)
 
 <a href="https://esphome.io/">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://esphome.io/_static/logo-text-on-dark.svg", alt="ESPHome Logo">
-    <img src="https://esphome.io/_static/logo-text-on-light.svg" alt="ESPHome Logo">
+    <source media="(prefers-color-scheme: dark)" srcset="https://media.esphome.io/logo/logo-text-on-dark.svg">
+    <img src="https://media.esphome.io/logo/logo-text-on-light.svg" alt="ESPHome Logo">
   </picture>
 </a>
 

docker/Dockerfile

@@ -9,11 +9,22 @@ FROM ghcr.io/esphome/docker-base:${BUILD_OS}-ha-addon-${BUILD_BASE_VERSION} AS b
 ARG BUILD_TYPE
 FROM base-source-${BUILD_TYPE} AS base
 
-RUN git config --system --add safe.directory "*"
+RUN git config --system --add safe.directory "*" \
+    && git config --system advice.detachedHead false
+
+# Install build tools for Python packages that require compilation
+# (e.g., ruamel.yaml.clibz used by ESP-IDF's idf-component-manager)
+RUN if command -v apk > /dev/null; then \
+        apk add --no-cache build-base; \
+    else \
+        apt-get update \
+        && apt-get install -y --no-install-recommends build-essential \
+        && rm -rf /var/lib/apt/lists/*; \
+    fi
 
 ENV PIP_DISABLE_PIP_VERSION_CHECK=1
 
-RUN pip install --no-cache-dir -U pip uv==0.6.14
+RUN pip install --no-cache-dir -U pip uv==0.10.1
 
 COPY requirements.txt /
 

docker/ha-addon-rootfs/etc/cont-init.d/40-device-builder.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/with-contenv bashio
+# ==============================================================================
+# Installs the latest prerelease of esphome-device-builder when the
+# `use_new_device_builder` config option is enabled.
+# This is a temporary install-on-boot step until esphome-device-builder
+# becomes a direct dependency of esphome.
+# ==============================================================================
+
+if ! bashio::config.true 'use_new_device_builder'; then
+  exit 0
+fi
+
+bashio::log.info "Installing latest prerelease of esphome-device-builder..."
+if command -v uv > /dev/null; then
+  uv pip install --system --no-cache-dir --prerelease=allow --upgrade \
+    esphome-device-builder ||
+    bashio::exit.nok "Failed installing esphome-device-builder."
+else
+  pip install --no-cache-dir --pre --upgrade esphome-device-builder ||
+    bashio::exit.nok "Failed installing esphome-device-builder."
+fi
+bashio::log.info "Installed esphome-device-builder."

docker/ha-addon-rootfs/etc/s6-overlay/s6-rc.d/esphome/run

@@ -49,5 +49,12 @@ if bashio::fs.directory_exists '/config/esphome/.esphome'; then
     rm -rf /config/esphome/.esphome
 fi
 
+if bashio::config.true 'use_new_device_builder'; then
+    bashio::log.info "Starting ESPHome Device Builder..."
+    exec esphome-device-builder /config/esphome \
+        --ha-addon \
+        --ingress-port "$(bashio::addon.ingress_port)"
+fi
+
 bashio::log.info "Starting ESPHome dashboard..."
 exec esphome dashboard /config/esphome --socket /var/run/esphome.sock --ha-addon

docker/ha-addon-rootfs/etc/s6-overlay/s6-rc.d/init-nginx/run

@@ -4,6 +4,14 @@
 # Community Hass.io Add-ons: ESPHome
 # Configures NGINX for use with ESPHome
 # ==============================================================================
+
+# When the new device builder is enabled it serves HA ingress directly,
+# so nginx is not used at all -- skip configuration.
+if bashio::config.true 'use_new_device_builder'; then
+    bashio::log.info "Skipping NGINX setup: new device builder serves ingress directly."
+    bashio::exit.ok
+fi
+
 mkdir -p /var/log/nginx
 
 # Generate Ingress configuration

docker/ha-addon-rootfs/etc/s6-overlay/s6-rc.d/nginx/run

@@ -5,6 +5,14 @@
 # Runs the NGINX proxy
 # ==============================================================================
 
+# The new device builder handles HA ingress itself, so nginx is bypassed.
+# Block the longrun forever so s6 keeps the dependency satisfied and does
+# not respawn it.
+if bashio::config.true 'use_new_device_builder'; then
+    bashio::log.info "NGINX bypassed: new device builder serves ingress directly."
+    exec sleep infinity
+fi
+
 bashio::log.info "Waiting for ESPHome dashboard to come up..."
 
 while [[ ! -S /var/run/esphome.sock ]]; do

esphome/address_cache.py

@@ -101,6 +101,17 @@ class AddressCache:
         """Check if any cache entries exist."""
         return bool(self.mdns_cache or self.dns_cache)
 
+    def add_mdns_addresses(self, hostname: str, addresses: list[str]) -> None:
+        """Store resolved mDNS addresses for ``hostname`` in the cache.
+
+        Callers that discover ``.local`` hosts (e.g. via mDNS browse) can use
+        this to avoid a second resolution round-trip during the upload path.
+        No-op when ``addresses`` is empty.
+        """
+        if not addresses:
+            return
+        self.mdns_cache[normalize_hostname(hostname)] = addresses
+
     @classmethod
     def from_cli_args(
         cls, mdns_args: Iterable[str], dns_args: Iterable[str]

esphome/analyze_memory/__main__.py

@@ -0,0 +1,6 @@
+"""Main entry point for running the memory analyzer as a module."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

esphome/analyze_memory/cli.py

@@ -0,0 +1,809 @@
+"""CLI interface for memory analysis with report generation."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Callable
+import heapq
+from operator import itemgetter
+import sys
+from typing import TYPE_CHECKING
+
+from . import (
+    _COMPONENT_API,
+    _COMPONENT_CORE,
+    _COMPONENT_PREFIX_ESPHOME,
+    _COMPONENT_PREFIX_EXTERNAL,
+    _COMPONENT_PREFIX_LIB,
+    _PSTORAGE_SUFFIX,
+    RAM_SECTIONS,
+    MemoryAnalyzer,
+)
+
+if TYPE_CHECKING:
+    from . import ComponentMemory
+
+
+def _format_pstorage_name(name: str) -> str:
+    """Format a __pstorage symbol as 'storage for {id}'."""
+    if not name.endswith(_PSTORAGE_SUFFIX):
+        return name
+    prefix = name[: -len(_PSTORAGE_SUFFIX)]
+    # Strip component namespace prefix: {component}__{id} -> {id}
+    dunder_pos = prefix.find("__")
+    var_id = prefix[dunder_pos + 2 :] if dunder_pos != -1 else prefix
+    return f"storage for {var_id}"
+
+
+class MemoryAnalyzerCLI(MemoryAnalyzer):
+    """Memory analyzer with CLI-specific report generation."""
+
+    # Symbol size threshold for detailed analysis
+    SYMBOL_SIZE_THRESHOLD: int = (
+        100  # Show symbols larger than this in detailed analysis
+    )
+    # Lower threshold for RAM symbols (RAM is more constrained)
+    RAM_SYMBOL_SIZE_THRESHOLD: int = 24
+    # Number of top symbols to show in the largest symbols report
+    TOP_SYMBOLS_LIMIT: int = 30
+    # Width for symbol name display in top symbols report
+    COL_TOP_SYMBOL_NAME: int = 55
+
+    # Column width constants
+    COL_COMPONENT: int = 29
+    COL_FLASH_TEXT: int = 14
+    COL_FLASH_DATA: int = 14
+    COL_RAM_DATA: int = 12
+    COL_RAM_BSS: int = 12
+    COL_TOTAL_FLASH: int = 15
+    COL_TOTAL_RAM: int = 12
+    COL_SEPARATOR: int = 3  # " | "
+
+    # Core analysis column widths
+    COL_CORE_SUBCATEGORY: int = 30
+    COL_CORE_SIZE: int = 12
+    COL_CORE_COUNT: int = 6
+    COL_CORE_PERCENT: int = 10
+
+    # Calculate table width once at class level
+    TABLE_WIDTH: int = (
+        COL_COMPONENT
+        + COL_SEPARATOR
+        + COL_FLASH_TEXT
+        + COL_SEPARATOR
+        + COL_FLASH_DATA
+        + COL_SEPARATOR
+        + COL_RAM_DATA
+        + COL_SEPARATOR
+        + COL_RAM_BSS
+        + COL_SEPARATOR
+        + COL_TOTAL_FLASH
+        + COL_SEPARATOR
+        + COL_TOTAL_RAM
+    )
+
+    @staticmethod
+    def _make_separator_line(*widths: int) -> str:
+        """Create a separator line with given column widths.
+
+        Args:
+            widths: Column widths to create separators for
+
+        Returns:
+            Separator line like "----+---------+-----"
+        """
+        return "-+-".join("-" * width for width in widths)
+
+    # Pre-computed separator lines
+    MAIN_TABLE_SEPARATOR: str = _make_separator_line(
+        COL_COMPONENT,
+        COL_FLASH_TEXT,
+        COL_FLASH_DATA,
+        COL_RAM_DATA,
+        COL_RAM_BSS,
+        COL_TOTAL_FLASH,
+        COL_TOTAL_RAM,
+    )
+
+    CORE_TABLE_SEPARATOR: str = _make_separator_line(
+        COL_CORE_SUBCATEGORY,
+        COL_CORE_SIZE,
+        COL_CORE_COUNT,
+        COL_CORE_PERCENT,
+    )
+
+    def _add_section_header(self, lines: list[str], title: str) -> None:
+        """Add a section header with title centered between separator lines."""
+        lines.append("")
+        lines.append("=" * self.TABLE_WIDTH)
+        lines.append(title.center(self.TABLE_WIDTH))
+        lines.append("=" * self.TABLE_WIDTH)
+        lines.append("")
+
+    def _add_top_consumers(
+        self,
+        lines: list[str],
+        title: str,
+        components: list[tuple[str, ComponentMemory]],
+        get_size: Callable[[ComponentMemory], int],
+        total: int,
+        memory_type: str,
+        limit: int = 25,
+    ) -> None:
+        """Add a formatted list of top memory consumers to the report.
+
+        Args:
+            lines: List of report lines to append the output to.
+            title: Section title to print before the list.
+            components: Sequence of (name, ComponentMemory) tuples to analyze.
+            get_size: Callable that takes a ComponentMemory and returns the
+                size in bytes to use for ranking and display.
+            total: Total size in bytes for computing percentage usage.
+            memory_type: Label for the memory region (e.g., "flash" or "RAM").
+            limit: Maximum number of components to include in the list.
+        """
+        lines.append("")
+        lines.append(f"{title}:")
+        for i, (name, mem) in enumerate(components[:limit]):
+            size = get_size(mem)
+            if size > 0:
+                percentage = (size / total * 100) if total > 0 else 0
+                lines.append(
+                    f"{i + 1}. {name} ({size:,} B) - {percentage:.1f}% of analyzed {memory_type}"
+                )
+
+    def _format_symbol_with_section(
+        self, demangled: str, size: int, section: str | None = None
+    ) -> str:
+        """Format a symbol entry, optionally adding a RAM section label.
+
+        If section is one of the RAM sections (.data or .bss), a label like
+        " [data]" or " [bss]" is appended. For non-RAM sections or when
+        section is None, no section label is added.
+
+        Placement new storage symbols are formatted as "storage for {id}".
+        """
+        display_name = _format_pstorage_name(demangled)
+        section_label = ""
+        if section in RAM_SECTIONS:
+            section_label = f" [{section[1:]}]"  # .data -> [data], .bss -> [bss]
+        return f"{display_name} ({size:,} B){section_label}"
+
+    def _add_top_symbols(self, lines: list[str]) -> None:
+        """Add a section showing the top largest symbols in the binary."""
+        # Collect all symbols from all components: (symbol, demangled, size, section, component)
+        all_symbols = [
+            (symbol, demangled, size, section, component)
+            for component, symbols in self._component_symbols.items()
+            for symbol, demangled, size, section in symbols
+        ]
+
+        # Get top N symbols by size using heapq for efficiency
+        top_symbols = heapq.nlargest(
+            self.TOP_SYMBOLS_LIMIT, all_symbols, key=itemgetter(2)
+        )
+
+        lines.append("")
+        lines.append(f"Top {self.TOP_SYMBOLS_LIMIT} Largest Symbols:")
+        # Calculate truncation limit from column width (leaving room for "...")
+        truncate_limit = self.COL_TOP_SYMBOL_NAME - 3
+        for i, (_, demangled, size, section, component) in enumerate(top_symbols):
+            # Format section label
+            section_label = f"[{section[1:]}]" if section else ""
+            # Format storage symbols readably
+            display_name = _format_pstorage_name(demangled)
+            # Truncate if too long
+            demangled_display = (
+                f"{display_name[:truncate_limit]}..."
+                if len(display_name) > self.COL_TOP_SYMBOL_NAME
+                else display_name
+            )
+            lines.append(
+                f"{i + 1:>2}. {size:>7,} B {section_label:<8} {demangled_display:<{self.COL_TOP_SYMBOL_NAME}} {component}"
+            )
+
+    def _add_cswtch_analysis(self, lines: list[str]) -> None:
+        """Add CSWTCH (GCC switch table lookup) analysis section."""
+        self._add_section_header(lines, "CSWTCH Analysis (GCC Switch Table Lookups)")
+
+        total_size = sum(size for _, size, _, _ in self._cswtch_symbols)
+        lines.append(
+            f"Total: {len(self._cswtch_symbols)} switch table(s), {total_size:,} B"
+        )
+        lines.append("")
+
+        # Group by component
+        by_component: dict[str, list[tuple[str, int, str]]] = defaultdict(list)
+        for sym_name, size, source_file, component in self._cswtch_symbols:
+            by_component[component].append((sym_name, size, source_file))
+
+        # Sort components by total size descending
+        sorted_components = sorted(
+            by_component.items(),
+            key=lambda x: sum(s[1] for s in x[1]),
+            reverse=True,
+        )
+
+        for component, symbols in sorted_components:
+            comp_total = sum(s[1] for s in symbols)
+            lines.append(f"{component} ({comp_total:,} B, {len(symbols)} tables):")
+
+            # Group by source file within component
+            by_file: dict[str, list[tuple[str, int]]] = defaultdict(list)
+            for sym_name, size, source_file in symbols:
+                by_file[source_file].append((sym_name, size))
+
+            for source_file, file_symbols in sorted(
+                by_file.items(),
+                key=lambda x: sum(s[1] for s in x[1]),
+                reverse=True,
+            ):
+                file_total = sum(s[1] for s in file_symbols)
+                lines.append(
+                    f"  {source_file} ({file_total:,} B, {len(file_symbols)} tables)"
+                )
+                for sym_name, size in sorted(
+                    file_symbols, key=lambda x: x[1], reverse=True
+                ):
+                    lines.append(f"    {size:>6,} B  {sym_name}")
+            lines.append("")
+
+    # Number of top called functions to show
+    TOP_CALLS_LIMIT: int = 50
+    # Number of inlining candidates to show
+    INLINE_CANDIDATES_LIMIT: int = 25
+    # Maximum function size in bytes to consider for inlining
+    INLINE_SIZE_THRESHOLD: int = 16
+
+    def _build_symbol_sizes(self) -> dict[str, int]:
+        """Build a size lookup from all component symbols: mangled_name -> size."""
+        return {
+            symbol: size
+            for symbols in self._component_symbols.values()
+            for symbol, _, size, _ in symbols
+        }
+
+    def _format_call_row(
+        self, index: int, mangled: str, count: int, symbol_sizes: dict[str, int]
+    ) -> str:
+        """Format a single row for call frequency tables."""
+        demangled = self._demangle_cache.get(mangled, mangled)
+        if len(demangled) > 80:
+            demangled = f"{demangled[:77]}..."
+        size = symbol_sizes.get(mangled)
+        size_str = f"{size:>5,} B" if size is not None else "      ?"
+        return f"{index:>3}  {count:>5}  {size_str}  {demangled}"
+
+    def _add_call_table_header(self, lines: list[str]) -> None:
+        """Add the header row for call frequency tables."""
+        lines.append(f"{'#':>3}  {'Calls':>5}  {'Size':>7}  Function")
+        lines.append(f"{'---':>3}  {'-----':>5}  {'-------':>7}  {'-' * 60}")
+
+    def _add_function_call_analysis(self, lines: list[str]) -> None:
+        """Add function call frequency analysis section.
+
+        Shows the most frequently called functions by call site count.
+        """
+        self._add_section_header(lines, "Top Called Functions")
+
+        symbol_sizes = self._build_symbol_sizes()
+
+        # Sort by call count descending
+        sorted_calls = sorted(
+            self._function_call_counts.items(), key=lambda x: x[1], reverse=True
+        )
+
+        self._add_call_table_header(lines)
+
+        for i, (mangled, count) in enumerate(sorted_calls[: self.TOP_CALLS_LIMIT]):
+            lines.append(self._format_call_row(i + 1, mangled, count, symbol_sizes))
+
+        total_calls = sum(self._function_call_counts.values())
+        lines.append("")
+        lines.append(
+            f"Total: {len(self._function_call_counts)} unique targets, "
+            f"{total_calls:,} call sites"
+        )
+        lines.append("")
+
+    def _add_inline_candidates(self, lines: list[str]) -> None:
+        """Add inlining candidates section.
+
+        Shows frequently called functions that are small enough to benefit
+        from inlining (< 16 bytes). These are the best candidates for
+        reducing call overhead.
+        """
+        self._add_section_header(
+            lines,
+            f"Inlining Candidates (<{self.INLINE_SIZE_THRESHOLD} B, by call count)",
+        )
+
+        symbol_sizes = self._build_symbol_sizes()
+
+        # Filter to small functions with known size, sort by call count
+        candidates = sorted(
+            (
+                (mangled, count)
+                for mangled, count in self._function_call_counts.items()
+                if mangled in symbol_sizes
+                and symbol_sizes[mangled] < self.INLINE_SIZE_THRESHOLD
+            ),
+            key=lambda x: x[1],
+            reverse=True,
+        )
+
+        if not candidates:
+            lines.append("No candidates found.")
+            lines.append("")
+            return
+
+        self._add_call_table_header(lines)
+
+        for i, (mangled, count) in enumerate(
+            candidates[: self.INLINE_CANDIDATES_LIMIT]
+        ):
+            lines.append(self._format_call_row(i + 1, mangled, count, symbol_sizes))
+
+        lines.append("")
+        lines.append(
+            f"Showing top {min(len(candidates), self.INLINE_CANDIDATES_LIMIT)} "
+            f"of {len(candidates)} functions under "
+            f"{self.INLINE_SIZE_THRESHOLD} B"
+        )
+        lines.append("")
+
+    def generate_report(self, detailed: bool = False) -> str:
+        """Generate a formatted memory report."""
+        components = sorted(
+            self.components.items(), key=lambda x: x[1].flash_total, reverse=True
+        )
+
+        # Calculate totals
+        total_flash = sum(c.flash_total for _, c in components)
+        total_ram = sum(c.ram_total for _, c in components)
+
+        # Build report
+        lines: list[str] = []
+
+        lines.append("=" * self.TABLE_WIDTH)
+        lines.append("Component Memory Analysis".center(self.TABLE_WIDTH))
+        lines.append("=" * self.TABLE_WIDTH)
+        lines.append("")
+
+        # Main table - fixed column widths
+        lines.append(
+            f"{'Component':<{self.COL_COMPONENT}} | {'Flash (text)':>{self.COL_FLASH_TEXT}} | {'Flash (data)':>{self.COL_FLASH_DATA}} | {'RAM (data)':>{self.COL_RAM_DATA}} | {'RAM (bss)':>{self.COL_RAM_BSS}} | {'Total Flash':>{self.COL_TOTAL_FLASH}} | {'Total RAM':>{self.COL_TOTAL_RAM}}"
+        )
+        lines.append(self.MAIN_TABLE_SEPARATOR)
+
+        for name, mem in components:
+            if mem.flash_total > 0 or mem.ram_total > 0:
+                flash_rodata = mem.rodata_size + mem.data_size
+                lines.append(
+                    f"{name:<{self.COL_COMPONENT}} | {mem.text_size:>{self.COL_FLASH_TEXT - 2},} B | {flash_rodata:>{self.COL_FLASH_DATA - 2},} B | "
+                    f"{mem.data_size:>{self.COL_RAM_DATA - 2},} B | {mem.bss_size:>{self.COL_RAM_BSS - 2},} B | "
+                    f"{mem.flash_total:>{self.COL_TOTAL_FLASH - 2},} B | {mem.ram_total:>{self.COL_TOTAL_RAM - 2},} B"
+                )
+
+        lines.append(self.MAIN_TABLE_SEPARATOR)
+        lines.append(
+            f"{'TOTAL':<{self.COL_COMPONENT}} | {' ':>{self.COL_FLASH_TEXT}} | {' ':>{self.COL_FLASH_DATA}} | "
+            f"{' ':>{self.COL_RAM_DATA}} | {' ':>{self.COL_RAM_BSS}} | "
+            f"{total_flash:>{self.COL_TOTAL_FLASH - 2},} B | {total_ram:>{self.COL_TOTAL_RAM - 2},} B"
+        )
+
+        # Show unattributed RAM (SDK/framework overhead)
+        unattributed_bss, unattributed_data, unattributed_total = (
+            self.get_unattributed_ram()
+        )
+        if unattributed_total > 0:
+            lines.append("")
+            lines.append(
+                f"Unattributed RAM: {unattributed_total:,} B (SDK/framework overhead)"
+            )
+            if unattributed_bss > 0 and unattributed_data > 0:
+                lines.append(
+                    f"  .bss: {unattributed_bss:,} B | .data: {unattributed_data:,} B"
+                )
+
+            # Show SDK symbol breakdown if available
+            sdk_by_lib = self.get_sdk_ram_by_library()
+            if sdk_by_lib:
+                lines.append("")
+                lines.append("SDK library breakdown (static symbols not in ELF):")
+                # Sort libraries by total size
+                lib_totals = [
+                    (lib, sum(s.size for s in syms), syms)
+                    for lib, syms in sdk_by_lib.items()
+                ]
+                lib_totals.sort(key=lambda x: x[1], reverse=True)
+
+                for lib_name, lib_total, syms in lib_totals:
+                    if lib_total == 0:
+                        continue
+                    lines.append(f"  {lib_name}: {lib_total:,} B")
+                    # Show top symbols from this library
+                    for sym in sorted(syms, key=lambda s: s.size, reverse=True)[:3]:
+                        section_label = sym.section.lstrip(".")
+                        # Use demangled name (falls back to original if not demangled)
+                        display_name = sym.demangled or sym.name
+                        if len(display_name) > 50:
+                            display_name = f"{display_name[:47]}..."
+                        lines.append(
+                            f"    {sym.size:>6,} B [{section_label}] {display_name}"
+                        )
+
+        # Top consumers
+        self._add_top_consumers(
+            lines,
+            "Top Flash Consumers",
+            components,
+            lambda m: m.flash_total,
+            total_flash,
+            "flash",
+        )
+
+        ram_components = sorted(components, key=lambda x: x[1].ram_total, reverse=True)
+        self._add_top_consumers(
+            lines,
+            "Top RAM Consumers",
+            ram_components,
+            lambda m: m.ram_total,
+            total_ram,
+            "RAM",
+        )
+
+        # Top largest symbols in the binary
+        self._add_top_symbols(lines)
+
+        # Add ESPHome core detailed analysis if there are core symbols
+        if self._esphome_core_symbols:
+            self._add_section_header(lines, f"{_COMPONENT_CORE} Detailed Analysis")
+
+            # Group core symbols by subcategory
+            core_subcategories: dict[str, list[tuple[str, str, int]]] = defaultdict(
+                list
+            )
+
+            for symbol, demangled, size in self._esphome_core_symbols:
+                # Categorize based on demangled name patterns
+                subcategory = self._categorize_esphome_core_symbol(demangled)
+                core_subcategories[subcategory].append((symbol, demangled, size))
+
+            # Sort subcategories by total size
+            sorted_subcategories = sorted(
+                [
+                    (name, symbols, sum(s[2] for s in symbols))
+                    for name, symbols in core_subcategories.items()
+                ],
+                key=lambda x: x[2],
+                reverse=True,
+            )
+
+            lines.append(
+                f"{'Subcategory':<{self.COL_CORE_SUBCATEGORY}} | {'Size':>{self.COL_CORE_SIZE}} | "
+                f"{'Count':>{self.COL_CORE_COUNT}} | {'% of Core':>{self.COL_CORE_PERCENT}}"
+            )
+            lines.append(self.CORE_TABLE_SEPARATOR)
+
+            core_total = sum(size for _, _, size in self._esphome_core_symbols)
+
+            for subcategory, symbols, total_size in sorted_subcategories:
+                percentage = (total_size / core_total * 100) if core_total > 0 else 0
+                lines.append(
+                    f"{subcategory:<{self.COL_CORE_SUBCATEGORY}} | {total_size:>{self.COL_CORE_SIZE - 2},} B | "
+                    f"{len(symbols):>{self.COL_CORE_COUNT}} | {percentage:>{self.COL_CORE_PERCENT - 1}.1f}%"
+                )
+
+            # All core symbols above threshold
+            lines.append("")
+            sorted_core_symbols = sorted(
+                self._esphome_core_symbols, key=lambda x: x[2], reverse=True
+            )
+            large_core_symbols = [
+                (symbol, demangled, size)
+                for symbol, demangled, size in sorted_core_symbols
+                if size > self.SYMBOL_SIZE_THRESHOLD
+            ]
+
+            lines.append(
+                f"{_COMPONENT_CORE} Symbols > {self.SYMBOL_SIZE_THRESHOLD} B ({len(large_core_symbols)} symbols):"
+            )
+            for i, (symbol, demangled, size) in enumerate(large_core_symbols):
+                # Core symbols only track (symbol, demangled, size) without section info,
+                # so we don't show section labels here
+                lines.append(
+                    f"{i + 1}. {self._format_symbol_with_section(demangled, size)}"
+                )
+
+            lines.append("=" * self.TABLE_WIDTH)
+
+        # Add detailed analysis for top ESPHome and external components
+        esphome_components = [
+            (name, mem)
+            for name, mem in components
+            if name.startswith(_COMPONENT_PREFIX_ESPHOME) and name != _COMPONENT_CORE
+        ]
+        external_components = [
+            (name, mem)
+            for name, mem in components
+            if name.startswith(_COMPONENT_PREFIX_EXTERNAL)
+        ]
+        library_components = [
+            (name, mem)
+            for name, mem in components
+            if name.startswith(_COMPONENT_PREFIX_LIB)
+        ]
+
+        top_esphome_components = sorted(
+            esphome_components, key=lambda x: x[1].flash_total, reverse=True
+        )[:30]
+
+        # Include all external components (they're usually important)
+        top_external_components = sorted(
+            external_components, key=lambda x: x[1].flash_total, reverse=True
+        )
+
+        # Include all library components
+        top_library_components = sorted(
+            library_components, key=lambda x: x[1].flash_total, reverse=True
+        )
+
+        # Check if API component exists and ensure it's included
+        api_component = None
+        for name, mem in components:
+            if name == _COMPONENT_API:
+                api_component = (name, mem)
+                break
+
+        # Also include wifi_stack and other important system components if they exist
+        system_components_to_include = [
+            # Empty list - we've finished debugging symbol categorization
+            # Add component names here if you need to debug their symbols
+        ]
+        system_components = [
+            (name, mem)
+            for name, mem in components
+            if name in system_components_to_include
+        ]
+
+        # Combine all components to analyze: top ESPHome + all external + libraries + API if not already included + system components
+        components_to_analyze = (
+            list(top_esphome_components)
+            + list(top_external_components)
+            + list(top_library_components)
+            + system_components
+        )
+        if api_component and api_component not in components_to_analyze:
+            components_to_analyze.append(api_component)
+
+        if components_to_analyze:
+            for comp_name, comp_mem in components_to_analyze:
+                if not (comp_symbols := self._component_symbols.get(comp_name, [])):
+                    continue
+                self._add_section_header(lines, f"{comp_name} Detailed Analysis")
+
+                # Sort symbols by size
+                sorted_symbols = sorted(comp_symbols, key=lambda x: x[2], reverse=True)
+
+                lines.append(f"Total symbols: {len(sorted_symbols)}")
+                lines.append(f"Total size: {comp_mem.flash_total:,} B")
+                lines.append("")
+
+                # Show symbols above threshold, always include storage symbols
+                large_symbols = [
+                    (sym, dem, size, sec)
+                    for sym, dem, size, sec in sorted_symbols
+                    if size > self.SYMBOL_SIZE_THRESHOLD
+                    or dem.endswith(_PSTORAGE_SUFFIX)
+                ]
+
+                lines.append(
+                    f"{comp_name} Symbols > {self.SYMBOL_SIZE_THRESHOLD} B & storage ({len(large_symbols)} symbols):"
+                )
+                for i, (symbol, demangled, size, section) in enumerate(large_symbols):
+                    lines.append(
+                        f"{i + 1}. {self._format_symbol_with_section(demangled, size, section)}"
+                    )
+
+                lines.append("=" * self.TABLE_WIDTH)
+
+        # Detailed RAM analysis by component (at end, before RAM strings analysis)
+        self._add_section_header(lines, "RAM Symbol Analysis by Component")
+
+        # Show top 15 RAM consumers with their large symbols
+        for name, mem in ram_components[:15]:
+            if mem.ram_total == 0:
+                continue
+            ram_syms = self._ram_symbols.get(name, [])
+            if not ram_syms:
+                continue
+
+            # Sort by size descending
+            sorted_ram_syms = sorted(ram_syms, key=lambda x: x[2], reverse=True)
+            large_ram_syms = [
+                s
+                for s in sorted_ram_syms
+                if s[2] > self.RAM_SYMBOL_SIZE_THRESHOLD
+                or s[1].endswith(_PSTORAGE_SUFFIX)
+            ]
+
+            lines.append(f"{name} ({mem.ram_total:,} B total RAM):")
+
+            # Show breakdown by section type
+            data_size = sum(s[2] for s in ram_syms if s[3] == ".data")
+            bss_size = sum(s[2] for s in ram_syms if s[3] == ".bss")
+            lines.append(f"  .data (initialized): {data_size:,} B")
+            lines.append(f"  .bss (uninitialized): {bss_size:,} B")
+
+            if large_ram_syms:
+                lines.append(
+                    f"  Symbols > {self.RAM_SYMBOL_SIZE_THRESHOLD} B ({len(large_ram_syms)}):"
+                )
+                for symbol, demangled, size, section in large_ram_syms[:10]:
+                    # Format section label consistently by stripping leading dot
+                    section_label = section.lstrip(".") if section else ""
+                    display_name = _format_pstorage_name(demangled)
+                    # Add ellipsis if name is truncated
+                    display_name = (
+                        f"{display_name[:70]}..."
+                        if len(display_name) > 70
+                        else display_name
+                    )
+                    lines.append(f"    {size:>6,} B [{section_label}] {display_name}")
+                if len(large_ram_syms) > 10:
+                    lines.append(f"    ... and {len(large_ram_syms) - 10} more")
+            lines.append("")
+
+        # CSWTCH (GCC switch table) analysis
+        if self._cswtch_symbols:
+            self._add_cswtch_analysis(lines)
+
+        # Function call frequency analysis
+        if self._function_call_counts:
+            self._add_function_call_analysis(lines)
+            self._add_inline_candidates(lines)
+
+        lines.append(
+            "Note: This analysis covers symbols in the ELF file. Some runtime allocations may not be included."
+        )
+        lines.append("=" * self.TABLE_WIDTH)
+
+        return "\n".join(lines)
+
+    def dump_uncategorized_symbols(self, output_file: str | None = None) -> None:
+        """Dump uncategorized symbols for analysis."""
+        # Sort by size descending
+        sorted_symbols = sorted(
+            self._uncategorized_symbols, key=lambda x: x[2], reverse=True
+        )
+
+        lines = ["Uncategorized Symbols Analysis", "=" * 80]
+        lines.append(f"Total uncategorized symbols: {len(sorted_symbols)}")
+        lines.append(
+            f"Total uncategorized size: {sum(s[2] for s in sorted_symbols):,} bytes"
+        )
+        lines.append("")
+        lines.append(f"{'Size':>10} | {'Symbol':<60} | Demangled")
+        lines.append("-" * 10 + "-+-" + "-" * 60 + "-+-" + "-" * 40)
+
+        for symbol, demangled, size in sorted_symbols[:100]:  # Top 100
+            demangled_display = (
+                demangled[:100] if symbol != demangled else "[not demangled]"
+            )
+            lines.append(f"{size:>10,} | {symbol[:60]:<60} | {demangled_display}")
+
+        if len(sorted_symbols) > 100:
+            lines.append(f"\n... and {len(sorted_symbols) - 100} more symbols")
+
+        content = "\n".join(lines)
+
+        if output_file:
+            with open(output_file, "w", encoding="utf-8") as f:
+                f.write(content)
+        else:
+            print(content)
+
+
+def analyze_elf(
+    elf_path: str,
+    objdump_path: str | None = None,
+    readelf_path: str | None = None,
+    detailed: bool = False,
+    external_components: set[str] | None = None,
+) -> str:
+    """Analyze an ELF file and return a memory report."""
+    analyzer = MemoryAnalyzerCLI(
+        elf_path, objdump_path, readelf_path, external_components
+    )
+    analyzer.analyze()
+    return analyzer.generate_report(detailed)
+
+
+def main():
+    """CLI entrypoint for memory analysis."""
+    if len(sys.argv) < 2:
+        print("Usage: python -m esphome.analyze_memory <build_directory>")
+        print("\nAnalyze memory usage from an ESPHome build directory.")
+        print("The build directory should contain firmware.elf and idedata will be")
+        print("loaded from ~/.esphome/.internal/idedata/<device>.json")
+        print("\nExamples:")
+        print("  python -m esphome.analyze_memory ~/.esphome/build/my-device")
+        print("  python -m esphome.analyze_memory .esphome/build/my-device")
+        print("  python -m esphome.analyze_memory my-device  # Short form")
+        sys.exit(1)
+
+    build_dir = sys.argv[1]
+
+    # Load build directory
+    import json
+    from pathlib import Path
+
+    from esphome.platformio.toolchain import IDEData
+
+    build_path = Path(build_dir)
+
+    # If no path separator in name, assume it's a device name
+    if "/" not in build_dir and not build_path.is_dir():
+        # Try current directory first
+        cwd_path = Path.cwd() / ".esphome" / "build" / build_dir
+        if cwd_path.is_dir():
+            build_path = cwd_path
+            print(f"Using build directory: {build_path}", file=sys.stderr)
+        else:
+            # Fall back to home directory
+            build_path = Path.home() / ".esphome" / "build" / build_dir
+            print(f"Using build directory: {build_path}", file=sys.stderr)
+
+    if not build_path.is_dir():
+        print(f"Error: {build_path} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    # Find firmware.elf
+    elf_file = None
+    for elf_candidate in [
+        build_path / "firmware.elf",
+        build_path / ".pioenvs" / build_path.name / "firmware.elf",
+    ]:
+        if elf_candidate.exists():
+            elf_file = str(elf_candidate)
+            break
+
+    if not elf_file:
+        print(f"Error: firmware.elf not found in {build_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    # Find idedata.json - check current directory first, then home
+    device_name = build_path.name
+    idedata_candidates = [
+        Path.cwd() / ".esphome" / "idedata" / f"{device_name}.json",
+        Path.home() / ".esphome" / "idedata" / f"{device_name}.json",
+    ]
+
+    idedata = None
+    for idedata_path in idedata_candidates:
+        if not idedata_path.exists():
+            continue
+        try:
+            with open(idedata_path, encoding="utf-8") as f:
+                raw_data = json.load(f)
+            idedata = IDEData(raw_data)
+            print(f"Loaded idedata from: {idedata_path}", file=sys.stderr)
+            break
+        except (json.JSONDecodeError, OSError) as e:
+            print(f"Warning: Failed to load idedata: {e}", file=sys.stderr)
+
+    if not idedata:
+        print(
+            f"Warning: idedata not found (searched {idedata_candidates[0]} and {idedata_candidates[1]})",
+            file=sys.stderr,
+        )
+
+    analyzer = MemoryAnalyzerCLI(elf_file, idedata=idedata)
+    analyzer.analyze()
+    report = analyzer.generate_report()
+    print(report)
+
+
+if __name__ == "__main__":
+    main()

esphome/analyze_memory/demangle.py

@@ -0,0 +1,182 @@
+"""Symbol demangling utilities for memory analysis.
+
+This module provides functions for demangling C++ symbol names using c++filt.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+
+from .toolchain import find_tool
+
+_LOGGER = logging.getLogger(__name__)
+
+# GCC global constructor/destructor prefix annotations
+GCC_PREFIX_ANNOTATIONS = {
+    "_GLOBAL__sub_I_": "global constructor for",
+    "_GLOBAL__sub_D_": "global destructor for",
+}
+
+# GCC optimization suffix pattern (e.g., $isra$0, $part$1, $constprop$2)
+GCC_OPTIMIZATION_SUFFIX_PATTERN = re.compile(r"(\$(?:isra|part|constprop)\$\d+)")
+
+
+def _strip_gcc_annotations(symbol: str) -> tuple[str, str]:
+    """Strip GCC optimization suffixes and prefixes from a symbol.
+
+    Args:
+        symbol: The mangled symbol name
+
+    Returns:
+        Tuple of (stripped_symbol, removed_prefix)
+    """
+    # Remove GCC optimization markers
+    stripped = GCC_OPTIMIZATION_SUFFIX_PATTERN.sub("", symbol)
+
+    # Handle GCC global constructor/initializer prefixes
+    prefix = ""
+    for gcc_prefix in GCC_PREFIX_ANNOTATIONS:
+        if stripped.startswith(gcc_prefix):
+            prefix = gcc_prefix
+            stripped = stripped[len(prefix) :]
+            break
+
+    return stripped, prefix
+
+
+def _restore_symbol_prefix(prefix: str, stripped: str, demangled: str) -> str:
+    """Restore prefix that was removed before demangling.
+
+    Args:
+        prefix: Prefix that was removed (e.g., "_GLOBAL__sub_I_")
+        stripped: Stripped symbol name
+        demangled: Demangled symbol name
+
+    Returns:
+        Demangled name with prefix restored/annotated
+    """
+    if not prefix:
+        return demangled
+
+    # Successfully demangled - add descriptive prefix
+    if demangled != stripped and (annotation := GCC_PREFIX_ANNOTATIONS.get(prefix)):
+        return f"[{annotation}: {demangled}]"
+
+    # Failed to demangle - restore original prefix
+    return prefix + demangled
+
+
+def _restore_symbol_suffix(original: str, demangled: str) -> str:
+    """Restore GCC optimization suffix that was removed before demangling.
+
+    Args:
+        original: Original symbol name with suffix
+        demangled: Demangled symbol name without suffix
+
+    Returns:
+        Demangled name with suffix annotation
+    """
+    if suffix_match := GCC_OPTIMIZATION_SUFFIX_PATTERN.search(original):
+        return f"{demangled} [{suffix_match.group(1)}]"
+    return demangled
+
+
+def batch_demangle(
+    symbols: list[str],
+    cppfilt_path: str | None = None,
+    objdump_path: str | None = None,
+) -> dict[str, str]:
+    """Batch demangle C++ symbol names.
+
+    Args:
+        symbols: List of symbol names to demangle
+        cppfilt_path: Path to c++filt binary (auto-detected if not provided)
+        objdump_path: Path to objdump binary to derive c++filt path from
+
+    Returns:
+        Dictionary mapping original symbol names to demangled names
+    """
+    cache: dict[str, str] = {}
+
+    if not symbols:
+        return cache
+
+    # Find c++filt tool
+    cppfilt_cmd = cppfilt_path or find_tool("c++filt", objdump_path)
+    if not cppfilt_cmd:
+        _LOGGER.warning("Could not find c++filt, symbols will not be demangled")
+        return {s: s for s in symbols}
+
+    _LOGGER.debug("Demangling %d symbols using %s", len(symbols), cppfilt_cmd)
+
+    # Strip GCC optimization suffixes and prefixes before demangling
+    symbols_stripped: list[str] = []
+    symbols_prefixes: list[str] = []
+    for symbol in symbols:
+        stripped, prefix = _strip_gcc_annotations(symbol)
+        symbols_stripped.append(stripped)
+        symbols_prefixes.append(prefix)
+
+    try:
+        result = subprocess.run(
+            [cppfilt_cmd],
+            input="\n".join(symbols_stripped),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (subprocess.SubprocessError, OSError, UnicodeDecodeError) as e:
+        _LOGGER.warning("Failed to batch demangle symbols: %s", e)
+        return {s: s for s in symbols}
+
+    if result.returncode != 0:
+        _LOGGER.warning(
+            "c++filt exited with code %d: %s",
+            result.returncode,
+            result.stderr[:200] if result.stderr else "(no error output)",
+        )
+        return {s: s for s in symbols}
+
+    # Process demangled output
+    demangled_lines = result.stdout.strip().split("\n")
+
+    # Check for output length mismatch
+    if len(demangled_lines) != len(symbols):
+        _LOGGER.warning(
+            "c++filt output mismatch: expected %d lines, got %d",
+            len(symbols),
+            len(demangled_lines),
+        )
+        return {s: s for s in symbols}
+
+    failed_count = 0
+
+    for original, stripped, prefix, demangled in zip(
+        symbols, symbols_stripped, symbols_prefixes, demangled_lines
+    ):
+        # Add back any prefix that was removed
+        demangled = _restore_symbol_prefix(prefix, stripped, demangled)
+
+        # If we stripped a suffix, add it back to the demangled name for clarity
+        if original != stripped and not prefix:
+            demangled = _restore_symbol_suffix(original, demangled)
+
+        cache[original] = demangled
+
+        # Count symbols that failed to demangle
+        if stripped == demangled and stripped.startswith("_Z"):
+            failed_count += 1
+            if failed_count <= 5:
+                _LOGGER.debug("Failed to demangle: %s", original)
+
+    if failed_count > 0:
+        _LOGGER.debug(
+            "Failed to demangle %d/%d symbols using %s",
+            failed_count,
+            len(symbols),
+            cppfilt_cmd,
+        )
+
+    return cache

esphome/analyze_memory/helpers.py

@@ -0,0 +1,121 @@
+"""Helper functions for memory analysis."""
+
+from functools import cache
+from pathlib import Path
+
+from .const import SECTION_MAPPING
+
+# Import namespace constant from parent module
+# Note: This would create a circular import if done at module level,
+# so we'll define it locally here as well
+_NAMESPACE_ESPHOME = "esphome::"
+
+
+# Get the list of actual ESPHome components by scanning the components directory
+@cache
+def get_esphome_components():
+    """Get set of actual ESPHome components from the components directory."""
+    # Find the components directory relative to this file
+    # Go up two levels from analyze_memory/helpers.py to esphome/
+    current_dir = Path(__file__).parent.parent
+    components_dir = current_dir / "components"
+
+    if not components_dir.exists() or not components_dir.is_dir():
+        return frozenset()
+
+    return frozenset(
+        item.name
+        for item in components_dir.iterdir()
+        if item.is_dir()
+        and not item.name.startswith(".")
+        and not item.name.startswith("__")
+    )
+
+
+@cache
+def get_component_class_patterns(component_name: str) -> list[str]:
+    """Generate component class name patterns for symbol matching.
+
+    Args:
+        component_name: The component name (e.g., "ota", "wifi", "api")
+
+    Returns:
+        List of pattern strings to match against demangled symbols
+    """
+    component_upper = component_name.upper()
+    component_camel = component_name.replace("_", "").title()
+    return [
+        f"{_NAMESPACE_ESPHOME}{component_upper}Component",  # e.g., esphome::OTAComponent
+        f"{_NAMESPACE_ESPHOME}ESPHome{component_upper}Component",  # e.g., esphome::ESPHomeOTAComponent
+        f"{_NAMESPACE_ESPHOME}{component_camel}Component",  # e.g., esphome::OtaComponent
+        f"{_NAMESPACE_ESPHOME}ESPHome{component_camel}Component",  # e.g., esphome::ESPHomeOtaComponent
+    ]
+
+
+def map_section_name(raw_section: str) -> str | None:
+    """Map raw section name to standard section.
+
+    Args:
+        raw_section: Raw section name from ELF file (e.g., ".iram0.text", ".rodata.str1.1")
+
+    Returns:
+        Standard section name (".text", ".rodata", ".data", ".bss") or None
+    """
+    for standard_section, patterns in SECTION_MAPPING.items():
+        if any(pattern in raw_section for pattern in patterns):
+            return standard_section
+    return None
+
+
+def parse_symbol_line(line: str) -> tuple[str, str, int, str] | None:
+    """Parse a single symbol line from objdump output.
+
+    Args:
+        line: Line from objdump -t output
+
+    Returns:
+        Tuple of (section, name, size, address) or None if not a valid symbol.
+        Format: address l/g w/d F/O section size name
+        Example: 40084870 l     F .iram0.text    00000000 _xt_user_exc
+    """
+    parts = line.split()
+    if len(parts) < 5:
+        return None
+
+    try:
+        # Validate and extract address
+        address = parts[0]
+        int(address, 16)
+    except ValueError:
+        return None
+
+    # Look for F (function) or O (object) flag
+    if "F" not in parts and "O" not in parts:
+        return None
+
+    # Find section, size, and name
+    # Try each part as a potential section name
+    for i, part in enumerate(parts):
+        # Skip parts that are clearly flags, addresses, or other metadata
+        # Sections start with '.' (standard ELF) or are known section names (Zephyr)
+        section = map_section_name(part)
+        if not section:
+            continue
+
+        # Need at least size field after section
+        if i + 1 >= len(parts):
+            break
+
+        try:
+            size = int(parts[i + 1], 16)
+        except ValueError:
+            break
+
+        # Need symbol name and non-zero size
+        if i + 2 >= len(parts) or size == 0:
+            break
+
+        name = " ".join(parts[i + 2 :])
+        return (section, name, size, address)
+
+    return None

esphome/analyze_memory/ram_strings.py

@@ -0,0 +1,493 @@
+"""Analyzer for RAM-stored strings in ESP8266/ESP32 firmware ELF files.
+
+This module identifies strings that are stored in RAM sections (.data, .bss, .rodata)
+rather than in flash sections (.irom0.text, .irom.text), which is important for
+memory-constrained platforms like ESP8266.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+import logging
+from pathlib import Path
+import re
+import subprocess
+
+from .demangle import batch_demangle
+from .toolchain import find_tool
+
+_LOGGER = logging.getLogger(__name__)
+
+# ESP8266: .rodata is in RAM (DRAM), not flash
+# ESP32: .rodata is in flash, mapped to data bus
+ESP8266_RAM_SECTIONS = frozenset([".data", ".rodata", ".bss"])
+ESP8266_FLASH_SECTIONS = frozenset([".irom0.text", ".irom.text", ".text"])
+
+# ESP32: .rodata is memory-mapped from flash
+ESP32_RAM_SECTIONS = frozenset([".data", ".bss", ".dram0.data", ".dram0.bss"])
+ESP32_FLASH_SECTIONS = frozenset([".text", ".rodata", ".flash.text", ".flash.rodata"])
+
+# nm symbol types for data symbols (D=global data, d=local data, R=rodata, B=bss)
+DATA_SYMBOL_TYPES = frozenset(["D", "d", "R", "r", "B", "b"])
+
+
+@dataclass
+class SectionInfo:
+    """Information about an ELF section."""
+
+    name: str
+    address: int
+    size: int
+
+
+@dataclass
+class RamString:
+    """A string found in RAM."""
+
+    section: str
+    address: int
+    content: str
+
+    @property
+    def size(self) -> int:
+        """Size in bytes including null terminator."""
+        return len(self.content) + 1
+
+
+@dataclass
+class RamSymbol:
+    """A symbol found in RAM."""
+
+    name: str
+    sym_type: str
+    address: int
+    size: int
+    section: str
+    demangled: str = ""  # Demangled name, set after batch demangling
+
+
+class RamStringsAnalyzer:
+    """Analyzes ELF files to find strings stored in RAM."""
+
+    def __init__(
+        self,
+        elf_path: str,
+        objdump_path: str | None = None,
+        min_length: int = 8,
+        platform: str = "esp32",
+    ) -> None:
+        """Initialize the RAM strings analyzer.
+
+        Args:
+            elf_path: Path to the ELF file to analyze
+            objdump_path: Path to objdump binary (used to find other tools)
+            min_length: Minimum string length to report (default: 8)
+            platform: Platform name ("esp8266", "esp32", etc.) for section mapping
+        """
+        self.elf_path = Path(elf_path)
+        if not self.elf_path.exists():
+            raise FileNotFoundError(f"ELF file not found: {elf_path}")
+
+        self.objdump_path = objdump_path
+        self.min_length = min_length
+        self.platform = platform
+
+        # Set RAM/flash sections based on platform
+        if self.platform == "esp8266":
+            self.ram_sections = ESP8266_RAM_SECTIONS
+            self.flash_sections = ESP8266_FLASH_SECTIONS
+        else:
+            # ESP32 and other platforms
+            self.ram_sections = ESP32_RAM_SECTIONS
+            self.flash_sections = ESP32_FLASH_SECTIONS
+
+        self.sections: dict[str, SectionInfo] = {}
+        self.ram_strings: list[RamString] = []
+        self.ram_symbols: list[RamSymbol] = []
+
+    def _run_command(self, cmd: list[str]) -> str:
+        """Run a command and return its output."""
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+            return result.stdout
+        except subprocess.CalledProcessError as e:
+            _LOGGER.debug("Command failed: %s - %s", " ".join(cmd), e.stderr)
+            raise
+        except FileNotFoundError:
+            _LOGGER.warning("Command not found: %s", cmd[0])
+            raise
+
+    def analyze(self) -> None:
+        """Perform the full RAM analysis."""
+        self._parse_sections()
+        self._extract_strings()
+        self._analyze_symbols()
+        self._demangle_symbols()
+
+    def _parse_sections(self) -> None:
+        """Parse section headers from ELF file."""
+        objdump = find_tool("objdump", self.objdump_path)
+        if not objdump:
+            _LOGGER.error("Could not find objdump command")
+            return
+
+        try:
+            output = self._run_command([objdump, "-h", str(self.elf_path)])
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return
+
+        # Parse section headers
+        # Format: Idx Name          Size      VMA       LMA       File off  Algn
+        section_pattern = re.compile(
+            r"^\s*\d+\s+(\S+)\s+([0-9a-fA-F]+)\s+([0-9a-fA-F]+)"
+        )
+
+        for line in output.split("\n"):
+            if match := section_pattern.match(line):
+                name = match.group(1)
+                size = int(match.group(2), 16)
+                vma = int(match.group(3), 16)
+                self.sections[name] = SectionInfo(name, vma, size)
+
+    def _extract_strings(self) -> None:
+        """Extract strings from RAM sections."""
+        objdump = find_tool("objdump", self.objdump_path)
+        if not objdump:
+            return
+
+        for section_name in self.ram_sections:
+            if section_name not in self.sections:
+                continue
+
+            try:
+                output = self._run_command(
+                    [objdump, "-s", "-j", section_name, str(self.elf_path)]
+                )
+            except subprocess.CalledProcessError:
+                # Section may exist but have no content (e.g., .bss)
+                continue
+            except FileNotFoundError:
+                continue
+
+            strings = self._parse_hex_dump(output, section_name)
+            self.ram_strings.extend(strings)
+
+    def _parse_hex_dump(self, output: str, section_name: str) -> list[RamString]:
+        """Parse hex dump output to extract strings.
+
+        Args:
+            output: Output from objdump -s
+            section_name: Name of the section being parsed
+
+        Returns:
+            List of RamString objects
+        """
+        strings: list[RamString] = []
+        current_string = bytearray()
+        string_start_addr = 0
+
+        for line in output.split("\n"):
+            # Lines look like: " 3ffef8a0 00000000 00000000 00000000 00000000  ................"
+            match = re.match(r"^\s+([0-9a-fA-F]+)\s+((?:[0-9a-fA-F]{2,8}\s*)+)", line)
+            if not match:
+                continue
+
+            addr = int(match.group(1), 16)
+            hex_data = match.group(2).strip()
+
+            # Convert hex to bytes
+            hex_bytes = hex_data.split()
+            byte_offset = 0
+            for hex_chunk in hex_bytes:
+                # Handle both byte-by-byte and word formats
+                for i in range(0, len(hex_chunk), 2):
+                    byte_val = int(hex_chunk[i : i + 2], 16)
+                    if 0x20 <= byte_val <= 0x7E:  # Printable ASCII
+                        if not current_string:
+                            string_start_addr = addr + byte_offset
+                        current_string.append(byte_val)
+                    else:
+                        if byte_val == 0 and len(current_string) >= self.min_length:
+                            # Found null terminator
+                            strings.append(
+                                RamString(
+                                    section=section_name,
+                                    address=string_start_addr,
+                                    content=current_string.decode(
+                                        "ascii", errors="ignore"
+                                    ),
+                                )
+                            )
+                        current_string = bytearray()
+                    byte_offset += 1
+
+        return strings
+
+    def _analyze_symbols(self) -> None:
+        """Analyze symbols in RAM sections."""
+        nm = find_tool("nm", self.objdump_path)
+        if not nm:
+            return
+
+        try:
+            output = self._run_command([nm, "-S", "--size-sort", str(self.elf_path)])
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return
+
+        for line in output.split("\n"):
+            parts = line.split()
+            if len(parts) < 4:
+                continue
+
+            try:
+                addr = int(parts[0], 16)
+                size = int(parts[1], 16) if parts[1] != "?" else 0
+            except ValueError:
+                continue
+
+            sym_type = parts[2]
+            name = " ".join(parts[3:])
+
+            # Filter for data symbols
+            if sym_type not in DATA_SYMBOL_TYPES:
+                continue
+
+            # Check if symbol is in a RAM section
+            for section_name in self.ram_sections:
+                if section_name not in self.sections:
+                    continue
+
+                section = self.sections[section_name]
+                if section.address <= addr < section.address + section.size:
+                    self.ram_symbols.append(
+                        RamSymbol(
+                            name=name,
+                            sym_type=sym_type,
+                            address=addr,
+                            size=size,
+                            section=section_name,
+                        )
+                    )
+                    break
+
+    def _demangle_symbols(self) -> None:
+        """Batch demangle all RAM symbol names."""
+        if not self.ram_symbols:
+            return
+
+        # Collect all symbol names and demangle them
+        symbol_names = [s.name for s in self.ram_symbols]
+        demangle_cache = batch_demangle(symbol_names, objdump_path=self.objdump_path)
+
+        # Assign demangled names to symbols
+        for symbol in self.ram_symbols:
+            symbol.demangled = demangle_cache.get(symbol.name, symbol.name)
+
+    def _get_sections_size(self, section_names: frozenset[str]) -> int:
+        """Get total size of specified sections."""
+        return sum(
+            section.size
+            for name, section in self.sections.items()
+            if name in section_names
+        )
+
+    def get_total_ram_usage(self) -> int:
+        """Get total RAM usage from RAM sections."""
+        return self._get_sections_size(self.ram_sections)
+
+    def get_total_flash_usage(self) -> int:
+        """Get total flash usage from flash sections."""
+        return self._get_sections_size(self.flash_sections)
+
+    def get_total_string_bytes(self) -> int:
+        """Get total bytes used by strings in RAM."""
+        return sum(s.size for s in self.ram_strings)
+
+    def get_repeated_strings(self) -> list[tuple[str, int]]:
+        """Find strings that appear multiple times.
+
+        Returns:
+            List of (string, count) tuples sorted by potential savings
+        """
+        string_counts: dict[str, int] = defaultdict(int)
+        for ram_string in self.ram_strings:
+            string_counts[ram_string.content] += 1
+
+        return sorted(
+            [(s, c) for s, c in string_counts.items() if c > 1],
+            key=lambda x: x[1] * (len(x[0]) + 1),
+            reverse=True,
+        )
+
+    def get_long_strings(self, min_len: int = 20) -> list[RamString]:
+        """Get strings longer than the specified length.
+
+        Args:
+            min_len: Minimum string length
+
+        Returns:
+            List of RamString objects sorted by length
+        """
+        return sorted(
+            [s for s in self.ram_strings if len(s.content) >= min_len],
+            key=lambda x: len(x.content),
+            reverse=True,
+        )
+
+    def get_largest_symbols(self, min_size: int = 100) -> list[RamSymbol]:
+        """Get RAM symbols larger than the specified size.
+
+        Args:
+            min_size: Minimum symbol size in bytes
+
+        Returns:
+            List of RamSymbol objects sorted by size
+        """
+        return sorted(
+            [s for s in self.ram_symbols if s.size >= min_size],
+            key=lambda x: x.size,
+            reverse=True,
+        )
+
+    def generate_report(self, show_all_sections: bool = False) -> str:
+        """Generate a formatted RAM strings analysis report.
+
+        Args:
+            show_all_sections: If True, show all sections, not just RAM
+
+        Returns:
+            Formatted report string
+        """
+        lines: list[str] = []
+        table_width = 80
+
+        lines.append("=" * table_width)
+        lines.append(
+            f"RAM Strings Analysis ({self.platform.upper()})".center(table_width)
+        )
+        lines.append("=" * table_width)
+        lines.append("")
+
+        # Section Analysis
+        lines.append("SECTION ANALYSIS")
+        lines.append("-" * table_width)
+        lines.append(f"{'Section':<20} {'Address':<12} {'Size':<12} {'Location'}")
+        lines.append("-" * table_width)
+
+        total_ram_usage = 0
+        total_flash_usage = 0
+
+        for name, section in sorted(self.sections.items(), key=lambda x: x[1].address):
+            if name in self.ram_sections:
+                location = "RAM"
+                total_ram_usage += section.size
+            elif name in self.flash_sections:
+                location = "FLASH"
+                total_flash_usage += section.size
+            else:
+                location = "OTHER"
+
+            if show_all_sections or name in self.ram_sections:
+                lines.append(
+                    f"{name:<20} 0x{section.address:08x}   {section.size:>8} B   {location}"
+                )
+
+        lines.append("-" * table_width)
+        lines.append(f"Total RAM sections size: {total_ram_usage:,} bytes")
+        lines.append(f"Total Flash sections size: {total_flash_usage:,} bytes")
+
+        # Strings in RAM
+        lines.append("")
+        lines.append("=" * table_width)
+        lines.append("STRINGS IN RAM SECTIONS")
+        lines.append("=" * table_width)
+        lines.append(
+            "Note: .bss sections contain uninitialized data (no strings to extract)"
+        )
+
+        # Group strings by section
+        strings_by_section: dict[str, list[RamString]] = defaultdict(list)
+        for ram_string in self.ram_strings:
+            strings_by_section[ram_string.section].append(ram_string)
+
+        for section_name in sorted(strings_by_section.keys()):
+            section_strings = strings_by_section[section_name]
+            lines.append(f"\nSection: {section_name}")
+            lines.append("-" * 40)
+            for ram_string in sorted(section_strings, key=lambda x: x.address):
+                clean_string = ram_string.content[:100] + (
+                    "..." if len(ram_string.content) > 100 else ""
+                )
+                lines.append(
+                    f'  0x{ram_string.address:08x}: "{clean_string}" (len={len(ram_string.content)})'
+                )
+
+        # Large RAM symbols
+        lines.append("")
+        lines.append("=" * table_width)
+        lines.append("LARGE DATA SYMBOLS IN RAM (>= 50 bytes)")
+        lines.append("=" * table_width)
+
+        largest_symbols = self.get_largest_symbols(50)
+        lines.append(f"\n{'Symbol':<50} {'Type':<6} {'Size':<10} {'Section'}")
+        lines.append("-" * table_width)
+
+        for symbol in largest_symbols:
+            # Use demangled name if available, otherwise raw name
+            display_name = symbol.demangled or symbol.name
+            name_display = display_name[:49] if len(display_name) > 49 else display_name
+            lines.append(
+                f"{name_display:<50} {symbol.sym_type:<6} {symbol.size:>8} B  {symbol.section}"
+            )
+
+        # Summary
+        lines.append("")
+        lines.append("=" * table_width)
+        lines.append("SUMMARY")
+        lines.append("=" * table_width)
+        lines.append(f"Total strings found in RAM: {len(self.ram_strings)}")
+        total_string_bytes = self.get_total_string_bytes()
+        lines.append(f"Total bytes used by strings: {total_string_bytes:,}")
+
+        # Optimization targets
+        lines.append("")
+        lines.append("=" * table_width)
+        lines.append("POTENTIAL OPTIMIZATION TARGETS")
+        lines.append("=" * table_width)
+
+        # Repeated strings
+        repeated = self.get_repeated_strings()[:10]
+        if repeated:
+            lines.append("\nRepeated strings (could be deduplicated):")
+            for string, count in repeated:
+                savings = (count - 1) * (len(string) + 1)
+                clean_string = string[:50] + ("..." if len(string) > 50 else "")
+                lines.append(
+                    f'  "{clean_string}" - appears {count} times (potential savings: {savings} bytes)'
+                )
+
+        # Long strings - platform-specific advice
+        long_strings = self.get_long_strings(20)[:10]
+        if long_strings:
+            if self.platform == "esp8266":
+                lines.append(
+                    "\nLong strings that could be moved to PROGMEM (>= 20 chars):"
+                )
+            else:
+                # ESP32: strings in DRAM are typically there for a reason
+                # (interrupt handlers, pre-flash-init code, etc.)
+                lines.append("\nLong strings in DRAM (>= 20 chars):")
+                lines.append(
+                    "Note: ESP32 DRAM strings may be required for interrupt/early-boot contexts"
+                )
+            for ram_string in long_strings:
+                clean_string = ram_string.content[:60] + (
+                    "..." if len(ram_string.content) > 60 else ""
+                )
+                lines.append(
+                    f'  {ram_string.section} @ 0x{ram_string.address:08x}: "{clean_string}" ({len(ram_string.content)} bytes)'
+                )
+
+        lines.append("")
+        return "\n".join(lines)

esphome/analyze_memory/toolchain.py

@@ -0,0 +1,173 @@
+"""Toolchain utilities for memory analysis."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+import subprocess
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+_LOGGER = logging.getLogger(__name__)
+
+# Platform-specific toolchain prefixes
+TOOLCHAIN_PREFIXES = [
+    "xtensa-lx106-elf-",  # ESP8266
+    "xtensa-esp32-elf-",  # ESP32
+    "xtensa-esp-elf-",  # ESP32 (newer IDF)
+    "arm-zephyr-eabi-",  # nRF52/Zephyr SDK
+    "arm-none-eabi-",  # Generic ARM (RP2040, etc.)
+    "",  # System default (no prefix)
+]
+
+
+def _find_in_platformio_packages(tool_name: str) -> str | None:
+    """Search for a tool in PlatformIO package directories.
+
+    This handles cases like Zephyr SDK where tools are installed in nested
+    directories that aren't in PATH.
+
+    Args:
+        tool_name: Name of the tool (e.g., "readelf", "objdump")
+
+    Returns:
+        Full path to the tool or None if not found
+    """
+    # Get PlatformIO packages directory
+    platformio_home = Path(os.path.expanduser("~/.platformio/packages"))
+    if not platformio_home.exists():
+        return None
+
+    # Search patterns for toolchains that might contain the tool
+    # Order matters - more specific patterns first
+    search_patterns = [
+        # Zephyr SDK deeply nested structure (4 levels)
+        # e.g., toolchain-gccarmnoneeabi/zephyr-sdk-0.17.4/arm-zephyr-eabi/bin/arm-zephyr-eabi-objdump
+        f"toolchain-*/*/*/bin/*-{tool_name}",
+        # Zephyr SDK nested structure (3 levels)
+        f"toolchain-*/*/bin/*-{tool_name}",
+        f"toolchain-*/bin/*-{tool_name}",
+        # Standard PlatformIO toolchain structure
+        f"toolchain-*/bin/*{tool_name}",
+    ]
+
+    for pattern in search_patterns:
+        matches = list(platformio_home.glob(pattern))
+        if matches:
+            # Sort to get consistent results, prefer arm-zephyr-eabi over arm-none-eabi
+            matches.sort(key=lambda p: ("zephyr" not in str(p), str(p)))
+            tool_path = str(matches[0])
+            _LOGGER.debug("Found %s in PlatformIO packages: %s", tool_name, tool_path)
+            return tool_path
+
+    return None
+
+
+def resolve_tool_path(
+    tool_name: str,
+    derived_path: str | None,
+    objdump_path: str | None = None,
+) -> str | None:
+    """Resolve a tool path, falling back to find_tool if derived path doesn't exist.
+
+    Args:
+        tool_name: Name of the tool (e.g., "objdump", "readelf")
+        derived_path: Path derived from idedata (may not exist for some platforms)
+        objdump_path: Path to objdump binary to derive other tool paths from
+
+    Returns:
+        Resolved path to the tool, or the original derived_path if it exists
+    """
+    if derived_path and not Path(derived_path).exists():
+        found = find_tool(tool_name, objdump_path)
+        if found:
+            _LOGGER.debug(
+                "Derived %s path %s not found, using %s",
+                tool_name,
+                derived_path,
+                found,
+            )
+            return found
+    return derived_path
+
+
+def find_tool(
+    tool_name: str,
+    objdump_path: str | None = None,
+) -> str | None:
+    """Find a toolchain tool by name.
+
+    First tries to derive the tool path from objdump_path (if provided),
+    then searches PlatformIO package directories (for cross-compile toolchains),
+    and finally falls back to searching for platform-specific tools in PATH.
+
+    Args:
+        tool_name: Name of the tool (e.g., "objdump", "nm", "c++filt")
+        objdump_path: Path to objdump binary to derive other tool paths from
+
+    Returns:
+        Path to the tool or None if not found
+    """
+    # Try to derive from objdump path first (most reliable)
+    if objdump_path and objdump_path != "objdump":
+        objdump_file = Path(objdump_path)
+        # Replace just the filename portion, preserving any prefix (e.g., xtensa-esp32-elf-)
+        new_name = objdump_file.name.replace("objdump", tool_name)
+        potential_path = str(objdump_file.with_name(new_name))
+        if Path(potential_path).exists():
+            _LOGGER.debug("Found %s at: %s", tool_name, potential_path)
+            return potential_path
+
+    # Search in PlatformIO packages directory first (handles Zephyr SDK, etc.)
+    # This must come before PATH search because system tools (e.g., /usr/bin/objdump)
+    # are for the host architecture, not the target (ARM, Xtensa, etc.)
+    if found := _find_in_platformio_packages(tool_name):
+        return found
+
+    # Try platform-specific tools in PATH (fallback for when tools are installed globally)
+    for prefix in TOOLCHAIN_PREFIXES:
+        cmd = f"{prefix}{tool_name}"
+        try:
+            subprocess.run([cmd, "--version"], capture_output=True, check=True)
+            _LOGGER.debug("Found %s: %s", tool_name, cmd)
+            return cmd
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            continue
+
+    _LOGGER.warning("Could not find %s tool", tool_name)
+    return None
+
+
+def run_tool(
+    cmd: Sequence[str],
+    timeout: int = 30,
+) -> subprocess.CompletedProcess[str] | None:
+    """Run a toolchain command and return the result.
+
+    Args:
+        cmd: Command and arguments to run
+        timeout: Timeout in seconds
+
+    Returns:
+        CompletedProcess on success, None on failure
+    """
+    try:
+        return subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        _LOGGER.warning("Command timed out: %s", " ".join(cmd))
+        return None
+    except FileNotFoundError:
+        _LOGGER.warning("Command not found: %s", cmd[0])
+        return None
+    except OSError as e:
+        _LOGGER.warning("Failed to run command %s: %s", cmd[0], e)
+        return None

esphome/async_thread.py

@@ -0,0 +1,56 @@
+"""Helpers for running an async coroutine from sync code via a daemon thread.
+
+``asyncio.run(coro())`` in the main thread blocks until the loop's cleanup
+cycle finishes, which can add hundreds of milliseconds before the caller
+receives the result. Running the loop in a daemon thread lets the caller
+observe the result as soon as the coroutine completes while cleanup finishes
+in the background.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+import threading
+from typing import Generic, TypeVar
+
+_T = TypeVar("_T")
+
+
+class AsyncThreadRunner(threading.Thread, Generic[_T]):
+    """Run an async coroutine in a daemon thread and expose its result.
+
+    The runner catches all exceptions from the coroutine and stores them in
+    ``exception`` so ``event`` is always set — this prevents callers waiting
+    on ``event`` from hanging forever when the coroutine crashes.
+
+    Typical usage::
+
+        runner = AsyncThreadRunner(lambda: my_coro(arg))
+        runner.start()
+        if not runner.event.wait(timeout=5.0):
+            ...  # timed out
+        if runner.exception is not None:
+            raise runner.exception
+        result = runner.result
+    """
+
+    def __init__(self, coro_factory: Callable[[], Awaitable[_T]]) -> None:
+        super().__init__(daemon=True)
+        self._coro_factory = coro_factory
+        self.result: _T | None = None
+        self.exception: BaseException | None = None
+        self.event = threading.Event()
+
+    async def _runner(self) -> None:
+        try:
+            self.result = await self._coro_factory()
+        except Exception as exc:  # pylint: disable=broad-except
+            # Capture all exceptions so ``event`` is always set — otherwise a
+            # crash would hang the waiter forever.
+            self.exception = exc
+        finally:
+            self.event.set()
+
+    def run(self) -> None:
+        asyncio.run(self._runner())

esphome/automation.py

@@ -1,3 +1,6 @@
+from dataclasses import dataclass, field
+import logging
+
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
@@ -15,8 +18,13 @@ from esphome.const import (
     CONF_TYPE_ID,
     CONF_UPDATE_INTERVAL,
 )
-from esphome.core import ID
-from esphome.cpp_generator import MockObj, MockObjClass, TemplateArgsType
+from esphome.core import ID, Lambda
+from esphome.cpp_generator import (
+    LambdaExpression,
+    MockObj,
+    MockObjClass,
+    TemplateArgsType,
+)
 from esphome.schema_extractors import SCHEMA_EXTRACT, schema_extractor
 from esphome.types import ConfigType
 from esphome.util import Registry
@@ -52,8 +60,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):
@@ -85,8 +127,9 @@ def validate_potentially_or_condition(value):
     return validate_condition(value)
 
 
-DelayAction = cg.esphome_ns.class_("DelayAction", Action, cg.Component)
+DelayAction = cg.esphome_ns.class_("DelayAction", Action)
 LambdaAction = cg.esphome_ns.class_("LambdaAction", Action)
+StatelessLambdaAction = cg.esphome_ns.class_("StatelessLambdaAction", Action)
 IfAction = cg.esphome_ns.class_("IfAction", Action)
 WhileAction = cg.esphome_ns.class_("WhileAction", Action)
 RepeatAction = cg.esphome_ns.class_("RepeatAction", Action)
@@ -95,11 +138,45 @@ UpdateComponentAction = cg.esphome_ns.class_("UpdateComponentAction", Action)
 SuspendComponentAction = cg.esphome_ns.class_("SuspendComponentAction", Action)
 ResumeComponentAction = cg.esphome_ns.class_("ResumeComponentAction", Action)
 Automation = cg.esphome_ns.class_("Automation")
+TriggerForwarder = cg.esphome_ns.class_("TriggerForwarder")
+TriggerOnTrueForwarder = cg.esphome_ns.class_("TriggerOnTrueForwarder")
+TriggerOnFalseForwarder = cg.esphome_ns.class_("TriggerOnFalseForwarder")
 
 LambdaCondition = cg.esphome_ns.class_("LambdaCondition", Condition)
+StatelessLambdaCondition = cg.esphome_ns.class_("StatelessLambdaCondition", Condition)
 ForCondition = cg.esphome_ns.class_("ForCondition", Condition, cg.Component)
 
 
+def new_lambda_pvariable(
+    id_obj: ID,
+    lambda_expr: LambdaExpression,
+    stateless_class: MockObjClass,
+    template_arg: cg.TemplateArguments | None = None,
+) -> MockObj:
+    """Create Pvariable for lambda, using stateless class if applicable.
+
+    Combines ID selection and Pvariable creation in one call. For stateless
+    lambdas (empty capture), uses function pointer instead of std::function.
+
+    Args:
+        id_obj: The ID object (action_id, condition_id, or filter_id)
+        lambda_expr: The lambda expression object
+        stateless_class: The stateless class to use for stateless lambdas
+        template_arg: Optional template arguments (for actions/conditions)
+
+    Returns:
+        The created Pvariable
+    """
+    # For stateless lambdas, use function pointer instead of std::function
+    if lambda_expr.capture == "":
+        id_obj = id_obj.copy()
+        id_obj.type = stateless_class
+
+    if template_arg is not None:
+        return cg.new_Pvariable(id_obj, template_arg, lambda_expr)
+    return cg.new_Pvariable(id_obj, lambda_expr)
+
+
 def validate_automation(extra_schema=None, extra_validators=None, single=False):
     if extra_schema is None:
         extra_schema = {}
@@ -122,11 +199,10 @@ def validate_automation(extra_schema=None, extra_validators=None, single=False):
                     return cv.Schema([schema])(value)
                 except cv.Invalid as err2:
                     if "extra keys not allowed" in str(err2) and len(err2.path) == 2:
-                        # pylint: disable=raise-missing-from
-                        raise err
+                        raise err from None
                     if "Unable to find action" in str(err):
-                        raise err2
-                    raise cv.MultipleInvalid([err, err2])
+                        raise err2 from None
+                    raise cv.MultipleInvalid([err, err2]) from None
         elif isinstance(value, dict):
             if CONF_THEN in value:
                 return [schema(value)]
@@ -145,7 +221,7 @@ def validate_automation(extra_schema=None, extra_validators=None, single=False):
             value = cv.Schema([extra_validators])(value)
         if single:
             if len(value) != 1:
-                raise cv.Invalid("Cannot have more than 1 automation for templates")
+                raise cv.Invalid("This trigger allows only a single automation")
             return value[0]
         return value
 
@@ -174,7 +250,9 @@ async def and_condition_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     conditions = await build_condition_list(config, template_arg, args)
-    return cg.new_Pvariable(condition_id, template_arg, conditions)
+    return cg.new_Pvariable(
+        condition_id, cg.TemplateArguments(len(conditions), *template_arg), conditions
+    )
 
 
 @register_condition("or", OrCondition, validate_condition_list)
@@ -185,7 +263,9 @@ async def or_condition_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     conditions = await build_condition_list(config, template_arg, args)
-    return cg.new_Pvariable(condition_id, template_arg, conditions)
+    return cg.new_Pvariable(
+        condition_id, cg.TemplateArguments(len(conditions), *template_arg), conditions
+    )
 
 
 @register_condition("all", AndCondition, validate_condition_list)
@@ -196,7 +276,9 @@ async def all_condition_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     conditions = await build_condition_list(config, template_arg, args)
-    return cg.new_Pvariable(condition_id, template_arg, conditions)
+    return cg.new_Pvariable(
+        condition_id, cg.TemplateArguments(len(conditions), *template_arg), conditions
+    )
 
 
 @register_condition("any", OrCondition, validate_condition_list)
@@ -207,7 +289,9 @@ async def any_condition_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     conditions = await build_condition_list(config, template_arg, args)
-    return cg.new_Pvariable(condition_id, template_arg, conditions)
+    return cg.new_Pvariable(
+        condition_id, cg.TemplateArguments(len(conditions), *template_arg), conditions
+    )
 
 
 @register_condition("not", NotCondition, validate_potentially_and_condition)
@@ -229,7 +313,9 @@ async def xor_condition_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     conditions = await build_condition_list(config, template_arg, args)
-    return cg.new_Pvariable(condition_id, template_arg, conditions)
+    return cg.new_Pvariable(
+        condition_id, cg.TemplateArguments(len(conditions), *template_arg), conditions
+    )
 
 
 @register_condition("lambda", LambdaCondition, cv.returning_lambda)
@@ -240,7 +326,9 @@ async def lambda_condition_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     lambda_ = await cg.process_lambda(config, args, return_type=bool)
-    return cg.new_Pvariable(condition_id, template_arg, lambda_)
+    return new_lambda_pvariable(
+        condition_id, lambda_, StatelessLambdaCondition, template_arg
+    )
 
 
 @register_condition(
@@ -271,8 +359,35 @@ async def for_condition_to_code(
     return var
 
 
+@register_condition(
+    "component.is_idle",
+    LambdaCondition,
+    maybe_simple_id(
+        {
+            cv.Required(CONF_ID): cv.use_id(cg.Component),
+        }
+    ),
+)
+async def component_is_idle_condition_to_code(
+    config: ConfigType,
+    condition_id: ID,
+    template_arg: cg.TemplateArguments,
+    args: TemplateArgsType,
+) -> MockObj:
+    comp = await cg.get_variable(config[CONF_ID])
+    lambda_ = await cg.process_lambda(
+        Lambda(f"return {comp}->is_idle();"), args, return_type=bool
+    )
+    return new_lambda_pvariable(
+        condition_id, lambda_, StatelessLambdaCondition, template_arg
+    )
+
+
 @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,
@@ -281,7 +396,6 @@ async def delay_action_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     var = cg.new_Pvariable(action_id, template_arg)
-    await cg.register_component(var, {})
     template_ = await cg.templatable(config, args, cg.uint32)
     cg.add(var.set_delay(template_))
     return var
@@ -303,6 +417,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,
@@ -310,13 +425,16 @@ async def if_action_to_code(
     template_arg: cg.TemplateArguments,
     args: TemplateArgsType,
 ) -> MockObj:
+    has_else = CONF_ELSE in config
+    # Prepend HasElse bool to template arguments: IfAction<HasElse, Ts...>
+    if_template_arg = cg.TemplateArguments(has_else, *template_arg)
     cond_conf = next(el for el in config if el in (CONF_ANY, CONF_ALL, CONF_CONDITION))
     condition = await build_condition(config[cond_conf], template_arg, args)
-    var = cg.new_Pvariable(action_id, template_arg, condition)
+    var = cg.new_Pvariable(action_id, if_template_arg, condition)
     if CONF_THEN in config:
         actions = await build_action_list(config[CONF_THEN], template_arg, args)
         cg.add(var.add_then(actions))
-    if CONF_ELSE in config:
+    if has_else:
         actions = await build_action_list(config[CONF_ELSE], template_arg, args)
         cg.add(var.add_else(actions))
     return var
@@ -331,6 +449,7 @@ async def if_action_to_code(
             cv.Required(CONF_THEN): validate_action_list,
         }
     ),
+    synchronous=True,
 )
 async def while_action_to_code(
     config: ConfigType,
@@ -354,6 +473,7 @@ async def while_action_to_code(
             cv.Required(CONF_THEN): validate_action_list,
         }
     ),
+    synchronous=True,
 )
 async def repeat_action_to_code(
     config: ConfigType,
@@ -382,7 +502,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,
@@ -398,7 +518,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,
@@ -406,7 +531,7 @@ async def lambda_action_to_code(
     args: TemplateArgsType,
 ) -> MockObj:
     lambda_ = await cg.process_lambda(config, args, return_type=cg.void)
-    return cg.new_Pvariable(action_id, template_arg, lambda_)
+    return new_lambda_pvariable(action_id, lambda_, StatelessLambdaAction, template_arg)
 
 
 @register_action(
@@ -417,6 +542,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,
@@ -436,6 +562,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,
@@ -458,6 +585,7 @@ async def component_suspend_action_to_code(
             ),
         }
     ),
+    synchronous=True,
 )
 async def component_resume_action_to_code(
     config: ConfigType,
@@ -468,7 +596,7 @@ async def component_resume_action_to_code(
     comp = await cg.get_variable(config[CONF_ID])
     var = cg.new_Pvariable(action_id, template_arg, comp)
     if CONF_UPDATE_INTERVAL in config:
-        template_ = await cg.templatable(config[CONF_UPDATE_INTERVAL], args, int)
+        template_ = await cg.templatable(config[CONF_UPDATE_INTERVAL], args, cg.uint32)
         cg.add(var.set_update_interval(template_))
     return var
 
@@ -515,6 +643,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:
@@ -524,3 +673,76 @@ async def build_automation(
     actions = await build_action_list(config[CONF_THEN], templ, args)
     cg.add(obj.add_actions(actions))
     return obj
+
+
+async def build_callback_automation(
+    parent: MockObj,
+    callback_method: str,
+    args: TemplateArgsType,
+    config: ConfigType,
+    forwarder: MockObj | MockObjClass | None = None,
+) -> None:
+    """Build an Automation and register it as a callback on the parent.
+
+    Eliminates the need for a Trigger wrapper object by registering the
+    automation's trigger() directly as a callback on the parent component.
+
+    Uses template forwarder structs so the compiler deduplicates the operator()
+    body across all call sites with the same signature. The forwarder must be
+    pointer-sized (single Automation* field) to fit inline in Callback::ctx_
+    and avoid heap allocation.
+
+    :param parent: The component object (e.g., button, sensor).
+    :param callback_method: Name of the callback method (e.g., "add_on_press_callback").
+    :param args: Automation template args as list of (type, name) tuples.
+    :param config: The automation config dict.
+    :param forwarder: Optional forwarder type to use instead of the default
+        TriggerForwarder<Ts...>. Pass any struct type whose aggregate init takes
+        a single Automation pointer (e.g., TriggerOnTrueForwarder).
+    """
+    arg_types = [arg[0] for arg in args]
+    templ = cg.TemplateArguments(*arg_types)
+    obj = cg.new_Pvariable(config[CONF_AUTOMATION_ID], templ)
+    actions = await build_action_list(config[CONF_THEN], templ, args)
+    cg.add(obj.add_actions(actions))
+    # Use template forwarder structs for deduplication. The compiler generates
+    # one operator() per forwarder type; different automation pointers are just
+    # data in the struct.
+    if forwarder is None:
+        forwarder = TriggerForwarder.template(templ)
+    # RawExpression for aggregate init — both forwarder and obj are codegen
+    # MockObjs (not user input), and there's no Expression type for positional
+    # aggregate initialization (StructInitializer uses named fields).
+    cg.add(getattr(parent, callback_method)(cg.RawExpression(f"{forwarder}{{{obj}}}")))
+
+
+@dataclass(frozen=True, slots=True)
+class CallbackAutomation:
+    """A single callback automation entry for build_callback_automations."""
+
+    conf_key: str
+    callback_method: str
+    args: TemplateArgsType = field(default_factory=list)
+    forwarder: MockObj | MockObjClass | None = None
+
+
+async def build_callback_automations(
+    parent: MockObj,
+    config: ConfigType,
+    entries: tuple[CallbackAutomation, ...],
+) -> None:
+    """Build multiple callback automations from a tuple of entries.
+
+    :param parent: The component object (e.g., button, sensor).
+    :param config: The full component config dict.
+    :param entries: Tuple of CallbackAutomation entries to process.
+    """
+    for entry in entries:
+        for conf in config.get(entry.conf_key, []):
+            await build_callback_automation(
+                parent,
+                entry.callback_method,
+                entry.args,
+                conf,
+                forwarder=entry.forwarder,
+            )

esphome/build_gen/espidf.py

@@ -0,0 +1,172 @@
+"""ESP-IDF direct build generator for ESPHome."""
+
+import json
+from pathlib import Path
+
+from esphome.components.esp32 import get_esp32_variant
+from esphome.core import CORE
+from esphome.helpers import mkdir_p, write_file_if_changed
+from esphome.writer import update_storage_json
+
+
+def get_available_components() -> list[str] | None:
+    """Get list of available ESP-IDF components from project_description.json.
+
+    Returns only internal ESP-IDF components, excluding external/managed
+    components (from idf_component.yml).
+    """
+    project_desc = Path(CORE.build_path) / "build" / "project_description.json"
+    if not project_desc.exists():
+        return None
+
+    try:
+        with open(project_desc, encoding="utf-8") as f:
+            data = json.load(f)
+
+        component_info = data.get("build_component_info", {})
+
+        result = []
+        for name, info in component_info.items():
+            # Exclude our own src component
+            if name == "src":
+                continue
+
+            # Exclude managed/external components
+            comp_dir = info.get("dir", "")
+            if "managed_components" in comp_dir:
+                continue
+
+            result.append(name)
+
+        return result
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def has_discovered_components() -> bool:
+    """Check if we have discovered components from a previous configure."""
+    return get_available_components() is not None
+
+
+def get_project_cmakelists() -> str:
+    """Generate the top-level CMakeLists.txt for ESP-IDF project."""
+    # Get IDF target from ESP32 variant (e.g., ESP32S3 -> esp32s3)
+    variant = get_esp32_variant()
+    idf_target = variant.lower().replace("-", "")
+
+    # Extract compile definitions from build flags (-DXXX -> XXX)
+    compile_defs = [flag for flag in sorted(CORE.build_flags) if flag.startswith("-D")]
+    extra_compile_options = "\n".join(
+        f'idf_build_set_property(COMPILE_OPTIONS "{compile_def}" APPEND)'
+        for compile_def in compile_defs
+    )
+
+    return f"""\
+# Auto-generated by ESPHome
+cmake_minimum_required(VERSION 3.16)
+
+# On Windows, Ninja can fail with:
+#   "CreateProcess: The parameter is incorrect (is the command line too long?)"
+# when compiler/linker command lines exceed the OS length limit.
+#
+# The following settings force CMake/Ninja to use *response files* (@file.rsp)
+# to pass long lists of includes, objects, and other arguments indirectly,
+# avoiding command-line length limits and fixing the build failure.
+#
+# This is especially useful for large ESP-IDF / ESPHome projects with many
+# source files or include directories.
+set(CMAKE_C_USE_RESPONSE_FILE_FOR_INCLUDES 1)
+set(CMAKE_CXX_USE_RESPONSE_FILE_FOR_INCLUDES 1)
+set(CMAKE_C_USE_RESPONSE_FILE_FOR_OBJECTS 1)
+set(CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS 1)
+set(CMAKE_NINJA_FORCE_RESPONSE_FILE 1)
+
+set(IDF_TARGET {idf_target})
+set(EXTRA_COMPONENT_DIRS ${{CMAKE_SOURCE_DIR}}/src)
+
+include($ENV{{IDF_PATH}}/tools/cmake/project.cmake)
+
+{extra_compile_options}
+
+project({CORE.name})
+
+# Emit raw JSON size data for ESPHome to read post-build.
+add_custom_command(
+    TARGET ${{CMAKE_PROJECT_NAME}}.elf POST_BUILD
+    COMMAND ${{PYTHON}} -m esp_idf_size --ng --format=raw
+            -o ${{CMAKE_BINARY_DIR}}/esp_idf_size.json
+            ${{CMAKE_PROJECT_NAME}}.map
+    WORKING_DIRECTORY ${{CMAKE_BINARY_DIR}}
+    VERBATIM
+)
+"""
+
+
+def get_component_cmakelists(minimal: bool = False) -> str:
+    """Generate the main component CMakeLists.txt."""
+    idf_requires = [] if minimal else (get_available_components() or [])
+    requires_str = " ".join(idf_requires)
+
+    # Extract compile options (-W flags, excluding linker flags)
+    compile_opts = [
+        flag
+        for flag in CORE.build_flags
+        if flag.startswith("-W") and not flag.startswith("-Wl,")
+    ]
+    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(sorted(link_opts)) if link_opts else ""
+
+    return f"""\
+# Auto-generated by ESPHome
+file(GLOB_RECURSE app_sources
+    "${{CMAKE_CURRENT_SOURCE_DIR}}/*.cpp"
+    "${{CMAKE_CURRENT_SOURCE_DIR}}/*.c"
+    "${{CMAKE_CURRENT_SOURCE_DIR}}/esphome/*.cpp"
+    "${{CMAKE_CURRENT_SOURCE_DIR}}/esphome/*.c"
+)
+
+idf_component_register(
+    SRCS ${{app_sources}}
+    INCLUDE_DIRS "." "esphome"
+    REQUIRES {requires_str}
+)
+
+# Apply C++ standard
+target_compile_features(${{COMPONENT_LIB}} PUBLIC cxx_std_20)
+
+# ESPHome compile options
+target_compile_options(${{COMPONENT_LIB}} PUBLIC
+    {compile_opts_str}
+)
+
+# ESPHome linker options
+target_link_options(${{COMPONENT_LIB}} PUBLIC
+    {link_opts_str}
+)
+"""
+
+
+def write_project(minimal: bool = False) -> None:
+    """Write ESP-IDF project files."""
+    # Refresh <data_dir>/storage/<name>.yaml.json so the dashboard's
+    # /info and /downloads endpoints can locate the build (they 404
+    # otherwise). This mirrors the PlatformIO build-gen path's call
+    # in build_gen/platformio.py:write_ini().
+    update_storage_json()
+    mkdir_p(CORE.build_path)
+    mkdir_p(CORE.relative_src_path())
+
+    # Write top-level CMakeLists.txt
+    write_file_if_changed(
+        CORE.relative_build_path("CMakeLists.txt"),
+        get_project_cmakelists(),
+    )
+
+    # Write component CMakeLists.txt in src/
+    write_file_if_changed(
+        CORE.relative_src_path("CMakeLists.txt"),
+        get_component_cmakelists(minimal=minimal),
+    )

esphome/bundle.py

@@ -0,0 +1,767 @@
+"""Config bundle creator and extractor for ESPHome.
+
+A bundle is a self-contained .tar.gz archive containing a YAML config
+and every local file it depends on. Bundles can be created from a config
+and compiled directly: ``esphome compile my_device.esphomebundle.tar.gz``
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+import io
+import json
+import logging
+from pathlib import Path
+import re
+import shutil
+import tarfile
+from typing import Any
+
+from esphome import const, yaml_util
+from esphome.const import (
+    CONF_ESPHOME,
+    CONF_EXTERNAL_COMPONENTS,
+    CONF_INCLUDES,
+    CONF_INCLUDES_C,
+    CONF_PATH,
+    CONF_SOURCE,
+    CONF_TYPE,
+)
+from esphome.core import CORE, EsphomeError
+
+_LOGGER = logging.getLogger(__name__)
+
+BUNDLE_EXTENSION = ".esphomebundle.tar.gz"
+MANIFEST_FILENAME = "manifest.json"
+CURRENT_MANIFEST_VERSION = 1
+MAX_DECOMPRESSED_SIZE = 500 * 1024 * 1024  # 500 MB
+MAX_MANIFEST_SIZE = 1024 * 1024  # 1 MB
+
+# Directories preserved across bundle extractions (build caches)
+_PRESERVE_DIRS = (".esphome", ".pioenvs", ".pio")
+_BUNDLE_STAGING_DIR = ".bundle_staging"
+
+
+class ManifestKey(StrEnum):
+    """Keys used in bundle manifest.json."""
+
+    MANIFEST_VERSION = "manifest_version"
+    ESPHOME_VERSION = "esphome_version"
+    CONFIG_FILENAME = "config_filename"
+    FILES = "files"
+    HAS_SECRETS = "has_secrets"
+
+
+# String prefixes that are never local file paths
+_NON_PATH_PREFIXES = ("http://", "https://", "ftp://", "mdi:", "<")
+
+# File extensions recognized when resolving relative path strings.
+# A relative string with one of these extensions is resolved against the
+# config directory and included if the file exists.
+_KNOWN_FILE_EXTENSIONS = frozenset(
+    {
+        # Fonts
+        ".ttf",
+        ".otf",
+        ".woff",
+        ".woff2",
+        ".pcf",
+        ".bdf",
+        # Images
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".bmp",
+        ".gif",
+        ".svg",
+        ".ico",
+        ".webp",
+        # Certificates
+        ".pem",
+        ".crt",
+        ".key",
+        ".der",
+        ".p12",
+        ".pfx",
+        # C/C++ includes
+        ".h",
+        ".hpp",
+        ".c",
+        ".cpp",
+        ".ino",
+        # Web assets
+        ".css",
+        ".js",
+        ".html",
+    }
+)
+
+
+# Matches !secret references in YAML text.  An optional surrounding
+# quote pair around the key is allowed and ignored: YAML treats
+# ``!secret 'foo'`` and ``!secret foo`` as the same key.  This is
+# intentionally a simple regex scan rather than a YAML parse — it may
+# match inside comments or multi-line strings, which is the conservative
+# direction (include more secrets rather than fewer).
+_SECRET_RE = re.compile(r"""!secret\s+['"]?([^\s'"]+)""")
+
+
+def _find_used_secret_keys(yaml_files: list[Path]) -> set[str]:
+    """Scan YAML files for ``!secret <key>`` references."""
+    keys: set[str] = set()
+    for fpath in yaml_files:
+        try:
+            text = fpath.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for match in _SECRET_RE.finditer(text):
+            keys.add(match.group(1))
+    return keys
+
+
+@dataclass
+class BundleFile:
+    """A file to include in the bundle."""
+
+    path: str  # Relative path inside the archive
+    source: Path  # Absolute path on disk
+
+
+@dataclass
+class BundleResult:
+    """Result of creating a bundle."""
+
+    data: bytes
+    manifest: dict[str, Any]
+    files: list[BundleFile]
+
+
+@dataclass
+class BundleManifest:
+    """Parsed and validated bundle manifest."""
+
+    manifest_version: int
+    esphome_version: str
+    config_filename: str
+    files: list[str]
+    has_secrets: bool
+
+
+class ConfigBundleCreator:
+    """Creates a self-contained bundle from an ESPHome config."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self._config = config
+        self._config_dir = Path(CORE.config_dir).resolve()
+        self._config_path = Path(CORE.config_path).resolve()
+        self._files: list[BundleFile] = []
+        self._seen_paths: set[Path] = set()
+        self._secrets_paths: set[Path] = set()
+
+    def discover_files(self) -> list[BundleFile]:
+        """Discover all files needed for the bundle."""
+        self._files = []
+        self._seen_paths = set()
+        self._secrets_paths = set()
+
+        # The main config file
+        self._add_file(self._config_path)
+
+        # Phase 1: YAML includes (tracked during config loading)
+        self._discover_yaml_includes()
+
+        # Phase 2: Component-referenced files from validated config
+        self._discover_component_files()
+
+        return list(self._files)
+
+    def create_bundle(self) -> BundleResult:
+        """Create the bundle archive."""
+        files = self.discover_files()
+
+        # Determine which secret keys are actually referenced by the
+        # bundled YAML files so we only ship those, not the entire
+        # secrets.yaml which may contain secrets for other devices.
+        yaml_sources = [
+            bf.source for bf in files if bf.source.suffix in (".yaml", ".yml")
+        ]
+        used_secret_keys = _find_used_secret_keys(yaml_sources)
+        filtered_secrets = self._build_filtered_secrets(used_secret_keys)
+
+        has_secrets = bool(filtered_secrets)
+        if has_secrets:
+            _LOGGER.warning(
+                "Bundle contains secrets (e.g. Wi-Fi passwords). "
+                "Do not share it with untrusted parties."
+            )
+
+        manifest = self._build_manifest(files, has_secrets=has_secrets)
+
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+            # Add manifest first
+            manifest_data = json.dumps(manifest, indent=2).encode("utf-8")
+            _add_bytes_to_tar(tar, MANIFEST_FILENAME, manifest_data)
+
+            # Add filtered secrets files
+            for rel_path, data in sorted(filtered_secrets.items()):
+                _add_bytes_to_tar(tar, rel_path, data)
+
+            # Add files in sorted order for determinism, skipping secrets
+            # files which were already added above with filtered content
+            for bf in sorted(files, key=lambda f: f.path):
+                if bf.source in self._secrets_paths:
+                    continue
+                self._add_to_tar(tar, bf)
+
+        return BundleResult(data=buf.getvalue(), manifest=manifest, files=files)
+
+    def _add_file(self, abs_path: Path) -> bool:
+        """Add a file to the bundle. Returns False if already added."""
+        abs_path = abs_path.resolve()
+        if abs_path in self._seen_paths:
+            return False
+        if not abs_path.is_file():
+            _LOGGER.warning("Bundle: skipping missing file %s", abs_path)
+            return False
+
+        rel_path = self._relative_to_config_dir(abs_path)
+        if rel_path is None:
+            _LOGGER.warning(
+                "Bundle: skipping file outside config directory: %s", abs_path
+            )
+            return False
+
+        self._seen_paths.add(abs_path)
+        self._files.append(BundleFile(path=rel_path, source=abs_path))
+        return True
+
+    def _add_directory(self, abs_path: Path) -> None:
+        """Recursively add all files in a directory."""
+        abs_path = abs_path.resolve()
+        if not abs_path.is_dir():
+            _LOGGER.warning("Bundle: skipping missing directory %s", abs_path)
+            return
+        for child in sorted(abs_path.rglob("*")):
+            if child.is_file() and "__pycache__" not in child.parts:
+                self._add_file(child)
+
+    def _relative_to_config_dir(self, abs_path: Path) -> str | None:
+        """Get a path relative to the config directory. Returns None if outside.
+
+        Always uses forward slashes for consistency in tar archives.
+        """
+        try:
+            return abs_path.relative_to(self._config_dir).as_posix()
+        except ValueError:
+            return None
+
+    def _discover_yaml_includes(self) -> None:
+        """Discover YAML files loaded during config parsing.
+
+        Deliberately uses a fresh re-parse and force-loads every deferred
+        ``IncludeFile`` to include *all* potentially-reachable includes,
+        even branches not selected by the local substitutions. Bundles are
+        meant to be compiled on another system where command-line
+        substitution overrides may choose a different branch — e.g.
+        ``!include network/${eth_model}/config.yaml`` must ship every
+        candidate so the remote build can pick any one.
+
+        Entries with unresolved substitution variables in the filename
+        path are skipped with a warning (they cannot be resolved without
+        the substitution pass).
+
+        Secrets files are tracked separately so we can filter them to
+        only include the keys this config actually references.
+        """
+        # Must be a fresh parse: IncludeFile.load() caches its result in
+        # _content, and we discover files by listening for loader calls. On
+        # an already-parsed tree the cache is populated, .load() returns
+        # without calling the loader, the listener never fires, and the
+        # referenced files would be silently dropped from the bundle.
+        with yaml_util.track_yaml_loads() as loaded_files:
+            try:
+                data = yaml_util.load_yaml(self._config_path)
+            except EsphomeError:
+                _LOGGER.debug(
+                    "Bundle: re-loading YAML for include discovery failed, "
+                    "proceeding with partial file list"
+                )
+            else:
+                _force_load_include_files(data)
+
+        for fpath in loaded_files:
+            if fpath == self._config_path.resolve():
+                continue  # Already added as config
+            if fpath.name in const.SECRETS_FILES:
+                self._secrets_paths.add(fpath)
+            self._add_file(fpath)
+
+    def _discover_component_files(self) -> None:
+        """Walk the validated config for file references.
+
+        Uses a generic recursive walk to find file paths instead of
+        hardcoding per-component knowledge about config dict formats.
+        After validation, components typically resolve paths to absolute
+        using CORE.relative_config_path() or cv.file_(). Relative paths
+        with known file extensions are also resolved and checked.
+
+        Core ESPHome concepts that use relative paths or directories
+        are handled explicitly.
+        """
+        config = self._config
+
+        # Generic walk: find all file paths in the validated config
+        self._walk_config_for_files(config)
+
+        # --- Core ESPHome concepts needing explicit handling ---
+
+        # esphome.includes / includes_c - can be relative paths and directories
+        esphome_conf = config.get(CONF_ESPHOME, {})
+        for include_path in esphome_conf.get(CONF_INCLUDES, []):
+            resolved = _resolve_include_path(include_path)
+            if resolved is None:
+                continue
+            if resolved.is_dir():
+                self._add_directory(resolved)
+            else:
+                self._add_file(resolved)
+        for include_path in esphome_conf.get(CONF_INCLUDES_C, []):
+            resolved = _resolve_include_path(include_path)
+            if resolved is not None:
+                self._add_file(resolved)
+
+        # external_components with source: local - directories
+        for ext_conf in config.get(CONF_EXTERNAL_COMPONENTS, []):
+            source = ext_conf.get(CONF_SOURCE, {})
+            if not isinstance(source, dict):
+                continue
+            if source.get(CONF_TYPE) != "local":
+                continue
+            path = source.get(CONF_PATH)
+            if not path:
+                continue
+            p = Path(path)
+            if not p.is_absolute():
+                p = CORE.relative_config_path(p)
+            self._add_directory(p)
+
+    def _walk_config_for_files(self, obj: Any) -> None:
+        """Recursively walk the config dict looking for file path references."""
+        if isinstance(obj, dict):
+            for value in obj.values():
+                self._walk_config_for_files(value)
+        elif isinstance(obj, (list, tuple)):
+            for item in obj:
+                self._walk_config_for_files(item)
+        elif isinstance(obj, Path):
+            if obj.is_absolute() and obj.is_file():
+                self._add_file(obj)
+        elif isinstance(obj, str):
+            self._check_string_path(obj)
+
+    def _check_string_path(self, value: str) -> None:
+        """Check if a string value is a local file reference."""
+        # Fast exits for strings that cannot be file paths
+        if len(value) < 2 or "\n" in value:
+            return
+        if value.startswith(_NON_PATH_PREFIXES):
+            return
+        # File paths must contain a path separator or a dot (for extension)
+        if "/" not in value and "\\" not in value and "." not in value:
+            return
+
+        p = Path(value)
+
+        # Absolute path - check if it points to an existing file
+        if p.is_absolute():
+            if p.is_file():
+                self._add_file(p)
+            return
+
+        # Relative path with a known file extension - likely a component
+        # validator that forgot to resolve to absolute via cv.file_() or
+        # CORE.relative_config_path(). Warn and try to resolve.
+        if p.suffix.lower() in _KNOWN_FILE_EXTENSIONS:
+            _LOGGER.warning(
+                "Bundle: non-absolute path in validated config: %s "
+                "(component validator should return absolute paths)",
+                value,
+            )
+            resolved = CORE.relative_config_path(p)
+            if resolved.is_file():
+                self._add_file(resolved)
+
+    def _build_filtered_secrets(self, used_keys: set[str]) -> dict[str, bytes]:
+        """Build filtered secrets files containing only the referenced keys.
+
+        Returns a dict mapping relative archive path to YAML bytes.
+        """
+        if not used_keys or not self._secrets_paths:
+            return {}
+
+        result: dict[str, bytes] = {}
+        for secrets_path in self._secrets_paths:
+            rel_path = self._relative_to_config_dir(secrets_path)
+            if rel_path is None:
+                continue
+            try:
+                all_secrets = yaml_util.load_yaml(secrets_path, clear_secrets=False)
+            except EsphomeError:
+                _LOGGER.warning("Bundle: failed to load secrets file %s", secrets_path)
+                continue
+            if not isinstance(all_secrets, dict):
+                continue
+            filtered = {k: v for k, v in all_secrets.items() if k in used_keys}
+            if filtered:
+                data = yaml_util.dump(filtered, show_secrets=True).encode("utf-8")
+                result[rel_path] = data
+        return result
+
+    def _build_manifest(
+        self, files: list[BundleFile], *, has_secrets: bool
+    ) -> dict[str, Any]:
+        """Build the manifest.json content."""
+        return {
+            ManifestKey.MANIFEST_VERSION: CURRENT_MANIFEST_VERSION,
+            ManifestKey.ESPHOME_VERSION: const.__version__,
+            ManifestKey.CONFIG_FILENAME: self._config_path.name,
+            ManifestKey.FILES: [f.path for f in files],
+            ManifestKey.HAS_SECRETS: has_secrets,
+        }
+
+    @staticmethod
+    def _add_to_tar(tar: tarfile.TarFile, bf: BundleFile) -> None:
+        """Add a BundleFile to the tar archive with deterministic metadata."""
+        with open(bf.source, "rb") as f:
+            _add_bytes_to_tar(tar, bf.path, f.read())
+
+
+def extract_bundle(
+    bundle_path: Path,
+    target_dir: Path | None = None,
+) -> Path:
+    """Extract a bundle archive and return the path to the config YAML.
+
+    Sanity checks reject path traversal, symlinks, absolute paths, and
+    oversized archives to prevent accidental file overwrites or extraction
+    outside the target directory.  These are **not** a security boundary —
+    bundles are assumed to come from the user's own machine or a trusted
+    build pipeline.
+
+    Args:
+        bundle_path: Path to the .tar.gz bundle file.
+        target_dir: Directory to extract into. If None, extracts next to
+                     the bundle file in a directory named after it.
+
+    Returns:
+        Absolute path to the extracted config YAML file.
+
+    Raises:
+        EsphomeError: If the bundle is invalid or extraction fails.
+    """
+
+    bundle_path = bundle_path.resolve()
+    if not bundle_path.is_file():
+        raise EsphomeError(f"Bundle file not found: {bundle_path}")
+
+    if target_dir is None:
+        target_dir = _default_target_dir(bundle_path)
+
+    target_dir = target_dir.resolve()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Read and validate the archive
+    try:
+        with tarfile.open(bundle_path, "r:gz") as tar:
+            manifest = _read_manifest_from_tar(tar)
+            _validate_tar_members(tar, target_dir)
+            tar.extractall(path=target_dir, filter="data")
+    except tarfile.TarError as err:
+        raise EsphomeError(f"Failed to extract bundle: {err}") from err
+
+    config_filename = manifest[ManifestKey.CONFIG_FILENAME]
+    config_path = target_dir / config_filename
+    if not config_path.is_file():
+        raise EsphomeError(
+            f"Bundle manifest references config '{config_filename}' "
+            f"but it was not found in the archive"
+        )
+
+    return config_path
+
+
+def read_bundle_manifest(bundle_path: Path) -> BundleManifest:
+    """Read and validate the manifest from a bundle without full extraction.
+
+    Args:
+        bundle_path: Path to the .tar.gz bundle file.
+
+    Returns:
+        Parsed BundleManifest.
+
+    Raises:
+        EsphomeError: If the manifest is missing, invalid, or version unsupported.
+    """
+
+    try:
+        with tarfile.open(bundle_path, "r:gz") as tar:
+            manifest = _read_manifest_from_tar(tar)
+    except tarfile.TarError as err:
+        raise EsphomeError(f"Failed to read bundle: {err}") from err
+
+    return BundleManifest(
+        manifest_version=manifest[ManifestKey.MANIFEST_VERSION],
+        esphome_version=manifest.get(ManifestKey.ESPHOME_VERSION, "unknown"),
+        config_filename=manifest[ManifestKey.CONFIG_FILENAME],
+        files=manifest.get(ManifestKey.FILES, []),
+        has_secrets=manifest.get(ManifestKey.HAS_SECRETS, False),
+    )
+
+
+def _read_manifest_from_tar(tar: tarfile.TarFile) -> dict[str, Any]:
+    """Read and validate manifest.json from an open tar archive."""
+
+    try:
+        member = tar.getmember(MANIFEST_FILENAME)
+    except KeyError:
+        raise EsphomeError("Invalid bundle: missing manifest.json") from None
+
+    f = tar.extractfile(member)
+    if f is None:
+        raise EsphomeError("Invalid bundle: manifest.json is not a regular file")
+
+    if member.size > MAX_MANIFEST_SIZE:
+        raise EsphomeError(
+            f"Invalid bundle: manifest.json too large "
+            f"({member.size} bytes, max {MAX_MANIFEST_SIZE})"
+        )
+
+    try:
+        manifest = json.loads(f.read())
+    except (json.JSONDecodeError, UnicodeDecodeError) as err:
+        raise EsphomeError(f"Invalid bundle: malformed manifest.json: {err}") from err
+
+    # Version check
+    version = manifest.get(ManifestKey.MANIFEST_VERSION)
+    if version is None:
+        raise EsphomeError("Invalid bundle: manifest.json missing 'manifest_version'")
+    if not isinstance(version, int) or version < 1:
+        raise EsphomeError(
+            f"Invalid bundle: manifest_version must be a positive integer, got {version!r}"
+        )
+    if version > CURRENT_MANIFEST_VERSION:
+        raise EsphomeError(
+            f"Bundle manifest version {version} is newer than this ESPHome "
+            f"version supports (max {CURRENT_MANIFEST_VERSION}). "
+            f"Please upgrade ESPHome to compile this bundle."
+        )
+
+    # Required fields
+    if ManifestKey.CONFIG_FILENAME not in manifest:
+        raise EsphomeError("Invalid bundle: manifest.json missing 'config_filename'")
+
+    return manifest
+
+
+def _validate_tar_members(tar: tarfile.TarFile, target_dir: Path) -> None:
+    """Sanity-check tar members to prevent mistakes and accidental overwrites.
+
+    This is not a security boundary — bundles are created locally or come
+    from a trusted build pipeline.  The checks catch malformed archives
+    and common mistakes (stray absolute paths, ``..`` components) that
+    could silently overwrite unrelated files.
+    """
+
+    total_size = 0
+    for member in tar.getmembers():
+        # Reject absolute paths (Unix and Windows)
+        if member.name.startswith(("/", "\\")):
+            raise EsphomeError(
+                f"Invalid bundle: absolute path in archive: {member.name}"
+            )
+
+        # Reject path traversal (split on both / and \ for cross-platform)
+        parts = re.split(r"[/\\]", member.name)
+        if ".." in parts:
+            raise EsphomeError(
+                f"Invalid bundle: path traversal in archive: {member.name}"
+            )
+
+        # Reject symlinks
+        if member.issym() or member.islnk():
+            raise EsphomeError(f"Invalid bundle: symlink in archive: {member.name}")
+
+        # Ensure extraction stays within target_dir
+        target_path = (target_dir / member.name).resolve()
+        if not target_path.is_relative_to(target_dir):
+            raise EsphomeError(
+                f"Invalid bundle: file would extract outside target: {member.name}"
+            )
+
+        # Track total decompressed size
+        total_size += member.size
+        if total_size > MAX_DECOMPRESSED_SIZE:
+            raise EsphomeError(
+                f"Invalid bundle: decompressed size exceeds "
+                f"{MAX_DECOMPRESSED_SIZE // (1024 * 1024)}MB limit"
+            )
+
+
+def is_bundle_path(path: Path) -> bool:
+    """Check if a path looks like a bundle file."""
+    return path.name.lower().endswith(BUNDLE_EXTENSION)
+
+
+def _add_bytes_to_tar(tar: tarfile.TarFile, name: str, data: bytes) -> None:
+    """Add in-memory bytes to a tar archive with deterministic metadata."""
+    info = tarfile.TarInfo(name=name)
+    info.size = len(data)
+    info.mtime = 0
+    info.uid = 0
+    info.gid = 0
+    info.mode = 0o644
+    tar.addfile(info, io.BytesIO(data))
+
+
+def _force_load_include_files(obj: Any, _seen: set[int] | None = None) -> None:
+    """Recursively resolve any ``IncludeFile`` instances in a YAML tree.
+
+    Nested ``!include`` returns a deferred ``IncludeFile`` that is only
+    resolved during the substitution pass. During bundle discovery we need
+    the referenced files to actually load so the ``track_yaml_loads``
+    listener fires for them.
+
+    ``IncludeFile`` instances with unresolved substitution variables in the
+    filename cannot be loaded — we skip and warn about those.
+    """
+    if _seen is None:
+        _seen = set()
+
+    if isinstance(obj, yaml_util.IncludeFile):
+        if id(obj) in _seen:
+            return
+        _seen.add(id(obj))
+        if obj.has_unresolved_expressions():
+            _LOGGER.warning(
+                "Bundle: cannot resolve !include %s (referenced from %s) "
+                "with substitutions in path",
+                obj.file,
+                obj.parent_file,
+            )
+            return
+        try:
+            loaded = obj.load()
+        except EsphomeError as err:
+            _LOGGER.warning(
+                "Bundle: failed to load !include %s (referenced from %s): %s",
+                obj.file,
+                obj.parent_file,
+                err,
+            )
+            return
+        _force_load_include_files(loaded, _seen)
+    elif isinstance(obj, dict):
+        if id(obj) in _seen:
+            return
+        _seen.add(id(obj))
+        for value in obj.values():
+            _force_load_include_files(value, _seen)
+    elif isinstance(obj, (list, tuple)):
+        if id(obj) in _seen:
+            return
+        _seen.add(id(obj))
+        for item in obj:
+            _force_load_include_files(item, _seen)
+
+
+def _resolve_include_path(include_path: Any) -> Path | None:
+    """Resolve an include path to absolute, skipping system includes."""
+    if isinstance(include_path, str) and include_path.startswith("<"):
+        return None  # System include, not a local file
+    p = Path(include_path)
+    if not p.is_absolute():
+        p = CORE.relative_config_path(p)
+    return p
+
+
+def _default_target_dir(bundle_path: Path) -> Path:
+    """Compute the default extraction directory for a bundle."""
+    name = bundle_path.name
+    if name.lower().endswith(BUNDLE_EXTENSION):
+        name = name[: -len(BUNDLE_EXTENSION)]
+    return bundle_path.parent / name
+
+
+def _restore_preserved_dirs(preserved: dict[str, Path], target_dir: Path) -> None:
+    """Move preserved build cache directories back into target_dir.
+
+    If the bundle contained entries under a preserved directory name,
+    the extracted copy is removed so the original cache always wins.
+    """
+    for dirname, src in preserved.items():
+        dst = target_dir / dirname
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.move(str(src), str(dst))
+
+
+def prepare_bundle_for_compile(
+    bundle_path: Path,
+    target_dir: Path | None = None,
+) -> Path:
+    """Extract a bundle for compilation, preserving build caches.
+
+    Unlike extract_bundle(), this preserves .esphome/ and .pioenvs/
+    directories in the target if they already exist (for incremental builds).
+
+    Args:
+        bundle_path: Path to the .tar.gz bundle file.
+        target_dir: Directory to extract into. Must be specified for
+                     build server use.
+
+    Returns:
+        Absolute path to the extracted config YAML file.
+    """
+
+    bundle_path = bundle_path.resolve()
+    if not bundle_path.is_file():
+        raise EsphomeError(f"Bundle file not found: {bundle_path}")
+
+    if target_dir is None:
+        target_dir = _default_target_dir(bundle_path)
+
+    target_dir = target_dir.resolve()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    preserved: dict[str, Path] = {}
+
+    # Temporarily move preserved dirs out of the way
+    staging = target_dir / _BUNDLE_STAGING_DIR
+    for dirname in _PRESERVE_DIRS:
+        src = target_dir / dirname
+        if src.is_dir():
+            dst = staging / dirname
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(src), str(dst))
+            preserved[dirname] = dst
+
+    try:
+        # Clean non-preserved content and extract fresh
+        for item in target_dir.iterdir():
+            if item.name == _BUNDLE_STAGING_DIR:
+                continue
+            if item.is_dir():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+
+        config_path = extract_bundle(bundle_path, target_dir)
+    finally:
+        # Restore preserved dirs (idempotent) and clean staging
+        _restore_preserved_dirs(preserved, target_dir)
+        if staging.is_dir():
+            shutil.rmtree(staging)
+
+    return config_path

esphome/codegen.py

@@ -11,6 +11,7 @@
 from esphome.cpp_generator import (  # noqa: F401
     ArrayInitializer,
     Expression,
+    FlashStringLiteral,
     LineComment,
     LogStringLiteral,
     MockObj,
@@ -62,12 +63,14 @@ from esphome.cpp_types import (  # noqa: F401
     EntityBase,
     EntityCategory,
     ESPTime,
+    FixedVector,
     GPIOPin,
     InternalGPIOPin,
     JsonObject,
     JsonObjectConst,
     Parented,
     PollingComponent,
+    StringRef,
     arduino_json_ns,
     bool_,
     const_char_ptr,
@@ -76,6 +79,7 @@ from esphome.cpp_types import (  # noqa: F401
     float_,
     global_ns,
     gpio_Flags,
+    int8,
     int16,
     int32,
     int64,
@@ -85,6 +89,7 @@ from esphome.cpp_types import (  # noqa: F401
     size_t,
     std_ns,
     std_shared_ptr,
+    std_span,
     std_string,
     std_string_ref,
     std_vector,

esphome/components/a01nyub/a01nyub.cpp

@@ -4,8 +4,7 @@
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace a01nyub {
+namespace esphome::a01nyub {
 
 static const char *const TAG = "a01nyub.sensor";
 
@@ -30,7 +29,9 @@ void A01nyubComponent::check_buffer_() {
       ESP_LOGV(TAG, "Distance from sensor: %f mm, %f m", distance, meters);
       this->publish_state(meters);
     } else {
-      ESP_LOGW(TAG, "Invalid data read from sensor: %s", format_hex_pretty(this->buffer_).c_str());
+      char hex_buf[format_hex_pretty_size(4)];
+      ESP_LOGW(TAG, "Invalid data read from sensor: %s",
+               format_hex_pretty_to(hex_buf, this->buffer_.data(), this->buffer_.size()));
     }
   } else {
     ESP_LOGW(TAG, "checksum failed: %02x != %02x", checksum, this->buffer_[3]);
@@ -40,5 +41,4 @@ void A01nyubComponent::check_buffer_() {
 
 void A01nyubComponent::dump_config() { LOG_SENSOR("", "A01nyub Sensor", this); }
 
-}  // namespace a01nyub
-}  // namespace esphome
+}  // namespace esphome::a01nyub

esphome/components/a01nyub/a01nyub.h

@@ -6,8 +6,7 @@
 #include "esphome/components/sensor/sensor.h"
 #include "esphome/components/uart/uart.h"
 
-namespace esphome {
-namespace a01nyub {
+namespace esphome::a01nyub {
 
 class A01nyubComponent : public sensor::Sensor, public Component, public uart::UARTDevice {
  public:
@@ -23,5 +22,4 @@ class A01nyubComponent : public sensor::Sensor, public Component, public uart::U
   std::vector<uint8_t> buffer_;
 };
 
-}  // namespace a01nyub
-}  // namespace esphome
+}  // namespace esphome::a01nyub

esphome/components/a02yyuw/a02yyuw.cpp

@@ -4,8 +4,7 @@
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace a02yyuw {
+namespace esphome::a02yyuw {
 
 static const char *const TAG = "a02yyuw.sensor";
 
@@ -29,7 +28,9 @@ void A02yyuwComponent::check_buffer_() {
       ESP_LOGV(TAG, "Distance from sensor: %f mm", distance);
       this->publish_state(distance);
     } else {
-      ESP_LOGW(TAG, "Invalid data read from sensor: %s", format_hex_pretty(this->buffer_).c_str());
+      char hex_buf[format_hex_pretty_size(4)];
+      ESP_LOGW(TAG, "Invalid data read from sensor: %s",
+               format_hex_pretty_to(hex_buf, this->buffer_.data(), this->buffer_.size()));
     }
   } else {
     ESP_LOGW(TAG, "checksum failed: %02x != %02x", checksum, this->buffer_[3]);
@@ -39,5 +40,4 @@ void A02yyuwComponent::check_buffer_() {
 
 void A02yyuwComponent::dump_config() { LOG_SENSOR("", "A02yyuw Sensor", this); }
 
-}  // namespace a02yyuw
-}  // namespace esphome
+}  // namespace esphome::a02yyuw

esphome/components/a02yyuw/a02yyuw.h

@@ -6,8 +6,7 @@
 #include "esphome/components/sensor/sensor.h"
 #include "esphome/components/uart/uart.h"
 
-namespace esphome {
-namespace a02yyuw {
+namespace esphome::a02yyuw {
 
 class A02yyuwComponent : public sensor::Sensor, public Component, public uart::UARTDevice {
  public:
@@ -23,5 +22,4 @@ class A02yyuwComponent : public sensor::Sensor, public Component, public uart::U
   std::vector<uint8_t> buffer_;
 };
 
-}  // namespace a02yyuw
-}  // namespace esphome
+}  // namespace esphome::a02yyuw

esphome/components/a4988/a4988.cpp

@@ -1,8 +1,7 @@
 #include "a4988.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace a4988 {
+namespace esphome::a4988 {
 
 static const char *const TAG = "a4988.stepper";
 
@@ -51,5 +50,4 @@ void A4988::loop() {
   this->step_pin_->digital_write(false);
 }
 
-}  // namespace a4988
-}  // namespace esphome
+}  // namespace esphome::a4988

esphome/components/a4988/a4988.h

@@ -4,8 +4,7 @@
 #include "esphome/core/hal.h"
 #include "esphome/components/stepper/stepper.h"
 
-namespace esphome {
-namespace a4988 {
+namespace esphome::a4988 {
 
 class A4988 : public stepper::Stepper, public Component {
  public:
@@ -25,5 +24,4 @@ class A4988 : public stepper::Stepper, public Component {
   HighFrequencyLoopRequester high_freq_;
 };
 
-}  // namespace a4988
-}  // namespace esphome
+}  // namespace esphome::a4988

esphome/components/absolute_humidity/absolute_humidity.cpp

@@ -1,22 +1,29 @@
 #include "esphome/core/log.h"
 #include "absolute_humidity.h"
 
-namespace esphome {
-namespace absolute_humidity {
+namespace esphome::absolute_humidity {
 
-static const char *const TAG = "absolute_humidity.sensor";
+static const char *const TAG{"absolute_humidity.sensor"};
 
 void AbsoluteHumidityComponent::setup() {
+  this->temperature_sensor_->add_on_state_callback([this](float state) {
+    this->temperature_ = state;
+    this->enable_loop();
+  });
   ESP_LOGD(TAG, "  Added callback for temperature '%s'", this->temperature_sensor_->get_name().c_str());
-  this->temperature_sensor_->add_on_state_callback([this](float state) { this->temperature_callback_(state); });
+  // Get initial value
   if (this->temperature_sensor_->has_state()) {
-    this->temperature_callback_(this->temperature_sensor_->get_state());
+    this->temperature_ = this->temperature_sensor_->get_state();
   }
 
+  this->humidity_sensor_->add_on_state_callback([this](float state) {
+    this->humidity_ = state;
+    this->enable_loop();
+  });
   ESP_LOGD(TAG, "  Added callback for relative humidity '%s'", this->humidity_sensor_->get_name().c_str());
-  this->humidity_sensor_->add_on_state_callback([this](float state) { this->humidity_callback_(state); });
+  // Get initial value
   if (this->humidity_sensor_->has_state()) {
-    this->humidity_callback_(this->humidity_sensor_->get_state());
+    this->humidity_ = this->humidity_sensor_->get_state();
   }
 }
 
@@ -45,17 +52,13 @@ void AbsoluteHumidityComponent::dump_config() {
                 this->temperature_sensor_->get_name().c_str(), this->humidity_sensor_->get_name().c_str());
 }
 
-float AbsoluteHumidityComponent::get_setup_priority() const { return setup_priority::DATA; }
-
 void AbsoluteHumidityComponent::loop() {
-  if (!this->next_update_) {
-    return;
-  }
-  this->next_update_ = false;
+  // Only run once
+  this->disable_loop();
 
   // Ensure we have source data
-  const bool no_temperature = std::isnan(this->temperature_);
-  const bool no_humidity = std::isnan(this->humidity_);
+  const bool no_temperature{std::isnan(this->temperature_)};
+  const bool no_humidity{std::isnan(this->humidity_)};
   if (no_temperature || no_humidity) {
     if (no_temperature) {
       ESP_LOGW(TAG, "No valid state from temperature sensor!");
@@ -69,9 +72,9 @@ void AbsoluteHumidityComponent::loop() {
   }
 
   // Convert to desired units
-  const float temperature_c = this->temperature_;
-  const float temperature_k = temperature_c + 273.15;
-  const float hr = this->humidity_ / 100;
+  const float temperature_c{this->temperature_};
+  const float temperature_k{temperature_c + 273.15f};
+  const float hr{this->humidity_ / 100.0f};
 
   // Calculate saturation vapor pressure
   float es;
@@ -87,16 +90,16 @@ void AbsoluteHumidityComponent::loop() {
       break;
     default:
       this->publish_state(NAN);
-      this->status_set_error("Invalid saturation vapor pressure equation selection!");
+      this->status_set_error(LOG_STR("Invalid saturation vapor pressure equation selection!"));
       return;
   }
-  ESP_LOGD(TAG, "Saturation vapor pressure %f kPa", es);
 
   // Calculate absolute humidity
-  const float absolute_humidity = vapor_density(es, hr, temperature_k);
+  const float absolute_humidity{vapor_density(es, hr, temperature_k)};
+
+  ESP_LOGD(TAG, "Saturation vapor pressure %f kPa, absolute humidity %f g/m³", es, absolute_humidity);
 
   // Publish absolute humidity
-  ESP_LOGD(TAG, "Publishing absolute humidity %f g/m³", absolute_humidity);
   this->status_clear_warning();
   this->publish_state(absolute_humidity);
 }
@@ -105,16 +108,16 @@ void AbsoluteHumidityComponent::loop() {
 // More accurate than Tetens in normal meteorologic conditions
 float AbsoluteHumidityComponent::es_buck(float temperature_c) {
   float a, b, c, d;
-  if (temperature_c >= 0) {
-    a = 0.61121;
-    b = 18.678;
-    c = 234.5;
-    d = 257.14;
+  if (temperature_c >= 0.0f) {
+    a = 0.61121f;
+    b = 18.678f;
+    c = 234.5f;
+    d = 257.14f;
   } else {
-    a = 0.61115;
-    b = 18.678;
-    c = 233.7;
-    d = 279.82;
+    a = 0.61115f;
+    b = 18.678f;
+    c = 233.7f;
+    d = 279.82f;
   }
   return a * expf((b - (temperature_c / c)) * (temperature_c / (d + temperature_c)));
 }
@@ -122,14 +125,14 @@ float AbsoluteHumidityComponent::es_buck(float temperature_c) {
 // Tetens equation (https://en.wikipedia.org/wiki/Tetens_equation)
 float AbsoluteHumidityComponent::es_tetens(float temperature_c) {
   float a, b;
-  if (temperature_c >= 0) {
-    a = 17.27;
-    b = 237.3;
+  if (temperature_c >= 0.0f) {
+    a = 17.27f;
+    b = 237.3f;
   } else {
-    a = 21.875;
-    b = 265.5;
+    a = 21.875f;
+    b = 265.5f;
   }
-  return 0.61078 * expf((a * temperature_c) / (temperature_c + b));
+  return 0.61078f * expf((a * temperature_c) / (temperature_c + b));
 }
 
 // Wobus equation
@@ -148,33 +151,32 @@ float AbsoluteHumidityComponent::es_wobus(float t) {
   //
   //     Baker, Schlatter  17-MAY-1982     Original version.
 
-  const float c0 = +0.99999683e00;
-  const float c1 = -0.90826951e-02;
-  const float c2 = +0.78736169e-04;
-  const float c3 = -0.61117958e-06;
-  const float c4 = +0.43884187e-08;
-  const float c5 = -0.29883885e-10;
-  const float c6 = +0.21874425e-12;
-  const float c7 = -0.17892321e-14;
-  const float c8 = +0.11112018e-16;
-  const float c9 = -0.30994571e-19;
-  const float p = c0 + t * (c1 + t * (c2 + t * (c3 + t * (c4 + t * (c5 + t * (c6 + t * (c7 + t * (c8 + t * (c9)))))))));
-  return 0.61078 / pow(p, 8);
+  constexpr float c0{+0.99999683e+00f};
+  constexpr float c1{-0.90826951e-02f};
+  constexpr float c2{+0.78736169e-04f};
+  constexpr float c3{-0.61117958e-06f};
+  constexpr float c4{+0.43884187e-08f};
+  constexpr float c5{-0.29883885e-10f};
+  constexpr float c6{+0.21874425e-12f};
+  constexpr float c7{-0.17892321e-14f};
+  constexpr float c8{+0.11112018e-16f};
+  constexpr float c9{-0.30994571e-19f};
+  const float p{c0 + t * (c1 + t * (c2 + t * (c3 + t * (c4 + t * (c5 + t * (c6 + t * (c7 + t * (c8 + t * (c9)))))))))};
+  return 0.61078f / powf(p, 8.0f);
 }
 
 // From https://www.environmentalbiophysics.org/chalk-talk-how-to-calculate-absolute-humidity/
-// H/T to https://esphome.io/cookbook/bme280_environment.html
+// H/T to https://esphome.io/cookbook/bme280_environment/
 // H/T to https://carnotcycle.wordpress.com/2012/08/04/how-to-convert-relative-humidity-to-absolute-humidity/
 float AbsoluteHumidityComponent::vapor_density(float es, float hr, float ta) {
   // es = saturated vapor pressure (kPa)
   // hr = relative humidity [0-1]
   // ta = absolute temperature (K)
 
-  const float ea = hr * es * 1000;   // vapor pressure of the air (Pa)
-  const float mw = 18.01528;         // molar mass of water (g⋅mol⁻¹)
-  const float r = 8.31446261815324;  // molar gas constant (J⋅K⁻¹)
+  const float ea{hr * es * 1000.0f};  // vapor pressure of the air (Pa)
+  const float mw{18.01528f};          // molar mass of water (g⋅mol⁻¹)
+  const float r{8.31446261815324f};   // molar gas constant (J⋅K⁻¹)
   return (ea * mw) / (r * ta);
 }
 
-}  // namespace absolute_humidity
-}  // namespace esphome
+}  // namespace esphome::absolute_humidity

esphome/components/absolute_humidity/absolute_humidity.h

@@ -3,8 +3,7 @@
 #include "esphome/core/component.h"
 #include "esphome/components/sensor/sensor.h"
 
-namespace esphome {
-namespace absolute_humidity {
+namespace esphome::absolute_humidity {
 
 /// Enum listing all implemented saturation vapor pressure equations.
 enum SaturationVaporPressureEquation {
@@ -16,27 +15,15 @@ enum SaturationVaporPressureEquation {
 /// This class implements calculation of absolute humidity from temperature and relative humidity.
 class AbsoluteHumidityComponent : public sensor::Sensor, public Component {
  public:
-  AbsoluteHumidityComponent() = default;
-
   void set_temperature_sensor(sensor::Sensor *temperature_sensor) { this->temperature_sensor_ = temperature_sensor; }
   void set_humidity_sensor(sensor::Sensor *humidity_sensor) { this->humidity_sensor_ = humidity_sensor; }
   void set_equation(SaturationVaporPressureEquation equation) { this->equation_ = equation; }
 
   void setup() override;
   void dump_config() override;
-  float get_setup_priority() const override;
   void loop() override;
 
  protected:
-  void temperature_callback_(float state) {
-    this->next_update_ = true;
-    this->temperature_ = state;
-  }
-  void humidity_callback_(float state) {
-    this->next_update_ = true;
-    this->humidity_ = state;
-  }
-
   /** Buck equation for saturation vapor pressure in kPa.
    *
    * @param temperature_c Air temperature in °C.
@@ -58,19 +45,15 @@ class AbsoluteHumidityComponent : public sensor::Sensor, public Component {
    * @param es Saturation vapor pressure in kPa.
    * @param hr Relative humidity 0 to 1.
    * @param ta Absolute temperature in K.
-   * @param heater_duration The duration in ms that the heater should turn on for when measuring.
    */
   static float vapor_density(float es, float hr, float ta);
 
   sensor::Sensor *temperature_sensor_{nullptr};
   sensor::Sensor *humidity_sensor_{nullptr};
 
-  bool next_update_{false};
-
   float temperature_{NAN};
   float humidity_{NAN};
   SaturationVaporPressureEquation equation_;
 };
 
-}  // namespace absolute_humidity
-}  // namespace esphome
+}  // namespace esphome::absolute_humidity

esphome/components/ac_dimmer/ac_dimmer.cpp

@@ -1,5 +1,3 @@
-#ifdef USE_ARDUINO
-
 #include "ac_dimmer.h"
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
@@ -9,12 +7,12 @@
 #ifdef USE_ESP8266
 #include <core_esp8266_waveform.h>
 #endif
-#ifdef USE_ESP32_FRAMEWORK_ARDUINO
-#include <esp32-hal-timer.h>
+
+#ifdef USE_ESP32
+#include "hw_timer_esp_idf.h"
 #endif
 
-namespace esphome {
-namespace ac_dimmer {
+namespace esphome::ac_dimmer {
 
 static const char *const TAG = "ac_dimmer";
 
@@ -27,7 +25,14 @@ static AcDimmerDataStore *all_dimmers[32];  // NOLINT(cppcoreguidelines-avoid-no
 /// However other factors like gate driver propagation time
 /// are also considered and a really low value is not important
 /// See also: https://github.com/esphome/issues/issues/1632
-static const uint32_t GATE_ENABLE_TIME = 50;
+static constexpr uint32_t GATE_ENABLE_TIME = 50;
+
+#ifdef USE_ESP32
+/// Timer frequency in Hz (1 MHz = 1µs resolution)
+static constexpr uint32_t TIMER_FREQUENCY_HZ = 1000000;
+/// Timer interrupt interval in microseconds
+static constexpr uint64_t TIMER_INTERVAL_US = 50;
+#endif
 
 /// Function called from timer interrupt
 /// Input is current time in microseconds (micros())
@@ -154,7 +159,7 @@ void IRAM_ATTR HOT AcDimmerDataStore::s_gpio_intr(AcDimmerDataStore *store) {
 #ifdef USE_ESP32
 // ESP32 implementation, uses basically the same code but needs to wrap
 // timer_interrupt() function to auto-reschedule
-static hw_timer_t *dimmer_timer = nullptr;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
+static HWTimer *dimmer_timer = nullptr;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 void IRAM_ATTR HOT AcDimmerDataStore::s_timer_intr() { timer_interrupt(); }
 #endif
 
@@ -185,7 +190,7 @@ void AcDimmer::setup() {
     this->zero_cross_pin_->setup();
     this->store_.zero_cross_pin = this->zero_cross_pin_->to_isr();
     this->zero_cross_pin_->attach_interrupt(&AcDimmerDataStore::s_gpio_intr, &this->store_,
-                                            gpio::INTERRUPT_FALLING_EDGE);
+                                            this->zero_cross_interrupt_type_);
   }
 
 #ifdef USE_ESP8266
@@ -194,15 +199,22 @@ void AcDimmer::setup() {
   setTimer1Callback(&timer_interrupt);
 #endif
 #ifdef USE_ESP32
-  // timer frequency of 1mhz
-  dimmer_timer = timerBegin(1000000);
-  timerAttachInterrupt(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.
-  timerAlarm(dimmer_timer, 50, 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
 }
+
 void AcDimmer::write_state(float state) {
   state = std::acos(1 - (2 * state)) / std::numbers::pi;  // RMS power compensation
   auto new_value = static_cast<uint16_t>(roundf(state * 65535));
@@ -210,27 +222,31 @@ void AcDimmer::write_state(float state) {
     this->store_.init_cycle = this->init_with_half_cycle_;
   this->store_.value = new_value;
 }
+
 void AcDimmer::dump_config() {
-  ESP_LOGCONFIG(TAG, "AcDimmer:");
+  ESP_LOGCONFIG(TAG,
+                "AcDimmer:\n"
+                "  Min Power: %.1f%%\n"
+                "  Init with half cycle: %s",
+                this->store_.min_power / 10.0f, YESNO(this->init_with_half_cycle_));
   LOG_PIN("  Output Pin: ", this->gate_pin_);
   LOG_PIN("  Zero-Cross Pin: ", this->zero_cross_pin_);
-  ESP_LOGCONFIG(TAG,
-                "   Min Power: %.1f%%\n"
-                "   Init with half cycle: %s",
-                this->store_.min_power / 10.0f, YESNO(this->init_with_half_cycle_));
-  if (method_ == DIM_METHOD_LEADING_PULSE) {
-    ESP_LOGCONFIG(TAG, "   Method: leading pulse");
-  } else if (method_ == DIM_METHOD_LEADING) {
-    ESP_LOGCONFIG(TAG, "   Method: leading");
+  if (this->zero_cross_interrupt_type_ == gpio::INTERRUPT_RISING_EDGE) {
+    ESP_LOGCONFIG(TAG, "  Interrupt Type: rising");
+  } else if (this->zero_cross_interrupt_type_ == gpio::INTERRUPT_FALLING_EDGE) {
+    ESP_LOGCONFIG(TAG, "  Interrupt Type: falling");
   } else {
-    ESP_LOGCONFIG(TAG, "   Method: trailing");
+    ESP_LOGCONFIG(TAG, "  Interrupt Type: any");
+  }
+  if (method_ == DIM_METHOD_LEADING_PULSE) {
+    ESP_LOGCONFIG(TAG, "  Method: leading pulse");
+  } else if (method_ == DIM_METHOD_LEADING) {
+    ESP_LOGCONFIG(TAG, "  Method: leading");
+  } else {
+    ESP_LOGCONFIG(TAG, "  Method: trailing");
   }
-
   LOG_FLOAT_OUTPUT(this);
   ESP_LOGV(TAG, "  Estimated Frequency: %.3fHz", 1e6f / this->store_.cycle_time_us / 2);
 }
 
-}  // namespace ac_dimmer
-}  // namespace esphome
-
-#endif  // USE_ARDUINO
+}  // namespace esphome::ac_dimmer

esphome/components/ac_dimmer/ac_dimmer.h

@@ -1,13 +1,10 @@
 #pragma once
 
-#ifdef USE_ARDUINO
-
 #include "esphome/core/component.h"
 #include "esphome/core/hal.h"
 #include "esphome/components/output/float_output.h"
 
-namespace esphome {
-namespace ac_dimmer {
+namespace esphome::ac_dimmer {
 
 enum DimMethod { DIM_METHOD_LEADING_PULSE = 0, DIM_METHOD_LEADING, DIM_METHOD_TRAILING };
 
@@ -51,6 +48,7 @@ class AcDimmer : public output::FloatOutput, public Component {
   void dump_config() override;
   void set_gate_pin(InternalGPIOPin *gate_pin) { gate_pin_ = gate_pin; }
   void set_zero_cross_pin(InternalGPIOPin *zero_cross_pin) { zero_cross_pin_ = zero_cross_pin; }
+  void set_zero_cross_interrupt_type(gpio::InterruptType type) { zero_cross_interrupt_type_ = type; }
   void set_init_with_half_cycle(bool init_with_half_cycle) { init_with_half_cycle_ = init_with_half_cycle; }
   void set_method(DimMethod method) { method_ = method; }
 
@@ -59,12 +57,10 @@ class AcDimmer : public output::FloatOutput, public Component {
 
   InternalGPIOPin *gate_pin_;
   InternalGPIOPin *zero_cross_pin_;
+  gpio::InterruptType zero_cross_interrupt_type_;
   AcDimmerDataStore store_;
   bool init_with_half_cycle_;
   DimMethod method_;
 };
 
-}  // namespace ac_dimmer
-}  // namespace esphome
-
-#endif  // USE_ARDUINO
+}  // namespace esphome::ac_dimmer

esphome/components/ac_dimmer/hw_timer_esp_idf.cpp

@@ -0,0 +1,152 @@
+#ifdef USE_ESP32
+
+#include "hw_timer_esp_idf.h"
+
+#include "freertos/FreeRTOS.h"
+#include "esphome/core/log.h"
+
+#include "driver/gptimer.h"
+#include "esp_clk_tree.h"
+#include "soc/clk_tree_defs.h"
+
+static const char *const TAG = "hw_timer_esp_idf";
+
+namespace esphome::ac_dimmer {
+
+// GPTimer divider constraints from ESP-IDF documentation
+static constexpr uint32_t GPTIMER_DIVIDER_MIN = 2;
+static constexpr uint32_t GPTIMER_DIVIDER_MAX = 65536;
+
+using voidFuncPtr = void (*)();
+using voidFuncPtrArg = void (*)(void *);
+
+struct InterruptConfigT {
+  voidFuncPtr fn{nullptr};
+  void *arg{nullptr};
+};
+
+struct HWTimer {
+  gptimer_handle_t timer_handle{nullptr};
+  InterruptConfigT interrupt_handle{};
+  bool timer_started{false};
+};
+
+HWTimer *timer_begin(uint32_t frequency) {
+  esp_err_t err = ESP_OK;
+  uint32_t counter_src_hz = 0;
+  uint32_t divider = 0;
+  soc_module_clk_t clk;
+  for (auto clk_candidate : SOC_GPTIMER_CLKS) {
+    clk = clk_candidate;
+    esp_clk_tree_src_get_freq_hz(clk, ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED, &counter_src_hz);
+    divider = counter_src_hz / frequency;
+    if ((divider >= GPTIMER_DIVIDER_MIN) && (divider <= GPTIMER_DIVIDER_MAX)) {
+      break;
+    } else {
+      divider = 0;
+    }
+  }
+
+  if (divider == 0) {
+    ESP_LOGE(TAG, "Resolution not possible; aborting");
+    return nullptr;
+  }
+
+  gptimer_config_t config = {
+      .clk_src = static_cast<gptimer_clock_source_t>(clk),
+      .direction = GPTIMER_COUNT_UP,
+      .resolution_hz = frequency,
+      .flags = {.intr_shared = true},
+  };
+
+  HWTimer *timer = new HWTimer();
+
+  err = gptimer_new_timer(&config, &timer->timer_handle);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "GPTimer creation failed; error %d", err);
+    delete timer;
+    return nullptr;
+  }
+
+  err = gptimer_enable(timer->timer_handle);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "GPTimer enable failed; error %d", err);
+    gptimer_del_timer(timer->timer_handle);
+    delete timer;
+    return nullptr;
+  }
+
+  err = gptimer_start(timer->timer_handle);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "GPTimer start failed; error %d", err);
+    gptimer_disable(timer->timer_handle);
+    gptimer_del_timer(timer->timer_handle);
+    delete timer;
+    return nullptr;
+  }
+
+  timer->timer_started = true;
+  return timer;
+}
+
+bool IRAM_ATTR timer_fn_wrapper(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *args) {
+  auto *isr = static_cast<InterruptConfigT *>(args);
+  if (isr->fn) {
+    if (isr->arg) {
+      reinterpret_cast<voidFuncPtrArg>(isr->fn)(isr->arg);
+    } else {
+      isr->fn();
+    }
+  }
+  // Return false to indicate that no higher-priority task was woken and no context switch is requested.
+  return false;
+}
+
+static void timer_attach_interrupt_functional_arg(HWTimer *timer, void (*user_func)(void *), void *arg) {
+  if (timer == nullptr) {
+    ESP_LOGE(TAG, "Timer handle is nullptr");
+    return;
+  }
+  gptimer_event_callbacks_t cbs = {
+      .on_alarm = timer_fn_wrapper,
+  };
+
+  timer->interrupt_handle.fn = reinterpret_cast<voidFuncPtr>(user_func);
+  timer->interrupt_handle.arg = arg;
+
+  if (timer->timer_started) {
+    gptimer_stop(timer->timer_handle);
+  }
+  gptimer_disable(timer->timer_handle);
+  esp_err_t err = gptimer_register_event_callbacks(timer->timer_handle, &cbs, &timer->interrupt_handle);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Timer Attach Interrupt failed; error %d", err);
+  }
+  gptimer_enable(timer->timer_handle);
+  if (timer->timer_started) {
+    gptimer_start(timer->timer_handle);
+  }
+}
+
+void timer_attach_interrupt(HWTimer *timer, voidFuncPtr user_func) {
+  timer_attach_interrupt_functional_arg(timer, reinterpret_cast<voidFuncPtrArg>(user_func), nullptr);
+}
+
+void timer_alarm(HWTimer *timer, uint64_t alarm_value, bool autoreload, uint64_t reload_count) {
+  if (timer == nullptr) {
+    ESP_LOGE(TAG, "Timer handle is nullptr");
+    return;
+  }
+  gptimer_alarm_config_t alarm_cfg = {
+      .alarm_count = alarm_value,
+      .reload_count = reload_count,
+      .flags = {.auto_reload_on_alarm = autoreload},
+  };
+  esp_err_t err = gptimer_set_alarm_action(timer->timer_handle, &alarm_cfg);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Timer Alarm Write failed; error %d", err);
+  }
+}
+
+}  // namespace esphome::ac_dimmer
+#endif

esphome/components/ac_dimmer/hw_timer_esp_idf.h

@@ -0,0 +1,17 @@
+#pragma once
+#ifdef USE_ESP32
+
+#include "driver/gptimer_types.h"
+
+namespace esphome::ac_dimmer {
+
+struct HWTimer;
+
+HWTimer *timer_begin(uint32_t frequency);
+
+void timer_attach_interrupt(HWTimer *timer, void (*user_func)());
+void timer_alarm(HWTimer *timer, uint64_t alarm_value, bool autoreload, uint64_t reload_count);
+
+}  // namespace esphome::ac_dimmer
+
+#endif

esphome/components/ac_dimmer/output.py

@@ -3,9 +3,12 @@ import esphome.codegen as cg
 from esphome.components import output
 import esphome.config_validation as cv
 from esphome.const import CONF_ID, CONF_METHOD, CONF_MIN_POWER
+from esphome.core import CORE
 
 CODEOWNERS = ["@glmnet"]
 
+gpio_ns = cg.esphome_ns.namespace("gpio")
+
 ac_dimmer_ns = cg.esphome_ns.namespace("ac_dimmer")
 AcDimmer = ac_dimmer_ns.class_("AcDimmer", output.FloatOutput, cg.Component)
 
@@ -16,26 +19,42 @@ DIM_METHODS = {
     "TRAILING": DimMethod.DIM_METHOD_TRAILING,
 }
 
+ZC_INTERRUPT_TYPES = {
+    "RISING": gpio_ns.INTERRUPT_RISING_EDGE,
+    "FALLING": gpio_ns.INTERRUPT_FALLING_EDGE,
+    "ANY": gpio_ns.INTERRUPT_ANY_EDGE,
+}
+
 CONF_GATE_PIN = "gate_pin"
 CONF_ZERO_CROSS_PIN = "zero_cross_pin"
 CONF_INIT_WITH_HALF_CYCLE = "init_with_half_cycle"
+CONF_ZERO_CROSS_INTERRUPT_TYPE = "zero_cross_interrupt_type"
+
 CONFIG_SCHEMA = cv.All(
     output.FLOAT_OUTPUT_SCHEMA.extend(
         {
             cv.Required(CONF_ID): cv.declare_id(AcDimmer),
             cv.Required(CONF_GATE_PIN): pins.internal_gpio_output_pin_schema,
             cv.Required(CONF_ZERO_CROSS_PIN): pins.internal_gpio_input_pin_schema,
+            cv.Optional(CONF_ZERO_CROSS_INTERRUPT_TYPE, default="FALLING"): cv.enum(
+                ZC_INTERRUPT_TYPES, upper=True, space="_"
+            ),
             cv.Optional(CONF_INIT_WITH_HALF_CYCLE, default=True): cv.boolean,
             cv.Optional(CONF_METHOD, default="leading pulse"): cv.enum(
                 DIM_METHODS, upper=True, space="_"
             ),
         }
     ).extend(cv.COMPONENT_SCHEMA),
-    cv.only_with_arduino,
 )
 
 
 async def to_code(config):
+    if CORE.is_esp8266:
+        # ac_dimmer uses setTimer1Callback which requires the waveform generator
+        from esphome.components.esp8266.const import require_waveform
+
+        require_waveform()
+
     var = cg.new_Pvariable(config[CONF_ID])
     await cg.register_component(var, config)
 
@@ -48,5 +67,6 @@ async def to_code(config):
     cg.add(var.set_gate_pin(pin))
     pin = await cg.gpio_pin_expression(config[CONF_ZERO_CROSS_PIN])
     cg.add(var.set_zero_cross_pin(pin))
+    cg.add(var.set_zero_cross_interrupt_type(config[CONF_ZERO_CROSS_INTERRUPT_TYPE]))
     cg.add(var.set_init_with_half_cycle(config[CONF_INIT_WITH_HALF_CYCLE]))
     cg.add(var.set_method(config[CONF_METHOD]))

esphome/components/adalight/adalight_light_effect.cpp

@@ -1,15 +1,14 @@
 #include "adalight_light_effect.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace adalight {
+namespace esphome::adalight {
 
 static const char *const TAG = "adalight_light_effect";
 
 static const uint32_t ADALIGHT_ACK_INTERVAL = 1000;
 static const uint32_t ADALIGHT_RECEIVE_TIMEOUT = 1000;
 
-AdalightLightEffect::AdalightLightEffect(const std::string &name) : AddressableLightEffect(name) {}
+AdalightLightEffect::AdalightLightEffect(const char *name) : AddressableLightEffect(name) {}
 
 void AdalightLightEffect::start() {
   AddressableLightEffect::start();
@@ -129,7 +128,7 @@ AdalightLightEffect::Frame AdalightLightEffect::parse_frame_(light::AddressableL
   uint8_t *led_data = &frame_[6];
 
   for (int led = 0; led < accepted_led_count; led++, led_data += 3) {
-    auto white = std::min(std::min(led_data[0], led_data[1]), led_data[2]);
+    auto white = std::min({led_data[0], led_data[1], led_data[2]});
 
     it[led].set(Color(led_data[0], led_data[1], led_data[2], white));
   }
@@ -138,5 +137,4 @@ AdalightLightEffect::Frame AdalightLightEffect::parse_frame_(light::AddressableL
   return CONSUMED;
 }
 
-}  // namespace adalight
-}  // namespace esphome
+}  // namespace esphome::adalight

esphome/components/adalight/adalight_light_effect.h

@@ -6,12 +6,11 @@
 
 #include <vector>
 
-namespace esphome {
-namespace adalight {
+namespace esphome::adalight {
 
 class AdalightLightEffect : public light::AddressableLightEffect, public uart::UARTDevice {
  public:
-  AdalightLightEffect(const std::string &name);
+  AdalightLightEffect(const char *name);
 
   void start() override;
   void stop() override;
@@ -35,5 +34,4 @@ class AdalightLightEffect : public light::AddressableLightEffect, public uart::U
   std::vector<uint8_t> frame_;
 };
 
-}  // namespace adalight
-}  // namespace esphome
+}  // namespace esphome::adalight

esphome/components/adc/__init__.py

@@ -1,15 +1,17 @@
 from esphome import pins
 import esphome.codegen as cg
-from esphome.components.esp32 import VARIANT_ESP32P4, get_esp32_variant
-from esphome.components.esp32.const import (
+from esphome.components.esp32 import (
     VARIANT_ESP32,
     VARIANT_ESP32C2,
     VARIANT_ESP32C3,
     VARIANT_ESP32C5,
     VARIANT_ESP32C6,
+    VARIANT_ESP32C61,
     VARIANT_ESP32H2,
+    VARIANT_ESP32P4,
     VARIANT_ESP32S2,
     VARIANT_ESP32S3,
+    get_esp32_variant,
 )
 import esphome.config_validation as cv
 from esphome.const import CONF_ANALOG, CONF_INPUT, CONF_NUMBER, PLATFORM_ESP8266
@@ -99,6 +101,13 @@ ESP32_VARIANT_ADC1_PIN_TO_CHANNEL = {
         5: adc_channel_t.ADC_CHANNEL_5,
         6: adc_channel_t.ADC_CHANNEL_6,
     },
+    # https://docs.espressif.com/projects/esp-idf/en/latest/esp32c61/api-reference/peripherals/gpio.html
+    VARIANT_ESP32C61: {
+        1: adc_channel_t.ADC_CHANNEL_0,
+        3: adc_channel_t.ADC_CHANNEL_1,
+        4: adc_channel_t.ADC_CHANNEL_2,
+        5: adc_channel_t.ADC_CHANNEL_3,
+    },
     # https://github.com/espressif/esp-idf/blob/master/components/soc/esp32h2/include/soc/adc_channel.h
     VARIANT_ESP32H2: {
         1: adc_channel_t.ADC_CHANNEL_0,
@@ -107,6 +116,17 @@ ESP32_VARIANT_ADC1_PIN_TO_CHANNEL = {
         4: adc_channel_t.ADC_CHANNEL_3,
         5: adc_channel_t.ADC_CHANNEL_4,
     },
+    # https://github.com/espressif/esp-idf/blob/master/components/soc/esp32p4/include/soc/adc_channel.h
+    VARIANT_ESP32P4: {
+        16: adc_channel_t.ADC_CHANNEL_0,
+        17: adc_channel_t.ADC_CHANNEL_1,
+        18: adc_channel_t.ADC_CHANNEL_2,
+        19: adc_channel_t.ADC_CHANNEL_3,
+        20: adc_channel_t.ADC_CHANNEL_4,
+        21: adc_channel_t.ADC_CHANNEL_5,
+        22: adc_channel_t.ADC_CHANNEL_6,
+        23: adc_channel_t.ADC_CHANNEL_7,
+    },
     # https://github.com/espressif/esp-idf/blob/master/components/soc/esp32s2/include/soc/adc_channel.h
     VARIANT_ESP32S2: {
         1: adc_channel_t.ADC_CHANNEL_0,
@@ -133,16 +153,6 @@ ESP32_VARIANT_ADC1_PIN_TO_CHANNEL = {
         9: adc_channel_t.ADC_CHANNEL_8,
         10: adc_channel_t.ADC_CHANNEL_9,
     },
-    VARIANT_ESP32P4: {
-        16: adc_channel_t.ADC_CHANNEL_0,
-        17: adc_channel_t.ADC_CHANNEL_1,
-        18: adc_channel_t.ADC_CHANNEL_2,
-        19: adc_channel_t.ADC_CHANNEL_3,
-        20: adc_channel_t.ADC_CHANNEL_4,
-        21: adc_channel_t.ADC_CHANNEL_5,
-        22: adc_channel_t.ADC_CHANNEL_6,
-        23: adc_channel_t.ADC_CHANNEL_7,
-    },
 }
 
 # pin to adc2 channel mapping
@@ -173,8 +183,19 @@ ESP32_VARIANT_ADC2_PIN_TO_CHANNEL = {
     VARIANT_ESP32C5: {},  # no ADC2
     # https://github.com/espressif/esp-idf/blob/master/components/soc/esp32c6/include/soc/adc_channel.h
     VARIANT_ESP32C6: {},  # no ADC2
+    # ESP32-C61 has no ADC2
+    VARIANT_ESP32C61: {},  # no ADC2
     # https://github.com/espressif/esp-idf/blob/master/components/soc/esp32h2/include/soc/adc_channel.h
     VARIANT_ESP32H2: {},  # no ADC2
+    # https://github.com/espressif/esp-idf/blob/master/components/soc/esp32p4/include/soc/adc_channel.h
+    VARIANT_ESP32P4: {
+        49: adc_channel_t.ADC_CHANNEL_0,
+        50: adc_channel_t.ADC_CHANNEL_1,
+        51: adc_channel_t.ADC_CHANNEL_2,
+        52: adc_channel_t.ADC_CHANNEL_3,
+        53: adc_channel_t.ADC_CHANNEL_4,
+        54: adc_channel_t.ADC_CHANNEL_5,
+    },
     # https://github.com/espressif/esp-idf/blob/master/components/soc/esp32s2/include/soc/adc_channel.h
     VARIANT_ESP32S2: {
         11: adc_channel_t.ADC_CHANNEL_0,
@@ -201,14 +222,6 @@ ESP32_VARIANT_ADC2_PIN_TO_CHANNEL = {
         19: adc_channel_t.ADC_CHANNEL_8,
         20: adc_channel_t.ADC_CHANNEL_9,
     },
-    VARIANT_ESP32P4: {
-        49: adc_channel_t.ADC_CHANNEL_0,
-        50: adc_channel_t.ADC_CHANNEL_1,
-        51: adc_channel_t.ADC_CHANNEL_2,
-        52: adc_channel_t.ADC_CHANNEL_3,
-        53: adc_channel_t.ADC_CHANNEL_4,
-        54: adc_channel_t.ADC_CHANNEL_5,
-    },
 }
 
 

esphome/components/adc/adc_sensor.h

@@ -17,12 +17,12 @@
 #include <zephyr/drivers/adc.h>
 #endif
 
-namespace esphome {
-namespace adc {
+namespace esphome::adc {
 
 #ifdef USE_ESP32
 // clang-format off
-#if (ESP_IDF_VERSION_MAJOR == 5 && \
+#if ESP_IDF_VERSION_MAJOR >= 6 || \
+    (ESP_IDF_VERSION_MAJOR == 5 && \
      ((ESP_IDF_VERSION_MINOR == 0 && ESP_IDF_VERSION_PATCH >= 5) || \
       (ESP_IDF_VERSION_MINOR == 1 && ESP_IDF_VERSION_PATCH >= 3) || \
       (ESP_IDF_VERSION_MINOR >= 2)) \
@@ -68,11 +68,6 @@ class ADCSensor : public sensor::Sensor, public PollingComponent, public voltage
   /// This method is called during the ESPHome setup process to log the configuration.
   void dump_config() override;
 
-  /// Return the setup priority for this component.
-  /// Components with higher priority are initialized earlier during setup.
-  /// @return A float representing the setup priority.
-  float get_setup_priority() const override;
-
 #ifdef USE_ZEPHYR
   /// Set the ADC channel to be used by the ADC sensor.
   /// @param channel Pointer to an adc_dt_spec structure representing the ADC channel.
@@ -166,5 +161,4 @@ class ADCSensor : public sensor::Sensor, public PollingComponent, public voltage
 #endif
 };
 
-}  // namespace adc
-}  // namespace esphome
+}  // namespace esphome::adc

esphome/components/adc/adc_sensor_common.cpp

@@ -1,8 +1,7 @@
 #include "adc_sensor.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace adc {
+namespace esphome::adc {
 
 static const char *const TAG = "adc.common";
 
@@ -79,7 +78,4 @@ void ADCSensor::set_sample_count(uint8_t sample_count) {
 
 void ADCSensor::set_sampling_mode(SamplingMode sampling_mode) { this->sampling_mode_ = sampling_mode; }
 
-float ADCSensor::get_setup_priority() const { return setup_priority::DATA; }
-
-}  // namespace adc
-}  // namespace esphome
+}  // namespace esphome::adc

esphome/components/adc/adc_sensor_esp32.cpp

@@ -2,9 +2,9 @@
 
 #include "adc_sensor.h"
 #include "esphome/core/log.h"
+#include <cinttypes>
 
-namespace esphome {
-namespace adc {
+namespace esphome::adc {
 
 static const char *const TAG = "adc.esp32";
 
@@ -42,10 +42,11 @@ void ADCSensor::setup() {
     adc_oneshot_unit_init_cfg_t init_config = {};  // Zero initialize
     init_config.unit_id = this->adc_unit_;
     init_config.ulp_mode = ADC_ULP_MODE_DISABLE;
-#if USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 || USE_ESP32_VARIANT_ESP32H2
+#if USE_ESP32_VARIANT_ESP32C2 || USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || \
+    USE_ESP32_VARIANT_ESP32C6 || USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2
     init_config.clk_src = ADC_DIGI_CLK_SRC_DEFAULT;
-#endif  // USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 ||
-        // USE_ESP32_VARIANT_ESP32H2
+#endif  // USE_ESP32_VARIANT_ESP32C2 || USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 ||
+        // USE_ESP32_VARIANT_ESP32C6 || USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2
     esp_err_t err = adc_oneshot_new_unit(&init_config, &ADCSensor::shared_adc_handles[this->adc_unit_]);
     if (err != ESP_OK) {
       ESP_LOGE(TAG, "Error initializing %s: %d", LOG_STR_ARG(adc_unit_to_str(this->adc_unit_)), err);
@@ -74,8 +75,8 @@ void ADCSensor::setup() {
     adc_cali_handle_t handle = nullptr;
 
 #if USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 || \
-    USE_ESP32_VARIANT_ESP32S3 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4
-    // RISC-V variants and S3 use curve fitting calibration
+    USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S3
+    // RISC-V variants (except C2) and S3 use curve fitting calibration
     adc_cali_curve_fitting_config_t cali_config = {};  // Zero initialize first
 #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0)
     cali_config.chan = this->channel_;
@@ -93,14 +94,14 @@ void ADCSensor::setup() {
       ESP_LOGW(TAG, "Curve fitting calibration failed with error %d, will use uncalibrated readings", err);
       this->setup_flags_.calibration_complete = false;
     }
-#else  // Other ESP32 variants use line fitting calibration
+#else  // ESP32, ESP32-S2, and ESP32-C2 use line fitting calibration
     adc_cali_line_fitting_config_t cali_config = {
       .unit_id = this->adc_unit_,
       .atten = this->attenuation_,
       .bitwidth = ADC_BITWIDTH_DEFAULT,
-#if !defined(USE_ESP32_VARIANT_ESP32S2)
+#if !defined(USE_ESP32_VARIANT_ESP32S2) && !defined(USE_ESP32_VARIANT_ESP32C2)
       .default_vref = 1100,  // Default reference voltage in mV
-#endif  // !defined(USE_ESP32_VARIANT_ESP32S2)
+#endif  // !defined(USE_ESP32_VARIANT_ESP32S2) && !defined(USE_ESP32_VARIANT_ESP32C2)
     };
     err = adc_cali_create_scheme_line_fitting(&cali_config, &handle);
     if (err == ESP_OK) {
@@ -111,7 +112,7 @@ void ADCSensor::setup() {
       ESP_LOGW(TAG, "Line fitting calibration failed with error %d, will use uncalibrated readings", err);
       this->setup_flags_.calibration_complete = false;
     }
-#endif  // USE_ESP32_VARIANT_ESP32C3 || ESP32C5 || ESP32C6 || ESP32S3 || ESP32H2
+#endif  // ESP32C3 || ESP32C5 || ESP32C6 || ESP32C61 || ESP32H2 || ESP32P4 || ESP32S3
   }
 
   this->setup_flags_.init_complete = true;
@@ -120,23 +121,21 @@ void ADCSensor::setup() {
 void ADCSensor::dump_config() {
   LOG_SENSOR("", "ADC Sensor", this);
   LOG_PIN("  Pin: ", this->pin_);
-  ESP_LOGCONFIG(TAG,
-                "  Channel:       %d\n"
-                "  Unit:          %s\n"
-                "  Attenuation:   %s\n"
-                "  Samples:       %i\n"
-                "  Sampling mode: %s",
-                this->channel_, LOG_STR_ARG(adc_unit_to_str(this->adc_unit_)),
-                this->autorange_ ? "Auto" : LOG_STR_ARG(attenuation_to_str(this->attenuation_)), this->sample_count_,
-                LOG_STR_ARG(sampling_mode_to_str(this->sampling_mode_)));
-
   ESP_LOGCONFIG(
       TAG,
+      "  Channel:       %d\n"
+      "  Unit:          %s\n"
+      "  Attenuation:   %s\n"
+      "  Samples:       %i\n"
+      "  Sampling mode: %s\n"
       "  Setup Status:\n"
       "    Handle Init:  %s\n"
       "    Config:       %s\n"
       "    Calibration:  %s\n"
       "    Overall Init: %s",
+      this->channel_, LOG_STR_ARG(adc_unit_to_str(this->adc_unit_)),
+      this->autorange_ ? "Auto" : LOG_STR_ARG(attenuation_to_str(this->attenuation_)), this->sample_count_,
+      LOG_STR_ARG(sampling_mode_to_str(this->sampling_mode_)),
       this->setup_flags_.handle_init_complete ? "OK" : "FAILED", this->setup_flags_.config_complete ? "OK" : "FAILED",
       this->setup_flags_.calibration_complete ? "OK" : "FAILED", this->setup_flags_.init_complete ? "OK" : "FAILED");
 
@@ -186,11 +185,11 @@ float ADCSensor::sample_fixed_attenuation_() {
       ESP_LOGW(TAG, "ADC calibration conversion failed with error %d, disabling calibration", err);
       if (this->calibration_handle_ != nullptr) {
 #if USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 || \
-    USE_ESP32_VARIANT_ESP32S3 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4
+    USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S3
         adc_cali_delete_scheme_curve_fitting(this->calibration_handle_);
 #else   // Other ESP32 variants use line fitting calibration
         adc_cali_delete_scheme_line_fitting(this->calibration_handle_);
-#endif  // USE_ESP32_VARIANT_ESP32C3 || ESP32C5 || ESP32C6 || ESP32S3 || ESP32H2
+#endif  // ESP32C3 || ESP32C5 || ESP32C6 || ESP32C61 || ESP32H2 || ESP32P4 || ESP32S3
         this->calibration_handle_ = nullptr;
       }
     }
@@ -219,7 +218,7 @@ float ADCSensor::sample_autorange_() {
     if (this->calibration_handle_ != nullptr) {
       // Delete old calibration handle
 #if USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 || \
-    USE_ESP32_VARIANT_ESP32S3 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4
+    USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S3
       adc_cali_delete_scheme_curve_fitting(this->calibration_handle_);
 #else
       adc_cali_delete_scheme_line_fitting(this->calibration_handle_);
@@ -231,7 +230,7 @@ float ADCSensor::sample_autorange_() {
     adc_cali_handle_t handle = nullptr;
 
 #if USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 || \
-    USE_ESP32_VARIANT_ESP32S3 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4
+    USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S3
     adc_cali_curve_fitting_config_t cali_config = {};
 #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0)
     cali_config.chan = this->channel_;
@@ -248,7 +247,7 @@ float ADCSensor::sample_autorange_() {
       .unit_id = this->adc_unit_,
       .atten = atten,
       .bitwidth = ADC_BITWIDTH_DEFAULT,
-#if !defined(USE_ESP32_VARIANT_ESP32S2)
+#if !defined(USE_ESP32_VARIANT_ESP32S2) && !defined(USE_ESP32_VARIANT_ESP32C2)
       .default_vref = 1100,
 #endif
     };
@@ -266,7 +265,7 @@ float ADCSensor::sample_autorange_() {
       ESP_LOGW(TAG, "ADC read failed in autorange with error %d", err);
       if (handle != nullptr) {
 #if USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 || \
-    USE_ESP32_VARIANT_ESP32S3 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4
+    USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S3
         adc_cali_delete_scheme_curve_fitting(handle);
 #else
         adc_cali_delete_scheme_line_fitting(handle);
@@ -288,7 +287,7 @@ float ADCSensor::sample_autorange_() {
       }
       // Clean up calibration handle
 #if USE_ESP32_VARIANT_ESP32C3 || USE_ESP32_VARIANT_ESP32C5 || USE_ESP32_VARIANT_ESP32C6 || \
-    USE_ESP32_VARIANT_ESP32S3 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4
+    USE_ESP32_VARIANT_ESP32C61 || USE_ESP32_VARIANT_ESP32H2 || USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S3
       adc_cali_delete_scheme_curve_fitting(handle);
 #else
       adc_cali_delete_scheme_line_fitting(handle);
@@ -347,7 +346,8 @@ float ADCSensor::sample_autorange_() {
   ESP_LOGVV(TAG, "Autorange summary:");
   ESP_LOGVV(TAG, "  Raw readings: 12db=%d, 6db=%d, 2.5db=%d, 0db=%d", raw12, raw6, raw2, raw0);
   ESP_LOGVV(TAG, "  Voltages: 12db=%.6f, 6db=%.6f, 2.5db=%.6f, 0db=%.6f", mv12, mv6, mv2, mv0);
-  ESP_LOGVV(TAG, "  Coefficients: c12=%u, c6=%u, c2=%u, c0=%u, sum=%u", c12, c6, c2, c0, csum);
+  ESP_LOGVV(TAG, "  Coefficients: c12=%" PRIu32 ", c6=%" PRIu32 ", c2=%" PRIu32 ", c0=%" PRIu32 ", sum=%" PRIu32, c12,
+            c6, c2, c0, csum);
 
   if (csum == 0) {
     ESP_LOGE(TAG, "Invalid weight sum in autorange calculation");
@@ -355,13 +355,14 @@ float ADCSensor::sample_autorange_() {
   }
 
   const float final_result = (mv12 * c12 + mv6 * c6 + mv2 * c2 + mv0 * c0) / csum;
-  ESP_LOGV(TAG, "Autorange final: (%.6f*%u + %.6f*%u + %.6f*%u + %.6f*%u)/%u = %.6fV", mv12, c12, mv6, c6, mv2, c2, mv0,
-           c0, csum, final_result);
+  ESP_LOGV(TAG,
+           "Autorange final: (%.6f*%" PRIu32 " + %.6f*%" PRIu32 " + %.6f*%" PRIu32 " + %.6f*%" PRIu32 ")/%" PRIu32
+           " = %.6fV",
+           mv12, c12, mv6, c6, mv2, c2, mv0, c0, csum, final_result);
 
   return final_result;
 }
 
-}  // namespace adc
-}  // namespace esphome
+}  // namespace esphome::adc
 
 #endif  // USE_ESP32

esphome/components/adc/adc_sensor_esp8266.cpp

@@ -11,8 +11,7 @@ ADC_MODE(ADC_VCC)
 #include <Arduino.h>
 #endif  // USE_ADC_SENSOR_VCC
 
-namespace esphome {
-namespace adc {
+namespace esphome::adc {
 
 static const char *const TAG = "adc.esp8266";
 
@@ -55,7 +54,6 @@ float ADCSensor::sample() {
   return aggr.aggregate() / 1024.0f;
 }
 
-}  // namespace adc
-}  // namespace esphome
+}  // namespace esphome::adc
 
 #endif  // USE_ESP8266

esphome/components/adc/adc_sensor_libretiny.cpp

@@ -3,8 +3,7 @@
 #include "adc_sensor.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace adc {
+namespace esphome::adc {
 
 static const char *const TAG = "adc.libretiny";
 
@@ -48,7 +47,6 @@ float ADCSensor::sample() {
   return aggr.aggregate() / 1000.0f;
 }
 
-}  // namespace adc
-}  // namespace esphome
+}  // namespace esphome::adc
 
 #endif  // USE_LIBRETINY

esphome/components/adc/adc_sensor_rp2040.cpp

@@ -8,8 +8,14 @@
 #endif  // CYW43_USES_VSYS_PIN
 #include <hardware/adc.h>
 
-namespace esphome {
-namespace adc {
+// 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::adc {
 
 static const char *const TAG = "adc.rp2040";
 
@@ -91,7 +97,6 @@ float ADCSensor::sample() {
   return aggr.aggregate() * 3.3f / 4096.0f * coeff;
 }
 
-}  // namespace adc
-}  // namespace esphome
+}  // namespace esphome::adc
 
 #endif  // USE_RP2040

esphome/components/adc/adc_sensor_zephyr.cpp

@@ -5,8 +5,7 @@
 
 #include "hal/nrf_saadc.h"
 
-namespace esphome {
-namespace adc {
+namespace esphome::adc {
 
 static const char *const TAG = "adc.zephyr";
 
@@ -202,6 +201,5 @@ float ADCSensor::sample() {
   return val_mv / 1000.0f;
 }
 
-}  // namespace adc
-}  // namespace esphome
+}  // namespace esphome::adc
 #endif

esphome/components/adc/sensor.py

@@ -2,7 +2,11 @@ import logging
 
 import esphome.codegen as cg
 from esphome.components import sensor, voltage_sampler
-from esphome.components.esp32 import get_esp32_variant
+from esphome.components.esp32 import (
+    get_esp32_variant,
+    include_builtin_idf_component,
+    require_adc_oneshot_iram,
+)
 from esphome.components.nrf52.const import AIN_TO_GPIO, EXTRA_ADC
 from esphome.components.zephyr import (
     zephyr_add_overlay,
@@ -24,6 +28,7 @@ from esphome.const import (
     PlatformFramework,
 )
 from esphome.core import CORE
+from esphome.types import ConfigType
 
 from . import (
     ATTENUATION_MODES,
@@ -65,6 +70,13 @@ def validate_config(config):
     return config
 
 
+def _require_adc_iram(config: ConfigType) -> ConfigType:
+    """Register ADC oneshot IRAM requirement during config validation."""
+    if CORE.is_esp32:
+        require_adc_oneshot_iram()
+    return config
+
+
 ADCSensor = adc_ns.class_(
     "ADCSensor", sensor.Sensor, cg.PollingComponent, voltage_sampler.VoltageSampler
 )
@@ -95,6 +107,7 @@ CONFIG_SCHEMA = cv.All(
     )
     .extend(cv.polling_component_schema("60s")),
     validate_config,
+    _require_adc_iram,
 )
 
 CONF_ADC_CHANNEL_ID = "adc_channel_id"
@@ -118,6 +131,9 @@ async def to_code(config):
     cg.add(var.set_sampling_mode(config[CONF_SAMPLING_MODE]))
 
     if CORE.is_esp32:
+        # Re-enable ESP-IDF's ADC driver (excluded by default to save compile time)
+        include_builtin_idf_component("esp_adc")
+
         if attenuation := config.get(CONF_ATTENUATION):
             if attenuation == "auto":
                 cg.add(var.set_autorange(cg.global_ns.true))
@@ -160,21 +176,21 @@ async def to_code(config):
         zephyr_add_user("io-channels", f"<&adc {channel_id}>")
         zephyr_add_overlay(
             f"""
-&adc {{
-    #address-cells = <1>;
-    #size-cells = <0>;
+                &adc {{
+                    #address-cells = <1>;
+                    #size-cells = <0>;
 
-    channel@{channel_id} {{
-        reg = <{channel_id}>;
-        zephyr,gain = "{gain}";
-        zephyr,reference = "ADC_REF_INTERNAL";
-        zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
-        zephyr,input-positive = <NRF_SAADC_{pin_number}>;
-        zephyr,resolution = <14>;
-        zephyr,oversampling = <8>;
-    }};
-}};
-"""
+                    channel@{channel_id} {{
+                        reg = <{channel_id}>;
+                        zephyr,gain = "{gain}";
+                        zephyr,reference = "ADC_REF_INTERNAL";
+                        zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
+                        zephyr,input-positive = <NRF_SAADC_{pin_number}>;
+                        zephyr,resolution = <14>;
+                        zephyr,oversampling = <8>;
+                    }};
+                }};
+            """
         )
 
 

esphome/components/adc128s102/adc128s102.cpp

@@ -1,8 +1,7 @@
 #include "adc128s102.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace adc128s102 {
+namespace esphome::adc128s102 {
 
 static const char *const TAG = "adc128s102";
 
@@ -28,5 +27,4 @@ uint16_t ADC128S102::read_data(uint8_t channel) {
   return digital_value;
 }
 
-}  // namespace adc128s102
-}  // namespace esphome
+}  // namespace esphome::adc128s102

esphome/components/adc128s102/adc128s102.h

@@ -4,8 +4,7 @@
 #include "esphome/core/hal.h"
 #include "esphome/components/spi/spi.h"
 
-namespace esphome {
-namespace adc128s102 {
+namespace esphome::adc128s102 {
 
 class ADC128S102 : public Component,
                    public spi::SPIDevice<spi::BIT_ORDER_MSB_FIRST, spi::CLOCK_POLARITY_LOW, spi::CLOCK_PHASE_LEADING,
@@ -19,5 +18,4 @@ class ADC128S102 : public Component,
   uint16_t read_data(uint8_t channel);
 };
 
-}  // namespace adc128s102
-}  // namespace esphome
+}  // namespace esphome::adc128s102

esphome/components/adc128s102/sensor/adc128s102_sensor.cpp

@@ -2,15 +2,12 @@
 
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace adc128s102 {
+namespace esphome::adc128s102 {
 
 static const char *const TAG = "adc128s102.sensor";
 
 ADC128S102Sensor::ADC128S102Sensor(uint8_t channel) : channel_(channel) {}
 
-float ADC128S102Sensor::get_setup_priority() const { return setup_priority::DATA; }
-
 void ADC128S102Sensor::dump_config() {
   LOG_SENSOR("", "ADC128S102 Sensor", this);
   ESP_LOGCONFIG(TAG, "  Pin: %u", this->channel_);
@@ -20,5 +17,4 @@ void ADC128S102Sensor::dump_config() {
 float ADC128S102Sensor::sample() { return this->parent_->read_data(this->channel_); }
 void ADC128S102Sensor::update() { this->publish_state(this->sample()); }
 
-}  // namespace adc128s102
-}  // namespace esphome
+}  // namespace esphome::adc128s102

esphome/components/adc128s102/sensor/adc128s102_sensor.h

@@ -7,8 +7,7 @@
 
 #include "../adc128s102.h"
 
-namespace esphome {
-namespace adc128s102 {
+namespace esphome::adc128s102 {
 
 class ADC128S102Sensor : public PollingComponent,
                          public Parented<ADC128S102>,
@@ -19,11 +18,9 @@ class ADC128S102Sensor : public PollingComponent,
 
   void update() override;
   void dump_config() override;
-  float get_setup_priority() const override;
   float sample() override;
 
  protected:
   uint8_t channel_;
 };
-}  // namespace adc128s102
-}  // namespace esphome
+}  // namespace esphome::adc128s102

esphome/components/addressable_light/addressable_light_display.cpp

@@ -1,8 +1,7 @@
 #include "addressable_light_display.h"
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace addressable_light {
+namespace esphome::addressable_light {
 
 static const char *const TAG = "addressable_light.display";
 
@@ -58,10 +57,12 @@ 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;
   }
 }
-}  // namespace addressable_light
-}  // namespace esphome
+}  // namespace esphome::addressable_light

esphome/components/addressable_light/addressable_light_display.h

@@ -7,8 +7,7 @@
 
 #include <vector>
 
-namespace esphome {
-namespace addressable_light {
+namespace esphome::addressable_light {
 
 class AddressableLightDisplay : public display::DisplayBuffer {
  public:
@@ -25,13 +24,15 @@ class AddressableLightDisplay : public display::DisplayBuffer {
       if (enabled_ && !enabled) {  // enabled -> disabled
         // - Tell the parent light to refresh, effectively wiping the display. Also
         //   restores the previous effect (if any).
-        light_state_->make_call().set_effect(this->last_effect_).perform();
+        if (this->last_effect_index_.has_value()) {
+          light_state_->make_call().set_effect(*this->last_effect_index_).perform();
+        }
 
       } else if (!enabled_ && enabled) {  // disabled -> enabled
-        // - Save the current effect.
-        this->last_effect_ = light_state_->get_effect_name();
+        // - 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;
@@ -56,8 +57,7 @@ class AddressableLightDisplay : public display::DisplayBuffer {
   int32_t width_;
   int32_t height_;
   std::vector<Color> addressable_light_buffer_;
-  optional<std::string> last_effect_;
+  optional<uint32_t> last_effect_index_;
   optional<std::function<int(int, int)>> pixel_mapper_f_;
 };
-}  // namespace addressable_light
-}  // namespace esphome
+}  // namespace esphome::addressable_light

esphome/components/ade7880/ade7880.cpp

@@ -13,8 +13,7 @@
 
 #include <cinttypes>
 
-namespace esphome {
-namespace ade7880 {
+namespace esphome::ade7880 {
 
 static const char *const TAG = "ade7880";
 
@@ -121,7 +120,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 +136,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 +152,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;
     });
   }
@@ -162,11 +161,13 @@ void ADE7880::update() {
 }
 
 void ADE7880::dump_config() {
-  ESP_LOGCONFIG(TAG, "ADE7880:");
+  ESP_LOGCONFIG(TAG,
+                "ADE7880:\n"
+                "  Frequency: %.0f Hz",
+                this->frequency_);
   LOG_PIN("  IRQ0  Pin: ", this->irq0_pin_);
   LOG_PIN("  IRQ1  Pin: ", this->irq1_pin_);
   LOG_PIN("  RESET Pin: ", this->reset_pin_);
-  ESP_LOGCONFIG(TAG, "  Frequency: %.0f Hz", this->frequency_);
 
   if (this->channel_a_ != nullptr) {
     ESP_LOGCONFIG(TAG, "  Phase A:");
@@ -311,5 +312,4 @@ void ADE7880::reset_device_() {
   this->store_.reset_pending = true;
 }
 
-}  // namespace ade7880
-}  // namespace esphome
+}  // namespace esphome::ade7880

esphome/components/ade7880/ade7880.h

@@ -16,8 +16,7 @@
 
 #include "ade7880_registers.h"
 
-namespace esphome {
-namespace ade7880 {
+namespace esphome::ade7880 {
 
 struct NeutralChannel {
   void set_current(sensor::Sensor *sens) { this->current = sens; }
@@ -125,5 +124,4 @@ class ADE7880 : public i2c::I2CDevice, public PollingComponent {
   void write_u32_register16_(uint16_t a_register, uint32_t value);
 };
 
-}  // namespace ade7880
-}  // namespace esphome
+}  // namespace esphome::ade7880

esphome/components/ade7880/ade7880_i2c.cpp

@@ -9,8 +9,7 @@
 
 #include "ade7880.h"
 
-namespace esphome {
-namespace ade7880 {
+namespace esphome::ade7880 {
 
 // adapted from https://stackoverflow.com/a/55912127/1886371
 template<size_t Bits, typename T> inline T sign_extend(const T &v) noexcept {
@@ -97,5 +96,4 @@ void ADE7880::write_u32_register16_(uint16_t a_register, uint32_t value) {
   this->write_register16(a_register, reinterpret_cast<uint8_t *>(&out), sizeof(out));
 }
 
-}  // namespace ade7880
-}  // namespace esphome
+}  // namespace esphome::ade7880