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

CODE-REVIEW-179-r2

• Issue: https://github.com/Matysh/houseplan-card/issues/179
• ТЗ: docs/specs/179-device-icons-redesign.md (зелёное SPEC-REVIEW r2)
• Диапазон: origin/dev..HEAD — ровно один коммит, 9daa2e9 («fix: align device compatibility guards and vacuum puck»). origin/dev уже стоит на 6fdb7dc — весь материал из CODE-REVIEW-179-r1 (зелёный, 48bcdaf и далее) туда слит; r2 проверяет только delta сверху.
• Ревьюер: Claude (свежая сессия, без контекста реализации r1/r2)
• Вердикт: зелёный · цикл r2/4 · High: 0 · Medium: 0

Скоуп

Автор объяснил в комментарии к issue: r1 был зелёным и слит, но параллельный полный smoke-прогон нашёл 7 существующих guard-смоков, которые ещё читали старую подложку .dev напрямую (до редизайна 48bcdaf фон/бордер маркера были на самом .dev, после — на дочерних .device-core/.device-shell). При их актуализации всплыл реальный, а не тестовый, дефект: живой vacpuck пылесоса не получил обновлённую тему пакета (light/dark core, обводка, тень), хотя действующий (до-#179) контракт «пылесос выглядит как базовая иконка устройства, только круглая и меньше» — docs/USER-GUIDE.ru.md и комментарий в src/styles.ts («owner's wording: «иконка похожа на иконку базы, только круглая и чуть меньше»») — привязывает его вид к базовому маркеру. Редизайн базового маркера изменил это «оригинал», а vacpuck не подтянулся — это пробел именно в объёме #179, не посторонняя находка.

Диапазон (git diff --stat origin/dev...HEAD, 16 файлов) состоит из:

• src/houseplan-card.ts, src/styles.ts — применение существующего deviceThemeClass() к .vacpuck и его CSS-блока (core/stroke/shadow теперь зеркалят .device-shell/.device-core из r1, а не старые --hp-bg/--hp-line/ --shadow-1 токены);
• 7 demo-смоков (smoke_cover_no_plate, smoke_cover_plate_precedence, smoke_hidden_flag, smoke_icon_scale, smoke_infinite_canvas, smoke_motion_sense, smoke_vacuum) — assertions переориентированы на новую DOM-структуру и текущие тайминги/значения (например, длительность continuous pulse 2.4s → 3.6s — уже принятая r1 величина, эти смоки её просто не знали);
• 3 сгенерированных копии бандла (dist/, custom_components/.../frontend/, demo/srv/assets/) — класс D, следствие правки styles/houseplan-card; 1 doc-скриншот (docs/images/06-device-display-preview.png) и docs/images/screenshots.json (весь sourceFingerprint пересчитан, как и ожидается при любой правке src/); оба changelog.
• Посторонних правок вне этого плана не найдено.

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

Гейт	Команда	Результат
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-gate), оба раза чисто
Docs fingerprint	node scripts/check-docs.mjs --external	green, 7 files, 10 external links
Process gate (офлайн)	node scripts/process-gate.mjs	green, диапазон = 1 коммит, 0 предупреждений
7 целевых compatibility-смоков (ровно то, что чинит коммит)	node demo/smoke_cover_no_plate.mjs, smoke_cover_plate_precedence.mjs, smoke_hidden_flag.mjs, smoke_icon_scale.mjs, smoke_infinite_canvas.mjs, smoke_motion_sense.mjs, smoke_vacuum.mjs	все 7 green, лично прогнаны
Регрессия mutation-guards из r1 (тот же styles.ts)	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: чистый прогон зелёный, мутант красный — гейты пережили этот диф без деградации
--check реестра мутаций	node scripts/mutation-gate.mjs --check	все 20 патчей, включая 4 device-, ложатся ровно один раз

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

• Полный node scripts/mutation-gate.mjs (без --id) и полный browser-smoke набор (127 файлов) — диф касается ровно одной подсистемы (device marker + vacpuck) и её уже известного набора зависимых смоков; все 7 задетых смоков прогнаны лично, полный набор — предрелизный гейт (PROCESS.md §8).
• npm run golden:verify — grep по demo/golden/ не нашёл ни одного сценария, завязанного на vacpuck; визуальный риск ограничен цветами core/shell, которые дословно совпадают с уже принятым в r1 (golden-проверенным) пакетом .device-shell/.device-core (тот же border: 1px solid #BCBCBC и тот же box-shadow: 0 1px 2px rgb(37 40 45/12%), 0 4px 8px -1.07px rgb(37 40 45/18%) — сверено построчно, см. ниже). Полный набор — предрелизный гейт.
• python -m pytest tests_backend -q — Python-код не тронут.
• Performance-профили — диф не добавляет новых подписок/наблюдателей (только CSS custom properties и класс-строка), числового бюджета в AC для этого фикса не названо; предрелизный гейт.
• Мутационная проверка вручную (временный откат deviceThemeClass() на .vacpuck в src/houseplan-card.ts и повторный прогон smoke_vacuum.mjs) была задумана, но заблокирована системой разрешений — ревьюеру запрещено редактировать продуктовый код (роль в PROCESS.md §6: «Ревьюер кода… Не имеет права: править продуктовый код»). Вместо этого проверено чтением: и smoke_cover_no_plate.mjs, и smoke_vacuum.mjs сверяют точные getComputedStyle(...).backgroundColor/.borderTopColor со значениями, которые совпадают только при наличии обеих правок (тема + пакетный shell/shadow) — вернуть старые токены (var(--hp-bg), var(--shadow-1)) сломало бы именно эти сравнения, не давая тесту пройти «случайно».

Находки

Нет High и Medium. Два Low, оба решены на месте без правки кода (запись ниже).

• Low-1 (снят). Формальный трейс: docs/specs/179-device-icons-redesign.md не упоминает vacpuck ни в одном AC — эта правка не была частью исходного ТЗ. Не поднимаю как Medium «вне скоупа», потому что решение задокументировано самим владельцем в комментарии issue («реальный пробел… vacpuck оставался на старых theme colors») и находится внутри той же поверхности, что и #179 (единственная причина, по которой vacpuck вообще имеет цветовой контракт — «выглядит как базовая иконка», а базовую иконку поменял именно #179). Формальной правки ТЗ (новый AC15) не внесено — при следующей правке этого маркера стоит дописать его в §8 ТЗ, но блокировать r2 из-за отсутствия строки в уже принятом документе не за что: issue как канонический источник (PROCESS.md, преамбула) фиксирует то же решение.
• Low-2 (снят). RU changelog («Живой маркер робота-пылесоса использует те же цвета темы, обводку и тень») не использует уже устоявшийся в docs/USER-GUIDE.ru.md термин «puck» (там прямо: «живой puck», «движущийся puck», строки 649/828/879/1153). EN-версия термин использует верно («The live vacuum puck…»). Смысл фразы не искажён и путаницы у пользователя не создаёт, поэтому не блокирую; для единообразия в следующей правке лучше сказать «живой puck пылесоса».

Проверено и корректно

• Тема vacpuck. .vacpuck теперь объявляет --vac-core-bg/--vac-core-fg через light-dark(#fff, #252525) с явным переопределением .vacpuck.theme-light/.vacpuck.theme-dark — тот же паттерн (тот же light-dark() fallback + классовое переопределение), что уже принят и проверен для .dev в r1 (--device-core-bg/--device-core-fg, src/styles.ts:1867-1868); новой техники CSS не введено. deviceThemeClass() — не новая функция, тот же хелпер из src/device-face.ts, который уже применяется к .dev во всех трёх поверхностях (houseplan-card.ts, hp-device-preview.ts, space-render.ts); здесь просто добавлен четвёртый вызов на vacpuck. проверено чтением + smoke (smoke_vacuum.mjs green, лично прогнан).
• Border/shadow parity. .vacpuck: border: 1px solid #BCBCBC и box-shadow: 0 1px 2px rgb(37 40 45/12%), 0 4px 8px -1.07px rgb(37 40 45/18%) — построчно идентичны .device-shell (src/styles.ts:1912,1915-1917), сверено дословно. Владельческий контракт «vacpuck = уменьшенная базовая иконка» соблюден для нового пакета так же, как соблюдался для старого. проверено чтением.
• 7 compatibility-смоков. Прочитаны целиком (не только diff): новые assertions измеряют то же самое, что старые (нейтральный/жёлтый/оранжевый фон, unlocked-amber, geometry без ellipsis, границы пульсации), но через корректный текущий DOM (.device-core/.device-shell вместо .dev — с r1 фон и бордер физически переехали на дочерние элементы, поэтому старые селекторы стали мимо цели, а не «менее строгими»). В одном месте строгость даже выросла: smoke_cover_no_plate.mjs теперь дополнительно проверяет color === 'rgb(0, 0, 0)' у закрытого замка (AC4 r1: чёрный glyph), чего раньше не было. Убранная «-2px» компенсация границы в smoke_icon_scale.mjs/smoke_infinite_canvas.mjs соответствует факту: .device-core (src/styles.ts:1951-1966) не имеет собственного border — бордер только на .device-shell, значит вычитать пиксель больше не нужно. Ни одна проверка не смягчена до тавтологии (typeof x === 'string' и т.п.) — все сравнивают конкретные getComputedStyle-значения. лично прогнаны, все 7 green.
• Отсутствие побочных правок. git diff --stat ограничен файлами из описания коммита; секьюрный lock-инвариант (docs/SCOPE.md CR-1) в этом диффе не затронут (правка не касается lockState/_clickDevice/ resolveToggleIntent) — подтверждено чтением, отдельный прогон smoke_lock_* не требовался, т.к. эти файлы не входят в diff. проверено чтением.
• Регрессия r1-мутаций. Все 4 mutation-guard, введённые в r1 (device-unavailable-hover-restored, device-marker-lqi-low-boundary-shifted, device-long-value-ellipsis-restored, device-keyboard-bypasses-click-path), лично прогнаны заново на новом HEAD — чистый код зелёный, мутант красный для каждого. Правка .vacpuck не задела их поведение. лично прогнано, мутация подтверждена исполнением.
• Freshness/parity. npm run build дважды (до и после mutation-gate) давал побайтово идентичные три копии бандла — сборка не расходится с тем, что закоммичено, и mutation-gate корректно восстанавливает файлы после себя (git status пуст после каждого прогона). check-docs.mjs --external зелёный — screenshot fingerprint (docs/images/screenshots.json) актуален относительно нового src/. лично прогнано.
• Трейлеры и процесс. Единственный коммит 9daa2e9 несёт Issue: #179 и User-Visible: yes; оба changelog правятся в этом же коммите (RU и EN), соответствует правилу «правки в оба changelog в том же коммите». process-gate.mjs (офлайн) — 0 предупреждений на диапазоне из 1 коммита.

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

• Полный golden:verify, полный browser-smoke набор (127), полный mutation-gate без --id, performance_smoke, pytest tests_backend — предрелизный гейт по PROCESS.md §8, диф не расширяет их необходимость (обосновано выше по каждому пункту).
• Мутационную проверку самой правки .vacpuck не выполнил исполнением (запрещено редактировать продуктовый код в роли ревьюера) — заменено разбором точных значений в assertions (см. «Как проверялось»).
• Визуальную приёмку docs/images/06-device-display-preview.png глазами не делал — доверился зелёному check-docs.mjs --external (фингерпринт подтверждает, что скриншот пересобран из текущего кода, а не устарел); единственный байт разницы в размере файла для полноценной ревизии PNG не даёт повода подозревать регрессию.

Итог

Единственный коммит диапазона (9daa2e9) — точечный compatibility-фикс внутри уже принятого объёма #179: обновляет 7 существующих guard-смоков под новую DOM- структуру маркера из r1 и приводит vacpuck в соответствие с той же темой/пакетом shell, что уже получил основной маркер. Оба изменения проверены построчным сравнением с уже отревьюенными в r1 значениями (не с нуля), все 7 задетых смоков и 4 унаследованных mutation-guard лично прогнаны и зелёные. Секьюрный lock-инвариант не затронут. High: 0, Medium: 0; два Low сняты с записью (отсутствие формального AC15 в ТЗ — компенсировано решением владельца в issue; RU-терминология «маркер» вместо устоявшегося «puck» — не искажает смысл). Задача уходит в очередь на пре-релиз.