houseplan-card/docs/reviews/CODE-REVIEW-451-r3.md

CODE-REVIEW #451 — заход r3

• Issue: #451 — «План тормозит: диагностика считается на каждый кадр, перетаскивание перерисовывает всё, нет фильтра обновлений»
• Этап: код-ревью (PROCESS.md §2.7)
• Заход: r3 · блокирующих циклов до этого раунда: 2/4
• Материал раунда: ветка issue/451-render-performance, HEAD = 444562e47cb746dc1c7d740b66b2f832ca02f064 (сверено git rev-parse HEAD непосредственно перед выводом, дерево чистое, PROCESS.md §2.7/#312)
• Дельта раунда: git diff cb68492c990b27e91c35130fa3a77806bd157c5e..444562e4 — SHA взят из машинного блока «Материал раунда» документа docs/reviews/CODE-REVIEW-451-r2.md (дерево aaa8519cee54…, сверено git cat-file -p cb68492c^{tree} — совпадает). Файлы дельты (без dist/** и бандла стенда): src/houseplan-card.ts, src/houseplan-editor-runtime.ts, src/junction-limits.ts, src/live-editor.ts, src/resize-controller.ts, test/resize-controller.test.mjs, docs/images/screenshots.json, docs/reviews/CODE-REVIEW-451-r2.md.

Скоуп раунда

r2 (красный, High:3) закончился на коммите cb68492c (диагностика — 8 файлов). С тех пор в ветку легли 7 коммитов: fe03eae2, 8d787530, 4b6b4abc, a7bee0f5, d513f13a (документ r2), 046efe96, 444562e4. Формально они делятся на «закрытие H1–H3 из r2» и одно не заявленное в r2 замечание — CI поймал регресс DOM после live-reconciliation ещё на a7bee0f5 (до публикации документа r2), и он же чинится в этом окне. Разбираю всю дельту по коду, а не только «после документа r2», потому что часть закрывающих коммитов (H2 — fe03eae2, H3 — 4b6b4abc) физически предшествует публикации d513f13a — r2 их не проверял (его собственная цитата диапазона 1850eb18..cb68492c их не включает), и раз так, «наследовать без проверки» для них не могу.

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

Дельта не геометрию персистентного формата, а раннее прекращение/typing нескольких вызовов и одну внутреннюю функцию (resizeLivePreflightAllowed). Прогнал сам, не полагаясь на цитаты из комментариев:

Команда	Результат
npm run build (после — git status --short)	зелёный, дерево не изменилось — бандл воспроизводим байт-в-байт
npm run bundle:sync	зелёный, стенд для браузерных смоков синхронизирован
npm test	1956 passed / 0 failed / 1 skipped (совпадает с заявленным)
node scripts/check-docs.mjs	«Documentation checks passed (7 files, 12 external links)» — H1 закрыт
node scripts/no-new-any.mjs --base cb68492c --head 444562e4	«Новых any нет» (77 строк в 5 файлах) — H2 закрыт для всей дельты, не только для fe03eae2
node demo/smoke_room_resize.mjs	OK — H3 закрыт (preflight_visible_reason/preflight_reason_once снова true/1)
node demo/smoke_resize_pointer_real_plan.mjs	OK — закрыт не заявленный в r2 регресс unrelated_pointer_ignored/capture_loss_restores_dom
node demo/smoke_resize_outer_reconciliation.mjs	OK
node demo/smoke_resize_audit_1550.mjs	OK
node demo/smoke_resize_inner_dimensions.mjs	OK
node demo/smoke_resize_labels.mjs	OK
node demo/smoke_resize_wall_thickness.mjs	OK
node demo/smoke_junction_limits.mjs	OK
node demo/smoke_wall_key_roundtrip.mjs	OK
node demo/smoke_bg_color.mjs	OK
node demo/smoke_pan_any_zoom.mjs	OK

Плюс независимая архивная проверка через gh: CI 33920551036 (SHA a7bee0f5, до публикации r2) показал Смоки в браузере (шард 3 из 3): failure с точными именами resize_pointer.unrelated_pointer_ignored / resize_pointer.capture_loss_restores_dom — это доказывает, что регресс был реальным (тест умел падать), а не выдумкой из комментария автора. Финальный CI 33922485666 (SHA 444562e4) зелёный целиком, включая все 3 шарда смоков и агрегатор.

node scripts/smoke-select.mjs --base cb68492c --head 444562e4: 29 прямых совпадений (_resize, _openingsR, _spaceWalls, NORM_W, _junctionLimitViolations, _mode, _spaceDisplayForRender, SpaceModel, WallEntry). Прогнал все, что касаются resize/geometry напрямую (список выше, 11 из 29); остальные 18 прямых совпадений — тот же класс, что уже прогнан (_openingsR/NORM_W-смоки опенингов/декора, не тронутых логически в этой дельте, тип-рефакторинг без изменения поведения) — не гонял отдельно, см. «Чего не проверял».

Закрытие r2

Находка r2	Чем закрыта	Где видно
H1 (check-docs --external красный, отпечаток скриншотов устарел)	Каноническая Linux-съёмка на точном SHA, обновлён только source fingerprint	444562e4; сам прогнал node scripts/check-docs.mjs на HEAD — зелёный
H2 (11 новых any в houseplan-card.ts:7792, junction-limits.ts:51,54,57,73, live-editor.ts:61,62,65,157,163,164)	Типизация _junctionLimitViolations/junctionLimitViolations через новый экспортируемый JunctionSharedGeometry (Pick<WallBodiesGeometryResult,...> | {status:'lightweight',...}), typed LiveEditorHost (SpaceDisplay, SpaceModel, WallEntry, RenderOpening)	fe03eae2 (src/houseplan-card.ts, src/houseplan-editor-runtime.ts, src/junction-limits.ts, src/live-editor.ts); сам прогнал no-new-any.mjs --base cb68492c --head 444562e4 — 0 новых any
H3 (_rszProjectPreview больше не вызывает _checkSpacePhysicalGeometry() ни разу во время drag — smoke_room_resize падал)	Новая resizeLivePreflightAllowed(rooms, edgeBudget=64): если суммарный периметр (число вершин) комнат кандидата ≤ 64, _rszProjectPreview вызывает _rszSpaceCandidateGeometry → тот же _checkSpacePhysicalGeometry, что и раньше, и отклоняет шаг при !ok; иначе (большие планы) остаётся только дешёвая junction-limit проверка, а точная — безусловно на pointerup через _commitPhysicalGeometry (не изменился, вызывает _checkSpacePhysicalGeometry без всяких условий)	4b6b4abc (src/resize-controller.ts:resizeLivePreflightAllowed, src/houseplan-editor-runtime.ts:3653,3691,3715-3734); прочитал _commitPhysicalGeometry (строки 2126–2148) — вызов fail-closed проверки безусловный, не зависит от live-preflight; сам прогнал smoke_room_resize.mjs — OK

Дополнительно (не было заявлено r2 находкой, но CI поймал регресс на a7bee0f5 — SHA, на котором физически лежал код r2 к моменту анализа, хотя r2 цитировал более ранний cb68492c): смоки resize_pointer.unrelated_pointer_ignored/capture_loss_restores_dom красные. Причина — _rszMove ставил в очередь _rszMoveNow для ЛЮБОГО pointerId (проверка владения была только внутри _rszMoveNow), из-за чего чужой указатель вытеснял из очереди уже поставленное обновление настоящего владельца. Закрыто 046efe96: guard ownsPointer перенесён в начало _rszMove (до постановки в очередь), плюс новый флаг _resizeBaseFrameStable — если во время resize случился полноценный render (routeLiveEditorUpdate вернул «не live» при активном _resize.preview), _rszCancelDrag больше не притворяется, что можно оставить старый терминальный DOM, и делает один обязательный reconciliation render. Сам прогнал smoke_resize_pointer_real_plan.mjs — OK; независимо подтверждено CI 33922485666 (все 3 шарда зелёные).

Унаследовано из r1 (через r2, без повторной проверки)

Эта дельта не касается доказательной базы следующих пунктов r1/r2 — принимаю как есть:

• AC1–AC2, AC7 (разделение intake/visual invalidation, dependency projection, last-wins HA во время жеста) — не тронуты дельтой r2→r3 (файлы фильтра hass/dependency classifier в диффе cb68492c..444562e4 отсутствуют). Документ: CODE-REVIEW-451-r2.md, SHA cb68492c.
• AC4 (diagnostics cache) — не тронут этой дельтой.
• AC9 (golden/canonical screenshots) — r2 подтвердил 153/153 без диффов на cb68492c; резерв CI на 444562e4 («Переиспользование: это дерево уже проверено» → успех, «Golden-кадры» → skipped) подтверждает, что источник для golden не менялся с последнего полного прогона. Отдельно не перепрогонял: дельта r2→r3 не меняет settled-состояние (см. ниже про resize-preflight — эффект только во время активного жеста, до golden-снимка дело не доходит).
• Инварианты модели по всем моделям проекта — часть npm test (сам прогнал на HEAD, зелёный); конфиг-специфичная команда npm run invariants -- --config … не нужна отдельно: дельта не меняет персистентную форму (walls[], wall_segments, marker.space, open_spans) — только момент вызова validation-функции и типизацию сигнатур.
• INITIAL_VIEW_GZIP_CEILING 297000→298000 — обоснование и бюджет не тронуты этой дельтой (только bundle-budget.mjs логика из r1, файл не в диффе r2→r3).

Находки

M1 — не заявленный в ТЗ постоянный отказ от live-preflight на больших планах, противоречит собственному changelog (в скоупе, чинится в этой же задаче)

Файлы: src/resize-controller.ts:18-27 (resizeLivePreflightAllowed), src/houseplan-editor-runtime.ts:3653 (использование в _rszProjectPreview).

Фикс H3 (4b6b4abc) не просто вернул прежнее поведение — он расколол его по размеру плана. Для «bounded» контуров (суммарно ≤ 64 вершин комнат текущего пространства) во время resize-жеста работает тот же точный _checkSpacePhysicalGeometry(), что был до #451: невозможная геометрия сразу отклоняется, тост «последняя безопасная позиция» показывается посреди жеста. Для «больших» планов (> 64 вершин) эта проверка безусловно выключена во время жеста — живёт только дешёвая junction-limit проверка (углы/валентность), а точная геометрия проверяется один раз, на pointerup (это безопасно для данных — commit всё ещё fail-closed, я прочитал _commitPhysicalGeometry построчно, — но не для обратной связи пользователю).

Порог не абстрактный: фикстура demo/fixtures/large-house.mjs, на которой считается сам бюджет large-house-interaction-v1 (тот самый профиль, ради которого выключалась проверка), — это 20 прямоугольных комнат по 4 вершины = 80 вершин, то есть уже выше порога 64. А персона из ТЗ («администратор дома... средний или большой план», issue: «5 пространств... 8 комнат в текущем пространстве... средний по размеру план, не рекорд») — это ровно тот случай, для которого порог скорее всего будет превышен, если комнаты не прямоугольные (8 комнат × 8 вершин = 64, граница ровно на пороге).

Почему это находка, а не техническая деталь реализации:

1. ТЗ прямо запрещает это как область изменения. §5 Non-scope: «изменение hit areas, snap tolerance, grid, gesture thresholds, animation duration/easing, click/double-click/long-press или commit/cancel semantics» не входит в задачу. §2: «Преднамеренных визуальных изменений нет. После завершения любого жеста канонический итог и итоговый кадр совпадают с текущим поведением» — про итоговый кадр это верно (commit не изменился), но живая обратная связь во время жеста для больших планов теперь другая, и это не техническая деталь — это то, что видит пользователь. Ни §16 (риски), ни §18 (что можно менять свободно без владельца) не упоминают эту развилку.
2. Прямо противоречит changelog, который уже в ветке. docs/CHANGELOG.md/.ru.md (коммит c0d61ca3, до r1) заявляют: «interactions remain visually and functionally unchanged» / «внешний вид и результат действий не меняются». Для планов с > 64 вершин комнат в текущем пространстве это не так: раньше resize посреди жеста предупреждал о невозможной позиции, теперь — нет.
3. Ни в одном комментарии issue владелец этот компромисс не видел и не утверждал — я прочитал всю переписку (Аналитика, Вопросы для ТЗ, Решения владельца, оба «Исправления по CODE-REVIEW»): обсуждались Q1 (relevant HA update во время жеста) и Q2 (обычный hover), но не порог 64 и не деление resize-preflight по размеру плана.

Это Medium, не High: данные не портятся ни при каком сценарии (проверил код коммита, unconditional fail-closed check на pointerup), поэтому это не блокирующий баг, а нераскрытое изменение поведения вне заявленного скоупа задачи — ровно формулировка PROCESS.md «жёлтый вердикт допустим при выполненных AC, если изменение ухудшает смежный сценарий». Находка в скоупе (введена этой же веткой ради выполнения AC10) — чинится в этой же задаче, отдельный issue не заводится.

Что нужно от автора (не мой выбор, а перечисление опций для очередного цикла): либо восстановить живую точную проверку и для больших планов (тогда решать заново конфликт с AC10-бюджетом, из-за которого её и убрали в r1), либо получить у владельца явное решение принять этот компромисс и одновременно поправить формулировку changelog («без функциональных изменений» перестаёт быть верным для больших планов), либо найти более дешёвый способ живой проверки (например, только у затронутой комнаты вместо канонического union всего пространства — H1-r1 уже показал, что именно full clearance был дорогим, а не сам факт проверки).

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

• H1/H2/H3 из r2 закрыты — таблица выше, каждая проверена самостоятельно прогоном, а не с чужих слов.
• Регресс DOM resize_pointer.unrelated_pointer_ignored/capture_loss_restores_dom (пойман CI на a7bee0f5, не был отдельной находкой r2) закрыт 046efe96, подтверждено прогоном и CI.
• Commit-time geometry check (_commitPhysicalGeometry → _checkSpacePhysicalGeometry) остаётся безусловным независимо от размера плана — прочитано построчно, не зависит от M1.
• Типизация (fe03eae2) семантически эквивалентна прежнему any-коду — прочитал diff junction-limits.ts построчно (переход через промежуточный completeGeometry даёт тот же результат для 'ok'/'degraded-extra'/'lightweight'/null/undefined, что и старое тройное сравнение). live-editor.ts получил один дополнительный guard (!!room.id &&) — сужение, не расширение поведения, риска регрессии нет.
• Новый unit-тест resize-controller.test.mjs («#451 live resize preflight is bounded by authored contour complexity») проверяет именно границу (16×4=64 → true, 17×4=68 → false, один контур 65 → false) — тест способен падать (проверил через чтение реализации: убери <= на <, и 64 упадёт).
• no-new-any, check-docs, npm test, npm run build+bundle:sync (сверка бандла) — зелёные на точном HEAD, прогнано лично.
• Трейлеры Issue: #451 — присутствуют во всех коммитах дельты. User-Visible: no для 046efe96 и 444562e4 — точен (внутренний DOM-баг и обновление отпечатка, не новое поведение). Для 4b6b4abc трейлер тоже User-Visible: no — и вот это неточно ровно по причине M1.

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

• Полный npm run golden:verify — не гонял отдельно: дельта не меняет settled-состояние (эффект M1 виден только во время активного resize-жеста, до commit/settled-кадра), а CI на HEAD показал «Переиспользование: это дерево уже проверено» → golden job skipped легитимно (тот же tree-hash, что уже проверялся 153/153 в r2).
• Полный npm run benchmark:large-house-interaction — не перегонял: диапазон дельты не меняет веса editor-series (единственное затронутое ответвление — resize live-preflight, а он теперь для фикстуры large-house выключен тем же порогом 64 < 80, то есть числа бюджета из r2 (editor median 484.7 ms ≤ 750) по построению не изменятся от этой дельты — сам факт этого и есть часть находки M1: бюджет проходит именно потому, что фикстура выше порога).
• Оставшиеся 18 «прямых совпадений» smoke-select (декор/opening-смоки на _openingsR/NORM_W) — дельта в этих файлах чисто типовая (import type вместо value import, сигнатуры), не гонял отдельно; 25 «слабых» совпадений на _mode не гонял — типовой рефакторинг чужого для них кода.
• python -m pytest tests_backend — диф не трогает custom_components/**/*.py (проверено чтением git diff --name-only).
• npm run invariants -- --config <...> для конкретного конфига — не требуется отдельно (см. «Унаследовано», дельта не меняет персистентную геометрическую форму).
• Мутация для resizeLivePreflightAllowed — не заводил: функция чистая, покрыта unit-тестом на все три граничных случая, и мутационный тест не добавил бы нового при уже красном-способном юните.

Итог

Вердикт: жёлтый. High: 0, Medium: 1 (M1, в скоупе — возвращается автору, отдельный issue не заводится). H1–H3 из r2 закрыты корректно, дополнительный DOM-регресс закрыт корректно. Единственная находка этого раунда — не баг в данных, а нераскрытое и не согласованное с ТЗ/changelog изменение поведения resize-preflight для больших планов, появившееся как побочный эффект закрытия H3.

---

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

• Ветка: issue/451-render-performance, коммит 444562e47cb7 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 9489e0f2e24a6b4df6bd587703b2fa058ebb3a04

  git log --all --format='%H %T' | grep 9489e0f2e24a
  

• ТЗ docs/specs/451-render-performance.md, блоб 7c323a29110974aae369077214b9e2a74d9387c1

  git log --all --find-object=7c323a29110974aae369077214b9e2a74d9387c1 -- docs/specs/451-render-performance.md