feat(map): node selection & emphasis on Map Analysis (#3788 Phase 1) (#4010)

* feat(map): add unifiedNodeKey identity helper (#3788)

Canonical cross-source node-identity helper for the upcoming node
selection/follow feature — mt:<nodeNum> / mc:<publicKey> keying,
plus isNodeEmphasized/selectionOpacity dimming helpers. Includes a
drift-guard test asserting the keys match what mergeUnifiedSourceData
buckets on.

* refactor(dashboard): use unifiedNodeKey in mergeUnifiedSourceData (#3788)

Replace the inline mt:/mc: keying block with a call to the new
unifiedNodeKey() helper so the merge and the node-selection feature
can never drift on identity. Behavior-preserving: unifiedNodeKey
implements the exact same MeshCore publicKey/nodeId fallback and
Meshtastic numeric-nodeNum checks the inline code did, including the
null-key skip.

* feat(map): add selectedNodeIds to MapAnalysisConfig (#3788)

Persisted array of unifiedNodeKey identities driving the map's node
selection/follow/dimming feature. load() coerces a missing or
non-array value to [] so old persisted configs and garbage don't
throw. Adds setSelectedNodeIds mirroring the existing setSources
pattern.

* feat(map): shared node hook + selection dimming + picker wiring (#3788)

- useAnalysisNodes(): extract the markers filter (hideFromMap, search,
  node-type, source allow-list) into a shared hook so the picker and the
  map markers layer agree on identity/visibility. Moves NodeRecord out of
  NodeMarkersLayer and adds publicKey for unifiedNodeKey.
- NodeMarkersLayer: consume useAnalysisNodes() instead of its inline
  filter; apply selection dimming via the Marker opacity prop only
  (isNodeEmphasized/selectionOpacity), leaving iconSig/divIcon and the
  spiderfier keyOf untouched.
- NodeMultiSelect: new toolbar picker mirroring SourceMultiSelect
  (pill + popover, Select all / Clear).
- MapAnalysisToolbar: build deduped/sorted node options from
  useAnalysisNodes() and mount NodeMultiSelect after NodeSearchControl.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015AFBA76hsjqhsXe1BdnYub

* test(map): cover useAnalysisNodes, NodeMultiSelect, marker dimming (#3788)

- useAnalysisNodes.test.tsx: positioned+visible filtering, mt:/mc: key
  derivation, hideFromMap/unpositioned exclusion, config.sources allow-list.
- NodeMultiSelect.test.tsx: pill label, checkbox toggle, Select all, Clear
  (only shown when a selection is active).
- NodeMarkersLayer.test.tsx (spec test #6, optional stretch): thin render
  test mocking react-leaflet's Marker to capture the opacity prop, proving
  the isNodeEmphasized/selectionOpacity wiring dims unselected markers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015AFBA76hsjqhsXe1BdnYub

* feat(map): dim unselected node trails on the analysis map (#3788)

Apply the WP-A selection-emphasis helpers (isNodeEmphasized/selectionOpacity)
to PositionTrailsLayer polylines, mirroring marker dimming. Trails are
Meshtastic-only (nodeNum-keyed), so identity is `mt:${nodeNum}`; an empty
selection leaves opacity unchanged at 0.7.

* docs(map): document node selection & emphasis; add epic plan + Phase 1 spec (#3788)

- User docs: map-analysis.md gains a "Node selection & emphasis" section, a
  toolbar-table row, and a persistence-list mention.
- Internal: commit the epic plan (MAP_FOLLOW_AUTOZOOM_EPIC.md) with Phase 1
  marked done + browser-validation evidence, and the Phase 1 implementation
  spec (PHASE1_NODE_SELECTION_SPEC.md).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015AFBA76hsjqhsXe1BdnYub

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: Yeraze

docs/features/map-analysis.md

@@ -34,6 +34,7 @@ The toolbar runs across the top of the canvas. From left to right:
 | --- | --- |
 | **Source multi-select** | Pick which sources contribute to every layer. "All sources" is the default. |
 | **Search box** | Filter visible markers (and traceroute link endpoints) by name or node number. See [Node search](#node-search). |
+| **Node multi-select** | Pick specific nodes to emphasize. Selected nodes render at full opacity; everything else dims. "All nodes" (empty selection) is the default. See [Node selection & emphasis](#node-selection-emphasis). |
 | **Time slider toggle** | Show/hide the floating time-window slider. |
 | **Layer buttons (×8)** | Toggle each visualization layer on/off. The right-edge chevron opens a popover for layer-specific options (lookback window, sub-options). |
 | **Progress bar** | Shows aggregate loading state while any layer is fetching. |
@@ -63,6 +64,23 @@ The toolbar **search box** hides every marker that doesn't match the term and co
 
 Clear the box to restore the full map. The search term lives in the workspace state alongside the other toolbar controls, so it composes with the source filter and every layer toggle.
 
+### Node selection & emphasis
+
+The toolbar **node multi-select** ("All nodes") lets you pin a specific set of
+nodes. The picker lists every node currently on the map — so it already
+reflects the source, node-type, and search filters — with **Select all** and
+**Clear** shortcuts.
+
+With one or more nodes selected, the map keeps *every* node visible but
+**dims the unselected ones** (both their markers and their position trails),
+so your chosen nodes stand out without losing surrounding context. An empty
+selection is the default and dims nothing.
+
+Selection is keyed on a node's stable cross-source identity (Meshtastic
+`nodeNum`, MeshCore public key), so a node reported by several sources stays a
+single entry. The set persists per-browser in the workspace config alongside
+the other toolbar controls.
+
 ## Layers
 
 ### Node markers
@@ -153,7 +171,7 @@ Map Analysis introduces **no new permission resource**. Page access is public (m
 
 ## Persistence
 
-All toolbar state — layer toggles, lookback selections, source filter, time slider window, inspector visibility — is persisted to a single versioned `localStorage` key (`mapAnalysis.config.v1`). It's per-browser, not per-account. The schema is versioned for future migration to server-persisted defaults.
+All toolbar state — layer toggles, lookback selections, source filter, node selection, time slider window, inspector visibility — is persisted to a single versioned `localStorage` key (`mapAnalysis.config.v1`). It's per-browser, not per-account. The schema is versioned for future migration to server-persisted defaults.
 
 ## Limitations (v1)
 

docs/internal/dev-notes/MAP_FOLLOW_AUTOZOOM_EPIC.md

@@ -0,0 +1,115 @@
+# Epic — Follow Nodes on the Map (Auto-center / Auto-zoom)
+
+**Issue:** #3788 — "[FEAT] Ability to follow nodes on the map"
+**Orchestrator model:** Opus 4.8
+**Started:** 2026-07-08
+
+## Goal
+
+Let a user pick a set of sources & nodes on the existing **Map Analysis**
+workspace (`/analysis`) and have the map keep them in view as they move:
+
+- **Follow mode** — on each position update, recenter the map to the *average
+  center* of the selected nodes' current positions, preserving zoom.
+- **Auto-zoom** — on each update, fit the map to the bounding box of the
+  selected nodes' current positions with a **15% margin**.
+- Selection also drives visual emphasis: selected nodes render at full
+  emphasis, unselected nodes are **dimmed but still visible**.
+- Multi-source by design: current positions come from the cross-source merge
+  (`useDashboardUnifiedData` → `mergeUnifiedSourceData`, dedup by
+  `mt:<nodeNum>` / `mc:<publicKey>`), so a node's position is the freshest fix
+  seen by any source (incl. MQTT).
+
+## Interview decisions (2026-07-08)
+
+1. **Home:** Extend the existing `/analysis` `MapAnalysisPage` workspace — NOT a
+   new Dashboard panel or standalone page. Maximum reuse of `MapAnalysisContext`,
+   `SourceMultiSelect`, `PositionTrailsLayer`, `NodeMarkersLayer`,
+   `useMapAnalysisConfig` (localStorage persistence).
+2. **Selection semantics:** **Dim unselected, keep visible.** When the selection
+   is non-empty, unselected node markers + trails are de-emphasized (reduced
+   opacity); selected nodes stay full-emphasis. Follow/Auto-zoom operate on the
+   selected set only. (An empty selection = today's behavior, nothing dimmed.)
+3. **Manual-pan conflict:** While Follow is active, a manual pan/zoom **pauses**
+   Follow and surfaces a "Resume follow" affordance; the map does not yank back
+   on the next update until the user resumes.
+4. **Phase split:** 2 phases (below).
+
+## Reuse anchors (from Stage-0 survey — do not rebuild these)
+
+- **Workspace shell:** `src/pages/MapAnalysisPage.tsx` (`ToastProvider > SettingsProvider > MapAnalysisProvider > [MapAnalysisToolbar, MapAnalysisCanvas, AnalysisInspectorPanel]`).
+- **Config + selection state:** `src/components/MapAnalysis/MapAnalysisContext.tsx` (`useMapAnalysisCtx`) spreads `useMapAnalysisConfig()` and adds `selected`/`nodeFilter`. Config persisted to `localStorage['mapAnalysis.config.v1']` via `src/hooks/useMapAnalysisConfig.ts` (`MapAnalysisConfig` at :40-52).
+- **Toolbar + source multi-select:** `src/components/MapAnalysis/MapAnalysisToolbar.tsx`, `SourceMultiSelect.tsx`, `NodeSearchControl.tsx`, `NodeTypeFilterControl.tsx`.
+- **Canvas + layers:** `src/components/MapAnalysis/MapAnalysisCanvas.tsx` (`MapContainer` at :43, pane stack :49-75). Markers: `layers/NodeMarkersLayer.tsx` (live positions via `useDashboardUnifiedData`, :145). Trails: `layers/PositionTrailsLayer.tsx` (one `Polyline` per `sourceId:nodeNum`, fed by `usePositions`).
+- **View controllers to mirror:** `MapBoundsUpdater` (one-shot `fitBounds`, `DashboardMap.tsx:136-155`), `src/components/MapCenterController.tsx` (`setView` to target), `src/components/ZoomHandler.tsx`, `MapPositionHandler.tsx`. All are `useMap()` children returning `null` — droppable into the Analysis `MapContainer`.
+- **Live position feed:** `useDashboardUnifiedData(sources, enabled)` (`src/hooks/useDashboardData.ts:436`), `refetchInterval: DASHBOARD_POLL_INTERVAL = 15_000`. Merge: `mergeUnifiedSourceData` (:332), position = newest record with both lat+lng.
+- **History/trajectory:** `GET /api/analysis/positions` (cross-source, cursor-paginated, `since` window) via `analysisApi.fetchPositionsPage` + `useMapAnalysisData.usePositions`.
+- **No backend change expected** — all data endpoints already exist. This is a frontend-only epic unless a phase surfaces a real gap.
+
+## Node identity note
+
+Selected-node set must key on the same identity the merge uses:
+`mt:<nodeNum>` for Meshtastic, `mc:<publicKey>` for MeshCore (see
+`mergeUnifiedSourceData`). Do NOT assume a bare `nodeNum` is unique across
+protocols.
+
+---
+
+## Phases
+
+### Phase 1 — Node selection & emphasis  ✅ (browser-validated; PR pending)
+Add an explicit node multi-select to the Analysis toolbar (scoped to the chosen
+sources), stored as `selectedNodeIds` in `MapAnalysisConfig` (persisted).
+`NodeMarkersLayer` + `PositionTrailsLayer` dim unselected nodes when the
+selection is non-empty; selected nodes stay full-emphasis. Empty selection =
+unchanged behavior.
+
+**Exit criteria:**
+- A node multi-select control in the toolbar lists nodes from the currently
+  selected sources (respects existing source/type/search filters), with
+  select-all / clear.
+- Selecting nodes dims unselected markers **and** trails; deselecting restores.
+- `selectedNodeIds` persists across reload (localStorage config).
+- Keyed on `mt:`/`mc:` identity; MeshCore + Meshtastic both selectable.
+- New/extended Vitest coverage green; typecheck clean; browser-validated.
+- Ships as a standalone, useful feature ("pick and highlight nodes").
+
+### Phase 2 — Follow & Auto-zoom  ⬜
+Add "Follow" and "Auto-zoom" toggles to the toolbar. New `useMap()` view
+controller(s) that, on each 15s position update, compute the selected nodes'
+current positions and:
+- **Follow:** `map.setView(averageCenter, currentZoom)`.
+- **Auto-zoom:** `map.fitBounds(L.latLngBounds(points).pad(0.15))`.
+- **Both on:** auto-zoom governs center+zoom (fitBounds implies its own center);
+  Follow is a no-op while Auto-zoom is on.
+- **Manual pan/zoom** while Follow active → pause; show "Resume follow".
+- Toggles persist in `MapAnalysisConfig`.
+
+**Exit criteria:**
+- Toggles present, persisted, independently operable.
+- Follow recenters to average center on update, keeps zoom.
+- Auto-zoom fits selected nodes' current positions + 15% margin on update.
+- Manual pan pauses Follow with a working Resume affordance.
+- Empty selection or single node handled sanely (no NaN bounds, single-point =
+  center at current zoom).
+- Rate-limited so rapid multi-node updates don't cause jitter.
+- New/extended Vitest coverage green; typecheck clean; browser-validated.
+
+---
+
+## Status log
+
+- 2026-07-08 — Stage 0 complete: issue read, code surveyed (2 Explore agents),
+  interview done, plan written. Next: Phase 1 Stage 1 (worktree).
+- 2026-07-08 — Phase 1 implemented across WP-A/B+C/D (identity helper +
+  `selectedNodeIds` config; shared `useAnalysisNodes` hook + `NodeMultiSelect`
+  picker + marker dimming; trail dimming). Full Vitest suite green after a
+  side-hotfix (PR #4008) repaired unrelated reboot-deps tests broken by the
+  #4004 unified-registry refactor on main. Browser-validated on the deployed
+  build: picker renders in the toolbar; selecting 2 nodes drove
+  `selectedNodeIds:["mt:4134514556","mt:3274688221"]`, dimmed 1528 markers to
+  0.3 while keeping selected at 1.0, and the selection + dimming persisted
+  across reload (pill "2 selected"). No Phase-1 console errors.
+  Deviation from plan: interview chose **dim-unselected (keep visible)** over
+  hide-unselected, so Phase 1 emphasizes rather than filters. Next: ship
+  Phase 1 PR after #4008 merges + rebase; then Phase 2 (Follow & Auto-zoom).