houseplan-card/docs/specs/124-isometric-view-toggle-performance.md

# Issue #124 — isometric view toggle выполняет Stage 1 performance budget

- **Issue:** https://github.com/Matysh/houseplan-card/issues/124
- **Статус документа:** готово к будущей реализации; issue остаётся на `S3-spec`
- **Приоритет:** P2
- **Тип:** bug/performance, обычный трек
- **Пользовательское изменение:** нет; скрытый Labs UI и pixels сохраняются

## 1. Симптом и доказательство

В exact-SHA Full Performance для `v1.63.0-beta.1` (`3270e039…`) профиль
`large-house-isometric-v1` измерил:

- `viewToggleMs.median`: 192.8 ms;
- pre-#89 baseline: 31.7 ms;
- limit: 131.7 ms (`base + 20% + 100 ms`);
- все семь candidate samples: 189.2–213.4 ms.

Одно переиспользование wall union в экспериментальном `2576d9d` дало около
10 ms и не закрыло долг. Точная доминирующая причина не доказана. Полная
Lit/DOM смена структурных шаблонов — гипотеза, а не готовое решение.

#156 не является дублем: его regression run имел зелёный `viewToggleMs` на
другой сравнительной линии и прямо исключил #124.

## 2. Цели

1. Профилированием установить стоимость Flat → Iso и Iso → Flat.
2. Уложить canonical profile в неизменённый budget.
3. Сохранить Flat/Iso geometry, live layers, actions, fallback и viewport.
4. Не увеличить cache/heap и не перенести стоимость в соседнюю метрику.
5. Получить воспроизводимое exact-SHA доказательство закрытия исходного долга.

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

- ослабление budget/noise/minimum samples;
- публичное включение изометрии;
- новая Stage 3 геометрия/материалы/камера;
- изменение Flat pixels или editors/static card;
- скрытие live layers на время toggle;
- async loading/network request;
- замена renderer architecture без измеренной причины;
- переоткрытие #89 или поглощение #156.

## 4. Канонический benchmark

`demo/benchmark_large_house.mjs --profile=large-house-isometric-v1` остаётся
authority. `viewToggleMs` включает полный user-observable цикл:

1. `_setProjection('flat')`;
2. `updateComplete`;
3. `_setProjection('iso')`;
4. `updateComplete`.

Нельзя завершить metric до painted DOM либо заменить его pure geometry timing.
Minimum — 7 samples на Linux CI с обычной environment/provenance проверкой.

Для закрытия нужны два сравнения:

- **debt closure:** candidate против pre-#89 SHA
  `316ee76a2913066f8ccd86d27fdf7b17dabaff48`, который использовался как
  историческая граница до merge #89;
- **current regression:** тот же exact candidate против актуального `main`/stable
  обычным workflow, чтобы оптимизация не ухудшила v1.64 соседние paths.

Если automation не умеет сохранить pinned comparison artifact, допускается
manual workflow input с exact SHA и ссылка на run в review. Один зелёный push
candidate-vs-parent, где product code одинаков, не закрывает #124.

## 5. Обязательное профилирование до изменения продукта

До выбора реализации author публикует в issue/review:

- отдельные Flat commit и Iso commit timings;
- main-thread flame/trace либо эквивалентные измеренные call stacks;
- Lit `performUpdate`/template commit долю;
- geometry/cache hit/miss и `_isoScene()` build count;
- DOM node add/remove count по классам слоёв;
- layout/style/paint долю;
- минимум три главных cost centres с абсолютным временем.

Профилирование выполняется на production bundle и той же fixture. Dev build,
один sample или ручное ощущение не являются доказательством.

Diagnostic instrumentation:

- живёт в benchmark/harness либо за test-only hook;
- не создаёт production console noise;
- не меняет timing path в финальном closure run;
- удаляется либо остаётся как дешёвый выключенный counter с documented owner.

## 6. Допустимые направления оптимизации

Конкретное направление выбирается только по §5. Допустимы:

- стабилизация shared DOM subtree и переключение минимального structural layer;
- reuse уже вычисленной scene/union/index geometry;
- разделение structural и live templates, чтобы HA layers не пересоздавались;
- memoization чистых template inputs с bounded identity;
- уменьшение синхронного layout/measurement после projection commit;
- использование части `2576d9d`, если trace подтверждает её вклад.

Запрещено:

- держать два полноценных интерактивных дерева, если это дублирует tab order,
  actions, ids или нарушает heap budget;
- CSS screenshot/bitmap вместо живого плана;
- пропуск `updateComplete`/paint в benchmark;
- debounce, который делает UI быстрым только до позднего тяжёлого commit;
- global cache без лимита;
- UA-specific fast path.

## 7. Render и DOM invariants

- Labs off/expired: iso DOM, geometry work, storage/network path отсутствуют;
- Flat остаётся reference и не получает Stage 2 DOM/classes/filters;
- editors и `houseplan-space-card` всегда Flat;
- Iso использует одну canonical scene/projection snapshot;
- room fills/hover, Glow/spill, sun, decor/backdrop, vacuum, devices, labels и
  opening live panels сохраняются;
- DOM/tab order и actions совпадают по semantic targets;
- no duplicate ids, focus targets или pointer consumers;
- toggle сохраняет logical center и zoom по #89;
- failure latch и explicit retry остаются работоспособными.

Если shared subtree остаётся смонтированным между projections, его inertness,
ARIA и pointer policy должны быть доказаны, а не основаны только на opacity.

## 8. Cache и lifecycle

- `_isoGeometryCache` cap остаётся 8;
- `cacheGrowth.isoGeometry` после profile — 0;
- repeated Flat ↔ Iso не добавляет новые entries при том же fingerprint;
- HA-only state update не rebuild-ит structural geometry;
- theme/locale/live state не меняют geometry key;
- config geometry change инвалидирует правильную scene;
- Labs expiry/removal немедленно делает effective Flat и не удерживает active
  iso DOM вне bounded cache;
- warm remount не усыновляет viewport другой projection.

## 9. Соседние performance budgets

Оптимизация не считается успешной, если `viewToggleMs` зелёный, но ухудшены:

- model ready / first stable render;
- space switch;
- HA state update;
- pan/zoom и resize preview;
- switch cycle;
- long-task count/max/total;
- heap growth;
- Flat `large-house-v1`.

Все лимиты читаются из текущих versioned budget files; hardcoded threshold в
production/test не добавляется.

## 10. Touch, accessibility и actions

- projection toggle остаётся hidden Labs control;
- touch/kiosk gestures имеют прежний safety contract;
- активный dialog/tooltip/focus не дублируется между trees;
- tap/long press на room/device/opening вызывает тот же outcome в Flat/Iso;
- locks/security и service target не меняются;
- keyboard tab order не получает скрытых duplicate nodes;
- reduced motion не относится к мгновенному projection toggle и не меняет
  benchmark semantics.

## 11. Acceptance criteria

1. Profiling evidence на production fixture публикует измеренную root cause.
2. Pinned pre-#89 exact comparison зелёный по неизменённому `viewToggleMs` budget
   с ≥7 samples.
3. Current-main exact comparison также зелёный.
4. Все остальные timing/long-task/heap/cache checks профиля зелёные.
5. Flat profile остаётся в budget.
6. `isoGeometry` cap/growth равны 8/0, repeated toggle — cache hit.
7. Flat/Iso golden и live/touch/action smokes зелёные без несвязанной
   переакцептации.
8. Labs off не создаёт iso work/DOM.
9. HA state update не rebuild-ит geometry и не переносит cost из toggle.
10. Viewport/fallback/warm-remount contract #89/#122 не регрессирует.

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

### Unit/source contract

- cache key/cap/hit/invalidation;
- effective projection/fallback;
- shared DOM ownership и отсутствие duplicate consumers;
- Labs-off source contract;
- logical center conversion unchanged.

### Browser smoke

- repeated Flat ↔ Iso с layer/action parity;
- room/device/opening/vacuum interactions;
- Glow/sun/room fills remain mounted and state-stable;
- theme/state update during/after toggle;
- editor round-trip always Flat;
- kiosk/touch and warm remount;
- injected geometry exception and explicit retry.

### Golden

- все existing Flat и Iso baselines verify;
- никакой baseline не принимается только ради performance fix;
- если measured solution намеренно меняет DOM без pixels, expected diff = 0.

### Performance

- local 1-sample diagnostic допустим только для итерации;
- closure evidence — два Linux exact-SHA runs по §4, ≥7 samples;
- artifacts содержат raw samples, summaries, provenance и cache counters.

## 13. План реализации

1. Добавить/выполнить profiling instrumentation и опубликовать вывод.
2. Выбрать минимальный measured optimization.
3. Зафиксировать structural/live DOM и cache invariants тестами.
4. Реализовать без visual/action diff.
5. Прогнать typecheck, unit и build в цикле.
6. Перед beta прогнать targeted smoke/golden и оба performance comparison.

## 14. Документация и release-артефакты

- changelog не нужен при чистой performance-починке скрытой функции
  (`User-Visible: no`);
- `docs/ISOMETRIC.md` обновляется measured architecture/root cause;
- ADR меняется, только если renderer ownership действительно изменён;
- `docs/TESTING.md`/performance README фиксируют pinned closure evidence;
- user guide и i18n не меняются;
- performance artifacts и review links обязательны;
- golden обновлять запрещено без отдельного visual rationale.

## 15. Риски и откат

| Риск | Мера |
| --- | --- |
| Cost просто отложен после metric | painted completion + trace |
| Два дерева дублируют actions | DOM/ARIA/pointer contract smoke |
| Cache растёт | cap/growth exact assertions |
| Flat подорожал | отдельный flat profile |
| Решение основано на гипотезе | profiling до product diff |

Откат возвращает прежний render path. Cache/storage schema не меняются. Если
оптимизация ломает Flat/actions, Labs kill switch немедленно даёт effective Flat,
но это mitigation, а не критерий принятия красного кода.

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

- историческая debt-граница — exact pre-#89 SHA `316ee76…`;
- benchmark продолжает измерять полный Flat → Iso → Flat/Iso user cycle;
- measured solution может не использовать `2576d9d`;
- public activation изометрии остаётся отдельной будущей задачей.