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

CODE-REVIEW-396-r1

• Issue: #396 — «Плавная камера #82: прерванный зум не сохраняется, якорь уезжает, glow-feather не заморожен»
• Этап: код-ревью (PROCESS.md §2.7), заход r1, блокирующих циклов израсходовано 0/4
• SHA материала: c1b6a01bcd72508288d26c7713c60dbdfe42322f (origin/issue/396-camera-transition-fixes)
• База: origin/dev = 8955c02e3a120e60092547adaf62743c0b042c4a
• Вердикт: зелёный · High: 0 · Medium: 0

Методологическая находка перед разбором (не дефект кода)

Окружение изначально выдало детач-HEAD на 4e07e8ec — это вершина одного только спек-ревью (docs/reviews/SPEC-REVIEW-396-r{1,2,3}.md + docs/specs/396-camera-transition-fixes.md), без единой строки продуктового кода. git diff origin/dev...4e07e8ec показывал только 4 файла документации. Реальная реализация (4c057fa0 + c1b6a01b) уже существовала на origin/issue/396-camera-transition-fixes, но не была вытянута в рабочую копию к началу цикла. Переключился на неё (git checkout c1b6a01b) и разбирал именно это состояние — это и есть SHA материала выше. Отмечаю это явно, чтобы не потерялось: если бы вердикт подводился на исходном чекауте, «оно вообще работает» ответить было бы нечем.

Скоуп

Диапазон origin/dev...HEAD (6 коммитов): весь трек #396 — 3 раунда спек-ревью, коммит реализации 4c057fa0 (fix: the camera keeps the zoom you see and the point you hold) и c1b6a01b (build: refresh bundle trees and the doc capture). Продуктовый код: src/houseplan-card.ts (38 строк), тесты: test/viewport-transition.test.mjs (+93), test/golden-matrix.test.mjs (+9 к существующей проверке), scripts/mutation-gate.mjs (+3 мутанта), demo/smoke_smooth_zoom.mjs (+84). Спека docs/specs/082-smooth-zoom.md: только §10 и §13 (2 hunk'а, сверено git diff --stat/grep "^@@"). Changelog en/ru в том же коммите 4c057fa0 (User-Visible: yes).

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

Гейт	Статус	Результат
npx tsc --noEmit	прогнал	чисто, exit 0
npm test	прогнал	1650 pass / 0 fail / 1 skip (не связан с #396)
npm run build + сверка бандлов	прогнал	git status после билда чист — dist/, custom_components/houseplan/frontend, манифест уже в актуальном состоянии
node scripts/check-docs.mjs	прогнал (diff трогает src/**)	«Documentation checks passed (7 files, 10 external links)»
npm run golden:verify	прогнал (диф касается glow/рендера)	все кейсы passed, exit 0
Мутанты camera-cancel-loses-zoom, camera-anchor-from-presented, glow-feather-thaws-during-camera (node scripts/mutation-gate.mjs --id=…)	прогнал по одному	все три «тест покраснел, как обязан» (1/1 каждый)
node demo/smoke_smooth_zoom.mjs	прогнал	OK; interruptedShown==interruptedStored, structuralSaves=0, anchorDriftPx=0
node scripts/smoke-select.mjs --base origin/dev --head HEAD	прогнал	11 «прямых совпадений» — прогнал все 11 (список ниже)
npm run invariants	не прогонял	diff не трогает геометрию комнат/стен/layout/marker.space/open_spans — только камера и glow-feather гейт
python -m pytest tests_backend	не прогонял	diff не трогает custom_components/**/*.py
perf-профили (demo/performance/*)	не прогонял	AC5 не называет конкретный перф-профиль; закрыт иначе (см. AC5 ниже)

11 «прямых совпадений» smoke-select (по символам _cameraTransition, _cancelCameraTransition, _saveZoom, _panStart, _pinchStart), все прогнаны, все OK: smoke_smooth_zoom, smoke_long_press_gesture, smoke_canvas_frame, smoke_decor, smoke_editor_gestures, smoke_infinite_canvas, smoke_kiosk_pan_lock, smoke_kiosk, smoke_pan_any_zoom, smoke_warm_dialogs, smoke_zoom_out. Полную матрицу (208 смоков) не гонял — diff узкий, одномодульный, вне неё не задевает подсистем (пред-релизная обязанность, не гейт ревью).

Разбор по AC

AC1 (пользовательская отмена сохраняет показанное). _cancelCameraTransition(commitTarget=false, keepPresented=false) (src/houseplan-card.ts:1250) при keepPresented=true и активном переходе читает this._cameraTransition.presented?.zoom до cancel(), затем зовёт _saveZoom(). _saveZoom() читает this._zoom, который _applyCameraTransitionFrame (:1222) синхронно держит равным presented на каждом кадре — значит к моменту вызова он уже равен замороженному кадру, второй канал не нужен. Единственный вызывающий с keepPresented=true — _stagePointerDown (:6410), это и есть буквальный сценарий issue. Доказано и автотестом: смоук demo/smoke_smooth_zoom.mjs реальным DOM (колесо → pointerdown до конца перехода → interruptedShown === interruptedStored, interruptedFroze: true), и мутантом camera-cancel-loses-zoom (откат keepPresented на false красит смоук). Доказано автотестом, тест умеет падать.

AC2 (структурная отмена не пишет). Из 11 мест отмены + dispose() только _stagePointerDown передаёт keepPresented=true; прочитал каждое (:1280,1414,1564,2376,2758,4201,4229,6102,6219,6303,6381) — классификация таблицы ТЗ подтверждена построчно, ни одно структурное место не получило второй аргумент. _zoomAt (:6303, немедленный pinch) не тронут, оба его вызывающих контекста (:6540, :6920) сами зовут _saveZoom() сразу после — поведение как до фикса. Смоук: structuralSaves === 0 после card._cancelCameraTransition(false) на середине перехода. Мутант camera-cancel-loses-zoom также покрывает обратную сторону (без него пользовательская ветка становится структурной — тест красится). Доказано автотестом + построчной сверкой кода.

AC3 (якорь точен на серии из шести нотчей, 8/16/33 мс). _cameraTargetAt(..., animated) (:6275) при animated=true и активном переходе берёт anchorFrom = this._cameraTransition.target — ту же цель, от которой в _onWheel (:6320) накапливается baseZoom. Юнит (test/viewport-transition.test.mjs:179) гоняет серию из 6 нотчей на 8/16/33 мс через реальный CameraTransitionController с фейковым клоком и проверяет дрейф мировой точки < 1e-9; тот же тест отдельно доказывает, что версия «от отстающего кадра» дрейфует >1 — то есть baseline дефекта воспроизведён, а не выдуман. Смоук подтверждает то же через реальный DOM: anchorDriftPx: 0. Мутант camera-anchor-from-presented (откат на false && …) красит и юнит, и смоук. Доказано автотестом, тест умеет падать (сам ассерт на дефект — прямое доказательство).

AC4 (накопление zoom не тронуто). Тот же юнит-файл, тест «AC4»: для обеих веток (anchorFromTarget: true/false) итоговый zoom после 6 нотчей равен 1.15**6 с точностью 1e-12 — фикс якоря математику не меняет, что и требовалось. baseZoom = this._cameraTransition.target?.zoom ?? this._zoom в _onWheel не редактировался этим диффом (только добавлен true в вызов _cameraTargetAt). Доказано автотестом.

AC5 (feather заморожен во время анимированного перехода). cameraStill = !this._pinchStart && !this._panStart && !this._cameraTransition.active (:10869-10871), передаётся в resolveGlowFeather. Прочитан весь путь: _cameraTransition.active — геттер контроллера, true строго на время phase==='running', false на settling/null — то есть ровно на кадрах анимированного перехода предикат cameraStill даёт false, feather не пересобирается; в момент _settleCameraTransition active уже false, предикат совпадает с допереходным поведением — визуальный результат в покое не меняется (подтверждено ниже: imageSha256 в docs/images/screenshots.json не изменился, поменялся только sourceSha256). Прямого счётчика вызовов за время анимации в тестах нет — вместо этого test/golden-matrix.test.mjs регэксом закрепляет и сам предикат, и место его использования, и мутант glow-feather-thaws-during-camera (откат на && true) красит этот тест. Проверено чтением кода + автотест на форму предиката (не на счётчик вызовов за прогон — план автотестов ТЗ называл отдельный perf-контракт demo/performance/*, который не добавлен; см. «Не в скоупе гейтов» ниже). AC по существу закрыт, но доказательство слабее, чем обещал план — это не блокирует: source-guard плюс мутант ловят именно тот регресс, который описывает AC5 (два флага жеста вместо признака движения камеры).

AC6 (§10/§13 правлены точечно). git diff origin/dev...HEAD -- docs/specs/082-smooth-zoom.md даёт ровно 2 hunk'а (169 и 224 строка исходного файла) — §10 п.3 и порог точности, §13 список видов отмены. Остальной текст спеки не тронут. Текст обоих правленных мест прочитан — соответствует контракту из ТЗ #396 дословно (anchor из целевого viewport, 1e-9 вместо «≤0.5px»; два вида отмены с перечнем мест). Проверено чтением, диф точечный.

AC7 (регресс не возвращается). _startCameraTransition и CameraTransitionController.start() этим диффом не редактировались (только добавлен параметр animated дальше по цепочке в _cameraTargetAt/_onWheel/ _stepZoom) — путь duration<=0 → phase='settling' без RAF цел. dispose() (:2758) по-прежнему зовёт this._cameraTransition.cancel(false) напрямую, RAF снимается в cancel(). npm test (1650/1650) включает существующие тесты на reduced-motion/RAF/config-leak — все зелёные, регрессии нет. Проверено чтением + полный набор существующих юнитов зелёный.

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

• Классификация 11 мест отмены + dispose() из ТЗ (ревизия 3, принята зелёным SPEC-REVIEW-396-r3) совпадает с кодом один-в-один — сверено построчно, не только по номерам, но и по имени функции на каждой строке.
• Единый источник числа: бейдж ${Math.round(this._zoom * 100)}% (:11571) и _saveZoom() читают одно и то же поле this._zoom — второго канала для показанного/сохранённого масштаба нет, test/single-source-numbers.test.mjs проходит (механическая часть контракта), смысловая проверена явно здесь.
• Changelog ru/en обновлены в том же коммите 4c057fa0, где User-Visible: yes; трейлеры Issue:/User-Visible: на обоих коммитах диапазона корректны. Билд-коммит c1b6a01b идёт User-Visible: no — верно, это только синхронизация бандлов и отпечатка скриншотов.
• docs/images/screenshots.json: изменился только sourceSha256 (отпечаток по src/** неизбежно съезжает), imageSha256 во всех записях не тронут — визуал в статике действительно идентичен, check-docs.mjs и golden:verify это подтверждают независимо.
• Риски из ТЗ («двойная запись», «грань пользовательская/структурная», «якорь трогает pinch») все адресованы: _zoomAt не редактировался и сохранил старое поведение, идемпотентность записи не проверялась отдельным счётчиком двойной записи, но смоук считает saveCount и не показывает лишних записей на пользовательской ветке.

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

• npm run invariants — diff не касается рёбер комнат, записей толщины, layout, marker.space, open_spans; только камера/zoom/glow-feather.
• python -m pytest tests_backend — ни один .py-файл не в диффе.
• Полная матрица браузерных смоков (208 шт.) — прогнал только 11 «прямых совпадений» из smoke-select; «зарегистрированных связей» и «неопределённостей» инструмент для этого диффа не напечатал (список выше — полный вывод, ничего не отфильтровано).
• Отдельный perf-профиль на число пересборок feather за один анимированный зум (план автотестов ТЗ, п.7) — не создан автором; AC5 закрыт иначе (см. разбор выше). Это расхождение с планом автотестов, а не с AC — не поднимаю как находку уровня Low/Medium, поскольку фактическое покрытие (source-guard + мутант, оба проверены на способность падать) отвечает на тот же вопрос, что должен был отвечать перф-профиль.
• test/camera-persistence.test.mjs, названный в плане автотестов ТЗ, не создан — вместо него AC1/AC2 доказаны браузерным смоуком на реальном HouseplanCard (сильнее, чем юнит на голом контроллере, который план и предполагал). Не поднимаю как находку по той же причине.
• docs/DEVELOPMENT.md не тронут: различение «пользовательская/структурная отмена» нигде не записано как готча за пределами кода/спеки. Прецедента для камеры/#82 в этом файле тоже нет (проверено — файл вообще не упоминает camera/zoom/transition), так что это не отклонение от практики подсистемы. Low, waived: причина в тексте выше, комментарий в коде (:1241) и §13 спеки выполняют ту же функцию для следующего разработчика.

Находки

Нет High. Нет Medium (ни в скоупе, ни вне скоупа). Два Low выше — по существу waived с объяснением, не требуют возврата автору.

Вывод

Все 7 AC закрыты: пять — автотестом с проверенной способностью падать (мутанты camera-cancel-loses-zoom, camera-anchor-from-presented, glow-feather-thaws-during-camera все reddened; юниты и смоук воспроизводят и baseline-дефект, и его фикс), два — чтением кода при неизменном покрывающем тестовом наборе. Полный локальный гейт (tsc, 1650 юнитов, build+bundle sync, check-docs, golden:verify, целевые смоуки) зелёный на SHA c1b6a01b. Спека #82 приведена в соответствие точечно, changelog и трейлеры на месте. Возврата в разработку не требуется.