houseplan-card/legacy/specs/277-safe-resize.md

Issue #277 — безопасный Resize без изменения топологии

• Issue: https://github.com/Matysh/houseplan-card/issues/277
• Статус: первая редакция для ревью; канонический статус задаётся метками issue
• Тип / приоритет: bug / P1
• Оценка: пользовательская ценность 10/10; ценность для разработки 10/10; сложность 9/10; риск 10/10
• Область: Plan Resize, room polygons, shared boundaries, thickness/openings, live preview, commit/Undo, geometry preflight, i18n и визуальные тесты
• Модель данных: schema не меняется; набор room segments остаётся неизменным
• Связано: #34, #199, #233, #234, #253, #264, #276, #278, docs/RESIZE.md, docs/WALL-THICKNESS.md, docs/TOUCH-SUPPORT.md

1. Сценарий и персона

Домашний администратор хочет немного сдвинуть одну стену готовой комнаты, не перерисовывая план. Текущий Resize разрешает диагональные рёбра, частичные shared spans, вставляет вершины соседу и отдельно масштабирует комнату угловой рамкой. На реальном плане эти широкие преобразования рассинхронизировали room polygons, thickness records, independent partitions и hosted openings; один результат перестал показывать всю кладку.

После исправления Resize делает только доказуемо безопасную операцию: переносит одну горизонтальную или вертикальную стену параллельно себе, меняет длину её двух примыкающих стен без изменения толщины и никогда не меняет число сегментов. Если гарантии перестают выполняться, live preview физически упирается в первую границу безопасного диапазона либо ручка остаётся disabled с понятной причиной.

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

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

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

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

Зафиксированы 2026-08-24:

1. Угловой scale-frame удаляется. Resize больше не масштабирует комнату целиком.
2. Двигаются только строго горизонтальные и вертикальные room walls.
3. Запрещённая стена сохраняет видимый disabled handle; hover/click/tap даёт короткую человекопонятную причину.
4. Необщая стена меняет положение; две примыкающие перпендикулярные стены удлиняются/укорачиваются без изменения толщины и числа segments.
5. Shared wall в начале жеста обязана совпадать endpoint-to-endpoint у двух комнат. Неправильная форма комнаты сама по себе допустима.
6. Shared drag продолжается только пока сохраняется исходное exact endpoint-to-endpoint соответствие. Перед углом/ступенькой, где следующий шаг изменил бы длину moving segment или topology, preview упирается и не идёт дальше.
7. За один жест меняются максимум две комнаты. Третья комната не вовлекается в каскад: она становится stop/disabled obstacle.
8. Если sliding endpoint дошёл до opening на примыкающей перпендикулярной стене, движущаяся кладка упирается в ближний косяк и не перекрывает проём.
9. Opening на самой moving wall продолжает ехать с ней, если после операции полностью помещается.
10. Любой нарушенный инвариант отменяет жест целиком; частичной записи нет.

Открытых продуктовых вопросов нет.

3. Термины и геометрический допуск

• Moving edge — выбранная сторона polygon комнаты между двумя соседними topology vertices.
• Side edges — предыдущая и следующая стороны того же polygon.
• Exact shared pair — ровно два moving edges разных rooms с совпадающими endpoints независимо от направления.
• Topology — количество, циклический порядок и identity correspondence vertices/segments каждой затронутой комнаты.
• Safe range — замкнутый диапазон нормального смещения, в котором все проверки §5–§7 выполняются.

«Строго horizontal/vertical» допускает только численный шум хранения меньше canonical coordinate epsilon. Это не пользовательский angle snap: заметно наклонённая стена не округляется и остаётся disabled. Все сравнения выполняются в production render coordinates; шаг сетки определяет итоговую позицию, но не геометрический epsilon.

Если математическая граница safe range лежит между grid nodes, commit получает ближайший grid node внутри диапазона. Если следующий node схлопнул бы side edge в ноль, стена визуально доходит до угла, но persisted candidate остаётся на последней положительной длине не меньше действующего minimum segment tolerance. Нулевая сторона и удаление vertex запрещены.

4. Eligibility и disabled reasons

Для каждого room edge pure resolver возвращает enabled + plan либо один стабильный reason. Порядок причин детерминирован:

1. diagonal — moving edge не horizontal/vertical;
2. side-angle — одна из side edges не перпендикулярна moving edge;
3. duplicate-physical-wall — ось перекрывает partition/draft/column; после канонизации #276 точное redundant совпадение исчезает;
4. partial-shared — сосед касается только части moving edge;
5. unequal-shared — endpoints/длины пары различаются;
6. multiple-rooms — moving edge либо swept side geometry вовлекла бы третью комнату;
7. thickness-conflict — effective thickness пары/side continuation неоднозначна либо не может быть перенесена lossless;
8. opening-conflict — opening на moving edge уже не помещается даже при нулевом смещении либо host неоднозначен;
9. invalid-geometry — исходный polygon/physical candidate не проходит обязательные structural проверки.

Enabled non-shared edge принадлежит ровно одной комнате. Enabled shared edge принадлежит ровно двум комнатам и совпадает endpoint-to-endpoint. У обеих комнат side edges в каждом конце лежат на одной перпендикулярной оси и имеют совместимую физическую толщину; короткая ступенька или T-contact не переносится каскадом, а ограничивает safe range.

Disabled handle:

• рисуется тем же размером и hit area, но приглушённо;
• имеет aria-disabled="true", cursor not-allowed и локализованный label;
• hover/focus показывает tooltip/hint, click/tap — тот же текст без начала drag;
• не захватывает pointer и не создаёт Undo/save;
• reason не содержит room ids, координат или исключений.

5. Преобразование non-shared wall

1. Оба endpoint moving edge получают один snapped normal displacement.
2. Два существующих side edges сохраняют свои противоположные endpoints и меняют только длину. Их оси не меняются.
3. Ни vertex, ни segment не добавляется, не удаляется и не переставляется.
4. Комната сохраняет orientation, positive area, simple polygon и действующий minimum clearance; foreign rooms/islands/physical extras не пересекаются.
5. Thickness profile каждого из трёх затронутых edges переносится геометрически и lossless. Не затронутые wall entries byte-equivalent.
6. Ordinary openings moving edge смещаются тем же вектором; openings side edges остаются на месте и определяют stop §7.
7. Partitions, room drafts, wall columns, hosted openings и остальные комнаты не меняются.

Общее число room segments всего пространства до/после одинаково; геометрию меняет ровно одна room.

6. Преобразование shared wall

1. Одна geometric moving edge представлена двумя противоположно направленными polygon edges ровно двух rooms. Обе копии смещаются одним вектором.
2. Четыре side edges меняют длину вдоль своих исходных осей. Никаких новых vertices, shiftSharedSpans()-вставок или simplifyPoly()-удалений нет.
3. В каждый момент preview endpoints обеих копий совпадают. Если следующий delta потребовал бы partial span, смену длины, схлопывание side edge, T-branch или третью room, delta clamp'ится к последнему safe положению.
4. Площади меняются только у этих двух rooms: одна растёт, другая уменьшается. Другие room polygons byte-equivalent.
5. Shared thickness/open spans преобразуются один раз. Разные destinations, conflicting cm либо ambiguous ownership fail closed.
6. Openings moving shared wall смещаются один раз и остаются на той же shared boundary. Side-wall openings остаются на месте и ограничивают range.

Если safe range после grid snap содержит только исходную позицию, resolver проверяет один grid step в обе стороны тем же exact validator. Когда оба направления запрещены, handle остаётся visible/focusable, но disabled с приоритетной причиной; pointer capture, preview, history и write не создаются. Это уточнение принято в #281 и заменяет прежний enabled no-op контракт.

7. Stops и live clamp

Один pure range resolver заранее собирает верхнюю/нижнюю границы normal delta. pointermove только clamp'ит snapped delta и проверяет exact candidate.

Обязательные ограничения:

1. minimum room clearance/positive area/simple orientation;
2. ближайший topology corner, после которого side edge стал бы нулевым либо moving edge перестал endpoint-to-endpoint совпадать;
3. foreign/third room, island, partition/draft/column physical body;
4. opening на moving edge должен полностью помещаться после переноса;
5. opening на каждом perpendicular side edge: outer face движущейся стены не входит в clear slot opening. Центр moving wall останавливается у ближнего jamb с учётом половины собственной физической толщины;
6. никакое opening не меняет host, длину, angle или unrelated compatibility fields;
7. canonical wall bodies/floor footprint точного preview не возвращают structural failure.

При нескольких stops выбирается ближайший к исходному положению. Clamp одинаков для обеих сторон drag и не зависит от частоты/порядка pointer events. Pinch, pan, pointercancel и lostpointercapture отменяют drag, как прежде.

8. Preview, commit и Undo

Preview строится каждый раз из immutable pre-drag snapshot и содержит точный candidate целого пространства: rooms, openings, walls/open spans и неизменные extras. Render не собирает candidate повторно другим путём.

Перед pointerup commit выполняет единый transaction check:

• touched room ids равны plan и их не больше двух;
• topology signature каждой room не изменилась;
• unrelated rooms/extras/openings byte-equivalent;
• wall/open-span preservation и destinations согласованы;
• exact production geometry preflight успешен;
• повторное применение результата является no-op.

Failure отбрасывает overlay, показывает локализованное безопасное сообщение и делает 0 config writes/Undo entries. Success выполняет ровно один save и одну именованную Undo-команду. Undo/Redo восстанавливают/повторяют rooms, openings, walls и open spans целиком.

9. Удаляемое старое поведение

• corner scale frame и четыре corner handles;
• applyRoomScale/clampRoomScale из production interaction path;
• drag диагональных edges;
• partial shared span movement;
• вставка vertices соседней комнате и commit-time simplifyPoly;
• вовлечение цепочки из трёх и более rooms.

Pure helpers могут временно оставаться для backward test history, но не должны быть reachable из bundle. Мёртвый production code удаляется в этой задаче.

10. В скоупе

• safe eligibility/range/candidate pure geometry;
• Resize controller, handles, tooltip/reason and live measures;
• fixed-topology rekey thickness/open spans and ordinary openings;
• exact commit preflight and zero-write failure;
• removal scale-frame/diagonal/partial-shared behavior;
• unit, production-bundle pointer smoke, mutation, benchmark, targeted golden;
• RU/EN i18n, user/canvas/architecture/testing docs и changelogs.

11. Не входит

• исправление/канонизация coincident partition (#276);
• generic wall union fail-safe для уже сохранённого bad plan (#278);
• произвольный vertex editor, room scale или diagonal resize replacement;
• изменение толщины, типа стены, room split/merge;
• автопочинка исходно invalid polygon;
• перемещение partitions/drafts/columns;
• touch parity редактора сверх safety floor.

12. Архитектура

1. Pure geometry/eligibility остаётся в src/resize.ts либо меньших pure модулях. Controller integration согласуется с #264 и не создаёт второй topology model.
2. Один typed ResizePlan содержит room ids, edge indices, fixed topology signatures, affected wall/opening mapping, safe delta interval и reason.
3. Один applySafeResize(snapshot, plan, delta) используется preview и commit; commit не вычисляет другую геометрию.
4. Thickness/open-span mapping использует canonical interval helpers #253, не compatibility keys как identity.
5. Structural preflight переиспользует production preparation #199; локальный simplified polygon-only check не считается достаточным.
6. No-op/failed drag не меняет _serverCfg, cfg epoch, history, layout или queued saves. Mid-drag previous save по-прежнему читает committed snapshot.

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

Риск	Мера
Сужение функции неожиданно делает привычную стену недоступной	Visible disabled handle и точная причина; positive/negative eligibility matrix AC1–AC4.
Corner clamp схлопывает side edge либо меняет число segments	Last safe grid coordinate, fixed topology signature и mutant topology-simplify.
Shared drag вовлекает третью комнату через T/partial contact	План содержит максимум два room ids; swept third-room stop и dedicated mutant.
Opening stop рассчитан по оси и кладка всё равно перекрывает проём	Physical half-thickness + jamb calculation, все типы openings и targeted golden AC6.
Preview проходит, а commit пересчитывает другую геометрию	Один immutable snapshot/applySafeResize для preview и commit, AC8/AC9.
Thickness/open spans расходятся при переносе	Canonical interval mapping #253, preservation assertions и реальная fixture AC17.
Параллельная реализация #264 создаёт второй controller boundary	#277 не зависит от #264 и реализуется на текущей границе; #264 не начинается параллельно, после #277 обязан rebase и refactor-only parity.
#276/#278 меняют соседние geometry helpers во время работы	Порядок merge #276 → #277 → #278; перед код-ревью ветка содержит актуальный dev, конфликты разрешаются автором с повтором targeted fixtures.
Strict checks ухудшают pointer latency	Range вычисляется до drag/мемоизируется, §13 budgets и call-count.
Rollback возвращает опасный старый Resize	Полный revert допустим технически, release note предупреждает не редактировать geometry до обновления.

13. Производительность

Eligibility всех handles мемоизируется по exact geometry fingerprint и не пересчитывает boolean geometry на каждый render. Pointermove p95 на large-house fixture — не более 16 ms и не более 20% хуже current edge-drag same-run baseline. Pointerup preflight может быть дороже, но не более 75 ms p95 на fixture; это не render/state path. Cache ограничен активным пространством и очищается при cfg epoch/tool exit.

14. Touch и accessibility

Plan editor остаётся desktop-first. Все handles сохраняют существующую finger-sized hit area. Disabled reason доступен focus и tap, не только hover. Pointer capture начинается только для enabled handle. pointercancel, lostpointercapture, pinch и app switch не коммитят. View и kiosk не получают handles и остаются полностью поддержанными.

15. Критерии приёмки

AC	Критерий	Доказательство
AC1	Только numerically axis-aligned edge eligible; diagonal и non-perpendicular side edges disabled с точным RU/EN reason.	Unit + UI smoke.
AC2	Non-shared drag меняет одну room и длины ровно двух side edges; topology/count/thickness неизменны.	Parameterized unit + invariants.
AC3	Exact shared drag меняет ровно две rooms и сохраняет endpoint-to-endpoint на каждом preview delta.	Unit matrix.
AC4	Partial/unequal/multiple-room/coincident-extra cases disabled; никакие vertices/segments не создаются.	Negative unit + mutation.
AC5	Irregular shared rooms двигаются до первого topology corner; следующий grid step clamp'ится и не схлопывает side edge.	Focused unit + production pointer smoke.
AC6	Side-wall door/window/gate ограничивает delta по физическому jamb; moving body не перекрывает slot с обеих сторон.	Geometry unit + targeted golden.
AC7	Opening на moving edge едет один раз и сохраняет fit/host fields; conflict даёт no-op.	Unit + browser smoke.
AC8	Preview и commit используют один candidate; pointercancel/lost capture/Esc делают 0 writes, pointerup success — 1 write/Undo.	Production-bundle smoke.
AC9	Exact commit preflight ловит wall/floor failure, third-room mutation, thickness loss и topology change до save.	Injectable unit + mutation gate.
AC10	Undo/Redo/reload сохраняют тот же plan, thickness/open spans/openings; repeated save canonical/no-op.	Browser smoke + round-trip unit.
AC11	Corner frame отсутствует, old scale/diagonal/partial-shared handlers unreachable; View/other tools pixel-equivalent.	Source guard + golden.
AC12	Disabled handle доступен mouse/keyboard/touch, reason локализован и pointer не захватывается.	a11y/i18n unit + browser smoke.
AC13	Performance budgets §13 и bounded cache выполняются.	Targeted benchmark/call-count.
AC14	Мутации eligibility bypass, third-room cascade, topology simplify, opening-stop bypass и commit-preflight bypass пойманы 1/1.	Mutation gate.
AC15	Typecheck, unit, build, targeted smokes зелёные; tracked bundles byte-identical.	Fast gates.
AC16	RU/EN changelog и RESIZE/user/canvas/architecture/testing docs описывают суженный контракт.	Docs gate + review.
AC17	Анонимизированная before-fixture из исходного пользовательского плана воспроизводит старое расхождение через production pointer handlers; новый Resize либо безопасно завершает тот же допустимый жест, либо предсказуемо clamp/disabled, сохраняет все walls/extras/openings и не даёт global wall-null.	Fixture provenance test + production-bundle smoke + model invariants.

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

• переписать test/resize.test.mjs под eligibility/safe-range/fixed topology;
• synthetic fixtures: non-shared rectangle/L-room, exact shared regular/irregular, corner clamp, third room, partition duplicate, all opening types;
• test/fixtures/resize-safe-regression.json: минимизированная и анонимизированная из пары реальных экспортов до/после (названия, ids, markers/layout удалены), с provenance-комментарием #277; smoke исполняет исходную последовательность pointer gestures, а не подставляет готовый after;
• demo/smoke_safe_resize.mjs: реальные pointerdown/move/up, disabled reasons, preview/commit/Undo/Redo/reload и zero-write failures;
• targeted golden light/dark: enabled/disabled handles, corner/opening clamp и final masonry;
• mutation ids из AC14;
• pointer/preflight benchmark на large-house fixture.

Полные golden/smoke/performance и Linux HA harness выполняются перед бетой.

17. Release-артефакты и rollback

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

• docs/CHANGELOG.md, docs/CHANGELOG.ru.md со ссылкой #277;
• docs/RESIZE.md как source of truth;
• docs/USER-GUIDE.md, docs/USER-GUIDE.ru.md, docs/CANVAS.md;
• docs/ARCHITECTURE.md, docs/TESTING.md, docs/STATUS.md;
• RU/EN i18n, tests/smoke/mutations/benchmark, reviewed golden candidates;
• tracked bundles и docs screenshot fingerprint при затронутом source.

Rollback — revert implementation commit. Schema/persisted migration нет. Планы, безопасно сохранённые новым Resize, совместимы со старой версией. После rollback вернётся широкий нестабильный UI, поэтому release rollback должен быть полным и сопровождаться предупреждением не использовать Resize до обновления.

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

1. Причины disabled имеют стабильный приоритет §4, но внутренние enum names не API.
2. Tooltip использует общий доступный hint primitive; отдельный modal не нужен.
3. Последняя безопасная grid coordinate перед нулевой side edge считается пользовательским «упором в угол» и не нарушает запрет изменения topology.
4. Thickness compatibility означает одинаковый физический профиль на совпадающих continuations, а не обязательно одно число для всех четырёх side edges; конфликт на одном атомарном участке запрещает gesture.
5. #276 реализуется раньше #277; exact redundant partition после Optimize исчезает, а оставшийся неоднозначный extra продолжает блокировать handle.
6. Реальная fixture обязательна, но публикуется только после минимизации и удаления пользовательских строк; исходные private exports в git не попадают.