feat: add contextual Zigbee topology hover

Issue: #54
User-Visible: yes

docs/ARCHITECTURE.md

@@ -1636,6 +1636,30 @@ diffs the real `seedHiddenBindings`/`buildDevices` outputs — there is no
 second copy of the filter logic to drift. The field registry (#33) carries
 their passports; `scripts/config-audit.mjs` treats both as `current`.
 
+## Contextual Zigbee topology (#54, 2026-09-04)
+
+The initial View graph owns only the fail-closed settings reader and a dynamic
+overlay bridge. A saved `settings.zigbee_topology.enabled === true`, an actual
+HA admin, full-card View and non-kiosk surface are all required before the
+topology overlay chunk is requested. Opening the lazy General Settings runtime
+does not load provider transport until an enabled saved setting needs status or
+the admin presses a provider action.
+
+`zigbee-topology.ts` normalizes ZHA and Zigbee2MQTT into unordered edge pairs
+with separate directional observations, maps IEEE nodes through exact HA
+registry ownership and resolves only edges incident to the hovered marker.
+Routes never invent neighbor edges. `zigbee-topology-runtime.ts` owns a
+per-connection memory cache and in-flight dedupe: ZHA reads `zha/devices`
+without requesting a scan; Z2M verifies the retained bridge-info topic, sends
+one correlated raw `routes:false` request through `mqtt.publish`, rejects
+retained/foreign/late replies and always releases subscriptions.
+
+The pointer-transparent overlay is stacked above architectural/isometric
+layers and below device markers. It reads the already projected marker centres,
+so flat/isometric camera and zoom remain single-source. Cache data, IEEE
+addresses and raw payloads are never persisted, logged, exported or admitted
+to support diagnostics.
+
 ## The initial bundle carries English and Russian whole (#400, 2026-08-31)
 
 `en` and `ru` are synchronous dictionaries in the initial chunk; `de` and `fr`

docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- Administrators can optionally load a ZHA or Zigbee2MQTT topology snapshot and
+  see only the observed direct neighbours of the device currently under a real
+  mouse pointer. The diagnostic layer is off by default, never scans on hover,
+  counts rather than draws cross-space links, and stays absent from touch,
+  kiosk, editors and the static card
+  ([#54](https://github.com/Matysh/houseplan-card/issues/54)).
 - In View and kiosk, clicking or tapping a room now centres it and fits its
   visible floor and boundary walls with 10% screen margins; a visible room
   label offers the same action from the keyboard

docs/CHANGELOG.ru.md

@@ -8,6 +8,12 @@
 
 ## Не выпущено
 
+- Администратор теперь может явно загрузить снимок топологии ZHA или
+  Zigbee2MQTT и при наведении реальной мыши видеть только наблюдаемых прямых
+  соседей выбранного устройства. Диагностика по умолчанию выключена, никогда не
+  запускает сканирование от наведения, считает вместо отрисовки связи с другими
+  пространствами и не появляется на touch, в киоске, редакторах и статической
+  карточке ([#54](https://github.com/Matysh/houseplan-card/issues/54)).
 - В Просмотре и киоске клик или тап по комнате теперь центрирует и вписывает
   её видимый пол и ограничивающие стены с полями 10%; видимая подпись комнаты
   даёт то же действие с клавиатуры

docs/CONFIG-COMPATIBILITY.md

@@ -77,6 +77,21 @@ new frontend restores the disabled behavior after upgrade. Full backup/import
 preserves the setting and the privacy-safe support projection includes only a
 validated boolean.
 
+## Contextual Zigbee topology (#54)
+
+`settings.zigbee_topology` is an optional global object. Only exact
+`enabled: true` activates the admin-only full-card View layer; absence,
+malformed values and older configs are off. `z2m_base_topics` is a bounded list
+of exact MQTT base topics: empty entries, wildcards, duplicates and control
+characters are dropped. Disabling the feature retains valid topics; resetting
+General settings removes the object.
+
+Provider snapshots, IEEE addresses, links, errors and timestamps are runtime
+memory only. They are not config fields, do not enter backup/export or support
+diagnostics, and disappear with the HA connection/page. Older frontends ignore
+the settings object; the backend's unknown-settings policy preserves it. No
+model or store version migration is required.
+
 ## Vacuum map routes (#162)
 
 `marker.vacuum.map_routes` is an optional array of

docs/SCOPE.md

@@ -46,7 +46,7 @@ deliberate degradation is allowed under `TOUCH-SUPPORT.md`.
 | J4 | "From zero to a working plan in one evening, no Inkscape/YAML" — image/PDF/draw, floors-import wizard, room polygons bound to areas, filtered auto-placement, editable icon rules | **Closed**; onboarding polish is *partial* (no registry-driven room suggestions) |
 | J5 | "Room climate at a glance" — per-room temperature/humidity, comfort-range fills, room-card metrics | **Closed** |
 | J6 | "Keep the plan true as the home evolves" — new-device flag, two editors, drag/resize, merge/split, multi-client live sync, optimistic locking | **Closed** |
-| J7 | "Is my Zigbee mesh healthy *here*?" — LQI badges, per-room average, LQI fill | **Closed** (kept deliberately: cheap, spatial by nature, no in-plan competitor) |
+| J7 | "Is my Zigbee mesh healthy *here*?" — LQI badges, per-room average/fill and opt-in direct-neighbour links for one hovered device | **Closed** (spatial diagnostics; no persistent full-mesh graph) |
 
 ## Partially covered — improvement backlog stays inside these
 

docs/SUPPORT-PRIVACY.md

@@ -25,6 +25,11 @@ URLs, paths, filenames, plan/backdrop/manual bytes, vacuum calibration and
 trails, backup history, message and contact. Unknown fields are dropped rather
 than copied and redacted later.
 
+The Zigbee topology snapshot is never offered to this package: raw provider
+payloads, IEEE addresses, neighbor links, base topics, timestamps and provider
+errors stay out of support preview/download/submission and out of browser
+storage and logs.
+
 ## Preview and authorization
 
 Only a Home Assistant user allowed to write House Plan can build or send a

docs/USER-GUIDE.md

@@ -201,6 +201,20 @@ but hide the floating room summary, turn off **General settings → Show the roo
 information window on hover**. The option is on by default and does not affect
 device tooltips.
 
+For an occasional Zigbee placement check, an administrator can enable
+**General settings → Show Zigbee links when hovering over a device**. The option
+is off by default. Load the provider snapshot there: **Read ZHA data** reads
+ZHA's existing cache, while **Update map** starts an explicit Zigbee2MQTT raw
+network-map scan for each entered base topic (default `zigbee2mqtt`). The latter
+may take 10 seconds to 2 minutes and can temporarily slow the Zigbee network.
+
+After data is loaded, moving a real mouse over a mapped Zigbee marker shows
+only its observed direct neighbours. Links to markers on the current space are
+lines; drawable neighbours on other spaces are summarized as a temporary
+count. This is a snapshot, not the route currently used by every packet. The
+layer does not appear on touch/pen, in kiosk, in editors or in the static card,
+and hovering never starts a scan.
+
 Each editor has a stable primary toolbar. Tool parameters and selected-object
 actions appear in a context tray over the top of the canvas. On a narrow screen
 the tray scrolls horizontally instead of shrinking the plan.

docs/USER-GUIDE.ru.md

@@ -212,6 +212,21 @@ title: План дома
 Показывать окно с информацией при наведении на комнату**. По умолчанию опция
 включена и не влияет на подсказки устройств.
 
+Для разовой проверки размещения Zigbee администратор может включить **Общие
+настройки → Показывать связи Zigbee при наведении на устройство**. По умолчанию
+опция выключена. Там же надо явно получить снимок: **Прочитать данные ZHA**
+читает уже существующий кеш ZHA, а **Обновить карту** запускает raw-сканирование
+Zigbee2MQTT для каждого указанного базового топика (по умолчанию
+`zigbee2mqtt`). Сканирование занимает от 10 секунд до 2 минут и временно может
+снизить отзывчивость Zigbee-сети.
+
+После загрузки данных наведение реальной мыши на сопоставленный Zigbee-маркер
+показывает только его наблюдаемых прямых соседей. Соседи в текущем пространстве
+соединяются линиями, а доступные маркеры в других пространствах учитываются во
+временном счётчике. Это снимок соседства, а не маршрут каждого текущего пакета.
+На touch/pen, в киоске, редакторах и статической карточке слой не появляется;
+само наведение никогда не запускает сканирование.
+
 В редакторах сетка продолжается по всему рабочему холсту. В режиме просмотра сетка не показывается.
 
 Основная панель каждого редактора содержит только постоянные инструменты, а

docs/UX-MODES.md

@@ -83,6 +83,14 @@ The global `settings.show_room_tooltip` preference controls only the floating
 room information window. Missing or invalid values mean enabled; exact `false`
 hides the window while room highlight and every device tooltip remain active.
 
+The admin-only **General settings → Show Zigbee links on device hover** option
+is off by default. Once an admin explicitly reads cached ZHA data or updates a
+configured Zigbee2MQTT map, mouse hover temporarily draws only the observed
+direct links incident to that device. A linked marker in another space is
+counted beside the source without drawing an inter-space line. Hover never
+fetches data; touch, pen, keyboard focus, kiosk, editors and the static card do
+not expose this diagnostic layer.
+
 Removed from this mode (they move, not die):
 - icon dragging ("drag anywhere", v1.9 — consciously reversed),
 - room-label dragging,