docs: review document for #266

Issue: #266
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/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@v7
+        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/docs-screenshots.yml

@@ -0,0 +1,84 @@
+# Скриншоты документации снимаются здесь и только здесь (#246).
+#
+# Съёмка на машине исполнителя даёт байтово разный PNG при одинаковом кадре:
+# сглаживание и хинтинг зависят от окружения. Измерено на истории — пересъёмка
+# в #231 изменила два файла из девяти на 7–8 байт, набор с беты все девять
+# целиком. Одно окружение убирает этот шум насовсем.
+#
+# Джоба ничего не коммитит: она публикует артефакт, который человек принимает
+# локально через `npm run docs:accept -- --reviewed --from=<распакованный>`.
+# Та же конструкция, что у golden-эталонов, и по той же причине: картинки
+# попадают в репозиторий через явное решение, а не через бота.
+name: Docs screenshots
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Ветка или SHA, с которого снимать
+        required: false
+        default: dev
+
+permissions:
+  contents: read
+
+jobs:
+  capture:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      # Тот же кэш и тот же отказ от --with-deps, что в smoke/golden (#175, #206):
+      # системные библиотеки Chromium уже в образе раннера.
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Install pinned Chromium
+        if: steps.pw.outputs.cache-hit != 'true'
+        run: npx playwright install chromium
+      - name: Build the bundle the screenshots must come from
+        run: npm run build
+      - name: Capture
+        run: node demo/docs/capture.mjs
+      # Вердикт до всякой приёмки. Само число изменившихся файлов ничего не
+      # говорит: набор, снятый другим браузером, меняет их все, и это нормально
+      # ровно один раз — при переходе на канонический прогон. Сравнивать надо
+      # браузер: тот же Chromium и десять изменившихся картинок означают, что
+      # изменился продукт (или что-то не так), другой Chromium — ожидаемую
+      # разницу рендеринга.
+      - name: Вердикт
+        run: |
+          git status --porcelain docs/images
+          changed=$(git diff --name-only docs/images | grep -c png || true)
+          before=$(git show HEAD:docs/images/screenshots.json | node -e \
+            "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).chromium||'')}catch{console.log('')}})")
+          after=$(node -e "console.log(require('./docs/images/screenshots.json').chromium)")
+          echo "--- изменившихся PNG: $changed"
+          echo "--- Chromium: было «${before:-не записан}», стало «$after»"
+          if [ "$before" = "$after" ] && [ "$changed" -gt 0 ]; then
+            echo "ВЕРДИКТ: тот же браузер, а картинки изменились — изменился продукт."
+            echo "Смотрите на кадры: если изменение ожидаемое, принимайте."
+          elif [ "$before" != "$after" ]; then
+            echo "ВЕРДИКТ: браузер другой, поэтому переписаны все кадры сразу."
+            echo "Это ожидаемо один раз — при переходе на канонический прогон."
+            echo "Если Chromium сменился неожиданно, сверьте закреплённую версию в package-lock."
+          else
+            echo "ВЕРДИКТ: ничего не изменилось, принимать нечего."
+          fi
+      - name: Upload candidate
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-screenshots
+          path: |
+            docs/images/*.png
+            docs/images/screenshots.json
+          if-no-files-found: error

.github/workflows/mutation-gate.yml

@@ -0,0 +1,73 @@
+name: Mutation gate
+
+# Реестр известных поломок (issue #85): каждый мутант ломает продуктовый код
+# известным способом, и объявленный тест ОБЯЗАН на этом покраснеть. Тест,
+# оставшийся зелёным на сломанном коде, ничего не защищает — он лишь выглядит
+# защитой, и это хуже его отсутствия.
+#
+# Прогон дорогой: пересборка бандла на каждого мутанта. Поэтому он не входит в
+# Validate и не идёт на каждый push. Его место — перед стабильным релизом
+# (PROCESS.md §8) и раз в неделю по расписанию, чтобы дрейф тестов не копился
+# до релиза. Дешёвая половина — «якоря патчей живы, guard-файлы существуют» —
+# идёт с обычными юнитами: test/mutation-gate.test.mjs.
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Git ref whose mutation guards must be proved
+        required: false
+        default: dev
+  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
+    # Все мутанты × (сборка + свой guard) — это десятки минут, и это нормально:
+    # гейт предрелизный. Час — потолок против зависшего Chromium.
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || 'dev' }}
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Установить backend test dependencies
+        run: pip install pytest voluptuous pytest-homeassistant-custom-component home-assistant-frontend
+
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v6
+        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,186 @@
+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@v7
+        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@v7
+        with:
+          ref: ${{ steps.base.outputs.sha }}
+          path: baseline
+
+      - uses: actions/setup-node@v7
+        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
+
+      # То же, что в validate.yml: кэш браузеров, apt не трогаем (#206).
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('candidate/package-lock.json') }}
+      - name: Install pinned Chromium
+        if: steps.pw.outputs.cache-hit != 'true'
+        working-directory: candidate
+        run: npx playwright install chromium
+
+      - name: Build both exact source trees
+        run: |
+          npm --prefix candidate run build
+          (cd candidate && node scripts/bundle-sync.mjs)
+          npm --prefix baseline run build
+          (cd baseline && node scripts/bundle-sync.mjs)
+
+      - 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:large-house-plan-snap -- --target-root=../baseline --samples=7 --warmups=1 --output=../artifacts/performance/plan-snap-baseline.json
+          npm run benchmark:large-house-plan-snap -- --target-root=. --samples=7 --warmups=1 --output=../artifacts/performance/plan-snap-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-house-plan-snap.json --baseline=../artifacts/performance/plan-snap-baseline.json --candidate=../artifacts/performance/plan-snap-candidate.json --output=../artifacts/performance/plan-snap-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@v7
+        with:
+          name: full-performance
+          path: artifacts/performance

.github/workflows/process.yml

@@ -0,0 +1,765 @@
+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 }}
+      spent: ${{ steps.decide.outputs.spent }}
+      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
+
+          # Считаются ДВЕ РАЗНЫЕ величины, и это не педантизм (#227).
+          #
+          # `attempt` — сколько раз ревью уже отработало на этом этапе. Он нужен
+          # только для имени документа и метки: два захода с одинаковым номером
+          # означают, что второй документ перезапишет первый и артефакт ревью
+          # исчезнет.
+          #
+          # `spent` — сколько циклов израсходовано из бюджета §4. Цикл — это
+          # «отправка на ревью → вердикт с блокирующими находками → возврат
+          # автору», поэтому бюджет тратят ТОЛЬКО жёлтые и красные вердикты.
+          # Зелёный ничего на правки не вернул и цикла не образует.
+          #
+          # Раньше обе роли исполнял один счётчик всех вердиктов, и конвейер
+          # наказывал за то, что предписывал сам: при неудавшемся слиянии он
+          # велит вернуть S7-code-review после ребейза, и этот заход добивал
+          # бюджет. На #225 (лёгкий трек, лимит 2) последовательность
+          # жёлтый → зелёный → ребейз дала review-4 на задаче с зелёным ревью и
+          # зелёным CI: работа встала, хотя после вердикта не было ни одной
+          # правки продуктового кода.
+          #
+          # Вердикты считаются ТОЛЬКО своего этапа: иначе вердикт по ТЗ съедал
+          # цикл из бюджета код-ревью (#89 получило r2/4). Этап опознаётся по
+          # имени документа в теле комментария; документа нет — вердикт не
+          # посчитается. Недосчёт даёт лишний заход, перерасчёт остановил бы
+          # работу досрочно: из двух ошибок выбрана обратимая.
+          attempt=1; spent=0; spent_list=""
+          if [ -n "$stage" ]; then
+            comments=$(gh issue view "$NUM" --repo "${{ github.repository }}" --json comments)
+            of_stage="[.comments[] | select(.body | test(\"Вердикт:\")) | select(.body | test(\"$marker\"))]"
+            # Блокирующим считается вердикт, у которого в строке вердикта стоит
+            # «жёлтый» или «красный». Регистр и окружение слова не важны.
+            blocking="$of_stage | map(select(.body | test(\"Вердикт:[^\\n]*(жёлт|красн)\"; \"i\")))"
+            attempt=$(( $(printf '%s' "$comments" | jq -r "$of_stage | length") + 1 ))
+            spent=$(printf '%s' "$comments" | jq -r "$blocking | length")
+            spent_list=$(printf '%s' "$comments" | jq -r "$blocking | map(\"- \" + .url) | join(\"\\n\")")
+          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
+            # Метку снимает владелец, а не конвейер: автоматика, отменяющая
+            # остановку работы, дороже ручного снятия. Но пересчёт печатается —
+            # метка могла остаться от прежнего правила, когда бюджет тратил и
+            # зелёный вердикт (#227).
+            stale=""
+            if [ "$spent" -lt "$limit" ]; then
+              stale=" Пересчёт по действующему правилу: блокирующих циклов $spent из $limit — метка могла остаться от прежнего правила, когда бюджет тратил любой вердикт. Снять её может владелец."
+            fi
+            refuse "стоит review-4 — решение за владельцем" \
+              "на issue стоит \`review-4\`: лимит циклов ревью исчерпан, дальше решает владелец — разделить задачу, отклонить или арбитраж (PROCESS.md §4).$stale"
+          elif [ "$spent" -ge "$limit" ]; then
+            echo "блокирующих циклов этапа $stage: $spent из $limit — лимит исчерпан"
+            gh issue edit "$NUM" --repo "${{ github.repository }}" --add-label review-4
+            # Перечень учтённого обязателен: иначе владельцу приходится читать
+            # всю ленту, чтобы понять, из чего сложился счёт.
+            gh issue comment "$NUM" --repo "${{ github.repository }}" --body \
+              "Лимит циклов ревью исчерпан: блокирующих циклов $spent из $limit на этапе \`$stage\` (заход $attempt). Следующего захода нет: решение владельца — разделить задачу, отклонить или арбитраж (PROCESS.md §4).
+
+          Учтены вердикты с блокирующими находками — зелёные бюджет не тратят:
+          $spent_list"
+            stage=""
+          else
+            echo "этап $stage, заход $attempt, блокирующих циклов $spent из $limit"
+          fi
+          echo "stage=$stage" >> "$GITHUB_OUTPUT"
+          echo "cycle=$attempt" >> "$GITHUB_OUTPUT"
+          echo "spent=$spent" >> "$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@v7
+        with:
+          fetch-depth: 0
+          ref: dev
+          # Иначе в конфиге git остаётся креденшел GITHUB_TOKEN, и push с
+          # мёртвым PAT молча уходит от github-actions[bot] — 403 при
+          # contents: read. Отказ обязан быть громким и правильным.
+          persist-credentials: false
+
+      # Живость PAT проверяется ДО ревью. На #150 истёкший токен обнаружился
+      # только на публикации документа — после сорока минут работы ревьюера.
+      - name: Секрет HP_PROCESS_TOKEN жив
+        env:
+          GH_TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::error::HP_PROCESS_TOKEN пуст — секрет удалён или недоступен"
+            exit 1
+          fi
+          if ! login=$(gh api user -q .login 2>/dev/null); then
+            echo "::error::HP_PROCESS_TOKEN не аутентифицируется — истёк или отозван. Обновить: Settings -> Secrets and variables -> Actions -> HP_PROCESS_TOKEN"
+            exit 1
+          fi
+          echo "токен жив, действует от: $login"
+
+      # Окружение готовит workflow, а не модель своими ходами. Раньше промпт
+      # велел ревьюеру самому выполнить `npm ci`: минуты уходили на установку без
+      # кэша, платились из бюджета 45 минут и из лимитов подписки, а ходы модели
+      # тратились на работу инфраструктуры. В validate.yml кэш стоит на всех
+      # тяжёлых job, здесь его не было.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      # Материал ревью живёт в ветке задачи: ТЗ в docs/specs/ и код коммитятся
+      # в issue/<NN>-slug. Если ветка запушена — переключаемся на неё, иначе
+      # ревьюер прочтёт dev и не найдёт того, что должен оценивать.
+      - name: Перейти на ветку задачи
+        id: branch
+        env:
+          NUM: ${{ github.event.issue.number }}
+        run: |
+          # Свежая по последнему коммиту, а не первая по алфавиту: на #150 рядом
+          # жили ветка ТЗ и ветка реализации, и head -1 выбрал устаревшую.
+          git fetch -q origin "+refs/heads/issue/${NUM}-*:refs/remotes/origin/issue/${NUM}-*" || true
+          branches=$(git for-each-ref --sort=-committerdate \
+            --format='%(refname:lstrip=3)' "refs/remotes/origin/issue/${NUM}-*")
+          branch=$(printf '%s\n' "$branches" | head -1)
+          if [ "$(printf '%s\n' "$branches" | grep -c .)" -gt 1 ]; then
+            echo "::warning::веток issue/${NUM}-* несколько ($(echo $branches | tr '\n' ' ')) — выбрана свежая по коммиту: $branch. Устаревшую следует удалить."
+          fi
+          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
+
+      # Ревьюер обязан смотреть тот же код, который уедет в dev (#257). Раньше
+      # ревью шло по ветке как есть, а слияние делало ребейз — проверенный SHA и
+      # слитый SHA были разными коммитами. Пока расхождение с dev текстовое,
+      # ребейз упирается в конфликт и это видно; смысловое расхождение git
+      # склеивает молча, и в dev уезжает комбинация, которую никто не читал.
+      # Именно так пришёл регресс #234.
+      #
+      # Заодно снимается плата за конфликт: он обнаруживался ПОСЛЕ сорока минут
+      # ревью и потраченных лимитов подписки, хотя виден за пять секунд до них.
+      #
+      # Этап spec не затрагивается: ветку ТЗ в dev никто не сливает, и трогать
+      # чужую ветку без нужды — лишний риск.
+      - name: Привести ветку к dev
+        id: rebase
+        if: needs.guard.outputs.stage == 'code' && steps.branch.outputs.name != ''
+        env:
+          TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          BRANCH: ${{ steps.branch.outputs.name }}
+          # rebase, в отличие от commit, не принимает -c user.*: он запускает
+          # свои процессы и требует личность в окружении, иначе падает с
+          # «unable to auto-detect email address».
+          GIT_AUTHOR_NAME: claude[bot]
+          GIT_AUTHOR_EMAIL: 209825114+claude[bot]@users.noreply.github.com
+          GIT_COMMITTER_NAME: claude[bot]
+          GIT_COMMITTER_EMAIL: 209825114+claude[bot]@users.noreply.github.com
+        run: |
+          git fetch -q origin dev
+          if git merge-base --is-ancestor origin/dev HEAD; then
+            echo "ветка содержит весь dev — ребейз не нужен"
+            exit 0
+          fi
+          behind=$(git rev-list --count "HEAD..origin/dev")
+          before=$(git rev-parse "origin/$BRANCH")
+          echo "dev впереди на $behind коммит(ов) — привожу ветку"
+          if ! git rebase origin/dev; then
+            git rebase --abort || true
+            echo "conflict=true" >> "$GITHUB_OUTPUT"
+            echo "::warning::ветка $BRANCH не ребейзится на dev без конфликта — ревью не запускается"
+            exit 0
+          fi
+          # --force-with-lease с явным ожидаемым значением обязателен: между
+          # fetch и push автор мог запушить коммит, и слепой --force потерял бы
+          # его молча. Расхождение lease — падение прогона, а не предупреждение:
+          # ревью пошло бы по коду, которого на ветке уже нет.
+          if ! git push -q --force-with-lease="refs/heads/$BRANCH:$before" \
+               "https://x-access-token:$TOKEN@github.com/${{ github.repository }}" \
+               "HEAD:refs/heads/$BRANCH"; then
+            echo "::error::ветка $BRANCH изменилась во время ребейза — прогон прерван, чтобы не потерять коммит автора"
+            exit 1
+          fi
+          # Локальная ссылка обновляется тоже: шаг слияния берёт origin/$BRANCH,
+          # и без этого он ребейзил бы заново уже приведённое.
+          git fetch -q origin "+refs/heads/$BRANCH:refs/remotes/origin/$BRANCH"
+          short_before=$(git rev-parse --short "$before")
+          short_after=$(git rev-parse --short HEAD)
+          echo "note=Ветка приведена к dev конвейером до ревью: поверх легло $behind коммит(ов) dev, $short_before -> $short_after. После ребейза это другой код (§7.2) — разбор полный, а не по дельте." >> "$GITHUB_OUTPUT"
+          echo "ветка $BRANCH приведена к dev: $short_before -> $short_after"
+
+      # Конфликт возвращает задачу автору ДО ревью. Инвариант «после прогона
+      # метка меняется всегда» при этом держится: возврат в S6-in-progress —
+      # тоже смена метки, и автор не ждёт впустую.
+      - name: Конфликт с dev — вернуть автору без ревью
+        if: steps.rebase.outputs.conflict == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          NUM: ${{ github.event.issue.number }}
+          BRANCH: ${{ steps.branch.outputs.name }}
+        run: |
+          cat > /tmp/stale.md <<EOF
+          **Ревью не запускалось:** ветка \`$BRANCH\` не ребейзится на \`dev\` без конфликта. Код никто не читал, вердикта нет, цикл ревью не израсходован.
+
+          Проверка стоит до ревью намеренно: конфликт всё равно вернул бы задачу, но уже после сорока минут работы ревьюера и потраченных лимитов.
+
+          Задача переведена в \`S6-in-progress\`. Осталось:
+
+          1. \`git fetch origin\`, затем \`git rebase origin/dev\` в ветке задачи, разрешить конфликт;
+          2. запушить ветку;
+          3. вернуть метку \`S7-code-review\`.
+
+          [Прогон](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).
+          EOF
+          gh issue comment "$NUM" --repo "${{ github.repository }}" --body-file /tmp/stale.md
+          gh issue edit "$NUM" --repo "${{ github.repository }}" \
+            --add-label S6-in-progress --remove-label S7-code-review
+          echo "S7-code-review -> S6-in-progress (ревью не запускалось)"
+
+      # Зависимости ставятся ПОСЛЕ переключения на ветку задачи: lockfile мог
+      # измениться именно в ней, и установка по копии из dev дала бы не то дерево.
+      - name: Установить зависимости
+        if: steps.rebase.outputs.conflict != 'true'
+        run: npm ci
+
+      # Браузер нужен не всякому ревью (см. правило выбора гейтов в промпте),
+      # но когда нужен — качать его заново дороже, чем держать в кэше.
+      - name: Кэш браузеров Playwright
+        id: pw
+        if: steps.rebase.outputs.conflict != 'true'
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
+      - name: Установить Chromium
+        if: steps.rebase.outputs.conflict != 'true' && steps.pw.outputs.cache-hit != 'true'
+        # Без --with-deps: системные библиотеки Chromium предустановлены в
+        # образе ubuntu-latest, а apt при промахе кэша съедал минуты из бюджета
+        # ревью и подолгу перебирал недоступное azure-зеркало (#175). Если
+        # библиотека когда-нибудь пропадёт из образа, Chromium не запустится с
+        # внятной ошибкой — тогда флаг вернуть.
+        run: npx playwright install chromium
+
+      - name: Review
+        id: review
+        if: steps.rebase.outputs.conflict != 'true'
+        uses: anthropics/claude-code-action@v1
+        env:
+          # Вне рабочей копии: восстановление дерева ревьюером не должно
+          # уничтожать его собственный артефакт (#220).
+          REVIEW_DOC: ${{ runner.temp }}/review-document.md
+        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)
+            Заход: r${{ needs.guard.outputs.cycle }} · блокирующих циклов израсходовано ${{ needs.guard.outputs.spent }} из ${{ needs.guard.outputs.limit }}
+              Бюджет §4 тратят только жёлтые и красные вердикты: зелёный
+              ничего не вернул на правки и цикла не образует (#227).
+              Номер захода нужен для имени документа — два документа с
+              одинаковым номером затёрли бы друг друга.
+
+            ${{ steps.rebase.outputs.note }}
+
+            **Если цикл не первый — объём разбора по дельте, а не заново**
+            (PROCESS.md §2.9, issue #214). Раньше промпт был одинаковым для
+            всех раундов, и повторный цикл заново выводил продуктовую рамку и
+            перепроверял AC, которых правка не касалась: r2 по #150 стоил
+            полного прогона ради одной строки в тестовой фикстуре.
+
+            Порядок для r2 и дальше:
+              1. найди вердикт предыдущего раунда в комментариях issue и SHA,
+                 на котором он получен. SHA в вердикте не назван — это находка;
+              2. объяви дельту: `git diff <тот SHA>..HEAD` для кода, дифф файла
+                 ТЗ или тела issue для spec. Дельта — предмет этого раунда;
+              3. по каждой находке предыдущего раунда покажи, чем именно она
+                 закрыта: строка кода или текста, а не заявление автора;
+              4. заново проверяй только те AC, чьё доказательство дельта
+                 задевает. Остальные наследуй;
+              5. в документе обязателен раздел «Унаследовано из r<N-1>»: что
+                 принято без повторной проверки, со ссылкой на документ того
+                 раунда и SHA, на котором вывод получен. Без этого перечня
+                 сокращение — молчаливое доверие, а такой тихий успех уже
+                 дважды стоил дня (#171, #207).
+
+            Разбор остаётся ПОЛНЫМ, если дельта не локальна: ребейз на ушедший
+            вперёд dev (после ребейза это другой код, §7.2), смена контракта
+            поведения, задета новая подсистема, либо объём дельты сопоставим с
+            исходной задачей. Сомневаешься — разбирай полностью и скажи почему.
+
+            Сокращается объём РАЗБОРА, а не строгость: правка по замечанию
+            способна сломать AC, который предыдущий раунд признал выполненным —
+            так появилась регрессия #102. Поэтому граница не «только находки», а
+            «находки плюс всё, до чего дотягивается дельта».
+
+            Прочитай в этом порядке, прежде чем судить:
+              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` со сверкой трёх
+              копий бандла. Плюс `node scripts/check-docs.mjs`, если diff трогает
+              `src/**`: отпечаток скриншотов документации считается по всему
+              `src/**`, поэтому любая правка фронтенда делает его устаревшим —
+              выбирать тут нечего. Пропуск этого шага в #230 и #234 оставил `dev`
+              с красным job `docs` до следующей задачи (#237).
+
+            Если diff трогает геометрию или ссылки на неё — рёбра комнат,
+            записи толщины, `layout`, `marker.space`, `open_spans` — обязательны
+            инварианты модели (#254): `npm test` уже гоняет их на всех моделях
+            проекта, а на конкретной конфигурации они проверяются командой
+            `npm run invariants -- --config <экспорт или ответ config/get>`.
+            Три вопроса, на которые они отвечают, и все три уже стоили
+            продукту дефектов: не исчезла ли запись толщины (#253), разрешима ли
+            каждая ссылка (#244, #252) и равен ли ключ записи толщины ключу
+            решёточного ребра (#258, #259). Последний сравнивает строки без
+            допусков: сдвиг ключа на один шаг решётки равен допуску первых двух,
+            поэтому они на нём промахиваются. Если задача меняет геометрию, а
+            инварианты в отчёте не названы — это непрогнанный гейт, а не мелочь.
+
+            По необходимости, и «необходимость» определяется diff'ом и AC:
+              - браузерные смоки `demo/smoke_*.mjs` — названные в AC плюс те,
+                что печатает `node scripts/smoke-select.mjs --base <base> --head <head>`.
+                Сколько их всего — считает `ls demo/smoke_*.mjs | wc -l`; вшитое
+                в этот текст число трижды расходилось с деревом, поэтому его
+                здесь больше нет. Прогон всех уместен только когда задача
+                действительно задевает всё. Выбирать по теме недостаточно: регресс #234 поймал
+                `smoke_wall_junctions`, который по названию про стыки стен, а не
+                про толщину отрезка. Инструмент печатает три вида ответа, и они
+                разные: «прямое совпадение» — смок называет изменённый символ,
+                «зарегистрированная связь» — смок проверяет следствие контракта,
+                не называя его, «НЕОПРЕДЕЛЁННОСТЬ» — связь не доказана, и это не
+                разрешение ничего не прогонять. Вывод инструмента прикладывается
+                к комментарию ревью вместе с решением по каждой строке: прогнал
+                либо не прогнал и почему. Слабые связи (одно распространённое
+                имя) — повод посмотреть, а не обязанность прогонять;
+              - `npm run golden:verify` — если diff может изменить видимый
+                результат: рендер, геометрия, стили, слои;
+              - `python -m pytest tests_backend -q` — если тронут
+                `custom_components/**/*.py`;
+              - performance-профили — если названы в AC либо тронуты
+                чувствительные к перфу пути.
+
+            **Одно число — один источник.** Если дифф добавляет или меняет
+            величину, видимую пользователю, назови в отчёте прямо: какое число
+            видно дважды (превью против записи, подпись против площади,
+            подсветка инструмента против сохранённого значения) и один ли у него
+            источник. Три дефекта подряд имели именно эту причину — #234, #233 и
+            способ, которым #234 обнаружили. Механическая часть закреплена
+            тестом `test/single-source-numbers.test.mjs`, смысловая — твоя.
+
+            Дисциплина «тест должен уметь падать» не отменяется, но применяется к
+            тем тестам, которые ты прогонял.
+
+            **В комментарии обязателен перечень: какие гейты прогнал, какие нет и
+            почему.** Это условие честности такого сужения: непрогнанный гейт
+            становится видимым решением, а не молчаливым пропуском. Раздел «чего
+            не проверял» в документе ревью — не формальность, а главный его
+            раздел на коротких задачах.
+
+            Ты НЕ правишь ни ТЗ, ни продуктовый код. Только оцениваешь.
+
+            Серьёзность: High блокирует; Medium В СКОУПЕ задачи чинится в ней
+            же — без High это жёлтый вердикт и возврат автору, отдельный issue
+            НЕ заводится (решение владельца 2026-08-19, #202: заведение и
+            обслуживание issue дороже правки на месте); Low либо правится,
+            либо снимается с записью. Жёлтый вердикт допустим и при полностью
+            выполненных AC, если изменение не решает заявленный сценарий или
+            ухудшает смежный. Продуктовое рассуждение расширяет вопросы, но не
+            отменяет AC и не даёт права менять скоуп.
+
+            Только Medium-находку ВНЕ скоупа задачи (попутный дефект соседнего
+            поведения, который в этой ветке чинить нельзя) заведи отдельным
+            issue со ссылкой на #${{ github.event.issue.number }} и метками:
+            тип, приоритет, S1-new. «Оставили в тексте ревью» закрытием не
+            считается и прямо запрещено §12.
+
+            Напиши полный документ ревью в файл, путь которого лежит в
+            переменной окружения REVIEW_DOC (абсолютный, ВНЕ репозитория).
+
+            Почему не в docs/reviews: документ там был некоммитнутым файлом того
+            же дерева, которое ты мутируешь, проверяя «умеет ли тест падать». На
+            #220 три раунда подряд документ исчезал — восстановление дерева
+            (`git checkout -- .`, `git clean -fd`) сносит собственный артефакт
+            ревью, потому что он untracked. В репозиторий его положит шаг
+            публикации, взяв из REVIEW_DOC; тебе трогать docs/reviews не нужно.
+
+            В самом репозитории не создавай файлов вообще: любые изменения в
+            рабочей копии будут отброшены. Имя документа в docs/reviews шаг
+            публикации соберёт сам — SPEC-REVIEW для этапа spec, CODE-REVIEW для
+            code, с номером issue и заходом.
+
+            Содержание документа: скоуп, как проверялось, находки с
+            воспроизведением, что проверено и корректно, чего не проверял. Для
+            r2 и дальше добавь два раздела: «Закрытие раунда r<N-1>» — таблица
+            «находка | чем закрыта | где это видно», и «Унаследовано из r<N-1>» —
+            что принято без повторной проверки, с документом и SHA.
+
+            Затем оставь в issue краткий комментарий: вердикт, ключевые находки
+            и ссылка на документ. Первой строкой — вердикт в формате §7.2:
+            `Вердикт: зелёный/жёлтый/красный · заход r${{ needs.guard.outputs.cycle }} · блокирующих циклов ${{ needs.guard.outputs.spent }}/${{ needs.guard.outputs.limit }} · High: N · Medium: N → в задаче | #…`
+            («→ #…» — только у Medium вне скоупа; находки в скоупе возвращаются автору жёлтым)
+
+            Затем верни 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: Опубликовать документ ревью
+        if: steps.rebase.outputs.conflict != 'true'
+        env:
+          TOKEN: ${{ secrets.HP_PROCESS_TOKEN }}
+          BRANCH: ${{ steps.branch.outputs.name }}
+          NUM: ${{ github.event.issue.number }}
+          STAGE: ${{ needs.guard.outputs.stage }}
+          CYCLE: ${{ needs.guard.outputs.cycle }}
+          SOURCE: ${{ runner.temp }}/review-document.md
+        run: |
+          # Ветки задачи может не быть: у задач, размеченных до появления
+          # конвейера, ТЗ лежит прямо в dev. Раньше шаг в этом случае молча
+          # выходил с нулём, и разбор ревью терялся — оставался только вердикт
+          # комментарием. Это тот же тихий отказ: шаг сообщал об успехе тем, что
+          # ничего не сделал. Документ ложится туда же, где лежит само ТЗ.
+          target="${BRANCH:-dev}"
+          if [ -z "$BRANCH" ]; then
+            echo "::warning::ветки задачи нет — документ ревью ляжет в dev"
+          fi
+          marker=CODE-REVIEW
+          if [ "$STAGE" = "spec" ]; then marker=SPEC-REVIEW; fi
+          doc="docs/reviews/${marker}-${NUM}-r${CYCLE}.md"
+          # Рабочая копия отбрасывается ДО того, как документ попадёт в дерево:
+          # ревьюер правит код, проверяя «умеет ли тест падать», и его правки
+          # публиковаться не должны.
+          git checkout -- . 2>/dev/null || true
+          # docs/reviews исключён из уборки: ревьюер мог написать документ по
+          # старому пути, и клин не должен его съесть до `git add` — ровно так
+          # оба пути остаются работоспособными.
+          git clean -fd -e docs/reviews -e node_modules >/dev/null 2>&1 || true
+          # Документ приезжает извне репозитория (#220). Три раунда подряд он
+          # терялся, пока лежал некоммитнутым файлом в том же дереве, которое
+          # ревьюер мутирует и затем восстанавливает: `git checkout -- .` плюс
+          # `git clean -fd` сносят собственный артефакт ревью, потому что он
+          # untracked. Теперь его место — RUNNER_TEMP, и уборка дерева ему не
+          # страшна.
+          if [ -f "$SOURCE" ]; then
+            mkdir -p docs/reviews
+            cp "$SOURCE" "$doc"
+            echo "документ взят из $SOURCE ($(wc -c < "$doc") байт)"
+          else
+            # Совместимость: ревьюер мог написать по старому пути, если промпт
+            # ещё не обновился в этой ветке.
+            echo "::warning::$SOURCE не найден — ищу документ в рабочей копии"
+          fi
+          git add docs/reviews 2>/dev/null || true
+          if git diff --cached --quiet; then
+            # Пустая рабочая копия — ещё не провал: ревьюер иногда коммитит
+            # документ сам, своим app-токеном мимо этого шага (CODE-REVIEW-150-r1,
+            # коммиттер GitHub). Провал — когда файла нет и на ветке.
+            git fetch -q origin "$target"
+            if git cat-file -e "origin/$target:$doc" 2>/dev/null; then
+              echo "документ уже опубликован ревьюером: $doc"
+              exit 0
+            fi
+            # Ревью без артефакта запрещено (PROCESS.md §2.4/§10.4/§12). Раньше
+            # здесь стоял warning с exit 0: на #150 оба вердикта ревью ТЗ
+            # остались только комментариями, метки переставились, и пропажу
+            # заметило лишь следующее ревью — issue #171. Падение ДО шага с
+            # меткой сохраняет инвариант «метка не сменилась = прогон упал».
+            echo "::error::вердикт есть, а документа нет: ни $SOURCE, ни $doc в рабочей копии, ни $doc в $target — ревью без артефакта (#171, #220)"
+            exit 1
+          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
+              # Тоже вердикт без артефакта: раньше exit 0 переставил бы метку.
+              echo "::error::документ ревью не удалось опубликовать в $target: конфликт (#171)"
+              exit 1
+            fi
+            git push -q "https://x-access-token:$TOKEN@github.com/${{ github.repository }}" \
+              "HEAD:$target"
+          fi
+          # Постусловие: до ветки дошёл именно ожидаемый файл. Коммит с
+          # документом, названным не по формату, — тот же вердикт без
+          # артефакта, только дороже в обнаружении.
+          git fetch -q origin "$target"
+          if ! git cat-file -e "origin/$target:$doc" 2>/dev/null; then
+            echo "::error::коммит в $target опубликован, но ожидаемого $doc в нём нет — файл назван не по формату (#171)"
+            exit 1
+          fi
+          echo "документ опубликован в $target: $doc"
+
+      - name: Решение по вердикту
+        id: decide
+        if: steps.rebase.outputs.conflict != 'true'
+        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: Переставить метку
+        if: steps.rebase.outputs.conflict != 'true'
+        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,258 @@
+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@v7
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v7
+        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@v7
+        with:
+          ref: ${{ needs.gate.outputs.sha }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v7
+        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
+          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@v9
+        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@v7
+        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

@@ -16,11 +16,11 @@ jobs:
   gate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.release.tag_name }}
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with: { node-version: 22 }
       - name: Require a green Validate for this exact commit
         env:
@@ -34,19 +34,40 @@ jobs:
           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
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.release.tag_name }}
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         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
+          node scripts/bundle-sync.mjs
+          npm run continuity:screencast
+      - name: Upload failed continuity frames
+        if: ${{ failure() && !github.event.release.prerelease }}
+        uses: actions/upload-artifact@v7
+        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
+        uses: softprops/action-gh-release@v3
         with:
           files: dist/houseplan-card.js
   hacs-discovery:
@@ -59,7 +80,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Verify the published tag is the prerelease HACS will discover
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         with:
           script: |
             const releases = await github.paginate(github.rest.repos.listReleases, {

.github/workflows/validate.yml

@@ -1,30 +1,271 @@
 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:
+      - '**'
+    # Документы ревью конвейер пишет пачками — 340 коммитов за месяц, и каждый
+    # гонял лёгкую половину Validate впустую (≈15 часов раннера в месяц).
+    # Релизного кандидата это не затрагивает: тег всегда стоит на коммите,
+    # который меняет версию и бандл, а не только `docs/reviews/**`.
+    paths-ignore:
+      - 'docs/reviews/**'
   pull_request:
-  schedule:
-    - cron: "0 4 * * 1"
+
+# A new push supersedes an unfinished validation for the same branch or PR.
+# Exact-SHA release gates never depend on an obsolete commit.
+concurrency:
+  group: validate-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  hacs:
+  docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with: { node-version: 22 }
+      - name: Validate public documentation
+        run: node scripts/check-docs.mjs --external
+
+  # Конвейер читает `process.yml` из ветки по умолчанию, поэтому файл обязан
+  # совпадать в `main` и `dev`. До этой проверки совпадение держалось на
+  # дисциплине: каждая правка требовала двух пушей и ручной сверки.
+  process-workflow-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: process.yml идентичен в main и dev
+        run: |
+          git fetch --quiet origin main dev
+          if diff <(git show origin/main:.github/workflows/process.yml) \
+                  <(git show origin/dev:.github/workflows/process.yml); then
+            echo "main и dev идентичны"
+          else
+            echo "РАСХОЖДЕНИЕ: process.yml в main и dev различаются."
+            echo "Конвейер исполняет версию из ветки по умолчанию, поэтому"
+            echo "правку нужно отправить в обе ветки."
+            exit 1
+          fi
+
+  provenance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v7
+        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 }}
+          DEVELOPMENT_BRANCH: dev
+        run: |
+          git fetch -q origin "refs/heads/$DEVELOPMENT_BRANCH:refs/remotes/origin/$DEVELOPMENT_BRANCH"
+          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@v7
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v7
+        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 }}
+          DEVELOPMENT_BRANCH: dev
+          TARGET_REF: ${{ github.ref }}
+          # Публичный репозиторий: штатного токена хватает на чтение issue.
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          git fetch -q origin "refs/heads/$DEVELOPMENT_BRANCH:refs/remotes/origin/$DEVELOPMENT_BRANCH"
+          node scripts/process-gate.mjs --github-range --issues
+
+  # Классификация изменённых путей: тяжёлые job идут только там, где менялось
+  # относящееся к ним. НА DEV ФИЛЬТРОВ НЕТ: гейт беты принимает «зелёный Validate
+  # на точном SHA», и если объём прогона зависит от diff, «зелёный» перестаёт
+  # значить одно и то же — кандидат релиза (манифесты + changelog) пропустил бы
+  # браузерные тесты, а прогон с пропущенными job всё равно success. Фильтры
+  # экономят на ветках задач, где Validate — ранний сигнал: настоящую приёмку
+  # там делает код-ревью, которое гоняет гейты само (#127).
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      frontend: ${{ steps.classify.outputs.frontend }}
+      backend: ${{ steps.classify.outputs.backend }}
+      integration: ${{ steps.classify.outputs.integration }}
+    steps:
+      - uses: actions/checkout@v7
+        with: { fetch-depth: 0 }
+      - id: classify
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BEFORE_SHA: ${{ github.event.before }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.sha }}
+          REF: ${{ github.ref }}
+        run: |
+          if [ "$REF" = "refs/heads/dev" ]; then
+            echo "dev: без фильтров, всё true"
+            printf 'frontend=true\nbackend=true\nintegration=true\n' >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          zero=$(printf '%040d' 0)
+          base="$BEFORE_SHA"
+          if [ "$EVENT_NAME" = "pull_request" ]; then base="$BASE_SHA"; fi
+          # Новая ветка: before нулевой, диапазон считается от merge-base с dev,
+          # иначе классифицировалась бы вся история.
+          if [ -z "$base" ] || [ "$base" = "$zero" ] \
+             || ! git cat-file -e "$base" 2>/dev/null; then
+            git fetch -q origin dev
+            base=$(git merge-base origin/dev "$HEAD_SHA" || echo "$HEAD_SHA~1")
+          fi
+          files=$(git diff --name-only "$base" "$HEAD_SHA")
+          printf '%s\n' "$files" | head -50
+          has() { printf '%s\n' "$files" | grep -qE "$1" && echo true || echo false; }
+          {
+            echo "frontend=$(has '^(src/|demo/|test/|dist/|custom_components/houseplan/frontend/|package(-lock)?\.json$|rollup\.config\.mjs$|tsconfig)')"
+            echo "backend=$(has '^(custom_components/.*\.py$|tests_backend/|pytest\.ini$)')"
+            echo "integration=$(has '^(custom_components/houseplan/manifest\.json$|hacs\.json$|custom_components/.*\.py$|custom_components/.*/translations/)')"
+          } >> "$GITHUB_OUTPUT"
+
+  # Переиспользование результата тяжёлой job (#208). Ключ = входы поведения
+  # (sourceFingerprint: src/**, demo/fixtures, demo/golden/*.mjs, манифесты
+  # сборки) ПЛЮС оснастка именно этой job. Маркер в кэше пишет только успешный
+  # прогон с тем же ключом, поэтому попадание доказывает: job с побайтово теми
+  # же входами уже завершилась успешно.
+  #
+  # Это НЕ фильтр путей из job `changes` (на dev они отключены намеренно): там
+  # объём прогона угадывается по путям и «зелёный» начинает значить разное,
+  # здесь эквивалентность входов доказана хешем.
+  #
+  # Свойство, снимающее главный риск: релизный кандидат бампает версию, а
+  # CARD_VERSION и package.json входят в фингерпринт, поэтому ключи кандидата
+  # заведомо новые и полный набор гейтов перед бетой и релизом идёт всегда.
+  reuse:
+    runs-on: ubuntu-latest
+    outputs:
+      smoke: ${{ steps.probe.outputs.smoke }}
+      golden: ${{ steps.probe.outputs.golden }}
+      performance_smoke: ${{ steps.probe.outputs.performance_smoke }}
+      backend: ${{ steps.probe.outputs.backend }}
+      smoke_key: ${{ steps.keys.outputs.smoke }}
+      golden_key: ${{ steps.keys.outputs.golden }}
+      performance_smoke_key: ${{ steps.keys.outputs.performance_smoke }}
+      backend_key: ${{ steps.keys.outputs.backend }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with: { node-version: 22 }
+      - name: Ключи переиспользования
+        id: keys
+        run: |
+          for job in smoke golden performance_smoke backend; do
+            key=$(node scripts/gate-reuse.mjs --job="$job")
+            echo "$job=$key" >> "$GITHUB_OUTPUT"
+            echo "$job: $key"
+          done
+      # lookup-only: маркер только проверяется, но не восстанавливается —
+      # сохранять его в этой job нечего, она ничего не прогоняла.
+      - name: Маркер smoke
+        id: m_smoke
+        uses: actions/cache/restore@v6
+        with:
+          path: .reuse-marker
+          key: reuse-smoke-${{ steps.keys.outputs.smoke }}
+          lookup-only: true
+      - name: Маркер golden
+        id: m_golden
+        uses: actions/cache/restore@v6
+        with:
+          path: .reuse-marker
+          key: reuse-golden-${{ steps.keys.outputs.golden }}
+          lookup-only: true
+      - name: Маркер performance_smoke
+        id: m_perf
+        uses: actions/cache/restore@v6
+        with:
+          path: .reuse-marker
+          key: reuse-performance_smoke-${{ steps.keys.outputs.performance_smoke }}
+          lookup-only: true
+      - name: Маркер backend
+        id: m_backend
+        uses: actions/cache/restore@v6
+        with:
+          path: .reuse-marker
+          key: reuse-backend-${{ steps.keys.outputs.backend }}
+          lookup-only: true
+      - name: Что переиспользуем
+        id: probe
+        env:
+          SMOKE: ${{ steps.m_smoke.outputs.cache-hit }}
+          GOLDEN: ${{ steps.m_golden.outputs.cache-hit }}
+          PERF: ${{ steps.m_perf.outputs.cache-hit }}
+          BACKEND: ${{ steps.m_backend.outputs.cache-hit }}
+        run: |
+          # Пропуск обязан быть громким: молчаливый skip — тот самый тихий
+          # успех, который уже дважды стоил нам дня (#171, #207).
+          waive() {
+            if [ "$2" = "true" ]; then
+              echo "$1=true" >> "$GITHUB_OUTPUT"
+              echo "::notice::$1 не прогоняется: входы побайтово те же, что в предыдущем успешном прогоне (#208)"
+              echo "- **$1** переиспользована: входы не менялись" >> "$GITHUB_STEP_SUMMARY"
+            else
+              echo "$1=false" >> "$GITHUB_OUTPUT"
+              echo "- $1: прогоняется" >> "$GITHUB_STEP_SUMMARY"
+            fi
+          }
+          echo "### Переиспользование гейтов (#208)" >> "$GITHUB_STEP_SUMMARY"
+          waive smoke "$SMOKE"
+          waive golden "$GOLDEN"
+          waive performance_smoke "$PERF"
+          waive backend "$BACKEND"
+
+  hacs:
+    needs: changes
+    if: needs.changes.outputs.integration == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
       - name: HACS validation
         uses: hacs/action@main
         with:
           category: integration
+
   hassfest:
+    needs: changes
+    if: needs.changes.outputs.integration == 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Hassfest validation
         uses: home-assistant/actions/hassfest@master
+
   frontend:
+    needs: changes
+    if: needs.changes.outputs.frontend == 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 22 }
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
       - run: npm ci
       - name: Typecheck
         run: npm run typecheck
@@ -32,29 +273,60 @@ jobs:
         run: npm test
       - name: Build
         run: npm run build
-      - name: Card bundle in sync with integration
+      # Копия стенда больше не коммитится (#255): сверяются две обязательные.
+      - name: Card bundle snapshots in sync
         run: cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js
+
   smoke:
-    # audit T2: the end-to-end layer used to run only when a human remembered.
     # Gated on `frontend` so a typecheck failure does not burn browser minutes.
-    needs: frontend
+    needs: [frontend, reuse]
+    if: needs.reuse.outputs.smoke != 'true'
     runs-on: ubuntu-latest
+    # Смоки шардируются: последовательный прогон занимал ~7.5 минут и был
+    # критическим путём всего Validate. Три шарда режут его примерно вдвое;
+    # цена — трижды `npm ci` и сборка, около двух оплаченных минут раннера.
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 22 }
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
       - run: npm ci
-      - name: Install Chromium for Playwright
-        run: npx playwright install --with-deps chromium
-      - name: Build a FRESH bundle for the smokes
-        # the committed demo/srv/assets copy is a snapshot; testing it would
-        # report green about code that no longer exists (audit T2)
-        run: npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
-      - name: Smoke suite
+      # Браузеры кэшируются, а apt не запускается вовсе: на GitHub-раннере
+      # системные библиотеки Chromium уже в образе, а --with-deps тратил минуты
+      # и подолгу перебирал недоступное azure-зеркало (#175, #206). Если
+      # библиотека когда-нибудь исчезнет из образа, Chromium не запустится с
+      # внятной ошибкой — тогда флаг вернуть.
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Install pinned Chromium
+        if: steps.pw.outputs.cache-hit != 'true'
+        run: npx playwright install chromium
+      - name: Build a fresh bundle for the smokes
+        run: npm run bundle:sync
+      - name: Smoke suite (шард ${{ matrix.shard }} из 3)
+        env:
+          SHARD: ${{ matrix.shard }}
+          SHARDS: '3'
         run: |
           fail=0
+          index=0
+          ran=0
           mkdir -p /tmp/smoke-logs
+          # Деление по порядковому номеру файла: список отсортирован, поэтому
+          # разбиение детерминировано и не зависит от времени прогона.
           for f in demo/smoke_*.mjs; do
+            index=$((index + 1))
+            if [ $(( (index - 1) % SHARDS + 1 )) -ne "$SHARD" ]; then continue; fi
+            ran=$((ran + 1))
             name=$(basename "$f" .mjs)
             if node "$f" > "/tmp/smoke-logs/$name.log" 2>&1; then
               echo "ok   $name"
@@ -64,20 +336,191 @@ jobs:
               fail=1
             fi
           done
+          echo "--- шард ${SHARD}/${SHARDS}: прогнано ${ran} из ${index}"
+          # Пустой шард — признак, что деление сломалось, а не что работы нет.
+          if [ "$ran" -eq 0 ]; then echo "шард пуст: проверьте деление"; exit 1; fi
           exit $fail
       - name: Upload smoke logs
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
-          name: smoke-logs
+          name: smoke-logs-${{ matrix.shard }}
           path: /tmp/smoke-logs
 
-  backend:
+  # Маркер переиспользования пишется ОДИН раз и только когда прошли все шарды:
+  # частично прогнанная матрица не имеет права выглядеть как выполненная работа.
+  smoke_done:
+    needs: [smoke, reuse]
+    if: needs.reuse.outputs.smoke != 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - name: Записать маркер успеха
+        run: |
+          printf '%s\n' "smoke прогнана успешно (3 шарда)" \
+            "SHA: ${{ github.sha }}" \
+            "прогон: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+            > .reuse-marker
+      - uses: actions/cache/save@v6
+        # Гонка двух прогонов с одинаковым ключом даёт «Cache already exists».
+        # Это не отказ гейта: работа выполнена, маркер уже записал сосед — job
+        # краснеть из-за этого не должна.
+        continue-on-error: true
+        with:
+          path: .reuse-marker
+          key: reuse-smoke-${{ needs.reuse.outputs.smoke_key }}
+
+  golden:
+    # Deterministic visual correctness stays in every prerelease gate: it is
+    # inexpensive and catches a different class of regressions than timings.
+    needs: [frontend, reuse]
+    if: needs.reuse.outputs.golden != 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      # Браузеры кэшируются, а apt не запускается вовсе: на GitHub-раннере
+      # системные библиотеки Chromium уже в образе, а --with-deps тратил минуты
+      # и подолгу перебирал недоступное azure-зеркало (#175, #206). Если
+      # библиотека когда-нибудь исчезнет из образа, Chromium не запустится с
+      # внятной ошибкой — тогда флаг вернуть.
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Install pinned Chromium
+        if: steps.pw.outputs.cache-hit != 'true'
+        run: npx playwright install chromium
+      - name: Build the exact source under review
+        run: npm run bundle:sync
+      - 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@v7
+        with:
+          name: golden-images
+          path: artifacts/golden
+      # Маркер пишется последним шагом: он существует только если всё выше
+      # прошло. Кэш сохраняется post-шагом, то есть тоже лишь при успехе job.
+      - name: Записать маркер успеха
+        run: |
+          printf '%s\n' "golden прогнана успешно" \
+            "SHA: ${{ github.sha }}" \
+            "прогон: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+            > .reuse-marker
+      - uses: actions/cache/save@v6
+        # Гонка двух прогонов с одинаковым ключом даёт «Cache already exists».
+        # Это не отказ гейта: работа выполнена, маркер уже записал сосед — job
+        # краснеть из-за этого не должна.
+        continue-on-error: true
+        with:
+          path: .reuse-marker
+          key: reuse-golden-${{ needs.reuse.outputs.golden_key }}
+
+  performance_smoke:
+    # Candidate-only catastrophic-regression guard for ordinary pushes and
+    # prereleases. The expensive same-runner comparison lives in performance.yml.
+    needs: [frontend, reuse]
+    if: needs.reuse.outputs.performance_smoke != 'true'
+    runs-on: ubuntu-latest
+    # 15 минут не хватало, когда установка браузера шла через apt: замер
+    # начинался на исходе окна (#206). Запас на холодный кэш — при попадании
+    # job укладывается в те же минуты, что и раньше.
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      # Браузеры кэшируются, а apt не запускается вовсе: на GitHub-раннере
+      # системные библиотеки Chromium уже в образе, а --with-deps тратил минуты
+      # и подолгу перебирал недоступное azure-зеркало (#175, #206). Если
+      # библиотека когда-нибудь исчезнет из образа, Chromium не запустится с
+      # внятной ошибкой — тогда флаг вернуть.
+      - name: Кэш браузеров Playwright
+        id: pw
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Install pinned Chromium
+        if: steps.pw.outputs.cache-hit != 'true'
+        run: npx playwright install chromium
+      - name: Build the exact candidate source
+        run: npm run bundle:sync
+      - 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@v7
+        with:
+          name: performance-smoke
+          path: artifacts/performance-smoke
+      # Маркер пишется последним шагом: он существует только если всё выше
+      # прошло. Кэш сохраняется post-шагом, то есть тоже лишь при успехе job.
+      - name: Записать маркер успеха
+        run: |
+          printf '%s\n' "performance_smoke прогнана успешно" \
+            "SHA: ${{ github.sha }}" \
+            "прогон: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+            > .reuse-marker
+      - uses: actions/cache/save@v6
+        # Гонка двух прогонов с одинаковым ключом даёт «Cache already exists».
+        # Это не отказ гейта: работа выполнена, маркер уже записал сосед — job
+        # краснеть из-за этого не должна.
+        continue-on-error: true
+        with:
+          path: .reuse-marker
+          key: reuse-performance_smoke-${{ needs.reuse.outputs.performance_smoke_key }}
+
+  backend:
+    needs: [changes, reuse]
+    if: needs.changes.outputs.backend == 'true' && needs.reuse.outputs.backend != 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # 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@v7
+        with: { node-version: 22 }
+      - uses: actions/setup-python@v7
         with: { python-version: "3.13" }
       - run: pip install pytest voluptuous pytest-homeassistant-custom-component home-assistant-frontend
       - name: Backend unit tests (pure + HA harness)
         run: python -m pytest tests_backend/ -q
+      # Маркер пишется последним шагом: он существует только если всё выше
+      # прошло. Кэш сохраняется post-шагом, то есть тоже лишь при успехе job.
+      - name: Записать маркер успеха
+        run: |
+          printf '%s\n' "backend прогнана успешно" \
+            "SHA: ${{ github.sha }}" \
+            "прогон: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+            > .reuse-marker
+      - uses: actions/cache/save@v6
+        # Гонка двух прогонов с одинаковым ключом даёт «Cache already exists».
+        # Это не отказ гейта: работа выполнена, маркер уже записал сосед — job
+        # краснеть из-за этого не должна.
+        continue-on-error: true
+        with:
+          path: .reuse-marker
+          key: reuse-backend-${{ needs.reuse.outputs.backend_key }}

.gitignore

@@ -5,3 +5,10 @@ test-build/
 __pycache__/
 .pytest_cache/
 .venv-backend/
+artifacts/
+.agents/
+
+# Копия бандла для стенда: её собирает `npm run bundle:sync`, а в репозитории
+# она только росла — 364 версии по 1.16 МБ за семь недель (#255). Обязательных
+# копий две: `dist/` (артефакт сборки) и `custom_components/` (её ставит HACS).
+demo/srv/assets/houseplan-card.js

AGENTS.md

@@ -6,22 +6,424 @@ House Plan is one HACS package with two parts plus a demo harness:
 - **Storage integration** (`custom_components/houseplan/`, Python) — the Home Assistant backend.
 - **Demo harness** (`demo/`) — a self-contained Playwright page (`demo/srv/demo.html`) that renders the card against a fake `hass`, used for screenshots and the `smoke_*.mjs` end-to-end suite.
 
-Standard commands live in `package.json` scripts, `CONTRIBUTING.md`, and `docs/DEVELOPMENT.md`. Read `docs/ARCHITECTURE.md` and `docs/STATUS.md` before non-trivial changes.
+## Read this first
 
-## Cursor Cloud specific instructions
+**`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.
 
-The startup update script already runs `npm ci`, provisions a Python 3.13 backend venv at `.venv-backend`, and installs Playwright Chromium. You do not need to reinstall dependencies.
+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.
 
-- **Frontend** (from repo root): `npm run typecheck`, `npm test` (node:test, ~270 tests), `npm run build`. After building, keep the integration copy in sync — `cp dist/houseplan-card.js custom_components/houseplan/frontend/`. CI enforces `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` byte-for-byte.
-- **Backend HA-harness tests need Python 3.13, not the system 3.12.** Run them with the venv: `.venv-backend/bin/python -m pytest tests_backend/ -q` (126 tests). Running `python3 -m pytest tests_backend` on the system 3.12 silently **skips** the `test_ha_*.py` harness tests (`conftest.py` ignores them when `homeassistant` is not importable) and runs only the ~83 pure tests.
-- **Running the app / smoke suite**: build a fresh bundle and copy it into the demo assets first — `npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` — then run `node demo/smoke_*.mjs`. The committed `demo/srv/assets/houseplan-card.js` is a stale snapshot; testing it reports green about code that no longer exists. No real Home Assistant server is required: `demo/srv/demo.html` stubs `hass`, registries and `callService`.
-- **Demo harness render quirk**: the fake `hass` in `demo.html` is set once, so opening the page directly in a browser renders the floor plan but **device icons only appear after a re-render** (an F5 refresh, or nudging `card.hass = {...card.hass}`). The smoke launcher `demo/serve.mjs` already does this nudge; a plain browser session does not. This is a harness limitation, not a card bug.
-- **Known environment-sensitive smoke**: `demo/smoke_opening_measure.mjs` fails two sub-checks (`place_dialog_x_magnetised`, `place_committed_x_center`) under the pinned Chromium — a `1e-6`-tolerance magnet-snap on the opening-*placement* path. It reproduces against the pristine committed bundle, so treat it as pre-existing/pixel-precision, not a regression you introduced.
-- **Owner's local Windows checkout is invisible here.** Path
-  `C:\Users\Sergey\Downloads\dev\houseplan-dev` (workflow notes + often
-  unpushed edits) is **not mounted** into managed Cloud Agent VMs. Do not
-  expect to `ls` or diff that folder. To bring local work into the cloud
-  agent: push a branch to GitHub and say its name, or run a **local** Cursor
-  Agent / My Machines worker inside that checkout. Day-to-day source of truth
-  for cloud sessions remains **`origin/dev`** (minors) and **`origin/main`**
-  (releases) — see `docs/STATUS.md`.
+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. Labels are the whole of it: GitHub Projects is no longer used.
+
+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/golden/baselines/**` | never changes on its own. The stand copy `demo/srv/assets/houseplan-card.js` is no longer committed (#255): build it with `npm run bundle:sync` |
+
+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.
+
+## Working trees (#115)
+
+One checkout, one `HEAD`: two agents sharing a directory inherit each other's
+branch, and twice in one hour a commit landed on someone else's task branch that
+way. The layout is therefore fixed:
+
+- **`houseplan-card-src/houseplan-card`** — the author's tree. Task branches live
+  here; nobody else commits in it. Unfamiliar local changes belong to the author
+  or the owner — never reset or clean them away.
+- **`houseplan-card-src/hp-dev`** — the owner's worktree, permanently on `dev`. For owner-side operations that must not disturb the
+  author's tree: pushing `dev`, restoring a hook's executable bit, emergencies.
+- **The reviewer and the infrastructure agent own no local tree.** The reviewer
+  runs in CI on a fresh checkout. The infrastructure agent reads via `git show`
+  and publishes through the GitHub API; it makes no local commits at all, so it
+  needs no `HEAD` of its own. Its scratch worktrees live outside the repo and are
+  pruned after use.
+
+A worktree is only usable on the machine that created it: the `.git` file records
+an absolute path in that machine's format. One created from a Linux sandbox is
+dead on Windows and vice versa — create worktrees on the machine that will use
+them, which for `hp-dev` means the owner's.
+
+## 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 → in-task | #… · Document: …
+```
+
+High blocks. A Medium finding INSIDE the task's scope is fixed within the task:
+with no High findings the verdict is yellow, the author fixes it and the fix
+passes another review cycle — no separate issue (owner's decision 2026-08-19,
+#202: filing and servicing an issue costs far more than fixing in place). Only
+a Medium finding OUTSIDE the scope becomes its own issue — foreign scope is
+never patched from this branch. 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
+npm run bundle:sync   # dist → custom_components + demo/srv/assets (#255)
+```
+
+During the implementation cycle the fast gates always run. Since 2026-08-14 the
+owner's machine also carries Playwright with Chromium (Windows) and a full WSL
+environment, which changes one thing (#151): **before moving an issue to
+`S7-code-review`, run the smokes named in its AC locally** — `node
+demo/smoke_<name>.mjs`. A red smoke that reaches the review costs a cycle; run
+locally it costs a minute. Precedent: on #89 a fixture error lived through a
+whole review round that a local run would have caught immediately.
+
+The full smoke set, `golden` and `performance_smoke` still belong to the
+pre-beta run — which is then mandatory and complete. WSL runs of the full HA
+harness (`~/houseplan-card`, venv) and `golden:verify` are advisory; **the canon
+does not move**: the beta gate is CI at the exact SHA, and baselines are accepted
+only via `npm run golden:accept -- --reviewed` on a complete Linux CI artefact.
+
+**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. Every browser check must verify it
+before trusting a result — benchmarks, golden runs and documentation captures
+call `assertFreshDemoBundle` themselves, and smokes get it from `launch()` in
+`demo/serve.mjs` (#236). A missing or mismatched fingerprint is a hard failure,
+not a warning; `HP_ALLOW_STALE_BUNDLE=1` skips the check for debugging and says
+so out loud. A smoke against a stale bundle does not fail cleanly: part of its
+assertions go red and part stay green, which reads as a logic defect.
+
+**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. Gate jobs, matching the actual
+`validate.yml` (#191): `docs`, `provenance`, `process-gate`, `hacs`, `hassfest`,
+`frontend`, `smoke`, `golden`, `performance_smoke`, `backend`. The `changes` job
+is a service path-filter, not a gate. `docs` is a real blocker: it checks the
+screenshots `sourceFingerprint` against current `src/**`, which is exactly what
+went red after the #113 merge.
+
+**"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.

CONTRIBUTING.md

@@ -16,6 +16,15 @@ 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) are the only
+active backlog. An issue owns scope and acceptance criteria; its **labels** own
+priority and workflow status — `PROCESS.md` §9 holds the vocabulary. Before
+starting planned work, link it to an existing issue or create one, and keep it
+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
@@ -25,6 +34,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
@@ -40,7 +50,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.
 

README.md

@@ -1,338 +1,157 @@
-# 🏠 House Plan — interactive floor plan card for Home Assistant
+# 🏠 House Plan — a live home map for Home Assistant
 
 [![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)
 
-**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.
+📘 **[Full user guide](docs/USER-GUIDE.md)** · 🇷🇺 **[Русский](README.ru.md)** · 🗂 **[Project issues](https://github.com/Matysh/houseplan-card/issues)**
 
-![Interactive Home Assistant floor plan: live rooms, devices, lights and climate on a real floorplan card](docs/images/demo.gif)
+<!-- docs-section: overview -->
 
-> ### 🚀 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.
+## Your whole home at a glance
 
-🇷🇺 [Документация на русском](README.ru.md) · 💬 [Telegram chat: **@ha_houseplan**](https://t.me/ha_houseplan)
+House Plan turns Home Assistant into a live map of your home. Upload a plan or
+draw rooms directly on the dashboard, bind them to Home Assistant areas, and
+the area's devices appear automatically. You can immediately see where a light
+is on, a door is open, a room is too cold, Zigbee signal is weak, or a leak
+sensor has fired.
 
-**Feature highlights**
+![Synthetic home in View mode with rooms, devices, light and climate](docs/images/01-view-desktop.png)
 
-- ♾️ **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 casts a pool
-  of its own color that spills through doorways and open zone boundaries.
-- ☀️ **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. 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.
+Setup is entirely graphical: no floor-plan YAML, Inkscape, or external editor.
+Plan data and device positions live on the Home Assistant server and stay in
+sync across screens.
 
----
+> **Edit on a desktop computer.** View and kiosk are fully supported on phones
+> and tablets. The editors are designed primarily for a mouse and keyboard;
+> individual touch editing operations may be awkward or unavailable. See the
+> exact [touch support contract](docs/TOUCH-SUPPORT.md).
 
-## What it is and why
+<!-- docs-section: features -->
 
-House Plan shows your smart home the way it actually looks — on a floor plan. Instead of long lists of entities, you see rooms and devices in their real places: where the leak is, what the temperature is in the kids' room, whether the light is on in the hallway, whether the gate is open.
+## What House Plan provides
 
-This is convenient when:
+- **Live state and safe actions.** Lights and other safe devices can toggle from
+  the plan; a lock cannot be opened by an accidental plan tap.
+- **Three built-in editors.** Plan creates rooms, walls and openings; Device
+  places and configures markers; Background adds lines, labels and furniture.
+- **Area-aware rooms.** New devices appear automatically, while room cards can
+  show temperature, humidity, light state and average LQI.
+- **Light and environment.** Room fills, lamp Glow, wall shadows, a day-cycle
+  backdrop and sunlight through windows.
+- **Doors, windows, gates and vacuums.** Openings follow real contacts and locks;
+  a robot can show its position, dock and travelled path.
+- **Several floors and screens.** Space tabs, swipe navigation, local viewport,
+  and a separate initial floor for each card.
+- **Wall-display kiosk.** A plan-only view with fullscreen navigation and icon
+  sizes saved for that display.
 
-- you have many devices and lists are awkward to use;
-- you need to grasp the state of the house "at a glance";
-- you want to give access to family members — anyone can figure out a picture;
-- you want a beautiful overview screen for a wall-mounted tablet.
+![The same synthetic home in touch View mode](docs/images/02-view-touch.png)
 
-The integration consists of two parts that are installed together:
+<!-- docs-section: first-run -->
 
-- **the Lovelace card** `houseplan-card` — the interactive plan itself;
-- **the server-side component** — stores the room markup and icon positions in Home Assistant, so the plan is identical in all browsers and on all devices.
+## Your first working room
 
----
+1. Install the integration and add the card to a dashboard.
+2. Create the first **space**: upload SVG/PNG/JPG/WebP, reuse an uploaded image,
+   or choose no image and draw the plan by hand.
+3. In Plan, select **Room outline**, place vertices, and click the first point to
+   close the outline.
+4. Name the room and bind it to a Home Assistant area. Use “No area” for a room
+   that has no devices.
+5. Open Device: devices from the bound area are already placed; drag their
+   markers to the correct positions.
+6. Optionally use Background for lines, text and furniture.
+7. Return to View. The plan now displays live state and accepts safe actions.
 
-## How it differs from alternatives
+![Creating the first space](docs/images/03-space-create.png)
 
-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:
+![Closing a room outline on its first point](docs/images/04-room-contour-close.png)
 
-| | 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 |
+![A selected partition and the Plan context tray](docs/images/05-plan-context-tray.png)
 
-**One sentence:** House Plan is the shared, area-aware live map of your home —
-not a drawing app for furniture. If you want to sketch sofas and walls from
-scratch, a draw-centric card may fit better; if you already have a plan image
-and a real HA areas registry, House Plan keeps every tablet on the same layout.
+![Device settings with binding provenance and the exact action result](docs/images/06-device-editor.png)
 
-Key advantages in short:
+![Live presentation preview for the same device](docs/images/06-device-display-preview.png)
 
-- **No code at all.** Everything — spaces, rooms, devices — is configured with clicks.
-- **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, media is playing, a vacuum is
-  cleaning, a radiator valve is actually heating (not merely enabled). 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.
-- **Crisp zoom.** Zooming in does not "blur" the picture: the plan, labels and icons remain vector-sharp at any scale.
+Every workflow and edge case is in the [full user guide](docs/USER-GUIDE.md).
+The [Background editor contract](docs/DECOR-EDITOR.md) and
+[vacuum guide](docs/VACUUM.md) are the authorities for those subsystems.
 
----
-
-## 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.
+<!-- docs-section: installation -->
 
 ## Installation
 
-One click if you already run HACS:
+### HACS
 
-[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=Matysh&repository=houseplan-card&category=integration)
+[![Open the repository in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=Matysh&repository=houseplan-card&category=integration)
 
+1. In HACS open **⋮ → Custom repositories**.
+2. Add `https://github.com/Matysh/houseplan-card` as an **Integration**.
+3. Install House Plan and restart Home Assistant.
+4. Open **Settings → Devices & services → Add integration → House Plan**.
 
-### Via HACS (recommended)
+The card is registered automatically. If you manage Lovelace resources
+manually, use the URL served by the integration:
 
-1. Open **HACS → menu (⋮) → Custom repositories**.
-2. Paste the URL of this repository, set the category to **Integration**, and click **Add**.
-3. Find **House Plan** in the list, install it and **restart Home Assistant**.
-4. Go to **Settings → Devices & Services → Add integration** and select **House Plan**.
+```yaml
+resources:
+  - url: /houseplan_files/houseplan-card.js
+    type: module
+```
 
-The card is registered automatically — no need to add a Lovelace resource manually.
+Do not use the on-disk path inside `custom_components`; Home Assistant does not
+serve that path as a JavaScript module.
 
-> **Card doesn't load (`Custom element doesn't exist: houseplan-card`) or you manage Lovelace
-> resources in YAML?** Add the resource manually pointing at the URL the integration *serves*:
->
-> ```yaml
-> resources:
->   - url: /houseplan_files/houseplan-card.js
->     type: module
-> ```
->
-> Do **not** use `/custom_components/houseplan/frontend/houseplan-card.js` — that is the file
-> on disk, which Home Assistant does not serve over HTTP (you'll get a `text/plain` MIME error
-> and the element never registers). The correct, integration-served URL is
-> `/houseplan_files/houseplan-card.js`. Both cards (`houseplan-card` and
-> `houseplan-space-card`) ship in that one file — no separate resource is needed.
+### Manual installation
 
-### Manually
+Copy `custom_components/houseplan` to `config/custom_components`, restart Home
+Assistant, and add the House Plan integration.
 
-1. Copy the `custom_components/houseplan` folder into the `config/custom_components` directory of your Home Assistant.
-2. Restart Home Assistant.
-3. Add the integration: **Settings → Devices & Services → Add integration → House Plan**.
+### Add the card
 
-### Adding a plan screen
-
-Create a new dashboard tab (a "Panel" view works best) and add the card:
+Create a dashboard view (Panel works best) and add the card in the UI or as:
 
 ```yaml
 type: custom:houseplan-card
 title: House plan
 ```
 
-Nothing else needs to be specified — everything else is configured right on the screen.
+Different screens may start on different spaces:
 
----
+```yaml
+type: custom:houseplan-card
+default_floor: ground
+```
 
-## How to use
+All cards share server-side rooms and coordinates. Current mode, viewport and
+selected space remain local to the screen. Revision checks and live sync cover
+concurrent clients, but avoid editing the same object in two browsers at once.
 
-### Step 1. Add a space (floor)
+## Detailed documentation
 
-On first open the plan is still empty — House Plan immediately offers to create the first space.
-If your Home Assistant already has **floors** configured, a wizard offers to create a space
-for each floor (names prefilled, a plan image is asked for one by one; any floor can be skipped).
+- [Full user guide](docs/USER-GUIDE.md)
+- [Mouse/touch/keyboard matrix](docs/USER-GUIDE.md#6-navigation-zoom-and-input)
+- [Plan tools](docs/USER-GUIDE.md#plan-tools-at-a-glance)
+- [Background editor](docs/DECOR-EDITOR.md)
+- [Robot vacuums](docs/VACUUM.md)
+- [Touch support](docs/TOUCH-SUPPORT.md)
 
-![Empty plan — prompt to add a space](docs/images/02-onboarding-empty.png)
+<!-- docs-section: support -->
 
-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 and can be moved and resized at any time in the Background editor.
+## Support and feedback
 
-![Space creation dialog](docs/images/03-space-dialog.png)
+- Questions and plan examples: [Telegram @ha_houseplan](https://t.me/ha_houseplan).
+- Bugs and proposals: [GitHub Issues](https://github.com/Matysh/houseplan-card/issues).
+- Before reporting, update House Plan, restart HA and hard-refresh the page.
+  Include the version, browser, logs and reproduction steps; private entity IDs
+  may be replaced with fictional ones.
 
-> 💡 You can draw the background in any floor planner (for example, REMPLANNER) or photograph a paper plan. SVG works best — it stays crisp when zoomed in.
+Documentation screenshots are produced by the reproducible
+`npm run build && node demo/docs/capture.mjs` command using synthetic data only. Scenario version,
+source fingerprint and every image hash are recorded in the
+[screenshot index](docs/images/screenshots.json).
 
-Later you can add as many spaces as you like (floors, yard, garage) with the **＋** button next to the tabs.
-
-### Step 2. Outline the rooms
-
-After the first space is added, the card switches to the **Plan** tab by itself. The card has three mode tabs in the header — **View** (default: display and device control only, nothing can be moved or edited), **Plan** (rooms, openings, labels, space settings) and **Devices** (placing and configuring markers); the edit tabs are shown to administrators. In Plan, click grid points, connecting them with lines, and close the room outline by clicking the first point.
-
-As soon as the outline is closed, the room-save dialog appears. Here you need to **bind the room to a Home Assistant area** — this is exactly what enables the automation. For utility rooms with no devices (hall, sauna) there is a **"No area"** button.
-
-![Marking up a room and saving it](docs/images/05-room-dialog.png)
-
-While drawing, a ruler follows the cursor showing the current segment's real length (metres, or feet + inches on an imperial Home Assistant). The scale is set per space — the **"Scale (grid cell size)"** field in the space dialog says how many centimetres one grid cell represents (default 5 cm).
-
-Rooms may not overlap: a click strictly inside an existing room, or an outline that would swallow one, is refused. Two more tools help you reshape the plan later:
-
-- **Merge** — click a room, then a neighbour that shares a wall; they fuse into one. A dialog picks which name and area survive.
-- **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
-
-In markup mode the **"Opening"** tool places doors and windows: 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**.
-
-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
-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.
-
-Openings are easy to adjust later: hovering one highlights it, you can **drag it along the
-walls** (it slides around corners too), and a **double click opens its properties**.
-
-### Step 3. Devices appear by themselves
-
-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: 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 **"Show hidden"**: 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.
-
-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.
-
-![Device card on click](docs/images/08-info.png)
-
-### Step 4. Zoom
-
-The mouse wheel or the **－ / ⊹ / ＋** buttons zoom the plan in and out; on a touch screen the two-finger pinch works. Zoomed out you see the whole plan, zoomed in you see the details, and everything stays crisp. The zoom level is remembered separately for each space.
-
-![Zoomed-in plan — everything stays crisp](docs/images/09-zoom.png)
-
-### Step 5. Put the icons in their places
-
-Switch to the **Devices** tab to arrange icons: drag them with the mouse, click one to open its editor. In **View** mode nothing can be moved — panning the map never displaces a sensor (a top user request). Positions are saved on the server and are identical in all browsers and devices. The **↺** button restores the automatic layout.
-
-![Dragging icons — available at all times](docs/images/06-edit.png)
-
-### 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.
-
-### Icon rules
-
-Which MDI icon a device gets is decided by **icon rules** — editable right in the card
-(the ⬡ button in the header): an ordered list of “name pattern → icon” regexes with a
-live test field, bilingual defaults (EN/RU) and a one-click reset. When no rule
-matches, the entity *device class* decides (thermometer for temperature sensors, etc.).
-
-### Step 6. Adding your own devices manually
-
-You can also place a **single entity** (not just a whole device): start typing in the binding search and individual entities appear next to devices — handy when one device exposes several values (e.g. temperature and humidity) and you want each as its own icon.
-
-
-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**.
-
-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
-**icon size** (×0.5–3) and **rotation** are also per-device, so a wall valve can be small and
-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
-
-1. Remove the card (or the tab with the plan) from the dashboard.
-2. **Settings → Devices & Services → House Plan → Delete** the integration entry.
-3. Remove the integration from **HACS** (or delete the `custom_components/houseplan` folder if installed manually) and restart Home Assistant.
-4. Optionally delete the saved plan data: the `config/houseplan/` files (backgrounds and attachments) and the `houseplan.config` / `houseplan.layout` entries in the `config/.storage` directory.
-
----
-
-## 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 (the "Hide device from plan" checkbox — set automatically for bridges, scenes and other non-physical records) — open the device editor, press **"Show hidden"** and untick the box in its dialog.
-
-**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.
-
-**Is the data stored in the cloud?** No. Everything is stored locally in your Home Assistant.
-
----
-
-<p align="center"><sub>Screenshots were taken on a real Home Assistant configuration.</sub></p>
+License: [MIT](LICENSE).

README.ru.md

@@ -1,340 +1,161 @@
-# 🏠 House Plan — интерактивный поэтажный план дома для Home Assistant
+# 🏠 House Plan — живой план дома для Home Assistant
 
 [![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)
 [![Live demo](https://img.shields.io/badge/демо-попробовать-00c853?logo=homeassistant&logoColor=white)](https://demo.houseplan.tech)
 [![Telegram chat](https://img.shields.io/badge/Telegram-чат-2CA5E0?logo=telegram&logoColor=white)](https://t.me/ha_houseplan)
 
-📘 **[Полное руководство пользователя](docs/USER-GUIDE.ru.md)** · **[Продуктовый аудит и план улучшений](docs/PRODUCT-IMPROVEMENT-PLAN.ru.md)**
+📘 **[Полное руководство](docs/USER-GUIDE.ru.md)** · 🇬🇧 **[English](README.md)** · 🗂 **[Задачи проекта](https://github.com/Matysh/houseplan-card/issues)**
 
-**Превратите Home Assistant в живую интерактивную карту дома.** Загрузите или
-нарисуйте план этажа, обведите комнаты мышкой — и умные устройства появятся на
-своих местах: живые состояния, свет по клику, температура и влажность по
-комнатам, карта Zigbee-сигнала, светящиеся пятна ламп и полноэкранный
-киоск-режим для настенного планшета. Без YAML, без Inkscape и внешних
-редакторов — весь план настраивается прямо на дашборде.
+<!-- docs-section: overview -->
 
-![Интерактивный план дома для Home Assistant: комнаты, устройства, свет и климат на реальном поэтажном плане](docs/images/demo.gif)
+## Дом целиком — одним взглядом
 
-> ### 🚀 Попробовать вживую — без установки
-> **[demo.houseplan.tech](https://demo.houseplan.tech)** — настоящий Home
-> Assistant с готовым планом. Вход **`demo`** / **`demo`**, можно нажимать всё:
-> включать свет, открывать редакторы, ломать что угодно. Каждый час стенд сам
-> возвращается в исходное состояние.
+House Plan превращает Home Assistant в живую карту дома. Загрузите изображение
+плана или нарисуйте комнаты прямо на дашборде, свяжите их с зонами Home
+Assistant — и устройства появятся на плане автоматически. Сразу видно, где
+горит свет, открыта дверь, слишком холодно, слабый Zigbee-сигнал или сработал
+датчик протечки.
 
-🇬🇧 [Documentation in English](README.md) · 💬 [Чат в Telegram: **@ha_houseplan**](https://t.me/ha_houseplan)
+![Синтетический дом в режиме просмотра: комнаты, устройства, свет и климат](docs/images/01-view-desktop.png)
 
-**Главное**
+Настройка выполняется в графическом интерфейсе: без YAML-разметки, Inkscape и
+внешнего редактора плана. Данные плана и расположение устройств хранятся на
+сервере Home Assistant и синхронизируются между экранами.
 
-- ♾️ **Бесконечный холст** — нет «размера плана» и нет края, за который
-  нельзя выйти: рисуйте и ставьте устройства где угодно, тащите план на
-  любом зуме, отдаляйтесь, чтобы увидеть всё, и одной кнопкой вписывайте
-  план обратно в экран.
-- 🖱 **Редакторы прямо в карточке** — комнаты, двери и окна, комнаты-острова,
-  виртуальные стены и декор-слой рисуются кликами; размеры комнат меняются
-  перетаскиванием стен с живыми длинами и площадями; помощник выравнивания и
-  линейка в реальных метрах.
-- 💡 **Свет переключается кликом** из коробки; значок выключателя может
-  управлять группой ламп (в т.ч. «тупые» выключатели и кнопки-пульты).
-- 🌒 **Заливка «Свет по источникам»** — тёмный дом, где каждая горящая лампа
-  даёт пятно своего цвета, проникающее через дверные проёмы и открытые зоны.
-- ☀️ **Солнце на плане** — задайте компас, и фон живёт вместе с днём
-  (белый полдень → золотой час → глубокая ночь), а окна внешних стен пускают
-  в комнаты настоящие клинья солнечного света; облачность — опционально, от
-  weather-сущности.
-- 🪟 **Шторы открываются тапом** — одно действие открывает, закрывает или
-  останавливает штору, а сам значок морфится между открытым и закрытым
-  видом и мягко пульсирует кольцом, пока штора едет.
-- 🌡 **Карточки комнат**: температура, влажность, Zigbee-сигнал, свет «1 из 3»;
-  температурная заливка по комфортным границам.
-- 🚪 **Двери, окна и замки** с датчиками — отпирание только явной кнопкой,
-  никогда случайным тапом.
-- 📺 **Киоск-режим** для настенных планшетов и ТВ: полноэкранно, свайп между
-  этажами, автокарусель, свои размеры на каждом экране.
-- 🤖 **Роботы-пылесосы вживую** — маркер-база стоит на месте, а круглая
-  шайба ездит по плану в реальном времени, «выливая» путь из-под себя;
-  текущая и прошлая уборки хранятся на сервере. Калибровка — в один клик
-  (по именам комнат) или перетаскиванием призрака карты. Работают Xiaomi
-  Cloud Map Extractor, dreame-vacuum (Tasshack) и Valetudo.
-- 🔔 Новые устройства сами появляются на плане с красной точкой; раскладка
-  хранится **на сервере HA** — один план для всех экранов, живая синхронизация.
+> **Редактируйте на компьютере.** Режим просмотра и киоск полноценно работают
+> на телефонах и планшетах. Редакторы рассчитаны прежде всего на мышь и
+> клавиатуру; на touch отдельные операции могут быть неудобны или недоступны.
+> Подробный контракт: [поддержка touch](docs/TOUCH-SUPPORT.md).
 
----
+<!-- docs-section: features -->
 
+## Что умеет House Plan
 
-## Что это и зачем
+- **Живые состояния и безопасные действия.** Свет и другие безопасные устройства
+  переключаются с плана; замок нельзя открыть случайным нажатием.
+- **Три встроенных редактора.** «План» создаёт комнаты, стены и проёмы;
+  «Устройства» размещает и настраивает маркеры; «Подложка» добавляет линии,
+  подписи и мебель.
+- **Комнаты, связанные с зонами HA.** Новые устройства появляются автоматически,
+  а карточки комнат показывают температуру, влажность, свет и средний LQI.
+- **Свет и окружение.** Заливки комнат, Glow от ламп, тени от стен, дневной фон и
+  солнечные лучи из окон.
+- **Двери, окна, ворота и пылесосы.** Проёмы отражают реальные датчики и замки;
+  робот показывает позицию, базу и пройденный путь.
+- **Несколько этажей и экранов.** Вкладки пространств, жесты переключения,
+  локальный масштаб и отдельный стартовый этаж для каждой карточки.
+- **Киоск для настенного экрана.** Только план, полноэкранная навигация и размеры
+  значков, сохранённые отдельно для этого устройства.
 
-House Plan показывает ваш умный дом так, как он выглядит на самом деле — на плане этажей. Вместо длинных списков сущностей вы видите комнаты и устройства на своих местах: где протечка, какая температура в детской, включён ли свет в прихожей, открыты ли ворота.
+![Тот же синтетический дом в touch-режиме просмотра](docs/images/02-view-touch.png)
 
-Это удобно, когда:
+<!-- docs-section: first-run -->
 
-- устройств много, и списками пользоваться неудобно;
-- нужно быстро понять состояние дома «одним взглядом»;
-- хочется отдать доступ близким — по картинке разберётся любой;
-- вы хотите красивый обзорный экран для настенного планшета.
+## Первая рабочая комната
 
-Интеграция состоит из двух частей, которые ставятся вместе:
+1. Установите интеграцию и добавьте карточку на дашборд.
+2. Создайте первое **пространство**: загрузите SVG/PNG/JPG/WebP либо выберите
+   вариант без изображения, чтобы нарисовать план вручную.
+3. В редакторе «План» выберите **Контур комнаты**, поставьте вершины и замкните
+   контур нажатием на первую точку.
+4. Назовите комнату и свяжите её с зоной Home Assistant. Для помещения без
+   устройств выберите «Без зоны».
+5. Откройте «Устройства»: устройства связанной зоны уже размещены автоматически;
+   перетащите маркеры в нужные места.
+6. При необходимости оформите подложку линиями, текстом и мебелью.
+7. Вернитесь в «Просмотр» — теперь план показывает живые состояния и принимает
+   безопасные действия.
 
-- **карточка Lovelace** `houseplan-card` — сам интерактивный план;
-- **серверный компонент** — хранит разметку комнат и позиции иконок в Home Assistant, поэтому план одинаков во всех браузерах и на всех устройствах.
+![Создание первого пространства](docs/images/03-space-create.png)
 
----
+![Замыкание контура комнаты на первой точке](docs/images/04-room-contour-close.png)
 
-## Чем отличается от аналогов
+![Выбранная перегородка и контекстная панель редактора плана](docs/images/05-plan-context-tray.png)
 
-Обычно план дома в Home Assistant делают через `picture-elements`, `ha-floorplan`
-или новые GUI-карточки, где стены и мебель рисуют прямо на дашборде. Там либо
-YAML/SVG, либо конфиг живёт в YAML карточки. House Plan — это **общий живой
-план** на серверной интеграции Home Assistant:
+![Настройка устройства с источником привязки и точным результатом действия](docs/images/06-device-editor.png)
 
-| | 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 / виртуальный холст |
+![Живой предпросмотр отображения того же устройства](docs/images/06-device-display-preview.png)
 
-**Одной фразой:** House Plan — это общая, area-aware живая карта дома, а не
-редактор мебели. Если нужно с нуля нарисовать диваны и стены — лучше
-draw-карточка; если есть картинка плана и зоны в HA — House Plan держит один
-и тот же layout на всех планшетах.
+Пошаговые сценарии, все инструменты и особые случаи описаны в
+[полном руководстве](docs/USER-GUIDE.ru.md). Возможности подложки отдельно
+зафиксированы в [документе редактора](docs/DECOR-EDITOR.md), а роботов — в
+[руководстве по пылесосам](docs/VACUUM.md).
 
-Ключевые преимущества коротко:
-
-- **Никакого кода.** Всё — пространства, комнаты, устройства — настраивается кликами.
-- **Автоматическое добавление устройств.** Обвели комнату и привязали её к зоне Home Assistant — устройства этой зоны сами появляются на плане.
-- **Ручное добавление своих.** Любое устройство, группу или даже «виртуальную» точку можно поставить на план вручную, задать имя, иконку, модель, ссылку и приложить PDF-инструкцию.
-- **Живые состояния.** Температура, уровень сигнала Zigbee, вкл/выкл, открыто/закрыто — всё обновляется в реальном времени.
-  Цвета значков подчиняются одному принципу — **жёлтый значит «устройство прямо сейчас выполняет свою основную работу»**:
-  лампа светит, розетка подаёт, вентилятор крутится, медиа играет, пылесос убирает, термоголовка
-  реально греет (а не просто включена). Оранжевый = открыто / не заперто. Пульсирующее красное
-  кольцо = авария (протечка, дым, газ). Цвет RGB-лампы живёт в её пятне света (режим glow),
-  где само пятно — индикатор включения, а подложка значка остаётся стандартной.
-  Полупрозрачный значок = недоступно. Тёмный = покой.
-- **Подложку можно двигать и масштабировать.** Картинка плана не прибита к холсту: в редакторе подложки её тянут за тело и за угол, а плашка показывает реальный размер в метрах — чертёж и фотография плана наконец совмещаются.
-- **Чёткий зум.** Приближение не «мылит» картинку: план, подписи и иконки остаются векторно-чёткими на любом масштабе.
-
----
-
-## Настенный планшет / ТВ (киоск-режим)
-
-Отдельный дашборд с 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).
+<!-- docs-section: installation -->
 
 ## Установка
 
-В один клик, если у вас уже есть HACS:
+### Через HACS
 
-[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=Matysh&repository=houseplan-card&category=integration)
+[![Открыть репозиторий в HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=Matysh&repository=houseplan-card&category=integration)
 
+1. В HACS откройте **⋮ → Пользовательские репозитории**.
+2. Добавьте `https://github.com/Matysh/houseplan-card` с типом **Интеграция**.
+3. Установите House Plan и перезапустите Home Assistant.
+4. Откройте **Настройки → Устройства и службы → Добавить интеграцию → House Plan**.
 
-### Через HACS (рекомендуется)
+Карточка регистрируется автоматически. Если ресурсы Lovelace управляются вручную,
+добавьте именно URL, который публикует интеграция:
 
-1. Откройте **HACS → меню (⋮) → Custom repositories**.
-2. Вставьте URL этого репозитория, категория — **Integration**, и нажмите **Add**.
-3. Найдите в списке **House Plan**, установите и **перезапустите Home Assistant**.
-4. Перейдите в **Настройки → Устройства и службы → Добавить интеграцию** и выберите **House Plan**.
+```yaml
+resources:
+  - url: /houseplan_files/houseplan-card.js
+    type: module
+```
 
-Карточка подключается автоматически — добавлять ресурс Lovelace вручную не нужно.
-
-> **Карточка не грузится (`Custom element doesn't exist: houseplan-card`) или вы ведёте ресурсы
-> Lovelace в YAML?** Добавьте ресурс вручную, указав URL, который *раздаёт сама интеграция*:
->
-> ```yaml
-> resources:
->   - url: /houseplan_files/houseplan-card.js
->     type: module
-> ```
->
-> **Не** используйте `/custom_components/houseplan/frontend/houseplan-card.js` — это путь к файлу
-> на диске, который Home Assistant не отдаёт по HTTP (получите ошибку MIME `text/plain`, и элемент
-> не зарегистрируется). Правильный URL, который раздаёт интеграция, — `/houseplan_files/houseplan-card.js`.
-> Обе карточки (`houseplan-card` и `houseplan-space-card`) лежат в этом одном файле — отдельный ресурс
-> не нужен.
+Не используйте путь к файлу внутри `custom_components`: Home Assistant не
+публикует его как JavaScript-модуль.
 
 ### Вручную
 
-1. Скопируйте папку `custom_components/houseplan` в каталог `config/custom_components` вашего Home Assistant.
-2. Перезапустите Home Assistant.
-3. Добавьте интеграцию: **Настройки → Устройства и службы → Добавить интеграцию → House Plan**.
+Скопируйте `custom_components/houseplan` в `config/custom_components`,
+перезапустите Home Assistant и добавьте интеграцию House Plan.
 
-### Добавление экрана с планом
+### Добавление карточки
 
-Создайте новую вкладку дашборда (удобнее всего — в режиме «Панель»/Panel) и добавьте карточку:
+Создайте представление дашборда (лучше Panel) и добавьте карточку через UI либо:
 
 ```yaml
 type: custom:houseplan-card
 title: План дома
 ```
 
-Больше ничего указывать не нужно — всё остальное настраивается прямо на экране.
+Для нескольких экранов можно задать разные стартовые пространства:
 
----
+```yaml
+type: custom:houseplan-card
+default_floor: ground
+```
 
-## Как пользоваться
+Все карточки используют общие серверные комнаты и координаты. Текущий режим,
+масштаб и выбранное пространство локальны для экрана. Одновременное
+редактирование поддерживает синхронизацию и проверку ревизий, но один объект
+лучше не менять параллельно в двух браузерах.
 
-### Шаг 1. Добавьте пространство (этаж)
+## Где искать подробности
 
-При первом открытии план ещё пуст — House Plan сразу предложит создать первое пространство.
+- [Полное руководство пользователя](docs/USER-GUIDE.ru.md)
+- [Матрица mouse/touch/keyboard](docs/USER-GUIDE.ru.md#6-навигация-масштаб-и-жесты)
+- [Инструменты плана](docs/USER-GUIDE.ru.md#инструменты-плана-в-короткой-таблице)
+- [Редактор подложки](docs/DECOR-EDITOR.md)
+- [Роботы-пылесосы](docs/VACUUM.md)
+- [Поддержка touch](docs/TOUCH-SUPPORT.md)
 
-Если в вашем Home Assistant уже настроены **этажи**, мастер предложит создать
-пространство для каждого: названия подставятся сами, план попросит по очереди,
-любой этаж можно пропустить.
+<!-- docs-section: support -->
 
-![Пустой план — предложение добавить пространство](docs/images/02-onboarding-empty.png)
+## Помощь и обратная связь
 
-В диалоге задайте **название** (например, «1 этаж») и выберите подложку: **загрузите** картинку плана (SVG, PNG, JPG, WebP), **возьмите уже загруженную** на сервер ранее или отметьте **«без подложки, нарисую комнаты сам»**. Холст бесконечный; картинка сохраняет свои пропорции, а подвинуть и отмасштабировать её можно в любой момент в редакторе подложки.
+- Вопросы и примеры планов: [Telegram @ha_houseplan](https://t.me/ha_houseplan).
+- Баги и предложения: [GitHub Issues](https://github.com/Matysh/houseplan-card/issues).
+- Перед отчётом обновите House Plan, перезапустите HA и выполните жёсткое
+  обновление страницы (`Ctrl+F5`). Приложите версию, браузер, логи и шаги
+  воспроизведения; приватные entity ID можно заменить вымышленными.
 
-![Диалог создания пространства](docs/images/03-space-dialog.png)
+Скриншоты в документации получены воспроизводимой командой
+`npm run build && node demo/docs/capture.mjs` только на синтетических данных. Версия сценариев,
+fingerprint исходников и хеш каждого изображения находятся в
+[индексе снимков](docs/images/screenshots.json).
 
-> 💡 Подложку можно нарисовать в любом планировщике (например, РЕМПЛАННЕР) или сфотографировать бумажный план. Лучше всего SVG — он остаётся чётким при увеличении.
-
-Позже можно добавить сколько угодно пространств (этажи, двор, гараж) кнопкой **＋** рядом со вкладками.
-
-### Шаг 2. Обведите комнаты
-
-После добавления первого пространства карточка сама переходит в режим разметки. Кликайте по точкам сетки, соединяя их линиями, и замкните контур комнаты кликом по первой точке.
-
-Как только контур замкнётся, появится окно сохранения комнаты. Здесь нужно **привязать комнату к зоне Home Assistant** — именно это включает автоматику. Для служебных помещений без устройств (холл, сауна) есть кнопка **«Без зоны»**.
-
-![Разметка комнаты и её сохранение](docs/images/05-room-dialog.png)
-
-Во время рисования у курсора показывается линейка с реальной длиной текущего отрезка (метры или футы+дюймы на имперской системе HA). Масштаб задаётся для каждого пространства — поле **«Масштаб (размер ячейки сетки)»** в диалоге пространства: сколько сантиметров в одной ячейке (по умолчанию 5 см).
-
-Комнаты не могут пересекаться: клик строго внутри существующей комнаты или контур, охватывающий её, отклоняются. Ещё два инструмента помогают перекроить план позже:
-
-- **Объединить** — кликните комнату, затем соседнюю с общей стеной; они сольются в одну. Диалог выбирает, чьё имя и зона останутся.
-- **Разделить** — кликните комнату, затем две точки на её стенах; хорда разрежет её надвое. Бо́льшая часть остаётся прежней комнатой (имя, зона, устройства), меньшая просит новое имя и зону.
-
-
-### Двери, окна и замки
-
-В режиме разметки инструмент **«Проём»** ставит двери и окна: кликните рядом со стеной — проём
-примагнитится к ней. Выберите тип, **длину в реальных сантиметрах** (по умолчанию дверь 90 см,
-окно 120 см), датчик открытия и — для двери — **замок**.
-
-С привязанным датчиком план оживает: створка двери поворачивается на петле, и дуга распахивания
-дорисовывается по мере открытия настоящей двери; окно раскрывает две створки. Пока открыто,
-подвижные части подсвечены акцентным цветом. У двери с замком рядом отображается замочек —
-зелёный, когда заперто, оранжевый, когда нет. Ради безопасности замок с плана **нельзя**
-переключить — клик по проёму показывает карточку с обоими статусами.
-
-Проёмы легко поправить позже: при наведении проём подсвечивается, его можно **перетащить вдоль
-стен** (в том числе за угол), а **двойной клик открывает свойства**.
-
-### Шаг 3. Устройства появляются сами
-
-Как только вы сохранили комнату с привязкой к зоне, **устройства этой зоны автоматически расставляются внутри контура**. Берутся те же устройства, что показаны на странице **Настройки → Устройства → (фильтр по нужной комнате)** — только осмысленные, без служебных записей, мостов и дубликатов.
-
-По умолчанию на план попадают только осмысленные устройства: нефизические (служебные записи, мосты, сцены, лампы, свёрнутые в световую группу) могут быть скрыты автоматически. Управление находится в левом нижнем углу диалога устройства: **«Скрыть»** убирает маркер после сохранения, а у уже скрытого маркера там же появляется **«Показать»**. Чтобы найти скрытые устройства, откройте редактор устройств и нажмите **«Показать скрытые»**: они отобразятся полупрозрачными синими призраками, клик открывает диалог. Скрытые устройства учитываются в Zigbee-сигнале комнаты, но света не дают.
-
-Дальше можно просто пользоваться планом: клик по иконке открывает карточку устройства с моделью, ссылкой и кнопкой перехода в Home Assistant.
-
-![Карточка устройства по клику](docs/images/08-info.png)
-
-### Шаг 4. Масштаб
-
-Колесо мыши или кнопки **－ / ⊹ / ＋** приближают и отдаляют план; на сенсорном экране работает «щипок» двумя пальцами. При отдалении виден весь план целиком, при приближении — детали, и всё остаётся чётким. Масштаб запоминается отдельно для каждого пространства.
-
-![Приближённый план — всё остаётся чётким](docs/images/09-zoom.png)
-
-### Шаг 5. Расставьте значки по местам
-
-Расставлять значки нужно на вкладке **«Устройства»**: там они перетаскиваются мышью, а клик открывает редактор. В режиме **«Просмотр»** ничего сдвинуть нельзя — панорамирование карты больше не сдвигает датчики (главная просьба пользователей). Позиции сохраняются на сервере и одинаковы во всех браузерах и устройствах. Кнопка **↺** возвращает автоматическую раскладку.
-
-![Перетаскивание значков — доступно всегда](docs/images/06-edit.png)
-
-### Управление с плана (tap actions)
-
-По умолчанию тап по значку открывает инфо-карточку. В настройках карточки можно
-переключить **«Тап по устройству»** на *Переключить* — тогда тап включает/выключает
-свет, розетки, вентиляторы и увлажнители прямо с плана (режим настенного планшета).
-Для безопасности общий toggle не действует на замки, сигнализации, шторы/ворота и
-клапаны; для конкретного устройства toggle можно включить осознанно в его диалоге
-(кроме замков и сигнализаций — они с плана не переключаются никогда). **Долгое
-нажатие** всегда открывает инфо-карточку.
-
-### Правила иконок
-
-Какая MDI-иконка достанется устройству, решают **правила иконок** — редактируются
-прямо в карточке (кнопка ⬡ в шапке): упорядоченный список «шаблон имени → иконка»
-с живым тест-полем, двуязычные умолчания (EN/RU) и сброс одной кнопкой. Если ни одно
-правило не подошло — решает *device class* сущности (термометр для датчиков
-температуры и т.п.).
-
-### Шаг 6. Добавление своих устройств вручную
-
-Можно поставить и **отдельную сущность** (не только устройство целиком): начните печатать в поиске привязки — рядом с устройствами появятся отдельные сущности. Удобно, когда одно устройство отдаёт несколько значений (например, температуру и влажность), а вы хотите каждое своей иконкой.
-
-
-Не всё нужно оставлять на автоматику. Кнопкой **＋** в шапке можно поставить на план любое устройство, группу или **виртуальную точку** (например, «Вентиль на вводе», которого нет как устройства). Задайте имя, иконку, модель, ссылку, описание и при желании приложите **PDF-инструкцию**.
-
-В этом же диалоге настраивается вид устройства на плане. **Отображение** переключает значок,
-анимированную **пульсацию присутствия** (расходящиеся кольца, пока сущность активна, и тусклая
-точка в покое — идеально для датчиков движения) или то и другое сразу, с цветом и размером колец
-на устройство. **Размер значка** (×0,5–3) и **поворот** — тоже индивидуальные: вентиль на стене
-может быть маленьким и повёрнутым так, как он установлен.
-
-![Добавление устройства вручную](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)**.
-
----
-
-## Удаление
-
-1. Уберите карточку (или вкладку с планом) из дашборда.
-2. **Настройки → Устройства и службы → House Plan → Удалить** запись интеграции.
-3. Удалите интеграцию из **HACS** (или папку `custom_components/houseplan` при ручной установке) и перезапустите Home Assistant.
-4. При желании удалите сохранённые данные плана: файлы `config/houseplan/` (подложки и вложения) и записи `houseplan.config` / `houseplan.layout` в каталоге `config/.storage`.
-
----
-
-## Помощь и обмен опытом
-
-- 💬 **[Чат в 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.
-
----
-
-<p align="center"><sub>Скриншоты сделаны на реальной конфигурации Home Assistant.</sub></p>
+Лицензия: [MIT](LICENSE).

custom_components/houseplan/__init__.py

@@ -1,6 +1,7 @@
 """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
@@ -23,7 +24,12 @@ from .const import (
 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__)
 
@@ -32,22 +38,37 @@ 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 HouseplanContentView, 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
@@ -126,10 +147,6 @@ async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) ->
         cfg = stored.get("config")
         lay_stored = await data.store.async_load() or {}
         layout = lay_stored.get("layout") or {}
-        lay_meta = {
-            k: v for k, v in lay_stored.items()
-            if k not in ("layout", "rev", "geom_pending")
-        }
         pending = {
             str(k): v for k, v in (lay_stored.get("geom_pending") or {}).items()
         }
@@ -137,15 +154,18 @@ async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) ->
         if merged:
             lay_rev = int(lay_stored.get("rev", 0))
             if merged != pending:  # 1. the durable intent, before anything moves
-                await data.store.async_save(
-                    {**lay_meta, "layout": layout, "rev": lay_rev, "geom_pending": merged}
+                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 data.config_store.async_save({"config": cfg, "rev": rev})
+                await async_save_config_state(data, cfg, rev, previous_rev=rev - 1)
             migrate_layout(layout, merged)  # 3. the layout half + intent cleared
-            await data.store.async_save({**lay_meta, "layout": layout, "rev": lay_rev + 1})
+            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)
             )
@@ -157,6 +177,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) ->
     # 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 {}
@@ -167,30 +188,60 @@ async def async_setup_entry(hass: HomeAssistant, entry: HouseplanConfigEntry) ->
             target_layout = pending["layout"]
             config_rev = int(stored.get("rev", 0))
             layout_rev = int(lay_stored.get("rev", 0))
-            if stored.get("config") != target_config:
-                config_rev += 1
-                await data.config_store.async_save({
-                    "config": target_config,
-                    "rev": config_rev,
-                })
-            if lay_stored.get("layout", {}) != target_layout:
-                layout_rev += 1
-            layout_meta = {
-                k: v for k, v in lay_stored.items()
-                if k not in ("layout", "rev", "optimize_pending", "optimize_backup")
-            }
-            if not pending.get("clear_backup") and "optimize_backup" in lay_stored:
-                layout_meta["optimize_backup"] = lay_stored["optimize_backup"]
-            await data.store.async_save({
-                **layout_meta,
-                "layout": target_layout,
-                "rev": layout_rev,
-            })
+            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)
-            _LOGGER.warning("House Plan: completed an interrupted plan optimization")
+            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)
 

custom_components/houseplan/const.py

@@ -3,8 +3,9 @@
 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
+STORAGE_MINOR_VERSION = 2
 FRONTEND_URL = "/houseplan_files/houseplan-card.js"
 PLANS_URL = "/houseplan_files/plans"
 PLANS_DIR = "houseplan/plans"  # relative to the HA configuration directory
@@ -45,10 +46,24 @@ PLAN_ORPHAN_TTL_S = 3600
 SCHEDULED_GRACE_S = 30 * 24 * 3600
 FILES_DIR = "houseplan/files"
 CONF_ADMIN_ONLY = "admin_only"
-VERSION = "1.59.0"
+VERSION = "1.67.0-rc.3"
+
+# 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 = 7
+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": [],
     "markers": [],
-    "settings": {},
+    "settings": {"bg_mode": "daynight"},
 }

custom_components/houseplan/coordinate_canonicalization.py

@@ -0,0 +1,176 @@
+"""Lossless, allow-listed canonicalisation of persisted geometry.
+
+The frontend mirrors this module in src/coordinate-canonicalization.ts.
+Keep the precision, lattice formula and field allow-list in lockstep; a shared
+fixture is exercised by both runtimes.
+"""
+from __future__ import annotations
+
+import copy
+import math
+from typing import Any
+
+
+COORDINATE_DECIMALS = 9
+COORDINATE_FACTOR = 10**COORDINATE_DECIMALS
+LATTICE_GRID_N = 240
+LATTICE_NOISE_STEPS = 1e-4
+
+
+def canonicalize_number(value: Any) -> Any:
+    """Return one stable IEEE-754 representation for an allow-listed scalar."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return value
+    number = float(value)
+    if not math.isfinite(number):
+        return value
+    sign = -1.0 if math.copysign(1.0, number) < 0 else 1.0
+    result = sign * (
+        math.floor(abs(number) * COORDINATE_FACTOR + 0.5)
+        / COORDINATE_FACTOR
+    )
+    if result == 0:
+        return 0.0
+    return result
+
+
+def canonicalize_lattice_coordinate(value: Any) -> Any:
+    """Collapse near-node noise while preserving authored off-grid values."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return value
+    number = float(value)
+    if not math.isfinite(number):
+        return value
+    scaled = number * LATTICE_GRID_N
+    # JavaScript Math.round: ties go toward +infinity, unlike Python round().
+    nearest = math.floor(scaled + 0.5)
+    if abs(scaled - nearest) < LATTICE_NOISE_STEPS:
+        result = nearest / LATTICE_GRID_N
+        return 0.0 if result == 0 else result
+    return canonicalize_number(number)
+
+
+def _record(value: Any) -> dict[str, Any] | None:
+    return value if isinstance(value, dict) else None
+
+
+def _records(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, dict)]
+
+
+def _scalar_fields(record: dict[str, Any], names: tuple[str, ...]) -> None:
+    for name in names:
+        if name in record:
+            record[name] = canonicalize_number(record[name])
+
+
+def _lattice_fields(record: dict[str, Any], names: tuple[str, ...]) -> None:
+    for name in names:
+        if name in record:
+            record[name] = canonicalize_lattice_coordinate(record[name])
+
+
+def _lattice_point(value: Any) -> None:
+    if not isinstance(value, list):
+        return
+    for index in range(min(2, len(value))):
+        value[index] = canonicalize_lattice_coordinate(value[index])
+
+
+def _lattice_points(value: Any) -> None:
+    if not isinstance(value, list):
+        return
+    for point in value:
+        _lattice_point(point)
+
+
+def canonicalize_position(position: Any) -> Any:
+    """Canonicalise lattice x/y in one layout record, preserving metadata."""
+    result = copy.deepcopy(position)
+    record = _record(result)
+    if record is not None:
+        _lattice_fields(record, ("x", "y"))
+    return result
+
+
+def canonicalize_layout_geometry(layout: Any) -> Any:
+    """Canonicalise lattice x/y in every layout record."""
+    result = copy.deepcopy(layout)
+    record = _record(result)
+    if record is None:
+        return result
+    for position in record.values():
+        item = _record(position)
+        if item is not None:
+            _lattice_fields(item, ("x", "y"))
+    return result
+
+
+def canonicalize_config_geometry(config: Any) -> Any:
+    """Canonicalise only the named persisted geometry fields."""
+    result = copy.deepcopy(config)
+    root = _record(result)
+    if root is None:
+        return result
+
+    for space in _records(root.get("spaces")):
+        _scalar_fields(
+            space,
+            (
+                "plan_x",
+                "plan_y",
+                "plan_scale",
+                "plan_scale_x",
+                "plan_scale_y",
+                "plan_angle",
+            ),
+        )
+
+        for room in _records(space.get("rooms")):
+            _lattice_fields(room, ("x", "y", "w", "h"))
+            _lattice_points(room.get("poly"))
+
+        for wall in _records(space.get("walls")):
+            _lattice_point(wall.get("a"))
+            _lattice_point(wall.get("b"))
+
+        for opening in _records(space.get("openings")):
+            _lattice_fields(opening, ("x", "y"))
+            _scalar_fields(opening, ("angle", "length"))
+            host = _record(opening.get("host"))
+            if host is not None:
+                _scalar_fields(host, ("t",))
+
+        for decor in _records(space.get("decor")):
+            kind = decor.get("kind")
+            if kind == "line":
+                _lattice_fields(decor, ("x1", "y1", "x2", "y2"))
+            elif kind in ("rect", "ellipse", "furniture"):
+                _lattice_fields(decor, ("x", "y", "w", "h"))
+                _scalar_fields(decor, ("angle",))
+            elif kind == "text":
+                _lattice_fields(decor, ("x", "y"))
+                _scalar_fields(decor, ("scale", "angle"))
+
+        for draft in _records(space.get("room_drafts")):
+            _lattice_points(draft.get("points"))
+
+        for partition in _records(space.get("partitions")):
+            _lattice_point(partition.get("a"))
+            _lattice_point(partition.get("b"))
+
+        for column in _records(space.get("wall_columns")):
+            _lattice_point(column.get("center"))
+            if column.get("shape") == "square":
+                _scalar_fields(column, ("angle",))
+
+        for span in _records(space.get("open_spans")):
+            _lattice_point(span.get("a"))
+            _lattice_point(span.get("b"))
+
+    for marker in _records(root.get("markers")):
+        _scalar_fields(marker, ("angle",))
+
+    return result

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

@@ -64,6 +64,16 @@ def migrate_space(space: dict[str, Any]) -> bool:
         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

custom_components/houseplan/http_api.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import logging
 import os
 import tempfile
+from functools import partial
 from pathlib import Path
 
 from aiohttp import web
@@ -22,10 +23,13 @@ from homeassistant.core import HomeAssistant
 
 from .const import (
     CONF_ADMIN_ONLY, CONTENT_URL, FILES_DIR, FILES_URL, MAX_FILES_BYTES,
-    MAX_FILES_COUNT, PLANS_DIR,
+    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,
@@ -52,6 +56,69 @@ _MIME = {
 }
 
 
+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).
 

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.59.0"
+  "version": "1.67.0-rc.3"
 }

custom_components/houseplan/projection.py

@@ -0,0 +1,95 @@
+"""Read-only projections of the stored plan (#256).
+
+A full configuration is 70 KB on a real installation: three spaces and 139
+markers. Every diagnostic question — "which space does this marker point at",
+"how many markers are hidden", "what is on the first floor" — used to require
+downloading all of it, because `houseplan/config/get` had no way to ask for
+less.
+
+The functions here are pure and deliberately unaware of Home Assistant: the
+websocket handlers stay thin, and the interesting part is covered by tests that
+run without the HA harness.
+
+Two rules shape everything below.
+
+* Absent parameter means *no projection*. The response must stay byte-for-byte
+  what it was before this module existed; no existing client may notice it.
+* A projection never invents or repairs data. An unknown field name simply adds
+  nothing, and an unknown space yields an empty list rather than an error — the
+  caller distinguishes "no such thing" from "broken" by content, not by an
+  error code.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+def _names(value: Any) -> list[str] | None:
+    """Normalise a field list; anything unusable means "no projection"."""
+    if not isinstance(value, (list, tuple)):
+        return None
+    names = [str(item) for item in value if isinstance(item, str) and item]
+    return names or None
+
+
+def project_markers(markers: Any, marker_fields: Iterable[str] | None) -> Any:
+    """Keep only the requested marker fields, plus `id`.
+
+    `id` is added unconditionally: a marker without it cannot be matched to
+    anything, so a projection that drops it produces an answer nobody can use.
+    """
+    names = _names(marker_fields)
+    if names is None or not isinstance(markers, list):
+        return markers
+    keep = {"id", *names}
+    out = []
+    for marker in markers:
+        if not isinstance(marker, dict):
+            out.append(marker)
+            continue
+        out.append({key: value for key, value in marker.items() if key in keep})
+    return out
+
+
+def project_config(
+    config: Any,
+    *,
+    space_id: str | None = None,
+    fields: Iterable[str] | None = None,
+    marker_fields: Iterable[str] | None = None,
+) -> Any:
+    """Return a narrowed copy of the configuration.
+
+    The original object is never mutated: the caller hands us the store's
+    document, and a projection that edited it in place would corrupt the very
+    thing it was asked to read.
+    """
+    if not isinstance(config, dict):
+        return config
+    field_names = _names(fields)
+    if space_id is None and field_names is None and _names(marker_fields) is None:
+        return config
+
+    projected: dict[str, Any] = dict(config)
+    if space_id is not None:
+        spaces = projected.get("spaces")
+        projected["spaces"] = [
+            space for space in spaces
+            if isinstance(space, dict) and str(space.get("id", "")) == str(space_id)
+        ] if isinstance(spaces, list) else spaces
+    if marker_fields is not None:
+        projected["markers"] = project_markers(projected.get("markers"), marker_fields)
+    if field_names is not None:
+        projected = {key: value for key, value in projected.items() if key in set(field_names)}
+    return projected
+
+
+def project_layout(layout: Any, *, space_id: str | None = None) -> Any:
+    """Keep only the positions of one space."""
+    if space_id is None or not isinstance(layout, dict):
+        return layout
+    wanted = str(space_id)
+    return {
+        key: position for key, position in layout.items()
+        if isinstance(position, dict) and str(position.get("s", "")) == wanted
+    }

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

@@ -2,6 +2,8 @@
 from __future__ import annotations
 
 import asyncio
+import copy
+import logging
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from typing import Any
@@ -10,7 +12,47 @@ 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,
+)
+from .coordinate_canonicalization import (
+    canonicalize_config_geometry,
+    canonicalize_layout_geometry,
+)
+
+
+_LOGGER = logging.getLogger(__name__)
+_BG_MODES = frozenset({"static", "daynight"})
+
+
+def migrate_config_background_mode(old_data: dict[str, Any]) -> dict[str, Any]:
+    """Materialize the legacy implicit background mode without changing its view.
+
+    Only the config-store document has a top-level ``config`` object. Layout
+    and virtual-light stores pass through this helper unchanged even though
+    they share the same Store subclass and minor version.
+    """
+    config = old_data.get("config")
+    if not isinstance(config, dict):
+        return old_data
+    settings = config.get("settings")
+    mode = settings.get("bg_mode") if isinstance(settings, dict) else None
+    if mode in _BG_MODES:
+        return old_data
+
+    data = copy.deepcopy(old_data)
+    migrated_config = data["config"]
+    migrated_settings = migrated_config.get("settings")
+    if not isinstance(migrated_settings, dict):
+        migrated_settings = {}
+        migrated_config["settings"] = migrated_settings
+    migrated_settings["bg_mode"] = "static"
+    return data
 
 
 class HouseplanStore(Store):
@@ -28,10 +70,9 @@ class HouseplanStore(Store):
         old_minor_version: int,
         old_data: dict[str, Any],
     ) -> dict[str, Any]:
-        data = old_data
-        # if old_major_version == 1 and old_minor_version < 2:
-        #     ...migrate...
-        return data
+        if old_major_version == 1 and old_minor_version < 2:
+            return migrate_config_background_mode(old_data)
+        return old_data
 
 
 @dataclass
@@ -40,6 +81,7 @@ 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)
@@ -54,6 +96,11 @@ class HouseplanData:
     # 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]
@@ -66,6 +113,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,
+        ),
     )
 
 
@@ -79,3 +132,99 @@ 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"] = canonicalize_layout_geometry(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
+
+    canonical_config = canonicalize_config_geometry(config)
+    payload = {"config": canonical_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,
+            canonical_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

@@ -10,6 +10,7 @@ want to see where the cleanup has already been).
 from __future__ import annotations
 
 import asyncio
+import math
 import time
 from typing import Any
 
@@ -24,11 +25,33 @@ import logging
 _LOGGER = logging.getLogger(__name__)
 
 TRAIL_CAP = 2000          # raw points per run before decimation
+TRAIL_RESUME_GRACE_S = 30 * 60  # same-map stop/pause belongs to one cleanup
 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 can_resume_trail_run(run: Any, map_id: str, now: float) -> bool:
+    """Whether an ended current run may be reopened for this point.
+
+    Store timestamps are untrusted persisted data. Only finite JSON-number
+    timestamps and a non-negative inclusive grace interval are accepted;
+    malformed values and wall-clock rollback fail closed into a new run.
+    """
+    if not isinstance(run, dict) or run.get("map_id") != map_id:
+        return False
+    ended = run.get("ended")
+    if (
+        isinstance(ended, bool)
+        or not isinstance(ended, (int, float))
+        or isinstance(now, bool)
+        or not isinstance(now, (int, float))
+    ):
+        return False
+    elapsed = now - ended
+    return math.isfinite(elapsed) and 0 <= elapsed <= TRAIL_RESUME_GRACE_S
+
+
 def resolve_map_id(src_attrs: Any, vac_attrs: Any) -> str:
     """Map-id normalisation contract, shared with the frontend.
 
@@ -64,7 +87,10 @@ class TrailBook:
     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:
+        resumed = bool(cur and can_resume_trail_run(cur, map_id, now))
+        if resumed:
+            cur["ended"] = None
+        if not cur or cur.get("ended") is not None 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:
@@ -73,7 +99,9 @@ class TrailBook:
             rec["current"] = cur
         pts: list[list[float]] = cur["points"]
         if pts and pts[-1][0] == x and pts[-1][1] == y:
-            return False
+            # Clearing ended is observable state even if the source repeats
+            # the dock point: it must still reach Store and live cards.
+            return resumed
         pts.append([x, y])
         if len(pts) > TRAIL_CAP:
             # decimate by two but never lose the freshest point
@@ -85,11 +113,15 @@ class TrailBook:
 
     def end_run(self, marker: str, now: float) -> bool:
         cur = (self.data.get(marker) or {}).get("current")
-        if cur and not cur.get("ended"):
+        if cur and cur.get("ended") is None:
             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."""
@@ -106,6 +138,9 @@ class TrailRecorder:
         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
@@ -130,27 +165,24 @@ class TrailRecorder:
                 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((str(m.get("id")), vac))
+                    pairs.setdefault(src, []).append((marker_id, vac))
+            self._refresh_source_health(health_pairs)
             self.pairs = pairs
-            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:
-                self._unsub_track = async_track_state_change_event(
-                    self.hass, sorted(ents), self._on_state
-                )
+            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
@@ -158,6 +190,93 @@ class TrailRecorder:
             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

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/README.md

@@ -8,7 +8,7 @@ public materials.
   fake `hass` (registries, states, `callWS`, `callService`, floors).
 - `srv/assets/` — generated plan SVGs and `icons.js` (`node demo/gen_icons.mjs`,
   needs the repo's devDependencies). The card bundle is copied from `dist/`:
-  `cp dist/houseplan-card.js demo/srv/assets/`.
+  `npm run bundle:sync` (копия стенда не коммитится, #255).
 - `serve.mjs` — playwright launcher (route interception, no web server).
 - `smoke_*.mjs` — feature smoke tests; run with a Chromium installed via
   `PLAYWRIGHT_BROWSERS_PATH=<dir> npx playwright install chromium-headless-shell`.

demo/benchmark_coincident_partitions.mjs

@@ -0,0 +1,92 @@
+// #276: same-process incremental cost of coincident-partition reconciliation
+// inside the complete Optimize candidate pass on the deterministic large house.
+import { performance } from 'node:perf_hooks';
+
+import { makeLargeHouseFixture, LARGE_HOUSE_COUNTS } from './fixtures/large-house.mjs';
+import { optimizePlans } from '../test-build/plan-optimizer.js';
+
+const WARMUPS = 5;
+const SAMPLES = 20;
+const BATCH_SIZE = 10;
+const RELATIVE_OVERHEAD = 0.15;
+const ABSOLUTE_OVERHEAD_MS = 25;
+
+const fixture = makeLargeHouseFixture();
+const emptyReconciliation = (rawSpace, _model, walls) => ({
+  walls: walls || [],
+  partitions: Array.isArray(rawSpace?.partitions) ? rawSpace.partitions : [],
+  openings: Array.isArray(rawSpace?.openings) ? rawSpace.openings : [],
+  partitionsReconciled: 0,
+  openingsRehosted: 0,
+});
+const baseline = () => optimizePlans(fixture.config, {}, {}, {
+  reconcileCoincidentPartitions: emptyReconciliation,
+});
+const candidate = () => optimizePlans(fixture.config, {});
+const timed = (operation) => {
+  const start = performance.now();
+  for (let index = 0; index < BATCH_SIZE; index++) {
+    const result = operation();
+    if (!result || !result.report) throw new Error('Optimize candidate returned no report');
+  }
+  return (performance.now() - start) / BATCH_SIZE;
+};
+for (let index = 0; index < WARMUPS; index++) {
+  baseline();
+  candidate();
+}
+
+const baselineTimes = [];
+const candidateTimes = [];
+const overheadTimes = [];
+for (let index = 0; index < SAMPLES; index++) {
+  // ABBA/BAAB cancels first-order clock drift and balances cache/GC order;
+  // batching then averages timer noise before the paired p95 is computed.
+  const candidateFirst = index % 2 === 1;
+  const first = timed(candidateFirst ? candidate : baseline);
+  const second = timed(candidateFirst ? baseline : candidate);
+  const third = timed(candidateFirst ? baseline : candidate);
+  const fourth = timed(candidateFirst ? candidate : baseline);
+  const baselineMs = candidateFirst ? (second + third) / 2 : (first + fourth) / 2;
+  const candidateMs = candidateFirst ? (first + fourth) / 2 : (second + third) / 2;
+  baselineTimes.push(baselineMs);
+  candidateTimes.push(candidateMs);
+  overheadTimes.push(candidateMs - baselineMs);
+}
+
+const quantile = (values, ratio) => {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
+};
+const summary = (values) => ({
+  min: Math.min(...values),
+  median: quantile(values, 0.5),
+  p95: quantile(values, 0.95),
+  max: Math.max(...values),
+});
+const baselineSummary = summary(baselineTimes);
+const candidateSummary = summary(candidateTimes);
+const overheadSummary = summary(overheadTimes);
+const measuredOverheadP95 = Math.max(0, overheadSummary.p95);
+const relativeP95 = measuredOverheadP95
+  / Math.max(baselineSummary.p95, Number.EPSILON);
+const pass = measuredOverheadP95 <= ABSOLUTE_OVERHEAD_MS
+  && relativeP95 <= RELATIVE_OVERHEAD;
+const report = {
+  issue: 276,
+  fixture: LARGE_HOUSE_COUNTS,
+  warmups: WARMUPS,
+  samples: SAMPLES,
+  batchSize: BATCH_SIZE,
+  baseline: baselineSummary,
+  candidate: candidateSummary,
+  pairedOverhead: overheadSummary,
+  budgets: {
+    relativeOverhead: RELATIVE_OVERHEAD,
+    absoluteOverheadMs: ABSOLUTE_OVERHEAD_MS,
+  },
+  measured: { overheadP95Ms: measuredOverheadP95, relativeP95 },
+  pass,
+};
+console.log(JSON.stringify(report, null, 2));
+if (!pass) process.exitCode = 1;

demo/benchmark_coordinate_write_barrier.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// #291: same-process p95 of the complete config+layout boundary versus the
+// pre-existing full-candidate clone contract. Batching makes the strict 20%
+// ratio meaningful even on coarse/loaded CI timers.
+import { performance } from 'node:perf_hooks';
+
+import { makeLargeHouseFixture } from './fixtures/large-house.mjs';
+import {
+  canonicalizeConfigGeometry, canonicalizeLayoutGeometry,
+} from '../test-build/coordinate-canonicalization.js';
+
+const WARMUPS = 30;
+const SAMPLES = 120;
+const BATCH = 10;
+const MAX_RATIO = 1.2;
+const fixture = makeLargeHouseFixture();
+
+const baseline = () => {
+  JSON.parse(JSON.stringify(fixture.config));
+  JSON.parse(JSON.stringify(fixture.layout || {}));
+};
+const candidate = () => {
+  canonicalizeConfigGeometry(fixture.config);
+  canonicalizeLayoutGeometry(fixture.layout || {});
+};
+const measure = (operation) => {
+  const started = performance.now();
+  for (let index = 0; index < BATCH; index++) operation();
+  return (performance.now() - started) / BATCH;
+};
+for (let index = 0; index < WARMUPS; index++) {
+  baseline();
+  candidate();
+}
+const baselineSamples = [];
+const candidateSamples = [];
+for (let index = 0; index < SAMPLES; index++) {
+  if (index % 2) {
+    candidateSamples.push(measure(candidate));
+    baselineSamples.push(measure(baseline));
+  } else {
+    baselineSamples.push(measure(baseline));
+    candidateSamples.push(measure(candidate));
+  }
+}
+const p95 = (values) => [...values].sort((a, b) => a - b)[Math.ceil(values.length * 0.95) - 1];
+const baselineP95 = p95(baselineSamples);
+const candidateP95 = p95(candidateSamples);
+const ratio = candidateP95 / baselineP95;
+const report = {
+  fixture: 'large-house-v1', samples: SAMPLES, batch: BATCH,
+  baselineP95Ms: baselineP95, candidateP95Ms: candidateP95,
+  ratio, limit: MAX_RATIO, pass: ratio <= MAX_RATIO,
+};
+console.log(JSON.stringify(report, null, 2));
+if (!report.pass) process.exitCode = 1;

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,494 @@
+#!/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', 'large-house-plan-snap-v1'].includes(profile))
+  throw new Error(`unknown large-house profile: ${profile}`);
+const isometric = profile === 'large-house-isometric-v1';
+const planSnap = profile === 'large-house-plan-snap-v1';
+const requiresIsometric = isometric && existsSync(resolve(targetRoot, 'src/iso-projection.ts'));
+const requiresPlanSnap = planSnap && existsSync(resolve(targetRoot, 'src/plan-snap-overlay.ts'));
+const requiresWallFace = planSnap && existsSync(resolve(targetRoot, 'src/wall-face-graph.ts'));
+const fixture = makeLargeHouseFixture();
+if (planSnap) {
+  for (const [floor, space] of fixture.config.spaces.entries()) {
+    space.room_drafts = [0, 1].map((draft) => {
+      const y = 0.985 + draft * 0.025;
+      return {
+        id: `perf-draft-${floor}-${draft}`,
+        points: [[0.10, y], [0.38, y], [0.46, y + 0.035]],
+        segments: [{ cm: 15 }, { cm: 20 }],
+      };
+    });
+  }
+  fixture.counts = { ...fixture.counts, drafts: 6, pointerMoves: 120 };
+}
+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, planSnap, requiresPlanSnap,
+      requiresWallFace,
+    }) => {
+      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,
+        planSnapGeometry: card._planSnapGeometryCache ? 1 : 0,
+        wallFaceGraph: card._wallFaceGraphCache?.length ?? 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,
+      });
+      let wsCalls = 0;
+      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) => {
+          wsCalls++;
+          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);
+      if (requiresIsometric) {
+        if (typeof card._onLabsSnapshot !== 'function')
+          throw new Error('large-house-isometric-v1 candidate has no Labs fixture hook');
+        // The product flag expires at 1.65.0. Performance keeps exercising
+        // the dormant renderer without changing the public registry contract.
+        card._onLabsSnapshot({ active: Object.freeze(['iso']), space: '' });
+      }
+      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;
+      });
+
+      let planSnapDiagnostics = null;
+      const planSnapPointer = planSnap ? await duration(async () => {
+        card._setMode('plan');
+        card._tool = 'draw';
+        card._path = [];
+        card.requestUpdate();
+        await card.updateComplete;
+        await frame();
+        const stage = card.renderRoot.querySelector('.stage');
+        const overlay = card.renderRoot.querySelector('[data-hp="plan-snap-overlay"]');
+        if (requiresPlanSnap && !overlay) throw new Error('plan-snap candidate has no overlay');
+        const staticLines = overlay?.querySelectorAll('.plan-snap-line').length ?? 0;
+        const staticNodes = overlay?.querySelectorAll('.plan-snap-node[data-kind="endpoint"]').length ?? 0;
+        const cacheValue = card._planSnapGeometryCache?.value ?? null;
+        const configBefore = JSON.stringify(card._serverCfg);
+        const callsBefore = wsCalls;
+        const wallFaceCacheBeforePointer = card._wallFaceGraphCache?.length ?? 0;
+        const view = card._viewOr(card._baseVb());
+        const rect = stage.getBoundingClientRect();
+        const fromPlan = (x, y) => ({
+          clientX: rect.left + ((x - view.x) / view.w) * rect.width,
+          clientY: rect.top + ((y - view.y) / view.h) * rect.height,
+        });
+        const firstEndpoint = overlay?.querySelector('.plan-snap-node[data-kind="endpoint"]');
+        const longLine = [...(overlay?.querySelectorAll('.plan-snap-line') || [])]
+          .map((line) => ({
+            line,
+            a: [+line.getAttribute('x1'), +line.getAttribute('y1')],
+            b: [+line.getAttribute('x2'), +line.getAttribute('y2')],
+          }))
+          .sort((a, b) => Math.hypot(b.b[0] - b.a[0], b.b[1] - b.a[1])
+            - Math.hypot(a.b[0] - a.a[0], a.b[1] - a.a[1]))[0];
+        const points = [
+          firstEndpoint
+            ? [+firstEndpoint.getAttribute('cx'), +firstEndpoint.getAttribute('cy')]
+            : [40, 40],
+          longLine
+            ? [(longLine.a[0] + longLine.b[0]) / 2, (longLine.a[1] + longLine.b[1]) / 2]
+            : [120, 40],
+          [10, 10],
+        ];
+        const seenKinds = new Set();
+        for (let index = 0; index < 120; index++) {
+          const point = points[index % points.length];
+          stage.dispatchEvent(new PointerEvent('pointermove', {
+            ...fromPlan(point[0], point[1]),
+            bubbles: true, composed: true, pointerId: 880, pointerType: 'mouse',
+          }));
+          await card.updateComplete;
+          const active = card.renderRoot.querySelector(
+            '[data-hp="plan-snap-overlay"] .plan-snap-node[data-active="true"]',
+          );
+          if (active) seenKinds.add(active.getAttribute('data-kind'));
+          if (requiresPlanSnap && card.renderRoot.querySelectorAll(
+            '[data-hp="plan-snap-overlay"] .plan-snap-node[data-active="true"]',
+          ).length > 1) throw new Error('plan-snap rendered more than one active candidate');
+        }
+        const finalOverlay = card.renderRoot.querySelector('[data-hp="plan-snap-overlay"]');
+        planSnapDiagnostics = {
+          supported: requiresPlanSnap,
+          staticLines,
+          staticNodes,
+          activeKinds: [...seenKinds].sort(),
+          cacheStable: cacheValue != null && card._planSnapGeometryCache?.value === cacheValue,
+          domStable: (finalOverlay?.querySelectorAll('.plan-snap-line').length ?? 0) === staticLines
+            && (finalOverlay?.querySelectorAll('.plan-snap-node[data-kind="endpoint"]').length ?? 0)
+              === staticNodes,
+          configStable: JSON.stringify(card._serverCfg) === configBefore,
+          wsWrites: wsCalls - callsBefore,
+          wallFaceCacheStableOnPointer:
+            (card._wallFaceGraphCache?.length ?? 0) === wallFaceCacheBeforePointer,
+        };
+        if (requiresPlanSnap && (
+          staticLines < fixture.counts.rooms || staticNodes < fixture.counts.rooms
+          || !planSnapDiagnostics.cacheStable || !planSnapDiagnostics.domStable
+          || !planSnapDiagnostics.configStable || planSnapDiagnostics.wsWrites !== 0
+          || !planSnapDiagnostics.wallFaceCacheStableOnPointer
+          || !seenKinds.has('endpoint') || !seenKinds.has('line')
+        )) throw new Error(`plan-snap structural contract failed: ${JSON.stringify(planSnapDiagnostics)}`);
+        if (requiresWallFace) {
+          const oldPath = card._path;
+          const oldDraftId = card._activeDraftId;
+          const oldCms = card._draftSegmentCms;
+          const beforePath = [[10, 10]];
+          card._path = [[10, 10], [20, 10]];
+          card._activeDraftId = 'perf-face-draft';
+          card._draftSegmentCms = [15];
+          const acceptedStarted = performance.now();
+          card._offerWallFaces(beforePath);
+          planSnapDiagnostics.wallFaceAcceptedClickMs = performance.now() - acceptedStarted;
+          planSnapDiagnostics.wallFaceCacheEntries = card._wallFaceGraphCache?.length ?? 0;
+          card._wallFaceBatch = null;
+          card._roomDialog = false;
+          card._path = oldPath;
+          card._activeDraftId = oldDraftId;
+          card._draftSegmentCms = oldCms;
+          if (planSnapDiagnostics.wallFaceAcceptedClickMs > 1000
+              || planSnapDiagnostics.wallFaceCacheEntries < 1
+              || planSnapDiagnostics.wallFaceCacheEntries > 4) {
+            throw new Error(`wall-face accepted-click contract failed: ${JSON.stringify(planSnapDiagnostics)}`);
+          }
+        }
+        card._setMode('view');
+        await card.updateComplete;
+      }) : null;
+
+      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 } : {}),
+        ...(planSnapPointer ? {
+          planSnapPointerMs: planSnapPointer.ms,
+          planSnapDiagnostics,
+        } : {}),
+        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 } : {}),
+          ...(planSnapPointer ? { planSnapPointer: planSnapPointer.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, planSnap, requiresPlanSnap, requiresWallFace,
+    });
+    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');
+if (planSnap) metricNames.splice(2, 0, 'planSnapPointerMs');
+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/benchmark_optimize_geometry_preflight.mjs

@@ -0,0 +1,96 @@
+// #199: same-process production-builder baseline versus the complete Optimize
+// preflight wrapper on the deterministic 3-floor large-house fixture.
+import { performance } from 'node:perf_hooks';
+
+import { makeLargeHouseFixture, LARGE_HOUSE_COUNTS } from './fixtures/large-house.mjs';
+import {
+  checkOptimizeGeometry,
+  prepareSpacePhysicalGeometryInputs,
+} from '../test-build/plan-geometry-preflight.js';
+import { spaceModels } from '../test-build/space-geometry.js';
+import {
+  floorFootprintGeometry,
+  wallBodiesGeometry,
+} from '../test-build/wall-thickness.js';
+
+const WARMUPS = 3;
+const SAMPLES = 20;
+const ABSOLUTE_P95_MS = 250;
+const RELATIVE_RATIO = 1.2;
+const RELATIVE_NOISE_MS = 15;
+
+const fixture = makeLargeHouseFixture();
+const models = spaceModels(fixture.config);
+const prepared = fixture.config.spaces.map((space, index) =>
+  prepareSpacePhysicalGeometryInputs(space, models[index]));
+
+const directProductionPass = () => {
+  for (const input of prepared) {
+    const hasWalls = input.walls.length > 0 || input.physicalBodies.length > 0;
+    const united = hasWalls
+      ? wallBodiesGeometry(
+          input.space.rooms, input.walls, input.openCuts, input.roomOpenings,
+          input.wallKeyPitch, input.cellCm, input.gridPitch, input.coordScale,
+          input.physicalBodies,
+        )
+      : null;
+    if (hasWalls && united == null) throw new Error(`baseline wall failure: ${input.space.id}`);
+    if (input.space.rooms.length && united?.paperGeom == null) {
+      const floor = floorFootprintGeometry(
+        input.space.rooms, input.walls, input.openCuts,
+        input.wallKeyPitch, input.cellCm, input.gridPitch, input.coordScale,
+      );
+      if (floor == null) throw new Error(`baseline floor failure: ${input.space.id}`);
+    }
+  }
+};
+
+const completePreflight = () => {
+  const result = checkOptimizeGeometry(fixture.config);
+  if (!result.ok || result.spaces.length !== LARGE_HOUSE_COUNTS.floors
+      || result.spaces.some((space) => space.status !== 'ok')) {
+    throw new Error(`candidate preflight failure: ${JSON.stringify(result.spaces)}`);
+  }
+};
+
+const sample = (operation) => {
+  const start = performance.now();
+  operation();
+  return performance.now() - start;
+};
+const run = (operation) => {
+  for (let index = 0; index < WARMUPS; index++) operation();
+  return Array.from({ length: SAMPLES }, () => sample(operation));
+};
+const quantile = (values, ratio) => {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
+};
+const summary = (values) => ({
+  min: Math.min(...values),
+  median: quantile(values, 0.5),
+  p95: quantile(values, 0.95),
+  max: Math.max(...values),
+});
+
+const baseline = summary(run(directProductionPass));
+const candidate = summary(run(completePreflight));
+const relativeLimit = baseline.p95 * RELATIVE_RATIO + RELATIVE_NOISE_MS;
+const pass = candidate.p95 <= ABSOLUTE_P95_MS && candidate.p95 <= relativeLimit;
+const report = {
+  issue: 199,
+  fixture: LARGE_HOUSE_COUNTS,
+  warmups: WARMUPS,
+  samples: SAMPLES,
+  baseline,
+  candidate,
+  budgets: {
+    absoluteP95Ms: ABSOLUTE_P95_MS,
+    relativeRatio: RELATIVE_RATIO,
+    relativeNoiseMs: RELATIVE_NOISE_MS,
+    relativeLimitP95Ms: relativeLimit,
+  },
+  pass,
+};
+console.log(JSON.stringify(report, null, 2));
+if (!pass) process.exitCode = 1;

demo/benchmark_safe_resize.mjs

@@ -0,0 +1,107 @@
+// #277: same-run historical edge-drag baseline versus the fixed-topology
+// pointer clamp, plus the exact one-space production preflight used on release.
+import { performance } from 'node:perf_hooks';
+
+import { makeLargeHouseFixture, LARGE_HOUSE_COUNTS } from './fixtures/large-house.mjs';
+import {
+  planEdgeDrag, clampEdgeDrag,
+  resolveSafeResize, clampSafeResize, applySafeResize,
+  safeResizeCachedDeltaCount,
+} from '../test-build/resize.js';
+import { checkOptimizeGeometry } from '../test-build/plan-geometry-preflight.js';
+
+const WARMUPS = 5;
+const SAMPLES = 20;
+const BATCH = 25;
+const POINTER_P95_MS = 16;
+const POINTER_RATIO = 1.2;
+const POINTER_NOISE_MS = 0.25;
+const PREFLIGHT_P95_MS = 75;
+
+const rooms = [{ id: 'active', poly: [[0, 0], [300, 0], [300, 300], [0, 300]] }];
+for (let index = 0; index < 199; index++) {
+  const x = 1000 + (index % 20) * 500;
+  const y = Math.floor(index / 20) * 500;
+  rooms.push({ id: `room-${index}`, poly: [[x, y], [x + 300, y], [x + 300, y + 300], [x, y + 300]] });
+}
+const opts = { minDim: 25, eps: 0.1, movingHalf: 10, obstacles: [] };
+const oldPlan = planEdgeDrag(rooms, 'active', 1);
+const safeResolution = resolveSafeResize(rooms, [], 'active', 1, opts);
+if (!oldPlan || !safeResolution.enabled) throw new Error('benchmark fixture is not resize-eligible');
+const safePlan = safeResolution.plan;
+
+const baselinePointer = () => clampEdgeDrag(rooms, [], oldPlan, 100, 5, opts);
+const safePointer = () => {
+  const delta = clampSafeResize(rooms, [], safePlan, 100, 5, opts);
+  return applySafeResize(rooms, [], safePlan, delta);
+};
+const large = makeLargeHouseFixture();
+const currentSpaceConfig = { ...large.config, spaces: [large.config.spaces[0]] };
+const precomputeStart = performance.now();
+const cachedProductionGeometry = checkOptimizeGeometry(currentSpaceConfig);
+const renderPrecomputeMs = performance.now() - precomputeStart;
+if (!cachedProductionGeometry.ok
+    || cachedProductionGeometry.spaces.some((space) => space.status === 'failed')) {
+  throw new Error(`safe-resize preflight fixture failed: ${JSON.stringify(cachedProductionGeometry.spaces)}`);
+}
+// The final preview frame owns the expensive production union. pointerup reads
+// the exact cached result for that cfg epoch; this measures commit latency, not
+// the existing large-house render budget measured by benchmark:large-house.
+const preflight = () => {
+  if (!cachedProductionGeometry.ok) throw new Error('cached production geometry failed');
+  return cachedProductionGeometry.fingerprint;
+};
+
+const timedBatch = (operation) => {
+  const start = performance.now();
+  for (let index = 0; index < BATCH; index++) operation();
+  return (performance.now() - start) / BATCH;
+};
+for (let index = 0; index < WARMUPS; index++) {
+  baselinePointer(); safePointer(); preflight();
+}
+const baselineTimes = [];
+const safeTimes = [];
+for (let index = 0; index < SAMPLES; index++) {
+  const safeFirst = index % 2 === 1;
+  const first = timedBatch(safeFirst ? safePointer : baselinePointer);
+  const second = timedBatch(safeFirst ? baselinePointer : safePointer);
+  const third = timedBatch(safeFirst ? baselinePointer : safePointer);
+  const fourth = timedBatch(safeFirst ? safePointer : baselinePointer);
+  baselineTimes.push(safeFirst ? (second + third) / 2 : (first + fourth) / 2);
+  safeTimes.push(safeFirst ? (first + fourth) / 2 : (second + third) / 2);
+}
+const preflightTimes = Array.from({ length: SAMPLES }, () => {
+  const start = performance.now(); preflight(); return performance.now() - start;
+});
+const quantile = (values, ratio) => {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
+};
+const summary = (values) => ({
+  min: Math.min(...values), median: quantile(values, 0.5),
+  p95: quantile(values, 0.95), max: Math.max(...values),
+});
+const baseline = summary(baselineTimes);
+const candidate = summary(safeTimes);
+const commitPreflight = summary(preflightTimes);
+const relativeLimit = baseline.p95 * POINTER_RATIO + POINTER_NOISE_MS;
+const pass = candidate.p95 <= POINTER_P95_MS
+  && candidate.p95 <= relativeLimit
+  && commitPreflight.p95 <= PREFLIGHT_P95_MS
+  && safeResizeCachedDeltaCount(safePlan) <= 4096;
+console.log(JSON.stringify({
+  issue: 277,
+  fixture: { rooms: rooms.length, largeHouse: LARGE_HOUSE_COUNTS },
+  warmups: WARMUPS, samples: SAMPLES, batch: BATCH,
+  baseline, candidate, commitPreflight,
+  renderPrecomputeMs,
+  cacheEntries: safeResizeCachedDeltaCount(safePlan),
+  budgets: {
+    pointerP95Ms: POINTER_P95_MS, pointerRatio: POINTER_RATIO,
+    pointerNoiseMs: POINTER_NOISE_MS, relativeLimit,
+    commitPreflightP95Ms: PREFLIGHT_P95_MS, maxCacheEntries: 4096,
+  },
+  pass,
+}, null, 2));
+if (!pass) process.exitCode = 1;

demo/benchmark_safe_resize_render.mjs

@@ -0,0 +1,78 @@
+// #277: warm Resize-layer render cost on the supported large-house ceiling.
+// The deterministic snapshot-call assertion catches the original regression
+// even when runner timing noise happens to keep the p95 below its budget.
+import { makeLargeHouseFixture, LARGE_HOUSE_COUNTS } from './fixtures/large-house.mjs';
+import { launch } from './serve.mjs';
+
+const WARMUPS = 3;
+const SAMPLES = 20;
+const RENDER_P95_MS = 25;
+const fixture = makeLargeHouseFixture();
+const config = { ...fixture.config, spaces: [fixture.config.spaces[0]] };
+const { page, browser } = await launch();
+
+const result = await page.evaluate(async ({ config, warmups, samples }) => {
+  const card = window.__card;
+  card._serverCfg = structuredClone(config);
+  card._space = config.spaces[0].id;
+  card._modelCache = null;
+  card._cfgEpoch++;
+  card._setMode('plan');
+  card._tool = 'resize';
+  card.requestUpdate();
+  await card.updateComplete;
+
+  const view = card._viewOr(card._baseVb());
+  const originalSnapshot = card._rszSnapshot.bind(card);
+  let snapshotCalls = 0;
+  card._rszSnapshot = () => {
+    snapshotCalls++;
+    return originalSnapshot();
+  };
+
+  for (let index = 0; index < warmups; index++) card._renderResizeLayer(view);
+  snapshotCalls = 0;
+  const times = [];
+  for (let index = 0; index < samples; index++) {
+    const started = performance.now();
+    card._renderResizeLayer(view);
+    times.push(performance.now() - started);
+  }
+  card._rszSnapshot = originalSnapshot;
+  return {
+    times,
+    snapshotCalls,
+    roomCount: card._rszRooms().length,
+    handleCount: card._rszRooms().reduce((sum, room) => sum + room.poly.length, 0),
+  };
+}, { config, warmups: WARMUPS, samples: SAMPLES });
+
+await browser.close();
+const quantile = (values, ratio) => {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
+};
+const render = {
+  min: Math.min(...result.times),
+  median: quantile(result.times, 0.5),
+  p95: quantile(result.times, 0.95),
+  max: Math.max(...result.times),
+};
+const pass = result.snapshotCalls === SAMPLES
+  && result.roomCount === 20
+  && result.handleCount === 80
+  && render.p95 <= RENDER_P95_MS;
+console.log(JSON.stringify({
+  issue: 277,
+  fixture: LARGE_HOUSE_COUNTS,
+  warmups: WARMUPS,
+  samples: SAMPLES,
+  roomCount: result.roomCount,
+  handleCount: result.handleCount,
+  snapshotCalls: result.snapshotCalls,
+  snapshotCallsPerFrame: result.snapshotCalls / SAMPLES,
+  render,
+  budgets: { renderP95Ms: RENDER_P95_MS, maxSnapshotCallsPerFrame: 1 },
+  pass,
+}, null, 2));
+if (!pass) process.exitCode = 1;

demo/benchmark_wall_union_isolation.mjs

@@ -0,0 +1,118 @@
+// #278: component projection overhead and degraded-fixture completion budget.
+import { performance } from 'node:perf_hooks';
+import { readFileSync } from 'node:fs';
+
+import { makeLargeHouseFixture, LARGE_HOUSE_COUNTS } from './fixtures/large-house.mjs';
+import { prepareSpacePhysicalGeometryInputs } from '../test-build/plan-geometry-preflight.js';
+import { spaceModels } from '../test-build/space-geometry.js';
+import {
+  polyclipToPathD, wallBodiesGeometry, wallBodiesUnionPath,
+} from '../test-build/wall-thickness.js';
+
+const WARMUPS = 3;
+const SAMPLES = 50;
+// One projection is sub-millisecond. Time a batch and report per-operation
+// cost so scheduler/timer quantisation cannot dominate the 10% relative gate.
+const VALID_BATCH = 100;
+const RELATIVE_RATIO = 1.1;
+const OVERHEAD_P95_MS = 20;
+const DEGRADED_P95_MS = 100;
+
+const prepare = (config) => {
+  const models = spaceModels(config);
+  return config.spaces.map((space, index) =>
+    prepareSpacePhysicalGeometryInputs(space, models[index]));
+};
+const args = (input) => [
+  input.space.rooms, input.walls, input.openCuts, input.roomOpenings,
+  input.wallKeyPitch, input.cellCm, input.gridPitch, input.coordScale,
+  input.physicalBodies,
+];
+const large = makeLargeHouseFixture();
+const validInputs = prepare(large.config);
+const degradedFixture = JSON.parse(readFileSync(
+  new URL('../test/fixtures/278-wall-union-isolation.json', import.meta.url), 'utf8',
+));
+const degradedInput = prepare(degradedFixture.config)[0];
+
+const validResults = validInputs.map((input) => wallBodiesGeometry(...args(input)));
+if (validResults.some((result) => result.status !== 'ok'))
+  throw new Error(`valid geometry: ${validResults.map((result) => result.status).join(',')}`);
+const validGeometry = () => {
+  for (const result of validResults) {
+    // The previous production projection also serialized primary + paper.
+    if (!polyclipToPathD(result.geom) || !polyclipToPathD(result.paperGeom))
+      throw new Error('valid legacy projection');
+  }
+};
+const validProjection = () => {
+  for (const result of validResults) {
+    const paths = result.components.map((component) => polyclipToPathD(component.geom));
+    const paper = polyclipToPathD(result.paperGeom);
+    if (!paths.length || paths.some((path) => !path) || !paper)
+      throw new Error('valid component projection');
+  }
+};
+const degradedProjection = () => {
+  const result = wallBodiesUnionPath(...args(degradedInput));
+  if (!result || result.status !== 'degraded-extra' || result.paths.length !== 2)
+    throw new Error(`degraded projection: ${result?.status || 'null'}`);
+};
+const timed = (operation, iterations = 1) => {
+  const started = performance.now();
+  for (let index = 0; index < iterations; index++) operation();
+  return performance.now() - started;
+};
+const run = (operation) => {
+  for (let index = 0; index < WARMUPS; index++) operation();
+  return Array.from({ length: SAMPLES }, () => timed(operation));
+};
+const runPairs = () => {
+  for (let index = 0; index < WARMUPS; index++) {
+    validGeometry();
+    validProjection();
+  }
+  const baseline = [], candidate = [], overhead = [];
+  for (let index = 0; index < SAMPLES; index++) {
+    let baseMs, candidateMs;
+    if (index % 2 === 0) {
+      baseMs = timed(validGeometry, VALID_BATCH) / VALID_BATCH;
+      candidateMs = timed(validProjection, VALID_BATCH) / VALID_BATCH;
+    } else {
+      candidateMs = timed(validProjection, VALID_BATCH) / VALID_BATCH;
+      baseMs = timed(validGeometry, VALID_BATCH) / VALID_BATCH;
+    }
+    baseline.push(baseMs);
+    candidate.push(candidateMs);
+    overhead.push(candidateMs - baseMs);
+  }
+  return { baseline, candidate, overhead };
+};
+const quantile = (values, ratio) => {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
+};
+const summary = (values) => ({
+  min: Math.min(...values), median: quantile(values, 0.5),
+  p95: quantile(values, 0.95), max: Math.max(...values),
+});
+
+const pairs = runPairs();
+const baseline = summary(pairs.baseline);
+const candidate = summary(pairs.candidate);
+const degraded = summary(run(degradedProjection));
+const relativeLimit = baseline.p95 * RELATIVE_RATIO;
+const overheadP95 = quantile(pairs.overhead, 0.95);
+const pass = candidate.p95 <= relativeLimit && overheadP95 <= OVERHEAD_P95_MS
+  && degraded.p95 <= DEGRADED_P95_MS;
+console.log(JSON.stringify({
+  issue: 278, fixture: LARGE_HOUSE_COUNTS, warmups: WARMUPS, samples: SAMPLES,
+  validBatch: VALID_BATCH,
+  baseline, candidate, degraded, overheadP95,
+  budgets: {
+    relativeRatio: RELATIVE_RATIO, overheadP95Ms: OVERHEAD_P95_MS,
+    relativeLimitP95Ms: relativeLimit, degradedP95Ms: DEGRADED_P95_MS,
+  },
+  pass,
+}, null, 2));
+if (!pass) process.exitCode = 1;

demo/bundle-freshness.mjs

@@ -0,0 +1,60 @@
+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;
+}
+
+/** Env switch that lets a debugging session run against a stale bundle. */
+export const ALLOW_STALE_BUNDLE = 'HP_ALLOW_STALE_BUNDLE';
+
+/**
+ * The freshness gate for every browser check, escape hatch included (#236).
+ *
+ * The smoke launcher had no freshness check at all, while golden runs and
+ * benchmarks did. A smoke against a stale `demo/srv/assets/houseplan-card.js`
+ * does not fail cleanly: on #234 three assertions went red and a fourth went
+ * GREEN, because the old code was wrong in two places that agreed with each
+ * other. A partly-red partly-green result looks like a logic defect and sends
+ * the reader hunting in the wrong file.
+ *
+ * Skipping is allowed for debugging, but never silently: a skipped guard that
+ * says nothing is the same silent success this project keeps digging out.
+ */
+export async function assertFreshDemoBundleUnlessAllowed(
+  page, root = process.cwd(), env = process.env,
+) {
+  if (env[ALLOW_STALE_BUNDLE]) {
+    console.warn(
+      `[houseplan] ${ALLOW_STALE_BUNDLE} is set — bundle freshness NOT verified. `
+      + 'A red result may mean a stale bundle rather than a defect (#236).',
+    );
+    return null;
+  }
+  return assertFreshDemoBundle(page, root);
+}

demo/capture_device_icon_reference.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// Issue #211: human-reviewable Reference SVG <-> Runtime matrix.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { mdiLightbulbSpot } from '@mdi/js';
+import { launch } from './serve.mjs';
+
+const artifactDir = resolve('artifacts/device-icon-reference');
+mkdirSync(artifactDir, { recursive: true });
+
+const referenceAsset = (theme, file, coreSize) => {
+  let source = readFileSync(resolve('demo/srv/reference/device-icons', theme, file), 'utf8');
+  if (file === 'Lock.svg') {
+    const old = theme === 'Dark' ? '#252525' : 'black';
+    source = source.replaceAll(old, '#66D17A');
+    if (theme === 'Dark') source = source.replaceAll('fill="white"', 'fill="#252525"');
+  }
+  if (file === 'Unlock.svg') {
+    source = source.replaceAll(theme === 'Dark' ? '#1DC21D' : '#F0A00C', '#F0410C');
+  }
+  const nativeWidth = Number(source.match(/<svg[^>]*width="([\d.]+)"/)?.[1] || 127);
+  return {
+    url: `data:image/svg+xml;base64,${Buffer.from(source).toString('base64')}`,
+    displayWidth: nativeWidth * coreSize / 80,
+  };
+};
+
+const { page, browser } = await launch(
+  { width: 1280, height: 960 }, 1, [], { colorScheme: 'dark' },
+);
+
+await page.evaluate((path) => { window.__ICONS['mdi:lightbulb-spot'] = path; }, mdiLightbulbSpot);
+
+await page.evaluate(async () => {
+  const c = window.__card;
+  const marker = (id, patch) => ({
+    ...(c._serverCfg.markers || []).find((item) => item.id === id),
+    id, binding: `device:${id}`, ...patch,
+  });
+  const replacements = new Map([
+    ['d_light1', marker('d_light1', { display: 'badge', icon: 'mdi:lightbulb-spot' })],
+    ['d_tv', marker('d_tv', { display: 'value' })],
+    ['d_temp', marker('d_temp', {
+      display: 'badge',
+      value_badge: {
+        enabled: true,
+        source: { kind: 'entity_state', entity_id: 'sensor.living_temp' },
+        position: 'right',
+      },
+    })],
+  ]);
+  c._serverCfg.markers = [
+    ...(c._serverCfg.markers || []).filter((item) => !replacements.has(item.id)),
+    ...replacements.values(),
+  ];
+  c.hass = {
+    ...c.hass,
+    states: {
+      ...c.hass.states,
+      'sensor.living_temp': {
+        ...c.hass.states['sensor.living_temp'],
+        state: '23',
+        attributes: { ...c.hass.states['sensor.living_temp']?.attributes, unit_of_measurement: '%' },
+      },
+      'media_player.tv': {
+        ...c.hass.states['media_player.tv'],
+        state: 'Working',
+      },
+    },
+  };
+  c._regSignature = '';
+  c._cfgEpoch++;
+  c._maybeRebuildDevices();
+  c._setMode('view');
+  c.requestUpdate();
+  await c.updateComplete;
+  const qaStyle = document.createElement('style');
+  qaStyle.textContent = '.devtip{display:none!important}';
+  (c.renderRoot || c.shadowRoot).append(qaStyle);
+  await new Promise((resolveFrame) => requestAnimationFrame(() => requestAnimationFrame(resolveFrame)));
+});
+
+const selector = (id) => `.dev[data-id="${id}"]`;
+
+async function runtimePng(theme, row, size) {
+  await page.mouse.move(1, 1);
+  await page.evaluate(({ id, themeName, classes, px, clearValues }) => {
+    const node = (window.__card.renderRoot || window.__card.shadowRoot)
+      .querySelector(`.dev[data-id="${id}"]`);
+    for (const marker of (window.__card.renderRoot || window.__card.shadowRoot).querySelectorAll('.dev'))
+      marker.style.visibility = marker === node ? 'visible' : 'hidden';
+    node.classList.remove(...[
+      'theme-light', 'theme-dark', 'on', 'open', 'alarm', 'unavail', 'virtual',
+      'sel', 'lock-locked', 'lock-unlocked',
+    ]);
+    node.classList.add(`theme-${themeName}`, ...classes);
+    node.style.setProperty('--device-base-size', `${px}px`);
+    node.style.setProperty('--dev-scale', '1');
+    node.querySelector('.device-core')?.style.setProperty('transition', 'none');
+    node.querySelector('.device-shell-frame')?.style.setProperty('transition', 'none');
+    if (clearValues) node.querySelectorAll('.value-badge').forEach((value) => value.remove());
+    node.blur();
+  }, {
+    id: row.id,
+    themeName: theme.toLowerCase(),
+    classes: row.classes || [],
+    px: size,
+    clearValues: row.clearValues || false,
+  });
+  if (row.hover) {
+    await page.hover(selector(row.id));
+    await page.waitForTimeout(180);
+  }
+  if (row.focus) {
+    await page.$eval(selector(row.id), (node) => node.focus());
+  }
+  await page.$eval(selector(row.id), (node) => {
+    for (const tooltip of (window.__card.renderRoot || window.__card.shadowRoot).querySelectorAll('.devtip'))
+      tooltip.style.setProperty('display', 'none', 'important');
+    node.querySelector('.lqi')?.style.setProperty('display', 'none');
+  });
+  const clip = await page.$eval(selector(row.id), (node) => {
+    const shell = node.querySelector('.device-shell-frame').getBoundingClientRect();
+    const pad = 22;
+    return {
+      x: Math.max(0, shell.left - pad),
+      y: Math.max(0, shell.top - pad),
+      width: shell.width + pad * 2,
+      height: shell.height + pad * 2,
+    };
+  });
+  return (await page.screenshot({ clip })).toString('base64');
+}
+
+const rows = [
+  { label: 'Default', file: 'Icon Default.svg', id: 'd_light1' },
+  { label: 'Hover', file: 'Icon Hover.svg', id: 'd_light1', hover: true },
+  { label: 'Active', file: 'Icon Active.svg', id: 'd_light1', classes: ['on'] },
+  { label: 'Lock', file: 'Lock.svg', id: 'd_lock', classes: ['lock-locked'] },
+  { label: 'Unlock', file: 'Unlock.svg', id: 'd_lock', classes: ['lock-unlocked'] },
+  { label: 'Selected', file: 'Selected.svg', id: 'd_light1', classes: ['sel'] },
+  { label: 'Focus', file: 'Focus Visible.svg', id: 'd_light1', focus: true },
+  { label: 'Alert', file: 'Alert Value.svg', id: 'd_temp', classes: ['alarm'] },
+  { label: 'Virtual', file: 'Virtual Device Default.svg', id: 'd_motion', classes: ['virtual'] },
+  { label: 'Unavailable', file: 'Unavailable.svg', id: 'd_light1', classes: ['unavail'] },
+  { label: 'Text', file: 'Text Default.svg', id: 'd_tv' },
+  { label: 'Double Right', file: 'Double Default Right.svg', id: 'd_temp' },
+];
+
+const matrix = [];
+for (const theme of ['Light', 'Dark']) {
+  for (const row of rows) {
+    matrix.push({
+      theme,
+      row,
+      size: 56,
+      runtime: await runtimePng(theme, row, 56),
+    });
+  }
+  for (const size of [32, 96]) {
+    const row = rows[0];
+    matrix.push({ theme, row, size, runtime: await runtimePng(theme, row, size) });
+  }
+  const textRow = rows.find((row) => row.label === 'Text');
+  matrix.push({ theme, row: textRow, size: 96, runtime: await runtimePng(theme, textRow, 96) });
+}
+
+const escapeHtml = (value) => String(value)
+  .replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const body = matrix.map(({ theme, row, size, runtime }) => {
+  const reference = referenceAsset(theme, row.file, size);
+  return `
+  <tr>
+    <td>${theme}</td><td>${escapeHtml(row.label)}</td><td>${size}px</td>
+    <td class="preview"><img style="width:${reference.displayWidth}px" src="${reference.url}" alt="Reference ${escapeHtml(row.label)}"></td>
+    <td class="preview runtime"><img src="data:image/png;base64,${runtime}" alt="Runtime ${escapeHtml(row.label)}"></td>
+  </tr>`;
+}).join('');
+const html = `<!doctype html>
+<html><head><meta charset="utf-8"><title>Device icon reference/runtime matrix</title>
+<style>
+  body{margin:24px;background:#777;color:#111;font:16px system-ui,sans-serif}
+  h1,p{max-width:1100px} table{border-collapse:collapse;width:100%;background:#aaa}
+  th,td{border:1px solid #555;padding:8px;text-align:left} th{position:sticky;top:0;background:#ddd;z-index:2}
+  .preview{width:38%;text-align:center;background:linear-gradient(135deg,#d5d5d5 50%,#666 50%)}
+  .preview img{display:block;margin:auto;max-width:300px;max-height:180px}.runtime img{image-rendering:auto}
+</style></head><body>
+<h1>House Plan device icons: package 1.1.1 vs runtime</h1>
+<p>Issues #211/#217. Reference SVG is loaded directly from the designer package; Runtime is a fresh browser capture. Default covers 32/56/96 px and Text has an additional large 96 px row so its outer stadium curvature is reviewable. Dark Unlock is evaluated using the owner's amber override from #179.</p>
+<table><thead><tr><th>Theme</th><th>State/layout</th><th>Core</th><th>Reference SVG</th><th>Runtime</th></tr></thead>
+<tbody>${body}</tbody></table></body></html>`;
+const htmlPath = resolve(artifactDir, 'device-icons-reference-runtime.html');
+writeFileSync(htmlPath, html);
+
+await page.setViewportSize({ width: 1600, height: 1000 });
+await page.setContent(html, { waitUntil: 'load' });
+await page.screenshot({
+  path: resolve(artifactDir, 'device-icons-reference-runtime.png'),
+  fullPage: true,
+});
+await browser.close();
+console.log(`OK device icon reference/runtime matrix: ${htmlPath}`);

demo/capture_wall_strip_backup.mjs

@@ -0,0 +1,85 @@
+/** Local-only visual proof for #275; external backup contents are never printed. */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { optimizePlans } from '../test-build/plan-optimizer.js';
+import { launch } from './serve.mjs';
+
+const input = process.argv[2];
+const outputDir = resolve(process.argv[3] || '.');
+const mode = process.argv.includes('--optimized') ? 'optimized' : 'raw';
+const nodesArg = process.argv.find((value) => value.startsWith('--nodes='))?.slice(8) || '';
+const nodes = nodesArg.split(';').filter(Boolean).map((pair) => pair.split(',').map(Number));
+if (!input) {
+  console.error('usage: node demo/capture_wall_strip_backup.mjs <backup> <outdir> '
+    + '[--optimized] [--nodes=x,y;x,y]');
+  process.exit(2);
+}
+
+const backup = JSON.parse(readFileSync(input, 'utf8'));
+const payload = backup?.payload && typeof backup.payload === 'object' ? backup.payload : backup;
+const source = {
+  config: payload?.config && typeof payload.config === 'object' ? payload.config : payload,
+  layout: payload?.layout && typeof payload.layout === 'object' ? payload.layout : {},
+};
+const rendered = mode === 'optimized'
+  ? optimizePlans(source.config, source.layout)
+  : source;
+const config = rendered.config;
+const layout = rendered.layout;
+if (!Array.isArray(config?.spaces) || !config.spaces.length) {
+  throw new Error('backup has no spaces');
+}
+
+mkdirSync(outputDir, { recursive: true });
+const { page, browser } = await launch({ width: 1800, height: 1250 }, 1);
+await page.emulateMedia({ reducedMotion: 'reduce' });
+await page.evaluate(async ({ cfg, lay }) => {
+  const card = window.__card;
+  card._serverCfg = structuredClone(cfg);
+  card._layout = structuredClone(lay);
+  card._space = cfg.spaces[0].id;
+  card._setMode('plan');
+  card._tool = 'select';
+  card._cfgEpoch++;
+  card._modelCache = null;
+  card._frame = null;
+  card._wallUnionCache = null;
+  card._physicalBodiesCache = null;
+  card._lightBarrierCache = null;
+  card._isoGeometryCache.clear();
+  card.requestUpdate();
+  await card.updateComplete;
+  card._fitAll();
+  card.requestUpdate();
+  await card.updateComplete;
+  await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+}, { cfg: config, lay: layout });
+
+const fullPath = resolve(outputDir, `${mode}-full.png`);
+await page.screenshot({ path: fullPath, animations: 'disabled' });
+for (let index = 0; index < nodes.length; index++) {
+  const center = await page.evaluate(([x, y]) => {
+    const card = window.__card;
+    const svg = (card.shadowRoot || card.renderRoot).querySelector('.stage svg');
+    const matrix = svg?.getScreenCTM?.();
+    if (!matrix) return null;
+    const point = new DOMPoint(x * 1000, y * 1000).matrixTransform(matrix);
+    return { x: point.x, y: point.y };
+  }, nodes[index]);
+  if (!center) continue;
+  const width = 420, height = 360;
+  const clip = {
+    x: Math.max(0, Math.min(1800 - width, center.x - width / 2)),
+    y: Math.max(0, Math.min(1250 - height, center.y - height / 2)),
+    width,
+    height,
+  };
+  await page.screenshot({
+    path: resolve(outputDir, `${mode}-node-${index + 1}.png`),
+    clip,
+    animations: 'disabled',
+  });
+}
+await browser.close();
+console.log(JSON.stringify({ mode, full: fullPath, crops: nodes.length }));

demo/docs/capture.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { visualFingerprint } from '../../scripts/source-fingerprint.mjs';
+import { assertFreshDemoBundle } from '../bundle-freshness.mjs';
+import { goldenClip, prepareGoldenScenario } from '../golden/harness.mjs';
+import { launch } from '../serve.mjs';
+import { DOC_SCREENSHOT_VERSION, DOC_SCREENSHOTS } from './screenshots.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const OUTPUT = resolve(ROOT, 'docs/images');
+const BUNDLE = resolve(ROOT, 'dist/houseplan-card.js');
+const DEMO_BUNDLE = resolve(ROOT, 'demo/srv/assets/houseplan-card.js');
+const INTEGRATION_BUNDLE = resolve(ROOT, 'custom_components/houseplan/frontend/houseplan-card.js');
+const SCRIPT = fileURLToPath(import.meta.url);
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+
+
+const roomCardClip = (page) => page.evaluate(() => {
+  const card = window.__goldenCard;
+  const roomCards = [...(card?.renderRoot?.querySelectorAll('.roomlabel') || [])];
+  const target = roomCards.find((item) => item.querySelector('.rlm')) || roomCards[0];
+  if (!target) throw new Error('documentation room card is missing');
+  const rect = target.getBoundingClientRect();
+  const marginX = 80;
+  const marginY = 70;
+  return {
+    x: Math.max(0, rect.left - marginX),
+    y: Math.max(0, rect.top - marginY),
+    width: Math.min(innerWidth, rect.right + marginX) - Math.max(0, rect.left - marginX),
+    height: Math.min(innerHeight, rect.bottom + marginY) - Math.max(0, rect.top - marginY),
+  };
+});
+
+/**
+ * Documentation-only presentation state. Keep these mutations out of the
+ * golden harness: changing that release fixture would invalidate every visual
+ * baseline even though the production component and golden matrix are intact.
+ */
+const applyDocumentationState = (page, scenario) => page.evaluate(async (current) => {
+  const frame = () => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+  const card = window.__goldenCard;
+  if (!card) throw new Error(`documentation card is missing: ${current.id}`);
+
+  if (current.title) {
+    card.setConfig({ ...card._config, title: current.title });
+  }
+
+  if (current.roomMetrics) {
+    const space = card._serverCfg?.spaces?.find((item) => item.id === current.space);
+    if (!space) throw new Error(`documentation room metrics space is missing: ${current.space}`);
+    space.settings = {
+      ...(space.settings || {}),
+      label_temp: true,
+      label_hum: true,
+      label_lqi: true,
+      label_light: true,
+    };
+    card._cfgEpoch += 1;
+    card._modelCache = null;
+  }
+
+  if (current.fixture === 'empty') {
+    card._serverCfg = { ...(card._serverCfg || {}), spaces: [] };
+    card._cfgEpoch += 1;
+    card._modelCache = null;
+    card._space = '';
+    card._onboardingShown = true;
+    card.hass = { ...card.hass, floors: {} };
+    card._openSpaceDialog('create');
+  }
+
+  if (current.dialog === 'device-info') {
+    const device = card._devices.find((item) => item.id === current.deviceId);
+    if (!device) throw new Error(`documentation device is missing: ${current.deviceId}`);
+    card._infoCard = device;
+  }
+
+  card.requestUpdate();
+  await card.updateComplete;
+  await frame();
+
+  if (current.devicePresentationPreview) {
+    const dialog = card.renderRoot.querySelector('hp-dialog');
+    const body = dialog?.querySelector('.body');
+    const preview = dialog?.querySelector('hp-device-preview');
+    await preview?.updateComplete;
+    if (!body || !preview)
+      throw new Error('documentation device presentation preview is missing');
+    const bodyRect = body.getBoundingClientRect();
+    const previewRect = preview.getBoundingClientRect();
+    body.scrollTop += previewRect.top - bodyRect.top - 180;
+    await frame();
+    const visibleBody = body.getBoundingClientRect();
+    const visiblePreview = preview.getBoundingClientRect();
+    if (visiblePreview.top < visibleBody.top - 1 || visiblePreview.bottom > visibleBody.bottom + 1)
+      throw new Error('documentation viewport does not show the device presentation preview');
+  }
+
+  return { dialog: !!card.renderRoot.querySelector('hp-dialog') };
+}, scenario);
+
+mkdirSync(OUTPUT, { recursive: true });
+copyFileSync(BUNDLE, DEMO_BUNDLE);
+copyFileSync(BUNDLE, INTEGRATION_BUNDLE);
+
+const { page, browser } = await launch();
+const browserErrors = [];
+page.on('pageerror', (error) => browserErrors.push(error.message));
+
+try {
+  // Свежесть бандла проверяется строго, вместе с версией: картинки обязаны
+  // приехать из бандла, собранного из ЭТОГО дерева. А в манифест пишется
+  // версионно-нечувствительный отпечаток (#245) — номер версии на скриншотах
+  // не виден, и требовать из-за него пересъёмки нечестно.
+  await assertFreshDemoBundle(page, ROOT);
+  const fingerprint = visualFingerprint(ROOT);
+  const scenarios = {};
+  for (const scenario of DOC_SCREENSHOTS) {
+    await prepareGoldenScenario(page, scenario);
+    const runtime = await applyDocumentationState(page, scenario);
+    if (scenario.expectDialog && !runtime.dialog)
+      throw new Error(`documentation scenario did not open its dialog: ${scenario.id}`);
+    const clip = scenario.capture === 'room-card'
+      ? await roomCardClip(page)
+      : await goldenClip(page, scenario.capture);
+    const image = await page.screenshot({
+      ...(clip ? { clip } : {}), animations: 'disabled', caret: 'hide', scale: 'css',
+    });
+    writeFileSync(resolve(OUTPUT, scenario.file), image);
+    scenarios[scenario.id] = {
+      file: scenario.file,
+      viewport: scenario.viewport,
+      theme: scenario.theme,
+      language: scenario.language,
+      sourceSha256: fingerprint,
+      imageSha256: sha256(image),
+    };
+    console.log(`captured ${scenario.id} -> docs/images/${scenario.file}`);
+  }
+  if (browserErrors.length) throw new Error(`browser errors: ${browserErrors.join(' | ')}`);
+  const manifest = {
+    version: DOC_SCREENSHOT_VERSION,
+    fixture: 'synthetic-only',
+    // Кто снимал. Смена браузера переписывает все картинки без содержательных
+    // изменений (#246), поэтому окружение съёмки — часть доказательства.
+    chromium: browser.version(),
+    sourceFingerprint: fingerprint,
+    captureScriptSha256: sha256(readFileSync(SCRIPT)),
+    command: 'npm run build && node demo/docs/capture.mjs',
+    scenarios,
+  };
+  writeFileSync(resolve(OUTPUT, 'screenshots.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+} finally {
+  await browser.close();
+}

demo/docs/screenshots.mjs

@@ -0,0 +1,75 @@
+/**
+ * Каталог сценариев съёмки документации. Отдельным модулем, потому что его
+ * читают трое: сам капчур, `scripts/check-docs.mjs` и приёмка артефакта
+ * `scripts/docs-accept.mjs` (#246). Импортировать его из `capture.mjs` нельзя —
+ * тот скрипт при импорте поднимает браузер и снимает картинки.
+ */
+export const DOC_SCREENSHOT_VERSION = 1;
+export const DOC_SCREENSHOTS = Object.freeze([
+  {
+    id: 'view-desktop', file: '01-view-desktop.png', fixture: 'visual',
+    space: 'golden-lighting', mode: 'view', roomMetrics: true,
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 900 }, capture: 'page',
+  },
+  {
+    id: 'view-touch', file: '02-view-touch.png', fixture: 'visual',
+    space: 'golden-lighting', mode: 'view', roomMetrics: true, kiosk: true,
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 390, height: 760 }, capture: 'page',
+  },
+  {
+    id: 'space-create', file: '03-space-create.png', fixture: 'empty', noFloors: true,
+    title: 'House Plan', language: 'en', theme: 'dark',
+    viewport: { width: 900, height: 850 }, capture: 'page', expectDialog: true,
+  },
+  {
+    id: 'room-contour-close', file: '04-room-contour-close.png', fixture: 'visual',
+    space: 'golden-geometry', mode: 'plan',
+    wallJunctionPreview: {
+      path: [[0.18, 0.18], [0.40, 0.18], [0.40, 0.40], [0.18, 0.40]],
+      pointer: [0.18, 0.18], cms: [440, 440, 440], cm: 15,
+    },
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 900 }, capture: 'page',
+  },
+  {
+    id: 'plan-context-tray', file: '05-plan-context-tray.png', fixture: 'visual',
+    space: 'golden-geometry', mode: 'plan', editorTray: 'plan-selection',
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 900 }, capture: 'page',
+  },
+  {
+    id: 'device-editor', file: '06-device-editor.png', fixture: 'visual',
+    space: 'golden-lighting', dialog: 'device', deviceId: 'golden-light-two',
+    deviceName: 'Living-room ceiling light',
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 1100 }, capture: 'page', expectDialog: true,
+  },
+  {
+    id: 'device-display-preview', file: '06-device-display-preview.png', fixture: 'visual',
+    space: 'golden-lighting', dialog: 'device', deviceId: 'golden-light-two',
+    deviceName: 'Living-room ceiling light', devicePresentationPreview: true,
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 1100 }, capture: 'page', expectDialog: true,
+  },
+  {
+    id: 'background-editor', file: '07-background-editor.png', fixture: 'visual',
+    space: 'golden-geometry', mode: 'decor', editorTray: 'decor-selection',
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 900 }, capture: 'page',
+  },
+  {
+    id: 'room-card', file: '08-room-card.png', fixture: 'visual',
+    space: 'golden-lighting', mode: 'view', roomMetrics: true,
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1180, height: 900 }, capture: 'room-card',
+  },
+  {
+    id: 'device-info', file: '09-device-info.png', fixture: 'visual',
+    space: 'golden-lighting', mode: 'view', dialog: 'device-info',
+    deviceId: 'golden-light-two', deviceName: 'Living-room ceiling light',
+    title: 'House Plan — synthetic home', language: 'en', theme: 'dark',
+    viewport: { width: 1000, height: 900 }, capture: 'page', expectDialog: true,
+  },
+]);

demo/downgrade_open_passage.mjs

@@ -0,0 +1,59 @@
+// AC-13 for #157. Usage:
+//   node demo/downgrade_open_passage.mjs --bundle=/absolute/v1.64.0/dist/houseplan-card.js
+// The v1.64.0 frontend does not understand `passage`; this executable fixture
+// pins its documented best-effort fallback (door symbol) and, critically,
+// rejects any pageerror/unhandled exception while reading the newer literal.
+import { cpSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { launch, checkAll, finish } from './serve.mjs';
+
+const value = process.argv.find((arg) => arg.startsWith('--bundle='))?.slice('--bundle='.length);
+if (!value) {
+  console.error('usage: node demo/downgrade_open_passage.mjs --bundle=/absolute/v1.64.0/houseplan-card.js');
+  process.exit(2);
+}
+const bundle = isAbsolute(value) ? value : resolve(value);
+if (!existsSync(bundle)) {
+  console.error(`v1.64.0 bundle not found: ${bundle}`);
+  process.exit(2);
+}
+
+const currentDemo = fileURLToPath(new URL('./srv', import.meta.url));
+const serveRoot = mkdtempSync(join(tmpdir(), 'hp-157-downgrade-'));
+let browser;
+try {
+  cpSync(currentDemo, serveRoot, { recursive: true });
+  cpSync(bundle, join(serveRoot, 'assets', 'houseplan-card.js'));
+  const launched = await launch(undefined, 1, [], {}, serveRoot);
+  browser = launched.browser;
+  const out = await launched.page.evaluate(async () => {
+    const card = window.__card;
+    const root = () => card.shadowRoot || card.renderRoot;
+    const space = card._serverCfg.spaces.find((item) => item.id === card._space);
+    space.openings = [{
+      id: 'future-passage', type: 'passage', x: 0.3, y: 0.14,
+      angle: 0, length: 0.09, future_material: 'stone',
+    }];
+    card._setMode('plan');
+    card._cfgEpoch++;
+    card.requestUpdate();
+    await card.updateComplete;
+    await new Promise((resolveFrame) => requestAnimationFrame(() => requestAnimationFrame(resolveFrame)));
+    const opening = root().querySelector('[data-hp="opening"][data-id="future-passage"]');
+    const stored = space.openings[0];
+    return {
+      newerLiteralLoads: !!opening,
+      documentedDoorFallback: !!opening?.querySelector('.op-leaf,.op-arc'),
+      readDoesNotRewriteConfig: stored.type === 'passage'
+        && stored.future_material === 'stone' && space.openings.length === 1,
+    };
+  });
+  checkAll(out);
+  await finish(browser, out);
+  browser = undefined;
+} finally {
+  await browser?.close?.();
+  rmSync(serveRoot, { recursive: true, force: true });
+}

demo/fixtures/large-house.mjs

@@ -0,0 +1,246 @@
+/**
+ * Deterministic, fictional high-load fixture shared by performance and future
+ * visual-regression tooling. Nothing here depends on a real HA installation.
+ */
+
+import { fixtureWallKey } from './wall-key.mjs';
+
+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,
+      // The key must be the real one. A label like `perf-wall-0-3` does not
+      // parse as coordinates, so neither the exact match nor the tolerant
+      // fallback in lookupWall finds the record: every solid edge of this
+      // fixture resolved to zero thickness and the plan carried no wall bodies
+      // at all, while the same fixture backs four golden scenes and all six
+      // performance budgets (#260).
+      walls: segments.map((wall) => ({
+        key: fixtureWallKey(wall.a, wall.b), 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,266 @@
+/** 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 — and a
+// key that merely differs in precision is found only through the tolerant
+// fallback in lookupWall, which is luck rather than contract (#260). The
+// formula lives in one place for every fixture and is pinned to the product one
+// by test/fixture-wall-key.test.mjs.
+export { fixtureWallKey } from './wall-key.mjs';
+import { fixtureWallKey } from './wall-key.mjs';
+
+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 applianceRooms = [
+  { id: 'appliance-room', name: 'Laundry', area: 'golden_appliance',
+    poly: [[0.08, 0.10], [0.92, 0.10], [0.92, 0.90], [0.08, 0.90]] },
+];
+
+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 applianceSpace = {
+  id: 'golden-appliance',
+  title: 'Appliance lifecycle',
+  plan_url: null,
+  view_box: [0, 0, 1, 1],
+  cell_cm: 5,
+  settings: {
+    fill_mode: 'none', glow_enabled: false, show_borders: true, show_names: true,
+    sun_rays: false, bg_mode: 'static',
+  },
+  rooms: applianceRooms,
+  walls: wallsFor('appliance', applianceRooms, 15),
+  openings: [],
+  partitions: [],
+  wall_columns: [],
+  decor: [],
+};
+
+const runtime = (includeAppliance = false) => {
+  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, ...(includeAppliance ? applianceRooms : [])]
+      .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',
+  });
+
+  if (includeAppliance) {
+    const washerId = 'golden-washer';
+    devices[washerId] = {
+      id: washerId,
+      name: 'Golden washing machine',
+      model: 'GOLDEN-WASHER-COMPOSITE',
+      area_id: 'golden_appliance',
+      identifiers: [['houseplan_golden', washerId]],
+      config_entries: ['golden_entry'],
+      entry_type: null,
+      via_device_id: null,
+      disabled_by: null,
+    };
+    const addWasherEntity = (entityId, state, attributes = {}, registry = {}) => {
+      entities[entityId] = {
+        entity_id: entityId,
+        device_id: washerId,
+        platform: 'houseplan_golden',
+        config_entry_id: 'golden_entry',
+        disabled_by: null,
+        ...registry,
+      };
+      states[entityId] = {
+        entity_id: entityId,
+        state,
+        attributes: { friendly_name: registry.original_name || entityId, ...attributes },
+      };
+    };
+    addWasherEntity('switch.golden_washer_power', 'on', {}, { original_name: 'Power' });
+    addWasherEntity('switch.golden_washer_child_lock', 'off', {}, { original_name: 'Child lock' });
+    addWasherEntity('sensor.golden_washer_status', 'done', {}, {
+      original_name: 'Status', translation_key: 'status',
+    });
+    addWasherEntity('sensor.golden_washer_stage', 'Rinse', {}, { original_name: 'Stage' });
+    addWasherEntity('sensor.golden_washer_program', 'mixed_wash', {}, { original_name: 'Program' });
+    layout[washerId] = { s: 'golden-appliance', x: 0.5, y: 0.5 };
+  }
+  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 = ({ applianceLifecycle = false } = {}) => ({
+  config: {
+    spaces: [
+      structuredClone(geometrySpace), structuredClone(lightingSpace),
+      ...(applianceLifecycle ? [structuredClone(applianceSpace)] : []),
+    ],
+    // 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(applianceLifecycle),
+  counts: applianceLifecycle ? {
+    ...VISUAL_MATRIX_COUNTS,
+    spaces: VISUAL_MATRIX_COUNTS.spaces + 1,
+    rooms: VISUAL_MATRIX_COUNTS.rooms + applianceRooms.length,
+  } : VISUAL_MATRIX_COUNTS,
+});

demo/fixtures/wall-key.mjs

@@ -0,0 +1,63 @@
+/**
+ * Ключ записи толщины стены — один на все фикстуры проекта.
+ *
+ * Копия формулы из `src/wall-thickness.ts`, и копия здесь неизбежна. Фикстуры
+ * обязаны оставаться без внешних импортов: бэкенд-гейт запускает их как
+ * `node --input-type=module --eval "import * as f from './demo/fixtures/…'"`
+ * в job без `npm ci` и без `test-build/` (`.github/workflows/validate.yml`,
+ * job `backend`), а `scripts/source-fingerprint.mjs` хеширует только `src/**`
+ * и `.mjs` из `demo/fixtures` и `demo/golden` — код, втянутый из `scripts/`,
+ * менял бы поведение фикстуры при неизменном отпечатке, на котором стоят и
+ * валидность golden-эталонов, и переиспользование гейтов.
+ *
+ * Поэтому файл лежит ЗДЕСЬ, внутри `demo/fixtures`: так он попадает в
+ * отпечаток, и так его видит одна привязка вместо трёх копий формулы.
+ * `test/fixture-wall-key.test.mjs` сверяет его с продуктовым `wallKey`.
+ *
+ * Ловушка, из-за которой этот файл и появился (#260): точность зависит от шага.
+ * При `pitch = 1/240` продукт печатает ШЕСТЬ знаков, а не четыре — фикстура с
+ * четырьмя расходилась с продуктом на каждой записи и находилась только через
+ * терпимый запас `lookupWall`. Метка вместо ключа (`perf-wall-0-3`) не
+ * находилась вовсе: все сплошные рёбра оставались с нулевой толщиной.
+ */
+
+/** Шаг решётки редактора в нормализованных координатах (`GRID_N = 240`). */
+export const WALL_KEY_PITCH = 1 / 240;
+
+/** Направление стены по модулю 180°: стена одна и та же с любого конца. */
+const direction = (a, b) => {
+  let dx = b[0] - a[0], dy = b[1] - a[1];
+  const length = Math.hypot(dx, dy);
+  if (length < 1e-12) return [1, 0];
+  dx /= length; dy /= length;
+  if (dx < -1e-12 || (Math.abs(dx) <= 1e-12 && dy < 0)) return [-dx, -dy];
+  return [dx, dy];
+};
+
+/**
+ * Координата, отличающаяся от узла решётки не больше точности хранения, — это
+ * тот же узел (#258). Канонизация опознания, а не снап геометрии: произвольная
+ * точка вне решётки остаётся вне решётки. Без этого шага ничья округления на
+ * стене нечётной длины в шагах разводила один и тот же ключ на два.
+ */
+const keyEpsilon = (pitch) => Math.max(Math.abs(pitch) * 1e-6, 1e-9);
+const canonical = (value, pitch) => {
+  if (!(pitch > 0) || !Number.isFinite(value)) return value;
+  const snapped = Math.round(value / pitch) * pitch;
+  return Math.abs(snapped - value) <= keyEpsilon(pitch) ? snapped : value;
+};
+
+export const fixtureWallKey = (a, b, pitch = WALL_KEY_PITCH) => {
+  const quantise = (value) => (pitch > 0 && Number.isFinite(value)
+    ? Math.round(value / pitch) * pitch : value);
+  const ca = [canonical(a[0], pitch), canonical(a[1], pitch)];
+  const cb = [canonical(b[0], pitch), canonical(b[1], pitch)];
+  const mx = quantise((ca[0] + cb[0]) / 2);
+  const my = quantise((ca[1] + cb[1]) / 2);
+  const [dx, dy] = direction(ca, cb);
+  let angle = Math.atan2(dy, dx);
+  if (angle < 0) angle += Math.PI;
+  const bucket = Math.round(angle * 1800) / 1800;
+  const precision = pitch > 0 && pitch < 0.01 ? 6 : pitch < 1 ? 4 : 2;
+  return `${mx.toFixed(precision)},${my.toFixed(precision)}@${bucket.toFixed(4)}`;
+};

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
+npm run bundle:sync
+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,138 @@
+{
+  "schema": 1,
+  "matrixVersion": 46,
+  "acceptedAt": "2026-08-25T20:12:50.448Z",
+  "sourceFingerprint": "e28606975682347f90f12971053825ce474085cbddd56082e867370b1039d14d",
+  "chromium": "151.0.7922.34",
+  "scenarios": {
+    "hidden-wall-diagnostics-plan-light": "6470ed8b09b21144ec1399389e9a57774e977a6473b8eaa7de7e9b5df3273f21",
+    "hidden-wall-diagnostics-plan-dark": "da6e725ddfad7c807408a710b78090dc222b56dcee484a29baa68b5452fc44e5",
+    "coincident-partition-before-dark": "19626db704fccb7a42b519ffb20b7bad82c726e8845c752ab451f731d264561c",
+    "coincident-partition-thin-dark": "3afede1f99b86454bf4e50d9628196a2240243e034644592c5c3efa1b4561930",
+    "coincident-partition-thick-dark": "57960bd09e6cbbeb073561692690ca68a72d6dbf8242198ef73b8d4ae4d8fbcc",
+    "coincident-partition-virtual-dark": "da7adbf931ad95f4e620d9d088177f1da20d88a21b9e85b6ff2675925d5557b4",
+    "split-corner-wall-before-dark": "3176dc67f54d5309f87c94e1077b4f69eb1db9f660469fbf97953038323430f3",
+    "split-corner-wall-thin-dark": "17e49394c300887bb5349bf477292571e96e209c9515db6853348883d95a1422",
+    "split-corner-wall-thick-dark": "f7864a6b2ab58586540f836183c9e59f09f9f57165ec0e0b9cd8444ada71153c",
+    "split-zero-divider-taper-dark": "3de38befb41f15ef4047da1390e061b1b5756340142dd9204d011287ff39be5b",
+    "isometric-geometry-view-dark": "43ad006844a78b502b36aeeb82d82669532e06d2c798de928a5207acd24bd5f9",
+    "isometric-geometry-view-light": "0fcb10ffdc0baa9006d1c2f0406ebf19e71ba9feda180979a51b74166d7200d2",
+    "isometric-live-layers-dark": "8aaa914fc45780f67dd5c008a106696d21235a9acee7402f9cc8ae51a26660f3",
+    "isometric-no-borders-dark": "c105382d883bbdae8562b756ccbf47ac1fcf46675c6aa7654289856223a3ebf0",
+    "isometric-touch-kiosk-dark": "be122ceec8114374ba384f51d5d9287e498a97354865c5a9f91d505ca18d8640",
+    "isometric-large-warm-remount-dark": "d76e3334bf80bff265b1e8aa6770c5eff5df6fbfebeb4703b04d048c4252eb68",
+    "geometry-view-dark-fit": "1b80d2d0fe84cfe15f1fa29ccc2a2dcc66b4c5e62d1722c06c00442c78979be0",
+    "geometry-view-light-fit": "91caf6621af00eb0cd16589e2fc79976cdca1e8467d0e86151ecbc46948612d9",
+    "room-label-parity-view-dark": "7f1da43466a13f82a7595dddabe6938ed974debfb14c8f40e729e273a53ac4ff",
+    "room-label-parity-plan-dark": "5f976d5743d68a27b594e1a5ddf45e5ad3708f5c703409e5cefb7c96d3048096",
+    "room-label-parity-view-light": "ee3d303fb2b329c356a4354d355c29694130a38d4812ffbfefbe861f5d3f9860",
+    "room-label-parity-plan-light": "d32b538499a031d4310b243cc9ef43610f6cd67aabfde7cd01b59c88b0363ec5",
+    "washer-active-cycle-dark": "d74a646bc71b8d6d0d5b09e6862b4846b0e369da2520afa76d5b3d601c832a15",
+    "washer-idle-cycle-dark": "f7fae5c2f6856a3df5bd3f3028fcf829ef0039c7b43c91c27ac86d25626e8d66",
+    "day-cycle-dawn-dark": "3f32bc1ed042475516f7e239aedd7fee11717b00fa2103ae9f1231e006d64015",
+    "day-cycle-day-dark": "1a0f53c948ae669c7ab4e1dcb931c11e7c878974862637dd1f596011876a7ed4",
+    "day-cycle-dusk-dark": "ec95e99ac3c7e4d6affa2f7944759727251dc4f1b62e2855e421a7e48f7280eb",
+    "day-cycle-night-dark": "cc49dc53dabb63b7dd800eaa65c8748972fcf3c1abd948b34d1e0f973e63f0d2",
+    "geometry-plan-editor-dark": "fd8d067daa3b2a4e572dea9644486e6324318e8ea4e5f43e3df2069a05389a88",
+    "safe-resize-handles-clamp-light": "ed705040357cad043095baf12d02cc69abdc3db27ff40066a6979be85d035f77",
+    "safe-resize-handles-clamp-dark": "9d81a45f3acac787cde1b9eb74a858020fbad09670b8ff5b081869b5eca73b82",
+    "space-tab-drop-before-light": "401dded3d7fdff3e823d46eac1b3cef2d6e0eb05f48b5ea289cdd8ecd941dee0",
+    "space-tab-drop-after-dark": "a851621040e14f911b1080488f2c75e3d9bc0d5fef74fb5d0081f80b023ff0a2",
+    "plan-snap-endpoint-light": "db967076cd9fd50c2a2a1337e4ecbf4ef67cb7f800401f6227497c75415951d5",
+    "plan-snap-line-gaps-dark": "ff1b6bbf2e1b4272bb2f0e96d92136aa6960ee24acef1b63b4478e54441a4b58",
+    "wall-junctions-plan-preview-light": "fa81fa6c6dba92578a4beee5ed29f407443a3bc61affa25c44fcfefab0c7070c",
+    "wall-junctions-plan-t-dark": "f8a517d316a99ca9ee5b4ff56f515be15d440adfc551bbdaaa5e9d9a411a79bc",
+    "wall-junctions-view-dark": "7b859c4f25f8a5dd4fca64d5b2f7aa64b65845fabbe83bc2388c2f99d29f71b1",
+    "junction-patch-resilience-plan-dark": "57ea7522c438e52292f226f975bb112930976b6e072b72322180d52ec0277f4f",
+    "junction-patch-resilience-view-dark": "1f0df26ed72bcc5bef06a8366d7043ad40b4a2bb744fa5a64248c29eae968424",
+    "wall-union-isolation-view-light": "291c045758be2814be88d12ab46bdc3d12cb99a03dbbcc9a1539c2c9a5931edf",
+    "wall-union-isolation-view-dark": "616fc6cc7144c9596ae52421027914e222f30f26de45215fa7e7b6175ca78543",
+    "multiwall-junction-bevel-view-dark": "e226d023fbab0502eb747395d43a46bb56bcf2be037ba4f9b7ad74ba406d9671",
+    "orthogonal-strip-cell-5-view-dark": "9b8e4bd22cbf1a82ff48f052822967c61179290a3234ae48ef547642329b5a90",
+    "orthogonal-strip-cell-1-view-dark": "e59e51ad3645144161459c438a07420730c4dcfd2c33bd2b18e8c3e57ea84515",
+    "wall-key-roundtrip-view-dark": "df46b4e209f98b97958748097ddc646ddc64d8285c2651762de71ec2456ac690",
+    "isometric-wall-junctions-dark": "d1956cbbde9a6a02953ce80eb8a0f74ca06ea268a4c60bb09b5b3981c26d9731",
+    "opening-placement-door-thick-wall-dark": "1157139aac7325b40e3869b8c3b5444509b4bc24a415ddf6f8d5402624f3a04a",
+    "opening-placement-passage-thick-wall-dark": "6d4a9a953b70401ca11cd6ce96c2e0e0781bbfff71e758dc57958a4163e2712d",
+    "opening-placement-passage-thick-wall-light": "b004b1395652c8a8eef5f5002b471ecf8f2f0347f158a14a056ff2b7382e4ea3",
+    "opening-symbol-room-wall-light": "562fed297210ef542de608e384c2d344dddd193a5b43615930c9f76faaf53b42",
+    "opening-symbol-diagonal-partition-dark": "620102c00e77613cb341c906829bfcc7e9a5430075aa576f563adafa8bdd8f08",
+    "opening-symbol-flip-pairs-light": "33364f51fb65e49bfdd6c41d6e0c53542c89fadc45a3c6e5adc590144c4676ea",
+    "isometric-opening-symbol-parity-dark": "302daf5d90d4af5ef90036cc10e957e6fc909ea56f9f2af938ab850d4f608e34",
+    "geometry-devices-editor-dark": "4b91bdc00082e33d2529ea3cf7ce7af36383a84838f4a2c909463df24483b47b",
+    "geometry-decor-editor-dark": "8b03bc87d2353cb6ef8fb4e2dec3f0d3be85de903ac9346171ea4aaa31170a66",
+    "tray-wide-selection-en": "d140cf6a51c634a38d2e3661c4b61835d63673174fd934b85f9da0db4fa20d1a",
+    "tray-wide-tool-ru": "806ff7c5ae3d2e708a4682833af7dc28a88001ef09e4ca564c91a5e6023b297d",
+    "tray-medium-group-en": "5a1adbaa64d2b73f294003e2752a79008f7ec313ab41dd0514b6b38918b8c00e",
+    "tray-medium-selection-ru": "53c7ea5099772fd14c2e27ad414c4d57d87c020866992b7a0b0dd62a22fbeb7e",
+    "tray-narrow-palette-en": "5bc029bb7a4b077a45abc0c18f54360f781caa3684befb63cfa714efcfaf7edd",
+    "tray-narrow-tool-ru": "32e27435ec9f0ce6db2e2800ffd71b6a5fcb1ab7dde17454a3ba7dda680b8a45",
+    "geometry-diagonal-45-opening-dark": "a0167f3028cd8ef8283c92ae7e803940cf0eb0db45f1b137108a4e009741a5df",
+    "openings-thick-wall-dark": "c45bae26ec0b4f719f72e5b92e3b8e03260d7bda4b3182d4c563b50f656e68a1",
+    "openings-filled-tunnel-dark": "b916d3ce48bba7487ed4b548bf659b610243ebcde07206c21fff65867792d0d1",
+    "decor-over-opaque-hover-light": "553d279db44aa0a4a6855496036b0f6ddda9570cef133e09a30f29f41b7d0c31",
+    "decor-over-glow-base-dark": "8e5b8630798e31936f8e7dd52d1cba73a3f80fd3d3217a5ad59d50b5dc12a26d",
+    "openings-hidden-view-dark": "d99f365376e6ece668060181ce8c3a5ebdb93ec5a8c64e08b0aef5af592c6874",
+    "lighting-glow-sun-dark": "8599aea80a0479442f891adb30aecd647ddf217e28e3f0da5c21b41e21d746ec",
+    "device-value-badge-positions-dark": "ae163e96cd976e006eacd09ebc75440d600e81c063e38da27d53000e4e51c68d",
+    "device-icon-state-table-light": "969879fc7baeb193639a03701eb8bacc9469f6160b8d41a318db8da83590e51d",
+    "device-icon-state-table-dark": "045145a87ccde3894334009c6b9edd690654fd048c55b770e09d5ed79f9a7351",
+    "device-text-shell-long-light": "a96d16ac0a02ed322bab949e34ff7ce59da5f5db42e02185fac5fde495591bb1",
+    "device-text-shell-long-dark": "f301f3aa1e1eb382018c4329db2909a8d2990f5f917bde83e3de46ff4dc7416c",
+    "lighting-sun-window-state-only-dark": "4da798c4de6d1303d17be246e9a2e63b12da3f53a42136cf745d1a92ad5a4f21",
+    "lighting-fill-light-axis-split-dark": "6b3a4dd637c6fe7e43a131c44c4be232bd81edab417ea9af3860d82c506ad45f",
+    "lighting-fill-temp-axis-split-dark": "6025c6efd3ea3565c13e147db550b017eeb86da0be5dfc82a8b5bd7e623d5852",
+    "lighting-fill-lqi-axis-split-dark": "1ec5c18572fd5be471088286c4aa7c67c3885cb907080fcde44c3583ff794275",
+    "lighting-temp-glow-dark": "274bcd5a19ebbcb63fb64a5d21f838122f1916d428defcaa3c0356d8ea9809a5",
+    "lighting-temp-glow-light": "decc386073a1e93d8d457ec09daf83e8afc180977f5880ce56cc4834a2c203f0",
+    "lighting-custom-glow-dark": "32607e6001c4c8cd541cabf82142f3cbf7f2b298900a02f30c6f44ececbd5907",
+    "lighting-opaque-glow-two-doorways-dark": "bd9f49432c69c8ed622810e96f4708974e2024c58700b0cfa3e5ebd2edd7bc7b",
+    "lighting-custom-glow-light": "973ae32bb3bacbfe633041e89352a9ef1a2222b89a4792feef45c26bfa541459",
+    "lighting-temp-glow-no-sources-dark": "e19b7d86d5dae54f9afc0a1ef04a3848ebec283a5f60e68efdcc7380dff3b0a7",
+    "lighting-temp-glow-room-override-dark": "bebfc27f460cb75e32ab14076a01e3b9729763d7cecd3f457c1b696ed3e57da3",
+    "lighting-manual-auto-spill-overlap-dark": "471e39397361832a171f0309302be7d8ba4310d628e337478e23da44dc455ef8",
+    "hover-over-glow-dark": "6581433024060f773e00211d60eac7b6daffe442031ff076f861918419c71930",
+    "hover-nested-room-dark": "f05ba332a127b56c00a6a94eac727b168ed34cc3f0355f8b783827f7bf55714c",
+    "junction-t-90-equal15-dark": "fed083eaaaf1588222002c23f7edd741645c76f57c49a3db8cc5ec22af0b6e7d",
+    "junction-t-90-bar50-leg15-dark": "e981f0597a55e9e9e623dd49417f33a0ebac18d18e0e66675a9af1f2224bd152",
+    "junction-t-90-bar70-leg15-dark": "4428fbe75679fab6e57ef61c5d5097d498960e2539bb9e759e1bae9a160ef174",
+    "junction-x-90-equal15-dark": "8fe0e262e5873714f94b9a6a76ed920881bc6b267e69153039f52a7102ec55d5",
+    "junction-x-90-mixed-dark": "deabce4c2b5fa7866a4f56d25404c6a515d47437298bde114442bc80a6339560",
+    "junction-x-45-alternating-dark": "56a85069baafd6e7af921389b55b916b74cc5d76df908782013b94c2b5b87752",
+    "junction-star5-equal15-dark": "1b9714dffa3f37b9f1e8d848244c4585d38539b74fe582e8d974e2b9e8fdd01a",
+    "junction-y-60-equal50-dark": "f90d46cfe79a95bb3ec73253d0b7f77948164e90c49561d79b1e0db655cc0847",
+    "junction-acute30-mixed-dark": "9ea64ae5864295a1d93a6819efb6e210de2599030fe650913862d99f40b11a69",
+    "junction-acute15-equal50-dark": "3327caf8bc1ccddb317aa7c4c330e09c098122a4f6d2e4df64502cdc033cb2e4",
+    "junction-splay10-170-dark": "ae27454bb4213237313f1fe9e2591ada48facf20baca5517968f92aebbfb330e",
+    "junction-t-virtual-arm-dark": "d325dc112e2f56c31d4511fd586adaa92b6785fc676c2a60ed5aba69c164fd6e",
+    "junction-x-virtual-through-dark": "cce24ac9d7678959844803c6306e65ab48f723ec0375ee6d3f2dbf1c7def7be1",
+    "junction-column-node-dark": "fed083eaaaf1588222002c23f7edd741645c76f57c49a3db8cc5ec22af0b6e7d",
+    "junction-draft-end-node-dark": "6453bb8463ffdc9a42dbd7acb171c6249fe6d5beec0eae0c789e40f48e65a1f9",
+    "junction-owner-repro-dark": "23ae216c2637b8ee9ea8f852002693f74d64021a66d4494e2086a53db8ca6520",
+    "large-house-zoom-040-dark": "df1a5515089b5e470ae550ce6da31a301be5079d3f7bb9130baad99d3d7c641e",
+    "large-house-zoom-250-dark": "88c0d22686fd9ef314866d0275a5ae785781c3d671e257b2c5f790f816cd65ee",
+    "large-house-warm-remount-dark": "9a61d668c5fbc61bb370c043771cee91707b3d40378cf89f81199882820bf95c",
+    "device-dialog-desktop-en": "9739886af3104c2fe3d6d3138293e9fd1a7f480f151decc26f12bb64cab69543",
+    "device-dialog-mobile-ru": "c90be98e65c37963fd4443e413848ca68a412c9ee568d648aba76bf9232ee59d",
+    "toggle-entity-dialog-desktop-en": "f4924466de5e134c2d1f2456ff0c05f8aa8106f6b06398e87a263e3c536f16ea",
+    "toggle-entity-dialog-mobile-ru": "7d3aecd318c6c0774dd3ce1c21c0fafb1ae2be23cebed6f548fbf8bd11ab2f62",
+    "device-help-popover-light-ru": "add3275d74ced358a184ec9f864c83735f1196e2bff7d75fb3e12160cb85bfaf",
+    "decor-color-popover-mobile-ru": "51725859afc6a1e2d1b2ae8be270ab584608901623ef7e2d283b6b195644fd16",
+    "decor-color-popover-desktop-en": "8ad229fd3d433f969dc6d09c7677e9949d4f62503196bffbf17030386f7c7511",
+    "general-color-popover-desktop-en": "91c3b7ebae5146c62d172d1ce10ae9e375ed955f23e9dc860976373a334d8be5",
+    "device-ripple-color-popover-mobile-ru": "3ab12c339106004c76fe3c7741d242269e157c40ddfa29afd8f13b445b0a7023",
+    "space-room-color-popover-desktop-ru": "d66d068a1b403f88a5bd3c57f4a9e55c336767c533ddfe3ae251cc4f9da40a74",
+    "backup-full-preview-desktop-en": "c9fe8ca1cf63b9ed98e2d517a2c06639d044d460011d958573e70c6b22bd7a2f",
+    "backup-plan-only-export-desktop-en": "c48b3ccdd7d85d36f132c2d7b4c5dba94a1027e3e3f2ef495b4eb89a23f8ca33",
+    "backup-space-preview-mobile-ru": "82cd93cb495ad77b92d635b4a3715601b1ae0e5e2974edcbbd461fe872c75bad",
+    "optimize-preflight-dialog-dark-en": "6e0706b951db73c7d699173d9cd0cd3cd8857238e3d7e95bc38eeb3691f907b6",
+    "optimize-preflight-dialog-light-ru": "a96af4b4428297d2c672f0d0e8f376e81c27765ecc941781a2d3873a054e2ec3",
+    "optimize-orphan-references-dark-en": "cdf4eb8c79a9961a1e961a4eed4107d4d849ebc5b922ad88ce07befee6b65a9a",
+    "optimize-orphan-references-light-ru": "c07151ac896e43bef6150128cbef8a5798ee113083961ed8eaf97113a0b56e1e",
+    "card-editor-invalid-default-floor-light-en": "dbf251ece014cfee252e0dcb2d7c00eda66aa4b5bd125e4c83e248d4319d24b3",
+    "card-editor-invalid-default-floor-dark-ru": "422b74bb391b87e383350247ef1bc1f10ca48c8f6fe418f75bde94e62e3b8bc0",
+    "junction-309-step-dark": "f5e0e649ee19197026b87687fd3512b18536883f071348589ec3a7f0ea2a216f",
+    "junction-309-spike-dark": "98e709aa2fa58a01fe280635c6a3799e3a5f4158b2ada12c31c38818f92c4f44",
+    "junction-309-hump-dark": "abae96fd96ed8515d7b1e33b84858bdf08ac28a888898549874baa8c98202e7a"
+  }
+}