# ТЗ #337 — ленивый editor-runtime и multi-asset frontend

- Issue: https://github.com/Matysh/houseplan-card/issues/337
- Тип: техдолг / производительность
- Приоритет: P2
- Трек: полный — задача влияет на производительность и меняет несколько
  поверхностей и release-asset contract, поэтому не проходит критерии `small`
  из `PROCESS.md` §5
- Связанные задачи: #34 — направление декомпозиции frontend; #62 — единый
  eager-реестр двух текущих языков, lazy i18n в этой задаче отсутствует

## 1. Сценарий

Основная персона — жилец или гость (`docs/SCOPE.md`), который открывает
дашборд Home Assistant на телефоне, планшете или настенной панели, чтобы быстро
увидеть дом и управлять устройствами в View. Он не должен загружать код трёх
администраторских редакторов, пока сам не попросил открыть редактор.

Вторичная персона — владелец/администратор. При первом входе в Plan, Devices
или Background после открытия дашборда он допускает короткое ожидание загрузки,
но не потерю View, текущего пространства, масштаба или незавершённого клика.

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

До изменения каждый вход на дашборд загружает весь редактор; после изменения
обычный View становится рабочим после заметно меньшей загрузки, а код редактора
подгружается только перед первым фактическим входом в него, без изменения
интерфейса и поведения редакторов.

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

## 3. Подтверждённое исходное состояние

Замеры выполнены на `origin/dev` `eff786f`, версия 1.68.1:

- `dist/houseplan-card.js` — 1 353 147 B raw / 378 335 B gzip;
- `src/houseplan-card.ts` даёт около 1 052 KiB кода до terser и содержит View,
  editor state machines, команды, панели и диалоги в одном классе;
- backend раздаёт только точный файл
  `/houseplan_files/houseplan-card.js`; относительный chunk сейчас получит 404;
- bundle sync, freshness, demo, CI и release scripts считают артефактом один
  JS-файл;
- консервативная минификация всех текущих статических `css\`\``-литералов
  уменьшает bundle примерно на 32 016 B raw, но только на 2 114 B gzip. Она не
  заменяет реальное code splitting;
- #62 намеренно сохранила `en` и `ru` синхронными/eager. Утверждение старого
  описания #337 о lazy dictionaries неверно и не является предпосылкой ТЗ.

## 4. Цели

1. Не загружать runtime Plan/Devices/Background и editor-only dialogs в первом
   рабочем View.
2. Ограничить сумму gzip initial View graph величиной **250 KiB**.
3. Сохранить наблюдаемое поведение View, переходов, редакторов, конфигурации и
   Home Assistant card editor.
4. Сделать несколько frontend-файлов полноценным проверяемым артефактом HACS,
   backend, demo, CI и release automation.
5. Безопасно минифицировать статические Lit CSS templates без визуальной
   разницы.

## 5. Не-цели

- не менять stored config/layout и не добавлять миграцию;
- не менять UX, состав инструментов, DOM-контракт, pointer thresholds,
  Undo/Redo, touch policy или геометрию;
- не заменять и не упрощать `polyclip-ts`;
- не делать lazy loading текущих i18n dictionaries;
- не оптимизировать backend API или SVG/Glow вычисления, если они нужны View;
- не считать успехом маленький entry, который тут же синхронно или автоматически
  скачивает тот же код до готовности View;
- не делать автоматический idle-prefetch editor runtime: он вернул бы сетевой
  расход всем пользователям, которые редактор не открывают.

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

### 6.1 Первый View

1. `houseplan-card` и `houseplan-space-card` регистрируются так же надёжно, как
   до изменения; HA не показывает промежуточное `Custom element doesn't exist`.
2. View считается готовым только когда видны план и устройства и доступны
   обычные View-действия. Все JS-файлы, обязательные до этого момента, входят в
   initial View graph и budget §13.
3. Ни один editor-only asset не запрашивается до намерения пользователя открыть
   редактор или editor-only диалог. Hover без клика и простои страницы не
   считаются намерением.
4. Пустая новая установка сохраняет текущий onboarding: диалог создания первого
   пространства не может зависеть от editor runtime.

### 6.2 Вход в редактор

1. Нажатие Plan, Devices или Background сначала запускает единственный shared
   loader. Mode, editor chrome и editor camera не коммитятся до успешной
   установки runtime.
2. Повторные/конкурентные клики используют один Promise; runtime не скачивается
   и не устанавливается дважды.
3. Пока загрузка занимает меньше 150 ms, отдельная плашка не появляется. После
   150 ms поверх неизменившегося View показывается неблокирующий существующий
   transition surface с текстом «Загружаем редактор…» / “Loading editor…”.
4. После успеха выполняется обычный переход текущего `mode-transition`; первая
   editor-панель не появляется в полуготовом состоянии. Пространство, View zoom
   snapshot и selection contracts сохраняются.
5. После первой успешной загрузки все три редактора и editor-only dialogs
   используют уже установленный runtime без новой сети.
6. Lovelace GUI editor загружается тем же lazy graph через async
   `getConfigElement()`. Создание config editor не должно заставлять View заранее
   загружать editor runtime.

### 6.3 Editor-only dialogs из View

К editor-only относятся формы, изменяющие plan/device/decor data и не нужные для
обычного просмотра. Если такая форма вызывается из доступной в View цепочки
(например, Edit из device info), loader завершается до открытия формы. Info,
more-info, подтверждение действия, статусы проёмов, kiosk controls и onboarding
остаются eager, если они нужны View сами по себе.

Точный список экспортов фиксирует `editor-runtime-manifest.ts`; новый editor-only
диалог должен добавляться туда, а не импортироваться из View entry напрямую.

### 6.4 Ошибка загрузки и обновление во время открытой вкладки

1. Первый сетевой/parse/fingerprint failure повторяет import один раз с
   versioned cache-buster текущей карточки. До retry View остаётся рабочим.
2. После повторной ошибки mode остаётся `view`, editor session не создаётся,
   toolbar/camera/selection не меняются. Показывается локализованное сообщение:
   «Не удалось загрузить редактор. Обновите страницу и повторите попытку.» /
   “Could not load the editor. Refresh the page and try again.”
3. Runtime сообщает build fingerprint до установки. Несовпадение entry/runtime
   рассматривается как тот же failure; код разных версий не смешивается.
4. Автоматический hard reload запрещён: он может прервать другое действие на
   HA-дашборде. Пользователь сам решает, когда обновить страницу.
5. Ошибка editor asset никогда не скрывает план и не ломает View-действия.

## 7. Архитектурный контракт frontend

### 7.1 Граница runtime

Создаётся `src/editors/runtime/` с двумя явными сторонами:

- eager `editor-loader.ts`: маленькая state machine `idle → loading → ready |
  failed`, dedupe, retry и fingerprint handshake;
- lazy `houseplan-editor-runtime.ts`: composition root редакторов;
- `editor-host-port.ts`: typed минимальный порт к snapshot, командами, save,
  translation, requestUpdate и mode transition владельца карточки;
- editor-specific render/controller modules, вынесенные из
  `houseplan-card.ts` законченными ответственностями.

Runtime не получает `HouseplanCard` через `any`, не патчит prototype и не читает
произвольные private fields. Он работает через typed host port и собственный
state. Число `any` в `src/` не увеличивается. Pure geometry authorities остаются
в текущих модулях и передаются runtime как обычные imports; второй модели
геометрии не создаётся.

Изменение является крупным independently releasable slice направления #34:
root сохраняет HA lifecycle, View projection/render, server revisions, common
dialogs, navigation и visual continuity; runtime получает editor gestures,
tool state, editor chrome/secondary tray, editor-only drafts/dialogs и команды.

### 7.2 Import graph

- eager entry не имеет static import из `src/editors/runtime/houseplan-editor-runtime.ts`
  или editor-only descendants;
- единственное runtime-ребро — `import()` внутри loader;
- общие модули, реально нужные View и editor, остаются eager либо становятся
  shared chunk, который входит в initial budget;
- модуль не признаётся editor-only только по имени: Rollup manifest и тест
  import graph являются источником истины;
- `polyclip-ts` сохраняется там, куда его помещают реальные потребители.

## 8. Multi-asset build и раздача

### 8.1 Выход Rollup

Rollup пишет дерево:

```text
dist/
  houseplan-card.js
  houseplan-assets/
    <rollup chunks>.js
  houseplan-assets.json
```

Имена chunk содержат content hash. Manifest детерминированно содержит:

- source fingerprint;
- entry filename;
- для каждого asset: relative path, SHA-256, raw bytes, gzip bytes;
- static imports и dynamic imports;
- рассчитанные `initialViewGzipBytes` и `lazyEditorGzipBytes`.

Порядок записей и gzip settings фиксированы, поэтому Windows/Linux build одного
SHA создаёт побайтово одинаковые committed snapshots.

### 8.2 Backend route

Точный публичный URL `/houseplan_files/houseplan-card.js` остаётся без изменений.
Chunks раздаются публичным read-only view по
`/houseplan_files/houseplan-assets/{filename}`.

View:

- принимает только один basename без `/`, `\\`, `..` и percent-decoded обходов;
- раздаёт только `.js`, присутствующий в текущем `houseplan-assets.json`;
- разрешает real path только внутри `frontend/houseplan-assets/`;
- возвращает 404 для отсутствующего/неразрешённого asset;
- не требует auth, потому что Lovelace ESM assets должны загружаться до карточки;
- перечитывает/инвалидирует manifest после обновления integration, чтобы config
  entry reload не оставлял старый allowlist.

Plans и marker files не возвращаются в public static path; существующий signed
content API не меняется.

### 8.3 Копии и HACS

`bundle:sync` атомарно синхронизирует **всё дерево**, а не один файл:

1. `dist/` — build output;
2. `custom_components/houseplan/frontend/` — committed release snapshot;
3. `demo/srv/assets/` — materialized untracked test copy.

Перед копированием target asset directory очищается только по списку старого
manifest, с path containment check; посторонние файлы не удаляются. После копии
каждый hash сверяется с manifest.

`houseplan.zip` включает entry, manifest и все chunks. Отдельный GitHub asset
`houseplan-card.js` сохраняется как диагностический entry-файл, но каноническая
установка остаётся целым `houseplan.zip`; документация не обещает, что один
скачанный entry без integration assets является самостоятельной установкой.
Release verification проверяет полный manifest внутри zip.

## 9. CSS minification

Build plugin обрабатывает только static Lit `css\`\`` templates без `${…}`:

- удаляет CSS comments вне строк;
- схлопывает ASCII whitespace вне строк;
- удаляет пробелы вокруг безопасной пунктуации, не меняя значения custom
  properties, strings, escapes, `url()`, `calc()`, media/container queries и
  descendant combinators;
- fail-closed сообщает файл/позицию при interpolation или незакрытой
  строке/comment вместо частичной порчи CSS;
- порядок templates и rules не меняется.

Минификация не имеет отдельного продуктового budget: ожидаемая gzip-экономия
мала и учитывается в общем initial View graph.

## 10. Fingerprint и cache contract

1. Source fingerprint продолжает покрывать `src/`, Rollup, TypeScript и lockfile;
   manifest несёт то же значение.
2. Entry публикует fingerprint как сейчас. Lazy runtime экспортирует тот же
   fingerprint; loader сверяет его до `ready`.
3. Demo freshness проверяет entry и manifest, затем SHA-256 каждого asset.
4. Content-hashed filename предотвращает выдачу нового кода из старого browser
   cache. Entry version query продолжает меняться вместе с release version.
5. Старый открытый entry после обновления может запросить удалённый hash; это
   штатный failure §6.4, а не основание хранить бесконечно старые chunks.

## 11. I18n и документация

Добавляются четыре ключа (RU/EN): loading editor, load failed, refresh advice и
доступное имя busy-state. Остальные подписи не меняются.

Обновляются:

- `docs/ARCHITECTURE.md` — multi-asset graph, runtime boundary и public routes;
- `docs/DEVELOPMENT.md` — build/sync/deploy всего дерева, проверка manifest;
- `docs/USER-GUIDE.ru.md` и README RU/EN — прежний resource URL сохраняется,
  но frontend состоит из entry и внутренних assets; ручное копирование одного
  JS не является поддерживаемой установкой;
- `docs/TESTING.md`/релевантный testing guide — сценарий failure и network gate;
- оба changelog — изменение пользовательски заметно по скорости и редкому
  сообщению ошибки.

## 12. Совместимость и миграция

Stored data не меняется; миграции нет. Старый браузер, способный исполнять
текущий ESM bundle, способен исполнять native dynamic import. При отсутствии
assets обновлённый entry сохраняет View и выдаёт §6.4.

Обновление integration требует полный HACS zip и обычный restart/reload HA.
Новый backend с новым frontend является штатной парой; mixed-version runtime
блокируется fingerprint handshake.

## 13. Критерии приёмки

**AC1. Честный initial budget.** На production build сумма gzip entry и всех
транзитивных static imports до рабочего первого View ≤ 256 000 B; dynamic editor
assets не учитываются только если browser smoke подтверждает, что они не
запрошены до editor intent. **Доказательство:** `bundle-budget` unit + CI command
с manifest + Playwright network smoke.

**AC2. Реальная lazy boundary.** Initial import graph не содержит editor runtime,
editor toolbar/gesture/dialog modules и GUI config editor; первый вход в любой
из трёх редакторов загружает один deduplicated editor graph. **Доказательство:**
manifest/import-graph unit и Playwright network smoke.

**AC3. View parity.** Configured View, kiosk, touch View, device actions,
Glow/sun/vacuum, openings, room hover, space switching and visual continuity
проходят без golden delta. **Доказательство:** связанные smokes + полный golden
verify на pre-release gate; на code-review — selected smokes из registry.

**AC4. Editor parity.** Plan, Devices и Background открываются после cold load;
основные select/draw/save/undo flows и editor-to-editor transitions проходят
существующие smokes без изменения ожидаемого DOM/данных. **Доказательство:**
selected editor smokes и unit tests controller/loader.

**AC5. Loader atomicity.** Двойной клик/конкурентные запросы выполняют один
import/install; mode и camera меняются только после ready. **Доказательство:**
unit с controllable Promise + browser smoke.

**AC6. Failure сохраняет View.** Первый 404/parse/fingerprint failure retry-ится
один раз; второй оставляет mode=view, план интерактивным и показывает
локализованное сообщение. **Доказательство:** unit loader state machine +
Playwright route abort/mismatch scenarios RU/EN.

**AC7. Asset security.** Backend отдаёт только manifest-listed JS из asset root и
отказывает traversal, encoded traversal, nested path, unknown extension и stale
asset. **Доказательство:** HA backend tests.

**AC8. Полнота distribution.** Build/sync/zip/release verification падают при
удалении или подмене любого manifest asset; dist, integration и demo после sync
побайтово совпадают по manifest. **Доказательство:** Node release-contract,
bundle-sync и freshness tests + zip test.

**AC9. CSS без семантической порчи.** Plugin корректно сохраняет strings,
escapes, URLs, custom properties, calc/media/container и combinators, умеет
падать на interpolation/malformed input; computed styles выбранных компонентов
и golden images не меняются. **Доказательство:** unit с adversarial fixtures +
computed-style smoke + golden verify.

**AC10. Fingerprint mismatch не смешивает версии.** Runtime с другим fingerprint
не устанавливается и проходит failure contract. **Доказательство:** unit +
browser injected mismatch.

**AC11. Onboarding и GUI editor.** Empty-config onboarding работает без editor
asset; async `getConfigElement()` загружает editor graph и возвращает прежний
custom element/config contract. **Доказательство:** browser smokes обоих путей.

**AC12. Без model drift.** No-op config/layout roundtrip и backend validation не
изменяют данные; `any` count в `src/` не растёт; второй geometry authority не
появляется. **Доказательство:** existing roundtrip/schema tests + static gate.

**AC13. Документация не обещает single-file install.** Resource URL остаётся
прежним, а install/deploy docs требуют целое asset tree. **Доказательство:**
`check-docs` и ревью текста.

## 14. План автотестов и гейты реализации

На каждом implementation slice:

```text
npm run typecheck
npm test
npm run build
npm run bundle:sync
node scripts/check-docs.mjs
node scripts/smoke-select.mjs --base origin/dev --head HEAD
<все smokes, выбранные registry и перечисленные AC>
git diff --check
```

Перед code review дополнительно:

- backend pure tests и полный HA subset в WSL/CI для frontend asset view;
- new network/failure/editor cold-load smoke;
- `npm run inventory`;
- hashes полного asset tree;
- `npm run golden:verify` как диагностический локальный прогон; канонический
  full golden/performance остаётся pre-beta CI по `PROCESS.md`.

Mutation guards обязаны уметь сломать: dynamic boundary, retry cap, fingerprint
check, manifest allowlist, omitted zip chunk, CSS string/comment handling и
initial budget.

## 15. Риски и меры

| Риск | Мера |
|---|---|
| Big-bang перенос editor state ломает жесты | переносить законченными typed slices; одинаковые smokes до/после каждого slice; без новой geometry model |
| Chunk доступен в demo, но 404 в HA | production backend route + HA harness test; smoke использует production URL layout |
| Entry мал, но eager shared chunk возвращает вес | budget следует transitive static graph из manifest и подтверждается network trace |
| Update смешивает версии | content hash + source fingerprint handshake; отказ до install |
| Сломан ручной deploy | sync/deploy docs и script работают с tree, не с одним `scp` |
| CSS whitespace меняет selector/value | token-aware conservative transform, adversarial tests, computed style + golden |
| Release zip неполон | manifest-driven zip validation и публичный asset verification |
| First editor click выглядит зависшим | 150 ms delayed loading surface, View остаётся на месте |

## 16. Откат

Откат выполняется одним release commit к предыдущему monolithic Rollup output,
точному static route и single-file bundle tooling. Stored config/layout не
менялись, поэтому data rollback не нужен. Backend не удаляет старый entry URL;
после отката новые chunk routes становятся неиспользуемыми.

## 17. Release-артефакты

- production entry + manifest + chunk tree в `dist/` и integration snapshot;
- обновлённый `houseplan.zip` с полным tree;
- прежний top-level GitHub `houseplan-card.js` entry asset;
- RU/EN changelog со ссылкой на #337;
- architecture/development/user docs;
- новые unit/backend/browser tests; golden baselines не меняются без отдельного
  reviewed acceptance.

## 18. Принято предположительно, можно менять без владельца

- имена внутренних modules/chunks и форма typed host port;
- формат manifest, если он остаётся детерминированным и доказывает все AC;
- точная реализация delayed loading surface поверх существующей transition UI;
- механизм перечитывания manifest backend view;
- gzip implementation и fixed compression level в budget script;
- разбиение editor extraction на внутренние commits/slices.

Нельзя менять без продуктового решения владельца: прежний resource URL,
отсутствие автоматического hard reload, сохранение рабочего View при failure и
отсутствие заранее загружаемого editor prefetch.