docs: review document for #107

Issue: #107
User-Visible: no

.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

.githooks/commit-msg

@@ -0,0 +1,14 @@
+#!/bin/sh
+set -eu
+
+message_file=$1
+
+# Git-generated merge commits do not represent an independently authored
+# product change and inherit provenance from their parents.
+case "${message_file##*/}" in
+  MERGE_MSG) exit 0 ;;
+esac
+
+repo_root=$(git rev-parse --show-toplevel)
+node "$repo_root/scripts/validate-commit-provenance.mjs" \
+  --message-file "$message_file" --staged --check-hook-mode

.githooks/pre-push

@@ -0,0 +1,80 @@
+#!/bin/sh
+set -eu
+
+# PROCESS.md 10.1: the blocking process gate lives here, because commits go
+# straight to dev without pull requests and GitHub blocks nothing on its side.
+# CI still runs the same script (10.3), but by then the code is already in dev —
+# that catch-up pass reports, it does not prevent.
+#
+# Git feeds one line per ref on stdin:
+#   <local ref> <local sha> <remote ref> <remote sha>
+
+repo_root=$(git rev-parse --show-toplevel)
+gate="$repo_root/scripts/process-gate.mjs"
+zero=$(printf '%040d' 0)
+
+# The gate reasons about commits. A repository without it — an old checkout, a
+# bisect, a worktree from before the script existed — must still be pushable.
+if [ ! -f "$gate" ]; then
+  exit 0
+fi
+
+# Reading issue status needs gh, and a hook that cannot work on a train is a
+# hook people disable. Offline the checks that need no network still run, and the
+# strict pass happens in CI, where gh is always present.
+issues_flag=""
+if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+  issues_flag="--issues"
+else
+  echo "process-gate: gh недоступен, проверка статуса issue пропущена — её выполнит CI" >&2
+fi
+
+status=0
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  # Deleting a remote branch pushes nothing to examine.
+  if [ "$local_sha" = "$zero" ]; then
+    continue
+  fi
+
+  # Tags carry no process state of their own: the commit they point at was
+  # already checked when it was pushed.
+  case "$local_ref" in
+    refs/tags/*) continue ;;
+  esac
+
+  if [ "$remote_sha" = "$zero" ]; then
+    # A branch that does not exist on the remote yet. Everything it adds on top
+    # of dev is new, so that is the range — not the whole history, which would
+    # drag in every violation committed before the gate existed.
+    base=$(git merge-base "$local_sha" refs/remotes/origin/dev 2>/dev/null || true)
+    if [ -z "$base" ]; then
+      echo "process-gate: не нашёл общего предка с origin/dev, проверяю последние 20 коммитов" >&2
+      base="$local_sha~20"
+    fi
+  else
+    base="$remote_sha"
+  fi
+
+  echo "process-gate: $local_ref, диапазон ${base}..${local_sha}" >&2
+  # shellcheck disable=SC2086
+  if ! node "$gate" --range "${base}..${local_sha}" --target-ref "$remote_ref" $issues_flag >&2; then
+    status=1
+  fi
+done
+
+if [ "$status" -ne 0 ]; then
+  cat >&2 <<'EOF'
+
+Push остановлен: нарушен процесс (PROCESS.md §10.2).
+
+Починить надо причину, а не симптом. Если нарушение уже опубликовано, его
+исправляет следующий коммит плюс issue с меткой `process` — не force-push
+(§12, правило 17).
+
+Обойти проверку можно через `git push --no-verify`, и тогда то же самое найдёт
+job `process-gate` в Validate — уже после того, как код окажется в dev.
+EOF
+fi
+
+exit "$status"

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Telegram chat (@ha_houseplan)
+    url: https://t.me/ha_houseplan
+    about: Questions, setup help, ideas and screenshots — the fastest way to get an answer.
+  - name: 💡 GitHub discussions
+    url: https://github.com/Matysh/houseplan-card/discussions
+    about: Longer-form ideas and show-and-tell.

.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/mutation-gate.yml

@@ -0,0 +1,61 @@
+name: Mutation gate
+
+# Реестр известных поломок (issue #85): каждый мутант ломает продуктовый код
+# известным способом, и объявленный тест ОБЯЗАН на этом покраснеть. Тест,
+# оставшийся зелёным на сломанном коде, ничего не защищает — он лишь выглядит
+# защитой, и это хуже его отсутствия.
+#
+# Прогон дорогой: пересборка бандла на каждого мутанта. Поэтому он не входит в
+# Validate и не идёт на каждый push. Его место — перед стабильным релизом
+# (PROCESS.md §8) и раз в неделю по расписанию, чтобы дрейф тестов не копился
+# до релиза. Дешёвая половина — «якоря патчей живы, guard-файлы существуют» —
+# идёт с обычными юнитами: test/mutation-gate.test.mjs.
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Понедельник, 05:20 UTC — до начала рабочего дня владельца.
+    - cron: '20 5 * * 1'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: mutation-gate
+  cancel-in-progress: true
+
+jobs:
+  mutants:
+    runs-on: ubuntu-latest
+    # Шесть мутантов × (сборка + браузерный смок) — это десятки минут, и это
+    # нормально: гейт предрелизный. Час — потолок против зависшего Chromium.
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: dev
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
+      - name: Установить Chromium
+        if: steps.pw.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+      - name: Реестр применим к текущему коду
+        run: node scripts/mutation-gate.mjs --check
+
+      - name: Каждый тест ловит свою поломку
+        run: node scripts/mutation-gate.mjs

.github/workflows/performance.yml

@@ -0,0 +1,175 @@
+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:large-house-isometric -- --target-root=../baseline --samples=7 --warmups=1 --output=../artifacts/performance/isometric-baseline.json
+          npm run benchmark:large-house-isometric -- --target-root=. --samples=7 --warmups=1 --output=../artifacts/performance/isometric-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-house-isometric.json --baseline=../artifacts/performance/isometric-baseline.json --candidate=../artifacts/performance/isometric-candidate.json --output=../artifacts/performance/isometric-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/process.yml

@@ -0,0 +1,456 @@
+name: Process
+
+# Событийный конвейер процесса (PROCESS.md). Смена статусной метки — это
+# сообщение: она порождает событие, событие запускает следующий шаг.
+#
+# S4-spec-review -> ревью ТЗ    -> S5-ready | S3-spec
+# S7-code-review -> код-ревью   -> слияние в dev -> S8-merged | S6-in-progress
+#
+# Три вещи, без которых конвейер молча не работает:
+#
+# 1. Метки переставляются токеном HP_PROCESS_TOKEN, а не GITHUB_TOKEN. GitHub
+#    намеренно не запускает workflow от событий, вызванных GITHUB_TOKEN, чтобы
+#    не было циклов — цепочка оборвалась бы после первого шага.
+# 2. Этот файл обязан лежать в ветке по умолчанию (main). Для события `issues`
+#    GitHub берёт workflow только оттуда, независимо от того, что в dev.
+# 3. Многострочный текст внутри `run:` — только через heredoc. Строка с нулевым
+#    отступом обрывает блок YAML, и скрипт обрезается без ошибки парсера.
+#    Проверять не только YAML, но и каждый `run` через `bash -n`.
+
+on:
+  issues:
+    types: [labeled]
+
+concurrency:
+  # Два события по одному issue не должны запускать два прогона.
+  group: process-issue-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+  # Обязательно: claude-code-action получает OIDC-токен для авторизации
+  # GitHub App. Без этого прогон падает с «Could not fetch an OIDC token».
+  id-token: write
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    outputs:
+      stage: ${{ steps.decide.outputs.stage }}
+      cycle: ${{ steps.decide.outputs.cycle }}
+      limit: ${{ steps.decide.outputs.limit }}
+    steps:
+      - id: decide
+        env:
+          GH_TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          LABEL: ${{ github.event.label.name }}
+          BLOCKED: ${{ contains(github.event.issue.labels.*.name, 'blocked') }}
+          EXHAUSTED: ${{ contains(github.event.issue.labels.*.name, 'review-4') }}
+          SMALL: ${{ contains(github.event.issue.labels.*.name, 'small') }}
+          TRIVIAL: ${{ contains(github.event.issue.labels.*.name, 'trivial') }}
+          NUM: ${{ github.event.issue.number }}
+        run: |
+          # Этап определяется первым: от него зависит, какие вердикты считать.
+          stage=""; marker=""
+          case "$LABEL" in
+            S4-spec-review) stage="spec"; marker="SPEC-REVIEW" ;;
+            S7-code-review) stage="code"; marker="CODE-REVIEW" ;;
+            *) echo "метка $LABEL конвейер не запускает" ;;
+          esac
+
+          # Лимит циклов: 4 обычный, 2 на лёгком и коротком треке (PROCESS.md §4).
+          limit=4
+          if [ "$SMALL" = "true" ] || [ "$TRIVIAL" = "true" ]; then limit=2; fi
+
+          # Счётчик считает вердикты ТОЛЬКО своего этапа. Раньше он брал все
+          # подряд, и вердикт по ТЗ съедал цикл из бюджета код-ревью: на #89
+          # первое код-ревью получило r2/4. На задаче с двумя циклами ТЗ второе
+          # код-ревью упиралось бы в review-4 после одной правки.
+          #
+          # Этап опознаётся по имени документа в теле комментария. Если документа
+          # нет, вердикт не посчитается — недосчёт даёт лишний цикл, а перерасчёт
+          # остановил бы работу досрочно; из двух ошибок выбрана обратимая.
+          done_cycles=0
+          if [ -n "$stage" ]; then
+            done_cycles=$(gh issue view "$NUM" --repo "${{ github.repository }}" \
+              --json comments \
+              -q "[.comments[] | select(.body | test(\"Вердикт:\")) | select(.body | test(\"$marker\"))] | length")
+          fi
+
+          # Отказ обязан быть виден в issue, а не только в логе прогона.
+          # Ревьюшная метка обещает работу; если конвейер её не начал и промолчал,
+          # задача стоит в этом статусе бесконечно и никто об этом не узнаёт.
+          # Так и вышло на #123: чужой issue довели до S4-spec-review, guard
+          # отказался за 9 секунд, и в issue не было ни слова.
+          #
+          # Пишем только когда пытались запустить ревью, то есть stage опознан.
+          # Иначе комментарий уходил бы на каждую смену любой метки.
+          refuse() {
+            echo "$1"
+            gh issue comment "$NUM" --repo "${{ github.repository }}" --body \
+              "Конвейер ревью не запущен: $2
+
+          Метка \`$LABEL\` обещает работу, которая не начнётся, поэтому статус лучше вернуть в предыдущий — иначе задача простоит здесь бесконечно. [Прогон](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})."
+            stage=""
+          }
+
+          # Автор issue здесь не проверяется (решение владельца 2026-08-13).
+          # Проверка стоит на входе в процесс, а не на каждом шаге: как только
+          # задача получила статусную метку, она в работе, и кто её завёл — не
+          # имеет значения. Само присвоение метки и есть явное подтверждение
+          # владельца, причём проверенное платформой: метки может ставить только
+          # тот, у кого есть право записи в репозиторий. Прежняя проверка здесь
+          # дублировала эту гарантию и заставляла переоформлять чужие отчёты
+          # своими issue — чистая работа впустую, как на #123.
+          if [ -z "$stage" ]; then
+            :
+          elif [ "$BLOCKED" = "true" ]; then
+            refuse "стоит blocked — конвейер не запускается" \
+              "на issue стоит \`blocked\` — задача ждёт внешнего решения. Снять метку, когда решение принято."
+          elif [ "$EXHAUSTED" = "true" ]; then
+            refuse "стоит review-4 — решение за владельцем" \
+              "на issue стоит \`review-4\`: лимит циклов ревью исчерпан, дальше решает владелец — разделить задачу, отклонить или арбитраж (PROCESS.md §4)."
+          elif [ "$done_cycles" -ge "$limit" ]; then
+            echo "циклов этапа $stage пройдено $done_cycles из $limit — лимит исчерпан"
+            gh issue edit "$NUM" --repo "${{ github.repository }}" --add-label review-4
+            gh issue comment "$NUM" --repo "${{ github.repository }}" --body \
+              "Лимит циклов ревью исчерпан ($done_cycles из $limit на этапе \`$stage\`). Пятого захода нет: решение владельца — разделить задачу, отклонить или арбитраж (PROCESS.md §4)."
+            stage=""
+          else
+            echo "этап $stage, цикл $((done_cycles + 1)) из $limit"
+          fi
+          echo "stage=$stage" >> "$GITHUB_OUTPUT"
+          echo "cycle=$((done_cycles + 1))" >> "$GITHUB_OUTPUT"
+          echo "limit=$limit" >> "$GITHUB_OUTPUT"
+
+  review:
+    needs: guard
+    if: needs.guard.outputs.stage != ''
+    runs-on: ubuntu-latest
+    # Время — единственный настоящий ограничитель зациклившегося прогона.
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: dev
+
+      # Окружение готовит workflow, а не модель своими ходами. Раньше промпт
+      # велел ревьюеру самому выполнить `npm ci`: минуты уходили на установку без
+      # кэша, платились из бюджета 45 минут и из лимитов подписки, а ходы модели
+      # тратились на работу инфраструктуры. В validate.yml кэш стоит на всех
+      # тяжёлых job, здесь его не было.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      # Материал ревью живёт в ветке задачи: ТЗ в docs/specs/ и код коммитятся
+      # в issue/<NN>-slug. Если ветка запушена — переключаемся на неё, иначе
+      # ревьюер прочтёт dev и не найдёт того, что должен оценивать.
+      - name: Перейти на ветку задачи
+        id: branch
+        env:
+          NUM: ${{ github.event.issue.number }}
+        run: |
+          branch=$(git ls-remote --heads origin "issue/${NUM}-*" \
+            | head -1 | sed 's|.*refs/heads/||')
+          if [ -n "$branch" ]; then
+            git checkout -q "origin/$branch"
+            echo "материал ревью: ветка $branch, $(git rev-parse --short HEAD)"
+            echo "name=$branch" >> "$GITHUB_OUTPUT"
+          else
+            echo "::warning::ветка issue/${NUM}-* не найдена на origin — ревью пойдёт по dev"
+            echo "МАТЕРИАЛ НЕ ЗАПУШЕН" >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      # Зависимости ставятся ПОСЛЕ переключения на ветку задачи: lockfile мог
+      # измениться именно в ней, и установка по копии из dev дала бы не то дерево.
+      - name: Установить зависимости
+        run: npm ci
+
+      # Браузер нужен не всякому ревью (см. правило выбора гейтов в промпте),
+      # но когда нужен — качать его заново дороже, чем держать в кэше.
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
+      - name: Установить Chromium
+        if: steps.pw.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+      - name: Review
+        id: review
+        uses: anthropics/claude-code-action@v1
+        with:
+          # Подписка, а не отдельный счёт API: токен выпускается через
+          # `claude setup-token` (Pro/Max). Действуют лимиты подписки.
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            Ты ревьюер проекта House Plan. Язык ответа — русский.
+
+            Issue: #${{ github.event.issue.number }}
+            Репозиторий: ${{ github.repository }}
+            Этап: ${{ needs.guard.outputs.stage }}
+              spec — ревью ТЗ (PROCESS.md §2.4)
+              code — код-ревью (PROCESS.md §2.7)
+
+            Прочитай в этом порядке, прежде чем судить:
+              1. docs/SCOPE.md — зачем продукт существует и для кого. Он
+                 ограничитель: «features are built, improved and accepted only
+                 if they serve a job listed here». Первый вопрос к задаче —
+                 какую строку Core user jobs она закрывает.
+              2. AGENTS.md и PROCESS.md — процесс, классы изменений, трейлеры,
+                 лимит циклов, формат вердикта.
+              3. Тело issue #${{ github.event.issue.number }} и все комментарии.
+              4. Если меняется видимое поведение — docs/USER-GUIDE.ru.md:
+                 терминология интерфейса берётся оттуда, а не изобретается.
+              5. Канонический документ затронутой подсистемы: docs/SUN.md,
+                 LIGHT.md, CANVAS.md, WALL-THICKNESS.md, UX-MODES.md,
+                 CONFIG-COMPATIBILITY.md, TOUCH-SUPPORT.md.
+
+            Для этапа spec: если issue помечен small, ТЗ живёт в теле issue и
+            файла в docs/specs/ быть не должно. Иначе ТЗ — docs/specs/<NN>-*.md.
+            Проверь обязательные разделы §7.1, однозначность каждого AC и
+            указание способа доказательства. Отдельно проверь, что автор не
+            выдал догадку за решение: утверждение о поведении, которого нет ни
+            в одном документе и которое не помечено как предположение, —
+            замечание. Не бывает сложной задачи без единого открытого вопроса.
+
+            Владельцу задаются только продуктовые вопросы: что человек видит или
+            делает и каков объём видимых изменений в этом issue. Технический
+            вопрос, вынесенный владельцу, — тоже замечание: ты его снимаешь и
+            решаешь по существу в своём вердикте.
+
+            Для этапа code: материал — диапазон `git log --oneline origin/dev..HEAD`
+            и `git diff origin/dev...HEAD`. Ручного тестирования в цикле нет,
+            поэтому именно ты отвечаешь на вопрос «оно вообще работает».
+            По каждому AC: либо он доказан автотестом и ты убедился, что тест
+            умеет падать, либо разобран по коду с явной записью «проверено
+            чтением, не исполнением». «Verified» без названной команды и её
+            результата доказательством не является. Зависимости уже установлены
+            workflow, Chromium тоже — `npm ci` выполнять не нужно. Проверь
+            трейлеры Issue и User-Visible, при User-Visible: yes — правки в оба
+            changelog в том же коммите.
+
+            **Объём гейтов соразмерен задаче.** Прогонять весь набор на каждой
+            правке — не тщательность, а потеря времени: полные наборы это
+            предрелизный гейт (PROCESS.md §8), а не гейт ревью.
+
+            Всегда, они дешёвые:
+              `npx tsc --noEmit`, `npm test`, `npm run build` со сверкой трёх
+              копий бандла.
+
+            По необходимости, и «необходимость» определяется diff'ом и AC:
+              - браузерные смоки `demo/smoke_*.mjs` — названные в AC плюс
+                относящиеся к тронутым поверхностям. Их 127; прогон всех уместен
+                только когда задача действительно задевает всё;
+              - `npm run golden:verify` — если diff может изменить видимый
+                результат: рендер, геометрия, стили, слои;
+              - `python -m pytest tests_backend -q` — если тронут
+                `custom_components/**/*.py`;
+              - performance-профили — если названы в AC либо тронуты
+                чувствительные к перфу пути.
+
+            Дисциплина «тест должен уметь падать» не отменяется, но применяется к
+            тем тестам, которые ты прогонял.
+
+            **В комментарии обязателен перечень: какие гейты прогнал, какие нет и
+            почему.** Это условие честности такого сужения: непрогнанный гейт
+            становится видимым решением, а не молчаливым пропуском. Раздел «чего
+            не проверял» в документе ревью — не формальность, а главный его
+            раздел на коротких задачах.
+
+            Ты НЕ правишь ни ТЗ, ни продуктовый код. Только оцениваешь.
+
+            Серьёзность: High блокирует; Medium обязан стать отдельным issue;
+            Low либо правится, либо снимается с записью. Жёлтый вердикт
+            допустим при полностью выполненных AC, если изменение не решает
+            заявленный сценарий или ухудшает смежный. Продуктовое рассуждение
+            расширяет вопросы, но не отменяет AC и не даёт права менять скоуп.
+
+            Каждую Medium-находку заведи отдельным issue со ссылкой на
+            #${{ github.event.issue.number }} и метками: тип, приоритет,
+            S1-new. «Оставили в тексте ревью» закрытием не считается и прямо
+            запрещено §12.
+
+            Напиши полный документ ревью в файл
+            docs/reviews/<SPEC|CODE>-REVIEW-${{ github.event.issue.number }}-r${{ needs.guard.outputs.cycle }}.md
+            (SPEC для этапа spec, CODE для code): скоуп, как проверялось,
+            находки с воспроизведением, что проверено и корректно, чего не
+            проверял. Каталог docs/reviews/ создай, если его нет. Больше не
+            пиши ничего: любой файл вне docs/reviews/ опубликован не будет.
+
+            Затем оставь в issue краткий комментарий: вердикт, ключевые находки
+            и ссылка на документ. Первой строкой — вердикт в формате §7.2:
+            `Вердикт: зелёный/жёлтый/красный · цикл r${{ needs.guard.outputs.cycle }}/${{ needs.guard.outputs.limit }} · High: N · Medium: N → #…`
+
+            Затем верни JSON по схеме. Это последнее действие и оно обязательно:
+            без него метка не переставится и конвейер встанет.
+          claude_args: |
+            --max-turns 150
+            --allowedTools Read,Write,Grep,Glob,Bash,mcp__github__add_issue_comment,mcp__github__issue_write,mcp__github__issue_read
+            --json-schema '{"type":"object","properties":{"verdict":{"type":"string","enum":["green","yellow","red"]},"high":{"type":"integer"},"medium":{"type":"integer"},"summary":{"type":"string"}},"required":["verdict","high","medium","summary"]}'
+
+      # Ревьюер пишет только в docs/reviews/. Что именно попадёт в коммит,
+      # решает этот шаг, а не модель: всё остальное откатывается.
+      - name: Опубликовать документ ревью
+        env:
+          TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          BRANCH: ${{ steps.branch.outputs.name }}
+          NUM: ${{ github.event.issue.number }}
+        run: |
+          # Ветки задачи может не быть: у задач, размеченных до появления
+          # конвейера, ТЗ лежит прямо в dev. Раньше шаг в этом случае молча
+          # выходил с нулём, и разбор ревью терялся — оставался только вердикт
+          # комментарием. Это тот же тихий отказ: шаг сообщал об успехе тем, что
+          # ничего не сделал. Документ ложится туда же, где лежит само ТЗ.
+          target="${BRANCH:-dev}"
+          if [ -z "$BRANCH" ]; then
+            echo "::warning::ветки задачи нет — документ ревью ляжет в dev"
+          fi
+          git checkout -- . 2>/dev/null || true
+          git clean -fd -e docs/reviews -e node_modules >/dev/null 2>&1 || true
+          git add docs/reviews 2>/dev/null || true
+          if git diff --cached --quiet; then
+            echo "::warning::документ ревью не создан"
+            exit 0
+          fi
+          git -c user.name="claude[bot]" \
+              -c user.email="209825114+claude[bot]@users.noreply.github.com" \
+              commit -q -F - <<EOF
+          docs: review document for #$NUM
+
+          Issue: #$NUM
+          User-Visible: no
+          EOF
+          # Публикация в dev идёт из детачнутого состояния поверх ветки задачи
+          # либо dev, поэтому push нужен с явным перебазированием при гонке:
+          # dev мог уйти вперёд, пока шло ревью — оно длится до 45 минут.
+          if ! git push -q "https://x-access-token:$TOKEN@github.com/${{ github.repository }}" \
+               "HEAD:$target"; then
+            git fetch -q origin "$target"
+            if ! git -c user.name="claude[bot]" \
+                     -c user.email="209825114+claude[bot]@users.noreply.github.com" \
+                     rebase "origin/$target"; then
+              git rebase --abort || true
+              echo "::error::документ ревью не удалось опубликовать в $target: конфликт"
+              exit 0
+            fi
+            git push -q "https://x-access-token:$TOKEN@github.com/${{ github.repository }}" \
+              "HEAD:$target"
+          fi
+          echo "документ опубликован в $target"
+
+      - name: Решение по вердикту
+        id: decide
+        env:
+          OUT: ${{ steps.review.outputs.structured_output }}
+          STAGE: ${{ needs.guard.outputs.stage }}
+        run: |
+          verdict=$(echo "$OUT" | jq -r '.verdict')
+          high=$(echo "$OUT" | jq -r '.high')
+          echo "вердикт: $verdict, High: $high"
+
+          # Вперёд двигает ТОЛЬКО зелёный. Жёлтый и красный возвращают
+          # автору: на прогоне #111 жёлтый означал, что AC описывает неверное
+          # изменение контракта — реализовать такое ТЗ значит сделать ошибку
+          # по инструкции. Оба считаются циклом.
+          if [ "$verdict" = "green" ] && [ "$high" -eq 0 ]; then
+            green=true
+            case "$STAGE" in
+              spec) from=S4-spec-review; to=S5-ready ;;
+              code) from=S7-code-review; to=S8-merged ;;
+            esac
+          else
+            green=false
+            case "$STAGE" in
+              spec) from=S4-spec-review; to=S3-spec ;;
+              code) from=S7-code-review; to=S6-in-progress ;;
+            esac
+          fi
+          echo "green=$green" >> "$GITHUB_OUTPUT"
+          echo "from=$from"   >> "$GITHUB_OUTPUT"
+          echo "to=$to"       >> "$GITHUB_OUTPUT"
+
+      # S8-merged утверждает, что код в dev. Значит слияние обязано произойти
+      # ДО метки, иначе она врёт в промежутке.
+      #
+      # При конфликте шаг НЕ падает и метку не оставляет на месте. Первая
+      # редакция делала именно так, и это оказалось тупиком: автор ждёт смену
+      # метки, метка не менялась, и он тридцать раз опрашивал впустую, чтобы
+      # затем отчитаться «лимит исчерпан» — при зелёном вердикте. Инвариант
+      # теперь жёстче: ПОСЛЕ ПРОГОНА РЕВЬЮ МЕТКА МЕНЯЕТСЯ ВСЕГДА.
+      - name: Слить ветку в dev
+        id: merge
+        if: needs.guard.outputs.stage == 'code' && steps.decide.outputs.green == 'true'
+        env:
+          TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          GH_TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          BRANCH: ${{ steps.branch.outputs.name }}
+          NUM: ${{ github.event.issue.number }}
+        run: |
+          if [ -z "$BRANCH" ]; then
+            echo "::error::ветки задачи нет — сливать нечего"
+            echo "merged=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git fetch -q origin dev
+          git checkout -q -B merge-into-dev "origin/$BRANCH"
+          if ! git -c user.name="claude[bot]" \
+                   -c user.email="209825114+claude[bot]@users.noreply.github.com" \
+                   rebase origin/dev; then
+            git rebase --abort || true
+            echo "merged=false" >> "$GITHUB_OUTPUT"
+            echo "::warning::ветка $BRANCH не сливается в dev без конфликта"
+            cat > /tmp/conflict.md <<EOF
+          **Код-ревью зелёное — вердикт выше в силе, переделывать работу не нужно.** Не удалось только слияние: ветка \`$BRANCH\` конфликтует с \`dev\`.
+
+          Задача переведена в \`S6-in-progress\`, потому что работа вернулась к автору. Осталась не правка кода, а ребейз:
+
+          1. \`git fetch origin\`, затем \`git rebase origin/dev\` в ветке задачи, разрешить конфликт;
+          2. запушить ветку;
+          3. вернуть метку \`S7-code-review\`.
+
+          Повторный прогон ревью — не формальность: после ребейза на новый \`dev\` это другой код, и принимать его без проверки нельзя. Цикл считается по этапу, лимит на код-ревью тратится отдельно от ревью ТЗ.
+          EOF
+            gh issue comment "$NUM" --repo "${{ github.repository }}" --body-file /tmp/conflict.md
+            exit 0
+          fi
+          git push -q "https://x-access-token:$TOKEN@github.com/${{ github.repository }}" HEAD:dev
+          echo "merged=true" >> "$GITHUB_OUTPUT"
+          echo "слито в dev: $(git rev-parse --short HEAD)"
+
+      - name: Переставить метку
+        env:
+          # Именно PAT: с GITHUB_TOKEN следующий шаг конвейера не запустится.
+          GH_TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          NUM: ${{ github.event.issue.number }}
+          FROM: ${{ steps.decide.outputs.from }}
+          # Зелёное код-ревью без слияния ведёт не в S8-merged, а обратно к
+          # автору: метка утверждала бы, что код в dev, а его там нет.
+          TO: ${{ (needs.guard.outputs.stage == 'code' && steps.decide.outputs.green == 'true' && steps.merge.outputs.merged != 'true') && 'S6-in-progress' || steps.decide.outputs.to }}
+        run: |
+          gh issue edit "$NUM" --repo "${{ github.repository }}" \
+            --add-label "$TO" --remove-label "$FROM"
+          echo "$FROM -> $TO"
+
+      - name: Позвать владельца, если ревью упало
+        if: failure()
+        env:
+          GH_TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          # Тело через heredoc, а не многострочный --body: строка с нулевым
+          # отступом обрывает блок YAML и оставляет незакрытую кавычку.
+          cat > /tmp/failure.md <<EOF
+          Автоматическое ревью не отработало: [прогон]($RUN_URL). Статусная метка не менялась, задача осталась на месте.
+
+          Если вердикт выше всё же опубликован — сбой произошёл после него. Перестановку метки в этом случае выполняет чат обслуживания или владелец, но не автор задачи: автор не толкует вердикт о своей же работе.
+          EOF
+          gh issue comment "${{ github.event.issue.number }}" \
+            --repo "${{ github.repository }}" --body-file /tmp/failure.md

.github/workflows/publish-prerelease.yml

@@ -0,0 +1,259 @@
+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,
+              );
+            }
+
+  # PROCESS.md 10.2 item 10: closing issues and stripping status labels happens
+  # because a beta was published, not because someone remembered to do it. The
+  # manual step was skipped twice, and both times it broke the invariant that a
+  # closed issue carries no status label — the one thing `verify` relies on.
+  #
+  # A manual step after a successful release is the worst kind: by the time it is
+  # due, the work already looks finished, which is exactly why it gets forgotten.
+  close-merged:
+    needs: [gate, publish]
+    if: ${{ needs.publish.outputs.newly_published == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Deliberately the stock token, not a PAT: events caused by GITHUB_TOKEN do
+      # not start workflows, so removing the label cannot wake the review
+      # pipeline. A PAT here would build a cascade out of a bookkeeping step.
+      issues: write
+    steps:
+      - name: Close the S8-merged queue and strip status labels
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ needs.gate.outputs.tag }}
+          URL: ${{ needs.publish.outputs.url }}
+        run: |
+          set -euo pipefail
+          # Only the owner's issues take part in the process; issues filed by
+          # anyone else never carry status labels and are not ours to close.
+          numbers=$(gh issue list --repo "$REPO" --state open --label S8-merged \
+            --author Matysh --limit 100 --json number --jq '.[].number')
+          if [ -z "$numbers" ]; then
+            echo "the S8-merged queue is empty, nothing to close"
+          else
+            for n in $numbers; do
+              gh issue comment "$n" --repo "$REPO" \
+                --body "Выпущено в \`$TAG\` · [релиз]($URL)"
+              # Label first, then close. If the run dies between the two steps an
+              # open issue without a status is visible and fixable in the flow;
+              # the reverse order would recreate the exact breakage this job is
+              # here to prevent.
+              gh issue edit "$n" --repo "$REPO" --remove-label S8-merged
+              gh issue close "$n" --repo "$REPO" --reason completed
+              echo "closed #$n"
+            done
+          fi
+          # Targeted at the defect that actually recurs, not at the invariant in
+          # general: no closed issue may still carry S8-merged.
+          leftover=$(gh issue list --repo "$REPO" --state closed --label S8-merged \
+            --limit 100 --json number --jq 'length')
+          test "$leftover" = "0" || {
+            echo "::error::$leftover closed issues still carry S8-merged"
+            exit 1
+          }
+
+  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,10 +1,62 @@
 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:
+  provenance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Validate commit trailers and hook mode
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BEFORE_SHA: ${{ github.event.before }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.sha }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          node scripts/validate-commit-provenance.mjs --check-hook-mode --github-range
+
+  # Догоняющая проверка процесса (PROCESS.md §10.3). Хуки ловят нарушение на
+  # машине автора, но их можно обойти `--no-verify`, а коммиты идут прямо в dev
+  # без PR — GitHub на своей стороне не блокирует ничего. Это последнее место,
+  # где нарушение правила №1 ловится машиной. Job независимый: краснеет сам и
+  # не роняет остальные, откат — удалить его отсюда, скрипт остаётся рабочим.
+  process-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Process gate
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BEFORE_SHA: ${{ github.event.before }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.sha }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+          TARGET_REF: ${{ github.ref }}
+          # Публичный репозиторий: штатного токена хватает на чтение issue.
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          node scripts/process-gate.mjs --github-range --issues
+
   hacs:
     runs-on: ubuntu-latest
     steps:
@@ -13,18 +65,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,12 +88,119 @@ 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:
+    # 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
+          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
+        run: npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+      - name: Smoke suite
+        run: |
+          fail=0
+          mkdir -p /tmp/smoke-logs
+          for f in demo/smoke_*.mjs; do
+            name=$(basename "$f" .mjs)
+            if node "$f" > "/tmp/smoke-logs/$name.log" 2>&1; then
+              echo "ok   $name"
+            else
+              echo "FAIL $name"
+              tail -20 "/tmp/smoke-logs/$name.log"
+              fail=1
+            fi
+          done
+          exit $fail
+      - name: Upload smoke logs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          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,6 @@ test-build/
 *.log
 __pycache__/
 .pytest_cache/
+.venv-backend/
+artifacts/
+.agents/

AGENTS.md

@@ -0,0 +1,385 @@
+# 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.
+
+## Read this first
+
+**`docs/SCOPE.md` before anything else.** It was fixed with the owner and states
+its own authority: features are built, improved and accepted **only** if they
+serve a job listed there. It carries the mission, the three personas, the core
+user jobs and the out-of-scope list.
+
+Its central consequence: **View mode is the product for two of the three
+personas.** Editors are admin-only tools and must never leak interactions into
+View.
+
+For work that changes visible behaviour, also read `docs/USER-GUIDE.ru.md` —
+interface wording comes from there and is not invented, or the UI starts speaking
+developer.
+
+Then `PROCESS.md` (the full process), `docs/STATUS.md` (where the release line
+is), and for non-trivial changes `docs/ARCHITECTURE.md` plus the canonical
+document of the subsystem you touch: `SUN.md`, `LIGHT.md`, `CANVAS.md`,
+`WALL-THICKNESS.md`, `UX-MODES.md`, `CONFIG-COMPATIBILITY.md`,
+`TOUCH-SUPPORT.md`.
+
+Standard commands live in `package.json` scripts, `CONTRIBUTING.md` and
+`docs/DEVELOPMENT.md`.
+
+## Canonical backlog and status
+
+[GitHub Issues](https://github.com/Matysh/houseplan-card/issues) are the canonical
+task records: problem, scope, acceptance criteria and discussion.
+
+**Status lives in labels:** `S1-new`, `S2-analysis`, `S3-spec`, `S4-spec-review`,
+`S5-ready`, `S6-in-progress`, `S7-code-review`, `S8-merged`, plus `blocked` on top
+of a status and `rejected` on a closed issue. Exactly one `S*` label per open
+issue. [GitHub Projects (v2)](https://github.com/users/Matysh/projects/1) is a
+human-facing view synchronised from the labels, not the source of truth.
+
+Two shortcuts exist for small work. `small` — the light track: the spec lives in
+the issue body and its review is a comment. `trivial` — the short track: no spec
+stage at all, `S2-analysis` straight to `S5-ready`, with the AC written into the
+issue body first. `trivial` requires a bug confined to one surface with no new UX
+contract, no migration, no i18n, no perf or touch impact, at most three checkable
+AC, **and expected behaviour already on record** — nothing left to decide. Code
+review is never skipped on either track; it is what stands in for testing.
+`PROCESS.md` §5 and §5.1 hold the criteria.
+
+An issue filed by an outsider is worked exactly like one of the owner's own, once
+the owner has decided to take it. The check sits **at the entrance**, not on every
+step: while an issue carries no status label it is outside the process and the
+invariants do not apply to it; once a label is on, the task is in flight and **who
+filed it stops mattering**.
+
+Applying that first label *is* the owner's explicit decision, and the platform
+already guarantees it — only someone with write access can label. The earlier rule
+made outside reports be refiled as the owner's own issues, which turned out to be
+work for nothing: on #123 the spec was already written by the time the guard
+refused.
+
+Specs, audits and ADRs may live under `docs/`, but must link to their issue and
+must not become a parallel task list. When repository documentation disagrees with
+Issues, the issue wins.
+
+## Rule #1
+
+> Changing product code without an issue is forbidden. Code changes only when the
+> issue exists and sits in "Ready for development" or later.
+
+Check before touching product code:
+
+```
+gh issue view <NN> --repo Matysh/houseplan-card --json number,state,labels
+```
+
+The label must be one of `S5-ready`, `S6-in-progress`, `S7-code-review`. Anything
+else — refuse and say why. "Issue #83 is in `S2-analysis`, code is off limits.
+Start with the spec?" is the correct answer, not a smaller patch.
+
+## Change classes
+
+| Class | Paths | Issue required |
+|---|---|---|
+| **A — product** | `src/**`, `custom_components/houseplan/**/*.py`, `manifest.json`, `hacs.json`, i18n, `custom_components/**/translations/**` | yes |
+| **B — gates and tooling** | `test/**`, `tests_backend/**`, `demo/**`, `scripts/**`, `.github/workflows/**`, `rollup.config.mjs`, `tsconfig*.json` | yes; may reuse the issue it covers |
+| **C — documentation** | `docs/**`, `README*`, `CHANGELOG*`, `AGENTS.md` | not if it is part of its issue's DoD |
+| **D — generated** | `dist/**`, `custom_components/houseplan/frontend/**`, `demo/srv/assets/houseplan-card.js`, `demo/golden/baselines/**` | never changes on its own |
+
+The table above is a summary; `PROCESS.md` §1 is the authority and now covers the
+configuration files this one omits — `package.json`, `package-lock.json`,
+`pytest.ini`, `.gitignore`, `.gitattributes`, `.githooks/**` and the rest of
+`.github/**` are class B. Where paths overlap, **D beats A**: the built bundle
+lives inside `custom_components/houseplan/frontend/` and would otherwise read as
+product source.
+
+## Commits
+
+Hooks install themselves: `package.json` runs `"prepare": "node
+scripts/install-hooks.mjs"`, so `npm ci` sets `core.hooksPath` in every fresh
+clone. Verify with `git config core.hooksPath` — expect `.githooks`.
+
+Every non-merge commit carries **terminal** trailers:
+
+```text
+Issue: #123
+User-Visible: yes
+```
+
+One `Issue:` line per issue if a commit closes several. `User-Visible: no` for
+tests, refactors, tooling and documentation that does not change the product.
+`User-Visible: yes` requires edits to **both** changelogs — `docs/CHANGELOG.md`
+and `docs/CHANGELOG.ru.md` — in the same commit.
+
+A commit touching `demo/golden/baselines/**` additionally requires:
+
+```text
+Release: v1.62.0-beta.9
+Baseline-Reviewed: https://github.com/Matysh/houseplan-card/actions/runs/<run-id>
+```
+
+Never invent a review link and never rewrite published history to satisfy
+trailers. `.githooks/commit-msg` and the `provenance` CI job both run
+`scripts/validate-commit-provenance.mjs`.
+
+Branch: `issue/<NN>-slug`. Direct commits to `dev`, no PR — the owner's decision;
+CI checks after the fact, and a violation is fixed with a follow-up commit, never
+a force-push.
+
+**Push after every task, not before a beta.** While work sits unpushed there is
+nothing to review, and reviewing twenty tasks at once is not review. `dev` may hold
+unreviewed code while a task is in flight; what matters is its state when the
+reviewer says it is accepted.
+
+**Standing permission: push `issue/<NN>-slug` without asking.** The reviewer runs
+in CI and can only read what is on the remote — an unpushed spec or commit means
+the review either stalls or judges the wrong tree. Pushing a task branch publishes
+nothing to users and does not touch the integration branch, so it needs no command.
+
+**Do not merge into `dev` by hand.** On a green code review the pipeline rebases
+the task branch onto `dev`, pushes it, and only then sets `S8-merged` — the label
+asserts the code is in `dev`, so the merge has to happen first or the label lies
+in between.
+
+If the rebase conflicts the pipeline says so in the issue and sends the task back
+to `S6-in-progress`. The verdict still stands: nothing needs reviewing again, the
+remaining work is the rebase. Resolve it, push the branch, re-apply
+`S7-code-review`. The second review run is not a formality — after a rebase onto a
+moved `dev` this is different code, and accepting it unchecked is how regressions
+arrive. Cycles are counted per stage, so a code review spends its own budget.
+
+Everything else still requires the owner's explicit command: pushing `main`,
+creating tags, publishing betas and releases, closing issues.
+
+## Two-agent workflow
+
+**Codex** writes analysis, specs and all product code. **Claude** reviews specs and
+code and owns infrastructure and distribution. The owner rules on disputes, closes
+issues and commands releases.
+
+Author and reviewer are different models, which is what "a fresh session without
+implementation context" means in practice. The reviewer never edits product code;
+the author never grades their own work.
+
+**Infrastructure-only work runs outside this flow.** CI, scripts, labels, demo
+stands, the landing page and distribution are Claude's alone, and running them
+through spec-writing and review buys nothing: the spec would restate what is
+already unambiguous, and author and reviewer would be the same role. So no spec
+file, no spec review, no code review, no walk through `S1`…`S8`.
+
+The test for "infrastructure only" is mechanical: **not a single class A file** —
+nothing under `src/**`, no `custom_components/**/*.py`, no manifests, no i18n. A
+task that touches class A even once is not infrastructure and takes the full flow;
+there is no such thing as "mostly infrastructure". The strictness is deliberate:
+a loose reading would turn this into the route by which product changes skip
+review.
+
+What stays mandatory either way: an issue exists, both trailers are on every
+commit, `typecheck`, `test` and `build` are green, and any non-obvious decision is
+written down in the code or the issue rather than kept in someone's head.
+
+**Review starts by itself.** Applying `S4-spec-review` or `S7-code-review` fires the
+pipeline, which reviews without anyone asking and takes ten to forty-five minutes.
+
+**Having applied one of those labels, wait for the result instead of ending the
+session.** Reporting "handed over for review" stops a conveyor that could have kept
+moving on its own. An agent has no clock — it exists only during its own turn — so
+waiting means polling: every 90 seconds, at most 30 times. A single long sleep hits
+the command timeout. Watch the **label**, not the comment: the label is the state,
+the comment only explains it. Do not wait at all while `blocked` is set — the task
+is waiting on the owner, not on the reviewer. On exhausting the attempts, stop and
+tell the owner: a failed run leaves the label where it was, forever.
+
+What the new label means:
+
+| Now reads | What happened | What you do |
+|---|---|---|
+| `S5-ready` | the spec is accepted | write the code |
+| `S3-spec` | the spec came back | read the verdict, revise, re-apply `S4-spec-review` |
+| `S6-in-progress` | the code came back | revise, re-apply `S7-code-review` — **or**, if the verdict was green and only the merge conflicted, just rebase and re-apply. The comment says which |
+| `S8-merged` | accepted and already in `dev` | nothing |
+| `review-4` | the cycle limit is spent | stop, the owner decides |
+
+**After a review run the label always changes.** If it did not, the run itself
+failed rather than the work — say so to the owner instead of polling on.
+
+**A failed pre-release gate does not send the issue back to review.** The
+implementation loop runs only typecheck, unit and build; golden, browser smokes,
+performance and the full HA harness run before a beta, which is after the code
+review has passed and the issue sits in `S8-merged`. Some defects cannot surface
+any earlier.
+
+Fix it, re-run what failed, and a green run is enough for the release to continue.
+The issue stays in `S8-merged`. Record the **exact command and its result** in the
+issue — "verified" without a command proves nothing. Trailers as usual, and
+`User-Visible: yes` still means both changelogs in the same commit.
+
+The exception covers repairing the defect the gate named, not carrying on
+development under the name of a repair. It goes through the normal flow — a new
+issue, or back to `S6-in-progress` — if the fix changes a behaviour contract, gives
+the user something new, reaches a subsystem the task never touched, or is
+comparable in size to the task itself. And editing the gate so it stops failing is
+concealment, not repair; the exception is a defect proven to be **in the fixture**,
+as on #89, where the sun sat at azimuth 180° and the only window faced north, so no
+ray was ever built.
+
+Baselines are still accepted only via `npm run golden:accept -- --reviewed` on a
+complete Linux CI artefact. "So the gate goes green" is not a reason.
+
+The exchange happens in **issue comments** — there is no local message bus. Verdict
+format:
+
+```text
+Verdict: green/yellow/red · cycle r<N>/4 · High: N · Medium: N → #… · Document: …
+```
+
+High blocks. Medium must become its own issue. Low is fixed or waived with a note
+in the review document. A yellow verdict is legitimate even when every acceptance
+criterion passes, if the change does not solve the stated scenario or degrades a
+neighbouring one.
+
+**Four review cycles** (two on the light track). The counter lives in the document
+name, `-r1`…`-r4`; the fourth adds the `review-4` label. There is no fifth attempt:
+the owner splits the task, rejects it, or arbitrates.
+
+On the light track (`small`: complexity ≤3, one surface, no config migration, no
+new UX contract, no perf or touch impact — all at once) the spec lives in the issue
+body and the spec review is a comment. Code review is never skipped.
+
+## Specs
+
+`docs/specs/<NN>-<slug>.md`, linked to its issue in both directions. Required
+sections are in `PROCESS.md` §7.1, plus two product ones: which persona meets this,
+on which surface, at what moment; and what the person sees before and after, in one
+sentence without implementation terms.
+
+**Ambiguity is asked, not guessed — but only product ambiguity.** A guess written as
+fact is the worst kind of defect: it passes review because it looks like a decision.
+
+The owner answers exactly two kinds of question: **what a person sees or does**, and
+**how much user-visible change belongs in this issue**. Behaviour in a boundary case,
+which persona wins when two conflict, what counts as acceptable degradation, whether
+a neighbouring behaviour is in scope here or becomes its own issue.
+
+Everything a user cannot observe is yours to settle: where state is stored, which
+module carries the guard, naming, file layout, test strategy, migration mechanics,
+development policy. Decide it, record it in an explicit "assumed, change freely"
+block, and let the reviewer challenge it. A technical disagreement between author and
+reviewer is settled by the verdict, not by the owner; it reaches him only when the
+cycle limit is exhausted.
+
+Split a mixed question instead of escalating all of it. "Where does this state live"
+is technical. "Does it survive a page reload and follow the plan across screens" is
+product. Ask the second, decide the first.
+
+Ask in one batched issue comment, each question carrying a proposed default, and put
+`blocked` on top of `S3-spec` while waiting. A question with a default costs the
+owner seconds; one without costs him minutes.
+
+## Gates
+
+```
+npm run typecheck
+npm test
+npm run build
+npm run inventory        # the only correct way to get test counts
+```
+
+Never copy test counts into documents by hand; they go stale in days.
+
+After building, keep all three bundle snapshots in sync — CI compares them
+byte-for-byte:
+
+```
+cp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js
+cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+```
+
+During the implementation cycle only the fast gates run. `smoke`, `golden` and
+`performance_smoke` spin up Chromium and belong to the pre-beta run — which is then
+mandatory and complete.
+
+**Backend.** A full Home Assistant harness cannot run on native Windows at all:
+Home Assistant imports the Unix-only `fcntl` module. Its canon is Linux CI or WSL.
+Locally only the pure subset runs; `python -m pytest tests_backend/ -q` without
+Home Assistant **silently skips** `test_ha_*.py` (`conftest.py` ignores them when
+`homeassistant` is not importable), so a green result proves nothing. Say so in the
+report instead of claiming the backend was verified. Cloud agents have the harness
+at `.venv-backend/bin/python`.
+
+**Running the app / smoke suite**: build a fresh bundle and copy it into the demo
+assets first, then run `node demo/smoke_*.mjs`. 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 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.
+
+**CI is pinned to an exact SHA.** The release gate accepts only a `completed
+success` run for the candidate's SHA, not "the last green one"; a new push cancels
+an unfinished Validate for the same branch. Jobs: `provenance`, `hacs`, `hassfest`,
+`frontend`, `smoke`, `golden`, `performance_smoke`, `backend`.
+
+**"Verified" without a named command and its result is not evidence.**
+
+## Environments
+
+**Local Windows checkout** is the day-to-day environment: Node 22 as in CI, Python
+3.13 in a venv, `gh` authenticated. `.venv-backend` does **not** exist there — it is
+provisioned only by cloud agent startup scripts, which also run `npm ci` and install
+Playwright Chromium.
+
+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.
+
+## Labs flags
+
+`src/labs.ts` is the single registry and resolver for hidden presentation
+experiments. Activate a live flag through `?hp-labs=<id>` or the shared hash
+grammar, remove it with `-<id>`, and use `off` to clear the set. Do not add a
+YAML/config switch for a Labs-only experiment. A new entry needs a unique
+lowercase id, issue, numeric-core `since`, numeric-core `expires`, summary and
+unit/browser coverage. Invalid or duplicate registry entries fail closed.
+
+Expiry is exclusive and ignores prerelease suffixes: an entry expiring at
+`1.65.0` is unavailable in `1.65.0-beta.1`. Before that cycle, either remove the
+experiment or graduate it through its own reviewed issue; never extend expiry as
+an incidental change. Labs may alter presentation only and must not gate data,
+migrations, stores, HA actions or network calls. Current renderer details are in
+`docs/ISOMETRIC.md`.
+
+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.
+
+## 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.
+
+A `Release vX.Y.Z-beta.N candidate` commit is **not** promotion-only: it carries
+the work itself and follows the ordinary rules, trailers included.
+
+Issues are closed in a batch when a beta ships, not when implementation ends: that
+way a bug found in the beta returns to the same task, and the beta announcement can
+list what went in. Status labels are stripped as the issues close.

CODE-REVIEW-issue-068-2026-08-12.md

@@ -0,0 +1,82 @@
+# Code review — issue #68 (contextual help)
+
+Date: 2026-08-12
+
+Branch: `dev`
+
+Scope: `hp-help`, Houseplan help factory, localization contract, dialog/overlay lifecycle,
+keyboard and touch interaction, responsive placement, consumers and regression coverage.
+
+## Outcome
+
+The overlay, focus, Escape, outside-click, scroll, Popover/fallback and visual-viewport
+paths are internally consistent. The shared dialog overlay registry is used correctly,
+the trigger remains reachable in disabled fieldsets through `legend`, and all seven
+current call sites have non-empty RU/EN body and ARIA strings.
+
+Four hardening findings were accepted and fixed locally. No model, saved configuration
+or user data contract changed.
+
+## Findings and resolutions
+
+### CR68-01 — dead trigger is rendered without help content (P1)
+
+`hp-help` blocked `_openHelp()` when `text` was empty, but `render()` still returned a
+focusable button. The result was the exact reported defect: a visible help glyph that
+could not open any explanation.
+
+Resolution: `hp-help` renders nothing unless both trimmed `text` and `ariaLabel` exist.
+The same predicate guards opening and closes an already-open surface if either value is
+removed dynamically.
+
+### CR68-02 — missing translation could be displayed as a key (P1)
+
+The card factory called `t()` directly. Its intended generic fallback returns the key
+name when neither dictionary contains a value, so a future incomplete help pair could
+produce a real trigger with implementation text such as `marker.foo.help`.
+
+Resolution: the factory now checks the localized value and its derived `.aria` value
+through `hasTranslation()` before it creates `hp-help`. English fallback remains valid;
+a genuinely absent or whitespace-only pair produces no host and no layout gap.
+
+### CR68-03 — accessible name had a hard-coded English fallback (P1)
+
+Direct use without `ariaLabel` produced `aria-label="Help"`. This violated the issue
+contract requiring a complete localized accessible name and made an incomplete component
+look valid to keyboard and screen-reader users.
+
+Resolution: the fallback was removed. Missing ARIA copy suppresses the affordance just
+like missing visible copy.
+
+### CR68-04 — icon did not follow the product icon system (P2)
+
+The trigger used a font `?`, whose shape and optical alignment depended on the platform
+font and did not visually mean “question in a circle”.
+
+Resolution: the glyph is now the shared MDI `help-circle-outline` vector inside the same
+32/40 px target. It remains decorative because the button already has a full ARIA label.
+
+### CR68-05 — regression coverage missed incomplete content (P2)
+
+The smoke covered all open/close and overlay paths but never instantiated an empty or
+half-configured component, so CR68-01/03 could pass the release gate.
+
+Resolution: the #68 smoke now asserts that empty body and empty ARIA copy create no
+trigger, and that restoring a complete pair creates the circled-question SVG.
+
+## Reviewed without changes
+
+- Mouse hover timing, keyboard focus, touch click and the second-Escape dialog path.
+- `aria-describedby` only while open; the visible bubble stays hidden from the
+  accessibility tree to avoid duplicate announcements.
+- Exclusive transient-surface ownership with the colour/opacity picker and toast.
+- Popover API path and dialog-owned fallback portal.
+- Cached dialog scroll-listener cleanup and disconnect cleanup.
+- Visual viewport placement, flipping and edge clamping.
+- Existing call sites and RU/EN localization parity.
+
+## Verification policy
+
+Per project policy, no tests were run during this local edit. Static type checking,
+syntax checking and whitespace validation are recorded in the handoff; the updated
+targeted smoke is intended for the next prerelease gate.

CODE-REVIEW-issue-094-2026-08-12.md

@@ -0,0 +1,180 @@
+# Код-ревью issue #94 — универсальное «Переключить состояние»
+
+- **Дата:** 2026-08-12
+- **Issue:** https://github.com/Matysh/houseplan-card/issues/94
+- **Проверенная версия:** локальный `dev` после `v1.62.0-beta.3`, включая
+  незакоммиченные исправления #95–#97
+- **Итог ревью до правок:** changes requested — 2 high, 4 medium, 1 minor
+- **Итог после локальных правок:** замечания устранены; проверки отложены до
+  ближайшего pre-release по принятому правилу владельца
+
+## 1. Охват
+
+Проверены:
+
+1. нормативный алгоритм и acceptance criteria в
+   `docs/specs/094-universal-state-toggle.md`;
+2. pure resolver `src/device-toggle.ts`;
+3. target selection через exact binding, device role и `controls`;
+4. capability/security/service guards;
+5. dialog projection, hint, lossless Save и preview;
+6. обычный click, confirmation re-resolve и обработка ошибок;
+7. общий cover target для действия и presentation;
+8. backend schema и import/export round-trip;
+9. unit/smoke-матрица и архитектурная документация;
+10. совместимость с визуальной непрерывностью #73 и локальными правками
+    #95–#97.
+
+## 2. Найденные и исправленные замечания
+
+### CR94-01 — High: domain service ошибочно считался capability конкретной entity
+
+**Было:** `POWER_DOMAINS` разрешал `climate`, `water_heater`, `siren` и
+`camera`, если нужный service существовал на уровне domain. Но HA публикует
+services для всего domain; неподдерживающая их конкретная entity всё равно
+оставалась «исполняемой» в hint, а вызов затем отклонялся Home Assistant.
+
+Это прямо противоречило §9.1 и mutation gate 6 ТЗ. Home Assistant Core
+подтверждает entity-level guards:
+
+- Climate `TURN_OFF=128`, `TURN_ON=256`:
+  https://github.com/home-assistant/core/blob/dev/homeassistant/components/climate/const.py
+- Water heater `ON_OFF=8`:
+  https://github.com/home-assistant/core/blob/dev/homeassistant/components/water_heater/__init__.py
+- Siren `TURN_ON=1`, `TURN_OFF=2`:
+  https://github.com/home-assistant/core/blob/dev/homeassistant/components/siren/const.py
+- Camera `ON_OFF=1`:
+  https://github.com/home-assistant/core/blob/dev/homeassistant/components/camera/__init__.py
+
+**Исправлено:** введён декларативный `POWER_ADAPTERS` с state semantics,
+unknown policy и точными feature masks. Feature-gated entity теперь получает
+команду только при наличии требуемых bits; service catalog остаётся вторым
+guard. Media player и legacy vacuum включены в тот же реестр.
+
+**Покрытие:** параметрические unit-матрицы для всех базовых power adapters и
+для climate, media player, siren, water heater, camera, legacy vacuum — как
+разрешённые, так и запрещённые/missing-feature варианты; отдельная матрица
+`unknown` проверяет полный/неполный capability mask.
+
+### CR94-02 — High: click мог использовать target из сохранённого визуального frame
+
+**Было:** #73 намеренно может некоторое время показывать последний цельный
+`_renderDevices` snapshot, но `_clickDevice(ev, d)` разрешал action прямо по
+переданному `d`. Если binding/controls изменились до атомарной смены frame,
+нажатие без confirmation могло вызвать прежнюю цель. Confirmation уже делал
+повторное разрешение, обычный click — нет.
+
+**Исправлено:** в View действие сначала находит текущий `DevItem` в
+`this._devices` по стабильному marker id. Action, binding, controls и command
+разрешаются только из него; исчезнувший marker даёт no-op. Локальная
+House Plan info-card по-прежнему может использовать видимый snapshot — это
+безопасная read-only поверхность и намеренный контракт исправления #96.
+
+**Покрытие:** smoke сохраняет старый `DevItem`, меняет controls, перестраивает
+live devices и проверяет, что click вызывает только новую группу.
+
+### CR94-03 — Medium: неизвестный persisted action расходил UI и runtime
+
+**Было:** неизвестный token на light проецировался как default `toggle`, тогда
+как `toggleOriginOf()` правильно не признавал его toggle-origin. Селектор мог
+показать «Переключить состояние», hint оставался пустым, а click был no-op.
+
+**Исправлено:** light default применяется только к действительно отсутствующему
+token (`null`, `undefined`, пустая legacy-строка). Неизвестное значение fail-
+closed проецируется в локальную карточку; backend по-прежнему отклоняет его при
+записи.
+
+### CR94-04 — Medium: legacy cover терял identity после disable в HA
+
+**Было:** legacy `tap_action: cover` искал cover только в active
+`device.entities`, если рядом оставался хотя бы один активный sibling. После
+disable cover в HA старое явное намерение превращалось в анонимный no-target и
+presentation переставал знать прежнюю cover entity.
+
+**Исправлено:** legacy-cover origin сначала сохраняет приоритет активной cover,
+а при её отсутствии ищет историческую цель в `allEntities`. Общий resolver
+возвращает `ha-disabled` и сохраняет тот же cover identity для hint/presentation,
+но более ранняя disabled registry row не может заслонить рабочую cover. Новый
+device-role toggle по-прежнему исключает disabled rows.
+
+### CR94-05 — Medium: пустой service catalog считался поддержкой всех services
+
+**Было:** отсутствие/пустой `hass.services` давало optimistic `true` для любого
+service. Это нарушало runtime guard из ТЗ и позволяло построить команду без
+доказательства её существования.
+
+**Исправлено:** отсутствующий catalog/domain/service теперь означает
+`unsupported`. После появления актуального HA snapshot resolver автоматически
+пересчитывает hint и command. Синтетический HA в `demo/srv/demo.html` теперь
+публикует явный service catalog, поэтому smoke-среда проверяет тот же fail-closed
+контракт и не создаёт ложные no-op.
+
+### CR94-06 — Medium: device binding не выбирал первую действительно поддерживаемую entity роли
+
+**Было:** resolver выбирал первую entity «подходящего domain», а затем мог
+остановиться на `unsupported`, хотя следующая равноправная entity той же
+functional role имела требуемую capability. Это не соответствовало формулировке
+§8.1 «первая поддерживаемая entity».
+
+**Исправлено:** проверка идёт по уже выбранной shared functional role.
+Capability-unsupported peer можно пропустить только внутри неё; missing,
+unavailable и secure identity сохраняются без retarget. Config/diagnostic
+switch более слабой роли по-прежнему никогда не подставляется.
+
+### CR94-07 — Minor: статус ТЗ оставался «готово к реализации»
+
+**Исправлено:** ТЗ, specs index, архитектура, STATUS, TESTING и RU/EN changelog
+актуализированы под опубликованную beta.3 и этот локальный hardening pass.
+
+## 3. Проверенные инварианты без изменений
+
+- exact `entity:` binding не ищет sibling при unsupported/missing/unavailable;
+- raw external controls владеют tap только у explicit toggle и не дают fallback
+  на собственную entity контроллера;
+- passive forced-light marker сохраняет единственное документированное driver-
+  исключение и дедупликацию;
+- partial group вызывает только отображённое доступное подмножество;
+- any-on/all-off group semantics соответствует ТЗ;
+- lock, alarm и cover classes `garage`/`door`/`gate` остаются secure no-op;
+- cover/valve open/close/stop используют одновременно feature bit и service;
+- confirmation сравнивает target set, а направление намеренно пересчитывается
+  по текущему state;
+- legacy `cover` и отсутствующий default-light action сохраняются lossless до
+  явного изменения select;
+- backend принимает текущие actions и legacy `cover`, неизвестные tokens
+  отклоняет; import/export сохраняет action-поля без преобразования;
+- отдельного `cover` в текущем UI нет;
+- right-click, long press, touch/pinch и confirmation UX этим проходом не
+  менялись.
+
+## 4. Изменённые файлы
+
+- `src/device-toggle.ts`
+- `src/houseplan-card.ts`
+- `test/device-toggle.test.mjs`
+- `demo/smoke_controls.mjs`
+- `demo/srv/demo.html`
+- `docs/specs/094-universal-state-toggle.md`
+- `docs/specs/README.md`
+- `docs/ARCHITECTURE.md`
+- `docs/STATUS.md`
+- `docs/TESTING.md`
+- `docs/CHANGELOG.md`
+- `docs/CHANGELOG.ru.md`
+
+## 5. Проверка
+
+Локально выполнены только read-only/static проверки ревью:
+
+- `git diff --check`;
+- `npm run typecheck`;
+- `node --check test/device-toggle.test.mjs`;
+- `node --check demo/smoke_controls.mjs`;
+- поиск всех consumers `resolveToggleIntent`, `projectedTapAction`,
+  `toggleCoverEntity`, `sameToggleCommandTargets`;
+- сверка backend schema/import-export;
+- сверка capability flags с официальным Home Assistant Core.
+
+Unit, browser smoke, backend tests, build и generated bundles **не запускались**
+по правилу проекта: локальные правки делаются без тестов, минимальный целевой
+прогон выполняется при следующем pre-release.

CONTRIBUTING.md

@@ -3,6 +3,29 @@
 Thanks for your interest! The project is one HACS package: a storage **integration**
 (`custom_components/houseplan/`, Python) and a **Lovelace card** (`src/`, TypeScript + Lit).
 
+## Changelog
+
+User-visible changes go into **both** changelogs in the same commit:
+`docs/CHANGELOG.md` (English) and `docs/CHANGELOG.ru.md` (Russian). Entries
+older than v1.42.0 exist only in the English file — no need to backfill them.
+
+## Where to ask
+
+Not sure whether something is a bug, or just want to discuss an idea before
+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
@@ -12,6 +35,7 @@ npm run typecheck         # tsc --noEmit (strict)
 npm test                  # node:test — pure logic, i18n parity, tap-action security
 npm run build             # tsc + rollup → dist/houseplan-card.js
 pip install pytest voluptuous && python -m pytest tests_backend -q   # pure backend tests
+npm install                # also installs .githooks through the prepare script
 ```
 
 The HA-harness backend tests (`tests_backend/test_ha_*.py`) need Python ≥3.13 and
@@ -27,7 +51,8 @@ every push — locally they are skipped when `homeassistant` is not importable.
 - The built card must be committed in sync: `cp dist/houseplan-card.js
   custom_components/houseplan/frontend/` (CI compares them byte-for-byte).
 - Tap actions have a security model (locks/alarms never toggle from the plan) —
-  see `resolveTapAction` in `src/logic.ts`; don't weaken it.
+  see `resolveToggleIntent` in `src/device-toggle.ts`; don't weaken it.
+- Every commit follows the issue and trailer contract in `PROCESS.md`.
 - Follow the Integration Quality Scale where applicable —
   `custom_components/houseplan/quality_scale.yaml` tracks the self-assessment.
 

PROCESS.md

@@ -0,0 +1,860 @@
+# Процесс работы над House Plan
+
+> **Статус документа: канон** (редакция 2026-08-13). Решения владельца, на
+> которых он стоит: прямые коммиты в `dev` **без PR** · канон статуса — **метки**,
+> имена английские · лёгкий трек **включён** · автор и ревьюер — разные модели ·
+> инфраструктурные задачи идут **вне** флоу.
+>
+> **Область действия:** обязателен для владельца и для любого агента. Читается
+> сразу после `docs/SCOPE.md` и `AGENTS.md`, до `docs/STATUS.md`. Живёт в
+> репозитории: до августа 2026 канон лежал только в папке владельца, и свежий клон
+> его не содержал вовсе.
+>
+> **Приоритет источников.** Канонический бэклог — GitHub Issues; статус живёт в
+> метках, Project v2 остаётся человеческим представлением. При расхождении
+> документации с GitHub побеждает GitHub. При расхождении этого документа с
+> `.github/workflows/*.yml` и `scripts/*` побеждает **фактическая автоматизация**:
+> она исполняется, а описание — нет. Расхождение при этом не игнорируется, а
+> заводится issue с меткой `process`.
+>
+> При расхождении процесса и привычки побеждает процесс.
+
+---
+
+## 1. Основное правило
+
+**Изменение продуктового кода без issue запрещено.** Код меняется только тогда,
+когда issue существует и находится в статусе «Готово к разработке» или дальше.
+Исключения — только §11, и каждое оставляет след.
+
+Правило работает лишь при точной границе «продуктового кода», иначе спор
+переносится на границу:
+
+| Класс | Что входит | Нужен ли issue |
+|---|---|---|
+| **A. Продукт** | `src/**`, `custom_components/houseplan/**/*.py`, `manifest.json`, `hacs.json`, `src/i18n/*.json`, `custom_components/**/translations/*` | **Да, обязательно.** Только из «Готово к разработке» или дальше |
+| **B. Гейты и инструменты** | `test/**`, `tests_backend/**`, `demo/**`, `scripts/**`, весь `.github/**`, `.githooks/**`, `rollup.config.mjs`, `tsconfig*.json`, `package.json`, `package-lock.json`, `pytest.ini`, `.gitignore`, `.gitattributes` | **Да.** Может использовать issue того изменения, которое покрывает; самостоятельная работа над гейтом получает свой issue (тип `tech-debt`) |
+| **C. Документация** | `docs/**`, `README*`, `CHANGELOG*`, `AGENTS.md`, `CONTRIBUTING.md`, `PROCESS*.md`, `LICENSE`, `(CODE\|SPEC)-REVIEW-*.md` | Документирование A/B в том же коммите — часть DoD своего issue. Самостоятельная работа над документацией — свой issue |
+| **D. Сгенерированное** | `dist/**`, `custom_components/houseplan/frontend/**`, `demo/srv/assets/houseplan-card.js`, `demo/golden/baselines/**` | Никогда не меняется само по себе. Коммит **только** класса D допустим лишь как релизный промоушен или как принятие эталонов с доказательством ревью |
+
+Практический смысл таблицы: «я только поправил тест» и «я только пересобрал
+бандл» перестают быть лазейками.
+
+Классы неупорядочены, но при пересечении путей **D сильнее A**: собранный бандл
+лежит внутри `custom_components/houseplan/frontend/`, и без этого правила он
+считался бы продуктовым исходником.
+
+**Инфраструктурная задача идёт вне флоу** (решение владельца 2026-08-13,
+issue #118). Признак механический: **ни одного файла класса A**. Такая задача
+делается без ТЗ, ревью ТЗ, код-ревью и без прохода по статусам — флоу построен
+для изменений, у которых есть персона и видимое поведение, а в инфраструктуре ТЗ
+пересказывало бы очевидное, и автор с ревьюером оказались бы одной ролью.
+Проверкой служат гейты и CI. Обязательным остаётся issue, трейлеры и зелёные
+`typecheck`, `test`, `build`.
+
+Задача, задевающая класс A хотя бы одним файлом, инфраструктурной **не
+является** и идёт полным флоу. «В основном инфраструктурная» не бывает: иначе
+это дорога, по которой продуктовые правки минуют ревью. Признак задан через
+класс файлов, а не через самоощущение исполнителя, именно поэтому.
+
+---
+
+## 2. Жизненный цикл
+
+Восемь рабочих статусов и два служебных. Фазы тестирования в цикле сознательно
+**нет**: найденные позже дефекты заводятся отдельными issue и проходят цикл
+заново. Issue закрывается после выпуска беты.
+
+```
+S1-new → S2-analysis → S3-spec → S4-spec-review ⟲ → S5-ready →
+       → S6-in-progress → S7-code-review ⟲ → S8-merged → закрыт при выпуске беты
+
+служебные:  blocked (поверх статуса)   rejected (закрыт)
+⟲ — возврат на правки, не более 4 циклов (§4), на лёгком и коротком треке 2
+короткий трек (`trivial`, §5.1) идёт S2-analysis → S5-ready, минуя S3 и S4
+```
+
+Переходы `S4-spec-review` и `S7-code-review` выполняются **автоматически**: метка
+порождает событие, событие запускает ревью (§10.4). Остальные ставит исполнитель.
+
+### 2.1 Новое — заведение задачи
+
+- **Кто:** любой — владелец, агент, пользователь (Telegram, GitHub).
+- **Вход:** проблема в пользовательских терминах; как проявляется или зачем нужно.
+  Решение **не требуется** и не приветствуется.
+- **Запрещено:** ставить приоритет, оценивать, писать ТЗ, начинать код.
+
+### 2.2 Аналитика и оценка
+
+Задача разбирается, продуктовое «да» ещё не дано.
+
+- **Кто:** агент-аналитик готовит, владелец решает.
+- **Чек-лист**, результат — комментарием в issue:
+  1. дубликаты проверены (ссылки на похожие issue);
+  2. в скоупе по `docs/SCOPE.md` и `docs/TOUCH-SUPPORT.md`;
+  3. **пользовательская ценность 1–10** и **ценность для разработки** — что
+     упрощает или разблокирует;
+  4. **сложность и риск 1–10** — трудоёмкость плюс вероятность задеть смежное;
+  5. приоритет **P1/P2/P3**;
+  6. тип: баг / фича / техдолг;
+  7. затронутые поверхности (модули, диалоги, бэкенд, i18n);
+  8. лёгкий трек — да/нет по критериям §5.
+- **Приоритет и ценность — поля владельца.** Агент предлагает, владелец
+  утверждает; иначе агенты приоритизируют сами и P1 разрастается.
+- **Выход:** «ТЗ в работе» либо «Отклонено» с записанной причиной.
+
+### 2.3 ТЗ в работе — написание ТЗ
+
+- **Кто:** автор ТЗ, назначает себя. Статус означает «занято».
+- **Артефакт:** `docs/specs/<NN>-<slug>.md`, где `NN` — **номер issue**.
+  Многоэтапная задача: `<NN>-<slug>-stage<N>.md`.
+- **Лёгкий трек:** ТЗ пишется в теле issue, файл не создаётся (§5).
+- **Выход:** полная первая редакция по §7.
+
+### 2.4 ТЗ на ревью
+
+- **Ревьюер ≠ автор.** Ревьюер получает issue и ТЗ, без устных пояснений автора.
+  Его задача — не согласиться, а найти, где ТЗ не выполнимо или не проверяемо.
+- **Артефакт:** `docs/reviews/SPEC-REVIEW-<NN>-r<N>.md`, вердикт
+  зелёный / жёлтый / красный. Лёгкий трек — комментарий в issue.
+- **High-находки блокируют.** Medium/Low — либо правятся, либо становятся
+  отдельными issue со ссылкой; «оставили в тексте ревью» не считается закрытием.
+- **Выход:** «Готово к разработке» либо возврат в «ТЗ в работе» — не более
+  4 циклов (§4).
+
+### 2.5 Готово к разработке (DoR)
+
+Не работа, а **очередь**: единственный статус, из которого можно трогать код.
+Все пункты обязательны:
+
+- ТЗ существует, ревью ТЗ зелёное, ссылки issue ↔ ТЗ на месте;
+- **AC1…ACn** — пронумерованные проверяемые критерии приёмки; у каждого указано,
+  чем он доказывается: `unit` / `backend` / `smoke` / `golden` / «ревью кода»;
+- перечислены затронутые файлы и модули;
+- i18n: ключи en + ru перечислены;
+- миграция и compatibility-поля решены по `docs/CONFIG-COMPATIBILITY.md`;
+- влияние на производительность и бюджеты названо (или явно «нет»);
+- влияние на touch по `docs/TOUCH-SUPPORT.md` (View и киоск — блокирующие);
+- release-артефакты по правилу `docs/specs/README.md` (changelog RU+EN,
+  документация, golden/скриншоты, performance/security);
+- **откат**: как выключить или вернуть назад (флаг Labs, обратная миграция);
+- открытых продуктовых вопросов нет; риски перечислены.
+
+Если хоть один пункт не выполнен — статус не «Готово к разработке», как бы ни
+хотелось начать.
+
+### 2.6 В разработке — реализация
+
+- **Занятие (claim):** назначить себя, поставить метку, комментарий
+  «Взял: <роль> · сессия <id> · ветка `issue/<NN>-<slug>`».
+- **WIP-лимиты:** не более **1** issue в «В разработке» на исполнителя, не более
+  **3** одновременно на цикл релиза, не более **2** в «Код-ревью».
+- **Трассируемость:** ветка `issue/<NN>-<slug>`; каждый коммит несёт трейлеры
+  `Issue: #<NN>` и `User-Visible: yes|no`.
+- **Автотесты — часть реализации, а не отдельная фаза.** Каждый AC, помеченный
+  `unit`/`backend`/`smoke`/`golden`, получает свою проверку здесь же.
+  «Тестирование вне жизненного цикла» означает отсутствие фазы ручного
+  тестирования, а не отсутствие тестов.
+- **Скоуп не расширяется.** Найденное по пути становится новым issue в «Новое».
+  Если находка блокирует — текущий issue уходит в «Заблокировано» со ссылкой.
+  Попутных правок «раз уж я здесь» не бывает.
+- **Документация — в том же коммите,** что и поведение (действующая политика
+  `docs/STATUS.md`): changelog RU+EN для пользовательского, `STATUS.md` для
+  состояния, `DEVELOPMENT.md` для новых грабель, `ARCHITECTURE.md` для дизайна.
+- **Выход:** локальный гейт зелёный (§8), хендофф-комментарий (§7.2).
+
+### 2.7 Код-ревью
+
+- **Ревьюер ≠ исполнитель**, свежая сессия без контекста реализации.
+- **Артефакт:** `docs/reviews/CODE-REVIEW-<tag|NN>-r<N>.md` в действующем
+  формате: скоуп, как проверялось (таблица гейтов с результатами), находки
+  High/Medium/Low с воспроизведением, что проверено и корректно, чего не проверял.
+- **Ревьюер отвечает за AC.** Раз ручного тестирования в цикле нет, именно ревью
+  кода отвечает на вопрос «оно вообще работает»: каждый AC либо доказан
+  автотестом — и ревьюер убедился, что **тест умеет падать**, — либо разобран по
+  коду с явной записью «проверено чтением, не исполнением».
+- **High блокируют.** Medium **обязаны** превратиться в issue.
+- **Выход:** очередь на пре-релиз либо возврат в «В разработке», не более
+  4 циклов (§4).
+
+### 2.8 Закрытие после выпуска беты
+
+- **Вход:** изменение вошло в опубликованную бету/RC, CI Validate зелёный на
+  **точном SHA** тега (промоушен-правило: ни одна фича не попадает в стабильный
+  релиз, не побывав в бете).
+- **Закрывает** релиз-менеджер, не исполнитель. Комментарий закрытия: тег беты,
+  ссылка на прогон CI, ссылка на бюллетень changelog.
+- **Стабильный релиз статусов не двигает** — issue уже закрыты; релизный коммит
+  promotion-only, changelog ссылается на закрытые issue.
+- **Что приходит потом:** дефект, найденный на стенде, дома или пользователем, —
+  **новый issue** типа «баг» со ссылкой на исходный. Исходный не переоткрывается.
+
+### 2.9 Заблокировано / Отклонено
+
+- **Заблокировано:** обязательна ссылка на блокирующий issue или внешнюю причину
+  и дата пересмотра. Без причины статус не ставится.
+- **Отклонено:** закрытие с записанной причиной (вне скоупа, дубликат, цена не
+  оправдана). Тихое закрытие без причины запрещено.
+
+---
+
+## 3. Правила
+
+Продолжение черновика владельца. Каждое правило проверяемо — глазами или машиной.
+
+1. **Никаких изменений в код, если нет issue** и он не помечен «Готово к
+   разработке» или дальше.
+2. **Issue не может быть взят в разработку**, пока у него нет ТЗ с зелёным ревью,
+   пронумерованных AC с указанием доказательства и назначенного исполнителя.
+3. **Issue не может быть взят дважды.** Занятие фиксируется назначением, меткой и
+   комментарием с именем ветки. У одного исполнителя одновременно не более одного
+   issue в разработке.
+4. **Статус меняется до действия, а не после.** Взял — поставил метку; отдал на
+   ревью — поставил метку. Метка, поставленная задним числом, — дефект процесса.
+5. **Ровно одна метка статуса** на issue в любой момент. Ноль или две — дефект,
+   еженедельная гигиена его показывает.
+6. **Автор не ревьюит своё** — ни ТЗ, ни код. Никто не переводит свою работу через
+   ревью-гейт.
+7. **Ревью возвращает не более 4 раз.** Пятый заход — решение владельца: разделить,
+   отклонить или арбитраж (§4).
+8. **High блокирует. Medium становится issue.** Low либо правится, либо снимается
+   решением ревьюера с записью в документе.
+9. **Скоуп не расширяется.** Всё найденное вне ТЗ — новый issue, а не попутная
+   правка. Блокирующая находка отправляет текущий issue в «Заблокировано».
+10. **Каждый коммит класса A и B несёт трейлер `Issue: #NN`**, ветка называется
+    `issue/NN-slug`, а `User-Visible: yes` требует правок в **обоих** changelog в
+    том же коммите.
+11. **Документация — в том же коммите, что поведение.** Отдельным «допишу потом»
+    коммитом документация не бывает.
+12. **Сгенерированное не коммитится само по себе.** Только релизный промоушен или
+    принятие эталонов со ссылкой на прогон CI.
+13. **Golden-эталоны принимаются только** `npm run golden:accept -- --reviewed` по
+    полному Linux-артефакту. Принятие ради зелёного CI — нарушение процесса.
+14. **Issue закрывается после выпуска беты** с зелёным CI на точном SHA. Не
+    раньше, не «по факту наличия кода», не исполнителем.
+15. **Закрытый issue не переоткрывается.** Новый дефект — новый issue со ссылкой.
+16. **Стабильный релиз — promotion-only:** версии, сгенерированные бандлы,
+    changelog и release-метаданные. Продуктового кода там нет.
+17. **История `dev` не перезаписывается.** На неё ссылаются теги. Нарушение
+    исправляется следующим коммитом плюс issue с меткой `process` — не
+    force-push'ем.
+18. **AC доказывает автотест или запись ревьюера.** Фразы «проверил локально, всё
+    работает» в процессе не существует: либо тест, который умеет падать, либо
+    честное «проверено чтением, не исполнением».
+19. **Параллельных бэклогов нет.** Планы, разборы и приоритеты живут в issue;
+    файловые отчёты — разовые и датированные.
+20. **Аварийный хотфикс — только решением владельца** и только по §11.2.
+
+---
+
+## 4. Лимит циклов ревью: 4
+
+Оба ревью-гейта возвращают задачу на правки не более **4 раз**. Счётчик виден в
+имени документа: `-r1` … `-r4`; на четвёртом заходе ставится метка `review-4`.
+
+- **Что считается циклом:** отправка на ревью → вердикт с блокирующими находками
+  → возврат. Уточняющий вопрос без вердикта циклом не считается.
+- **Исчерпание лимита — не «пятая попытка», а разбор.** Задача уходит владельцу,
+  решение одно из трёх:
+  1. **разделить** — issue закрывается как «заменён», вместо него 2–3 меньших с
+     ясным скоупом (частый настоящий диагноз: ТЗ было слишком большим);
+  2. **отклонить** — цена решения оказалась выше ценности;
+  3. **арбитраж владельца** — владелец фиксирует решение в issue, оно принимается
+     как есть; несогласие ревьюера записывается, но не блокирует.
+- **Граница между «циклом» и «новым багом»:** до закрытия беты находка ревьюера —
+  возврат на правки; после закрытия — новый issue. Иначе лимит 4 обходится
+  заведением issue вместо возврата.
+- Для лёгкого трека лимит ревью ТЗ — **2** цикла: задача на три часа, которую
+  переписывают трижды, лёгкой не была.
+
+---
+
+## 5. Лёгкий трек (метка `small`)
+
+**Критерии — все одновременно:**
+
+- сложность и риск ≤ 3;
+- одна поверхность (один диалог, один модуль, один эндпоинт);
+- нет миграции конфига и новых compatibility-полей;
+- нет нового UX-контракта — меняется поведение в рамках уже описанного;
+- нет влияния на производительность и на touch-контракт.
+
+**Что упрощается:**
+
+- ТЗ пишется **в теле issue** по шаблону: проблема · контракт · AC1…ACn с
+  доказательством · откат. Файл в `docs/specs/` не создаётся;
+- ревью ТЗ — комментарий второго агента, отдельный документ не нужен;
+- лимит ревью ТЗ — 2 цикла.
+
+**Что не упрощается:** issue, оценка, статусы, трейлеры коммитов, changelog,
+**код-ревью и его документ**, закрытие после беты. Код-ревью не пропускается
+никогда — именно оно в этом процессе заменяет тестирование. Единственное
+исключение — починка упавшего предрелизного гейта, §11.4.
+
+Если по ходу выясняется, что критерий нарушен (появилась миграция, задело второй
+модуль) — метка `small` снимается, issue возвращается в `S3-spec` и получает
+нормальный файл ТЗ. Это не провал, это ранняя диагностика.
+
+### 5.1 Короткий трек (метка `trivial`)
+
+Решение владельца 2026-08-13, issue #128. Лёгкий трек делает ТЗ дешёвым; короткий
+обходится без него совсем.
+
+**Маршрут:** `S1-new` → `S2-analysis` → `S5-ready` → `S6-in-progress` →
+`S7-code-review` → `S8-merged`. Стадии `S3-spec` и `S4-spec-review` пропускаются.
+
+`S2-analysis` остаётся: это комментарий, а не прогон CI, и именно там владелец
+решает приоритет и ценность. AC пишет автор в теле issue при переводе в
+`S5-ready` — до перехода, иначе ревьюеру нечего будет сверять.
+
+**Критерии, все обязательны:**
+
+- тип `bug`;
+- правка ограничена одной поверхностью, нового UX-контракта нет;
+- нет миграции конфига, новых ключей i18n, влияния на перф и touch;
+- AC выражаются тремя проверяемыми утверждениями или меньше;
+- **ожидаемое поведение уже зафиксировано** — в `docs/USER-GUIDE.ru.md`, в
+  каноническом документе подсистемы либо однозначно в самом отчёте. Решать нечего.
+  Если есть что решать, это `S3-spec`, и никакая экономия этого не отменяет.
+
+Метка ставится в `S2-analysis` вместе с остальными оценками, одним комментарием,
+где владелец утверждает и приоритет.
+
+**Что не упрощается:** issue, оценка, статусы, трейлеры, changelog и **код-ревью**.
+Лимит циклов код-ревью — 2, как на лёгком треке.
+
+Если по ходу выясняется, что критерий нарушен, метка снимается и issue уходит в
+`S3-spec` за нормальным ТЗ. Как и на лёгком треке, это не провал, а ранняя
+диагностика.
+
+**Чем этот трек опасен.** Он убирает единственное место, где решение проверялось
+до написания кода. Признак «решать нечего» держит всю конструкцию, и его нельзя
+подтверждать ощущением — только ссылкой на уже зафиксированное поведение.
+
+---
+
+## 6. Роли
+
+Один агент может исполнять несколько ролей в разных issue, но **не две роли в
+одном артефакте**.
+
+| Роль | Делает | Не имеет права |
+|---|---|---|
+| Аналитик | разбор, оценки, поверхности | окончательно ставить приоритет |
+| Автор ТЗ | `docs/specs/NN-*.md` или ТЗ в issue | ревьюить своё ТЗ |
+| Ревьюер ТЗ | `docs/reviews/SPEC-REVIEW-NN-rN.md` | править ТЗ вместо автора |
+| Разработчик | код, автотесты, документация, changelog | ревьюить свой код, принимать golden |
+| Ревьюер кода | `docs/reviews/CODE-REVIEW-*-rN.md`, проверка AC | править продуктовый код |
+| Релиз-менеджер | пре-релиз, стабильный релиз, закрытие issue | добавлять код в релизный коммит |
+| Владелец | приоритет, ценность, скоуп, отклонение, арбитраж, хотфикс | — |
+
+**Правило разделения:** ревьюер работает состязательно. Ему передаётся тег или
+диапазон коммитов и ТЗ — не рассказ автора о том, как всё хорошо.
+
+**Роли закреплены за исполнителями** (решение владельца 2026-08-12):
+
+| Исполнитель | Роли |
+|---|---|
+| **Codex** | аналитик, автор ТЗ, разработчик, релиз-инженер по команде владельца |
+| **Claude** | ревьюер ТЗ, ревьюер кода, вся инфраструктура и дистрибуция |
+| **Владелец** | приоритет, скоуп, арбитраж, закрытие issue, команда на выпуск |
+
+Автор и ревьюер — **разные модели**, и это сильнее требования «другая сессия»:
+одна модель, читая свой же артефакт заново, повторяет свои же слепые пятна.
+
+Ревью ТЗ и код-ревью держатся в **разных сессиях** Claude: ревьюер кода не должен
+приходить с контекстом того, как обсуждали ТЗ.
+
+---
+
+## 7. Артефакты и трассируемость
+
+### 7.1 Цепочка
+
+```
+issue #NN
+  ↔ ТЗ            docs/specs/NN-slug.md              (или тело issue при `small`)
+  ↔ ревью ТЗ      docs/reviews/SPEC-REVIEW-NN-rN.md  (или комментарий при `small`)
+  ↔ ветка         issue/NN-slug
+  ↔ коммиты       трейлеры  Issue: #NN · User-Visible: yes|no
+  ↔ ревью кода    docs/reviews/CODE-REVIEW-<tag|NN>-rN.md
+  ↔ changelog     бюллетень RU+EN со ссылкой на #NN
+  ↔ бета          тег, зелёный CI на точном SHA → закрытие
+```
+
+Обязательные разделы ТЗ: **сценарий** · **что человек увидит до и после** ·
+проблема · скоуп и **не-скоуп** · контракт поведения · UX · модель данных и
+миграция · i18n · критерии приёмки AC1…ACn с указанием доказательства · план
+автотестов · риски · откат · release-артефакты.
+
+Два первых раздела — продуктовые, и они идут первыми не случайно. **Сценарий:**
+какая персона (`docs/SCOPE.md`), на какой поверхности, в какой момент это
+встретит. **Что человек увидит:** одной фразой, без терминов реализации. ТЗ,
+которое не может ответить на эти два вопроса, описывает работу, а не изменение
+продукта.
+
+**Размытое место не додумывается, а выносится владельцу.** Догадка, записанная
+как факт, — худший вид дефекта: она проходит ревью, потому что выглядит решением.
+
+Но спрашивать обо всём нельзя: владелец один, и анкета из двадцати пунктов хуже
+угадывания. Порог такой (решение владельца 2026-08-13).
+
+**Владельцу задаются только продуктовые вопросы** — что человек видит или делает
+и какой объём видимых изменений входит в этот issue. Поведение в пограничном
+случае; какая из персон важнее в конфликте; что считать приемлемой деградацией;
+относится ли смежное поведение сюда или становится отдельной задачей.
+
+**Всё, чего пользователь не наблюдает, агенты решают сами** либо согласовывают
+между собой: где хранится состояние, в каком модуле стоит гвард, именование,
+раскладка файлов, стратегия тестов, механика миграции. Решение записывается явным
+блоком в конце ТЗ — «принято предположительно, поменять свободно», и ревьюер
+вправе его оспорить. Технический спор автора и ревьюера решается вердиктом, а не
+владельцем; до него он доходит только при исчерпании лимита циклов (§4).
+
+**Смешанный вопрос делится, а не эскалируется целиком.** «Где живёт это
+состояние» — техническое. «Переживает ли оно перезагрузку страницы и общее ли оно
+для всех экранов» — продуктовое.
+
+Вопросы задаются **одним комментарием, пачкой**, каждый в форме: что неясно ·
+что изменится от ответа · **предлагаемый вариант по умолчанию**. Вопрос с готовым
+вариантом стоит владельцу пяти секунд, вопрос без него — пяти минут. Пока ждём
+ответа, issue остаётся в `S3-spec` и получает `blocked`: статус не подменяется,
+`blocked` его дополняет, иначе конвейер считает задачу в работе, а она стоит.
+
+### 7.2 Шаблоны комментариев
+
+Короткие и однообразные, чтобы читались и человеком, и машиной.
+
+- **Аналитика:** `Оценка: ценность N/10 · сложность N/10 · P<1-3> · тип ·
+  поверхности: … · дубликаты: … · лёгкий трек: да/нет`
+- **Занятие:** `Взял: <роль> · сессия <id> · ветка issue/NN-slug`
+- **Хендофф:** `Сделано: … · Файлы: … · Гейты: <команда → результат> ·
+  НЕ сделано: … · Риски: … · Следующий статус: … · Новые issue: #…`
+- **Вердикт ревью:** `Вердикт: зелёный/жёлтый/красный · цикл r<N>/<лимит> ·
+  High: N · Medium: N → #… · Документ: docs/reviews/…`
+- **Закрытие:** `Выпущено в <тег беты> · CI: <ссылка> · Changelog: <ссылка>`
+
+**Вперёд двигает только зелёный вердикт.** Жёлтый и красный возвращают автору;
+разница между ними содержательна для человека, но не для маршрута. Первая
+редакция конвейера (§10.4) пропускала жёлтый при `High: 0`, и первый же живой
+прогон показал, почему это неверно: жёлтый там означал, что AC описывает неверное
+изменение контракта — реализовать такое ТЗ значило бы сделать ошибку по инструкции.
+
+### 7.3 Расхождения с текущим состоянием, которые надо закрыть
+
+1. **Статус ТЗ дублирует статус issue.** `docs/specs/README.md` держит колонку
+   «Статус ТЗ» со своим словарём («черновик решения», «в реализации»,
+   «реализовано»). Два источника статуса уже расходятся. Колонку убрать, оставить
+   таблицу «issue ↔ ТЗ».
+2. **Ревью до релиза 1.62 живут вне репозитория.** Документы `CODE-REVIEW-*.md` и
+   `SPEC-REVIEW-*.md` за прежний период лежат в папке владельца, и переносить их
+   задним числом смысла нет: они описывают код, которого уже нет. Новые документы
+   ревью кладёт в `docs/reviews/` сам конвейер, в ветку задачи.
+
+---
+
+## 8. Гейты
+
+**Локальный гейт перед выходом из «В разработке»** — минимальный набор,
+покрывающий изменённые поверхности (действующее правило владельца):
+
+```
+npx tsc --noEmit
+npm test
+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
+node demo/smoke_<целевые>.mjs
+npm run golden:verify                 # если менялся визуал
+python -m pytest tests_backend -q     # py3.13, если менялся бэкенд
+```
+
+**Объём гейтов на код-ревью соразмерен задаче** (issue #127). Всегда:
+`typecheck`, `npm test`, `npm run build` со сверкой трёх копий бандла. По
+необходимости, определяемой diff'ом и AC: браузерные смоки (их 127 — прогон всех
+уместен только когда задача задевает всё), `golden:verify` при изменении видимого
+результата, `pytest tests_backend` при правках в Python, performance-профили при
+названном в AC влиянии. **Полные наборы — предрелизный гейт, а не гейт ревью.**
+
+Условие честности такого сужения: ревьюер обязан перечислить, какие гейты прогнал,
+какие нет и почему. Непрогнанный гейт становится видимым решением, а не молчаливым
+пропуском.
+
+**Гейт беты** (условие закрытия issue): CI Validate зелёный на точном SHA тега.
+
+Часть гейтов запускается только здесь, то есть **после** пройденного код-ревью.
+Упавший предрелизный гейт автор чинит и повторно прогоняет; зелёный прогон
+достаточен для продолжения релиза, повторное код-ревью не требуется — §11.4.
+
+**Гейт стабильного релиза:** полный локальный прогон плюс Validate и Full
+Performance зелёные на точном SHA; статусов issue не касается.
+
+---
+
+## 9. Метки — канонический статус
+
+Статус читается из меток: их видно в списке issue и их читает любой токен с
+доступом к Issues, в отличие от Project v2, который требует отдельного скоупа.
+Project v2 остаётся человеческим представлением и синхронизируется по меткам.
+
+**Имена меток английские** (решение владельца 2026-08-12). Русские имена в этом
+документе были только на бумаге; репозиторий с самого начала жил на английских.
+
+| Метка | Статус |
+|---|---|
+| `S1-new` | Новое, не разобрано |
+| `S2-analysis` | Аналитика и оценка |
+| `S3-spec` | ТЗ в работе |
+| `S4-spec-review` | ТЗ на ревью |
+| `S5-ready` | Готово к разработке — единственный статус, из которого можно начать трогать код |
+| `S6-in-progress` | В разработке, занято исполнителем |
+| `S7-code-review` | Код-ревью |
+| `S8-merged` | Ревью пройдено, код в `dev`, ждёт беты. Issue закрывается пачкой при выпуске |
+| `blocked` | Ждём внешнего или владельца, **поверх** статусной метки |
+| `rejected` | Отклонено, issue закрыт |
+
+Модификаторы: `small` (лёгкий трек, сложность ≤3), `trivial` (короткий трек,
+§5.1), `hotfix`, `process`, `review-4`; приоритет `P1`/`P2`/`P3`; тип `bug`/`feature`/`tech-debt`.
+Тематические метки (`polish`, `infra`, `tests`, `docs`, `security`, `vacuum`)
+ортогональны процессу.
+
+Инварианты: **ровно одна `S*`-метка** на открытом issue; закрытый issue статусных
+меток не несёт; `blocked` не заменяет статус, а дополняет его.
+
+**Чужой issue берётся в работу так же, как свой — после явного решения
+владельца** (решение владельца 2026-08-13, уточнено в тот же день). Репозиторий
+публичный, отчёты заводят и посторонние; проверка стоит **на входе**, а не на
+каждом шаге.
+
+Входом служит присвоение первой статусной метки: пока меток нет, issue вне
+процесса и инварианты на него не распространяются. Как только метка стоит, задача
+в работе, и **кто её завёл, дальше не имеет значения** — статусы, ревью и лимиты
+работают одинаково.
+
+Присвоение метки и есть то самое явное решение, причём проверенное платформой:
+метки может ставить только тот, у кого есть право записи в репозиторий. Прежняя
+редакция требовала переоформлять чужой отчёт своим issue со ссылкой на исходный;
+это оказалось работой впустую — на #123 к моменту отказа ТЗ уже было написано.
+
+`S8-merged` появился позже остальных и закрывает разрыв, который раньше
+закрывался памятью человека: код принят, но бета ещё не вышла, и issue закрывать
+рано. Без него принятая задача либо висела в `S7-code-review`, либо закрывалась
+досрочно.
+
+---
+
+## 10. Механизация при прямых коммитах в `dev`
+
+Решение владельца — работать без PR. Значит, GitHub не может ничего заблокировать
+на своей стороне: **основной гейт переезжает на клиента, CI остаётся страховкой.**
+
+### 10.1 Хуки, которые невозможно забыть поставить
+
+`.githooks/` в репозитории, `core.hooksPath` выставляется автоматически при
+установке зависимостей:
+
+```json
+"scripts": { "prepare": "node scripts/install-hooks.mjs" }
+```
+
+`npm ci` вызывает `prepare` сам — значит, хуки появляются в каждом окружении,
+включая свежий контейнер облачного агента, без отдельного шага в инструкции.
+
+- **`commit-msg`** — есть, работает. Отклоняет коммит без терминального
+  `Issue: #NN`, требует ровно один `User-Visible: yes|no`, а для коммитов,
+  трогающих `demo/golden/baselines/**`, — `Release:` плюс `Baseline-Reviewed:`.
+  Реализация — `scripts/validate-commit-provenance.mjs`, тот же скрипт вызывается
+  job `provenance` в `validate.yml`.
+- **`pre-push`** — есть, работает. Прогоняет `scripts/process-gate.mjs` по каждому
+  пушимому ref и останавливает push при нарушении. Это и есть блокирующий гейт
+  вместо PR. Удаление ветки и теги пропускаются: в первом случае проверять нечего,
+  во втором коммит уже проверен, когда его пушили. Для новой ветки диапазон
+  считается от `merge-base` с `origin/dev`, а не от начала истории — иначе в него
+  попали бы все нарушения, совершённые до появления гейта.
+
+  Проверка статуса issue требует `gh`, поэтому при его отсутствии хук печатает
+  предупреждение и выполняет только офлайн-часть. Это сознательная уступка: хук,
+  который не работает в самолёте, отключают целиком, а строгий проход всё равно
+  делает CI.
+
+**Хук обязан быть исполняемым, и это тише всего ломается.** Git **молча** не
+запускает файл без бита `+x`: гейт сообщает об успехе тем, что его нет. Проверено
+на настоящем push — при `644` от гейта ноль строк и push проходит, при `755` он
+останавливается.
+
+Через GitHub API режим не выставляется: файл, отправленный так, приезжает
+`100644`. Поэтому `scripts/install-hooks.mjs` восстанавливает бит при каждой
+установке зависимостей, а `assertHookMode` дополнительно проверяет бит
+`.githooks/commit-msg` в индексе. Правится вручную:
+`git update-index --chmod=+x .githooks/<хук>`.
+
+### 10.2 Что проверяет `process-gate.mjs`
+
+Реализовано, `scripts/process-gate.mjs`, issue #105. Офлайн, без GitHub API:
+
+1. трейлер `Issue: #NN` у каждого коммита класса A/B, допускается несколько;
+2. имя ветки `issue/NN-slug` соответствует трейлерам;
+3. для класса A существует `docs/specs/NN-*.md` — **или** issue помечен `small`.
+   Офлайн это предупреждение: лёгкий трек держит ТЗ в теле issue, и без чтения
+   меток «ТЗ в issue» неотличимо от «ТЗ не написано». С `--issues` — отказ;
+4. `User-Visible: yes` → правки в обоих changelog в том же коммите;
+5. коммит только класса D невалиден без `Release: vX.Y.Z` либо
+   `Baseline-Reviewed: <ссылка на прогон CI>`;
+6. релизный коммит не содержит изменений в `src/` и `custom_components/**/*.py`;
+7. документов ревью на один issue не больше четырёх (`-r1`…`-r4`).
+
+С токеном GitHub:
+
+8. `--issues` тянет каждый упомянутый issue и требует метку из
+   {`S5-ready`, `S6-in-progress`, `S7-code-review`, `S8-merged`}; закрытый,
+   недоступный или помеченный `blocked` — отказ (**fail closed**).
+
+ Три оговорки к проверке 8 выяснились при реализации.
+
+**`S8-merged` входит в множество**, хотя по смыслу задача уже принята. Причина
+механическая: конвейер (§10.4) сливает ветку в `dev` **раньше**, чем ставит метку,
+Validate стартует от этого push и успевает прочитать issue уже в `S8-merged`.
+Строгое множество красило бы каждую принятую задачу. Локальная строгость
+возвращается флагом `--no-merged`.
+
+**Статус спрашивается только у коммитов класса A/B.** Правило №1 говорит о
+продуктовом коде и инструментах, а не о документации. Иначе краснел бы каждый
+документ ревью: он ложится в ветку задачи, пока та в `S4-spec-review` или
+`S7-code-review`, то есть заведомо вне рабочего множества.
+
+**При продвижении в `main` не перепроверяются коммиты, уже достижимые из
+prerelease-тега.** После выпуска беты их issue по §2.8 должны быть закрыты, а
+stable fast-forward снова включает эти коммиты в диапазон `old-main..candidate`.
+Pre-push передаёт целевую remote ref через `--target-ref`, а Validate — через
+`TARGET_REF`; оба исключают только уже опубликованную prerelease-историю. Любой
+post-beta коммит остаётся в проверке и по закрытому issue отклоняется fail-closed.
+
+Не реализовано и остаётся долгом:
+
+9. `npm run release:prerelease -- --issues=…` не проверяет, есть ли у issue
+   зелёный вердикт код-ревью;
+10. закрытие issue и снятие статусных меток при публикации беты делаются руками —
+    `node process-labels/apply.mjs cleanup --apply`, а не `publish-prerelease.yml`.
+    Пропуск этого шага уже ломал инвариант «закрытый issue без статусной метки».
+
+### 10.3 Страховка и разбор
+
+- **`process-gate.mjs` — job `process-gate` в `validate.yml`**, без `needs`:
+  краснеет сам и не роняет остальные. При прямом push проверка догоняющая: код уже
+  в `dev`, CI краснеет после. Это принятая цена отказа от PR: `pre-push` ловит
+  нарушение до отправки, а этот job — то, что прошло мимо хука, включая
+  `--no-verify` и окружение без установленных зависимостей.
+- **Нарушение не откатывается force-push'ем** (правило 17): исправляющий коммит
+  плюс issue с меткой `process`. Починить надо проверку, а не только симптом.
+- **Еженедельная гигиена** (workflow): issue в `S1-new` дольше 14 дней и в
+  `S6-in-progress` дольше 7; issue класса A в `S5-ready` без ТЗ; issue с нулём или
+  двумя `S*`-метками; коммиты без трейлера за неделю — **цель 0**; rework rate и
+  число issue, дошедших до `review-4`; **баги, заведённые после закрытия беты** —
+  прямая цена отказа от фазы тестирования.
+
+### 10.4 Событийный конвейер: метка как триггер
+
+`.github/workflows/process.yml`, issue #114. Смена статусной метки — не запись в
+журнал, а **сообщение**: она порождает событие, событие запускает следующий шаг.
+
+```
+S4-spec-review → ревью ТЗ  → S5-ready  либо возврат в S3-spec
+S7-code-review → код-ревью → слияние в dev → S8-merged либо возврат в S6-in-progress
+```
+
+Ревьюер — `anthropics/claude-code-action`. Он читает `docs/SCOPE.md`, `AGENTS.md`,
+этот документ и тело issue, публикует разбор комментарием, заводит issue на каждую
+Medium-находку, кладёт документ в `docs/reviews/` ветки задачи и возвращает вердикт
+структурированным JSON. **Метку переставляет отдельный детерминированный шаг по
+вердикту, а не модель.**
+
+Четыре вещи, без которых конвейер молча не работает:
+
+1. метки переставляет **PAT**, а не `GITHUB_TOKEN`: GitHub намеренно не порождает
+   события от `GITHUB_TOKEN`, чтобы не было циклов, и цепочка обрывалась бы после
+   первого шага без ошибок в логах;
+2. `process.yml` обязан лежать в **ветке по умолчанию**: для события `issues`
+   GitHub берёт workflow только оттуда, независимо от содержимого `dev`;
+3. слияние в `dev` происходит **до** простановки `S8-merged`, иначе метка врёт в
+   промежутке — она утверждает, что код в `dev`;
+4. многострочный текст внутри `run:` — только через heredoc: строка с нулевым
+   отступом обрывает блок YAML, и скрипт обрезается без ошибки парсера.
+
+**Автор обязан дождаться вердикта, а не заканчивать сессию.** Ревью идёт от десяти
+минут до сорока пяти. Отчёт «передал на ревью» останавливает конвейер там, где он
+мог идти сам: вердикт придёт, а подхватить его будет некому. У агента нет часов —
+он существует только в момент своего хода, поэтому ожидание это опрос: раз в 90
+секунд, не более 30 попыток. Смотреть на метку, а не на комментарий: метка и есть
+состояние. При `blocked` не ждать — задача ждёт владельца.
+
+**После прогона ревью метка меняется всегда.** Инвариант появился не сразу: первая
+редакция при конфликте слияния оставляла метку на месте, и это оказалось тупиком —
+автор ждёт смену метки, метка не менялась, и он тридцать раз опрашивал впустую,
+чтобы отчитаться «лимит исчерпан» при зелёном вердикте. Состояние, из которого
+никто не может выйти и о котором никто не узнает, для конвейера хуже громкой
+ошибки.
+
+Поэтому зелёное код-ревью с неудавшимся слиянием ведёт не в `S8-merged`, а в
+`S6-in-progress`: работа действительно вернулась к автору, только осталась не
+правка кода, а ребейз. Вердикт при этом в силе, переделывать нечего. После ребейза
+метка `S7-code-review` возвращается и ревью идёт заново — не формальность:
+после ребейза на ушедший вперёд `dev` это другой код.
+
+Если метка не сменилась, значит упал сам прогон, а не работа: смотреть логи и
+сообщать владельцу, а не продолжать опрос.
+
+Цикл считается **по этапу**: вердикт по ТЗ не расходует бюджет код-ревью. Раньше
+считались все вердикты подряд, и первое код-ревью #89 получило `r2/4`.
+
+---
+
+## 11. Исключения
+
+### 11.1 Лёгкий трек
+
+См. §5 — это не исключение из правила №1, а более дешёвый путь по тем же статусам.
+
+### 11.2 Аварийный хотфикс (метка `hotfix`, решение владельца)
+
+Разрешено писать код до появления issue. Обязательно:
+
+- issue создан в **той же сессии до коммита**, метка `hotfix`;
+- ТЗ «как сделано» + раздел «почему нельзя было ждать»;
+- в течение 24 часов задача ретроспективно проходит код-ревью;
+- аварийность названа явно в релизном хендоффе (действующее правило `AGENTS.md`).
+
+### 11.3 Гигиена репозитория
+
+Механические изменения без изменения поведения (форматирование, мёртвые файлы)
+идут под квартальный umbrella-issue «Гигиена репозитория»; каждый коммит
+ссылается на него. Трассируемость 1:1 сохраняется.
+
+### 11.4 Починка предрелизных гейтов без повторного код-ревью
+
+Решение владельца 2026-08-13.
+
+В цикле реализации гоняется только лёгкий набор — typecheck, unit, build (§8).
+Golden, браузерные смоки, performance и полный HA-харнесс запускаются перед бетой,
+то есть **после** того, как код-ревью пройдено и issue в `S8-merged`. Часть
+проблем физически не может быть найдена раньше.
+
+**Если предрелизный гейт упал, автор правит, повторно прогоняет упавшее, и
+зелёного прогона достаточно, чтобы релиз продолжился.** Issue остаётся в
+`S8-merged` и на повторное код-ревью не отправляется.
+
+Причина: полный цикл ревью в момент выпуска стоит дороже, чем риск, который он
+здесь снимает. Гейт уже назвал дефект точно, а исправление проверяется тем же
+гейтом — то есть проверка объективна и не зависит от чьего-либо суждения.
+
+**Что при этом обязательно:**
+
+- прогон упавшего гейта записан в issue: **точная команда и её результат**.
+  «Verified» без команды доказательством не является (§8);
+- трейлеры на коммите как обычно, `Issue: #NN` того же issue;
+- при `User-Visible: yes` — правки в оба changelog в том же коммите;
+- эталоны golden принимаются только через `npm run golden:accept -- --reviewed`
+  на полном артефакте Linux CI. «Чтобы гейт позеленел» основанием не является.
+
+**Границы, за которыми исключение не действует.** Оно про починку названного
+гейтом дефекта, а не про продолжение разработки под видом починки. Правка идёт
+обычным путём — новым issue либо возвратом в `S6-in-progress` — если она:
+
+- меняет контракт поведения или добавляет пользователю что-то новое;
+- задевает подсистему, которой в исходной задаче не было;
+- по объёму сопоставима с самой задачей;
+- меняет сам гейт вместо кода — правка теста, чтобы он перестал падать, это не
+  починка, а сокрытие. Исключение — когда дефект **в фикстуре** и это доказано
+  разбором, как на #89: солнце на азимуте 180° и единственное окно на северной
+  стене, поэтому луч честно не строился.
+
+Границу определяет автор, и здесь процесс сознательно отдаёт ему то, что в
+остальных местах не доверяет — оценку собственной работы. Плата за скорость в
+единственной точке, где цикл ревью стоит дороже всего. Компенсируется тем, что
+запись в issue публична и релиз-менеджер видит, что именно было сделано перед
+выпуском.
+
+Это исключение из правила «код-ревью не пропускается никогда» (§5, §7.1) —
+единственное, и относится только к окну между `S8-merged` и выпуском.
+
+---
+
+## 12. Запрещено
+
+- код без issue или из статуса раньше «Готово к разработке»;
+- ТЗ, написанное после кода (кроме §11.2, и тогда с пометкой «как сделано»);
+- ревью своей работы; перевод своей работы через ревью-гейт;
+- пятый цикл ревью вместо разбора по §4;
+- заведение issue вместо возврата на правки, чтобы обойти лимит циклов;
+- принятие golden-эталонов ради зелёного CI или по частичному артефакту;
+- закрытие issue до выпуска беты с зелёным CI;
+- переоткрытие закрытого issue вместо нового бага;
+- Medium-находки, оставленные как TODO в документе ревью;
+- **параллельные бэклоги** в файлах (`BACKLOG-*.md`, «планы» в docs);
+- ревью-документы вне репозитория;
+- попутные правки «раз уж я здесь»;
+- фича или материальное изменение поведения в стабильном релиз-коммите;
+- force-push в `dev`;
+- ручное копирование на домашний инстанс.
+
+**Нарушение процесса — тоже issue** (метка `process`): если правило удалось
+нарушить незаметно, виновата проверка.
+
+---
+
+## 13. Внедрение
+
+Состояние на 2026-08-13.
+
+1. ✅ **Метки созданы, бэклог размечен.** У всех открытых issue владельца ровно
+   одна `S*`-метка, инварианты чистые.
+2. ⏳ **Колонку «Статус ТЗ» из `docs/specs/README.md` убрать** — не сделано, §7.3
+   п.1. Перенос старых документов ревью в `docs/reviews/` отменён: они описывают
+   код, которого уже нет.
+3. ✅ **Гейт написан** — `scripts/process-gate.mjs` плюс job в `validate.yml`,
+   issue #105. Прошёл **вне** флоу как инфраструктурная задача (§1, issue #118), а
+   не через ТЗ и ревью, как предполагала прежняя редакция этого пункта.
+4. ✅ **Долг ревью списан решением владельца.** Беты `beta.2`…`beta.10` сделаны по
+   прежнему процессу и не пересматриваются. Точка отсчёта — релиз 1.62.0; отсчёт
+   начинается с первой беты следующей линии.
+5. ⏳ Завести issue на находку «смок `visual_continuity` не умеет падать» — это
+   ровно тот класс дефектов, который в процессе без ручного тестирования стоит
+   дороже всего.
+6. ✅ `BACKLOG-2026-08-11.md` — разовый отчёт, решения живут в issue.
+7. ✅ `AGENTS.md` переписан целиком, шире блока §14.
+8. ✅ **Канон перенесён в репозиторий** (issue #112). До этого полный процесс жил
+   только в папке владельца, а в репозитории лежал файл на 51 строку про трейлеры
+   коммитов — из свежего клона канон не был виден вообще.
+9. ✅ **`pre-push` написан** (§10.1, issue #121). Блокирующая проверка на клиенте
+   есть; обойти её можно только `--no-verify`, и тогда то же найдёт CI.
+
+---
+
+## 14. Блок для AGENTS.md
+
+```markdown
+## Процесс: код только через issue
+
+Изменение продуктового кода без issue запрещено. Код меняется только из статуса
+«Готово к разработке» или дальше. Полные правила, критерии статусов и гейты —
+`docs/PROCESS.md`, читать до начала работы.
+
+Жизненный цикл (статус = метка issue): `S1-new` → `S2-analysis` → `S3-spec` →
+`S4-spec-review` → `S5-ready` → `S6-in-progress` → `S7-code-review` → `S8-merged`
+→ закрытие пачкой при выпуске беты. Оба ревью возвращают на правки не более 4
+циклов; пятый заход — разбор у владельца (разделить / отклонить / арбитраж).
+
+Ревью запускается **само** от меток `S4-spec-review` и `S7-code-review` и идёт до
+45 минут. Поставив такую метку, автор не заканчивает работу, а ждёт смены метки
+опросом и продолжает по тому, чем она стала.
+
+- ветка `issue/<NN>-<slug>`, коммиты с трейлерами `Issue: #NN` и `User-Visible: yes|no`;
+- работаем прямыми коммитами в `dev`, без PR: блокирующий гейт — локальный
+  `pre-push` (ставится автоматически через `npm ci`), CI — страховка. Force-push
+  в `dev` запрещён;
+- автор ≠ ревьюер, ни для ТЗ, ни для кода;
+- фазы ручного тестирования нет: автотесты пишутся в реализации, AC проверяет
+  код-ревью, найденные позже дефекты — новые issue типа «баг»;
+- мелкие задачи (метка `small`, сложность ≤3): ТЗ в теле issue, ревью ТЗ
+  комментарием, код-ревью — как обычно;
+- найденное вне скоупа — новый issue, а не попутная правка;
+- issue закрывает релиз-менеджер после выпуска беты, не исполнитель.
+```

README.md

@@ -1,10 +1,74 @@
-# 🏠 House Plan — an interactive house plan for Home Assistant
+# 🏠 House Plan — interactive floor plan card for Home Assistant
 
-**A live map of your home right inside Home Assistant: floors, rooms and devices on a real floor plan — with live states, temperature and signal strength. Everything is configured with the mouse, without a single line of YAML.**
+[![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)
+[![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)
 
-![House Plan demo](docs/images/demo.gif)
+**Turn Home Assistant into a live, interactive map of your home.** Upload or draw
+a floor plan, outline the rooms with your mouse — and every smart device appears
+in its real place: live states, tap-to-toggle lights, temperature and humidity per
+room, Zigbee signal maps, glowing light pools and a fullscreen kiosk mode for wall
+tablets. No YAML, no Inkscape, no external editors — the whole floorplan lives
+right on your Lovelace dashboard.
 
-🇷🇺 [Документация на русском](README.ru.md)
+> **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; 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 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.
 
 ---
 
@@ -28,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:
 
@@ -45,10 +120,39 @@ 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.
 
 ---
 
+## Wall tablet / TV (kiosk mode)
+
+Add the card to a dedicated dashboard with a **panel view** and set `kiosk: true`
+(or tick "Wall device (kiosk) mode" in the card editor):
+
+```yaml
+type: custom:houseplan-card
+kiosk: true
+cycle: 0   # seconds between auto space switches, 0 = off (nice for TVs)
+```
+
+No header, no editors — just the live plan. Swipe to change floors (at 1:1),
+pinch to zoom, double-tap to reset. Long-press an empty spot for 3 seconds to
+tune icon and text sizes for THIS screen (saved per device). To hide Home
+Assistant's own header use the companion app's kiosk settings or the
+[kiosk-mode](https://github.com/NemesisRE/kiosk-mode) plugin.
+
 ## Installation
 
 One click if you already run HACS:
@@ -109,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)
 
@@ -133,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.
 
@@ -152,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.
 
@@ -172,12 +278,15 @@ Switch to the **Devices** tab to arrange icons: drag them with the mouse, click
 
 ### Tap actions: control devices from the plan
 
-By default a tap on an icon opens its info card. In the card settings you can switch
-**Tap on a device** to *Toggle* — a tap then switches lights, sockets, fans and
-humidifiers directly on the plan (wall-tablet style). For safety, a card-wide toggle
-never affects locks, alarms, covers or valves; you can consciously enable toggle for a
-specific device (except locks and alarms — those never toggle from the plan) in its
-edit dialog. A **long press** always opens the info card.
+By default a tap on an icon opens its info card. A device can instead use the
+universal **Toggle state** action. Its editor shows the exact entity or configured
+group, the current state and what the next tap will do; when nothing can be toggled,
+it says so and the tap is a quiet no-op rather than an unexpected info-card fallback.
+Lights keep their convenient toggle default. Covers and valves use open/close/stop
+semantics automatically, while locks, alarm panels and secure garage/door/gate covers
+remain blocked. An exact entity binding never falls through to a sibling switch, and
+temporarily unavailable group members are skipped without erasing the configuration.
+A **long press** still opens the info card and right-click still opens HA more-info.
 
 ### Icon rules
 
@@ -193,6 +302,27 @@ You can also place a **single entity** (not just a whole device): start typing i
 
 Not everything has to be left to the automation. With the **＋** button in the header you can place any device, group or a **virtual point** on the plan (for example, an "Inlet valve" that does not exist as a device). Set a name, icon, model, link, description and, if you wish, attach a **PDF manual**.
 
+To represent a dumb physical lamp controlled by a smart relay, place a virtual
+point where the lamp really is and set **Light source → Always**. Manual colour,
+brightness and radius stay available even though the point has no HA entity.
+Then open the relay and add that plan source under **Controls other light
+sources**. The relay continues to show the aggregate working state, while Glow,
+room fill and statistics belong to the lamp's position. An unlinked passive
+Always source is deliberately constant-on. With several own `light.*`/`switch.*`
+entities, Always also offers a leading-entity selector; a missing saved choice
+is warned about and retained while a deterministic fallback is used.
+
+To make that virtual lamp manually switchable without creating a Home
+Assistant helper, also choose **Tap action → Toggle state** on the lamp itself.
+This exact combination — virtual binding, **Light source → Always**, and
+**Toggle state** — stores a shared on/off state in the House Plan integration.
+It survives page reloads and Home Assistant restarts and updates Glow, room
+fill/statistics, full cards and `houseplan-space-card` together. Any signed-in
+dashboard viewer may toggle it. While this manual mode is active, saved
+**Controls other light sources** remain intact but are not called; changing the
+role, binding or tap action restores their normal behaviour. This operational
+state is deliberately not part of plan exports or Home Assistant entities.
+
 The same dialog controls how the device looks on the plan. **Display** switches between the
 icon badge, an animated **presence ripple** (pulsing rings while the entity is active, a faint
 dot when idle — great for motion sensors) or both, with a per-device ring colour and size. The
@@ -201,6 +331,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
@@ -212,11 +346,29 @@ turned the way it is mounted.
 
 ---
 
+## Getting help & sharing your plan
+
+- 💬 **[Telegram chat — @ha_houseplan](https://t.me/ha_houseplan)** — questions,
+  setup help, feature ideas, and screenshots of your plans. The fastest way to
+  reach the author and other users.
+- 🐞 [GitHub issues](https://github.com/Matysh/houseplan-card/issues) — bug
+  reports and feature requests (please attach your House Plan version).
+- 💡 [GitHub discussions](https://github.com/Matysh/houseplan-card/discussions) —
+  longer-form ideas.
+- 📜 [Changelog](docs/CHANGELOG.md) — what changed in every version
+  ([на русском](docs/CHANGELOG.ru.md)).
+
+When reporting a problem, the version number helps a lot: it is shown in the
+browser console on load (`HOUSEPLAN-CARD vX.Y.Z`) and in **Settings → Devices &
+Services → House Plan**.
+
+---
+
 ## Frequently asked questions
 
 **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

@@ -1,13 +1,76 @@
-# 🏠 House Plan — интерактивный план дома для Home Assistant
+# 🏠 House Plan — интерактивный поэтажный план дома для Home Assistant
 
-**Живая карта вашего дома прямо в Home Assistant: этажи, комнаты и устройства на настоящем плане — с реальными состояниями, температурой и уровнем сигнала. Всё настраивается мышкой, без единой строчки YAML.**
+[![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)
 
-![House Plan demo](docs/images/demo.gif)
+📘 **[Полное руководство пользователя](docs/USER-GUIDE.ru.md)** · 🗂 **[Беклог проекта](https://github.com/users/Matysh/projects/1)**
 
-🇬🇧 [English documentation](README.md)
+**Превратите Home Assistant в живую интерактивную карту дома.** Загрузите или
+нарисуйте план этажа, обведите комнаты мышкой — и умные устройства появятся на
+своих местах: живые состояния, свет по клику, температура и влажность по
+комнатам, карта Zigbee-сигнала, светящиеся пятна ламп и полноэкранный
+киоск-режим для настенного планшета. Без 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** — один план для всех экранов, живая синхронизация.
 
 ---
 
+
 ## Что это и зачем
 
 House Plan показывает ваш умный дом так, как он выглядит на самом деле — на плане этажей. Вместо длинных списков сущностей вы видите комнаты и устройства на своих местах: где протечка, какая температура в детской, включён ли свет в прихожей, открыты ли ворота.
@@ -28,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
+на всех планшетах.
 
 Ключевые преимущества коротко:
 
@@ -45,10 +118,36 @@ House Plan показывает ваш умный дом так, как он в
 - **Автоматическое добавление устройств.** Обвели комнату и привязали её к зоне Home Assistant — устройства этой зоны сами появляются на плане.
 - **Ручное добавление своих.** Любое устройство, группу или даже «виртуальную» точку можно поставить на план вручную, задать имя, иконку, модель, ссылку и приложить PDF-инструкцию.
 - **Живые состояния.** Температура, уровень сигнала Zigbee, вкл/выкл, открыто/закрыто — всё обновляется в реальном времени.
+  Цвета значков подчиняются одному принципу — **жёлтый значит «устройство прямо сейчас выполняет свою основную работу»**:
+  лампа светит, розетка подаёт, вентилятор крутится, пылесос убирает, термоголовка
+  реально греет (а не просто включена). Для climate-сущностей переданное действие приоритетно;
+  если интеграция сообщает только включённый HVAC-режим, он служит лучшим доступным приближением.
+  Оранжевый = открыто / не заперто. Пульсирующее красное
+  кольцо = авария (протечка, дым, газ). Цвет RGB-лампы живёт в её пятне света (режим glow),
+  где само пятно — индикатор включения, а подложка значка остаётся стандартной.
+  Полупрозрачный значок = недоступно. Тёмный = покой.
+- **Единый визуальный редактор подложки.** Линии, фигуры, надписи и мебель используют общее выделение, физические стили и Undo/Redo. Картинка плана не прибита к холсту: отдельный инструмент двигает, масштабирует и поворачивает её, а числовой диалог задаёт точный размер и угол.
 - **Чёткий зум.** Приближение не «мылит» картинку: план, подписи и иконки остаются векторно-чёткими на любом масштабе.
 
 ---
 
+## Настенный планшет / ТВ (киоск-режим)
+
+Отдельный дашборд с view типа «панель», у карточки — `kiosk: true` (или
+галочка «Режим настенного устройства» в редакторе карточки):
+
+```yaml
+type: custom:houseplan-card
+kiosk: true
+cycle: 0   # автосмена пространств каждые N секунд, 0 = выкл (удобно для ТВ)
+```
+
+Без шапки и редакторов — только живой план. Свайп листает этажи (при 1:1),
+пинч — зум, двойной тап — сброс. Долгое нажатие (3 с) по пустому месту —
+настройка размеров значков и текста для ЭТОГО экрана (хранится на
+устройстве). Шапку самого Home Assistant скрывают настройки companion-app
+или плагин [kiosk-mode](https://github.com/NemesisRE/kiosk-mode).
+
 ## Установка
 
 В один клик, если у вас уже есть HACS:
@@ -111,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)
 
@@ -135,15 +234,15 @@ title: План дома
 - **Разделить** — кликните комнату, затем две точки на её стенах; хорда разрежет её надвое. Бо́льшая часть остаётся прежней комнатой (имя, зона, устройства), меньшая просит новое имя и зону.
 
 
-### Двери, окна и замки
+### Двери, окна, ворота и замки
 
-В режиме разметки инструмент **«Проём»** ставит двери и окна: кликните рядом со стеной — проём
+В режиме разметки инструмент **«Проём»** ставит двери, окна и ворота: кликните рядом со стеной — проём
 примагнитится к ней. Выберите тип, **длину в реальных сантиметрах** (по умолчанию дверь 90 см,
-окно 120 см), датчик открытия и — для двери — **замок**.
+окно 120 см, ворота 300 см), датчик открытия и — для двери или ворот — **замок**.
 
 С привязанным датчиком план оживает: створка двери поворачивается на петле, и дуга распахивания
 дорисовывается по мере открытия настоящей двери; окно раскрывает две створки. Пока открыто,
-подвижные части подсвечены акцентным цветом. У двери с замком рядом отображается замочек —
+подвижные части подсвечены акцентным цветом. Ворота не занимают полплана даже при ширине 3–4 м: две половинные створки показаны открытыми наружу всего на 10°, без большой дуги. Датчик, замок и пропуск света работают как у двери. У двери или ворот с замком рядом отображается замочек —
 зелёный, когда заперто, оранжевый, когда нет. Ради безопасности замок с плана **нельзя**
 переключить — клик по проёму показывает карточку с обоими статусами.
 
@@ -154,7 +253,7 @@ title: План дома
 
 Как только вы сохранили комнату с привязкой к зоне, **устройства этой зоны автоматически расставляются внутри контура**. Берутся те же устройства, что показаны на странице **Настройки → Устройства → (фильтр по нужной комнате)** — только осмысленные, без служебных записей, мостов и дубликатов.
 
-По умолчанию на план попадают только осмысленные устройства — служебные записи, мосты и дубликаты отфильтрованы. Если нужно видеть **вообще все** устройства зоны, включите в шапке кнопку **👁 «Показать все устройства»**.
+По умолчанию на план попадают только осмысленные устройства: нефизические (служебные записи, мосты, сцены, лампы, свёрнутые в световую группу) могут быть скрыты автоматически. Управление находится в левом нижнем углу диалога устройства: **«Скрыть»** убирает маркер после сохранения, а у уже скрытого маркера там же появляется **«Показать»**. Чтобы найти их, откройте редактор устройств и нажмите **«Скрытые и деактивированные»**: пользовательски скрытые устройства отображаются синими призраками. Деактивированное в HA устройство показывается серым служебным призраком и полностью исключается из данных и действий плана до повторной активации.
 
 Дальше можно просто пользоваться планом: клик по иконке открывает карточку устройства с моделью, ссылкой и кнопкой перехода в Home Assistant.
 
@@ -205,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)**.
+
 ---
 
 ## Удаление
@@ -216,11 +319,28 @@ title: План дома
 
 ---
 
+## Помощь и обмен опытом
+
+- 💬 **[Чат в Telegram — @ha_houseplan](https://t.me/ha_houseplan)** — вопросы,
+  помощь с настройкой, идеи и скриншоты ваших планов. Самый быстрый способ
+  связаться с автором и другими пользователями.
+- 🐞 [Issues на GitHub](https://github.com/Matysh/houseplan-card/issues) — баги
+  и запросы фич (пожалуйста, указывайте версию House Plan).
+- 💡 [Discussions](https://github.com/Matysh/houseplan-card/discussions) — для
+  развёрнутых обсуждений.
+- 📜 [История изменений](docs/CHANGELOG.ru.md) — что менялось в каждой версии.
+
+Версия видна в консоли браузера при загрузке (`HOUSEPLAN-CARD vX.Y.Z`) и в
+**Настройки → Устройства и службы → House Plan** — с ней разбираться сильно
+быстрее.
+
+---
+
 ## Часто задаваемые вопросы
 
 **Нужно ли что-то писать в YAML?** Нет. Единственная строчка — это добавление карточки на дашборд; всё остальное делается мышкой.
 
-**Мои устройства не появились на плане.** Устройство появляется, только если его зона в Home Assistant привязана к нарисованной комнате. Проверьте, что у устройства задана комната (Настройки → Устройства), а комната обведена и привязана к этой зоне. Если устройство есть, но скрыто курированием (мосты, служебные, дубликаты) — включите в шапке кнопку **👁 «Показать все устройства»**.
+**Мои устройства не появились на плане.** Устройство появляется, только если его зона в Home Assistant привязана к нарисованной комнате. Проверьте, что у устройства задана комната (Настройки → Устройства), а комната обведена и привязана к этой зоне. Откройте **«Скрытые и деактивированные»**: синий призрак можно показать в его диалоге, серый сначала нужно активировать в Home Assistant.
 
 **Можно ли скрыть лишнее устройство или переименовать его?** Да — кликните по устройству на плане и в его карточке нажмите «Редактировать»: там можно сменить имя, иконку, модель или скрыть значок.
 

SPEC-REVIEW-089-isometric-view-stage1.md

@@ -0,0 +1,503 @@
+# Ревью ТЗ `docs/specs/089-isometric-view-stage1.md`
+
+Дата ревью: 2026-08-11  
+Issue: [#89](https://github.com/Matysh/houseplan-card/issues/89)  
+Проверенная версия ТЗ: локальный `dev`, после `v1.62.0-beta.1`, SHA `2cf5c27`
+
+## Итог
+
+Направление выбрано правильно: фиксированная SVG-проекция, отсутствие новой
+модели данных, каноническая геометрия стен, плоские редакторы, скрытая поставка
+через Labs и обязательные golden/performance gates хорошо соответствуют
+текущей архитектуре House Plan.
+
+Однако статус **«готово к реализации» пока преждевременен**. В ТЗ остаются
+восемь блокирующих неоднозначностей. Главная из них — документ описывает
+проекцию точек, но не определяет переход между тремя реально существующими
+системами координат и не задаёт новый контракт viewport/frame. Если начать
+реализацию буквально по текущему тексту, наиболее вероятный результат —
+прыжок масштаба при переключении, рассинхронизация HTML-маркеров и SVG, неверный
+warm-remount либо двойное обратное преобразование pointer events.
+
+Рекомендация: внести блокеры B1–B8 и существенные замечания M1–M8 в ТЗ, после
+чего документ можно переводить в `approved`. Переписывать продуктовую часть
+или менять выбранный renderer не требуется.
+
+## Что уже зафиксировано хорошо
+
+1. Labs не меняет backend, schema/config/layout и не попадает в backup.
+2. Плоский вид остаётся default и fallback; редакторы остаются плоскими.
+3. CSS 3D, WebGL и многократное клонирование SVG явно запрещены.
+4. Источник wall geometry — `wallBodiesGeometry()`, а не новый параллельный
+   контур.
+5. Проёмы должны быть настоящими разрывами masonry geometry.
+6. Glow сохраняет один регион на источник и один blur на слой по `LIGHT.md`.
+7. Кэш не должен зависеть только от `_cfgEpoch`.
+8. У stage 1 нет публичного обещания и пользовательской миграции.
+
+---
+
+## Блокирующие замечания
+
+### B1 — Не определены системы координат, pivot и projected frame
+
+**Где:** §4, §7, §8, AC 8.  
+**Критичность:** blocker.
+
+`projectPoint(p, z, cam)` и `unprojectPoint(screen, cam)` недостаточны для
+существующего renderer. Сейчас House Plan различает как минимум:
+
+- plan/model units (`room`, `wall`, `marker`);
+- координаты SVG scene/viewBox (`_view`);
+- client pixels внутри `.stage` (`_screenToVb()`).
+
+В объёмном виде plan units и scene units перестают совпадать. Кроме того,
+`IsoCamera` не содержит pivot/origin и масштаба оси Z. Проекция вокруг `(0, 0)`
+сместит план при смене пространства, а старый `_baseVb()` не включает поднятые
+верхние грани и начнёт обрезать стены.
+
+**Что добавить в ТЗ:**
+
+```ts
+type PlanPoint = readonly [number, number];
+type ScenePoint = readonly [number, number];
+
+interface IsoCamera {
+  rotDeg: number;
+  tiltDeg: number;
+  xyScale: number;
+  zScale: number;
+  origin: PlanPoint;
+}
+
+projectPlanPoint(p: PlanPoint, zUnits: number, cam: IsoCamera): ScenePoint;
+unprojectFloorPoint(p: ScenePoint, cam: IsoCamera): PlanPoint; // только z=0
+clientToScenePoint(client: readonly [number, number], stageRect: DOMRectReadOnly,
+  view: ViewRect): ScenePoint;
+projectedFrame(input: IsoFrameInput, cam: IsoCamera): ViewRect;
+```
+
+Нормативно определить:
+
+1. `projectPoint` возвращает **scene**, а не screen/client coordinates.
+2. `unprojectFloorPoint` инвертирует только плоскость `z=0`; высотная грань не
+   имеет единственной plan-точки.
+3. Pivot — одна фиксированная plan-space константа (рекомендуемо
+   `[NORM_W / 2, NORM_W / 2]`), а не центр viewport/content frame и не
+   положение курсора. Иначе появление far marker или переключение `_showFar`
+   сдвинет уже построенные стены без изменения их геометрии.
+4. Wall height сначала переводится из общей константы в plan units, затем
+   применяется `zScale`; выбранные значения фиксируются ADR.
+5. `fit`, pan clamp, home arrow, far-object hint и initial view используют
+   `projectedFrame`, включающий floor content и поднятые wall faces.
+6. Projected frame не зависит от текущего zoom/pan и входит в geometry cache.
+
+Без этого нельзя проверить «не меняет фокус плана скачком» и «не обрезает
+объекты».
+
+### B2 — Не задано преобразование viewport при flat ↔ iso и при входе в редактор
+
+**Где:** §7, §10, AC 7–9.  
+**Критичность:** blocker.
+
+Текущий `_view` хранит прямоугольник именно в координатах текущего SVG. Его
+нельзя без преобразования перенести из flat scene в iso scene. Текущий
+`_viewModeSnap` также хранит `cx/cy` в flat units. Требование «не менять zoom и
+фокус» сейчас не имеет алгоритма.
+
+**Добавить нормативный алгоритм:**
+
+1. Перед сменой проекции получить логический центр пола:
+   - flat: центр `_view` уже является plan point;
+   - iso: центр `_view` пропустить через `unprojectFloorPoint`.
+2. Построить target frame и target fit.
+3. Сохранить тот же scalar zoom.
+4. Спроецировать логический центр в target scene и вызвать `_applyView()` с
+   этим scene center.
+5. Не переиспользовать raw `x/y/w/h` между видами.
+6. Вход в editor выполняет тот же iso → flat переход; выход — flat → прежний
+   view kind. Смена пространства внутри editor сбрасывает старый snapshot по
+   существующему правилу.
+
+Предпочтение вида (`flat|iso`) и viewport — разные сущности. В localStorage
+пишется только предпочтение и существующий scalar zoom; raw viewport остаётся
+runtime/warm state.
+
+### B3 — ТЗ не совместимо с `docs/WARM-REMOUNT.md`
+
+**Где:** §7 «Непрерывность», §10.  
+**Критичность:** blocker.
+
+#73 переносит через `warmBoot` точный `_view`, `_viewModeSnap`, mode и
+fingerprint кадра. После введения iso один и тот же `ViewRect` имеет два разных
+смысла. Если новый экземпляр восстановит iso rectangle в flat mode (например,
+флаг снят/истёк) либо наоборот, получится именно тот скачок/пустой кадр, который
+#73 устраняет.
+
+**Добавить:**
+
+- warm viewport хранит `projection: 'flat'|'iso'` и `logicalCenter`;
+- raw `_view` усыновляется только при совпадении space, projection и активного
+  Labs contract;
+- при несовпадении восстанавливаются scalar zoom + logical center через
+  алгоритм B2, а не чужой rectangle;
+- frame fingerprint включает effective projection и iso geometry fingerprint;
+- выключение/expiry Labs никогда не может воскресить iso DOM из memo;
+- отдельный smoke: iso → remount → тот же iso frame; iso → снять flag →
+  remount → корректный flat frame без veil/flash.
+
+### B4 — Правило «все попадания через unproject» технически неверно
+
+**Где:** §7 Pointer, §11 smoke Pointer.  
+**Критичность:** blocker.
+
+SVG сам hit-тестирует элементы внутри трансформированного `<g>`. Room hover и
+SVG opening symbols не нужно вручную unproject-ить: это даст двойное
+преобразование. HTML marker также получает click как обычный DOM-элемент.
+Кроме того, marker drag выполняется в Device editor, а по этому же ТЗ все
+редакторы плоские; smoke «перетаскивание маркера в объёмном виде» противоречит
+scope.
+
+**Заменить правило на:**
+
+- SVG/HTML interactive children используют нативный DOM/SVG hit-test;
+- pan и zoom anchor работают в scene coordinates;
+- `client → scene → unprojectFloor` применяется только там, где stage event
+  действительно должен получить plan coordinate;
+- в stage 1 iso mode не создаёт/редактирует geometry и не перетаскивает
+  markers, поэтому editor `_svgPoint()` остаётся flat;
+- тесты кликают реальные room/device/opening DOM targets и проверяют action;
+  отдельный unit проверяет `client → scene → floor` для будущего использования.
+
+### B5 — Kiosk UX противоречит фактическому DOM
+
+**Где:** §3, §7, AC 2/4.  
+**Критичность:** blocker.
+
+ТЗ обещает кнопку «в режиме просмотра (и в киоске) рядом с шапкой». В текущем
+kiosk вся `.hdr.kioskhide` имеет `display:none`; такой кнопки физически не
+будет. Одновременно §7 говорит, что скрытая панель не должна лишить пользователя
+возврата в flat.
+
+Для скрытого stage 1 рекомендуется закрепить простой вариант:
+
+1. Кнопка существует только в обычном View под активным Labs.
+2. Kiosk читает последнее per-space предпочтение этого браузера.
+3. `hp-labs=-iso` или `hp-labs=off` — обязательный аварийный путь: kiosk сразу
+   становится flat и не может восстановить iso из warm memo.
+4. В kiosk нет новой панели/диалога stage 1.
+5. Smoke покрывает загрузку kiosk с сохранённым `iso` и возврат в flat через
+   URL operation.
+
+Если владельцу нужен переключатель прямо в kiosk, его надо отдельно поместить
+в существующий long-press kiosk dialog; «рядом с шапкой» всё равно неверно.
+
+### B6 — Грамматика Labs содержит противоречия и ломает комбинированный hash
+
+**Где:** §2.2–2.4.  
+**Критичность:** blocker.
+
+Не определено:
+
+- кто сильнее при одновременных `?hp-labs=` и `#hp-labs=`;
+- является URL полным replacement или операциями над storage;
+- что делает `iso,-iso`, `off,iso`, повторный параметр;
+- §2.2 требует не удалять параметр из URL, а §2.3 говорит, что `off` «очищает
+  и то, и другое»;
+- как `#space=x&hp-labs=iso` сохраняет существующий deep link;
+- что происходит при `history.back()`/`popstate`.
+
+**Предлагаемый точный контракт:**
+
+1. База — валидный набор из storage.
+2. Query operations применяются слева направо, затем hash operations слева
+   направо; hash сильнее, потому что именно он реактивен внутри Lovelace.
+3. `id` добавляет, `-id` удаляет, `off` очищает набор в этой позиции; следующие
+   токены снова могут добавлять.
+4. Повторные `hp-labs` обрабатываются в порядке появления.
+5. Если в URL был хотя бы один известный operation или `off`, итог пишется в
+   storage. Неизвестные значения сами по себе storage не переписывают.
+6. URL никогда не переписывается механизмом Labs. Из §2.3 убрать слова об
+   очистке URL: `off` очищает **effective set и storage**, но остаётся видимым.
+7. Hash разбирается общим helper вместе с `space`; оба порядка параметров и
+   percent-encoding тестируются. `_hashSpace()` не остаётся вторым regex parser.
+8. `hashchange` реактивен; `popstate` перечитывает query/hash, если URL реально
+   сменился без reload.
+
+### B7 — Не определена топология side faces и смысл «нет торцов в проёме»
+
+**Где:** §5, AC 3/5/6.  
+**Критичность:** blocker.
+
+`wallBodiesGeometry().geom` — MultiPolygon с внешними и внутренними rings, уже
+после union, junction patches и opening cuts. «Граничные рёбра» недостаточно:
+нужно определить winding, outward normal, holes, culling и порядок отрисовки.
+Фраза «без торцов внутри проёма» двусмысленна. При полном разрыве стены
+вертикальные jamb faces по краям проёма являются корректной частью объёма;
+запретить их — значит получить визуально обрезанную плёнку вместо стены.
+
+**Добавить:**
+
+- faces строятся непосредственно из rings канонического MultiPolygon после
+  union/cuts; исходные room edges для extrusion не используются;
+- winding нормализуется один раз, outward normal учитывает outer/hole ring;
+- face видима по знаку dot product normal и фиксированного view direction;
+- для фиксированной камеры задаётся детерминированный stable depth order;
+- opening slot создаёт две exposed jamb faces по концам разрыва — они нужны;
+- запрещены face/полоса, пересекающая сам gap, и cap на floor тоннеля;
+- на stage 1 дверь, окно и ворота являются full-height gaps осознанно, так как
+  модель не хранит высоту подоконника;
+- opening никогда не вырезает coincident partition/column — сохраняется
+  текущий порядок union extras после room opening cuts;
+- top face использует whole geometry с `fill-rule:evenodd`;
+- unit fixtures включают outer ring, hole, multipolygon, T/X join, opening у
+  угла и coincident independent body.
+
+### B8 — Fallback может зациклить exception и оставить кнопку во лжи
+
+**Где:** §9, AC 10.  
+**Критичность:** blocker.
+
+«Вернуться в flat на этом кадре» не отвечает на вопросы: будет ли следующий
+Lit render снова падать, что показывает `aria-pressed`, сохраняется ли `iso` в
+localStorage и когда разрешён retry.
+
+**Добавить state machine:**
+
+- `desiredView` — сохранённое предпочтение;
+- `effectiveView` — реально нарисованный `flat|iso`;
+- исключение в pure geometry/iso template ловится на границе
+  `renderIsoScene()`, для `(space, geometryFingerprint)` ставится session latch;
+- при latch effective view = flat, iso geometry больше не вызывается на каждом
+  HA state update;
+- конфиг/layout и сохранённое предпочтение не меняются автоматически;
+- кнопка отражает `effectiveView` (`aria-pressed=false`), явное повторное
+  нажатие или новый geometry fingerprint очищает latch и делает один retry;
+- console error содержит issue, space, fingerprint и короткий reason, но без
+  config/entity payload; один раз на latch;
+- ошибка HTML overlay projection также входит в эту границу, иначе получится
+  «стены flat, markers iso».
+
+---
+
+## Существенные замечания
+
+### M1 — Spike ADR должен фиксировать больше, чем выбор renderer
+
+Сейчас D6 требует ADR, но его обязательные решения не перечислены. ADR должен
+закрыть до основной реализации:
+
+- формулу и pivot проекции;
+- camera constants, wall-height units и zScale;
+- top/side fill, stroke, hatch и side shading в light/dark theme;
+- ring normalization, face visibility и depth order;
+- z-order floor → Glow/sun/decor → faces/top → screen-facing HTML overlays;
+- осознанное правило stage 1: markers/room cards всегда выше wall faces и не
+  получают геометрическую occlusion;
+- projected frame и flat↔iso viewport conversion;
+- результат проверки SVG filter/clip/mix-blend на Chromium, Firefox, WebKit;
+- причины отказа от проигравшего прототипа.
+
+До ADR issue остаётся в статусе spike/implementation-prep, не renderer-ready.
+
+### M2 — Fingerprint перечисляет не все входы iso geometry
+
+В §8 добавить как минимум:
+
+- `room_drafts` и их segment thickness;
+- нормализованные `openCuts`/virtual intervals;
+- canonical opening cuts;
+- partitions и columns с shape/angle/diameter;
+- `cell_cm`, grid pitch, coordinate scale/NORM;
+- camera constants и wall-height constant;
+- версию алгоритма projection/faces.
+
+Массивы должны сериализоваться детерминированно, числа — нормализоваться как в
+существующих geometry fingerprints. Display state (`hover`, HA states,
+`show_borders`) не должен инвалидировать geometry cache. `show_borders:false`
+просто не рисует cached top/sides, но physics остаётся прежней.
+
+### M3 — `since`/`expires` требуют точной version semantics
+
+В проекте нет зависимости `semver`; строкового сравнения допускать нельзя.
+Зафиксировать parser `major.minor.patch[-prerelease]`, fail-closed для
+некорректной registry entry и инвариант `since < expires`.
+
+Рекомендуемое продуктовое правило: сравнивать numeric core, поэтому
+`1.65.0-beta.1` уже достигает `expires: 1.65.0` и не тащит мёртвый флаг в новый
+release cycle. Добавить тесты `1.64.9`, `1.65.0-beta.1`, `1.65.0`, malformed.
+
+### M4 — Не определён runtime owner механизма Labs
+
+Нужно указать, что availability flags глобальны для загруженного JS-модуля, а
+effective `flat|iso` остаётся состоянием конкретной карточки/пространства.
+Один module-level resolver/subscription не должен создавать по listener на
+каждый render.
+
+`window.__hpLabs` должен иметь нормативную форму, например frozen sorted array:
+
+```ts
+Object.freeze(['iso'])
+```
+
+При изменении URL property заменяется новым frozen array, все подключённые
+карточки получают update. Нельзя отдавать внутренний mutable `Set`.
+
+### M5 — Scope `houseplan-space-card` не указан
+
+В репозитории есть второй renderer: `src/space-card.ts` + `src/space-render.ts`.
+Текущий текст можно прочитать как требование объёмного вида для обеих карточек.
+
+Рекомендация для stage 1: явно записать, что `houseplan-space-card` остаётся
+flat и Labs `iso` на него не влияет. Его поддержка — отдельный будущий scope.
+Иначе придётся сразу заводить вторую композицию сцены, что противоречит цели
+скрытого первого этапа.
+
+### M6 — Performance contract не совпадает с существующей инфраструктурой
+
+`compare.mjs` использует profile-specific budgets, noise allowance,
+relative+absolute thresholds и exact same runner. Просто потребовать «≤20% по
+трём полям» недостаточно; `longTask.maxSingleMs` особенно нестабилен около
+нуля, а `modelReadyMs` почти не измеряет переключение renderer.
+
+Добавить отдельный профиль `large-house-isometric-v1`:
+
+- текущий benchmark harness запускает candidate bundle с `hp-labs=iso` и
+  переключает view; тот же harness запускает base bundle, который игнорирует
+  неизвестный flag и остаётся flat;
+- profile id в обоих reports одинаков, runtime/browser/fingerprint проверяются
+  существующим fail-closed контрактом;
+- отдельный reviewed budget JSON задаёт 20% relative allowance **плюс**
+  абсолютный noise allowance;
+- обязательные метрики: first stable iso frame, view toggle, pan/zoom,
+  HA-state update, space switch, long-task count/total/max, heap growth,
+  iso-cache entries/growth, rendered devices;
+- candidate-only prerelease smoke получает абсолютные ceilings;
+- перед завершением этапа выполняется exact-SHA full performance workflow, а
+  не локальное сравнение с другой машиной.
+
+Фразу «flat не должен подорожать вообще» заменить на проверяемое: при
+выключенном флаге iso geometry/cache/DOM отсутствуют и нет дополнительного
+прохода по room/device collections; timing находится внутри noise allowance.
+
+### M7 — Golden coverage слишком мала для новой системы координат
+
+Две картинки не покрывают заявленный scope. Минимальная матрица stage 1:
+
+1. desktop dark: mixed walls + openings + Glow/sun + devices;
+2. desktop light: theme/shading/filter parity;
+3. mobile portrait или узкий kiosk: fit, marker/label alignment, no clipping;
+4. `show_borders:false`: стены не нарисованы, room fill/Glow сохраняются;
+5. remount/toggle sequence проверяется smoke, а финальный кадр — golden при
+   необходимости.
+
+Существующие flat baselines действительно не принимаются заново, если diff не
+нулевой. Новые baselines принимаются только из полного Linux CI artifact по
+действующему HP-QA-01 контракту.
+
+### M8 — A11y toggle contract неполон
+
+Для кнопки добавить:
+
+- `aria-pressed="true|false"` по `effectiveView`;
+- стабильный accessible name «Объёмный вид» / `Volumetric view`;
+- focus остаётся на той же кнопке после переключения;
+- active visual state не кодируется только цветом;
+- DOM/tab order устройств и room actions совпадает с flat;
+- stage 1 не добавляет projection animation: swap атомарный. Если анимация
+  будет добавлена через #82, `prefers-reduced-motion` делает её мгновенной.
+
+---
+
+## Замечания к тестам и формулировкам
+
+### T1 — «innerHTML до и после ветки» нужно сделать воспроизводимым
+
+Обычный тест не может сравнить текущий commit с кодом до ветки. Разделить
+контракт:
+
+- в одном candidate build сравнить no-param и unknown-param: нет iso nodes,
+  нет дополнительных WS/HTTP и config/layout writes;
+- golden гарантирует нулевой diff существующих flat scenes между revisions;
+- unit spy подтверждает, что iso geometry builder не вызывался;
+- чтение собственного Labs localStorage не считать сетевым/сторным изменением,
+  но при отсутствии URL оно не должно переписывать ключ.
+
+### T2 — Мутанты должны быть исполнимыми
+
+Пункт «отдельная формула проекции HTML» нельзя надёжно поймать текстовым
+поиском. Нормативный mutant: внести controlled offset только в overlay mapping;
+smoke должен увидеть расхождение anchor больше 1 CSS px. Для cache mutant тест
+меняет geometry in-place без `_cfgEpoch`; iso faces обязаны обновиться. Для
+layer-copy mutant тест проверяет upper bound DOM face count как `O(E)`.
+
+Для каждого из пяти mutants сохранить команду/patch id и имя краснеющего теста
+в PR/issue evidence; ручной тезис «проверено» недостаточен.
+
+### T3 — Opening wording
+
+В AC 6 заменить «без швов и торцов внутри проёма» на:
+
+> Проём является full-height gap. Внутри gap нет wall top/side полосы;
+> вертикальные jamb faces на двух границах masonry разрыва являются ожидаемыми.
+
+Это снимает конфликт с B7 и делает golden однозначным.
+
+### T4 — Первый запуск и сохранённое предпочтение
+
+В §9/§10 уточнить:
+
+- без записи `houseplan_card_view_v1[space]` effective view всегда flat, даже
+  при активном Labs;
+- toggle в обычном View пишет `flat|iso` per space;
+- при неактивном/expired flag сохранённое `iso` игнорируется, не меняет DOM и
+  не попадает в warm memo;
+- вход/выход editor не перезаписывает предпочтение;
+- fallback B8 не перезаписывает предпочтение автоматически.
+
+### T5 — Backlog — канонический источник
+
+Issue #89 сейчас говорит «черновик продуктового и технического решения», тогда
+как файл говорит «готово к реализации». По `AGENTS.md` Issue/Project являются
+каноническими. После принятия новой редакции:
+
+- добавить в body issue ссылку на stage 1 spec как нормативную;
+- синхронизировать scope/acceptance criteria issue с утверждённой редакцией;
+- оставить Project `Todo` до фактического начала, затем перевести в
+  `In progress`;
+- не закрывать #89 после одного spike ADR: закрытие только после всех AC этапа.
+
+---
+
+## Рекомендуемая новая структура нормативных разделов
+
+Чтобы не раздувать основной текст, достаточно добавить четыре подраздела:
+
+1. **§4.4 Coordinate spaces and viewport** — B1, B2.
+2. **§5.1 Wall-face topology and visual tokens** — B7, M1.
+3. **§7.1 Native hit testing and warm continuity** — B3, B4, B5.
+4. **§2.2.1 Labs operation precedence and version lifecycle** — B6, M3, M4.
+
+Остальные замечания можно встроить в §8–§13.
+
+## Definition of Ready после следующей итерации
+
+ТЗ можно считать готовым к реализации, когда:
+
+- [ ] определены plan/scene/client spaces, camera pivot/zScale и projected frame;
+- [ ] записан алгоритм flat↔iso viewport conversion;
+- [ ] обновлён warm-remount contract;
+- [ ] исправлено pointer rule и убран iso marker-drag smoke;
+- [ ] выбран однозначный kiosk escape contract;
+- [ ] полностью определена Labs grammar и expiry semantics;
+- [ ] определены ring/face/jamb/depth rules;
+- [ ] определена fallback state machine;
+- [ ] ADR имеет обязательный список решений;
+- [ ] fingerprint содержит все входы;
+- [ ] указан scope `houseplan-space-card`;
+- [ ] создан исполнимый performance profile/budget plan;
+- [ ] расширена golden/a11y/mutant matrix;
+- [ ] issue #89 ссылается на утверждённое ТЗ и не противоречит ему.
+
+После этого оценка stage 1 остаётся **L/XL с высоким риском**, но работа станет
+декомпозируемой и проверяемой; менять выбранную продуктовую концепцию не нужно.

custom_components/houseplan/__init__.py

@@ -1,12 +1,15 @@
 """House Plan: server-side house plan configuration + Lovelace card serving."""
 from __future__ import annotations
 
+import inspect
 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,8 +21,15 @@ 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
+from .store import (
+    HouseplanConfigEntry,
+    async_save_config_state,
+    async_save_layout_state,
+    create_data,
+)
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -28,23 +38,48 @@ async def async_setup(hass: HomeAssistant, config) -> bool:
     """Register global handlers (survive config-entry reloads): WS commands, HTTP view."""
     hass.data.setdefault(DOMAIN, {})
     hp_ws.async_register(hass)
-    from .http_api import HouseplanUploadView
+    from .http_api import HouseplanContentView, HouseplanImportPreviewView, HouseplanUploadView
 
     hass.http.register_view(HouseplanUploadView())
+    hass.http.register_view(HouseplanContentView())
+    hass.http.register_view(HouseplanImportPreviewView())
     return True
 
 
 async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) -> bool:
     """Config entry: stores in runtime_data, static paths, card auto-registration."""
     data = create_data(hass)
+    # Home Assistant's installation id never leaves the instance.  Exports
+    # carry only a salted SHA-256 fingerprint so same-instance internal files
+    # can be distinguished from cross-instance references.
+    try:
+        from homeassistant.helpers import instance_id as ha_instance_id
+
+        value = ha_instance_id.async_get(hass)
+        data.instance_id = str(await value if inspect.isawaitable(value) else value)
+    except Exception:  # noqa: BLE001 - old HA/test harness fallback
+        data.instance_id = str(entry.entry_id)
     # test-before-setup: storage must be readable, otherwise retry later
     try:
         await data.store.async_load()
         await data.config_store.async_load()
     except Exception as err:  # noqa: BLE001 — corrupt/unreadable .storage
         raise ConfigEntryNotReady(f"House Plan storage is not readable: {err}") from err
+    try:
+        await data.virtual_light_store.async_load()
+    except Exception:  # noqa: BLE001 — operational state fails safe to default on
+        _LOGGER.exception("House Plan: virtual-light storage is not readable; using default on")
     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))
@@ -61,14 +96,14 @@ async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) ->
 
             if card_path.exists():
                 static_paths.append(StaticPathConfig(FRONTEND_URL, str(card_path), cache_headers=False))
-            static_paths.append(StaticPathConfig(PLANS_URL, str(plans_path), cache_headers=True))
-            static_paths.append(StaticPathConfig(FILES_URL, str(files_path), cache_headers=True))
-            await hass.http.async_register_static_paths(static_paths)
+            # NOTE (audit B1): plans and marker files are NO LONGER static.
+            # They are served by HouseplanContentView, which requires auth.
+            # Only the card bundle stays public — Lovelace resources must be.
+            if static_paths:
+                await hass.http.async_register_static_paths(static_paths)
         except ImportError:  # very old HA versions
             if card_path.exists():
                 hass.http.register_static_path(FRONTEND_URL, str(card_path), cache_headers=False)
-            hass.http.register_static_path(PLANS_URL, str(plans_path), cache_headers=True)
-            hass.http.register_static_path(FILES_URL, str(files_path), cache_headers=True)
 
     if not card_path.exists():
         _LOGGER.warning("houseplan-card.js not found next to the integration: %s", card_path)
@@ -95,11 +130,176 @@ 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 {}
+        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 async_save_layout_state(
+                    data, lay_stored, layout, lay_rev,
+                    metadata={"geom_pending": merged}, remove=("geom_pending",),
+                )
+            rev = int(stored.get("rev", 0))
+            if cfg and migrate_config(cfg):  # 2. the config half
+                rev += 1
+                await async_save_config_state(data, cfg, rev, previous_rev=rev - 1)
+            migrate_layout(layout, merged)  # 3. the layout half + intent cleared
+            await async_save_layout_state(
+                data, lay_stored, layout, lay_rev + 1, remove=("geom_pending",)
+            )
+            _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
+    recovered_import = False
+    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))
+            target_config_rev = int(pending.get(
+                "config_rev", config_rev + (stored.get("config") != target_config)
+            ))
+            target_layout_rev = int(pending.get(
+                "layout_rev", layout_rev + (lay_stored.get("layout", {}) != target_layout)
+            ))
+            if stored.get("config") != target_config or config_rev < target_config_rev:
+                previous_config_rev = config_rev
+                config_rev = max(config_rev, target_config_rev)
+                await async_save_config_state(
+                    data,
+                    target_config,
+                    config_rev,
+                    previous_rev=previous_config_rev,
+                )
+            if lay_stored.get("layout", {}) != target_layout or layout_rev < target_layout_rev:
+                layout_rev = max(layout_rev, target_layout_rev)
+            exact_metadata = pending.get("final_metadata")
+            replace_metadata = isinstance(exact_metadata, dict)
+            metadata = dict(exact_metadata) if replace_metadata else None
+            if not replace_metadata and not pending.get("clear_backup") \
+                    and "optimize_backup" in lay_stored:
+                metadata = {"optimize_backup": lay_stored["optimize_backup"]}
+            remove_metadata = ["optimize_pending", "optimize_backup"]
+            if pending.get("clear_backup"):
+                # A recovered whole-plan undo replaces the complete layout;
+                # a point-wise repair snapshot from the replaced layout must
+                # not survive and later restore coordinates into the new pair.
+                remove_metadata.append("repair_backup")
+            await async_save_layout_state(
+                data,
+                lay_stored,
+                target_layout,
+                layout_rev,
+                metadata=metadata,
+                remove=tuple(remove_metadata),
+                replace_metadata=replace_metadata,
+            )
+            optimize_revs = (config_rev, layout_rev)
+            recovered_import = str(pending.get("kind") or "").startswith("import")
+            _LOGGER.warning(
+                "House Plan: completed an interrupted %s",
+                str(pending.get("kind") or "plan optimization").replace("_", " "),
+            )
+    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]})
+        if recovered_import:
+            await recorder.async_refresh()
+            current = (await data.config_store.async_load() or {}).get("config") or {}
+            live_ids = {str(marker.get("id")) for marker in current.get("markers") or []}
+            for marker_id in list(recorder.book.data):
+                if marker_id not in live_ids:
+                    await recorder.async_delete(marker_id)
+
     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

@@ -0,0 +1,31 @@
+"""Single source of truth for the write-authorization policy.
+
+The WS and HTTP paths used to duplicate this decision and drifted apart: the
+WS copy was fixed to fail closed while the upload view still failed OPEN when
+the config entry was unavailable (audit follow-up B2, 2026-07-27). One helper,
+one behaviour.
+"""
+from __future__ import annotations
+
+from homeassistant.core import HomeAssistant
+
+from .const import CONF_ADMIN_ONLY
+from .store import get_entry
+
+
+def may_write(hass: HomeAssistant, user) -> bool:
+    """True when `user` may modify House Plan data.
+
+    Fails CLOSED: when the entry cannot be read — during a reload, or while the
+    integration is disabled — the policy is unknown, and "unknown" is not the
+    same as "permissive": only admins are allowed through.
+    """
+    is_admin = bool(getattr(user, "is_admin", False))
+    entry = get_entry(hass)
+    if entry is None:
+        return is_admin
+    # 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

@@ -3,15 +3,64 @@
 DOMAIN = "houseplan"
 STORAGE_KEY = f"{DOMAIN}.layout"
 STORAGE_CONFIG_KEY = f"{DOMAIN}.config"
+STORAGE_VIRTUAL_LIGHTS_KEY = f"{DOMAIN}.virtual_lights"
 STORAGE_VERSION = 1
 STORAGE_MINOR_VERSION = 1
 FRONTEND_URL = "/houseplan_files/houseplan-card.js"
 PLANS_URL = "/houseplan_files/plans"
 PLANS_DIR = "houseplan/plans"  # relative to the HA configuration directory
 FILES_URL = "/houseplan_files/files"
+# authenticated read path (audit B1): /api/houseplan/content/<plans|files>/<sub>/<name>
+CONTENT_URL = "/api/houseplan/content"
+
+# How many paths one houseplan/content/sign call may carry. The card batches to
+# the same number; a client that sends more used to get a partial answer with no
+# 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.27.0"
+VERSION = "1.63.0"
+
+# Portable backup format.  This is deliberately independent from the Home
+# Assistant Store version above: storage migrations and files exported by a
+# user have different compatibility lifecycles.
+PLAN_MODEL_VERSION = 6
+EXPORT_VERSION = 1
+MAX_EXPORT_BYTES = 8 * 1024 * 1024
+IMPORT_PREVIEW_TTL_S = 10 * 60
+MAX_IMPORT_PREVIEWS_PER_USER = 3
+# Parsed documents are larger than their wire representation.  Keep the
+# original three-preview memory ceiling global as well as per user so turning
+# off the admin-only policy cannot multiply it by the number of household
+# accounts.
+MAX_IMPORT_PREVIEWS_TOTAL = 3
 
 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,9 @@ 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 functools import partial
 from pathlib import Path
 
 from aiohttp import web
@@ -18,8 +21,15 @@ except ImportError:  # older HA versions
     KEY_HASS = "hass"  # type: ignore[assignment]
 from homeassistant.core import HomeAssistant
 
-from .const import CONF_ADMIN_ONLY, FILES_DIR, FILES_URL
-from .store import get_entry
+from .const import (
+    CONF_ADMIN_ONLY, CONTENT_URL, FILES_DIR, FILES_URL, MAX_FILES_BYTES,
+    MAX_FILES_COUNT, MAX_EXPORT_BYTES, PLANS_DIR,
+)
+from .auth import may_write
+from .import_export import ImportFailure, create_preview
+from .plans import TMP_PREFIX, QuotaError, check_quota, reserve_filename
+from .registry_snapshot import import_registry_snapshot
+from .store import get_data
 from .validation import (
     FILE_EXTENSIONS,
     MAX_FILE_BYTES,
@@ -31,6 +41,142 @@ 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",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".txt": "text/plain",
+}
+
+
+class HouseplanImportPreviewView(HomeAssistantView):
+    """Upload a bounded JSON backup and return a server-side preview token."""
+
+    url = "/api/houseplan/import/preview"
+    name = "api:houseplan:import-preview"
+    requires_auth = True
+
+    async def post(self, request: web.Request) -> web.Response:
+        hass: HomeAssistant = request.app[KEY_HASS]
+        user = request.get("hass_user")
+        if not may_write(hass, user):
+            return web.json_response({"error": "unauthorized"}, status=403)
+        runtime = get_data(hass)
+        if runtime is None:
+            return web.json_response({"error": "not_ready"}, status=503)
+        policy = request.query.get("duplicate_policy", "skip")
+        if policy not in ("skip", "virtual"):
+            return web.json_response({"error": "invalid_format"}, status=400)
+        declared = request.content_length
+        if declared is not None and declared > MAX_EXPORT_BYTES:
+            return web.json_response({"error": "too_large"}, status=413)
+        blocks: list[bytes] = []
+        size = 0
+        async for block in request.content.iter_chunked(_CHUNK):
+            size += len(block)
+            if size > MAX_EXPORT_BYTES:
+                return web.json_response({"error": "too_large"}, status=413)
+            blocks.append(block)
+        owner_id = str(getattr(user, "id", ""))
+        try:
+            # Hold the global writer only while taking one coherent store
+            # snapshot. Parsing up to 8 MiB, schema validation and space remap
+            # are CPU work and apply will revalidate both revisions anyway.
+            async with runtime.write_lock:
+                config_data = await runtime.config_store.async_load() or {}
+                layout_data = await runtime.store.async_load() or {}
+            try:
+                registry_snapshot = import_registry_snapshot(hass)
+            except Exception:  # noqa: BLE001 - summary must not block a valid backup
+                _LOGGER.debug("House Plan import registry summary unavailable", exc_info=True)
+                registry_snapshot = None
+            result = await hass.async_add_executor_job(
+                partial(
+                    create_preview,
+                    runtime,
+                    b"".join(blocks),
+                    owner_id=owner_id,
+                    duplicate_policy=policy,
+                    current_config_data=config_data,
+                    current_layout_data=layout_data,
+                    config_root=Path(hass.config.path("")),
+                    registry_snapshot=registry_snapshot,
+                )
+            )
+        except ImportFailure as err:
+            status = 413 if err.code == "too_large" else 400
+            return web.json_response({"error": err.code, "message": err.message}, status=status)
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception("House Plan import preview failed")
+            return web.json_response({"error": "invalid_format"}, status=400)
+        return web.json_response(result)
+
+
+class HouseplanContentView(HomeAssistantView):
+    """Authenticated read access to plans and marker files (audit B1).
+
+    The directories used to be exposed as unauthenticated static paths, so
+    anyone who could reach the HA endpoint could pull floor plans and uploaded
+    manuals without logging in. This view keeps the same URLs but requires a
+    Home Assistant session (or a signed path, which the frontend uses for
+    <image href> inside the SVG).
+    """
+
+    url = "/api/houseplan/content/{kind}/{sub}/{name}"
+    name = "api:houseplan:content"
+    requires_auth = True
+
+    async def get(self, request: web.Request, kind: str, sub: str, name: str) -> web.StreamResponse:
+        hass: HomeAssistant = request.app[KEY_HASS]
+        if kind not in ("plans", "files"):
+            return web.Response(status=404)
+        safe_sub = sanitize_marker_id(sub)
+        safe_name = sanitize_filename(name)
+        if not safe_sub or not safe_name:
+            return web.Response(status=404)
+        base = Path(hass.config.path(PLANS_DIR if kind == "plans" else FILES_DIR)).resolve()
+        # plans live flat in one directory: the sub segment is a placeholder ("_")
+        path = (base / safe_name if kind == "plans" else base / safe_sub / safe_name).resolve()
+        # defence in depth: the sanitizers already strip separators
+        if not str(path).startswith(str(base)):
+            return web.Response(status=404)
+
+        if not await hass.async_add_executor_job(path.is_file):
+            return web.Response(status=404)
+        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):
@@ -42,62 +188,135 @@ class HouseplanUploadView(HomeAssistantView):
 
     async def post(self, request: web.Request) -> web.Response:
         hass: HomeAssistant = request.app[KEY_HASS]
-        entry = get_entry(hass)
-        admin_only = bool(entry and entry.options.get(CONF_ADMIN_ONLY, False))
-        if admin_only:
-            user = request.get("hass_user")
-            if user is None or not user.is_admin:
-                return web.json_response({"error": "unauthorized"}, status=403)
+        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"{FILES_URL}/{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.27.0"
+  "version": "1.63.0"
 }

custom_components/houseplan/plans.py

@@ -0,0 +1,357 @@
+"""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 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 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)."""
+    if not isinstance(url, str) or not url:
+        return ""
+    return url.split("?", 1)[0].rsplit("/", 1)[-1]
+
+
+def plan_refs(cfg: dict[str, Any] | None) -> set[str]:
+    """Plan file names a configuration references."""
+    out: set[str] = set()
+    for sp in (cfg or {}).get("spaces") or []:
+        name = plan_basename(sp.get("plan_url"))
+        if name:
+            out.add(name)
+    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(".")
+    return len(parts) in (2, 3) and parts[-1].lower() in PLAN_EXTENSIONS
+
+
+def collect_plans(
+    plans_dir: Path,
+    old_cfg: dict[str, Any] | None,
+    new_cfg: dict[str, Any],
+    now: float | None = None,
+) -> int:
+    """Drop plan files the accepted configuration made obsolete (review R3-1).
+
+    Called inside the config write lock, right after the new revision is
+    stored, so it decides from the two configurations that actually bracket the
+    commit instead of trusting a client to say what may be deleted. The earlier
+    design — a `plan/cleanup` command carrying `keep` — could not be ordered
+    against another client's commit: a delayed call removed the file that
+    client had just saved, leaving the accepted configuration pointing at
+    nothing, which is the damage copy-on-write was introduced to prevent.
+
+    Two rules, both conservative:
+      * 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 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
+    a file-system problem must not turn a durable commit into a failed call.
+    """
+    new_refs = plan_refs(new_cfg)
+    old_refs = plan_refs(old_cfg)
+    # 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 []
+    except OSError as err:
+        # The directory can vanish or turn unreadable between the check and the
+        # walk. This is housekeeping running behind a commit that is already
+        # durable, so it reports "nothing collected" instead of failing (R4-1).
+        _LOGGER.warning("House Plan: could not list %s: %s", plans_dir, err)
+        return 0
+    for item in items:
+        if not item.is_file() or item.name in new_refs or not is_plan_file(item.name):
+            continue
+        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()
+            removed += 1
+        except OSError as err:
+            _LOGGER.warning("House Plan: could not remove the old plan %s: %s", item, err)
+    return removed

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/registry_snapshot.py

@@ -0,0 +1,47 @@
+"""Small registry projection shared by import HTTP and WebSocket previews."""
+from __future__ import annotations
+
+from typing import Any
+
+from homeassistant.core import HomeAssistant
+
+
+def import_registry_snapshot(hass: HomeAssistant) -> dict[str, set[str]]:
+    """Return non-sensitive target inventory used only for preview counts."""
+    from homeassistant.helpers import area_registry as ar
+    from homeassistant.helpers import device_registry as dr
+    from homeassistant.helpers import entity_registry as er
+
+    entities = list(er.async_get(hass).entities.values())
+    active_entity: set[str] = set()
+    disabled_entity: set[str] = set()
+    entities_by_device: dict[str, list[Any]] = {}
+    for entry in entities:
+        entity_id = str(entry.entity_id)
+        if getattr(entry, "disabled_by", None) is None:
+            active_entity.add(entity_id)
+        else:
+            disabled_entity.add(entity_id)
+        if entry.device_id:
+            entities_by_device.setdefault(str(entry.device_id), []).append(entry)
+
+    # Synthetic/runtime entities may legitimately have no registry row.
+    active_entity.update(str(state.entity_id) for state in hass.states.async_all())
+
+    active_device: set[str] = set()
+    disabled_device: set[str] = set()
+    for entry in dr.async_get(hass).devices.values():
+        device_id = str(entry.id)
+        children = entities_by_device.get(device_id, [])
+        disabled = getattr(entry, "disabled_by", None) is not None or (
+            bool(children)
+            and all(getattr(child, "disabled_by", None) is not None for child in children)
+        )
+        (disabled_device if disabled else active_device).add(device_id)
+    return {
+        "active_device": active_device,
+        "disabled_device": disabled_device,
+        "active_entity": active_entity,
+        "disabled_entity": disabled_entity - active_entity,
+        "areas": {str(entry.id) for entry in ar.async_get(hass).areas.values()},
+    }

custom_components/houseplan/repairs.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers import issue_registry as ir
 
-from .const import DOMAIN, PLANS_DIR, PLANS_URL
+from .const import CONTENT_URL, DOMAIN, PLANS_DIR, PLANS_URL
 from .store import HouseplanConfigEntry
 
 
@@ -25,9 +25,15 @@ async def async_check_plan_files(hass: HomeAssistant, entry: HouseplanConfigEntr
         res = []
         for sp in spaces:
             url = sp.get("plan_url") or ""
-            if not url.startswith(PLANS_URL + "/"):
+            # both the legacy static URL and the authenticated content URL
+            prefix = None
+            if url.startswith(PLANS_URL + "/"):
+                prefix = PLANS_URL + "/"
+            elif url.startswith(CONTENT_URL + "/plans/_/"):
+                prefix = CONTENT_URL + "/plans/_/"
+            if prefix is None:
                 continue  # external/legacy URL — not ours to verify
-            fname = url[len(PLANS_URL) + 1 :].split("?", 1)[0]
+            fname = url[len(prefix) :].split("?", 1)[0]
             if not (plans_dir / fname).is_file():
                 res.append((sp.get("id", "?"), fname))
         return res
@@ -45,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,8 @@
 from __future__ import annotations
 
 import asyncio
+import logging
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -9,7 +11,17 @@ from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.storage import Store
 
-from .const import DOMAIN, STORAGE_CONFIG_KEY, STORAGE_KEY, STORAGE_MINOR_VERSION, STORAGE_VERSION
+from .const import (
+    DOMAIN,
+    STORAGE_CONFIG_KEY,
+    STORAGE_KEY,
+    STORAGE_MINOR_VERSION,
+    STORAGE_VERSION,
+    STORAGE_VIRTUAL_LIGHTS_KEY,
+)
+
+
+_LOGGER = logging.getLogger(__name__)
 
 
 class HouseplanStore(Store):
@@ -39,9 +51,26 @@ class HouseplanData:
 
     store: HouseplanStore
     config_store: HouseplanStore
+    virtual_light_store: HouseplanStore
     # 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
+    # Stable HA instance id used only through a one-way export fingerprint.
+    instance_id: str = ""
+    # Parsed import candidates are short-lived, user-bound and memory-only.
+    # dict keeps insertion order, which lets the preview service evict oldest.
+    import_previews: dict[str, dict[str, Any]] = field(default_factory=dict)
 
 
 HouseplanConfigEntry = ConfigEntry[HouseplanData]
@@ -54,6 +83,12 @@ def create_data(hass: HomeAssistant) -> HouseplanData:
         config_store=HouseplanStore(
             hass, STORAGE_VERSION, STORAGE_CONFIG_KEY, minor_version=STORAGE_MINOR_VERSION
         ),
+        virtual_light_store=HouseplanStore(
+            hass,
+            STORAGE_VERSION,
+            STORAGE_VIRTUAL_LIGHTS_KEY,
+            minor_version=STORAGE_MINOR_VERSION,
+        ),
     )
 
 
@@ -67,3 +102,98 @@ def get_entry(hass: HomeAssistant) -> ConfigEntry | None:
     """The loaded config entry, or None."""
     entries = hass.config_entries.async_loaded_entries(DOMAIN)
     return entries[0] if entries else None
+
+
+OPTIMIZE_BACKUP = "optimize_backup"
+OPTIMIZE_PENDING = "optimize_pending"
+LAYOUT_STORE_CORE_KEYS = frozenset({"layout", "rev"})
+
+
+def layout_store_payload(
+    stored: dict[str, Any],
+    layout: dict[str, Any],
+    rev: int,
+    *,
+    metadata: dict[str, Any] | None = None,
+    remove: tuple[str, ...] = (),
+    replace_metadata: bool = False,
+) -> dict[str, Any]:
+    """Build one layout-store write without silently dropping metadata.
+
+    Layout used to be saved by several independent dict comprehensions.  Every
+    new metadata key therefore had to be added to every caller or was lost on
+    the next drag.  All writers now express only the metadata they intentionally
+    add/remove and this helper preserves the rest.
+    """
+    excluded = {*LAYOUT_STORE_CORE_KEYS, *remove}
+    out = {} if replace_metadata else {
+        key: value for key, value in stored.items() if key not in excluded
+    }
+    if metadata:
+        out.update(metadata)
+    out["layout"] = layout
+    out["rev"] = rev
+    return out
+
+
+async def async_save_layout_state(
+    runtime: HouseplanData,
+    stored: dict[str, Any],
+    layout: dict[str, Any],
+    rev: int,
+    *,
+    metadata: dict[str, Any] | None = None,
+    remove: tuple[str, ...] = (),
+    replace_metadata: bool = False,
+) -> dict[str, Any]:
+    """Persist layout and return the exact store document written."""
+    payload = layout_store_payload(
+        stored,
+        layout,
+        rev,
+        metadata=metadata,
+        remove=remove,
+        replace_metadata=replace_metadata,
+    )
+    await runtime.store.async_save(payload)
+    return payload
+
+
+async def async_save_config_state(
+    runtime: HouseplanData,
+    config: dict[str, Any],
+    rev: int,
+    *,
+    previous_rev: int | None = None,
+) -> dict[str, Any]:
+    """Persist configuration and reconcile dependent operational state.
+
+    Callers already hold ``runtime.write_lock``.  Reading the previous
+    revision here keeps less common writers (import recovery and undo) on the
+    same path as ordinary editor saves without duplicating lifecycle rules.
+    """
+    if previous_rev is None:
+        previous = await runtime.config_store.async_load() or {}
+        try:
+            previous_rev = int(previous.get("rev", 0))
+        except (TypeError, ValueError):
+            previous_rev = 0
+
+    payload = {"config": config, "rev": rev}
+    await runtime.config_store.async_save(payload)
+
+    # The config is already durable at this point.  Reconciliation remains a
+    # separate Store write; an interrupted pair is detected from config_rev on
+    # the next read and fails safe to the compatibility default (all on).
+    from .virtual_lights import async_reconcile_virtual_lights
+
+    try:
+        await async_reconcile_virtual_lights(
+            runtime.virtual_light_store,
+            config,
+            rev,
+            previous_config_rev=previous_rev,
+        )
+    except Exception:  # noqa: BLE001 - config commit already stands
+        _LOGGER.exception("House Plan: virtual-light state reconciliation failed")
+    return payload

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

@@ -4,6 +4,7 @@ Kept separate so it can be covered by unit tests (only voluptuous is needed).
 """
 from __future__ import annotations
 
+from collections import Counter
 import re
 
 import voluptuous as vol
@@ -16,6 +17,231 @@ 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
+MARKER_CONTROL_PREFIX = "marker:"
+_CONTROL_ENTITY_ID_RE = re.compile(r"^[a-z0-9_]+\.[a-z0-9_]+\Z")
+
+
+class MarkerControlError(ValueError):
+    """Semantic marker-link error with a stable public code."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+VALUE_BADGE_ATTRIBUTES = {
+    "current_temperature", "temperature", "current_humidity", "humidity",
+    "current_position", "percentage", "brightness", "volume_level",
+    "battery_level", "fan_speed",
+}
+VALUE_BADGE_POSITIONS = {"right", "bottom", "left", "top"}
+VALUE_BADGE_SOURCE_KINDS = {
+    "entity_state", "entity_attribute", "derived_lqi", "derived_marker_state",
+}
+_LIGHT_ENTITY_RE = re.compile(r"^(?:light|switch)\.[a-z0-9_]+\Z")
+
+
+def _matching_previous_marker(
+    marker: dict, marker_id: str, old_by_id: dict[str, dict], old_markers: list[dict],
+    new_ids: set[str], consumed_old_ids: set[str], validate_all: bool,
+) -> dict | None:
+    """Match the previous marker across the binding-stable id rename path."""
+    old_marker = old_by_id.get(marker_id)
+    if old_marker is not None:
+        consumed_old_ids.add(marker_id)
+        return old_marker
+    if validate_all:
+        return None
+    binding = marker.get("binding")
+    matches = [
+        old for old in old_markers
+        if binding not in (None, "virtual")
+        and old.get("binding") == binding
+        and str(old.get("id")) not in new_ids
+        and str(old.get("id")) not in consumed_old_ids
+    ]
+    if len(matches) == 1:
+        consumed_old_ids.add(str(matches[0].get("id")))
+        return matches[0]
+    return None
+
+
+def validate_marker_value_badges(
+    config: dict, previous: dict | None = None, *, validate_all: bool = False
+) -> None:
+    """Validate only new/changed badge data; dormant future/legacy data round-trips."""
+    markers = config.get("markers") or []
+    by_id = {str(marker.get("id")): marker for marker in markers}
+    old_markers = (previous or {}).get("markers") or []
+    old_by_id = {str(marker.get("id")): marker for marker in old_markers}
+    new_ids = set(by_id)
+    consumed_old_ids: set[str] = set()
+    known_source_fields = {"kind", "entity_id", "attribute", "ref"}
+
+    for marker_id, marker in by_id.items():
+        old_marker = _matching_previous_marker(
+            marker, marker_id, old_by_id, old_markers, new_ids,
+            consumed_old_ids, validate_all,
+        )
+        badge = marker.get("value_badge")
+        old_badge = None if validate_all else (old_marker or {}).get("value_badge")
+        if not validate_all and badge == old_badge:
+            continue
+        if badge is None:
+            continue
+        if not isinstance(badge, dict):
+            raise MarkerControlError("invalid_value_badge", "Value badge must be an object")
+        if not isinstance(badge.get("enabled"), bool):
+            raise MarkerControlError("invalid_value_badge", "Value badge enabled must be boolean")
+        if badge.get("position") not in VALUE_BADGE_POSITIONS:
+            raise MarkerControlError("invalid_value_badge_position", "Invalid value badge position")
+        source = badge.get("source")
+        if badge["enabled"] and not isinstance(source, dict):
+            raise MarkerControlError("value_badge_source_required", "Enabled value badge needs a source")
+        if source is None:
+            continue
+        if not isinstance(source, dict) or source.get("kind") not in VALUE_BADGE_SOURCE_KINDS:
+            raise MarkerControlError("invalid_value_badge_source", "Invalid value badge source")
+        kind = source["kind"]
+        allowed_fields = {
+            "entity_state": {"kind", "entity_id"},
+            "entity_attribute": {"kind", "entity_id", "attribute"},
+            "derived_lqi": {"kind"},
+            "derived_marker_state": {"kind", "ref"},
+        }[kind]
+        if (known_source_fields & set(source)) - allowed_fields:
+            raise MarkerControlError("invalid_value_badge_source", "Inconsistent value badge source")
+        if kind in {"entity_state", "entity_attribute"}:
+            entity_id = source.get("entity_id")
+            if not isinstance(entity_id, str) or not _CONTROL_ENTITY_ID_RE.fullmatch(entity_id):
+                raise MarkerControlError("invalid_value_badge_source", "Invalid value badge entity id")
+        if kind == "entity_attribute":
+            if source.get("attribute") not in VALUE_BADGE_ATTRIBUTES:
+                raise MarkerControlError("invalid_value_badge_attribute", "Invalid value badge attribute")
+        if kind == "derived_marker_state":
+            ref = source.get("ref")
+            if not isinstance(ref, str) or not ref.startswith(MARKER_CONTROL_PREFIX) or not ref[len(MARKER_CONTROL_PREFIX):]:
+                raise MarkerControlError("invalid_value_badge_source", "Invalid marker value badge target")
+            target = by_id.get(ref[len(MARKER_CONTROL_PREFIX):])
+            if target is None or target.get("removed") is True:
+                raise MarkerControlError("value_badge_marker_missing", "Marker value badge target does not exist")
+            if target.get("is_light") is not True:
+                raise MarkerControlError("value_badge_marker_not_light", "Marker value badge target is not a forced light")
+
+
+def validate_marker_light_entities(
+    config: dict, previous: dict | None = None, *, validate_all: bool = False
+) -> None:
+    """Validate new/changed leading-light choices without rejecting dormant data.
+
+    The top-level schema must stay lossless: an old or future literal that the
+    current frontend cannot edit may round-trip unchanged. Imports validate the
+    whole incoming document because every imported value is new to this plan.
+    """
+    markers = config.get("markers") or []
+    old_markers = (previous or {}).get("markers") or []
+    old_by_id = {str(marker.get("id")): marker for marker in old_markers}
+    new_ids = {str(marker.get("id")) for marker in markers}
+    consumed_old_ids: set[str] = set()
+    for marker in markers:
+        marker_id = str(marker.get("id"))
+        old_marker = _matching_previous_marker(
+            marker, marker_id, old_by_id, old_markers, new_ids,
+            consumed_old_ids, validate_all,
+        )
+        value = marker.get("light_entity")
+        old_value = None if validate_all else (old_marker or {}).get("light_entity")
+        if not validate_all and value == old_value:
+            continue
+        if value is None:
+            continue
+        if not isinstance(value, str) or not _LIGHT_ENTITY_RE.fullmatch(value):
+            raise MarkerControlError(
+                "invalid_light_entity", "Leading light entity must be light.* or switch.*"
+            )
+
+
+def validate_marker_controls(
+    config: dict, previous: dict | None = None, *, validate_all: bool = False
+) -> None:
+    """Validate newly introduced marker:* edges without rewriting old data.
+
+    Existing broken refs remain editable and round-trip losslessly. Imports use
+    validate_all because their complete candidate graph is new to this plan.
+    """
+    markers = config.get("markers") or []
+    by_id = {str(marker.get("id")): marker for marker in markers}
+    old_markers = (previous or {}).get("markers") or []
+    old_by_id = {
+        str(marker.get("id")): marker for marker in (previous or {}).get("markers") or []
+    }
+    new_ids = set(by_id)
+    consumed_old_ids: set[str] = set()
+    graph: dict[str, list[str]] = {}
+    added: list[tuple[str, str]] = []
+    for marker_id, marker in by_id.items():
+        old_marker = _matching_previous_marker(
+            marker, marker_id, old_by_id, old_markers, new_ids,
+            consumed_old_ids, validate_all,
+        )
+        raw_controls = [
+            ref for ref in marker.get("controls") or [] if isinstance(ref, str)
+        ]
+        old_controls = [] if validate_all else [
+            ref for ref in (old_marker or {}).get("controls") or [] if isinstance(ref, str)
+        ]
+        refs = [
+            ref for ref in raw_controls
+            if isinstance(ref, str) and ref.startswith(MARKER_CONTROL_PREFIX)
+        ]
+        graph[marker_id] = [ref[len(MARKER_CONTROL_PREFIX):] for ref in refs]
+        old_refs = [
+            ref for ref in old_controls
+            if isinstance(ref, str) and ref.startswith(MARKER_CONTROL_PREFIX)
+        ]
+        remaining = list(old_refs)
+        for ref in refs:
+            if ref in remaining:
+                remaining.remove(ref)
+            else:
+                added.append((marker_id, ref[len(MARKER_CONTROL_PREFIX):]))
+        new_counts, old_counts = Counter(refs), Counter(old_refs)
+        if any(count > 1 and count > old_counts[ref] for ref, count in new_counts.items()):
+            raise MarkerControlError("duplicate_marker_control", "Duplicate marker light target")
+        remaining_controls = list(old_controls)
+        for ref in raw_controls:
+            if ref in remaining_controls:
+                remaining_controls.remove(ref)
+            elif not ref.startswith(MARKER_CONTROL_PREFIX) and not _CONTROL_ENTITY_ID_RE.fullmatch(ref):
+                raise MarkerControlError("invalid_marker_control", f"Invalid entity target: {ref}")
+
+    def reaches(start: str, wanted: str) -> bool:
+        stack, seen = [start], set()
+        while stack:
+            node = stack.pop()
+            if node == wanted:
+                return True
+            if node in seen:
+                continue
+            seen.add(node)
+            stack.extend(graph.get(node, []))
+        return False
+
+    for controller, target in added:
+        if not target:
+            raise MarkerControlError("invalid_marker_control", "Marker target id is empty")
+        if target == controller:
+            raise MarkerControlError("marker_control_self", "A marker cannot control itself")
+        target_marker = by_id.get(target)
+        if target_marker is None or target_marker.get("removed") is True:
+            raise MarkerControlError("marker_control_missing", f"Marker target does not exist: {target}")
+        if target_marker.get("is_light") is not True:
+            raise MarkerControlError("marker_control_not_light", f"Marker target is not a forced light: {target}")
+        if reaches(target, controller):
+            raise MarkerControlError("marker_control_cycle", "Marker light controls contain a cycle")
 
 # ---------- sanitizers ----------
 
@@ -33,7 +259,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:
@@ -47,13 +273,160 @@ def valid_space_id(value: str) -> bool:
 
 
 # ---------- voluptuous schemas ----------
+def _finite(value):
+    """Coerce to float and reject NaN/Infinity (audit B5).
+
+    'NaN' and 'Infinity' pass Coerce(float) and serialize to null on write,
+    silently corrupting a stored position forever.
+    """
+    f = float(value)
+    if f != f or f in (float("inf"), float("-inf")):
+        raise vol.Invalid("coordinate must be a finite number")
+    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"): vol.Coerce(float), vol.Required("y"): vol.Coerce(float)},
+    {vol.Required("x"): _COORD, vol.Required("y"): _COORD},
     extra=vol.ALLOW_EXTRA,  # v2 records carry the "s" key (space id)
 )
-LAYOUT_SCHEMA = vol.Schema({str: POS_SCHEMA})
+LAYOUT_SCHEMA = vol.All(vol.Schema({str: POS_SCHEMA}), vol.Length(max=MAX_LAYOUT))
 
-POINT = vol.All([vol.Coerce(float)], 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:
@@ -65,51 +438,348 @@ 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("x"): vol.Coerce(float),
-            vol.Optional("y"): vol.Coerce(float),
-            vol.Optional("w"): vol.Coerce(float),
-            vol.Optional("h"): vol.Coerce(float),
-            vol.Optional("poly"): vol.All([POINT], vol.Length(min=3)),
+            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", "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))),
+                        vol.Optional("label_scale"): vol.Any(None, vol.All(vol.Coerce(float), vol.Range(min=0.5, max=3))),
+                    },
+                    extra=vol.ALLOW_EXTRA,
+                ),
+            ),
+            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"]),
+        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,
 )
 
-SPACE_SCHEMA = vol.Schema(
+# 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"): _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)),
+}
+# 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.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,
+                # 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,
+                # 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),
+)
+
+
+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([vol.Coerce(float)], vol.Length(min=4, max=4)),
-        vol.Required("rooms"): [ROOM_SCHEMA],
-        vol.Optional("openings"): [
+        # 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"): vol.Coerce(float),
-                    vol.Required("y"): vol.Coerce(float),
-                    vol.Required("angle"): vol.Coerce(float),
-                    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,
@@ -118,50 +788,160 @@ 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("display"): vol.Any("badge", "ripple", "icon_ripple", None),
-        vol.Optional("ripple_color"): 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),
+        # Explicit leading entity for composite Always sources. It is kept
+        # literally when temporarily absent; runtime falls back without
+        # deleting the user's choice.
+        # Semantic delta validation below the schema preserves unknown/future
+        # literals until that exact field is edited (lossless config doctrine).
+        vol.Optional("light_entity"): object,
+        vol.Optional("value_badge"): vol.Any(
+            None,
+            vol.Schema(
+                {
+                    # Required semantically for changed/new data. Optional here
+                    # keeps old/future configs readable until the user edits it.
+                    vol.Optional("enabled"): object,
+                    vol.Optional("position"): object,
+                    vol.Optional("source"): vol.Any(
+                        None,
+                        vol.Schema({}, extra=vol.ALLOW_EXTRA),
+                    ),
+                },
+                extra=vol.ALLOW_EXTRA,
+            ),
+        ),
+        # 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),
+        # 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,
 )
 CONFIG_SCHEMA = vol.Schema(
     {
-        vol.Required("spaces"): [SPACE_SCHEMA],
-        vol.Optional("markers", default=list): [MARKER_SCHEMA],
+        vol.Required("spaces"): vol.All([SPACE_SCHEMA], vol.Length(max=MAX_SPACES)),
+        vol.Optional("markers", default=list): vol.All([MARKER_SCHEMA], vol.Length(max=MAX_MARKERS)),
         vol.Optional("settings", default=dict): vol.Schema(
             {
+                vol.Optional("glow_radius_cm"): vol.All(vol.Coerce(float), vol.Range(min=10, max=10000)),
+                # 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/virtual_lights.py

@@ -0,0 +1,125 @@
+"""Persistent operational state for manual virtual lights."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .store import HouseplanStore
+
+
+EVENT_VIRTUAL_LIGHT_UPDATED = "houseplan_virtual_light_updated"
+
+
+def is_manual_virtual_light(marker: Any) -> bool:
+    """Return whether a marker uses the exact persistent manual-light mode."""
+    return (
+        isinstance(marker, dict)
+        and isinstance(marker.get("id"), str)
+        and bool(marker["id"])
+        and marker.get("binding") == "virtual"
+        and marker.get("is_light") is True
+        and marker.get("tap_action") == "toggle"
+        and marker.get("removed") is not True
+    )
+
+
+def eligible_virtual_light_ids(config: Any) -> set[str]:
+    """Collect live marker ids eligible for persistent manual state."""
+    if not isinstance(config, dict):
+        return set()
+    markers = config.get("markers")
+    if not isinstance(markers, list):
+        return set()
+    return {marker["id"] for marker in markers if is_manual_virtual_light(marker)}
+
+
+def _integer(value: Any, default: int = 0) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default
+    return max(0, parsed)
+
+
+def _read_state(stored: Any) -> tuple[int, int, set[str]]:
+    if not isinstance(stored, dict):
+        return 0, 0, set()
+    raw_off = stored.get("off")
+    off = (
+        {item for item in raw_off if isinstance(item, str) and item}
+        if isinstance(raw_off, list)
+        else set()
+    )
+    return _integer(stored.get("rev")), _integer(stored.get("config_rev")), off
+
+
+def _wire(rev: int, config_rev: int, off: set[str]) -> dict[str, Any]:
+    return {"rev": rev, "config_rev": config_rev, "off": sorted(off)}
+
+
+async def async_virtual_light_snapshot(
+    store: HouseplanStore,
+    config: dict[str, Any],
+    config_rev: int,
+) -> dict[str, Any]:
+    """Return a coherent snapshot, repairing stale or interrupted state.
+
+    A revision gap means an older writer may have changed eligibility without
+    knowing about this Store.  Clearing every manual-off bit is conservative:
+    it restores the pre-feature/default-on behaviour and cannot resurrect an
+    old off state for a marker whose role changed in the meantime.
+    """
+    stored = await store.async_load() or {}
+    rev, state_config_rev, stored_off = _read_state(stored)
+    eligible = eligible_virtual_light_ids(config)
+    off = stored_off & eligible if state_config_rev == config_rev else set()
+    if off != stored_off:
+        rev += 1
+    payload = _wire(rev, config_rev, off)
+    if payload != stored:
+        await store.async_save(payload)
+    return payload
+
+
+async def async_reconcile_virtual_lights(
+    store: HouseplanStore,
+    config: dict[str, Any],
+    config_rev: int,
+    *,
+    previous_config_rev: int,
+) -> dict[str, Any]:
+    """Carry eligible state across one known configuration transition."""
+    stored = await store.async_load() or {}
+    rev, state_config_rev, stored_off = _read_state(stored)
+    eligible = eligible_virtual_light_ids(config)
+    off = stored_off & eligible if state_config_rev == previous_config_rev else set()
+    if off != stored_off:
+        rev += 1
+    payload = _wire(rev, config_rev, off)
+    if payload != stored:
+        await store.async_save(payload)
+    return payload
+
+
+async def async_toggle_virtual_light(
+    store: HouseplanStore,
+    config: dict[str, Any],
+    config_rev: int,
+    marker_id: str,
+) -> dict[str, Any] | None:
+    """Atomically invert one eligible marker and persist before returning."""
+    if marker_id not in eligible_virtual_light_ids(config):
+        return None
+    snapshot = await async_virtual_light_snapshot(store, config, config_rev)
+    off = set(snapshot["off"])
+    if marker_id in off:
+        off.remove(marker_id)
+    else:
+        off.add(marker_id)
+    payload = _wire(_integer(snapshot["rev"]) + 1, config_rev, off)
+    await store.async_save(payload)
+    return {
+        "marker_id": marker_id,
+        "on": marker_id not in off,
+        "rev": payload["rev"],
+    }

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,352 @@
+#!/usr/bin/env node
+/** Reproducible browser benchmark and report producer for HP-PERF-01. */
+import { existsSync, 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 profile = valueArg('profile') ?? 'large-house-v1';
+if (!['large-house-v1', 'large-house-isometric-v1'].includes(profile))
+  throw new Error(`unknown large-house profile: ${profile}`);
+const isometric = profile === 'large-house-isometric-v1';
+const requiresIsometric = isometric && existsSync(resolve(targetRoot, 'src/iso-projection.ts'));
+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, isometric, requiresIsometric }) => {
+      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,
+        isoGeometry: card._isoGeometryCache?.size ?? 0,
+      });
+
+      window.__card?.remove?.();
+      localStorage.clear();
+      if (isometric) {
+        localStorage.setItem('houseplan_card_labs_v1', JSON.stringify(['iso']));
+        localStorage.setItem('houseplan_card_view_v1', JSON.stringify(Object.fromEntries(
+          fixture.config.spaces.map((space) => [space.id, 'iso']),
+        )));
+        history.replaceState(null, '', '?hp-labs=iso');
+      } else history.replaceState(null, '', location.pathname);
+      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);
+      if (requiresIsometric && (typeof card._setProjection !== 'function'
+          || !(card._isoGeometryCache instanceof Map))) {
+        throw new Error('large-house-isometric-v1 candidate has no renderer contract');
+      }
+      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 viewToggle = isometric ? await duration(async () => {
+        if (typeof card._setProjection === 'function') {
+          card._setProjection('flat');
+          await card.updateComplete;
+          card._setProjection('iso');
+          await card.updateComplete;
+        } else {
+          // Comparison SHAs before #89 intentionally ignore the Labs operation.
+          card.requestUpdate();
+          await card.updateComplete;
+        }
+      }) : null;
+      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,
+        ...(viewToggle ? { viewToggleMs: viewToggle.ms } : {}),
+        spaceSwitchMs: spaceSwitch.ms,
+        stateUpdateMs: stateUpdate.ms,
+        resizePreviewMs: resizePreview.ms,
+        panZoomMs: panZoom.ms,
+        settingsDialogMs: settingsDialog.ms,
+        switchCycleMs: switchCycle.ms,
+        longTasks: {
+          load: loadLongTaskResult,
+          ...(viewToggle ? { viewToggle: viewToggle.longTasks } : {}),
+          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,
+      isometric, requiresIsometric,
+    });
+    if (measuredSample >= 0) rows.push(row);
+  }
+} finally {
+  await browser.close();
+}
+
+const metricNames = [
+  'modelReadyMs', 'firstStableRenderMs', 'spaceSwitchMs', 'stateUpdateMs',
+  'resizePreviewMs', 'panZoomMs', 'settingsDialogMs', 'switchCycleMs',
+];
+if (isometric) metricNames.splice(2, 0, 'viewToggleMs');
+const report = {
+  schema: 2,
+  profile,
+  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 the ${profile} budget.`,
+};
+
+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,31 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { sourceFingerprint } from '../scripts/source-fingerprint.mjs';
+
+const fingerprintForTree = async (root) => {
+  const modulePath = resolve(root, 'scripts/source-fingerprint.mjs');
+  if (!existsSync(modulePath)) return sourceFingerprint(root);
+  const module = await import(pathToFileURL(modulePath).href);
+  if (typeof module.sourceFingerprint !== 'function') {
+    throw new Error(`${modulePath} does not export sourceFingerprint`);
+  }
+  return module.sourceFingerprint(root);
+};
+
+/** Refuse measurements/screenshots made by a committed bundle from old source. */
+export async function assertFreshDemoBundle(page, root = process.cwd()) {
+  // A comparative performance run may load an older tree whose fingerprint
+  // contract is intentionally different from the candidate's. Validate that
+  // tree with the implementation that built it, not with today's algorithm.
+  const expected = await fingerprintForTree(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,238 @@
+/**
+ * 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);
+  const lightMarkers = Object.entries(runtime.entities)
+    .filter(([entityId]) => entityId.startsWith('light.'))
+    .map(([_entityId, entity]) => ({
+      id: entity.device_id,
+      binding: `device:${entity.device_id}`,
+      is_light: true,
+    }));
+  return {
+    config: { spaces, markers: lightMarkers, settings: { glow_radius_cm: 300 } },
+    ...runtime,
+    counts: LARGE_HOUSE_COUNTS,
+  };
+};

demo/fixtures/visual-matrix.mjs

@@ -0,0 +1,206 @@
+/** Deterministic fictional scenes for HP-QA-01 golden-image coverage. */
+
+const round = (value) => Number(value.toFixed(6));
+
+// Golden fixtures must use the same persisted wall-key contract as real plan
+// data. Arbitrary labels make every configured wall look virtual to the
+// renderer, which lets a visually ineffective baseline pass unnoticed.
+const WALL_KEY_PITCH = 1 / 240;
+export const fixtureWallKey = (a, b) => {
+  const quantize = (value) => Math.round(value / WALL_KEY_PITCH) * WALL_KEY_PITCH;
+  const mx = quantize((a[0] + b[0]) / 2);
+  const my = quantize((a[1] + b[1]) / 2);
+  let dx = b[0] - a[0], dy = b[1] - a[1];
+  const length = Math.hypot(dx, dy);
+  if (length < 1e-12) { dx = 1; dy = 0; }
+  else { dx /= length; dy /= length; }
+  if (dx < -1e-12 || (Math.abs(dx) <= 1e-12 && dy < 0)) { dx = -dx; dy = -dy; }
+  let angle = Math.atan2(dy, dx);
+  if (angle < 0) angle += Math.PI;
+  const bucket = Math.round(angle * 1800) / 1800;
+  return `${mx.toFixed(4)},${my.toFixed(4)}@${bucket.toFixed(4)}`;
+};
+
+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: fixtureWallKey(edge.a, edge.b),
+  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 },
+    },
+  };
+  // Keep sun.sun state-only on purpose. Core/runtime entities and YAML
+  // entities without unique_id may have a live state without a registry row.
+  // The production projection must preserve them.
+  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/baselines-index.json

@@ -0,0 +1,59 @@
+{
+  "schema": 1,
+  "matrixVersion": 18,
+  "acceptedAt": "2026-08-13T19:26:19.387Z",
+  "sourceFingerprint": "27fda3d75e4cda95b9d85a9481f15ccd44b96d8c9d3311e0476718d36e2588c5",
+  "chromium": "151.0.7922.34",
+  "scenarios": {
+    "split-corner-wall-before-dark": "3176dc67f54d5309f87c94e1077b4f69eb1db9f660469fbf97953038323430f3",
+    "split-corner-wall-thin-dark": "6da64905a3a4f8e4b4d457e5b20d2d55e0e7c2c601316a088c4bcc6557d35cc6",
+    "split-corner-wall-thick-dark": "494d559aa71ee85f90b8cfa11c1d3087fa123e963dec2b0975e7ce6c1520852a",
+    "isometric-geometry-view-dark": "73939fa61bebe2254591a788fad455a026a5e3b7394eeff27d4fe9a905de7ad2",
+    "isometric-geometry-view-light": "fc62f6ee8935d2e0c57b4918bf5fe554056a5956747b53a752ae265349ce662e",
+    "isometric-live-layers-dark": "869c62bf9cd762c36d342d1a3bbd992969425b46b132f3243439735e2c75c14f",
+    "isometric-no-borders-dark": "36f972f95704bff81ea1a59bdf3cd2cf7b636ec7871780460e98b23e3ebc3da2",
+    "isometric-touch-kiosk-dark": "5eba7794e563e1ef5b9387184693c819976454d0efd222bd12b38aad8ea03e20",
+    "isometric-large-warm-remount-dark": "798d312671dffebf59034a39f2865a65ece27a84b150e77bc59038bb2567d07c",
+    "geometry-view-dark-fit": "3df272f6c3c3d20e9e375ea037f3dbb885657b94b0b29d0067505f4a73741237",
+    "geometry-view-light-fit": "a7f2c9667d9872dd84a37d5318fd238c9eabcc0f413017eb19e02204587b4e1a",
+    "geometry-plan-editor-dark": "19b5c84943b70074ba1aae51d1e54f9a59c44dde34fff89e32f0babb1e90a2ca",
+    "opening-placement-door-thick-wall-dark": "395c03bbf5d968e83664fd6621f0ac25902e718022f2e92ffbcddb8ce629cf9c",
+    "geometry-devices-editor-dark": "a9e4846ce5453400b87e6ad3d575882bc23a07b59dc3eecb612ed872b0c871ec",
+    "geometry-decor-editor-dark": "435b36096bbb2996d56ff0af262ddebff4a727edd841b0fad9b8d4f507b987ac",
+    "tray-wide-selection-en": "024ac666ac4dac01a36f7d1fdbf3bb41f76a627377f7c02dc373f429dfe96d43",
+    "tray-wide-tool-ru": "669fc1cf04433b936c0e9d05799ad19eda8bc003d5ab71937d0512c8f49ba921",
+    "tray-medium-group-en": "50cd3980b21f554bec2e76f4d2e8032f4bd30c0679477eb2f5cbe22f68935b7c",
+    "tray-medium-selection-ru": "4e5f235be8ed6296e136641d172e727a6a6b7a9d061f0928a96ccc1103c19f1f",
+    "tray-narrow-palette-en": "88b9846e4b451ed95b7ae7d2c3183a2ea191d7668768992a1364c6a7a53eb0c6",
+    "tray-narrow-tool-ru": "c4130715b3cb31c68619dfc706a3aa308e86edf272bfae6833b20666764ece2b",
+    "geometry-diagonal-45-opening-dark": "01206d25631c8fd09fa077932fbb5c1ee115b65ba76b38e6f7b09315dbbf6002",
+    "openings-thick-wall-dark": "5aa0b3d26894bef9ab9fca25c31bbef2f13f2c410f5f6d3f61c8d608ceb929f8",
+    "openings-filled-tunnel-dark": "167d92c11e6a8b3ff0f31177ac5905f8db4b5fb03ee78b4965c40bc45aeee50f",
+    "openings-hidden-view-dark": "c85cc04d1d8622b98215e2bb83f5bb233a7cfb0ac684c912475ef7bc44245897",
+    "lighting-glow-sun-dark": "a98eee332f25a43c8d9d126c118c8cfea4ee73752b1060227548efedaf0efcdd",
+    "device-value-badge-positions-dark": "1ad43f2bd866733aa75c34de38fb97d469661799b540a8ae22150067d788cec8",
+    "lighting-sun-window-state-only-dark": "3bd581a23a2e0ebba58530db5182adea5cba6ec10bc032bee024415c19108a17",
+    "lighting-fill-light-axis-split-dark": "4f867528aeb9124229f81659876b03ff297a3a7a92bc57ffb32d5c24913c4938",
+    "lighting-fill-temp-axis-split-dark": "e0535b70701c9fe6753f74c943b9f288a0fb1a23a9cfc8590d4945e0a1724eb5",
+    "lighting-fill-lqi-axis-split-dark": "485ab183144913569ddc11154553ab4ac7db522ab188de74d652b717dc786d9c",
+    "lighting-temp-glow-dark": "ecaed039fb6aab4e1fdc9f1856c89e5f563219b8ff813877027737cecbeca41a",
+    "lighting-temp-glow-light": "5bc8a35aaa94c427d465d198f1cd5eecfdc704f5abeded9e407f32ce93aa7d32",
+    "lighting-custom-glow-dark": "899e334dfc0d3490ca291b7239bf7b88ca9d1ef3be199ddf347314bab1513f27",
+    "lighting-opaque-glow-two-doorways-dark": "413f5a8e39193ba941f72955a391ccac954c09f24322b7bf67494c7691275980",
+    "lighting-custom-glow-light": "266bba4ae1744a884b2cd224b37fdc36447d57405a1c5298ca30027e2957cc8a",
+    "lighting-temp-glow-no-sources-dark": "5100c81543fc30a7934a6db6f9e67e2c4fa185df0a974be5911879e43c0d3fc9",
+    "lighting-temp-glow-room-override-dark": "0a35d3508526187ea18e44456cfb8cd9e578a1864e896fad1c3eec2892c753e0",
+    "lighting-manual-auto-spill-overlap-dark": "6324dbe2079a255e7a194720c8c19f210549ac734e564270bc1373e6385b9cac",
+    "hover-over-glow-dark": "fc14ba6f6b670e61c0fb5be277e67551ea2da7a06b5c167a8c2c989f1de08910",
+    "hover-nested-room-dark": "6c09526ad885c4555063def5b43287b41124a81d90972c425084dba6e622d055",
+    "large-house-zoom-040-dark": "5f11c4b78318a64c2a7cf803716661eea506609d4f0a6bb3d64a709f8c49db1d",
+    "large-house-zoom-250-dark": "c906426f888ff4e306c5c334c6329b387fc5ca368e229f55acc33c202351a1ac",
+    "large-house-warm-remount-dark": "6baf4baed1c735c64dfe1e69d9864ca287ffc0e8452d00e801f0873e98b187ee",
+    "device-dialog-desktop-en": "d6fcc83aa1335df1041e2b1aa445b0019d1e3567f98ef8f47a889894051f2b62",
+    "device-dialog-mobile-ru": "8cb928853ddacb61882804c3d00ead31da31bc4559ee6a8e293ef6b55cd5a463",
+    "device-help-popover-light-ru": "f1bf21d62a5dd349aa57b746069c5aef58d7a26b0b9d9e0c233fde0c1d56d7eb",
+    "decor-color-popover-mobile-ru": "46d4c2e4dd20c3a38e90efe3db59b3e878bdbcf273fbc1aa23de4b230723fa6e",
+    "backup-full-preview-desktop-en": "1957c1c797c7793fb8dcf592ca74c9f2e3eccfcf4bac1d0187482c055bebb93b",
+    "backup-space-preview-mobile-ru": "998c6b52c1cc95109feb440a9966cade738154ceeae387246d40f8c56f9e8a3a"
+  }
+}