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

# CODE-REVIEW-86-r1

- **Issue:** #86 — Тексты подсказок к настройкам, партия 1
- **ТЗ:** `docs/specs/086-settings-help-content-party1.md` (актуализировано 2026-08-30, зелёный SPEC-REVIEW-86-r1)
- **SHA материала:** `bd27fca107f61eee74d69bffeb1e15506402b6a4` (`origin/dev...HEAD`, diff трёх коммитов 97c807ba/58fb2ef5/bd27fca1)
- **Трек:** полный (нарушен критерий light-track «одна поверхность», сам автор это фиксирует в шапке ТЗ)
- **Заход:** r1 · блокирующих циклов израсходовано 0/4

## Скоуп

Diff добавляет 11 согласованных Party-1 `hp-help` подсказок (масштаб пространства,
общий Glow-радиус, режим заливки, роль источника света — обновлён текст пилота,
управление другими источниками, общий/локальный север, общий/локальный фон, стиль
стен нулевой толщины, «Показывать скрытые на плане») в `houseplan-editor-runtime.ts`
и параллельно — 5 space-подсказок в `houseplan-onboarding-runtime.ts`; переводит их
на en/ru/de/fr; удаляет 4 старых `.rhint`; добавляет unit-тесты инвентаря/parity/
no-duplicate, мутационный тест, один браузерный смок и правки трёх документов
(`CHANGELOG`×2, `USER-GUIDE.ru.md`, `TESTING.md`). Он же трогает
`docs/images/screenshots.json` (без файлов картинок).

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

Прогнано лично на SHA `bd27fca1` (окружение содержит Node 22 и Chromium, `npm ci`
не требовался):

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | зелёный |
| Unit | `npm test` | 1607 тестов, 1606 pass, 1 skip (тот же тест, что скипается и на `origin/dev`, к #86 не относится), 0 fail |
| Build + 3 копии бандла | `npm run build` затем `cmp dist/houseplan-card.js custom_components/.../houseplan-card.js` и `cmp dist/houseplan-assets.json custom_components/.../houseplan-assets.json` | идентичны |
| Bundle budget | `npm run bundle:budget` | initial View 280 313 B гзип, бюджет 300 000 — в норме |
| check-docs | `node scripts/check-docs.mjs` | зелёный (**но см. находку H1** — зелёный статус здесь ложноположителен) |
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 12 «прямое совпадение», 18 «слабая связь» (см. ниже) |
| Смоки прямого совпадения (12/12) | `node demo/smoke_help_affordance.mjs`, `smoke_bg_color`, `smoke_color_picker_consumers`, `smoke_device_inbox`, `smoke_dialog_zombie`, `smoke_disabled_device`, `smoke_esc_dialogs`, `smoke_gs_always`, `smoke_ha_controls`, `smoke_hidden_flag`, `smoke_motion_sense`, `smoke_sun` | все 12 зелёные |
| Мутационный гейт задачи | `node scripts/mutation-gate.mjs --id=settings-help-party1-placement-removed` | мутант пойман (`node --test` покраснел, как обязан) |
| **Golden** | `npm run golden:verify` | **красный, exit 1** — см. находку H2 |

**Что не прогонял и почему:**
- 18 «слабых связей» из `smoke-select` (общее имя `_config`) — не прогонял: каждая
  из них про геометрию/локали/optimize, не про диалоги настроек, диф не касается их
  логики, и после прогона всех 12 прямых совпадений сигнала для расширения нет.
- `python -m pytest tests_backend -q` — не прогонял: diff не касается
  `custom_components/**/*.py`, backend не затронут (среда ревью к тому же не имеет
  установленного pytest — `No module named pytest`, что подтверждает отсутствие
  окружения, а не маскирует красный результат: гейт неприменим по diff).
- Остальные 193 браузерных смока — задача не задевает геометрию/логику модели
  целиком, полный прогон здесь избыточен (PROCESS §8: полные наборы — предрелизный
  гейт).
- `model-invariants` — diff не трогает геометрию, ссылки, `layout`, `marker.space`
  или `open_spans`; не применимо.
- Реальный CI Validate на этом SHA не найден зелёным — прогнал дешёвые гейты сам,
  как и предписано.

## Находки

### H1 — Манифест скриншотов документации подделан, а не пересчитан (High, в скоупе)

`docs/images/screenshots.json` в коммите `bd27fca1` меняет `sourceFingerprint`
(`d77faa6e…` → `401722…`) и все десять `sourceSha256` на то же новое значение —
но ни один PNG в `docs/images/**` в этом коммите не изменился
(`git show bd27fca1 --stat -- docs/images/` показывает только правку JSON,
0 файлов картинок). Я запустил `npm run build` и `node scripts/check-docs.mjs` на
HEAD — гейт зелёный, потому что зафиксированный `sourceFingerprint` теперь
математически совпадает с текущим `src/**`. То есть кто-то отдельно посчитал
`visualFingerprint()` и вписал результат в JSON руками, не выполнив настоящую
пересъёмку.

Это прямо запрещённый в проекте путь. `scripts/docs-accept.mjs` (единственный
легитимный писатель этого файла) копирует новые PNG из артефакта CI
`Docs screenshots` и **не может** обновить манифест без файлов: он сверяет
`imageSha256` каждого кадра с байтами кандидата и требует `--reviewed`.
Исторический прецедент в этом же репозитории — коммиты «`docs: refresh screenshot
fingerprint`» (например `b1b1e743`) — **всегда** одновременно переписывают все
десять PNG (см. `git show b1b1e743 --stat`), потому что даже визуально идентичный
кадр даёт другие байты при пересъёмке (комментарий в `docs-accept.mjs` объясняет
это явно). Здесь PNG не тронуты вовсе — списанный ярлык не соответствует
содержимому.

Хуже того, содержимое двух сценариев из этого манифеста **действительно
устарело**: `space-create` (`fixture: 'empty'` → `card._openSpaceDialog('create')`
→ рендерится ровно тот `_renderSpaceDialog()` из
`houseplan-onboarding-runtime.ts`, куда этот diff добавил 5 подсказок) и
`device-editor` (`dialog: 'device'` → маркер-диалог, где `marker.controls_label` +
`.rhint` заменены на `helpfieldlabel` с новой иконкой) должны показывать новые
значки подсказок — а показывают старую картинку без них. Спецификация §17 прямо
требует «актуальные screenshots» как release-артефакт; вместо этого CI-гейт
`docs` обманут значением, которое ему не принадлежит.

**Как воспроизвести:** `git show bd27fca1 --stat -- docs/images/` → 0 изменённых
`.png`; `git show b1b1e743 --stat` → для сравнения, легитимный рефреш всегда меняет
все 10 файлов.

**Что нужно:** прогнать GH Actions `Docs screenshots` (`workflow_dispatch`),
скачать артефакт, `npm run docs:accept -- --reviewed --from=<artifact>`, отдать
на ревью человеку и закоммитить обновлённые PNG вместе с манифестом. Понижать
трек до «просто поправить фингерпринт» — то самое сокрытие, которое AGENTS.md
называет запрещённым по отношению к golden-эталонам и что не менее верно для
docs-скриншотов.

### H2 — `npm run golden:verify` красный: 6 эталонов расходятся с рендером (High, в скоупе)

Прогнал `npm run golden:verify` на `bd27fca1`: `exitCode=1`. Расхождения:

```
different   device-inbox-desktop-en-light
different   device-inbox-desktop-ru-dark
different   device-inbox-narrow-ru-dark
different   toggle-entity-dialog-desktop-en
different   toggle-entity-dialog-mobile-ru
different   space-room-color-popover-desktop-ru
```

Все шесть напрямую объясняются этим diff'ом, не совпадением имени символа:

- `device-inbox-*` — сценарии `dialog: 'device-inbox'` (`demo/golden/matrix.mjs:383-392`)
  снимают ровно тот блок, где чекбокс «Показывать скрытые на плане» обёрнут в
  новый `<span class="device-inbox-filter-help">` с триггером
  `device_inbox.show_hidden.help` (`houseplan-editor-runtime.ts:11815-11825`).
- `toggle-entity-dialog-*` — сценарии `dialog: 'device'` для `golden-washer`
  (`matrix.mjs:765-778`) открывают тот же маркер-диалог, где
  `marker.controls_label` + постоянный `.rhint` заменены на
  `<div class="helpfieldlabel">` с триггером `marker.controls.help`
  (`houseplan-editor-runtime.ts:12588-12592`) — сдвиг разметки докатывается вниз до
  `toggle_entity`-секции того же диалога.
- `space-room-color-popover-desktop-ru` — сценарий `dialog: 'space-room-color'`
  (`matrix.mjs:795-797`) открывает попап цвета комнаты в диалоге пространства,
  выше которого теперь стоит новый `helpfieldlabel` для `space.fill_mode.help`.

Ни один `demo/golden/baselines/**` файл в diff'е не менялся
(`git diff --stat origin/dev...HEAD -- demo/golden/` — пусто), значит эти шесть
эталонов не пересматривались вовсе. Хендофф-комментарий автора в issue
(«Проверки: npm test… smoke_help_affordance… mutation… docs и bundle budget — OK»)
`golden:verify` не упоминает — гейт не прогонялся.

Отдельно (не блокирует и не относится к #86): `furniture-transform-light/dark` —
`missing-baseline`, но baseline для них отсутствует в дереве и на `origin/dev` тоже
— унаследованный, не внесённый этим diff'ом пробел, к задаче не относится.

**Как воспроизвести:** `npm run bundle:sync && npm run golden:verify` на
`bd27fca1` → `EXIT=1`, шесть `different`.

**Что нужно:** просмотреть `artifacts/golden/diff/{device-inbox-*,
toggle-entity-dialog-*, space-room-color-popover-desktop-ru}.png`, убедиться, что
новая раскладка — то, что задумано (правдоподобно, раз это ровно новые триггеры
подсказок), и принять через `npm run golden:accept -- --reviewed` на полном
Linux CI-артефакте. ТЗ §14 прямо планировал «Golden: general settings and space
dialog with help open… full Linux artifact review required» — этот пункт плана
не выполнен, а не просто пропущен по недосмотру мелочи.

### M1 — Onboarding-путь 5 space-подсказок не доказан исполнением (Medium, в скоупе)

ТЗ §8 требует: «Пять space-подсказок присутствуют и в обычном editor runtime, и в
отдельном onboarding runtime… их текст и поведение идентичны», а §14 планирует
браузерный смок «по одному placement на… space». `demo/smoke_help_affordance.mjs`
целиком работает через обычный редактор (`card._openSpaceDialog('edit', card._space)`),
и ни один смок/golden не открывает cold-onboarding путь
(`_openSpaceDialog('create')` при пустом `_serverCfg.spaces`), который ведёт в
`HouseplanOnboardingRuntime._renderSpaceDialog()` с отдельной, скопированной
реализацией `_help()` (`houseplan-onboarding-runtime.ts:54-60`). Единственная
проверка, которая реально открывала бы этот путь в браузере — сценарий
`space-create` документационных скриншотов — сам оказался несвежим (H1).
Статический regex-тест в `test/i18n.test.mjs` (`helpSource` = конкатенация двух
файлов) доказывает только, что строка `this._help('space.xxx.help')` присутствует
в исходнике `houseplan-onboarding-runtime.ts`, а не что она реально рендерится,
не мутирует `_spaceDialog` и работает мышью/клавиатурой/тапом в этом отдельном
компоненте.

Прочитал код: `_help()` в онбординге текстуально идентичен варианту в
`houseplan-editor-runtime.ts`, импорт `./hp-help` добавлен, сигнатура и порядок
аргументов совпадают — на вид рабочий. Но это «проверено чтением, не
исполнением», а не автотест, и явно заявленного как такового в
`docs/reviews`/handoff нет. Учитывая, что H1 обесценил единственный кандидат на
исполняемое доказательство, AC5/AC7 для onboarding-поверхности сейчас не доказаны
никак, кроме моего чтения.

**Что нужно:** либо добавить в `demo/smoke_help_affordance.mjs` (или отдельный
файл) сценарий, открывающий `_openSpaceDialog('create')` из пустого состояния и
повторяющий read-only/inventory проверки для всех пяти onboarding-триггеров, либо
явно зафиксировать в ТЗ/тестовом плане, что onboarding-путь покрывается только
docs-скриншотом — и тогда почему это допустимо. Совместно с H1 естественно
чинится одним заходом: настоящая пересъёмка `space-create` подтвердит хотя бы
рендер, а отдельный смок — поведение.

### L1 — `.help`-ключ не совпадает буквально с ключом видимого label (Low, снимается без правки)

Унаследовано из ревью ТЗ (SPEC-REVIEW-86-r1): `space.cell_cm.help` соседствует с
`space.scale_label`, `space.fill_mode.help` — с `space.fill_label`. Не создаёт
двусмысленности контракта, тот же паттерн уже был у пилотов #68, находится в
рамках технической свободы реализации по PROCESS.md §7.1. Оставляю без правки.

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

- **AC1 (инвентарь).** `grep -oE "_help\('[^']+\.help'\)"` по обоим рантаймам даёт
  ровно 11 Party-1 ключей плюс уже существующие 8 пилотных `marker.*` ключей из
  #68 — новых мест за пределами §6 нет. Пять `space.*`-ключей продублированы
  один-в-один в `houseplan-onboarding-runtime.ts`. Доказано и чтением, и тестом
  `issue 86 Party 1 has the exact help inventory` (`test/i18n.test.mjs`) — тест
  запускался (`npm test`, зелёный) и умеет падать: мутационный гейт
  `settings-help-party1-placement-removed` подтверждает (прогнал лично).
- **AC2/AC3 (канонический текст, parity).** RU/EN тексты в `en.json`/`ru.json`
  побайтово совпадают с таблицей §6 ТЗ — сверил вручную все 11 строк. DE/FR
  прочитаны целиком (см. выдержку выше) — передают тот же смысл, не пропускают
  предложений. `.help.aria` пары присутствуют во всех 4 словарях, тест
  `i18n: every literal help call has body and full aria keys in every language`
  прогонялся и прошёл.
- **AC4 (без дублей).** `marker.controls_hint`, `gs.bg_daynight_hint`,
  `gs.north_hint`, `space.zero_wall_help` удалены из всех 4 словарей и из обоих
  рантаймов — подтверждено тестом `issue 86 removes explanatory hints…` (прошёл)
  и `grep` лично.
- **AC6 (input/a11y).** Переиспользует lifecycle #68 без форка
  (`import './hp-help'`, тот же `_help()` контракт); `smoke_help_affordance.mjs`
  (прогнал, зелёный) покрывает hover/focus/click/Escape/disabled/Popover-fallback
  для нового содержимого партии наравне со старым пилотом.
- **AC7 (узкий viewport 390 px).** `party1ShowHiddenHelpInsideNarrowViewport` в
  смоке проверяет геометрию попапа в 390 px — прошло. 200%-zoom и «reviewed
  golden» часть AC7 не доказана — см. H2.
- **AC8 (модель не меняется).** Прочитан весь diff `src/**` — ни одного изменения
  вне JSX/CSS шаблонов и двух новых `_help()`-методов; `strictNumber`,
  `touchSpaceDisplay`, обработчики `@change`/`@input` не тронуты. `npm test`
  (1606/1607 pass) включает существующие config-serialization снапшоты — без
  регрессий.
- **AC9 (партии 2/3 отсутствуют).** Diff `src/**` просмотрен построчно — нет ни
  одного `_help()` вне §6 сверх уже существующих `marker.*` пилотов; в i18n-файлах
  нет добавленных ключей `opening.*`, `wallthick.*`, `decor.*`,
  `device.binding.*` и т. п. из партий 2/3.
- **Гейты общего назначения.** typecheck/test/build/bundle-sync/bundle-budget/
  check-docs (формально) — все зелёные, три копии бандла идентичны.
- **Одно число — один источник.** Diff не добавляет и не меняет ни одной
  пользовательской величины (только текст подсказок) — правило неприменимо.
- **Трейлеры.** `Issue: #86` на всех трёх коммитах; `User-Visible: yes` в
  `bd27fca1` — оба changelog (`docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`) правлены
  в этом же коммите, формулировки на месте.

## Вывод

Контент-часть партии 1 (11 подсказок, переводы, source contract, mutation-тест)
выполнена аккуратно и проходит собственные unit- и smoke-гейты. Но два
предрелизных для видимого рендера гейта, обязательных именно для этой задачи —
`docs`-скриншоты и `golden` — либо подделаны (H1), либо действительно красные и
не прогонялись (H2). Оба находятся в скоупе issue (сам diff их и ломает) и
требуют настоящей пересъёмки/приёмки, а не текстовой правки. Пока это не сделано,
вердикт не может быть даже жёлтым.