docs: review document for #531

Issue: #531
User-Visible: no

docs/reviews/CODE-REVIEW-531-r1.md

@@ -0,0 +1,184 @@
+# CODE-REVIEW-531-r1
+
+**Issue:** #531 «Панорама лагает в Firefox: viewBox переписывается каждый кадр»
+**Материал:** ветка `issue/531-live-pan-transform`, SHA `57b80f08e63040c90ef67ff6ab7b65e4addfdc36` (дерево `2b20dd807a08f98ef09ed50cc0cd04db39138ea3`)
+**Заход:** r1 · блокирующих циклов израсходовано 0/4
+**Вердикт: жёлтый**
+
+## Скоуп
+
+ТЗ (спор-ревью зелёный на r2, `docs/reviews/SPEC-REVIEW-531-r2.md`) требует: во время
+жеста панорамы SVG-сцена двигается CSS-трансформом, а `viewBox` переписывается не
+чаще, чем позволяет бюджет (`LIVE_VIEWBOX_REFRESH_MS` ≈100 мс либо
+`LIVE_VIEWBOX_REFRESH_SHIFT` ≈15 % сдвига/масштаба); терминальное примирение не
+меняется; ничего не пишется в DOM, если строка не изменилась; слой устройств и
+сцена не расходятся (#451). AC1–AC9 в теле issue.
+
+Диапазон диффа к `origin/dev`: `src/live-viewport.ts` (единственный продуктовый
+файл), `test/live-viewport.test.mjs` (новый), `demo/smoke_live_pan_viewbox.mjs`
+(новый), `scripts/mutation-gate.mjs` (3 новые записи), `docs/CHANGELOG.md`,
+`docs/CHANGELOG.ru.md`, `docs/ARCHITECTURE.md`, плюс три копии сгенерированного
+бандла (класс D). `src/live-interaction-runtime.ts`, вопреки предположению аналитики
+о затронутых поверхностях, не тронут — планировщик жеста не менялся, значит и
+touch-путь (тот же `PointerEvent`) не отличается от мышиного ни для одной из
+проверок ниже.
+
+## Как проверялось
+
+Дешёвые гейты уже зелёные в Validate на этом SHA (ссылка на прогон в задаче
+ревью), но я перегнал их и сам, поскольку часть проверок ниже требует
+пересобранного бандла и рабочего дерева на этом же SHA:
+
+| Гейт | Команда | Результат |
+|---|---|---|
+| Типы + юниты + сборка | `npm run build` (включает `tsc --noEmit`) | green |
+| Юнит-тесты | `npm test` | 2525 passed, 1 skipped, 0 failed |
+| Три копии бандла | `npm run bundle:sync` + `cmp` попарно `dist`/`custom_components`/`demo/srv/assets` | идентичны |
+| Бюджет бандла | `npm run bundle:budget` | initial View 287 284 Б (потолок 288 300 ±2000) — совпадает с заявленным в хендоффе |
+| Новый `any` | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | 109 добавленных строк, новых `any` нет |
+| Провенанс коммита | `git show -s --format=full HEAD` | `Issue: #531`, `User-Visible: yes`, ветка/трейлеры на месте |
+| Документация фронтенда (diff трогает `src/**`) | `node scripts/check-docs.mjs` | **ERROR** — см. находку Medium ниже |
+| Смок AC5/AC6 | `node demo/smoke_live_pan_viewbox.mjs` | green: `viewBoxWritesDuringGesture=4`, `worstParityPx=0`, совпадает с хендоффом |
+| Golden (AC7) | `npm run golden:verify` | **169/169 passed, 0 расхождений** — полнее, чем в хендоффе (167 + 2 таймаута песочницы автора); подтверждает, что оба «зависших» сценария у автора не относились к реальному регрессу |
+| Мутанты (AC8) | см. таблицу «чем краснеет» ниже | 3/3 новых + 1 соседний старый — все проверены **выполнением**, не чтением |
+| `smoke-select.mjs` | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | НЕОПРЕДЕЛЁННОСТЬ — новые символы (`needsViewBoxRefresh`, `LIVE_VIEWBOX_REFRESH_*` и т.д.) не связаны ни с одним существующим смоком; это ожидаемо для новой сущности, свидетель для неё — именно новый `demo/smoke_live_pan_viewbox.mjs`, названный в AC5/AC6 напрямую. Дополнительных «широких» совпадений выборка не дала (0 смоков) |
+| Инварианты модели | не запускал | диф не трогает геометрию/`layout`/толщины — не применимо |
+| `pytest tests_backend` | не запускал | диф не трогает `custom_components/**/*.py` — не применимо |
+| `performance_smoke` (`large-house-interaction-v1`) | не запускал | явно выведено из-под AC самим ТЗ («Приёмка по скорости — отдельно и не здесь»); Validate на этом SHA его тоже не гонял (job гейтится `heavy`, а этот push — обычный, не кандидат/PR/`workflow_dispatch full=true`) |
+
+Рабочее дерево после всех прогонов и намеренных мутаций восстановлено ровно к
+`57b80f08` (`git status --short` пуст, `git diff HEAD -- src/live-viewport.ts`
+пуст) — материал ревью не изменён.
+
+## Находки
+
+### Medium (в скоупе задачи) — устаревший отпечаток скриншотов документации
+
+`node scripts/check-docs.mjs` на `57b80f08` красный:
+
+```
+ERROR screenshot source fingerprint is stale; run npm run docs:capture and accept before the beta candidate (#479)
+```
+
+На `origin/dev` (до этого диффа) тот же скрипт зелёный: `Documentation checks
+passed (7 files, 12 external links)`. Значит именно правка `src/live-viewport.ts`
+делает отпечаток `docs/images/screenshots.json` устаревшим (отпечаток считается по
+всему `src/**`, PROCESS.md §8) — а `docs/images/screenshots.json` в этом диффе не
+трогался (`git diff origin/dev...HEAD -- docs/images/screenshots.json` пуст).
+
+Это не всплыло в Validate на этом SHA, потому что `docs`-job на обычном push
+(не кандидат, не PR, не `workflow_dispatch full=true`) идёт в режиме `warn`, а
+не `strict` — job зелёный, хотя отпечаток фактически устарел. Ровно тот же
+сценарий, что увёл `dev` в красный `docs`-job на #230/#234 до следующей задачи.
+
+Правка не меняет ни один снятый кадр документации (сама механика жеста — не то,
+что попадает на статичные скриншоты), и `golden:verify` подтверждает нулевое
+визуальное расхождение по всей матрице — то есть цена закрытия минимальна:
+`npm run docs:accept -- --identical` должен пройти чисто (перезаписать только
+отпечаток исходников, не сами PNG) и закоммититься в этом же issue. Я не
+выполнял это сам — правка `docs/**` вне git-дерева ревьюера не моя роль, а
+предмет авторского коммита.
+
+**Воспроизведение:** `node scripts/check-docs.mjs` на `57b80f08` (без каких-либо
+изменений с моей стороны).
+
+## Таблица «чем краснеет» (защитные AC, #435)
+
+| AC | чем доказан | чем краснеет | проверено |
+|---|---|---|---|
+| AC1 (кадр жеста — трансформ, не `viewBox`) | `test/live-viewport.test.mjs`, тест «#531 AC1» | мутант `live-pan-rewrites-viewbox-every-frame` (`needsViewBoxRefresh(...)` → `true`) | **выполнением**: применил патч, `tsc -p tsconfig.test.json` + `fix-test-build` + `node --test` → 6/8 (AC1 и AC2 падают) |
+| AC2 (перезапись по бюджету времени, трансформ снимается) | тест «#531 AC2» | тот же мутант | тем же прогоном (см. выше) |
+| AC2а (сдвиговый триггер срабатывает раньше времени) | тест «#531 AC2а» | мутант `live-pan-shift-threshold-ignored` (удаление сдвиговых веток) | **выполнением**: 7/8, падает именно AC2а |
+| AC3 (тихий кадр не пишет в DOM) | тест «#531 AC3» | мутант `live-pan-writes-unchanged-viewbox` (снятие проверки тождества в `setViewBox`) **не красит AC3** — в этом кадре `refresh=false`, и `setViewBox` вовсе не вызывается, проверка внутри неё недостижима. Красит **AC4** (см. ниже) | выполнением; уточнение важно само по себе — без него третий столбец для AC3 был бы пуст |
+| AC4 (терминальное примирение идемпотентно) | тест «#531 AC4» | мутант `live-pan-writes-unchanged-viewbox` | **выполнением**: 7/8, падает AC4 (повторный `force:true` пишет лишний раз) |
+| AC5 (≤ бюджета перезаписей за 20 кадров жеста) | `demo/smoke_live_pan_viewbox.mjs` | мутант `live-pan-rewrites-viewbox-every-frame`, guard = этот смок (дорогой гейт, повторно не гонял чужую отрицательную пробу — но тот же мутант уже поймал юнит-прогон выше, независимое подтверждение) | смок прогнан чистым: `viewBoxWritesDuringGesture=4` при `framesInGesture=20` |
+| AC6 (маркер и сцена в пределах 1 px, #451) | тот же смок, `worstParityPx`/`markerFollowsTheScene` | любое расхождение экранных смещений маркера и узла сцены | прогнан: `worstParityPx=0` |
+| AC7 (осевшие кадры не изменились) | `npm run golden:verify` | любое отличие хотя бы одного пикселя от эталона — это сравнение, не мутация | прогнан: 169/169, 0 расхождений |
+| AC8 (мутанты реестра) | `scripts/mutation-gate.mjs`, 3 новые записи | сами мутанты | все три плюс соседний `live-viewport-identity-projection-not-recognized` — выполнением, см. выше |
+| AC9 (документация, трейлеры) | `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`, `docs/ARCHITECTURE.md`, коммит | не защитный AC — обычное сравнение | чтением диффа |
+
+## Что проверено и корректно
+
+- **К1/К2/К3/К4 в коде соответствуют ТЗ.** `paintLiveViewport` держит `anchor`
+  (кадр, чей `viewBox` реально в DOM, и момент записи); сцена всегда проецируется
+  от `anchor` к текущему кадру тем же `liveLayerProjection`, что и HTML-слои;
+  `viewBox` переписывается только когда `needsViewBoxRefresh` (время **или**
+  сдвиг **или** масштаб) либо `force`; и `setViewBox`/`setLayerProjection`
+  дедуплицируют запись по строке в обоих случаях.
+- **К5/#451 не нарушен.** Сцена и HTML-слой двигаются одним и тем же
+  преобразованием на каждом кадре (для сцены — от `anchor`, для слоя — от
+  последнего осевшего кадра Lit, но оба landing point — текущий вид); смок
+  AC6 подтверждает 0 px расхождения после 20 кадров жеста.
+- **Две базы проекции (сцена от `anchor`, слой от `painted`) — намеренная и
+  корректная асимметрия**, а не путаница: HTML-слой позиционирован в процентах
+  осевшего Lit-кадра и не может проецироваться от `anchor`, у него нет своего
+  атрибута для дедупликации записи.
+- **Дополнительный триггер по масштабу** (`needsViewBoxRefresh` проверяет не
+  только сдвиг по x/y, но и изменение `w`) — расширение сверх буквального текста
+  К2 (там речь только о сдвиге), но действует строго в сторону усиления защиты
+  от пустой полосы на краю при зуме, не ослабляет ни один AC. Не считаю
+  находкой.
+- **AC5 в реализации отличается от буквального текста ТЗ** («не больше двух» →
+  формула `max(2, ceil(elapsed/100)+1)` + `< frames/2`). Автор явно вынес это
+  отклонение на решение ревью. Обоснование верное: 20 кадров смока на 60 Гц
+  песочницы — это ≈330 мс, то есть 3–4 бюджетных окна по 100 мс, а не 139 мс
+  (2 окна) как на владельческих 144 Гц; жёсткая «2» сделала бы свидетеля
+  зависимым от частоты кадров машины прогона. Формула сохраняет содержательную
+  проверку (перезаписей заметно меньше, чем кадров) и ловится тем же мутантом.
+  Принимаю без правки: технический спор автора и ревьюера решается вердиктом
+  (§7.2), не отправляю владельцу.
+- **Провенанс.** Один коммит, `Issue: #531`, `User-Visible: yes`, оба
+  changelog правлены в нём же, `docs/ARCHITECTURE.md` описывает механику.
+- **Бюджет и типизация** без регрессий (см. таблицу гейтов).
+
+## Чего не проверял и почему
+
+- **`performance_smoke` (`large-house-interaction-v1`).** Сам ТЗ выводит
+  миллисекунды за скобки AC («Приёмка по скорости — отдельно и не здесь»,
+  единственный судья — профиль с машины владельца); Validate на этом SHA его
+  тоже не гонял, поскольку job `heavy`-гейтится, а push не кандидат/PR/ручной
+  полный прогон. Причинный механизм (сцена не растеризуется каждый кадр)
+  доказан AC1–AC6 напрямую.
+- **`node scripts/model-invariants.mjs`, `pytest tests_backend`.** Диф не
+  трогает геометрию/толщины/`layout` и не трогает Python — не применимо.
+- **Полная матрица смоков (243 файла).** `smoke-select.mjs` не нашёл ни прямых,
+  ни зарегистрированных связей (только НЕОПРЕДЕЛЁННОСТЬ на новых символах,
+  для которых свидетель — сам новый смок), «широких» совпадений — 0. Прогон
+  всей матрицы для точечной правки одного модуля камеры избыточен.
+- **Мутант `live-pan-rewrites-viewbox-every-frame` против самого браузерного
+  смока** (а не только против юнитов, которые тот же мутант тоже красит) —
+  дорогой гейт, свидетеля второй раз не воспроизводил; принял отчёт автора
+  (3/3 пойманы) вместе с независимым фактом, что тот же мутант уже красит
+  юнит-прогон.
+- **Изометрический путь (риск 3 ТЗ).** Ни один тест (юнит или смок) не
+  использует кадр, где `floor !== view` — то есть заявленное в разделе «Риски»
+  ТЗ «проверяется тем же юнитом на изометрических данных» текстом теста не
+  подтверждается: `frame()`-хелпер в `test/live-viewport.test.mjs` всегда
+  строит `floor` равным `view`, а смок работает в `_setMode('view')`
+  (не изо). Код при этом полностью симметричен для `camera`/`floor` (одна и
+  та же пара функций, различается только поле кадра), так что риск разъехаться
+  именно на изометрии низкий, но эмпирически не закрыт. Не блокирую — это не
+  требование ни одного из AC1–AC9, только пункт из повествовательного раздела
+  «Риски»; фиксирую как наблюдение, а не как находку Medium/Low с обязательной
+  правкой.
+
+## Материал раунда
+
+- SHA: `57b80f08e63040c90ef67ff6ab7b65e4addfdc36`
+- Дерево: `2b20dd807a08f98ef09ed50cc0cd04db39138ea3`
+- Диапазон: `origin/dev...HEAD` (53 файла, из них продуктовый — только
+  `src/live-viewport.ts`; остальное — тесты/смок/мутанты/документация/бандл)
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/531-live-pan-transform`, коммит `57b80f08e630` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `2b20dd807a08f98ef09ed50cc0cd04db39138ea3`
+  ```
+  git log --all --format='%H %T' | grep 2b20dd807a08
+  ```
+- Тело issue: `89e75138a50434ac52f42cef606d8af741a8ae3b022dba382c4b62c1f4887e8a`
+- Вердикт конвейера: `yellow` · High 0