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

# SPEC-REVIEW-531-r1

**Issue:** #531 — «Панорама плана в Firefox: `viewBox` переписывается на каждый
кадр жеста, композитор ждёт 13 vsync-тиков»
**Этап:** spec (ревью ТЗ, PROCESS.md §2.4)
**Трек:** полный (автор называет нарушенный критерий §5: «нет влияния на
производительность» — обоснованно, см. «Что проверено и корректно»)
**Заход:** r1 · блокирующих циклов израсходовано 0 из 4
**Материал:** тело issue #531 на dev `af2081cb` (рабочая копия на этом же SHA)

## Скоуп

ТЗ живёт в теле issue #531, раздел `## ТЗ`, написан после аналитики S2
(комментарий от 11.09). Предмет: во время живого жеста панорамы/зума
(`paintLiveViewport`, `src/live-viewport.ts`) двигать SVG-узлы сцены
(`[data-hp-live-viewbox]`) тем же CSS-трансформом, что уже применяется к
HTML-слою устройств, вместо безусловной перезаписи атрибута `viewBox` на
каждый кадр; переписывать `viewBox` редко, по бюджету времени и/или
накопленному сдвигу; не писать в DOM значения, совпадающие с уже записанными.
Терминальное примирение (`commitHouseplanViewport`) не меняется по результату.
Контракт К1–К6, AC1–AC9.

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

Чтением кода без исполнения — на этапе ТЗ продуктового кода ещё нет, гейты не
прогонялись (правка кода не входит в этот этап; изменений класса A в этом
материале нет). Каждое техническое утверждение ТЗ сверено построчно с
`src/live-viewport.ts`, `src/live-interaction-runtime.ts`,
`src/houseplan-card.ts` на текущем `dev` (`af2081cb`).

- `docs/SCOPE.md` — J1 («живой пространственный обзор»), View mode как
  продукт для двух персон из трёх; правка не добавляет UI и не открывает
  новую поверхность действий — конфликта со скоупом нет.
- `AGENTS.md`, `PROCESS.md` §2.3–§2.5, §5, §7.1 — формальные требования к ТЗ
  и выбору трека.
- `src/live-viewport.ts` целиком (166 строк): `paintLiveViewport`,
  `liveLayerProjection`, `isIdentityLiveLayerProjection`, `setLayerProjection`,
  `scheduleHouseplanViewport`, `commitHouseplanViewport`, `frameOf`.
- `src/live-interaction-runtime.ts` целиком: `LiveRuntime.viewport/commit`
  вызывают ровно эти функции, других путей записи `viewBox` нет.
- `src/houseplan-card.ts:6149-6153` — `_floorView`: в неизометрическом режиме
  возвращает **тот же объект** `view` без копирования, что делает утверждение
  спеки «`_floorView(view) === view`» (принятое предположение №3) буквально
  верным, а не приближением; `data-hp-live-viewbox="camera"/"floor"` и
  `data-hp-live-layer="camera"` (строки 11507–12801) — теги существуют и
  используются как описано, включая изометрическую и обычную ветки.
- `demo/benchmark_large_house.mjs:643-919` — единственная существующая
  проверка, трогающая `viewBox` во время жеста; проверяет только сам факт
  сдвига после завершения жеста, не частоту перезаписи.
- `test/live-viewport.test.mjs` (31 строка) — файл уже существует (ТЗ верно
  пишет «создаётся, если нет», не заявляя, что он новый).
- `scripts/mutation-gate.mjs:7551-7558` — существующий мутант на
  `isIdentityLiveLayerProjection`, прецедент для новых AC8-мутантов.
- `docs/ARCHITECTURE.md:1908` — раздел про `live-viewport.ts` уже существует,
  есть что расширять по AC9.

## Находки

### Medium — второй триггер бюджета (К2) не имеет ни одного AC и ни одной названной константы

**Место:** тело issue #531, раздел `### Контракт`, пункт К2.

К2 определяет **два независимых** триггера перезаписи `viewBox`: истечение
времени (`LIVE_VIEWBOX_REFRESH_MS`, с ориентиром «≈100 мс») **или**
накопленный сдвиг, превысивший «долю видимой области». Первому триггеру дан
и ориентир значения, и прямой тест: AC2 явно описывает сценарий «по истечении
бюджета `viewBox` переписывается ровно один раз». Второму триггеру не дано ни
ориентировочного значения константы (в отличие от 100 мс для первого), ни
отдельного AC — ни одного из AC1–AC9 нельзя провалить, если реализация вообще
не построит путь «накопленный сдвиг → досрочная перезапись», при условии, что
временной бюджет продолжает работать:

- AC1–AC4 — модульные сценарии с явными кадрами/вызовами, ни один не создаёт
  ситуацию «время в пределах бюджета, но сдвиг уже большой»;
- AC5 (смок, реальная панорама) считает *суммарное* число перезаписей
  `viewBox` за 20 кадров жеста («не больше двух») — этот счётчик не
  различает, каким триггером вызвана каждая перезапись, и пройдёт одинаково
  и с рабочим, и с полностью бездействующим сдвиговым триггером (например,
  если реализация просто не добавит вторую ветку условия);
- `demo/benchmark_large_house.mjs` (единственная существующая проверка живого
  `viewBox`) тоже смотрит только на факт сдвига после жеста, не на триггер.

Формально К2 — часть контракта, обязательного к реализации, но ни один AC не
способен покраснеть на его отсутствии. Это ровно тот класс дефекта, который
должен ловить ревью ТЗ (PROCESS.md §2.4: «найти, где ТЗ не выполнимо или не
проверяемо») и который DoR прямо требует закрыть (PROCESS.md §2.5:
«AC1…ACn — пронумерованные проверяемые критерии приёмки» для контракта
целиком).

**Требуется от автора** (правка ТЗ в этом же issue, без нового): либо назвать
константу-ориентир для доли видимой области и добавить AC/строку в
существующий AC2, отдельно проверяющую срабатывание именно по сдвигу (кадры
без истечения временного бюджета, но с большим накопленным перемещением) —
либо, если авторское намерение — необязательная оптимизация без отдельной
гарантии, явно перенести пункт К2-«сдвиг» в блок «Принятые технические
предположения» и снять его из нормативного контракта К-разряда. Оба выхода
дёшевы; несделанное — жёлтый вердикт, не блокирует до второго захода.

Серьёзность — Medium, строго в скоупе задачи: без High-находок это жёлтый
вердикт, автор правит ТЗ, фикс проходит повторный (второй) заход.

### Low — обязательные разделы §7.1 присутствуют по содержанию, но не как отдельные заголовки; снято без правки

**Место:** тело issue #531, раздел `## ТЗ`.

PROCESS.md §7.1 перечисляет как отдельные обязательные разделы «проблема»,
«скоуп и не-скоуп», «UX», «модель данных и миграция», «release-артефакты».
В тексте ТЗ они не оформлены отдельными заголовками: проблема раскрыта внутри
`### Сценарий и что человек увидит` (абзац «До.» — числа задержки, тик
рефреш-драйвера, причина), не-скоуп — пунктом К6 внутри `### Контракт`
(изометрия работает по тому же механизму без отдельной оптимизации;
тайлинг/предрендер/изменения сцены вне объёма), UX — фразой «Ни одной новой
настройки, вид плана не меняется» там же, модель данных/миграция и
release-артефакты — разделом `### i18n, миграция, бэкенд` («Ничего») и AC9
соответственно.

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

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

- **Продуктовая рамка (§7.1, два первых раздела).** Персона не названа явно
  словом, но сценарий однозначен и совпадает с `docs/SCOPE.md`: любой человек,
  тянущий план мышью или пальцем, на любой поверхности, в любом режиме —
  панорама используется и в View (планшет/киоск), и в редакторах. «До/После»
  — одной фразой каждое, без терминов реализации («план едет за курсором
  плавно», «вид плана не меняется»).
- **Трек выбран верно.** Единственный названный критерий §5 («нет влияния на
  производительность») нарушен по существу: правка целиком посвящена частоте
  дорогой операции (растеризация SVG) в кадре жеста, а раздел «Производительность
  и бюджеты» прямо называет `large-house-interaction-v1` как гейт.
- **Все технические утверждения о текущем коде подтверждены чтением.**
  `paintLiveViewport` действительно пишет `viewBox` безусловно (строки 95,
  98) и не имеет проверки на тождество для него, при этом у слоя-трансформа
  такая проверка уже есть (`isIdentityLiveLayerProjection`, строка 105) —
  ровно то расхождение, которое К4 просит устранить. `_floorView` в
  неизометрическом режиме возвращает тот же объект `view` — принятое
  предположение №3 не приближение, а факт.
- **К1–К5 внутренне непротиворечивы.** «Каждый кадр — только трансформ» (К1)
  и «раз в бюджет — новый `viewBox`» (К2, по времени) не конфликтуют: кадр,
  на котором истёк бюджет, — не нарушение К1, а исключение, явно описанное
  тем же пунктом К2 («после чего трансформ возвращается в единицу в том же
  кадре»).
- **AC1–AC4, AC6, AC9 проверяемы и имеют названный способ доказательства**,
  соответствующий существующей инфраструктуре: `test/live-viewport.test.mjs`
  уже существует и расширяем, `scripts/mutation-gate.mjs` уже содержит
  прецедент мутанта на этот же модуль, `docs/ARCHITECTURE.md` уже содержит
  раздел про `live-viewport.ts` для AC9.
- **AC7 (golden) и AC5 (смок) не выдают синтетическую слабость сборки за
  доказательство.** Раздел «Приёмка по скорости — отдельно и не здесь» прямо
  и честно признаёт: headless-песочница держит 60 к/с на обоих путях, поэтому
  итоговый приговор по миллисекундам даёт только профиль с машины владельца
  — AC внутри репозитория доказывают механизм (частота записи в DOM), а не
  цифру задержки. Это ровно то разделение, которого требует §2.4
  (доказательство, а не заявление).
- **Риски по существу и с путём отступления.** Пустая полоса на набегающем
  крае (риск 1) ограничена именованной константой бюджета — при
  «недостаточно» её можно уменьшить без нового цикла ревью; риск изометрии
  (риск 3) закрыт тем же юнитом на изометрических данных; риск округления на
  границе (риск 4) держится существующим пиксельным порогом контракта #451
  (К5, AC6), а не новым числом.
- **Touch.** Заявление «панорама пальцем — тот же путь» подтверждено кодом:
  единственная точка входа `_liveVp()` (`houseplan-card.ts:4543`) вызывается
  из одних и тех же мест независимо от типа указателя (Pointer Events
  унифицируют мышь/тач) — отдельного тач-пути для панорамы нет, значит и
  отдельного тач-контракта не требуется. `docs/TOUCH-SUPPORT.md` не нарушается:
  раздел «Touch» ТЗ корректно называет вывод «без смены контракта».
- **Принятые технические предположения — действительно технические.** Ни
  одно не подменяет продуктовое решение: все три — про то, как
  реализовывать (применимость проективного преобразования к SVG,
  неизменность толщин линий во время жеста, равенство `_floorView(view)` и
  `view` в обычном режиме), ни одно не про то, что видит пользователь.
- **Откат.** «Ревёрт коммита» достаточен и корректен: правка не трогает
  конфиг, миграций нет, флага Labs не заявлено и не требуется по масштабу
  изменения.

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

- Гейты `npx tsc --noEmit`/`npm test`/`npm run build` не запускались — в этом
  материале нет изменений класса A/B/D относительно `dev` (диапазон
  `origin/dev..HEAD` пуст), прогонять их значило бы проверять пустое
  множество.
- `node scripts/check-docs.mjs` не запускался по той же причине — `src/**` не
  менялся.
- Реализуемость числового бюджета `LIVE_VIEWBOX_REFRESH_MS≈100 мс` и порога
  «доля видимой области» на реальном железе владельца не оценивалась — это по
  тексту самого ТЗ («Приёмка по скорости — отдельно и не здесь») предмет
  профиля с машины владельца на этапе код-ревью/пре-релиза, не текста спеки.
- Поведение в изометрическом режиме не проверялось построчно за пределами
  `_floorView` и наличия тех же data-тегов на изометрических SVG (строки
  11507, 11753–11762) — К6 явно исключает отдельную изометрическую
  оптимизацию из объёма этой задачи, детальная проверка изо-пути остаётся
  код-ревью по факту диффа.
- Точное поведение при одновременном зуме и панораме (`_zoom` в кадре) не
  прослеживалось до реализации — контракт не даёт для этого случая
  отдельного AC, а зум уже часть существующего `LiveViewportFrame` без
  изменений в этом ТЗ.

## Вердикт

**Жёлтый · заход r1/4 · High: 0 · Medium: 1 → в задаче.**

ТЗ технически точное — все конкретные утверждения о коде подтвердились,
трек выбран обоснованно, продуктовая рамка и границы (К6, Riски, откат)
сформулированы честно и без догадок, выданных за факт. Единственная
находка — контрактный пункт К2 (сдвиговый триггер перезаписи) не имеет
доказательства ни одним из AC1–AC9 и не назван даже ориентировочной
константой, поэтому реализация может законно пройти весь набор AC, вообще не
построив этот путь. Это в точности класс дефекта, который ревью ТЗ обязано
ловить (§2.4: «не выполнимо или не проверяемо»). Правка дешёвая — либо один
AC плюс ориентир константы, либо честный перенос пункта в «Принятые
технические предположения» как необязательной оптимизации. Low-находка о
неформальной структуре разделов снята без правки, записью в этом документе.

Следующий статус при исправлении — «Готово к разработке» (`S5-ready`).

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

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

- Ветка: `dev`, коммит `af2081cbc40e` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `08815814f33b6c836ecbd32deabf793353fc1bb1`
  ```
  git log --all --format='%H %T' | grep 08815814f33b
  ```
- Тело issue: `f2fb7dcc85656bdbedb38eff70aa8b3ef28804c4aab4bccc41c36879e7533e95`
- Вердикт конвейера: `yellow` · High 0