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

# CODE-REVIEW-113-r1 — честный optional-контракт `_spaceModel()`

- **Issue:** https://github.com/Matysh/houseplan-card/issues/113
- **ТЗ:** `docs/specs/113-optional-space-model.md`, ревью ТЗ — `docs/reviews/SPEC-REVIEW-113-r1.md` (зелёный, Medium-1 → #184, не блокирует)
- **Диапазон:** `origin/dev..HEAD` = `5f02dd3` (docs: specify optional space model contract), `7660868` (docs: review document), `09b5a74` (Make empty space model explicit)
- **Коммит реализации:** `09b5a74e866a595138bd93703fd09a4860bf7757`
- **Цикл:** r1/4
- **Роль:** ревьюер кода (Claude), свежая сессия, без контекста реализации Codex

## 1. Скоуп

Единственный коммит класса A/B по существу — `09b5a74`. Он:

- меняет `_spaceModel(): SpaceModel` → `_spaceModel(): SpaceModel | undefined` и вводит
  `_spaceModelById(id): SpaceModel | undefined` (exact lookup, без first-space fallback);
- выносит чистые селекторы в новый файл `src/space-model-selection.ts`
  (`selectActiveSpaceModel`, `selectSpaceModelById`) с unit-тестами;
- классифицирует и правит все ~45+ производственных обращений к `_spaceModel()` по классам
  §5 ТЗ (lifecycle/render-гейт, event handlers редакторов, pure render helpers, paths с уже
  доказанным space);
- вводит `_syncEmptySpaceState()` — вызываемый из `willUpdate()` guard, который один раз на
  переход non-empty→empty снимает pointer capture, обрывает жесты/drag/pan/pinch/resize/vac-fit,
  закрывает draft/history/space-scoped диалоги, отменяет debounced config write и возвращает
  `_mode` в `'view'`; повторно вооружается при следующем appearance/disappearance цикле;
  добавляет `Debounced.cancel()`;
- добавляет `demo/smoke_optional_space_model.mjs`, `test/space-model-selection.test.mjs`,
  `test/optional-space-model-contract.test.mjs`, мутационный guard
  `empty-space-cleanup-disabled` в `scripts/mutation-gate.mjs`;
- документирует инвариант в `docs/ARCHITECTURE.md` и добавляет чек-лист в `docs/TESTING.md`.

`User-Visible: no` — согласовано с владельцем на этапе ТЗ (§13 спецификации): видимое поведение
при существующих пространствах не меняется (гейт `render()` на `model.length === 0` уже отделял
пустой план от общего пути, старый код уже безопасно работал по факту порядка вызовов). Изменение
устраняет класс латентных крашей (#111 повторно), не новую пользовательскую возможность.
Соответствует, обе changelog-правки в этом коммите отсутствуют обоснованно.

Medium-1 из ревью ТЗ (#184, fallback-семантика §6 для явного `id`) вынесен отдельным issue,
не расширяет #113; ниже проверено, что реализация фактически перевела все стабильные-id call
sites на exact lookup (сильнее, чем требовало формально необязательное AC8) — см. §4.

## 2. Как проверялось — таблица гейтов

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | OK, без ошибок |
| Unit | `npm test` | `811/811` — совпадает с заявленным в хендоффе и с `npm run inventory` |
| Build + 3 копии бандла | `npm run build` затем `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` и `cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` | OK, обе сверки — байт-в-байт совпадение |
| Именованный smoke (AC3–AC6) | `node demo/smoke_optional_space_model.mjs` | OK, все 9 подпроверок `true` |
| Именованный smoke (AC6, read-only cold start) | `node demo/smoke_readonly_cold_start.mjs` | OK, все 13 подпроверок `true` |
| Мутационный guard AC10/AC4/AC5 | `node scripts/mutation-gate.mjs --id=empty-space-cleanup-disabled` | `поймано 1 из 1` — чистый прогон зелёный, мутант (`if (empty) return;` вместо `if (this._emptySpaceStateActive) return;`) красит смок, т.е. тест **умеет падать** |
| Регрессия непустого пути (поверхности: markers/positions, wall-thickness, free walls/columns, opening preview, open/close wall, isometric contract, merge/split, vacuum fit, corner split, draw-wall thickness) | `node demo/smoke_marker_stay.mjs`, `smoke_wall_thickness.mjs`, `smoke_free_walls.mjs`, `smoke_opening_preview.mjs`, `smoke_openwall.mjs`, `smoke_isometric_contract.mjs`, `smoke_merge_split.mjs`, `smoke_vacuum.mjs`, `smoke_split_corner_wall.mjs`, `smoke_draw_wall_thickness.mjs` | OK, все 10 зелёные |
| Process gate | `node scripts/process-gate.mjs --issues` | `гейт пройден, предупреждений 0` |

**Не прогонялось, и почему:**

- **Полный набор из 135 браузерных смоков** — diff трогает десятки геометрических хелперов
  (`_frameOf`, `_isoScene`, wall/opening/decor/room helpers), но во всех них новый код — это
  *guard, добавленный до* существующей логики, срабатывающий только при `model.length === 0`.
  При непустой модели `_spaceModel()` = `models.find(...) ?? models[0]`, что при непустом массиве
  никогда не даёт `undefined` — путь `if (!space) return …` в каждом таком месте логически
  недостижим для непустого плана (проверено чтением, не исполнением, во всех местах диффа).
  Прогнан репрезентативный набор из 10 смоков по каждой тронутой геометрической поверхности
  (таблица выше) — все зелёные, что подтверждает отсутствие регрессии на практике, а не только
  по рассуждению. Прогон всех 135 не добавил бы информации, пропорционально задаче не прогонялся
  (PROCESS §8).
- **`npm run golden:verify`** — не прогонялся. По той же причине (недостижимость нового кода
  при непустой модели, подтверждённая чтением `render()`: `if (!model.length) return html\`…\`;`
  идёт раньше `const space = this._spaceModel(); if (!space) return nothing;`, и второй `return`
  математически недостижим, когда `model.length > 0`) видимый результат при непустом плане не
  меняется; для пустого плана экран тот же самый JSX-блок, что и раньше диффа (не тронут).
  Пиксельного риска нет, golden не запускался осознанно, а не пропущен по умолчанию.
- **`python -m pytest tests_backend`** — не тронут ни один файл `custom_components/**/*.py`,
  бэкенд не запускался.
- **Performance-профили** — ни в AC, ни в диффе не затронут ни один hot render path кроме
  добавления O(1)-проверок в начале функций и одного one-shot `querySelectorAll('*')`,
  срабатывающего не на каждый рендер, а один раз на реальный переход в пустой план (проверено
  чтением `_syncEmptySpaceState`/`willUpdate`). Не прогонялись.
- Оставшиеся ~120 смоков вне таблицы (isometric-live-touch и т.п. поверхности, которые дифф не
  трогает напрямую) — не прогонялись; сознательное решение, а не молчаливый пропуск.

## 3. Проверка AC (docs/specs/113-optional-space-model.md §10)

| AC | Доказательство | Статус |
|---|---|---|
| AC1 optional тип у `_spaceModel`/exact варианта | `npx tsc --noEmit` зелёный при сигнатуре `SpaceModel \| undefined`; `test/optional-space-model-contract.test.mjs` проверяет regex-ом наличие точной сигнатуры обоих методов | доказано unit-тестом, тест умеет падать (см. §4) |
| AC2 все production call sites без non-null assertions | тот же contract-test: `assert.doesNotMatch(source, /this\._spaceModel\(\)\s*!/ …)` плюс запрет наготовой `.` без `?.`/guard | доказано unit-тестом, экспериментально подтверждена ловля регрессии (см. §4) |
| AC3 empty render/update/resize/theme/WS не бросают исключений | `smoke_optional_space_model.mjs`: `deleteLastRendersEmpty`, `wsEmptyAbortsLiveGesture`, `emptySurvivesThemeResizeReadonly` — все `true`, без падения страницы | доказано браузерным smoke (исполнение) |
| AC4 удаление последнего space оставляет рабочий empty-state | `deleteLastRendersEmpty`, `createFlowSurvivesEmpty` | доказано smoke |
| AC5 pending pointer/drag/editor action abort без history/persist/service call | `deleteLastAbortsEditorState`, `deleteLastCancelsPendingWrite`; проверено чтением, что `_drag`/`_pointers` очищаются **до** какого-либо `pointerup`-коммита (коммит живёт в up-хендлерах, которые физически не вызываются после очистки состояния) | смок + чтение кода up-хендлеров |
| AC6 read-only cold start с `spaces: []` стабилен | `emptySurvivesThemeResizeReadonly` (в `smoke_optional_space_model.mjs`, `_serverCanWrite=false`) + `smoke_readonly_cold_start.mjs` (непустой read-only путь, не регрессировал) | доказано smoke |
| AC7 non-empty View/editors — pixels/actions без изменений | логически недостижимый guard (см. §2) + 10 регрессионных smoke по тронутым поверхностям, все зелёные | проверено чтением + smoke, golden сознательно не прогонялся (см. §2) |
| AC8 missing explicit stale id не мутирует первый space | `test/space-model-selection.test.mjs`: `selectSpaceModelById(spaces, 'stale') === undefined`; `optional-space-model-contract.test.mjs` проверяет, что `_livePos`, `_vacPlanRoomAnchors`, `_vacStartFit`, `_labelMove`, `_rlResizeMove` используют `_spaceModelById`; лично сверено чтением, что все явные call sites (`_livePos`, `_vacPlanRoomAnchors`, `_vacStartFit`, `_labelMove`, `_rlResizeMove`, `_saveMarker`'s `targetSpaceModel`) действительно вызывают `_spaceModelById`, а не `_spaceModel(id)` (метод с параметром `id` больше не существует) | доказано unit-тестом + подтверждено чтением исходника |
| AC9 active-id fallback при непустой модели сохраняет legacy behavior | `test/space-model-selection.test.mjs`: `selectActiveSpaceModel(spaces, 'stale') === spaces[0]`, `selectActiveSpaceModel(spaces, null) === spaces[0]` | доказано unit-тестом |
| AC10 type/source gates не пускают прежнюю ложную сигнатуру | `node scripts/mutation-gate.mjs --id=empty-space-cleanup-disabled` → `поймано 1 из 1`; отдельно вручную подтверждено, что regex контракт-теста ловит намеренно испорченный naked-deref (см. §4) | доказано мутационным тестом (исполнение) |

## 4. Дисциплина «тест умеет падать» — что лично проверено исполнением

- **Мутационный гейт**: `node scripts/mutation-gate.mjs --id=empty-space-cleanup-disabled`
  фактически применяет патч (`if (this._emptySpaceStateActive) return;` →
  `if (empty) return;`), пересобирает и гоняет `smoke_optional_space_model.mjs` — результат
  `тест покраснел, как обязан`. Не «предположительно ловит», а подтверждённая красная реакция.
- **Source-contract regex**: собран мутированный в памяти текст (без изменения репозитория) с
  заменой `this._spaceModel()?.bg` → `this._spaceModel().bg` и прогнан ровно тем же regex, что
  использует `optional-space-model-contract.test.mjs`
  (`/this\._spaceModel\(\)\s*\./`) — совпадение `true`, то есть тест обязательно упадёт при
  возврате naked-deref. Проверка выполнена вживую через `node -e`, не только прочитана.

## 5. Находки

Нет находок High. Нет находок Medium.

**Low-1** (не блокирует, не требует правки — оставлено с записью). `_syncEmptySpaceState()` не
сбрасывает `_splitSel`, `_mergeDialog`, `_wallDialog` при переходе в пустой план (ТЗ §7
перечисляет конкретный список, и эти три в него не входят напрямую). Разобрано чтением: все три
рендерятся только внутри ветки `render()` после `if (!model.length) return …` и
`if (!space) return nothing;`, то есть при пустом плане не видны; `_splitClick`/аналоги уже
содержат защитный код на случай "roomId не найден в моделе" (строки ~11239–11244), который
сработает безопасно, если пользователь пересоздаст план с другими id комнат и продолжит с
залипшим `_splitSel`. Наблюдение косметическое (не входит ни в один пользовательский сценарий из
ТЗ, не даёт сбоя) — снимаю без issue.

**Low-2** (не блокирует). `render()`'s `if (!space) return nothing;` (после
`const space = this._spaceModel();` в непустой ветке) недостижим при `model.length > 0` — то же
верно и для нескольких других мест диффа (см. §2/AC7). Это защитный код на случай будущего
разъединения инварианта «модель непуста ⇒ активный space существует», не дефект; TS не может
доказать эту связь сам, так что явная проверка оправдана как type-safety, а не как признак
недоделки. Отмечено, правки не требуется.

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

- `_model` (геттер) строится через `spaceModels(cfg).map(...)` 1:1 по `cfg.spaces`, без
  фильтрации записей; `_renderCfg` сохраняет длину `spaces` (заменяет только контент одного
  элемента при активном resize-preview). Значит проверка `_syncEmptySpaceState` на
  `this._serverCfg.spaces.length === 0` и проверка `render()` на `this._model.length === 0`
  наблюдают одно и то же состояние — не расходятся (прочитано `_buildModel`, `spaceModels`,
  `_renderCfg`).
- `_syncEmptySpaceState()` вызывается из `willUpdate()` **до** `_captureRenderDeviceSnapshot()`
  на каждом обновлении (не только при смене `_serverCfg`), но благодаря флагу
  `_emptySpaceStateActive` весь путь очистки — не более двух проверок свойств при непустой
  модели; повторный вход в пустое состояние (после пересоздания и нового WS-опустошения) снова
  срабатывает — подтверждено вторым циклом внутри самого smoke.
- Все guard'ы в event-хендлерах редакторов (`_physicalDown`, `_openingClick`, `_opPointerDown`,
  `_physicalRotateDown`, `_savePhysicalDialog`, `_commitMerge`, `_commitRoom`, `_saveMarker` и
  далее по диффу) расположены **до** `stopPropagation`/`capturePointer`/мутации диалога —
  соответствует ТЗ §5.2 «guard до side effects». Проверено построчным чтением каждого изменённого
  метода в диффе, не выборочно.
- `_saveMarker` — самая тяжёлая перестройка диффа: `targetSpaceModel` (через
  `_spaceModelById(explicitSpaceId)` либо активный `_spaceModel()`) вычисляется и проверяется
  (`if (!targetSpaceModel) return;`) до `this._markerDialog = { ...dlg, busy: true }` — то есть до
  первого наблюдаемого побочного эффекта транзакции. Старый код вместо этого читал
  `this._spaceModel(space || undefined).vb` внутри `try`, что при пустой модели тип обещал
  безопасным, а исполнение — падало; теперь путь физически не достижим без валидной модели.
- `_isoSource`/`_isoScene`/`_frameOf` — все места, где сигнатура стала `| null`, имеют парный
  `if (!x) return …` у каждого вызывающего (7 точек использования `_isoScene()` в файле,
  проверены все, не выборочно).
- `npx tsc --noEmit` зелёный — это, в частности, доказывает, что каждый параметр, куда
  «доказанный» `SpaceModel` передаётся вниз по вызовам (§5.4 ТЗ), действительно набран нешироким
  (не `| undefined`) типом на входе — компилятор не пропустил бы несовпадение, обходов через `any`
  в диффе не найдено при чтении.
- Коммит `09b5a74` несёт `Issue: #113` и `User-Visible: no`; изменений в `docs/CHANGELOG*.md` нет
  и не требуется. `docs/ARCHITECTURE.md`/`docs/TESTING.md` обновлены в том же коммите.
- `node scripts/process-gate.mjs --issues` зелёный на этом диапазоне.

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

- Полный браузерный набор (135 смоков) и `golden:verify` — обоснование сужения в §2.
- `pytest tests_backend` — класс A/B бэкенда не тронут.
- Performance-профили — не названы в AC, hot-path не тронут (обоснование в §2).
- Не проверялось поведение при повреждённой модели с дублирующимися id (явно вне скоупа, ТЗ §3).
- Не перепроверял Medium-1/#184 по существу — это отдельный issue, не в диапазоне этого код-ревью.

## 8. Вердикт

Все AC1–AC10 доказаны — либо исполняемым тестом с подтверждённой способностью упасть (unit,
browser smoke, mutation gate), либо явной записью «проверено чтением, не исполнением» с указанием
конкретных строк/инвариантов. High: 0. Medium: 0. Two Low observations waived with a note, no new
issue required.

**Вердикт: зелёный · цикл r1/4 · High: 0 · Medium: 0 → нет · Документ: docs/reviews/CODE-REVIEW-113-r1.md**