houseplan-card/docs/specs/293-resize-pointer-noop.md

# Issue #293 — активная рукоятка Resize обязана выполнять pointer-жест

- **Issue:** https://github.com/Matysh/houseplan-card/issues/293
- **Статус:** первая редакция для внешнего ревью; канонический статус задаётся метками issue
- **Тип / приоритет:** bug / P1
- **Область:** production pointer pipeline safe Resize, live preview transaction,
  pointer capture, commit/cancel/Undo и browser regression smoke
- **Модель данных:** schema и model version не меняются
- **Связано:** #277, #289, #292; правила eligibility не расширяются

## 1. Подтверждённый дефект

На `test/fixtures/real-plan-second-floor.json` общая стена `room-a` edge 2 /
`room-b` edge 2 имеет одинаковые endpoints и разрешена
`resolveSafeResize`. Обе рукоятки активны. `pointerdown` создаёт корректный plan
для двух комнат, но настоящие `pointermove` на 2–60 px не дают видимого preview,
а `pointerup` не меняет geometry/history.

Чистая математика на том же plan исправна: `validateSafeResize`,
`clampSafeResize` и `applySafeResize` принимают ненулевые шаги в обе стороны и
изменяют только две комнаты. Значит, дефект находится в production integration
между pointer event и live overlay/commit.

Текущее наблюдение `d=0, moved=false` не доказывает, что ошибка только в
screen-to-SVG conversion: `_rszMove` также молча возвращает старое `d`, если
`_rszApplyPreview` отвергает persistence metadata. Реализация обязана сначала
зафиксировать точную причину отказа на полноценно инициализированной карточке, а
затем исправить её. Маскировать ошибку прямым вызовом private methods нельзя.

## 2. Пользовательский результат

Если рукоятка выглядит активной, drag по нормали стены немедленно показывает
live preview. Общая стена и обе комнаты движутся синхронно; стены, проёмы,
virtual spans и thickness records следуют за своей геометрией. Pointerup делает
ровно один commit и один Undo-шаг.

Если runtime preflight всё же обнаруживает конфликт, рукоятка не может молча
остаться активной и инертной: предсказуемый конфликт должен быть отражён в
eligibility до жеста, а непредсказуемый отказ во время жеста останавливает
preview на последней безопасной позиции и один раз показывает локализованную
причину. Нулевая позиция без объяснения запрещена.

## 3. Pointer contract

1. `pointerdown` на enabled handle сохраняет immutable geometry snapshot,
   `pointerId`, plan, options и начальную точку в SVG coordinates.
2. Последующие события того же pointer вычисляют signed displacement как
   проекцию **дельты от начальной pointer point** на `plan.n`; место click вдоль
   самой стены не влияет на результат.
3. Новая ось стены проходит grid snap один раз, затем `clampSafeResize`.
4. Gesture получает pointer capture на `currentTarget` handle либо эквивалентный
   общий listener, поэтому продолжает работать за пределами круга.
5. Pointer другого id, hover с `buttons=0`, pinch/pan и unrelated stage gesture
   не изменяют resize drag.
6. `pointerup` коммитит только уже показанный валидный preview. `pointercancel`,
   `lostpointercapture` до нормального release и Esc отменяют overlay без записи.
7. Один physical shared wall может иметь две owner circles, но started gesture
   привязан к одному immutable plan и не переключается на circle после rerender.

## 4. Live overlay contract

Preview строится из immutable pre-drag geometry и записывается только в
`_rszPreview`; `_serverCfg` до pointerup не меняется. На каждом candidate:

- room polygons и openings берутся из одного `applySafeResize` result;
- wall/open-span rekey выполняется из исходных spans, не из предыдущего frame;
- число wall/open-span records и multiset `wall.cm` сохраняются;
- общий physical geometry preflight проверяет exact overlay;
- reject возвращает структурированную причину, а не просто `false`.

Предсказуемые metadata/preflight условия должны использоваться и eligibility
#292. Непредсказуемый reject не сбрасывает успешно показанный preview. При первом
кандидате он оставляет `moved=false`, но показывает локализованный toast; повтор
того же reject в рамках жеста не спамит уведомления.

## 5. Реальный browser smoke

Regression test загружает production bundle и настоящую tracked fixture через
полноценный `_serverCfg`/space path. Он входит в Plan через штатный mode path,
выбирает Resize и отправляет browser pointer events по фактическим screen
coordinates handle. Тесту запрещено вызывать `_rszMove`, `_rszApplyPreview`,
`applySafeResize` или менять rooms после начала жеста.

Private state можно читать только как дополнительную диагностику; pass/fail
основан на DOM preview, persisted config, history и invariants. Smoke обязан
сначала доказать, что fixture space действительно является текущим объектом
`_serverCfg.spaces`, чтобы неполный setup не выдавал ложный no-op.

## 6. Scope

### Входит

- точная локализация и исправление enabled pointer no-op;
- pointer origin/capture и устойчивость к rerender;
- структурированный reject live preview и пользовательская обратная связь;
- реальный fixture browser smoke на 10 grid steps и 60 px;
- cancel, commit, Undo, metadata и geometry invariants;
- RU/EN i18n для runtime reject, если существующего текста недостаточно.

### Не входит

- изменение правил, какие стены считаются eligible (#292/#289/#290);
- разрешение partial-shared, mixed-role, diagonal или >2-room Resize;
- новый resize UX, новая кнопка подтверждения или новый режим;
- изменения schema/storage;
- исправление геометрии real fixture через прямую мутацию теста.

## 7. Acceptance criteria

### AC1. Реальный enabled drag работает

Production-bundle smoke на `room-a` edge 2 / `room-b` edge 2 выполняет
pointerdown, движение ровно на 10 grid steps и pointerup. До release DOM/live
geometry показывает 10 шагов, persisted geometry неизменна; после release обе
комнаты изменены ровно на 10 шагов, shared endpoints совпадают.

### AC2. Движение за пределами handle не теряется

Отдельный drag проходит не менее 60 screen px по нормали. Все intermediate
events одного pointer доходят до жеста, preview монотонно следует safe clamp.
Mutation, удаляющая capture/common listener, убивается этим smoke.

### AC3. Pointer delta не зависит от click вдоль стены

Три старта — midpoint и точки у обоих концов hit area — при одинаковой дельте
по нормали дают один `d`. Тангенциальное движение даёт ноль; reversed owner
copy даёт тот же physical target, а не противоположный результат.

### AC4. Один commit и Undo

Pointerup после ненулевого preview создаёт одну history command и одну config
write. Undo восстанавливает byte-equivalent pre-drag room/opening/wall/open-span
geometry. Synthesized click не меняет selection и не создаёт второй commit.

### AC5. Esc и interruption безопасны

Esc, pointercancel и lost capture до release удаляют overlay, оставляют config
и history неизменными и не запускают отложенную запись. Событие другого
`pointerId` игнорируется.

### AC6. Preview reject не молчит

Targeted test заставляет persistence/preflight отвергнуть первый candidate.
Geometry не меняется, `_serverCfg` не мутируется, пользователь получает ровно
один локализованный toast. Если reject детерминирован до pointerdown, handle
disabled через #292 вместо runtime toast.

### AC7. Metadata и topology сохраняются

После реального drag проходят room simplicity/orientation, shared ownership,
wall keys, mixed-role records, opening host/fit и physical render preflight.
Vertex counts/order, число wall/open-span records и multiset `wall.cm`
неизменны; затронуты не более двух комнат.

### AC8. Harness не может дать ложную зелень

Smoke падает, если fixture не находится в текущем `_serverCfg`, handle disabled,
preview отсутствует, persisted config меняется до release или движение сделано
private method. Mutation, возвращающая `d` к нулю либо заставляющая
`_rszApplyPreview` отвергать candidate, убивает smoke.

### AC9. Существующие сценарии не регрессируют

Outer wall, synthetic exact pair, clamp у угла, disabled handle, opening move,
preflight failure и cancellation в `smoke_room_resize` остаются зелёными.

### AC10. Локальные гейты

- `npm run typecheck`;
- `npm test`;
- `npm run build` и bundle parity;
- `node scripts/check-docs.mjs`;
- targeted real-plan pointer smoke и mutation.

Полные golden, smoke, performance и Linux HA harness выполняются перед beta.

## 8. Совместимость, touch, security и performance

Schema/storage не меняются. Desktop mouse является обязательным контрактом.
Touch editor остаётся best effort, но safety floor обязателен: pinch/pan и
pointercancel не коммитят resize, а active single-pointer drag не теряется.

Новых HA actions/security boundaries нет. Pointermove сохраняет существующий
bounded `clampSafeResize` и snapshot cache; нельзя сериализовать config или
пересчитывать весь model сверх текущего preview path более одного раза на
candidate. Safe Resize performance budget из `docs/RESIZE.md` сохраняется.

## 9. Риски и меры

- Точная причина интеграционного no-op устанавливается только на этапе
  реализации: screen-to-SVG conversion и молчаливый reject live-preview дают
  одинаковый внешний симптом. AC1, AC6 и AC8 требуют реальный pointer smoke и
  mutation для обоих путей, поэтому частичное исправление не пройдёт.
- Pointer capture и обработка отмены могут задеть touch safety floor. AC2 и AC5
  отдельно закрепляют выход за handle, `pointercancel`, lost capture и чужой
  `pointerId`, а AC9 сохраняет существующие сценарии.
- Исправление live-preview может случайно ослабить safe Resize. AC7 оставляет
  topology, metadata и physical preflight обязательными и ограничивает
  изменение двумя комнатами.

## 10. Откат

Откат — полный revert implementation-коммита #293 вместе с тестами и
документацией. Schema, model version и сохранённые данные не меняются, отдельная
миграция или восстановление конфигурации не требуются.

## 11. Ожидаемые файлы

- `src/houseplan-card.ts`, при необходимости `src/resize.ts`;
- `src/i18n/en.json`, `src/i18n/ru.json`, если добавляется runtime reason;
- `demo/smoke_room_resize.mjs` либо отдельный real-plan pointer smoke;
- unit/production-path/mutation tests;
- `docs/RESIZE.md`, `docs/TESTING.md`, при необходимости `docs/ARCHITECTURE.md`;
- `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`.

## 12. Release

Implementation-коммит имеет `Issue: #293`, `User-Visible: yes` и обновляет оба
changelog. Issue не закрывается вручную: она закрывается выпуском beta.

## 13. Принятые предположения

1. Скриншот владельца и реальная fixture имеют приоритет над ограничением
   первоначального программно собранного стенда; новый smoke обязан устранить
   это различие setup.
2. Structured preview reject — часть внутреннего API, а не новый persisted
   формат.
3. Если root cause окажется только в неполной инициализации старого smoke, это
   не считается исправлением пользовательского бага без воспроизведения и
   зелёного pointer path на конфигурации, эквивалентной реальному приложению.