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

CODE-REVIEW-212-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/212
• Спецификация: docs/specs/212-device-icons-polish.md (зелёный SPEC-REVIEW-212-r1)
• Диапазон: origin/dev...HEAD = ec6f77b (specify) · 5cae1fd (spec review doc) · 120d413 (fix: polish device icons and pointer feedback, Issue: #212, User-Visible: yes)
• Ветка: issue/212-device-icons-polish
• Роль: ревьюер кода, свежая сессия, без контекста написания ТЗ/кода.

Скоуп проверки

Единая задача #212, консолидирующая #22/#154/#181: 10% визуальное уменьшение marker geometry, форма display: value, accepted-action feedback (200 ms), instance-local pointer modality и снятие sticky touch-hover, гейтинг всех :hover в общем View/shared CSS, обновление docs/UX-MODES.md, docs/TOUCH-SUPPORT.md, docs/USER-GUIDE.ru.md, docs/TESTING.md, оба changelog. AC1–AC16 из спецификации.

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

Гейт	Команда	Результат
Типы	npx tsc --noEmit	зелёный
Юнит	npm test	952/952 зелёных
Сборка	npm run build	зелёная; md5sum dist/… custom_components/…/frontend/… demo/srv/assets/… — три копии идентичны
Документация	node scripts/check-docs.mjs --external	«Documentation checks passed (7 files, 10 external links)»
Mutation-proof (§19.1: 4 критичных guard'а)	node scripts/mutation-gate.mjs --id=device-visual-factor-removed и ещё 3 (device-text-capsule-radius-restored, device-press-duration-drifted, device-touch-hover-gate-removed)	все 4: «тест покраснел, как обязан» — тесты доказанно умеют падать
Таргетированные browser smoke (названные в §19.1)	node demo/smoke_device_icon_design.mjs	зелёный, включая новые ключи acceptedActionFeedback, reducedMotionUsesNoScale, keyboardActionFeedback, textCoreIsStadium
	node demo/smoke_device_preview_parity.mjs	зелёный
	node demo/smoke_static_icon.mjs	зелёный
	node demo/smoke_state_value.mjs	зелёный
	node demo/smoke_icon_scale.mjs	зелёный
	node demo/smoke_touch_tips.mjs (переписан под real-touch context)	зелёный
	node demo/smoke_feedback_v2.mjs	зелёный
	node demo/smoke_help_affordance.mjs	зелёный (включая mouseHover внутри вложенного hp-dialog)
	node demo/smoke_long_press_gesture.mjs	зелёный
Regression-смоки затронутой поверхности (не названы в §19.1, но задеты диффом hover/pointer)	smoke_lock_action, smoke_lock_invariant, smoke_toggle_confirmation, smoke_vacuum, smoke_opening_binding, smoke_editor_gestures, smoke_isometric_live_touch, smoke_kiosk_pan_lock, smoke_pan_any_zoom	все зелёные — lock-инвариант и gesture-safety не задеты
Regression-смоки затронутой поверхности (найдены сломанными)	smoke_glow.mjs, smoke_room_settings.mjs, smoke_ux_fixes.mjs	красные — см. находки M1/M2 ниже
Golden	npm run golden:verify (диагностически, Windows/Linux CI локально недоступен)	ожидаемо много different (10% resize, value-radius, hover-гейт) — согласно §19.2 принятие эталонов не входит в код-ревью и остаётся пре-релизным шагом

Геометрический вывод AC1/AC3 проверен чтением, не исполнением, с ручным выводом формул (см. ниже) — сверх того, что покрывают unit/smoke.

AC-трассировка

• AC1 (10% geometry). Формула: --dev-size: calc(icon-size × dev-scale × var(--device-visual-factor, 0.9)); --puck-size использует тот же множитель. Unit (device-marker-polish-contract.test.mjs) + browser smoke (geometryMatchesAt32_56_96, referenceStateMatrixMatches) зелёные; mutation-proof device-visual-factor-removed красит guard. Доказано.
• AC2 (anchor/hit area). .dev::before держит width/height: max(44px, --device-shell-size); painted face уменьшается, hit target и left/top anchor — нет. hitAreaAtLeast44 в smoke зелёный. Доказано чтением + smoke.
• AC3 (value capsule). Проверено чтением и ручным геометрическим выводом: core height фиксирована (--dev-size), core border-radius = --dev-size/2; shell height фиксирована (--device-shell-size), border-radius = --device-shell-size/2. Поскольку --device-shell-size = --dev-size × 1.26875 и --device-shell-pad/border устроены так, что --dev-size + 2× (pad+border) = --device-shell-size (уже верно в базовом пакете #179), прямой подстановкой получается: straight_length_inner = straight_length_outer = core-content-width − 0.68×dev-size, т.е. эрозия равномерна — прямые стороны и полукруглые торцы получают одинаковый inset, не приближённо, а точно по формуле. textCoreIsStadium (browser smoke) и mutation-proof device-text-capsule-radius-restored подтверждают на практике. Доказано.
• AC4/AC5 (feedback, gate действия). _startDevicePressFeedback вызывается ровно в трёх точках, все — непосредственно перед реальным callWS/ callService: virtual-light toggle, обычный toggle (включая cover/valve — projectedTapAction проецирует legacy 'cover' в 'toggle', тот же путь), run (script/scene/automation) внутри guarded() после согласия confirmation. info/more-info/gate _deviceBindingActive перед run не получают feedback. _keyDevice идёт через тот же _clickDevice. Смоки acceptedActionFeedback, informationalActionHasNoFeedback, keyboardActionFeedback, touchDispatchGetsFeedback зелёные; mutation-proof device-press-duration-drifted красит guard. Доказано.
• AC6 (composition/lifecycle). renderDeviceFace кладёт activity-ring/ activity-dot/newdot/habadge/.lqi соседями .device-shell, а не внутри него — анимация scale на .device-shell не касается их. Web Animations scale-keyframe анимирует только раскрашенное тело относительно собственного центра (стандартный transform-origin элемента). updated() зовёт _pruneDevicePressFeedback() — снимает анимацию исчезнувшего маркера; _cancelDevicePressFeedback() вызывается на смену режима/пространства/ visibilitychange/reduced-motion change. feedbackLifecycleBounded в smoke зелёный. Доказано чтением + smoke.
• AC7 (reduced motion/focus). _reducedMotion переключает набор keyframes на outline-акцент вместо scale; reducedMotionUsesNoScale зелёный. Focus/:focus-visible не гейтится pointer-атрибутом (см. AC10). Доказано.
• AC8 (modality authority). PointerModalityController/ nextPointerModality — чистые функции, покрыты unit-матрицей (pointer-modality.test.mjs), включая изоляцию двух экземпляров и отказ compatibility-mouse (sourceCapabilities.firesTouchEvents) возвращать hover. Browser smoke touchOnlyHardwareRejectsMouseHover, compatibilityMouseIgnored, realMouseRestoresHover зелёные. Доказано.
• AC9 (JS hover cleanup). _clearTransientHover вызывается на terminal pointerup/pointercancel/lostpointercapture, начало multi-touch, _commitSpace, _setMode, visibilitychange hidden, disconnectedCallback. Smoke touchClearsTransientHover/ touchClearsAllTransientHover зелёные. Доказано.
• AC10 (CSS/nested hover inventory). Все :hover в styles.ts, hp-dialog.ts, hp-help.ts, hp-color-opacity.ts, space-card.ts гейтированы :host([data-pointer-hover]); unit-тест сканирует эти 5 файлов и требует пустой список голых селекторов. Но hp-device-preview.ts получил такой же гейтированный селектор (:host([data-pointer-hover]) .previewstage .dev:hover), не входит в список файлов юнит-теста и не входит в список элементов, которым родительская карточка проставляет атрибут — см. M2. Кроме этого файла, AC10 доказан.
• AC11 (desktop/hybrid parity). smoke_help_affordance.mjs (mouseHover/mouseLeave) и smoke_feedback_v2.mjs (realMouseRestoresHover) зелёные на реальных PointerEvent. Но три ранее существовавших регрессионных смока той же поверхности (room/device tooltip и hover) остались на старом MouseEvent-API и красные — см. M1.
• AC12 (gesture/action safety). smoke_editor_gestures, smoke_isometric_live_touch, smoke_kiosk_pan_lock, smoke_pan_any_zoom, smoke_lock_action, smoke_lock_invariant, smoke_toggle_confirmation, smoke_vacuum, smoke_opening_binding — все зелёные, регрессии не обнаружено. Доказано.
• AC13 (surface parity). Один renderDeviceFace на full/preview/static; smoke_device_preview_parity, smoke_static_icon зелёные. Доказано.
• AC14 (no data/i18n change). git diff не содержит правок в src/i18n/** ни в custom_components/**/*.py. Доказано чтением.
• AC15 (documentation address). docs/UX-MODES.md получил раздел hover/pressed ownership; docs/CANVAS.md не тронут (git diff пуст); check-docs.mjs --external зелёный. Доказано.
• AC16 (performance). Один MediaQueryList-listener и один MutationObserver на карточку (не на маркер); _pruneDevicePressFeedback сканирует .dev[data-id] только пока жив хотя бы один press-анимейшн (узкое окно ~200 мс на одно нажатие), не на каждый кадр. Полный performance_smoke — пре-релизный гейт, не прогонялся по правилу соразмерности. Проверено чтением, не исполнением, кроме этого — за пределами код-ревью.

Находки

M1 — три существующих regression-смока сломаны миграцией mouse→pointer событий (Medium, в скоупе)

src/houseplan-card.ts заменил обработчики комнаты/маркера с @mouseenter/@mousemove/@mouseleave на @pointerenter/@pointermove/ @pointerleave, а статический HouseplanCard._touchSeen удалён целиком — это входит в скоуп (§12, AC8/AC9/AC11). Автор обновил под новое API smoke_touch_tips.mjs, smoke_feedback_v2.mjs, smoke_help_affordance.mjs, smoke_device_icon_design.mjs, но пропустил три других существующих смока той же поверхности:

• demo/smoke_glow.mjs — трогает _hoverRoom через new MouseEvent('mouseenter'). Воспроизведение: node demo/smoke_glow.mjs → FAILED (3): hoverUsesPlainSvg, hoverUsesNeutralDarkening, hoverLayerOrder. На origin/dev (проверено в чистом worktree) тот же смок зелёный целиком.
• demo/smoke_room_settings.mjs — node demo/smoke_room_settings.mjs → FAILED (1): tooltipShowsHumiditySource.
• demo/smoke_ux_fixes.mjs — использует и MouseEvent('mousemove', …) для tooltip, и несуществующий более c.constructor._touchSeen = true для проверки touch-подавления. node demo/smoke_ux_fixes.mjs → FAILED (8): tipTemp, tipHum, tipHasTempLine, tipHasHumLine, tipMetricOrder, tipPositionUnchanged, tipHasArea, tipHasAreaLine.

Это не регрессия поведения для реального пользователя — я подтвердил диагностически: подменив в smoke_ux_fixes.mjs вызовы на настоящие PointerEvent('pointermove', {pointerType:'mouse', …}) (без изменения продуктового кода), все 7 из 8 упавших проверок содержимого/позиции тултипа (tipTemp, tipHum, tipHasTempLine, tipHasHumLine, tipMetricOrder, tipPositionUnchanged, tipHasArea, tipHasAreaLine) зазеленели — реальная мышь по-прежнему корректно показывает тултип с температурой/влажностью/ площадью в прежнем порядке и позиции. Единственная оставшаяся red (noHoverSuppressesTooltip) — прямое следствие удалённого _touchSeen, который тест больше не может имитировать без настоящего touch-события (смотри как это сделано в переписанном smoke_touch_tips.mjs).

Почему это всё равно находка, а не «просто устаревший тест». CI-джоб smoke в .github/workflows/validate.yml прогоняет весь набор demo/smoke_*.mjs на каждый push (только байт-в-байт идентичный вход снимает прогон через reuse-кэш — здесь src/** меняется, значит прогон неизбежен). Эти три файла красные прямо сейчас на этом SHA — обязательный пре-релизный гейт CI будет красным. Кроме того, smoke_ux_fixes.mjs noHoverSuppressesTooltip после фикса перестаёт что-либо проверять (тест не падает по правильной причине, а молча не взаимодействует с картой) — это ровно тот «тест, который не умеет падать по факту», который правило ревью требует ловить.

Требуется: в smoke_glow.mjs, smoke_room_settings.mjs, smoke_ux_fixes.mjs заменить MouseEvent('mouse{enter,move,leave}') на PointerEvent('pointer{enter,move,leave}', {pointerType:'mouse', …}) (по образцу уже переписанных смоков этого же коммита) и переписать touch-latch проверку в smoke_ux_fixes.mjs через настоящий PointerEvent('pointerdown', {pointerType:'touch'}) вместо c.constructor._touchSeen.

M2 — hp-device-preview.ts гейтирует hover, но никто не выставляет ему атрибут (Medium, в скоупе)

src/hp-device-preview.ts:357 меняет .previewstage .dev:hover { z-index: 2; } на :host([data-pointer-hover]) .previewstage .dev:hover { z-index: 2; } — тот же паттерн, что и в hp-dialog.ts/hp-help.ts/hp-color-opacity.ts. Но:

• houseplan-card.ts._syncPointerHoverTargets() и ._syncPointerHoverSubtree() выставляют data-pointer-hover только на 'hp-dialog, hp-help, hp-color-opacity' — hp-device-preview в списке нет;
• у HpDevicePreview нет собственного PointerModalityController (в отличие от HouseplanSpaceCard, который держит свой);
• unit-тест device-marker-polish-contract.test.mjs («removes the global touch latch and gates every shared hover selector») сканирует только ['styles.ts', 'hp-dialog.ts', 'hp-help.ts', 'hp-color-opacity.ts', 'space-card.ts'] — hp-device-preview.ts не входит, поэтому «голый» (в реальности осиротевший) селектор не поймался.

Воспроизведение: <hp-device-preview> рендерится напрямую в шаблоне houseplan-card.ts:19684 (Device editor → preview). В демо-харнессе: открыл _setMode('devices') → _openMarkerDialog(...), нашёл вложенный hp-device-preview, продиспатчил на нём настоящие PointerEvent('pointerover' /'pointermove', {pointerType:'mouse'}). Результат: у карты data-pointer-hover появляется (true), у hp-device-preview — нет (false) ни при каких условиях, поскольку ничего не вызывает toggleAttribute на этом элементе. Эффект: .previewstage .dev:hover { z-index: 2 } в Device preview теперь не включается никогда (до #212 работал через голый :hover) — маленькая, но настоящая регрессия видимого поведения на явно указанной в скоупе поверхности (§5: «Device preview»; §16 явно называет этот файл среди тех, что нужно трогать «если parity требует явной передачи»).

Требуется: либо добавить hp-device-preview в список целей _syncPointerHoverTargets/_syncPointerHoverSubtree (симметрично hp-dialog/hp-help/hp-color-opacity), либо завести собственный PointerModalityController внутри HpDevicePreview по образцу HouseplanSpaceCard; вместе с этим расширить список файлов в naked-hover-selector unit-тесте, чтобы такой пробел не проходил снова.

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

• Формула 10%-коэффициента, её применение к shell/core/glyph/puck/rings и сохранение anchor/hit-area — код и мат. вывод сходятся, mutation-proof ловит регрессию.
• Радиус display: value — точный геометрический вывод показывает равномерный inset по всему периметру, не приближение.
• Feedback-контракт (кому положен, длительность, reduced-motion, keyboard, lifecycle, отсутствие влияния на semantic state/LQI/badges) — сходится по коду и по смокам на всех проверенных путях диспатча (toggle, virtual-light, cover через projected toggle, run/script, keyboard Enter/Space, touch tap).
• Lock-инвариант, gesture-safety (pan/pinch/long-press/second pointer), toggle-confirmation — не задеты; все относящиеся смоки зелёные.
• Три копии бандла идентичны, документация (UX-MODES/TOUCH-SUPPORT/ USER-GUIDE.ru/TESTING/оба CHANGELOG) обновлена в том же коммите с верным адресом (CANVAS.md не тронут), трейлеры корректны.
• i18n/backend не задеты.

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

• npm run golden:accept не запускался и не должен — принятие эталонов вне код-ревью (PROCESS.md §8, §13). golden:verify прогнан диагностически локально (Windows), ожидаемо показывает массовые different от 10%-resize и гейта hover; финальная сверка на полном Linux CI-артефакте — задача пре-релиза.
• performance_smoke и npm run inventory не прогонялись — не относятся к гейту код-ревью (PROCESS.md §8), AC16 закрыт чтением кода.
• Полный набор из 127 demo/smoke_*.mjs не прогонялся целиком — прогнаны все смоки из §19.1 плюс 12 смоков смежных поверхностей (lock/confirmation/ gesture/vacuum/opening), которые и вскрыли M1. Оставшиеся ~100 смоков не относятся к затронутым файлам (plan/backup/floors/registry и т.п.) и не прогонялись.
• python -m pytest tests_backend не прогонялся — диапазон не трогает custom_components/**/*.py.
• Ручная визуальная приёмка golden-скриншотов (Light/Dark 32/56/96, pressed midpoint, reduced-motion accent) не проводилась — не относится к код-ревью, явно назначена на пре-релиз (§19.2).

Вердикт

Продуктовое поведение для реального пользователя не сломано ни разу за то, что я смог воспроизвести (M1 — только стенд, не поведение; M2 — реальная, но небольшая визуальная регрессия в admin-only Device preview). High: 0. Обе находки — Medium, в скоупе задачи (пункты §12/§13 самой спецификации), чинятся в этой же ветке без нового issue.

Вердикт: жёлтый · цикл r1/4 · High: 0 · Medium: 2 → в задаче