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

# CODE-REVIEW-476-r1

- **Issue:** #476 — Явное завершение выбора цвета кнопкой «ОК»
- **Этап:** код-ревью (PROCESS.md §2.7), заход r1, блокирующих циклов израсходовано 0 из 4
- **Ветка:** `issue/476-color-picker-ok`, HEAD `b5a1001e` (приведена к `dev` конвейером,
  поверх легло 4 коммита `dev`: `34a6b276 → b5a1001e`). Разбор — полный, не по дельте
  (ребейз на ушедший вперёд `dev`, §7.2/§2.10).
- **Диапазон:** `git log --oneline origin/dev..HEAD` — 7 коммитов (2 ТЗ, 2 документа
  ревью ТЗ, 3 реализации); материал — `git diff origin/dev...HEAD`, 53 файла.
- **ТЗ:** `docs/specs/476-color-picker-ok.md`, лёгкий трек не применялся (полный трек по
  собственному решению аналитики — новый UX-контракт), ревью ТЗ зелёное на r2
  (`docs/reviews/SPEC-REVIEW-476-r2.md`).

## Скоуп диффа

Общий `hp-color-opacity`: полноширинная кнопка «ОК» (последний DOM-control),
CSS-контракт (100% width, ≥40px, forced-colors), новый признак `_hexNeedsValidInput`
(защита от снятия ошибки повторным «ОК» без нового ввода), `color_picker.confirm` в
4 словарях, per-card labels в `houseplan-card.ts`, обновлённые unit/i18n-тесты,
расширенный `demo/smoke_color_picker.mjs` и правки `demo/smoke_help_affordance.mjs`
(fallback-путь), запись в `scripts/smoke-links.mjs`, оба changelog, `docs/TESTING.md`,
пересобранные `dist/**`/`custom_components/houseplan/frontend/**`, обновлённый
`docs/images/screenshots.json` (только fingerprint, PNG не менялись). Backend, модель
геометрии, config/storage не затронуты.

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

Зелёного Validate на `b5a1001e` не найдено — прогнал дешёвые и часть тяжёлых гейтов сам.

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | чисто, без вывода |
| Unit-тесты | `npm test` | `2077 tests, pass 2076, fail 0, skipped 1` — совпадает с заявленным в хендоффе |
| Build + sync | `npm run build && npm run bundle:sync` | `dist` собран; `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` — идентичны; `git status --short` после `bundle:sync` пуст (demo/srv/assets, custom_components и dist совпадают с закоммиченным, включая несобственную копию стенда) |
| Docs-гейт | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 12 external links)` — обязателен, diff трогает `src/**` |
| Новый `any` | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | «Новых any нет» (59 добавленных строк в 2 файлах) |
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | Зарегистрированная связь (2): `smoke_color_picker.mjs`, `smoke_help_affordance.mjs`. Слабая связь (15, общее имя `stopPropagation`) — просмотрел список: `smoke_cover_*`, `smoke_decor`, `smoke_edit_walk`, `smoke_editor_gestures`, `smoke_furniture`, `smoke_hide_layers`, `smoke_inert_openings`, `smoke_modes`, `smoke_room_cards`, `smoke_space_settings`, `smoke_tap_ctx`, `smoke_tap_run`, `smoke_toggle_confirmation`, `smoke_value_face_source` — все про другие компоненты, ни один не адресует `hp-color-opacity`; не гонял |
| Целевой смок 1 | `node demo/smoke_color_picker.mjs` | `OK`, все 21 поле `true` |
| Целевой смок 2 | `node demo/smoke_help_affordance.mjs` | `OK`, все поля `true`, включая новые `fallbackPickerHasConfirm`/`fallbackPickerConfirmCloses` |
| Bundle budget | `npm run bundle:budget` | initial View `299683 B` gzip, потолок `300500±2000` — в бюджете; `::warning::` про низкий запас (1383 Б) — долг #367, не новый и не вызван этим диффом |
| Golden (advisory) | `npm run golden:verify` | 5 названных ТЗ сцен (`decor-color-popover-mobile-ru`, `decor-color-popover-desktop-en`, `general-color-popover-desktop-en`, `device-ripple-color-popover-mobile-ru`, `space-room-color-popover-desktop-ru`) — `different`, ожидаемо (новая кнопка); остальные ~100 сцен — `passed`. Просмотрел `actual/`+`diff/` для обеих цветовых сцен глазами — разница только в кнопке и вертикальном сдвиге содержимого попапа, цвет/геометрия/тема не поехали. Принятие эталонов — предрелизный гейт (`golden:accept -- --reviewed` на Linux CI), не гейт код-ревью; автор в хендоффе прямо назвал это «НЕ сделано» |
| Docs screenshots | ссылка автора: run `34029831929` | `gh run view` → `completed/success`; SHA `ce07db74` — предок HEAD; `check-docs.mjs` на HEAD зелёный, то есть текущий фингерпринт уже совпадает с деревом |
| Process-gate | `node scripts/process-gate.mjs` | «гейт пройден, предупреждений 0» |
| Трейлеры | `git log origin/dev..HEAD` (7 коммитов) | у всех `Issue: #476`; `11cc5386` (реализация) — `User-Visible: yes`, оба changelog в том же коммите; остальные 6 — `User-Visible: no` |

**Мутации, прогнанные лично** (§2.7 «чем краснеет», защитные AC):

| # | Мутация | Файл | Прогон | Результат |
|---|---|---|---|---|
| 1 | Снял ветку `if (this._hexNeedsValidInput) { this._hexInvalid = true; return; }` в `_commitHex` — повторное «ОК» без нового ввода закрывало бы picker | `src/hp-color-opacity.ts` | `npm run bundle:sync && node demo/smoke_color_picker.mjs` | `repeatedConfirmCannotBypassInvalidHex: expected true, got false` — тест красится, как обязан (см. M1) |
| 2 | Убрал `if (normalized !== this._lastValidColor)` — `_commitHex` эмитит всегда | `src/hp-color-opacity.ts` | то же | `confirmClosesWithoutDuplicateOrClickThrough: false`, `validCorrectionAllowsConfirm: false` — AC2 доказан исполнением |
| 3 | Убрал `event.stopPropagation()` из `_confirm` | `src/hp-color-opacity.ts` | то же + отдельный probe-скрипт с листенерами на каждом уровне DOM | `confirmClosesWithoutDuplicateOrClickThrough: true` — **тест НЕ покраснел** (см. M2); probe показал, что событие гасится на `.editor-secondary`, на один уровень выше `hp-color-opacity`, независимо от этой мутации |

После каждой мутации источник восстановлен из `git show HEAD:src/hp-color-opacity.ts`,
`npm run bundle:sync` прогнан повторно, `git status --short` — пусто, `demo/smoke_color_picker.mjs`
снова `OK` (проверено).

**Не гонял и почему:**
- `python -m pytest tests_backend` — diff не трогает `custom_components/**/*.py`.
- `npm run invariants` — diff не меняет рёбра комнат, записи толщины, `layout`,
  `marker.space`, `open_spans`; геометрия не затронута.
- Performance-профили — не названы в AC; §15 ТЗ обоснованно утверждает отсутствие
  влияния (один статический `button`, один `click`-handler в уже открытом lazy-picker).
- Полная матрица `demo/smoke_*.mjs` и полный `scripts/mutation-gate.mjs` — предрелизные
  гейты (PROCESS §8), не гейт код-ревью; по дельте прогнаны только зарегистрированные
  смоки плюс личные точечные мутации.
- `npm run golden:accept` — не моя роль на этом этапе; смотри выше.

## Находки

### Medium (в скоупе задачи, обе)

**M1 — AC4: защита от обхода невалидного HEX повторным «ОК» не имеет постоянного
свидетеля в `scripts/mutation-gate.mjs`.**

Признак `_hexNeedsValidInput` — это ровно то, что r1 ревью ТЗ потребовало добавить
(`SPEC-REVIEW-476-r1.md`), и ровно то, что доказывается только браузерным смоком
(`demo/smoke_color_picker.mjs`, дорогой гейт: пересборка бандла + Chromium). По
PROCESS.md §2.7: «Мутант в `scripts/mutation-gate.mjs` обязателен, когда защита живёт
в продуктовом коде и проверяется дорогим гейтом… там ревьюер не воспроизведёт
отрицательный прогон второй раз». Диф не добавляет ни одной записи в
`scripts/mutation-gate.mjs` (только запись-указатель в `scripts/smoke-links.mjs`, это
другой реестр — для выбора смоков, не для мутационного гейта).

Я лично применил ровно эту мутацию (см. таблицу выше, #1) и получил красный
`repeatedConfirmCannotBypassInvalidHex`, так что защита реальна и смок сегодня её ловит
— но без постоянной записи в реестре это разовое доказательство ревьюера, а не
воспроизводимый гейт: следующий рефакторинг того же кода останется незамеченным, если
не начитает эту главу отчёта.

**Чинится:** зарегистрировать мутант (по образцу #366/#384/#330 — `guard: node
demo/smoke_color_picker.mjs`, патч — снятие ветки `if (this._hexNeedsValidInput)` в
`_commitHex`), прогнать `node scripts/mutation-gate.mjs --check` и целевой `--id=`.

**M2 — AC3/§7.2.4: заявленная защита «клик не проваливается в план/toolbar под
поверхностью» не имеет проверки, способной упасть на снятой защите.**

Я убрал `event.stopPropagation()` из `_confirm` (единственный код защиты, добавленный
этой задачей) и прогнал `demo/smoke_color_picker.mjs` — `confirmClosesWithoutDuplicateOrClickThrough`
остался `true`. Добавил зонды-слушатели на каждом уровне DOM (кнопка → `.picker` →
shadowRoot picker → хост `hp-color-opacity` → `.editor-secondary` → shadowRoot `card`
→ `card`) и увидел, что событие в проверяемом сценарии (decor-tool color внутри
`.editor-secondary`) гасится ещё на `.editor-secondary`, на уровень выше самого
пикера, независимо от того, вызывает ли `_confirm` `stopPropagation()`.

Продуктового бага здесь нет — клик в план сегодня не проваливается, даже с двойным
запасом. Но это значит, что заявленная в АС3/§7.2.4 защита самого `hp-color-opacity`
не доказана ни одним тестом, который способен упасть: в единственном
протестированном потребителе есть посторонний внешний гаситель, а другие потребители
общего пикера (general settings, room/space, ripple color) не обязательно обёрнуты
таким же контейнером — для них `_confirm`'s `stopPropagation()` может быть
единственной защитой, и она никем не проверяется.

**Чинится** одним из двух путей: (а) перенести click-through-пробу в потребителя без
такого внешнего гасителя (например, `general-color` или `device-ripple-color`,
благо они уже в golden-матрице) так, чтобы снятие `stopPropagation()` красило смок;
либо (б) зарегистрировать мутант в `scripts/mutation-gate.mjs` с guard'ом на
`demo/smoke_color_picker.mjs`, но тогда сам смок сначала должен научиться падать по
пункту (а) — иначе мутант зарегистрирован, но бесполезен.

High: 0. Medium вне скоупа: 0.

### Low (сняты с записью, не блокируют)

- **L1** `src/houseplan-card.ts:5932` — `invalidHex: …, confirm: …` на одной строке
  (`git diff` слепил две записи объекта). Чисто косметика, синтаксис и typecheck
  корректны; не мешает чтению настолько, чтобы требовать отдельного цикла. Снято.
- **L2** AC3 «keyboard activation» (Enter/Space по кнопке) проверяется в смоке только
  через `.click()`, не через реальный `KeyboardEvent`. Риск исчезающий: кнопка —
  нативный `<button type="button">` без собственного `keydown`-перехватчика, поэтому
  активация с клавиатуры и мышью в браузере производят один и тот же `click`. Снято.
- **L3** AC5 в ТЗ (§12) декларирует доказательство «smoke» для всех путей закрытия
  (`outside pointer`, `trigger`, `Escape`), но ни `demo/smoke_color_picker.mjs`, ни
  unit-тесты не проверяют `outside pointer` и повторный клик по `trigger` — ни до
  этой задачи, ни после (проверил `git show origin/dev:demo/smoke_color_picker.mjs`
  — тоже нет). Код `_outsidePointerDown` и ветка закрытия в `_toggle()` этим диффом
  не тронуты (проверено чтением, не исполнением) — риска регрессии нет, `Escape`
  же покрыт и прогнан зелёным. Пред-существующий пробел плана тестов, не этой
  задачи; попутно не чиню (§ «скоуп не расширяется»), фиксирую, чтобы не читать
  как «покрыто», когда это не так.

## AC — таблица доказательств (весь список, r1)

| AC | Чем доказан | Чем краснеет |
|---|---|---|
| AC1 видимая кнопка/геометрия | unit (`color-picker.test.mjs`: `width:100%`, `min-height:40px`, DOM-порядок) + `golden:verify` (5 сцен, диф — только кнопка, см. выше) | не защитный AC (расположение/CSS), правило §2.7 не требует столбца |
| AC2 live parity, без дублирующего события | smoke `confirmClosesWithoutDuplicateOrClickThrough`, `validCorrectionAllowsConfirm` | мутация #2 лично: `_commitHex` эмитит всегда → оба поля `false` |
| AC3 успешное завершение / без click-through | smoke `confirmClosesWithoutDuplicateOrClickThrough` (aria-expanded, focus, `parentClicks`) | click-through часть — **не красится** (M2); закрытие/фокус — красится (проверено логикой `_closePicker(true)`, не мутировал отдельно, риск низкий, код тривиален) |
| AC4 невалидный HEX / защита от обхода | unit (regex на `_hexNeedsValidInput`) + smoke `invalidHex*`, `repeatedConfirmCannotBypassInvalidHex` | мутация #1 лично: красное (M1 — нет постоянной регистрации) |
| AC5 прежние close paths | smoke `escapeClosesFirstAndRefocuses` (Escape); outside/trigger — не проверены автотестом, проверено чтением (L3) | Escape: не мутировал отдельно, код path нетронут диффом |
| AC6 i18n/a11y | unit (`test/i18n.test.mjs`, `color-picker.test.mjs` — EN/RU/DE/FR parity, DOM-порядок = порядок Tab) + smoke `englishLabels`/`cardLanguageOwnsCopy` | не защитный AC (текст/раскладка) |
| AC7 touch/fallback/lifecycle | smoke `confirmIsFullWidthTouchTarget`, `smoke_help_affordance.mjs` (`fallbackPickerHasConfirm`, `fallbackPickerConfirmCloses`) | не мутировал; оба пути (Popover/fallback) реально прогнаны через разные смоки, расхождения нет |
| AC8 совместимость/release/бюджеты | `no-new-any`, `check-docs`, `bundle:budget`, оба changelog в одном коммите (см. таблицу гейтов) | не защитный AC в терминах §2.7 |

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

- Состояние `_hexNeedsValidInput` синхронно с §7.3 ТЗ: снимается только новым
  `input`-событием с валидным HEX (`_hexInput`), не снимается нормализацией draft в
  `_commitHex`, не снимается повторным «ОК», не снимается `blur` — прочитано построчно
  и подтверждено мутацией #1.
- `_hexDraft`/`_lastValidColor` остаются синхронными после любого live-изменения (hue/
  sat/val/opacity тоже проходят через `_emit`, который обновляет `_hexDraft`), поэтому
  обычное «ОК» после слайдеров не создаёт дублирующий emit — подтверждено мутацией #2
  от противного и штатным прогоном смока.
- Кнопка — последний DOM-control независимо от `showOpacity` (проверено и unit-, и
  smoke-ассертами на разных инстансах, включая `showOpacity=false`).
- i18n: 4 языка добавлены синхронно; DE/FR allow-list для омографов с EN обновлён
  обоснованно (`OK` там действительно совпадает с английским текстом — это ожидаемый
  омограф, а не пропущенный перевод).
- Оба changelog в одном `User-Visible: yes` коммите (`11cc5386`), трейлеры на всех 7
  коммитах корректны, ветка/issue совпадают.
- Backend, config, миграция, геометрия не затронуты — соответствует ТЗ §10 и §6
  (не входит).
- Golden-diff глазами: разница ровно в кнопке и вертикальном сдвиге контента, ничего
  постороннего не поехало ни в одной из 5 сцен.

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

- `pytest tests_backend`, `npm run invariants`, performance-профили, полная матрица
  `demo/smoke_*.mjs`, полный `scripts/mutation-gate.mjs`, `golden:accept` — см.
  обоснование в таблице гейтов выше.
- 15 «слабых» смоков по `stopPropagation` из вывода `smoke-select.mjs` — просмотрел
  список имён, все про другие поверхности, не про `hp-color-opacity`; не гонял.

## Вывод

High: 0. Medium в скоупе: 2 (M1, M2) — обе чинятся в этой же задаче, без отдельного
issue (#202). Verdict: жёлтый.

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/476-color-picker-ok`, коммит `34a6b276473c` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `94485fdc0eca504692dd2776c7f3c86518a8dfb9`
  ```
  git log --all --format='%H %T' | grep 94485fdc0eca
  ```
- ТЗ `docs/specs/476-color-picker-ok.md`, блоб `d21066d56e69c35fe7d0b40d9f965968dac9f803`
  ```
  git log --all --find-object=d21066d56e69c35fe7d0b40d9f965968dac9f803 -- docs/specs/476-color-picker-ok.md
  ```