houseplan-card/docs/specs/464-zigbee-topology-layer-order.md

# #464 — Верхний контекстный слой Zigbee-топологии

- **Issue:** https://github.com/Matysh/houseplan-card/issues/464
- **Тип / приоритет:** bug + polish / P2
- **Трек:** полный; задача намеренно меняет публичный порядок слоёв, ранее
  закреплённый в #54 и #457, и пересекает full-card compositor, lazy overlay и
  live-camera projection
- **Оценка:** пользовательская ценность 6/10; ценность для разработки 5/10;
  сложность 5/10; риск 5/10
- **Связано:** #54, #457, #459; `docs/SCOPE.md`,
  `docs/TOUCH-SUPPORT.md`, `docs/ARCHITECTURE.md`

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

Персона — Home admin из `docs/SCOPE.md`. Поверхность — полная карточка House
Plan в режиме View на desktop с реальной мышью. Момент — администратор уже
включил контекстную Zigbee-диагностику, загрузил snapshot ZHA или Zigbee2MQTT и
наводит указатель на устройство, чтобы понять его прямые связи и следующий шаг
к координатору.

На насыщенном плане линия, стрелка или поясняющая плашка проходит через название
комнаты либо через посторонний маркер. Сейчас содержимое плана закрывает
диагностику именно там, где её нужно прочитать.

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

**До:** названия комнат и любые маркеры устройств могут перекрыть линии,
стрелки и подписи активной Zigbee-топологии; серый пунктир неизвестного LQI
теряется на части заливок.

**После:** активная топология читается поверх содержимого плана, но визуально
уходит под полные маркеры именно тех устройств, которые соединяет; серый
пунктир получает тонкую тёмную окантовку с сохранёнными просветами.

## 3. Подтверждённая причина и изменяемый контракт

Текущая композиция соответствует старому ТЗ, а не случайной CSS-ошибке:

- `docs/specs/054-zigbee-topology-overlay.md` §6 и AC6 закрепляют overlay над
  архитектурой/decor, но под всеми device markers;
- `docs/specs/457-zigbee-route-arrows.md` §8 оставляет arrow/bubble в том же
  слое и AC5 обещает не менять unknown-пунктир;
- `docs/ARCHITECTURE.md` повторяет этот порядок;
- `src/houseplan-card.ts` монтирует lazy overlay перед `.devlayer`;
- host overlay имеет `z-index: 5`, а `.devlayer` — отдельный stacking context с
  `z-index: 6`;
- unknown-LQI link сейчас является одним серым dashed stroke без casing.

Поэтому простое увеличение `z-index` у существующего sibling overlay решает
только половину задачи: весь `.devlayer` останется единым context ниже или выше
него, а дочерний endpoint marker не сможет выйти поверх соседнего stacking
context. Снятие context с `.devlayer` также неприемлемо: во время live pan/zoom
родитель получает CSS transform и снова образует context, отчего settled и
intermediate кадры разойдутся.

#464 явно заменяет только прежний контракт порядка слоёв и оформления
unknown-LQI line. Семантика snapshot, mapping, route tree и hover не меняется.

## 4. Решение владельца

Визуальный порядок активной Zigbee-топологии внутри содержимого плана, сверху
вниз:

1. полные маркеры устройств — концов реально показанных локальных связей:
   исходный hovered marker и все drawable local neighbor markers;
2. все элементы активной топологии: lines, route arrows, halos, remote count и
   parent/space/unplaced bubbles;
3. все посторонние маркеры, названия комнат и остальное содержимое плана.

Системные панели, диалоги, глобальные tooltips и служебные overlays карточки
остаются выше топологии. Весь topology overlay остаётся pointer-transparent.

Unknown-LQI link получает внешнюю окантовку 1 CSS px цветом `#2e2e2e`; основной
серый пунктир, его 2 px ширина, dash rhythm, геометрия и прозрачные промежутки
сохраняются.

## 5. Скоуп

1. Поместить lazy topology overlay в тот же локальный camera/stacking context,
   что device markers и room labels.
2. Задать однозначные локальные уровни для обычного содержимого, topology и
   активных локальных endpoints.
3. Поднимать только точное множество полных marker-элементов, являющихся
   концами реально нарисованных локальных links.
4. Полностью очищать transient endpoint ownership вместе с hover overlay во
   всех действующих lifecycle exits и при замене marker DOM.
5. Не применять отдельную live-camera projection к вложенному overlay: он
   должен двигаться один раз вместе с `.devlayer`.
6. Добавить casing только серому пунктиру local link с неизвестным LQI.
7. Расширить целевой browser smoke фактическими пересечениями, raster probes,
   lifecycle и live-camera проверками; добавить дорогие защитные мутанты.
8. Актуализировать прежние ТЗ, архитектуру, User Guide EN/RU, testing contract,
   STATUS и оба changelog.

## 6. Не входит

- получение, срок жизни, ручное обновление и cache topology snapshot;
- ZHA/Zigbee2MQTT adapters, matching IEEE → marker и privacy contract;
- состав incident links, parent tree, направление стрелок и remote count;
- цветовая шкала известного LQI, halo, тексты или размещение bubbles, кроме
  недопущения перекрытия endpoint marker;
- новые настройки, config/storage поля, миграция либо backend API;
- topology в kiosk, редакторах, static card, touch/pen или keyboard focus;
- изменение маркеров, room labels, live vacuum, opening locks, fit/bounds,
  pan/pinch или device actions;
- общий рефакторинг слоёв карточки за пределами topology;
- исправление возможных пересечений нескольких линий друг с другом: они
  являются одним диагностическим слоем и рисуются по существующему порядку.

Если для решения потребуется изменить mapping, route selection, bubble copy,
config или публичный жест, задача возвращается в `S3-spec` как расширение
скоупа.

## 7. Контракт композиции

### 7.1 Один локальный stacking context

`<hp-zigbee-topology-overlay>` монтируется дочерним элементом `.devlayer`, а не
отдельным sibling между plan SVG и `.devlayer`. Внешний `.devlayer` сохраняет
действующий stage-level `z-index: 6`, поэтому весь пакет остаётся:

- выше plan/architectural/isometric слоёв;
- ниже editor chrome, recovery/loading overlays, zoom/home UI, tooltip и
  диалогов;
- в одном camera context с HTML markers и room labels.

Внутри `.devlayer` нормативный относительный порядок такой:

| Слой | Нормативный локальный уровень | Содержимое |
|---|---:|---|
| Обычное plan HTML | ниже topology | room labels, opening locks, обычные `.dev`, vacuum trail/puck и прочие посторонние markers |
| Active topology | выше любого обычного plan HTML | line casing/core, arrows, halo, remote count, parent bubbles |
| Active endpoints | выше topology | полный `.dev` исходного marker и каждого drawable local neighbor |

Точные числовые `z-index` являются внутренним решением. Они должны образовывать
строгий порядок и не пересекаться с stage chrome. Один рекомендуемый вариант:
обычные дочерние элементы сохраняют текущие 1…6, topology получает 7, endpoints
— 8.

Topology host и каждый его видимый потомок остаются `pointer-events:none`.
Повышение слоя не меняет hit testing: клик, hover, right click, long press и
pan продолжают получать нижележащие существующие targets.

### 7.2 Множество активных endpoints

Transient set равен:

```text
{ hovered source marker }
  ∪ { neighborMarkerId каждого local line, который фактически отрисован }
```

Правила:

- source поднимается только когда для hover существует хотя бы один видимый
  topology primitive: local line/arrow/halo, remote count или parent bubble;
- local neighbor поднимается только если его DOM marker найден и соответствующая
  линия действительно вошла в rendered set;
- remote-space, unplaced, ambiguous, hidden, removed и HA-disabled target не
  создаёт и не поднимает вымышленный marker;
- один marker, участвующий в нескольких links, поднимается один раз;
- посторонний hovered/focused marker не становится endpoint только из-за своего
  обычного CSS hover/focus уровня;
- transient ownership маркируется namespaced DOM-атрибутом, не сохраняется в
  config/layout/localStorage и не попадает в экспорт;
- полный marker означает shell, core, icon/value, LQI/value badges, status dots,
  pulse и остальные уже принадлежащие ему визуальные части.

Overlay остаётся владельцем mouse-hover state и endpoint set. Родительская full
card не получает новый reactive state и не делает тяжёлый render на
pointerover/pointerout.

### 7.3 Cleanup и замена DOM

Endpoint attribute снимается в тот же lifecycle turn, что и визуальная
топология, при каждом из событий:

- pointerleave исходного marker;
- реальный touch/pen input или потеря mouse-hover gate;
- смена space или режима;
- выключение topology setting;
- смена devices/registry/runtime, после которой endpoint больше не drawable;
- disconnected/remount overlay;
- удаление либо замена marker DOM родительским Lit render.

После любого cleanup в `.devlayer` не остаётся marker с endpoint-атрибутом.
Если активный marker DOM заменён эквивалентным элементом при допустимом render,
ownership переносится на новый элемент без закрепления на старом. Для этого
допустим ограниченный `MutationObserver` только за `childList`; он не наблюдает
собственные attribute changes и отключается в `disconnectedCallback`.

### 7.4 Live camera

Вложенный overlay не имеет собственного `data-hp-live-layer="camera"`. Во время
быстрого pan/zoom `live-viewport.ts` трансформирует `.devlayer` целиком, поэтому
markers, labels и topology получают одну и ту же projection ровно один раз.

После terminal Lit frame `viewKey` остаётся сигналом пересчитать screen-space
marker centres и arrow geometry. Контракт проверяется как во временном кадре с
неединичной parent transform, так и после settled frame: линия не отстаёт, не
удваивает сдвиг и не меняет endpoint ownership.

## 8. Контракт unknown-LQI casing

Только локальная link line, у которой выбранное directional observation не
содержит LQI, рисуется двумя совпадающими dashed strokes:

1. casing первым: `#2e2e2e`, ширина 4 CSS px;
2. существующий neutral-gray core вторым: ширина 2 CSS px.

Оба stroke имеют одну геометрию, `stroke-dasharray: 5 5`, одинаковые dash
offset/linecap, opacity contract и `vector-effect: non-scaling-stroke`. Разница
общей ширины 2 px даёт по 1 CSS px окантовки с каждой стороны. Casing не должен
заполнять gap целиком: между соседними видимыми dash остаётся хотя бы один
прозрачный raster column при DPR 1 в целевом smoke.

Известный LQI остаётся одним цветным solid stroke. Solid parent route к bubble
не получает casing, даже если он серый. Route arrow сохраняет текущий fill и не
получает отдельную обводку в этой задаче.

В `forced-colors` действующий системный override сильнее точного `#2e2e2e`:
line/arrow продолжают использовать `Highlight`, а bubble —
`CanvasText`/`Canvas`. Это accessibility contract, а не визуальная регрессия.

## 9. Режимы, touch и доступность

- Функция по-прежнему существует только в full-card View, для HA admin, после
  настоящего mouse hover и при включённой setting.
- Touch/pen немедленно очищают topology и endpoint promotion. Tap/long press не
  получают topology path и не меняются.
- Kiosk, Plan/Devices/Background editors, `houseplan-space-card` и non-admin не
  монтируют overlay и не оставляют transient endpoint attributes.
- Keyboard focus не создаёт topology, но обычный focus marker продолжает
  работать по существующему CSS.
- Overlay не получает role, tab stop или accessible text: это временное
  визуальное продолжение уже существующей admin-only диагностики.
- `prefers-reduced-motion` не затрагивается: новой анимации нет.

Таким образом, View/touch safety floor из `docs/TOUCH-SUPPORT.md` сохраняется;
нового touch UX и сознательной деградации нет.

## 10. Модель данных, миграция и совместимость

Config, layout, topology runtime model, provider payload и WebSocket/MQTT API
не меняются. Endpoint promotion — transient DOM state одного экземпляра full
card.

Миграции, compatibility-полей и downgrade converter нет. Старый frontend после
downgrade читает тот же config и просто возвращает прежний порядок слоёв.

## 11. i18n

Новых или изменённых пользовательских строк нет. Словари EN/RU/DE/FR и
topology namespace не меняются.

## 12. Производительность и lazy boundary

- Disabled topology по-прежнему не загружает lazy overlay chunk.
- Изменение не запускает provider fetch, topology normalization, route BFS,
  mapping или full-card render на hover.
- Endpoint sync ограничен marker DOM текущего space и выполняется только при
  смене hover/rendered endpoints либо замене marker DOM; HA state tick без
  изменения этих границ не должен создавать новый observer или цикл update.
- `MutationObserver`, если используется, один на mounted overlay, наблюдает
  только `.devlayer` child-list и обязательно отключается при disconnect.
- Два SVG stroke вместо одного создаются только для видимых unknown-LQI local
  links активного hover. Постоянного DOM или работы при отсутствии hover нет.
- Initial View graph, topology lazy chunk и bundle budget не должны превысить
  действующие ceilings. Новый full performance profile не требуется; целевой
  topology smoke и `bundle:budget` обязательны.

## 13. Security и privacy

Новых API, permission или persistence surfaces нет. DOM-атрибут содержит только
уже существующую роль endpoint без IEEE, raw payload, entity/device/space id в
значении. Существующие marker `data-id` не расширяются и не логируются.

Pointer transparency обязательна: поднятый overlay не может перехватить
устройство, комнату либо жест сцены. Пользовательский текст bubbles продолжает
выводиться безопасным Lit text binding.

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

### AC1 — однозначный визуальный порядок (`smoke` + raster + ревью кода)

При активном hover полные source и все drawable local neighbor markers
находятся выше lines/arrows/halos/bubbles/remote count. Вся topology находится
выше намеренно пересекающих её unrelated `.dev`, `.roomlabel`, vacuum
trail/puck, opening lock и plan/iso/decor. Stage chrome, tooltip и dialogs
остаются выше topology.

Доказательство: расширенный `smoke_zigbee_topology_hover.mjs` строит
детерминированные пересечения, проверяет computed stacking levels и raster
pixels в точках topology-over-unrelated и endpoint-over-topology. Мутанты
«вернуть overlay sibling под `.devlayer`» и «не поднимать endpoints» краснеют.

### AC2 — ownership, lifecycle и camera invariants (`smoke` + mutation)

Endpoint set точно равен source + endpoints реально нарисованных local links;
remote/unplaced targets не поднимают marker. Overlay и все его primitives
pointer-transparent. Leave, touch/pen, hover-gate loss, mode/space/setting
change, devices/registry/runtime invalidation, DOM replacement и disconnect
очищают либо правильно переносят namespaced attributes. Во время live pan/zoom
topology получает ровно parent projection, а settled frame сохраняет alignment.
Действующие disabled/lazy, click/tap/room-fit/pan contracts не меняются.

Доказательство: browser lifecycle/click/gesture/live-transform matrix.
Защитный мутант, отключающий cleanup или возвращающий отдельный camera attribute
overlay, обязан краснеть.

### AC3 — casing неизвестного LQI (`smoke` + raster + mutation)

Каждый local unknown-LQI link содержит сначала casing `#2e2e2e` 4 px, затем
существующий gray core 2 px; оба имеют одинаковые `5 5`, geometry, offset,
linecap и non-scaling stroke. Raster probe подтверждает 1 px тёмную кромку и
хотя бы один прозрачный column в gap при DPR 1, а min/default/max zoom сохраняют
screen-space толщину. Known-LQI links и solid parent route не получают casing;
forced-colors сохраняет системную палитру.

Доказательство: DOM/computed-style assertions, deterministic raster probes и
мутанты удаления casing, неверного цвета/ширины либо solid gap.

## 15. План автотестов и отрицательные доказательства

1. Расширить `demo/smoke_zigbee_topology_hover.mjs` fixture как минимум тремя
   local markers: source, drawable neighbor и unrelated marker, плюс room label;
   принудительно расположить пересечения в известных screen coordinates.
2. Проверить document/stacking context: overlay является ребёнком `.devlayer`,
   не имеет отдельного live-camera attribute, обычные объекты ниже, exact
   endpoint markers выше.
3. Снять stage screenshot в самом smoke и прочитать pixels через
   `createImageBitmap`/`OffscreenCanvas`: линия видна поверх unrelated marker и
   room label, но не поверх центров source/neighbor. Отдельно навести настоящий
   Playwright-курсор через `page.mouse.move` на source и проверить, что его
   вычисленный `z-index` остаётся выше overlay при активном CSS `:hover`;
   синтетический `dispatchEvent(pointerover)` эту ветку каскада не покрывает.
4. Для unknown-LQI link проверить два совпадающих strokes и растровую
   последовательность core → dark casing → background/gap при DPR 1; повторить
   screen-space geometry на wide/tall и min/default/max zoom.
5. Проверить known-LQI local link и gray solid parent route отрицательно: casing
   отсутствует.
6. Расширить существующий lifecycle smoke: pointerleave, touch, mode, space,
   setting off, marker DOM replacement и overlay disconnect не оставляют
   endpoint attributes; click сквозь overlay достигает прежнего target.
7. В transient live-camera frame вручную применить одну non-identity projection
   штатным viewport helper и доказать общую матрицу parent/markers/overlay;
   после commit transform отсутствует, geometry совпадает.
8. Добавить в `scripts/mutation-gate.mjs` дорогие mutants для AC1–AC3, чтобы
   отзыв слоя, endpoint promotion/cleanup и casing нельзя было принять одним
   зелёным DOM-тестом, не чувствительным к дефекту.
9. Перед `S7-code-review`: `npx tsc --noEmit`, `npm test`, `npm run build`,
   `npm run bundle:sync`, `npm run bundle:budget`,
   `node scripts/check-docs.mjs`, `node scripts/smoke-select.mjs --base
   origin/dev --head HEAD`, выбранные topology/device-action/viewport smokes,
   `npm run golden:verify`, `npm run benchmark:zigbee-topology` и
   `node scripts/no-new-any.mjs --base origin/dev --head HEAD`.

Существующая golden matrix не активирует admin mouse-hover topology, поэтому
новый постоянный golden baseline не вводится. Визуальный контракт закрывает
детерминированный raster smoke, который падает по пикселям, а не только по DOM.
`golden:verify` подтверждает отсутствие регрессий остальных сцен.

## 16. Затронутые файлы и модули

Ожидаемый продуктовый минимум:

- `src/houseplan-card.ts` — topology host внутри `.devlayer`;
- `src/zigbee-topology-overlay-bridge.ts` — исключение двойной camera
  projection;
- `src/hp-zigbee-topology-overlay.ts` — локальный уровень, endpoint ownership,
  cleanup и unknown-LQI casing;
- `src/styles/devices.styles.ts` и при необходимости
  `src/styles/plan.styles.ts` — namespaced endpoint layer contract.

Проверки и документы:

- `demo/smoke_zigbee_topology_hover.mjs`;
- `scripts/mutation-gate.mjs` и smoke-selection registry при необходимости;
- `docs/specs/054-zigbee-topology-overlay.md` и
  `docs/specs/457-zigbee-route-arrows.md` — явная отметка о заменённом #464
  порядке слоёв/unknown casing;
- `docs/ARCHITECTURE.md`, `docs/USER-GUIDE.md`,
  `docs/USER-GUIDE.ru.md`, `docs/TESTING.md`, `docs/STATUS.md`;
- `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`;
- manifest-driven `dist/**` и integration frontend после `bundle:sync`;
- docs screenshot index/frames после штатного Linux capture, потому что
  меняется `src/**`.

Backend Python, config schema и i18n не меняются.

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

| Риск | Мера |
|---|---|
| Простое повышение sibling `z-index` накрывает endpoints или остаётся под всем `.devlayer` | Один stacking context внутри `.devlayer`, отдельный exact endpoint level |
| Двойной сдвиг при быстром pan/zoom | У вложенного overlay нет собственного camera projection; live-transform smoke |
| Transient attribute залипает после смены режима/DOM | Единый owner set, полный cleanup matrix, bounded child-list observer |
| Линия перекрывает badge/pulse связанного marker | Поднимается полный root `.dev`, raster probe на endpoint centre и shell edge |
| Topology закрывает системную кнопку/tooltip | Внешний `.devlayer` level не меняется, chrome/dialog levels проверяются |
| Поднятый overlay крадёт click/pan | `pointer-events:none` на host/primitives + сквозной click/gesture smoke |
| Casing превращает пунктир в сплошную линию | Одинаковый `5 5`, screen-space strokes и pixel probe прозрачного gap |
| Forced colors теряет системный контраст | Существующий `!important Highlight` остаётся authority |
| Hover начинает перерендеривать всю карточку | Ownership остаётся внутри lazy child; parent reactive state не добавляется |
| Observer создаёт цикл или leak | Только `childList`, один observer, disconnect cleanup и call-count assertion |

## 18. Rollback

Кодовый откат одного продуктового коммита возвращает topology host отдельным
sibling под `.devlayer`, удаляет endpoint promotion и второй unknown-LQI stroke.
Config, layout и provider cache не мигрируют, поэтому data rollback и ручное
вмешательство не нужны.

Пользовательский немедленный workaround до отката — выключить существующую
опцию Zigbee links; весь lazy overlay исчезает как раньше.

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

Поскольку исправление пользовательски видимо:

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md` получают короткий пункт со
  ссылкой на #464;
- User Guide EN/RU объясняет приоритет активной topology над посторонним
  содержимым и сохранение endpoints сверху;
- `docs/ARCHITECTURE.md` фиксирует один `.devlayer` stacking context и
  transient endpoint ownership;
- исходные ТЗ #54/#457 получают ссылку, что #464 заменил только прежний layer и
  unknown-dash visual contract;
- `docs/TESTING.md` связывает AC с topology raster/lifecycle smoke;
- постоянный product golden не добавляется по причине из §15;
  `golden:verify` остаётся обязательным;
- изменение `src/**` требует полного актуального Linux `Docs screenshots`
  artifact и reviewed acceptance всех кадров по общему процессу; кадры не
  принимаются с Windows;
- performance/security отдельных отчётов не требуется; обязательны
  `benchmark:zigbee-topology`, `bundle:budget`, mutation и штатные beta gates;
- generated bundle trees обновляются только через `npm run bundle:sync`.

## 20. Принятые технические предположения — можно менять на ревью

1. Рекомендуемые local levels 7/8 не являются публичными; важен строгий порядок
   §7.1 и неизменный внешний `.devlayer` level.
2. Namespaced endpoint attribute живёт на root `.dev`, потому что так единым
   уровнем поднимаются shell, badges, pulse и hit surface без дублирования
   renderer.
3. Overlay сам синхронизирует attributes, чтобы mouse hover не становился
   reactive state full card и не возвращал регрессию производительности #451.
4. Bounded `MutationObserver(childList)` допустим только если Lit способен
   заменить marker DOM без изменения child properties; реализация может выбрать
   эквивалентный lifecycle hook с теми же AC.
5. Casing реализуется вторым совпадающим `<line>` перед core, а не SVG filter:
   это сохраняет deterministic screen-space geometry и позволяет отдельно
   проверить прозрачный gap.
6. Parent-route line к bubble остаётся без casing: решение владельца относится
   к серым пунктирным links с неизвестным LQI, а этот route сплошной и имеет
   другую семантику.
7. Raster probes в целевом smoke являются достаточным визуальным witness без
   расширения общей golden matrix, поскольку topology существует только во
   время программно созданного admin mouse hover.