houseplan-card/docs/specs/396-camera-transition-fixes.md

# ТЗ #396 — Плавная камера: сохранение прерванного зума, честный якорь, заморозка feather

- Issue: https://github.com/Matysh/houseplan-card/issues/396
- Приоритет: P1, bug (регресс против v1.69.0); полный трек — класс A, три
  находки на одной поверхности (камера), плюс правка формулировок принятой
  спеки #82 (`docs/specs/082-smooth-zoom.md` §10, §13)
- Ревизия: 3 (2026-08-31) — по SPEC-REVIEW-396-r2 (Medium-1: имена функций в таблице)

## Сценарий

Хозяин дома смотрит план на планшете. Крутит колесо (или жмёт «+»), чтобы
разглядеть кухню, и сразу тыкает в лампу — не дожидаясь, пока картинка доедет.
Через минуту уходит на второй этаж и возвращается: масштаб откатился к тому,
что был до зума. Второй случай — трекпад: быстрая серия нотчей уводит из-под
пальца ровно ту точку, которую он держал.

## Что человек увидит до и после

**До**: (1) зум, прерванный любым касанием плана, не запоминается — при
возврате на пространство карта показывает старый масштаб; (2) при быстром зуме
трекпадом точка под курсором уезжает на 10–16 px; (3) во время плавного зума
свечение пересобирает размытие на каждом кадре.
**После**: показанный масштаб и есть сохранённый; точка под курсором стоит на
месте при любой частоте событий; свечение во время движения камеры ведёт себя
как при pinch/pan.

## Проблема и контракты по пунктам

### (1) B1 — прерванный зум не сохраняется

`_saveZoom()` на пути перехода вызывается ровно из `_settleCameraTransition`
(`src/houseplan-card.ts:1237`). До перехода на анимацию запись делали сами
команды: `_onWheel`, `_stepZoom`, `_resetZoom` (`v1.69.0:6009,6016,6030`).
`CameraTransitionController.cancel(false)` (`src/viewport-transition.ts:189`)
`settled` не вызывает, поэтому показанный масштаб остаётся незаписанным.

Полный перечень мест, где переход отменяется, и их классификация (сверено
`grep`'ом по `src/houseplan-card.ts` на HEAD, каждое прочитано):

| Место | Что это | Класс |
|---|---|---|
| `:6387` `_stagePointerDown` | **буквальный сценарий issue**: касание плана поверх собственного зума | **пользовательская — сохранять** |
| `:6283` `_zoomAt` | немедленный pinch | правки не требует: оба вызывающих контекста сразу зовут `_saveZoom()` |
| `:1267` `_startCameraTransition` | цель совпала с текущим состоянием (no-op) | сохранять нечего — зум уже равен сохранённому |
| `:1159` `_onMotionChange`, `:2363` `_pageVisibility` | `cancel(true)`, цель коммитится | уже сохраняется через `settled` |
| `:1401` `_cancelModeTransition` | смена режима | структурная |
| `:1551` `_commitSpace` | смена пространства | структурная |
| `:4188`, `:4216` `_adoptStructuralResponses` | adoption конфига и layout | структурная |
| `:6089` `_applyView` | программная установка вида | структурная |
| `:6206` resize-обработчик | новая геометрия сцены | структурная |
| `:6360` `_restoreZoom` | восстановление сохранённого зума | структурная (пишет то, что и читает) |
| `:2745` `_cameraTransition.dispose()` | `disconnectedCallback`, минуя обёртку | структурная |

Правка нужна ровно в одном месте пользовательского класса (`:6387`) плюс сам
механизм различения; остальные строки перечислены, чтобы граница была явной и
следующая правка не расширила её молча.

Воспроизведение (исполнением, фейковый клок): переход 1.0 → 1.15 за 220 мс,
обрыв на 120 мс → `settled` вызван 0 раз, `presented.zoom = 1.1413`.

**Корень — в спеке #82, а не только в коде.** §13 говорит «structural
cancellation не сохраняет stale camera target», §11 — «pointerdown … фиксирует
представленный кадр». Спека не различает два случая отмены, а они разные:

| Вид отмены | Что на экране | Что сохранять |
|---|---|---|
| **Пользовательская**: pointerdown по сцене, начало pan/pinch/draw/drag/selection поверх собственного зума | представленный кадр фиксируется и остаётся видимым | **сохранять представленное** — оно и есть текущее намерение |
| **Структурная**: смена пространства/режима/проекции, resize, adoption конфига или layout, continuity recovery, viewport restore, disconnect | вид заменяется целиком другим контрактом | не сохранять ничего: цель устарела вместе с видом |

Контракт: **сохранённый зум пространства равен показанному после любой
пользовательской отмены**. Структурная отмена по-прежнему не пишет ничего.

Требуется правка `docs/specs/082-smooth-zoom.md` §13: разделить два вида
отмены явно, вместо одной строки про «stale target».

### (2) B2 — якорь считается от отстающего кадра

`_cameraTargetAt` (`src/houseplan-card.ts:6272`) передаёт в
`cameraTargetAtAnchor` состояние `this._cameraState()` — представленный кадр.
Пока tween не доиграл, он отстаёт от цели, и мировая точка под курсором
вычисляется в другом viewport, чем тот, к которому строится новая цель.

Замер (6 нотчей шагом 1.15, сравнение «якорь от presented» против «якорь от
целевого состояния»):

| интервал | смещение точки под курсором |
|---|---|
| 8 мс | 14,5 px |
| 16 мс | 16,1 px |
| 33 мс | 10,3 px |
| 220 мс | 0,0 px |

Спека #82 §10 при этом требует обе несовместимые вещи сразу: п.3 — «world-point
… в представленном viewport», абзац ниже — «anchor остаётся на месте с ошибкой
не более 0.5 CSS px». Реализация выполнила п.3 и нарушила AC.

Контракт: **масштаб и мировая точка берутся из одного и того же состояния —
цели текущего перехода** (при её отсутствии — из представленного, оно же
текущее). Это ровно принцип §10 п.2, распространённый на якорь. Ошибка якоря
без clamp — **0 px** (точное равенство мировой точки до плавающей погрешности
1e-9), а не «не более 0.5».

Требуется правка `docs/specs/082-smooth-zoom.md` §10: п.3 переформулировать на
«в целевом viewport running tween», порог заменить на точное равенство.

Немедленный `_zoomAt` (pinch) продолжает работать от представленного состояния:
там tween заведомо отменён, представленное и есть текущее.

### (3) M2 — feather не заморожен во время перехода

`src/houseplan-card.ts:10842-10847`: `resolveGlowFeather(…, !this._pinchStart &&
!this._panStart)`. Признак «камера движется» подменён признаками жеста, а новый
tween ни одного из них не выставляет: `perUnit` меняется каждый кадр, регион
размытия пересобирается на каждом.

Контракт: feather заморожен, **пока камера движется любым способом** — pinch,
pan или анимированный переход.

## Скоуп / не-скоуп

**В скоупе**: `src/viewport-transition.ts`, камера-путь `src/houseplan-card.ts`
(`_startCameraTransition`, `_cameraTargetAt`, `_onWheel`, `_stepZoom`,
`_cancelCameraTransition`, **`_stagePointerDown`**, glow-гейт), правка §10 и §13
в `docs/specs/082-smooth-zoom.md`, тесты и мутанты.

**Не в скоупе**: поведение pinch/pan persistence (свой контракт, §13 #82),
длительности и кривые анимации, kiosk double-tap, изменение формата `LS_ZOOM`,
editor zoom (не персистится по решению #82).

## UX

Видимых изменений в оформлении нет. Меняется только то, что показанный
масштаб сохраняется, а точка под курсором не уезжает.

## Модель данных и миграция

Формат `LS_ZOOM` и warm viewport memo не меняются. Миграции нет.

## i18n

Новых строк нет.

## Критерии приёмки

- **AC1**. После пользовательской отмены перехода (`_stagePointerDown` —
  касание плана, с которого начинается pan/pinch/draw/drag/selection)
  сохранённый зум пространства равен показанному на момент отмены.
  Доказательство: юнит на контроллер + карту, сравнение сохранённого значения
  с `presented`.
- **AC2**. Структурная отмена (смена пространства/режима, `_applyView`,
  resize, adoption, `_restoreZoom`, disconnect — строки таблицы выше) не
  записывает зум вовсе. Доказательство: тот же юнит, обратный случай —
  счётчик записей не растёт. Отдельно: `_zoomAt` (pinch) остаётся без
  изменений и продолжает сохранять через вызывающий контекст.
- **AC3**. Серия из шести wheel-событий с интервалом 8 мс оставляет мировую
  точку под курсором на месте с точностью 1e-9 единиц плана (без clamp).
  Доказательство: юнит с фейковым клоком; при clamp смещение допускается
  только по ограниченной оси.
- **AC4**. Накопление масштаба в серии не меняется: шесть нотчей дают тот же
  итоговый зум, что и сегодня (1.15⁶ с точностью 1e-12) — фикс якоря не
  трогает арифметику масштаба.
- **AC5**. Во время анимированного перехода `resolveGlowFeather` вызывается с
  замороженным признаком: число пересборок региона размытия за один зум не
  больше, чем на pinch-пути.
- **AC6**. `docs/specs/082-smooth-zoom.md` §10 и §13 приведены в соответствие
  с реализуемым поведением; ни один другой параграф не меняется.
- **AC7**. Регресс не возвращается: reduced-motion по-прежнему даёт ноль
  запросов rAF и точный таргет, `dispose()` снимает rAF, анимационное
  состояние не попадает в конфиг.

## План автотестов

**Unit** (`test/viewport-transition.test.mjs`, `test/camera-persistence.test.mjs`):

1. `cancel(false)` после частичного перехода → хук сохранения вызван с
   представленным состоянием (AC1); структурная отмена → не вызван (AC2).
2. Серия из шести нотчей с интервалом 8/16/33 мс → мировая точка под курсором
   неизменна до 1e-9 (AC3), итоговый зум равен 1.15⁶ (AC4).
3. Clamp у границы: смещение только по ограниченной оси, вторая ось точна.
4. `reducedMotion` → 0 rAF, один кадр, точный таргет (AC7).

**Browser smoke** (`demo/smoke_smooth_zoom.mjs`, дополнение):

5. Колесо → pointerdown по плану до окончания перехода → перезагрузка карты →
   восстановленный зум равен показанному до клика (AC1 на реальном DOM).
6. Смена пространства во время перехода → в `localStorage` для исходного
   пространства осталось прежнее значение (AC2).

**Perf-контракт** (`demo/performance/*`):

7. Число вызовов пересборки feather за один анимированный зум не превышает
   значение pinch-пути (AC5).

**Мутанты** (`scripts/mutation-gate.mjs`):

- `camera-anchor-from-presented`: вернуть якорь на представленный кадр → юнит
  AC3 красный.
- `camera-cancel-loses-zoom`: убрать сохранение при пользовательской отмене →
  юнит AC1 красный.
- `glow-feather-thaws-during-camera`: снять признак движения камеры из гейта
  feather → перф-контракт AC5 красный.

## Риски

- **Двойная запись зума.** Сохранение при отмене плюс сохранение в `settle`
  может дать две записи на один жест. Смягчение: запись идемпотентна по
  значению (тот же зум не переписывает storage — §11 #82 «no-op не переписывает
  localStorage»), контракт проверяется счётчиком записей в юните.
- **Тонкая грань «пользовательская против структурной».** Ошибка
  классификации перевернёт поведение. Смягчение: классификация задаётся одним
  аргументом на вызове отмены (а не выводится из состояния), оба случая
  покрыты юнитами, список мест перечислен в спеке #82 §13.
- **Изменение якоря затрагивает pinch.** Смягчение: `_zoomAt` явно оставлен на
  представленном состоянии, отдельный юнит фиксирует, что pinch-путь не
  изменился численно.

## Откат

Точечный: три изменения независимы. Откат якоря — вернуть `_cameraState()` в
`_cameraTargetAt`; откат персиста — убрать сохранение из ветки отмены; откат
feather — вернуть гейт на признаки жеста. Формат хранения не меняется, поэтому
откат не оставляет следов в данных пользователя.

## Release-артефакты

- `docs/CHANGELOG.md` / `docs/CHANGELOG.ru.md`: один пункт про то, что
  прерванный зум запоминается и точка под курсором не уезжает (User-Visible).
- `docs/specs/082-smooth-zoom.md`: §10 и §13 в новой редакции.
- Скриншоты не меняются: визуал в статике идентичен.