houseplan-card/docs/specs/137-plan-snap-overlay.md

Issue #137 — узлы и линии привязки в редакторе Плана

• Issue: https://github.com/Matysh/houseplan-card/issues/137
• Редакция: первая редакция для независимого ревью; статус определяется только метками issue
• Тип / приоритет: feature + polish / P2
• Оценка: пользовательская ценность 7/10; ценность для разработки 5/10; сложность и риск 6/10
• Область: редактор Плана, инструменты «Контур» и «Перегородка», производный SVG-слой архитектурных сегментов и узлов, pointer/click snap
• Модель данных: без новых полей, миграции и backend-изменений
• Связано: #75, #91, docs/SCOPE.md, docs/TOUCH-SUPPORT.md, docs/CANVAS.md, docs/UX-MODES.md

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

Персона: администратор дома — основной пользователь редакторов House Plan.

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

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

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

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

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

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

После: поверх стен видны тонкие осевые линии и точки их концов, а endpoint или динамическая точка на линии увеличивается там, куда точно присоединится следующий клик.

3. Проблема

Сейчас _snapDrawPoint() знает только глобальную сетку и Shift/45°. Текущий _renderMarkupLayer() показывает вершины live-пути, но не даёт единого верхнего слоя уже сохранённой архитектуры. Основная markup-геометрия также рисуется до физических wall bodies и может быть ими закрыта.

В результате пользователь не различает три разные ситуации:

1. клик попадёт точно в существующий endpoint;
2. клик соединит новый отрезок с серединой существующей стены;
3. клик останется обычной точкой сетки рядом со стеной и оставит зазор.

4. Scope

В issue входят:

1. Производный pointer-transparent overlay только для активных инструментов «Контур» и «Перегородка» в редакторе Плана.
2. Тонкие линии по фактически сплошным интервалам:
   • завершённых контуров комнат;
   • сохранённых открытых контуров (room_drafts);
   • независимых перегородок (partitions).
3. Статические точки в реальных координатах начала и конца исходных сегментов.
4. Endpoint-snap и line-snap для первого и последующих кликов обоих инструментов.
5. Динамический промежуточный узел на выбранной линии.
6. Единый resolver кандидата для hover-preview и commit клика.
7. Светлая, тёмная и forced-colours читаемость без нового пользовательского параметра.
8. Unit, production-bundle smoke, editor golden и performance-покрытие.
9. Описание принятого snap-контракта в документации редактора.

5. Non-scope

В issue не входят:

• View, kiosk, редактор Устройств и редактор Подложки;
• новые инструменты, режимы, кнопки, настройки или i18n-текст;
• колонны, мебель, декор, устройства и сами проёмы как snap-кандидаты;
• привязка к пересечению продолжений линий, центрам, касательным или произвольным направляющим;
• автоматическое дробление существующей комнаты, draft или partition при T-соединении;
• изменение толщины, ключей, порядка или семантики существующих сегментов;
• исправление старой off-grid геометрии и массовая оптимизация планов;
• полноценный hover-паритет редактора на coarse pointer;
• новая схема, backend API, storage key, импорт/экспорт или миграция.

6. Контракт отображения

6.1 Когда слой существует

Overlay создаётся только когда одновременно выполняются условия:

• режим — редактор Плана;
• активный инструмент — «Контур» или «Перегородка»;
• существует текущее пространство.

Он виден уже до первого клика. При смене инструмента, пространства, выходе в View, закрытии редактора или потере pointer из сцены активный кандидат очищается; сам статический слой исчезает, когда инструмент больше не подходит.

6.2 Геометрия линий

Линии повторяют оси существующих стен и перегородок и рисуются поверх их физических тел. Они строятся из модели, не измеряют SVG DOM и не становятся новым источником геометрии.

Из линии и line-snap исключаются:

• дверные, оконные и воротные вырезы;
• намеренно открытые open-span интервалы;
• нулевые и невалидные интервалы;
• сегменты текущего активного draft и live-preview.

Вырезы применяются к каноническому сегменту до отображения и hit resolution. Статический endpoint исходного сегмента остаётся кандидатом только если к нему примыкает положительный сплошной интервал. Граница проёма сама по себе не создаёт новый постоянный endpoint.

6.3 Геометрия точек

• Обычная статическая точка имеет физический радиус 5 см в координатах плана.
• Активный endpoint и динамический line-node имеют физический радиус 10 см и дополнительный контрастный контур.
• Совпадающие endpoints разных сегментов отображаются одной точкой.
• Точка остаётся привязана к модели при pan/zoom; её физический размер масштабируется вместе с планом и не превращается в фиксированный screen-space marker.
• Тонкая линия имеет толщину 1 CSS px независимо от zoom.

Точные цветовые токены являются технической деталью, но линия, обычная точка и активная точка должны различаться в светлой, тёмной и forced-colours теме. Никакой пульсации или постоянной анимации нет.

6.4 Layering и интерактивность

Архитектурный overlay рисуется после room/partition wall bodies и до верхнего интерактивного editor chrome. Он:

• имеет pointer-events:none на группе и дочерних элементах;
• не создаёт focusable/ARIA-содержимое;
• не перехватывает click, pan, pinch, room card, opening и context tray;
• не меняет hit-testing существующих инструментов.

7. Контракт выбора кандидата

7.1 Общая зона

Resolver использует зону захвата 12 CSS px, переведённую в координаты текущего view. Поэтому зона pointer-попадания стабильна на экране и не зависит от zoom, хотя видимый радиус точек остаётся физическим.

Один и тот же чистый resolver вызывается:

• на pointermove — для отображения активной точки и live-preview;
• непосредственно на click/tap — для commit, даже если до него не было pointermove.

Hover-состояние никогда не считается авторитетом для commit: клик повторно решает кандидата из своих координат и актуальной геометрии.

7.2 Приоритет и стабильность

Результат всегда один:

1. если в зоне есть существующий endpoint, выбирается ближайший endpoint;
2. только при отсутствии endpoint выбирается ближайший сплошной сегмент;
3. совпадающие endpoints дедуплицируются;
4. равные расстояния разрешаются детерминированным стабильным порядком геометрии, не зависящим от частоты pointermove;
5. текущий anchor исключается как кандидат нулевого отрезка.

Endpoint имеет приоритет, даже если другая линия формально ближе. Это делает визуально увеличенную точку точным обещанием следующего клика и предотвращает мерцание между endpoint и line-node.

7.3 Endpoint-snap

Если выбран endpoint:

• live-preview оканчивается в его точной сохранённой координате;
• точка увеличивается до 10 см;
• click сохраняет ровно ту же координату;
• правило действует для первого и последующих кликов «Контура» и «Перегородки».

Endpoint-snap внутри активной зоны сильнее обычной сетки и Shift/45°. Вне зоны текущий grid-bound + Shift/45° контракт остаётся без изменений.

7.4 Line-snap и динамический узел

Если endpoint не выбран, но pointer находится в зоне линии:

1. raw pointer проецируется на ближайший сплошной сегмент;
2. расстояние вдоль сегмента квантуется с текущим шагом сетки, отсчитанным от стабильного начала сегмента;
3. итоговая точка остаётся точно на линии;
4. на ней отображается единственный динамический узел радиусом 10 см;
5. live-preview и click используют одну и ту же итоговую координату.

На диагонали wall-bound точка не обязана одновременно быть глобальным узлом по X и Y. Это тот же класс координат, который уже применяется для wall-bound opening и split points в docs/CANVAS.md §9.3.

Динамический узел — только preview. После клика существующий сегмент не дробится и не переписывается; новый отрезок получает endpoint в wall-bound координате, поэтому возникает реальное геометрическое T-соединение.

7.5 Текущий контур и валидация

Активный draft и live-preview исключены из общего overlay и resolver. Исключение — первая точка текущего контура, когда существующий сценарий разрешает его замыкание. Другие вершины и сегменты текущего пути не создают ответвления или self-snap.

Snap не обходит существующие правила:

• повторный click в текущий anchor остаётся no-op;
• самопересечение, overlap, минимальное число сторон и лимиты сохраняются;
• невалидное замыкание продолжает показывать существующий toast;
• отмена, Undo/Redo и history boundary остаются прежними.

8. Touch, accessibility и безопасная деградация

Touch editor: best effort / intentionally degraded.

• Статические линии и точки могут отображаться на coarse pointer.
• Tap непосредственно выполняет тот же resolver и может точно соединить endpoint или линию без предварительного hover.
• Отдельное состояние увеличенной точки до tap на устройстве без hover не гарантируется.
• Pinch, cancelled pointer и синтетический click после pan не должны создавать геометрию; действующий _suppressClick/gesture safety contract сохраняется.
• View и kiosk не создают overlay DOM и не меняют gestures, действия или pixels.

Вспомогательная геометрия декоративна для accessibility: она скрыта от assistive technology, а новая клавиатурная навигация в editor не вводится.

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

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

• rooms[].poly, room_drafts, partitions, walls и openings сохраняют текущую схему;
• mid-line snap не вставляет точку в существующий сегмент;
• overlay/hover не пишет config, layout или local storage;
• write происходит только в существующем commit действия «Контур» или «Перегородка»;
• импорт, экспорт, downgrade и старые конфиги не требуют миграции;
• backend validation и integration API не меняются.

10. UX и i18n

Новых строк, кнопок и настроек нет, поэтому i18n-ключи не добавляются.

docs/USER-GUIDE.ru.md должен объяснить одной короткой секцией:

• линии/точки появляются при рисовании контура или перегородки;
• увеличенная точка показывает точное место следующего соединения;
• endpoint имеет приоритет, а точка на линии создаёт T-соединение;
• desktop остаётся рекомендуемой поверхностью редактора.

Публичное обещание не распространяется на hover-паритет touch editor.

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

1. Производная архитектурная геометрия собирается из модели и может быть вынесена в чистый helper; SVG DOM не является источником данных.
2. Статический набор линий/endpoints кэшируется по структурному fingerprint либо эквивалентному стабильному ключу и не пересобирается на каждый pointermove.
3. Pointermove не пишет состояние модели, config/storage и не создаёт новый массив SVG-узлов сверх обновления единственного active candidate.
4. Количество статических SVG-элементов ограничено O(E): один элемент на сплошной интервал и один на уникальный endpoint. Динамический line-node — не более одного.
5. Resolver может быть линейным от числа кандидатов на первом этапе, но большой fixture обязан пройти неизменные performance-бюджеты. Пространственный индекс допустим как техническая оптимизация, если не меняет контракт выбора.
6. Cut-геометрия переиспользует канонические opening/open-span решения и не изобретает второй способ трактовать проёмы.
7. Overlay не создаёт websocket, HA service, fetch, timer или внешнюю зависимость.

12. Acceptance criteria

• AC1 (unit + smoke; разработчик): только в Plan editor при активном «Контуре»/«Перегородке» поверх физических стен существует pointer-transparent overlay завершённых room contours, неактивных saved drafts и partitions; View, kiosk и остальные editor tools не создают его DOM.
• AC2 (unit + golden; разработчик): каждый уникальный исходный endpoint с примыкающим сплошным интервалом показан одной точкой радиусом 5 см; линии имеют 1 CSS px и повторяют solid intervals; active endpoint/dynamic node имеют радиус 10 см и читаемый контур в light/dark/forced colours.
• AC3 (unit + smoke; разработчик): первый и последующие клики обоих инструментов внутри 12 CSS px endpoint показывают один active endpoint, ведут live-preview в него и сохраняют его точную координату; endpoint приоритетнее любой линии.
• AC4 (unit + smoke; разработчик): при попадании на solid line вне endpoint-priority отображается один динамический узел в wall-bound координате, квантованной вдоль линии; click создаёт точное T-соединение и не дробит/не переписывает существующий сегмент.
• AC5 (unit; разработчик): совпадающие endpoints дедуплицируются, ближайший кандидат выбирается детерминированно, равные расстояния не мерцают, а resolver pointermove и resolver click возвращают одинаковый результат для одинакового snapshot.
• AC6 (unit + smoke; разработчик): активный draft/live-preview исключён из общего snap; первая точка остаётся целью разрешённого замыкания, current anchor не создаёт нулевой сегмент, а другие точки текущего пути не создают self-branch.
• AC7 (unit + golden; разработчик): door/window/gate и open-span интервалы отсутствуют в линии и line-snap; границы выреза не становятся постоянными endpoints; columns/openings/decor/devices не входят в кандидаты.
• AC8 (unit + smoke; разработчик): активный endpoint/line candidate сильнее grid и Shift/45°, а вне 12 CSS px существующие grid-bound, Shift/45°, contour validity, limits и toast contracts остаются без изменений.
• AC9 (unit + code review; разработчик/ревьюер): hover и candidate resolution не пишут config/layout/local storage; commit использует существующие history, Undo/Redo и save boundaries и добавляет только новый endpoint нового отрезка.
• AC10 (smoke; разработчик): tap без предшествующего pointermove повторно решает кандидата и соединяет геометрию; pan, pinch, pointercancel и suppressed synthetic click не создают отрезок. Hover-паритет coarse pointer не требуется.
• AC11 (smoke + existing View golden; разработчик): overlay не перехватывает pointer/focus/ARIA, не меняет View/kiosk pixels и gestures, room/opening/editor chrome interactions и lock/action contract.
• AC12 (performance + code review; разработчик/ревьюер): large-house fixture с 60 комнатами и 60 partitions проходит overlay render и серию pointermove без роста cache/DOM между стабильными кадрами; существующие performance budgets не ослаблены, exact-SHA Full Performance перед бетой зелёный.
• AC13 (unit + backend/schema review; разработчик/ревьюер): config schema, import/export, backend, storage keys, i18n и зависимости не меняются; старые планы читаются без миграции.
• AC14 (typecheck + unit + build + documentation review; разработчик): implementation-loop gates зелёные, три bundle-копии побайтно одинаковы, оба changelog и пользовательская/internal документация обновлены в видимом коммите.

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

13.1 Unit

Добавить чистое покрытие сборщика и resolver:

1. room rectangle, polygon, saved open draft и partition дают ожидаемые segments и endpoints;
2. совпадающие room/partition endpoints дедуплицируются независимо от направления;
3. active draft, zero-length и columns исключаются;
4. opening/open-span cuts оставляют только solid intervals и не создают endpoints на границах cut;
5. endpoint выигрывает у более близкой линии в общей 12 px зоне;
6. nearest line projection и quantisation along segment стабильны для horizontal, vertical и diagonal случаев;
7. tie разрешается одинаково при перестановке pointermove и не меняет snapshot;
8. current anchor исключён, first contour point разрешён только для closure;
9. candidate overrides Shift, а no-candidate сохраняет существующий grid/45 output;
10. cache/fingerprint меняется от структурной геометрии и не меняется от hover.

Каждый тест должен уметь падать отдельно: удаление dedup, смена приоритета, возвращение точки в opening gap, off-wall округление или включение active draft делают соответствующий тест красным.

13.2 Targeted browser smoke

Добавить production-bundle сценарий, например demo/smoke_plan_snap_overlay.mjs:

1. открыть Plan editor с комнатой, saved draft, partition, door и open span;
2. переключать «Контур»/«Перегородка» и другие tools, проверяя наличие/отсутствие overlay и его DOM-порядок после wall bodies;
3. pointermove к endpoint — active radius/класс, preview и commit exact coordinate;
4. pointermove к середине horizontal и diagonal line — dynamic node, wall-bound quantisation и T-join без split исходного segment;
5. доказать endpoint priority, first-click snap и Shift override;
6. доказать отсутствие snap в opening/open-span gap и сохранение обычной grid snap;
7. closure current first point работает, intermediate self-snap отсутствует;
8. tap без pointermove соединяет, а pan/pinch/cancel/suppressed click не пишет;
9. выйти в View/другой editor и убедиться, что overlay DOM исчез и pixels/actions не изменились.

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

13.3 Golden

Добавить либо расширить editor matrix минимум двумя кадрами:

• light: статические линии/endpoints и active endpoint поверх толстых стен;
• dark: dynamic mid-line node, opening/open-span gaps и T-preview поверх стены.

Проверяются физические размеры относительно масштаба плана, слой над wall bodies, контраст и отсутствие линии через вырезы. View baselines должны остаться pixel-identical.

Golden принимаются только из полного просмотренного Linux artifact через npm run golden:accept -- --reviewed с обязательными трейлерами процесса.

13.4 Performance

Расширить large-house harness либо добавить отдельный overlay profile:

• 60 rooms, 60 partitions, opening cuts и несколько saved drafts;
• первый render статического overlay;
• серия не менее 100 pointermove по endpoint, line и miss;
• bounded DOM, cache cap/growth и отсутствие config/network writes;
• сравнение exact candidate с base при неизменных budgets.

Локальный performance-run диагностический. Перед бетой обязательны зелёные performance smoke и Full Performance на точном SHA кандидата.

13.5 Backend

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

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

1. Ввести чистые типы/сборщик architectural snap geometry и resolver кандидата.
2. Подключить к нему канонические room/draft/partition segments и существующие cuts.
3. Разделить raw pointer, resolved candidate и committed point так, чтобы click всегда re-resolve актуальный snapshot.
4. Добавить верхний pointer-inert SVG overlay и theme/forced-colours styles.
5. Добавить unit, targeted smoke, golden/performance fixtures.
6. Обновить docs/CANVAS.md, docs/USER-GUIDE.ru.md, оба changelog и bundle-копии.

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

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

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

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

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

• exact-SHA Linux Validate;
• полный smoke-suite;
• просмотренный и принятый Linux golden artifact;
• performance smoke и Full Performance на точном SHA с неизменными budgets;
• code review с отрицательным security/network/schema verdict.

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

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

Риск	Вероятность / влияние	Мера
Overlay закрыт толстой стеной или opening symbol	medium / high	явный DOM-order smoke и editor golden
Endpoint/line меняются между hover и click	medium / high	один pure resolver, обязательный re-resolve на click
T-node оказывается off-wall после grid snap	medium / high	wall-bound projection + along-segment quantisation units
Opening gap остаётся кликабельной линией	medium / high	единая cut-геометрия, unit + golden gap case
Active draft привязывается сам к себе	medium / high	исключение по active id, отдельный closure case
Много SVG-узлов ухудшает pointermove	medium / high	structural cache, O(E) DOM, large-house performance profile
Точки 5 см плохо видны далеко	medium / low	это принятый физический размер; контрастный stroke и 12 px hit tolerance
Touch tap и hover расходятся	medium / medium	re-resolve непосредственно на tap, hover parity не обещается
Snap обходит overlap/self-intersection	low / high	существующая validation после resolution, regression smoke
Overlay попадает в View/kiosk	low / high	mode/tool guard, DOM absence smoke, unchanged View golden

17. Откат

Откат — revert implementation-коммита #137 вместе с тестами, документацией, changelog и bundle-копиями. Persisted schema не меняется, поэтому data rollback и миграция не нужны; созданные новой версией endpoints остаются валидной существующей геометрией и читаются старой версией.

Если перед бетой красный только новый визуальный/performance gate, релиз блокируется: feature flag или ослабление budget не вводятся как аварийный обход.

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

1. Рекомендуется новый чистый src/plan-snap-overlay.ts (или эквивалент) с типами segment/endpoint/candidate; точное имя и раскладка файлов свободны.
2. Stable tie key может состоять из нормализованных координат, kind и persisted id; конкретный формат не хранится и не публикуется.
3. Dedup использует существующую точность samePoint либо более строгую grid-compatible нормализацию; он не объединяет визуально близкие, но разные узлы.
4. Screen tolerance вычисляется из текущего view/stage scale один раз на event; допустима единая isotropic scale для SVG preserveAspectRatio.
5. Статический geometry cache может быть keyed существующим _cfgEpoch плюс structural fingerprint или только полным fingerprint; HA state/theme/hover в key не входят.
6. Цвета берутся из существующих editor accent/contrast tokens. Можно выбрать dashed или solid line, если golden сохраняет однозначную непрерывность и 1 px толщину.
7. Forced-colours реализация может использовать media query и системные цвета; отдельная настройка не нужна.
8. Canonical cuts можно получать до SVG render или через чистый helper, но не через DOM measurement и не через второй независимый opening resolver.
9. Unit-тесты могут держать новые helper-файлы отдельно от монолитного card test; browser smoke остаётся авторитетом integration/layer/click контракта.
10. Нет открытых продуктовых вопросов: D1–D5 и Q1–Q7 приняты владельцем 2026-08-14.