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

CODE-REVIEW-213-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/213
• Спецификация: docs/specs/213-device-marker-geometry.md (зелёный SPEC-REVIEW-213-r1, High 0 · Medium 0)
• Диапазон: origin/dev...HEAD = 0c93be9 (specify) · c749d68 (spec review doc) · 0e5ee03 (fix: polish device marker geometry and input, Issue: #213, User-Visible: yes)
• Ветка: issue/213-device-marker-geometry
• Роль: ревьюер кода, свежая сессия, без контекста написания ТЗ/кода.

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

Одна реализационная задача, закрывающая AC1–AC13 из спецификации: удаление позднего --device-visual-factor: 0.9 в пользу единого effective-base на границе поверхности; прямой 0.55×core MDI viewport; общая concentric-геометрия core/shell через новый .device-shell-frame; opening Lock/Unlock на визуальном пакете #179; hover/action всей видимой value-капсулы; возврат непрерывной lqiColor() для marker LQI. Изменённые модули: src/styles.ts, src/device-face.ts, src/device-presentation.ts, src/houseplan-card.ts, src/space-render.ts, src/hp-device-preview.ts, новый src/device-marker-geometry.ts; targeted smokes, unit-тесты, mutation-gate guard, docs (ARCHITECTURE.md, TESTING.md, USER-GUIDE.md/.ru.md, оба changelog), reference screenshots.

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

Гейт	Команда	Результат
Типы	npx tsc --noEmit	зелёный
Юнит	npm test	955/955 зелёных, 0 skipped (расходится с хендофф-комментарием «954 passed, 1 skipped» — вероятно другое окружение автора; актуальный прогон здесь зелёный и это авторитетно)
Сборка	npm run build	зелёная; cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js и cmp … demo/srv/assets/houseplan-card.js — обе байт-в-байт идентичны, git status после пересборки чист (закоммиченный бандл свежий)
Документация	node scripts/check-docs.mjs --external	«Documentation checks passed (7 files, 10 external links)»
Mutation-proof (AC1, единственный названный в §18.2 guard)	node scripts/mutation-gate.mjs --id=device-visual-factor-removed	«тест покраснел, как обязан» — guard доказанно умеет падать
Таргетированные browser smoke (названы в §18.2 / затронуты диффом)	node demo/smoke_device_icon_design.mjs	зелёный, включая новые valueCapsuleOwnsHoverAndActionAtEveryPosition, lqiUsesContinuousComputedColor
	node demo/smoke_device_icon_pixel_alignment.mjs (новый, ядро AC3)	зелёный на всех 4 DPR; собственный mutant (translateX(1px)) детектируется — тест доказанно умеет падать
	node demo/smoke_device_preview_parity.mjs	зелёный, включая переписанный resolvedBaseContract
	node demo/smoke_static_icon.mjs, smoke_icon_scale.mjs, smoke_state_value.mjs	зелёные
	node demo/smoke_opening_binding.mjs	зелёный, включая новый openingLockUsesPackageGeometryAndStates (Light/Dark × locked/unlocked/unknown)
	node demo/smoke_registryless_opening.mjs, smoke_lock_action.mjs, smoke_lock_invariant.mjs	зелёные — secure no-toggle-on-plan инвариант не задет
	node demo/smoke_touch_tips.mjs	зелёный — hover/touch-контракт не задет
Regression-смоки, задетые переименованием .device-shell → .device-shell-frame	node demo/smoke_hidden_flag.mjs, node demo/smoke_vacuum.mjs	зелёные
Golden (диагностически, этот раннер — Linux)	npm run golden:verify	30 из ~90 сценариев different — все просмотрены (artifacts/golden/diff/*.png): расхождение локализовано строго на маркерах устройств/lock-бейджах (обновлённая геометрия/глиф/LQI-цвет), стены/комнаты/tray/диалоги без затронутых markers не изменились. Ожидаемо по §18.3/§20 ТЗ: baseline принимается только npm run golden:accept -- --reviewed на полном Linux CI артефакте, это пре-релизный шаг, не гейт код-ревью

Полный smoke (154 файла), performance_smoke и pytest tests_backend сознательно не прогонялись — см. «Чего не проверял».

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

• AC1 (size contract). --device-visual-factor удалён из src/styles.ts (.dev, .vacpuck); effectiveDeviceBaseSize() в новом src/device-marker-geometry.ts пересчитывает legacy icon_size в effective base один раз на границе (houseplan-card.ts, space-render.ts, hp-device-preview.ts — статический 48.6px). Арифметика проверена: (x/2.5) × 2.25 = x × 0.9, т.е. численно тождественно старому позднему множителю для default/explicit/kiosk/per-marker/preview/vacuum. Юнит device-marker-geometry.test.mjs покрывает границы (NaN→default, пропорциональность). Mutation-proof device-visual-factor-removed красный на восстановленном позднем * 0.9 внутри --dev-size. Доказано unit + mutation-proof + smoke geometryMatchesAt32_56_96.
• AC2 (glyph). .dev ha-icon { --mdc-icon-size: calc(var(--dev-size) * 0.55) } — прямой base, без второго множителя/transform; core/shell/anchor не читают этот токен. demo/smoke_device_icon_design.mjs (geometryMatchesAt32_56_96 проверяет iconViewport/core ≈ 0.55 и painted bbox ≈0.458) зелёный на 32/56/96, custom/rotated/state-swapped глиф не проверялся отдельным smoke сверх существующего reference-матрикса, но источник ratio один общий CSS-токен — клиппинг архитектурно маловероятен. Доказано source + smoke, custom/rotated путь — чтением.
• AC3 (concentric geometry). Ключевая переработка: .device-shell больше не несёт border/padding (padding: 0, border: 0), это чистый flex-контейнер размера --dev-size (без values) или content-based (с values). Новый .device-shell-frame — единственный визуальный слой, inset: calc(var( --device-shell-inset) / -1) растягивает его наружу от границ .device-shell на константу --dev-size × 0.134375 (алгебраически равно старой (--device-shell-size − --dev-size) / 2, то есть тот же целевой внешний диаметр, но без независимого round у padding/border). Для :not(.with-values) .device-shell выставлен left:0;top:0 — совпадает с .dev's собственным боксом (который уже центрирован на сохранённой точке через margin: calc(--dev-size/-2) 0 0 calc(--dev-size/-2)), поэтому core и frame разделяют одну систему координат вместо двух независимо округляемых. Для with-values.pos-* анкер аналогично зафиксирован на 0 (не 50% − size/2), расширение идёт только в выбранную сторону. Никаких translate(1px), UA/DPR sniffing или per-size исключений. Доказано чтением (вывод формулы выше) + новый smoke_device_icon_pixel_alignment.mjs (dense quarter-px DOM-центры на 24…112px, alpha-weighted painted-centroid на 12 дробных размерах × 4 DPR, red/green solid-diagnostic слои, calibrated предел DPR/2 + 0.1 физ. пикселя, отдельный mutant translateX(1px) детектируется) + reviewed golden diff (только маркеры).
• AC4 (anchor/parity). .dev width/height/margin формула не изменилась (тот же --dev-size, просто из другого источника); 44×44 пол сохранён через .dev::before { width/height: max(44px, --device-shell-size) } (не тронут). smoke_device_preview_parity, smoke_static_icon, smoke_icon_scale, hitAreaAtLeast44 в smoke_device_icon_design зелёные. Доказано unit facts + smoke.
• AC5/AC6 (opening locks + security). .oplock разложен на .oplock-shell/.oplock-core с ratio 1.26875/0.55, Light/Dark токены и цвета locked (#000/#252525, белый глиф) / unlocked (#F0A00C, тема-зависимый глиф) / unknown (нейтральный, без ложного locked/unlocked) сверены с §10 ТЗ и подтверждены openingLockUsesPackageGeometryAndStates в smoke_opening_binding.mjs (обе темы × три состояния, точные RGB). Клик по .oplock по-прежнему только this._openingInfo = o (открывает карточку), без вызова сервиса; smoke_lock_action/smoke_lock_invariant зелёные без изменений в их коде — инвариант docs/SCOPE.md (единственная санкционированная actuation-поверхность — кнопка карточки) не затронут. Доказано smoke + чтением обработчика клика.
• AC7/AC8 (capsule hover/action). .device-shell-frame получил pointer-events: auto (был none на прежнем .device-shell); .device-core и .device-sections — pointer-events: none. Единственный обработчик клика остаётся на .dev (@click=${(e) => this._clickDevice(e, d)}) — событие бабблится от любого потомка независимо от того, что визуально «капсула» выходит за CSS-бокс .dev (overflow visible); _clickDevice не читает e.target, поэтому не может задвоить действие. :hover на .dev уже был gated через data-pointer-hover (src/styles.ts:2180) и распространяется от любого наведённого потомка — новых hover-правил не потребовалось, только снятие pointer-events: none с ранее «мёртвых» зон (gap, padding) через frame. smoke_device_icon_design.mjs (valueCapsuleOwnsHoverAndActionAtEveryPosition) кликает и наводит мышь на четыре позиции value-бейджа, проверяет elementFromPoint попадает в device-shell-frame, hover совпадает с core-hover цветом и действие засчитывается ровно один раз на позицию (capsuleActions === 5, включая клик по core). Доказано smoke + чтением (нет stopPropagation на пути, единственный listener).
• AC9/AC10 (continuous marker LQI). markerLqiColor() теперь однострочно делегирует в общий lqiColor() (src/logic.ts, формула не менялась: hue = clamp((lqi-40)/140×120, 0, 120)); markerLqiBand() не тронут и остаётся источником aria/data band. Юнит device-presentation.test.mjs сравнивает markerLqiColor с lqiColor на representative/boundary значениях и явно проверяет 41 !== 42 (нет ступени). Room fill (logic.ts:1428, mode==='lqi') и tooltip (houseplan-card.ts:16185) и раньше читали lqiColor() напрямую, не через markerLqiColor — путь не затронут. Доказано unit + smoke (lqiUsesContinuousComputedColor сравнивает вычисленный computed-color с независимо построенным hsl(...)-пробником) + чтением вызывающих мест room-fill/tooltip.
• AC11 (data/i18n compatibility). Diff не касается src/i18n/*.json, card-config schema, миграций. Проверено чтением diff-статистики: изменённые файлы — только .ts/CSS-in-JS/тесты/доки; ни один i18n JSON не в списке. Доказано чтением, не исполнением.
• AC12 (performance). Чтением: реализация CSS-only + один чистый расчёт (effectiveDeviceBaseSize), новых ResizeObserver/matchMedia/per-frame JS нет; backdrop-filter: none явно сохранён и на .oplock-shell, и на .device-shell-frame; DOM-прирост на маркер — один статический <span class="device-shell-frame">, на opening-lock — два статических <span>, без анимационных слоёв сверх существующих. Performance-smoke не прогонялся — это осознанно пре-релизный гейт (§18.3 ТЗ, AGENTS.md §8), не названный в AC12 способом доказательства сверх source review. Доказано чтением, не исполнением, инструментальная часть отложена по процессу.
• AC13 (release artifacts). Оба changelog обновлены в том же коммите 0e5ee03 (User-Visible: yes), docs/USER-GUIDE.md/.ru.md, docs/ARCHITECTURE.md, docs/TESTING.md обновлены там же; check-docs.mjs --external зелёный; reference screenshots (docs/images/*.png, screenshots.json) обновлены тем же коммитом. Терминология RU-текста («капсула», «жёлтая подложка» для #F0A00C) сверена с уже установленными терминами в этом же файле (устройство pulse-активности уже описывает тот же #F0A00C как «жёлтую подложку», src/device-pulse.ts DEVICE_ACTIVITY_AMBER = '#F0A00C') — не изобретена заново. Доказано diff + check-docs + сверка терминологии чтением.

Находки

Нет находок High или Medium — ни в скоупе, ни вне его.

Low (снято, без правки). Хендофф-комментарий автора заявляет «954 passed, 1 skipped»; фактический прогон в этой сессии на том же коммите — «955 passed, 0 skipped» (см. таблицу гейтов). Расхождение не воспроизводится и не влияет на вердикт — авторитетен прогон, выполненный ревьюером на диапазоне ревью; вероятная причина — иное окружение автора (не единственный canonical способ получить число, npm run inventory тоже даёт 955). Правки не требует.

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

• Единая система координат core/shell (общий .device-shell бокс + один .device-shell-frame с константным inset) устраняет источник независимого округления, названный в issue, — подтверждено и алгебраически, и dense-matrix/painted-centroid browser-доказательством с работающим mutant.
• Effective-size arithmetic численно тождественна старому позднему × 0.9 во всех точках входа (default/explicit/kiosk/per-marker/preview/vacuum).
• Hover/action unification переиспользует существующую bubble-модель .dev без нового кода действия — риск задвоения действия исключён по построению (_clickDevice не смотрит на e.target), не только по smoke-доказательству.
• Lock security invariant (никогда не toggled с плана) не затронут: единственный обработчик клика на .oplock остаётся «открыть карточку», существующие lock-action/lock-invariant smoke не изменены и зелёные.
• Continuous marker LQI — тонкая, безопасная правка (делегирование в уже протестированную lqiColor()), room fill/tooltip путь не переиспользует markerLqiColor и не затронут.
• Vacuum-puck собственный MDI ratio (0.68) сознательно не тронут — сохранена договорённость из SPEC-REVIEW-213-r1 (Low снят на этапе ТЗ).
• Три копии бандла синхронны, docs fingerprint свежий, трейлеры и оба changelog на месте в одном коммите.
• 30 golden-сценариев, помеченных different, визуально сверены (не только по счётчику): расхождение точно очерчено пикселями маркеров/lock-бейджей, никакой утечки в стены/комнаты/tray/диалоги не обнаружено.

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

• Полный npm run smoke (154 файла). Diff не касается poверхностей вне device-face/opening-lock/LQI (planering, backup, furniture, sun/glow вычислений и т.д.); прогнаны все targeted + все смоки, тронутые переименованием класса. Расширение до полного набора — предрелизный гейт (PROCESS.md §8), непропорционально объёму диффа.
• npm run golden:accept. Не входит в роль ревьюера кода (только релиз- менеджер/владелец после полного Linux CI артефакта); увиденные 30 different — ожидаемое следствие AC1–AC5, не дефект.
• node scripts/mutation-gate.mjs (полный набор). Дорогой прогон (пересборка на мутанта), по процессу — предрелизный, не гейт ревью; прогнан только единственный мутант, названный ТЗ для этой задачи (device-visual-factor-removed), и он ловит регрессию.
• npm run performance_smoke и полный HA-харнесс (pytest tests_backend). Diff не касается custom_components/**/*.py — backend вне класса A/B этой задачи. Performance-профиль — источник для AC12 явно указан как «source review + pre-beta performance smoke»; source review выполнен, инструментальная часть — по процессу пре-релизная.
• Custom/rotated/state-swapped MDI на не-32/56/96 размерах сверх того, что покрывает существующий reference-матрикс в smoke_device_icon_design.mjs — архитектурно один общий CSS-токен, специальный smoke не заведён отдельно от общего пиксельного alignment-smoke; риск оценён как низкий чтением.

Вердикт

Зелёный. AC1–AC13 доказаны либо автотестом, который умеет падать (unit, mutation-proof, browser smoke с собственным mutant), либо прочтением с явной пометкой там, где инструментальная проверка по процессу отложена до пре-релизного гейта (AC11, частично AC12). Golden проверен диагностически на этом (Linux) раннере и подтверждает, что видимые изменения ограничены ровно заявленным скоупом.