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

SPEC-REVIEW-396-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/396
• ТЗ под ревью: docs/specs/396-camera-transition-fixes.md, коммит 4e0a30a78161a4ff59679454d1f8b5c471e10008 (HEAD ветки issue/396-camera-transition-fixes)
• Этап: spec (PROCESS.md §2.4)
• Трек: обычный (без метки small/trivial)
• Заход: r1 · блокирующих циклов ревью ТЗ израсходовано 0 из 4 (до этого вердикта)

Скоуп ревью

Issue #396 переносит три находки внешнего аудита (AUDIT-2026-08-31-v1700beta1.md, в репозитории не лежит — внешний документ, ссылка не проверяется) в одно ТЗ, поскольку все три касаются одной подсистемы (камера-переход из #82):

• B1 (High) — прерванный пользователем зум не сохраняется: регресс против v1.69.0;
• B2 (High) — якорь под курсором вычисляется от отстающего кадра при быстрой серии wheel-событий;
• M2 (Medium) — glow-feather не заморожен во время нового camera tween.

Ревьюер не видел устных пояснений автора; материал — только issue #396, ТЗ docs/specs/396-camera-transition-fixes.md и код на origin/dev/ветке задачи. Продуктового кода к этому изменению ещё нет (ветка содержит один doc-коммит), поэтому единственный вопрос ревью — проверить каждое фактическое утверждение ТЗ о поведении src/viewport-transition.ts и src/houseplan-card.ts построчно против реального кода, ровно так же, как это требует PROCESS.md §2.4 и прецедент SPEC-REVIEW-197-r1.

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

1. Прочитаны целиком docs/SCOPE.md, PROCESS.md (действующая редакция, §1, §2.4, §2.5, §2.10, §7.1, §7.2), AGENTS.md.
2. Прочитано тело issue #396 (единственный комментарий — сам текст issue, других комментариев нет).
3. Прочитан docs/specs/082-smooth-zoom.md целиком — канонический документ подсистемы, поскольку #396 правит его §10 и §13 (AC6).
4. Прочитан весь текст ТЗ docs/specs/396-camera-transition-fixes.md (206 строк), сверены обязательные разделы §7.1 PROCESS.md — присутствуют все: сценарий, что человек увидит до/после, проблема и контракты по пунктам, скоуп/не-скоуп, UX, модель данных и миграция, i18n, критерии приёмки AC1–AC7 (у каждого назван способ доказательства), план автотестов, риски, откат, release-артефакты, блок принятых технических предположений.
5. Построчно сверены все технические утверждения ТЗ с фактическим кодом:
   • src/viewport-transition.ts (212 строк) прочитан целиком — CameraTransitionController.cancel(commitTarget) (:189-200), dispose() (:202), _settle() (:204-211);
   • все вызовы _cancelCameraTransition(...) и _cameraTransition.cancel/dispose в src/houseplan-card.ts пересчитаны поимённо: grep -n "_cancelCameraTransition(false)\|_cancelCameraTransition(true)\|_cameraTransition\.\(cancel\|dispose\)" src/houseplan-card.ts;
   • каждый найденный вызов прочитан в контексте функции, которая его содержит (_onMotionChange, _startCameraTransition, _cancelModeTransition, _adoptMode, _commitSpace, _adoptStructuralResponses ×2, _applyView, _refitView, _zoomAt, _restoreZoom, _stagePointerDown, disconnectedCallback);
   • оба вызова _zoomAt(...) (:6517, :6897, внутри pinch-путей _stagePointerMove/_touchGesture...) прочитаны с окружением, чтобы проверить, действительно ли за ними сразу следует _saveZoom();
   • _cameraTargetAt (:6262-6279) и cameraTargetAtAnchor (viewport-transition.ts:94-116) прочитаны вместе, чтобы проверить claim B2 (мировая точка считается от this._cameraState(), то есть от представленного кадра, независимо от того, какой targetZoom передал вызывающий код);
   • resolveGlowFeather(...) вызов на :10845-10847 сверен с цитатой ТЗ (:10842-10847) — совпадает дословно.
6. Гейты (typecheck/test/build) не прогонялись — на этапе ревью ТЗ продуктового кода не существует (только doc-коммит), что вне скоупа этапа (PROCESS.md §2.4/§8).

Находки

High-1 — центральное фактическое утверждение B1 («семь мест») не совпадает с реальными вызовами и не покрывает главный сценарий issue

Файл: docs/specs/396-camera-transition-fixes.md, раздел «(1) B1 — прерванный зум не сохраняется» и раздел «Скоуп / не-скоуп».

ТЗ утверждает: «_cancelCameraTransition(false) зовут семь мест: :1267, :1401, :1551, :4188, :4216, :6089, :6206 — pointerdown по сцене, смена пространства, _refitView, adoption, reload, _zoomAt, disconnect.» (позиционное соответствие семи чисел семи описаниям в том же порядке).

Фактическая проверка (grep -n "_cancelCameraTransition(false)\|_cancelCameraTransition(true)\|_cameraTransition\.\(cancel\|dispose\)" src/houseplan-card.ts на HEAD ветки задачи) даёт десять мест с commitTarget=false плюс одно место, где котроллер отменяется напрямую, минуя обёртку:

Строка	Функция	Что это на самом деле
:1267	_startCameraTransition, no-op ветка (sameCameraState(current, target))	не «pointerdown», а ранний выход при запросе уже показанного состояния
:1401	_cancelModeTransition	общий helper для смены mode/space, не «смена пространства» отдельно
:1551	_commitSpace	это и есть настоящая «смена пространства» — но в списке ей приписана строка :1401
:4188	_adoptStructuralResponses (config adopt)	«adoption» — совпадает
:4216	_adoptStructuralResponses (layout adopt)	второе «adoption», в списке названо «reload»
:6089	_applyView	не «_zoomAt» — другая функция
:6206	_refitView	resize, не «disconnect»
:6283	_zoomAt (pinch, immediate)	отсутствует в списке семи
:6360	_restoreZoom	отсутствует в списке семи, не упомянута нигде в ТЗ
:6387	_stagePointerDown	отсутствует в списке семи — это и есть буквальный «pointerdown по сцене» из пользовательского сценария issue
:2745	disconnectedCallback	вызывает this._cameraTransition.dispose() напрямую, минуя _cancelCameraTransition — не через строку :6206, как подразумевает список

Т.е. ни одна из строк реального _stagePointerDown (:6387) и реального _zoomAt (:6283) не входит в перечисленные семь чисел, хотя проза ТЗ прямо называет «pointerdown по сцене» и «_zoomAt» в качестве двух из этих семи. Disconnect вообще не проходит через _cancelCameraTransition — там отдельный вызов .dispose() на :2745.

Проверено исполнением/чтением, что :6387 — это настоящий воспроизводящий сценарий из issue. _stagePointerDown (houseplan-card.ts:6386-6446) вызывает this._cancelCameraTransition(false) первой строкой и не содержит ни одного вызова _saveZoom() внутри себя или в путях, которые гарантированно выполняются после простого клика (не переросшего в pan/pinch). Ровно это — «колесо/кнопка «+» → сразу клик по плану» из раздела «Пользовательский сценарий» B1. Сопутствующая проверка: _zoomAt (:6283) технически тоже вызывает _cancelCameraTransition(false), но оба его реальных вызывающих контекста (:6517 — pinch move, :6897 — touch multitouch move) сразу же следом вызывают _saveZoom() — то есть через _zoomAt состояние фактически не теряется, вопреки тому, что список подписывает его как один из семи «теряющих» вызовов.

Почему это блокирует, а не опечатка в номерах строк. Раздел «Скоуп / не-скоуп» ТЗ перечисляет затронутые функции: «_startCameraTransition, _cameraTargetAt, _onWheel, _stepZoom, _cancelCameraTransition, glow-гейт» — и не называет _stagePointerDown ни разу. DoR (PROCESS.md §2.5) требует «перечислены затронутые файлы и модули» именно для того, чтобы разработчик не должен был заново открывать код в поисках места правки. Если разработчик читает этот список как объявление границы работы (а не как приглашение заново обыскать весь файл), правка _stagePointerDown не попадёт в реализацию — а именно там лежит буквальный баг из пользовательского сценария issue. Раздел «Риски» ТЗ («Тонкая грань «пользовательская против структурной»») сам ссылается на «список мест перечислен в спеке #82 §13» как на средство защиты от ошибки классификации — но источник (список из этого же ТЗ) неточен, то есть заявленная мера риска опирается на тот же дефектный список.

Смягчающее обстоятельство: план автотестов (шаг 5 browser smoke, «Колесо → pointerdown по плану до окончания перехода → перезагрузка карты → восстановленный зум равен показанному до клика (AC1 на реальном DOM)») сам по себе устроен так, что реализация, не тронувшая _stagePointerDown, эту проверку не пройдёт — то есть дефект будет пойман на код-ревью. Но это означает лишний цикл там, где спек-ревью для того и существует, чтобы поймать это раньше и дешевле (тот же аргумент, что в SPEC-REVIEW-197-r1 High-1: разработчик рискует чинить не тот код, опираясь на неверную фактическую базу раздела).

Что нужно поправить. В разделе «(1) B1» — заменить список из семи чисел на фактическую сверку (реальных мест десять плюс disconnectedCallback, использующий .dispose() напрямую), явно отметить, какие из них пользовательские (как минимум :6387), а какие структурные, и без двусмысленности показать, что _zoomAt (:6283/:6517/:6897) уже не теряет состояние благодаря существующему _saveZoom() сразу после — то есть не требует правки по контракту B1. В разделе «Скоуп / не-скоуп» — добавить _stagePointerDown в список затронутых функций (и, при необходимости, _restoreZoom, если ревью реализации решит, что он тоже нуждается в явной классификации).

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

• B1 — контракт и AC1/AC2 сформулированы верно, несмотря на дефектный список строк: CameraTransitionController.cancel(false) (viewport-transition.ts:189-200) действительно не вызывает _hooks.settled и, следовательно, никогда не проходит через _settleCameraTransition → _saveZoom() (houseplan-card.ts:1232-1244) — регресс реален и подтверждён чтением обоих файлов независимо от того, какие конкретно строки его проявляют. Различение «пользовательская отмена / структурная отмена» (таблица в разделе «(1)») продуктово согласовано с уже принятым §11 docs/specs/082-smooth-zoom.md («Pointerdown, который начинает pan, pinch, draw, drag или selection, сначала фиксирует представленный кадр и отменяет tween без скачка» — то есть #82 уже требовал этого поведения, #396 первым делает его явным контрактом с AC).
• B2 подтверждён чтением и математически обоснован. _cameraTargetAt (houseplan-card.ts:6262-6279) всегда строит якорь от this._cameraState() (:6273) — то есть от представленного, а не целевого кадра — независимо от того, что _onWheel (:6294-6308) уже правильно берёт baseZoom из this._cameraTransition.target?.zoom ?? this._zoom (:6301). Это ровно расхождение «масштаб — из target, точка — из presented», которое ТЗ описывает как корень утечки якоря. Контрактная формулировка («масштаб и мировая точка берутся из одного и того же состояния») корректно закрывает разрыв, а замечание про _zoomAt («там tween заведомо отменён, представленное и есть текущее») подтверждено: _zoomAt (:6282-6292) вызывает _cancelCameraTransition(false) первой строкой, поэтому к моменту вычисления якоря активного перехода уже нет и presented/target совпадают по определению.
• M2 подтверждён дословным совпадением цитаты. resolveGlowFeather(...) вызов на houseplan-card.ts:10845-10847 с третьим аргументом !this._pinchStart && !this._panStart совпадает с цитатой ТЗ буквально — признак «камера движется» не учитывает новый camera tween, только pinch/pan gesture state.
• Правка docs/specs/082-smooth-zoom.md §10/§13 обоснована. Прочитан документ целиком (386 строк): §10 п.3 действительно говорит «в представленном viewport», а порог ниже — «не более 0.5 CSS px», то есть спека #82 сама себе противоречит после реализации B2-бага (п.3 выполнен, порог нарушен) — формулировка AC6 «привести в соответствие» корректна и не требует продуктового решения владельца (чисто согласование текста с уже принятым поведенческим контрактом п.2 §10).
• Структура ТЗ и обязательные разделы (PROCESS.md §7.1) — все на месте, включая i18n («Новых строк нет» — верно, ни один из трёх контрактов не добавляет UI-текст), модель данных/миграция («формат LS_ZOOM не меняется» — верно, персист остаётся тем же ключом/структурой), touch (пункт «Немедленный _zoomAt (pinch) продолжает работать от представленного состояния» — корректно определяет границу с touch-контрактом), откат (точечный, три независимых правки, без миграции данных — согласуется с характером задачи).
• Трек. Обычный трек (не small) обоснован по факту: три независимых находки на одной подсистеме, правка канонического документа #82 — критерий §5 PROCESS.md («нет нового UX-контракта» технически спорен, но задача явно не «одна поверхность» и трогает канон #82, что само по себе исключение из лёгкого трека).
• Открытых продуктовых вопросов к владельцу не осталось и не должно остаться — единственный найденный пробел (High-1) технический (какие именно строки/функции меняются), а не продуктовый: ни «что видит пользователь», ни «объём видимых изменений в issue» здесь не решаются. Технический спор автора и ревьюера решается вердиктом, не владельцем (PROCESS.md §7.1).
• Мутанты названы конкретно (camera-anchor-from-presented, camera-cancel-loses-zoom, glow-feather-thaws-during-camera) и каждый указывает, какой юнит должен покраснеть — соответствует правилу «тест умеет падать» (PROCESS.md §2.7, применимо и к дизайну теста на этапе ТЗ).

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

• Код продукта не существует на этой стадии (только ТЗ) — гейты typecheck/test/build/check-docs/invariants/смоки/golden:verify неприменимы и не запускались; это нормально для этапа ТЗ, а не пропуск.
• Не проверял содержимое внешнего аудита AUDIT-2026-08-31-v1700beta1.md — файл не лежит в репозитории (только ссылка на него в теле issue), поэтому его точные измерения (14.5/16.1/10.3 px и т.п.) не перепроверялись инструментально; для ревью достаточно того, что оба бага (B1, B2) независимо подтверждены чтением реального кода на origin/dev.
• Не прогонял test-build/viewport-transition.js с фейковым клоком, на который ссылается ТЗ («переход 1.0 → 1.15 за 220 мс, обрыв на 120 мс → settled вызван 0 раз, presented.zoom = 1.1413») — подтвердил тот же вывод логическим чтением CameraTransitionController.cancel() (viewport-transition.ts:189-200: commitTarget=false выходит до вызова this._hooks.settled), числовое значение 1.1413 не пересчитывал.
• Не искал дополнительные вызовы _cancelCameraTransition/_cameraTransition.cancel за пределами src/houseplan-card.ts (например, в src/houseplan-editor-runtime.ts) — раздел «Скоуп» ТЗ ограничивает камеру ядром houseplan-card.ts, и grep -n "_cameraTransition\b" src/houseplan-editor-runtime.ts не выполнялся; при исправлении High-1 автору стоит перепроверить и этот файл на всякий случай, хотя #82 §19 явно оставляет бизнес-логику zoom в core.

Вердикт

Красный. High: 1 (B1 — список мест «_cancelCameraTransition(false)» фактически неверен и не включает _stagePointerDown/_zoomAt, а раздел «Скоуп» не называет _stagePointerDown как затрагиваемую функцию — риск, что буквальный пользовательский сценарий issue останется незачинённым). Medium: 0. Контракты B1/B2/M2 и AC1–AC7 по существу верны и не требуют продуктового решения владельца; правка текстовая — исправить раздел «(1) B1» и «Скоуп / не-скоуп» по фактической сверке выше, без изменения AC. После правки — повторный заход по дельте (PROCESS.md §2.10): проверить перечень мест и то, что _stagePointerDown явно назван местом правки, остальные разделы (B2/M2, AC3-AC7, риски §10/§13) наследуются без повторной проверки.

Вердикт: красный · заход r1 · блокирующих циклов 1/4 · High: 1 · Medium: 0 → в задаче · Документ: docs/reviews/SPEC-REVIEW-396-r1.md