houseplan-card/docs/specs/148-tool-first-plan-editor.md

# Issue #148 — Tool-first редактирование комнаты в Plan Editor

- **Issue:** https://github.com/Matysh/houseplan-card/issues/148
- **Редакция:** первая редакция для независимого ревью; статус задачи определяется
  только метками issue
- **Тип / приоритет:** feature + polish / P2
- **Оценка:** пользовательская ценность 8/10; ценность для разработки 7/10;
  сложность и риск 8/10
- **Область:** нижняя панель Plan Editor, шесть инструментов редактирования
  комнаты, выбор целей, локальные параметры, Undo/Redo, keyboard и accessibility
- **Модель данных:** сохранённый формат плана не меняется; `ToolSession` — только
  runtime-состояние редактора
- **Связано:** `docs/UX-MODES.md`, `docs/CANVAS.md`, `docs/RESIZE.md`,
  `docs/WALL-THICKNESS.md`, `docs/TOUCH-SUPPORT.md`

## 1. Сценарий и продуктовый контекст

**Персона:** администратор дома, который строит и исправляет план в
desktop-браузере.

**Поверхность и момент:** пользователь открывает Plan Editor и хочет выполнить
операцию над комнатой, ещё не выбрав комнату или стену.

**До → после, без терминов реализации:** сейчас состав нижней панели зависит от
того, сколько комнат уже выбрано, и заставляет сначала угадывать нужное
выделение; после изменения пользователь одним и тем же способом сначала
выбирает действие, затем требуемые объекты и только после валидного выбора
настраивает и применяет результат.

Это поддерживает J4 и J6 из `docs/SCOPE.md`: встроенный редактор становится
предсказуемым инструментом построения и последующего исправления плана.

## 2. Решение владельца и источник UX-контракта

Владелец 15.08.2026 отклонил предложенное разбиение на этапы: общий framework и
все шесть действий поставляются **одним релизом**. Каноническая запись:
https://github.com/Matysh/houseplan-card/issues/148#issuecomment-5301106841

Приложенный к issue архив `Plan Editor.zip` является UX-референсом. Его
`DECISION.md`, `UX-SPECIFICATION.md`, `WIREFRAMES.md`,
`interactive-prototype.html` и `states.html` уточняют поведение, но не являются
готовым кодом или отдельной системой стилей. При расхождении приоритет таков:

1. решения владельца в issue;
2. это ТЗ;
3. текстовые документы архива;
4. визуальная реализация прототипа.

## 3. Скоуп одного релиза

В задачу входят:

1. единый runtime lifecycle сессии инструмента;
2. стабильная группа «Редактировать комнату» с действиями «Объединить»,
   «Разделить», «Размер», «Граница», «Толщина», «Удалить»;
3. перевод на tool-first контракт всех шести действий без сохранения скрытого
   preselection-зависимого маршрута;
4. инструкции, счётчики, validation errors и визуальные состояния active,
   hover, selected и invalid;
5. локальная панель толщины и контекстные настройки остальных инструментов;
6. единые правила отмены, переключения, фокуса, клавиатуры и Undo/Redo;
7. сохранение верхней навигации и занимаемой нижней панелью геометрии;
8. unit, browser smoke, visual golden, документация и RU/EN changelog.

Поставка только framework, Merge или Thickness при незавершённых остальных
четырёх инструментах не выполняет задачу.

## 4. Не входит в задачу

- новая верхняя навигация, постоянный правый inspector или перенос редактора в
  отдельную страницу;
- новые архитектурные операции, которых сейчас нет в Plan Editor;
- изменение результата Merge/Split/Resize/Boundary/Thickness/Delete после
  подтверждения, кроме необходимого выравнивания их UX lifecycle;
- изменение моделей комнат, стен, проёмов, перегородок, колонн и HA Areas;
- миграция, schema version или backend API;
- переход Devices/Background editor на новый lifecycle;
- полноценный touch-first Plan Editor: редактор остаётся desktop-first, при
  обязательном safety floor из раздела 11;
- изменение View, киоска и верхней segmented navigation;
- новый верхнеуровневый режим «Удаление».

## 5. Информационная архитектура нижней панели

### 5.1. Стабильные группы

В Plan сохраняются существующая верхняя навигация и общий каркас нижней панели.
Панель предоставляет стабильные группы:

- «Выбрать»;
- «Редактировать комнату»;
- «Контур комнаты»;
- «Конструкции»;
- «Проём».

Внутри «Редактировать комнату» состав не меняется от выделения на холсте:

1. Объединить;
2. Разделить;
3. Размер;
4. Граница;
5. Толщина;
6. Удалить.

Группа доступна без предварительного выбора комнаты. Условия конкретной
операции показывает активная сессия, а не disabled-состав подпанели.

### 5.2. Шесть обзорных состояний

Требуемый комплект продуктовых состояний/скриншотов:

1. без выбора;
2. редактирование комнаты;
3. контур комнаты;
4. конструкции;
5. проём;
6. подтверждение удаления.

«Подтверждение удаления» — временное destructive-состояние внутри группы
«Редактировать комнату». Оно не добавляет шестую постоянную группу или вкладку.

### 5.3. Геометрия панели

- раскрытие группы и смена фазы не меняют размеры stage и не сдвигают холст;
- содержимое остаётся в выделенной нижней области и использует существующий
  shared secondary controller;
- overflow прокручивается внутри панели; кнопка подтверждения и текущая
  инструкция не уходят за viewport;
- локальная плавающая панель может перекрывать stage, но не участвует в layout.

## 6. Каноническая сессия инструмента

Реализация может уточнить имена типов, но обязана иметь один явный источник
runtime-истины со следующим смыслом:

```ts
interface ToolSession {
  tool: 'merge' | 'split' | 'resize' | 'boundary' | 'wallthick' | 'delete' | null;
  phase: 'idle' | 'selecting_targets' | 'validating_targets' | 'configuring' | 'applying';
  targets: ToolTarget[];
  anchor?: { x: number; y: number };
  draft: Record<string, unknown>;
  validationError?: { key: string; targetId?: string };
}
```

Обязательные инварианты:

1. `tool === null` означает отсутствие незавершённой операции;
2. тип, количество, порядок и совместимость целей задаёт активный инструмент;
3. `selectedRooms.length` и другие глобальные selection counts не определяют
   состав подпанели;
4. hover не является target и не меняет конфигурацию;
5. invalid target не добавляется в `targets`;
6. `draft` и targets не пишутся в server config, localStorage или history;
7. единственная граница Undo/Redo — успешно применённая команда;
8. после apply сессия завершается и очищается до `idle`; повтор операции
   требует нового явного выбора инструмента;
9. переключение space/mode, закрытие редактора и потеря актуальной цели
   безопасно отменяют незавершённую сессию;
10. asynchronous validation/apply проверяют revision сессии: запоздалый ответ
    отменённого или заменённого инструмента не меняет UI и конфигурацию.

Существующие разрозненные поля допустимы как внутренние детали перехода, но не
могут оставаться конкурирующими источниками lifecycle.

## 7. Контракты шести инструментов

### 7.1. Объединить

1. Клик по «Объединить» включает инструмент и показывает «Выберите две
   смежные комнаты», счётчик `0 из 2`.
2. Первая валидная комната получает selected-state, счётчик становится
   `1 из 2`.
3. Повторный клик по уже выбранной комнате снимает её; порядок остальных целей
   сохраняется.
4. Вторая кандидатура валидируется до добавления: это другая существующая
   комната того же space/floor с подходящей общей границей, не занятая
   конфликтующей операцией.
5. Невалидная комната не заменяет первую и не становится третьей целью. Рядом
   с подпанелью показывается конкретная причина, а кандидат получает временный
   invalid-state.
6. После второй валидной комнаты автоматически открываются действующие
   настройки Merge. Фокус переходит на их заголовок/первое поле.
7. Пользователь может применить, отменить всю сессию или вернуться к выбору
   комнат, сохранив первую/обе валидные цели согласно явной кнопке «Назад».
8. Конфигурация и history меняются только после подтверждения.

### 7.2. Разделить

1. Инструмент просит выбрать одну существующую комнату.
2. После валидного выбора начинается действующий маршрут задания линии Split;
   незавершённые точки являются `draft`, а не history-командами.
3. Начальная/конечная точки, пересечения и результирующие полигоны валидируются
   по текущим правилам Split; invalid click не повреждает уже валидный draft.
4. Настройки новой комнаты открываются только после законченной валидной линии.
5. «Назад» из настроек возвращает к редактированию линии; подтверждение
   применяет Split атомарно, cancel очищает его полностью.

### 7.3. Размер

1. Инструмент просит выбрать одну комнату либо допустимый её сегмент.
2. Первый валидный target включает существующие resize handles и preview.
3. Live preview хранится только в сессии; server config и соседние render paths
   не видят частично применённую геометрию.
4. Настройки/контролы показываются после валидного target, а apply фиксирует
   одну атомарную history-команду.
5. Cancel восстанавливает точную исходную геометрию без записи и без Undo item.

### 7.4. Граница

1. Инструмент объясняет требуемую текущей операцией цель и принимает только
   допустимую общую границу/её endpoints.
2. Первая точка или boundary target переводит сессию в выбор следующей цели;
   pan/pinch не подтверждает точку.
3. Невалидная цель не заменяет валидный anchor и сопровождается конкретной
   причиной.
4. Конфигурация границы применяется одной подтверждённой командой. Esc во
   время двухточечного выбора сначала возвращает к выбору целей по правилам
   раздела 9, не создавая history.

### 7.5. Толщина

1. Инструмент показывает «Выберите стену или несколько стен».
2. Доступный atomic wall segment получает hover-state; клик добавляет/снимает
   его из набора targets. Открытый span и другой невалидный объект не
   добавляются.
3. После первого выбранного сегмента появляется локальная панель рядом с ним:
   поле «Толщина», диапазон `1–100 см` (с действующим imperial-equivalent),
   «Применить ко всем стенам комнаты» и кнопка подтверждения с галочкой.
4. При нескольких targets anchor панели — общий bbox выбранных сегментов либо
   последний выбранный сегмент; выбор должен быть детерминирован.
5. Предпочтительное положение — под anchor с отступом 8–12 px. Панель
   переворачивается/сдвигается, чтобы целиком остаться в card viewport, не
   закрывать выбранный сегмент и критичные handles.
6. Поле может содержать draft, но стены не меняются до подтверждения. Ошибка
   диапазона показывается рядом с полем и блокирует apply.
7. «Ко всем стенам комнаты» вычисляет цели от комнаты выбранного anchor в
   момент подтверждения; неоднозначность shared wall решается действующим
   владельцем atomic interval и не распространяется на соседнюю комнату
   скрыто.
8. Одна галочка создаёт одну атомарную history-команду для всех targets.

### 7.6. Удалить

1. Инструмент просит выбрать одну комнату; hover/selected не удаляют данные.
2. После валидного target открывается встроенное состояние подтверждения с
   именем комнаты и явным destructive action.
3. Красный цвет используется для финальной destructive-кнопки и invalid/error,
   но не как постоянная окраска всей группы.
4. «Назад» возвращает к выбору комнаты; cancel не создаёт history.
5. Подтверждение удаляет только явно выбранную комнату существующей атомарной
   командой и затем очищает сессию.

## 8. Визуальные состояния и обратная связь

- **active tool:** постоянный cyan/accent state кнопки и текстовая инструкция;
- **hover target:** лёгкий контур без изменения target count;
- **selected target:** стабильный заметный контур/заливка и текстовый счётчик;
- **invalid target:** краткий красный/not-allowed state вместе с текстовой
  причиной; цвет не является единственным каналом;
- **applying:** повторное подтверждение блокируется, но отменённый устаревший
  completion не может завершить новую сессию;
- status/instruction использует `aria-live="polite"`, validation error —
  `aria-live="assertive"` или эквивалентный alert.

Стили берутся из текущих токенов редактора. Прототип определяет иерархию и
состояния, но не разрешает вводить параллельную палитру.

## 9. Отмена, keyboard и focus

1. Повторный клик по активному инструменту отменяет всю незавершённую сессию.
2. Переключение инструмента атомарно очищает targets, anchors, draft, preview,
   validation error и локальную панель предыдущего.
3. Esc в `configuring` закрывает настройки и возвращает к `selecting_targets`
   с последним валидным набором targets.
4. Esc в `selecting_targets` очищает targets и выключает инструмент.
5. Для многошагового Split/Boundary первый Esc может снять последнюю
   незавершённую точку только если это явно показано пользователю; следующий
   следует общему правилу отмены сессии.
6. Enter применяет только валидную configuring-фазу и никогда не подтверждает
   destructive Delete без фокуса на явной кнопке.
7. После автоматического открытия настроек фокус переходит на их heading или
   первое поле; после «Назад» — на active tool/instruction; после apply/cancel
   — на кнопку запуска инструмента.
8. Кнопки имеют `aria-pressed`, локализованное имя и понятный disabled reason.

## 10. Модель данных, persistence и compatibility

- форматы `spaces`, `rooms`, `walls`, `open_spans`, openings и физических
  объектов не меняются;
- `ToolSession`, targets, anchors и drafts не сериализуются;
- миграции, backfill и schema version нет;
- открытие и отмена любого инструмента не вызывает `_saveConfig()`;
- применённые команды используют действующий config/write contract и остаются
  читаемыми предыдущей версией;
- import/export не получает новых полей;
- текущие планы открываются без materialisation и побайтовых изменений.

## 11. Touch, zoom, resilience и performance

Plan Editor остаётся desktop-first. На coarse pointer полный ergonomic parity
не требуется, но:

- второй палец, pan, pinch и pointercancel не могут подтвердить цель или apply;
- touch target controls не меньше действующего minimum;
- cancel/switch/space change не оставляет preview или заблокированный stage;
- zoom между выбором targets не меняет их identity и корректно перепривязывает
  локальную панель;
- удаление target внешним config update переводит сессию в безопасную отмену с
  сообщением, а не применяет операцию к другому объекту.

Hover/pointermove меняют только дешёвый preview. Полная геометрия, render model
и secondary-panel composition не пересчитываются на каждый pixel движения.
Target validation и локальная раскладка входят в существующие bounded caches;
HA state ticks не перестраивают tool session без структурной причины.

## 12. i18n

Все новые пользовательские строки добавляются одновременно в RU и EN:

- название группы и шести действий, если действующие ключи не подходят;
- инструкции каждой фазы;
- счётчики целей (`0 из 2`, `1 из 2`, `2 из 2`) через plural/parameter contract;
- конкретные validation reasons Merge и остальных инструментов;
- «Назад», «Применить», «Применить ко всем стенам комнаты»;
- accessible labels/status для панели и targets.

Нельзя собирать предложения конкатенацией или оставлять prototype-only English.
Термины сверяются с `docs/USER-GUIDE.ru.md`.

## 13. Acceptance criteria

1. «Редактировать комнату» доступно без preselection и всегда показывает все
   шесть действий в заданном порядке.
2. В основной панели нет компоновок «выбрана 1 комната»/«выбраны 2 комнаты» и
   ветвления состава от `selectedRooms.length`.
3. Каждое из шести действий следует фазам tool → targets → validation →
   configuring → apply и не пишет draft в config/history.
4. Merge показывает `0/2` и `1/2`, не принимает третью/невалидную комнату и
   автоматически открывает настройки после второй валидной.
5. Thickness допускает один/несколько atomic segments, открывает рядом панель,
   валидирует `1–100 см`, поддерживает all-room и применяет только по галочке.
6. Split, Resize и Boundary сохраняют действующую геометрическую семантику, но
   получают единые выбор, отмену, настройки и apply boundary.
7. Delete сначала выбирает одну комнату и показывает отдельное подтверждение;
   до финальной кнопки данные не меняются.
8. Active, hover, selected и invalid различимы визуально и доступны без цвета.
9. Esc, повторный tool click, смена tool/mode/space и stale target очищают
   незавершённое состояние по разделам 6 и 9.
10. Undo/Redo содержит только подтверждённые операции — ровно одну запись на
    один apply независимо от числа targets.
11. Верхняя navigation не меняется, secondary content не сдвигает stage, а
    локальная панель целиком остаётся в viewport при zoom и у всех краёв.
12. RU/EN, keyboard, focus, ARIA status/error и reduced-motion проходят
    проверки; destructive Enter не срабатывает неявно.
13. Существующие планы и wire format не меняются; cancel не вызывает save.
14. Все шесть состояний раздела 5.2 обновлены и приняты visual review.

## 14. Проверки и доказательства

### Unit

- переходы state machine для каждого инструмента, повторного клика, switch,
  Esc, apply, stale async completion и external target removal;
- target cardinality/identity и invalid-target exclusion;
- Merge same floor/shared boundary и автоматический configuring transition;
- Thickness multi-select, `1–100`, all-room и одна history-команда;
- отсутствие save/history для всех cancel paths.

### Browser smoke

- полный happy path и cancel/back path всех шести инструментов мышью;
- keyboard-only Merge, Thickness и Delete safety;
- zoom/pan во время выбора и позиционирование локальной панели у четырёх краёв;
- mode/space switch, pointercancel и structural config update;
- верхняя навигация и размеры stage до/после раскрытия групп.

### Golden

Обновляется и reviewится комплект из шести состояний раздела 5.2 минимум в
desktop theme light/dark, плюс узкие golden для:

- Merge `1 из 2`, invalid second target и configuring;
- Thickness hover, multi-selected и local panel у края;
- Delete confirmation.

Baseline меняется только после проверки, что diff соответствует ТЗ. Golden,
smoke и performance запускаются в release gate перед бетой; цикл реализации —
`typecheck`, `unit`, `build` по процессу.

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

В том же user-visible коммите реализации обязательны:

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`;
- `docs/USER-GUIDE.ru.md` — новый порядок редактирования всех шести операций;
- `docs/UX-MODES.md` — стабильные группы и tool-first lifecycle;
- при необходимости `docs/CANVAS.md`, `docs/RESIZE.md` и
  `docs/WALL-THICKNESS.md`, если реализация уточнит их взаимодействие;
- RU/EN locale files;
- принятые golden/baseline и smoke scenario либо ссылка на канонический
  артефакт CI по правилам репозитория;
- `docs/TESTING.md`, если добавлен новый сценарий/gate.

Security и backend release artifacts не требуются, пока реализация не меняет
права или wire format. Если такой change окажется необходим, задача должна
вернуться к владельцу до кода.

## 16. Риски и rollback

Основные риски: два конкурирующих источника selection state, применение stale
draft, потеря Undo boundary, недоступный focus и floating panel вне viewport.
Они закрываются единой сессией, revision guard и проверками раздела 14.

Rollback — возврат UI/runtime-кода и locale/docs без миграции данных. Уже
сохранённые планы остаются совместимыми.

## 17. Принятые технические предположения

1. Shared secondary controller остаётся хозяином нижней contextual surface;
   новый lifecycle расширяет его, а не создаёт второй overlay stack.
2. Existing domain helpers Merge/Split/Resize/Boundary/Thickness/Delete
   сохраняются; задача унифицирует orchestration и transaction boundaries.
3. Для multi-select Thickness стабильная identity — нормализованный atomic wall
   interval вместе с room/space context, а не DOM element или экранные
   координаты.
4. «Заблокирована другим процессом» на первом этапе означает локальную
   конфликтующую сессию/структурно устаревшую цель; новая distributed locking
   модель не вводится.
5. Overview prototype state «Удаление» трактуется как подтверждение внутри
   «Редактировать комнату», поскольку это одновременно сохраняет заявленную
   стабильную иерархию и шесть продуктовых скриншотов.