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

CODE-REVIEW-231-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/231
• ТЗ: docs/specs/231-decor-layer-order.md (зелёный SPEC-REVIEW r2)
• Диапазон: git log --oneline origin/dev..HEAD → один коммит b747316 «fix: render decor above room fills» (Issue: #231, User-Visible: yes)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4

Скоуп

Единственное продуктовое изменение: перенос вызова _renderDecorLayer() в src/houseplan-card.ts из позиции перед рендером комнат в позицию после активной hover-заливки комнаты, обоих проходов тоннелей проёмов и Glow-base комнат — то есть непосредственно перед _renderGlowLayer(), как того требует §8.1 ТЗ. Сопутствующие изменения: новый browser-smoke demo/smoke_decor_layer_order.mjs, расширение demo/smoke_glow.mjs (decorLayer теперь участвует в hoverLayerOrder), новый documented mutant decor-restored-below-room-fills в scripts/mutation-gate.mjs, две новые golden-сцены (decor-over-opaque-hover-light, decor-over-glow-base-dark) с семантическими пиксельными пробами в demo/golden/{matrix,harness,run}.mjs и юнит-контракт на них в test/golden-matrix.test.mjs, документация (docs/BACKDROP.md, docs/DECOR-EDITOR.md, docs/TESTING.md, оба changelog), три синхронные копии бандла и пересчитанный отпечаток docs/images/screenshots.json.

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

Свежий чекаут ветки issue/231-decor-layer-order на b747316, origin/dev на момент ревью — 6683e52.

Гейты — обязательная часть (прогнаны все)

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный, без вывода
Unit	npm test	зелёный, 1070/1070 pass (0 skip — на CI runner’е автора один тест process-gate.test.mjs пропускался, окружение без gh; на поведение #231 не влияет)
Build + bundle parity	npm run build, затем cmp трёх копий и sha256sum	зелёный, все три houseplan-card.js (dist, custom_components/houseplan/frontend, demo/srv/assets) байт-в-байт идентичны (baf60c9a…)
Docs fingerprint	node scripts/check-docs.mjs	зелёный: «Documentation checks passed (7 files, 10 external links)» — diff трогает src/**, поэтому гейт обязателен, не пропущен

Гейты — по необходимости (diff и AC)

Гейт	Команда	Результат	Почему выбран
Mutation registry (статика)	node scripts/mutation-gate.mjs --check	зелёный, все id, включая новый	якоря патчей мутанта существуют ровно один раз
Mutation run (AC5, доказательство «тест умеет падать»)	node scripts/mutation-gate.mjs --id=decor-restored-below-room-fills	зелёный: «чистый прогон: node demo/smoke_decor_layer_order.mjs» → ok, «decor-restored-below-room-fills: тест покраснел, как обязан»	AC5 явно требует это доказательство, а не только регистрацию мутанта
Целевой smoke (AC1–AC4)	node demo/smoke_decor_layer_order.mjs	зелёный, все 25 полей true, включая DOM-order и пиксельные пробы hover/tunnel/glow-base	назван в АС1–АС4 и в плане тестов §15.1
Glow layer order (AC2/AC3, hover×decor×glow)	node demo/smoke_glow.mjs	зелёный, hoverLayerOrder: true и весь остальной Glow-контракт	назван в плане тестов §15.1 и напрямую правится в этом diff
Opening tunnel fill (AC2, тоннель как продолжение пола)	node demo/smoke_opening_tunnel_fill.mjs	зелёный	тоннели — предмет нормативной границы §8.1, смок их проверяет отдельно от decor
Hide/editor parity (AC4)	node demo/smoke_hide_layers.mjs	зелёный	явно назван в AC4
Decor editor поведение (AC4/AC6, не regresses)	node demo/smoke_decor.mjs	зелёный, включая decorRestored, visibleInView, inertInView	самый прямой существующий смок по объекту правки
Backdrop parity (AC4, backdrop ниже decor)	node demo/smoke_backdrop.mjs	зелёный	явно назван в AC4 и §9
Golden (AC1/AC8, диф может менять видимый результат)	npm run golden:verify	см. раздел «Находки», M1	обязателен по правилам гейтов — diff меняет геометрию/порядок слоёв
Mutation unit-контракт	node --test test/mutation-gate.test.mjs	зелёный, 6/6	регистр мутантов и test-build резолвятся

Не прогонялось и почему

• Полный demo/smoke_*.mjs (167 файлов) — не прогонялся. scripts/smoke-select.mjs, на который ссылается инструкция ревью, в репозитории отсутствует (Cannot find module .../scripts/smoke-select.mjs), поэтому автоматической выборки нет; список выше подобран вручную по AC и по diff (Glow, тоннели, hide/editor/backdrop — единственные существующие smokes, которые diff и ТЗ называют напрямую). Остальные 160+ смоков не касаются композиции SVG-слоёв.
• python -m pytest tests_backend -q — не прогонялся, diff не трогает custom_components/**/*.py.
• Performance-профили — не прогонялись, AC7 требует только «DOM count, source review и targeted performance sanity»; смок smoke_decor_layer_order.mjs уже проверяет oneDecorLayer: true (нет второго .decorlayer), число decor-групп не растёт, что и требуется. Отдельного профиля AC не называет.
• Ручного тестирования в браузере не было — не предусмотрено циклом (см. «Гейты», PROCESS §2.7); AC доказаны автотестами и разбором по коду.

Находки

M1 (Medium, в скоупе) — golden regression на трёх существующих large-house сценах не определена и не учтена

Issue #231 (п.4) прямо требует: «Любая сцена с декором изменится. Определить список и переснять отдельным шагом с доказательством ревью». ТЗ AC8 требует актуальное «golden evidence». Handoff-комментарий разработчика утверждает: «Полный npm run golden:verify → ожидаемо красный: две новые сцены имеют missing-baseline, а текущий dev уже содержит множество ранее накопленных непринятых diff».

Я прогнал npm run golden:verify на HEAD (b747316) и получил, помимо двух ожидаемых missing-baseline, ещё три сценария с вердиктом different: isometric-large-warm-remount-dark, large-house-zoom-250-dark, large-house-warm-remount-dark.

Проверил заявление о «уже накопленном dev-дрейфе» напрямую: собрал origin/dev (6683e52) в отдельном git worktree, собрал бандл и прогнал те же три сценария через node demo/golden/run.mjs --mode=capture --scenario=<id> (diagnostic-режим, --mode=verify требует полный матрикс и отказывает на --scenario) — все три passed против того же самого принятого baseline. То есть регрессия появляется именно между origin/dev и этим коммитом, а не существовала на dev заранее — причина утверждения в handoff неверна для этих трёх сценариев.

Причина найдена по коду: фикстура demo/fixtures/large-house.mjs кладёт 500 decor-объектов сеткой (makeDecor, x:0.02–0.98, y:0.018–0.97) поверх 20-комнатной сетки (roomGrid, x:0.04–0.96, y:0.04–0.96) с fill_mode: 'glow' (large-house.mjs:214) — то есть decor обширно перекрывает Glow-base заливку комнат. Это ровно тот же эффект, что и цель #231 (decor становится видимым поверх Glow-base), только на perf-фикстуре, а не на новой синтетической. При zoom 0.4 (large-house-zoom-040-dark) разница остаётся под порогом maxDiffRatio и сценарий проходит; при zoom 2.5 и в warm-remount сценариях рендер крупнее и разница превышает порог — отсюда different.

Сам визуальный эффект — ожидаемое и корректное следствие фикса (Приложение пруф выше: изменения соответствуют цели задачи, а не побочный дефект рендера). Дефект не в поведении, а в полноте DoD: список затронутых golden сцен (issue п.4, ТЗ AC8, docs/TESTING.md) называет только две новые сцены; три существующие accepted-сцены, тоже реально изменившиеся из-за этого же коммита, не определены, не занесены ни в docs/TESTING.md, ни в комментарий с доказательством. Риск: на предрелизном golden:accept -- --reviewed эти три скриншота будет легко спутать с «уже накопленным неразобранным дрейфом» (как и произошло в handoff-комментарии) и принять непроверенными либо, наоборот, несправедливо связать с #231 задним числом без объяснения причины.

Не High: поведенческий AC1–AC7 не нарушен, ничего не ломается для пользователя в этом коммите — golden baseline в этом issue не принимается вообще (по правилу принятия эталонов), сама заливка не тронута. Это пробел в трассируемости релизного артефакта и неточное заявление в handoff, а не неверное продуктовое решение.

Как закрыть в этой же задаче: дополнить список сцен, изменившихся из-за переноса decor (минимум isometric-large-warm-remount-dark, large-house-zoom-250-dark, large-house-warm-remount-dark) в docs/TESTING.md/комментарий к задаче, и заменить формулировку «уже накопленный dev-дрейф» на подтверждённую причину — пересечение large-house-decor с Glow-base после переноса слоя, которое требует того же reviewed-baseline-подтверждения перед бетой, что и две новые сцены.

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

• AC1 (decor поверх room fill). demo/smoke_decor_layer_order.mjs: customFillKeepsDecorPixels, customTunnelKeepsDecorPixels — true; прогон против кода до фикса (мутант) даёт красный, значит проверка не тривиальна.
• AC2 (decor поверх hover и пола проёма). DOM-order hoverBeforeDecor/glowBaseBeforeDecor и пиксельные hoverDoesNotTintDecorPixels, hoverTunnelKeepsDecorPixels, glowBaseKeepsDecorPixels, glowTunnelKeepsDecorPixels — все true; smoke_glow.mjs hoverLayerOrder: true подтверждает то же на независимой fixture. M1 из SPEC-REVIEW r1 закрыта именно здесь — код src/houseplan-card.ts:16720-16729 ставит decor строго после _renderRoomHoverFill и обоих _renderOpeningTunnelFills.
• AC3 (верхние слои сохранены). parity-блок smoke: liveGlowAfterDecor, sunAfterDecor, wallsAfterDecor, openingSymbolsAfterDecor, htmlDevicesAndLabelsAfterDecor — все true; подтверждено чтением src/houseplan-card.ts:16729-16731 (decor → Glow → sun rays, стены/символы/устройства дальше по файлу не переставлялись).
• AC4 (hide/editor/backdrop parity). hideDecorStillHidesView, ownEditorOverridesHide, backdropBeforeDecor — true; smoke_hide_layers.mjs, smoke_decor.mjs, smoke_backdrop.mjs — все зелёные без изменений в их собственной логике (diff их не трогает).
• AC5 (mutant доказывает тест). Реально прогнан node scripts/mutation-gate.mjs --id=decor-restored-below-room-fills: чистый прогон зелёный, с мутантом — целевой smoke красный. Не «зарегистрирован», а исполнен.
• AC6 (compatibility и surfaces). renderDoesNotRewriteDecor: true (JSON.stringify(sp.decor) === stored после полного цикла рендера); oneDecorLayer: true — второй .decorlayer не создан; статическая карточка и скрытая изометрия в diff не затронуты (изменений в соответствующих renderer'ах нет).
• AC7 (performance/security). Diff — это перемещение одного вызова и одного komментария, новых groups/observers/listeners не добавлено; oneDecorLayer: true подтверждает отсутствие дублирования слоя.
• Q1 (владелец). Единый порядок без нового флага — подтверждено кодом: disp.hideDecor && this._mode !== 'decor' ? nothing : this._renderDecorLayer() не получил новых веток/условий по объекту.
• Release-артефакты. Оба changelog обновлены в том же коммите (Issue: #231, User-Visible: yes); docs/BACKDROP.md и docs/DECOR-EDITOR.md описывают новый порядок текстом, совпадающим с фактическим кодом; docs/images/screenshots.json — отпечаток пересчитан, check-docs.mjs зелёный; три копии бандла синхронны.
• Golden — новые сцены. decor-over-opaque-hover-light и decor-over-glow-base-dark дают missing-baseline, что ожидаемо (baseline не принимается в этом ревью); test/golden-matrix.test.mjs покрывает их структуру юнитом (fill_mode, hoverRoom/glowEnabled, набор decor kinds, наличие opening-tunnel пробы) — прогнан в составе npm test.
• Существующие golden-сцены с decor (кроме large-house). golden-geometry использует fill_mode: 'none' по умолчанию — decor-линия geo-axis-h визуально не перекрывалась заливкой ни до, ни после переноса, поэтому 30+ сцен на этом пространстве (geometry-view-*, day-cycle-*, isometric-geometry-view-*, hover-nested-room-dark и др.) остались passed — подтверждено прогоном golden:verify, не только чтением. hover-nested-room-dark дополнительно проверен геометрически: полигон geo-nested (y: 0.14–0.38) не пересекает decor-линию на y=0.5, поэтому hover-fill и decor не перекрываются пространственно в этом сценарии.

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

• Полный browser-smoke набор (167 файлов) — не прогонялся целиком, только выбранные вручную из-за отсутствия scripts/smoke-select.mjs в репозитории (см. «Не прогонялось и почему»).
• pytest tests_backend — не прогонялся, diff не касается Python.
• Performance-профили (benchmark:large-house и т.п.) — не прогонялись; AC7 не называет отдельный профиль, а oneDecorLayer/DOM count проверены smoke'ом.
• Полный Linux golden-артефакт и его reviewed-принятие — вне цикла код-ревью по правилу принятия эталонов (§13 PROCESS.md); это предрелизный шаг, не код-ревью.
• Ручной просмотр в браузере на реальном HA — не проводился (не предусмотрено циклом).