docs: review document for #107

Issue: #107
User-Visible: no

.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

@@ -1,36 +1,89 @@
 name: Announce release
 # Telegram notifications for t.me/ha_houseplan (owner request, 2026-08-07).
-# Fires on every published release, prereleases included: the workflow file
-# lives at the TAGGED commit, so it works for beta tags cut from dev as soon
-# as this file is on dev, and for stable tags once it reaches main.
-# workflow_dispatch exists purely as a connectivity test button.
+# 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: {}
-permissions: {}
+  workflow_call:
+    inputs:
+      reusable:
+        required: true
+        type: boolean
+      tag:
+        required: true
+        type: string
+      release_name:
+        required: true
+        type: string
+      url:
+        required: true
+        type: string
+      prerelease:
+        required: true
+        type: boolean
+      ref:
+        required: true
+        type: string
+    secrets:
+      TELEGRAM_BOT_TOKEN:
+        required: true
+      TELEGRAM_CHAT_ID:
+        required: true
+permissions:
+  contents: read
 jobs:
   telegram:
+    if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'release' && github.event.release.prerelease == false) || (github.event_name == 'workflow_call' && inputs.prerelease == false) }}
     runs-on: ubuntu-latest
     steps:
+      - name: Check out release notes for a reusable call
+        if: ${{ inputs.reusable == true }}
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
       - name: Send to Telegram
         env:
           TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
           CHAT: ${{ secrets.TELEGRAM_CHAT_ID }}
-          TAG: ${{ github.event.release.tag_name }}
-          NAME: ${{ github.event.release.name }}
-          URL: ${{ github.event.release.html_url }}
-          PRE: ${{ github.event.release.prerelease }}
+          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.
-          BODY: ${{ github.event.release.body }}
+          RELEASE_BODY: ${{ github.event.release.body }}
           EVENT: ${{ github.event_name }}
         run: |
           set -euo pipefail
-          if [ "$EVENT" = "workflow_dispatch" ]; then
+          if [ "$EVENT" = "workflow_dispatch" ] && [ "$CALLED" != "true" ]; then
             TEXT="✅ Тест: оповещения о релизах houseplan-card подключены."
           else
-            KIND=$([ "$PRE" = "true" ] && echo "🧪 Пре-релиз" || echo "🏠 Релиз")
+            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")

.github/workflows/mutation-gate.yml

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

.github/workflows/performance.yml

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

.github/workflows/process.yml

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

.github/workflows/publish-prerelease.yml

@@ -0,0 +1,259 @@
+name: Publish prerelease
+run-name: Publish ${{ inputs.tag }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Exact prerelease tag, for example v1.61.0-beta.4"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  actions: read
+
+concurrency:
+  group: publish-prerelease-${{ inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      sha: ${{ steps.candidate.outputs.sha }}
+      tag: ${{ steps.candidate.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Pin the current dev candidate
+        id: candidate
+        env:
+          TAG: ${{ inputs.tag }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          test "$REF_NAME" = "dev" || {
+            echo "::error::Prereleases must be dispatched from the dev branch, got $REF_NAME"
+            exit 1
+          }
+          SHA=$(git rev-parse HEAD)
+          git fetch origin dev
+          test "$(git rev-parse origin/dev)" = "$SHA" || {
+            echo "::error::The dispatched SHA is no longer the origin/dev tip"
+            exit 1
+          }
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+      - name: Verify version, changelogs and bilingual release notes
+        env:
+          TAG: ${{ inputs.tag }}
+        run: node scripts/release-contract.mjs "$TAG" --repo="$GITHUB_REPOSITORY"
+      - name: Require green Validate for this exact SHA
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ steps.candidate.outputs.sha }}
+        run: node scripts/release-gate.mjs "$SHA"
+
+  publish:
+    needs: gate
+    runs-on: ubuntu-latest
+    outputs:
+      url: ${{ steps.verify.outputs.url }}
+      newly_published: ${{ steps.release.outputs.newly_published }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.gate.outputs.sha }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Build and verify both release assets before publication
+        env:
+          TAG: ${{ needs.gate.outputs.tag }}
+        run: |
+          set -euo pipefail
+          npm ci
+          npm run build
+          cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js
+          cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+          VERSION=${TAG#v}
+          grep -Fq "$VERSION" dist/houseplan-card.js
+          (cd custom_components/houseplan && zip -qr ../../houseplan.zip .)
+          unzip -l houseplan.zip | grep -q "manifest.json"
+          ZIP_VERSION=$(unzip -p houseplan.zip manifest.json | node -e \
+            "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>process.stdout.write(JSON.parse(s).version))")
+          test "$ZIP_VERSION" = "$VERSION" || {
+            echo "::error::houseplan.zip manifest version $ZIP_VERSION != $VERSION"
+            exit 1
+          }
+          test -s dist/houseplan-card.js
+          test -s houseplan.zip
+      - name: Create or verify the annotated tag
+        env:
+          TAG: ${{ needs.gate.outputs.tag }}
+          SHA: ${{ needs.gate.outputs.sha }}
+        run: |
+          set -euo pipefail
+          REMOTE=$(git ls-remote --tags origin "refs/tags/$TAG" "refs/tags/$TAG^{}")
+          if [ -n "$REMOTE" ]; then
+            PEELED=$(printf '%s\n' "$REMOTE" | awk -v ref="refs/tags/$TAG^{}" '$2 == ref {print $1}')
+            test -n "$PEELED" || {
+              echo "::error::Existing remote tag $TAG is not annotated"
+              exit 1
+            }
+            test "$PEELED" = "$SHA" || {
+              echo "::error::Existing tag $TAG points to $PEELED, expected $SHA"
+              exit 1
+            }
+            git fetch --force origin "refs/tags/$TAG:refs/tags/$TAG"
+            test "$(git cat-file -t "refs/tags/$TAG")" = "tag"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git tag -a "$TAG" "$SHA" -m "$TAG"
+            git push origin "$TAG"
+          fi
+      - name: Stage, verify and publish the prerelease
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.gate.outputs.tag }}
+        run: |
+          set -euo pipefail
+          if ! gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag \
+              --draft --prerelease --title "$TAG" --notes-file docs/RELEASE-NOTES.md
+          fi
+          WAS_DRAFT=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" --json isDraft --jq .isDraft)
+          echo "newly_published=$WAS_DRAFT" >> "$GITHUB_OUTPUT"
+          gh release upload "$TAG" dist/houseplan-card.js houseplan.zip \
+            --repo "$GITHUB_REPOSITORY" --clobber
+          RELEASE_JSON=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --json tagName,isDraft,isPrerelease,assets,url)
+          export RELEASE_JSON TAG
+          node <<'NODE'
+          const release = JSON.parse(process.env.RELEASE_JSON);
+          if (release.tagName !== process.env.TAG) throw new Error('release tag mismatch');
+          const assets = new Map(release.assets.map((asset) => [asset.name, asset]));
+          for (const name of ['houseplan-card.js', 'houseplan.zip']) {
+            if (!(Number(assets.get(name)?.size) > 0)) throw new Error(`${name} is missing or empty`);
+          }
+          NODE
+          gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --draft=false --prerelease \
+            --title "$TAG" --notes-file docs/RELEASE-NOTES.md
+      - name: Verify the public release and assets
+        id: verify
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.gate.outputs.tag }}
+          SHA: ${{ needs.gate.outputs.sha }}
+        run: |
+          set -euo pipefail
+          RELEASE_JSON=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --json tagName,isDraft,isPrerelease,assets,url)
+          export RELEASE_JSON TAG
+          node <<'NODE'
+          const release = JSON.parse(process.env.RELEASE_JSON);
+          if (release.tagName !== process.env.TAG || release.isDraft || !release.isPrerelease)
+            throw new Error('release is not a public prerelease for the requested tag');
+          const assets = new Map(release.assets.map((asset) => [asset.name, asset]));
+          for (const name of ['houseplan-card.js', 'houseplan.zip']) {
+            if (!(Number(assets.get(name)?.size) > 0)) throw new Error(`${name} is missing or empty`);
+          }
+          NODE
+          test "$(git rev-list -n 1 "$TAG")" = "$SHA"
+          URL=$(node -p "JSON.parse(process.env.RELEASE_JSON).url")
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+          printf '### Published %s\n\n- exact SHA: `%s`\n- [GitHub prerelease](%s)\n- assets: `houseplan-card.js`, `houseplan.zip`\n' \
+            "$TAG" "$SHA" "$URL" >> "$GITHUB_STEP_SUMMARY"
+      - name: Verify HACS prerelease discovery order
+        uses: actions/github-script@v7
+        env:
+          EXPECTED_TAG: ${{ needs.gate.outputs.tag }}
+        with:
+          script: |
+            const releases = await github.paginate(github.rest.repos.listReleases, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              per_page: 100,
+            });
+            const first = releases.find((release) => release.prerelease && !release.draft);
+            if (first?.tag_name !== process.env.EXPECTED_TAG) {
+              core.setFailed(
+                `HACS prerelease discovery is stale: ${first?.tag_name ?? 'none'} precedes ` +
+                process.env.EXPECTED_TAG,
+              );
+            }
+
+  # PROCESS.md 10.2 item 10: closing issues and stripping status labels happens
+  # because a beta was published, not because someone remembered to do it. The
+  # manual step was skipped twice, and both times it broke the invariant that a
+  # closed issue carries no status label — the one thing `verify` relies on.
+  #
+  # A manual step after a successful release is the worst kind: by the time it is
+  # due, the work already looks finished, which is exactly why it gets forgotten.
+  close-merged:
+    needs: [gate, publish]
+    if: ${{ needs.publish.outputs.newly_published == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Deliberately the stock token, not a PAT: events caused by GITHUB_TOKEN do
+      # not start workflows, so removing the label cannot wake the review
+      # pipeline. A PAT here would build a cascade out of a bookkeeping step.
+      issues: write
+    steps:
+      - name: Close the S8-merged queue and strip status labels
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ needs.gate.outputs.tag }}
+          URL: ${{ needs.publish.outputs.url }}
+        run: |
+          set -euo pipefail
+          # Only the owner's issues take part in the process; issues filed by
+          # anyone else never carry status labels and are not ours to close.
+          numbers=$(gh issue list --repo "$REPO" --state open --label S8-merged \
+            --author Matysh --limit 100 --json number --jq '.[].number')
+          if [ -z "$numbers" ]; then
+            echo "the S8-merged queue is empty, nothing to close"
+          else
+            for n in $numbers; do
+              gh issue comment "$n" --repo "$REPO" \
+                --body "Выпущено в \`$TAG\` · [релиз]($URL)"
+              # Label first, then close. If the run dies between the two steps an
+              # open issue without a status is visible and fixable in the flow;
+              # the reverse order would recreate the exact breakage this job is
+              # here to prevent.
+              gh issue edit "$n" --repo "$REPO" --remove-label S8-merged
+              gh issue close "$n" --repo "$REPO" --reason completed
+              echo "closed #$n"
+            done
+          fi
+          # Targeted at the defect that actually recurs, not at the invariant in
+          # general: no closed issue may still carry S8-merged.
+          leftover=$(gh issue list --repo "$REPO" --state closed --label S8-merged \
+            --limit 100 --json number --jq 'length')
+          test "$leftover" = "0" || {
+            echo "::error::$leftover closed issues still carry S8-merged"
+            exit 1
+          }
+
+  announce:
+    needs: [gate, publish]
+    if: ${{ needs.publish.outputs.newly_published == 'true' }}
+    uses: ./.github/workflows/announce.yml
+    with:
+      reusable: true
+      tag: ${{ needs.gate.outputs.tag }}
+      release_name: ${{ needs.gate.outputs.tag }}
+      url: ${{ needs.publish.outputs.url }}
+      prerelease: true
+      ref: ${{ needs.gate.outputs.tag }}
+    secrets: inherit

.github/workflows/release.yml

@@ -34,6 +34,15 @@ 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
@@ -44,6 +53,18 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - run: npm ci && npm run build
+      - name: Verify compositor frame continuity for a stable release
+        if: ${{ !github.event.release.prerelease }}
+        run: |
+          npx playwright install --with-deps chromium
+          cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+          npm run continuity:screencast
+      - name: Upload failed continuity frames
+        if: ${{ failure() && !github.event.release.prerelease }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: continuity-screencast
+          path: artifacts/continuity-screencast
       - run: cp dist/houseplan-card.js custom_components/houseplan/frontend/
       - name: Attach card to release
         uses: softprops/action-gh-release@v2

.github/workflows/validate.yml

@@ -1,14 +1,62 @@
 name: Validate
+
 on:
   push:
     # The branch commit is the release-gate authority. An annotated tag points
-    # to the same SHA and must not duplicate every expensive browser/perf job.
+    # to the same SHA and must not duplicate the browser validation jobs.
     branches:
       - '**'
   pull_request:
-  schedule:
-    - cron: "0 4 * * 1"
+
+# A new push supersedes an unfinished validation for the same branch or PR.
+# Exact-SHA release gates never depend on an obsolete commit.
+concurrency:
+  group: validate-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
+  provenance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Validate commit trailers and hook mode
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BEFORE_SHA: ${{ github.event.before }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.sha }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          node scripts/validate-commit-provenance.mjs --check-hook-mode --github-range
+
+  # Догоняющая проверка процесса (PROCESS.md §10.3). Хуки ловят нарушение на
+  # машине автора, но их можно обойти `--no-verify`, а коммиты идут прямо в dev
+  # без PR — GitHub на своей стороне не блокирует ничего. Это последнее место,
+  # где нарушение правила №1 ловится машиной. Job независимый: краснеет сам и
+  # не роняет остальные, откат — удалить его отсюда, скрипт остаётся рабочим.
+  process-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Process gate
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BEFORE_SHA: ${{ github.event.before }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.sha }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+          TARGET_REF: ${{ github.ref }}
+          # Публичный репозиторий: штатного токена хватает на чтение issue.
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          node scripts/process-gate.mjs --github-range --issues
+
   hacs:
     runs-on: ubuntu-latest
     steps:
@@ -17,18 +65,22 @@ jobs:
         uses: hacs/action@main
         with:
           category: integration
+
   hassfest:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: Hassfest validation
         uses: home-assistant/actions/hassfest@master
+
   frontend:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with: { node-version: 22 }
+        with:
+          node-version: 22
+          cache: npm
       - run: npm ci
       - name: Typecheck
         run: npm run typecheck
@@ -40,21 +92,21 @@ jobs:
         run: |
           cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js
           cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+
   smoke:
-    # audit T2: the end-to-end layer used to run only when a human remembered.
     # Gated on `frontend` so a typecheck failure does not burn browser minutes.
     needs: frontend
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with: { node-version: 22 }
+        with:
+          node-version: 22
+          cache: npm
       - run: npm ci
       - name: Install Chromium for Playwright
         run: npx playwright install --with-deps chromium
-      - name: Build a FRESH bundle for the smokes
-        # Never depend on a previous job's artefact; build the exact source
-        # under test again before the browser suite.
+      - name: Build a fresh bundle for the smokes
         run: npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
       - name: Smoke suite
         run: |
@@ -79,15 +131,16 @@ jobs:
           path: /tmp/smoke-logs
 
   golden:
-    # Separate deterministic pixel layer. Before the first reviewed baseline
-    # set it captures candidates; once baselines exist the same job becomes a
-    # blocking comparison and uploads actual/diff/report on failure.
+    # Deterministic visual correctness stays in every prerelease gate: it is
+    # inexpensive and catches a different class of regressions than timings.
     needs: frontend
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with: { node-version: 22 }
+        with:
+          node-version: 22
+          cache: npm
       - run: npm ci
       - name: Install pinned Chromium
         run: npx playwright install --with-deps chromium
@@ -110,82 +163,35 @@ jobs:
           name: golden-images
           path: artifacts/golden
 
-  performance:
-    # Candidate and base SHA run sequentially on the same hosted runner with
-    # one Playwright/Chromium installation. This avoids turning a developer
-    # laptop or cross-runner variance into a timing budget.
+  performance_smoke:
+    # Candidate-only catastrophic-regression guard for ordinary pushes and
+    # prereleases. The expensive same-runner comparison lives in performance.yml.
     needs: frontend
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
-      - name: Check out candidate
-        uses: actions/checkout@v4
-        with:
-          path: candidate
-          fetch-depth: 2
-      - name: Resolve comparison SHA
-        id: base
-        working-directory: candidate
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          PUSH_BEFORE_SHA: ${{ github.event.before }}
-        run: |
-          if [ "$EVENT_NAME" = "pull_request" ] && [ -n "$PR_BASE_SHA" ]; then
-            sha="$PR_BASE_SHA"
-          elif [ "$EVENT_NAME" = "push" ] && [ -n "$PUSH_BEFORE_SHA" ] && ! printf '%s' "$PUSH_BEFORE_SHA" | grep -Eq '^0+$'; then
-            sha="$PUSH_BEFORE_SHA"
-          else
-            sha="$(git rev-parse HEAD^)"
-          fi
-          # The first main promotion after HP-PERF-01 can legitimately point
-          # at an older stable commit which predates the benchmark's embedded
-          # bundle fingerprint. Comparing against that legacy tree would fail
-          # the freshness guard before any measurements are taken. Fall back
-          # to the candidate's direct parent, which is the last dev revision
-          # included in the promotion and already has the current harness.
-          git fetch --no-tags --depth=1 origin "$sha"
-          if ! git cat-file -e "${sha}:demo/bundle-freshness.mjs" 2>/dev/null; then
-            echo "comparison $sha predates HP-PERF-01; using HEAD^" >&2
-            sha="$(git rev-parse HEAD^)"
-          fi
-          echo "sha=$sha" >> "$GITHUB_OUTPUT"
-      - name: Check out base SHA
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ steps.base.outputs.sha }}
-          path: baseline
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: 22
           cache: npm
-          cache-dependency-path: |
-            candidate/package-lock.json
-            baseline/package-lock.json
-      - name: Install candidate and baseline dependencies
-        run: npm ci --prefix candidate && npm ci --prefix baseline
+      - run: npm ci
       - name: Install pinned Chromium
-        working-directory: candidate
         run: npx playwright install --with-deps chromium
-      - name: Build both exact source trees
+      - name: Build the exact candidate source
+        run: npm run build && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
+      - name: Capture the heaviest Glow state
         run: |
-          npm --prefix candidate run build
-          cp candidate/dist/houseplan-card.js candidate/demo/srv/assets/houseplan-card.js
-          npm --prefix baseline run build
-          cp baseline/dist/houseplan-card.js baseline/demo/srv/assets/houseplan-card.js
-      - name: Capture base and candidate profiles
-        working-directory: candidate
+          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: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
-      - name: Enforce 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
-      - name: Upload performance reports
+          npm run benchmark:compare -- --absolute-only --budgets=demo/performance/budgets-glow-smoke.json --candidate=artifacts/performance-smoke/candidate.json --output=artifacts/performance-smoke/comparison.json
+      - name: Upload performance smoke report
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: large-house-performance
-          path: artifacts/performance
+          name: performance-smoke
+          path: artifacts/performance-smoke
 
   backend:
     runs-on: ubuntu-latest

.gitignore

@@ -6,3 +6,4 @@ __pycache__/
 .pytest_cache/
 .venv-backend/
 artifacts/
+.agents/

AGENTS.md

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

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

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

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

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

CONTRIBUTING.md

@@ -35,6 +35,7 @@ npm run typecheck         # tsc --noEmit (strict)
 npm test                  # node:test — pure logic, i18n parity, tap-action security
 npm run build             # tsc + rollup → dist/houseplan-card.js
 pip install pytest voluptuous && python -m pytest tests_backend -q   # pure backend tests
+npm install                # also installs .githooks through the prepare script
 ```
 
 The HA-harness backend tests (`tests_backend/test_ha_*.py`) need Python ≥3.13 and
@@ -50,7 +51,8 @@ every push — locally they are skipped when `homeassistant` is not importable.
 - The built card must be committed in sync: `cp dist/houseplan-card.js
   custom_components/houseplan/frontend/` (CI compares them byte-for-byte).
 - Tap actions have a security model (locks/alarms never toggle from the plan) —
-  see `resolveTapAction` in `src/logic.ts`; don't weaken it.
+  see `resolveToggleIntent` in `src/device-toggle.ts`; don't weaken it.
+- Every commit follows the issue and trailer contract in `PROCESS.md`.
 - Follow the Integration Quality Scale where applicable —
   `custom_components/houseplan/quality_scale.yaml` tracks the self-assessment.
 

PROCESS.md

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

README.md

@@ -44,8 +44,9 @@ right on your Lovelace dashboard.
   you drag, so the drawing and the photo of your plan finally line up.
 - 💡 **Lights toggle on click** out of the box; wall-switch markers can control
   whole groups of lights (works for dumb switches and stateless remotes too).
-- 🌒 **“Light sources” fill** — a dark house where every lit lamp casts a pool
-  of its own color that spills through doorways and open zone boundaries.
+- 🌒 **“Light sources” fill** — a dark house where every lit lamp lights exactly
+  the floor it can see: through doorways and open boundaries, stopped by walls,
+  columns and partitions, which cast real shadows.
 - ☀️ **The sun on the plan** — set the compass and the backdrop lives with
   the day (white noon → golden hour → deep night), while windows on exterior
   walls cast real wedges of sunlight into the rooms; optional cloud cover
@@ -62,8 +63,10 @@ right on your Lovelace dashboard.
 - 🤖 **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.
+  one click (rooms matched by name) or a drag-and-stretch overlay. A diagnostic
+  source picker also covers registry-less map cameras without silently
+  rebinding broken sources. Works with Xiaomi Cloud Map Extractor, Tasshack
+  dreame-vacuum and Valetudo.
 - 🔔 New devices appear automatically with a red “new” dot; the layout is stored
   **server-side** — one shared plan for every user and screen, synced live.
 
@@ -275,12 +278,15 @@ Switch to the **Devices** tab to arrange icons: drag them with the mouse, click
 
 ### Tap actions: control devices from the plan
 
-By default a tap on an icon opens its info card. In the card settings you can switch
-**Tap on a device** to *Toggle* — a tap then switches lights, sockets, fans and
-humidifiers directly on the plan (wall-tablet style). For safety, a card-wide toggle
-never affects locks, alarms, covers or valves; you can consciously enable toggle for a
-specific device (except locks and alarms — those never toggle from the plan) in its
-edit dialog. A **long press** always opens the info card.
+By default a tap on an icon opens its info card. A device can instead use the
+universal **Toggle state** action. Its editor shows the exact entity or configured
+group, the current state and what the next tap will do; when nothing can be toggled,
+it says so and the tap is a quiet no-op rather than an unexpected info-card fallback.
+Lights keep their convenient toggle default. Covers and valves use open/close/stop
+semantics automatically, while locks, alarm panels and secure garage/door/gate covers
+remain blocked. An exact entity binding never falls through to a sibling switch, and
+temporarily unavailable group members are skipped without erasing the configuration.
+A **long press** still opens the info card and right-click still opens HA more-info.
 
 ### Icon rules
 
@@ -296,6 +302,27 @@ You can also place a **single entity** (not just a whole device): start typing i
 
 Not everything has to be left to the automation. With the **＋** button in the header you can place any device, group or a **virtual point** on the plan (for example, an "Inlet valve" that does not exist as a device). Set a name, icon, model, link, description and, if you wish, attach a **PDF manual**.
 
+To represent a dumb physical lamp controlled by a smart relay, place a virtual
+point where the lamp really is and set **Light source → Always**. Manual colour,
+brightness and radius stay available even though the point has no HA entity.
+Then open the relay and add that plan source under **Controls other light
+sources**. The relay continues to show the aggregate working state, while Glow,
+room fill and statistics belong to the lamp's position. An unlinked passive
+Always source is deliberately constant-on. With several own `light.*`/`switch.*`
+entities, Always also offers a leading-entity selector; a missing saved choice
+is warned about and retained while a deterministic fallback is used.
+
+To make that virtual lamp manually switchable without creating a Home
+Assistant helper, also choose **Tap action → Toggle state** on the lamp itself.
+This exact combination — virtual binding, **Light source → Always**, and
+**Toggle state** — stores a shared on/off state in the House Plan integration.
+It survives page reloads and Home Assistant restarts and updates Glow, room
+fill/statistics, full cards and `houseplan-space-card` together. Any signed-in
+dashboard viewer may toggle it. While this manual mode is active, saved
+**Controls other light sources** remain intact but are not called; changing the
+role, binding or tap action restores their normal behaviour. This operational
+state is deliberately not part of plan exports or Home Assistant entities.
+
 The same dialog controls how the device looks on the plan. **Display** switches between the
 icon badge, an animated **presence ripple** (pulsing rings while the entity is active, a faint
 dot when idle — great for motion sensors) or both, with a per-device ring colour and size. The

README.ru.md

@@ -43,7 +43,8 @@
 - 💡 **Свет переключается кликом** из коробки; значок выключателя может
   управлять группой ламп (в т.ч. «тупые» выключатели и кнопки-пульты).
 - 🌒 **Заливка «Свет по источникам»** — тёмный дом, где каждая горящая лампа
-  даёт пятно своего цвета, проникающее через дверные проёмы и открытые зоны.
+  освещает ровно тот пол, который видит: через проёмы и открытые границы,
+  а стены, колонны и перегородки его не пропускают и дают настоящие тени.
 - ☀️ **Солнце на плане** — задайте компас, и фон живёт вместе с днём
   (белый полдень → золотой час → глубокая ночь), а окна внешних стен пускают
   в комнаты настоящие клинья солнечного света; облачность — опционально, от
@@ -60,8 +61,10 @@
 - 🤖 **Роботы-пылесосы вживую** — маркер-база стоит на месте, а круглая
   шайба ездит по плану в реальном времени, «выливая» путь из-под себя;
   текущая и прошлая уборки хранятся на сервере. Калибровка — в один клик
-  (по именам комнат) или перетаскиванием призрака карты. Работают Xiaomi
-  Cloud Map Extractor, dreame-vacuum (Tasshack) и Valetudo.
+  (по именам комнат) или перетаскиванием призрака карты. Диагностика и явный
+  выбор источника поддерживают registry-less камеры карт и не подменяют молча
+  сломавшуюся привязку. Работают Xiaomi Cloud Map Extractor, dreame-vacuum
+  (Tasshack) и Valetudo.
 - 🔔 Новые устройства сами появляются на плане с красной точкой; раскладка
   хранится **на сервере HA** — один план для всех экранов, живая синхронизация.
 

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

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

custom_components/houseplan/__init__.py

@@ -1,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,6 +3,7 @@
 DOMAIN = "houseplan"
 STORAGE_KEY = f"{DOMAIN}.layout"
 STORAGE_CONFIG_KEY = f"{DOMAIN}.config"
+STORAGE_VIRTUAL_LIGHTS_KEY = f"{DOMAIN}.virtual_lights"
 STORAGE_VERSION = 1
 STORAGE_MINOR_VERSION = 1
 FRONTEND_URL = "/houseplan_files/houseplan-card.js"
@@ -45,7 +46,21 @@ PLAN_ORPHAN_TTL_S = 3600
 SCHEDULED_GRACE_S = 30 * 24 * 3600
 FILES_DIR = "houseplan/files"
 CONF_ADMIN_ONLY = "admin_only"
-VERSION = "1.60.3"
+VERSION = "1.63.0"
+
+# Portable backup format.  This is deliberately independent from the Home
+# Assistant Store version above: storage migrations and files exported by a
+# user have different compatibility lifecycles.
+PLAN_MODEL_VERSION = 6
+EXPORT_VERSION = 1
+MAX_EXPORT_BYTES = 8 * 1024 * 1024
+IMPORT_PREVIEW_TTL_S = 10 * 60
+MAX_IMPORT_PREVIEWS_PER_USER = 3
+# Parsed documents are larger than their wire representation.  Keep the
+# original three-preview memory ceiling global as well as per user so turning
+# off the admin-only policy cannot multiply it by the number of household
+# accounts.
+MAX_IMPORT_PREVIEWS_TOTAL = 3
 
 DEFAULT_CONFIG: dict = {
     "spaces": [],

custom_components/houseplan/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.60.3"
+  "version": "1.63.0"
 }

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,7 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from typing import Any
@@ -10,7 +11,17 @@ from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.storage import Store
 
-from .const import DOMAIN, STORAGE_CONFIG_KEY, STORAGE_KEY, STORAGE_MINOR_VERSION, STORAGE_VERSION
+from .const import (
+    DOMAIN,
+    STORAGE_CONFIG_KEY,
+    STORAGE_KEY,
+    STORAGE_MINOR_VERSION,
+    STORAGE_VERSION,
+    STORAGE_VIRTUAL_LIGHTS_KEY,
+)
+
+
+_LOGGER = logging.getLogger(__name__)
 
 
 class HouseplanStore(Store):
@@ -40,6 +51,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 +66,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 +83,12 @@ def create_data(hass: HomeAssistant) -> HouseplanData:
         config_store=HouseplanStore(
             hass, STORAGE_VERSION, STORAGE_CONFIG_KEY, minor_version=STORAGE_MINOR_VERSION
         ),
+        virtual_light_store=HouseplanStore(
+            hass,
+            STORAGE_VERSION,
+            STORAGE_VIRTUAL_LIGHTS_KEY,
+            minor_version=STORAGE_MINOR_VERSION,
+        ),
     )
 
 
@@ -79,3 +102,98 @@ def get_entry(hass: HomeAssistant) -> ConfigEntry | None:
     """The loaded config entry, or None."""
     entries = hass.config_entries.async_loaded_entries(DOMAIN)
     return entries[0] if entries else None
+
+
+OPTIMIZE_BACKUP = "optimize_backup"
+OPTIMIZE_PENDING = "optimize_pending"
+LAYOUT_STORE_CORE_KEYS = frozenset({"layout", "rev"})
+
+
+def layout_store_payload(
+    stored: dict[str, Any],
+    layout: dict[str, Any],
+    rev: int,
+    *,
+    metadata: dict[str, Any] | None = None,
+    remove: tuple[str, ...] = (),
+    replace_metadata: bool = False,
+) -> dict[str, Any]:
+    """Build one layout-store write without silently dropping metadata.
+
+    Layout used to be saved by several independent dict comprehensions.  Every
+    new metadata key therefore had to be added to every caller or was lost on
+    the next drag.  All writers now express only the metadata they intentionally
+    add/remove and this helper preserves the rest.
+    """
+    excluded = {*LAYOUT_STORE_CORE_KEYS, *remove}
+    out = {} if replace_metadata else {
+        key: value for key, value in stored.items() if key not in excluded
+    }
+    if metadata:
+        out.update(metadata)
+    out["layout"] = layout
+    out["rev"] = rev
+    return out
+
+
+async def async_save_layout_state(
+    runtime: HouseplanData,
+    stored: dict[str, Any],
+    layout: dict[str, Any],
+    rev: int,
+    *,
+    metadata: dict[str, Any] | None = None,
+    remove: tuple[str, ...] = (),
+    replace_metadata: bool = False,
+) -> dict[str, Any]:
+    """Persist layout and return the exact store document written."""
+    payload = layout_store_payload(
+        stored,
+        layout,
+        rev,
+        metadata=metadata,
+        remove=remove,
+        replace_metadata=replace_metadata,
+    )
+    await runtime.store.async_save(payload)
+    return payload
+
+
+async def async_save_config_state(
+    runtime: HouseplanData,
+    config: dict[str, Any],
+    rev: int,
+    *,
+    previous_rev: int | None = None,
+) -> dict[str, Any]:
+    """Persist configuration and reconcile dependent operational state.
+
+    Callers already hold ``runtime.write_lock``.  Reading the previous
+    revision here keeps less common writers (import recovery and undo) on the
+    same path as ordinary editor saves without duplicating lifecycle rules.
+    """
+    if previous_rev is None:
+        previous = await runtime.config_store.async_load() or {}
+        try:
+            previous_rev = int(previous.get("rev", 0))
+        except (TypeError, ValueError):
+            previous_rev = 0
+
+    payload = {"config": config, "rev": rev}
+    await runtime.config_store.async_save(payload)
+
+    # The config is already durable at this point.  Reconciliation remains a
+    # separate Store write; an interrupted pair is detected from config_rev on
+    # the next read and fails safe to the compatibility default (all on).
+    from .virtual_lights import async_reconcile_virtual_lights
+
+    try:
+        await async_reconcile_virtual_lights(
+            runtime.virtual_light_store,
+            config,
+            rev,
+            previous_config_rev=previous_rev,
+        )
+    except Exception:  # noqa: BLE001 - config commit already stands
+        _LOGGER.exception("House Plan: virtual-light state reconciliation failed")
+    return payload

custom_components/houseplan/trails.py

@@ -110,6 +110,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
@@ -134,6 +137,7 @@ 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
@@ -141,11 +145,14 @@ class TrailRecorder:
                 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
             self._resubscribe()
             # A run already in progress (HA restarted mid-cleanup, or the user
@@ -155,6 +162,58 @@ 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:

custom_components/houseplan/validation.py

@@ -4,6 +4,7 @@ Kept separate so it can be covered by unit tests (only voluptuous is needed).
 """
 from __future__ import annotations
 
+from collections import Counter
 import re
 
 import voluptuous as vol
@@ -19,6 +20,228 @@ _SAFE_NAME_RE = re.compile(r"[^A-Za-z0-9._-]+")
 # The name length the content view will accept back in a request. Anything a
 # generated name must fit inside, collision tag included (HP-1460-01).
 MAX_FILENAME = 120
+MARKER_CONTROL_PREFIX = "marker:"
+_CONTROL_ENTITY_ID_RE = re.compile(r"^[a-z0-9_]+\.[a-z0-9_]+\Z")
+
+
+class MarkerControlError(ValueError):
+    """Semantic marker-link error with a stable public code."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+VALUE_BADGE_ATTRIBUTES = {
+    "current_temperature", "temperature", "current_humidity", "humidity",
+    "current_position", "percentage", "brightness", "volume_level",
+    "battery_level", "fan_speed",
+}
+VALUE_BADGE_POSITIONS = {"right", "bottom", "left", "top"}
+VALUE_BADGE_SOURCE_KINDS = {
+    "entity_state", "entity_attribute", "derived_lqi", "derived_marker_state",
+}
+_LIGHT_ENTITY_RE = re.compile(r"^(?:light|switch)\.[a-z0-9_]+\Z")
+
+
+def _matching_previous_marker(
+    marker: dict, marker_id: str, old_by_id: dict[str, dict], old_markers: list[dict],
+    new_ids: set[str], consumed_old_ids: set[str], validate_all: bool,
+) -> dict | None:
+    """Match the previous marker across the binding-stable id rename path."""
+    old_marker = old_by_id.get(marker_id)
+    if old_marker is not None:
+        consumed_old_ids.add(marker_id)
+        return old_marker
+    if validate_all:
+        return None
+    binding = marker.get("binding")
+    matches = [
+        old for old in old_markers
+        if binding not in (None, "virtual")
+        and old.get("binding") == binding
+        and str(old.get("id")) not in new_ids
+        and str(old.get("id")) not in consumed_old_ids
+    ]
+    if len(matches) == 1:
+        consumed_old_ids.add(str(matches[0].get("id")))
+        return matches[0]
+    return None
+
+
+def validate_marker_value_badges(
+    config: dict, previous: dict | None = None, *, validate_all: bool = False
+) -> None:
+    """Validate only new/changed badge data; dormant future/legacy data round-trips."""
+    markers = config.get("markers") or []
+    by_id = {str(marker.get("id")): marker for marker in markers}
+    old_markers = (previous or {}).get("markers") or []
+    old_by_id = {str(marker.get("id")): marker for marker in old_markers}
+    new_ids = set(by_id)
+    consumed_old_ids: set[str] = set()
+    known_source_fields = {"kind", "entity_id", "attribute", "ref"}
+
+    for marker_id, marker in by_id.items():
+        old_marker = _matching_previous_marker(
+            marker, marker_id, old_by_id, old_markers, new_ids,
+            consumed_old_ids, validate_all,
+        )
+        badge = marker.get("value_badge")
+        old_badge = None if validate_all else (old_marker or {}).get("value_badge")
+        if not validate_all and badge == old_badge:
+            continue
+        if badge is None:
+            continue
+        if not isinstance(badge, dict):
+            raise MarkerControlError("invalid_value_badge", "Value badge must be an object")
+        if not isinstance(badge.get("enabled"), bool):
+            raise MarkerControlError("invalid_value_badge", "Value badge enabled must be boolean")
+        if badge.get("position") not in VALUE_BADGE_POSITIONS:
+            raise MarkerControlError("invalid_value_badge_position", "Invalid value badge position")
+        source = badge.get("source")
+        if badge["enabled"] and not isinstance(source, dict):
+            raise MarkerControlError("value_badge_source_required", "Enabled value badge needs a source")
+        if source is None:
+            continue
+        if not isinstance(source, dict) or source.get("kind") not in VALUE_BADGE_SOURCE_KINDS:
+            raise MarkerControlError("invalid_value_badge_source", "Invalid value badge source")
+        kind = source["kind"]
+        allowed_fields = {
+            "entity_state": {"kind", "entity_id"},
+            "entity_attribute": {"kind", "entity_id", "attribute"},
+            "derived_lqi": {"kind"},
+            "derived_marker_state": {"kind", "ref"},
+        }[kind]
+        if (known_source_fields & set(source)) - allowed_fields:
+            raise MarkerControlError("invalid_value_badge_source", "Inconsistent value badge source")
+        if kind in {"entity_state", "entity_attribute"}:
+            entity_id = source.get("entity_id")
+            if not isinstance(entity_id, str) or not _CONTROL_ENTITY_ID_RE.fullmatch(entity_id):
+                raise MarkerControlError("invalid_value_badge_source", "Invalid value badge entity id")
+        if kind == "entity_attribute":
+            if source.get("attribute") not in VALUE_BADGE_ATTRIBUTES:
+                raise MarkerControlError("invalid_value_badge_attribute", "Invalid value badge attribute")
+        if kind == "derived_marker_state":
+            ref = source.get("ref")
+            if not isinstance(ref, str) or not ref.startswith(MARKER_CONTROL_PREFIX) or not ref[len(MARKER_CONTROL_PREFIX):]:
+                raise MarkerControlError("invalid_value_badge_source", "Invalid marker value badge target")
+            target = by_id.get(ref[len(MARKER_CONTROL_PREFIX):])
+            if target is None or target.get("removed") is True:
+                raise MarkerControlError("value_badge_marker_missing", "Marker value badge target does not exist")
+            if target.get("is_light") is not True:
+                raise MarkerControlError("value_badge_marker_not_light", "Marker value badge target is not a forced light")
+
+
+def validate_marker_light_entities(
+    config: dict, previous: dict | None = None, *, validate_all: bool = False
+) -> None:
+    """Validate new/changed leading-light choices without rejecting dormant data.
+
+    The top-level schema must stay lossless: an old or future literal that the
+    current frontend cannot edit may round-trip unchanged. Imports validate the
+    whole incoming document because every imported value is new to this plan.
+    """
+    markers = config.get("markers") or []
+    old_markers = (previous or {}).get("markers") or []
+    old_by_id = {str(marker.get("id")): marker for marker in old_markers}
+    new_ids = {str(marker.get("id")) for marker in markers}
+    consumed_old_ids: set[str] = set()
+    for marker in markers:
+        marker_id = str(marker.get("id"))
+        old_marker = _matching_previous_marker(
+            marker, marker_id, old_by_id, old_markers, new_ids,
+            consumed_old_ids, validate_all,
+        )
+        value = marker.get("light_entity")
+        old_value = None if validate_all else (old_marker or {}).get("light_entity")
+        if not validate_all and value == old_value:
+            continue
+        if value is None:
+            continue
+        if not isinstance(value, str) or not _LIGHT_ENTITY_RE.fullmatch(value):
+            raise MarkerControlError(
+                "invalid_light_entity", "Leading light entity must be light.* or switch.*"
+            )
+
+
+def validate_marker_controls(
+    config: dict, previous: dict | None = None, *, validate_all: bool = False
+) -> None:
+    """Validate newly introduced marker:* edges without rewriting old data.
+
+    Existing broken refs remain editable and round-trip losslessly. Imports use
+    validate_all because their complete candidate graph is new to this plan.
+    """
+    markers = config.get("markers") or []
+    by_id = {str(marker.get("id")): marker for marker in markers}
+    old_markers = (previous or {}).get("markers") or []
+    old_by_id = {
+        str(marker.get("id")): marker for marker in (previous or {}).get("markers") or []
+    }
+    new_ids = set(by_id)
+    consumed_old_ids: set[str] = set()
+    graph: dict[str, list[str]] = {}
+    added: list[tuple[str, str]] = []
+    for marker_id, marker in by_id.items():
+        old_marker = _matching_previous_marker(
+            marker, marker_id, old_by_id, old_markers, new_ids,
+            consumed_old_ids, validate_all,
+        )
+        raw_controls = [
+            ref for ref in marker.get("controls") or [] if isinstance(ref, str)
+        ]
+        old_controls = [] if validate_all else [
+            ref for ref in (old_marker or {}).get("controls") or [] if isinstance(ref, str)
+        ]
+        refs = [
+            ref for ref in raw_controls
+            if isinstance(ref, str) and ref.startswith(MARKER_CONTROL_PREFIX)
+        ]
+        graph[marker_id] = [ref[len(MARKER_CONTROL_PREFIX):] for ref in refs]
+        old_refs = [
+            ref for ref in old_controls
+            if isinstance(ref, str) and ref.startswith(MARKER_CONTROL_PREFIX)
+        ]
+        remaining = list(old_refs)
+        for ref in refs:
+            if ref in remaining:
+                remaining.remove(ref)
+            else:
+                added.append((marker_id, ref[len(MARKER_CONTROL_PREFIX):]))
+        new_counts, old_counts = Counter(refs), Counter(old_refs)
+        if any(count > 1 and count > old_counts[ref] for ref, count in new_counts.items()):
+            raise MarkerControlError("duplicate_marker_control", "Duplicate marker light target")
+        remaining_controls = list(old_controls)
+        for ref in raw_controls:
+            if ref in remaining_controls:
+                remaining_controls.remove(ref)
+            elif not ref.startswith(MARKER_CONTROL_PREFIX) and not _CONTROL_ENTITY_ID_RE.fullmatch(ref):
+                raise MarkerControlError("invalid_marker_control", f"Invalid entity target: {ref}")
+
+    def reaches(start: str, wanted: str) -> bool:
+        stack, seen = [start], set()
+        while stack:
+            node = stack.pop()
+            if node == wanted:
+                return True
+            if node in seen:
+                continue
+            seen.add(node)
+            stack.extend(graph.get(node, []))
+        return False
+
+    for controller, target in added:
+        if not target:
+            raise MarkerControlError("invalid_marker_control", "Marker target id is empty")
+        if target == controller:
+            raise MarkerControlError("marker_control_self", "A marker cannot control itself")
+        target_marker = by_id.get(target)
+        if target_marker is None or target_marker.get("removed") is True:
+            raise MarkerControlError("marker_control_missing", f"Marker target does not exist: {target}")
+        if target_marker.get("is_light") is not True:
+            raise MarkerControlError("marker_control_not_light", f"Marker target is not a forced light: {target}")
+        if reaches(target, controller):
+            raise MarkerControlError("marker_control_cycle", "Marker light controls contain a cycle")
 
 # ---------- sanitizers ----------
 
@@ -62,6 +285,19 @@ def _finite(value):
     return f
 
 
+# Persisted colours deliberately use one small, browser-independent format.
+# Keep this exact contract in sync with src/color.ts.
+# `^...$` accepts a trailing newline in Python. Persisted CSS tokens must
+# match the whole string exactly, in parity with the frontend validator.
+_COLOR = vol.Match(r"\A#[0-9a-fA-F]{6}\Z")
+_CUSTOM_FILL = vol.Schema(
+    {
+        vol.Required("c"): _COLOR,
+        vol.Required("a"): vol.All(_finite, vol.Range(min=0.0, max=1.0)),
+    }
+)
+
+
 # generous caps: the product targets 20-200 devices and a handful of floors
 MAX_SPACES = 50
 MAX_ROOMS = 400
@@ -210,7 +446,9 @@ ROOM_SCHEMA = vol.All(
                 None,
                 vol.Schema(
                     {
-                        vol.Optional("fill_mode"): vol.Any(None, vol.In(["none", "lqi", "light", "temp"])),
+                        vol.Optional("fill_mode"): vol.Any(None, vol.In(["none", "lqi", "light", "temp", "custom", "glow"])),
+                        vol.Optional("custom_fill"): vol.Any(None, _CUSTOM_FILL),
+                        vol.Optional("glow"): vol.Any(bool, None),
                         vol.Optional("temp_source"): vol.Any(str, None),
                         vol.Optional("hum_source"): vol.Any(str, None),
                         vol.Optional("name_scale"): vol.Any(None, vol.All(vol.Coerce(float), vol.Range(min=0.5, max=3))),
@@ -249,11 +487,13 @@ SPACE_DISPLAY_SCHEMA = vol.Schema(
     {
         vol.Optional("show_borders"): bool,
         vol.Optional("show_names"): bool,
-        vol.Optional("room_color"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+        vol.Optional("room_color"): _COLOR,
         # per-space background around the plan; absent = inherit the global one
-        vol.Optional("bg_color"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+        vol.Optional("bg_color"): _COLOR,
         vol.Optional("room_opacity"): vol.All(vol.Coerce(float), vol.Range(min=0, max=1)),
-        vol.Optional("fill_mode"): vol.In(["none", "lqi", "light", "temp", "glow"]),
+        vol.Optional("fill_mode"): vol.In(["none", "lqi", "light", "temp", "custom", "glow"]),
+        vol.Optional("custom_fill"): vol.Any(None, _CUSTOM_FILL),
+        vol.Optional("glow_enabled"): bool,
         vol.Optional("temp_min"): vol.Coerce(float),
         vol.Optional("temp_max"): vol.Coerce(float),
         vol.Optional("show_lqi"): bool,
@@ -305,7 +545,7 @@ _FURN_SIZE = vol.All(_finite, vol.Range(min=0.0000001, max=CANVAS_LIMIT))
 
 _DECOR_COMMON = {
     vol.Required("id"): str,
-    vol.Optional("color"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+    vol.Optional("color"): _COLOR,
     vol.Optional("opacity"): vol.All(_finite, vol.Range(min=0.0, max=1.0)),
     # Physical centimetres are canonical. `width` remains accepted so plans
     # written by older cards keep their exact appearance until edited.
@@ -328,7 +568,7 @@ DECOR_SCHEMA = vol.Any(
                 vol.Required("h"): vol.All(_finite, vol.Range(min=0.001, max=CANVAS_LIMIT)),
                 vol.Optional("angle"): vol.All(_finite, vol.Range(min=-360.0, max=360.0)),
                 vol.Optional("fill"): bool,
-                vol.Optional("fill_color"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+                vol.Optional("fill_color"): _COLOR,
                 vol.Optional("fill_opacity"): vol.All(_finite, vol.Range(min=0.0, max=1.0))},
                extra=vol.ALLOW_EXTRA),
     vol.Schema({**_DECOR_COMMON, vol.Required("kind"): "text",
@@ -626,16 +866,48 @@ MARKER_SCHEMA = vol.Schema(
         ),
         vol.Optional("controls"): vol.Any(None, vol.All([_TEXT], vol.Length(max=MAX_CONTROLS))),
         vol.Optional("glow_radius_cm"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=10, max=10000)), None),
+        vol.Optional("glow_color"): vol.Any(
+            None,
+            vol.Schema(
+                {
+                    vol.Required("c"): _COLOR,
+                    vol.Optional("bri"): vol.Any(
+                        None,
+                        vol.All(_finite, vol.Range(min=0.01, max=1.0)),
+                    ),
+                }
+            ),
+        ),
         vol.Optional("is_light"): vol.Any(bool, None),
+        # Explicit leading entity for composite Always sources. It is kept
+        # literally when temporarily absent; runtime falls back without
+        # deleting the user's choice.
+        # Semantic delta validation below the schema preserves unknown/future
+        # literals until that exact field is edited (lossless config doctrine).
+        vol.Optional("light_entity"): object,
+        vol.Optional("value_badge"): vol.Any(
+            None,
+            vol.Schema(
+                {
+                    # Required semantically for changed/new data. Optional here
+                    # keeps old/future configs readable until the user edits it.
+                    vol.Optional("enabled"): object,
+                    vol.Optional("position"): object,
+                    vol.Optional("source"): vol.Any(
+                        None,
+                        vol.Schema({}, extra=vol.ALLOW_EXTRA),
+                    ),
+                },
+                extra=vol.ALLOW_EXTRA,
+            ),
+        ),
         # climate current_temperature: badge + room-average vote (off unless True)
         vol.Optional("use_climate_temp"): vol.Any(bool, None),
         vol.Optional("room_id"): vol.Any(str, None),
         # Keep in sync with DISPLAY_MODES in src/logic.ts. `ripple` is no longer
         # offered, but remains accepted while old stores migrate to icon_ripple.
         vol.Optional("display"): vol.Any("badge", "ripple", "icon_ripple", "value", "static_icon", None),
-        vol.Optional("ripple_color"): vol.Any(
-            None, vol.Match(r"^#[0-9a-fA-F]{6}$")
-        ),
+        vol.Optional("ripple_color"): vol.Any(None, _COLOR),
         vol.Optional("ripple_size"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=1, max=20)), None),
         vol.Optional("size"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=0.2, max=6)), None),
         vol.Optional("angle"): vol.Any(vol.All(vol.Coerce(float), vol.Range(min=-360, max=360)), None),
@@ -654,7 +926,7 @@ CONFIG_SCHEMA = vol.Schema(
             {
                 vol.Optional("glow_radius_cm"): vol.All(vol.Coerce(float), vol.Range(min=10, max=10000)),
                 # background around the plan, all spaces (a space may override)
-                vol.Optional("bg_color"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+                vol.Optional("bg_color"): _COLOR,
                 # sun on the plan (docs/SUN.md): global defaults
                 vol.Optional("north_deg"): _north_deg,
                 vol.Optional("bg_mode"): _BG_MODE,
@@ -669,7 +941,7 @@ CONFIG_SCHEMA = vol.Schema(
                     {
                         str: vol.Schema(
                             {
-                                vol.Required("c"): vol.Match(r"^#[0-9a-fA-F]{6}$"),
+                                vol.Required("c"): _COLOR,
                                 vol.Required("a"): vol.All(vol.Coerce(float), vol.Range(min=0, max=1)),
                             }
                         )

custom_components/houseplan/virtual_lights.py

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

custom_components/houseplan/websocket_api.py

@@ -8,6 +8,8 @@ import binascii
 import json
 import secrets
 import time
+from datetime import UTC, datetime
+from functools import partial
 from pathlib import Path
 from typing import Any
 
@@ -24,25 +26,47 @@ from .const import (
     PLANS_DIR, PLANS_URL,
 )
 from .auth import may_write
+from .import_export import (
+    ImportFailure,
+    content_manifest,
+    create_export,
+    get_candidate,
+    live_layout,
+    prepare_apply,
+    revalidate_candidate,
+)
 from .plans import (
     QuotaError, check_quota, collect_attachments, collect_plans, is_plan_file,
     plan_basename, plan_refs, reserve_filename,
 )
-from .store import HouseplanData, get_data, get_entry
+from .store import (
+    LAYOUT_STORE_CORE_KEYS,
+    OPTIMIZE_BACKUP as _OPTIMIZE_BACKUP,
+    OPTIMIZE_PENDING as _OPTIMIZE_PENDING,
+    HouseplanData,
+    async_save_config_state,
+    async_save_layout_state,
+    get_data,
+    get_entry,
+)
+from .virtual_lights import (
+    EVENT_VIRTUAL_LIGHT_UPDATED,
+    async_toggle_virtual_light,
+    async_virtual_light_snapshot,
+)
+from .registry_snapshot import import_registry_snapshot
 from .validation import (
     CONFIG_SCHEMA, LAYOUT_SCHEMA, MAX_CONFIG_BYTES, MAX_PLAN_BYTES,
-    PLAN_EXTENSIONS, POS_SCHEMA, sanitize_filename, valid_space_id,
+    PLAN_EXTENSIONS, POS_SCHEMA, MarkerControlError, sanitize_filename,
+    validate_marker_controls, validate_marker_light_entities,
+    validate_marker_value_badges, valid_space_id,
 )
 
 
 _LOGGER = logging.getLogger(__name__)
 
-_OPTIMIZE_BACKUP = "optimize_backup"
-_OPTIMIZE_PENDING = "optimize_pending"
-
-
 def _optimizer_backup_is_current(config_data: dict[str, Any], layout_data: dict[str, Any]) -> bool:
-    """An optimization can be undone only before any later plan edit."""
+    """An optimization can be undone before any later ordinary plan edit."""
     backup = layout_data.get(_OPTIMIZE_BACKUP)
     if not isinstance(backup, dict):
         return False
@@ -55,17 +79,46 @@ def _optimizer_backup_is_current(config_data: dict[str, Any], layout_data: dict[
         return False
 
 
+def _optimizer_backup_after_layout_maintenance(
+    layout_data: dict[str, Any], new_layout_rev: int,
+) -> dict[str, Any]:
+    """Carry a one-deep plan snapshot across explicit layout maintenance.
+
+    Geometry repair is part of plan maintenance, not an ordinary user edit:
+    losing the Optimize/Import undo there makes the advertised safety net
+    disappear.  The snapshot must also follow the new layout revision or the
+    freshness guard will correctly, but unhelpfully, classify it as stale.
+    """
+    backup = layout_data.get(_OPTIMIZE_BACKUP)
+    if not isinstance(backup, dict):
+        return {}
+    return {
+        _OPTIMIZE_BACKUP: {
+            **backup,
+            "after_layout_rev": new_layout_rev,
+        }
+    }
+
+
+def _undo_kind(config_data: dict[str, Any], layout_data: dict[str, Any]) -> str | None:
+    if not _optimizer_backup_is_current(config_data, layout_data):
+        return None
+    backup = layout_data.get(_OPTIMIZE_BACKUP)
+    return str(backup.get("kind") or "optimize") if isinstance(backup, dict) else None
+
+
 async def _discard_optimizer_snapshot(rt: HouseplanData) -> None:
     """Free a snapshot made stale by a later ordinary config edit."""
     data = await rt.store.async_load() or {}
     if _OPTIMIZE_BACKUP not in data and _OPTIMIZE_PENDING not in data:
         return
-    await rt.store.async_save({
-        **{
-            k: v for k, v in data.items()
-            if k not in (_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)
-        }
-    })
+    await async_save_layout_state(
+        rt,
+        data,
+        data.get("layout") or {},
+        int(data.get("rev", 0)),
+        remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING),
+    )
 
 
 @callback
@@ -79,6 +132,7 @@ def async_register(hass: HomeAssistant) -> None:
     websocket_api.async_register_command(hass, ws_layout_update)
     websocket_api.async_register_command(hass, ws_layout_delete)
     websocket_api.async_register_command(hass, ws_config_get)
+    websocket_api.async_register_command(hass, ws_virtual_light_toggle)
     websocket_api.async_register_command(hass, ws_config_set)
     websocket_api.async_register_command(hass, ws_plan_optimize)
     websocket_api.async_register_command(hass, ws_plan_optimize_undo)
@@ -88,6 +142,9 @@ def async_register(hass: HomeAssistant) -> None:
     websocket_api.async_register_command(hass, ws_files_migrate)
     websocket_api.async_register_command(hass, ws_files_cleanup)
     websocket_api.async_register_command(hass, ws_content_sign)
+    websocket_api.async_register_command(hass, ws_export_create)
+    websocket_api.async_register_command(hass, ws_import_revalidate)
+    websocket_api.async_register_command(hass, ws_import_apply)
 
 
 def _runtime(hass: HomeAssistant, connection, msg_id: int) -> HouseplanData | None:
@@ -108,6 +165,337 @@ def _check_write(hass: HomeAssistant, connection) -> bool:
     return may_write(hass, getattr(connection, "user", None))
 
 
+def _connection_user_id(connection) -> str:
+    return str(getattr(getattr(connection, "user", None), "id", ""))
+
+
+def _send_import_error(connection, msg_id: int, err: ImportFailure) -> None:
+    connection.send_error(msg_id, err.code, err.message)
+
+
+def _layout_metadata(stored: dict[str, Any]) -> dict[str, Any]:
+    """Return the exact non-layout portion of a layout-store document."""
+    return {
+        key: value for key, value in stored.items()
+        if key not in LAYOUT_STORE_CORE_KEYS
+    }
+
+
+async def _persist_pair_intent(
+    rt: HouseplanData,
+    pending: dict[str, Any],
+) -> None:
+    """Make a target pair recoverable before either visible half moves."""
+    stored = await rt.store.async_load() or {}
+    metadata = dict(pending.get("final_metadata") or {})
+    metadata[_OPTIMIZE_PENDING] = pending
+    await async_save_layout_state(
+        rt,
+        stored,
+        stored.get("layout") or {},
+        int(stored.get("rev", 0)),
+        metadata=metadata,
+        replace_metadata=True,
+    )
+
+
+async def _converge_pair(rt: HouseplanData, pending: dict[str, Any]) -> None:
+    """Write both target halves and remove the durable intent last."""
+    await async_save_config_state(
+        rt,
+        pending["config"],
+        int(pending["config_rev"]),
+    )
+    stored = await rt.store.async_load() or {}
+    await async_save_layout_state(
+        rt,
+        stored,
+        pending["layout"],
+        int(pending["layout_rev"]),
+        metadata=dict(pending.get("final_metadata") or {}),
+        replace_metadata=True,
+    )
+
+
+async def _commit_import_pair(
+    rt: HouseplanData,
+    pending: dict[str, Any],
+    rollback: dict[str, Any],
+) -> None:
+    """Commit, retry once, or restore the before-pair before returning.
+
+    A Store write may raise after the bytes reached disk, so recovery always
+    reloads and converges an explicit pair instead of guessing which half won.
+    If the target cannot be completed, a rollback intent replaces it before we
+    restore the old pair; setup will therefore restore, never unexpectedly
+    finish an import that was reported as failed.
+    """
+    try:
+        await _persist_pair_intent(rt, pending)
+        await _converge_pair(rt, pending)
+        return
+    except Exception:  # noqa: BLE001 - one retry handles fail-after-write too
+        _LOGGER.warning("House Plan import pair write failed; retrying target", exc_info=True)
+    try:
+        await _persist_pair_intent(rt, pending)
+        await _converge_pair(rt, pending)
+        return
+    except Exception:  # noqa: BLE001 - target is no longer the recovery policy
+        _LOGGER.exception("House Plan import target retry failed; restoring previous pair")
+    try:
+        await _persist_pair_intent(rt, rollback)
+        await _converge_pair(rt, rollback)
+    except Exception as rollback_error:  # noqa: BLE001
+        _LOGGER.exception(
+            "House Plan import rollback could not finish; rollback intent remains for setup"
+        )
+        raise ImportFailure(
+            "commit_failed", "Import failed; the previous plan is pending recovery"
+        ) from rollback_error
+    raise ImportFailure("commit_failed", "Import failed and the previous plan was restored")
+
+
+# ---------------- portable backup / transfer ----------------
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/export/create",
+        vol.Required("kind"): vol.In(["full", "space"]),
+        vol.Optional("space_id"): str,
+        vol.Optional("card_version", default=""): str,
+    }
+)
+@websocket_api.async_response
+async def ws_export_create(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Build a consistent full or one-space JSON snapshot."""
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only editors may export House Plan")
+        return
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    try:
+        async with rt.write_lock:
+            config_data = await rt.config_store.async_load() or {}
+            layout_data = await rt.store.async_load() or {}
+            document, filename = await hass.async_add_executor_job(
+                partial(
+                    create_export,
+                    rt,
+                    config_data,
+                    layout_data,
+                    kind=msg["kind"],
+                    space_id=msg.get("space_id"),
+                    card_version=msg.get("card_version", ""),
+                    config_root=Path(hass.config.path("")),
+                )
+            )
+    except ImportFailure as err:
+        _send_import_error(connection, msg["id"], err)
+        return
+    except Exception:  # noqa: BLE001
+        _LOGGER.exception("House Plan export failed")
+        connection.send_error(msg["id"], "invalid_config", "Could not create export")
+        return
+    connection.send_result(msg["id"], {"document": document, "filename": filename})
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/import/revalidate",
+        vol.Required("token"): str,
+        vol.Optional("duplicate_policy", default="skip"): vol.In(["skip", "virtual"]),
+    }
+)
+@websocket_api.async_response
+async def ws_import_revalidate(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Re-evaluate a space candidate after its duplicate policy changes."""
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only editors may import House Plan")
+        return
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    try:
+        async with rt.write_lock:
+            candidate = get_candidate(rt, msg["token"], _connection_user_id(connection))
+            config_data = await rt.config_store.async_load() or {}
+            layout_data = await rt.store.async_load() or {}
+            try:
+                registry_snapshot = import_registry_snapshot(hass)
+            except Exception:  # noqa: BLE001 - summary must not block revalidation
+                _LOGGER.debug("House Plan import registry summary unavailable", exc_info=True)
+                registry_snapshot = None
+            result = await hass.async_add_executor_job(
+                partial(
+                    revalidate_candidate,
+                    candidate,
+                    config_data,
+                    layout_data,
+                    duplicate_policy=msg["duplicate_policy"],
+                    registry_snapshot=registry_snapshot,
+                    config_root=Path(hass.config.path("")),
+                )
+            )
+            result["token"] = msg["token"]
+            result["expires_at"] = datetime.fromtimestamp(
+                candidate["expires"], UTC
+            ).isoformat().replace("+00:00", "Z")
+    except ImportFailure as err:
+        _send_import_error(connection, msg["id"], err)
+        return
+    connection.send_result(msg["id"], result)
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/import/apply",
+        vol.Required("token"): str,
+        vol.Required("expected_config_rev"): int,
+        vol.Required("expected_layout_rev"): int,
+        vol.Optional("duplicate_policy"): vol.In(["skip", "virtual"]),
+        vol.Optional("confirm_missing_content", default=False): bool,
+    }
+)
+@websocket_api.async_response
+async def ws_import_apply(hass: HomeAssistant, connection, msg: dict[str, Any]) -> None:
+    """Commit exactly the previewed candidate as one crash-resumable pair."""
+    if not _check_write(hass, connection):
+        connection.send_error(msg["id"], "unauthorized", "Only editors may import House Plan")
+        return
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    kind = ""
+    details: dict[str, Any] = {}
+    try:
+        async with rt.write_lock:
+            candidate = get_candidate(rt, msg["token"], _connection_user_id(connection))
+            config_data = await rt.config_store.async_load() or {}
+            layout_data = await rt.store.async_load() or {}
+            config_rev = int(config_data.get("rev", 0))
+            layout_rev = int(layout_data.get("rev", 0))
+            if (
+                msg["expected_config_rev"] != config_rev
+                or msg["expected_layout_rev"] != layout_rev
+                or candidate.get("config_rev") != config_rev
+                or candidate.get("layout_rev") != layout_rev
+            ):
+                raise ImportFailure("conflict", "Plan changed after the preview")
+            kind = str(candidate["document"]["kind"])
+            requested_policy = msg.get("duplicate_policy", candidate.get("duplicate_policy"))
+            if kind == "space" and requested_policy != candidate.get("duplicate_policy"):
+                raise ImportFailure("conflict", "Duplicate policy changed after the preview")
+            target_config, target_layout, details = await hass.async_add_executor_job(
+                partial(
+                    prepare_apply,
+                    candidate,
+                    config_data.get("config") or {"spaces": [], "markers": [], "settings": {}},
+                    layout_data.get("layout") or {},
+                    duplicate_policy=candidate.get("duplicate_policy"),
+                    confirm_missing_content=msg["confirm_missing_content"],
+                )
+            )
+            missing = await hass.async_add_executor_job(
+                _missing_internal_plans,
+                Path(hass.config.path(PLANS_DIR)),
+                target_config,
+                config_data.get("config"),
+            )
+            if missing:
+                raise ImportFailure(
+                    "missing_plan",
+                    "Plan file no longer exists: " + ", ".join(sorted(missing)),
+                )
+            missing_attachments = _missing_internal_attachments(
+                Path(hass.config.path("")), target_config, config_data.get("config")
+            )
+            if missing_attachments:
+                raise ImportFailure(
+                    "missing_content",
+                    "Attachment no longer exists: " + ", ".join(sorted(missing_attachments)),
+                )
+            new_config_rev = config_rev + 1
+            new_layout_rev = layout_rev + 1
+            backup = None
+            if kind == "full":
+                backup = {
+                    "kind": "import",
+                    "config": config_data.get("config") or DEFAULT_CONFIG,
+                    "layout": layout_data.get("layout") or {},
+                    "created": int(time.time()),
+                    "after_config_rev": new_config_rev,
+                    "after_layout_rev": new_layout_rev,
+                }
+            original_metadata = _layout_metadata(layout_data)
+            replaced_metadata = {_OPTIMIZE_PENDING, _OPTIMIZE_BACKUP}
+            if kind == "full":
+                replaced_metadata.update({"repair_backup", "geom_pending"})
+            final_metadata = {
+                key: value for key, value in original_metadata.items()
+                if key not in replaced_metadata
+            }
+            if backup is not None:
+                final_metadata[_OPTIMIZE_BACKUP] = backup
+            pending = {
+                "kind": "import",
+                "config": target_config,
+                "layout": target_layout,
+                "config_rev": new_config_rev,
+                "layout_rev": new_layout_rev,
+                "final_metadata": final_metadata,
+            }
+            rollback = {
+                "kind": "import_rollback",
+                "config": config_data.get("config") or DEFAULT_CONFIG,
+                "layout": layout_data.get("layout") or {},
+                "config_rev": config_rev,
+                "layout_rev": layout_rev,
+                "final_metadata": original_metadata,
+            }
+            await _commit_import_pair(rt, pending, rollback)
+            # A token becomes single-use only after both durable halves land.
+            get_candidate(rt, msg["token"], _connection_user_id(connection), consume=True)
+    except ImportFailure as err:
+        _send_import_error(connection, msg["id"], err)
+        return
+    except Exception:  # noqa: BLE001
+        _LOGGER.exception("House Plan import commit failed")
+        connection.send_error(msg["id"], "commit_failed", "Import commit failed")
+        return
+
+    hass.bus.async_fire("houseplan_config_updated", {"rev": new_config_rev})
+    hass.bus.async_fire("houseplan_layout_updated", {"rev": new_layout_rev})
+    _refresh_trail_recorder(hass)
+    if kind == "full":
+        recorder = hass.data.get(DOMAIN, {}).get("trail_recorder")
+        live_marker_ids = {
+            str(marker.get("id")) for marker in target_config.get("markers") or []
+        }
+        if recorder is not None:
+            for marker_id in list(getattr(getattr(recorder, "book", None), "data", {})):
+                if marker_id not in live_marker_ids:
+                    try:
+                        await recorder.async_delete(marker_id)
+                    except Exception:  # noqa: BLE001
+                        _LOGGER.exception("House Plan: removing orphan import trail failed")
+        entry = get_entry(hass)
+        if entry is not None:
+            from .repairs import async_check_plan_files
+
+            hass.async_create_task(async_check_plan_files(hass, entry))
+    connection.send_result(msg["id"], {
+        "ok": True,
+        "kind": kind,
+        "config_rev": new_config_rev,
+        "layout_rev": new_layout_rev,
+        "counts": details.get("counts", {}),
+        "space_id": details.get("space_id"),
+        "can_undo": kind == "full",
+    })
+
+
 # ---------------- layout ----------------
 
 
@@ -120,25 +508,7 @@ def _live_layout(config: dict[str, Any], layout: dict[str, Any]) -> dict[str, An
     only a legacy naming convention, however; an explicit real marker remains
     authoritative even when its id happens to begin with `v_`.
     """
-    markers = config.get("markers") or []
-    removed_ids = {
-        str(m.get("id")) for m in markers if m.get("removed") is True
-    }
-    virtual_ids = {
-        str(m.get("id")) for m in markers
-        if m.get("removed") is not True and m.get("binding") == "virtual"
-    }
-    explicit_live_ids = {
-        str(m.get("id")) for m in markers
-        if m.get("removed") is not True and m.get("binding") != "virtual"
-    }
-    return {
-        marker_id: pos for marker_id, pos in layout.items()
-        if marker_id not in removed_ids
-        and (not marker_id.startswith("v_")
-             or marker_id in virtual_ids
-             or marker_id in explicit_live_ids)
-    }
+    return live_layout(config, layout)
 
 
 @websocket_api.websocket_command({vol.Required("type"): "houseplan/layout/get"})
@@ -155,6 +525,7 @@ async def ws_layout_get(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
             "layout": data.get("layout", {}),
             "rev": int(data.get("rev", 0)),
             "can_optimize_undo": _optimizer_backup_is_current(config_data, data),
+            "undo_kind": _undo_kind(config_data, data),
         }
     )
 
@@ -192,9 +563,10 @@ async def ws_layout_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
             return
         layout = _live_layout(config_data.get("config") or {}, msg["layout"])
         new_rev = current_rev + 1
-        await rt.store.async_save({**{k: v for k, v in data.items() if k not in (
-                                       "layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)},
-                                   "layout": layout, "rev": new_rev})
+        await async_save_layout_state(
+            rt, data, layout, new_rev,
+            remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING),
+        )
     hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
     connection.send_result(msg["id"], {"ok": True, "rev": new_rev})
 
@@ -256,9 +628,10 @@ async def ws_layout_update(hass: HomeAssistant, connection, msg: dict[str, Any])
         # optimistic locking on layout/set meaningless — every drag reset the
         # counter to 0 (HP-1454-08)
         new_rev = int(data.get("rev", 0)) + 1
-        await rt.store.async_save({**{k: v for k, v in data.items() if k not in (
-                                       "layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)},
-                                   "layout": layout, "rev": new_rev})
+        await async_save_layout_state(
+            rt, data, layout, new_rev,
+            remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING),
+        )
     hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
     connection.send_result(msg["id"], {"ok": True, "rev": new_rev})
 
@@ -270,6 +643,7 @@ async def ws_layout_update(hass: HomeAssistant, connection, msg: dict[str, Any])
         vol.Required("aspect"): vol.All(vol.Coerce(float), vol.Range(min=0.05, max=20)),
         vol.Optional("dry_run"): bool,
         vol.Optional("undo"): bool,
+        vol.Optional("expected_rev"): int,
     }
 )
 @websocket_api.async_response
@@ -302,6 +676,12 @@ async def ws_geometry_repair(hass: HomeAssistant, connection, msg: dict[str, Any
         data = await rt.store.async_load() or {}
         layout = data.get("layout") or {}
         current_rev = int(data.get("rev", 0))
+        if "expected_rev" in msg and msg["expected_rev"] != current_rev:
+            connection.send_error(
+                msg["id"], "conflict",
+                f"Layout was changed in another window (rev {current_rev} != {msg['expected_rev']})",
+            )
+            return
         if msg.get("undo"):
             backup = data.get("repair_backup")
             if not isinstance(backup, dict) or backup.get("space") != space_id:
@@ -311,7 +691,11 @@ async def ws_geometry_repair(hass: HomeAssistant, connection, msg: dict[str, Any
             for key, pos in (backup.get("positions") or {}).items():
                 restored[key] = pos
             new_rev = current_rev + 1
-            await rt.store.async_save({"layout": restored, "rev": new_rev})
+            await async_save_layout_state(
+                rt, data, restored, new_rev,
+                metadata=_optimizer_backup_after_layout_maintenance(data, new_rev),
+                remove=("repair_backup",),
+            )
             hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
             connection.send_result(msg["id"], {"ok": True, "rev": new_rev,
                                                "restored": len(backup.get("positions") or {})})
@@ -343,10 +727,14 @@ async def ws_geometry_repair(hass: HomeAssistant, connection, msg: dict[str, Any
         # the backup rides the same store write: either both are durable or
         # neither — the deletion-shy rules of this project apply to positions
         # too
-        await rt.store.async_save({
-            "layout": new_layout, "rev": new_rev,
-            "repair_backup": {"space": space_id, "positions": touched},
-        })
+        await async_save_layout_state(
+            rt, data, new_layout, new_rev,
+            metadata={
+                **_optimizer_backup_after_layout_maintenance(data, new_rev),
+                "repair_backup": {"space": space_id, "positions": touched},
+            },
+            remove=("repair_backup",),
+        )
     hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
     connection.send_result(msg["id"], {"ok": True, "rev": new_rev, "moved": len(preview)})
 
@@ -654,9 +1042,10 @@ async def ws_layout_delete(hass: HomeAssistant, connection, msg: dict[str, Any])
         if msg["device_id"] in layout:
             del layout[msg["device_id"]]
             new_rev = int(data.get("rev", 0)) + 1
-            await rt.store.async_save({**{k: v for k, v in data.items() if k not in (
-                                           "layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)},
-                                       "layout": layout, "rev": new_rev})
+            await async_save_layout_state(
+                rt, data, layout, new_rev,
+                remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING),
+            )
     if new_rev is not None:
         hass.bus.async_fire("houseplan_layout_updated", {"rev": new_rev})
     connection.send_result(msg["id"], {"ok": True, "rev": new_rev})
@@ -677,20 +1066,71 @@ async def ws_config_get(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
     rt = _runtime(hass, connection, msg["id"])
     if rt is None:
         return
-    data = await rt.config_store.async_load() or {}
-    layout_data = await rt.store.async_load() or {}
-    config = {**DEFAULT_CONFIG, **data.get("config", {})}
+    async with rt.write_lock:
+        data = await rt.config_store.async_load() or {}
+        layout_data = await rt.store.async_load() or {}
+        config = {**DEFAULT_CONFIG, **data.get("config", {})}
+        config_rev = int(data.get("rev", 0))
+        try:
+            virtual_lights = await async_virtual_light_snapshot(
+                rt.virtual_light_store,
+                config,
+                config_rev,
+            )
+        except Exception:  # noqa: BLE001 - config remains independently readable
+            _LOGGER.exception("House Plan: reading virtual-light state failed")
+            # Never expose a stale off bit after an unreadable/revision-gap
+            # operational store. Compatibility/default on is the safe frame.
+            virtual_lights = {"rev": 0, "config_rev": config_rev, "off": []}
     connection.send_result(
         msg["id"],
         {
             "config": config,
-            "rev": data.get("rev", 0),
+            "rev": config_rev,
+            "virtual_lights": virtual_lights,
             "can_write": may_write(hass, getattr(connection, "user", None)),
             "can_optimize_undo": _optimizer_backup_is_current(data, layout_data),
+            "undo_kind": _undo_kind(data, layout_data),
         },
     )
 
 
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "houseplan/virtual_light/toggle",
+        vol.Required("marker_id"): vol.All(str, vol.Length(min=1, max=500)),
+    }
+)
+@websocket_api.async_response
+async def ws_virtual_light_toggle(
+    hass: HomeAssistant, connection, msg: dict[str, Any]
+) -> None:
+    """Atomically toggle one eligible virtual light for any signed-in user."""
+    rt = _runtime(hass, connection, msg["id"])
+    if rt is None:
+        return
+    async with rt.write_lock:
+        data = await rt.config_store.async_load() or {}
+        config = {**DEFAULT_CONFIG, **data.get("config", {})}
+        result = await async_toggle_virtual_light(
+            rt.virtual_light_store,
+            config,
+            int(data.get("rev", 0)),
+            msg["marker_id"],
+        )
+        if result is None:
+            connection.send_error(
+                msg["id"],
+                "not_toggleable",
+                "Marker is not an active virtual light with tap_action=toggle",
+            )
+            return
+    # Both the reply and event follow the durable Store write.  There is no
+    # optimistic client state, so all cards converge on this revision.
+    connection.send_result(msg["id"], result)
+    hass.bus.async_fire(EVENT_VIRTUAL_LIGHT_UPDATED, result)
+
+
 
 def _internal_plan_names(config: dict[str, Any]) -> set[str]:
     """Plan file names a configuration names through OUR urls.
@@ -732,6 +1172,30 @@ def _missing_internal_plans(
     }
 
 
+def _missing_internal_attachments(
+    config_root: Path, config: dict[str, Any], previous: dict[str, Any] | None = None
+) -> set[str]:
+    """New local attachments that vanished between import preview and apply.
+
+    Existing broken references stay writable for the same reason as historical
+    plan URLs: refusing every unrelated write would prevent the user from
+    detaching or repairing them.
+    """
+    known = {
+        str(item["url"])
+        for item in content_manifest(previous or {}, config_root)
+        if item.get("kind") == "attachment" and item.get("storage") == "internal"
+    }
+    return {
+        str(item["url"])
+        for item in content_manifest(config, config_root)
+        if item.get("kind") == "attachment"
+        and item.get("storage") == "internal"
+        and item.get("exists_at_export") is False
+        and str(item["url"]) not in known
+    }
+
+
 @websocket_api.websocket_command(
     {
         vol.Required("type"): "houseplan/config/set",
@@ -781,6 +1245,16 @@ async def ws_config_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
                 f"Configuration was changed in another window (rev {current_rev} != {msg['expected_rev']})",
             )
             return
+        # Marker-to-marker light links are a semantic graph layered on top of
+        # the lossless controls array. Validate only edges introduced by this
+        # write so an unrelated edit can still round-trip a legacy broken ref.
+        try:
+            validate_marker_controls(msg["config"], data.get("config"))
+            validate_marker_light_entities(msg["config"], data.get("config"))
+            validate_marker_value_badges(msg["config"], data.get("config"))
+        except MarkerControlError as err:
+            connection.send_error(msg["id"], err.code, str(err))
+            return
         # An internal plan url must name a file that exists. The card can pick a
         # plan and then delete it from the same dialog, and two clients can do
         # the same thing in either order — the lock serialises them but says
@@ -799,7 +1273,12 @@ async def ws_config_set(hass: HomeAssistant, connection, msg: dict[str, Any]) ->
             )
             return
         new_rev = current_rev + 1
-        await rt.config_store.async_save({"config": msg["config"], "rev": new_rev})
+        await async_save_config_state(
+            rt,
+            msg["config"],
+            new_rev,
+            previous_rev=int(current_rev),
+        )
         try:
             await _discard_optimizer_snapshot(rt)
         except Exception:  # noqa: BLE001 — stale backup cleanup is best-effort
@@ -876,6 +1355,17 @@ async def ws_plan_optimize(hass: HomeAssistant, connection, msg: dict[str, Any])
             )
             return
 
+        # Optimization is a normal configuration write with an additional
+        # layout transaction. It must enforce the same marker-link semantics
+        # as config/set; otherwise a crafted client can persist a new cycle.
+        try:
+            validate_marker_controls(msg["config"], config_data.get("config"))
+            validate_marker_light_entities(msg["config"], config_data.get("config"))
+            validate_marker_value_badges(msg["config"], config_data.get("config"))
+        except MarkerControlError as err:
+            connection.send_error(msg["id"], err.code, str(err))
+            return
+
         missing = await hass.async_add_executor_job(
             _missing_internal_plans,
             Path(hass.config.path(PLANS_DIR)),
@@ -892,6 +1382,7 @@ async def ws_plan_optimize(hass: HomeAssistant, connection, msg: dict[str, Any])
         new_config_rev = config_rev + 1
         new_layout_rev = layout_rev + 1
         backup = {
+            "kind": "optimize",
             "config": config_data.get("config") or DEFAULT_CONFIG,
             "layout": layout_data.get("layout", {}),
             "created": int(time.time()),
@@ -901,29 +1392,28 @@ async def ws_plan_optimize(hass: HomeAssistant, connection, msg: dict[str, Any])
         pending = {
             "config": msg["config"],
             "layout": msg["layout"],
+            "config_rev": new_config_rev,
+            "layout_rev": new_layout_rev,
             "clear_backup": False,
         }
-        layout_meta = {
-            k: v for k, v in layout_data.items()
-            if k not in ("layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)
-        }
-
         # Intent first. A setup-time finisher completes whichever half a crash
         # interrupted; until then the visible layout/revision remain unchanged.
-        await rt.store.async_save({
-            **layout_meta,
-            "layout": layout_data.get("layout", {}),
-            "rev": layout_rev,
-            _OPTIMIZE_BACKUP: backup,
-            _OPTIMIZE_PENDING: pending,
-        })
-        await rt.config_store.async_save({"config": msg["config"], "rev": new_config_rev})
-        await rt.store.async_save({
-            **layout_meta,
-            "layout": msg["layout"],
-            "rev": new_layout_rev,
-            _OPTIMIZE_BACKUP: backup,
-        })
+        await async_save_layout_state(
+            rt, layout_data, layout_data.get("layout", {}), layout_rev,
+            metadata={_OPTIMIZE_BACKUP: backup, _OPTIMIZE_PENDING: pending},
+            remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING),
+        )
+        await async_save_config_state(
+            rt,
+            msg["config"],
+            new_config_rev,
+            previous_rev=config_rev,
+        )
+        await async_save_layout_state(
+            rt, layout_data, msg["layout"], new_layout_rev,
+            metadata={_OPTIMIZE_BACKUP: backup},
+            remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING, "repair_backup", "geom_pending"),
+        )
 
     hass.bus.async_fire("houseplan_config_updated", {"rev": new_config_rev})
     hass.bus.async_fire("houseplan_layout_updated", {"rev": new_layout_rev})
@@ -953,6 +1443,7 @@ async def ws_plan_optimize_undo(hass: HomeAssistant, connection, msg: dict[str,
     if rt is None:
         return
 
+    restored_kind = "optimize"
     async with rt.write_lock:
         config_data = await rt.config_store.async_load() or {}
         layout_data = await rt.store.async_load() or {}
@@ -969,36 +1460,55 @@ async def ws_plan_optimize_undo(hass: HomeAssistant, connection, msg: dict[str,
             return
 
         backup = layout_data[_OPTIMIZE_BACKUP]
+        restored_kind = str(backup.get("kind") or "optimize")
         restored_config = backup.get("config") or DEFAULT_CONFIG
         restored_layout = backup.get("layout") or {}
         new_config_rev = config_rev + 1
         new_layout_rev = layout_rev + 1
         pending = {
+            "kind": "import_undo" if restored_kind == "import" else "optimize_undo",
             "config": restored_config,
             "layout": restored_layout,
+            "config_rev": new_config_rev,
+            "layout_rev": new_layout_rev,
             "clear_backup": True,
         }
-        layout_meta = {
-            k: v for k, v in layout_data.items()
-            if k not in ("layout", "rev", _OPTIMIZE_BACKUP, _OPTIMIZE_PENDING)
-        }
-        await rt.store.async_save({
-            **layout_meta,
-            "layout": layout_data.get("layout", {}),
-            "rev": layout_rev,
-            _OPTIMIZE_BACKUP: backup,
-            _OPTIMIZE_PENDING: pending,
-        })
-        await rt.config_store.async_save({"config": restored_config, "rev": new_config_rev})
-        await rt.store.async_save({
-            **layout_meta,
-            "layout": restored_layout,
-            "rev": new_layout_rev,
-        })
+        await async_save_layout_state(
+            rt, layout_data, layout_data.get("layout", {}), layout_rev,
+            metadata={_OPTIMIZE_BACKUP: backup, _OPTIMIZE_PENDING: pending},
+            remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING),
+        )
+        await async_save_config_state(
+            rt,
+            restored_config,
+            new_config_rev,
+            previous_rev=config_rev,
+        )
+        await async_save_layout_state(
+            rt, layout_data, restored_layout, new_layout_rev,
+            remove=(_OPTIMIZE_BACKUP, _OPTIMIZE_PENDING, "repair_backup"),
+        )
 
     hass.bus.async_fire("houseplan_config_updated", {"rev": new_config_rev})
     hass.bus.async_fire("houseplan_layout_updated", {"rev": new_layout_rev})
     _refresh_trail_recorder(hass)
+    if restored_kind == "import":
+        recorder = hass.data.get(DOMAIN, {}).get("trail_recorder")
+        live_marker_ids = {
+            str(marker.get("id")) for marker in restored_config.get("markers") or []
+        }
+        if recorder is not None:
+            for marker_id in list(getattr(getattr(recorder, "book", None), "data", {})):
+                if marker_id not in live_marker_ids:
+                    try:
+                        await recorder.async_delete(marker_id)
+                    except Exception:  # noqa: BLE001
+                        _LOGGER.exception("House Plan: removing orphan undo trail failed")
+        entry = get_entry(hass)
+        if entry is not None:
+            from .repairs import async_check_plan_files
+
+            hass.async_create_task(async_check_plan_files(hass, entry))
     connection.send_result(msg["id"], {
         "ok": True,
         "config_rev": new_config_rev,

demo/benchmark_glow.mjs

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

demo/benchmark_large_house.mjs

@@ -1,17 +1,23 @@
 #!/usr/bin/env node
 /** Reproducible browser benchmark and report producer for HP-PERF-01. */
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { launch } from './serve.mjs';
 import { LARGE_HOUSE_COUNTS, makeLargeHouseFixture } from './fixtures/large-house.mjs';
 import { assertFreshDemoBundle } from './bundle-freshness.mjs';
 import { summarizeLongTasks, summarizeTimings } from './performance/evaluate.mjs';
+import { assertCardContract, LARGE_HOUSE_CARD_CONTRACT } from './performance/card-contract.mjs';
 
 const valueArg = (name) => process.argv.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
 const samples = Math.max(1, Math.min(20, Number(valueArg('samples')) || 7));
 const warmups = Math.max(0, Math.min(5, Number(valueArg('warmups')) || 1));
 const output = valueArg('output') ? resolve(valueArg('output')) : null;
 const targetRoot = resolve(valueArg('target-root') ?? '.');
+const profile = valueArg('profile') ?? 'large-house-v1';
+if (!['large-house-v1', 'large-house-isometric-v1'].includes(profile))
+  throw new Error(`unknown large-house profile: ${profile}`);
+const isometric = profile === 'large-house-isometric-v1';
+const requiresIsometric = isometric && existsSync(resolve(targetRoot, 'src/iso-projection.ts'));
 const fixture = makeLargeHouseFixture();
 const viewport = { width: 1440, height: 1000 };
 
@@ -26,6 +32,9 @@ 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 {
@@ -39,7 +48,7 @@ const rows = [];
 try {
   for (let iteration = 0; iteration < warmups + samples; iteration++) {
     const measuredSample = iteration - warmups;
-    const row = await page.evaluate(async ({ fixture, sample }) => {
+    const row = await page.evaluate(async ({ fixture, sample, cardContract, isometric, requiresIsometric }) => {
       const frame = () => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
       const until = async (predicate, timeout = 10000) => {
         const started = performance.now();
@@ -94,10 +103,18 @@ try {
         wallUnion: card._wallUnionCache ? 1 : 0,
         openingTunnel: card._openingTunnelCache ? 1 : 0,
         openingWallIndex: card._openingWallIndexCache ? 1 : 0,
+        isoGeometry: card._isoGeometryCache?.size ?? 0,
       });
 
       window.__card?.remove?.();
       localStorage.clear();
+      if (isometric) {
+        localStorage.setItem('houseplan_card_labs_v1', JSON.stringify(['iso']));
+        localStorage.setItem('houseplan_card_view_v1', JSON.stringify(Object.fromEntries(
+          fixture.config.spaces.map((space) => [space.id, 'iso']),
+        )));
+        history.replaceState(null, '', '?hp-labs=iso');
+      } else history.replaceState(null, '', location.pathname);
       const host = document.getElementById('host');
       const card = document.createElement('houseplan-card');
       card.setConfig({
@@ -139,6 +156,11 @@ try {
       const loadStarted = performance.now();
       host.replaceChildren(card);
       card.hass = hassFor(fixture.states);
+      window.__hpAssertCardContract(card, cardContract);
+      if (requiresIsometric && (typeof card._setProjection !== 'function'
+          || !(card._isoGeometryCache instanceof Map))) {
+        throw new Error('large-house-isometric-v1 candidate has no renderer contract');
+      }
       await until(() => card._loadOk && card._model?.length === fixture.counts.floors);
       await card.updateComplete;
       await frame();
@@ -147,6 +169,18 @@ try {
       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;
@@ -244,6 +278,7 @@ try {
         sample,
         modelReadyMs,
         firstStableRenderMs,
+        ...(viewToggle ? { viewToggleMs: viewToggle.ms } : {}),
         spaceSwitchMs: spaceSwitch.ms,
         stateUpdateMs: stateUpdate.ms,
         resizePreviewMs: resizePreview.ms,
@@ -252,6 +287,7 @@ try {
         switchCycleMs: switchCycle.ms,
         longTasks: {
           load: loadLongTaskResult,
+          ...(viewToggle ? { viewToggle: viewToggle.longTasks } : {}),
           spaceSwitch: spaceSwitch.longTasks,
           stateUpdate: stateUpdate.longTasks,
           resizePreview: resizePreview.longTasks,
@@ -268,7 +304,10 @@ try {
       card.remove();
       await frame();
       return result;
-    }, { fixture, sample: measuredSample });
+    }, {
+      fixture, sample: measuredSample, cardContract: LARGE_HOUSE_CARD_CONTRACT,
+      isometric, requiresIsometric,
+    });
     if (measuredSample >= 0) rows.push(row);
   }
 } finally {
@@ -279,9 +318,10 @@ const metricNames = [
   'modelReadyMs', 'firstStableRenderMs', 'spaceSwitchMs', 'stateUpdateMs',
   'resizePreviewMs', 'panZoomMs', 'settingsDialogMs', 'switchCycleMs',
 ];
+if (isometric) metricNames.splice(2, 0, 'viewToggleMs');
 const report = {
   schema: 2,
-  profile: 'large-house-v1',
+  profile,
   generatedAt: new Date().toISOString(),
   buildFingerprint,
   runtime: {
@@ -299,7 +339,7 @@ const report = {
   summary: summarizeTimings(rows, metricNames),
   longTasks: summarizeLongTasks(rows),
   rows,
-  note: 'Compare with a base-SHA report captured by the same runner and evaluate demo/performance/budgets.json.',
+  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`;

demo/bundle-freshness.mjs

@@ -1,8 +1,24 @@
+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()) {
-  const expected = sourceFingerprint(root);
+  // 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/fixtures/large-house.mjs

@@ -223,8 +223,15 @@ export const makeLargeHouseFixture = () => {
     };
   });
   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: [], settings: { glow_radius_cm: 300 } },
+    config: { spaces, markers: lightMarkers, settings: { glow_radius_cm: 300 } },
     ...runtime,
     counts: LARGE_HOUSE_COUNTS,
   };

demo/fixtures/visual-matrix.mjs

@@ -2,6 +2,25 @@
 
 const round = (value) => Number(value.toFixed(6));
 
+// Golden fixtures must use the same persisted wall-key contract as real plan
+// data. Arbitrary labels make every configured wall look virtual to the
+// renderer, which lets a visually ineffective baseline pass unnoticed.
+const WALL_KEY_PITCH = 1 / 240;
+export const fixtureWallKey = (a, b) => {
+  const quantize = (value) => Math.round(value / WALL_KEY_PITCH) * WALL_KEY_PITCH;
+  const mx = quantize((a[0] + b[0]) / 2);
+  const my = quantize((a[1] + b[1]) / 2);
+  let dx = b[0] - a[0], dy = b[1] - a[1];
+  const length = Math.hypot(dx, dy);
+  if (length < 1e-12) { dx = 1; dy = 0; }
+  else { dx /= length; dy /= length; }
+  if (dx < -1e-12 || (Math.abs(dx) <= 1e-12 && dy < 0)) { dx = -dx; dy = -dy; }
+  let angle = Math.atan2(dy, dx);
+  if (angle < 0) angle += Math.PI;
+  const bucket = Math.round(angle * 1800) / 1800;
+  return `${mx.toFixed(4)},${my.toFixed(4)}@${bucket.toFixed(4)}`;
+};
+
 const uniqueEdges = (rooms) => {
   const edges = new Map();
   for (const room of rooms) {
@@ -16,7 +35,7 @@ const uniqueEdges = (rooms) => {
 };
 
 const wallsFor = (prefix, rooms, thickness) => uniqueEdges(rooms).map((edge, index) => ({
-  key: `${prefix}-wall-${index}`,
+  key: fixtureWallKey(edge.a, edge.b),
   a: edge.a,
   b: edge.b,
   cm: typeof thickness === 'function' ? thickness(edge, index) : thickness,
@@ -82,7 +101,7 @@ const lightingSpace = {
   view_box: [0, 0, 1, 1],
   cell_cm: 5,
   settings: {
-    fill_mode: 'glow', show_borders: true, show_names: true,
+    fill_mode: 'none', glow_enabled: true, show_borders: true, show_names: true,
     north_deg: 0, sun_rays: true, bg_mode: 'static',
   },
   rooms: lightingRooms,
@@ -112,6 +131,9 @@ const runtime = () => {
       attributes: { azimuth: 180, elevation: 24 },
     },
   };
+  // Keep sun.sun state-only on purpose. Core/runtime entities and YAML
+  // entities without unique_id may have a live state without a registry row.
+  // The production projection must preserve them.
   const layout = {};
   const areas = Object.fromEntries(
     [...geometryRooms, ...lightingRooms].map((room) => [room.area, { area_id: room.area, name: room.name }]),
@@ -163,7 +185,10 @@ export const VISUAL_MATRIX_COUNTS = Object.freeze({
 export const makeVisualMatrixFixture = () => ({
   config: {
     spaces: [structuredClone(geometrySpace), structuredClone(lightingSpace)],
-    markers: [],
+    // 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,

demo/golden/README.md

@@ -4,7 +4,13 @@ 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.
+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
 
@@ -48,3 +54,8 @@ 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/baselines/baseline-manifest.json

@@ -1,35 +0,0 @@
-{
-  "schema": 1,
-  "matrixVersion": 3,
-  "acceptedAt": "2026-08-09T12:30:01.505Z",
-  "sourceFingerprint": "f1969cf05ab483dd1bf24d32d967f931f1e3c9ce37cd3f61d4b851f1eae417ee",
-  "chromium": "151.0.7922.34",
-  "scenarios": {
-    "geometry-view-dark-fit": "fbce77f97180cd7d50a997c74d3fa1874ee3be2515a4c09b36dd4e792ebc66df",
-    "geometry-view-light-fit": "a425fa6d77081bb35d2fb81e469962402c6a3c86a8113ff957f28548908d0816",
-    "geometry-plan-editor-dark": "86d64305e4da13436aef14fe96b2c9eb5978d1d32a0bba2318005421a2fda161",
-    "geometry-devices-editor-dark": "93417ab7363ca50e65c9d6f0b876f4d5a6a367a8fabdf42306b244e6511693f1",
-    "geometry-decor-editor-dark": "25d341052e30e7acea13c17897e8bd0f1f08235342b949c02afd3db5b9936c64",
-    "tray-wide-selection-en": "c7350c3661f17f46d22b2c977524fde9fba1ebf9d6e10f021482f0d1caeffa8a",
-    "tray-wide-tool-ru": "5472a302ad7e7b70235089164a5c4558183504519d95280e8ff30883e304cb71",
-    "tray-medium-group-en": "59480e04ff5ea0f2cfb31b88c1c753ce8eeac785596ca21eac48dd99ec5e0eb6",
-    "tray-medium-selection-ru": "805c23560bc340582f9b951e910f39245ab62b6cd980d175c8d9e3b7e1ef1519",
-    "tray-narrow-palette-en": "e8dede0d90ebc32e1e294ba3c39621df918aaf7b3183f71aed9b60014eee51db",
-    "tray-narrow-tool-ru": "8889d58aca90daadf0bedd6a7c08afb2604c086a453f9435f32d29607aa49e42",
-    "geometry-diagonal-45-opening-dark": "fbce77f97180cd7d50a997c74d3fa1874ee3be2515a4c09b36dd4e792ebc66df",
-    "openings-thick-wall-dark": "5d9ac6add9a5709318180f4554ac62c1c7e2862bd016be7901a2bd450e021f0c",
-    "openings-hidden-view-dark": "799e791830ab63a1c445b8c77650a577d8e881daa1ff47d1dcf4e238eb1cff16",
-    "lighting-glow-sun-dark": "638ab9fa6856f91581453c732e4059b2a7af47b20d6a58b45a47497876142ea1",
-    "lighting-fill-light-axis-split-dark": "acdbebe845ede66dbbe9de979aad93ba78dc2779d1ec533b238a9bea0d047d1c",
-    "lighting-fill-temp-axis-split-dark": "2348b7c6a8594468664755e2fea1b49126e604192599be0a3965f24a0c2d2765",
-    "lighting-fill-lqi-axis-split-dark": "584adcfb5541b1dddc814c2674bfce8002566bbb667b10501b7ff49fedef6f9c",
-    "hover-over-glow-dark": "3ca354fa94922a3e38ce15886250ae88630a1e9356e4ac07b74b425f063839d7",
-    "hover-nested-room-dark": "472f630768f60c3168f64744af891323a64cf71f36f943fc5a56b4f0494efa70",
-    "large-house-zoom-040-dark": "69593f75f1965daf0a12777fde923ae25c99b42089a73a04cf523b3ea5ce4f0d",
-    "large-house-zoom-250-dark": "21a1a0408c913f477913ae9c0339417ae7aaad7baad8a890eb558f6e36a5a597",
-    "large-house-warm-remount-dark": "f3eb077934701cf11bc828da6a68b55346d499a68c323988938b88aca5f5d9fe",
-    "device-dialog-desktop-en": "c2e1c2864f13b9e27e0d56e3eb7a7b245feab0d543f5533a7b3c4aa34ab2f3eb",
-    "device-dialog-mobile-ru": "5445eb576636362d402f66aa80c3816e01ca7ee75f4ffc86708ff3a43bbfb4a5",
-    "decor-color-popover-mobile-ru": "eab3c5c76b27050dbdbc1627371a16916ea30473934de48842c6ab94a045f9db"
-  }
-}

demo/golden/baselines/baselines-index.json

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

demo/golden/harness.mjs

@@ -1,5 +1,5 @@
 import { makeLargeHouseFixture } from '../fixtures/large-house.mjs';
-import { makeVisualMatrixFixture } from '../fixtures/visual-matrix.mjs';
+import { fixtureWallKey, makeVisualMatrixFixture } from '../fixtures/visual-matrix.mjs';
 
 const fixtureFor = (name) => name === 'large' ? makeLargeHouseFixture() : makeVisualMatrixFixture();
 
@@ -48,19 +48,172 @@ async function stableEnvironment(page, scenario) {
   }, { variables: themeVars[scenario.theme] || themeVars.dark, theme: scenario.theme });
 }
 
-export async function prepareGoldenScenario(page, scenario) {
-  await stableEnvironment(page, scenario);
+/** Apply every data-only scenario override before the fixture crosses into the browser. */
+export function prepareGoldenFixture(scenario) {
   const fixture = fixtureFor(scenario.fixture);
-  if (scenario.deviceName && fixture.devices?.[scenario.deviceId])
-    fixture.devices[scenario.deviceId].name = scenario.deviceName;
-  if (scenario.fillMode) {
+  if (scenario.cornerSplitWall) {
+    const stage = scenario.cornerSplitWall;
+    if (!['before', 'thin', 'thick'].includes(stage))
+      throw new Error(`unknown cornerSplitWall stage: ${stage}`);
+    const a = [0.10, 0.10], tr = [0.90, 0.10], split = [0.90, 0.50];
+    const br = [0.90, 0.90], bl = [0.10, 0.90];
+    const entry = (from, to, cm) => ({
+      key: fixtureWallKey(from, to), a: [...from], b: [...to], cm,
+    });
+    const before = stage === 'before';
+    fixture.config.spaces.push({
+      id: scenario.space,
+      name: 'Corner Split',
+      rooms: before
+        ? [{ id: 'corner-source', name: 'Before Split', area: null, poly: [a, tr, br, bl] }]
+        : [
+          { id: 'corner-source', name: 'Main room', area: null, poly: [a, tr, split] },
+          { id: 'corner-fresh', name: 'New room', area: null, poly: [split, br, bl, a] },
+        ],
+      walls: before
+        ? [entry(a, tr, 15), entry(tr, br, 15), entry(br, bl, 15), entry(bl, a, 15)]
+        : [
+          entry(a, tr, 15), entry(tr, split, 15), entry(split, br, 15),
+          entry(br, bl, 15), entry(bl, a, 15), entry(a, split, stage === 'thin' ? 15 : 100),
+        ],
+      settings: { show_borders: true, fill_mode: 'custom', custom_fill: { c: '#536b82', a: 0.42 } },
+    });
+  }
+  const requireSpace = () => {
     const space = fixture.config.spaces.find((item) => item.id === scenario.space);
-    space.settings = { ...(space.settings || {}), fill_mode: scenario.fillMode };
+    if (!space) throw new Error(`golden override references missing space: ${scenario.space}`);
+    return space;
+  };
+  if (scenario.deviceName) {
+    if (!scenario.deviceId || !fixture.devices?.[scenario.deviceId])
+      throw new Error(`golden deviceName references missing device: ${scenario.deviceId || '<empty>'}`);
+    fixture.devices[scenario.deviceId].name = scenario.deviceName;
+  }
+  if (scenario.fillMode || typeof scenario.glowEnabled === 'boolean'
+      || typeof scenario.sunRays === 'boolean' || typeof scenario.showBorders === 'boolean') {
+    const space = requireSpace();
+    space.settings = {
+      ...(space.settings || {}),
+      ...(scenario.fillMode ? { fill_mode: scenario.fillMode } : {}),
+      ...(typeof scenario.glowEnabled === 'boolean' ? { glow_enabled: scenario.glowEnabled } : {}),
+      ...(typeof scenario.sunRays === 'boolean' ? { sun_rays: scenario.sunRays } : {}),
+      ...(typeof scenario.showBorders === 'boolean' ? { show_borders: scenario.showBorders } : {}),
+      ...(scenario.customFill ? { custom_fill: scenario.customFill } : {}),
+    };
+  }
+  if (scenario.extraOpenings?.length) {
+    const space = requireSpace();
+    const known = new Set((space.openings || []).map((opening) => opening.id));
+    for (const opening of scenario.extraOpenings) {
+      if (!opening?.id || known.has(opening.id))
+        throw new Error(`golden extraOpening has missing/duplicate id: ${opening?.id || '<empty>'}`);
+      if (!['door', 'window', 'gate'].includes(opening.type))
+        throw new Error(`golden extraOpening has unknown type: ${opening.type}`);
+      known.add(opening.id);
+    }
+    space.openings = [...(space.openings || []), ...structuredClone(scenario.extraOpenings)];
+  }
+  if (scenario.openingGeometry) {
+    const space = requireSpace();
+    const opening = (space.openings || []).find(
+      (item) => item.id === scenario.openingGeometry.id,
+    );
+    if (!opening || opening.type !== scenario.openingGeometry.type
+        || Math.abs(Number(opening.angle) - scenario.openingGeometry.angle) > 0.001) {
+      throw new Error(
+        `golden openingGeometry references a missing/mismatched opening: `
+        + `${scenario.openingGeometry.id}`,
+      );
+    }
+    // This scenario must not remain byte-identical to the generic geometry
+    // capture: isolate the intended diagonal symbol in the rendered fixture.
+    space.openings = [opening];
+  }
+  if (scenario.wallReplacements?.length) {
+    const space = requireSpace();
+    const samePoint = (a, b) => Array.isArray(a) && Array.isArray(b)
+      && Math.abs(a[0] - b[0]) < 1e-9 && Math.abs(a[1] - b[1]) < 1e-9;
+    for (const replacement of scenario.wallReplacements) {
+      const index = (space.walls || []).findIndex((wall) => (
+        samePoint(wall.a, replacement.match?.a) && samePoint(wall.b, replacement.match?.b)
+      ) || (
+        samePoint(wall.a, replacement.match?.b) && samePoint(wall.b, replacement.match?.a)
+      ));
+      if (index < 0 || !replacement.segments?.length)
+        throw new Error(`golden wallReplacement cannot find a valid wall in ${space.id}`);
+      space.walls.splice(index, 1, ...structuredClone(replacement.segments));
+    }
   }
   if (scenario.hideOpenings) {
-    const space = fixture.config.spaces.find((item) => item.id === scenario.space);
+    const space = requireSpace();
     space.settings = { ...(space.settings || {}), hide_openings: true };
   }
+  if (scenario.roomGlow) {
+    const space = requireSpace();
+    const unknown = new Set(Object.keys(scenario.roomGlow));
+    for (const room of space.rooms) {
+      if (!(room.id in scenario.roomGlow)) continue;
+      unknown.delete(room.id);
+      room.settings = { ...(room.settings || {}), glow: scenario.roomGlow[room.id] };
+    }
+    if (unknown.size) throw new Error(`golden roomGlow references missing room(s): ${[...unknown].join(', ')}`);
+  }
+  if (scenario.roomCustomFill) {
+    const space = requireSpace();
+    const unknown = new Set(Object.keys(scenario.roomCustomFill));
+    for (const room of space.rooms) {
+      if (!(room.id in scenario.roomCustomFill)) continue;
+      unknown.delete(room.id);
+      room.settings = { ...(room.settings || {}), custom_fill: scenario.roomCustomFill[room.id] };
+    }
+    if (unknown.size)
+      throw new Error(`golden roomCustomFill references missing room(s): ${[...unknown].join(', ')}`);
+  }
+  if (scenario.allLightsOff) {
+    for (const [entityId, state] of Object.entries(fixture.states || {})) {
+      if (!entityId.startsWith('light.')) continue;
+      fixture.states[entityId] = { ...state, state: 'off' };
+    }
+  }
+  if (scenario.stateOverrides) {
+    for (const [entityId, override] of Object.entries(scenario.stateOverrides)) {
+      const current = fixture.states?.[entityId];
+      if (!current) throw new Error(`golden stateOverride references missing entity: ${entityId}`);
+      fixture.states[entityId] = {
+        ...current,
+        ...structuredClone(override),
+        attributes: { ...(current.attributes || {}), ...(override.attributes || {}) },
+      };
+    }
+  }
+  if (scenario.markerOverrides) {
+    const ids = new Set(scenario.markerOverrides.map((marker) => marker.id));
+    // Runtime devices without explicit marker settings are still valid saved
+    // marker targets. A visual scenario may materialize their first setting,
+    // just like the real device dialog does on save.
+    const known = new Set([
+      ...(fixture.config.markers || []).map((marker) => marker.id),
+      ...Object.keys(fixture.devices || {}),
+    ]);
+    const missing = [...ids].filter((id) => !known.has(id));
+    if (missing.length) throw new Error(`golden markerOverrides reference missing marker(s): ${missing.join(', ')}`);
+    fixture.config.markers = [
+      ...(fixture.config.markers || []).filter((marker) => !ids.has(marker.id)),
+      ...structuredClone(scenario.markerOverrides),
+    ];
+  }
+  if (scenario.layoutOverrides) {
+    const missing = Object.keys(scenario.layoutOverrides).filter((id) => !(id in (fixture.layout || {})));
+    if (missing.length) throw new Error(`golden layoutOverrides reference missing item(s): ${missing.join(', ')}`);
+    fixture.layout = { ...(fixture.layout || {}), ...structuredClone(scenario.layoutOverrides) };
+  }
+
+  return fixture;
+}
+
+export async function prepareGoldenScenario(page, scenario) {
+  await stableEnvironment(page, scenario);
+  const fixture = prepareGoldenFixture(scenario);
 
   return page.evaluate(async ({ fixture, scenario }) => {
     const wait = (ms) => new Promise((done) => setTimeout(done, ms));
@@ -72,13 +225,29 @@ export async function prepareGoldenScenario(page, scenario) {
         await wait(15);
       }
     };
+    const settleMode = async (card) => {
+      await until(() => !card._modeTransitionBusy);
+      await card.updateComplete;
+      await frame();
+    };
     window.__goldenCard?.remove?.();
     window.__card?.remove?.();
     localStorage.clear();
+    history.replaceState(null, '', scenario.labs?.length
+      ? `?hp-labs=${encodeURIComponent(scenario.labs.join(','))}` : location.pathname);
+    if (scenario.labs?.length) {
+      localStorage.setItem('houseplan_card_labs_v1', JSON.stringify(scenario.labs));
+    }
+    if (scenario.projection && scenario.space) {
+      localStorage.setItem('houseplan_card_view_v1', JSON.stringify({
+        [scenario.space]: scenario.projection,
+      }));
+    }
     const host = document.getElementById('host');
     const cardConfig = {
       type: 'custom:houseplan-card', title: `Golden ${scenario.id}`, icon_size: 3.4,
       language: scenario.language || 'en',
+      ...(scenario.kiosk ? { kiosk: true } : {}),
     };
     const hassFor = () => ({
       language: scenario.language || 'en', locale: { language: scenario.language || 'en' },
@@ -137,12 +306,61 @@ export async function prepareGoldenScenario(page, scenario) {
     if (scenario.mode) {
       card._setMode(scenario.mode);
       await card.updateComplete;
+      await settleMode(card);
+    }
+    if (scenario.projection === 'iso' && typeof card._setProjection === 'function') {
+      card._setProjection('iso');
+      await card.updateComplete;
+      await frame();
     }
     if (Number.isFinite(scenario.zoom)) {
       card._applyView(scenario.zoom, 500, 500);
       card.requestUpdate();
       await card.updateComplete;
     }
+    if (scenario.openingPreview) {
+      const { type, pointer } = scenario.openingPreview;
+      if (!['window', 'door', 'gate'].includes(type)
+        || !Array.isArray(pointer) || pointer.length !== 2
+        || !pointer.every(Number.isFinite)) {
+        throw new Error(`invalid golden openingPreview: ${scenario.id}`);
+      }
+      card._activateOpeningPlacement(type);
+      card.requestUpdate();
+      await card.updateComplete;
+      await frame();
+      // Exercise the production pointer path after the toolbar update has
+      // settled. Writing `_cursorPt` before that update is racy: replacing the
+      // stage under Chromium's real pointer legitimately emits pointerleave
+      // and clears the preview before capture.
+      const svgRoot = card.renderRoot.querySelector('.stage svg');
+      const stage = card.renderRoot.querySelector('.stage');
+      const screen = new DOMPoint(pointer[0] * 1000, pointer[1] * card._spaceH)
+        .matrixTransform(svgRoot.getScreenCTM());
+      stage.dispatchEvent(new PointerEvent('pointermove', {
+        bubbles: true, composed: true, pointerId: 991, pointerType: 'mouse',
+        clientX: screen.x, clientY: screen.y,
+      }));
+      await card.updateComplete;
+      await frame();
+      const preview = card.renderRoot.querySelector(`.opening-preview[data-kind="${type}"]`);
+      if (!preview || !preview.querySelector('.op-leaf')) {
+        const intervals = card._openingPlacementIntervalsCache?.value || [];
+        const nearest = intervals.map((interval) => {
+          const [px, py] = card._cursorPt || [0, 0];
+          const [ax, ay] = interval.a, [bx, by] = interval.b;
+          const dx = bx - ax, dy = by - ay, length2 = dx * dx + dy * dy || 1;
+          const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / length2));
+          return {
+            a: interval.a, b: interval.b, cm: interval.cm, open: interval.open,
+            kind: interval.kind,
+            distance: Math.hypot(px - (ax + dx * t), py - (ay + dy * t)),
+          };
+        }).sort((a, b) => a.distance - b.distance).slice(0, 3);
+        throw new Error(`golden opening preview did not render: ${scenario.id}; `
+          + `cursor=${JSON.stringify(card._cursorPt)} nearest=${JSON.stringify(nearest)}`);
+      }
+    }
     if (scenario.editorTray) {
       let expectedKind = '';
       if (scenario.editorTray === 'plan-selection') {
@@ -202,19 +420,84 @@ export async function prepareGoldenScenario(page, scenario) {
     if (scenario.dialog === 'device') {
       card._setMode('devices');
       await card.updateComplete;
+      await settleMode(card);
       const device = card._devices.find((item) => item.id === scenario.deviceId);
       if (!device) throw new Error(`golden device missing: ${scenario.deviceId}`);
       card._openMarkerDialog(device);
       await card.updateComplete;
+      if (scenario.deviceLightControls) {
+        card._setMarkerLightRole('always');
+        await card.updateComplete;
+        card._setMarkerGlowMode('fixed');
+        await card.updateComplete;
+        const dialog = card.renderRoot.querySelector('hp-dialog');
+        const body = dialog?.querySelector('.body');
+        const roleGroup = dialog?.querySelector('input[name="marker-light-role"]')?.closest('fieldset');
+        const glowGroup = dialog?.querySelector('input[name="marker-glow-mode"]')?.closest('fieldset');
+        const roleInputs = roleGroup?.querySelectorAll('input[name="marker-light-role"]');
+        const glowInputs = glowGroup?.querySelectorAll('input[name="marker-glow-mode"]');
+        const color = glowGroup?.querySelector('hp-color-opacity');
+        const brightness = glowGroup?.querySelector('input[type="range"]');
+        const radius = dialog?.querySelector('#marker-glow-radius');
+        if (!body || !roleGroup || !glowGroup || roleInputs?.length !== 3 || glowInputs?.length !== 3
+          || !roleInputs[1]?.checked || !glowInputs[2]?.checked
+          || !color || color.disabled || !brightness || brightness.disabled || !radius || radius.disabled)
+          throw new Error('golden device light-source controls are incomplete');
+        const bodyRect = body.getBoundingClientRect();
+        const roleRect = roleGroup.getBoundingClientRect();
+        body.scrollTop += roleRect.top - bodyRect.top - 8;
+        await frame();
+        const visibleBody = body.getBoundingClientRect();
+        const visibleRole = roleGroup.getBoundingClientRect();
+        const visibleRadius = radius.getBoundingClientRect();
+        if (visibleRole.top < visibleBody.top - 1 || visibleRadius.bottom > visibleBody.bottom + 1)
+          throw new Error('golden viewport does not show the complete device light-source controls');
+      }
+      if (scenario.openHelp) {
+        const help = card.renderRoot.querySelector(`hp-help[data-help-key="${scenario.openHelp}"]`);
+        await help?.updateComplete;
+        const trigger = help?.renderRoot?.querySelector('.trigger');
+        if (!trigger) throw new Error(`golden help trigger missing: ${scenario.openHelp}`);
+        trigger.click();
+        await help.updateComplete;
+        await frame();
+        const surface = help.renderRoot?.querySelector('.tooltip:popover-open')
+          || card.renderRoot.querySelector('hp-dialog')?.renderRoot
+            ?.querySelector('[data-hp-overlay="help"]')?.shadowRoot?.querySelector('.tooltip');
+        if (trigger.getAttribute('aria-expanded') !== 'true' || !surface?.getBoundingClientRect().width)
+          throw new Error(`golden help surface did not open: ${scenario.openHelp}`);
+      }
       if (scenario.focusDialogClose) {
         const dialog = card.renderRoot.querySelector('hp-dialog');
         await dialog?.updateComplete;
         dialog?.renderRoot?.querySelector('.close')?.focus();
       }
+    } else if (scenario.dialog === 'backup-full' || scenario.dialog === 'backup-space') {
+      const full = scenario.dialog === 'backup-full';
+      card._backupImportDialog = {
+        filename: full ? 'houseplan-full-2026-08-11.json' : 'houseplan-space-ground.json',
+        size: 12345,
+        token: 'golden-token',
+        preview: {
+          kind: full ? 'full' : 'space', source: full ? 'foreign' : 'same',
+          created_at: '2026-08-11T10:00:00Z', space_title: 'Ground (2)',
+          counts: { spaces: 1, rooms: 4, markers: 12, layout: 15 },
+          duplicates: full ? 0 : 2,
+          confirmation_required: full,
+          content: full
+            ? [{ url: '/api/houseplan/content/plans/_/ground.svg', state: 'detach_required' }]
+            : [{ url: 'https://example.test/ground.svg', state: 'external' }],
+        },
+        expectedConfigRev: 1, expectedLayoutRev: 1,
+        duplicatePolicy: 'skip', confirmMissing: false, busy: false, error: '',
+      };
+      card.requestUpdate();
+      await card.updateComplete;
     } else if (scenario.dialog === 'decor-color') {
       card._setMode('decor');
       card._decorTool = 'select';
       await card.updateComplete;
+      await settleMode(card);
       const shape = card._decorList.find((item) => item.kind === 'line');
       if (!shape) throw new Error('golden decor line missing');
       card._decorShapeDbl(new MouseEvent('dblclick'), shape);
@@ -234,24 +517,46 @@ export async function prepareGoldenScenario(page, scenario) {
       mode: card._mode,
       devices: card._devices.length,
       dialog: !!card.renderRoot.querySelector('hp-dialog'),
+      helpOpen: [...card.renderRoot.querySelectorAll('hp-help')]
+        .some((help) => help.renderRoot?.querySelector('.trigger')?.getAttribute('aria-expanded') === 'true'),
       editorTray: card.renderRoot.querySelector('.editor-secondary-host.open .editor-secondary')
         ?.className || '',
+      ...(scenario.sunRayPixels ? { sun: {
+        raw: card.hass?.states?.['sun.sun']?.attributes || null,
+        plan: card._planHass?.states?.['sun.sun']?.attributes || null,
+        render: card._renderPlanHass?.states?.['sun.sun']?.attributes || null,
+        north: card._effNorth(),
+        enabled: card._effSunRays(),
+        editing: card._editing,
+        cachedRays: card._sunRaysCache?.rays?.length || 0,
+      } } : {}),
     };
   }, { fixture, scenario });
 }
 
 export async function goldenClip(page, capture) {
   if (capture === 'page') return null;
-  return page.evaluate(() => {
+  return page.evaluate((captureKind) => {
     const card = window.__goldenCard;
     const target = card?.renderRoot?.querySelector('.stage');
     if (!target) throw new Error('golden stage capture target missing');
     const rect = target.getBoundingClientRect();
+    if (captureKind === 'sun-window') {
+      // Stable crop around the exterior window and the first part of its ray:
+      // deliberately excludes room labels and device markers, whose font/icon
+      // rasterisation would add noise unrelated to the visual contract.
+      return {
+        x: Math.max(0, Math.floor(rect.left + rect.width * 0.10)),
+        y: Math.max(0, Math.floor(rect.top + rect.height * 0.02)),
+        width: Math.max(1, Math.ceil(rect.width * 0.35)),
+        height: Math.max(1, Math.ceil(rect.height * 0.25)),
+      };
+    }
     const pad = 2;
     const x = Math.max(0, Math.floor(rect.left - pad));
     const y = Math.max(0, Math.floor(rect.top - pad));
     const right = Math.min(window.innerWidth, Math.ceil(rect.right + pad));
     const bottom = Math.min(window.innerHeight, Math.ceil(rect.bottom + pad));
     return { x, y, width: Math.max(1, right - x), height: Math.max(1, bottom - y) };
-  });
+  }, capture);
 }

demo/golden/matrix.mjs

@@ -1,16 +1,49 @@
+import { fixtureWallKey } from '../fixtures/visual-matrix.mjs';
+
 /** Data-only HP-QA-01 capture matrix. Bump when framing or scenarios change. */
-export const GOLDEN_MATRIX_VERSION = 3;
+export const GOLDEN_MATRIX_VERSION = 19;
 
 const stage = { capture: 'stage', threshold: { maxChannelDelta: 10, maxDiffRatio: 0.0005 } };
 const page = { capture: 'page', threshold: { maxChannelDelta: 10, maxDiffRatio: 0.0008 } };
+const sunWindow = { capture: 'sun-window', threshold: { maxChannelDelta: 10, maxDiffRatio: 0.001 } };
 
 export const GOLDEN_SCENARIOS = Object.freeze([
+  { id: 'split-corner-wall-before-dark', fixture: 'visual', space: 'golden-corner-split',
+    cornerSplitWall: 'before', mode: 'view', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'split-corner-wall-thin-dark', fixture: 'visual', space: 'golden-corner-split',
+    cornerSplitWall: 'thin', mode: 'view', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'split-corner-wall-thick-dark', fixture: 'visual', space: 'golden-corner-split',
+    cornerSplitWall: 'thick', mode: 'view', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'isometric-geometry-view-dark', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    // Stage 2 material/floor-edge plus door, window, gate and nested-room coverage.
+    labs: ['iso'], projection: 'iso', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'isometric-geometry-view-light', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    labs: ['iso'], projection: 'iso', theme: 'light', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'isometric-live-layers-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    labs: ['iso'], projection: 'iso', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'isometric-no-borders-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    labs: ['iso'], projection: 'iso', showBorders: false, fillMode: 'custom',
+    customFill: { c: '#486a8f', a: 0.42 }, glowEnabled: true,
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'isometric-touch-kiosk-dark', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    labs: ['iso'], projection: 'iso', kiosk: true,
+    theme: 'dark', viewport: { width: 390, height: 760 }, ...stage },
+  { id: 'isometric-large-warm-remount-dark', fixture: 'large', space: 'perf-floor-2', mode: 'view',
+    labs: ['iso'], projection: 'iso', warmRemount: true,
+    theme: 'dark', viewport: { width: 1180, height: 900 }, ...stage },
   { id: 'geometry-view-dark-fit', fixture: 'visual', space: 'golden-geometry', mode: 'view',
     theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'geometry-view-light-fit', fixture: 'visual', space: 'golden-geometry', mode: 'view',
     theme: 'light', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'geometry-plan-editor-dark', fixture: 'visual', space: 'golden-geometry', mode: 'plan',
     theme: 'dark', viewport: { width: 1180, height: 900 }, ...page },
+  { id: 'opening-placement-door-thick-wall-dark', fixture: 'visual', space: 'golden-geometry',
+    // The shared centre edge is a long 25 cm physical wall. It can contain the
+    // complete 90 cm door preset while still proving rotation, inner-face
+    // offset and ruler placement on a thick wall.
+    mode: 'plan', openingPreview: { type: 'door', pointer: [0.48, 0.65] },
+    openingPreviewPixels: { minPixels: 150, minInsideWallPixels: 8, minChannelDelta: 4 },
+    theme: 'dark', viewport: { width: 1180, height: 900 }, ...page },
   { id: 'geometry-devices-editor-dark', fixture: 'visual', space: 'golden-geometry', mode: 'devices',
     theme: 'dark', viewport: { width: 1180, height: 900 }, ...page },
   { id: 'geometry-decor-editor-dark', fixture: 'visual', space: 'golden-geometry', mode: 'decor',
@@ -36,19 +69,106 @@ export const GOLDEN_SCENARIOS = Object.freeze([
     editorTray: 'decor-tool', language: 'ru', theme: 'dark',
     viewport: { width: 390, height: 760 }, ...page },
   { id: 'geometry-diagonal-45-opening-dark', fixture: 'visual', space: 'golden-geometry', mode: 'view',
+    openingGeometry: { id: 'geo-diagonal-window', type: 'window', angle: 45 },
     theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'openings-thick-wall-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
-    fillMode: 'none', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+    fillMode: 'none', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'openings-filled-tunnel-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'custom', customFill: { c: '#66717c', a: 0.55 }, glowEnabled: false,
+    hideOpenings: true,
+    wallReplacements: [{
+      match: { a: [0.5, 0.1], b: [0.5, 0.88] },
+      segments: [
+        { key: fixtureWallKey([0.5, 0.1], [0.5, 0.5]), a: [0.5, 0.1], b: [0.5, 0.5], cm: 18 },
+        { key: fixtureWallKey([0.5, 0.5], [0.5, 0.88]), a: [0.5, 0.5], b: [0.5, 0.88], cm: 32 },
+      ],
+    }],
+    tunnelContinuity: { openingId: 'light-door', insetPx: 2, maxChannelJump: 3, dpr2: true },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'openings-hidden-view-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
-    fillMode: 'none', hideOpenings: true, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+    fillMode: 'none', glowEnabled: false, hideOpenings: true, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'lighting-glow-sun-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
     theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'device-value-badge-positions-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    glowEnabled: false, sunRays: false,
+    markerOverrides: [
+      { id: 'golden-light-one', binding: 'device:golden-light-one', value_badge: {
+        enabled: true, source: { kind: 'entity_state', entity_id: 'light.golden_light_one' }, position: 'right',
+      } },
+      { id: 'golden-light-two', binding: 'device:golden-light-two', value_badge: {
+        enabled: true, source: { kind: 'entity_state', entity_id: 'light.golden_light_two' }, position: 'left',
+      } },
+      { id: 'golden-presence', binding: 'device:golden-presence', value_badge: {
+        enabled: true, source: { kind: 'entity_state', entity_id: 'binary_sensor.golden_presence' }, position: 'top',
+      } },
+      { id: 'golden-climate', binding: 'device:golden-climate', value_badge: {
+        enabled: true,
+        source: { kind: 'entity_attribute', entity_id: 'climate.golden_climate', attribute: 'current_temperature' },
+        position: 'bottom',
+      } },
+    ],
+    stateOverrides: { 'climate.golden_climate': { attributes: { lqi: 190 } } },
+    layoutOverrides: {
+      'golden-light-one': { s: 'golden-lighting', x: 0.20, y: 0.32 },
+      'golden-light-two': { s: 'golden-lighting', x: 0.20, y: 0.72 },
+      'golden-presence': { s: 'golden-lighting', x: 0.80, y: 0.68 },
+      'golden-climate': { s: 'golden-lighting', x: 0.80, y: 0.28 },
+    },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-sun-window-state-only-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    // The golden screenshot is backed by a second, sun-layer-hidden capture.
+    // A real painted ray must account for enough changed pixels; DOM-only
+    // presence or an accidentally accepted empty baseline is not sufficient.
+    glowEnabled: false, allLightsOff: true,
+    stateOverrides: { 'sun.sun': { attributes: { azimuth: 0, elevation: 24 } } },
+    sunRayPixels: { minPixels: 500, minChannelDelta: 4 },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...sunWindow },
   { id: 'lighting-fill-light-axis-split-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
-    fillMode: 'light', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+    fillMode: 'light', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'lighting-fill-temp-axis-split-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
-    fillMode: 'temp', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+    fillMode: 'temp', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'lighting-fill-lqi-axis-split-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
-    fillMode: 'lqi', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+    fillMode: 'lqi', glowEnabled: false, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-light', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, theme: 'light', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-custom-glow-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'custom', customFill: { c: '#486a8f', a: 0.42 }, glowEnabled: true,
+    roomCustomFill: { 'light-right': { c: '#8f5f48', a: 0.56 } },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-opaque-glow-two-doorways-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'custom', customFill: { c: '#3f4854', a: 1 }, glowEnabled: true, sunRays: false,
+    allLightsOff: true,
+    stateOverrides: {
+      'light.golden_light_one': { state: 'on', attributes: { rgb_color: [255, 196, 112], brightness: 255 } },
+    },
+    extraOpenings: [
+      { id: 'light-door-second', type: 'door', x: 0.50, y: 0.32, angle: 90, length: 0.13 },
+    ],
+    layoutOverrides: { 'golden-light-one': { s: 'golden-lighting', x: 0.40, y: 0.48 } },
+    // The golden is protection only if the receiving half actually contains
+    // rendered light. A data-only check once let a visually empty baseline pass.
+    warmPixelRegion: { x: 0.5, y: 0, w: 0.5, h: 1, minPixels: 2500, minRedBlueDelta: 25 },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-custom-glow-light', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'custom', customFill: { c: '#486a8f', a: 0.42 }, glowEnabled: true,
+    roomCustomFill: { 'light-right': { c: '#8f5f48', a: 0.56 } },
+    theme: 'light', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-no-sources-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, allLightsOff: true,
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-temp-glow-room-override-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true, roomGlow: { 'light-left': true, 'light-right': false },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
+  { id: 'lighting-manual-auto-spill-overlap-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
+    fillMode: 'temp', glowEnabled: true,
+    markerOverrides: [{
+      id: 'golden-light-two', binding: 'device:golden-light-two',
+      glow_color: { c: '#3a8fff', bri: 0.35 }, glow_radius_cm: 420,
+    }],
+    layoutOverrides: { 'golden-light-two': { s: 'golden-lighting', x: 0.39, y: 0.57 } },
+    theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'hover-over-glow-dark', fixture: 'visual', space: 'golden-lighting', mode: 'view',
     hoverRoom: 'light-right', theme: 'dark', viewport: { width: 1000, height: 900 }, ...stage },
   { id: 'hover-nested-room-dark', fixture: 'visual', space: 'golden-geometry', mode: 'view',
@@ -60,14 +180,25 @@ export const GOLDEN_SCENARIOS = Object.freeze([
   { id: 'large-house-warm-remount-dark', fixture: 'large', space: 'perf-floor-2', mode: 'view',
     warmRemount: true, theme: 'dark', viewport: { width: 1180, height: 900 }, ...stage },
   { id: 'device-dialog-desktop-en', fixture: 'visual', space: 'golden-lighting',
-    dialog: 'device', deviceId: 'golden-climate',
-    deviceName: 'Living room climate controller with an intentionally long title',
-    focusDialogClose: true, language: 'en', theme: 'dark', viewport: { width: 1180, height: 900 }, ...page },
+    dialog: 'device', deviceId: 'golden-light-two', deviceLightControls: true,
+    deviceName: 'Living room light controller with an intentionally long title',
+    openHelp: 'marker.glow_mode.help', helpTextRegion: { key: 'marker.glow_mode.help', minPixels: 30 },
+    focusDialogClose: true, language: 'en', theme: 'dark', viewport: { width: 1180, height: 1200 }, ...page },
   { id: 'device-dialog-mobile-ru', fixture: 'visual', space: 'golden-lighting',
-    dialog: 'device', deviceId: 'golden-climate',
-    deviceName: 'Контроллер климата гостиной с намеренно очень длинным названием',
-    language: 'ru', theme: 'dark', viewport: { width: 390, height: 760 }, ...page },
+    dialog: 'device', deviceId: 'golden-light-two', deviceLightControls: true,
+    deviceName: 'Контроллер освещения гостиной с намеренно очень длинным названием',
+    language: 'ru', theme: 'dark', viewport: { width: 390, height: 1000 }, ...page },
+  { id: 'device-help-popover-light-ru', fixture: 'visual', space: 'golden-lighting',
+    dialog: 'device', deviceId: 'golden-light-two', deviceLightControls: true,
+    openHelp: 'marker.glow_mode.help', helpTextRegion: { key: 'marker.glow_mode.help', minPixels: 30 },
+    language: 'ru', theme: 'light', viewport: { width: 760, height: 900 }, ...page },
   { id: 'decor-color-popover-mobile-ru', fixture: 'visual', space: 'golden-geometry',
     dialog: 'decor-color', language: 'ru', theme: 'dark',
     viewport: { width: 390, height: 760 }, ...page },
+  { id: 'backup-full-preview-desktop-en', fixture: 'visual', space: 'golden-geometry',
+    dialog: 'backup-full', language: 'en', theme: 'dark',
+    viewport: { width: 1000, height: 900 }, ...page },
+  { id: 'backup-space-preview-mobile-ru', fixture: 'visual', space: 'golden-geometry',
+    dialog: 'backup-space', language: 'ru', theme: 'light',
+    viewport: { width: 390, height: 820 }, ...page },
 ]);

demo/golden/policy.mjs

@@ -1,4 +1,7 @@
-export const GOLDEN_BASELINE_MANIFEST = 'baseline-manifest.json';
+// The name must NOT end with `manifest.json`: the HACS submission check globs
+// `*manifest.json` over the whole clone of the default branch and refuses a
+// repository with more than one match (test/repo-hygiene.test.mjs).
+export const GOLDEN_BASELINE_MANIFEST = 'baselines-index.json';
 
 export const assertGoldenInvocation = (mode, scenarioFilter = '') => {
   if (!['capture', 'verify'].includes(mode)) throw new Error(`unknown golden mode: ${mode}`);
@@ -6,6 +9,15 @@ export const assertGoldenInvocation = (mode, scenarioFilter = '') => {
     throw new Error('golden verify must run the complete matrix; use capture for a diagnostic --scenario run');
 };
 
+/** A reviewed golden matrix is exact: neither an orphan PNG nor a stale hash
+ * entry may survive after a scenario is removed or renamed. */
+export const goldenScenarioSetsMatch = (expected, indexed, baselineFiles) => {
+  const normalized = (values) => [...new Set(values)].sort();
+  const wanted = normalized(expected);
+  return JSON.stringify(normalized(indexed)) === JSON.stringify(wanted)
+    && JSON.stringify(normalized(baselineFiles)) === JSON.stringify(wanted);
+};
+
 export const goldenRunFailed = (mode, manifestValid, results) => {
   if (results.some((result) => result.status === 'error')) return true;
   return mode === 'verify'

demo/golden/run.mjs

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { launch } from '../serve.mjs';
 import { assertFreshDemoBundle } from '../bundle-freshness.mjs';
 import { goldenClip, prepareGoldenScenario } from './harness.mjs';
 import { GOLDEN_MATRIX_VERSION, GOLDEN_SCENARIOS } from './matrix.mjs';
-import { assertGoldenInvocation, GOLDEN_BASELINE_MANIFEST, goldenRunFailed } from './policy.mjs';
+import {
+  assertGoldenInvocation,
+  GOLDEN_BASELINE_MANIFEST,
+  goldenRunFailed,
+  goldenScenarioSetsMatch,
+} from './policy.mjs';
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 const mode = process.argv.find((arg) => arg.startsWith('--mode='))?.slice(7) || 'capture';
@@ -105,6 +110,324 @@ async function comparePng(page, actual, baseline, threshold) {
   });
 }
 
+/** Capture the identical visual frame with only the rendered sun-ray SVG
+ * hidden. Comparing this control frame with the reviewed golden proves that
+ * the layer changes real browser pixels, not merely that its DOM exists. */
+async function captureWithoutSunRays(page, screenshotOptions) {
+  const layerState = await page.evaluate(async () => {
+    const layer = window.__goldenCard?.renderRoot?.querySelector('.sunlayer');
+    if (!layer) throw new Error('semantic golden sun layer is missing');
+    const shapes = layer.querySelectorAll('path, polygon').length;
+    if (!shapes) throw new Error('semantic golden sun layer has no painted shapes');
+    const previous = layer.style.visibility;
+    layer.style.visibility = 'hidden';
+    await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    return { previous, shapes };
+  });
+  try {
+    return { png: await page.screenshot(screenshotOptions), shapes: layerState.shapes };
+  } finally {
+    await page.evaluate(async (previous) => {
+      const layer = window.__goldenCard?.renderRoot?.querySelector('.sunlayer');
+      if (layer) layer.style.visibility = previous;
+      await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    }, layerState.previous);
+  }
+}
+
+/** Capture a control frame with only the transient opening symbol hidden.
+ * Comparing it with the actual frame proves the preview paints browser pixels;
+ * the smoke test separately locks its DOM order above the wall body. */
+async function captureWithoutOpeningPreview(page, screenshotOptions) {
+  const layerState = await page.evaluate(async () => {
+    const card = window.__goldenCard;
+    const parts = [...(card?.renderRoot?.querySelectorAll(
+      '.opening-preview, .opening-preview-dot',
+    ) || [])];
+    if (!parts.length) throw new Error('semantic golden opening preview is missing');
+    const previous = parts.map((part) => part.style.visibility);
+    for (const part of parts) part.style.visibility = 'hidden';
+    await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    return { previous, count: parts.length };
+  });
+  try {
+    return { png: await page.screenshot(screenshotOptions), parts: layerState.count };
+  } finally {
+    await page.evaluate(async (previous) => {
+      const card = window.__goldenCard;
+      const parts = [...(card?.renderRoot?.querySelectorAll(
+        '.opening-preview, .opening-preview-dot',
+      ) || [])];
+      parts.forEach((part, index) => { part.style.visibility = previous[index] || ''; });
+      await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    }, layerState.previous);
+  }
+}
+
+async function countChangedPixels(page, actual, control, spec) {
+  return page.evaluate(async ({ actual64, control64, minChannelDelta }) => {
+    const decode = async (base64) => {
+      const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+      return createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    };
+    const [actualImage, controlImage] = await Promise.all([decode(actual64), decode(control64)]);
+    if (actualImage.width !== controlImage.width || actualImage.height !== controlImage.height)
+      throw new Error('semantic golden control frame has different dimensions');
+    const canvas = document.createElement('canvas');
+    const controlCanvas = document.createElement('canvas');
+    canvas.width = controlCanvas.width = actualImage.width;
+    canvas.height = controlCanvas.height = actualImage.height;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    const controlContext = controlCanvas.getContext('2d', { willReadFrequently: true });
+    context.drawImage(actualImage, 0, 0);
+    controlContext.drawImage(controlImage, 0, 0);
+    const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data;
+    const controlPixels = controlContext.getImageData(0, 0, canvas.width, canvas.height).data;
+    let changed = 0;
+    let maxDelta = 0;
+    for (let offset = 0; offset < pixels.length; offset += 4) {
+      const delta = Math.max(
+        Math.abs(pixels[offset] - controlPixels[offset]),
+        Math.abs(pixels[offset + 1] - controlPixels[offset + 1]),
+        Math.abs(pixels[offset + 2] - controlPixels[offset + 2]),
+      );
+      maxDelta = Math.max(maxDelta, delta);
+      if (delta >= minChannelDelta) changed++;
+    }
+    return { changed, maxDelta, size: [canvas.width, canvas.height] };
+  }, {
+    actual64: actual.toString('base64'),
+    control64: control.toString('base64'),
+    minChannelDelta: spec.minChannelDelta,
+  });
+}
+
+/** Count preview pixels which are actually painted over the physical wall
+ * fill. A global changed-pixel threshold can pass even when the complete
+ * symbol is accidentally hidden below masonry because its swing arc remains
+ * outside the body. */
+async function countOpeningPreviewPixelsInsideWall(
+  page, actual, control, clip, minChannelDelta,
+) {
+  return page.evaluate(async ({ actual64, control64, clipRect, minDelta }) => {
+    const decode = async (base64) => {
+      const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+      return createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    };
+    const [actualImage, controlImage] = await Promise.all([decode(actual64), decode(control64)]);
+    const canvas = document.createElement('canvas');
+    const controlCanvas = document.createElement('canvas');
+    canvas.width = controlCanvas.width = actualImage.width;
+    canvas.height = controlCanvas.height = actualImage.height;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    const controlContext = controlCanvas.getContext('2d', { willReadFrequently: true });
+    context.drawImage(actualImage, 0, 0);
+    controlContext.drawImage(controlImage, 0, 0);
+    const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data;
+    const controls = controlContext.getImageData(0, 0, canvas.width, canvas.height).data;
+    const card = window.__goldenCard;
+    const preview = card?.renderRoot?.querySelector('.opening-preview');
+    const walls = [...(card?.renderRoot?.querySelectorAll('.wallbody-fill') || [])]
+      .map((wall) => {
+        const matrix = wall.getScreenCTM?.();
+        return matrix ? { wall, rect: wall.getBoundingClientRect(), inverse: matrix.inverse() } : null;
+      })
+      .filter(Boolean);
+    if (!preview || !walls.length) return { changed: 0, sampled: 0 };
+    const previewRect = preview.getBoundingClientRect();
+    const candidates = walls.filter(({ rect }) => rect.right >= previewRect.left
+      && rect.left <= previewRect.right && rect.bottom >= previewRect.top
+      && rect.top <= previewRect.bottom);
+    if (!candidates.length) return { changed: 0, sampled: 0 };
+    const left = Math.ceil(previewRect.left);
+    const top = Math.ceil(previewRect.top);
+    const right = Math.floor(previewRect.right);
+    const bottom = Math.floor(previewRect.bottom);
+    const originX = clipRect?.x || 0;
+    const originY = clipRect?.y || 0;
+    let changed = 0;
+    let sampled = 0;
+    for (let y = top; y <= bottom; y++) {
+      for (let x = left; x <= right; x++) {
+        const screenPoint = new DOMPoint(x + 0.5, y + 0.5);
+        const insideWall = candidates.some(({ wall, rect, inverse }) => {
+          if (x < rect.left || x > rect.right || y < rect.top || y > rect.bottom) return false;
+          return wall.isPointInFill(screenPoint.matrixTransform(inverse));
+        });
+        if (!insideWall) continue;
+        const px = Math.round(x - originX);
+        const py = Math.round(y - originY);
+        if (px < 0 || py < 0 || px >= canvas.width || py >= canvas.height) continue;
+        sampled += 1;
+        const offset = (py * canvas.width + px) * 4;
+        const delta = Math.max(
+          Math.abs(pixels[offset] - controls[offset]),
+          Math.abs(pixels[offset + 1] - controls[offset + 1]),
+          Math.abs(pixels[offset + 2] - controls[offset + 2]),
+          Math.abs(pixels[offset + 3] - controls[offset + 3]),
+        );
+        if (delta >= minDelta) changed += 1;
+      }
+    }
+    return { changed, sampled };
+  }, {
+    actual64: actual.toString('base64'),
+    control64: control.toString('base64'),
+    clipRect: clip || null,
+    minDelta: minChannelDelta,
+  });
+}
+
+/** Assert scenario semantics against the actual capture, not only its data.
+ *  This protects a reviewed-but-empty baseline from becoming the reference. */
+async function countWarmPixels(page, png, region) {
+  return page.evaluate(async ({ png64, region }) => {
+    const bytes = Uint8Array.from(atob(png64), (char) => char.charCodeAt(0));
+    const image = await createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    const canvas = document.createElement('canvas');
+    canvas.width = image.width;
+    canvas.height = image.height;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    context.drawImage(image, 0, 0);
+    const left = Math.max(0, Math.min(image.width, Math.floor(region.x * image.width)));
+    const top = Math.max(0, Math.min(image.height, Math.floor(region.y * image.height)));
+    const right = Math.max(left, Math.min(image.width, Math.ceil((region.x + region.w) * image.width)));
+    const bottom = Math.max(top, Math.min(image.height, Math.ceil((region.y + region.h) * image.height)));
+    const pixels = context.getImageData(left, top, right - left, bottom - top).data;
+    let warm = 0;
+    for (let offset = 0; offset < pixels.length; offset += 4) {
+      if (pixels[offset] - pixels[offset + 2] > region.minRedBlueDelta) warm++;
+    }
+    return { warm, bounds: [left, top, right, bottom] };
+  }, { png64: png.toString('base64'), region });
+}
+
+/** Semantic guard for issue #68: the reviewed bubble must contain rendered
+ * glyph pixels, not just an empty surface or a stale open-state flag. */
+async function countHelpTextPixels(page, png, clip, spec) {
+  return page.evaluate(async ({ png64, clip, spec }) => {
+    const card = window.__goldenCard;
+    const help = card?.renderRoot?.querySelector(`hp-help[data-help-key="${spec.key}"]`);
+    const surface = help?.renderRoot?.querySelector('.tooltip:popover-open')
+      || card?.renderRoot?.querySelector('hp-dialog')?.renderRoot
+        ?.querySelector('[data-hp-overlay="help"]')?.shadowRoot?.querySelector('.tooltip');
+    if (!surface) throw new Error(`semantic golden help missing: ${spec.key}`);
+    const bounds = surface.getBoundingClientRect();
+    const match = getComputedStyle(surface).color.match(/[\d.]+/g)?.slice(0, 3).map(Number);
+    if (!match || match.length !== 3) throw new Error(`semantic golden help has invalid text color: ${spec.key}`);
+    const bytes = Uint8Array.from(atob(png64), (char) => char.charCodeAt(0));
+    const image = await createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    const canvas = document.createElement('canvas');
+    canvas.width = image.width;
+    canvas.height = image.height;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    context.drawImage(image, 0, 0);
+    const pixels = context.getImageData(0, 0, image.width, image.height).data;
+    const originX = clip?.x || 0, originY = clip?.y || 0;
+    const left = Math.max(0, Math.ceil(bounds.left - originX) + 5);
+    const top = Math.max(0, Math.ceil(bounds.top - originY) + 5);
+    const right = Math.min(image.width - 1, Math.floor(bounds.right - originX) - 5);
+    const bottom = Math.min(image.height - 1, Math.floor(bounds.bottom - originY) - 5);
+    let textPixels = 0;
+    for (let y = top; y <= bottom; y++) {
+      for (let x = left; x <= right; x++) {
+        const offset = (y * image.width + x) * 4;
+        const distance = Math.abs(pixels[offset] - match[0])
+          + Math.abs(pixels[offset + 1] - match[1])
+          + Math.abs(pixels[offset + 2] - match[2]);
+        if (pixels[offset + 3] > 240 && distance <= 90) textPixels++;
+      }
+    }
+    return { textPixels, bounds: [left, top, right, bottom] };
+  }, { png64: png.toString('base64'), clip, spec });
+}
+
+/** Detect one-pixel SVG seams inside a room-coloured opening tunnel. Sample a
+ * narrow strip around local y=0: this crosses the join between both tunnel
+ * half-faces at any opening angle while excluding legitimate outer-profile
+ * steps where adjacent wall intervals have different physical thicknesses. */
+async function inspectTunnelContinuity(page, png, clip, spec) {
+  return page.evaluate(async ({ png64, clip, spec }) => {
+    const card = window.__goldenCard;
+    const tunnel = card?.renderRoot?.querySelector(
+      `.opening-tunnels[data-layer="data"] [data-hp="opening-tunnel"][data-id="${spec.openingId}"]`,
+    );
+    if (!tunnel) throw new Error(`semantic golden tunnel missing: ${spec.openingId}`);
+    const rect = tunnel.getBoundingClientRect();
+    const matrix = tunnel.getScreenCTM();
+    if (!matrix) throw new Error(`semantic golden tunnel has no screen transform: ${spec.openingId}`);
+    const inverse = matrix.inverse();
+    const localBounds = tunnel.getBBox();
+    const bytes = Uint8Array.from(atob(png64), (char) => char.charCodeAt(0));
+    const image = await createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    const canvas = document.createElement('canvas');
+    canvas.width = image.width;
+    canvas.height = image.height;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    context.drawImage(image, 0, 0);
+    const originX = clip?.x || 0, originY = clip?.y || 0;
+    // Screenshots may be captured at DPR > 1. DOMRect/clip are CSS pixels,
+    // image coordinates are device pixels, so derive the scale instead of
+    // silently sampling the wrong strip at high DPI.
+    const cssWidth = clip?.width || document.documentElement.clientWidth;
+    const cssHeight = clip?.height || document.documentElement.clientHeight;
+    const scaleX = image.width / Math.max(1, cssWidth);
+    const scaleY = image.height / Math.max(1, cssHeight);
+    const insetX = Math.max(1, Math.round(spec.insetPx * scaleX));
+    const insetY = Math.max(1, Math.round(spec.insetPx * scaleY));
+    const left = Math.max(0, Math.ceil((rect.left - originX) * scaleX) + insetX);
+    const top = Math.max(0, Math.ceil((rect.top - originY) * scaleY) + insetY);
+    const right = Math.min(image.width - 1, Math.floor((rect.right - originX) * scaleX) - insetX);
+    const bottom = Math.min(image.height - 1, Math.floor((rect.bottom - originY) * scaleY) - insetY);
+    if (right - left < 3 || bottom - top < 3)
+      throw new Error(`semantic golden tunnel is too small: ${left},${top},${right},${bottom}`);
+    const pixels = context.getImageData(0, 0, image.width, image.height).data;
+    const rgb = (x, y) => {
+      const offset = (y * image.width + x) * 4;
+      return [pixels[offset], pixels[offset + 1], pixels[offset + 2]];
+    };
+    let maxJump = 0, maxPair = null, samplePairs = 0;
+    const compare = (a, b, x, y, direction) => {
+      const jump = Math.max(
+        Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]), Math.abs(a[2] - b[2]));
+      if (jump > maxJump) {
+        maxJump = jump;
+        maxPair = { x, y, direction, a, b };
+      }
+      samplePairs++;
+    };
+    const localXScale = Math.max(1e-6, Math.hypot(matrix.a, matrix.b));
+    const localYScale = Math.max(1e-6, Math.hypot(matrix.c, matrix.d));
+    const endInset = Math.max(1, spec.insetPx) / localXScale;
+    const axisBand = Math.max(1.5, spec.axisBandPx || 2.5) / localYScale;
+    const insideAxisBand = (x, y) => {
+      const cssX = originX + (x + 0.5) / scaleX;
+      const cssY = originY + (y + 0.5) / scaleY;
+      const local = new DOMPoint(cssX, cssY).matrixTransform(inverse);
+      return local.x >= localBounds.x + endInset
+        && local.x <= localBounds.x + localBounds.width - endInset
+        && Math.abs(local.y) <= axisBand;
+    };
+    for (let y = top; y <= bottom; y++) {
+      for (let x = left + 1; x <= right; x++) {
+        if (insideAxisBand(x - 1, y) && insideAxisBand(x, y))
+          compare(rgb(x - 1, y), rgb(x, y), x, y, 'horizontal');
+      }
+    }
+    for (let x = left; x <= right; x++) {
+      for (let y = top + 1; y <= bottom; y++) {
+        if (insideAxisBand(x, y - 1) && insideAxisBand(x, y))
+          compare(rgb(x, y - 1), rgb(x, y), x, y, 'vertical');
+      }
+    }
+    if (!samplePairs) throw new Error(`semantic golden tunnel axis strip is empty: ${spec.openingId}`);
+    return {
+      maxJump, maxPair, samplePairs, bounds: [left, top, right, bottom],
+      scale: [scaleX, scaleY],
+    };
+  }, { png64: png.toString('base64'), clip, spec });
+}
+
 let baselineManifest = null;
 const baselineManifestPath = resolve(baselineRoot, GOLDEN_BASELINE_MANIFEST);
 if (existsSync(baselineManifestPath)) {
@@ -112,11 +435,13 @@ if (existsSync(baselineManifestPath)) {
   catch { baselineManifest = { invalid: true }; }
 }
 
+const browserArgs = ['--force-color-profile=srgb', '--font-render-hinting=none', '--disable-lcd-text'];
+const browserContext = { locale: 'en-US', timezoneId: 'UTC', colorScheme: 'dark', reducedMotion: 'reduce' };
 const { page, browser } = await launch(
   { width: 1000, height: 900 },
   1,
-  ['--force-color-profile=srgb', '--font-render-hinting=none', '--disable-lcd-text'],
-  { locale: 'en-US', timezoneId: 'UTC', colorScheme: 'dark', reducedMotion: 'reduce' },
+  browserArgs,
+  browserContext,
 );
 const chromium = await browser.version();
 const results = [];
@@ -136,17 +461,170 @@ try {
       pageErrors.length = 0;
       result.runtime = await prepareGoldenScenario(page, scenario);
       if (pageErrors.length) throw new Error(`browser exception: ${pageErrors.join(' | ')}`);
+      if (scenario.openingGeometry) {
+        result.openingGeometry = await page.evaluate((expected) => {
+          const card = window.__goldenCard;
+          const opening = card?.renderRoot?.querySelector(
+            `.opening[data-id="${CSS.escape(expected.id)}"]`,
+          );
+          if (!opening) return null;
+          const transform = opening.getAttribute('transform') || '';
+          const angle = Number(transform.match(/rotate\(([-+0-9.eE]+)\)/)?.[1]);
+          const painted = [...opening.querySelectorAll('.op-leaf, .op-arc, .op-glass')]
+            .map((part) => part.getBoundingClientRect())
+            .filter((rect) => rect.width > 0 || rect.height > 0);
+          const bounds = painted.length ? {
+            width: Math.max(...painted.map((rect) => rect.right))
+              - Math.min(...painted.map((rect) => rect.left)),
+            height: Math.max(...painted.map((rect) => rect.bottom))
+              - Math.min(...painted.map((rect) => rect.top)),
+          } : { width: 0, height: 0 };
+          return {
+            type: opening.getAttribute('data-kind'), angle,
+            width: bounds.width, height: bounds.height,
+            visibleParts: opening.querySelectorAll('.op-leaf, .op-arc, .op-glass').length,
+          };
+        }, scenario.openingGeometry);
+        const expected = scenario.openingGeometry;
+        const actualOpening = result.openingGeometry;
+        if (!actualOpening || actualOpening.type !== expected.type
+            || Math.abs(actualOpening.angle - expected.angle) > 0.001
+            || actualOpening.width <= 0 || actualOpening.height <= 0
+            || actualOpening.visibleParts <= 0) {
+          throw new Error(
+            `semantic golden opening geometry failed for ${expected.id}: `
+            + JSON.stringify(actualOpening),
+          );
+        }
+      }
       const clip = await goldenClip(page, scenario.capture);
-      const actual = await page.screenshot({
+      const screenshotOptions = {
         ...(clip ? { clip } : {}),
         animations: 'disabled',
         caret: 'hide',
         scale: 'css',
-      });
+      };
+      const actual = await page.screenshot(screenshotOptions);
       const actualPath = resolve(actualRoot, `${scenario.id}.png`);
       writeFileSync(actualPath, actual);
       result.actualSha256 = sha256(actual);
       result.actual = actualPath;
+      if (scenario.sunRayPixels) {
+        const control = await captureWithoutSunRays(page, screenshotOptions);
+        const sample = await countChangedPixels(page, actual, control.png, scenario.sunRayPixels);
+        result.sunRayShapes = control.shapes;
+        result.sunRayChangedPixels = sample.changed;
+        result.sunRayMaxChannelDelta = sample.maxDelta;
+        if (sample.changed < scenario.sunRayPixels.minPixels) {
+          throw new Error(
+            `semantic golden assertion failed: sun rays paint ${sample.changed} pixels, expected at least `
+            + `${scenario.sunRayPixels.minPixels}`,
+          );
+        }
+      }
+      if (scenario.openingPreviewPixels) {
+        const control = await captureWithoutOpeningPreview(page, screenshotOptions);
+        const sample = await countChangedPixels(
+          page, actual, control.png, scenario.openingPreviewPixels,
+        );
+        result.openingPreviewParts = control.parts;
+        result.openingPreviewChangedPixels = sample.changed;
+        result.openingPreviewMaxChannelDelta = sample.maxDelta;
+        const insideWall = await countOpeningPreviewPixelsInsideWall(
+          page, actual, control.png, clip, scenario.openingPreviewPixels.minChannelDelta,
+        );
+        result.openingPreviewPixelsInsideWall = insideWall.changed;
+        result.openingPreviewWallSamples = insideWall.sampled;
+        if (control.parts < 2) {
+          throw new Error(
+            `semantic golden assertion failed: opening preview is incomplete (${control.parts} parts)`,
+          );
+        }
+        if (sample.changed < scenario.openingPreviewPixels.minPixels) {
+          throw new Error(
+            `semantic golden assertion failed: opening preview paints ${sample.changed} pixels, `
+            + `expected at least ${scenario.openingPreviewPixels.minPixels}`,
+          );
+        }
+        if (insideWall.changed < scenario.openingPreviewPixels.minInsideWallPixels) {
+          throw new Error(
+            `semantic golden assertion failed: opening preview paints ${insideWall.changed} pixels `
+            + `inside the wall body, expected at least `
+            + `${scenario.openingPreviewPixels.minInsideWallPixels}`,
+          );
+        }
+      }
+      if (scenario.warmPixelRegion) {
+        const sample = await countWarmPixels(page, actual, scenario.warmPixelRegion);
+        result.warmPixels = sample.warm;
+        result.warmPixelBounds = sample.bounds;
+        if (sample.warm < scenario.warmPixelRegion.minPixels) {
+          throw new Error(
+            `semantic golden assertion failed: ${sample.warm} warm pixels, expected at least `
+            + `${scenario.warmPixelRegion.minPixels}`,
+          );
+        }
+      }
+      if (scenario.helpTextRegion) {
+        const sample = await countHelpTextPixels(page, actual, clip, scenario.helpTextRegion);
+        result.helpTextPixels = sample.textPixels;
+        result.helpPixelBounds = sample.bounds;
+        if (sample.textPixels < scenario.helpTextRegion.minPixels) {
+          throw new Error(
+            `semantic golden assertion failed: help ${scenario.helpTextRegion.key} contains `
+            + `${sample.textPixels} text pixels, expected at least ${scenario.helpTextRegion.minPixels}`,
+          );
+        }
+      }
+      if (scenario.tunnelContinuity) {
+        const sample = await inspectTunnelContinuity(
+          page, actual, clip, scenario.tunnelContinuity,
+        );
+        result.tunnelMaxChannelJump = sample.maxJump;
+        result.tunnelMaxJumpPair = sample.maxPair;
+        result.tunnelSamplePairs = sample.samplePairs;
+        result.tunnelPixelBounds = sample.bounds;
+        result.tunnelImageScale = sample.scale;
+        if (sample.maxJump > scenario.tunnelContinuity.maxChannelJump) {
+          throw new Error(
+            `semantic golden assertion failed: opening ${scenario.tunnelContinuity.openingId} `
+            + `has a ${sample.maxJump}-channel local jump, expected at most `
+            + `${scenario.tunnelContinuity.maxChannelJump}`,
+          );
+        }
+        if (scenario.tunnelContinuity.dpr2) {
+          // A CSS-pixel capture cannot prove that half-device-pixel joins are
+          // clean. Run the same semantic assertion once at DPR 2 without
+          // adding a second reviewed baseline to the matrix.
+          const highDpi = await launch(
+            scenario.viewport, 2, browserArgs, browserContext,
+          );
+          try {
+            await assertFreshDemoBundle(highDpi.page, ROOT);
+            await prepareGoldenScenario(highDpi.page, scenario);
+            const highDpiClip = await goldenClip(highDpi.page, scenario.capture);
+            const highDpiPng = await highDpi.page.screenshot({
+              ...(highDpiClip ? { clip: highDpiClip } : {}),
+              animations: 'disabled', caret: 'hide', scale: 'device',
+            });
+            const highDpiSample = await inspectTunnelContinuity(
+              highDpi.page, highDpiPng, highDpiClip, scenario.tunnelContinuity,
+            );
+            result.tunnelDpr2MaxChannelJump = highDpiSample.maxJump;
+            result.tunnelDpr2SamplePairs = highDpiSample.samplePairs;
+            result.tunnelDpr2PixelBounds = highDpiSample.bounds;
+            if (highDpiSample.maxJump > scenario.tunnelContinuity.maxChannelJump) {
+              throw new Error(
+                `semantic golden assertion failed at DPR 2: opening ${scenario.tunnelContinuity.openingId} `
+                + `has a ${highDpiSample.maxJump}-channel local jump, expected at most `
+                + `${scenario.tunnelContinuity.maxChannelJump}`,
+              );
+            }
+          } finally {
+            await highDpi.browser.close();
+          }
+        }
+      }
       const baselinePath = resolve(baselineRoot, `${scenario.id}.png`);
       result.baseline = baselinePath;
       if (!existsSync(baselinePath)) {
@@ -184,11 +662,17 @@ try {
   await browser.close();
 }
 
+const expectedScenarioIds = GOLDEN_SCENARIOS.map((scenario) => scenario.id);
+const indexedScenarioIds = Object.keys(baselineManifest?.scenarios || {});
+const baselineScenarioIds = readdirSync(baselineRoot)
+  .filter((name) => name.endsWith('.png'))
+  .map((name) => name.slice(0, -'.png'.length));
 const manifestValid = !!baselineManifest
   && !baselineManifest.invalid
   && baselineManifest.matrixVersion === GOLDEN_MATRIX_VERSION
   && baselineManifest.chromium === chromium
-  && GOLDEN_SCENARIOS.every((scenario) => typeof baselineManifest.scenarios?.[scenario.id] === 'string');
+  && expectedScenarioIds.every((id) => typeof baselineManifest.scenarios?.[id] === 'string')
+  && goldenScenarioSetsMatch(expectedScenarioIds, indexedScenarioIds, baselineScenarioIds);
 const report = {
   schema: 1,
   mode,

demo/performance/README.md

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

demo/performance/budgets-glow-smoke.json

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

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

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

demo/performance/budgets-large-house-isometric.json

@@ -0,0 +1,50 @@
+{
+  "schema": 1,
+  "profile": "large-house-isometric-v1",
+  "minimumSamples": 7,
+  "timings": {
+    "modelReadyMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 200, "hardMaxMs": 3000 },
+    "firstStableRenderMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 250, "hardMaxMs": 3500 },
+    "viewToggleMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 100, "hardMaxMs": 1500 },
+    "spaceSwitchMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 100, "hardMaxMs": 1800 },
+    "stateUpdateMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 75, "hardMaxMs": 1000 },
+    "resizePreviewMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 150, "hardMaxMs": 2200 },
+    "panZoomMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 60, "hardMaxMs": 600 },
+    "settingsDialogMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 100, "hardMaxMs": 1200 },
+    "switchCycleMs": { "stat": "median", "maxRegressionRatio": 0.2, "noiseAllowanceMs": 250, "hardMaxMs": 8000 }
+  },
+  "longTasks": {
+    "maxSingleMs": 3000,
+    "maxSingleRegressionRatio": 0.2,
+    "maxSingleNoiseAllowanceMs": 250,
+    "maxCountP95": 30,
+    "maxCountRegressionRatio": 0.2,
+    "countNoiseAllowance": 3,
+    "maxTotalP95Ms": 12000,
+    "maxTotalRegressionRatio": 0.2,
+    "noiseAllowanceMs": 150
+  },
+  "heap": {
+    "required": true,
+    "hardMaxGrowthBytes": 67108864,
+    "maxRegressionRatio": 0.2,
+    "noiseAllowanceBytes": 16777216
+  },
+  "cacheEntries": {
+    "cleanFloor": 160,
+    "glowClip": 200,
+    "wallUnion": 1,
+    "openingTunnel": 1,
+    "openingWallIndex": 1,
+    "isoGeometry": 8
+  },
+  "cacheGrowth": {
+    "cleanFloor": 0,
+    "glowClip": 0,
+    "wallUnion": 0,
+    "openingTunnel": 0,
+    "openingWallIndex": 0,
+    "isoGeometry": 0
+  },
+  "renderedDevices": 200
+}

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

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

demo/performance/card-contract.mjs

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

demo/performance/compare.mjs

@@ -4,6 +4,7 @@ import { dirname, resolve } from 'node:path';
 import { evaluatePerformanceBudget, performanceSummaryMarkdown } from './evaluate.mjs';
 
 const valueArg = (name) => process.argv.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+const absoluteOnly = process.argv.includes('--absolute-only');
 const candidatePath = resolve(valueArg('candidate') ?? 'artifacts/performance/candidate.json');
 const baselinePath = resolve(valueArg('baseline') ?? 'artifacts/performance/baseline.json');
 const budgetsPath = resolve(valueArg('budgets') ?? 'demo/performance/budgets.json');
@@ -12,8 +13,9 @@ const outputPath = resolve(valueArg('output') ?? 'artifacts/performance/comparis
 const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
 const evaluation = evaluatePerformanceBudget({
   candidate: readJson(candidatePath),
-  baseline: readJson(baselinePath),
+  baseline: absoluteOnly ? null : readJson(baselinePath),
   budgets: readJson(budgetsPath),
+  absoluteOnly,
 });
 
 mkdirSync(dirname(outputPath), { recursive: true });

demo/performance/evaluate.mjs

@@ -60,16 +60,19 @@ const makeCheck = (id, actual, limit, details = {}) => ({
 });
 
 /**
- * Evaluate a candidate report against both stable absolute ceilings and a
- * report captured from the base SHA on the same runner.
+ * Evaluate a candidate report against stable absolute ceilings. Full captures
+ * additionally compare a base-SHA report from the same runner; fast smoke
+ * captures deliberately enforce only the hard candidate limits.
  */
-export const evaluatePerformanceBudget = ({ candidate, baseline, budgets }) => {
+export const evaluatePerformanceBudget = ({ candidate, baseline, budgets, absoluteOnly = false }) => {
   requireReport(candidate, budgets, 'candidate');
-  requireReport(baseline, budgets, 'baseline');
-  if (!sameJson(candidate.fixture, baseline.fixture)) throw new Error('fixture mismatch');
-  for (const key of ['node', 'chromium', 'platform', 'arch']) {
-    if (candidate.runtime?.[key] !== baseline.runtime?.[key]) {
-      throw new Error(`runtime mismatch for ${key}`);
+  if (!absoluteOnly) {
+    requireReport(baseline, budgets, 'baseline');
+    if (!sameJson(candidate.fixture, baseline.fixture)) throw new Error('fixture mismatch');
+    for (const key of ['node', 'chromium', 'platform', 'arch']) {
+      if (candidate.runtime?.[key] !== baseline.runtime?.[key]) {
+        throw new Error(`runtime mismatch for ${key}`);
+      }
     }
   }
 
@@ -77,63 +80,74 @@ export const evaluatePerformanceBudget = ({ candidate, baseline, budgets }) => {
   for (const [metric, budget] of Object.entries(budgets.timings)) {
     const stat = budget.stat ?? 'median';
     const actual = candidate.summary?.[metric]?.[stat];
-    const base = baseline.summary?.[metric]?.[stat];
-    if (!finite(actual) || !finite(base)) throw new Error(`missing ${stat} for ${metric}`);
-    const regressionLimit = relativeLimit(base, budget.maxRegressionRatio, budget.noiseAllowanceMs);
+    const base = absoluteOnly ? null : baseline.summary?.[metric]?.[stat];
+    if (!finite(actual) || (!absoluteOnly && !finite(base))) throw new Error(`missing ${stat} for ${metric}`);
+    const regressionLimit = absoluteOnly
+      ? Number.POSITIVE_INFINITY
+      : relativeLimit(base, budget.maxRegressionRatio, budget.noiseAllowanceMs);
     checks.push(makeCheck(
       `timing.${metric}.${stat}`,
       actual,
       Math.min(budget.hardMaxMs, regressionLimit),
-      { baseline: round(base), hardLimit: budget.hardMaxMs, regressionLimit: round(regressionLimit) },
+      {
+        ...(absoluteOnly ? {} : { baseline: round(base), regressionLimit: round(regressionLimit) }),
+        hardLimit: budget.hardMaxMs,
+      },
     ));
   }
 
   const candidateLong = candidate.longTasks ?? summarizeLongTasks(candidate.rows);
-  const baselineLong = baseline.longTasks ?? summarizeLongTasks(baseline.rows);
+  const baselineLong = absoluteOnly ? null : (baseline.longTasks ?? summarizeLongTasks(baseline.rows));
   const longTasksAvailable = candidate.rows.every((row) => {
     const windows = Object.values(row.longTasks ?? {});
     return windows.length > 0 && windows.every((item) => item?.supported === true);
   });
   checks.push({ id: 'longTask.available', actual: longTasksAvailable ? 1 : 0, limit: 1, pass: longTasksAvailable });
-  const singleRegressionLimit = relativeLimit(
-    baselineLong.maxSingleMs,
-    budgets.longTasks.maxSingleRegressionRatio,
+  const singleRegressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+    baselineLong.maxSingleMs, budgets.longTasks.maxSingleRegressionRatio,
     budgets.longTasks.maxSingleNoiseAllowanceMs,
   );
   checks.push(makeCheck(
     'longTask.maxSingleMs',
     candidateLong.maxSingleMs,
     Math.min(budgets.longTasks.maxSingleMs, singleRegressionLimit),
-    { baseline: baselineLong.maxSingleMs, hardLimit: budgets.longTasks.maxSingleMs },
+    {
+      ...(absoluteOnly ? {} : { baseline: baselineLong.maxSingleMs }),
+      hardLimit: budgets.longTasks.maxSingleMs,
+    },
   ));
-  const countRegressionLimit = relativeLimit(
-    baselineLong.countP95,
-    budgets.longTasks.maxCountRegressionRatio,
+  const countRegressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+    baselineLong.countP95, budgets.longTasks.maxCountRegressionRatio,
     budgets.longTasks.countNoiseAllowance,
   );
   checks.push(makeCheck(
     'longTask.countP95',
     candidateLong.countP95,
     Math.min(budgets.longTasks.maxCountP95, countRegressionLimit),
-    { baseline: baselineLong.countP95, hardLimit: budgets.longTasks.maxCountP95 },
+    {
+      ...(absoluteOnly ? {} : { baseline: baselineLong.countP95 }),
+      hardLimit: budgets.longTasks.maxCountP95,
+    },
   ));
-  const longRegressionLimit = relativeLimit(
-    baselineLong.totalP95Ms,
-    budgets.longTasks.maxTotalRegressionRatio,
+  const longRegressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+    baselineLong.totalP95Ms, budgets.longTasks.maxTotalRegressionRatio,
     budgets.longTasks.noiseAllowanceMs,
   );
   checks.push(makeCheck(
     'longTask.totalP95Ms',
     candidateLong.totalP95Ms,
     Math.min(budgets.longTasks.maxTotalP95Ms, longRegressionLimit),
-    { baseline: baselineLong.totalP95Ms, hardLimit: budgets.longTasks.maxTotalP95Ms },
+    {
+      ...(absoluteOnly ? {} : { baseline: baselineLong.totalP95Ms }),
+      hardLimit: budgets.longTasks.maxTotalP95Ms,
+    },
   ));
 
   const candidateHeap = candidate.rows
     .map((row) => row.heapGrowthBytes)
     .filter(finite)
     .map((value) => Math.max(0, value));
-  const baselineHeap = baseline.rows
+  const baselineHeap = absoluteOnly ? [] : baseline.rows
     .map((row) => row.heapGrowthBytes)
     .filter(finite)
     .map((value) => Math.max(0, value));
@@ -142,17 +156,22 @@ export const evaluatePerformanceBudget = ({ candidate, baseline, budgets }) => {
     id: 'heap.preciseGc', actual: preciseGc ? 1 : 0, limit: budgets.heap.required ? 1 : 0,
     pass: !budgets.heap.required || preciseGc,
   });
-  if (budgets.heap.required && (!candidateHeap.length || !baselineHeap.length)) {
+  if (budgets.heap.required && (!candidateHeap.length || (!absoluteOnly && !baselineHeap.length))) {
     checks.push({ id: 'heap.available', actual: candidateHeap.length, limit: 1, pass: false });
-  } else if (candidateHeap.length && baselineHeap.length) {
+  } else if (candidateHeap.length && (absoluteOnly || baselineHeap.length)) {
     const actual = percentile(candidateHeap, 0.95);
-    const base = percentile(baselineHeap, 0.95);
-    const regressionLimit = relativeLimit(base, budgets.heap.maxRegressionRatio, budgets.heap.noiseAllowanceBytes);
+    const base = absoluteOnly ? null : percentile(baselineHeap, 0.95);
+    const regressionLimit = absoluteOnly ? Number.POSITIVE_INFINITY : relativeLimit(
+      base, budgets.heap.maxRegressionRatio, budgets.heap.noiseAllowanceBytes,
+    );
     checks.push(makeCheck(
       'heap.growthP95Bytes',
       actual,
       Math.min(budgets.heap.hardMaxGrowthBytes, regressionLimit),
-      { baseline: base, hardLimit: budgets.heap.hardMaxGrowthBytes },
+      {
+        ...(absoluteOnly ? {} : { baseline: base }),
+        hardLimit: budgets.heap.hardMaxGrowthBytes,
+      },
     ));
   }
 
@@ -178,8 +197,9 @@ export const evaluatePerformanceBudget = ({ candidate, baseline, budgets }) => {
     schema: 1,
     profile: budgets.profile,
     pass: failures.length === 0,
+    mode: absoluteOnly ? 'absolute' : 'relative',
     candidateFingerprint: candidate.buildFingerprint,
-    baselineFingerprint: baseline.buildFingerprint,
+    baselineFingerprint: baseline?.buildFingerprint ?? null,
     checks,
     failures,
   };