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

# CODE-REVIEW-211-r1 — визуальное соответствие маркеров дизайн-пакету #179

- **Issue:** https://github.com/Matysh/houseplan-card/issues/211
- **ТЗ:** `docs/specs/211-device-icons-visual-parity.md` (принято `SPEC-REVIEW-211-r2`, зелёный)
- **Диапазон реализации:** `6feb018..270cf63`
  - `4e82976` fix: match device icons to designer package · `Issue: #211` · `User-Visible: yes`
  - `270cf63` test: strengthen unavailable hover mutant · `Issue: #211` · `User-Visible: no`
- **Цикл:** r1/4

## Скоуп проверки

Диапазон реализации ограничен двумя коммитами: `src/styles.ts` (geometry/theme/state
tokens), новый независимый reference-fixture (`demo/srv/reference/device-icons/**`),
расширенный `demo/smoke_device_icon_design.mjs`, новый
`demo/capture_device_icon_reference.mjs`, точечная правка мутационного теста
`scripts/mutation-gate.mjs`, три копии бандла, оба changelog, `docs/TESTING.md` и
шесть скриншотов `docs/images/*`. Ни `device-visual.ts`, ни `device-presentation.ts`,
ни `device-pulse.ts`, ни `device-face.ts` не тронуты — совпадает с §10 ТЗ
(«не должны меняться без доказанного отсутствующего renderer fact»). Конфиг,
i18n, `custom_components/**/*.py` не задеты.

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

Проверка велась не по описанию хендоффа, а самостоятельным прогоном на чистом
дереве и собственным чтением диффа/скриншотов.

### Гейты — прогнаны

```
npx tsc --noEmit                                          → чисто, без ошибок
npm test                                                   → 939 pass, 0 fail, 0 skipped
npm run build                                              → OK
cmp dist vs custom_components/.../houseplan-card.js        → идентичны
cmp dist vs demo/srv/assets/houseplan-card.js               → идентичны
node scripts/check-docs.mjs                                 → "7 files, 10 external links" — OK
node demo/smoke_device_icon_design.mjs                       → все 29 фактов true, OK
node demo/smoke_device_preview_parity.mjs                    → все 15 фактов true, OK
node demo/smoke_static_icon.mjs                              → все 12 фактов true, OK
node demo/smoke_disabled_device.mjs                          → все 7 фактов true, OK
node scripts/mutation-gate.mjs --id=device-unavailable-hover-restored
    → чистый прогон зелёный; мутант красный, «поймано 1 из 1»
node demo/capture_device_icon_reference.mjs                  → сгенерирован
    artifacts/device-icon-reference/device-icons-reference-runtime.{html,png}
node demo/golden/run.mjs --mode=capture --scenario=device-icon-state-table-light
node demo/golden/run.mjs --mode=capture --scenario=device-icon-state-table-dark
    → оба "different" (ожидаемо, старый baseline зафиксировал баг)
```

Независимая проверка «тест умеет падать» (дисциплина применена к самому
дорогому и самому content-heavy тесту, `smoke_device_icon_design.mjs`): в
отдельном `git clone` собран бандл со **старым** `src/styles.ts` (коммит
`6feb018`, до фикса) и **новым** смоком/reference-фикстурой (`270cf63`).
Результат: **13 фактов красные** — `geometryMatchesAt32_56_96`,
`referenceStateMatrixMatches`, `referenceHoverMatches`,
`virtualUsesThemeDefaultWithDashedShell`, `iconCoreIsCircle`,
`valueBadgeIsPill`, `activeUsesPackageAmber`,
`lightActiveUsesWhiteGlyphAndAmberShell`, `darkDefaultShellUsesPackageStroke`,
`darkHoverChangesCoreOnly`, `selectionDecoratesCoreNotShell`,
`focusDecoratesCoreNotShell`, `darkLockUsesWhiteGlyphAndDarkShell`. Это больше,
чем девять фактов, названных в хендоффе (хендофф перечислял по смыслу, не по
имени предиката) — расхождение не в пользу автора, а в сторону более сильного
доказательства: тест ловит регрессию с запасом. AC9 подтверждён независимо, не
на слово.

### Визуальная проверка «глазами» (обязательна по §11 ТЗ)

Просмотрен `artifacts/device-icon-reference/device-icons-reference-runtime.png`
целиком (28 строк: Default/Hover/Active/Lock/Unlock/Selected/Focus/Alert/
Virtual/Unavailable/Text/Double Right для Light и Dark, плюс Default на
32/56/96 px). Круглая геометрия, размер MDI-глифа, value-pill радиус, theme
stroke и цвета состояний в runtime визуально совпадают с колонкой Reference
SVG построчно, включая Lock/Unlock (проверены отдельным 4×-кропом — форма и
пропорция глифа замка совпадают с эталоном в обеих темах).

Также открыт и прочитан `artifacts/golden/actual/device-icon-state-table-{light,dark}.png`
целиком. Комбинация `alarm + sel` с `focusDevice` на одном маркере
(«golden-climate») отрендерена так: core и shell — красные (alert выигрывает
покраску, как требует §7.3), а кольцо декорации — синее (focus), не янтарное
(selected). Это прямое следствие принятого в #179 приоритета
`Alert > Focus > Selected > Hover > semantic > Default`: кольцо — теперь
отдельный CSS-слой (`--device-ring-color`/`--device-ring-width` на
`.device-core`), и правило `:focus-visible` в каскаде идёт позже `.sel`, то
есть более приоритетное состояние перекрывает кольцо менее приоritetного —
ровно то поведение, которого требует таблица приоритета. До этого коммита
кольцо было частью `box-shadow` на `.device-shell` и `.dev.alarm` (более
специфичное правило ниже по каскаду) стирало декорацию selection/focus
полностью — то есть alert раньше «съедал» кольцо целиком, а не выигрывал
только цвет core/shell. Новое поведение (alert красит core/shell, но не
гасит более высокоприоритетный focus-ring) точнее реализует буквальное
требование §7.1 «Selected/Focus ring — отдельный круглый слой; не заменяет
внешний shell» и не описано ни одним найденным мной артефактом как
регрессия. Технически это расширение видимой информации (можно увидеть, что
элемент одновременно и alert, и focused), не потеря её.

Проверены также обновлённые документационные скриншоты
(`docs/images/01-view-desktop.png` и другие) — маркеры на них уже круглые, а
не скруглённо-квадратные; `sourceFingerprint` в `screenshots.json` пересчитан
и совпадает с проверкой `check-docs.mjs`.

### Коммиты и трейлеры

Оба коммита несут `Issue: #211`. `4e82976` (`User-Visible: yes`) в одном
коммите правит оба changelog (`docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`) —
условие AGENTS.md выполнено. `270cf63` (`User-Visible: no`) правит только
`scripts/mutation-gate.mjs` — чистый class B, трейлер соответствует.

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

- **AC1 (геометрия).** Круглый core (`border-radius: 50%` вместо `28%`),
  shell/core `1.26875` сохранён через `box-sizing: border-box` и
  компенсирующий `--device-shell-pad` независимо от переменной ширины
  stroke — геометрия не плывёт между состояниями с разной толщиной обводки.
  Value-pill радиус — `height/2` (`0.39375`), а не `0.18`. `geometryMatchesAt32_56_96`
  подтверждает допуск на 32/56/96 px, включая painted bbox настоящего
  `mdi:lightbulb-spot` (реальный SVG-путь, не bounding box `ha-icon`).
- **AC2 (theme parity).** Light/Dark default core/glyph/stroke/shadow и
  запрет `backdrop-filter` подтверждены смоком и визуальной таблицей;
  `darkDefaultShellUsesPackageStroke` сверяет буквальный `rgba(37,37,37,0.75)`.
- **AC3 (state parity).** Default/Hover/Active/Lock/Unlock/Alert сверены
  байт-в-байт с прямым SVG (цвет **и** ширина stroke) в обеих темах;
  Selected/Focus/Virtual/Unavailable подтверждены отдельными вычисляемыми
  фактами и визуально. Тёмный Unlock корректно использует утверждённый
  владельцем янтарный override, а не архивный зелёный.
- **AC4 (combinations).** Golden-сценарий `device-icon-state-table-*`
  содержит маркер с `alarm+sel+focus` одновременно; результат просмотрен и
  соответствует принятому в #179 приоритету слоёв (см. выше).
- **AC5 (layouts).** Text/Double/third section/LQI не сломаны
  (`doubleUsesOneShell`, `textIsComplete`, `lqiBandsProjected`).
- **AC6 (surface parity).** `smoke_device_preview_parity` и `smoke_static_icon`
  зелёные — план, preview и static card используют общий `renderDeviceFace()`
  без расхождений.
- **AC7 (interaction regression).** 44×44 hit area, unavailable
  click/tap без hover, keyboard/tab order, secure-путь — все факты зелёные,
  `smoke_disabled_device` не задет.
- **AC8 (data/semantics).** Диапазон реализации не касается
  `device-visual.ts`/`device-presentation.ts`/`device-pulse.ts`, i18n или
  `custom_components/**`; unit-suite (939) зелёный без исключений.
- **AC9 (failing-before-fix).** Независимо подтверждено (13 фактов красные на
  старом CSS, все зелёные после фикса) — см. раздел «Как проверялось».
- **AC10 (release artifacts).** Оба changelog, `docs/TESTING.md`, обновлённые
  скриншоты — всё в user-visible коммите; golden не принят вручную (верно —
  ждёт полного reviewed Linux CI artefact).

## Находки

Нет находок уровня High или Medium. Два Low, оба не блокируют и не требуют
правки в этом цикле:

- **L1.** `virtualUsesThemeDefaultWithDashedShell` в смоке проверяет только
  состояние `virtual` в покое; «virtual hover идентичен ordinary hover»
  (§7.3 ТЗ) не покрыт отдельным вычисляемым фактом — только логическим
  чтением каскада (правило `.dev:not(.unavail):hover` не имеет исключения
  для `.virtual` и не переопределяется ничем более специфичным). Риск
  минимален и ограничен одним недостающим предикатом в уже большом смоке.
  Снимаю без правки: поведение не изменилось этим диапазоном (правила
  `.virtual`/`.dashed` не тронуты диффом), это пробел покрытия, а не дефект
  поведения.
- **L2.** Комбинации `Alert+Focus+Selected` не сверены с одноимённым SVG
  архива буквально (§7.3 формально требует «сверяются с одноимёнными Light
  SVG»), потому что такого экспортированного файла в переданном архиве нет —
  собственный AC4 ТЗ признаёт это, требуя доказательство именно
  «combination golden», которое выполнено и просмотрено. Снимаю без правки:
  доказательство соответствует явно заявленному в ТЗ уровню, более сильного
  источника истины не существует.

Отдельно фиксирую техническую неточность в хендоффе, не влияющую на вердикт:
он сообщает «938 pass, 1 skipped», а независимый прогон на этом же дереве
даёт «939 pass, 0 skipped» (совпадает с `npm run inventory`). Не поднимаю как
находку — расхождение не воспроизводится и не меняет результат ни одного
гейта.

## Чего не проверял и почему

- **Полный набор из 152 browser smokes** — не запускал; диапазон реализации
  ограничен общим рендерером маркера и его собственным smoke/preview/static
  покрытием, названным в AC и хендоффе. Остальные 148 не имеют отношения к
  геометрии/theme/state маркера.
- **`npm run golden:verify` по полному набору сценариев** — не запускал;
  прогнал `capture` только по двум сценариям, прямо относящимся к задаче
  (`device-icon-state-table-{light,dark}`), и открыл получившиеся PNG.
  Полный golden-прогон и оценка остальных ~90 сценариев на предмет побочных
  визуальных отличий из-за глобального изменения CSS маркера — предрелizный
  гейт (PROCESS.md §8), а не гейт код-ревью; риск того, что какой-то другой
  golden-сценарий с устройствами теперь тоже "different", реален, но это
  ожидаемое и штатно обрабатываемое следствие правки, а не повод возвращать
  задачу на этом этапе.
- **`python -m pytest tests_backend -q`** — не запускал; диапазон не
  затрагивает `custom_components/**/*.py`.
- **Performance-профили** — не запускал; правка не добавляет DOM-узлов,
  layout read или подписок (`device-face.ts` не тронут), а AC не называет
  performance-смок явно.
- **Полный Linux CI-прогон** — не запускал локально; это гейт CI при выходе
  из код-ревью, не задача рецензента.

## Вердикт

Все десять AC выполнены и подтверждены либо автотестом, который доказанно
умеет падать, либо непосредственным визуальным просмотром, как того требует
§11 ТЗ. Регрессий в интеракции, данных, конфиге и семантике не найдено.

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