houseplan-card/docs/specs/138-adjacent-room-autoclose.md

Issue #138 — автозамыкание комнаты по существующей стене

• Issue: https://github.com/Matysh/houseplan-card/issues/138
• Редакция: r2 после High из docs/reviews/SPEC-REVIEW-138-r1.md; статус определяется только метками issue
• Тип / приоритет: bug / P1
• Оценка: пользовательская ценность 9/10; ценность для разработки 7/10; сложность 5/10; риск 7/10
• Область: редактор Плана, инструмент «Контур комнаты», архитектурная endpoint/line-привязка #137, замыкание и сохранение room draft
• Модель данных: без новых полей, миграции и backend-изменений
• Связано: #137, docs/SCOPE.md, docs/ARCHITECTURE.md, docs/CANVAS.md, docs/WALL-THICKNESS.md, docs/TOUCH-SUPPORT.md

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

Персона: администратор дома, который дорисовывает соседнее помещение в редакторе Плана.

Поверхность: desktop browser с мышью или точным pointer. Touch editor остаётся best effort по docs/TOUCH-SUPPORT.md.

Момент: пользователь начинает новый контур на углу либо середине стены существующей комнаты, обходит новое помещение и заканчивает контур на другом месте той же непрерывной стены.

Задача поддерживает:

• J4: план можно точно нарисовать встроенным GUI без ручного редактирования SVG;
• J6: соседние помещения используют общую границу без микрозазоров и лишних обходных действий.

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

До: #137 точно привязывает финальный клик к существующему углу или линии, но редактор сохраняет его как ещё одну точку открытого draft. Диалог новой комнаты не открывается, хотя последний и первый узлы уже однозначно соединены существующей сплошной стеной.

После: если первая и последняя точки нового контура лежат на одном непрерывном сплошном интервале существующей стены, финальный клик сразу использует участок этой стены как замыкающее ребро и открывает обычный диалог новой комнаты.

3. Причина дефекта

_resolvePlanDrawPoint() уже возвращает точную endpoint- или line-snap координату, но _markupClick() считает контур замкнутым только при клике в собственную первую точку либо при Ctrl/Cmd + click. При клике в другую точку существующей стены результат snap добавляется в _path и сохраняется в room_drafts, после чего рисование остаётся открытым.

Это не ошибка точности #137: отсутствует продуктовый контракт, связывающий два узла одного существующего сплошного wall interval с неявным замыкающим ребром.

4. Решения владельца

Владелец подтвердил 2026-08-14 все предложенные defaults:

1. Автозамыкание действует только тогда, когда первая и последняя точки лежат на одном прямом каноническом ребре существующей комнаты. Допустимы исходные endpoints/углы и промежуточные line-snap точки. Разные рёбра одной комнаты не подходят.
2. Door/window/gate и open_span разрывают допустимую стену. Первая и последняя точки должны принадлежать одному непрерывному видимому сплошному интервалу #137.
3. Подходящий финальный клик сразу добавляет существующий интервал как неявное замыкающее ребро и открывает стандартный диалог новой комнаты, без отдельного подтверждения.
4. Новая визуальная индикация и новые строки не нужны: используются увеличенная snap-точка, live-preview и существующий диалог.
5. Приоритет задачи — P1.

5. Scope

В issue входят:

1. Распознавание подходящего финального клика инструмента «Контур комнаты» после актуального endpoint/line resolution #137.
2. Проверка принадлежности первой и финальной точек одному room-owned solid interval из общего архитектурного snap snapshot.
3. Автозамыкание валидного контура существующим участком стены и открытие обычного диалога комнаты.
4. Сохранение существующих validation, draft, per-segment thickness, history, Cancel/Save и Undo/Redo контрактов.
5. Unit и production-bundle smoke для положительных, отрицательных и touch-safety сценариев.
6. Обновление пользовательской и архитектурной документации.

6. Non-scope

В issue не входят:

• автозамыкание между разными рёбрами одной или разных комнат;
• поиск пути по нескольким коллинеарным либо угловым стенам;
• автозамыкание по room_drafts, partitions, колоннам, декору или подложке;
• проведение замыкающего ребра через дверь, окно, ворота или виртуальную границу;
• автоматическое дробление, переписывание или удаление существующей стены;
• новая кнопка, настройка, toast, анимация, цвет или i18n-ключ;
• изменение endpoint/line hit radius, приоритета и визуального слоя #137;
• исправление старой off-grid геометрии;
• новая schema, backend API, storage key, импорт/экспорт или миграция;
• полный hover-паритет редактора на coarse pointer.

7. Контракт распознавания

7.1 Порядок разрешения клика

Финальный click/tap сначала повторно получает авторитетную точку через действующий resolver #137. Hover-кандидат не используется как сохранённое обещание. Проверка автозамыкания выполняется до обычного добавления точки в draft и до _draftEndAt(), чтобы существующий endpoint draft не перехватил подходящий клик.

Существующие явные варианты имеют приоритет и не меняются:

1. клик в собственную первую точку замыкает контур как сейчас;
2. Ctrl/Cmd + click выполняет существующее быстрое замыкание;
3. только отличный от первой точки обычный клик, после добавления которого в prospective path будет не меньше трёх вершин, проверяется как новое автозамыкание по существующей стене.

Повторный клик в текущий anchor остаётся no-op и не создаёт нулевой сегмент. Если в path пока находится только первая точка A, второй клик B не считается попыткой автозамыкания даже при общем solid interval A—B: он без validation toast добавляется в draft обычным способом. Это тот же минимальный gate, который уже защищает ручное замыкание кликом в первую точку.

7.2 Допустимый существующий интервал

После прохождения gate минимального числа вершин автозамыкание разрешено, если существует хотя бы один сегмент текущего архитектурного snap snapshot, который одновременно:

• имеет sourceKind: room и происходит из завершённого контура комнаты;
• является одним прямым сплошным интервалом после канонических cuts #137;
• содержит первую точку нового контура;
• содержит финальную resolved-точку нового контура;
• имеет положительную длину, а две точки на нём различны.

«Содержит» означает коллинеарность и положение внутри закрытого интервала с геометрической точностью существующих pure helpers, а не визуальную близость в CSS pixels. Если угол принадлежит двум стенам, достаточно одного общего подходящего интервала для первой и финальной точки. Стабильный порядок решает технические ties, не меняя полученную линию замыкания.

room_draft и partition остаются видимыми snap-кандидатами #137, но не могут стать неявной границей новой комнаты.

7.3 Проёмы и виртуальные участки

Используется уже разрезанная геометрия #137:

• door/window/gate и open_span удаляются из room axis до проверки;
• граница cut не становится новым постоянным endpoint;
• точки по разные стороны любого cut не принадлежат одному solid interval и не запускают автозамыкание;
• точка внутри cut не получает line-snap, как и до этой задачи.

Новый код не вводит второй resolver проёмов или виртуальных границ.

8. Контракт замыкания и валидации

8.1 Успешный финальный клик

Пусть A — первая точка draft, P — его текущий конец, B — отличный от A resolved-финал на общем solid interval A—B.

Проверка автозамыкания начинается только когда до клика path уже содержит минимум две вершины, поэтому добавление B создаёт prospective path минимум из трёх вершин. Для подходящего клика редактор рассматривает prospective polygon [..., P, B] + B—A и требует минимум три различные вершины. До пользовательского диалога он применяет те же проверки минимального размера, нулевой площади, self-intersection, overlap и общих geometry limits, что и обычное замыкание.

Если контур валиден, одним пользовательским действием:

1. B становится настоящей последней вершиной нового контура;
2. нарисованный сегмент P—B сохраняется как обычный завершённый draft segment с выбранной для него толщиной;
3. B—A считается замыкающим ребром комнаты;
4. открывается существующий диалог имени/HA-зоны комнаты.

Отдельного confirm, toast об успехе или промежуточного UI нет.

8.2 Невалидный prospective contour

Если при достаточном количестве вершин подходящий клик дал невалидный prospective polygon:

• диалог комнаты не открывается;
• B, P—B и B—A не записываются;
• draft остаётся в том же редактируемом состоянии, что до клика;
• показывается существующий подходящий validation toast;
• config, layout и history не получают частично применённой операции.

Клик не превращается после ошибки в обычное добавление B: подходящая точка уже означает намерение замкнуть контур, как клик в собственную первую точку. Недостаточное количество вершин не является такой ошибкой: оно отсекается до eligibility и обрабатывается как обычный клик по §8.3 без toast.

8.3 Обычный клик

Если общего room-owned solid interval нет либо после добавления resolved-точки в path всё ещё будет меньше трёх вершин, поведение остаётся полностью текущим: resolved-точка добавляется в открытый draft, сегмент сохраняется, а диалог не открывается. Это относится в том числе к:

• второму клику B после единственной первой точки A, даже если A и B — разные endpoints одной существующей стены;
• разным рёбрам одной комнаты;
• разным комнатам;
• точкам по разные стороны opening/open-span cut;
• room_draft и partition;
• обычной точке сетки рядом со стеной.

После такого клика пользователь по-прежнему может явно замкнуть контур первой точкой или Ctrl/Cmd + click.

9. Draft, диалог, история и толщина

• Каждый явно нарисованный сегмент до и включая P—B сохраняет текущую толщину в room_drafts по существующему контракту.
• Неявный B—A не создаёт independent partition или отдельную физическую запись. Он становится room-boundary edge только при сохранении комнаты.
• Save удаляет соответствующий draft и создаёт обычную комнату через текущий commit/history boundary.
• Cancel стандартного диалога снимает состояние замкнутого контура, но оставляет открытый draft с последней настоящей точкой B и сегментом P—B, как при существующем ручном замыкании.
• Оставить замкнутыми стенами продолжает использовать текущий путь конвертации рёбер в independent partitions.
• Undo/Redo, смена инструмента, reload/resume, external config adoption и лимит 50 команд не получают отдельной ветки поведения.
• На общей границе B—A сохраняется уже существующая толщина соседней комнаты. Выбранная толщина рисования применяется только к новым внешним участкам по действующему applyWallThicknessToNewRoom-контракту.
• Room-boundary walls остаются производными и дедуплицированными. Автозамыкание не создаёт вторую физическую стену поверх общей границы.

10. Touch, accessibility и визуальная деградация

Touch editor: best effort / intentionally degraded.

• Tap без предварительного pointermove повторно решает snap и выполняет тот же контракт автозамыкания.
• Hover или увеличенная точка до tap на no-hover устройстве не обещаются.
• Pinch, pan, pointercancel, второй touch и suppressed synthetic click не должны замыкать или менять draft.
• Новый DOM, focus target, ARIA-содержимое или клавиатурная команда не создаются.
• View и kiosk не меняют pixels, gestures или действия.

11. Модель данных, совместимость и миграция

Новых данных нет.

• rooms[].poly, room_drafts, walls, openings и open_spans сохраняют текущую схему;
• старые и импортированные планы читаются без миграции;
• backend validation и integration API не меняются;
• downgrade не требует data rollback: созданная комната является обычным polygon;
• новая версия меняет только момент интерпретации подходящего финального клика.

12. Архитектурный и performance-контракт

1. Проверка общего интервала является чистой геометрической операцией над существующим immutable snap snapshot; SVG DOM не является источником данных.
2. Canonical opening/open-span cuts переиспользуются из plan-snap-overlay.ts или эквивалентного общего helper, без дублирования wall topology.
3. Проверка выполняется только на click/tap. Она не добавляет работу в pointermove, не пересобирает статическую геометрию и не меняет O(E) overlay DOM #137.
4. Линейный O(S) просмотр room-owned solid segments на click допустим. Новый постоянно растущий cache или spatial index не требуется.
5. Prospective validation завершается до mutation. Успех использует существующие draft/save/history границы; ошибка не требует rollback частичного состояния.
6. Решение не создаёт websocket, HA service, fetch, timer, storage key или внешнюю зависимость.

13. Acceptance criteria

• AC1 (unit + smoke; разработчик): контур, начатый в endpoint A завершённой room wall, после обхода нового помещения заканчивается в другом endpoint B того же непрерывного solid interval; финальный click сохраняет P—B, замыкает polygon через B—A и сразу открывает стандартный room dialog.
• AC2 (unit + smoke; разработчик): тот же результат получается, когда A, B или обе точки являются line-snap точками внутри одного solid room interval; сохранённые координаты остаются точно на существующей стене.
• AC3 (unit + smoke; разработчик): если path содержит только первую точку A, второй click в отличный endpoint/line-node B того же solid room interval не запускает автозамыкание и validation: B добавляется как обычная точка открытого draft без dialog и toast, после чего контур можно продолжить.
• AC4 (unit + smoke; разработчик): разные рёбра одной комнаты, стены разных комнат, saved draft и partition не запускают автозамыкание: финальная точка остаётся обычной точкой открытого draft, а явное замыкание первой точкой и Ctrl/Cmd продолжают работать.
• AC5 (unit + smoke; разработчик): door/window/gate или open_span между A и B разрывает общий interval и не допускает автозамыкание; cut boundary не становится новым endpoint и отдельный resolver проёмов не появляется.
• AC6 (unit + smoke; разработчик): при достаточном числе вершин zero-area, self-intersecting, overlapping, слишком маленький или выходящий за лимиты prospective contour не открывает диалог, показывает существующий validation toast и оставляет draft, config и history в состоянии до финального клика.
• AC7 (unit + smoke; разработчик): успешный финальный P—B сохраняет выбранную толщину; Cancel оставляет открытый draft с B, Save создаёт комнату и удаляет draft, а secondary action создаёт замкнутые стены по текущему контракту.
• AC8 (unit + wall-thickness regression; разработчик): B—A использует существующую толщину общей стены, новые внешние рёбра сохраняют свои per-segment значения, room geometry не создаёт duplicate partition или двойное физическое wall body.
• AC9 (unit + code review; разработчик/ревьюер): собственная первая точка и Ctrl/Cmd имеют прежний приоритет, current anchor остаётся no-op, а eligibility решается до resume/draft endpoint handling.
• AC10 (smoke; разработчик): tap без hover выполняет тот же результат; pan, pinch, pointercancel и suppressed synthetic click не меняют geometry. View, kiosk, остальные Plan tools и другие editors не меняются.
• AC11 (unit + performance review; разработчик/ревьюер): общий interval определяется из уже кэшированного snapshot чистым O(S) helper только на click; pointermove, cache size, DOM count и network/storage activity #137 не растут.
• AC12 (typecheck + unit + build + documentation review; разработчик): implementation-loop gates зелёные, три bundle-копии побайтно одинаковы, пользовательская документация и оба changelog обновлены в том же видимом коммите.
• AC13 (schema/security review; ревьюер): backend, schema, import/export, i18n, HA permissions/calls и зависимости не меняются; старые планы совместимы.

14. План автотестов

14.1 Unit

Добавить pure-helper покрытие:

1. оба endpoints одного room segment дают общий interval;
2. endpoint + interior point и две interior line-snap точки дают общий interval;
3. при path [A] второй click B на том же room interval не вызывает eligibility, dialog или toast, а добавляет B и A—B в открытый draft;
4. угол, принадлежащий двум рёбрам, соединяется только с точкой на одном из них;
5. разные рёбра/rooms, draft и partition возвращают отсутствие eligibility;
6. opening/open-span cut разделяет исходную прямую на разные intervals;
7. reversed segment, floating tolerance и stable tie дают тот же результат;
8. одинаковые A/B, zero-length и current anchor не подходят;
9. prospective polygon валидируется до mutation для success и каждого класса существующей ошибки;
10. shared-wall thickness и внешние per-segment thickness сохраняются.

Каждый тест должен падать отдельно при ослаблении sourceKind, игнорировании cut, смешивании разных рёбер, добавлении точки до validation или перезаписи толщины.

14.2 Targeted browser smoke

Расширить demo/smoke_plan_snap_overlay.mjs либо добавить отдельный production-bundle smoke:

1. создать существующую комнату, opening/open span, draft и partition;
2. начать A→B по двум точкам одной существующей стены и проверить, что второй click добавляет B без dialog/toast и оставляет открытый draft;
3. нарисовать соседний контур endpoint→внешние точки→endpoint той же стены и проверить немедленное открытие room dialog;
4. повторить с mid-line point и diagonal room edge;
5. доказать отрицательные случаи different edge, cut, draft и partition;
6. доказать отсутствие partial write при self-intersection/overlap;
7. проверить Cancel, Save, secondary action, reload/resume и Undo/Redo;
8. проверить inherited shared thickness и разные толщины внешних сегментов;
9. повторить tap без pointermove и gesture-safety случаи.

Targeted smoke пишется вместе с кодом; полный smoke-suite запускается перед бетой.

14.3 Golden и performance

Новых pixels, стилей и состояний overlay нет, поэтому новый golden baseline не нужен. Существующие editor/View golden должны остаться без изменений; любое изменение baseline требует отдельного объяснения и review.

Отдельный performance fixture не нужен: новый O(S) поиск выполняется только на click. Перед бетой обязательны существующие performance smoke и Full Performance на точном SHA без ослабления budgets.

14.4 Backend

Backend не меняется. Нового backend-теста не требуется; полный Linux Validate остаётся release gate.

15. План реализации

1. Добавить чистый helper принадлежности двух точек одному room-owned solid segment в snap geometry #137.
2. Отделить prospective validation от mutation либо дать текущему close helper безопасно проверить путь с новым терминальным B.
3. Подключить eligibility в _markupClick() после click re-resolution и до обычного draft/resume handling.
4. На success сохранить P—B обычным draft-механизмом и открыть существующий dialog с B—A; на failure не менять state.
5. Добавить unit и production-bundle smoke.
6. Обновить docs/ARCHITECTURE.md, docs/CANVAS.md, docs/USER-GUIDE.ru.md, оба changelog и три bundle-копии.

Имена helper-функций и приватных полей не являются продуктовым контрактом.

16. Release-артефакты

Изменение пользовательское: implementation-коммит имеет User-Visible: yes и в том же коммите обновляет:

• docs/CHANGELOG.md;
• docs/CHANGELOG.ru.md;
• docs/USER-GUIDE.ru.md — автозамыкание соседней комнаты;
• docs/CANVAS.md и docs/ARCHITECTURE.md — внутренний snap/markup контракт;
• три поставляемые bundle-копии.

Новый screenshot/golden не требуется, потому что визуал #137 не меняется.

Перед бетой обязательны:

• exact-SHA Linux Validate;
• полный smoke-suite;
• существующие golden без необъяснённого diff;
• performance smoke и Full Performance на точном SHA;
• code review с отрицательным security/network/schema verdict.

Отдельный security report не нужен: новых внешних данных, HTML input, HA calls, network или storage путей нет. Публикация проходит через бету до stable.

17. Риски и меры

Риск	Вероятность / влияние	Мера
Разные рёбра ошибочно считаются одной стеной	средняя / высокий	проверять один canonical segment, unit на corner/different edge
Автозамыкание проходит через проём	средняя / высокий	использовать cut snapshot #137, unit + smoke opening/open-span
Второй узел общей стены ошибочно трактуется как невалидное замыкание	средняя / высокий	minimum-vertex gate до eligibility, отдельные unit + smoke
Невалидный click частично сохраняет draft	средняя / высокий	prospective validation до mutation, state/history assertions
Resume endpoint перехватывает финальный click	средняя / высокий	eligibility до _draftEndAt(), integration smoke
Общая стена получает новую толщину	средняя / высокий	действующий wall inheritance helper + regression matrix
Cancel теряет финальный нарисованный сегмент	средняя / средний	явный Cancel contract и smoke snapshot draft
Поведение touch расходится с click	низкая / средний	re-resolve на tap, gesture-safety regression
Click начинает пересобирать overlay	низкая / средний	использовать cached snapshot, performance/code review

18. Откат

Откат — revert implementation-коммита #138 вместе с тестами, документацией, changelog и bundle-копиями. Persisted schema не меняется, поэтому data rollback и миграция не нужны. Комнаты, сохранённые новой версией, являются обычными polygons и полностью читаются предыдущей версией.

19. Принятые технические предположения — можно менять без продуктового ревью

1. Eligibility helper рекомендуется разместить в src/plan-snap-overlay.ts и передавать ему готовый snapshot; точное имя и сигнатура свободны.
2. Геометрическая точность использует существующий samePoint/segment epsilon или более строгий эквивалент, совместимый с grid- и wall-bound координатами. Она не превращается в новую CSS hit tolerance.
3. При нескольких одинаково подходящих room segments применяется стабильный ключ #137; persisted id результата не нужен.
4. Prospective validation может быть вынесена из _closeRoomContour() в pure helper либо параметризовать существующий путь, если success/error contract не меняется.
5. Успешное добавление B может использовать текущий _persistActiveDraftSegment(); отдельной транзакции backend не требуется.
6. При достаточном числе вершин geometry validation error не добавляет B. Если же B была бы только второй вершиной, eligibility не запускается и B добавляется обычным способом без ошибки; это воспроизводит существующий minimum-vertex gate ручного замыкания.
7. Никаких открытых продуктовых вопросов нет: Q1–Q5 и технические defaults приняты владельцем 2026-08-14.