houseplan-card/legacy/specs/172-zero-divider-taper.md

Issue #172 — нулевой Split-разделитель не получает ложную толщину

• Issue: https://github.com/Matysh/houseplan-card/issues/172
• Редакция: первая редакция для независимого ревью; статус определяется только метками issue
• Тип / приоритет: bug / P2
• Оценка: пользовательская ценность 8/10; сложность 6/10; риск 7/10
• Область: редактор Плана, каноническая геометрия стен, View/static, hidden Iso, clean floor, Glow и солнце
• Модель данных: без изменений и миграции
• Связано: #123, #150, docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md, docs/TOUCH-SUPPORT.md

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

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

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

Задача поддерживает J4 и J6 из docs/SCOPE.md: редактор должен сохранять правдивую геометрию, а штатное разделение комнаты не должно создавать стену, которую пользователь не задавал. Общая физическая модель также сохраняет согласованность J1/J2/J3 между Plan, View и световыми эффектами.

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

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

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

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

Дефект воспроизведён на origin/dev SHA a05aa5d с production-параметрами pitch = 1/240, coordScale = 1000, cell_cm = 5, GRID_PITCH = 1000/240.

Fixture — Г-образный полигон [100,100]–[900,100]–[900,800]–[600,800]–[600,400]–[100,400], наружные стены 15 см, Split от [600,400] к [900,402.5] или [900,405].

Слой данных корректен:

• оба room-owned интервала общей границы классифицируются как shared;
• их эффективная толщина равна 0;
• положительной WallEntry для разделителя нет;
• рендер не должен материализовать такую запись.

Ошибка возникает в insetContour() / outsetContour(). При стыке положительного offset с нулевым и небольшом отклонении от коллинеарности удалённый mitre отбрасывается по MITRE_LIMIT. Bevel-ветка сохраняет только смещённую точку толстой грани и теряет исходную вершину нулевой грани. Следующий участок контура соединяет эту точку с дальним концом разделителя и создаёт taper-клин.

На красном fixture поперечное сечение ложной кладки растёт вдоль нулевого разделителя приблизительно от 0 до полной глубины стены 15 см. При точном 0° специальная коллинеарная ветка уже сохраняет ступень, поэтому дефект легко пропустить тестом только ортогональной геометрии.

Это не дубликат:

• #123 сохраняет наружный фасад при Split из вершины;
• #150 сохраняет breakpoint между коллинеарными внешними интервалами разной толщины;
• #172 убирает ложный taper вдоль нулевой внутренней общей границы.

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

Владелец принял defaults Q1–Q4 18.08.2026: https://github.com/Matysh/houseplan-card/issues/172#issuecomment-5329384353

1. Split-разделитель с cm = 0 не содержит masonry по всей длине; толстая примыкающая стена заканчивается локальным стыком без taper.
2. Инвариант применяется ко всем углам, толщинам, направлениям и winding.
3. Фактический угол Split сохраняется; snapping к нормали не добавляется.
4. Исправление едино для Plan, View/static, hidden Iso, clean floor/room fills и препятствий Glow/солнца, без миграции конфигурации.

5. Скоуп

В задачу входят:

1. переход между положительной толщиной и точным нулевым offset в вершине room wall profile;
2. обе последовательности h → 0 и 0 → h, прямой и обратный winding;
3. выпуклые и вогнутые вершины, острые, тупые, почти коллинеарные и ортогональные допустимые углы;
4. все допустимые толщины 1…100 см;
5. Split с одним или двумя endpoint на толстых стенах;
6. локальный cap/step без кладки в интерьере нулевого разделителя;
7. сохранение существующего mitre/bevel-контракта для пар h1 ↔ h2, где обе толщины положительны;
8. единая каноническая геометрия всех перечисленных поверхностей;
9. корректное отображение уже сохранённых планов без записи конфигурации;
10. unit, targeted browser smoke, visual fixture, документация и RU/EN changelog.

6. Не входит в задачу

• snapping почти перпендикулярного или почти коллинеарного Split;
• изменение допустимости, маршрута кликов, диалога или сохранения Split;
• автоматическое назначение толщины новой общей границе;
• изменение инструмента «Толщина», Перегородка или открытых контуров;
• переработка модели rooms, walls, partitions, open_spans или wall_columns;
• новые настройки cap/join, пользовательские переключатели или i18n-тексты;
• изменение MITRE_LIMIT для стыков двух положительных толщин;
• миграция, schema version, backend или импорт/экспорт;
• публикация изометрии как публичной функции.

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

7.1. Нулевой разделитель

Пусть D — общая граница двух комнат после Split, а её эффективная толщина равна 0.

• Внутренняя часть D, за вычетом локальных областей примыкания существующих толстых стен, не пересекается с канонической masonry geometry.
• Толщина вдоль D не интерполируется и не образует taper.
• В точке перехода h ↔ 0 сохраняется вершина нулевой грани и формируется локальный cap/step толстой стены.
• Локальная область примыкания ограничена физической half-depth примыкающей стены и геометрическим epsilon; она не может расти пропорционально длине D.
• Правило симметрично относительно порядка комнат, направления границы и winding.

7.2. Существующие стены

• Толстая наружная или общая стена сохраняет заданную полную глубину до точки примыкания.
• Наружный фасад до и после Split сохраняет контракт #123.
• Две положительные соседние толщины продолжают использовать действующие mitre/bevel и MITRE_LIMIT; исправление нулевого перехода не превращает их в принудительные плоские caps.
• Строго коллинеарный переход сохраняет существующую точную ступень.
• Проёмы и независимые физические тела не меняют свою ассоциацию или форму.

7.3. Геометрия Split и данные

• splitRoomPath() сохраняет фактически выбранные endpoints и промежуточные точки; угол не округляется к нормали.
• Большая и новая комнаты сохраняются по действующему контракту.
• Нулевой разделитель не получает WallEntry и не материализуется при чтении.
• Рендер не мутирует rooms, walls и другие persisted-поля.
• Уже сохранённая конфигурация исправляется вычисляемо сразу после обновления.

7.4. Все потребители

Один результат wall-body geometry используется в:

• Plan editor;
• View, kiosk и houseplan-space-card;
• hidden Iso/floor footprint;
• paper, room fills и clean-floor contours;
• физических препятствиях Glow и солнечных лучей.

Renderer-specific SVG mask, отдельная геометрия только для Plan или подавление штриховки без исправления физического тела не выполняют контракт.

8. Архитектурные ограничения реализации

1. Исправление живёт в общей variable-offset логике src/wall-thickness.ts, а не в обработчике кликов Split.
2. Для стыка, где ровно один из соседних offsets положителен, контур обязан сохранить как смещённую точку толстой грани, так и исходную вершину нулевой грани в детерминированном порядке для inset и outset.
3. Обе половины кольца вместе формируют локальный cap; ни одна не соединяет offset-точку с дальним узлом нулевой грани.
4. Пары двух положительных offsets проходят прежний bounded-mitre/bevel путь.
5. Результат остаётся валидным для boolean union/difference/intersection и не полагается на порядок полигонов.
6. Canonical wall geometry остаётся единственным источником для drawing, clean-floor и light/sun occlusion.
7. Новых persisted-полей, фоновых writes и renderer-specific caches нет.

Предполагаемые файлы:

• src/wall-thickness.ts;
• test/wall-thickness.test.mjs;
• новый demo/smoke_zero_divider_taper.mjs либо эквивалентное расширение узкого Split-smoke;
• demo/golden/matrix.mjs, fixture/harness и test/golden-matrix.test.mjs, если новая visual-сцена оформляется отдельно;
• docs/WALL-THICKNESS.md, при необходимости docs/ARCHITECTURE.md;
• docs/CHANGELOG.md, docs/CHANGELOG.ru.md;
• три синхронные поставляемые копии bundle.

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

Форматы RoomCfg и WallEntry не меняются. Новых ключей, aliases и compatibility-полей нет.

• legacy midpoint-only keys продолжают читаться;
• lossless a/b endpoints сохраняют текущий смысл;
• чтение и рендер не записывают конфигурацию;
• прямая и обратная миграции не нужны;
• откат на предыдущую версию не требует восстановления данных, но возвращает визуальный дефект.

Это соответствует docs/CONFIG-COMPATIBILITY.md: меняется только вычисляемая геометрия существующих данных.

10. UX, i18n, accessibility и touch

Новых controls, текстов, focus/keyboard semantics или ARIA нет. Новые RU/EN i18n-ключи не требуются.

Split остаётся desktop-first. Touch editor: best effort / intentionally degraded, но одна и та же сохранённая геометрия не может зависеть от типа указателя. View, kiosk и static являются блокирующими поверхностями и обязаны совпадать с desktop Plan.

Темы, prefers-reduced-motion, цвет и opacity стен не меняются.

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

• AC1 (unit): production-scale fixture из §3 с углами 0,477° и 0,955° сохраняет cm = 0 на обоих room-owned интервалах разделителя, а его внутренняя часть не пересекается с masonry geometry. Тест красный на исходном dev из-за taper-клина.
• AC2 (unit): матрица h = 1, 15, 100 см, h → 0 и 0 → h, углы по обе стороны от точной линии, оба направления и оба winding не создаёт кладку вдоль нулевой грани; размер локального cap ограничен half-depth и epsilon, а не длиной грани.
• AC3 (unit): точный коллинеарный и ортогональный переходы остаются корректными; пары 1 ↔ 15, 15 ↔ 100 и равные положительные offsets сохраняют действующий mitre/bevel-контракт.
• AC4 (unit): наружная геометрия Г-образной комнаты до/после Split сохраняется, а clean-floor union равен room union минус каноническая кладка; нулевой разделитель не удаляет треугольник пола.
• AC5 (unit): splitRoomPath() сохраняет фактический угол fixture без snap, render helpers не меняют сериализованные rooms/walls, миграция и новые config keys отсутствуют.
• AC6 (smoke): targeted browser-smoke выполняет реальный Split из вогнутого угла с отклонением около 1°, подтверждает нулевые persisted интервалы и отсутствие taper в SVG Plan.
• AC7 (smoke): тот же smoke доказывает побайтовое/геометрическое совпадение канонической wall-body path в Plan, View/kiosk, static и hidden Iso и совпадение masonry geometry световых препятствий; конфигурация после рендера не меняется.
• AC8 (golden): детерминированная visual-сцена Г-образного Split явно показывает нулевой разделитель без клина и без изменения фасада. Baseline принимается только через golden:accept -- --reviewed по полному Linux CI artifact на предрелизном этапе.
• AC9 (unit + smoke): существующие регрессии corner Split, wall junctions, wall thickness и opening tunnels остаются зелёными; проёмы и независимые тела не меняются.
• AC10 (ревью кода): исправление находится в общей variable-offset геометрии; renderer-specific masks/branches и изменения persisted schema отсутствуют.
• AC11 (ревью кода): новых DOM-узлов, событий, таймеров, сетевых запросов, HA services и privacy/security surfaces нет.

12. План автотестов и гейтов

Unit

В test/wall-thickness.test.mjs добавить:

1. точный красный fixture §3 с проверкой данных и площади пересечения masonry с внутренней полосой разделителя;
2. параметрическую матрицу толщин, углов, направлений и winding;
3. negative-regression для двух положительных offsets и exact-collinear step;
4. clean-floor/exterior invariants и immutability.

Проверка должна уметь падать: временное возвращение старой bevel-ветки обязано красить как минимум AC1/AC2. Ревьюер фиксирует эту проверку в code review.

Browser smoke

node demo/smoke_zero_divider_taper.mjs (имя можно изменить при сохранении однозначной связи с #172) выполняется локально перед S7-code-review. Smoke использует show_borders: true, чтобы Plan/View/static/Iso сравнивали реально отрисованные стены.

Golden и pre-release

Новая visual-сцена добавляется в матрицу, но baseline не принимается ради зелёной ветки. Capture/diff рассматриваются на предрелизном Linux-гейте; полный golden, smoke и performance выполняются перед бетой по PROCESS.md §11.4.

Обязательный implementation loop

npm run typecheck
npm test
npm run build
node demo/smoke_zero_divider_taper.mjs

После build три bundle-копии должны совпадать побайтово. Backend/HA harness не нужен: Python и Home Assistant integration не затрагиваются.

13. Риски, performance и security

Риск	Мера
Исправление нулевого перехода меняет обычные положительные углы.	AC2/AC3 разделяют h ↔ 0 и h1 ↔ h2; положительные пары сохраняют прежний путь.
Новый cap создаёт самопересекающийся contour при вогнутом угле.	Матрица convex/concave, оба winding и boolean-validity assertions.
SVG исправлен, но floor/light продолжают видеть клин.	AC4/AC7 проверяют общий geometry object и потребителей.
Тест исключает слишком большую endpoint-зону и пропускает taper.	Endpoint allowance ограничен физической half-depth + epsilon, дополнительно проверяются несколько внутренних сечений.
Golden принимается без review.	Только полный Linux artifact и --reviewed; до этого хранится candidate/diff.

Performance-влияние практически отсутствует: число вершин variable-offset контура увеличивается максимум на одну точку в каждом переходе h ↔ 0. Асимптотика, cache keys и частота вычислений не меняются. Отдельный performance budget не нужен; общий pre-release performance smoke остаётся обязательным.

Security/privacy влияние отсутствует: нет ввода HTML/CSS, сетевых запросов, service calls, новых разрешений или данных HA.

14. Откат

Исправление откатывается одним frontend-коммитом вместе с тестами и документацией. Persisted schema не меняется, поэтому обратная миграция и cleanup не нужны. Откат возвращает ложный taper, но не повреждает сохранённые планы.

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

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

• пользовательские записи в docs/CHANGELOG.md и docs/CHANGELOG.ru.md в том же implementation-коммите (User-Visible: yes);
• обновление docs/WALL-THICKNESS.md; docs/ARCHITECTURE.md — только если уточняется общий variable-offset контракт;
• targeted unit и browser smoke;
• visual fixture/candidate и reviewed golden baseline по правилам §12;
• синхронные dist/houseplan-card.js, HA frontend и demo bundle;
• screenshots вне golden не требуются;
• backend, migration и отдельные security/performance artifacts не требуются;
• issue закрывается только после включения в опубликованную бету.

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

1. Точный нулевой offset — единственный триггер нового cap/step пути; малые положительные толщины не приравниваются к нулю.
2. Endpoint allowance в тестах вычисляется из half-depth примыкающей стены и общего geometry epsilon, а не задаётся долей длины разделителя.
3. Исправление выполняется симметрично в inset и outset; отдельная post-render маска не допускается.
4. Новая visual-сцена может переиспользовать fixture #123, если остаётся однозначно проверяемой и не скрывает L-shaped near-normal case.
5. Если во время реализации обнаружится отдельный дефект boolean-библиотеки, он оформляется новой issue; #172 не расширяется до общей замены offset engine.