Release v1.61.0

HACS will install from the named asset instead of the auto zipball, so
GitHub's public download counter becomes a per-version install metric.
The workflow also has a manual dispatch to backfill an existing release.

.gitattributes

@@ -0,0 +1,14 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary
+*.mp4 binary
+*.webm binary
+*.zip binary
+*.woff binary
+*.woff2 binary

.github/workflows/announce.yml

@@ -0,0 +1,95 @@
+name: Announce release
+# Telegram notifications for t.me/ha_houseplan (owner request, 2026-08-07).
+# Stable releases are announced; prereleases are deliberately silent.
+# workflow_dispatch exists purely as a connectivity test button and therefore
+# remains allowed to send a test message.
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+  workflow_call:
+    inputs:
+      reusable:
+        required: true
+        type: boolean
+      tag:
+        required: true
+        type: string
+      release_name:
+        required: true
+        type: string
+      url:
+        required: true
+        type: string
+      prerelease:
+        required: true
+        type: boolean
+      ref:
+        required: true
+        type: string
+    secrets:
+      TELEGRAM_BOT_TOKEN:
+        required: true
+      TELEGRAM_CHAT_ID:
+        required: true
+permissions:
+  contents: read
+jobs:
+  telegram:
+    if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'release' && github.event.release.prerelease == false) || (github.event_name == 'workflow_call' && inputs.prerelease == false) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out release notes for a reusable call
+        if: ${{ inputs.reusable == true }}
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - name: Send to Telegram
+        env:
+          TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          CHAT: ${{ secrets.TELEGRAM_CHAT_ID }}
+          CALLED: ${{ inputs.reusable }}
+          INPUT_TAG: ${{ inputs.tag }}
+          INPUT_NAME: ${{ inputs.release_name }}
+          INPUT_URL: ${{ inputs.url }}
+          INPUT_PRE: ${{ inputs.prerelease }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          RELEASE_NAME: ${{ github.event.release.name }}
+          RELEASE_URL: ${{ github.event.release.html_url }}
+          RELEASE_PRE: ${{ github.event.release.prerelease }}
+          # The body goes through env, never through shell interpolation —
+          # release notes are arbitrary text.
+          RELEASE_BODY: ${{ github.event.release.body }}
+          EVENT: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          if [ "$EVENT" = "workflow_dispatch" ] && [ "$CALLED" != "true" ]; then
+            TEXT="✅ Тест: оповещения о релизах houseplan-card подключены."
+          else
+            if [ "$CALLED" = "true" ]; then
+              TAG=$INPUT_TAG
+              NAME=$INPUT_NAME
+              URL=$INPUT_URL
+              PRE=$INPUT_PRE
+              BODY=$(cat docs/RELEASE-NOTES.md)
+            else
+              TAG=$RELEASE_TAG
+              NAME=$RELEASE_NAME
+              URL=$RELEASE_URL
+              PRE=$RELEASE_PRE
+              BODY=$RELEASE_BODY
+            fi
+            if [ "$PRE" = "true" ]; then
+              echo "Prerelease Telegram announcement is disabled"
+              exit 0
+            fi
+            KIND="🏠 Релиз"
+            SUMMARY=$(printf '%s' "$BODY" | head -c 2500)
+            TEXT=$(printf '%s houseplan-card %s — %s\n\n%s\n\n%s' \
+              "$KIND" "$TAG" "$NAME" "$SUMMARY" "$URL")
+          fi
+          curl -sS --fail-with-body -X POST \
+            "https://api.telegram.org/bot$TOKEN/sendMessage" \
+            --data-urlencode "chat_id=$CHAT" \
+            --data-urlencode "text=$TEXT" \
+            -d disable_web_page_preview=true

.github/workflows/performance.yml

@@ -0,0 +1,172 @@
+name: Full Performance
+
+on:
+  # Every main promotion is a stable-release candidate and must have an
+  # exact-SHA full comparison before stable assets are published.
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "0 4 * * 1"
+  workflow_dispatch:
+    inputs:
+      comparison_ref:
+        description: "Optional baseline tag, branch or SHA; empty uses the candidate parent"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: full-performance-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  performance:
+    # Base and candidate stay sequential on one hosted runner. Splitting them
+    # across runners would turn machine variance into a false regression.
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Check out candidate
+        uses: actions/checkout@v4
+        with:
+          path: candidate
+          fetch-depth: 2
+
+      - name: Resolve comparison SHA
+        id: base
+        working-directory: candidate
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PUSH_BEFORE_SHA: ${{ github.event.before }}
+          MANUAL_BASE: ${{ inputs.comparison_ref }}
+        run: |
+          set -euo pipefail
+          if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+            git fetch --force --tags --prune --unshallow origin
+          else
+            git fetch --force --tags --prune origin
+          fi
+
+          if [ "$EVENT_NAME" = "workflow_dispatch" ] && [ -n "$MANUAL_BASE" ]; then
+            sha="$(git rev-parse "${MANUAL_BASE}^{commit}" 2>/dev/null || true)"
+            source="manual comparison ref $MANUAL_BASE"
+          elif [ "$EVENT_NAME" = "push" ] && [ -n "$PUSH_BEFORE_SHA" ] && ! printf '%s' "$PUSH_BEFORE_SHA" | grep -Eq '^0+$'; then
+            sha="$PUSH_BEFORE_SHA"
+            source="push before"
+          else
+            sha="$(git rev-parse HEAD^ 2>/dev/null || true)"
+            source="candidate parent"
+          fi
+          requested_sha="$sha"
+
+          usable=true
+          reason=""
+          if [ -z "$sha" ] || ! git cat-file -e "${sha}^{commit}" 2>/dev/null; then
+            usable=false
+            reason="commit is not present after fetching all remote refs"
+          elif [ "$source" = "push before" ] && ! git merge-base --is-ancestor "$sha" HEAD; then
+            usable=false
+            reason="commit is no longer an ancestor of the pushed revision"
+          fi
+
+          if [ "$usable" != true ]; then
+            parent_sha="$(git rev-parse HEAD^ 2>/dev/null || true)"
+            if [ -n "$parent_sha" ] && [ "$parent_sha" != "$(git rev-parse HEAD)" ]; then
+              sha="$parent_sha"
+              source="candidate parent (unusable requested-base fallback)"
+              echo "::warning::Comparison SHA ${requested_sha:-none} is unusable ($reason); using candidate parent $sha."
+              usable=true
+            fi
+          fi
+
+          if [ "$usable" != true ]; then
+            fallback_tag=""
+            fallback_sha=""
+            head_sha="$(git rev-parse HEAD)"
+            while IFS= read -r tag; do
+              case "$tag" in
+                v[0-9]*.[0-9]*.[0-9]*) ;;
+                *) continue ;;
+              esac
+              tag_sha="$(git rev-list -n 1 "$tag")"
+              if [ "$tag_sha" != "$head_sha" ]; then
+                fallback_tag="$tag"
+                fallback_sha="$tag_sha"
+                break
+              fi
+            done < <(git tag --merged HEAD --sort=-version:refname)
+            if [ -z "$fallback_sha" ]; then
+              echo "::error::No usable comparison commit or previous release tag is reachable from HEAD."
+              exit 1
+            fi
+            sha="$fallback_sha"
+            source="release tag $fallback_tag"
+            echo "::warning::Using $fallback_tag ($sha) as the comparison base."
+          fi
+
+          if ! git cat-file -e "${sha}:demo/bundle-freshness.mjs" 2>/dev/null; then
+            echo "::warning::Comparison $sha predates HP-PERF-01; using candidate parent HEAD^."
+            sha="$(git rev-parse HEAD^)"
+            source="candidate parent (HP-PERF-01 compatibility)"
+          fi
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          echo "Comparison base: $sha ($source)" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Check out base SHA
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.base.outputs.sha }}
+          path: baseline
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            candidate/package-lock.json
+            baseline/package-lock.json
+
+      - name: Install candidate and baseline dependencies
+        run: npm ci --prefix candidate && npm ci --prefix baseline
+
+      - name: Install pinned Chromium
+        working-directory: candidate
+        run: npx playwright install --with-deps chromium
+
+      - name: Build both exact source trees
+        run: |
+          npm --prefix candidate run build
+          cp candidate/dist/houseplan-card.js candidate/demo/srv/assets/houseplan-card.js
+          npm --prefix baseline run build
+          cp baseline/dist/houseplan-card.js baseline/demo/srv/assets/houseplan-card.js
+
+      - name: Capture base and candidate profiles
+        working-directory: candidate
+        run: |
+          npm run benchmark:large-house -- --target-root=../baseline --samples=7 --warmups=1 --output=../artifacts/performance/baseline.json
+          npm run benchmark:large-house -- --target-root=. --samples=7 --warmups=1 --output=../artifacts/performance/candidate.json
+          npm run benchmark:glow -- --profile=large-light-blend-v1 --target-root=../baseline --samples=7 --warmups=1 --output=../artifacts/performance/blend-baseline.json
+          npm run benchmark:glow -- --profile=large-light-blend-v1 --target-root=. --samples=7 --warmups=1 --output=../artifacts/performance/blend-candidate.json
+          npm run benchmark:glow -- --profile=large-house-glow-overlay-v1 --target-root=../baseline --samples=7 --warmups=1 --output=../artifacts/performance/overlay-baseline.json
+          npm run benchmark:glow -- --profile=large-house-glow-overlay-v1 --target-root=. --samples=7 --warmups=1 --output=../artifacts/performance/overlay-candidate.json
+          if ! grep -q "glow_enabled" ../baseline/src/logic.ts; then
+            echo "Base predates independent Glow; bootstrap relative overlay baseline, keep absolute gate"
+            cp ../artifacts/performance/overlay-candidate.json ../artifacts/performance/overlay-baseline.json
+          fi
+
+      - name: Enforce relative and absolute performance budgets
+        working-directory: candidate
+        run: |
+          npm run benchmark:compare -- --baseline=../artifacts/performance/baseline.json --candidate=../artifacts/performance/candidate.json --output=../artifacts/performance/comparison.json
+          npm run benchmark:compare -- --budgets=demo/performance/budgets-large-light-blend.json --baseline=../artifacts/performance/blend-baseline.json --candidate=../artifacts/performance/blend-candidate.json --output=../artifacts/performance/blend-comparison.json
+          npm run benchmark:compare -- --budgets=demo/performance/budgets-large-house-glow-overlay.json --baseline=../artifacts/performance/overlay-baseline.json --candidate=../artifacts/performance/overlay-candidate.json --output=../artifacts/performance/overlay-comparison.json
+
+      - name: Upload full performance reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: full-performance
+          path: artifacts/performance

.github/workflows/publish-prerelease.yml

@@ -0,0 +1,205 @@
+name: Publish prerelease
+run-name: Publish ${{ inputs.tag }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Exact prerelease tag, for example v1.61.0-beta.4"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  actions: read
+
+concurrency:
+  group: publish-prerelease-${{ inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      sha: ${{ steps.candidate.outputs.sha }}
+      tag: ${{ steps.candidate.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Pin the current dev candidate
+        id: candidate
+        env:
+          TAG: ${{ inputs.tag }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          test "$REF_NAME" = "dev" || {
+            echo "::error::Prereleases must be dispatched from the dev branch, got $REF_NAME"
+            exit 1
+          }
+          SHA=$(git rev-parse HEAD)
+          git fetch origin dev
+          test "$(git rev-parse origin/dev)" = "$SHA" || {
+            echo "::error::The dispatched SHA is no longer the origin/dev tip"
+            exit 1
+          }
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+      - name: Verify version, changelogs and bilingual release notes
+        env:
+          TAG: ${{ inputs.tag }}
+        run: node scripts/release-contract.mjs "$TAG" --repo="$GITHUB_REPOSITORY"
+      - name: Require green Validate for this exact SHA
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ steps.candidate.outputs.sha }}
+        run: node scripts/release-gate.mjs "$SHA"
+
+  publish:
+    needs: gate
+    runs-on: ubuntu-latest
+    outputs:
+      url: ${{ steps.verify.outputs.url }}
+      newly_published: ${{ steps.release.outputs.newly_published }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.gate.outputs.sha }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Build and verify both release assets before publication
+        env:
+          TAG: ${{ needs.gate.outputs.tag }}
+        run: |
+          set -euo pipefail
+          npm ci
+          npm run build
+          cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js
+          cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+          VERSION=${TAG#v}
+          grep -Fq "$VERSION" dist/houseplan-card.js
+          (cd custom_components/houseplan && zip -qr ../../houseplan.zip .)
+          unzip -l houseplan.zip | grep -q "manifest.json"
+          ZIP_VERSION=$(unzip -p houseplan.zip manifest.json | node -e \
+            "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>process.stdout.write(JSON.parse(s).version))")
+          test "$ZIP_VERSION" = "$VERSION" || {
+            echo "::error::houseplan.zip manifest version $ZIP_VERSION != $VERSION"
+            exit 1
+          }
+          test -s dist/houseplan-card.js
+          test -s houseplan.zip
+      - name: Create or verify the annotated tag
+        env:
+          TAG: ${{ needs.gate.outputs.tag }}
+          SHA: ${{ needs.gate.outputs.sha }}
+        run: |
+          set -euo pipefail
+          REMOTE=$(git ls-remote --tags origin "refs/tags/$TAG" "refs/tags/$TAG^{}")
+          if [ -n "$REMOTE" ]; then
+            PEELED=$(printf '%s\n' "$REMOTE" | awk -v ref="refs/tags/$TAG^{}" '$2 == ref {print $1}')
+            test -n "$PEELED" || {
+              echo "::error::Existing remote tag $TAG is not annotated"
+              exit 1
+            }
+            test "$PEELED" = "$SHA" || {
+              echo "::error::Existing tag $TAG points to $PEELED, expected $SHA"
+              exit 1
+            }
+            git fetch --force origin "refs/tags/$TAG:refs/tags/$TAG"
+            test "$(git cat-file -t "refs/tags/$TAG")" = "tag"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git tag -a "$TAG" "$SHA" -m "$TAG"
+            git push origin "$TAG"
+          fi
+      - name: Stage, verify and publish the prerelease
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.gate.outputs.tag }}
+        run: |
+          set -euo pipefail
+          if ! gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag \
+              --draft --prerelease --title "$TAG" --notes-file docs/RELEASE-NOTES.md
+          fi
+          WAS_DRAFT=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" --json isDraft --jq .isDraft)
+          echo "newly_published=$WAS_DRAFT" >> "$GITHUB_OUTPUT"
+          gh release upload "$TAG" dist/houseplan-card.js houseplan.zip \
+            --repo "$GITHUB_REPOSITORY" --clobber
+          RELEASE_JSON=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --json tagName,isDraft,isPrerelease,assets,url)
+          export RELEASE_JSON TAG
+          node <<'NODE'
+          const release = JSON.parse(process.env.RELEASE_JSON);
+          if (release.tagName !== process.env.TAG) throw new Error('release tag mismatch');
+          const assets = new Map(release.assets.map((asset) => [asset.name, asset]));
+          for (const name of ['houseplan-card.js', 'houseplan.zip']) {
+            if (!(Number(assets.get(name)?.size) > 0)) throw new Error(`${name} is missing or empty`);
+          }
+          NODE
+          gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --draft=false --prerelease \
+            --title "$TAG" --notes-file docs/RELEASE-NOTES.md
+      - name: Verify the public release and assets
+        id: verify
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.gate.outputs.tag }}
+          SHA: ${{ needs.gate.outputs.sha }}
+        run: |
+          set -euo pipefail
+          RELEASE_JSON=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --json tagName,isDraft,isPrerelease,assets,url)
+          export RELEASE_JSON TAG
+          node <<'NODE'
+          const release = JSON.parse(process.env.RELEASE_JSON);
+          if (release.tagName !== process.env.TAG || release.isDraft || !release.isPrerelease)
+            throw new Error('release is not a public prerelease for the requested tag');
+          const assets = new Map(release.assets.map((asset) => [asset.name, asset]));
+          for (const name of ['houseplan-card.js', 'houseplan.zip']) {
+            if (!(Number(assets.get(name)?.size) > 0)) throw new Error(`${name} is missing or empty`);
+          }
+          NODE
+          test "$(git rev-list -n 1 "$TAG")" = "$SHA"
+          URL=$(node -p "JSON.parse(process.env.RELEASE_JSON).url")
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+          printf '### Published %s\n\n- exact SHA: `%s`\n- [GitHub prerelease](%s)\n- assets: `houseplan-card.js`, `houseplan.zip`\n' \
+            "$TAG" "$SHA" "$URL" >> "$GITHUB_STEP_SUMMARY"
+      - name: Verify HACS prerelease discovery order
+        uses: actions/github-script@v7
+        env:
+          EXPECTED_TAG: ${{ needs.gate.outputs.tag }}
+        with:
+          script: |
+            const releases = await github.paginate(github.rest.repos.listReleases, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              per_page: 100,
+            });
+            const first = releases.find((release) => release.prerelease && !release.draft);
+            if (first?.tag_name !== process.env.EXPECTED_TAG) {
+              core.setFailed(
+                `HACS prerelease discovery is stale: ${first?.tag_name ?? 'none'} precedes ` +
+                process.env.EXPECTED_TAG,
+              );
+            }
+
+  announce:
+    needs: [gate, publish]
+    if: ${{ needs.publish.outputs.newly_published == 'true' }}
+    uses: ./.github/workflows/announce.yml
+    with:
+      reusable: true
+      tag: ${{ needs.gate.outputs.tag }}
+      release_name: ${{ needs.gate.outputs.tag }}
+      url: ${{ needs.publish.outputs.url }}
+      prerelease: true
+      ref: ${{ needs.gate.outputs.tag }}
+    secrets: inherit

.github/workflows/release-zip.yml

@@ -0,0 +1,40 @@
+name: Attach HACS zip to release
+# hacs.json declares zip_release + filename=houseplan.zip, so every release
+# (prereleases included) must carry the asset — HACS installs from it and
+# GitHub's public download counter becomes a free per-version install metric
+# (owner request, 2026-08-08). Like announce.yml, the workflow file lives at
+# the TAGGED commit: betas cut from dev pick it up as soon as this file is on
+# dev, stable tags once it reaches main.
+# workflow_dispatch lets us attach the zip to an EXISTING release (needed
+# once for the latest stable after the hacs.json change reaches main).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing release tag to attach the zip to"
+        required: true
+permissions:
+  contents: write
+jobs:
+  zip:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve tag
+        id: tag
+        env:
+          EVENT_TAG: ${{ github.event.release.tag_name }}
+          INPUT_TAG: ${{ github.event.inputs.tag }}
+        run: echo "tag=${EVENT_TAG:-$INPUT_TAG}" >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+      - name: Build houseplan.zip (contents of custom_components/houseplan at zip root)
+        run: cd custom_components/houseplan && zip -qr ../../houseplan.zip .
+      - name: Sanity check
+        run: unzip -l houseplan.zip | grep -q "manifest.json"
+      - name: Upload asset
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload "${{ steps.tag.outputs.tag }}" houseplan.zip --clobber --repo "$GITHUB_REPOSITORY"

.github/workflows/release.yml

@@ -4,16 +4,95 @@ on:
     types: [published]
 permissions:
   contents: write
+  actions: read
 jobs:
-  build:
+  # AUD-159B7-02: publishing a GitHub Release used to BE the gate — this
+  # workflow only built and uploaded, so an asset shipped while both Validate
+  # runs for the very same commit were red. The asset now waits for a green
+  # Validate of the EXACT commit the tag points at, and is withheld otherwise.
+  #
+  # Needs a push with a token that has the `workflow` scope (the ordinary
+  # Personal Access Token used for `git push` refuses workflow file updates).
+  gate:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Require a green Validate for this exact commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          # HEAD is the peeled commit even when TAG is annotated. Do not trust
+          # target_commitish (it may be a branch name) or an event-context SHA.
+          SHA=$(git rev-parse HEAD)
+          echo "release tag: $TAG; exact commit: $SHA"
+          node scripts/release-gate.mjs "$SHA"
+      - name: Require full performance for a stable release
+        if: ${{ !github.event.release.prerelease }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          SHA=$(git rev-parse HEAD)
+          node scripts/release-gate.mjs "$SHA" --workflow=performance.yml --label="Full Performance"
+  build:
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - run: npm ci && npm run build
+      - name: Verify compositor frame continuity for a stable release
+        if: ${{ !github.event.release.prerelease }}
+        run: |
+          npx playwright install --with-deps chromium
+          cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+          npm run continuity:screencast
+      - name: Upload failed continuity frames
+        if: ${{ failure() && !github.event.release.prerelease }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: continuity-screencast
+          path: artifacts/continuity-screencast
       - run: cp dist/houseplan-card.js custom_components/houseplan/frontend/
       - name: Attach card to release
         uses: softprops/action-gh-release@v2
         with:
           files: dist/houseplan-card.js
+  hacs-discovery:
+    # HACS 2.0.x takes the first prerelease in GitHub's response instead of
+    # sorting SemVer. A valid asset can therefore be invisible to beta users
+    # (beta.10 appeared after beta.9). Keep the release asset, but
+    # make that distribution failure impossible to miss in the release run.
+    if: ${{ github.event.release.prerelease }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify the published tag is the prerelease HACS will discover
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const releases = await github.paginate(github.rest.repos.listReleases, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              per_page: 100,
+            });
+            const first = releases.find((r) => r.prerelease && !r.draft);
+            const expected = context.payload.release.tag_name;
+            if (first?.tag_name !== expected) {
+              core.setFailed(
+                `HACS prerelease discovery is stale: GitHub returns ${first?.tag_name ?? 'none'} before ${expected}. ` +
+                `Use an rc/new version line or correct the release ordering before announcing the update.`,
+              );
+            }

.github/workflows/validate.yml

@@ -1,9 +1,19 @@
 name: Validate
+
 on:
   push:
+    # The branch commit is the release-gate authority. An annotated tag points
+    # to the same SHA and must not duplicate the browser validation jobs.
+    branches:
+      - '**'
   pull_request:
-  schedule:
-    - cron: "0 4 * * 1"
+
+# A new push supersedes an unfinished validation for the same branch or PR.
+# Exact-SHA release gates never depend on an obsolete commit.
+concurrency:
+  group: validate-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   hacs:
     runs-on: ubuntu-latest
@@ -13,18 +23,22 @@ jobs:
         uses: hacs/action@main
         with:
           category: integration
+
   hassfest:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: Hassfest validation
         uses: home-assistant/actions/hassfest@master
+
   frontend:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with: { node-version: 22 }
+        with:
+          node-version: 22
+          cache: npm
       - run: npm ci
       - name: Typecheck
         run: npm run typecheck
@@ -32,23 +46,25 @@ jobs:
         run: npm test
       - name: Build
         run: npm run build
-      - name: Card bundle in sync with integration
-        run: cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js
+      - name: Card bundle snapshots in sync
+        run: |
+          cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js
+          cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+
   smoke:
-    # audit T2: the end-to-end layer used to run only when a human remembered.
     # Gated on `frontend` so a typecheck failure does not burn browser minutes.
     needs: frontend
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with: { node-version: 22 }
+        with:
+          node-version: 22
+          cache: npm
       - run: npm ci
       - name: Install Chromium for Playwright
         run: npx playwright install --with-deps chromium
-      - name: Build a FRESH bundle for the smokes
-        # the committed demo/srv/assets copy is a snapshot; testing it would
-        # report green about code that no longer exists (audit T2)
+      - name: Build a fresh bundle for the smokes
         run: npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
       - name: Smoke suite
         run: |
@@ -72,10 +88,77 @@ jobs:
           name: smoke-logs
           path: /tmp/smoke-logs
 
+  golden:
+    # Deterministic visual correctness stays in every prerelease gate: it is
+    # inexpensive and catches a different class of regressions than timings.
+    needs: frontend
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Install pinned Chromium
+        run: npx playwright install --with-deps chromium
+      - name: Build the exact source under review
+        run: npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+      - name: Capture or verify golden matrix
+        id: golden
+        run: |
+          if find demo/golden/baselines -maxdepth 1 -name '*.png' -print -quit | grep -q .; then
+            echo "has_baselines=true" >> "$GITHUB_OUTPUT"
+            npm run golden:verify
+          else
+            echo "has_baselines=false" >> "$GITHUB_OUTPUT"
+            npm run golden:capture
+          fi
+      - name: Upload golden candidates/diffs
+        if: failure() || steps.golden.outputs.has_baselines == 'false'
+        uses: actions/upload-artifact@v4
+        with:
+          name: golden-images
+          path: artifacts/golden
+
+  performance_smoke:
+    # Candidate-only catastrophic-regression guard for ordinary pushes and
+    # prereleases. The expensive same-runner comparison lives in performance.yml.
+    needs: frontend
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Install pinned Chromium
+        run: npx playwright install --with-deps chromium
+      - name: Build the exact candidate source
+        run: npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+      - name: Capture the heaviest Glow state
+        run: |
+          npm run benchmark:glow -- --profile=large-house-glow-overlay-v1 --variants=60 --samples=3 --warmups=1 --output=artifacts/performance-smoke/candidate.json
+      - name: Enforce absolute smoke ceilings
+        run: |
+          npm run benchmark:compare -- --absolute-only --budgets=demo/performance/budgets-glow-smoke.json --candidate=artifacts/performance-smoke/candidate.json --output=artifacts/performance-smoke/comparison.json
+      - name: Upload performance smoke report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: performance-smoke
+          path: artifacts/performance-smoke
+
   backend:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      # Browser fixtures are generated by their real ESM factories and then
+      # validated through the Python CONFIG_SCHEMA/LAYOUT_SCHEMA in the same test.
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
       - uses: actions/setup-python@v5
         with: { python-version: "3.13" }
       - run: pip install pytest voluptuous pytest-homeassistant-custom-component home-assistant-frontend

.gitignore

@@ -4,3 +4,5 @@ test-build/
 *.log
 __pycache__/
 .pytest_cache/
+.venv-backend/
+artifacts/

AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+House Plan is one HACS package with two parts plus a demo harness:
+
+- **Lovelace card** (`src/`, TypeScript + Lit) — the primary product, bundled to `dist/houseplan-card.js`.
+- **Storage integration** (`custom_components/houseplan/`, Python) — the Home Assistant backend.
+- **Demo harness** (`demo/`) — a self-contained Playwright page (`demo/srv/demo.html`) that renders the card against a fake `hass`, used for screenshots and the `smoke_*.mjs` end-to-end suite.
+
+Standard commands live in `package.json` scripts, `CONTRIBUTING.md`, and `docs/DEVELOPMENT.md`. Read `docs/ARCHITECTURE.md` and `docs/STATUS.md` before non-trivial changes.
+
+## Canonical backlog
+
+GitHub is the only active backlog for House Plan:
+
+- [GitHub Issues](https://github.com/Matysh/houseplan-card/issues) are the
+  canonical task records: problem, scope, acceptance criteria and discussion.
+- [GitHub Projects (v2)](https://github.com/users/Matysh/projects/1) is
+  the canonical prioritization and workflow-status view. Every open in-scope
+  issue must be present there.
+
+Before starting planned work, find or create its issue and keep its description,
+labels and Project status current as decisions and implementation state change.
+Close an issue only after the result is verified. Specs, audits and ADRs may
+remain under `docs/`, but must link to their issue and must not become a parallel
+task list. When repository documentation disagrees with Issues or Project v2,
+the GitHub backlog wins.
+
+## Cursor Cloud specific instructions
+
+The startup update script already runs `npm ci`, provisions a Python 3.13 backend venv at `.venv-backend`, and installs Playwright Chromium. You do not need to reinstall dependencies.
+
+- **Frontend** (from repo root): `npm run typecheck`, `npm test` (node:test, 424 tests at v1.60.0), `npm run build`. After building, keep both committed snapshots in sync — `cp dist/houseplan-card.js custom_components/houseplan/frontend/` and `cp dist/houseplan-card.js demo/srv/assets/`. CI enforces both comparisons byte-for-byte.
+- **Backend HA-harness tests need Python 3.13, not the system 3.12.** Run them with the venv: `.venv-backend/bin/python -m pytest tests_backend/ -q` (150 tests at v1.60.0: 100 pure + 50 HA harness). Running `python3 -m pytest tests_backend` without Home Assistant silently **skips** the `test_ha_*.py` harness tests (`conftest.py` ignores them when `homeassistant` is not importable) and runs only the pure set.
+- **Running the app / smoke suite**: build a fresh bundle and copy it into the demo assets first — `npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` — then run `node demo/smoke_*.mjs`. The committed demo snapshot must remain byte-identical to `dist` (CI checks it); rebuilding first also guarantees the browser suite tests the current source in an uncommitted worktree. No real Home Assistant server is required: `demo/srv/demo.html` stubs `hass`, registries and `callService`.
+- **Golden images**: `npm run golden:capture` and `npm run golden:verify` refuse a stale demo bundle. Build and copy the current bundle first, then review `artifacts/golden/actual/` and `diff/`. Update baselines only with `npm run golden:accept -- --reviewed`, using the complete Linux CI artifact; never accept a partial scenario or images merely to make CI green. See `demo/golden/README.md`.
+- **Freshness contract**: the embedded fingerprint covers `src/` plus Rollup, TypeScript and package-lock build inputs. Benchmark and golden tooling must call `assertFreshDemoBundle` before recording any result; a missing or mismatched fingerprint is a hard failure, not a warning.
+- **Demo harness render quirk**: the fake `hass` in `demo.html` is set once, so opening the page directly in a browser renders the floor plan but **device icons only appear after a re-render** (an F5 refresh, or nudging `card.hass = {...card.hass}`). The smoke launcher `demo/serve.mjs` already does this nudge; a plain browser session does not. This is a harness limitation, not a card bug.
+- **Known environment-sensitive smoke**: `demo/smoke_opening_measure.mjs` fails two sub-checks (`place_dialog_x_magnetised`, `place_committed_x_center`) under the pinned Chromium — a `1e-6`-tolerance magnet-snap on the opening-*placement* path. It reproduces against the pristine committed bundle, so treat it as pre-existing/pixel-precision, not a regression you introduced.
+- **Owner's local Windows checkout is invisible here.** Path
+  `C:\Users\Sergey\Downloads\dev\houseplan-dev` (workflow notes + often
+  unpushed edits) is **not mounted** into managed Cloud Agent VMs. Do not
+  expect to `ls` or diff that folder. To bring local work into the cloud
+  agent: push a branch to GitHub and say its name, or run a **local** Cursor
+  Agent / My Machines worker inside that checkout. Day-to-day source of truth
+  for cloud sessions remains **`origin/dev`** (minors) and **`origin/main`**
+  (releases) — see `docs/STATUS.md`.
+
+## Promotion rule
+
+Every new feature or material behaviour change must be published as a beta/RC
+before it can enter a stable release, even when its local audit is clean. The
+stable release commit is promotion-only: version fields, generated bundle
+snapshots and changelog/release metadata. Do not add feature source code in
+that commit. An explicit owner-requested emergency hotfix is the only exception
+and must be called out in the release handoff.

CONTRIBUTING.md

@@ -16,6 +16,16 @@ writing code? The **[Telegram chat @ha_houseplan](https://t.me/ha_houseplan)**
 is the quickest route to the author and other users. Bugs and concrete feature
 requests still belong in [issues](https://github.com/Matysh/houseplan-card/issues).
 
+## Backlog and work status
+
+[GitHub Issues](https://github.com/Matysh/houseplan-card/issues) and the linked
+[GitHub Project v2](https://github.com/users/Matysh/projects/1) are the
+only active project backlog. Issues own scope and acceptance criteria; Project
+v2 owns prioritization and workflow status. Before starting planned work, link
+it to an existing issue or create one, add it to the Project, and keep both
+surfaces current until the verified result is closed. Design specs and ADRs may
+support an issue, but they do not replace it or maintain a separate checklist.
+
 ## Five-minute setup
 
 ```bash

README.md

@@ -5,6 +5,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/Matysh/houseplan-card)](https://github.com/Matysh/houseplan-card/stargazers)
 [![CI](https://github.com/Matysh/houseplan-card/actions/workflows/validate.yml/badge.svg)](https://github.com/Matysh/houseplan-card/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Live demo](https://img.shields.io/badge/demo-try_it_live-00c853?logo=homeassistant&logoColor=white)](https://demo.houseplan.tech)
 [![Telegram chat](https://img.shields.io/badge/Telegram-chat-2CA5E0?logo=telegram&logoColor=white)](https://t.me/ha_houseplan)
 
 **Turn Home Assistant into a live, interactive map of your home.** Upload or draw
@@ -14,25 +15,58 @@ room, Zigbee signal maps, glowing light pools and a fullscreen kiosk mode for wa
 tablets. No YAML, no Inkscape, no external editors — the whole floorplan lives
 right on your Lovelace dashboard.
 
+> **Use a desktop computer to edit plans.** View and kiosk are fully supported
+> on phones and tablets. The editors are designed primarily for a desktop
+> browser with a mouse and keyboard; individual editing operations on touch
+> devices may be awkward, limited, or unavailable.
+
 ![Interactive Home Assistant floor plan: live rooms, devices, lights and climate on a real floorplan card](docs/images/demo.gif)
 
+> ### 🚀 Try it live — no install needed
+> **[demo.houseplan.tech](https://demo.houseplan.tech)** — a real Home Assistant
+> with a ready-made plan. Log in as **`demo`** / **`demo`** and click anything:
+> toggle lights, open the editors, break things. The stand resets itself to a
+> pristine state every hour.
+
 🇷🇺 [Документация на русском](README.ru.md) · 💬 [Telegram chat: **@ha_houseplan**](https://t.me/ha_houseplan)
 
 **Feature highlights**
 
+- ♾️ **An infinite canvas** — there is no "plan size" and no edge to run
+  past: draw and place devices anywhere, pan at any zoom, zoom out to see
+  everything, and let one tap fit the whole plan back on screen.
 - 🖱 **GUI-first floorplan editor** — rooms, doors & windows, island rooms,
-  virtual walls and a visual decor layer, all drawn with clicks; smart
+  virtual walls and a visual decor layer, all drawn with clicks; room resize
+  by dragging walls, with live lengths and areas as you drag; smart
   alignment guides and a live ruler in real meters/feet.
+- 🖼 **A backdrop you can move and scale** — drag the floor-plan picture into
+  place and pull a corner to size it, with its real size in metres shown as
+  you drag, so the drawing and the photo of your plan finally line up.
 - 💡 **Lights toggle on click** out of the box; wall-switch markers can control
   whole groups of lights (works for dumb switches and stateless remotes too).
-- 🌒 **“Light sources” fill** — a dark house where every lit lamp casts a pool
-  of its own color that spills through doorways and open zone boundaries.
+- 🌒 **“Light sources” fill** — a dark house where every lit lamp lights exactly
+  the floor it can see: through doorways and open boundaries, stopped by walls,
+  columns and partitions, which cast real shadows.
+- ☀️ **The sun on the plan** — set the compass and the backdrop lives with
+  the day (white noon → golden hour → deep night), while windows on exterior
+  walls cast real wedges of sunlight into the rooms; optional cloud cover
+  from a weather entity.
+- 🪟 **Curtains and blinds open on a tap** — one action opens, closes or
+  stops a cover, and the icon itself morphs between open and closed while a
+  soft ring pulses as it travels.
 - 🌡 **Room cards** with temperature, humidity, Zigbee LQI and light count;
   comfort-range temperature fills, per-room signal heatmap.
 - 🚪 **Doors, windows and locks** with contact sensors — unlocking is always an
   explicit button, never an accidental tap.
 - 📺 **Kiosk mode** for wall tablets and TVs: fullscreen, swipe between floors,
   auto-carousel, per-screen icon sizes.
+- 🤖 **Live robot vacuums** — the dock marker stays put while a round puck
+  drives the plan in real time, pouring its path out from under itself;
+  current and previous cleanup runs are recorded server-side. Calibration is
+  one click (rooms matched by name) or a drag-and-stretch overlay. A diagnostic
+  source picker also covers registry-less map cameras without silently
+  rebinding broken sources. Works with Xiaomi Cloud Map Extractor, Tasshack
+  dreame-vacuum and Valetudo.
 - 🔔 New devices appear automatically with a red “new” dot; the layout is stored
   **server-side** — one shared plan for every user and screen, synced live.
 
@@ -58,16 +92,27 @@ The integration consists of two parts that are installed together:
 
 ## How it differs from alternatives
 
-A house plan in Home Assistant is usually built with `picture-elements`, `ha-floorplan` and similar solutions. There you have to write YAML by hand, calculate the coordinates of every icon, and edit the config again after every change. House Plan works differently:
+A house plan in Home Assistant is usually built with `picture-elements`,
+`ha-floorplan`, or newer GUI cards that draw walls and furniture in the
+dashboard. Those either lock you into YAML/SVG, or store the plan in the
+Lovelace card config. House Plan is a **shared live map** backed by a Home
+Assistant integration:
 
-| | House Plan | Typical solutions (picture-elements / ha-floorplan) |
-|---|---|---|
-| **Setup** | Entirely through the UI, with the mouse | Manual YAML and code editing |
-| **Adding devices** | Automatic, by room | You type in every entity by hand |
-| **Icon coordinates** | Drag with the mouse | You count pixels and write them into the config |
-| **Room markup** | Built-in outline editor | You draw in an external SVG editor |
-| **Storage** | On the HA server (shared by all devices) | In the dashboard YAML |
-| **Zoom** | Smooth zoom, everything stays crisp (vector) | Usually a fixed image |
+| | House Plan | picture-elements / ha-floorplan | GUI draw cards (e.g. easy-floorplan) |
+|---|---|---|---|
+| **Setup** | Entirely through the UI, with the mouse | Manual YAML / Inkscape SVG | In-card drawing of walls & furniture |
+| **Adding devices** | Automatic, by HA **area** | You type every entity by hand | Place entities by hand on the drawing |
+| **Icon coordinates** | Drag with the mouse | Count pixels into YAML | Drag on the canvas |
+| **Room markup** | Built-in outline editor bound to areas | External SVG editor | Draw walls yourself (furniture CAD) |
+| **Storage** | On the HA server (`.storage`, shared, multi-client) | In the dashboard YAML | In the card / dashboard YAML |
+| **Overlays** | Glow, climate, LQI, sun, vacuums, kiosk | Whatever you script in SVG/CSS | Varies by card |
+| **Zoom** | Smooth vector zoom | Usually a fixed image | SVG / virtual canvas |
+
+**One sentence:** House Plan is the shared, area-aware live map of your home —
+not a general-purpose CAD package. Its Background editor covers practical
+decor, labels and furniture; if you need unrestricted architectural drafting,
+a draw-centric tool may fit better. With a plan and HA areas, House Plan keeps
+every tablet on the same live layout.
 
 Key advantages in short:
 
@@ -75,6 +120,18 @@ Key advantages in short:
 - **Automatic device placement.** Outline a room and bind it to a Home Assistant area — the devices of that area appear on the plan by themselves.
 - **Manual additions of your own.** Any device, group or even a "virtual" point can be placed on the plan manually, with a name, icon, model, link and an attached PDF manual.
 - **Live states.** Temperature, Zigbee signal strength, on/off, open/closed — everything updates in real time.
+  Icon colors follow one principle — **yellow means the device is doing its main job right now**:
+  a light is shining, a socket is powering, a fan is spinning, a vacuum is
+  cleaning, a radiator valve is actually heating (not merely enabled). For climate integrations,
+  a reported work action is authoritative; when an integration exposes only its enabled HVAC mode,
+  that mode is the best available fallback. Orange = open / unlocked.
+  A pulsing red ring = an emergency (leak, smoke, gas). An RGB bulb's colour lives in its glow
+  spot (glow fill), where the spot itself is the on/off indicator and the badge stays standard.
+  A translucent icon = unavailable. Dark = idle.
+- **A coherent visual Background editor.** Draw lines/shapes, place labels and
+  furniture, edit physical styles and transform every object with the same
+  selection model. The plan image has its own move/resize/rotate tool, numeric
+  properties and shared Undo/Redo.
 - **Crisp zoom.** Zooming in does not "blur" the picture: the plan, labels and icons remain vector-sharp at any scale.
 
 ---
@@ -156,7 +213,7 @@ for each floor (names prefilled, a plan image is asked for one by one; any floor
 
 ![Empty plan — prompt to add a space](docs/images/02-onboarding-empty.png)
 
-In the dialog, set a **name** (for example, "1st floor") and **upload a background** — a floor-plan image in SVG, PNG or JPG format. Both fields are required: without a plan the "Save" button stays disabled.
+In the dialog, set a **name** (for example, "1st floor") and pick the background: **upload** a floor-plan image (SVG, PNG, JPG, WebP), **choose one already uploaded** to the server earlier, or select **"no background, I'll draw the rooms"** for a hand-drawn space. The canvas is infinite; an image keeps its own proportions by default and can be moved, resized or rotated at any time in the Background editor.
 
 ![Space creation dialog](docs/images/03-space-dialog.png)
 
@@ -180,15 +237,17 @@ Rooms may not overlap: a click strictly inside an existing room, or an outline t
 - **Split** — click a room, then two points on its walls; the chord cuts it in two. The bigger part stays the room it was (name, area, devices); the smaller one asks for a new name and area.
 
 
-### Doors, windows and locks
+### Doors, windows, gates and locks
 
-In markup mode the **"Opening"** tool places doors and windows: click next to a wall and the
+In markup mode the **"Opening"** tool places doors, windows and gates: click next to a wall and the
 opening snaps onto it. Pick the type, the **length in real centimetres** (defaults: door 90 cm,
-window 120 cm), an open/close sensor and — for doors — a **lock entity**.
+window 120 cm, gate 300 cm), an open/close sensor and — for doors and gates — a **lock entity**.
 
 With a sensor bound, the plan comes alive: the door leaf swings on its hinge and the swing arc
 draws itself in as the real door opens; a window opens its two casements. While open, the moving
-parts take an accent colour. A door with a lock shows a padlock badge next to it — green when
+parts take an accent colour. A gate keeps a 3–4 m opening compact on the plan: two half-width
+leaves open only 10° outwards, without a full-width swing arc, while contact, lock and light
+passage work exactly like a door. A door or gate with a lock shows a padlock badge next to it — green when
 locked, orange when unlocked. For safety the lock can **not** be toggled from the plan; a click
 on the opening shows a status card with both states instead.
 
@@ -199,7 +258,7 @@ walls** (it slides around corners too), and a **double click opens its propertie
 
 As soon as you save a room bound to an area, **the devices of that area are automatically laid out inside the outline**. These are the same devices shown on the **Settings → Devices → (filtered by the room)** page — only the meaningful ones, without service records, bridges and duplicates.
 
-By default only meaningful devices make it onto the plan — service records, bridges and duplicates are filtered out. If you need to see **absolutely all** devices of the area, enable the **👁 "Show all devices"** button in the header.
+By default only meaningful devices make it onto the plan: non-physical ones (service records, bridges, scenes, individual lamps folded into a light group) arrive with the **"Hide device from plan"** checkbox already ticked. The checkbox is yours from then on — every device dialog has it, virtual devices included. To see and un-hide them, open the device editor and press **"Hidden and disabled"**: user-hidden devices appear as translucent blue ghosts, a click opens the dialog. Hidden devices still count toward the room's Zigbee signal, but cast no light. A device disabled in Home Assistant appears there as a labelled grey service ghost and is excluded from all plan data/actions until it is enabled in HA again.
 
 From here on you can just use the plan: clicking an icon opens the device card with the model, link and a button to jump into Home Assistant.
 
@@ -248,6 +307,10 @@ turned the way it is mounted.
 
 ![Adding a device manually](docs/images/07-marker-dialog.png)
 
+### Styling the plan with card-mod (advanced, unsupported)
+
+The card ships finished and has no CSS field of its own — but if you already run [card-mod](https://github.com/thomasloven/lovelace-card-mod), every object on the plan now carries a stable hook you can aim at: `data-hp="device"` (plus `data-entity`, `data-area`), `data-hp="room"`, `data-hp="opening"`, `data-hp="decor"`, `data-hp="room-label"`, `data-hp="space-tab"`. We promise not to rename them; we do not ship card-mod, do not support it, and are not responsible for what your CSS does to the card. The full table, the examples and the limits are in **[docs/STYLING-HOOKS.md](docs/STYLING-HOOKS.md)**.
+
 ---
 
 ## Uninstalling
@@ -281,7 +344,7 @@ Services → House Plan**.
 
 **Do I need to write anything in YAML?** No. The only line is adding the card to the dashboard; everything else is done with the mouse.
 
-**My devices did not appear on the plan.** A device appears only if its Home Assistant area is bound to a drawn room. Check that the device has a room assigned (Settings → Devices) and that the room is outlined and bound to that area. If the device exists but is hidden by curation (bridges, service records, duplicates) — enable the **👁 "Show all devices"** button in the header.
+**My devices did not appear on the plan.** A device appears only if its Home Assistant area is bound to a drawn room. Check that the device has a room assigned (Settings → Devices) and that the room is outlined and bound to that area. Open the device editor and press **"Hidden and disabled"**: a blue ghost is user-hidden and can be shown; a grey disabled ghost must first be enabled in Home Assistant.
 
 **Can I hide an unwanted device or rename it?** Yes — click the device on the plan and press "Edit" in its card: there you can change the name, icon, model or hide the icon.
 

README.ru.md

@@ -3,8 +3,11 @@
 [![HACS Custom](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)
 [![GitHub release](https://img.shields.io/github/v/release/Matysh/houseplan-card)](https://github.com/Matysh/houseplan-card/releases)
 [![GitHub stars](https://img.shields.io/github/stars/Matysh/houseplan-card)](https://github.com/Matysh/houseplan-card/stargazers)
+[![Live demo](https://img.shields.io/badge/демо-попробовать-00c853?logo=homeassistant&logoColor=white)](https://demo.houseplan.tech)
 [![Telegram chat](https://img.shields.io/badge/Telegram-чат-2CA5E0?logo=telegram&logoColor=white)](https://t.me/ha_houseplan)
 
+📘 **[Полное руководство пользователя](docs/USER-GUIDE.ru.md)** · 🗂 **[Беклог проекта](https://github.com/users/Matysh/projects/1)**
+
 **Превратите Home Assistant в живую интерактивную карту дома.** Загрузите или
 нарисуйте план этажа, обведите комнаты мышкой — и умные устройства появятся на
 своих местах: живые состояния, свет по клику, температура и влажность по
@@ -12,25 +15,56 @@
 киоск-режим для настенного планшета. Без YAML, без Inkscape и внешних
 редакторов — весь план настраивается прямо на дашборде.
 
+> **Редактировать планы рекомендуется на компьютере.** Режим просмотра и
+> киоск полноценно поддерживаются на телефонах и планшетах. Редакторы рассчитаны
+> прежде всего на desktop с мышью и клавиатурой: на touch-устройстве отдельные
+> операции могут быть менее удобны, работать ограниченно или отсутствовать.
+
 ![Интерактивный план дома для Home Assistant: комнаты, устройства, свет и климат на реальном поэтажном плане](docs/images/demo.gif)
 
+> ### 🚀 Попробовать вживую — без установки
+> **[demo.houseplan.tech](https://demo.houseplan.tech)** — настоящий Home
+> Assistant с готовым планом. Вход **`demo`** / **`demo`**, можно нажимать всё:
+> включать свет, открывать редакторы, ломать что угодно. Каждый час стенд сам
+> возвращается в исходное состояние.
+
 🇬🇧 [Documentation in English](README.md) · 💬 [Чат в Telegram: **@ha_houseplan**](https://t.me/ha_houseplan)
 
 **Главное**
 
-- 🖱 **Редакторы прямо в карточке** — комнаты, двери и окна, комнаты-острова,
-  виртуальные стены и декор-слой рисуются кликами; помощник выравнивания и
+- ♾️ **Бесконечный холст** — нет «размера плана» и нет края, за который
+  нельзя выйти: рисуйте и ставьте устройства где угодно, тащите план на
+  любом зуме, отдаляйтесь, чтобы увидеть всё, и одной кнопкой вписывайте
+  план обратно в экран.
+- 🖱 **Редакторы прямо в карточке** — комнаты, двери, окна и ворота, комнаты-острова,
+  виртуальные стены и декор-слой рисуются кликами; размеры комнат меняются
+  перетаскиванием стен с живыми длинами и площадями; помощник выравнивания и
   линейка в реальных метрах.
 - 💡 **Свет переключается кликом** из коробки; значок выключателя может
   управлять группой ламп (в т.ч. «тупые» выключатели и кнопки-пульты).
 - 🌒 **Заливка «Свет по источникам»** — тёмный дом, где каждая горящая лампа
-  даёт пятно своего цвета, проникающее через дверные проёмы и открытые зоны.
+  освещает ровно тот пол, который видит: через проёмы и открытые границы,
+  а стены, колонны и перегородки его не пропускают и дают настоящие тени.
+- ☀️ **Солнце на плане** — задайте компас, и фон живёт вместе с днём
+  (белый полдень → золотой час → глубокая ночь), а окна внешних стен пускают
+  в комнаты настоящие клинья солнечного света; облачность — опционально, от
+  weather-сущности.
+- 🪟 **Шторы открываются тапом** — одно действие открывает, закрывает или
+  останавливает штору, а сам значок морфится между открытым и закрытым
+  видом и мягко пульсирует кольцом, пока штора едет.
 - 🌡 **Карточки комнат**: температура, влажность, Zigbee-сигнал, свет «1 из 3»;
   температурная заливка по комфортным границам.
 - 🚪 **Двери, окна и замки** с датчиками — отпирание только явной кнопкой,
   никогда случайным тапом.
 - 📺 **Киоск-режим** для настенных планшетов и ТВ: полноэкранно, свайп между
   этажами, автокарусель, свои размеры на каждом экране.
+- 🤖 **Роботы-пылесосы вживую** — маркер-база стоит на месте, а круглая
+  шайба ездит по плану в реальном времени, «выливая» путь из-под себя;
+  текущая и прошлая уборки хранятся на сервере. Калибровка — в один клик
+  (по именам комнат) или перетаскиванием призрака карты. Диагностика и явный
+  выбор источника поддерживают registry-less камеры карт и не подменяют молча
+  сломавшуюся привязку. Работают Xiaomi Cloud Map Extractor, dreame-vacuum
+  (Tasshack) и Valetudo.
 - 🔔 Новые устройства сами появляются на плане с красной точкой; раскладка
   хранится **на сервере HA** — один план для всех экранов, живая синхронизация.
 
@@ -57,16 +91,26 @@ House Plan показывает ваш умный дом так, как он в
 
 ## Чем отличается от аналогов
 
-Обычно план дома в Home Assistant делают через `picture-elements`, `ha-floorplan` и подобные решения. Там приходится вручную писать YAML, вычислять координаты каждой иконки и заново править конфиг при каждом изменении. House Plan устроен иначе:
+Обычно план дома в Home Assistant делают через `picture-elements`, `ha-floorplan`
+или новые GUI-карточки, где стены и мебель рисуют прямо на дашборде. Там либо
+YAML/SVG, либо конфиг живёт в YAML карточки. House Plan — это **общий живой
+план** на серверной интеграции Home Assistant:
 
-| | House Plan | Обычные решения (picture-elements / ha-floorplan) |
-|---|---|---|
-| **Настройка** | Полностью через интерфейс, мышкой | Ручной YAML и правка кода |
-| **Добавление устройств** | Автоматически по комнатам | Каждую сущность вписываете руками |
-| **Координаты иконок** | Перетаскиваете мышью | Считаете пиксели и пишете в конфиг |
-| **Разметка комнат** | Встроенный редактор контуров | Рисуете в стороннем редакторе SVG |
-| **Хранение** | На сервере HA (общее для всех устройств) | В YAML дашборда |
-| **Масштаб** | Плавный зум, всё остаётся чётким (вектор) | Обычно фиксированная картинка |
+| | House Plan | picture-elements / ha-floorplan | GUI-рисовалки (напр. easy-floorplan) |
+|---|---|---|---|
+| **Настройка** | Полностью через интерфейс, мышкой | Ручной YAML / Inkscape SVG | Рисование стен и мебели в карточке |
+| **Добавление устройств** | Автоматически по **зоне** HA | Каждую сущность вписываете руками | Ставите сущности руками на чертёж |
+| **Координаты иконок** | Перетаскиваете мышью | Считаете пиксели в YAML | Drag на холсте |
+| **Разметка комнат** | Встроенный редактор контуров, привязка к зонам | Сторонний SVG-редактор | Сами рисуете стены (мебельный CAD) |
+| **Хранение** | На сервере HA (`.storage`, общее, multi-client) | В YAML дашборда | В карточке / YAML дашборда |
+| **Оверлеи** | Glow, климат, LQI, солнце, пылесосы, киоск | Что пропишете в SVG/CSS | Зависит от карточки |
+| **Масштаб** | Плавный векторный зум | Обычно фиксированная картинка | SVG / виртуальный холст |
+
+**Одной фразой:** House Plan — это общая, area-aware живая карта дома, а не
+универсальная CAD-система. Редактор подложки покрывает практический декор,
+надписи и мебель; для свободного архитектурного черчения лучше отдельный
+draw-инструмент. При наличии плана и зон HA House Plan держит один живой layout
+на всех планшетах.
 
 Ключевые преимущества коротко:
 
@@ -74,6 +118,15 @@ House Plan показывает ваш умный дом так, как он в
 - **Автоматическое добавление устройств.** Обвели комнату и привязали её к зоне Home Assistant — устройства этой зоны сами появляются на плане.
 - **Ручное добавление своих.** Любое устройство, группу или даже «виртуальную» точку можно поставить на план вручную, задать имя, иконку, модель, ссылку и приложить PDF-инструкцию.
 - **Живые состояния.** Температура, уровень сигнала Zigbee, вкл/выкл, открыто/закрыто — всё обновляется в реальном времени.
+  Цвета значков подчиняются одному принципу — **жёлтый значит «устройство прямо сейчас выполняет свою основную работу»**:
+  лампа светит, розетка подаёт, вентилятор крутится, пылесос убирает, термоголовка
+  реально греет (а не просто включена). Для climate-сущностей переданное действие приоритетно;
+  если интеграция сообщает только включённый HVAC-режим, он служит лучшим доступным приближением.
+  Оранжевый = открыто / не заперто. Пульсирующее красное
+  кольцо = авария (протечка, дым, газ). Цвет RGB-лампы живёт в её пятне света (режим glow),
+  где само пятно — индикатор включения, а подложка значка остаётся стандартной.
+  Полупрозрачный значок = недоступно. Тёмный = покой.
+- **Единый визуальный редактор подложки.** Линии, фигуры, надписи и мебель используют общее выделение, физические стили и Undo/Redo. Картинка плана не прибита к холсту: отдельный инструмент двигает, масштабирует и поворачивает её, а числовой диалог задаёт точный размер и угол.
 - **Чёткий зум.** Приближение не «мылит» картинку: план, подписи и иконки остаются векторно-чёткими на любом масштабе.
 
 ---
@@ -157,7 +210,7 @@ title: План дома
 
 ![Пустой план — предложение добавить пространство](docs/images/02-onboarding-empty.png)
 
-В диалоге задайте **название** (например, «1 этаж») и **загрузите подложку** — картинку плана этажа в формате SVG, PNG или JPG. Оба поля обязательны: без плана кнопка «Сохранить» неактивна.
+В диалоге задайте **название** (например, «1 этаж») и выберите подложку: **загрузите** картинку плана (SVG, PNG, JPG, WebP), **возьмите уже загруженную** на сервер ранее или отметьте **«без подложки, нарисую комнаты сам»**. Холст бесконечный; картинка по умолчанию сохраняет пропорции, а подвинуть, изменить размер или повернуть её можно в любой момент в редакторе подложки.
 
 ![Диалог создания пространства](docs/images/03-space-dialog.png)
 
@@ -181,15 +234,15 @@ title: План дома
 - **Разделить** — кликните комнату, затем две точки на её стенах; хорда разрежет её надвое. Бо́льшая часть остаётся прежней комнатой (имя, зона, устройства), меньшая просит новое имя и зону.
 
 
-### Двери, окна и замки
+### Двери, окна, ворота и замки
 
-В режиме разметки инструмент **«Проём»** ставит двери и окна: кликните рядом со стеной — проём
+В режиме разметки инструмент **«Проём»** ставит двери, окна и ворота: кликните рядом со стеной — проём
 примагнитится к ней. Выберите тип, **длину в реальных сантиметрах** (по умолчанию дверь 90 см,
-окно 120 см), датчик открытия и — для двери — **замок**.
+окно 120 см, ворота 300 см), датчик открытия и — для двери или ворот — **замок**.
 
 С привязанным датчиком план оживает: створка двери поворачивается на петле, и дуга распахивания
 дорисовывается по мере открытия настоящей двери; окно раскрывает две створки. Пока открыто,
-подвижные части подсвечены акцентным цветом. У двери с замком рядом отображается замочек —
+подвижные части подсвечены акцентным цветом. Ворота не занимают полплана даже при ширине 3–4 м: две половинные створки показаны открытыми наружу всего на 10°, без большой дуги. Датчик, замок и пропуск света работают как у двери. У двери или ворот с замком рядом отображается замочек —
 зелёный, когда заперто, оранжевый, когда нет. Ради безопасности замок с плана **нельзя**
 переключить — клик по проёму показывает карточку с обоими статусами.
 
@@ -200,7 +253,7 @@ title: План дома
 
 Как только вы сохранили комнату с привязкой к зоне, **устройства этой зоны автоматически расставляются внутри контура**. Берутся те же устройства, что показаны на странице **Настройки → Устройства → (фильтр по нужной комнате)** — только осмысленные, без служебных записей, мостов и дубликатов.
 
-По умолчанию на план попадают только осмысленные устройства — служебные записи, мосты и дубликаты отфильтрованы. Если нужно видеть **вообще все** устройства зоны, включите в шапке кнопку **👁 «Показать все устройства»**.
+По умолчанию на план попадают только осмысленные устройства: нефизические (служебные записи, мосты, сцены, лампы, свёрнутые в световую группу) могут быть скрыты автоматически. Управление находится в левом нижнем углу диалога устройства: **«Скрыть»** убирает маркер после сохранения, а у уже скрытого маркера там же появляется **«Показать»**. Чтобы найти их, откройте редактор устройств и нажмите **«Скрытые и деактивированные»**: пользовательски скрытые устройства отображаются синими призраками. Деактивированное в HA устройство показывается серым служебным призраком и полностью исключается из данных и действий плана до повторной активации.
 
 Дальше можно просто пользоваться планом: клик по иконке открывает карточку устройства с моделью, ссылкой и кнопкой перехода в Home Assistant.
 
@@ -251,6 +304,10 @@ title: План дома
 
 ![Добавление устройства вручную](docs/images/07-marker-dialog.png)
 
+### Свои стили через card-mod (для продвинутых, без поддержки)
+
+Карточка приезжает готовой, и поля для CSS у неё нет — но если у вас уже стоит [card-mod](https://github.com/thomasloven/lovelace-card-mod), у каждого объекта плана теперь есть стабильный «крючок», за который можно зацепиться: `data-hp="device"` (плюс `data-entity`, `data-area`), `data-hp="room"`, `data-hp="opening"`, `data-hp="decor"`, `data-hp="room-label"`, `data-hp="space-tab"`. Мы обещаем их не переименовывать; сам card-mod мы не поставляем, не поддерживаем и за то, что ваш CSS сделает с карточкой, не отвечаем. Полная таблица, примеры и ограничения — в **[docs/STYLING-HOOKS.md](docs/STYLING-HOOKS.md)**.
+
 ---
 
 ## Удаление
@@ -283,7 +340,7 @@ title: План дома
 
 **Нужно ли что-то писать в YAML?** Нет. Единственная строчка — это добавление карточки на дашборд; всё остальное делается мышкой.
 
-**Мои устройства не появились на плане.** Устройство появляется, только если его зона в Home Assistant привязана к нарисованной комнате. Проверьте, что у устройства задана комната (Настройки → Устройства), а комната обведена и привязана к этой зоне. Если устройство есть, но скрыто курированием (мосты, служебные, дубликаты) — включите в шапке кнопку **👁 «Показать все устройства»**.
+**Мои устройства не появились на плане.** Устройство появляется, только если его зона в Home Assistant привязана к нарисованной комнате. Проверьте, что у устройства задана комната (Настройки → Устройства), а комната обведена и привязана к этой зоне. Откройте **«Скрытые и деактивированные»**: синий призрак можно показать в его диалоге, серый сначала нужно активировать в Home Assistant.
 
 **Можно ли скрыть лишнее устройство или переименовать его?** Да — кликните по устройству на плане и в его карточке нажмите «Редактировать»: там можно сменить имя, иконку, модель или скрыть значок.
 

custom_components/houseplan/__init__.py

@@ -2,11 +2,13 @@
 from __future__ import annotations
 
 import logging
+from datetime import timedelta
 from pathlib import Path
 
 from homeassistant.components.frontend import add_extra_js_url
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import ConfigEntryNotReady
+from homeassistant.helpers.event import async_track_time_interval
 
 from . import websocket_api as hp_ws
 from .const import (
@@ -18,6 +20,8 @@ from .const import (
     PLANS_URL,
     VERSION,
 )
+from .geometry_migration import migrate_config, migrate_layout, pending_from_config
+from .plans import collect_attachments, collect_plans, sweep_upload_temps
 from .repairs import async_check_plan_files
 from .store import HouseplanConfigEntry, create_data
 
@@ -46,6 +50,15 @@ async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) ->
         raise ConfigEntryNotReady(f"House Plan storage is not readable: {err}") from err
     entry.runtime_data = data
 
+    # server-side vacuum trails: the integration records the path itself
+    from .trails import TrailRecorder
+    recorder = TrailRecorder(hass, data)
+    await recorder.async_setup()
+    # setdefault: the CI harness sets entries up without async_setup, so
+    # hass.data[DOMAIN] may not exist yet — a KeyError here failed EVERY
+    # downstream WS test with unknown_error
+    hass.data.setdefault(DOMAIN, {})["trail_recorder"] = recorder
+
     card_path = Path(__file__).parent / "frontend" / "houseplan-card.js"
     plans_path = Path(hass.config.path(PLANS_DIR))
     files_path = Path(hass.config.path(FILES_DIR))
@@ -96,11 +109,146 @@ async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) ->
             module_url, module_url,
         )
 
+    # One-time move to the square canvas (v1.48.0). Coordinates used to be
+    # normalised against a per-space aspect ratio; the canvas is now always
+    # square and a plan is centred inside it. Nothing about the drawing changes
+    # — the box is padded and the numbers re-expressed against it.
+    # The two stores are written independently, and the lock is no transaction:
+    # a crash between the writes used to leave the config in square coordinates
+    # with the layout still in the old ones — permanently, because the config
+    # write had already deleted the `aspect` fields the layout half needed
+    # (HP-1490-01). So the intent is made durable FIRST, in the layout store,
+    # and each half carries its own trigger with its own write: the config half
+    # removes `aspect`, the layout half removes the saved intent. Whatever
+    # half is missing after a crash, the next start finishes exactly it.
+    async with data.write_lock:
+        stored = await data.config_store.async_load() or {}
+        cfg = stored.get("config")
+        lay_stored = await data.store.async_load() or {}
+        layout = lay_stored.get("layout") or {}
+        lay_meta = {
+            k: v for k, v in lay_stored.items()
+            if k not in ("layout", "rev", "geom_pending")
+        }
+        pending = {
+            str(k): v for k, v in (lay_stored.get("geom_pending") or {}).items()
+        }
+        merged = {**pending, **pending_from_config(cfg)}
+        if merged:
+            lay_rev = int(lay_stored.get("rev", 0))
+            if merged != pending:  # 1. the durable intent, before anything moves
+                await data.store.async_save(
+                    {**lay_meta, "layout": layout, "rev": lay_rev, "geom_pending": merged}
+                )
+            rev = int(stored.get("rev", 0))
+            if cfg and migrate_config(cfg):  # 2. the config half
+                rev += 1
+                await data.config_store.async_save({"config": cfg, "rev": rev})
+            migrate_layout(layout, merged)  # 3. the layout half + intent cleared
+            await data.store.async_save({**lay_meta, "layout": layout, "rev": lay_rev + 1})
+            _LOGGER.info(
+                "House Plan: migrated %s space(s) to the square canvas", len(merged)
+            )
+            # only once both halves are durable — a client refetching on this
+            # event must never see one migrated half and one old one
+            hass.bus.async_fire("houseplan_config_updated", {"rev": rev})
+
+    # Finish an explicit whole-plan optimization/undo interrupted between the
+    # config and layout store writes. The target was persisted before either
+    # visible half changed, so setup can always converge on the requested pair.
+    optimize_revs: tuple[int, int] | None = None
+    async with data.write_lock:
+        stored = await data.config_store.async_load() or {}
+        lay_stored = await data.store.async_load() or {}
+        pending = lay_stored.get("optimize_pending")
+        if isinstance(pending, dict) and isinstance(pending.get("config"), dict) \
+                and isinstance(pending.get("layout"), dict):
+            target_config = pending["config"]
+            target_layout = pending["layout"]
+            config_rev = int(stored.get("rev", 0))
+            layout_rev = int(lay_stored.get("rev", 0))
+            if stored.get("config") != target_config:
+                config_rev += 1
+                await data.config_store.async_save({
+                    "config": target_config,
+                    "rev": config_rev,
+                })
+            if lay_stored.get("layout", {}) != target_layout:
+                layout_rev += 1
+            layout_meta = {
+                k: v for k, v in lay_stored.items()
+                if k not in ("layout", "rev", "optimize_pending", "optimize_backup")
+            }
+            if not pending.get("clear_backup") and "optimize_backup" in lay_stored:
+                layout_meta["optimize_backup"] = lay_stored["optimize_backup"]
+            await data.store.async_save({
+                **layout_meta,
+                "layout": target_layout,
+                "rev": layout_rev,
+            })
+            optimize_revs = (config_rev, layout_rev)
+            _LOGGER.warning("House Plan: completed an interrupted plan optimization")
+    if optimize_revs is not None:
+        hass.bus.async_fire("houseplan_config_updated", {"rev": optimize_revs[0]})
+        hass.bus.async_fire("houseplan_layout_updated", {"rev": optimize_revs[1]})
+
     await async_check_plan_files(hass, entry)
+
+    # Scheduled collection of everything nobody ended up referencing.
+    #
+    # A commit collects what that commit superseded, which is the right rule for
+    # a commit — but it only ever runs when somebody saves. Cancel a dialog
+    # after the file has already uploaded, lose the connection after the upload
+    # succeeded, or call the API directly, and the file is unreferenced with no
+    # future write to notice it (HP-1461-01). The earlier version of this sweep
+    # only removed streaming temporaries, which are a different, narrower case.
+    #
+    # Passing the CURRENT configuration as both sides means "nothing was
+    # superseded": every referenced file is preserved and only unreferenced ones
+    # past PLAN_ORPHAN_TTL_S go. It runs under the same lock as a config write,
+    # so it cannot decide from a snapshot that a commit is about to replace.
+    async def _sweep(_now=None) -> None:
+        files_dir = Path(hass.config.path(FILES_DIR))
+        plans_dir = Path(hass.config.path(PLANS_DIR))
+        try:
+            # `data` from the closure, NOT get_data(hass): during
+            # async_setup_entry the entry is still SETUP_IN_PROGRESS, so
+            # async_loaded_entries() does not list it and the lookup returned
+            # None. The startup pass then silently degraded to removing
+            # streaming temporaries only, and the real collection waited a full
+            # day — restarting more often than that meant it never ran at all
+            # (HP-1462-01). The callback is unregistered with the entry, so
+            # closing over its runtime data matches the lifecycle exactly.
+            async with data.write_lock:
+                stored = await data.config_store.async_load() or {}
+                cfg = stored.get("config") or {}
+
+                def _collect() -> int:
+                    n = sweep_upload_temps(files_dir)
+                    # same config on both sides: nothing is superseded, so this
+                    # only ever collects what the shared rules call abandoned
+                    n += collect_attachments(files_dir, cfg, cfg)
+                    n += collect_plans(plans_dir, cfg, cfg)
+                    return n
+
+                n = await hass.async_add_executor_job(_collect)
+            if n:
+                _LOGGER.info("House Plan: removed %s unreferenced file(s)", n)
+        except Exception:  # noqa: BLE001 — housekeeping must never fail a setup
+            _LOGGER.exception("House Plan: sweeping unreferenced files failed")
+
+    data.sweep = _sweep
+    await _sweep()
+    entry.async_on_unload(
+        async_track_time_interval(hass, _sweep, timedelta(hours=24))
+    )
     return True
 
 
 async def async_unload_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) -> bool:
+    rec = hass.data.get(DOMAIN, {}).pop("trail_recorder", None)
+    if rec:
+        rec.teardown()
     """Unload the entry.
 
     WS commands and the HTTP view are global (async_setup) and stay registered —

custom_components/houseplan/auth.py

@@ -24,5 +24,8 @@ def may_write(hass: HomeAssistant, user) -> bool:
     entry = get_entry(hass)
     if entry is None:
         return is_admin
-    admin_only = bool(entry.options.get(CONF_ADMIN_ONLY, False))
+    # Default TRUE when the key is absent (audit P0-4, 2026-08-05): the card
+    # UI has always been admin-gated, and an unset option must not open every
+    # write WS/HTTP path to every authenticated household user.
+    admin_only = bool(entry.options.get(CONF_ADMIN_ONLY, True))
     return is_admin if admin_only else True

custom_components/houseplan/config_flow.py

@@ -18,7 +18,7 @@ class HouseplanConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
             return self.async_create_entry(title="House Plan", data={}, options=user_input)
         return self.async_show_form(
             step_id="user",
-            data_schema=vol.Schema({vol.Optional(CONF_ADMIN_ONLY, default=False): bool}),
+            data_schema=vol.Schema({vol.Optional(CONF_ADMIN_ONLY, default=True): bool}),
         )
 
     @staticmethod
@@ -32,7 +32,8 @@ class HouseplanOptionsFlow(config_entries.OptionsFlow):
     async def async_step_init(self, user_input=None):
         if user_input is not None:
             return self.async_create_entry(title="", data=user_input)
-        current = self.config_entry.options.get(CONF_ADMIN_ONLY, False)
+        # Match auth.may_write: missing key ⇒ admin-only (audit P0-4).
+        current = self.config_entry.options.get(CONF_ADMIN_ONLY, True)
         return self.async_show_form(
             step_id="init",
             data_schema=vol.Schema({vol.Optional(CONF_ADMIN_ONLY, default=current): bool}),

custom_components/houseplan/const.py

@@ -17,14 +17,35 @@ CONTENT_URL = "/api/houseplan/content"
 # way to tell which paths were dropped (review R2-2).
 MAX_SIGN_PATHS = 200
 
+# Nothing is ever deleted for being old (docs/SCOPE.md), so growth has to be
+# stopped at the door instead. These bound the whole store, not one request: by
+# default any authenticated user may upload, and a per-request cap of 8/50 MB
+# says nothing about how many requests there are (HP-1470-01).
+MAX_PLANS_BYTES = 256 * 1024 * 1024
+MAX_PLANS_FILES = 200
+# How many the picker asks for at once — newest first.
+MAX_PLANS_LISTED = 60
+MAX_FILES_BYTES = 1024 * 1024 * 1024
+MAX_FILES_COUNT = 1000
+# Refuse to write when the disk is nearly full: filling the config partition
+# breaks .storage, the recorder and backups, not just this card.
+MIN_FREE_BYTES = 512 * 1024 * 1024
+
 # An uploaded plan that no accepted configuration references is collected only
 # once it is this old. Age is a race guard, not a policy: a plan uploaded
 # seconds ago may belong to another client's transaction that has not written
 # its configuration yet (review R3-1).
 PLAN_ORPHAN_TTL_S = 3600
+
+# Kept for compatibility with anything reading it; the collectors no longer use
+# a long grace at all. Every attempt to age files out ended badly — first by
+# deleting detached plans, then by racing the save that was about to reference a
+# retried upload. What is left is deliberately simple: files go when the user's
+# action says so, plus staging folders after PLAN_ORPHAN_TTL_S.
+SCHEDULED_GRACE_S = 30 * 24 * 3600
 FILES_DIR = "houseplan/files"
 CONF_ADMIN_ONLY = "admin_only"
-VERSION = "1.45.2"
+VERSION = "1.61.0"
 
 DEFAULT_CONFIG: dict = {
     "spaces": [],

custom_components/houseplan/diagnostics.py

@@ -31,6 +31,9 @@ async def async_get_config_entry_diagnostics(
                 "has_plan": bool(s.get("plan_url")),
                 "rooms": len(s.get("rooms", [])),
                 "rooms_with_area": sum(1 for r in s.get("rooms", []) if r.get("area")),
+                "room_drafts": len(s.get("room_drafts", [])),
+                "partitions": len(s.get("partitions", [])),
+                "wall_columns": len(s.get("wall_columns", [])),
             }
             for s in config.get("spaces", [])
         ],

custom_components/houseplan/geometry_migration.py

@@ -0,0 +1,171 @@
+"""One-time migration to a square canvas — pure, so it can be tested alone.
+
+Until v1.48.0 a space had an `aspect`, and coordinates were normalised against
+it: x by the width, y by the HEIGHT. Making every canvas square without touching
+the numbers would stretch every plan vertically.
+
+Nothing about the drawing changes here. The canvas is padded to a square —
+top and bottom for a wide plan, left and right for a tall one — and the
+coordinates are re-expressed against that larger box. In render units it is a
+uniform scale plus an offset, so angles, room proportions and relative positions
+survive exactly. `cell_cm` follows, because the grid is tied to the width: for a
+tall plan the width grew, so the same wall would otherwise measure less.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def transform_for(aspect: float) -> tuple[float, float, float, float]:
+    """(dx, dy, kx, ky) that map old normalised coordinates onto the square.
+
+    x' = dx + x * kx, y' = dy + y * ky. Lengths along an axis scale by that
+    axis's factor; both are the same uniform scale in RENDER units, which is
+    why angles are preserved.
+    """
+    a = float(aspect)
+    if not a or a <= 0:
+        a = 1.0
+    k = min(1.0, a)          # how much the old box shrinks inside the square
+    kx = k                   # x was normalised by the width
+    ky = k / a               # y was normalised by the height (= width / aspect)
+    return (1.0 - kx) / 2, (1.0 - ky) / 2, kx, ky
+
+
+def _pt(p: Any, dx: float, dy: float, kx: float, ky: float) -> Any:
+    if isinstance(p, (list, tuple)) and len(p) >= 2:
+        return [dx + float(p[0]) * kx, dy + float(p[1]) * ky]
+    return p
+
+
+def migrate_space(space: dict[str, Any]) -> bool:
+    """Rewrite one space in place. Returns True when anything was changed."""
+    if "aspect" not in space:
+        return False
+    try:
+        aspect = float(space.get("aspect") or 1)
+    except (TypeError, ValueError):
+        aspect = 1.0
+    dx, dy, kx, ky = transform_for(aspect)
+    space.pop("aspect", None)
+
+    for room in space.get("rooms") or []:
+        if room.get("x") is not None:
+            room["x"] = dx + float(room["x"]) * kx
+        if room.get("y") is not None:
+            room["y"] = dy + float(room["y"]) * ky
+        if room.get("w") is not None:
+            room["w"] = float(room["w"]) * kx
+        if room.get("h") is not None:
+            room["h"] = float(room["h"]) * ky
+        if room.get("poly"):
+            room["poly"] = [_pt(p, dx, dy, kx, ky) for p in room["poly"]]
+
+    for draft in space.get("room_drafts") or []:
+        draft["points"] = [_pt(p, dx, dy, kx, ky) for p in draft.get("points") or []]
+
+    for part in space.get("partitions") or []:
+        part["a"] = _pt(part.get("a"), dx, dy, kx, ky)
+        part["b"] = _pt(part.get("b"), dx, dy, kx, ky)
+
+    for column in space.get("wall_columns") or []:
+        column["center"] = _pt(column.get("center"), dx, dy, kx, ky)
+
+    for op in space.get("openings") or []:
+        op["x"] = dx + float(op.get("x", 0)) * kx
+        op["y"] = dy + float(op.get("y", 0)) * ky
+        # a length is measured along the wall, and the render scale is uniform
+        if op.get("length") is not None:
+            op["length"] = float(op["length"]) * kx
+
+    for shape in space.get("decor") or []:
+        for a, b, fx, fy in (("x1", "y1", kx, ky), ("x2", "y2", kx, ky), ("x", "y", kx, ky)):
+            if shape.get(a) is not None:
+                shape[a] = dx + float(shape[a]) * fx
+            if shape.get(b) is not None:
+                shape[b] = dy + float(shape[b]) * fy
+        if shape.get("w") is not None:
+            shape["w"] = float(shape["w"]) * kx
+        if shape.get("h") is not None:
+            shape["h"] = float(shape["h"]) * ky
+
+    # The viewport becomes the whole square rather than the transformed old
+    # rectangle. It is what the grid is drawn over and what "fit to screen"
+    # fits, so keeping the old box would leave the new margins outside the
+    # canvas — no dots, nothing to draw on — which is exactly the room this
+    # change was meant to give.
+    space["view_box"] = [0.0, 0.0, 1.0, 1.0]
+
+    # The grid pitch is a fraction of the WIDTH. A tall plan just got a wider
+    # canvas, so a wall now covers fewer cells; without this every measurement
+    # in the plan would silently shrink.
+    if kx != 1:
+        try:
+            cell = float(space.get("cell_cm") or 5)
+        except (TypeError, ValueError):
+            cell = 5.0
+        space["cell_cm"] = round(cell / kx, 4)
+
+    # The image keeps its own proportions and is centred; the space no longer
+    # has any of its own.
+    if space.get("plan_url") and not space.get("plan_aspect"):
+        space["plan_aspect"] = round(aspect, 6)
+    return True
+
+
+def pending_from_config(config: dict[str, Any] | None) -> dict[str, float]:
+    """{space_id: old aspect} for every space still carrying one.
+
+    This is the migration INTENT. The two stores are written independently and
+    either write can fail, so the intent has to survive on its own: it is saved
+    into the layout store BEFORE anything changes (HP-1490-01), and cleared by
+    the same write that stores the migrated layout. A crash between the writes
+    leaves the intent behind, and the next start finishes the missing half —
+    each half is idempotent because its trigger (`aspect` in the config, the
+    saved intent for the layout) travels with that half's own write.
+    """
+    out: dict[str, float] = {}
+    for space in (config or {}).get("spaces") or []:
+        if "aspect" not in space:
+            continue
+        try:
+            out[str(space.get("id"))] = float(space.get("aspect") or 1) or 1.0
+        except (TypeError, ValueError):
+            out[str(space.get("id"))] = 1.0
+    return out
+
+
+def migrate_config(config: dict[str, Any], layout: dict[str, Any] | None = None) -> bool:
+    """The config half: migrate every space still carrying an `aspect`.
+
+    `layout` is accepted for backward compatibility and migrated with the
+    factors found in the config — callers that can crash between store writes
+    should use `pending_from_config()` + `migrate_layout()` instead, so the
+    layout half does not depend on state the config half just deleted.
+    """
+    factors = pending_from_config(config)
+    if not factors:
+        return False
+    for space in config.get("spaces") or []:
+        migrate_space(space)
+    if layout:
+        migrate_layout(layout, factors)
+    return True
+
+
+def migrate_layout(layout: dict[str, Any] | None, pending: dict[str, float]) -> bool:
+    """The layout half: marker and label positions of the spaces in `pending`."""
+    changed = False
+    for pos in (layout or {}).values():
+        if not isinstance(pos, dict) or str(pos.get("s")) not in pending:
+            continue
+        dx, dy, kx, ky = transform_for(pending[str(pos.get("s"))])
+        if pos.get("x") is not None:
+            pos["x"] = dx + float(pos["x"]) * kx
+        if pos.get("y") is not None:
+            pos["y"] = dy + float(pos["y"]) * ky
+        changed = True
+    return changed

custom_components/houseplan/http_api.py

@@ -6,6 +6,8 @@ breaks the connection on a large PDF) but via a plain multipart POST — like me
 from __future__ import annotations
 
 import logging
+import os
+import tempfile
 from pathlib import Path
 
 from aiohttp import web
@@ -18,8 +20,12 @@ except ImportError:  # older HA versions
     KEY_HASS = "hass"  # type: ignore[assignment]
 from homeassistant.core import HomeAssistant
 
-from .const import CONF_ADMIN_ONLY, CONTENT_URL, FILES_DIR, FILES_URL, PLANS_DIR
+from .const import (
+    CONF_ADMIN_ONLY, CONTENT_URL, FILES_DIR, FILES_URL, MAX_FILES_BYTES,
+    MAX_FILES_COUNT, PLANS_DIR,
+)
 from .auth import may_write
+from .plans import TMP_PREFIX, QuotaError, check_quota, reserve_filename
 from .validation import (
     FILE_EXTENSIONS,
     MAX_FILE_BYTES,
@@ -31,6 +37,8 @@ from .validation import (
 _LOGGER = logging.getLogger(__name__)
 
 _CHUNK = 64 * 1024
+# batch disk writes: one executor job per megabyte instead of per chunk
+_FLUSH_AT = 1024 * 1024
 
 _MIME = {
     ".pdf": "application/pdf",
@@ -73,17 +81,35 @@ class HouseplanContentView(HomeAssistantView):
         if not str(path).startswith(str(base)):
             return web.Response(status=404)
 
-        def _read() -> bytes | None:
-            return path.read_bytes() if path.is_file() else None
-
-        blob = await hass.async_add_executor_job(_read)
-        if blob is None:
+        if not await hass.async_add_executor_job(path.is_file):
             return web.Response(status=404)
-        return web.Response(
-            body=blob,
-            content_type=_MIME.get(path.suffix.lower(), "application/octet-stream"),
-            headers={"Cache-Control": "private, max-age=3600"},
-        )
+        suffix = path.suffix.lower()
+        headers = {
+            "Cache-Control": "private, max-age=3600",
+            "Content-Type": _MIME.get(suffix, "application/octet-stream"),
+        }
+        if suffix == ".svg":
+            # An uploaded SVG is user content served from Home Assistant's own
+            # origin. Inside the card it is referenced by <image>, where scripts
+            # never run — but the same url opened as a top-level document is a
+            # live document of this origin, and a <script> in it reaches the
+            # session's localStorage and API (HP-1454-01, 2026-07-28: uploading
+            # needs write access, which by default every authenticated user has,
+            # and the signed url is easy to hand to an admin).
+            #
+            # `sandbox` with no allow-* tokens drops the document into an opaque
+            # origin: no scripts, no same-origin access, no forms. The explicit
+            # directives below are belt and braces for older engines. Only SVG
+            # gets this — a CSP on a PDF response can break the browser's built-in
+            # viewer, and a raster image cannot execute anything in the first place.
+            headers["Content-Security-Policy"] = (
+                "sandbox; default-src 'none'; script-src 'none'; object-src 'none'; "
+                "base-uri 'none'; form-action 'none'; style-src 'unsafe-inline'; img-src data:"
+            )
+        # FileResponse streams from disk: a 50 MB manual used to be read whole
+        # into memory and copied into the response body, so a couple of parallel
+        # downloads could push a small Home Assistant host into swap (HP-1454-06).
+        return web.FileResponse(path, chunk_size=_CHUNK, headers=headers)
 
 
 class HouseplanUploadView(HomeAssistantView):
@@ -98,55 +124,132 @@ class HouseplanUploadView(HomeAssistantView):
         if not may_write(hass, request.get("hass_user")):
             return web.json_response({"error": "unauthorized"}, status=403)
 
+        files_root = Path(hass.config.path(FILES_DIR))
         marker_id = "misc"
         filename: str | None = None
-        blob: bytes | None = None
-        too_large = False
+        # Every temporary file this request creates, promoted or not. The outer
+        # `finally` removes whatever is left: a dropped connection, a second
+        # `file` part or a failure while promoting used to leave a `.upload-*`
+        # behind for good, and the collector only ever walks marker folders, so
+        # nothing would have picked it up (HP-1460-02).
+        temps: list[Path] = []
+        error: tuple[dict, int] | None = None
+
+        def _new_tmp() -> Path:
+            files_root.mkdir(parents=True, exist_ok=True)
+            fd, name = tempfile.mkstemp(prefix=TMP_PREFIX, dir=str(files_root))
+            os.close(fd)
+            return Path(name)
+
+        def _flush(target: Path, blocks: list[bytes]) -> None:
+            with open(target, "ab") as fh:
+                for block in blocks:
+                    fh.write(block)
+
+        def _cleanup(paths: list[Path]) -> None:
+            for path in paths:
+                try:
+                    path.unlink()
+                except OSError:
+                    pass
+
         try:
-            reader = await request.multipart()
-            async for part in reader:
-                if part.name == "marker_id":
-                    marker_id = sanitize_marker_id(await part.text())
-                elif part.name == "file":
-                    filename = part.filename or "file"
-                    # read in chunks, aborting at the limit, instead of loading the whole file into memory
-                    chunks: list[bytes] = []
-                    size = 0
-                    while chunk := await part.read_chunk(_CHUNK):
-                        size += len(chunk)
-                        if size > MAX_FILE_BYTES:
-                            too_large = True
+            try:
+                reader = await request.multipart()
+                async for part in reader:
+                    if part.name == "marker_id":
+                        marker_id = sanitize_marker_id(await part.text())
+                    elif part.name == "file":
+                        if filename is not None:
+                            # one upload per request: a second part would strand
+                            # the first temporary file and make the response
+                            # ambiguous about which url was returned
+                            error = ({"error": "one_file_only"}, 400)
                             break
-                        chunks.append(chunk)
-                    if too_large:
-                        break
-                    blob = b"".join(chunks)
-        except Exception as err:  # noqa: BLE001
-            _LOGGER.warning("House Plan upload: multipart read error: %s", err)
-            return web.json_response({"error": "bad_request"}, status=400)
+                        filename = part.filename or "file"
+                        if file_ext(filename) not in FILE_EXTENSIONS:
+                            error = ({"error": "bad_ext", "allowed": sorted(FILE_EXTENSIONS)}, 400)
+                            break
+                        # Stream to a temporary file instead of collecting the
+                        # whole upload in memory and copying it again into one
+                        # buffer: a 50 MB manual used to cost ~100 MB of RSS
+                        # mid-request (HP-1454-06). Blocks are batched so this
+                        # is one executor job per megabyte, not per 64 KB.
+                        tmp = await hass.async_add_executor_job(_new_tmp)
+                        temps.append(tmp)
+                        size = 0
+                        pending: list[bytes] = []
+                        buffered = 0
+                        while chunk := await part.read_chunk(_CHUNK):
+                            size += len(chunk)
+                            if size > MAX_FILE_BYTES:
+                                error = (
+                                    {"error": "too_large", "max_mb": MAX_FILE_BYTES // 1024 // 1024},
+                                    413,
+                                )
+                                break
+                            pending.append(chunk)
+                            buffered += len(chunk)
+                            if buffered >= _FLUSH_AT:
+                                await hass.async_add_executor_job(_flush, tmp, pending)
+                                pending, buffered = [], 0
+                        if error:
+                            break
+                        if pending:
+                            await hass.async_add_executor_job(_flush, tmp, pending)
+            except Exception as err:  # noqa: BLE001
+                _LOGGER.warning("House Plan upload: multipart read error: %s", err)
+                error = ({"error": "bad_request"}, 400)
 
-        if too_large:
+            if error:
+                return web.json_response(error[0], status=error[1])
+            if not temps or not filename:
+                return web.json_response({"error": "no_file"}, status=400)
+
+            tmp_path = temps[0]
+            try:
+                await hass.async_add_executor_job(
+                    check_quota, files_root, tmp_path.stat().st_size,
+                    MAX_FILES_BYTES, MAX_FILES_COUNT,
+                )
+            except QuotaError as err:
+                _LOGGER.warning("House Plan upload refused: %s", err.detail)
+                return web.json_response({"error": err.reason, "detail": err.detail}, status=507)
+            except OSError:
+                pass
+            target_dir = files_root / marker_id
+            safe_name = filename
+
+            def _promote() -> str:
+                """Claim a free name, then move the finished upload onto it.
+
+                Never overwrite an existing attachment: its bytes may be
+                referenced by the stored configuration, and this upload is not
+                part of that transaction — a cancelled dialog or a rejected save
+                would leave the old url serving the new content (HP-1454-02).
+                The name is reserved atomically, so two uploads racing on the
+                same filename cannot agree on it (HP-1460-01).
+                """
+                name = reserve_filename(target_dir, safe_name)
+                try:
+                    os.replace(tmp_path, target_dir / name)
+                except OSError:
+                    (target_dir / name).unlink(missing_ok=True)
+                    raise
+                return name
+
+            try:
+                name = await hass.async_add_executor_job(_promote)
+            except OSError as err:
+                _LOGGER.warning("House Plan upload: could not store the file: %s", err)
+                return web.json_response({"error": "io_error"}, status=500)
+            temps.remove(tmp_path)  # it is the attachment now, not a temporary
             return web.json_response(
-                {"error": "too_large", "max_mb": MAX_FILE_BYTES // 1024 // 1024}, status=413
+                {"ok": True, "url": f"{CONTENT_URL}/files/{marker_id}/{name}", "name": filename}
             )
-        if blob is None or not filename:
-            return web.json_response({"error": "no_file"}, status=400)
-        ext = file_ext(filename)
-        if ext not in FILE_EXTENSIONS:
-            return web.json_response(
-                {"error": "bad_ext", "allowed": sorted(FILE_EXTENSIONS)}, status=400
-            )
-
-        safe_name = sanitize_filename(filename)
-        target_dir = Path(hass.config.path(FILES_DIR)) / marker_id
-        path = target_dir / safe_name
-
-        def _write() -> int:
-            target_dir.mkdir(parents=True, exist_ok=True)
-            path.write_bytes(blob)
-            return int(path.stat().st_mtime)
-
-        mtime = await hass.async_add_executor_job(_write)
-        return web.json_response(
-            {"ok": True, "url": f"{CONTENT_URL}/files/{marker_id}/{safe_name}?v={mtime}", "name": filename}
-        )
+        finally:
+            # BaseException too: cancelling the request task raises
+            # asyncio.CancelledError, which an `except Exception` never saw —
+            # an aborted large upload leaked its temporary file every time
+            if temps:
+                await hass.async_add_executor_job(_cleanup, list(temps))

custom_components/houseplan/manifest.json

@@ -16,5 +16,5 @@
   "issue_tracker": "https://github.com/Matysh/houseplan-card/issues",
   "requirements": [],
   "single_config_entry": true,
-  "version": "1.45.2"
+  "version": "1.61.0"
 }

custom_components/houseplan/plans.py

@@ -1,22 +1,243 @@
-"""Plan-file collection — pure, so it is unit-testable without Home Assistant.
+"""Blob lifecycle — pure, so it is unit-testable without Home Assistant.
 
 The file system is not part of the configuration store's transaction, so who
-may delete a plan file, and when, is a correctness question rather than a
-housekeeping one. It lives here, apart from the WebSocket plumbing, precisely
-because it is the part that has to be reasoned about and tested.
+may write or delete a plan or an attachment, and when, is a correctness
+question rather than housekeeping. It lives here, apart from the WebSocket and
+HTTP plumbing, precisely because it is the part that has to be reasoned about
+and tested.
 """
 from __future__ import annotations
 
 import logging
+import os
 import time
 from pathlib import Path
 from typing import Any
 
-from .const import PLAN_ORPHAN_TTL_S
-from .validation import PLAN_EXTENSIONS
+from .const import MIN_FREE_BYTES, PLAN_ORPHAN_TTL_S
+from .validation import MAX_FILENAME, PLAN_EXTENSIONS, sanitize_filename
 
 _LOGGER = logging.getLogger(__name__)
 
+# Streaming uploads land here first. The prefix is a dot so the name can never
+# collide with an attachment (sanitize_filename strips leading dots) and is easy
+# to sweep.
+TMP_PREFIX = ".upload-"
+
+
+def reserve_filename(directory: Path, name: str) -> str:
+    """Atomically claim a free name inside `directory` and return it.
+
+    Creates the file, empty, with `O_CREAT | O_EXCL`, so the name is *taken* the
+    moment it is chosen. The previous version asked `exists()` and returned a
+    string; two uploads racing between the check and the write agreed on the
+    same name and one silently overwrote the other, both reporting success
+    (HP-1460-01). The caller writes the real bytes over the placeholder — it
+    owns the name by then — and must remove it if it never gets that far.
+
+    The result is guaranteed to satisfy `sanitize_filename(result) == result`:
+    the content view sanitises the name in the request too, so a name it would
+    shorten or rewrite is a file that is written and then never served.
+    """
+    directory.mkdir(parents=True, exist_ok=True)
+    # Split the extension off the RAW name: sanitize_filename() truncates to
+    # MAX_FILENAME, so sanitising first would cut ".pdf" off a long name and the
+    # attachment would be stored — and served — without its type.
+    base = name.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+    stem, dot, suffix = base.rpartition(".")
+    if not dot:
+        stem, suffix = base, ""
+    stem = sanitize_filename(stem)
+    ext = f".{sanitize_filename(suffix)[:16]}" if suffix else ""
+    i = 1
+    while True:
+        tag = "" if i == 1 else f"-{i}"
+        # budget the stem so the WHOLE name fits, including the collision tag —
+        # appending "-2" to an already maximal name produced a url the view
+        # truncated back to something else, i.e. a permanent 404
+        room = MAX_FILENAME - len(ext) - len(tag)
+        candidate = (stem[:room] if room > 0 else "f") + tag + ext
+        candidate = sanitize_filename(candidate)
+        if candidate.startswith("."):  # a name that is only an extension
+            candidate = "file" + candidate
+        try:
+            fd = os.open(directory / candidate, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            i += 1
+            if i > 10000:  # pathological directory; do not spin forever
+                raise
+            continue
+        os.close(fd)
+        return candidate
+
+
+def attachment_refs(cfg: dict[str, Any] | None) -> set[str]:
+    """"<marker>/<file>" for every attachment a configuration references."""
+    out: set[str] = set()
+    for m in (cfg or {}).get("markers") or []:
+        for pdf in m.get("pdfs") or []:
+            url = pdf.get("url") if isinstance(pdf, dict) else None
+            if not isinstance(url, str) or "/files/" not in url:
+                continue
+            rel = url.split("?", 1)[0].split("/files/", 1)[1]
+            if rel.count("/") == 1:
+                out.add(rel)
+    return out
+
+
+def sweep_upload_temps(files_dir: Path, now: float | None = None) -> int:
+    """Remove abandoned streaming temporaries (HP-1460-02).
+
+    The request itself deletes its own, but a hard kill — a restart mid-upload,
+    an OOM — leaves one behind, and the attachment collector only walks marker
+    folders, so it would never be seen. Age-gated for the same reason as the
+    rest: a fresh one belongs to a request still in flight.
+    """
+    cutoff = (time.time() if now is None else now) - PLAN_ORPHAN_TTL_S
+    removed = 0
+    try:
+        items = [p for p in files_dir.iterdir() if p.is_file()] if files_dir.is_dir() else []
+    except OSError as err:
+        _LOGGER.warning("House Plan: could not list %s: %s", files_dir, err)
+        return 0
+    for item in items:
+        if not item.name.startswith(TMP_PREFIX):
+            continue
+        try:
+            if item.stat().st_mtime >= cutoff:
+                continue
+            item.unlink()
+            removed += 1
+        except OSError:
+            continue
+    return removed
+
+
+def collect_attachments(
+    files_dir: Path,
+    old_cfg: dict[str, Any] | None,
+    new_cfg: dict[str, Any],
+    now: float | None = None,
+) -> int:
+    """The same commit-scoped rule as `collect_plans`, for marker attachments.
+
+    A file the old revision referenced and the new one does not, whose marker
+    still exists, was removed on purpose — the dialog has a trash button and
+    promises nothing. It goes. Everything else is kept, except a staging folder
+    (`up_*`), which by construction only ever holds an upload from a dialog that
+    was never saved: those go after PLAN_ORPHAN_TTL_S. Never raises: it runs
+    behind a durable write.
+    """
+    new_refs = attachment_refs(new_cfg)
+    old_refs = attachment_refs(old_cfg)
+    # Removing an attachment from a device that still exists is the user saying
+    # "drop this one" — a trash button, no promise that anything is kept. A
+    # device that is GONE is a different transition, and its files follow the
+    # same rule as a deleted space's plan: kept.
+    live_markers = {str(m.get("id")) for m in (new_cfg or {}).get("markers") or []}
+    # Same distinction as for plans. A staging folder (`up_*`) is different: it
+    # only ever holds an upload from a dialog that was never saved, so the short
+    # rule is exactly right there even on the timer.
+    now_s = time.time() if now is None else now
+    staging_cutoff = now_s - PLAN_ORPHAN_TTL_S
+    removed = 0
+    try:
+        folders = sorted(p for p in files_dir.iterdir() if p.is_dir()) if files_dir.is_dir() else []
+    except OSError as err:
+        _LOGGER.warning("House Plan: could not list %s: %s", files_dir, err)
+        return 0
+    removed += sweep_upload_temps(files_dir, now)
+    for folder in folders:
+        # A staging folder only ever holds an upload from a dialog that was never
+        # saved — unambiguous, so an hour is right, and no device owns it.
+        staging = folder.name.startswith("up_")
+        try:
+            items = sorted(p for p in folder.iterdir() if p.is_file())
+        except OSError:
+            continue
+        for item in items:
+            rel = f"{folder.name}/{item.name}"
+            if rel in new_refs:
+                continue
+            dropped = rel in old_refs and folder.name in live_markers
+            if not dropped:
+                if not staging:
+                    # Same rule as for plans: not asked for, so kept. A file in
+                    # a device's folder that the device does not list is an
+                    # upload whose save was rejected — and ageing those out
+                    # raced the retry that was about to reference them.
+                    continue
+                try:
+                    if item.stat().st_mtime >= staging_cutoff:
+                        continue
+                except OSError:
+                    continue
+            try:
+                item.unlink()
+                removed += 1
+            except OSError as err:
+                _LOGGER.warning("House Plan: could not remove the attachment %s: %s", item, err)
+        try:
+            next(folder.iterdir())
+        except StopIteration:
+            try:
+                folder.rmdir()
+            except OSError:
+                pass
+        except OSError:
+            pass
+    return removed
+
+
+class QuotaError(Exception):
+    """A store limit would be exceeded. Carries what to tell the user."""
+
+    def __init__(self, reason: str, detail: str) -> None:
+        super().__init__(detail)
+        self.reason = reason
+        self.detail = detail
+
+
+def dir_usage(path: Path) -> tuple[int, int]:
+    """(bytes, files) below `path`, ignoring what we cannot read."""
+    total = count = 0
+    if not path.is_dir():
+        return 0, 0
+    for item in path.rglob("*"):
+        try:
+            if item.is_file():
+                total += item.stat().st_size
+                count += 1
+        except OSError:
+            continue
+    return total, count
+
+
+def check_quota(path: Path, incoming: int, max_bytes: int, max_files: int) -> None:
+    """Raise QuotaError unless `incoming` more bytes fit.
+
+    Deliberately not an age rule. Files are never removed for getting old — that
+    cost real plans twice — so the limit sits where a decision is being made
+    anyway: at the moment somebody asks to store something new.
+    """
+    import shutil
+
+    used, count = dir_usage(path)
+    if count + 1 > max_files:
+        raise QuotaError("too_many_files", f"{count} files already stored, the limit is {max_files}")
+    if used + incoming > max_bytes:
+        raise QuotaError(
+            "quota_exceeded",
+            f"{(used + incoming) // 1024 // 1024} MB would be stored, the limit is "
+            f"{max_bytes // 1024 // 1024} MB",
+        )
+    try:
+        free = shutil.disk_usage(str(path if path.is_dir() else path.parent)).free
+    except OSError:
+        return
+    if free - incoming < MIN_FREE_BYTES:
+        raise QuotaError("low_disk_space", f"only {free // 1024 // 1024} MB free on the disk")
+
 
 def plan_basename(url: Any) -> str:
     """File name a stored plan_url points at ('' when there is none)."""
@@ -35,6 +256,14 @@ def plan_refs(cfg: dict[str, Any] | None) -> set[str]:
     return out
 
 
+def plan_by_space(cfg: dict[str, Any] | None) -> dict[str, str]:
+    """space id -> the plan file it references ('' when it has none)."""
+    return {
+        str(sp.get("id")): plan_basename(sp.get("plan_url"))
+        for sp in (cfg or {}).get("spaces") or []
+    }
+
+
 def is_plan_file(name: str) -> bool:
     """Does this look like a plan we wrote: <space>.<ext> or <space>.<token>.<ext>?"""
     parts = name.split(".")
@@ -61,7 +290,7 @@ def collect_plans(
       * a file the OLD configuration referenced and the new one does not was
         authoritative and has been superseded — remove it;
       * any other unreferenced plan file is a rejected or abandoned upload, and
-        is removed only once PLAN_ORPHAN_TTL_S has passed: a fresh one may
+        is KEPT — see the rule above; only a staging folder ages out: a fresh one may
         belong to a transaction that has not committed yet.
 
     Never raises: the configuration is already stored by the time this runs, so
@@ -69,7 +298,29 @@ def collect_plans(
     """
     new_refs = plan_refs(new_cfg)
     old_refs = plan_refs(old_cfg)
-    cutoff = (time.time() if now is None else now) - PLAN_ORPHAN_TTL_S
+    # A commit knows what it superseded. The timer only knows what nothing
+    # points at *right now*, and for a plan that is a reversible state: the
+    # editor detaches the image when a space switches to "draw" and says the
+    # file stays on disk. So the scheduled pass keeps anything belonging to a
+    # space that still exists, and waits a month for the rest.
+    # A space with NO plan_url has had its image detached — reversible, and the
+    # editor promises the file stays. A space that HAS one is different: any
+    # other file of its own is a superseded or rejected upload, so the short
+    # rule is right for those. Getting this distinction wrong (protecting
+    # nothing) destroyed two detached plans on 2026-07-28.
+    # The short rule fits exactly one case: a space that HAS a plan, where any
+    # other file of its own can only be a superseded or rejected upload.
+    old_by_space = plan_by_space(old_cfg)
+    new_by_space = plan_by_space(new_cfg)
+    # A file that left the configuration tells us nothing on its own: replacing a
+    # plan, detaching one and deleting a space all look identical from
+    # `old_refs - new_refs`. Only the first is a deletion the user asked for
+    # (HP-1465-01 — the guards below were written and then never reached,
+    # because the code decided "superseded" before asking why).
+    replaced = {
+        name for space, name in old_by_space.items()
+        if new_by_space.get(space) and new_by_space[space] != name
+    }
     removed = 0
     try:
         items = sorted(plans_dir.iterdir()) if plans_dir.is_dir() else []
@@ -82,12 +333,21 @@ def collect_plans(
     for item in items:
         if not item.is_file() or item.name in new_refs or not is_plan_file(item.name):
             continue
-        superseded = item.name in old_refs
-        try:
-            stale = item.stat().st_mtime < cutoff
-        except OSError:
-            stale = False
-        if not superseded and not stale:
+        if item.name not in replaced:
+            # PRODUCT RULE (owner's decision, 2026-07-28): a plan file we were
+            # not told to delete is kept, however long it sits there. Detaching
+            # is one click to undo and the editor says the image stays; deleting
+            # a space is deliberate but the image was imported and may be
+            # nowhere else. The errors are not symmetrical — unnecessary
+            # megabytes can be removed by hand, a deleted file cannot be
+            # brought back.
+            #
+            # There is deliberately no age rule here. An earlier version aged
+            # out "rejected uploads" — a file of a space that has a plan, which
+            # was never the plan — and that raced a save: the sweep deleted the
+            # upload from the failed attempt while a retry was committing a
+            # reference to it. A rule that can delete a file somebody is about
+            # to point at is not worth the disk it reclaims.
             continue
         try:
             item.unlink()

custom_components/houseplan/quality_scale.yaml

@@ -20,7 +20,7 @@ rules:
     status: done
   config-flow-test-coverage:
     status: done
-    comment: tests_backend/test_config_flow.py (runs in CI on Python 3.13).
+    comment: tests_backend/test_ha_config_flow.py (runs in CI on Python 3.13).
   dependency-transparency:
     status: done
     comment: No external requirements.

custom_components/houseplan/repairs.py

@@ -51,8 +51,17 @@ async def async_check_plan_files(hass: HomeAssistant, entry: HouseplanConfigEntr
             translation_key="broken_plan",
             translation_placeholders={"space": space_id, "file": fname},
         )
-    # clear stale issues for spaces that are fine again (or gone)
-    for sp in spaces:
-        sid = sp.get("id", "?")
-        if sid not in broken:
-            ir.async_delete_issue(hass, DOMAIN, f"broken_plan_{sid}")
+    # Clear stale issues. Iterating the CURRENT spaces could only ever clear
+    # issues for spaces that still exist, so deleting or renaming a space with a
+    # missing plan left its warning in Repairs forever, with nothing left to fix
+    # it (HP-1454-09). Enumerate what we actually published instead.
+    registry = ir.async_get(hass)
+    stale = [
+        issue_id
+        for (domain, issue_id) in list(registry.issues)
+        if domain == DOMAIN
+        and issue_id.startswith("broken_plan_")
+        and issue_id[len("broken_plan_") :] not in broken
+    ]
+    for issue_id in stale:
+        ir.async_delete_issue(hass, DOMAIN, issue_id)

custom_components/houseplan/store.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -42,6 +43,17 @@ class HouseplanData:
     # One lock for every load→modify→save cycle of both stores: prevents
     # lost updates from concurrent WS calls and makes the rev check atomic.
     write_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    # A separate, narrower lock for the check-quota→write-file pair of an
+    # upload. Without it N parallel uploads all measure the store BEFORE any
+    # of them writes, and all pass a quota only one of them fits under
+    # (HP-1490-02). Separate from write_lock so a slow directory scan does not
+    # stall config/layout commits.
+    upload_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    # Collect files nothing references any more. Set during setup, which also
+    # runs it once and schedules it daily. Exposed so it can be invoked
+    # directly — a test that fakes a 24 h jump proves the timer fires, not that
+    # the work happens, and those are different claims.
+    sweep: Callable[[], Awaitable[None]] | None = None
 
 
 HouseplanConfigEntry = ConfigEntry[HouseplanData]

custom_components/houseplan/system_health.py

@@ -27,6 +27,9 @@ async def system_health_info(hass: HomeAssistant) -> dict[str, Any]:
         "config_rev": cfg_raw.get("rev", 0),
         "spaces": len(config.get("spaces", [])),
         "rooms": sum(len(s.get("rooms", [])) for s in config.get("spaces", [])),
+        "room_drafts": sum(len(s.get("room_drafts", [])) for s in config.get("spaces", [])),
+        "partitions": sum(len(s.get("partitions", [])) for s in config.get("spaces", [])),
+        "wall_columns": sum(len(s.get("wall_columns", [])) for s in config.get("spaces", [])),
         "markers": len(config.get("markers", [])),
         "layout_entries": len(layout_raw.get("layout", {})),
     }

custom_components/houseplan/trails.py

@@ -0,0 +1,333 @@
+"""Server-side vacuum trails.
+
+The integration records the robot's path ITSELF by watching the source
+entity's state changes — no card involvement. This removes every client-side
+race (N open tabs would fight over writes), survives page reloads by
+construction, and keeps recording while no card is open at all. Stored: the
+current run and one previous run per marker (owner call 2026-07-31 — users
+want to see where the cleanup has already been).
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from homeassistant.core import HomeAssistant, callback
+from homeassistant.helpers import entity_registry as er
+from homeassistant.helpers.event import async_call_later, async_track_state_change_event
+from homeassistant.helpers.storage import Store
+
+from .const import DOMAIN
+
+import logging
+_LOGGER = logging.getLogger(__name__)
+
+TRAIL_CAP = 2000          # raw points per run before decimation
+SAVE_DELAY_S = 10         # debounce store writes — flash wear over precision
+FIRE_THROTTLE_S = 2.0     # event-bus updates for live cards
+MOVING_STATES = {"cleaning", "returning", "on"}
+
+
+def resolve_map_id(src_attrs: Any, vac_attrs: Any) -> str:
+    """Map-id normalisation contract, shared with the frontend.
+
+    Mirrors src/vacuum.ts vacMapIdFromAttrs (source attrs, `??`-chain) plus the
+    card's _vacMapId fallback to the vacuum entity's selected_map. The FIRST
+    value that is not None wins — truthiness is wrong here: a zero-based
+    `map_index: 0` is a valid first map and an empty string is still an id.
+    The old `or`-chain dropped the zero, so the server stored trails under a
+    key the renderer never looked up (HP-1540-02).
+    """
+    for v in (
+        src_attrs.get("map_name"),
+        src_attrs.get("current_map"),
+        src_attrs.get("map_index"),
+        src_attrs.get("selected_map"),
+        vac_attrs.get("selected_map"),
+    ):
+        if v is not None:
+            return str(v)
+    return "default"
+
+
+class TrailBook:
+    """Pure run bookkeeping: {marker: {current: run, previous: run}}.
+
+    A run is {"map_id", "started", "ended", "points": [[x, y], …]} in RAW
+    robot coordinates — recalibration never invalidates a stored trail.
+    """
+
+    def __init__(self, data: dict[str, Any] | None = None) -> None:
+        self.data: dict[str, Any] = data if isinstance(data, dict) else {}
+
+    def on_point(self, marker: str, map_id: str, x: float, y: float, now: float) -> bool:
+        rec = self.data.setdefault(marker, {})
+        cur = rec.get("current")
+        if not cur or cur.get("ended") or cur.get("map_id") != map_id:
+            # a new run begins: the old one becomes "previous" (and the one
+            # before it is forgotten — we keep exactly two, per the owner)
+            if cur:
+                rec["previous"] = cur
+            cur = {"map_id": map_id, "started": now, "ended": None, "points": []}
+            rec["current"] = cur
+        pts: list[list[float]] = cur["points"]
+        if pts and pts[-1][0] == x and pts[-1][1] == y:
+            return False
+        pts.append([x, y])
+        if len(pts) > TRAIL_CAP:
+            # decimate by two but never lose the freshest point
+            half = pts[0::2]
+            if half[-1] != pts[-1]:
+                half.append(pts[-1])
+            cur["points"] = half
+        return True
+
+    def end_run(self, marker: str, now: float) -> bool:
+        cur = (self.data.get(marker) or {}).get("current")
+        if cur and not cur.get("ended"):
+            cur["ended"] = now
+            return True
+        return False
+
+    def delete(self, marker: str) -> bool:
+        """Forget every stored run of one plan marker."""
+        return self.data.pop(marker, None) is not None
+
+
+class TrailRecorder:
+    """HA wiring: watch the tracked entities, feed the book, persist, notify."""
+
+    def __init__(self, hass: HomeAssistant, rt: Any) -> None:
+        self.hass = hass
+        self.rt = rt
+        self.store = Store(hass, 1, f"{DOMAIN}.trails")
+        self.book = TrailBook()
+        # HP-1540-03: one source may feed SEVERAL markers — the same robot
+        # placed on two floors is the documented multi-floor case, and a plain
+        # source → (marker, vacuum) dict silently kept only the last one
+        self.pairs: dict[str, list[tuple[str, str]]] = {}  # source → [(marker, vacuum), …]
+        self._unsub_track = None
+        self._unsub_save = None
+        self._last_fire = 0.0
+        # One active incident per saved marker/source. `reason` is mutable so
+        # missing↔disabled changes do not create warning storms.
+        self._source_health: dict[tuple[str, str], str] = {}
+        # HP-1540-05: config/set fires refresh as a detached task; two of them
+        # interleaving across the awaited load both subscribed and the loser's
+        # unsub handle was overwritten — a leak until HA restart
+        self._refresh_lock = asyncio.Lock()
+        self._closed = False
+
+    async def async_setup(self) -> None:
+        self.book = TrailBook(await self.store.async_load() or {})
+        await self.async_refresh()
+
+    async def async_refresh(self) -> None:
+        """(Re)subscribe after any config change — markers may come and go.
+
+        Serialised (HP-1540-05): the lock makes unsubscribe-then-resubscribe
+        atomic across the awaited config load, so overlapping refresh tasks can
+        no longer both subscribe and strand one callback forever. The _closed
+        check covers teardown() racing a refresh that is parked on its await.
+        """
+        async with self._refresh_lock:
+            stored = await self.rt.config_store.async_load() or {}
+            if self._closed:
+                return
+            cfg = stored.get("config") or {}
+            pairs: dict[str, list[tuple[str, str]]] = {}
+            health_pairs: set[tuple[str, str]] = set()
+            for m in cfg.get("markers") or []:
+                if m.get("removed") is True:
+                    continue
+                v = m.get("vacuum") or {}
+                src = v.get("source")
+                if not src or v.get("live") is False:
+                    continue
+                marker_id = str(m.get("id"))
+                health_pairs.add((marker_id, str(src)))
+                vac = self._vacuum_entity(m)
+                if vac:
+                    # HP-1540-03: append, never overwrite — every floor's
+                    # marker records its own copy of the run
+                    pairs.setdefault(src, []).append((marker_id, vac))
+            self._refresh_source_health(health_pairs)
+            self.pairs = pairs
+            self._resubscribe()
+            # A run already in progress (HA restarted mid-cleanup, or the user
+            # just finished calibrating) must start recording NOW, not at the
+            # next state change — otherwise the first seconds of the path are
+            # lost.
+            for src in self.pairs:
+                self._sample(src, time.time())
+
+    def _source_failure_reason(self, source: str) -> str | None:
+        """Classify only refresh-time health evidence.
+
+        A registry row or exact live state proves existence. No registry access
+        is neutral: it can neither create a loss incident nor recover one.
+        """
+        registry = er.async_get(self.hass)
+        state = self.hass.states.get(source)
+        if registry is None or not hasattr(registry, "async_get"):
+            return None if state is not None else "unverified"
+        entry = registry.async_get(source)
+        if entry is not None and getattr(entry, "disabled_by", None) is not None:
+            return "disabled"
+        # Registry-less YAML entities are valid: exact live state is stronger
+        # evidence than a missing registry row.
+        if entry is not None or state is not None:
+            return None
+        return "missing"
+
+    def _refresh_source_health(self, expected: set[tuple[str, str]]) -> None:
+        """Refresh deduplicated source incidents during config refresh/restart.
+
+        `unavailable` and unsupported-but-existing states count as proven
+        recovery. There is intentionally no registry subscription in Stage 1;
+        the next config refresh or restart observes a later transition.
+        """
+        for key in list(self._source_health):
+            if key not in expected:
+                del self._source_health[key]
+        for marker_id, source in sorted(expected):
+            key = (marker_id, source)
+            reason = self._source_failure_reason(source)
+            previous = self._source_health.get(key)
+            # Limited/unavailable registry evidence is neutral: keep an
+            # existing incident as-is, and never create or recover one.
+            if reason == "unverified":
+                continue
+            if reason is None:
+                if previous is not None:
+                    _LOGGER.info(
+                        "Vacuum source recovered: marker=%s source=%s (was %s)",
+                        marker_id, source, previous,
+                    )
+                    del self._source_health[key]
+                continue
+            if previous is None:
+                _LOGGER.warning(
+                    "Vacuum source %s: marker=%s source=%s",
+                    reason, marker_id, source,
+                )
+            self._source_health[key] = reason
+
+    async def async_delete(self, marker: str) -> bool:
+        """Stop and erase one marker without racing subscription refresh/save."""
+        async with self._refresh_lock:
+            # The trail book owns deletion. When it has no such marker, this
+            # is a no-op and must not silently damage the live tracking graph.
+            removed = self.book.delete(marker)
+            if not removed:
+                return False
+            for src in list(self.pairs):
+                kept = [pair for pair in self.pairs[src] if pair[0] != marker]
+                if kept:
+                    self.pairs[src] = kept
+                else:
+                    del self.pairs[src]
+            self._resubscribe()
+            if self._unsub_save:
+                self._unsub_save()
+                self._unsub_save = None
+            await self.store.async_save(self.book.data)
+        self.hass.bus.async_fire("houseplan_trail_updated", {})
+        return True
+
+    def _resubscribe(self) -> None:
+        """Replace the state subscription for the current pair graph."""
+        if self._unsub_track:
+            self._unsub_track()
+            self._unsub_track = None
+        # deduplicated: two markers of one robot share source AND vacuum
+        ents = set(self.pairs) | {vac for ps in self.pairs.values() for _, vac in ps}
+        _LOGGER.info("Trail recorder: tracking %s", sorted(ents))
+        if ents and not self._closed:
+            self._unsub_track = async_track_state_change_event(
+                self.hass, sorted(ents), self._on_state
+            )
+
+    def teardown(self) -> None:
+        # HP-1540-05: flag FIRST — a refresh parked on its awaited load must
+        # not re-subscribe after this cleanup has already run
+        self._closed = True
+        if self._unsub_track:
+            self._unsub_track()
+            self._unsub_track = None
+        if self._unsub_save:
+            self._unsub_save()
+            self._unsub_save = None
+
+    def _vacuum_entity(self, m: dict[str, Any]) -> str | None:
+        b = str(m.get("binding") or "")
+        if b.startswith("entity:vacuum."):
+            return b[len("entity:"):]
+        if b.startswith("device:"):
+            reg = er.async_get(self.hass)
+            for e in er.async_entries_for_device(reg, b[len("device:"):]):
+                if e.entity_id.startswith("vacuum."):
+                    return e.entity_id
+        return None
+
+    def _sample(self, src: str, now: float) -> bool:
+        """Record one point (or end the run) for EVERY marker fed by src.
+
+        HP-1540-03: the same source serves one marker per floor — all of them
+        must receive the point, not just whichever survived the dict.
+        """
+        changed = False
+        for marker, vac in self.pairs.get(src) or ():
+            st_vac = self.hass.states.get(vac)
+            # "no state yet" is NOT "stopped": during HA boot the vacuum reads
+            # unavailable and ending the run here would split one cleanup into
+            # current+previous on every restart (observed live: 21 points
+            # became previous, the same run restarted at 5)
+            if not st_vac or st_vac.state in ("unavailable", "unknown"):
+                continue
+            if st_vac.state not in MOVING_STATES:
+                changed |= self.book.end_run(marker, now)
+                continue
+            st_src = self.hass.states.get(src)
+            attrs = st_src.attributes if st_src else {}
+            raw = attrs.get("vacuum_position") or attrs.get("robot_position")
+            # Server-side these attributes are often OBJECTS (Tasshack keeps a
+            # Point dataclass in memory — it only becomes a dict when
+            # serialised to the frontend). Caught live on the owner's X50: the
+            # recorder saw every state change and rejected every single one.
+            if isinstance(raw, dict):
+                px, py = raw.get("x"), raw.get("y")
+            else:
+                px, py = getattr(raw, "x", None), getattr(raw, "y", None)
+            try:
+                x, y = float(px), float(py)  # type: ignore[arg-type]
+            except (TypeError, ValueError):
+                continue
+            map_id = resolve_map_id(attrs, st_vac.attributes)
+            changed |= self.book.on_point(marker, map_id, x, y, now)
+        return changed
+
+    @callback
+    def _on_state(self, event: Any) -> None:
+        eid = event.data.get("entity_id")
+        now = time.time()
+        changed = False
+        for src, pair_list in self.pairs.items():
+            if eid == src or any(eid == vac for _, vac in pair_list):
+                changed |= self._sample(src, now)
+        if changed:
+            self._schedule_save()
+            if now - self._last_fire >= FIRE_THROTTLE_S:
+                self._last_fire = now
+                self.hass.bus.async_fire("houseplan_trail_updated", {})
+
+    def _schedule_save(self) -> None:
+        if self._unsub_save:
+            return
+
+        async def _save(_now: Any) -> None:
+            self._unsub_save = None
+            await self.store.async_save(self.book.data)
+
+        self._unsub_save = async_call_later(self.hass, SAVE_DELAY_S, _save)

custom_components/houseplan/validation.py

@@ -16,6 +16,9 @@ MAX_FILE_BYTES = 50 * 1024 * 1024
 
 SPACE_ID_RE = re.compile(r"^[a-z0-9_-]{1,64}$")
 _SAFE_NAME_RE = re.compile(r"[^A-Za-z0-9._-]+")
+# The name length the content view will accept back in a request. Anything a
+# generated name must fit inside, collision tag included (HP-1460-01).
+MAX_FILENAME = 120
 
 # ---------- sanitizers ----------
 
@@ -33,7 +36,7 @@ def sanitize_marker_id(value: str) -> str:
 def sanitize_filename(value: str) -> str:
     """Drop the path and leading dots, keep a safe file name."""
     raw = value.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
-    return _SAFE_NAME_RE.sub("_", raw).lstrip(".")[:120] or "file"
+    return _SAFE_NAME_RE.sub("_", raw).lstrip(".")[:MAX_FILENAME] or "file"
 
 
 def file_ext(filename: str) -> str:
@@ -59,21 +62,148 @@ def _finite(value):
     return f
 
 
+# Persisted colours deliberately use one small, browser-independent format.
+# Keep this exact contract in sync with src/color.ts.
+# `^...$` accepts a trailing newline in Python. Persisted CSS tokens must
+# match the whole string exactly, in parity with the frontend validator.
+_COLOR = vol.Match(r"\A#[0-9a-fA-F]{6}\Z")
+_CUSTOM_FILL = vol.Schema(
+    {
+        vol.Required("c"): _COLOR,
+        vol.Required("a"): vol.All(_finite, vol.Range(min=0.0, max=1.0)),
+    }
+)
+
+
 # generous caps: the product targets 20-200 devices and a handful of floors
 MAX_SPACES = 50
 MAX_ROOMS = 400
 MAX_MARKERS = 2000
 MAX_OPENINGS = 500
 MAX_DECOR = 1000
+MAX_WALLS = 500
+MAX_ROOM_DRAFTS = 200
+MAX_DRAFT_SEGMENTS = 2000
+MAX_PARTITIONS = 2000
+MAX_WALL_COLUMNS = 500
+# Open (virtual) wall stretches, docs/superpowers/specs/2026-08-05-open-spans-delete-design.md.
+# Every span is a piece of a shared boundary, so there can never be more of
+# them than there are wall segments — the cap is the walls' one (AUD-159B6-03).
+MAX_OPEN_SPANS = 500
 MAX_LAYOUT = 5000
+# Inner limits (HP-1454-05). The outer collections were capped, the collections
+# INSIDE them were not: a 150 000-point polygon or a 100 000-entry known_devices
+# list passed validation, then made the card build gigantic SVG attributes and
+# walk them on every render. Any authenticated writer could store one, and with
+# `admin_only` off that is every user. These are product limits, not guesses: a
+# hand-drawn room does not need 500 vertices, and no home has 200 lights behind
+# one switch.
+MAX_POLY_POINTS = 500
+MAX_OPEN_TO = 50
+MAX_CONTROLS = 200
+MAX_PDFS = 50
+MAX_KNOWN_DEVICES = 20000
+MAX_TEXT = 500          # names, models, ids
+MAX_DESCRIPTION = 4000
+MAX_URL = 2000
+# Comfortably below the WebSocket frame limit (aiohttp's default is 4 MB): a
+# payload larger than the frame never reaches the handler at all — the socket
+# closes with 1009 and the user sees a dropped connection instead of an error
+# they can act on. For scale, a real three-floor home with ~200 devices stores
+# about 70 KB, so this is ~30x headroom.
+MAX_CONFIG_BYTES = 2 * 1024 * 1024
+CELL_CM_MIN = 0.1
+CELL_CM_MAX = 1000.0
+
+_TEXT = vol.All(str, vol.Length(max=MAX_TEXT))
+_TEXT_OR_NONE = vol.Any(None, _TEXT)
+_URL = vol.All(str, vol.Length(max=MAX_URL))
+
+# The canvas is UNBOUNDED (docs/CANVAS.md). Coordinates are still normalised —
+# 1.0 is still one canvas width — but there is no frame any more, so a plan may
+# legitimately live at 2.7 or -1.4. The range below is GARBAGE INSURANCE, not a
+# boundary: at the product's own scale (cell_cm=5, 240 cells across the unit
+# width) 5000 is about 60 km of plan, unreachable in a home, while a stored
+# 1e100 still cannot stretch every client's view until the plan is invisible
+# (HP-1500-03 / HP-1501-01). Widened from +/-4 on 2026-08-03.
+CANVAS_LIMIT = 5000.0
+_COORD = vol.All(_finite, vol.Range(min=-CANVAS_LIMIT, max=CANVAS_LIMIT))
 
 POS_SCHEMA = vol.Schema(
-    {vol.Required("x"): _finite, vol.Required("y"): _finite},
+    {vol.Required("x"): _COORD, vol.Required("y"): _COORD},
     extra=vol.ALLOW_EXTRA,  # v2 records carry the "s" key (space id)
 )
 LAYOUT_SCHEMA = vol.All(vol.Schema({str: POS_SCHEMA}), vol.Length(max=MAX_LAYOUT))
 
-POINT = vol.All([_finite], vol.Length(min=2, max=2))
+# Room/opening geometry: same story, same range (docs/CANVAS.md). A vertex at
+# 2.5 is a plan that grew past the old square, not corruption; 1e100 is
+# corruption (HP-1501-01, the room-geometry twin of HP-1500-03).
+_GEOM = vol.All(_finite, vol.Range(min=-CANVAS_LIMIT, max=CANVAS_LIMIT))
+
+# A SIZE is not a coordinate (HP-1502-01): SVG requires positive width/height,
+# and the clients divide by these. `view_box: [0,0,0,0]` passed the shared
+# validator and serialised into viewBox="0 0 0 0" — a blank plan on every
+# client. The floor is one thousandth of the canvas (1 render unit): far below
+# any real room, but keeps the maths finite. The CEILING follows the canvas
+# (docs/CANVAS.md) — a room on an unbounded plane may legitimately be wider
+# than the old unit square — while staying strictly positive.
+_EXTENT = vol.All(_finite, vol.Range(min=0.001, max=CANVAS_LIMIT))
+
+# The backdrop's uniform scale (docs/BACKDROP.md). A MULTIPLIER, not a
+# coordinate: strictly positive, and bounded by what a person could mean —
+# a hundredth of the canvas is already a thumbnail, a hundred canvases is
+# already absurd. Mirrored by PLAN_SCALE_MIN/MAX in src/space-geometry.ts.
+PLAN_SCALE_MIN = 0.01
+PLAN_SCALE_MAX = 100.0
+
+
+def _view_box(value):
+    """[x, y, w, h]: the first two are coordinates, the last two are sizes."""
+    if not isinstance(value, (list, tuple)) or len(value) != 4:
+        raise vol.Invalid("view_box must be [x, y, w, h]")
+    return [_GEOM(value[0]), _GEOM(value[1]), _EXTENT(value[2]), _EXTENT(value[3])]
+
+
+POINT = vol.All([_GEOM], vol.Length(min=2, max=2))
+
+# A virtual stretch shorter than this is a click, not a span. Mirrors
+# OPEN_SPAN_MIN_UNITS in src/open-spans.ts (normalised units).
+OPEN_SPAN_MIN_LEN = 1e-3
+
+
+def _open_span(value):
+    """One virtual stretch: exactly two distinct finite points a/b.
+
+    AUD-159B6-03: the field used to ride on `extra=ALLOW_EXTRA` — any shape
+    passed the backend and the card crashed reading `e.a[0]` on render, for
+    every reader of that space. A degenerate span (a == b) is not a stretch
+    either: it can never be hit, closed or drawn, so it is corruption, not data.
+    """
+    if not isinstance(value, dict):
+        raise vol.Invalid("open_span must be an object with a/b points")
+    a = POINT(value.get("a"))
+    b = POINT(value.get("b"))
+    if abs(a[0] - b[0]) < OPEN_SPAN_MIN_LEN and abs(a[1] - b[1]) < OPEN_SPAN_MIN_LEN:
+        raise vol.Invalid("open_span: a and b must differ")
+    out = {k: v for k, v in value.items() if k not in ("a", "b")}
+    out["a"] = a
+    out["b"] = b
+    return out
+
+
+def _dedupe_open_spans(value):
+    """Drop repeats of the same stretch (either direction) — one wall, one span."""
+    seen = set()
+    out = []
+    for span in value:
+        a, b = span["a"], span["b"]
+        fwd = (round(a[0], 6), round(a[1], 6), round(b[0], 6), round(b[1], 6))
+        key = min(fwd, (fwd[2], fwd[3], fwd[0], fwd[1]))
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(span)
+    return out
 
 
 def _require_geometry(room: dict) -> dict:
@@ -85,15 +215,17 @@ def _require_geometry(room: dict) -> dict:
 ROOM_SCHEMA = vol.All(
     vol.Schema(
         {
-            vol.Required("id"): str,
-            vol.Required("name"): str,
-            vol.Optional("area"): vol.Any(str, None),
-            vol.Optional("open_to"): [str],
+            vol.Required("id"): _TEXT,
+            vol.Required("name"): _TEXT,
+            vol.Optional("area"): _TEXT_OR_NONE,
+            vol.Optional("open_to"): vol.All([_TEXT], vol.Length(max=MAX_OPEN_TO)),
             vol.Optional("settings"): vol.Any(
                 None,
                 vol.Schema(
                     {
-                        vol.Optional("fill_mode"): vol.Any(None, vol.In(["none", "lqi", "light", "temp"])),
+                        vol.Optional("fill_mode"): vol.Any(None, vol.In(["none", "lqi", "light", "temp", "custom", "glow"])),
+                        vol.Optional("custom_fill"): vol.Any(None, _CUSTOM_FILL),
+                        vol.Optional("glow"): vol.Any(bool, None),
                         vol.Optional("temp_source"): vol.Any(str, None),
                         vol.Optional("hum_source"): vol.Any(str, None),
                         vol.Optional("name_scale"): vol.Any(None, vol.All(vol.Coerce(float), vol.Range(min=0.5, max=3))),
@@ -102,77 +234,329 @@ ROOM_SCHEMA = vol.All(
                     extra=vol.ALLOW_EXTRA,
                 ),
             ),
-            vol.Optional("x"): _finite,
-            vol.Optional("y"): _finite,
-            vol.Optional("w"): _finite,
-            vol.Optional("h"): _finite,
-            vol.Optional("poly"): vol.All([POINT], vol.Length(min=3)),
+            vol.Optional("x"): _GEOM,
+            vol.Optional("y"): _GEOM,
+            vol.Optional("w"): _EXTENT,
+            vol.Optional("h"): _EXTENT,
+            vol.Optional("poly"): vol.All([POINT], vol.Length(min=3, max=MAX_POLY_POINTS)),
         },
         extra=vol.ALLOW_EXTRA,
     ),
     _require_geometry,
 )
+
+def _north_deg(value):
+    """Compass (docs/SUN.md): strict integer degrees, 0..359.
+
+    Strict on purpose: Coerce(int) would take "90" and 1.5, and a bool is an
+    int in Python — none of those is a compass reading a client stored.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise vol.Invalid("north_deg must be an integer in 0..359")
+    if not 0 <= value <= 359:
+        raise vol.Invalid("north_deg must be an integer in 0..359")
+    return value
+
+
+_BG_MODE = vol.In(["static", "daynight"])
+
 SPACE_DISPLAY_SCHEMA = vol.Schema(
     {
         vol.Optional("show_borders"): bool,
         vol.Optional("show_names"): bool,
-        vol.Optional("room_color"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+        vol.Optional("room_color"): _COLOR,
+        # per-space background around the plan; absent = inherit the global one
+        vol.Optional("bg_color"): _COLOR,
         vol.Optional("room_opacity"): vol.All(vol.Coerce(float), vol.Range(min=0, max=1)),
-        vol.Optional("fill_mode"): vol.In(["none", "lqi", "light", "temp", "glow"]),
+        vol.Optional("fill_mode"): vol.In(["none", "lqi", "light", "temp", "custom", "glow"]),
+        vol.Optional("custom_fill"): vol.Any(None, _CUSTOM_FILL),
+        vol.Optional("glow_enabled"): bool,
         vol.Optional("temp_min"): vol.Coerce(float),
         vol.Optional("temp_max"): vol.Coerce(float),
         vol.Optional("show_lqi"): bool,
+        # "draw less" switches; absent = False = everything is drawn as before
+        vol.Optional("hide_decor"): bool,
+        vol.Optional("hide_openings"): bool,
         vol.Optional("label_temp"): bool,
         vol.Optional("label_hum"): bool,
         vol.Optional("label_lqi"): bool,
         vol.Optional("label_light"): bool,
         vol.Optional("card_font_scale"): vol.All(vol.Coerce(float), vol.Range(min=0.5, max=3)),
+        # sun on the plan (docs/SUN.md): per-space overrides, absent = inherit
+        vol.Optional("north_deg"): vol.Any(None, _north_deg),
+        vol.Optional("bg_mode"): vol.Any(None, _BG_MODE),
+        vol.Optional("sun_rays"): vol.Any(None, bool),
     },
     extra=vol.ALLOW_EXTRA,
 )
 
+# Live text on a decor label (docs/LIVE-TEXT.md). An entity id is
+# `<domain>.<object_id>`; HA itself allows only lowercase letters, digits and
+# underscores in both halves. The bound is a sanity limit, not a policy.
+MAX_ENTITY_ID = 255
+_ENTITY_ID = vol.All(str, vol.Length(min=3, max=MAX_ENTITY_ID),
+                     vol.Match(r"^[a-z0-9_]+\.[a-z0-9_]+$"))
+# A caption is a caption: the inline-reference template is bounded. Attribute
+# and unit bounds below apply only to legacy beta.9 link fields, which remain
+# accepted so an older saved plan can reach the frontend and migrate on edit.
+MAX_DECOR_TEXT = 200
+MAX_DECOR_ATTR = 64
+MAX_DECOR_UNIT = 16
+# The text block is scaled by dragging its corners; the range is what a human
+# could mean on a 1000-unit canvas, the rest is garbage insurance.
+DECOR_TEXT_SCALE_MIN = 0.15
+DECOR_TEXT_SCALE_MAX = 20.0
+DECOR_TEXT_CM_MAX = 2000.0
+# A furniture symbol id (docs/FURNITURE.md). Deliberately NOT the card's list:
+# the backend must accept a plan written by a NEWER card, and a card that has
+# learnt a new symbol must not have to wait for the integration to be updated
+# before the user can save. What is enforced is the shape of the id — a flat
+# lowercase name — and its length; an id this backend has never heard of simply
+# renders as nothing in an older card.
+MAX_FURN_SYMBOL = 32
+_FURN_SYMBOL = vol.All(str, vol.Length(min=1, max=MAX_FURN_SYMBOL),
+                       vol.Match(r"^[a-z0-9_]+$"))
+# …and its size: strictly positive, capped by the same canvas insurance limit
+# an opening's length is. A piece of furniture is a SIZE, not a coordinate.
+_FURN_SIZE = vol.All(_finite, vol.Range(min=0.0000001, max=CANVAS_LIMIT))
+
 _DECOR_COMMON = {
     vol.Required("id"): str,
-    vol.Optional("color"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+    vol.Optional("color"): _COLOR,
+    vol.Optional("opacity"): vol.All(_finite, vol.Range(min=0.0, max=1.0)),
+    # Physical centimetres are canonical. `width` remains accepted so plans
+    # written by older cards keep their exact appearance until edited.
+    vol.Optional("width_cm"): vol.All(_finite, vol.Range(min=0.1, max=100)),
     vol.Optional("width"): vol.All(vol.Coerce(float), vol.Range(min=0.1, max=30)),
 }
-_NORM = vol.All(vol.Coerce(float), vol.Range(min=-1, max=2))
+# Decor lives on the same unbounded canvas as everything else (docs/CANVAS.md):
+# it used to be pinned to -1..2, i.e. "one canvas of slack around the square".
+_NORM = vol.All(_finite, vol.Range(min=-CANVAS_LIMIT, max=CANVAS_LIMIT))
 DECOR_SCHEMA = vol.Any(
     vol.Schema({**_DECOR_COMMON, vol.Required("kind"): "line",
                 vol.Required("x1"): _NORM, vol.Required("y1"): _NORM,
-                vol.Required("x2"): _NORM, vol.Required("y2"): _NORM},
+                vol.Required("x2"): _NORM, vol.Required("y2"): _NORM,
+                vol.Optional("line_style"): vol.In(["solid", "dashed"])},
                extra=vol.ALLOW_EXTRA),
     vol.Schema({**_DECOR_COMMON, vol.Required("kind"): vol.In(["rect", "ellipse"]),
                 vol.Required("x"): _NORM, vol.Required("y"): _NORM,
-                vol.Required("w"): _NORM, vol.Required("h"): _NORM,
-                vol.Optional("fill"): bool},
+                # sizes are extents — negative/zero is garbage, not "canvas slack"
+                vol.Required("w"): vol.All(_finite, vol.Range(min=0.001, max=CANVAS_LIMIT)),
+                vol.Required("h"): vol.All(_finite, vol.Range(min=0.001, max=CANVAS_LIMIT)),
+                vol.Optional("angle"): vol.All(_finite, vol.Range(min=-360.0, max=360.0)),
+                vol.Optional("fill"): bool,
+                vol.Optional("fill_color"): _COLOR,
+                vol.Optional("fill_opacity"): vol.All(_finite, vol.Range(min=0.0, max=1.0))},
                extra=vol.ALLOW_EXTRA),
     vol.Schema({**_DECOR_COMMON, vol.Required("kind"): "text",
                 vol.Required("x"): _NORM, vol.Required("y"): _NORM,
-                vol.Required("text"): vol.All(str, vol.Length(min=1, max=200)),
-                vol.Optional("size"): vol.In(["s", "m", "l"])},
+                # the template: newlines are the user's own line breaks and are
+                # kept verbatim (docs/LIVE-TEXT.md); the label never wraps itself
+                vol.Required("text"): vol.All(str, vol.Length(min=1, max=MAX_DECOR_TEXT)),
+                # legacy font size ('s'|'m'|'l'). The dialog no longer offers it
+                # — the block is scaled by its corner handles — but a plan
+                # written before that keeps it, and it is read as the scale it
+                # used to render at. Kept in the schema so it stays BOUNDED.
+                vol.Optional("size"): vol.In(["s", "m", "l"]),
+                # Canonical physical font size plus the legacy scale. Both are
+                # accepted so older plans remain pixel-identical until edited
+                # or explicitly optimized.
+                vol.Optional("size_cm"): vol.All(
+                    _finite, vol.Range(min=0.1, max=DECOR_TEXT_CM_MAX)),
+                vol.Optional("scale"): vol.All(
+                    _finite, vol.Range(min=DECOR_TEXT_SCALE_MIN, max=DECOR_TEXT_SCALE_MAX)),
+                vol.Optional("angle"): vol.All(_finite, vol.Range(min=-360.0, max=360.0)),
+                # Legacy one-value link (beta.9 and earlier). New labels store
+                # every `{entity[:attribute]}` reference directly in `text`;
+                # these stay accepted solely for backward compatibility.
+                vol.Optional("entity"): vol.Any(None, _ENTITY_ID),
+                vol.Optional("attr"): vol.Any(None, vol.All(str, vol.Length(max=MAX_DECOR_ATTR))),
+                vol.Optional("unit"): vol.Any(None, vol.All(str, vol.Length(max=MAX_DECOR_UNIT)))},
+               extra=vol.ALLOW_EXTRA),
+    # A piece of furniture (docs/FURNITURE.md): a symbol id, a normalised box
+    # and an optional rotation. It is a NEW kind, so no existing plan carries
+    # it, nothing is migrated, and an integration that has this branch reads
+    # every older config byte-for-byte as before.
+    vol.Schema({**_DECOR_COMMON, vol.Required("kind"): "furniture",
+                vol.Required("symbol"): _FURN_SYMBOL,
+                vol.Required("x"): _NORM, vol.Required("y"): _NORM,
+                vol.Required("w"): _FURN_SIZE, vol.Required("h"): _FURN_SIZE,
+                vol.Optional("angle"): vol.All(_finite, vol.Range(min=-360.0, max=360.0))},
                extra=vol.ALLOW_EXTRA),
 )
 
-SPACE_SCHEMA = vol.Schema(
+
+def _wall_endpoints_pair(entry: dict) -> dict:
+    """Exact wall endpoints are useful only as a complete a/b pair."""
+    if ("a" in entry) != ("b" in entry):
+        raise vol.Invalid("wall exact endpoints require both a and b")
+    return entry
+
+
+WALL_SCHEMA = vol.All(
+    vol.Schema(
+        {
+            vol.Required("key"): vol.All(str, vol.Length(min=1, max=64)),
+            vol.Required("cm"): vol.All(_finite, vol.Range(min=1, max=100)),
+            # New writes retain exact normalized interval endpoints. The old
+            # key remains the compatibility lookup; endpoints preserve a
+            # differing-thickness breakpoint after a virtual span is closed.
+            vol.Optional("a"): vol.All([_NORM], vol.Length(min=2, max=2)),
+            vol.Optional("b"): vol.All([_NORM], vol.Length(min=2, max=2)),
+        },
+        extra=vol.ALLOW_EXTRA,
+    ),
+    _wall_endpoints_pair,
+)
+
+
+def _room_draft_segments(value: dict) -> dict:
+    """An open draft has exactly one thickness per consecutive edge."""
+    if len(value.get("segments", [])) != max(0, len(value.get("points", [])) - 1):
+        raise vol.Invalid("room draft segments must match consecutive point pairs")
+    if any(a == b for a, b in zip(value.get("points", []), value.get("points", [])[1:])):
+        raise vol.Invalid("room draft consecutive points must differ")
+    return value
+
+
+ROOM_DRAFT_SCHEMA = vol.All(
+    vol.Schema(
+        {
+            vol.Required("id"): vol.All(str, vol.Length(min=1, max=64)),
+            vol.Required("points"): vol.All([POINT], vol.Length(min=2, max=500)),
+            vol.Required("segments"): vol.All(
+                [vol.Schema({vol.Required("cm"): vol.All(_finite, vol.Range(min=1, max=100))},
+                            extra=vol.ALLOW_EXTRA)],
+                vol.Length(min=1, max=499),
+            ),
+        },
+        extra=vol.ALLOW_EXTRA,
+    ),
+    _room_draft_segments,
+)
+
+def _partition_nonzero(value: dict) -> dict:
+    if value["a"] == value["b"]:
+        raise vol.Invalid("partition endpoints must differ")
+    return value
+
+
+PARTITION_SCHEMA = vol.All(
+    vol.Schema(
+        {
+            vol.Required("id"): vol.All(str, vol.Length(min=1, max=64)),
+            vol.Required("a"): POINT,
+            vol.Required("b"): POINT,
+            vol.Required("cm"): vol.All(_finite, vol.Range(min=1, max=100)),
+        },
+        extra=vol.ALLOW_EXTRA,
+    ),
+    _partition_nonzero,
+)
+
+def _strict_wall_column(value: dict) -> dict:
+    """Reject shape-inapplicable or non-canonical column fields."""
+    if value["shape"] == "circle" and "angle" in value:
+        raise vol.Invalid("angle is allowed only for square wall columns")
+    if value["shape"] == "square" and value.get("angle", 0) >= 90:
+        raise vol.Invalid("square wall column angle must be in [0, 90)")
+    return value
+
+
+WALL_COLUMN_SCHEMA = vol.All(
+    vol.Schema(
+        {
+            vol.Required("id"): vol.All(str, vol.Length(min=1, max=64)),
+            vol.Required("shape"): vol.In(["square", "circle"]),
+            vol.Required("center"): POINT,
+            # Outer side for a square, outer diameter for a circle.
+            vol.Required("cm"): vol.All(_finite, vol.Range(min=1, max=150)),
+            vol.Optional("angle"): vol.All(
+                _finite, vol.Range(min=0, max=90)
+            ),
+        },
+        extra=vol.ALLOW_EXTRA,
+    ),
+    _strict_wall_column,
+)
+
+
+def _space_geometry_invariants(value: dict) -> dict:
+    """All stored geometry shares ids; draft segments also have a space cap."""
+    seen: set[str] = set()
+    for key in ("rooms", "openings", "decor", "room_drafts", "partitions", "wall_columns"):
+        for item in value.get(key, []):
+            item_id = item.get("id")
+            if not item_id:
+                continue
+            if item_id in seen:
+                raise vol.Invalid("geometry object ids must be unique within a space")
+            seen.add(item_id)
+    draft_segments = sum(
+        len(item.get("segments", [])) for item in value.get("room_drafts", [])
+    )
+    if draft_segments > MAX_DRAFT_SEGMENTS:
+        raise vol.Invalid("too many saved room-draft segments")
+    return value
+
+
+SPACE_SCHEMA = vol.All(vol.Schema(
     {
-        vol.Required("id"): str,
+        vol.Required("id"): vol.All(str, vol.Match(SPACE_ID_RE.pattern)),
         vol.Required("title"): str,
+        # Physical grid scale. It feeds every px/cell -> centimetres migration,
+        # so NaN/Infinity or an absurd value must not be allowed to manufacture
+        # invalid decor sizes later.
+        vol.Optional("cell_cm"): vol.All(
+            _finite, vol.Range(min=CELL_CM_MIN, max=CELL_CM_MAX)
+        ),
         vol.Optional("settings"): SPACE_DISPLAY_SCHEMA,
         vol.Optional("plan_url"): vol.Any(str, None),
-        vol.Required("aspect"): vol.All(vol.Coerce(float), vol.Range(min=0.05, max=20)),
-        vol.Required("view_box"): vol.All([_finite], vol.Length(min=4, max=4)),
+        # The canvas is square since v1.48.0. What used to be the space's own
+        # `aspect` is gone; the background image keeps its own proportions and
+        # is centred, so only the IMAGE's ratio is stored. A stale tab may still
+        # send the old field — it is dropped rather than trusted, because the
+        # coordinates it comes with were normalised against a different box.
+        vol.Remove("aspect"): object,
+        vol.Optional("plan_aspect"): vol.Any(
+            None, vol.All(vol.Coerce(float), vol.Range(min=0.05, max=20))
+        ),
+        # Backdrop placement (docs/BACKDROP.md): the picture may be moved,
+        # resized per axis and rotated. Every transform field is optional; its
+        # complete absence is the pre-v1.58.0 behaviour exactly, and an old
+        # config validates unchanged. The offset is a normalised
+        # coordinate like every other one (the ±CANVAS_LIMIT garbage guard);
+        # the scale is a positive multiplier in a range a human could mean.
+        vol.Optional("plan_x"): vol.Any(None, _COORD),
+        vol.Optional("plan_y"): vol.Any(None, _COORD),
+        vol.Optional("plan_scale"): vol.Any(
+            None, vol.All(_finite, vol.Range(min=PLAN_SCALE_MIN, max=PLAN_SCALE_MAX))
+        ),
+        # New writes may stretch each axis independently and rotate. The old
+        # uniform field remains a read-compatible fallback for both axes.
+        vol.Optional("plan_scale_x"): vol.Any(
+            None, vol.All(_finite, vol.Range(min=PLAN_SCALE_MIN, max=PLAN_SCALE_MAX))
+        ),
+        vol.Optional("plan_scale_y"): vol.Any(
+            None, vol.All(_finite, vol.Range(min=PLAN_SCALE_MIN, max=PLAN_SCALE_MAX))
+        ),
+        vol.Optional("plan_angle"): vol.Any(
+            None, vol.All(_finite, vol.Range(min=-360.0, max=360.0))
+        ),
+        vol.Required("view_box"): _view_box,
         vol.Required("rooms"): vol.All([ROOM_SCHEMA], vol.Length(max=MAX_ROOMS)),
         vol.Optional("decor"): vol.All([DECOR_SCHEMA], vol.Length(max=MAX_DECOR)),
         vol.Optional("openings"): vol.All([
             vol.Schema(
                 {
                     vol.Required("id"): str,
-                    vol.Required("type"): vol.Any("door", "window"),
-                    vol.Required("x"): _finite,
-                    vol.Required("y"): _finite,
-                    vol.Required("angle"): _finite,
-                    vol.Required("length"): vol.All(vol.Coerce(float), vol.Range(min=0.001, max=1)),
+                    vol.Required("type"): vol.Any("door", "window", "gate"),
+                    vol.Required("x"): _GEOM,
+                    vol.Required("y"): _GEOM,
+                    vol.Required("angle"): vol.All(_finite, vol.Range(min=-360.0, max=360.0)),
+                    # a SIZE: strictly positive, capped by the canvas insurance
+                    # limit rather than by the old unit square (docs/CANVAS.md)
+                    vol.Required("length"): vol.All(_finite, vol.Range(min=0.001, max=CANVAS_LIMIT)),
                     vol.Optional("contact"): vol.Any(str, None),
                     vol.Optional("lock"): vol.Any(str, None),
                     vol.Optional("invert"): bool,
@@ -182,39 +566,110 @@ SPACE_SCHEMA = vol.Schema(
                 extra=vol.ALLOW_EXTRA,
             )
         ], vol.Length(max=MAX_OPENINGS)),
+        # Wall thickness (docs/WALL-THICKNESS.md): keyed by a segment identity
+        # (midpoint + direction), thickness always in centimetres. Optional —
+        # a space without `walls` validates and renders exactly as before.
+        vol.Optional("walls"): vol.All([WALL_SCHEMA], vol.Length(max=MAX_WALLS)),
+        vol.Optional("room_drafts"): vol.All(
+            [ROOM_DRAFT_SCHEMA], vol.Length(max=MAX_ROOM_DRAFTS)
+        ),
+        vol.Optional("partitions"): vol.All(
+            [PARTITION_SCHEMA], vol.Length(max=MAX_PARTITIONS)
+        ),
+        vol.Optional("wall_columns"): vol.All(
+            [WALL_COLUMN_SCHEMA], vol.Length(max=MAX_WALL_COLUMNS)
+        ),
+        # Open (virtual) wall stretches: a piece of a shared boundary that the
+        # user opened. Optional and bounded — a space without `open_spans`
+        # validates exactly as before, and the legacy `rooms[].open_to` index
+        # keeps working on its own (AUD-159B6-03).
+        vol.Optional("open_spans"): vol.All(
+            vol.Length(max=MAX_OPEN_SPANS), [_open_span], _dedupe_open_spans,
+        ),
         # Legacy: walls are derived from room outlines since v1.19.0 — a line has no
         # independent existence. Still accepted so a stale browser tab cannot fail a save;
         # the card strips the field on every write.
-        vol.Optional("segments"): [vol.All([vol.Coerce(float)], vol.Length(min=4, max=4))],
+        # Accepted so a stale browser tab cannot fail a save, then DROPPED here
+        # (HP-1454-05): relying on a modern client to strip an unbounded legacy
+        # list is not a limit, it is a hope. `Remove` returns the key stripped.
+        vol.Remove("segments"): object,
     },
     extra=vol.ALLOW_EXTRA,
-)
+), _space_geometry_invariants)
 MARKER_SCHEMA = vol.Schema(
     {
         vol.Required("id"): str,
         # 'device:<device_id>' | 'entity:<entity_id>' | 'virtual'
-        vol.Required("binding"): str,
+        vol.Required("binding"): vol.All(
+            str,
+            vol.Length(min=1, max=MAX_TEXT),
+            vol.Match(r"^(device:.+|entity:.+|virtual)$"),
+        ),
         vol.Optional("space"): vol.Any(str, None),
         vol.Optional("area"): vol.Any(str, None),
         vol.Optional("hidden"): bool,
-        vol.Optional("name"): vol.Any(str, None),
-        vol.Optional("icon"): vol.Any(str, None),
-        vol.Optional("model"): vol.Any(str, None),
-        vol.Optional("link"): vol.Any(str, None),
-        vol.Optional("description"): vol.Any(str, None),
-        vol.Optional("tap_action"): vol.Any("info", "more-info", "toggle", None),
-        vol.Optional("controls"): vol.Any([str], None),
+        # A binding-level tombstone: not rendered or aggregated, but retained
+        # so automatic discovery does not put a deleted device straight back.
+        vol.Optional("removed"): bool,
+        vol.Optional("name"): _TEXT_OR_NONE,
+        vol.Optional("icon"): _TEXT_OR_NONE,
+        vol.Optional("model"): _TEXT_OR_NONE,
+        vol.Optional("link"): vol.Any(None, _URL),
+        vol.Optional("description"): vol.Any(None, vol.All(str, vol.Length(max=MAX_DESCRIPTION))),
+        vol.Optional("tap_action"): vol.Any("info", "more-info", "toggle", "run", "cover", None),
+        # the 'run' target: only the runnable domains, nothing else is callable
+        vol.Optional("tap_target"): vol.Any(
+            None, vol.All(str, vol.Length(max=MAX_TEXT), vol.Match(r"^(automation|script|scene)\.[A-Za-z0-9_]+$"))
+        ),
+        vol.Optional("tap_confirm"): vol.Any(bool, None),
+        # live robot vacuums (docs/VACUUM.md): everything optional so configs
+        # from older versions stay valid untouched
+        vol.Optional("vacuum"): vol.Any(
+            None,
+            vol.Schema({
+                vol.Optional("live"): vol.Any(bool, None),
+                vol.Optional("trail"): vol.Any(bool, None),
+                vol.Optional("trail_mode"): vol.Any(
+                    None, vol.In(["never", "cleaning", "always"])
+                ),
+                vol.Optional("room_highlight"): vol.Any(bool, None),
+                vol.Optional("source"): vol.Any(str, None),
+                # one 6-number affine per robot map; numbers must be finite
+                vol.Optional("calibration"): vol.Schema(
+                    {str: vol.All([_finite], vol.Length(min=6, max=6))}
+                ),
+                vol.Optional("segment_map"): vol.Schema({str: str}),
+            }),
+        ),
+        vol.Optional("controls"): vol.Any(None, vol.All([_TEXT], vol.Length(max=MAX_CONTROLS))),
         vol.Optional("glow_radius_cm"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=10, max=10000)), None),
+        vol.Optional("glow_color"): vol.Any(
+            None,
+            vol.Schema(
+                {
+                    vol.Required("c"): _COLOR,
+                    vol.Optional("bri"): vol.Any(
+                        None,
+                        vol.All(_finite, vol.Range(min=0.01, max=1.0)),
+                    ),
+                }
+            ),
+        ),
         vol.Optional("is_light"): vol.Any(bool, None),
+        # climate current_temperature: badge + room-average vote (off unless True)
+        vol.Optional("use_climate_temp"): vol.Any(bool, None),
         vol.Optional("room_id"): vol.Any(str, None),
-        vol.Optional("display"): vol.Any("badge", "ripple", "icon_ripple", None),
-        vol.Optional("ripple_color"): vol.Any(str, None),
+        # Keep in sync with DISPLAY_MODES in src/logic.ts. `ripple` is no longer
+        # offered, but remains accepted while old stores migrate to icon_ripple.
+        vol.Optional("display"): vol.Any("badge", "ripple", "icon_ripple", "value", "static_icon", None),
+        vol.Optional("ripple_color"): vol.Any(None, _COLOR),
         vol.Optional("ripple_size"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=1, max=20)), None),
         vol.Optional("size"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=0.2, max=6)), None),
         vol.Optional("angle"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=-360, max=360)), None),
-        vol.Optional("pdfs"): [
-            vol.Schema({vol.Required("name"): str, vol.Required("url"): str}, extra=vol.ALLOW_EXTRA)
-        ],
+        vol.Optional("pdfs"): vol.All(
+            [vol.Schema({vol.Required("name"): _TEXT, vol.Required("url"): _URL}, extra=vol.ALLOW_EXTRA)],
+            vol.Length(max=MAX_PDFS),
+        ),
     },
     extra=vol.ALLOW_EXTRA,
 )
@@ -225,13 +680,23 @@ CONFIG_SCHEMA = vol.Schema(
         vol.Optional("settings", default=dict): vol.Schema(
             {
                 vol.Optional("glow_radius_cm"): vol.All(vol.Coerce(float), vol.Range(min=10, max=10000)),
-                vol.Optional("known_devices"): [str],
-                vol.Optional("new_device_ids"): [str],
+                # background around the plan, all spaces (a space may override)
+                vol.Optional("bg_color"): _COLOR,
+                # sun on the plan (docs/SUN.md): global defaults
+                vol.Optional("north_deg"): _north_deg,
+                vol.Optional("bg_mode"): _BG_MODE,
+                vol.Optional("sun_rays"): bool,
+                # Removed from the UI/runtime in 2026-08-08. Keep accepting the
+                # legacy field so an existing stored config can still load; the
+                # frontend ignores it and removes it on the next settings save.
+                vol.Optional("weather_entity"): vol.Any(None, _TEXT),
+                vol.Optional("known_devices"): vol.All([_TEXT], vol.Length(max=MAX_KNOWN_DEVICES)),
+                vol.Optional("new_device_ids"): vol.All([_TEXT], vol.Length(max=MAX_KNOWN_DEVICES)),
                 vol.Optional("fill_colors"): vol.Schema(
                     {
                         str: vol.Schema(
                             {
-                                vol.Required("c"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+                                vol.Required("c"): _COLOR,
                                 vol.Required("a"): vol.All(vol.Coerce(float), vol.Range(min=0, max=1)),
                             }
                         )

custom_components/houseplan/websocket_api.py

@@ -5,7 +5,9 @@ import logging
 
 import base64
 import binascii
+import json
 import secrets
+import time
 from pathlib import Path
 from typing import Any
 
@@ -15,31 +17,74 @@ from homeassistant.components import websocket_api
 from homeassistant.core import HomeAssistant, callback
 
 from .const import (
+    DOMAIN,
     CONF_ADMIN_ONLY, DEFAULT_CONFIG,
-    CONTENT_URL, MAX_SIGN_PATHS, PLANS_DIR, PLANS_URL,
+    CONTENT_URL, FILES_DIR, MAX_PLANS_BYTES, MAX_PLANS_FILES, MAX_PLANS_LISTED,
+    MAX_SIGN_PATHS,
+    PLANS_DIR, PLANS_URL,
 )
 from .auth import may_write
-from .plans import collect_plans
+from .plans import (
+    QuotaError, check_quota, collect_attachments, collect_plans, is_plan_file,
+    plan_basename, plan_refs, reserve_filename,
+)
 from .store import HouseplanData, get_data, get_entry
 from .validation import (
-    CONFIG_SCHEMA, LAYOUT_SCHEMA, MAX_PLAN_BYTES,
-    PLAN_EXTENSIONS, POS_SCHEMA, valid_space_id,
+    CONFIG_SCHEMA, LAYOUT_SCHEMA, MAX_CONFIG_BYTES, MAX_PLAN_BYTES,
+    PLAN_EXTENSIONS, POS_SCHEMA, sanitize_filename, valid_space_id,
 )
 
 
 _LOGGER = logging.getLogger(__name__)
 
+_OPTIMIZE_BACKUP = "optimize_backup"
+_OPTIMIZE_PENDING = "optimize_pending"
+
+
+def _optimizer_backup_is_current(config_data: dict[str, Any], layout_data: dict[str, Any]) -> bool:
+    """An optimization can be undone only before any later plan edit."""
+    backup = layout_data.get(_OPTIMIZE_BACKUP)
+    if not isinstance(backup, dict):
+        return False
+    try:
+        return (
+            int(backup.get("after_config_rev", -1)) == int(config_data.get("rev", 0))
+            and int(backup.get("after_layout_rev", -1)) == int(layout_data.get("rev", 0))
+        )
+    except (TypeError, ValueError):
+        return False
+
+
+async def _discard_optimizer_snapshot(rt: HouseplanData) -> None:
+    """Free a snapshot made stale by a later ordinary config edit."""
+    data = await rt.store.async_load() or {}
+    if _OPTIMIZE_BACKUP not in data and _OPTIMIZE_PENDING not in data:
+        return
+    await rt.store.async_save({
+        **{
+            k: v for k, v in data.items()
+            if k not in (_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)
+        }
+    })
+
 
 @callback
 def async_register(hass: HomeAssistant) -> None:
     """Register the WS commands."""
     websocket_api.async_register_command(hass, ws_layout_get)
+    websocket_api.async_register_command(hass, ws_trail_get)
+    websocket_api.async_register_command(hass, ws_trail_delete)
     websocket_api.async_register_command(hass, ws_layout_set)
+    websocket_api.async_register_command(hass, ws_geometry_repair)
     websocket_api.async_register_command(hass, ws_layout_update)
     websocket_api.async_register_command(hass, ws_layout_delete)
     websocket_api.async_register_command(hass, ws_config_get)
     websocket_api.async_register_command(hass, ws_config_set)
+    websocket_api.async_register_command(hass, ws_plan_optimize)
+    websocket_api.async_register_command(hass, ws_plan_optimize_undo)
     websocket_api.async_register_command(hass, ws_plan_set)
+    websocket_api.async_register_command(hass, ws_plans_list)
+    websocket_api.async_register_command(hass, ws_plans_delete)
     websocket_api.async_register_command(hass, ws_files_migrate)
     websocket_api.async_register_command(hass, ws_files_cleanup)
     websocket_api.async_register_command(hass, ws_content_sign)
@@ -66,6 +111,36 @@ def _check_write(hass: HomeAssistant, connection) -> bool:
 # ---------------- layout ----------------
 
 
+def _live_layout(config: dict[str, Any], layout: dict[str, Any]) -> dict[str, Any]:
+    """Drop positions which a deleted marker can no longer own.
+
+    HA device ids may be layout-only because auto-discovered devices need no
+    marker entry. Virtual ids are different: every live virtual marker is
+    explicit, so a missing `v_*` owner is stale data. The prefix itself is
+    only a legacy naming convention, however; an explicit real marker remains
+    authoritative even when its id happens to begin with `v_`.
+    """
+    markers = config.get("markers") or []
+    removed_ids = {
+        str(m.get("id")) for m in markers if m.get("removed") is True
+    }
+    virtual_ids = {
+        str(m.get("id")) for m in markers
+        if m.get("removed") is not True and m.get("binding") == "virtual"
+    }
+    explicit_live_ids = {
+        str(m.get("id")) for m in markers
+        if m.get("removed") is not True and m.get("binding") != "virtual"
+    }
+    return {
+        marker_id: pos for marker_id, pos in layout.items()
+        if marker_id not in removed_ids
+        and (not marker_id.startswith("v_")
+             or marker_id in virtual_ids
+             or marker_id in explicit_live_ids)
+    }
+
+
 @websocket_api.websocket_command({vol.Required("type"): "houseplan/layout/get"})
 @websocket_api.async_response
 async def ws_layout_get(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
@@ -74,7 +149,14 @@ async def ws_layout_get(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
     if rt is None:
         return
     data = await rt.store.async_load() or {}
-    connection.send_result(msg["id"], {"layout": data.get("layout", {})})
+    config_data = await rt.config_store.async_load() or {}
+    connection.send_result(
+        msg["id"], {
+            "layout": data.get("layout", {}),
+            "rev": int(data.get("rev", 0)),
+            "can_optimize_undo": _optimizer_backup_is_current(config_data, data),
+        }
+    )
 
 
 @websocket_api.websocket_command(
@@ -100,6 +182,7 @@ async def ws_layout_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
     if rt is None:
         return
     async with rt.write_lock:
+        config_data = await rt.config_store.async_load() or {}
         data = await rt.store.async_load() or {}
         current_rev = int(data.get("rev", 0))
         if "expected_rev" in msg and msg["expected_rev"] != current_rev:
@@ -107,8 +190,13 @@ async def ws_layout_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
                 msg["id"], "conflict", f"Layout changed elsewhere (rev {current_rev})"
             )
             return
-        await rt.store.async_save({"layout": msg["layout"], "rev": current_rev + 1})
-    connection.send_result(msg["id"], {"ok": True, "rev": current_rev + 1})
+        layout = _live_layout(config_data.get("config") or {}, msg["layout"])
+        new_rev = current_rev + 1
+        await rt.store.async_save({**{k: v for k, v in data.items() if k not in (
+                                       "layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)},
+                                   "layout": layout, "rev": new_rev})
+    hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
+    connection.send_result(msg["id"], {"ok": True, "rev": new_rev})
 
 
 @websocket_api.websocket_command(
@@ -128,11 +216,139 @@ async def ws_layout_update(hass: HomeAssistant, connection, msg: dict[str, Any])
     if rt is None:
         return
     async with rt.write_lock:
+        # A stale browser may still finish a drag after another client deleted
+        # the marker. Its tombstone is the server-side authority: acknowledge
+        # but ignore the late point so re-adding starts without a zombie
+        # position.
+        config_data = await rt.config_store.async_load() or {}
+        config = config_data.get("config") or {}
+        markers = config.get("markers") or []
+        deleted = any(
+            str(m.get("id")) == msg["device_id"] and m.get("removed") is True
+            for m in markers
+        )
+        live_virtual = any(
+            str(m.get("id")) == msg["device_id"] and m.get("removed") is not True
+            and m.get("binding") == "virtual"
+            for m in markers
+        )
+        live_explicit = any(
+            str(m.get("id")) == msg["device_id"] and m.get("removed") is not True
+            for m in markers
+        )
+        orphan_virtual = (
+            msg["device_id"].startswith("v_")
+            and not live_virtual
+            and not live_explicit
+        )
+        if deleted or orphan_virtual:
+            data = await rt.store.async_load() or {}
+            connection.send_result(msg["id"], {
+                "ok": True,
+                "ignored": "removed" if deleted else "missing_virtual",
+                "rev": int(data.get("rev", 0)),
+            })
+            return
         data = await rt.store.async_load() or {}
         layout = data.get("layout", {})
         layout[msg["device_id"]] = msg["pos"]
-        await rt.store.async_save({"layout": layout})
-    connection.send_result(msg["id"], {"ok": True})
+        # keep the revision: a point-wise write used to drop it, which made the
+        # optimistic locking on layout/set meaningless — every drag reset the
+        # counter to 0 (HP-1454-08)
+        new_rev = int(data.get("rev", 0)) + 1
+        await rt.store.async_save({**{k: v for k, v in data.items() if k not in (
+                                       "layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)},
+                                   "layout": layout, "rev": new_rev})
+    hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
+    connection.send_result(msg["id"], {"ok": True, "rev": new_rev})
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/geometry/repair",
+        vol.Required("space_id"): str,
+        vol.Required("aspect"): vol.All(vol.Coerce(float), vol.Range(min=0.05, max=20)),
+        vol.Optional("dry_run"): bool,
+        vol.Optional("undo"): bool,
+    }
+)
+@websocket_api.async_response
+async def ws_geometry_repair(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Re-apply the square-canvas transform to ONE space's layout, explicitly.
+
+    For installations that hit the v1.48/v1.49 crash window: the config write
+    of the migration landed, the layout write did not, and the trigger fields
+    were already gone — markers and labels of that space are stranded in the
+    old coordinates with nothing able to tell (HP-1500-01). Nothing can be
+    detected reliably after the fact, and re-running a transform on a layout
+    that is already correct would corrupt it, so this NEVER runs by itself:
+    an administrator names the space and its old aspect, may preview with
+    `dry_run`, and gets a one-deep backup written in the same store write —
+    `undo` restores it.
+    """
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only administrators may repair the layout")
+        return
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    from .geometry_migration import migrate_layout
+
+    space_id = msg["space_id"]
+    if not valid_space_id(space_id):
+        connection.send_error(msg["id"], "invalid_space_id", "space_id: only [a-z0-9_-], up to 64 characters")
+        return
+    async with rt.write_lock:
+        data = await rt.store.async_load() or {}
+        layout = data.get("layout") or {}
+        current_rev = int(data.get("rev", 0))
+        if msg.get("undo"):
+            backup = data.get("repair_backup")
+            if not isinstance(backup, dict) or backup.get("space") != space_id:
+                connection.send_error(msg["id"], "no_backup", "No repair backup stored for this space")
+                return
+            restored = dict(layout)
+            for key, pos in (backup.get("positions") or {}).items():
+                restored[key] = pos
+            new_rev = current_rev + 1
+            await rt.store.async_save({"layout": restored, "rev": new_rev})
+            hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
+            connection.send_result(msg["id"], {"ok": True, "rev": new_rev,
+                                               "restored": len(backup.get("positions") or {})})
+            return
+        touched = {
+            k: dict(v) for k, v in layout.items()
+            if isinstance(v, dict) and str(v.get("s")) == space_id
+        }
+        if not touched:
+            # A typo'd space id used to "succeed" with moved: 0 — and its
+            # empty result REPLACED the one-deep backup, destroying the very
+            # undo this endpoint promises (HP-1501-02). Nothing to move means
+            # nothing to save: no write, no revision bump, the backup stays.
+            connection.send_error(
+                msg["id"], "nothing_to_repair",
+                f"No stored positions belong to space '{space_id}'",
+            )
+            return
+        preview = {k: dict(v) for k, v in touched.items()}
+        migrate_layout(preview, {space_id: msg["aspect"]})
+        if msg.get("dry_run"):
+            connection.send_result(msg["id"], {
+                "ok": True, "dry_run": True, "moved": len(preview),
+                "before": touched, "after": preview,
+            })
+            return
+        new_layout = {**layout, **preview}
+        new_rev = current_rev + 1
+        # the backup rides the same store write: either both are durable or
+        # neither — the deletion-shy rules of this project apply to positions
+        # too
+        await rt.store.async_save({
+            "layout": new_layout, "rev": new_rev,
+            "repair_backup": {"space": space_id, "positions": touched},
+        })
+    hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
+    connection.send_result(msg["id"], {"ok": True, "rev": new_rev, "moved": len(preview)})
 
 
 @websocket_api.websocket_command(
@@ -183,17 +399,18 @@ async def ws_files_migrate(hass: HomeAssistant, connection, msg: dict[str, Any])
         for f in sorted(src.iterdir()):
             if not f.is_file():
                 continue
-            target = dst / f.name
-            if target.exists():
-                # a different file already owns this name — do NOT silently
-                # point the url at it; give the copy a unique name instead
-                stem, suffix = f.stem, f.suffix
-                i = 2
-                while (dst / f"{stem} ({i}){suffix}").exists():
-                    i += 1
-                target = dst / f"{stem} ({i}){suffix}"
-            shutil.copy2(str(f), str(target))
-            mapping[f.name] = target.name
+            # a different file may already own this name — do NOT silently point
+            # the url at it. The shared helper CLAIMS a free one atomically, so
+            # a concurrent migrate or upload cannot pick the same one, and the
+            # name it returns is one the content view accepts back in a request.
+            name = reserve_filename(dst, f.name)
+            target = dst / name
+            try:
+                shutil.copy2(str(f), str(target))
+            except OSError:
+                target.unlink(missing_ok=True)  # never leave an empty placeholder
+                raise
+            mapping[f.name] = name
         return mapping
 
     try:
@@ -204,6 +421,105 @@ async def ws_files_migrate(hass: HomeAssistant, connection, msg: dict[str, Any])
     connection.send_result(msg["id"], {"ok": True, "mapping": mapping, "copied": len(mapping)})
 
 
+@websocket_api.websocket_command({vol.Required("type"): "houseplan/plans/list"})
+@websocket_api.async_response
+async def ws_plans_list(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Plan images on the server, with what still uses them.
+
+    Files are never removed for being unreferenced (docs/SCOPE.md), which only
+    works as a policy if the user can see them: detaching a plan keeps the
+    image, and this is how it gets picked up again — or deleted on purpose.
+    """
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    stored = await rt.config_store.async_load() or {}
+    cfg = stored.get("config") or {}
+    used: dict[str, list[str]] = {}
+    for space in cfg.get("spaces") or []:
+        name = plan_basename(space.get("plan_url"))
+        if name:
+            used.setdefault(name, []).append(space.get("title") or space.get("id") or "?")
+
+    plans_dir = Path(hass.config.path(PLANS_DIR))
+
+    def _scan() -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        if not plans_dir.is_dir():
+            return out
+        for item in sorted(plans_dir.iterdir()):
+            if not item.is_file() or not is_plan_file(item.name):
+                continue
+            try:
+                st = item.stat()
+            except OSError:
+                continue
+            out.append({
+                "name": item.name,
+                "url": f"{CONTENT_URL}/plans/_/{item.name}",
+                "size": st.st_size,
+                "modified": int(st.st_mtime),
+                "used_by": used.get(item.name, []),
+            })
+        out.sort(key=lambda x: -x["modified"])
+        return out
+
+    plans = await hass.async_add_executor_job(_scan)
+    # newest first and capped: a folder with thousands of files would otherwise
+    # become one huge message, one huge list and a signing request per row
+    connection.send_result(
+        msg["id"], {"plans": plans[:MAX_PLANS_LISTED], "total": len(plans)}
+    )
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/plans/delete",
+        vol.Required("name"): str,
+    }
+)
+@websocket_api.async_response
+async def ws_plans_delete(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Delete a plan image because the user asked — the only way one goes.
+
+    Refuses while a space still references it: the answer to "can I delete this"
+    is the stored configuration's, not the client's.
+    """
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only administrators may delete plans")
+        return
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    name = sanitize_filename(msg["name"])
+    if not is_plan_file(name):
+        connection.send_error(msg["id"], "invalid_name", "Not a plan file")
+        return
+
+    async with rt.write_lock:
+        stored = await rt.config_store.async_load() or {}
+        cfg = stored.get("config") or {}
+        if name in plan_refs(cfg):
+            connection.send_error(
+                msg["id"], "in_use", "A space still uses this plan — detach it first"
+            )
+            return
+        path = Path(hass.config.path(PLANS_DIR)) / name
+
+        def _rm() -> bool:
+            try:
+                path.unlink()
+                return True
+            except FileNotFoundError:
+                return False
+            except OSError as err:
+                _LOGGER.warning("House Plan: could not delete %s: %s", path, err)
+                return False
+
+        removed = await hass.async_add_executor_job(_rm)
+    connection.send_result(msg["id"], {"ok": True, "removed": removed})
+
+
 @websocket_api.websocket_command(
     {
         vol.Required("type"): "houseplan/content/sign",
@@ -252,34 +568,68 @@ async def ws_content_sign(hass: HomeAssistant, connection, msg: dict[str, Any])
 )
 @websocket_api.async_response
 async def ws_files_cleanup(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
-    """Delete a marker's file folder — called only AFTER the config is committed."""
+    """Drop a marker folder's leftovers after its files moved elsewhere.
+
+    Called after a rebind: the files were copied to the new marker id and the
+    config that references them is committed, so the source folder is spent.
+
+    It used to `rmtree` the folder on the client's word alone. Two ways that
+    ends badly: a partial copy leaves some urls still pointing INTO this folder
+    (the migration deliberately does not rewrite those), and a wrong or stale
+    id from any client deletes a live marker's attachments outright. So the
+    server checks for itself — under the config lock — and removes only files
+    the stored configuration does not reference. Same principle as the
+    collector: a client may say what it no longer needs, never what may go.
+    """
     if not _check_write(hass, connection):
         connection.send_error(msg["id"], "unauthorized", "Only administrators may edit files")
         return
-    import shutil
-    from pathlib import Path
-
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
     from .const import FILES_DIR
+    from .plans import attachment_refs
     from .validation import sanitize_marker_id
 
     mid = sanitize_marker_id(msg["marker_id"])
-    if not mid:
-        connection.send_result(msg["id"], {"ok": True, "removed": False})
-        return
     base = Path(hass.config.path(FILES_DIR)).resolve()
-    target = (base / mid).resolve()
-    if not str(target).startswith(str(base)) or target == base:
-        connection.send_result(msg["id"], {"ok": True, "removed": False})
+    target = (base / mid).resolve() if mid else base
+    if not mid or not str(target).startswith(str(base)) or target == base:
+        connection.send_result(msg["id"], {"ok": True, "removed": 0, "kept": 0})
         return
 
-    def _rm() -> bool:
-        if not target.is_dir():
-            return False
-        shutil.rmtree(target, ignore_errors=True)
-        return True
+    async with rt.write_lock:
+        stored = await rt.config_store.async_load() or {}
+        refs = attachment_refs(stored.get("config") or {})
 
-    removed = await hass.async_add_executor_job(_rm)
-    connection.send_result(msg["id"], {"ok": True, "removed": removed})
+        def _rm() -> tuple[int, int]:
+            if not target.is_dir():
+                return 0, 0
+            removed = kept = 0
+            for item in sorted(target.iterdir()):
+                if not item.is_file():
+                    continue
+                if f"{mid}/{item.name}" in refs:
+                    kept += 1
+                    continue
+                try:
+                    item.unlink()
+                    removed += 1
+                except OSError as err:
+                    _LOGGER.warning("House Plan: could not remove %s: %s", item, err)
+            if not kept:
+                try:
+                    target.rmdir()
+                except OSError:
+                    pass
+            return removed, kept
+
+        removed, kept = await hass.async_add_executor_job(_rm)
+    if kept:
+        _LOGGER.info(
+            "House Plan: kept %s file(s) in %s — the configuration still references them", kept, mid
+        )
+    connection.send_result(msg["id"], {"ok": True, "removed": removed, "kept": kept})
 
 
 @websocket_api.websocket_command(
@@ -297,13 +647,19 @@ async def ws_layout_delete(hass: HomeAssistant, connection, msg: dict[str, Any])
     rt = _runtime(hass, connection, msg["id"])
     if rt is None:
         return
+    new_rev: int | None = None
     async with rt.write_lock:
         data = await rt.store.async_load() or {}
         layout = data.get("layout", {})
         if msg["device_id"] in layout:
             del layout[msg["device_id"]]
-            await rt.store.async_save({"layout": layout})
-    connection.send_result(msg["id"], {"ok": True})
+            new_rev = int(data.get("rev", 0)) + 1
+            await rt.store.async_save({**{k: v for k, v in data.items() if k not in (
+                                           "layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)},
+                                       "layout": layout, "rev": new_rev})
+    if new_rev is not None:
+        hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
+    connection.send_result(msg["id"], {"ok": True, "rev": new_rev})
 
 
 # ---------------- space configuration ----------------
@@ -312,16 +668,70 @@ async def ws_layout_delete(hass: HomeAssistant, connection, msg: dict[str, Any])
 @websocket_api.websocket_command({vol.Required("type"): "houseplan/config/get"})
 @websocket_api.async_response
 async def ws_config_get(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
-    """Return the configuration and its revision."""
+    """Return the configuration, its revision, and whether this user may write.
+
+    `can_write` is the single source of truth for the card's editor chrome
+    (audit P0-4): the UI must mirror `may_write`, not a hard-coded is_admin
+    check that drifted from the integration option.
+    """
     rt = _runtime(hass, connection, msg["id"])
     if rt is None:
         return
     data = await rt.config_store.async_load() or {}
+    layout_data = await rt.store.async_load() or {}
     config = {**DEFAULT_CONFIG, **data.get("config", {})}
-    connection.send_result(msg["id"], {"config": config, "rev": data.get("rev", 0)})
+    connection.send_result(
+        msg["id"],
+        {
+            "config": config,
+            "rev": data.get("rev", 0),
+            "can_write": may_write(hass, getattr(connection, "user", None)),
+            "can_optimize_undo": _optimizer_backup_is_current(data, layout_data),
+        },
+    )
 
 
 
+def _internal_plan_names(config: dict[str, Any]) -> set[str]:
+    """Plan file names a configuration names through OUR urls.
+
+    Only `/api/houseplan/content/plans/_/<name>` and the legacy static path
+    count. Anything else belongs to the user and may point wherever they like.
+    """
+    out: set[str] = set()
+    for space in (config or {}).get("spaces") or []:
+        url = space.get("plan_url")
+        if not isinstance(url, str) or not url:
+            continue
+        if not (url.startswith(CONTENT_URL + "/plans/") or url.startswith(PLANS_URL + "/")):
+            continue
+        name = plan_basename(url)
+        if name:
+            out.add(name)
+    return out
+
+
+def _missing_internal_plans(
+    plans_dir: Path, config: dict[str, Any], previous: dict[str, Any] | None = None
+) -> set[str]:
+    """Newly named plan files that are not on disk.
+
+    Guards the pick-then-save window: another client may delete a plan between
+    the moment this one chose it and the moment it saves, which would otherwise
+    store a url with nothing behind it (HP-1470-02).
+
+    A name the stored configuration already carries is deliberately let through.
+    It is already broken — repairs says so — and refusing the write would lock
+    the owner out of every other edit, including the one that detaches it.
+    """
+    known = _internal_plan_names(previous or {})
+    return {
+        name
+        for name in _internal_plan_names(config)
+        if name not in known and not (plans_dir / name).is_file()
+    }
+
+
 @websocket_api.websocket_command(
     {
         vol.Required("type"): "houseplan/config/set",
@@ -343,6 +753,16 @@ async def ws_config_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
     rt = _runtime(hass, connection, msg["id"])
     if rt is None:
         return
+    # Per-field limits bound each list; this bounds their product (HP-1454-05).
+    # Everything below the caps can still add up to something no dashboard can
+    # render, and the store writes it to disk on every save.
+    size = len(json.dumps(msg["config"], separators=(",", ":")))
+    if size > MAX_CONFIG_BYTES:
+        connection.send_error(
+            msg["id"], "too_large",
+            f"Configuration is {size // 1024} KB, the limit is {MAX_CONFIG_BYTES // 1024} KB",
+        )
+        return
     async with rt.write_lock:
         data = await rt.config_store.async_load() or {}
         current_rev = data.get("rev", 0)
@@ -361,21 +781,45 @@ async def ws_config_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
                 f"Configuration was changed in another window (rev {current_rev} != {msg['expected_rev']})",
             )
             return
+        # An internal plan url must name a file that exists. The card can pick a
+        # plan and then delete it from the same dialog, and two clients can do
+        # the same thing in either order — the lock serialises them but says
+        # nothing about whether the file survived (HP-1470-02). External and
+        # legacy urls are not ours to check and are left alone.
+        missing = await hass.async_add_executor_job(
+            _missing_internal_plans,
+            Path(hass.config.path(PLANS_DIR)),
+            msg["config"],
+            data.get("config"),
+        )
+        if missing:
+            connection.send_error(
+                msg["id"], "missing_plan",
+                "Plan file no longer exists: " + ", ".join(sorted(missing)),
+            )
+            return
         new_rev = current_rev + 1
         await rt.config_store.async_save({"config": msg["config"], "rev": new_rev})
+        try:
+            await _discard_optimizer_snapshot(rt)
+        except Exception:  # noqa: BLE001 — stale backup cleanup is best-effort
+            _LOGGER.exception("House Plan: discarding stale optimization backup failed")
         # Still holding the lock: the file system is not part of the store's
         # transaction, so collection has to be pinned to this commit (R3-1).
         # It is best-effort housekeeping behind an already durable write — a
         # failure here must not withhold the event and the success response,
         # or the client retries an edit the server has already accepted and
         # gets a conflict for its trouble (R4-1).
+        def _collect() -> None:
+            collect_plans(Path(hass.config.path(PLANS_DIR)), data.get("config"), msg["config"])
+            collect_attachments(Path(hass.config.path(FILES_DIR)), data.get("config"), msg["config"])
+
         try:
-            await hass.async_add_executor_job(
-                collect_plans, Path(hass.config.path(PLANS_DIR)), data.get("config"), msg["config"]
-            )
+            await hass.async_add_executor_job(_collect)
         except Exception:  # noqa: BLE001 — see above: the commit stands regardless
-            _LOGGER.exception("House Plan: collecting superseded plan files failed")
+            _LOGGER.exception("House Plan: collecting superseded files failed")
     hass.bus.async_fire("houseplan_config_updated", {"rev": new_rev})
+    _refresh_trail_recorder(hass)
     # refresh repair issues (broken plan references) without waiting for a restart
     entry = get_entry(hass)
     if entry is not None:
@@ -385,6 +829,184 @@ async def ws_config_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
     connection.send_result(msg["id"], {"ok": True, "rev": new_rev})
 
 
+# ---------------- whole-plan maintenance ----------------
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/plan/optimize",
+        vol.Required("config"): CONFIG_SCHEMA,
+        vol.Required("layout"): LAYOUT_SCHEMA,
+        vol.Required("expected_config_rev"): int,
+        vol.Required("expected_layout_rev"): int,
+    }
+)
+@websocket_api.async_response
+async def ws_plan_optimize(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Atomically-intended replacement of config+layout with one-deep undo.
+
+    Home Assistant stores are separate files, so a literal cross-file
+    transaction is impossible. Persisting the target as an intent before
+    either half changes makes a crash resumable during the next setup; the UI
+    only receives success once both halves are durable.
+    """
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only administrators may optimize plans")
+        return
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    size = len(json.dumps(msg["config"], separators=(",", ":")))
+    if size > MAX_CONFIG_BYTES:
+        connection.send_error(
+            msg["id"], "too_large",
+            f"Configuration is {size // 1024} KB, the limit is {MAX_CONFIG_BYTES // 1024} KB",
+        )
+        return
+
+    async with rt.write_lock:
+        config_data = await rt.config_store.async_load() or {}
+        layout_data = await rt.store.async_load() or {}
+        config_rev = int(config_data.get("rev", 0))
+        layout_rev = int(layout_data.get("rev", 0))
+        if msg["expected_config_rev"] != config_rev or msg["expected_layout_rev"] != layout_rev:
+            connection.send_error(
+                msg["id"], "conflict",
+                f"Plan changed elsewhere (config {config_rev}, layout {layout_rev})",
+            )
+            return
+
+        missing = await hass.async_add_executor_job(
+            _missing_internal_plans,
+            Path(hass.config.path(PLANS_DIR)),
+            msg["config"],
+            config_data.get("config"),
+        )
+        if missing:
+            connection.send_error(
+                msg["id"], "missing_plan",
+                "Plan file no longer exists: " + ", ".join(sorted(missing)),
+            )
+            return
+
+        new_config_rev = config_rev + 1
+        new_layout_rev = layout_rev + 1
+        backup = {
+            "config": config_data.get("config") or DEFAULT_CONFIG,
+            "layout": layout_data.get("layout", {}),
+            "created": int(time.time()),
+            "after_config_rev": new_config_rev,
+            "after_layout_rev": new_layout_rev,
+        }
+        pending = {
+            "config": msg["config"],
+            "layout": msg["layout"],
+            "clear_backup": False,
+        }
+        layout_meta = {
+            k: v for k, v in layout_data.items()
+            if k not in ("layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)
+        }
+
+        # Intent first. A setup-time finisher completes whichever half a crash
+        # interrupted; until then the visible layout/revision remain unchanged.
+        await rt.store.async_save({
+            **layout_meta,
+            "layout": layout_data.get("layout", {}),
+            "rev": layout_rev,
+            _OPTIMIZE_BACKUP: backup,
+            _OPTIMIZE_PENDING: pending,
+        })
+        await rt.config_store.async_save({"config": msg["config"], "rev": new_config_rev})
+        await rt.store.async_save({
+            **layout_meta,
+            "layout": msg["layout"],
+            "rev": new_layout_rev,
+            _OPTIMIZE_BACKUP: backup,
+        })
+
+    hass.bus.async_fire("houseplan_config_updated", {"rev": new_config_rev})
+    hass.bus.async_fire("houseplan_layout_updated", {"rev": new_layout_rev})
+    _refresh_trail_recorder(hass)
+    connection.send_result(msg["id"], {
+        "ok": True,
+        "config_rev": new_config_rev,
+        "layout_rev": new_layout_rev,
+        "can_undo": True,
+    })
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/plan/optimize_undo",
+        vol.Required("expected_config_rev"): int,
+        vol.Required("expected_layout_rev"): int,
+    }
+)
+@websocket_api.async_response
+async def ws_plan_optimize_undo(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Restore the snapshot, but never overwrite edits made after optimization."""
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only administrators may undo optimization")
+        return
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+
+    async with rt.write_lock:
+        config_data = await rt.config_store.async_load() or {}
+        layout_data = await rt.store.async_load() or {}
+        config_rev = int(config_data.get("rev", 0))
+        layout_rev = int(layout_data.get("rev", 0))
+        if msg["expected_config_rev"] != config_rev or msg["expected_layout_rev"] != layout_rev:
+            connection.send_error(msg["id"], "conflict", "Plan changed elsewhere")
+            return
+        if not _optimizer_backup_is_current(config_data, layout_data):
+            connection.send_error(
+                msg["id"], "no_backup",
+                "The optimization backup is unavailable or a later edit made it stale",
+            )
+            return
+
+        backup = layout_data[_OPTIMIZE_BACKUP]
+        restored_config = backup.get("config") or DEFAULT_CONFIG
+        restored_layout = backup.get("layout") or {}
+        new_config_rev = config_rev + 1
+        new_layout_rev = layout_rev + 1
+        pending = {
+            "config": restored_config,
+            "layout": restored_layout,
+            "clear_backup": True,
+        }
+        layout_meta = {
+            k: v for k, v in layout_data.items()
+            if k not in ("layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)
+        }
+        await rt.store.async_save({
+            **layout_meta,
+            "layout": layout_data.get("layout", {}),
+            "rev": layout_rev,
+            _OPTIMIZE_BACKUP: backup,
+            _OPTIMIZE_PENDING: pending,
+        })
+        await rt.config_store.async_save({"config": restored_config, "rev": new_config_rev})
+        await rt.store.async_save({
+            **layout_meta,
+            "layout": restored_layout,
+            "rev": new_layout_rev,
+        })
+
+    hass.bus.async_fire("houseplan_config_updated", {"rev": new_config_rev})
+    hass.bus.async_fire("houseplan_layout_updated", {"rev": new_layout_rev})
+    _refresh_trail_recorder(hass)
+    connection.send_result(msg["id"], {
+        "ok": True,
+        "config_rev": new_config_rev,
+        "layout_rev": new_layout_rev,
+        "can_undo": False,
+    })
+
+
 # ---------------- plan uploads ----------------
 
 
@@ -419,10 +1041,11 @@ async def ws_plan_set(hass: HomeAssistant, connection, msg: dict[str, Any]) -> N
     # deleted here (review R2-1). The old name stays readable, so a config write
     # that is later rejected — revision conflict, validation, lost connection —
     # leaves the stored plan exactly as it was. The card calls
-    # nothing here; the superseded file is collected by `config/set` itself,
-    # inside the write lock, once a revision that no longer references it has
-    # been accepted (review R3-1). A crash in between leaves an orphan, which
-    # the same collector removes on a later commit once it is old enough.
+    # nothing here; the file a commit REPLACES is collected by `config/set`
+    # itself, inside the write lock (review R3-1). An upload that never gets
+    # committed is not collected at all — it is offered back in the space
+    # dialog's "already uploaded" list, where the user can attach or delete it.
+    # Every attempt to age these out ended in data loss or a race (v1.46.4-6).
     #
     # `.` separates the id from the token because a space id cannot contain one
     # (SPACE_ID_RE), so "<space>.<token>.<ext>" can never be confused with the
@@ -431,9 +1054,56 @@ async def ws_plan_set(hass: HomeAssistant, connection, msg: dict[str, Any]) -> N
     name = f"{space_id}.{secrets.token_hex(4)}.{msg['ext']}"
     path = plans_dir / name
 
-    def _write() -> None:
+    def _check_and_write() -> None:
+        # one executor job for the pair, under upload_lock: the measurement
+        # is only a bound if nothing else writes between it and our write
+        # (HP-1490-02). A failed write reserves nothing — the file either
+        # exists and is counted by the next scan, or does not and is not.
+        check_quota(plans_dir, len(raw), MAX_PLANS_BYTES, MAX_PLANS_FILES)
         plans_dir.mkdir(parents=True, exist_ok=True)
         path.write_bytes(raw)
 
-    await hass.async_add_executor_job(_write)
+    data = _runtime(hass, connection, msg["id"])
+    if data is None:
+        return
+    async with data.upload_lock:
+        try:
+            await hass.async_add_executor_job(_check_and_write)
+        except QuotaError as err:
+            connection.send_error(msg["id"], err.reason, err.detail)
+            return
     connection.send_result(msg["id"], {"ok": True, "url": f"{CONTENT_URL}/plans/_/{name}"})
+
+
+def _refresh_trail_recorder(hass: HomeAssistant) -> None:
+    """Markers changed — the trail recorder must re-resolve what it watches."""
+    rec = hass.data.get(DOMAIN, {}).get("trail_recorder")
+    if rec:
+        hass.async_create_task(rec.async_refresh())
+
+
+@websocket_api.websocket_command({vol.Required("type"): "houseplan/trail/get"})
+@websocket_api.async_response
+async def ws_trail_get(hass: HomeAssistant, connection: websocket_api.ActiveConnection, msg: dict) -> None:
+    """Current + previous cleanup runs per marker, raw robot coordinates."""
+    rec = hass.data.get(DOMAIN, {}).get("trail_recorder")
+    connection.send_result(msg["id"], {"trails": rec.book.data if rec else {}})
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/trail/delete",
+        vol.Required("marker_id"): vol.All(str, vol.Length(min=1, max=256)),
+    }
+)
+@websocket_api.async_response
+async def ws_trail_delete(hass: HomeAssistant, connection: websocket_api.ActiveConnection, msg: dict) -> None:
+    """Permanently forget one deleted marker's current and previous runs."""
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only administrators may delete trails")
+        return
+    if _runtime(hass, connection, msg["id"]) is None:
+        return
+    rec = hass.data.get(DOMAIN, {}).get("trail_recorder")
+    removed = await rec.async_delete(msg["marker_id"]) if rec else False
+    connection.send_result(msg["id"], {"ok": True, "removed": removed})

demo/benchmark_glow.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/** Isolated 1/10/30/60-pool performance profiles for #19 and #55. */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { launch } from './serve.mjs';
+import { assertFreshDemoBundle } from './bundle-freshness.mjs';
+import { summarizeLongTasks, summarizeTimings } from './performance/evaluate.mjs';
+import { makeLargeHouseFixture } from './fixtures/large-house.mjs';
+import { assertCardContract, GLOW_CARD_CONTRACT } from './performance/card-contract.mjs';
+
+const valueArg = (name) => process.argv.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+const profile = valueArg('profile') || 'large-light-blend-v1';
+if (!['large-light-blend-v1', 'large-house-glow-overlay-v1'].includes(profile))
+  throw new Error(`unknown Glow profile: ${profile}`);
+const parsedSamples = Number(valueArg('samples'));
+const parsedWarmups = Number(valueArg('warmups'));
+const samples = Math.max(1, Math.min(20, Number.isFinite(parsedSamples) && parsedSamples > 0 ? parsedSamples : 7));
+const warmups = Math.max(0, Math.min(5, Number.isFinite(parsedWarmups) && parsedWarmups >= 0 ? parsedWarmups : 1));
+const requestedVariants = valueArg('variants')?.split(',').map(Number);
+if (requestedVariants?.some((count) => ![1, 10, 30, 60].includes(count)))
+  throw new Error(`invalid Glow variants: ${valueArg('variants')}`);
+const output = valueArg('output') ? resolve(valueArg('output')) : null;
+const targetRoot = resolve(valueArg('target-root') ?? '.');
+const additiveFixture = JSON.parse(readFileSync(
+  new URL('../test/fixtures/glow/additive-pools.json', import.meta.url), 'utf8',
+));
+additiveFixture.sourceIds = Object.keys(additiveFixture.ha.states)
+  .filter((entityId) => entityId.startsWith('light.'));
+additiveFixture.roomCount = additiveFixture.config.spaces
+  .reduce((sum, space) => sum + space.rooms.length, 0);
+additiveFixture.deviceCount = Object.keys(additiveFixture.ha.devices).length;
+
+const makeOverlayFixture = () => {
+  const large = makeLargeHouseFixture();
+  const firstSpace = large.config.spaces[0].id;
+  const sourceDeviceIds = Object.entries(large.layout)
+    .filter(([, position]) => position.s === firstSpace)
+    .slice(0, 60)
+    .map(([deviceId]) => deviceId);
+  const sourceIds = [];
+  sourceDeviceIds.forEach((deviceId, index) => {
+    for (const [entityId, entity] of Object.entries(large.entities)) {
+      if (entity.device_id !== deviceId) continue;
+      delete large.entities[entityId];
+      delete large.states[entityId];
+    }
+    const entityId = `light.glow_overlay_${String(index + 1).padStart(3, '0')}`;
+    large.entities[entityId] = {
+      entity_id: entityId, device_id: deviceId, platform: 'houseplan_perf',
+      config_entry_id: 'perf_entry', disabled_by: null,
+    };
+    large.states[entityId] = {
+      entity_id: entityId, state: 'on',
+      attributes: {
+        friendly_name: `Overlay light ${index + 1}`,
+        brightness: 96 + (index % 5) * 32,
+        rgb_color: index % 2 ? [255, 154, 72] : [92, 156, 255],
+      },
+    };
+    sourceIds.push(entityId);
+  });
+  // The shared large-house fixture already contains a few ordinary lights.
+  // Keep them as devices but turn them off so the profile's pool cardinality
+  // is exactly the declared 1/10/30/60, not N plus an unrelated background lamp.
+  for (const [entityId, state] of Object.entries(large.states)) {
+    if (entityId.startsWith('light.') && !sourceIds.includes(entityId)) {
+      large.states[entityId] = { ...state, state: 'off' };
+    }
+  }
+  for (const space of large.config.spaces) {
+    space.settings = { ...(space.settings || {}), fill_mode: 'temp', glow_enabled: true };
+  }
+  return {
+    fixture: 'large-house-glow-overlay-v1', variants: [1, 10, 30, 60],
+    config: large.config, layout: large.layout,
+    ha: { devices: large.devices, entities: large.entities, areas: large.areas, states: large.states },
+    sourceIds,
+    roomCount: large.counts.rooms,
+    deviceCount: large.counts.devices,
+  };
+};
+const fixture = profile === 'large-light-blend-v1' ? additiveFixture : makeOverlayFixture();
+if (requestedVariants?.length) fixture.variants = [...new Set(requestedVariants)];
+const viewport = { width: 1280, height: 900 };
+
+const { page, browser } = await launch(
+  viewport, 1,
+  ['--enable-precise-memory-info', '--js-flags=--expose-gc'],
+  {}, resolve(targetRoot, 'demo/srv'),
+);
+await page.addScriptTag({
+  content: `window.__hpAssertCardContract = ${assertCardContract.toString()};`,
+});
+const cdp = await page.context().newCDPSession(page);
+await cdp.send('Emulation.setCPUThrottlingRate', { rate: 4 });
+await page.emulateMedia({ reducedMotion: 'reduce' });
+await page.addStyleTag({
+  content: '*,*::before,*::after{animation-duration:0s!important;transition-duration:0s!important;caret-color:transparent!important}',
+});
+const chromium = await browser.version();
+let buildFingerprint;
+try {
+  buildFingerprint = await assertFreshDemoBundle(page, targetRoot);
+} catch (error) {
+  await browser.close();
+  throw error;
+}
+
+const rows = [];
+try {
+  for (let iteration = 0; iteration < warmups + samples; iteration++) {
+    const sample = iteration - warmups;
+    const row = await page.evaluate(async ({ fixture, profile, sample, cardContract }) => {
+      const frame = () => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+      const until = async (predicate, timeout = 10000) => {
+        const started = performance.now();
+        while (!predicate()) {
+          if (performance.now() - started > timeout) throw new Error('Glow benchmark timed out');
+          await new Promise((done) => setTimeout(done, 10));
+        }
+      };
+      const observeLongTasks = () => {
+        const entries = [];
+        if (!PerformanceObserver.supportedEntryTypes?.includes('longtask'))
+          return { stop: async () => ({ supported: false, count: 0, maxMs: 0, totalMs: 0 }) };
+        const observer = new PerformanceObserver((list) => entries.push(...list.getEntries()));
+        observer.observe({ type: 'longtask', buffered: false });
+        return { stop: async () => {
+          await new Promise((done) => setTimeout(done, 0));
+          entries.push(...observer.takeRecords());
+          observer.disconnect();
+          const values = entries.map((entry) => entry.duration);
+          return {
+            supported: true,
+            count: values.length,
+            maxMs: Number((values.length ? Math.max(...values) : 0).toFixed(2)),
+            totalMs: Number(values.reduce((sum, value) => sum + value, 0).toFixed(2)),
+          };
+        }};
+      };
+      const forceGc = async () => {
+        if (typeof globalThis.gc !== 'function') return false;
+        globalThis.gc(); await frame(); globalThis.gc(); await frame();
+        return true;
+      };
+      const configFor = () => {
+        const config = structuredClone(fixture.config);
+        if (profile === 'large-light-blend-v1') {
+          const settings = config.spaces[0].settings;
+          settings.fill_mode = 'glow';
+          delete settings.glow_enabled;
+        }
+        return config;
+      };
+      const statesFor = (count, brightnessDelta = 0) => {
+        const active = new Set(fixture.sourceIds.slice(0, count));
+        const sources = new Set(fixture.sourceIds);
+        return Object.fromEntries(Object.entries(fixture.ha.states).map(([entityId, state]) => {
+          if (!sources.has(entityId)) return [entityId, state];
+          return [entityId, {
+            ...state,
+            state: active.has(entityId) ? 'on' : 'off',
+            attributes: {
+              ...state.attributes,
+              brightness: Math.max(1, Math.min(255, Number(state.attributes.brightness) + brightnessDelta)),
+            },
+          }];
+        }));
+      };
+      const connection = {
+        subscribeEvents: async () => () => undefined,
+        subscribeMessage: async () => () => undefined,
+      };
+      const hassFor = (states) => ({
+        language: 'en', locale: { language: 'en' },
+        user: { id: 'glow-perf', name: 'Glow performance', is_admin: true },
+        devices: fixture.ha.devices, entities: fixture.ha.entities,
+        areas: fixture.ha.areas, states, floors: {}, connection,
+        callWS: async (message) => {
+          if (message.type === 'houseplan/config/get')
+            return { config: configFor(), rev: 1, can_write: true };
+          if (message.type === 'houseplan/layout/get')
+            return { layout: structuredClone(fixture.layout), rev: 1 };
+          if (message.type === 'config/device_registry/list') return Object.values(fixture.ha.devices);
+          if (message.type === 'config/entity_registry/list') return Object.values(fixture.ha.entities);
+          if (message.type === 'config_entries/get')
+            return [{ entry_id: 'glow_fixture', domain: 'houseplan_fixture', title: 'Glow fixture' }];
+          if (message.type === 'manifest/list')
+            return [{ domain: 'houseplan_fixture', name: 'House Plan Glow Fixture' }];
+          return { ok: true };
+        },
+        callService: async () => undefined,
+        localize: () => null,
+        formatEntityState: (state) => state.state,
+        config: { unit_system: { length: 'km' } },
+      });
+      const cacheSnapshot = (card) => ({
+        cleanFloor: card._cleanFloorCache?.size ?? 0,
+        glowClip: card._glowClipCache?.size ?? 0,
+        wallUnion: card._wallUnionCache ? 1 : 0,
+        openingTunnel: card._openingTunnelCache ? 1 : 0,
+        openingWallIndex: card._openingWallIndexCache ? 1 : 0,
+      });
+      window.__card?.remove?.();
+      localStorage.clear();
+      const host = document.getElementById('host');
+      const result = { sample, longTasks: {}, renderCounts: {}, poolCounts: {} };
+      const card = document.createElement('houseplan-card');
+      card.setConfig({ type: 'custom:houseplan-card', title: `Glow ${profile}`, icon_size: 2.4 });
+      host.replaceChildren(card);
+      card.hass = hassFor(statesFor(1));
+      window.__hpAssertCardContract(card, cardContract);
+      await until(() => card._loadOk && card._devices?.length === fixture.deviceCount);
+      if ('_glowScreenBlend' in card) {
+        const probeDeadline = performance.now() + 2500;
+        while (!card._glowScreenBlend && performance.now() < probeDeadline)
+          await new Promise((done) => setTimeout(done, 10));
+      }
+      await card.updateComplete;
+      await frame();
+      for (const count of fixture.variants) {
+        // Mount cost is not part of this profile. Prime each source-count
+        // state on the same full plan, then measure only the following HA tick.
+        card.hass = hassFor(statesFor(count));
+        await card.updateComplete;
+        await frame();
+        let renders = 0;
+        const originalUpdate = card.performUpdate.bind(card);
+        card.performUpdate = () => { renders++; return originalUpdate(); };
+        const longTasks = observeLongTasks();
+        const started = performance.now();
+        card.hass = hassFor(statesFor(count, 1));
+        await card.updateComplete;
+        await frame();
+        result[`stateUpdate${count}Ms`] = Number((performance.now() - started).toFixed(2));
+        result.longTasks[`stateUpdate${count}`] = await longTasks.stop();
+        result.renderCounts[count] = renders;
+        result.poolCounts[count] = card.renderRoot.querySelectorAll('.glow-pool, .glowlayer circle').length;
+      }
+      window.__card = card;
+      await forceGc();
+      const cacheBefore = cacheSnapshot(card);
+      const heapBefore = performance.memory?.usedJSHeapSize ?? null;
+      for (let index = 0; index < 5; index++) {
+        card.hass = hassFor(statesFor(60, index % 2));
+        await card.updateComplete;
+        await frame();
+      }
+      await forceGc();
+      const cacheEntries = cacheSnapshot(card);
+      const heapAfter = performance.memory?.usedJSHeapSize ?? null;
+      result.cacheEntries = cacheEntries;
+      result.cacheGrowth = Object.fromEntries(
+        Object.keys(cacheEntries).map((key) => [key, cacheEntries[key] - cacheBefore[key]]),
+      );
+      result.heapGrowthBytes = heapBefore == null || heapAfter == null ? null : heapAfter - heapBefore;
+      result.preciseGc = typeof globalThis.gc === 'function';
+      result.renderedDevices = card._devices?.length ?? 0;
+      result.screenBlend = card._glowScreenBlend === true;
+      return result;
+    }, { fixture, profile, sample, cardContract: GLOW_CARD_CONTRACT });
+    const captureStarted = performance.now();
+    await page.screenshot({ type: 'png' });
+    row.screenshotCaptureMs = Number((performance.now() - captureStarted).toFixed(2));
+    if (sample >= 0) rows.push(row);
+  }
+} finally {
+  await cdp.send('Emulation.setCPUThrottlingRate', { rate: 1 }).catch(() => undefined);
+  await browser.close();
+}
+
+const metricNames = [
+  ...fixture.variants.map((count) => `stateUpdate${count}Ms`), 'screenshotCaptureMs',
+];
+const report = {
+  schema: 2,
+  profile,
+  generatedAt: new Date().toISOString(),
+  buildFingerprint,
+  runtime: {
+    node: process.version, chromium, platform: process.platform, arch: process.arch,
+    viewport, deviceScaleFactor: 1, cpuThrottleRate: 4, reducedMotion: true,
+  },
+  fixture: {
+    id: fixture.fixture, variants: fixture.variants,
+    rooms: fixture.roomCount, devices: fixture.deviceCount,
+  },
+  samples,
+  warmups,
+  summary: summarizeTimings(rows, metricNames),
+  longTasks: summarizeLongTasks(rows),
+  rows,
+};
+const text = `${JSON.stringify(report, null, 2)}\n`;
+if (output) {
+  mkdirSync(dirname(output), { recursive: true });
+  writeFileSync(output, text, 'utf8');
+  console.log(output);
+} else process.stdout.write(text);

demo/benchmark_large_house.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/** Reproducible browser benchmark and report producer for HP-PERF-01. */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { launch } from './serve.mjs';
+import { LARGE_HOUSE_COUNTS, makeLargeHouseFixture } from './fixtures/large-house.mjs';
+import { assertFreshDemoBundle } from './bundle-freshness.mjs';
+import { summarizeLongTasks, summarizeTimings } from './performance/evaluate.mjs';
+import { assertCardContract, LARGE_HOUSE_CARD_CONTRACT } from './performance/card-contract.mjs';
+
+const valueArg = (name) => process.argv.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+const samples = Math.max(1, Math.min(20, Number(valueArg('samples')) || 7));
+const warmups = Math.max(0, Math.min(5, Number(valueArg('warmups')) || 1));
+const output = valueArg('output') ? resolve(valueArg('output')) : null;
+const targetRoot = resolve(valueArg('target-root') ?? '.');
+const fixture = makeLargeHouseFixture();
+const viewport = { width: 1440, height: 1000 };
+
+const { page, browser } = await launch(
+  viewport,
+  1,
+  ['--enable-precise-memory-info', '--js-flags=--expose-gc'],
+  {},
+  resolve(targetRoot, 'demo/srv'),
+);
+await page.emulateMedia({ reducedMotion: 'reduce' });
+await page.addStyleTag({
+  content: '*,*::before,*::after{animation-duration:0s!important;transition-duration:0s!important;caret-color:transparent!important}',
+});
+await page.addScriptTag({
+  content: `window.__hpAssertCardContract = ${assertCardContract.toString()};`,
+});
+const chromium = await browser.version();
+let buildFingerprint;
+try {
+  buildFingerprint = await assertFreshDemoBundle(page, targetRoot);
+} catch (error) {
+  await browser.close();
+  throw error;
+}
+
+const rows = [];
+try {
+  for (let iteration = 0; iteration < warmups + samples; iteration++) {
+    const measuredSample = iteration - warmups;
+    const row = await page.evaluate(async ({ fixture, sample, cardContract }) => {
+      const frame = () => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+      const until = async (predicate, timeout = 10000) => {
+        const started = performance.now();
+        while (!predicate()) {
+          if (performance.now() - started > timeout) throw new Error('large-house benchmark timed out');
+          await new Promise((done) => setTimeout(done, 10));
+        }
+      };
+      const startLongTaskWindow = () => {
+        const entries = [];
+        if (!PerformanceObserver.supportedEntryTypes?.includes('longtask')) {
+          return { stop: async () => ({ supported: false, count: 0, maxMs: 0, totalMs: 0 }) };
+        }
+        const observer = new PerformanceObserver((list) => entries.push(...list.getEntries()));
+        observer.observe({ type: 'longtask', buffered: false });
+        return {
+          stop: async () => {
+            await new Promise((done) => setTimeout(done, 0));
+            entries.push(...observer.takeRecords());
+            observer.disconnect();
+            const durations = entries.map((entry) => entry.duration);
+            return {
+              supported: true,
+              count: durations.length,
+              maxMs: Number((durations.length ? Math.max(...durations) : 0).toFixed(2)),
+              totalMs: Number(durations.reduce((sum, value) => sum + value, 0).toFixed(2)),
+            };
+          },
+        };
+      };
+      const duration = async (action) => {
+        const longTasks = startLongTaskWindow();
+        const started = performance.now();
+        await action();
+        await frame();
+        return {
+          ms: Number((performance.now() - started).toFixed(2)),
+          longTasks: await longTasks.stop(),
+        };
+      };
+      const forceGc = async () => {
+        if (typeof globalThis.gc !== 'function') return false;
+        globalThis.gc();
+        await frame();
+        globalThis.gc();
+        await frame();
+        return true;
+      };
+      const cacheSnapshot = (card) => ({
+        cleanFloor: card._cleanFloorCache?.size ?? 0,
+        glowClip: card._glowClipCache?.size ?? 0,
+        wallUnion: card._wallUnionCache ? 1 : 0,
+        openingTunnel: card._openingTunnelCache ? 1 : 0,
+        openingWallIndex: card._openingWallIndexCache ? 1 : 0,
+      });
+
+      window.__card?.remove?.();
+      localStorage.clear();
+      const host = document.getElementById('host');
+      const card = document.createElement('houseplan-card');
+      card.setConfig({
+        type: 'custom:houseplan-card', title: `Performance baseline ${sample}`, icon_size: 3.4,
+      });
+      const connection = {
+        subscribeEvents: async () => () => undefined,
+        subscribeMessage: async () => () => undefined,
+      };
+      const hassFor = (states) => ({
+        language: 'en', locale: { language: 'en' },
+        user: { id: 'perf', name: 'Performance fixture', is_admin: true },
+        devices: fixture.devices, entities: fixture.entities, areas: fixture.areas, states,
+        floors: {
+          one: { floor_id: 'one', name: 'One', level: 0 },
+          two: { floor_id: 'two', name: 'Two', level: 1 },
+          three: { floor_id: 'three', name: 'Three', level: 2 },
+        },
+        callWS: async (message) => {
+          if (message.type === 'houseplan/config/get')
+            return { config: structuredClone(fixture.config), rev: 1, can_write: true };
+          if (message.type === 'houseplan/layout/get')
+            return { layout: structuredClone(fixture.layout), rev: 1 };
+          if (message.type === 'config/device_registry/list') return Object.values(fixture.devices);
+          if (message.type === 'config/entity_registry/list') return Object.values(fixture.entities);
+          if (message.type === 'config_entries/get')
+            return [{ entry_id: 'perf_entry', domain: 'houseplan_perf', title: 'Synthetic performance fixture' }];
+          if (message.type === 'manifest/list') return [{ domain: 'houseplan_perf', name: 'House Plan Performance' }];
+          return { ok: true };
+        },
+        callService: async () => undefined,
+        connection,
+        localize: () => null,
+        formatEntityState: (state) => state.state,
+        config: { unit_system: { length: 'km' } },
+      });
+
+      const loadLongTasks = startLongTaskWindow();
+      const loadStarted = performance.now();
+      host.replaceChildren(card);
+      card.hass = hassFor(fixture.states);
+      window.__hpAssertCardContract(card, cardContract);
+      await until(() => card._loadOk && card._model?.length === fixture.counts.floors);
+      await card.updateComplete;
+      await frame();
+      const modelReadyMs = Number((performance.now() - loadStarted).toFixed(2));
+      await until(() => card._booting === false);
+      await frame();
+      const firstStableRenderMs = Number((performance.now() - loadStarted).toFixed(2));
+      const loadLongTaskResult = await loadLongTasks.stop();
+      const spaceSwitch = await duration(async () => {
+        card._pickSpace('perf-floor-2');
+        await card.updateComplete;
+      });
+
+      const firstEntity = Object.keys(fixture.states)[0];
+      const nextStates = {
+        ...fixture.states,
+        [firstEntity]: { ...fixture.states[firstEntity], state: fixture.states[firstEntity].state === 'on' ? 'off' : 'on' },
+      };
+      const stateUpdate = await duration(async () => {
+        card.hass = hassFor(nextStates);
+        await card.updateComplete;
+      });
+
+      const resizePreview = await duration(async () => {
+        card._setMode('plan');
+        card._tool = 'resize';
+        await card.updateComplete;
+        const room = card._rszRooms()[0];
+        const pointerId = 777;
+        const quietEvent = {
+          pointerId,
+          stopPropagation: () => undefined,
+          preventDefault: () => undefined,
+          target: null,
+        };
+        card._rszEdgeDown(quietEvent, room.id, 1);
+        const plan = card._rszDrag?.plan;
+        if (!plan) throw new Error('large-house resize plan was not created');
+        const target = [
+          plan.a[0] + plan.n[0] * card._gridPitch,
+          plan.a[1] + plan.n[1] * card._gridPitch,
+        ];
+        const stage = card.renderRoot.querySelector('.stage');
+        const rect = stage.getBoundingClientRect();
+        const view = card._viewOr(card._baseVb());
+        card._rszMove({
+          ...quietEvent,
+          clientX: rect.left + ((target[0] - view.x) / view.w) * rect.width,
+          clientY: rect.top + ((target[1] - view.y) / view.h) * rect.height,
+        });
+        await card.updateComplete;
+        card._rszCancelDrag();
+        card._setMode('view');
+        await card.updateComplete;
+      });
+
+      const stage = card.renderRoot.querySelector('.stage');
+      const rect = stage.getBoundingClientRect();
+      const panZoom = await duration(async () => {
+        stage.dispatchEvent(new WheelEvent('wheel', {
+          deltaY: -120, clientX: rect.left + rect.width / 2, clientY: rect.top + rect.height / 2,
+          bubbles: true, cancelable: true,
+        }));
+        await card.updateComplete;
+      });
+
+      const settingsDialog = await duration(async () => {
+        card._openSettingsDialog();
+        await card.updateComplete;
+      });
+      card._settingsDialog = null;
+      await card.updateComplete;
+
+      const switchCycle = await duration(async () => {
+        for (let index = 0; index < 12; index++) {
+          card._pickSpace(`perf-floor-${(index % fixture.counts.floors) + 1}`);
+          await card.updateComplete;
+          // A user cannot produce twelve tab clicks in one JavaScript task.
+          // Yield between interactions so Long Task entries describe one
+          // switch, while switchCycleMs still measures the complete cycle.
+          await new Promise((done) => setTimeout(done, 0));
+        }
+      });
+
+      await forceGc();
+      const cacheBefore = cacheSnapshot(card);
+      const heapBefore = performance.memory?.usedJSHeapSize ?? null;
+      for (let round = 0; round < 4; round++) {
+        for (let index = 0; index < 12; index++) {
+          card._pickSpace(`perf-floor-${(index % fixture.counts.floors) + 1}`);
+          await card.updateComplete;
+          await new Promise((done) => setTimeout(done, 0));
+        }
+        await forceGc();
+      }
+      const cacheEntries = cacheSnapshot(card);
+      const heapAfter = performance.memory?.usedJSHeapSize ?? null;
+      const cacheGrowth = Object.fromEntries(
+        Object.keys(cacheEntries).map((key) => [key, cacheEntries[key] - cacheBefore[key]]),
+      );
+
+      const result = {
+        sample,
+        modelReadyMs,
+        firstStableRenderMs,
+        spaceSwitchMs: spaceSwitch.ms,
+        stateUpdateMs: stateUpdate.ms,
+        resizePreviewMs: resizePreview.ms,
+        panZoomMs: panZoom.ms,
+        settingsDialogMs: settingsDialog.ms,
+        switchCycleMs: switchCycle.ms,
+        longTasks: {
+          load: loadLongTaskResult,
+          spaceSwitch: spaceSwitch.longTasks,
+          stateUpdate: stateUpdate.longTasks,
+          resizePreview: resizePreview.longTasks,
+          panZoom: panZoom.longTasks,
+          settingsDialog: settingsDialog.longTasks,
+          switchCycle: switchCycle.longTasks,
+        },
+        cacheEntries,
+        cacheGrowth,
+        heapGrowthBytes: heapBefore == null || heapAfter == null ? null : heapAfter - heapBefore,
+        preciseGc: typeof globalThis.gc === 'function',
+        renderedDevices: card._devices?.length ?? 0,
+      };
+      card.remove();
+      await frame();
+      return result;
+    }, { fixture, sample: measuredSample, cardContract: LARGE_HOUSE_CARD_CONTRACT });
+    if (measuredSample >= 0) rows.push(row);
+  }
+} finally {
+  await browser.close();
+}
+
+const metricNames = [
+  'modelReadyMs', 'firstStableRenderMs', 'spaceSwitchMs', 'stateUpdateMs',
+  'resizePreviewMs', 'panZoomMs', 'settingsDialogMs', 'switchCycleMs',
+];
+const report = {
+  schema: 2,
+  profile: 'large-house-v1',
+  generatedAt: new Date().toISOString(),
+  buildFingerprint,
+  runtime: {
+    node: process.version,
+    chromium,
+    platform: process.platform,
+    arch: process.arch,
+    viewport,
+    deviceScaleFactor: 1,
+    reducedMotion: true,
+  },
+  fixture: LARGE_HOUSE_COUNTS,
+  samples,
+  warmups,
+  summary: summarizeTimings(rows, metricNames),
+  longTasks: summarizeLongTasks(rows),
+  rows,
+  note: 'Compare with a base-SHA report captured by the same runner and evaluate demo/performance/budgets.json.',
+};
+
+const text = `${JSON.stringify(report, null, 2)}\n`;
+if (output) {
+  mkdirSync(dirname(output), { recursive: true });
+  writeFileSync(output, text, 'utf8');
+  console.log(output);
+} else {
+  process.stdout.write(text);
+}

demo/bundle-freshness.mjs

@@ -0,0 +1,15 @@
+import { sourceFingerprint } from '../scripts/source-fingerprint.mjs';
+
+/** Refuse measurements/screenshots made by a committed bundle from old source. */
+export async function assertFreshDemoBundle(page, root = process.cwd()) {
+  const expected = sourceFingerprint(root);
+  const loaded = await page.evaluate(() => globalThis.__HOUSEPLAN_BUILD_FINGERPRINT__ ?? null);
+  if (loaded !== expected) {
+    throw new Error(
+      'demo/srv/assets/houseplan-card.js is stale. Run npm run build and copy '
+      + 'dist/houseplan-card.js to demo/srv/assets/houseplan-card.js first. '
+      + `Expected ${expected}, loaded ${loaded || 'no fingerprint'}.`,
+    );
+  }
+  return expected;
+}

demo/fixtures/large-house.mjs

@@ -0,0 +1,231 @@
+/**
+ * Deterministic, fictional high-load fixture shared by performance and future
+ * visual-regression tooling. Nothing here depends on a real HA installation.
+ */
+
+const FLOOR_COUNT = 3;
+const ROOMS_PER_FLOOR = 20;
+const DEVICE_COUNT = 200;
+const OPENING_COUNT = 100;
+const PARTITION_COUNT = 60;
+const COLUMN_COUNT = 40;
+const DECOR_COUNT = 500;
+
+const round = (value) => Number(value.toFixed(6));
+
+const roomGrid = (floor) => {
+  const rooms = [];
+  const left = 0.04;
+  const top = 0.04;
+  const width = 0.92 / 5;
+  const height = 0.92 / 4;
+  for (let row = 0; row < 4; row++) {
+    for (let column = 0; column < 5; column++) {
+      const index = row * 5 + column;
+      const x1 = round(left + column * width);
+      const y1 = round(top + row * height);
+      const x2 = round(x1 + width);
+      const y2 = round(y1 + height);
+      rooms.push({
+        id: `perf-room-${floor}-${index}`,
+        name: `Room ${floor + 1}.${index + 1}`,
+        area: `perf_area_${floor}_${index}`,
+        poly: [[x1, y1], [x2, y1], [x2, y2], [x1, y2]],
+      });
+    }
+  }
+  return rooms;
+};
+
+const wallSegments = (rooms) => {
+  const unique = new Map();
+  for (const room of rooms) {
+    room.poly.forEach((a, index) => {
+      const b = room.poly[(index + 1) % room.poly.length];
+      const forward = `${a.join(',')}/${b.join(',')}`;
+      const reverse = `${b.join(',')}/${a.join(',')}`;
+      if (!unique.has(reverse)) unique.set(forward, { a, b });
+    });
+  }
+  return [...unique.values()];
+};
+
+const makeOpenings = (floor, walls, count) => walls.slice(0, count).map((wall, index) => {
+  const horizontal = Math.abs(wall.b[0] - wall.a[0]) >= Math.abs(wall.b[1] - wall.a[1]);
+  return {
+    id: `perf-opening-${floor}-${index}`,
+    type: index % 7 === 0 ? 'window' : index % 11 === 0 ? 'gate' : 'door',
+    x: round((wall.a[0] + wall.b[0]) / 2),
+    y: round((wall.a[1] + wall.b[1]) / 2),
+    angle: horizontal ? 0 : 90,
+    length: horizontal ? 0.045 : 0.055,
+  };
+});
+
+const makePartitions = (floor, rooms, count) => Array.from({ length: count }, (_, index) => {
+  const room = rooms[index % rooms.length];
+  const [a, , c] = room.poly;
+  const y = round(a[1] + (c[1] - a[1]) * (0.35 + (index % 3) * 0.12));
+  return {
+    id: `perf-partition-${floor}-${index}`,
+    a: [round(a[0] + 0.035), y],
+    b: [round(c[0] - 0.035), y],
+    cm: 10 + (index % 3) * 5,
+  };
+});
+
+const makeColumns = (floor, rooms, count) => Array.from({ length: count }, (_, index) => {
+  const room = rooms[(index * 3) % rooms.length];
+  const [a, , c] = room.poly;
+  return {
+    id: `perf-column-${floor}-${index}`,
+    shape: index % 3 === 0 ? 'circle' : 'square',
+    center: [
+      round(a[0] + (c[0] - a[0]) * (0.28 + (index % 2) * 0.44)),
+      round(a[1] + (c[1] - a[1]) * (0.28 + ((index >> 1) % 2) * 0.44)),
+    ],
+    cm: 25 + (index % 4) * 5,
+    ...(index % 3 === 0 ? {} : { angle: (index % 6) * 15 }),
+  };
+});
+
+const makeDecor = (floor, count) => Array.from({ length: count }, (_, index) => {
+  const column = index % 25;
+  const row = Math.floor(index / 25);
+  const x = round(0.02 + column * 0.039);
+  const y = round(0.018 + (row % 20) * 0.048);
+  if (index % 10 === 0) {
+    return {
+      id: `perf-decor-${floor}-${index}`,
+      kind: 'text', x, y, text: `F${floor + 1}-${index}`, size_cm: 14,
+      color: '#59636e', opacity: 0.75,
+    };
+  }
+  if (index % 3 === 0) {
+    return {
+      id: `perf-decor-${floor}-${index}`,
+      kind: 'rect', x, y, w: 0.022, h: 0.018, angle: (index % 12) * 5,
+      color: '#687681', opacity: 0.55, width_cm: 1.5,
+      fill: index % 2 === 0, fill_color: '#75838e', fill_opacity: 0.12,
+    };
+  }
+  return {
+    id: `perf-decor-${floor}-${index}`,
+    kind: 'line', x1: x, y1: y, x2: round(x + 0.025), y2: round(y + (index % 2 ? 0.012 : 0)),
+    color: '#687681', opacity: 0.6, width_cm: 1.2,
+    ...(index % 9 === 0 ? { line_style: 'dashed' } : {}),
+  };
+});
+
+const entityKinds = [
+  ['light', 'on'],
+  ['switch', 'off'],
+  ['sensor', '21.5'],
+  ['binary_sensor', 'off'],
+  ['climate', 'heat'],
+  ['media_player', 'playing'],
+  ['cover', 'closed'],
+  ['fan', 'on'],
+  ['lock', 'locked'],
+  ['vacuum', 'docked'],
+];
+
+const makeRuntime = (spaces) => {
+  const devices = {};
+  const entities = {};
+  const states = {};
+  const areas = {};
+  const layout = {};
+  const roomRefs = spaces.flatMap((space) => space.rooms.map((room) => ({ space, room })));
+  for (const { room } of roomRefs) areas[room.area] = { area_id: room.area, name: room.name };
+  for (let index = 0; index < DEVICE_COUNT; index++) {
+    const { space, room } = roomRefs[index % roomRefs.length];
+    const [domain, baseState] = entityKinds[index % entityKinds.length];
+    const deviceId = `perf-device-${index}`;
+    const entityId = `${domain}.perf_${index}`;
+    devices[deviceId] = {
+      id: deviceId,
+      name: `Synthetic ${domain} ${index + 1}`,
+      model: `PERF-${String(index + 1).padStart(3, '0')}`,
+      area_id: room.area,
+      identifiers: [['houseplan_perf', deviceId]],
+      config_entries: ['perf_entry'],
+      entry_type: null,
+      via_device_id: null,
+      disabled_by: null,
+    };
+    entities[entityId] = {
+      entity_id: entityId,
+      device_id: deviceId,
+      platform: 'houseplan_perf',
+      config_entry_id: 'perf_entry',
+      disabled_by: null,
+    };
+    const attributes = { friendly_name: devices[deviceId].name };
+    if (domain === 'sensor') Object.assign(attributes, {
+      device_class: 'temperature', unit_of_measurement: '°C', state_class: 'measurement',
+    });
+    if (domain === 'binary_sensor') attributes.device_class = index % 2 ? 'motion' : 'occupancy';
+    if (domain === 'climate') Object.assign(attributes, { current_temperature: 21.5, temperature: 22 });
+    states[entityId] = { entity_id: entityId, state: index % 4 === 0 && domain === 'light' ? 'off' : baseState, attributes };
+    const [a, , c] = room.poly;
+    layout[deviceId] = {
+      s: space.id,
+      x: round(a[0] + (c[0] - a[0]) * (0.2 + (index % 4) * 0.2)),
+      y: round(a[1] + (c[1] - a[1]) * (0.28 + ((index >> 2) % 3) * 0.22)),
+    };
+  }
+  return { devices, entities, states, areas, layout };
+};
+
+export const LARGE_HOUSE_COUNTS = Object.freeze({
+  floors: FLOOR_COUNT,
+  rooms: FLOOR_COUNT * ROOMS_PER_FLOOR,
+  devices: DEVICE_COUNT,
+  openings: OPENING_COUNT,
+  partitions: PARTITION_COUNT,
+  columns: COLUMN_COUNT,
+  decor: DECOR_COUNT,
+});
+
+export const makeLargeHouseFixture = () => {
+  let openingsLeft = OPENING_COUNT;
+  let partitionsLeft = PARTITION_COUNT;
+  let columnsLeft = COLUMN_COUNT;
+  let decorLeft = DECOR_COUNT;
+  const spaces = Array.from({ length: FLOOR_COUNT }, (_, floor) => {
+    const rooms = roomGrid(floor);
+    const segments = wallSegments(rooms);
+    const floorsRemaining = FLOOR_COUNT - floor;
+    const openingCount = Math.ceil(openingsLeft / floorsRemaining);
+    const partitionCount = Math.ceil(partitionsLeft / floorsRemaining);
+    const columnCount = Math.ceil(columnsLeft / floorsRemaining);
+    const decorCount = Math.ceil(decorLeft / floorsRemaining);
+    openingsLeft -= openingCount;
+    partitionsLeft -= partitionCount;
+    columnsLeft -= columnCount;
+    decorLeft -= decorCount;
+    return {
+      id: `perf-floor-${floor + 1}`,
+      title: `Performance floor ${floor + 1}`,
+      plan_url: null,
+      view_box: [0, 0, 1, 1],
+      cell_cm: 5,
+      settings: { fill_mode: 'glow', show_borders: true, show_names: true },
+      rooms,
+      walls: segments.map((wall, index) => ({
+        key: `perf-wall-${floor}-${index}`, cm: 15, a: wall.a, b: wall.b,
+      })),
+      openings: makeOpenings(floor, segments, openingCount),
+      partitions: makePartitions(floor, rooms, partitionCount),
+      wall_columns: makeColumns(floor, rooms, columnCount),
+      decor: makeDecor(floor, decorCount),
+    };
+  });
+  const runtime = makeRuntime(spaces);
+  return {
+    config: { spaces, markers: [], settings: { glow_radius_cm: 300 } },
+    ...runtime,
+    counts: LARGE_HOUSE_COUNTS,
+  };
+};

demo/fixtures/visual-matrix.mjs

@@ -0,0 +1,187 @@
+/** Deterministic fictional scenes for HP-QA-01 golden-image coverage. */
+
+const round = (value) => Number(value.toFixed(6));
+
+const uniqueEdges = (rooms) => {
+  const edges = new Map();
+  for (const room of rooms) {
+    room.poly.forEach((a, index) => {
+      const b = room.poly[(index + 1) % room.poly.length];
+      const forward = `${a.join(',')}/${b.join(',')}`;
+      const reverse = `${b.join(',')}/${a.join(',')}`;
+      if (!edges.has(reverse) && !edges.has(forward)) edges.set(forward, { a, b });
+    });
+  }
+  return [...edges.values()];
+};
+
+const wallsFor = (prefix, rooms, thickness) => uniqueEdges(rooms).map((edge, index) => ({
+  key: `${prefix}-wall-${index}`,
+  a: edge.a,
+  b: edge.b,
+  cm: typeof thickness === 'function' ? thickness(edge, index) : thickness,
+}));
+
+const geometryRooms = [
+  { id: 'geo-nw', name: 'NW', area: 'golden_geo_nw', poly: [[0.06, 0.08], [0.48, 0.08], [0.48, 0.48], [0.06, 0.48]] },
+  { id: 'geo-ne', name: 'NE', area: 'golden_geo_ne', poly: [[0.48, 0.08], [0.94, 0.08], [0.94, 0.48], [0.48, 0.48]] },
+  { id: 'geo-sw', name: 'SW', area: 'golden_geo_sw', poly: [[0.06, 0.48], [0.48, 0.48], [0.48, 0.92], [0.06, 0.92]] },
+  { id: 'geo-se', name: 'SE', area: 'golden_geo_se', poly: [[0.48, 0.48], [0.94, 0.48], [0.94, 0.92], [0.48, 0.92]] },
+  { id: 'geo-nested', name: 'Nested', area: 'golden_geo_nested',
+    poly: [[0.72, 0.14], [0.84, 0.26], [0.72, 0.38], [0.60, 0.26]] },
+];
+
+const lightingRooms = [
+  { id: 'light-left', name: 'Light source room', area: 'golden_light_left',
+    poly: [[0.07, 0.10], [0.50, 0.10], [0.50, 0.88], [0.07, 0.88]] },
+  { id: 'light-right', name: 'Receiving room', area: 'golden_light_right',
+    poly: [[0.50, 0.10], [0.93, 0.10], [0.93, 0.88], [0.50, 0.88]] },
+];
+
+const geometrySpace = {
+  id: 'golden-geometry',
+  title: 'Geometry matrix',
+  plan_url: null,
+  view_box: [0, 0, 1, 1],
+  cell_cm: 5,
+  settings: {
+    fill_mode: 'none', show_borders: true, show_names: true,
+    room_color: '#2d8fce', room_opacity: 0.16,
+  },
+  rooms: geometryRooms,
+  walls: wallsFor('geo', geometryRooms, (edge, index) => {
+    const vertical = Math.abs(edge.a[0] - edge.b[0]) < 1e-9;
+    if (vertical && Math.abs(edge.a[0] - 0.48) < 1e-9) return 25;
+    return index % 4 === 0 ? 10 : 15;
+  }),
+  open_spans: [{ a: [0.48, 0.15], b: [0.48, 0.27] }],
+  openings: [
+    { id: 'geo-window', type: 'window', x: 0.26, y: 0.08, angle: 0, length: 0.12 },
+    { id: 'geo-door', type: 'door', x: 0.48, y: 0.37, angle: 90, length: 0.12 },
+    { id: 'geo-gate', type: 'gate', x: 0.72, y: 0.92, angle: 0, length: 0.2 },
+    { id: 'geo-diagonal-window', type: 'window', x: 0.78, y: 0.20, angle: 45, length: 0.08 },
+  ],
+  partitions: [
+    { id: 'geo-partition-h', a: [0.14, 0.68], b: [0.40, 0.68], cm: 12 },
+    { id: 'geo-partition-v', a: [0.75, 0.56], b: [0.75, 0.82], cm: 20 },
+  ],
+  wall_columns: [
+    { id: 'geo-column-square', shape: 'square', center: [0.63, 0.67], cm: 35, angle: 30 },
+    { id: 'geo-column-circle', shape: 'circle', center: [0.86, 0.72], cm: 40 },
+  ],
+  decor: [
+    { id: 'geo-axis-h', kind: 'line', x1: 0.04, y1: 0.5, x2: 0.96, y2: 0.5,
+      color: '#5d6a73', opacity: 0.35, width_cm: 0.8, line_style: 'dashed' },
+  ],
+};
+
+const lightingSpace = {
+  id: 'golden-lighting',
+  title: 'Lighting matrix',
+  plan_url: null,
+  view_box: [0, 0, 1, 1],
+  cell_cm: 5,
+  settings: {
+    fill_mode: 'none', glow_enabled: true, show_borders: true, show_names: true,
+    north_deg: 0, sun_rays: true, bg_mode: 'static',
+  },
+  rooms: lightingRooms,
+  walls: wallsFor('light', lightingRooms, (edge) => (
+    Math.abs(edge.a[0] - 0.5) < 1e-9 && Math.abs(edge.b[0] - 0.5) < 1e-9 ? 25 : 15
+  )),
+  openings: [
+    { id: 'light-window', type: 'window', x: 0.27, y: 0.10, angle: 0, length: 0.14 },
+    { id: 'light-door', type: 'door', x: 0.50, y: 0.54, angle: 90, length: 0.15 },
+    { id: 'light-gate', type: 'gate', x: 0.74, y: 0.88, angle: 0, length: 0.22 },
+  ],
+  partitions: [
+    { id: 'light-partition', a: [0.70, 0.22], b: [0.70, 0.70], cm: 18 },
+  ],
+  wall_columns: [
+    { id: 'light-column', shape: 'circle', center: [0.38, 0.64], cm: 45 },
+  ],
+  decor: [],
+};
+
+const runtime = () => {
+  const devices = {};
+  const entities = {};
+  const states = {
+    'sun.sun': {
+      entity_id: 'sun.sun', state: 'above_horizon',
+      attributes: { azimuth: 180, elevation: 24 },
+    },
+  };
+  entities['sun.sun'] = {
+    entity_id: 'sun.sun', device_id: null, platform: 'sun', disabled_by: null,
+  };
+  const layout = {};
+  const areas = Object.fromEntries(
+    [...geometryRooms, ...lightingRooms].map((room) => [room.area, { area_id: room.area, name: room.name }]),
+  );
+  const add = (id, domain, area, x, y, state, attributes = {}) => {
+    const entityId = `${domain}.${id.replaceAll('-', '_')}`;
+    devices[id] = {
+      id, name: `Golden ${id}`, model: `GOLDEN-${id.toUpperCase()}`, area_id: area,
+      identifiers: [['houseplan_golden', id]], config_entries: ['golden_entry'],
+      entry_type: null, via_device_id: null, disabled_by: null,
+    };
+    entities[entityId] = {
+      entity_id: entityId, device_id: id, platform: 'houseplan_golden',
+      config_entry_id: 'golden_entry', disabled_by: null,
+    };
+    states[entityId] = { entity_id: entityId, state, attributes: { friendly_name: devices[id].name, ...attributes } };
+    layout[id] = { s: 'golden-lighting', x: round(x), y: round(y) };
+  };
+  add('golden-light-one', 'light', 'golden_light_left', 0.20, 0.34, 'on', { rgb_color: [255, 196, 112] });
+  add('golden-light-two', 'light', 'golden_light_left', 0.35, 0.72, 'on', { color_temp_kelvin: 2700 });
+  add('golden-light-three', 'light', 'golden_light_right', 0.82, 0.30, 'off');
+  add('golden-presence', 'binary_sensor', 'golden_light_right', 0.82, 0.62, 'on', { device_class: 'occupancy' });
+  add('golden-climate', 'climate', 'golden_light_right', 0.60, 0.28, 'heat', {
+    current_temperature: 22.4, temperature: 23, hvac_action: 'heating',
+  });
+  add('golden-left-temperature', 'sensor', 'golden_light_left', 0.19, 0.54, '17', {
+    device_class: 'temperature', unit_of_measurement: '°C',
+  });
+  add('golden-right-temperature', 'sensor', 'golden_light_right', 0.81, 0.48, '29', {
+    device_class: 'temperature', unit_of_measurement: '°C',
+  });
+  add('golden-left-linkquality', 'sensor', 'golden_light_left', 0.34, 0.54, '35', {
+    unit_of_measurement: 'lqi',
+  });
+  add('golden-right-linkquality', 'sensor', 'golden_light_right', 0.66, 0.70, '190', {
+    unit_of_measurement: 'lqi',
+  });
+  return { devices, entities, states, layout, areas };
+};
+
+export const VISUAL_MATRIX_COUNTS = Object.freeze({
+  spaces: 2,
+  rooms: geometryRooms.length + lightingRooms.length,
+  openings: geometrySpace.openings.length + lightingSpace.openings.length,
+  partitions: geometrySpace.partitions.length + lightingSpace.partitions.length,
+  columns: geometrySpace.wall_columns.length + lightingSpace.wall_columns.length,
+});
+
+export const makeVisualMatrixFixture = () => ({
+  config: {
+    spaces: [structuredClone(geometrySpace), structuredClone(lightingSpace)],
+    // A persisted marker is part of the fixture contract for scenarios that
+    // override per-source Glow controls. The device/layout alone are not a
+    // saved marker configuration and must not be silently treated as one.
+    markers: [{ id: 'golden-light-two', binding: 'device:golden-light-two' }],
+    settings: {
+      glow_radius_cm: 360,
+      north_deg: 0,
+      sun_rays: true,
+      bg_mode: 'static',
+      fill_colors: {
+        glow_base: { c: '#1b2530', a: 0.78 },
+        glow_light: { c: '#ffd27b', a: 0.70 },
+        wall_fill: { c: '#d7d9dc', a: 1 },
+      },
+    },
+  },
+  ...runtime(),
+  counts: VISUAL_MATRIX_COUNTS,
+});

demo/golden/README.md

@@ -0,0 +1,61 @@
+# HP-QA-01 golden images
+
+This layer catches visual regressions that DOM smokes cannot: wall seams and
+end caps, thick opening tunnels, Glow/sun clipping, hover contours, editor
+chrome, the open contextual tray at wide/medium/narrow widths in English and
+Russian (selection, tool options, group and palette), long dialog
+titles/footers, mobile clipping, themes and zoom/remount. The desktop and
+mobile device-dialog scenarios use a real light and make the complete
+source-role, Glow colour, brightness and radius controls visible; capturing
+only the top of that section fails the scenario before comparison.
+The Glow matrix also keeps one deliberately opaque custom-fill scene with a
+single source and two doorways: it makes hard spill wedges and fully unlit
+radial spokes visible instead of hiding them under a translucent room fill.
+
+## Safety contract
+
+- A build fingerprint embedded by Rollup must match `src/`, Rollup/TypeScript
+  configuration and locked package inputs; stale committed
+  demo bundles fail before the first screenshot.
+- Chromium, viewport, locale, timezone, colour profile, font rendering,
+  animations and caret are controlled by the runner.
+- `capture` writes only to ignored `artifacts/golden/`; it never changes a
+  baseline and never claims a missing baseline passed. Any scenario runtime
+  error makes capture fail, including the initial no-baseline CI run.
+- `verify` requires every image plus a matching matrix manifest and fails on
+  missing/different/error scenarios, browser mismatch or a baseline whose hash
+  no longer matches the reviewed manifest.
+- `accept` requires `--reviewed`, a complete candidate report and current
+  source fingerprint. It validates the whole set before copying anything and
+  is the only command allowed to update baselines.
+
+## Workflow
+
+Build and copy the exact current source first:
+
+```bash
+npm run build
+cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+npm run golden:capture
+```
+
+Review `artifacts/golden/actual/` and, when existing references are present,
+`artifacts/golden/diff/`. If every image is intentional:
+
+```bash
+npm run golden:accept -- --reviewed
+npm run golden:verify
+```
+
+Never accept images merely to make CI green. A matrix/framing change increments
+`GOLDEN_MATRIX_VERSION`; a normal rendering fix does not. The first canonical
+Linux baseline was reviewed and accepted during the v1.60.3-beta.1 gate.
+Future updates must still use the `golden-images` artifact produced by the Linux
+CI job as the review set: desktop font rasterisation can differ from the CI
+environment even with the same pinned Chromium. Pass its unpacked root via
+`--from=...` when accepting it locally.
+
+Scenarios may also declare a semantic pixel region (for example, a receiving
+room that must contain warm light). `golden:capture` and `golden:verify` reject
+the capture before baseline comparison when that visual precondition is empty;
+a reviewed but meaningless PNG therefore cannot become the contract.

demo/golden/accept.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sourceFingerprint } from '../../scripts/source-fingerprint.mjs';
+import { GOLDEN_MATRIX_VERSION, GOLDEN_SCENARIOS } from './matrix.mjs';
+import { GOLDEN_BASELINE_MANIFEST } from './policy.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const reviewed = process.argv.includes('--reviewed');
+const fromArg = process.argv.find((arg) => arg.startsWith('--from='));
+const from = resolve(fromArg ? fromArg.slice('--from='.length) : resolve(ROOT, 'artifacts/golden'));
+if (!reviewed) throw new Error('refusing to replace baselines without explicit --reviewed');
+
+const reportPath = resolve(from, 'golden-report.json');
+if (!existsSync(reportPath)) throw new Error(`candidate report not found: ${reportPath}`);
+const report = JSON.parse(readFileSync(reportPath, 'utf8'));
+if (report.matrixVersion !== GOLDEN_MATRIX_VERSION)
+  throw new Error(`candidate matrix ${report.matrixVersion} != current ${GOLDEN_MATRIX_VERSION}`);
+if (report.buildFingerprint !== sourceFingerprint(ROOT))
+  throw new Error('candidate screenshots were not captured from the current frontend source');
+if (typeof report.chromium !== 'string' || !report.chromium)
+  throw new Error('candidate report does not identify its Chromium build');
+if (!Array.isArray(report.results)) throw new Error('candidate report has no scenario results');
+
+const byId = new Map(report.results.map((result) => [result.id, result]));
+const baselineRoot = resolve(ROOT, 'demo/golden/baselines');
+mkdirSync(baselineRoot, { recursive: true });
+const hashes = {};
+const candidates = [];
+for (const scenario of GOLDEN_SCENARIOS) {
+  const result = byId.get(scenario.id);
+  const candidate = resolve(from, 'actual', `${scenario.id}.png`);
+  if (result?.error || !['missing-baseline', 'passed', 'different'].includes(result?.status))
+    throw new Error(`review candidate has an invalid run status: ${scenario.id} (${result?.status || 'missing'})`);
+  if (!result?.actualSha256 || !existsSync(candidate))
+    throw new Error(`review candidate missing: ${scenario.id}`);
+  const bytes = readFileSync(candidate);
+  const digest = createHash('sha256').update(bytes).digest('hex');
+  if (digest !== result.actualSha256) throw new Error(`candidate changed after capture: ${scenario.id}`);
+  candidates.push({ scenario, candidate });
+  hashes[scenario.id] = digest;
+}
+// Validate the complete set first: a broken report must never leave a half-
+// updated baseline directory behind.
+for (const { scenario, candidate } of candidates)
+  copyFileSync(candidate, resolve(baselineRoot, `${scenario.id}.png`));
+writeFileSync(resolve(baselineRoot, GOLDEN_BASELINE_MANIFEST), `${JSON.stringify({
+  schema: 1,
+  matrixVersion: GOLDEN_MATRIX_VERSION,
+  acceptedAt: new Date().toISOString(),
+  sourceFingerprint: report.buildFingerprint,
+  chromium: report.chromium,
+  scenarios: hashes,
+}, null, 2)}\n`, 'utf8');
+console.log(`Accepted ${GOLDEN_SCENARIOS.length} reviewed golden baselines.`);

demo/golden/baselines/.gitkeep

@@ -0,0 +1 @@
+

demo/golden/baselines/baseline-manifest.json

@@ -0,0 +1,43 @@
+{
+  "schema": 1,
+  "matrixVersion": 8,
+  "acceptedAt": "2026-08-10T23:57:00.140Z",
+  "sourceFingerprint": "0f963f24ce2ba631daf1931ac9ffd44c7326b1bfee5fca1dac9b3a1678c892f7",
+  "chromium": "151.0.7922.34",
+  "scenarios": {
+    "geometry-view-dark-fit": "fbce77f97180cd7d50a997c74d3fa1874ee3be2515a4c09b36dd4e792ebc66df",
+    "geometry-view-light-fit": "a425fa6d77081bb35d2fb81e469962402c6a3c86a8113ff957f28548908d0816",
+    "geometry-plan-editor-dark": "86d64305e4da13436aef14fe96b2c9eb5978d1d32a0bba2318005421a2fda161",
+    "geometry-devices-editor-dark": "93417ab7363ca50e65c9d6f0b876f4d5a6a367a8fabdf42306b244e6511693f1",
+    "geometry-decor-editor-dark": "25d341052e30e7acea13c17897e8bd0f1f08235342b949c02afd3db5b9936c64",
+    "tray-wide-selection-en": "c7350c3661f17f46d22b2c977524fde9fba1ebf9d6e10f021482f0d1caeffa8a",
+    "tray-wide-tool-ru": "5472a302ad7e7b70235089164a5c4558183504519d95280e8ff30883e304cb71",
+    "tray-medium-group-en": "5ab850cb6b91f3bc1020c2257970d8a80d175eb7329c6bfd6de7a94386c930ac",
+    "tray-medium-selection-ru": "805c23560bc340582f9b951e910f39245ab62b6cd980d175c8d9e3b7e1ef1519",
+    "tray-narrow-palette-en": "e8dede0d90ebc32e1e294ba3c39621df918aaf7b3183f71aed9b60014eee51db",
+    "tray-narrow-tool-ru": "8889d58aca90daadf0bedd6a7c08afb2604c086a453f9435f32d29607aa49e42",
+    "geometry-diagonal-45-opening-dark": "fbce77f97180cd7d50a997c74d3fa1874ee3be2515a4c09b36dd4e792ebc66df",
+    "openings-thick-wall-dark": "2a502049283df7a38119a3b62a5fbc4bc6d1d1b5aeb1e21337f2436c78017dce",
+    "openings-hidden-view-dark": "eb6f53c7836ccf086a080640394a63b366abe267ea2740912d98f8f163e187fb",
+    "lighting-glow-sun-dark": "567f609ebc409c8477aa0d369bef3578bcadfa17b450e60f6678442ab9b43810",
+    "lighting-fill-light-axis-split-dark": "0e1a90ec64fc8e07e62e1ba684b0345b2caecadaa0e84dcc2f1bc61080d8bc92",
+    "lighting-fill-temp-axis-split-dark": "653deb8ba50763c91665ca9199eed12f4a05ac63e118d294e78c833db867c661",
+    "lighting-fill-lqi-axis-split-dark": "059d129e6ebc8eb645348ebf41560df559494f23d3b3d0e6c2f0269e03de275d",
+    "lighting-temp-glow-dark": "c2dbd5c35f69587291a16ea24da7d8bcc276800ba7f19c88493132e1acc3b35c",
+    "lighting-temp-glow-light": "6f78a661baa9d914358472d1c077ed61d8aaf88a861058afb9dacf2b28e98786",
+    "lighting-custom-glow-dark": "168364a966a0b4d342d38924e0790c7cf5fe6a34798622b7928425c59bb1e737",
+    "lighting-opaque-glow-two-doorways-dark": "9dbeb9ba58e5c30ee2efd7e200353475ed8cb63a3a99620e1f7c862d5448f956",
+    "lighting-custom-glow-light": "d22374e0639578ed80a5703a4acedb20dc0f6dedb2e3512af24ebdabeb97b8c0",
+    "lighting-temp-glow-no-sources-dark": "e35535052212cd519567236a2227393727729654f5670f9b41918c4b23e9127a",
+    "lighting-temp-glow-room-override-dark": "d92fa0f1e4d5ed66aa11651d5807c7e562a215540a45fc2712691b738c475bc9",
+    "lighting-manual-auto-spill-overlap-dark": "2c44b28c86ae0a77c178d982b4e8c47c70ed0df66ccaba23baf89bdddd311fbd",
+    "hover-over-glow-dark": "c24fbcdd2c79037de540d63413592ae49b360d14bc557135d9cf830bfc959fcc",
+    "hover-nested-room-dark": "dbda5b5f82493b14cc6bf36dfe47758f7d8d4af9c8dab0998ff62fb4456ada1f",
+    "large-house-zoom-040-dark": "0a69ba78fc8476c33c0326df697eb9ee1f19799cc7b7ed84b8c95944d3934f03",
+    "large-house-zoom-250-dark": "c906426f888ff4e306c5c334c6329b387fc5ca368e229f55acc33c202351a1ac",
+    "large-house-warm-remount-dark": "6baf4baed1c735c64dfe1e69d9864ca287ffc0e8452d00e801f0873e98b187ee",
+    "device-dialog-desktop-en": "177bca2af39fd1bf0c9af58dfa6d17effd8ffdf9f96bcf399a0172e9da58f692",
+    "device-dialog-mobile-ru": "5b66639f71623d218f33df8db99f70edc139b9de60ffe291641ccf10665b78cb",
+    "decor-color-popover-mobile-ru": "eab3c5c76b27050dbdbc1627371a16916ea30473934de48842c6ab94a045f9db"
+  }
+}

demo/golden/harness.mjs

@@ -0,0 +1,371 @@
+import { makeLargeHouseFixture } from '../fixtures/large-house.mjs';
+import { makeVisualMatrixFixture } from '../fixtures/visual-matrix.mjs';
+
+const fixtureFor = (name) => name === 'large' ? makeLargeHouseFixture() : makeVisualMatrixFixture();
+
+const themeVars = {
+  dark: {
+    '--primary-color': '#3ea6ff', '--primary-text-color': '#e6e7eb',
+    '--secondary-text-color': '#9aa4ad', '--card-background-color': '#202126',
+    '--ha-card-background': '#202126', '--divider-color': '#3a3d45',
+  },
+  light: {
+    '--primary-color': '#0b73b8', '--primary-text-color': '#202124',
+    '--secondary-text-color': '#5f6368', '--card-background-color': '#ffffff',
+    '--ha-card-background': '#ffffff', '--divider-color': '#d7d9de',
+  },
+};
+
+async function stableEnvironment(page, scenario) {
+  await page.setViewportSize(scenario.viewport);
+  await page.emulateMedia({ reducedMotion: 'reduce', colorScheme: scenario.theme });
+  await page.evaluate(({ variables, theme }) => {
+    let style = document.getElementById('hp-golden-stability');
+    if (!style) {
+      style = document.createElement('style');
+      style.id = 'hp-golden-stability';
+      style.textContent = `
+        *, *::before, *::after {
+          animation: none !important;
+          transition: none !important;
+          caret-color: transparent !important;
+          scroll-behavior: auto !important;
+        }
+        html, body { width: 100%; min-height: 100%; overflow: hidden; }
+        body { background: var(--hp-golden-page-bg) !important;
+          font-family: Arial, sans-serif !important; }
+        #host { width: min(100%, 1120px) !important; margin: 0 auto !important;
+          padding: 8px !important; box-sizing: border-box !important; }
+      `;
+      document.head.appendChild(style);
+    }
+    for (const [name, value] of Object.entries(variables))
+      document.documentElement.style.setProperty(name, value);
+    document.documentElement.style.setProperty(
+      '--hp-golden-page-bg', theme === 'light' ? '#eef1f4' : '#11151b',
+    );
+    document.documentElement.style.colorScheme = theme;
+  }, { variables: themeVars[scenario.theme] || themeVars.dark, theme: scenario.theme });
+}
+
+/** Apply every data-only scenario override before the fixture crosses into the browser. */
+export function prepareGoldenFixture(scenario) {
+  const fixture = fixtureFor(scenario.fixture);
+  const requireSpace = () => {
+    const space = fixture.config.spaces.find((item) => item.id === scenario.space);
+    if (!space) throw new Error(`golden override references missing space: ${scenario.space}`);
+    return space;
+  };
+  if (scenario.deviceName) {
+    if (!scenario.deviceId || !fixture.devices?.[scenario.deviceId])
+      throw new Error(`golden deviceName references missing device: ${scenario.deviceId || '<empty>'}`);
+    fixture.devices[scenario.deviceId].name = scenario.deviceName;
+  }
+  if (scenario.fillMode || typeof scenario.glowEnabled === 'boolean'
+      || typeof scenario.sunRays === 'boolean') {
+    const space = requireSpace();
+    space.settings = {
+      ...(space.settings || {}),
+      ...(scenario.fillMode ? { fill_mode: scenario.fillMode } : {}),
+      ...(typeof scenario.glowEnabled === 'boolean' ? { glow_enabled: scenario.glowEnabled } : {}),
+      ...(typeof scenario.sunRays === 'boolean' ? { sun_rays: scenario.sunRays } : {}),
+      ...(scenario.customFill ? { custom_fill: scenario.customFill } : {}),
+    };
+  }
+  if (scenario.extraOpenings?.length) {
+    const space = requireSpace();
+    const known = new Set((space.openings || []).map((opening) => opening.id));
+    for (const opening of scenario.extraOpenings) {
+      if (!opening?.id || known.has(opening.id))
+        throw new Error(`golden extraOpening has missing/duplicate id: ${opening?.id || '<empty>'}`);
+      if (!['door', 'window', 'gate'].includes(opening.type))
+        throw new Error(`golden extraOpening has unknown type: ${opening.type}`);
+      known.add(opening.id);
+    }
+    space.openings = [...(space.openings || []), ...structuredClone(scenario.extraOpenings)];
+  }
+  if (scenario.hideOpenings) {
+    const space = requireSpace();
+    space.settings = { ...(space.settings || {}), hide_openings: true };
+  }
+  if (scenario.roomGlow) {
+    const space = requireSpace();
+    const unknown = new Set(Object.keys(scenario.roomGlow));
+    for (const room of space.rooms) {
+      if (!(room.id in scenario.roomGlow)) continue;
+      unknown.delete(room.id);
+      room.settings = { ...(room.settings || {}), glow: scenario.roomGlow[room.id] };
+    }
+    if (unknown.size) throw new Error(`golden roomGlow references missing room(s): ${[...unknown].join(', ')}`);
+  }
+  if (scenario.roomCustomFill) {
+    const space = requireSpace();
+    const unknown = new Set(Object.keys(scenario.roomCustomFill));
+    for (const room of space.rooms) {
+      if (!(room.id in scenario.roomCustomFill)) continue;
+      unknown.delete(room.id);
+      room.settings = { ...(room.settings || {}), custom_fill: scenario.roomCustomFill[room.id] };
+    }
+    if (unknown.size)
+      throw new Error(`golden roomCustomFill references missing room(s): ${[...unknown].join(', ')}`);
+  }
+  if (scenario.allLightsOff) {
+    for (const [entityId, state] of Object.entries(fixture.states || {})) {
+      if (!entityId.startsWith('light.')) continue;
+      fixture.states[entityId] = { ...state, state: 'off' };
+    }
+  }
+  if (scenario.stateOverrides) {
+    for (const [entityId, override] of Object.entries(scenario.stateOverrides)) {
+      const current = fixture.states?.[entityId];
+      if (!current) throw new Error(`golden stateOverride references missing entity: ${entityId}`);
+      fixture.states[entityId] = {
+        ...current,
+        ...structuredClone(override),
+        attributes: { ...(current.attributes || {}), ...(override.attributes || {}) },
+      };
+    }
+  }
+  if (scenario.markerOverrides) {
+    const ids = new Set(scenario.markerOverrides.map((marker) => marker.id));
+    const known = new Set((fixture.config.markers || []).map((marker) => marker.id));
+    const missing = [...ids].filter((id) => !known.has(id));
+    if (missing.length) throw new Error(`golden markerOverrides reference missing marker(s): ${missing.join(', ')}`);
+    fixture.config.markers = [
+      ...(fixture.config.markers || []).filter((marker) => !ids.has(marker.id)),
+      ...structuredClone(scenario.markerOverrides),
+    ];
+  }
+  if (scenario.layoutOverrides) {
+    const missing = Object.keys(scenario.layoutOverrides).filter((id) => !(id in (fixture.layout || {})));
+    if (missing.length) throw new Error(`golden layoutOverrides reference missing item(s): ${missing.join(', ')}`);
+    fixture.layout = { ...(fixture.layout || {}), ...structuredClone(scenario.layoutOverrides) };
+  }
+
+  return fixture;
+}
+
+export async function prepareGoldenScenario(page, scenario) {
+  await stableEnvironment(page, scenario);
+  const fixture = prepareGoldenFixture(scenario);
+
+  return page.evaluate(async ({ fixture, scenario }) => {
+    const wait = (ms) => new Promise((done) => setTimeout(done, ms));
+    const frame = () => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    const until = async (predicate, timeout = 10000) => {
+      const started = performance.now();
+      while (!predicate()) {
+        if (performance.now() - started > timeout) throw new Error(`golden scenario timed out: ${scenario.id}`);
+        await wait(15);
+      }
+    };
+    window.__goldenCard?.remove?.();
+    window.__card?.remove?.();
+    localStorage.clear();
+    const host = document.getElementById('host');
+    const cardConfig = {
+      type: 'custom:houseplan-card', title: `Golden ${scenario.id}`, icon_size: 3.4,
+      language: scenario.language || 'en',
+    };
+    const hassFor = () => ({
+      language: scenario.language || 'en', locale: { language: scenario.language || 'en' },
+      user: { id: 'golden', name: 'Golden fixture', is_admin: true },
+      devices: fixture.devices || {}, entities: fixture.entities || {},
+      areas: fixture.areas || {}, states: fixture.states || {},
+      floors: {
+        one: { floor_id: 'one', name: 'One', level: 0 },
+        two: { floor_id: 'two', name: 'Two', level: 1 },
+        three: { floor_id: 'three', name: 'Three', level: 2 },
+      },
+      callWS: async (message) => {
+        if (message.type === 'houseplan/config/get')
+          return { config: structuredClone(fixture.config), rev: 1, can_write: true };
+        if (message.type === 'houseplan/layout/get')
+          return { layout: structuredClone(fixture.layout || {}), rev: 1 };
+        if (message.type === 'config/device_registry/list') return Object.values(fixture.devices || {});
+        if (message.type === 'config/entity_registry/list') return Object.values(fixture.entities || {});
+        if (message.type === 'config_entries/get')
+          return [{ entry_id: 'golden_entry', domain: 'houseplan_golden', title: 'Golden fixture' }];
+        if (message.type === 'manifest/list')
+          return [{ domain: 'houseplan_golden', name: 'House Plan Golden' }];
+        return { ok: true };
+      },
+      callService: async () => undefined,
+      connection: { subscribeEvents: async () => () => undefined, subscribeMessage: async () => () => undefined },
+      localize: () => null,
+      formatEntityState: (state) => state.state,
+      config: { unit_system: { length: 'km' } },
+    });
+    const mount = async () => {
+      const card = document.createElement('houseplan-card');
+      card.setConfig(cardConfig);
+      host.replaceChildren(card);
+      card.hass = hassFor();
+      await until(() => card._loadOk && card._model?.length === fixture.config.spaces.length);
+      await card.updateComplete;
+      const expectedDevices = Object.keys(fixture.devices || {}).length;
+      if (expectedDevices) await until(() => card._devices?.length >= expectedDevices);
+      await until(() => card._booting === false);
+      await frame();
+      return card;
+    };
+
+    let card = await mount();
+    if (scenario.warmRemount) {
+      card.remove();
+      await wait(0);
+      card = await mount();
+    }
+    window.__goldenCard = card;
+    if (scenario.space && card._space !== scenario.space) {
+      card._pickSpace(scenario.space);
+      await card.updateComplete;
+    }
+    if (scenario.mode) {
+      card._setMode(scenario.mode);
+      await card.updateComplete;
+    }
+    if (Number.isFinite(scenario.zoom)) {
+      card._applyView(scenario.zoom, 500, 500);
+      card.requestUpdate();
+      await card.updateComplete;
+    }
+    if (scenario.editorTray) {
+      let expectedKind = '';
+      if (scenario.editorTray === 'plan-selection') {
+        card._physicalSel = { kind: 'partition', id: 'geo-partition-h' };
+        expectedKind = 'selection';
+      } else if (scenario.editorTray === 'plan-tool') {
+        card._physicalSel = null;
+        card._tool = 'draw';
+        expectedKind = 'tool';
+      } else if (scenario.editorTray === 'decor-selection') {
+        card._decorTool = 'select';
+        card._decorSel = 'geo-axis-h';
+        expectedKind = 'selection';
+      } else if (scenario.editorTray === 'decor-tool') {
+        card._decorSel = null;
+        card._decorTool = 'line';
+        expectedKind = 'tool';
+      } else if (scenario.editorTray === 'furniture-palette') {
+        card._decorSel = null;
+        card._furnPalette = null;
+        card._editorSecondary.openPalette();
+        card._decorTool = 'furniture';
+        expectedKind = 'palette';
+      } else if (scenario.editorTray === 'group') {
+        const group = {
+          id: 'golden-group', label: 'Arrange', icon: 'mdi:shape-outline', items: [
+            { id: 'align', label: 'Align', icon: 'mdi:format-align-center', role: 'command', invoke: () => undefined },
+            { id: 'distribute', label: 'Distribute', icon: 'mdi:format-horizontal-align-center', role: 'command', invoke: () => undefined },
+          ],
+        };
+        Object.defineProperty(card, '_editorToolbarGroups', {
+          configurable: true,
+          get: () => [group],
+        });
+        card.requestUpdate();
+        await card.updateComplete;
+        card._editorSecondary.toggleGroup(card._editorToolbarGroups, group.id);
+        expectedKind = 'group';
+      } else {
+        throw new Error(`unknown golden editor tray: ${scenario.editorTray}`);
+      }
+      card.requestUpdate();
+      await card.updateComplete;
+      await frame();
+      const tray = card.renderRoot.querySelector(
+        `.editor-secondary-host.open .editor-secondary.kind-${expectedKind}`,
+      );
+      if (!tray) throw new Error(`golden editor tray did not open: ${scenario.editorTray}`);
+    }
+    if (scenario.hoverRoom) {
+      const room = card._spaceModel().rooms.find((item) => item.id === scenario.hoverRoom);
+      if (!room) throw new Error(`golden hover room missing: ${scenario.hoverRoom}`);
+      card._hoverRoom = { space: card._space, room };
+      card.requestUpdate();
+      await card.updateComplete;
+    }
+    if (scenario.dialog === 'device') {
+      card._setMode('devices');
+      await card.updateComplete;
+      const device = card._devices.find((item) => item.id === scenario.deviceId);
+      if (!device) throw new Error(`golden device missing: ${scenario.deviceId}`);
+      card._openMarkerDialog(device);
+      await card.updateComplete;
+      if (scenario.deviceLightControls) {
+        card._setMarkerLightRole('always');
+        await card.updateComplete;
+        card._setMarkerGlowMode('fixed');
+        await card.updateComplete;
+        const dialog = card.renderRoot.querySelector('hp-dialog');
+        const body = dialog?.querySelector('.body');
+        const groups = [...(dialog?.querySelectorAll('.markerlightgroup') || [])];
+        const roleInputs = groups[0]?.querySelectorAll('input[name="marker-light-role"]');
+        const glowInputs = groups[1]?.querySelectorAll('input[name="marker-glow-mode"]');
+        const color = groups[1]?.querySelector('hp-color-opacity');
+        const brightness = groups[1]?.querySelector('input[type="range"]');
+        const radius = groups[1]?.querySelector('input.tempin[type="number"]');
+        if (!body || groups.length !== 2 || roleInputs?.length !== 3 || glowInputs?.length !== 3
+          || !roleInputs[1]?.checked || !glowInputs[2]?.checked
+          || !color || color.disabled || !brightness || brightness.disabled || !radius || radius.disabled)
+          throw new Error('golden device light-source controls are incomplete');
+        const bodyRect = body.getBoundingClientRect();
+        const roleRect = groups[0].getBoundingClientRect();
+        body.scrollTop += roleRect.top - bodyRect.top - 8;
+        await frame();
+        const visibleBody = body.getBoundingClientRect();
+        const visibleRole = groups[0].getBoundingClientRect();
+        const visibleGlow = groups[1].getBoundingClientRect();
+        if (visibleRole.top < visibleBody.top - 1 || visibleGlow.bottom > visibleBody.bottom + 1)
+          throw new Error('golden viewport does not show the complete device light-source controls');
+      }
+      if (scenario.focusDialogClose) {
+        const dialog = card.renderRoot.querySelector('hp-dialog');
+        await dialog?.updateComplete;
+        dialog?.renderRoot?.querySelector('.close')?.focus();
+      }
+    } else if (scenario.dialog === 'decor-color') {
+      card._setMode('decor');
+      card._decorTool = 'select';
+      await card.updateComplete;
+      const shape = card._decorList.find((item) => item.kind === 'line');
+      if (!shape) throw new Error('golden decor line missing');
+      card._decorShapeDbl(new MouseEvent('dblclick'), shape);
+      await card.updateComplete;
+      const dialog = card.renderRoot.querySelector('hp-dialog');
+      const picker = dialog?.querySelector('hp-color-opacity');
+      await picker?.updateComplete;
+      const trigger = picker?.renderRoot?.querySelector('.trigger');
+      if (!trigger) throw new Error('golden decor color trigger missing');
+      trigger.click();
+      await picker.updateComplete;
+    }
+    await document.fonts?.ready;
+    await frame();
+    return {
+      space: card._space,
+      mode: card._mode,
+      devices: card._devices.length,
+      dialog: !!card.renderRoot.querySelector('hp-dialog'),
+      editorTray: card.renderRoot.querySelector('.editor-secondary-host.open .editor-secondary')
+        ?.className || '',
+    };
+  }, { fixture, scenario });
+}
+
+export async function goldenClip(page, capture) {
+  if (capture === 'page') return null;
+  return page.evaluate(() => {
+    const card = window.__goldenCard;
+    const target = card?.renderRoot?.querySelector('.stage');
+    if (!target) throw new Error('golden stage capture target missing');
+    const rect = target.getBoundingClientRect();
+    const pad = 2;
+    const x = Math.max(0, Math.floor(rect.left - pad));
+    const y = Math.max(0, Math.floor(rect.top - pad));
+    const right = Math.min(window.innerWidth, Math.ceil(rect.right + pad));
+    const bottom = Math.min(window.innerHeight, Math.ceil(rect.bottom + pad));
+    return { x, y, width: Math.max(1, right - x), height: Math.max(1, bottom - y) };
+  });
+}

demo/golden/matrix.mjs

@@ -0,0 +1,113 @@
+/** Data-only HP-QA-01 capture matrix. Bump when framing or scenarios change. */
+export const GOLDEN_MATRIX_VERSION = 8;
+
+const stage = { capture: 'stage', threshold: { maxChannelDelta: 10, maxDiffRatio: 0.0005 } };
+const page = { capture: 'page', threshold: { maxChannelDelta: 10, maxDiffRatio: 0.0008 } };
+
+export const GOLDEN_SCENARIOS = Object.freeze([
+  { id: 'geometry-view-dark-fit', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'geometry-view-light-fit', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    theme: 'light', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'geometry-plan-editor-dark', fixture: 'visual', space: 'golden-geometry', mode: 'plan',
+    theme: 'dark', viewport: { width: 1180, height: 900 }, ...page },
+  { id: 'geometry-devices-editor-dark', fixture: 'visual', space: 'golden-geometry', mode: 'devices',
+    theme: 'dark', viewport: { width: 1180, height: 900 }, ...page },
+  { id: 'geometry-decor-editor-dark', fixture: 'visual', space: 'golden-geometry', mode: 'decor',
+    theme: 'dark', viewport: { width: 1180, height: 900 }, ...page },
+  // HP-UX-11 visual contract: every adaptive width is captured in both
+  // languages while the six materially different tray contents are open.
+  { id: 'tray-wide-selection-en', fixture: 'visual', space: 'golden-geometry', mode: 'plan',
+    editorTray: 'plan-selection', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 900 }, ...page },
+  { id: 'tray-wide-tool-ru', fixture: 'visual', space: 'golden-geometry', mode: 'plan',
+    editorTray: 'plan-tool', language: 'ru', theme: 'dark',
+    viewport: { width: 1180, height: 900 }, ...page },
+  { id: 'tray-medium-group-en', fixture: 'visual', space: 'golden-geometry', mode: 'plan',
+    editorTray: 'group', language: 'en', theme: 'dark',
+    viewport: { width: 760, height: 820 }, ...page },
+  { id: 'tray-medium-selection-ru', fixture: 'visual', space: 'golden-geometry', mode: 'decor',
+    editorTray: 'decor-selection', language: 'ru', theme: 'dark',
+    viewport: { width: 760, height: 820 }, ...page },
+  { id: 'tray-narrow-palette-en', fixture: 'visual', space: 'golden-geometry', mode: 'decor',
+    editorTray: 'furniture-palette', language: 'en', theme: 'dark',
+    viewport: { width: 390, height: 760 }, ...page },
+  { id: 'tray-narrow-tool-ru', fixture: 'visual', space: 'golden-geometry', mode: 'decor',
+    editorTray: 'decor-tool', language: 'ru', theme: 'dark',
+    viewport: { width: 390, height: 760 }, ...page },
+  { id: 'geometry-diagonal-45-opening-dark', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'openings-thick-wall-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'none', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'openings-hidden-view-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'none', glowEnabled: false, hideOpenings: true, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-glow-sun-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-fill-light-axis-split-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'light', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-fill-temp-axis-split-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-fill-lqi-axis-split-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'lqi', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-light', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, theme: 'light', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-custom-glow-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'custom', customFill: { c: '#486a8f', a: 0.42 }, glowEnabled: true,
+    roomCustomFill: { 'light-right': { c: '#8f5f48', a: 0.56 } },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-opaque-glow-two-doorways-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'custom', customFill: { c: '#3f4854', a: 1 }, glowEnabled: true, sunRays: false,
+    allLightsOff: true,
+    stateOverrides: {
+      'light.golden_light_one': { state: 'on', attributes: { rgb_color: [255, 196, 112], brightness: 255 } },
+    },
+    extraOpenings: [
+      { id: 'light-door-second', type: 'door', x: 0.50, y: 0.32, angle: 90, length: 0.13 },
+    ],
+    layoutOverrides: { 'golden-light-one': { s: 'golden-lighting', x: 0.40, y: 0.48 } },
+    // The golden is protection only if the receiving half actually contains
+    // rendered light. A data-only check once let a visually empty baseline pass.
+    warmPixelRegion: { x: 0.5, y: 0, w: 0.5, h: 1, minPixels: 2500, minRedBlueDelta: 25 },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-custom-glow-light', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'custom', customFill: { c: '#486a8f', a: 0.42 }, glowEnabled: true,
+    roomCustomFill: { 'light-right': { c: '#8f5f48', a: 0.56 } },
+    theme: 'light', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-no-sources-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, allLightsOff: true,
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-room-override-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, roomGlow: { 'light-left': true, 'light-right': false },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-manual-auto-spill-overlap-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true,
+    markerOverrides: [{
+      id: 'golden-light-two', binding: 'device:golden-light-two',
+      glow_color: { c: '#3a8fff', bri: 0.35 }, glow_radius_cm: 420,
+    }],
+    layoutOverrides: { 'golden-light-two': { s: 'golden-lighting', x: 0.39, y: 0.57 } },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'hover-over-glow-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    hoverRoom: 'light-right', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'hover-nested-room-dark', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    hoverRoom: 'geo-nested', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'large-house-zoom-040-dark', fixture: 'large', space: 'perf-floor-1', mode: 'view',
+    zoom: 0.4, theme: 'dark', viewport: { width: 1180, height: 900 }, ...stage },
+  { id: 'large-house-zoom-250-dark', fixture: 'large', space: 'perf-floor-1', mode: 'view',
+    zoom: 2.5, theme: 'dark', viewport: { width: 1180, height: 900 }, ...stage },
+  { id: 'large-house-warm-remount-dark', fixture: 'large', space: 'perf-floor-2', mode: 'view',
+    warmRemount: true, theme: 'dark', viewport: { width: 1180, height: 900 }, ...stage },
+  { id: 'device-dialog-desktop-en', fixture: 'visual', space: 'golden-lighting',
+    dialog: 'device', deviceId: 'golden-light-two', deviceLightControls: true,
+    deviceName: 'Living room light controller with an intentionally long title',
+    focusDialogClose: true, language: 'en', theme: 'dark', viewport: { width: 1180, height: 1200 }, ...page },
+  { id: 'device-dialog-mobile-ru', fixture: 'visual', space: 'golden-lighting',
+    dialog: 'device', deviceId: 'golden-light-two', deviceLightControls: true,
+    deviceName: 'Контроллер освещения гостиной с намеренно очень длинным названием',
+    language: 'ru', theme: 'dark', viewport: { width: 390, height: 1000 }, ...page },
+  { id: 'decor-color-popover-mobile-ru', fixture: 'visual', space: 'golden-geometry',
+    dialog: 'decor-color', language: 'ru', theme: 'dark',
+    viewport: { width: 390, height: 760 }, ...page },
+]);

demo/golden/policy.mjs

@@ -0,0 +1,13 @@
+export const GOLDEN_BASELINE_MANIFEST = 'baseline-manifest.json';
+
+export const assertGoldenInvocation = (mode, scenarioFilter = '') => {
+  if (!['capture', 'verify'].includes(mode)) throw new Error(`unknown golden mode: ${mode}`);
+  if (mode === 'verify' && scenarioFilter)
+    throw new Error('golden verify must run the complete matrix; use capture for a diagnostic --scenario run');
+};
+
+export const goldenRunFailed = (mode, manifestValid, results) => {
+  if (results.some((result) => result.status === 'error')) return true;
+  return mode === 'verify'
+    && (!manifestValid || results.some((result) => result.status !== 'passed'));
+};

demo/golden/run.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { launch } from '../serve.mjs';
+import { assertFreshDemoBundle } from '../bundle-freshness.mjs';
+import { goldenClip, prepareGoldenScenario } from './harness.mjs';
+import { GOLDEN_MATRIX_VERSION, GOLDEN_SCENARIOS } from './matrix.mjs';
+import { assertGoldenInvocation, GOLDEN_BASELINE_MANIFEST, goldenRunFailed } from './policy.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const mode = process.argv.find((arg) => arg.startsWith('--mode='))?.slice(7) || 'capture';
+const scenarioFilter = process.argv.find((arg) => arg.startsWith('--scenario='))?.slice(11) || '';
+assertGoldenInvocation(mode, scenarioFilter);
+const scenarios = scenarioFilter
+  ? GOLDEN_SCENARIOS.filter((scenario) => scenario.id === scenarioFilter)
+  : GOLDEN_SCENARIOS;
+if (!scenarios.length) throw new Error(`unknown golden scenario: ${scenarioFilter}`);
+
+const artifactRoot = resolve(ROOT, 'artifacts/golden');
+const actualRoot = resolve(artifactRoot, 'actual');
+const diffRoot = resolve(artifactRoot, 'diff');
+const baselineRoot = resolve(ROOT, 'demo/golden/baselines');
+mkdirSync(actualRoot, { recursive: true });
+mkdirSync(diffRoot, { recursive: true });
+
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest('hex');
+
+async function comparePng(page, actual, baseline, threshold) {
+  return page.evaluate(async ({ actual64, baseline64, threshold }) => {
+    const decode = async (base64) => {
+      const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+      return createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    };
+    const [actualImage, baselineImage] = await Promise.all([decode(actual64), decode(baseline64)]);
+    if (actualImage.width !== baselineImage.width || actualImage.height !== baselineImage.height) {
+      return {
+        dimensionsMatch: false,
+        actualSize: [actualImage.width, actualImage.height],
+        baselineSize: [baselineImage.width, baselineImage.height],
+        differingPixels: null,
+        diffRatio: 1,
+        maxObservedDelta: 255,
+        passed: false,
+        diffPngBase64: null,
+      };
+    }
+    const width = actualImage.width;
+    const height = actualImage.height;
+    const canvas = document.createElement('canvas');
+    const baselineCanvas = document.createElement('canvas');
+    const diffCanvas = document.createElement('canvas');
+    for (const item of [canvas, baselineCanvas, diffCanvas]) {
+      item.width = width;
+      item.height = height;
+    }
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    const baselineContext = baselineCanvas.getContext('2d', { willReadFrequently: true });
+    const diffContext = diffCanvas.getContext('2d');
+    context.drawImage(actualImage, 0, 0);
+    baselineContext.drawImage(baselineImage, 0, 0);
+    const actualData = context.getImageData(0, 0, width, height).data;
+    const baselineData = baselineContext.getImageData(0, 0, width, height).data;
+    const diff = diffContext.createImageData(width, height);
+    let differingPixels = 0;
+    let maxObservedDelta = 0;
+    for (let offset = 0; offset < actualData.length; offset += 4) {
+      let delta = 0;
+      for (let channel = 0; channel < 4; channel++)
+        delta = Math.max(delta, Math.abs(actualData[offset + channel] - baselineData[offset + channel]));
+      maxObservedDelta = Math.max(maxObservedDelta, delta);
+      if (delta > threshold.maxChannelDelta) {
+        differingPixels++;
+        diff.data[offset] = 255;
+        diff.data[offset + 1] = 0;
+        diff.data[offset + 2] = 180;
+        diff.data[offset + 3] = 255;
+      } else {
+        const gray = Math.round((actualData[offset] + actualData[offset + 1] + actualData[offset + 2]) / 9);
+        diff.data[offset] = gray;
+        diff.data[offset + 1] = gray;
+        diff.data[offset + 2] = gray;
+        diff.data[offset + 3] = 90;
+      }
+    }
+    diffContext.putImageData(diff, 0, 0);
+    const diffRatio = differingPixels / (width * height);
+    return {
+      dimensionsMatch: true,
+      actualSize: [width, height],
+      baselineSize: [width, height],
+      differingPixels,
+      diffRatio,
+      maxObservedDelta,
+      passed: diffRatio <= threshold.maxDiffRatio,
+      diffPngBase64: differingPixels
+        ? diffCanvas.toDataURL('image/png').slice('data:image/png;base64,'.length)
+        : null,
+    };
+  }, {
+    actual64: actual.toString('base64'),
+    baseline64: baseline.toString('base64'),
+    threshold,
+  });
+}
+
+/** Assert scenario semantics against the actual capture, not only its data.
+ *  This protects a reviewed-but-empty baseline from becoming the reference. */
+async function countWarmPixels(page, png, region) {
+  return page.evaluate(async ({ png64, region }) => {
+    const bytes = Uint8Array.from(atob(png64), (char) => char.charCodeAt(0));
+    const image = await createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    const canvas = document.createElement('canvas');
+    canvas.width = image.width;
+    canvas.height = image.height;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    context.drawImage(image, 0, 0);
+    const left = Math.max(0, Math.min(image.width, Math.floor(region.x * image.width)));
+    const top = Math.max(0, Math.min(image.height, Math.floor(region.y * image.height)));
+    const right = Math.max(left, Math.min(image.width, Math.ceil((region.x + region.w) * image.width)));
+    const bottom = Math.max(top, Math.min(image.height, Math.ceil((region.y + region.h) * image.height)));
+    const pixels = context.getImageData(left, top, right - left, bottom - top).data;
+    let warm = 0;
+    for (let offset = 0; offset < pixels.length; offset += 4) {
+      if (pixels[offset] - pixels[offset + 2] > region.minRedBlueDelta) warm++;
+    }
+    return { warm, bounds: [left, top, right, bottom] };
+  }, { png64: png.toString('base64'), region });
+}
+
+let baselineManifest = null;
+const baselineManifestPath = resolve(baselineRoot, GOLDEN_BASELINE_MANIFEST);
+if (existsSync(baselineManifestPath)) {
+  try { baselineManifest = JSON.parse(readFileSync(baselineManifestPath, 'utf8')); }
+  catch { baselineManifest = { invalid: true }; }
+}
+
+const { page, browser } = await launch(
+  { width: 1000, height: 900 },
+  1,
+  ['--force-color-profile=srgb', '--font-render-hinting=none', '--disable-lcd-text'],
+  { locale: 'en-US', timezoneId: 'UTC', colorScheme: 'dark', reducedMotion: 'reduce' },
+);
+const chromium = await browser.version();
+const results = [];
+const pageErrors = [];
+page.on('pageerror', (error) => pageErrors.push(error.message));
+let buildFingerprint = null;
+try {
+  buildFingerprint = await assertFreshDemoBundle(page, ROOT);
+  for (const scenario of scenarios) {
+    const result = {
+      id: scenario.id,
+      threshold: scenario.threshold,
+      status: 'error',
+      actualSha256: null,
+    };
+    try {
+      pageErrors.length = 0;
+      result.runtime = await prepareGoldenScenario(page, scenario);
+      if (pageErrors.length) throw new Error(`browser exception: ${pageErrors.join(' | ')}`);
+      const clip = await goldenClip(page, scenario.capture);
+      const actual = await page.screenshot({
+        ...(clip ? { clip } : {}),
+        animations: 'disabled',
+        caret: 'hide',
+        scale: 'css',
+      });
+      const actualPath = resolve(actualRoot, `${scenario.id}.png`);
+      writeFileSync(actualPath, actual);
+      result.actualSha256 = sha256(actual);
+      result.actual = actualPath;
+      if (scenario.warmPixelRegion) {
+        const sample = await countWarmPixels(page, actual, scenario.warmPixelRegion);
+        result.warmPixels = sample.warm;
+        result.warmPixelBounds = sample.bounds;
+        if (sample.warm < scenario.warmPixelRegion.minPixels) {
+          throw new Error(
+            `semantic golden assertion failed: ${sample.warm} warm pixels, expected at least `
+            + `${scenario.warmPixelRegion.minPixels}`,
+          );
+        }
+      }
+      const baselinePath = resolve(baselineRoot, `${scenario.id}.png`);
+      result.baseline = baselinePath;
+      if (!existsSync(baselinePath)) {
+        result.status = 'missing-baseline';
+      } else {
+        const baseline = readFileSync(baselinePath);
+        const expectedBaselineSha256 = baselineManifest?.scenarios?.[scenario.id];
+        result.baselineSha256 = sha256(baseline);
+        if (!expectedBaselineSha256 || result.baselineSha256 !== expectedBaselineSha256) {
+          result.status = 'invalid-baseline';
+          result.error = expectedBaselineSha256
+            ? 'baseline PNG does not match its reviewed manifest hash'
+            : 'baseline PNG is not listed in the reviewed manifest';
+          results.push(result);
+          console.log(`${result.status.padEnd(17)} ${scenario.id}`);
+          continue;
+        }
+        const comparison = await comparePng(page, actual, baseline, scenario.threshold);
+        Object.assign(result, comparison);
+        result.status = comparison.passed ? 'passed' : 'different';
+        if (comparison.diffPngBase64) {
+          const diffPath = resolve(diffRoot, `${scenario.id}.png`);
+          writeFileSync(diffPath, Buffer.from(comparison.diffPngBase64, 'base64'));
+          result.diff = diffPath;
+        }
+        delete result.diffPngBase64;
+      }
+    } catch (error) {
+      result.error = error instanceof Error ? error.message : String(error);
+    }
+    results.push(result);
+    console.log(`${result.status.padEnd(17)} ${scenario.id}`);
+  }
+} finally {
+  await browser.close();
+}
+
+const manifestValid = !!baselineManifest
+  && !baselineManifest.invalid
+  && baselineManifest.matrixVersion === GOLDEN_MATRIX_VERSION
+  && baselineManifest.chromium === chromium
+  && GOLDEN_SCENARIOS.every((scenario) => typeof baselineManifest.scenarios?.[scenario.id] === 'string');
+const report = {
+  schema: 1,
+  mode,
+  generatedAt: new Date().toISOString(),
+  matrixVersion: GOLDEN_MATRIX_VERSION,
+  buildFingerprint,
+  chromium,
+  baselineManifest: baselineManifest ? {
+    present: true,
+    valid: manifestValid,
+    matrixVersion: baselineManifest.matrixVersion ?? null,
+    chromium: baselineManifest.chromium ?? null,
+  } : { present: false, valid: false, matrixVersion: null, chromium: null },
+  results,
+};
+writeFileSync(resolve(artifactRoot, 'golden-report.json'), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+if (goldenRunFailed(mode, manifestValid, results)) process.exitCode = 1;

demo/performance/README.md

@@ -0,0 +1,159 @@
+# Large-house performance gate
+
+`benchmark_large_house.mjs` exercises the deterministic `large-house-v1`
+fixture. The fixture has 60 rooms, 200 devices, 100 openings, 60 partitions,
+40 columns and 500 decor objects on three floors.
+
+The runner records seven measured samples after one discarded warm-up. With
+this intentionally small CI sample, the nearest-rank `p95` is the observed
+maximum; reports keep the conventional field name but should be read as a
+high-tail guard rather than a population estimate:
+
+- model readiness and first stable render;
+- space switch, HA state update, pan/zoom and opening the settings dialog;
+- a shared-wall room-resize preview which is cancelled before persistence;
+- a twelve-switch navigation cycle;
+- Long Tasks for every measured window;
+- heap growth after four additional navigation rounds with forced GC;
+- hot-cache size and growth after the same warmed cycles.
+
+Every report is tied to the source fingerprint embedded by Rollup. A stale
+bundle is a hard failure.
+
+## CI contracts
+
+Ordinary pushes, pull requests and prereleases use the blocking
+`performance_smoke` job in `validate.yml`. It builds only the candidate and
+measures the heaviest 60-source `large-house-glow-overlay-v1` state after one
+warm-up, with three recorded samples. `compare.mjs --absolute-only` enforces the
+reviewed hard timing, Long Task, heap, cache and rendered-device ceilings from
+`budgets-glow-smoke.json`; it deliberately makes no noisy base-relative claim.
+This is a catastrophic-regression guard, not a performance trend detector.
+
+The dedicated `performance.yml` workflow is the full comparison. It runs on
+every `main` promotion, weekly and on manual dispatch for an important beta or
+performance-sensitive change. It checks out the candidate and its base SHA,
+builds both, and runs them sequentially with the same Node.js 22 process
+family, pinned Playwright Chromium and hosted runner. `compare.mjs` then
+applies two limits:
+
+1. a relative regression allowance against the base-SHA report;
+2. an absolute safety ceiling from `budgets.json`.
+
+The tighter limit wins. The absolute values are catastrophic safety ceilings,
+not normal-performance targets; the base-relative comparison catches smaller
+regressions. Small fast operations receive an absolute noise
+allowance so normal scheduler jitter does not become a false regression. Heap,
+Long Tasks, warmed-cache growth and the expected rendered-device count are
+gated separately. Long-Task maximum/count/total checks use the same
+relative-plus-absolute policy as timings. Both raw reports and the comparison
+are always uploaded as the `full-performance` artifact, and the table is
+written to the GitHub job summary. Stable release assets require both exact-SHA
+`Validate` and exact-SHA `Full Performance`; prereleases require only
+`Validate`.
+
+This base-vs-candidate design intentionally does not compare timings captured
+on different machines or different Chromium builds. A runtime/profile mismatch
+fails closed.
+
+Before the base checkout, CI fetches the complete commit graph and verifies the
+requested comparison revision. A `main` push uses `github.event.before`, which
+must both exist and remain an ancestor of the candidate; this catches the
+unreachable SHA left by a force-push. A manual run may name an explicit tag,
+branch or SHA, while an empty manual input and the weekly run use the candidate
+parent. An unusable requested revision falls back with a warning to the direct
+parent, then to the newest reachable semver release. If no safe comparison
+exists, the job fails closed instead of comparing against an arbitrary commit.
+
+## Private card contract
+
+The candidate benchmark runner is also executed against the base bundle, so
+every private `houseplan-card` field or method it reads is an explicit API of
+the performance harness. `card-contract.mjs` lists that surface for the
+large-house and Glow profiles. Each runner verifies it immediately after card
+creation and fails with the exact missing names or invalid runtime types before
+waiting for readiness or recording timings. Required caches must be real
+`Map` instances and must never be converted from missing/invalid values to
+plausible zeroes.
+
+`fields` are required in every supported comparison base. `optionalFields` are
+newer members whose absence has an explicit safe fallback in the runner; if an
+optional member exists, its declared `fieldTypes` contract still applies. Add a
+new safely degradable field to `optionalFields` until every supported base has
+it, then promote it to `fields`. A member without a truthful fallback must be
+introduced through a compatibility revision before the benchmark consumes it.
+
+Rename a consumed private member in two revisions:
+
+1. teach the contract and every reader to understand both the old and proposed
+   name while production still exposes the old name; land that compatibility
+   revision so it can become a comparison base;
+2. rename the production member and prefer the new name while retaining the
+   old reader fallback. Remove the fallback only after all supported comparison
+   bases expose the new member.
+
+This sequencing keeps the current harness capable of profiling both source
+trees. A one-step rename that merely edits the candidate reader is forbidden:
+it would make the same runner incompatible with its base bundle.
+
+## Local diagnostics
+
+Build and copy a fresh demo bundle first, then run:
+
+```bash
+npm run benchmark:large-house -- --samples=7 --warmups=1 --output=artifacts/performance/local.json
+```
+
+A local report is diagnostic only; it cannot replace the CI comparison.
+
+To reproduce the comparison against another checkout using one harness and one
+browser installation:
+
+```bash
+npm run benchmark:large-house -- --target-root=../base --samples=7 --output=artifacts/performance/baseline.json
+npm run benchmark:large-house -- --target-root=. --samples=7 --output=artifacts/performance/candidate.json
+npm run benchmark:compare
+```
+
+## Changing budgets
+
+Budget changes require an explicit review of recent CI artifacts and a written
+rationale in the change. Do not loosen a threshold merely to make a single red
+run pass. A new fixture profile gets a new profile id instead of silently
+changing the meaning of `large-house-v1`.
+
+The `cleanFloor` entry ceiling is 160: the reviewed fixture currently warms
+120 deterministic room/physical-body entries, and the extra 40 slots allow a
+legitimate fixture extension without weakening the separate zero-growth gate.
+
+## Glow profiles
+
+Both Glow profiles run deterministic 1/10/30/60-pool variants at DPR 1 and
+Chromium CPU throttling x4, but deliberately exercise different fixtures:
+
+- `large-light-blend-v1` compares the isolated screen group with the previous
+  normal-layer implementation on the shared frontend/backend schema fixture
+  `test/fixtures/glow/additive-pools.json`;
+- `large-house-glow-overlay-v1` measures simultaneous temperature fill and
+  independent Glow on the existing 60-room/200-device large-house fixture,
+  without changing `large-house-v1`.
+
+```bash
+npm run benchmark:glow -- --profile=large-light-blend-v1 --output=artifacts/performance/glow.json
+npm run benchmark:glow -- --profile=large-house-glow-overlay-v1 --output=artifacts/performance/overlay.json
+npm run benchmark:glow -- --profile=large-house-glow-overlay-v1 --variants=60 --samples=3 --warmups=1 --output=artifacts/performance-smoke/candidate.json
+npm run benchmark:compare -- --absolute-only --budgets=demo/performance/budgets-glow-smoke.json --candidate=artifacts/performance-smoke/candidate.json --output=artifacts/performance-smoke/comparison.json
+```
+
+Reports include per-variant state-update timings, render/pool counts, Long
+Tasks, screenshot time, heap and cache growth. The first CI comparison against
+a base SHA that predates `glow_enabled` bootstraps only the overlay profile's
+relative baseline from the candidate; its absolute ceilings still gate that
+introduction. Every subsequent revision compares both profiles to the real
+base SHA.
+
+The initial absolute ceilings are intentionally conservative bootstrap limits;
+they must be reviewed against the first paired Ubuntu artifacts before the
+feature is promoted from beta. Same-runner relative checks in the full workflow
+remain the primary regression signal; the candidate-only smoke only guards
+against catastrophic failures.

demo/performance/budgets-glow-smoke.json

@@ -0,0 +1,39 @@
+{
+  "schema": 1,
+  "profile": "large-house-glow-overlay-v1",
+  "minimumSamples": 3,
+  "timings": {
+    "stateUpdate60Ms": {
+      "stat": "median",
+      "hardMaxMs": 2200
+    },
+    "screenshotCaptureMs": {
+      "stat": "median",
+      "hardMaxMs": 3200
+    }
+  },
+  "longTasks": {
+    "maxSingleMs": 2700,
+    "maxCountP95": 12,
+    "maxTotalP95Ms": 5500
+  },
+  "heap": {
+    "required": true,
+    "hardMaxGrowthBytes": 67108864
+  },
+  "cacheEntries": {
+    "cleanFloor": 80,
+    "glowClip": 128,
+    "wallUnion": 1,
+    "openingTunnel": 1,
+    "openingWallIndex": 1
+  },
+  "cacheGrowth": {
+    "cleanFloor": 0,
+    "glowClip": 0,
+    "wallUnion": 0,
+    "openingTunnel": 0,
+    "openingWallIndex": 0
+  },
+  "renderedDevices": 200
+}

demo/performance/budgets-large-house-glow-overlay.json

@@ -0,0 +1,27 @@
+{
+  "schema": 1,
+  "profile": "large-house-glow-overlay-v1",
+  "minimumSamples": 7,
+  "timings": {
+    "stateUpdate1Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 50, "hardMaxMs": 750 },
+    "stateUpdate10Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 75, "hardMaxMs": 1100 },
+    "stateUpdate30Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 100, "hardMaxMs": 1500 },
+    "stateUpdate60Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 150, "hardMaxMs": 2200 },
+    "screenshotCaptureMs": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 250, "hardMaxMs": 3200 }
+  },
+  "longTasks": {
+    "maxSingleMs": 2700,
+    "maxSingleRegressionRatio": 0.5,
+    "maxSingleNoiseAllowanceMs": 200,
+    "maxCountP95": 12,
+    "maxCountRegressionRatio": 0.5,
+    "countNoiseAllowance": 2,
+    "maxTotalP95Ms": 5500,
+    "maxTotalRegressionRatio": 0.5,
+    "noiseAllowanceMs": 250
+  },
+  "heap": { "required": true, "hardMaxGrowthBytes": 67108864, "maxRegressionRatio": 0.75, "noiseAllowanceBytes": 16777216 },
+  "cacheEntries": { "cleanFloor": 80, "glowClip": 128, "wallUnion": 1, "openingTunnel": 1, "openingWallIndex": 1 },
+  "cacheGrowth": { "cleanFloor": 0, "glowClip": 0, "wallUnion": 0, "openingTunnel": 0, "openingWallIndex": 0 },
+  "renderedDevices": 200
+}

demo/performance/budgets-large-light-blend.json

@@ -0,0 +1,27 @@
+{
+  "schema": 1,
+  "profile": "large-light-blend-v1",
+  "minimumSamples": 7,
+  "timings": {
+    "stateUpdate1Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 50, "hardMaxMs": 700 },
+    "stateUpdate10Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 75, "hardMaxMs": 1000 },
+    "stateUpdate30Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 100, "hardMaxMs": 1400 },
+    "stateUpdate60Ms": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 150, "hardMaxMs": 2000 },
+    "screenshotCaptureMs": { "stat": "median", "maxRegressionRatio": 0.5, "noiseAllowanceMs": 250, "hardMaxMs": 3000 }
+  },
+  "longTasks": {
+    "maxSingleMs": 2500,
+    "maxSingleRegressionRatio": 0.5,
+    "maxSingleNoiseAllowanceMs": 200,
+    "maxCountP95": 12,
+    "maxCountRegressionRatio": 0.5,
+    "countNoiseAllowance": 2,
+    "maxTotalP95Ms": 5000,
+    "maxTotalRegressionRatio": 0.5,
+    "noiseAllowanceMs": 250
+  },
+  "heap": { "required": true, "hardMaxGrowthBytes": 67108864, "maxRegressionRatio": 0.75, "noiseAllowanceBytes": 16777216 },
+  "cacheEntries": { "cleanFloor": 8, "glowClip": 200, "wallUnion": 1, "openingTunnel": 1, "openingWallIndex": 1 },
+  "cacheGrowth": { "cleanFloor": 0, "glowClip": 0, "wallUnion": 0, "openingTunnel": 0, "openingWallIndex": 0 },
+  "renderedDevices": 60
+}

demo/performance/budgets.json

@@ -0,0 +1,87 @@
+{
+  "schema": 1,
+  "profile": "large-house-v1",
+  "minimumSamples": 7,
+  "timings": {
+    "modelReadyMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.3,
+      "noiseAllowanceMs": 200,
+      "hardMaxMs": 2500
+    },
+    "firstStableRenderMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.3,
+      "noiseAllowanceMs": 250,
+      "hardMaxMs": 3000
+    },
+    "spaceSwitchMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.5,
+      "noiseAllowanceMs": 75,
+      "hardMaxMs": 1500
+    },
+    "stateUpdateMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.5,
+      "noiseAllowanceMs": 75,
+      "hardMaxMs": 1000
+    },
+    "resizePreviewMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.4,
+      "noiseAllowanceMs": 150,
+      "hardMaxMs": 2000
+    },
+    "panZoomMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.5,
+      "noiseAllowanceMs": 60,
+      "hardMaxMs": 500
+    },
+    "settingsDialogMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.5,
+      "noiseAllowanceMs": 100,
+      "hardMaxMs": 1000
+    },
+    "switchCycleMs": {
+      "stat": "median",
+      "maxRegressionRatio": 0.35,
+      "noiseAllowanceMs": 250,
+      "hardMaxMs": 7000
+    }
+  },
+  "longTasks": {
+    "maxSingleMs": 3000,
+    "maxSingleRegressionRatio": 0.3,
+    "maxSingleNoiseAllowanceMs": 250,
+    "maxCountP95": 30,
+    "maxCountRegressionRatio": 0.35,
+    "countNoiseAllowance": 3,
+    "maxTotalP95Ms": 12000,
+    "maxTotalRegressionRatio": 0.3,
+    "noiseAllowanceMs": 150
+  },
+  "heap": {
+    "required": true,
+    "hardMaxGrowthBytes": 67108864,
+    "maxRegressionRatio": 0.75,
+    "noiseAllowanceBytes": 16777216
+  },
+  "cacheEntries": {
+    "cleanFloor": 160,
+    "glowClip": 200,
+    "wallUnion": 1,
+    "openingTunnel": 1,
+    "openingWallIndex": 1
+  },
+  "cacheGrowth": {
+    "cleanFloor": 0,
+    "glowClip": 0,
+    "wallUnion": 0,
+    "openingTunnel": 0,
+    "openingWallIndex": 0
+  },
+  "renderedDevices": 200
+}

demo/performance/card-contract.mjs

@@ -0,0 +1,101 @@
+/**
+ * Private houseplan-card surface consumed by the performance runners.
+ *
+ * The candidate runner profiles both the candidate bundle and a bundle built
+ * from the comparison SHA. Keep these lists explicit so a private rename in
+ * either tree fails before measurements instead of silently reporting zeroes.
+ */
+const CACHE_FIELDS = Object.freeze([
+  '_cleanFloorCache',
+  '_glowClipCache',
+  '_wallUnionCache',
+  '_openingTunnelCache',
+  '_openingWallIndexCache',
+]);
+
+export const LARGE_HOUSE_CARD_CONTRACT = Object.freeze({
+  label: 'large-house-v1',
+  methods: Object.freeze([
+    '_baseVb',
+    '_openSettingsDialog',
+    '_pickSpace',
+    '_rszCancelDrag',
+    '_rszEdgeDown',
+    '_rszMove',
+    '_rszRooms',
+    '_setMode',
+    '_viewOr',
+  ]),
+  fields: Object.freeze([
+    '_booting',
+    ...CACHE_FIELDS,
+    '_devices',
+    '_gridPitch',
+    '_loadOk',
+    '_model',
+    '_rszDrag',
+    '_settingsDialog',
+    '_tool',
+  ]),
+  optionalFields: Object.freeze([]),
+  fieldTypes: Object.freeze({
+    _booting: 'boolean',
+    _cleanFloorCache: 'map',
+    _devices: 'array',
+    _glowClipCache: 'map',
+    _gridPitch: 'number',
+    _loadOk: 'boolean',
+    _model: 'array',
+    _tool: 'string',
+  }),
+});
+
+export const GLOW_CARD_CONTRACT = Object.freeze({
+  label: 'Glow performance profiles',
+  methods: Object.freeze([]),
+  fields: Object.freeze([
+    ...CACHE_FIELDS,
+    '_devices',
+    '_loadOk',
+  ]),
+  // Additive blending was introduced after the first supported performance
+  // bases. Its absence is safe: the runner keeps the historical normal blend.
+  optionalFields: Object.freeze(['_glowScreenBlend']),
+  fieldTypes: Object.freeze({
+    _cleanFloorCache: 'map',
+    _devices: 'array',
+    _glowClipCache: 'map',
+    _glowScreenBlend: 'boolean',
+    _loadOk: 'boolean',
+  }),
+});
+
+/** Single fail-fast implementation injected into both browser runners. Keep
+ * this function self-contained: runners serialize it with `toString()`. */
+export function assertCardContract(card, contract) {
+  const matches = (value, expected) => {
+    if (expected === 'array') return Array.isArray(value);
+    if (expected === 'map') return value instanceof Map;
+    return typeof value === expected;
+  };
+  const missingMethods = contract.methods
+    .filter((name) => typeof card[name] !== 'function')
+    .map((name) => `${name}()`);
+  const missingFields = contract.fields
+    .filter((name) => !(name in card) || card[name] === undefined);
+  const invalidFields = [...contract.fields, ...(contract.optionalFields || [])]
+    .filter((name) => name in card && contract.fieldTypes?.[name]
+      && !matches(card[name], contract.fieldTypes[name]))
+    .map((name) => `${name}:${contract.fieldTypes[name]}`);
+  const missing = [...missingMethods, ...missingFields];
+  if (missing.length || invalidFields.length) {
+    const details = [
+      missing.length ? `missing private API: ${missing.join(', ')}` : '',
+      invalidFields.length ? `invalid private API types: ${invalidFields.join(', ')}` : '',
+    ].filter(Boolean).join('; ');
+    throw new Error(
+      `${contract.label} harness is incompatible with this houseplan-card bundle; ${details}. `
+      + 'Update the explicit candidate/base compatibility contract before profiling.',
+    );
+  }
+}

demo/performance/compare.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { evaluatePerformanceBudget, performanceSummaryMarkdown } from './evaluate.mjs';
+
+const valueArg = (name) => process.argv.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+const absoluteOnly = process.argv.includes('--absolute-only');
+const candidatePath = resolve(valueArg('candidate') ?? 'artifacts/performance/candidate.json');
+const baselinePath = resolve(valueArg('baseline') ?? 'artifacts/performance/baseline.json');
+const budgetsPath = resolve(valueArg('budgets') ?? 'demo/performance/budgets.json');
+const outputPath = resolve(valueArg('output') ?? 'artifacts/performance/comparison.json');
+
+const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
+const evaluation = evaluatePerformanceBudget({
+  candidate: readJson(candidatePath),
+  baseline: absoluteOnly ? null : readJson(baselinePath),
+  budgets: readJson(budgetsPath),
+  absoluteOnly,
+});
+
+mkdirSync(dirname(outputPath), { recursive: true });
+writeFileSync(outputPath, `${JSON.stringify(evaluation, null, 2)}\n`, 'utf8');
+const markdown = performanceSummaryMarkdown(evaluation);
+process.stdout.write(markdown);
+if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown, 'utf8');
+if (!evaluation.pass) {
+  console.error(`Performance budget failed: ${evaluation.failures.map((item) => item.id).join(', ')}`);
+  process.exitCode = 1;
+}

demo/performance/evaluate.mjs

@@ -0,0 +1,220 @@
+const percentile = (values, p) => {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1))];
+};
+
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+const round = (value, digits = 2) => finite(value) ? Number(value.toFixed(digits)) : value;
+
+export const summarizeTimings = (rows, metricNames) => Object.fromEntries(
+  metricNames.map((metric) => {
+    const values = rows.map((row) => row[metric]).filter(finite);
+    return [metric, {
+      median: percentile(values, 0.5),
+      p95: percentile(values, 0.95),
+      min: values.length ? Math.min(...values) : null,
+      max: values.length ? Math.max(...values) : null,
+    }];
+  }),
+);
+
+export const summarizeLongTasks = (rows) => {
+  const totals = [];
+  const counts = [];
+  const singles = [];
+  for (const row of rows) {
+    const windows = Object.values(row.longTasks ?? {});
+    totals.push(windows.reduce((sum, item) => sum + (item?.totalMs ?? 0), 0));
+    counts.push(windows.reduce((sum, item) => sum + (item?.count ?? 0), 0));
+    singles.push(...windows.map((item) => item?.maxMs ?? 0));
+  }
+  return {
+    maxSingleMs: round(singles.length ? Math.max(...singles) : 0),
+    countP95: percentile(counts, 0.95) ?? 0,
+    totalP95Ms: round(percentile(totals, 0.95) ?? 0),
+  };
+};
+
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+const requireReport = (report, budgets, label) => {
+  if (!report || report.schema !== 2) throw new Error(`${label}: unsupported report schema`);
+  if (report.profile !== budgets.profile) throw new Error(`${label}: unexpected benchmark profile`);
+  if (!Array.isArray(report.rows) || report.rows.length < budgets.minimumSamples) {
+    throw new Error(`${label}: expected at least ${budgets.minimumSamples} measured samples`);
+  }
+};
+
+const relativeLimit = (baseline, ratio, allowance) => Math.max(
+  baseline * (1 + ratio),
+  baseline + allowance,
+);
+
+const makeCheck = (id, actual, limit, details = {}) => ({
+  id,
+  actual: round(actual),
+  limit: round(limit),
+  pass: finite(actual) && actual <= limit,
+  ...details,
+});
+
+/**
+ * Evaluate a candidate report against stable absolute ceilings. Full captures
+ * additionally compare a base-SHA report from the same runner; fast smoke
+ * captures deliberately enforce only the hard candidate limits.
+ */
+export const evaluatePerformanceBudget = ({ candidate, baseline, budgets, absoluteOnly = false }) => {
+  requireReport(candidate, budgets, 'candidate');
+  if (!absoluteOnly) {
+    requireReport(baseline, budgets, 'baseline');
+    if (!sameJson(candidate.fixture, baseline.fixture)) throw new Error('fixture mismatch');
+    for (const key of ['node', 'chromium', 'platform', 'arch']) {
+      if (candidate.runtime?.[key] !== baseline.runtime?.[key]) {
+        throw new Error(`runtime mismatch for ${key}`);
+      }
+    }
+  }
+
+  const checks = [];
+  for (const [metric, budget] of Object.entries(budgets.timings)) {
+    const stat = budget.stat ?? 'median';
+    const actual = candidate.summary?.[metric]?.[stat];
+    const base = absoluteOnly ? null : baseline.summary?.[metric]?.[stat];
+    if (!finite(actual) || (!absoluteOnly && !finite(base))) throw new Error(`missing ${stat} for ${metric}`);
+    const regressionLimit = absoluteOnly
+      ? Number.POSITIVE_INFINITY
+      : relativeLimit(base, budget.maxRegressionRatio, budget.noiseAllowanceMs);
+    checks.push(makeCheck(
+      `timing.${metric}.${stat}`,
+      actual,
+      Math.min(budget.hardMaxMs, regressionLimit),
+      {
+        ...(absoluteOnly ? {} : { baseline: round(base), regressionLimit: round(regressionLimit) }),
+        hardLimit: budget.hardMaxMs,
+      },
+    ));
+  }
+
+  const candidateLong = candidate.longTasks ?? summarizeLongTasks(candidate.rows);
+  const baselineLong = absoluteOnly ? null : (baseline.longTasks ?? summarizeLongTasks(baseline.rows));
+  const longTasksAvailable = candidate.rows.every((row) => {
+    const windows = Object.values(row.longTasks ?? {});
+    return windows.length > 0 && windows.every((item) => item?.supported === true);
+  });
+  checks.push({ id: 'longTask.available', actual: longTasksAvailable ? 1 : 0, limit: 1, pass: longTasksAvailable });
+  const singleRegressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+    baselineLong.maxSingleMs, budgets.longTasks.maxSingleRegressionRatio,
+    budgets.longTasks.maxSingleNoiseAllowanceMs,
+  );
+  checks.push(makeCheck(
+    'longTask.maxSingleMs',
+    candidateLong.maxSingleMs,
+    Math.min(budgets.longTasks.maxSingleMs, singleRegressionLimit),
+    {
+      ...(absoluteOnly ? {} : { baseline: baselineLong.maxSingleMs }),
+      hardLimit: budgets.longTasks.maxSingleMs,
+    },
+  ));
+  const countRegressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+    baselineLong.countP95, budgets.longTasks.maxCountRegressionRatio,
+    budgets.longTasks.countNoiseAllowance,
+  );
+  checks.push(makeCheck(
+    'longTask.countP95',
+    candidateLong.countP95,
+    Math.min(budgets.longTasks.maxCountP95, countRegressionLimit),
+    {
+      ...(absoluteOnly ? {} : { baseline: baselineLong.countP95 }),
+      hardLimit: budgets.longTasks.maxCountP95,
+    },
+  ));
+  const longRegressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+    baselineLong.totalP95Ms, budgets.longTasks.maxTotalRegressionRatio,
+    budgets.longTasks.noiseAllowanceMs,
+  );
+  checks.push(makeCheck(
+    'longTask.totalP95Ms',
+    candidateLong.totalP95Ms,
+    Math.min(budgets.longTasks.maxTotalP95Ms, longRegressionLimit),
+    {
+      ...(absoluteOnly ? {} : { baseline: baselineLong.totalP95Ms }),
+      hardLimit: budgets.longTasks.maxTotalP95Ms,
+    },
+  ));
+
+  const candidateHeap = candidate.rows
+    .map((row) => row.heapGrowthBytes)
+    .filter(finite)
+    .map((value) => Math.max(0, value));
+  const baselineHeap = absoluteOnly ? [] : baseline.rows
+    .map((row) => row.heapGrowthBytes)
+    .filter(finite)
+    .map((value) => Math.max(0, value));
+  const preciseGc = candidate.rows.every((row) => row.preciseGc === true);
+  checks.push({
+    id: 'heap.preciseGc', actual: preciseGc ? 1 : 0, limit: budgets.heap.required ? 1 : 0,
+    pass: !budgets.heap.required || preciseGc,
+  });
+  if (budgets.heap.required && (!candidateHeap.length || (!absoluteOnly && !baselineHeap.length))) {
+    checks.push({ id: 'heap.available', actual: candidateHeap.length, limit: 1, pass: false });
+  } else if (candidateHeap.length && (absoluteOnly || baselineHeap.length)) {
+    const actual = percentile(candidateHeap, 0.95);
+    const base = absoluteOnly ? null : percentile(baselineHeap, 0.95);
+    const regressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+      base, budgets.heap.maxRegressionRatio, budgets.heap.noiseAllowanceBytes,
+    );
+    checks.push(makeCheck(
+      'heap.growthP95Bytes',
+      actual,
+      Math.min(budgets.heap.hardMaxGrowthBytes, regressionLimit),
+      {
+        ...(absoluteOnly ? {} : { baseline: base }),
+        hardLimit: budgets.heap.hardMaxGrowthBytes,
+      },
+    ));
+  }
+
+  for (const [cache, limit] of Object.entries(budgets.cacheEntries)) {
+    const actual = Math.max(...candidate.rows.map((row) => row.cacheEntries?.[cache] ?? Number.POSITIVE_INFINITY));
+    checks.push(makeCheck(`cache.entries.${cache}`, actual, limit));
+  }
+  for (const [cache, limit] of Object.entries(budgets.cacheGrowth)) {
+    const actual = Math.max(...candidate.rows.map((row) => row.cacheGrowth?.[cache] ?? Number.POSITIVE_INFINITY));
+    checks.push(makeCheck(`cache.growth.${cache}`, actual, limit));
+  }
+
+  const renderedDevices = Math.min(...candidate.rows.map((row) => row.renderedDevices ?? -1));
+  checks.push({
+    id: 'renderedDevices',
+    actual: renderedDevices,
+    limit: budgets.renderedDevices,
+    pass: renderedDevices === budgets.renderedDevices,
+  });
+
+  const failures = checks.filter((check) => !check.pass);
+  return {
+    schema: 1,
+    profile: budgets.profile,
+    pass: failures.length === 0,
+    mode: absoluteOnly ? 'absolute' : 'relative',
+    candidateFingerprint: candidate.buildFingerprint,
+    baselineFingerprint: baseline?.buildFingerprint ?? null,
+    checks,
+    failures,
+  };
+};
+
+export const performanceSummaryMarkdown = (evaluation) => {
+  const icon = evaluation.pass ? '✅' : '❌';
+  const lines = [
+    `### ${icon} House Plan large-house performance`,
+    '',
+    '| Check | Candidate | Limit | Base |',
+    '|---|---:|---:|---:|',
+  ];
+  for (const check of evaluation.checks) {
+    lines.push(`| ${check.pass ? '✅' : '❌'} ${check.id} | ${check.actual} | ${check.limit} | ${check.baseline ?? '—'} |`);
+  }
+  return `${lines.join('\n')}\n`;
+};

demo/screencast_visual_continuity.mjs

@@ -0,0 +1,126 @@
+// #73 stable-release pixel gate. Unlike a loop of Playwright screenshots,
+// CDP screencast observes compositor-presented frames and can therefore catch
+// the single black/empty frame that motivated the visual-continuity contract.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { launch, check, finish } from './serve.mjs';
+
+const { page, browser } = await launch({ width: 820, height: 760 });
+const session = await page.context().newCDPSession(page);
+const frames = [];
+let stopped = false;
+
+session.on('Page.screencastFrame', (event) => {
+  if (frames.length < 120) frames.push(event.data);
+  void session.send('Page.screencastFrameAck', { sessionId: event.sessionId });
+});
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+try {
+  await page.waitForFunction(() => {
+    const card = window.__card;
+    const root = card?.shadowRoot || card?.renderRoot;
+    const host = root?.querySelector('ha-card');
+    return host?.dataset.continuityState === 'steady' && !!host?.dataset.frameFingerprint;
+  });
+  const stage = await page.locator('houseplan-card').evaluate((card) => {
+    const node = (card.shadowRoot || card.renderRoot).querySelector('.stage');
+    const rect = node.getBoundingClientRect();
+    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+  });
+  // The reference is an explicitly settled DOM screenshot, never the first
+  // compositor frame emitted by the screencast itself. A degraded first frame
+  // must fail against this baseline rather than widening its own tolerance.
+  const baselinePng = await page.screenshot({ clip: stage });
+
+  await session.send('Page.startScreencast', {
+    format: 'png', everyNthFrame: 1, maxWidth: 820, maxHeight: 760,
+  });
+  await wait(120);
+  await page.evaluate(() => window.__card._pageVisibility({
+    kind: 'visible', token: 73, at: Date.now(), hiddenFor: 20_000, long: true,
+  }));
+  // A harmless real paint gives the compositor enough damage to emit the
+  // candidate sequence even when the fresh server response equals the stale
+  // frame pixel-for-pixel.
+  await page.mouse.move(stage.x + stage.width * 0.42, stage.y + stage.height * 0.52);
+  await wait(850);
+  await page.mouse.move(2, 2);
+  await wait(180);
+  await session.send('Page.stopScreencast');
+  stopped = true;
+
+  const allMetrics = await page.evaluate(async ({ encoded, crop }) => {
+    const decode = (data) => new Promise((resolve, reject) => {
+      const image = new Image();
+      image.onload = () => resolve(image);
+      image.onerror = reject;
+      image.src = `data:image/png;base64,${data}`;
+    });
+    const out = [];
+    for (const data of encoded) {
+      const image = await decode(data);
+      const scaleX = image.width / innerWidth;
+      const scaleY = image.height / innerHeight;
+      const x = Math.max(0, Math.floor(crop.x * scaleX));
+      const y = Math.max(0, Math.floor(crop.y * scaleY));
+      const width = Math.max(1, Math.min(image.width - x, Math.floor(crop.width * scaleX)));
+      const height = Math.max(1, Math.min(image.height - y, Math.floor(crop.height * scaleY)));
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const context = canvas.getContext('2d', { willReadFrequently: true });
+      context.drawImage(image, x, y, width, height, 0, 0, width, height);
+      const pixels = context.getImageData(0, 0, width, height).data;
+      let count = 0;
+      let sum = 0;
+      let sum2 = 0;
+      let dark = 0;
+      for (let row = 0; row < height; row += 4) {
+        for (let column = 0; column < width; column += 4) {
+          const offset = (row * width + column) * 4;
+          const luma = pixels[offset] * 0.2126
+            + pixels[offset + 1] * 0.7152 + pixels[offset + 2] * 0.0722;
+          count++;
+          sum += luma;
+          sum2 += luma * luma;
+          if (luma < 18) dark++;
+        }
+      }
+      const mean = sum / Math.max(1, count);
+      out.push({
+        mean,
+        variance: sum2 / Math.max(1, count) - mean * mean,
+        darkRatio: dark / Math.max(1, count),
+      });
+    }
+    return out;
+  }, { encoded: [baselinePng.toString('base64'), ...frames], crop: stage });
+
+  const baseline = allMetrics[0] || { mean: 0, variance: 0, darkRatio: 1 };
+  const metrics = allMetrics.slice(1);
+  const forbidden = metrics.filter((frame) => (
+    frame.variance < Math.max(12, baseline.variance * 0.08)
+    || frame.mean < Math.max(4, baseline.mean * 0.35)
+    || (baseline.darkRatio < 0.85 && frame.darkRatio > 0.96)
+  ));
+
+  mkdirSync('artifacts/continuity-screencast', { recursive: true });
+  frames.forEach((data, index) => writeFileSync(
+    `artifacts/continuity-screencast/frame-${String(index).padStart(3, '0')}.png`,
+    Buffer.from(data, 'base64'),
+  ));
+  writeFileSync('artifacts/continuity-screencast/metrics.json', JSON.stringify({
+    stage, frames: metrics, forbidden: forbidden.length,
+  }, null, 2));
+
+  const result = {
+    capturedPresentedFrames: frames.length >= 2,
+    baselineContainsPlanDetail: baseline.variance >= 12 && baseline.mean >= 4,
+    noEmptyOrBlackPresentedFrame: forbidden.length === 0,
+  };
+  for (const [name, value] of Object.entries(result)) check(name, value);
+  await finish(browser, result);
+} finally {
+  if (!stopped) await session.send('Page.stopScreencast').catch(() => undefined);
+  await browser.close().catch(() => undefined);
+}

demo/serve.mjs

@@ -40,22 +40,34 @@ export async function finish(browser, out) {
   }
 }
 
-export async function launch(viewport = { width: 820, height: 760 }, scale = 1) {
-  const browser = await chromium.launch({ args: ['--no-sandbox'] });
-  const page = await (await browser.newContext({ viewport, deviceScaleFactor: scale })).newPage();
+export async function launch(
+  viewport = { width: 820, height: 760 },
+  scale = 1,
+  browserArgs = [],
+  contextOptions = {},
+  serveRoot = ROOT,
+) {
+  const browser = await chromium.launch({ args: ['--no-sandbox', ...browserArgs] });
+  const page = await (await browser.newContext({
+    viewport, deviceScaleFactor: scale, ...contextOptions,
+  })).newPage();
   // audit T1: an exception inside the card used to be logged and ignored
   page.on('pageerror', (e) => { _pageErrors++; console.log('EXC', e.message); });
   await page.route('**/*', (r) => {
     const u = new URL(r.request().url());
     let p = decodeURIComponent(u.pathname);
     if (p === '/') p = '/demo.html';
-    const f = ROOT + p;
+    const f = serveRoot + p;
     existsSync(f)
       ? r.fulfill({ status: 200, headers: { 'content-type': CT[p.slice(p.lastIndexOf('.'))] || 'application/octet-stream' }, body: readFileSync(f) })
       : r.fulfill({ status: 404, body: 'nf' });
   });
   await page.goto('http://demo.local/demo.html', { waitUntil: 'domcontentloaded' });
   await page.waitForFunction(() => window.__card?._model?.length > 0, { timeout: 9000 });
+  // HP-1552: the first-open boot veil hides the plan (visibility:hidden) until
+  // the stage height settles — real pointer interaction cannot hit a hidden
+  // plan, so every smoke starts where the user does: with the plan revealed.
+  await page.waitForFunction(() => window.__card._booting === false, { timeout: 9000 });
   // hass flows continuously in production; the stub sets it once — nudge a rebuild
   await page.evaluate(() => { const c = window.__card; c.hass = { ...c.hass }; });
   await page.waitForFunction(() => window.__card._devices.length > 0, { timeout: 9000 });

demo/shot_backdrop.mjs

@@ -0,0 +1,67 @@
+// Backdrop image (docs/BACKDROP.md) — two shots for the owner:
+//   backdrop_frame — the transform frame mid-gesture: dashed outline, four
+//                    finger-sized corner handles, and the live "W × H" badge
+//                    stating the picture's real size through cell_cm;
+//   backdrop_paper — the new paper rule on an image plan: the opaque sheet is
+//                    the ROOM CONTOURS, so the scene colour is visible around
+//                    them and under the parts of the picture nobody has drawn
+//                    over. The picture is scaled down here so both are obvious.
+// Usage: node demo/shot_backdrop.mjs <outdir>
+import { launch } from './serve.mjs';
+const outDir = process.argv[2] || '/tmp';
+const { page, browser } = await launch({ width: 900, height: 820 }, 2);
+await page.emulateMedia({ reducedMotion: 'reduce' });
+
+const settle = () => page.waitForTimeout(260);
+
+// ---- 1) the frame, mid-drag ---------------------------------------------
+await page.evaluate(async () => {
+  const c = window.__card;
+  c._setMode('decor');
+  c._decorTool = 'backdrop';
+  c.requestUpdate();
+  await c.updateComplete;
+});
+await settle();
+const screenPt = (x, y) => page.evaluate(([x, y]) => {
+  const stage = window.__card.renderRoot.querySelector('.stage');
+  const r = stage.getBoundingClientRect();
+  const [vx, vy, vw, vh] = stage.querySelector('svg').getAttribute('viewBox').split(' ').map(Number);
+  return [r.left + ((x - vx) / vw) * r.width, r.top + ((y - vy) / vh) * r.height];
+}, [x, y]);
+{
+  // grab the bottom-right handle and hold it mid-gesture, so the shot carries
+  // the frame AND the live badge at once
+  const [ax, ay] = await screenPt(1000, 900);
+  const [bx, by] = await screenPt(820, 760);
+  await page.mouse.move(ax, ay);
+  await page.mouse.down();
+  await page.mouse.move((ax + bx) / 2, (ay + by) / 2, { steps: 4 });
+  await settle();
+  await page.screenshot({ path: `${outDir}/backdrop_frame.png` });
+  await page.mouse.up();
+}
+await settle();
+
+// ---- 2) the paper is the rooms ------------------------------------------
+await page.evaluate(async () => {
+  const c = window.__card;
+  const sp = c._serverCfg.spaces.find((s) => s.id === 'f1');
+  // a picture pulled well inside the plan and an acid scene colour: what shows
+  // through around the rooms is the SCENE, which is the whole new rule
+  sp.plan_x = 0.16; sp.plan_y = 0.10; sp.plan_scale = 0.62;
+  c._serverCfg.settings = { ...(c._serverCfg.settings || {}), bg_color: '#7bd389' };
+  c._cfgEpoch++; c._frame = null;
+  c._setMode('view');
+  c.requestUpdate();
+  await c.updateComplete;
+  c._fitAll();
+  c.requestUpdate();
+  await c.updateComplete;
+});
+await settle();
+await settle();
+await page.screenshot({ path: `${outDir}/backdrop_paper.png` });
+
+await browser.close();
+console.log('shots written to ' + outDir + '/backdrop_frame.png, ' + outDir + '/backdrop_paper.png');

demo/shot_cover_move.mjs

@@ -0,0 +1,33 @@
+// Capture: a curtain on the move — the semantic transition ring around a
+// NEUTRAL plate (owner 2026-08-03). The pulse is frozen at a visible frame so
+// the shot is deterministic.
+import { launch } from './serve.mjs';
+const { page, browser } = await launch({ width: 820, height: 760 }, 2);
+await page.evaluate(async () => {
+  const c = window.__card;
+  c._serverCfg = { ...c._serverCfg, markers: [
+    { id: 'm_gate', binding: 'device:d_gate', tap_action: 'cover', display: 'icon_ripple' },
+    { id: 'm_mower', binding: 'device:d_mower', hidden: true },
+  ] };
+  c._cfgEpoch++; c._regSignature = ''; c._maybeRebuildDevices();
+  c.hass = { ...c.hass, states: { ...c.hass.states,
+    'cover.gate': { entity_id: 'cover.gate', state: 'opening',
+      attributes: { friendly_name: 'Curtain', device_class: 'curtain' } } } };
+  c._setMode('view'); c._space = 'garden';
+  c.requestUpdate();
+  await c.updateComplete;
+  const st = document.createElement('style');
+  st.textContent = '.activity-ring.transition i:first-child{animation-delay:-1.1s!important;animation-play-state:paused!important;}';
+  (c.shadowRoot || c.renderRoot).appendChild(st);
+});
+await page.waitForTimeout(400);
+const box = await page.evaluate(() => {
+  const c = window.__card;
+  const r = (c.shadowRoot || c.renderRoot).querySelector('.dev.activity-transition').getBoundingClientRect();
+  return { x: r.x, y: r.y, w: r.width, h: r.height };
+});
+const pad = 70;
+await page.screenshot({ path: process.argv[2] || '/tmp/cover_move.png',
+  clip: { x: Math.max(0, box.x - pad), y: Math.max(0, box.y - pad), width: box.w + pad * 2, height: box.h + pad * 2 } });
+await browser.close();
+console.log('shot ok');

demo/shot_cover_states.mjs

@@ -0,0 +1,70 @@
+// Capture: one curtain in the four states an owner sees — closed, open,
+// opening, closing (owner's contract 2026-08-04). The plate is the plain
+// neutral badge in ALL of them; open/closed is told by the icon morph alone,
+// and the two travelling ones add the breathing transition ring (frozen at a
+// visible frame so the shot is deterministic).
+import { launch } from './serve.mjs';
+const { page, browser } = await launch({ width: 900, height: 520 }, 2);
+const STATES = ['closed', 'open', 'opening', 'closing'];
+await page.evaluate(async (STATES) => {
+  const c = window.__card;
+  const devices = {}; const entities = {}; const states = {};
+  STATES.forEach((s, i) => {
+    const id = 'd_cur' + i;
+    devices[id] = { id, name: 'Curtain ' + s, model: 'Roller shade driver E1',
+      area_id: 'garden', identifiers: [['demo', id]], entry_type: null, via_device_id: null };
+    entities['cover.cur' + i] = { entity_id: 'cover.cur' + i, device_id: id, platform: 'demo' };
+    states['cover.cur' + i] = { entity_id: 'cover.cur' + i, state: s,
+      attributes: { friendly_name: 'Curtain ' + s, device_class: 'curtain' } };
+  });
+  c.hass = { ...c.hass,
+    devices: { ...c.hass.devices, ...devices },
+    entities: { ...c.hass.entities, ...entities },
+    states: { ...c.hass.states, ...states } };
+  c._serverCfg = { ...c._serverCfg, markers: [
+    ...STATES.map((s, i) => ({ id: 'm_cur' + i, binding: 'device:d_cur' + i,
+      tap_action: 'cover', display: 'icon_ripple' })),
+    { id: 'm_mower', binding: 'device:d_mower', hidden: true },
+    { id: 'm_gate', binding: 'device:d_gate', hidden: true },
+  ] };
+  c._cfgEpoch++; c._regSignature = ''; c._maybeRebuildDevices();
+  const layout = { ...c._layout };
+  STATES.forEach((s, i) => {
+    const d = c._devices.find((x) => x.bindingRef === 'd_cur' + i);
+    if (d) layout[d.id] = { s: 'garden', x: 0.18 + i * 0.215, y: 0.5 };
+  });
+  c._layout = layout;
+  c._setMode('view'); c._space = 'garden';
+  c.requestUpdate();
+  await c.updateComplete;
+  const st = document.createElement('style');
+  st.textContent = '.activity-ring.transition i:first-child{animation-delay:-1.1s!important;animation-play-state:paused!important;}';
+  (c.shadowRoot || c.renderRoot).appendChild(st);
+}, STATES);
+await page.waitForTimeout(500);
+// captions under each badge, so the four states are readable in the file
+const box = await page.evaluate((STATES) => {
+  const c = window.__card;
+  const els = [...(c.shadowRoot || c.renderRoot).querySelectorAll('.devlayer .dev')]
+    .sort((a, b) => a.getBoundingClientRect().x - b.getBoundingClientRect().x);
+  let minX = 1e9, maxX = -1e9, minY = 1e9, maxY = -1e9;
+  els.forEach((el, i) => {
+    const r = el.getBoundingClientRect();
+    const cap = document.createElement('div');
+    cap.textContent = STATES[i];
+    cap.style.cssText = `position:fixed;left:${r.x + r.width / 2}px;top:${r.y + r.height + 10}px;`
+      + 'transform:translateX(-50%);font:600 13px system-ui,sans-serif;color:#1c2530;'
+      + 'letter-spacing:.02em;z-index:9999;padding:2px 7px;border-radius:6px;'
+      + 'background:rgba(255,255,255,0.88);white-space:nowrap;';
+    document.body.appendChild(cap);
+    minX = Math.min(minX, r.x); maxX = Math.max(maxX, r.x + r.width);
+    minY = Math.min(minY, r.y); maxY = Math.max(maxY, r.y + r.height);
+  });
+  return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+}, STATES);
+const pad = 55;
+await page.screenshot({ path: process.argv[2] || '/tmp/cover_states.png',
+  clip: { x: Math.max(0, box.x - pad), y: Math.max(0, box.y - pad),
+    width: box.w + pad * 2, height: box.h + pad * 2 + 22 } });
+await browser.close();
+console.log('shot ok');

demo/shot_daynight.mjs

@@ -0,0 +1,36 @@
+// Three stills of the daynight scale (noon/sunset/night) for the white-day review.
+import { launch } from './serve.mjs';
+const outDir = process.argv[2] || '/tmp';
+const { page, browser } = await launch({ width: 700, height: 700 }, 1);
+await page.emulateMedia({ reducedMotion: 'reduce' });
+await page.evaluate(async () => {
+  const c = window.__card;
+  const sp = c._serverCfg.spaces.find((s) => s.id === 'f1');
+  sp.openings = [
+    { id: 'wN', type: 'window', x: 0.30, y: 0.14, angle: 0, length: 0.08 },
+    { id: 'wE', type: 'window', x: 0.96, y: 0.60, angle: 90, length: 0.08 },
+    { id: 'wW', type: 'window', x: 0.04, y: 0.30, angle: 90, length: 0.08 },
+  ];
+  sp.plan_url = ''; // hand-drawn plan: white paper — the risky case for a white day
+  sp.settings = { ...(sp.settings || {}), show_borders: true, fill_mode: 'glow' };
+  c._serverCfg.settings = { ...(c._serverCfg.settings || {}), north_deg: 0, sun_rays: true, bg_mode: 'daynight' };
+  c._cfgRev = (c._cfgRev || 0) + 1;
+});
+const shot = async (az, el, name) => {
+  await page.evaluate(async ([az, el]) => {
+    const c = window.__card;
+    c.hass = { ...c.hass, states: { ...c.hass.states, 'sun.sun': {
+      entity_id: 'sun.sun', state: el > 0 ? 'above_horizon' : 'below_horizon',
+      attributes: { azimuth: az, elevation: el },
+    } } };
+    c.requestUpdate(); await c.updateComplete;
+  }, [az, el]);
+  await page.waitForTimeout(300);
+  const stage = await page.evaluateHandle(() => window.__card.shadowRoot.querySelector('.stage'));
+  await stage.asElement().screenshot({ path: `${outDir}/${name}.png` });
+};
+await shot(180, 60, 'dn_noon');
+await shot(265, 3, 'dn_sunset');
+await shot(0, -20, 'dn_night');
+await browser.close();
+console.log('shots done');

demo/shot_furniture.mjs

@@ -0,0 +1,63 @@
+// Скриншоты библиотеки мебели: палитра и расставленная мебель на плане.
+import { launch } from './serve.mjs';
+const OUT = process.env.HP_SHOT_DIR || '/tmp';
+const { page, browser } = await launch({ width: 900, height: 900 }, 2);
+
+await page.evaluate(async () => {
+  const c = window.__card;
+  const sr = c.shadowRoot || c.renderRoot;
+  sr.querySelectorAll('.modetab')[2].click();
+  await c.updateComplete;
+  c._curSpaceCfg.decor = [];
+  c._decorTool = 'furniture';
+  c._cfgEpoch++; c.requestUpdate();
+  await c.updateComplete;
+  sr.querySelector('.furnitem[data-symbol="sofa"]').click();
+  await c.updateComplete;
+});
+await page.waitForTimeout(400);
+await page.screenshot({ path: `${OUT}/furniture_palette.png` });
+
+await page.evaluate(async () => {
+  const c = window.__card;
+  const P = 1000 / 240;
+  const cm = (v) => (v / 5) * P / 1000;                 // cm -> normalised
+  const put = (id, symbol, w, h, cx, cy, angle) => ({
+    id, kind: 'furniture', symbol,
+    x: cx / 1000 - cm(w) / 2, y: cy / 1000 - cm(h) / 2,
+    w: cm(w), h: cm(h), color: '#8d6e63', width: 3,
+    ...(angle ? { angle } : {}),
+  });
+  // r1 living 40..550 x 140..580 | r2 kitchen 550..960 x 140..460
+  // r3 bedroom 550..960 x 460..860 | r4 hall 40..550 x 580..860
+  c._curSpaceCfg.decor = [
+    put('f1', 'sofa', 220, 90, 250, 140 + 37.5),
+    put('f2', 'coffee_table', 110, 60, 250, 300),
+    put('f3', 'tv', 120, 30, 250, 570),
+    put('f4', 'armchair', 90, 85, 90, 340, 90),
+    put('f5', 'table_dining', 140, 80, 700, 300),
+    put('f6', 'chair', 45, 45, 700, 240),
+    put('f7', 'chair', 45, 45, 700, 360, 180),
+    put('f8', 'fridge', 60, 65, 590, 140 + 27, 0),
+    put('f9', 'stove', 60, 60, 670, 140 + 25),
+    put('f10', 'kitchen_sink', 80, 60, 760, 140 + 25),
+    put('f11', 'dishwasher', 60, 60, 840, 140 + 25),
+    put('f12', 'bed_double', 160, 200, 700, 460 + 42),
+    put('f13', 'nightstand', 45, 40, 620, 470),
+    put('f14', 'nightstand', 45, 40, 780, 470),
+    put('f15', 'wardrobe', 100, 60, 910, 700, 90),
+    put('f16', 'washer', 60, 60, 120, 860 - 25, 180),
+    put('f17', 'toilet', 40, 70, 220, 860 - 29, 180),
+    put('f18', 'bathtub', 170, 75, 400, 860 - 31, 180),
+    put('f19', 'plant', 40, 40, 500, 620),
+    put('f20', 'shower', 90, 90, 490, 700),
+  ];
+  c._decorTool = 'select';
+  c._decorSel = 'f1';
+  c._cfgEpoch++; c.requestUpdate();
+  await c.updateComplete;
+});
+await page.waitForTimeout(500);
+await page.screenshot({ path: `${OUT}/furniture_plan.png` });
+await browser.close();
+console.log('shots written to', OUT);

demo/shot_motion_sense.mjs

@@ -0,0 +1,34 @@
+import { launch } from './serve.mjs';
+const { page, browser } = await launch({ width: 820, height: 760 }, 2);
+await page.evaluate(async () => {
+  const c = window.__card;
+  c._serverCfg.markers = (c._serverCfg.markers || []).filter((m) => m.binding !== 'device:d_motion');
+  c._serverCfg.markers.push({ id: 'd_motion', binding: 'device:d_motion', display: 'icon_ripple' });
+  c._cfgEpoch++; c._regSignature = ''; c._maybeRebuildDevices();
+  // the flash is keyed to a WITNESSED off→on transition (owner's rule
+  // 2026-08-01: разовая вспышка в момент обнаружения) — cycle through off
+  const set = async (state) => {
+    c.hass = { ...c.hass, states: { ...c.hass.states,
+      'binary_sensor.hall_motion': { entity_id: 'binary_sensor.hall_motion', state,
+        attributes: { friendly_name: 'Motion', device_class: 'motion', linkquality: 64 } } } };
+    await c.updateComplete;
+  };
+  await set('off');
+  await set('on');
+  // freeze the pulse at a visible frame for a deterministic capture
+  const st = document.createElement('style');
+  st.textContent = '.activity-ring.event i{animation-delay:-0.4s!important;animation-play-state:paused!important;}';
+  (c.shadowRoot || c.renderRoot).appendChild(st);
+});
+await page.waitForTimeout(300);
+const box = await page.evaluate(() => {
+  const c = window.__card;
+  const el = (c.shadowRoot || c.renderRoot).querySelector('.dev.activity-event');
+  const r = el.getBoundingClientRect();
+  return { x: r.x, y: r.y, w: r.width, h: r.height };
+});
+const pad = 70;
+await page.screenshot({ path: process.argv[2] || '/tmp/motion_sense.png',
+  clip: { x: Math.max(0, box.x - pad), y: Math.max(0, box.y - pad), width: box.w + pad * 2, height: box.h + pad * 2 } });
+await browser.close();
+console.log('shot ok');

demo/shot_opening_place.mjs

@@ -0,0 +1,27 @@
+// Capture: the shoulder rulers + centre tick while PLACING a new opening
+// (Opening tool, cursor hovering the wall centre) — owner 2026-08-03.
+import { launch } from './serve.mjs';
+const { page, browser } = await launch({ width: 900, height: 820 }, 2);
+await page.evaluate(() => {
+  const c = window.__card;
+  const sp = c._serverCfg.spaces.find((s) => s.id === 'f1');
+  sp.openings = [];
+  c._setMode('plan'); c._tool = 'opening';
+  c._cfgEpoch++; c.requestUpdate();
+  return c.updateComplete && true;
+});
+await page.waitForTimeout(300);
+const pt = await page.evaluate(() => {
+  const c = window.__card;
+  const stage = c.renderRoot.querySelector('.stage');
+  const r = stage.getBoundingClientRect();
+  const [vx, vy, vw, vh] = stage.querySelector('svg').getAttribute('viewBox').split(' ').map(Number);
+  return { x: r.left + ((293.7 - vx) / vw) * r.width, y: r.top + ((141 - vy) / vh) * r.height,
+    sx: r.left, sy: r.top, sw: r.width, sh: r.height };
+});
+await page.mouse.move(pt.x, pt.y, { steps: 4 });
+await page.waitForTimeout(300);
+await page.screenshot({ path: process.argv[2] || '/tmp/opening_place.png',
+  clip: { x: pt.sx, y: pt.sy, width: pt.sw, height: Math.min(pt.sh, 420) } });
+await browser.close();
+console.log('shot ok');

demo/shot_room_joins.mjs

@@ -0,0 +1,45 @@
+// Owner 2026-08-04: «углы границ комнат всё ещё с зубцами». A miter join on a
+// sharp corner shoots a spike far past the walls that meet there; past the
+// miter limit it flips to a flat bevel. Room borders now join round, like the
+// decor lines already did. Two rooms make the defect obvious: an L (a concave
+// 90° corner plus the convex ones) and a wedge with a ~45° apex — the angle
+// where the miter spike is longest before the miter limit clips it to a bevel.
+// Usage: node demo/shot_room_joins.mjs <outdir> <name>
+import { launch } from './serve.mjs';
+const outDir = process.argv[2] || '/tmp';
+const name = process.argv[3] || 'room_joins';
+const { page, browser } = await launch({ width: 900, height: 820 }, 6);
+await page.emulateMedia({ reducedMotion: 'reduce' });
+
+await page.evaluate(async () => {
+  const c = window.__card;
+  const sp = c._serverCfg.spaces.find((s) => s.id === 'f1');
+  delete sp.plan_url;
+  sp.rooms = [
+    { id: 'rL', name: '', area: 'living_room',
+      poly: [[0.06, 0.04], [0.52, 0.04], [0.52, 0.14], [0.94, 0.14], [0.94, 0.26], [0.06, 0.26]] },
+    { id: 'rW', name: '', area: 'kitchen',
+      poly: [[0.20, 0.318], [0.90, 0.55], [0.20, 0.782]] },
+  ];
+  sp.settings = { ...(sp.settings || {}), show_borders: true, show_names: false,
+    fill_mode: 'none', room_color: '#3ea6ff', room_opacity: 1 };
+  c._cfgEpoch = (c._cfgEpoch || 0) + 1;
+  c.requestUpdate();
+  await c.updateComplete;
+});
+await page.waitForTimeout(300);
+// crop tight around the wedge's ~28° apex: at plan scale the whole stage hides
+// a 5-unit spike, and the spike is the entire point of the shot
+const box = await page.evaluate(() => {
+  const c = window.__card;
+  const svg = c.shadowRoot.querySelector('.stage svg');
+  const poly = [...svg.querySelectorAll('polygon.room')].pop();
+  const pts = poly.getAttribute('points').split(' ').map((s) => s.split(',').map(Number));
+  const apex = pts.reduce((m, p) => (p[0] > m[0] ? p : m), pts[0]);
+  const m = svg.getScreenCTM();
+  return { x: m.a * apex[0] + m.c * apex[1] + m.e, y: m.b * apex[0] + m.d * apex[1] + m.f };
+});
+await page.screenshot({ path: `${outDir}/${name}.png`,
+  clip: { x: box.x - 62, y: box.y - 30, width: 72, height: 60 } });
+await browser.close();
+console.log('shot written to ' + outDir + '/' + name + '.png');

demo/shot_sun.mjs

@@ -0,0 +1,53 @@
+// Screenshots for docs/SUN.md: evening wedges over the glow fill + the compass
+// dial in the general settings. Usage: node demo/shot_sun.mjs <outdir>
+import { launch } from './serve.mjs';
+const outDir = process.argv[2] || '/tmp';
+const { page, browser } = await launch({ width: 900, height: 860 }, 2);
+// instant colors for the still shot: the day/night transition is tens of seconds
+await page.emulateMedia({ reducedMotion: 'reduce' });
+
+await page.evaluate(async () => {
+  const c = window.__card;
+  const sp = c._serverCfg.spaces.find((s) => s.id === 'f1');
+  sp.openings = [
+    { id: 'wN', type: 'window', x: 0.30, y: 0.14, angle: 0, length: 0.08 },
+    { id: 'wE', type: 'window', x: 0.96, y: 0.60, angle: 90, length: 0.08 },
+    { id: 'wS', type: 'window', x: 0.30, y: 0.86, angle: 0, length: 0.08 },
+    { id: 'wW', type: 'window', x: 0.04, y: 0.30, angle: 90, length: 0.08 },
+    { id: 'wW2', type: 'window', x: 0.04, y: 0.72, angle: 90, length: 0.08 },
+  ];
+  sp.settings = { ...(sp.settings || {}), show_borders: true, fill_mode: 'glow' };
+  c._serverCfg.settings = {
+    ...(c._serverCfg.settings || {}),
+    north_deg: 0, sun_rays: true, bg_mode: 'daynight',
+  };
+  c._cfgRev = (c._cfgRev || 0) + 1;
+  // a warm evening: the sun low in the west; the living-room light off so
+  // the glow pool does not swamp the west wedge
+  c.hass = { ...c.hass, states: { ...c.hass.states,
+    'light.ceiling': { ...c.hass.states['light.ceiling'], state: 'off' },
+    'sun.sun': {
+      entity_id: 'sun.sun', state: 'above_horizon', attributes: { azimuth: 265, elevation: 3 },
+    },
+  } };
+  c.requestUpdate();
+  await c.updateComplete;
+});
+await page.waitForTimeout(400);
+const stage = await page.evaluateHandle(() => window.__card.shadowRoot.querySelector('.stage'));
+await stage.asElement().screenshot({ path: outDir + '/sun_rays.png' });
+
+await page.evaluate(async () => {
+  const c = window.__card;
+  c._openSettingsDialog();
+  c._settingsDialog = { ...c._settingsDialog, northDeg: 330 };
+  c.requestUpdate();
+  await c.updateComplete;
+  c.shadowRoot.querySelector('.compass').scrollIntoView({ block: 'center' });
+});
+await page.waitForTimeout(200);
+const dlg = await page.evaluateHandle(() => window.__card.shadowRoot
+  .querySelector('hp-dialog').shadowRoot.querySelector('.surface'));
+await dlg.asElement().screenshot({ path: outDir + '/sun_compass.png' });
+await browser.close();
+console.log('shots written to ' + outDir);

demo/shot_sun_bright.mjs

@@ -0,0 +1,46 @@
+// Brightness check for the wedges (owner 2026-08-03: «поярче, иногда плохо
+// видны»). Two hardest cases side by side: a DAYLIGHT sun on white paper (the
+// wedge colour is nearly neutral there) and a low sun over the dark glow
+// canvas. Usage: node demo/shot_sun_bright.mjs <outdir> [suffix]
+import { launch } from './serve.mjs';
+const outDir = process.argv[2] || '/tmp';
+const tag = process.argv[3] ? '_' + process.argv[3] : '';
+const { page, browser } = await launch({ width: 900, height: 860 }, 2);
+// the fade is a 2 s animation; reduced motion pins the layer at full opacity
+await page.emulateMedia({ reducedMotion: 'reduce' });
+
+const setup = (fill, azimuth, elevation, ceiling) => page.evaluate(async ([fill, azimuth, elevation, ceiling]) => {
+  const c = window.__card;
+  const sp = c._serverCfg.spaces.find((s) => s.id === 'f1');
+  sp.openings = [
+    { id: 'wN', type: 'window', x: 0.30, y: 0.14, angle: 0, length: 0.08 },
+    { id: 'wE', type: 'window', x: 0.96, y: 0.60, angle: 90, length: 0.08 },
+    { id: 'wS', type: 'window', x: 0.30, y: 0.86, angle: 0, length: 0.08 },
+    { id: 'wW', type: 'window', x: 0.04, y: 0.30, angle: 90, length: 0.08 },
+    { id: 'wW2', type: 'window', x: 0.04, y: 0.72, angle: 90, length: 0.08 },
+  ];
+  sp.settings = { ...(sp.settings || {}), show_borders: true, fill_mode: fill };
+  c._serverCfg.settings = { ...(c._serverCfg.settings || {}),
+    north_deg: 0, sun_rays: true, bg_mode: 'daynight' };
+  c._cfgEpoch++;
+  c.hass = { ...c.hass, states: { ...c.hass.states,
+    'light.ceiling': { ...c.hass.states['light.ceiling'], state: ceiling },
+    'sun.sun': { entity_id: 'sun.sun', state: 'above_horizon', attributes: { azimuth, elevation } } } };
+  c.requestUpdate();
+  await c.updateComplete;
+}, [fill, azimuth, elevation, ceiling]);
+
+const shoot = async (name) => {
+  await page.waitForTimeout(400);
+  const stage = await page.evaluateHandle(() => window.__card.shadowRoot.querySelector('.stage'));
+  await stage.asElement().screenshot({ path: `${outDir}/${name}${tag}.png` });
+};
+
+// 1) plain daylight on white paper: neutral wedge colour, brightest canvas
+await setup('none', 265, 24, 'off');
+await shoot('sun_bright_paper');
+// 2) a low warm sun over the dark glow canvas
+await setup('glow', 265, 4, 'off');
+await shoot('sun_bright_glow');
+await browser.close();
+console.log('shots written to ' + outDir);