houseplan-card/docs/specs/294-wall-esc-detach.md

# Issue #294 — Esc завершает текущую цепочку стен без удаления геометрии

- **Issue:** https://github.com/Matysh/houseplan-card/issues/294
- **Статус:** редакция r2 после жёлтого ревью r1; канонический статус задаётся метками issue
- **Тип / приоритет:** feature + polish / P2
- **Область:** Plan editor, desktop keyboard, lifecycle активного wall draft,
  подсказки RU/EN, targeted browser regression
- **Модель данных:** schema и model version не меняются
- **Связано:** #173; эта задача заменяет только прежний контракт `Esc`

## 1. Проблема

После каждого завершённого сегмента единый инструмент «Стены» сохраняет
crash-safe `room_draft`. Пока цепочка активна, её последний узел остаётся
якорем следующего сегмента. Сейчас `Esc` вызывает ту же операцию удаления
последней точки, что и локальный шаг назад: последний сегмент и соответствующая
толщина исчезают из draft и с плана.

Это не соответствует ожидаемой роли `Esc`: пользователь хочет закончить
текущий жест рисования, сохранить уже сделанное и начать следующую независимую
цепочку без переключения инструментов.

Эталон уже существует. Переход со «Стен» на «Колонну» вызывает штатный finish:
draft становится ordinary `partitions`, активный якорь очищается. Возврат на
«Стены» начинает новую цепочку. #294 даёт тот же результат одним `Esc`, но не
покидает инструмент «Стены».

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

Для открытой цепочки `A–B–C` нажатие `Esc`:

1. оставляет на плане всю уже принятую геометрию `AB` и `BC` с её толщинами;
2. заканчивает текущую цепочку и снимает привязку к `C`;
3. оставляет выбранным инструмент «Стены»;
4. делает следующий клик `D` первой точкой новой цепочки;
5. создаёт новый сегмент только вторым кликом `E`, то есть `DE`, но не `C–D`.

`Ctrl/Cmd+Z` остаётся действием «убрать последнюю принятую точку/отрезок».
Таким образом, finish и undo больше не скрыты за одной клавишей.

## 3. Контракт Esc

### 3.1 Активная открытая цепочка с сегментами

Если Plan editor активен, выбран `draw`, диалог комнаты не открыт и в `_path`
есть не менее двух точек, `Esc` выполняет ровно штатное завершение wall chain:

- каждый сегмент materialize-ится как ordinary `partition` тем же кодом и с
  теми же merge/limit правилами, что при смене инструмента;
- исходный активный `room_draft` удаляется, дубликат draft + partitions
  недопустим;
- `_path`, `_activeDraftId`, `_draftSegmentCms`, closing state, snap-hover и
  rubber-band preview очищаются;
- `_resumeDraftBySpace` не сохраняет ссылку на завершённый draft;
- `_tool` остаётся `draw`;
- используется существующая одна history/config transaction
  `history.wall_chain_finish`; дополнительная команда для самого `Esc` не
  создаётся.

Если штатный finish отклонён, например из-за лимита partitions, применяется
действующее сообщение об ошибке, цепочка остаётся активной и геометрия не
теряется. Визуально отцеплять не завершённую в storage цепочку запрещено.

### 3.2 Только первая точка

Если есть одна временная точка и нет завершённого сегмента, `Esc` очищает
точку, preview и snap state. Никакие `room_draft`, `partition`, history command
или config write не создаются; инструмент остаётся «Стены».

### 3.3 Нет активной цепочки

В `draw` без `_path` `Esc` не меняет геометрию, history и выбранный инструмент.
Повторное нажатие после успешного finish идемпотентно.

### 3.4 Приоритет верхних поверхностей

Действующая лестница Escape сохраняется:

- topmost dialog/editor surface обрабатывает клавишу первой;
- при открытом room proposal первый `Esc` отменяет весь ещё не применённый
  batch и восстанавливает его terminal draft по контракту #173;
- этот же keydown не должен дополнительно завершить восстановленный draft;
- только следующий отдельный `Esc` вне диалога может превратить его в
  partitions;
- resize/drag, physical selection и прочие инструменты сохраняют свои нынешние
  обработчики Escape.

## 4. Undo, ввод и persistence

1. `Ctrl/Cmd+Z` на активной цепочке сохраняет текущий путь через
   `_undoActiveDraftPoint` / `_undoPoint`: удаляет последнюю точку и сегмент,
   не завершая всю цепочку.
2. `Ctrl/Cmd+Z` после `Esc` следует существующей history-семантике штатного
   `wall_chain_finish`; #294 не добавляет второй undo step.
3. Завершённые по `Esc` partitions переживают save/reload как любые другие
   законченные независимые стены и не возобновляются автоматически как draft.
4. Явный будущий клик по концу finished partition может использовать обычный
   snap, но не является восстановлением старой chain session.
5. Pinch, pan, `pointercancel`, suppressed synthetic click и повторный выбор
   уже активной кнопки «Стены» не получают семантику `Esc` и не завершают цепь.

## 5. Подсказки и документация

Новых i18n-ключей нет. Существующий `markup.hint_points` меняется синхронно:

- RU различает «Esc — завершить цепочку» и «Ctrl+Z — убрать точку»;
- EN различает “Esc — finish chain” и “Ctrl+Z — undo a point”.

`docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md` должны явно описать тот же
контракт во всех местах, где сейчас обобщено старое поведение:

- RU, таблица поверхностей ввода «Рисование и точный drag»: отделить finish
  цепочки «Стены» от отмены текущего precise drag;
- RU, таблица «Клавиши отмены»: разделить объединённый Draw/Split-контекст —
  `Esc` завершает wall chain, а Split сохраняет свою действующую отмену;
- RU, «Комнаты и стены»: заменить «Esc/Ctrl+Z удаляет последнюю точку» двумя
  разными действиями;
- EN, input-surface row “Draw or precise drag”: отделить Walls finish от
  cancel текущего precise drag;
- EN, “Cancel and undo”: исключить wall chain из обобщения “Esc cancels an
  unfinished path” и явно назвать сохранение принятой цепочки;
- EN, “Create a room”: добавить тот же явный паритет Esc/Ctrl+Z, который есть
  в RU-разделе, а не оставлять новый контракт только в общей клавиатурной
  памятке.

Поведение Escape у room dialog, Resize, Split и других операций остаётся
описано отдельно и не обобщается на wall chain.

Изменение пользовательское: implementation-коммит обновляет оба changelog.

## 6. Scope

### Входит

- desktop `Escape` для активной wall chain;
- повторное использование штатного finish без смены `_tool`;
- сохранение различия Esc и Ctrl/Cmd+Z;
- приоритет room dialog и безопасный отказ finish;
- RU/EN hint и обе версии руководства;
- targeted production-bundle browser smoke через настоящий `keydown`.

### Не входит

- новая кнопка «Завершить», обработка Enter или новая touch-команда;
- изменение face detection, room proposal, merge partitions или limit policy;
- изменение формата `room_drafts`, `partitions` либо history storage;
- изменение Escape у Resize, Columns, Openings, Boundary, Decor и диалогов;
- автоматическое продолжение finished partition как draft;
- переработка всех общих текстов про Escape вне затронутого Walls-контекста.

## 7. Acceptance criteria

### AC1. Esc сохраняет всю открытую цепочку (`smoke`)

Production-bundle smoke рисует `A–B–C` с различимыми толщинами `AB` и `BC`,
посылает настоящий `window` `keydown` с `key=Escape` и доказывает: обе оси и
толщины присутствуют в ordinary partitions, `room_draft` отсутствует,
`_path/_activeDraftId` очищены, preview отсутствует, `_tool === 'draw'`.

### AC2. Следующая цепочка независима (`smoke`)

После AC1 smoke кликает stage в `D`, затем `E` через production click path.
После `D` segment не появляется; после `E` появляется только `DE`. Ни
partition, ни draft с соединением `C–D` нет.

### AC3. Одна точка не создаёт геометрию (`smoke`)

На пустом плане первый клик создаёт только active anchor. Настоящий `Esc`
очищает anchor/preview, оставляет `draw`, не создаёт draft, partition, history
command или config write.

### AC4. Ctrl/Cmd+Z остаётся шагом назад (`smoke`)

На активной `A–B–C` настоящий `Ctrl/Cmd+Z` оставляет активной `A–B`, удаляет
только `BC` и одну запись толщины. Mutation, направляющая этот shortcut в finish,
обязана ломать проверку.

### AC5. Dialog precedence не регрессирует (`smoke`)

При открытом room proposal один `Esc` отменяет batch, оставляет terminal draft
активным и не создаёт partitions. Второй отдельный `Esc` завершает этот draft.
Закрытие dialog и finish — две разные keyboard transactions.

### AC6. Failure и повтор безопасны (`smoke` + ревью кода)

Если штатный `_finishWallChain()` возвращает `false`, `Esc` не очищает active
state и не меняет geometry/history. После успешного finish повторный `Esc`
ничего не добавляет, не удаляет и не возобновляет draft.

### AC7. Тексты совпадают с поведением во всех справочных местах (`unit` + ревью кода)

RU/EN `markup.hint_points`, обе user guide и оба changelog различают finish по
Esc и удаление точки по Ctrl/Cmd+Z. Ревью кода обязано проверить все шесть
конкретных поверхностей из §5:

1. `docs/USER-GUIDE.ru.md`: строка «Рисование и точный drag» не называет Esc
   общей отменой; она отдельно говорит про finish «Стен» и cancel drag;
2. `docs/USER-GUIDE.ru.md`: объединённая строка «Незавершённый Draw/Split»
   разделена, и у Walls больше нет текста «убирает последнюю точку» для Esc;
3. `docs/USER-GUIDE.ru.md`: «Комнаты и стены» различает `Esc` и `Ctrl+Z`;
4. `docs/USER-GUIDE.md`: строка “Draw or precise drag” не называет Esc общей
   отменой, а различает Walls finish и cancel drag;
5. `docs/USER-GUIDE.md`: “Cancel and undo” исключает wall chain из “cancels an
   unfinished path” и не обещает удалить принятую геометрию;
6. `docs/USER-GUIDE.md`: “Create a room” явно описывает Esc/Ctrl+Z с тем же
   смыслом, что RU-раздел.

Старые противоречащие формулировки отсутствуют, i18n parity зелёный.

### AC8. Регрессии и локальные гейты (`unit` + `build`)

- `npm run typecheck`;
- `npm test`;
- `npm run build` и bundle parity;
- существующие wall-chain, room dialog, physical Escape и history тесты зелёные.

Targeted smoke пишется в реализации, но по принятому циклу исполняется вместе
со smoke-набором перед beta; golden и performance также остаются предрелизными.

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

Schema, model version и storage не меняются; миграция и compatibility-fields не
нужны. Сохранённые старые drafts читаются и завершаются штатным кодом.

Изменяется только desktop keyboard. Touch View и kiosk не затронуты, touch
editor остаётся best effort без новой команды finish; pan, pinch и
`pointercancel` сохраняют safety floor.

Новых HA actions, backend endpoint и security boundary нет. На один `Esc`
выполняется уже существующий O(n) finish активной цепочки; pointermove/render
hot path не меняется, performance budget не затрагивается.

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

- **Потеря геометрии при ошибке finish.** AC6 требует сохранять active state при
  `false` и использовать существующий limit toast.
- **Draft и partitions одновременно.** AC1 проверяет materialization и удаление
  active draft одной transaction.
- **Скрытое продолжение от старой точки.** AC2 проверяет production click path,
  а не только private state.
- **Двойное действие одного keydown после диалога.** AC5 фиксирует ранний return
  и два отдельных нажатия.
- **Регресс Ctrl/Cmd+Z.** AC4 отдельно проверяет shortcut через реальный keydown.
- **Документация врёт после изменения.** AC7 включает обе локали и hint.

## 10. Откат

Откат — полный revert implementation-коммита #294 вместе с smoke, RU/EN hint,
руководствами и changelog. Schema и сохранённые данные не меняются, поэтому
миграция назад и восстановление конфигурации не нужны. После отката возвращается
контракт #173: Esc снова удаляет последнюю точку.

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

- `src/houseplan-card.ts`;
- `src/i18n/en.json`, `src/i18n/ru.json`;
- `demo/smoke_unified_wall_tool.mjs`;
- `docs/USER-GUIDE.md`, `docs/USER-GUIDE.ru.md`;
- `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`.

Новый backend-код, config schema, golden и performance fixture не ожидаются.

## 12. Release

Implementation-коммит имеет терминальные трейлеры `Issue: #294` и
`User-Visible: yes`; оба changelog входят в тот же коммит. Issue не закрывается
вручную: она закрывается пачкой при выпуске beta.

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

1. «То же самое, что Колонна → Стены» означает тот же materialization/merge и
   history contract, но без фактической смены инструмента.
2. `Esc` при единственной точке снимает пустой жест: сохранять нечего.
3. Открытый room dialog имеет больший приоритет, поэтому для его Cancel и
   последующего finish нужны два нажатия.
4. Отказ из-за общего physical limit не позволяет отцепиться визуально от ещё
   не завершённого draft.