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

# CODE-REVIEW-192-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/192
- **ТЗ:** лёгкий трек (`small`) — живёт в теле issue #192 (ревью —
  `docs/reviews/SPEC-REVIEW-192-r1.md`, вердикт зелёный, Low-1 снят с записью,
  Medium: 0)
- **Диапазон:** `git log --oneline origin/dev..HEAD` / `git diff
  origin/dev...HEAD` — один коммит `508d38c` «Show spectrum on hue slider»
  (`Issue: #192`, `User-Visible: yes`)
- **Роль:** ревьюер кода (не автор), этап `S7-code-review`
- **Цикл:** r1/2 (лёгкий трек)

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

Проверялось соответствие реализации:

- контракту из тела issue #192 (§«Контракт поведения и UX», AC1–AC5, план
  автотестов, риски);
- `docs/SCOPE.md` — задача не расширяет продукт за пределы editor usability
  polish (J4/J6), View/kiosk не затронуты;
- `AGENTS.md`/`PROCESS.md` — классы файлов, трейлеры, оба changelog в одном
  `User-Visible: yes` коммите, изоляция (только `.hue-range`, не общий
  `input[type='range']`);
- фактическому поведению `src/hp-color-opacity.ts` в браузере (Chromium,
  Playwright), а не только по чтению CSS;
- реально выполненным гейтам (см. ниже), включая полный `npm run
  golden:verify` — diff меняет видимый рендер открытого picker, что подпадает
  под критерий «рендер/геометрия/стили» из инструкции к этому ревью.

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

1. Прочитан весь diff (`git diff origin/dev...HEAD --stat` и файлы по
   отдельности): `src/hp-color-opacity.ts` (+23/-0 в стилях), `test/color-
   picker.test.mjs` (+15 строк, новый тест), `demo/smoke_color_picker.mjs`
   (+5 строк), `demo/golden/matrix.mjs` (+3, новая сцена `decor-color-
   popover-desktop-en`), `test/golden-matrix.test.mjs` (+10, contract-тест
   на список сцен), `docs/{CHANGELOG.md,CHANGELOG.ru.md,USER-GUIDE.md,
   USER-GUIDE.ru.md,TESTING.md}`, сгенерированные `dist/houseplan-card.js` /
   `custom_components/houseplan/frontend/houseplan-card.js` /
   `demo/srv/assets/houseplan-card.js`.
2. Прочитано тело issue #192 целиком и все четыре комментария (аналитика
   владельца, зелёное SPEC-ревью, хендофф реализации) — сверено, что
   реализация не расширяет и не сужает скоуп относительно принятого ТЗ
   (только `.hue-range`, S/V/opacity не тронуты).
3. Прочитан `src/hp-color-opacity.ts:225-312` построчно: `input[type='range']`
   (общий, высота 40px, `margin: -5px 0`) не изменён; `.hue-range` добавляет
   `--hp-picker-hue-track` (linear-gradient, 7 стопов, циклический —
   0%/100% оба `#f00`) и `accent-color` не тронут; `::-webkit-slider-
   runnable-track` и `::-moz-range-track` — одинаковый контракт (высота
   10px, `border`, `border-radius: 999px`, `background: var(--hp-picker-
   hue-track)`); `::-moz-range-progress` обнулён в `transparent`, чтобы
   Gecko не закрашивал левую часть трека сплошным accent-цветом поверх
   градиента; `@media (forced-colors: active)` переопределяет оба трека на
   `Canvas`/`ButtonText` — системный безопасный fallback без градиента.
4. Подтверждено, что новый CSS не покидает `.hue-range`: точечный grep по
   файлу — `::-webkit-slider-thumb`/`::-moz-range-thumb` для `.hue-range`
   отсутствуют (совпадает с тем, что ТЗ не заявляло новый thumb-стиль,
   только «остаётся различимым»); общий `input[type='range']` не содержит
   `linear-gradient`/`hp-picker-hue-track` (подтверждено также unit-тестом
   `commonRange`).
5. **Дисциплина falsifiability применена к обоим прогнанным тестам:**
   - unit: воссоздан pre-#192 файл во временном `git worktree` на
     `origin/dev` и прогнан новый тест `test/color-picker.test.mjs`
     («the hue range exposes one cyclic spectrum...») именно против старого
     `.hue-range` (только `accent-color`, без градиента) — тест корректно
     падает на первой же проверке
     (`--hp-picker-hue-track:\s*linear-gradient` не находит совпадения).
     Worktree удалён после проверки.
   - browser smoke: `node demo/smoke_color_picker.mjs` прогнан на текущем
     дереве — все 15 проверок `true`, включая новую `hueTrackContract`
     (class, `min/max/step`, `--hp-picker-hue-track` содержит
     `linear-gradient`, `height >= 40px`); падение этой же проверки на
     pre-#192 бандле подтверждено тем же временным worktree (переменная
     `--hp-picker-hue-track` не существует на старом `.hue-range`, так что
     проверка `.includes('linear-gradient')` даёт `false`).
6. Собран собственный бандл (`npm run build`) и сверен SHA-256 всех трёх
   копий (`dist/`, `custom_components/houseplan/frontend/`,
   `demo/srv/assets/`) — совпадает с заявленным автором в хендоффе
   (`8ec9aff0...`).
7. Прогнан `npm run golden:verify` (полный набор, 67 активных сценариев) —
   не только названные в TESTING.md сцены: подтверждён список расхождений
   (см. «Обязательные гейты» и «Гейты по необходимости»).
8. **Живая проверка в браузере сверх названных в issue способов
   доказательства** (см. «Находки»): открыт picker через тот же харнесс,
   что использует `smoke_color_picker.mjs`
   (`demo/serve.mjs` + `card._decorTool='line'` + `.trigger` click), hue
   программно выставлялся в 0°, 55°, 205°, 210°, 220°, 235°, 250°, 260°,
   каждый раз делался точный `page.screenshot({clip})` по
   `getBoundingClientRect()` самого `.hue-range`, чтобы увидеть реальный
   растровый результат, а не полагаться на чтение CSS. Аналогичная проверка
   повторена на независимо собранном pre-#192 бандле (тот же временный
   worktree) для сравнения «было/стало».
9. Проверены трейлеры и class-принадлежность: `git show 508d38c --stat` —
   класс A (`src/hp-color-opacity.ts`), B (`test/`, `demo/`), C (`docs/`), D
   (все три копии бандла) — все в одном коммите; `Issue: #192`,
   `User-Visible: yes`; оба changelog редактируются в этом же коммите.
10. Проверено отсутствие новых runtime dependencies:
    `git diff origin/dev...HEAD -- package.json package-lock.json` — пусто.

## Обязательные гейты (всегда)

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | чисто, без вывода |
| Unit-тесты | `npm test` | `889/889`, 0 fail (совпадает с заявленным автором) |
| Build + сверка бандлов | `npm run build` + `sha256sum dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js demo/srv/assets/houseplan-card.js` | все три идентичны, `8ec9aff054216bc8df5df9bf6410213254a352c7b742b4b28231e0a0048171b2` — совпадает с хендоффом автора |

Falsifiability (тест должен уметь падать), применена к обоим прогнанным
наборам — см. п.5 выше («Как проверялось»): unit и browser-smoke оба
корректно падают на pre-#192 коде.

## Гейты по необходимости

| Гейт | Почему запускался | Результат |
|---|---|---|
| `node demo/smoke_color_picker.mjs` | назван в AC2 issue как способ доказательства, единственная затронутая поверхность | зелёный, все 15 проверок `true`, включая новую `hueTrackContract`; falsifiability подтверждена (см. выше) |
| `npm run golden:verify` (полный набор, 67 активных сценариев) | diff меняет видимый рендер открытого picker (новый градиент трека) — подпадает под критерий «рендер/геометрия/стили/слои» из инструкции к ревью | 65 `passed`, 1 `different` (`decor-color-popover-mobile-ru` — ожидаемо, картинка просмотрена, см. «Находки»), 1 `missing-baseline` (`decor-color-popover-desktop-en` — новая сцена, ожидаемо). Изоляция (AC4) подтверждена: ни один из 65 остальных сценариев, включая все прочие поверхности с `input[type=range]` (тряй-панели, диалоги устройств), не изменился |
| `python -m pytest tests_backend -q` | не запускался | diff не трогает ни одного файла `custom_components/**/*.py` (подтверждено `git diff --stat`), гейт неприменим |
| performance-профили | не запускались | AC явно называет причину не запускать: «статичный CSS gradient, runtime вычислений нет»; diff не трогает canvas/рендер-цикл плана, только статичный CSS двух `input[type=range]` |

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

- **AC1 — спектр.** `.hue-range` получает циклический 7-стопный
  `linear-gradient(to right, #f00 0% … #f00 100%)`, применённый через
  `::-webkit-slider-runnable-track` и `::-moz-range-track` с одинаковыми
  стопами (общая CSS-переменная `--hp-picker-hue-track`) — подтверждено
  чтением и unit source-contract тестом. Живой рендер в Chromium (скриншоты
  hue=0/55/205/235/250) показывает корректный порядок цветов: красный →
  жёлтый → зелёный → циан → синий → маджента → красный, совпадает со
  стандартным hue-кругом.
- **AC2 — управление.** `min=0/max=359/step=1` не изменены; mouse (через
  `.value` + `input` event), touch (pointer-путь `sv-field` не тронут,
  сам hue остаётся нативным range), Arrow/`Shift+Arrow` (`shiftArrowUsesTenStep`),
  focus/Escape и `hp-color-opacity-change` — все существующие smoke-проверки
  остались зелёными без изменений ожиданий, кроме одной новой добавленной
  (`hueTrackContract`); 120° по-прежнему даёт `#00ff00` (`hueUpdatesSharedDraft`).
- **AC4 — изоляция.** Полный `golden:verify` (67 сценариев) подтверждает: из
  всех поверхностей с `input[type='range']` (decor picker, диалоги устройств,
  тряй-панели) изменился рендер только у самого открытого color popover;
  общий `input[type='range']` блок не содержит градиентных деклараций
  (unit-тест `commonRange` + собственноручный grep).
- **AC5 — совместимость.** `package.json`/`package-lock.json` не менялись;
  API компонента (`color`/`opacity`/`showOpacity`/`disabled`,
  `hp-color-opacity-change`) не тронуто; i18n-строк не добавлено — сверено
  чтением diff.
- **forced-colors fallback (часть AC3).** `@media (forced-colors: active)`
  корректно переопределяет оба трека на системные `Canvas`/`ButtonText` без
  градиента — безопасный вариант деградации, соответствует общей практике
  WCAG для forced-colors.
- **Gecko progress не перекрывает градиент.** `::-moz-range-progress`
  обнулён в `background: transparent` — без этого Firefox залил бы левую
  часть трека сплошным accent-цветом поверх спектра, что было прямо названо
  риском в хендоффе автора; проверено чтением (Gecko недоступен в среде
  ревью, как и заявлено в «Принятых предположениях» issue).
- **Изоляция gradient от текущего выбранного цвета (п.3 контракта).**
  `--hp-picker-hue-track` — статическая константа, не зависит от `_hue`;
  подтверждено чтением и тем, что unit-тест матчит буквальные hex-стопы.
- **prefers-reduced-motion (п.4 контракта).** Новый CSS не добавляет
  `transition`/`animation`; существующий `@media (prefers-reduced-motion:
  reduce)` блок не тронут — подтверждено diff'ом.
- **Trailers/классы файлов/changelog.** Коммит `508d38c` несёт `Issue: #192`,
  `User-Visible: yes`; оба changelog (`docs/CHANGELOG.md`,
  `docs/CHANGELOG.ru.md`) редактируются в этом же коммите; формулировки
  («шкала «Оттенок» показывает полный спектр») соответствуют
  `docs/USER-GUIDE.ru.md`, термины не изобретены.
- **Golden-сценарии (план автотестов).** Новая light-сцена
  `decor-color-popover-desktop-en` добавлена и покрыта отдельным
  contract-тестом (`test/golden-matrix.test.mjs`), проверяющим ровно два
  сценария `dialog === 'decor-color'` с ожидаемыми `theme`/`language`/
  `width` — соответствует плану автотестов issue.

## Находки

### Medium-1 — thumb hue-шкалы теряет контраст с треком в диапазоне циан/синий/индиго (~195°–260°)

**Файл:** `src/hp-color-opacity.ts:234-259` (новый градиент трека без
компенсирующего стиля thumb).

AC3 issue дословно требует: «Spectrum/thumb читаемы в light/dark... thumb
остаётся различимым». Риск-таблица самого issue заранее называла этот
сценарий («Thumb теряется на ярком секторе») и предлагала меру
(«контрастная border/shadow без уменьшения focus indicator») — эта мера не
реализована: в diff нет ни `::-webkit-slider-thumb`, ни `::-moz-range-thumb`
для `.hue-range`.

**Воспроизведение (выполнено, не предположение).** Открыт picker тем же
харнессом, что и `demo/smoke_color_picker.mjs` (`demo/serve.mjs`, decor →
Line → `.trigger`), hue выставлялся программно через `input.value` +
`input`-event, затем снят `page.screenshot({ clip })` строго по
`getBoundingClientRect()` элемента `.hue-range`:

- при hue 205° (то самое значение, что используется в обеих golden-сценах
  `decor-color-popover-mobile-ru` и `decor-color-popover-desktop-en`,
  просмотренных автором как «контраст корректен») граница между thumb и
  треком уже заметно слабее, чем на жёлтом/красном участке;
- при 210°, 220°, 235°, 250° thumb почти сливается с треком — узнаваемого
  контрастного контура нет, различим только по едва заметному перепаду
  яркости.

Причина: thumb рисуется фиксированным системным цветом браузера (в
тестируемом Chromium — solid blue), который не меняется с `_hue`
(независимый от #192 давний баг: `accent-color: var(--hp-picker-hue)` не
красит сам thumb ни до, ни после этого коммита — проверено тем же способом
на независимо собранном pre-#192 бандле, thumb там тоже фиксированно-синий,
но на равномерно-сером треке это никогда не создавало проблемы контраста).
До #192 нейтральный серый трек гарантировал контраст с любым
фиксированным цветом thumb; #192 заменяет этот трек радугой, и ровно в той
части круга, что близка по тону к цвету самого thumb, декларированное в
AC3 «thumb остаётся различимым» перестаёт быть верным для реального
Chromium-рендера — единственного движка, фактически исполняемого в CI/
smoke/golden этого проекта (Gecko/WebKit заявлены как source-contract-only
по «Принятым предположениям» issue).

**Почему Medium, не Low.** Находка не гипотетическая: воспроизведена прямым
запуском в том же харнессе, что использует официальный smoke, на реальном
исполняемом движке проекта, включая ровно те hue-значения, что приняты в
golden baseline. Диапазон ~65° из 359° (≈18% круга) — это не край случай, а
частый выбор (синие/циановые акценты в HA-конфигурациях освещения).
Функциональность не ломается (клавиатура, числовая подпись `205°`,
drag из любой точки трека работают), поэтому не High; но декларированный
критерий приёмки (AC3, «thumb остаётся различимым») в этом диапазоне не
выполняется, что не позволяет закрыть находку как Low с одной лишь записью.

**Действие:** заведён отдельный issue
[#194](https://github.com/Matysh/houseplan-card/issues/194) (`bug`, `P3`,
`S1-new`), со ссылкой на #192 и на этот документ. Обнаруженный смежный
давний баг «`accent-color` не красит thumb вообще» описан в issue как явно
не-скоуп — самостоятельный вопрос, а не часть этой находки.

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

- **Реальный Firefox/Gecko и Safari/WebKit.** Смотрел только Chromium
  (единственный движок, доступный в среде ревью и в CI проекта). Gecko/
  WebKit-декларации (`::-moz-range-track`, `::-moz-range-progress`)
  проверены исключительно чтением CSS и совпадением стопов с
  webkit-версией — это прямо принято issue как достаточное доказательство
  («Принятые предположения»: «WebKit/Safari и Gecko declarations
  доказываются source-contract и code review»), не пытаюсь выдать это за
  исполненный тест.
- **Реальный screen-reader / forced-colors режим ОС.** `@media
  (forced-colors: active)` прочитан построчно (валидный синтаксис, системные
  ключевые слова `Canvas`/`ButtonText`), но не исполнялся в браузере с
  реально включённым forced-colors — то же ограничение среды, что уже было
  зафиксировано как Low в SPEC-ревью и признано доказуемым только чтением
  кода.
- **`prefers-reduced-motion: reduce` живьём** — подтверждено чтением diff
  (блок не тронут, новый CSS не содержит `transition`/`animation`), не
  отдельным browser-прогоном с эмуляцией медиа-фичи.
- **`npm run golden:accept`** — не запускал и не должен: принятие baseline
  (в т.ч. новой сцены `decor-color-popover-desktop-en`) принадлежит
  пре-бета этапу на полном Linux CI-артефакте, не циклу код-ревью.
- **Полный `node demo/smoke_*.mjs` набор (127 файлов)** — не запускался
  целиком: diff касается ровно одной поверхности (`hp-color-opacity`),
  прогнан только относящийся к ней `smoke_color_picker.mjs` плюс golden
  целиком (гейт «по необходимости» — рендер/стили).
- **Bundle size budget** — issue не называет числовой бюджет (в отличие от
  #57); не оценивал raw/gzip дельту отдельно, только сверил байт-в-байт
  идентичность трёх копий и совпадение SHA-256 с хендоффом автора.

## Вердикт

Жёлтый. High: 0, Medium: 1 (→ [#194](https://github.com/Matysh/houseplan-card/issues/194)), Low: 0.
AC1, AC2, AC4, AC5 выполнены и доказаны исполнением, с личной проверкой
falsifiability для обоих прогнанных тестов. AC3 выполнена частично: light/
dark читаемость трека и forced-colors fallback подтверждены, но
задекларированное в этом же AC «thumb остаётся различимым» не
выполняется в диапазоне hue ~195°–260° на Chromium — единственном
исполняемом в этом проекте движке — что прямо воспроизведено скриншотами в
ходе ревью, а не предположено. Это ровно тот сценарий, который сама задача
предвидела в своей риск-таблице и не закрыла кодом. Находка не блокирует
(функциональность и три остальных AC не страдают, диапазон — суб-часть
одного критерия), поэтому не High; заведена отдельным issue #194 согласно
процессу. Жёлтый, а не зелёный — потому что реализация не полностью решает
заявленный в AC3 сценарий, даже при том что формальные шаги плана
автотестов пройдены.