houseplan-card/docs/specs/156-full-performance-regressions.md

Issue #156 — регрессии Full Performance перед v1.64.0 stable

• Issue: https://github.com/Matysh/houseplan-card/issues/156
• Редакция: первая редакция для независимого ревью; статус определяется только метками issue
• Тип / приоритет: bug / P1
• Оценка: пользовательская ценность 8/10; ценность для разработки 10/10; сложность и риск 6/10
• Область: runtime physical geometry, Plan snap hover/render, release performance gate
• Модель данных: без новых полей, миграции и backend-изменений
• Связано: #137, #141, #153, #124, docs/specs/137-plan-snap-overlay.md, docs/specs/141-wall-junctions.md, demo/performance/README.md

1. Контекст и симптом

Exact-SHA stable-кандидат 321d153c22dfe2087e31437720919f872d9cd47c дважды воспроизводимо провалил обязательный Full Performance:

• run: https://github.com/Matysh/houseplan-card/actions/runs/31829284992;
• обычный и изометрический профили превысили бюджеты полного цикла из 12 переключений этажей и суммарных Long Tasks;
• Plan snap профиль дополнительно потратил около 2,65 секунды на 120 pointermove до первого клика, включая один Long Task около 2,54 секунды;
• оба Glow-профиля прошли;
• viewToggleMs прошёл, поэтому #124 не является причиной этого падения.

Attempt 1 и повтор на свежем runner-е показали один класс превышений. Ослабление budget запрещено; стабильный релиз #153 заблокирован до зелёного exact-SHA Full Performance.

2. Пользовательский сценарий

Персона: администратор дома, который переключает этажи в View или точно рисует контур/перегородку в desktop-редакторе Плана.

До исправления: релизная линия beta выполняет лишнюю polygon-union работу при переключении пространства. В Плане движение мыши над snap topology до первой точки инициирует полный render большой сцены; на крупном плане серия движений может заблокировать main thread на секунды.

После исправления: переключение не строит неиспользуемую unioned geometry, а до первой точки hover меняет только один SVG-маркер. Линии, точки, snap-result, rubber-band, click и сохранённая геометрия визуально и семантически прежние.

3. Установленные причины

3.1 Лишняя unioned physical geometry

После #141 physicalBodySet() всегда вычисляет geometry через polygon union. Полный card runtime и physicalBodies() используют только drafts, partitions, columns, patches и all; geometry в production-пути не читается. Одноэлементный cache полного card меняет ключ при каждом переходе на другой этаж, поэтому ненужный union повторяется в каждом switch.

3.2 Полный render на initial snap hover

#137 сохраняет результат hover в _planSnapHover, а координату — в реактивный _cursorPt. Даже когда _path пуст и rubber-band ещё отсутствует, каждый pointermove назначает _cursorPt и запускает полный Lit render 60 комнат, 200 устройств и всей статической snap topology. В benchmark 120 обновлений идут в одном interaction window и образуют наблюдаемый длинный блок.

4. Scope

В issue входят:

1. Разделение построения raw/join-patch physical bodies и необязательной unioned geometry так, чтобы production consumers без union не платили за неё.
2. Сохранение текущего pure API/семантики unioned geometry для unit-проверок и любого consumer, которому она действительно нужна.
3. Разделение Plan snap overlay на неизменную topology и единственный активный marker.
4. Обновление active marker до первого клика без полного render карточки.
5. Сохранение обычного реактивного rubber-band после появления anchor, без повторного создания статической topology при неизменном snapshot.
6. Regression unit/smoke и прохождение неизменённых Full Performance budgets.
7. Запись исправления в оба changelog и выпуск через дополнительную beta перед повторным stable promotion.

5. Non-scope

Не входят:

• изменение цветов, радиусов, толщины линий, layering или видимости overlay;
• изменение tolerance, endpoint-first приоритета, grid/45°/line quantization;
• изменение click/tap, T-join, autoclose, room/draft/partition или wall geometry;
• новый spatial index для resolver или общая декомпозиция большого render;
• изменение fixture, samples, budget, baseline selection или compare policy;
• исправление отдельного изометрического долга #124;
• schema, backend, storage, import/export, i18n, network или HA permissions;
• публичная функция, настройка или feature flag.

6. Контракт physical geometry

1. Pure-построитель physical parts возвращает тот же детерминированный набор drafts, partitions, columns, patches и all, что текущий physicalBodySet() до union.
2. physicalBodySet() либо эквивалентный явный union-consumer сохраняет текущее значение geometry, порядок-независимость, bounded mitre/bevel и fail-closed поведение malformed inputs.
3. Full card и static-card consumers, которым нужны только bodies, используют non-union путь. Они не вычисляют geometry скрыто через spread, getter или wrapper side effect.
4. Cache keys и invalidation остаются структурными: пространство, config epoch, cell_cm и grid/scale. HA state, hover и theme не добавляются в ключ.
5. Raw identity для editor hit/selection и joined patches для render/physics сохраняются. Результирующие SVG/clean-floor/light/iso pixels не меняются.

7. Контракт snap hover и DOM

7.1 Статическая topology

• Статические plan-snap-line и endpoint nodes строятся из существующего immutable geometry snapshot.
• При pointermove с тем же snapshot их DOM nodes и атрибуты не пересоздаются и не обходятся ради выбора active styling.
• Cache invalidation остаётся прежним: structural config, space, active draft и другие уже входящие в geometry key факторы перестраивают topology.

7.2 Один активный marker

• Overlay содержит не более одного active marker.
• Для endpoint marker расположен точно поверх статической точки, имеет прежний active endpoint style и радиус 10 см.
• Для line candidate marker имеет прежний dynamic style, wall-bound/grid-bound координату и радиус 10 см.
• При miss, pointerleave, смене инструмента/пространства/режима, pan/pinch cancel marker очищается.
• Marker остаётся pointer-events:none, aria-hidden через родительскую группу и не становится focusable.

7.3 Initial hover без полного render

Пока _path пуст:

1. pointermove использует тот же canonical resolvePlanSnap();
2. _cursorPt остаётся пустым, потому что rubber-band ещё нечего рисовать;
3. меняется только dedicated active marker внутри уже существующего overlay;
4. полный Lit update карточки не запрашивается только ради hover;
5. click повторно вызывает resolver из координат события и не доверяет DOM или устаревшему hover state.

После первого click текущий reactive path/cursor render сохраняется: live rubber-band должен двигаться вместе с marker. Следующий внешний Lit render обязан согласовать dedicated marker с текущим state, поэтому оптимизация не создаёт второго авторитетного snap-result.

8. Совместимость, touch и accessibility

• Persisted config и layout побайтно не меняются от hover/render/cache warm-up.
• Старые планы получают оптимизацию без migration и write-back.
• Desktop hover остаётся полным контрактом #137.
• Touch editor остаётся best effort: tap без hover повторно resolves candidate; pinch/pan/suppressed click не сохраняют сегмент. View и kiosk не получают новых interaction branches.
• Новых доступных элементов, текстов и keyboard semantics нет. Forced colours, dark/light theme и reduced motion сохраняют текущий вид.

9. Производительность и наблюдаемость

1. Budgets и runner не ослабляются и не меняют смысл.
2. large-house-v1, large-house-isometric-v1 и large-house-plan-snap-v1 проходят относительные и абсолютные thresholds на одном exact SHA; оба Glow-профиля остаются зелёными.
3. Plan snap diagnostics по-прежнему доказывают cache/DOM/config/ws stability, endpoint и line paths и единственный active candidate.
4. Технический regression test отдельно доказывает отсутствие полного Lit update для initial hover; один зелёный timing без structural assertion недостаточен.
5. Full Performance запускается после публикации исправленной beta и нового promotion SHA в main, как требует stable runbook.

10. Acceptance criteria

• AC1 (unit + code review; разработчик/ревьюер): pure physical-parts path возвращает те же raw bodies и junction patches, что текущая реализация, но не вызывает polygon union; explicit union path сохраняет прежнюю geometry и permutation/area assertions #141.
• AC2 (unit + smoke; разработчик): full/static runtime использует non-union parts без скрытого eager вычисления; View/Plan/static/hidden iso сохраняют прежний physical footprint, clean floor и wall-junction pixels.
• AC3 (smoke; разработчик): при пустом _path endpoint, line и miss pointermove обновляют ровно один active marker без вызова полного Lit update, не меняют static-node identity/count, geometry cache, config и websocket.
• AC4 (smoke + golden; разработчик): endpoint marker остаётся прежнего цвета/радиуса 10 см поверх статического endpoint, line marker — прежнего dynamic вида; lines/endpoints, layering, forced-colours и pointer transparency визуально не меняются.
• AC5 (unit + smoke; разработчик): click без предварительного hover, click после initial hover и следующие clicks используют canonical resolver; endpoint/line coordinates, Shift/grid priority, T-join, autoclose и no-split-target semantics #137/#138/#141 сохраняются.
• AC6 (smoke; разработчик): после первого anchor rubber-band и marker следуют pointer, а pointerleave, tool/space/mode change, pan/pinch и cancel очищают marker без ghost state или лишнего commit.
• AC7 (performance; разработчик): exact-SHA Full Performance проходит без правок пяти budget files, fixture semantics, sample count и compare logic; артефакт содержит зелёные ordinary, isometric, plan-snap, blend и overlay comparisons.
• AC8 (unit + backend/schema review; разработчик/ревьюер): schema, serialized config/layout, backend, import/export, i18n, HA calls, permissions и зависимости не меняются; hover и cache не создают writes.
• AC9 (typecheck + unit + build + documentation review; разработчик): implementation-loop gates зелёные; RU/EN changelog обновлены в том же User-Visible: yes commit; три bundle snapshots после release build идентичны.
• AC10 (release gate; релиз-менеджер): исправление опубликовано в новой v1.64.0-beta.*, beta issue закрыты штатно, затем новый promotion-only stable commit получает зелёные exact-SHA Validate и Full Performance до тега v1.64.0.

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

11.1 Unit

• выделить pure physical-parts builder и сравнить drafts/partitions/columns, patches и all с explicit union wrapper;
• сохранить #141 matrix: endpoint/line joins, unequal thickness, permutation, near-miss, malformed/zero-length и geometry area;
• добавить assertion, что production parts API не требует/не материализует geometry;
• существующие resolver tests #137/#138 остаются без изменения ожидаемых точек.

11.2 Targeted production-bundle smoke

Расширить demo/smoke_plan_snap_overlay.mjs либо добавить узкий smoke:

1. после initial render перехватить/посчитать card update requests;
2. выполнить endpoint → line → miss pointermove при пустом path;
3. доказать ноль full updates, один active marker, неизменные static nodes/cache и отсутствие writes;
4. выполнить click без hover и после hover, затем move с непустым path;
5. проверить rubber-band, exact coordinates и очистку marker;
6. сохранить существующие gesture, gaps, draft exclusion и T-join проверки.

Существующие smoke/golden #137/#141 являются визуальным и поведенческим контрактом. Новые golden не требуются, потому что pixels должны остаться прежними; любой непредусмотренный diff исследуется и не принимается автоматически.

11.3 Performance и release

• implementation loop: npm run typecheck, npm test, npm run build;
• перед beta: полный smoke/golden/HA/performance gate по runbook;
• после promotion в main: exact-SHA Validate и Full Performance;
• сравнить все пять comparison reports, а не останавливаться на первом зелёном профиле;
• не переиспользовать красный artifact как доказательство и не ослаблять budget.

Backend не меняется; targeted backend test не нужен, полный Linux harness остаётся release gate.

12. План реализации

1. Выделить из physicalBodySet() построитель physical parts без union; явный set/geometry consumer строит union только по запросу.
2. Перевести full/static body consumers на parts path и убрать geometry из runtime cache shape, если оно не читается.
3. Разделить static snap topology и dedicated active marker; исключить обход всех endpoints ради active styling.
4. Добавить синхронизацию marker с canonical hover state и fast path при пустом _path; сохранить reactive path после anchor.
5. Дополнить unit/smoke, прогнать implementation gates.
6. Обновить changelog и release metadata, пересобрать bundle snapshots в prerelease commit, выпустить beta и повторить stable promotion/gates.

Точные имена helpers и способ локального DOM-handle (ref, controller или эквивалент) не являются продуктовым контрактом.

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

Исправление пользовательски заметно как восстановление отзывчивости, поэтому implementation commit имеет User-Visible: yes и обновляет:

• docs/CHANGELOG.md;
• docs/CHANGELOG.ru.md.

docs/USER-GUIDE.ru.md, docs/CANVAS.md, docs/WALL-THICKNESS.md и i18n не меняются: описанный пользовательский контракт остаётся прежним. Новые golden не ожидаются. Обязательны targeted smoke, полный beta gate, exact-SHA artifacts и повторный stable Full Performance. Security report не требуется.

14. Риски и снижение

Риск	Вероятность / ущерб	Снижение
Dedicated marker расходится с Lit state после внешнего render	средняя / высокий	один canonical hover state; render всегда повторно синхронизирует marker; transition smoke
Fast path оставляет ghost marker при навигации/gesture	средняя / средний	единый clear helper и matrix pointerleave/tool/space/mode/pinch
Endpoint меняет yellow style на dynamic green	средняя / средний	отдельный kind/class contract и golden/smoke radius/style assertions
Удаление eager union меняет physical footprint	низкая / высокий	parts equality, existing #141 unit/smoke/golden, explicit union wrapper unchanged
Локальный runner зелёный, Linux всё ещё красный	средняя / высокий	только exact-SHA Full Performance является release evidence
Оптимизация маскируется ослаблением gate	низкая / высокий	budget/fixture/compare files вне implementation diff

15. Откат

Откат — revert user-visible implementation commit #156 вместе с тестами, changelog и соответствующими prerelease bundle snapshots. Persisted data и schema не меняются, migration/data rollback не нужны. После отката возвращается performance-регрессия, поэтому стабильный релиз остаётся заблокированным.

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

1. Внешний snap/junction контракт полностью наследуется из #137/#138/#141; новых продуктовых решений нет.
2. Рекомендуемый physical-parts helper может называться иначе, если eager union доказуемо отсутствует у production consumers.
3. Active marker может обновляться через локальный DOM handle внутри overlay; SVG DOM не становится источником snap geometry или commit coordinates.
4. Static topology может быть защищена Lit guard, вынесена в child component или сохранена эквивалентным способом; node identity/count обязаны быть стабильны.
5. Fast path применяется только когда live rubber-band отсутствует. После anchor допустим полный reactive update, если Full Performance и структурные AC зелёные.
6. Любая дополнительная оптимизация вне двух установленных горячих путей требует отдельного обоснования в issue и не должна расширять пользовательский scope.
7. Открытых продуктовых вопросов нет.