refactor: split renderPrefixTool, fix recommendation logic, add tests

Address all 4 review items:

1. God function: split 290-line renderPrefixTool into 10+ smaller
   functions (buildPrefixIndex, computePrefixStats, recommendPrefixSize,
   validatePrefixInput, checkPrefix, generatePrefix, plus HTML helpers:
   renderNetworkOverview, renderPrefixChecker, renderPrefixGenerator,
   renderCheckerResults, renderNodeEntry, renderSeverityBadge,
   renderPrefixStatCard).

2. Inline HTML: extracted HTML template literals into dedicated builder
   functions that return HTML strings. Each section (overview, checker,
   generator, results) is its own function.

3. Dead recommendation logic: fixed >=500 nodes to recommend 3-byte
   prefixes instead of 2-byte (was dead code recommending the same
   thing for both branches).

4. Tests: added test-prefix-tool.js with 28 tests covering index
   building, collision detection, recommendation thresholds (including
   boundary values), input validation, prefix checking, generator
   logic (deterministic via injectable random fn), and severity badges.

Pure logic functions are exported via window._prefixToolExports for
testability without DOM dependencies.

.github/workflows/deploy.yml

@@ -129,6 +129,13 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Free disk space
+        run: |
+          # Prune old runner diagnostic logs (can accumulate 50MB+)
+          find ~/actions-runner/_diag/ -name '*.log' -mtime +3 -delete 2>/dev/null || true
+          # Show available disk space
+          df -h / | tail -1
+
       - name: Set up Node.js 22
         uses: actions/setup-node@v5
         with:
@@ -229,7 +236,7 @@ jobs:
   build:
     name: "🏗️ Build Docker Image"
     needs: [e2e-test]
-    runs-on: [self-hosted, Linux]
+    runs-on: [self-hosted, meshcore-vm]
     steps:
       - name: Checkout code
         uses: actions/checkout@v5
@@ -239,6 +246,12 @@ jobs:
         with:
           node-version: '22'
 
+      - name: Free disk space
+        run: |
+          docker system prune -af 2>/dev/null || true
+          docker builder prune -af 2>/dev/null || true
+          df -h /
+
       - name: Build Go Docker image
         run: |
           echo "${GITHUB_SHA::7}" > .git-commit
@@ -258,7 +271,7 @@ jobs:
     name: "🚀 Deploy Staging"
     if: github.event_name == 'push'
     needs: [build]
-    runs-on: [self-hosted, Linux]
+    runs-on: [self-hosted, meshcore-vm]
     steps:
       - name: Checkout code
         uses: actions/checkout@v5
@@ -314,6 +327,17 @@ jobs:
             exit 1
           fi
 
+      - name: Clean up old Docker images
+        if: always()
+        run: |
+          # Remove dangling images and images older than 24h (keeps current build)
+          echo "--- Docker disk usage before cleanup ---"
+          docker system df
+          docker image prune -af --filter "until=24h" 2>/dev/null || true
+          docker builder prune -f --keep-storage=1GB 2>/dev/null || true
+          echo "--- Docker disk usage after cleanup ---"
+          docker system df
+
   # ───────────────────────────────────────────────────────────────
   # 5. Publish Badges & Summary (master only)
   # ───────────────────────────────────────────────────────────────

.gitignore

@@ -30,3 +30,4 @@ cmd/ingestor/ingestor.exe
 # CI trigger
 !test-fixtures/e2e-fixture.db
 corescope-server
+cmd/server/server

AGENTS.md

@@ -33,7 +33,7 @@ public/            — Frontend (vanilla JS, one file per page) — ACTIVE, NOT
   style.css        — Main styles, CSS variables for theming
   live.css         — Live page styles
   home.css         — Home page styles
-  index.html       — SPA shell, script/style tags with cache busters
+  index.html       — SPA shell, script/style tags with __BUST__ placeholder (auto-replaced at server startup)
 test-fixtures/     — Real data SQLite fixture from staging (used for E2E tests)
 scripts/           — Tooling (coverage collector, fixture capture, frontend instrumentation)
 ```
@@ -51,18 +51,41 @@ The following were part of the old Node.js backend and have been removed:
 
 ## Rules — Read These First
 
+### 0. Performance is a feature — not an afterthought
+Every change must consider performance impact BEFORE implementation. This codebase handles 30K+ packets, 2K+ nodes, and real-time WebSocket updates. A single O(n²) loop or per-item API call can freeze the UI or stall the server.
+
+**Before writing code, ask:**
+- What's the worst-case data size this code will process?
+- Am I adding work inside a hot loop (render, ingest, WS broadcast)?
+- Am I fetching from the server what I could compute client-side?
+- Am I recomputing something that could be cached/incremental?
+- Does my change invalidate caches more broadly than necessary?
+
+**Hard rules:**
+- **No per-item API calls.** Fetch bulk, filter client-side.
+- **No O(n²) in hot paths.** Use Maps/Sets for lookups, not nested array scans.
+- **No full DOM rebuilds.** Diff or virtualize — never innerHTML entire tables.
+- **No unbounded data structures.** Every map/slice/array must have eviction or size limits.
+- **No expensive work under locks.** Copy data under lock, process outside.
+- **Cache expensive computations.** Invalidate surgically, not globally.
+- **Debounce/coalesce rapid events.** WebSocket messages, scroll, resize — never fire raw.
+
+**If your change touches a hot path (packet rendering, ingest, analytics), include a perf justification in the PR description:** what the complexity is, what the expected scale is, and why it won't degrade.
+
+**Perf claims require proof.** "This is faster" without data is not acceptable. Every PR claiming to fix or improve performance MUST include one of:
+- A benchmark test (before/after timings with realistic data sizes)
+- Profile output or timing measurements (e.g. "renderTableRows: 450ms → 12ms on 30K packets")
+- A test assertion that enforces the perf characteristic (e.g. "filters 30K packets in <50ms")
+No proof = no merge.
+
 ### 1. No commit without tests
 Every change that touches logic MUST have tests. For Go backend: `cd cmd/server && go test ./...` and `cd cmd/ingestor && go test ./...`. For frontend: `node test-packet-filter.js && node test-aging.js && node test-frontend-helpers.js`. If you add new logic, add tests. No exceptions.
 
 ### 2. No commit without browser validation
 After pushing, verify the change works in an actual browser. Use `browser profile=openclaw` against the running instance. Take a screenshot if the change is visual. If you can't validate it, say so — don't claim it works.
 
-### 3. Cache busters — ALWAYS bump them
-Every time you change a `.js` or `.css` file in `public/`, bump the cache buster in `index.html`. This has caused 7 separate production regressions. Use:
-```bash
-NEWV=$(date +%s) && sed -i "s/v=[0-9]*/v=$NEWV/g" public/index.html
-```
-Do this in the SAME commit as the code change, not as a follow-up.
+### 3. Cache busters are automatic — do NOT manually edit them
+Cache busters are injected automatically by the Go server at startup. The `__BUST__` placeholder in `index.html` is replaced with a Unix timestamp when the server reads the file. No manual bumping needed — every server restart picks up new asset versions. Do NOT replace `__BUST__` with hardcoded timestamps.
 
 ### 4. Verify API response shape before building UI
 Before writing client code that consumes an API endpoint, check what the endpoint ACTUALLY returns. Use `curl` or check the server code. Don't assume fields exist — grouped packets (`groupByHash=true`) have different fields than raw packets. This has caused multiple breakages.
@@ -324,7 +347,7 @@ One logical change per commit. Each commit is deployable. Each commit has its te
 
 | Pitfall | Times it happened | Prevention |
 |---------|-------------------|------------|
-| Forgot cache busters | 7 | Always bump in same commit |
+| Forgot cache busters | 7 | Now automatic — `__BUST__` replaced at server startup |
 | Grouped packets missing fields | 3 | curl the actual API first |
 | last_seen vs last_heard mismatch | 4 | Always use `last_heard \|\| last_seen` |
 | CSS selectors don't match SVG | 2 | Manipulate SVG in JS after generation |
@@ -339,6 +362,12 @@ One logical change per commit. Each commit is deployable. Each commit has its te
 - Tests: `test-{feature}.js` in repo root
 - No build step, no transpilation — write ES2020 for server, ES5/6 for frontend (broad browser support)
 
+### Deep Linking
+All new UI states that a user might want to share or bookmark MUST be reflected in the URL hash.
+This includes: tabs, filters, selected items, view modes. Use query parameters on the hash
+(e.g., `#/packets?observer=ABC&timeRange=24h`) for filter state.
+Existing patterns: `#/nodes/{pubkey}?section=node-neighbors`, `#/analytics?tab=collisions`, `#/packets/{hash}`.
+
 ## What NOT to Do
 - **Don't check in private information** — no names, API keys, tokens, passwords, IP addresses, personal data, or any identifying information. This is a PUBLIC repo.
 - Don't add npm dependencies without asking

Dockerfile

@@ -9,6 +9,7 @@ ARG BUILD_TIME=unknown
 # Build server
 WORKDIR /build/server
 COPY cmd/server/go.mod cmd/server/go.sum ./
+COPY internal/geofilter/ ../../internal/geofilter/
 RUN go mod download
 COPY cmd/server/ ./
 RUN go build -ldflags "-X main.Version=${APP_VERSION} -X main.Commit=${GIT_COMMIT} -X main.BuildTime=${BUILD_TIME}" -o /corescope-server .

README.md

@@ -80,7 +80,7 @@ No Go installation needed — everything builds inside the container.
 
 ```bash
 git clone https://github.com/Kpa-clawbot/CoreScope.git
-cd corescope
+cd CoreScope
 ./manage.sh setup
 ```
 

cmd/ingestor/config.go

@@ -5,6 +5,8 @@ import (
 	"fmt"
 	"os"
 	"strings"
+
+	"github.com/meshcore-analyzer/geofilter"
 )
 
 // MQTTSource represents a single MQTT broker connection.
@@ -34,8 +36,12 @@ type Config struct {
 	ChannelKeys     map[string]string `json:"channelKeys,omitempty"`
 	HashChannels    []string          `json:"hashChannels,omitempty"`
 	Retention       *RetentionConfig  `json:"retention,omitempty"`
+	GeoFilter       *GeoFilterConfig  `json:"geo_filter,omitempty"`
 }
 
+// GeoFilterConfig is an alias for the shared geofilter.Config type.
+type GeoFilterConfig = geofilter.Config
+
 // RetentionConfig controls how long stale nodes are kept before being moved to inactive_nodes.
 type RetentionConfig struct {
 	NodeDays int `json:"nodeDays"`

cmd/ingestor/db.go

@@ -36,8 +36,9 @@ type Store struct {
 	stmtUpsertNode           *sql.Stmt
 	stmtIncrementAdvertCount *sql.Stmt
 	stmtUpsertObserver       *sql.Stmt
-	stmtGetObserverRowid     *sql.Stmt
-	stmtUpdateNodeTelemetry  *sql.Stmt
+	stmtGetObserverRowid       *sql.Stmt
+	stmtUpdateObserverLastSeen *sql.Stmt
+	stmtUpdateNodeTelemetry    *sql.Stmt
 }
 
 // OpenStore opens or creates a SQLite DB at the given path, applying the
@@ -280,6 +281,17 @@ func applySchema(db *sql.DB) error {
 		log.Println("[migration] node telemetry columns added")
 	}
 
+	// One-time migration: add timestamp index on observations for fast stats queries.
+	// Older databases created before this index was added suffer from full table scans
+	// on COUNT(*) WHERE timestamp > ?, causing /api/stats to take 30s+.
+	row = db.QueryRow("SELECT 1 FROM _migrations WHERE name = 'obs_timestamp_index_v1'")
+	if row.Scan(&migDone) != nil {
+		log.Println("[migration] Adding timestamp index on observations...")
+		db.Exec(`CREATE INDEX IF NOT EXISTS idx_observations_timestamp ON observations(timestamp)`)
+		db.Exec(`INSERT INTO _migrations (name) VALUES ('obs_timestamp_index_v1')`)
+		log.Println("[migration] observations timestamp index created")
+	}
+
 	return nil
 }
 
@@ -358,6 +370,11 @@ func (s *Store) prepareStatements() error {
 		return err
 	}
 
+	s.stmtUpdateObserverLastSeen, err = s.db.Prepare("UPDATE observers SET last_seen = ? WHERE rowid = ?")
+	if err != nil {
+		return err
+	}
+
 	s.stmtUpdateNodeTelemetry, err = s.db.Prepare(`
 		UPDATE nodes SET
 			battery_mv = COALESCE(?, battery_mv),
@@ -417,13 +434,16 @@ func (s *Store) InsertTransmission(data *PacketData) (bool, error) {
 		s.Stats.DuplicateTransmissions.Add(1)
 	}
 
-	// Resolve observer_idx
+	// Resolve observer_idx and update last_seen
 	var observerIdx *int64
 	if data.ObserverID != "" {
 		var rowid int64
 		err := s.stmtGetObserverRowid.QueryRow(data.ObserverID).Scan(&rowid)
 		if err == nil {
 			observerIdx = &rowid
+			// Update observer last_seen on every packet to prevent
+			// low-traffic observers from appearing offline (#463)
+			_, _ = s.stmtUpdateObserverLastSeen.Exec(now, rowid)
 		}
 	}
 
@@ -434,8 +454,8 @@ func (s *Store) InsertTransmission(data *PacketData) (bool, error) {
 	}
 
 	_, err = s.stmtInsertObservation.Exec(
-		txID, observerIdx, nil, // direction
-		data.SNR, data.RSSI, nil, // score
+		txID, observerIdx, data.Direction,
+		data.SNR, data.RSSI, data.Score,
 		data.PathJSON, epochTs,
 	)
 	if err != nil {
@@ -542,11 +562,22 @@ func (s *Store) UpsertObserver(id, name, iata string, meta *ObserverMeta) error
 	return err
 }
 
-// Close closes the database.
+// Close checkpoints the WAL and closes the database.
 func (s *Store) Close() error {
+	s.Checkpoint()
 	return s.db.Close()
 }
 
+// Checkpoint forces a WAL checkpoint to release the WAL lock file,
+// preventing lock contention with a new process starting up.
+func (s *Store) Checkpoint() {
+	if _, err := s.db.Exec("PRAGMA wal_checkpoint(TRUNCATE)"); err != nil {
+		log.Printf("[db] WAL checkpoint error: %v", err)
+	} else {
+		log.Println("[db] WAL checkpoint complete")
+	}
+}
+
 // LogStats logs current operational metrics.
 func (s *Store) LogStats() {
 	log.Printf("[stats] tx_inserted=%d tx_dupes=%d obs_inserted=%d node_upserts=%d observer_upserts=%d write_errors=%d",
@@ -595,6 +626,8 @@ type PacketData struct {
 	ObserverName   string
 	SNR            *float64
 	RSSI           *float64
+	Score          *float64
+	Direction      *string
 	Hash           string
 	RouteType      int
 	PayloadType    int
@@ -605,10 +638,12 @@ type PacketData struct {
 
 // MQTTPacketMessage is the JSON payload from an MQTT raw packet message.
 type MQTTPacketMessage struct {
-	Raw    string   `json:"raw"`
-	SNR    *float64 `json:"SNR"`
-	RSSI   *float64 `json:"RSSI"`
-	Origin string   `json:"origin"`
+	Raw       string   `json:"raw"`
+	SNR       *float64 `json:"SNR"`
+	RSSI      *float64 `json:"RSSI"`
+	Score     *float64 `json:"score"`
+	Direction *string  `json:"direction"`
+	Origin    string   `json:"origin"`
 }
 
 // BuildPacketData constructs a PacketData from a decoded packet and MQTT message.
@@ -627,6 +662,8 @@ func BuildPacketData(msg *MQTTPacketMessage, decoded *DecodedPacket, observerID,
 		ObserverName:   msg.Origin,
 		SNR:            msg.SNR,
 		RSSI:           msg.RSSI,
+		Score:          msg.Score,
+		Direction:      msg.Direction,
 		Hash:           ComputeContentHash(msg.Raw),
 		RouteType:      decoded.Header.RouteType,
 		PayloadType:    decoded.Header.PayloadType,

cmd/ingestor/db_test.go

@@ -516,6 +516,56 @@ func TestInsertTransmissionWithObserver(t *testing.T) {
 	}
 }
 
+// #463: Verify that inserting a packet updates the observer's last_seen,
+// so low-traffic observers don't incorrectly appear offline.
+func TestInsertTransmissionUpdatesObserverLastSeen(t *testing.T) {
+	s, err := OpenStore(tempDBPath(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+
+	// Insert observer with an old last_seen
+	if err := s.UpsertObserver("obs1", "Observer1", "SJC", nil); err != nil {
+		t.Fatal(err)
+	}
+	// Backdate last_seen to 2 hours ago
+	oldTime := "2026-03-24T22:00:00Z"
+	s.db.Exec("UPDATE observers SET last_seen = ? WHERE id = ?", oldTime, "obs1")
+
+	// Verify it was backdated
+	var lastSeenBefore string
+	s.db.QueryRow("SELECT last_seen FROM observers WHERE id = ?", "obs1").Scan(&lastSeenBefore)
+	if lastSeenBefore != oldTime {
+		t.Fatalf("expected last_seen=%s, got %s", oldTime, lastSeenBefore)
+	}
+
+	// Insert a packet from this observer
+	data := &PacketData{
+		RawHex:      "0A00D69F",
+		Timestamp:   "2026-03-25T01:00:00Z",
+		ObserverID:  "obs1",
+		Hash:        "lastseentest123456",
+		RouteType:   2,
+		PayloadType: 2,
+		PathJSON:    "[]",
+		DecodedJSON: `{"type":"TXT_MSG"}`,
+	}
+	if _, err := s.InsertTransmission(data); err != nil {
+		t.Fatal(err)
+	}
+
+	// Verify last_seen was updated
+	var lastSeenAfter string
+	s.db.QueryRow("SELECT last_seen FROM observers WHERE id = ?", "obs1").Scan(&lastSeenAfter)
+	if lastSeenAfter == oldTime {
+		t.Error("observer last_seen was NOT updated after packet insertion — low-traffic observers will appear offline")
+	}
+	if lastSeenAfter != "2026-03-25T01:00:00Z" {
+		t.Errorf("expected last_seen=2026-03-25T01:00:00Z, got %s", lastSeenAfter)
+	}
+}
+
 func TestEndToEndIngest(t *testing.T) {
 	s, err := OpenStore(tempDBPath(t))
 	if err != nil {
@@ -1313,3 +1363,343 @@ func TestTelemetryMigrationAddsColumns(t *testing.T) {
 		t.Errorf("migration node_telemetry_v1 should be recorded, count=%d", count)
 	}
 }
+
+// --- Bug #320: Observer metadata nested stats ---
+
+func TestExtractObserverMetaNestedStats(t *testing.T) {
+	// Real-world MQTT status payload: stats fields nested under "stats"
+	msg := map[string]interface{}{
+		"status":           "online",
+		"origin":           "ObserverName",
+		"model":            "Heltec V3",
+		"firmware_version": "v1.14.0-9f1a3ea",
+		"stats": map[string]interface{}{
+			"battery_mv":  4174.0,
+			"uptime_secs": 80277.0,
+			"noise_floor": -110.0,
+		},
+	}
+	meta := extractObserverMeta(msg)
+	if meta == nil {
+		t.Fatal("expected non-nil meta")
+	}
+	if meta.Model == nil || *meta.Model != "Heltec V3" {
+		t.Errorf("Model=%v, want Heltec V3", meta.Model)
+	}
+	if meta.Firmware == nil || *meta.Firmware != "v1.14.0-9f1a3ea" {
+		t.Errorf("Firmware=%v, want v1.14.0-9f1a3ea", meta.Firmware)
+	}
+	if meta.BatteryMv == nil || *meta.BatteryMv != 4174 {
+		t.Errorf("BatteryMv=%v, want 4174", meta.BatteryMv)
+	}
+	if meta.UptimeSecs == nil || *meta.UptimeSecs != 80277 {
+		t.Errorf("UptimeSecs=%v, want 80277", meta.UptimeSecs)
+	}
+	if meta.NoiseFloor == nil || *meta.NoiseFloor != -110.0 {
+		t.Errorf("NoiseFloor=%v, want -110", meta.NoiseFloor)
+	}
+}
+
+func TestExtractObserverMetaNestedStatsPrecedence(t *testing.T) {
+	// If stats has a value AND top-level has a value, nested wins
+	msg := map[string]interface{}{
+		"battery_mv":  9999.0, // top-level (stale/wrong)
+		"noise_floor": -120.0, // top-level (stale/wrong)
+		"stats": map[string]interface{}{
+			"battery_mv":  4174.0, // nested (correct)
+			"noise_floor": -110.5, // nested (correct)
+		},
+	}
+	meta := extractObserverMeta(msg)
+	if meta == nil {
+		t.Fatal("expected non-nil meta")
+	}
+	if meta.BatteryMv == nil || *meta.BatteryMv != 4174 {
+		t.Errorf("BatteryMv=%v, want 4174 (nested should win over top-level)", meta.BatteryMv)
+	}
+	if meta.NoiseFloor == nil || *meta.NoiseFloor != -110.5 {
+		t.Errorf("NoiseFloor=%v, want -110.5 (nested should win over top-level)", meta.NoiseFloor)
+	}
+}
+
+func TestExtractObserverMetaFlatFallback(t *testing.T) {
+	// Backward compatibility: flat structure (no stats object) still works
+	msg := map[string]interface{}{
+		"battery_mv":  3500.0,
+		"uptime_secs": 86400.0,
+		"noise_floor": -115.5,
+	}
+	meta := extractObserverMeta(msg)
+	if meta == nil {
+		t.Fatal("expected non-nil meta for flat structure")
+	}
+	if meta.BatteryMv == nil || *meta.BatteryMv != 3500 {
+		t.Errorf("BatteryMv=%v, want 3500", meta.BatteryMv)
+	}
+	if meta.UptimeSecs == nil || *meta.UptimeSecs != 86400 {
+		t.Errorf("UptimeSecs=%v, want 86400", meta.UptimeSecs)
+	}
+	if meta.NoiseFloor == nil || *meta.NoiseFloor != -115.5 {
+		t.Errorf("NoiseFloor=%v, want -115.5", meta.NoiseFloor)
+	}
+}
+
+func TestExtractObserverMetaEmptyStats(t *testing.T) {
+	// Empty stats object should not crash, top-level fallback still applies
+	msg := map[string]interface{}{
+		"model": "T-Beam",
+		"stats": map[string]interface{}{},
+	}
+	meta := extractObserverMeta(msg)
+	if meta == nil {
+		t.Fatal("expected non-nil meta (model is present)")
+	}
+	if meta.Model == nil || *meta.Model != "T-Beam" {
+		t.Errorf("Model=%v, want T-Beam", meta.Model)
+	}
+	if meta.BatteryMv != nil {
+		t.Errorf("BatteryMv should be nil, got %v", *meta.BatteryMv)
+	}
+}
+
+func TestExtractObserverMetaStatsNotAMap(t *testing.T) {
+	// stats field is not a map (e.g., string) — should not crash, fall back to top-level
+	msg := map[string]interface{}{
+		"stats":      "invalid",
+		"battery_mv": 3700.0,
+	}
+	meta := extractObserverMeta(msg)
+	if meta == nil {
+		t.Fatal("expected non-nil meta")
+	}
+	if meta.BatteryMv == nil || *meta.BatteryMv != 3700 {
+		t.Errorf("BatteryMv=%v, want 3700 (top-level fallback when stats is not a map)", meta.BatteryMv)
+	}
+}
+
+func TestExtractObserverMetaNoiseFloorFloat(t *testing.T) {
+	// noise_floor migrated to REAL — verify float precision preserved
+	msg := map[string]interface{}{
+		"stats": map[string]interface{}{
+			"noise_floor": -108.75,
+		},
+	}
+	meta := extractObserverMeta(msg)
+	if meta == nil {
+		t.Fatal("expected non-nil meta")
+	}
+	if meta.NoiseFloor == nil || *meta.NoiseFloor != -108.75 {
+		t.Errorf("NoiseFloor=%v, want -108.75", meta.NoiseFloor)
+	}
+}
+
+func TestExtractObserverMetaNestedNilSkipsTopLevel(t *testing.T) {
+	// JSON {"stats": {"battery_mv": null}} decodes to nil value in the map.
+	// Nested nil should suppress top-level fallback (nested wins semantics).
+	msg := map[string]interface{}{
+		"battery_mv": 3700.0,
+		"stats": map[string]interface{}{
+			"battery_mv": nil,
+		},
+	}
+	meta := extractObserverMeta(msg)
+	if meta != nil && meta.BatteryMv != nil {
+		t.Error("nested nil should suppress top-level fallback")
+	}
+}
+
+func TestObsTimestampIndexMigration(t *testing.T) {
+	// Case 1: new DB — OpenStore should create idx_observations_timestamp as part
+	// of the observations table schema.
+	t.Run("NewDB", func(t *testing.T) {
+		s, err := OpenStore(tempDBPath(t))
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer s.Close()
+
+		var count int
+		err = s.db.QueryRow(
+			"SELECT COUNT(*) FROM sqlite_master WHERE type='index' AND name='idx_observations_timestamp'",
+		).Scan(&count)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if count != 1 {
+			t.Error("idx_observations_timestamp should exist on a new DB")
+		}
+
+		var migCount int
+		err = s.db.QueryRow(
+			"SELECT COUNT(*) FROM _migrations WHERE name='obs_timestamp_index_v1'",
+		).Scan(&migCount)
+		if err != nil {
+			t.Fatal(err)
+		}
+		// On a new DB the index is created inline (not via migration), so the
+		// migration row may or may not be recorded — just verify the index exists.
+		_ = migCount
+	})
+
+	// Case 2: existing DB that has the observations table but lacks the index
+	// and lacks the _migrations entry — simulates an older installation.
+	t.Run("MigrationPath", func(t *testing.T) {
+		path := tempDBPath(t)
+
+		// Build a bare-bones DB that mimics an old installation:
+		// observations table exists but idx_observations_timestamp does NOT.
+		db, err := sql.Open("sqlite", path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, err = db.Exec(`
+			CREATE TABLE IF NOT EXISTS _migrations (name TEXT PRIMARY KEY);
+			CREATE TABLE IF NOT EXISTS transmissions (
+				id INTEGER PRIMARY KEY AUTOINCREMENT,
+				raw_hex TEXT NOT NULL,
+				hash TEXT NOT NULL UNIQUE,
+				first_seen TEXT NOT NULL,
+				route_type INTEGER,
+				payload_type INTEGER,
+				payload_version INTEGER,
+				decoded_json TEXT,
+				created_at TEXT DEFAULT (datetime('now'))
+			);
+			CREATE TABLE IF NOT EXISTS observations (
+				id INTEGER PRIMARY KEY AUTOINCREMENT,
+				transmission_id INTEGER NOT NULL REFERENCES transmissions(id),
+				observer_idx INTEGER,
+				direction TEXT,
+				snr REAL,
+				rssi REAL,
+				score INTEGER,
+				path_json TEXT,
+				timestamp INTEGER NOT NULL
+			);
+		`)
+		if err != nil {
+			db.Close()
+			t.Fatal(err)
+		}
+		// Confirm the index is absent before OpenStore runs.
+		var preCount int
+		db.QueryRow(
+			"SELECT COUNT(*) FROM sqlite_master WHERE type='index' AND name='idx_observations_timestamp'",
+		).Scan(&preCount)
+		db.Close()
+		if preCount != 0 {
+			t.Fatalf("pre-condition failed: idx_observations_timestamp should not exist yet, got count=%d", preCount)
+		}
+
+		// Now open via OpenStore — the migration should add the index.
+		s, err := OpenStore(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer s.Close()
+
+		var idxCount int
+		err = s.db.QueryRow(
+			"SELECT COUNT(*) FROM sqlite_master WHERE type='index' AND name='idx_observations_timestamp'",
+		).Scan(&idxCount)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if idxCount != 1 {
+			t.Error("idx_observations_timestamp should exist after migration on old DB")
+		}
+
+		var migCount int
+		err = s.db.QueryRow(
+			"SELECT COUNT(*) FROM _migrations WHERE name='obs_timestamp_index_v1'",
+		).Scan(&migCount)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if migCount != 1 {
+			t.Errorf("migration obs_timestamp_index_v1 should be recorded, got count=%d", migCount)
+		}
+	})
+}
+
+func TestBuildPacketDataScoreAndDirection(t *testing.T) {
+	rawHex := "0A00D69FD7A5A7475DB07337749AE61FA53A4788E976"
+	decoded, err := DecodePacket(rawHex, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	score := 42.0
+	dir := "incoming"
+	msg := &MQTTPacketMessage{
+		Raw:       rawHex,
+		Score:     &score,
+		Direction: &dir,
+	}
+
+	pkt := BuildPacketData(msg, decoded, "obs1", "SJC")
+	if pkt.Score == nil || *pkt.Score != 42.0 {
+		t.Errorf("Score=%v, want 42.0", pkt.Score)
+	}
+	if pkt.Direction == nil || *pkt.Direction != "incoming" {
+		t.Errorf("Direction=%v, want incoming", pkt.Direction)
+	}
+}
+
+func TestBuildPacketDataNilScoreDirection(t *testing.T) {
+	decoded, _ := DecodePacket("0A00"+strings.Repeat("00", 10), nil)
+	msg := &MQTTPacketMessage{Raw: "0A00" + strings.Repeat("00", 10)}
+	pkt := BuildPacketData(msg, decoded, "", "")
+
+	if pkt.Score != nil {
+		t.Errorf("Score should be nil, got %v", *pkt.Score)
+	}
+	if pkt.Direction != nil {
+		t.Errorf("Direction should be nil, got %v", *pkt.Direction)
+	}
+}
+
+func TestInsertTransmissionWithScoreAndDirection(t *testing.T) {
+	s, err := OpenStore(tempDBPath(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+
+	score := 7.5
+	dir := "outgoing"
+	data := &PacketData{
+		RawHex:    "AABB",
+		Timestamp: "2025-01-01T00:00:00Z",
+		SNR:       ptrFloat(5.0),
+		RSSI:      ptrFloat(-90.0),
+		Score:     &score,
+		Direction: &dir,
+		Hash:      "abc123",
+		PathJSON:  "[]",
+	}
+
+	isNew, err := s.InsertTransmission(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !isNew {
+		t.Error("expected new transmission")
+	}
+
+	// Verify the observation was stored with score and direction
+	var gotDir sql.NullString
+	var gotScore sql.NullFloat64
+	err = s.db.QueryRow("SELECT direction, score FROM observations LIMIT 1").Scan(&gotDir, &gotScore)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !gotDir.Valid || gotDir.String != "outgoing" {
+		t.Errorf("direction=%v, want outgoing", gotDir)
+	}
+	if !gotScore.Valid || gotScore.Float64 != 7.5 {
+		t.Errorf("score=%v, want 7.5", gotScore)
+	}
+}
+
+func ptrFloat(f float64) *float64 { return &f }

cmd/ingestor/geo_filter.go

@@ -0,0 +1,15 @@
+package main
+
+import "github.com/meshcore-analyzer/geofilter"
+
+// NodePassesGeoFilter returns true if the node should be kept.
+// Nodes with no GPS coordinates are always allowed.
+func NodePassesGeoFilter(lat, lon *float64, gf *GeoFilterConfig) bool {
+	if gf == nil {
+		return true
+	}
+	if lat == nil || lon == nil {
+		return true
+	}
+	return geofilter.PassesFilter(*lat, *lon, gf)
+}

cmd/ingestor/go.mod

@@ -4,9 +4,12 @@ go 1.22
 
 require (
 	github.com/eclipse/paho.mqtt.golang v1.5.0
+	github.com/meshcore-analyzer/geofilter v0.0.0
 	modernc.org/sqlite v1.34.5
 )
 
+replace github.com/meshcore-analyzer/geofilter => ../../internal/geofilter
+
 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect

cmd/ingestor/main.go

@@ -14,6 +14,7 @@ import (
 	"os"
 	"os/signal"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"syscall"
 	"time"
@@ -136,7 +137,7 @@ func main() {
 		// Capture source for closure
 		src := source
 		opts.SetDefaultPublishHandler(func(c mqtt.Client, m mqtt.Message) {
-			handleMessage(store, tag, src, m, channelKeys)
+			handleMessage(store, tag, src, m, channelKeys, cfg.GeoFilter)
 		})
 
 		client := mqtt.NewClient(opts)
@@ -165,12 +166,12 @@ func main() {
 	statsTicker.Stop()
 	store.LogStats() // final stats on shutdown
 	for _, c := range clients {
-		c.Disconnect(1000)
+		c.Disconnect(5000) // 5s to allow in-flight messages to drain
 	}
 	log.Println("Done.")
 }
 
-func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message, channelKeys map[string]string) {
+func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message, channelKeys map[string]string, geoFilter *GeoFilterConfig) {
 	defer func() {
 		if r := recover(); r != nil {
 			log.Printf("MQTT [%s] panic in handler: %v", tag, r)
@@ -241,43 +242,75 @@ func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message,
 			if f, ok := toFloat64(v); ok {
 				mqttMsg.SNR = &f
 			}
+		} else if v, ok := msg["snr"]; ok {
+			if f, ok := toFloat64(v); ok {
+				mqttMsg.SNR = &f
+			}
 		}
 		if v, ok := msg["RSSI"]; ok {
 			if f, ok := toFloat64(v); ok {
 				mqttMsg.RSSI = &f
 			}
+		} else if v, ok := msg["rssi"]; ok {
+			if f, ok := toFloat64(v); ok {
+				mqttMsg.RSSI = &f
+			}
+		}
+		if v, ok := msg["score"]; ok {
+			if f, ok := toFloat64(v); ok {
+				mqttMsg.Score = &f
+			}
+		} else if v, ok := msg["Score"]; ok {
+			if f, ok := toFloat64(v); ok {
+				mqttMsg.Score = &f
+			}
+		}
+		if v, ok := msg["direction"].(string); ok {
+			mqttMsg.Direction = &v
+		} else if v, ok := msg["Direction"].(string); ok {
+			mqttMsg.Direction = &v
 		}
 		if v, ok := msg["origin"].(string); ok {
 			mqttMsg.Origin = v
 		}
 
-		pktData := BuildPacketData(mqttMsg, decoded, observerID, region)
-		isNew, err := store.InsertTransmission(pktData)
-		if err != nil {
-			log.Printf("MQTT [%s] db insert error: %v", tag, err)
-		}
-
-		// Process ADVERT → upsert node
+		// For ADVERT packets with known coordinates, enforce geo_filter before
+		// storing anything — drop the entire message if outside the area.
 		if decoded.Header.PayloadTypeName == "ADVERT" && decoded.Payload.PubKey != "" {
 			ok, reason := ValidateAdvert(&decoded.Payload)
-			if ok {
-				role := advertRole(decoded.Payload.Flags)
-				if err := store.UpsertNode(decoded.Payload.PubKey, decoded.Payload.Name, role, decoded.Payload.Lat, decoded.Payload.Lon, pktData.Timestamp); err != nil {
-					log.Printf("MQTT [%s] node upsert error: %v", tag, err)
-				}
-				if isNew {
-					if err := store.IncrementAdvertCount(decoded.Payload.PubKey); err != nil {
-						log.Printf("MQTT [%s] advert count error: %v", tag, err)
-					}
-				}
-				// Update telemetry if present in advert
-				if decoded.Payload.BatteryMv != nil || decoded.Payload.TemperatureC != nil {
-					if err := store.UpdateNodeTelemetry(decoded.Payload.PubKey, decoded.Payload.BatteryMv, decoded.Payload.TemperatureC); err != nil {
-						log.Printf("MQTT [%s] node telemetry update error: %v", tag, err)
-					}
-				}
-			} else {
+			if !ok {
 				log.Printf("MQTT [%s] skipping corrupted ADVERT: %s", tag, reason)
+				return
+			}
+			if !NodePassesGeoFilter(decoded.Payload.Lat, decoded.Payload.Lon, geoFilter) {
+				return
+			}
+			pktData := BuildPacketData(mqttMsg, decoded, observerID, region)
+			isNew, err := store.InsertTransmission(pktData)
+			if err != nil {
+				log.Printf("MQTT [%s] db insert error: %v", tag, err)
+			}
+			role := advertRole(decoded.Payload.Flags)
+			if err := store.UpsertNode(decoded.Payload.PubKey, decoded.Payload.Name, role, decoded.Payload.Lat, decoded.Payload.Lon, pktData.Timestamp); err != nil {
+				log.Printf("MQTT [%s] node upsert error: %v", tag, err)
+			}
+			if isNew {
+				if err := store.IncrementAdvertCount(decoded.Payload.PubKey); err != nil {
+					log.Printf("MQTT [%s] advert count error: %v", tag, err)
+				}
+			}
+			// Update telemetry if present in advert
+			if decoded.Payload.BatteryMv != nil || decoded.Payload.TemperatureC != nil {
+				if err := store.UpdateNodeTelemetry(decoded.Payload.PubKey, decoded.Payload.BatteryMv, decoded.Payload.TemperatureC); err != nil {
+					log.Printf("MQTT [%s] node telemetry update error: %v", tag, err)
+				}
+			}
+		} else {
+			// Non-ADVERT packets: store normally (routing/channel messages from
+			// in-area observers are relevant regardless of relay hop origin).
+			pktData := BuildPacketData(mqttMsg, decoded, observerID, region)
+			if _, err := store.InsertTransmission(pktData); err != nil {
+				log.Printf("MQTT [%s] db insert error: %v", tag, err)
 			}
 		}
 
@@ -333,7 +366,8 @@ func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message,
 		h := sha256.Sum256([]byte(hashInput))
 		hash := hex.EncodeToString(h[:])[:16]
 
-		var snr, rssi *float64
+		var snr, rssi, score *float64
+		var direction *string
 		if v, ok := msg["SNR"]; ok {
 			if f, ok := toFloat64(v); ok {
 				snr = &f
@@ -352,6 +386,20 @@ func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message,
 				rssi = &f
 			}
 		}
+		if v, ok := msg["score"]; ok {
+			if f, ok := toFloat64(v); ok {
+				score = &f
+			}
+		} else if v, ok := msg["Score"]; ok {
+			if f, ok := toFloat64(v); ok {
+				score = &f
+			}
+		}
+		if v, ok := msg["direction"].(string); ok {
+			direction = &v
+		} else if v, ok := msg["Direction"].(string); ok {
+			direction = &v
+		}
 
 		pktData := &PacketData{
 			Timestamp:    now,
@@ -359,6 +407,8 @@ func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message,
 			ObserverName: "L1 Pro (BLE)",
 			SNR:          snr,
 			RSSI:         rssi,
+			Score:        score,
+			Direction:    direction,
 			Hash:         hash,
 			RouteType:    1, // FLOOD
 			PayloadType:  5, // GRP_TXT
@@ -410,7 +460,8 @@ func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message,
 		h := sha256.Sum256([]byte(hashInput))
 		hash := hex.EncodeToString(h[:])[:16]
 
-		var snr, rssi *float64
+		var snr, rssi, score *float64
+		var direction *string
 		if v, ok := msg["SNR"]; ok {
 			if f, ok := toFloat64(v); ok {
 				snr = &f
@@ -429,6 +480,20 @@ func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message,
 				rssi = &f
 			}
 		}
+		if v, ok := msg["score"]; ok {
+			if f, ok := toFloat64(v); ok {
+				score = &f
+			}
+		} else if v, ok := msg["Score"]; ok {
+			if f, ok := toFloat64(v); ok {
+				score = &f
+			}
+		}
+		if v, ok := msg["direction"].(string); ok {
+			direction = &v
+		} else if v, ok := msg["Direction"].(string); ok {
+			direction = &v
+		}
 
 		pktData := &PacketData{
 			Timestamp:    now,
@@ -436,6 +501,8 @@ func handleMessage(store *Store, tag string, source MQTTSource, m mqtt.Message,
 			ObserverName: "L1 Pro (BLE)",
 			SNR:          snr,
 			RSSI:         rssi,
+			Score:        score,
+			Direction:    direction,
 			Hash:         hash,
 			RouteType:    1, // FLOOD
 			PayloadType:  2, // TXT_MSG
@@ -465,11 +532,35 @@ func toFloat64(v interface{}) (float64, bool) {
 	case json.Number:
 		f, err := n.Float64()
 		return f, err == nil
+	case string:
+		s := strings.TrimSpace(n)
+		s = stripUnitSuffix(s)
+		f, err := strconv.ParseFloat(s, 64)
+		return f, err == nil
+	case uint:
+		return float64(n), true
+	case uint64:
+		return float64(n), true
 	default:
 		return 0, false
 	}
 }
 
+// unitSuffixes lists common RF/signal unit suffixes to strip before parsing.
+var unitSuffixes = []string{"dBm", "dB", "mW", "km", "mi", "m"}
+
+// stripUnitSuffix removes a trailing unit suffix (case-insensitive) from a
+// numeric string so that values like "-110dBm" can be parsed as float64.
+func stripUnitSuffix(s string) string {
+	lower := strings.ToLower(s)
+	for _, suffix := range unitSuffixes {
+		if strings.HasSuffix(lower, strings.ToLower(suffix)) {
+			return strings.TrimSpace(s[:len(s)-len(suffix)])
+		}
+	}
+	return s
+}
+
 // extractObserverMeta extracts hardware metadata from an MQTT status message.
 // Casts battery_mv and uptime_secs to integers (they're always whole numbers).
 func extractObserverMeta(msg map[string]interface{}) *ObserverMeta {
@@ -501,21 +592,25 @@ func extractObserverMeta(msg map[string]interface{}) *ObserverMeta {
 		hasData = true
 	}
 
-	if v, ok := msg["battery_mv"]; ok {
+	// Stats fields may be nested under a "stats" object or at top level.
+	// Try nested first, fall back to top-level for backward compatibility.
+	stats, _ := msg["stats"].(map[string]interface{})
+
+	if v := nestedOrTopLevel(stats, msg, "battery_mv"); v != nil {
 		if f, ok := toFloat64(v); ok {
 			iv := int(math.Round(f))
 			meta.BatteryMv = &iv
 			hasData = true
 		}
 	}
-	if v, ok := msg["uptime_secs"]; ok {
+	if v := nestedOrTopLevel(stats, msg, "uptime_secs"); v != nil {
 		if f, ok := toFloat64(v); ok {
 			iv := int64(math.Round(f))
 			meta.UptimeSecs = &iv
 			hasData = true
 		}
 	}
-	if v, ok := msg["noise_floor"]; ok {
+	if v := nestedOrTopLevel(stats, msg, "noise_floor"); v != nil {
 		if f, ok := toFloat64(v); ok {
 			meta.NoiseFloor = &f
 			hasData = true
@@ -528,6 +623,19 @@ func extractObserverMeta(msg map[string]interface{}) *ObserverMeta {
 	return meta
 }
 
+// nestedOrTopLevel looks up a key in the nested map first, then the top-level map.
+func nestedOrTopLevel(nested, toplevel map[string]interface{}, key string) interface{} {
+	if nested != nil {
+		if v, ok := nested[key]; ok {
+			return v
+		}
+	}
+	if v, ok := toplevel[key]; ok {
+		return v
+	}
+	return nil
+}
+
 func firstNonEmpty(vals ...string) string {
 	for _, v := range vals {
 		if v != "" {

cmd/ingestor/main_test.go

@@ -22,7 +22,13 @@ func TestToFloat64(t *testing.T) {
 		{"int64", int64(100), 100.0, true},
 		{"json.Number valid", json.Number("9.5"), 9.5, true},
 		{"json.Number invalid", json.Number("not_a_number"), 0, false},
-		{"string unsupported", "hello", 0, false},
+		{"string valid", "3.14", 3.14, true},
+		{"string with spaces", "  -7.5  ", -7.5, true},
+		{"string integer", "42", 42.0, true},
+		{"string invalid", "hello", 0, false},
+		{"string empty", "", 0, false},
+		{"uint", uint(10), 10.0, true},
+		{"uint64", uint64(999), 999.0, true},
 		{"bool unsupported", true, 0, false},
 		{"nil unsupported", nil, 0, false},
 		{"slice unsupported", []int{1}, 0, false},
@@ -124,7 +130,7 @@ func TestHandleMessageRawPacket(t *testing.T) {
 	payload := []byte(`{"raw":"` + rawHex + `","SNR":5.5,"RSSI":-100.0,"origin":"myobs"}`)
 	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
 
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -141,7 +147,7 @@ func TestHandleMessageRawPacketAdvert(t *testing.T) {
 	payload := []byte(`{"raw":"` + rawHex + `"}`)
 	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
 
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	// Should create a node from the ADVERT
 	var count int
@@ -163,7 +169,7 @@ func TestHandleMessageInvalidJSON(t *testing.T) {
 	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: []byte(`not json`)}
 
 	// Should not panic
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -177,13 +183,13 @@ func TestHandleMessageStatusTopic(t *testing.T) {
 	source := MQTTSource{Name: "test"}
 	msg := &mockMessage{
 		topic:   "meshcore/SJC/obs1/status",
-		payload: []byte(`{"origin":"MyObserver","model":"L1","firmware_version":"v1.2.3","client_version":"2.4.1","radio":"SX1262"}`),
+		payload: []byte(`{"origin":"MyObserver"}`),
 	}
 
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
-	var name, iata, model, firmware, clientVersion, radio string
-	err := store.db.QueryRow("SELECT name, iata, model, firmware, client_version, radio FROM observers WHERE id = 'obs1'").Scan(&name, &iata, &model, &firmware, &clientVersion, &radio)
+	var name, iata string
+	err := store.db.QueryRow("SELECT name, iata FROM observers WHERE id = 'obs1'").Scan(&name, &iata)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -193,39 +199,6 @@ func TestHandleMessageStatusTopic(t *testing.T) {
 	if iata != "SJC" {
 		t.Errorf("iata=%s, want SJC", iata)
 	}
-	if model != "L1" {
-		t.Errorf("model=%s, want L1", model)
-	}
-	if firmware != "v1.2.3" {
-		t.Errorf("firmware=%s, want v1.2.3", firmware)
-	}
-	if clientVersion != "2.4.1" {
-		t.Errorf("client_version=%s, want 2.4.1", clientVersion)
-	}
-	if radio != "SX1262" {
-		t.Errorf("radio=%s, want SX1262", radio)
-	}
-}
-
-func TestHandleMessageStatusTopicMissingIdentityFields(t *testing.T) {
-	store := newTestStore(t)
-	source := MQTTSource{Name: "test"}
-	msg := &mockMessage{
-		topic:   "meshcore/SJC/obs1/status",
-		payload: []byte(`{"origin":"MyObserver","battery_mv":3500}`),
-	}
-
-	handleMessage(store, "test", source, msg, nil)
-
-	var model, firmware, clientVersion, radio interface{}
-	err := store.db.QueryRow("SELECT model, firmware, client_version, radio FROM observers WHERE id = 'obs1'").
-		Scan(&model, &firmware, &clientVersion, &radio)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if model != nil || firmware != nil || clientVersion != nil || radio != nil {
-		t.Errorf("identity fields should remain NULL when absent: model=%v firmware=%v client_version=%v radio=%v", model, firmware, clientVersion, radio)
-	}
 }
 
 func TestHandleMessageSkipStatusTopics(t *testing.T) {
@@ -234,11 +207,11 @@ func TestHandleMessageSkipStatusTopics(t *testing.T) {
 
 	// meshcore/status should be skipped
 	msg1 := &mockMessage{topic: "meshcore/status", payload: []byte(`{"raw":"0A00"}`)}
-	handleMessage(store, "test", source, msg1, nil)
+	handleMessage(store, "test", source, msg1, nil, nil)
 
 	// meshcore/events/connection should be skipped
 	msg2 := &mockMessage{topic: "meshcore/events/connection", payload: []byte(`{"raw":"0A00"}`)}
-	handleMessage(store, "test", source, msg2, nil)
+	handleMessage(store, "test", source, msg2, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -257,7 +230,7 @@ func TestHandleMessageIATAFilter(t *testing.T) {
 		topic:   "meshcore/SJC/obs1/packets",
 		payload: []byte(`{"raw":"` + rawHex + `"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -270,7 +243,7 @@ func TestHandleMessageIATAFilter(t *testing.T) {
 		topic:   "meshcore/LAX/obs2/packets",
 		payload: []byte(`{"raw":"` + rawHex + `"}`),
 	}
-	handleMessage(store, "test", source, msg2, nil)
+	handleMessage(store, "test", source, msg2, nil, nil)
 
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
 	if count != 1 {
@@ -288,7 +261,7 @@ func TestHandleMessageIATAFilterNoRegion(t *testing.T) {
 		topic:   "meshcore",
 		payload: []byte(`{"raw":"` + rawHex + `"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	// No region part → filter doesn't apply, message goes through
 	// Actually the code checks len(parts) > 1 for IATA filter
@@ -304,7 +277,7 @@ func TestHandleMessageNoRawHex(t *testing.T) {
 		topic:   "meshcore/SJC/obs1/packets",
 		payload: []byte(`{"type":"companion","data":"something"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -322,7 +295,7 @@ func TestHandleMessageBadRawHex(t *testing.T) {
 		topic:   "meshcore/SJC/obs1/packets",
 		payload: []byte(`{"raw":"ZZZZ"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -339,7 +312,7 @@ func TestHandleMessageWithSNRRSSIAsNumbers(t *testing.T) {
 	payload := []byte(`{"raw":"` + rawHex + `","SNR":7.2,"RSSI":-95}`)
 	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
 
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var snr, rssi *float64
 	store.db.QueryRow("SELECT snr, rssi FROM observations LIMIT 1").Scan(&snr, &rssi)
@@ -358,7 +331,7 @@ func TestHandleMessageMinimalTopic(t *testing.T) {
 		topic:   "meshcore/SJC",
 		payload: []byte(`{"raw":"` + rawHex + `"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -379,7 +352,7 @@ func TestHandleMessageCorruptedAdvert(t *testing.T) {
 		topic:   "meshcore/SJC/obs1/packets",
 		payload: []byte(`{"raw":"` + rawHex + `"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	// Transmission should be inserted (even if advert is invalid)
 	var count int
@@ -405,7 +378,7 @@ func TestHandleMessageNoObserverID(t *testing.T) {
 		topic:   "packets",
 		payload: []byte(`{"raw":"` + rawHex + `","origin":"obs1"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -427,7 +400,7 @@ func TestHandleMessageSNRNotFloat(t *testing.T) {
 	// SNR as a string value — should not parse as float
 	payload := []byte(`{"raw":"` + rawHex + `","SNR":"bad","RSSI":"bad"}`)
 	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var count int
 	store.db.QueryRow("SELECT COUNT(*) FROM transmissions").Scan(&count)
@@ -443,7 +416,7 @@ func TestHandleMessageOriginExtraction(t *testing.T) {
 	rawHex := "0A00D69FD7A5A7475DB07337749AE61FA53A4788E976"
 	payload := []byte(`{"raw":"` + rawHex + `","origin":"MyOrigin"}`)
 	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	// Verify origin was extracted to observer name
 	var name string
@@ -466,7 +439,7 @@ func TestHandleMessagePanicRecovery(t *testing.T) {
 	}
 
 	// Should not panic — the defer/recover should catch it
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 }
 
 func TestHandleMessageStatusOriginFallback(t *testing.T) {
@@ -478,7 +451,7 @@ func TestHandleMessageStatusOriginFallback(t *testing.T) {
 		topic:   "meshcore/SJC/obs1/status",
 		payload: []byte(`{"type":"status"}`),
 	}
-	handleMessage(store, "test", source, msg, nil)
+	handleMessage(store, "test", source, msg, nil, nil)
 
 	var name string
 	err := store.db.QueryRow("SELECT name FROM observers WHERE id = 'obs1'").Scan(&name)
@@ -656,3 +629,113 @@ func TestLoadChannelKeysSkipExplicit(t *testing.T) {
 		t.Errorf("#General = %q, want my_explicit_key", keys["#General"])
 	}
 }
+
+// --- Bug #321: SNR/RSSI case-insensitive fallback ---
+
+func TestHandleMessageWithLowercaseSNRRSSI(t *testing.T) {
+	store := newTestStore(t)
+	source := MQTTSource{Name: "test"}
+
+	rawHex := "0A00D69FD7A5A7475DB07337749AE61FA53A4788E976"
+	payload := []byte(`{"raw":"` + rawHex + `","snr":5.5,"rssi":-102}`)
+	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
+
+	handleMessage(store, "test", source, msg, nil, nil)
+
+	var snr, rssi *float64
+	store.db.QueryRow("SELECT snr, rssi FROM observations LIMIT 1").Scan(&snr, &rssi)
+	if snr == nil || *snr != 5.5 {
+		t.Errorf("snr=%v, want 5.5 (lowercase key)", snr)
+	}
+	if rssi == nil || *rssi != -102 {
+		t.Errorf("rssi=%v, want -102 (lowercase key)", rssi)
+	}
+}
+
+func TestHandleMessageSNRRSSIUppercaseWins(t *testing.T) {
+	store := newTestStore(t)
+	source := MQTTSource{Name: "test"}
+
+	// Both uppercase and lowercase present — uppercase should take precedence
+	rawHex := "0A00D69FD7A5A7475DB07337749AE61FA53A4788E976"
+	payload := []byte(`{"raw":"` + rawHex + `","SNR":7.2,"snr":1.0,"RSSI":-95,"rssi":-50}`)
+	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
+
+	handleMessage(store, "test", source, msg, nil, nil)
+
+	var snr, rssi *float64
+	store.db.QueryRow("SELECT snr, rssi FROM observations LIMIT 1").Scan(&snr, &rssi)
+	if snr == nil || *snr != 7.2 {
+		t.Errorf("snr=%v, want 7.2 (uppercase should take precedence)", snr)
+	}
+	if rssi == nil || *rssi != -95 {
+		t.Errorf("rssi=%v, want -95 (uppercase should take precedence)", rssi)
+	}
+}
+
+func TestHandleMessageNoSNRRSSI(t *testing.T) {
+	store := newTestStore(t)
+	source := MQTTSource{Name: "test"}
+
+	rawHex := "0A00D69FD7A5A7475DB07337749AE61FA53A4788E976"
+	payload := []byte(`{"raw":"` + rawHex + `"}`)
+	msg := &mockMessage{topic: "meshcore/SJC/obs1/packets", payload: payload}
+
+	handleMessage(store, "test", source, msg, nil, nil)
+
+	var snr, rssi *float64
+	store.db.QueryRow("SELECT snr, rssi FROM observations LIMIT 1").Scan(&snr, &rssi)
+	if snr != nil {
+		t.Errorf("snr should be nil when not present, got %v", *snr)
+	}
+	if rssi != nil {
+		t.Errorf("rssi should be nil when not present, got %v", *rssi)
+	}
+}
+
+func TestStripUnitSuffix(t *testing.T) {
+	tests := []struct {
+		input, want string
+	}{
+		{"-110dBm", "-110"},
+		{"-110DBM", "-110"},
+		{"5.5dB", "5.5"},
+		{"100mW", "100"},
+		{"1.5km", "1.5"},
+		{"500m", "500"},
+		{"10mi", "10"},
+		{"42", "42"},
+		{"", ""},
+		{"hello", "hello"},
+	}
+	for _, tt := range tests {
+		got := stripUnitSuffix(tt.input)
+		if got != tt.want {
+			t.Errorf("stripUnitSuffix(%q) = %q, want %q", tt.input, got, tt.want)
+		}
+	}
+}
+
+func TestToFloat64WithUnits(t *testing.T) {
+	tests := []struct {
+		input interface{}
+		want  float64
+		ok    bool
+	}{
+		{"-110dBm", -110.0, true},
+		{"5.5dB", 5.5, true},
+		{"100mW", 100.0, true},
+		{"-85.3dBm", -85.3, true},
+		{"42", 42.0, true},
+		{"not_a_number", 0, false},
+	}
+	for _, tt := range tests {
+		got, ok := toFloat64(tt.input)
+		if ok != tt.ok {
+			t.Errorf("toFloat64(%v) ok=%v, want %v", tt.input, ok, tt.ok)
+		}
+		if ok && got != tt.want {
+			t.Errorf("toFloat64(%v) = %v, want %v", tt.input, got, tt.want)
+		}
+	}
+}

cmd/server/advert_pubkey_test.go

@@ -0,0 +1,181 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"testing"
+)
+
+// TestAdvertPubkeyTracking verifies that advertPubkeys is maintained
+// incrementally during ingest and eviction, and that GetPerfStoreStats
+// returns the correct count without per-request JSON parsing.
+func TestAdvertPubkeyTracking(t *testing.T) {
+	ps := NewPacketStore(nil, nil)
+	ps.mu.Lock()
+
+	// Helper to create an ADVERT StoreTx with a given pubkey.
+	pt4 := 4
+	mkAdvert := func(id int, pubkey string) *StoreTx {
+		d := map[string]interface{}{"pubKey": pubkey}
+		j, _ := json.Marshal(d)
+		return &StoreTx{
+			ID:          id,
+			Hash:        fmt.Sprintf("hash%d", id),
+			PayloadType: &pt4,
+			DecodedJSON: string(j),
+		}
+	}
+
+	// Add 3 adverts: 2 distinct pubkeys
+	tx1 := mkAdvert(1, "pk_alpha")
+	tx2 := mkAdvert(2, "pk_beta")
+	tx3 := mkAdvert(3, "pk_alpha") // duplicate pubkey
+
+	for _, tx := range []*StoreTx{tx1, tx2, tx3} {
+		ps.packets = append(ps.packets, tx)
+		ps.byHash[tx.Hash] = tx
+		ps.byTxID[tx.ID] = tx
+		ps.byPayloadType[4] = append(ps.byPayloadType[4], tx)
+		ps.trackAdvertPubkey(tx)
+	}
+	ps.mu.Unlock()
+
+	// GetPerfStoreStats should report 2 distinct pubkeys
+	stats := ps.GetPerfStoreStats()
+	indexes := stats["indexes"].(map[string]interface{})
+	got := indexes["advertByObserver"].(int)
+	if got != 2 {
+		t.Errorf("advertByObserver = %d, want 2", got)
+	}
+
+	// GetPerfStoreStatsTyped should agree
+	typed := ps.GetPerfStoreStatsTyped()
+	if typed.Indexes.AdvertByObserver != 2 {
+		t.Errorf("typed AdvertByObserver = %d, want 2", typed.Indexes.AdvertByObserver)
+	}
+
+	// Evict tx3 (pk_alpha duplicate) — count should stay 2
+	ps.mu.Lock()
+	ps.untrackAdvertPubkey(tx3)
+	ps.mu.Unlock()
+
+	stats2 := ps.GetPerfStoreStats()
+	idx2 := stats2["indexes"].(map[string]interface{})
+	if idx2["advertByObserver"].(int) != 2 {
+		t.Errorf("after evicting duplicate: advertByObserver = %d, want 2", idx2["advertByObserver"].(int))
+	}
+
+	// Evict tx1 (last pk_alpha) — count should drop to 1
+	ps.mu.Lock()
+	ps.untrackAdvertPubkey(tx1)
+	ps.mu.Unlock()
+
+	stats3 := ps.GetPerfStoreStats()
+	idx3 := stats3["indexes"].(map[string]interface{})
+	if idx3["advertByObserver"].(int) != 1 {
+		t.Errorf("after evicting last pk_alpha: advertByObserver = %d, want 1", idx3["advertByObserver"].(int))
+	}
+
+	// Evict tx2 (last remaining) — count should be 0
+	ps.mu.Lock()
+	ps.untrackAdvertPubkey(tx2)
+	ps.mu.Unlock()
+
+	stats4 := ps.GetPerfStoreStats()
+	idx4 := stats4["indexes"].(map[string]interface{})
+	if idx4["advertByObserver"].(int) != 0 {
+		t.Errorf("after evicting all: advertByObserver = %d, want 0", idx4["advertByObserver"].(int))
+	}
+}
+
+// TestAdvertPubkeyPublicKeyField tests the "public_key" JSON field variant.
+func TestAdvertPubkeyPublicKeyField(t *testing.T) {
+	ps := NewPacketStore(nil, nil)
+	ps.mu.Lock()
+	pt4 := 4
+	d, _ := json.Marshal(map[string]interface{}{"public_key": "pk_legacy"})
+	tx := &StoreTx{ID: 1, Hash: "h1", PayloadType: &pt4, DecodedJSON: string(d)}
+	ps.trackAdvertPubkey(tx)
+	ps.mu.Unlock()
+
+	stats := ps.GetPerfStoreStats()
+	idx := stats["indexes"].(map[string]interface{})
+	if idx["advertByObserver"].(int) != 1 {
+		t.Errorf("public_key field: advertByObserver = %d, want 1", idx["advertByObserver"].(int))
+	}
+}
+
+// TestAdvertPubkeyNonAdvert ensures non-ADVERT packets don't affect the count.
+func TestAdvertPubkeyNonAdvert(t *testing.T) {
+	ps := NewPacketStore(nil, nil)
+	ps.mu.Lock()
+	pt2 := 2
+	d, _ := json.Marshal(map[string]interface{}{"pubKey": "pk_text"})
+	tx := &StoreTx{ID: 1, Hash: "h1", PayloadType: &pt2, DecodedJSON: string(d)}
+	ps.trackAdvertPubkey(tx)
+	ps.mu.Unlock()
+
+	stats := ps.GetPerfStoreStats()
+	idx := stats["indexes"].(map[string]interface{})
+	if idx["advertByObserver"].(int) != 0 {
+		t.Errorf("non-ADVERT should not be tracked: advertByObserver = %d, want 0", idx["advertByObserver"].(int))
+	}
+}
+
+// BenchmarkGetPerfStoreStats benchmarks the perf stats endpoint with many adverts.
+// Before the fix, this did O(N) JSON unmarshals per call.
+// After the fix, it's O(1) — just len(map).
+func BenchmarkGetPerfStoreStats(b *testing.B) {
+	ps := NewPacketStore(nil, nil)
+	ps.mu.Lock()
+	pt4 := 4
+	for i := 0; i < 5000; i++ {
+		pk := fmt.Sprintf("pk_%04d", i%200) // 200 distinct pubkeys
+		d, _ := json.Marshal(map[string]interface{}{"pubKey": pk})
+		tx := &StoreTx{
+			ID:          i + 1,
+			Hash:        fmt.Sprintf("hash%d", i+1),
+			PayloadType: &pt4,
+			DecodedJSON: string(d),
+		}
+		ps.packets = append(ps.packets, tx)
+		ps.byHash[tx.Hash] = tx
+		ps.byTxID[tx.ID] = tx
+		ps.byPayloadType[4] = append(ps.byPayloadType[4], tx)
+		ps.trackAdvertPubkey(tx)
+	}
+	ps.mu.Unlock()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		ps.GetPerfStoreStats()
+	}
+}
+
+// BenchmarkGetPerfStoreStatsTyped benchmarks the typed variant.
+func BenchmarkGetPerfStoreStatsTyped(b *testing.B) {
+	ps := NewPacketStore(nil, nil)
+	ps.mu.Lock()
+	pt4 := 4
+	for i := 0; i < 5000; i++ {
+		pk := fmt.Sprintf("pk_%04d", i%200)
+		d, _ := json.Marshal(map[string]interface{}{"pubKey": pk})
+		tx := &StoreTx{
+			ID:          i + 1,
+			Hash:        fmt.Sprintf("hash%d", i+1),
+			PayloadType: &pt4,
+			DecodedJSON: string(d),
+		}
+		ps.packets = append(ps.packets, tx)
+		ps.byHash[tx.Hash] = tx
+		ps.byTxID[tx.ID] = tx
+		ps.byPayloadType[4] = append(ps.byPayloadType[4], tx)
+		ps.trackAdvertPubkey(tx)
+	}
+	ps.mu.Unlock()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		ps.GetPerfStoreStatsTyped()
+	}
+}

cmd/server/cache_invalidation_test.go

@@ -0,0 +1,333 @@
+package main
+
+import (
+	"testing"
+	"time"
+)
+
+// newTestStore creates a minimal PacketStore for cache invalidation testing.
+func newTestStore(t *testing.T) *PacketStore {
+	t.Helper()
+	return &PacketStore{
+		rfCache:      make(map[string]*cachedResult),
+		topoCache:    make(map[string]*cachedResult),
+		hashCache:    make(map[string]*cachedResult),
+		chanCache:    make(map[string]*cachedResult),
+		distCache:    make(map[string]*cachedResult),
+		subpathCache: make(map[string]*cachedResult),
+		rfCacheTTL:   15 * time.Second,
+		invCooldown:  10 * time.Second,
+	}
+}
+
+// populateAllCaches fills every analytics cache with a dummy entry so tests
+// can verify which caches are cleared and which are preserved.
+func populateAllCaches(s *PacketStore) {
+	s.cacheMu.Lock()
+	defer s.cacheMu.Unlock()
+	dummy := &cachedResult{data: map[string]interface{}{"test": true}, expiresAt: time.Now().Add(time.Hour)}
+	s.rfCache["global"] = dummy
+	s.topoCache["global"] = dummy
+	s.hashCache["global"] = dummy
+	s.chanCache["global"] = dummy
+	s.distCache["global"] = dummy
+	s.subpathCache["global"] = dummy
+}
+
+// cachePopulated returns which caches still have their "global" entry.
+func cachePopulated(s *PacketStore) map[string]bool {
+	s.cacheMu.Lock()
+	defer s.cacheMu.Unlock()
+	return map[string]bool{
+		"rf":      len(s.rfCache) > 0,
+		"topo":    len(s.topoCache) > 0,
+		"hash":    len(s.hashCache) > 0,
+		"chan":     len(s.chanCache) > 0,
+		"dist":    len(s.distCache) > 0,
+		"subpath": len(s.subpathCache) > 0,
+	}
+}
+
+func TestInvalidateCachesFor_Eviction(t *testing.T) {
+	s := newTestStore(t)
+	populateAllCaches(s)
+
+	s.invalidateCachesFor(cacheInvalidation{eviction: true})
+
+	pop := cachePopulated(s)
+	for name, has := range pop {
+		if has {
+			t.Errorf("eviction should clear %s cache", name)
+		}
+	}
+}
+
+func TestInvalidateCachesFor_NewObservationsOnly(t *testing.T) {
+	s := newTestStore(t)
+	populateAllCaches(s)
+
+	s.invalidateCachesFor(cacheInvalidation{hasNewObservations: true})
+
+	pop := cachePopulated(s)
+	if pop["rf"] {
+		t.Error("rf cache should be cleared on new observations")
+	}
+	// These should be preserved
+	for _, name := range []string{"topo", "hash", "chan", "dist", "subpath"} {
+		if !pop[name] {
+			t.Errorf("%s cache should NOT be cleared on observation-only ingest", name)
+		}
+	}
+}
+
+func TestInvalidateCachesFor_NewTransmissionsOnly(t *testing.T) {
+	s := newTestStore(t)
+	populateAllCaches(s)
+
+	s.invalidateCachesFor(cacheInvalidation{hasNewTransmissions: true})
+
+	pop := cachePopulated(s)
+	if pop["hash"] {
+		t.Error("hash cache should be cleared on new transmissions")
+	}
+	for _, name := range []string{"rf", "topo", "chan", "dist", "subpath"} {
+		if !pop[name] {
+			t.Errorf("%s cache should NOT be cleared on transmission-only ingest", name)
+		}
+	}
+}
+
+func TestInvalidateCachesFor_ChannelDataOnly(t *testing.T) {
+	s := newTestStore(t)
+	populateAllCaches(s)
+
+	s.invalidateCachesFor(cacheInvalidation{hasChannelData: true})
+
+	pop := cachePopulated(s)
+	if pop["chan"] {
+		t.Error("chan cache should be cleared on channel data")
+	}
+	for _, name := range []string{"rf", "topo", "hash", "dist", "subpath"} {
+		if !pop[name] {
+			t.Errorf("%s cache should NOT be cleared on channel-data-only ingest", name)
+		}
+	}
+}
+
+func TestInvalidateCachesFor_NewPaths(t *testing.T) {
+	s := newTestStore(t)
+	populateAllCaches(s)
+
+	s.invalidateCachesFor(cacheInvalidation{hasNewPaths: true})
+
+	pop := cachePopulated(s)
+	for _, name := range []string{"topo", "dist", "subpath"} {
+		if pop[name] {
+			t.Errorf("%s cache should be cleared on new paths", name)
+		}
+	}
+	for _, name := range []string{"rf", "hash", "chan"} {
+		if !pop[name] {
+			t.Errorf("%s cache should NOT be cleared on path-only ingest", name)
+		}
+	}
+}
+
+func TestInvalidateCachesFor_CombinedFlags(t *testing.T) {
+	s := newTestStore(t)
+	populateAllCaches(s)
+
+	// Simulate a typical ingest: new transmissions with observations but no GRP_TXT
+	s.invalidateCachesFor(cacheInvalidation{
+		hasNewObservations:  true,
+		hasNewTransmissions: true,
+		hasNewPaths:         true,
+	})
+
+	pop := cachePopulated(s)
+	// rf, topo, hash, dist, subpath should all be cleared
+	for _, name := range []string{"rf", "topo", "hash", "dist", "subpath"} {
+		if pop[name] {
+			t.Errorf("%s cache should be cleared with combined flags", name)
+		}
+	}
+	// chan should be preserved (no GRP_TXT)
+	if !pop["chan"] {
+		t.Error("chan cache should NOT be cleared without hasChannelData flag")
+	}
+}
+
+func TestInvalidateCachesFor_NoFlags(t *testing.T) {
+	s := newTestStore(t)
+	populateAllCaches(s)
+
+	s.invalidateCachesFor(cacheInvalidation{})
+
+	pop := cachePopulated(s)
+	for name, has := range pop {
+		if !has {
+			t.Errorf("%s cache should be preserved when no flags are set", name)
+		}
+	}
+}
+
+// TestInvalidationRateLimited verifies that rapid ingest cycles don't clear
+// caches immediately — they accumulate dirty flags during the cooldown period
+// and apply them on the next call after cooldown expires (fixes #533).
+func TestInvalidationRateLimited(t *testing.T) {
+	s := newTestStore(t)
+	s.invCooldown = 100 * time.Millisecond // short cooldown for testing
+
+	// First invalidation should go through immediately
+	populateAllCaches(s)
+	s.invalidateCachesFor(cacheInvalidation{hasNewObservations: true})
+	state := cachePopulated(s)
+	if state["rf"] {
+		t.Error("rf cache should be cleared on first invalidation")
+	}
+	if !state["topo"] {
+		t.Error("topo cache should survive (no path changes)")
+	}
+
+	// Repopulate and call again within cooldown — should NOT clear
+	populateAllCaches(s)
+	s.invalidateCachesFor(cacheInvalidation{hasNewObservations: true})
+	state = cachePopulated(s)
+	if !state["rf"] {
+		t.Error("rf cache should survive during cooldown period")
+	}
+
+	// Wait for cooldown to expire
+	time.Sleep(150 * time.Millisecond)
+
+	// Next call should apply accumulated + current flags
+	populateAllCaches(s)
+	s.invalidateCachesFor(cacheInvalidation{hasNewPaths: true})
+	state = cachePopulated(s)
+	if state["rf"] {
+		t.Error("rf cache should be cleared (pending from cooldown)")
+	}
+	if state["topo"] {
+		t.Error("topo cache should be cleared (current call has hasNewPaths)")
+	}
+	if !state["hash"] {
+		t.Error("hash cache should survive (no transmission changes)")
+	}
+}
+
+// TestInvalidationCooldownAccumulatesFlags verifies that multiple calls during
+// cooldown merge their flags correctly.
+func TestInvalidationCooldownAccumulatesFlags(t *testing.T) {
+	s := newTestStore(t)
+	s.invCooldown = 200 * time.Millisecond
+
+	// Initial invalidation (goes through, starts cooldown)
+	s.invalidateCachesFor(cacheInvalidation{hasNewObservations: true})
+
+	// Several calls during cooldown with different flags
+	s.invalidateCachesFor(cacheInvalidation{hasNewPaths: true})
+	s.invalidateCachesFor(cacheInvalidation{hasNewTransmissions: true})
+	s.invalidateCachesFor(cacheInvalidation{hasChannelData: true})
+
+	// Verify pending has all flags
+	s.cacheMu.Lock()
+	if s.pendingInv == nil {
+		t.Fatal("pendingInv should not be nil during cooldown")
+	}
+	if !s.pendingInv.hasNewPaths || !s.pendingInv.hasNewTransmissions || !s.pendingInv.hasChannelData {
+		t.Error("all flags should be accumulated in pendingInv")
+	}
+	// hasNewObservations was applied immediately, not accumulated
+	if s.pendingInv.hasNewObservations {
+		t.Error("hasNewObservations was already applied, should not be in pending")
+	}
+	s.cacheMu.Unlock()
+
+	// Wait for cooldown, then trigger — all accumulated flags should apply
+	time.Sleep(250 * time.Millisecond)
+	populateAllCaches(s)
+	s.invalidateCachesFor(cacheInvalidation{}) // empty trigger
+	state := cachePopulated(s)
+
+	// Pending had paths, transmissions, channels — all those caches should clear
+	if state["topo"] {
+		t.Error("topo should be cleared (pending hasNewPaths)")
+	}
+	if state["hash"] {
+		t.Error("hash should be cleared (pending hasNewTransmissions)")
+	}
+	if state["chan"] {
+		t.Error("chan should be cleared (pending hasChannelData)")
+	}
+}
+
+// TestEvictionBypassesCooldown verifies eviction always clears immediately.
+func TestEvictionBypassesCooldown(t *testing.T) {
+	s := newTestStore(t)
+	s.invCooldown = 10 * time.Second // long cooldown
+
+	// Start cooldown
+	s.invalidateCachesFor(cacheInvalidation{hasNewObservations: true})
+
+	// Eviction during cooldown should still clear everything
+	populateAllCaches(s)
+	s.invalidateCachesFor(cacheInvalidation{eviction: true})
+	state := cachePopulated(s)
+	for name, has := range state {
+		if has {
+			t.Errorf("%s cache should be cleared on eviction even during cooldown", name)
+		}
+	}
+	// pendingInv should be cleared
+	s.cacheMu.Lock()
+	if s.pendingInv != nil {
+		t.Error("pendingInv should be nil after eviction")
+	}
+	s.cacheMu.Unlock()
+}
+
+// BenchmarkCacheHitDuringIngestion simulates rapid ingestion and verifies
+// that cache hits now occur thanks to rate-limited invalidation.
+func BenchmarkCacheHitDuringIngestion(b *testing.B) {
+	s := &PacketStore{
+		rfCache:      make(map[string]*cachedResult),
+		topoCache:    make(map[string]*cachedResult),
+		hashCache:    make(map[string]*cachedResult),
+		chanCache:    make(map[string]*cachedResult),
+		distCache:    make(map[string]*cachedResult),
+		subpathCache: make(map[string]*cachedResult),
+		rfCacheTTL:   15 * time.Second,
+		invCooldown:  50 * time.Millisecond,
+	}
+
+	// Trigger first invalidation to start cooldown timer
+	s.invalidateCachesFor(cacheInvalidation{hasNewObservations: true})
+
+	var hits, misses int64
+	for i := 0; i < b.N; i++ {
+		// Populate cache (simulates an analytics query filling the cache)
+		s.cacheMu.Lock()
+		s.rfCache["global"] = &cachedResult{
+			data:      map[string]interface{}{"test": true},
+			expiresAt: time.Now().Add(time.Hour),
+		}
+		s.cacheMu.Unlock()
+
+		// Simulate rapid ingest invalidation (should be rate-limited)
+		s.invalidateCachesFor(cacheInvalidation{hasNewObservations: true})
+
+		// Check if cache survived the invalidation
+		s.cacheMu.Lock()
+		if len(s.rfCache) > 0 {
+			hits++
+		} else {
+			misses++
+		}
+		s.cacheMu.Unlock()
+	}
+
+	if hits == 0 {
+		b.Errorf("expected cache hits > 0 with rate-limited invalidation, got 0 hits / %d misses", misses)
+	}
+	b.ReportMetric(float64(hits)/float64(hits+misses)*100, "hit%")
+}

cmd/server/config.go

@@ -6,6 +6,8 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+
+	"github.com/meshcore-analyzer/geofilter"
 )
 
 // Config mirrors the Node.js config.json structure (read-only fields).
@@ -53,6 +55,8 @@ type Config struct {
 	GeoFilter *GeoFilterConfig `json:"geo_filter,omitempty"`
 
 	Timestamps *TimestampConfig `json:"timestamps,omitempty"`
+
+	DebugAffinity bool `json:"debugAffinity,omitempty"`
 }
 
 // PacketStoreConfig controls in-memory packet store limits.
@@ -61,15 +65,15 @@ type PacketStoreConfig struct {
 	MaxMemoryMB    int     `json:"maxMemoryMB"`     // hard memory ceiling in MB (0 = unlimited)
 }
 
-type GeoFilterConfig struct {
-	Polygon  [][2]float64 `json:"polygon,omitempty"`
-	BufferKm float64      `json:"bufferKm,omitempty"`
-	LatMin   *float64     `json:"latMin,omitempty"`
-	LatMax   *float64     `json:"latMax,omitempty"`
-	LonMin   *float64     `json:"lonMin,omitempty"`
-	LonMax   *float64     `json:"lonMax,omitempty"`
+// GeoFilterConfig is an alias for the shared geofilter.Config type.
+type GeoFilterConfig = geofilter.Config
+
+type RetentionConfig struct {
+	NodeDays   int `json:"nodeDays"`
+	PacketDays int `json:"packetDays"`
 }
 
+
 type TimestampConfig struct {
 	DefaultMode       string `json:"defaultMode"`       // "ago" | "absolute"
 	Timezone          string `json:"timezone"`          // "local" | "utc"
@@ -78,10 +82,6 @@ type TimestampConfig struct {
 	AllowCustomFormat bool   `json:"allowCustomFormat"` // admin gate
 }
 
-type RetentionConfig struct {
-	NodeDays int `json:"nodeDays"`
-}
-
 func defaultTimestampConfig() TimestampConfig {
 	return TimestampConfig{
 		DefaultMode:       "ago",
@@ -221,17 +221,11 @@ func (c *Config) ResolveDBPath(baseDir string) string {
 	return filepath.Join(baseDir, "data", "meshcore.db")
 }
 
-func (c *Config) PropagationBufferMs() int {
-	if c.LiveMap.PropagationBufferMs > 0 {
-		return c.LiveMap.PropagationBufferMs
-	}
-	return 5000
-}
 
 func (c *Config) NormalizeTimestampConfig() {
 	defaults := defaultTimestampConfig()
 	if c.Timestamps == nil {
-		log.Printf("[config] timestamps not configured — using defaults (ago/local/iso)")
+		log.Printf("[config] timestamps not configured - using defaults (ago/local/iso)")
 		c.Timestamps = &defaults
 		return
 	}
@@ -273,3 +267,9 @@ func (c *Config) GetTimestampConfig() TimestampConfig {
 	}
 	return *c.Timestamps
 }
+func (c *Config) PropagationBufferMs() int {
+	if c.LiveMap.PropagationBufferMs > 0 {
+		return c.LiveMap.PropagationBufferMs
+	}
+	return 5000
+}

cmd/server/coverage_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bytes"
 	"database/sql"
 	"encoding/json"
 	"fmt"
@@ -428,6 +429,49 @@ func TestMaxTransmissionID(t *testing.T) {
 	})
 }
 
+// --- MaxTransmissionID incremental tracking ---
+
+func TestMaxTransmissionIDIncremental(t *testing.T) {
+	db := setupTestDB(t)
+	defer db.Close()
+	seedTestData(t, db)
+	store := NewPacketStore(db, nil)
+	store.Load()
+
+	maxTx := store.MaxTransmissionID()
+	maxObs := store.MaxObservationID()
+
+	if maxTx <= 0 {
+		t.Fatalf("expected maxTx > 0 after Load, got %d", maxTx)
+	}
+	if maxObs <= 0 {
+		t.Fatalf("expected maxObs > 0 after Load, got %d", maxObs)
+	}
+
+	// Verify incremental field matches brute-force iteration
+	store.mu.RLock()
+	bruteMaxTx := 0
+	for id := range store.byTxID {
+		if id > bruteMaxTx {
+			bruteMaxTx = id
+		}
+	}
+	bruteMaxObs := 0
+	for id := range store.byObsID {
+		if id > bruteMaxObs {
+			bruteMaxObs = id
+		}
+	}
+	store.mu.RUnlock()
+
+	if maxTx != bruteMaxTx {
+		t.Errorf("maxTxID mismatch: incremental=%d brute=%d", maxTx, bruteMaxTx)
+	}
+	if maxObs != bruteMaxObs {
+		t.Errorf("maxObsID mismatch: incremental=%d brute=%d", maxObs, bruteMaxObs)
+	}
+}
+
 // --- Route handler DB fallback (no store) ---
 
 func TestHandleBulkHealthNoStore(t *testing.T) {
@@ -770,6 +814,56 @@ func TestPrefixMapResolve(t *testing.T) {
 	})
 }
 
+func TestPrefixMapCap(t *testing.T) {
+	// 16-char pubkey — longer than maxPrefixLen
+	nodes := []nodeInfo{
+		{PublicKey: "aabbccdd11223344", Name: "LongKey"},
+		{PublicKey: "eeff0011", Name: "ShortKey"}, // exactly 8 chars
+	}
+	pm := buildPrefixMap(nodes)
+
+	t.Run("short prefixes still work", func(t *testing.T) {
+		n := pm.resolve("aabb")
+		if n == nil || n.Name != "LongKey" {
+			t.Errorf("expected LongKey for short prefix, got %v", n)
+		}
+	})
+
+	t.Run("full pubkey exact match works", func(t *testing.T) {
+		n := pm.resolve("aabbccdd11223344")
+		if n == nil || n.Name != "LongKey" {
+			t.Errorf("expected LongKey for full key, got %v", n)
+		}
+	})
+
+	t.Run("intermediate prefix beyond cap returns nil", func(t *testing.T) {
+		// 10-char prefix — beyond maxPrefixLen but not full key
+		n := pm.resolve("aabbccdd11")
+		if n != nil {
+			t.Errorf("expected nil for intermediate prefix beyond cap, got %v", n.Name)
+		}
+	})
+
+	t.Run("short key within cap has all prefixes", func(t *testing.T) {
+		for l := 2; l <= 8; l++ {
+			pfx := "eeff0011"[:l]
+			n := pm.resolve(pfx)
+			if n == nil || n.Name != "ShortKey" {
+				t.Errorf("prefix %q: expected ShortKey, got %v", pfx, n)
+			}
+		}
+	})
+
+	t.Run("map size is capped", func(t *testing.T) {
+		// LongKey: 7 prefix entries (2..8) + 1 full key = 8
+		// ShortKey: 7 prefix entries (2..8), no full key entry (len == maxPrefixLen) = 7
+		// No overlapping prefixes between the two nodes → 8 + 7 = 15 unique map keys
+		if len(pm.m) != 15 {
+			t.Errorf("expected 15 map entries (8 for LongKey + 7 for ShortKey), got %d", len(pm.m))
+		}
+	})
+}
+
 // --- pathLen ---
 
 func TestPathLen(t *testing.T) {
@@ -1333,6 +1427,40 @@ func TestGetNodeLocations(t *testing.T) {
 	}
 }
 
+// --- GetNodeLocationsByKeys ---
+
+func TestGetNodeLocationsByKeys(t *testing.T) {
+	db := setupTestDB(t)
+	defer db.Close()
+	seedTestData(t, db)
+
+	// Query with a known key
+	pk := "aabbccdd11223344"
+	locs := db.GetNodeLocationsByKeys([]string{pk})
+	if len(locs) != 1 {
+		t.Errorf("expected 1 location, got %d", len(locs))
+	}
+	if entry, ok := locs[strings.ToLower(pk)]; ok {
+		if entry["lat"] == nil {
+			t.Error("expected non-nil lat")
+		}
+	} else {
+		t.Error("expected node location for test repeater")
+	}
+
+	// Query with no keys returns empty map
+	empty := db.GetNodeLocationsByKeys([]string{})
+	if len(empty) != 0 {
+		t.Errorf("expected 0 locations for empty keys, got %d", len(empty))
+	}
+
+	// Query with unknown key returns empty map
+	unknown := db.GetNodeLocationsByKeys([]string{"nonexistent"})
+	if len(unknown) != 0 {
+		t.Errorf("expected 0 locations for unknown key, got %d", len(unknown))
+	}
+}
+
 // --- Store edge cases ---
 
 func TestStoreQueryPacketsEdgeCases(t *testing.T) {
@@ -1906,6 +2034,48 @@ func TestTxToMap(t *testing.T) {
 	}
 }
 
+func TestTxToMapLazyObservations(t *testing.T) {
+	snr := 10.5
+	rssi := -90.0
+	tx := &StoreTx{
+		ID:   1,
+		Hash: "abc",
+		Observations: []*StoreObs{
+			{ID: 10, ObserverID: "obs1", ObserverName: "O1", SNR: &snr, RSSI: &rssi, Timestamp: "2025-01-01"},
+			{ID: 11, ObserverID: "obs2", ObserverName: "O2", SNR: &snr, RSSI: &rssi, Timestamp: "2025-01-02"},
+		},
+	}
+
+	// Without flag: no observations key
+	m := txToMap(tx)
+	if _, ok := m["observations"]; ok {
+		t.Error("txToMap without includeObservations should not include observations key")
+	}
+
+	// With false: no observations key
+	m = txToMap(tx, false)
+	if _, ok := m["observations"]; ok {
+		t.Error("txToMap(tx, false) should not include observations key")
+	}
+
+	// With true: observations included
+	m = txToMap(tx, true)
+	obs, ok := m["observations"]
+	if !ok {
+		t.Fatal("txToMap(tx, true) should include observations key")
+	}
+	obsList, ok := obs.([]map[string]interface{})
+	if !ok {
+		t.Fatal("observations should be []map[string]interface{}")
+	}
+	if len(obsList) != 2 {
+		t.Errorf("expected 2 observations, got %d", len(obsList))
+	}
+	if obsList[0]["observer_id"] != "obs1" {
+		t.Errorf("expected observer_id obs1, got %v", obsList[0]["observer_id"])
+	}
+}
+
 // --- filterTxSlice ---
 
 func TestFilterTxSlice(t *testing.T) {
@@ -2099,6 +2269,84 @@ func TestSubpathPrecomputedIndex(t *testing.T) {
 	}
 }
 
+func TestSubpathTxIndexPopulated(t *testing.T) {
+	db := setupRichTestDB(t)
+	defer db.Close()
+	store := NewPacketStore(db, nil)
+	store.Load()
+
+	// spTxIndex must be populated alongside spIndex
+	if len(store.spTxIndex) == 0 {
+		t.Fatal("expected spTxIndex to be populated after Load()")
+	}
+
+	// Every key in spIndex must also exist in spTxIndex with matching count
+	for key, count := range store.spIndex {
+		txs, ok := store.spTxIndex[key]
+		if !ok {
+			t.Errorf("spTxIndex missing key %q that exists in spIndex", key)
+			continue
+		}
+		if len(txs) != count {
+			t.Errorf("spTxIndex[%q] has %d txs, spIndex count is %d", key, len(txs), count)
+		}
+	}
+
+	// GetSubpathDetail should return correct match count via indexed lookup
+	detail := store.GetSubpathDetail([]string{"eeff", "0011"})
+	if detail == nil {
+		t.Fatal("expected non-nil detail for existing subpath")
+	}
+	matches, _ := detail["totalMatches"].(int)
+	if matches != 1 {
+		t.Errorf("totalMatches = %d, want 1", matches)
+	}
+
+	// Non-existent subpath should return 0 matches
+	detail2 := store.GetSubpathDetail([]string{"zzzz", "yyyy"})
+	if detail2 == nil {
+		t.Fatal("expected non-nil result even for non-existent subpath")
+	}
+	matches2, _ := detail2["totalMatches"].(int)
+	if matches2 != 0 {
+		t.Errorf("totalMatches for non-existent subpath = %d, want 0", matches2)
+	}
+}
+
+func TestSubpathDetailMixedCaseHops(t *testing.T) {
+	db := setupRichTestDB(t)
+	defer db.Close()
+	store := NewPacketStore(db, nil)
+	store.Load()
+
+	// Query with lowercase hops to establish baseline
+	lower := store.GetSubpathDetail([]string{"eeff", "0011"})
+	if lower == nil {
+		t.Fatal("expected non-nil detail for lowercase subpath")
+	}
+	lowerMatches, _ := lower["totalMatches"].(int)
+	if lowerMatches == 0 {
+		t.Fatal("expected >0 matches for lowercase subpath")
+	}
+
+	// Query with mixed-case hops — must return the same results (case-insensitive)
+	mixed := store.GetSubpathDetail([]string{"EEFF", "0011"})
+	if mixed == nil {
+		t.Fatal("expected non-nil detail for mixed-case subpath")
+	}
+	mixedMatches, _ := mixed["totalMatches"].(int)
+	if mixedMatches != lowerMatches {
+		t.Errorf("mixed-case totalMatches = %d, want %d (same as lowercase)", mixedMatches, lowerMatches)
+	}
+
+	// All-uppercase should also match
+	upper := store.GetSubpathDetail([]string{"EEFF", "0011"})
+	upperMatches, _ := upper["totalMatches"].(int)
+	if upperMatches != lowerMatches {
+		t.Errorf("uppercase totalMatches = %d, want %d", upperMatches, lowerMatches)
+	}
+}
+
 func TestStoreGetAnalyticsRFCacheHit(t *testing.T) {
 	db := setupRichTestDB(t)
 	defer db.Close()
@@ -3715,3 +3963,379 @@ func TestGetChannelMessagesAfterIngest(t *testing.T) {
 		t.Errorf("newest message should be 'brand new message', got %q", lastMsg["text"])
 	}
 }
+
+// --- resolveRegionObservers caching ---
+
+func TestResolveRegionObserversCaching(t *testing.T) {
+	db := setupTestDB(t)
+	defer db.Close()
+	seedTestData(t, db)
+
+	store := &PacketStore{db: db}
+
+	// First call should populate cache.
+	obs1 := store.resolveRegionObservers("SJC")
+	if obs1 == nil || len(obs1) == 0 {
+		t.Fatal("expected observer IDs for SJC on first call")
+	}
+
+	// Second call should return cached result (same pointer).
+	obs2 := store.resolveRegionObservers("SJC")
+	if len(obs2) != len(obs1) {
+		t.Errorf("cached result differs: got %d, want %d", len(obs2), len(obs1))
+	}
+
+	// Non-existent region should return nil even from cache.
+	obs3 := store.resolveRegionObservers("NONEXIST")
+	if obs3 != nil {
+		t.Errorf("expected nil for NONEXIST, got %v", obs3)
+	}
+
+	// Verify cache fields are set.
+	if store.regionObsCache == nil {
+		t.Error("regionObsCache should be non-nil after calls")
+	}
+	if store.regionObsCacheTime.IsZero() {
+		t.Error("regionObsCacheTime should be set")
+	}
+}
+
+func TestResolveRegionObserversCacheMissNewRegion(t *testing.T) {
+	db := setupTestDB(t)
+	defer db.Close()
+	seedTestData(t, db)
+
+	store := &PacketStore{db: db}
+
+	// Populate cache with SJC.
+	obs1 := store.resolveRegionObservers("SJC")
+	if obs1 == nil || len(obs1) == 0 {
+		t.Fatal("expected observer IDs for SJC on first call")
+	}
+
+	// Cache is now valid. Request a different region that exists in DB.
+	// Before the fix, this would return nil from the map lookup instead of
+	// fetching from DB, silently returning "no observers" for up to 30s.
+	obs2 := store.resolveRegionObservers("LAX")
+	// LAX may or may not have data in the test DB, but the key point is:
+	// a non-existent region should be fetched (not just nil-returned).
+	// Verify the region key was cached (even if empty).
+	store.regionObsMu.Lock()
+	_, cached := store.regionObsCache["LAX"]
+	store.regionObsMu.Unlock()
+	if !cached {
+		t.Error("LAX should be cached after resolveRegionObservers call, even if empty")
+	}
+	_ = obs2
+}
+
+func TestIndexByNodePreCheck(t *testing.T) {
+	store := &PacketStore{
+		byNode:     make(map[string][]*StoreTx),
+		nodeHashes: make(map[string]map[string]bool),
+	}
+
+	t.Run("indexes ADVERT with pubKey", func(t *testing.T) {
+		tx := &StoreTx{Hash: "h1", DecodedJSON: `{"pubKey":"AABBCC","type":"ADVERT"}`}
+		store.indexByNode(tx)
+		if len(store.byNode["AABBCC"]) != 1 {
+			t.Errorf("expected 1 entry for pubKey AABBCC, got %d", len(store.byNode["AABBCC"]))
+		}
+	})
+
+	t.Run("indexes destPubKey", func(t *testing.T) {
+		tx := &StoreTx{Hash: "h2", DecodedJSON: `{"destPubKey":"DDEEFF","type":"MSG"}`}
+		store.indexByNode(tx)
+		if len(store.byNode["DDEEFF"]) != 1 {
+			t.Errorf("expected 1 entry for destPubKey DDEEFF, got %d", len(store.byNode["DDEEFF"]))
+		}
+	})
+
+	t.Run("indexes srcPubKey", func(t *testing.T) {
+		tx := &StoreTx{Hash: "h2b", DecodedJSON: `{"srcPubKey":"112233","type":"TXT_MSG"}`}
+		store.indexByNode(tx)
+		if len(store.byNode["112233"]) != 1 {
+			t.Errorf("expected 1 entry for srcPubKey 112233, got %d", len(store.byNode["112233"]))
+		}
+	})
+
+	t.Run("skips channel message without pubKey", func(t *testing.T) {
+		beforeLen := len(store.byNode)
+		tx := &StoreTx{Hash: "h3", DecodedJSON: `{"type":"CHAN","channel":"#test","text":"hello"}`}
+		store.indexByNode(tx)
+		if len(store.byNode) != beforeLen {
+			t.Errorf("expected byNode unchanged for channel packet, got %d new entries", len(store.byNode)-beforeLen)
+		}
+	})
+
+	t.Run("skips empty DecodedJSON", func(t *testing.T) {
+		beforeLen := len(store.byNode)
+		tx := &StoreTx{Hash: "h4", DecodedJSON: ""}
+		store.indexByNode(tx)
+		if len(store.byNode) != beforeLen {
+			t.Error("expected byNode unchanged for empty DecodedJSON")
+		}
+	})
+
+	t.Run("deduplicates same hash", func(t *testing.T) {
+		tx := &StoreTx{Hash: "h1", DecodedJSON: `{"pubKey":"AABBCC","type":"ADVERT"}`}
+		store.indexByNode(tx) // second call for same hash
+		if len(store.byNode["AABBCC"]) != 1 {
+			t.Errorf("expected dedup to keep 1 entry, got %d", len(store.byNode["AABBCC"]))
+		}
+	})
+}
+
+// BenchmarkIndexByNode measures indexByNode performance with and without pubkey
+// fields to demonstrate the strings.Contains pre-check optimization.
+func BenchmarkIndexByNode(b *testing.B) {
+	// Payload WITHOUT any pubkey fields — should be skipped via pre-check
+	noPubkey := `{"type":1,"msgId":42,"sender":"node1","data":"hello world"}`
+	// Payload WITH a pubkey field — requires JSON parse
+	withPubkey := `{"type":1,"msgId":42,"pubKey":"AABB","sender":"node1","data":"hello world"}`
+
+	b.Run("no_pubkey_skip", func(b *testing.B) {
+		store := &PacketStore{
+			byNode:     make(map[string][]*StoreTx),
+			nodeHashes: make(map[string]map[string]bool),
+		}
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			tx := &StoreTx{
+				Hash:        fmt.Sprintf("hash-%d", i),
+				DecodedJSON: noPubkey,
+			}
+			store.indexByNode(tx)
+		}
+	})
+
+	b.Run("with_pubkey_parse", func(b *testing.B) {
+		store := &PacketStore{
+			byNode:     make(map[string][]*StoreTx),
+			nodeHashes: make(map[string]map[string]bool),
+		}
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			tx := &StoreTx{
+				Hash:        fmt.Sprintf("hash-%d", i),
+				DecodedJSON: withPubkey,
+			}
+			store.indexByNode(tx)
+		}
+	})
+}
+
+// --- Multi-observer comma-separated filter tests ---
+
+func TestTransmissionsForObserverMultiCSV(t *testing.T) {
+	db := setupTestDB(t)
+	defer db.Close()
+	seedTestData(t, db)
+	store := NewPacketStore(db, nil)
+	store.Load()
+
+	t.Run("comma-separated returns union via index", func(t *testing.T) {
+		result := store.transmissionsForObserver("obs1,obs2", nil)
+		if len(result) == 0 {
+			t.Fatal("expected results for obs1,obs2")
+		}
+		// obs1 has transmissions 1,2,3; obs2 has transmission 1
+		// Union should include all unique transmissions
+		obs1Only := store.transmissionsForObserver("obs1", nil)
+		obs2Only := store.transmissionsForObserver("obs2", nil)
+		if len(result) < len(obs1Only) || len(result) < len(obs2Only) {
+			t.Errorf("union (%d) should be >= each individual set (obs1=%d, obs2=%d)",
+				len(result), len(obs1Only), len(obs2Only))
+		}
+	})
+
+	t.Run("comma-separated with spaces via index", func(t *testing.T) {
+		result := store.transmissionsForObserver("obs1, obs2", nil)
+		if len(result) == 0 {
+			t.Fatal("expected results for 'obs1, obs2' (with space)")
+		}
+		noSpace := store.transmissionsForObserver("obs1,obs2", nil)
+		if len(result) != len(noSpace) {
+			t.Errorf("with-space (%d) should equal no-space (%d)", len(result), len(noSpace))
+		}
+	})
+
+	t.Run("comma-separated returns union via filter path", func(t *testing.T) {
+		allTx := store.packets
+		result := store.transmissionsForObserver("obs1,obs2", allTx)
+		if len(result) == 0 {
+			t.Fatal("expected results for obs1,obs2 via filter path")
+		}
+	})
+
+	t.Run("comma-separated with spaces via filter path", func(t *testing.T) {
+		allTx := store.packets
+		withSpace := store.transmissionsForObserver("obs1, obs2", allTx)
+		noSpace := store.transmissionsForObserver("obs1,obs2", allTx)
+		if len(withSpace) != len(noSpace) {
+			t.Errorf("filter path: with-space (%d) should equal no-space (%d)", len(withSpace), len(noSpace))
+		}
+	})
+}
+
+func TestBuildTransmissionWhereMultiObserver(t *testing.T) {
+	db := setupTestDB(t)
+	defer db.Close()
+	seedTestData(t, db)
+
+	t.Run("comma-separated produces IN clause", func(t *testing.T) {
+		q := PacketQuery{Observer: "obs1,obs2"}
+		where, args := db.buildTransmissionWhere(q)
+		if len(where) != 1 {
+			t.Fatalf("expected 1 WHERE clause, got %d", len(where))
+		}
+		clause := where[0]
+		if !strings.Contains(clause, "IN (?,?)") {
+			t.Errorf("expected IN (?,?) in clause, got: %s", clause)
+		}
+		if len(args) != 2 {
+			t.Fatalf("expected 2 args, got %d", len(args))
+		}
+		if args[0] != "obs1" || args[1] != "obs2" {
+			t.Errorf("expected [obs1, obs2], got %v", args)
+		}
+	})
+
+	t.Run("comma-separated with spaces trims IDs", func(t *testing.T) {
+		q := PacketQuery{Observer: "obs1, obs2"}
+		_, args := db.buildTransmissionWhere(q)
+		if len(args) != 2 {
+			t.Fatalf("expected 2 args, got %d", len(args))
+		}
+		if args[0] != "obs1" || args[1] != "obs2" {
+			t.Errorf("expected trimmed [obs1, obs2], got %v", args)
+		}
+	})
+
+	t.Run("single observer still works", func(t *testing.T) {
+		q := PacketQuery{Observer: "obs1"}
+		where, args := db.buildTransmissionWhere(q)
+		if len(where) != 1 {
+			t.Fatalf("expected 1 WHERE clause, got %d", len(where))
+		}
+		if !strings.Contains(where[0], "IN (?)") {
+			t.Errorf("expected IN (?) for single observer, got: %s", where[0])
+		}
+		if len(args) != 1 || args[0] != "obs1" {
+			t.Errorf("expected [obs1], got %v", args)
+		}
+	})
+}
+
+// --- Distance index incremental update (#365, replaces debounce #557) ---
+
+func TestDistanceIncrementalUpdate(t *testing.T) {
+	db := setupTestDB(t)
+	defer db.Close()
+	seedTestData(t, db)
+	store := NewPacketStore(db, nil)
+	store.Load()
+
+	// Record initial distance index size.
+	initialHops := len(store.distHops)
+	initialPaths := len(store.distPaths)
+
+	// Insert a new observation with a different path to trigger an incremental update.
+	maxObsID := db.GetMaxObservationID()
+	db.conn.Exec(`INSERT INTO observations (transmission_id, observer_idx, snr, rssi, path_json, timestamp)
+		VALUES (1, 2, 5.0, -100, '["xx","yy","zz"]', ?)`, time.Now().Unix())
+
+	store.IngestNewObservations(maxObsID, 500)
+
+	// Distance index should have been updated incrementally (sizes may differ
+	// if the new path resolves differently, but should not panic or corrupt).
+	_ = len(store.distHops)
+	_ = len(store.distPaths)
+
+	// Insert another observation with yet another path.
+	maxObsID = db.GetMaxObservationID()
+	db.conn.Exec(`INSERT INTO observations (transmission_id, observer_idx, snr, rssi, path_json, timestamp)
+		VALUES (1, 2, 7.0, -95, '["aa","bb","cc","dd"]', ?)`, time.Now().Unix())
+
+	store.IngestNewObservations(maxObsID, 500)
+
+	// Verify the index is still coherent (no duplicates for the same tx).
+	txSeen := make(map[int]int)
+	for _, r := range store.distPaths {
+		if r.tx != nil {
+			txSeen[r.tx.ID]++
+		}
+	}
+	for txID, count := range txSeen {
+		if count > 1 {
+			t.Errorf("distPaths has %d entries for tx %d (expected at most 1)", count, txID)
+		}
+	}
+
+	t.Logf("Distance index: %d→%d hops, %d→%d paths (incremental)",
+		initialHops, len(store.distHops), initialPaths, len(store.distPaths))
+}
+
+func TestHandleBatchObservations(t *testing.T) {
+	_, router := setupNoStoreServer(t)
+
+	t.Run("empty hashes returns empty results", func(t *testing.T) {
+		body := strings.NewReader(`{"hashes":[]}`)
+		req := httptest.NewRequest("POST", "/api/packets/observations", body)
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+		if w.Code != 200 {
+			t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+		}
+		var resp map[string]interface{}
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		results, ok := resp["results"].(map[string]interface{})
+		if !ok || len(results) != 0 {
+			t.Fatalf("expected empty results map, got %v", resp)
+		}
+	})
+
+	t.Run("invalid JSON returns 400", func(t *testing.T) {
+		body := strings.NewReader(`not json`)
+		req := httptest.NewRequest("POST", "/api/packets/observations", body)
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+		if w.Code != 400 {
+			t.Fatalf("expected 400, got %d", w.Code)
+		}
+	})
+
+	t.Run("too many hashes returns 400", func(t *testing.T) {
+		hashes := make([]string, 201)
+		for i := range hashes {
+			hashes[i] = fmt.Sprintf("hash%d", i)
+		}
+		data, _ := json.Marshal(map[string][]string{"hashes": hashes})
+		req := httptest.NewRequest("POST", "/api/packets/observations", bytes.NewReader(data))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+		if w.Code != 400 {
+			t.Fatalf("expected 400, got %d", w.Code)
+		}
+	})
+
+	t.Run("valid hashes with no store returns empty results", func(t *testing.T) {
+		body := strings.NewReader(`{"hashes":["abc123","def456"]}`)
+		req := httptest.NewRequest("POST", "/api/packets/observations", body)
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+		if w.Code != 200 {
+			t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+		}
+		var resp map[string]interface{}
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		_, ok := resp["results"].(map[string]interface{})
+		if !ok {
+			t.Fatalf("expected results map, got %v", resp)
+		}
+	})
+}

cmd/server/db.go

@@ -4,6 +4,7 @@ import (
 	"database/sql"
 	"encoding/json"
 	"fmt"
+	"log"
 	"math"
 	"os"
 	"strings"
@@ -14,9 +15,10 @@ import (
 
 // DB wraps a read-only connection to the MeshCore SQLite database.
 type DB struct {
-	conn *sql.DB
-	path string // filesystem path to the database file
-	isV3 bool   // v3 schema: observer_idx in observations (vs observer_id in v2)
+	conn             *sql.DB
+	path             string // filesystem path to the database file
+	isV3             bool   // v3 schema: observer_idx in observations (vs observer_id in v2)
+	hasResolvedPath  bool   // observations table has resolved_path column
 }
 
 // OpenDB opens a read-only SQLite connection with WAL mode.
@@ -38,6 +40,12 @@ func OpenDB(path string) (*DB, error) {
 }
 
 func (db *DB) Close() error {
+	// Checkpoint WAL before closing to release lock cleanly for new processes
+	if _, err := db.conn.Exec("PRAGMA wal_checkpoint(TRUNCATE)"); err != nil {
+		log.Printf("[db] WAL checkpoint error: %v", err)
+	} else {
+		log.Println("[db] WAL checkpoint complete")
+	}
 	return db.conn.Close()
 }
 
@@ -54,9 +62,13 @@ func (db *DB) detectSchema() {
 		var colType sql.NullString
 		var notNull, pk int
 		var dflt sql.NullString
-		if rows.Scan(&cid, &colName, &colType, &notNull, &dflt, &pk) == nil && colName == "observer_idx" {
-			db.isV3 = true
-			return
+		if rows.Scan(&cid, &colName, &colType, &notNull, &dflt, &pk) == nil {
+			if colName == "observer_idx" {
+				db.isV3 = true
+			}
+			if colName == "resolved_path" {
+				db.hasResolvedPath = true
+			}
 		}
 	}
 }
@@ -365,7 +377,8 @@ type PacketQuery struct {
 	Until    string
 	Region   string
 	Node     string
-	Order    string // ASC or DESC
+	Order               string // ASC or DESC
+	ExpandObservations  bool   // when true, include observation sub-maps in txToMap output
 }
 
 // PacketResult wraps paginated packet list.
@@ -601,12 +614,17 @@ func (db *DB) buildTransmissionWhere(q PacketQuery) ([]string, []interface{}) {
 		args = append(args, "%"+pk+"%")
 	}
 	if q.Observer != "" {
+		ids := strings.Split(q.Observer, ",")
+		placeholders := strings.Repeat("?,", len(ids))
+		placeholders = placeholders[:len(placeholders)-1]
 		if db.isV3 {
-			where = append(where, "EXISTS (SELECT 1 FROM observations oi JOIN observers obi ON obi.rowid = oi.observer_idx WHERE oi.transmission_id = t.id AND obi.id = ?)")
+			where = append(where, "EXISTS (SELECT 1 FROM observations oi JOIN observers obi ON obi.rowid = oi.observer_idx WHERE oi.transmission_id = t.id AND obi.id IN ("+placeholders+"))")
 		} else {
-			where = append(where, "EXISTS (SELECT 1 FROM observations oi WHERE oi.transmission_id = t.id AND oi.observer_id = ?)")
+			where = append(where, "EXISTS (SELECT 1 FROM observations oi WHERE oi.transmission_id = t.id AND oi.observer_id IN ("+placeholders+"))")
+		}
+		for _, id := range ids {
+			args = append(args, strings.TrimSpace(id))
 		}
-		args = append(args, q.Observer)
 	}
 	if q.Region != "" {
 		if db.isV3 {
@@ -691,6 +709,32 @@ func (db *DB) GetNodes(limit, offset int, role, search, before, lastHeard, sortB
 		}
 	}
 
+	if region != "" {
+		codes := normalizeRegionCodes(region)
+		if len(codes) > 0 {
+			placeholders := make([]string, len(codes))
+			regionArgs := make([]interface{}, len(codes))
+			for i, c := range codes {
+				placeholders[i] = "?"
+				regionArgs[i] = c
+			}
+			joinCond := "obs.rowid = o.observer_idx"
+			if !db.isV3 {
+				joinCond = "obs.id = o.observer_id"
+			}
+			subq := fmt.Sprintf(`public_key IN (
+				SELECT DISTINCT JSON_EXTRACT(t.decoded_json, '$.pubKey')
+				FROM transmissions t
+				JOIN observations o ON o.transmission_id = t.id
+				JOIN observers obs ON %s
+				WHERE t.payload_type = 4
+				AND UPPER(TRIM(obs.iata)) IN (%s)
+			)`, joinCond, strings.Join(placeholders, ","))
+			where = append(where, subq)
+			args = append(args, regionArgs...)
+		}
+	}
+
 	w := ""
 	if len(where) > 0 {
 		w = "WHERE " + strings.Join(where, " AND ")
@@ -1454,6 +1498,39 @@ func (db *DB) GetNodeLocations() map[string]map[string]interface{} {
 	return result
 }
 
+// GetNodeLocationsByKeys returns location data only for the given public keys.
+// This avoids fetching ALL nodes when only a few keys need to be matched.
+func (db *DB) GetNodeLocationsByKeys(keys []string) map[string]map[string]interface{} {
+	result := make(map[string]map[string]interface{})
+	if len(keys) == 0 {
+		return result
+	}
+	placeholders := make([]string, len(keys))
+	args := make([]interface{}, len(keys))
+	for i, k := range keys {
+		placeholders[i] = "?"
+		args[i] = strings.ToLower(k)
+	}
+	query := "SELECT public_key, lat, lon, role FROM nodes WHERE LOWER(public_key) IN (" + strings.Join(placeholders, ",") + ")"
+	rows, err := db.conn.Query(query, args...)
+	if err != nil {
+		return result
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var pk string
+		var role sql.NullString
+		var lat, lon sql.NullFloat64
+		rows.Scan(&pk, &lat, &lon, &role)
+		result[strings.ToLower(pk)] = map[string]interface{}{
+			"lat":  nullFloat(lat),
+			"lon":  nullFloat(lon),
+			"role": nullStr(role),
+		}
+	}
+	return result
+}
+
 // QueryMultiNodePackets returns transmissions referencing any of the given pubkeys.
 func (db *DB) QueryMultiNodePackets(pubkeys []string, limit, offset int, order, since, until string) (*PacketResult, error) {
 	if len(pubkeys) == 0 {
@@ -1621,3 +1698,39 @@ func nullInt(ni sql.NullInt64) interface{} {
 	}
 	return nil
 }
+
+// PruneOldPackets deletes transmissions and their observations older than the
+// given number of days. Nodes and observers are never touched.
+// Returns the number of transmissions deleted.
+// Opens a separate read-write connection since the main connection is read-only.
+func (db *DB) PruneOldPackets(days int) (int64, error) {
+	dsn := fmt.Sprintf("file:%s?_journal_mode=WAL&_busy_timeout=10000", db.path)
+	rw, err := sql.Open("sqlite", dsn)
+	if err != nil {
+		return 0, err
+	}
+	rw.SetMaxOpenConns(1)
+	defer rw.Close()
+
+	cutoff := time.Now().UTC().AddDate(0, 0, -days).Format(time.RFC3339)
+	tx, err := rw.Begin()
+	if err != nil {
+		return 0, err
+	}
+	defer tx.Rollback()
+
+	// Delete observations linked to old transmissions first (no CASCADE in SQLite)
+	_, err = tx.Exec(`DELETE FROM observations WHERE transmission_id IN (
+		SELECT id FROM transmissions WHERE first_seen < ?
+	)`, cutoff)
+	if err != nil {
+		return 0, err
+	}
+
+	res, err := tx.Exec(`DELETE FROM transmissions WHERE first_seen < ?`, cutoff)
+	if err != nil {
+		return 0, err
+	}
+	n, _ := res.RowsAffected()
+	return n, tx.Commit()
+}

cmd/server/db_test.go

@@ -1012,6 +1012,168 @@ func TestGetNodesFiltering(t *testing.T) {
 			t.Errorf("expected 1 node with offset, got %d", len(nodes))
 		}
 	})
+
+	t.Run("region filter SJC", func(t *testing.T) {
+		nodes, total, _, err := db.GetNodes(50, 0, "", "", "", "", "", "SJC")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if total != 1 {
+			t.Errorf("expected 1 node for SJC region, got %d", total)
+		}
+		if len(nodes) != 1 {
+			t.Fatalf("expected 1 node, got %d", len(nodes))
+		}
+		if nodes[0]["public_key"] != "aabbccdd11223344" {
+			t.Errorf("expected TestRepeater, got %v", nodes[0]["public_key"])
+		}
+	})
+
+	t.Run("region filter SFO", func(t *testing.T) {
+		_, total, _, err := db.GetNodes(50, 0, "", "", "", "", "", "SFO")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if total != 1 {
+			t.Errorf("expected 1 node for SFO region, got %d", total)
+		}
+	})
+
+	t.Run("region filter multi", func(t *testing.T) {
+		_, total, _, err := db.GetNodes(50, 0, "", "", "", "", "", "SJC,SFO")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if total != 1 {
+			t.Errorf("expected 1 node for SJC,SFO region, got %d", total)
+		}
+	})
+
+	t.Run("region filter unknown", func(t *testing.T) {
+		_, total, _, err := db.GetNodes(50, 0, "", "", "", "", "", "AMS")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if total != 0 {
+			t.Errorf("expected 0 nodes for unknown region, got %d", total)
+		}
+	})
+}
+
+// setupTestDBV2 creates an in-memory SQLite database with the v2 schema
+// where observations use observer_id TEXT instead of observer_idx INTEGER.
+func setupTestDBV2(t *testing.T) *DB {
+	t.Helper()
+	conn, err := sql.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatal(err)
+	}
+	conn.SetMaxOpenConns(1)
+
+	schema := `
+		CREATE TABLE nodes (
+			public_key TEXT PRIMARY KEY,
+			name TEXT,
+			role TEXT,
+			lat REAL,
+			lon REAL,
+			last_seen TEXT,
+			first_seen TEXT,
+			advert_count INTEGER DEFAULT 0,
+			battery_mv INTEGER,
+			temperature_c REAL
+		);
+
+		CREATE TABLE observers (
+			id TEXT PRIMARY KEY,
+			name TEXT,
+			iata TEXT,
+			last_seen TEXT,
+			first_seen TEXT,
+			packet_count INTEGER DEFAULT 0
+		);
+
+		CREATE TABLE transmissions (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			raw_hex TEXT NOT NULL,
+			hash TEXT NOT NULL UNIQUE,
+			first_seen TEXT NOT NULL,
+			route_type INTEGER,
+			payload_type INTEGER,
+			payload_version INTEGER,
+			decoded_json TEXT,
+			created_at TEXT DEFAULT (datetime('now'))
+		);
+
+		CREATE TABLE observations (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			transmission_id INTEGER NOT NULL REFERENCES transmissions(id),
+			observer_id TEXT,
+			observer_name TEXT,
+			direction TEXT,
+			snr REAL,
+			rssi REAL,
+			score INTEGER,
+			path_json TEXT,
+			timestamp INTEGER NOT NULL
+		);
+	`
+	if _, err := conn.Exec(schema); err != nil {
+		t.Fatal(err)
+	}
+
+	return &DB{conn: conn, isV3: false}
+}
+
+func TestGetNodesRegionFilterV2(t *testing.T) {
+	db := setupTestDBV2(t)
+	defer db.Close()
+
+	now := time.Now().UTC()
+	recent := now.Add(-1 * time.Hour).Format(time.RFC3339)
+	recentEpoch := now.Add(-1 * time.Hour).Unix()
+
+	// Seed observer with IATA code
+	db.conn.Exec(`INSERT INTO observers (id, name, iata, last_seen, first_seen, packet_count)
+		VALUES ('obs-v2-1', 'V2 Observer', 'LAX', ?, '2026-01-01T00:00:00Z', 10)`, recent)
+
+	// Seed a node
+	db.conn.Exec(`INSERT INTO nodes (public_key, name, role, lat, lon, last_seen, first_seen, advert_count)
+		VALUES ('v2pubkey11223344', 'V2Node', 'repeater', 34.0, -118.0, ?, '2026-01-01T00:00:00Z', 5)`, recent)
+
+	// Seed an ADVERT transmission for the node
+	db.conn.Exec(`INSERT INTO transmissions (raw_hex, hash, first_seen, route_type, payload_type, decoded_json)
+		VALUES ('AABB', 'v2hash0001', ?, 1, 4, '{"pubKey":"v2pubkey11223344","name":"V2Node","type":"ADVERT"}')`, recent)
+
+	// Seed v2-style observation: observer_id references observers.id directly
+	db.conn.Exec(`INSERT INTO observations (transmission_id, observer_id, observer_name, snr, rssi, path_json, timestamp)
+		VALUES (1, 'obs-v2-1', 'V2 Observer', 10.0, -90, '[]', ?)`, recentEpoch)
+
+	t.Run("v2 region filter match", func(t *testing.T) {
+		nodes, total, _, err := db.GetNodes(50, 0, "", "", "", "", "", "LAX")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if total != 1 {
+			t.Errorf("expected 1 node for LAX region (v2 schema), got %d", total)
+		}
+		if len(nodes) != 1 {
+			t.Fatalf("expected 1 node, got %d", len(nodes))
+		}
+		if nodes[0]["public_key"] != "v2pubkey11223344" {
+			t.Errorf("expected V2Node, got %v", nodes[0]["public_key"])
+		}
+	})
+
+	t.Run("v2 region filter no match", func(t *testing.T) {
+		_, total, _, err := db.GetNodes(50, 0, "", "", "", "", "", "JFK")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if total != 0 {
+			t.Errorf("expected 0 nodes for JFK region (v2 schema), got %d", total)
+		}
+	})
 }
 
 func TestGetChannelMessagesDedup(t *testing.T) {

cmd/server/decoder.go

@@ -397,6 +397,106 @@ func DecodePacket(hexString string) (*DecodedPacket, error) {
 	}, nil
 }
 
+// HexRange represents a labeled byte range for the hex breakdown visualization.
+type HexRange struct {
+	Start int    `json:"start"`
+	End   int    `json:"end"`
+	Label string `json:"label"`
+}
+
+// Breakdown holds colored byte ranges returned by the packet detail endpoint.
+type Breakdown struct {
+	Ranges []HexRange `json:"ranges"`
+}
+
+// BuildBreakdown computes labeled byte ranges for each section of a MeshCore packet.
+// The returned ranges are consumed by createColoredHexDump() and buildHexLegend()
+// in the frontend (public/app.js).
+func BuildBreakdown(hexString string) *Breakdown {
+	hexString = strings.ReplaceAll(hexString, " ", "")
+	hexString = strings.ReplaceAll(hexString, "\n", "")
+	hexString = strings.ReplaceAll(hexString, "\r", "")
+	buf, err := hex.DecodeString(hexString)
+	if err != nil || len(buf) < 2 {
+		return &Breakdown{Ranges: []HexRange{}}
+	}
+
+	var ranges []HexRange
+	offset := 0
+
+	// Byte 0: Header
+	ranges = append(ranges, HexRange{Start: 0, End: 0, Label: "Header"})
+	offset = 1
+
+	header := decodeHeader(buf[0])
+
+	// Bytes 1-4: Transport Codes (TRANSPORT_FLOOD / TRANSPORT_DIRECT only)
+	if isTransportRoute(header.RouteType) {
+		if len(buf) < offset+4 {
+			return &Breakdown{Ranges: ranges}
+		}
+		ranges = append(ranges, HexRange{Start: offset, End: offset + 3, Label: "Transport Codes"})
+		offset += 4
+	}
+
+	if offset >= len(buf) {
+		return &Breakdown{Ranges: ranges}
+	}
+
+	// Next byte: Path Length (bits 7-6 = hashSize-1, bits 5-0 = hashCount)
+	ranges = append(ranges, HexRange{Start: offset, End: offset, Label: "Path Length"})
+	pathByte := buf[offset]
+	offset++
+
+	hashSize := int(pathByte>>6) + 1
+	hashCount := int(pathByte & 0x3F)
+	pathBytes := hashSize * hashCount
+
+	// Path hops
+	if hashCount > 0 && offset+pathBytes <= len(buf) {
+		ranges = append(ranges, HexRange{Start: offset, End: offset + pathBytes - 1, Label: "Path"})
+	}
+	offset += pathBytes
+
+	if offset >= len(buf) {
+		return &Breakdown{Ranges: ranges}
+	}
+
+	payloadStart := offset
+
+	// Payload — break ADVERT into named sub-fields; everything else is one Payload range
+	if header.PayloadType == PayloadADVERT && len(buf)-payloadStart >= 100 {
+		ranges = append(ranges, HexRange{Start: payloadStart, End: payloadStart + 31, Label: "PubKey"})
+		ranges = append(ranges, HexRange{Start: payloadStart + 32, End: payloadStart + 35, Label: "Timestamp"})
+		ranges = append(ranges, HexRange{Start: payloadStart + 36, End: payloadStart + 99, Label: "Signature"})
+
+		appStart := payloadStart + 100
+		if appStart < len(buf) {
+			ranges = append(ranges, HexRange{Start: appStart, End: appStart, Label: "Flags"})
+			appFlags := buf[appStart]
+			fOff := appStart + 1
+			if appFlags&0x10 != 0 && fOff+8 <= len(buf) {
+				ranges = append(ranges, HexRange{Start: fOff, End: fOff + 3, Label: "Latitude"})
+				ranges = append(ranges, HexRange{Start: fOff + 4, End: fOff + 7, Label: "Longitude"})
+				fOff += 8
+			}
+			if appFlags&0x20 != 0 && fOff+2 <= len(buf) {
+				fOff += 2
+			}
+			if appFlags&0x40 != 0 && fOff+2 <= len(buf) {
+				fOff += 2
+			}
+			if appFlags&0x80 != 0 && fOff < len(buf) {
+				ranges = append(ranges, HexRange{Start: fOff, End: len(buf) - 1, Label: "Name"})
+			}
+		}
+	} else {
+		ranges = append(ranges, HexRange{Start: payloadStart, End: len(buf) - 1, Label: "Payload"})
+	}
+
+	return &Breakdown{Ranges: ranges}
+}
+
 // ComputeContentHash computes the SHA-256-based content hash (first 16 hex chars).
 func ComputeContentHash(rawHex string) string {
 	buf, err := hex.DecodeString(rawHex)

cmd/server/decoder_test.go

@@ -0,0 +1,244 @@
+package main
+
+import (
+	"testing"
+)
+
+func TestDecodeHeader_TransportFlood(t *testing.T) {
+	// Route type 0 = TRANSPORT_FLOOD, payload type 5 = GRP_TXT, version 0
+	// Header byte: (0 << 6) | (5 << 2) | 0 = 0x14
+	h := decodeHeader(0x14)
+	if h.RouteType != RouteTransportFlood {
+		t.Errorf("expected RouteTransportFlood (0), got %d", h.RouteType)
+	}
+	if h.RouteTypeName != "TRANSPORT_FLOOD" {
+		t.Errorf("expected TRANSPORT_FLOOD, got %s", h.RouteTypeName)
+	}
+	if h.PayloadType != PayloadGRP_TXT {
+		t.Errorf("expected PayloadGRP_TXT (5), got %d", h.PayloadType)
+	}
+}
+
+func TestDecodeHeader_TransportDirect(t *testing.T) {
+	// Route type 3 = TRANSPORT_DIRECT, payload type 2 = TXT_MSG, version 0
+	// Header byte: (0 << 6) | (2 << 2) | 3 = 0x0B
+	h := decodeHeader(0x0B)
+	if h.RouteType != RouteTransportDirect {
+		t.Errorf("expected RouteTransportDirect (3), got %d", h.RouteType)
+	}
+	if h.RouteTypeName != "TRANSPORT_DIRECT" {
+		t.Errorf("expected TRANSPORT_DIRECT, got %s", h.RouteTypeName)
+	}
+}
+
+func TestDecodeHeader_Flood(t *testing.T) {
+	// Route type 1 = FLOOD, payload type 4 = ADVERT
+	// Header byte: (0 << 6) | (4 << 2) | 1 = 0x11
+	h := decodeHeader(0x11)
+	if h.RouteType != RouteFlood {
+		t.Errorf("expected RouteFlood (1), got %d", h.RouteType)
+	}
+	if h.RouteTypeName != "FLOOD" {
+		t.Errorf("expected FLOOD, got %s", h.RouteTypeName)
+	}
+}
+
+func TestIsTransportRoute(t *testing.T) {
+	if !isTransportRoute(RouteTransportFlood) {
+		t.Error("expected RouteTransportFlood to be transport")
+	}
+	if !isTransportRoute(RouteTransportDirect) {
+		t.Error("expected RouteTransportDirect to be transport")
+	}
+	if isTransportRoute(RouteFlood) {
+		t.Error("expected RouteFlood to NOT be transport")
+	}
+	if isTransportRoute(RouteDirect) {
+		t.Error("expected RouteDirect to NOT be transport")
+	}
+}
+
+func TestDecodePacket_TransportFloodHasCodes(t *testing.T) {
+	// Build a minimal TRANSPORT_FLOOD packet:
+	// Header 0x14 (route=0/T_FLOOD, payload=5/GRP_TXT)
+	// Transport codes: AABB CCDD (4 bytes)
+	// Path byte: 0x00 (hashSize=1, hashCount=0)
+	// Payload: at least some bytes for GRP_TXT
+	hex := "14AABBCCDD00112233445566778899"
+	pkt, err := DecodePacket(hex)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pkt.TransportCodes == nil {
+		t.Fatal("expected transport codes to be present")
+	}
+	if pkt.TransportCodes.Code1 != "AABB" {
+		t.Errorf("expected Code1=AABB, got %s", pkt.TransportCodes.Code1)
+	}
+	if pkt.TransportCodes.Code2 != "CCDD" {
+		t.Errorf("expected Code2=CCDD, got %s", pkt.TransportCodes.Code2)
+	}
+}
+
+func TestDecodePacket_FloodHasNoCodes(t *testing.T) {
+	// Header 0x11 (route=1/FLOOD, payload=4/ADVERT)
+	// Path byte: 0x00 (no hops)
+	// Some payload bytes
+	hex := "110011223344556677889900AABBCCDD"
+	pkt, err := DecodePacket(hex)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pkt.TransportCodes != nil {
+		t.Error("expected no transport codes for FLOOD route")
+	}
+}
+
+func TestBuildBreakdown_InvalidHex(t *testing.T) {
+	b := BuildBreakdown("not-hex!")
+	if len(b.Ranges) != 0 {
+		t.Errorf("expected empty ranges for invalid hex, got %d", len(b.Ranges))
+	}
+}
+
+func TestBuildBreakdown_TooShort(t *testing.T) {
+	b := BuildBreakdown("11") // 1 byte — no path byte
+	if len(b.Ranges) != 0 {
+		t.Errorf("expected empty ranges for too-short packet, got %d", len(b.Ranges))
+	}
+}
+
+func TestBuildBreakdown_FloodNonAdvert(t *testing.T) {
+	// Header 0x15: route=1/FLOOD, payload=5/GRP_TXT
+	// PathByte 0x01: 1 hop, 1-byte hash
+	// PathHop: AA
+	// Payload: FF0011
+	b := BuildBreakdown("1501AAFFFF00")
+	labels := rangeLabels(b.Ranges)
+	expect := []string{"Header", "Path Length", "Path", "Payload"}
+	if !equalLabels(labels, expect) {
+		t.Errorf("expected labels %v, got %v", expect, labels)
+	}
+	// Verify byte positions
+	assertRange(t, b.Ranges, "Header", 0, 0)
+	assertRange(t, b.Ranges, "Path Length", 1, 1)
+	assertRange(t, b.Ranges, "Path", 2, 2)
+	assertRange(t, b.Ranges, "Payload", 3, 5)
+}
+
+func TestBuildBreakdown_TransportFlood(t *testing.T) {
+	// Header 0x14: route=0/TRANSPORT_FLOOD, payload=5/GRP_TXT
+	// TransportCodes: AABBCCDD (4 bytes)
+	// PathByte 0x01: 1 hop, 1-byte hash
+	// PathHop: EE
+	// Payload: FF00
+	b := BuildBreakdown("14AABBCCDD01EEFF00")
+	assertRange(t, b.Ranges, "Header", 0, 0)
+	assertRange(t, b.Ranges, "Transport Codes", 1, 4)
+	assertRange(t, b.Ranges, "Path Length", 5, 5)
+	assertRange(t, b.Ranges, "Path", 6, 6)
+	assertRange(t, b.Ranges, "Payload", 7, 8)
+}
+
+func TestBuildBreakdown_FloodNoHops(t *testing.T) {
+	// Header 0x15: FLOOD/GRP_TXT; PathByte 0x00: 0 hops; Payload: AABB
+	b := BuildBreakdown("150000AABB")
+	assertRange(t, b.Ranges, "Header", 0, 0)
+	assertRange(t, b.Ranges, "Path Length", 1, 1)
+	// No Path range since hashCount=0
+	for _, r := range b.Ranges {
+		if r.Label == "Path" {
+			t.Error("expected no Path range for zero-hop packet")
+		}
+	}
+	assertRange(t, b.Ranges, "Payload", 2, 4)
+}
+
+func TestBuildBreakdown_AdvertBasic(t *testing.T) {
+	// Header 0x11: FLOOD/ADVERT
+	// PathByte 0x01: 1 hop, 1-byte hash
+	// PathHop: AA
+	// Payload: 100 bytes (PubKey32 + Timestamp4 + Signature64) + Flags=0x02 (repeater, no extras)
+	pubkey := repeatHex("AB", 32)
+	ts := "00000000" // 4 bytes
+	sig := repeatHex("CD", 64)
+	flags := "02"
+	hex := "1101AA" + pubkey + ts + sig + flags
+	b := BuildBreakdown(hex)
+	assertRange(t, b.Ranges, "Header", 0, 0)
+	assertRange(t, b.Ranges, "Path Length", 1, 1)
+	assertRange(t, b.Ranges, "Path", 2, 2)
+	assertRange(t, b.Ranges, "PubKey", 3, 34)
+	assertRange(t, b.Ranges, "Timestamp", 35, 38)
+	assertRange(t, b.Ranges, "Signature", 39, 102)
+	assertRange(t, b.Ranges, "Flags", 103, 103)
+}
+
+func TestBuildBreakdown_AdvertWithLocation(t *testing.T) {
+	// flags=0x12: hasLocation bit set
+	pubkey := repeatHex("00", 32)
+	ts := "00000000"
+	sig := repeatHex("00", 64)
+	flags := "12" // 0x10 = hasLocation
+	latBytes := "00000000"
+	lonBytes := "00000000"
+	hex := "1101AA" + pubkey + ts + sig + flags + latBytes + lonBytes
+	b := BuildBreakdown(hex)
+	assertRange(t, b.Ranges, "Latitude", 104, 107)
+	assertRange(t, b.Ranges, "Longitude", 108, 111)
+}
+
+func TestBuildBreakdown_AdvertWithName(t *testing.T) {
+	// flags=0x82: hasName bit set
+	pubkey := repeatHex("00", 32)
+	ts := "00000000"
+	sig := repeatHex("00", 64)
+	flags := "82" // 0x80 = hasName
+	name := "4E6F6465" // "Node" in hex
+	hex := "1101AA" + pubkey + ts + sig + flags + name
+	b := BuildBreakdown(hex)
+	assertRange(t, b.Ranges, "Name", 104, 107)
+}
+
+// helpers
+
+func rangeLabels(ranges []HexRange) []string {
+	out := make([]string, len(ranges))
+	for i, r := range ranges {
+		out[i] = r.Label
+	}
+	return out
+}
+
+func equalLabels(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+func assertRange(t *testing.T, ranges []HexRange, label string, wantStart, wantEnd int) {
+	t.Helper()
+	for _, r := range ranges {
+		if r.Label == label {
+			if r.Start != wantStart || r.End != wantEnd {
+				t.Errorf("range %q: want [%d,%d], got [%d,%d]", label, wantStart, wantEnd, r.Start, r.End)
+			}
+			return
+		}
+	}
+	t.Errorf("range %q not found in %v", label, rangeLabels(ranges))
+}
+
+func repeatHex(byteHex string, n int) string {
+	s := ""
+	for i := 0; i < n; i++ {
+		s += byteHex
+	}
+	return s
+}

cmd/server/eviction_test.go

@@ -162,24 +162,50 @@ func TestEvictStale_NoEvictionWhenDisabled(t *testing.T) {
 
 func TestEvictStale_MemoryBasedEviction(t *testing.T) {
 	now := time.Now().UTC()
-	// Create enough packets to exceed a small memory limit
-	// 1000 packets * 5KB + 2000 obs * 500B ≈ 6MB
 	store := makeTestStore(1000, now.Add(-1*time.Hour), 0)
-	// All packets are recent (1h old) so time-based won't trigger
+	// All packets are recent (1h old) so time-based won't trigger.
 	store.retentionHours = 24
-	store.maxMemoryMB = 3 // ~3MB limit, should evict roughly half
+	store.maxMemoryMB = 3
+	// Inject deterministic estimator: simulates 6MB (over 3MB limit).
+	// Uses packet count so it scales correctly after eviction.
+	store.memoryEstimator = func() float64 {
+		return float64(len(store.packets)*5120+store.totalObs*500) / 1048576.0
+	}
 
 	evicted := store.EvictStale()
 	if evicted == 0 {
 		t.Fatal("expected some evictions for memory cap")
 	}
-	// After eviction, estimated memory should be <= 3MB
 	estMB := store.estimatedMemoryMB()
-	if estMB > 3.5 { // small tolerance
+	if estMB > 3.5 {
 		t.Fatalf("expected <=3.5MB after eviction, got %.1fMB", estMB)
 	}
 }
 
+// TestEvictStale_MemoryBasedEviction_UnderestimatedHeap verifies that eviction
+// fires correctly when actual heap is much larger than a formula-based estimate
+// would report — the scenario that caused OOM kills in production.
+func TestEvictStale_MemoryBasedEviction_UnderestimatedHeap(t *testing.T) {
+	now := time.Now().UTC()
+	store := makeTestStore(1000, now.Add(-1*time.Hour), 0)
+	store.retentionHours = 24
+	store.maxMemoryMB = 500
+	// Simulate actual heap 5x over budget (like production: ~5GB actual vs ~1GB limit).
+	store.memoryEstimator = func() float64 {
+		return 2500.0 // 2500MB actual vs 500MB limit
+	}
+
+	evicted := store.EvictStale()
+	if evicted == 0 {
+		t.Fatal("expected evictions when heap is 5x over limit")
+	}
+	// Should keep roughly 500/2500 * 0.9 = 18% of packets → ~180 of 1000.
+	remaining := len(store.packets)
+	if remaining > 250 {
+		t.Fatalf("expected most packets evicted (heap 5x over), but %d of 1000 remain", remaining)
+	}
+}
+
 func TestEvictStale_CleansNodeIndexes(t *testing.T) {
 	now := time.Now().UTC()
 	store := makeTestStore(10, now.Add(-48*time.Hour), 0)

cmd/server/geo_filter.go

@@ -0,0 +1,34 @@
+package main
+
+import "github.com/meshcore-analyzer/geofilter"
+
+// NodePassesGeoFilter returns true if the node should be included in responses.
+// Nodes with no GPS coordinates are always allowed.
+// lat and lon are interface{} because they come from DB row maps.
+func NodePassesGeoFilter(lat, lon interface{}, gf *GeoFilterConfig) bool {
+	if gf == nil {
+		return true
+	}
+	latF, ok1 := toFloat64(lat)
+	lonF, ok2 := toFloat64(lon)
+	if !ok1 || !ok2 {
+		return true
+	}
+	return geofilter.PassesFilter(latF, lonF, gf)
+}
+
+func toFloat64(v interface{}) (float64, bool) {
+	switch x := v.(type) {
+	case float64:
+		return x, true
+	case float32:
+		return float64(x), true
+	case int:
+		return float64(x), true
+	case int64:
+		return float64(x), true
+	case nil:
+		return 0, false
+	}
+	return 0, false
+}

cmd/server/go.mod

@@ -5,9 +5,12 @@ go 1.22
 require (
 	github.com/gorilla/mux v1.8.1
 	github.com/gorilla/websocket v1.5.3
+	github.com/meshcore-analyzer/geofilter v0.0.0
 	modernc.org/sqlite v1.34.5
 )
 
+replace github.com/meshcore-analyzer/geofilter => ../../internal/geofilter
+
 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect

cmd/server/helpers_test.go

@@ -2,10 +2,13 @@ package main
 
 import (
 	"encoding/json"
+	"fmt"
+	"math/rand"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -219,6 +222,44 @@ func TestSortedCopy(t *testing.T) {
 	}
 }
 
+func TestSortedCopyLarge(t *testing.T) {
+	// Regression: verify correct sort on larger input
+	rng := rand.New(rand.NewSource(42))
+	n := 1000
+	input := make([]float64, n)
+	for i := range input {
+		input[i] = rng.Float64() * 1000
+	}
+	result := sortedCopy(input)
+	if len(result) != n {
+		t.Fatalf("expected %d elements, got %d", n, len(result))
+	}
+	for i := 1; i < len(result); i++ {
+		if result[i] < result[i-1] {
+			t.Fatalf("not sorted at index %d: %v > %v", i, result[i-1], result[i])
+		}
+	}
+	// Original unchanged
+	if input[0] == result[0] && input[1] == result[1] && input[2] == result[2] {
+		// Could be coincidence but very unlikely with random data
+	}
+}
+
+func BenchmarkSortedCopy(b *testing.B) {
+	rng := rand.New(rand.NewSource(42))
+	for _, size := range []int{256, 1000, 10000} {
+		data := make([]float64, size)
+		for i := range data {
+			data[i] = rng.Float64() * 1000
+		}
+		b.Run(fmt.Sprintf("n=%d", size), func(b *testing.B) {
+			for i := 0; i < b.N; i++ {
+				sortedCopy(data)
+			}
+		})
+	}
+}
+
 func TestLastN(t *testing.T) {
 	arr := []map[string]interface{}{
 		{"id": 1}, {"id": 2}, {"id": 3}, {"id": 4}, {"id": 5},
@@ -326,6 +367,84 @@ func TestSpaHandler(t *testing.T) {
 			t.Errorf("expected no-cache header for .html, got %s", cc)
 		}
 	})
+
+	t.Run("root path serves index.html", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/", nil)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+
+		if w.Code != 200 {
+			t.Errorf("expected 200, got %d", w.Code)
+		}
+		body := w.Body.String()
+		if body != "<html>SPA</html>" {
+			t.Errorf("expected SPA index.html content, got %s", body)
+		}
+		ct := w.Header().Get("Content-Type")
+		if ct != "text/html; charset=utf-8" {
+			t.Errorf("expected text/html content type, got %s", ct)
+		}
+	})
+
+	t.Run("/index.html serves pre-processed content", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/index.html", nil)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+
+		if w.Code != 200 {
+			t.Errorf("expected 200, got %d", w.Code)
+		}
+		body := w.Body.String()
+		if body != "<html>SPA</html>" {
+			t.Errorf("expected SPA index.html content, got %s", body)
+		}
+	})
+}
+
+func TestSpaHandlerCacheBust(t *testing.T) {
+	dir := t.TempDir()
+	htmlWithBust := `<html><script src="app.js?v=__BUST__"></script><link href="style.css?v=__BUST__"></html>`
+	os.WriteFile(filepath.Join(dir, "index.html"), []byte(htmlWithBust), 0644)
+
+	fs := http.FileServer(http.Dir(dir))
+	handler := spaHandler(dir, fs)
+
+	t.Run("__BUST__ is replaced with a Unix timestamp", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/", nil)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+
+		body := w.Body.String()
+		if strings.Contains(body, "__BUST__") {
+			t.Errorf("__BUST__ placeholder was not replaced in response: %s", body)
+		}
+		// Verify it was replaced with digits (Unix timestamp)
+		if !strings.Contains(body, "v=") {
+			t.Errorf("expected v= query params in response, got: %s", body)
+		}
+	})
+
+	t.Run("SPA fallback also has busted values", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/nonexistent/route", nil)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+
+		body := w.Body.String()
+		if strings.Contains(body, "__BUST__") {
+			t.Errorf("__BUST__ placeholder was not replaced in SPA fallback: %s", body)
+		}
+	})
+
+	t.Run("/index.html also has busted values", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/index.html", nil)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+
+		body := w.Body.String()
+		if strings.Contains(body, "__BUST__") {
+			t.Errorf("__BUST__ placeholder was not replaced for /index.html: %s", body)
+		}
+	})
 }
 
 func TestWriteJSON(t *testing.T) {
@@ -345,3 +464,29 @@ func TestWriteJSON(t *testing.T) {
 		t.Errorf("expected 'value', got %v", body["key"])
 	}
 }
+
+func TestHaversineKm(t *testing.T) {
+	// Same point should be 0
+	if d := haversineKm(37.0, -122.0, 37.0, -122.0); d != 0 {
+		t.Errorf("same point: expected 0, got %f", d)
+	}
+
+	// SF to LA ~559km
+	d := haversineKm(37.7749, -122.4194, 34.0522, -118.2437)
+	if d < 550 || d > 570 {
+		t.Errorf("SF to LA: expected ~559km, got %f", d)
+	}
+
+	// Symmetry
+	d1 := haversineKm(37.7749, -122.4194, 34.0522, -118.2437)
+	d2 := haversineKm(34.0522, -118.2437, 37.7749, -122.4194)
+	if d1 != d2 {
+		t.Errorf("not symmetric: %f vs %f", d1, d2)
+	}
+
+	// Oslo to Stockholm ~415km (old Euclidean dLat*111, dLon*85 would give ~627km)
+	d = haversineKm(59.9, 10.7, 59.3, 18.0)
+	if d < 400 || d > 430 {
+		t.Errorf("Oslo to Stockholm: expected ~415km, got %f", d)
+	}
+}

cmd/server/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"context"
 	"database/sql"
 	"flag"
 	"fmt"
@@ -12,6 +13,7 @@ import (
 	"os/signal"
 	"path/filepath"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 
@@ -113,7 +115,13 @@ func main() {
 	if err != nil {
 		log.Fatalf("[db] failed to open %s: %v", resolvedDB, err)
 	}
-	defer database.Close()
+	var dbCloseOnce sync.Once
+	dbClose := func() error {
+		var err error
+		dbCloseOnce.Do(func() { err = database.Close() })
+		return err
+	}
+	defer dbClose()
 
 	// Verify DB has expected tables
 	var tableName string
@@ -136,6 +144,50 @@ func main() {
 		log.Fatalf("[store] failed to load: %v", err)
 	}
 
+	// Initialize persisted neighbor graph
+	dbPath = database.path
+	if err := ensureNeighborEdgesTable(dbPath); err != nil {
+		log.Printf("[neighbor] warning: could not create neighbor_edges table: %v", err)
+	}
+	// Add resolved_path column if missing.
+	// NOTE on startup ordering (review item #10): ensureResolvedPathColumn runs AFTER
+	// OpenDB/detectSchema, so db.hasResolvedPath will be false on first run with a
+	// pre-existing DB. This means Load() won't SELECT resolved_path from SQLite.
+	// That's OK: backfillResolvedPaths (below) computes and persists them in-memory
+	// AND to SQLite. On next restart, detectSchema finds the column and Load() reads it.
+	if err := ensureResolvedPathColumn(dbPath); err != nil {
+		log.Printf("[store] warning: could not add resolved_path column: %v", err)
+	} else {
+		database.hasResolvedPath = true // detectSchema ran before column was added; fix the flag
+	}
+
+	// Load or build neighbor graph
+	if neighborEdgesTableExists(database.conn) {
+		store.graph = loadNeighborEdgesFromDB(database.conn)
+		log.Printf("[neighbor] loaded persisted neighbor graph")
+	} else {
+		log.Printf("[neighbor] no persisted edges found, building from store...")
+		rw, rwErr := openRW(dbPath)
+		if rwErr == nil {
+			edgeCount := buildAndPersistEdges(store, rw)
+			rw.Close()
+			log.Printf("[neighbor] persisted %d edges", edgeCount)
+		}
+		store.graph = BuildFromStore(store)
+	}
+
+	// Backfill resolved_path for observations that don't have it yet
+	if backfilled := backfillResolvedPaths(store, dbPath); backfilled > 0 {
+		log.Printf("[store] backfilled resolved_path for %d observations", backfilled)
+	}
+
+	// Re-pick best observation now that resolved paths are populated
+	store.mu.Lock()
+	for _, tx := range store.packets {
+		pickBestObservation(tx)
+	}
+	store.mu.Unlock()
+
 	// WebSocket hub
 	hub := NewHub()
 
@@ -171,6 +223,39 @@ func main() {
 	stopEviction := store.StartEvictionTicker()
 	defer stopEviction()
 
+	// Auto-prune old packets if retention.packetDays is configured
+	var stopPrune func()
+	if cfg.Retention != nil && cfg.Retention.PacketDays > 0 {
+		days := cfg.Retention.PacketDays
+		pruneTicker := time.NewTicker(24 * time.Hour)
+		pruneDone := make(chan struct{})
+		stopPrune = func() {
+			pruneTicker.Stop()
+			close(pruneDone)
+		}
+		go func() {
+			time.Sleep(1 * time.Minute)
+			if n, err := database.PruneOldPackets(days); err != nil {
+				log.Printf("[prune] error: %v", err)
+			} else {
+				log.Printf("[prune] deleted %d transmissions older than %d days", n, days)
+			}
+			for {
+				select {
+				case <-pruneTicker.C:
+					if n, err := database.PruneOldPackets(days); err != nil {
+						log.Printf("[prune] error: %v", err)
+					} else {
+						log.Printf("[prune] deleted %d transmissions older than %d days", n, days)
+					}
+				case <-pruneDone:
+					return
+				}
+			}
+		}()
+		log.Printf("[prune] auto-prune enabled: packets older than %d days will be removed daily", days)
+	}
+
 	// Graceful shutdown
 	httpServer := &http.Server{
 		Addr:         fmt.Sprintf(":%d", cfg.Port),
@@ -183,10 +268,32 @@ func main() {
 	go func() {
 		sigCh := make(chan os.Signal, 1)
 		signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
-		<-sigCh
-		log.Println("[server] shutting down...")
+		sig := <-sigCh
+		log.Printf("[server] received %v, shutting down...", sig)
+
+		// 1. Stop accepting new WebSocket/poll data
 		poller.Stop()
-		httpServer.Close()
+
+		// 1b. Stop auto-prune ticker
+		if stopPrune != nil {
+			stopPrune()
+		}
+
+		// 2. Gracefully drain HTTP connections (up to 15s)
+		ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+		defer cancel()
+		if err := httpServer.Shutdown(ctx); err != nil {
+			log.Printf("[server] HTTP shutdown error: %v", err)
+		}
+
+		// 3. Close WebSocket hub
+		hub.Close()
+
+		// 4. Close database (release SQLite WAL lock)
+		if err := dbClose(); err != nil {
+			log.Printf("[server] DB close error: %v", err)
+		}
+		log.Println("[server] shutdown complete")
 	}()
 
 	log.Printf("[server] CoreScope (Go) listening on http://localhost:%d", cfg.Port)
@@ -196,11 +303,35 @@ func main() {
 }
 
 // spaHandler serves static files, falling back to index.html for SPA routes.
+// It reads index.html once at creation time and replaces the __BUST__ placeholder
+// with a Unix timestamp so browsers fetch fresh JS/CSS after each server restart.
 func spaHandler(root string, fs http.Handler) http.Handler {
+	// Pre-process index.html: replace __BUST__ with a cache-bust timestamp
+	indexPath := filepath.Join(root, "index.html")
+	rawHTML, err := os.ReadFile(indexPath)
+	if err != nil {
+		log.Printf("[static] warning: could not read index.html for cache-bust: %v", err)
+		rawHTML = []byte("<!DOCTYPE html><html><body><h1>CoreScope</h1><p>index.html not found</p></body></html>")
+	}
+	bustValue := fmt.Sprintf("%d", time.Now().Unix())
+	indexHTML := []byte(strings.ReplaceAll(string(rawHTML), "__BUST__", bustValue))
+	log.Printf("[static] cache-bust value: %s", bustValue)
+
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Serve pre-processed index.html for root and /index.html
+		if r.URL.Path == "/" || r.URL.Path == "/index.html" {
+			w.Header().Set("Content-Type", "text/html; charset=utf-8")
+			w.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate")
+			w.Write(indexHTML)
+			return
+		}
+
 		path := filepath.Join(root, r.URL.Path)
 		if _, err := os.Stat(path); os.IsNotExist(err) {
-			http.ServeFile(w, r, filepath.Join(root, "index.html"))
+			// SPA fallback — serve pre-processed index.html
+			w.Header().Set("Content-Type", "text/html; charset=utf-8")
+			w.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate")
+			w.Write(indexHTML)
 			return
 		}
 		// Disable caching for JS/CSS/HTML

cmd/server/neighbor_api.go

@@ -0,0 +1,362 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gorilla/mux"
+)
+
+// ─── Neighbor API response types ───────────────────────────────────────────────
+
+type NeighborResponse struct {
+	Node              string             `json:"node"`
+	Neighbors         []NeighborEntry    `json:"neighbors"`
+	TotalObservations int                `json:"total_observations"`
+}
+
+type NeighborEntry struct {
+	Pubkey     *string           `json:"pubkey"`
+	Prefix     string            `json:"prefix"`
+	Name       *string           `json:"name"`
+	Role       *string           `json:"role"`
+	Count      int               `json:"count"`
+	Score      float64           `json:"score"`
+	FirstSeen  string            `json:"first_seen"`
+	LastSeen   string            `json:"last_seen"`
+	AvgSNR     *float64          `json:"avg_snr"`
+	Observers  []string          `json:"observers"`
+	Ambiguous  bool              `json:"ambiguous"`
+	Unresolved bool              `json:"unresolved,omitempty"`
+	Candidates []CandidateEntry  `json:"candidates,omitempty"`
+}
+
+type CandidateEntry struct {
+	Pubkey string  `json:"pubkey"`
+	Name   string  `json:"name"`
+	Role   string  `json:"role"`
+}
+
+type NeighborGraphResponse struct {
+	Nodes []GraphNode `json:"nodes"`
+	Edges []GraphEdge `json:"edges"`
+	Stats GraphStats  `json:"stats"`
+}
+
+type GraphNode struct {
+	Pubkey        string `json:"pubkey"`
+	Name          string `json:"name"`
+	Role          string `json:"role"`
+	NeighborCount int    `json:"neighbor_count"`
+}
+
+type GraphEdge struct {
+	Source        string   `json:"source"`
+	Target        string   `json:"target"`
+	Weight        int      `json:"weight"`
+	Score         float64  `json:"score"`
+	Bidirectional bool     `json:"bidirectional"`
+	AvgSNR        *float64 `json:"avg_snr"`
+	Ambiguous     bool     `json:"ambiguous"`
+}
+
+type GraphStats struct {
+	TotalNodes     int     `json:"total_nodes"`
+	TotalEdges     int     `json:"total_edges"`
+	AmbiguousEdges int     `json:"ambiguous_edges"`
+	AvgClusterSize float64 `json:"avg_cluster_size"`
+}
+
+// ─── Graph accessor on Server ──────────────────────────────────────────────────
+
+// getNeighborGraph returns the current neighbor graph, rebuilding if stale.
+func (s *Server) getNeighborGraph() *NeighborGraph {
+	s.neighborMu.Lock()
+	defer s.neighborMu.Unlock()
+
+	if s.neighborGraph == nil || s.neighborGraph.IsStale() {
+		if s.store != nil {
+			debugLog := s.cfg != nil && s.cfg.DebugAffinity
+			s.neighborGraph = BuildFromStoreWithLog(s.store, debugLog)
+		} else {
+			s.neighborGraph = NewNeighborGraph()
+		}
+	}
+	return s.neighborGraph
+}
+
+// ─── Handlers ──────────────────────────────────────────────────────────────────
+
+func (s *Server) handleNodeNeighbors(w http.ResponseWriter, r *http.Request) {
+	pubkey := strings.ToLower(mux.Vars(r)["pubkey"])
+
+	minCount := 1
+	if v := r.URL.Query().Get("min_count"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			minCount = n
+		}
+	}
+	minScore := 0.0
+	if v := r.URL.Query().Get("min_score"); v != "" {
+		if f, err := strconv.ParseFloat(v, 64); err == nil {
+			minScore = f
+		}
+	}
+	includeAmbiguous := true
+	if v := r.URL.Query().Get("include_ambiguous"); v == "false" {
+		includeAmbiguous = false
+	}
+
+	graph := s.getNeighborGraph()
+	edges := graph.Neighbors(pubkey)
+	now := time.Now()
+
+	// Build node info lookup for names/roles.
+	nodeMap := s.buildNodeInfoMap()
+
+	var entries []NeighborEntry
+	totalObs := 0
+
+	for _, e := range edges {
+		score := e.Score(now)
+		if e.Count < minCount || score < minScore {
+			continue
+		}
+		if e.Ambiguous && !includeAmbiguous {
+			continue
+		}
+
+		totalObs += e.Count
+
+		// Determine the "other" node (neighbor of the queried pubkey).
+		neighborPK := e.NodeA
+		if strings.EqualFold(neighborPK, pubkey) {
+			neighborPK = e.NodeB
+		}
+
+		entry := NeighborEntry{
+			Prefix:    e.Prefix,
+			Count:     e.Count,
+			Score:     score,
+			FirstSeen: e.FirstSeen.UTC().Format(time.RFC3339),
+			LastSeen:  e.LastSeen.UTC().Format(time.RFC3339),
+			Ambiguous: e.Ambiguous,
+			Observers: observerList(e.Observers),
+		}
+
+		if e.SNRCount > 0 {
+			avg := e.AvgSNR()
+			entry.AvgSNR = &avg
+		}
+
+		if e.Ambiguous {
+			if len(e.Candidates) == 0 {
+				entry.Unresolved = true
+			}
+			for _, cpk := range e.Candidates {
+				ce := CandidateEntry{Pubkey: cpk}
+				if info, ok := nodeMap[strings.ToLower(cpk)]; ok {
+					ce.Name = info.Name
+					ce.Role = info.Role
+				}
+				entry.Candidates = append(entry.Candidates, ce)
+			}
+		} else if neighborPK != "" {
+			entry.Pubkey = &neighborPK
+			if info, ok := nodeMap[strings.ToLower(neighborPK)]; ok {
+				entry.Name = &info.Name
+				entry.Role = &info.Role
+			}
+		}
+
+		entries = append(entries, entry)
+	}
+
+	// Sort by score descending.
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].Score > entries[j].Score
+	})
+
+	if entries == nil {
+		entries = []NeighborEntry{}
+	}
+
+	resp := NeighborResponse{
+		Node:              pubkey,
+		Neighbors:         entries,
+		TotalObservations: totalObs,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+func (s *Server) handleNeighborGraph(w http.ResponseWriter, r *http.Request) {
+	minCount := 5
+	if v := r.URL.Query().Get("min_count"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			minCount = n
+		}
+	}
+	minScore := 0.1
+	if v := r.URL.Query().Get("min_score"); v != "" {
+		if f, err := strconv.ParseFloat(v, 64); err == nil {
+			minScore = f
+		}
+	}
+	region := r.URL.Query().Get("region")
+	roleFilter := strings.ToLower(r.URL.Query().Get("role"))
+
+	graph := s.getNeighborGraph()
+	allEdges := graph.AllEdges()
+	now := time.Now()
+
+	// Resolve region observers if filtering.
+	var regionObs map[string]bool
+	if region != "" && s.store != nil {
+		regionObs = s.store.resolveRegionObservers(region)
+	}
+
+	nodeMap := s.buildNodeInfoMap()
+	nodeSet := make(map[string]bool)
+	var filteredEdges []GraphEdge
+	ambiguousCount := 0
+
+	for _, e := range allEdges {
+		score := e.Score(now)
+		if e.Count < minCount || score < minScore {
+			continue
+		}
+
+		// Role filter: at least one endpoint must match the role.
+		if roleFilter != "" && nodeMap != nil {
+			aInfo, aOK := nodeMap[strings.ToLower(e.NodeA)]
+			bInfo, bOK := nodeMap[strings.ToLower(e.NodeB)]
+			aMatch := aOK && strings.EqualFold(aInfo.Role, roleFilter)
+			bMatch := bOK && strings.EqualFold(bInfo.Role, roleFilter)
+			if !aMatch && !bMatch {
+				continue
+			}
+		}
+
+		// Region filter: at least one observer must be in the region.
+		if regionObs != nil {
+			match := false
+			for obs := range e.Observers {
+				if regionObs[obs] {
+					match = true
+					break
+				}
+			}
+			if !match {
+				continue
+			}
+		}
+
+		ge := GraphEdge{
+			Source:        e.NodeA,
+			Target:        e.NodeB,
+			Weight:        e.Count,
+			Score:         score,
+			Bidirectional: true,
+			Ambiguous:     e.Ambiguous,
+		}
+		if e.SNRCount > 0 {
+			avg := e.AvgSNR()
+			ge.AvgSNR = &avg
+		}
+
+		if e.Ambiguous {
+			ambiguousCount++
+			// For ambiguous edges, use prefix as target.
+			if e.NodeB == "" {
+				ge.Target = "prefix:" + e.Prefix
+			}
+		}
+
+		filteredEdges = append(filteredEdges, ge)
+
+		// Track nodes.
+		if e.NodeA != "" && !strings.HasPrefix(e.NodeA, "prefix:") {
+			nodeSet[e.NodeA] = true
+		}
+		if e.NodeB != "" && !strings.HasPrefix(e.NodeB, "prefix:") {
+			nodeSet[e.NodeB] = true
+		}
+	}
+
+	// Build node list.
+	// Count neighbors per node from filtered edges.
+	neighborCounts := make(map[string]int)
+	for _, ge := range filteredEdges {
+		neighborCounts[ge.Source]++
+		neighborCounts[ge.Target]++
+	}
+
+	var nodes []GraphNode
+	for pk := range nodeSet {
+		gn := GraphNode{Pubkey: pk, NeighborCount: neighborCounts[pk]}
+		if info, ok := nodeMap[strings.ToLower(pk)]; ok {
+			gn.Name = info.Name
+			gn.Role = info.Role
+		}
+		nodes = append(nodes, gn)
+	}
+
+	if filteredEdges == nil {
+		filteredEdges = []GraphEdge{}
+	}
+	if nodes == nil {
+		nodes = []GraphNode{}
+	}
+
+	avgCluster := 0.0
+	if len(nodes) > 0 {
+		avgCluster = float64(len(filteredEdges)*2) / float64(len(nodes))
+	}
+
+	resp := NeighborGraphResponse{
+		Nodes: nodes,
+		Edges: filteredEdges,
+		Stats: GraphStats{
+			TotalNodes:     len(nodes),
+			TotalEdges:     len(filteredEdges),
+			AmbiguousEdges: ambiguousCount,
+			AvgClusterSize: avgCluster,
+		},
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+func observerList(m map[string]bool) []string {
+	if len(m) == 0 {
+		return []string{}
+	}
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// buildNodeInfoMap returns a map of lowercase pubkey → nodeInfo for name/role lookups.
+func (s *Server) buildNodeInfoMap() map[string]nodeInfo {
+	if s.store == nil {
+		return nil
+	}
+	nodes, _ := s.store.getCachedNodesAndPM()
+	m := make(map[string]nodeInfo, len(nodes))
+	for _, n := range nodes {
+		m[strings.ToLower(n.PublicKey)] = n
+	}
+	return m
+}

cmd/server/neighbor_api_test.go

@@ -0,0 +1,396 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gorilla/mux"
+)
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+// makeTestServer creates a Server with a pre-built neighbor graph for testing.
+func makeTestServer(graph *NeighborGraph) *Server {
+	srv := &Server{
+		perfStats: NewPerfStats(),
+	}
+	srv.neighborGraph = graph
+	return srv
+}
+
+// makeTestGraph creates a graph with given edges for testing.
+func makeTestGraph(edges ...*NeighborEdge) *NeighborGraph {
+	g := NewNeighborGraph()
+	g.mu.Lock()
+	for _, e := range edges {
+		key := makeEdgeKey(e.NodeA, e.NodeB)
+		if e.NodeB == "" {
+			key = makeEdgeKey(e.NodeA, "prefix:"+e.Prefix)
+		}
+		e.NodeA = key.A
+		if e.NodeB != "" {
+			e.NodeB = key.B
+		}
+		g.edges[key] = e
+		g.byNode[key.A] = append(g.byNode[key.A], e)
+		if key.B != "" && key.B != key.A {
+			g.byNode[key.B] = append(g.byNode[key.B], e)
+		}
+	}
+	g.builtAt = time.Now()
+	g.mu.Unlock()
+	return g
+}
+
+func newEdge(a, b, prefix string, count int, lastSeen time.Time) *NeighborEdge {
+	return &NeighborEdge{
+		NodeA:     a,
+		NodeB:     b,
+		Prefix:    prefix,
+		Count:     count,
+		FirstSeen: lastSeen.Add(-24 * time.Hour),
+		LastSeen:  lastSeen,
+		Observers: map[string]bool{"obs1": true},
+		SNRSum:    -8.0,
+		SNRCount:  1,
+	}
+}
+
+func newAmbiguousEdge(knownPK, prefix string, candidates []string, count int, lastSeen time.Time) *NeighborEdge {
+	return &NeighborEdge{
+		NodeA:      knownPK,
+		NodeB:      "",
+		Prefix:     prefix,
+		Count:      count,
+		FirstSeen:  lastSeen.Add(-24 * time.Hour),
+		LastSeen:   lastSeen,
+		Observers:  map[string]bool{"obs1": true},
+		Ambiguous:  true,
+		Candidates: candidates,
+	}
+}
+
+func serveRequest(srv *Server, method, path string) *httptest.ResponseRecorder {
+	router := mux.NewRouter()
+	router.HandleFunc("/api/nodes/{pubkey}/neighbors", srv.handleNodeNeighbors).Methods("GET")
+	router.HandleFunc("/api/analytics/neighbor-graph", srv.handleNeighborGraph).Methods("GET")
+
+	req := httptest.NewRequest(method, path, nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+	return rr
+}
+
+// ─── Tests: /api/nodes/{pubkey}/neighbors ──────────────────────────────────────
+
+func TestNeighborAPI_EmptyGraph(t *testing.T) {
+	srv := makeTestServer(makeTestGraph())
+	rr := serveRequest(srv, "GET", "/api/nodes/deadbeef/neighbors")
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", rr.Code)
+	}
+
+	var resp NeighborResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("bad JSON: %v", err)
+	}
+	if resp.Node != "deadbeef" {
+		t.Errorf("node = %q, want deadbeef", resp.Node)
+	}
+	if len(resp.Neighbors) != 0 {
+		t.Errorf("expected 0 neighbors, got %d", len(resp.Neighbors))
+	}
+	if resp.TotalObservations != 0 {
+		t.Errorf("expected 0 observations, got %d", resp.TotalObservations)
+	}
+}
+
+func TestNeighborAPI_SingleNeighbor(t *testing.T) {
+	now := time.Now()
+	e := newEdge("aaaa", "bbbb", "bb", 50, now)
+	srv := makeTestServer(makeTestGraph(e))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/aaaa/neighbors")
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", rr.Code)
+	}
+
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Neighbors) != 1 {
+		t.Fatalf("expected 1 neighbor, got %d", len(resp.Neighbors))
+	}
+	n := resp.Neighbors[0]
+	if n.Pubkey == nil || *n.Pubkey != "bbbb" {
+		t.Errorf("expected pubkey bbbb, got %v", n.Pubkey)
+	}
+	if n.Count != 50 {
+		t.Errorf("expected count 50, got %d", n.Count)
+	}
+	if n.Score <= 0 {
+		t.Errorf("expected positive score, got %f", n.Score)
+	}
+	if n.Ambiguous {
+		t.Error("expected not ambiguous")
+	}
+}
+
+func TestNeighborAPI_MultipleNeighbors(t *testing.T) {
+	now := time.Now()
+	e1 := newEdge("aaaa", "bbbb", "bb", 100, now)
+	e2 := newEdge("aaaa", "cccc", "cc", 10, now)
+	srv := makeTestServer(makeTestGraph(e1, e2))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/aaaa/neighbors")
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Neighbors) != 2 {
+		t.Fatalf("expected 2 neighbors, got %d", len(resp.Neighbors))
+	}
+	// Should be sorted by score descending.
+	if resp.Neighbors[0].Score < resp.Neighbors[1].Score {
+		t.Error("expected sorted by score descending")
+	}
+	if resp.TotalObservations != 110 {
+		t.Errorf("expected 110 total observations, got %d", resp.TotalObservations)
+	}
+}
+
+func TestNeighborAPI_AmbiguousCandidates(t *testing.T) {
+	now := time.Now()
+	e := newAmbiguousEdge("aaaa", "c0", []string{"c0de01", "c0de02"}, 12, now)
+	srv := makeTestServer(makeTestGraph(e))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/aaaa/neighbors")
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Neighbors) != 1 {
+		t.Fatalf("expected 1 neighbor, got %d", len(resp.Neighbors))
+	}
+	n := resp.Neighbors[0]
+	if !n.Ambiguous {
+		t.Error("expected ambiguous")
+	}
+	if n.Pubkey != nil {
+		t.Errorf("expected nil pubkey for ambiguous, got %v", n.Pubkey)
+	}
+	if len(n.Candidates) != 2 {
+		t.Fatalf("expected 2 candidates, got %d", len(n.Candidates))
+	}
+}
+
+func TestNeighborAPI_UnresolvedPrefix(t *testing.T) {
+	now := time.Now()
+	e := newAmbiguousEdge("aaaa", "ff", []string{}, 3, now)
+	srv := makeTestServer(makeTestGraph(e))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/aaaa/neighbors")
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Neighbors) != 1 {
+		t.Fatalf("expected 1 neighbor, got %d", len(resp.Neighbors))
+	}
+	n := resp.Neighbors[0]
+	if !n.Unresolved {
+		t.Error("expected unresolved=true")
+	}
+	if len(n.Candidates) != 0 {
+		t.Error("expected empty candidates for unresolved")
+	}
+}
+
+func TestNeighborAPI_MinCountFilter(t *testing.T) {
+	now := time.Now()
+	e1 := newEdge("aaaa", "bbbb", "bb", 100, now)
+	e2 := newEdge("aaaa", "cccc", "cc", 2, now)
+	srv := makeTestServer(makeTestGraph(e1, e2))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/aaaa/neighbors?min_count=10")
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Neighbors) != 1 {
+		t.Fatalf("expected 1 neighbor after min_count filter, got %d", len(resp.Neighbors))
+	}
+	if *resp.Neighbors[0].Pubkey != "bbbb" {
+		t.Error("expected bbbb to survive filter")
+	}
+}
+
+func TestNeighborAPI_MinScoreFilter(t *testing.T) {
+	now := time.Now()
+	e1 := newEdge("aaaa", "bbbb", "bb", 100, now)                               // score ~1.0
+	e2 := newEdge("aaaa", "cccc", "cc", 1, now.Add(-30*24*time.Hour)) // very low score
+	srv := makeTestServer(makeTestGraph(e1, e2))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/aaaa/neighbors?min_score=0.5")
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Neighbors) != 1 {
+		t.Fatalf("expected 1 neighbor after min_score filter, got %d", len(resp.Neighbors))
+	}
+}
+
+func TestNeighborAPI_ExcludeAmbiguous(t *testing.T) {
+	now := time.Now()
+	e1 := newEdge("aaaa", "bbbb", "bb", 50, now)
+	e2 := newAmbiguousEdge("aaaa", "c0", []string{"c0de01"}, 10, now)
+	srv := makeTestServer(makeTestGraph(e1, e2))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/aaaa/neighbors?include_ambiguous=false")
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Neighbors) != 1 {
+		t.Fatalf("expected 1 non-ambiguous neighbor, got %d", len(resp.Neighbors))
+	}
+}
+
+func TestNeighborAPI_UnknownNode(t *testing.T) {
+	now := time.Now()
+	e := newEdge("aaaa", "bbbb", "bb", 50, now)
+	srv := makeTestServer(makeTestGraph(e))
+
+	rr := serveRequest(srv, "GET", "/api/nodes/unknown1234/neighbors")
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200 for unknown node, got %d", rr.Code)
+	}
+
+	var resp NeighborResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+	if len(resp.Neighbors) != 0 {
+		t.Errorf("expected 0 neighbors for unknown node, got %d", len(resp.Neighbors))
+	}
+}
+
+// ─── Tests: /api/analytics/neighbor-graph ──────────────────────────────────────
+
+func TestNeighborGraphAPI_EmptyGraph(t *testing.T) {
+	srv := makeTestServer(makeTestGraph())
+	rr := serveRequest(srv, "GET", "/api/analytics/neighbor-graph")
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", rr.Code)
+	}
+
+	var resp NeighborGraphResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Edges) != 0 {
+		t.Errorf("expected 0 edges, got %d", len(resp.Edges))
+	}
+	if resp.Stats.TotalEdges != 0 {
+		t.Errorf("expected 0 total edges, got %d", resp.Stats.TotalEdges)
+	}
+	if resp.Stats.TotalNodes != 0 {
+		t.Errorf("expected 0 total nodes, got %d", resp.Stats.TotalNodes)
+	}
+}
+
+func TestNeighborGraphAPI_WithEdges(t *testing.T) {
+	now := time.Now()
+	e1 := newEdge("aaaa", "bbbb", "bb", 100, now)
+	e2 := newEdge("bbbb", "cccc", "cc", 50, now)
+	srv := makeTestServer(makeTestGraph(e1, e2))
+
+	rr := serveRequest(srv, "GET", "/api/analytics/neighbor-graph?min_count=1&min_score=0")
+	var resp NeighborGraphResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Edges) != 2 {
+		t.Fatalf("expected 2 edges, got %d", len(resp.Edges))
+	}
+	if resp.Stats.TotalNodes != 3 {
+		t.Errorf("expected 3 nodes, got %d", resp.Stats.TotalNodes)
+	}
+	if resp.Stats.TotalEdges != 2 {
+		t.Errorf("expected 2 total edges, got %d", resp.Stats.TotalEdges)
+	}
+}
+
+func TestNeighborGraphAPI_MinCountDefault(t *testing.T) {
+	now := time.Now()
+	e1 := newEdge("aaaa", "bbbb", "bb", 100, now) // passes default min_count=5
+	e2 := newEdge("aaaa", "cccc", "cc", 2, now)   // fails default min_count=5
+	srv := makeTestServer(makeTestGraph(e1, e2))
+
+	rr := serveRequest(srv, "GET", "/api/analytics/neighbor-graph")
+	var resp NeighborGraphResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if len(resp.Edges) != 1 {
+		t.Fatalf("expected 1 edge with default min_count=5, got %d", len(resp.Edges))
+	}
+}
+
+func TestNeighborGraphAPI_AmbiguousEdgesCount(t *testing.T) {
+	now := time.Now()
+	e1 := newEdge("aaaa", "bbbb", "bb", 100, now)
+	e2 := newAmbiguousEdge("aaaa", "c0", []string{"c0de01", "c0de02"}, 50, now)
+	srv := makeTestServer(makeTestGraph(e1, e2))
+
+	rr := serveRequest(srv, "GET", "/api/analytics/neighbor-graph?min_count=1&min_score=0")
+	var resp NeighborGraphResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	if resp.Stats.AmbiguousEdges != 1 {
+		t.Errorf("expected 1 ambiguous edge, got %d", resp.Stats.AmbiguousEdges)
+	}
+}
+
+func TestNeighborGraphAPI_RegionFilter(t *testing.T) {
+	now := time.Now()
+	// Edge with observer "obs-sjc" — would match region SJC if we had region resolution.
+	// Without a store, region filtering returns nothing (no observers match).
+	e1 := newEdge("aaaa", "bbbb", "bb", 100, now)
+	srv := makeTestServer(makeTestGraph(e1))
+	// No store → region filter has no observers → filters everything out.
+	rr := serveRequest(srv, "GET", "/api/analytics/neighbor-graph?region=SJC&min_count=1&min_score=0")
+	var resp NeighborGraphResponse
+	json.Unmarshal(rr.Body.Bytes(), &resp)
+
+	// With no store, regionObs is nil so filter is skipped → all edges returned.
+	// Actually: region="" when store is nil → regionObs stays nil → no filtering.
+	// Wait, we set region=SJC and store is nil → resolveRegionObservers won't be called
+	// because s.store is nil. So regionObs is nil → filter not applied.
+	// Let's just check it doesn't crash.
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", rr.Code)
+	}
+}
+
+func TestNeighborGraphAPI_ResponseShape(t *testing.T) {
+	now := time.Now()
+	e := newEdge("aaaa", "bbbb", "bb", 100, now)
+	srv := makeTestServer(makeTestGraph(e))
+
+	rr := serveRequest(srv, "GET", "/api/analytics/neighbor-graph?min_count=1&min_score=0")
+	var raw map[string]interface{}
+	if err := json.Unmarshal(rr.Body.Bytes(), &raw); err != nil {
+		t.Fatalf("bad JSON: %v", err)
+	}
+
+	// Verify top-level keys.
+	for _, key := range []string{"nodes", "edges", "stats"} {
+		if _, ok := raw[key]; !ok {
+			t.Errorf("missing key %q in response", key)
+		}
+	}
+
+	// Verify stats keys.
+	stats := raw["stats"].(map[string]interface{})
+	for _, key := range []string{"total_nodes", "total_edges", "ambiguous_edges", "avg_cluster_size"} {
+		if _, ok := stats[key]; !ok {
+			t.Errorf("missing stats key %q", key)
+		}
+	}
+}

cmd/server/neighbor_debug.go

@@ -0,0 +1,399 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"math"
+	"net/http"
+	"sort"
+	"strings"
+	"time"
+)
+
+// ─── Debug API response types ──────────────────────────────────────────────────
+
+type DebugAffinityResponse struct {
+	Edges       []DebugEdge       `json:"edges"`
+	Resolutions []DebugResolution `json:"resolutions"`
+	Stats       DebugStats        `json:"stats"`
+}
+
+type DebugEdge struct {
+	NodeA            string   `json:"nodeA"`
+	NodeAName        string   `json:"nodeAName,omitempty"`
+	NodeB            string   `json:"nodeB"`
+	NodeBName        string   `json:"nodeBName,omitempty"`
+	Prefix           string   `json:"prefix"`
+	Weight           int      `json:"weight"`
+	ObservationCount int      `json:"observationCount"`
+	LastSeen         string   `json:"lastSeen"`
+	FirstSeen        string   `json:"firstSeen"`
+	Score            float64  `json:"score"`
+	Jaccard          float64  `json:"jaccard,omitempty"`
+	AvgSNR           *float64 `json:"avgSnr,omitempty"`
+	Observers        []string `json:"observers"`
+	Ambiguous        bool     `json:"ambiguous"`
+	Unresolved       bool     `json:"unresolved,omitempty"`
+	Resolved         bool     `json:"resolved,omitempty"`
+}
+
+type DebugResolution struct {
+	Prefix           string             `json:"prefix"`
+	Chosen           string             `json:"chosen,omitempty"`
+	ChosenName       string             `json:"chosenName,omitempty"`
+	ChosenScore      int                `json:"chosenScore"`
+	ChosenJaccard    float64            `json:"chosenJaccard"`
+	Confidence       string             `json:"confidence"`
+	Candidates       []DebugCandidate   `json:"candidates"`
+	Ratio            float64            `json:"ratio"`
+	ThresholdApplied float64            `json:"thresholdApplied"`
+	Method           string             `json:"method"`
+	Tier             string             `json:"tier"`
+	KnownNode        string             `json:"knownNode"`
+	KnownNodeName    string             `json:"knownNodeName,omitempty"`
+}
+
+type DebugCandidate struct {
+	Pubkey  string  `json:"pubkey"`
+	Name    string  `json:"name,omitempty"`
+	Score   int     `json:"score"`
+	Jaccard float64 `json:"jaccard"`
+}
+
+type DebugStats struct {
+	TotalEdges       int     `json:"totalEdges"`
+	TotalNodes       int     `json:"totalNodes"`
+	ResolvedCount    int     `json:"resolvedCount"`
+	AmbiguousCount   int     `json:"ambiguousCount"`
+	UnresolvedCount  int     `json:"unresolvedCount"`
+	AvgConfidence    float64 `json:"avgConfidence"`
+	ColdStartCoverage float64 `json:"coldStartCoverage"`
+	CacheAge         string  `json:"cacheAge"`
+	LastRebuild      string  `json:"lastRebuild"`
+}
+
+// ─── Debug API Handler ─────────────────────────────────────────────────────────
+
+func (s *Server) handleDebugAffinity(w http.ResponseWriter, r *http.Request) {
+	prefixFilter := strings.ToLower(r.URL.Query().Get("prefix"))
+	nodeFilter := strings.ToLower(r.URL.Query().Get("node"))
+
+	graph := s.getNeighborGraph()
+	now := time.Now()
+	nodeMap := s.buildNodeInfoMap()
+
+	allEdges := graph.AllEdges()
+
+	// Build edges response
+	var debugEdges []DebugEdge
+	nodeSet := make(map[string]bool)
+	resolvedCount := 0
+	ambiguousCount := 0
+	unresolvedCount := 0
+	var scoreSum float64
+	var scoreCount int
+
+	for _, e := range allEdges {
+		// Apply filters
+		if prefixFilter != "" && !strings.EqualFold(e.Prefix, prefixFilter) {
+			continue
+		}
+		if nodeFilter != "" {
+			if !strings.EqualFold(e.NodeA, nodeFilter) && !strings.EqualFold(e.NodeB, nodeFilter) {
+				// Also check if any candidate matches
+				found := false
+				for _, c := range e.Candidates {
+					if strings.EqualFold(c, nodeFilter) {
+						found = true
+						break
+					}
+				}
+				if !found {
+					continue
+				}
+			}
+		}
+
+		score := e.Score(now)
+		de := DebugEdge{
+			NodeA:            e.NodeA,
+			NodeB:            e.NodeB,
+			Prefix:           e.Prefix,
+			Weight:           e.Count,
+			ObservationCount: e.Count,
+			LastSeen:         e.LastSeen.UTC().Format(time.RFC3339),
+			FirstSeen:        e.FirstSeen.UTC().Format(time.RFC3339),
+			Score:            math.Round(score*1000) / 1000,
+			Observers:        observerList(e.Observers),
+			Ambiguous:        e.Ambiguous,
+			Resolved:         e.Resolved,
+		}
+
+		if e.SNRCount > 0 {
+			avg := e.AvgSNR()
+			de.AvgSNR = &avg
+		}
+
+		// Add names
+		if nodeMap != nil {
+			if info, ok := nodeMap[strings.ToLower(e.NodeA)]; ok {
+				de.NodeAName = info.Name
+			}
+			if info, ok := nodeMap[strings.ToLower(e.NodeB)]; ok {
+				de.NodeBName = info.Name
+			}
+		}
+
+		if e.Ambiguous {
+			if len(e.Candidates) == 0 {
+				de.Unresolved = true
+				unresolvedCount++
+			} else {
+				ambiguousCount++
+			}
+		} else {
+			resolvedCount++
+			scoreSum += score
+			scoreCount++
+		}
+
+		debugEdges = append(debugEdges, de)
+
+		if e.NodeA != "" && !strings.HasPrefix(e.NodeA, "prefix:") {
+			nodeSet[e.NodeA] = true
+		}
+		if e.NodeB != "" && !strings.HasPrefix(e.NodeB, "prefix:") {
+			nodeSet[e.NodeB] = true
+		}
+	}
+
+	// Build resolutions from the graph's disambiguation history
+	resolutions := s.buildResolutions(graph, nodeMap, prefixFilter, nodeFilter)
+
+	// Cold-start coverage: % of 1-byte prefixes with ≥3 observations
+	coldStart := s.computeColdStartCoverage(allEdges)
+
+	avgConf := 0.0
+	if scoreCount > 0 {
+		avgConf = math.Round(scoreSum/float64(scoreCount)*1000) / 1000
+	}
+
+	if debugEdges == nil {
+		debugEdges = []DebugEdge{}
+	}
+	if resolutions == nil {
+		resolutions = []DebugResolution{}
+	}
+
+	// Sort edges by weight descending
+	sort.Slice(debugEdges, func(i, j int) bool {
+		return debugEdges[i].Weight > debugEdges[j].Weight
+	})
+
+	graph.mu.RLock()
+	builtAt := graph.builtAt
+	graph.mu.RUnlock()
+
+	cacheAge := ""
+	lastRebuild := ""
+	if !builtAt.IsZero() {
+		cacheAge = fmt.Sprintf("%.1fs", time.Since(builtAt).Seconds())
+		lastRebuild = builtAt.UTC().Format(time.RFC3339)
+	}
+
+	resp := DebugAffinityResponse{
+		Edges:       debugEdges,
+		Resolutions: resolutions,
+		Stats: DebugStats{
+			TotalEdges:        len(debugEdges),
+			TotalNodes:        len(nodeSet),
+			ResolvedCount:     resolvedCount,
+			AmbiguousCount:    ambiguousCount,
+			UnresolvedCount:   unresolvedCount,
+			AvgConfidence:     avgConf,
+			ColdStartCoverage: coldStart,
+			CacheAge:          cacheAge,
+			LastRebuild:       lastRebuild,
+		},
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+// buildResolutions generates per-prefix resolution decision logs.
+// It uses resolveWithContext (M4) to show the actual 4-tier fallback path
+// (affinity → geo → GPS → first_match) for each prefix resolution.
+func (s *Server) buildResolutions(graph *NeighborGraph, nodeMap map[string]nodeInfo, prefixFilter, nodeFilter string) []DebugResolution {
+	graph.mu.RLock()
+	defer graph.mu.RUnlock()
+
+	// Get the prefix map for resolveWithContext tier computation.
+	var pm *prefixMap
+	if s.store != nil {
+		_, pm = s.store.getCachedNodesAndPM()
+	}
+
+	// Build resolved neighbor sets for Jaccard computation
+	resolvedNeighbors := make(map[string]map[string]bool)
+	for _, e := range graph.edges {
+		if e.Ambiguous || e.NodeB == "" {
+			continue
+		}
+		if resolvedNeighbors[e.NodeA] == nil {
+			resolvedNeighbors[e.NodeA] = make(map[string]bool)
+		}
+		if resolvedNeighbors[e.NodeB] == nil {
+			resolvedNeighbors[e.NodeB] = make(map[string]bool)
+		}
+		resolvedNeighbors[e.NodeA][e.NodeB] = true
+		resolvedNeighbors[e.NodeB][e.NodeA] = true
+	}
+
+	var resolutions []DebugResolution
+
+	for _, e := range graph.edges {
+		// Show resolution info for both resolved (auto-resolved) and ambiguous edges
+		if !e.Resolved && !e.Ambiguous {
+			continue
+		}
+		if len(e.Candidates) < 2 && !e.Resolved {
+			continue
+		}
+
+		if prefixFilter != "" && !strings.EqualFold(e.Prefix, prefixFilter) {
+			continue
+		}
+
+		knownNode := e.NodeA
+		if strings.HasPrefix(e.NodeA, "prefix:") {
+			knownNode = e.NodeB
+		}
+
+		if nodeFilter != "" && !strings.EqualFold(knownNode, nodeFilter) {
+			// Check if the resolved node matches
+			if e.Resolved && !strings.EqualFold(e.NodeB, nodeFilter) && !strings.EqualFold(e.NodeA, nodeFilter) {
+				continue
+			}
+		}
+
+		knownNeighbors := resolvedNeighbors[knownNode]
+
+		var candidates []DebugCandidate
+		candList := e.Candidates
+		// For resolved edges, add the resolved node as a candidate too
+		if e.Resolved {
+			resolvedPK := e.NodeB
+			if strings.EqualFold(e.NodeB, knownNode) {
+				resolvedPK = e.NodeA
+			}
+			// Include resolved + original candidates
+			found := false
+			for _, c := range candList {
+				if strings.EqualFold(c, resolvedPK) {
+					found = true
+					break
+				}
+			}
+			if !found {
+				candList = append([]string{resolvedPK}, candList...)
+			}
+		}
+
+		for _, cpk := range candList {
+			candNeighbors := resolvedNeighbors[cpk]
+			j := jaccardSimilarity(knownNeighbors, candNeighbors)
+			dc := DebugCandidate{
+				Pubkey:  cpk,
+				Score:   e.Count,
+				Jaccard: math.Round(j*1000) / 1000,
+			}
+			if nodeMap != nil {
+				if info, ok := nodeMap[strings.ToLower(cpk)]; ok {
+					dc.Name = info.Name
+				}
+			}
+			candidates = append(candidates, dc)
+		}
+
+		// Sort candidates by Jaccard descending
+		sort.Slice(candidates, func(i, j int) bool {
+			return candidates[i].Jaccard > candidates[j].Jaccard
+		})
+
+		dr := DebugResolution{
+			Prefix:           e.Prefix,
+			ThresholdApplied: affinityConfidenceRatio,
+			KnownNode:        knownNode,
+		}
+
+		if nodeMap != nil {
+			if info, ok := nodeMap[strings.ToLower(knownNode)]; ok {
+				dr.KnownNodeName = info.Name
+			}
+		}
+
+		// Use resolveWithContext to determine the actual 4-tier fallback path.
+		tier := ""
+		if pm != nil {
+			contextPubkeys := []string{knownNode}
+			_, tierUsed, _ := pm.resolveWithContext(e.Prefix, contextPubkeys, graph)
+			tier = tierUsed
+		}
+
+		if e.Resolved && len(candidates) > 0 {
+			dr.Chosen = candidates[0].Pubkey
+			dr.ChosenName = candidates[0].Name
+			dr.ChosenScore = candidates[0].Score
+			dr.ChosenJaccard = candidates[0].Jaccard
+			dr.Confidence = "HIGH"
+			dr.Method = "auto-resolved"
+			dr.Tier = tier
+			if len(candidates) > 1 && candidates[1].Jaccard > 0 {
+				dr.Ratio = math.Round(candidates[0].Jaccard/candidates[1].Jaccard*10) / 10
+			} else if candidates[0].Jaccard > 0 {
+				dr.Ratio = 999.0 // effectively infinite — JSON doesn't support Infinity
+			}
+		} else {
+			dr.Confidence = "AMBIGUOUS"
+			dr.Method = "ambiguous"
+			dr.Tier = tier
+			if len(candidates) >= 2 {
+				dr.ChosenScore = candidates[0].Score
+				dr.ChosenJaccard = candidates[0].Jaccard
+				if candidates[1].Jaccard > 0 {
+					dr.Ratio = math.Round(candidates[0].Jaccard/candidates[1].Jaccard*10) / 10
+				}
+			}
+		}
+		dr.Candidates = candidates
+
+		resolutions = append(resolutions, dr)
+	}
+
+	return resolutions
+}
+
+// computeColdStartCoverage returns the % of active 1-byte hex prefixes with ≥3 observations.
+func (s *Server) computeColdStartCoverage(edges []*NeighborEdge) float64 {
+	// Track which 1-byte prefixes have sufficient observations
+	prefixObs := make(map[string]int) // 1-byte prefix → total observations
+	for _, e := range edges {
+		if len(e.Prefix) == 2 { // 1-byte = 2 hex chars
+			prefixObs[strings.ToLower(e.Prefix)] += e.Count
+		}
+	}
+
+	if len(prefixObs) == 0 {
+		return 0
+	}
+
+	covered := 0
+	for _, count := range prefixObs {
+		if count >= affinityMinObservations {
+			covered++
+		}
+	}
+
+	return math.Round(float64(covered)/float64(len(prefixObs))*1000) / 10
+}

cmd/server/neighbor_debug_test.go

@@ -0,0 +1,223 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestDebugAffinityEndpoint(t *testing.T) {
+	now := time.Now()
+
+	edge1 := newEdge("aaaa1111", "bbbb2222", "bb", 50, now)
+	edge2 := newEdge("aaaa1111", "", "cc", 10, now)
+	edge2.Ambiguous = true
+	edge2.Candidates = []string{"cccc3333", "cccc4444"}
+
+	graph := makeTestGraph(edge1, edge2)
+	srv := makeTestServer(graph)
+	srv.cfg = &Config{APIKey: "test-key", DebugAffinity: true}
+
+	r, _ := http.NewRequest("GET", "/api/debug/affinity", nil)
+	r.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.handleDebugAffinity(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var resp DebugAffinityResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode error: %v", err)
+	}
+
+	if len(resp.Edges) != 2 {
+		t.Errorf("expected 2 edges, got %d", len(resp.Edges))
+	}
+
+	// Check stats shape
+	if resp.Stats.TotalEdges != 2 {
+		t.Errorf("expected 2 total edges in stats, got %d", resp.Stats.TotalEdges)
+	}
+	if resp.Stats.LastRebuild == "" {
+		t.Error("expected lastRebuild to be set")
+	}
+	if resp.Stats.CacheAge == "" {
+		t.Error("expected cacheAge to be set")
+	}
+}
+
+func TestDebugAffinityPrefixFilter(t *testing.T) {
+	now := time.Now()
+	edge1 := newEdge("aaaa1111", "bbbb2222", "bb", 50, now)
+	edge2 := newEdge("aaaa1111", "dddd3333", "dd", 30, now)
+
+	graph := makeTestGraph(edge1, edge2)
+	srv := makeTestServer(graph)
+	srv.cfg = &Config{APIKey: "test-key"}
+
+	r, _ := http.NewRequest("GET", "/api/debug/affinity?prefix=bb", nil)
+	r.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.handleDebugAffinity(w, r)
+
+	var resp DebugAffinityResponse
+	json.NewDecoder(w.Body).Decode(&resp)
+
+	if len(resp.Edges) != 1 {
+		t.Errorf("expected 1 edge with prefix filter, got %d", len(resp.Edges))
+	}
+}
+
+func TestDebugAffinityNodeFilter(t *testing.T) {
+	now := time.Now()
+	edge1 := newEdge("aaaa1111", "bbbb2222", "bb", 50, now)
+	edge2 := newEdge("cccc3333", "dddd4444", "dd", 30, now)
+
+	graph := makeTestGraph(edge1, edge2)
+	srv := makeTestServer(graph)
+	srv.cfg = &Config{APIKey: "test-key"}
+
+	r, _ := http.NewRequest("GET", "/api/debug/affinity?node=aaaa1111", nil)
+	r.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.handleDebugAffinity(w, r)
+
+	var resp DebugAffinityResponse
+	json.NewDecoder(w.Body).Decode(&resp)
+
+	if len(resp.Edges) != 1 {
+		t.Errorf("expected 1 edge with node filter, got %d", len(resp.Edges))
+	}
+}
+
+func TestDebugAffinityRequiresAuth(t *testing.T) {
+	graph := makeTestGraph()
+	srv := makeTestServer(graph)
+	srv.cfg = &Config{APIKey: "secret"}
+
+	r, _ := http.NewRequest("GET", "/api/debug/affinity", nil)
+	r.Header.Set("X-API-Key", "wrong-key")
+	w := httptest.NewRecorder()
+
+	// Use the requireAPIKey middleware
+	handler := srv.requireAPIKey(http.HandlerFunc(srv.handleDebugAffinity))
+	handler.ServeHTTP(w, r)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("expected 401, got %d", w.Code)
+	}
+}
+
+func TestStructuredLogging(t *testing.T) {
+	// Test that the logging function in the graph actually works
+	var logMessages []string
+	g := NewNeighborGraph()
+	g.logFn = func(prefix, msg string) {
+		logMessages = append(logMessages, "[affinity] resolve "+prefix+": "+msg)
+	}
+
+	// Add some edges that would trigger disambiguation
+	now := time.Now()
+	// Add resolved edges for neighbor sets
+	g.mu.Lock()
+	// Node aaaa has neighbors: xxxx, yyyy
+	e1 := &NeighborEdge{NodeA: "aaaa", NodeB: "xxxx", Prefix: "xx", Count: 10, Observers: map[string]bool{}, FirstSeen: now, LastSeen: now}
+	g.edges[makeEdgeKey("aaaa", "xxxx")] = e1
+	g.byNode["aaaa"] = append(g.byNode["aaaa"], e1)
+	g.byNode["xxxx"] = append(g.byNode["xxxx"], e1)
+
+	e2 := &NeighborEdge{NodeA: "aaaa", NodeB: "yyyy", Prefix: "yy", Count: 10, Observers: map[string]bool{}, FirstSeen: now, LastSeen: now}
+	g.edges[makeEdgeKey("aaaa", "yyyy")] = e2
+	g.byNode["aaaa"] = append(g.byNode["aaaa"], e2)
+	g.byNode["yyyy"] = append(g.byNode["yyyy"], e2)
+
+	// Candidate cccc1 also has neighbor xxxx, yyyy (high Jaccard with aaaa)
+	e3 := &NeighborEdge{NodeA: "cccc1", NodeB: "xxxx", Prefix: "xx", Count: 10, Observers: map[string]bool{}, FirstSeen: now, LastSeen: now}
+	g.edges[makeEdgeKey("cccc1", "xxxx")] = e3
+	g.byNode["cccc1"] = append(g.byNode["cccc1"], e3)
+
+	e4 := &NeighborEdge{NodeA: "cccc1", NodeB: "yyyy", Prefix: "yy", Count: 10, Observers: map[string]bool{}, FirstSeen: now, LastSeen: now}
+	g.edges[makeEdgeKey("cccc1", "yyyy")] = e4
+	g.byNode["cccc1"] = append(g.byNode["cccc1"], e4)
+
+	// Candidate cccc2 has no neighbors (low Jaccard)
+	// Add ambiguous edge: aaaa ↔ prefix:cc with candidates [cccc1, cccc2]
+	ambigEdge := &NeighborEdge{
+		NodeA: "aaaa", NodeB: "", Prefix: "cc", Count: 5,
+		Ambiguous: true, Candidates: []string{"cccc1", "cccc2"},
+		Observers: map[string]bool{}, FirstSeen: now, LastSeen: now,
+	}
+	ambigKey := makeEdgeKey("aaaa", "prefix:cc")
+	g.edges[ambigKey] = ambigEdge
+	g.byNode["aaaa"] = append(g.byNode["aaaa"], ambigEdge)
+	g.mu.Unlock()
+
+	// Now run disambiguate — this should trigger logging
+	g.disambiguate()
+
+	if len(logMessages) == 0 {
+		t.Error("expected at least one log message from disambiguation")
+	}
+
+	found := false
+	for _, msg := range logMessages {
+		if strings.Contains(msg, "[affinity] resolve cc:") {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected log message about prefix 'cc', got: %v", logMessages)
+	}
+}
+
+func TestColdStartCoverage(t *testing.T) {
+	edges := []*NeighborEdge{
+		{Prefix: "aa", Count: 5},
+		{Prefix: "bb", Count: 3},
+		{Prefix: "cc", Count: 1}, // below threshold
+	}
+
+	srv := &Server{cfg: &Config{}}
+	coverage := srv.computeColdStartCoverage(edges)
+
+	// 2 out of 3 prefixes have >=3 observations = 66.7%
+	if coverage < 66.0 || coverage > 67.0 {
+		t.Errorf("expected ~66.7%% coverage, got %.1f%%", coverage)
+	}
+}
+
+func TestDebugResponseShape(t *testing.T) {
+	edge := newEdge("aaaa1111", "bbbb2222", "bb", 50, time.Now())
+	edge.Resolved = true
+
+	graph := makeTestGraph(edge)
+	srv := makeTestServer(graph)
+	srv.cfg = &Config{APIKey: "test-key"}
+
+	r, _ := http.NewRequest("GET", "/api/debug/affinity", nil)
+	r.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.handleDebugAffinity(w, r)
+
+	var resp map[string]interface{}
+	json.NewDecoder(w.Body).Decode(&resp)
+
+	// Verify top-level keys
+	for _, key := range []string{"edges", "resolutions", "stats"} {
+		if _, ok := resp[key]; !ok {
+			t.Errorf("missing top-level key: %s", key)
+		}
+	}
+
+	stats := resp["stats"].(map[string]interface{})
+	for _, key := range []string{"totalEdges", "totalNodes", "resolvedCount", "ambiguousCount", "unresolvedCount", "avgConfidence", "coldStartCoverage", "cacheAge", "lastRebuild"} {
+		if _, ok := stats[key]; !ok {
+			t.Errorf("missing stats key: %s", key)
+		}
+	}
+}

cmd/server/neighbor_graph.go

@@ -0,0 +1,544 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"math"
+	"strings"
+	"sync"
+	"time"
+)
+
+// ─── Constants ─────────────────────────────────────────────────────────────────
+
+const (
+	// After this many observations, count contributes max weight to the score.
+	affinitySaturationCount = 100
+	// Time-decay half-life: 7 days.
+	affinityHalfLifeHours = 168.0
+	// Cache TTL for the built graph.
+	neighborGraphTTL = 5 * time.Minute
+	// Auto-resolve confidence: best must be >= this factor × second-best.
+	affinityConfidenceRatio = 3.0
+	// Minimum observation count to auto-resolve.
+	affinityMinObservations = 3
+)
+
+// affinityLambda = ln(2) / half-life-hours, precomputed.
+var affinityLambda = math.Ln2 / affinityHalfLifeHours
+
+// ─── Data model ────────────────────────────────────────────────────────────────
+
+// edgeKey is the canonical key for an undirected edge (A < B lexicographically).
+// For ambiguous edges where NodeB is unknown, B is the raw prefix prefixed with "prefix:".
+type edgeKey struct {
+	A, B string
+}
+
+func makeEdgeKey(a, b string) edgeKey {
+	if a > b {
+		a, b = b, a
+	}
+	return edgeKey{A: a, B: b}
+}
+
+// NeighborEdge represents a weighted, undirected first-hop neighbor relationship.
+type NeighborEdge struct {
+	NodeA      string            // full pubkey
+	NodeB      string            // full pubkey, or "" if unresolved/ambiguous
+	Prefix     string            // raw hop prefix that established this edge
+	Count      int               // total observations
+	FirstSeen  time.Time         //
+	LastSeen   time.Time         //
+	SNRSum     float64           // running sum for average
+	SNRCount   int               // how many SNR samples
+	Observers  map[string]bool   // observer pubkeys that witnessed
+	Ambiguous  bool              // multiple candidates or zero candidates
+	Candidates []string          // candidate pubkeys when ambiguous
+	Resolved   bool              // true if auto-resolved via Jaccard
+}
+
+// Score computes the affinity score at query time with time decay.
+func (e *NeighborEdge) Score(now time.Time) float64 {
+	countFactor := math.Min(1.0, float64(e.Count)/float64(affinitySaturationCount))
+	hoursSince := now.Sub(e.LastSeen).Hours()
+	if hoursSince < 0 {
+		hoursSince = 0
+	}
+	decay := math.Exp(-affinityLambda * hoursSince)
+	return countFactor * decay
+}
+
+// AvgSNR returns the average SNR, or 0 if no samples.
+func (e *NeighborEdge) AvgSNR() float64 {
+	if e.SNRCount == 0 {
+		return 0
+	}
+	return e.SNRSum / float64(e.SNRCount)
+}
+
+// ─── NeighborGraph ─────────────────────────────────────────────────────────────
+
+// NeighborGraph is a cached, in-memory first-hop neighbor affinity graph.
+type NeighborGraph struct {
+	mu      sync.RWMutex
+	edges   map[edgeKey]*NeighborEdge
+	byNode  map[string][]*NeighborEdge // pubkey → edges involving this node
+	builtAt time.Time
+	logFn   func(prefix, msg string) // optional structured logging callback
+}
+
+// NewNeighborGraph creates an empty graph.
+func NewNeighborGraph() *NeighborGraph {
+	return &NeighborGraph{
+		edges:  make(map[edgeKey]*NeighborEdge),
+		byNode: make(map[string][]*NeighborEdge),
+	}
+}
+
+// Neighbors returns all edges for a given node pubkey.
+func (g *NeighborGraph) Neighbors(pubkey string) []*NeighborEdge {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	return g.byNode[strings.ToLower(pubkey)]
+}
+
+// AllEdges returns all edges in the graph.
+func (g *NeighborGraph) AllEdges() []*NeighborEdge {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	out := make([]*NeighborEdge, 0, len(g.edges))
+	for _, e := range g.edges {
+		out = append(out, e)
+	}
+	return out
+}
+
+// IsStale returns true if the graph cache has expired.
+func (g *NeighborGraph) IsStale() bool {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	return g.builtAt.IsZero() || time.Since(g.builtAt) > neighborGraphTTL
+}
+
+// ─── Builder ───────────────────────────────────────────────────────────────────
+
+// BuildFromStore constructs the neighbor graph from all packets in the store.
+// The store's read-lock must NOT be held by the caller.
+func BuildFromStore(store *PacketStore) *NeighborGraph {
+	return BuildFromStoreWithLog(store, false)
+}
+
+// cachedToLower returns strings.ToLower(s), caching results to avoid
+// repeated allocations for the same pubkey string.
+func cachedToLower(cache map[string]string, s string) string {
+	if v, ok := cache[s]; ok {
+		return v
+	}
+	v := strings.ToLower(s)
+	cache[s] = v
+	return v
+}
+
+// BuildFromStoreWithLog constructs the neighbor graph, optionally logging disambiguation decisions.
+func BuildFromStoreWithLog(store *PacketStore, enableLog bool) *NeighborGraph {
+	g := NewNeighborGraph()
+	if enableLog {
+		g.logFn = func(prefix, msg string) {
+			log.Printf("[affinity] resolve %s: %s", prefix, msg)
+		}
+	}
+
+	store.mu.RLock()
+	// Snapshot what we need under lock.
+	packets := make([]*StoreTx, len(store.packets))
+	copy(packets, store.packets)
+	store.mu.RUnlock()
+
+	// Build prefix map for candidate resolution.
+	// Use cached nodes+PM (avoids DB call if cache is fresh).
+	_, pm := store.getCachedNodesAndPM()
+
+	// Local cache for strings.ToLower — pubkeys are immutable and repeat
+	// across hundreds of thousands of observations.
+	lowerCache := make(map[string]string, 256)
+
+	// Phase 1: Extract edges from every transmission + observation.
+	for _, tx := range packets {
+		isAdvert := tx.PayloadType != nil && *tx.PayloadType == 4
+		fromNode := extractFromNode(tx)
+		// Pre-compute lowered originator once per tx (not per observation).
+		fromLower := ""
+		if fromNode != "" {
+			fromLower = cachedToLower(lowerCache, fromNode)
+		}
+
+		for _, obs := range tx.Observations {
+			path := parsePathJSON(obs.PathJSON)
+			observerPK := cachedToLower(lowerCache, obs.ObserverID)
+
+			if len(path) == 0 {
+				// Zero-hop
+				if isAdvert && fromLower != "" {
+					if fromLower != observerPK { // self-edge guard
+						g.upsertEdge(fromLower, observerPK, "", observerPK, obs.SNR, parseTimestamp(obs.Timestamp))
+					}
+				}
+				continue
+			}
+
+			// Edge 1: originator ↔ path[0] — ADVERTs only
+			if isAdvert && fromLower != "" {
+				firstHop := cachedToLower(lowerCache, path[0])
+				if fromLower != firstHop { // self-edge guard (shouldn't happen but spec says check)
+					candidates := pm.m[firstHop]
+					g.upsertEdgeWithCandidates(fromLower, firstHop, candidates, observerPK, obs.SNR, parseTimestamp(obs.Timestamp), lowerCache)
+				}
+			}
+
+			// Edge 2: observer ↔ path[last] — ALL packet types
+			lastHop := cachedToLower(lowerCache, path[len(path)-1])
+			if observerPK != lastHop { // self-edge guard
+				candidates := pm.m[lastHop]
+				g.upsertEdgeWithCandidates(observerPK, lastHop, candidates, observerPK, obs.SNR, parseTimestamp(obs.Timestamp), lowerCache)
+			}
+		}
+	}
+
+	// Phase 2: Disambiguation via Jaccard similarity.
+	g.disambiguate()
+
+	g.mu.Lock()
+	g.builtAt = time.Now()
+	g.mu.Unlock()
+
+	return g
+}
+
+// extractFromNode pulls the originator pubkey from a StoreTx's DecodedJSON.
+// ADVERTs use "pubKey", other packets may use "from_node" or "from".
+// Uses the cached ParsedDecoded() accessor to avoid repeated json.Unmarshal.
+func extractFromNode(tx *StoreTx) string {
+	decoded := tx.ParsedDecoded()
+	if decoded == nil {
+		return ""
+	}
+	// ADVERTs store the originator pubkey as "pubKey"; other packets may use
+	// "from_node" or "from".  Check all three so we never miss the originator.
+	for _, field := range []string{"pubKey", "from_node", "from"} {
+		if v, ok := decoded[field]; ok {
+			if s, ok := v.(string); ok && s != "" {
+				return s
+			}
+		}
+	}
+	return ""
+}
+
+// jsonUnmarshalFast is a thin wrapper; could be optimized later.
+func jsonUnmarshalFast(data string, v interface{}) error {
+	return json.Unmarshal([]byte(data), v)
+}
+
+// upsertEdge adds/updates an edge between two fully-known pubkeys.
+func (g *NeighborGraph) upsertEdge(pubkeyA, pubkeyB, prefix, observer string, snr *float64, ts time.Time) {
+	key := makeEdgeKey(pubkeyA, pubkeyB)
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	e, exists := g.edges[key]
+	if !exists {
+		e = &NeighborEdge{
+			NodeA:     key.A,
+			NodeB:     key.B,
+			Prefix:    prefix,
+			Observers: make(map[string]bool),
+			FirstSeen: ts,
+			LastSeen:  ts,
+		}
+		g.edges[key] = e
+		g.byNode[key.A] = append(g.byNode[key.A], e)
+		g.byNode[key.B] = append(g.byNode[key.B], e)
+	}
+
+	e.Count++
+	if ts.After(e.LastSeen) {
+		e.LastSeen = ts
+	}
+	if ts.Before(e.FirstSeen) {
+		e.FirstSeen = ts
+	}
+	if snr != nil {
+		e.SNRSum += *snr
+		e.SNRCount++
+	}
+	if observer != "" {
+		e.Observers[observer] = true
+	}
+}
+
+// upsertEdgeWithCandidates handles prefix-based edges that may be ambiguous.
+func (g *NeighborGraph) upsertEdgeWithCandidates(knownPK, prefix string, candidates []nodeInfo, observer string, snr *float64, ts time.Time, lc map[string]string) {
+	if len(candidates) == 1 {
+		resolved := cachedToLower(lc, candidates[0].PublicKey)
+		if resolved == knownPK {
+			return // self-edge guard
+		}
+		g.upsertEdge(knownPK, resolved, prefix, observer, snr, ts)
+		return
+	}
+
+	// Filter out self from candidates
+	filtered := make([]string, 0, len(candidates))
+	for _, c := range candidates {
+		pk := cachedToLower(lc, c.PublicKey)
+		if pk != knownPK {
+			filtered = append(filtered, pk)
+		}
+	}
+
+	if len(filtered) == 1 {
+		g.upsertEdge(knownPK, filtered[0], prefix, observer, snr, ts)
+		return
+	}
+
+	// Ambiguous or orphan: use prefix-based key
+	pseudoB := "prefix:" + prefix
+	key := makeEdgeKey(knownPK, pseudoB)
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	e, exists := g.edges[key]
+	if !exists {
+		e = &NeighborEdge{
+			NodeA:      key.A,
+			NodeB:      "",
+			Prefix:     prefix,
+			Observers:  make(map[string]bool),
+			Ambiguous:  true,
+			Candidates: filtered,
+			FirstSeen:  ts,
+			LastSeen:   ts,
+		}
+		g.edges[key] = e
+		g.byNode[knownPK] = append(g.byNode[knownPK], e)
+	}
+
+	e.Count++
+	if ts.After(e.LastSeen) {
+		e.LastSeen = ts
+	}
+	if ts.Before(e.FirstSeen) {
+		e.FirstSeen = ts
+	}
+	if snr != nil {
+		e.SNRSum += *snr
+		e.SNRCount++
+	}
+	if observer != "" {
+		e.Observers[observer] = true
+	}
+}
+
+// ─── Disambiguation ────────────────────────────────────────────────────────────
+
+// disambiguate resolves ambiguous edges using Jaccard similarity of neighbor sets.
+// Only fully-resolved edges are used as evidence (transitivity poisoning guard).
+func (g *NeighborGraph) disambiguate() {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	// Build resolved neighbor sets: for each node, collect the set of nodes
+	// it has fully-resolved (non-ambiguous) edges with.
+	resolvedNeighbors := make(map[string]map[string]bool)
+	for _, e := range g.edges {
+		if e.Ambiguous || e.NodeB == "" {
+			continue
+		}
+		if resolvedNeighbors[e.NodeA] == nil {
+			resolvedNeighbors[e.NodeA] = make(map[string]bool)
+		}
+		if resolvedNeighbors[e.NodeB] == nil {
+			resolvedNeighbors[e.NodeB] = make(map[string]bool)
+		}
+		resolvedNeighbors[e.NodeA][e.NodeB] = true
+		resolvedNeighbors[e.NodeB][e.NodeA] = true
+	}
+
+	// Try to resolve each ambiguous edge.
+	for key, e := range g.edges {
+		if !e.Ambiguous || len(e.Candidates) < 2 {
+			continue
+		}
+		if e.Count < affinityMinObservations {
+			continue
+		}
+
+		// Determine the known node (the one that's a real pubkey, not the prefix side).
+		knownNode := e.NodeA
+		if strings.HasPrefix(e.NodeA, "prefix:") {
+			knownNode = e.NodeB
+		}
+		// If knownNode is empty (shouldn't happen for ambiguous edges with candidates), skip.
+		if knownNode == "" {
+			continue
+		}
+
+		knownNeighbors := resolvedNeighbors[knownNode]
+
+		type scored struct {
+			pubkey  string
+			jaccard float64
+		}
+		var scores []scored
+
+		for _, cand := range e.Candidates {
+			candNeighbors := resolvedNeighbors[cand]
+			j := jaccardSimilarity(knownNeighbors, candNeighbors)
+			scores = append(scores, scored{cand, j})
+		}
+
+		if len(scores) < 2 {
+			continue
+		}
+
+		// Find best and second-best.
+		best, secondBest := scores[0], scores[1]
+		if secondBest.jaccard > best.jaccard {
+			best, secondBest = secondBest, best
+		}
+		for i := 2; i < len(scores); i++ {
+			if scores[i].jaccard > best.jaccard {
+				secondBest = best
+				best = scores[i]
+			} else if scores[i].jaccard > secondBest.jaccard {
+				secondBest = scores[i]
+			}
+		}
+
+		// Auto-resolve only if best >= 3× second-best AND enough observations.
+		if secondBest.jaccard == 0 {
+			// If second-best is 0 and best > 0, ratio is infinite → resolve.
+			if best.jaccard > 0 {
+				if g.logFn != nil {
+					g.logFn(e.Prefix, fmt.Sprintf("%s score=%d Jaccard=%.2f vs %s score=%d Jaccard=%.2f → neighbor_affinity (ratio ∞)",
+						best.pubkey[:minLen(best.pubkey, 8)], e.Count, best.jaccard,
+						secondBest.pubkey[:minLen(secondBest.pubkey, 8)], e.Count, secondBest.jaccard))
+				}
+				g.resolveEdge(key, e, knownNode, best.pubkey)
+			}
+		} else if best.jaccard/secondBest.jaccard >= affinityConfidenceRatio {
+			ratio := best.jaccard / secondBest.jaccard
+			if g.logFn != nil {
+				g.logFn(e.Prefix, fmt.Sprintf("%s score=%d Jaccard=%.2f vs %s score=%d Jaccard=%.2f → neighbor_affinity (ratio %.1f×)",
+					best.pubkey[:minLen(best.pubkey, 8)], e.Count, best.jaccard,
+					secondBest.pubkey[:minLen(secondBest.pubkey, 8)], e.Count, secondBest.jaccard, ratio))
+			}
+			g.resolveEdge(key, e, knownNode, best.pubkey)
+		} else {
+			// Ambiguous
+			if g.logFn != nil {
+				ratio := 0.0
+				if secondBest.jaccard > 0 {
+					ratio = best.jaccard / secondBest.jaccard
+				}
+				g.logFn(e.Prefix, fmt.Sprintf("scores too close (Jaccard %.2f vs %.2f, ratio %.1f×) → ambiguous, returning %d candidates",
+					best.jaccard, secondBest.jaccard, ratio, len(e.Candidates)))
+			}
+		}
+	}
+}
+
+// resolveEdge converts an ambiguous edge to a resolved one.
+// Must be called with g.mu held.
+func (g *NeighborGraph) resolveEdge(oldKey edgeKey, e *NeighborEdge, knownNode, resolvedPK string) {
+	// Remove old edge.
+	delete(g.edges, oldKey)
+	g.removeFromByNode(oldKey.A, e)
+	g.removeFromByNode(oldKey.B, e)
+
+	// Update edge.
+	newKey := makeEdgeKey(knownNode, resolvedPK)
+	e.NodeA = newKey.A
+	e.NodeB = newKey.B
+	e.Ambiguous = false
+	e.Resolved = true
+
+	// Merge with existing edge if any.
+	if existing, ok := g.edges[newKey]; ok {
+		existing.Count += e.Count
+		if e.LastSeen.After(existing.LastSeen) {
+			existing.LastSeen = e.LastSeen
+		}
+		if e.FirstSeen.Before(existing.FirstSeen) {
+			existing.FirstSeen = e.FirstSeen
+		}
+		existing.SNRSum += e.SNRSum
+		existing.SNRCount += e.SNRCount
+		for obs := range e.Observers {
+			existing.Observers[obs] = true
+		}
+		return
+	}
+
+	g.edges[newKey] = e
+	g.byNode[newKey.A] = append(g.byNode[newKey.A], e)
+	g.byNode[newKey.B] = append(g.byNode[newKey.B], e)
+}
+
+// removeFromByNode removes an edge from the byNode index for the given key.
+func (g *NeighborGraph) removeFromByNode(nodeKey string, edge *NeighborEdge) {
+	edges := g.byNode[nodeKey]
+	for i, e := range edges {
+		if e == edge {
+			g.byNode[nodeKey] = append(edges[:i], edges[i+1:]...)
+			return
+		}
+	}
+}
+
+// jaccardSimilarity computes |A ∩ B| / |A ∪ B|.
+func jaccardSimilarity(a, b map[string]bool) float64 {
+	if len(a) == 0 && len(b) == 0 {
+		return 0
+	}
+	intersection := 0
+	for k := range a {
+		if b[k] {
+			intersection++
+		}
+	}
+	union := len(a) + len(b) - intersection
+	if union == 0 {
+		return 0
+	}
+	return float64(intersection) / float64(union)
+}
+
+// parseTimestamp parses a timestamp string into time.Time.
+func parseTimestamp(s string) time.Time {
+	// Try common formats.
+	for _, fmt := range []string{
+		time.RFC3339,
+		"2006-01-02T15:04:05Z",
+		"2006-01-02 15:04:05",
+		"2006-01-02T15:04:05.000Z",
+	} {
+		if t, err := time.Parse(fmt, s); err == nil {
+			return t
+		}
+	}
+	return time.Time{}
+}
+
+
+// minLen returns the smaller of n and len(s).
+func minLen(s string, n int) int {
+	if len(s) < n {
+		return len(s)
+	}
+	return n
+}

cmd/server/neighbor_graph_test.go

@@ -0,0 +1,836 @@
+package main
+
+import (
+	"encoding/json"
+	"math"
+	"testing"
+	"time"
+)
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+// ngTestStore creates a minimal PacketStore with injected nodes and packets.
+func ngTestStore(nodes []nodeInfo, packets []*StoreTx) *PacketStore {
+	if nodes == nil {
+		nodes = []nodeInfo{}
+	}
+	if packets == nil {
+		packets = []*StoreTx{}
+	}
+	ps := &PacketStore{
+		packets:        packets,
+		byHash:         make(map[string]*StoreTx),
+		byTxID:         make(map[int]*StoreTx),
+		byObsID:        make(map[int]*StoreObs),
+		byObserver:     make(map[string][]*StoreObs),
+		byNode:         make(map[string][]*StoreTx),
+		nodeHashes:     make(map[string]map[string]bool),
+		byPayloadType:  make(map[int][]*StoreTx),
+		rfCache:        make(map[string]*cachedResult),
+		topoCache:      make(map[string]*cachedResult),
+		hashCache:      make(map[string]*cachedResult),
+		collisionCache: make(map[string]*cachedResult),
+		chanCache:      make(map[string]*cachedResult),
+		distCache:      make(map[string]*cachedResult),
+		subpathCache:   make(map[string]*cachedResult),
+		spIndex:        make(map[string]int),
+	}
+	ps.nodeCache = nodes
+	ps.nodePM = buildPrefixMap(nodes)
+	ps.nodeCacheTime = time.Now().Add(1 * time.Hour)
+	return ps
+}
+
+func ngIntPtr(v int) *int         { return &v }
+func ngFloatPtr(v float64) *float64 { return &v }
+
+func ngMakeTx(id int, payloadType int, decodedJSON string, obs []*StoreObs) *StoreTx {
+	tx := &StoreTx{
+		ID:           id,
+		PayloadType:  ngIntPtr(payloadType),
+		DecodedJSON:  decodedJSON,
+		Observations: obs,
+	}
+	return tx
+}
+
+func ngMakeObs(observerID, pathJSON, timestamp string, snr *float64) *StoreObs {
+	return &StoreObs{
+		ObserverID: observerID,
+		PathJSON:   pathJSON,
+		Timestamp:  timestamp,
+		SNR:        snr,
+	}
+}
+
+func ngFromNodeJSON(pubkey string) string {
+	b, _ := json.Marshal(map[string]string{"from_node": pubkey})
+	return string(b)
+}
+
+var now = time.Now()
+var nowStr = now.UTC().Format(time.RFC3339)
+var weekAgoStr = now.Add(-7 * 24 * time.Hour).UTC().Format(time.RFC3339)
+var monthAgoStr = now.Add(-30 * 24 * time.Hour).UTC().Format(time.RFC3339)
+
+// ─── Tests ─────────────────────────────────────────────────────────────────────
+
+func TestBuildNeighborGraph_EmptyStore(t *testing.T) {
+	store := ngTestStore(nil, nil)
+	g := BuildFromStore(store)
+	if len(g.edges) != 0 {
+		t.Errorf("expected 0 edges, got %d", len(g.edges))
+	}
+}
+
+func TestBuildNeighborGraph_AdvertSingleHopPath(t *testing.T) {
+	// ADVERT from X, path=["R1_prefix"] → edges: X↔R1 and Observer↔R1
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["r1aa"]`, nowStr, ngFloatPtr(-10)),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	// Should have 2 edges: X↔R1 and Observer↔R1
+	// But since path has 1 element, path[0]==path[last], so for ADVERTs
+	// both edge types point to the same hop. X↔R1 and Obs↔R1 = 2 edges.
+	edges := g.AllEdges()
+	if len(edges) != 2 {
+		t.Fatalf("expected 2 edges, got %d", len(edges))
+	}
+
+	// Check X↔R1 exists
+	found := false
+	for _, e := range edges {
+		if (e.NodeA == "aaaa1111" && e.NodeB == "r1aabbcc") ||
+			(e.NodeA == "r1aabbcc" && e.NodeB == "aaaa1111") {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("missing originator↔path[0] edge (X↔R1)")
+	}
+
+	// Check Observer↔R1 exists
+	found = false
+	for _, e := range edges {
+		if (e.NodeA == "obs00001" && e.NodeB == "r1aabbcc") ||
+			(e.NodeA == "r1aabbcc" && e.NodeB == "obs00001") {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("missing observer↔path[last] edge (Observer↔R1)")
+	}
+}
+
+func TestBuildNeighborGraph_AdvertMultiHopPath(t *testing.T) {
+	// ADVERT from X, path=["R1","R2"] → X↔R1 and Observer↔R2
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "r2ddeeff", Name: "R2"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["r1aa","r2dd"]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	edges := g.AllEdges()
+	if len(edges) != 2 {
+		t.Fatalf("expected 2 edges, got %d", len(edges))
+	}
+
+	// X↔R1
+	hasXR1 := false
+	hasObsR2 := false
+	for _, e := range edges {
+		if (e.NodeA == "aaaa1111" && e.NodeB == "r1aabbcc") || (e.NodeA == "r1aabbcc" && e.NodeB == "aaaa1111") {
+			hasXR1 = true
+		}
+		if (e.NodeA == "obs00001" && e.NodeB == "r2ddeeff") || (e.NodeA == "r2ddeeff" && e.NodeB == "obs00001") {
+			hasObsR2 = true
+		}
+	}
+	if !hasXR1 {
+		t.Error("missing X↔R1 edge")
+	}
+	if !hasObsR2 {
+		t.Error("missing Observer↔R2 edge")
+	}
+}
+
+func TestBuildNeighborGraph_AdvertZeroHop(t *testing.T) {
+	// ADVERT from X, path=[] → X↔Observer direct edge
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `[]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	edges := g.AllEdges()
+	if len(edges) != 1 {
+		t.Fatalf("expected 1 edge, got %d", len(edges))
+	}
+	e := edges[0]
+	if !((e.NodeA == "aaaa1111" && e.NodeB == "obs00001") || (e.NodeA == "obs00001" && e.NodeB == "aaaa1111")) {
+		t.Errorf("expected X↔Observer edge, got %s↔%s", e.NodeA, e.NodeB)
+	}
+	if e.Ambiguous {
+		t.Error("zero-hop edge should not be ambiguous")
+	}
+}
+
+func TestBuildNeighborGraph_NonAdvertEmptyPath(t *testing.T) {
+	// Non-ADVERT, path=[] → no edges
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 2, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `[]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	if len(g.edges) != 0 {
+		t.Errorf("expected 0 edges for non-ADVERT empty path, got %d", len(g.edges))
+	}
+}
+
+func TestBuildNeighborGraph_NonAdvertOnlyObserverEdge(t *testing.T) {
+	// Non-ADVERT with path=["R1","R2"] → only Observer↔R2, NO originator edge
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "r2ddeeff", Name: "R2"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 2, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["r1aa","r2dd"]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	edges := g.AllEdges()
+	if len(edges) != 1 {
+		t.Fatalf("expected 1 edge, got %d", len(edges))
+	}
+	e := edges[0]
+	if !((e.NodeA == "obs00001" && e.NodeB == "r2ddeeff") || (e.NodeA == "r2ddeeff" && e.NodeB == "obs00001")) {
+		t.Errorf("expected Observer↔R2 edge, got %s↔%s", e.NodeA, e.NodeB)
+	}
+}
+
+func TestBuildNeighborGraph_NonAdvertSingleHop(t *testing.T) {
+	// Non-ADVERT with path=["R1"] → Observer↔R1 only
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 2, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["r1aa"]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	edges := g.AllEdges()
+	if len(edges) != 1 {
+		t.Fatalf("expected 1 edge, got %d", len(edges))
+	}
+	e := edges[0]
+	if !((e.NodeA == "obs00001" && e.NodeB == "r1aabbcc") || (e.NodeA == "r1aabbcc" && e.NodeB == "obs00001")) {
+		t.Errorf("expected Observer↔R1, got %s↔%s", e.NodeA, e.NodeB)
+	}
+}
+
+func TestBuildNeighborGraph_HashCollision(t *testing.T) {
+	// Two nodes share prefix "a3" → ambiguous edge
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "a3bb1111", Name: "CandidateA"},
+		{PublicKey: "a3bb2222", Name: "CandidateB"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["a3bb"]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	// Should have ambiguous edges
+	var ambigCount int
+	for _, e := range g.AllEdges() {
+		if e.Ambiguous {
+			ambigCount++
+			if len(e.Candidates) < 2 {
+				t.Errorf("expected >=2 candidates, got %d", len(e.Candidates))
+			}
+		}
+	}
+	if ambigCount == 0 {
+		t.Error("expected at least one ambiguous edge for hash collision")
+	}
+}
+
+func TestBuildNeighborGraph_JaccardScoring(t *testing.T) {
+	// Test Jaccard similarity computation directly
+	a := map[string]bool{"x": true, "y": true, "z": true}
+	b := map[string]bool{"y": true, "z": true, "w": true}
+	j := jaccardSimilarity(a, b)
+	// intersection = {y, z} = 2, union = {x, y, z, w} = 4 → 0.5
+	if math.Abs(j-0.5) > 0.001 {
+		t.Errorf("expected Jaccard 0.5, got %f", j)
+	}
+
+	// Empty sets
+	j = jaccardSimilarity(nil, nil)
+	if j != 0 {
+		t.Errorf("expected 0 for empty sets, got %f", j)
+	}
+}
+
+func TestBuildNeighborGraph_ConfidenceAutoResolve(t *testing.T) {
+	// Setup: NodeX has known neighbors N1, N2, N3 (resolved edges).
+	// CandidateA also has known neighbors N1, N2, N3 (high Jaccard with X).
+	// CandidateB has no known neighbors (Jaccard = 0).
+	// An ambiguous edge X↔prefix "a3" with candidates [A, B] should auto-resolve to A.
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "n1111111", Name: "N1"},
+		{PublicKey: "n2222222", Name: "N2"},
+		{PublicKey: "n3333333", Name: "N3"},
+		{PublicKey: "a3001111", Name: "CandidateA"},
+		{PublicKey: "a3002222", Name: "CandidateB"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+
+	// Create resolved edges: X↔N1, X↔N2, X↔N3, A↔N1, A↔N2, A↔N3
+	// Then an ambiguous edge X↔"a300" prefix with 3+ observations.
+	var txs []*StoreTx
+	txID := 1
+
+	// X sends ADVERTs through N1, N2, N3
+	for _, nhop := range []string{"n111", "n222", "n333"} {
+		txs = append(txs, ngMakeTx(txID, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+			ngMakeObs("obs00001", `["`+nhop+`"]`, nowStr, nil),
+		}))
+		txID++
+	}
+
+	// CandidateA sends ADVERTs through N1, N2, N3
+	for _, nhop := range []string{"n111", "n222", "n333"} {
+		txs = append(txs, ngMakeTx(txID, 4, ngFromNodeJSON("a3001111"), []*StoreObs{
+			ngMakeObs("obs00001", `["`+nhop+`"]`, nowStr, nil),
+		}))
+		txID++
+	}
+
+	// Ambiguous edge: X sends ADVERTs with path[0]="a300" (matches both candidates)
+	// Need 3+ observations for confidence threshold.
+	for i := 0; i < 3; i++ {
+		txs = append(txs, ngMakeTx(txID, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+			ngMakeObs("obs00001", `["a300"]`, nowStr, nil),
+		}))
+		txID++
+	}
+
+	store := ngTestStore(nodes, txs)
+	g := BuildFromStore(store)
+
+	// The ambiguous edge X↔a300 should have been resolved to CandidateA
+	neighbors := g.Neighbors("aaaa1111")
+	foundA := false
+	for _, e := range neighbors {
+		other := e.NodeB
+		if e.NodeA != "aaaa1111" {
+			other = e.NodeA
+		}
+		if other == "a3001111" {
+			foundA = true
+			if e.Ambiguous {
+				t.Error("edge should have been resolved (not ambiguous)")
+			}
+		}
+	}
+	if !foundA {
+		t.Error("expected edge X↔CandidateA to be auto-resolved")
+	}
+}
+
+func TestBuildNeighborGraph_EqualScoresAmbiguous(t *testing.T) {
+	// Two candidates with identical neighbor sets → should NOT auto-resolve.
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "n1111111", Name: "N1"},
+		{PublicKey: "a3001111", Name: "CandidateA"},
+		{PublicKey: "a3002222", Name: "CandidateB"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+
+	var txs []*StoreTx
+	txID := 1
+
+	// X↔N1
+	txs = append(txs, ngMakeTx(txID, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["n111"]`, nowStr, nil),
+	}))
+	txID++
+
+	// Both candidates have same neighbor (N1)
+	txs = append(txs, ngMakeTx(txID, 4, ngFromNodeJSON("a3001111"), []*StoreObs{
+		ngMakeObs("obs00001", `["n111"]`, nowStr, nil),
+	}))
+	txID++
+	txs = append(txs, ngMakeTx(txID, 4, ngFromNodeJSON("a3002222"), []*StoreObs{
+		ngMakeObs("obs00001", `["n111"]`, nowStr, nil),
+	}))
+	txID++
+
+	// Ambiguous edge with 3+ observations
+	for i := 0; i < 3; i++ {
+		txs = append(txs, ngMakeTx(txID, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+			ngMakeObs("obs00001", `["a300"]`, nowStr, nil),
+		}))
+		txID++
+	}
+
+	store := ngTestStore(nodes, txs)
+	g := BuildFromStore(store)
+
+	// Should remain ambiguous
+	var ambigFound bool
+	for _, e := range g.AllEdges() {
+		if e.Ambiguous && e.Prefix == "a300" {
+			ambigFound = true
+		}
+	}
+	if !ambigFound {
+		t.Error("expected ambiguous edge to remain unresolved with equal scores")
+	}
+}
+
+func TestBuildNeighborGraph_ObserverSelfEdgeGuard(t *testing.T) {
+	// Observer's own prefix in path → should NOT create self-edge.
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["obs0"]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	// Check no self-edge for observer
+	for _, e := range g.AllEdges() {
+		if e.NodeA == e.NodeB && e.NodeA == "obs00001" {
+			t.Error("self-edge created for observer")
+		}
+	}
+}
+
+func TestBuildNeighborGraph_OrphanPrefix(t *testing.T) {
+	// Path contains prefix matching zero nodes → edge recorded as unresolved.
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["ff99"]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	// Should have ambiguous edges with empty candidates.
+	var orphanFound bool
+	for _, e := range g.AllEdges() {
+		if e.Ambiguous && len(e.Candidates) == 0 {
+			orphanFound = true
+			if e.Prefix != "ff99" {
+				t.Errorf("expected prefix ff99, got %s", e.Prefix)
+			}
+		}
+	}
+	if !orphanFound {
+		t.Error("expected orphan prefix edge with empty candidates")
+	}
+}
+
+func TestAffinityScore_Fresh(t *testing.T) {
+	e := &NeighborEdge{Count: 100, LastSeen: time.Now()}
+	s := e.Score(time.Now())
+	if s < 0.99 || s > 1.0 {
+		t.Errorf("expected score ≈ 1.0, got %f", s)
+	}
+}
+
+func TestAffinityScore_Decayed(t *testing.T) {
+	e := &NeighborEdge{Count: 100, LastSeen: time.Now().Add(-7 * 24 * time.Hour)}
+	s := e.Score(time.Now())
+	// 7 days → half-life → ~0.5
+	if math.Abs(s-0.5) > 0.05 {
+		t.Errorf("expected score ≈ 0.5, got %f", s)
+	}
+}
+
+func TestAffinityScore_LowCount(t *testing.T) {
+	e := &NeighborEdge{Count: 5, LastSeen: time.Now()}
+	s := e.Score(time.Now())
+	// 5/100 = 0.05
+	if math.Abs(s-0.05) > 0.01 {
+		t.Errorf("expected score ≈ 0.05, got %f", s)
+	}
+}
+
+func TestAffinityScore_StaleAndLow(t *testing.T) {
+	e := &NeighborEdge{Count: 5, LastSeen: time.Now().Add(-30 * 24 * time.Hour)}
+	s := e.Score(time.Now())
+	// Very small
+	if s > 0.01 {
+		t.Errorf("expected score ≈ 0, got %f", s)
+	}
+}
+
+func TestBuildNeighborGraph_CountAccumulation(t *testing.T) {
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+
+	var txs []*StoreTx
+	for i := 0; i < 5; i++ {
+		txs = append(txs, ngMakeTx(i+1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+			ngMakeObs("obs00001", `["r1aa"]`, nowStr, nil),
+		}))
+	}
+
+	store := ngTestStore(nodes, txs)
+	g := BuildFromStore(store)
+
+	// Check count on X↔R1 edge
+	for _, e := range g.AllEdges() {
+		if (e.NodeA == "aaaa1111" && e.NodeB == "r1aabbcc") || (e.NodeA == "r1aabbcc" && e.NodeB == "aaaa1111") {
+			if e.Count != 5 {
+				t.Errorf("expected count 5, got %d", e.Count)
+			}
+			return
+		}
+	}
+	t.Error("X↔R1 edge not found")
+}
+
+func TestBuildNeighborGraph_MultipleObservers(t *testing.T) {
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "obs00001", Name: "Obs1"},
+		{PublicKey: "obs00002", Name: "Obs2"},
+	}
+
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["r1aa"]`, nowStr, nil),
+		ngMakeObs("obs00002", `["r1aa"]`, nowStr, nil),
+	})
+
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	for _, e := range g.AllEdges() {
+		if (e.NodeA == "aaaa1111" && e.NodeB == "r1aabbcc") || (e.NodeA == "r1aabbcc" && e.NodeB == "aaaa1111") {
+			if len(e.Observers) != 2 {
+				t.Errorf("expected 2 observers, got %d", len(e.Observers))
+			}
+			if !e.Observers["obs00001"] || !e.Observers["obs00002"] {
+				t.Error("missing expected observer")
+			}
+			return
+		}
+	}
+	t.Error("X↔R1 edge not found")
+}
+
+func TestBuildNeighborGraph_TimeDecayOldObservations(t *testing.T) {
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+
+	tx := ngMakeTx(1, 4, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["r1aa"]`, monthAgoStr, nil),
+	})
+
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	for _, e := range g.AllEdges() {
+		if (e.NodeA == "aaaa1111" && e.NodeB == "r1aabbcc") || (e.NodeA == "r1aabbcc" && e.NodeB == "aaaa1111") {
+			score := e.Score(time.Now())
+			if score > 0.05 {
+				t.Errorf("expected decayed score < 0.05, got %f", score)
+			}
+			return
+		}
+	}
+	t.Error("X↔R1 edge not found")
+}
+
+func TestBuildNeighborGraph_ADVERTOnlyConstraint(t *testing.T) {
+	// Non-ADVERT: should NOT create originator↔path[0] edge, only observer↔path[last].
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeX"},
+		{PublicKey: "r1aabbcc", Name: "R1"},
+		{PublicKey: "r2ddeeff", Name: "R2"},
+		{PublicKey: "obs00001", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 2, ngFromNodeJSON("aaaa1111"), []*StoreObs{
+		ngMakeObs("obs00001", `["r1aa","r2dd"]`, nowStr, nil),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	for _, e := range g.AllEdges() {
+		a, b := e.NodeA, e.NodeB
+		if (a == "aaaa1111" && b == "r1aabbcc") || (a == "r1aabbcc" && b == "aaaa1111") {
+			t.Error("non-ADVERT should NOT produce originator↔path[0] edge")
+		}
+	}
+
+	// Should have Observer↔R2
+	found := false
+	for _, e := range g.AllEdges() {
+		if (e.NodeA == "obs00001" && e.NodeB == "r2ddeeff") || (e.NodeA == "r2ddeeff" && e.NodeB == "obs00001") {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("missing Observer↔R2 edge from non-ADVERT")
+	}
+}
+
+// ngPubKeyJSON creates decoded JSON using the real ADVERT format ("pubKey" field).
+func ngPubKeyJSON(pubkey string) string {
+	b, _ := json.Marshal(map[string]string{"pubKey": pubkey})
+	return string(b)
+}
+
+func TestBuildNeighborGraph_AdvertPubKeyField(t *testing.T) {
+	// Real ADVERTs use "pubKey", not "from_node". Verify the builder handles it.
+	nodes := []nodeInfo{
+		{PublicKey: "99bf37abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234", Name: "Originator"},
+		{PublicKey: "r1aabbccdd001122334455667788990011223344556677889900112233445566", Name: "R1"},
+		{PublicKey: "obs0000100112233445566778899001122334455667788990011223344556677", Name: "Observer"},
+	}
+	tx := ngMakeTx(1, 4, ngPubKeyJSON("99bf37abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234"), []*StoreObs{
+		ngMakeObs("obs0000100112233445566778899001122334455667788990011223344556677", `["r1"]`, nowStr, ngFloatPtr(-8.5)),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	edges := g.AllEdges()
+	if len(edges) < 1 {
+		t.Fatalf("expected >=1 edges from ADVERT with pubKey field, got %d", len(edges))
+	}
+
+	// Check originator↔R1 edge exists
+	found := false
+	for _, e := range edges {
+		a := e.NodeA
+		b := e.NodeB
+		orig := "99bf37abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234"
+		r1 := "r1aabbccdd001122334455667788990011223344556677889900112233445566"
+		if (a == orig && b == r1) || (a == r1 && b == orig) {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("missing originator↔R1 edge when using pubKey field (real ADVERT format)")
+	}
+}
+
+func TestBuildNeighborGraph_OneByteHashPrefixes(t *testing.T) {
+	// Real-world scenario: 1-byte hash prefixes with multiple candidates.
+	// Should create edges (possibly ambiguous) rather than empty graph.
+	nodes := []nodeInfo{
+		{PublicKey: "c0dedad400000000000000000000000000000000000000000000000000000001", Name: "NodeC0-1"},
+		{PublicKey: "c0dedad900000000000000000000000000000000000000000000000000000002", Name: "NodeC0-2"},
+		{PublicKey: "a3bbccdd00000000000000000000000000000000000000000000000000000003", Name: "Originator"},
+		{PublicKey: "obs1234500000000000000000000000000000000000000000000000000000004", Name: "Observer"},
+	}
+	// ADVERT from Originator with 1-byte path hop "c0"
+	tx := ngMakeTx(1, 4, ngPubKeyJSON("a3bbccdd00000000000000000000000000000000000000000000000000000003"), []*StoreObs{
+		ngMakeObs("obs1234500000000000000000000000000000000000000000000000000000004", `["c0"]`, nowStr, ngFloatPtr(-12)),
+	})
+	store := ngTestStore(nodes, []*StoreTx{tx})
+	g := BuildFromStore(store)
+
+	edges := g.AllEdges()
+	if len(edges) == 0 {
+		t.Fatal("expected non-empty edges for 1-byte hash prefix network, got 0")
+	}
+
+	// The originator↔c0 edge should be ambiguous (2 candidates match "c0")
+	var hasAmbig bool
+	for _, e := range edges {
+		if e.Ambiguous && e.Prefix == "c0" {
+			hasAmbig = true
+			if len(e.Candidates) != 2 {
+				t.Errorf("expected 2 candidates for prefix c0, got %d", len(e.Candidates))
+			}
+		}
+	}
+	if !hasAmbig {
+		// Could be resolved if one candidate was filtered — check we got some edge
+		t.Log("no ambiguous edge found, but edges exist — acceptable if resolved")
+	}
+}
+
+func TestNeighborGraph_CacheTTL(t *testing.T) {
+	g := NewNeighborGraph()
+	if !g.IsStale() {
+		t.Error("new graph should be stale")
+	}
+	g.mu.Lock()
+	g.builtAt = time.Now()
+	g.mu.Unlock()
+	if g.IsStale() {
+		t.Error("just-built graph should not be stale")
+	}
+	g.mu.Lock()
+	g.builtAt = time.Now().Add(-2 * neighborGraphTTL)
+	g.mu.Unlock()
+	if !g.IsStale() {
+		t.Error("old graph should be stale")
+	}
+}
+
+func TestNeighborGraph_TTLIsReasonable(t *testing.T) {
+	// TTL must be long enough to avoid rebuild storms on busy meshes,
+	// but short enough to reflect topology changes within minutes.
+	if neighborGraphTTL < 1*time.Minute {
+		t.Errorf("neighborGraphTTL too short (%v), will cause rebuild storms", neighborGraphTTL)
+	}
+	if neighborGraphTTL > 10*time.Minute {
+		t.Errorf("neighborGraphTTL too long (%v), topology changes will be stale", neighborGraphTTL)
+	}
+}
+
+func TestCachedToLower(t *testing.T) {
+	cache := make(map[string]string)
+	// Basic lowercasing
+	if got := cachedToLower(cache, "AABB"); got != "aabb" {
+		t.Errorf("expected 'aabb', got %q", got)
+	}
+	// Verify it was cached
+	if _, ok := cache["AABB"]; !ok {
+		t.Error("expected 'AABB' to be in cache")
+	}
+	// Same input returns cached result
+	if got := cachedToLower(cache, "AABB"); got != "aabb" {
+		t.Errorf("expected cached 'aabb', got %q", got)
+	}
+	// Already lowercase stays the same
+	if got := cachedToLower(cache, "aabb"); got != "aabb" {
+		t.Errorf("expected 'aabb', got %q", got)
+	}
+	// Empty string
+	if got := cachedToLower(cache, ""); got != "" {
+		t.Errorf("expected empty, got %q", got)
+	}
+}
+
+func TestParsedDecoded_Caching(t *testing.T) {
+	tx := &StoreTx{DecodedJSON: `{"pubKey":"abc123","name":"test"}`}
+	// First call parses
+	d1 := tx.ParsedDecoded()
+	if d1 == nil {
+		t.Fatal("expected non-nil parsed result")
+	}
+	if d1["pubKey"] != "abc123" {
+		t.Errorf("expected pubKey=abc123, got %v", d1["pubKey"])
+	}
+	// Second call must return the exact same map (pointer equality proves caching)
+	d2 := tx.ParsedDecoded()
+	if &d1 == nil || &d2 == nil {
+		t.Fatal("unexpected nil")
+	}
+	// Mutate d1 and verify d2 sees the mutation — proves same underlying map
+	d1["_sentinel"] = true
+	if d2["_sentinel"] != true {
+		t.Error("expected same map instance from second call (caching broken)")
+	}
+	delete(d1, "_sentinel") // clean up
+}
+
+func TestParsedDecoded_EmptyJSON(t *testing.T) {
+	tx := &StoreTx{DecodedJSON: ""}
+	d := tx.ParsedDecoded()
+	if d != nil {
+		t.Errorf("expected nil for empty DecodedJSON, got %v", d)
+	}
+}
+
+func TestParsedDecoded_InvalidJSON(t *testing.T) {
+	tx := &StoreTx{DecodedJSON: "not json"}
+	d := tx.ParsedDecoded()
+	if d != nil {
+		t.Errorf("expected nil for invalid JSON, got %v", d)
+	}
+}
+
+func TestExtractFromNode_UsesCachedParse(t *testing.T) {
+	tx := &StoreTx{DecodedJSON: `{"pubKey":"aabb1122"}`}
+	// First call to extractFromNode should use ParsedDecoded
+	from := extractFromNode(tx)
+	if from != "aabb1122" {
+		t.Errorf("expected aabb1122, got %q", from)
+	}
+	// ParsedDecoded should now be cached
+	d := tx.ParsedDecoded()
+	if d == nil || d["pubKey"] != "aabb1122" {
+		t.Error("expected ParsedDecoded to return cached result")
+	}
+}
+
+func BenchmarkBuildFromStore(b *testing.B) {
+	// Simulate a dataset with many packets and repeated pubkeys
+	nodes := []nodeInfo{
+		{PublicKey: "aaaa1111", Name: "NodeA"},
+		{PublicKey: "bbbb2222", Name: "NodeB"},
+		{PublicKey: "cccc3333", Name: "NodeC"},
+		{PublicKey: "dddd4444", Name: "NodeD"},
+	}
+	const numPackets = 1000
+	packets := make([]*StoreTx, 0, numPackets)
+	for i := 0; i < numPackets; i++ {
+		pt := 4 // ADVERT
+		packets = append(packets, &StoreTx{
+			ID:          i,
+			PayloadType: &pt,
+			DecodedJSON: `{"pubKey":"aaaa1111"}`,
+			Observations: []*StoreObs{
+				{ObserverID: "bbbb2222", PathJSON: `["cccc"]`, Timestamp: nowStr, SNR: ngFloatPtr(-5.0)},
+			},
+		})
+	}
+	store := ngTestStore(nodes, packets)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		BuildFromStore(store)
+	}
+}

cmd/server/neighbor_persist.go

@@ -0,0 +1,531 @@
+package main
+
+import (
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"log"
+	"strings"
+	"time"
+)
+
+// persistSem limits concurrent async persistence goroutines to 1.
+// Without this, each ingest cycle spawns a goroutine that opens a new
+// SQLite RW connection; under sustained load goroutines pile up with
+// no backpressure, causing contention and busy-timeout cascades.
+var persistSem = make(chan struct{}, 1)
+
+// ─── neighbor_edges table ──────────────────────────────────────────────────────
+
+// ensureNeighborEdgesTable creates the neighbor_edges table if it doesn't exist.
+// Uses a separate read-write connection since the main DB is read-only.
+func ensureNeighborEdgesTable(dbPath string) error {
+	rw, err := openRW(dbPath)
+	if err != nil {
+		return fmt.Errorf("open rw for neighbor_edges: %w", err)
+	}
+	defer rw.Close()
+
+	_, err = rw.Exec(`CREATE TABLE IF NOT EXISTS neighbor_edges (
+		node_a TEXT NOT NULL,
+		node_b TEXT NOT NULL,
+		count INTEGER DEFAULT 1,
+		last_seen TEXT,
+		PRIMARY KEY (node_a, node_b)
+	)`)
+	return err
+}
+
+// loadNeighborEdgesFromDB loads all edges from the neighbor_edges table
+// and builds an in-memory NeighborGraph.
+func loadNeighborEdgesFromDB(conn *sql.DB) *NeighborGraph {
+	g := NewNeighborGraph()
+
+	rows, err := conn.Query("SELECT node_a, node_b, count, last_seen FROM neighbor_edges")
+	if err != nil {
+		log.Printf("[neighbor] failed to load neighbor_edges: %v", err)
+		return g
+	}
+	defer rows.Close()
+
+	count := 0
+	for rows.Next() {
+		var a, b string
+		var cnt int
+		var lastSeen sql.NullString
+		if err := rows.Scan(&a, &b, &cnt, &lastSeen); err != nil {
+			continue
+		}
+		ts := time.Time{}
+		if lastSeen.Valid {
+			ts = parseTimestamp(lastSeen.String)
+		}
+		// Build edge directly (both nodes are full pubkeys from persisted data)
+		key := makeEdgeKey(a, b)
+		g.mu.Lock()
+		e, exists := g.edges[key]
+		if !exists {
+			e = &NeighborEdge{
+				NodeA:     key.A,
+				NodeB:     key.B,
+				Observers: make(map[string]bool),
+				FirstSeen: ts,
+				LastSeen:  ts,
+				Count:     cnt,
+			}
+			g.edges[key] = e
+			g.byNode[key.A] = append(g.byNode[key.A], e)
+			g.byNode[key.B] = append(g.byNode[key.B], e)
+		} else {
+			e.Count += cnt
+			if ts.After(e.LastSeen) {
+				e.LastSeen = ts
+			}
+		}
+		g.mu.Unlock()
+		count++
+	}
+
+	if count > 0 {
+		g.mu.Lock()
+		g.builtAt = time.Now()
+		g.mu.Unlock()
+		log.Printf("[neighbor] loaded %d edges from neighbor_edges table", count)
+	}
+
+	return g
+}
+
+// ─── shared async persistence helper ───────────────────────────────────────────
+
+// persistObsUpdate holds data for a resolved_path SQLite update.
+type persistObsUpdate struct {
+	obsID        int
+	resolvedPath string
+}
+
+// persistEdgeUpdate holds data for a neighbor_edges SQLite upsert.
+type persistEdgeUpdate struct {
+	a, b, ts string
+}
+
+// asyncPersistResolvedPathsAndEdges writes resolved_path updates and neighbor
+// edge upserts to SQLite in a background goroutine. Shared between
+// IngestNewFromDB and IngestNewObservations to avoid DRY violation.
+func asyncPersistResolvedPathsAndEdges(dbPath string, obsUpdates []persistObsUpdate, edgeUpdates []persistEdgeUpdate, logPrefix string) {
+	if len(obsUpdates) == 0 && len(edgeUpdates) == 0 {
+		return
+	}
+	// Try-acquire semaphore BEFORE spawning goroutine. If another
+	// persistence operation is already running, drop this batch —
+	// data lives in memory and will be backfilled on restart.
+	select {
+	case persistSem <- struct{}{}:
+		// Acquired — spawn goroutine to do the work.
+	default:
+		log.Printf("[store] %s skipped: persistence already in progress", logPrefix)
+		return
+	}
+	go func() {
+		defer func() { <-persistSem }()
+
+		rw, err := openRW(dbPath)
+		if err != nil {
+			log.Printf("[store] %s rw open error: %v", logPrefix, err)
+			return
+		}
+		defer rw.Close()
+
+		if len(obsUpdates) > 0 {
+			sqlTx, err := rw.Begin()
+			if err == nil {
+				stmt, err := sqlTx.Prepare("UPDATE observations SET resolved_path = ? WHERE id = ?")
+				if err == nil {
+					var firstErr error
+					for _, u := range obsUpdates {
+						if _, err := stmt.Exec(u.resolvedPath, u.obsID); err != nil && firstErr == nil {
+							firstErr = err
+						}
+					}
+					stmt.Close()
+					if firstErr != nil {
+						log.Printf("[store] %s resolved_path error (first): %v", logPrefix, firstErr)
+					}
+				} else {
+					log.Printf("[store] %s resolved_path prepare error: %v", logPrefix, err)
+				}
+				sqlTx.Commit()
+			}
+		}
+
+		if len(edgeUpdates) > 0 {
+			sqlTx, err := rw.Begin()
+			if err == nil {
+				stmt, err := sqlTx.Prepare(`INSERT INTO neighbor_edges (node_a, node_b, count, last_seen)
+					VALUES (?, ?, 1, ?)
+					ON CONFLICT(node_a, node_b) DO UPDATE SET
+					count = count + 1, last_seen = MAX(last_seen, excluded.last_seen)`)
+				if err == nil {
+					var firstErr error
+					for _, e := range edgeUpdates {
+						if _, err := stmt.Exec(e.a, e.b, e.ts); err != nil && firstErr == nil {
+							firstErr = err
+						}
+					}
+					stmt.Close()
+					if firstErr != nil {
+						log.Printf("[store] %s edge error (first): %v", logPrefix, firstErr)
+					}
+				} else {
+					log.Printf("[store] %s edge prepare error: %v", logPrefix, err)
+				}
+				sqlTx.Commit()
+			}
+		}
+	}()
+}
+
+// neighborEdgesTableExists checks if the neighbor_edges table has any data.
+func neighborEdgesTableExists(conn *sql.DB) bool {
+	var cnt int
+	err := conn.QueryRow("SELECT COUNT(*) FROM neighbor_edges").Scan(&cnt)
+	if err != nil {
+		return false // table doesn't exist
+	}
+	return cnt > 0
+}
+
+// buildAndPersistEdges scans all packets in the store, extracts edges per
+// ADVERT/non-ADVERT rules, and persists them to SQLite.
+func buildAndPersistEdges(store *PacketStore, rw *sql.DB) int {
+	store.mu.RLock()
+	packets := make([]*StoreTx, len(store.packets))
+	copy(packets, store.packets)
+	store.mu.RUnlock()
+
+	_, pm := store.getCachedNodesAndPM()
+
+	tx, err := rw.Begin()
+	if err != nil {
+		log.Printf("[neighbor] begin tx error: %v", err)
+		return 0
+	}
+	defer tx.Rollback()
+
+	stmt, err := tx.Prepare(`INSERT INTO neighbor_edges (node_a, node_b, count, last_seen)
+		VALUES (?, ?, 1, ?)
+		ON CONFLICT(node_a, node_b) DO UPDATE SET
+		count = count + 1, last_seen = MAX(last_seen, excluded.last_seen)`)
+	if err != nil {
+		log.Printf("[neighbor] prepare stmt error: %v", err)
+		return 0
+	}
+	defer stmt.Close()
+
+	edgeCount := 0
+	var firstErr error
+	for _, pkt := range packets {
+		for _, obs := range pkt.Observations {
+			for _, ec := range extractEdgesFromObs(obs, pkt, pm) {
+				if _, err := stmt.Exec(ec.A, ec.B, ec.Timestamp); err != nil && firstErr == nil {
+					firstErr = err
+				}
+				edgeCount++
+			}
+		}
+	}
+	if firstErr != nil {
+		log.Printf("[neighbor] edge exec error (first): %v", firstErr)
+	}
+
+	if err := tx.Commit(); err != nil {
+		log.Printf("[neighbor] commit error: %v", err)
+		return 0
+	}
+	return edgeCount
+}
+
+// ─── resolved_path column ──────────────────────────────────────────────────────
+
+// ensureResolvedPathColumn adds the resolved_path column to observations if missing.
+func ensureResolvedPathColumn(dbPath string) error {
+	rw, err := openRW(dbPath)
+	if err != nil {
+		return err
+	}
+	defer rw.Close()
+
+	// Check if column already exists
+	rows, err := rw.Query("PRAGMA table_info(observations)")
+	if err != nil {
+		return err
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var cid int
+		var colName string
+		var colType sql.NullString
+		var notNull, pk int
+		var dflt sql.NullString
+		if rows.Scan(&cid, &colName, &colType, &notNull, &dflt, &pk) == nil && colName == "resolved_path" {
+			return nil // already exists
+		}
+	}
+
+	_, err = rw.Exec("ALTER TABLE observations ADD COLUMN resolved_path TEXT")
+	if err != nil {
+		return fmt.Errorf("add resolved_path column: %w", err)
+	}
+	log.Println("[store] Added resolved_path column to observations")
+	return nil
+}
+
+// resolvePathForObs resolves hop prefixes to full pubkeys for an observation.
+// Returns nil if path is empty.
+func resolvePathForObs(pathJSON, observerID string, tx *StoreTx, pm *prefixMap, graph *NeighborGraph) []*string {
+	hops := parsePathJSON(pathJSON)
+	if len(hops) == 0 {
+		return nil
+	}
+
+	// Build context pubkeys: observer + originator (if known)
+	contextPKs := make([]string, 0, 3)
+	if observerID != "" {
+		contextPKs = append(contextPKs, strings.ToLower(observerID))
+	}
+	fromNode := extractFromNode(tx)
+	if fromNode != "" {
+		contextPKs = append(contextPKs, strings.ToLower(fromNode))
+	}
+
+	resolved := make([]*string, len(hops))
+	for i, hop := range hops {
+		// Add adjacent hops as context for disambiguation
+		ctx := make([]string, len(contextPKs), len(contextPKs)+2)
+		copy(ctx, contextPKs)
+		// Add previously resolved hops as context
+		if i > 0 && resolved[i-1] != nil {
+			ctx = append(ctx, *resolved[i-1])
+		}
+
+		node, _, _ := pm.resolveWithContext(hop, ctx, graph)
+		if node != nil {
+			pk := strings.ToLower(node.PublicKey)
+			resolved[i] = &pk
+		}
+	}
+
+	return resolved
+}
+
+// marshalResolvedPath converts []*string to JSON for storage.
+func marshalResolvedPath(rp []*string) string {
+	if len(rp) == 0 {
+		return ""
+	}
+	b, err := json.Marshal(rp)
+	if err != nil {
+		return ""
+	}
+	return string(b)
+}
+
+// unmarshalResolvedPath parses a resolved_path JSON string.
+func unmarshalResolvedPath(s string) []*string {
+	if s == "" {
+		return nil
+	}
+	var result []*string
+	if json.Unmarshal([]byte(s), &result) != nil {
+		return nil
+	}
+	return result
+}
+
+// backfillResolvedPaths resolves paths for all observations that have NULL resolved_path.
+func backfillResolvedPaths(store *PacketStore, dbPath string) int {
+	// Collect pending observations and snapshot immutable fields under read lock.
+	// graph is set in main.go before backfill is called; nil-safe throughout (review item #6).
+	type obsRef struct {
+		obsID      int
+		pathJSON   string
+		observerID string
+		txJSON     string // snapshot of DecodedJSON for extractFromNode
+		payloadType *int
+	}
+	store.mu.RLock()
+	pm := store.nodePM
+	graph := store.graph
+	var pending []obsRef
+	for _, tx := range store.packets {
+		for _, obs := range tx.Observations {
+			if obs.ResolvedPath == nil && obs.PathJSON != "" && obs.PathJSON != "[]" {
+				pending = append(pending, obsRef{
+					obsID:       obs.ID,
+					pathJSON:    obs.PathJSON,
+					observerID:  obs.ObserverID,
+					txJSON:      tx.DecodedJSON,
+					payloadType: tx.PayloadType,
+				})
+			}
+		}
+	}
+	store.mu.RUnlock()
+
+	if len(pending) == 0 || pm == nil {
+		return 0
+	}
+
+	// Resolve paths outside the lock — resolvePathForObs only reads pm and graph.
+	type resolved struct {
+		obsID  int
+		rp     []*string
+		rpJSON string
+	}
+	var results []resolved
+	for _, ref := range pending {
+		// Build a minimal StoreTx for extractFromNode (only needs DecodedJSON + PayloadType).
+		fakeTx := &StoreTx{DecodedJSON: ref.txJSON, PayloadType: ref.payloadType}
+		rp := resolvePathForObs(ref.pathJSON, ref.observerID, fakeTx, pm, graph)
+		if len(rp) > 0 {
+			rpJSON := marshalResolvedPath(rp)
+			if rpJSON != "" {
+				results = append(results, resolved{ref.obsID, rp, rpJSON})
+			}
+		}
+	}
+
+	if len(results) == 0 {
+		return 0
+	}
+
+	// Persist to SQLite (no lock needed — separate RW connection).
+	rw, err := openRW(dbPath)
+	if err != nil {
+		log.Printf("[store] backfill: open rw error: %v", err)
+		return 0
+	}
+	defer rw.Close()
+
+	sqlTx, err := rw.Begin()
+	if err != nil {
+		log.Printf("[store] backfill: begin tx error: %v", err)
+		return 0
+	}
+	defer sqlTx.Rollback()
+
+	stmt, err := sqlTx.Prepare("UPDATE observations SET resolved_path = ? WHERE id = ?")
+	if err != nil {
+		log.Printf("[store] backfill: prepare error: %v", err)
+		return 0
+	}
+	defer stmt.Close()
+
+	var firstErr error
+	for _, r := range results {
+		if _, err := stmt.Exec(r.rpJSON, r.obsID); err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	if firstErr != nil {
+		log.Printf("[store] backfill resolved_path exec error (first): %v", firstErr)
+	}
+
+	if err := sqlTx.Commit(); err != nil {
+		log.Printf("[store] backfill: commit error: %v", err)
+		return 0
+	}
+
+	// Update in-memory state under write lock.
+	store.mu.Lock()
+	count := 0
+	for _, r := range results {
+		if obs, ok := store.byObsID[r.obsID]; ok {
+			obs.ResolvedPath = r.rp
+			count++
+		}
+	}
+	store.mu.Unlock()
+
+	return count
+}
+
+// ─── Shared helpers ────────────────────────────────────────────────────────────
+
+// edgeCandidate represents an extracted edge to be persisted.
+type edgeCandidate struct {
+	A, B, Timestamp string
+}
+
+// extractEdgesFromObs extracts neighbor edge candidates from a single observation.
+// For ADVERTs: originator↔path[0] (if unambiguous). For ALL types: observer↔path[last] (if unambiguous).
+// Also handles zero-hop ADVERTs (originator↔observer direct link).
+func extractEdgesFromObs(obs *StoreObs, tx *StoreTx, pm *prefixMap) []edgeCandidate {
+	isAdvert := tx.PayloadType != nil && *tx.PayloadType == 4
+	fromNode := extractFromNode(tx)
+	path := parsePathJSON(obs.PathJSON)
+	observerPK := strings.ToLower(obs.ObserverID)
+	ts := obs.Timestamp
+	var edges []edgeCandidate
+
+	if len(path) == 0 {
+		if isAdvert && fromNode != "" {
+			fromLower := strings.ToLower(fromNode)
+			if fromLower != observerPK {
+				a, b := fromLower, observerPK
+				if a > b {
+					a, b = b, a
+				}
+				edges = append(edges, edgeCandidate{a, b, ts})
+			}
+		}
+		return edges
+	}
+
+	// Edge 1: originator ↔ path[0] — ADVERTs only (resolve prefix to full pubkey)
+	if isAdvert && fromNode != "" && pm != nil {
+		firstHop := strings.ToLower(path[0])
+		fromLower := strings.ToLower(fromNode)
+		candidates := pm.m[firstHop]
+		if len(candidates) == 1 {
+			resolved := strings.ToLower(candidates[0].PublicKey)
+			if resolved != fromLower {
+				a, b := fromLower, resolved
+				if a > b {
+					a, b = b, a
+				}
+				edges = append(edges, edgeCandidate{a, b, ts})
+			}
+		}
+	}
+
+	// Edge 2: observer ↔ path[last] — ALL packet types
+	if pm != nil {
+		lastHop := strings.ToLower(path[len(path)-1])
+		candidates := pm.m[lastHop]
+		if len(candidates) == 1 {
+			resolved := strings.ToLower(candidates[0].PublicKey)
+			if resolved != observerPK {
+				a, b := observerPK, resolved
+				if a > b {
+					a, b = b, a
+				}
+				edges = append(edges, edgeCandidate{a, b, ts})
+			}
+		}
+	}
+
+	return edges
+}
+
+// openRW opens a read-write SQLite connection (same pattern as PruneOldPackets).
+func openRW(dbPath string) (*sql.DB, error) {
+	dsn := fmt.Sprintf("file:%s?_journal_mode=WAL&_busy_timeout=10000", dbPath)
+	rw, err := sql.Open("sqlite", dsn)
+	if err != nil {
+		return nil, err
+	}
+	rw.SetMaxOpenConns(1)
+	return rw, nil
+}

cmd/server/neighbor_persist_test.go

@@ -0,0 +1,534 @@
+package main
+
+import (
+	"database/sql"
+	"encoding/json"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	_ "modernc.org/sqlite"
+)
+
+// createTestDBWithSchema creates a temp SQLite DB with the standard schema + resolved_path column.
+func createTestDBWithSchema(t *testing.T) (*DB, string) {
+	t.Helper()
+	dir := t.TempDir()
+	dbPath := filepath.Join(dir, "test.db")
+
+	conn, err := sql.Open("sqlite", "file:"+dbPath+"?_journal_mode=WAL")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Create tables
+	conn.Exec(`CREATE TABLE transmissions (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		raw_hex TEXT, hash TEXT UNIQUE, first_seen TEXT,
+		route_type INTEGER, payload_type INTEGER, payload_version INTEGER,
+		decoded_json TEXT
+	)`)
+	conn.Exec(`CREATE TABLE observers (
+		id TEXT PRIMARY KEY, name TEXT, iata TEXT
+	)`)
+	conn.Exec(`CREATE TABLE observations (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		transmission_id INTEGER NOT NULL REFERENCES transmissions(id),
+		observer_id TEXT, observer_name TEXT, direction TEXT,
+		snr REAL, rssi REAL, score INTEGER,
+		path_json TEXT, timestamp TEXT,
+		resolved_path TEXT
+	)`)
+	conn.Exec(`CREATE TABLE nodes (
+		public_key TEXT PRIMARY KEY, name TEXT, role TEXT,
+		lat REAL, lon REAL, last_seen TEXT, first_seen TEXT,
+		advert_count INTEGER DEFAULT 0
+	)`)
+
+	conn.Close()
+
+	db, err := OpenDB(dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return db, dbPath
+}
+
+func TestResolvePathForObs(t *testing.T) {
+	// Build a prefix map with known nodes
+	nodes := []nodeInfo{
+		{PublicKey: "aabbccddee1234567890aabbccddee1234567890aabbccddee1234567890aabb", Name: "Node-AA"},
+		{PublicKey: "bbccddee1234567890aabbccddee1234567890aabbccddee1234567890aabb11", Name: "Node-BB"},
+	}
+	pm := buildPrefixMap(nodes)
+	graph := NewNeighborGraph()
+
+	tx := &StoreTx{
+		DecodedJSON: `{"pubKey": "originator1234567890"}`,
+		PayloadType: intPtr(4),
+	}
+
+	// Unambiguous prefixes should resolve
+	rp := resolvePathForObs(`["aa","bb"]`, "observer1", tx, pm, graph)
+	if len(rp) != 2 {
+		t.Fatalf("expected 2 resolved hops, got %d", len(rp))
+	}
+	if rp[0] == nil || !strings.HasPrefix(*rp[0], "aabbcc") {
+		t.Errorf("expected first hop to resolve to Node-AA, got %v", rp[0])
+	}
+	if rp[1] == nil || !strings.HasPrefix(*rp[1], "bbccdd") {
+		t.Errorf("expected second hop to resolve to Node-BB, got %v", rp[1])
+	}
+}
+
+func TestResolvePathForObs_EmptyPath(t *testing.T) {
+	pm := buildPrefixMap(nil)
+	rp := resolvePathForObs(`[]`, "", &StoreTx{}, pm, nil)
+	if rp != nil {
+		t.Errorf("expected nil for empty path, got %v", rp)
+	}
+
+	rp = resolvePathForObs("", "", &StoreTx{}, pm, nil)
+	if rp != nil {
+		t.Errorf("expected nil for empty string, got %v", rp)
+	}
+}
+
+func TestResolvePathForObs_Unresolvable(t *testing.T) {
+	nodes := []nodeInfo{
+		{PublicKey: "aabbccddee1234567890aabbccddee1234567890aabbccddee1234567890aabb", Name: "Node-AA"},
+	}
+	pm := buildPrefixMap(nodes)
+
+	// "zz" prefix doesn't match any node
+	rp := resolvePathForObs(`["zz"]`, "", &StoreTx{}, pm, nil)
+	if len(rp) != 1 {
+		t.Fatalf("expected 1 hop, got %d", len(rp))
+	}
+	if rp[0] != nil {
+		t.Errorf("expected nil for unresolvable hop, got %v", *rp[0])
+	}
+}
+
+func TestMarshalUnmarshalResolvedPath(t *testing.T) {
+	pk1 := "aabbccdd"
+	var rp []*string
+	rp = append(rp, &pk1, nil)
+
+	j := marshalResolvedPath(rp)
+	if j == "" {
+		t.Fatal("expected non-empty JSON")
+	}
+
+	parsed := unmarshalResolvedPath(j)
+	if len(parsed) != 2 {
+		t.Fatalf("expected 2 elements, got %d", len(parsed))
+	}
+	if parsed[0] == nil || *parsed[0] != "aabbccdd" {
+		t.Errorf("first element wrong: %v", parsed[0])
+	}
+	if parsed[1] != nil {
+		t.Errorf("second element should be nil, got %v", *parsed[1])
+	}
+}
+
+func TestMarshalResolvedPath_Empty(t *testing.T) {
+	if marshalResolvedPath(nil) != "" {
+		t.Error("expected empty for nil")
+	}
+	if marshalResolvedPath([]*string{}) != "" {
+		t.Error("expected empty for empty slice")
+	}
+}
+
+func TestUnmarshalResolvedPath_Invalid(t *testing.T) {
+	if unmarshalResolvedPath("") != nil {
+		t.Error("expected nil for empty string")
+	}
+	if unmarshalResolvedPath("not json") != nil {
+		t.Error("expected nil for invalid JSON")
+	}
+}
+
+func TestEnsureNeighborEdgesTable(t *testing.T) {
+	dir := t.TempDir()
+	dbPath := filepath.Join(dir, "test.db")
+
+	// Create initial DB
+	conn, _ := sql.Open("sqlite", "file:"+dbPath+"?_journal_mode=WAL")
+	conn.Exec("CREATE TABLE test (id INTEGER PRIMARY KEY)")
+	conn.Close()
+
+	if err := ensureNeighborEdgesTable(dbPath); err != nil {
+		t.Fatal(err)
+	}
+
+	// Verify table exists
+	conn, _ = sql.Open("sqlite", "file:"+dbPath+"?mode=ro")
+	defer conn.Close()
+	var cnt int
+	if err := conn.QueryRow("SELECT COUNT(*) FROM neighbor_edges").Scan(&cnt); err != nil {
+		t.Fatalf("neighbor_edges table not created: %v", err)
+	}
+}
+
+func TestLoadNeighborEdgesFromDB(t *testing.T) {
+	dir := t.TempDir()
+	dbPath := filepath.Join(dir, "test.db")
+
+	conn, _ := sql.Open("sqlite", "file:"+dbPath+"?_journal_mode=WAL")
+	conn.Exec(`CREATE TABLE neighbor_edges (
+		node_a TEXT NOT NULL, node_b TEXT NOT NULL,
+		count INTEGER DEFAULT 1, last_seen TEXT,
+		PRIMARY KEY (node_a, node_b)
+	)`)
+	conn.Exec("INSERT INTO neighbor_edges VALUES ('aaa', 'bbb', 5, '2024-01-01T00:00:00Z')")
+	conn.Exec("INSERT INTO neighbor_edges VALUES ('ccc', 'ddd', 3, '2024-01-02T00:00:00Z')")
+
+	g := loadNeighborEdgesFromDB(conn)
+	conn.Close()
+
+	// Should have 2 edges
+	edges := g.AllEdges()
+	if len(edges) != 2 {
+		t.Errorf("expected 2 edges, got %d", len(edges))
+	}
+
+	// Check neighbors
+	n := g.Neighbors("aaa")
+	if len(n) != 1 {
+		t.Errorf("expected 1 neighbor for aaa, got %d", len(n))
+	}
+}
+
+func TestStoreObsResolvedPathInBroadcast(t *testing.T) {
+	// Verify resolved_path appears in broadcast maps
+	pk := "aabbccdd"
+	obs := &StoreObs{
+		ID:           1,
+		ObserverID:   "obs1",
+		ObserverName: "Observer 1",
+		PathJSON:     `["aa"]`,
+		ResolvedPath: []*string{&pk},
+		Timestamp:    "2024-01-01T00:00:00Z",
+	}
+
+	tx := &StoreTx{
+		ID:   1,
+		Hash: "abc123",
+		Observations: []*StoreObs{obs},
+	}
+	pickBestObservation(tx)
+
+	if tx.ResolvedPath == nil {
+		t.Fatal("expected ResolvedPath to be set on tx after pickBestObservation")
+	}
+	if *tx.ResolvedPath[0] != "aabbccdd" {
+		t.Errorf("expected resolved path to be aabbccdd, got %s", *tx.ResolvedPath[0])
+	}
+}
+
+func TestResolvedPathInTxToMap(t *testing.T) {
+	pk := "aabbccdd"
+	tx := &StoreTx{
+		ID:           1,
+		Hash:         "abc123",
+		PathJSON:     `["aa"]`,
+		ResolvedPath: []*string{&pk},
+		obsKeys:      make(map[string]bool),
+	}
+
+	m := txToMap(tx)
+	rp, ok := m["resolved_path"]
+	if !ok {
+		t.Fatal("resolved_path not in txToMap output")
+	}
+	rpSlice, ok := rp.([]*string)
+	if !ok || len(rpSlice) != 1 || *rpSlice[0] != "aabbccdd" {
+		t.Errorf("unexpected resolved_path: %v", rp)
+	}
+}
+
+func TestResolvedPathOmittedWhenNil(t *testing.T) {
+	tx := &StoreTx{
+		ID:      1,
+		Hash:    "abc123",
+		obsKeys: make(map[string]bool),
+	}
+
+	m := txToMap(tx)
+	if _, ok := m["resolved_path"]; ok {
+		t.Error("resolved_path should not be in map when nil")
+	}
+}
+
+func TestEnsureResolvedPathColumn(t *testing.T) {
+	dir := t.TempDir()
+	dbPath := filepath.Join(dir, "test.db")
+
+	conn, _ := sql.Open("sqlite", "file:"+dbPath+"?_journal_mode=WAL")
+	conn.Exec(`CREATE TABLE observations (
+		id INTEGER PRIMARY KEY, transmission_id INTEGER,
+		observer_id TEXT, path_json TEXT, timestamp TEXT
+	)`)
+	conn.Close()
+
+	if err := ensureResolvedPathColumn(dbPath); err != nil {
+		t.Fatal(err)
+	}
+
+	// Verify column exists
+	conn, _ = sql.Open("sqlite", "file:"+dbPath+"?mode=ro")
+	defer conn.Close()
+	rows, _ := conn.Query("PRAGMA table_info(observations)")
+	found := false
+	for rows.Next() {
+		var cid int
+		var colName string
+		var colType sql.NullString
+		var notNull, pk int
+		var dflt sql.NullString
+		rows.Scan(&cid, &colName, &colType, &notNull, &dflt, &pk)
+		if colName == "resolved_path" {
+			found = true
+		}
+	}
+	rows.Close()
+	if !found {
+		t.Error("resolved_path column not added")
+	}
+
+	// Running again should be idempotent
+	if err := ensureResolvedPathColumn(dbPath); err != nil {
+		t.Fatal("second call should be idempotent:", err)
+	}
+}
+
+func TestDBDetectsResolvedPathColumn(t *testing.T) {
+	dir := t.TempDir()
+	dbPath := filepath.Join(dir, "test.db")
+
+	// Create DB without resolved_path
+	conn, _ := sql.Open("sqlite", "file:"+dbPath+"?_journal_mode=WAL")
+	conn.Exec(`CREATE TABLE observations (id INTEGER PRIMARY KEY, observer_idx INTEGER)`)
+	conn.Exec(`CREATE TABLE transmissions (id INTEGER PRIMARY KEY)`)
+	conn.Close()
+
+	db, err := OpenDB(dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if db.hasResolvedPath {
+		t.Error("should not detect resolved_path when column missing")
+	}
+	db.Close()
+
+	// Add resolved_path column
+	conn, _ = sql.Open("sqlite", "file:"+dbPath+"?_journal_mode=WAL")
+	conn.Exec("ALTER TABLE observations ADD COLUMN resolved_path TEXT")
+	conn.Close()
+
+	db, err = OpenDB(dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !db.hasResolvedPath {
+		t.Error("should detect resolved_path when column exists")
+	}
+	db.Close()
+}
+
+func TestLoadWithResolvedPath(t *testing.T) {
+	db, dbPath := createTestDBWithSchema(t)
+	defer db.Close()
+
+	// Insert test data
+	rw, _ := openRW(dbPath)
+	rw.Exec(`INSERT INTO transmissions (id, hash, first_seen, payload_type, decoded_json)
+		VALUES (1, 'hash1', '2024-01-01T00:00:00Z', 4, '{"pubKey":"origpk"}')`)
+	rw.Exec(`INSERT INTO observations (id, transmission_id, observer_id, observer_name, path_json, timestamp, resolved_path)
+		VALUES (1, 1, 'obs1', 'Observer1', '["aa"]', '2024-01-01T00:00:00Z', '["aabbccdd"]')`)
+	rw.Close()
+
+	store := NewPacketStore(db, nil)
+	if err := store.Load(); err != nil {
+		t.Fatal(err)
+	}
+
+	if len(store.packets) != 1 {
+		t.Fatalf("expected 1 packet, got %d", len(store.packets))
+	}
+
+	tx := store.packets[0]
+	if len(tx.Observations) != 1 {
+		t.Fatalf("expected 1 observation, got %d", len(tx.Observations))
+	}
+
+	obs := tx.Observations[0]
+	if obs.ResolvedPath == nil {
+		t.Fatal("expected ResolvedPath to be loaded")
+	}
+	if len(obs.ResolvedPath) != 1 || *obs.ResolvedPath[0] != "aabbccdd" {
+		t.Errorf("unexpected ResolvedPath: %v", obs.ResolvedPath)
+	}
+
+	// Check that pickBestObservation propagated resolved_path to tx
+	if tx.ResolvedPath == nil || len(tx.ResolvedPath) != 1 {
+		t.Error("expected ResolvedPath to be propagated to tx")
+	}
+}
+
+func TestResolvedPathInAPIResponse(t *testing.T) {
+	// Test that TransmissionResp properly marshals resolved_path
+	pk := "aabbccddee"
+	resp := TransmissionResp{
+		ID:           1,
+		Hash:         "test",
+		ResolvedPath: []*string{&pk, nil},
+	}
+
+	data, err := json.Marshal(resp)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var m map[string]interface{}
+	json.Unmarshal(data, &m)
+
+	rp, ok := m["resolved_path"]
+	if !ok {
+		t.Fatal("resolved_path missing from JSON")
+	}
+	rpArr, ok := rp.([]interface{})
+	if !ok || len(rpArr) != 2 {
+		t.Fatalf("unexpected resolved_path shape: %v", rp)
+	}
+	if rpArr[0] != "aabbccddee" {
+		t.Errorf("first element wrong: %v", rpArr[0])
+	}
+	if rpArr[1] != nil {
+		t.Errorf("second element should be null: %v", rpArr[1])
+	}
+}
+
+func TestResolvedPathOmittedWhenEmpty(t *testing.T) {
+	resp := TransmissionResp{
+		ID:   1,
+		Hash: "test",
+	}
+
+	data, _ := json.Marshal(resp)
+	var m map[string]interface{}
+	json.Unmarshal(data, &m)
+
+	if _, ok := m["resolved_path"]; ok {
+		t.Error("resolved_path should be omitted when nil")
+	}
+}
+
+func TestExtractEdgesFromObs_AdvertNoPath(t *testing.T) {
+	tx := &StoreTx{
+		DecodedJSON: `{"pubKey":"aaaa1111"}`,
+		PayloadType: intPtr(4),
+	}
+	obs := &StoreObs{
+		ObserverID: "bbbb2222",
+		PathJSON:   "",
+		Timestamp:  "2024-01-01T00:00:00Z",
+	}
+
+	edges := extractEdgesFromObs(obs, tx, nil)
+	if len(edges) != 1 {
+		t.Fatalf("expected 1 edge for zero-hop advert, got %d", len(edges))
+	}
+	// Canonical ordering: aaaa < bbbb
+	if edges[0].A != "aaaa1111" || edges[0].B != "bbbb2222" {
+		t.Errorf("unexpected edge: %+v", edges[0])
+	}
+}
+
+func TestExtractEdgesFromObs_NonAdvertNoPath(t *testing.T) {
+	tx := &StoreTx{PayloadType: intPtr(1)}
+	obs := &StoreObs{ObserverID: "obs1", PathJSON: ""}
+	edges := extractEdgesFromObs(obs, tx, nil)
+	if len(edges) != 0 {
+		t.Errorf("expected 0 edges for non-advert without path, got %d", len(edges))
+	}
+}
+
+func TestExtractEdgesFromObs_WithPath(t *testing.T) {
+	nodes := []nodeInfo{
+		{PublicKey: "aabbccddee1234567890aabbccddee1234567890aabbccddee1234567890aabb", Name: "Node-AA"},
+		{PublicKey: "ffgghhii1234567890aabbccddee1234567890aabbccddee1234567890aabb11", Name: "Node-FF"},
+	}
+	pm := buildPrefixMap(nodes)
+
+	tx := &StoreTx{
+		DecodedJSON: `{"pubKey":"originator00"}`,
+		PayloadType: intPtr(4),
+	}
+	obs := &StoreObs{
+		ObserverID: "observer00",
+		PathJSON:   `["aa","ff"]`,
+		Timestamp:  "2024-01-01T00:00:00Z",
+	}
+
+	edges := extractEdgesFromObs(obs, tx, pm)
+	// Should get: originator↔aa (advert), observer↔ff (last hop)
+	if len(edges) != 2 {
+		t.Fatalf("expected 2 edges, got %d", len(edges))
+	}
+}
+
+func TestExtractEdgesFromObs_SameNodeNoEdge(t *testing.T) {
+	tx := &StoreTx{
+		DecodedJSON: `{"pubKey":"same1234"}`,
+		PayloadType: intPtr(4),
+	}
+	obs := &StoreObs{
+		ObserverID: "same1234",
+		PathJSON:   "",
+		Timestamp:  "2024-01-01T00:00:00Z",
+	}
+	edges := extractEdgesFromObs(obs, tx, nil)
+	if len(edges) != 0 {
+		t.Errorf("expected 0 edges when originator == observer, got %d", len(edges))
+	}
+}
+
+
+
+func TestPersistSemaphoreTryAcquireSkipsBatch(t *testing.T) {
+	// Verify that persistSem is a buffered channel of size 1.
+	if cap(persistSem) != 1 {
+		t.Errorf("persistSem capacity = %d, want 1", cap(persistSem))
+	}
+	// Acquire the semaphore to simulate an in-progress persistence.
+	persistSem <- struct{}{}
+
+	// asyncPersistResolvedPathsAndEdges should skip (not block, not
+	// spawn a goroutine) when the semaphore is already held.
+	done := make(chan struct{})
+	go func() {
+		asyncPersistResolvedPathsAndEdges(
+			"/nonexistent/path.db",
+			[]persistObsUpdate{{obsID: 1, resolvedPath: "x"}},
+			nil,
+			"test",
+		)
+		close(done)
+	}()
+
+	// If the function blocks on the semaphore instead of skipping,
+	// this select will hit the timeout.
+	select {
+	case <-done:
+		// Expected: returned immediately because semaphore was busy.
+	case <-time.After(500 * time.Millisecond):
+		<-persistSem
+		t.Fatal("asyncPersistResolvedPathsAndEdges blocked instead of skipping when semaphore was held")
+	}
+
+	<-persistSem // release
+}

cmd/server/obs_dedup_test.go

@@ -0,0 +1,134 @@
+package main
+
+import (
+	"fmt"
+	"testing"
+)
+
+// TestObsDedupCorrectness verifies that the map-based dedup produces correct
+// results: no duplicate observations (same observerID + pathJSON) on a single
+// transmission.
+func TestObsDedupCorrectness(t *testing.T) {
+	tx := &StoreTx{
+		ID:      1,
+		Hash:    "abc123",
+		obsKeys: make(map[string]bool),
+	}
+
+	// Add 5 unique observations
+	for i := 0; i < 5; i++ {
+		obsID := fmt.Sprintf("obs-%d", i)
+		pathJSON := fmt.Sprintf(`["path-%d"]`, i)
+		dk := obsID + "|" + pathJSON
+		if tx.obsKeys[dk] {
+			t.Fatalf("observation %d should not be a duplicate", i)
+		}
+		tx.Observations = append(tx.Observations, &StoreObs{
+			ID:         i,
+			ObserverID: obsID,
+			PathJSON:   pathJSON,
+		})
+		tx.obsKeys[dk] = true
+		tx.ObservationCount++
+	}
+
+	if tx.ObservationCount != 5 {
+		t.Fatalf("expected 5 observations, got %d", tx.ObservationCount)
+	}
+
+	// Try to add duplicates of each — all should be rejected
+	for i := 0; i < 5; i++ {
+		obsID := fmt.Sprintf("obs-%d", i)
+		pathJSON := fmt.Sprintf(`["path-%d"]`, i)
+		dk := obsID + "|" + pathJSON
+		if !tx.obsKeys[dk] {
+			t.Fatalf("observation %d should be detected as duplicate", i)
+		}
+	}
+
+	// Same observer, different path — should NOT be a duplicate
+	dk := "obs-0" + "|" + `["different-path"]`
+	if tx.obsKeys[dk] {
+		t.Fatal("different path should not be a duplicate")
+	}
+
+	// Different observer, same path — should NOT be a duplicate
+	dk = "obs-new" + "|" + `["path-0"]`
+	if tx.obsKeys[dk] {
+		t.Fatal("different observer should not be a duplicate")
+	}
+}
+
+// TestObsDedupNilMapSafety ensures obsKeys lazy init works for pre-existing
+// transmissions that may not have the map initialized.
+func TestObsDedupNilMapSafety(t *testing.T) {
+	tx := &StoreTx{ID: 1, Hash: "abc"}
+	// obsKeys is nil — the lazy init pattern used in IngestNewFromDB/IngestNewObservations
+	if tx.obsKeys == nil {
+		tx.obsKeys = make(map[string]bool)
+	}
+	dk := "obs1|path1"
+	if tx.obsKeys[dk] {
+		t.Fatal("should not be duplicate on empty map")
+	}
+	tx.obsKeys[dk] = true
+	if !tx.obsKeys[dk] {
+		t.Fatal("should be duplicate after insert")
+	}
+}
+
+// BenchmarkObsDedupMap benchmarks the map-based O(1) dedup approach.
+func BenchmarkObsDedupMap(b *testing.B) {
+	for _, obsCount := range []int{10, 50, 100, 500} {
+		b.Run(fmt.Sprintf("obs=%d", obsCount), func(b *testing.B) {
+			// Pre-populate a tx with obsCount observations
+			tx := &StoreTx{
+				ID:      1,
+				obsKeys: make(map[string]bool),
+			}
+			for i := 0; i < obsCount; i++ {
+				obsID := fmt.Sprintf("obs-%d", i)
+				pathJSON := fmt.Sprintf(`["hop-%d"]`, i)
+				dk := obsID + "|" + pathJSON
+				tx.Observations = append(tx.Observations, &StoreObs{
+					ObserverID: obsID,
+					PathJSON:   pathJSON,
+				})
+				tx.obsKeys[dk] = true
+			}
+
+			// Benchmark: check dedup for a new observation (not duplicate)
+			newDK := "new-obs|new-path"
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				_ = tx.obsKeys[newDK]
+			}
+		})
+	}
+}
+
+// BenchmarkObsDedupLinear benchmarks the old O(n) linear scan for comparison.
+func BenchmarkObsDedupLinear(b *testing.B) {
+	for _, obsCount := range []int{10, 50, 100, 500} {
+		b.Run(fmt.Sprintf("obs=%d", obsCount), func(b *testing.B) {
+			tx := &StoreTx{ID: 1}
+			for i := 0; i < obsCount; i++ {
+				tx.Observations = append(tx.Observations, &StoreObs{
+					ObserverID: fmt.Sprintf("obs-%d", i),
+					PathJSON:   fmt.Sprintf(`["hop-%d"]`, i),
+				})
+			}
+
+			newObsID := "new-obs"
+			newPath := "new-path"
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				for _, existing := range tx.Observations {
+					if existing.ObserverID == newObsID && existing.PathJSON == newPath {
+						break
+					}
+				}
+			}
+		})
+	}
+}

cmd/server/perfstats_race_test.go

@@ -0,0 +1,95 @@
+package main
+
+import (
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestPerfStatsConcurrentAccess verifies that concurrent writes and reads
+// to PerfStats do not trigger data races. Run with: go test -race
+func TestPerfStatsConcurrentAccess(t *testing.T) {
+	ps := NewPerfStats()
+
+	var wg sync.WaitGroup
+	const goroutines = 50
+	const iterations = 200
+
+	// Concurrent writers (simulating perfMiddleware)
+	for i := 0; i < goroutines; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for j := 0; j < iterations; j++ {
+				ms := float64(j) * 0.5
+				key := "/api/test"
+				if id%2 == 0 {
+					key = "/api/other"
+				}
+
+				ps.mu.Lock()
+				ps.Requests++
+				ps.TotalMs += ms
+				if _, ok := ps.Endpoints[key]; !ok {
+					ps.Endpoints[key] = &EndpointPerf{Recent: make([]float64, 0, 100)}
+				}
+				ep := ps.Endpoints[key]
+				ep.Count++
+				ep.TotalMs += ms
+				if ms > ep.MaxMs {
+					ep.MaxMs = ms
+				}
+				ep.Recent = append(ep.Recent, ms)
+				if len(ep.Recent) > 100 {
+					ep.Recent = ep.Recent[1:]
+				}
+				if ms > 50 {
+					ps.SlowQueries = append(ps.SlowQueries, SlowQuery{
+						Path: key,
+						Ms:   ms,
+						Time: time.Now().UTC().Format(time.RFC3339),
+					})
+					if len(ps.SlowQueries) > 50 {
+						ps.SlowQueries = ps.SlowQueries[1:]
+					}
+				}
+				ps.mu.Unlock()
+			}
+		}(i)
+	}
+
+	// Concurrent readers (simulating handlePerf / handleHealth)
+	for i := 0; i < 10; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for j := 0; j < iterations; j++ {
+				ps.mu.Lock()
+				_ = ps.Requests
+				_ = ps.TotalMs
+				for _, ep := range ps.Endpoints {
+					_ = ep.Count
+					_ = ep.MaxMs
+					c := make([]float64, len(ep.Recent))
+					copy(c, ep.Recent)
+				}
+				s := make([]SlowQuery, len(ps.SlowQueries))
+				copy(s, ps.SlowQueries)
+				ps.mu.Unlock()
+			}
+		}()
+	}
+
+	wg.Wait()
+
+	// Verify consistency
+	ps.mu.Lock()
+	defer ps.mu.Unlock()
+	expectedRequests := int64(goroutines * iterations)
+	if ps.Requests != expectedRequests {
+		t.Errorf("expected %d requests, got %d", expectedRequests, ps.Requests)
+	}
+	if len(ps.Endpoints) == 0 {
+		t.Error("expected endpoints to be populated")
+	}
+}

cmd/server/resolve_context_test.go

@@ -0,0 +1,309 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// ─── resolveWithContext unit tests ─────────────────────────────────────────────
+
+func TestResolveWithContext_UniquePrefix(t *testing.T) {
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1b2c3d4", Name: "Node-A", HasGPS: true, Lat: 1, Lon: 2},
+	})
+	ni, confidence, _ := pm.resolveWithContext("a1b2c3d4", nil, nil)
+	if ni == nil || ni.Name != "Node-A" {
+		t.Fatal("expected Node-A")
+	}
+	if confidence != "unique_prefix" {
+		t.Fatalf("expected unique_prefix, got %s", confidence)
+	}
+}
+
+func TestResolveWithContext_NoMatch(t *testing.T) {
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1b2c3d4", Name: "Node-A"},
+	})
+	ni, confidence, _ := pm.resolveWithContext("ff", nil, nil)
+	if ni != nil {
+		t.Fatal("expected nil")
+	}
+	if confidence != "no_match" {
+		t.Fatalf("expected no_match, got %s", confidence)
+	}
+}
+
+func TestResolveWithContext_AffinityWins(t *testing.T) {
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1aaaaaa", Name: "Node-A1"},
+		{PublicKey: "a1bbbbbb", Name: "Node-A2"},
+	})
+
+	graph := NewNeighborGraph()
+	for i := 0; i < 100; i++ {
+		graph.upsertEdge("c0c0c0c0", "a1aaaaaa", "a1", "obs1", nil, time.Now())
+	}
+
+	ni, confidence, score := pm.resolveWithContext("a1", []string{"c0c0c0c0"}, graph)
+	if ni == nil || ni.Name != "Node-A1" {
+		t.Fatalf("expected Node-A1, got %v", ni)
+	}
+	if confidence != "neighbor_affinity" {
+		t.Fatalf("expected neighbor_affinity, got %s", confidence)
+	}
+	if score <= 0 {
+		t.Fatalf("expected positive score, got %f", score)
+	}
+}
+
+func TestResolveWithContext_AffinityTooClose_FallsToGeo(t *testing.T) {
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1aaaaaa", Name: "Node-A1", HasGPS: true, Lat: 10, Lon: 20},
+		{PublicKey: "a1bbbbbb", Name: "Node-A2", HasGPS: true, Lat: 11, Lon: 21},
+		{PublicKey: "c0c0c0c0", Name: "Ctx", HasGPS: true, Lat: 10.1, Lon: 20.1},
+	})
+
+	graph := NewNeighborGraph()
+	for i := 0; i < 50; i++ {
+		graph.upsertEdge("c0c0c0c0", "a1aaaaaa", "a1", "obs1", nil, time.Now())
+		graph.upsertEdge("c0c0c0c0", "a1bbbbbb", "a1", "obs1", nil, time.Now())
+	}
+
+	ni, confidence, _ := pm.resolveWithContext("a1", []string{"c0c0c0c0"}, graph)
+	if ni == nil {
+		t.Fatal("expected a result")
+	}
+	if confidence != "geo_proximity" {
+		t.Fatalf("expected geo_proximity, got %s", confidence)
+	}
+	if ni.Name != "Node-A1" {
+		t.Fatalf("expected Node-A1 (closer to context), got %s", ni.Name)
+	}
+}
+
+func TestResolveWithContext_GPSPreference(t *testing.T) {
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1aaaaaa", Name: "NoGPS"},
+		{PublicKey: "a1bbbbbb", Name: "HasGPS", HasGPS: true, Lat: 1, Lon: 2},
+	})
+
+	ni, confidence, _ := pm.resolveWithContext("a1", nil, nil)
+	if ni == nil || ni.Name != "HasGPS" {
+		t.Fatalf("expected HasGPS, got %v", ni)
+	}
+	if confidence != "gps_preference" {
+		t.Fatalf("expected gps_preference, got %s", confidence)
+	}
+}
+
+func TestResolveWithContext_FirstMatchFallback(t *testing.T) {
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1aaaaaa", Name: "First"},
+		{PublicKey: "a1bbbbbb", Name: "Second"},
+	})
+
+	ni, confidence, _ := pm.resolveWithContext("a1", nil, nil)
+	if ni == nil || ni.Name != "First" {
+		t.Fatalf("expected First, got %v", ni)
+	}
+	if confidence != "first_match" {
+		t.Fatalf("expected first_match, got %s", confidence)
+	}
+}
+
+func TestResolveWithContext_NilGraphFallsToGPS(t *testing.T) {
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1aaaaaa", Name: "NoGPS"},
+		{PublicKey: "a1bbbbbb", Name: "HasGPS", HasGPS: true, Lat: 1, Lon: 2},
+	})
+
+	ni, confidence, _ := pm.resolveWithContext("a1", []string{"someone"}, nil)
+	if ni == nil || ni.Name != "HasGPS" {
+		t.Fatalf("expected HasGPS, got %v", ni)
+	}
+	if confidence != "gps_preference" {
+		t.Fatalf("expected gps_preference, got %s", confidence)
+	}
+}
+
+func TestResolveWithContext_BackwardCompatResolve(t *testing.T) {
+	// Verify original resolve() still works unchanged
+	pm := buildPrefixMap([]nodeInfo{
+		{PublicKey: "a1aaaaaa", Name: "NoGPS"},
+		{PublicKey: "a1bbbbbb", Name: "HasGPS", HasGPS: true, Lat: 1, Lon: 2},
+	})
+	ni := pm.resolve("a1")
+	if ni == nil || ni.Name != "HasGPS" {
+		t.Fatalf("expected HasGPS from resolve(), got %v", ni)
+	}
+}
+
+// ─── geoDistApprox ─────────────────────────────────────────────────────────────
+
+func TestGeoDistApprox_SamePoint(t *testing.T) {
+	d := geoDistApprox(37.0, -122.0, 37.0, -122.0)
+	if d != 0 {
+		t.Fatalf("expected 0, got %f", d)
+	}
+}
+
+func TestGeoDistApprox_Ordering(t *testing.T) {
+	d1 := geoDistApprox(37.0, -122.0, 37.01, -122.01)
+	d2 := geoDistApprox(37.0, -122.0, 38.0, -121.0)
+	if d1 >= d2 {
+		t.Fatal("closer point should have smaller distance")
+	}
+}
+
+// ─── handleResolveHops enhanced response (API tests) ───────────────────────────
+
+func TestResolveHopsAPI_UniquePrefix(t *testing.T) {
+	srv, router := setupTestServer(t)
+	_ = srv
+
+	// Insert a unique node
+	srv.db.conn.Exec("INSERT OR IGNORE INTO nodes (public_key, name, lat, lon) VALUES (?, ?, ?, ?)",
+		"ff11223344", "UniqueNode", 37.0, -122.0)
+	srv.store.InvalidateNodeCache()
+
+	req := httptest.NewRequest("GET", "/api/resolve-hops?hops=ff11223344", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	var result ResolveHopsResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &result); err != nil {
+		t.Fatalf("bad JSON: %v", err)
+	}
+
+	hr, ok := result.Resolved["ff11223344"]
+	if !ok {
+		t.Fatal("expected hop in resolved map")
+	}
+	if hr.Confidence != "unique_prefix" {
+		t.Fatalf("expected unique_prefix, got %s", hr.Confidence)
+	}
+}
+
+func TestResolveHopsAPI_AmbiguousNoContext(t *testing.T) {
+	srv, router := setupTestServer(t)
+
+	srv.db.conn.Exec("INSERT OR IGNORE INTO nodes (public_key, name, lat, lon) VALUES (?, ?, ?, ?)",
+		"ee1aaaaaaa", "Node-E1", 37.0, -122.0)
+	srv.db.conn.Exec("INSERT OR IGNORE INTO nodes (public_key, name, lat, lon) VALUES (?, ?, ?, ?)",
+		"ee1bbbbbbb", "Node-E2", 38.0, -121.0)
+	srv.store.InvalidateNodeCache()
+
+	req := httptest.NewRequest("GET", "/api/resolve-hops?hops=ee1", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	var result ResolveHopsResponse
+	json.Unmarshal(rr.Body.Bytes(), &result)
+
+	hr := result.Resolved["ee1"]
+	if hr == nil {
+		t.Fatal("expected hop in resolved map")
+	}
+	// With both candidates having GPS and no affinity context, the resolver
+	// picks the GPS-preferred candidate → confidence is "gps_preference".
+	if hr.Confidence != "gps_preference" {
+		t.Fatalf("expected gps_preference, got %s", hr.Confidence)
+	}
+	if len(hr.Candidates) != 2 {
+		t.Fatalf("expected 2 candidates, got %d", len(hr.Candidates))
+	}
+	for _, c := range hr.Candidates {
+		if c.AffinityScore != nil {
+			t.Fatal("expected nil affinity score without context")
+		}
+	}
+}
+
+func TestResolveHopsAPI_WithAffinityContext(t *testing.T) {
+	srv, router := setupTestServer(t)
+
+	srv.db.conn.Exec("INSERT OR IGNORE INTO nodes (public_key, name, lat, lon) VALUES (?, ?, ?, ?)",
+		"dd1aaaaaaa", "Node-D1", 37.0, -122.0)
+	srv.db.conn.Exec("INSERT OR IGNORE INTO nodes (public_key, name, lat, lon) VALUES (?, ?, ?, ?)",
+		"dd1bbbbbbb", "Node-D2", 38.0, -121.0)
+	srv.db.conn.Exec("INSERT OR IGNORE INTO nodes (public_key, name, lat, lon) VALUES (?, ?, ?, ?)",
+		"c0c0c0c0c0", "Context", 37.1, -122.1)
+
+	// Invalidate node cache so the PM includes newly inserted nodes.
+	srv.store.cacheMu.Lock()
+	srv.store.nodeCacheTime = time.Time{}
+	srv.store.cacheMu.Unlock()
+
+	// Build graph with strong affinity
+	graph := NewNeighborGraph()
+	for i := 0; i < 100; i++ {
+		graph.upsertEdge("c0c0c0c0c0", "dd1aaaaaaa", "dd1", "obs1", nil, time.Now())
+	}
+	graph.builtAt = time.Now()
+	srv.neighborMu.Lock()
+	srv.neighborGraph = graph
+	srv.neighborMu.Unlock()
+
+	req := httptest.NewRequest("GET", "/api/resolve-hops?hops=dd1&from_node=c0c0c0c0c0", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	var result ResolveHopsResponse
+	json.Unmarshal(rr.Body.Bytes(), &result)
+
+	hr := result.Resolved["dd1"]
+	if hr == nil {
+		t.Fatal("expected hop in resolved map")
+	}
+	if hr.Confidence != "neighbor_affinity" {
+		t.Fatalf("expected neighbor_affinity, got %s", hr.Confidence)
+	}
+	if hr.BestCandidate == nil || *hr.BestCandidate != "dd1aaaaaaa" {
+		t.Fatalf("expected bestCandidate dd1aaaaaaa, got %v", hr.BestCandidate)
+	}
+
+	// Verify affinity scores present
+	hasScore := false
+	for _, c := range hr.Candidates {
+		if c.AffinityScore != nil && *c.AffinityScore > 0 {
+			hasScore = true
+		}
+	}
+	if !hasScore {
+		t.Fatal("expected at least one candidate with affinity score")
+	}
+}
+
+func TestResolveHopsAPI_ResponseShape(t *testing.T) {
+	srv, router := setupTestServer(t)
+
+	srv.db.conn.Exec("INSERT OR IGNORE INTO nodes (public_key, name, lat, lon) VALUES (?, ?, ?, ?)",
+		"bb1aaaaaaa", "Node-B1", 37.0, -122.0)
+
+	req := httptest.NewRequest("GET", "/api/resolve-hops?hops=bb1a", nil)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	var raw map[string]json.RawMessage
+	json.Unmarshal(rr.Body.Bytes(), &raw)
+
+	if _, ok := raw["resolved"]; !ok {
+		t.Fatal("missing 'resolved' key")
+	}
+
+	var resolved map[string]map[string]interface{}
+	json.Unmarshal(raw["resolved"], &resolved)
+
+	for _, hr := range resolved {
+		if _, ok := hr["confidence"]; !ok {
+			t.Error("missing 'confidence' field in HopResolution")
+		}
+		if _, ok := hr["candidates"]; !ok {
+			t.Error("missing 'candidates' field")
+		}
+	}
+}
+
+// ─── Helpers used only in this test file ───────────────────────────────────────

cmd/server/routes.go

@@ -38,10 +38,15 @@ type Server struct {
 	statsMu      sync.Mutex
 	statsCache   *StatsResponse
 	statsCachedAt time.Time
+
+	// Neighbor affinity graph (lazy-built, cached with TTL)
+	neighborMu    sync.Mutex
+	neighborGraph *NeighborGraph
 }
 
 // PerfStats tracks request performance.
 type PerfStats struct {
+	mu          sync.Mutex
 	Requests    int64
 	TotalMs     float64
 	Endpoints   map[string]*EndpointPerf
@@ -109,8 +114,11 @@ func (s *Server) RegisterRoutes(r *mux.Router) {
 	r.HandleFunc("/api/stats", s.handleStats).Methods("GET")
 	r.HandleFunc("/api/perf", s.handlePerf).Methods("GET")
 	r.Handle("/api/perf/reset", s.requireAPIKey(http.HandlerFunc(s.handlePerfReset))).Methods("POST")
+	r.Handle("/api/admin/prune", s.requireAPIKey(http.HandlerFunc(s.handleAdminPrune))).Methods("POST")
+	r.Handle("/api/debug/affinity", s.requireAPIKey(http.HandlerFunc(s.handleDebugAffinity))).Methods("GET")
 
 	// Packet endpoints
+	r.HandleFunc("/api/packets/observations", s.handleBatchObservations).Methods("POST")
 	r.HandleFunc("/api/packets/timestamps", s.handlePacketTimestamps).Methods("GET")
 	r.HandleFunc("/api/packets/{id}", s.handlePacketDetail).Methods("GET")
 	r.HandleFunc("/api/packets", s.handlePackets).Methods("GET")
@@ -126,6 +134,7 @@ func (s *Server) RegisterRoutes(r *mux.Router) {
 	r.HandleFunc("/api/nodes/{pubkey}/health", s.handleNodeHealth).Methods("GET")
 	r.HandleFunc("/api/nodes/{pubkey}/paths", s.handleNodePaths).Methods("GET")
 	r.HandleFunc("/api/nodes/{pubkey}/analytics", s.handleNodeAnalytics).Methods("GET")
+	r.HandleFunc("/api/nodes/{pubkey}/neighbors", s.handleNodeNeighbors).Methods("GET")
 	r.HandleFunc("/api/nodes/{pubkey}", s.handleNodeDetail).Methods("GET")
 	r.HandleFunc("/api/nodes", s.handleNodes).Methods("GET")
 
@@ -135,8 +144,11 @@ func (s *Server) RegisterRoutes(r *mux.Router) {
 	r.HandleFunc("/api/analytics/channels", s.handleAnalyticsChannels).Methods("GET")
 	r.HandleFunc("/api/analytics/distance", s.handleAnalyticsDistance).Methods("GET")
 	r.HandleFunc("/api/analytics/hash-sizes", s.handleAnalyticsHashSizes).Methods("GET")
+	r.HandleFunc("/api/analytics/hash-collisions", s.handleAnalyticsHashCollisions).Methods("GET")
 	r.HandleFunc("/api/analytics/subpaths", s.handleAnalyticsSubpaths).Methods("GET")
+	r.HandleFunc("/api/analytics/subpaths-bulk", s.handleAnalyticsSubpathsBulk).Methods("GET")
 	r.HandleFunc("/api/analytics/subpath-detail", s.handleAnalyticsSubpathDetail).Methods("GET")
+	r.HandleFunc("/api/analytics/neighbor-graph", s.handleNeighborGraph).Methods("GET")
 
 	// Other endpoints
 	r.HandleFunc("/api/resolve-hops", s.handleResolveHops).Methods("GET")
@@ -160,10 +172,7 @@ func (s *Server) perfMiddleware(next http.Handler) http.Handler {
 		next.ServeHTTP(w, r)
 		ms := float64(time.Since(start).Microseconds()) / 1000.0
 
-		s.perfStats.Requests++
-		s.perfStats.TotalMs += ms
-
-		// Normalize key: prefer mux route template (like Node.js req.route.path)
+		// Normalize key outside lock (no shared state needed)
 		key := r.URL.Path
 		if route := mux.CurrentRoute(r); route != nil {
 			if tmpl, err := route.GetPathTemplate(); err == nil {
@@ -173,6 +182,11 @@ func (s *Server) perfMiddleware(next http.Handler) http.Handler {
 		if key == r.URL.Path {
 			key = perfHexFallback.ReplaceAllString(key, ":id")
 		}
+
+		s.perfStats.mu.Lock()
+		s.perfStats.Requests++
+		s.perfStats.TotalMs += ms
+
 		if _, ok := s.perfStats.Endpoints[key]; !ok {
 			s.perfStats.Endpoints[key] = &EndpointPerf{Recent: make([]float64, 0, 100)}
 		}
@@ -198,6 +212,7 @@ func (s *Server) perfMiddleware(next http.Handler) http.Handler {
 				s.perfStats.SlowQueries = s.perfStats.SlowQueries[1:]
 			}
 		}
+		s.perfStats.mu.Unlock()
 	})
 }
 
@@ -240,6 +255,7 @@ func (s *Server) handleConfigClient(w http.ResponseWriter, r *http.Request) {
 		ExternalUrls:        s.cfg.ExternalUrls,
 		PropagationBufferMs: float64(s.cfg.PropagationBufferMs()),
 		Timestamps:          s.cfg.GetTimestampConfig(),
+		DebugAffinity:       s.cfg.DebugAffinity,
 	})
 }
 
@@ -270,6 +286,26 @@ func (s *Server) handleConfigTheme(w http.ResponseWriter, r *http.Request) {
 		"accentHover": "#6db3ff",
 		"navBg":       "#0f0f23",
 		"navBg2":      "#1a1a2e",
+		"navText":     "#ffffff",
+		"navTextMuted": "#cbd5e1",
+		"background":  "#f4f5f7",
+		"text":        "#1a1a2e",
+		"textMuted":   "#5b6370",
+		"border":      "#e2e5ea",
+		"surface1":    "#ffffff",
+		"surface2":    "#ffffff",
+		"surface3":    "#ffffff",
+		"sectionBg":   "#eef2ff",
+		"cardBg":      "#ffffff",
+		"contentBg":   "#f4f5f7",
+		"detailBg":    "#ffffff",
+		"inputBg":     "#ffffff",
+		"rowStripe":   "#f9fafb",
+		"rowHover":    "#eef2ff",
+		"selectedBg":  "#dbeafe",
+		"statusGreen": "#22c55e",
+		"statusYellow": "#eab308",
+		"statusRed":   "#ef4444",
 	}, s.cfg.Theme, theme.Theme)
 
 	nodeColors := mergeMap(map[string]interface{}{
@@ -280,15 +316,60 @@ func (s *Server) handleConfigTheme(w http.ResponseWriter, r *http.Request) {
 		"observer":  "#8b5cf6",
 	}, s.cfg.NodeColors, theme.NodeColors)
 
-	themeDark := mergeMap(map[string]interface{}{}, s.cfg.ThemeDark, theme.ThemeDark)
-	typeColors := mergeMap(map[string]interface{}{}, s.cfg.TypeColors, theme.TypeColors)
+	themeDark := mergeMap(map[string]interface{}{
+		"accent":      "#4a9eff",
+		"accentHover": "#6db3ff",
+		"navBg":       "#0f0f23",
+		"navBg2":      "#1a1a2e",
+		"navText":     "#ffffff",
+		"navTextMuted": "#cbd5e1",
+		"background":  "#0f0f23",
+		"text":        "#e2e8f0",
+		"textMuted":   "#a8b8cc",
+		"border":      "#334155",
+		"surface1":    "#1a1a2e",
+		"surface2":    "#232340",
+		"cardBg":      "#1a1a2e",
+		"contentBg":   "#0f0f23",
+		"detailBg":    "#232340",
+		"inputBg":     "#1e1e34",
+		"rowStripe":   "#1e1e34",
+		"rowHover":    "#2d2d50",
+		"selectedBg":  "#1e3a5f",
+		"statusGreen": "#22c55e",
+		"statusYellow": "#eab308",
+		"statusRed":   "#ef4444",
+		"surface3":    "#2d2d50",
+		"sectionBg":   "#1e1e34",
+	}, s.cfg.ThemeDark, theme.ThemeDark)
+	typeColors := mergeMap(map[string]interface{}{
+		"ADVERT":   "#22c55e",
+		"GRP_TXT":  "#3b82f6",
+		"TXT_MSG":  "#f59e0b",
+		"ACK":      "#6b7280",
+		"REQUEST":  "#a855f7",
+		"RESPONSE": "#06b6d4",
+		"TRACE":    "#ec4899",
+		"PATH":     "#14b8a6",
+		"ANON_REQ": "#f43f5e",
+		"UNKNOWN":  "#6b7280",
+	}, s.cfg.TypeColors, theme.TypeColors)
 
-	var home interface{}
-	if theme.Home != nil {
-		home = theme.Home
-	} else if s.cfg.Home != nil {
-		home = s.cfg.Home
+	defaultHome := map[string]interface{}{
+		"heroTitle":    "CoreScope",
+		"heroSubtitle": "Real-time MeshCore LoRa mesh network analyzer",
+		"steps": []interface{}{
+			map[string]interface{}{"emoji": "🔵", "title": "Connect via Bluetooth", "description": "Flash **BLE companion** firmware from [MeshCore Flasher](https://flasher.meshcore.co.uk/).\n- Screenless devices: default PIN `123456`\n- Screen devices: random PIN shown on display\n- If pairing fails: forget device, reboot, re-pair"},
+			map[string]interface{}{"emoji": "📻", "title": "Set the right frequency preset", "description": "**US Recommended:**\n`910.525 MHz · BW 62.5 kHz · SF 7 · CR 5`\nSelect **\"US Recommended\"** in the app or flasher."},
+			map[string]interface{}{"emoji": "📡", "title": "Advertise yourself", "description": "Tap the signal icon → **Flood** to broadcast your node to the mesh. Companions only advert when you trigger it manually."},
+			map[string]interface{}{"emoji": "🔁", "title": "Check \"Heard N repeats\"", "description": "- **\"Sent\"** = transmitted, no confirmation\n- **\"Heard 0 repeats\"** = no repeater picked it up\n- **\"Heard 1+ repeats\"** = you're on the mesh!"},
+		},
+		"footerLinks": []interface{}{
+			map[string]interface{}{"label": "📦 Packets", "url": "#/packets"},
+			map[string]interface{}{"label": "🗺️ Network Map", "url": "#/map"},
+		},
 	}
+	home := mergeMap(defaultHome, s.cfg.Home, theme.Home)
 
 	writeJSON(w, ThemeResponse{
 		Branding:   branding,
@@ -363,7 +444,8 @@ func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
 		lastPauseMs = float64(m.PauseNs[(m.NumGC+255)%256]) / 1e6
 	}
 
-	// Build slow queries list
+	// Build slow queries list (copy under lock)
+	s.perfStats.mu.Lock()
 	recentSlow := make([]SlowQuery, 0)
 	sliceEnd := s.perfStats.SlowQueries
 	if len(sliceEnd) > 5 {
@@ -372,6 +454,10 @@ func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
 	for _, sq := range sliceEnd {
 		recentSlow = append(recentSlow, sq)
 	}
+	perfRequests := s.perfStats.Requests
+	perfTotalMs := s.perfStats.TotalMs
+	perfSlowCount := len(s.perfStats.SlowQueries)
+	s.perfStats.mu.Unlock()
 
 	writeJSON(w, HealthResponse{
 		Status:      "ok",
@@ -401,9 +487,9 @@ func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
 			EstimatedMB: pktEstMB,
 		},
 		Perf: HealthPerfStats{
-			TotalRequests: int(s.perfStats.Requests),
-			AvgMs:         safeAvg(s.perfStats.TotalMs, float64(s.perfStats.Requests)),
-			SlowQueries:   len(s.perfStats.SlowQueries),
+			TotalRequests: int(perfRequests),
+			AvgMs:         safeAvg(perfTotalMs, float64(perfRequests)),
+			SlowQueries:   perfSlowCount,
 			RecentSlow:    recentSlow,
 		},
 	})
@@ -463,22 +549,50 @@ func (s *Server) handleStats(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handlePerf(w http.ResponseWriter, r *http.Request) {
-	// Endpoint performance summary
+	// Copy perfStats under lock to avoid data races
+	s.perfStats.mu.Lock()
+	type epSnapshot struct {
+		path    string
+		count   int
+		totalMs float64
+		maxMs   float64
+		recent  []float64
+	}
+	epSnapshots := make([]epSnapshot, 0, len(s.perfStats.Endpoints))
+	for path, ep := range s.perfStats.Endpoints {
+		recentCopy := make([]float64, len(ep.Recent))
+		copy(recentCopy, ep.Recent)
+		epSnapshots = append(epSnapshots, epSnapshot{path, ep.Count, ep.TotalMs, ep.MaxMs, recentCopy})
+	}
+	uptimeSec := int(time.Since(s.perfStats.StartedAt).Seconds())
+	totalRequests := s.perfStats.Requests
+	totalMs := s.perfStats.TotalMs
+	slowQueries := make([]SlowQuery, 0)
+	sliceEnd := s.perfStats.SlowQueries
+	if len(sliceEnd) > 20 {
+		sliceEnd = sliceEnd[len(sliceEnd)-20:]
+	}
+	for _, sq := range sliceEnd {
+		slowQueries = append(slowQueries, sq)
+	}
+	s.perfStats.mu.Unlock()
+
+	// Process snapshots outside lock
 	type epEntry struct {
 		path string
 		data *EndpointStatsResp
 	}
 	var entries []epEntry
-	for path, ep := range s.perfStats.Endpoints {
-		sorted := sortedCopy(ep.Recent)
+	for _, snap := range epSnapshots {
+		sorted := sortedCopy(snap.recent)
 		d := &EndpointStatsResp{
-			Count: ep.Count,
-			AvgMs: safeAvg(ep.TotalMs, float64(ep.Count)),
+			Count: snap.count,
+			AvgMs: safeAvg(snap.totalMs, float64(snap.count)),
 			P50Ms: round(percentile(sorted, 0.5), 1),
 			P95Ms: round(percentile(sorted, 0.95), 1),
-			MaxMs: round(ep.MaxMs, 1),
+			MaxMs: round(snap.maxMs, 1),
 		}
-		entries = append(entries, epEntry{path, d})
+		entries = append(entries, epEntry{snap.path, d})
 	}
 	// Sort by total time spent (count * avg) descending, matching Node.js
 	sort.Slice(entries, func(i, j int) bool {
@@ -519,22 +633,10 @@ func (s *Server) handlePerf(w http.ResponseWriter, r *http.Request) {
 		sqliteStats = &ss
 	}
 
-	uptimeSec := int(time.Since(s.perfStats.StartedAt).Seconds())
-
-	// Convert slow queries
-	slowQueries := make([]SlowQuery, 0)
-	sliceEnd := s.perfStats.SlowQueries
-	if len(sliceEnd) > 20 {
-		sliceEnd = sliceEnd[len(sliceEnd)-20:]
-	}
-	for _, sq := range sliceEnd {
-		slowQueries = append(slowQueries, sq)
-	}
-
 	writeJSON(w, PerfResponse{
 		Uptime:        uptimeSec,
-		TotalRequests: s.perfStats.Requests,
-		AvgMs:         safeAvg(s.perfStats.TotalMs, float64(s.perfStats.Requests)),
+		TotalRequests: totalRequests,
+		AvgMs:         safeAvg(totalMs, float64(totalRequests)),
 		Endpoints:     summary,
 		SlowQueries:   slowQueries,
 		Cache:         perfCS,
@@ -558,7 +660,13 @@ func (s *Server) handlePerf(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handlePerfReset(w http.ResponseWriter, r *http.Request) {
-	s.perfStats = NewPerfStats()
+	s.perfStats.mu.Lock()
+	s.perfStats.Requests = 0
+	s.perfStats.TotalMs = 0
+	s.perfStats.Endpoints = make(map[string]*EndpointPerf)
+	s.perfStats.SlowQueries = make([]SlowQuery, 0)
+	s.perfStats.StartedAt = time.Now()
+	s.perfStats.mu.Unlock()
 	writeJSON(w, OkResp{Ok: true})
 }
 
@@ -612,7 +720,8 @@ func (s *Server) handlePackets(w http.ResponseWriter, r *http.Request) {
 		Until:    r.URL.Query().Get("until"),
 		Region:   r.URL.Query().Get("region"),
 		Node:     r.URL.Query().Get("node"),
-		Order:    "DESC",
+		Order:              "DESC",
+		ExpandObservations: r.URL.Query().Get("expand") == "observations",
 	}
 	if r.URL.Query().Get("order") == "asc" {
 		q.Order = "ASC"
@@ -654,13 +763,6 @@ func (s *Server) handlePackets(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Strip observations from default response
-	if r.URL.Query().Get("expand") != "observations" {
-		for _, p := range result.Packets {
-			delete(p, "observations")
-		}
-	}
-
 	writeJSON(w, result)
 }
 
@@ -685,6 +787,38 @@ var muxBraceParam = regexp.MustCompile(`\{([^}]+)\}`)
 // perfHexFallback matches hex IDs for perf path normalization fallback.
 var perfHexFallback = regexp.MustCompile(`[0-9a-f]{8,}`)
 
+// handleBatchObservations returns observations for multiple hashes in a single request.
+// POST /api/packets/observations with JSON body: {"hashes": ["abc123", "def456", ...]}
+// Response: {"results": {"abc123": [...observations...], "def456": [...], ...}}
+// Limited to 200 hashes per request to prevent abuse.
+func (s *Server) handleBatchObservations(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Hashes []string `json:"hashes"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, 400, "invalid JSON body")
+		return
+	}
+	const maxHashes = 200
+	if len(body.Hashes) > maxHashes {
+		writeError(w, 400, fmt.Sprintf("too many hashes (max %d)", maxHashes))
+		return
+	}
+	if len(body.Hashes) == 0 {
+		writeJSON(w, map[string]interface{}{"results": map[string]interface{}{}})
+		return
+	}
+
+	results := make(map[string][]ObservationResp, len(body.Hashes))
+	if s.store != nil {
+		for _, hash := range body.Hashes {
+			obs := s.store.GetObservationsForHash(hash)
+			results[hash] = mapSliceToObservations(obs)
+		}
+	}
+	writeJSON(w, map[string]interface{}{"results": results})
+}
+
 func (s *Server) handlePacketDetail(w http.ResponseWriter, r *http.Request) {
 	param := mux.Vars(r)["id"]
 	var packet map[string]interface{}
@@ -728,10 +862,11 @@ func (s *Server) handlePacketDetail(w http.ResponseWriter, r *http.Request) {
 		pathHops = []interface{}{}
 	}
 
+	rawHex, _ := packet["raw_hex"].(string)
 	writeJSON(w, PacketDetailResponse{
 		Packet:           packet,
 		Path:             pathHops,
-		Breakdown:        struct{}{},
+		Breakdown:        BuildBreakdown(rawHex),
 		ObservationCount: observationCount,
 		Observations:     mapSliceToObservations(observations),
 	})
@@ -855,6 +990,16 @@ func (s *Server) handleNodes(w http.ResponseWriter, r *http.Request) {
 			}
 		}
 	}
+	if s.cfg.GeoFilter != nil {
+		filtered := nodes[:0]
+		for _, node := range nodes {
+			if NodePassesGeoFilter(node["lat"], node["lon"], s.cfg.GeoFilter) {
+				filtered = append(filtered, node)
+			}
+		}
+		total = len(filtered)
+		nodes = filtered
+	}
 	writeJSON(w, NodeListResponse{Nodes: nodes, Total: total, Counts: counts})
 }
 
@@ -948,16 +1093,44 @@ func (s *Server) handleNodePaths(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	prefix1 := strings.ToLower(pubkey)
-	if len(prefix1) > 2 {
-		prefix1 = prefix1[:2]
-	}
-	prefix2 := strings.ToLower(pubkey)
+	// Use the precomputed byPathHop index instead of scanning all packets.
+	// Look up by full pubkey (resolved hops) and by short prefixes (raw hops).
+	lowerPK := strings.ToLower(pubkey)
+	prefix2 := lowerPK
 	if len(prefix2) > 4 {
 		prefix2 = prefix2[:4]
 	}
+	prefix1 := lowerPK
+	if len(prefix1) > 2 {
+		prefix1 = prefix1[:2]
+	}
+
 	s.store.mu.RLock()
 	_, pm := s.store.getCachedNodesAndPM()
+
+	// Collect candidate transmissions from the index, deduplicating by tx ID.
+	seen := make(map[int]bool)
+	var candidates []*StoreTx
+	addCandidates := func(key string) {
+		for _, tx := range s.store.byPathHop[key] {
+			if !seen[tx.ID] {
+				seen[tx.ID] = true
+				candidates = append(candidates, tx)
+			}
+		}
+	}
+	addCandidates(lowerPK) // full pubkey match (from resolved_path)
+	addCandidates(prefix1) // 2-char raw hop match
+	addCandidates(prefix2) // 4-char raw hop match
+	// Also check any raw hops that start with prefix2 (longer prefixes).
+	// Raw hops are typically 2 chars, so iterate only keys with HasPrefix
+	// on the small set of index keys rather than all packets.
+	for key := range s.store.byPathHop {
+		if len(key) > 4 && len(key) < len(lowerPK) && strings.HasPrefix(key, prefix2) {
+			addCandidates(key)
+		}
+	}
+
 	type pathAgg struct {
 		Hops       []PathHopResp
 		Count      int
@@ -971,28 +1144,13 @@ func (s *Server) handleNodePaths(w http.ResponseWriter, r *http.Request) {
 		if cached, ok := hopCache[hop]; ok {
 			return cached
 		}
-		r := pm.resolve(hop)
+		r, _, _ := pm.resolveWithContext(hop, nil, s.store.graph)
 		hopCache[hop] = r
 		return r
 	}
-	for _, tx := range s.store.packets {
-		hops := txGetParsedPath(tx)
-		if len(hops) == 0 {
-			continue
-		}
-		found := false
-		for _, hop := range hops {
-			hl := strings.ToLower(hop)
-			if hl == prefix1 || hl == prefix2 || strings.HasPrefix(hl, prefix2) {
-				found = true
-				break
-			}
-		}
-		if !found {
-			continue
-		}
-
+	for _, tx := range candidates {
 		totalTransmissions++
+		hops := txGetParsedPath(tx)
 		resolvedHops := make([]PathHopResp, len(hops))
 		sigParts := make([]string, len(hops))
 		for i, hop := range hops {
@@ -1190,6 +1348,18 @@ func (s *Server) handleAnalyticsHashSizes(w http.ResponseWriter, r *http.Request
 	})
 }
 
+func (s *Server) handleAnalyticsHashCollisions(w http.ResponseWriter, r *http.Request) {
+	if s.store != nil {
+		region := r.URL.Query().Get("region")
+		writeJSON(w, s.store.GetAnalyticsHashCollisions(region))
+		return
+	}
+	writeJSON(w, map[string]interface{}{
+		"inconsistent_nodes": []interface{}{},
+		"by_size":            map[string]interface{}{},
+	})
+}
+
 func (s *Server) handleAnalyticsSubpaths(w http.ResponseWriter, r *http.Request) {
 	if s.store != nil {
 		region := r.URL.Query().Get("region")
@@ -1208,6 +1378,57 @@ func (s *Server) handleAnalyticsSubpaths(w http.ResponseWriter, r *http.Request)
 	})
 }
 
+// handleAnalyticsSubpathsBulk returns multiple length-range buckets in a single
+// response, avoiding repeated scans of the same packet data. Query format:
+//   ?groups=2-2:50,3-3:30,4-4:20,5-8:15   (minLen-maxLen:limit per group)
+func (s *Server) handleAnalyticsSubpathsBulk(w http.ResponseWriter, r *http.Request) {
+	region := r.URL.Query().Get("region")
+	groupsParam := r.URL.Query().Get("groups")
+	if groupsParam == "" {
+		writeJSON(w, ErrorResp{Error: "groups parameter required (e.g. groups=2-2:50,3-3:30)"})
+		return
+	}
+
+	var groups []subpathGroup
+	for _, g := range strings.Split(groupsParam, ",") {
+		parts := strings.SplitN(g, ":", 2)
+		if len(parts) != 2 {
+			writeJSON(w, ErrorResp{Error: "invalid group format: " + g})
+			return
+		}
+		rangeParts := strings.SplitN(parts[0], "-", 2)
+		if len(rangeParts) != 2 {
+			writeJSON(w, ErrorResp{Error: "invalid range format: " + parts[0]})
+			return
+		}
+		mn, err1 := strconv.Atoi(rangeParts[0])
+		mx, err2 := strconv.Atoi(rangeParts[1])
+		lim, err3 := strconv.Atoi(parts[1])
+		if err1 != nil || err2 != nil || err3 != nil || mn < 2 || mx < mn || lim < 1 {
+			writeJSON(w, ErrorResp{Error: "invalid group: " + g})
+			return
+		}
+		groups = append(groups, subpathGroup{mn, mx, lim})
+	}
+
+	if s.store == nil {
+		results := make([]map[string]interface{}, len(groups))
+		for i := range groups {
+			results[i] = map[string]interface{}{"subpaths": []interface{}{}, "totalPaths": 0}
+		}
+		writeJSON(w, map[string]interface{}{"results": results})
+		return
+	}
+
+	results := s.store.GetAnalyticsSubpathsBulk(region, groups)
+	writeJSON(w, map[string]interface{}{"results": results})
+}
+
+// subpathGroup defines a length-range + limit for the bulk subpaths endpoint.
+type subpathGroup struct {
+	MinLen, MaxLen, Limit int
+}
+
 func (s *Server) handleAnalyticsSubpathDetail(w http.ResponseWriter, r *http.Request) {
 	hops := r.URL.Query().Get("hops")
 	if hops == "" {
@@ -1247,43 +1468,128 @@ func (s *Server) handleResolveHops(w http.ResponseWriter, r *http.Request) {
 	hops := strings.Split(hopsParam, ",")
 	resolved := map[string]*HopResolution{}
 
+	// Context for affinity-based disambiguation.
+	fromNode := r.URL.Query().Get("from_node")
+	observer := r.URL.Query().Get("observer")
+	var contextPubkeys []string
+	if fromNode != "" {
+		contextPubkeys = append(contextPubkeys, fromNode)
+	}
+	if observer != "" {
+		contextPubkeys = append(contextPubkeys, observer)
+	}
+
+	// Get the neighbor graph for affinity scoring (may be nil).
+	var graph *NeighborGraph
+	if len(contextPubkeys) > 0 {
+		graph = s.getNeighborGraph()
+	}
+
+	// Get the server's prefix map for resolveWithContext.
+	var pm *prefixMap
+	if s.store != nil {
+		s.store.mu.RLock()
+		_, pm = s.store.getCachedNodesAndPM()
+		s.store.mu.RUnlock()
+	}
+
 	for _, hop := range hops {
 		if hop == "" {
 			continue
 		}
 		hopLower := strings.ToLower(hop)
-		rows, err := s.db.conn.Query("SELECT public_key, name, lat, lon FROM nodes WHERE LOWER(public_key) LIKE ?", hopLower+"%")
-		if err != nil {
-			resolved[hop] = &HopResolution{Name: nil, Candidates: []HopCandidate{}, Conflicts: []interface{}{}}
-			continue
-		}
 
+		// Resolve candidates from the in-memory prefix map instead of
+		// issuing per-hop DB queries (fixes N+1 pattern, see #369).
 		var candidates []HopCandidate
-		for rows.Next() {
-			var pk string
-			var name sql.NullString
-			var lat, lon sql.NullFloat64
-			rows.Scan(&pk, &name, &lat, &lon)
-			candidates = append(candidates, HopCandidate{
-				Name: nullStr(name), Pubkey: pk,
-				Lat: nullFloat(lat), Lon: nullFloat(lon),
-			})
+		if pm != nil {
+			if matched, ok := pm.m[hopLower]; ok {
+				for _, ni := range matched {
+					c := HopCandidate{Pubkey: ni.PublicKey}
+					if ni.Name != "" {
+						c.Name = ni.Name
+					}
+					if ni.HasGPS {
+						c.Lat = ni.Lat
+						c.Lon = ni.Lon
+					}
+					candidates = append(candidates, c)
+				}
+			}
 		}
-		rows.Close()
 
 		if len(candidates) == 0 {
-			resolved[hop] = &HopResolution{Name: nil, Candidates: []HopCandidate{}, Conflicts: []interface{}{}}
+			resolved[hop] = &HopResolution{Name: nil, Candidates: []HopCandidate{}, Conflicts: []interface{}{}, Confidence: "no_match"}
 		} else if len(candidates) == 1 {
 			resolved[hop] = &HopResolution{
 				Name: candidates[0].Name, Pubkey: candidates[0].Pubkey,
 				Candidates: candidates, Conflicts: []interface{}{},
+				Confidence: "unique_prefix",
 			}
 		} else {
+			// Compute affinity scores for each candidate if we have context.
+			if graph != nil && len(contextPubkeys) > 0 {
+				now := time.Now()
+				for i := range candidates {
+					candPK := strings.ToLower(candidates[i].Pubkey)
+					bestScore := 0.0
+					for _, ctxPK := range contextPubkeys {
+						edges := graph.Neighbors(strings.ToLower(ctxPK))
+						for _, e := range edges {
+							if e.Ambiguous {
+								continue
+							}
+							otherPK := e.NodeA
+							if strings.EqualFold(otherPK, ctxPK) {
+								otherPK = e.NodeB
+							}
+							if strings.EqualFold(otherPK, candPK) {
+								sc := e.Score(now)
+								if sc > bestScore {
+									bestScore = sc
+								}
+							}
+						}
+					}
+					if bestScore > 0 {
+						s := bestScore
+						candidates[i].AffinityScore = &s
+					}
+				}
+			}
+
+			// Use resolveWithContext for 4-tier disambiguation.
+			var best *nodeInfo
+			var confidence string
+			if pm != nil {
+				best, confidence, _ = pm.resolveWithContext(hopLower, contextPubkeys, graph)
+			}
+
 			ambig := true
-			resolved[hop] = &HopResolution{
+			hr := &HopResolution{
 				Name: candidates[0].Name, Pubkey: candidates[0].Pubkey,
 				Ambiguous: &ambig, Candidates: candidates, Conflicts: hopCandidatesToConflicts(candidates),
+				Confidence: "ambiguous",
 			}
+
+			// Use the resolved node as the default (best-effort pick).
+			if best != nil {
+				hr.Name = best.Name
+				hr.Pubkey = best.PublicKey
+			}
+
+			// Only promote to bestCandidate when affinity is confident.
+			if confidence == "neighbor_affinity" && best != nil {
+				pk := best.PublicKey
+				hr.BestCandidate = &pk
+				hr.Confidence = "neighbor_affinity"
+			} else if (confidence == "geo_proximity" || confidence == "gps_preference" || confidence == "first_match") && best != nil {
+				// Propagate lower-priority tiers so the API reflects the actual
+				// resolution strategy used, rather than collapsing everything to "ambiguous".
+				hr.Confidence = confidence
+			}
+
+			resolved[hop] = hr
 		}
 	}
 	writeJSON(w, ResolveHopsResponse{Resolved: resolved})
@@ -1333,8 +1639,12 @@ func (s *Server) handleObservers(w http.ResponseWriter, r *http.Request) {
 	oneHourAgo := time.Now().Add(-1 * time.Hour).Unix()
 	pktCounts := s.db.GetObserverPacketCounts(oneHourAgo)
 
-	// Batch lookup: node locations (observer ID may match a node public_key)
-	nodeLocations := s.db.GetNodeLocations()
+	// Batch lookup: node locations only for observer IDs (not all nodes)
+	observerIDs := make([]string, len(observers))
+	for i, o := range observers {
+		observerIDs[i] = o.ID
+	}
+	nodeLocations := s.db.GetNodeLocationsByKeys(observerIDs)
 
 	result := make([]ObserverResp, 0, len(observers))
 	for _, o := range observers {
@@ -1745,13 +2055,7 @@ func percentile(sorted []float64, p float64) float64 {
 func sortedCopy(arr []float64) []float64 {
 	cp := make([]float64, len(arr))
 	copy(cp, arr)
-	for i := 0; i < len(cp); i++ {
-		for j := i + 1; j < len(cp); j++ {
-			if cp[j] < cp[i] {
-				cp[i], cp[j] = cp[j], cp[i]
-			}
-		}
-	}
+	sort.Float64s(cp)
 	return cp
 }
 
@@ -1790,6 +2094,9 @@ func mapSliceToTransmissions(maps []map[string]interface{}) []TransmissionResp {
 		tx.PathJSON = m["path_json"]
 		tx.Direction = m["direction"]
 		tx.Score = m["score"]
+		if rp, ok := m["resolved_path"].([]*string); ok {
+			tx.ResolvedPath = rp
+		}
 		result = append(result, tx)
 	}
 	return result
@@ -1811,6 +2118,9 @@ func mapSliceToObservations(maps []map[string]interface{}) []ObservationResp {
 		obs.RSSI = m["rssi"]
 		obs.PathJSON = m["path_json"]
 		obs.Timestamp = m["timestamp"]
+		if rp, ok := m["resolved_path"].([]*string); ok {
+			obs.ResolvedPath = rp
+		}
 		result = append(result, obs)
 	}
 	return result
@@ -1842,3 +2152,24 @@ func nullFloatVal(n sql.NullFloat64) float64 {
 	}
 	return 0
 }
+
+func (s *Server) handleAdminPrune(w http.ResponseWriter, r *http.Request) {
+	days := 0
+	if d := r.URL.Query().Get("days"); d != "" {
+		fmt.Sscanf(d, "%d", &days)
+	}
+	if days <= 0 && s.cfg.Retention != nil {
+		days = s.cfg.Retention.PacketDays
+	}
+	if days <= 0 {
+		writeError(w, 400, "days parameter required (or set retention.packetDays in config)")
+		return
+	}
+	n, err := s.db.PruneOldPackets(days)
+	if err != nil {
+		writeError(w, 500, err.Error())
+		return
+	}
+	log.Printf("[prune] deleted %d transmissions older than %d days", n, days)
+	writeJSON(w, map[string]interface{}{"deleted": n, "days": days})
+}

cmd/server/types.go

@@ -240,6 +240,7 @@ type TransmissionResp struct {
 	SNR              interface{}      `json:"snr"`
 	RSSI             interface{}      `json:"rssi"`
 	PathJSON         interface{}      `json:"path_json"`
+	ResolvedPath     []*string        `json:"resolved_path,omitempty"`
 	Direction        interface{}      `json:"direction"`
 	Score            interface{}      `json:"score,omitempty"`
 	Observations     []ObservationResp `json:"observations,omitempty"`
@@ -254,6 +255,7 @@ type ObservationResp struct {
 	SNR            interface{} `json:"snr"`
 	RSSI           interface{} `json:"rssi"`
 	PathJSON       interface{} `json:"path_json"`
+	ResolvedPath   []*string   `json:"resolved_path,omitempty"`
 	Timestamp      interface{} `json:"timestamp"`
 }
 
@@ -289,7 +291,7 @@ type PacketTimestampsResponse struct {
 type PacketDetailResponse struct {
 	Packet           interface{}       `json:"packet"`
 	Path             []interface{}     `json:"path"`
-	Breakdown        interface{}       `json:"breakdown"`
+	Breakdown        *Breakdown        `json:"breakdown"`
 	ObservationCount int               `json:"observation_count"`
 	Observations     []ObservationResp `json:"observations,omitempty"`
 }
@@ -873,18 +875,21 @@ type TraceResponse struct {
 // ─── Resolve Hops ──────────────────────────────────────────────────────────────
 
 type HopCandidate struct {
-	Name   interface{} `json:"name"`
-	Pubkey string      `json:"pubkey"`
-	Lat    interface{} `json:"lat"`
-	Lon    interface{} `json:"lon"`
+	Name          interface{} `json:"name"`
+	Pubkey        string      `json:"pubkey"`
+	Lat           interface{} `json:"lat"`
+	Lon           interface{} `json:"lon"`
+	AffinityScore *float64    `json:"affinityScore"`
 }
 
 type HopResolution struct {
-	Name       interface{}    `json:"name"`
-	Pubkey     interface{}    `json:"pubkey,omitempty"`
-	Ambiguous  *bool          `json:"ambiguous,omitempty"`
-	Candidates []HopCandidate `json:"candidates"`
-	Conflicts  []interface{}  `json:"conflicts"`
+	Name          interface{}    `json:"name"`
+	Pubkey        interface{}    `json:"pubkey,omitempty"`
+	Ambiguous     *bool          `json:"ambiguous,omitempty"`
+	Candidates    []HopCandidate `json:"candidates"`
+	Conflicts     []interface{}  `json:"conflicts"`
+	BestCandidate *string        `json:"bestCandidate,omitempty"`
+	Confidence    string         `json:"confidence,omitempty"`
 }
 
 type ResolveHopsResponse struct {
@@ -921,6 +926,7 @@ type ClientConfigResponse struct {
 	ExternalUrls       interface{} `json:"externalUrls"`
 	PropagationBufferMs float64         `json:"propagationBufferMs"`
 	Timestamps          TimestampConfig `json:"timestamps"`
+	DebugAffinity       bool            `json:"debugAffinity,omitempty"`
 }
 
 // ─── IATA Coords ───────────────────────────────────────────────────────────────

cmd/server/websocket.go

@@ -25,8 +25,9 @@ type Hub struct {
 
 // Client is a single WebSocket connection.
 type Client struct {
-	conn *websocket.Conn
-	send chan []byte
+	conn     *websocket.Conn
+	send     chan []byte
+	closeOnce sync.Once
 }
 
 func NewHub() *Hub {
@@ -52,12 +53,28 @@ func (h *Hub) Unregister(c *Client) {
 	h.mu.Lock()
 	if _, ok := h.clients[c]; ok {
 		delete(h.clients, c)
-		close(c.send)
+		c.closeOnce.Do(func() { close(c.send) })
 	}
 	h.mu.Unlock()
 	log.Printf("[ws] client disconnected (%d total)", h.ClientCount())
 }
 
+// Close gracefully disconnects all WebSocket clients.
+func (h *Hub) Close() {
+	h.mu.Lock()
+	for c := range h.clients {
+		c.conn.WriteControl(
+			websocket.CloseMessage,
+			websocket.FormatCloseMessage(websocket.CloseGoingAway, "server shutting down"),
+			time.Now().Add(3*time.Second),
+		)
+		c.closeOnce.Do(func() { close(c.send) })
+		delete(h.clients, c)
+	}
+	h.mu.Unlock()
+	log.Println("[ws] all clients disconnected")
+}
+
 // Broadcast sends a message to all connected clients.
 func (h *Hub) Broadcast(msg interface{}) {
 	data, err := json.Marshal(msg)
@@ -166,6 +183,17 @@ func NewPoller(db *DB, hub *Hub, interval time.Duration) *Poller {
 func (p *Poller) Start() {
 	lastID := p.db.GetMaxTransmissionID()
 	lastObsID := p.db.GetMaxObservationID()
+	// If the store already loaded data, use its max IDs as a floor.
+	// This prevents replaying the entire DB when the DB query fails
+	// (e.g., corrupted DB returns 0 from COALESCE).
+	if p.store != nil {
+		if storeMax := p.store.MaxTransmissionID(); storeMax > lastID {
+			lastID = storeMax
+		}
+		if storeMaxObs := p.store.MaxObservationID(); storeMaxObs > lastObsID {
+			lastObsID = storeMaxObs
+		}
+	}
 	log.Printf("[poller] starting from transmission ID %d, obs ID %d, interval %v", lastID, lastObsID, p.interval)
 
 	ticker := time.NewTicker(p.interval)

config.example.json

@@ -3,7 +3,8 @@
   "apiKey": "your-secret-api-key-here",
   "retention": {
     "nodeDays": 7,
-    "_comment": "Nodes not seen in this many days are moved to inactive_nodes table. Default 7."
+    "packetDays": 30,
+    "_comment": "nodeDays: nodes not seen in N days are moved to inactive_nodes (default 7). packetDays: transmissions+observations older than N days are deleted daily (0 = disabled)."
   },
   "https": {
     "cert": "/path/to/cert.pem",

deploy-live.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+set -e
+
+DEPLOY_DIR="$(cd "$(dirname "$0")" && pwd)"
+MATOMO_COMMIT="38c30f9"
+
+cd "$DEPLOY_DIR"
+
+echo "[deploy] Fetching latest from origin..."
+git fetch origin
+
+echo "[deploy] Resetting to origin/master..."
+git reset --hard origin/master
+
+echo "[deploy] Building Docker image..."
+docker build -t meshcore-analyzer .
+
+echo "[deploy] Stopping old container (30s grace period)..."
+docker stop -t 30 meshcore-analyzer && docker rm meshcore-analyzer
+docker run -d --name meshcore-analyzer \
+  --restart unless-stopped \
+  -p 3000:3000 \
+  -v "$(pwd)/config.json:/app/config.json:ro" \
+  -v meshcore-data:/app/data \
+  meshcore-analyzer
+
+echo "[deploy] Done. Live at https://analyzer.on8ar.eu"

deploy-staging.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+set -e
+
+DEPLOY_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+cd "$DEPLOY_DIR"
+
+echo "[staging] Fetching latest from origin..."
+git fetch origin
+
+BRANCH="${1:-master}"
+echo "[staging] Checking out $BRANCH..."
+git reset --hard "origin/$BRANCH"
+
+echo "[staging] Building Docker image..."
+docker build -t meshcore-analyzer-staging .
+
+echo "[staging] Stopping old container (30s grace period)..."
+docker stop -t 30 meshcore-staging 2>/dev/null || true
+docker rm meshcore-staging 2>/dev/null || true
+
+echo "[staging] Starting new container..."
+docker run -d --name meshcore-staging \
+  --restart unless-stopped \
+  -p 3001:3000 \
+  -v "$(pwd)/config.json:/app/config.json:ro" \
+  -v meshcore-staging-data:/app/data \
+  meshcore-analyzer-staging
+
+echo "[staging] Done. Live at https://staging.on8ar.eu"

docker-compose.no-mosquitto.yml

@@ -9,6 +9,8 @@ services:
     image: corescope:latest
     container_name: corescope-prod
     restart: unless-stopped
+    stop_grace_period: 30s
+    stop_signal: SIGTERM
     extra_hosts:
       - "host.docker.internal:host-gateway"
     ports:

docker-compose.staging.no-mosquitto.yml

@@ -10,6 +10,8 @@ services:
     image: corescope-go:latest
     container_name: corescope-staging-go
     restart: unless-stopped
+    stop_grace_period: 30s
+    stop_signal: SIGTERM
     deploy:
       resources:
         limits:

docker-compose.staging.yml

@@ -13,6 +13,8 @@ services:
     image: corescope-go:latest
     container_name: corescope-staging-go
     restart: unless-stopped
+    stop_grace_period: 30s
+    stop_signal: SIGTERM
     deploy:
       resources:
         limits:

docker-compose.yml

@@ -14,6 +14,8 @@ services:
     image: corescope:latest
     container_name: corescope-prod
     restart: unless-stopped
+    stop_grace_period: 30s
+    stop_signal: SIGTERM
     extra_hosts:
       - "host.docker.internal:host-gateway"
     ports:

docker/supervisord-go-no-mosquitto.conf

@@ -12,6 +12,8 @@ autostart=true
 autorestart=true
 startretries=10
 startsecs=2
+stopsignal=TERM
+stopwaitsecs=20
 stdout_logfile=/dev/stdout
 stdout_logfile_maxbytes=0
 stderr_logfile=/dev/stderr
@@ -24,6 +26,8 @@ autostart=true
 autorestart=true
 startretries=10
 startsecs=2
+stopsignal=TERM
+stopwaitsecs=20
 stdout_logfile=/dev/stdout
 stdout_logfile_maxbytes=0
 stderr_logfile=/dev/stderr

docker/supervisord-go.conf

@@ -21,6 +21,8 @@ autostart=true
 autorestart=true
 startretries=10
 startsecs=2
+stopsignal=TERM
+stopwaitsecs=20
 stdout_logfile=/dev/stdout
 stdout_logfile_maxbytes=0
 stderr_logfile=/dev/stderr
@@ -33,6 +35,8 @@ autostart=true
 autorestart=true
 startretries=10
 startsecs=2
+stopsignal=TERM
+stopwaitsecs=20
 stdout_logfile=/dev/stdout
 stdout_logfile_maxbytes=0
 stderr_logfile=/dev/stderr

docs/RELEASE-NOTES-v3.4.md

@@ -0,0 +1,47 @@
+# CoreScope v3.4 Release Notes
+
+**The neighbor affinity release.** CoreScope now understands how nodes relate to each other — not just that they exist, but how strongly they're connected. This powers smarter hop resolution, richer node detail pages, and a new graph visualization in analytics.
+
+---
+
+## 🎯 Features
+
+### Neighbor Affinity System (7 milestones)
+A complete neighbor relationship engine, from backend graph building to frontend visualization:
+
+- **Affinity graph builder** — computes neighbor relationships and connection strength from packet traffic (#507)
+- **Affinity API endpoints** — REST endpoints to query neighbor data (#508)
+- **Show Neighbors via affinity API** — the existing Show Neighbors feature now uses real affinity data instead of raw packet heuristics (#512, fixes #484)
+- **Affinity-aware hop resolution** — hop resolver uses neighbor affinity to pick better paths (#511)
+- **Node detail neighbors section** — dedicated neighbors panel on the node detail page (#510)
+- **Affinity debugging tools** — inspect and troubleshoot affinity calculations (#521)
+- **Neighbor graph visualization** — interactive neighbor graph in the analytics tab (#513)
+
+### Customizer v2
+- Event-driven state management replaces the old imperative approach — cleaner, more predictable theme/config updates (#503)
+
+---
+
+## 🐛 Bug Fixes
+
+- **Stale parsed cache on observation packets** — observation packets now correctly invalidate the JSON parse cache (#505)
+- **Null-guard rAF callbacks** — live page no longer crashes when `requestAnimationFrame` callbacks fire after cleanup (#506)
+- **Customizer v2 phantom overrides** — fixed phantom config entries, missing defaults, and stale dark mode state (#520)
+- **Neighbor affinity empty results** — fixed pubKey field name mismatch causing empty affinity graphs (#524)
+- **Home defaults in server theme** — server-side theme config now includes home page defaults (#526)
+- **Neighbor UI crash + dark mode** — fixed Show Neighbors crash and improved dark mode contrast (#527)
+- **Home page steps + FAQ** — both steps AND FAQ now render correctly on the home page (#529)
+
+---
+
+## ⚡ Performance
+
+- **Cached JSON.parse for packet data** — packet payloads are parsed once and cached, avoiding redundant `JSON.parse` calls on repeated access (#400)
+
+---
+
+## Known Limitations
+
+- **Affinity graph scales with traffic volume** — networks with very low packet rates may show weak or missing neighbor relationships until enough data accumulates
+- **Debugging tools are developer-facing** — the affinity debug panel (#521) is functional but not polished for end-user consumption
+- **Customizer v2 migration** — custom themes saved under v1 may need to be re-applied after upgrade

docs/proposals/ecb-frequency-analysis.md

@@ -0,0 +1,403 @@
+# Security Analysis: MeshCore Channel Encryption
+
+## Scope
+
+This analysis covers MeshCore's encryption vulnerabilities in order of practical severity. Section 1 addresses PSK brute-force (the highest-priority practical threat). Sections 2–9 cover AES-128-ECB structural weaknesses. Section 8 covers TXT_MSG. All claims are derived from firmware source (`BaseChatMesh.cpp`, `Utils.cpp`, `Mesh.cpp`, `MeshCore.h`) unless explicitly marked as conjecture.
+
+## 1. PSK Brute-Force with Timestamp Oracle
+
+### 1.1 The No-KDF Design
+
+MeshCore channel PSKs are base64-decoded directly into AES-128 keys with no key derivation function (from `BaseChatMesh::addChannel()`):
+
+```cpp
+int len = decode_base64((unsigned char *) psk_base64, strlen(psk_base64), dest->channel.secret);
+```
+
+No PBKDF2, scrypt, argon2, or HKDF is applied. The base64-decoded bytes ARE the AES key. This means:
+
+1. **Human-memorable passphrases have drastically reduced entropy.** If a user types "SecretChannel" as their PSK, the base64-decoded output is ~10 bytes of ASCII-range values. The key space is determined by the passphrase complexity, not by AES-128's theoretical 2^128 key space.
+
+2. **Short passphrases produce short keys.** `decode_base64` maps every 4 base64 characters to 3 bytes. A passphrase shorter than ~22 base64 characters produces fewer than 16 bytes, and the remainder of the 16-byte key buffer depends on whatever was previously in memory (likely zeros from initialization). An 8-character passphrase decodes to only 6 bytes — the effective key space may be as low as 2^48.
+
+3. **No salt.** Identical passphrases on different meshes produce identical keys. A single precomputed dictionary attack works globally against all MeshCore deployments.
+
+### 1.2 Timestamp as Known-Plaintext Oracle
+
+Every GRP_TXT plaintext begins with a structured, largely predictable header:
+
+```
+Block 0: [TS₀][TS₁][TS₂][TS₃][0x00][sender_name][: ][message_start...]
+```
+
+An attacker who captures a single packet can verify a candidate PSK by:
+1. Decrypting block 0 with the candidate key
+2. Checking if bytes 0–3 produce a plausible Unix timestamp (within a reasonable window of the capture time)
+3. Checking if byte 4 is 0x00 (TXT_TYPE_PLAIN)
+4. Optionally checking if bytes 5+ are valid ASCII (sender name)
+
+The timestamp alone constrains the search: a ±1-hour window around capture time yields ~7,200 valid timestamps out of 2^32 possibilities — a false-positive rate of ~1.7×10^-6. Combined with the type byte and ASCII sender-name check, false positives are effectively zero. **One captured packet is sufficient for definitive key verification.**
+
+### 1.3 Attack Cost Estimates
+
+Hardware assumption: commodity GPU (e.g., RTX 4090) performing ~10 billion AES-128-ECB block encryptions per second. This is conservative — optimized implementations achieve higher throughput.
+
+| Passphrase style | Search space | Time at 10^10 AES/sec |
+|---|---|---|
+| Single common English word (10K-word list) | ~10^4 | microseconds |
+| Single English word (170K full dictionary) | ~1.7×10^5 | microseconds |
+| Two concatenated common words | ~10^8 | ~10 milliseconds |
+| Three concatenated common words | ~10^12 | ~100 seconds (~2 min) |
+| Four random common words (Diceware-style) | ~10^16 | ~10^6 seconds (~12 days) |
+| Random 8-char alphanumeric (62^8) | ~2.2×10^14 | ~22,000 seconds (~6 hours) |
+| Random 12-char alphanumeric (62^12) | ~3.2×10^21 | ~10^11 seconds (infeasible) |
+| Full random 16-byte key (2^128) | ~3.4×10^38 | infeasible |
+
+**Important caveats on search space:**
+- Dictionary sizes vary: "common English words" ≈ 3K–10K; full dictionary ≈ 170K. Estimates above use 10K for "common" lists.
+- Humans do not choose words uniformly. Zipf's law applies — a small fraction of words account for most selections. The effective entropy is **lower** than the uniform assumption, making attacks faster.
+- Concatenation without separators creates ambiguity ("therapist" = "therapist" or "the"+"rapist"), but this marginally reduces search space rather than increasing it.
+- Multi-channel amortization: an attacker can test each candidate against ALL captured channels simultaneously, paying the AES cost once per candidate.
+
+### 1.4 Attack Properties
+
+- **Offline attack.** No rate limiting, no lockout, no detection. The attacker works entirely on captured ciphertext.
+- **Single-packet verification.** One GRP_TXT packet is sufficient. No need to collect multiple messages.
+- **No KDF stretching.** Each candidate requires exactly one AES-128 block decryption (16 bytes), not thousands of hash iterations.
+- **Global applicability.** No salt means precomputed tables work across all MeshCore deployments using the same passphrase.
+- **Side-channel exposure.** Since the PSK IS the key (no KDF), any AES key-schedule side-channel directly reveals the passphrase. PSK reuse across systems (e.g., same passphrase for MeshCore and WiFi) means compromise of one compromises both.
+
+### 1.5 Severity Assessment
+
+**PSK brute-force is the #1 practical threat to MeshCore channel confidentiality.** Unlike ECB frequency analysis (§5), which requires hundreds of captured messages with repeated content, PSK brute-force requires a single captured packet and succeeds whenever users choose human-memorable passphrases — which is the common case for manually-configured channels.
+
+Any channel using a passphrase of 3 or fewer common words, or any alphanumeric string shorter than 12 characters, should be considered **vulnerable to offline brute-force within hours to days** using commodity hardware.
+
+### 1.6 Recommended Mitigations
+
+**Priority 0 (Critical):** Apply a memory-hard KDF (argon2id preferred; scrypt or PBKDF2 with ≥100K iterations as fallback) to derive the AES key from the passphrase. This transforms each candidate test from ~1 nanosecond to ~100 milliseconds, increasing attack cost by a factor of ~10^8.
+
+**Priority 0a:** Add a per-channel salt (random bytes stored alongside the channel config) to prevent precomputed/global attacks.
+
+**Priority 0b:** Document that channel PSKs should be random 16-byte keys (e.g., generated with `openssl rand -base64 22`), not human-memorable passphrases. This is a stopgap until KDF support is added.
+
+## 2. How Encryption Works
+
+### Constants (from `MeshCore.h`)
+- `CIPHER_KEY_SIZE = 16` (AES-128)
+- `PUB_KEY_SIZE = 32`
+- `CIPHER_MAC_SIZE` = HMAC-SHA256 truncated output size
+
+### encrypt() (from `Utils.cpp`)
+AES-128-ECB, block-by-block. No IV, no counter, no chaining:
+```cpp
+aes.setKey(shared_secret, CIPHER_KEY_SIZE);  // first 16 bytes of shared_secret
+while (src_len >= 16) {
+    aes.encryptBlock(dp, src);  // each 16-byte block independently
+    dp += 16; src += 16; src_len -= 16;
+}
+if (src_len > 0) {  // partial final block
+    uint8_t tmp[16];
+    memset(tmp, 0, 16);   // zero-fill
+    memcpy(tmp, src, src_len);  // copy remaining bytes
+    aes.encryptBlock(dp, tmp);
+}
+```
+
+### encryptThenMAC() (from `Utils.cpp`)
+```cpp
+int enc_len = encrypt(shared_secret, dest + CIPHER_MAC_SIZE, src, src_len);
+SHA256 sha;
+sha.resetHMAC(shared_secret, PUB_KEY_SIZE);   // HMAC uses full 32 bytes
+sha.update(dest + CIPHER_MAC_SIZE, enc_len);
+sha.finalizeHMAC(shared_secret, PUB_KEY_SIZE, dest, CIPHER_MAC_SIZE);
+```
+
+**Key reuse flaw:** The same `shared_secret` buffer serves both AES and HMAC. AES uses `shared_secret[0..15]` (first 16 bytes). HMAC uses `shared_secret[0..31]` (full 32 bytes). The AES key is a prefix of the HMAC key. See §7 for implications.
+
+### GRP_TXT Plaintext Construction (from `BaseChatMesh::sendGroupMessage()`)
+
+```cpp
+memcpy(temp, &timestamp, 4);          // bytes 0-3: Unix timestamp (seconds)
+temp[4] = 0;                           // byte 4: TXT_TYPE_PLAIN
+sprintf((char *)&temp[5], "%s: ", sender_name);  // bytes 5+: "SenderName: "
+char *ep = strchr((char *)&temp[5], 0);
+int prefix_len = ep - (char *)&temp[5];           // length of "SenderName: "
+memcpy(ep, text, text_len);            // message text (no null terminator)
+ep[text_len] = 0;                      // null written AFTER data boundary
+// data_len passed to encrypt = 5 + prefix_len + text_len
+```
+
+**The null terminator is NOT part of the encrypted data length.** The call to `createGroupDatagram` passes length `5 + prefix_len + text_len`. The null at `ep[text_len]` is written to the buffer but is beyond `data_len`. In the final partial block, `encrypt()` zero-fills with `memset(tmp, 0, 16)` before copying the remaining bytes — so a zero byte appears at the position where the null would be, but this is an artifact of zero-padding, not an explicit null in the plaintext.
+
+On the receiving side, this is confirmed:
+```cpp
+data[len] = 0; // need to make a C string again, with null terminator
+```
+The receiver must re-add the null after decryption.
+
+## 3. Block Layout Analysis
+
+### Notation
+
+Let `N` = length of sender name. Then:
+- `prefix_len` = N + 2 (for ": " suffix from `sprintf("%s: ", sender_name)`)
+- Header overhead = 4 (timestamp) + 1 (type) + prefix_len = N + 7 bytes
+- Message text begins at byte offset N + 7
+
+### Block 0
+
+Block 0 = bytes 0–15 of plaintext:
+```
+[TS₀][TS₁][TS₂][TS₃][0x00][sender_name: ][...message start...]
+```
+
+The first 9 − N bytes of message text fit in block 0 (when N < 9). For N ≥ 9, no message text fits in block 0.
+
+### Boundary Condition: Sender Name ≥ 12 Characters
+
+When N ≥ 12, the header overhead (N + 7 ≥ 19) exceeds 16 bytes. The header itself spills into block 1:
+
+**Example: sender name "LongUserName1" (N = 13), message "hi":**
+```
+Header = 13 + 7 = 20 bytes. Total plaintext = 20 + 2 = 22 bytes.
+
+Block 0 (bytes 0-15):  [TS₀][TS₁][TS₂][TS₃][0x00][L][o][n][g][U][s][e][r][N][a][m]
+Block 1 (bytes 16-31): [e][1][:][space][h][i][0x00 ×10]  ← zero-padded partial block
+```
+
+Block 1 here contains the tail of the sender name, the ": " separator, message text, AND zero-padding. For sender names of length 12–15, block 1 is a mix of header and message — **it is NOT "pure message text."**
+
+For sender names ≥ 16, blocks 0 and 1 are both pure header, and message text doesn't begin until block 1 or later.
+
+### General Block Content Table
+
+| Sender name length N | Header bytes | Message starts at byte | Block 0 content | Block 1+ content |
+|---|---|---|---|---|
+| 1–8 | 8–15 | 8–15 | timestamp + header + message start | message text + zero-pad |
+| 9–11 | 16–18 | 16–18 | timestamp + header (no message) | header tail + message + zero-pad |
+| 12–15 | 19–22 | 19–22 | timestamp + partial header | header tail + message + zero-pad |
+| ≥16 | ≥23 | ≥23 | timestamp + partial header | header continuation, then message |
+
+### Typical Case (N = 5, e.g. "Alice")
+
+Header = 12 bytes. Message starts at byte 12. Block 0 holds 4 bytes of message text.
+
+```
+Message "hello world" (11 chars). Total plaintext = 12 + 11 = 23 bytes.
+
+Block 0 (bytes 0-15):  [TS₀][TS₁][TS₂][TS₃][0x00][A][l][i][c][e][:][space][h][e][l][l]
+Block 1 (bytes 16-22): [o][space][w][o][r][l][d] → padded to: [o][space][w][o][r][l][d][0×9]
+```
+
+Block 1 contains 7 bytes of message text and 9 bytes of zero-padding.
+
+## 4. Attack Surface by Block Position
+
+### Block 0: Accidental Nonce from Timestamp
+
+The 4-byte Unix timestamp in bytes 0–3 acts as an **accidental nonce** — it was included "mostly as an extra blob to help make packet_hash unique" (per firmware comment), not as a cryptographic countermeasure against ECB determinism. Nevertheless, it has the effect of making block 0's plaintext vary per message.
+
+**Precision on uniqueness:** Block 0 is unique per (sender, timestamp-second) pair, not per message. Two messages from the same sender within the same second, on the same channel, with the same type byte, produce identical block 0 plaintext and therefore identical block 0 ciphertext. At typical mesh chat rates, same-second collisions are rare but not impossible for automated/scripted senders.
+
+**Known-plaintext observation:** Bytes 4–15 of block 0 are largely predictable per sender (type byte is always 0x00 for plain text; sender name and ": " are static). The timestamp is predictable within a window (Unix seconds). An attacker who knows the sender name and approximate time can compute all 16 plaintext bytes of block 0. However, **AES-128 is resistant to known-plaintext attacks** — knowing plaintext-ciphertext pairs for block 0 does not help recover the key or decrypt other blocks.
+
+### Blocks 1+: Deterministic ECB (for short sender names)
+
+When the sender name is short enough that the header fits in block 0 (N ≤ 8), blocks 1+ contain **only message text and zero-padding.** No timestamp, no nonce, no per-message varying data. Identical message text at the same block offset produces identical ciphertext, always.
+
+When N ≥ 9, block 1 contains header spillover, which includes static sender name bytes — these vary per sender but not per message, so block 1 is still deterministic for a given sender once the header portion is fixed.
+
+**The fundamental ECB property:** For any block beyond the timestamp's reach, `E_K(P) = E_K(P)`. Same plaintext block → same ciphertext block, regardless of when or how many times it's sent.
+
+### Partial Final Block: Strongest Attack Target
+
+The final block of every message is zero-padded by `encrypt()` to 16 bytes. The padding bytes are deterministic and known (always 0x00). For a message whose final block contains `B` bytes of actual content:
+
+- `B` bytes are unknown message text
+- `16 - B` bytes are known zeros
+
+When B is small (short final fragment), most of the block is known plaintext. For B = 1, the attacker knows 15 of 16 bytes — only 256 possible plaintext blocks exist. This means:
+
+- **The final block has at most 2^(8B) possible plaintexts** (versus 2^128 for a full unknown block)
+- For B ≤ 4, there are ≤ 2^32 possibilities — a small enough space for dictionary attacks given enough ciphertext samples
+- The attacker can precompute all possible final-block plaintexts for small B values and match against observed ciphertext blocks
+
+This makes the partial final block a **stronger frequency analysis target** than interior blocks, where all 16 bytes may be unknown text.
+
+## 5. Feasible Attack Scenarios
+
+### 4.1 Block Frequency Analysis on Blocks 1+
+
+**Preconditions (all must hold):**
+1. Attacker can observe encrypted GRP_TXT packets (passive radio capture)
+2. Messages from the same sender (or senders with identical name lengths — same block alignment)
+3. Messages long enough to produce blocks beyond block 0 (text > 9 − N chars)
+4. Sufficient message volume with repeated content at the same block positions
+
+**Method:**
+1. Collect GRP_TXT packets, group by sender hash
+2. Decompose encrypted payloads into 16-byte blocks (after stripping HMAC prefix)
+3. Discard block 0 (timestamp-varying)
+4. Build frequency tables for blocks 1, 2, 3, etc., per sender
+5. Match high-frequency ciphertext blocks against expected plaintext distributions
+
+**Practical constraints limiting this attack:**
+- LoRa bandwidth severely limits message length. Most mesh chat messages are short — many fit entirely within block 0 (≤ 9 − N chars of text), yielding zero analyzable blocks.
+- Messages that spill into block 1+ tend to be longer and more varied — fewer repeated patterns.
+- The attack requires repeated identical 16-byte-aligned text fragments from the same sender over time.
+
+**Conditions under which this attack succeeds:** Automated or scripted senders transmitting repetitive messages longer than block 0 capacity, on a channel with a static PSK, over an extended collection period. For human-typed conversational messages with typical length and variety, the number of repeated block 1+ patterns is likely too low for meaningful frequency analysis. (This is an empirical claim that depends on actual traffic patterns — no formal bound is established here.)
+
+### 4.2 Partial Final Block Dictionary Attack
+
+**Preconditions:**
+1. Attacker knows (or can estimate) the message length modulo 16
+2. Final block has few content bytes (B ≤ 4)
+
+**Method:** Enumerate all 2^(8B) candidate plaintexts for the final block. Since AES-ECB is deterministic with a fixed key, the attacker can build a lookup table: if they ever observe a ciphertext block matching one of the candidates in a known-plaintext scenario (e.g., from a leaked or guessed message), they can identify which final-block value corresponds to which ciphertext.
+
+**Limitation:** Without the key, the attacker cannot compute E_K(candidate) directly. The attack requires collecting enough ciphertext final blocks to perform frequency analysis within the reduced plaintext space. With only 256 possibilities (B=1), convergence is fast given sufficient samples.
+
+### 4.3 Cross-Sender Correlation
+
+Senders with identical name lengths produce identical block alignments. Messages from "Alice" (N=5) and "Bobby" (N=5) place message text at the same byte offsets. If both send the same message, their blocks 1+ are identical ciphertext — **but only if they share the same channel PSK** (same AES key). On the same channel, this enables cross-sender frequency analysis within same-name-length groups.
+
+### 4.4 Message Length Leakage
+
+Ciphertext length = ⌈(5 + prefix_len + text_len) / 16⌉ × 16 bytes. This reveals the message text length within a 16-byte window (not 15, because the block count is the observable quantity). Not ECB-specific — any block cipher without constant-length padding leaks this.
+
+### 4.5 Replay Attacks
+
+`encryptThenMAC()` authenticates the ciphertext, but if the mesh doesn't track previously-seen packet MACs, captured packets can be replayed. The embedded timestamp may be checked for staleness — this requires firmware verification beyond the scope of this analysis.
+
+### 4.6 No Forward Secrecy
+
+Channel PSKs are static and shared among all participants. ECDH shared secrets for direct messages are also static (no ephemeral key exchange). Compromise of any key decrypts all past and future traffic encrypted under that key.
+
+## 6. What Known-Plaintext Does NOT Achieve
+
+AES-128 is designed to resist known-plaintext attacks. An attacker who knows the full plaintext and ciphertext of block 0 (or any block) **cannot**:
+- Recover the AES key
+- Decrypt other blocks encrypted under the same key
+- Derive any information about other plaintexts from their ciphertexts
+
+The ECB weakness is **determinism** (identical plaintext → identical ciphertext), not key recovery. The attacks in §5 exploit pattern matching and frequency analysis, not cryptanalysis of AES itself.
+
+## 7. HMAC Key Reuse: Cryptographic Design Flaw
+
+From `encryptThenMAC()`:
+- AES key: `shared_secret[0..15]` (CIPHER_KEY_SIZE = 16)
+- HMAC key: `shared_secret[0..31]` (PUB_KEY_SIZE = 32)
+
+The AES key is the first half of the HMAC key. Both are derived from the same `shared_secret` — for channels, this is the PSK; for direct messages, the ECDH shared secret.
+
+**Why this matters:**
+1. **Violated key separation principle.** Standard practice dictates that encryption and authentication keys must be independent. Using overlapping portions of the same secret means a weakness in one mechanism could leak information relevant to the other.
+2. **HMAC key reveals AES key.** If an attacker recovers the 32-byte HMAC key (e.g., through a side-channel attack on the HMAC computation), they automatically obtain the 16-byte AES key as a prefix.
+3. **No key derivation function.** The shared_secret is used directly — no HKDF or similar KDF is applied to derive independent subkeys. This is a departure from cryptographic best practice (cf. RFC 5869).
+
+**Practical impact:** In the current threat model (passive radio capture of LoRa packets), this is unlikely to be directly exploitable — HMAC-SHA256 does not leak its key through normal operation. However, it represents a structural weakness that compounds with any future vulnerability in either the AES or HMAC implementation.
+
+## 8. TXT_MSG (Direct Message) Block Layout
+
+Direct messages use a different plaintext structure (from `BaseChatMesh::composeMsgPacket()`):
+
+```cpp
+memcpy(temp, &timestamp, 4);          // bytes 0-3: timestamp
+temp[4] = (attempt & 3);               // byte 4: attempt counter (0-3)
+memcpy(&temp[5], text, text_len + 1);  // bytes 5+: message text
+// data_len = 5 + text_len (null terminator copied but not counted in length)
+```
+
+**Block layout for TXT_MSG:**
+```
+Block 0: [TS₀][TS₁][TS₂][TS₃][attempt][text bytes 0-10]
+Block 1: [text bytes 11-26] (if message long enough)
+```
+
+Key differences from GRP_TXT:
+- **No sender name in plaintext** — the sender is identified by the source hash in the unencrypted packet header, not in the encrypted payload.
+- **Header is exactly 5 bytes** (4 timestamp + 1 attempt), always. No variable-length field.
+- **11 bytes of message text fit in block 0** (vs. 9 − N for GRP_TXT).
+- **Encrypted with per-pair ECDH shared secret**, not a group PSK. Each sender-recipient pair has a unique key.
+
+**ECB implications for TXT_MSG:**
+- Block 0 is still protected by the timestamp accidental nonce.
+- Blocks 1+ are deterministic, same as GRP_TXT — identical message text at the same offset produces identical ciphertext.
+- However, frequency analysis is harder: each sender-recipient pair uses a different key, so the attacker can only correlate messages within a single pair. The message volume for any given pair is typically much lower than for a group channel.
+- The fixed 5-byte header means block alignment is consistent across ALL direct messages (unlike GRP_TXT where alignment varies by sender name length). An attacker who compromises one ECDH key can build block frequency tables, but only for that specific pair.
+
+## 9. Mitigations
+
+### Priority 1: Switch to AES-128-CTR
+
+Replace ECB with CTR mode. Use the existing 4-byte timestamp + a 4-byte per-message counter as the 8-byte nonce (padded to 16 bytes for the CTR block). Each byte of plaintext gets XORed with a unique keystream byte — eliminates all block-level determinism.
+
+**Wire format change:** None if the nonce is derived from header fields already present. If an explicit counter is added, 4 bytes of overhead per message.
+
+### Priority 2: Derive Independent Subkeys
+
+Apply HKDF (or at minimum, two distinct SHA-256 hashes) to the shared_secret to produce independent AES and HMAC keys. This is a minimal code change:
+```
+aes_key = SHA256(shared_secret || "encrypt")[0..15]
+hmac_key = SHA256(shared_secret || "authenticate")
+```
+
+### Priority 3: Constant-Length Padding
+
+Pad all messages to a fixed block count (e.g., 4 blocks = 64 bytes) to eliminate length leakage. Expensive on LoRa — should be configurable per channel as a security-vs-bandwidth tradeoff.
+
+### Priority 4: Replay Protection
+
+Track seen packet HMACs within a time window. Reject messages with timestamps older than N minutes.
+
+### Priority 5: Channel Key Rotation
+
+Manual or automated periodic rotation of channel PSKs. Even monthly rotation limits the exposure window.
+
+### Priority 6: Forward Secrecy
+
+Ephemeral ECDH for direct messages. Significant protocol change but prevents retroactive decryption on key compromise.
+
+## 10. Speculative: LLM-Assisted Analysis
+
+> **This section is speculation, not formal analysis.** The claims below are plausible but unvalidated. They do not affect the formal findings in §1–9.
+
+An LLM could reduce the sample size needed for block frequency analysis:
+
+1. **Context-aware candidate generation:** Given a sender's known patterns (the sender name is recoverable from block 0's predictable prefix), an LLM could generate likely message continuations and predict which plaintext blocks to look for in the frequency tables.
+2. **Conversational inference:** Timestamps + sender IDs + partially decoded messages could let an LLM reconstruct probable conversation flow, narrowing the search space for unknown blocks.
+3. **Community-specific vocabulary:** Training on public mesh chat logs could yield common phrases and greeting patterns, further reducing the candidate plaintext space.
+
+This does not change the fundamental requirement (blocks 1+ must repeat, or the final block must be in a small enough space for dictionary matching). It potentially reduces the number of captured messages needed for convergence, but no quantitative bound is established.
+
+## 11. Conclusion
+
+MeshCore's encryption has four vulnerabilities, ranked by practical exploitability:
+
+### Vulnerability #1: PSK Brute-Force (Critical)
+
+**No KDF + known-plaintext oracle = offline key recovery from a single packet.** Any channel using a human-memorable passphrase of ≤3 common words or ≤11 alphanumeric characters is recoverable in minutes to hours on commodity GPU hardware. This is the highest-priority threat because it requires minimal attacker capability (one captured packet), succeeds against the most common deployment pattern (human-chosen passphrases), and completely compromises channel confidentiality. See §1.
+
+### Vulnerability #2: ECB Determinism (Medium)
+
+**Blocks beyond the timestamp's reach are deterministic.** Identical plaintext at the same block offset always produces identical ciphertext. For GRP_TXT messages longer than ~9 − N characters (where N is sender name length), this enables frequency analysis on blocks 1+. The partial final block, with its known zero-padding, is the strongest individual target. Exploitation requires hundreds of captured messages with repeated content — a higher bar than PSK brute-force. See §4–§5.
+
+### Vulnerability #3: Key Material Reuse (Medium)
+
+**AES and HMAC share the same key material** without a key derivation function. The AES key is a prefix of the HMAC key. This violates key separation and creates a structural dependency between the encryption and authentication mechanisms. See §7.
+
+### Vulnerability #4: No Forward Secrecy (Low–Medium)
+
+**No forward secrecy, no key rotation, no replay protection.** These are independent of the above but compound the risk: a single key compromise (whether via brute-force or other means) exposes all past and future traffic encrypted under that key. See §9.
+
+**Summary of recommended mitigations (in priority order):**
+1. **(Critical)** Apply a memory-hard KDF (argon2id) to channel PSKs — §1.6
+2. **(Critical)** Add per-channel salt — §1.6
+3. **(High)** Switch from AES-128-ECB to AES-128-CTR — §9
+4. **(High)** Derive independent AES and HMAC subkeys via HKDF — §9
+5. **(Medium)** Constant-length padding, replay protection, key rotation — §9
+6. **(Low)** Forward secrecy via ephemeral ECDH — §9
+
+The timestamp in block 0 was not designed as a nonce and should not be relied upon as one.

docs/specs/customizer-rework.md

@@ -0,0 +1,568 @@
+# Customizer Rework Spec
+
+## Overview
+
+The current customizer (`public/customize.js`) suffers from fundamental state management issues documented in [issue #284](https://github.com/Kpa-clawbot/CoreScope/issues/284). State is scattered across 7 localStorage keys, CSS updates bypass the data layer, and there's no single source of truth for the effective configuration.
+
+This spec defines a clean rework based on event-driven state management with a single data flow path. The goal: predictable state, minimal storage footprint, portable config format, and zero ambiguity about which values are active and why.
+
+## Design Decisions
+
+These are agreed and final. Do not reinterpret or deviate.
+
+1. **Three state layers:** server defaults (immutable after fetch), user overrides (delta in localStorage), effective config (computed via merge, never stored directly).
+2. **Single data flow:** user action → debounce (~300ms) → write delta to localStorage → read back from localStorage → merge with server defaults → apply CSS variables. No shortcuts, no optimistic CSS updates (see Decision #12 for the one exception).
+3. **One localStorage key:** `cs-theme-overrides` — replaces the current 7 scattered keys (`meshcore-user-theme`, `meshcore-timestamp-mode`, `meshcore-timestamp-timezone`, `meshcore-timestamp-format`, `meshcore-timestamp-custom-format`, `meshcore-heatmap-opacity`, `meshcore-live-heatmap-opacity`).
+4. **Universal format:** same shape as the server's `ThemeResponse` plus additional keys. Works identically for user export, admin `theme.json`, and user import.
+5. **User overrides always win** in merge — `merge(serverDefaults, userOverrides)` = effective config.
+6. **Override indicator:** shown in customizer panel ONLY when override value differs from current server default.
+7. **No silent pruning:** overrides stay in localStorage until the user explicitly resets them (per-field reset or full reset). The delta may contain values that happen to match current server defaults — that's fine. User intent is preserved; nothing silently disappears.
+8. **Per-field reset:** remove a single key from the delta → re-merge → re-apply CSS.
+9. **Full reset:** `localStorage.removeItem('cs-theme-overrides')` → re-merge (effective = server defaults) → re-apply CSS.
+10. **Export = dump delta object as JSON download. Import = validate shape, write to localStorage, trigger re-merge.**
+11. **No CSS magic:** CSS variables ONLY update after the localStorage round-trip completes. No optimistic updates (see Decision #12 for the one exception).
+12. **Color picker optimistic CSS exception:** For continuous inputs (color pickers, sliders), CSS is updated optimistically during `input` events for visual responsiveness. The localStorage write only happens on `change` event (mouseup/blur). On `change`, the full pipeline runs: write → read → merge → apply (which will match the optimistic state). If the user refreshes mid-drag before `change` fires, the change is lost — this is acceptable. This is the ONLY exception to the localStorage-first rule.
+
+## Dark/Light Mode
+
+The customizer treats light and dark mode as separate override sections:
+
+- **`theme`** stores light mode color overrides.
+- **`themeDark`** stores dark mode color overrides.
+- When the user changes a color in the customizer, it writes to whichever section matches their current mode: `theme` if light, `themeDark` if dark.
+- The dark/light mode toggle preference (`meshcore-theme` localStorage key) is **separate** from the delta object. It is a view preference, not a customization — it is not stored in `cs-theme-overrides`.
+- The customizer UI shows color fields for the currently active mode only. Switching modes re-renders the color fields with values from the matching section.
+
+## Presets
+
+The existing preset themes are preserved and flow through the standard pipeline:
+
+**Available presets:** Default, Ocean, Forest, Sunset, Monochrome.
+
+**How presets work:**
+- Clicking a preset writes its values to localStorage via the same pipeline as any other change: preset data → `writeOverrides()` → read back → merge → apply CSS.
+- Presets are NOT special — they are pre-built delta objects applied through the standard flow.
+- Each preset contains both `theme` (light) and `themeDark` (dark) sections, plus any other overrides the preset defines (e.g., `nodeColors`).
+- **"Reset to Default"** = clear all overrides (equivalent to full reset: `localStorage.removeItem('cs-theme-overrides')` → re-merge → apply).
+
+**Preset data format:** Same shape as the delta object. Example:
+
+```json
+{
+  "theme": {
+    "accent": "#0077b6",
+    "navBg": "#03045e",
+    "background": "#f0f7fa"
+  },
+  "themeDark": {
+    "accent": "#48cae4",
+    "navBg": "#03045e",
+    "background": "#0a1929"
+  }
+}
+```
+
+Applying a preset **replaces** the entire delta (it's a `writeOverrides(presetData)`, not a merge onto existing overrides). The user can then further customize individual fields on top.
+
+## Data Model
+
+### Delta Object Format
+
+The user override delta is a sparse object — it only contains fields the user has explicitly changed. The shape mirrors the server's `ThemeResponse` (from `/api/config/theme`) plus additional client-only sections:
+
+```json
+{
+  "branding": {
+    "siteName": "string — site name override",
+    "tagline": "string — tagline override",
+    "logoUrl": "string — custom logo URL",
+    "faviconUrl": "string — custom favicon URL"
+  },
+  "theme": {
+    "accent": "string — CSS color, light mode accent",
+    "accentHover": "string — CSS color, light mode accent hover",
+    "navBg": "string — CSS color, nav background",
+    "navBg2": "string — CSS color, nav secondary background",
+    "navText": "string — CSS color, nav text",
+    "navTextMuted": "string — CSS color, nav muted text",
+    "background": "string — CSS color, page background",
+    "text": "string — CSS color, body text",
+    "textMuted": "string — CSS color, muted text",
+    "border": "string — CSS color, borders",
+    "surface1": "string — CSS color, surface level 1",
+    "surface2": "string — CSS color, surface level 2",
+    "cardBg": "string — CSS color, card backgrounds",
+    "contentBg": "string — CSS color, content area background",
+    "detailBg": "string — CSS color, detail pane background",
+    "inputBg": "string — CSS color, input backgrounds",
+    "rowStripe": "string — CSS color, alternating row stripe",
+    "rowHover": "string — CSS color, row hover highlight",
+    "selectedBg": "string — CSS color, selected row background",
+    "statusGreen": "string — CSS color, healthy status",
+    "statusYellow": "string — CSS color, degraded status",
+    "statusRed": "string — CSS color, critical status",
+    "font": "string — CSS font-family for body text",
+    "mono": "string — CSS font-family for monospace"
+  },
+  "themeDark": {
+    "/* same keys as theme — dark mode overrides */"
+  },
+  "nodeColors": {
+    "repeater": "string — CSS color",
+    "companion": "string — CSS color",
+    "room": "string — CSS color",
+    "sensor": "string — CSS color",
+    "observer": "string — CSS color"
+  },
+  "typeColors": {
+    "ADVERT": "string — CSS color",
+    "GRP_TXT": "string — CSS color",
+    "TXT_MSG": "string — CSS color",
+    "ACK": "string — CSS color",
+    "REQUEST": "string — CSS color",
+    "RESPONSE": "string — CSS color",
+    "TRACE": "string — CSS color",
+    "PATH": "string — CSS color",
+    "ANON_REQ": "string — CSS color"
+  },
+  "home": {
+    "heroTitle": "string",
+    "heroSubtitle": "string",
+    "steps": "[array of {emoji, title, description}]",
+    "checklist": "[array of strings]",
+    "footerLinks": "[array of {label, url}]"
+  },
+  "timestamps": {
+    "defaultMode": "string — 'ago' | 'absolute'",
+    "timezone": "string — 'local' | 'utc'",
+    "formatPreset": "string — 'iso' | 'iso-seconds' | 'locale'",
+    "customFormat": "string — custom strftime-style format"
+  },
+  "heatmapOpacity": "number — 0.0 to 1.0",
+  "liveHeatmapOpacity": "number — 0.0 to 1.0"
+}
+```
+
+**Rules:**
+- All sections and keys are optional. An empty object `{}` means "no overrides."
+- The `timestamps`, `heatmapOpacity`, and `liveHeatmapOpacity` keys are client-only extensions — not part of the server's `ThemeResponse`, but included in the universal format for portability.
+
+### localStorage Key
+
+**Key:** `cs-theme-overrides`
+**Value:** JSON string of the delta object above.
+**Absent key** = no overrides = effective config equals server defaults.
+
+### Dark/Light Mode Preference
+
+**Key:** `meshcore-theme`
+**Value:** `"dark"` or `"light"` (or absent = follow system preference).
+**This key is NOT part of the delta object.** It controls which mode is active, not which colors are used. The delta stores overrides for both modes independently in `theme` and `themeDark`.
+
+## Data Flow Diagrams
+
+### Page Load
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│ Fetch        │     │ Read localStorage │     │ Migration check │
+│ /api/config/ │     │ cs-theme-overrides│     │ (one-time)      │
+│ theme        │     └────────┬─────────┘     └────────┬────────┘
+└──────┬──────┘              │                         │
+       │                     │    ┌────────────────────┘
+       ▼                     ▼    ▼
+  serverDefaults      userOverrides (possibly migrated)
+       │                     │
+       ▼                     ▼
+  ┌──────────────────────────────────────┐
+  │ computeEffective(server, userOverrides) │
+  └──────────────┬───────────────────────┘
+                 │
+                 ▼
+  ┌──────────────────────────────────────┐
+  │ window.SITE_CONFIG = effective       │ ← atomic assignment
+  └──────────────┬───────────────────────┘
+                 │
+                 ▼
+  ┌──────────────────────┐
+  │ applyCSS(effective)  │ ← sets CSS vars on :root for current mode
+  └──────────────────────┘
+                 │
+                 ▼
+  ┌──────────────────────────────┐
+  │ dispatch 'theme-changed'     │ ← bare signal, no payload
+  └──────────────────────────────┘
+```
+
+### User Change (e.g., picks new accent color)
+
+```
+  User action (input/click)
+       │
+       ▼
+  debounce(300ms)
+       │
+       ▼
+  setOverride('theme', 'accent', '#ff0000')
+       │
+       ├─► readOverrides()          ← read current delta from localStorage
+       │       │
+       │       ▼
+       ├─► update delta object      ← set delta.theme.accent = '#ff0000'
+       │       │
+       │       ▼
+       ├─► writeOverrides(delta)    ← serialize & write to localStorage
+       │       │
+       │       ▼
+       ├─► readOverrides()          ← read BACK from localStorage (round-trip)
+       │       │
+       │       ▼
+       ├─► computeEffective(server, delta)
+       │       │
+       │       ▼
+       ├─► window.SITE_CONFIG = effective  ← atomic assignment
+       │       │
+       │       ▼
+       └─► applyCSS(effective)      ← CSS vars updated on :root
+              │
+              ▼
+         dispatch 'theme-changed'
+```
+
+**Color picker / slider exception:** During continuous `input` events (drag), CSS is updated optimistically (directly setting `--var` on `:root`) without the localStorage round-trip. The full pipeline above only runs on the `change` event (mouseup/blur).
+
+### Per-Field Reset
+
+```
+  User clicks reset icon on a field
+       │
+       ▼
+  clearOverride('theme', 'accent')
+       │
+       ├─► readOverrides()
+       ├─► delete delta.theme.accent
+       ├─► if delta.theme is empty, delete delta.theme
+       ├─► writeOverrides(delta)
+       ├─► readOverrides()          ← round-trip
+       ├─► computeEffective(server, delta)
+       ├─► window.SITE_CONFIG = effective
+       └─► applyCSS(effective)
+              │
+              ▼
+         dispatch 'theme-changed'
+```
+
+### Full Reset
+
+```
+  User clicks "Reset All"
+       │
+       ▼
+  localStorage.removeItem('cs-theme-overrides')
+       │
+       ▼
+  computeEffective(server, {})    ← no overrides = server defaults
+       │
+       ▼
+  window.SITE_CONFIG = effective
+       │
+       ▼
+  applyCSS(effective)
+       │
+       ▼
+  dispatch 'theme-changed'
+```
+
+### Export
+
+```
+  User clicks "Export"
+       │
+       ▼
+  readOverrides()
+       │
+       ▼
+  JSON.stringify(delta, null, 2)
+       │
+       ▼
+  trigger download as .json file
+```
+
+### Import
+
+```
+  User selects .json file
+       │
+       ▼
+  parse JSON
+       │
+       ▼
+  validateShape(parsed)           ← check structure, validate values
+       │
+       ├─► invalid → show error, abort
+       │
+       ▼ valid
+  writeOverrides(parsed)
+       │
+       ▼
+  readOverrides()                 ← round-trip
+       │
+       ▼
+  computeEffective(server, delta)
+       │
+       ▼
+  window.SITE_CONFIG = effective
+       │
+       ▼
+  applyCSS(effective)
+       │
+       ▼
+  dispatch 'theme-changed'
+```
+
+## Function Signatures
+
+### `readOverrides() → object`
+
+Reads `cs-theme-overrides` from localStorage, parses as JSON. Returns empty object `{}` on missing key, parse error, or non-object value. Never throws.
+
+### `writeOverrides(delta: object) → void`
+
+Serializes `delta` to JSON and writes to `cs-theme-overrides` in localStorage. If `delta` is empty (`{}`), removes the key entirely.
+
+**Validation on write:**
+- Color values must match: `#hex` (3, 4, 6, or 8 digit), `rgb()`, `rgba()`, `hsl()`, `hsla()`, or CSS named colors. Invalid color values are rejected (not written) with `console.warn`.
+- Numeric values (`heatmapOpacity`, `liveHeatmapOpacity`) must be finite numbers in the range 0–1. Invalid values are rejected with `console.warn`.
+- Timestamp enum values are validated against known options (`defaultMode`: `'ago'`/`'absolute'`; `timezone`: `'local'`/`'utc'`; `formatPreset`: `'iso'`/`'iso-seconds'`/`'locale'`). Invalid values are rejected with `console.warn`.
+
+**Quota error handling:**
+- Wrap `localStorage.setItem` in try/catch.
+- On `QuotaExceededError`: show a visible warning to the user ("Storage full — changes may not be saved"), log to console.
+- Do NOT silently swallow the error.
+
+### `computeEffective(serverConfig: object, userOverrides: object) → object`
+
+Deep merges `userOverrides` onto `serverConfig`. For each section (e.g., `theme`, `nodeColors`), if `userOverrides` has the section, its keys override the corresponding `serverConfig` keys. Top-level non-object keys (e.g., `heatmapOpacity`) are directly overridden.
+
+Returns a new object — neither input is mutated.
+
+**Merge rules:**
+- Object sections: shallow merge per section (`Object.assign({}, server.theme, user.theme)`)
+- Array sections (e.g., `home.steps`): full replacement (user array wins entirely, no element-level merge)
+- Scalar sections (e.g., `heatmapOpacity`): direct replacement
+
+After computing the effective config, writes it to `window.SITE_CONFIG` atomically (single assignment, not piecemeal mutations).
+
+### `applyCSS(effectiveConfig: object) → void`
+
+Maps effective config values to CSS custom properties on `:root`. Behavior:
+
+1. Reads the current mode (light/dark) from the `meshcore-theme` localStorage key, falling back to system preference (`prefers-color-scheme`).
+2. Applies the matching section's values: `theme` for light mode, `themeDark` for dark mode.
+3. Also applies mode-independent values: node colors as `--node-{role}`, type colors as `--type-{name}`, font families as `--font-body` and `--font-mono`.
+4. Does NOT generate dual CSS rule blocks — only the current mode's values are applied to `:root`.
+5. On dark/light mode toggle, `applyCSS` is called again to re-apply the correct section.
+
+Updates the `<style>` element (create if absent, reuse if present). Dispatches a `theme-changed` CustomEvent on `window` after applying.
+
+### `theme-changed` Event
+
+- `theme-changed` is a bare `CustomEvent` with no payload (matches current behavior).
+- After each merge cycle, the effective config is written to `window.SITE_CONFIG` atomically (single assignment).
+- `window.SITE_CONFIG` is the canonical readable source for effective config throughout the app. All existing listeners that read from `SITE_CONFIG` continue to work without changes.
+
+### `setOverride(section: string, key: string, value: any) → void`
+
+Sets a single override. For nested sections (e.g., `section='theme'`, `key='accent'`), sets `delta[section][key] = value`. For top-level scalars (e.g., `section=null`, `key='heatmapOpacity'`), sets `delta[key] = value`.
+
+Follows the full data flow: read → update → write → read-back → merge → apply CSS → dispatch `theme-changed`. Debounced at ~300ms (the debounce wraps the write-through-to-CSS portion).
+
+### `clearOverride(section: string, key: string) → void`
+
+Removes a single key from the delta. If the section becomes empty after removal, removes the section too. Triggers the full data flow (no debounce — resets should feel instant).
+
+### `migrateOldKeys() → object | null`
+
+One-time migration. Checks for any of the 7 legacy localStorage keys. If found:
+1. Reads all legacy values
+2. Maps them into the new delta format (see Migration Plan)
+3. Writes the merged delta to `cs-theme-overrides`
+4. Removes all 7 legacy keys
+5. Returns the migrated delta
+
+Returns `null` if no legacy keys found.
+
+### `validateShape(obj: any) → { valid: boolean, errors: string[] }`
+
+Validates that an imported object conforms to the expected shape:
+- Must be a plain object
+- Top-level keys must be from the known set: `branding`, `theme`, `themeDark`, `nodeColors`, `typeColors`, `home`, `timestamps`, `heatmapOpacity`, `liveHeatmapOpacity`
+- Section values must be objects (where expected) or correct scalar types
+- Color values are validated: must match `#hex` (3, 4, 6, or 8 digit), `rgb()`, `rgba()`, `hsl()`, `hsla()`, or CSS named colors
+- Numeric values (`heatmapOpacity`, `liveHeatmapOpacity`) must be finite numbers in range 0–1
+- Timestamp enum values validated against known options
+
+Unknown top-level keys cause a warning but don't fail validation (forward compatibility).
+
+## Migration Plan
+
+On first page load, before the normal init flow:
+
+1. Check if `cs-theme-overrides` already exists → if yes, skip migration.
+2. Check if ANY of the 7 legacy keys exist in localStorage.
+3. If legacy keys found, build a delta object using the exact mapping below:
+
+### Field-by-Field Migration Mapping
+
+```
+meshcore-user-theme (JSON) → parse, map directly:
+  .branding  → delta.branding
+  .theme     → delta.theme
+  .themeDark → delta.themeDark
+  .nodeColors → delta.nodeColors
+  .typeColors → delta.typeColors
+  .home      → delta.home
+  (any other keys are dropped)
+
+meshcore-timestamp-mode           → delta.timestamps.defaultMode
+meshcore-timestamp-timezone       → delta.timestamps.timezone
+meshcore-timestamp-format         → delta.timestamps.formatPreset
+meshcore-timestamp-custom-format  → delta.timestamps.customFormat
+meshcore-heatmap-opacity          → delta.heatmapOpacity (parseFloat)
+meshcore-live-heatmap-opacity     → delta.liveHeatmapOpacity (parseFloat)
+```
+
+4. Write the assembled delta to `cs-theme-overrides`.
+5. Delete all 7 legacy keys.
+6. Continue with normal init.
+
+**Edge cases:**
+- If `meshcore-user-theme` contains invalid JSON, skip it (log a warning to console).
+- If a legacy value is empty string or null, skip that field.
+- Migration runs exactly once — the presence of `cs-theme-overrides` (even as `{}`) prevents re-migration.
+
+## `allowCustomFormat` — User Preferences Trump
+
+The server-side `allowCustomFormat` gate is not enforced client-side. If a user imports a delta with a custom format, it's applied regardless. The server controls what formats are available in the UI (whether the custom format input field is shown), but does not block stored preferences.
+
+## Override Indicator UX
+
+In the customizer panel, each field that has an active override (value differs from server default) shows a visual indicator:
+
+- **Indicator:** A small dot or icon (e.g., `●` or a reset arrow `↺`) adjacent to the field label.
+- **Color:** Use the accent color to draw attention without being noisy.
+- **Behavior:** Clicking the indicator resets that single field (calls `clearOverride`).
+- **Tooltip:** "Reset to server default" or "This value differs from the server default."
+- **Absence:** Fields matching the server default show no indicator — clean and minimal.
+
+**Section-level indicator:** If any field in a section (e.g., "Theme Colors") is overridden, the tab/section header shows a count badge (e.g., "Theme Colors (3)").
+
+**"Reset All" button:** Always visible at bottom of panel. Confirms before executing (`localStorage.removeItem` + re-merge).
+
+## UX Requirements
+
+### Browser-Local Banner
+
+The customizer panel must display a persistent, always-visible notice:
+
+> **"These settings are saved in your browser only and don't affect other users."**
+
+This is NOT a tooltip, NOT a dismissible popup — it must be always visible in the panel header or footer area. Users must understand at a glance that their changes are local.
+
+### Auto-Save Indicator
+
+Show a persistent status in the customizer panel footer, Google Docs style — subtle but always present:
+
+- **Default state:** "All changes saved" (muted text)
+- **During debounce:** "Saving..." (muted text)
+- **On quota error:** "⚠️ Storage full — changes may not be saved" (red text, persistent until resolved)
+
+The indicator reflects the actual state of the localStorage write, not just the UI action.
+
+## Server Compatibility
+
+The delta format is intentionally shaped to be a valid subset of the server's `theme.json` admin config file. This means:
+
+- **User export → admin import:** An admin can take a user's exported JSON and drop it into `theme.json` as server defaults. The `timestamps`, `heatmapOpacity`, and `liveHeatmapOpacity` keys are ignored by the current server (it doesn't read them from `theme.json`), but they don't cause errors.
+- **Admin config → user import:** A `theme.json` file can be imported as user overrides. Unknown server-only keys are ignored by the client.
+- **Round-trip safe:** Export → import produces identical delta (assuming no server default changes between operations).
+
+The server's `ThemeResponse` struct currently returns: `branding`, `theme`, `themeDark`, `nodeColors`, `typeColors`, `home`. The client-only extensions (`timestamps`, `heatmapOpacity`, `liveHeatmapOpacity`) are additive — they extend the format without conflicting.
+
+## Testing Requirements
+
+### Unit Tests (Node.js, no browser required)
+
+1. **`readOverrides`**
+   - Returns `{}` when key is absent
+   - Returns `{}` when key contains invalid JSON
+   - Returns `{}` when key contains a non-object (string, array, number)
+   - Returns parsed object when key contains valid JSON object
+
+2. **`writeOverrides`**
+   - Writes serialized JSON to localStorage
+   - Removes key when delta is empty `{}`
+   - Round-trips correctly (write → read = identical object)
+   - Rejects invalid color values with console.warn
+   - Rejects out-of-range numeric values with console.warn
+   - Rejects invalid timestamp enum values with console.warn
+   - Handles QuotaExceededError gracefully (warns user, does not throw)
+
+3. **`computeEffective`**
+   - Returns server defaults when overrides is `{}`
+   - Overrides a single key in a section
+   - Overrides multiple keys across sections
+   - Does not mutate either input
+   - Handles missing sections in overrides gracefully
+   - Array values (e.g., `home.steps`) are fully replaced, not merged
+   - Top-level scalars (`heatmapOpacity`) are directly replaced
+
+4. **`setOverride` / `clearOverride`**
+   - Setting a value stores it in the delta
+   - Clearing a key removes it from delta
+   - Clearing the last key in a section removes the section
+   - Full data flow executes (CSS vars updated)
+
+5. **`migrateOldKeys`**
+   - Migrates all 7 keys correctly using exact field mapping
+   - Handles partial migration (only some keys present)
+   - Handles invalid JSON in `meshcore-user-theme`
+   - Removes all legacy keys after migration
+   - Skips migration if `cs-theme-overrides` already exists
+   - Returns null when no legacy keys found
+   - Drops unknown keys from `meshcore-user-theme`
+
+6. **`validateShape`**
+   - Accepts valid delta objects
+   - Accepts empty object
+   - Rejects non-objects (string, array, null)
+   - Warns on unknown top-level keys (doesn't reject)
+   - Validates section types (object vs scalar)
+   - Rejects invalid color values
+   - Rejects out-of-range opacity values
+   - Rejects invalid timestamp enum values
+
+### Browser/E2E Tests (Playwright)
+
+1. **Customizer opens and shows current values** — fields reflect effective config.
+2. **Changing a color updates CSS variable** — after debounce, `:root` has new value.
+3. **Override indicator appears** when value differs from server default.
+4. **Per-field reset** removes override, reverts to server default, indicator disappears.
+5. **Full reset** clears all overrides, all fields show server defaults.
+6. **Export** downloads a JSON file with current delta.
+7. **Import** applies overrides from uploaded JSON file.
+8. **Migration** — set legacy keys, reload, verify they're migrated and removed.
+9. **Preset application** — clicking a preset applies its colors, fields update.
+10. **Dark/light mode toggle** — switching mode re-applies correct section's CSS vars.
+11. **Browser-local banner** — verify persistent notice is visible in customizer panel.
+12. **Auto-save indicator** — verify status text updates during and after changes.
+
+## What's NOT In Scope
+
+- **Undo/redo stack** — could be added as P2. For v1, per-field reset to server default is the only revert mechanism.
+- **Cross-tab synchronization** — two tabs editing simultaneously may clobber each other's changes. Acceptable for v1.
+- **Server-side timestamp config** (`allowCustomFormat` gate) — remains server-only, not exposed in the customizer delta. The server controls UI availability but does not block stored preferences (see `allowCustomFormat` section above).
+- **Admin import endpoint** — no server API for uploading `theme.json` via the UI. Admins edit the file directly. Future work.
+- **Map config overrides** (`mapDefaults.center`, `mapDefaults.zoom`) — separate concern, not part of theme. Future work.
+- **Geo-filter config** — server-only. Not in scope.
+- **Per-page layout preferences** (column widths, sort orders) — separate from theming. Future work.

internal/geofilter/geofilter.go

@@ -0,0 +1,86 @@
+// Package geofilter provides the shared geographic filter configuration and
+// geometry used by both the server and ingestor packages.
+package geofilter
+
+import "math"
+
+// Config defines the geographic filter polygon or bounding box.
+// Shared between the server and ingestor packages.
+type Config struct {
+	Polygon  [][2]float64 `json:"polygon,omitempty"`
+	BufferKm float64      `json:"bufferKm,omitempty"`
+	LatMin   *float64     `json:"latMin,omitempty"`
+	LatMax   *float64     `json:"latMax,omitempty"`
+	LonMin   *float64     `json:"lonMin,omitempty"`
+	LonMax   *float64     `json:"lonMax,omitempty"`
+}
+
+// PassesFilter returns true if the coordinates fall within the filter area.
+// Nodes with no GPS fix (0,0) are always allowed.
+func PassesFilter(lat, lon float64, gf *Config) bool {
+	if gf == nil {
+		return true
+	}
+	if lat == 0 && lon == 0 {
+		return true
+	}
+	if len(gf.Polygon) >= 3 {
+		if PointInPolygon(lat, lon, gf.Polygon) {
+			return true
+		}
+		if gf.BufferKm > 0 {
+			n := len(gf.Polygon)
+			for i := 0; i < n; i++ {
+				j := (i + 1) % n
+				if DistToSegmentKm(lat, lon, gf.Polygon[i], gf.Polygon[j]) <= gf.BufferKm {
+					return true
+				}
+			}
+		}
+		return false
+	}
+	// Legacy bounding box fallback
+	if gf.LatMin != nil && gf.LatMax != nil && gf.LonMin != nil && gf.LonMax != nil {
+		return lat >= *gf.LatMin && lat <= *gf.LatMax && lon >= *gf.LonMin && lon <= *gf.LonMax
+	}
+	return true
+}
+
+// PointInPolygon uses the ray-casting algorithm.
+func PointInPolygon(lat, lon float64, polygon [][2]float64) bool {
+	inside := false
+	n := len(polygon)
+	j := n - 1
+	for i := 0; i < n; i++ {
+		yi, xi := polygon[i][0], polygon[i][1]
+		yj, xj := polygon[j][0], polygon[j][1]
+		if (yi > lat) != (yj > lat) {
+			if lon < (xj-xi)*(lat-yi)/(yj-yi)+xi {
+				inside = !inside
+			}
+		}
+		j = i
+	}
+	return inside
+}
+
+// DistToSegmentKm returns the approximate distance in km from point (lat,lon)
+// to line segment a→b using a flat-earth projection.
+func DistToSegmentKm(lat, lon float64, a, b [2]float64) float64 {
+	lat1, lon1 := a[0], a[1]
+	lat2, lon2 := b[0], b[1]
+	cosLat := math.Cos((lat1+lat2) / 2.0 * math.Pi / 180.0)
+	ax := (lon1 - lon) * 111.0 * cosLat
+	ay := (lat1 - lat) * 111.0
+	bx := (lon2 - lon) * 111.0 * cosLat
+	by := (lat2 - lat) * 111.0
+	abx, aby := bx-ax, by-ay
+	abSq := abx*abx + aby*aby
+	if abSq == 0 {
+		return math.Sqrt(ax*ax + ay*ay)
+	}
+	t := math.Max(0, math.Min(1, -(ax*abx+ay*aby)/abSq))
+	px := ax + t*abx
+	py := ay + t*aby
+	return math.Sqrt(px*px + py*py)
+}

internal/geofilter/go.mod

@@ -0,0 +1,3 @@
+module github.com/meshcore-analyzer/geofilter
+
+go 1.22

manage.sh

@@ -40,7 +40,7 @@ STAGING_DATA="${STAGING_DATA_DIR:-$HOME/meshcore-staging-data}"
 STAGING_COMPOSE_FILE="docker-compose.staging.yml"
 
 # Build metadata — exported so docker compose build picks them up via args
-export APP_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "unknown")
+export APP_VERSION=$(git describe --tags --match "v*" 2>/dev/null || echo "unknown")
 export GIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
 export BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
@@ -509,6 +509,24 @@ cmd_setup() {
 
   log "Docker $(docker --version | grep -oP 'version \K[^ ,]+')"
   log "Compose: $DC"
+
+  # Default to latest release tag (instead of staying on master)
+  if ! is_done "version_pin"; then
+    git fetch origin --tags --force 2>/dev/null || true
+    local latest_tag
+    latest_tag=$(git tag -l 'v*' --sort=-v:refname | head -1)
+    if [ -n "$latest_tag" ]; then
+      local current_ref
+      current_ref=$(git describe --tags --exact-match 2>/dev/null || echo "")
+      if [ "$current_ref" != "$latest_tag" ]; then
+        info "Pinning to latest release: ${latest_tag}"
+        git checkout "$latest_tag" 2>/dev/null
+      else
+        log "Already on latest release: ${latest_tag}"
+      fi
+    fi
+    mark_done "version_pin"
+  fi
   
   mark_done "docker"
 
@@ -885,14 +903,10 @@ prepare_staging_config() {
     warn "No production config at ${prod_config} — staging may use defaults."
     return
   fi
-  if [ ! -f "$staging_config" ] || [ "$prod_config" -nt "$staging_config" ]; then
-    info "Copying production config to staging..."
-    cp "$prod_config" "$staging_config"
-    sed -i 's/"siteName":\s*"[^"]*"/"siteName": "CoreScope — STAGING"/' "$staging_config"
-    log "Staging config created at ${staging_config} with STAGING site name."
-  else
-    log "Staging config is up to date."
-  fi
+  info "Copying production config to staging..."
+  cp "$prod_config" "$staging_config"
+  sed -i 's/"siteName":\s*"[^"]*"/"siteName": "CoreScope — STAGING"/' "$staging_config"
+  log "Staging config created at ${staging_config} with STAGING site name."
   # Copy Caddyfile for staging (HTTP-only on staging port)
   local staging_caddy="$STAGING_DATA/Caddyfile"
   if [ ! -f "$staging_caddy" ]; then
@@ -1167,6 +1181,12 @@ cmd_status() {
   echo "═══════════════════════════════════════"
   echo ""
 
+  # Version
+  local current_version
+  current_version=$(git describe --tags --exact-match 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+  info "Version: ${current_version}"
+  echo ""
+
   # Production
   show_container_status "corescope-prod" "Production"
   echo ""
@@ -1294,8 +1314,39 @@ cmd_promote() {
 # ─── Update ───────────────────────────────────────────────────────────────
 
 cmd_update() {
-  info "Pulling latest code..."
-  git pull --ff-only
+  local version="${1:-}"
+
+  info "Fetching latest changes and tags..."
+  git fetch origin --tags --force
+
+  if [ -z "$version" ]; then
+    # No arg: checkout latest release tag
+    local latest_tag
+    latest_tag=$(git tag -l 'v*' --sort=-v:refname | head -1)
+    if [ -z "$latest_tag" ]; then
+      err "No release tags found. Use './manage.sh update latest' for tip of master."
+      exit 1
+    fi
+    info "Checking out latest release: ${latest_tag}"
+    git checkout "$latest_tag" || { err "Failed to checkout tag '${latest_tag}'."; exit 1; }
+  elif [ "$version" = "latest" ]; then
+    # Explicit opt-in to bleeding edge (tip of master)
+    # Note: this creates a detached HEAD at origin/master, which is intentional —
+    # we want a read-only snapshot of upstream, not a local tracking branch.
+    info "Checking out tip of master (detached HEAD at origin/master)..."
+    git checkout origin/master || { err "Failed to checkout origin/master."; exit 1; }
+  else
+    # Specific tag requested
+    if ! git tag -l "$version" | grep -q .; then
+      err "Tag '${version}' not found."
+      echo ""
+      echo "   Available releases:"
+      git tag -l 'v*' --sort=-v:refname | head -10 | sed 's/^/     /'
+      exit 1
+    fi
+    info "Checking out version: ${version}"
+    git checkout "$version" || { err "Failed to checkout '${version}'."; exit 1; }
+  fi
 
   migrate_config auto
 
@@ -1306,6 +1357,10 @@ cmd_update() {
   dc_prod up -d --force-recreate prod
 
   log "Updated and restarted. Data preserved."
+  # Show current version
+  local current
+  current=$(git describe --tags --exact-match 2>/dev/null || git rev-parse --short HEAD)
+  log "Running version: ${current}"
 }
 
 # ─── Backup ───────────────────────────────────────────────────────────────
@@ -1515,7 +1570,7 @@ cmd_help() {
   echo "    logs [prod|staging] [N]  Follow logs (default: prod, last 100 lines)"
   echo ""
   printf '%b\n' "  ${BOLD}Maintain${NC}"
-  echo "    update             Pull latest code, rebuild, restart (keeps data)"
+  echo "    update [version]   Update to version (no arg=latest tag, 'latest'=master tip, or e.g. v3.1.0)"
   echo "    promote            Promote staging → production (backup + restart)"
   echo "    backup [dir]       Full backup: database + config + theme"
   echo "    restore <d>        Restore from backup dir or .db file"
@@ -1534,7 +1589,7 @@ case "${1:-help}" in
   restart)   cmd_restart "$2" ;;
   status)    cmd_status ;;
   logs)      cmd_logs "$2" "$3" ;;
-  update)    cmd_update ;;
+  update)    cmd_update "$2" ;;
   promote)   cmd_promote ;;
   backup)    cmd_backup "$2" ;;
   restore)   cmd_restore "$2" ;;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "meshcore-analyzer",
-  "version": "3.1.0",
+  "version": "0.0.0-use-git-tags",
   "description": "Community-run alternative to the closed-source `analyzer.letsmesh.net`. MQTT packet collection + open-source web analyzer for the Bay Area MeshCore mesh.",
   "main": "index.js",
   "scripts": {

public/app.js

@@ -9,6 +9,8 @@ const PAYLOAD_COLORS = { 0: 'req', 1: 'response', 2: 'txt-msg', 3: 'ack', 4: 'ad
 function routeTypeName(n) { return ROUTE_TYPES[n] || 'UNKNOWN'; }
 function payloadTypeName(n) { return PAYLOAD_TYPES[n] || 'UNKNOWN'; }
 function payloadTypeColor(n) { return PAYLOAD_COLORS[n] || 'unknown'; }
+function isTransportRoute(rt) { return rt === 0 || rt === 3; }
+function transportBadge(rt) { return isTransportRoute(rt) ? ' <span class="badge badge-transport" title="' + routeTypeName(rt) + '">T</span>' : ''; }
 
 // --- Utilities ---
 const _apiPerf = { calls: 0, totalMs: 0, log: [], cacheHits: 0 };
@@ -134,13 +136,6 @@ function getTimestampCustomFormat() {
 function pad2(v) { return String(v).padStart(2, '0'); }
 function pad3(v) { return String(v).padStart(3, '0'); }
 
-function mergeUserHomeConfig(siteConfig, userTheme) {
-  if (!siteConfig || !userTheme || !userTheme.home || typeof userTheme.home !== 'object') return siteConfig;
-  const serverHome = (siteConfig.home && typeof siteConfig.home === 'object') ? siteConfig.home : {};
-  siteConfig.home = Object.assign({}, serverHome, userTheme.home);
-  return siteConfig;
-}
-
 function formatIsoLike(d, timezone, includeMs) {
   const useUtc = timezone === 'utc';
   const year = useUtc ? d.getUTCFullYear() : d.getFullYear();
@@ -405,7 +400,24 @@ function registerPage(name, mod) { pages[name] = mod; }
 
 let currentPage = null;
 
+function closeNav() {
+  document.querySelector('.nav-links')?.classList.remove('open');
+  document.body.classList.remove('nav-open');
+  var btn = document.getElementById('hamburger');
+  if (btn) btn.setAttribute('aria-expanded', 'false');
+  closeMoreMenu();
+}
+
+function closeMoreMenu() {
+  var menu = document.getElementById('navMoreMenu');
+  var btn = document.getElementById('navMoreBtn');
+  if (menu) menu.classList.remove('open');
+  if (btn) btn.setAttribute('aria-expanded', 'false');
+}
+
 function navigate() {
+  closeNav();
+
   const hash = location.hash.replace('#/', '') || 'packets';
   const route = hash.split('?')[0];
 
@@ -437,6 +449,13 @@ function navigate() {
   document.querySelectorAll('.nav-link[data-route]').forEach(el => {
     el.classList.toggle('active', el.dataset.route === basePage);
   });
+  // Update "More" button to show active state if a low-priority page is selected
+  var moreBtn = document.getElementById('navMoreBtn');
+  if (moreBtn) {
+    var moreMenu = document.getElementById('navMoreMenu');
+    var hasActiveMore = moreMenu && moreMenu.querySelector('.nav-link.active');
+    moreBtn.classList.toggle('active', !!hasActiveMore);
+  }
 
   if (currentPage && pages[currentPage]?.destroy) {
     pages[currentPage].destroy();
@@ -444,6 +463,9 @@ function navigate() {
   currentPage = basePage;
 
   const app = document.getElementById('app');
+  // Pages with fixed-height containers (maps, virtual-scroll, split-panels)
+  const fixedPages = { packets: 1, nodes: 1, map: 1, live: 1, channels: 1, 'audio-lab': 1 };
+  app.classList.toggle('app-fixed', basePage in fixedPages);
   if (pages[basePage]?.init) {
     const t0 = performance.now();
     pages[basePage].init(app, routeParam);
@@ -531,10 +553,57 @@ window.addEventListener('DOMContentLoaded', () => {
   // --- Hamburger Menu ---
   const hamburger = document.getElementById('hamburger');
   const navLinks = document.querySelector('.nav-links');
-  hamburger.addEventListener('click', () => navLinks.classList.toggle('open'));
-  // Close menu on nav link click
+  hamburger.addEventListener('click', () => {
+    const opening = !navLinks.classList.contains('open');
+    navLinks.classList.toggle('open');
+    document.body.classList.toggle('nav-open');
+    hamburger.setAttribute('aria-expanded', String(opening));
+  });
   navLinks.querySelectorAll('.nav-link').forEach(link => {
-    link.addEventListener('click', () => navLinks.classList.remove('open'));
+    link.addEventListener('click', closeNav);
+  });
+
+  // --- "More" dropdown (tablet Priority+ nav) ---
+  const navMoreBtn = document.getElementById('navMoreBtn');
+  const navMoreMenu = document.getElementById('navMoreMenu');
+  if (navMoreBtn && navMoreMenu) {
+    // Build More menu dynamically from non-priority nav links (DRY)
+    navMoreMenu.innerHTML = '';
+    document.querySelectorAll('.nav-links a:not([data-priority="high"])').forEach(function(link) {
+      var clone = link.cloneNode(true);
+      clone.setAttribute('role', 'menuitem');
+      clone.addEventListener('click', closeMoreMenu);
+      navMoreMenu.appendChild(clone);
+    });
+    navMoreBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const opening = !navMoreMenu.classList.contains('open');
+      navMoreMenu.classList.toggle('open');
+      navMoreBtn.setAttribute('aria-expanded', String(opening));
+      if (opening) {
+        var firstLink = navMoreMenu.querySelector('.nav-link');
+        if (firstLink) firstLink.focus();
+      }
+    });
+  }
+
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') {
+      if (navMoreMenu && navMoreMenu.classList.contains('open')) closeMoreMenu();
+      if (navLinks.classList.contains('open')) closeNav();
+    }
+  });
+  document.addEventListener('click', (e) => {
+    if (navLinks.classList.contains('open') &&
+        !navLinks.contains(e.target) &&
+        !hamburger.contains(e.target)) {
+      closeNav();
+    }
+    if (navMoreMenu && navMoreMenu.classList.contains('open') &&
+        !navMoreMenu.contains(e.target) &&
+        !navMoreBtn.contains(e.target)) {
+      closeMoreMenu();
+    }
   });
 
   // --- Favorites dropdown ---
@@ -721,91 +790,30 @@ window.addEventListener('DOMContentLoaded', () => {
   debouncedOnWS(function () { updateNavStats(); });
 
   // --- Theme Customization ---
-  // Fetch theme config and apply branding/colors before first render
+  // Fetch theme config and apply via customizer v2 pipeline
   fetch('/api/config/theme', { cache: 'no-store' }).then(r => r.json()).then(cfg => {
-    window.SITE_CONFIG = cfg || {};
-    if (!window.SITE_CONFIG.timestamps) window.SITE_CONFIG.timestamps = {};
-    const tsCfg = window.SITE_CONFIG.timestamps;
+    // Normalize timestamp defaults
+    cfg = cfg || {};
+    if (!cfg.timestamps) cfg.timestamps = {};
+    const tsCfg = cfg.timestamps;
     if (tsCfg.defaultMode !== 'absolute' && tsCfg.defaultMode !== 'ago') tsCfg.defaultMode = 'ago';
     if (tsCfg.timezone !== 'utc' && tsCfg.timezone !== 'local') tsCfg.timezone = 'local';
     if (tsCfg.formatPreset !== 'iso' && tsCfg.formatPreset !== 'iso-seconds' && tsCfg.formatPreset !== 'locale') tsCfg.formatPreset = 'iso';
     if (typeof tsCfg.customFormat !== 'string') tsCfg.customFormat = '';
     tsCfg.allowCustomFormat = tsCfg.allowCustomFormat === true;
 
-    // User's localStorage preferences take priority over server config
-    const userTheme = (() => { try { return JSON.parse(localStorage.getItem('meshcore-user-theme') || '{}'); } catch { return {}; } })();
-    mergeUserHomeConfig(window.SITE_CONFIG, userTheme);
-
-    // Apply CSS variable overrides from theme config (skipped if user has local overrides)
-    if (!userTheme.theme && !userTheme.themeDark) {
-      const dark = document.documentElement.getAttribute('data-theme') === 'dark' ||
-        (document.documentElement.getAttribute('data-theme') !== 'light' && window.matchMedia('(prefers-color-scheme: dark)').matches);
-      const themeData = dark ? { ...(cfg.theme || {}), ...(cfg.themeDark || {}) } : (cfg.theme || {});
-      const root = document.documentElement.style;
-      const varMap = {
-        accent: '--accent', accentHover: '--accent-hover',
-        navBg: '--nav-bg', navBg2: '--nav-bg2', navText: '--nav-text', navTextMuted: '--nav-text-muted',
-        background: '--surface-0', text: '--text', textMuted: '--text-muted', border: '--border',
-        statusGreen: '--status-green', statusYellow: '--status-yellow', statusRed: '--status-red',
-        surface1: '--surface-1', surface2: '--surface-2', surface3: '--surface-3',
-        cardBg: '--card-bg', contentBg: '--content-bg', inputBg: '--input-bg',
-        rowStripe: '--row-stripe', rowHover: '--row-hover', detailBg: '--detail-bg',
-        selectedBg: '--selected-bg', sectionBg: '--section-bg',
-        font: '--font', mono: '--mono'
-      };
-      for (const [key, cssVar] of Object.entries(varMap)) {
-        if (themeData[key]) root.setProperty(cssVar, themeData[key]);
-      }
-      // Derived vars
-      if (themeData.background) root.setProperty('--content-bg', themeData.contentBg || themeData.background);
-      if (themeData.surface1) root.setProperty('--card-bg', themeData.cardBg || themeData.surface1);
-      // Nav gradient
-      if (themeData.navBg) {
-        const nav = document.querySelector('.top-nav');
-        if (nav) nav.style.background = `linear-gradient(135deg, ${themeData.navBg} 0%, ${themeData.navBg2 || themeData.navBg} 50%, ${themeData.navBg} 100%)`;
-      }
+    // Customizer v2: set server defaults and run full pipeline
+    // (reads localStorage overrides → merges → sets SITE_CONFIG → applies CSS → dispatches theme-changed)
+    if (window._customizerV2) {
+      window._customizerV2.init(cfg);
+    } else {
+      // Fallback if customize-v2.js didn't load
+      window.SITE_CONFIG = cfg;
     }
-
-    // Apply node color overrides (skip if user has local preferences)
-    if (cfg.nodeColors && !userTheme.nodeColors) {
-      for (const [role, color] of Object.entries(cfg.nodeColors)) {
-        if (window.ROLE_COLORS && role in window.ROLE_COLORS) window.ROLE_COLORS[role] = color;
-        if (window.ROLE_STYLE && window.ROLE_STYLE[role]) window.ROLE_STYLE[role].color = color;
-      }
-    }
-
-    // Apply type color overrides (skip if user has local preferences)
-    if (cfg.typeColors && !userTheme.typeColors) {
-      for (const [type, color] of Object.entries(cfg.typeColors)) {
-        if (window.TYPE_COLORS && type in window.TYPE_COLORS) window.TYPE_COLORS[type] = color;
-      }
-      if (window.syncBadgeColors) window.syncBadgeColors();
-    }
-
-    // Apply branding (skip if user has local preferences)
-    if (cfg.branding && !userTheme.branding) {
-      if (cfg.branding.siteName) {
-        document.title = cfg.branding.siteName;
-        const brandText = document.querySelector('.brand-text');
-        if (brandText) brandText.textContent = cfg.branding.siteName;
-      }
-      if (cfg.branding.logoUrl) {
-        const brandIcon = document.querySelector('.brand-icon');
-        if (brandIcon) {
-          const img = document.createElement('img');
-          img.src = cfg.branding.logoUrl;
-          img.alt = cfg.branding.siteName || 'Logo';
-          img.style.height = '24px';
-          img.style.width = 'auto';
-          brandIcon.replaceWith(img);
-        }
-      }
-      if (cfg.branding.faviconUrl) {
-        const favicon = document.querySelector('link[rel="icon"]');
-        if (favicon) favicon.href = cfg.branding.faviconUrl;
-      }
-    }
-  }).catch(() => { window.SITE_CONFIG = { timestamps: { defaultMode: 'ago', timezone: 'local', formatPreset: 'iso', customFormat: '', allowCustomFormat: false } }; }).finally(() => {
+  }).catch(() => {
+    window.SITE_CONFIG = { timestamps: { defaultMode: 'ago', timezone: 'local', formatPreset: 'iso', customFormat: '', allowCustomFormat: false } };
+    if (window._customizerV2) window._customizerV2.init(window.SITE_CONFIG);
+  }).finally(() => {
     if (!location.hash || location.hash === '#/') location.hash = '#/home';
     else navigate();
   });

public/channels.js

@@ -274,6 +274,9 @@
     for (let i = 0; i < str.length; i++) h = ((h << 5) - h + str.charCodeAt(i)) | 0;
     return Math.abs(h);
   }
+  function formatHashHex(hash) {
+    return typeof hash === 'number' ? '0x' + hash.toString(16).toUpperCase().padStart(2, '0') : hash;
+  }
   function getChannelColor(hash) { return CHANNEL_COLORS[hashCode(String(hash)) % CHANNEL_COLORS.length]; }
   function getSenderColor(name) {
     const isDark = document.documentElement.getAttribute('data-theme') === 'dark' ||
@@ -659,7 +662,7 @@
     });
 
     el.innerHTML = sorted.map(ch => {
-      const name = ch.name || `Channel ${ch.hash}`;
+      const name = ch.name || `Channel ${formatHashHex(ch.hash)}`;
       const color = getChannelColor(ch.hash);
       const time = ch.lastActivityMs ? formatSecondsAgo(Math.floor((Date.now() - ch.lastActivityMs) / 1000)) : '';
       const preview = ch.lastSender && ch.lastMessage
@@ -688,7 +691,7 @@
     history.replaceState(null, '', `#/channels/${encodeURIComponent(hash)}`);
     renderChannelList();
     const ch = channels.find(c => c.hash === hash);
-    const name = ch?.name || `Channel ${hash}`;
+    const name = ch?.name || `Channel ${formatHashHex(hash)}`;
     const header = document.getElementById('chHeader');
     header.querySelector('.ch-header-text').textContent = `${name} — ${ch?.messageCount || 0} messages`;
 

public/compare.js

@@ -48,7 +48,7 @@ if (typeof window !== 'undefined') window.comparePacketSets = comparePacketSets;
     packetsB = [];
     currentView = 'summary';
 
-    app.innerHTML = '<div class="compare-page" style="overflow-y:auto;height:calc(100vh - 56px);padding:16px">' +
+    app.innerHTML = '<div class="compare-page" style="padding:16px">' +
       '<div class="page-header" style="display:flex;align-items:center;gap:12px;margin-bottom:16px">' +
         '<a href="#/observers" class="btn-icon" title="Back to Observers" aria-label="Back">\u2190</a>' +
         '<h2 style="margin:0">\uD83D\uDD0D Observer Comparison</h2>' +

public/customize.js

@@ -450,7 +450,8 @@
     function mergeSection(key) {
       return Object.assign({}, DEFAULTS[key], cfg[key] || {}, local[key] || {});
     }
-    var mergedHome = mergeSection('home');
+    var serverHome = window._SITE_CONFIG_ORIGINAL_HOME || cfg.home || {};
+    var mergedHome = Object.assign({}, DEFAULTS.home, serverHome, local.home || {});
     var localTsMode = localStorage.getItem('meshcore-timestamp-mode');
     var localTsTimezone = localStorage.getItem('meshcore-timestamp-timezone');
     var localTsFormat = localStorage.getItem('meshcore-timestamp-format');
@@ -1202,19 +1203,19 @@
         var tmp = state.home.steps[i];
         state.home.steps[i] = state.home.steps[j];
         state.home.steps[j] = tmp;
-        render(container);
+        render(container); autoSave();
       });
     });
     container.querySelectorAll('[data-rm-step]').forEach(function (btn) {
       btn.addEventListener('click', function () {
         state.home.steps.splice(parseInt(btn.dataset.rmStep), 1);
-        render(container);
+        render(container); autoSave();
       });
     });
     var addStepBtn = document.getElementById('addStep');
     if (addStepBtn) addStepBtn.addEventListener('click', function () {
       state.home.steps.push({ emoji: '📌', title: '', description: '' });
-      render(container);
+      render(container); autoSave();
     });
 
     // Checklist
@@ -1227,13 +1228,13 @@
     container.querySelectorAll('[data-rm-check]').forEach(function (btn) {
       btn.addEventListener('click', function () {
         state.home.checklist.splice(parseInt(btn.dataset.rmCheck), 1);
-        render(container);
+        render(container); autoSave();
       });
     });
     var addCheckBtn = document.getElementById('addCheck');
     if (addCheckBtn) addCheckBtn.addEventListener('click', function () {
       state.home.checklist.push({ question: '', answer: '' });
-      render(container);
+      render(container); autoSave();
     });
 
     // Footer links
@@ -1246,13 +1247,13 @@
     container.querySelectorAll('[data-rm-link]').forEach(function (btn) {
       btn.addEventListener('click', function () {
         state.home.footerLinks.splice(parseInt(btn.dataset.rmLink), 1);
-        render(container);
+        render(container); autoSave();
       });
     });
     var addLinkBtn = document.getElementById('addLink');
     if (addLinkBtn) addLinkBtn.addEventListener('click', function () {
       state.home.footerLinks.push({ label: '', url: '' });
-      render(container);
+      render(container); autoSave();
     });
 
     // Export copy

public/home.css

@@ -1,7 +1,6 @@
 /* === CoreScope — home.css === */
 
-/* Override #app overflow:hidden for home page scrolling */
-#app:has(.home-hero), #app:has(.home-chooser) { overflow-y: auto; }
+/* Home page now uses body scroll (no #app override needed — see style.css) */
 
 /* Chooser */
 .home-chooser {

public/home.js

@@ -511,27 +511,35 @@
   function timeSinceMs(d) { return Date.now() - d.getTime(); }
 
   function checklist(homeCfg) {
-    if (homeCfg?.checklist) {
-      return homeCfg.checklist.map(i => `<div class="checklist-item"><div class="checklist-q" role="button" tabindex="0" aria-expanded="false">${escapeHtml(i.question)}</div><div class="checklist-a">${window.miniMarkdown ? miniMarkdown(i.answer) : escapeHtml(i.answer)}</div></div>`).join('');
+    var html = '';
+    // Render steps (getting started guide)
+    if (homeCfg?.steps?.length) {
+      html += homeCfg.steps.map(s => `<div class="checklist-item"><div class="checklist-q" role="button" tabindex="0" aria-expanded="false">${escapeHtml(s.emoji || '')} ${escapeHtml(s.title)}</div><div class="checklist-a">${window.miniMarkdown ? miniMarkdown(s.description) : escapeHtml(s.description)}</div></div>`).join('');
     }
-    if (homeCfg?.steps) {
-      return homeCfg.steps.map(s => `<div class="checklist-item"><div class="checklist-q" role="button" tabindex="0" aria-expanded="false">${escapeHtml(s.emoji || '')} ${escapeHtml(s.title)}</div><div class="checklist-a">${window.miniMarkdown ? miniMarkdown(s.description) : escapeHtml(s.description)}</div></div>`).join('');
+    // Render FAQ/checklist (additional Q&A)
+    if (homeCfg?.checklist?.length) {
+      if (html) html += '<h3 style="margin:24px 0 12px;font-size:16px">❓ FAQ</h3>';
+      html += homeCfg.checklist.map(i => `<div class="checklist-item"><div class="checklist-q" role="button" tabindex="0" aria-expanded="false">${escapeHtml(i.question)}</div><div class="checklist-a">${window.miniMarkdown ? miniMarkdown(i.answer) : escapeHtml(i.answer)}</div></div>`).join('');
     }
-    const items = [
-      { q: '💬 First: Join the Bay Area MeshCore Discord',
-        a: '<p>The community Discord is the best place to get help and find local mesh enthusiasts.</p><p><a href="https://discord.gg/q59JzsYTst" target="_blank" rel="noopener" style="color:var(--accent);font-weight:600">Join the Discord ↗</a></p><p>Start with <strong>#intro-to-meshcore</strong> — it has detailed setup instructions.</p>' },
-      { q: '🔵 Step 1: Connect via Bluetooth',
-        a: '<p>Flash <strong>BLE companion</strong> firmware from <a href="https://flasher.meshcore.co.uk/" target="_blank" rel="noopener" style="color:var(--accent)">MeshCore Flasher</a>.</p><ul><li>Screenless devices: default PIN <code>123456</code></li><li>Screen devices: random PIN shown on display</li><li>If pairing fails: forget device, reboot, re-pair</li></ul>' },
-      { q: '📻 Step 2: Set the right frequency preset',
-        a: '<p><strong>US Recommended:</strong></p><div style="margin:8px 0;padding:8px 12px;background:var(--surface-1);border-radius:6px;font-family:var(--mono);font-size:.85rem">910.525 MHz · BW 62.5 kHz · SF 7 · CR 5</div><p>Select <strong>"US Recommended"</strong> in the app or flasher.</p>' },
-      { q: '📡 Step 3: Advertise yourself',
-        a: '<p>Tap the signal icon → <strong>Flood</strong> to broadcast your node to the mesh. Companions only advert when you trigger it manually.</p>' },
-      { q: '🔁 Step 4: Check "Heard N repeats"',
-        a: '<ul><li><strong>"Sent"</strong> = transmitted, no confirmation</li><li><strong>"Heard 0 repeats"</strong> = no repeater picked it up</li><li><strong>"Heard 1+ repeats"</strong> = you\'re on the mesh!</li></ul>' },
-      { q: '📍 Repeaters near you?',
-        a: '<p><a href="#/map" style="color:var(--accent)">Check the network map</a> to see active repeaters.</p>' }
-    ];
-    return items.map(i => `<div class="checklist-item"><div class="checklist-q" role="button" tabindex="0" aria-expanded="false">${i.q}</div><div class="checklist-a">${i.a}</div></div>`).join('');
+    // Fallback: Bay Area defaults when no config at all
+    if (!html) {
+      const items = [
+        { q: '💬 First: Join the Bay Area MeshCore Discord',
+          a: '<p>The community Discord is the best place to get help and find local mesh enthusiasts.</p><p><a href="https://discord.gg/q59JzsYTst" target="_blank" rel="noopener" style="color:var(--accent);font-weight:600">Join the Discord ↗</a></p><p>Start with <strong>#intro-to-meshcore</strong> — it has detailed setup instructions.</p>' },
+        { q: '🔵 Step 1: Connect via Bluetooth',
+          a: '<p>Flash <strong>BLE companion</strong> firmware from <a href="https://flasher.meshcore.co.uk/" target="_blank" rel="noopener" style="color:var(--accent)">MeshCore Flasher</a>.</p><ul><li>Screenless devices: default PIN <code>123456</code></li><li>Screen devices: random PIN shown on display</li><li>If pairing fails: forget device, reboot, re-pair</li></ul>' },
+        { q: '📻 Step 2: Set the right frequency preset',
+          a: '<p><strong>US Recommended:</strong></p><div style="margin:8px 0;padding:8px 12px;background:var(--surface-1);border-radius:6px;font-family:var(--mono);font-size:.85rem">910.525 MHz · BW 62.5 kHz · SF 7 · CR 5</div><p>Select <strong>"US Recommended"</strong> in the app or flasher.</p>' },
+        { q: '📡 Step 3: Advertise yourself',
+          a: '<p>Tap the signal icon → <strong>Flood</strong> to broadcast your node to the mesh. Companions only advert when you trigger it manually.</p>' },
+        { q: '🔁 Step 4: Check "Heard N repeats"',
+          a: '<ul><li><strong>"Sent"</strong> = transmitted, no confirmation</li><li><strong>"Heard 0 repeats"</strong> = no repeater picked it up</li><li><strong>"Heard 1+ repeats"</strong> = you\'re on the mesh!</li></ul>' },
+        { q: '📍 Repeaters near you?',
+          a: '<p><a href="#/map" style="color:var(--accent)">Check the network map</a> to see active repeaters.</p>' }
+      ];
+      html = items.map(i => `<div class="checklist-item"><div class="checklist-q" role="button" tabindex="0" aria-expanded="false">${i.q}</div><div class="checklist-a">${i.a}</div></div>`).join('');
+    }
+    return html;
   }
 
   registerPage('home', { init, destroy });

public/hop-resolver.js

@@ -8,9 +8,11 @@ window.HopResolver = (function() {
   const MAX_HOP_DIST = 1.8; // ~200km in degrees
   const REGION_RADIUS_KM = 300;
   let prefixIdx = {};   // lowercase hex prefix → [node, ...]
+  let pubkeyIdx = {};   // full lowercase pubkey → node (O(1) lookup)
   let nodesList = [];
   let observerIataMap = {}; // observer_id → iata
   let iataCoords = {};  // iata → {lat, lon}
+  let affinityMap = {}; // pubkey → { neighborPubkey → score }
 
   function dist(lat1, lon1, lat2, lon2) {
     return Math.sqrt((lat1 - lat2) ** 2 + (lon1 - lon2) ** 2);
@@ -34,9 +36,11 @@ window.HopResolver = (function() {
   function init(nodes, opts) {
     nodesList = nodes || [];
     prefixIdx = {};
+    pubkeyIdx = {};
     for (const n of nodesList) {
       if (!n.public_key) continue;
       const pk = n.public_key.toLowerCase();
+      pubkeyIdx[pk] = n;
       for (let len = 1; len <= 3; len++) {
         const p = pk.slice(0, len * 2);
         if (!prefixIdx[p]) prefixIdx[p] = [];
@@ -67,6 +71,34 @@ window.HopResolver = (function() {
     return null; // no GPS — can't geo-filter client-side
   }
 
+  /**
+   * Pick the best candidate using affinity first, then geo-distance fallback.
+   * @param {Array} candidates - candidates with lat/lon/pubkey/name
+   * @param {string|null} adjacentPubkey - pubkey of the previously/next resolved hop
+   * @param {Object|null} anchor - {lat, lon} for geo fallback
+   * @param {number|null} fallbackLat - fallback anchor lat (e.g. observer)
+   * @param {number|null} fallbackLon - fallback anchor lon
+   * @returns {Object} best candidate
+   */
+  function pickByAffinity(candidates, adjacentPubkey, anchor, fallbackLat, fallbackLon) {
+    // If we have affinity data and an adjacent hop, prefer neighbors
+    if (adjacentPubkey && Object.keys(affinityMap).length > 0) {
+      const withAffinity = candidates
+        .map(c => ({ ...c, affinity: getAffinity(adjacentPubkey, c.pubkey) }))
+        .filter(c => c.affinity > 0);
+      if (withAffinity.length > 0) {
+        withAffinity.sort((a, b) => b.affinity - a.affinity);
+        return withAffinity[0];
+      }
+    }
+    // Fallback: geo-distance sort (existing behavior)
+    const effectiveAnchor = anchor || (fallbackLat != null ? { lat: fallbackLat, lon: fallbackLon } : null);
+    if (effectiveAnchor) {
+      candidates.sort((a, b) => dist(a.lat, a.lon, effectiveAnchor.lat, effectiveAnchor.lon) - dist(b.lat, b.lon, effectiveAnchor.lat, effectiveAnchor.lon));
+    }
+    return candidates[0];
+  }
+
   /**
    * Resolve an array of hex hop prefixes to node info.
    * Returns a map: { hop: {name, pubkey, lat, lon, ambiguous, unreliable} }
@@ -139,40 +171,50 @@ window.HopResolver = (function() {
 
     // Forward pass
     let lastPos = (originLat != null && originLon != null) ? { lat: originLat, lon: originLon } : null;
+    let lastResolvedPubkey = null;
     for (let i = 0; i < hops.length; i++) {
       const hop = hops[i];
-      if (hopPositions[hop]) { lastPos = hopPositions[hop]; continue; }
+      if (hopPositions[hop]) {
+        lastPos = hopPositions[hop];
+        lastResolvedPubkey = resolved[hop] ? resolved[hop].pubkey : null;
+        continue;
+      }
       const r = resolved[hop];
       if (!r || !r.ambiguous) continue;
       const withLoc = r.candidates.filter(c => c.lat && c.lon && !(c.lat === 0 && c.lon === 0));
       if (!withLoc.length) continue;
-      let anchor = lastPos;
-      if (!anchor && i === hops.length - 1 && observerLat != null) {
-        anchor = { lat: observerLat, lon: observerLon };
-      }
-      if (anchor) {
-        withLoc.sort((a, b) => dist(a.lat, a.lon, anchor.lat, anchor.lon) - dist(b.lat, b.lon, anchor.lat, anchor.lon));
-      }
-      r.name = withLoc[0].name;
-      r.pubkey = withLoc[0].pubkey;
-      hopPositions[hop] = { lat: withLoc[0].lat, lon: withLoc[0].lon };
+
+      // Affinity-aware: prefer candidates that are neighbors of the previous hop
+      const picked = pickByAffinity(withLoc, lastResolvedPubkey, lastPos, i === hops.length - 1 ? observerLat : null, i === hops.length - 1 ? observerLon : null);
+      r.name = picked.name;
+      r.pubkey = picked.pubkey;
+      hopPositions[hop] = { lat: picked.lat, lon: picked.lon };
       lastPos = hopPositions[hop];
+      lastResolvedPubkey = picked.pubkey;
     }
 
     // Backward pass
     let nextPos = (observerLat != null && observerLon != null) ? { lat: observerLat, lon: observerLon } : null;
+    let nextResolvedPubkey = null;
     for (let i = hops.length - 1; i >= 0; i--) {
       const hop = hops[i];
-      if (hopPositions[hop]) { nextPos = hopPositions[hop]; continue; }
+      if (hopPositions[hop]) {
+        nextPos = hopPositions[hop];
+        nextResolvedPubkey = resolved[hop] ? resolved[hop].pubkey : null;
+        continue;
+      }
       const r = resolved[hop];
       if (!r || !r.ambiguous) continue;
       const withLoc = r.candidates.filter(c => c.lat && c.lon && !(c.lat === 0 && c.lon === 0));
       if (!withLoc.length || !nextPos) continue;
-      withLoc.sort((a, b) => dist(a.lat, a.lon, nextPos.lat, nextPos.lon) - dist(b.lat, b.lon, nextPos.lat, nextPos.lon));
-      r.name = withLoc[0].name;
-      r.pubkey = withLoc[0].pubkey;
-      hopPositions[hop] = { lat: withLoc[0].lat, lon: withLoc[0].lon };
+
+      // Affinity-aware: prefer candidates that are neighbors of the next hop
+      const picked = pickByAffinity(withLoc, nextResolvedPubkey, nextPos, null, null);
+      r.name = picked.name;
+      r.pubkey = picked.pubkey;
+      hopPositions[hop] = { lat: picked.lat, lon: picked.lon };
       nextPos = hopPositions[hop];
+      nextResolvedPubkey = picked.pubkey;
     }
 
     // Sanity check: drop hops impossibly far from neighbors
@@ -203,5 +245,53 @@ window.HopResolver = (function() {
     return nodesList.length > 0;
   }
 
-  return { init: init, resolve: resolve, ready: ready };
+  /**
+   * Load neighbor-graph affinity data.
+   * @param {Object} graph - { edges: [{source, target, score, weight}, ...] }
+   */
+  function setAffinity(graph) {
+    affinityMap = {};
+    if (!graph || !graph.edges) return;
+    for (const e of graph.edges) {
+      if (!affinityMap[e.source]) affinityMap[e.source] = {};
+      affinityMap[e.source][e.target] = e.score || e.weight || 1;
+      if (!affinityMap[e.target]) affinityMap[e.target] = {};
+      affinityMap[e.target][e.source] = e.score || e.weight || 1;
+    }
+  }
+
+  /**
+   * Get the affinity score between two pubkeys (0 if not neighbors).
+   */
+  function getAffinity(pubkeyA, pubkeyB) {
+    if (!pubkeyA || !pubkeyB || !affinityMap[pubkeyA]) return 0;
+    return affinityMap[pubkeyA][pubkeyB] || 0;
+  }
+
+  /**
+   * Resolve hops using server-provided resolved_path (full pubkeys).
+   * Returns the same format as resolve() — { [hop]: { name, pubkey, ... } }.
+   * resolved_path is an array aligned with path_json: each element is a
+   * 64-char lowercase hex pubkey or null. Skips entries that are null.
+   */
+  function resolveFromServer(hops, resolvedPath) {
+    if (!hops || !resolvedPath || hops.length !== resolvedPath.length) return {};
+    var result = {};
+    for (var i = 0; i < hops.length; i++) {
+      var hop = hops[i];
+      var pubkey = resolvedPath[i];
+      if (!pubkey) continue; // null = unresolved, leave for client-side fallback
+      // O(1) lookup via pubkeyIdx built during init()
+      var node = pubkeyIdx[pubkey.toLowerCase()] || null;
+      result[hop] = {
+        name: node ? node.name : pubkey.slice(0, 8),
+        pubkey: pubkey,
+        candidates: node ? [{ name: node.name, pubkey: pubkey, lat: node.lat, lon: node.lon }] : [],
+        conflicts: []
+      };
+    }
+    return result;
+  }
+
+  return { init: init, resolve: resolve, resolveFromServer: resolveFromServer, ready: ready, haversineKm: haversineKm, setAffinity: setAffinity, getAffinity: getAffinity };
 })();

public/index.html

@@ -22,9 +22,9 @@
   <meta name="twitter:title" content="CoreScope">
   <meta name="twitter:description" content="Real-time MeshCore LoRa mesh network analyzer — live packet visualization, node tracking, channel decryption, and route analysis.">
   <meta name="twitter:image" content="https://raw.githubusercontent.com/Kpa-clawbot/corescope/master/public/og-image.png">
-  <link rel="stylesheet" href="style.css?v=1774937706">
-  <link rel="stylesheet" href="home.css?v=1774937706">
-  <link rel="stylesheet" href="live.css?v=1774937706">
+  <link rel="stylesheet" href="style.css?v=__BUST__">
+  <link rel="stylesheet" href="home.css?v=__BUST__">
+  <link rel="stylesheet" href="live.css?v=__BUST__">
   <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
     integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
     crossorigin="anonymous">
@@ -44,18 +44,22 @@
         <span class="live-dot" id="liveDot" title="WebSocket connected" aria-label="WebSocket connected"></span>
       </a>
       <div class="nav-links">
-        <a href="#/home" class="nav-link" data-route="home">Home</a>
-        <a href="#/packets" class="nav-link" data-route="packets">Packets</a>
-        <a href="#/map" class="nav-link" data-route="map">Map</a>
-        <a href="#/live" class="nav-link" data-route="live">🔴 Live</a>
+        <a href="#/home" class="nav-link" data-route="home" data-priority="high">Home</a>
+        <a href="#/packets" class="nav-link" data-route="packets" data-priority="high">Packets</a>
+        <a href="#/map" class="nav-link" data-route="map" data-priority="high">Map</a>
+        <a href="#/live" class="nav-link" data-route="live" data-priority="high">🔴 Live</a>
         <a href="#/channels" class="nav-link" data-route="channels">Channels</a>
-        <a href="#/nodes" class="nav-link" data-route="nodes">Nodes</a>
+        <a href="#/nodes" class="nav-link" data-route="nodes" data-priority="high">Nodes</a>
         <a href="#/traces" class="nav-link" data-route="traces">Traces</a>
         <a href="#/observers" class="nav-link" data-route="observers">Observers</a>
         <a href="#/analytics" class="nav-link" data-route="analytics">Analytics</a>
         <a href="#/perf" class="nav-link" data-route="perf">⚡ Perf</a>
         <a href="#/audio-lab" class="nav-link" data-route="audio-lab">🎵 Lab</a>
       </div>
+      <div class="nav-more-wrap">
+        <button class="nav-btn nav-more-btn" id="navMoreBtn" aria-haspopup="true" aria-expanded="false" aria-controls="navMoreMenu" title="More pages">More ▾</button>
+        <div class="nav-more-menu" id="navMoreMenu" role="menu"></div>
+      </div>
     </div>
     <div class="nav-right">
       <div class="nav-stats" id="navStats" title="Live stats"></div>
@@ -81,33 +85,31 @@
   <main id="app" role="main"></main>
 
   <script src="vendor/qrcode.js"></script>
-  <script src="roles.js?v=1774937706"></script>
-  <script src="customize.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="region-filter.js?v=1774937706"></script>
-  <script src="hop-resolver.js?v=1774937706"></script>
-  <script src="hop-display.js?v=1774937706"></script>
-  <script src="app.js?v=1774937706"></script>
-  <script src="home.js?v=1774937706"></script>
-  <script src="packet-filter.js?v=1774937706"></script>
-  <script src="packets.js?v=1774937706"></script>
-  <script src="geo-filter-overlay.js?v=1774937706"></script>
-  <script src="map.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="channels.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="nodes.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="traces.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="analytics.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="audio.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="audio-v1-constellation.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="audio-v2-constellation.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="audio-lab.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="live.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="observers.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="observer-detail.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="compare.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="node-analytics.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
-  <script src="perf.js?v=1774937706" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="roles.js?v=__BUST__"></script>
+  <script src="customize-v2.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="region-filter.js?v=__BUST__"></script>
+  <script src="hop-resolver.js?v=__BUST__"></script>
+  <script src="hop-display.js?v=__BUST__"></script>
+  <script src="app.js?v=__BUST__"></script>
+  <script src="home.js?v=__BUST__"></script>
+  <script src="packet-filter.js?v=__BUST__"></script>
+  <script src="packet-helpers.js?v=__BUST__"></script>
+  <script src="packets.js?v=__BUST__"></script>
+  <script src="geo-filter-overlay.js?v=__BUST__"></script>
+  <script src="map.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="channels.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="nodes.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="traces.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="analytics.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="audio.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="audio-v1-constellation.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="audio-v2-constellation.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="audio-lab.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="live.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="observers.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="observer-detail.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="compare.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="node-analytics.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
+  <script src="perf.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></script>
 </body>
 </html>
-
-
-

public/live.js

@@ -1,6 +1,10 @@
 (function() {
   'use strict';
 
+  // getParsedPath / getParsedDecoded are in shared packet-helpers.js (loaded before this file)
+  var getParsedPath = window.getParsedPath;
+  var getParsedDecoded = window.getParsedDecoded;
+
   // Status color helpers (read from CSS variables for theme support)
   function cssVar(name) { return getComputedStyle(document.documentElement).getPropertyValue(name).trim(); }
   function statusGreen() { return cssVar('--status-green') || '#22c55e'; }
@@ -10,6 +14,7 @@
   let nodeData = {};
   let packetCount = 0;
   let activeAnims = 0;
+  const MAX_CONCURRENT_ANIMS = 20;
   let nodeActivity = {};
   let recentPaths = [];
   let showGhostHops = localStorage.getItem('live-ghost-hops') !== 'false';
@@ -38,6 +43,7 @@
     timelineScope: 3600000, // 1h default ms
     timelineTimestamps: [], // historical timestamps from DB for sparkline
     timelineFetchedScope: 0, // last fetched scope to avoid redundant fetches
+    replayGen: 0,            // generation counter — incremented on each replay/rewind to discard stale async results
   };
 
   // ROLE_COLORS loaded from shared roles.js (includes 'unknown')
@@ -111,6 +117,7 @@
 
   function vcrResumeLive() {
     stopReplay();
+    VCR.replayGen++; // invalidate any in-flight async chunk processing
     VCR.playhead = -1;
     VCR.speed = 1;
     VCR.missedCount = 0;
@@ -137,6 +144,8 @@
   function vcrReplayFromTs(targetTs) {
     const fetchFrom = new Date(targetTs).toISOString();
     stopReplay();
+    VCR.replayGen++;
+    var gen = VCR.replayGen;
     vcrSetMode('REPLAY');
 
     // Reload map nodes to match the replay time
@@ -148,7 +157,10 @@
       .then(r => r.json())
       .then(data => {
         const pkts = data.packets || [];
-        const replayEntries = expandToBufferEntries(pkts);
+        return expandToBufferEntriesAsync(pkts);
+      })
+      .then(function(replayEntries) {
+        if (gen !== VCR.replayGen) return; // stale async result — user changed mode
         if (replayEntries.length === 0) {
           vcrSetMode('PAUSED');
           return;
@@ -197,6 +209,8 @@
 
   function vcrRewind(ms) {
     stopReplay();
+    VCR.replayGen++;
+    var gen = VCR.replayGen;
     // Fetch packets from DB for the time window
     const now = Date.now();
     const from = new Date(now - ms).toISOString();
@@ -207,8 +221,11 @@
         // Prepend to buffer (avoid duplicates by ID)
         const existingIds = new Set(VCR.buffer.map(b => b.pkt.id).filter(Boolean));
         const filtered = pkts.filter(p => !existingIds.has(p.id));
-        const newEntries = expandToBufferEntries(filtered);
-        VCR.buffer = [...newEntries, ...VCR.buffer];
+        return expandToBufferEntriesAsync(filtered);
+      })
+      .then(function(newEntries) {
+        if (gen !== VCR.replayGen) return; // stale async result
+        VCR.buffer = [].concat(newEntries, VCR.buffer);
         VCR.playhead = 0;
         VCR.speed = 1;
         vcrSetMode('REPLAY');
@@ -269,15 +286,18 @@
     // Get timestamp of last packet in buffer to fetch the next page
     const last = VCR.buffer[VCR.buffer.length - 1];
     if (!last) return Promise.resolve(false);
+    var gen = VCR.replayGen;
     const since = new Date(last.ts + 1).toISOString(); // +1ms to avoid dupe
     return fetch(`/api/packets?limit=10000&grouped=false&expand=observations&since=${encodeURIComponent(since)}&order=asc`)
       .then(r => r.json())
       .then(data => {
         const pkts = data.packets || [];
         if (pkts.length === 0) return false;
-        const newEntries = expandToBufferEntries(pkts);
-        VCR.buffer = VCR.buffer.concat(newEntries);
-        return true;
+        return expandToBufferEntriesAsync(pkts).then(function(newEntries) {
+          if (gen !== VCR.replayGen) return false; // stale
+          VCR.buffer = VCR.buffer.concat(newEntries);
+          return true;
+        });
       })
       .catch(() => false);
   }
@@ -368,12 +388,17 @@
     }
   }
 
-  function updateVCRClock(tsMs) {
+  function vcrFormatTime(tsMs) {
     const d = new Date(tsMs);
-    const hh = String(d.getHours()).padStart(2, '0');
-    const mm = String(d.getMinutes()).padStart(2, '0');
-    const ss = String(d.getSeconds()).padStart(2, '0');
-    drawLcdText(`${hh}:${mm}:${ss}`, statusGreen());
+    const utc = typeof getTimestampTimezone === 'function' && getTimestampTimezone() === 'utc';
+    const hh = String(utc ? d.getUTCHours() : d.getHours()).padStart(2, '0');
+    const mm = String(utc ? d.getUTCMinutes() : d.getMinutes()).padStart(2, '0');
+    const ss = String(utc ? d.getUTCSeconds() : d.getSeconds()).padStart(2, '0');
+    return `${hh}:${mm}:${ss}`;
+  }
+
+  function updateVCRClock(tsMs) {
+    drawLcdText(vcrFormatTime(tsMs), statusGreen());
   }
 
   function updateVCRLcd() {
@@ -425,13 +450,14 @@
   }
 
   function dbPacketToLive(pkt) {
-    const raw = JSON.parse(pkt.decoded_json || '{}');
-    const hops = JSON.parse(pkt.path_json || '[]');
+    const raw = getParsedDecoded(pkt);
+    const hops = getParsedPath(pkt);
     const typeName = raw.type || pkt.payload_type_name || 'UNKNOWN';
     return {
       id: pkt.id, hash: pkt.hash,
       raw: pkt.raw_hex,
       path_json: pkt.path_json,
+      resolved_path: pkt.resolved_path,
       _ts: new Date(pkt.timestamp || pkt.created_at).getTime(),
       decoded: { header: { payloadTypeName: typeName }, payload: raw, path: { hops } },
       snr: pkt.snr, rssi: pkt.rssi, observer: pkt.observer_name
@@ -439,11 +465,53 @@
   }
 
   // Expand a DB packet (with optional observations[]) into VCR buffer entries
+  /**
+   * Process packets into buffer entries in chunks to avoid blocking the main thread.
+   * Returns a Promise that resolves with the entries array.
+   * Each chunk processes CHUNK_SIZE packets, then yields to the event loop via setTimeout(0).
+   */
+  var VCR_CHUNK_SIZE = 200;
+  function expandToBufferEntriesAsync(pkts) {
+    return new Promise(function(resolve) {
+      var entries = [];
+      var i = 0;
+      function processChunk() {
+        var end = Math.min(i + VCR_CHUNK_SIZE, pkts.length);
+        for (; i < end; i++) {
+          var p = pkts[i];
+          if (p.observations && p.observations.length > 0) {
+            for (var j = 0; j < p.observations.length; j++) {
+              var obs = p.observations[j];
+              entries.push({
+                ts: new Date(obs.timestamp || p.timestamp || p.created_at).getTime(),
+                pkt: dbPacketToLive(Object.assign({}, p, obs, { hash: p.hash, raw_hex: p.raw_hex, decoded_json: p.decoded_json }))
+              });
+            }
+          } else {
+            entries.push({
+              ts: new Date(p.timestamp || p.created_at).getTime(),
+              pkt: dbPacketToLive(p)
+            });
+          }
+        }
+        if (i < pkts.length) {
+          setTimeout(processChunk, 0);
+        } else {
+          resolve(entries);
+        }
+      }
+      processChunk();
+    });
+  }
+
+  // Synchronous version kept for small datasets and backward compat (tests)
   function expandToBufferEntries(pkts) {
-    const entries = [];
-    for (const p of pkts) {
+    var entries = [];
+    for (var k = 0; k < pkts.length; k++) {
+      var p = pkts[k];
       if (p.observations && p.observations.length > 0) {
-        for (const obs of p.observations) {
+        for (var j = 0; j < p.observations.length; j++) {
+          var obs = p.observations[j];
           entries.push({
             ts: new Date(obs.timestamp || p.timestamp || p.created_at).getTime(),
             pkt: dbPacketToLive(Object.assign({}, p, obs, { hash: p.hash, raw_hex: p.raw_hex, decoded_json: p.decoded_json }))
@@ -472,11 +540,18 @@
         clearTimeout(entry.timer);
       }
       propagationBuffer.clear();
+      // Batch-update timeline once on restore instead of per-packet while hidden
+      updateTimeline();
     }
   });
 
+  function packetTimestamp(pkt) {
+    return new Date(pkt.timestamp || pkt.created_at || Date.now()).getTime();
+  }
+  if (typeof window !== 'undefined') window._live_packetTimestamp = packetTimestamp;
+
   function bufferPacket(pkt) {
-    pkt._ts = Date.now();
+    pkt._ts = packetTimestamp(pkt);
     const entry = { ts: pkt._ts, pkt };
     VCR.buffer.push(entry);
     // Keep buffer capped at ~2000 — adjust playhead to avoid stale indices (#63)
@@ -491,7 +566,6 @@
     if (VCR.mode === 'LIVE') {
       // Skip animations when tab is backgrounded — just buffer for VCR timeline
       if (_tabHidden) {
-        updateTimeline();
         return;
       }
       if (realisticPropagation && pkt.hash) {
@@ -817,7 +891,48 @@
     });
 
     // Geo filter overlay
-    initGeoFilterOverlay(map, 'liveGeoFilterToggle', 'liveGeoFilterLabel').then(function (layer) { geoFilterLayer = layer; });
+    (async function () {
+      try {
+        const gf = await api('/config/geo-filter', { ttl: 3600 });
+        if (!gf || !gf.polygon || gf.polygon.length < 3) return;
+        const geoColor = cssVar('--geo-filter-color') || '#3b82f6';
+        const latlngs = gf.polygon.map(function (p) { return [p[0], p[1]]; });
+        const innerPoly = L.polygon(latlngs, {
+          color: geoColor, weight: 2, opacity: 0.8,
+          fillColor: geoColor, fillOpacity: 0.08
+        });
+        const bufferPoly = gf.bufferKm > 0 ? (function () {
+          let cLat = 0, cLon = 0;
+          gf.polygon.forEach(function (p) { cLat += p[0]; cLon += p[1]; });
+          cLat /= gf.polygon.length; cLon /= gf.polygon.length;
+          const cosLat = Math.cos(cLat * Math.PI / 180);
+          const outer = gf.polygon.map(function (p) {
+            const dLatM = (p[0] - cLat) * 111000;
+            const dLonM = (p[1] - cLon) * 111000 * cosLat;
+            const dist = Math.sqrt(dLatM * dLatM + dLonM * dLonM);
+            if (dist === 0) return [p[0], p[1]];
+            const scale = (gf.bufferKm * 1000) / dist;
+            return [p[0] + dLatM * scale / 111000, p[1] + dLonM * scale / (111000 * cosLat)];
+          });
+          return L.polygon(outer, {
+            color: geoColor, weight: 1.5, opacity: 0.4, dashArray: '6 4',
+            fillColor: geoColor, fillOpacity: 0.04
+          });
+        })() : null;
+        geoFilterLayer = L.layerGroup(bufferPoly ? [bufferPoly, innerPoly] : [innerPoly]);
+        const label = document.getElementById('liveGeoFilterLabel');
+        if (label) label.style.display = '';
+        const el = document.getElementById('liveGeoFilterToggle');
+        if (el) {
+          const saved = localStorage.getItem('meshcore-map-geo-filter');
+          if (saved === 'true') { el.checked = true; geoFilterLayer.addTo(map); }
+          el.addEventListener('change', function (e) {
+            localStorage.setItem('meshcore-map-geo-filter', e.target.checked);
+            if (e.target.checked) { geoFilterLayer.addTo(map); } else { map.removeLayer(geoFilterLayer); }
+          });
+        }
+      } catch (e) { /* no geo filter configured */ }
+    })();
 
     const matrixToggle = document.getElementById('liveMatrixToggle');
     matrixToggle.checked = matrixMode;
@@ -1019,8 +1134,7 @@
       const rect = timelineEl.getBoundingClientRect();
       const pct = (e.clientX - rect.left) / rect.width;
       const ts = Date.now() - VCR.timelineScope + pct * VCR.timelineScope;
-      const d = new Date(ts);
-      timeTooltip.textContent = d.toLocaleTimeString([], {hour:'2-digit',minute:'2-digit',second:'2-digit'});
+      timeTooltip.textContent = vcrFormatTime(ts);
       timeTooltip.style.left = (e.clientX - rect.left) + 'px';
       timeTooltip.classList.remove('hidden');
     });
@@ -1033,8 +1147,7 @@
       const rect = timelineEl.getBoundingClientRect();
       const pct = Math.max(0, Math.min(1, (touch.clientX - rect.left) / rect.width));
       const ts = Date.now() - VCR.timelineScope + pct * VCR.timelineScope;
-      const d = new Date(ts);
-      timeTooltip.textContent = d.toLocaleTimeString([], {hour:'2-digit',minute:'2-digit',second:'2-digit'});
+      timeTooltip.textContent = vcrFormatTime(ts);
       timeTooltip.style.left = (touch.clientX - rect.left) + 'px';
       timeTooltip.classList.remove('hidden');
     });
@@ -1232,7 +1345,7 @@
         html += `<h4 style="font-size:12px;margin:12px 0 6px;color:var(--text-muted);">Recent Packets</h4>
           <div style="font-size:11px;max-height:200px;overflow-y:auto;">` +
           recent.slice(0, 10).map(p => `<div style="padding:2px 0;display:flex;justify-content:space-between;">
-            <a href="#/packets/${encodeURIComponent(p.hash || '')}" style="color:var(--accent);text-decoration:none;">${escapeHtml(p.payload_type || '?')}${p.observation_count > 1 ? ' <span class="badge badge-obs" style="font-size:9px">👁 ' + p.observation_count + '</span>' : ''}</a>
+            <a href="#/packets/${encodeURIComponent(p.hash || '')}" style="color:var(--accent);text-decoration:none;">${escapeHtml(p.payload_type || '?')}${transportBadge(p.route_type)}${p.observation_count > 1 ? ' <span class="badge badge-obs" style="font-size:9px">👁 ' + p.observation_count + '</span>' : ''}</a>
             <span style="color:var(--text-muted)">${formatLiveTimestampHtml(p.timestamp)}</span>
           </div>`).join('') +
           '</div>';
@@ -1305,9 +1418,29 @@
       const _el2 = document.getElementById('liveNodeCount'); if (_el2) _el2.textContent = Object.keys(nodeMarkers).length;
       // Initialize shared HopResolver with loaded nodes
       if (window.HopResolver) HopResolver.init(list);
+      // Fetch affinity data for hop disambiguation
+      fetchAffinityData();
+      startAffinityRefresh();
     } catch (e) { console.error('Failed to load nodes:', e); }
   }
 
+  let _affinityInterval = null;
+
+  async function fetchAffinityData() {
+    try {
+      const resp = await fetch('/api/analytics/neighbor-graph');
+      const graph = await resp.json();
+      if (window.HopResolver && HopResolver.setAffinity) {
+        HopResolver.setAffinity(graph);
+      }
+    } catch (e) { console.warn('Failed to fetch affinity data:', e); }
+  }
+
+  function startAffinityRefresh() {
+    if (_affinityInterval) clearInterval(_affinityInterval);
+    _affinityInterval = setInterval(fetchAffinityData, 60000);
+  }
+
   function clearNodeMarkers() {
     if (nodesLayer) nodesLayer.clearLayers();
     if (animLayer) animLayer.clearLayers();
@@ -1395,7 +1528,7 @@
       for (const op of group.packets) {
         let opHops = [];
         if (op.path_json) {
-          try { opHops = typeof op.path_json === 'string' ? JSON.parse(op.path_json) : op.path_json; } catch {}
+          try { opHops = getParsedPath(op); } catch {}
         } else if (op.decoded?.path?.hops) {
           opHops = op.decoded.path.hops;
         }
@@ -1417,7 +1550,7 @@
       item.innerHTML = `
         <span class="feed-icon" style="color:${color}">${icon}</span>
         <span class="feed-type" style="color:${color}">${typeName}</span>
-        ${hopStr}${obsBadge}
+        ${transportBadge(pkt.route_type)}${hopStr}${obsBadge}
         <span class="feed-text">${escapeHtml(preview)}</span>
         <span class="feed-time">${formatLiveTimestampHtml(group.latestTs || Date.now())}</span>
       `;
@@ -1519,6 +1652,7 @@
           }
           delete nodeMarkers[key];
           delete nodeData[key];
+          delete nodeActivity[key];
           pruned = true;
         }
       } else if (marker && marker._staleDimmed) {
@@ -1534,29 +1668,43 @@
       if (_el2) _el2.textContent = Object.keys(nodeMarkers).length;
       if (window.HopResolver) HopResolver.init(Object.values(nodeData));
     }
+    // Prune orphaned nodeActivity entries (nodes removed above or never tracked)
+    for (var aKey in nodeActivity) {
+      if (!(aKey in nodeData)) delete nodeActivity[aKey];
+    }
   }
 
   // Expose for testing
   window._livePruneStaleNodes = pruneStaleNodes;
   window._liveNodeMarkers = function() { return nodeMarkers; };
   window._liveNodeData = function() { return nodeData; };
+  window._liveNodeActivity = function() { return nodeActivity; };
+  window._vcrFormatTime = vcrFormatTime;
+  window._liveDbPacketToLive = dbPacketToLive;
+  window._liveExpandToBufferEntries = expandToBufferEntries;
+  window._liveExpandToBufferEntriesAsync = expandToBufferEntriesAsync;
+  window._liveSEG_MAP = SEG_MAP;
+  window._liveBufferPacket = bufferPacket;
+  window._liveVCR = function() { return VCR; };
+  window._liveGetFavoritePubkeys = getFavoritePubkeys;
+  window._livePacketInvolvesFavorite = packetInvolvesFavorite;
+  window._liveIsNodeFavorited = isNodeFavorited;
+  window._liveFormatLiveTimestampHtml = formatLiveTimestampHtml;
+  window._liveResolveHopPositions = resolveHopPositions;
+  window._liveVcrSpeedCycle = vcrSpeedCycle;
+  window._liveVcrPause = vcrPause;
+  window._liveVcrResumeLive = vcrResumeLive;
+  window._liveVcrSetMode = vcrSetMode;
 
   async function replayRecent() {
     try {
-      const resp = await fetch('/api/packets?limit=8&groupByHash=true');
+      // Single bulk fetch with expand=observations — no N+1 calls
+      const resp = await fetch('/api/packets?limit=8&expand=observations');
       const data = await resp.json();
       const groups = (data.packets || []).reverse();
 
-      // Fetch all observations first, then stagger rendering
-      const allGroups = [];
-      for (let i = 0; i < groups.length; i++) {
-        const group = groups[i];
-        let observations = [];
-        try {
-          const detail = await fetch('/api/packets/' + encodeURIComponent(group.hash));
-          const detailData = await detail.json();
-          observations = detailData.observations || [];
-        } catch {}
+      const allGroups = groups.map((group) => {
+        const observations = group.observations || [];
 
         const livePackets = observations.map(obs => {
           const livePkt = dbPacketToLive(Object.assign({}, group, obs, {
@@ -1575,8 +1723,8 @@
         }
 
         livePackets.forEach(lp => VCR.buffer.push({ ts: lp._ts, pkt: lp }));
-        allGroups.push(livePackets);
-      }
+        return livePackets;
+      });
 
       // Render with real timing gaps between packets
       // Sort by earliest timestamp
@@ -1664,7 +1812,7 @@
       for (const fp of packets) {
         let fpHops = [];
         if (fp.path_json) {
-          try { fpHops = typeof fp.path_json === 'string' ? JSON.parse(fp.path_json) : fp.path_json; } catch {}
+          try { fpHops = getParsedPath(fp); } catch {}
         } else if (fp.decoded?.path?.hops) {
           fpHops = fp.decoded.path.hops;
         }
@@ -1701,14 +1849,14 @@
       var qp = qd.payload || {};
       var hops;
       if (qpkt.path_json) {
-        try { hops = typeof qpkt.path_json === 'string' ? JSON.parse(qpkt.path_json) : qpkt.path_json; } catch (e) { hops = qd.path?.hops || []; }
+        try { hops = getParsedPath(qpkt); } catch (e) { hops = qd.path?.hops || []; }
       } else {
         hops = qd.path?.hops || [];
       }
       var pathKey = hops.join(',');
       if (seenPathKeys.has(pathKey)) continue;
       seenPathKeys.add(pathKey);
-      var hopPositions = resolveHopPositions(hops, qp);
+      var hopPositions = resolveHopPositions(hops, qp, window.getResolvedPath ? getResolvedPath(qpkt) : null);
       if (hopPositions.length >= 2) {
         allPaths.push({ hopPositions: hopPositions, raw: qpkt.raw || first.raw });
       } else if (hopPositions.length === 1) {
@@ -1745,15 +1893,29 @@
     }
   }
 
-  function resolveHopPositions(hops, payload) {
-    // Delegate to shared HopResolver (from hop-resolver.js) instead of reimplementing
-    const originLat = payload.lat != null && !(payload.lat === 0 && payload.lon === 0) ? payload.lat : null;
-    const originLon = payload.lon != null && !(payload.lon === 0 && payload.lon === 0) ? payload.lon : null;
+  function resolveHopPositions(hops, payload, resolvedPath) {
+    // Prefer server-side resolved_path when available
+    var resolvedMap;
+    if (resolvedPath && resolvedPath.length === hops.length && window.HopResolver && HopResolver.ready()) {
+      resolvedMap = HopResolver.resolveFromServer(hops, resolvedPath);
+      // Fill in any null entries from client-side fallback, preserving sender GPS context
+      var nullHops = hops.filter(function(h, i) { return !resolvedPath[i] && !resolvedMap[h]; });
+      if (nullHops.length) {
+        const originLat = payload.lat != null && !(payload.lat === 0 && payload.lon === 0) ? payload.lat : null;
+        const originLon = payload.lon != null && !(payload.lon === 0 && payload.lon === 0) ? payload.lon : null;
+        var fallback = HopResolver.resolve(nullHops, originLat, originLon, null, null, null);
+        for (var k in fallback) resolvedMap[k] = fallback[k];
+      }
+    } else {
+      // Delegate to shared HopResolver (from hop-resolver.js) instead of reimplementing
+      const originLat = payload.lat != null && !(payload.lat === 0 && payload.lon === 0) ? payload.lat : null;
+      const originLon = payload.lon != null && !(payload.lon === 0 && payload.lon === 0) ? payload.lon : null;
 
-    // Use HopResolver if available and initialized, otherwise fall back to simple lookup
-    const resolvedMap = (window.HopResolver && HopResolver.ready())
-      ? HopResolver.resolve(hops, originLat, originLon, null, null, null)
-      : {};
+      // Use HopResolver if available and initialized, otherwise fall back to simple lookup
+      resolvedMap = (window.HopResolver && HopResolver.ready())
+        ? HopResolver.resolve(hops, originLat, originLon, null, null, null)
+        : {};
+    }
 
     // Convert HopResolver's map format to the array format live.js expects: {key, pos, name, known}
     const raw = hops.map(hop => {
@@ -1802,6 +1964,7 @@
 
   function animatePath(hopPositions, typeName, color, rawHex, onHop) {
     if (!animLayer || !pathsLayer) return;
+    if (activeAnims >= MAX_CONCURRENT_ANIMS) return;
     activeAnims++;
     document.getElementById('liveAnimCount').textContent = activeAnims;
     let hopIndex = 0;
@@ -1809,9 +1972,11 @@
     function nextHop() {
       if (hopIndex >= hopPositions.length) {
         activeAnims = Math.max(0, activeAnims - 1);
-        document.getElementById('liveAnimCount').textContent = activeAnims;
+        const countEl = document.getElementById('liveAnimCount');
+        if (countEl) countEl.textContent = activeAnims;
         return;
       }
+      if (!animLayer) return;
       // Audio hook: notify per-hop callback
       if (onHop) try { onHop(hopIndex, hopPositions.length, hopPositions[hopIndex]); } catch (e) {}
       const hp = hopPositions[hopIndex];
@@ -1823,12 +1988,22 @@
             radius: 3, fillColor: '#94a3b8', fillOpacity: 0.35, color: '#94a3b8', weight: 1, opacity: 0.5
           }).addTo(animLayer);
           let pulseUp = true;
-          const pulseTimer = setInterval(() => {
-            if (!animLayer.hasLayer(ghost)) { clearInterval(pulseTimer); return; }
-            ghost.setStyle({ fillOpacity: pulseUp ? 0.6 : 0.25, opacity: pulseUp ? 0.7 : 0.4 });
-            pulseUp = !pulseUp;
-          }, 600);
-          setTimeout(() => { clearInterval(pulseTimer); if (animLayer.hasLayer(ghost)) animLayer.removeLayer(ghost); }, 3000);
+          let lastPulseTime = performance.now();
+          const pulseExpiry = lastPulseTime + 3000;
+          function ghostPulse(now) {
+            if (!animLayer || !animLayer.hasLayer(ghost)) return;
+            if (now >= pulseExpiry) {
+              if (animLayer && animLayer.hasLayer(ghost)) animLayer.removeLayer(ghost);
+              return;
+            }
+            if (now - lastPulseTime >= 600) {
+              lastPulseTime = now;
+              ghost.setStyle({ fillOpacity: pulseUp ? 0.6 : 0.25, opacity: pulseUp ? 0.7 : 0.4 });
+              pulseUp = !pulseUp;
+            }
+            requestAnimationFrame(ghostPulse);
+          }
+          requestAnimationFrame(ghostPulse);
         }
       } else {
         pulseNode(hp.key, hp.pos, typeName);
@@ -1872,20 +2047,31 @@
     }).addTo(animLayer);
 
     let r = 2, op = 0.9;
-    const iv = setInterval(() => {
-      r += 1.5; op -= 0.03;
-      if (op <= 0) {
-        clearInterval(iv);
+    let lastPulse = performance.now();
+    const pulseStart = lastPulse;
+    function animatePulse(now) {
+      if (!animLayer) return;
+      if (now - pulseStart > 2000) {
         try { animLayer.removeLayer(ring); } catch {}
         return;
       }
-      try {
-        ring.setRadius(r);
-        ring.setStyle({ opacity: op, weight: Math.max(0.3, 3 - r * 0.04) });
-      } catch { clearInterval(iv); }
-    }, 26);
-    // Safety cleanup — never let a ring live longer than 2s
-    setTimeout(() => { clearInterval(iv); try { animLayer.removeLayer(ring); } catch {} }, 2000);
+      const elapsed = now - lastPulse;
+      if (elapsed >= 26) {
+        const ticks = Math.min(Math.floor(elapsed / 26), 4);
+        r += 1.5 * ticks; op -= 0.03 * ticks;
+        lastPulse = now;
+        if (op <= 0) {
+          try { animLayer.removeLayer(ring); } catch {}
+          return;
+        }
+        try {
+          ring.setRadius(r);
+          ring.setStyle({ opacity: op, weight: Math.max(0.3, 3 - r * 0.04) });
+        } catch { return; }
+      }
+      requestAnimationFrame(animatePulse);
+    }
+    requestAnimationFrame(animatePulse);
 
     const baseColor = marker._baseColor || '#6b7280';
     const baseSize = marker._baseSize || 6;
@@ -2109,6 +2295,10 @@
     const startTime = performance.now();
 
     function tick(now) {
+      if (!animLayer || !pathsLayer) {
+        if (onComplete) onComplete();
+        return;
+      }
       const elapsed = now - startTime;
       const t = Math.min(1, elapsed / DURATION_MS);
       const lat = from[0] + (to[0] - from[0]) * t;
@@ -2153,6 +2343,11 @@
         // Fade out
         const fadeStart = performance.now();
         function fadeOut(now) {
+          if (!animLayer || !pathsLayer) {
+            charMarkers.length = 0;
+            if (onComplete) onComplete();
+            return;
+          }
           const ft = Math.min(1, (now - fadeStart) / 300);
           if (ft >= 1) {
             for (const cm of charMarkers) try { animLayer.removeLayer(cm.marker); } catch {}
@@ -2198,43 +2393,66 @@
       radius: 3.5, fillColor: '#fff', fillOpacity: 1, color: color, weight: 1.5
     }).addTo(animLayer);
 
-    const interval = setInterval(() => {
-      step++;
-      const lat = from[0] + latStep * step;
-      const lon = from[1] + lonStep * step;
-      currentCoords.push([lat, lon]);
-      line.setLatLngs(currentCoords);
-      contrail.setLatLngs(currentCoords);
-      dot.setLatLng([lat, lon]);
-
-      if (step >= steps) {
-        clearInterval(interval);
-        if (animLayer) animLayer.removeLayer(dot);
-
-        recentPaths.push({ line, glowLine: contrail, time: Date.now() });
-        while (recentPaths.length > 5) {
-          const old = recentPaths.shift();
-          if (pathsLayer) { pathsLayer.removeLayer(old.line); pathsLayer.removeLayer(old.glowLine); }
-        }
-
-        setTimeout(() => {
-          let fadeOp = mainOpacity;
-          const fi = setInterval(() => {
-            fadeOp -= 0.1;
-            if (fadeOp <= 0) {
-              clearInterval(fi);
-              if (pathsLayer) { pathsLayer.removeLayer(line); pathsLayer.removeLayer(contrail); }
-              recentPaths = recentPaths.filter(p => p.line !== line);
-            } else {
-              line.setStyle({ opacity: fadeOp });
-              contrail.setStyle({ opacity: fadeOp * 0.15 });
-            }
-          }, 52);
-        }, 800);
-
+    let lastStep = performance.now();
+    function animateLine(now) {
+      if (!animLayer || !pathsLayer) {
         if (onComplete) onComplete();
+        return;
       }
-    }, 33);
+      const elapsed = now - lastStep;
+      if (elapsed >= 33) {
+        const ticks = Math.min(Math.floor(elapsed / 33), 4);
+        lastStep = now;
+        for (let t = 0; t < ticks && step < steps; t++) {
+          step++;
+          const lat = from[0] + latStep * step;
+          const lon = from[1] + lonStep * step;
+          currentCoords.push([lat, lon]);
+        }
+        const lastPt = currentCoords[currentCoords.length - 1];
+        line.setLatLngs(currentCoords);
+        contrail.setLatLngs(currentCoords);
+        dot.setLatLng(lastPt);
+
+        if (step >= steps) {
+          if (animLayer) animLayer.removeLayer(dot);
+
+          recentPaths.push({ line, glowLine: contrail, time: Date.now() });
+          while (recentPaths.length > 5) {
+            const old = recentPaths.shift();
+            if (pathsLayer) { pathsLayer.removeLayer(old.line); pathsLayer.removeLayer(old.glowLine); }
+          }
+
+          setTimeout(() => {
+            let fadeOp = mainOpacity;
+            let lastFade = performance.now();
+            function animateFade(now) {
+              if (!pathsLayer) return;
+              const fadeElapsed = now - lastFade;
+              if (fadeElapsed >= 52) {
+                const fadeTicks = Math.min(Math.floor(fadeElapsed / 52), 4);
+                lastFade = now;
+                fadeOp -= 0.1 * fadeTicks;
+                if (fadeOp <= 0) {
+                  if (pathsLayer) { pathsLayer.removeLayer(line); pathsLayer.removeLayer(contrail); }
+                  recentPaths = recentPaths.filter(p => p.line !== line);
+                  return;
+                }
+                line.setStyle({ opacity: fadeOp });
+                contrail.setStyle({ opacity: fadeOp * 0.15 });
+              }
+              requestAnimationFrame(animateFade);
+            }
+            requestAnimationFrame(animateFade);
+          }, 800);
+
+          if (onComplete) onComplete();
+          return;
+        }
+      }
+      requestAnimationFrame(animateLine);
+    }
+    requestAnimationFrame(animateLine);
   }
 
   function showHeatMap() {
@@ -2281,7 +2499,7 @@
     item.innerHTML = `
       <span class="feed-icon" style="color:${color}">${icon}</span>
       <span class="feed-type" style="color:${color}">${typeName}</span>
-      ${hopStr}${obsBadge}
+      ${transportBadge(pkt.route_type)}${hopStr}${obsBadge}
       <span class="feed-text">${escapeHtml(preview)}</span>
       <span class="feed-time">${formatLiveTimestampHtml(pkt._ts || Date.now())}</span>
     `;
@@ -2349,7 +2567,7 @@
     item.innerHTML = `
       <span class="feed-icon" style="color:${color}">${icon}</span>
       <span class="feed-type" style="color:${color}">${typeName}</span>
-      ${hopStr}${obsBadge}
+      ${transportBadge(pkt.route_type)}${hopStr}${obsBadge}
       <span class="feed-text">${escapeHtml(preview)}</span>
       <span class="feed-time">${formatLiveTimestampHtml(pkt._ts || Date.now())}</span>
     `;
@@ -2427,6 +2645,7 @@
     if (_lcdClockInterval) { clearInterval(_lcdClockInterval); _lcdClockInterval = null; }
     if (_rateCounterInterval) { clearInterval(_rateCounterInterval); _rateCounterInterval = null; }
     if (_pruneInterval) { clearInterval(_pruneInterval); _pruneInterval = null; }
+    if (_affinityInterval) { clearInterval(_affinityInterval); _affinityInterval = null; }
     if (ws) { ws.onclose = null; ws.close(); ws = null; }
     if (map) { map.remove(); map = null; }
     if (_onResize) {
@@ -2459,7 +2678,7 @@
     packetCount = 0; activeAnims = 0;
     nodeActivity = {}; pktTimestamps = [];
     feedDedup.clear();
-    VCR.buffer = []; VCR.playhead = -1; VCR.mode = 'LIVE'; VCR.missedCount = 0; VCR.speed = 1;
+    VCR.buffer = []; VCR.playhead = -1; VCR.mode = 'LIVE'; VCR.missedCount = 0; VCR.speed = 1; VCR.replayGen = 0;
   }
 
   let _themeRefreshHandler = null;

public/map.js

@@ -9,10 +9,14 @@
   let nodes = [];
   let targetNodeKey = null;
   let observers = [];
-  let filters = { repeater: true, companion: true, room: true, sensor: true, observer: true, lastHeard: '30d', neighbors: false, clusters: false, hashLabels: localStorage.getItem('meshcore-map-hash-labels') !== 'false', statusFilter: localStorage.getItem('meshcore-map-status-filter') || 'all' };
+  let filters = { repeater: true, companion: true, room: true, sensor: true, observer: true, lastHeard: '30d', neighbors: false, clusters: false, hashLabels: localStorage.getItem('meshcore-map-hash-labels') !== 'false', statusFilter: localStorage.getItem('meshcore-map-status-filter') || 'all', byteSize: localStorage.getItem('meshcore-map-byte-filter') || 'all' };
+  let selectedReferenceNode = null;  // pubkey of the reference node for neighbor filtering
+  let neighborPubkeys = null;        // Set of pubkeys that are direct neighbors of selected node
   let wsHandler = null;
   let heatLayer = null;
   let geoFilterLayer = null;
+  let affinityLayer = null;
+  let affinityData = null;
   let userHasMoved = false;
   let controlsCollapsed = false;
 
@@ -90,12 +94,21 @@
             <legend class="mc-label">Node Types</legend>
             <div id="mcRoleChecks"></div>
           </fieldset>
+          <fieldset class="mc-section">
+            <legend class="mc-label">Byte Size</legend>
+            <div class="filter-group" id="mcByteFilter">
+              <button class="btn ${filters.byteSize==='all'?'active':''}" data-byte="all">All</button>
+              <button class="btn ${filters.byteSize==='1'?'active':''}" data-byte="1">1-byte</button>
+              <button class="btn ${filters.byteSize==='2'?'active':''}" data-byte="2">2-byte</button>
+              <button class="btn ${filters.byteSize==='3'?'active':''}" data-byte="3">3-byte</button>
+            </div>
+          </fieldset>
           <fieldset class="mc-section">
             <legend class="mc-label">Display</legend>
             <label for="mcClusters"><input type="checkbox" id="mcClusters"> Show clusters</label>
             <label for="mcHeatmap"><input type="checkbox" id="mcHeatmap"> Heat map</label>
             <label for="mcHashLabels"><input type="checkbox" id="mcHashLabels"> Hash prefix labels</label>
-            <label for="mcGeoFilter" id="mcGeoFilterLabel" style="display:none"><input type="checkbox" id="mcGeoFilter"> Geo filter area</label>
+            <label id="mcGeoFilterLabel" for="mcGeoFilter" style="display:none"><input type="checkbox" id="mcGeoFilter"> Mesh live area</label>
           </fieldset>
           <fieldset class="mc-section">
             <legend class="mc-label">Status</legend>
@@ -108,6 +121,9 @@
           <fieldset class="mc-section">
             <legend class="mc-label">Filters</legend>
             <label for="mcNeighbors"><input type="checkbox" id="mcNeighbors"> Show direct neighbors</label>
+            <div id="mcNeighborRef" style="display:none;font-size:11px;color:var(--text-muted);margin-top:2px;padding-left:20px;">Ref: <span id="mcNeighborRefName">—</span></div>
+            <div id="mcNeighborHint" style="display:none;font-size:11px;color:var(--text-muted);margin-top:2px;padding-left:20px;">Click a node marker to set the reference node</div>
+            <label id="mcAffinityDebugLabel" for="mcAffinityDebug" style="display:none"><input type="checkbox" id="mcAffinityDebug"> 🔍 Affinity Debug</label>
           </fieldset>
           <fieldset class="mc-section">
             <legend class="mc-label">Last Heard</legend>
@@ -174,11 +190,17 @@
     });
 
     map.on('zoomend', () => {
-      if (!_renderingMarkers) renderMarkers();
+      clearTimeout(_zoomResizeTimer);
+      _zoomResizeTimer = setTimeout(() => {
+        if (!_renderingMarkers) _repositionMarkers();
+      }, 150);
     });
 
     map.on('resize', () => {
-      if (!_renderingMarkers) renderMarkers();
+      clearTimeout(_zoomResizeTimer);
+      _zoomResizeTimer = setTimeout(() => {
+        if (!_renderingMarkers) _repositionMarkers();
+      }, 150);
     });
 
     markerLayer = L.layerGroup().addTo(map);
@@ -207,7 +229,35 @@
     const heatEl = document.getElementById('mcHeatmap');
     if (localStorage.getItem('meshcore-map-heatmap') === 'true') { heatEl.checked = true; }
     heatEl.addEventListener('change', e => { localStorage.setItem('meshcore-map-heatmap', e.target.checked); toggleHeatmap(e.target.checked); });
-    document.getElementById('mcNeighbors').addEventListener('change', e => { filters.neighbors = e.target.checked; renderMarkers(); });
+    document.getElementById('mcNeighbors').addEventListener('change', e => {
+      filters.neighbors = e.target.checked;
+      const hintEl = document.getElementById('mcNeighborHint');
+      const refEl = document.getElementById('mcNeighborRef');
+      if (e.target.checked && !selectedReferenceNode) {
+        hintEl.style.display = 'block';
+        refEl.style.display = 'none';
+      } else {
+        hintEl.style.display = 'none';
+        refEl.style.display = selectedReferenceNode ? 'block' : 'none';
+      }
+      renderMarkers();
+    });
+
+    // Affinity Debug overlay toggle — shown only when debugAffinity config is on or localStorage override
+    (function initAffinityDebug() {
+      var label = document.getElementById('mcAffinityDebugLabel');
+      var show = (window.CLIENT_CONFIG && window.CLIENT_CONFIG.debugAffinity) || localStorage.getItem('meshcore-affinity-debug') === 'true';
+      if (show && label) label.style.display = '';
+      var cb = document.getElementById('mcAffinityDebug');
+      if (!cb) return;
+      cb.addEventListener('change', function (e) {
+        if (e.target.checked) {
+          loadAffinityDebugOverlay();
+        } else {
+          clearAffinityOverlay();
+        }
+      });
+    })();
 
     // Hash Labels toggle
     const hashLabelEl = document.getElementById('mcHashLabels');
@@ -227,8 +277,60 @@
       });
     });
 
+    // Byte size filter buttons
+    document.querySelectorAll('#mcByteFilter .btn').forEach(btn => {
+      btn.addEventListener('click', () => {
+        filters.byteSize = btn.dataset.byte;
+        localStorage.setItem('meshcore-map-byte-filter', filters.byteSize);
+        document.querySelectorAll('#mcByteFilter .btn').forEach(b => b.classList.toggle('active', b.dataset.byte === filters.byteSize));
+        renderMarkers();
+      });
+    });
+
     // Geo filter overlay
-    initGeoFilterOverlay(map, 'mcGeoFilter', 'mcGeoFilterLabel').then(function (layer) { geoFilterLayer = layer; });
+    (async function () {
+      try {
+        const gf = await api('/config/geo-filter', { ttl: 3600 });
+        if (!gf || !gf.polygon || gf.polygon.length < 3) return;
+        const geoColor = getComputedStyle(document.documentElement).getPropertyValue('--geo-filter-color').trim() || '#3b82f6';
+        const latlngs = gf.polygon.map(function (p) { return [p[0], p[1]]; });
+        const innerPoly = L.polygon(latlngs, {
+          color: geoColor, weight: 2, opacity: 0.8,
+          fillColor: geoColor, fillOpacity: 0.08
+        });
+        // Approximate buffer zone — expand each vertex outward from centroid by bufferKm
+        const bufferPoly = gf.bufferKm > 0 ? (function () {
+          let cLat = 0, cLon = 0;
+          gf.polygon.forEach(function (p) { cLat += p[0]; cLon += p[1]; });
+          cLat /= gf.polygon.length; cLon /= gf.polygon.length;
+          const cosLat = Math.cos(cLat * Math.PI / 180);
+          const outer = gf.polygon.map(function (p) {
+            const dLatM = (p[0] - cLat) * 111000;
+            const dLonM = (p[1] - cLon) * 111000 * cosLat;
+            const dist = Math.sqrt(dLatM * dLatM + dLonM * dLonM);
+            if (dist === 0) return [p[0], p[1]];
+            const scale = (gf.bufferKm * 1000) / dist;
+            return [p[0] + dLatM * scale / 111000, p[1] + dLonM * scale / (111000 * cosLat)];
+          });
+          return L.polygon(outer, {
+            color: geoColor, weight: 1.5, opacity: 0.4, dashArray: '6 4',
+            fillColor: geoColor, fillOpacity: 0.04
+          });
+        })() : null;
+        geoFilterLayer = L.layerGroup(bufferPoly ? [bufferPoly, innerPoly] : [innerPoly]);
+        const label = document.getElementById('mcGeoFilterLabel');
+        if (label) label.style.display = '';
+        const el = document.getElementById('mcGeoFilter');
+        if (el) {
+          const saved = localStorage.getItem('meshcore-map-geo-filter');
+          if (saved === 'true') { el.checked = true; geoFilterLayer.addTo(map); }
+          el.addEventListener('change', function (e) {
+            localStorage.setItem('meshcore-map-geo-filter', e.target.checked);
+            if (e.target.checked) { geoFilterLayer.addTo(map); } else { map.removeLayer(geoFilterLayer); }
+          });
+        }
+      } catch (e) { /* no geo filter configured */ }
+    })();
 
     // WS for live advert updates
     wsHandler = debouncedOnWS(function (msgs) {
@@ -535,6 +637,8 @@
 
   var _renderingMarkers = false;
   var _lastDeconflictZoom = null;
+  var _currentMarkerData = []; // stored marker data for zoom-only repositioning
+  var _zoomResizeTimer = null;
 
   function deconflictLabels(markers, mapRef) {
     const placed = [];
@@ -585,6 +689,62 @@
     }
   }
 
+  /**
+   * Create, update, or remove the offset indicator (dashed line + dot at true GPS position)
+   * for a deconflicted marker. Shared by _renderMarkersInner and _repositionMarkers.
+   * @param {Object} m - marker data object with latLng, adjustedLatLng, offset, _leafletLine, _leafletDot
+   * @param {L.LayerGroup} layer - layer group to add/remove indicators from
+   */
+  function _updateOffsetIndicator(m, layer) {
+    var pos = m.adjustedLatLng || m.latLng;
+    var redColor = getComputedStyle(document.documentElement).getPropertyValue('--status-red').trim() || '#ef4444';
+
+    if (m.offset > 10) {
+      // Line from true position to adjusted position
+      if (m._leafletLine) {
+        m._leafletLine.setLatLngs([m.latLng, pos]);
+      } else {
+        m._leafletLine = L.polyline([m.latLng, pos], {
+          color: redColor, weight: 2, dashArray: '6,4', opacity: 0.85
+        });
+        layer.addLayer(m._leafletLine);
+      }
+      // Dot at true GPS position
+      if (!m._leafletDot) {
+        m._leafletDot = L.circleMarker(m.latLng, {
+          radius: 3, fillColor: redColor, fillOpacity: 0.9, stroke: true, color: '#fff', weight: 1
+        });
+        layer.addLayer(m._leafletDot);
+      }
+    } else {
+      // No offset — remove indicator if it existed
+      if (m._leafletLine) { layer.removeLayer(m._leafletLine); m._leafletLine = null; }
+      if (m._leafletDot) { layer.removeLayer(m._leafletDot); m._leafletDot = null; }
+    }
+  }
+
+  /**
+   * Reposition existing markers by re-running deconfliction at the current zoom.
+   * Avoids clearing and rebuilding all markers — eliminates flicker on zoom/resize.
+   */
+  function _repositionMarkers() {
+    if (!map || _currentMarkerData.length === 0) return;
+    map.invalidateSize({ animate: false });
+
+    // Re-run deconfliction with current zoom pixel coordinates
+    deconflictLabels(_currentMarkerData, map);
+
+    for (var i = 0; i < _currentMarkerData.length; i++) {
+      var m = _currentMarkerData[i];
+      var pos = m.adjustedLatLng || m.latLng;
+
+      // Update marker position
+      if (m._leafletMarker) m._leafletMarker.setLatLng(pos);
+
+      _updateOffsetIndicator(m, markerLayer);
+    }
+  }
+
   function renderMarkers() {
     if (_renderingMarkers) return;
     _renderingMarkers = true;
@@ -593,10 +753,16 @@
 
   function _renderMarkersInner() {
     markerLayer.clearLayers();
+    _currentMarkerData = [];
 
     const filtered = nodes.filter(n => {
       if (!n.lat || !n.lon) return false;
       if (!filters[n.role || 'companion']) return false;
+      // Byte size filter (applies only to repeaters)
+      if (filters.byteSize !== 'all' && (n.role || 'companion') === 'repeater') {
+        const hs = n.hash_size || 1;
+        if (String(hs) !== filters.byteSize) return false;
+      }
       // Status filter
       if (filters.statusFilter !== 'all') {
         const role = (n.role || 'companion').toLowerCase();
@@ -604,6 +770,11 @@
         const status = getNodeStatus(role, lastMs);
         if (status !== filters.statusFilter) return false;
       }
+      // Neighbor filter: show only the reference node and its direct neighbors
+      if (filters.neighbors && selectedReferenceNode && neighborPubkeys) {
+        const pk = n.public_key;
+        if (pk !== selectedReferenceNode && !neighborPubkeys.has(pk)) return false;
+      }
       return true;
     });
 
@@ -637,24 +808,20 @@
       deconflictLabels(allMarkers, map);
     }
 
+    // Store marker data for zoom/resize repositioning (avoids full rebuild)
+    _currentMarkerData = allMarkers;
+
     for (const m of allMarkers) {
       const pos = m.adjustedLatLng || m.latLng;
       const marker = L.marker(pos, { icon: m.icon, alt: m.alt });
       marker._nodeKey = m.node.public_key || m.node.id || null;
       marker.bindPopup(m.popupFn(), { maxWidth: 280 });
       markerLayer.addLayer(marker);
+      m._leafletMarker = marker;
+      m._leafletLine = null;
+      m._leafletDot = null;
 
-      if (m.offset > 10) {
-        const line = L.polyline([m.latLng, pos], {
-          color: getComputedStyle(document.documentElement).getPropertyValue('--status-red').trim() || '#ef4444', weight: 2, dashArray: '6,4', opacity: 0.85
-        });
-        markerLayer.addLayer(line);
-        // Small dot at true GPS position
-        const dot = L.circleMarker(m.latLng, {
-          radius: 3, fillColor: getComputedStyle(document.documentElement).getPropertyValue('--status-red').trim() || '#ef4444', fillOpacity: 0.9, stroke: true, color: '#fff', weight: 1
-        });
-        markerLayer.addLayer(dot);
-      }
+      _updateOffsetIndicator(m, markerLayer);
     }
   }
 
@@ -682,6 +849,61 @@
       </div>`;
   }
 
+  async function selectReferenceNode(pubkey, name) {
+    selectedReferenceNode = pubkey;
+    neighborPubkeys = new Set();
+    try {
+      // Use affinity-based neighbor API (server-side disambiguation) instead of
+      // client-side path walking which fails on hash collisions (#484)
+      const data = await api('/nodes/' + pubkey + '/neighbors?min_count=3');
+      for (const n of (data.neighbors || [])) {
+        if (n.pubkey) neighborPubkeys.add(n.pubkey);
+        // For ambiguous edges, include all candidates (better to show extra than miss)
+        if (n.candidates) n.candidates.forEach(function(c) { if (c.pubkey) neighborPubkeys.add(c.pubkey); });
+      }
+      // If affinity data is insufficient, fall back to client-side path walking
+      if (neighborPubkeys.size === 0) {
+        const pathData = await api('/nodes/' + pubkey + '/paths');
+        const paths = pathData.paths || [];
+        for (const p of paths) {
+          const hops = p.hops || [];
+          for (var i = 0; i < hops.length; i++) {
+            if (hops[i].pubkey === pubkey) {
+              if (i > 0 && hops[i - 1].pubkey) neighborPubkeys.add(hops[i - 1].pubkey);
+              if (i < hops.length - 1 && hops[i + 1].pubkey) neighborPubkeys.add(hops[i + 1].pubkey);
+            }
+          }
+        }
+      }
+    } catch (e) {
+      console.warn('Failed to fetch neighbors for', pubkey, ':', e);
+      neighborPubkeys = new Set();
+    }
+    // Update sidebar UI
+    const refEl = document.getElementById('mcNeighborRef');
+    const refNameEl = document.getElementById('mcNeighborRefName');
+    const hintEl = document.getElementById('mcNeighborHint');
+    if (refEl) { refEl.style.display = 'block'; }
+    if (refNameEl) { refNameEl.textContent = name || pubkey.slice(0, 8); }
+    if (hintEl) { hintEl.style.display = 'none'; }
+    // Auto-enable the neighbors filter
+    filters.neighbors = true;
+    const cb = document.getElementById('mcNeighbors');
+    if (cb) cb.checked = true;
+    renderMarkers();
+  }
+  // Event delegation for Show Neighbors links (avoids inline onclick / global function timing issues)
+  document.addEventListener('click', function(e) {
+    var link = e.target.closest('[data-show-neighbors]');
+    if (link) {
+      e.preventDefault();
+      selectReferenceNode(link.dataset.pubkey, link.dataset.name);
+    }
+  });
+  // Expose for testing
+  window._mapSelectRefNode = selectReferenceNode;
+  window._mapGetNeighborPubkeys = function() { return neighborPubkeys ? Array.from(neighborPubkeys) : []; };
+
   function buildPopup(node) {
     const key = node.public_key ? truncate(node.public_key, 16) : '—';
     const loc = (node.lat && node.lon) ? `${node.lat.toFixed(5)}, ${node.lon.toFixed(5)}` : '—';
@@ -707,7 +929,10 @@
           <dt style="color:var(--text-muted);float:left;clear:left;width:80px;padding:2px 0;">Adverts</dt>
           <dd style="margin-left:88px;padding:2px 0;">${node.advert_count || 0}</dd>
         </dl>
-        <div style="margin-top:8px;clear:both;"><a href="#/nodes/${node.public_key}" style="color:var(--accent);font-size:12px;">View Node →</a></div>
+        <div style="margin-top:8px;clear:both;">
+          <a href="#/nodes/${node.public_key}" style="color:var(--accent);font-size:12px;">View Node →</a>
+          ${node.public_key ? ` · <a href="#" data-show-neighbors data-pubkey="${escapeHtml(node.public_key)}" data-name="${escapeHtml(node.name || 'Unknown')}" style="color:var(--accent);font-size:12px;">Show Neighbors</a>` : ''}
+        </div>
       </div>`;
   }
 
@@ -730,9 +955,14 @@
       map = null;
     }
     markerLayer = null;
+    _currentMarkerData = [];
     routeLayer = null;
     if (heatLayer) { heatLayer = null; }
     geoFilterLayer = null;
+    selectedReferenceNode = null;
+    neighborPubkeys = null;
+    delete window._mapSelectRefNode;
+    delete window._mapGetNeighborPubkeys;
   }
 
   function toggleHeatmap(on) {
@@ -769,6 +999,95 @@
 
   let _themeRefreshHandler = null;
 
+  // ─── Affinity Debug Overlay ────────────────────────────────────────────────
+  function clearAffinityOverlay() {
+    if (affinityLayer) { map.removeLayer(affinityLayer); affinityLayer = null; }
+    affinityData = null;
+  }
+
+  function loadAffinityDebugOverlay() {
+    clearAffinityOverlay();
+    // Fetch debug data — requires API key stored in localStorage
+    var apiKey = localStorage.getItem('meshcore-api-key') || '';
+    fetch('/api/debug/affinity', { headers: { 'X-API-Key': apiKey } })
+      .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); })
+      .then(function (data) {
+        affinityData = data;
+        renderAffinityOverlay();
+      })
+      .catch(function (err) {
+        console.warn('[affinity-debug] Failed to load:', err);
+        var cb = document.getElementById('mcAffinityDebug');
+        if (cb) cb.checked = false;
+      });
+  }
+
+  function renderAffinityOverlay() {
+    if (!affinityData || !map) return;
+    clearAffinityOverlay();
+    affinityLayer = L.layerGroup();
+
+    // Build node position lookup from current markers
+    var nodePos = {};
+    nodes.forEach(function (n) {
+      if (n.latitude && n.longitude) {
+        nodePos[n.public_key.toLowerCase()] = [n.latitude, n.longitude];
+      }
+    });
+
+    var edges = affinityData.edges || [];
+    edges.forEach(function (e) {
+      var posA = nodePos[e.nodeA];
+      var posB = e.nodeB ? nodePos[e.nodeB] : null;
+
+      if (!posA) return;
+
+      // Unresolved prefix — show ❓ marker near nodeA
+      if (e.unresolved || (!posB && e.ambiguous)) {
+        if (posA) {
+          var marker = L.marker([posA[0] + 0.001, posA[1] + 0.001], {
+            icon: L.divIcon({ html: '❓', className: 'affinity-unresolved', iconSize: [20, 20] })
+          });
+          marker.bindPopup('<b>Unresolved prefix:</b> ' + escapeHtml(e.prefix) + '<br>Observations: ' + e.weight);
+          affinityLayer.addLayer(marker);
+        }
+        return;
+      }
+
+      if (!posB) return;
+
+      // Color by confidence
+      var color = '#ef4444'; // red — ambiguous
+      var score = e.score || 0;
+      if (score >= 0.6) color = '#22c55e'; // green — high
+      else if (score >= 0.3) color = '#eab308'; // yellow — medium
+
+      // Thickness proportional to weight, clamped 1-5px
+      var weight = Math.max(1, Math.min(5, Math.round((e.weight || 1) / 20)));
+
+      var line = L.polyline([posA, posB], {
+        color: color,
+        weight: weight,
+        opacity: 0.7,
+        dashArray: e.ambiguous ? '5,5' : null
+      });
+
+      var popup = '<b>Affinity Edge</b><br>' +
+        escapeHtml(e.nodeAName || e.nodeA.substring(0, 8)) + ' ↔ ' + escapeHtml(e.nodeBName || e.nodeB.substring(0, 8)) + '<br>' +
+        'Observations: ' + e.observationCount + '<br>' +
+        'Score: ' + (e.score || 0).toFixed(3) + '<br>' +
+        'Last seen: ' + escapeHtml(e.lastSeen) + '<br>' +
+        'Observers: ' + escapeHtml((e.observers || []).join(', '));
+      if (e.avgSnr != null) popup += '<br>Avg SNR: ' + e.avgSnr.toFixed(1) + ' dB';
+
+      line.bindPopup(popup);
+      affinityLayer.addLayer(line);
+    });
+
+    affinityLayer.addTo(map);
+  }
+  // ─── End Affinity Debug ────────────────────────────────────────────────────
+
   registerPage('map', {
     init: function(app, routeParam) {
       _themeRefreshHandler = () => { if (markerLayer) renderMarkers(); };

public/node-analytics.js

@@ -51,7 +51,7 @@
     const nodeName = escapeHtml(n.name || n.public_key.slice(0, 12));
 
     container.innerHTML = `
-      <div style="max-width:1000px;margin:0 auto;padding:12px 16px;height:100%;overflow-y:auto">
+      <div style="max-width:1000px;margin:0 auto;padding:12px 16px">
         <div style="margin-bottom:12px">
           <a href="#/nodes/${encodeURIComponent(n.public_key)}" style="color:var(--accent);text-decoration:none;font-size:12px">← Back to ${nodeName}</a>
           <h2 style="margin:4px 0 2px;font-size:18px">📊 ${nodeName} — Analytics</h2>

public/nodes.js

@@ -175,6 +175,114 @@
     return `<div style="font-size:11px;color:var(--text-muted);margin:-2px 0 6px;padding:6px 10px;background:var(--surface-2);border-radius:4px;border-left:3px solid var(--status-yellow)">Adverts show varying hash sizes (<strong>${sizes.join('-byte, ')}-byte</strong>). This is a <a href="https://github.com/meshcore-dev/MeshCore/commit/fcfdc5f" target="_blank" style="color:var(--accent)">known bug</a> where automatic adverts ignore the configured multibyte path setting. Fixed in <a href="https://github.com/meshcore-dev/MeshCore/releases/tag/repeater-v1.14.1" target="_blank" style="color:var(--accent)">repeater v1.14.1</a>.</div>`;
   }
 
+  // ─── Neighbor section helpers ───────────────────────────────────────────────
+
+  // Cache: pubkey → { data, ts }
+  var _neighborCache = {};
+
+  function getConfidenceIndicator(entry) {
+    if (entry.ambiguous) return { icon: '⚠️', label: 'AMBIGUOUS', cls: 'confidence-ambiguous' };
+    if (entry.count <= 1) return { icon: '🔴', label: 'LOW', cls: 'confidence-low' };
+    if (entry.score >= 0.5 && entry.count >= 3) return { icon: '🟢', label: 'HIGH', cls: 'confidence-high' };
+    return { icon: '🟡', label: 'MEDIUM', cls: 'confidence-medium' };
+  }
+
+  function renderNeighborRows(neighbors, limit) {
+    var sorted = neighbors.slice().sort(function(a, b) {
+      return (b.score || b.affinity || 0) - (a.score || a.affinity || 0);
+    });
+    var items = limit ? sorted.slice(0, limit) : sorted;
+    return items.map(function(nb) {
+      var conf = getConfidenceIndicator(nb);
+      var name = nb.name || (nb.prefix + '… (unknown)');
+      var nameHtml = nb.pubkey
+        ? '<a href="#/nodes/' + encodeURIComponent(nb.pubkey) + '">' + escapeHtml(name) + '</a>'
+        : '<span class="text-muted">' + escapeHtml(name) + '</span>';
+      var role = nb.role || '—';
+      var roleBadge = nb.role
+        ? '<span class="badge" style="background:' + (ROLE_COLORS[nb.role] || 'var(--surface-2)') + ';color:#fff;font-size:10px">' + escapeHtml(role) + '</span>'
+        : '<span class="text-muted">—</span>';
+      var scoreTitle = 'Observations: ' + nb.count;
+      if (nb.avg_snr != null) scoreTitle += ' · Avg SNR: ' + Number(nb.avg_snr).toFixed(1) + ' dB';
+      var showOnMap = nb.pubkey
+        ? ' <button class="btn-link neighbor-show-map" data-pubkey="' + escapeHtml(nb.pubkey) + '" style="font-size:11px;padding:1px 6px;white-space:nowrap">📍 Map</button>'
+        : '';
+      return '<tr>' +
+        '<td style="font-weight:600">' + nameHtml + '</td>' +
+        '<td>' + roleBadge + '</td>' +
+        '<td title="' + escapeHtml(scoreTitle) + '">' + Number(nb.score).toFixed(2) + '</td>' +
+        '<td>' + nb.count + '</td>' +
+        '<td>' + renderNodeTimestampHtml(nb.last_seen) + '</td>' +
+        '<td><span title="' + conf.label + '">' + conf.icon + '</span></td>' +
+        '<td style="text-align:right">' + showOnMap + '</td>' +
+        '</tr>';
+    }).join('');
+  }
+
+  function renderNeighborTable(neighbors, limit) {
+    return '<table class="data-table" style="font-size:12px">' +
+      '<thead><tr><th>Neighbor</th><th>Role</th><th>Score</th><th>Obs</th><th>Last Seen</th><th>Conf</th><th></th></tr></thead>' +
+      '<tbody>' + renderNeighborRows(neighbors, limit) + '</tbody></table>';
+  }
+
+  function fetchAndRenderNeighbors(pubkey, containerId, opts) {
+    opts = opts || {};
+    var limit = opts.limit || 0;
+    var headerSelector = opts.headerSelector;
+    var viewAllPubkey = opts.viewAllPubkey;
+
+    // Always set spinner as initial DOM state (synchronous) so tests can observe it
+    var spinnerEl = document.getElementById(containerId);
+    if (spinnerEl) spinnerEl.innerHTML = '<div class="text-muted" style="padding:8px"><span class="spinner"></span> Loading neighbors…</div>';
+
+    // Check cache
+    var cached = _neighborCache[pubkey];
+    if (cached && (Date.now() - cached.ts < 300000)) { // 5 min cache
+      renderNeighborData(cached.data, containerId, limit, headerSelector, viewAllPubkey);
+      return;
+    }
+
+    api('/nodes/' + encodeURIComponent(pubkey) + '/neighbors', { ttl: CLIENT_TTL.nodeDetail }).then(function(data) {
+      _neighborCache[pubkey] = { data: data, ts: Date.now() };
+      renderNeighborData(data, containerId, limit, headerSelector, viewAllPubkey);
+    }).catch(function() {
+      var el = document.getElementById(containerId);
+      if (el) el.innerHTML = '<div class="text-muted" style="padding:8px">Could not load neighbor data</div>';
+    });
+  }
+
+  function renderNeighborData(data, containerId, limit, headerSelector, viewAllPubkey) {
+    var el = document.getElementById(containerId);
+    if (!el) return;
+    if (!data || !data.neighbors || !data.neighbors.length) {
+      el.innerHTML = '<div class="text-muted" style="padding:8px">No neighbor data available yet. Neighbor relationships are built from observed packet paths over time.</div>';
+      if (headerSelector) {
+        var h = document.querySelector(headerSelector);
+        if (h) h.textContent = 'Neighbors (0)';
+      }
+      return;
+    }
+    if (headerSelector) {
+      var h = document.querySelector(headerSelector);
+      if (h) h.textContent = 'Neighbors (' + data.neighbors.length + ')';
+    }
+    var html = renderNeighborTable(data.neighbors, limit);
+    if (limit && data.neighbors.length > limit && viewAllPubkey) {
+      html += '<div style="margin-top:6px;text-align:right"><a href="#/nodes/' + encodeURIComponent(viewAllPubkey) + '?section=node-neighbors" style="font-size:12px">View all ' + data.neighbors.length + ' neighbors →</a></div>';
+    }
+    el.innerHTML = html;
+
+    // Wire up "Show on Map" buttons via event delegation
+    el.addEventListener('click', function(e) {
+      var btn = e.target.closest('.neighbor-show-map');
+      if (!btn) return;
+      var pk = btn.getAttribute('data-pubkey');
+      if (pk) location.hash = '#/map?node=' + encodeURIComponent(pk);
+    });
+  }
+
+  // ─── End neighbor helpers ─────────────────────────────────────────────────
+
   let directNode = null; // set when navigating directly to #/nodes/:pubkey
 
   let regionChangeHandler = null;
@@ -228,21 +336,61 @@
     loadNodes();
     // Auto-refresh when ADVERT packets arrive via WebSocket (fixes #131)
     wsHandler = debouncedOnWS(function (msgs) {
-      if (msgs.some(isAdvertMessage)) {
-        _allNodes = null;
+      const advertMsgs = msgs.filter(isAdvertMessage);
+      if (!advertMsgs.length) return;
+
+      if (!_allNodes) {
         invalidateApiCache('/nodes');
         loadNodes(true);
+        return;
       }
+
+      let needReload = false;
+      for (const m of advertMsgs) {
+        const payload = m.data && m.data.decoded && m.data.decoded.payload;
+        const pubKey = payload && (payload.pubKey || payload.public_key);
+        if (!pubKey) { needReload = true; break; }
+
+        const existing = _allNodes.find(n => n.public_key === pubKey);
+        if (existing) {
+          if (payload.name) existing.name = payload.name;
+          if (payload.lat != null) existing.lat = payload.lat;
+          if (payload.lon != null) existing.lon = payload.lon;
+          const ts = m.data.packet && (m.data.packet.timestamp || m.data.packet.first_seen);
+          if (ts) existing.last_seen = ts;
+        } else {
+          needReload = true;
+          break;
+        }
+      }
+
+      if (needReload) {
+        _allNodes = null;
+        invalidateApiCache('/nodes');
+      }
+      loadNodes(true);
     }, 5000);
   }
 
+  /**
+   * Fetch node detail + health data in parallel.
+   * Both selectNode() and loadFullNode() need the same data —
+   * this shared helper avoids duplicating the fetch logic (fixes #391).
+   */
+  async function fetchNodeDetail(pubkey) {
+    const [nodeData, healthData] = await Promise.all([
+      api('/nodes/' + encodeURIComponent(pubkey), { ttl: CLIENT_TTL.nodeDetail }),
+      api('/nodes/' + encodeURIComponent(pubkey) + '/health', { ttl: CLIENT_TTL.nodeDetail }).catch(() => null)
+    ]);
+    nodeData.healthData = healthData;
+    return nodeData;
+  }
+
   async function loadFullNode(pubkey) {
     const body = document.getElementById('nodeFullBody');
     try {
-      const [nodeData, healthData] = await Promise.all([
-        api('/nodes/' + encodeURIComponent(pubkey), { ttl: CLIENT_TTL.nodeDetail }),
-        api('/nodes/' + encodeURIComponent(pubkey) + '/health', { ttl: CLIENT_TTL.nodeDetail }).catch(() => null)
-      ]);
+      const nodeData = await fetchNodeDetail(pubkey);
+      const healthData = nodeData.healthData;
       const n = nodeData.node;
       const adverts = (nodeData.recentAdverts || []).sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
       const title = document.querySelector('.node-full-title');
@@ -319,6 +467,18 @@
           </table>
         </div>` : ''}
 
+        <div class="node-full-card" id="node-neighbors">
+          <h4 id="fullNeighborsHeader">Neighbors</h4>
+          <div id="fullNeighborsContent"><div class="text-muted" style="padding:8px"><span class="spinner"></span> Loading neighbors…</div></div>
+        </div>
+
+        <div class="node-full-card" id="node-affinity-debug" style="display:none">
+          <h4 style="cursor:pointer" onclick="this.parentElement.querySelector('.affinity-debug-body').style.display=this.parentElement.querySelector('.affinity-debug-body').style.display==='none'?'block':'none'; this.querySelector('.toggle-icon').textContent=this.parentElement.querySelector('.affinity-debug-body').style.display==='none'?'▶':'▼'"><span class="toggle-icon">▶</span> 🔍 Affinity Debug</h4>
+          <div class="affinity-debug-body" style="display:none">
+            <div id="affinityDebugContent"><div class="text-muted" style="padding:8px"><span class="spinner"></span> Loading debug data…</div></div>
+          </div>
+        </div>
+
         <div class="node-full-card" id="fullPathsSection">
           <h4>Paths Through This Node</h4>
           <div id="fullPathsContent"><div class="text-muted" style="padding:8px"><span class="spinner"></span> Loading paths…</div></div>
@@ -399,6 +559,103 @@
         } catch {}
       }
 
+      // Fetch neighbors for this node (full-screen view)
+      fetchAndRenderNeighbors(n.public_key, 'fullNeighborsContent', {
+        headerSelector: '#fullNeighborsHeader'
+      });
+
+      // Affinity debug panel — show if debugAffinity is enabled
+      (function loadAffinityDebug() {
+        var show = (window.CLIENT_CONFIG && window.CLIENT_CONFIG.debugAffinity) || localStorage.getItem('meshcore-affinity-debug') === 'true';
+        var panel = document.getElementById('node-affinity-debug');
+        if (!show || !panel) return;
+        panel.style.display = '';
+        var apiKey = localStorage.getItem('meshcore-api-key') || '';
+        fetch('/api/debug/affinity?node=' + encodeURIComponent(n.public_key), { headers: { 'X-API-Key': apiKey } })
+          .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); })
+          .then(function (data) {
+            var el = document.getElementById('affinityDebugContent');
+            if (!el) return;
+            var html = '';
+
+            // Edges table
+            if (data.edges && data.edges.length) {
+              html += '<h5 style="margin:8px 0 4px">Neighbor Edges (' + data.edges.length + ')</h5>';
+              html += '<table class="mini-table" style="width:100%;font-size:12px"><thead><tr><th>Neighbor</th><th>Score</th><th>Count</th><th>Last Seen</th><th>Observers</th><th>Status</th></tr></thead><tbody>';
+              data.edges.forEach(function (e) {
+                var neighbor = e.nodeBName || e.nodeAName || (e.nodeB || e.nodeA || '').substring(0, 8);
+                if (e.nodeA.toLowerCase() === n.public_key.toLowerCase()) {
+                  neighbor = e.nodeBName || (e.nodeB || e.prefix || '?').substring(0, 8);
+                } else {
+                  neighbor = e.nodeAName || (e.nodeA || '').substring(0, 8);
+                }
+                var status = e.ambiguous ? (e.unresolved ? '❓ Unresolved' : '⚠️ Ambiguous') : (e.resolved ? '✅ Auto-resolved' : '✅ Resolved');
+                html += '<tr><td>' + escapeHtml(neighbor) + '</td><td>' + (e.score || 0).toFixed(3) + '</td><td>' + e.weight + '</td><td>' + (e.lastSeen || '').substring(0, 10) + '</td><td>' + (e.observers || []).length + '</td><td>' + status + '</td></tr>';
+              });
+              html += '</tbody></table>';
+            } else {
+              html += '<div class="text-muted" style="padding:8px">No affinity edges for this node</div>';
+            }
+
+            // Resolutions
+            if (data.resolutions && data.resolutions.length) {
+              html += '<h5 style="margin:12px 0 4px">Prefix Resolutions (' + data.resolutions.length + ')</h5>';
+              data.resolutions.forEach(function (r) {
+                html += '<div style="border:1px solid var(--border);border-radius:4px;padding:8px;margin-bottom:6px;font-size:12px">';
+                html += '<b>Prefix: ' + escapeHtml(r.prefix) + '</b> → ';
+                if (r.method === 'auto-resolved') {
+                  html += '<span style="color:var(--status-green)">✅ ' + escapeHtml(r.chosenName || r.chosen || '?') + '</span>';
+                  html += ' (Jaccard=' + r.chosenJaccard.toFixed(2) + ', ratio=' + ((isFinite(r.ratio) && r.ratio < 100) ? r.ratio.toFixed(1) + '×' : '∞') + ')';
+                } else {
+                  html += '<span style="color:var(--status-yellow)">⚠️ Ambiguous</span>';
+                  if (r.ratio) html += ' (ratio=' + r.ratio.toFixed(1) + '×, threshold=' + r.thresholdApplied + '×)';
+                }
+                // Show disambiguation tier used (M4 resolveWithContext)
+                if (r.tier) {
+                  var tierLabels = {
+                    'neighbor_affinity': '🏘️ Affinity',
+                    'geo_proximity': '🌍 Geo',
+                    'gps_preference': '📍 GPS',
+                    'first_match': '🎲 Naive',
+                    'unique_prefix': '✓ Unique',
+                    'no_match': '∅ None'
+                  };
+                  html += ' <span style="font-size:11px;opacity:0.8">[tier: ' + (tierLabels[r.tier] || escapeHtml(r.tier)) + ']</span>';
+                }
+                // Candidates table
+                if (r.candidates && r.candidates.length) {
+                  html += '<div style="margin-top:4px"><table class="mini-table" style="width:100%;font-size:11px"><thead><tr><th>Candidate</th><th>Jaccard</th><th>Count</th></tr></thead><tbody>';
+                  r.candidates.forEach(function (c) {
+                    var highlight = r.chosen && c.pubkey === r.chosen ? ' style="background:var(--status-green-bg,rgba(34,197,94,0.1))"' : '';
+                    html += '<tr' + highlight + '><td>' + escapeHtml(c.name || c.pubkey.substring(0, 8)) + '</td><td>' + c.jaccard.toFixed(3) + '</td><td>' + c.score + '</td></tr>';
+                  });
+                  html += '</tbody></table></div>';
+                }
+                html += '</div>';
+              });
+            }
+
+            // Stats summary
+            if (data.stats) {
+              html += '<h5 style="margin:12px 0 4px">Graph Stats</h5>';
+              html += '<div style="font-size:12px;line-height:1.6">';
+              html += 'Total edges: ' + data.stats.totalEdges + '<br>';
+              html += 'Total nodes: ' + data.stats.totalNodes + '<br>';
+              html += 'Resolved: ' + data.stats.resolvedCount + ' | Ambiguous: ' + data.stats.ambiguousCount + ' | Unresolved: ' + data.stats.unresolvedCount + '<br>';
+              html += 'Avg confidence: ' + (data.stats.avgConfidence || 0).toFixed(3) + '<br>';
+              html += 'Cold-start coverage: ' + (data.stats.coldStartCoverage || 0).toFixed(1) + '%<br>';
+              html += 'Cache age: ' + (data.stats.cacheAge || 'N/A') + ' | Last rebuild: ' + (data.stats.lastRebuild || 'N/A');
+              html += '</div>';
+            }
+
+            el.innerHTML = html;
+          })
+          .catch(function (err) {
+            var el = document.getElementById('affinityDebugContent');
+            if (el) el.innerHTML = '<div class="text-muted" style="padding:8px">Failed to load debug data: ' + escapeHtml(err.message) + '</div>';
+          });
+      })();
+
       // Fetch paths through this node (full-screen view)
       api('/nodes/' + encodeURIComponent(n.public_key) + '/paths', { ttl: CLIENT_TTL.nodeDetail }).then(pathData => {
         const el = document.getElementById('fullPathsContent');
@@ -718,11 +975,7 @@
     panel.innerHTML = '<div class="text-center text-muted" style="padding:40px">Loading…</div>';
 
     try {
-      const [data, healthData] = await Promise.all([
-        api('/nodes/' + encodeURIComponent(pubkey), { ttl: CLIENT_TTL.nodeDetail }),
-        api('/nodes/' + encodeURIComponent(pubkey) + '/health', { ttl: CLIENT_TTL.nodeDetail }).catch(() => null)
-      ]);
-      data.healthData = healthData;
+      const data = await fetchNodeDetail(pubkey);
       renderDetail(panel, data);
     } catch (e) {
       panel.innerHTML = `<div class="text-muted">Error: ${e.message}</div>`;
@@ -791,6 +1044,11 @@
           </div>
         </div>` : ''}
 
+        <div class="node-detail-section" id="panelNeighborsSection">
+          <h4 id="panelNeighborsHeader">Neighbors</h4>
+          <div id="panelNeighborsContent"><div class="text-muted" style="padding:8px"><span class="spinner"></span> Loading neighbors…</div></div>
+        </div>
+
         <div class="node-detail-section" id="pathsSection">
           <h4>Paths Through This Node</h4>
           <div id="pathsContent"><div class="text-muted" style="padding:8px"><span class="spinner"></span> Loading paths…</div></div>
@@ -861,6 +1119,13 @@
       } catch {}
     }
 
+    // Fetch neighbors for this node (condensed panel — top 5)
+    fetchAndRenderNeighbors(n.public_key, 'panelNeighborsContent', {
+      limit: 5,
+      headerSelector: '#panelNeighborsHeader',
+      viewAllPubkey: n.public_key
+    });
+
     // Fetch paths through this node
     api('/nodes/' + encodeURIComponent(n.public_key) + '/paths', { ttl: CLIENT_TTL.nodeDetail }).then(pathData => {
       const el = document.getElementById('pathsContent');
@@ -929,4 +1194,16 @@
 
   // Test hooks
   window._nodesIsAdvertMessage = isAdvertMessage;
+  window._nodesGetAllNodes = function() { return _allNodes; };
+  window._nodesSetAllNodes = function(n) { _allNodes = n; };
+  window._nodesToggleSort = toggleSort;
+  window._nodesSortNodes = sortNodes;
+  window._nodesSortArrow = sortArrow;
+  window._nodesGetSortState = function() { return sortState; };
+  window._nodesSetSortState = function(s) { sortState = s; };
+  window._nodesSyncClaimedToFavorites = syncClaimedToFavorites;
+  window._nodesRenderNodeTimestampHtml = renderNodeTimestampHtml;
+  window._nodesRenderNodeTimestampText = renderNodeTimestampText;
+  window._nodesGetStatusInfo = getStatusInfo;
+  window._nodesGetStatusTooltip = getStatusTooltip;
 })();

public/observer-detail.js

@@ -37,7 +37,7 @@
     }
 
     app.innerHTML = `
-      <div class="observer-detail-page" style="overflow-y:auto;height:calc(100vh - 56px);padding:16px">
+      <div class="observer-detail-page" style="padding:16px">
         <div class="page-header" style="display:flex;align-items:center;gap:12px;margin-bottom:16px">
           <a href="#/observers" class="btn-icon" title="Back to Observers" aria-label="Back">←</a>
           <h2 style="margin:0" id="obsTitle">Observer Detail</h2>

public/packet-helpers.js

@@ -0,0 +1,61 @@
+/* === CoreScope — packet-helpers.js (shared packet utilities) === */
+'use strict';
+
+/**
+ * Cached JSON.parse helpers for packet data (issue #387).
+ * Avoids repeated parsing of path_json / decoded_json on the same packet object.
+ * Results are cached as _parsedPath / _parsedDecoded properties on the packet.
+ *
+ * Handles pre-parsed objects (non-string values) gracefully — returns them as-is.
+ */
+
+window.getParsedPath = function getParsedPath(p) {
+  if (p._parsedPath !== undefined) return p._parsedPath || [];
+  var raw = p.path_json;
+  if (typeof raw !== 'string') {
+    p._parsedPath = Array.isArray(raw) ? raw : [];
+    return p._parsedPath;
+  }
+  try { p._parsedPath = JSON.parse(raw) || []; } catch (e) { p._parsedPath = []; }
+  return p._parsedPath;
+};
+
+/**
+ * Clear cached _parsedPath/_parsedDecoded from a packet object.
+ * Must be called after spreading a parent packet into an observation/child,
+ * otherwise the child inherits stale cached values from the parent (issue #504).
+ */
+window.clearParsedCache = function clearParsedCache(p) {
+  delete p._parsedPath;
+  delete p._parsedDecoded;
+  delete p._parsedResolvedPath;
+  return p;
+};
+
+/**
+ * Parse resolved_path (server-side resolved full pubkeys).
+ * Returns array of pubkey strings (or null entries) if present, or null if absent.
+ * Cached as _parsedResolvedPath on the packet object.
+ */
+window.getResolvedPath = function getResolvedPath(p) {
+  if (p._parsedResolvedPath !== undefined) return p._parsedResolvedPath;
+  var raw = p.resolved_path;
+  if (!raw) { p._parsedResolvedPath = null; return null; }
+  if (typeof raw !== 'string') {
+    p._parsedResolvedPath = Array.isArray(raw) ? raw : null;
+    return p._parsedResolvedPath;
+  }
+  try { p._parsedResolvedPath = JSON.parse(raw) || null; } catch (e) { p._parsedResolvedPath = null; }
+  return p._parsedResolvedPath;
+};
+
+window.getParsedDecoded = function getParsedDecoded(p) {
+  if (p._parsedDecoded !== undefined) return p._parsedDecoded || {};
+  var raw = p.decoded_json;
+  if (typeof raw !== 'string') {
+    p._parsedDecoded = (raw && typeof raw === 'object') ? raw : {};
+    return p._parsedDecoded;
+  }
+  try { p._parsedDecoded = JSON.parse(raw) || {}; } catch (e) { p._parsedDecoded = {}; }
+  return p._parsedDecoded;
+};

public/perf.js

@@ -5,7 +5,7 @@
   let interval = null;
 
   async function render(app) {
-    app.innerHTML = '<div id="perfWrapper" style="height:100%;overflow-y:auto;padding:16px 24px;"><h2>⚡ Performance Dashboard</h2><div id="perfContent">Loading...</div></div>';
+    app.innerHTML = '<div id="perfWrapper" style="padding:16px 24px;"><h2>⚡ Performance Dashboard</h2><div id="perfContent">Loading...</div></div>';
     await refresh();
   }
 

public/style.css

@@ -5,7 +5,9 @@
   --nav-bg2: #1a1a2e;
   --nav-text: #ffffff;
   --nav-text-muted: #cbd5e1;
+  --nav-active-bg: rgba(74, 158, 255, 0.15);
   --accent: #4a9eff;
+  --geo-filter-color: #3b82f6;
   --status-green: #22c55e;
   --status-yellow: #eab308;
   --status-red: #ef4444;
@@ -127,7 +129,7 @@ a:focus-visible, button:focus-visible, input:focus-visible, select:focus-visible
 .nav-link.active { 
   color: var(--nav-text); 
   border-bottom-color: transparent;
-  background: rgba(74, 158, 255, 0.15); 
+  background: var(--nav-active-bg); 
   border-radius: 6px; 
   margin: 4px 0;
   padding: 10px 12px;
@@ -179,7 +181,12 @@ a:focus-visible, button:focus-visible, input:focus-visible, select:focus-visible
 }
 
 /* === Layout === */
-#app { height: calc(100vh - 52px); height: calc(100dvh - 52px); overflow: hidden; }
+/* Default: body-scroll mode — content pushes beyond viewport, iOS status-bar
+   tap-to-scroll works because <body> is the scroll container.  Pages that need
+   a fixed-height container (maps, virtual-scroll, split-panels) add
+   .app-fixed via the router so their children can use height:100%. */
+#app { min-height: calc(100vh - 52px); min-height: calc(100dvh - 52px); }
+#app.app-fixed { height: calc(100vh - 52px); height: calc(100dvh - 52px); min-height: 0; overflow: hidden; }
 
 .split-layout {
   display: flex; height: 100%; overflow: hidden;
@@ -297,6 +304,13 @@ a:focus-visible, button:focus-visible, input:focus-visible, select:focus-visible
   font-size: 10px; font-weight: 700; font-family: var(--mono);
   background: var(--nav-bg); color: var(--nav-text); letter-spacing: .5px;
 }
+/* TODO: expose --transport-badge-bg/fg in customizer THEME_CSS_MAP (tracked in future milestone) */
+.badge-transport {
+  display: inline-block; padding: 1px 5px; border-radius: 4px;
+  font-size: 9px; font-weight: 700; font-family: var(--mono);
+  background: var(--transport-badge-bg, #f59e0b20); color: var(--transport-badge-fg, #d97706);
+  letter-spacing: .5px; vertical-align: middle;
+}
 .badge-obs {
   display: inline-block; padding: 1px 6px; border-radius: 10px;
   font-size: 10px; font-weight: 600;
@@ -366,6 +380,10 @@ a:focus-visible, button:focus-visible, input:focus-visible, select:focus-visible
   background: var(--section-bg, #eef2ff); font-weight: 700; font-size: 11px;
   text-transform: uppercase; letter-spacing: .5px; color: var(--accent);
 }
+.field-table .section-header td  { background: rgba(243,139,168,0.18); }
+.field-table .section-transport td { background: rgba(137,180,250,0.18); }
+.field-table .section-path td    { background: rgba(166,227,161,0.18); }
+.field-table .section-payload td { background: rgba(249,226,175,0.18); }
 
 /* === Path display === */
 .path-hops {
@@ -613,7 +631,19 @@ button.ch-item.selected { background: var(--selected-bg); }
 .node-detail { padding: 4px 0; }
 .node-detail-name { font-size: 20px; font-weight: 700; margin: 12px 0 4px; }
 .node-detail-role { margin-bottom: 12px; }
-.node-detail-section { margin-bottom: 16px; }
+.node-detail-section {
+  background: var(--card-bg); border: 1px solid var(--border);
+  border-radius: 8px; padding: 12px; margin-bottom: 8px;
+}
+/* Bug 7 fix: neighbor table text inherits accent color — force readable text */
+.node-detail-section .data-table td,
+.node-full-card .data-table td {
+  color: var(--text);
+}
+.node-detail-section .data-table td a,
+.node-full-card .data-table td a {
+  color: var(--accent);
+}
 .node-detail-section h4 {
   font-size: 12px; text-transform: uppercase; letter-spacing: .5px;
   color: var(--text-muted); margin-bottom: 8px; padding-bottom: 4px;
@@ -649,7 +679,7 @@ button.ch-item.selected { background: var(--selected-bg); }
 .advert-info { font-size: 12px; line-height: 1.5; }
 
 /* === Traces Page === */
-.traces-page { padding: 16px; max-width: var(--trace-max-width, 95vw); margin: 0 auto; overflow-y: auto; height: 100%; }
+.traces-page { padding: 16px; max-width: var(--trace-max-width, 95vw); margin: 0 auto; }
 .trace-search {
   display: flex; gap: 8px; margin-bottom: 20px;
 }
@@ -721,7 +751,7 @@ button.ch-item.selected { background: var(--selected-bg); }
 ::-webkit-scrollbar-thumb:hover { background: var(--text-muted); }
 
 /* === Observers Page === */
-.observers-page { padding: 20px; max-width: 1200px; margin: 0 auto; overflow-y: auto; height: calc(100vh - 56px); }
+.observers-page { padding: 20px; max-width: 1200px; margin: 0 auto; }
 .obs-summary { display: flex; gap: 20px; margin-bottom: 16px; flex-wrap: wrap; }
 .obs-stat { display: flex; align-items: center; gap: 6px; font-size: 14px; color: var(--text-muted); }
 .health-dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; flex-shrink: 0; }
@@ -826,6 +856,22 @@ button.ch-item.selected { background: var(--selected-bg); }
 
 /* === Hamburger (hidden on desktop) === */
 .hamburger { display: none; }
+/* "More" button (hidden on desktop) */
+.nav-more-wrap { display: none; position: relative; }
+.nav-more-btn { display: inline-flex; }
+.nav-more-menu {
+  display: none; position: absolute; top: calc(var(--top-nav-h, 52px) - 4px); right: 0;
+  background: var(--nav-bg); border: 1px solid var(--border); border-radius: 8px;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15); flex-direction: column;
+  min-width: 160px; padding: 4px 0; z-index: 1200;
+}
+.nav-more-menu.open { display: flex; }
+.nav-more-menu .nav-link {
+  padding: 10px 16px; border-bottom: none; border-radius: 0; margin: 0;
+  white-space: nowrap;
+}
+.nav-more-menu .nav-link:hover { background: var(--nav-bg2); color: var(--nav-text); }
+.nav-more-menu .nav-link.active { background: var(--nav-active-bg); }
 /* Ensure nav stays above Leaflet map */
 .nav-links.open { z-index: 1100; }
 #map-wrap .leaflet-container { z-index: 1; }
@@ -840,19 +886,37 @@ button.ch-item.selected { background: var(--selected-bg); }
   .map-controls { width: 180px; font-size: 12px; }
 }
 
-/* === Responsive — Mobile (≤640px) === */
-@media (max-width: 640px) {
-  /* Nav: hamburger + collapse */
+/* === Responsive — Tablet Priority+ nav (768–1023px) === */
+@media (min-width: 768px) and (max-width: 1023px) {
+  .nav-links { display: flex !important; flex-direction: row; gap: 2px; }
+  .nav-links a:not([data-priority="high"]) { display: none; }
+  .nav-more-wrap { display: flex; align-items: center; }
+  .hamburger { display: none; }
+  .nav-link { padding: 14px 8px; font-size: 13px; }
+  .nav-links a[data-priority="high"] { order: -1; }
+  .nav-link.active { background: var(--nav-active-bg); border-radius: 6px; margin: 4px 0; padding: 10px 8px; }
+}
+
+/* === Responsive — Hamburger nav (<768px) === */
+@media (max-width: 767px) {
   .hamburger { display: inline-flex; }
+  .nav-more-wrap { display: none !important; }
   .nav-links {
     display: none; position: absolute; top: 52px; left: 0; right: 0;
     background: var(--nav-bg); flex-direction: column; padding: 8px 0;
-    box-shadow: 0 8px 24px rgba(0,0,0,.4); z-index: 99;
+    box-shadow: 0 8px 24px rgba(0,0,0,.4); z-index: 1100;
+    max-height: calc(100dvh - 52px); overflow-y: auto;
   }
+  .nav-links a:not([data-priority="high"]) { display: flex; }
   .nav-links.open { display: flex; }
   .nav-link { padding: 12px 20px; border-bottom: none; }
-  .nav-link.active { background: rgba(74,158,255,0.15); border-radius: 0; margin: 0; padding: 12px 20px; }
+  .nav-link.active { background: var(--nav-active-bg); border-radius: 0; margin: 0; padding: 12px 20px; }
   .nav-left { gap: 12px; }
+  body.nav-open { overflow: hidden; }
+}
+
+/* === Responsive — Mobile (≤640px) === */
+@media (max-width: 640px) {
   .brand-text { display: none; }
   .nav-right { gap: 4px; }
 
@@ -888,7 +952,9 @@ button.ch-item.selected { background: var(--selected-bg); }
   .filter-bar { flex-direction: row; flex-wrap: wrap; gap: 4px; }
   .filter-toggle-btn { display: inline-flex !important; }
   .filter-bar > *:not(.filter-toggle-btn):not(.col-toggle-wrap) { display: none; }
-  .filter-bar.filters-expanded > * { display: inline-flex; }
+  /* Must match :not() specificity of the hide rule above, otherwise .filters-expanded loses
+     the specificity battle and filter children stay hidden (see issue #534). */
+  .filter-bar.filters-expanded > *:not(.filter-toggle-btn):not(.col-toggle-wrap) { display: inline-flex; }
   .filter-bar.filters-expanded > .col-toggle-wrap { display: inline-block; }
   .filter-bar.filters-expanded input { width: 100%; }
   .filter-bar.filters-expanded select { width: 100%; }
@@ -1077,7 +1143,7 @@ button.ch-item.ch-item-encrypted .ch-badge { filter: grayscale(0.6); }
 .node-activity-time { color: var(--text-muted); white-space: nowrap; min-width: 70px; font-size: 12px; }
 
 /* Analytics page */
-.analytics-page { padding: 16px 24px; max-width: 1600px; margin: 0 auto; overflow-y: auto; height: 100%; }
+.analytics-page { padding: 16px 24px; max-width: 1600px; margin: 0 auto; }
 .analytics-header { margin-bottom: 20px; }
 .analytics-header h2 { margin: 0 0 4px; }
 .analytics-card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px; margin-bottom: 16px; }
@@ -1224,7 +1290,7 @@ button.ch-item.ch-item-encrypted .ch-badge { filter: grayscale(0.6); }
 
 /* Hide low-value columns on mobile */
 @media (max-width: 640px) {
-  .col-region, .col-rpt, .col-size, .col-pubkey { display: none; }
+  .col-region, .col-rpt, .col-size, .col-hashsize, .col-pubkey { display: none; }
 }
 
 /* Clickable hop links */
@@ -1370,6 +1436,7 @@ tr[data-hops]:hover { background: rgba(59,130,246,0.1); }
 .hide-col-observer .col-observer,
 .hide-col-path .col-path,
 .hide-col-rpt .col-rpt,
+.hide-col-hashsize .col-hashsize,
 .hide-col-details .col-details { display: none; }
 
 /* === Home page fixes === */
@@ -1882,3 +1949,12 @@ tr[data-hops]:hover { background: rgba(59,130,246,0.1); }
   .compare-select { min-width: auto; width: 100%; }
   .compare-summary { grid-template-columns: 1fr; }
 }
+
+/* Neighbor graph canvas focus indicator for keyboard navigation */
+#ngCanvas:focus {
+  outline: 2px solid var(--link-color, #60a5fa);
+  outline-offset: 2px;
+}
+#ngCanvas:focus:not(:focus-visible) {
+  outline: none;
+}

scripts/prune-nodes-outside-geo-filter.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Delete nodes from the database that fall outside the configured geo_filter polygon + bufferKm.
+Nodes with no GPS coordinates are always kept.
+
+Usage:
+  python3 prune-nodes-outside-geo-filter.py [db_path] [--config config.json] [--dry-run]
+
+  db_path         Path to meshcore.db   (default: /app/data/meshcore.db)
+  --config PATH   Path to config.json   (default: /app/config.json)
+  --dry-run       Show what would be deleted without making any changes
+"""
+
+import sqlite3
+import math
+import sys
+import json
+import os
+
+
+def point_in_polygon(lat, lon, polygon):
+    """Ray-casting algorithm."""
+    inside = False
+    n = len(polygon)
+    j = n - 1
+    for i in range(n):
+        yi, xi = polygon[i]   # lat, lon
+        yj, xj = polygon[j]
+        if ((yi > lat) != (yj > lat)) and (lon < (xj - xi) * (lat - yi) / (yj - yi) + xi):
+            inside = not inside
+        j = i
+    return inside
+
+
+def dist_to_segment_km(lat, lon, a, b):
+    """Approximate distance (km) from point to line segment, using flat-earth projection."""
+    lat1, lon1 = a
+    lat2, lon2 = b
+    mid_lat = (lat1 + lat2) / 2.0
+    cos_lat = math.cos(math.radians(mid_lat))
+    km_per_deg_lat = 111.0
+    km_per_deg_lon = 111.0 * cos_lat
+
+    # Translate so point is at origin
+    ax = (lon1 - lon) * km_per_deg_lon
+    ay = (lat1 - lat) * km_per_deg_lat
+    bx = (lon2 - lon) * km_per_deg_lon
+    by = (lat2 - lat) * km_per_deg_lat
+
+    abx, aby = bx - ax, by - ay
+    ab_sq = abx * abx + aby * aby
+    if ab_sq == 0:
+        return math.sqrt(ax * ax + ay * ay)
+
+    t = max(0.0, min(1.0, -(ax * abx + ay * aby) / ab_sq))
+    px = ax + t * abx
+    py = ay + t * aby
+    return math.sqrt(px * px + py * py)
+
+
+def node_passes_filter(lat, lon, polygon, buffer_km):
+    """Return True if the node should be kept."""
+    if lat is None or lon is None:
+        return True
+    if lat == 0.0 and lon == 0.0:
+        return True  # no GPS fix
+    if point_in_polygon(lat, lon, polygon):
+        return True
+    if buffer_km > 0:
+        n = len(polygon)
+        for i in range(n):
+            j = (i + 1) % n
+            if dist_to_segment_km(lat, lon, polygon[i], polygon[j]) <= buffer_km:
+                return True
+    return False
+
+
+def load_geo_filter(config_path):
+    """Load polygon and bufferKm from config.json geo_filter section."""
+    if not os.path.exists(config_path):
+        print(f"ERROR: config not found at {config_path}")
+        sys.exit(1)
+    with open(config_path) as f:
+        cfg = json.load(f)
+    gf = cfg.get('geo_filter')
+    if not gf:
+        print("ERROR: no geo_filter section found in config.json")
+        sys.exit(1)
+    polygon = gf.get('polygon', [])
+    if len(polygon) < 3:
+        print("ERROR: geo_filter.polygon must have at least 3 points")
+        sys.exit(1)
+    buffer_km = gf.get('bufferKm', 0.0)
+    print(f"Loaded geo_filter from {config_path}: {len(polygon)} points, bufferKm={buffer_km}")
+    return polygon, buffer_km
+
+
+def main():
+    args = sys.argv[1:]
+    dry_run = '--dry-run' in args
+    args = [a for a in args if a != '--dry-run']
+
+    config_path = '/app/config.json'
+    if '--config' in args:
+        idx = args.index('--config')
+        config_path = args[idx + 1]
+        args = args[:idx] + args[idx + 2:]
+
+    db_path = args[0] if args else '/app/data/meshcore.db'
+
+    polygon, buffer_km = load_geo_filter(config_path)
+
+    if not os.path.exists(db_path):
+        print(f"ERROR: database not found at {db_path}")
+        sys.exit(1)
+
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    cur = conn.cursor()
+
+    cur.execute('SELECT public_key, name, lat, lon FROM nodes ORDER BY name')
+    nodes = cur.fetchall()
+
+    keep, remove = [], []
+    for row in nodes:
+        lat = row['lat']
+        lon = row['lon']
+        if node_passes_filter(lat, lon, polygon, buffer_km):
+            keep.append(row)
+        else:
+            remove.append(row)
+
+    print(f"Total nodes in DB : {len(nodes)}")
+    print(f"Nodes to keep     : {len(keep)}")
+    print(f"Nodes to delete   : {len(remove)}")
+
+    if not remove:
+        print("\nNothing to delete.")
+        conn.close()
+        return
+
+    print("\nNodes that will be DELETED:")
+    for row in remove:
+        lat = row['lat'] or 0
+        lon = row['lon'] or 0
+        name = row['name'] or row['public_key'][:12]
+        print(f"  {name:<30}  lat={lat:.4f}  lon={lon:.4f}")
+
+    if dry_run:
+        print("\n[dry-run] No changes made.")
+        conn.close()
+        return
+
+    confirm = input(f"\nDelete {len(remove)} nodes? Type 'yes' to confirm: ").strip()
+    if confirm.lower() != 'yes':
+        print("Aborted.")
+        conn.close()
+        return
+
+    pubkeys = [row['public_key'] for row in remove]
+    cur.executemany('DELETE FROM nodes WHERE public_key = ?', [(pk,) for pk in pubkeys])
+    conn.commit()
+    print(f"\nDeleted {cur.rowcount if cur.rowcount >= 0 else len(pubkeys)} nodes.")
+    conn.close()
+
+
+if __name__ == '__main__':
+    main()

test-anim-perf.js

@@ -0,0 +1,123 @@
+/**
+ * test-anim-perf.js — Performance benchmark for animation timer management
+ *
+ * Demonstrates that the rAF + concurrency-cap approach keeps active animation
+ * count bounded, whereas the old setInterval approach accumulated without limit.
+ *
+ * Run: node test-anim-perf.js
+ */
+
+'use strict';
+
+let passed = 0, failed = 0;
+function assert(cond, msg) {
+  if (cond) { console.log(`  ✅ ${msg}`); passed++; }
+  else { console.log(`  ❌ ${msg}`); failed++; }
+}
+
+// ---------------------------------------------------------------------------
+// Simulate OLD behaviour: setInterval-based, no concurrency cap
+// ---------------------------------------------------------------------------
+function simulateOldModel(packetsPerSec, hopsPerPacket, durationSec) {
+  // Each hop spawns 3 intervals (pulse 26ms, line 33ms, fade 52ms).
+  // Pulse lasts ~2s, line ~0.66s, fade ~0.8s+0.4s ≈ 1.2s
+  // At any moment, timers from the last ~2s of packets are still alive.
+  const intervalLifetimes = [2.0, 0.66, 1.2]; // seconds each interval lives
+  let maxConcurrent = 0;
+  // Walk through time in 0.1s steps
+  const dt = 0.1;
+  const spawns = []; // {time, lifetime}
+  for (let t = 0; t < durationSec; t += dt) {
+    // Spawn timers for packets arriving in this window
+    const pktsInWindow = packetsPerSec * dt;
+    for (let p = 0; p < pktsInWindow; p++) {
+      for (let h = 0; h < hopsPerPacket; h++) {
+        for (const lt of intervalLifetimes) {
+          spawns.push({ time: t, lifetime: lt });
+        }
+      }
+    }
+    // Count alive timers
+    const alive = spawns.filter(s => t < s.time + s.lifetime).length;
+    if (alive > maxConcurrent) maxConcurrent = alive;
+  }
+  return maxConcurrent;
+}
+
+// ---------------------------------------------------------------------------
+// Simulate NEW behaviour: rAF + MAX_CONCURRENT_ANIMS cap
+// ---------------------------------------------------------------------------
+function simulateNewModel(packetsPerSec, hopsPerPacket, durationSec) {
+  const MAX_CONCURRENT_ANIMS = 20;
+  let activeAnims = 0;
+  let maxConcurrent = 0;
+  const anims = []; // {endTime}
+  const dt = 0.1;
+  for (let t = 0; t < durationSec; t += dt) {
+    // Expire finished animations
+    while (anims.length && anims[0].endTime <= t) {
+      anims.shift();
+      activeAnims--;
+    }
+    // Try to start new animations
+    const pktsInWindow = packetsPerSec * dt;
+    for (let p = 0; p < pktsInWindow; p++) {
+      if (activeAnims >= MAX_CONCURRENT_ANIMS) break; // cap reached — drop
+      activeAnims++;
+      // rAF animation lifetime: longest is pulse ~2s
+      anims.push({ endTime: t + 2.0 });
+    }
+    // Sort by endTime so expiry works
+    anims.sort((a, b) => a.endTime - b.endTime);
+    if (activeAnims > maxConcurrent) maxConcurrent = activeAnims;
+  }
+  return maxConcurrent;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+console.log('\n=== Animation timer accumulation: old vs new ===');
+
+// Scenario: 5 pkts/sec, 3 hops each, 30 seconds
+const oldPeak30s = simulateOldModel(5, 3, 30);
+const newPeak30s = simulateNewModel(5, 3, 30);
+console.log(`  Old model (30s @ 5pkt/s×3hops): peak ${oldPeak30s} concurrent timers`);
+console.log(`  New model (30s @ 5pkt/s×3hops): peak ${newPeak30s} concurrent animations`);
+assert(oldPeak30s > 100, `old model accumulates >100 timers (got ${oldPeak30s})`);
+assert(newPeak30s <= 20, `new model stays ≤20 (got ${newPeak30s})`);
+
+// Scenario: 5 minutes sustained
+const oldPeak5m = simulateOldModel(5, 3, 300);
+const newPeak5m = simulateNewModel(5, 3, 300);
+console.log(`  Old model (5min @ 5pkt/s×3hops): peak ${oldPeak5m} concurrent timers`);
+console.log(`  New model (5min @ 5pkt/s×3hops): peak ${newPeak5m} concurrent animations`);
+assert(oldPeak5m > 100, `old model at 5min still unbounded (got ${oldPeak5m})`);
+assert(newPeak5m <= 20, `new model at 5min still ≤20 (got ${newPeak5m})`);
+
+// Scenario: burst — 20 pkts/sec for 10s
+const oldBurst = simulateOldModel(20, 3, 10);
+const newBurst = simulateNewModel(20, 3, 10);
+console.log(`  Old model (burst 20pkt/s×3hops, 10s): peak ${oldBurst} concurrent timers`);
+console.log(`  New model (burst 20pkt/s×3hops, 10s): peak ${newBurst} concurrent animations`);
+assert(oldBurst > 200, `old model under burst >200 timers (got ${oldBurst})`);
+assert(newBurst <= 20, `new model under burst stays ≤20 (got ${newBurst})`);
+
+console.log('\n=== drawAnimatedLine frame-drop catch-up ===');
+
+// Read the source and verify catch-up logic exists
+const fs = require('fs');
+const src = fs.readFileSync(__dirname + '/public/live.js', 'utf8');
+
+// Extract the animateLine function body
+const lineMatch = src.match(/function animateLine\(now\)\s*\{[\s\S]*?requestAnimationFrame\(animateLine\)/);
+assert(lineMatch && /Math\.min\(Math\.floor\(elapsed\s*\/\s*33\)/.test(lineMatch[0]),
+  'drawAnimatedLine catches up on frame drops (multi-tick per frame)');
+
+const fadeMatch = src.match(/function animateFade\(now\)\s*\{[\s\S]*?requestAnimationFrame\(animateFade\)/);
+assert(fadeMatch && /Math\.min\(Math\.floor\(fadeElapsed\s*\/\s*52\)/.test(fadeMatch[0]),
+  'animateFade catches up on frame drops (multi-tick per frame)');
+
+console.log(`\n${passed} passed, ${failed} failed\n`);
+process.exit(failed ? 1 : 0);

test-customizer-v2.js

@@ -0,0 +1,517 @@
+/* Unit tests for customizer v2 core functions */
+'use strict';
+const vm = require('vm');
+const fs = require('fs');
+const assert = require('assert');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ✅ ${name}`); }
+  catch (e) { failed++; console.log(`  ❌ ${name}: ${e.message}`); }
+}
+
+function makeSandbox() {
+  const storage = {};
+  const localStorage = {
+    _data: storage,
+    getItem(k) { return k in storage ? storage[k] : null; },
+    setItem(k, v) { storage[k] = String(v); },
+    removeItem(k) { delete storage[k]; },
+    clear() { for (const k in storage) delete storage[k]; }
+  };
+  const ctx = {
+    window: {
+      addEventListener: () => {},
+      dispatchEvent: () => {},
+      SITE_CONFIG: {},
+      _SITE_CONFIG_ORIGINAL_HOME: null,
+    },
+    document: {
+      readyState: 'loading',
+      createElement: (tag) => ({
+        id: '', textContent: '', innerHTML: '', className: '',
+        setAttribute: () => {}, appendChild: () => {},
+        style: {}, addEventListener: () => {},
+        querySelectorAll: () => [], querySelector: () => null,
+      }),
+      head: { appendChild: () => {} },
+      getElementById: () => null,
+      addEventListener: () => {},
+      querySelectorAll: () => [],
+      querySelector: () => null,
+      documentElement: {
+        style: { setProperty: () => {}, removeProperty: () => {}, getPropertyValue: () => '' },
+        dataset: { theme: 'dark' },
+        getAttribute: () => 'dark',
+      },
+    },
+    console,
+    localStorage,
+    setTimeout: (fn) => fn(),
+    clearTimeout: () => {},
+    Date, Math, Array, Object, JSON, String, Number, Boolean,
+    parseInt, parseFloat, isNaN, Infinity, NaN, undefined,
+    MutationObserver: class { observe() {} },
+    HashChangeEvent: class {},
+    CustomEvent: class CustomEvent { constructor(type, opts) { this.type = type; this.detail = opts && opts.detail; } },
+    getComputedStyle: () => ({ getPropertyValue: () => '' }),
+  };
+  ctx.window.localStorage = localStorage;
+  ctx.self = ctx.window;
+  return ctx;
+}
+
+function loadCustomizer() {
+  const ctx = makeSandbox();
+  const code = fs.readFileSync('public/customize-v2.js', 'utf8');
+  vm.createContext(ctx);
+  vm.runInContext(code, ctx, { filename: 'customize-v2.js' });
+  return { ctx, api: ctx.window._customizerV2, ls: ctx.localStorage };
+}
+
+console.log('\n📋 Customizer V2 — Core Function Tests\n');
+
+// ── readOverrides ──
+console.log('readOverrides:');
+test('returns {} when key is absent', () => {
+  const { api } = loadCustomizer();
+  const result = api.readOverrides();
+  assert.strictEqual(JSON.stringify(result), '{}');
+});
+
+test('returns {} when key contains invalid JSON', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', 'not json{{{');
+  assert.strictEqual(JSON.stringify(api.readOverrides()), '{}');
+});
+
+test('returns {} when key contains a non-object (string)', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', '"just a string"');
+  assert.strictEqual(JSON.stringify(api.readOverrides()), '{}');
+});
+
+test('returns {} when key contains an array', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', '[1,2,3]');
+  assert.strictEqual(JSON.stringify(api.readOverrides()), '{}');
+});
+
+test('returns {} when key contains a number', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', '42');
+  assert.strictEqual(JSON.stringify(api.readOverrides()), '{}');
+});
+
+test('returns parsed object when valid', () => {
+  const { api, ls } = loadCustomizer();
+  const data = { theme: { accent: '#ff0000' } };
+  ls.setItem('cs-theme-overrides', JSON.stringify(data));
+  assert.deepStrictEqual(api.readOverrides(), data);
+});
+
+// ── writeOverrides ──
+console.log('\nwriteOverrides:');
+test('writes serialized JSON to localStorage', () => {
+  const { api, ls } = loadCustomizer();
+  const data = { theme: { accent: '#ff0000' } };
+  api.writeOverrides(data);
+  assert.deepStrictEqual(JSON.parse(ls.getItem('cs-theme-overrides')), data);
+});
+
+test('removes key when delta is empty {}', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', '{"theme":{}}');
+  api.writeOverrides({});
+  assert.strictEqual(ls.getItem('cs-theme-overrides'), null);
+});
+
+test('round-trips correctly (write → read = identical)', () => {
+  const { api } = loadCustomizer();
+  const data = { theme: { accent: '#abc', text: '#def' }, nodeColors: { repeater: '#111' } };
+  api.writeOverrides(data);
+  assert.deepStrictEqual(api.readOverrides(), data);
+});
+
+test('strips invalid color values silently', () => {
+  const { api, ls } = loadCustomizer();
+  api.writeOverrides({ theme: { accent: 'not-a-color' } });
+  // Invalid color is stripped by _validateDelta; remaining empty object is stored as '{}'
+  const stored = JSON.parse(ls.getItem('cs-theme-overrides'));
+  assert.strictEqual(stored.theme, undefined);
+});
+
+test('strips out-of-range opacity', () => {
+  const { api, ls } = loadCustomizer();
+  api.writeOverrides({ heatmapOpacity: 1.5 });
+  const stored1 = JSON.parse(ls.getItem('cs-theme-overrides'));
+  assert.strictEqual(stored1.heatmapOpacity, undefined);
+  api.writeOverrides({ heatmapOpacity: -0.1 });
+  const stored2 = JSON.parse(ls.getItem('cs-theme-overrides'));
+  assert.strictEqual(stored2.heatmapOpacity, undefined);
+});
+
+test('accepts valid opacity', () => {
+  const { api, ls } = loadCustomizer();
+  api.writeOverrides({ heatmapOpacity: 0.5 });
+  const stored = JSON.parse(ls.getItem('cs-theme-overrides'));
+  assert.strictEqual(stored.heatmapOpacity, 0.5);
+});
+
+// ── computeEffective ──
+console.log('\ncomputeEffective:');
+test('returns server defaults when overrides is {}', () => {
+  const { api } = loadCustomizer();
+  const defaults = { theme: { accent: '#aaa', text: '#bbb' }, nodeColors: { repeater: '#ccc' } };
+  const result = api.computeEffective(defaults, {});
+  assert.deepStrictEqual(result, defaults);
+});
+
+test('overrides a single key in a section', () => {
+  const { api } = loadCustomizer();
+  const defaults = { theme: { accent: '#aaa', text: '#bbb' } };
+  const result = api.computeEffective(defaults, { theme: { accent: '#ff0000' } });
+  assert.strictEqual(result.theme.accent, '#ff0000');
+  assert.strictEqual(result.theme.text, '#bbb');
+});
+
+test('overrides multiple keys across sections', () => {
+  const { api } = loadCustomizer();
+  const defaults = { theme: { accent: '#aaa' }, nodeColors: { repeater: '#bbb' } };
+  const result = api.computeEffective(defaults, { theme: { accent: '#111' }, nodeColors: { repeater: '#222' } });
+  assert.strictEqual(result.theme.accent, '#111');
+  assert.strictEqual(result.nodeColors.repeater, '#222');
+});
+
+test('does not mutate either input', () => {
+  const { api } = loadCustomizer();
+  const defaults = { theme: { accent: '#aaa' } };
+  const overrides = { theme: { accent: '#bbb' } };
+  const defCopy = JSON.stringify(defaults);
+  const ovrCopy = JSON.stringify(overrides);
+  api.computeEffective(defaults, overrides);
+  assert.strictEqual(JSON.stringify(defaults), defCopy);
+  assert.strictEqual(JSON.stringify(overrides), ovrCopy);
+});
+
+test('handles missing sections in overrides gracefully', () => {
+  const { api } = loadCustomizer();
+  const defaults = { theme: { accent: '#aaa' }, nodeColors: { repeater: '#bbb' } };
+  const result = api.computeEffective(defaults, { theme: { accent: '#ccc' } });
+  assert.strictEqual(result.nodeColors.repeater, '#bbb');
+});
+
+test('array values in home are fully replaced, not merged', () => {
+  const { api } = loadCustomizer();
+  const defaults = { home: { steps: [{ emoji: '1', title: 'a', description: 'b' }], heroTitle: 'X' } };
+  const overrides = { home: { steps: [{ emoji: '2', title: 'c', description: 'd' }, { emoji: '3', title: 'e', description: 'f' }] } };
+  const result = api.computeEffective(defaults, overrides);
+  assert.strictEqual(result.home.steps.length, 2);
+  assert.strictEqual(result.home.steps[0].emoji, '2');
+  assert.strictEqual(result.home.heroTitle, 'X'); // untouched
+});
+
+test('top-level scalars are directly replaced', () => {
+  const { api } = loadCustomizer();
+  const defaults = { heatmapOpacity: 0.5 };
+  const result = api.computeEffective(defaults, { heatmapOpacity: 0.8 });
+  assert.strictEqual(result.heatmapOpacity, 0.8);
+});
+
+// ── validateShape ──
+console.log('\nvalidateShape:');
+test('accepts valid delta objects', () => {
+  const { api } = loadCustomizer();
+  const result = api.validateShape({ theme: { accent: '#fff' }, heatmapOpacity: 0.5 });
+  assert.strictEqual(result.valid, true);
+});
+
+test('accepts empty object', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.validateShape({}).valid, true);
+});
+
+test('rejects non-objects (string)', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.validateShape('hello').valid, false);
+});
+
+test('rejects non-objects (array)', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.validateShape([1, 2]).valid, false);
+});
+
+test('rejects non-objects (null)', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.validateShape(null).valid, false);
+});
+
+test('warns on unknown top-level keys', () => {
+  const { api } = loadCustomizer();
+  const result = api.validateShape({ unknownKey: {} });
+  // Unknown keys produce a console.warn but validateShape still returns valid
+  assert.strictEqual(result.valid, true);
+  assert.strictEqual(result.errors.length, 0);
+});
+
+test('validates section types (rejects non-object section)', () => {
+  const { api } = loadCustomizer();
+  const result = api.validateShape({ theme: 'not an object' });
+  assert.strictEqual(result.valid, false);
+});
+
+test('accepts valid rgb() color values in theme', () => {
+  const { api } = loadCustomizer();
+  const result = api.validateShape({ theme: { accent: 'rgb(1,2,3)' } });
+  assert.strictEqual(result.valid, true);
+});
+
+test('rejects out-of-range opacity values', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.validateShape({ heatmapOpacity: 2.0 }).valid, false);
+  assert.strictEqual(api.validateShape({ liveHeatmapOpacity: -1 }).valid, false);
+});
+
+// ── migrateOldKeys ──
+console.log('\nmigrateOldKeys:');
+test('migrates all 7 keys correctly', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('meshcore-user-theme', JSON.stringify({ theme: { accent: '#f00' }, branding: { siteName: 'Test' } }));
+  ls.setItem('meshcore-timestamp-mode', 'absolute');
+  ls.setItem('meshcore-timestamp-timezone', 'utc');
+  ls.setItem('meshcore-timestamp-format', 'iso-seconds');
+  ls.setItem('meshcore-timestamp-custom-format', 'YYYY-MM-DD');
+  ls.setItem('meshcore-heatmap-opacity', '0.7');
+  ls.setItem('meshcore-live-heatmap-opacity', '0.3');
+  const result = api.migrateOldKeys();
+  assert.strictEqual(result.theme.accent, '#f00');
+  assert.strictEqual(result.branding.siteName, 'Test');
+  assert.strictEqual(result.timestamps.defaultMode, 'absolute');
+  assert.strictEqual(result.timestamps.timezone, 'utc');
+  assert.strictEqual(result.heatmapOpacity, 0.7);
+  assert.strictEqual(result.liveHeatmapOpacity, 0.3);
+  // Legacy keys removed
+  assert.strictEqual(ls.getItem('meshcore-user-theme'), null);
+  assert.strictEqual(ls.getItem('meshcore-timestamp-mode'), null);
+  // New key written
+  assert.notStrictEqual(ls.getItem('cs-theme-overrides'), null);
+});
+
+test('handles partial migration (only some keys)', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('meshcore-timestamp-mode', 'ago');
+  const result = api.migrateOldKeys();
+  assert.strictEqual(result.timestamps.defaultMode, 'ago');
+  assert.strictEqual(ls.getItem('meshcore-timestamp-mode'), null);
+});
+
+test('handles invalid JSON in meshcore-user-theme', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('meshcore-user-theme', '{bad json');
+  const result = api.migrateOldKeys();
+  // Should not crash, returns delta (possibly empty besides what was valid)
+  assert(result !== null);
+  assert.strictEqual(ls.getItem('meshcore-user-theme'), null);
+});
+
+test('skips migration if cs-theme-overrides already exists', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', '{"theme":{}}');
+  ls.setItem('meshcore-user-theme', JSON.stringify({ theme: { accent: '#f00' } }));
+  const result = api.migrateOldKeys();
+  assert.strictEqual(result, null);
+  // Legacy key NOT removed (migration skipped entirely)
+  assert.notStrictEqual(ls.getItem('meshcore-user-theme'), null);
+});
+
+test('returns null when no legacy keys found', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.migrateOldKeys(), null);
+});
+
+test('drops unknown keys from meshcore-user-theme', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('meshcore-user-theme', JSON.stringify({ theme: { accent: '#f00' }, unknownStuff: 'hi' }));
+  const result = api.migrateOldKeys();
+  assert.strictEqual(result.theme.accent, '#f00');
+  assert.strictEqual(result.unknownStuff, undefined);
+});
+
+// ── THEME_CSS_MAP completeness ──
+console.log('\nTHEME_CSS_MAP:');
+test('includes surface3 mapping', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.THEME_CSS_MAP.surface3, '--surface-3');
+});
+
+test('includes sectionBg mapping', () => {
+  const { api } = loadCustomizer();
+  assert.strictEqual(api.THEME_CSS_MAP.sectionBg, '--section-bg');
+});
+
+test('matches all keys from old app.js varMap', () => {
+  const { api } = loadCustomizer();
+  const expectedKeys = [
+    'accent', 'accentHover', 'navBg', 'navBg2', 'navText', 'navTextMuted',
+    'background', 'text', 'textMuted', 'border',
+    'statusGreen', 'statusYellow', 'statusRed',
+    'surface1', 'surface2', 'surface3',
+    'cardBg', 'contentBg', 'inputBg',
+    'rowStripe', 'rowHover', 'detailBg',
+    'selectedBg', 'sectionBg',
+    'font', 'mono'
+  ];
+  for (const key of expectedKeys) {
+    assert(key in api.THEME_CSS_MAP, `Missing key: ${key}`);
+  }
+});
+
+// ── _isOverridden tests ──
+console.log('\n_isOverridden (value comparison):');
+
+test('returns false when no overrides exist', () => {
+  const { api } = loadCustomizer();
+  api.init({ theme: { accent: '#aaa' } });
+  assert.strictEqual(api.isOverridden('theme', 'accent'), false);
+});
+
+test('returns false when override matches server default', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#aaa' } }));
+  api.init({ theme: { accent: '#aaa' } });
+  assert.strictEqual(api.isOverridden('theme', 'accent'), false);
+});
+
+test('returns true when override differs from server default', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#bbb' } }));
+  api.init({ theme: { accent: '#aaa' } });
+  assert.strictEqual(api.isOverridden('theme', 'accent'), true);
+});
+
+test('returns false for key not in overrides', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#bbb' } }));
+  api.init({ theme: { accent: '#aaa', border: '#ccc' } });
+  assert.strictEqual(api.isOverridden('theme', 'border'), false);
+});
+
+test('returns true when server has no default for overridden key', () => {
+  const { api, ls } = loadCustomizer();
+  ls.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#bbb' } }));
+  api.init({});
+  assert.strictEqual(api.isOverridden('theme', 'accent'), true);
+});
+
+// ── Bug #518 Fixes ──
+
+test('phantom overrides cleaned on init — matching scalars removed', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { theme: { accent: '#4a9eff', border: '#e2e5ea' }, typeColors: { ADVERT: '#22c55e' } };
+  ls.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#4a9eff' }, typeColors: { ADVERT: '#22c55e' } }));
+  api.init(server);
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides') || '{}');
+  assert.ok(!delta.theme, 'phantom theme override should be cleaned');
+  assert.ok(!delta.typeColors, 'phantom typeColors override should be cleaned');
+});
+
+test('phantom overrides cleaned on init — matching arrays removed', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { home: { steps: [{ emoji: '📡', title: 'Go', description: 'Do it' }] } };
+  ls.setItem('cs-theme-overrides', JSON.stringify({ home: { steps: [{ emoji: '📡', title: 'Go', description: 'Do it' }] } }));
+  api.init(server);
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides') || '{}');
+  assert.ok(!delta.home, 'phantom home array override should be cleaned');
+});
+
+test('real overrides preserved after init cleanup', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { theme: { accent: '#4a9eff' } };
+  ls.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#ff0000' } }));
+  api.init(server);
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides'));
+  assert.strictEqual(delta.theme.accent, '#ff0000');
+});
+
+test('isOverridden handles array comparison via JSON.stringify', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { home: { steps: [{ emoji: '📡', title: 'Go', description: 'Do' }] } };
+  ls.setItem('cs-theme-overrides', JSON.stringify({ home: { steps: [{ emoji: '📡', title: 'Go', description: 'Do' }] } }));
+  api.init(server);
+  assert.strictEqual(api.isOverridden('home', 'steps'), false, 'matching array should not be overridden');
+});
+
+test('isOverridden returns true for differing arrays', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { home: { steps: [{ emoji: '📡', title: 'Go', description: 'Do' }] } };
+  ls.setItem('cs-theme-overrides', JSON.stringify({ home: { steps: [{ emoji: '🚀', title: 'New', description: 'Changed' }] } }));
+  api.init(server);
+  assert.strictEqual(api.isOverridden('home', 'steps'), true, 'differing array should be overridden');
+});
+
+test('setOverride prunes value matching server default', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { theme: { accent: '#4a9eff' } };
+  api.init(server);
+  api.setOverride('theme', 'accent', '#4a9eff');
+  // debounce fires synchronously in sandbox
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides') || '{}');
+  assert.ok(!delta.theme || !delta.theme.accent, 'matching value should be pruned after setOverride');
+});
+
+// ── Fix #2: _cleanPhantomOverrides when server has no section ──
+
+test('phantom overrides cleaned when server has NO home section', () => {
+  const { api, ls } = loadCustomizer();
+  // Server has theme but NO home — the common deployment case
+  const server = { theme: { accent: '#4a9eff' } };
+  ls.setItem('cs-theme-overrides', JSON.stringify({ home: { checklist: [], steps: [] } }));
+  api.init(server);
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides') || '{}');
+  assert.ok(!delta.home, 'phantom home override should be removed when server has no home section');
+});
+
+test('phantom overrides cleaned when server section is undefined — empty arrays removed', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { theme: { accent: '#4a9eff' }, nodeColors: { repeater: '#dc2626' } };
+  // timestamps has actual values (not phantom), home has empty arrays (phantom)
+  ls.setItem('cs-theme-overrides', JSON.stringify({
+    timestamps: { defaultMode: 'ago', timezone: 'local' },
+    home: { checklist: [], steps: [] }
+  }));
+  api.init(server);
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides') || '{}');
+  assert.ok(!delta.home, 'phantom home with empty arrays should be removed');
+  // timestamps has non-empty values — preserved even without server section
+  assert.ok(delta.timestamps, 'timestamps with actual values should be preserved');
+  assert.strictEqual(delta.timestamps.defaultMode, 'ago');
+});
+
+// ── Fix #4: setOverride with value matching server default is NOT stored ──
+
+test('setOverride with value matching server default is not stored', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { theme: { accent: '#4a9eff', border: '#e2e5ea' } };
+  api.init(server);
+  // Set override to same value as server default
+  api.setOverride('theme', 'accent', '#4a9eff');
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides') || '{}');
+  assert.ok(!delta.theme || !delta.theme.accent, 'value matching server default should not be stored');
+});
+
+test('existing user overrides are NOT pruned by setOverride on other keys', () => {
+  const { api, ls } = loadCustomizer();
+  const server = { theme: { accent: '#4a9eff', border: '#e2e5ea' } };
+  // User previously chose a custom accent (different from server default)
+  ls.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#ff0000' } }));
+  api.init(server);
+  // Now user changes border — accent should be preserved
+  api.setOverride('theme', 'border', '#00ff00');
+  const delta = JSON.parse(ls.getItem('cs-theme-overrides') || '{}');
+  assert.strictEqual(delta.theme.accent, '#ff0000', 'pre-existing custom override should be preserved');
+  assert.strictEqual(delta.theme.border, '#00ff00', 'new non-matching override should be stored');
+});
+
+// ── Summary ──
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`);
+process.exit(failed > 0 ? 1 : 0);

test-e2e-playwright.js

@@ -85,7 +85,7 @@ async function run() {
     await page.goto(BASE, { waitUntil: 'domcontentloaded' });
     await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
     await page.evaluate(() => {
-      localStorage.removeItem('meshcore-user-theme');
+      localStorage.removeItem('cs-theme-overrides');
       window.SITE_CONFIG = window.SITE_CONFIG || {};
       window.SITE_CONFIG.home = {
         heroTitle: 'Server Hero (E2E)',
@@ -122,18 +122,18 @@ async function run() {
     const homeTab = page.locator('.cust-tab[data-tab="home"]');
     await homeTab.waitFor({ state: 'visible', timeout: 10000 });
     await homeTab.click();
-    const heroInput = page.locator('#cust-heroTitle');
+    const heroInput = page.locator('[data-cv2-field="home.heroTitle"]');
     if (await heroInput.count() === 0) {
-      console.log('    ⏭️  #cust-heroTitle not found — TODO: requires running server');
+      console.log('    ⏭️  home.heroTitle input not found — TODO: requires running server');
       return;
     }
     await heroInput.waitFor({ state: 'visible', timeout: 10000 });
     await heroInput.fill(editedHero);
-    await page.waitForTimeout(700); // autoSave debounce is 500ms
+    await page.waitForTimeout(700); // debounce is 300ms, allow margin
     await page.reload({ waitUntil: 'domcontentloaded' });
     const persistedHero = await page.evaluate(() => {
       try {
-        const saved = JSON.parse(localStorage.getItem('meshcore-user-theme') || '{}');
+        const saved = JSON.parse(localStorage.getItem('cs-theme-overrides') || '{}');
         return saved && saved.home ? saved.home.heroTitle : '';
       } catch {
         return '';
@@ -363,8 +363,15 @@ async function run() {
 
   // Test 4: Packets page loads with filter
   await test('Packets page loads with filter', async () => {
+    // Ensure desktop viewport and broad time window so fixture timestamps are included.
+    await page.setViewportSize({ width: 1280, height: 720 });
+    // Set time window BEFORE packets.js IIFE re-executes (525600 min ≈ 1 year).
+    // Navigate to the packets URL then reload — avoids about:blank cross-origin issues
+    // that can prevent the SPA from fully initializing within the timeout.
     await page.goto(`${BASE}/#/packets`, { waitUntil: 'domcontentloaded' });
-    await page.waitForSelector('table tbody tr');
+    await page.evaluate(() => localStorage.setItem('meshcore-time-window', '525600'));
+    await page.reload({ waitUntil: 'load' });
+    await page.waitForSelector('table tbody tr', { timeout: 15000 });
     const rowsBefore = await page.$$('table tbody tr');
     assert(rowsBefore.length > 0, 'No packets visible');
     // Use the specific filter input
@@ -379,8 +386,7 @@ async function run() {
   });
 
   await test('Packets initial fetch honors persisted time window', async () => {
-    // Navigate to base first to get same-origin context for localStorage
-    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    // Set persisted time window to 60 min and reload so the IIFE reads it
     await page.evaluate(() => localStorage.setItem('meshcore-time-window', '60'));
 
     const packetsRequestPromise = page.waitForRequest((req) => {
@@ -392,8 +398,8 @@ async function run() {
       }
     }, { timeout: 10000 });
 
-    // Full reload to packets page — forces app to re-read localStorage
-    await page.evaluate(() => { window.location.href = window.location.origin + '/#/packets'; window.location.reload(); });
+    // Full reload on the packets page — scripts re-execute, IIFE reads localStorage
+    await page.reload({ waitUntil: 'load' });
     await page.waitForSelector('#fTimeWindow', { timeout: 10000 });
     const timeWindowValue = await page.$eval('#fTimeWindow', (el) => el.value);
     assert(timeWindowValue === '60', `Expected time window dropdown to restore 60, got ${timeWindowValue}`);
@@ -417,7 +423,10 @@ async function run() {
 
   // Test: Packets groupByHash toggle changes view
   await test('Packets groupByHash toggle works', async () => {
-    await page.waitForSelector('table tbody tr');
+    // Restore wide time window — previous test set it to 60 min which excludes fixture data
+    await page.evaluate(() => localStorage.setItem('meshcore-time-window', '525600'));
+    await page.reload({ waitUntil: 'load' });
+    await page.waitForSelector('table tbody tr', { timeout: 15000 });
     const groupBtn = await page.$('#fGroup');
     assert(groupBtn, 'Group by hash button (#fGroup) not found');
     // Check initial state (default is grouped/active)
@@ -541,7 +550,7 @@ async function run() {
     await page.goto(`${BASE}/#/analytics`, { waitUntil: 'domcontentloaded' });
     await page.waitForSelector('#analyticsTabs');
     const tabs = await page.$$('#analyticsTabs .tab-btn');
-    assert(tabs.length >= 8, `Expected >=8 analytics tabs, got ${tabs.length}`);
+    assert(tabs.length >= 10, `Expected >=10 analytics tabs, got ${tabs.length}`);
     // Overview tab should be active by default and show stat cards
     await page.waitForSelector('#analyticsContent .stat-card', { timeout: 8000 });
     const cards = await page.$$('#analyticsContent .stat-card');
@@ -615,6 +624,53 @@ async function run() {
     assert(content.length > 10, 'Distance tab should render content');
   });
 
+  await test('Analytics Neighbor Graph tab renders canvas and stats', async () => {
+    await page.click('[data-tab="neighbor-graph"]');
+    await page.waitForSelector('#ngCanvas', { timeout: 8000 });
+    const hasCanvas = await page.$('#ngCanvas');
+    assert(hasCanvas, 'Neighbor Graph tab should have a canvas element');
+    const hasStats = await page.$$eval('#ngStats .stat-card', els => els.length);
+    assert(hasStats >= 3, `Neighbor Graph stats should have >=3 cards, got ${hasStats}`);
+    // Verify filters exist
+    const hasSlider = await page.$('#ngMinScore');
+    assert(hasSlider, 'Should have min score slider');
+    const hasConfidence = await page.$('#ngConfidence');
+    assert(hasConfidence, 'Should have confidence filter');
+  });
+
+  await test('Analytics Neighbor Graph filter changes update stats', async () => {
+    // Capture edge count before filter
+    const edgesBefore = await page.$eval('#ngStats', el => {
+      const cards = el.querySelectorAll('.stat-card');
+      for (const c of cards) {
+        if (c.textContent.toLowerCase().includes('edge')) {
+          const m = c.textContent.match(/\d+/);
+          if (m) return parseInt(m[0], 10);
+        }
+      }
+      return -1;
+    });
+    // Set min score slider to high value to reduce edges
+    await page.$eval('#ngMinScore', el => { el.value = 90; el.dispatchEvent(new Event('input')); });
+    await page.waitForTimeout(300);
+    const edgesAfter = await page.$eval('#ngStats', el => {
+      const cards = el.querySelectorAll('.stat-card');
+      for (const c of cards) {
+        if (c.textContent.toLowerCase().includes('edge')) {
+          const m = c.textContent.match(/\d+/);
+          if (m) return parseInt(m[0], 10);
+        }
+      }
+      return -1;
+    });
+    assert(edgesBefore >= 0, 'Should find edge count in stats before filter');
+    assert(edgesAfter >= 0, 'Should find edge count in stats after filter');
+    assert(edgesAfter <= edgesBefore, `Raising min score should reduce (or keep) edge count: ${edgesBefore} → ${edgesAfter}`);
+    // Reset slider
+    await page.$eval('#ngMinScore', el => { el.value = 0; el.dispatchEvent(new Event('input')); });
+    await page.waitForTimeout(200);
+  });
+
   // --- Group: Compare page ---
 
   await test('Compare page loads with observer dropdowns', async () => {
@@ -1006,6 +1062,558 @@ async function run() {
     assert(hexDump, 'Hex dump should be visible after selecting a packet');
   });
 
+  // --- Group: Customizer v2 E2E tests ---
+
+  await test('Customizer v2: setOverride persists and applies CSS', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    // Force light mode — CI headless browsers may default to dark mode,
+    // and in dark mode themeDark.accent overwrites theme.accent in applyCSS
+    await page.evaluate(() => {
+      localStorage.setItem('meshcore-theme', 'light');
+      document.documentElement.setAttribute('data-theme', 'light');
+    });
+    // Clear any existing overrides
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+    // Wait for init() to complete (server config fetch + full pipeline) before
+    // setting override, so _runPipeline from init doesn't overwrite our value.
+    await page.waitForFunction(() => {
+      return window._customizerV2 && window._customizerV2.initDone;
+    }, { timeout: 5000 });
+    // Set an override via the API
+    const result = await page.evaluate(() => {
+      window._customizerV2.setOverride('theme', 'accent', '#ff0000');
+      // Wait for debounce (300ms) + buffer
+      return new Promise(resolve => setTimeout(() => {
+        const stored = JSON.parse(localStorage.getItem('cs-theme-overrides') || '{}');
+        const cssVal = getComputedStyle(document.documentElement).getPropertyValue('--accent').trim();
+        resolve({ stored, cssVal });
+      }, 500));
+    });
+    assert(result.stored.theme && result.stored.theme.accent === '#ff0000',
+      'Override not persisted to localStorage');
+    assert(result.cssVal === '#ff0000',
+      `CSS variable --accent expected #ff0000 but got "${result.cssVal}"`);
+    // Cleanup
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+  });
+
+  await test('Customizer v2: clearOverride resets to server default', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    // Force light mode for consistent CSS testing
+    await page.evaluate(() => {
+      localStorage.setItem('meshcore-theme', 'light');
+      document.documentElement.setAttribute('data-theme', 'light');
+    });
+    // Wait for init() to complete so _serverDefaults is populated
+    await page.waitForFunction(() => {
+      return window._customizerV2 && window._customizerV2.initDone;
+    }, { timeout: 5000 });
+    const result = await page.evaluate(() => {
+      // Set the server default accent
+      window._customizerV2.setOverride('theme', 'accent', '#ff0000');
+      return new Promise(resolve => setTimeout(() => {
+        window._customizerV2.clearOverride('theme', 'accent');
+        const stored = JSON.parse(localStorage.getItem('cs-theme-overrides') || '{}');
+        const hasAccent = stored.theme && stored.theme.hasOwnProperty('accent');
+        resolve({ hasAccent });
+      }, 500));
+    });
+    assert(!result.hasAccent, 'accent should be removed from overrides after clearOverride');
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+  });
+
+  await test('Customizer v2: full reset clears all overrides', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    const result = await page.evaluate(() => {
+      if (!window._customizerV2) return { error: 'customizerV2 not loaded' };
+      localStorage.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#ff0000' }, nodeColors: { repeater: '#00ff00' } }));
+      // Simulate full reset
+      localStorage.removeItem('cs-theme-overrides');
+      const stored = localStorage.getItem('cs-theme-overrides');
+      return { stored };
+    });
+    assert(!result.error, result.error || '');
+    assert(result.stored === null, 'cs-theme-overrides should be null after full reset');
+  });
+
+  await test('Customizer v2: export produces valid JSON', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    const result = await page.evaluate(() => {
+      if (!window._customizerV2) return { error: 'customizerV2 not loaded' };
+      // Set some overrides
+      localStorage.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#123456' } }));
+      const delta = window._customizerV2.readOverrides();
+      const json = JSON.stringify(delta, null, 2);
+      try { JSON.parse(json); return { valid: true, hasAccent: delta.theme && delta.theme.accent === '#123456' }; }
+      catch { return { valid: false }; }
+    });
+    assert(!result.error, result.error || '');
+    assert(result.valid, 'Exported JSON must be valid');
+    assert(result.hasAccent, 'Exported JSON must contain the stored override');
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+  });
+
+  await test('Customizer v2: import applies overrides', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    const result = await page.evaluate(() => {
+      if (!window._customizerV2) return { error: 'customizerV2 not loaded' };
+      localStorage.removeItem('cs-theme-overrides');
+      const importData = { theme: { accent: '#abcdef' }, nodeColors: { repeater: '#112233' } };
+      const validation = window._customizerV2.validateShape(importData);
+      if (!validation.valid) return { error: 'Validation failed: ' + validation.errors.join(', ') };
+      window._customizerV2.writeOverrides(importData);
+      const stored = window._customizerV2.readOverrides();
+      return { accent: stored.theme && stored.theme.accent, repeater: stored.nodeColors && stored.nodeColors.repeater };
+    });
+    assert(!result.error, result.error || '');
+    assert(result.accent === '#abcdef', 'Imported accent should be #abcdef');
+    assert(result.repeater === '#112233', 'Imported repeater should be #112233');
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+  });
+
+  await test('Customizer v2: migration from legacy keys', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    const result = await page.evaluate(() => {
+      if (!window._customizerV2) return { error: 'customizerV2 not loaded' };
+      // Clear new key so migration can run
+      localStorage.removeItem('cs-theme-overrides');
+      // Set legacy keys
+      localStorage.setItem('meshcore-user-theme', JSON.stringify({ theme: { accent: '#aabb01' }, branding: { siteName: 'LegacyName' } }));
+      localStorage.setItem('meshcore-timestamp-mode', 'absolute');
+      localStorage.setItem('meshcore-heatmap-opacity', '0.5');
+      // Run migration
+      const migrated = window._customizerV2.migrateOldKeys();
+      const stored = window._customizerV2.readOverrides();
+      const legacyGone = localStorage.getItem('meshcore-user-theme') === null &&
+                         localStorage.getItem('meshcore-timestamp-mode') === null &&
+                         localStorage.getItem('meshcore-heatmap-opacity') === null;
+      return {
+        migrated: !!migrated,
+        accent: stored.theme && stored.theme.accent,
+        siteName: stored.branding && stored.branding.siteName,
+        tsMode: stored.timestamps && stored.timestamps.defaultMode,
+        opacity: stored.heatmapOpacity,
+        legacyGone
+      };
+    });
+    assert(!result.error, result.error || '');
+    assert(result.migrated, 'migrateOldKeys should return non-null');
+    assert(result.accent === '#aabb01', 'Theme accent should be migrated');
+    assert(result.siteName === 'LegacyName', 'Branding should be migrated');
+    assert(result.tsMode === 'absolute', 'Timestamp mode should be migrated');
+    assert(result.opacity === 0.5, 'Heatmap opacity should be migrated');
+    assert(result.legacyGone, 'Legacy keys should be removed after migration');
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+  });
+
+  await test('Customizer v2: browser-local banner visible', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    // Open customizer
+    const toggleSel = '#customizeToggle, button[title*="ustom" i], [class*="customize"]';
+    const btn = await page.$(toggleSel);
+    if (!btn) { console.log('    ⏭️  Customizer toggle not found'); return; }
+    await btn.click();
+    await page.waitForSelector('.cv2-local-banner', { timeout: 5000 });
+    const bannerText = await page.$eval('.cv2-local-banner', el => el.textContent);
+    assert(bannerText.includes('browser only'), `Banner should mention "browser only" but got "${bannerText}"`);
+  });
+
+  await test('Customizer v2: auto-save status indicator', async () => {
+    // Panel should already be open from previous test
+    const statusEl = await page.$('#cv2-save-status');
+    if (!statusEl) { console.log('    ⏭️  Save status element not found'); return; }
+    const statusText = await page.$eval('#cv2-save-status', el => el.textContent);
+    assert(statusText.includes('saved') || statusText.includes('Saving'),
+      `Status should show save state but got "${statusText}"`);
+  });
+
+  await test('Customizer v2: override indicator appears and disappears', async () => {
+    // Set override BEFORE page load so _renderTheme sees it during init
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.evaluate(() => {
+      // Force light mode so theme tab renders 'theme' section (not 'themeDark')
+      localStorage.setItem('meshcore-theme', 'light');
+      localStorage.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#ff0000' } }));
+    });
+    // Reload so customizer v2 initializes with the override in place
+    await page.reload({ waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    // Ensure light mode is active (CI headless may default to dark)
+    await page.evaluate(() => document.documentElement.setAttribute('data-theme', 'light'));
+    const result = await page.evaluate(() => {
+      if (!window._customizerV2) return { error: 'customizerV2 not loaded' };
+      return { ok: true };
+    });
+    assert(!result.error, result.error || '');
+    // Open customizer and check for override dot
+    const toggleSel = '#customizeToggle, button[title*="ustom" i], [class*="customize"]';
+    const btn = await page.$(toggleSel);
+    if (!btn) { console.log('    ⏭️  Customizer toggle not found'); return; }
+    await btn.click();
+    await page.waitForSelector('.cust-overlay', { timeout: 5000 });
+    // Click theme tab
+    const themeTab = await page.$('.cust-tab[data-tab="theme"]');
+    if (themeTab) await themeTab.click();
+    await page.waitForTimeout(200);
+    // Check for override dot
+    const dots = await page.$$('.cv2-override-dot');
+    assert(dots.length > 0, 'Override dot should be visible when overrides exist');
+    // Clear overrides and reload to verify dots disappear
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+    await page.reload({ waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    const btn2 = await page.$(toggleSel);
+    if (btn2) await btn2.click();
+    await page.waitForSelector('.cust-overlay', { timeout: 5000 });
+    const themeTab2 = await page.$('.cust-tab[data-tab="theme"]');
+    if (themeTab2) await themeTab2.click();
+    await page.waitForTimeout(200);
+    const dotsAfter = await page.$$('.cv2-override-dot');
+    assert(dotsAfter.length === 0, 'Override dots should disappear after clearing overrides');
+  });
+
+  await test('Customizer v2: presets apply through standard pipeline', async () => {
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+    const toggleSel = '#customizeToggle, button[title*="ustom" i], [class*="customize"]';
+    const btn = await page.$(toggleSel);
+    if (!btn) { console.log('    ⏭️  Customizer toggle not found'); return; }
+    await btn.click();
+    await page.waitForSelector('.cust-overlay', { timeout: 5000 });
+    // Click theme tab
+    const themeTab = await page.$('.cust-tab[data-tab="theme"]');
+    if (themeTab) await themeTab.click();
+    await page.waitForTimeout(200);
+    // Click ocean preset
+    const oceanBtn = await page.$('.cust-preset-btn[data-preset="ocean"]');
+    if (!oceanBtn) { console.log('    ⏭️  Ocean preset button not found'); return; }
+    await oceanBtn.click();
+    await page.waitForTimeout(300);
+    const result = await page.evaluate(() => {
+      const stored = JSON.parse(localStorage.getItem('cs-theme-overrides') || '{}');
+      const cssAccent = getComputedStyle(document.documentElement).getPropertyValue('--accent').trim();
+      return { hasTheme: !!stored.theme, cssAccent };
+    });
+    assert(result.hasTheme, 'Preset should write theme to localStorage');
+    assert(result.cssAccent.length > 0, 'CSS accent should be set after preset');
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+  });
+
+  await test('Customizer v2: page load applies overrides from localStorage', async () => {
+    // Set overrides BEFORE navigating
+    await page.goto(BASE, { waitUntil: 'domcontentloaded' });
+    await page.evaluate(() => {
+      localStorage.setItem('cs-theme-overrides', JSON.stringify({ theme: { accent: '#ee1122' } }));
+    });
+    // Reload to trigger init with overrides
+    await page.reload({ waitUntil: 'domcontentloaded' });
+    await page.waitForSelector('nav, .navbar, .nav, [class*="nav"]');
+    await page.waitForTimeout(500); // allow pipeline to run
+    const cssAccent = await page.evaluate(() =>
+      getComputedStyle(document.documentElement).getPropertyValue('--accent').trim()
+    );
+    assert(cssAccent === '#ee1122', `Page load should apply override accent #ee1122 but got "${cssAccent}"`);
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+  });
+
+
+  await test('Show Neighbors populates neighborPubkeys from affinity API', async () => {
+    const testPubkey = 'aabbccdd11223344556677889900aabbccddeeff00112233445566778899001122';
+    const neighborPubkey1 = '1111111111111111111111111111111111111111111111111111111111111111';
+    const neighborPubkey2 = '2222222222222222222222222222222222222222222222222222222222222222';
+
+    await page.route(`**/api/nodes/${testPubkey}/neighbors*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          node: testPubkey,
+          neighbors: [
+            { pubkey: neighborPubkey1, prefix: '11', name: 'Neighbor-1', role: 'repeater', count: 50, score: 0.9, ambiguous: false },
+            { pubkey: neighborPubkey2, prefix: '22', name: 'Neighbor-2', role: 'companion', count: 20, score: 0.7, ambiguous: false }
+          ],
+          total_observations: 70
+        })
+      });
+    });
+
+    await page.goto(`${BASE}/#/map`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(1500);
+
+    const result = await page.evaluate(async (args) => {
+      if (typeof window._mapSelectRefNode !== 'function') return { error: 'no _mapSelectRefNode' };
+      await window._mapSelectRefNode(args.pk, 'TestNode');
+      return { neighbors: window._mapGetNeighborPubkeys() };
+    }, { pk: testPubkey });
+
+    assert(!result.error, result.error || '');
+    assert(result.neighbors.includes(neighborPubkey1), 'Should contain neighbor1');
+    assert(result.neighbors.includes(neighborPubkey2), 'Should contain neighbor2');
+    assert(result.neighbors.length === 2, `Expected 2 neighbors, got ${result.neighbors.length}`);
+    await page.unroute(`**/api/nodes/${testPubkey}/neighbors*`);
+  });
+
+  await test('Show Neighbors resolves correct node on hash collision via affinity API', async () => {
+    const nodeA = 'c0dedad4208acb6cbe44b848943fc6d3c5d43cf38a21e48b43826a70862980e4';
+    const nodeB = 'c0f1a2b3000000000000000000000000000000000000000000000000000000ff';
+    const neighborR1 = 'r1aaaaaa000000000000000000000000000000000000000000000000000000aa';
+    const neighborR2 = 'r2bbbbbb000000000000000000000000000000000000000000000000000000bb';
+    const neighborR4 = 'r4dddddd000000000000000000000000000000000000000000000000000000dd';
+
+    await page.route(`**/api/nodes/${nodeA}/neighbors*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          node: nodeA,
+          neighbors: [
+            { pubkey: neighborR1, prefix: 'R1', name: 'Repeater-R1', role: 'repeater', count: 100, score: 0.95, ambiguous: false },
+            { pubkey: neighborR2, prefix: 'R2', name: 'Repeater-R2', role: 'repeater', count: 80, score: 0.85, ambiguous: false }
+          ],
+          total_observations: 180
+        })
+      });
+    });
+
+    await page.route(`**/api/nodes/${nodeB}/neighbors*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          node: nodeB,
+          neighbors: [
+            { pubkey: neighborR4, prefix: 'R4', name: 'Repeater-R4', role: 'repeater', count: 60, score: 0.75, ambiguous: false }
+          ],
+          total_observations: 60
+        })
+      });
+    });
+
+    await page.goto(`${BASE}/#/map`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(1500);
+
+    // Select Node A — should get R1, R2 but NOT R4
+    const resultA = await page.evaluate(async (pk) => {
+      await window._mapSelectRefNode(pk, 'NodeA');
+      return window._mapGetNeighborPubkeys();
+    }, nodeA);
+    assert(resultA.includes(neighborR1), 'Node A should have R1');
+    assert(resultA.includes(neighborR2), 'Node A should have R2');
+    assert(!resultA.includes(neighborR4), 'Node A should NOT have R4');
+
+    // Select Node B — should get R4 but NOT R1, R2
+    const resultB = await page.evaluate(async (pk) => {
+      await window._mapSelectRefNode(pk, 'NodeB');
+      return window._mapGetNeighborPubkeys();
+    }, nodeB);
+    assert(resultB.includes(neighborR4), 'Node B should have R4');
+    assert(!resultB.includes(neighborR1), 'Node B should NOT have R1');
+    assert(!resultB.includes(neighborR2), 'Node B should NOT have R2');
+
+    await page.unroute(`**/api/nodes/${nodeA}/neighbors*`);
+    await page.unroute(`**/api/nodes/${nodeB}/neighbors*`);
+  });
+
+  await test('Show Neighbors falls back to path walking when affinity API returns empty', async () => {
+    const testPubkey = 'fallbacktest0000000000000000000000000000000000000000000000000000';
+    const hopBefore = 'aaaa000000000000000000000000000000000000000000000000000000000000';
+    const hopAfter = 'bbbb000000000000000000000000000000000000000000000000000000000000';
+
+    await page.route(`**/api/nodes/${testPubkey}/neighbors*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ node: testPubkey, neighbors: [], total_observations: 0 })
+      });
+    });
+
+    await page.route(`**/api/nodes/${testPubkey}/paths*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          paths: [{
+            hops: [
+              { pubkey: hopBefore, name: 'HopBefore' },
+              { pubkey: testPubkey, name: 'Self' },
+              { pubkey: hopAfter, name: 'HopAfter' }
+            ]
+          }]
+        })
+      });
+    });
+
+    await page.goto(`${BASE}/#/map`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(1500);
+
+    const result = await page.evaluate(async (pk) => {
+      if (typeof window._mapSelectRefNode !== 'function') return { error: 'no-function' };
+      await window._mapSelectRefNode(pk, 'FallbackNode');
+      return { neighbors: window._mapGetNeighborPubkeys() };
+    }, testPubkey);
+
+    assert(!result.error, result.error || '');
+    assert(result.neighbors.includes(hopBefore), 'Fallback should find hopBefore');
+    assert(result.neighbors.includes(hopAfter), 'Fallback should find hopAfter');
+    assert(result.neighbors.length === 2, `Expected 2 fallback neighbors, got ${result.neighbors.length}`);
+    await page.unroute(`**/api/nodes/${testPubkey}/neighbors*`);
+    await page.unroute(`**/api/nodes/${testPubkey}/paths*`);
+  });
+  // ─── Neighbor section tests ───────────────────────────────────────────────
+
+  await test('Node detail: neighbors section exists with correct columns', async () => {
+    // Navigate to a node detail page (use the first node in the list)
+    await page.goto(BASE + '/#/nodes');
+    await page.waitForSelector('#nodesBody tr[data-key]', { timeout: 10000 });
+    // Get the first node's pubkey from the row's data-key attribute
+    const pubkey = await page.$eval('#nodesBody tr[data-key]', el => el.dataset.key);
+    await page.goto(BASE + '/#/nodes/' + pubkey);
+    await page.waitForSelector('#node-neighbors', { timeout: 10000 });
+    // Check the section exists
+    const header = await page.$eval('#fullNeighborsHeader', el => el.textContent);
+    assert(header.startsWith('Neighbors'), 'Header should start with "Neighbors", got: ' + header);
+    // Wait for content to load (either table or empty state)
+    await page.waitForFunction(() => {
+      const el = document.getElementById('fullNeighborsContent');
+      return el && !el.innerHTML.includes('spinner');
+    }, { timeout: 10000 });
+    const hasTable = await page.$('#fullNeighborsContent .data-table');
+    if (hasTable) {
+      // Check columns
+      const headers = await page.$$eval('#fullNeighborsContent thead th', ths => ths.map(t => t.textContent));
+      assert(headers.includes('Neighbor'), 'Should have Neighbor column');
+      assert(headers.includes('Role'), 'Should have Role column');
+      assert(headers.includes('Score'), 'Should have Score column');
+      assert(headers.includes('Obs'), 'Should have Obs column');
+      assert(headers.includes('Last Seen'), 'Should have Last Seen column');
+      assert(headers.includes('Conf'), 'Should have Conf column');
+    } else {
+      // Empty state
+      const text = await page.$eval('#fullNeighborsContent', el => el.textContent);
+      assert(text.includes('No neighbor data') || text.includes('Could not load'), 'Should show empty or error state');
+    }
+  });
+
+
+  // ─── End neighbor section tests ───────────────────────────────────────────
+
+  // ─── Affinity debug overlay tests ─────────────────────────────────────────
+
+  await test('Map: affinity debug checkbox exists in DOM', async () => {
+    await page.goto(BASE + '/#/map');
+    await page.waitForSelector('#mapControls', { timeout: 5000 });
+    const checkbox = await page.$('#mcAffinityDebug');
+    assert(checkbox !== null, 'Affinity debug checkbox should exist in DOM');
+  });
+
+  await test('Map: affinity debug checkbox toggles without crash', async () => {
+    await page.goto(BASE + '/#/map');
+    await page.waitForSelector('#mapControls', { timeout: 5000 });
+    // Make the checkbox visible by setting localStorage
+    await page.evaluate(() => localStorage.setItem('meshcore-affinity-debug', 'true'));
+    await page.reload();
+    await page.waitForSelector('#mapControls', { timeout: 5000 });
+    const label = await page.$('#mcAffinityDebugLabel');
+    if (label) {
+      const display = await label.evaluate(el => getComputedStyle(el).display);
+      // When debugAffinity or localStorage is set, label should be visible
+      // Just verify toggling doesn't crash
+      const cb = await page.$('#mcAffinityDebug');
+      if (cb) {
+        await cb.click();
+        // Wait a bit for fetch to complete (or fail gracefully)
+        await page.waitForTimeout(500);
+        await cb.click();
+        await page.waitForTimeout(200);
+      }
+    }
+    // Clean up
+    await page.evaluate(() => localStorage.removeItem('meshcore-affinity-debug'));
+    assert(true, 'Toggle did not crash');
+  });
+
+  await test('Node detail: affinity debug section expandable', async () => {
+    await page.goto(BASE + '/#/nodes');
+    await page.waitForSelector('#nodesBody tr[data-key]', { timeout: 10000 });
+    // Enable debug mode
+    await page.evaluate(() => localStorage.setItem('meshcore-affinity-debug', 'true'));
+    // Click first node to go to detail
+    const nodeLink = await page.$('a[href*="/nodes/"]');
+    if (nodeLink) {
+      await nodeLink.click();
+      await page.waitForTimeout(1000);
+      const debugPanel = await page.$('#node-affinity-debug');
+      if (debugPanel) {
+        const display = await debugPanel.evaluate(el => el.style.display);
+        // Panel should be visible when debug is enabled
+        const header = await debugPanel.$('h4');
+        if (header) {
+          // Click to expand
+          await header.click();
+          await page.waitForTimeout(300);
+          const body = await debugPanel.$('.affinity-debug-body');
+          if (body) {
+            const bodyDisplay = await body.evaluate(el => el.style.display);
+            assert(bodyDisplay !== 'none', 'Debug body should be expanded after click');
+          }
+        }
+      }
+    }
+    await page.evaluate(() => localStorage.removeItem('meshcore-affinity-debug'));
+    assert(true, 'Debug panel expansion works');
+  });
+
+  // ─── End affinity debug tests ─────────────────────────────────────────────
+
+  // ─── Mobile filter dropdown tests (#534) ──────────────────────────────────
+
+  await test('Mobile: filter toggle expands filter bar on packets page (#534)', async () => {
+    // Use a mobile viewport
+    await page.setViewportSize({ width: 480, height: 800 });
+    await page.goto(`${BASE}/#/packets`);
+    await page.waitForTimeout(500);
+
+    const filterBar = await page.$('.filter-bar');
+    assert(filterBar, 'Filter bar should exist on packets page');
+
+    // Before clicking toggle, filter inputs should be hidden
+    const toggleBtn = await page.$('.filter-toggle-btn');
+    assert(toggleBtn, 'Filter toggle button should exist on mobile');
+
+    await toggleBtn.click();
+    await page.waitForTimeout(300);
+
+    // After clicking, .filters-expanded should be on the filter bar
+    const expanded = await filterBar.evaluate(el => el.classList.contains('filters-expanded'));
+    assert(expanded, 'Filter bar should have filters-expanded class after toggle');
+
+    // Filter inputs should now be visible
+    const filterInput = await page.$('.filter-bar input');
+    if (filterInput) {
+      const display = await filterInput.evaluate(el => getComputedStyle(el).display);
+      assert(display !== 'none', `Filter input should be visible when expanded, got display: ${display}`);
+    }
+
+    const filterSelect = await page.$('.filter-bar select');
+    if (filterSelect) {
+      const display = await filterSelect.evaluate(el => getComputedStyle(el).display);
+      assert(display !== 'none', `Filter select should be visible when expanded, got display: ${display}`);
+    }
+
+    // Reset viewport
+    await page.setViewportSize({ width: 1280, height: 720 });
+  });
+
+  // ─── End mobile filter tests ──────────────────────────────────────────────
+
   // Extract frontend coverage if instrumented server is running
   try {
     const coverage = await page.evaluate(() => window.__coverage__);

test-hop-resolver-affinity.js

@@ -0,0 +1,99 @@
+/**
+ * Unit tests for HopResolver affinity-aware hop resolution.
+ */
+'use strict';
+const fs = require('fs');
+const vm = require('vm');
+
+// Load hop-resolver.js in a sandboxed context
+const code = fs.readFileSync(__dirname + '/public/hop-resolver.js', 'utf8');
+const sandbox = { window: {}, console, Math, Object, Array, Number, Date, Map, Set, parseInt, parseFloat, encodeURIComponent };
+vm.createContext(sandbox);
+vm.runInContext(code, sandbox);
+const HopResolver = sandbox.window.HopResolver;
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, msg) {
+  if (condition) { passed++; console.log('  ✓ ' + msg); }
+  else { failed++; console.error('  ✗ ' + msg); }
+}
+
+// ── Test nodes ──
+// Two nodes share the same 1-byte prefix "ab"
+const nodeA = { public_key: 'ab1111', name: 'NodeA', lat: 37.0, lon: -122.0 };
+const nodeB = { public_key: 'ab2222', name: 'NodeB', lat: 38.0, lon: -123.0 };
+const nodeC = { public_key: 'cd3333', name: 'NodeC', lat: 37.5, lon: -122.5 };
+
+console.log('\n=== HopResolver Affinity Tests ===\n');
+
+// Test 1: Affinity prefers neighbor candidate over geo-closest
+console.log('Test 1: Affinity prefers neighbor over geo-closest');
+HopResolver.init([nodeA, nodeB, nodeC]);
+HopResolver.setAffinity({
+  edges: [
+    { source: 'cd3333', target: 'ab2222', score: 0.8 }
+    // NodeC is a neighbor of NodeB but NOT NodeA
+  ]
+});
+
+// Resolve hop "ab" after NodeC was resolved — should pick NodeB (neighbor) not NodeA (geo-closer)
+// Origin at NodeC's position so forward pass runs with NodeC as anchor
+const result1 = HopResolver.resolve(['cd33', 'ab'], nodeC.lat, nodeC.lon, null, null, null);
+assert(result1['ab'].name === 'NodeB', 'Should pick NodeB (affinity neighbor of NodeC) — got: ' + result1['ab'].name);
+
+// Test 2: Without affinity, falls back to geo-closest
+console.log('\nTest 2: Cold start (no affinity) falls back to geo-closest');
+HopResolver.init([nodeA, nodeB, nodeC]);
+HopResolver.setAffinity({}); // No edges
+
+// With anchor at NodeC's position, NodeA is closer to NodeC than NodeB
+const result2 = HopResolver.resolve(['cd33', 'ab'], nodeC.lat, nodeC.lon, null, null, null);
+// NodeA (37, -122) is closer to NodeC (37.5, -122.5) than NodeB (38, -123)
+assert(result2['ab'].name === 'NodeA', 'Should pick NodeA (geo-closest) — got: ' + result2['ab'].name);
+
+// Test 3: setAffinity with null/undefined doesn't crash
+console.log('\nTest 3: setAffinity with null/undefined is safe');
+HopResolver.setAffinity(null);
+HopResolver.setAffinity(undefined);
+HopResolver.setAffinity({});
+assert(true, 'No crash on null/undefined/empty affinity');
+
+// Test 4: getAffinity returns correct scores
+console.log('\nTest 4: getAffinity returns correct scores');
+HopResolver.setAffinity({
+  edges: [
+    { source: 'aaa', target: 'bbb', score: 0.95 },
+    { source: 'ccc', target: 'ddd', weight: 5 }
+  ]
+});
+assert(HopResolver.getAffinity('aaa', 'bbb') === 0.95, 'aaa→bbb = 0.95');
+assert(HopResolver.getAffinity('bbb', 'aaa') === 0.95, 'bbb→aaa = 0.95 (bidirectional)');
+assert(HopResolver.getAffinity('ccc', 'ddd') === 5, 'ccc→ddd = 5 (weight fallback)');
+assert(HopResolver.getAffinity('aaa', 'zzz') === 0, 'unknown pair = 0');
+assert(HopResolver.getAffinity(null, 'bbb') === 0, 'null pubkey = 0');
+
+// Test 5: Affinity with multiple neighbors — highest score wins
+console.log('\nTest 5: Highest affinity score wins among neighbors');
+HopResolver.init([nodeA, nodeB, nodeC]);
+HopResolver.setAffinity({
+  edges: [
+    { source: 'cd3333', target: 'ab1111', score: 0.3 },
+    { source: 'cd3333', target: 'ab2222', score: 0.9 }
+  ]
+});
+const result5 = HopResolver.resolve(['cd33', 'ab'], nodeC.lat, nodeC.lon, null, null, null);
+assert(result5['ab'].name === 'NodeB', 'Should pick NodeB (highest affinity 0.9) — got: ' + result5['ab'].name);
+
+// Test 6: Unambiguous hops are not affected by affinity
+console.log('\nTest 6: Unambiguous hops unaffected by affinity');
+const nodeD = { public_key: 'ee4444', name: 'NodeD', lat: 36.0, lon: -121.0 };
+HopResolver.init([nodeA, nodeB, nodeC, nodeD]);
+HopResolver.setAffinity({ edges: [] });
+const result6 = HopResolver.resolve(['ee44'], null, null, null, null, null);
+assert(result6['ee44'].name === 'NodeD', 'Unique prefix resolves directly — got: ' + result6['ee44'].name);
+assert(!result6['ee44'].ambiguous, 'Should not be marked ambiguous');
+
+console.log('\n' + (passed + failed) + ' tests, ' + passed + ' passed, ' + failed + ' failed\n');
+process.exit(failed > 0 ? 1 : 0);

test-live-anims.js

@@ -0,0 +1,128 @@
+/* Unit tests for live.js animation system — verifies rAF migration and concurrency cap */
+'use strict';
+const fs = require('fs');
+const assert = require('assert');
+
+const src = fs.readFileSync('public/live.js', 'utf8');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ✅ ${name}`); }
+  catch (e) { failed++; console.log(`  ❌ ${name}: ${e.message}`); }
+}
+
+console.log('\n=== Animation interval elimination ===');
+
+test('pulseNode does not use setInterval', () => {
+  // Extract pulseNode function body
+  const pulseStart = src.indexOf('function pulseNode(');
+  const nextFn = src.indexOf('\n  function ', pulseStart + 1);
+  const body = src.substring(pulseStart, nextFn);
+  assert.ok(!body.includes('setInterval'), 'pulseNode still uses setInterval');
+  assert.ok(body.includes('requestAnimationFrame'), 'pulseNode should use requestAnimationFrame');
+});
+
+test('drawAnimatedLine does not use setInterval', () => {
+  const drawStart = src.indexOf('function drawAnimatedLine(');
+  const nextFn = src.indexOf('\n  function ', drawStart + 1);
+  const body = src.substring(drawStart, nextFn);
+  assert.ok(!body.includes('setInterval'), 'drawAnimatedLine still uses setInterval');
+  assert.ok(body.includes('requestAnimationFrame'), 'drawAnimatedLine should use requestAnimationFrame');
+});
+
+test('ghost hop pulse does not use setInterval', () => {
+  // Ghost pulse is inside animatePath
+  const animStart = src.indexOf('function animatePath(');
+  const animEnd = src.indexOf('\n  function ', animStart + 1);
+  const body = src.substring(animStart, animEnd);
+  assert.ok(!body.includes('setInterval'), 'animatePath still uses setInterval');
+});
+
+console.log('\n=== Concurrency cap ===');
+
+test('MAX_CONCURRENT_ANIMS is defined', () => {
+  assert.ok(src.includes('MAX_CONCURRENT_ANIMS'), 'MAX_CONCURRENT_ANIMS constant not found');
+});
+
+test('MAX_CONCURRENT_ANIMS is set to 20', () => {
+  const match = src.match(/MAX_CONCURRENT_ANIMS\s*=\s*(\d+)/);
+  assert.ok(match, 'Could not parse MAX_CONCURRENT_ANIMS value');
+  assert.strictEqual(parseInt(match[1]), 20);
+});
+
+test('animatePath checks MAX_CONCURRENT_ANIMS before proceeding', () => {
+  const animStart = src.indexOf('function animatePath(');
+  // Check that within the first 200 chars of the function, we check the cap
+  const snippet = src.substring(animStart, animStart + 300);
+  assert.ok(snippet.includes('activeAnims >= MAX_CONCURRENT_ANIMS'), 'animatePath should check activeAnims against cap');
+});
+
+console.log('\n=== Safety: no stale setInterval in animation functions ===');
+
+test('no setInterval remains in animation hot path', () => {
+  // The only acceptable setIntervals are the UI ones (timeline, clock, prune, rate counter)
+  // Count total setInterval occurrences
+  const matches = src.match(/setInterval\(/g) || [];
+  // Count known OK ones: _timelineRefreshInterval, _lcdClockInterval, _pruneInterval, _rateCounterInterval
+  const okPatterns = ['_timelineRefreshInterval', '_lcdClockInterval', '_pruneInterval', '_rateCounterInterval'];
+  let okCount = 0;
+  for (const p of okPatterns) {
+    if (src.includes(p + ' = setInterval') || src.includes(p + '= setInterval')) okCount++;
+  }
+  // Allow some non-animation setIntervals (the 4 UI ones above)
+  assert.ok(matches.length <= okCount + 1, 
+    `Found ${matches.length} setInterval calls, expected at most ${okCount + 1} (non-animation). Some animation setIntervals may remain.`);
+});
+
+console.log(`\n${passed} passed, ${failed} failed\n`);
+if (failed > 0) process.exit(1);
+
+/* === Null-guard coverage for rAF callbacks === */
+const src2 = fs.readFileSync('public/live.js', 'utf8');
+let p2 = 0, f2 = 0;
+function test2(name, fn) {
+  try { fn(); p2++; console.log(`  ✅ ${name}`); }
+  catch (e) { f2++; console.log(`  ❌ ${name}: ${e.message}`); }
+}
+
+console.log('\n=== Null guards on rAF animation callbacks ===');
+
+test2('animatePath tick() has null guard', () => {
+  // tick is inside animatePath, after "function tick(now)"
+  const tickStart = src2.indexOf('function tick(now)');
+  const tickBody = src2.substring(tickStart, tickStart + 200);
+  assert.ok(tickBody.includes('!animLayer || !pathsLayer'), 'tick() missing animLayer/pathsLayer null guard');
+});
+
+test2('animatePath fadeOut() has null guard', () => {
+  const fadeOutStart = src2.indexOf('function fadeOut(now)');
+  const fadeOutBody = src2.substring(fadeOutStart, fadeOutStart + 200);
+  assert.ok(fadeOutBody.includes('!animLayer || !pathsLayer'), 'fadeOut() missing animLayer/pathsLayer null guard');
+});
+
+test2('drawAnimatedLine animateLine() has null guard', () => {
+  const lineStart = src2.indexOf('function animateLine(now)');
+  const lineBody = src2.substring(lineStart, lineStart + 200);
+  assert.ok(lineBody.includes('!animLayer || !pathsLayer'), 'animateLine() missing animLayer/pathsLayer null guard');
+});
+
+test2('drawAnimatedLine animateFade() has null guard', () => {
+  const fadeStart = src2.indexOf('function animateFade(now)');
+  const fadeBody = src2.substring(fadeStart, fadeStart + 200);
+  assert.ok(fadeBody.includes('!pathsLayer'), 'animateFade() missing pathsLayer null guard');
+});
+
+test2('pulseNode animatePulse() has null guard', () => {
+  const pulseStart = src2.indexOf('function animatePulse(now)');
+  const pulseBody = src2.substring(pulseStart, pulseStart + 200);
+  assert.ok(pulseBody.includes('!animLayer'), 'animatePulse() missing animLayer null guard');
+});
+
+test2('ghostPulse has null guard', () => {
+  const ghostStart = src2.indexOf('function ghostPulse(now)');
+  const ghostBody = src2.substring(ghostStart, ghostStart + 200);
+  assert.ok(ghostBody.includes('!animLayer'), 'ghostPulse() missing animLayer null guard');
+});
+
+console.log(`\n${p2} passed, ${f2} failed\n`);
+if (f2 > 0) process.exit(1);

test-live.js

@@ -0,0 +1,906 @@
+/* Unit tests for live.js functions (tested via VM sandbox)
+ * Part of #344 — live.js coverage
+ */
+'use strict';
+const vm = require('vm');
+const fs = require('fs');
+const assert = require('assert');
+
+let passed = 0, failed = 0;
+const pendingTests = [];
+function test(name, fn) {
+  try {
+    const out = fn();
+    if (out && typeof out.then === 'function') {
+      pendingTests.push(
+        out.then(() => { passed++; console.log(`  ✅ ${name}`); })
+        .catch((e) => { failed++; console.log(`  ❌ ${name}: ${e.message}`); })
+      );
+      return;
+    }
+    passed++; console.log(`  ✅ ${name}`);
+  } catch (e) { failed++; console.log(`  ❌ ${name}: ${e.message}`); }
+}
+
+// --- Browser-like sandbox ---
+function makeSandbox() {
+  const ctx = {
+    window: { addEventListener: () => {}, dispatchEvent: () => {}, devicePixelRatio: 1 },
+    document: {
+      readyState: 'complete',
+      createElement: (tag) => ({
+        tagName: tag, id: '', textContent: '', innerHTML: '', style: {},
+        classList: { add() {}, remove() {}, contains() { return false; } },
+        setAttribute() {}, getAttribute() { return null; },
+        addEventListener() {}, focus() {},
+        getContext: () => ({
+          clearRect() {}, fillRect() {}, beginPath() {}, arc() {}, fill() {},
+          scale() {}, fillStyle: '', font: '', fillText() {},
+        }),
+        offsetWidth: 200, offsetHeight: 40, width: 0, height: 0,
+      }),
+      head: { appendChild: () => {} },
+      getElementById: () => null,
+      addEventListener: () => {},
+      querySelectorAll: () => [],
+      querySelector: () => null,
+      createElementNS: () => ({
+        tagName: 'svg', id: '', textContent: '', innerHTML: '', style: {},
+        setAttribute() {}, getAttribute() { return null; },
+      }),
+      documentElement: { getAttribute: () => null, setAttribute: () => {} },
+      body: { appendChild: () => {}, removeChild: () => {}, contains: () => false },
+      hidden: false,
+    },
+    console,
+    Date, Infinity, Math, Array, Object, String, Number, JSON, RegExp,
+    Error, TypeError, Map, Set, Promise, URLSearchParams,
+    parseInt, parseFloat, isNaN, isFinite,
+    encodeURIComponent, decodeURIComponent,
+    setTimeout: () => 0, clearTimeout: () => {},
+    setInterval: () => 0, clearInterval: () => {},
+    fetch: () => Promise.resolve({ json: () => Promise.resolve({}) }),
+    performance: { now: () => Date.now() },
+    requestAnimationFrame: (cb) => setTimeout(cb, 0),
+    cancelAnimationFrame: () => {},
+    localStorage: (() => {
+      const store = {};
+      return {
+        getItem: k => store[k] !== undefined ? store[k] : null,
+        setItem: (k, v) => { store[k] = String(v); },
+        removeItem: k => { delete store[k]; },
+      };
+    })(),
+    location: { hash: '', protocol: 'https:', host: 'localhost' },
+    CustomEvent: class CustomEvent {},
+    addEventListener: () => {},
+    dispatchEvent: () => {},
+    getComputedStyle: () => ({ getPropertyValue: () => '' }),
+    matchMedia: () => ({ matches: false, addEventListener: () => {} }),
+    navigator: {},
+    visualViewport: null,
+    MutationObserver: function() { this.observe = () => {}; this.disconnect = () => {}; },
+    WebSocket: function() { this.close = () => {}; },
+    IATA_COORDS_GEO: {},
+  };
+  vm.createContext(ctx);
+  return ctx;
+}
+
+function loadInCtx(ctx, file) {
+  vm.runInContext(fs.readFileSync(file, 'utf8'), ctx);
+  for (const k of Object.keys(ctx.window)) ctx[k] = ctx.window[k];
+}
+
+function makeLeafletMock() {
+  return {
+    circleMarker: () => {
+      const m = {
+        addTo() { return m; }, bindTooltip() { return m; }, on() { return m; },
+        setRadius() {}, setStyle() {}, setLatLng() {},
+        getLatLng() { return { lat: 0, lng: 0 }; },
+        _baseColor: '', _baseSize: 5, _glowMarker: null, remove() {},
+      };
+      return m;
+    },
+    polyline: () => { const p = { addTo() { return p; }, setStyle() {}, remove() {} }; return p; },
+    polygon: () => { const p = { addTo() { return p; }, remove() {} }; return p; },
+    map: () => {
+      const m = {
+        setView() { return m; }, addLayer() { return m; }, on() { return m; },
+        getZoom() { return 11; }, getCenter() { return { lat: 37, lng: -122 }; },
+        getBounds() { return { contains: () => true }; }, fitBounds() { return m; },
+        invalidateSize() {}, remove() {}, hasLayer() { return false; }, removeLayer() {},
+      };
+      return m;
+    },
+    layerGroup: () => {
+      const g = {
+        addTo() { return g; }, addLayer() {}, removeLayer() {},
+        clearLayers() {}, hasLayer() { return true; }, eachLayer() {},
+      };
+      return g;
+    },
+    tileLayer: () => ({ addTo() { return this; } }),
+    control: { attribution: () => ({ addTo() {} }) },
+    DomUtil: { addClass() {}, removeClass() {} },
+  };
+}
+
+function addLiveGlobals(ctx) {
+  ctx.L = makeLeafletMock();
+  ctx.registerPage = () => {};
+  ctx.onWS = () => {};
+  ctx.offWS = () => {};
+  ctx.connectWS = () => {};
+  ctx.api = () => Promise.resolve([]);
+  ctx.invalidateApiCache = () => {};
+  ctx.favStar = () => '';
+  ctx.bindFavStars = () => {};
+  ctx.getFavorites = () => [];
+  ctx.isFavorite = () => false;
+  ctx.HopResolver = { init() {}, resolve: () => ({}), ready: () => false };
+  ctx.MeshAudio = null;
+  ctx.RegionFilter = { init() {}, getSelected: () => null, onRegionChange: () => {} };
+}
+
+function makeLiveSandbox({ withAppJs = false } = {}) {
+  const ctx = makeSandbox();
+  addLiveGlobals(ctx);
+
+  loadInCtx(ctx, 'public/roles.js');
+  if (withAppJs) loadInCtx(ctx, 'public/app.js');
+  try { loadInCtx(ctx, 'public/live.js'); } catch (e) {
+    console.error('live.js load error:', e.message);
+    for (const k of Object.keys(ctx.window)) ctx[k] = ctx.window[k];
+  }
+  return ctx;
+}
+
+// ===== dbPacketToLive =====
+console.log('\n=== live.js: dbPacketToLive ===');
+{
+  const ctx = makeLiveSandbox();
+  const dbPacketToLive = ctx.window._liveDbPacketToLive;
+  assert.ok(dbPacketToLive, '_liveDbPacketToLive must be exposed');
+
+  test('converts basic DB packet to live format', () => {
+    const pkt = {
+      id: 42, hash: 'abc123',
+      raw_hex: 'deadbeef',
+      path_json: '["hop1","hop2"]',
+      decoded_json: '{"type":"GRP_TXT","text":"hello"}',
+      timestamp: '2024-06-15T12:00:00Z',
+      snr: 7.5, rssi: -85, observer_name: 'ObsA',
+    };
+    const result = dbPacketToLive(pkt);
+    assert.strictEqual(result.id, 42);
+    assert.strictEqual(result.hash, 'abc123');
+    assert.strictEqual(result.raw, 'deadbeef');
+    assert.strictEqual(result.snr, 7.5);
+    assert.strictEqual(result.rssi, -85);
+    assert.strictEqual(result.observer, 'ObsA');
+    assert.strictEqual(result.decoded.header.payloadTypeName, 'GRP_TXT');
+    assert.strictEqual(result.decoded.payload.text, 'hello');
+    assert.deepStrictEqual(result.decoded.path.hops, ['hop1', 'hop2']);
+    assert.strictEqual(result._ts, new Date('2024-06-15T12:00:00Z').getTime());
+  });
+
+  test('handles null decoded_json', () => {
+    const pkt = { id: 1, hash: 'x', decoded_json: null, path_json: null, timestamp: '2024-01-01T00:00:00Z' };
+    const result = dbPacketToLive(pkt);
+    assert.strictEqual(result.decoded.header.payloadTypeName, 'UNKNOWN');
+    assert.deepStrictEqual(result.decoded.path.hops, []);
+  });
+
+  test('uses payload_type_name as fallback', () => {
+    const pkt = { id: 2, hash: 'y', decoded_json: '{}', path_json: '[]', timestamp: '2024-01-01T00:00:00Z', payload_type_name: 'ADVERT' };
+    const result = dbPacketToLive(pkt);
+    assert.strictEqual(result.decoded.header.payloadTypeName, 'ADVERT');
+  });
+
+  test('uses created_at as timestamp fallback', () => {
+    const pkt = { id: 3, hash: 'z', decoded_json: '{}', path_json: '[]', created_at: '2024-03-01T06:00:00Z' };
+    const result = dbPacketToLive(pkt);
+    assert.strictEqual(result._ts, new Date('2024-03-01T06:00:00Z').getTime());
+  });
+}
+
+// ===== expandToBufferEntries =====
+console.log('\n=== live.js: expandToBufferEntries ===');
+{
+  const ctx = makeLiveSandbox();
+  const expand = ctx.window._liveExpandToBufferEntries;
+  assert.ok(expand, '_liveExpandToBufferEntries must be exposed');
+
+  test('single packet without observations returns one entry', () => {
+    const pkts = [{
+      id: 1, hash: 'h1', timestamp: '2024-06-15T12:00:00Z',
+      decoded_json: '{"type":"GRP_TXT"}', path_json: '[]',
+    }];
+    const entries = expand(pkts);
+    assert.strictEqual(entries.length, 1);
+    assert.strictEqual(entries[0].pkt.id, 1);
+    assert.strictEqual(entries[0].ts, new Date('2024-06-15T12:00:00Z').getTime());
+  });
+
+  test('packet with observations expands to one entry per observation', () => {
+    const pkts = [{
+      id: 10, hash: 'h10', timestamp: '2024-06-15T12:00:00Z',
+      decoded_json: '{"type":"ADVERT"}', path_json: '[]', raw_hex: 'ff',
+      observations: [
+        { timestamp: '2024-06-15T12:00:01Z', snr: 5, observer_name: 'O1' },
+        { timestamp: '2024-06-15T12:00:02Z', snr: 8, observer_name: 'O2' },
+        { timestamp: '2024-06-15T12:00:03Z', snr: 3, observer_name: 'O3' },
+      ],
+    }];
+    const entries = expand(pkts);
+    assert.strictEqual(entries.length, 3);
+    assert.strictEqual(entries[0].pkt.observer, 'O1');
+    assert.strictEqual(entries[1].pkt.observer, 'O2');
+    assert.strictEqual(entries[2].pkt.observer, 'O3');
+    // All should share the same hash
+    assert.strictEqual(entries[0].pkt.hash, 'h10');
+    assert.strictEqual(entries[2].pkt.hash, 'h10');
+    // Entries should be in chronological order
+    assert.ok(entries[0].ts < entries[1].ts, 'entry 0 should be before entry 1');
+    assert.ok(entries[1].ts < entries[2].ts, 'entry 1 should be before entry 2');
+  });
+
+  test('empty observations array treated as no observations', () => {
+    const pkts = [{
+      id: 5, hash: 'h5', timestamp: '2024-01-01T00:00:00Z',
+      decoded_json: '{}', path_json: '[]', observations: [],
+    }];
+    const entries = expand(pkts);
+    assert.strictEqual(entries.length, 1);
+  });
+
+  test('multiple packets expand independently', () => {
+    const pkts = [
+      { id: 1, hash: 'h1', timestamp: '2024-01-01T00:00:00Z', decoded_json: '{}', path_json: '[]' },
+      {
+        id: 2, hash: 'h2', timestamp: '2024-01-01T00:00:00Z', decoded_json: '{}', path_json: '[]', raw_hex: 'aa',
+        observations: [
+          { timestamp: '2024-01-01T00:00:01Z', observer_name: 'X' },
+          { timestamp: '2024-01-01T00:00:02Z', observer_name: 'Y' },
+        ],
+      },
+    ];
+    const entries = expand(pkts);
+    assert.strictEqual(entries.length, 3);
+  });
+}
+
+// ===== expandToBufferEntriesAsync (chunked, non-blocking) =====
+console.log('\n=== live.js: expandToBufferEntriesAsync ===');
+{
+  // Build a sandbox with packet-helpers loaded so expandToBufferEntries can call dbPacketToLive
+  const ctx = makeSandbox();
+  addLiveGlobals(ctx);
+  loadInCtx(ctx, 'public/roles.js');
+  loadInCtx(ctx, 'public/packet-helpers.js');
+  try { loadInCtx(ctx, 'public/live.js'); } catch (e) {
+    for (const k of Object.keys(ctx.window)) ctx[k] = ctx.window[k];
+  }
+  const expandSync = ctx.window._liveExpandToBufferEntries;
+  const expandAsync = ctx.window._liveExpandToBufferEntriesAsync;
+  assert.ok(expandAsync, '_liveExpandToBufferEntriesAsync must be exposed');
+
+  const pkts = [];
+  for (let i = 0; i < 500; i++) {
+    pkts.push({
+      id: i, hash: 'h' + i, timestamp: new Date(1700000000000 + i * 1000).toISOString(),
+      decoded_json: '{"type":"GRP_TXT"}', path_json: '[]',
+      observations: [
+        { timestamp: new Date(1700000000000 + i * 1000 + 100).toISOString(), snr: 5, observer_name: 'O1' },
+        { timestamp: new Date(1700000000000 + i * 1000 + 200).toISOString(), snr: 8, observer_name: 'O2' },
+      ],
+    });
+  }
+
+  test('sync expand handles 500 packets (1000 entries) correctly', () => {
+    const result = expandSync(pkts);
+    assert.strictEqual(result.length, 1000, '500 packets * 2 observations = 1000 entries');
+    assert.strictEqual(result[0].pkt.hash, 'h0');
+    assert.strictEqual(result[999].pkt.hash, 'h499');
+  });
+
+  test('VCR_CHUNK_SIZE is defined and async function yields via setTimeout', () => {
+    const src = fs.readFileSync(__dirname + '/public/live.js', 'utf8');
+    assert.ok(src.includes('VCR_CHUNK_SIZE'), 'VCR_CHUNK_SIZE constant must exist');
+    assert.ok(src.includes('expandToBufferEntriesAsync'), 'async version must exist');
+    assert.ok(src.includes('setTimeout(processChunk, 0)'), 'must yield via setTimeout between chunks');
+  });
+}
+
+// ===== SEG_MAP (7-segment display) =====
+console.log('\n=== live.js: SEG_MAP ===');
+{
+  const ctx = makeLiveSandbox();
+  const SEG_MAP = ctx.window._liveSEG_MAP;
+  assert.ok(SEG_MAP, '_liveSEG_MAP must be exposed');
+
+  test('all digits 0-9 are mapped', () => {
+    for (let i = 0; i <= 9; i++) {
+      assert.ok(SEG_MAP[String(i)] !== undefined, `digit ${i} must be in SEG_MAP`);
+      assert.ok(SEG_MAP[String(i)] > 0, `digit ${i} must have non-zero segments`);
+    }
+  });
+
+  test('digit 8 lights all 7 segments and no others', () => {
+    // 0x7F = 0b01111111 — all 7 segment bits on, MSB (colon) off
+    const val = SEG_MAP['8'];
+    assert.strictEqual(val & 0x7F, 0x7F, 'all 7 segment bits should be set');
+    assert.strictEqual(val & 0x80, 0, 'colon bit should not be set for a digit');
+  });
+
+  test('colon only sets the MSB (dot/colon indicator)', () => {
+    const val = SEG_MAP[':'];
+    assert.strictEqual(val & 0x80, 0x80, 'MSB (colon bit) should be set');
+    assert.strictEqual(val & 0x7F, 0, 'no segment bits should be set for colon');
+  });
+
+  test('space lights no segments', () => {
+    assert.strictEqual(SEG_MAP[' '], 0x00, 'space should have no bits set');
+  });
+
+  test('digit 1 lights fewer segments than digit 8', () => {
+    // Behavioral: 1 has fewer segments lit than 8
+    const ones = (n) => { let c = 0; while (n) { c += n & 1; n >>= 1; } return c; };
+    assert.ok(ones(SEG_MAP['1']) < ones(SEG_MAP['8']),
+      'digit 1 should have fewer segment bits than digit 8');
+  });
+
+  test('VCR mode letters are mapped with non-zero segments', () => {
+    for (const ch of ['P', 'A', 'U', 'S', 'E', 'L', 'I', 'V']) {
+      assert.ok(SEG_MAP[ch] !== undefined, `${ch} must be in SEG_MAP`);
+      assert.ok(SEG_MAP[ch] > 0, `${ch} must have non-zero segments`);
+    }
+  });
+}
+
+// ===== VCR state machine =====
+console.log('\n=== live.js: VCR state machine ===');
+{
+  const ctx = makeLiveSandbox();
+  const VCR = ctx.window._liveVCR;
+  const vcrSetMode = ctx.window._liveVcrSetMode;
+  const vcrPause = ctx.window._liveVcrPause;
+  const vcrSpeedCycle = ctx.window._liveVcrSpeedCycle;
+  assert.ok(VCR, '_liveVCR must be exposed');
+
+  test('VCR initial mode is LIVE', () => {
+    assert.strictEqual(VCR().mode, 'LIVE');
+  });
+
+  test('vcrSetMode changes mode', () => {
+    vcrSetMode('PAUSED');
+    assert.strictEqual(VCR().mode, 'PAUSED');
+    assert.ok(VCR().frozenNow != null, 'frozenNow should be set when not LIVE');
+  });
+
+  test('vcrSetMode LIVE clears frozenNow', () => {
+    vcrSetMode('LIVE');
+    assert.strictEqual(VCR().mode, 'LIVE');
+    assert.strictEqual(VCR().frozenNow, null);
+  });
+
+  test('vcrPause stops replay and sets PAUSED', () => {
+    vcrSetMode('LIVE');
+    vcrPause();
+    assert.strictEqual(VCR().mode, 'PAUSED');
+    assert.strictEqual(VCR().missedCount, 0);
+  });
+
+  test('vcrPause is idempotent', () => {
+    vcrPause();
+    const frozen1 = VCR().frozenNow;
+    assert.strictEqual(VCR().mode, 'PAUSED', 'mode should be PAUSED after first call');
+    vcrPause();
+    assert.strictEqual(VCR().frozenNow, frozen1);
+    assert.strictEqual(VCR().mode, 'PAUSED', 'mode should stay PAUSED after second call');
+  });
+
+  test('vcrSpeedCycle cycles through 1,2,4,8', () => {
+    vcrSetMode('LIVE');
+    VCR().speed = 1;
+    vcrSpeedCycle();
+    assert.strictEqual(VCR().speed, 2);
+    vcrSpeedCycle();
+    assert.strictEqual(VCR().speed, 4);
+    vcrSpeedCycle();
+    assert.strictEqual(VCR().speed, 8);
+    vcrSpeedCycle();
+    assert.strictEqual(VCR().speed, 1); // wraps around
+  });
+
+  const vcrResumeLive = ctx.window._liveVcrResumeLive;
+  assert.ok(vcrResumeLive, '_liveVcrResumeLive must be exposed');
+
+  test('vcrResumeLive transitions from PAUSED to LIVE', () => {
+    vcrPause();
+    assert.strictEqual(VCR().mode, 'PAUSED');
+    assert.ok(VCR().frozenNow != null, 'frozenNow should be set when paused');
+    vcrResumeLive();
+    assert.strictEqual(VCR().mode, 'LIVE');
+    assert.strictEqual(VCR().frozenNow, null, 'frozenNow should be cleared');
+    assert.strictEqual(VCR().playhead, -1, 'playhead should reset to -1');
+    assert.strictEqual(VCR().speed, 1, 'speed should reset to 1');
+    assert.strictEqual(VCR().missedCount, 0, 'missedCount should be 0');
+  });
+}
+
+// ===== getFavoritePubkeys =====
+console.log('\n=== live.js: getFavoritePubkeys ===');
+{
+  const ctx = makeLiveSandbox();
+  const getFavPubkeys = ctx.window._liveGetFavoritePubkeys;
+  assert.ok(getFavPubkeys, '_liveGetFavoritePubkeys must be exposed');
+
+  test('returns empty array when no favorites stored', () => {
+    ctx.localStorage.removeItem('meshcore-favorites');
+    ctx.localStorage.removeItem('meshcore-my-nodes');
+    const result = getFavPubkeys();
+    assert.ok(Array.isArray(result));
+    assert.strictEqual(result.length, 0);
+  });
+
+  test('reads from meshcore-favorites', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["pk1","pk2"]');
+    ctx.localStorage.removeItem('meshcore-my-nodes');
+    const result = getFavPubkeys();
+    assert.ok(result.includes('pk1'));
+    assert.ok(result.includes('pk2'));
+  });
+
+  test('reads from meshcore-my-nodes pubkeys', () => {
+    ctx.localStorage.removeItem('meshcore-favorites');
+    ctx.localStorage.setItem('meshcore-my-nodes', '[{"pubkey":"mynode1"},{"pubkey":"mynode2"}]');
+    const result = getFavPubkeys();
+    assert.ok(result.includes('mynode1'));
+    assert.ok(result.includes('mynode2'));
+  });
+
+  test('merges both sources', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["fav1"]');
+    ctx.localStorage.setItem('meshcore-my-nodes', '[{"pubkey":"mine1"}]');
+    const result = getFavPubkeys();
+    assert.ok(result.includes('fav1'));
+    assert.ok(result.includes('mine1'));
+    assert.strictEqual(result.length, 2);
+  });
+
+  test('handles corrupt localStorage gracefully', () => {
+    ctx.localStorage.setItem('meshcore-favorites', 'not json');
+    ctx.localStorage.setItem('meshcore-my-nodes', '{bad}');
+    const result = getFavPubkeys();
+    assert.ok(Array.isArray(result));
+    assert.strictEqual(result.length, 0, 'corrupt data should yield empty array');
+  });
+
+  test('filters out falsy values', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["pk1",null,"",false,"pk2"]');
+    ctx.localStorage.removeItem('meshcore-my-nodes');
+    const result = getFavPubkeys();
+    assert.ok(!result.includes(null));
+    assert.ok(!result.includes(''));
+    assert.strictEqual(result.length, 2);
+  });
+}
+
+// ===== packetInvolvesFavorite =====
+console.log('\n=== live.js: packetInvolvesFavorite ===');
+{
+  const ctx = makeLiveSandbox();
+  // Clean localStorage to avoid leakage from prior test sections
+  ctx.localStorage.removeItem('meshcore-favorites');
+  ctx.localStorage.removeItem('meshcore-my-nodes');
+  const involves = ctx.window._livePacketInvolvesFavorite;
+  assert.ok(involves, '_livePacketInvolvesFavorite must be exposed');
+
+  test('returns false when no favorites', () => {
+    ctx.localStorage.removeItem('meshcore-favorites');
+    ctx.localStorage.removeItem('meshcore-my-nodes');
+    const pkt = { decoded: { header: {}, payload: { pubKey: 'abc' } } };
+    assert.strictEqual(involves(pkt), false);
+  });
+
+  test('matches sender pubKey', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["sender123"]');
+    const pkt = { decoded: { header: {}, payload: { pubKey: 'sender123' } } };
+    assert.strictEqual(involves(pkt), true);
+  });
+
+  test('matches hop prefix', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["abcdef1234567890"]');
+    const pkt = { decoded: { header: {}, payload: {}, path: { hops: ['abcd'] } } };
+    assert.strictEqual(involves(pkt), true);
+  });
+
+  test('does not match unrelated hop', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["abcdef1234567890"]');
+    const pkt = { decoded: { header: {}, payload: {}, path: { hops: ['ffff'] } } };
+    assert.strictEqual(involves(pkt), false);
+  });
+
+  test('handles missing decoded fields gracefully', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["xyz"]');
+    const pkt = {};
+    assert.strictEqual(involves(pkt), false);
+  });
+}
+
+// ===== isNodeFavorited =====
+console.log('\n=== live.js: isNodeFavorited ===');
+{
+  const ctx = makeLiveSandbox();
+  // Clean localStorage to avoid leakage from prior test sections
+  ctx.localStorage.removeItem('meshcore-favorites');
+  ctx.localStorage.removeItem('meshcore-my-nodes');
+  const isFav = ctx.window._liveIsNodeFavorited;
+  assert.ok(isFav, '_liveIsNodeFavorited must be exposed');
+
+  test('returns true when pubkey is in favorites', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["pk1","pk2"]');
+    assert.strictEqual(isFav('pk1'), true);
+  });
+
+  test('returns false when pubkey not in favorites', () => {
+    ctx.localStorage.setItem('meshcore-favorites', '["pk1"]');
+    assert.strictEqual(isFav('pk99'), false);
+  });
+
+  test('returns false with empty favorites', () => {
+    ctx.localStorage.removeItem('meshcore-favorites');
+    ctx.localStorage.removeItem('meshcore-my-nodes');
+    assert.strictEqual(isFav('pk1'), false);
+  });
+}
+
+// ===== formatLiveTimestampHtml =====
+console.log('\n=== live.js: formatLiveTimestampHtml ===');
+{
+  const ctx = makeLiveSandbox({ withAppJs: true });
+
+  const fmt = ctx.window._liveFormatLiveTimestampHtml;
+  assert.ok(fmt, '_liveFormatLiveTimestampHtml must be exposed');
+
+  test('formats a recent ISO timestamp', () => {
+    const iso = new Date(Date.now() - 30000).toISOString();
+    const html = fmt(iso);
+    assert.ok(html.includes('timestamp-text'), 'should contain timestamp-text span');
+    assert.ok(html.includes('title='), 'should have tooltip');
+  });
+
+  test('handles null input', () => {
+    const html = fmt(null);
+    assert.ok(typeof html === 'string');
+    assert.ok(html.includes('—'), 'null input should render em-dash fallback');
+  });
+
+  test('handles numeric timestamp', () => {
+    const html = fmt(Date.now() - 60000);
+    assert.ok(typeof html === 'string');
+    assert.ok(html.includes('timestamp-text'), 'numeric timestamp should produce timestamp-text span');
+    assert.ok(html.includes('title='), 'numeric timestamp should have tooltip');
+  });
+
+  test('future timestamp shows warning icon', () => {
+    const future = new Date(Date.now() + 120000).toISOString();
+    const html = fmt(future);
+    assert.ok(html.includes('timestamp-future-icon'), 'should show future warning');
+  });
+}
+
+// ===== resolveHopPositions =====
+console.log('\n=== live.js: resolveHopPositions ===');
+{
+  const ctx = makeLiveSandbox();
+  const resolve = ctx.window._liveResolveHopPositions;
+  const nodeData = ctx.window._liveNodeData();
+  const nodeMarkers = ctx.window._liveNodeMarkers();
+  assert.ok(resolve, '_liveResolveHopPositions must be exposed');
+
+  test('returns empty array for empty hops', () => {
+    const result = resolve([], {});
+    assert.deepStrictEqual(result, []);
+  });
+
+  test('returns sender position when payload has pubKey + coords', () => {
+    const payload = { pubKey: 'sender1', name: 'Sender', lat: 37.5, lon: -122.0 };
+    // No nodes in nodeData, so hops won't resolve
+    const result = resolve([], payload);
+    // With empty hops, the function still adds the sender as an anchor point.
+    assert.ok(Array.isArray(result), 'should return an array');
+    assert.strictEqual(result.length, 1, 'sender coords should produce one anchor position');
+    assert.strictEqual(result[0].pos[0], 37.5, 'anchor should use sender lat');
+    assert.strictEqual(result[0].pos[1], -122.0, 'anchor should use sender lon');
+    assert.strictEqual(result[0].name, 'Sender', 'anchor should use sender name');
+    assert.strictEqual(result[0].known, true, 'sender with coords should be marked as known');
+  });
+
+  test('resolves known node from nodeData', () => {
+    // Add a node to nodeData
+    nodeData['nodeA_pubkey'] = { public_key: 'nodeA_pubkey', name: 'NodeA', lat: 37.3, lon: -122.0 };
+    nodeData['nodeB_pubkey'] = { public_key: 'nodeB_pubkey', name: 'NodeB', lat: 38.0, lon: -121.0 };
+    // Need HopResolver to resolve the hop prefix — set on both ctx and window
+    const mockResolver = {
+      init() {},
+      ready() { return true; },
+      resolve(hops) {
+        const map = {};
+        for (const h of hops) {
+          if (h === 'nodeA') map[h] = { name: 'NodeA', pubkey: 'nodeA_pubkey' };
+          else if (h === 'nodeB') map[h] = { name: 'NodeB', pubkey: 'nodeB_pubkey' };
+          else map[h] = { name: null, pubkey: null };
+        }
+        return map;
+      },
+    };
+    ctx.HopResolver = mockResolver;
+    ctx.window.HopResolver = mockResolver;
+    // Need at least 2 known nodes for ghost mode to not filter down
+    const result = resolve(['nodeA', 'nodeB'], {});
+    assert.ok(result.length >= 2, `expected >= 2 positions, got ${result.length}`);
+    const foundA = result.find(r => r.key === 'nodeA_pubkey');
+    assert.ok(foundA, 'should resolve nodeA to nodeA_pubkey');
+    assert.strictEqual(foundA.pos[0], 37.3);
+    assert.strictEqual(foundA.pos[1], -122.0);
+    assert.strictEqual(foundA.known, true);
+    delete nodeData['nodeA_pubkey'];
+    delete nodeData['nodeB_pubkey'];
+  });
+
+  test('ghost hops get interpolated positions between known nodes', () => {
+    // Set up: two known nodes, one unknown hop between them
+    nodeData['n1'] = { public_key: 'n1', name: 'N1', lat: 37.0, lon: -122.0 };
+    nodeData['n2'] = { public_key: 'n2', name: 'N2', lat: 38.0, lon: -121.0 };
+    const mockResolver = {
+      init() {},
+      ready() { return true; },
+      resolve(hops) {
+        const map = {};
+        for (const h of hops) {
+          if (h === 'h1') map[h] = { name: 'N1', pubkey: 'n1' };
+          else if (h === 'h3') map[h] = { name: 'N2', pubkey: 'n2' };
+          else map[h] = { name: null, pubkey: null };
+        }
+        return map;
+      },
+    };
+    ctx.HopResolver = mockResolver;
+    ctx.window.HopResolver = mockResolver;
+    const result = resolve(['h1', 'h2', 'h3'], {});
+    assert.ok(result.length >= 2, `should have at least 2 positions, got ${result.length}`);
+    // Check that the ghost hop got an interpolated position
+    const ghost = result.find(r => r.ghost);
+    assert.ok(ghost, 'ghost hop should be present in resolved positions — if missing, interpolation logic changed');
+    assert.ok(ghost.pos[0] > 37.0 && ghost.pos[0] < 38.0, 'ghost lat should be interpolated');
+    assert.ok(ghost.pos[1] > -122.0 && ghost.pos[1] < -121.0, 'ghost lon should be interpolated');
+    delete nodeData['n1'];
+    delete nodeData['n2'];
+  });
+}
+
+// ===== bufferPacket and VCR buffer management =====
+console.log('\n=== live.js: bufferPacket / VCR buffer ===');
+{
+  const ctx = makeLiveSandbox();
+  const bufferPacket = ctx.window._liveBufferPacket;
+  const VCR = ctx.window._liveVCR;
+  assert.ok(bufferPacket, '_liveBufferPacket must be exposed');
+
+  test('bufferPacket adds entry to VCR buffer', () => {
+    const initialLen = VCR().buffer.length;
+    const pkt = { hash: 'test1', decoded: { header: { payloadTypeName: 'GRP_TXT' }, payload: {} } };
+    bufferPacket(pkt);
+    assert.strictEqual(VCR().buffer.length, initialLen + 1);
+    const last = VCR().buffer[VCR().buffer.length - 1];
+    assert.strictEqual(last.pkt.hash, 'test1');
+    assert.ok(last.ts > 0);
+  });
+
+  test('bufferPacket sets _ts on packet', () => {
+    const pkt = { hash: 'test2', decoded: { header: {}, payload: {} } };
+    const before = Date.now();
+    bufferPacket(pkt);
+    const after = Date.now();
+    assert.ok(pkt._ts >= before && pkt._ts <= after, `_ts should be between ${before} and ${after}, got ${pkt._ts}`);
+  });
+
+  test('VCR buffer caps at ~2000 entries', () => {
+    // Fill buffer past 2000
+    VCR().buffer.length = 0;
+    for (let i = 0; i < 2100; i++) {
+      VCR().buffer.push({ ts: Date.now(), pkt: { hash: 'fill' + i } });
+    }
+    // Next bufferPacket triggers trim: 2100+1=2101 > 2000 → splice(0, 500) → 1601
+    const pkt = { hash: 'overflow', decoded: { header: {}, payload: {} } };
+    bufferPacket(pkt);
+    assert.strictEqual(VCR().buffer.length, 1601, `buffer should be 2101 - 500 = 1601, got ${VCR().buffer.length}`);
+  });
+
+  test('bufferPacket increments missedCount when PAUSED', () => {
+    ctx.window._liveVcrSetMode('PAUSED');
+    VCR().missedCount = 0;
+    const pkt = { hash: 'missed1', decoded: { header: {}, payload: {} } };
+    bufferPacket(pkt);
+    assert.strictEqual(VCR().missedCount, 1);
+    bufferPacket({ hash: 'missed2', decoded: { header: {}, payload: {} } });
+    assert.strictEqual(VCR().missedCount, 2);
+    ctx.window._liveVcrSetMode('LIVE');
+  });
+
+  test('bufferPacket handles malformed packet without decoded field', () => {
+    const before = VCR().buffer.length;
+    // Packet with no decoded field at all — should not throw, and should still be buffered
+    bufferPacket({ hash: 'malformed1' });
+    assert.strictEqual(VCR().buffer.length, before + 1, 'malformed packet should still be added to buffer');
+  });
+
+  test('bufferPacket handles packet with null decoded', () => {
+    const before = VCR().buffer.length;
+    bufferPacket({ hash: 'malformed2', decoded: null });
+    assert.strictEqual(VCR().buffer.length, before + 1, 'packet with null decoded should still be added to buffer');
+  });
+}
+
+// ===== VCR frozenNow behavior =====
+console.log('\n=== live.js: VCR frozenNow ===');
+{
+  const ctx = makeLiveSandbox();
+  const VCR = ctx.window._liveVCR;
+  const setMode = ctx.window._liveVcrSetMode;
+
+  test('frozenNow is set on first non-LIVE mode', () => {
+    setMode('LIVE');
+    assert.strictEqual(VCR().frozenNow, null);
+    setMode('PAUSED');
+    const t1 = VCR().frozenNow;
+    assert.ok(t1 > 0);
+    // Should NOT change on subsequent non-LIVE mode changes
+    setMode('REPLAY');
+    assert.strictEqual(VCR().frozenNow, t1, 'frozenNow should not change if already set');
+  });
+
+  test('frozenNow cleared on LIVE', () => {
+    setMode('PAUSED');
+    assert.ok(VCR().frozenNow != null);
+    setMode('LIVE');
+    assert.strictEqual(VCR().frozenNow, null);
+  });
+}
+
+// ===== Source-level checks for live.js safety guards =====
+// NOTE: These src.includes() checks are intentionally brittle — they verify that specific
+// safety guards exist in the source code TODAY. They will break on whitespace/rename refactors,
+// which is an acceptable tradeoff: a failing test forces the developer to verify the guard
+// still exists in its new form. For critical guards (animation limits, null checks), prefer
+// behavioral tests where feasible (see bufferPacket and VCR sections above).
+console.log('\n=== live.js: source-level safety checks ===');
+{
+  const src = fs.readFileSync('public/live.js', 'utf8');
+
+  test('renderPacketTree null-checks packets array', () => {
+    assert.ok(src.includes('if (!packets || !packets.length) return;'),
+      'renderPacketTree must guard null/empty packets');
+  });
+
+  test('animatePath guards MAX_CONCURRENT_ANIMS', () => {
+    assert.ok(src.includes('if (activeAnims >= MAX_CONCURRENT_ANIMS) return;'),
+      'animatePath must respect concurrent animation limit');
+  });
+
+  test('animatePath guards null animLayer/pathsLayer', () => {
+    assert.ok(src.includes('if (!animLayer || !pathsLayer) return;'),
+      'animatePath must guard null layers');
+  });
+
+  test('pulseNode guards null animLayer/nodesLayer', () => {
+    assert.ok(src.includes('if (!animLayer || !nodesLayer) return;'),
+      'pulseNode must guard null layers');
+  });
+
+  test('nextHop guards null animLayer', () => {
+    assert.ok(src.includes('if (!animLayer) return;'),
+      'nextHop must guard null animLayer before drawing');
+  });
+
+  test('VCR buffer trim adjusts playhead', () => {
+    assert.ok(src.includes('VCR.playhead = Math.max(0, VCR.playhead - trimCount)'),
+      'buffer trim must adjust playhead to prevent stale indices');
+  });
+
+  test('tab hidden skips animations', () => {
+    assert.ok(src.includes('if (_tabHidden)'),
+      'bufferPacket should skip animation when tab is hidden');
+  });
+
+  test('visibility change clears propagation buffer', () => {
+    assert.ok(src.includes('propagationBuffer.clear()'),
+      'tab restore should clear propagation buffer');
+  });
+
+  test('connectWS has reconnect on close', () => {
+    assert.ok(src.includes('ws.onclose = () => setTimeout(connectWS, WS_RECONNECT_MS)'),
+      'WebSocket should auto-reconnect on close');
+  });
+
+  test('addNodeMarker avoids duplicates', () => {
+    assert.ok(src.includes('if (nodeMarkers[n.public_key]) return nodeMarkers[n.public_key]'),
+      'addNodeMarker should return existing marker if already exists');
+  });
+
+  test('matrix mode saves toggle to localStorage', () => {
+    assert.ok(src.includes("localStorage.setItem('live-matrix-mode'"),
+      'matrix toggle should persist to localStorage');
+  });
+
+  test('matrix rain saves toggle to localStorage', () => {
+    assert.ok(src.includes("localStorage.setItem('live-matrix-rain'"),
+      'matrix rain toggle should persist to localStorage');
+  });
+
+  test('realistic propagation saves toggle to localStorage', () => {
+    assert.ok(src.includes("localStorage.setItem('live-realistic-propagation'"),
+      'realistic propagation toggle should persist to localStorage');
+  });
+
+  test('favorites filter saves toggle to localStorage', () => {
+    assert.ok(src.includes("localStorage.setItem('live-favorites-only'"),
+      'favorites filter toggle should persist to localStorage');
+  });
+
+  test('ghost hops saves toggle to localStorage', () => {
+    assert.ok(src.includes("localStorage.setItem('live-ghost-hops'"),
+      'ghost hops toggle should persist to localStorage');
+  });
+
+  test('clearNodeMarkers resets HopResolver', () => {
+    assert.ok(src.includes('if (window.HopResolver) HopResolver.init([])'),
+      'clearNodeMarkers should reset HopResolver');
+  });
+
+  test('rescaleMarkers reads zoom from map', () => {
+    assert.ok(src.includes('const zoom = map.getZoom()'),
+      'rescaleMarkers should read current zoom level');
+  });
+
+  test('startReplay pre-aggregates by hash', () => {
+    assert.ok(src.includes('const hashGroups = new Map()'),
+      'startReplay should group buffer entries by hash');
+  });
+
+  test('orientation change retries resize with delays', () => {
+    assert.ok(src.includes('[50, 200, 500, 1000, 2000].forEach'),
+      'orientation change handler should retry resize at multiple intervals');
+  });
+
+  test('VCR rewind deduplicates buffer entries by ID', () => {
+    assert.ok(src.includes('const existingIds = new Set(VCR.buffer.map(b => b.pkt.id)'),
+      'vcrRewind should dedup by packet ID');
+  });
+
+  test('feed items include transport badge', () => {
+    const count = (src.match(/transportBadge\(pkt\.route_type\)/g) || []).length;
+    assert.ok(count >= 3,
+      `feed rendering should call transportBadge(pkt.route_type) in at least 3 places (found ${count})`);
+  });
+
+  test('node detail recent packets include transport badge', () => {
+    assert.ok(src.includes('transportBadge(p.route_type)'),
+      'node detail recent packets should call transportBadge(p.route_type)');
+  });
+}
+
+// ===== SUMMARY =====
+Promise.allSettled(pendingTests).then(() => {
+  console.log(`\n${'═'.repeat(40)}`);
+  console.log(`  live.js tests: ${passed} passed, ${failed} failed`);
+  console.log(`${'═'.repeat(40)}\n`);
+  if (failed > 0) process.exit(1);
+}).catch((e) => {
+  console.error('Failed waiting for async tests:', e);
+  process.exit(1);
+});

test-packets.js

@@ -0,0 +1,790 @@
+/* Unit tests for packets.js functions (tested via VM sandbox) */
+'use strict';
+const vm = require('vm');
+const fs = require('fs');
+const assert = require('assert');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ✅ ${name}`);
+  } catch (e) {
+    failed++;
+    console.log(`  ❌ ${name}: ${e.message}`);
+  }
+}
+
+// Build a browser-like sandbox with all deps packets.js needs
+function makeSandbox() {
+  const registeredPages = {};
+  const ctx = {
+    window: {
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => {},
+      innerWidth: 1200,
+      PacketFilter: null,
+    },
+    document: {
+      readyState: 'complete',
+      createElement: (tag) => ({
+        tagName: tag.toUpperCase(), id: '', textContent: '', innerHTML: '',
+        className: '', style: {}, appendChild: () => {}, setAttribute: () => {},
+        addEventListener: () => {}, querySelectorAll: () => [], querySelector: () => null,
+        classList: { add: () => {}, remove: () => {}, contains: () => false },
+      }),
+      head: { appendChild: () => {} },
+      getElementById: () => null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      querySelectorAll: () => [],
+      querySelector: () => null,
+      body: { appendChild: () => {} },
+    },
+    console,
+    Date,
+    Infinity,
+    Math,
+    Array,
+    Object,
+    String,
+    Number,
+    JSON,
+    RegExp,
+    Error,
+    TypeError,
+    RangeError,
+    parseInt,
+    parseFloat,
+    isNaN,
+    isFinite,
+    encodeURIComponent,
+    decodeURIComponent,
+    setTimeout: () => {},
+    clearTimeout: () => {},
+    setInterval: () => {},
+    clearInterval: () => {},
+    fetch: () => Promise.resolve({ ok: true, json: () => Promise.resolve({}) }),
+    performance: { now: () => Date.now() },
+    localStorage: (() => {
+      const store = {};
+      return {
+        getItem: k => store[k] || null,
+        setItem: (k, v) => { store[k] = String(v); },
+        removeItem: k => { delete store[k]; },
+      };
+    })(),
+    location: { hash: '' },
+    history: { replaceState: () => {} },
+    CustomEvent: class CustomEvent {},
+    Map,
+    Set,
+    Promise,
+    URLSearchParams,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => {},
+    requestAnimationFrame: (cb) => setTimeout(cb, 0),
+    _registeredPages: registeredPages,
+    // Stub global functions packets.js depends on
+    registerPage: (name, handler) => { registeredPages[name] = handler; },
+  };
+  vm.createContext(ctx);
+  return ctx;
+}
+
+function loadInCtx(ctx, file) {
+  vm.runInContext(fs.readFileSync(file, 'utf8'), ctx, { filename: file });
+  for (const k of Object.keys(ctx.window)) {
+    ctx[k] = ctx.window[k];
+  }
+}
+
+function loadPacketsSandbox() {
+  const ctx = makeSandbox();
+  // Load dependencies first
+  loadInCtx(ctx, 'public/roles.js');
+  loadInCtx(ctx, 'public/app.js');
+  // HopDisplay stub (simpler than loading real file which may have DOM deps)
+  vm.runInContext(`
+    window.HopDisplay = {
+      renderHop: function(h, entry, opts) {
+        if (entry && entry.name) return '<span class="hop-named">' + entry.name + '</span>';
+        return '<span class="hop-hex">' + h + '</span>';
+      },
+      _showFromBtn: function() {}
+    };
+  `, ctx);
+  loadInCtx(ctx, 'public/packets.js');
+  return ctx;
+}
+
+// ===== TESTS =====
+
+console.log('\n=== packets.js: typeName ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('typeName returns known type', () => {
+    assert.strictEqual(api.typeName(0), 'Request');
+    assert.strictEqual(api.typeName(4), 'Advert');
+    assert.strictEqual(api.typeName(5), 'Channel Msg');
+  });
+
+  test('typeName returns fallback for unknown', () => {
+    assert.strictEqual(api.typeName(99), 'Type 99');
+    assert.strictEqual(api.typeName(undefined), 'Type undefined');
+  });
+}
+
+console.log('\n=== packets.js: obsName ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('obsName returns dash for falsy id', () => {
+    assert.strictEqual(api.obsName(null), '—');
+    assert.strictEqual(api.obsName(''), '—');
+    assert.strictEqual(api.obsName(undefined), '—');
+  });
+
+  test('obsName returns id when not in observerMap', () => {
+    assert.strictEqual(api.obsName('unknown-id'), 'unknown-id');
+  });
+}
+
+console.log('\n=== packets.js: kv ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('kv produces correct HTML', () => {
+    const result = api.kv('Route', 'Direct');
+    assert(result.includes('byop-key'));
+    assert(result.includes('Route'));
+    assert(result.includes('Direct'));
+    assert(result.includes('byop-val'));
+  });
+}
+
+console.log('\n=== packets.js: sectionRow / fieldRow ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('sectionRow produces section HTML', () => {
+    const result = api.sectionRow('Header');
+    assert(result.includes('section-row'));
+    assert(result.includes('Header'));
+    assert(result.includes('colspan="4"'));
+  });
+
+  test('fieldRow produces field HTML', () => {
+    const result = api.fieldRow(0, 'Header Byte', '0xFF', 'some desc');
+    assert(result.includes('0'));
+    assert(result.includes('Header Byte'));
+    assert(result.includes('0xFF'));
+    assert(result.includes('some desc'));
+    assert(result.includes('mono'));
+  });
+
+  test('fieldRow handles empty description', () => {
+    const result = api.fieldRow(5, 'Test', 'val', '');
+    assert(result.includes('text-muted'));
+  });
+}
+
+console.log('\n=== packets.js: getDetailPreview ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('getDetailPreview returns empty for null/undefined', () => {
+    assert.strictEqual(api.getDetailPreview(null), '');
+    assert.strictEqual(api.getDetailPreview(undefined), '');
+  });
+
+  test('getDetailPreview handles CHAN type', () => {
+    const result = api.getDetailPreview({ type: 'CHAN', text: 'hello world', channel: 'general' });
+    assert(result.includes('💬'));
+    assert(result.includes('hello world'));
+    assert(result.includes('chan-tag'));
+    assert(result.includes('general'));
+  });
+
+  test('getDetailPreview truncates long CHAN text', () => {
+    const longText = 'x'.repeat(100);
+    const result = api.getDetailPreview({ type: 'CHAN', text: longText });
+    assert(result.includes('…'));
+    assert(!result.includes('x'.repeat(100)));
+  });
+
+  test('getDetailPreview handles ADVERT type', () => {
+    const result = api.getDetailPreview({
+      type: 'ADVERT', name: 'TestNode', pubKey: 'abc123',
+      flags: { repeater: true }
+    });
+    assert(result.includes('📡'));
+    assert(result.includes('TestNode'));
+    assert(result.includes('hop-link'));
+  });
+
+  test('getDetailPreview handles ADVERT room', () => {
+    const result = api.getDetailPreview({
+      type: 'ADVERT', name: 'RoomNode', pubKey: 'abc',
+      flags: { room: true }
+    });
+    assert(result.includes('🏠'));
+  });
+
+  test('getDetailPreview handles ADVERT sensor', () => {
+    const result = api.getDetailPreview({
+      type: 'ADVERT', name: 'Sensor1', pubKey: 'abc',
+      flags: { sensor: true }
+    });
+    assert(result.includes('🌡'));
+  });
+
+  test('getDetailPreview handles ADVERT companion (default)', () => {
+    const result = api.getDetailPreview({
+      type: 'ADVERT', name: 'Comp', pubKey: 'abc',
+      flags: {}
+    });
+    assert(result.includes('📻'));
+  });
+
+  test('getDetailPreview handles GRP_TXT with channelHash (no_key)', () => {
+    const result = api.getDetailPreview({
+      type: 'GRP_TXT', channelHash: 0xAB, decryptionStatus: 'no_key'
+    });
+    assert(result.includes('🔒'));
+    assert(result.includes('0xAB'));
+    assert(result.includes('no key'));
+  });
+
+  test('getDetailPreview handles GRP_TXT decryption_failed', () => {
+    const result = api.getDetailPreview({
+      type: 'GRP_TXT', channelHash: 5, decryptionStatus: 'decryption_failed'
+    });
+    assert(result.includes('decryption failed'));
+  });
+
+  test('getDetailPreview handles GRP_TXT with channelHashHex', () => {
+    const result = api.getDetailPreview({
+      type: 'GRP_TXT', channelHash: 0xFF, channelHashHex: 'FF'
+    });
+    assert(result.includes('0xFF'));
+  });
+
+  test('getDetailPreview handles TXT_MSG', () => {
+    const result = api.getDetailPreview({
+      type: 'TXT_MSG', srcHash: 'abcdef01', destHash: '12345678'
+    });
+    assert(result.includes('✉️'));
+    assert(result.includes('abcdef01'));
+    assert(result.includes('12345678'));
+  });
+
+  test('getDetailPreview handles PATH', () => {
+    const result = api.getDetailPreview({
+      type: 'PATH', srcHash: 'aabb', destHash: 'ccdd'
+    });
+    assert(result.includes('🔀'));
+  });
+
+  test('getDetailPreview handles REQ', () => {
+    const result = api.getDetailPreview({
+      type: 'REQ', srcHash: 'aa', destHash: 'bb'
+    });
+    assert(result.includes('🔒'));
+    assert(result.includes('aa'));
+  });
+
+  test('getDetailPreview handles RESPONSE', () => {
+    const result = api.getDetailPreview({
+      type: 'RESPONSE', srcHash: 'aa', destHash: 'bb'
+    });
+    assert(result.includes('🔒'));
+  });
+
+  test('getDetailPreview handles ANON_REQ', () => {
+    const result = api.getDetailPreview({
+      type: 'ANON_REQ', destHash: 'dd'
+    });
+    assert(result.includes('anon'));
+    assert(result.includes('dd'));
+  });
+
+  test('getDetailPreview handles text fallback', () => {
+    const result = api.getDetailPreview({ text: 'some message' });
+    assert(result.includes('some message'));
+  });
+
+  test('getDetailPreview truncates long text fallback', () => {
+    const result = api.getDetailPreview({ text: 'z'.repeat(100) });
+    assert(result.includes('…'));
+  });
+
+  test('getDetailPreview handles public_key fallback', () => {
+    const result = api.getDetailPreview({ public_key: 'abcdef1234567890abcdef' });
+    assert(result.includes('📡'));
+    assert(result.includes('abcdef1234567890'));
+  });
+
+  test('getDetailPreview returns empty for empty decoded', () => {
+    assert.strictEqual(api.getDetailPreview({}), '');
+  });
+}
+
+console.log('\n=== packets.js: getPathHopCount ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('getPathHopCount with valid path', () => {
+    assert.strictEqual(api.getPathHopCount({ path_json: '["a","b","c"]' }), 3);
+  });
+
+  test('getPathHopCount with empty path', () => {
+    assert.strictEqual(api.getPathHopCount({ path_json: '[]' }), 0);
+  });
+
+  test('getPathHopCount with null/missing', () => {
+    assert.strictEqual(api.getPathHopCount({}), 0);
+    assert.strictEqual(api.getPathHopCount({ path_json: null }), 0);
+  });
+
+  test('getPathHopCount with invalid JSON', () => {
+    assert.strictEqual(api.getPathHopCount({ path_json: 'not json' }), 0);
+  });
+}
+
+console.log('\n=== packets.js: sortGroupChildren ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('sortGroupChildren handles null/empty gracefully', () => {
+    api.sortGroupChildren(null);
+    api.sortGroupChildren({});
+    api.sortGroupChildren({ _children: [] });
+    // No throw
+  });
+
+  test('sortGroupChildren default sort groups by observer earliest-first', () => {
+    // Need to set obsSortMode — it reads from closure. Default is 'observer'.
+    const group = {
+      _children: [
+        { observer_name: 'B', timestamp: '2024-01-01T02:00:00Z' },
+        { observer_name: 'A', timestamp: '2024-01-01T01:00:00Z' },
+        { observer_name: 'B', timestamp: '2024-01-01T01:30:00Z' },
+      ]
+    };
+    api.sortGroupChildren(group);
+    // A has earliest timestamp, should be first
+    assert.strictEqual(group._children[0].observer_name, 'A');
+    // Then B entries
+    assert.strictEqual(group._children[1].observer_name, 'B');
+    assert.strictEqual(group._children[2].observer_name, 'B');
+    // B entries should be time-ascending within group
+    assert(group._children[1].timestamp < group._children[2].timestamp);
+  });
+
+  test('sortGroupChildren updates header from first child', () => {
+    const group = {
+      observer_id: 'old',
+      _children: [
+        { observer_name: 'A', observer_id: 'new-id', timestamp: '2024-01-01T01:00:00Z', snr: 10, rssi: -50, path_json: '["x"]', direction: 'rx' },
+      ]
+    };
+    api.sortGroupChildren(group);
+    assert.strictEqual(group.observer_id, 'new-id');
+    assert.strictEqual(group.snr, 10);
+    assert.strictEqual(group.rssi, -50);
+    assert.strictEqual(group.path_json, '["x"]');
+    assert.strictEqual(group.direction, 'rx');
+  });
+}
+
+console.log('\n=== packets.js: renderTimestampCell ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('renderTimestampCell produces HTML with timestamp-text', () => {
+    const result = api.renderTimestampCell('2024-01-15T10:30:00Z');
+    assert(result.includes('timestamp-text'));
+  });
+
+  test('renderTimestampCell handles null gracefully', () => {
+    const result = api.renderTimestampCell(null);
+    // Should not throw, produces some output
+    assert(typeof result === 'string');
+  });
+}
+
+console.log('\n=== packets.js: renderPath ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('renderPath returns dash for empty/null', () => {
+    assert.strictEqual(api.renderPath(null, null), '—');
+    assert.strictEqual(api.renderPath([], null), '—');
+  });
+
+  test('renderPath renders hops with arrows', () => {
+    const result = api.renderPath(['aa', 'bb'], null);
+    assert(result.includes('arrow'));
+    assert(result.includes('aa'));
+    assert(result.includes('bb'));
+  });
+
+  test('renderPath renders single hop without arrow', () => {
+    const result = api.renderPath(['cc'], null);
+    assert(result.includes('cc'));
+    assert(!result.includes('arrow'));
+  });
+}
+
+console.log('\n=== packets.js: renderDecodedPacket ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('renderDecodedPacket produces header section', () => {
+    const decoded = {
+      header: { routeType: 0, payloadType: 4, payloadVersion: 1 },
+      payload: { name: 'TestNode' },
+      path: { hops: [] }
+    };
+    const hex = 'aabbccdd';
+    const result = api.renderDecodedPacket(decoded, hex);
+    assert(result.includes('byop-decoded'));
+    assert(result.includes('Header'));
+    assert(result.includes('4 bytes'));
+  });
+
+  test('renderDecodedPacket renders path hops', () => {
+    const decoded = {
+      header: { routeType: 0, payloadType: 4 },
+      payload: {},
+      path: { hops: ['aa', 'bb'] }
+    };
+    const hex = 'aabbccdd';
+    const result = api.renderDecodedPacket(decoded, hex);
+    assert(result.includes('Path (2 hops)'));
+    assert(result.includes('aa'));
+    assert(result.includes('bb'));
+  });
+
+  test('renderDecodedPacket renders payload fields', () => {
+    const decoded = {
+      header: { routeType: 0, payloadType: 5 },
+      payload: { channel: 'general', text: 'hello' },
+      path: { hops: [] }
+    };
+    const hex = 'aabb';
+    const result = api.renderDecodedPacket(decoded, hex);
+    assert(result.includes('channel'));
+    assert(result.includes('general'));
+    assert(result.includes('hello'));
+  });
+
+  test('renderDecodedPacket renders nested objects as JSON', () => {
+    const decoded = {
+      header: { routeType: 0, payloadType: 0 },
+      payload: { flags: { repeater: true } },
+      path: { hops: [] }
+    };
+    const hex = 'aa';
+    const result = api.renderDecodedPacket(decoded, hex);
+    assert(result.includes('byop-pre'));
+    assert(result.includes('repeater'));
+  });
+
+  test('renderDecodedPacket skips null payload values', () => {
+    const decoded = {
+      header: { routeType: 0, payloadType: 0 },
+      payload: { a: null, b: undefined, c: 'visible' },
+      path: { hops: [] }
+    };
+    const hex = 'aa';
+    const result = api.renderDecodedPacket(decoded, hex);
+    assert(result.includes('visible'));
+    // null/undefined values should be skipped
+    const kvCount = (result.match(/byop-row/g) || []).length;
+    // Only 'c' should appear in payload (a and b are null/undefined), plus header fields
+    assert(kvCount >= 1);
+  });
+
+  test('renderDecodedPacket renders raw hex', () => {
+    const decoded = {
+      header: { routeType: 0, payloadType: 0 },
+      payload: {},
+      path: { hops: [] }
+    };
+    const hex = 'aabbcc';
+    const result = api.renderDecodedPacket(decoded, hex);
+    assert(result.includes('AA BB CC'));
+    assert(result.includes('byop-hex'));
+  });
+}
+
+console.log('\n=== packets.js: buildFieldTable ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('buildFieldTable produces table HTML', () => {
+    const pkt = { raw_hex: 'c0400102', route_type: 1, payload_type: 4 };
+    const decoded = { type: 'ADVERT', name: 'Node', pubKey: 'abc', flags: { type: 2, hasLocation: false, hasName: true, raw: 0x22 } };
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('field-table'));
+    assert(result.includes('Header'));
+    assert(result.includes('Header Byte'));
+    assert(result.includes('Path Length'));
+  });
+
+  test('buildFieldTable handles transport codes (route_type 0)', () => {
+    const pkt = { raw_hex: 'c0400102030405060708', route_type: 0, payload_type: 0 };
+    const decoded = { destHash: 'aa', srcHash: 'bb', mac: 'cc', encryptedData: 'dd' };
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('Transport Codes'));
+    assert(result.includes('Next Hop'));
+    assert(result.includes('Last Hop'));
+  });
+
+  test('buildFieldTable renders path hops', () => {
+    const pkt = { raw_hex: 'c042aabb', route_type: 1, payload_type: 0 };
+    const decoded = { destHash: 'xx' };
+    const result = api.buildFieldTable(pkt, decoded, ['aa', 'bb'], []);
+    assert(result.includes('Path (2 hops)'));
+    assert(result.includes('Hop 0'));
+    assert(result.includes('Hop 1'));
+  });
+
+  test('buildFieldTable renders ADVERT payload', () => {
+    const pkt = { raw_hex: 'c040', route_type: 1, payload_type: 4 };
+    const decoded = {
+      type: 'ADVERT', pubKey: 'abc123', timestamp: 1234567890,
+      timestampISO: '2009-02-13T23:31:30Z', signature: 'sig',
+      name: 'TestNode',
+      flags: { type: 1, hasLocation: true, hasName: true, raw: 0x55 }
+    };
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('Public Key'));
+    assert(result.includes('Timestamp'));
+    assert(result.includes('Signature'));
+    assert(result.includes('App Flags'));
+    assert(result.includes('Companion'));
+    assert(result.includes('Latitude'));
+    assert(result.includes('Node Name'));
+  });
+
+  test('buildFieldTable renders GRP_TXT payload', () => {
+    const pkt = { raw_hex: 'c040', route_type: 1, payload_type: 5 };
+    const decoded = { type: 'GRP_TXT', channelHash: 0xAB, mac: 'AABB', encryptedData: 'data', decryptionStatus: 'no_key' };
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('Channel Hash'));
+    assert(result.includes('MAC'));
+    assert(result.includes('Encrypted Data'));
+  });
+
+  test('buildFieldTable renders CHAN payload', () => {
+    const pkt = { raw_hex: 'c040', route_type: 1, payload_type: 5 };
+    const decoded = { type: 'CHAN', channel: 'general', sender: 'Alice', sender_timestamp: '12:00' };
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('Channel'));
+    assert(result.includes('general'));
+    assert(result.includes('Sender'));
+    assert(result.includes('Sender Time'));
+  });
+
+  test('buildFieldTable renders ACK payload', () => {
+    const pkt = { raw_hex: 'c040', route_type: 1, payload_type: 3 };
+    const decoded = { type: 'ACK', ackChecksum: 'DEADBEEF' };
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('Checksum'));
+    assert(result.includes('DEADBEEF'));
+  });
+
+  test('buildFieldTable renders destHash-based payload', () => {
+    const pkt = { raw_hex: 'c040', route_type: 1, payload_type: 2 };
+    const decoded = { destHash: 'DD', srcHash: 'SS', mac: 'MM', encryptedData: 'EE' };
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('Dest Hash'));
+    assert(result.includes('Src Hash'));
+  });
+
+  test('buildFieldTable renders raw fallback for unknown payload', () => {
+    const pkt = { raw_hex: 'c040aabbccdd', route_type: 1, payload_type: 99 };
+    const decoded = {};
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('Raw'));
+  });
+
+  test('buildFieldTable hash_size calculation', () => {
+    // Path byte 0xC0 → bits 7-6 = 3 → hash_size = 4
+    const pkt = { raw_hex: '00C0', route_type: 1, payload_type: 0 };
+    const decoded = {};
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('hash_size=4'));
+  });
+
+  test('buildFieldTable handles empty raw_hex', () => {
+    const pkt = { raw_hex: '', route_type: 1, payload_type: 0 };
+    const decoded = {};
+    const result = api.buildFieldTable(pkt, decoded, [], []);
+    assert(result.includes('field-table'));
+    assert(result.includes('0B') || result.includes('0 bytes') || result.includes('??'));
+  });
+}
+
+console.log('\n=== packets.js: _getRowCount ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('_getRowCount returns 1 for ungrouped', () => {
+    // _displayGrouped is internal, but when not grouped, should return 1
+    // Since we can't easily control _displayGrouped, test the function behavior
+    const result = api._getRowCount({ hash: 'abc', _children: [{ observer_id: '1' }] });
+    // Default _displayGrouped depends on initialization, but the function should not throw
+    assert(typeof result === 'number');
+    assert(result >= 1);
+  });
+}
+
+console.log('\n=== packets.js: buildFlatRowHtml ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('buildFlatRowHtml produces table row', () => {
+    const p = {
+      id: 1, hash: 'abc123', timestamp: '2024-01-01T00:00:00Z',
+      observer_id: null, raw_hex: 'aabb', payload_type: 4,
+      route_type: 1, decoded_json: '{}', path_json: '[]'
+    };
+    const result = api.buildFlatRowHtml(p);
+    assert(result.includes('<tr'));
+    assert(result.includes('data-id="1"'));
+    assert(result.includes('data-hash="abc123"'));
+  });
+
+  test('buildFlatRowHtml calculates size from hex', () => {
+    const p = {
+      id: 2, hash: 'x', timestamp: '', observer_id: null,
+      raw_hex: 'aabbccdd', payload_type: 0, route_type: 0,
+      decoded_json: '{}', path_json: '[]'
+    };
+    const result = api.buildFlatRowHtml(p);
+    assert(result.includes('4B'));  // 8 hex chars = 4 bytes
+  });
+
+  test('buildFlatRowHtml handles missing raw_hex', () => {
+    const p = {
+      id: 3, hash: 'y', timestamp: '', observer_id: null,
+      raw_hex: null, payload_type: 0, route_type: 0,
+      decoded_json: '{}', path_json: '[]'
+    };
+    const result = api.buildFlatRowHtml(p);
+    assert(result.includes('0B'));
+  });
+}
+
+console.log('\n=== packets.js: buildGroupRowHtml ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('buildGroupRowHtml renders single-count group', () => {
+    const p = {
+      hash: 'abc', count: 1, latest: '2024-01-01T00:00:00Z',
+      observer_id: null, raw_hex: 'aabb', payload_type: 4,
+      route_type: 1, decoded_json: '{}', path_json: '[]',
+      observation_count: 1, observer_count: 1
+    };
+    const result = api.buildGroupRowHtml(p);
+    assert(result.includes('<tr'));
+    assert(result.includes('data-hash="abc"'));
+    // Single count: no expand arrow, no group-header class
+    assert(!result.includes('group-header'));
+  });
+
+  test('buildGroupRowHtml renders multi-count group with expand arrow', () => {
+    const p = {
+      hash: 'xyz', count: 3, latest: '2024-01-01T00:00:00Z',
+      observer_id: null, raw_hex: 'aabbcc', payload_type: 0,
+      route_type: 0, decoded_json: '{}', path_json: '[]',
+      observation_count: 3, observer_count: 2
+    };
+    const result = api.buildGroupRowHtml(p);
+    assert(result.includes('group-header'));
+    assert(result.includes('▶'));  // collapsed arrow
+  });
+
+  test('buildGroupRowHtml shows observation count badge', () => {
+    const p = {
+      hash: 'obs', count: 1, latest: '2024-01-01T00:00:00Z',
+      observer_id: null, raw_hex: 'aa', payload_type: 0,
+      route_type: 0, decoded_json: '{}', path_json: '[]',
+      observation_count: 5, observer_count: 1
+    };
+    const result = api.buildGroupRowHtml(p);
+    assert(result.includes('badge-obs'));
+    assert(result.includes('👁'));
+    assert(result.includes('5'));
+  });
+}
+
+console.log('\n=== packets.js: page registration ===');
+{
+  const ctx = loadPacketsSandbox();
+  // registerPage is defined in app.js and stores in its own `pages` closure.
+  // We verify via the navigateTo mechanism or by checking the pages object isn't empty.
+  // Since we can't easily access the closure, just verify the test API is exposed.
+  test('_packetsTestAPI is exposed on window', () => {
+    assert(ctx._packetsTestAPI);
+    assert(typeof ctx._packetsTestAPI.typeName === 'function');
+    assert(typeof ctx._packetsTestAPI.getDetailPreview === 'function');
+    assert(typeof ctx._packetsTestAPI.sortGroupChildren === 'function');
+    assert(typeof ctx._packetsTestAPI.buildFieldTable === 'function');
+  });
+}
+
+console.log('\n=== packets.js: _invalidateRowCounts / _refreshRowCountsIfDirty (#410) ===');
+{
+  const ctx = loadPacketsSandbox();
+  const api = ctx._packetsTestAPI;
+
+  test('_invalidateRowCounts and _refreshRowCountsIfDirty are exported', () => {
+    assert(typeof api._invalidateRowCounts === 'function');
+    assert(typeof api._refreshRowCountsIfDirty === 'function');
+  });
+
+  test('_invalidateRowCounts does not throw', () => {
+    api._invalidateRowCounts();
+  });
+
+  test('_refreshRowCountsIfDirty does not throw when no display packets', () => {
+    api._invalidateRowCounts();
+    api._refreshRowCountsIfDirty();
+  });
+
+  test('_cumulativeRowOffsets returns valid offsets after invalidation cycle', () => {
+    // Even with no display packets, should return valid array
+    const offsets = api._cumulativeRowOffsets();
+    assert(Array.isArray(offsets));
+    assert(offsets[0] === 0);
+  });
+}
+
+// ===== SUMMARY =====
+console.log(`\n${'='.repeat(40)}`);
+console.log(`packets.js tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

test-prefix-tool.js

@@ -0,0 +1,268 @@
+/* Unit tests for prefix tool logic (analytics.js _prefixToolExports) */
+'use strict';
+const vm = require('vm');
+const fs = require('fs');
+const assert = require('assert');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ✅ ${name}`); }
+  catch (e) { failed++; console.log(`  ❌ ${name}: ${e.message}`); }
+}
+
+// Load analytics.js in a VM sandbox with minimal stubs
+const code = fs.readFileSync(__dirname + '/public/analytics.js', 'utf8');
+const sandbox = {
+  window: {},
+  document: { addEventListener() {} },
+  location: { hash: '' },
+  setTimeout: () => {},
+  requestAnimationFrame: () => {},
+  console,
+  Map, Set, Array, Object, Number, Math, Date, JSON,
+  encodeURIComponent,
+  URLSearchParams,
+  parseInt, parseFloat, isNaN, isFinite,
+  RegExp, Error, TypeError, RangeError,
+  Promise: { resolve: () => ({ then: () => ({}) }) },
+};
+sandbox.window = sandbox;
+sandbox.self = sandbox;
+
+try {
+  vm.runInNewContext(code, sandbox, { filename: 'analytics.js', timeout: 5000 });
+} catch (e) {
+  // IIFE may throw due to missing DOM — that's fine, we just need the exports
+}
+
+const ex = sandbox.window._prefixToolExports;
+if (!ex) {
+  console.log('❌ _prefixToolExports not found on window');
+  process.exit(1);
+}
+
+const { buildPrefixIndex, computePrefixStats, recommendPrefixSize,
+        validatePrefixInput, checkPrefix, generatePrefix,
+        renderSeverityBadge, PREFIX_SPACE_SIZES } = ex;
+
+console.log('\n--- buildPrefixIndex ---');
+
+test('builds 3-tier index from nodes', () => {
+  const nodes = [
+    { public_key: 'A1B2C3D4E5F6' },
+    { public_key: 'A1B2FFFFFF00' },
+    { public_key: 'FF00112233AA' },
+  ];
+  const idx = buildPrefixIndex(nodes);
+  assert.strictEqual(idx[1].size, 2); // A1, FF
+  assert.strictEqual(idx[2].size, 2); // A1B2, FF00
+  assert.strictEqual(idx[3].size, 3); // A1B2C3, A1B2FF, FF0011
+  assert.strictEqual(idx[1].get('A1').length, 2);
+  assert.strictEqual(idx[2].get('A1B2').length, 2);
+  assert.strictEqual(idx[1].get('FF').length, 1);
+});
+
+test('handles empty node list', () => {
+  const idx = buildPrefixIndex([]);
+  assert.strictEqual(idx[1].size, 0);
+  assert.strictEqual(idx[2].size, 0);
+  assert.strictEqual(idx[3].size, 0);
+});
+
+console.log('\n--- computePrefixStats ---');
+
+test('detects collisions', () => {
+  const nodes = [
+    { public_key: 'A1B2C3D4E5F6' },
+    { public_key: 'A1B2FFFFFF00' },
+  ];
+  const idx = buildPrefixIndex(nodes);
+  const stats = computePrefixStats(idx);
+  assert.strictEqual(stats[1].collidingPrefixes, 1); // A1 collides
+  assert.strictEqual(stats[2].collidingPrefixes, 1); // A1B2 collides
+  assert.strictEqual(stats[3].collidingPrefixes, 0); // no 3-byte collision
+});
+
+test('no collisions when all unique', () => {
+  const nodes = [
+    { public_key: 'A1B2C3D4E5F6' },
+    { public_key: 'B1B2C3D4E5F6' },
+  ];
+  const idx = buildPrefixIndex(nodes);
+  const stats = computePrefixStats(idx);
+  assert.strictEqual(stats[1].collidingPrefixes, 0);
+});
+
+console.log('\n--- recommendPrefixSize ---');
+
+test('recommends 1-byte for small networks (<20)', () => {
+  const r = recommendPrefixSize(5);
+  assert.strictEqual(r.rec, '1-byte');
+});
+
+test('recommends 2-byte for medium networks (20-499)', () => {
+  const r = recommendPrefixSize(100);
+  assert.strictEqual(r.rec, '2-byte');
+});
+
+test('recommends 3-byte for large networks (>=500)', () => {
+  const r = recommendPrefixSize(500);
+  assert.strictEqual(r.rec, '3-byte');
+});
+
+test('recommends 3-byte for very large networks', () => {
+  const r = recommendPrefixSize(5000);
+  assert.strictEqual(r.rec, '3-byte');
+});
+
+test('boundary: 19 nodes = 1-byte', () => {
+  assert.strictEqual(recommendPrefixSize(19).rec, '1-byte');
+});
+
+test('boundary: 20 nodes = 2-byte', () => {
+  assert.strictEqual(recommendPrefixSize(20).rec, '2-byte');
+});
+
+test('boundary: 499 nodes = 2-byte', () => {
+  assert.strictEqual(recommendPrefixSize(499).rec, '2-byte');
+});
+
+console.log('\n--- validatePrefixInput ---');
+
+test('empty input', () => {
+  const r = validatePrefixInput('');
+  assert.strictEqual(r.valid, false);
+  assert.strictEqual(r.isEmpty, true);
+});
+
+test('valid 1-byte prefix', () => {
+  const r = validatePrefixInput('A1');
+  assert.strictEqual(r.valid, true);
+  assert.strictEqual(r.tiers.length, 1);
+  assert.strictEqual(r.tiers[0].b, 1);
+  assert.strictEqual(r.tiers[0].prefix, 'A1');
+});
+
+test('valid 2-byte prefix', () => {
+  const r = validatePrefixInput('a1b2');
+  assert.strictEqual(r.valid, true);
+  assert.strictEqual(r.tiers[0].prefix, 'A1B2');
+  assert.strictEqual(r.isFullKey, false);
+});
+
+test('valid 3-byte prefix', () => {
+  const r = validatePrefixInput('A1B2C3');
+  assert.strictEqual(r.valid, true);
+  assert.strictEqual(r.tiers[0].b, 3);
+});
+
+test('full public key (64 chars) derives 3 tiers', () => {
+  const pk = 'A1B2C3D4' + '0'.repeat(56);
+  const r = validatePrefixInput(pk);
+  assert.strictEqual(r.valid, true);
+  assert.strictEqual(r.isFullKey, true);
+  assert.strictEqual(r.tiers.length, 3);
+  assert.strictEqual(r.tiers[0].prefix, 'A1');
+  assert.strictEqual(r.tiers[1].prefix, 'A1B2');
+  assert.strictEqual(r.tiers[2].prefix, 'A1B2C3');
+});
+
+test('rejects non-hex', () => {
+  const r = validatePrefixInput('ZZZZ');
+  assert.strictEqual(r.valid, false);
+  assert(r.error.includes('hex'));
+});
+
+test('rejects odd-length input', () => {
+  const r = validatePrefixInput('A1B');
+  assert.strictEqual(r.valid, false);
+  assert(r.error.includes('2, 4, or 6'));
+});
+
+console.log('\n--- checkPrefix ---');
+
+test('detects collision on 1-byte', () => {
+  const nodes = [{ public_key: 'A1B2C3D4E5F6' }, { public_key: 'A1FFFFFF0000' }];
+  const idx = buildPrefixIndex(nodes);
+  const r = checkPrefix('A1', idx, nodes);
+  assert.strictEqual(r.valid, true);
+  assert.strictEqual(r.results[0].count, 2);
+});
+
+test('no collision for unused prefix', () => {
+  const nodes = [{ public_key: 'A1B2C3D4E5F6' }];
+  const idx = buildPrefixIndex(nodes);
+  const r = checkPrefix('FF', idx, nodes);
+  assert.strictEqual(r.results[0].count, 0);
+});
+
+test('full key excludes self from colliders', () => {
+  const pk = 'A1B2C3D4E5F60000';
+  const nodes = [{ public_key: pk }, { public_key: 'A1B2FFFFFF000000' }];
+  const idx = buildPrefixIndex(nodes);
+  const r = checkPrefix(pk, idx, nodes);
+  assert.strictEqual(r.isFullKey, true);
+  // 1-byte tier: A1 has both nodes, but self excluded = 1 collider
+  assert.strictEqual(r.results[0].count, 1);
+});
+
+console.log('\n--- generatePrefix ---');
+
+test('generates a collision-free 1-byte prefix', () => {
+  const nodes = [];
+  // Fill all but one 1-byte prefix
+  for (let i = 0; i < 255; i++) {
+    nodes.push({ public_key: i.toString(16).toUpperCase().padStart(2, '0') + '0000000000' });
+  }
+  const idx = buildPrefixIndex(nodes);
+  const prefix = generatePrefix(1, idx, () => 0.5);
+  assert.strictEqual(prefix, 'FF'); // only FF is free
+  assert(!idx[1].has(prefix));
+});
+
+test('returns null when no prefix available', () => {
+  const nodes = [];
+  for (let i = 0; i < 256; i++) {
+    nodes.push({ public_key: i.toString(16).toUpperCase().padStart(2, '0') + '0000000000' });
+  }
+  const idx = buildPrefixIndex(nodes);
+  const prefix = generatePrefix(1, idx);
+  assert.strictEqual(prefix, null);
+});
+
+test('generates 2-byte prefix not in index', () => {
+  const nodes = [{ public_key: 'A1B2C3D4E5F6' }];
+  const idx = buildPrefixIndex(nodes);
+  const prefix = generatePrefix(2, idx, () => 0.5);
+  assert.strictEqual(typeof prefix, 'string');
+  assert.strictEqual(prefix.length, 4);
+  assert(!idx[2].has(prefix));
+});
+
+test('uses deterministic random function', () => {
+  const nodes = [{ public_key: 'A1B2C3D4E5F6' }];
+  const idx = buildPrefixIndex(nodes);
+  const p1 = generatePrefix(2, idx, () => 0.1);
+  const p2 = generatePrefix(2, idx, () => 0.1);
+  assert.strictEqual(p1, p2);
+});
+
+console.log('\n--- renderSeverityBadge ---');
+
+test('unique badge for 0', () => {
+  assert(renderSeverityBadge(0).includes('Unique'));
+});
+
+test('warning badge for 1-2', () => {
+  assert(renderSeverityBadge(1).includes('1 collision'));
+  assert(renderSeverityBadge(2).includes('2 collisions'));
+});
+
+test('red badge for 3+', () => {
+  assert(renderSeverityBadge(5).includes('5 collisions'));
+  assert(renderSeverityBadge(5).includes('status-red'));
+});
+
+// --- Summary ---
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

test-show-neighbors.js

@@ -0,0 +1,242 @@
+/**
+ * Show Neighbors E2E tests (#484 fix)
+ * Tests that selectReferenceNode() uses the affinity API instead of client-side path walking.
+ * Usage: CHROMIUM_PATH=/usr/bin/chromium-browser BASE_URL=http://localhost:13590 node test-show-neighbors.js
+ */
+const { chromium } = require('playwright');
+
+const BASE = process.env.BASE_URL || 'http://localhost:3000';
+const results = [];
+
+async function test(name, fn) {
+  try {
+    await fn();
+    results.push({ name, pass: true });
+    console.log(`  ✅ ${name}`);
+  } catch (err) {
+    results.push({ name, pass: false, error: err.message });
+    console.log(`  ❌ ${name}: ${err.message}`);
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg || 'Assertion failed');
+}
+
+async function run() {
+  console.log('Launching Chromium...');
+  const launchOpts = { headless: true, args: ['--no-sandbox', '--disable-gpu'] };
+  if (process.env.CHROMIUM_PATH) launchOpts.executablePath = process.env.CHROMIUM_PATH;
+  const browser = await chromium.launch(launchOpts);
+  const page = await browser.newPage();
+
+  console.log(`\nRunning Show Neighbors tests against ${BASE}\n`);
+
+  await test('Show Neighbors calls affinity API and populates neighborPubkeys', async () => {
+    const testPubkey = 'aabbccdd11223344556677889900aabbccddeeff00112233445566778899001122';
+    const neighborPubkey1 = '1111111111111111111111111111111111111111111111111111111111111111';
+    const neighborPubkey2 = '2222222222222222222222222222222222222222222222222222222222222222';
+
+    let apiCalled = false;
+    await page.route(`**/api/nodes/${testPubkey}/neighbors*`, route => {
+      apiCalled = true;
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          node: testPubkey,
+          neighbors: [
+            { pubkey: neighborPubkey1, prefix: '11', name: 'Neighbor-1', role: 'repeater', count: 50, score: 0.9, ambiguous: false },
+            { pubkey: neighborPubkey2, prefix: '22', name: 'Neighbor-2', role: 'companion', count: 20, score: 0.7, ambiguous: false }
+          ],
+          total_observations: 70
+        })
+      });
+    });
+
+    await page.goto(`${BASE}/#/map`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    const result = await page.evaluate(async (args) => {
+      if (typeof window._mapSelectRefNode !== 'function') return { error: 'no _mapSelectRefNode function' };
+      if (typeof window._mapGetNeighborPubkeys !== 'function') return { error: 'no _mapGetNeighborPubkeys function' };
+      await window._mapSelectRefNode(args.pk, 'TestNode');
+      return { neighbors: window._mapGetNeighborPubkeys() };
+    }, { pk: testPubkey });
+
+    assert(!result.error, result.error || '');
+    assert(apiCalled, 'The /neighbors API should have been called');
+    assert(result.neighbors.includes(neighborPubkey1), `Should contain neighbor1, got: ${JSON.stringify(result.neighbors)}`);
+    assert(result.neighbors.includes(neighborPubkey2), `Should contain neighbor2, got: ${JSON.stringify(result.neighbors)}`);
+    assert(result.neighbors.length === 2, `Should have exactly 2 neighbors, got ${result.neighbors.length}`);
+    await page.unroute(`**/api/nodes/${testPubkey}/neighbors*`);
+  });
+
+  await test('Show Neighbors resolves correct node on hash collision via affinity API', async () => {
+    const nodeA = 'c0dedad4208acb6cbe44b848943fc6d3c5d43cf38a21e48b43826a70862980e4';
+    const nodeB = 'c0f1a2b3000000000000000000000000000000000000000000000000000000ff';
+    const neighborR1 = 'r1aaaaaa000000000000000000000000000000000000000000000000000000aa';
+    const neighborR2 = 'r2bbbbbb000000000000000000000000000000000000000000000000000000bb';
+    const neighborR4 = 'r4dddddd000000000000000000000000000000000000000000000000000000dd';
+
+    await page.route(`**/api/nodes/${nodeA}/neighbors*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          node: nodeA,
+          neighbors: [
+            { pubkey: neighborR1, prefix: 'R1', name: 'Repeater-R1', role: 'repeater', count: 100, score: 0.95, ambiguous: false },
+            { pubkey: neighborR2, prefix: 'R2', name: 'Repeater-R2', role: 'repeater', count: 80, score: 0.85, ambiguous: false }
+          ],
+          total_observations: 180
+        })
+      });
+    });
+
+    await page.route(`**/api/nodes/${nodeB}/neighbors*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          node: nodeB,
+          neighbors: [
+            { pubkey: neighborR4, prefix: 'R4', name: 'Repeater-R4', role: 'repeater', count: 60, score: 0.75, ambiguous: false }
+          ],
+          total_observations: 60
+        })
+      });
+    });
+
+    await page.goto(`${BASE}/#/map`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    // Select Node A — should get R1, R2 but NOT R4
+    const resultA = await page.evaluate(async (pk) => {
+      await window._mapSelectRefNode(pk, 'NodeA');
+      return window._mapGetNeighborPubkeys();
+    }, nodeA);
+    assert(resultA.includes(neighborR1), 'Node A should have R1 as neighbor');
+    assert(resultA.includes(neighborR2), 'Node A should have R2 as neighbor');
+    assert(!resultA.includes(neighborR4), 'Node A should NOT have R4 (that belongs to Node B)');
+
+    // Select Node B — should get R4 but NOT R1, R2
+    const resultB = await page.evaluate(async (pk) => {
+      await window._mapSelectRefNode(pk, 'NodeB');
+      return window._mapGetNeighborPubkeys();
+    }, nodeB);
+    assert(resultB.includes(neighborR4), 'Node B should have R4 as neighbor');
+    assert(!resultB.includes(neighborR1), 'Node B should NOT have R1 (that belongs to Node A)');
+    assert(!resultB.includes(neighborR2), 'Node B should NOT have R2 (that belongs to Node A)');
+
+    await page.unroute(`**/api/nodes/${nodeA}/neighbors*`);
+    await page.unroute(`**/api/nodes/${nodeB}/neighbors*`);
+  });
+
+  await test('Show Neighbors falls back to path walking when affinity API returns empty', async () => {
+    const testPubkey = 'fallbacktest0000000000000000000000000000000000000000000000000000';
+    const hopBefore = 'aaaa000000000000000000000000000000000000000000000000000000000000';
+    const hopAfter = 'bbbb000000000000000000000000000000000000000000000000000000000000';
+
+    let neighborApiCalled = false;
+    let pathsApiCalled = false;
+
+    await page.route(`**/api/nodes/${testPubkey}/neighbors*`, route => {
+      neighborApiCalled = true;
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ node: testPubkey, neighbors: [], total_observations: 0 })
+      });
+    });
+
+    await page.route(`**/api/nodes/${testPubkey}/paths*`, route => {
+      pathsApiCalled = true;
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          paths: [{
+            hops: [
+              { pubkey: hopBefore, name: 'HopBefore' },
+              { pubkey: testPubkey, name: 'Self' },
+              { pubkey: hopAfter, name: 'HopAfter' }
+            ]
+          }]
+        })
+      });
+    });
+
+    await page.goto(`${BASE}/#/map`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    const result = await page.evaluate(async (pk) => {
+      if (typeof window._mapSelectRefNode !== 'function') return { error: 'no-function' };
+      await window._mapSelectRefNode(pk, 'FallbackNode');
+      return { neighbors: window._mapGetNeighborPubkeys() };
+    }, testPubkey);
+
+    assert(!result.error, result.error || '');
+    assert(neighborApiCalled, 'Should try neighbor API first');
+    assert(pathsApiCalled, 'Should fall back to paths API when neighbors empty');
+    assert(result.neighbors.includes(hopBefore), 'Fallback should find hopBefore as neighbor');
+    assert(result.neighbors.includes(hopAfter), 'Fallback should find hopAfter as neighbor');
+    assert(result.neighbors.length === 2, `Fallback should find exactly 2 neighbors, got ${result.neighbors.length}`);
+    await page.unroute(`**/api/nodes/${testPubkey}/neighbors*`);
+    await page.unroute(`**/api/nodes/${testPubkey}/paths*`);
+  });
+
+  await test('Show Neighbors includes ambiguous candidates in neighborPubkeys', async () => {
+    const testPubkey = 'ambigtest000000000000000000000000000000000000000000000000000000';
+    const candidate1 = 'a3b4c500000000000000000000000000000000000000000000000000000000';
+    const candidate2 = 'a3f0e100000000000000000000000000000000000000000000000000000000';
+    const knownNeighbor = 'b7e8f9a000000000000000000000000000000000000000000000000000000000';
+
+    await page.route(`**/api/nodes/${testPubkey}/neighbors*`, route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          node: testPubkey,
+          neighbors: [
+            { pubkey: knownNeighbor, prefix: 'B7', name: 'Known-Neighbor', role: 'repeater', count: 100, score: 0.95, ambiguous: false },
+            { pubkey: null, prefix: 'A3', name: null, role: null, count: 12, score: 0.08, ambiguous: true,
+              candidates: [
+                { pubkey: candidate1, name: 'Node-Alpha', role: 'companion' },
+                { pubkey: candidate2, name: 'Node-Beta', role: 'companion' }
+              ]
+            }
+          ],
+          total_observations: 112
+        })
+      });
+    });
+
+    await page.goto(`${BASE}/#/map`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    const result = await page.evaluate(async (pk) => {
+      await window._mapSelectRefNode(pk, 'AmbigNode');
+      return window._mapGetNeighborPubkeys();
+    }, testPubkey);
+
+    // Should include the known neighbor AND both ambiguous candidates
+    assert(result.includes(knownNeighbor), 'Should include known neighbor');
+    assert(result.includes(candidate1), 'Should include ambiguous candidate 1');
+    assert(result.includes(candidate2), 'Should include ambiguous candidate 2');
+    assert(result.length === 3, `Should have 3 neighbors (1 known + 2 candidates), got ${result.length}`);
+    await page.unroute(`**/api/nodes/${testPubkey}/neighbors*`);
+  });
+
+  await browser.close();
+
+  const passed = results.filter(r => r.pass).length;
+  const failed = results.filter(r => !r.pass).length;
+  console.log(`\n${passed}/${results.length} tests passed${failed ? `, ${failed} failed` : ''}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+run().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

tools/geofilter-builder.html

@@ -0,0 +1,153 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>GeoFilter Builder</title>
+<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"/>
+<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: system-ui, sans-serif; background: #1a1a2e; color: #e0e0e0; height: 100vh; display: flex; flex-direction: column; }
+  header { padding: 12px 16px; background: #0f0f23; border-bottom: 1px solid #333; display: flex; align-items: center; gap: 16px; flex-wrap: wrap; }
+  header h1 { font-size: 1rem; font-weight: 600; color: #4a9eff; white-space: nowrap; }
+  .controls { display: flex; gap: 8px; flex-wrap: wrap; }
+  button { padding: 6px 14px; border: none; border-radius: 6px; cursor: pointer; font-size: 0.85rem; font-weight: 500; }
+  #btnUndo  { background: #333; color: #ccc; }
+  #btnClear { background: #5a2020; color: #ffaaaa; }
+  #btnUndo:hover  { background: #444; }
+  #btnClear:hover { background: #7a2020; }
+  .hint { font-size: 0.8rem; color: #888; margin-left: auto; }
+  #map { flex: 1; }
+  #output-panel { background: #0f0f23; border-top: 1px solid #333; padding: 12px 16px; display: flex; gap: 12px; align-items: flex-start; }
+  #output-panel label { font-size: 0.75rem; color: #888; white-space: nowrap; padding-top: 6px; }
+  #output { flex: 1; background: #111; border: 1px solid #333; border-radius: 6px; padding: 10px 12px; font-family: monospace; font-size: 0.78rem; color: #7ec8e3; white-space: pre; overflow-x: auto; min-height: 54px; max-height: 140px; overflow-y: auto; cursor: text; }
+  #output.empty { color: #555; font-style: italic; }
+  #btnCopy { padding: 6px 14px; background: #1a4a7a; color: #7ec8e3; border-radius: 6px; border: none; cursor: pointer; font-size: 0.85rem; white-space: nowrap; align-self: flex-end; }
+  #btnCopy:hover { background: #2a6aaa; }
+  #btnCopy.copied { background: #1a6a3a; color: #7effa0; }
+  #counter { font-size: 0.8rem; color: #888; padding-top: 6px; white-space: nowrap; }
+  .bufferRow { display: flex; align-items: center; gap: 8px; }
+  .bufferRow label { font-size: 0.85rem; color: #aaa; }
+  .bufferRow input { width: 60px; padding: 5px 8px; background: #222; border: 1px solid #444; border-radius: 6px; color: #eee; font-size: 0.85rem; }
+</style>
+</head>
+<body>
+
+<header>
+  <h1>GeoFilter Builder</h1>
+  <div class="controls">
+    <button id="btnUndo">↩ Undo</button>
+    <button id="btnClear">✕ Clear</button>
+  </div>
+  <div class="bufferRow">
+    <label for="bufferKm">Buffer km:</label>
+    <input type="number" id="bufferKm" value="20" min="0" max="500"/>
+  </div>
+  <span class="hint">Click on the map to add polygon points</span>
+</header>
+
+<div id="map"></div>
+
+<div id="output-panel">
+  <label>config.json</label>
+  <div id="output" class="empty">Add at least 3 points to generate config…</div>
+  <div style="display:flex;flex-direction:column;gap:8px;align-items:flex-end">
+    <span id="counter">0 points</span>
+    <button id="btnCopy">Copy</button>
+  </div>
+</div>
+
+<script>
+const map = L.map('map').setView([50.5, 4.4], 8);
+
+L.tileLayer('https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png', {
+  attribution: '© OpenStreetMap © CartoDB',
+  maxZoom: 19
+}).addTo(map);
+
+let points = [];
+let markers = [];
+let polygon = null;
+let closingLine = null;
+
+function latLonPair(latlng) {
+  return [parseFloat(latlng.lat.toFixed(6)), parseFloat(latlng.lng.toFixed(6))];
+}
+
+function render() {
+  // Remove existing polygon and closing line
+  if (polygon) { map.removeLayer(polygon); polygon = null; }
+  if (closingLine) { map.removeLayer(closingLine); closingLine = null; }
+
+  if (points.length >= 3) {
+    polygon = L.polygon(points, {
+      color: '#4a9eff', weight: 2, fillColor: '#4a9eff', fillOpacity: 0.12
+    }).addTo(map);
+  } else if (points.length === 2) {
+    closingLine = L.polyline(points, { color: '#4a9eff', weight: 2, dashArray: '5,5' }).addTo(map);
+  }
+
+  updateOutput();
+}
+
+function updateOutput() {
+  const el = document.getElementById('output');
+  const counter = document.getElementById('counter');
+  counter.textContent = points.length + ' point' + (points.length !== 1 ? 's' : '');
+
+  if (points.length < 3) {
+    el.textContent = 'Add at least 3 points to generate config…';
+    el.classList.add('empty');
+    return;
+  }
+  el.classList.remove('empty');
+
+  const bufferKm = parseFloat(document.getElementById('bufferKm').value) || 0;
+  const config = { bufferKm, polygon: points };
+  el.textContent = JSON.stringify({ geo_filter: config }, null, 2);
+}
+
+map.on('click', function(e) {
+  const pt = latLonPair(e.latlng);
+  points.push(pt);
+
+  const idx = points.length;
+  const marker = L.circleMarker(e.latlng, {
+    radius: 6, color: '#4a9eff', weight: 2, fillColor: '#4a9eff', fillOpacity: 0.9
+  }).addTo(map).bindTooltip(String(idx), { permanent: true, direction: 'top', offset: [0, -8], className: 'pt-label' });
+  markers.push(marker);
+
+  render();
+});
+
+document.getElementById('btnUndo').addEventListener('click', function() {
+  if (!points.length) return;
+  points.pop();
+  const m = markers.pop();
+  if (m) map.removeLayer(m);
+  render();
+});
+
+document.getElementById('btnClear').addEventListener('click', function() {
+  points = [];
+  markers.forEach(m => map.removeLayer(m));
+  markers = [];
+  render();
+});
+
+document.getElementById('bufferKm').addEventListener('input', updateOutput);
+
+document.getElementById('btnCopy').addEventListener('click', function() {
+  if (points.length < 3) return;
+  const text = document.getElementById('output').textContent;
+  navigator.clipboard.writeText(text).then(() => {
+    const btn = document.getElementById('btnCopy');
+    btn.textContent = 'Copied!';
+    btn.classList.add('copied');
+    setTimeout(() => { btn.textContent = 'Copy'; btn.classList.remove('copied'); }, 2000);
+  });
+});
+</script>
+</body>
+</html>