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

# CODE-REVIEW-400-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/400
- ТЗ: `docs/specs/400-beta-polish.md` (r1), ревью ТЗ зелёное (комментарий 2026-08-31T04:44:56Z)
- Диапазон: `origin/dev..HEAD`, HEAD на момент разбора и на момент вердикта — `73ecfbd1d74a6d194f62e8e83766294018f8eb81`
- Заход r1 (первый код-ревью этой задачи), блокирующих циклов израсходовано 0 из 4

## Скоуп

Три несвязанные правки из ТЗ:

1. Угловые ручки рамки декора (`.dtframe`) рисуются последними, чтобы забирать хит у осевых на мелкой мебели (AC1/AC2).
2. `_alignCandidates` в режиме `devices` исключает перетаскиваемый маркер по `_deviceDrag`, а не по мёртвому `_drag` (AC4/AC5).
3. Решение по 38 help-строкам #86 зафиксировано в `docs/ARCHITECTURE.md`: остаются в initial-чанке, с числом и причиной (AC3/AC6).

Коммиты: `60c211c8` (ТЗ), `532743b0` (документ ревью ТЗ), `fe3b85c0` (реализация,
оба changelog в одном коммите с `User-Visible: yes`), `73ecfbd1` (пересборка
бандлов + пересъёмка двух doc-скриншотов, `User-Visible: no`). Трейлеры на всех
четырёх в порядке.

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

Материал — `git diff origin/dev...HEAD`, без ручного тестирования. Ниже —
таблица гейтов с результатами; часть прогнана заново, часть свежих чисел взята
из хендоффа и перепроверена.

| Гейт | Команда | Результат |
|---|---|---|
| typecheck | `npx tsc --noEmit` | чисто |
| unit | `npm test` | 1668 tests, 1667 pass, 0 fail, 1 skipped — совпадает с хендоффом |
| build + сверка бандлов | `npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | совпадают; `npm run bundle:sync` не внёс изменений (дерево уже синхронизировано в `73ecfbd1`) |
| any-гейт | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | 24 добавленные строки, новых `any` нет |
| check-docs | `node scripts/check-docs.mjs` | обязателен, т.к. diff трогает `src/**`: чисто (7 файлов, 10 внешних ссылок) |
| бюджет | `npm run bundle:budget` | initial 285 425 / 300 000 — не вырос против заявленного; отдельный варнинг про запас < 15 000 Б — фоновый (#367), не следствие этой задачи |
| смок-выборка | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 8 «прямых совпадений» по символам `_drag`/`_deviceDrag`: `smoke_align_guides`, `smoke_drag_bounds`, `smoke_decor`, `smoke_device_position_history`, `smoke_grid_snap`, `smoke_modes`, `smoke_optional_space_model`, `smoke_pan_any_zoom` |
| смоки (прямое совпадение + целевые AC) | `node demo/smoke_{align_guides,drag_bounds,decor,device_position_history,grid_snap,modes,optional_space_model,pan_any_zoom,furniture_polish}.mjs` | все 9 зелёные, прогнаны заново вживую |
| мутанты (полный, дорогой прогон — оправдан, т.к. это прямая проверка «тест умеет падать» для AC1/AC4) | `node scripts/mutation-gate.mjs --id=furniture-edge-handles-steal-the-corner` | **красный**: «тест остался зелёным на сломанном коде», поймано 0 из 1 — находка ниже |
| мутанты | `node scripts/mutation-gate.mjs --id=align-guides-exclude-dead-source` | зелёный: «тест покраснел, как обязан», поймано 1 из 1 |

Не прогонялось: `npm run golden:verify` (обоснование — см. «Что проверено»),
`python -m pytest tests_backend` (diff не трогает `custom_components/**/*.py`),
`node scripts/model-invariants.mjs` (diff не трогает геометрию/ссылки на неё —
ни рёбер комнат, ни толщины, ни `layout`, ни `marker.space`, ни `open_spans`),
performance-профили (не названы в AC, diff не на горячем пути рендера плана),
полный набор смоков (диф — два файла с точечными правками, широкая выборка
`scripts/smoke-select.mjs` уже покрывает все прямые совпадения; расширять до
всего дерева здесь непропорционально задаче).

## Находки

### Medium (в скоупе задачи — чинится в этом issue)

**M1. Мутант `furniture-edge-handles-steal-the-corner` не воспроизводит регрессию, которую обязан ловить (AC1).**

`scripts/mutation-gate.mjs:749-759`. Патч мутанта:

```
find:    "      ${/* #400: corners LAST."
replace: "      ${/* mutant: corners no longer last."
```

Это правка **внутри JS-комментария** в `src/houseplan-card.ts:8475` — она не
меняет порядок отрисовки `sides.map(...)` / `corners.map(...)`, только текст
внутри `/* ... */`. Комментарии не влияют на поведение шаблона: физический
порядок двух блоков в исходнике остаётся прежним (`sides` перед `corners`),
и «сломанный» бандл рендерит рамку так же, как исправленный.

**Воспроизведено исполнением**, не расчётом:

```
$ node scripts/mutation-gate.mjs --id=furniture-edge-handles-steal-the-corner
ok   чистый прогон: node demo/smoke_furniture_polish.mjs
FAIL furniture-edge-handles-steal-the-corner: тест остался зелёным на сломанном коде
поймано 0 из 1
```

Второй мутант (`align-guides-exclude-dead-source`) свою регрессию ловит верно
(«поймано 1 из 1», проверено тем же способом) — дефект локален к первому пункту.

Коммит `fe3b85c0` утверждает «Both mutants run by hand: reverting the paint
order reddens the 40 cm probe» — это, видимо, было проверено вручную корректной
правкой (перестановкой блоков), но то, что легло в постоянный реестр
`scripts/mutation-gate.mjs` (файл класса B, который будет гонять
`.github/workflows/mutation-gate.yml` перед каждым стабильным релизом без
участия человека), эту регрессию не ловит. AC1 в ТЗ прямо называет мутант как
доказательство «тест умеет падать» — сейчас это неверно для постоянного
артефакта, а не только для разового ручного прогона.

**Почему Medium, а не High**: сама функциональная правка верна и доказана
живым браузерным смоком на реальном DOM (`smallFurnitureCornerWinsTheHit: true`,
`largeFurnitureKeepsBothHandles: true` — прогнано заново вживую, не только по
хендоффу). Пользователь получает исправленное поведение уже сейчас. Ломается
не продукт, а будущая защита от регресса — обнаружится не раньше, чем перед
следующим стабильным релизом, когда её прогонят по-настоящему, и к тому
моменту будет поздно понять, что она никогда не работала.

**Ожидаемо**: патч мутанта должен реально возвращать `corners` перед `sides`
(или иным способом менять фактический порядок рендера), а не текст комментария.
Проверка приёмки: `node scripts/mutation-gate.mjs --id=furniture-edge-handles-steal-the-corner` → «поймано 1 из 1».

### Low (снимаются с записью, доработки не требуют)

**L1. AC4 доказан не тем видом теста, что назван в ТЗ.**

План тестов ТЗ называет для AC4 «юнит на `_alignCandidates`»
(`test/align-candidates.test.mjs` либо существующий файл). Такого юнит-теста в
диффе нет — `git diff --stat -- test/` пуст. Вместо этого AC4 проверяется
браузерным смоком `demo/smoke_align_guides.mjs` (`devGuideComesFromAnotherMarker`),
который вызывает тот же `_alignCandidates()` напрямую на живом инстансе и
сравнивает списки кандидатов с активным `_deviceDrag` и без — по существу то
же утверждение, что просило ТЗ, просто через e2e, а не через изолированный
юнит. Проверено исполнением: смок зелёный, а отрицательный прогон мутанта
`align-guides-exclude-dead-source` подтверждает, что проверка умеет падать.
Снимаю без правок: доказательство сильнее, чем просило ТЗ (реальный DOM вместо
изолированного вызова), просто не в той форме файла.

**L2. Число «2 654 Б gzip» для 38 help-строк в `docs/ARCHITECTURE.md` не
перепроверено независимо.**

Прочитано и признано правдоподобным (38 ключей, общий вес словарей 47 754 Б
gzip, итоговый бюджет 285 425 — совпадает с хендоффом), но точный вес именно
этих 38 ключей отдельно не измерялся мной — потребовал бы отдельного скрипта
подсчёта, которого в репозитории нет. AC3 требует записанного решения с
причиной, а не независимого замера ревьюером; решение и причина на месте.
Снимаю без правок.

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

- **AC1/AC2** (приоритет угловой ручки на мелкой мебели, отсутствие регрессии
  на крупной) — доказаны исполнением: `node demo/smoke_furniture_polish.mjs`
  зелёный, диагностика `handleProbeDiagnostics` показывает ровно одно
  срабатывание на угловой ручке и ноль на осевой для 40 см и для 160 см.
  Порядок отрисовки в `src/houseplan-card.ts:8467-8485` подтверждён чтением:
  `sides.map` идёт раньше `corners.map`, радиусы хита идентичны (`hr` общий на
  `:8440`).
- **AC4** — доказан исполнением через смок (см. L1); чтением подтверждено, что
  `_alignCandidates` (`src/houseplan-editor-runtime.ts:10970-10979`) теперь
  берёт `this.host._deviceDrag?.id ?? this.host._drag?.id`, и что в режиме
  `devices` `_drag` действительно остаётся `null` (не тронуто этим диффом,
  проверено чтением `houseplan-card.ts:2547` и присваиваний `_drag` — ни одно
  не относится к ветке `devices`).
- **AC5** — доказан исполнением, включая отрицательный прогон мутанта
  («поймано 1 из 1»): смок различает направляющую от другого маркера и от
  себя, сравнением списков кандидатов, а не по заранее посчитанной точке —
  учтён риск гонки координат, названный в ТЗ.
- **AC3** — решение (2) «en/ru неделимы» записано в `docs/ARCHITECTURE.md` с
  причиной (стоимость раздельной поставки против экономии), проверено чтением.
- **AC6** — бюджет initial не вырос: `npm run bundle:budget` = 285 425 / 300 000,
  прогнано заново, совпадает с хендоффом.
- Интерфейс `HouseplanEditorHostPort._deviceDrag` — новое поле только в типе,
  реальное приватное поле `_deviceDrag` в `HouseplanCard` существовало и до
  этого диффа (`houseplan-card.ts:2548`, не изменено) — подтверждено чтением,
  `tsc --noEmit` подтверждает совместимость типов.
- Трейлеры: все четыре коммита несут `Issue: #400` и корректный
  `User-Visible:`; `User-Visible: yes` (`fe3b85c0`) правит оба changelog в том
  же коммите — подтверждено `git show --stat`.
- Видимых числовых значений, которые пользователь видел бы дважды, в этом
  диффе нет (правки — хит-тестинг и внутренний список кандидатов
  направляющих, не отображаемые величины) — «одно число, один источник» не
  применимо.
- Диф не трогает геометрию комнат/толщины/`layout`/`marker.space`/`open_spans`
  — инварианты модели не требуются.

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

- **`npm run golden:verify`** — не прогонял. Обоснование: правка (1) меняет
  DOM-порядок двух групп невидимых (прозрачных) хит-кругов и парных с ними
  `.dtknob`; сами бусины позиционно не пересекаются друг с другом (углы и
  середины сторон — разные точки), поэтому перестановка групп не может менять
  итоговые пиксели рамки редактирования декора. Риск назван и разобран в самом
  ТЗ («перестановка не должна менять картинку»). Golden-баз для оверлея рамки
  редактирования декора в матрице предположительно нет (оверлей — состояние
  выделения в редакторе, а не View); не проверял это утверждение отдельным
  прогоном golden, полагаюсь на разбор по коду.
- **`python -m pytest tests_backend`** — не прогонял, diff не касается
  `custom_components/**/*.py`.
- **`node scripts/model-invariants.mjs`** — не прогонял, diff не касается
  геометрии.
- **Полный `ls demo/smoke_*.mjs` (209 смоков)** — не прогонял; прогнаны 9,
  названные `scripts/smoke-select.mjs` как прямые совпадения, плюс целевые
  `align_guides`/`furniture_polish` из AC. Полный набор — предрелизный гейт.
- **Точный байтовый вес 38 help-строк отдельно** — не перемерял (см. L2).
- **Ручное DOM-тестирование в браузере вне смоков** — не проводилось; в этом
  процессе фазы ручного тестирования нет, автотесты и код-ревью её заменяют
  (см. таблицу гейтов выше).

## Итог

Один Medium в скоупе задачи (M1), без High — жёлтый вердикт. Функциональные
правки (1) и (2) верны и доказаны исполнением; постоянный регресс-гейт для
пункта (1) сломан и не защищает от отката ровно той регрессии, которую
описывает ТЗ. Правка ожидается в этом же issue — заменить патч мутанта
`furniture-edge-handles-steal-the-corner` на такой, что реально возвращает
`corners` перед `sides`, и подтвердить прогоном
`node scripts/mutation-gate.mjs --id=furniture-edge-handles-steal-the-corner`
(«поймано 1 из 1»).