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

# SPEC-REVIEW-82-r1 — Плавное масштабирование плана (issue #82)

- **Issue:** https://github.com/Matysh/houseplan-card/issues/82
- **Артефакт ТЗ:** `docs/specs/082-smooth-zoom.md`, коммит `141d79a923f5703eb3beceebdabbd5508821f0fe`
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4 (полный трек, лимит 4)
- **Ревьюер:** Claude, роль «Ревьюер ТЗ» (PROCESS.md §2.4, §6)

## Скоуп ревью

Задача полного трека (нет метки `small`), поэтому ТЗ живёт файлом
`docs/specs/082-smooth-zoom.md`, а не в теле issue. Это первый заход
ревью на этом ТЗ (r1), поэтому §2.10 (разбор по дельте) не применяется —
разбор полный. Диф на пути к текущему SHA:

```
git diff 453c3e3d..141d79a9 -- docs/specs/082-smooth-zoom.md   # 352+/232- строк, актуализация ТЗ
```

Диф не трогает `src/**`, `custom_components/**`, `test/**`, `demo/**` —
только `docs/specs/082-smooth-zoom.md`. Класс C (документация), гейты
типа `typecheck`/`test`/`build`/`check-docs` к этому диффу неприменимы:
менять нечего, кода не существует. См. «Чего не проверял».

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

1. Прочитан `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (§1, §2.3–2.10, §4,
   §5, §7, §12).
2. Прочитано тело issue #82 и все три комментария (аналитика 2026-08-14,
   заведение ТЗ 2026-08-15, актуализация 2026-08-30).
3. Прочитан полный текущий текст `docs/specs/082-smooth-zoom.md` (24
   раздела).
4. Прочитан канонический `docs/CANVAS.md` (§5 Zoom and pan, «View/editor
   camera handoff», §4 content frame) и `docs/TOUCH-SUPPORT.md` (raздел
   про View/editor visual transition, deliberate degradation rule).
5. Проверены фактические утверждения ТЗ о текущем коде против
   `src/houseplan-card.ts` (`_zoomAt`, `_onWheel`, `_stepZoom`,
   `_resetZoom`, `_fitAll`, `_fitFar`, `_baseVb`, `_clampView`,
   `ZOOM_MAX`/`ZOOM_MIN`, `LS_ZOOM`, `_saveZoom`, lazy `import('./houseplan-editor-runtime')`)
   и `src/mode-transition.ts` (`ModeTransitionController`,
   `interpolateModeVisualState` — уже интерполирует `pixelsPerUnit` в
   log-space и center линейно тем же easing, что подтверждает
   реализуемость предложенного §9 механизма).
6. Проверена терминология кнопок/подсказок против `src/i18n/ru.json`
   (`title.zoom_fit` = «Вписать всё», `canvas.show_far` = «Показать») —
   совпадает с матрицей §6 ТЗ.
7. Проверено существование смоков, на которые ссылается план тестов
   (`demo/smoke_mode_transition.mjs`, `demo/smoke_visual_continuity.mjs`,
   `demo/smoke_zoom_out.mjs`, `demo/smoke_pan_any_zoom.mjs`,
   `demo/screencast_visual_continuity.mjs`, `npm run continuity:screencast`
   в `docs/TESTING.md`) — не изобретены, это существующий инструментарий
   #73.
8. Проверены обязательные разделы ТЗ по PROCESS.md §7.1 построчно
   (список ниже).

## Проверка обязательных разделов (§7.1)

| Раздел §7.1 | Есть в ТЗ | Где |
| --- | --- | --- |
| Сценарий (персона/поверхность/момент) | ✅ | §1 |
| Что человек увидит до/после | ✅ | §2 |
| Проблема | ✅ | §3 |
| Скоуп и не-скоуп | ✅ | §4 (цели) + §5 (не входит) |
| Контракт поведения / UX | ✅ | §6–§13 |
| Модель данных и миграция | ✅ | §14 — «не меняется, миграции нет» |
| i18n | ✅ | §20 — новых ключей нет |
| AC1…ACn с доказательством | ✅ | §17, 14 критериев, у каждого назван способ |
| План автотестов | ✅ | §18 (unit / browser smoke / golden-perf) |
| Риски | ✅ | §22, 8 рисков с мерой |
| Откат | ✅ | §23 |
| Release-артефакты | ✅ | §21 |

Все обязательные разделы присутствуют и содержательны, не переписывают
issue дословно.

## Находки

Блокирующих (High) находок нет. В скоупе-Medium находок нет. Вне
скоупа — нет.

Ниже — три Low-наблюдения; ни одно не требует правки ТЗ, оставлены с
записью решения ревьюера (не блокируют переход в `S5-ready`).

### Low-1 — AC13 частично доказывается гейтом, недоступным на этой стадии цикла

`AC13` называет доказательством «Performance profile + screencast
smoke». Per `docs/STATUS.md`, CDP-скриншот-профиль (`continuity:screencast`)
— **stable-release-only** гейт, а не гейт код-ревью или даже бета-гейта;
то есть формально AC13 не может быть закрыт автотестом до промоушена в
стабильный релиз. Это не изобретение автора ТЗ: тот же паттерн уже
принят для #73 (`docs/superpowers/specs/2026-08-10-plan-visual-continuity-design.md`
явно делит проверку на обязательный CI rAF sampler и pre-stable CDP
screencast). Решение ревьюера: не блокировать — прецедент уже
принят продуктом, а перформанс-часть AC13 (RAF/rebuild-счётчики) всё
равно доказывается раньше, в pre-beta профиле (§8). Отметить только,
что на код-ревью AC13 будет разобран по коду плюс перформанс-профиль,
а screencast-часть закроется не раньше стабильного гейта — это стоит
явно писать в хендоффе, а не подразумевать.

### Low-2 — общий easing-хелпер между `ModeTransitionController` и новым camera controller не специфицирован технически

§24 помечает разделение camera/mode-контроллеров с общим easing как
«принято предположительно, поменять свободно» — формально корректно
по PROCESS.md §7.1 (технический вопрос, не продуктовый). Замечание
чисто наблюдательное: `interpolateModeVisualState` в
`src/mode-transition.ts:124-156` уже реализует ровно ту же схему
(log-space для масштаба, линейно для центра, общий `ease()`), так что
риск, который §22 таблицы называет «Wheel ощущается медленным» /
«SVG и HTML расходятся», технически прецедентно снят — эта же формула
уже работает в проде для перехода режимов. Не требует правки ТЗ.

### Low-3 — «дальний hint «Показать»» добавлен в матрицу §6, не упомянутый в исходном тексте issue

Матрица §6 ТЗ добавляет девятую строку («Far hint «Показать»»)
относительно восьми строк в исходном issue. Проверено по коду:
`_fitFar()` (`src/houseplan-card.ts:5879`) сам вызывает `_resetZoom()`
— тот же примитив, что и «Вписать всё»/home-arrow/double-tap, так что
это не новая функциональность, а актуализация того, что «Вписать всё» в
issue уже подразумевало устройство разных источников одного и того же
действия. Не расширение скоупа, не требует нового вопроса владельцу.

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

- Все фактические утверждения раздела 3 «Актуальность и проблема» о
  текущем коде (`_zoomAt`, `_onWheel`, `_stepZoom`, `_resetZoom`,
  `_fitAll`/`_fitFar`, lazy editor runtime, общий `_view` для
  flat/isometric) — сверены с исходным кодом и точны.
- Константы `MIN_ZOOM = 1/3`, `ZOOM_MAX = 8`, easing
  `cubic-bezier(0.2, 0.7, 0.2, 1)` — совпадают с `docs/CANVAS.md` §5 и
  `src/mode-transition.ts`.
- Persistence-контракт §13 («editor zoom не пишется в View intent»,
  «`_saveZoom()` работает только в `mode === 'view'`») сверен с
  `src/houseplan-card.ts:6212-6228` — комментарий в коде подтверждает
  тот же инвариант дословно.
- Терминология кнопок («Вписать всё», «Показать») сверена с
  `src/i18n/ru.json` — совпадает буквально.
- `docs/TOUCH-SUPPORT.md` не противоречит требованию §12 «stage не
  получает overlay/inert» во время camera-only tween: канонический
  `inert` относится к отдельному, другому контракту View/editor
  mode-перехода (#101), а не к zoom-действию внутри режима — ТЗ
  корректно разграничивает эти два случая в §8.
- AC1–AC14 однозначны, у каждого указан способ доказательства; ни
  одна формулировка не читается как два разных критерия одновременно.
- Раздел 24 «Принятые технические предположения» корректно отделяет
  технические решения от продуктовых; продуктовых вопросов к
  владельцу действительно не осталось — сценарии из issue (interruption
  matrix, accessibility, no-op) уже были фактами, подтверждёнными
  комментарием владельца 2026-08-14 («вопросы: нет»).
- Раздел «Не входит в задачу» корректно исключает inertia/kinetic pan,
  анимацию mode/space/projection-переходов, новый storage-формат,
  что не даёт скоупу расползтись на смежные issue (#101, #73, #89/122).
- Двунаправленные ссылки issue ↔ ТЗ на месте (`docs/specs/README.md`
  строка 115, тело ТЗ строка 3).

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

- **Код-гейты `typecheck`/`test`/`build`/`check-docs` не прогонялись** —
  диф этого раунда состоит только из `docs/specs/082-smooth-zoom.md`
  (класс C), продуктового кода/тестов нет, прогонять нечего. Это
  сознательное решение по объёму, а не пропуск: `git diff --stat`
  выше подтверждает единственный изменённый файл.
- Не проверялась реализуемость точной wheel-anchor математики
  (0.5 CSS px) на реальном RAF-цикле — это вопрос будущей реализации
  и код-ревью («тест умеет падать»), не спецификации: ТЗ формулирует
  требование измеримо (AC4, unit на presented-state retarget), способ
  доказательства назван.
- Не запускал browser/perf/golden-смоки — на этой стадии кода нет,
  им неоткуда взяться; они будут частью реализации (§18) и предметом
  код-ревью.
- Не проверял детально `iso-projection.ts` построчно на предмет
  скрытых зависимостей от zoom помимо общего `_view`/`_zoom`
  состояния — ограничился подтверждением, что модуль не содержит
  собственных ссылок на `viewBox`/`zoom` (grep пуст), что достаточно
  для вывода «камера едина для flat/iso» из §9/AC10.

## Вердикт

ТЗ полное, разделы §7.1 закрыты, критерии приёмки однозначны и
снабжены способом доказательства, продуктовых вопросов к владельцу не
осталось, фактические утверждения о текущем коде и канонических
документах проверены и точны. Блокирующих находок нет.

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