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

CODE-REVIEW-521-r1

Issue: #521 «fix: alignment guides follow the live gesture again» Материал ревью: 0715321fdc69a2955d7850f3f384c1a0fdc25311 (ветка issue/521-align-guides-live, HEAD == origin/dev + 2 коммита: 53585b45 продукт, 0715321f отпечаток скриншотов). Заход: r1 · блокирующих циклов израсходовано 0 из 4.

Скоуп

Регресс #451 (перевод жестов редактора на «живой» путь) убрал направляющие выравнивания из трёх жестов десктопных редакторов (значок в devices, фигура в decor, курсор в plan). Задача восстанавливает слой направляющих в живом пути и чинит вторую поломку — _alignPoint в режиме devices читал замороженный _pos вместо живого _livePos. Класс A, полный трек (владелец назвал нарушенный критерий §5 — влияние на touch/перф-контракт кадра жеста). Диф продукта: src/live-editor.ts (+19/−4), src/houseplan-card.ts (+4/−3). Плюс: 4 новых мутанта (scripts/mutation-gate.mjs), тест-линт свидетеля (test/smoke-harness-contract.test.mjs), полностью переписанный demo/smoke_align_guides.mjs, оба changelog, пересобранный бандл, второй коммит — обновление отпечатка скриншотов документации (docs:accept --identical, картинки побайтово не изменились).

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

Ревью прочитан по коду и прогнан руками — часть независимо от заявлений автора, часть с воспроизведением находок. Дешёвые гейты (tsc, test, build+сверка бандла) уже зелёные на этом SHA в Validate (https://github.com/Matysh/houseplan-card/actions/runs/34520976425) — не перегонял их ради самого факта зелени, но npm test и локальную сборку всё же выполнил повторно, поскольку без свежего demo/srv/assets/houseplan-card.js (не коммитится, #255) браузерные смоки было не запустить.

Гейт	Прогнал	Результат
npx tsc --noEmit	да (часть npm run build)	чисто
npm test	да	2515 pass / 0 fail / 1 skip
npm run build + сверка dist / custom_components/.../frontend / demo/srv/assets	да	побайтово идентичны рабочему дереву, git status чист после сборки
node scripts/no-new-any.mjs --base origin/dev --head HEAD	да	новых any нет (25 добавленных строк в 2 файлах)
node scripts/check-docs.mjs	да	зелёный (диф трогает src/**)
node scripts/smoke-select.mjs --base origin/dev --head HEAD	да	11 прямых совпадений (_pos, _livePos, _editorRuntime, _editorRuntimeOrThrow) + 22 слабые связи
Прямые смоки (align_guides, cover_no_plate, cover_plate_precedence, device_position_history, drag_bounds, edge_cases, glow, grid_snap, light_badges, modes, v8_draft_write)	да, все 11	зелёные
Точечно из «слабых»/AC-рисков (editor_gestures, decor, merge_split)	да	зелёные
node scripts/mutation-gate.mjs --check (применимость патчей)	да	все мутанты, включая 4 новых задачи, применимы
Мутанты задачи по одному (live-editor-devices-drops-align-guides, live-editor-decor-drops-align-guides, live-editor-plan-drops-align-guides, align-point-reads-frozen-snapshot)	да, все 4, полный прогон через scripts/mutation-gate.mjs --id=… (git worktree, пересборка, смок)	все 4 «поймано 1 из 1» — свидетель действительно краснеет
node --test test/smoke-harness-contract.test.mjs	да	7/7, включая новый тест-линт #521
AC9: npm run benchmark:large-house-interaction (7 образцов) + benchmark:compare против budgets-large-house-interaction.json	да, самостоятельно — база собрана в отдельном worktree на fa7ac02c (= origin/dev, тот же SHA, что назвал автор)	все метрики ✅, в частности timing.interactionSeriesMs.median 3175.4/3300, timing.editorSeriesMs.median 612.1/750, longTask.maxSingleMs 1184/1618.5 — без регрессии к базе
Собственный эксперимент: пришить обратно старое условие (makeTransparent только в ветке plan, т.е. без правки контракта №3) в изолированный git worktree, пересобрать, прогнать сам demo/smoke_align_guides.mjs	да	смок остался зелёным — см. находку Medium-1
golden, pytest tests_backend, полный набор смоков	нет	не требуются диффом (визуал не менялся кроме отпечатка, бэкенд не тронут); полный набор — предрелизный гейт

Не прогонял намеренно: golden:verify (диф не меняет пиксели вне подтверждённого identical-принятия), pytest tests_backend (Python не тронут), полную матрицу смоков (239 штук — не требуется диффом), WSL/HA-харнесс.

Находки

Medium-1 (в скоупе) — AC5 заявляет доказательство, которого смок не даёт

AC5: «Во время жеста в DOM ровно одна группа .alignguides»; «чем краснеет»: «снятие подавления осевого слоя даёт 2 — смок красный» (docs/reviews таблица AC, тело issue).

Это не так. Правка вынесла makeTransparent(state, root, '.hp-editor-only-layer:not(.hp-plan-snap-layer)') (src/live-editor.ts:358) из ветки if (host._mode === 'plan') в безусловное начало paintHouseplanEditor — то есть теперь осевая копия слоя гасится в любом режиме редактора, а раньше гасилась только в plan. Это разумная защита ровно от риска, названного в самом ТЗ («Двойной слой… если во время жеста случится осевая отрисовка»). Но проверил экспериментально: в отдельном git worktree (не в материале ревью) вернул эту строку внутрь if (host._mode === 'plan') { … }, как было до задачи, пересобрал бандл и прогнал сам переписанный demo/smoke_align_guides.mjs — все 26 полей вывода, включая devSingleGuideLayer, decorSingleGuideLayer, planSingleGuideLayer, остались true, смок напечатал OK.

Причина: _renderAlignGuides() в осевшей сцене (houseplan-card.ts:11698-11699) рисует .alignguides только когда _alignPoint не null; на момент последней осевой отрисовки перед стартом жеста (pointerdown, до которого _deviceDrag.moved/_decorDraft/_cursorPt ещё не в «жестовом» состоянии) эта группа пуста, и других осевых перерисовок в ходе самого смока не происходит — весь жест идёт по живому пути. Значит замороженная копия все время остаётся пустой независимо от того, подавлена она opacity:0 или нет, и groups() === 1 истинно в обоих случаях. Сценарий, который правка реально защищает (осевая отрисовка посреди жеста — приход hass, ступенька _hdrH, resize), смок не воспроизводит: он не форсирует ни одного стороннего requestUpdate() во время движений.

Проверил дальше (форсированный пробник в том же выброшенном worktree, не в материале): если во время шагов перетаскивания значка искусственно вызвать c.requestUpdate('_holdFired') (несвязанное реактивное свойство, эмулирует внешний settled-рендер), эксперимент завис на превышении времени Playwright — то есть даже принудительно вызвать вторую осевую отрисовку внутри активного жеста в текущей демо-обвязке не тривиально; я не довёл этот путь до результата и не настаиваю на нём как на предмете находки. Находка не в том, что защита не работает, а в том, что заявленное в AC5 доказательство ложно: третий столбец «чем краснеет» называет мутацию, которая, как показано выше, смок не ловит. Это ровно тот случай, о котором PROCESS.md §2.7 предупреждает отдельно: «пустой третий столбец — находка Medium»; здесь столбец не пуст, но недостоверен, что не лучше.

Почему Medium, а не High: сама защита в продукте существует и концептуально верна (единственный явный визуальный риск — задвоенная линия у пользователя, а не потеря данных/некорректная запись), просто не имеет свидетеля, который её удержит. Регрессия по этой строке не сломает ни один существующий тест.

Как чинить в скоупе задачи (предложение, не обязывающее автора): заставить смок форсировать осевую отрисовку в момент активного жеста — например, c.requestUpdate('_someUnrelatedSettledProp') (свойство вне liveProperties/hoverProperties/gestureProperties) на одном шаге каждого из трёх сценариев, с проверкой groups() === 1 сразу после, — либо честно понизить формулировку AC5 до «проверено чтением», раз механизм осознанно защищает окно, которое смок не воспроизводит. Второе дешевле; выбор — за автором.

Наблюдение (не находка, для полноты) — AC6 тоже без мутанта

Как и AC5, AC6 («один расчёт кандидатов на кадр») не имеет отдельной записи в scripts/mutation-gate.mjs, только проверку внутри самого смока (candidatesAreComputedOncePerFrame). В отличие от AC5, логика проверки (candidateCalls <= paints, где пять pointermove шлются без ожидания между собой) структурно способна поймать регрессию «расчёт на событие вместо кадра» — каждое лишнее срабатывание _alignCandidates() вне кадра подняло бы candidateCalls выше paints. Не воспроизводил такую мутацию отдельно (не нашёл дешёвого точечного способа сместить расчёт в обработчик события без более широкой правки); оставляю как «проверено чтением», не как находку.

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

• AC1–AC4 (направляющая в трёх живых жестах). Проверено смоком плюс четырьмя мутантами — каждый мутант независимо пересобран и прогнан, каждый дал красный смок («поймано 1 из 1»). Свидетель ведёт настоящие PointerEvent/click, ждёт тишины _hdrH перед жестом, считает осевые циклы за движения (обязаны быть 0) — воспроизвёл сам, наблюдения совпадают с заявленными в issue числами (8 шагов сетки расхождения _pos/_livePos).
• AC2 (живая точка выравнивания). _alignPoint в режиме devices читает _livePos(d) (houseplan-card.ts:12896); _livePos читает this._layout напрямую, минуя снимок _renderDeviceSnapshot, который использует _pos. Мутант align-point-reads-frozen-snapshot подтверждает регрессию при откате к _pos.
• AC5 (частично) — сама защита существует в коде и корректно расширена на все три режима; не хватает свидетеля (Medium-1 выше).
• AC6 — структура рендера гарантирует один расчёт на кадр: editorTemplate вызывается один раз за paintHouseplanEditor, который сам собран в один вызов на requestAnimationFrame через scheduleHouseplanEditor (гейт state.raf не даёт повторной постановки в очередь). Проверено чтением (src/live-editor.ts:344-391) и смоком (candidatesAreComputedOncePerFrame = true при собственном прогоне).
• AC7 (старые гарантии: нет гидов в Просмотре, нет гидов без совпадения, #400-исключение перетаскиваемого маркера). Все три сохранены и переведены на настоящий жест без прежней подмены состояния; проверено собственным прогоном смока (noneInView, devNoGuideOffAxis, devCandidatesExcludeTheDraggedMarker, devGuideAnchorIsTheOtherMarker).
• AC8 (свидетель не фабрикует состояние жеста). test/smoke-harness-contract.test.mjs регекспом проверяет отсутствие _deviceDrag =/_decorDraft = в demo/smoke_align_guides.mjs — прогнал node --test на этом файле, 7/7, включая новый тест; вручную проверил grep — присваиваний в файле действительно нет, только чтение (!!c._deviceDrag и т. п.).
• AC9 (перф). Перепрогнал независимо от автора: своя база на fa7ac02c (голова origin/dev, тот же SHA, что назвал автор) в отдельном git worktree, свой кандидат на материале ревью, benchmark:compare — весь отчёт зелёный, ни одна строка не читает красным. Числа близки к тем, что привёл автор в хендоффе (расхождение в пределах шума прогона).
• _renderAlignGuides стал «мягким» (this._editorRuntime?._renderAlignGuides() ?? nothing, было _editorRuntimeOrThrow()). Проверено чтением: _editing (единственный вызывающий контекст осевого пути) истинен только когда _mode уже plan/devices/decor, а вход в эти режимы уже требует загруженного _editorRuntime — так что смягчение не маскирует реальную ошибку на осевом пути, а покрывает только окно живого жеста, начавшегося до полной загрузки рантайма (контракт, пункт 5).
• Трейлеры и changelog. Оба коммита несут Issue: #521 и корректный User-Visible; User-Visible: yes коммит (53585b45) правит оба changelog в этом же коммите (проверено git show --stat).
• Отпечаток скриншотов (0715321f) — принят через docs:accept --identical, все 11 кадров побайтово совпали (imageSha256 не изменились), поэтому не требует ручной визуальной приёмки владельца; коммит только меняет sourceFingerprint/sourceSha256.
• Бандл. Пересобрал с нуля из материала — dist/, custom_components/houseplan/frontend/, demo/srv/assets/ совпали с закоммиченными файлами побайтово (git status чист после сборки).
• Класс изменений и трек. Класс A по прямому указанию владельца (комментарий в issue), полный трек с названным нарушенным критерием §5 — соответствует ТЗ и его зелёному ревью r3.

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

• npm run golden:verify — диф не меняет видимую геометрию/стили сцены за пределами уже принятого identical-скриншота; не увидел оснований гонять.
• python -m pytest tests_backend — custom_components/**/*.py не затронут.
• Полный набор из 239 смоков — не обосновано диффом (2 изменённых файла, 7 символов на изменённых строках); прогнал 11 прямых совпадений плюс три из широкого списка, относящихся к жестам редактора.
• WSL/полный HA-харнесс — вне гейта код-ревью.
• Не довёл до конца эксперимент с принудительным осевым рендером посреди живого жеста (см. Medium-1) — не нашёл дешёвого способа в текущей демо- обвязке и не стал тратить на это больше бюджета раунда; сама находка не зависит от результата этого эксперимента.

Вердикт

Единственная находка — Medium в скоупе задачи (недостоверное доказательство AC5, не сама защита). High-находок нет. По правилу PROCESS.md §2.7 это жёлтый вердикт с возвратом автору для правки в этой же задаче.

Вердикт: жёлтый · заход r1 · блокирующих циклов 1/4 · High: 0 · Medium: 1 → в задаче

Документ: docs/reviews/CODE-REVIEW-521-r1.md

---

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

• Ветка: issue/521-align-guides-live, коммит 0715321fdc69 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: d8bf0a0fe057a7b6d2470eb288b88850c51d5a24

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

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