houseplan-card/docs/reviews/CODE-REVIEW-358-r1.md

# CODE-REVIEW-358-r1

Issue: #358 · этап: code · заход r1 · блокирующих циклов израсходовано 0/2
SHA ревью: `bb3c1fd1` (HEAD ветки `issue/358-cold-view-vacuum`, детач от `origin/dev`)

## Скоуп

Систематический аудит после #357: единственный оставшийся достижимый из
холодного View жёсткий стаб `_vacMapId` — вызывается внутри `willUpdate`
(`_captureRenderDeviceSnapshot`) для любого пылесоса с телеметрией. На
холодной вкладке бросает `Houseplan editor runtime is not loaded`,
исключение внутри `willUpdate` убивает весь цикл обновления Lit — карточка
замирает целиком, не только клик, как в #357.

Задача — light track (`small`), ТЗ в теле issue, ревью по PROCESS.md §2.7.
Диф: `src/houseplan-card.ts`, `src/houseplan-editor-runtime.ts`, новый смок
`demo/smoke_cold_view_vacuum.mjs`, мутант в `scripts/mutation-gate.mjs`,
запись в `scripts/smoke-links.mjs`, оба changelog, синхронизация трёх копий
бандла и `docs/images/screenshots.json` (фингерпринт документации).

Соответствие job из `docs/SCOPE.md`: чинит регресс в основном View-пути
(J1/J2 — «живая пространственная карта» не должна замирать), правка не
расширяет скоуп.

## Как проверялось

Материал — `git log --oneline origin/dev..HEAD` (один коммит) и
`git diff origin/dev...HEAD`. Ручного тестирования не было, весь разбор —
чтением диффа плюс браузерные смоки локально.

**Дешёвые гейты (нет зелёного Validate на этом SHA — прогнал сам):**

| Гейт | Результат |
|---|---|
| `npx tsc --noEmit` | чисто, без вывода |
| `npm test` | `tests 1499 / pass 1498 / fail 0 / skipped 1` — совпадает с числом, заявленным автором |
| `npm run build` | успешно, `dist` собран |
| `npm run bundle:sync` | пересобрал; `git status --short` пуст — три копии бандла (dist, `custom_components/.../frontend`, `demo/srv/assets`) идентичны коммиту |
| `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links)` — diff трогает `src/**`, фингерпринт скриншотов в коммите уже обновлён и совпадает |

**Инварианты модели (`npm run invariants`)** — не прогонял: диф не трогает
геометрию, `layout`, `marker.space`, рёбра/толщину стен, `open_spans`.
Не применимо к этой задаче.

**Браузерные смоки** — выбор через
`node scripts/smoke-select.mjs --base <origin/dev SHA> --head HEAD`
(изменено 2 файла `src/**`, 11 символов проекта на изменённых строках,
16 прямых совпадений):

```
demo/smoke_cold_view_vacuum.mjs   ← _editorRuntime, _vacMapId, willUpdate
demo/smoke_binding_picker.mjs     ← _planHass
demo/smoke_cold_view_toggle.mjs   ← _editorRuntime
demo/smoke_controls.mjs           ← DevItem
demo/smoke_decor_text.mjs         ← _decorShapeDbl
demo/smoke_decor.mjs              ← _decorShapeDown
demo/smoke_drag_bounds.mjs        ← _decorShapeDown
demo/smoke_furniture.mjs          ← _decorShapeDbl
demo/smoke_grid_scale_invariance.mjs ← _editorRuntime
demo/smoke_ha_controls.mjs        ← _editorRuntime
demo/smoke_lazy_editor_chunk.mjs  ← _editorRuntime
demo/smoke_live_text.mjs          ← _decorShapeDbl
demo/smoke_partition_openings.mjs ← _editorRuntime
demo/smoke_static_icon.mjs        ← _planHass
demo/smoke_vacuum_firstuse.mjs    ← _vacCalConfirm
demo/smoke_ws_resilience.mjs      ← willUpdate
```

Решение по каждой строке:

- **Прогнал** (прямое совпадение на реально изменённом символе, либо
  AC-обязательный):
  - `smoke_cold_view_vacuum.mjs` — новый, доказывает AC1/AC3 — **OK**
  - `smoke_vacuum.mjs` — назван AC2 в issue напрямую (нет в выдаче
    smoke-select, т.к. не ссылается на изменённые символы текстом, но
    AC требует его явно) — **OK**
  - `smoke_vacuum_firstuse.mjs` — назван AC2, плюс прямое совпадение на
    `_vacCalConfirm` (гард К2) — **OK**
  - `smoke_decor.mjs` — прямое совпадение на `_decorShapeDown`, метод
    реально изменён (К2-гард) — **OK**
  - `smoke_drag_bounds.mjs` — то же самое совпадение на `_decorShapeDown` — **OK**
  - `smoke_cold_view_toggle.mjs` — тот же класс регрессии (#357),
    родственный контракт «холодная вкладка + `_editorRuntime`» — **OK**
  - `smoke_lazy_editor_chunk.mjs` — прямой контракт ленивой загрузки
    редакторского чанка, который меняющийся гард `_vacCalConfirm` мог
    задеть — **OK**
- **Не прогонял** (связь через широко используемое имя, символ сам не
  менялся):
  - `smoke_binding_picker.mjs`, `smoke_static_icon.mjs` — совпадение на
    `_planHass`, который в диффе фигурирует только как непереименованный
    параметр по умолчанию, не как изменённая логика.
  - `smoke_controls.mjs` — совпадение на типе `DevItem`, использованном в
    сигнатуре без изменения самого типа.
  - `smoke_decor_text.mjs`, `smoke_furniture.mjs`, `smoke_live_text.mjs` —
    совпадение на `_decorShapeDbl`, парном методе, который сам не тронут
    (гард получил только `_decorShapeDown`).
  - `smoke_grid_scale_invariance.mjs`, `smoke_ha_controls.mjs`,
    `smoke_partition_openings.mjs`, `smoke_ws_resilience.mjs` — совпадение
    на широких именах (`_editorRuntime`, `willUpdate`), не специфичных для
    вносимого изменения; уже покрыты по духу выбранными cold-view смоками.

Результаты (все зелёные, без правки ассертов):

```
smoke_cold_view_vacuum   → OK (все 10 подпроверок true)
smoke_vacuum             → OK
smoke_vacuum_firstuse    → OK (13 подпроверок true)
smoke_decor              → OK (13 подпроверок true)
smoke_drag_bounds        → OK (12 подпроверок true)
smoke_cold_view_toggle   → OK (12 подпроверок true)
smoke_lazy_editor_chunk  → OK (12 подпроверок true)
```

**AC3 (мутант «вернуть делегацию `_vacMapId` в runtime»)**: скрипт
`scripts/mutation-gate.mjs` в этом окружении не принимает выборочный `--id`
и вместо точечного прогона выполняет полный «чистый прогон» всех гардов
подряд; он остановился на несвязанном с задачей `FAIL … красный без
мутанта: node scripts/backend-test-guard.mjs … tests_backend/test_frontend_assets.py`
— причина `No module named pytest` (в этом контейнере не установлен
Python-бэкенд-харнесс, см. AGENTS.md «Backend» — pytest без Home Assistant
не то же самое, что полный харнесс, а тут его вообще нет). Это ограничение
окружения ревьюера, а не дефект диффа: диф не трогает
`custom_components/**/*.py` вообще.

Проверил мутант вручную вместо гейта: применил патч мутанта
(`cold-view-vacuum-mapid-delegated`) к рабочей копии `src/houseplan-card.ts`
руками (тот же find/replace, что в `scripts/mutation-gate.mjs`), пересобрал
(`npm run build && node scripts/bundle-sync.mjs`) и прогнал
`node demo/smoke_cold_view_vacuum.mjs`:

```
page.evaluate: Error: Houseplan editor runtime is not loaded
    at Dm._editorRuntimeOrThrow (...)
    at Dm._vacMapId (...)
    at Dm._captureRenderDeviceSnapshot (...)
    at Dm.willUpdate (...)
```

Смок падает некрасиво (необработанное исключение вместо контролируемого
`FAIL`) — это ожидаемо, ровно как описывает issue: `willUpdate` рушится
целиком. Мутант убит. После проверки восстановил файл из бэкапа,
пересобрал и снова прогнал смок на чистом коде — зелёный, `git status
--short` пуст.

**`python -m pytest tests_backend -q`** — не прогонял: диф не трогает
`custom_components/houseplan/**/*.py`; изменённые файлы под
`custom_components/houseplan/frontend/**` — класс D (генерируемое),
получены исключительно из `npm run bundle:sync`, вручную не редактировались
(проверено побайтовой идентичностью после локального пересобранного
прогона).

**`npm run golden:verify`** — не прогонял: диф не меняет геометрию, стили
и слои рендера; единственное визуальное изменение — фингерпринт
скриншотов документации (регенерация хэша из-за правки `src/**`, покрыта
`check-docs.mjs`), а не новый визуальный контент.

**Performance-профили** — не названы в AC, диф не трогает
производительность-чувствительные пути (только выбор map-id и два гарда).

## Находки

Не найдено. Правка — механический перенос владения (карта вместо
делегирования в редакторский runtime) по уже принятому образцу #357,
плюс два точечных гарда по образцу уже принятого `_decorShapeDbl` и
остальных редакторских диалогов. Инвариант HP-1541-01 (`selected_map: 0`
как валидный id, nullish-, а не truthy-проверка) перенесён дословно вместе
с комментарием — сверено построчно, диф не меняет ни один символ внутри
тела метода при переносе.

## Что проверено и корректно

- **К1 (перенос `_vacMapId`)**: `_vacMapId` теперь публичный метод
  `HouseplanCard`, тело идентично прежней реализации в
  `houseplan-editor-runtime.ts` (только откуда чтение `this` → `this`,
  без изменения логики). `HouseplanEditorHostPort` пополнен записью
  `_vacMapId: (d, tele, planHass?) => string` — типы совпадают с сигнатурой
  карты. Runtime-версия теперь однострочно делегирует в `this.host._vacMapId(...)`
  — тот же приём, что `_toggleIntent` в #357.
- **К2 (гарды)**:
  - `_decorShapeDown` получил `if (!this._editorRuntime) return;` — точно
    такой же гард, как у `_decorShapeDbl` (#337); проверено смоками
    `smoke_decor.mjs`/`smoke_drag_bounds.mjs` (не бьёт существующее
    поведение) и новым холодным смоком (тихий no-op на pointerdown).
  - Рендер `_vacCalConfirm` обёрнут `this._editorRuntime ?` — выровнено с
    соседними редакторскими диалогами (`_deviceInbox`, `_markerDialog`,
    `_rulesDialog`, `_settingsDialog` в том же шаблоне).
- **К3 (холодный смок)**: `demo/smoke_cold_view_vacuum.mjs` — инжектирует
  пылесос с реальной телеметрией (`vacuum_position`, `selected_map: 0`),
  проверяет: карточка рендерится на холодной вкладке; **три
  последовательных кадра** телеметрии подтверждают, что `willUpdate` не
  просто пережил первый рендер, а продолжает работать (`secondFrameCommitted`,
  `thirdFrameCommitted` сверяют, что снэпшот реально обновился, а не просто
  существует); `mapIdResolved` проверяет HP-1541-01 (`selected_map: 0` →
  `'0'`); `noEditorRuntimeRequest` — редакторский чанк не запрошен;
  `noPageErrors` — исключений нет; декор-гард (К2) проверен pointerdown по
  реальному DOM-узлу `.dshape`.
- **AC2**: `smoke_vacuum.mjs`, `smoke_vacuum_firstuse.mjs` зелёные без
  правки ассертов (прогнал сам, см. таблицу выше) — регресс в тёплом
  пути не внесён.
- **Трейлеры**: `Issue: #358`, `User-Visible: yes` на коммите; оба
  changelog (`docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`) правлены в том
  же коммите, формулировка на пользовательском языке («карточка
  замирает» / «freezes»), без утечки внутренних имён методов.
- **Трассируемость аудита**: `scripts/smoke-links.mjs` пополнен записью,
  привязывающей `vacMapIdWithFallback`/`vacMapIdFromAttrs`/`readVacTelemetry`
  к новому смоку — будущий diff по этим символам сам найдёт нужный смок.
- **Мутационный гейт**: новый мутант `cold-view-vacuum-mapid-delegated`
  добавлен, `guard` указывает на правильный смок; убит вручную (см. выше).
- **Одно число — один источник**: диф не добавляет и не меняет
  пользовательски видимую величину, отображаемую параллельно в двух
  местах (map id — внутреннее значение для сопоставления координат
  телеметрии, не рендерится пользователю как число/подпись). Проверка
  `test/single-source-numbers.test.mjs` — часть `npm test`, прошла в
  общем прогоне (1498/1498).
- **Границы аудита (раздел issue «Результат аудита в целом»)**: утверждение
  «остальные жёсткие заглушки недостижимы из холодного View» не
  перепроверял по всем 305 узлам графа — это отдельное объёмное
  статическое исследование вне этого диффа; для целей этого code review
  важно только то, что сам диф закрывает названные в AC1–AC4 дыры, что
  подтверждено смоками и мутантом.

## Чего не проверял

- Полный набор `demo/smoke_*.mjs` (200 файлов) — не запускал; выбор
  ограничен `smoke-select.mjs` + AC-именованными смоками (см. таблицу).
  Полный прогон — обязанность пред-релизного гейта (PROCESS.md §8), не
  этого ревью.
- `npm run invariants` — диф не трогает геометрию/толщину стен/`layout`.
- `python -m pytest tests_backend -q` — диф не трогает Python-код бэкенда;
  окружение ревьюера к тому же не имеет `pytest` вовсе.
- `npm run golden:verify` — диф не меняет визуальный рендер; единственное
  затронутое изображение (`01-view-desktop.png`) — побочный продукт
  пересборки бандла (иная хэш-сумма бандла → новый скриншот с тем же
  содержимым), покрыт `check-docs.mjs`, не самостоятельный визуальный
  гейт.
- Performance-профили — не названы в AC, диф не касается чувствительных
  к перфу путей.
- Полный `node scripts/mutation-gate.mjs` (весь набор мутантов) — не
  прогонял; прогнал только «чистый прогон» гардов до первой (несвязанной)
  остановки и точечно проверил новый мутант вручную патчем/ребилдом.

## Вердикт

Все AC1–AC4 доказаны: AC1/AC2 браузерными смоками (прогнаны лично),
AC3 — мутант проверен вручную и убит новым смоком, AC4 — чтением
диффа (гарды идентичны принятым образцам) плюс смок-проверка декор-гарда
исполнением. Трейлеры и changelog в порядке. Находок нет.

**Зелёный.**