houseplan-card/docs/specs/449-double-fit-all.md

# ТЗ #449 — двойной клик/тап по свободному фону вписывает весь план

- Issue: https://github.com/Matysh/houseplan-card/issues/449
- Приоритет: P2
- Тип: feature
- Трек: полный — новый UX-контракт и изменение гарантированного touch-контракта
- Связанные задачи: #82, #152, #183
- Решения владельца: Q1 Default, Q2 Default
- **Touch editor: not exposed** — жест живёт только во View и kiosk; редакторы
  Плана, Устройств и Подложки (в ней редактируется декор) его не получают, их
  touch-поведение и редакторский double-click не меняются (§6 «Режимы», AC7).
  Правило `docs/TOUCH-SUPPORT.md` → «Documentation rule».

## Сценарий

Пользователь House Plan в обычном View или kiosk приблизил либо сдвинул план и
хочет быстро вернуться к обзору всего пространства. Вместо поиска кнопки в
верхней панели он дважды нажимает мышью или дважды касается свободного места на
сцене.

Комнаты и самостоятельные элементы плана сохраняют свои текущие действия:
комната вписывается одним нажатием, устройство выполняет своё действие, ссылка
открывается, проём и его controls не становятся поверхностью нового жеста.

## Что человек увидит до и после

До изменения двойной тап по свободному фону вписывает план только в kiosk, а в
обычном View двойной клик и двойной тап ничего не делают. После изменения два
быстрых clean-нажатия по свободному фону в View или kiosk плавно дают ровно тот
же кадр, что кнопка **«Вписать всё»**.

## Проблема и подтверждённое текущее состояние

В `src/houseplan-card.ts` уже есть единая команда `_fitAll()`: она снимает
room-focus, возвращает полный content frame, включая ранее скрытые дальние
объекты, и передаёт exact target в `_resetZoom()` и camera transition #82.

Текущий double-tap не является общей командой View:

- `_lastTap` обновляется только внутри kiosk-ветки `_stagePointerUp()`;
- kiosk считает clean tap по сохранённому `_swipeStart`, использует окно 350 мс
  и вызывает `_resetZoom('double-tap')`;
- stage не имеет общего `dblclick`-обработчика;
- #152 немедленно принимает clean room click/tap на `pointerup`; room-owned tap
  намеренно не обновляет kiosk `_lastTap`;
- pan, pinch, kiosk swipe/long press, устройства, проёмы, room link и редакторы
  уже имеют собственных владельцев указателя.

#183 ранее зафиксировала это расхождение как уточнение к #152, но не добавляла
жест в обычный View. Поэтому #449 — новая пользовательская возможность, а не
исправление документации и не дубликат room-fit.

## Скоуп

1. Двойной primary click мышью по свободной неинтерактивной области сцены в
   обычном View вызывает fit-all.
2. Двойной primary tap touch/pen по той же области в обычном View вызывает
   fit-all.
3. Действующий kiosk double-tap переводится на тот же общий gesture contract и
   тот же fit-all command.
4. Оба способа используют существующие fit bounds, zoom limits, transition,
   reduced-motion и camera persistence rules.
5. Вводится единый проверяемый арбитраж free-background tap для View и kiosk.
6. Добавляются unit, mutation и production-bundle browser smoke доказательства
   положительных и отрицательных путей.
7. Обновляются канонические документы View/touch и оба changelog.

## Не-скоуп

- двойной жест по комнате, room label или HA Area link;
- задержка одиночного room-fit для распознавания второй половины double-tap;
- двойной жест по device marker/capsule, vacuum, opening или его controls;
- работа жеста в редакторах План, Устройства и Подложка;
- новый button, tooltip, настройка, key binding или пользовательский параметр;
- изменение геометрии content frame, outlier policy, zoom limits, длительности
  или easing camera transition;
- изменение kiosk floor swipe, long press, pan/pinch и cycling;
- изменение click/double-click действий объектов редактора;
- миграция конфигурации, localStorage или backend API.

## Контракт поведения

### 1. Каноническое действие fit-all

Успешный двойной жест вызывает ту же семантическую команду, что кнопка
**«Вписать всё»**, а не отдельный расчёт камеры и не прямое присваивание zoom:

1. снимается session-only room-focus;
2. `_showFar` становится `true`, `_frame` инвалидируется;
3. берётся актуальный `_baseVb()` после восстановления полного content frame;
4. `fitView()` строит exact target для текущего aspect ratio;
5. target проходит существующий `CameraTransitionController` с reason
   `double-tap` и действующим `CAMERA_FIT_MS`;
6. reduced motion немедленно применяет тот же exact target;
7. повторный вызов при уже совпадающем target остаётся no-op по действующему
   контракту controller.

`_fitAll()` принимает reason `fit | home | double-tap` либо эквивалентным
способом передаёт существующий reason дальше. Второй controller, CSS transform и
альтернативная математика fit запрещены.

### 2. Что считается свободным фоном

Кандидат создаётся только для primary pointer с основной кнопкой в `view`, если
его исходный composed path принадлежит scene/stage и не содержит владельца
самостоятельного действия.

Не являются свободным фоном:

- `[data-hp="room"]`, `.roomlabel` и `.rlgo`;
- `.dev`, device capsule/badge/action, `.vacpuck`;
- `.opening`, `.op-hit`, `.oplock` и opening actions;
- `a`, `button`, `input`, `select`, `textarea`, editable content;
- элементы с `role=link`, `role=button` или `data-room-fit-block`;
- editor secondary/chrome, dialog/popover и любые действующие explicit action
  targets.

Декоративные слои View, которые уже имеют `pointer-events: none`, не создают
нового owner и не мешают нажать на лежащий под ними свободный фон. Проверка
работает по browser `composedPath()`, а не по повторному геометрическому hit-test.

Список ownership должен иметь один источник для room-fit и нового background
gesture либо отдельный helper с явно доказанной совместимостью; две расходящиеся
копии selector list недопустимы.

### 3. Clean tap/click

Одно нажатие может войти в последовательность только если:

1. pointerdown и pointerup принадлежат одному pointer id и тому же space;
2. режим на всём жесте — `view`;
3. down и up разрешаются как свободный фон;
4. жест не стал pan, pinch, kiosk swipe, object drag или long press;
5. не было second-pointer/multitouch sequence, `pointercancel` или
   `lostpointercapture`;
6. `_suppressClick` и существующие mode-transition/continuity guards не
   запрещают действие.

Порог движения не дублируется новой константой: решение использует тот же
источник истины, по которому текущий stage отличает clean click от pan. Жест,
который хотя бы однажды был классифицирован как pan/swipe/pinch, не может снова
стать tap на release.

### 4. Последовательность двух нажатий

Первый принятый free-background tap только записывает transient candidate и не
двигает камеру. Второй последовательный принятый tap в пределах действующего
kiosk-окна 350 мс один раз вызывает fit-all и очищает sequence до вызова
команды.

Sequence хранит только transient данные, необходимые для арбитража: timestamp,
space и pointer modality. Pointer id между двумя touch taps совпадать не обязан.
Mouse, touch и pen не склеиваются друг с другом в одну пару.

Просроченный второй tap становится новым первым tap. Любой несовместимый жест,
смена space/mode/projection, начало editor transition, structural adoption,
`pointercancel`, hidden/disconnect или multitouch очищают sequence. Timer,
который сам вызывает действие по истечении окна, не нужен.

Для сохранения kiosk compatibility эта задача не вводит новый межтаповый
spatial threshold: два последовательных clean free-background tap следуют
действующему временному контракту. Это техническое допущение явно покрывается
тестами и может быть пересмотрено отдельной UX-задачей.

### 5. Арбитраж с комнатой и объектами

Решение владельца Q1 — free background only:

- одиночный room click/tap по #152 выполняется немедленно;
- второй room click остаётся вторым room-fit и не вызывает fit-all;
- room-owned жест не записывает первый tap и очищает незавершённую
  free-background sequence, если достигает общего stage arbitration;
- интерактивный ребёнок выполняет только собственное действие и никогда не
  становится первой или второй половиной fit-all;
- новый gesture handler не вызывает `preventDefault()`/`stopPropagation()` на
  чужой поверхности ради распознавания.

Первая половина double gesture не задерживает ни room-fit, ни object action.

### 6. Режимы

| Режим | Двойной жест по свободному фону |
|---|---|
| View | Fit all |
| Kiosk | Fit all; прежние swipe/long-press/cycle правила сохранены |
| План | Нет нового действия |
| Устройства | Нет нового действия |
| Подложка | Нет нового действия |

Переход между режимами или пространствами всегда разрывает незавершённую пару.
Редакторские double-click properties и drawing click chain не меняются.

## UX и доступность

- Новый жест не имеет отдельной визуальной подсказки или состояния hover.
- Анимация визуально совпадает с кнопкой «Вписать всё» и kiosk reset.
- При `prefers-reduced-motion: reduce` применяется тот же конечный кадр без
  промежуточной анимации.
- Кнопка «Вписать всё» остаётся видимым и keyboard-accessible способом выполнить
  действие; новый скрытый shortcut не заменяет её.
- Клавиатурные room-label actions, focus и screen-reader semantics не меняются.
- На touch один tap по свободному фону остаётся no-op; никаких отложенных
  эффектов после 350 мс нет.

## Модель данных, миграция, compatibility и i18n

- Новых полей config, localStorage, backend model и service calls нет.
- Gesture candidate живёт только в экземпляре карточки и не переживает
  disconnect/remount.
- Формат конфигурации и downgrade не меняются.
- Новых строк интерфейса и ключей i18n нет.
- Несколько экземпляров карточки не разделяют sequence; каждый реагирует только
  на жесты внутри собственной stage.

## Производительность и безопасность

- На pointerdown/up допускается только O(length of composed path) ownership
  check и O(1) обновление transient state.
- Нового interval, глобального listener, дополнительного RAF-loop и render на
  первом tap нет.
- Второй tap использует существующий camera transition; budget #82 не меняется.
- Событие не пишет config и не вызывает Home Assistant service/navigation.
- Exception в path resolution или отсутствующая stage/невалидный frame даёт
  fail-safe no-op через действующие guards, без частичного camera state.

## Критерии приёмки и доказательства

### AC1. Mouse double-click в обычном View выполняет fit-all

После zoom/pan два clean primary mouse click по свободному фону за ≤350 мс дают
тот же exact конечный viewBox/zoom, `_showFar` и room-focus state, что кнопка
«Вписать всё».

**Доказательство:** unit recognizer + production-bundle browser smoke со
сравнением обоих путей.

### AC2. Touch/pen double-tap в обычном View выполняет fit-all

Два clean tap одной modality по свободному фону дают один fit-all; первый tap не
меняет камеру. Mouse/touch/pen не образуют смешанную пару.

**Доказательство:** unit matrix + browser smoke реальными PointerEvent.

### AC3. Kiosk использует общий contract без регрессии навигации

Kiosk double-tap по свободному фону по-прежнему вписывает план. Straight/bent
floor swipe, pan at any zoom, long press, cycling pause и motionless first tap
сохраняют текущий результат.

**Доказательство:** расширенные `smoke_kiosk.mjs` и
`smoke_kiosk_pan_lock.mjs`, mutation общего recognizer.

### AC4. Комната не участвует в fit-all sequence

Один и два room click/tap немедленно выполняют только room-fit #152. Ни первый,
ни второй room-owned release не вызывают fit-all и не оставляют скрытую половину
последовательности.

**Доказательство:** unit ownership + расширенный `smoke_room_fit.mjs` с spy на
fit-all и camera result.

### AC5. Интерактивные owners полностью подавляют новый жест

Double click/tap по device/capsule/action, vacuum, opening/lock, HA Area link,
button/form control выполняет только прежнее действие либо no-op этого owner.
Fit-all не вызывается и sequence не остаётся вооружённой.

**Доказательство:** unit composed-path table + targeted production-bundle smoke
для device, opening и room link.

### AC6. Навигационный жест нельзя завершить как double-tap

Pan, pinch, kiosk swipe, long press, pointercancel/lost capture и любое движение
за существующим click threshold дают zero fit-all. Следующий одиночный free tap
после них не считается второй половиной старой пары.

**Доказательство:** unit state-machine table + smoke pan/pinch/cancel/kiosk.

### AC7. Редакторы не меняются

В Plan, Devices и Background два нажатия по свободному фону не вызывают
fit-all. Double-click properties, drawing placement, select/move и decor
handlers сохраняют существующие результаты.

**Доказательство:** mode unit matrix + `smoke_editor_gestures.mjs` и целевой
decor smoke.

### AC8. Sequence изолирована и корректно инвалидируется

Смена space/mode/projection, structural adoption, hidden/disconnect и истечение
350 мс не позволяют второму tap завершить прежнюю пару. Два экземпляра карточки
не разделяют состояние.

**Доказательство:** unit с управляемым clock + browser smoke для mode/space и
двух instances.

### AC9. Camera transition остаётся единым

Double-fit retarget-ит активную camera animation из фактически показанного
кадра, reduced motion применяет exact target, а повторный fit к совпадающему
target не создаёт лишний RAF/render/storage write.

**Доказательство:** unit `viewport-transition` + расширенный smooth-zoom smoke и
write/render spies.

### AC10. Данные и внешние действия не меняются

Успешный и отклонённый жест не меняют server config/history и не вызывают HA
service/navigation. Используется только session camera state по действующим
правилам fit-all.

**Доказательство:** browser smoke со spies на save/history/hass.callService и
navigation.

### AC11. Производительность и bundle budget не регрессируют

Первый tap не запускает render/timer, ownership остаётся линейным по короткому
composed path, initial bundle проходит действующий потолок.

**Доказательство:** unit/render spy, `bundle:budget`, performance-smoke перед
бетой.

## План автотестов

1. Добавить pure unit-тесты для:
   - free/room/interactive composed paths;
   - clean/stale/cancelled/moved/multitouch candidates;
   - mouse/touch/pen и запрета mixed modality;
   - same/different space, mode, projection и instance;
   - first/second/expired sequence, ровно одного trigger и очистки до callback.
2. Расширить `test/room-fit.test.mjs` отрицательными room-owned сценариями.
3. Добавить mutation witnesses как минимум для:
   - удаления free-background owner guard;
   - принятия room tap в sequence;
   - пропуска pan/pinch cancellation;
   - вызова `_resetZoom` вместо канонического `_fitAll`;
   - включения жеста в editor mode.
4. Добавить/расширить production-bundle smoke:
   - mouse double-click и touch double-tap в обычном View;
   - kiosk parity;
   - room/device/opening/link suppression;
   - pan, pinch, cancel и editor non-regression;
   - exact parity с кнопкой «Вписать всё» после zoom/pan и при far object.
5. Локальный цикл реализации: `npx tsc --noEmit`, `npm test`, `npm run build`,
   `npm run bundle:sync`, targeted smoke и `no-new-any`.
6. Перед бетой: полный smoke, golden verify без ожидаемого baseline diff и
   performance-smoke; канонический полный HA-harness — Linux CI.

## Карта реализации

- `src/houseplan-card.ts`: transient candidate/sequence lifecycle, общий вызов
  fit-all, очистка на structural/mode lifecycle и удаление kiosk-only развилки.
- Новый либо существующий pure gesture helper: path ownership и state-machine,
  без DOM state и side effects.
- `src/room-fit.ts` или общий ownership module: единый источник selector/owner
  classification без расхождения с #152.
- `src/viewport-transition.ts`: только расширение типа reason при необходимости;
  математика/controller не меняются.
- `test/**`, `demo/smoke_*.mjs`, `scripts/mutation-gate.mjs`: доказательства AC.
- `docs/CANVAS.md`, `docs/TOUCH-SUPPORT.md`, `docs/UX-MODES.md`,
  `docs/USER-GUIDE.md`, `docs/USER-GUIDE.ru.md`: новый shortcut и его границы.

## Риски

1. **Room tap станет первой половиной fit-all.** Защита: единый path owner и
   отрицательный smoke с двумя room taps.
2. **Pan/swipe завершится fit-all на release.** Защита: финальная gesture
   classification и очистка sequence при первом переходе в navigation owner.
3. **Touch породит synthetic mouse double-click и два вызова.** Защита: один
   pointer-based recognizer либо явное подавление compatibility event с тестом
   «одна пара — один command».
4. **Редактор потеряет double-click properties.** Защита: mode guard до записи
   candidate и smoke существующих editor handlers.
5. **Kiosk изменит навигацию.** Защита: сохранение окна 350 мс и полный набор
   kiosk pan/swipe/long-press witnesses.
6. **Fit вызовет другой кадр, чем кнопка.** Защита: один command и численное
   сравнение exact camera target, включая far-object frame.

## Откат

Откат удаляет общий free-background recognizer и его transient state, возвращает
прежнюю kiosk-only ветку `_lastTap`, убирает тесты/документацию #449. Форматы
данных не меняются, поэтому миграция назад не нужна. Кнопка «Вписать всё»,
room-fit #152 и camera transition #82 остаются работоспособны независимо от
отката.

## Release-артефакты

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`: одна пользовательская запись со
  ссылкой на #449 без раскрытия внутренних имён state/handler.
- `docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md`: shortcut только для свободного
  фона в View/kiosk и явное отличие от room-fit.
- `docs/CANVAS.md`, `docs/TOUCH-SUPPORT.md`, `docs/UX-MODES.md`: канонический
  gesture/ownership contract.
- Новых UI screenshots не требуется: статический вид не меняется.
- Golden baseline не должен меняться; `golden:verify` остаётся предрелизным
  доказательством отсутствия визуальной регрессии.
- Release notes беты получают краткое пользовательское описание без технических
  деталей.

## Принятые предположения — можно менять на ревью без решения владельца

1. Общий recognizer реализуется на Pointer Events, а не параллельными
   `dblclick` и touch-кодами, чтобы synthetic compatibility event не дублировал
   команду.
2. Окно 350 мс сохраняется из kiosk; отдельный межтаповый spatial threshold в
   #449 не вводится.
3. Sequence различает mouse/touch/pen и не требует одинакового pointer id между
   двумя taps.
4. Первый tap не создаёт timer и render; просрочка определяется при следующем
   входном событии.
5. Ownership selectors выносятся в общий pure helper, если это уменьшает
   расхождение с #152; точное имя файла и типов свободно.
6. Double-fit передаёт reason `double-tap` для всех pointer modalities, включая
   mouse, чтобы telemetry/tests имели один semantic reason.