houseplan-card/docs/reviews/CODE-REVIEW-582-r1.md

# CODE-REVIEW-582-r1

Issue: [#582](https://github.com/Matysh/houseplan-card/issues/582) · этап: code · заход r1 ·
блокирующих циклов израсходовано 0 из 4 · материал: `0a6592f4112fd7ceef68cbd3be7c44eeb8a7ef3e`
(`origin/dev` = `bae6afaae7bac2dd45bca52b6caf64a16d96f182`, `origin/dev..HEAD` = `b9bf3daa`
(документ ревью ТЗ) + `0a6592f4` (сама правка)).

## Скоуп

ТЗ (в теле issue) чинит воспроизводимый в HA Companion дефект: во время pinch-zoom
пространства с фоном «Следует за Солнцем» появляются фиксированные белые/прозрачные
области, вызванные тем, что постоянный `will-change: filter` из #532 висит на
внутренней группе `.hp-paperg`, чей локальный SVG-bbox при `cell_cm: 1` может достигать
тысяч единиц — Chromium промотирует слой пропорционально этому координатному размеру, а
не экранному. Контракт (п.1–7) требует: сохранить визуальный контур и его перфоманс-выигрыш
из #532, но привязать промотированный слой к экранному viewport независимо от `cell_cm`, и
сделать то же самое для `houseplan-space-card`. AC1–AC9 в теле issue.

Это основная View-поверхность (J1) и touch-контракт View/kiosk (`docs/TOUCH-SUPPORT.md`,
release-blocking), так что вопрос "работает ли оно на самом деле" здесь не формальность.

## Материал и что сделано в коде

- Новый общий рендерер `src/render/paper-scene.ts` (`renderPaperShapes`) — заменяет три
  дублированные ветки `path/poly/rect` в `houseplan-card.ts` и `space-render.ts`.
- В `houseplan-card.ts` и `space-render.ts` добавлен ОТДЕЛЬНЫЙ `<svg class="hp-paper-outline-svg">`
  сосед перед основным `plan-svg`/`hp-static-plan-svg`, содержащий копию бумажных фигур;
  он использует тот же `viewBox`/`data-hp-live-viewbox`, что и основной план, и тот же
  `isoFloorMatrixCss()` в изометрии.
- В `plan.styles.ts` тройной `drop-shadow` и `will-change: filter` перенесены с
  `.hp-paperg` на `.hp-paper-outline-svg` (стейдж-размерный корневой `<svg>`, растянутый
  правилом `.zoomwrap > svg { width:100%; height:100% }`), тем самым слой теперь
  действительно ограничен экранными пикселями, а не локальными SVG-единицами.
- `space-card.ts` получил такое же правило для `.hp-static-stage .hp-paper-outline-svg`.
- Новый браузерный смок `demo/smoke_daycycle_layer_budget.mjs` (CDP LayerTree + screencast)
  — свидетель AC1/AC3. Новый мутант `daycycle-outline-promoted-on-inner-paper` (guard —
  этот смок) — свидетель AC2. `smoke_daycycle_raster.mjs`/`smoke_bg_color.mjs` обновлены
  под новые имена классов — свидетели AC4/AC5. Новый `test/paper-scene-contract.test.mjs`
  — свидетель AC7. `scripts/smoke-links.mjs` регистрирует связь `renderPaperShapes` → 4
  смока. `scripts/bundle-budget.mjs` подвинул потолок на 200 Б с объяснением. Оба changelog
  и `docs/ARCHITECTURE.md`/`docs/SUN.md`/`docs/TOUCH-SUPPORT.md`/`docs/TESTING.md` обновлены
  согласованно с кодом. Трейлеры коммита `Issue: #582` / `User-Visible: yes` на месте.

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

Дешёвые гейты подтверждены зелёным Validate на точном SHA
(https://github.com/Matysh/houseplan-card/actions/runs/34940487324, `workflow_dispatch`,
без `heavy`): предполёт, классификация, «Фронтенд: типы/юниты/бандл», 6 шардов
«Мутанты по диффу» — всё `success`. Тяжёлые джобы (`golden`, `smoke`, `performance_smoke`,
`hacs`, `hassfest`, `geometry_parity`, `backend`) в этом прогоне **skipped** — не PR,
не `Release:`, не `full=true`, поэтому они не гейтили этот пуш. Именно эти пропущенные
джобы оказались важны (см. находки).

Я лично прогнал (то, что Validate не покрыл, и что явно относится к диффу):

| Гейт | Результат | Почему прогнан/не прогнан |
|---|---|---|
| `npm run bundle:sync` (typecheck+build+rollup+bundle-tree) | зелёный, `git status` после — чисто | дёшево, диф трогает `src/**` |
| `node demo/smoke_daycycle_layer_budget.mjs` (AC1/AC3) | **зелёный**, 4 прогона подряд | прямое совпадение с диффом |
| `node demo/smoke_bg_color.mjs` | **зелёный** (все 47 проверок, включая изменённую `staticCardLayersStayOrdered`) | зарегистрированная связь, CI её не гонял (heavy=false) |
| `node demo/smoke_live_pan_coverage.mjs` | **зелёный** | зарегистрированная связь, CI её не гонял |
| `node demo/smoke_daycycle_raster.mjs` (AC4, свидетель #532) | **красный, воспроизводимо 8/8** (ratio 2.16–2.50 против потолка 2.0); на `origin/dev` тот же смок даёт 1.01–1.14 в 7/7 запусках в ЭТОМ ЖЕ окружении | прямое совпадение с диффом; CI отчитался зелёным на этом SHA, но локальный результат детерминирован и объяснён (см. Находка №1) |
| `npm run golden:verify` (AC6, полная матрица) | **4 из 4 day-cycle сцен = `different`**, остальные ~150 сцен `passed` | diff меняет рендер; CI `golden` был skipped на этом пуше, так что это первый реальный прогон на данном SHA |
| `npm run inventory` | не гонял | не требуется для этого раунда |
| `python -m pytest tests_backend -q`, HACS, Hassfest, geometry parity | не гонял | диф не трогает `custom_components/**/*.py`, манифесты или геометрию решётки/толщины стен |
| `performance_smoke` (полный) | не гонял | AC4 уже красный на более дешёвом целевом свидетеле; полный перф-профиль не добавит новой информации до фикса |

Плюс диагностика причины (CDP `LayerTree` + `compositingReasons`, одна и та же гарнитура
`demo/serve.mjs`, один и тот же демо-фикстур 1400×900, сравнение `origin/dev` vs `HEAD`
бок о бок в одном окружении) — вынесена в Находку №1.

## Находки

### Находка №1 (High) — AC4 не держится: день-цикл при pan рерастеризует весь план, не только контур

**Файлы:** `src/houseplan-card.ts:11597-11603`, `src/styles/plan.styles.ts:97-105`,
`src/space-render.ts` (тот же паттерн для static card).

**Механизм.** Раньше `will-change: filter` стоял на `.hp-paperg` — `<g>` ВНУТРИ
`plan-svg`, с малым собственным bbox. `plan-svg` целиком в свой отдельный
compositor-слой не попадал (в baseline `origin/dev` слой `plan-svg` в CDP `LayerTree`
вообще не значится: контент рисуется в общей поверхности). Патч кладёт контур в
ОТДЕЛЬНЫЙ `<svg class="hp-paper-outline-svg">`-СОСЕД перед `plan-svg` в том же
`.zoomwrap`. Chromium корректно ограничивает промотированный слой контура экранными
пикселями (это и было целью, AC1/AC2/AC3 — подтверждены), но побочный эффект: теперь
`plan-svg` (ВЕСЬ видимый план — стены, комнаты, устройства, декор) визуально
перекрывает промотированный слой-соседа и по правилам Chromium сам получает
отдельный compositor-слой с причиной `"Overlaps other composited content"`
(проверено CDP `LayerTree.compositingReasons` на обоих деревьях, один и тот же демо-стенд,
1400×900):

```
origin/dev (до патча):     hp-paperg 920×720 (will-change: filter); НЕТ отдельного слоя plan-svg
0a6592f4 (после патча):    hp-paper-outline-svg 780×724 (will-change: filter);
                           plan-svg 780×724 ("Overlaps other composited content")  ← новый слой
```

Это ПОЛНЫЙ план как отдельная растеризуемая поверхность, которая теперь должна
перерисовываться при любом визуальном изменении плана во время жеста — то есть именно
тот класс стоимости, который #532 устранял для внешнего контура, теперь возвращается
для всего плана.

**Численное подтверждение (изолированный прогон, 20 шагов панорамы мышью, тот же
демо-стенд, RasterTask по CDP Tracing):**

```
origin/dev:  31.8 мс,  106 RasterTask
0a6592f4:    74.7 мс,  282 RasterTask   (≈2.35× по времени, ≈2.7× по числу тасков)
```

**Свидетель AC4 (`demo/smoke_daycycle_raster.mjs`), 60-шаговая панорама, то же
окружение, 8 прогонов на `HEAD` против 7 на `origin/dev`:**

| Дерево | ratio (потолок 2.0) |
|---|---|
| `origin/dev` | 1.09, 1.14, 1.03, 1.03, 1.04, 1.01 (все ≤ 1.14) |
| `0a6592f4` | 2.19, 2.16, 2.23, 2.18, 2.50, 2.33 (все ≥ 2.16) |

Разброс между двумя деревьями непересекается ни разу за 13 запусков — это не шум
конкретной машины, а систематическая разница, воспроизводимая в контролируемом A/B
внутри ОДНОГО окружения (обе половины смока меряются в одном процессе на одной
странице, как и задумано автором смока).

**Почему CI на этом SHA отчитался зелёным, а не потому что находки нет.** Job
«Мутанты по диффу» реально исполняет `node demo/smoke_daycycle_raster.mjs` (лог
`ok чистый прогон: node demo/smoke_daycycle_raster.mjs`, 07:14:24) и код проверки
(`serve.mjs: finish()`) действительно ставит `process.exitCode=1` при `ratio > 2.0` —
то есть CI-раннер в моменте объективно получил ratio ≤ 2.0. Проблема в марже: порог
2.0 был откалиброван «примерно посередине по логарифму» между 7.9 (без подсказки
вообще) и 0.26 (подсказка на тесной `.hp-paperg`, комментарий в самом смоке, строка 15).
Новая реализация переехала с 0.26 на ~2.2–2.5 — то есть съела почти весь запас,
оставленный именно на случай машинной вариативности, и на GitHub-раннере это на
сегодня чуть-чуть укладывается, а на менее мощном/более шумном исполнителе — уже нет.
Целевая платформа этой самой задачи — Android HA Companion WebView — как правило
СЛАБЕЕ настольного CI-раннера, а не сильнее; то есть именно то устройство, ради
которого чинится #582, статистически более рискованно по AC4, чем моя тестовая машина.

**Последствие.** AC4 сформулирован как "свидетель #532 остаётся зелёным" — де-факто он
не остаётся зелёным как класс поведения (плана целиком, а не только контура), просто
конкретный числовой порог на конкретном раннере пока не перешагнут. Это разваливает и
собственное объяснение ТЗ в "Технические ограничения": "Фильтр/промоушен должен
применяться на уровне экранной scene surface, а не координатно большой внутренней
группы" — технически верно для самого контура, но не учитывает, что помещение этой
scene surface СОСЕДОМ (а не потомком) плана заставляет браузер промотировать и сам план.

### Находка №2 (High) — AC6 не проходит: все 4 day-cycle golden-сцены отличаются от эталона на каноничной платформе

**Файлы:** `demo/golden/baselines/day-cycle-{dawn,day,dusk,night}-dark.png` (не
обновлены в этом диффе — `git diff origin/dev...HEAD --stat -- demo/golden/` пуст).

`npm run golden:verify` (Linux, тот же движок, что CI/golden — каноничная платформа
по AGENTS.md) на точном SHA даёт:

| Сцена | статус | differing px | diffRatio | maxObservedDelta | порог diffRatio |
|---|---|---|---|---|---|
| day-cycle-dawn-dark | different | 26 903 | 0.0349 | 81 | 0.0005 |
| day-cycle-day-dark | different | 26 160 | 0.0339 | 81 | 0.0005 |
| day-cycle-dusk-dark | different | 25 667 | 0.0333 | 81 | 0.0005 |
| day-cycle-night-dark | different | 26 142 | 0.0339 | 94 | 0.0005 |

Это ~70× превышение допустимой доли различающихся пикселей и разница каналов до 94/255
при допуске 10/255 — не антиалиасинг-дребезг на границе допуска. Визуально (сравнение
`demo/golden/baselines/day-cycle-day-dark.png` и `artifacts/golden/actual/day-cycle-day-dark.png`
на глаз почти неотличимы; diff-маска в `artifacts/golden/diff/day-cycle-day-dark.png`
подсвечивает штриховку буквально ВСЕХ стен по всему плану, не только внешний контур)
похоже на тот же механизм, что и Находка №1: как только `plan-svg` стал отдельным
композитным слоем, финальная сборка кадра проходит через дополнительный проход
растеризации/блендинга этого слоя, слегка меняя суб-пиксельное позиционирование штриховки
стен по всему плану — отсюда широкий, но мелкий по амплитуде на глаз разброс.

Оставшиеся ~150 сцен матрицы прошли (`passed`), включая не-day-cycle сцены — регрессия
локализована именно в day-cycle рендере, как и предсказывает механизм Находки №1.

AC6 прямо требует: "четыре существующие day-cycle сцены... проходят... Любое
необходимое обновление baseline допускается только после объяснённого визуального
сравнения". Baseline не обновлён, объяснения в issue/коммите нет — сам факт диффа не
скрывается (никто не подделывал числа), но и не заявлен: ни в диффе, ни в комментариях
issue нет упоминания, что `golden:verify` был прогнан и дал результат. Раз diff явно
трогает рендер (`src/**`: `houseplan-card.ts`, `space-render.ts`, `paper-scene.ts`,
`plan.styles.ts`), `golden:verify` был обязателен перед `S7-code-review`
(AGENTS.md, "проверь по diff и AC" + сам этот процесс-документ).

**Обе находки объединяет один и тот же корень**: помещение дневного контура СОСЕДНИМ
`<svg>` перед `plan-svg` вместо ВНУТРИ него как раньше — технически верно решает
координатно-огромный слой (AC1–AC3 в порядке), но по пути превращает весь план в
отдельный композитный слой, что стоит и лишней растеризации (Находка №1), и лишнего
прохода блендинга, видимого в пикселях (Находка №2). Возможные направления для автора
(не предписание, только ориентир): не выносить контур отдельным сиблингом, а найти
способ ограничить экранными размерами именно промотированный слой ВНУТРИ существующего
дерева `plan-svg` (например, через `clipPath`/`contain`, привязанный к экранному
`viewBox`, а не к локальному bbox фигуры), либо явно и всегда держать `plan-svg` на
собственном стабильном слое ДО появления контура, чтобы контур не мог его "продавить"
через overlap-эвристику при первом появлении.

### Находка №3 (Low, не блокирует, оставлена без правки)

`src/houseplan-card.ts:11623-11624` — комментарий "One `<g>` around ALL paper shapes:
the external day-cycle outline (styles.ts) is composited once for the whole sheet"
относится к `.hp-paperg`, но сам фильтр туда больше не прикреплён (перенесён на
`.hp-paper-outline-svg`, отдельный узел). Смысл абзаца (одна группа = отсутствие швов
между комнатами) остаётся верным, но фраза про "the external day-cycle outline...
is composited" на этом самом `<g>` — уже не так. Мелкая правка комментария, не код.

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

- **AC1/AC2/AC3** — подтверждены и CI-логом мутанта (`daycycle-outline-promoted-on-inner-paper`,
  чистый прогон ok + красный на мутанте ok, 07:14:05–07:14:50 на точном SHA), и моим
  локальным повторным запуском `smoke_daycycle_layer_budget.mjs` (4/4 зелёных): контур
  теперь 826×736 (экранный порядок) вместо потенциальных 4700×4200; ни один content-слой
  > 4096; 9/9 отснятых кадров pinch без белых пикселей.
- **Единый живой viewport (#579, контракт п.3–4).** `data-hp-live-viewbox` стоит на
  `.hp-paper-outline-svg` тем же значением (`camera`/`floor`), что на `plan-svg`;
  `live-viewport.ts:paintLiveViewport` обновляет оба через один и тот же
  `querySelectorAll` и одну и ту же проекцию — контур и план не могут разойтись по
  кадру или масштабу отдельно от терминального примирения. Проверено чтением, не
  исполнением отдельно от смоков выше (которые это же утверждение покрывают AC3).
- **Основная бумага не фильтруется (контракт «Технические ограничения»).**
  `renderPaperShapes(paperShapes)` без `groupClass` даёт `.hp-paperg` без фильтра;
  `test/paper-scene-contract.test.mjs` проверяет отсутствие `will-change: filter` на
  `.hp-paperg`; смок `smoke_daycycle_raster.mjs` подтверждает
  `dayCyclePaperStaysUnfiltered: true` в моём прогоне.
- **Изометрия и static card не потеряли зеркальность.** `<g transform=${iso ?
  isoFloorMatrixCss() : nothing}>` оборачивает `renderPaperShapes` в контурном SVG тем
  же способом, что в основном; `hp-static-stage` получил аналогичное правило z-index/
  overflow/pointer-events; `smoke_bg_color.mjs` (`staticCardLayersStayOrdered`) зелёный.
- **`plan-svg` z-index стал безусловным** (было `class=${iso ? 'plan-svg' : nothing}`,
  стало `class="plan-svg"`) — раньше во flat-режиме класс не вешался вовсе и элемент
  зависел от порядка DOM для стэкинга; теперь это явное `z-index: 1` против `0` у
  контура. Не регрессия: до этого диффа конкурирующего элемента с явным z-index не было,
  после — есть (сам контур), и явный класс корректно фиксирует стэкинг. `test/isometric-contract.test.mjs`
  обновлён синхронно.
- **Changelog/трейлеры/документация.** `Issue: #582` + `User-Visible: yes` на
  терминальном коммите; оба `docs/CHANGELOG*.md` правлены в нём же; `docs/ARCHITECTURE.md`,
  `docs/SUN.md`, `docs/TOUCH-SUPPORT.md`, `docs/TESTING.md` описывают именно то, что
  делает код (сверено построчно с диффом кода). `scripts/bundle-budget.mjs` — потолок
  подвинут на 200 Б с содержательным объяснением, общий бюджет не тронут.
- **Мутационная регистрация.** `daycycle-outline-promoted-on-inner-paper` привязан к
  правильному guard-файлу и реально ловит возврат старого `will-change` (подтверждено
  и в CI, и локально).

## Чего не проверял и почему

- `python -m pytest tests_backend`, HACS, Hassfest, geometry-parity — diff не трогает
  `custom_components/**/*.py`, манифесты, `layout`/`marker.space`/толщину стен; эти
  гейты были в Validate `skipped` по классификации файлов, а не по heavy-флагу, что и
  ожидаемо для чисто фронтенд-диффа.
- Полный `performance_smoke`/профили вне `smoke_daycycle_raster.mjs` — AC4 уже
  провалена на целевом, более дёшевом свидетеле; гонять более тяжёлый профиль до
  фикса не добавляет решающей информации.
- `npm run inventory` — не требуется для вынесения вердикта этого раунда.
- Полная browser-smoke матрица (250 файлов) — вне AC и вне выборки `smoke-select.mjs`
  (4 зарегистрированные связи, все 4 прогнаны явно, см. таблицу выше).
- AC9 (полевая приёмка на реальном Android WebView владельцем в следующей бете) —
  вне этого этапа по определению самого AC.

## Вывод

Реализация корректно решает координатно-зависимый размер промотированного слоя
(AC1–AC3), сохраняет единый live-viewport и визуальный контракт контура на уровне
кода, документация и трейлеры в порядке. Но выбранная архитектура (контур —
СОСЕДНИЙ `<svg>` перед планом, а не элемент внутри него) имеет побочный эффект:
`plan-svg` целиком продавливается в отдельный композитный слой, что воспроизводимо
проваливает собственный AC4 (перф-свидетель #532) вне узкой марки конкретного
CI-раннера и приводит к measurable расхождению во всех 4 golden-сценах AC6 на
каноничной Linux-платформе, не сопровождённому обновлением baseline или объяснением.
Обе находки — High, обе в скоупе задачи (эта же ветка чинит то, что сама же
сформулировала как риск: "Исправление WebView может регрессировать
Firefox-производительность #532"). Возврат автору.

---

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

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

- Ветка: `issue/582-webview-large-filter-layers`, коммит `0a6592f4112f` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `9f4d95168fdda9650fa7d35f17d80c7177a7d12b`
  ```
  git log --all --format='%H %T' | grep 9f4d95168fdd
  ```
- Тело issue: `4c1e1ecfe8ce205f3cfb3c44eb6028a35d0bb4358323e05ba60c6fd85b3b40ba`
- Вердикт конвейера: `red` · High 2