houseplan-card/docs/reviews/CODE-REVIEW-649-r2.md

# CODE-REVIEW-649-r2

Issue: [#649](https://github.com/Matysh/houseplan-card/issues/649) · 2.5D, этап 6:
объёмные иконки-плитки с тенью, мягкий свет по солнцу, слой декора без
изменений, режим из experimental в General settings.

Материал: `git log --oneline origin/dev..HEAD` / `git diff origin/dev...HEAD`,
ровно на SHA `106fdc096d5dd7de55d22a88c3a0a2b894b83b49` (рабочая копия уже на
нём; ветку не переключал, `git fetch`/`pull`/`checkout` на другой коммит не
выполнял).

```
106fdc09 fix(2.5D): prove the sun beam is cut by bodies; review r1 lows (#649)
e1f1c7d9 docs: review document for #649
2ed05031 test(mutants): stage3-w12 guard follows the renamed #649 contract test
e5ab4659 feat: 2.5D stage 6 — public setting, raised tiles, soft sun, theme-free walls (#649)
```

164 файла в фиче + 73 файла в делте раунда. Трейлеры на всех трёх рабочих
коммитах корректны: `Issue: #649` везде; `User-Visible: yes` на `e5ab4659`
(оба changelog в том же коммите — `docs/CHANGELOG.md`/`.ru.md`, +12/+12 строк);
`User-Visible: no` на `2ed05031` (гейт мутанта) и на `106fdc09` (делта этого
раунда — см. ниже, почему верно). Заход r2 код-ревью; ТЗ (r2 в теле issue) уже
прошло зелёное SPEC-REVIEW-649-r2.

**SHA материала r1 не резолвится.** `de4521823ba69c390fda4c0534e52e24a63cc66a`
(коммит) и дерево `571541905136a48c1729755f6d7877e5ac6aece4` из блока
«Материал раунда» документа r1 отсутствуют в `git log --all` этого клона (не
shallow — `git rev-parse --is-shallow-repository` → `false`, 3576 коммитов на
`origin/dev`). Это не находка (§2.10: «SHA не резолвится — обычное дело»): у
текущего `e5ab4659` тот же commit message, тот же автор/дата инструмента, тот
же родитель (`origin/dev` tip) и почти идентичная статистика диффа (164 файла,
+5569/−3766 против заявленных в r1 +5570/−3767 — расхождение в одну строку в
обе стороны, не содержательное). Это типичная механика конвейера: ветка
ребейзится на актуальный `origin/dev` перед каждым раундом, что меняет все SHA
ниже точки ребейза без изменения содержимого. Дельта раунда — ровно то, что
показывает `git diff e5ab4659..106fdc09` (коммит `2ed05031` между ними не
трогает продуктовый код, только чинит протухший guard мутанта — унаследован
как есть). Объём разбора: по дельте (§2.10), она полностью локальна — один
новый коммит `106fdc09`, который сам называет себя ответом на r1 («review r1
lows»).

## Скоуп

Без изменений с r1 (см. `docs/reviews/CODE-REVIEW-649-r1.md` → «Скоуп»).
Предмет ЭТОГО раунда — единственный новый коммит `106fdc09`: закрывает
Medium-находку r1 (M1, обрезка 2.5D-луча барьерами не была доказана тестом) и
пять из шести Low (L1, L3, L4, L5, L6; L2 была снята самим r1 без правки кода
как опечатка хендоффа — здесь закрывать нечего).

## Как проверялось (объём по дельте, §2.10)

1. Прочитан документ и вердикт предыдущего раунда:
   `docs/reviews/CODE-REVIEW-649-r1.md` — жёлтый, High 0, Medium 1 (M1), Low 6
   (L2 снята r1 сразу).
2. Объявлена дельта: `git diff e5ab4659..106fdc09` — 73 файла (в основном
   пересобранный бандл), содержательно: `src/iso-sun.ts` не тронут (только
   `test/`, `demo/`, `scripts/mutation-registry.mjs`, `src/iso-tiles.ts`,
   `src/houseplan-card.ts` комментарий, `docs/DEVELOPMENT.md`,
   `docs/ARCHITECTURE.md`, `demo/benchmark_large_house.mjs`). Полный текст
   диффа коммита `106fdc09` прочитан построчно.
3. Для M1 — прочитан `src/iso-sun.ts:82-122` (`computeIsoSunBeams`),
   подтверждено, что `directionalOccluders(input.occluders, away, travel)`
   (строка 112) — ровно то место, которое M1 называл риском (перепутанный
   знак направления/длина). Новый юнит
   `test/iso-stage6.test.mjs` (тест «AC7 the 2.5D beam is cut…») ставит
   колонну на пути луча и проверяет три точки (перед колонной светло, за
   колонной темно, рядом с тенью снова светло) плюс площадь тени.
4. **Мутационное доказательство выполнено исполнением, не чтением.** Для всех
   трёх новых мутантов (`iso-sun-occluders-toward-sun`,
   `iso-sun-occluders-ignored`, `iso-sun-card-drops-occluders`) я вручную
   применил патч из `scripts/mutation-registry.mjs`, прогнал именно тот guard,
   что записан в реестре, убедился в красном результате, затем откатил файл и
   для двух из них (те, что требуют бандл) пересобрал (`npm run bundle:sync`)
   и подтвердил `git status` чист — см. таблицу ниже, результаты все реальные
   прогоны этой сессии.
5. Для L3 (`src/iso-tiles.ts:109-117`, `isoTileStateCss`) вручную пересчитана
   специфичность CSS: новые правила `.dev.theme-dark.${state}` (3 класса) и
   `.dev.theme-dark.${state}.iso-floor-light` (4 класса) перебивают старые
   `.dev.${state}` (2) / `.dev.${state}.iso-floor-light` (3) по специфичности
   независимо от порядка — правки корректны структурно, не только текстуально.
   Также перепроверено (как и в r1), что для всех 6 `ISO_STATE_BODIES`
   `isoEdgeColor` сегодня возвращает одно и то же значение независимо от
   `theme`, потому что ни один не тёмный (`luma·255<70`) и ни один не
   «near-white» в 0..1-шкале (`luma>0.98`) — значит фикс сегодня не меняет
   видимый результат ни для одного реального состояния, что и объясняет
   `User-Visible: no`.
6. Для L1 прочитаны все 4 места, названные в r1 (`docs/DEVELOPMENT.md:231`,
   `docs/ARCHITECTURE.md:31`, `src/houseplan-card.ts:627`,
   `demo/benchmark_large_house.mjs:145`) — все четыре переписаны, проверено,
   что переписанный текст не противоречит соседним абзацам того же файла
   (`docs/DEVELOPMENT.md:249-251`, `docs/ARCHITECTURE.md:86-88`,
   `src/houseplan-card.ts:~2305`), и что не осталось других вхождений
   «experimental/alpha-only/opt-in alpha» применительно именно к 2.5D/Stage 4
   (`grep -n alpha` по трём файлам — только легитимные несвязанные
   употребления: общий `hp_alpha`/Labs-инфраструктура и цветовая альфа).
7. Для L4/L5/L6 прочитаны новые ассерты `demo/smoke_iso_tiles.mjs` и сверены с
   CSS-правилами, на которые они опираются (специфичность
   `.dev.theme-dark`/`.oplock`/`.virtual .device-shell-frame`,
   `iso-overlays?.devices.get(d.id)` опциональная цепочка для L6) — все три
   были задокументированы в r1 как «проверено чтением, корректно, но без
   теста»; теперь тест есть и я лично прогнал его (все ассерты `true`).
8. Прогнаны реально (не приняты по Validate) — таблица ниже.

### Гейты — что прогнано и с каким результатом

| Гейт | Прогнан | Результат |
|---|---|---|
| `Validate` на `106fdc09` | нет, зачтён по ссылке (условие задачи) | success, https://github.com/Matysh/houseplan-card/actions/runs/36161723663 |
| `npx tsc -p tsconfig.test.json` + `node scripts/fix-test-build.mjs` | да | 0 ошибок |
| `npm run bundle:sync` (`tsc --noEmit && rollup -c` + bundle-tree sync) | да, дважды (baseline и после отката мутанта) | чисто оба раза, `git status --porcelain` пуст после отката — закоммиченные `dist/**`, `custom_components/.../frontend`, `demo/srv/assets` побайтово совпадают со свежей сборкой на этом SHA |
| `node --test test/iso-stage6.test.mjs` (весь файл, 10 тестов) | да | **OK**, 10/10 `pass` |
| `node --test --test-name-pattern="AC7 the 2.5D beam is cut" test/iso-stage6.test.mjs` на немутированном коде | да | **OK** |
| Мутант `iso-sun-occluders-toward-sun` (`away`→`toSun`) применён к `src/iso-sun.ts`, тот же guard | да | **красный** — `AssertionError: between the window and the body the floor stays lit`, ожидалось `true`, получено `false` |
| Мутант `iso-sun-occluders-ignored` (доп. условие `elevation > 90`) применён, тот же guard | да | **красный** — `AssertionError: behind the body, away from the sun, the floor is in shadow` |
| Мутант `iso-sun-card-drops-occluders` (`occluders: []` в `houseplan-card.ts`) применён, пересобран, `node demo/smoke_iso_sun.mjs` | да | **красный** — `bodyCutsTheBeam: expected true, got false`; после отката и пересборки `git status` снова чист |
| `node demo/smoke_iso_sun.mjs` на немутированном коде | да | **OK**, все 20 проверок `true`, включая новые `bodyCutsTheBeam`, `beamBackWithoutBody` |
| `node demo/smoke_iso_tiles.mjs` на немутированном коде | да | **OK**, все 39 проверок `true`, включая новые `alarmBeatsHover`, `alarmBeatsSelected`, `virtualNoDashedRing`, `noBordersKeepsTiles`, `noBordersKeepsShadows` |
| `node scripts/check-docs.mjs --external --screenshots=warn` (режим обычного пуша, `classify-changes.mjs`/`validate.yml`) | да | **OK**, 7 файлов, 12 внешних ссылок; один `WARN` про устаревший фингерпринт скриншотов — унаследован, предрелизный гейт (#479), делта его не касается |
| `node scripts/smoke-select.mjs --base 2ed05031 --head HEAD` (скоуп ровно делты раунда) | да | `НЕОПРЕДЕЛЁННОСТЬ` — дифф исполняемый, но инструмент не находит символьной связи (делта — 2 файла `src/**`, изменения в основном текстовые/CSS-generation внутри уже покрытых функций); решение — см. ниже |
| `node scripts/smoke-select.mjs --base origin/dev --head HEAD` (полный охват фичи, как в r1) | да | те же 78 прямых совпадений, что в r1 (делта раунда их не меняет) — решение r1 унаследовано без повтора |
| `python -m pytest tests_backend` | нет | делта раунда не трогает ни одного `.py`-файла (`git show 106fdc09 --stat` — 0 совпадений `custom_components/.*\.py`); гейт неприменим к этой делте |
| `npm run golden:verify` | нет | делта `User-Visible: no`, ни одна золотая сцена не задета |
| `npm run invariants` | нет | делта не меняет каноническую геометрию (только презентационные occluders/CSS-эмиссию) |
| Полный `npm test` | нет, принят по Validate на этом SHA | — |

**Решение по `smoke-select --base 2ed05031 --head HEAD` (НЕОПРЕДЕЛЁННОСТЬ).**
Инструмент не связал делту ни с одним смоком символьно (изменения в
`iso-sun.ts` не тронуты вовсе — только новый юнит-тест их покрывает; изменения
в `iso-tiles.ts` — две дополнительные CSS-строки внутри уже существующей
функции). Это не разрешение ничего не прогонять (по инструкции промпта): я сам
выбрал и прогнал `smoke_iso_sun.mjs` и `smoke_iso_tiles.mjs` — ровно те смоки,
что физически упражняют изменённые функции (`computeIsoSunBeams`,
`isoTileStateCss`) через реальный рендер в браузере, и лично воспроизвёл
падение всех трёх новых мутантов на них. Остальные ~275 смоков матрицы не
запускал: делта не трогает ничего вне `iso-sun.ts`/`iso-tiles.ts`/тестов/доков.

## Находки

Нет ни High, ни Medium, ни Low. Делта раунда полностью и по существу
закрывает M1 (доказано исполнением: тест и три мутанта, все три реально
покраснели) и пять Low из шести (L1, L3, L4, L5, L6); L2 была снята ещё в r1.

## Закрытие раунда r1

| Находка | Чем закрыта | Где это видно |
|---|---|---|
| **M1** (Medium) — обрезка 2.5D-луча барьерами (физические тела, Solid-перегородки) нигде не доказана тестом; названный риск — перепутанный знак направления или длина экструзии в `directionalOccluders(input.occluders, away, travel)` | Новый юнит `test/iso-stage6.test.mjs` («AC7 the 2.5D beam is cut…», колонна на пути луча: лит перед ней, тень за ней, лит рядом) + новые ассерты `demo/smoke_iso_sun.mjs` (`bodyCutsTheBeam`, `beamBackWithoutBody`, Solid-перегородка в реальном рендере) + три мутанта реестра (`iso-sun-occluders-toward-sun`, `iso-sun-occluders-ignored`, `iso-sun-card-drops-occluders`). Все три лично применены и подтверждены красными в этой сессии (см. таблицу гейтов) | `test/iso-stage6.test.mjs:151-179`; `demo/smoke_iso_sun.mjs:99-130`; `scripts/mutation-registry.mjs:3526-3546`; код неизменён — `src/iso-sun.ts:111-114` |
| **L1** — устаревшие «alpha/hidden»-формулировки рядом с исправленным текстом | Переписаны все 4 места, проверено на противоречие соседним абзацам | `docs/DEVELOPMENT.md:231-232`, `docs/ARCHITECTURE.md:31`, `src/houseplan-card.ts:627`, `demo/benchmark_large_house.mjs:145` |
| **L2** — опечатка числа в хендоффе (не код) | Была снята уже в r1 без правки; в этом раунде править нечего | — |
| **L3** — `isoTileStateCss()` не различал тему для торца состояний | Добавлены `.dev.theme-dark.${state}` / `...iso-floor-light` со своим вызовом `edge(body,'dark',...)`, специфичность выше старых правил (проверено пересчётом), покрыто новым ассертом юнита | `src/iso-tiles.ts:113-116`; `test/iso-stage6.test.mjs:68-70` |
| **L4** — «Alert > чистый Hover» и «Alert > чистый Selected» не проверялись отдельно | Два новых прогона: реальный `mouse.move` + `alarm` без селекта/фокуса; `sel`+`alarm` без hover/focus | `demo/smoke_iso_tiles.mjs:197-200,207-221` |
| **L5** — нет теста на `.dev.virtual` (Q1: без пунктира) | Новый ассерт `virtualNoDashedRing` на `.device-shell-frame` с классом `.virtual` | `demo/smoke_iso_tiles.mjs:201-203,222` |
| **L6** — плитки/тени без стен (`show_borders:false`) не покрыты тестом | Новые ассерты `noBordersKeepsTiles`/`noBordersKeepsShadows` через реальный `setServerConfig` | `demo/smoke_iso_tiles.mjs:224-238` |

## Унаследовано из r1

Без повторной проверки, документ `docs/reviews/CODE-REVIEW-649-r1.md`,
материал — фактическое содержимое `e5ab4659`/`2ed05031` (идентично по
существу тому, что рецензировалось в r1 под старыми SHA `e59c89df`/`de452182`,
см. обоснование выше — ребейз без изменения содержимого):

- AC1 (Flat неизменен, `test/styles-split.test.mjs`, единственный вызов
  `furniturePlanScreenScale`), AC2 (геометрия/торец плитки), AC3 (коллизии
  ×1.12), AC4 (тень, таблица параметров), AC5 (рамки/приоритет — базовая
  часть, за вычетом закрытых сейчас L4-пар), AC6 (forced-colors), AC7 (формула
  луча, градиенты, стопы, ворота видимости — за вычетом закрытого сейчас M1),
  AC8 (мебель, `stroke-width`), AC9 (тема не красит стены), AC10/AC11
  (`settings.volumetric_view`, alpha-вход убран, backend-валидация), AC12
  (макеты, side-by-side), Golden/матрица, мутационный реестр (16 старых
  мутантов), бюджет бандла — все приняты по документу r1 без повторного
  прогона в этом раунде, т.к. делта `106fdc09` их не касается.
- `python -m pytest tests_backend` не прогонялся ни в r1 (нет `pytest` в
  песочнице), ни сейчас (делта не трогает Python) — тот же непокрытый гейт,
  не расширившийся.
- ~70 «слабых» совпадений `smoke-select --base origin/dev` — решение r1 не
  прогонять сохраняется без изменений (делта их не касается).

## Проверено и корректно

- M1 закрыта доказательством через исполнение, а не только чтением: юнит и
  смок падают именно там, где ожидается (перед барьером — светло, за ним —
  тень, рядом — снова светло; площадь луча уменьшается минимум на 20×50
  плановых единиц), и все три мутанта реестра лично воспроизведены красными,
  затем код и бандл возвращены в состояние `HEAD` (`git status` чист).
- L3 — фикс специфичностно корректен (новые селекторы объективно перебивают
  старые) и сегодня не меняет видимый результат ни для одного из 6
  `ISO_STATE_BODIES` (пересчитано вручную по порогам `luma<70`/`luma>0.98`),
  что подтверждает трейлер `User-Visible: no`.
- L1 — все 4 места переписаны без противоречий с соседним текстом; других
  вхождений «2.5D как alpha/hidden/opt-in» в кодовой базе не осталось
  (`grep` по изменённым и смежным файлам).
- L4/L5/L6 — только новые тесты поверх неизменного, уже корректного (по
  выводу r1) поведения; лично прогнаны, все зелёные.
- Три-way синхронизация бандла (`dist/**`, `custom_components/.../frontend`,
  `demo/srv/assets`) чиста на `106fdc09` — подтверждено дважды: один раз как
  есть, один раз после применения и отката мутанта `iso-sun-card-drops-occluders`.
- Монолит `src/houseplan-card.ts` — 12880 строк, без изменений (правка L1 в
  нём — замена текста комментария в тех же строках, не добавление).
- Трейлеры всех трёх коммитов раунда корректны; `User-Visible: no` на
  `106fdc09` обоснован построчно (доп. тесты + одна текстуально верная, но
  сегодня недостижимая ветка CSS).

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

- `python -m pytest tests_backend` — делта не трогает `custom_components/**/*.py`
  (0 совпадений в статистике коммита); не гейт этой делты.
- `npm run golden:verify` / `npm run invariants` — делта `User-Visible: no`,
  не меняет золотые сцены и не трогает каноническую геометрию модели.
- Полный `npm test` и полный `Validate` (мутанты) — приняты по зелёному
  прогону на этом самом SHA (ссылка в задаче); перегонял только те тесты и
  мутанты, что относятся к делте раунда.
- ~275 смоков вне `smoke_iso_sun.mjs`/`smoke_iso_tiles.mjs` — `smoke-select`
  с базой ровно на делту (`2ed05031..HEAD`) не нашёл символьной связи
  (НЕОПРЕДЕЛЁННОСТЬ) ни с одним из них, и содержательно делта не выходит за
  пределы `iso-sun.ts`/`iso-tiles.ts`/тестов/документации; полный прогон
  матрицы против всей фичи (78 прямых совпадений `origin/dev..HEAD`) унаследован
  из r1 без повтора.
- Реальный экран/планшет, Safari — как и в r1, недоступны в песочнице.

## Вывод

High: 0. Medium: 0. Low: 0. Делта раунда (`106fdc09`) полностью закрывает
единственную блокирующую находку r1 (M1) доказательством через исполнение — я
лично применил все три новых мутанта реестра и подтвердил, что юнит и смок
падают именно так, как заявлено в `because`, а не просто прочитал код на
доверие. Пять Low из шести получили тесты или точечные правки без побочных
эффектов (L3 пересчитан на отсутствие видимого изменения сегодня — трейлер
`User-Visible: no` корректен); L2 была снята ещё в r1. Дельта локальна и
изолирована (`src/iso-sun.ts` не изменён вовсе, `src/iso-tiles.ts` — 2 строки,
остальное — тесты/доки/бандл), новых находок не внесла.

Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0

---

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

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

- Ветка: `issue/649-25d-stage6`, коммит `106fdc096d5d` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `77286175d538a146863d0b2f80a63e9ffa20af96`
  ```
  git log --all --format='%H %T' | grep 77286175d538
  ```
- Тело issue: `e7d94f185bc9a5d2d7e168933579903e54c88a9819347cb49f0f7c35db60a9e7`
- Вердикт конвейера: `green` · High 0