houseplan-card/docs/specs/400-beta-polish.md

ТЗ #400 — Полиш v1.70.0-beta.1: ручки мебели, вес помощи, мёртвое исключение

• Issue: https://github.com/Matysh/houseplan-card/issues/400
• Приоритет: P3, polish; полный трек — три несвязанные поверхности (SVG-рамка редактора декора, состав ленивых чанков, направляющие выравнивания), критерий «одна поверхность» для small не выполняется — прецеденты #369, #385
• Ревизия: 1 (2026-08-31)

Сценарий

Три шероховатости свежей беты, каждая мала по отдельности. Владелец расставляет мелкую мебель (тумба 40 см) и замечает, что за угол рамки ухватиться труднее, чем за бок. Пользователь на медленном канале грузит карточку чуть тяжелее, чем нужно: тексты подсказок редактора приезжают вместе с холодным View. Разработчик читает код направляющих и видит исключение, которое ничего не исключает.

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

До: (1) на мебели уже примерно 80 см осевая ручка лежит поверх угловой и забирает часть её зоны — угол остаётся доступен, но площадь попадания меньше; (2) 38 строк помощи (EN 3,0 КБ + RU 6,3 КБ сырого текста) едут в initial-чанке, хотя видны только в редакторе; (3) видимой разницы нет — это внутренняя правка. После: угол мелкой мебели тянется так же уверенно, как бок; вес initial не несёт редакторских текстов (либо решение зафиксировано осознанно); направляющие опираются на актуальный источник перетаскивания.

Проблема и контракты по пунктам

(1) M5 — осевые ручки перекрывают угловые на мелкой мебели

src/houseplan-card.ts:8439 задаёт единый радиус хита hr = max(view.w, view.h) * 0.018, одинаковый для угловых (:8467) и осевых (:8471) ручек. Осевые рисуются после угловых, поэтому в зоне пересечения хит забирают они.

Замер, а не расчёт (браузер, режим декора, .dtframe на реальной мебели): радиус обеих ручек — 14 px на экране; перекрытие возникает, когда полуширина объекта меньше 2·hr, то есть примерно до 80 см.

Уточнение серьёзности против формулировки аудита. В отчёте было сказано, что «пропорциональный ресайз углом становится недоступен». Это неверно: центр угловой ручки лежит вне круга осевой (для 40 см — 20 единиц плана против радиуса 18), попасть в угол можно, сужается лишь зона. Поэтому пункт остаётся полишем, а не багом. Честная формулировка: на мебели до ~80 см зона угловой ручки урезана примерно вдвое, потому что осевая лежит поверх неё.

Контракт: у угловой ручки приоритет хита над осевой. Достигается порядком отрисовки (угловые кладутся последними) и/или скрытием осевых, когда сторона меньше 4·hr — на такой стороне осевая ручка всё равно неотличима от угловых. Выбор — за реализацией; критерий один: на мебели 40 см клик в геометрический угол рамки достаётся угловой ручке.

(2) Low «б» — тексты помощи в холодном чанке

38 ключей помощи #86 лежат в dist/houseplan-assets/houseplan-card-*.js (проверено grep'ом по собранному дереву), а не в ленивом чанке редактора. Это не дефект #86: словари en и ru по архитектуре ленивой поставки всегда в initial, лениво грузятся только de и fr. Но текст, который виден исключительно в редакторе, оплачивается каждым холодным просмотром: запас бюджета сейчас 15 945 Б при потолке 300 000, а за сутки беты израсходовано 6,1 КБ.

Контракт: решение принимается явно и записывается. Два честных исхода:

1. вынести *.help*-ключи в ленивый чанк редактора (он и так грузится, когда помощь может понадобиться) — тогда initial худеет на величину, которую нужно замерить и указать в отчёте;
2. зафиксировать, что en/ru неделимы, и планировать бюджет с этим знанием — тогда в docs/ARCHITECTURE.md появляется строка о том, что стоимость редакторских текстов входит в initial по построению.

Исход (1) предпочтителен, если механика ленивых словарей допускает раздельные секции без второго сетевого запроса на каждое открытие подсказки; если нет — честнее (2), чем ломать поставку ради 9 КБ.

(3) Low «г» — исключение по мёртвому источнику

src/houseplan-editor-runtime.ts:10970 в ветке _mode === 'devices' пропускает перетаскиваемый маркер по this.host._drag?.id. Но перетаскивание устройств после #74 живёт в отдельном состоянии _deviceDrag (houseplan-card.ts:2548, заполняется на :6736), а _drag (:2547) в этом режиме остаётся null — проверено чтением обоих объявлений и всех присваиваний.

Следствие: маркер, который тянут, попадает в собственный список кандидатов выравнивания. Видимого сбоя нет только потому, что alignGuides (src/logic.ts:1981) сравнивает точку с кандидатами по допуску, и точка совпадает сама с собой — направляющая рисуется «от себя к себе» и визуально неотличима от честной. demo/smoke_align_guides.mjs после a6b0850a проверяет guides() >= 1 и такую подмену не различает.

Контракт: исключение опирается на актуальный источник перетаскивания (_deviceDrag?.id в режиме устройств), а смок различает направляющую от другого маркера и направляющую от самого себя.

Скоуп / не-скоуп

В скоупе: _renderTextFrame в src/houseplan-card.ts (порядок и/или видимость ручек), состав ленивых чанков для help-ключей либо запись решения, _alignCandidates в src/houseplan-editor-runtime.ts, demo/smoke_align_guides.mjs, тесты и мутанты.

Не в скоупе: радиус ручек (hr, решение владельца 2026-08-05 «уменьшить в 4 раза»), механика ресайза мебели (#383), содержание текстов помощи (#86), архитектура ленивой поставки словарей (#352–#355).

UX

Пункт (1) видим: угол мелкой мебели становится так же надёжен, как бок. Пункты (2) и (3) видимого поведения не меняют.

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

Не применимо: ни конфиг, ни layout не затрагиваются.

i18n

Новых строк нет. При исходе (1) пункта (2) ключи не меняются — меняется чанк, в котором они лежат.

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

• AC1. На мебели 40 см клик в геометрический угол рамки достаётся угловой ручке, а не осевой. Доказательство: браузерный смок с синтетическим pointerdown в точку угла и перехватом обработчика — elementFromPoint через shadow root недостаточно (проверено: возвращает саму карточку).
• AC2. На крупной мебели (160 см) поведение не меняется: доступны и угловые, и осевые ручки. Доказательство: тот же смок, вторая ветка.
• AC3. Пункт (2) закрыт явным решением: либо help-ключи не попадают в initial-чанк (доказательство: grep по собранному дереву + замер бюджета до и после), либо решение «en/ru неделимы» записано в docs/ARCHITECTURE.md с причиной.
• AC4. В режиме устройств перетаскиваемый маркер исключён из кандидатов выравнивания по _deviceDrag. Доказательство: юнит на _alignCandidates — при активном _deviceDrag список не содержит позицию тянущегося маркера.
• AC5. Смок направляющих различает «от другого маркера» и «от себя»: проверка падает, если исключение убрать. Доказательство: отрицательный прогон, зафиксированный в документе ревью.
• AC6. Бюджет initial не растёт: при исходе (1) он уменьшается, при исходе (2) остаётся прежним. Доказательство: npm run bundle:budget до и после.

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

Unit (test/align-candidates.test.mjs либо существующий файл):

1. _alignCandidates в режиме devices при активном _deviceDrag не возвращает позицию тянущегося маркера (AC4).
2. Тот же вызов без активного перетаскивания возвращает все маркеры пространства — исключение не «съедает» лишнего.

Browser smoke (demo/smoke_furniture_polish.mjs — дополнение, demo/smoke_align_guides.mjs — правка):

3. Мебель 40 см: pointerdown в геометрический угол рамки вызывает обработчик угловой ручки (AC1).
4. Мебель 160 см: доступны обе ручки, поведение прежнее (AC2).
5. Направляющие: при перетаскивании маркера направляющая строится от ДРУГОГО маркера, а не от самого себя (AC5).

Мутанты (scripts/mutation-gate.mjs):

• furniture-edge-handles-steal-the-corner: вернуть прежний порядок отрисовки → смок AC1 красный.
• align-guides-exclude-dead-source: вернуть _drag?.id в ветке устройств → юнит AC4 и смок AC5 красные.

Риски

• Порядок отрисовки меняет и видимую рамку. Бусины (.dtknob) рисуются рядом с хит-кругами; перестановка не должна менять картинку. Смягчение: golden-кадры рамки мебели — если они есть в матрице, они это и покажут; при расхождении кадр пересматривается осознанно.
• Скрытие осевых ручек ниже порога может удивить. Пользователь, привыкший тянуть за бок, на мелкой мебели его не найдёт. Смягчение: предпочтителен порядок отрисовки, а не скрытие; скрытие — только если порядок не решает.
• Вынос help-ключей ломает ленивую загрузку словаря. Второй сетевой запрос на открытие подсказки хуже, чем 9 КБ в initial. Смягчение: исход (2) остаётся честным ответом, если механика не позволяет.

Откат

Три независимые правки. Пункт (1) — порядок двух блоков в шаблоне; пункт (2) при исходе (1) — состав чанка, при исходе (2) — строка документации; пункт (3) — одно поле в условии. Данные пользователя не затрагиваются.

Release-артефакты

• docs/CHANGELOG.md / docs/CHANGELOG.ru.md: один пункт про угол мелкой мебели (User-Visible: yes). Пункты (2) и (3) — User-Visible: no.
• Скриншоты: пересматриваются, только если golden покажет расхождение рамки.