houseplan-card/legacy/specs/445-furniture-wall-face-snap.md

ТЗ #445 — Магнит мебели к физической поверхности стены

• Issue: https://github.com/Matysh/houseplan-card/issues/445
• Приоритет: P2, bug
• Статус ТЗ: готово к ревью
• Маршрут: full; меняется физический контракт магнита мебели одновременно для preview, первого размещения и перемещения
• Связанные контракты: #359 (preview равен сохранённому результату), #383 (трансформации мебели), #233 (размеры от внутренних граней), #201 (локальная атомарная толщина стены)

Сценарий

Home admin в Редакторе подложки выбирает телевизор, шкаф или другой предмет с выраженной задней гранью и подводит его к стене комнаты. Магнит должен поставить предмет вплотную к видимой поверхности стены со стороны комнаты. То же правило действует, когда уже сохранённый предмет перетаскивают к другой стене.

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

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

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

Подтверждённая проблема

1. HouseplanEditorRuntime._furnWalls объединяет roomEdges с гранями только независимых тел. Для комнатных стен передаются осевые линии без толщины.
2. snapFurnitureToWall принимает голый [x1,y1,x2,y2], кладёт BACK мебели на этот сегмент и смещает центр только на половину глубины предмета. Половина толщины стены в расчёте отсутствует.
3. _decorSnap до вызова resolver штатно переносит указатель на контур комнаты. В результате исходная сторона теряется, а ветка nl < 1e-9 выбирает левую нормаль из направления записи ребра. Эта нормаль не является внутренней стороной комнаты.
4. И placement preview, и commit используют _resolveFurniturePlacement, но перемещение существующей мебели вызывает snapFurnitureToWall отдельно. Без общего физического входа эти пути могут разойтись.
5. test/furniture.test.mjs использует roomEdges голого полигона и прямо ожидает центр = осевая + глубина/2. Ненулевая толщина стены в фикстуре отсутствует, поэтому тест закрепляет дефект.

Скоуп

В скоупе:

• явная модель кандидата поверхности для магнита мебели вместо голого центролинейного сегмента;
• внутренние поверхности внешних стен комнат;
• обе внутренние поверхности общих стен с выбором стороны по исходному указателю;
• локальная атомарная толщина на участке проекции;
• сохранение исходной, ещё не притянутой точки до _decorSnap;
• стабильная сторона при точном попадании на ось;
• радиус магнита от физической поверхности, а не от осевой линии;
• один pure resolver и одна семантика для hover preview, clean tap и drag существующей мебели;
• прежнее поведение нулевых стен и физических граней независимых тел;
• unit, browser smoke, mutation witnesses и визуальный regression fixture;
• документация и оба changelog.

Не-скоуп

• collision model мебели с дверями, окнами, колоннами, другой мебелью или границами комнаты;
• автоматический поиск свободного места вдоль стены;
• привязка сохранённой мебели к wall id и автоматическое следование будущему resize стены;
• изменение размеров, rotation/Shift, зеркалирования и hit area из #383;
• изменение каталога либо SVG-рисунков мебели;
• изменение толщины, геометрии или рендера самих стен;
• новая настройка силы магнита или UI-индикация поверхности;
• миграция уже сохранённых предметов;
• новые жесты, диалоги, тексты или ключи i18n.

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

1. Физический кандидат стены

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

• конечный атомарный интервал оси;
• параллельная ему поверхность;
• единичная нормаль от поверхности в сторону допустимого тела мебели;
• вид владельца: внутренняя грань комнаты либо обычная грань независимого тела;
• стабильная identity/tie-break информация, не зависящая от порядка комнат и направления ребра.

Для комнатной стены поверхность строится из существующего атомарного wall profile: axis + inwardNormal * halfDepth. Значение halfDepth берётся у локального атома под проекцией, поэтому перепад толщины на том же исходном ребре не размазывается на соседний участок.

Внешняя стена даёт один допустимый room-facing candidate. Общая стена даёт по одному candidate для каждой смежной комнаты. Нулевая/виртуальная стена имеет halfDepth = 0, поэтому её поверхность совпадает с осью и видимое положение остаётся прежним.

Грани partitions и wall_columns, которые уже приходят как физические полигоны, не получают повторного offset: их сегмент уже является поверхностью.

2. Выбор стороны

Resolver различает:

• точку размещения после действующего grid/decor snap — она определяет положение вдоль поверхности;
• точку намерения до snap — она определяет, с какой стороны пользователь подвёл предмет;
• при перемещении — предыдущую сторону предмета как tie-break для точного равенства.

Правила выбора:

1. У внешней комнатной стены всегда выбирается единственная внутренняя поверхность. Положение указателя чуть снаружи не отправляет предмет на фасад; намеренное свободное размещение снаружи остаётся доступно через Shift.
2. У общей стены выбирается candidate на стороне точки намерения относительно оси.
3. Если точка намерения лежит на оси в пределах числового epsilon, drag сохраняет текущую сторону предмета, чтобы тот не прыгнул через стену.
4. Для нового предмета без прежней стороны точное равенство разрешается устойчивым tie-break по стабильной identity смежных комнат. Результат не зависит от winding, направления ребра или порядка массива.
5. У независимого физического тела сохраняется выбор ближайшей к точке намерения грани; его можно обойти с любой стороны, как сейчас.
6. В углу либо при равном расстоянии до нескольких стен выигрывает физически ближайшая поверхность, затем сторона намерения, затем стабильный tie-break. Перестановка входных массивов не меняет результат.

Левая нормаль направления ребра больше не является допустимым продуктовым fallback для комнатной стены.

3. Положение предмета

После выбора candidate:

• BACK мебели лежит на его surface segment;
• локальная +y предмета направлена по нормали в допустимую сторону;
• центр равен точке поверхности плюс normal * depth/2;
• координата вдоль поверхности по-прежнему квантуется действующим grid step;
• квантизация ограничивается конечным интервалом candidate и не переносит предмет на соседний атом с другой толщиной;
• angle следует направлению поверхности с прежней точностью хранения;
• результат проходит существующий canvas clamp только после физического snap.

Для стены толщиной 20 см и мебели глубиной 10 см BACK лежит в 10 см от оси на внутренней грани, а центр — ещё в 5 см внутрь комнаты. Ни одна часть глубины предмета не лежит между двумя физическими поверхностями стены.

4. Радиус магнита

Действующее значение FURN_WALL_CELLS не меняется. Расстояние для eligibility и поля dist считается от точки намерения до surface segment. Поэтому шесть клеток соответствуют тем же физическим 30 см от видимой поверхности и для нулевой, и для толстой стены.

За пределами радиуса resolver возвращает отсутствие магнита и сохраняет действующее grid-bound размещение. Shift по-прежнему не строит и не выбирает wall candidate вообще.

5. Preview, commit и move

Первичное размещение сохраняет контракт #359:

• hover preview и clean click вызывают один resolveFurniturePlacement с одной и той же raw/intent точкой и одним снимком wall candidates;
• клик сохраняет точные x/y/w/h/angle, которые показывал последний валидный preview;
• pointerleave, pointercancel, pinch и смена инструмента не создают объект.

Перемещение существующей мебели использует тот же low-level selection/snap helper, а не собственную центролинейную ветку. В resolver передаётся исходный центр текущего drag и сторона исходного предмета для tie-break. После отпускания сохраняются те же координаты, которые видны во время drag.

Mouse, pen и clean touch tap получают одинаковую конечную геометрию. Hover остаётся необязательным на coarse pointer; новых touch-жестов нет.

6. Кэш и производительность

Wall candidates зависят от пространства, wall/room geometry, wall thickness, open/virtual profile и масштаба физических единиц, но не от каждого движения указателя. Runtime кэширует либо переиспользует готовый список на действующий geometry/config epoch и сбрасывает его при изменении любой из этих зависимостей.

Pointermove не должен заново строить полный roomWallProfile для всех комнат. Pure snap по уже готовому списку остаётся линейным по числу кандидатов, как нынешний поиск по _furnWalls. Новых initial-view imports нет: код остаётся в существующем lazy editor graph.

Данные и совместимость

• Persisted schema и формат decor.kind = "furniture" не меняются.
• x, y, w, h, angle, flip_h, flip_v, цвет, opacity и width_cm сохраняют текущий смысл.
• Уже сохранённая мебель не перемещается при load, render, Optimize, export или import. Новый алгоритм действует только во время нового placement/drag.
• Успешная операция сохраняет обычный config write и Undo/Redo contract Редактора подложки.
• Пространство без физической толщины получает прежний центролинейный результат.
• Backend и версия config не меняются; миграции нет.

Touch, клавиатура и доступность

• Touch editor остаётся best effort по docs/TOUCH-SUPPORT.md, но safety floor обязателен: clean tap создаёт не более одного предмета в той же физической позиции, что и pure resolver; pinch, второй pointer и pointercancel ничего не сохраняют.
• Shift на desktop сохраняет действующий смысл «временно отключить магнит».
• Клавиатурных focus targets, ARIA-строк и диалогов не добавляется.
• View и kiosk не получают новых интеракций; уже сохранённая мебель рендерится без изменений.

Ошибки и крайние случаи

Случай	Ожидаемое поведение
внешняя стена 20 см, мебель 10 см, pointer внутри	BACK на внутренней поверхности, тело внутри комнаты
тот же pointer попал точно на ось после grid snap	используется исходная unsnapped сторона, не winding ребра
pointer чуть снаружи внешней стены	магнит всё равно ставит предмет внутрь; Shift оставляет снаружи свободно
общая стена, pointer с каждой стороны	предмет оказывается в соответствующей комнате
drag попал точно на ось общей стены	сохраняется сторона предмета до drag
новое размещение точно на оси общей стены	устойчивый результат, одинаковый при перестановке rooms/edges
локальный переход 10 → 20 см	каждая проекция использует толщину своего атома
нулевая/виртуальная стена	поверхность совпадает с осью, прежнее положение
независимая перегородка/колонна	привязка к ближайшей уже физической грани без двойного offset
вне шести клеток от поверхности	магнита нет
Shift	магнита нет независимо от близости стены
malformed/нулевой segment	кандидат пропускается, finite-результат остальных сохраняется
угол с двумя равноудалёнными стенами	стабильный tie-break, без зависимости от порядка массива

Acceptance criteria и доказательства

AC1. Толстая внешняя стена использует внутреннюю поверхность

Unit fixture с комнатой, стеной 20 см и мебелью глубиной 10 см проверяет BACK, центр, angle и отсутствие пересечения глубины с телом стены для pointer внутри, на оси и чуть снаружи. Mutation, возвращающая halfDepth = 0, обязана сделать этот тест красным.

AC2. Общая стена сохраняет намеренную сторону

Unit проверяет обе стороны общей стены, точное попадание на ось при новом placement и сохранение прежней стороны при drag. Перестановка комнат, разворот ребра и изменение winding дают эквивалентный результат. Mutation, возвращающая fallback к левой нормали, обязана краснить witness.

AC3. Используется локальная атомарная толщина

Unit fixture с коллинеарными участками 10 и 20 см проверяет разные surface offset в соответствующих проекциях и отсутствие переноса после along-grid quantization. Mutation с whole-edge/default thickness обязана краснить witness.

AC4. Радиус считается от поверхности

Unit проверяет порог ровно вокруг FURN_WALL_CELLS: толстая и нулевая стены срабатывают на одинаковом физическом расстоянии от видимой поверхности и не срабатывают сразу за порогом. Mutation с distance-to-axis обязана краснить witness.

AC5. Preview, commit и move используют один контракт

Browser smoke на production bundle размещает и затем двигает мебель у толстой внешней и общей стены. Он сравнивает preview transform с сохранёнными x/y/angle, проверяет отсутствие скачка, устойчивую сторону и Shift bypass. Отрицательная подмена одного из путей на legacy centrelines делает smoke красным и регистрируется в scripts/mutation-gate.mjs.

AC6. Нулевые стены и независимые тела не регрессировали

Unit сохраняет прежние ожидаемые координаты для halfDepth = 0, partitions и column faces, доказывает отсутствие двойного offset и finite fallback для битого сегмента.

AC7. Touch safety и данные сохранены

Существующий furniture browser smoke остаётся зелёным для clean touch tap, pinch/second-pointer/pointercancel, Undo/Redo и одного config write. Contract test подтверждает отсутствие schema/migration changes и отсутствие переписи уже сохранённой мебели при load/render.

AC8. Видимый результат защищён

Canonical furniture-placement visual fixture показывает мебель у стены с ненулевой толщиной; BACK совпадает с внутренней поверхностью в light и dark темах либо одна тема используется как пиксельный witness, а вторая проверяется browser geometry assertions. Принятие golden выполняется только через Linux CI перед бетой по действующему процессу.

AC9. Производительность и общие гейты

Unit/code review подтверждает, что wall candidates строятся не чаще одного раза на geometry/config epoch, pointermove использует готовый массив и initial-view graph не растёт новым импортом. Обязательны typecheck, unit и build; перед бетой — выбранные smoke_furniture, golden, docs screenshots, performance и полный exact-SHA Validate. Для src/** обновляется canonical docs source fingerprint. Backend pytest и model-invariants неприменимы, если реализация не меняет Python или сохранённую геометрию стен.

AC10. Выбор стены в углу детерминирован

Unit fixture с двумя неколлинеарными поверхностями одного угла проверяет три ветки выбора: при разных расстояниях выигрывает физически ближайшая поверхность; при равном расстоянии сторона точки намерения учитывается раньше стабильного tie-break; при полном равенстве перестановка входного массива не меняет выбранную поверхность и конечные x/y/angle. Mutation, возвращающая прежний выбор первого минимума из массива либо меняющая местами intent-критерий и стабильный tie-break, обязана сделать соответствующий witness красным.

План тестирования

• заменить центролинейные expectations секции wall magnet в test/furniture.test.mjs typed wall-face fixtures с 0/10/20 см;
• добавить pure tests внешней/общей стены, intent point, exact-axis tie, permutation/winding, local thickness, threshold и independent faces;
• добавить отдельный AC10 unit для двух неколлинеарных стен в углу: ближайшая поверхность, приоритет стороны намерения и инвариантность к порядку массива при точном равенстве;
• расширить demo/smoke_furniture.mjs production-bundle сценарием preview → commit → drag у толстой стены и touch safety;
• зарегистрировать дорогие отрицательные варианты в scripts/mutation-gate.mjs, включая legacy centreline и произвольную left normal;
• обновить либо добавить canonical furniture golden, который визуально видит ненулевую толщину;
• выполнить в реализации typecheck, unit, build и целевые witnesses; полный golden/smoke/performance/HA gate — перед следующей бетой.

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

• src/wall-thickness.ts либо небольшой pure-модуль рядом — построение атомарных room-facing surface candidates на существующем wall profile;
• src/furniture.ts — typed candidate input, distance-to-surface, выбор стороны и общий pure snap;
• src/houseplan-editor-runtime.ts — кэш candidates, передача raw intent point и прежней стороны в placement/move;
• test/furniture.test.mjs, при необходимости отдельный wall-surface unit;
• demo/smoke_furniture.mjs, scripts/mutation-gate.mjs, golden fixture;
• docs/FURNITURE.md, RU/EN changelog, docs screenshots provenance.

Риски и rollback

• Главный риск — неверно определить внешнюю/общую сторону на частично общей или разнотолщинной стене. Его закрывают атомарные candidates, permutation fixtures и запрет fallback на winding.
• Второй риск — preview и commit получают разные raw точки. Его закрывает один placement resolver и browser-сравнение точных координат.
• Третий риск — пересчитывать wall profile на каждом pointermove. Его закрывает epoch cache и call-count/code-review evidence.
• Четвёртый риск — дважды сместить уже физическую грань partition/column. Его закрывает отдельный owner kind и unit regression.
• Rollback реализации — revert frontend/tests/docs/bundle. Data rollback и миграция не нужны: сохранённый формат не меняется.

Release-артефакты

• User-visible implementation commit обновляет docs/CHANGELOG.md и docs/CHANGELOG.ru.md со ссылкой на #445.
• docs/FURNITURE.md заменяет обещание «BACK на wall» точным определением: BACK на room-facing физической поверхности, сторона — intent point, Shift отключает магнит.
• Любой src/** diff требует canonical Docs screenshots capture и приёмки fingerprint.
• Видимый regression fixture/golden принимается только через Linux CI. Если существующий furniture preview baseline достаточно ясно показывает стену, обновляется он; иначе добавляется один узкий сценарий без разрастания матрицы.
• Release notes отдельно называют исправление только если оно входит в число четырёх значимых bullet; иначе оно остаётся в подробном changelog и общем «Мелкие исправления и улучшения».

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

• Default Q1: внешняя стена всегда выбирает внутреннюю поверхность; общая — сторону исходного указателя; exact-axis drag сохраняет прежнюю сторону, а новое placement использует детерминированный room tie-break.
• Default Q2: радиус считается от физической поверхности.
• Preview, placement и move используют один контракт.
• На участке переменной толщины используется локальная атомарная толщина.
• Нулевые стены и физические грани независимых тел сохраняют прежнее поведение.
• Проёмы не участвуют в collision model этой задачи.
• Shift, persisted schema, i18n и уже сохранённая мебель не меняются.