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

# SPEC-REVIEW-579-r1

- Issue: #579 — «HA Companion: при pinch-zoom стены и пол мигают белым или прозрачным»
- Этап: spec (PROCESS.md §2.4), заход r1, блокирующих циклов израсходовано 0 из 4
- Материал: тело issue #579 целиком (аналитика → `## ТЗ`, 14 разделов) плюс один
  комментарий-аналитика (`S2`), метка `S4-spec-review`; предыдущих раундов
  ревью в issue нет — это первый заход, разбор полный, раздела «Унаследовано»
  не требуется
- Проверено на `dev` @ `856a2c6e1238d5cb735f0c4676af2f2d8edfc838` (рабочая копия
  уже на этом SHA — сверено `git rev-parse HEAD` и `git log -1`); тот же SHA
  назван автором в комментарии-аналитике как точка проверки

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

Ревью ТЗ, не кода: `src/live-viewport.ts` ещё не менялся (issue открыт,
продуктового коммита по #579 нет). Вопрос — выполнимо ли и однозначно ли ТЗ,
доказуем ли каждый AC, не выдана ли догадка за факт, верно ли выбран полный
трек, и нет ли продуктового вопроса, спрятанного в тексте под видом
технического.

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

1. Прочитан `docs/SCOPE.md`: задача чинит поломку J1 («Show the whole home and
   what's happening right now») ровно в той поверхности, которую SCOPE.md
   называет решающей для двух из трёх персон — «View mode is the product»
   (Household members, Guests/kiosk). Новой job не открывает, рамку не
   расширяет.
2. Прочитаны `AGENTS.md` и PROCESS.md §2.4, §2.9/2.10 (не применимо — r1),
   §4, §7.1, §7.2.
3. Прочитано тело issue #579 целиком: аналитический блок до `## ТЗ` (причина,
   почему тесты зелёные, связанные issue, диагностическая развилка, границы
   исправления, покрытие будущей реализации) и сам `## ТЗ` (14 разделов).
   Прочитан единственный комментарий — S2-аналитика владельца, подтверждающая
   механизм на этом же SHA и явно снимающая продуктовые вопросы.
4. Прочитан `docs/TOUCH-SUPPORT.md`: pinch/pan в View и kiosk — гарантированная,
   release-blocking поверхность («support convenient pan, pinch zoom and space
   switching», «A touch-only failure in View is a product defect, not an
   accepted limitation»). Задача лежит строго внутри этого контракта, не
   пытается его расширить или сузить.
5. Прочитан `docs/CANVAS.md` §5 (Zoom and pan): «Pinch and pan remain direct
   1:1 gestures», модель zoom/pan/anchor не входит в скоуп задачи и прямо
   исключена в её не-скоупе — согласовано.
6. Прочитан `docs/ARCHITECTURE.md`, раздел «Live viewport: a transform per
   frame, a `viewBox` on a budget (#531, 2026-09-11)» — канонический текст
   подсистемы. Он же документирует ныне действующее поведение, которое ТЗ
   собирается менять: «A budget refresh or the terminal commit removes the
   inline overflow together with the transform» — совпадает с описанием
   дефекта в ТЗ дословно, не расходится.
7. **Технический механизм дефекта сверен построчно с кодом на названном SHA**,
   а не принят на веру:
   - `src/live-viewport.ts:190-205` (`paintLiveViewport`): на каждом кадре
     сцена-SVG проецируется от `next.frame` к `current` через
     `liveLayerProjection`; при бюджетном refresh (`needsViewBoxRefresh`,
     `:93-103`, 100 мс либо сдвиг/масштаб 15 %) `next.frame` становится равен
     `current` → проекция тождественна → `isIdentityLiveLayerProjection`
     возвращает `true` → в `setLayerProjection` передаётся `null`
     (`:192-205`), что физически снимает `transform`/`transform-origin`/
     `will-change` и (при `exposeSceneOverflow`) `overflow` (`:112-146`,
     ветка `!projection`). Следующий кадр жеста снова получает нетождественную
     проекцию и заново промотирует слой. Это ровно тот churn
     промотирования/демотирования, который ТЗ называет причиной дефекта —
     подтверждено чтением, а не предположением.
   - `commitHouseplanViewport` (`:255-270`) вызывается из
     `LiveInteractionRuntime.commit()` (`src/live-interaction-runtime.ts:79`),
     который, в свою очередь, вызывается из `protected updated()`
     (`src/houseplan-card.ts:4202-4203`) — то есть **на каждом полном Lit-цикле
     обновления**, включая конец программной камеры (переход анимации меняет
     реактивные `_view`/`_zoom`, что вызывает `requestUpdate` → `updated()`).
     Это подтверждает контрактный пункт 4 и 9 ТЗ («тот же lifecycle для
     pointerup/pointercancel/lostpointercapture/программной камеры/обычного
     Lit-коммита, не по user-agent») без необходимости заводить новые
     обработчики событий — он уже общий по архитектуре.
   - `setLayerProjection` (`:112-146`) уже содержит write-only-on-change
     защиту (`if (style.transform === text) return;`, `:142`, и аналог для
     `viewBox` в `setViewBox`, `:149-151`) — то есть требование АС1/АС2/АС9
     «держать identity transform явно установленным без лишних записей на
     неизменный кадр» технически совместимо с существующим примитивом: нужно
     не убирать значение, а один раз записать identity-текст, дальше сравнение
     строк само не даст повторных записей.
   - Селектор `data-hp-live-viewbox="camera"/"floor"` (`houseplan-card.ts`,
     множественные точки: iso underlay/shadows/walls/overlays, flat/iso
     floor-svg, `vactrail`, `radar-ranges`) уже общий (`querySelectorAll`, без
     перечисления по имени) — значит формулировка ТЗ «каждый scene-SVG с
     `data-hp-live-viewbox=camera/floor`» реализуется тем же общим
     механизмом, не требует адресного списка и не рискует пропустить один из
     iso-слоёв.
   - Риск ТЗ «изометрия имеет несколько SVG с разными camera/floor
     проекциями; применение одной матрицы ко всем запрещено» — подтверждён:
     в коде камера и floor действительно проецируются раздельно
     (`sceneCamera`/`sceneFloor`, `:190-191`, отдельные querySelectorAll на
     `:192` и `:199`), общий рефакторинг рискует их случайно смешать, и ТЗ
     этот риск называет явно, а не молчит о нём.
8. Сверены названные в плане автотестов файлы/инструменты — все существуют,
   ни один не выдуман: `test/live-viewport.test.mjs`,
   `demo/smoke_live_pan_coverage.mjs`, `demo/screencast_visual_continuity.mjs`
   (CDP screencast harness, npm-скрипт `continuity:screencast`),
   `demo/smoke_editor_gestures.mjs`, `demo/smoke_smooth_zoom.mjs`,
   `demo/smoke_tap_ctx.mjs`, `demo/smoke_long_press_gesture.mjs`,
   `demo/smoke_isometric_live_touch.mjs`, `scripts/mutation-gate.mjs`.
9. Попытка воспроизвести приведённый в issue вывод
   `node demo/smoke_live_pan_coverage.mjs` (`OK — 37/37 checks green`) —
   локально упала на старте (`Failed to fetch dynamically imported module`,
   таймаут `page.waitForFunction`), потому что нет собранного `dist/**`
   (продуктовый код по #579 не менялся, бандл собирался в другой раз). Это
   ожидаемо для стадии spec (гейты и сборка сюда не относятся, см. ниже) и не
   ставит под сомнение вывод: сам механизм дефекта я подтвердил прямым чтением
   исходников (п.7) — более надёжным способом, чем повторный прогон уже
   процитированного зелёного смока.
10. Проверено согласование трека: `small` (PROCESS.md §5) требует одну
    поверхность и отсутствие нового touch/производительного контракта —
    задача одновременно трогает compositor lifecycle, кросс-браузерную
    производительность (Chrome/Firefox) и touch-контракт View/kiosk; владелец
    в аналитике явно пишет «лёгкий трек: нет» с обоснованием. Полный трек
    выбран верно.

Гейты (`typecheck`/`test`/`build`/`golden`) на этой стадии не прогонялись и не
нужны: продуктового кода по #579 ещё нет, предмет проверки — текст ТЗ, а не
бинарник (см. п.9 выше — попытка была сделана ровно для проверки
воспроизводимости цитаты из issue, а не как обязательный гейт стадии).

## Находки

Ни одной High или Medium находки.

- **Проверено и не является находкой: возможная догадка о причине.** Аналитика
  (до `## ТЗ`) прямо помечает локализацию как «подтверждённая, но не доказанный
  конкретный фикс» и требует A/B-развилку из 5 вариантов до выбора реализации.
  Раздел «Принятые предположения» отдельно и честно выделяет «причина — churn
  promotion/demotion, а не конкретный фильтр/геометрия» как предположение,
  которое можно поменять на ревью. Я сам подтвердил именно этот механизм прямым
  чтением кода (см. «Как проверялось», п.7) — то есть то, что в ТЗ помечено как
  предположение, на самом деле уже доказано чтением; это не ухудшает ТЗ (лишняя
  осторожность автора не вредит), поэтому не является дефектом текста.
- **Проверено и не является находкой: чем закрывается AC10 без физического
  устройства.** ТЗ прямо возлагает финальную полевую проверку на владельца
  перед закрытием beta candidate и разрешает честно отметить «невыполненная
  полевая приёмка» вместо подмены Chromium-скриншотом. Это не новый прецедент:
  `docs/reviews/CODE-REVIEW-544-r1.md` («физическое устройство — не локальное
  доказательство») ровно так же выносит полевую проверку за пределы
  автоматического доказательства того же самого подкласса дефекта (Companion
  WebView). Формулировка AC10 не создаёт скрытого продуктового вопроса и не
  блокирует «Готово к разработке» — критерий доказуем в том виде, в каком
  сформулирован.
- **Проверено и не является находкой: смешение технического и продуктового
  вопроса.** Раздел «Продуктовые вопросы владельцу: нет» обоснован —
  пользовательский контракт («ни один показанный кадр не теряет пол/стены»)
  уже зафиксирован в `docs/TOUCH-SUPPORT.md` как release-blocking для View, а
  выбор конкретного compositor-механизма — техническое решение авторов
  (§7.1: «где хранится состояние… агенты решают сами»), корректно вынесенное
  в раздел «Технический механизм требует A/B до реализации», а не владельцу.

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

Все обязательные разделы на месте и в правильном порядке: сценарий · что
человек увидит до и после · проблема · скоуп и не-скоуп · контракт поведения
(9 пунктов) · UX · модель данных и миграция (эфемерное состояние
`LiveViewportState`, явно «новых полей/ключей/миграций нет») · i18n (явно
«новых строк нет») · критерии приёмки AC1–AC10, каждый со способом
доказательства · план автотестов · риски · откат · release-артефакты. Плюс
полезные необязательные разделы: аналитика по коду, диагностическая развилка,
предварительные границы, требуемое покрытие будущей реализации, приоритет и
трек, принятые предположения.

- **Сценарий/что человек увидит** — персона-центричны («пользователь Home
  Assistant… в Companion на телефоне»), без терминов реализации; «промежуточный
  кадр», «pinch», «zoom», «View», «kiosk» — уже канонические термины подсистемы
  (`CANVAS.md`, `TOUCH-SUPPORT.md`, `USER-GUIDE.ru.md`), не изобретены задачей.
- **AC однозначны и проверяемы.** Каждый из AC1–AC10 называет способ
  доказательства (unit/browser smoke/screencast/mutation witness/полевая
  проверка), большинство — с отрицательным свидетелем (AC1 и AC6 явно требуют
  красного mutation witness; AC10 явно требует красного текущего поведения на
  реальном устройстве до фикса — это условие «тест умеет падать» будущего
  код-ревью, зафиксированное уже в самом ТЗ).
- **Скоуп/не-скоуп** согласован с `SCOPE.md` (J1) и `TOUCH-SUPPORT.md`
  (View/kiosk — гарантированная поверхность); не расползается: явно исключены
  геометрия плана, диапазон/якорь/инерция zoom, UA-sniffing, отключение
  эффектов, рефакторинг Companion/Chromium, публикация изометрии.
- **Контракт поведения** (9 пунктов) внутренне непротиворечив и совместим с
  существующим кодом: п.7 («частота записей viewBox не возрастает») не
  конфликтует с п.2/п.3 («identity transform остаётся явно установленным») —
  это разные атрибуты (`viewBox` vs `style.transform`), и существующий
  write-on-change примитив (`:142`, `:149-151`) их не смешивает.
- **Принятые предположения** оформлены отдельным блоком «можно менять на
  ревью» с явным обоснованием каждого пункта — ровно то разделение
  «продуктовое решает владелец, техническое — авторы», которого требует §7.1.
  Открытых продуктовых вопросов, замаскированных под технические, не найдено.
- **Риски** называют конкретные точки провала предположения (GPU-память
  постоянно промотированного слоя; WebView может мигать и внутри уже
  стабильного layer — с названным следующим техническим вариантом на этот
  случай; identity transform может дать другой settled raster — с названным
  контролем через golden/cleanup-unit; смешение iso camera/floor проекций) —
  не декоративные, а операционные.
- **Откат** — ревертом единственного продуктового коммита, без данных/миграции;
  единственная оговорка (возврат к покадровому `viewBox` как временная мера при
  доказанной GPU-регрессии) явно помечена как повторное открытие исходного
  дефекта, не как тихий компромисс.

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

- Технический механизм дефекта (churn промотирования/демотирования scene-SVG
  на каждом budget refresh) подтверждён построчным чтением `live-viewport.ts`
  и `houseplan-card.ts` на названном SHA, совпадает и с текстом ТЗ, и с
  действующим описанием в `docs/ARCHITECTURE.md`.
- Существующая архитектура (write-on-change примитивы, общий селектор
  `data-hp-live-viewbox`, generic `updated()`-коммит) технически допускает
  предложенный фикс без новых обработчиков событий или специальных случаев —
  «Техническая реализация» не описывает невозможную или противоречивую схему.
- Ни одно техническое утверждение ТЗ, не помеченное как предположение, не
  разошлось с кодом или каноническими документами при проверке.
- Названные в плане автотестов файлы и npm-скрипты существуют, инфраструктура
  для AC1–AC9 реальна, а не гипотетична.
- Продуктовых вопросов владельцу нет обоснованно: контракт «ни один показанный
  кадр не теряет пол/стены» уже зафиксирован `TOUCH-SUPPORT.md` как
  release-blocking, новых продуктовых решений задача не вводит.

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

- Гейты `typecheck`/`test`/`build`/`golden` — не прогонялись: продуктового
  кода ещё нет, предмет этапа — текст ТЗ, а не бинарник.
- Полный `node demo/smoke_live_pan_coverage.mjs` — попытка запуска сделана
  только для проверки воспроизводимости цитаты из issue (см. п.9), упала на
  отсутствии собранного `dist/**`; пересборка бандла на этой стадии не
  требуется и не выполнялась.
- Реализация будущего mutation witness и содержимое расширенного
  `test/live-viewport.test.mjs`/`smoke_live_pan_coverage.mjs` — не существуют
  на этой стадии, их проверит код-ревью.
- Ручного/физического Companion-теста не проводилось и не требовалось: ТЗ
  прямо и корректно относит его к AC10 как отдельный релизный гейт перед
  закрытием issue, а не как доказательство этого раунда.
- Perfomance-профиль большого плана (AC9) — назван «перед бетой», вне скоупа
  ревью ТЗ.

## Вердикт

Зелёный. High — 0, Medium — 0. Все обязательные разделы §7.1 присутствуют,
каждый AC однозначен, проверяем и снабжён доказательством и (где применимо)
отрицательным свидетелем. Технический механизм дефекта подтверждён прямым
чтением кода на названном SHA, а не принят на веру. Единственное
предположение, обозначенное как таковое, на практике уже доказано чтением
кода. Продуктовых вопросов владельцу нет обоснованно. Задача может переходить
в «Готово к разработке».

---

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

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

- Ветка: `issue/579-webview-pinch-compositor`, коммит `856a2c6e1238` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `35e12ab83a88ef61b8284ef386341e4e71f40b89`
  ```
  git log --all --format='%H %T' | grep 35e12ab83a88
  ```
- Тело issue: `4545e4010a0a0d13588d41c73912f543b83f5091653de15127390b77630498a0`
- Вердикт конвейера: `green` · High 0