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

# CODE-REVIEW-362-r1

Issue: #362 · Заход: r1 · Трек: `small` (лимит циклов код-ревью — 2, §5) ·
Вердикт: **зелёный** · блокирующих циклов израсходовано 0/2

Ветка `issue/362-decor-device-inert`. Хендофф был на `fafd3601`; конвейер
привёл ветку к `dev` перед ревью (поверх легло 3 коммита `dev`,
`fafd3601 → f57a0c08`, вершина `f57a0c08` "fix: make devices inert in the
Background editor"). Ветка полностью содержит `origin/dev`
(`merge-base(HEAD, origin/dev) == origin/dev`), т.е. это честный fast-forward
rebase без потери коммитов. Разбор — полный (это первый заход, и рёбейз того
требует по §7.2 в любом случае).

## Скоуп

Контракт (тело issue, small-track ТЗ, зелёное спек-ревью r1): в редакторе
Подложка (`mode-decor`) вся presentation-subtree устройства (ядро, 44px
псевдо-хит-область, shell/frame, капсула значения, LQI/бейджи, pulse,
opening-lock сателлиты) должна быть инертна к hit-testing, а нажатие в той же
точке — доставаться активному инструменту Подложки. View и Устройства не
меняются. Задача входит в J4/J6 (`docs/SCOPE.md`) и восстанавливает
инвариант, уже задокументированный в `docs/DECOR-EDITOR.md` (opacity 0.35,
устройства вне magnet targets).

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

Дешёвые гейты (обязательны всегда, прогнаны на `f57a0c08`):

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | PASS, без вывода |
| Unit | `npm test` | PASS — 1511 passed, 1 skipped, 0 failed (`# tests 1512`) |
| Build + bundle sync | `npm run build && npm run bundle:sync`, затем `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` и `cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` | PASS, три копии бандла побайтово идентичны |
| any-бюджет | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | PASS — «Новых any нет» (32 добавленные строки в 2 файлах) |
| Whitespace | `git diff --check origin/dev...HEAD` | PASS, без вывода |
| Docs fingerprint | `node scripts/check-docs.mjs` (обязателен — diff трогает `src/**`) | **RED** ожидаемо: `ERROR screenshot source fingerprint is stale`. Проверено сравнением: тот же гейт на `origin/dev`@`9431a5ce` (временный `git worktree`, чистая сборка) — **PASS** («Documentation checks passed»). Значит, стал stale именно из-за этой задачи. Это не эквивалент #230/#234 (там шаг вообще не прогоняли и находка терялась): отпечаток считается по всему `src/**`, поэтому *любая* правка фронтенда обязана его инвалидировать — «выбирать тут нечего» (см. текст задания ревью). Пересъёмка — отдельная джоба `Docs screenshots` (`workflow_dispatch`) с последующим `npm run docs:accept -- --reviewed`, коммит делает человек (`PROCESS.md` §8); это не часть цикла реализации и не повод для жёлтого вердикта, но обязана быть сделана до релиза — фиксирую как открытый пункт для релиз-менеджера, а не как находку к этому issue. |

По необходимости (определено diff'ом и AC):

- `node scripts/smoke-select.mjs --base origin/dev --head HEAD` — выборка:
  **прямое совпадение (12)**: `smoke_decor.mjs`, `smoke_inert_openings.mjs`,
  `smoke_isometric_live_touch.mjs`, `smoke_modes.mjs`,
  `smoke_space_settings.mjs`, `smoke_esc_dialogs.mjs`, `smoke_feedback_v2.mjs`,
  `smoke_lock_action.mjs`, `smoke_open_passage.mjs`,
  `smoke_opening_binding.mjs`, `smoke_registryless_opening.mjs`,
  `smoke_touch_tips.mjs`; плюс 29 «слабых» (одно распространённое имя —
  `_mode`/`stopPropagation`), решение по ним — не гонять: диф не трогает то
  поведение, о котором они спорят (wall/room/cover/furniture инструменты вне
  Подложки), совпадение по имени случайно.
  Прогнаны все 12 прямых (свежий бандл, `node demo/<name>.mjs` каждый) —
  **все PASS**, включая `smoke_decor.mjs`, обновлённый этой задачей.
  Опенинг-смоки (`smoke_inert_openings`, `smoke_lock_action`,
  `smoke_esc_dialogs`, `smoke_open_passage`, `smoke_opening_binding`,
  `smoke_registryless_opening`) прогнаны специально: правка тронула JS-гвард
  `.oplock`-обработчика клика (см. находку Low ниже), эти смоки — прямая
  regression-проверка того, что `View`-поведение замка (`_openingInfo`,
  диалог) не сломано. `smoke_modes.mjs` подтверждает регрессии нет в
  `Devices` (`devDragWorks`, `devClickOpensEditor` — оба true).
- `npm run golden:verify` — **не гонялся**. Diff не меняет ни одного
  painted-свойства: `opacity`/цвет/geometry устройств не тронуты, единственное
  новое CSS-свойство — `pointer-events`, которое не участвует в растеризации.
  Единственная удалённая строка (`.stage.mode-decor .oplock { pointer-events:
  none }`) была вычислительно избыточна и до правки: базовое правило `.oplock`
  уже задаёт `pointer-events: none`, `auto` включается только
  `.stage.mode-view .oplock` — вычисленное значение в `mode-decor` не
  изменилось. AC4 в самом ТЗ также утверждает «golden без переприёмки».
- `python -m pytest tests_backend` — не гонялся, diff не трогает
  `custom_components/**/*.py`.
- `node scripts/model-invariants.mjs` — не гонялся, diff не меняет геометрию,
  `layout`, `marker.space` или `open_spans`.
- performance-профили — не названы в AC, не гонялись.

**«Одно число — один источник»**: диф не вводит и не меняет ни одной новой
пользовательской величины. Единственное число рядом с изменением — opacity
`0.35`, которое уже было односточником через `architectureOpacity` в
`_modeVisualState`/`houseplan-card.ts:1212,1394`, потребляемое CSS-переменной
`--hp-mode-architecture-opacity`; эта задача её не трогает.

### Тест умеет падать — проверено фактическим ревертом, не заявлением

Дважды откатывал часть фикса на рабочем дереве (сборка, прогон смока/юнита,
затем восстановление файла из бэкапа, повторная сборка и `cmp` трёх копий
бандла — дерево вернулось чистым, `git status` пуст):

1. Откат CSS-правила `.stage.mode-decor .devlayer, .stage.mode-decor
   .devlayer *, .stage.mode-decor .dev::before` к старому
   `.stage.mode-decor .devlayer { pointer-events: none; }` →
   `node demo/smoke_decor.mjs` **упал** на трёх ассертах:
   `decorDeviceCoreFallsThrough`, `decorDeviceCapsuleFallsThrough`,
   `decorDeviceSubtreeIsPointerInert` (ожидалось true, получено false).
2. Откат гварда в `_pointerDown` к старому `if (this._mode === 'plan')
   return;` → `node demo/smoke_decor.mjs` **упал** на 10 ассертах:
   `decorDeviceHandlersFailClosed`, `lineStartsThroughDeviceCapsule`,
   `rectStartsThroughDeviceCore`, `textStartsThroughDeviceCore`,
   `furniturePlacesThroughDeviceCore` и 5 каскадных (`lineToolStartsDraft` и
   др. — устройство перехватило `_drag`, что сломало последующие проверки
   инструментов).

`test/device-marker-polish-contract.test.mjs` — новый юнит-тест регексами
сверяет ровно те же строки кода (CSS-правило, порядок гварда/`stopPropagation`
в `_clickDevice`, гварды `_pointerDown/_pointerMove/_pointerUp`, условия в
`@pointerover`/`@pointermove`); ревертнутые выше строки буквально не совпали
бы с этими регексами — падение подтверждено тем же способом, без отдельного
повторного прогона.

## AC — разбор

| AC | Статус | Доказательство |
|---|---|---|
| AC1 (hit-testing инертен для ядра/капсулы) | **Выполнен** | `smoke_decor.mjs`: `decorDeviceCoreFallsThrough`, `decorDeviceCapsuleFallsThrough`, `decorDeviceSubtreeIsPointerInert` — true; подтверждено умением падать (см. выше). CSS-специфичность проверена чтением: `.stage.mode-decor .devlayer *` (0,2,0) бьёт одноклассовые `.dev`/`.device-shell-frame` `pointer-events: auto` (0,1,0) в `devices.styles.ts:144,213`; `::before` — отдельным явным селектором, т.к. `*` не матчит псевдоэлементы. |
| AC2 (Line/Rect/Text/Furniture сквозь устройство) | **Выполнен** | `smoke_decor.mjs`: `lineStartsThroughDeviceCapsule`, `rectStartsThroughDeviceCore`, `textStartsThroughDeviceCore`, `furnitureToolArmedThroughDeviceCore`+`furnitureTargetFallsThroughDeviceCore`+`furniturePlacesThroughDeviceCore` — все true. Умение падать подтверждено (пункт 2 выше). |
| AC3 (нет device-побочных эффектов) | **Выполнен** | `decorDeviceHandlersFailClosed` (serviceCalls=0, wsCalls=0, `_tip`/`_infoCard`/`_drag` не выставлены) при прямом dispatch pointerover/pointerdown/click — true. Прочитан код: `_clickDevice`/`_pointerDown` возвращают до какого-либо побочного эффекта при `_mode ∉ {view, devices}`; `_pointerMove`/`_pointerUp` (drag/selection/`_savePos`) — гвард `_mode !== 'devices'`; long-press таймер живёт только в view-ветке `_pointerDown`, недостижим в Background. |
| AC4 (opacity 0.35 стабилен, смена инструмента не меняет пассивность) | **Выполнен** | `decorDeviceLayerIsTranslucent` (opacity≈0.35) — true; core/capsule fall-through и through-device постановка проверены при 4 разных `_decorTool` (line/rect/text/furniture). Golden не переприёмывался — обоснование в разделе «как проверялось» (paint не меняется). |
| AC5 (View/Devices не деградировали) | **Выполнен** | Регрессионные смоки: `smoke_decor.mjs` `visibleInView`/`inertInView` (для decor-фигур, не устройств — существующий несвязанный ассерт, не трогался); `smoke_modes.mjs` `devDragWorks`/`devClickOpensEditor` — true (Devices editor). View-специфичный `_pointerDown`-путь (long-press → `_infoCard`) не тронут кодом (ветка `if (this._mode === 'view')` идёт первой и делает `return` до нового гварда — гвард лишь сузил, какие ещё режимы доходят дальше). Opening-lock смоки (6 штук, список выше) — все PASS, без регрессии `_openingInfo`/View-клика. |
| AC6 (нет config/i18n/perf/touch изменений) | **Выполнен** | `git diff --stat` — только `src/houseplan-card.ts`, `src/styles/plan.styles.ts`, `demo/smoke_decor.mjs`, `test/*.mjs`, `docs/*`, бандлы; ни одного i18n/schema файла. Новых listener/observer/render-путей нет — все изменения это ранние `return` внутри уже существующих обработчиков плюс чисто декларативный CSS-каскад. Pointer/pen/touch не различаются нигде в изменённом коде (`PointerEvent`-путь общий для всех `pointerType`), поэтому инертность автоматически распространяется на все типы указателя без отдельного touch-контракта. |

## Находки

### Low — верифицировано чтением, фикс не требуется

`_openingInfo`-обработчик клика по `.oplock` (`src/houseplan-card.ts`,
`@click` в `_renderOpeningLocks`) получил тот же паттерн гварда
(`if (this._mode !== 'view') return;` до `stopPropagation()`), хотя контракт
ТЗ явно называет «opening-lock satellites» частью инертной subtree (пункт 1),
а сам AC1 в таблице доказательства называет только `.dev`/`::before`/
`.device-shell-frame`/capsule — без oplock. Ни один AC, ни новый блок
`smoke_decor.mjs` не проверяют это напрямую для `mode-decor`.

Прочитано и проверено: `.oplock` уже до этой задачи имел базовое
`pointer-events: none` (`dialogs.styles.ts:167`, комментарий «inert while
editing; clickable in View (rule below)»), и `auto` включался только
`.stage.mode-view .oplock` (`plan.styles.ts:488`). То есть в реальном браузере
хэндлер и до, и после правки недостижим кликом мыши/тача в `plan`/`devices`/
`decor` — CSS уже резал hit-testing независимо от этой задачи. Изменение —
чисто defense-in-depth, симметричное остальному фиксу (контрактный пункт 6:
«не полагаться только на `pointer-events: none` родителя»), и не меняет
наблюдаемое поведение ни в одном режиме. 6 opening-related смоков (список
выше) подтверждают отсутствие регрессии в View. Не блокирует: находка не
меняет функциональность и не требует правки в этом issue.

### Не найдено High/Medium

Ни одного High. Ни одного Medium — ни в скоупе, ни вне его. Новый issue не
заводится.

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

- Двойная защита (CSS-каскад + fail-closed JS-гварды) реализована так, как
  требует контракт: ни один слой не полагается только на другой.
- CSS-специфичность нового правила действительно перебивает все три
  `pointer-events: auto` в `devices.styles.ts`, включая псевдоэлемент
  `::before`, отдельно вынесенный, поскольку универсальный селектор `*` его
  не матчит.
- Гварды в обработчиках копируют структуру существующего `_ctxDevice`
  (правый клик — уже был fail-closed вне View до этой задачи, не тронут) —
  согласованный паттерн по всей поверхности.
- `_keyDevice` (клавиатурная активация) уже был защищён гвардом `_mode
  !== 'view' && _mode !== 'devices'` до этой задачи — не тронут, риска нет
  (в Background `tabindex` не проставляется, элемент не фокусируем).
- И новый юнит-тест, и новый блок смока проверены на умение падать прямым
  ревертом кода (см. выше) — не приняты на слово автора.
- Терминология CHANGELOG/DECOR-EDITOR.md сверена с `docs/USER-GUIDE.ru.md`
  и `docs/USER-GUIDE.md` («Подложка»/Background editor) — совпадает.
- Трейлеры коммита `f57a0c08`: `Issue: #362`, `User-Visible: yes` — оба
  changelog (`docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`) правлены в том же
  коммите.
- Три копии бандла (`dist`, `custom_components/.../frontend`,
  `demo/srv/assets`) побайтово идентичны после `npm run bundle:sync`.

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

- `npm run golden:verify` и `pytest tests_backend` — не гонялись, обоснование
  выше (diff не меняет paint и не трогает Python).
- Полный набор `demo/smoke_*.mjs` (не выборка) — не гонялся, диф не задевает
  геометрию/стены/проёмы вне уже прогнанных opening-смоков; полный набор —
  предрелизный гейт.
- Performance-профили — не названы в AC, не запускались.
- Пересъёмка docs-скриншотов (гейт `docs` в CI) — не выполнялась и не может
  быть выполнена в этом цикле (нужна выделенная джоба `Docs screenshots` на
  точном Chromium плюс `--reviewed`-приёмка человеком); зафиксировано выше как
  открытый пункт для релиз-менеджера, не как находка к этому issue.