houseplan-card/docs/TESTING.md

# Testing

Действующая инструкция: правила для новых тестов, гейты, локальный набор и
матрицы релизной проверки. Ручные чек-листы по поверхностям и приложения по
отдельным issue перенесены дословно в [`testing-notes/`](testing-notes/README.md)
(#634) — индекс там же, по заголовку и номеру issue. Новый чек-лист по задаче
ложится в приложение своей подсистемы; сюда — только то, что действует для
любой задачи. Маркер `[auto: …]` у пункта в любом из этих файлов обещает
падающую проверку в том же коммите (`docs/DEVELOPMENT.md`).

## Правила для новых тестов (issue #85) — обязательны

Зелёный тест в этом проекте несколько раз означал «ничего не проверено»:
смок непрерывности не заметил удаления механизма, который защищает; golden-сцена,
заведённая под #71, была пустой; смок теней был зелёным, пока тени физически не
рисовались. Общее у всех случаев — **тест ни разу не проверяли на способность
падать**. Отсюда правила.

1. **Наличие атрибута, класса или узла — не проверка поведения.** Такой ассерт
   допустим только рядом с пиксельным либо поведенческим: атрибут доказывает,
   что код выполнился, а не что механизм сработал.
2. **Golden-сцена, заведённая под конкретную задачу, несёт семантический
   ассерт** (`warmPixelRegion` и родственные в `demo/golden/run.mjs`): сцена
   обязана падать, если перестала показывать то, ради чего заведена. Пиксельный
   дифф с эталоном этого не заменяет — пустая сцена совпадает со своим пустым
   эталоном идеально.
3. **Фикстура содержит слои, которые тест защищает.** Смок непрерывности без
   подложки, Glow и декора проверяет пустую страницу; солнце с азимутом, при
   котором луч не достигает единственного окна (#89), — та же ошибка в
   геометрии.
4. **Тест, охраняющий механизм, сопровождается мутантом** в
   `scripts/mutation-registry.mjs`: 2–5 строк патча, воспроизводящего поломку,
   против которой тест заведён, и тест обязан на ней краснеть. Чистым функциям
   с обычными юнитами мутант не нужен.
5. **Тавтологический ассерт — читающий то же свойство, которое код только что
   выставил, — не пишется вовсе.** Он может упасть только при удалении строки,
   но не при её неработоспособности.
6. **Смок входит в сценарий через публичную поверхность** (#629): DOM с
   контрактными хуками (`docs/data-hp-contract.json`), события HA и фикстуры,
   тестовый фасад `window.__hpTest`. Приватное поле карточки допускается только
   для **чтения** в ассертах. Смок, открывший диалог присваиванием
   `c._roomDialog = …`, зелёный и при сломанной кнопке, — это тот же «ничего не
   проверено», что в правилах 1–5. Новые записи держит гейт
   `no-new-private-writes`, остальное — ревью (раздел ниже).

Проверка: `node scripts/mutation-gate.mjs --check` — якоря патчей живы;
полный прогон — workflow `mutation-gate.yml` (шесть чересполосных шардов
`--shard=i/6` — при четырёх шард упёрся в потолок 60 минут на 810 мутантах, #604;
один зафиксированный commit/tree для всего прогона; каждый артефакт несёт
identity и исход шага прогона, а отдельный агрегатор fail-closed отвергает
смешанные, неполные или прерванные по таймауту evidence даже при частичном
rerun; лог шарда считается зелёным только с итоговой строкой `поймано N из M`)
каждую ночь по расписанию (01:00 UTC); в
релизном гейте он не участвует — проверяет тесты, а не продукт; отказ сам
заводит issue с отчётом (#472, #513). С #620 ночь по расписанию на дереве, уже
доказанном зелёным полным прогоном, шарды не гоняет: зелёный агрегатор
оставляет маркер в кэше Actions (tree материала, `github.workflow_sha`, номер
прогона), следующая ночь с тем же tree и тем же workflow принимает его и пишет в
сводку `reused from run N`. Маркер старше семи суток не принимается (tree
фиксирует код, а не раннер), ручной dispatch гоняет реестр всегда, а красный
прогон маркера не оставляет — следующая ночь гонит реестр заново и снова
заводит issue. Решение — чистая функция `scripts/mutation-nightly-reuse.mjs`
(`test/mutation-nightly-reuse.test.mjs`). Дешёвая половина
идёт с юнитами: `test/mutation-gate.test.mjs`. Локально для дельты задачи —
`node scripts/mutation-gate.mjs --changed origin/dev..HEAD`: гоняются только
мутанты, чьи patch-файлы или **входы гарда** задеты диффом (#332, #475, #492).
Входы гарда — это не только файлы, названные в команде: обёртка
(`scripts/*-guard.mjs`) объявляет запускаемые тесты в `export const
GUARD_INPUTS` (умолчание `backend-test-guard.mjs` —
`tests_backend/test_ha_import_export.py`, действует без третьего аргумента), а
от каждого файла гарда берётся замыкание импортов и путей: смок тянет
`demo/serve.mjs`, compat-хелперы и фикстуры, pytest-модуль — `conftest.py`.
`src/**` в замыкание не входит — это сторона патча (§6.4 ТЗ #492). Дифф,
трогающий сам реестр, дополнительно отбирает добавленные и изменённые
определения относительно реестра базы (`git show <base>:scripts/mutation-registry.mjs`;
для commit до #558 используется прежний `scripts/mutation-gate.mjs`). В одном
CLI-вызове замыкание входов вычисляется один раз на уникальную строку guard и
переиспользуется отбором и fingerprint; строка `plan-metrics` показывает число
запросов/вычислений/чтений и время построения плана.
Бандл собирается только мутантам с браузерным гвардом; компиляция тестов в
worktree стартует с тёплого `test-build/` основного дерева.

С #550 ненулевой exit сам по себе не означает «мутант пойман». Цепочка
`setup && ... && oracle` разбирается по шагам: ошибки компиляции, сборки,
загрузки/collection теста дают `setup-failure`; неприменимый патч —
`invalid-mutation`; timeout, signal и отсутствие exit status —
`infrastructure-interruption`; зелёный oracle — `survived`. Только падение
последнего заявленного oracle даёт `assertion-killed` и может попасть в
ledger. Compile-time проверка допустима как самостоятельный свидетель лишь с
явным полем определения `oracle: 'compile'`; прятать её в префиксе обычного
browser/backend guard нельзя. Все недоказанные исходы завершают гейт кодом 2 и
отдельно называются в ночном отчёте. Гвард с `--test-name-pattern`, не исполнивший
ни одного теста, — тоже `setup-failure` ([#650](testing-notes/infrastructure.md#пустое-совпадение---test-name-pattern-650)).

С #568 `setup-failure` в дифф-режиме **атрибутируется**: раннер прогоняет
ОПРЕДЕЛЕНИЕ БАЗЫ диапазона на дереве базы и говорит, чей это отказ.
Предсуществующий (не готовится и на базе) гейт задачи не красит — автор не чинит
чужое, — но называется строкой `pre-existing-setup-failures=<id,…>` и обязан
покраснеть в ночном полном прогоне, у которого есть адресат (#472). Отказ,
внесённый диффом, краснит как раньше; свидетеля, которого в базе нет, оправдывать
нечем по построению. Сравнение именно подобного с подобным: с определением из
головы своя же сломанная правка реестра выглядела бы предсуществующей.

Приём, который делает мутанта мёртвым молча, один и тот же: **статически**
мёртвая ветка в `.ts` — `if (false)`, `false &&`, безусловный `return` в начале
функции. TypeScript перестаёт помнить сужения, сделанные выше (`profile` снова
`| null`), компиляция падает до заявленного теста. Писать ложь, ложную в
рантайме, но не статически: `if (eps < 0)`, `String(mode) === 'mutant-never-…'`,
`if (walls.length >= 0) return walls.slice();`. В `.mjs` этого ограничения нет.

В CI `changed_mutants` бежит не на каждом пуше, а по явному запросу (#510,
сужено в #601): `workflow_dispatch validate.yml -f mutants=true` (его делают
ревью-конвейер на материале ревью и слияние на кандидате) и PR. `full=true`
(ночь, кнопка), кандидат беты (трейлер `Release:`) и обычный push мутантов не
запрашивают: за 08–09.09 мутанты на промежуточных пушах стоили 48 из 56 часов
job-минут и в основном отменялись следующим пушем, а к бете каждая задача уже
прогнана ими на ревью и на слитом кандидате; ночь покрыта полным реестром
(`mutation-gate.yml`). Доказательство мутантов для ревью — именно dispatch-прогон
на точном SHA; зелёный push-прогон им не является. Релизный гейт mutant-jobs не
требует (`CI_PROOF_POLICIES.release.mutants = false`).

План шарда (`--plan-only`) считается до установки окружения (#518) и с #620
называет окружение своих гардов строками `plan-browser=` и `plan-python=`
(`scripts/mutation-environment.mjs`). Python с зависимостями бэкенда ставится
только шарду с pytest-гардами (в графе исполнения гарда есть `.py` или запуск
`'python3'`/pytest), Chromium — только шарду, чей граф исполнения импортирует
Playwright (смоки, golden, юниты через `demo/serve.mjs`). Граф исполнения — не
замыкание входов для отбора: файлы из строки гарда, объявленные входы обёрток,
пути, названные в этих точках входа, и их относительные импорты. Шард без
таких гардов окружение не ставит, но исполняется и отчитывается — шесть
mutant-jobs в доказательстве ревью (#541) не меняются. Ошибка признака
ложной зелени не даёт: гард без своей среды краснеет уже чистым прогоном.

`changed_mutants` добавляет `--ledger=<файл>` — журнал доказанных
свидетелей (#481, #550): после каждого пойманного мутанта в файл пишутся тип
доказательства (`assertion` или явно объявленный `compile`) и отпечаток
его входов (файлы патча, все входы гарда по замыканию выше, объявление мутанта;
строка версии продукта нормализована), и мутант с тем же отпечатком в следующем
прогоне не гоняется. Схема 2 намеренно не читает старые записи без типа
доказательства: setup failure из прежнего раннера нельзя унаследовать как
зелёный результат.
Журнал живёт в кэше Actions по шарду, сохраняется при любом исходе шага, так
что отменённый пуш или таймаут не пропадают даром. Полный прогон и `--id`
журнал не читают; `--ledger` без `--changed` — ошибка.

## Новый код не добавляет any (#342)

```bash
node scripts/no-new-any.mjs                              # origin/dev...HEAD
node scripts/no-new-any.mjs --base origin/dev --head HEAD
node scripts/no-new-any.mjs --diff patch.diff            # или `-` для stdin
```

В `src/**` сейчас **1034 вхождения** явного `any` в 49 файлах — больше, чем
называл аудит (330), потому что монолит с тех пор разделился и его обвязка
уехала в `houseplan-editor-runtime.ts`. Разовая замена такого объёма — месяц
риска ради нуля пользовательской ценности, поэтому долг снимается при плановом
извлечении подсистем (#425, прежний #34). Гейт держит приращение на нуле.

Что он судит: **только добавленные строки** диапазона. Существующий `any` на
нетронутой строке законен. Правка строки со старым `any` считается новой
ответственностью — изменённая строка в диффе выглядит добавленной, и это
намеренно: тронул, значит либо типизируй, либо обоснуй.

Исключение объявляется на той же строке:

```ts
const raw = (event as any).detail; // any-ok: форма события HA не типизирована в @types
```

Голый `// any-ok`, пустая причина и шаблоны вроде `todo`, `hack`, `потом` не
проходят: причина обязана быть не короче 12 символов и не совпадать со списком
заглушек в скрипте.

Ложных срабатываний нет по построению, а не по старанию: текст разбирается
парсером TypeScript, и нарушением считается узел `AnyKeyword`. Слово «any» в
комментарии, в строковом литерале, в многострочном шаблоне `html` и в
идентификаторах `company`, `anyOf`, `manyRooms` таким узлом не является.

В CI гейт вызывается в job `frontend`; её checkout получил полную историю без
блобов, потому что diff-aware проверке нужен диапазон, а содержимое старых
ревизий — нет.

## Тестовый фасад и приватное состояние (#629)

На 22.09 смоки писали в приватное состояние карточки больше двух тысяч раз и
поэтому не видели обработчиков ввода и путей закрытия: шестерёнку, поле имени,
Escape и крестик не нажимал никто. Фасад харнесса `window.__hpTest`
(`demo/helpers/hp-test.mjs`) делает то же, что человек или другой клиент HA.
Он ставится `launch()`, `launchColdView()` и `launchPanelCold()`; смок,
перезагрузивший страницу, зовёт `installHpTestOnPage(page)` заново. Кода фасада в
бандле нет — `window.__hpTest.preinstalled` обязан быть `false`.

| Операция | Что нажимает или шлёт | Готово, когда |
|---|---|---|
| `setMode(m)` | `[data-hp="mode-tab"][data-mode=m]`; для `view` — `[data-hp="editor-close"]` | `ha-card[data-hp-mode=m]` |
| `setTool(t)` | `[data-hp="toolbar"] [data-hp="tool"][data-tool=t]` | кнопка нажата, `updateComplete` |
| `switchSpace(id)` | `[data-hp="space-tab"][data-id=id]` | вкладка `aria-current="page"` |
| `openRoomEdit(roomId)` | `[data-hp="room-settings"][data-room=roomId]` (режим plan) | открыт `[data-kind="room"]`, возвращается он |
| `openMarkerDialog(id?)` | без id — `add-device`; с id — `[data-hp="device"][data-id]` в режиме devices | открыт `[data-kind="marker"]` |
| `openSpaceDialog('create' \| 'edit', id?)` | `space-add` / `create-space`; `space-settings[data-id]` | открыт `[data-kind="space"]` |
| `setServerConfig(next \| fn)` | фикстура `__pushServerConfig`: событие `houseplan_config_updated`, карточка сама читает `houseplan/config/get` | карточка приняла ревизию (тайм-аут 5 с) |
| `setLayout(next \| fn)` | то же через `houseplan_layout_updated` (у карточки дебаунс 200 мс) | ревизия раскладки принята |
| `input(el, text, {clear})` | `keydown` → значение → `InputEvent(insertText)` → `keyup` на символ, в конце `change` | `updateComplete` |
| `close(dialog?, {via})` | `escape` — keydown на активном элементе; `x` — крестик окна; `cancel` — `[data-hp="dialog-cancel"]` содержимого | диалог отсоединён или открыт `[data-kind="confirm"]`; `{closed, confirm}` |

`settled()` — `updateComplete` и два кадра, общий шаг ожидания.

Правила фасада:

- элемент ищется **только** по таблице `SELECTORS`, и каждый её селектор объявлен
  в JSON-контракте с аудиторией `test` (`test/hp-test-facade.test.mjs`). Если
  элемента нет — именованная ошибка с селектором и режимом, без отката на
  приватный метод;
- фасад ничего не пишет в карточку и читает только `_cfgRev`, `_layoutRev`,
  `_serverCfg`, `_layout` — то, что читает и сам продукт;
- `setServerConfig`/`setLayout` означают «план изменили на сервере», а не
  «несохранённая правка»: функциональный аргумент получает `structuredClone`
  текущего конфига карточки. Правку в редакторе смок делает через UI.
  Фикстура, как настоящий сервер, отвечает `conflict` на запись с
  `expected_rev` старше доставленной ревизии — только после первой доставки,
  чтобы смоки без фасада видели прежнюю фикстуру;
- крестик `ha-dialog` HA живёт в его приватном shadow root: `via: 'x'` там —
  ошибка, Escape и cancel работают.

Гейт и счётчик:

```bash
node scripts/no-new-private-writes.mjs                              # origin/dev...HEAD
node scripts/no-new-private-writes.mjs --base origin/dev --head HEAD
node scripts/no-new-private-writes.mjs --diff patch.diff            # или `-`
node scripts/no-new-private-writes.mjs --count                      # остаток на HEAD, не гейт
```

Судятся добавленные строки `demo/smoke_*.mjs` и `demo/helpers/**`. Записью
считаются присваивание любым оператором, `++`/`--` и `delete`, если в цепочке
левой части есть сегмент `_x`: `c._serverCfg.model_version = 7` — запись в
`_serverCfg`, а `window.__card = …`, `o.ok = …` и цепочки от `this` — нет. Вызовы
`._setMode(`, `._openRoomEdit(`, `._openMarkerDialog(`, `._openSpaceDialog(` —
тоже нарушение, с подсказкой операции фасада. Правка строки зачитывается
удалённой записью в то же поле того же файла; перенос непрерывного куска — как
у `no-new-any`. Исключение — на той же строке:

```js
c._drag = { id, sx, sy }; // private-ok: #NNN состояние жеста, операции фасада для него нет
```

с теми же требованиями к причине, что у `any-ok`. Мутации через вызовы
(`c._serverCfg.spaces.push(…)`) и через локальный псевдоним гейт не видит — их
ловит ревью по правилу №6 выше. Гейт идёт в `gate:small` и в шаге job
`frontend` рядом с `no-new-any`, с той же базой.

`HP_SMOKE_CHECKS=1 node demo/smoke_<имя>.mjs` печатает в `finish()`
отсортированный список имён проверок — так перевод смока доказывается «без
потери утверждений»: список до и после сравнивается построчно.

## Локальный набор перед пушем (#343)

Красный CI — дорогой способ узнать о проблеме: пять минут ожидания, а при
код-ревью ещё и лишний раунд. Прецедент назван в задаче: находка r2-H1 в #329
стоила целого раунда и ловилась локальным `npm test`.

```bash
node scripts/pre-push-gate.mjs                       # origin/dev..HEAD
node scripts/pre-push-gate.mjs --base origin/dev --head HEAD
node scripts/pre-push-gate.mjs --no-smokes --no-mutants
node scripts/pre-push-gate.mjs --max-smokes=3 --max-mutants=1
```

Что прогоняется: проверка, что ветка приведена к `origin/dev`, `npx tsc
--noEmit`, `npm test`, смоки, выбранные `scripts/smoke-select.mjs` по диффу, и
мутанты, выбранные `scripts/mutation-gate.mjs --changed` по тем же файлам.

Отставание от `dev` — предупреждение, а не провал набора: гейтом остаётся
конвейер, который приводит ветку сам (#257) и забыть не может. Смысл локальной
проверки в другом: после любого ребейза разбор на ревью становится полным, а не
по дельте (§7.2), а конфликт всё равно чинится на машине автора — дешевле
узнать об этом до пуша, чем из комментария через сорок минут (#364). Отключается
флагом `--no-rebase-check`. Замер на реальном
диапазоне (`953f675~1..953f675`, правка `src/houseplan-card.ts`): типы 5 с,
юниты 17–19 с, два смока 22 с — **46 секунд** на всё.

Три свойства, без которых такой набор бесполезен:

- **не останавливается на первом упавшем** — иначе автор узнаёт о втором
  нарушении следующим кругом, то есть ровно то, от чего набор защищает;
- **громко перечисляет, чего не проверял** — молчаливый пропуск дважды стоил
  проекту дня (#171, #207), а «Verified» без названной команды и её результата
  доказательством не является;
- **не претендует на полноту.** Golden, полная матрица смоков, HA-харнесс —
  heavy-набор Validate на кандидате; весь мутационный реестр — ночное
  расписание (#513), а не этот набор.

Бандл не собирается: `bundle-sync.mjs` раскладывает закоммиченный `dist`, а
свежесть проверяет сам продукт — `assertFreshDemoBundle` внутри каждого смока
сверяет вшитый отпечаток с исходниками дерева и скажет, если нужна пересборка.

Лимиты по умолчанию — шесть смоков и два мутанта. Мутант дорог: каждый
пересобирает бандл, а правка `src/houseplan-card.ts` задевает их 62. Превышение
лимита не проглатывается — набор печатает точную команду для полного прогона.

Три вида ответа `smoke-select` различаются и здесь: дифф без исполняемого кода —
«смоки не требуются»; прямое совпадение или зарегистрированная связь —
прогоняется; **связь не доказана** — отдельная громкая строка, потому что это не
«проверять нечего»: молчание стоило #234 бета-блокирующего регресса.

### В хуке — по умолчанию для веток задач (#633)

Прежде набор включался только переменной `HP_PREPUSH_GATE=1`, и ошибки, которые
ловит `gate:small`, находил Validate с конвейером через полчаса после пуша. Теперь
`.githooks/pre-push` сам вызывает `node scripts/pre-push-gate.mjs --hook`, и тот
для каждой пушимой ветки решает:

| Случай | Что делает хук |
|---|---|
| ветка `issue/*`, в диффе от merge-base с `origin/dev` есть хоть один файл не класса C/D | `npm run gate:small` (`scripts/gate-small.mjs --base=<merge-base>`); красный — push отклонён |
| дифф ветки — только класс C/D (документы ревью, changelog, бандл) или пуст | набор не гонится, причина печатается |
| ветка не `issue/*`, тег, удаление | набор не гонится |
| исполняемый дифф, но пушится не `HEAD` | push отклонён: набор проверяет рабочее дерево, а оно не совпадает с пушимым коммитом |
| `HP_PREPUSH_GATE=0` | выключен явно |
| `HP_PREPUSH_GATE=1` | гонится для любой ветки и любого диффа |

Процессный гейт идёт первым — он отвечает за секунды; набор — после, и
прогоняются оба, чтобы все провалы были видны одним кругом. `gate:small` идёт
минуты: в песочнице агента, где команда живёт ≈ 3 минуты, набор гоняют отдельной
командой, а пушат с `HP_PREPUSH_GATE=0` — и пишут об этом в хендоффе.

Ручной режим выше (`node scripts/pre-push-gate.mjs` без `--hook`) остался как был:
tsc, юниты, смоки и мутанты по диффу. Решение хука покрыто
`test/pre-push-gate.test.mjs`, включая настоящий `.githooks/pre-push` на
временном репозитории.

Обойти, как и процессный гейт, можно через `git push --no-verify` — и тогда то же
самое найдёт Validate, уже после того как код окажется в `dev`.

## Manifest входов: какие job запускать и что хешировать (#492)

Один модуль, `scripts/check-inputs.mjs`, объявляет каждую проверку Validate
(`preflight`, `frontend`, `changed_mutants`, `integration`, `smoke`, `golden`,
`performance_smoke`, `backend`) через корни и точки входа, а остальное
вычисляет: от точек входа берётся замыкание — импорты транзитивно, строковые
пути как листья, каталог по строке — все текстовые файлы под ним. Из этого
manifest читают и `classify-changes.mjs` (job `changes`: job запускается,
если дифф задел хотя бы один её вход), и `gate-reuse.mjs` (ключ реюза =
хеш содержимого всех входов job). Два места не могут разойтись: до #492 у
бэкенда ключ не знал relay, converter и schema, а golden/perf — `serve.mjs`,
`demo.html` и compat-хелперов.

Правила, которые стоит знать:

- `validate.yml` — вход toolchain каждой job: правка workflow гоняет всё;
- `src/**` — вход только браузерных job, кроме точных cross-runtime входов
  `src/plan-optimizer.ts` и `src/logic.ts`, которые backend pytest читает для
  parity-контрактов; `demo/fixtures/large-house.mjs` и
  `demo/fixtures/visual-matrix.mjs` так же явно входят в backend, потому что
  pytest запускает их через Node dynamic import. Точные исключения не делают
  весь UI или каталог fixtures входом backend (#542); backend от остального UI
  не зависит, а
  `custom_components/houseplan/manifest.json` (версия) держит правило «кандидат
  релиза прогоняет всё» и для него;
- `assets/furniture/**` — вход `frontend` (#671); `assets/fonts/**` — явное исключение ручного `generate-pdf-font.mjs`;
- **неизвестный охраняемый вход** — исполняемый файл под `scripts/`, `demo/`, `test/`, `tests_backend/`, `.github/`, `custom_components/`, `src/` либо tracked-файл под `assets/**`, которого нет в manifest ни
  одной проверки, — расширяет прогон до полного набора и называется
  в summary. Лист покрытия (`node scripts/check-inputs.mjs --coverage`,
  `test/check-inputs.test.mjs`) требует, чтобы каждый такой файл был чьим-то
  входом либо стоял в `NOT_AN_INPUT` с причиной: новый скрипт или asset без записи —
  красный юнит, не вечное расширение прогонов;
- **overlay принятых эталонов** (`demo/golden/baselines/**`, #573) — вход
  только `golden`, у которой он стоит явным корнем. Раскрытие каталога по
  строке его не выдаёт: корпус отпечатка называет `demo/golden` каталогом,
  но берёт из него только `*.mjs`, а до #573 индекс эталонов через это
  раскрытие становился входом smoke, perf и 181 из 183 браузерных
  свидетелей — приёмка 13 кадров на beta.3 (`ad4000f9`) сменила их ключи и
  отпечатки, и второй полный Validate повторил 22 минуты уже сделанной
  работы. Явная ссылка на файл индекса (как в `test/check-inputs.test.mjs`)
  входом остаётся;
- `--check=<job>` печатает входы, `--why=<файл>` — цепочку, по которой файл
  стал входом.

Отрицательные пробы (`test/gate-reuse.test.mjs`, `test/classify-changes.test.mjs`,
`test/check-inputs.test.mjs`) держат представителей каждой категории входов и
обратную пробу для UI ↔ backend; мутанты `manifest-drops-workflow-input`,
`classify-unknown-input-is-unaffected`, `reuse-backend-hashes-ui`,
`backend-dynamic-inputs-dropped`, `baseline-overlay-leaks-into-every-key`,
`guard-inputs-ignore-wrapper-defaults`, `registry-diff-not-selected`,
`merge-pushes-unvalidated-candidate`, `merge-ignores-lease-rejection`,
`nightly-does-not-wait` держат сам протокол.

Чистые Python-контракты канонизации, которым не нужен Home Assistant, находятся
в `tests_backend/test_coordinate_canonicalization_pure.py`. Они обязаны реально
исполняться в локальном `pytest tests_backend`, а не исчезать за module-level
`importorskip`; schema/store/virtual-light проверки остаются в HA-зависимом
`test_coordinate_canonicalization.py`. Поведение static-card capability
доказывается unit/smoke-счётчиками и состоянием runtime, а не regex по исходнику
(#440).

Без установленного Home Assistant (нативная Windows, песочница) HA-харнесс
`tests_backend/test_ha_*.py` **не собирается вовсе** — `conftest.py` исключает
эти файлы через `collect_ignore_glob`, поэтому их нет ни в `passed`, ни в
`skipped`, и зелёная итоговая строка про них ничего не говорит. С #630 pytest в
таком прогоне печатает в шапке и в итоге строку `HA harness NOT collected: N
test_ha_*.py files (M tests)` со ссылкой на канон — Linux CI или WSL
(`bash scripts/wsl-setup.sh --verify`). N и M считаются при каждом запуске по
тому же glob (объявления `def test_*`/`async def test_*`, без размножения
параметризацией), в документах их не переписывают. Проверка —
`tests_backend/test_conftest_harness_notice.py`, мутанты
`ha-harness-notice-silent` и `ha-harness-notice-count-frozen`.

## Версия в кадрах и попиксельная приёмка (#512)

Golden-кадры и скриншоты документации не должны меняться от bump версии. Для
golden отображаемая версия идёт через seam `displayVersion()` (`src/card-version.ts`,
глобальная `__HP_VERSION_OVERRIDE__` — только для харнесов; продукт её не задаёт),
и харнес фиксирует `0.0.0-golden`. Для docs-скриншотов есть локальная приёмка
`npm run docs:accept -- --identical`: кадры сравниваются по декодированным
пикселям, и при полном совпадении обновляется только отпечаток исходников.

## Ядра фронтенда растут только осознанно (#425, заменяет #34)

- [ ] `node --test test/core-file-budget.test.mjs` — потолки на
      `src/houseplan-card.ts` и `src/houseplan-editor-runtime.ts`.

Гейт-храповик: наверх не пускает, вниз требует зафиксировать выигрыш. Если он
покраснел, вариантов два, и оба нормальные — вынести из ядра столько же строк,
сколько добавили, либо поднять потолок отдельным решением, объяснив его в
ревью. Молча поднять не выйдет: число живёт в тесте и попадает в дифф.

Вторая половина правила (уменьшение ниже потолка на 250 строк тоже краснеет)
нужна затем, что без неё вынос двух тысяч строк ничего не меняет: потолок
остаётся прежним, и ядро дорастает до него обратно «в рамках бюджета».

## Локальный CI-совместимый toolchain (#557)

- [ ] `test/toolchain-pins.test.mjs` проверяет, что явно выбранный Python
      используется и для version probe, и для `pip show`, без fallback к
      `python`/`python3`/`py` из PATH; строки результата содержат пути Node,
      Python, Playwright package и Chromium executable.
- [ ] Тот же unit запрещает Windows setup менять persistent PATH или удалять
      существующий venv, требует SHA-256 проверки portable Node и подтверждает,
      что WSL verify запускает настоящий HA subset и одну Linux golden-съёмку.
- [ ] На Windows два последовательных
      `pwsh -File scripts/windows-toolchain.ps1 setup` проходят: первый ставит
      изолированные runtimes, второй переиспользует их; `check` после каждого
      зелёный и печатает фактические версии/пути.
- [ ] Из свежего ext4 checkout WSL команда
      `bash scripts/wsl-setup.sh --verify` проходит `test_ha_setup.py` без skip,
      создаёт непустой `panel-wide-view-light-en.png` и печатает длительность.
      Это ранняя обратная связь; независимый exact-SHA Validate остаётся каноном.

## E2E на реальном Home Assistant (#514)

Репозиторий `Matysh/houseplan-e2e`: настоящий HA в docker, House Plan из
релиза или из дерева коммита, 13 сценариев Playwright (боковая панель,
дашборды, роли, телефон, PDF, рестарт HA, первый запуск, обновление). Ночью —
по расписанию на последней бете; для **стабильного** релиза `release.yml`
запускает его на **SHA кандидата** (`scripts/e2e-gate.mjs --ref=<sha>`, #540:
ставится `custom_components/houseplan` из tarball коммита — то же дерево, из
которого `git archive` строит `houseplan.zip`) и ждёт зелёного: красный —
релиз остаётся черновиком, ассеты не публикуются. В цикле разработки и на
бетах не участвует.

## Environments matrix

Run View/kiosk core flows in every applicable touch environment. Run editor core
flows in desktop environments; touch editors only need the safety floor and
separately promised workflows:

- [ ] Chrome / Edge (desktop, Windows or Linux) — View + all editors
- [ ] Firefox (desktop) — View + all editors; SVG viewBox math and container queries differ historically
- [ ] Safari (macOS) — View + all editors; pointer events / pinch behavior
- [ ] HA Companion app, Android — View only as the parity contract; cold start is mandatory
- [ ] HA Companion app, iOS — View only as the parity contract
- [ ] Tablet in kiosk/panel mode — View/kiosk, landscape, touch gestures
- [ ] Phone portrait, narrow ≤400 px — View and View dialogs/actions
- [ ] Dark theme and light theme (badges, dialogs, plan contrast)
- [ ] RU, EN and DE profile locales (+ `language:` card option forcing each);
      `de-DE`, `de-AT` and `de-CH` resolve to German, while an unknown locale
      falls back to English [unit: i18n, i18n-runtime]
- [ ] German cold start requests exactly one locale chunk, shows only a neutral
      busy frame before commit and never flashes English; a second card reuses
      the page cache. EN/RU request no locale chunk [auto: German locale smoke]
- [ ] German locale download failure retries the content-hashed asset once and
      then unblocks the card in English with one warning [unit: i18n-runtime;
      auto: German locale smoke fault injection]
- [ ] German View and a representative settings/device dialog fit at desktop
      and 390 px without horizontal overflow or clipped actions [golden: German
      desktop/mobile scenarios; auto: dialog footer width at desktop and 320 px]

## Touch support and release gates

The product contract is defined in `docs/TOUCH-SUPPORT.md`:

| Surface | Touch release status |
|---|---|
| View and View dialogs/actions | Required and release-blocking |
| Kiosk/wall tablet | Required and release-blocking |
| Editor entry/exit and no accidental mutation during multi-touch | Safety floor; release-blocking |
| Feature parity of Plan/Device/Background editors | Best effort; not a general release gate |

All editors remain fully tested on desktop with mouse/keyboard. A touch-editor
failure may be accepted only as a deliberate scope change with updated user
documentation and test classification in the same change. “Best effort” cannot
be used to waive data corruption, unsafe service calls, permission failures,
missing destructive confirmation or an editor exception that breaks View.

- [ ] Smoke harness itself (v1.43.2, audit T1/T2): every smoke asserts named
      facts via `check`/`checkAll` and exits non-zero on any mismatch or
      uncaught in-card exception; the suite runs in CI against a FRESHLY built
      bundle. Sanity ritual: break one invariant on purpose (e.g. remove the
      kiosk editor guard) and confirm the matching smoke goes red [auto: CI job "smoke"]

- [ ] Room gear discoverability (v1.43.3, user feedback): in the Plan editor
      every room card carries a pill button "⚙ Room" of a FIXED readable size
      (independent of the card font) — including rooms without a name; it opens
      Room settings [auto: smoke_feedback_v2]
- [ ] Metrics readability (v1.43.3): the metrics line is 0.75 of the room name
      (was 0.62 — unreadable on tablets); per-room sliders still apply on top [auto: smoke_feedback_v2]
- [ ] Touch tooltips: touch/pen immediately clears hover even if the browser
      claims hover support; compatibility mouse is ignored, while a later real
      paired-mouse event restores desktop hover without reload
      [auto: smoke_feedback_v2]

- [ ] Light-source flag (v1.44.0, user feedback): a smart SWITCH driving dumb
      fixtures creates a Glow pool only once "This device is a
      light source" is ticked. External targets under "Controls" still feed
      group state/statistics but never create a pool at the switch coordinates;
      unticked devices without a light entity never glow [auto: smoke_glow]
- [ ] Device card controls (v1.44.0): the device card opens with its
      controllable entities FIRST — toggles right there (≥30 px tap targets),
      cover/lock/climate open HA more-info; model, links and manuals moved
      below; config/diagnostic entities are not listed; locks never toggle from
      the card [auto: smoke_card_controls]

- [ ] Lock invariant, all paths (v1.44.2, review CR-1): icon tap, controls[],
      device card and _cardToggle refuse locks/alarm panels entirely; the door
      card's Unlock asks for confirmation, Lock does not [auto: smoke_lock_invariant]
- [ ] Attachment migration is transactional (v1.44.2, review CR-2/CR-3):
      rebinding COPIES files, saves the config, and only then deletes the old
      folder; a rejected save leaves the old files and urls intact; a name
      collision in the destination gets a unique name (the pre-existing file is
      never silently linked); urls are rewritten only for confirmed copies
      [auto: unit logic.test + tests_backend]

- [ ] Plans and PDFs load in a real browser (v1.44.3, B1 regression): open a
      dashboard with an uploaded plan — the background renders and a manual link
      opens; DevTools shows /api/houseplan/content/... returning 200 via a
      signed url, while the same url without authSig returns 401
      [auto: tests_backend + manual]
- [ ] Auth policy is single-sourced (v1.44.4, B2): the HTTP upload and every WS
      write use the same `may_write`, which denies non-admins when the config
      entry is unavailable [auto: tests_backend]
- [ ] Coordinates and caps (v1.44.4, B5): NaN/Infinity are refused on room
      rects, polygon vertices, view_box and openings — not only in layout; the
      openings list honours MAX_OPENINGS [auto: tests_backend]
- [ ] Drag hardening (v1.44.4, L4 sub-item): every drag pipeline captures the
      pointer through the tolerant helper; decor follows the infinite canvas
      and stops only at the shared normalized ±5000 garbage bound
      [auto: smoke_decor, smoke_drag_bounds]

- [ ] Room climate counts hidden sensors (v1.44.5): a thermometer that is NOT
      placed on the plan (hidden by filtering or by the user) still feeds the
      room card, the tooltip and the temperature fill; fridges/TRVs still do
      not; an explicit per-room source still wins [auto: unit devices.test]
- [ ] Room climate follows explicit House Plan placement (#317): a real
      temperature/humidity sensor moved away from registry Area A votes exactly
      once in its marker target, including an area-less `space + room_id` room;
      hidden markers still vote, while removed/HA-disabled ones do not. Exact
      entity placement wins over its parent device only for that entity, and
      explicit room sources remain authoritative [auto:
      smoke_room_climate_placement; units: test/devices.test.mjs; mutation:
      room-climate-ignores-marker-placement]
- [ ] Room hover + tooltip: in View, hovering any room visibly highlights it
      (filled, transparent and area-less alike) and shows its name plus clean-
      floor area; temperature/signal follow when available. Thick walls reduce
      the area to the inner contour. The wash/halo use plain SVG without CSS
      filters, and hovering never replaces or flashes the Glow pool/gradient
      DOM. Editors do neither [auto: smoke_ux_fixes + smoke_glow; manual visual]

## Golden-image regression matrix

`npm run golden:capture` records the data-only scenarios from
`demo/golden/matrix.mjs` into ignored `artifacts/golden/actual/`; it never
changes a reviewed image and fails if any scenario itself errors.
`golden:verify` always compares the complete matrix (a diagnostic
`--scenario` is capture-only) with
`demo/golden/baselines/`, writes high-contrast pixel diffs and fails on a
missing image, changed dimensions, excessive diff, scenario error or stale
matrix manifest. It also refuses a different Chromium build and baseline PNGs
whose hashes no longer match the reviewed manifest. `golden:accept --
--reviewed` is the only baseline write path and also requires a complete,
error-free report captured from the current source fingerprint; the entire set
is validated before any reference is copied.

The matrix covers thick wall junctions, the full #197 multi-room
virtual-junction resilience fixture in Plan and View (including the #261
measured exterior-wedge fill probe), the #249 three-ray
unequal-thickness fixture with a semantic filled-node/empty-old-wedge gate,
the two #275 orthogonal-strip fixtures at `cell_cm: 5/1` with dense
`isPointInFill()` containment before raster comparison,
virtual/physical boundaries,
partitions/columns, axis-aligned and 45° door/window/gate tunnels, hidden
opening symbols, Glow and sun, live/manual Glow overlap and light through a doorway,
light/temperature/LQI fill splits on a wall axis, hover over Glow and nested rooms, all three editors, dark/light themes,
0.4×/fit/2.5×, warm remount and adaptive RU/EN dialogs including focus and the
decor colour popover. The two device-dialog scenes deliberately bind a real
light, select Always plus fixed colour/brightness, and scroll the complete
role/colour/brightness/radius block into the captured viewport; a screenshot
that contains only its heading is a scenario error, not an acceptable baseline. In the
canonical Linux CI profile Chromium, viewport, DPR, locale, timezone, colour
profile, font rendering, animations and caret are deterministic. The separate
CI job captures review candidates until the first baseline is accepted; after
that it automatically runs blocking verification. Review and accept the
`golden-images` CI artifact rather than treating a developer OS raster as the
canonical set. See `demo/golden/README.md`.

For #249, `test/wall-thickness.test.mjs` additionally covers equal and unequal
three-/four-ray nodes (including literal 15/50/70 cm arms), reversed input,
winding/order changes, production `coordScale = 1000`, unchanged two-ray joins
and the anonymised regression fixture in
`test/fixtures/249-multiwall-junction.json`. The asymmetric corner-Split case
also proves that the union of clean-room floors equals the original room union
minus canonical bounded masonry and that every floor vertex remains inside the
source building.
`demo/smoke_multiwall_junction.mjs` checks Plan/View/kiosk/Static/hidden-Iso
parity, paper and clean-floor presence, shared Glow/sun masonry, cache reuse on
HA/theme ticks, no saved-config mutation, a filled node and the removed old
spike. Full golden/smoke/performance remain pre-beta gates.

For #272 the same fixture and table-driven equal/mixed T/X fans inventory every
polygon hole fully enclosed in the local degree-3+ node window. The matrix runs
at `cell_cm: 5` and `cell_cm: 1`, reversed/permuted input and production scale;
`roomGeom`, final masonry and paper must all report zero local holes while the
existing discarded-wedge probe remains empty. The browser smoke repeats a
local flood-fill with real `SVGGeometryElement.isPointInFill()` in Plan, View,
kiosk and Static, and inspects hidden-Iso and light/sun source rings. The golden
scenario declares `enclosedHoles: 0`, so semantic failure happens before the
whole-frame pixel threshold. Mutation `multi-wall-exterior-corridor-disabled`
restores point-only contact and must be caught by the hole inventory even while
the legacy single-point probes remain green.

For #275, `test/fixtures/275-orthogonal-strip-containment.json` contains only
the minimized coordinates and wall depths needed from both owner backups. The
unit oracle classifies perpendicular ray pairs independently, differences their
finite strip union against `roomGeom`/paper, covers adjacent overlapping repair
masks and keeps the non-orthogonal #249 discarded wedge empty. The production-
bundle smoke densely samples the same strips through Plan, View, kiosk, Static,
hidden Iso and light barriers. Golden scenes
`orthogonal-strip-cell-5-view-dark` and
`orthogonal-strip-cell-1-view-dark` repeat that semantic containment before
pixel comparison; `enclosedHoles: 0` remains a separate #272 assertion and can
no longer approve an exterior-connected notch. For private full-plan evidence,
`scripts/wall-strip-containment.mjs <backup...>` checks raw, Optimize preview,
applied canonical storage and JSON reload without printing or committing plan
contents. Mutation `multi-wall-orthogonal-strip-protection-disabled` restores
the release escape and must be killed by the containment tests.

For #288, the node-map unit fixes the real topology class: `349 / 120 / 5`
steps, a 30 cm short ray and a perpendicular 20 cm shared wall beginning at its
far endpoint. It runs at scales corresponding to `cell_cm: 1/5/30`, reversed
endpoints and input permutations, while an outer continuation remains under
the established #271 contract. `demo/smoke_real_plan_masonry.mjs` loads both
tracked real-plan fixtures through the production bundle and densely samples
every undeclared room edge with `SVGGeometryElement.isPointInFill()`. Both
plans require exact `gapCount: 0` and `totalGapSteps: 0`. Mutation
`multi-wall-shared-continuation-protection-disabled` removes the endpoint
handoff and must be killed by the unit before the real-plan smoke.

For #261, the anonymised #197 fixture also probes the real regression point
`(895.5, 556)`: `roomGeom`, final masonry and paper must fill it, while every
clean-floor contour must exclude it. The browser smoke repeats semantic point
coverage in Plan, View, kiosk, Static, hidden Iso and light/sun masonry; the two
existing #197 goldens require `SVGGeometryElement.isPointInFill()` at the same
point. Mutation `multi-wall-paper-full-origin-cut` restores the faulty
offset-origin cut and must make that regression test fail.

## Large-house performance gate

`npm run benchmark:large-house` runs a deterministic fictional three-floor
fixture with 60 rooms, 200 devices, 100 openings, 60 partitions, 40 columns and
500 decor objects. It records model readiness, first stable render, space
switch, HA state update, shared-wall resize preview, pan/zoom, settings-dialog render, repeated navigation,
Long Tasks, warmed hot-cache growth and post-GC heap growth.

`Validate` carries a `performance_smoke`: one warm-up and three measured
samples of the heaviest 60-source Glow state. It enforces absolute timing, Long
Task, heap, cache and 200-device ceilings, but does not claim to detect small
relative regressions. Together with the browser smokes and `golden` it runs on
the beta candidate (a head commit with a `Release:` trailer), on the nightly
`full=true` dispatch of `dev` and on pull requests — not on every push (#479).

The dedicated `Full Performance` workflow builds the candidate and base SHA,
then captures seven measured samples for each sequentially on the same Node 22,
Playwright Chromium and hosted runner. It runs on `main`, weekly and by manual
dispatch. `demo/performance/compare.mjs` applies the tighter of the approved
absolute ceiling and baseline-relative allowance. Stable release assets additionally need
an exact-SHA green Full Performance run; every release, including a prerelease,
needs the full exact-SHA `Validate` proof. Raw reports and comparisons are uploaded as CI artifacts, and the check
tables are written to the job summary. Local measurements remain diagnostic.
See `demo/performance/README.md` for commands and the budget-review contract.

## Installation / upgrade / removal

- [ ] A successful entry setup registers `/houseplan` as `houseplan-panel` only
      after store migrations/repairs complete. The panel is visible to admin and
      read-only users; actual editor/write access still follows `can_write` and
      `admin_only` [auto backend: panel registration/permission tests].
- [ ] Missing `houseplan-panel.js`, static registration failure, foreign path
      collision or panel API exception leaves the integration, WS API and
      dashboard card usable. Unload removes only the exact panel object owned by
      this setup generation; reload/reconnect cannot duplicate or delete a
      replacement [auto backend: panel lifecycle + mutation tests].
- [ ] Wide View/editor and 320 px read-only/empty `/houseplan` have no horizontal
      overflow or duplicate product title. Menu activation emits bubbling and
      composed `hass-toggle-menu`; `hass`, `narrow`, `route` and `panel` updates
      preserve one child card; leaving the route keeps only the space and returns
      in View [auto: `smoke_houseplan_panel`; golden: panel matrix].
- [ ] The dashboard full card advertises `{columns:"full",rows:10,min_rows:6}`
      to Sections; the compact card has no grid default. Fixed 6/10/14-row slots,
      all editors and a 30-step storm stay bounded and preserve camera intent;
      other layouts stay unchanged [browser: `smoke_sections_resize`,
      `smoke_houseplan_panel`; unit/mutation: `houseplan-panel`, four grid witnesses].
- [ ] README and User Guide in EN/RU each separate Storage mode, HA 2026.2+
      `resource_mode: yaml` and legacy HA 2024.6–2026.1 full-YAML dashboard
      setup; both hard-reload shortcuts are present and a flat top-level
      `resources:` block is rejected [auto: `check-docs`].
- [ ] Fresh Storage-mode install from the HACS default catalog (plain search)
      → integration appears; the exact `?v=` URL is created or adopted in the
      Lovelace resource registry without an `extra_module_url` fallback or a
      duplicate. An upgrade updates the one canonical entry [auto backend:
      `tests_backend/test_ha_frontend_registration.py`].
- [ ] `single_config_entry`: adding a second entry is impossible [manual]
- [ ] A pending or transient registry installs the fallback immediately, then
      retries exactly once after HA started plus the fixed one-second delay.
      Success removes only this setup's exact fallback when supported; unload
      before the listener, during the delay or during the task prevents all late
      side effects, and reloads do not accumulate listeners [auto backend:
      `tests_backend/test_ha_frontend_registration.py`; mutation gate].
- [ ] HA 2026.2+ YAML resources and a legacy 2024.6–2026.1 full-YAML dashboard
      use the truthful `extra_module_url` fallback without a registry write or
      polling loop. A Storage dashboard is never instructed to switch to legacy
      `mode: yaml` just for House Plan [auto backend:
      `tests_backend/test_ha_frontend_registration.py`; auto: `check-docs`].
- [ ] A missing frontend bundle or failed static-path registration does not fail
      integration setup, does not report a successful loader and does not consume
      the one-time notification; System Health reports file/static/loader/outcome
      honestly [auto backend: `tests_backend/test_ha_frontend_registration.py`,
      `tests_backend/test_ha_setup.py::test_missing_frontend_bundle_does_not_skip_backend_setup`].
- [ ] The first available frontend registration creates one localized persistent
      hard-reload notification. Repeated setup, retry completion and a new House
      Plan version create no duplicate; uninstall dismisses it best effort [auto
      backend: `tests_backend/test_ha_frontend_registration.py`; mutation gate].
- [ ] System Health preserves existing plan statistics and reports card file,
      static path, typed resource outcome, final loader, exact versioned URL,
      retry state, safe error and first-notice state without traceback, tokens or
      external paths [auto backend:
      `tests_backend/test_ha_frontend_registration.py`].
- [ ] In a full card, every successful `config/get` authoritatively replaces the
      backend version. Equal versions and unknown/malformed values show nothing;
      a known symmetric mismatch shows one direction-neutral manual-reload banner
      in ordinary View/editor/dialog states and never reloads without a trusted
      click [unit: `version-recovery`; auto: `smoke_version_recovery`].
- [ ] In kiosk, an unsafe mismatch preserves the current frame. The first fully
      safe idle state stores the backend target before exactly one reload; the same
      target after reload/remount or in a second full card gets no second attempt,
      a new target gets one, and unavailable `sessionStorage` is manual-only
      [unit: `version-recovery`; auto: `smoke_version_recovery`; mutation gate].
- [ ] `custom:houseplan-space-card` loads the shared bundle/config but never owns
      the version banner, safety timer or automatic reload [unit:
      `version-recovery`; auto: `smoke_version_recovery`].
- [ ] Removal deletes every House Plan Lovelace resource entry with the canonical
      base URL and dismisses the notification; `.storage/houseplan.*` survives and
      reinstall picks the old config up [auto backend:
      `tests_backend/test_ha_frontend_registration.py`].
- [ ] Diagnostics download works; personal fields (name/link/description/pdfs) are `**REDACTED**` [manual]

## Edge cases

- [ ] HA instance with zero devices/areas → onboarding works, rooms can be drawn, no crashes [manual]
- [ ] Space with zero rooms → renders; markup hint visible
- [ ] Room without HA area + borders OFF → still has a transparent View hit
      surface, highlights on hover, reports geometric floor area, click does nothing
- [ ] No zigbee devices anywhere → no LQI badges, lqi fill leaves all rooms unfilled [manual]
- [ ] 100+ devices in one space → build under ~50 ms [manual], drag stays smooth
- [ ] Very long device/room names → ellipsis/wrap, no layout explosion
- [ ] HTML/emoji in names (`<b>xss</b>`, 🚿) → rendered as text, never as markup [manual]
- [ ] Plan file deleted from disk → Repairs issue appears after config save/restart; re-upload clears it [auto backend]
- [ ] Corrupted `.storage/houseplan.config` → entry retries (ConfigEntryNotReady), no crash loop [auto backend]
- [ ] HA restart while a dialog is open → next save gets a clean error/conflict, no data loss
- [ ] Legacy layout entries (v1 {x,y} without space) are ignored gracefully
- [ ] Kiosk cold start on mobile app: the card is defined before dashboard
      render; a version mismatch follows the one-safe-attempt contract from the
      installation section instead of flashing or entering a reload loop
      [auto: `smoke_version_recovery`].

## Release regression quickies

- [ ] Browser console has zero errors from houseplan-card.js on: dashboard load, markup, dialogs, zoom
- [ ] HA log has zero houseplan errors/warnings after restart
- [ ] `npm test` (frontend), `pytest tests_backend` (pure only without HA: `test_ha_*.py` are not collected, the run prints how many — #630), CI HA-harness — all green
- [ ] README screenshots/GIF still match the current UI (synthetic home only)