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

# CODE-REVIEW-179-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/179
- **ТЗ:** `docs/specs/179-device-icons-redesign.md` (зелёное SPEC-REVIEW r2)
- **Диапазон:** `origin/dev..HEAD`, коммиты `517a710`…`7af6d74`, основной —
  `48bcdaf` («feat: redesign device marker faces»)
- **Ревьюер:** Claude (свежая сессия, без контекста реализации)
- **Вердикт:** зелёный · цикл r1/4 · High: 0 · Medium: 0

## Скоуп

Единый shell/core-рендерер маркера устройства (пакет дизайнера #179) на полном
плане, editor preview и static space card: geometry/theme, приоритет
состояний, Text/Double без ellipsis, категориальный marker LQI, motion
timings/цвета, keyboard/hit-area/aria, backward-совместимый config. Диапазон
ограничен ровно тем, что перечислено в хендоффе; посторонних правок не найдено
(`git diff --stat origin/dev...HEAD` — только файлы из плана ТЗ §13 плюс
docs/i18n/tests).

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

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | green |
| Unit | `npm test` | 930 tests, 930 pass, 0 fail, 0 skip |
| Build + bundle parity | `npm run build && cmp` (все 3 копии) | green, побайтово идентичны |
| Mutation guards (новые, не полный набор) | `node scripts/mutation-gate.mjs --id=device-unavailable-hover-restored` / `--id=device-marker-lqi-low-boundary-shifted` / `--id=device-long-value-ellipsis-restored` / `--id=device-keyboard-bypasses-click-path` | все 4: чистый прогон зелёный, мутант красный — «тест умеет падать» подтверждено для каждого |
| Целевые browser smokes (названные в ТЗ §16.2) | `node demo/smoke_device_icon_design.mjs`, `smoke_device_preview_parity.mjs`, `smoke_static_icon.mjs`, `smoke_state_value.mjs`, `smoke_disabled_device.mjs` | все green |
| Secure-action smokes (lock invariant, `docs/SCOPE.md` CR-1) | `smoke_lock_action.mjs`, `smoke_lock_invariant.mjs`, `smoke_toggle_confirmation.mjs` | все green |
| Смежный smoke, задетый styles.ts (continuous-пульсация cover) | `smoke_cover_tap.mjs` | green |
| Golden (диагностика, не acceptance) | `node demo/golden/run.mjs --mode=capture --scenario=device-icon-state-table-light` / `-dark` | `missing-baseline` (ожидаемо, как и заявил автор), рендер без runtime-ошибок, изображения сверены визуально — см. «Проверено и корректно» |
| `--check` реестра мутаций | `node scripts/mutation-gate.mjs --check` | все патчи, включая 4 новых, ложатся ровно один раз |

**Гейты НЕ прогонялись, и почему:**

- Полный `node scripts/mutation-gate.mjs` (без `--id`) и полный browser-smoke
  набор (127 файлов) — задача касается общего рендерера маркера, но не всех
  127 поверхностей; PROCESS.md §8 прямо резервирует полный прогон за
  предрелизным гейтом. Прогнаны все смоки, названные в ТЗ §16.2, плюс
  secure-action и один смежный (cover), которые diff трогает напрямую.
- `npm run golden:verify` (полный набор, 100+ сценариев) — golden-политика
  (`demo/golden/policy.mjs`) сама отказывается гонять `verify` частично;
  полный прогон — Linux CI перед бетой (canon, `AGENTS.md`). Вместо этого
  выполнена диагностика `golden/run.mjs --mode=capture` только по двум новым
  сценариям — видимый результат сверен глазами (см. ниже), это не замена
  gate, а проверка «не сломано визуально».
- `python -m pytest tests_backend -q` — Python-код (`custom_components/**`)
  не тронут (только doc-комментарий `validation.py` был прочитан для сверки
  диапазона `ripple_size`, не изменён).
- Performance-профили (`performance_smoke.mjs`) — AC13 не называет числовой
  бюджет для прогона именно на этом ревью; код прочитан на отсутствие
  per-marker `ResizeObserver`/`matchMedia`/`backdrop-filter` (ниже) вместо
  измерения. Профиль остаётся предрелизным гейтом (ТЗ §16.4).

## Находки

Нет. High: 0, Medium: 0. Ниже — два Low, оба решены на месте (не требуют
правки, оставлены с записью).

- **Low-1 (снят).** `src/styles.ts`, блок `.dev` (~строка 1875): `--device-core-bg`
  и `--device-core-fg` объявлены дважды подряд в одном правиле — сначала через
  `var(--card-background-color…)`/`var(--primary-text-color…)`, затем тем же
  свойством через `light-dark(#fff, #252525)`. Второе объявление всегда
  выигрывает (последнее правило для custom property в одном селекторе), первое
  — мёртвый код. Функционально не влияет: `.dev.theme-light`/`.dev.theme-dark`
  всё равно переопределяют обе переменные явно, когда `hass.themes.darkMode`
  известен (см. `deviceThemeClass`, `smoke_device_icon_design.mjs` —
  `lightThemeCoreIsWhite`/`darkThemeCoreIs252525` подтверждают оба пути).
  Косметика, не блокирует.
- **Low-2 (снят).** Цветовая линия `tone-humidity` (`border-color: #4fc3f7`),
  различавшая temperature/humidity legacy-сателлиты бордюром, не имеет
  преемника в новом shell — все секции (value badge, LQI-как-badge, legacy
  temp/hum) теперь визуально одинаковы (белая/тёмная пилюля без цветной рамки).
  Это не регрессия относительно ТЗ: §8.2 прямо требует единый shell без
  отдельных «спутников», а пакет дизайнера не определяет per-tone цвета —
  унификация здесь является сутью задачи, а не побочным эффектом. Отмечаю для
  протокола, правки не требую.

## Проверено и корректно (по каждому AC)

- **AC1 (shell/theme).** `src/styles.ts` — `--device-shell-size: calc(var(--dev-size) * 1.26875)`
  = `101.5/80`, `--device-shell-pad` даёт `0.788` core/shell с учётом
  1px stroke — совпадает с ТЗ §7.1. Light: `stroke #BCBCBC`,
  `box-shadow: 0 1px 2px rgb(37 40 45/12%), 0 4px 8px -1.07px rgb(37 40 45/18%)`,
  `backdrop-filter: none` явным правилом. Dark: `--device-core-bg:#252525`
  через класс `.dev.theme-dark`. Подтверждено смоком
  (`sharedShellGeometry`, `packageShadowColor`, `noBackdropBlur`,
  `lightThemeCoreIsWhite`, `darkThemeCoreIs252525` — все `true`).
  **unit + smoke.**
- **AC2 (states/priority).** CSS-каскад разложен так, что правила
  `.dev.alarm…` идут физически последними среди правил с равной специфичностью
  (`.dev.sel`, `.dev:focus-visible`, `.dev.alarm`), что при равенстве
  специфичности (по 3 класс-эквивалента на каждый селектор) даёт порядок
  Alert > Focus > Selected по исходному коду — соответствует нормативному
  приоритету §7.3. Golden-диагностика `device-icon-state-table-{light,dark}`
  визуально подтверждает: alarm-маркер (одновременно `sel`+`alarm`+focus)
  рисуется красным поверх всех остальных decorations. **unit (presentation
  matrix, не показан здесь, но покрыт `device-presentation.test.mjs`) +
  golden-диагностика.**
- **AC3 (unavailable).** `.dev:not(.unavail):hover` исключает `.unavail` из
  hover-перекраски и shell-border; клик/keyboard остаются разрешены (`_clickDevice`
  не проверяет unavailable). Мутант `device-unavailable-hover-restored`
  красный при восстановлении общего hover — **проверил лично**, гейт ловит
  регрессию. **unit + smoke, мутация подтверждена исполнением.**
- **AC4 (secure locks).** `lockState` вычисляется только для `lock.*`
  entity (не путается с generic cover/contact `open`), `lock-locked` даёт
  чёрный glyph на theme-фоне, `lock-unlocked` — amber `#F0A00C`. Keyboard путь
  (`_keyDevice` → `_clickDevice`) — тот же самый метод, что pointer click, без
  отдельной ветки для секьюрных действий. `smoke_lock_action.mjs` и
  `smoke_lock_invariant.mjs` (полный набор secure-инвариантов из
  `docs/SCOPE.md` CR-1) — оба green, обход подтверждения не найден.
  **unit + secure-action smoke, лично прогнано.**
- **AC5 (virtual/static).** `.dev.virtual .device-shell { border-style: dashed }`
  — только shell, не core (не путается с реальным unavailable). `static_icon`
  получает theme-aware core/shell, но не реагирует на live state/pulse/value
  (`resolveDevicePresentation` подставляет нейтральный `visual` для
  `staticIcon`, не тронуто в этом diff). `smoke_static_icon.mjs` green.
  **unit + smoke.**
- **AC6 (Text/Double).** `deviceTextScale()` — детерминированная функция без
  DOM-измерения (юнит подтверждает `0.45` для короткого, `0.25`-floor для
  длинного); `overflow: visible`, `text-overflow` не установлен. Shell
  расширяется по content (`width: max-content` на core/badge). Единый
  `device-sections` контейнер для badge + legacy secondary (третья секция).
  Мутант `device-long-value-ellipsis-restored` красный при восстановлении
  `ellipsis` — **проверил лично**. `textIsComplete`/`doubleUsesOneShell` в
  smoke — true. **unit + smoke + мутация, всё исполнено.**
- **AC7 (LQI).** `markerLqiBand`/`markerLqiColor` — границы `<=40`/`<180`/`>=180`
  дают ровно `low/mid/high` на `{0,40,41,179,180}` (юнит-тест по всем пяти
  граничным значениям). `logic.ts::lqiColor()` (комнатный градиент) не
  импортируется больше в `device-presentation.ts` для маркера, но
  используется по-прежнему для заливки комнаты — не тронут. Мутант
  `device-marker-lqi-low-boundary-shifted` (сдвиг `<=40` → `<40`) красный —
  **проверил лично**. **unit + мутация, исполнено.**
- **AC8 (motion).** Timings/easing сверены с ТЗ §10: continuous
  `3.6s cubic-bezier(.45,.05,.55,.95)`, short `1.1s×3, delay 0/1.1/2.2,
  cubic-bezier(.22,.61,.36,1)`, alarm `2.4s, 2 волны с задержкой 1.2s,
  тот же easing`, scale `1→1.5`. `semanticPulseColor()` даёт
  green/presence, amber/running|working|open, blue/иначе — юнит-тест
  `device-pulse.test.mjs` проверяет все три ветки плюс explicit-override
  приоритет. **unit (исполнено) + smoke (`presenceContinuousGreen` true).**
- **AC9 (reduced motion).** `reducedMotionIndicator: 'dot'` заменяет кольца;
  `.activity-dot` берёт цвет из того же `--ripple-color`, что и кольца
  (раньше был явный `null` под reduced motion — терялся цвет точки, теперь
  исправлено). Одна host-level `matchMedia` подписка (`_motionMedia`,
  `houseplan-card.ts`), в device-слое новых подписок не добавлено (grep
  подтверждает). **unit + проверено чтением (нет второй подписки).**
- **AC10 (keyboard/a11y).** `role="button"`/`tabindex="0"` только когда
  `mode === 'view' || 'devices'`; `planNotInTabOrder` в smoke подтверждает
  отсутствие атрибутов в Plan-режиме. Preview (`hp-device-preview.ts`) и
  static card (`space-render.ts`) получили `role="img"` без tabindex —
  не входят в tab order (grep подтверждает отсутствие `tabindex` в обоих
  файлах). Enter/Space вызывают тот же `_clickDevice`, что click (мутант
  `device-keyboard-bypasses-click-path` красный при подмене пути —
  **проверил лично**). `aria-label` включает `state_a11y_*`/`lqi_a11y_*` —
  `unavailableAriaIsReadable` в smoke подтверждает наличие "unavailable" и
  "LQI/signal" в одной строке. Hit-area 44×44 — через `.dev::before` c
  `max(44px, shell-size)`, `hitAreaAtLeast44` true. Возврат фокуса после
  диалога — существующий, не тронутый этим diff механизм `hp-dialog.ts`
  (`connectedCallback` захватывает opener, `disconnectedCallback` его
  восстанавливает); маркер теперь фокусируем, поэтому механизм
  автоматически распространяется без нового кода — **проверено чтением, не
  отдельным тестом** (в ТЗ явно «по существующему dialog contract», не
  новая фича). **unit + smoke + мутация (частично исполнено, частично
  чтением).**
- **AC11 (parity).** Один `renderDeviceFace()` вызывается из всех трёх
  поверхностей (`houseplan-card.ts`, `hp-device-preview.ts`,
  `space-render.ts`) — новых копий DOM/state-mapping не найдено (grep по
  `renderDeviceFace` — 3 вызова, все из общего модуля).
  `smoke_device_preview_parity.mjs` и `smoke_static_icon.mjs` green.
  **existing smoke.**
- **AC12 (совместимость).** `ripple_size` дефолт `3→1.5` заменён
  консистентно во всех 4 местах записи/чтения конфига (grep подтверждает
  отсутствие старого литерала `3`); "не материализуется" — та же
  тернарная схема `!== 1.5 ? value : null`, что и раньше была `!== 3`,
  проверено чтением каждого из 4 мест (нет посвящённого юнит-теста на этот
  конкретный литерал — **проверено чтением, не исполнением**, отмечаю
  честно). Backend `vol.Range(min=1, max=20)` (`validation.py`) не менялся;
  UI-слайдер расширен `2→1`, что *внутри* уже разрешённого backend-диапазона,
  не нарушение. i18n en/ru parity — новые ключи присутствуют в обоих файлах
  построчно. **unit (частично) + чтение кода + backend-схема прочитана.**
- **AC13 (производительность).** `grep ResizeObserver` — только
  существующие host/viewport подписки, ни одной новой per-marker; `grep
  backdrop-filter` — единственное вхождение `none` на `.device-shell`
  (запрещающее правило, соответствует Dark No-Blur решению M4 из
  SPEC-REVIEW r1). Motion — только `transform`/`opacity`
  (не задевает layout). SVG-примеры пакета не импортированы в `src/`/`dist`
  (grep по характерным именам файлов архива — пусто). **проверено чтением,
  не исполнением; performance_smoke — предрелизный гейт, не гонялся здесь.**
- **AC14 (release artifacts).** `docs/CHANGELOG.md`/`.ru.md`,
  `docs/USER-GUIDE.md`/`.ru.md`, `docs/ARCHITECTURE.md`, `docs/TESTING.md`
  обновлены в том же коммите `48bcdaf` (`User-Visible: yes`), терминология
  USER-GUIDE.ru.md согласована с уже принятой в файле («жёлтая подложка»
  и т.п., не изобретена заново). i18n en/ru добавлены parity. Golden
  matrix version `31→32`, новый юнит `golden-matrix.test.mjs` проверяет
  структуру двух новых сценариев. Скриншоты (`docs/images/*.png`,
  `screenshots.json`) обновлены вместе с кодом.

## Трейлеры и процесс

- Каждый из 7 коммитов диапазона несёт `Issue: #179` и ровно один
  `User-Visible: yes|no`; `yes` — только на `48bcdaf`, где лежат оба
  changelog. Остальные 6 — `no` (доки/тесты/ТЗ), корректно.
  `node scripts/process-gate.mjs --issues` — green по заявлению автора;
  офлайн-часть (`--check`, структура трейлеров) визуально сверена по
  `git log`, расхождений не найдено.
- Ветка `issue/179-device-icons-redesign` соответствует номеру issue.
  Диапазон коммитов не содержит посторонних правок вне плана ТЗ §13.

## Итог

Реализация соответствует ТЗ по всем 14 AC, включая явно принятые владельцем
решения (§4) и технические предположения (§20). Секьюрный инвариант замков
(`docs/SCOPE.md` CR-1) не затронут — подтверждено прогоном
`smoke_lock_invariant.mjs`/`smoke_lock_action.mjs`. Все 4 новых mutation-guard
лично прогнаны и подтверждённо ловят свою регрессию — это самое сильное
доступное в этом процессе доказательство «тест умеет падать» для AC3/AC6/AC7/AC10.
Golden-baseline осознанно не принят (корректно оставлено предрелизному Linux
CI гейту); диагностический прогон двух новых сценариев не выявил визуальных
дефектов. Два Low-замечания зафиксированы и сняты без правки кода (обоснование
выше). High: 0, Medium: 0 — задача уходит в очередь на пре-релиз.