Merge remote-tracking branch 'upstream/dev' into neutral-ble-client

Bump bundled esphome-device-builder to 1.12.1 (#18541 )
[wifi] Take the lwIP core lock around sntp_servermode_dhcp() (#18511 )
2026-08-23 14:46:20 +00:00 · 2026-08-20 00:45:33 -05:00 · 2026-08-20 00:00:44 -05:00 · 2026-08-19 23:31:27 -05:00 · 2026-08-20 14:32:46 +12:00 · 2026-08-20 14:32:15 +12:00
252 changed files with 6078 additions and 1326 deletions
@@ -32,7 +32,7 @@ runs:
      # detects the activated venv via ``VIRTUAL_ENV`` so the venv layout
      # downstream jobs rely on is preserved.
      if: steps.cache-venv.outputs.cache-hit != 'true'
-      uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      with:
        enable-cache: true
        # Pull request saves land in per-PR scopes nothing else can
@@ -49,7 +49,7 @@ runs:
        python -m venv venv
        source venv/bin/activate
        python --version
-        uv pip install -r requirements.txt -r requirements_test.txt
+        uv pip install -r requirements.txt -r requirements_dev.txt -r requirements_test.txt
        uv pip install -e .
    - name: Create Python virtual environment
      if: steps.cache-venv.outputs.cache-hit != 'true' && runner.os == 'Windows'
@@ -58,5 +58,5 @@ runs:
        python -m venv venv
        source ./venv/Scripts/activate
        python --version
-        uv pip install -r requirements.txt -r requirements_test.txt
+        uv pip install -r requirements.txt -r requirements_dev.txt -r requirements_test.txt
        uv pip install -e .
@@ -70,6 +70,7 @@ async function isStackedPr(github, context) {
 async function detectMergeBranch(github, context) {
  const labels = new Set();
  const baseRef = context.payload.pull_request.base.ref;
+  const defaultBranch = context.payload.repository.default_branch;

  if (baseRef === 'release') {
    labels.add('merging-to-release');
@@ -78,7 +79,7 @@ async function detectMergeBranch(github, context) {
  } else if (await isStackedPr(github, context)) {
    // GitHub manages the merge order for a stack, so these are not blocked.
    labels.add('stacked-pr');
-  } else if (baseRef !== 'dev') {
+  } else if (baseRef !== defaultBranch) {
    // A chain built by hand: it must not merge until its base branch does.
    labels.add('chained-pr');
  }
@@ -43,14 +43,14 @@ const WITHOUT_SCHEMA = 'CODEOWNERS = ["@esphome/core"]';

 // Builds a fresh context for detectMergeBranch tests instead of mutating the
 // shared CONTEXT fixture above (which other describe blocks rely on).
-function makeMergeContext(baseRef, { stack } = {}) {
+function makeMergeContext(baseRef, { stack, defaultBranch = 'dev' } = {}) {
  const pull_request = { number: 1, base: { ref: baseRef } };
  if (stack !== undefined) {
    pull_request.stack = stack;
  }
  return {
    repo: { owner: 'esphome', repo: 'esphome' },
-    payload: { pull_request }
+    payload: { pull_request, repository: { default_branch: defaultBranch } }
  };
 }

@@ -136,6 +136,21 @@ describe('detectMergeBranch', () => {
    assert.deepEqual(Array.from(labels).sort(), ['chained-pr']);
    assert.equal(state.calls, 1);
  });
+
+  it('base ref matches default branch adds no labels', async () => {
+    const { github } = makeStackGithub({ stack: null });
+    const context = makeMergeContext('other', { defaultBranch: 'other' });
+    const labels = await detectMergeBranch(github, context);
+    assert.deepEqual(Array.from(labels).sort(), []);
+  });
+
+  it('base ref dev when the default branch is main adds chained-pr', async () => {
+    const { github } = makeStackGithub({ stack: null });
+    const context = makeMergeContext('dev', { defaultBranch: 'main' });
+    const labels = await detectMergeBranch(github, context);
+    assert.deepEqual(Array.from(labels).sort(), ['chained-pr']);
+  });
+
 });

 // ---------------------------------------------------------------------------
@@ -29,7 +29,7 @@ jobs:
      - name: Set up uv
        # ``--system`` (below) installs into the setup-python interpreter;
        # no venv is created or restored by this workflow.
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          # Pull-request-only workflow: a save could never be shared and
@@ -41,10 +41,32 @@ jobs:
          version: "0.11.15"

      - name: Install apt dependencies
+        # PR-only workflow, so nothing on dev could seed a shared apt cache
+        # entry; the cached apt action would save one copy per PR. Plain apt
+        # with every call bounded: the apt.conf.d timeouts make a dead
+        # mirror fail over in seconds, and timeout runs under sudo so it can
+        # kill apt-get itself. Install without update first: image lists are
+        # fresh, and the index refresh is what a congested mirror makes slow.
+        timeout-minutes: 15
        run: |
-          sudo apt update
-          sudo apt-cache show protobuf-compiler
-          sudo apt install -y protobuf-compiler
+          sudo tee /etc/apt/apt.conf.d/99ci-acquire-timeouts >/dev/null <<'EOF'
+          Acquire::Retries "1";
+          Acquire::http::Timeout "15";
+          Acquire::https::Timeout "15";
+          EOF
+          # Common path: the image's package lists are fresh enough.
+          if sudo DEBIAN_FRONTEND=noninteractive timeout -k 15 90 \
+              apt-get install -y protobuf-compiler; then
+            protoc --version
+            exit 0
+          fi
+          # Rescue path: refresh the lists once with a generous bound; the
+          # apt config already fails a stalled mirror over quickly.
+          sudo DEBIAN_FRONTEND=noninteractive timeout -k 10 30 \
+            dpkg --configure -a || true
+          sudo timeout -k 15 300 apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive timeout -k 15 300 \
+            apt-get install -y protobuf-compiler
          protoc --version
      - name: Install python dependencies
        run: uv pip install --system aioesphomeapi -c requirements.txt -r requirements_dev.txt
@@ -49,7 +49,7 @@ jobs:
        # detects the activated venv via ``VIRTUAL_ENV`` so downstream jobs
        # that ``. venv/bin/activate`` see an identical layout.
        if: steps.cache-venv.outputs.cache-hit != 'true'
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          # Pull request saves land in per-PR scopes nothing else can
@@ -68,6 +68,22 @@ jobs:
          uv pip install -r requirements.txt -r requirements_dev.txt -r requirements_test.txt
          uv pip install -e .

+  seed-apt-cache:
+    name: Seed apt package cache
+    runs-on: ubuntu-24.04
+    # PR-branch cache saves are invisible to other PRs, so dev/beta/release
+    # pushes seed the one shared entry PR jobs restore. The key is derived
+    # only from the package list and version; keep both identical in every
+    # step that restores it. In ci-status needs so a broken seed fails dev.
+    if: github.event_name == 'push'
+    timeout-minutes: 10
+    steps:
+      - name: Install apt packages (cached)
+        uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3
+        with:
+          packages: libsdl2-dev ccache
+          version: 1.1
+
  determine-jobs:
    name: Determine which jobs to run
    runs-on: ubuntu-24.04
@@ -323,7 +339,8 @@ jobs:

  integration-tests:
    name: Run integration tests (${{ matrix.bucket.name }})
-    runs-on: ubuntu-latest
+    # Must match seed-apt-cache's image: the apt cache key has no OS in it.
+    runs-on: ubuntu-24.04
    needs:
      - common
      - determine-jobs
@@ -335,24 +352,16 @@ jobs:
    steps:
      - name: Check out code from GitHub
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - name: Install ccache
-        # Speeds up the host compiles: tests in a bucket compile overlapping
-        # component sets, so later tests reuse earlier tests' objects.
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y --no-install-recommends ccache
-      - name: Restore ccache (restore-only)
-        # esphome stores the PlatformIO ccache under the machine-global cache
-        # dir (see _ccache_env() in esphome/platformio/toolchain.py). The
-        # bucket-name prefix prefers a same-bucket seed; the bare prefix falls
-        # back to any seed when the bucket layout differs from dev.
-        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      - name: Install apt packages (cached)
+        # ccache speeds up the host compiles. A cache hit never touches apt
+        # (mirror outages cannot hang the job); the timeout bounds the cold
+        # path. Packages and version must match seed-apt-cache exactly;
+        # libsdl2-dev is unused here and carried only for cache-key parity.
+        timeout-minutes: 10
+        uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3
        with:
-          path: ~/.cache/esphome/platformio-ccache
-          key: integration-ccache-${{ matrix.bucket.name }}-${{ github.sha }}
-          restore-keys: |
-            integration-ccache-${{ matrix.bucket.name }}-
-            integration-ccache-
+          packages: libsdl2-dev ccache
+          version: 1.1
      - name: Set up Python 3.13
        id: python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -367,7 +376,7 @@ jobs:
      - name: Set up uv
        # Only needed on cache miss to populate the venv.
        if: steps.cache-venv.outputs.cache-hit != 'true'
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          # Pull request saves land in per-PR scopes nothing else can
@@ -401,14 +410,6 @@ jobs:
        # esphome stores the PlatformIO ccache under the machine-global cache
        # dir (see _ccache_env() in esphome/platformio/toolchain.py).
        run: CCACHE_DIR="$HOME/.cache/esphome/platformio-ccache" ccache -s
-      - name: Save ccache
-        # Pull request saves land in per-PR scopes nothing else can reuse;
-        # dev pushes seed the shared copy instead.
-        if: github.event_name != 'pull_request'
-        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: ~/.cache/esphome/platformio-ccache
-          key: integration-ccache-${{ matrix.bucket.name }}-${{ github.sha }}

  import-time:
    name: Check import esphome.__main__ time
@@ -441,12 +442,17 @@ jobs:
  benchmarks:
    name: Run CodSpeed benchmarks
    runs-on: ubuntu-24.04
+    timeout-minutes: 30
    needs:
      - common
      - determine-jobs
    if: >-
-      (github.event_name == 'push' && github.ref_name == 'dev') ||
-      (github.event_name == 'pull_request' && needs.determine-jobs.outputs.benchmarks == 'true')
+      github.repository == 'esphome/esphome' && (
+        (github.event_name == 'push' && github.ref_name == 'dev') ||
+        (github.event_name == 'pull_request' && needs.determine-jobs.outputs.benchmarks == 'true')
+      )
+    # CodSpeed benchmarks require a CodSpeed account linked to the repository to run
+    # (https://codspeed.io) -- disabled on forks that aren't esphome/esphome itself.
    steps:
      - name: Check out code from GitHub
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -460,12 +466,58 @@ jobs:
      - name: Build benchmarks
        id: build
        run: |
+          # pipefail: without it a failed build is masked by the grep/cut
+          # pipeline below, leaving BINARY empty and silently dropping every
+          # C++ benchmark from the run while the job still reports success.
+          set -o pipefail
          . venv/bin/activate
-          export BENCHMARK_LIB_CONFIG=$(python script/setup_codspeed_lib.py)
-          # --build-only prints BUILD_BINARY=<path> to stdout
-          BINARY=$(script/cpp_benchmark.py --all --build-only | grep '^BUILD_BINARY=' | tail -1 | cut -d= -f2-)
+          BENCHMARK_LIB_CONFIG=$(python script/setup_codspeed_lib.py)
+          export BENCHMARK_LIB_CONFIG
+          # --build-only prints BUILD_BINARY=<path> to stdout; the grep is
+          # non-fatal so a missing marker reaches the check below instead of
+          # tripping errexit at this assignment
+          BINARY=$(script/cpp_benchmark.py --all --build-only | { grep '^BUILD_BINARY=' || true; } | tail -1 | cut -d= -f2-)
+          if [ -z "$BINARY" ]; then
+            echo "::error::Benchmark build did not report a binary path"
+            exit 1
+          fi
          echo "binary=$BINARY" >> $GITHUB_OUTPUT

+      - name: Bound apt fetches and pre-install libc6-dbg
+        # The CodSpeed runner installs valgrind + libc6-dbg via its own
+        # unbounded apt-get update; per-invocation apt options cannot reach
+        # it. The apt.conf.d timeouts below bound every later apt call in
+        # this job, the runner's included. Pre-installing libc6-dbg lets the
+        # runner skip apt once its valgrind cache is restored (it checks
+        # ``dpkg -s libc6-dbg``, so the cache action's unregistered restores
+        # would not count). Install without update first: image lists are
+        # fresh, and the index refresh is what a congested mirror makes
+        # slow. Best effort; the job timeout is the last backstop.
+        timeout-minutes: 15
+        continue-on-error: true
+        run: |
+          sudo tee /etc/apt/apt.conf.d/99ci-acquire-timeouts >/dev/null <<'EOF'
+          Acquire::Retries "1";
+          Acquire::http::Timeout "15";
+          Acquire::https::Timeout "15";
+          EOF
+          if dpkg -s libc6-dbg >/dev/null 2>&1; then
+            echo "libc6-dbg already installed"
+            exit 0
+          fi
+          # Common path: the image's package lists are fresh enough.
+          if sudo DEBIAN_FRONTEND=noninteractive timeout -k 15 90 \
+              apt-get install -y libc6-dbg; then
+            exit 0
+          fi
+          # Rescue path: refresh the lists once with a generous bound; the
+          # apt config already fails a stalled mirror over quickly.
+          sudo DEBIAN_FRONTEND=noninteractive timeout -k 10 30 \
+            dpkg --configure -a || true
+          sudo timeout -k 15 300 apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive timeout -k 15 300 \
+            apt-get install -y libc6-dbg
+
      - name: Run CodSpeed benchmarks
        uses: CodSpeedHQ/action@4296e51e7041e24dadb86d1d6e8b9320d223dbe8 # v5.0.3
        with:
@@ -550,24 +602,29 @@ jobs:
          fetch-depth: 2

      - name: Restore Python
+        id: restore-python
        uses: ./.github/actions/restore-python
        with:
          python-version: ${{ env.DEFAULT_PYTHON }}
          cache-key: ${{ needs.common.outputs.cache-key }}

+      # Key on the exact Python version as well: LibreTiny creates a venv under
+      # ~/.platformio/penv whose interpreter is a symlink into the runner's
+      # hosted toolcache, so a cache saved on an older runner image breaks once
+      # a new image ships a newer patch release and drops the old interpreter.
      - name: Cache platformio
        if: github.ref == 'refs/heads/dev' && matrix.pio_cache_key
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.platformio
-          key: platformio-${{ matrix.pio_cache_key }}-${{ hashFiles('platformio.ini') }}
+          key: platformio-${{ matrix.pio_cache_key }}-${{ steps.restore-python.outputs.python-version }}-${{ hashFiles('platformio.ini') }}

      - name: Cache platformio
        if: github.ref != 'refs/heads/dev' && matrix.pio_cache_key
        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.platformio
-          key: platformio-${{ matrix.pio_cache_key }}-${{ hashFiles('platformio.ini') }}
+          key: platformio-${{ matrix.pio_cache_key }}-${{ steps.restore-python.outputs.python-version }}-${{ hashFiles('platformio.ini') }}

      - name: Cache ESP-IDF install
        if: matrix.cache_idf
@@ -884,12 +941,17 @@ jobs:
      - name: List components
        run: echo ${{ matrix.batch.components }}

-      - name: Install apt packages
-        # Not cached: this job is pull-request-only, so a cache save could
-        # never be shared and would only consume quota.
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y --no-install-recommends libsdl2-dev ccache
+      - name: Install apt packages (cached)
+        # A cache hit (seeded on dev by seed-apt-cache) never touches apt,
+        # so mirror outages cannot hang this PR-only job; the timeout bounds
+        # the cold path. Packages and version must match seed-apt-cache
+        # exactly. The action has no --no-install-recommends; same package
+        # set this job used before #17463.
+        timeout-minutes: 10
+        uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3
+        with:
+          packages: libsdl2-dev ccache
+          version: 1.1

      - name: Check out code from GitHub
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -1091,7 +1153,7 @@ jobs:
        # install step (order-of-magnitude faster on cold boots,
        # with its own wheel cache). actions/setup-python still
        # provides the interpreter.
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          # Pull request saves land in per-PR scopes nothing else can
@@ -1424,6 +1486,7 @@ jobs:
    # this check.
    needs:
      - common
+      - seed-apt-cache
      - determine-jobs
      - ci-custom
      - pylint
@@ -56,7 +56,7 @@ jobs:

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
-        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
        with:
          languages: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
@@ -84,6 +84,6 @@ jobs:
          exit 1

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
        with:
          category: "/language:${{matrix.language}}"
@@ -14,4 +14,4 @@ jobs:
    permissions:
      issues: write         # issues.lock on closed issues
      pull-requests: write  # issues.lock on closed pull requests
-    uses: esphome/workflows/.github/workflows/lock.yml@9f6577fd37b5cf773ab1b9be929714a0dcd15661  # 2026.7.0
+    uses: esphome/workflows/.github/workflows/lock.yml@0fdd5e311b7e744069166696072a1a9cbc5fbeb6  # 2026.8.1
@@ -16,7 +16,7 @@ jobs:
    # No GITHUB_TOKEN permissions: the reusable workflow mints an ESPHome
    # GitHub App token so the labels, comments and closures come from
    # esphome[bot] instead of github-actions[bot].
-    uses: esphome/workflows/.github/workflows/stale.yml@61fd37a044cad4e9aa4303027b2a61b6a34da855  # main
+    uses: esphome/workflows/.github/workflows/stale.yml@a1c1485ab46ef41a84a6a9d8abd7fa4b7628fd70  # main
    secrets:
      ESPHOME_GITHUB_APP_PRIVATE_KEY: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
    with:
@@ -47,7 +47,7 @@ jobs:
        # setup-python interpreter so subsequent ``prek`` /
        # ``script/run-in-env.py`` steps find the deps without a
        # ``uv run`` prefix.
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          # Pin uv version so the action does not have to fetch the
@@ -11,7 +11,7 @@ ci:
 repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    # Ruff version.
-    rev: v0.16.0
+    rev: v0.16.3
    hooks:
      # Run the linter.
      - id: ruff
@@ -763,3 +763,13 @@ The project uses English for non-code content. When drafting documentation, code
 PR descriptions, and similar text, avoid technical jargon. Instead, express concepts in plain English,
 using standard technical terms only when required. Ensure the text is readily comprehensible to a wide
 audience, including non-native English speakers.
+
+## 10. Code Comments
+
+Code comments on individual lines should be used only where necessary to flag issues that may not be obvious
+on a simple reading of the code. Keep them short (e.g. 1 or 2 lines).
+
+Function and method comment blocks may include more detail as required to make
+calling contracts clear and document parameter usage, but should still be kept concise.
+
+Avoid redundancy and repetition; comments should never simply restate what the code already says.
@@ -22,7 +22,7 @@ RUN \
    -r /requirements.txt

 # Install the ESPHome Device Builder dashboard.
-RUN uv pip install --no-cache-dir esphome-device-builder==1.9.6
+RUN uv pip install --no-cache-dir esphome-device-builder==1.12.1

 RUN \
    platformio settings set enable_telemetry No \
@@ -2732,7 +2732,8 @@ def run_esphome(argv):
                conf_path.name,
            )

-    if config is None:
+    cache_missed = config is None
+    if cache_missed:
        from esphome.config import read_config

        config = read_config(
@@ -2741,26 +2742,25 @@ def run_esphome(argv):
            # Snapshot only needed by `esphome config --no-defaults`.
            snapshot_user_config=getattr(args, "no_defaults", False),
        )
-        # Refresh the cache so the next upload/logs hits the fast path
-        # instead of re-running read_config. Skip when the storage
-        # sidecar is absent (no compile has run): the cache would
-        # never be loaded back, so writing secrets to disk is wasted.
-        if cache_eligible and config is not None:
-            from esphome.compiled_config import save_compiled_config
-            from esphome.storage_json import ext_storage_path
-
-            if ext_storage_path(conf_path.name).exists():
-                save_compiled_config(config)
-    if config is None:
-        return 2
+        if config is None:
+            return 2
    CORE.config = config

    # Fallback for platforms whose validators didn't set the toolchain
    # (only the esp32 component reads esp32.framework.toolchain). All
-    # other platforms only support PlatformIO today.
+    # other platforms only support PlatformIO today. Must run before the
+    # cache refresh below so its sidecar records the same toolchain a
+    # compile would.
    if CORE.toolchain is None:
        CORE.toolchain = Toolchain.PLATFORMIO

+    # Refresh the cache so the next upload/logs hits the fast path
+    # instead of re-running read_config.
+    if cache_eligible and cache_missed:
+        from esphome.compiled_config import save_compiled_config_and_sidecar
+
+        save_compiled_config_and_sidecar(config)
+
    if args.command not in POST_CONFIG_ACTIONS:
        safe_print(f"Unknown command {args.command}")
        return 1
@@ -18,9 +18,9 @@ from pathlib import Path
 from typing import Any

 from esphome.const import __version__ as ESPHOME_VERSION
-from esphome.core import CORE, Lambda
+from esphome.core import CORE, EsphomeError, Lambda
 from esphome.helpers import write_file
-from esphome.storage_json import StorageJSON, ext_storage_path
+from esphome.storage_json import StorageJSON, ext_storage_path, storage_path
 from esphome.types import ConfigType

 _LOGGER = logging.getLogger(__name__)
@@ -65,7 +65,71 @@ def save_compiled_config(config: ConfigType) -> None:
        # non-basic dict key), so every upload/logs pays the slow path.
        _LOGGER.warning("Cannot cache the validated config: %s", err)
    except Exception as err:  # noqa: BLE001  # pylint: disable=broad-except
-        _LOGGER.debug("Skipping compiled config cache write: %s", err)
+        # Likely persistent (permissions, full disk): every upload/logs
+        # pays the slow path until it clears, so surface it.
+        _LOGGER.warning("Skipping compiled config cache write: %s", err)
+
+
+def save_compiled_config_and_sidecar(config: ConfigType) -> None:
+    """Refresh the cache from the upload/logs fallback (CORE.config must be set).
+
+    The cache is only written when a complete sidecar is on disk:
+    load_compiled_config can't use it otherwise, and it holds resolved
+    secrets.
+    """
+    if _refresh_sidecar():
+        save_compiled_config(config)
+
+
+def _refresh_sidecar() -> bool:
+    """Ensure a complete sidecar is on disk; True when one is.
+
+    Writes one (without claiming a build) when missing or wizard-only.
+    Failures are non-fatal; the next upload/logs pays the slow path again.
+    """
+    try:
+        path = storage_path()
+        try:
+            old = StorageJSON.load_strict(path)
+        except Exception as err:  # noqa: BLE001  # pylint: disable=broad-except
+            # Present but unreadable: it may hold a real build's metadata,
+            # and a fresh rewrite would also stop the next compile from
+            # cleaning a possibly incoherent build tree.
+            _LOGGER.warning(
+                "Not caching: storage sidecar %s is unreadable (%s)", path, err
+            )
+            return False
+        if old is not None and old.can_apply_to_core():
+            # Compile-written; nothing to refresh.
+            return True
+        if CORE.build_path is not None and CORE.build_path.exists():
+            # An unvalidated build tree: its absent or mismatched sidecar
+            # is what makes the next compile wipe it, so don't vouch for
+            # a build this run never saw.
+            _LOGGER.warning(
+                "Not caching: build tree %s has no matching sidecar; "
+                "'esphome compile' will settle it",
+                CORE.build_path,
+            )
+            return False
+        new = StorageJSON.from_esphome_core(CORE, old, claim_build=False)
+        if not new.can_apply_to_core():
+            _LOGGER.warning("Not caching: rebuilt storage sidecar is still incomplete")
+            return False
+        new.save(path)
+        return True
+    except (OSError, EsphomeError) as err:
+        # write_file wraps OSError into EsphomeError. Persistent
+        # (unwritable storage dir), so surface that every upload/logs
+        # pays the slow path.
+        _LOGGER.warning("Could not refresh the storage sidecar: %s", err)
+    except Exception:  # noqa: BLE001  # pylint: disable=broad-except
+        # A structural bug; keep the traceback so it isn't mistaken
+        # for the I/O failure above.
+        _LOGGER.warning(
+            "Unexpected error refreshing the storage sidecar", exc_info=True
+        )
+    return False


 def load_compiled_config(conf_path: Path) -> ConfigType | None:
@@ -98,11 +162,8 @@ def load_compiled_config(conf_path: Path) -> ConfigType | None:
        return None

    storage = StorageJSON.load(ext_storage_path(conf_path.name))
-    if storage is None:
-        return None
-    # apply_to_core assumes a real compile wrote the sidecar; wizard-only
-    # sidecars leave both of these unset and can't drive upload/logs.
-    if not storage.core_platform and not storage.target_platform:
+    if storage is None or not storage.can_apply_to_core():
+        _LOGGER.debug("Ignoring compiled config cache: sidecar missing or incomplete")
        return None
    storage.apply_to_core()
    return config
@@ -3,7 +3,7 @@

 namespace esphome::adc {

-static const char *const TAG = "adc.common";
+static const char *const TAG = "adc";

 const LogString *sampling_mode_to_str(SamplingMode mode) {
  switch (mode) {
@@ -6,7 +6,7 @@

 namespace esphome::adc {

-static const char *const TAG = "adc.esp32";
+static const char *const TAG = "adc";

 adc_oneshot_unit_handle_t ADCSensor::shared_adc_handles[2] = {nullptr, nullptr};

@@ -13,7 +13,7 @@ ADC_MODE(ADC_VCC)

 namespace esphome::adc {

-static const char *const TAG = "adc.esp8266";
+static const char *const TAG = "adc";

 void ADCSensor::setup() {
 #ifndef USE_ADC_SENSOR_VCC
@@ -5,7 +5,7 @@

 namespace esphome::adc {

-static const char *const TAG = "adc.libretiny";
+static const char *const TAG = "adc";

 void ADCSensor::setup() {
 #ifndef USE_ADC_SENSOR_VCC
@@ -17,7 +17,7 @@

 namespace esphome::adc {

-static const char *const TAG = "adc.rp2";
+static const char *const TAG = "adc";

 // The on-die temperature sensor sits on the last ADC channel: input 4 on RP2040
 // and RP2350A, but input 8 on RP2350B, which has eight external channels rather
@@ -7,7 +7,7 @@

 namespace esphome::adc {

-static const char *const TAG = "adc.zephyr";
+static const char *const TAG = "adc";

 void ADCSensor::setup() {
  if (!adc_is_ready_dt(this->channel_)) {
@@ -497,7 +497,7 @@ async def to_code(config: ConfigType) -> None:
            # and plaintext disabled. Only a factory reset can remove it.
            cg.add_define("USE_API_PLAINTEXT")
        cg.add_define("USE_API_NOISE")
-        cg.add_library("esphome/noise-c", "0.1.11")
+        cg.add_library("esphome/noise-c", "0.1.21")
        # Enable optimized memzero/memcmp in libsodium instead of volatile byte loops
        cg.add_build_flag("-DHAVE_WEAK_SYMBOLS=1")
        cg.add_build_flag("-DHAVE_INLINE_ASM=1")
@@ -160,11 +160,6 @@ APIConnection::APIConnection(std::unique_ptr<socket::Socket> sock, APIServer *pa
 #else
 #error "No frame helper defined"
 #endif
-#ifdef USE_CAMERA
-  if (camera::Camera::instance() != nullptr) {
-    this->image_reader_ = std::unique_ptr<camera::CameraImageReader>{camera::Camera::instance()->create_image_reader()};
-  }
-#endif
 }

 void APIConnection::start() {
@@ -1140,6 +1135,7 @@ void APIConnection::try_send_camera_image_() {
  if (!this->image_reader_)
    return;

+  const auto *cam = camera::Camera::instance();
  // Send as many chunks as possible without blocking
  while (this->image_reader_->available()) {
    if (!this->helper_->can_write_without_blocking())
@@ -1149,11 +1145,11 @@ void APIConnection::try_send_camera_image_() {
    bool done = this->image_reader_->available() == to_send;

    CameraImageResponse msg;
-    msg.key = camera::Camera::instance()->get_object_id_hash();
+    msg.key = cam->get_object_id_hash();
    msg.set_data(this->image_reader_->peek_data_buffer(), to_send);
    msg.done = done;
 #ifdef USE_DEVICES
-    msg.device_id = camera::Camera::instance()->get_device_id();
+    msg.device_id = cam->get_device_id();
 #endif

    if (!this->send_message(msg)) {
@@ -1169,15 +1165,19 @@ void APIConnection::try_send_camera_image_() {
 void APIConnection::set_camera_state(std::shared_ptr<camera::CameraImage> image) {
  if (!this->flags_.state_subscription)
    return;
-  if (!this->image_reader_)
+  if (this->image_reader_ && this->image_reader_->available())
    return;
-  if (this->image_reader_->available())
+  if (!image->was_requested_by(esphome::camera::API_REQUESTER) && !image->was_requested_by(esphome::camera::IDLE))
    return;
-  if (image->was_requested_by(esphome::camera::API_REQUESTER) || image->was_requested_by(esphome::camera::IDLE)) {
-    this->image_reader_->set_image(std::move(image));
-    // Try to send immediately to reduce latency
-    this->try_send_camera_image_();
+  if (!this->image_reader_) {
+    // Created on the first image this connection will send, so connections
+    // that never receive one never pay for a reader. Only a registered
+    // camera's listener can reach this, so instance() is non-null here.
+    this->image_reader_ = std::unique_ptr<camera::CameraImageReader>{camera::Camera::instance()->create_image_reader()};
  }
+  this->image_reader_->set_image(std::move(image));
+  // Try to send immediately to reduce latency
+  this->try_send_camera_image_();
 }
 uint16_t APIConnection::try_send_camera_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size) {
  auto *camera = static_cast<camera::Camera *>(entity);
@@ -591,18 +591,21 @@ APIError APINoiseFrameHelper::write_frame_(const uint8_t *data, uint16_t len) {
 */
 APIError APINoiseFrameHelper::init_handshake_() {
  int err;
-  memset(&nid_, 0, sizeof(nid_));
-  // const char *proto = "Noise_NNpsk0_25519_ChaChaPoly_SHA256";
-  // err = noise_protocol_name_to_id(&nid_, proto, strlen(proto));
-  nid_.pattern_id = NOISE_PATTERN_NN;
-  nid_.cipher_id = NOISE_CIPHER_CHACHAPOLY;
-  nid_.dh_id = NOISE_DH_CURVE25519;
-  nid_.prefix_id = NOISE_PREFIX_STANDARD;
-  nid_.hybrid_id = NOISE_DH_NONE;
-  nid_.hash_id = NOISE_HASH_SHA256;
-  nid_.modifier_ids[0] = NOISE_MODIFIER_PSK0;
+  // Noise_NNpsk0_25519_ChaChaPoly_SHA256, built on the stack:
+  // noise_handshakestate_new_by_id copies it, so a member would waste
+  // 104 bytes per connection, and a static const would sit in RAM on
+  // ESP8266 (.rodata is DRAM there).
+  const NoiseProtocolId nid = {
+      .prefix_id = NOISE_PREFIX_STANDARD,
+      .pattern_id = NOISE_PATTERN_NN,
+      .modifier_ids = {NOISE_MODIFIER_PSK0},
+      .dh_id = NOISE_DH_CURVE25519,
+      .cipher_id = NOISE_CIPHER_CHACHAPOLY,
+      .hash_id = NOISE_HASH_SHA256,
+      .hybrid_id = NOISE_DH_NONE,
+  };

-  err = noise_handshakestate_new_by_id(&handshake_, &nid_, NOISE_ROLE_RESPONDER);
+  err = noise_handshakestate_new_by_id(&handshake_, &nid, NOISE_ROLE_RESPONDER);
  APIError aerr =
      handle_noise_error_(err, LOG_STR("noise_handshakestate_new_by_id"), APIError::HANDSHAKESTATE_SETUP_FAILED);
  if (aerr != APIError::OK)
@@ -63,9 +63,6 @@ class APINoiseFrameHelper final : public APIFrameHelper {
  // Buffer for noise handshake prologue (released after handshake)
  APIBuffer prologue_;

-  // NoiseProtocolId (size depends on implementation)
-  NoiseProtocolId nid_;
-
  // Group small types together
  // Fixed-size header buffer for noise protocol:
  // 1 byte for indicator + 2 bytes for message size (16-bit value, not varint)
@@ -300,46 +300,12 @@ void BekenSPILEDStripLightOutput::write_state(light::LightState *state) {
 }

 light::ESPColorView BekenSPILEDStripLightOutput::get_view_internal(int32_t index) const {
-  int32_t r = 0, g = 0, b = 0;
-  switch (this->rgb_order_) {
-    case ORDER_RGB:
-      r = 0;
-      g = 1;
-      b = 2;
-      break;
-    case ORDER_RBG:
-      r = 0;
-      g = 2;
-      b = 1;
-      break;
-    case ORDER_GRB:
-      r = 1;
-      g = 0;
-      b = 2;
-      break;
-    case ORDER_GBR:
-      r = 2;
-      g = 0;
-      b = 1;
-      break;
-    case ORDER_BGR:
-      r = 2;
-      g = 1;
-      b = 0;
-      break;
-    case ORDER_BRG:
-      r = 1;
-      g = 2;
-      b = 0;
-      break;
-  }
-  uint8_t multiplier = this->is_rgbw_ || this->is_wrgb_ ? 4 : 3;
-  uint8_t white = this->is_wrgb_ ? 0 : 3;
-
-  return {this->buf_ + (index * multiplier) + r + this->is_wrgb_,
-          this->buf_ + (index * multiplier) + g + this->is_wrgb_,
-          this->buf_ + (index * multiplier) + b + this->is_wrgb_,
-          this->is_rgbw_ || this->is_wrgb_ ? this->buf_ + (index * multiplier) + white : nullptr,
+  const light::ChannelColors &colors = this->channel_colors_;
+  uint8_t *led = this->buf_ + (index * colors.bytes_per_led());
+  return {led + colors.r,
+          led + colors.g,
+          led + colors.b,
+          colors.has_white() ? led + colors.w : nullptr,
          &this->effect_data_[index],
          &this->correction_};
 }
@@ -349,35 +315,12 @@ void BekenSPILEDStripLightOutput::dump_config() {
                "Beken SPI LED Strip:\n"
                "  Pin: %u",
                this->pin_);
-  const char *rgb_order;
-  switch (this->rgb_order_) {
-    case ORDER_RGB:
-      rgb_order = "RGB";
-      break;
-    case ORDER_RBG:
-      rgb_order = "RBG";
-      break;
-    case ORDER_GRB:
-      rgb_order = "GRB";
-      break;
-    case ORDER_GBR:
-      rgb_order = "GBR";
-      break;
-    case ORDER_BGR:
-      rgb_order = "BGR";
-      break;
-    case ORDER_BRG:
-      rgb_order = "BRG";
-      break;
-    default:
-      rgb_order = "UNKNOWN";
-      break;
-  }
+  char channel_colors[5];
  ESP_LOGCONFIG(TAG,
-                "  RGB Order: %s\n"
+                "  Channel colors: %s\n"
                "  Max refresh rate: %" PRIu32 "\n"
                "  Number of LEDs: %u",
-                rgb_order, this->max_refresh_rate_.value_or(0), this->num_leds_);
+                this->channel_colors_.to_string(channel_colors), this->max_refresh_rate_.value_or(0), this->num_leds_);
 }

 float BekenSPILEDStripLightOutput::get_setup_priority() const { return setup_priority::HARDWARE; }
@@ -3,6 +3,7 @@
 #ifdef USE_BK72XX

 #include "esphome/components/light/addressable_light.h"
+#include "esphome/components/light/channel_colors.h"
 #include "esphome/components/light/light_output.h"
 #include "esphome/core/color.h"
 #include "esphome/core/component.h"
@@ -10,15 +11,6 @@

 namespace esphome::beken_spi_led_strip {

-enum RGBOrder : uint8_t {
-  ORDER_RGB,
-  ORDER_RBG,
-  ORDER_GRB,
-  ORDER_GBR,
-  ORDER_BGR,
-  ORDER_BRG,
-};
-
 class BekenSPILEDStripLightOutput final : public light::AddressableLight {
 public:
  void setup() override;
@@ -28,7 +20,7 @@ class BekenSPILEDStripLightOutput final : public light::AddressableLight {
  int32_t size() const override { return this->num_leds_; }
  light::LightTraits get_traits() override {
    auto traits = light::LightTraits();
-    if (this->is_rgbw_ || this->is_wrgb_) {
+    if (this->channel_colors_.has_white()) {
      traits.set_supported_color_modes({light::ColorMode::RGB_WHITE, light::ColorMode::WHITE});
    } else {
      traits.set_supported_color_modes({light::ColorMode::RGB});
@@ -38,16 +30,13 @@ class BekenSPILEDStripLightOutput final : public light::AddressableLight {

  void set_pin(uint8_t pin) { this->pin_ = pin; }
  void set_num_leds(uint16_t num_leds) { this->num_leds_ = num_leds; }
-  void set_is_rgbw(bool is_rgbw) { this->is_rgbw_ = is_rgbw; }
-  void set_is_wrgb(bool is_wrgb) { this->is_wrgb_ = is_wrgb; }
+  void set_channel_colors(light::ChannelColors channel_colors) { this->channel_colors_ = channel_colors; }

  /// Set a maximum refresh rate in µs as some lights do not like being updated too often.
  void set_max_refresh_rate(uint32_t interval_us) { this->max_refresh_rate_ = interval_us; }

  void set_led_params(uint8_t bit0, uint8_t bit1, uint32_t spi_frequency);

-  void set_rgb_order(RGBOrder rgb_order) { this->rgb_order_ = rgb_order; }
-
  void clear_effect_data() override {
    for (int i = 0; i < this->size(); i++)
      this->effect_data_[i] = 0;
@@ -58,7 +47,7 @@ class BekenSPILEDStripLightOutput final : public light::AddressableLight {
 protected:
  light::ESPColorView get_view_internal(int32_t index) const override;

-  size_t get_buffer_size_() const { return this->num_leds_ * (this->is_rgbw_ || this->is_wrgb_ ? 4 : 3); }
+  size_t get_buffer_size_() const { return this->num_leds_ * this->channel_colors_.bytes_per_led(); }

  uint8_t *buf_{nullptr};
  uint8_t *effect_data_{nullptr};
@@ -66,13 +55,11 @@ class BekenSPILEDStripLightOutput final : public light::AddressableLight {

  uint8_t pin_;
  uint16_t num_leds_;
-  bool is_rgbw_;
-  bool is_wrgb_;

  uint32_t spi_frequency_{6666666};
  uint8_t bit0_{0xE0};
  uint8_t bit1_{0xFC};
-  RGBOrder rgb_order_;
+  light::ChannelColors channel_colors_{0, 1, 2, light::ChannelColors::NO_WHITE};

  uint32_t last_refresh_{0};
  optional<uint32_t> max_refresh_rate_{};
@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from esphome import pins
 import esphome.codegen as cg
 from esphome.components import libretiny, light
+from esphome.components.const import CONF_CHANNEL_COLORS, CONF_IS_WRGB
 import esphome.config_validation as cv
 from esphome.const import (
    CONF_CHIPSET,
@@ -13,6 +14,7 @@ from esphome.const import (
    CONF_PIN,
    CONF_RGB_ORDER,
 )
+from esphome.types import ConfigType

 CODEOWNERS = ["@Mat931"]
 DEPENDENCIES = ["libretiny"]
@@ -22,17 +24,6 @@ BekenSPILEDStripLightOutput = beken_spi_led_strip_ns.class_(
    "BekenSPILEDStripLightOutput", light.AddressableLight
 )

-RGBOrder = beken_spi_led_strip_ns.enum("RGBOrder")
-
-RGB_ORDERS = {
-    "RGB": RGBOrder.ORDER_RGB,
-    "RBG": RGBOrder.ORDER_RBG,
-    "GRB": RGBOrder.ORDER_GRB,
-    "GBR": RGBOrder.ORDER_GBR,
-    "BGR": RGBOrder.ORDER_BGR,
-    "BRG": RGBOrder.ORDER_BRG,
-}
-

@dataclass
 class LEDStripTimings:
@@ -57,8 +48,6 @@ CHIPSETS = {
 }


-CONF_IS_WRGB = "is_wrgb"
-
 SUPPORTED_PINS = {
    libretiny.const.FAMILY_BK7231N: [16],
    libretiny.const.FAMILY_BK7231T: [16],
@@ -79,10 +68,9 @@ def _validate_pin(value):
    return value


-def _validate_num_leds(value):
-    max_num_leds = 165  # 170
-    if value[CONF_IS_RGBW] or value[CONF_IS_WRGB]:
-        max_num_leds = 123  # 127
+def _validate_num_leds(value: ConfigType) -> ConfigType:
+    # A white channel makes each LED one byte wider, so fewer of them fit in the DMA buffer.
+    max_num_leds = 123 if "W" in value[CONF_CHANNEL_COLORS] else 165  # 127 / 170
    if value[CONF_NUM_LEDS] > max_num_leds:
        raise cv.Invalid(
            f"The maximum number of LEDs for this configuration is {max_num_leds}.",
@@ -99,18 +87,23 @@ CONFIG_SCHEMA = cv.All(
                pins.internal_gpio_output_pin_number, _validate_pin
            ),
            cv.Required(CONF_NUM_LEDS): cv.positive_not_null_int,
-            cv.Required(CONF_RGB_ORDER): cv.enum(RGB_ORDERS, upper=True),
+            cv.Optional(CONF_CHANNEL_COLORS): light.validate_channel_colors,
+            # Deprecated in favour of CONF_CHANNEL_COLORS, remove in 2027.3.0
+            cv.Optional(CONF_RGB_ORDER): cv.one_of(*light.RGB_ORDERS, upper=True),
+            cv.Optional(CONF_IS_RGBW): cv.boolean,
+            cv.Optional(CONF_IS_WRGB): cv.boolean,
            cv.Optional(CONF_MAX_REFRESH_RATE): cv.positive_time_period_microseconds,
            cv.Required(CONF_CHIPSET): cv.one_of(*CHIPSETS, upper=True),
-            cv.Optional(CONF_IS_RGBW, default=False): cv.boolean,
-            cv.Optional(CONF_IS_WRGB, default=False): cv.boolean,
        }
    ),
+    light.migrate_channel_colors(
+        removed_in="2027.3.0", component="beken_spi_led_strip"
+    ),
    _validate_num_leds,
 )


-async def to_code(config):
+async def to_code(config: ConfigType) -> None:
    var = cg.new_Pvariable(config[CONF_OUTPUT_ID])
    await light.register_light(var, config)
    await cg.register_component(var, config)
@@ -130,6 +123,6 @@ async def to_code(config):
        )
    )

-    cg.add(var.set_rgb_order(config[CONF_RGB_ORDER]))
-    cg.add(var.set_is_rgbw(config[CONF_IS_RGBW]))
-    cg.add(var.set_is_wrgb(config[CONF_IS_WRGB]))
+    cg.add(
+        var.set_channel_colors(light.channel_colors_struct(config[CONF_CHANNEL_COLORS]))
+    )
@@ -5,11 +5,11 @@ bring-up and the controller BLE address. Consumers (bk72xx_ble_tracker) build
 on this component and contain no SDK calls of their own.

 Supported SoCs (BLE 5.x): BK7231N/BK7236 (BLE 5.1), BK7238/BK7252N/BK7253
-(BLE 5.2), and any future BLE-5.x SoC. Capability is detected at compile time,
-not by a chip list: the C++ guards on `__has_include("ble_api.h")` — the Beken
-BLE 5.x public API header, which the LibreTiny beken-72xx builder ships only
-for BLE-5.x SoCs. BK7231T/BK7251/BK7271 (BLE 4.2) and BK7231Q (no BLE) fail
-with a clear #error.
+(BLE 5.2), and any future BLE-5.x SoC. Known non-5.x families are rejected in
+to_code; unknown families are capability-checked at compile time via
+`__has_include("app_ble.h")`, a header only on the BLE 5.x include path
+(ble_api.h ships for every SoC, so it cannot be the probe). A non-5.x build
+fails with a clear #error.

 No framework patch is needed: the LibreTiny beken-72xx builder already compiles
 and links the BLE 5.x stack (CFG_SUPPORT_BLE=1 + CFG_BLE_VERSION=BLE_VERSION_5_x;
@@ -21,9 +21,16 @@ import logging

 import esphome.codegen as cg
 from esphome.components import libretiny
-from esphome.components.libretiny.const import FAMILY_BK7231N, FAMILY_BK7238
+from esphome.components.libretiny.const import (
+    FAMILY_BK7231N,
+    FAMILY_BK7231Q,
+    FAMILY_BK7231T,
+    FAMILY_BK7238,
+    FAMILY_BK7251,
+)
 import esphome.config_validation as cv
 from esphome.const import CONF_ENABLE_ON_BOOT, CONF_ID
+from esphome.core import EsphomeError
 from esphome.types import ConfigType

 DEPENDENCIES = ["bk72xx"]
@@ -50,7 +57,31 @@ CONFIG_SCHEMA = cv.Schema(
 request_scan_listener_slot = cg.slot_counter("BK72XX_BLE_SCAN_LISTENER_COUNT")


+def _unsupported_family_message(family: str) -> str | None:
+    if family in (FAMILY_BK7231T, FAMILY_BK7251):
+        return (
+            f"bk72xx_ble does not support {family}: this SoC has the Beken BLE 4.2 "
+            "stack; a BLE 5.x SoC such as BK7231N or BK7238 is required"
+        )
+    if family == FAMILY_BK7231Q:
+        return "bk72xx_ble does not support BK7231Q: this SoC has no BLE"
+    return None
+
+
+def _final_validate(config: ConfigType) -> None:
+    # Warn only: a hard error here would break the validate-only CI fixtures,
+    # which run on a BLE 4.2 board. The hard error is raised at codegen.
+    if msg := _unsupported_family_message(libretiny.get_libretiny_family()):
+        _LOGGER.warning("%s (this configuration cannot compile)", msg)
+
+
+FINAL_VALIDATE_SCHEMA = _final_validate
+
+
 async def to_code(config: ConfigType) -> None:
+    if msg := _unsupported_family_message(libretiny.get_libretiny_family()):
+        raise EsphomeError(msg)
+
    var = cg.new_Pvariable(config[CONF_ID])
    await cg.register_component(var, config)

@@ -10,7 +10,7 @@
 #ifdef USE_BK72XX_BLE

 // Same SDK gate as bk72xx_ble.cpp (which carries the explanatory #error).
-#if !defined(CLANG_TIDY) && __has_include("ble_api.h")
+#if !defined(CLANG_TIDY) && __has_include("ble_api.h") && __has_include("app_ble.h")

 extern "C" {
 #include "app_ble.h"     // app_ble_env, app_ble_run, app_ble_reset, actv_state_t,
@@ -115,5 +115,5 @@ BdkOpResult bdk_scan_release(uint8_t activity_idx, bool created, int *err_out) {

 }  // namespace esphome::bk72xx_ble

-#endif  // !CLANG_TIDY && ble_api.h
+#endif  // !CLANG_TIDY && ble_api.h && app_ble.h
 #endif  // USE_BK72XX_BLE
@@ -34,22 +34,26 @@

 // ---------------------------------------------------------------------------
 // SDK-capability gate (not a chip allowlist).
-// This component drives the Beken BLE *5.x* controller via its public API,
-// `ble_api.h`, which the LibreTiny beken-72xx builder ships only for the
-// BLE-5.x SoCs (it selects the `ble_pub` 5.x stack from CFG_BLE_VERSION; the
-// 4.2 SoCs build a different, older API with no ble_api.h). Gate on the header
-// itself so any BLE-5.x Beken chip — present or future — is supported without a
-// hard-coded list, and a non-5.x build fails here with a clear message instead
-// of a cryptic "ble_api.h: No such file or directory".
+// This component drives the Beken BLE *5.x* controller. `ble_api.h` cannot be
+// the probe: it ships for every SoC (driver/include) and merely switches on
+// CFG_BLE_VERSION internally. `app_ble.h` is on the include path only when the
+// LibreTiny beken-72xx builder selects a 5.x stack, so gating on it supports
+// any BLE-5.x chip — present or future — without a hard-coded list, and a
+// non-5.x build fails here with a clear message instead of a cryptic
+// "app_ble.h: No such file or directory".
 // ---------------------------------------------------------------------------
 #if defined(CLANG_TIDY)
 // The clang-tidy environment does not carry the full Beken BDK BLE 5.x API
 // (its ble_api.h variant lacks parts of the 5.x surface), so there is nothing
 // accurate to analyze the SDK calls against — skip the file under analysis.
 #define BK72XX_BLE_NO_SDK
-#elif !__has_include("ble_api.h")
+#elif !__has_include("ble_api.h") || !__has_include("app_ble.h")
+// Also skip the SDK body: #error does not stop the preprocessor, and on a 4.2
+// SoC ble_api.h exists, so without the guard the 5.x symbols would fail one by
+// one and bury this message.
+#define BK72XX_BLE_NO_SDK
 #error \
-    "bk72xx_ble requires a BLE 5.x Beken SDK (ble_api.h). Supported SoCs: BK7231N/BK7236 (BLE 5.1) and BK7238/BK7252N/BK7253 (BLE 5.2). BK7231T/BK7251/BK7271 (BLE 4.2) and BK7231Q (no BLE) are not supported."
+    "bk72xx_ble requires a BLE 5.x Beken SDK (app_ble.h). Supported SoCs: BK7231N/BK7236 (BLE 5.1) and BK7238/BK7252N/BK7253 (BLE 5.2). BK7231T/BK7251/BK7271 (BLE 4.2) and BK7231Q (no BLE) are not supported."
 #endif

 #ifndef BK72XX_BLE_NO_SDK
@@ -1,8 +1,23 @@
+from collections.abc import Callable
+import functools
+from typing import Any
+
 from esphome import automation
 from esphome.automation import maybe_simple_id
 import esphome.codegen as cg
-from esphome.components import esp32_ble, esp32_ble_client, esp32_ble_tracker
-from esphome.components.esp32_ble import BTLoggers
+from esphome.components import ble_device_base, bluetooth_connection
+from esphome.components.ble_device_base import (
+    BT_UUID16_FORMAT as bt_uuid16_format,
+    BT_UUID32_FORMAT as bt_uuid32_format,
+    BT_UUID128_FORMAT as bt_uuid128_format,
+    as_hex,
+    as_reversed_hex_array,
+    bt_uuid,
+)
+from esphome.config_helpers import (
+    filter_source_files_from_platform,
+    frameworks_for_platforms,
+)
 import esphome.config_validation as cv
 from esphome.const import (
    CONF_CHARACTERISTIC_UUID,
@@ -15,13 +30,53 @@ from esphome.const import (
    CONF_SERVICE_UUID,
    CONF_TRIGGER_ID,
    CONF_VALUE,
+    PLATFORM_ESP32,
+    PlatformFramework,
 )
-from esphome.core import ID
+from esphome.core import CORE, ID
+from esphome.enum import StrEnum
+from esphome.schema_extractors import SCHEMA_EXTRACT, schema_extractor
 from esphome.types import ConfigType

-AUTO_LOAD = ["esp32_ble_client"]
+# The esp32 BLE stack (esp32_ble, esp32_ble_tracker) is imported lazily inside
+# the esp32 schema/codegen arms: importing those modules registers esp32-only
+# automations as a side effect, which must not leak into the neutral
+# platforms' registries (the bluetooth_proxy pattern).
+
+
+def _legacy_engine() -> bool:
+    """True when the build uses the legacy raw-gattc engine - one line to
+    flip when esp32 moves to the neutral engine (with
+    USE_BLE_CLIENT_LEGACY_ENGINE in _to_code_esp32)."""
+    return CORE.is_esp32
+
+
+def AUTO_LOAD() -> list[str]:
+    """The engine's closure per platform: the legacy esp32 engine builds on
+    esp32_ble_client plus bluetooth_connection (the shared service-table
+    materializer; its sources compile empty in builds without a neutral
+    node), the neutral engine on the bluetooth_connection backend. The
+    platform-less arm is the union for manifest-resolving tooling."""
+    if _legacy_engine() or CORE.target_platform is None:
+        return ["bluetooth_connection", "esp32_ble_client"]
+    return ["bluetooth_connection"]
+
+
 CODEOWNERS = ["@buxtronix", "@clydebarrow"]
-DEPENDENCIES = ["esp32_ble_tracker"]
+
+FILTER_SOURCE_FILES = filter_source_files_from_platform(
+    {
+        "ble_client.cpp": {
+            PlatformFramework.ESP32_ARDUINO,
+            PlatformFramework.ESP32_IDF,
+        },
+        # Every framework of every non-esp32 registry platform: a platform
+        # that validates the neutral arm must also compile the neutral engine.
+        "ble_client_gatt.cpp": frameworks_for_platforms(
+            set(bluetooth_connection.GATT_CLIENT_PLATFORMS) - {PLATFORM_ESP32}
+        ),
+    }
+)

 CONF_DESCRIPTOR_UUID = "descriptor_uuid"
 CONF_ON_NOTIFY = "on_notify"
@@ -58,7 +113,9 @@ def notify_from_on_notify(config: ConfigType) -> ConfigType:


 ble_client_ns = cg.esphome_ns.namespace("ble_client")
-BLEClient = ble_client_ns.class_("BLEClient", esp32_ble_client.BLEClientBase)
+# One codegen class for both engines: the exclusively-gated headers resolve
+# the name to exactly one C++ definition per build.
+BLEClient = ble_client_ns.class_("BLEClient", cg.Component)
 BLEClientNode = ble_client_ns.class_("BLEClientNode")
 BLEClientNodeConstRef = BLEClientNode.operator("ref").operator("const")
 # Triggers
@@ -105,62 +162,179 @@ CONF_AUTO_CONNECT = "auto_connect"

 MULTI_CONF = True

-CONFIG_SCHEMA = cv.All(
-    cv.Schema(
-        {
-            cv.GenerateID(): cv.declare_id(BLEClient),
-            cv.Required(CONF_MAC_ADDRESS): cv.mac_address,
-            cv.Optional(CONF_NAME): cv.string,
-            cv.Optional(CONF_AUTO_CONNECT, default=True): cv.boolean,
-            cv.Optional(CONF_ON_CONNECT): automation.validate_automation(
-                {
-                    cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
-                        BLEClientConnectTrigger
-                    ),
-                }
-            ),
-            cv.Optional(CONF_ON_DISCONNECT): automation.validate_automation(
-                {
-                    cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
-                        BLEClientDisconnectTrigger
-                    ),
-                }
-            ),
-            cv.Optional(CONF_ON_PASSKEY_REQUEST): automation.validate_automation(
-                {
-                    cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
-                        BLEClientPasskeyRequestTrigger
-                    ),
-                }
-            ),
-            cv.Optional(CONF_ON_PASSKEY_NOTIFICATION): automation.validate_automation(
-                {
-                    cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
-                        BLEClientPasskeyNotificationTrigger
-                    ),
-                }
-            ),
-            cv.Optional(
-                CONF_ON_NUMERIC_COMPARISON_REQUEST
-            ): automation.validate_automation(
-                {
-                    cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
-                        BLEClientNumericComparisonRequestTrigger
-                    ),
-                }
-            ),
-        }
+# Keys shared by both engines' schemas.
+_COMMON_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(): cv.declare_id(BLEClient),
+        cv.Required(CONF_MAC_ADDRESS): cv.mac_address,
+        cv.Optional(CONF_AUTO_CONNECT, default=True): cv.boolean,
+        cv.Optional(CONF_ON_CONNECT): automation.validate_automation(
+            {
+                cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(BLEClientConnectTrigger),
+            }
+        ),
+        cv.Optional(CONF_ON_DISCONNECT): automation.validate_automation(
+            {
+                cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
+                    BLEClientDisconnectTrigger
+                ),
+            }
+        ),
+    }
+).extend(cv.COMPONENT_SCHEMA)
+
+
+@functools.cache
+def _esp32_config_schema() -> cv.All:
+    """The legacy engine's schema, byte-compatible with what esp32 always had
+    (including the Bluedroid security triggers)."""
+    from esphome.components import esp32_ble_tracker
+
+    return cv.All(
+        _COMMON_SCHEMA.extend(
+            {
+                # Accepted-but-unused legacy key; not propagated to the
+                # neutral schema.
+                cv.Optional(CONF_NAME): cv.string,
+                cv.Optional(CONF_ON_PASSKEY_REQUEST): automation.validate_automation(
+                    {
+                        cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
+                            BLEClientPasskeyRequestTrigger
+                        ),
+                    }
+                ),
+                cv.Optional(
+                    CONF_ON_PASSKEY_NOTIFICATION
+                ): automation.validate_automation(
+                    {
+                        cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
+                            BLEClientPasskeyNotificationTrigger
+                        ),
+                    }
+                ),
+                cv.Optional(
+                    CONF_ON_NUMERIC_COMPARISON_REQUEST
+                ): automation.validate_automation(
+                    {
+                        cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(
+                            BLEClientNumericComparisonRequestTrigger
+                        ),
+                    }
+                ),
+            }
+        ).extend(esp32_ble_tracker.ESP_BLE_DEVICE_SCHEMA),
+        bluetooth_connection.consume_gatt_slot("ble_client"),
    )
-    .extend(cv.COMPONENT_SCHEMA)
-    .extend(esp32_ble_tracker.ESP_BLE_DEVICE_SCHEMA),
-    esp32_ble.consume_connection_slots(1, "ble_client"),
-)
+
+
+@functools.cache
+def _gatt_config_schema(platform: str) -> cv.All:
+    """The neutral engine's schema: the shared keys plus the hub reference
+    (parsed-advertisement sightings) and the GATT backend declaration.
+    Keyed by platform - the backend fragment differs per platform."""
+    return cv.All(
+        _COMMON_SCHEMA.extend(ble_device_base.BLE_DEVICE_SCHEMA).extend(
+            bluetooth_connection.gatt_client_schema(platform)
+        ),
+        bluetooth_connection.consume_gatt_slot("ble_client"),
+    )
+
+
+@schema_extractor("schema")
+def _validate_platform(config: ConfigType) -> ConfigType:
+    if config is SCHEMA_EXTRACT:
+        # Deliberate gap (the bluetooth_proxy pattern): the dumper gets only
+        # this shape, so the neutral arm's ble_hub_id is absent from editor
+        # schemas and the esp32-only keys are advertised on every platform.
+        # The language-schema dumper runs without a platform; expose the
+        # esp32 (legacy-engine) shape.
+        return _esp32_config_schema()
+    if _legacy_engine():
+        return _esp32_config_schema()(config)
+    if CORE.target_platform in bluetooth_connection.GATT_CLIENT_PLATFORMS:
+        return _gatt_config_schema(CORE.target_platform)(config)
+    raise cv.Invalid(f"ble_client is not supported on {CORE.target_platform}")
+
+
+CONFIG_SCHEMA = _validate_platform

 CONF_BLE_CLIENT_ID = "ble_client_id"

+
+class BLEClientFeatures(StrEnum):
+    """Per-platform engine capabilities consumers declare against."""
+
+    # The platform-neutral node interface (on_connected/table + completion
+    # callbacks) - every platform with a ble_client engine.
+    GATT_NODE = "gatt_node"
+    # The raw esp32 GATT client event stream (gattc/gap handlers,
+    # node_state) - the legacy engine only.
+    RAW_GATTC = "raw_gattc"
+    # Pairing dialog replies and bond management (Bluedroid GAP/SMP).
+    SECURITY = "security"
+
+
+def _engine_features() -> set[BLEClientFeatures]:
+    """Features the validated platform's engine provides."""
+    if _legacy_engine():
+        return {
+            BLEClientFeatures.GATT_NODE,
+            BLEClientFeatures.RAW_GATTC,
+            BLEClientFeatures.SECURITY,
+        }
+    if CORE.target_platform in bluetooth_connection.GATT_CLIENT_PLATFORMS:
+        return {BLEClientFeatures.GATT_NODE}
+    return set()
+
+
+def requires_feature(
+    feature: BLEClientFeatures, description: str
+) -> Callable[[Any], Any]:
+    """Validator gating a consumer to platforms whose engine provides
+    `feature`, naming the missing capability in the error."""
+
+    def validator(value: Any) -> Any:
+        features = _engine_features()
+        if feature not in features:
+            available = (
+                f"; this platform's engine provides: {', '.join(sorted(features))}"
+                if features
+                else ""
+            )
+            raise cv.Invalid(
+                f"{description} requires the ble_client '{feature}' feature, "
+                f"which {CORE.target_platform} does not provide{available}"
+            )
+        return value
+
+    return validator
+
+
+# The one choke point for every node component still on the raw esp32 event
+# stream; migrating to the neutral interface (NODE_BLE_CLIENT_SCHEMA +
+# register_gatt_node) lifts it.
+_legacy_engine_only = requires_feature(
+    BLEClientFeatures.RAW_GATTC,
+    "This component drives the raw ESP32 GATT client events and has not "
+    "been migrated to the platform-neutral node interface yet; it",
+)
+
 BLE_CLIENT_SCHEMA = cv.Schema(
    {
-        cv.GenerateID(CONF_BLE_CLIENT_ID): cv.use_id(BLEClient),
+        cv.GenerateID(CONF_BLE_CLIENT_ID): cv.All(
+            cv.use_id(BLEClient), _legacy_engine_only
+        ),
+    }
+)
+
+# For node components on the neutral interface: valid wherever ble_client
+# itself is.
+NODE_BLE_CLIENT_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(CONF_BLE_CLIENT_ID): cv.All(
+            cv.use_id(BLEClient),
+            requires_feature(BLEClientFeatures.GATT_NODE, "This component"),
+        ),
    }
 )

@@ -170,11 +344,31 @@ async def register_ble_node(var, config):
    cg.add(parent.register_ble_node(var))


+def _request_gatt_node_build() -> None:
+    """Node storage and the one define meaning "the neutral node surface is
+    compiled in", plus the esp32 bridge/materializer defines."""
+    _request_node_slot()
+    cg.add_define("USE_BLE_CLIENT_GATT_NODES")
+    if _legacy_engine():
+        # Deliberately not ble_device_base.request_gatt_client(): that would
+        # claim a phantom backend slot on combined proxy builds.
+        cg.add_define("USE_BLE_GATT_CLIENT")
+        cg.add_define("USE_BLE_GATT_BACKEND_BLUEDROID")
+        cg.add_define("USE_BLUEDROID_GATT_SERVICE_TABLE")
+
+
+async def register_gatt_node(var, config):
+    """Register a node on the platform-neutral interface (both engines)."""
+    parent = await cg.get_variable(config[CONF_BLE_CLIENT_ID])
+    _request_gatt_node_build()
+    cg.add(parent.register_gatt_node(var))
+
+
 BLE_WRITE_ACTION_SCHEMA = cv.Schema(
    {
        cv.GenerateID(CONF_ID): cv.use_id(BLEClient),
-        cv.Required(CONF_SERVICE_UUID): esp32_ble_tracker.bt_uuid,
-        cv.Required(CONF_CHARACTERISTIC_UUID): esp32_ble_tracker.bt_uuid,
+        cv.Required(CONF_SERVICE_UUID): bt_uuid,
+        cv.Required(CONF_CHARACTERISTIC_UUID): bt_uuid,
        cv.Required(CONF_VALUE): cv.templatable(cv.ensure_list(cv.hex_uint8_t)),
    }
 )
@@ -185,25 +379,34 @@ BLE_CONNECT_ACTION_SCHEMA = maybe_simple_id(
    }
 )

-BLE_NUMERIC_COMPARISON_REPLY_ACTION_SCHEMA = cv.Schema(
-    {
-        cv.GenerateID(CONF_ID): cv.use_id(BLEClient),
-        cv.Required(CONF_ACCEPT): cv.templatable(cv.boolean),
-    }
+BLE_NUMERIC_COMPARISON_REPLY_ACTION_SCHEMA = cv.All(
+    requires_feature(BLEClientFeatures.SECURITY, "This action"),
+    cv.Schema(
+        {
+            cv.GenerateID(CONF_ID): cv.use_id(BLEClient),
+            cv.Required(CONF_ACCEPT): cv.templatable(cv.boolean),
+        }
+    ),
 )

-BLE_PASSKEY_REPLY_ACTION_SCHEMA = cv.Schema(
-    {
-        cv.GenerateID(CONF_ID): cv.use_id(BLEClient),
-        cv.Required(CONF_PASSKEY): cv.templatable(cv.int_range(min=0, max=999999)),
-    }
+BLE_PASSKEY_REPLY_ACTION_SCHEMA = cv.All(
+    requires_feature(BLEClientFeatures.SECURITY, "This action"),
+    cv.Schema(
+        {
+            cv.GenerateID(CONF_ID): cv.use_id(BLEClient),
+            cv.Required(CONF_PASSKEY): cv.templatable(cv.int_range(min=0, max=999999)),
+        }
+    ),
 )


-BLE_REMOVE_BOND_ACTION_SCHEMA = cv.Schema(
-    {
-        cv.GenerateID(CONF_ID): cv.use_id(BLEClient),
-    }
+BLE_REMOVE_BOND_ACTION_SCHEMA = cv.All(
+    requires_feature(BLEClientFeatures.SECURITY, "This action"),
+    cv.Schema(
+        {
+            cv.GenerateID(CONF_ID): cv.use_id(BLEClient),
+        }
+    ),
 )


@@ -237,6 +440,8 @@ async def ble_connect_to_code(config, action_id, template_arg, args):
 )
 async def ble_write_to_code(config, action_id, template_arg, args):
    parent = await cg.get_variable(config[CONF_ID])
+    # The action registers itself as a neutral node in its constructor.
+    _request_gatt_node_build()
    var = cg.new_Pvariable(action_id, template_arg, parent)

    value = config[CONF_VALUE]
@@ -251,38 +456,20 @@ async def ble_write_to_code(config, action_id, template_arg, args):
        arr = cg.static_const_array(arr_id, cg.ArrayInitializer(*value))
        cg.add(var.set_value_simple(arr, len(value)))

-    if len(config[CONF_SERVICE_UUID]) == len(esp32_ble_tracker.bt_uuid16_format):
-        cg.add(
-            var.set_service_uuid16(esp32_ble_tracker.as_hex(config[CONF_SERVICE_UUID]))
-        )
-    elif len(config[CONF_SERVICE_UUID]) == len(esp32_ble_tracker.bt_uuid32_format):
-        cg.add(
-            var.set_service_uuid32(esp32_ble_tracker.as_hex(config[CONF_SERVICE_UUID]))
-        )
-    elif len(config[CONF_SERVICE_UUID]) == len(esp32_ble_tracker.bt_uuid128_format):
-        uuid128 = esp32_ble_tracker.as_reversed_hex_array(config[CONF_SERVICE_UUID])
+    if len(config[CONF_SERVICE_UUID]) == len(bt_uuid16_format):
+        cg.add(var.set_service_uuid16(as_hex(config[CONF_SERVICE_UUID])))
+    elif len(config[CONF_SERVICE_UUID]) == len(bt_uuid32_format):
+        cg.add(var.set_service_uuid32(as_hex(config[CONF_SERVICE_UUID])))
+    elif len(config[CONF_SERVICE_UUID]) == len(bt_uuid128_format):
+        uuid128 = as_reversed_hex_array(config[CONF_SERVICE_UUID])
        cg.add(var.set_service_uuid128(uuid128))

-    if len(config[CONF_CHARACTERISTIC_UUID]) == len(esp32_ble_tracker.bt_uuid16_format):
-        cg.add(
-            var.set_char_uuid16(
-                esp32_ble_tracker.as_hex(config[CONF_CHARACTERISTIC_UUID])
-            )
-        )
-    elif len(config[CONF_CHARACTERISTIC_UUID]) == len(
-        esp32_ble_tracker.bt_uuid32_format
-    ):
-        cg.add(
-            var.set_char_uuid32(
-                esp32_ble_tracker.as_hex(config[CONF_CHARACTERISTIC_UUID])
-            )
-        )
-    elif len(config[CONF_CHARACTERISTIC_UUID]) == len(
-        esp32_ble_tracker.bt_uuid128_format
-    ):
-        uuid128 = esp32_ble_tracker.as_reversed_hex_array(
-            config[CONF_CHARACTERISTIC_UUID]
-        )
+    if len(config[CONF_CHARACTERISTIC_UUID]) == len(bt_uuid16_format):
+        cg.add(var.set_char_uuid16(as_hex(config[CONF_CHARACTERISTIC_UUID])))
+    elif len(config[CONF_CHARACTERISTIC_UUID]) == len(bt_uuid32_format):
+        cg.add(var.set_char_uuid32(as_hex(config[CONF_CHARACTERISTIC_UUID])))
+    elif len(config[CONF_CHARACTERISTIC_UUID]) == len(bt_uuid128_format):
+        uuid128 = as_reversed_hex_array(config[CONF_CHARACTERISTIC_UUID])
        cg.add(var.set_char_uuid128(uuid128))

    return var
@@ -339,14 +526,45 @@ async def remove_bond_to_code(config, action_id, template_arg, args):
    return cg.new_Pvariable(action_id, template_arg, parent)


-async def to_code(config):
+async def _to_code_esp32(config: ConfigType) -> cg.MockObj:
+    from esphome.components import esp32_ble, esp32_ble_tracker
+    from esphome.components.esp32_ble import BTLoggers
+
    # Register the loggers this component needs
    esp32_ble.register_bt_logger(BTLoggers.GATT, BTLoggers.SMP)
    cg.add_define("USE_ESP32_BLE_UUID")
+    cg.add_define("USE_BLE_CLIENT_LEGACY_ENGINE")

    var = cg.new_Pvariable(config[CONF_ID])
    await cg.register_component(var, config)
    await esp32_ble_tracker.register_client(var, config)
+    return var
+
+
+# Sizes the neutral client's node storage; the client itself requests a
+# baseline slot so the define exists on every build that compiles the engine.
+_request_node_slot = cg.slot_counter("ESPHOME_BLE_CLIENT_MAX_NODES")
+
+
+async def _to_code_gatt(config: ConfigType) -> cg.MockObj:
+    # The engine always carries the node surface (the client itself owns the
+    # baseline slot).
+    _request_gatt_node_build()
+    backend = await bluetooth_connection.new_gatt_backend(config)
+    var = cg.new_Pvariable(config[CONF_ID])
+    await cg.register_component(var, config)
+    cg.add(var.set_backend(backend))
+    # Sighting-gated connects: the client listens for the peer's parsed
+    # advertisements through the hub.
+    await ble_device_base.register_ble_device(var, config)
+    return var
+
+
+async def to_code(config: ConfigType) -> None:
+    if _legacy_engine():
+        var = await _to_code_esp32(config)
+    else:
+        var = await _to_code_gatt(config)
    cg.add(var.set_address(config[CONF_MAC_ADDRESS].as_hex))
    cg.add(var.set_auto_connect(config[CONF_AUTO_CONNECT]))
    for conf in config.get(CONF_ON_CONNECT, []):
@@ -1,11 +0,0 @@
-#ifdef USE_ESP32
-
-#include "automation.h"
-
-namespace esphome::ble_client {
-
-const char *const Automation::TAG = "ble_client.automation";
-
-}  // namespace esphome::ble_client
-
-#endif
@@ -1,27 +1,14 @@
 #pragma once

-#ifdef USE_ESP32
+#include "esphome/core/defines.h"

-#include <utility>
-#include <vector>
+#ifdef USE_BLE_CLIENT_LEGACY_ENGINE

 #include "esphome/core/automation.h"
 #include "esphome/components/ble_client/ble_client.h"
-#include "esphome/core/helpers.h"
-#include "esphome/core/log.h"
-
-// Maximum bytes to log in hex format for BLE writes (many logging buffers are 256 chars)
-static constexpr size_t BLE_WRITE_MAX_LOG_BYTES = 64;

 namespace esphome::ble_client {

-// placeholder class for static TAG .
-class Automation {
- public:
-  // could be made inline with C++17
-  static const char *const TAG;
-};
-
 // implement on_connect automation.
 class BLEClientConnectTrigger final : public Trigger<>, public BLEClientNode {
 public:
@@ -93,144 +80,6 @@ class BLEClientNumericComparisonRequestTrigger final : public Trigger<uint32_t>,
  }
 };

-// implement the ble_client.ble_write action.
-template<typename... Ts> class BLEClientWriteAction final : public Action<Ts...>, public BLEClientNode {
- public:
-  BLEClientWriteAction(BLEClient *ble_client) {
-    ble_client->register_ble_node(this);
-    ble_client_ = ble_client;
-  }
-
-  void set_service_uuid16(uint16_t uuid) { this->service_uuid_ = espbt::ESPBTUUID::from_uint16(uuid); }
-  void set_service_uuid32(uint32_t uuid) { this->service_uuid_ = espbt::ESPBTUUID::from_uint32(uuid); }
-  void set_service_uuid128(uint8_t *uuid) { this->service_uuid_ = espbt::ESPBTUUID::from_raw(uuid); }
-
-  void set_char_uuid16(uint16_t uuid) { this->char_uuid_ = espbt::ESPBTUUID::from_uint16(uuid); }
-  void set_char_uuid32(uint32_t uuid) { this->char_uuid_ = espbt::ESPBTUUID::from_uint32(uuid); }
-  void set_char_uuid128(uint8_t *uuid) { this->char_uuid_ = espbt::ESPBTUUID::from_raw(uuid); }
-
-  void set_value_template(std::vector<uint8_t> (*func)(Ts...)) {
-    this->value_.func = func;
-    this->len_ = -1;  // Sentinel value indicates template mode
-  }
-
-  // Store pointer to static data in flash (no RAM copy)
-  void set_value_simple(const uint8_t *data, size_t len) {
-    this->value_.data = data;
-    this->len_ = len;  // Length >= 0 indicates static mode
-  }
-
-  void play(const Ts &...x) override {}
-
-  void play_complex(const Ts &...x) override {
-    this->num_running_++;
-    this->var_ = std::make_tuple(x...);
-
-    bool result;
-    if (this->len_ >= 0) {
-      // Static mode: write directly from flash pointer
-      result = this->write(this->value_.data, this->len_);
-    } else {
-      // Template mode: call function and write the vector
-      std::vector<uint8_t> value = this->value_.func(x...);
-      result = this->write(value);
-    }
-
-    // on write failure, continue the automation chain rather than stopping so that e.g. disconnect can work.
-    if (!result)
-      this->play_next_(x...);
-  }
-
-  /**
-   * Note about logging: the esph_log_X macros are used here because the CI checks complain about use of the ESP LOG
-   * macros in header files (Can't even write it in a comment!)
-   * Not sure why, because they seem to work just fine.
-   * The problem is that the implementation of a templated class can't be placed in a .cpp file when using C++ less than
-   * 17, so the methods have to be here.  The esph_log_X macros are equivalent in function, but don't trigger the CI
-   * errors.
-   */
-  // initiate the write. Return true if all went well, will be followed by a WRITE_CHAR event.
-  bool write(const uint8_t *data, size_t len) {
-    if (this->node_state != espbt::ClientState::ESTABLISHED) {
-      esph_log_w(Automation::TAG, "Cannot write to BLE characteristic - not connected");
-      return false;
-    }
-#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_VERY_VERBOSE
-    char hex_buf[format_hex_pretty_size(BLE_WRITE_MAX_LOG_BYTES)];
-    esph_log_vv(Automation::TAG, "Will write %d bytes: %s", len, format_hex_pretty_to(hex_buf, data, len));
-#endif
-    esp_err_t err =
-        esp_ble_gattc_write_char(this->parent()->get_gattc_if(), this->parent()->get_conn_id(), this->char_handle_, len,
-                                 const_cast<uint8_t *>(data), this->write_type_, ESP_GATT_AUTH_REQ_NONE);
-    if (err != ESP_OK) {
-      esph_log_e(Automation::TAG, "Error writing to characteristic: %s!", esp_err_to_name(err));
-      return false;
-    }
-    return true;
-  }
-
-  bool write(const std::vector<uint8_t> &value) { return this->write(value.data(), value.size()); }
-
-  void gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
-                           esp_ble_gattc_cb_param_t *param) override {
-    switch (event) {
-      case ESP_GATTC_WRITE_CHAR_EVT:
-        // upstream code checked the MAC address, verify the characteristic.
-        if (param->write.handle == this->char_handle_)
-          this->parent()->run_later([this]() { this->play_next_tuple_(this->var_); });
-        break;
-      case ESP_GATTC_DISCONNECT_EVT:
-        if (this->num_running_ != 0)
-          this->stop_complex();
-        break;
-      case ESP_GATTC_SEARCH_CMPL_EVT: {
-        auto *chr = this->parent()->get_characteristic(this->service_uuid_, this->char_uuid_);
-        if (chr == nullptr) {
-          char char_buf[esp32_ble::UUID_STR_LEN];
-          char service_buf[esp32_ble::UUID_STR_LEN];
-          esph_log_w("ble_write_action", "Characteristic %s was not found in service %s",
-                     this->char_uuid_.to_str(char_buf), this->service_uuid_.to_str(service_buf));
-          break;
-        }
-        this->char_handle_ = chr->handle;
-        this->char_props_ = chr->properties;
-        if (this->char_props_ & ESP_GATT_CHAR_PROP_BIT_WRITE) {
-          this->write_type_ = ESP_GATT_WRITE_TYPE_RSP;
-          esph_log_d(Automation::TAG, "Write type: ESP_GATT_WRITE_TYPE_RSP");
-        } else if (this->char_props_ & ESP_GATT_CHAR_PROP_BIT_WRITE_NR) {
-          this->write_type_ = ESP_GATT_WRITE_TYPE_NO_RSP;
-          esph_log_d(Automation::TAG, "Write type: ESP_GATT_WRITE_TYPE_NO_RSP");
-        } else {
-          char char_buf[esp32_ble::UUID_STR_LEN];
-          esph_log_e(Automation::TAG, "Characteristic %s does not allow writing", this->char_uuid_.to_str(char_buf));
-          break;
-        }
-        this->node_state = espbt::ClientState::ESTABLISHED;
-        char char_buf[esp32_ble::UUID_STR_LEN];
-        esph_log_d(Automation::TAG, "Found characteristic %s on device %s", this->char_uuid_.to_str(char_buf),
-                   ble_client_->address_str());
-        break;
-      }
-      default:
-        break;
-    }
-  }
-
- private:
-  BLEClient *ble_client_;
-  ssize_t len_{-1};  // -1 = template mode, >=0 = static mode with length
-  union Value {
-    std::vector<uint8_t> (*func)(Ts...);  // Function pointer (stateless lambdas)
-    const uint8_t *data;                  // Pointer to static data in flash
-  } value_;
-  espbt::ESPBTUUID service_uuid_;
-  espbt::ESPBTUUID char_uuid_;
-  std::tuple<Ts...> var_{};
-  uint16_t char_handle_{};
-  esp_gatt_char_prop_t char_props_{};
-  esp_gatt_write_type_t write_type_{};
-};
-
 template<typename... Ts> class BLEClientPasskeyReplyAction final : public Action<Ts...> {
 public:
  BLEClientPasskeyReplyAction(BLEClient *ble_client) { parent_ = ble_client; }
@@ -0,0 +1,118 @@
+// Neutral twins of the shared ble_client automations. Class names, namespace,
+// and codegen-visible signatures are IDENTICAL to automation.h so generated
+// main.cpp compiles against whichever engine the build gates in; only the
+// internals differ (client callbacks and the neutral node interface instead
+// of raw gattc events). The Bluedroid-security automations (passkey, numeric
+// comparison, remove bond) have no neutral equivalent and stay esp32-only.
+
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#if defined(USE_BLE_GATT_CLIENT) && !defined(USE_BLE_CLIENT_LEGACY_ENGINE)
+
+#include <tuple>
+
+#include "ble_client_gatt.h"
+#include "esphome/core/automation.h"
+
+namespace esphome::ble_client {
+
+class BLEClientConnectTrigger final : public Trigger<> {
+ public:
+  explicit BLEClientConnectTrigger(BLEClient *parent) {
+    parent->add_on_connect_callback([this]() { this->trigger(); });
+  }
+};
+
+class BLEClientDisconnectTrigger final : public Trigger<> {
+ public:
+  explicit BLEClientDisconnectTrigger(BLEClient *parent) {
+    // Fires only after a completed connection (never for failed attempts),
+    // matching the legacy CLOSE_EVT semantics.
+    parent->add_on_disconnect_callback([this]() { this->trigger(); });
+  }
+};
+
+template<typename... Ts> class BLEClientConnectAction final : public Action<Ts...> {
+ public:
+  BLEClientConnectAction(BLEClient *ble_client) {
+    ble_client_ = ble_client;
+    ble_client->add_on_connect_callback([this]() {
+      if (this->num_running_ != 0)
+        this->play_next_tuple_(this->var_);
+    });
+    // A connect attempt that dies (or a later disconnect) terminates the
+    // chain, mirroring the legacy DISCONNECT_EVT handling.
+    ble_client->add_on_connect_failed_callback([this]() {
+      if (this->num_running_ != 0)
+        this->stop_complex();
+    });
+    ble_client->add_on_disconnect_callback([this]() {
+      if (this->num_running_ != 0)
+        this->stop_complex();
+    });
+  }
+
+  // not used since we override play_complex_
+  void play(const Ts &...x) override {}
+
+  void play_complex(const Ts &...x) override {
+    // it makes no sense to have multiple instances of this running at the
+    // same time; cancel a re-trigger while still running.
+    if (this->num_running_ != 0) {
+      this->stop_complex();
+      return;
+    }
+    this->num_running_++;
+    if (this->ble_client_->connected()) {
+      this->play_next_(x...);
+    } else {
+      this->var_ = std::make_tuple(x...);
+      // No-op while already connecting; the callback resolves the wait.
+      this->ble_client_->connect();
+    }
+  }
+
+ private:
+  BLEClient *ble_client_;
+  std::tuple<Ts...> var_{};
+};
+
+template<typename... Ts> class BLEClientDisconnectAction final : public Action<Ts...> {
+ public:
+  BLEClientDisconnectAction(BLEClient *ble_client) {
+    ble_client_ = ble_client;
+    // Both terminal outcomes resolve the wait: a completed teardown and a
+    // connect attempt that died on the way down.
+    ble_client->add_on_disconnect_callback([this]() {
+      if (this->num_running_ != 0)
+        this->play_next_tuple_(this->var_);
+    });
+    ble_client->add_on_connect_failed_callback([this]() {
+      if (this->num_running_ != 0)
+        this->play_next_tuple_(this->var_);
+    });
+  }
+
+  // not used since we override play_complex_
+  void play(const Ts &...x) override {}
+
+  void play_complex(const Ts &...x) override {
+    this->num_running_++;
+    if (this->ble_client_->idle()) {
+      this->play_next_(x...);
+    } else {
+      this->var_ = std::make_tuple(x...);
+      this->ble_client_->disconnect();
+    }
+  }
+
+ private:
+  BLEClient *ble_client_;
+  std::tuple<Ts...> var_{};
+};
+
+}  // namespace esphome::ble_client
+
+#endif  // USE_BLE_GATT_CLIENT && !USE_BLE_CLIENT_LEGACY_ENGINE
@@ -2,10 +2,16 @@
 #include "esphome/components/esp32_ble_client/ble_client_base.h"
 #include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
 #include "esphome/core/application.h"
+#include "esphome/core/hal.h"
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"

-#ifdef USE_ESP32
+#ifdef USE_BLE_CLIENT_LEGACY_ENGINE
+
+#ifdef USE_BLE_CLIENT_GATT_NODES
+#include "esphome/components/bluetooth_connection/bluetooth_connection.h"
+#include "esphome/components/bluetooth_connection/gatt_service_table_bluedroid.h"
+#endif

 namespace esphome::ble_client {

@@ -30,6 +36,10 @@ void BLEClient::dump_config() {
 bool BLEClient::parse_device(const espbt::ESPBTDevice &device) {
  if (!this->enabled)
    return false;
+#ifdef USE_BLE_CLIENT_GATT_NODES
+  if (device.address_uint64() == this->address_ && this->gatt_backoff_.holding_off())
+    return false;
+#endif
  return BLEClientBase::parse_device(device);
 }

@@ -40,24 +50,60 @@ void BLEClient::set_enabled(bool enabled) {
  if (!enabled) {
    ESP_LOGI(TAG, "[%s] Disabling BLE client.", this->address_str());
    this->disconnect();
+    return;
  }
+#ifdef USE_BLE_CLIENT_GATT_NODES
+  // A re-enable clears the backoff (neutral-engine parity).
+  this->gatt_backoff_.reset();
+#endif
 }

 bool BLEClient::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t esp_gattc_if,
                                    esp_ble_gattc_cb_param_t *param) {
+#ifdef USE_BLE_CLIENT_GATT_NODES
+  // Bridge-initiated registrations bypass the base's REG_FOR_NOTIFY handling:
+  // its automatic CCCD write would double the node's own.
+  // Handle-keyed: mixed legacy/neutral subscriptions to one characteristic
+  // are unsupported during the migration window.
+  if (event == ESP_GATTC_REG_FOR_NOTIFY_EVT && esp_gattc_if == this->gattc_if_ &&
+      this->take_pending_gatt_reg_(param->reg_for_notify.handle)) {
+    if (this->pending_notify_regs_ > 0)
+      this->pending_notify_regs_--;
+    int err = param->reg_for_notify.status == ESP_GATT_OK ? 0 : param->reg_for_notify.status;
+    this->notify_state_to_gatt_nodes_(param->reg_for_notify.handle, true, err);
+    // A retiring last registration must still release the cache.
+    this->maybe_release_services_();
+    return true;
+  }
+#endif
  if (!BLEClientBase::gattc_event_handler(event, esp_gattc_if, param))
    return false;

+#ifdef USE_BLE_CLIENT_GATT_NODES
+  // Before the legacy fan-out so gatt nodes resolve before any trigger fires.
+  if (!this->gatt_nodes_.empty()) {
+    if (event == ESP_GATTC_SEARCH_CMPL_EVT) {
+      // A failed discovery tears the link down; the on_connect trigger must
+      // not fire into the teardown.
+      if (!this->handle_gatt_search_cmpl_(param->search_cmpl.status))
+        return true;
+    } else {
+      this->dispatch_gatt_event_(event, param);
+    }
+  }
+#endif
  for (auto *node : this->nodes_)
    node->gattc_event_handler(event, esp_gattc_if, param);
+  this->maybe_release_services_();
+  return true;
+}

+void BLEClient::maybe_release_services_() {
  // The release frees the GATT cache that BLEClientBase's CCCD lookup still needs.
-  // The last REG_FOR_NOTIFY event clears the counter before node dispatch, so the release still runs here.
  if (!this->services_.empty() && !this->notify_registration_pending() && this->all_nodes_established_()) {
    this->release_services();
    ESP_LOGD(TAG, "All clients established, services released");
  }
-  return true;
 }

 void BLEClient::gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) {
@@ -65,10 +111,19 @@ void BLEClient::gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_p

  for (auto *node : this->nodes_)
    node->gap_event_handler(event, param);
+#ifdef USE_BLE_CLIENT_GATT_NODES
+  if (event == ESP_GAP_BLE_AUTH_CMPL_EVT && this->check_addr(param->ble_security.auth_cmpl.bd_addr)) {
+    int status = param->ble_security.auth_cmpl.success ? 0 : param->ble_security.auth_cmpl.fail_reason;
+    for (auto *node : this->gatt_nodes_)
+      node->on_pairing_result(status);
+  }
+#endif
 }

 void BLEClient::set_state(espbt::ClientState state) {
  BLEClientBase::set_state(state);
+  // ESTABLISHED never flows through here; gatt nodes are promoted after the
+  // on_connected fan-out.
  for (auto &node : nodes_)
    node->node_state = state;
 }
@@ -83,6 +138,218 @@ bool BLEClient::all_nodes_established_() {
  return true;
 }

+#ifdef USE_BLE_CLIENT_GATT_NODES
+
+void BLEClient::register_gatt_node(BLEClientNode *node) {
+  // Parent before the capacity check so a dropped node still has a usable
+  // parent() (neutral-engine parity).
+  node->set_ble_client_parent(this);
+  if (this->gatt_nodes_.size() == ESPHOME_BLE_CLIENT_MAX_NODES) {
+    // push_back past capacity is a silent no-op; an undersized slot count
+    // must be loud at boot, not an unresolvable node at runtime.
+    ESP_LOGE(TAG, "[%s] Node capacity exceeded; node dropped", this->address_str());
+    this->status_set_error(LOG_STR("node capacity exceeded"));
+    return;
+  }
+  this->gatt_nodes_.push_back(node);
+  // nodes_ covers the shared state bookkeeping; gatt_nodes_ is the neutral
+  // fan-out subset.
+  this->register_ble_node(node);
+}
+
+int BLEClient::find_pending_gatt_reg_(uint16_t handle) const {
+  for (uint8_t i = 0; i < this->pending_gatt_reg_count_; i++) {
+    if (this->pending_gatt_regs_[i] == handle)
+      return i;
+  }
+  return -1;
+}
+
+bool BLEClient::take_pending_gatt_reg_(uint16_t handle) {
+  int i = this->find_pending_gatt_reg_(handle);
+  if (i < 0)
+    return false;
+  // No duplicates (notify_characteristic refuses a re-push); swap-with-last.
+  this->pending_gatt_regs_[i] = this->pending_gatt_regs_[--this->pending_gatt_reg_count_];
+  return true;
+}
+
+void BLEClient::notify_state_to_gatt_nodes_(uint16_t handle, bool enabled, int error) {
+  if (error != 0) {
+    ESP_LOGW(TAG, "[%s] Notify %s on handle 0x%04x failed, status=%d", this->address_str(),
+             enabled ? "enable" : "disable", handle, error);
+  }
+  for (auto *node : this->gatt_nodes_)
+    node->on_notify_state(handle, enabled, error);
+}
+
+void BLEClient::dispatch_gatt_event_(esp_gattc_cb_event_t event, esp_ble_gattc_cb_param_t *param) {
+  switch (event) {
+    case ESP_GATTC_READ_CHAR_EVT:
+    case ESP_GATTC_READ_DESCR_EVT: {
+      bool ok = param->read.status == ESP_GATT_OK;
+      if (!ok) {
+        // Breadcrumb even when no node claims the handle.
+        ESP_LOGD(TAG, "[%s] Read on handle 0x%04x completed with status %d", this->address_str(), param->read.handle,
+                 param->read.status);
+      }
+      for (auto *node : this->gatt_nodes_) {
+        node->on_read_result(param->read.handle, ok ? param->read.value : nullptr, ok ? param->read.value_len : 0,
+                             ok ? 0 : param->read.status);
+      }
+      break;
+    }
+    case ESP_GATTC_WRITE_CHAR_EVT:
+    case ESP_GATTC_WRITE_DESCR_EVT:
+      if (param->write.status != ESP_GATT_OK) {
+        // Breadcrumb even when no node claims the handle.
+        ESP_LOGD(TAG, "[%s] Write on handle 0x%04x completed with status %d", this->address_str(), param->write.handle,
+                 param->write.status);
+      }
+      for (auto *node : this->gatt_nodes_) {
+        node->on_write_result(param->write.handle, param->write.status == ESP_GATT_OK ? 0 : param->write.status);
+      }
+      break;
+    case ESP_GATTC_NOTIFY_EVT:
+      for (auto *node : this->gatt_nodes_) {
+        node->on_notify(param->notify.handle, param->notify.value, param->notify.value_len);
+      }
+      break;
+    case ESP_GATTC_UNREG_FOR_NOTIFY_EVT:
+      // The base does no CCCD work for unregister; no interception needed.
+      this->notify_state_to_gatt_nodes_(
+          param->unreg_for_notify.handle, false,
+          param->unreg_for_notify.status == ESP_GATT_OK ? 0 : param->unreg_for_notify.status);
+      break;
+    default:
+      break;
+  }
+}
+
+bool BLEClient::handle_gatt_search_cmpl_(esp_gatt_status_t status) {
+  // The base ignores the search status; the neutral contract must not.
+  uint16_t service_total = 0;
+  bool counted = status == ESP_GATT_OK && bluetooth_connection::BluedroidServiceTable::count_services(
+                                              this->gattc_if_, this->conn_id_, &service_total);
+  if (!counted || service_total == 0) {
+    // A failed search poisons the whole discovery, legacy nodes included.
+    ESP_LOGW(TAG, "[%s] Discovery failed (status=%d, services=%u)", this->address_str(), status, service_total);
+    this->gatt_backoff_.register_failure(this->address_str());
+    this->disconnect();
+    return false;
+  }
+  // Stack-owned; nodes copy their handles during on_connected().
+  bluetooth_connection::BluedroidServiceTable table;
+  if (!table.build(this->gattc_if_, this->conn_id_, service_total, this->connection_index_)) {
+    if (!this->has_legacy_nodes_()) {
+      ESP_LOGW(TAG, "[%s] Service table build failed; treating as failed discovery", this->address_str());
+      this->gatt_backoff_.register_failure(this->address_str());
+      this->disconnect();
+      return false;
+    }
+    // Only the table build failed; legacy nodes read the base's services_
+    // and keep the link. Gatt nodes catch the next connection.
+    ESP_LOGW(TAG, "[%s] Service table build failed; gatt nodes skip this connection", this->address_str());
+    this->status_set_warning(LOG_STR("gatt nodes inactive: service table build failed"));
+  } else {
+    this->gatt_connected_ = true;
+    auto view = table.view();
+    for (auto *node : this->gatt_nodes_) {
+      node->on_connected(view);
+      if (this->state() != espbt::ClientState::ESTABLISHED) {
+        // The node tore the link down; remaining nodes get on_disconnected
+        // with no preceding on_connected, so leave a trace of why.
+        ESP_LOGW(TAG, "[%s] A node aborted the connection during setup", this->address_str());
+        return false;
+      }
+    }
+    this->gatt_backoff_.reset();
+    this->status_clear_warning();
+  }
+  // Promote so the legacy release condition can fire.
+  for (auto *node : this->gatt_nodes_)
+    node->node_state = espbt::ClientState::ESTABLISHED;
+  return true;
+}
+
+void BLEClient::on_disconnect_complete(esp_err_t reason) {
+  this->pending_gatt_reg_count_ = 0;
+  if (!this->gatt_connected_)
+    return;  // Never-established links report nothing (neutral parity).
+  this->gatt_connected_ = false;
+  for (auto *node : this->gatt_nodes_)
+    node->on_disconnected();
+}
+
+int BLEClient::check_and_log_error_(const char *operation, esp_err_t err) {
+  if (err != ESP_OK)
+    this->log_gattc_warning_(operation, err);
+  return err;
+}
+
+int BLEClient::write_characteristic(uint16_t handle, const uint8_t *data, uint16_t len, bool response) {
+  if (this->conn_id_ == UNSET_CONN_ID)
+    return ble_device_base::GATT_ERR_NOT_CONNECTED;
+  return this->check_and_log_error_(
+      "esp_ble_gattc_write_char",
+      esp_ble_gattc_write_char(this->gattc_if_, this->conn_id_, handle, len, const_cast<uint8_t *>(data),
+                               response ? ESP_GATT_WRITE_TYPE_RSP : ESP_GATT_WRITE_TYPE_NO_RSP,
+                               ESP_GATT_AUTH_REQ_NONE));
+}
+
+int BLEClient::read_characteristic(uint16_t handle) {
+  if (this->conn_id_ == UNSET_CONN_ID)
+    return ble_device_base::GATT_ERR_NOT_CONNECTED;
+  return this->check_and_log_error_("esp_ble_gattc_read_char", esp_ble_gattc_read_char(this->gattc_if_, this->conn_id_,
+                                                                                       handle, ESP_GATT_AUTH_REQ_NONE));
+}
+
+int BLEClient::read_descriptor(uint16_t handle) {
+  if (this->conn_id_ == UNSET_CONN_ID)
+    return ble_device_base::GATT_ERR_NOT_CONNECTED;
+  return this->check_and_log_error_(
+      "esp_ble_gattc_read_char_descr",
+      esp_ble_gattc_read_char_descr(this->gattc_if_, this->conn_id_, handle, ESP_GATT_AUTH_REQ_NONE));
+}
+
+int BLEClient::write_descriptor(uint16_t handle, const uint8_t *data, uint16_t len) {
+  if (this->conn_id_ == UNSET_CONN_ID)
+    return ble_device_base::GATT_ERR_NOT_CONNECTED;
+  return this->check_and_log_error_(
+      "esp_ble_gattc_write_char_descr",
+      esp_ble_gattc_write_char_descr(this->gattc_if_, this->conn_id_, handle, len, const_cast<uint8_t *>(data),
+                                     ESP_GATT_WRITE_TYPE_RSP, ESP_GATT_AUTH_REQ_NONE));
+}
+
+int BLEClient::notify_characteristic(uint16_t handle, bool enable) {
+  if (this->conn_id_ == UNSET_CONN_ID)
+    return ble_device_base::GATT_ERR_NOT_CONNECTED;
+  if (enable) {
+    if (this->find_pending_gatt_reg_(handle) >= 0) {
+      // ESP_OK: the in-flight registration's completion fans out to all nodes.
+      ESP_LOGW(TAG, "[%s] Notify registration already pending for handle 0x%04x", this->address_str(), handle);
+      return ESP_OK;
+    }
+    if (this->pending_gatt_reg_count_ == MAX_PENDING_NOTIFY_REGS) {
+      // An untracked registration would let the base's auto-CCCD through.
+      ESP_LOGE(TAG, "[%s] Too many pending notify registrations", this->address_str());
+      return ble_device_base::GATT_ERR_NO_MEMORY;
+    }
+    // The base helper's pending count holds the service-release until the
+    // (intercepted) completion.
+    esp_err_t err = this->register_for_notify(handle);
+    if (err == ESP_OK)
+      this->pending_gatt_regs_[this->pending_gatt_reg_count_++] = handle;
+    return this->check_and_log_error_("esp_ble_gattc_register_for_notify", err);
+  }
+  return this->check_and_log_error_("esp_ble_gattc_unregister_for_notify",
+                                    esp_ble_gattc_unregister_for_notify(this->gattc_if_, this->remote_bda_, handle));
+}
+
+int BLEClient::unpair() { return bluetooth_connection::unpair_device(this->get_address()); }
+
+#endif  // USE_BLE_CLIENT_GATT_NODES
+
 }  // namespace esphome::ble_client

 #endif
@@ -1,18 +1,20 @@
 #pragma once

+#include "esphome/core/defines.h"
+
+#ifdef USE_BLE_CLIENT_LEGACY_ENGINE
+
+#include "ble_client_node.h"
+#include "connect_backoff.h"
 #include "esphome/components/esp32_ble_client/ble_client_base.h"
 #include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
 #include "esphome/core/component.h"
 #include "esphome/core/helpers.h"

-#ifdef USE_ESP32
-
 #include <esp_bt_defs.h>
 #include <esp_gap_ble_api.h>
 #include <esp_gatt_common_api.h>
 #include <esp_gattc_api.h>
-#include <array>
-#include <string>
 #include <vector>

 namespace esphome::ble_client {
@@ -21,34 +23,6 @@ namespace espbt = esphome::esp32_ble_tracker;

 using namespace esp32_ble_client;

-class BLEClient;
-
-class BLEClientNode {
- public:
-  virtual void gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
-                                   esp_ble_gattc_cb_param_t *param){};
-  virtual void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) {}
-  virtual void loop() {}
-  void set_address(uint64_t address) { address_ = address; }
-  espbt::ESPBTClient *client;
-  // This should be transitioned to Established once the node no longer needs
-  // the services/descriptors/characteristics of the parent client. This will
-  // allow some memory to be freed.
-  // The parent frees the peer's GATT cache once every node reports Established.
-  // Never report Established while an operation that reads that cache is outstanding.
-  // - esp_ble_gattc_register_for_notify() completes asynchronously.
-  // - Register from ESP_GATTC_SEARCH_CMPL_EVT, then set this from ESP_GATTC_REG_FOR_NOTIFY_EVT.
-  // - BLEClientBase::register_for_notify() holds the release until the registration completes.
-  espbt::ClientState node_state;
-
-  BLEClient *parent() { return this->parent_; }
-  void set_ble_client_parent(BLEClient *parent) { this->parent_ = parent; }
-
- protected:
-  BLEClient *parent_;
-  uint64_t address_;
-};
-
 class BLEClient final : public BLEClientBase {
 public:
  void setup() override;
@@ -64,7 +38,6 @@ class BLEClient final : public BLEClientBase {
  void set_enabled(bool enabled);

  void register_ble_node(BLEClientNode *node) {
-    node->client = this;
    node->set_ble_client_parent(this);
    this->nodes_.push_back(node);
  }
@@ -73,10 +46,57 @@ class BLEClient final : public BLEClientBase {

  void set_state(espbt::ClientState state) override;

+#ifdef USE_BLE_CLIENT_GATT_NODES
+  // ---- the neutral node surface (signatures shared with the non-esp32
+  // engine, so nodes on the neutral interface compile against either) ----
+  void register_gatt_node(BLEClientNode *node);
+
+  bool idle() const { return this->state() == espbt::ClientState::IDLE; }
+
+  int write_characteristic(uint16_t handle, const uint8_t *data, uint16_t len, bool response);
+  int read_characteristic(uint16_t handle);
+  int read_descriptor(uint16_t handle);
+  int write_descriptor(uint16_t handle, const uint8_t *data, uint16_t len);
+  /// Local registration only; per the neutral contract the CCCD write is the
+  /// node's job (the legacy auto-CCCD is suppressed for these handles).
+  int notify_characteristic(uint16_t handle, bool enable);
+  // pair() comes from BLEClientBase, matching the neutral engine's.
+  int unpair();
+#endif
+
 protected:
  bool all_nodes_established_();
+  void maybe_release_services_();
+#ifdef USE_BLE_CLIENT_GATT_NODES
+  int check_and_log_error_(const char *operation, esp_err_t err);
+  int find_pending_gatt_reg_(uint16_t handle) const;
+  void notify_state_to_gatt_nodes_(uint16_t handle, bool enabled, int error);
+  void dispatch_gatt_event_(esp_gattc_cb_event_t event, esp_ble_gattc_cb_param_t *param);
+  // False = failed discovery: the link comes down and the caller suppresses
+  // the legacy fan-out.
+  bool handle_gatt_search_cmpl_(esp_gatt_status_t status);
+  bool take_pending_gatt_reg_(uint16_t handle);
+  void on_disconnect_complete(esp_err_t reason) override;
+#endif

  std::vector<BLEClientNode *> nodes_;
+#ifdef USE_BLE_CLIENT_GATT_NODES
+  // Raise if a migrated node needs more concurrent registrations.
+  static constexpr uint8_t MAX_PENDING_NOTIFY_REGS = 4;
+
+  // Nodes on the neutral surface; fed the translated callbacks and
+  // auto-established after the on_connected fan-out. Every gatt node is
+  // also in nodes_ (registration pushes into both).
+  StaticVector<BLEClientNode *, ESPHOME_BLE_CLIENT_MAX_NODES> gatt_nodes_;
+  bool has_legacy_nodes_() const { return this->nodes_.size() > this->gatt_nodes_.size(); }
+  // Reconnect backoff after materializer failures.
+  ConnectBackoff gatt_backoff_;
+  // Bridge-initiated notify registrations awaiting REG_FOR_NOTIFY_EVT.
+  uint16_t pending_gatt_regs_[MAX_PENDING_NOTIFY_REGS];
+  uint8_t pending_gatt_reg_count_{0};
+  // on_connected fan-out started; on_disconnected is owed at teardown.
+  bool gatt_connected_{false};
+#endif
 };

 }  // namespace esphome::ble_client
@@ -0,0 +1,249 @@
+#include "ble_client_gatt.h"
+
+#if defined(USE_BLE_GATT_CLIENT) && !defined(USE_BLE_CLIENT_LEGACY_ENGINE)
+
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+
+namespace esphome::ble_client {
+
+static const char *const TAG = "ble_client";
+
+void BLEClient::register_ble_node(BLEClientNode *node) {
+  node->set_ble_client_parent(this);
+  if (this->nodes_.size() == ESPHOME_BLE_CLIENT_MAX_NODES) {
+    // push_back past capacity is a silent no-op; an undersized slot count
+    // must be loud at boot, not an unresolvable node at runtime.
+    ESP_LOGE(TAG, "[%s] Node capacity exceeded; node dropped", this->address_str_);
+    this->status_set_error(LOG_STR("node capacity exceeded"));
+    return;
+  }
+  this->nodes_.push_back(node);
+}
+
+void BLEClient::set_address(uint64_t address) {
+  this->address_ = address;
+  uint8_t mac[6];
+  ble_device_base::uint64_to_mac_msb_first(address, mac);
+  format_mac_addr_upper(mac, this->address_str_);
+}
+
+void BLEClient::set_enabled(bool enabled) {
+  if (enabled == this->enabled)
+    return;
+  ESP_LOGI(TAG, "[%s] %s", this->address_str_, enabled ? "Enabled" : "Disabled");
+  this->enabled = enabled;
+  if (!enabled) {
+    this->disconnect();
+    return;
+  }
+  // A re-enable clears the backoff; the next sighting connects (legacy
+  // parity: enabling does not itself connect).
+  this->backoff_.reset();
+}
+
+bool BLEClient::parse_device(const ble_device_base::ESPBTDevice &device) {
+  if (device.address_uint64() != this->address_)
+    return false;
+  // The sighting is the source of truth for the address type.
+  this->address_type_ = device.get_address_type();
+  this->address_type_known_ = true;
+  if (!this->enabled || !this->auto_connect_ || this->state_ != State::IDLE)
+    return true;
+  if (this->backoff_.holding_off())
+    return true;
+  this->attempt_connect_();
+  return true;
+}
+
+void BLEClient::connect() {
+  if (this->state_ != State::IDLE) {
+    ESP_LOGD(TAG, "[%s] Connect requested while busy, ignoring", this->address_str_);
+    return;
+  }
+  // An absent peer can inhibit scanning for the backend's full connect
+  // timeout, so this is worth a breadcrumb - but it is a supported action.
+  ESP_LOGI(TAG, "[%s] Connecting on request", this->address_str_);
+  if (!this->address_type_known_) {
+    // Legacy parity: without a sighting the address type defaults to
+    // public, which never matches a random-static peer.
+    ESP_LOGW(TAG, "[%s] No sighting yet; assuming a public address type", this->address_str_);
+  }
+  this->attempt_connect_();
+}
+
+void BLEClient::attempt_connect_() {
+  int err = this->backend_->connect(this->address_, this->address_type_);
+  if (err != 0) {
+    // A refused connect never produces a callback: stay idle, charge the
+    // backoff, and resolve any waiting connect action through the failure
+    // path so its chain terminates.
+    ESP_LOGW(TAG, "[%s] Connect refused, err=%d", this->address_str_, err);
+    this->backoff_.register_failure(this->address_str_);
+    this->defer([this]() { this->connect_failed_callbacks_.call(); });
+    return;
+  }
+  ESP_LOGD(TAG, "[%s] Connecting", this->address_str_);
+  this->state_ = State::CONNECTING;
+}
+
+void BLEClient::disconnect() {
+  if (this->state_ == State::IDLE) {
+    ESP_LOGD(TAG, "[%s] Disconnect requested while idle, ignoring", this->address_str_);
+    return;
+  }
+  // A deliberate teardown's failure report must not feed the backoff.
+  this->cancel_requested_ = true;
+  int err = this->backend_->gatt_disconnect();
+  if (err != 0) {
+    // Refused synchronously: backend and client disagree about the link
+    // state. Warn, then settle through the deliberate-cancel path.
+    ESP_LOGW(TAG, "[%s] Disconnect refused, err=%d; settling locally", this->address_str_, err);
+    this->on_connection_state(false, 0, err);
+  }
+}
+
+void BLEClient::on_connection_state(bool connected, uint16_t mtu, int error) {
+  if (connected) {
+    this->state_ = State::DISCOVERING;
+    int discover_err = this->backend_->discover_services();
+    if (discover_err != 0) {
+      // Synchronous refusal: no discovery completion will follow.
+      ESP_LOGW(TAG, "[%s] Service discovery refused, err=%d", this->address_str_, discover_err);
+      this->backoff_.register_failure(this->address_str_);
+      // Deliberate teardown: its report must not charge the backoff again.
+      this->disconnect();
+    }
+    return;
+  }
+  bool was_connected = this->state_ == State::CONNECTED;
+  bool cancelled = this->cancel_requested_;
+  this->cancel_requested_ = false;
+  this->state_ = State::IDLE;
+  if (was_connected) {
+    ESP_LOGI(TAG, "[%s] Disconnected, status=%d", this->address_str_, error);
+    for (auto *node : this->nodes_) {
+      node->on_disconnected();
+    }
+    // Continuations leave the backend's event-drain stack first.
+    this->defer([this]() { this->disconnect_callbacks_.call(); });
+  } else {
+    if (cancelled) {
+      // status carries the refusal code when the teardown settled
+      // synchronously; 0 on a backend-completed cancel.
+      ESP_LOGD(TAG, "[%s] Connect attempt cancelled, status=%d", this->address_str_, error);
+    } else {
+      ESP_LOGW(TAG, "[%s] Connect failed, status=%d", this->address_str_, error);
+      this->backoff_.register_failure(this->address_str_);
+    }
+    this->defer([this]() { this->connect_failed_callbacks_.call(); });
+  }
+}
+
+void BLEClient::on_service_discovery_done(int error) {
+  if (error != 0) {
+    ESP_LOGW(TAG, "[%s] Service discovery failed, status=%d", this->address_str_, error);
+    this->backoff_.register_failure(this->address_str_);
+    // The teardown is deliberate: do not charge the backoff again for its
+    // connection report.
+    this->disconnect();
+    return;
+  }
+  ble_device_base::GattServiceTable table{};
+  if (!this->nodes_.empty()) {
+    // Materialize only when a node will read it: a client with no nodes
+    // would pay the build/free cycle on every (re)connect for nothing.
+    table = this->backend_->get_service_table();
+    if (table.service_count == 0) {
+      // A failed materialization is indistinguishable from a service-less
+      // peer, and a real GATT peer always exposes at least GAP/GATT: fail
+      // the discovery before CONNECTED so the teardown resolves through
+      // connect_failed, never a spurious on_disconnect.
+      ESP_LOGW(TAG, "[%s] Service table is empty; treating as failed discovery", this->address_str_);
+      this->backend_->release_services();
+      this->backoff_.register_failure(this->address_str_);
+      this->disconnect();
+      return;
+    }
+  }
+  // CONNECTED before the fan-out so nodes may consult connected() from
+  // their own on_connected().
+  this->state_ = State::CONNECTED;
+  for (auto *node : this->nodes_) {
+    node->on_connected(table);
+    if (this->state_ != State::CONNECTED || this->cancel_requested_) {
+      // A node tore the link down mid-fan-out: on_disconnect fires with no
+      // preceding on_connect, so leave a trace of why.
+      ESP_LOGW(TAG, "[%s] A node aborted the connection during setup", this->address_str_);
+      this->backend_->release_services();
+      return;
+    }
+  }
+  this->backend_->release_services();
+  this->backoff_.reset();
+  ESP_LOGI(TAG, "[%s] Connected", this->address_str_);
+  this->defer([this]() { this->connect_callbacks_.call(); });
+}
+
+void BLEClient::on_write_result(uint16_t handle, int error) {
+  if (error != 0) {
+    // Breadcrumb even when no node claims the handle.
+    ESP_LOGD(TAG, "[%s] Write on handle 0x%04x completed with status %d", this->address_str_, handle, error);
+  }
+  for (auto *node : this->nodes_) {
+    node->on_write_result(handle, error);
+  }
+}
+
+void BLEClient::on_read_result(uint16_t handle, const uint8_t *data, uint16_t len, int error) {
+  if (error != 0) {
+    // Breadcrumb even when no node claims the handle.
+    ESP_LOGD(TAG, "[%s] Read on handle 0x%04x completed with status %d", this->address_str_, handle, error);
+  }
+  for (auto *node : this->nodes_) {
+    node->on_read_result(handle, data, len, error);
+  }
+}
+
+void BLEClient::on_notify_data(uint16_t handle, const uint8_t *data, uint16_t len) {
+  // Every node sees every notification and filters by handle (legacy parity).
+  for (auto *node : this->nodes_) {
+    node->on_notify(handle, data, len);
+  }
+}
+
+void BLEClient::on_notify_state(uint16_t handle, bool enabled, int error) {
+  if (error != 0) {
+    ESP_LOGW(TAG, "[%s] Notify %s on handle 0x%04x failed, status=%d", this->address_str_,
+             enabled ? "enable" : "disable", handle, error);
+  }
+  for (auto *node : this->nodes_) {
+    node->on_notify_state(handle, enabled, error);
+  }
+}
+
+void BLEClient::on_pairing_result(int status) {
+  if (status != 0) {
+    ESP_LOGW(TAG, "[%s] Pairing failed, status=%d", this->address_str_, status);
+  } else {
+    ESP_LOGI(TAG, "[%s] Paired", this->address_str_);
+  }
+  for (auto *node : this->nodes_) {
+    node->on_pairing_result(status);
+  }
+}
+
+void BLEClient::dump_config() {
+  ESP_LOGCONFIG(TAG,
+                "BLE Client:\n"
+                "  Address: %s\n"
+                "  Auto connect: %s",
+                this->address_str_, YESNO(this->auto_connect_));
+  if (this->enabled && this->state_ == State::IDLE) {
+    ESP_LOGCONFIG(TAG, "  Waiting for an advertisement from the device");
+  }
+}
+
+}  // namespace esphome::ble_client
+
+#endif  // USE_BLE_GATT_CLIENT && !USE_BLE_CLIENT_LEGACY_ENGINE
@@ -0,0 +1,149 @@
+// Platform-neutral ble_client engine on the ble_device_base GATT contract.
+//
+// Compiled on every platform with a GATT backend except esp32, which keeps
+// the legacy BLEClientBase engine (ble_client.h) until its raw-gattc node
+// family migrates - the exclusive gates make the same class names resolve to
+// exactly one definition per build, so codegen is shared.
+//
+// Connects are sighting-gated like the legacy engine: the client is a parsed
+// advertisement listener, captures the peer's address type from the sighting,
+// and asks the backend to connect only when enabled and idle.
+
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#if defined(USE_BLE_GATT_CLIENT) && !defined(USE_BLE_CLIENT_LEGACY_ENGINE)
+
+#include "ble_client_node.h"
+#include "connect_backoff.h"
+#include "esphome/components/ble_device_base/ble_device.h"
+#include "esphome/components/ble_device_base/ble_gatt_client.h"
+#include "esphome/components/bluetooth_connection/bluetooth_connection.h"
+#include "esphome/components/bluetooth_connection/bluetooth_connection_gatt_backend.h"
+#include "esphome/core/component.h"
+#include "esphome/core/helpers.h"
+
+#include <cstdint>
+#include <functional>
+
+namespace esphome::ble_client {
+
+class BLEClient : public Component,
+                  public ble_device_base::ESPBTDeviceListener,
+                  public ble_device_base::GattClientListener {
+ public:
+  void dump_config() override;
+
+  // Public field for legacy parity (the switch platform republishes it).
+  bool enabled{true};
+
+  void set_backend(ble_device_base::BLEGattConnection *backend) {
+    this->backend_ = backend;
+    backend->set_listener(this);
+  }
+  void set_address(uint64_t address);
+  void set_auto_connect(bool auto_connect) { this->auto_connect_ = auto_connect; }
+  void set_enabled(bool enabled);
+  const char *address_str() const { return this->address_str_; }
+
+  void register_ble_node(BLEClientNode *node);
+  // One registration spelling shared with the esp32 engine's bridge.
+  void register_gatt_node(BLEClientNode *node) { this->register_ble_node(node); }
+
+  bool connected() const { return this->state_ == State::CONNECTED; }
+  bool idle() const { return this->state_ == State::IDLE; }
+
+  /// Action-initiated connect (no sighting needed; uses the last captured
+  /// address type, public until a sighting arrives). No-op unless idle.
+  void connect();
+  void disconnect();
+
+  /// Legacy-named deferral used by the automation twins: neutral listener
+  /// callbacks run inside the backend's event drain, so automation chain
+  /// continuations must leave that stack first.
+  void run_later(std::function<void()> &&f) { this->defer(std::move(f)); }  // NOLINT
+
+  // Backend ops for nodes and actions - the frozen node-facing surface.
+  // Only write_characteristic has an in-tree caller; subscribing means
+  // notify_characteristic plus a CCCD write_descriptor (the caller's job
+  // per the contract).
+  int write_characteristic(uint16_t handle, const uint8_t *data, uint16_t len, bool response) {
+    return this->backend_->write_characteristic(handle, data, len, response);
+  }
+  int read_characteristic(uint16_t handle) { return this->backend_->read_characteristic(handle); }
+  int read_descriptor(uint16_t handle) { return this->backend_->read_descriptor(handle); }
+  int write_descriptor(uint16_t handle, const uint8_t *data, uint16_t len) {
+    return this->backend_->write_descriptor(handle, data, len);
+  }
+  int notify_characteristic(uint16_t handle, bool enable) {
+    return this->backend_->notify_characteristic(handle, enable);
+  }
+  int pair() { return this->backend_->pair(); }
+  int unpair() { return bluetooth_connection::unpair_device(this->address_); }
+
+  // Automation callback registration.
+  template<typename F> void add_on_connect_callback(F &&callback) {
+    this->connect_callbacks_.add(std::forward<F>(callback));
+  }
+  template<typename F> void add_on_disconnect_callback(F &&callback) {
+    this->disconnect_callbacks_.add(std::forward<F>(callback));
+  }
+  // Fired when a connect attempt dies before being established; the user
+  // on_disconnect trigger deliberately does NOT fire here (legacy parity).
+  template<typename F> void add_on_connect_failed_callback(F &&callback) {
+    this->connect_failed_callbacks_.add(std::forward<F>(callback));
+  }
+
+  // ---- ble_device_base::ESPBTDeviceListener ----
+  bool parse_device(const ble_device_base::ESPBTDevice &device) override;
+
+  // ---- ble_device_base::GattClientListener ----
+  void on_connection_state(bool connected, uint16_t mtu, int error) override;
+  void on_service_discovery_done(int error) override;
+  void on_read_result(uint16_t handle, const uint8_t *data, uint16_t len, int error) override;
+  void on_write_result(uint16_t handle, int error) override;
+  void on_notify_data(uint16_t handle, const uint8_t *data, uint16_t len) override;
+  void on_notify_state(uint16_t handle, bool enabled, int error) override;
+  void on_pairing_result(int status) override;
+
+ protected:
+  enum class State : uint8_t { IDLE, CONNECTING, DISCOVERING, CONNECTED };
+
+  void attempt_connect_();
+
+  // Group 1: pointers / containers
+  ble_device_base::BLEGattConnection *backend_{nullptr};
+  // Codegen-sized (ESPHOME_BLE_CLIENT_MAX_NODES); filled during setup.
+  StaticVector<BLEClientNode *, ESPHOME_BLE_CLIENT_MAX_NODES> nodes_;
+
+  // Group 2: 8-byte types
+  uint64_t address_{0};
+
+  // Group 3: callback managers (pointer-sized when empty)
+  LazyCallbackManager<void()> connect_callbacks_;
+  LazyCallbackManager<void()> disconnect_callbacks_;
+  LazyCallbackManager<void()> connect_failed_callbacks_;
+
+  // Group 4: 4-byte types
+  // Backoff so an undiscoverable database or a dead peer cannot produce a
+  // battery-draining connect loop.
+  ConnectBackoff backoff_;
+
+  // Group 5: arrays
+  char address_str_[MAC_ADDRESS_PRETTY_BUFFER_SIZE]{};
+
+  // Group 6: 1-byte types
+  State state_{State::IDLE};
+  uint8_t address_type_{0};  // BLE_ADDR_TYPE_*, captured from the sighting
+  // Distinguishes a captured public type from the never-sighted default.
+  bool address_type_known_{false};
+  bool auto_connect_{true};
+  // A user-initiated teardown in flight; its failure report is not a
+  // connect failure and must not feed the backoff.
+  bool cancel_requested_{false};
+};
+
+}  // namespace esphome::ble_client
+
+#endif  // USE_BLE_GATT_CLIENT && !USE_BLE_CLIENT_LEGACY_ENGINE
@@ -0,0 +1,68 @@
+// The single BLEClientNode both ble_client engines share. The neutral
+// callback surface is the one interface node components build on; the raw
+// esp32 surface below it remains for components that have not migrated yet.
+
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#ifdef USE_BLE_GATT_CLIENT
+#include "esphome/components/ble_device_base/ble_gatt_client.h"
+#endif
+#ifdef USE_BLE_CLIENT_LEGACY_ENGINE
+#include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
+
+#include <esp_gap_ble_api.h>
+#include <esp_gattc_api.h>
+#endif
+
+#include <cstdint>
+
+namespace esphome::ble_client {
+
+class BLEClient;
+
+class BLEClientNode {
+ public:
+#ifdef USE_BLE_CLIENT_GATT_NODES
+  // Neutral surface, delivered by both engines. The table is borrowed: copy
+  // handles during on_connected(). All nodes see all completions; filter by
+  // handle.
+  // A node that disconnects from inside on_connected() aborts the fan-out;
+  // the user's on_disconnect may then fire without a preceding on_connect.
+  virtual void on_connected(const ble_device_base::GattServiceTable &table) {}
+  virtual void on_disconnected() {}
+  virtual void on_notify(uint16_t handle, const uint8_t *data, uint16_t len) {}
+  // One in-flight registration per handle; its completion fans out to every
+  // node, so a refused duplicate request still sees on_notify_state.
+  virtual void on_notify_state(uint16_t handle, bool enabled, int error) {}
+  virtual void on_read_result(uint16_t handle, const uint8_t *data, uint16_t len, int error) {}
+  virtual void on_write_result(uint16_t handle, int error) {}
+  virtual void on_pairing_result(int status) {}
+#endif
+#ifdef USE_BLE_CLIENT_LEGACY_ENGINE
+  // Legacy raw surface; components overriding these need the legacy engine
+  // until migrated to the neutral surface above.
+  virtual void gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
+                                   esp_ble_gattc_cb_param_t *param) {}
+  virtual void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) {}
+  virtual void loop() {}
+  // This should be transitioned to Established once the node no longer needs
+  // the services/descriptors/characteristics of the parent client. This will
+  // allow some memory to be freed.
+  // The parent frees the peer's GATT cache once every node reports Established.
+  // Never report Established while an operation that reads that cache is outstanding.
+  // - esp_ble_gattc_register_for_notify() completes asynchronously.
+  // - Register from ESP_GATTC_SEARCH_CMPL_EVT, then set this from ESP_GATTC_REG_FOR_NOTIFY_EVT.
+  // - BLEClientBase::register_for_notify() holds the release until the registration completes.
+  esp32_ble_tracker::ClientState node_state;
+#endif
+
+  BLEClient *parent() const { return this->parent_; }
+  void set_ble_client_parent(BLEClient *parent) { this->parent_ = parent; }
+
+ protected:
+  BLEClient *parent_{nullptr};
+};
+
+}  // namespace esphome::ble_client
@@ -0,0 +1,168 @@
+// The ble_client.ble_write action: a node on the platform-neutral interface,
+// so one implementation serves both engines (the esp32 bridge and the
+// neutral engine).
+
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#ifdef USE_BLE_CLIENT_GATT_NODES
+
+#include <tuple>
+#include <vector>
+
+// One of the two engine headers resolves per build.
+#include "ble_client.h"
+#include "ble_client_gatt.h"
+#include "ble_client_node.h"
+#include "esphome/core/automation.h"
+#include "esphome/core/helpers.h"
+#include "esphome/core/log.h"
+
+namespace esphome::ble_client {
+
+static const char *const BLE_WRITE_TAG = "ble_client.automation";
+
+// Maximum bytes to log in hex format for BLE writes (many logging buffers are 256 chars)
+static constexpr size_t BLE_WRITE_MAX_LOG_BYTES = 64;
+
+template<typename... Ts> class BLEClientWriteAction final : public Action<Ts...>, public BLEClientNode {
+ public:
+  BLEClientWriteAction(BLEClient *ble_client) {
+    ble_client->register_gatt_node(this);
+    ble_client_ = ble_client;
+  }
+
+  void set_service_uuid16(uint16_t uuid) { this->service_uuid_ = ble_device_base::ESPBTUUID::from_uint16(uuid); }
+  void set_service_uuid32(uint32_t uuid) { this->service_uuid_ = ble_device_base::ESPBTUUID::from_uint32(uuid); }
+  void set_service_uuid128(uint8_t *uuid) { this->service_uuid_ = ble_device_base::ESPBTUUID::from_raw(uuid); }
+
+  void set_char_uuid16(uint16_t uuid) { this->char_uuid_ = ble_device_base::ESPBTUUID::from_uint16(uuid); }
+  void set_char_uuid32(uint32_t uuid) { this->char_uuid_ = ble_device_base::ESPBTUUID::from_uint32(uuid); }
+  void set_char_uuid128(uint8_t *uuid) { this->char_uuid_ = ble_device_base::ESPBTUUID::from_raw(uuid); }
+
+  void set_value_template(std::vector<uint8_t> (*func)(Ts...)) {
+    this->value_.func = func;
+    this->len_ = -1;  // Sentinel value indicates template mode
+  }
+
+  // Store pointer to static data in flash (no RAM copy)
+  void set_value_simple(const uint8_t *data, size_t len) {
+    this->value_.data = data;
+    this->len_ = len;  // Length >= 0 indicates static mode
+  }
+
+  void play(const Ts &...x) override {}
+
+  void play_complex(const Ts &...x) override {
+    this->num_running_++;
+    this->var_ = std::make_tuple(x...);
+
+    bool result;
+    if (this->len_ >= 0) {
+      result = this->write(this->value_.data, this->len_);
+    } else {
+      std::vector<uint8_t> value = this->value_.func(x...);
+      result = this->write(value.data(), value.size());
+    }
+
+    // on write failure, continue the automation chain rather than stopping so
+    // that e.g. disconnect can work.
+    if (!result)
+      this->play_next_(x...);
+  }
+
+  // Initiate the write; the completion arrives in on_write_result. The
+  // response-less path can complete synchronously inside the call, so the
+  // handle is armed before the backend is touched.
+  bool write(const uint8_t *data, size_t len) {
+    if (!this->ble_client_->connected()) {
+      esph_log_w(BLE_WRITE_TAG, "Cannot write to BLE characteristic - not connected");
+      return false;
+    }
+    if (!this->resolved_) {
+      esph_log_w(BLE_WRITE_TAG, "Cannot write to BLE characteristic - characteristic was not resolved");
+      return false;
+    }
+#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_VERY_VERBOSE
+    char hex_buf[format_hex_pretty_size(BLE_WRITE_MAX_LOG_BYTES)];
+    esph_log_vv(BLE_WRITE_TAG, "Will write %d bytes: %s", len, format_hex_pretty_to(hex_buf, data, len));
+#endif
+    int err = this->ble_client_->write_characteristic(this->char_handle_, data, len, this->write_response_);
+    if (err != 0) {
+      esph_log_e(BLE_WRITE_TAG, "Error writing to characteristic: %d!", err);
+      return false;
+    }
+    return true;
+  }
+
+  void on_connected(const ble_device_base::GattServiceTable &table) override {
+    const auto *service = ble_device_base::find_service(table, this->service_uuid_);
+    const auto *chr =
+        service == nullptr ? nullptr : ble_device_base::find_characteristic(table, *service, this->char_uuid_);
+    if (chr == nullptr) {
+      char char_buf[ble_device_base::UUID_STR_LEN];
+      char service_buf[ble_device_base::UUID_STR_LEN];
+      esph_log_w(BLE_WRITE_TAG, "Characteristic %s was not found in service %s", this->char_uuid_.to_str(char_buf),
+                 this->service_uuid_.to_str(service_buf));
+      return;
+    }
+    if (chr->properties & ble_device_base::GATT_CHAR_PROP_WRITE) {
+      this->write_response_ = true;
+    } else if (chr->properties & ble_device_base::GATT_CHAR_PROP_WRITE_NO_RSP) {
+      this->write_response_ = false;
+    } else {
+      char char_buf[ble_device_base::UUID_STR_LEN];
+      esph_log_e(BLE_WRITE_TAG, "Characteristic %s does not allow writing", this->char_uuid_.to_str(char_buf));
+      return;
+    }
+    this->char_handle_ = chr->value_handle;
+    this->resolved_ = true;
+    char char_buf[ble_device_base::UUID_STR_LEN];
+    esph_log_d(BLE_WRITE_TAG, "Found characteristic %s on device %s", this->char_uuid_.to_str(char_buf),
+               this->ble_client_->address_str());
+  }
+
+  void on_disconnected() override {
+    this->resolved_ = false;
+    this->char_handle_ = 0;
+    if (this->num_running_ != 0)
+      this->stop_complex();
+  }
+
+  void on_write_result(uint16_t handle, int error) override {
+    if (this->num_running_ == 0) {
+      return;
+    }
+    if (!this->resolved_ || handle != this->char_handle_) {
+      // A parked chain waiting on a completion that never matches would
+      // otherwise stall silently until disconnect.
+      esph_log_d(BLE_WRITE_TAG, "Write result for handle 0x%04x ignored, waiting on 0x%04x", handle,
+                 this->char_handle_);
+      return;
+    }
+    if (error != 0) {
+      // Continue the chain (legacy parity) but leave a breadcrumb.
+      esph_log_w(BLE_WRITE_TAG, "Write completed with status %d", error);
+    }
+    this->ble_client_->run_later([this]() { this->play_next_tuple_(this->var_); });
+  }
+
+ private:
+  BLEClient *ble_client_;
+  ssize_t len_{-1};  // -1 = template mode, >=0 = static mode with length
+  union Value {
+    std::vector<uint8_t> (*func)(Ts...);  // Function pointer (stateless lambdas)
+    const uint8_t *data;                  // Pointer to static data in flash
+  } value_;
+  ble_device_base::ESPBTUUID service_uuid_;
+  ble_device_base::ESPBTUUID char_uuid_;
+  std::tuple<Ts...> var_{};
+  uint16_t char_handle_{};
+  bool write_response_{false};
+  bool resolved_{false};
+};
+
+}  // namespace esphome::ble_client
+
+#endif  // USE_BLE_CLIENT_GATT_NODES
@@ -0,0 +1,43 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#ifdef USE_BLE_GATT_CLIENT
+
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+
+#include <cstdint>
+
+namespace esphome::ble_client {
+
+/// Reconnect backoff after repeated connect/discovery failures, shared by
+/// both engines. 256 ms ticks in a uint16_t keep it 4 bytes; the ~4.7 h tick
+/// wrap can at worst reinstate one stale hold-off of a minute.
+class ConnectBackoff {
+ public:
+  bool holding_off() const {
+    return this->failures_ != 0 && static_cast<uint16_t>(now() - this->start_) < this->failures_ * STEP_TICKS;
+  }
+  void register_failure(const char *address_str) {
+    if (this->failures_ < MAX_STEPS)
+      this->failures_++;
+    this->start_ = now();
+    esph_log_w("ble_client", "[%s] Holding off reconnect for %u s", address_str, this->failures_ * 10u);
+  }
+  void reset() { this->failures_ = 0; }
+
+ private:
+  // ~10 s per consecutive failure, capped so a flapping peer retries within
+  // a minute at worst.
+  static constexpr uint16_t STEP_TICKS = 40;  // x 256 ms
+  static constexpr uint8_t MAX_STEPS = 6;
+  static uint16_t now() { return static_cast<uint16_t>(millis() >> 8); }
+
+  uint16_t start_{0};
+  uint8_t failures_{0};
+};
+
+}  // namespace esphome::ble_client
+
+#endif  // USE_BLE_GATT_CLIENT
@@ -0,0 +1,48 @@
+#include "ble_gatt_client.h"
+
+#ifdef USE_BLE_GATT_CLIENT
+
+#include "esphome/core/log.h"
+
+namespace esphome::ble_device_base {
+
+static const char *const TAG = "ble_gatt_client";
+
+const GattCharacteristic *find_characteristic(const GattServiceTable &table, const GattService &service,
+                                              const ESPBTUUID &uuid) {
+  // 32-bit range math: a corrupt first/count pair cannot wrap past the check.
+  uint32_t end = uint32_t(service.first_characteristic) + service.characteristic_count;
+  if (end > table.characteristic_count) {
+    ESP_LOGW(TAG, "characteristic range out of bounds");
+    return nullptr;
+  }
+  for (uint32_t i = service.first_characteristic; i < end; i++) {
+    if (table.characteristics[i].uuid == uuid)
+      return &table.characteristics[i];
+  }
+  return nullptr;
+}
+
+const GattDescriptor *find_descriptor(const GattServiceTable &table, const GattCharacteristic &characteristic,
+                                      const ESPBTUUID &uuid) {
+  uint32_t end = uint32_t(characteristic.first_descriptor) + characteristic.descriptor_count;
+  if (end > table.descriptor_count) {
+    // Corrupt range, not a missing descriptor.
+    ESP_LOGW(TAG, "descriptor range out of bounds");
+    return nullptr;
+  }
+  for (uint32_t i = characteristic.first_descriptor; i < end; i++) {
+    if (table.descriptors[i].uuid == uuid)
+      return &table.descriptors[i];
+  }
+  return nullptr;
+}
+
+uint16_t find_cccd(const GattServiceTable &table, const GattCharacteristic &characteristic) {
+  const GattDescriptor *desc = find_descriptor(table, characteristic, ESPBTUUID::from_uint16(CCCD_UUID));
+  return desc != nullptr ? desc->handle : 0;
+}
+
+}  // namespace esphome::ble_device_base
+
+#endif  // USE_BLE_GATT_CLIENT
@@ -11,13 +11,16 @@
 // interface. All listener calls are delivered on the ESPHome main loop;
 // borrowed data pointers are valid only for the duration of the call.
 //
-// Error domain (plain int, forwarded to the API without translation):
+// Error domain (plain int, forwarded to the API without translation, so the
+// values are wire-frozen - API clients interpret them):
 //   0            success
-//   1..0x11      ATT error codes (Bluetooth spec; BTstack and Bluedroid agree)
+//   1..0x11      ATT error codes (Bluetooth spec) - reserved; a backend whose
+//                native error codes land in this window must remap them out
 //   GATT_ERR_NOT_CONNECTED (-1)  no connection to the peer (on esp32 a raw
 //                ESP_FAIL from the stack shares this value; both read as a
 //                failed, unusable connection on the client side)
 //   GATT_ERR_NO_MEMORY (-2)      backend storage exhausted
+//   -1..-15      reserved for future contract sentinels
 //   anything else: platform stack error/status code, surfaced opaquely.
 // Connection events carry HCI status/disconnect reason codes (same code
 // space on every controller).
@@ -99,9 +102,18 @@ class GattClientListener {
 // The BLEGattConnection op surface, asserted where the alias binds
 // (bluetooth_connection_gatt_backend.h). Operations return 0 when accepted (completion arrives
 // through the listener) or a synchronous error (busy, not connected, stack
-// rejection); one operation may be outstanding at a time. Semantics beyond
-// the signatures:
+// rejection); one operation may be outstanding at a time. An accepted
+// operation's completion is delivered from the event loop, NEVER
+// synchronously from inside the op call - a synchronous terminal
+// on_connection_state from within gatt_disconnect() would re-enter the
+// consumer mid-teardown. Semantics beyond the signatures:
 // - connect: addr_type is a BLE_ADDR_TYPE_* constant (ble_device.h).
+//   Returning 0 means the request is accepted, not that the radio acted: the
+//   backend owns integration with its platform's scan/connect arbitration
+//   (Bluedroid parks the request for the tracker's promote loop, which owns
+//   scan-stop/coex/one-connect-at-a-time; the rp2 backend opens immediately
+//   and relies on sighting-gated consumers). Consumers must not assume
+//   connect timing.
 // - gatt_disconnect: also cancels a connect in progress (named to coexist
 //   with a platform stack's own void disconnect() on one backend class).
 //   Nonzero means nothing to tear down and no completion will follow; an
@@ -143,6 +155,41 @@ concept BLEGattConnectionContract = requires(T conn, GattClientListener *listene
  { conn.set_connection_type(ConnectionType{}) } -> std::same_as<void>;
 };

+// ---- service table lookup helpers ----
+//
+// Neutral, bounds-checked walks over a materialized GattServiceTable for
+// direct consumers that resolve a known device's handles by UUID (streaming
+// consumers forward the raw database and never need these). Linear search:
+// the table exists only between discovery and release_services(), for one
+// small known device.
+
+/// Client Characteristic Configuration descriptor UUID (Bluetooth spec).
+static constexpr uint16_t CCCD_UUID = 0x2902;
+
+// Characteristic property bits (the Bluetooth-spec declaration byte carried
+// in GattCharacteristic::properties; the ESP-IDF macros for these do not
+// exist on the other platforms).
+static constexpr uint8_t GATT_CHAR_PROP_WRITE_NO_RSP = 0x04;
+static constexpr uint8_t GATT_CHAR_PROP_WRITE = 0x08;
+
+inline const GattService *find_service(const GattServiceTable &table, const ESPBTUUID &uuid) {
+  for (uint16_t i = 0; i < table.service_count; i++) {
+    if (table.services[i].uuid == uuid)
+      return &table.services[i];
+  }
+  return nullptr;
+}
+
+const GattCharacteristic *find_characteristic(const GattServiceTable &table, const GattService &service,
+                                              const ESPBTUUID &uuid);
+
+const GattDescriptor *find_descriptor(const GattServiceTable &table, const GattCharacteristic &characteristic,
+                                      const ESPBTUUID &uuid);
+
+/// Handle of the characteristic's Client Characteristic Configuration
+/// descriptor (0x2902), or 0 when it has none.
+uint16_t find_cccd(const GattServiceTable &table, const GattCharacteristic &characteristic);
+
 }  // namespace esphome::ble_device_base

 #endif  // USE_BLE_GATT_CLIENT
@@ -1,12 +1,14 @@
 """Per-platform GATT connection backends and the helpers to embed one.

-Backends: esp32 Bluedroid, rp2 BTstack. No user-facing configuration; the
-Bluetooth proxy's codegen declares and registers the backend instances
-through gatt_client_schema()/hub_connection_schema() + new_gatt_backend().
+Backends: esp32 Bluedroid, rp2 BTstack. No user-facing configuration; a
+consumer's codegen declares and registers the backend instances — the
+Bluetooth proxy through its per-slot connection wrappers (a streaming
+consumer), and the neutral ble_client through gatt_client_schema() +
+new_gatt_backend().
 """

 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field

 import esphome.codegen as cg
 from esphome.components import rp2040_ble
@@ -23,7 +25,8 @@ from esphome.types import ConfigType
 def AUTO_LOAD() -> list[str]:
    """ble_device_base plus the platform BLE stack the build's backend
    registers with (the Bluedroid header includes the tracker's), so
-    consumers need not know. The platform-less arm serves manifest tooling."""
+    consumers stay platform-blind. The platform-less arm serves tooling that
+    resolves the manifest without a target."""
    if CORE.is_esp32:
        return ["ble_device_base", "esp32_ble_tracker"]
    if CORE.is_rp2:
@@ -63,6 +66,8 @@ DOMAIN = "bluetooth_connection"
@dataclass
 class _ConnectionData:
    rp2_backend_count: int = 0
+    # GATT connection slots claimed this run, for the platform cap check.
+    slot_consumers: list[str] = field(default_factory=list)


 def _get_data() -> _ConnectionData:
@@ -119,6 +124,10 @@ class _PlatformBackend:
    backend_class: cg.MockObjClass
    schema_fragment: Callable[[], cv.Schema]
    register: Callable[[cg.MockObj, ConfigType], Awaitable[None]]
+    # Selects the backend's alias-ladder arm (order-independent arms).
+    define: str
+    # The backend's on-demand materializer gate, when it has one.
+    materializer_define: str | None = None


 # The single registry of platforms with a GATT client backend; a platform
@@ -126,11 +135,20 @@ class _PlatformBackend:
 # platform's arm.
 _PLATFORM_BACKENDS: dict[str, _PlatformBackend] = {
    PLATFORM_ESP32: _PlatformBackend(
-        BluedroidGattClient, _esp32_schema_fragment, _esp32_register
+        BluedroidGattClient,
+        _esp32_schema_fragment,
+        _esp32_register,
+        "USE_BLE_GATT_BACKEND_BLUEDROID",
+        materializer_define="USE_BLUEDROID_GATT_SERVICE_TABLE",
+    ),
+    PLATFORM_RP2: _PlatformBackend(
+        RP2GattClient, _rp2_schema_fragment, _rp2_register, "USE_BLE_GATT_BACKEND_RP2"
    ),
-    PLATFORM_RP2: _PlatformBackend(RP2GattClient, _rp2_schema_fragment, _rp2_register),
 }

+# Gates dedicated-backend consumers (cv.only_on).
+GATT_CLIENT_PLATFORMS = list(_PLATFORM_BACKENDS)
+

 def _backend_entry(platform: str | None = None) -> _PlatformBackend:
    key = platform if platform is not None else CORE.target_platform
@@ -165,21 +183,89 @@ def hub_connection_schema(platform: str | None = None) -> cv.Schema:
    )


-async def new_gatt_backend(config: ConfigType) -> cg.MockObj:
+def consume_gatt_slot(
+    consumer: str, count: int = 1
+) -> Callable[[ConfigType], ConfigType]:
+    """Validator claiming GATT connection slots - the one spelling for every
+    claimant. Platforms whose BLE stack owns a connection budget (esp32, rp2)
+    are charged there and their stack's final validation reports an
+    overcommit; the neutral ledger covers any future backend platform without
+    one (the cap check in FINAL_VALIDATE_SCHEMA)."""
+
+    def validator(config: ConfigType) -> ConfigType:
+        _get_data().slot_consumers.extend([consumer] * count)
+        if CORE.is_esp32:
+            from esphome.components import esp32_ble
+
+            esp32_ble.consume_connection_slots(count, consumer)(config)
+        elif CORE.target_platform == PLATFORM_RP2:
+            rp2040_ble.consume_connection_slots(count, consumer)(config)
+        return config
+
+    return validator
+
+
+# Platforms whose BLE stack owns its own connection budget: consume_gatt_slot
+# charges it there, and the stack's final validation is the one place an
+# overcommit is reported (never two messages for one misconfiguration).
+_STACK_BUDGET_PLATFORMS = {PLATFORM_ESP32, PLATFORM_RP2}
+
+
+def _validate_slot_totals(config: ConfigType) -> ConfigType:
+    # Skipped in testing mode so grouped component builds can co-exist
+    # (mirrors esp32_ble.validate_connection_slots).
+    if CORE.testing_mode:
+        return config
+    if CORE.target_platform in _STACK_BUDGET_PLATFORMS:
+        return config
+    if (cap := HUB_MAX_CONNECTIONS.get(CORE.target_platform)) is None:
+        # Any backend platform without a stack budget must carry a cap here
+        # or fail loudly, never fail open.
+        if CORE.target_platform in _PLATFORM_BACKENDS:
+            raise cv.Invalid(
+                f"{CORE.target_platform} has a GATT backend but no slot cap "
+                "in HUB_MAX_CONNECTIONS"
+            )
+        return config
+    claimed = _get_data().slot_consumers
+    if len(claimed) > cap:
+        raise cv.Invalid(
+            f"{CORE.target_platform} supports at most {cap} GATT client "
+            f"connection(s); {len(claimed)} requested by: {', '.join(claimed)}"
+        )
+    return config
+
+
+FINAL_VALIDATE_SCHEMA = _validate_slot_totals
+
+
+async def new_gatt_backend(
+    config: ConfigType, *, service_table: bool = True
+) -> cg.MockObj:
    """Instantiate the backend declared by gatt_client_schema() and register
    it with its platform stack. The connection slot is claimed at validation
-    (the proxy's slot validators), not here.
+    (the consume_gatt_slot validators), not here.
+
+    service_table is honored by the Bluedroid backend only: forward
+    scaffolding for the first esp32 direct consumer, load-bearing on no
+    current build (rp2 ignores the define and always materializes - its
+    proxy hub streams through get_service_table(), so it must keep the
+    materializer regardless of the flag).
    """
    from esphome.components import ble_device_base

+    entry = _backend_entry()
    ble_device_base.request_gatt_client()
+    cg.add_define(entry.define)
+    if service_table and entry.materializer_define is not None:
+        cg.add_define(entry.materializer_define)
    backend = cg.new_Pvariable(config[CONF_BACKEND_ID])
    # The backend is the slot's real Component: component keys from the
    # connection entry (setup_priority, ...) apply to it. Consumers whose own
    # schema carries keys that register_component would misapply to the
    # backend (e.g. a polling interval) must not put them in this config.
    await cg.register_component(backend, config)
-    await _backend_entry().register(backend, config)
+    await entry.register(backend, config)
    return backend


@@ -187,6 +273,7 @@ async def new_gatt_backend(config: ConfigType) -> cg.MockObj:
 # list (this module cannot import bluetooth_proxy to derive it).
 SOURCE_FILE_FRAMEWORKS: dict[str, set[PlatformFramework]] = {
    "bluetooth_connection_bluedroid.cpp": frameworks_for_platforms([PLATFORM_ESP32]),
+    "gatt_service_table_bluedroid.cpp": frameworks_for_platforms([PLATFORM_ESP32]),
    # Every hub platform the proxy admits (the file compiles empty where
    # USE_BLE_GATT_CLIENT is not defined), so a platform gaining a backend
    # cannot hit a missing-symbol trap here.
@@ -46,7 +46,7 @@ BatchClose close_service_batch(api::BluetoothGATTGetServicesResponse &resp, size

 #endif  // USE_BLUETOOTH_PROXY_CONNECTIONS

-#if defined(USE_ESP32) && defined(USE_BLE_GATT_CLIENT)
+#if defined(USE_ESP32_BLE) && defined(USE_BLE_GATT_CLIENT)
 namespace esphome::bluetooth_connection {

 // Address-scoped Bluedroid maintenance. Gated with the connection surface:
@@ -65,4 +65,4 @@ conn_err_t clear_gatt_cache(uint64_t address) {
 }

 }  // namespace esphome::bluetooth_connection
-#endif  // USE_ESP32 && USE_BLE_GATT_CLIENT
+#endif  // USE_ESP32_BLE && USE_BLE_GATT_CLIENT
@@ -48,15 +48,16 @@ static constexpr conn_err_t CONN_OK = 0;
 // GATT contract so backend and wrapper cannot drift.
 static constexpr conn_err_t GATT_NOT_CONNECTED = ble_device_base::GATT_ERR_NOT_CONNECTED;

-// What the platform's connection backend supports beyond GATT operations;
-// the proxy derives its feature flags and legacy version from these.
-#if defined(USE_ESP32)
+// What the build's connection backend supports beyond GATT operations; the
+// proxy derives its feature flags and legacy version from these. Keyed on
+// the backend define, never the platform, so a second backend on one
+// platform carries its own facts.
+#if defined(USE_BLE_GATT_BACKEND_BLUEDROID)
 static constexpr bool SUPPORTS_PAIRING = true;
 static constexpr bool SUPPORTS_CACHE_CLEARING = true;
-#elif defined(USE_RP2040_BLE) && defined(USE_BLE_GATT_CLIENT)
+#elif defined(USE_BLE_GATT_BACKEND_RP2)
 // The rp2 BTstack backend pairs (just works + bonding); it has no service
-// cache to clear. Keyed on the backend, not the generic client define, so a
-// future backend without pairing keeps the stub arm below.
+// cache to clear.
 static constexpr bool SUPPORTS_PAIRING = true;
 static constexpr bool SUPPORTS_CACHE_CLEARING = false;
 #else
@@ -64,13 +65,14 @@ static constexpr bool SUPPORTS_PAIRING = false;
 static constexpr bool SUPPORTS_CACHE_CLEARING = false;
 #endif

-// Address-scoped (not connection-scoped) maintenance requests.
-#if (defined(USE_ESP32) || defined(USE_RP2040_BLE)) && defined(USE_BLE_GATT_CLIENT)
+// Address-scoped (not connection-scoped) maintenance requests; keyed on the
+// stack (the calls need no backend instance).
+#if (defined(USE_ESP32_BLE) || defined(USE_RP2040_BLE)) && defined(USE_BLE_GATT_CLIENT)
 conn_err_t unpair_device(uint64_t address);
 #else
 inline conn_err_t unpair_device(uint64_t) { return GATT_NOT_CONNECTED; }
 #endif
-#if defined(USE_ESP32) && defined(USE_BLE_GATT_CLIENT)
+#if defined(USE_ESP32_BLE) && defined(USE_BLE_GATT_CLIENT)
 conn_err_t clear_gatt_cache(uint64_t address);
 #else
 inline conn_err_t clear_gatt_cache(uint64_t) { return GATT_NOT_CONNECTED; }
@@ -2,10 +2,11 @@

 #if defined(USE_ESP32_BLE) && defined(USE_BLE_GATT_CLIENT)

+#include "bluetooth_connection.h"
+
 // The in-place streamer serves the proxy's service-discovery API; backend-only
 // builds compile without the proxy headers or the streamer.
 #ifdef USE_BLUETOOTH_PROXY_CONNECTIONS
-#include "bluetooth_connection.h"
 #include "bluetooth_connection_hub.h"

 #include "esphome/components/bluetooth_proxy/bluetooth_proxy.h"
@@ -20,7 +21,7 @@

 namespace esphome::bluetooth_connection {

-static const char *const TAG = "bluetooth_connection.bluedroid";
+static const char *const TAG = "bluetooth_connection";

 using ble_device_base::FAST_CONN_TIMEOUT;
 using ble_device_base::FAST_MAX_CONN_INTERVAL;
@@ -300,6 +301,9 @@ int BluedroidGattClient::update_connection_params(uint16_t min_interval, uint16_

 void BluedroidGattClient::release_services() {
  this->service_total_ = 0;
+#ifdef USE_BLUEDROID_GATT_SERVICE_TABLE
+  this->table_.free();
+#endif
  // Always set: terminates any in-flight stream on every cache config.
  this->services_released_ = true;
 #ifndef CONFIG_BT_GATTC_CACHE_NVS_FLASH
@@ -312,6 +316,24 @@ void BluedroidGattClient::release_services() {
 #endif
 }

+#ifdef USE_BLUEDROID_GATT_SERVICE_TABLE
+ble_device_base::GattServiceTable BluedroidGattClient::get_service_table() {
+  // Lifetime: every teardown path (CLOSE_EVT, the safety timeout, stack-down,
+  // passive DISCONNECT) routes through release_services(), so a materialized
+  // table cannot outlive its link.
+  if (this->table_.empty() &&
+      (this->services_released_ || this->service_total_ == 0 ||
+       !this->table_.build(this->gattc_if_, this->conn_id_, this->service_total_, this->connection_index_))) {
+    // Released / no services / failed build all collapse to empty; the
+    // build failures warned above, log the quiet two.
+    ESP_LOGD(TAG, "[%d] No service table (released=%d, services=%u)", this->connection_index_, this->services_released_,
+             this->service_total_);
+    return {};
+  }
+  return this->table_.view();
+}
+#endif  // USE_BLUEDROID_GATT_SERVICE_TABLE
+
 // ---- internals ----

 bool BluedroidGattClient::check_addr_(const esp_bd_addr_t &addr) const {
@@ -358,6 +380,11 @@ void BluedroidGattClient::log_gattc_warning_(const char *operation, int code) {
 // ---- service streaming ----

 int BluedroidGattClient::handle_search_cmpl_(esp_gatt_status_t status) {
+#ifdef USE_BLUEDROID_GATT_SERVICE_TABLE
+  // Re-discovery moves the counts the table view derives offsets from; free
+  // the stale table.
+  this->table_.free();
+#endif
  // Step down from the fast discovery params.
  this->update_conn_params_(MEDIUM_MIN_CONN_INTERVAL, MEDIUM_MAX_CONN_INTERVAL, 0, MEDIUM_CONN_TIMEOUT, "medium");
  if (status != ESP_GATT_OK) {
@@ -11,6 +11,9 @@

 #if defined(USE_ESP32_BLE) && defined(USE_BLE_GATT_CLIENT)

+#include "bluetooth_connection.h"
+#include "gatt_service_table_bluedroid.h"
+
 #include "esphome/components/ble_device_base/ble_gatt_client.h"
 #include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
 #include "esphome/core/component.h"
@@ -72,11 +75,16 @@ class BluedroidGattClient final : public esp32_ble_tracker::ESPBTClient, public
  int notify_characteristic(uint16_t handle, bool enable);
  int pair();
  int update_connection_params(uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout);
-  // Contract stub: the proxy streams in place; the on-demand materializer
-  // for direct consumers lands with #18205. NOTE: a direct consumer reaching
-  // this stub gets an empty table indistinguishable from a service-less
-  // peer - do not ship one against this backend before the materializer.
+  // On-demand table for direct consumers; the proxy streams instead, so the
+  // materializer compiles only under USE_BLUEDROID_GATT_SERVICE_TABLE (emitted by
+  // direct-consumer codegen, never by the proxy).
+#ifdef USE_BLUEDROID_GATT_SERVICE_TABLE
+  ble_device_base::GattServiceTable get_service_table();
+#else
+  // A direct consumer reaching this stub misconfigured its codegen
+  // (service_table=False): the empty table reads as a service-less peer.
  ble_device_base::GattServiceTable get_service_table() { return {}; }
+#endif
  void release_services();

 #ifdef USE_BLUETOOTH_PROXY_CONNECTIONS
@@ -105,6 +113,9 @@ class BluedroidGattClient final : public esp32_ble_tracker::ESPBTClient, public

  // Group 1: pointers / composed objects
  ble_device_base::GattClientListener *listener_{nullptr};
+#ifdef USE_BLUEDROID_GATT_SERVICE_TABLE
+  BluedroidServiceTable table_;
+#endif
  // Group 2: 4-byte types
  uint32_t disconnecting_started_{0};

@@ -12,10 +12,12 @@

 #include "esphome/components/ble_device_base/ble_gatt_client.h"

-#if defined(USE_RP2040_BLE)
+// Arms are keyed on codegen-emitted per-backend defines (_PLATFORM_BACKENDS
+// in __init__.py), so they are order-independent.
+#if defined(USE_BLE_GATT_BACKEND_RP2)
 #include "bluetooth_connection_rp2.h"
 #define ESPHOME_BLE_GATT_CONNECTION_TYPE bluetooth_connection::RP2GattClient
-#elif defined(USE_ESP32_BLE)
+#elif defined(USE_BLE_GATT_BACKEND_BLUEDROID)
 #include "bluetooth_connection_bluedroid.h"
 #define ESPHOME_BLE_GATT_CONNECTION_TYPE bluetooth_connection::BluedroidGattClient
 #elif defined(USE_BLE_GATT_CLIENT_STUB_BACKEND)
@@ -15,7 +15,7 @@

 namespace esphome::bluetooth_connection {

-static const char *const TAG = "bluetooth_connection.rp2";
+static const char *const TAG = "bluetooth_connection";

 using ble_device_base::ESPBTUUID;
 using ble_device_base::GATT_ERR_NOT_CONNECTED;
@@ -0,0 +1,198 @@
+#include "gatt_service_table_bluedroid.h"
+
+#if defined(USE_ESP32_BLE) && defined(USE_BLE_GATT_CLIENT) && defined(USE_BLUEDROID_GATT_SERVICE_TABLE)
+
+#include "esphome/core/log.h"
+
+namespace esphome::bluetooth_connection {
+
+static const char *const TAG = "gatt_service_table";
+
+// A stack that never reports end-of-range would otherwise walk forever.
+static constexpr uint16_t MAX_DESCRIPTORS_PER_CHARACTERISTIC = 64;
+
+// Shared enumeration for both build passes: an identical walk order is what
+// lets the counting pass size the block the filling pass fills.
+// INVALID_OFFSET/NOT_FOUND mean end-of-range; anything else is a failure.
+template<typename ServiceFn, typename CharFn, typename DescFn>
+bool BluedroidServiceTable::walk_(ServiceFn &&on_service, CharFn &&on_char, DescFn &&on_desc) {
+  for (uint16_t s = 0; s < this->service_total_; s++) {
+    esp_gattc_service_elem_t svc;
+    uint16_t svc_count = 1;
+    auto svc_status = esp_ble_gattc_get_service(this->gattc_if_, this->conn_id_, nullptr, &svc, &svc_count, s);
+    if (svc_status != ESP_GATT_OK || svc_count == 0) {
+      this->log_walk_warning_("esp_ble_gattc_get_service", svc_status);
+      return false;
+    }
+    if (!on_service(s, svc)) {
+      return false;
+    }
+    uint16_t svc_chars = 0;
+    auto count_status = esp_ble_gattc_get_attr_count(this->gattc_if_, this->conn_id_, ESP_GATT_DB_CHARACTERISTIC,
+                                                     svc.start_handle, svc.end_handle, 0, &svc_chars);
+    if (count_status != ESP_GATT_OK) {
+      this->log_walk_warning_("esp_ble_gattc_get_attr_count", count_status);
+      return false;
+    }
+    for (uint16_t c = 0; c < svc_chars; c++) {
+      esp_gattc_char_elem_t chr;
+      uint16_t char_count = 1;
+      auto status = esp_ble_gattc_get_all_char(this->gattc_if_, this->conn_id_, svc.start_handle, svc.end_handle, &chr,
+                                               &char_count, c);
+      if (status != ESP_GATT_OK || char_count == 0) {
+        // An early terminator contradicts svc_chars from the same cache;
+        // never build a silently truncated table.
+        this->log_walk_warning_("esp_ble_gattc_get_all_char", status);
+        return false;
+      }
+      if (!on_char(svc, chr)) {
+        return false;
+      }
+      for (uint16_t d = 0;; d++) {
+        if (d == MAX_DESCRIPTORS_PER_CHARACTERISTIC) {
+          // A stack that never reports end-of-range; fail like every other
+          // inconsistency instead of truncating the table silently.
+          ESP_LOGW(TAG, "[%d] Descriptor walk exceeded %u entries", this->log_index_,
+                   MAX_DESCRIPTORS_PER_CHARACTERISTIC);
+          return false;
+        }
+        esp_gattc_descr_elem_t desc;
+        uint16_t desc_count = 1;
+        auto desc_status =
+            esp_ble_gattc_get_all_descr(this->gattc_if_, this->conn_id_, chr.char_handle, &desc, &desc_count, d);
+        if (desc_status == ESP_GATT_INVALID_OFFSET || desc_status == ESP_GATT_NOT_FOUND) {
+          break;
+        }
+        if (desc_status != ESP_GATT_OK || desc_count == 0) {
+          this->log_walk_warning_("esp_ble_gattc_get_all_descr", desc_status);
+          return false;
+        }
+        if (!on_desc(chr, desc)) {
+          return false;
+        }
+      }
+    }
+  }
+  return true;
+}
+
+bool BluedroidServiceTable::count_services(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t *total) {
+  uint16_t primary = 0;
+  uint16_t secondary = 0;
+  if (esp_ble_gattc_get_attr_count(gattc_if, conn_id, ESP_GATT_DB_PRIMARY_SERVICE, 0x0001, 0xFFFF, 0, &primary) !=
+          ESP_GATT_OK ||
+      esp_ble_gattc_get_attr_count(gattc_if, conn_id, ESP_GATT_DB_SECONDARY_SERVICE, 0x0001, 0xFFFF, 0, &secondary) !=
+          ESP_GATT_OK) {
+    // A failed count must not read as an authoritative empty database.
+    return false;
+  }
+  *total = primary + secondary;
+  return true;
+}
+
+bool BluedroidServiceTable::build(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t service_total, uint8_t log_index) {
+  this->free();
+  this->gattc_if_ = gattc_if;
+  this->conn_id_ = conn_id;
+  this->service_total_ = service_total;
+  this->log_index_ = log_index;
+
+  // Pass 1: count, so one exact-size block holds the whole table.
+  uint16_t char_total = 0;
+  uint16_t desc_total = 0;
+  bool counted = this->walk_([](uint16_t, const esp_gattc_service_elem_t &) { return true; },
+                             [&](const esp_gattc_service_elem_t &, const esp_gattc_char_elem_t &) {
+                               char_total++;
+                               return true;
+                             },
+                             [&](const esp_gattc_char_elem_t &, const esp_gattc_descr_elem_t &) {
+                               desc_total++;
+                               return true;
+                             });
+  if (!counted) {
+    ESP_LOGW(TAG, "[%d] Service table walk failed during count", this->log_index_);
+    this->free();
+    return false;
+  }
+
+  // The arrays share one block; carving stays aligned because each struct's
+  // strictest member is the UUID and array sizes are multiples of it.
+  static_assert(alignof(ble_device_base::GattService) >= alignof(ble_device_base::GattCharacteristic) &&
+                alignof(ble_device_base::GattCharacteristic) >= alignof(ble_device_base::GattDescriptor));
+  size_t svc_bytes = this->service_total_ * sizeof(ble_device_base::GattService);
+  size_t char_bytes = char_total * sizeof(ble_device_base::GattCharacteristic);
+  size_t total_bytes = svc_bytes + char_bytes + desc_total * sizeof(ble_device_base::GattDescriptor);
+  RAMAllocator<uint8_t> allocator(RAMAllocator<uint8_t>::ALLOC_INTERNAL);
+  this->storage_ = allocator.allocate(total_bytes);
+  if (this->storage_ == nullptr) {
+    ESP_LOGW(TAG, "[%d] Service table allocation failed (%u bytes)", this->log_index_,
+             static_cast<unsigned>(total_bytes));
+    this->free();
+    return false;
+  }
+  auto *services = reinterpret_cast<ble_device_base::GattService *>(this->storage_);
+  auto *characteristics = reinterpret_cast<ble_device_base::GattCharacteristic *>(this->storage_ + svc_bytes);
+  auto *descriptors = reinterpret_cast<ble_device_base::GattDescriptor *>(this->storage_ + svc_bytes + char_bytes);
+
+  // Pass 2: fill, bounded by the pass-1 totals. A bound trip or a shortfall
+  // means the cached database changed between the passes; fail the build
+  // rather than serve an inconsistent table (the consumer retries).
+  uint16_t char_index = 0;
+  uint16_t desc_index = 0;
+  ble_device_base::GattService *cur_service = nullptr;
+  ble_device_base::GattCharacteristic *cur_char = nullptr;
+  bool filled = this->walk_(
+      [&](uint16_t s, const esp_gattc_service_elem_t &svc) {
+        cur_service = &services[s];
+        cur_service->uuid = ble_device_base::ESPBTUUID::from_uuid(svc.uuid);
+        cur_service->start_handle = svc.start_handle;
+        cur_service->end_handle = svc.end_handle;
+        cur_service->first_characteristic = char_index;
+        cur_service->characteristic_count = 0;
+        return true;
+      },
+      [&](const esp_gattc_service_elem_t &svc, const esp_gattc_char_elem_t &chr) {
+        if (char_index >= char_total) {
+          return false;
+        }
+        cur_char = &characteristics[char_index++];
+        cur_char->uuid = ble_device_base::ESPBTUUID::from_uuid(chr.uuid);
+        cur_char->value_handle = chr.char_handle;
+        // Bluedroid addresses descriptors by characteristic handle, so the
+        // table's end_handle only needs the service-bounded upper bound.
+        cur_char->end_handle = svc.end_handle;
+        cur_char->properties = chr.properties;
+        cur_char->first_descriptor = desc_index;
+        cur_char->descriptor_count = 0;
+        cur_service->characteristic_count++;
+        return true;
+      },
+      [&](const esp_gattc_char_elem_t &, const esp_gattc_descr_elem_t &desc) {
+        if (desc_index >= desc_total) {
+          return false;
+        }
+        descriptors[desc_index].uuid = ble_device_base::ESPBTUUID::from_uuid(desc.uuid);
+        descriptors[desc_index].handle = desc.handle;
+        desc_index++;
+        cur_char->descriptor_count++;
+        return true;
+      });
+  if (!filled || char_index != char_total || desc_index != desc_total) {
+    // Walk error or the database changed between passes; better an empty
+    // table than a corrupt one.
+    ESP_LOGW(TAG, "[%d] Service table walk mismatch, discarding", this->log_index_);
+    this->free();
+    return false;
+  }
+  this->char_total_ = char_total;
+  this->desc_total_ = desc_total;
+  return true;
+}
+
+void BluedroidServiceTable::log_walk_warning_(const char *operation, int code) {
+  ESP_LOGW(TAG, "[%d] %s failed, status=%d", this->log_index_, operation, code);
+}
+
+}  // namespace esphome::bluetooth_connection
+
+#endif  // USE_ESP32_BLE && USE_BLE_GATT_CLIENT && USE_BLUEDROID_GATT_SERVICE_TABLE
@@ -0,0 +1,80 @@
+// Owning two-pass materializer of one Bluedroid GATT database snapshot into
+// the neutral GattServiceTable layout, shared by the BluedroidGattClient
+// backend and ble_client's esp32 engine.
+
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#if defined(USE_ESP32_BLE) && defined(USE_BLE_GATT_CLIENT) && defined(USE_BLUEDROID_GATT_SERVICE_TABLE)
+
+#include "esphome/components/ble_device_base/ble_gatt_client.h"
+#include "esphome/core/helpers.h"
+
+#include <esp_gattc_api.h>
+
+namespace esphome::bluetooth_connection {
+
+class BluedroidServiceTable {
+ public:
+  ~BluedroidServiceTable() { this->free(); }
+  // Owns storage_; a copy would double-free.
+  BluedroidServiceTable() = default;
+  BluedroidServiceTable(const BluedroidServiceTable &) = delete;
+  BluedroidServiceTable &operator=(const BluedroidServiceTable &) = delete;
+
+  /// The service count build() requires: the stack's PRIMARY+SECONDARY
+  /// attribute totals, never the SEARCH_RES event count.
+  static bool count_services(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t *total);
+
+  /// Two-pass build from the stack's cached database (service_total from
+  /// count_services()). log_index labels warnings. Frees any previous table
+  /// first; on failure the table is left empty.
+  bool build(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t service_total, uint8_t log_index);
+
+  // The view is carved from the storage block and the counts on each call
+  // (a cold path) rather than cached, saving a per-instance table member.
+  ble_device_base::GattServiceTable view() const {
+    size_t svc_bytes = this->service_total_ * sizeof(ble_device_base::GattService);
+    size_t char_bytes = this->char_total_ * sizeof(ble_device_base::GattCharacteristic);
+    return {reinterpret_cast<const ble_device_base::GattService *>(this->storage_),
+            reinterpret_cast<const ble_device_base::GattCharacteristic *>(this->storage_ + svc_bytes),
+            reinterpret_cast<const ble_device_base::GattDescriptor *>(this->storage_ + svc_bytes + char_bytes),
+            this->service_total_,
+            this->char_total_,
+            this->desc_total_};
+  }
+
+  // Always resets the counts: a failed build must never leave a non-zero
+  // service_total_ behind a null table.
+  void free() {
+    if (this->storage_ != nullptr) {
+      RAMAllocator<uint8_t> allocator(RAMAllocator<uint8_t>::ALLOC_INTERNAL);
+      allocator.deallocate(this->storage_, 0);
+      this->storage_ = nullptr;
+    }
+    this->service_total_ = 0;
+    this->char_total_ = 0;
+    this->desc_total_ = 0;
+  }
+
+  bool empty() const { return this->storage_ == nullptr; }
+
+ private:
+  template<typename ServiceFn, typename CharFn, typename DescFn>
+  bool walk_(ServiceFn &&on_service, CharFn &&on_char, DescFn &&on_desc);
+  void log_walk_warning_(const char *operation, int code);
+
+  uint8_t *storage_{nullptr};
+  uint16_t service_total_{0};
+  uint16_t char_total_{0};
+  uint16_t desc_total_{0};
+  // Walk context, set by build().
+  uint16_t conn_id_{0};
+  esp_gatt_if_t gattc_if_{};  // uint8_t width
+  uint8_t log_index_{0};
+};
+
+}  // namespace esphome::bluetooth_connection
+
+#endif  // USE_ESP32_BLE && USE_BLE_GATT_CLIENT && USE_BLUEDROID_GATT_SERVICE_TABLE
@@ -98,9 +98,15 @@ def _esp32_config_schema() -> cv.All:
                raise cv.Invalid(
                    "Connections can only be used if the proxy is set to active"
                )
+            # Explicit entries claim slots like the generated ones; dev
+            # historically skipped this, letting an explicit-connections
+            # config evade the controller budget.
+            bluetooth_connection.consume_gatt_slot(
+                "bluetooth_proxy", len(config[CONF_CONNECTIONS])
+            )(config)
        elif config[CONF_ACTIVE]:
            connection_slots: int = config[CONF_CONNECTION_SLOTS]
-            esp32_ble.consume_connection_slots(connection_slots, "bluetooth_proxy")(
+            bluetooth_connection.consume_gatt_slot("bluetooth_proxy", connection_slots)(
                config
            )

@@ -157,14 +163,14 @@ def _rp2_config_schema() -> cv.All:
    connection_schema = bluetooth_connection.hub_connection_schema(PLATFORM_RP2)

    def populate_connections(config: ConfigType) -> ConfigType:
-        from esphome.components import rp2040_ble
-
        # One wrapper + backend pair per slot, declared during validation so
        # their ids exist for codegen (the esp32 arm's `connections` pattern).
        if not config[CONF_ACTIVE]:
            return config
        connection_slots: int = config[CONF_CONNECTION_SLOTS]
-        rp2040_ble.consume_connection_slots(connection_slots, "bluetooth_proxy")(config)
+        bluetooth_connection.consume_gatt_slot("bluetooth_proxy", connection_slots)(
+            config
+        )
        return {
            **config,
            CONF_CONNECTIONS: [connection_schema({}) for _ in range(connection_slots)],
@@ -214,7 +220,9 @@ async def _connections_to_code(var: cg.MockObj, config: ConfigType) -> None:
        # sends those requests and their handlers and encoders are dead.
        cg.add_define("USE_BLUETOOTH_PROXY_CONNECTIONS")
    for connection_conf in connections:
-        backend = await bluetooth_connection.new_gatt_backend(connection_conf)
+        backend = await bluetooth_connection.new_gatt_backend(
+            connection_conf, service_table=False
+        )
        connection = cg.new_Pvariable(connection_conf[CONF_ID])
        cg.add(connection.set_backend(backend))
        cg.add(var.register_connection(connection))
@@ -103,7 +103,8 @@ struct CameraImageSpec {
 /** Abstract camera base class. Collaborates with API.
 *  1) API server starts and registers as a listener (add_listener)
 *     to receive new images from the camera.
- *  2) New API client connects and creates a new image reader (create_image_reader).
+ *  2) API connection creates an image reader (create_image_reader) when it receives
+ *     the first image it will send.
 *  3) API connection receives protobuf CameraImageRequest and calls request_image.
 *  3.a) API connection receives protobuf CameraImageRequest and calls start_stream.
 *  4) Camera implementation provides JPEG data in the CameraImage and notifies listeners.
@@ -61,7 +61,7 @@ CONFIG_SCHEMA = cv.All(
 )


-def _final_validate(config: ConfigType) -> ConfigType:
+def _final_validate(config: ConfigType) -> None:
    full_config = fv.full_config.get()
    wifi_conf = full_config.get("wifi")

@@ -88,8 +88,6 @@ def _final_validate(config: ConfigType) -> ConfigType:
    socket.consume_sockets(3, "captive_portal")(config)
    socket.consume_sockets(1, "captive_portal", socket.SocketType.UDP)(config)

-    return config
-

 FINAL_VALIDATE_SCHEMA = _final_validate

@@ -10,6 +10,7 @@ CONF_ACCELEROMETER_RANGE = "accelerometer_range"
 CONF_B_CONSTANT = "b_constant"
 CONF_BREATH_VOC_EQUIVALENT = "breath_voc_equivalent"
 CONF_BYTE_ORDER = "byte_order"
+CONF_CHANNEL_COLORS = "channel_colors"
 CONF_CLIMATE_ID = "climate_id"
 CONF_CO2_EQUIVALENT = "co2_equivalent"
 CONF_COLOR_DEPTH = "color_depth"
@@ -22,6 +23,7 @@ CONF_GYROSCOPE_ODR = "gyroscope_odr"
 CONF_GYROSCOPE_RANGE = "gyroscope_range"
 CONF_IAQ = "iaq"
 CONF_IGNORE_NOT_FOUND = "ignore_not_found"
+CONF_IS_WRGB = "is_wrgb"
 CONF_LABEL = "label"
 CONF_LIBRETINY = "libretiny"
 CONF_LOOP = "loop"
@@ -5,7 +5,7 @@

 namespace esphome::deep_sleep {

-static const char *const TAG = "deep_sleep.bk72xx";
+static const char *const TAG = "deep_sleep";

 #ifdef USE_DEEP_SLEEP_ON_WAKE
 WakeupCause get_wakeup_cause() {
@@ -88,7 +88,7 @@ async def to_code(config):
    cg.add_library("esphome/dsmr_parser", "1.9.0")


-def final_validate(config: ConfigType) -> ConfigType:
+def final_validate(config: ConfigType) -> None:
    full_config = fv.full_config.get()

    for uart_conf in full_config["uart"]:
@@ -102,7 +102,5 @@ def final_validate(config: ConfigType) -> ConfigType:
                )
            break

-    return config
-

 FINAL_VALIDATE_SCHEMA = final_validate
@@ -59,7 +59,7 @@ CONFIG_SCHEMA = (
 )


-def final_validate(config: ConfigType) -> ConfigType:
+def final_validate(config: ConfigType) -> None:
    full_config = fv.full_config.get()

    # Count sensors registered to this hub (IDs are resolved at final_validate stage)
@@ -95,7 +95,7 @@ def final_validate(config: ConfigType) -> ConfigType:
        parity="NONE",
        stop_bits=1,
    )
-    return schema(config)
+    schema(config)


 FINAL_VALIDATE_SCHEMA = final_validate
@@ -153,7 +153,7 @@ def customise_schema(config):
 CONFIG_SCHEMA = customise_schema


-def _final_validate(config):
+def _final_validate(config) -> None:
    spi.final_validate_device_schema(
        "epaper_spi", require_miso=False, require_mosi=True
    )(config)
@@ -170,7 +170,6 @@ def _final_validate(config):
            config[CONF_SHOW_TEST_CARD] = True
    elif CONF_UPDATE_INTERVAL not in config:
        config[CONF_UPDATE_INTERVAL] = update_interval("1min")
-    return config


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -570,6 +570,9 @@ def get_download_types(storage_json):
    the shape stable so the download panel
    doesn't have to special-case per-platform schemas.
    """
+    # No recorded firmware path means nothing was built; no downloads.
+    if storage_json.firmware_bin_path is None:
+        return []
    return [
        {
            "title": "Factory format (Previously Modern)",
@@ -1070,6 +1073,26 @@ def _parse_pio_platform_version(value):
        return value


+def _normalize_p4_engineering_sample(value: ConfigType) -> bool:
+    """Fill in CONF_ENGINEERING_SAMPLE when unset, warning that production
+    silicon (rev3) is assumed. Returns the normalized flag."""
+    if (engineering_sample := value.get(CONF_ENGINEERING_SAMPLE)) is None:
+        _LOGGER.warning(
+            "Defaulting to ESP32-P4 production silicon (rev3).\n"
+            "If you have an early engineering sample (pre-rev3), add this to your config:\n"
+            "\n"
+            "  esp32:\n"
+            "    engineering_sample: true\n"
+            "\n"
+            "To check your chip revision, look for 'chip revision: vX.Y' in the boot log.\n"
+            "Engineering samples will show a revision below v3.0.\n"
+            "The 'debug:' component also reports the revision (e.g. Revision: 100 = v1.0, 300 = v3.0)."
+        )
+        engineering_sample = False
+        value[CONF_ENGINEERING_SAMPLE] = engineering_sample
+    return engineering_sample
+
+
 def _detect_variant(value):
    board = value.get(CONF_BOARD)
    variant = value.get(CONF_VARIANT)
@@ -1082,6 +1105,8 @@ def _detect_variant(value):
        # name rather than carrying a PIO board name through the IDF build.
        if CORE.using_toolchain_esp_idf:
            value = value.copy()
+            if variant == VARIANT_ESP32P4:
+                _normalize_p4_engineering_sample(value)
            value[CONF_BOARD] = VARIANT_FRIENDLY[variant].lower()
            return value
        if variant not in STANDARD_BOARDS:
@@ -1092,22 +1117,8 @@ def _detect_variant(value):
            )
        value = value.copy()
        value[CONF_BOARD] = STANDARD_BOARDS[variant]
-        if variant == VARIANT_ESP32P4:
-            engineering_sample = value.get(CONF_ENGINEERING_SAMPLE)
-            if engineering_sample is None:
-                _LOGGER.warning(
-                    "No board specified for ESP32-P4. Defaulting to production silicon (rev3).\n"
-                    "If you have an early engineering sample (pre-rev3), add this to your config:\n"
-                    "\n"
-                    "  esp32:\n"
-                    "    engineering_sample: true\n"
-                    "\n"
-                    "To check your chip revision, look for 'chip revision: vX.Y' in the boot log.\n"
-                    "Engineering samples will show a revision below v3.0.\n"
-                    "The 'debug:' component also reports the revision (e.g. Revision: 100 = v1.0, 300 = v3.0)."
-                )
-            elif engineering_sample:
-                value[CONF_BOARD] = "esp32-p4-evboard"
+        if variant == VARIANT_ESP32P4 and _normalize_p4_engineering_sample(value):
+            value[CONF_BOARD] = "esp32-p4-evboard"
    elif board in BOARDS:
        variant = variant or BOARDS[board][KEY_VARIANT]
        if variant != BOARDS[board][KEY_VARIANT]:
@@ -1117,6 +1128,14 @@ def _detect_variant(value):
            )
        value = value.copy()
        value[CONF_VARIANT] = variant
+        if variant == VARIANT_ESP32P4:
+            board_is_es = BOARDS[board].get("engineering_sample", False)
+            engineering_sample = value.setdefault(CONF_ENGINEERING_SAMPLE, board_is_es)
+            if engineering_sample != board_is_es:
+                raise cv.Invalid(
+                    f"'{CONF_ENGINEERING_SAMPLE}' does not match board '{board}'",
+                    path=[CONF_ENGINEERING_SAMPLE],
+                )
    elif not variant:
        raise cv.Invalid(
            "This board is unknown, if you are sure you want to compile with this board selection, "
@@ -1128,6 +1147,9 @@ def _detect_variant(value):
            "This board is unknown; the specified variant '%s' will be used but this may not work as expected.",
            variant,
        )
+        if variant == VARIANT_ESP32P4:
+            value = value.copy()
+            _normalize_p4_engineering_sample(value)
    return value


@@ -1365,7 +1387,7 @@ def _validate_signed_ota_keys(config: ConfigType) -> ConfigType:
    return config


-def final_validate(config):
+def final_validate(config) -> None:
    # Imported locally to avoid circular import issues
    from esphome.components.psram import DOMAIN as PSRAM_DOMAIN

@@ -1431,20 +1453,6 @@ def final_validate(config):
                path=[CONF_ENGINEERING_SAMPLE],
            )
        )
-    if (
-        config[CONF_VARIANT] == VARIANT_ESP32P4
-        and config.get(CONF_ENGINEERING_SAMPLE) is not None
-    ):
-        board_is_es = BOARDS.get(config[CONF_BOARD], {}).get(
-            "engineering_sample", False
-        )
-        if config[CONF_ENGINEERING_SAMPLE] != board_is_es:
-            errs.append(
-                cv.Invalid(
-                    f"'{CONF_ENGINEERING_SAMPLE}' does not match board '{config[CONF_BOARD]}'",
-                    path=[CONF_ENGINEERING_SAMPLE],
-                )
-            )
    if advanced[CONF_EXECUTE_FROM_PSRAM]:
        if config[CONF_VARIANT] not in {VARIANT_ESP32S3, VARIANT_ESP32P4}:
            errs.append(
@@ -1626,8 +1634,6 @@ def final_validate(config):
    if errs:
        raise cv.MultipleInvalid(errs)

-    return config
-

 CONF_SDKCONFIG_OPTIONS = "sdkconfig_options"
 CONF_ENABLE_LWIP_DHCP_SERVER = "enable_lwip_dhcp_server"
@@ -2517,15 +2523,14 @@ async def to_code(config):
            f"CONFIG_ESPTOOLPY_FLASHFREQ_{flash_frequency[:-3]}M", True
        )

-    # ESP32-P4: ESP-IDF 5.5.3 changed the default of ESP32P4_SELECTS_REV_LESS_V3
-    # from y to n. PlatformIO uses sections.ld.in (for rev <3) or
-    # sections.rev3.ld.in (for rev >=3) based on board definition.
-    # Set the sdkconfig option to match the board's chip revision.
+    # ESP32-P4: pre-v3 and rev3 (v3.0+) silicon are not binary compatible.
+    # CONFIG_ESP32P4_SELECTS_REV_LESS_V3 selects which layout ESP-IDF links;
+    # validation normalizes CONF_ENGINEERING_SAMPLE from the board when unset.
    if variant == VARIANT_ESP32P4:
-        is_eng_sample = BOARDS.get(config[CONF_BOARD], {}).get(
-            "engineering_sample", False
+        add_idf_sdkconfig_option(
+            "CONFIG_ESP32P4_SELECTS_REV_LESS_V3",
+            config.get(CONF_ENGINEERING_SAMPLE, False),
        )
-        add_idf_sdkconfig_option("CONFIG_ESP32P4_SELECTS_REV_LESS_V3", is_eng_sample)

    # Set minimum chip revision for ESP32 variant
    # Setting this to 3.0 or higher reduces flash size by excluding workaround code,
@@ -360,17 +360,6 @@ static bool has_fault_addr() {
  return s_raw_crash_data.exception == PANIC_EXCEPTION_FAULT && !s_raw_crash_data.pseudo_excause;
 }

-// Append both cores' backtrace addresses to buf; returns the new position.
-static int append_all_backtraces(char *buf, int size, int pos) {
-  pos = append_addrs_to_hint(buf, size, pos, s_raw_crash_data.backtrace, s_raw_crash_data.backtrace_count,
-                             s_raw_crash_data.reg_frame_count);
-#if SOC_CPU_CORES_NUM > 1
-  pos = append_addrs_to_hint(buf, size, pos, s_raw_crash_data.other_backtrace, s_raw_crash_data.other_backtrace_count,
-                             s_raw_crash_data.other_reg_frame_count);
-#endif
-  return pos;
-}
-
 // The record was captured by a different firmware build (it survives soft
 // resets, including the OTA reboot), so symbolizing its addresses against the
 // current ELF would produce misleading symbols. Print them with lowercase
@@ -443,11 +432,23 @@ void crash_handler_log() {
  }
 #endif

-  // Build addr2line hint with all captured addresses for easy copy-paste
+  // Build addr2line hints for easy copy-paste. One line per core: the two
+  // backtraces are separate stacks, and a combined list decodes as one
+  // impossible call chain (and can overflow the buffer, dropping addresses).
+  static const char *const ADDR2LINE_CMD = "addr2line -pfiaC -e firmware.elf";
  char hint[256];
-  int pos = snprintf(hint, sizeof(hint), "Use: addr2line -pfiaC -e firmware.elf 0x%08" PRIX32, s_raw_crash_data.pc);
-  append_all_backtraces(hint, sizeof(hint), pos);
+  int pos = snprintf(hint, sizeof(hint), "Use: %s 0x%08" PRIX32, ADDR2LINE_CMD, s_raw_crash_data.pc);
+  append_addrs_to_hint(hint, sizeof(hint), pos, s_raw_crash_data.backtrace, s_raw_crash_data.backtrace_count,
+                       s_raw_crash_data.reg_frame_count);
  ESP_LOGE(TAG, "%s", hint);
+#if SOC_CPU_CORES_NUM > 1
+  if (s_raw_crash_data.other_backtrace_count > 0) {
+    pos = snprintf(hint, sizeof(hint), "Other core: %s", ADDR2LINE_CMD);
+    append_addrs_to_hint(hint, sizeof(hint), pos, s_raw_crash_data.other_backtrace,
+                         s_raw_crash_data.other_backtrace_count, s_raw_crash_data.other_reg_frame_count);
+    ESP_LOGE(TAG, "%s", hint);
+  }
+#endif
 }

 }  // namespace esphome::esp32
@@ -443,7 +443,7 @@ def validate_connection_slots(max_connections: int) -> None:
    )


-def final_validation(config):
+def final_validation(config) -> None:
    validate_variant(config)
    if (name := config.get(CONF_NAME)) is not None:
        full_config = fv.full_config.get()
@@ -514,8 +514,6 @@ def final_validation(config):
    # For newer chips (C3/S3/etc), different configs are used automatically
    add_idf_sdkconfig_option("CONFIG_BTDM_CTRL_BLE_MAX_CONN", max_connections)

-    return config
-

 FINAL_VALIDATE_SCHEMA = final_validation

@@ -307,7 +307,7 @@ def create_device_information_service(config):
    return config


-def final_validate_config(config):
+def final_validate_config(config) -> None:
    # Validate max_clients does not exceed esp32_ble max_connections
    max_clients = config[CONF_MAX_CLIENTS]
    if max_clients > 1:
@@ -355,7 +355,6 @@ def final_validate_config(config):
            raise cv.Invalid(
                f"Characteristic {char_config[CONF_UUID]} has both a set_value action and a templated value"
            )
-    return config


 def validate_value_type(value_config):
@@ -16,8 +16,10 @@ from esphome.const import (
    CONF_VARIANT,
 )
 from esphome.cpp_generator import add_define
+from esphome.types import ConfigType

 CODEOWNERS = ["@swoboda1337"]
+DEPENDENCIES = ["esp32"]
 # esp32_ble raises the task watchdog around the remote BT controller bring-up
 AUTO_LOAD = ["watchdog"]

@@ -124,6 +126,21 @@ CONFIG_SCHEMA = cv.typed_schema(
 )


+def _final_validate(config: ConfigType) -> None:
+    # The esp_hosted releases compatible with older ESP-IDF versions crash at
+    # boot with a heap double free in the SDIO RX path (fixed in esp_hosted
+    # 2.11.0, which requires ESP-IDF 5.3), so reject them at validation time.
+    if (idf_ver := esp32.idf_version()) < cv.Version(5, 3, 0):
+        raise cv.Invalid(
+            f"esp32_hosted requires ESP-IDF 5.3 or newer, got {idf_ver}. "
+            "Remove the framework version from your configuration to use the "
+            "recommended version, or pin a version at or above 5.3."
+        )
+
+
+FINAL_VALIDATE_SCHEMA = _final_validate
+
+
 def _configure_sdio(config):
    slot = config[CONF_SLOT]
    esp32.add_idf_sdkconfig_option(
@@ -251,18 +268,14 @@ async def to_code(config):
    if config[CONF_USE_PSRAM]:
        esp32.add_idf_sdkconfig_option("CONFIG_ESP_HOSTED_MEMPOOL_PREFER_SPIRAM", True)

-    # Library versions
+    # Library versions; this component set requires ESP-IDF 5.3 or newer,
+    # which is enforced at validation time.
    idf_ver = esp32.idf_version()
    os.environ["ESP_IDF_VERSION"] = f"{idf_ver.major}.{idf_ver.minor}"
-    if idf_ver >= cv.Version(5, 5, 0):
-        esp32.add_idf_component(name="espressif/esp_wifi_remote", ref="1.6.3")
-        esp32.add_idf_component(name="espressif/wifi_remote_over_eppp", ref="0.3.3")
-        esp32.add_idf_component(name="espressif/eppp_link", ref="1.1.5")
-        esp32.add_idf_component(name="espressif/esp_hosted", ref="2.12.12")
-    else:
-        esp32.add_idf_component(name="espressif/esp_wifi_remote", ref="0.13.0")
-        esp32.add_idf_component(name="espressif/eppp_link", ref="0.2.0")
-        esp32.add_idf_component(name="espressif/esp_hosted", ref="2.0.11")
+    esp32.add_idf_component(name="espressif/esp_wifi_remote", ref="1.6.3")
+    esp32.add_idf_component(name="espressif/wifi_remote_over_eppp", ref="0.3.3")
+    esp32.add_idf_component(name="espressif/eppp_link", ref="1.1.5")
+    esp32.add_idf_component(name="espressif/esp_hosted", ref="2.12.12")
    esp32.add_extra_script(
        "post",
        "esp32_hosted.py",
@@ -221,46 +221,12 @@ void ESP32RMTLEDStripLightOutput::write_state(light::LightState *state) {
 }

 light::ESPColorView ESP32RMTLEDStripLightOutput::get_view_internal(int32_t index) const {
-  int32_t r = 0, g = 0, b = 0;
-  switch (this->rgb_order_) {
-    case ORDER_RGB:
-      r = 0;
-      g = 1;
-      b = 2;
-      break;
-    case ORDER_RBG:
-      r = 0;
-      g = 2;
-      b = 1;
-      break;
-    case ORDER_GRB:
-      r = 1;
-      g = 0;
-      b = 2;
-      break;
-    case ORDER_GBR:
-      r = 2;
-      g = 0;
-      b = 1;
-      break;
-    case ORDER_BGR:
-      r = 2;
-      g = 1;
-      b = 0;
-      break;
-    case ORDER_BRG:
-      r = 1;
-      g = 2;
-      b = 0;
-      break;
-  }
-  uint8_t multiplier = this->is_rgbw_ || this->is_wrgb_ ? 4 : 3;
-  uint8_t white = this->is_wrgb_ ? 0 : this->white_index_;
-
-  return {this->buf_ + (index * multiplier) + r + (white <= r),
-          this->buf_ + (index * multiplier) + g + (white <= g),
-          this->buf_ + (index * multiplier) + b + (white <= b),
-          this->is_rgbw_ || this->is_wrgb_ ? this->buf_ + (index * multiplier) + white : nullptr,
+  const light::ChannelColors &colors = this->channel_colors_;
+  uint8_t *led = this->buf_ + (index * colors.bytes_per_led());
+  return {led + colors.r,
+          led + colors.g,
+          led + colors.b,
+          colors.has_white() ? led + colors.w : nullptr,
          &this->effect_data_[index],
          &this->correction_};
 }
@@ -271,46 +237,12 @@ void ESP32RMTLEDStripLightOutput::dump_config() {
                "  Pin: %u",
                this->pin_);
  ESP_LOGCONFIG(TAG, "  RMT Symbols: %" PRIu32, this->rmt_symbols_);
-  const char *rgb_order;
-  switch (this->rgb_order_) {
-    case ORDER_RGB:
-      rgb_order = "RGB";
-      break;
-    case ORDER_RBG:
-      rgb_order = "RBG";
-      break;
-    case ORDER_GRB:
-      rgb_order = "GRB";
-      break;
-    case ORDER_GBR:
-      rgb_order = "GBR";
-      break;
-    case ORDER_BGR:
-      rgb_order = "BGR";
-      break;
-    case ORDER_BRG:
-      rgb_order = "BRG";
-      break;
-    default:
-      rgb_order = "UNKNOWN";
-      break;
-  }
-  if (this->is_rgbw_ || this->is_wrgb_) {
-    char rgbw_order[5];
-    uint8_t white = this->is_wrgb_ ? 0 : this->white_index_;
-    uint8_t rgb_index = 0;
-    for (uint8_t i = 0; i < 4; i++) {
-      rgbw_order[i] = i == white ? 'W' : rgb_order[rgb_index++];
-    }
-    rgbw_order[4] = '\0';
-    ESP_LOGCONFIG(TAG, "  RGBW Order: %s", rgbw_order);
-  } else {
-    ESP_LOGCONFIG(TAG, "  RGB Order: %s", rgb_order);
-  }
+  char channel_colors[5];
  ESP_LOGCONFIG(TAG,
+                "  Channel colors: %s\n"
                "  Max refresh rate: %" PRIu32 "\n"
                "  Number of LEDs: %u",
-                this->max_refresh_rate_.value_or(0), this->num_leds_);
+                this->channel_colors_.to_string(channel_colors), this->max_refresh_rate_.value_or(0), this->num_leds_);
 }

 float ESP32RMTLEDStripLightOutput::get_setup_priority() const { return setup_priority::HARDWARE; }
@@ -3,6 +3,7 @@
 #ifdef USE_ESP32

 #include "esphome/components/light/addressable_light.h"
+#include "esphome/components/light/channel_colors.h"
 #include "esphome/components/light/light_output.h"
 #include "esphome/core/color.h"
 #include "esphome/core/component.h"
@@ -15,15 +16,6 @@

 namespace esphome::esp32_rmt_led_strip {

-enum RGBOrder : uint8_t {
-  ORDER_RGB,
-  ORDER_RBG,
-  ORDER_GRB,
-  ORDER_GBR,
-  ORDER_BGR,
-  ORDER_BRG,
-};
-
 struct LedParams {
  rmt_symbol_word_t bit0;
  rmt_symbol_word_t bit1;
@@ -39,7 +31,7 @@ class ESP32RMTLEDStripLightOutput final : public light::AddressableLight {
  int32_t size() const override { return this->num_leds_; }
  light::LightTraits get_traits() override {
    auto traits = light::LightTraits();
-    if (this->is_rgbw_ || this->is_wrgb_) {
+    if (this->channel_colors_.has_white()) {
      traits.set_supported_color_modes({light::ColorMode::RGB_WHITE, light::ColorMode::WHITE});
    } else {
      traits.set_supported_color_modes({light::ColorMode::RGB});
@@ -50,13 +42,7 @@ class ESP32RMTLEDStripLightOutput final : public light::AddressableLight {
  void set_pin(uint8_t pin) { this->pin_ = pin; }
  void set_inverted(bool inverted) { this->invert_out_ = inverted; }
  void set_num_leds(uint16_t num_leds) { this->num_leds_ = num_leds; }
-  void set_is_rgbw(bool is_rgbw) { this->is_rgbw_ = is_rgbw; }
-  void set_is_wrgb(bool is_wrgb) { this->is_wrgb_ = is_wrgb; }
-  void set_rgbw_order(uint8_t white_index) {
-    this->is_rgbw_ = true;
-    this->is_wrgb_ = false;
-    this->white_index_ = white_index;
-  }
+  void set_channel_colors(light::ChannelColors channel_colors) { this->channel_colors_ = channel_colors; }
  void set_use_dma(bool use_dma) { this->use_dma_ = use_dma; }
  void set_use_psram(bool use_psram) { this->use_psram_ = use_psram; }

@@ -66,7 +52,6 @@ class ESP32RMTLEDStripLightOutput final : public light::AddressableLight {
  void set_led_params(uint32_t bit0_high, uint32_t bit0_low, uint32_t bit1_high, uint32_t bit1_low,
                      uint32_t reset_time_high, uint32_t reset_time_low);

-  void set_rgb_order(RGBOrder rgb_order) { this->rgb_order_ = rgb_order; }
  void set_rmt_symbols(uint32_t rmt_symbols) { this->rmt_symbols_ = rmt_symbols; }

  void clear_effect_data() override {
@@ -79,7 +64,7 @@ class ESP32RMTLEDStripLightOutput final : public light::AddressableLight {
 protected:
  light::ESPColorView get_view_internal(int32_t index) const override;

-  size_t get_buffer_size_() const { return this->num_leds_ * (this->is_rgbw_ || this->is_wrgb_ ? 4 : 3); }
+  size_t get_buffer_size_() const { return this->num_leds_ * this->channel_colors_.bytes_per_led(); }

  uint8_t *buf_{nullptr};
  uint8_t *effect_data_{nullptr};
@@ -94,15 +79,11 @@ class ESP32RMTLEDStripLightOutput final : public light::AddressableLight {
  uint32_t rmt_symbols_{48};
  uint8_t pin_;
  uint16_t num_leds_;
-  bool is_rgbw_{false};
-  bool is_wrgb_{false};
-  // An index after the RGB channels makes offset adjustment a no-op for three-channel strips.
-  uint8_t white_index_{3};
  bool use_dma_{false};
  bool use_psram_{false};
  bool invert_out_{false};

-  RGBOrder rgb_order_{ORDER_RGB};
+  light::ChannelColors channel_colors_{0, 1, 2, light::ChannelColors::NO_WHITE};

  uint32_t last_refresh_{0};
  optional<uint32_t> max_refresh_rate_{};
@@ -1,10 +1,9 @@
 from dataclasses import dataclass
-import logging

 from esphome import pins
 import esphome.codegen as cg
 from esphome.components import esp32, esp32_rmt, light
-from esphome.components.const import CONF_USE_PSRAM
+from esphome.components.const import CONF_CHANNEL_COLORS, CONF_IS_WRGB, CONF_USE_PSRAM
 from esphome.components.esp32 import include_builtin_idf_component
 import esphome.config_validation as cv
 from esphome.const import (
@@ -22,8 +21,6 @@ from esphome.const import (
 )
 from esphome.types import ConfigType

-_LOGGER = logging.getLogger(__name__)
-
 CODEOWNERS = ["@jesserockz"]
 DEPENDENCIES = ["esp32"]

@@ -32,17 +29,6 @@ ESP32RMTLEDStripLightOutput = esp32_rmt_led_strip_ns.class_(
    "ESP32RMTLEDStripLightOutput", light.AddressableLight
 )

-RGBOrder = esp32_rmt_led_strip_ns.enum("RGBOrder")
-
-RGB_ORDERS = {
-    "RGB": RGBOrder.ORDER_RGB,
-    "RBG": RGBOrder.ORDER_RBG,
-    "GRB": RGBOrder.ORDER_GRB,
-    "GBR": RGBOrder.ORDER_GBR,
-    "BGR": RGBOrder.ORDER_BGR,
-    "BRG": RGBOrder.ORDER_BRG,
-}
-

@dataclass
 class LEDStripTimings:
@@ -62,8 +48,6 @@ CHIPSETS = {
    "SM16703": LEDStripTimings(300, 900, 900, 300, 0, 0),
 }

-CONF_IS_WRGB = "is_wrgb"
-CONF_RGBW_ORDER = "rgbw_order"
 CONF_BIT0_HIGH = "bit0_high"
 CONF_BIT0_LOW = "bit0_low"
 CONF_BIT1_HIGH = "bit1_high"
@@ -72,26 +56,6 @@ CONF_RESET_HIGH = "reset_high"
 CONF_RESET_LOW = "reset_low"


-def _validate_rgbw_order(value: str) -> str:
-    value = cv.string(value).upper()
-    if len(value) != 4 or set(value) != set("RGBW"):
-        raise cv.Invalid("RGBW order must be a permutation of RGBW")
-    return value
-
-
-def _split_rgbw_order(rgbw_order: str) -> tuple[str, int]:
-    return rgbw_order.replace("W", ""), rgbw_order.index("W")
-
-
-def _validate_rgbw_order_exclusivity(config: ConfigType) -> ConfigType:
-    if CONF_RGBW_ORDER in config and (config[CONF_IS_RGBW] or config[CONF_IS_WRGB]):
-        raise cv.Invalid(
-            f"'{CONF_RGBW_ORDER}' cannot be used with '{CONF_IS_RGBW}' or "
-            f"'{CONF_IS_WRGB}'"
-        )
-    return config
-
-
 CONFIG_SCHEMA = cv.All(
    esp32.only_on_variant(
        unsupported=list(esp32_rmt.VARIANTS_NO_RMT),
@@ -102,8 +66,11 @@ CONFIG_SCHEMA = cv.All(
            cv.GenerateID(CONF_OUTPUT_ID): cv.declare_id(ESP32RMTLEDStripLightOutput),
            cv.Required(CONF_PIN): pins.internal_gpio_output_pin_schema,
            cv.Required(CONF_NUM_LEDS): cv.positive_not_null_int,
-            cv.Optional(CONF_RGB_ORDER): cv.enum(RGB_ORDERS, upper=True),
-            cv.Optional(CONF_RGBW_ORDER): _validate_rgbw_order,
+            cv.Optional(CONF_CHANNEL_COLORS): light.validate_channel_colors,
+            # Deprecated in favour of CONF_CHANNEL_COLORS, remove in 2027.3.0
+            cv.Optional(CONF_RGB_ORDER): cv.one_of(*light.RGB_ORDERS, upper=True),
+            cv.Optional(CONF_IS_RGBW): cv.boolean,
+            cv.Optional(CONF_IS_WRGB): cv.boolean,
            cv.SplitDefault(
                CONF_RMT_SYMBOLS,
                esp32=192,
@@ -117,8 +84,6 @@ CONFIG_SCHEMA = cv.All(
            ): cv.int_range(min=2),
            cv.Optional(CONF_MAX_REFRESH_RATE): cv.positive_time_period_microseconds,
            cv.Optional(CONF_CHIPSET): cv.one_of(*CHIPSETS, upper=True),
-            cv.Optional(CONF_IS_RGBW, default=False): cv.boolean,
-            cv.Optional(CONF_IS_WRGB, default=False): cv.boolean,
            cv.Optional(CONF_USE_DMA): cv.All(
                esp32.only_on_variant(
                    supported=[esp32.VARIANT_ESP32P4, esp32.VARIANT_ESP32S3]
@@ -153,12 +118,13 @@ CONFIG_SCHEMA = cv.All(
        }
    ).extend(cv.COMPONENT_SCHEMA),
    cv.has_exactly_one_key(CONF_CHIPSET, CONF_BIT0_HIGH),
-    cv.has_exactly_one_key(CONF_RGB_ORDER, CONF_RGBW_ORDER),
-    _validate_rgbw_order_exclusivity,
+    light.migrate_channel_colors(
+        removed_in="2027.3.0", component="esp32_rmt_led_strip"
+    ),
 )


-async def to_code(config):
+async def to_code(config: ConfigType) -> None:
    # Re-enable ESP-IDF's RMT driver (excluded by default to save compile time)
    include_builtin_idf_component("esp_driver_rmt")

@@ -198,14 +164,9 @@ async def to_code(config):
            )
        )

-    if (rgbw_order := config.get(CONF_RGBW_ORDER)) is not None:
-        rgb_order, white_index = _split_rgbw_order(rgbw_order)
-        cg.add(var.set_rgb_order(RGB_ORDERS[rgb_order]))
-        cg.add(var.set_rgbw_order(white_index))
-    else:
-        cg.add(var.set_rgb_order(config[CONF_RGB_ORDER]))
-        cg.add(var.set_is_rgbw(config[CONF_IS_RGBW]))
-        cg.add(var.set_is_wrgb(config[CONF_IS_WRGB]))
+    cg.add(
+        var.set_channel_colors(light.channel_colors_struct(config[CONF_CHANNEL_COLORS]))
+    )
    cg.add(var.set_use_psram(config[CONF_USE_PSRAM]))
    cg.add(var.set_rmt_symbols(config[CONF_RMT_SYMBOLS]))
    if CONF_USE_DMA in config:
@@ -113,6 +113,9 @@ def get_download_types(storage_json):
    the shape stable so the download panel
    doesn't have to special-case per-platform schemas.
    """
+    # No recorded firmware path means nothing was built; no downloads.
+    if storage_json.firmware_bin_path is None:
+        return []
    return [
        {
            "title": "Standard format",
@@ -355,7 +355,7 @@ def _validate(config):
                    "  clk:\n"
                    "    mode: %s\n"
                    "    pin: %s\n"
-                    "Removal scheduled for 2026.9.0.",
+                    "Removal scheduled for 2026.11.0.",
                    config[CONF_CLK_MODE],
                    mode,
                    pin,
@@ -767,7 +767,7 @@ def _final_validate_rmii_pins(config: ConfigType) -> None:
            raise cv.Invalid(error_msg, path=pin_path)


-def _final_validate(config: ConfigType) -> ConfigType:
+def _final_validate(config: ConfigType) -> None:
    """Final validation for Ethernet component."""
    # Allow ethernet + wifi coexistence only when both are declared in network: priority:.
    if "wifi" in fv.full_config.get():
@@ -787,7 +787,6 @@ def _final_validate(config: ConfigType) -> ConfigType:

    _final_validate_spi(config)
    _final_validate_rmii_pins(config)
-    return config


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -60,14 +60,13 @@ CONFIG_SCHEMA = cv.All(
 )


-def _final_validate(config):
+def _final_validate(config) -> None:
    if CORE.is_esp8266 and CONF_RESETS_REQUIRED in config:
        fconfig = full_config.get()
        if not fconfig.get_config_for_path([KEY_ESP8266, CONF_RESTORE_FROM_FLASH]):
            raise cv.Invalid(
                "'resets_required' needs 'restore_from_flash' to be enabled in the  'esp8266' configuration"
            )
-    return config


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -23,6 +23,7 @@ from esphome.components.image import (
    get_image_type_enum,
    get_transparency_enum,
    is_svg_file,
+    validate_byte_order,
    validate_settings,
    validate_transparency,
    validate_type,
@@ -200,7 +201,7 @@ OPTIONS_SCHEMA = {
        "NONE", "FLOYDSTEINBERG", upper=True
    ),
    cv.Optional(CONF_INVERT_ALPHA, default=False): cv.boolean,
-    cv.Optional(CONF_BYTE_ORDER): cv.one_of("BIG_ENDIAN", "LITTLE_ENDIAN", upper=True),
+    cv.Optional(CONF_BYTE_ORDER): validate_byte_order,
    cv.Optional(CONF_TRANSPARENCY, default=CONF_OPAQUE): validate_transparency(),
 }

@@ -225,7 +226,7 @@ def image_schema(class_: MockObjClass = Image_) -> cv.Schema:
    )


-def validate_image_final(config: ConfigType) -> ConfigType:
+def validate_image_final(config: ConfigType) -> None:
    """Per-entry final validation, shared by file-backed image platforms.

    For LVGL 9 the default byte order for RGB565 images is little-endian, so
@@ -240,7 +241,6 @@ def validate_image_final(config: ConfigType) -> ConfigType:
            )
    else:
        config[CONF_BYTE_ORDER] = "LITTLE_ENDIAN"
-    return config


 async def new_image(config: ConfigType) -> MockObj:
@@ -68,10 +68,10 @@ def _pin_shared_only_with_deep_sleep(pin_num: int) -> bool:
    return any(path and path[0] == "deep_sleep" for path, _, _ in pin_users)


-def _final_validate(config):
+def _final_validate(config) -> None:
    use_interrupt = config[CONF_USE_INTERRUPT]
    if not use_interrupt:
-        return config
+        return

    # Expander pins (e.g. PCF8574, MCP23017) don't support direct interrupt
    # attachment — only internal/native GPIO pins do.
@@ -82,7 +82,7 @@ def _final_validate(config):
            config.get(CONF_NAME, config[CONF_ID]),
        )
        config[CONF_USE_INTERRUPT] = False
-        return config
+        return

    pin_num = config[CONF_PIN][CONF_NUMBER]

@@ -96,7 +96,7 @@ def _final_validate(config):
            config.get(CONF_NAME, config[CONF_ID]),
        )
        config[CONF_USE_INTERRUPT] = False
-        return config
+        return

    # When a pin is shared, interrupts can interfere with other components
    # (e.g., duty_cycle sensor) that need to monitor the pin's state changes.
@@ -120,8 +120,6 @@ def _final_validate(config):
                pin_num,
            )

-    return config
-

 FINAL_VALIDATE_SCHEMA = _final_validate

@@ -0,0 +1,22 @@
+from esphome import pins
+import esphome.config_validation as cv
+from esphome.const import CONF_ALLOW_OTHER_USES, CONF_INTERRUPT_PIN, CONF_INVERTED
+from esphome.types import ConfigType
+
+
+def validate_interrupt_pin(value: ConfigType) -> ConfigType:
+    # The expander components own INT polarity (active-low, hardcoded falling-edge ISR)
+    # and install a single ISR per GPIO, so neither inversion nor sharing is supported.
+    value = pins.internal_gpio_input_pin_schema(value)
+    if value.get(CONF_INVERTED):
+        raise cv.Invalid(
+            f"'{CONF_INVERTED}: true' is not supported on '{CONF_INTERRUPT_PIN}'; "
+            "the expander INT line is fixed active-low"
+        )
+    if value.get(CONF_ALLOW_OTHER_USES):
+        raise cv.Invalid(
+            f"'{CONF_ALLOW_OTHER_USES}: true' is not supported on '{CONF_INTERRUPT_PIN}'; "
+            "sharing the interrupt pin between multiple components is not implemented. "
+            f"Remove the '{CONF_INTERRUPT_PIN}' to fall back to polling."
+        )
+    return value
@@ -163,8 +163,8 @@ CONFIG_SCHEMA = (
 )


-def _final_validate(config: ConfigType) -> ConfigType:
-    return modbus.final_validate_modbus_device("growatt_solar", role="client")(config)
+def _final_validate(config: ConfigType) -> None:
+    modbus.final_validate_modbus_device("growatt_solar", role="client")(config)


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -424,7 +424,7 @@ async def power_action_to_code(config, action_id, template_arg, args):
    return cg.new_Pvariable(action_id, template_arg, paren)


-def _final_validate(config):
+def _final_validate(config) -> None:
    full_config = fv.full_config.get()
    if CONF_LOGGER in full_config:
        _level = "NONE"
@@ -448,7 +448,6 @@ def _final_validate(config):
        raise cv.Invalid(
            f"No WiFi configured, if you want to use haier climate without WiFi add {CONF_WIFI_SIGNAL}: false to climate configuration"
        )
-    return config


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -60,7 +60,7 @@ CONFIG_SCHEMA = cv.Schema(
 )


-def _final_validate(config):
+def _final_validate(config) -> None:
    full_config = fv.full_config.get()
    for switch_type in [CONF_BEEPER, CONF_QUIET_MODE]:
        # Check switches that are only supported for HonClimate
@@ -72,7 +72,6 @@ def _final_validate(config):
                raise cv.Invalid(
                    f"{switch_type} switch is only supported for hon climate"
                )
-    return config


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -217,8 +217,8 @@ CONFIG_SCHEMA = (
 )


-def _final_validate(config: ConfigType) -> ConfigType:
-    return modbus.final_validate_modbus_device("havells_solar", role="client")(config)
+def _final_validate(config: ConfigType) -> None:
+    modbus.final_validate_modbus_device("havells_solar", role="client")(config)


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -16,7 +16,7 @@

 namespace esphome::http_request {

-static const char *const TAG = "http_request.arduino";
+static const char *const TAG = "http_request";
 #ifdef USE_ESP8266
 // ESP8266 Arduino core (WiFiClientSecureBearSSL.cpp) returns -1000 on OOM
 static constexpr int ESP8266_SSL_ERR_OOM = -1000;
@@ -14,7 +14,7 @@

 namespace esphome::http_request {

-static const char *const TAG = "http_request.host";
+static const char *const TAG = "http_request";

 std::shared_ptr<HttpContainer> HttpRequestHost::perform(const std::string &url, const std::string &method,
                                                        const std::string &body,
@@ -16,7 +16,7 @@

 namespace esphome::http_request {

-static const char *const TAG = "http_request.idf";
+static const char *const TAG = "http_request";
 static constexpr uint32_t ERROR_DURATION_MS = 1000;

 void HttpRequestIDF::dump_config() {
@@ -315,7 +315,7 @@ def _validate_config(config: ConfigType) -> ConfigType:
    return config


-def _final_validate(config: ConfigType) -> ConfigType:
+def _final_validate(config: ConfigType) -> None:
    """Validate requirements when using HUB75 display."""
    # Local imports to avoid circular dependencies
    from esphome.components.esp32 import get_esp32_variant
@@ -381,8 +381,6 @@ def _final_validate(config: ConfigType) -> ConfigType:
    if errs:
        raise cv.MultipleInvalid(errs)

-    return config
-

 FINAL_VALIDATE_SCHEMA = cv.Schema(_final_validate)

@@ -9,7 +9,7 @@

 namespace esphome::i2c {

-static const char *const TAG = "i2c.arduino";
+static const char *const TAG = "i2c";

 // Maximum bytes to log in hex format (truncates larger transfers)
 static constexpr size_t I2C_MAX_LOG_BYTES = 32;
@@ -12,7 +12,7 @@

 namespace esphome::i2c {

-static const char *const TAG = "i2c.idf";
+static const char *const TAG = "i2c";

 // Maximum bytes to log in hex format (truncates larger transfers)
 static constexpr size_t I2C_MAX_LOG_BYTES = 32;
@@ -16,7 +16,7 @@

 namespace esphome::i2c {

-static const char *const TAG = "i2c.host";
+static const char *const TAG = "i2c";

 HostI2CBus::~HostI2CBus() {
  if (this->file_descriptor_ != -1) {
@@ -6,7 +6,7 @@

 namespace esphome::i2c {

-static const char *const TAG = "i2c.zephyr";
+static const char *const TAG = "i2c";

 static const char *get_speed(uint32_t dev_config) {
  switch (I2C_SPEED_GET(dev_config)) {
@@ -10,7 +10,14 @@ from PIL import Image, UnidentifiedImageError
 import esphome.codegen as cg
 from esphome.components.const import CONF_BYTE_ORDER, KEY_METADATA
 import esphome.config_validation as cv
-from esphome.const import CONF_DEFAULTS, CONF_FILE, CONF_ID, CONF_PLATFORM, CONF_TYPE
+from esphome.const import (
+    CONF_DEFAULTS,
+    CONF_FILE,
+    CONF_FILES,
+    CONF_ID,
+    CONF_PLATFORM,
+    CONF_TYPE,
+)
 from esphome.core import CORE
 from esphome.types import ConfigType

@@ -48,6 +55,9 @@ TRANSPARENCY_TYPES = (
    CONF_ALPHA_CHANNEL,
 )

+# Shared validator for the image platform schemas and `_drop_incompatible_byte_order`.
+validate_byte_order = cv.one_of("BIG_ENDIAN", "LITTLE_ENDIAN", upper=True)
+

 def get_image_type_enum(type):
    return getattr(ImageType, f"IMAGE_TYPE_{type.upper()}")
@@ -404,6 +414,120 @@ def get_image_metadata(image_id: str) -> ImageMetaData | None:
    return get_all_image_metadata().get(image_id)


+# ---------------------------------------------------------------------------
+# `defaults:`/`files:` expansion: a `platform:` entry merges shared `defaults:`
+# into every `files:` entry; the platform's CONFIG_SCHEMA validates each.
+# Permanent, unlike the legacy migration below.
+# ---------------------------------------------------------------------------
+
+
+def _drop_incompatible_byte_order(
+    merged: dict, explicit: dict, *, index: int | None = None
+) -> dict:
+    """Drop `byte_order` when the resolved type doesn't support it, unless written directly on `explicit`.
+
+    With `index`, inherited values are validated before being dropped (the legacy flattener always drops).
+    """
+    if CONF_BYTE_ORDER in explicit:
+        return merged
+    type_class = IMAGE_TYPE.get(str(merged.get(CONF_TYPE, "")).upper())
+    if (
+        CONF_BYTE_ORDER in merged
+        and isinstance(type_class, type)
+        and issubclass(type_class, ImageEncoder)
+        and not type_class.is_endian()
+    ):
+        if index is not None:
+            try:
+                validate_byte_order(merged[CONF_BYTE_ORDER])
+            except cv.Invalid as exc:
+                exc.prepend([index])
+                raise
+        del merged[CONF_BYTE_ORDER]
+    return merged
+
+
+def _expand_platform_entry(index: int, entry: dict) -> list[dict]:
+    if CONF_FILES not in entry:
+        if CONF_DEFAULTS in entry:
+            raise cv.Invalid(
+                f"'{CONF_DEFAULTS}' may only be used together with '{CONF_FILES}'",
+                path=[index],
+            )
+        return [entry]
+
+    extra_keys = set(entry) - {CONF_PLATFORM, CONF_DEFAULTS, CONF_FILES}
+    if extra_keys:
+        raise cv.Invalid(
+            f"'{CONF_FILES}' cannot be combined with "
+            f"{', '.join(sorted(extra_keys))} on the same entry",
+            path=[index],
+        )
+
+    files = entry[CONF_FILES]
+    if files is None:
+        raise cv.Invalid(f"'{CONF_FILES}' must not be empty", path=[index])
+    if not isinstance(files, list):
+        raise cv.Invalid(f"'{CONF_FILES}' must be a list", path=[index])
+    if not files:
+        raise cv.Invalid(f"'{CONF_FILES}' must not be empty", path=[index])
+
+    defaults = entry.get(CONF_DEFAULTS, {})
+    if defaults is None:
+        defaults = {}
+    if not isinstance(defaults, dict):
+        raise cv.Invalid(f"'{CONF_DEFAULTS}' must be a mapping", path=[index])
+    # Neither `id:` nor `platform:` makes sense inside `defaults:`.
+    for disallowed in (CONF_ID, CONF_PLATFORM):
+        if disallowed in defaults:
+            raise cv.Invalid(
+                f"'{disallowed}' is not allowed inside '{CONF_DEFAULTS}'",
+                path=[index],
+            )
+
+    from esphome import yaml_util
+
+    platform = entry[CONF_PLATFORM]
+    result: list[dict] = []
+    for file_entry in files:
+        if not isinstance(file_entry, dict):
+            raise cv.Invalid(
+                f"each entry in '{CONF_FILES}' must be a mapping", path=[index]
+            )
+        # The platform is chosen by the entry's own `platform:` key, not per file.
+        if CONF_PLATFORM in file_entry:
+            raise cv.Invalid(
+                f"'{CONF_PLATFORM}' is not allowed inside '{CONF_FILES}'",
+                path=[index],
+            )
+        # Keep the `files:` item's source range so whole-entry errors anchor there;
+        # `make_data_base` needs a real ESPHomeDataBase, so skip it for plain dicts.
+        source = (
+            file_entry if isinstance(file_entry, yaml_util.ESPHomeDataBase) else None
+        )
+        merged = yaml_util.make_data_base(
+            {CONF_PLATFORM: platform, **defaults, **file_entry}, source
+        )
+        result.append(_drop_incompatible_byte_order(merged, file_entry, index=index))
+    return result
+
+
+def expand_platform_config(config: list) -> list:
+    """Expand `defaults:`/`files:` entries; the platform's own CONFIG_SCHEMA validates each result."""
+    result = []
+    for i, entry in enumerate(config):
+        if isinstance(entry, dict) and CONF_PLATFORM in entry:
+            result.extend(_expand_platform_entry(i, entry))
+        else:
+            result.append(entry)
+    return result
+
+
+EXPAND_PLATFORM_CONFIG = expand_platform_config
+
+# --------------------- end defaults/files expansion -------------------------
+
+
 # ---------------------------------------------------------------------------
 # Legacy top-level component -> `image:` platform deprecation helpers
 # -- REMOVE after 2027.1.0 together with the `animation:`/`online_image:` shims.
@@ -496,11 +620,17 @@ def _is_legacy_image_format(config: object) -> bool:
    proper error instead of the migration silently dropping the input.
    """
    if isinstance(config, list):
-        # A bare list of (not-yet-platform-tagged) image dicts.
+        # Exclude `files:` entries -- the list branch would otherwise silently
+        # migrate them to `platform: file` instead of raising the missing-platform error.
        return bool(config) and all(
-            isinstance(entry, dict) and CONF_PLATFORM not in entry for entry in config
+            isinstance(entry, dict)
+            and CONF_PLATFORM not in entry
+            and CONF_FILES not in entry
+            for entry in config
        )
-    if not isinstance(config, dict):
+    if not isinstance(config, dict) or CONF_PLATFORM in config or CONF_FILES in config:
+        # `platform:`/`files:` dicts are new-format (left for list-wrapping +
+        # expansion); the legacy flattener has no `files:` branch and would drop them.
        return False
    # A single image dict, or the grouped `defaults:`/`images:`/type-key form.
    return (
@@ -532,18 +662,8 @@ def _flatten_legacy_image_config(config: object) -> list[dict]:

    def _add(entry: dict, extra: dict) -> None:
        merged = {**defaults, **extra, **entry}
-        # The legacy `defaults:`/type-grouped forms only applied `byte_order` to
-        # types that support it. Replicate that so an endian default merged into
-        # e.g. a binary image stays valid.
-        type_class = IMAGE_TYPE.get(str(merged.get(CONF_TYPE, "")).upper())
-        if (
-            CONF_BYTE_ORDER in merged
-            and isinstance(type_class, type)
-            and issubclass(type_class, ImageEncoder)
-            and not type_class.is_endian()
-        ):
-            del merged[CONF_BYTE_ORDER]
-        result.append(merged)
+        # Always drop, matching the pre-platform behavior -- see `_drop_incompatible_byte_order`.
+        result.append(_drop_incompatible_byte_order(merged, {}))

    def _add_entries(entries: object, extra: dict) -> None:
        # `entries` may be a single image dict or a list of them; non-dict
@@ -22,7 +22,7 @@ CONFIG_SCHEMA = (
 )


-def validate_logger(config):
+def validate_logger(config) -> None:
    logger_conf = fv.full_config.get()[CONF_LOGGER]
    if logger_conf[CONF_BAUD_RATE] == 0:
        raise cv.Invalid("improv_serial requires the logger baud_rate to be not 0")
@@ -33,7 +33,6 @@ def validate_logger(config):
        raise cv.Invalid(
            "improv_serial does not support the selected logger hardware_uart"
        )
-    return config


 FINAL_VALIDATE_SCHEMA = validate_logger
@@ -146,13 +146,12 @@ CONFIG_SCHEMA = cv.All(
 )


-def _validate_cpu_frequency(config):
+def _validate_cpu_frequency(config) -> None:
    esp32_config = fv.full_config.get()[PLATFORM_ESP32]
    if esp32_config[CONF_CPU_FREQUENCY] != "240MHZ":
        raise cv.Invalid(
            "Inkplate requires 240MHz CPU frequency (set in esp32 component)"
        )
-    return config


 FINAL_VALIDATE_SCHEMA = _validate_cpu_frequency
@@ -9,7 +9,7 @@ uint32_t temp_single_get_current_temperature(uint32_t *temp_value);

 namespace esphome::internal_temperature {

-static const char *const TAG = "internal_temperature.bk72xx";
+static const char *const TAG = "internal_temperature";

 void InternalTemperatureSensor::update() {
  float temperature = NAN;
@@ -16,7 +16,7 @@ uint8_t temprature_sens_read();

 namespace esphome::internal_temperature {

-static const char *const TAG = "internal_temperature.esp32";
+static const char *const TAG = "internal_temperature";

 void InternalTemperatureSensor::update() {
  float temperature = NAN;
@@ -16,7 +16,7 @@

 namespace esphome::internal_temperature {

-static const char *const TAG = "internal_temperature.rp2";
+static const char *const TAG = "internal_temperature";

 // The on-die temperature sensor sits on the last ADC channel: input 4 on RP2040
 // and RP2350A, but input 8 on RP2350B, which has eight external channels rather
@@ -8,7 +8,7 @@

 namespace esphome::internal_temperature {

-static const char *const TAG = "internal_temperature.zephyr";
+static const char *const TAG = "internal_temperature";

 static const struct device *const DIE_TEMPERATURE_SENSOR = DEVICE_DT_GET_ONE(nordic_nrf_temp);

@@ -336,7 +336,7 @@ def _customise_schema(config):
 CONFIG_SCHEMA = _customise_schema


-def _final_validate(config):
+def _final_validate(config) -> None:
    # IT8951 reads from SPI (DevInfo, VCOM, register reads) so MISO is required.
    spi.final_validate_device_schema("it8951", require_miso=True, require_mosi=True)(
        config
@@ -351,7 +351,6 @@ def _final_validate(config):
                config[CONF_UPDATE_INTERVAL] = update_interval("never")
        else:
            config[CONF_SHOW_TEST_CARD] = True
-    return config


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -89,8 +89,8 @@ CONFIG_SCHEMA = (
 )


-def _final_validate(config: ConfigType) -> ConfigType:
-    return modbus.final_validate_modbus_device("kuntze", role="client")(config)
+def _final_validate(config: ConfigType) -> None:
+    modbus.final_validate_modbus_device("kuntze", role="client")(config)


 FINAL_VALIDATE_SCHEMA = _final_validate
@@ -184,8 +184,6 @@ static int32_t get_firmware_int(const char *version_string) {
  return result;
 }

-float LD2420Component::get_setup_priority() const { return setup_priority::BUS; }
-
 void LD2420Component::dump_config() {
  ESP_LOGCONFIG(TAG,
                "LD2420:\n"
@@ -105,7 +105,6 @@ class LD2420Component final : public Component, public uart::UARTDevice {
  void apply_config_action();
  void factory_reset_action();
  void revert_config_action();
-  float get_setup_priority() const override;
  int send_cmd_from_array(CmdFrameT cmd_frame);
  void report_gate_data();
  void handle_cmd_error(uint16_t error);
@@ -84,7 +84,7 @@ CONFIG_SCHEMA = cv.Schema(
 )


-def final_validate(config: ConfigType) -> ConfigType:
+def final_validate(config: ConfigType) -> None:
    full_config = fv.full_config.get()
    hub_id = config[CONF_LD6002B_ID]

@@ -108,8 +108,6 @@ def final_validate(config: ConfigType) -> ConfigType:
                path=[CONF_WAKE],
            )

-    return config
-

 FINAL_VALIDATE_SCHEMA = final_validate

@@ -105,9 +105,9 @@ CONFIG_SCHEMA = cv.Schema(
 )


-def final_validate(config: ConfigType) -> ConfigType:
+def final_validate(config: ConfigType) -> None:
    if config.get(CONF_AREA_CONFIG) is None:
-        return config
+        return

    full_config = fv.full_config.get()
    hub_id = config[CONF_LD6002B_ID]
@@ -132,8 +132,6 @@ def final_validate(config: ConfigType) -> ConfigType:
            path=[CONF_AREA_CONFIG],
        )

-    return config
-

 FINAL_VALIDATE_SCHEMA = final_validate

@@ -182,6 +182,9 @@ def get_download_types(storage_json: StorageJSON = None):
    the shape stable so the download panel
    doesn't have to special-case per-platform schemas.
    """
+    # No recorded firmware path means nothing was built; no downloads.
+    if storage_json.firmware_bin_path is None:
+        return []
    types = [
        {
            "title": "UF2 package (recommended)",
--- a/Show More
+++ b/Show More