[Feature]: Network Map — mobile-first Zigbee topology viewer

[tashda]

What problem does this solve?

The Z2M web frontend has a Network Map, but it's a poor fit on a phone:

• Force-directed layout janks under finger gestures, drifts under your tap, and is unreadable on a 6" screen with 50+ nodes.
• No mobile gestures — relies on mouse wheel and click-drag. Pinch-zoom and pan aren't first-class.
• Visual treatment is a generic graph viz, not designed for at-a-glance diagnosis. Weak links, offline devices, and routers don't stand out.
• Refresh model — re-renders constantly, generates lag while still settling.

Shellbee should ship a mobile-first network map: legible, fast, beautiful, and useful for both understanding the mesh and acting on it.

What would you like Shellbee to do?

Build a Network Map screen that's purpose-built for phones.

Layout: hierarchical tree, coordinator at top

Drop force-directed physics. The coordinator sits at the top, routers form the middle layer(s), end devices hang as leaves. Reads like an org chart — predictable, scannable, deterministic. Renders without continuous CPU work, so no jitter, no skipped frames, no "wait for it to settle" UX.

Tradeoffs vs Z2M's force-directed graph: relationships further than 2 hops can be rendered with the longer router chain visible; multi-parent edges (a device that has historical links to multiple routers) draw as additional thin lines without re-layouting.

Use case: diagnostics + action launcher

The map is both a health dashboard and a launcher. Visual treatment:

• Edges colored by LQI: green (≥150), amber (50–149), red (<50), grey/dashed (offline / no recent communication).
• Node states: solid dot for online, hollow / muted for offline, pulse animation for "interviewing" / "updating".
• Routers vs end devices visually distinguished — routers larger, with a small radio glyph; end devices smaller, leaf-shaped.
• Coordinator distinct: hub icon, accent color.
• Device thumbnails inside the node circle when zoomed in past a threshold (matches the iconography reuse from [Feature]: Redesign Activity Log — iconography, density, health events, detail view #14).
• Weak-link highlight: nodes with any LQI below a threshold get a subtle red ring even at the default zoom level, so problems are findable without scanning.

Interactions

• Pinch to zoom + pan — standard MagnificationGesture + DragGesture. Snap-to-fit button to reset.
• Tap a node → open that device's detail screen (same destination as tapping its row in Devices).
• Long-press a node → SwiftUI context menu with the same quick actions as the device list long-press (rename, OTA check / update / schedule, remove). Reuses the menu from [Feature]: Add OTA actions to device long-press menu in device list #15.
• Filter chips above the canvas: Routers, End devices, Weak links, Offline. Tapping fades non-matching nodes/edges to subtle grey instead of hiding them — preserves spatial memory while focusing attention.

Data and refresh

• Cached + manual refresh. On screen entry, show the last-fetched topology immediately (no spinner, no empty screen). A Refresh button in the nav bar re-runs bridge/request/networkmap and shows a non-blocking progress indicator. networkmap is expensive on the coordinator (often 30–60 s on busy networks); never auto-refresh.
• Persist the fetched topology to disk so the cache survives app restarts. Show "Last updated: 2 hours ago" so the user knows whether to refresh.
• Live state overlay: while the topology graph itself is cached, the node states (online/offline, current LQI, updating-now) overlay live data from the existing AppStore. So even before refreshing, dots go green/red as availability changes — the structure is cached, the health is live.

Performance budget

• Static layout = no continuous redraw. The whole canvas should stay at 60–120 fps even on iPhone SE under finger gestures.
• Use Canvas (or MetalView if needed for very large networks) rather than nested ZStacks of shapes. Hundreds of nodes shouldn't drop frames.
• Avoid GeometryReader inside the per-node view — measure once at the canvas level.

Does the Z2M web frontend already do this?

Yes — and Shellbee should match the capability but redesign the experience for mobile. Mirror Z2M terminology (router, end device, coordinator, LQI) so users recognize what they're looking at.

Alternatives considered

• Force-directed graph like Z2M — explicitly rejected. The user's complaint is that the existing one lags and is hard to read; replicating it doesn't solve the problem.
• Radial / concentric rings layout — visually striking, but harder to render multi-hop chains clearly than a tree, and breaks down when one router has many children.
• Live auto-updating — networkmap is too expensive. Cached topology + live state overlay is the right tradeoff.
• Read-only viewer (no actions) — leaves the map as a curiosity rather than a tool. Tap-to-act and long-press-to-menu turn it into a real maintenance surface.

Related

• [Feature]: Redesign Activity Log — iconography, density, health events, detail view #14 (Activity Log redesign) — share the device-thumbnail iconography and category color tokens.
• [Feature]: Add OTA actions to device long-press menu in device list #15 (OTA actions on long-press) — the long-press menu in the map reuses the same items.
• [Feature]: Schedule OTA update for sleepy/battery devices #12 (Schedule OTA) — same battery-aware logic when invoked from the map.