# #482 — Доводка экспорта пространства в PDF - **Issue:** https://github.com/Matysh/houseplan-card/issues/482 - **Тип / приоритет:** bug + polish / P1 - **Трек:** полный; меняются геометрия размеров, PDF-примитивы, компоновка страницы, адаптивность View-диалога и golden-эталон - **Оценка:** пользовательская ценность 8/10; ценность для разработки 7/10; сложность 7/10; риск 7/10 - **Связано:** #52, #53; `docs/specs/052-view-dimensions.md`, `docs/specs/053-pdf-export.md`, `docs/PDF-EXPORT.md`, `docs/TOUCH-SUPPORT.md` ## 1. Сценарий Персона — Home admin из `docs/SCOPE.md`. Поверхность — полная карточка House Plan в режиме View на desktop либо touch-устройстве. Момент — пользователь открывает «Сохранение в PDF», выбирает состав архитектурного чертежа и сохраняет текущее пространство для печати, передачи строителю или обсуждения планировки. В исходном плане могут одновременно присутствовать внешние и внутренние стены, проёмы, перегородки, колонны, ступенчатые и вогнутые комнаты, декор, растровая подложка и заданное направление севера. ## 2. Что человек увидит до и после **До:** узкий диалог может получить горизонтальный scroll; противоположные стороны дублируют одинаковые размеры; почти совпадающие вершины иногда создают ложную диагональ; подписи прилипают к стенам; стены не похожи на стены плана; чертёж плохо заполняет лист; север показан упрощённой стрелкой; внизу печатается техническая легенда `wall · door · window`. **После:** диалог помещается от 320 CSS px, размерные цепочки остаются только у реальных осевых граней и не повторяют локальную противоположную пару, подписи расположены равномерно и не пересекают стены, физические стены имеют фон `#7f7f7f` и штриховку, полный чертёж оптимально вписан и центрирован, север обозначен векторным компасом, а технической легенды нет. ## 3. Подтверждённые причины 1. `compactRing()` удаляет коллинеарные точки до схлопывания соседних точных и почти точных дублей. В ступенчатом контуре это соединяет несмежные стороны хордой. На приложенном примере ложные `3.39 m` и `3.93 m` совпадают с диагоналями между реальными ортогональными участками; стены под углом 72° в исходном плане нет. 2. Размеры формируются для каждой пригодной стороны независимо: понятия локальной пары противоположных граней нет. 3. Внутренние подписи используют фиксированные 2 mm без учёта bbox текста и тела стены; fallback сдвигает только текст вдоль стены. Внешняя shelf также может двигаться отдельно от своей размерной линии. 4. Ориентация выбирается по сырому bbox архитектуры, до построения размеров и выносок. Дополнительно всегда резервируются приближённые 30/48 mm, после чего центрируется только архитектура. Поэтому масштаб и свободные поля не соответствуют фактической печатной сцене. 5. PDF writer умеет заливать и обводить path, но не умеет even-odd clipping для штриховки и заполненный составной vector path для нового компаса. 6. Общий двухзнаковый formatter PDF превратит `127 / 255` в `0.5`, то есть в `#808080`. Для точного `#7f7f7f` цвету нужна отдельная точность. 7. В CSS диалога padding прибавляется к `min-width`, flex-подписи не могут сжиматься, а footer запрещает перенос. ## 4. Изменяемый контракт Это ТЗ заменяет только противоречащие ему части #53: - §7.1: цвет и вид физических стен; - §7.3: правило «все четыре стороны» и размещение размеров; - §7.5: упрощённую стрелку севера и архитектурную легенду; - §8.1–8.2: выбор ориентации, масштаба и центрирование; - связанные AC4, AC6 и golden-ожидания. Остальные гарантии #53 сохраняются: один лист A4, стандартный масштаб, генерация на клиенте, Unicode-шрифт, детерминированные байты, отсутствие маркеров и live-state, опциональные названия/размеры/декор/подложка и ленивый PDF chunk. ## 5. Скоуп 1. Сделать диалог PDF безопасным на узкой View-поверхности. 2. Исправить нормализацию контуров до генерации размеров. 3. Ограничить размеры горизонтальными и вертикальными гранями с каноническим near-axis допуском. 4. Убирать только одну из локальной пары геометрически противоположных равных граней. 5. Перестроить размещение внутренних и внешних размеров в согласованные полосы. 6. Добавить физическим стенам, перегородкам и колоннам точный фон и штриховку с clipping по их реальной геометрии и проёмам. 7. Выбирать ориентацию и стандартный масштаб по bbox фактически построенной сцены и центрировать эту сцену в печатном поле. 8. Заменить стрелку севера на переданный векторный компас. 9. Удалить архитектурную легенду, сохранив дату, версию и масштабную линейку. 10. Обновить тесты, golden, документацию и лицензионное уведомление. ## 6. Не входит - изменение модели пространства, wall segments, openings, decor или PDF настроек в `localStorage`; - новые настройки экспорта либо изменение значений существующих галочек; - размеры диагональных стен, дуг, мебели, проёмов, перегородок или колонн; - многостраничный PDF, другой формат бумаги или ручной выбор масштаба; - ручное перетаскивание размеров и автоматические строительные размерные цепи; - изменение вида стен на интерактивном плане; - изменение семантики `north_deg` либо способа задания севера; - печать устройств, их состояний или подключение внешних PDF-сервисов; - общий рефакторинг writer за пределами нужных заполненных vector path, clipping и точной сериализации цвета. Если исправление потребует нового config-поля, изменения пользовательских галочек или поддержки размеров настоящих диагональных стен, задача возвращается в `S3-spec`. ## 7. Диалог на узкой поверхности - Поддерживаемая минимальная ширина viewport — 320 CSS px. - Surface, body и footer используют `box-sizing:border-box`, `min-width:0` и не шире доступной области. Padding входит в вычисленную ширину. - Текст внутри label может переноситься; checkbox/radio/input не сжимается и не отделяется от начала своей подписи. - При ширине, на которой две footer-кнопки с локализованными подписями не помещаются, footer становится одной колонкой: «Отмена» сверху, основное действие «Сохранить PDF» снизу; обе кнопки занимают доступную ширину. - На большей ширине сохраняется действующий горизонтальный footer. - Горизонтальный scroll запрещён для документа, dialog surface, body и footer. Вертикальный scroll допустим; все элементы остаются доступны. - Интерактивные цели сохраняют минимум 44×44 CSS px, focus ring и существующий keyboard contract. - Контракт проверяется во всех четырёх локалях EN/RU/DE/FR, а не только на самой короткой строке. ## 8. Нормализация контуров и допустимые грани ### 8.1 Порядок очистки ring Перед поиском коллинеарных вершин каждый конечный ring нормализуется так: 1. удалить повтор последней точки, если он замыкает первую; 2. схлопнуть соседние точные либо близкие точки, включая пару на seam «последняя → первая»; 3. только после этого итеративно удалять промежуточную точку действительно прямого участка; 4. повторять шаги 2–3 до fixed point либо пока проход ничего не изменил. Близость точек — не более 1 mm в физических координатах плана, переведённых в render coordinates через действующий `cell_cm`. Это только фильтр печатной геометрии: исходный config не мутируется. Точки с нечисловыми координатами не создают размер. Точка считается промежуточной только когда оба соседних вектора ненулевые, коллинеарны в пределах канонического допуска и их скалярное произведение положительно. Поэтому разворот, настоящий угол и короткая грань между разными точками не превращаются в хорду. Результат не содержит нулевых рёбер. ### 8.2 Только осевые размеры Размер допускается только для: - строго горизонтальной/вертикальной грани; либо - near-axis грани, отклонённой не более чем на канонические 0.25° из `src/near-axis.ts` (`NEAR_AXIS_MAX_DEGREES` / `NEAR_AXIS_MAX_SLOPE`). Для near-axis шума печатная размерная грань выравнивается по major axis через её midpoint и использует длину major projection. Исходная геометрия не изменяется. Грань за пределом допуска полностью исключается: запрещено строить проекцию, хорду или соединять её соседние концы. Каждый кандидат сохраняет стабильную ссылку на исходные ring и edge index до компактации. Стабильность нужна для дедупликации, layout и детерминированного порядка, но не экспортируется в PDF. ## 9. Локальная дедупликация противоположных размеров Равный отформатированный текст сам по себе никогда не является основанием для удаления. Дедупликация выполняется отдельно: - внутри одного room inner contour; либо - внутри одного связного external outer ring. Два кандидата образуют пару только если одновременно: 1. они имеют одну ось и противоположные нормали; 2. их tangent projection intervals совпадают с допуском 1 mm; 3. их projected lengths совпадают с допуском 1 mm; 4. midpoint соединяющего их перпендикуляра лежит внутри соответствующего простого ring; 5. обе грани остаются допустимыми после §8. Для external ring проверяется внутренняя область самого ring; внутренние holes не связывают несвязанные здания. Один кандидат участвует максимум в одной паре. Если возможны несколько пар, выбирается ближайшая по перпендикуляру, затем по стабильному edge key. Из пары остаётся сторона с лучшим placement score: меньше hard collisions с телом архитектуры/границей печатного поля/уже размещёнными более приоритетными аннотациями, затем больше свободного пространства по нормали. Полная ничья разрешается минимальным стабильным ключом `(axis, tangentStart, normalSign, ringIndex, sourceEdgeIndex)`. Следствия: - прямоугольная комната получает один горизонтальный и один вертикальный внутренний размер, а не четыре; - одинаковые значения у разных комнат, разных connected rings либо на разных осях сохраняются; - равные, но не противоположные участки L/ступенчатого контура сохраняются; - общий горизонтальный и вертикальный габарит одинаковой длины не конфликтуют. ## 10. Размещение размеров Все вычисления clearance выполняются в mm страницы после выбора масштаба и по фактическому rotated bbox текста. ### 10.1 Общие правила - Центр текста проецируется в midpoint измеряемой грани. - Между bbox текста и ближайшей гранью тела стены остаётся минимум 1 mm. - Текст, основная размерная линия и shelf не пересекают тело стены. Extension внешнего размера может начинаться на самой внешней грани стены, но не входит внутрь её тела. - Для вогнутого ring внутренняя/внешняя нормаль определяется пробами point-in-ring по обе стороны грани, а не только направлением к centroid. - Нельзя исправлять collision индивидуальным tangent-jitter текста. ### 10.2 Внутренние размеры Внутренний размер сохраняет действующий лаконичный text-only вид. Его базовая полоса находится внутрь комнаты на расстоянии, равном половине normal extent текста плюс 1 mm от реальной внутренней грани стены. Размеры одного room contour с общей стороной/осью/нормалью относятся к одной полосе. Если любой элемент полосы конфликтует с архитектурой либо уже принятым более приоритетным элементом, вся полоса смещается внутрь шагами 3 mm до первого валидного положения. Если валидного положения нет, сохраняется существующая выноска для непрямоугольной комнаты; произвольный сдвиг текста вдоль стены не допускается. ### 10.3 Внешние размеры Базовая размерная линия проходит на 6 mm наружу от внешней грани тела стены. Текст расположен снаружи линии с зазором 1 mm. Extension lines начинаются на грани тела стены и заканчиваются на своей размерной линии. Коллинеарные внешние размеры с общей осью и внешней нормалью образуют одну полосу. При collision вся полоса — line, extensions, shelf и text — смещается наружу шагами 4 mm. Shelf используется только когда текст шире доступного участка и остаётся частью той же полосы. Базовое расстояние одинаково для всех размеров своего класса. Дополнительные полосы разрешены только как детерминированный ответ на collision; отдельная подпись не может «прилипнуть» к стене или уехать независимо. ## 11. Вид физических стен В PDF следующие объекты получают одинаковый material: - физические room/external/shared стены ненулевой толщины; - перегородки ненулевой толщины; - квадратные и круглые колонны ненулевого размера. Material состоит из: 1. фон RGB `127 127 127`, то есть точный `#7f7f7f`; 2. одна семья диагональных линий 45° к странице, шаг 3 mm, толщина 0.18 mm, цвет основной печатной краски; 3. существующий контур толщиной 0.25 mm поверх fill и hatch. Фаза штриховки привязана к началу страницы, поэтому соседние стены не начинают узор заново и не дают заметных швов. Hatch строится в paper coordinates и обрезается even-odd clip path (`W* n` или эквивалентом) фактического тела каждого объекта. Проёмы остаются чистыми holes; hatch/fill не попадает в tunnel. Нулевая стена сохраняет действующий line contract и не получает ни серый фон, ни hatch. Decor и растровая подложка не меняются. Цвет сериализуется отдельным formatter с достаточной точностью (минимум пять знаков после точки для `127/255`). Координатный formatter writer не меняется: это сохраняет детерминизм и размер файла. ## 12. Компоновка листа ### 12.1 Кандидаты Для обеих ориентаций A4 — portrait и landscape — строится фактическая сцена с: - архитектурой, включёнными decor/подложкой; - реально оставшимися dimension lines, extensions, shelves и text; - фактически понадобившимися выносками; - line widths и rotated text bbox. Приближённые безусловные резервы 30/48 mm удаляются. Header и footer не входят в plan scene и заранее вычитаются из доступного поля. Для каждой ориентации проверяется действующий стандартный ряд масштабов от наиболее крупного к мелкому. Кандидат валиден, только если полный scene bbox с допуском 0.5 mm находится внутри печатного поля. Для экстремального плана после 1:500 denominator продолжается с шагом 50 через конечный bracket/refinement. Заведомо невместимая фиксированная аннотация завершает экспорт `pdf.failed`; обрезанный best-effort PDF не возвращается. ### 12.2 Выбор и центрирование Побеждает: 1. минимальный denominator, то есть наиболее крупный стандартный масштаб; 2. при равном масштабе — большая доля площади печатного поля, занятая полным scene bbox; 3. при полной ничьей — portrait. После выбора переводится весь scene целиком: paths, raster, размеры, текст и выноски. Центр полного bbox совпадает с центром доступного plan field с допуском 0.5 mm. Ни один элемент не пересекает header/footer или поля страницы. Подпись масштаба и scale bar вычисляются из выбранного denominator; нельзя визуально увеличить чертёж, оставив старое значение масштаба. ## 13. Векторный компас Если у пространства задан `north_deg`, существующее место северного указателя занимает `compass-line` из VMware Clarity Assets (`viewBox 0 0 36 36`) — обе канонические filled path, без растрирования и без внешних ссылок. Provenance проверен перед реализацией по неизменяемым первичным материалам: - точный upstream commit — https://github.com/vmware-archive/clarity-assets/commit/bf6bdd0dd3f247f1a320d44d13fecdeda18c071c; - SVG в этом commit — https://github.com/vmware-archive/clarity-assets/blob/bf6bdd0dd3f247f1a320d44d13fecdeda18c071c/icons/travel/compass-line.svg; - MIT license и copyright VMware 2018 в том же commit — https://github.com/vmware-archive/clarity-assets/blob/bf6bdd0dd3f247f1a320d44d13fecdeda18c071c/LICENSE. Переданный владельцем файл имеет SHA-256 `461EBD20E65DF8F017CADCCFEF4F58E7A7E5CB3A8877B4797E6C81C011E41F0B`. Он не совпадает с upstream побайтово: SVG Repo добавил XML/comment и заменил display size `36×36` на `800×800`. При этом `viewBox` и значения обеих `d` path совпадают с точным upstream blob. Реализация вендорит path из указанного upstream commit, а не оболочку SVG Repo, и сохраняет полный MIT license и copyright рядом с ассетом либо в third-party notices. Компас: - сохраняет квадратный aspect ratio и основной печатный цвет; - остаётся vector content PDF; - вращается по прежней семантике: `0°` — северная стрелка вверх страницы, `90°` — вправо, `180°` — вниз, `270°` — влево; - использует действующий resolver `north_deg` и подпись `pdf.north`; - отсутствует, если направление севера не задано. PDF writer получает минимально необходимый filled vector primitive с явно заданными fill rule/fill/stroke. Он не становится универсальным SVG renderer. ## 14. Footer и i18n Архитектурная легенда полностью удаляется: в PDF нет `wall · door · window`, её переводов либо разделителей. Неиспользуемые `pdf.legend.*` удаляются из EN/RU/ DE/FR словарей. В footer сохраняются локализованная дата, `House Plan v…`, действующие разделители и масштабная линейка. Новых пользовательских строк нет. Изменённые описания в документации обновляются на EN/RU; существующие строки диалога проверяются во всех четырёх локалях. ## 15. Модель, совместимость и rollback Config schema, `config_version`, модель пространства и ключи сохранённых PDF опций не меняются. Миграции и downgrade converter не нужны. Экспорт читает исходную модель, создаёт нормализованную временную геометрию и не записывает её обратно. Rollback — возврат frontend/PDF lazy chunk к предыдущей версии. Сохранённые планы и пользовательские настройки остаются совместимы в обе стороны. ## 16. Touch, доступность, безопасность и производительность - PDF-диалог относится к View, поэтому полностью поддерживается на touch, а не по best-effort правилу редакторов. На 320 px он остаётся читаемым и usable. - Клавиатура, Escape, focus trap, focus return и screen-reader names действуют как в #53; перестройка footer не меняет DOM-порядок действий. - Генерация остаётся полностью локальной. Новый ассет вендорится, runtime network request, пользовательский HTML и новые данные HA не появляются. - Lazy boundary сохраняется: до открытия экспорта PDF writer, compass и шрифт не загружаются в initial bundle. - Детерминированность байтов при одинаковых `now`, config и options сохраняется. - Бюджет построения сцены из теста #53 остаётся `<200 ms` для его large-house fixture на референсной Node-среде. Проверка двух ориентаций не должна выполнять повторный разбор модели или декодирование растра. ## 17. Acceptance criteria и доказательства | AC | Критерий | Обязательное доказательство | |---|---|---| | AC1 | При viewport 320×760 в EN/RU/DE/FR ни document, ни surface/body/footer диалога не имеют горизонтального overflow; кнопки полностью доступны и не меньше 44×44 px | targeted browser smoke с `scrollWidth <= clientWidth`, bbox кнопок и фактическим export | | AC2 | Точные/почти точные соседние вершины схлопываются до удаления коллинеарных точек; каждый реальный поворот сохраняется; нулевых рёбер и ложных `3.39/3.93` нет | unit fixture регрессии + mutation witness, отключающий duplicate normalization | | AC3 | Размер получают только H/V и near-axis ≤0.25°; грань за порогом не создаёт проекцию/хорду | boundary unit на обе стороны допуска + scene test + mutation witness без axis filter | | AC4 | Удаляется одна локальная противоположная пара, но сохраняются одинаковые значения разных комнат/rings/осей и непарные равные грани L-контура | unit topology matrix + scene counts + mutation witness глобальной дедупликации | | AC5 | Подпись центрирована, clearance ≥1 mm, базовая полоса едина; collision перемещает целиком полосу, включая line/extensions/shelf | unit bbox/concave tests + focused golden + mutation witness старого tangent-jitter | | AC6 | Физические стены/перегородки/обе колонны имеют точный `#7f7f7f` и page-anchored hatch; openings чисты; zero wall не заштрихована | writer operators/color unit + PDF raster semantic probes/golden + mutation witness без even-odd clip | | AC7 | Обе A4 orientation оцениваются по полному фактическому bbox; выбран максимальный стандартный масштаб, сцена целиком внутри поля и центрирована ≤0.5 mm | scene unit с portrait/landscape и реальными callouts + focused golden + mutation witness старого raw-aspect выбора | | AC8 | Компас содержит обе канонические path, остаётся vector и верно ориентирован при 0/90/180/270°; без north отсутствует; license сохранена | parser/unit + writer PDF parse + raster probes + license check + mutation witness старой стрелки | | AC9 | Архитектурная легенда и `pdf.legend.*` отсутствуют, дата/версия/масштаб сохраняются | extracted-text unit/smoke и i18n consistency + mutation witness возврата легенды | | AC10 | Сохраняются один A4, стандартный scale, все четыре content-toggle, Unicode, отсутствие devices/live-state, deterministic bytes и lazy loading | актуализированные существующие unit/smoke тесты #53 | | AC11 | Построение large-house scene укладывается в `<200 ms`; initial bundle не получает PDF-код | perf unit + bundle/lazy manifest check | | AC12 | Пользовательская и техническая документация соответствует новому результату, а golden/docs fingerprints актуальны | `check-docs`, Linux golden verify и полный Linux docs artifact review | ## 18. Тест-план ### Unit / component - `pdf-dimensions`: exact/near duplicate, seam duplicate, turn retention, fixed-point compact, zero edge, 0.25° boundary, true diagonal, rectangle pair, L-contour false pair, equal dimensions across rooms/rings/axes. - `pdf-scene`: retained counts, midpoint, clearance, whole-lane shift, concave normal, exact full bbox, both orientations, scale bar, wall/partition/column material, opening holes, zero wall, compass cardinals, footer text and perf. - `pdf-writer`: high-precision color, filled compound vector, even-odd clip, parseability and deterministic bytes after new operators. - отдельный compass unit: обе path разбираются в конечные координаты, имеют квадратный bbox и детерминированно трансформируются. ### Browser smoke - текущий полный экспорт и отказ lazy chunk; - 320×760 и четыре локали с измерением overflow; - stacked footer сохраняет cancel/save behavior и download; - извлечённый текст не содержит легенду. ### Visual / golden Обновить `pdf-export-geometry-light` и добавить focused scenario с почти квадратным планом, near-duplicate углом, локальной парой, одинаковыми размерами двух комнат, проёмом, zero wall, перегородкой, обеими колоннами и `north_deg`. Semantic guard проверяет: - ненулевой architectural ink и минимальное заполнение plan field; - серый участок стены с контрастными hatch-полосами; - чистую область проёма; - vector/raster ink в области компаса; - отсутствие содержимого за полями и приблизительное центрирование. На Windows разрешены unit/typecheck/build/browser smoke и диагностический `golden:verify`. Канонические golden и десять docs screenshots переснимаются в Linux CI/закреплённом контейнере: DirectWrite не является принимаемой заменой Linux FreeType. Backend и HA API не меняются, поэтому backend pytest не является целевым доказательством этой задачи. ## 19. Документация и release artifacts Обновить: - `docs/PDF-EXPORT.md` — размеры, hatch, layout, compass, отсутствие легенды; - `docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md` — вид результата; - `docs/TESTING.md` — структурные и visual PDF gates; - `docs/specs/053-pdf-export.md` — явные ссылки на заменённый контракт #482; - `docs/specs/README.md`, `docs/STATUS.md`, `docs/ARCHITECTURE.md` при изменении перечисленных модулей; - screenshot диалога PDF и оба changelog. Коммиты реализации получают `User-Visible: yes`. Changelog EN/RU коротко описывает исправленный экспорт и ссылается на #482. Release body по общему процессу содержит только значимое пользовательское изменение и ссылки на оба changelog. ## 20. Ожидаемая карта изменений - `src/pdf/pdf-dimensions.ts` — нормализация, axis filter, кандидаты и пары; - `src/pdf/pdf-collision.ts` — точные box/segment collision-предикаты для полос; - `src/pdf/pdf-scene.ts` — dimension lanes, material, full-scene candidates; - `src/pdf/pdf-writer.ts` — clipping, filled vector и точный цвет; - `src/pdf/pdf-compass.ts` и лицензионный notice — канонический compass asset; - `src/pdf/hp-pdf-dialog.ts` — narrow responsive contract; - `src/i18n/{en,ru,de,fr}.json` — удаление мёртвых legend keys; - targeted unit/smoke, golden matrix/guards/fixtures и документы §19. Карта не является разрешением на сопутствующий refactoring. Любой новый runtime dependency, config migration или выход за PDF/View dialog требует возврата в `S3-spec`. ## 21. Риски | Риск | Снижение | |---|---| | Локальная дедупликация удалит два разных размера с одинаковым числом | topology pair требует общий ring, ось, interval, противоположные normals и inside probe; negative matrix AC4 | | Очистка дублей срежет настоящий короткий участок | физический epsilon 1 mm, forward-dot и сохранение каждого turn; boundary tests AC2 | | Штриховка закроет проём либо даст швы | page-anchored pattern + even-odd clip + raster probes AC6 | | `#7f7f7f` округлится до `#808080` | отдельный high-precision color formatter и operator/raster test | | Более точный layout станет медленным | model parse/raster decode один раз, perf budget AC11 | | Полный bbox всё ещё пропустит rotated text/line width | bbox строится после фактических annotations и включает stroke/text extents; adversarial tests AC7 | | Compass нарушит лицензию или раздует runtime | две вендоренные path, MIT notice, без общего SVG runtime и в lazy chunk | | Narrow fix сломает focus либо действия | DOM-order неизменен, browser keyboard/download smoke AC1/AC10 |