houseplan-card/docs/reviews/SPEC-REVIEW-300-r2.md

# SPEC-REVIEW-300-r2

- Issue: [#300](https://github.com/Matysh/houseplan-card/issues/300) — Подписи при ресайзе: подсвечивать измеряемые стены, убрать размер перетаскиваемой, площадь показывать по бокам от неё
- Этап: spec (PROCESS.md §2.4)
- ТЗ: `docs/specs/300-resize-measurement-layout.md`, коммит `2b7c98e6bcc4a7fed920c05f2298a06a138683fd` на ветке `issue/300-resize-labels`
- Заход: r2 · блокирующих циклов израсходовано (до этого раунда) 1/4
- Ревьюер: Claude (роль «ревьюер ТЗ», не автор)

## Скоуп разбора

Раунд не первый → разбор по дельте (PROCESS.md §2.9, issue #214), не заново.

1. Вердикт r1 найден в комментарии issue #300 (2026-08-24T19:14:59Z): жёлтый,
   заход r1, блокирующих циклов 1/4, High 0 / Medium 2 → в задаче. SHA, на
   котором получен вердикт r1, в самом комментарии не назван — это находка,
   отдельно не заводится (не Medium, не блокирует), восстановлен из
   `docs/reviews/SPEC-REVIEW-300-r1.md` (шапка документа) и из тела следующего
   коммита: **`ab9a83e755211a599ba8d73be0a3716696a5168b`**.
2. Автор ответил комментарием 2026-08-24T19:19:16Z: правки внесены и запушены
   в **`2b7c98e6bcc4a7fed920c05f2298a06a138683fd`**, явно указана дельта для
   повторного ревью: `git diff ab9a83e..2b7c98e -- docs/specs/300-resize-measurement-layout.md`.
3. Дельта проверена: `git diff ab9a83e7..2b7c98e6 -- docs/specs/300-resize-measurement-layout.md`
   — правка ограничена файлом спецификации, 40 добавленных / 18 удалённых
   строк. Дополнительно `git diff ab9a83e7..2b7c98e6 --stat` показывает, что
   между раундами появился только сам документ `SPEC-REVIEW-300-r1.md`
   (публикация предыдущего ревью) — это не продуктовый код и не меняет предмет
   разбора.
4. Дельта локальна: тот же файл, тот же раздел (правки только в §3, §4 п.6,
   §5, §6.3, §7, §10, §11 (AC7/AC11), §12, §13, §14, §18, заключительный
   абзац §18) — не ребейз на ушедший вперёд `dev` (весь `origin/dev..HEAD`
   всё ещё только markdown), не смена контракта поведения целиком, не задета
   новая подсистема. Полный повторный разбор не требуется; проверяются:
   закрытие M1/M2, и все AC/разделы, чьё доказательство эта дельта задевает
   (AC6, AC7, AC11 и связанные с ними §6.3, §7, §12, §13, §14, §18).
5. Гейты кода неприменимы, как и в r1: класс изменений — C (документация),
   диапазон `origin/dev..HEAD` не содержит `src/**`/`test/**`.

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

Проверено чтением (не исполнением), только по дельте:

| Утверждение правки | Где проверено |
|---|---|
| Класс `.rlgearbtn` — реальное имя кнопки настроек комнаты (не `.roomgear`, как было в r1) | `src/styles.ts:1000`, `src/houseplan-card.ts:18705` (`_renderRoomGear`) |
| `demo/benchmark_safe_resize_render.mjs` действительно использует абсолютный потолок `RENDER_P95_MS = 25`, без relative-сравнения | `demo/benchmark_safe_resize_render.mjs:9,64,75` — совпадает с формулировкой нового AC11 |
| Утверждение нового §6.3/§18.4 «screen-fixed footprint `.rlgearbtn`» проверено против реального CSS кнопки | `src/styles.ts:996-1008` — `--gear-h: calc(var(--icon-size, 2.5cqw) * 0.77)`; `--icon-size` вычисляется `iconCqw()` |
| `iconCqw()` явно и намеренно **зависит от текущего zoom/viewBox**, а не постоянна в screen px | `src/space-geometry.ts:463-489` — докстринг: «An icon is a percentage of the PLAN, not of the viewport: it scales with the plan as you zoom… (owner, 2026-08-03)»; формула `(iconPct * iconUnit(space) * k) / w`, где `w = viewW` |
| Тот же вывод подтверждён комментарием в стилях | `src/styles.ts:997-998`: «icon-size already rescales with the view… so the button zooms WITH the plan instead of keeping a constant screen size (owner's spec)» |
| `_renderRoomGear` позиционирует кнопку в процентах контейнера (`left/top: %`), что синхронно с zoom — сама позиция не проблема | `src/houseplan-card.ts:18701-18703` |

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

| Находка r1 | Чем закрыта | Где это видно |
|---|---|---|
| **M1** — временное скрытие `.roomgear` во время Resize объявлено «acceptance contract» без подтверждения владельца и без прецедента в коде | Автор не стал спрашивать владельца и не оставил догадку — убрал сам guess: кнопка теперь **всегда видима** (не меняется относительно текущего поведения, значит не требует продуктового решения), а перекрытие снимается сдвигом area-плашки вдоль стены. То, что реально новое и видимо пользователю («площадь не перекрывает видимую кнопку»), явно оставлено в контракте; конкретный алгоритм сдвига явно вынесен в §18 п.4 как оспариваемое техническое предположение («допустима другая pure screen-space стратегия») | §4 п.6, §6.3 (новый абзац «Для collision check…»), §7 («Room settings buttons продолжают рендериться и не получают нового состояния»), §18 п.4, заключительный абзац §18 («…отсутствие overlap с видимой room settings button — это acceptance contract») |
| **M2** — AC11 требовал относительный регресс-бюджет (10%/1ms), которого не считает `demo/benchmark_safe_resize_render.mjs` | AC11 переформулирован под реальный механизм инструмента — абсолютный потолок `RENDER_P95_MS = 25`; §10 теперь явно называет этот файл в списке участвующих файлов с пояснением «исходник менять не требуется»; §13 п.5 явно требует прогонять его перед код-ревью | AC11 (раздел 11), §10 («`demo/benchmark_safe_resize_render.mjs` — существующий real-render gate с абсолютным `RENDER_P95_MS = 25`»), §13 п.5 |

Оба закрытия проверены не на слово: `.rlgearbtn` и `RENDER_P95_MS = 25`
сверены с реальным кодом (таблица выше). Оба Medium из r1 закрыты корректно.

## Находки

### Medium — M3: новый текст утверждает, что footprint `.rlgearbtn` «screen-fixed», хотя размер кнопки явно и намеренно зависит от zoom

**Файл:** `docs/specs/300-resize-measurement-layout.md`, §6.3 (новый абзац «Для
collision check…») и §18 п.4 — обе фразы введены именно этой правкой (в r1
их не было вовсе, тема отсутствовала, так как r1 просто прятал кнопку).

**В чём проблема.** Новый механизм collision-avoidance описан так:
«консервативный **screen-space footprint** плашки, вычисленный из
форматированного текста, font/padding tokens и **screen-fixed footprint**
`.rlgearbtn`» (§6.3), и повторно в §18 п.4: «screen-fixed footprint room
gear». В документе термин «screen-fixed» уже занят и используется
последовательно в другом, точном смысле — «не меняется при zoom SVG»: то же
§6.3 про leader-линию («Перевод screen px в render units использует текущий
viewBox/stage size; stroke остаётся **screen-fixed**») и §6.2 про подсветку
(`vector-effect="non-scaling-stroke"`, «одинаково читается при zoom»).

Реальный `.rlgearbtn` этому определению не соответствует.
`--gear-h: calc(var(--icon-size, 2.5cqw) * 0.77)`, а `--icon-size`
вычисляется `iconCqw()`, чей докстринг прямо говорит: «An icon is a
percentage of the PLAN, not of the viewport: it scales with the plan as you
zoom… (owner, 2026-08-03)» — то есть размер кнопки в CSS px на экране
**растёт и уменьшается вместе с zoom плана**, а не остаётся константой. Это
подтверждено ещё и соседним комментарием в `styles.ts`: «icon-size already
rescales with the view… so the button zooms WITH the plan instead of keeping
a constant screen size **(owner's spec)**» — то есть зависимость от zoom не
случайность реализации, а явное продуктовое решение того же владельца.

Если реализация буквально возьмёт формулировку ТЗ («screen-fixed footprint
`.rlgearbtn`») и один раз посчитает/захардкодит размер кнопки без учёта
текущего zoom (что и подсказывает слово «screen-fixed» рядом с «не читает
layout в pointermove»), консервативный footprint будет верным только на том
zoom, для которого его посчитали, и разойдётся с реальным на любом другом —
ровно то, от чего должен защищать сам механизм (AC7: «её фактический DOM
rectangle не пересекает area-плашку»). Существующий риск-пункт 4 в §15
(«Консервативный footprint разойдётся с фактическим CSS… smoke сравнивает
реальные `getBoundingClientRect()`») называет только font/padding-погрешность,
а не zoom-масштабирование, и план тестов (§13 п.2) не называет конкретный
нестандартный zoom как fixture — то есть смок на дефолтном zoom формально
пройдёт даже с неверной («screen-fixed») трактовкой формулы.

**Сценарий проявления.** Администратор дома открывает Resize на плане,
предварительно отдалённом (zoomed out) от дефолтного масштаба — сценарий
никак не запрещён и не редок при работе с большими планами. `.rlgearbtn`
на экране меньше, чем при дефолтном zoom (или больше — при приближении).
Реализация, посчитавшая «screen-fixed» footprint по дефолтному размеру,
либо пропускает реальное пересечение (кнопка настроек оказывается частично
под площадью — ровно проблема 3 из тела issue, которую задача должна решить),
либо наоборot излишне отодвигает плашку туда, где реального пересечения нет.
Оба исхода — нарушение AC7 на zoom, не покрытом smoke-фикстурой.

**Почему не High.** Правится на этом же этапе без пересмотра остального
документа: либо явно указать, что footprint `.rlgearbtn` должен пересчитываться
по той же zoom-зависимой формуле, что и `--icon-size`/`iconCqw()` (то есть
заменить «screen-fixed» на «screen-space, пересчитываемый от текущего
view.w» в двух местах — §6.3 и §18 п.4), либо явно добавить в §13 п.2 fixture
с нестандартным zoom для доказательства, что консервативный footprint
остаётся консервативным не только на дефолтном масштабе. Технический
алгоритм и так помечен в §18 п.4 как свободно оспариваемое предположение —
менять нужно только формулировку факта о самой кнопке, не продуктовый
контракт AC7.

## Что проверено и признано корректным (в рамках дельты)

- M1 и M2 закрыты корректно и проверены по коду, не на слово (таблица выше).
- Новое решение по M1 не создаёт нового недекларированного guess: сохранение
  видимости кнопки — это отсутствие изменения существующего поведения, а не
  новое решение, требующее подтверждения владельца; конкретный алгоритм сдвига
  корректно оформлен как оспариваемое предположение в §18 п.4, а сам факт
  «кнопка видима и не перекрыта» верно зафиксирован как acceptance contract.
- AC7 переформулирован непротиворечиво: «unit + smoke» вместо старого
  «smoke», согласуется с тем, что появился чистый collision-helper, который
  можно проверить unit-тестом отдельно от production DOM-пути.
- Переименование mutation guard `resize-labels-gear-during-drag` →
  `resize-labels-ignore-gear-collision` (§12) соответствует новому механизму
  (сдвиг вместо скрытия) и продолжает указывать на AC7.
- §13 п.5 корректно добавляет прогон `demo/benchmark_safe_resize_render.mjs`
  как обязательное доказательство AC11 перед код-ревью — согласуется с новой
  формулировкой AC11.
- §7 («Area projection использует тот же вычисленный visual centre, что
  `_renderRoomGear()`») — корректное техническое требование по *позиции*
  (совпадает с `poleOfInaccessibility(r.poly)` в `_renderRoomGear`); в отличие
  от заявления о *размере* (M3), про позицию текст не грешит против кода.
- Риск-пункт 4 в §15 добавлен обоснованно (несовпадение расчётного и
  фактического CSS — реальный риск), но не покрывает конкретно
  zoom-масштабирование — см. M3.

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

- Полные гейты (`typecheck`/`test`/`build`, `check-docs`, `smoke-select`,
  golden, invariants, backend, `python -m pytest`) — не запускались: диапазон
  `origin/dev..HEAD` содержит только markdown, класса A/B изменений нет,
  как и в r1. Эта проверка относится к будущему код-ревью того же issue.
- Реализацию проекции (`src/resize-labels.ts` и т.д.) — она ещё не написана.
- Прочие AC (AC1–AC5, AC8–AC10) и разделы §1, §2, §6.1, §6.2, §8, §9, §16,
  §17, §18 п.1–3,5 — не затронуты дельтой, повторно не проверялись, см.
  «Унаследовано из r1».
- Численно, действительно ли `--icon-size`/`iconCqw()` в реализации даёт
  «консервативный» (заведомо не меньше фактического) footprint при любом
  zoom, если формула будет исправлена по M3 — это вопрос реализации, не
  наблюдаем на этапе ТЗ.

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

Всё, что не затронуто дельтой между `ab9a83e7` и `2b7c98e6`, принято без
повторной проверки на основании `docs/reviews/SPEC-REVIEW-300-r1.md`
(SHA `ab9a83e755211a599ba8d73be0a3716696a5168b`), раздел «Что проверено и
признано корректным»:

- обязательные разделы §7.1 присутствуют и не перепутаны местами; сценарий
  и «что человек увидит» — первые два раздела;
- диагноз текущего кода (три длины, `poleOfInaccessibility` для площади,
  отсутствие отдельной подсветки измеряемого ребра) подтверждён чтением кода;
- технический контракт §6 согласован с реальной формой `SafeResizePlan`
  (`roomIds`, `edgeByRoom` в `src/resize.ts`);
- продуктовое решение по Q1 (narrow-room fallback — площадь всегда видна,
  выносится за контур с leader-линией) верно перенесено из решения владельца
  дословно;
- граница с #233 (математика длины/площади) и #277 (eligibility/commit/Undo)
  проведена верно и не переоткрывает их;
- модель данных/миграция/i18n корректно поданы как «без изменений»;
- AC1–AC5, AC8–AC10 однозначны, у каждого указан способ доказательства;
  golden-сцена `safe-resize-handles-clamp-{light,dark}` действительно
  эмулирует активный preview (`safeResizePreview: true`);
- откат описан верно (одна frontend-ревизия, без миграции);
- смежные issue (#233/#277/#238/#52) корректно отнесены к «не входит».

## Вердикт

Одно новое Medium (M3) в скоупе задачи, устранимо без пересмотра остального
документа — правкой формулировки в двух местах (§6.3, §18 п.4) либо
добавлением non-default-zoom fixture в §13 п.2. High нет. Оба Medium
предыдущего раунда (M1, M2) закрыты корректно и проверены по коду.

Вердикт: жёлтый · заход r2 · блокирующих циклов 2/4 · High: 0 · Medium: 1 → в задаче · Документ: docs/reviews/SPEC-REVIEW-300-r2.md