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

# CODE-REVIEW-217-r1

- **Issue:** #217 — внешняя рамка Text-маркера должна быть капсулой
- **ТЗ:** `docs/specs/217-text-shell-outline.md` (SPEC-REVIEW-217-r1, зелёный)
- **Ветка/SHA:** `issue/217-text-shell-outline` @ `39456dc` (implementation),
  предыдущий коммит `fe33dea` (spec), `c547586` (spec-review doc)
- **Диапазон:** `origin/dev...HEAD`
- **Трек:** обычный (не `small`)
- **Цикл:** r1/4
- **Вердикт:** зелёный · High: 0 · Medium: 0

## Скоуп ревью

Первый цикл — разбор полный. `git log --oneline origin/dev..HEAD` даёт три
коммита (spec, spec-review doc, implementation); `git diff
origin/dev...HEAD` — 17 файлов. Проверены: сам фикс в `src/styles.ts`,
source-regression тест, изменения в `demo/smoke_device_icon_design.mjs`,
golden-матрица (`demo/golden/matrix.mjs`, `harness.mjs`,
`test/golden-matrix.test.mjs`), reference-капчер (`capture_device_icon_reference.mjs`),
оба changelog, `docs/TESTING.md`, `docs/images/screenshots.json`, три копии
бандла, трейлеры коммитов. Соответствие AC1–AC9 из §13 ТЗ проверено по
каждому пункту.

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

Прочитаны целиком: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` §2.7/§7.2/§8/§12,
`docs/specs/217-text-shell-outline.md`, тело issue #217 и оба комментария,
`docs/reviews/SPEC-REVIEW-217-r1.md` (контекст спек-ревью), `src/styles.ts`
(строки 2013–2090 — весь блок `.device-shell`/`.device-shell-frame`),
`src/device-face.ts` (весь `renderDeviceFace`, классы `text-shell`/`with-values`).

Прогнаны гейты:

| Команда | Результат |
| --- | --- |
| `npx tsc --noEmit` | 0 ошибок |
| `npm test` | 957 pass / 0 fail |
| `npm run build` + `md5sum dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js demo/srv/assets/houseplan-card.js` | одинаковый хеш `6b01daba677f602728d128dc80e25cfc` во всех трёх копиях |
| `node scripts/check-docs.mjs --external` | "Documentation checks passed (7 files, 10 external links)" |
| `node demo/smoke_device_icon_design.mjs` (изменён в этом диффе, покрывает AC1–AC5) | все флаги `true`, `OK` |
| `node demo/smoke_device_preview_parity.mjs` (AC7, названа в §14.2 ТЗ) | все флаги `true`, `OK` |
| `node demo/smoke_static_icon.mjs` (AC7, названа в §14.2 ТЗ) | все флаги `true`, `OK` |
| `npm run golden:verify` (диагностически, диф — CSS-геометрия, видимый результат меняется) | см. ниже |

Дисциплина «тест должен уметь падать» — применена к обоим тестам, которые
покрывают сам фикс:

- временно вернул старый селектор `.device-shell:not(.with-values)
  .device-shell-frame` (без `:not(.text-shell)`) в `src/styles.ts`, пересобрал,
  скопировал бандл в `demo/srv/assets/`, прогнал `smoke_device_icon_design.mjs` —
  красным стали ровно `textShellIsStadiumAtRepresentativeSizes: false` и
  `textShellMutationGuardRejects50Percent: false`, остальные 39 флагов не
  затронуты;
- на том же мутанте прогнал `node --test
  test/device-marker-polish-contract.test.mjs` — 6 pass / 1 fail (упал именно
  новый тест `issue 217 keeps the Text shell stadium...`);
- восстановил `src/styles.ts` из git, пересобрал, скопировал все три копии
  бандла — хеши снова совпали с закоммиченными (`6b01daba677f602728d128dc80e25cfc`),
  `git status` чист.

`npm run golden:verify` (диагностический Linux-раннер, не гейт код-ревью):
90 сценариев, `passed` — 84, `different` — 2, `missing-baseline` — 2, `error` — 0.

- `missing-baseline`: `device-text-shell-long-{light,dark}` — новые сценарии
  из этого диффа, у них по определению ещё нет принятого baseline. Просмотрел
  `artifacts/golden/actual/device-text-shell-long-{light,dark}.png`: маркер
  `498 ppm` показывает корректную stadium-форму (полукруглые торцы, прямой
  средний участок сверху/снизу) в обеих темах — визуально решает ровно тот
  сценарий, который описан в §2 ТЗ.
- `different`: `device-icon-state-table-{light,dark}` — существующий,
  ранее принятый baseline. Просмотрел `artifacts/golden/diff/*.png`:
  расхождение строго локализовано на одном маркере — `golden-left-temperature`
  (Text-only, `display: value`, длинное значение "Complete long localized
  state..."), его внешняя рамка стала капсулой вместо эллипса; стены, комнаты,
  остальные маркеры (Double/badge, Icon-only, presence, climate, LQI) пиксель
  в пиксель не изменились. Это ожидаемый побочный эффект того же самого фикса
  на уже существующем сценарии — доказательство, что фикс работает
  единообразно, а не находка. Принятие обновлённого baseline — пре-релизный
  шаг (`npm run golden:accept -- --reviewed` на Linux CI-артефакте, AGENTS.md
  «Gates»), не действие код-ревью; тот же паттерн зафиксирован в
  `docs/reviews/CODE-REVIEW-213-r1.md`.

Не прогонялись и почему:

- полный набор `demo/smoke_*.mjs` (127 файлов) — диф не задевает стены, tray,
  sun/glow, openings, isometric и т.п.; `golden:verify` выше подтвердил, что
  все сценарии этих поверхностей `passed` без изменений, значит расширять
  смок-набор не нужно;
- `python -m pytest tests_backend -q` — диф не касается `custom_components/**/*.py`;
- перф-профили — AC8 не требует их явно, изменение CSS-only (одно правило,
  без нового JS/ResizeObserver/слоя), проверено чтением `src/styles.ts` и
  диффа `demo/smoke_device_icon_design.mjs` целиком — новых наблюдателей,
  таймеров или compositor-слоёв не добавлено;
- `npm run golden:accept` — не роль код-ревью (см. выше).

## Проверка AC (§13 ТЗ)

1. **AC1 (stadium shell).** Подтверждено визуально по обоим новым golden-кадрам
   и смоком `textShellIsStadiumAtRepresentativeSizes`. ✅
2. **AC2 (защита от `50%`).** Source-тест `test/device-marker-polish-contract.test.mjs`
   и browser-мутант в смоке оба красны на documented mutant — проверено ручным
   реверсом селектора (см. выше). ✅
3. **AC3 (матрица размеров).** `textShellSizeMatrix` в смоке проходит все пять
   размеров (24/32/56/96/112) с допуском `<=0.5px` для радиуса/инсета. ✅
4. **AC4 (геометрическая совместимость).** Изменение — только `border-radius`
   одного CSS-правила; `width`/`height`/`inset` этим свойством не затрагиваются
   ни в спецификации CSS, ни фактически (golden-диф показывает identical
   footprint, меняется только форма угла). Проверено чтением + golden-диф. ✅
5. **AC5 (соседние варианты).** `iconShellIsCircle` и `doubleShellKeepsCapsule`
   в смоке — `true`; golden-диф подтверждает, что Icon-only/Double/badge
   маркеры в `device-icon-state-table-*` не изменились ни на пиксель. ✅
6. **AC6 (interaction parity).** `valueCapsuleOwnsHoverAndActionAtEveryPosition`,
   `hitAreaAtLeast44` — `true`; правка не касается `pointer-events`, hover- или
   action-кода — только `border-radius` в CSS, подтверждено чтением диффа. ✅
7. **AC7 (surface/theme parity).** `smoke_device_preview_parity.mjs`
   (`planPreviewEqual`, `planStaticEqual` — `true`) и `smoke_static_icon.mjs`
   (`planStaticCardParity` — `true`) плюс golden в обеих темах. ✅
8. **AC8 (data/i18n/security/perf).** Диф не содержит правок схемы, storage,
   i18n-ключей, `resolveToggleIntent`/`isControllable`/action-путей,
   `ResizeObserver`, media listener или анимации — проверено чтением всего
   диффа (`git diff origin/dev...HEAD`). ✅ — «проверено чтением, не исполнением».
9. **AC9 (release artifacts).** `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`
   правлены в том же коммите `39456dc` (`User-Visible: yes`), `docs/TESTING.md`
   получил новый раздел «Text marker shell shape (#217)»,
   `docs/images/screenshots.json` fingerprint обновлён и подтверждён
   `check-docs.mjs`, golden/smoke fixtures обновлены. ✅

## Трейлеры и класс изменений

- `fe33dea` (спек, класс C) — `Issue: #217` / `User-Visible: no` — корректно.
- `c547586` (документ спек-ревью, класс C) — те же трейлеры — корректно.
- `39456dc` (реализация) — `Issue: #217` / `User-Visible: yes`; правки
  `src/**` (класс A, только CSS), `test/**`/`demo/**` (класс B),
  `dist/**`/`custom_components/houseplan/frontend/**`/`demo/srv/assets/**`
  (класс D, три копии синхронны), `docs/**` (класс C, оба changelog в том же
  коммите — соответствует требованию AGENTS.md). Всё в одном коммите,
  ветка не содержит признаков ребейза на ушедший вперёд `dev` (три коммита
  линейно продолжают `origin/dev`).

## Находки

Нет находок High или Medium. Low не обнаружено (терминология changelog
"капсульную форму" соответствует `docs/USER-GUIDE.ru.md`; спек-ревью уже снял
единственный Low прошлого этапа — слово "stadium" в тексте ТЗ, не в
user-visible строке).

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

- Сам фикс — `src/styles.ts:2061`: сужение селектора
  `.device-shell:not(.with-values) .device-shell-frame` до
  `.device-shell:not(.with-values):not(.text-shell) .device-shell-frame`.
  Единственная строка продуктового кода, ровно то, что предсказано §11 ТЗ
  ("сузить circular override так, чтобы он не захватывал Text").
- Комбинация классов `text-shell` + `with-values` (Text с badge) не затронута:
  такой маркер и раньше не попадал под circular override (уже был исключён
  `:not(.with-values)`), новое условие `:not(.text-shell)` для него избыточно,
  но не вредит — подтверждено чтением `src/device-face.ts:96-101`.
- Regression-тест и browser-мутант доказанно умеют падать (ручной реверс,
  см. «Как проверялось»).
- Побочный эффект на уже принятом golden (`device-icon-state-table-*`)
  локализован ровно на затронутом маркере, остальная сцена не сдвинулась —
  подтверждает, что фикс не расширяет blast radius за пределы Text-shell.
- Три копии бандла синхронны после чистой пересборки; фингерпринт скриншотов
  обновлён и проходит `check-docs.mjs`.

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

- Полный `demo/smoke_*.mjs` (127 файлов) — не запускал; необходимость
  отсутствует, см. «Как проверялось». Косвенно покрыто через `golden:verify`
  (все нетронутые поверхности — `passed`).
- `python -m pytest tests_backend` — не запускал, диф не касается backend.
- Performance-профили (`performance_smoke` и аналоги) — не запускал; AC8 не
  требует их явно, изменение CSS-only проверено чтением.
- Принятие/пересчёт golden baseline (`npm run golden:accept -- --reviewed`) —
  сознательно не выполнял: это пре-релизный шаг на полном Linux CI-артефакте,
  не входит в роль код-ревью (прецедент — CODE-REVIEW-213-r1). Два
  `missing-baseline` и два `different` сценария должны быть приняты перед
  публикацией беты — фиксирую это как ожидаемый следующий шаг, не как
  блокирующую находку.
- Ручное браузерное тестирование за пределами `smoke_*.mjs`/`golden:verify` —
  не проводилось; по процессу ручного тестирования в цикле код-ревью нет.