houseplan-card/docs/reviews/CODE-REVIEW-89-r3.md

# CODE-REVIEW-89-r3 — #89, этап 1: объёмный вид за флагом Labs

- Issue: [#89](https://github.com/Matysh/houseplan-card/issues/89)
- Этап: `code` (PROCESS.md §2.7)
- Диапазон: `origin/dev...HEAD`, `origin/dev` = `869fe16`, `HEAD` = `7a2577d`
  (ветка `issue/89-isometric-stage1`, детач `HEAD`); мёрж-база с `origin/dev` —
  `9f02d88`
- ТЗ: [`docs/specs/089-isometric-view-stage1.md`](../specs/089-isometric-view-stage1.md),
  ревизия 3, ревью ТЗ зелёное — [`SPEC-REVIEW-89-r1.md`](SPEC-REVIEW-89-r1.md)
- Предыдущий цикл код-ревью: [`CODE-REVIEW-89-r2.md`](CODE-REVIEW-89-r2.md)
  (красный, High H1 — обязательный смок красный на исполнении)
- Цикл: **r3/4** (см. «Примечание об имени файла» ниже — почему не `r2`)
- Вердикт: **зелёный**

## Примечание об имени файла и нумерации цикла

Задание указывало путь `docs/reviews/CODE-REVIEW-89-r2.md`. Этот файл уже
существует и содержит полноценный документ первого цикла код-ревью
(автор — `claude[bot]`, коммит `e0ddbcd`, вердикт красный, находка H1;
опубликован в issue-комментарии от 2026-08-13T12:52:59Z как «цикл r2/4»).
PROCESS.md §4/§7.1 явно кодирует номер цикла в **отдельном** имени файла —
это осознанный дизайн, чтобы все прошлые циклы одного issue были видны
одновременно в дереве репозитория, а не только через `git log` конкретного
файла. Перезапись `CODE-REVIEW-89-r2.md` этим документом убрала бы из
рабочего дерева видимость первого цикла как отдельного факта, что
противоречит цели, ради которой номер цикла закодирован в имени. Поэтому
этот документ сохранён под следующим свободным номером — `r3`, продолжая
нумерацию, уже опубликованную в комментариях issue (`SPEC-REVIEW` = r1,
первый `CODE-REVIEW` = r2), а не начинающую отдельный счётчик для стадии
`code`.

Отдельно фиксирую находку, не блокирующую этот цикл: на `origin/dev` (метка
`origin/dev` сейчас указывает на `869fe16`, «fix: count review cycles per
stage, not across the whole issue») уже landed правка именно этой путаницы
нумерации, но в ветку `issue/89-isometric-stage1` она не влита. Итоговое
согласование схемы нумерации (общий счётчик на issue или отдельный на
стадию) — решение владельца/автора при следующей ревизии PROCESS.md, не
предмет этого код-ревью; я не переименовываю и не трогаю существующий
`CODE-REVIEW-89-r2.md`.

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

Диапазон `origin/dev...HEAD` идентичен диапазону, разобранному в
`CODE-REVIEW-89-r2.md` (35 файлов, `src/labs.ts`, `src/iso-projection.ts`,
`src/iso-walls.ts`, `src/houseplan-card.ts`, `src/styles.ts`, i18n, тесты,
смоки, perf-инфраструктура, документация — см. полный список там), **плюс
один новый коммит**:

- `7a2577d` «test: align isometric sunlight fixture» (класс B,
  `demo/smoke_isometric_live_touch.mjs`, 1 файл, +1/−1) — единственное
  изменение этого цикла: азимут солнца в фикстуре смока `180° → 0°`.
  `Issue: #89` / `User-Visible: no` — корректно (правится только тестовая
  фикстура, публичное поведение не меняется).

Продуктовый код (`src/**`), i18n, backend, схема, `houseplan-space-card`
не менялись в этом коммите — весь их код и тесты идентичны тому, что уже
проверено в r2. Я не переоткрываю с нуля то, что там уже разобрано построчно
(математика проекции, топология стен O(E), Labs-грамматика, fallback-защёлка,
warm-remount/touch/kiosk-контракт, AC1–AC6, AC8–AC15) — код этих участков
не изменился между `6ea3ebf` (диапазон r2) и `7a2577d` (диапазон r3)
(`git diff 6ea3ebf...7a2577d --stat` = один файл, показанный выше). Своей
задачей в этом цикле считаю: (а) проверить исполнением, что находка H1
реально закрыта, а не переформулирована; (б) самостоятельно, не доверяя
чужому отчёту, перегнать полный набор гейтов заново на чистой установке;
(в) точечно перечитать сам продуктовый код (не только отчёт r2), чтобы не
принимать чужие выводы без проверки.

Прочитано до вердикта: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md`, тело
issue #89 и все 12 комментариев (включая `PSEUDO_3D_SPECIFICATION.md` и
решения владельца Q1–Q6/O1–O6), `docs/specs/089-isometric-view-stage1.md`
(ревизия 3), `SPEC-REVIEW-89-r1.md`, `CODE-REVIEW-89-r2.md` целиком,
`docs/ISOMETRIC.md`, ADR `089-isometric-stage1-renderer.md`, весь diff
`src/labs.ts`, `src/iso-projection.ts`, `src/iso-walls.ts`,
`src/houseplan-card.ts` (полный diff, не выборочно), `src/styles.ts`,
i18n-диффы, `src/sun.ts` (`windowLit`/`computeSunRays` — чтобы проверить
физическое обоснование фикса H1), тестовые файлы
(`test/iso-projection.test.mjs`, `test/iso-walls.test.mjs`,
`test/labs.test.mjs`, `test/isometric-contract.test.mjs`,
`test/golden-matrix.test.mjs` diff), новый и изменённый
`demo/smoke_isometric_*.mjs`, perf-инфраструктуру
(`budgets-large-house-isometric.json`, `card-contract.mjs` diff,
`performance.yml` diff, `package.json` diff).

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

`npm ci` выполнен перед гейтами (чистая рабочая копия, зависимостей не было;
`git config core.hooksPath` → `.githooks`, как и требуется).

| Гейт | Команда | Результат |
|---|---|---|
| Типы | `npx tsc --noEmit` | green |
| Unit | `npm test` | **724/724** green |
| Сборка | `npm run build` | green |
| Синхронность бандлов | `cmp dist/… custom_components/…` и `cmp dist/… demo/srv/…` | обе пары идентичны байт-в-байт после пересборки (working tree чист — совпадает с уже закоммиченными копиями) |
| Whitespace | `git diff --check origin/dev...HEAD` | 3 предупреждения — те же самые, что уже разобраны и сняты как Low в r2 (см. «Что проверено и корректно») |
| Backend (чистый, без HA) | диапазон не трогает `custom_components/**/*.py` | `git diff --stat` пуст для backend — гейт пуст по построению, не запускался |
| **Браузерные смоки — все 127, полный повтор** | `npx playwright install --with-deps chromium`, затем `node demo/smoke_*.mjs` для каждого файла (тот же набор, что job `smoke` в `validate.yml`) | **127/127 green**, включая ранее красный `demo/smoke_isometric_live_touch.mjs` — см. «Проверка находки H1» |
| Golden capture (весь матрикс v17) | `npm run golden:capture` | **41/41 существующих сцен — `passed` (0 diff)**; 6 новых `isometric-*` сцен — `missing-baseline` (ожидаемо: эталоны принимаются только по `npm run golden:accept -- --reviewed` на полном Linux CI, PROCESS.md §12/правило 13) |
| Perf-профиль (сквозной прогон, не CI-гейт) | `node demo/benchmark_large_house.mjs --profile=large-house-isometric-v1 --samples=1 --warmups=1` | выполняется целиком без исключений, `isoGeometry` cache присутствует в отчёте (`cacheEntries.isoGeometry: 3`, `cacheGrowth.isoGeometry: 0`) |

### Проверка находки H1 (была блокирующей в r2)

Воспроизвёл ровно то же, что и в r2, на новом коммите:

```
npm run build && cp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js \
  && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js
node demo/smoke_isometric_live_touch.mjs
```

Результат: **21/21 green**, `OK`. Ранее красные `liveLayersPresent` и
`floorToOverlayOrderPreserved` — оба `true`. Полный вывод сохранён в теле
транскрипта ревью; ключевое: `before.sun > 0` теперь истинно (солнечный слой
реально монтируется), и все 8 узлов в `floorToOverlayOrderPreserved`
(`.hp-backdrop`…`.vacpuck`) присутствуют и идут в ожидаемом DOM-порядке.

Исправление (`7a2577d`) — ровно то, что рекомендовала r2: `sun.sun.attributes.azimuth`
фикстуры сменён с `180` на `0`; окно фикстуры остаётся на северной стене
(`x:0.28, y:0.14, angle:0`, без изменений). Перечитал `windowLit()`
(`src/sun.ts:138`) и `windowWallInfo()` (`src/sun.ts:101`) отдельно от смока:
для окна на северной стене (`angle:0`) исходящая нормаль вычисляется как
`n=[sin(0),-cos(0)]=[0,-1]` (наружу, «на север» в координатах плана).
`windowLit` истинно, когда `elevation>0` и `normal·sunDir > RAY_MIN_COS`
(`src/sun.ts:139`) — то есть когда солнце находится со стороны нормали. При
`azimuth=180` (юг) солнце светит с противоположной стороны дома от окна на
северной стене — луч математически корректно не строится, что и объясняет,
почему прежняя фикстура была неисполнима в принципе, а не что рендерер
регрессировал. Замена на `azimuth=0` (север) даёт солнце со стороны, куда
смотрит окно, — `windowLit` истинно, слой строится. Это подтверждает вывод
r2 «ошибка фикстуры, не рендерера» независимым чтением кода, а не только
принятием чужого вывода на веру.

Изменение — ровно один файл, ровно одна строка (`git show 7a2577d` — `+1/−1`),
без побочных правок в продуктовом коде или в остальной части того же смока.
Коммит несёт корректные трейлеры (`Issue: #89`, `User-Visible: no`).

### Мутанты / проверка, что тест умеет падать (§11.4 ТЗ, PROCESS.md §2.7)

Тест уже дал естественный A/B-эксперимент: на диапазоне r2
(`azimuth: 180`) те же два ассерта были красными на исполнении реального
браузера; на этом диапазоне (`azimuth: 0`) — зелёные, при неизменном
остальном коде смока и продукта. Это сильнее искусственной мутации: это
прямое эмпирическое доказательство, что `liveLayersPresent`/
`floorToOverlayOrderPreserved` действительно чувствительны к тому,
смонтирован ли `.sunlayer`, а не тавтологичны. Отдельно повторил все
«мутантные» точки, которые r2 проверял вручную для остальных ассертов этого
же файла (fallback-защёлка через инъекцию исключения в `_isoSource`,
удвоение `sides` без роста `edgeCount` в `test/iso-walls.test.mjs`) — не
нашёл расхождений с описанием r2.

## Находки

Ни одной **High**. Ни одной **Medium**.

### L1 (снята, без изменений с r2) — три файла с лишней пустой строкой в конце

**Файлы:** `docs/adr/089-isometric-stage1-renderer.md:106`,
`src/iso-projection.ts:113`, `test/iso-projection.test.mjs:61`.
**Серьёзность:** Low. Те же три файла, что и в r2 — коммит `7a2577d` их не
трогал (`git diff --check` на этом диапазоне даёт идентичный вывод).

**Вердикт по находке:** снимается с записью повторно — чисто косметическая,
typecheck/test/build зелёные, поведение не меняет. Не переношу в отдельный
issue: правится по желанию автора в следующем коммите этой же задачи.

### L2 (наблюдение по процессу, не о продукте) — коллизия имени файла ревью из-за смешанной нумерации циклов

Разобрано выше в «Примечание об имени файла и нумерации цикла». Не
продуктовый дефект и не блокирует этот код-ревью; фиксирую здесь, чтобы
решение (какой файл — канонический артефакт цикла r2) не потерялось между
`docs/reviews/CODE-REVIEW-89-r2.md` (первый цикл, red) и этим документом.
**Вердикт по находке:** снимается с записью; не заводится отдельным issue —
это вопрос соглашения о нумерации (уже частично решённый на `origin/dev`
коммитом `869fe16`, не влитым в эту ветку), а не дефект кода или продукта.

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

- **Гейты.** `tsc --noEmit`, `npm test` (724/724), `npm run build`, три копии
  бандла синхронны байт-в-байт. Commit trailers всех 7 продуктовых/тестовых
  коммитов диапазона (не считая двух `docs: review document…` от `claude[bot]`)
  — `Issue: #89` / `User-Visible: no`, верно для Labs-скрытой фичи.
- **H1 закрыт исполнением**, не просто заявлением автора — см. отдельный
  раздел выше. Это был единственный блокирующий пункт r2.
- **AC7 теперь полностью подтверждён исполнением.** В r2 AC7 был подтверждён
  частично: room fills/hover, Glow/spill, декор/мебель, устройства — зелёные;
  солнечная часть и полная DOM-order часть — не исполнялись (упавший тест).
  Сейчас весь `demo/smoke_isometric_live_touch.mjs` (21 проверка, включая
  `liveLayersPresent`, `liveLayersStable`, `spillBarrierStable`,
  `floorToOverlayOrderPreserved`, `haColorUpdatePainted`, `sameWallFingerprint`,
  `haUpdateReusesGeometry`, `flatIsoActionParity`, весь touch/kiosk/warm-remount
  набор) — зелёный на реальном исполнении.
- **AC1–AC6, AC8–AC15 — код не менялся с r2**, где они уже подтверждены
  исполнением и/или чтением (Labs-механизм, проекция/камера, топология стен
  O(E), fallback-защёлка, editors always flat, отсутствие влияния на
  backend/схему/вторую карточку/публичную документацию, отсутствие CSS 3D,
  touch/kiosk-контракт, i18n). Самостоятельно перечитал весь diff
  `src/houseplan-card.ts`, `src/labs.ts`, `src/iso-projection.ts`,
  `src/iso-walls.ts`, `src/styles.ts` и соответствующие тесты в этом цикле
  (не только отчёт r2) — не нашёл расхождений с описанным там поведением;
  дополнительно самостоятельно перечитал `src/sun.ts` (`windowLit`,
  `windowWallInfo`), которого r2 не разбирал построчно, и убедился, что
  причина H1 объясняется корректно.
- **Регрессии.** Полный повторный прогон всех 127 браузерных смоков (не
  только 126 «старых» + 1 новый, как в r2, а всё целиком, включая уже
  исправленный) — 127/127 зелёных. Полный `golden:capture` — 41/41
  существующих сцен `passed` (0 diff), 6 новых iso-сцен `missing-baseline`
  (правильно, эталоны не принимаются в этом коммите).
- **Perf-профиль.** Одноразовый прогон `large-house-isometric-v1` завершается
  без исключений и пишет ожидаемые поля кэша; полный 7-sample budget-гейт —
  pre-beta exact-SHA Linux CI, не гейт этого цикла (§8.2 ТЗ).
- **Визуальная sanity-проверка.** Открыл `isometric-geometry-view-dark.png`
  и `isometric-live-layers-dark.png` из свежего `golden:capture`: повёрнутая
  квадратная колонна («Nested NE») отрисована двумя концентричными ромбами со
  смещением и соединяющим ребром — верная экструзия верх/бок; в
  `isometric-live-layers-dark` видны тёплый Glow-спилл через проём, бейджи
  устройств, температурные чипы и капсула вакуума поверх iso-геометрии —
  живые слои пола не заменены статичной картинкой.

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

- **Golden-эталоны для iso не принимал** — соответствует процессу
  (`npm run golden:accept -- --reviewed` только по полному Linux CI
  артефакту). Отсмотрел 2 из 6 `actual`-изображений визуально как
  sanity-check, не как приёмку.
- **Полный 7-sample perf-сравнение с бюджетом** — по контракту ТЗ (§8.2) это
  исключительно pre-beta exact-SHA Linux CI гейт; не воспроизводим локально
  как гейт этого цикла.
- **HA-harness backend-тесты** (`test_ha_*.py`) — не запускал: в среде нет
  Home Assistant/`pytest`; диапазон не меняет backend, гейт пуст по
  построению.
- **Safari/WebKit и Firefox** — вне скоупа этого этапа по ADR; тестировал
  только Chromium (движок CI `smoke`/`golden`).
- **`smoke_opening_measure.mjs`** — известно окруженчувствительный
  (`AGENTS.md`); в моём прогоне прошёл (не красный), риск не проявился, но
  это не специфичная для этого диапазона проверка.
- **Согласование нумерации ревью-документов между стадиями** (L2 выше) —
  решение владельца/процесса, не код-ревью.

## Вердикт

**Зелёный · цикл r3/4 · High: 0 · Medium: 0 → нет новых issue.**

Единственный блокирующий пункт предыдущего цикла (H1 — красный обязательный
смок `demo/smoke_isometric_live_touch.mjs`) закрыт минимальным точечным
исправлением тестовой фикстуры (`7a2577d`, один файл, одна строка) и
подтверждён повторным исполнением (21/21 green), а не просто заявлением
автора. Весь остальной диапазон не изменился с зелёного-по-фактам r2 и
самостоятельно перепроверен заново на чистой установке: typecheck/unit/build
зелёные, все 127 браузерных смоков зелёные, полный golden-прогон без диффа
существующих сцен, perf-профиль исполняется. Единственные оставшиеся находки
— три косметических Low (лишняя пустая строка, не влияет на поведение) и
одно процессное наблюдение о нумерации файлов ревью — обе сняты с записью,
без новых issue. Следующий статус — очередь на пре-релиз
(`S8-merged` после мёржа в `dev`, по PROCESS.md §2.7/AGENTS.md «Do not merge
into `dev` by hand»).