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

CODE-REVIEW-651-r1

Материал раунда: git log --oneline origin/dev..HEAD / git diff origin/dev...HEAD, SHA c40266431ca1335ed09ebbaace9656b55ee84e23 (рабочая копия уже на нём). Коммиты: 4ab7ecb4 (fix(2.5D): keep device overlays stable while zooming, Issue #651, User-Visible: yes) и c4026643 (test(2.5D): retire superseded zoom mutant, Issue #651, User-Visible: no).

Скоуп

Задача переводит вычисление положения HTML-overlays устройств и lock badges в 2.5D в стабильный масштаб «вписать всё» (referenceView) и заменяет независимое попарное разведение значков (resolveIsoOverlayCollisions) на жёсткую групповую раскладку (resolveIsoOverlayRigidGroups): все значки одной комнаты, чьи расширенные на 12 CSS px базовые bounds пересекаются, получают один общий вектор сдвига. Затронуты src/iso-overlays.ts (+338 строк, новый резолвер), src/iso-scene-render.ts (кэш/подпись раскладки берёт referenceView, а не live view), src/houseplan-card.ts (передаёт структурный _baseVb('iso', structural) как referenceView), тесты, docs/ISOMETRIC.md, оба changelog, docs/STATUS.md, scripts/mutation-registry.mjs. Список затронутых модулей совпадает с §14 ТЗ, выхода за список нет.

Соответствие docs/SCOPE.md: правка чинит J1/J6 (спатиальный обзор дома остаётся читаемым при зуме, план остаётся «true» после действий пользователя) в рамках уже принятого J1-исключения #89 на публичный 2.5D-режим; новых поверхностей, настроек или охвата не добавляет.

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

Валидация на c4026643 уже зелёная (https://github.com/Matysh/houseplan-card/actions/runs/36206722475) — дешёвые гейты (tsc, npm test, build, мутанты по диффу) не перегонялись повторно вручную сверх точечной проверки ниже; тяжёлые прогнаны мной лично на этом же SHA, т.к. Validate явно пропустил их (skipped, reuse-маркер) для обоих коммитов диапазона.

Гейт	Статус	Кем/чем подтверждено
npx tsc --noEmit	🟢	часть npm run bundle:sync, прогнан лично; 0 ошибок
npm test (3099 тестов)	🟢 (не дублировал)	job «Фронтенд: типы, юниты, мутанты, синхрон бандла» зелёной Validate на этом SHA; лично прогнал целиком только test/iso-overlays.test.mjs + test/iso-scene-render.test.mjs (50/50) при верификации мутаций ниже
npm run build + сверка 3 копий бандла	🟢	прогнан лично (bundle:sync); git status после сборки — 0 диффов в dist/, custom_components/.../frontend/, demo/srv/assets/
node scripts/check-docs.mjs	🟢 (warn, как в CI)	прогнан лично с --screenshots=$(node scripts/classify-changes.mjs --screenshots-mode) → warn; единственное сообщение — ожидаемый WARN «screenshot source fingerprint is stale… before the beta candidate (#479)», это системное следствие любой правки src/** и не блокирует ни в CI, ни здесь (в strict-режиme без флага та же строка попадает в errors — не имеет отношения к #651, это дефолт скрипта, а не регресс)
demo/smoke_isometric_contract.mjs	🟢	прогнан лично: все 46 проверок true, включая новую desktopZoomKeepsOverlayScene
demo/smoke_isometric_live_touch.mjs	🟢	прогнан лично: все проверки true, включая новую touchPinchKeepsOverlayScene
node scripts/smoke-select.mjs --base origin/dev --head HEAD	🟢, изучен	8 прямых совпадений — все на _openingsR (проброшен без изменений в новый вызов, не новая логика); 35 слабых связей — все на _baseVb (реализация функции не менялась, только новый вызывающий код с явными аргументами); ни один из смоков сверх двух уже прогнанных изометрических не выбран для запуска — риск ограничен iso-overlays.ts/iso-scene-render.ts/4 строк в houseplan-card.ts, что уже покрыто прогнанными изометрическими смоками
npm run golden:verify (полная матрица, видимое изменение)	🟡 см. ниже	прогнан лично целиком (245 сценариев) на этом SHA после npm run bundle:sync
npm run benchmark:large-house-isometric	🟢	прогнан лично на этом SHA: sourceSha=c4026643…, panZoomMs median 67.3 / p95 133.7 мс — бюджет budgets-isometric-smoke.json (panZoomMs.hardMaxMs=600, absolute) кратно не задет; сам absolute-гейт уже зелёный в Validate
npm run benchmark:isometric-stage3-dense	🟢	прогнан лично на этом SHA: panZoomMs median 73.4 / p95 75.8 мс, тот же запас
npm run invariants -- --config …	не прогонял	диффа геометрии модели/конфигурации нет — сдвиг overlay - runtime-only presentation state, не сериализуется (§7 ТЗ, подтверждено чтением: nudgeScene/visualScene нигде не пишутся в RoomCfg/marker)
python -m pytest tests_backend	не прогонял	диффа custom_components/**/*.py нет
Мутационные свидетели #651 (3 новых)	🟢	зафиксированы «Мутанты по диффу (1–6/6)» зелёной Validate на c4026643; дополнительно перечитаны сами патчи (см. находки о непокрытых веток ниже)

Golden: что показал полный прогон

5 из 245 сценариев вышли different — все прямо относятся к 2.5D-оверлеям (остальные 240, включая isometric-geometry-view-*, isometric-touch-kiosk-dark, isometric-wall-junctions-dark, Flat-эквивалент large-house-warm-remount-dark на той же perf-floor-2 фикстуре — не изменились):

• isometric-stage3-overlays-light (diffRatio 1.76 %), -dark (2.10 %), isometric-stage3-forced-colors-dark (0.94 %), isometric-stage3-no-filter-dark (0.97 %) — визуально проверены: значок/бейдж и связанный с ним lock badge той же комнаты сдвигаются вместе на несколько CSS px в сторону от стены; ряд и взаимные интервалы сохраняются, диагонального распада нет.
• isometric-large-warm-remount-dark (8.21 %) — самый крупный диффа. Проверено по кропам (Room 2.1 и соседние): старый эталон рисовал в этой стресс-фикстуре по 2–3 визуально разведённых значка на комнату, где во Flat (large-house-warm-remount-dark, тот же perf-floor-2, не изменился и остался passed) на то же место приходится ровно один значок — т.е. старый попарный резолвер resolveIsoOverlayCollisions расталкивал канонически совпадающие точки, которых в Flat не существует. Новый код показывает ровно один значок на комнату, как во Flat. Это не регрессия, а прямое следствие требования §5.2.3 ТЗ («горизонтальный ряд… остаётся…», обобщённо — совпадающие точки остаются совпадающими) и корректный результат.

Новые baseline-PNG в диффе НЕ приняты — это правильно и соответствует AC7 («новый baseline принимается только из reviewed Linux artifact в ближайшем beta-candidate, а не самовольно в author-коммите»). Формулировка автора в комментарии к реализации («визуальный контракт проверяется существующими Linux golden-сценами isometric-stage3-*») неточна: существующие эталоны сейчас не совпадают с рендером этого SHA — обязательство §10.4 ТЗ («golden — перед beta по процессу») выполнено правильно тем, что PR не подделал их самостоятельно, но фраза «проверяется существующими сценами» вводит в заблуждение (эталоны как раз показывают ожидаемое расхождение, а не подтверждение). На вердикт это не влияет — сути AC7 (проверка ревьюером «одного общего сдвига без диагонального распада») сделанный мной прогон и разбор изображений закрывают.

Находки

Medium-1 (в скоупе, возврат автору) — AC1 «другая комната исключена» не доказан ни тестом, ни мутацией

resolveIsoOverlayRigidGroups/rigidOverlayGroups (src/iso-overlays.ts:1738) объединяет в одну жёсткую группу значки только при совпадении placement.owner?.id. Это ключевая часть AC1 («device markers и lock badges одной комнаты образуют ожидаемые компоненты; другая комната… исключены») и явно обещанного теста в §10.1 ТЗ («матрица групп… перестановок»). Единственный новый тест (test/iso-overlays.test.mjs, «rigid overlay groups preserve a row…») проверяет только один сценарий — три значка ОДНОЙ комнаты. Ни один тест не ставит рядом значки двух РАЗНЫХ комнат.

Воспроизведение (чем краснеет — точнее, чем не краснеет). Закомментировал проверку владельца в join-цикле:

// было:  if (stable[right].placement.owner?.id !== owner) continue;
// стало: // mutated: room ownership check removed

Пересобрал test-build (npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs) и прогнал node --test test/iso-overlays.test.mjs test/iso-scene-render.test.mjs — 50/50 тестов прошли, ни один не заметил, что значки двух разных комнат теперь могут объединяться в одну жёсткую группу и сдвигаться единым вектором через границу комнаты. Правка отменена (git diff пуст, репозиторий не тронут).

Риск: будущий рефакторинг рядом (например, изменение условия соединения) может незаметно позволить группе «перетекать» через границу комнаты — именно то, для защиты от чего ТЗ явно требует этот тест.

Medium-2 (в скоупе, возврат автору) — AC4 «деградированный fallback группы» не доказан ни тестом, ни мутацией

§5.3.5 ТЗ — самая рискованная новая ветка (собственный риск №1/2 из §11 ТЗ): если ни один кандидат-сдвиг не свободен от конфликтов, resolveIsoOverlayRigidGroups выбирает «ближайший вектор, который сохраняет принадлежность комнате и минимизирует сначала конфликт со стеной, затем с другой группой» — реализовано в rigidFallbackOrder (src/iso-overlays.ts:1690): сравнение по roomViolations, затем wallViolations, затем overlapPenalty. §10.1 ТЗ прямо обещает тест на «невозможного размещения и границы 48 px» в test/iso-overlays.test.mjs. Такого теста нет; нет и мутанта в scripts/mutation-registry.mjs, нацеленного на эту функцию (три новых мутанта бьют по: масштабу раскладки, факту соединения в группу, факту использования нового резолвера в проде — не по порядку приоритетов деградации).

Воспроизведение. Заменил тело rigidFallbackOrder на «игнорировать room/wall/overlap, сравнивать только по расстоянию»:

function rigidFallbackOrder(left: RigidCandidate, right: RigidCandidate): number {
  return rigidOffsetOrder(left.offset, right.offset);
}

Пересобрал test-build и прогнал те же два файла — 50/50 тестов прошли. Ни один существующий тест не ставит группу в положение, где после перебора всех кандидатов остаётся конфликт, поэтому приоритет «сначала не покинуть комнату, потом не задеть стену, потом не пересечься с другой группой» сейчас ничем не защищён: обратный порядок или полное игнорирование прошли бы CI незамеченными. Правка отменена, git diff пуст.

Обе находки — Medium, в скоупе задачи (тесты этого самого файла, обещанные в уже одобренном ТЗ), без High. По правилу §3 п.8/§2.7 это жёлтый вердикт и возврат автору в этом же issue, а не отдельная задача.

Low — неточная формулировка в комментарии к реализации (снято без правки)

Комментарий автора к реализации утверждает, что визуальный контракт «проверяется существующими Linux golden-сценами» — на деле эти сцены сейчас показывают ожидаемое расхождение (см. раздел Golden выше), а не подтверждение. Не меняет вердикт и не требует действий в коде/ТЗ — фиксирую только для точности учёта golden-цикла на бете; правку не считаю нужной.

Что проверено и признано корректным

• AC3 (инвариантность zoom/pan). layoutView = input.referenceView || input.view (src/iso-scene-render.ts:806); _baseVb('iso', structural) берёт scene.frame/_frameOf().rect, т.е. геометрию фита, а не live _view (src/houseplan-card.ts:6054, 6075-6092) — подтверждено чтением и тестом #651 supersedes #473 W3 (test/iso-scene-render.test.mjs), который меняет view без изменения referenceView и требует strictEqual того же объекта размещения; мутант iso-rigid-groups-use-live-zoom-scale ловится этим же тестом (подтверждено зелёной Validate). Браузерные смоки desktopZoomKeepsOverlayScene/touchPinchKeepsOverlayScene подтверждают то же в реальном DOM (прогнано лично).
• AC2 (один вектор на группу, ряд остаётся горизонтальным). Тест «rigid overlay groups preserve a row…» и «render scene keeps a close device cluster rigid…» проверяют nudgeCss/visualScene идентичность внутри группы и инвариантность к порядку входа; мутант iso-rigid-groups-split-close-row (отключение join) ловится первым тестом (зелёная Validate).
• Производственная проводка (AC — переключение на новый резолвер). src/iso-scene-render.ts:987 вызывает resolveIsoOverlayRigidGroups только в mode === 'live'; resolveIsoOverlayCollisions в проде более не вызывается (grep подтверждает единственное вхождение — сама декларация). Мутант iso-scene-restores-per-marker-collision-resolver возвращает старый вызов и ловится тестом «keeps a close device cluster rigid» (зелёная Validate).
• Room labels не входят в группу. entries.flatMap в buildIsoOverlayRenderScene явно отфильтровывает entry.kind === 'room-label' перед передачей в resolveIsoOverlayRigidGroups (src/iso-scene-render.ts:988-989) — проверено чтением, не тестом (структурная гарантия, не защитный AC — низкий риск регрессии, т.к. типы IsoOverlayCollisionKind уже исключают 'room-label' на уровне TypeScript).
• 48 px cap и safety-gap глобально. addOffset в resolveIsoOverlayRigidGroups отбрасывает кандидатов с `distance > maxNudge
  • EPS; кандидаты строятся из buildIsoOverlayBoundaryCandidates/ addBoundaryCircle`, оба уже покрыты существующими unit-тестами на границу. Не покрыт именно ВЫБОР среди легальных-по-cap, но конфликтующих кандидатов — см. Medium-2.
• AC8 (перформанс). Оба профиля прогнаны мной лично на точном SHA c4026643, бюджетные файлы (demo/performance/*.json) не менялись в диффе.
• Трейлеры и changelog. Issue: #651 + User-Visible: yes|no на обоих коммитах; docs/CHANGELOG.md/docs/CHANGELOG.ru.md правлены в том же коммите 4ab7ecb4, что и код (не в последующем). Одно число с одним источником: константы ISO_OVERLAY_MAX_NUDGE_CSS_PX (48), ISO_OVERLAY_RIGID_GROUP_GAP_CSS_PX (12), ISO_OVERLAY_SAFETY_GAP_CSS_PX (4) объявлены один раз и переиспользованы; docs/ISOMETRIC.md описывает те же числа словами, не дублирует их как отдельный источник правды.
• Три копии бандла. После npm run bundle:sync git status не показал диффов ни в dist/, ни в custom_components/houseplan/frontend/, ни в demo/srv/assets/ — сборка детерминирована и уже соответствует материалу.
• docs/reviews/INDEX.md обновлён автогенератором и синхронен со SPEC-REVIEW r1/r2 этого issue.

Чего не проверял и почему

• Полный npm test — не перегонял целиком лично (только два целевых файла много раз при верификации мутаций); полагаюсь на зелёный job «Фронтенд…» в уже подтверждённой Validate на этом самом SHA (дешёвый гейт, инструкция явно разрешает не дублировать).
• 35 «слабых» смоков из smoke-select.mjs (все на _baseVb) — не прогонял: сигнатура и реализация _baseVb не менялись, только добавлен один новый вызывающий код; риск ограничен уже прогнанными изометрическими смоками.
• npm run invariants — геометрия плана/стен/проёмов не меняется (это presentation-only runtime cache для overlay), поэтому гейт не применим; не формальный пропуск, а обоснованный чтением §7 ТЗ и кода (nudgeScene нигде не попадает в RoomCfg/config).
• pytest tests_backend — нет диффа в custom_components/**/*.py.
• Golden main/предрелизный accept — не выполнял и не должен: AC7 прямо запрещает принимать новый baseline в author-коммите; свою часть (просмотр diff-изображений, суждение «один сдвиг, не диагональ») выполнил вручную по выгруженным PNG этого прогона.
• isometric-stage3-openings-dark и другие golden с opening/lock фокусом — прошли (passed) сами, детально не разбирал сверх этого.

Вердикт

Оба AC, вынесенных в находки, входят в собственный (уже одобренный, зелёный на ревью ТЗ) тестовый план задачи (§10.1) и являются защитными/инвариантными по характеру (границы группы по комнате; порядок приоритетов деградированного fallback) — по правилу REVIEWER.md пустая графа «чем краснеет» для такого AC есть находка Medium сама по себе, а обе находки здесь дополнительно подтверждены явным мутационным экспериментом (50/50 тестов проходят при удалении защиты). High-находок нет, реализация в остальном корректна, инвариантность к zoom/pan и групповая раскладка проверены чтением, тестом и исполнением (unit + 2 браузерных смока + перформанс на точном SHA + ручной разбор golden-диффов). Вердикт — жёлтый, работа возвращается автору: дополнить test/iso-overlays.test.mjs (и по необходимости mutation-registry.mjs) сценариями «две разные комнаты не объединяются» и «невозможное размещение внутри 48 px», как было обещано в §10.1 уже одобренного ТЗ.

---

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

• Ветка: issue/651-iso-device-layout-stability, коммит c40266431ca1 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 7afb4dcc4787ceabd952ead5915616bd806a98b2

  git log --all --format='%H %T' | grep 7afb4dcc4787
  

• Тело issue: 699e063899bf674ad775879fc1a0c889489a2f90b14fde467497787cc8f69442
• Вердикт конвейера: yellow · High 0