From 64745f89b10e765db7048c641e968d307b40f207 Mon Sep 17 00:00:00 2001
From: Kpa-clawbot <kpaclawbot@outlook.com>
Date: Thu, 2 Apr 2026 21:14:38 -0700
Subject: [PATCH] =?UTF-8?q?feat:=20customizer=20v2=20=E2=80=94=20event-dri?=
 =?UTF-8?q?ven=20state=20management=20(#502)=20(#503)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Implements the customizer v2 per the [approved
spec](docs/specs/customizer-rework.md), replacing the v1 customizer's
scattered state management with a clean event-driven architecture.
Resolves #502.

## What Changed

### New: `public/customize-v2.js`
Complete rewrite of the customizer as a self-contained IIFE with:

- **Single localStorage key** (`cs-theme-overrides`) replacing 7
scattered keys
- **Three state layers:** server defaults (immutable) → user overrides
(delta) → effective config (computed)
- **Full data flow pipeline:** `write → read-back → merge → atomic
SITE_CONFIG assign → apply CSS → dispatch theme-changed`
- **Color picker optimistic CSS** (Decision #12): `input` events update
CSS directly for responsiveness; `change` events trigger the full
pipeline
- **Override indicator dots** (●) on each field — click to reset
individual values
- **Section-level override count badges** on tabs
- **Browser-local banner** in panel header: "These settings are saved in
your browser only"
- **Auto-save status indicator** in footer: "All changes saved" /
"Saving..." / "⚠️ Storage full"
- **Export/Import** with full shape validation (`validateShape()`)
- **Presets** flow through the standard pipeline
(`writeOverrides(presetData) → pipeline`)
- **One-time migration** from 7 legacy localStorage keys (exact field
mapping per spec)
- **Validation** on all writes: color format, opacity range, timestamp
enum values
- **QuotaExceededError handling** with visible user warning

### Modified: `public/app.js`
Replaced ~80 lines of inline theme application code with a 15-line
`_customizerV2.init(cfg)` call. The customizer v2 handles all merging,
CSS application, and global state updates.

### Modified: `public/index.html`
Swapped `customize.js` → `customize-v2.js` script tag.

### Added: `docs/specs/customizer-rework.md`
The full approved spec, included in the repo for reference.

## Migration

On first page load:
1. Checks if `cs-theme-overrides` already exists → skip if yes
2. Reads all 7 legacy keys (`meshcore-user-theme`,
`meshcore-timestamp-*`, `meshcore-heatmap-opacity`,
`meshcore-live-heatmap-opacity`)
3. Maps them to the new delta format per the spec's field-by-field
mapping
4. Writes to `cs-theme-overrides`, removes all legacy keys
5. Continues with normal init

Users with existing customizations will see them preserved
automatically.

## Dark/Light Mode

- `theme` section stores light mode overrides, `themeDark` stores dark
mode overrides
- `meshcore-theme` localStorage key remains **separate** (view
preference, not customization)
- Switching modes re-runs the full pipeline with the correct section

## Testing

- All existing tests pass (`test-packet-filter.js`, `test-aging.js`,
`test-frontend-helpers.js`)
- Old `customize.js` is NOT modified — left in place for reference but
no longer loaded

## Not in Scope (per spec)

- Undo/redo stack
- Cross-tab synchronization
- Server-side admin import endpoint
- Map config / geo-filter overrides

---------

Co-authored-by: you <you@example.com>
---
 docs/specs/customizer-rework.md |  568 ++++++++++++
 public/app.js                   |  101 +--
 public/customize-v2.js          | 1503 +++++++++++++++++++++++++++++++
 public/index.html               |    2 +-
 test-customizer-v2.js           |  408 +++++++++
 test-e2e-playwright.js          |  256 +++++-
 test-frontend-helpers.js        |  321 ++-----
 7 files changed, 2803 insertions(+), 356 deletions(-)
 create mode 100644 docs/specs/customizer-rework.md
 create mode 100644 public/customize-v2.js
 create mode 100644 test-customizer-v2.js

diff --git a/docs/specs/customizer-rework.md b/docs/specs/customizer-rework.md
new file mode 100644
index 00000000..02e0ac37
--- /dev/null
+++ b/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.
diff --git a/public/app.js b/public/app.js
index bd54467b..9272955d 100644
--- a/public/app.js
+++ b/public/app.js
@@ -136,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();
@@ -794,92 +787,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 {}; } })();
-    window._SITE_CONFIG_ORIGINAL_HOME = JSON.parse(JSON.stringify(window.SITE_CONFIG.home || {}));
-    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();
   });
diff --git a/public/customize-v2.js b/public/customize-v2.js
new file mode 100644
index 00000000..577f6beb
--- /dev/null
+++ b/public/customize-v2.js
@@ -0,0 +1,1503 @@
+/* === CoreScope — customize-v2.js === */
+/* Event-driven customizer with single-key localStorage, delta-based overrides, and migration from v1.
+   Spec: docs/specs/customizer-rework.md | Issue: #502 */
+'use strict';
+
+(function () {
+  // ── Constants ──
+
+  var STORAGE_KEY = 'cs-theme-overrides';
+  var DARK_MODE_KEY = 'meshcore-theme';
+  var LEGACY_KEYS = [
+    'meshcore-user-theme',
+    'meshcore-timestamp-mode',
+    'meshcore-timestamp-timezone',
+    'meshcore-timestamp-format',
+    'meshcore-timestamp-custom-format',
+    'meshcore-heatmap-opacity',
+    'meshcore-live-heatmap-opacity'
+  ];
+
+  var VALID_SECTIONS = ['branding', 'theme', 'themeDark', 'nodeColors', 'typeColors', 'home', 'timestamps', 'heatmapOpacity', 'liveHeatmapOpacity'];
+  var OBJECT_SECTIONS = ['branding', 'theme', 'themeDark', 'nodeColors', 'typeColors', 'home', 'timestamps'];
+  var SCALAR_SECTIONS = ['heatmapOpacity', 'liveHeatmapOpacity'];
+
+  // CSS variable mapping (theme key → CSS custom property)
+  var THEME_CSS_MAP = {
+    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',
+    sectionBg: '--section-bg',
+    cardBg: '--card-bg', contentBg: '--content-bg', detailBg: '--detail-bg',
+    inputBg: '--input-bg', rowStripe: '--row-stripe', rowHover: '--row-hover', selectedBg: '--selected-bg',
+    font: '--font', mono: '--mono'
+  };
+
+  var THEME_COLOR_KEYS = Object.keys(THEME_CSS_MAP).filter(function (k) { return k !== 'font' && k !== 'mono'; });
+
+  // ── Presets (copied from v1 customize.js) ──
+  var PRESETS = {
+    default: {
+      name: 'Default', desc: 'MeshCore blue',
+      preview: ['#4a9eff', '#0f0f23', '#f4f5f7', '#1a1a2e', '#22c55e'],
+      theme: {
+        accent: '#4a9eff', navBg: '#0f0f23', navText: '#ffffff', background: '#f4f5f7', text: '#1a1a2e',
+        statusGreen: '#22c55e', statusYellow: '#eab308', statusRed: '#ef4444',
+        accentHover: '#6db3ff', navBg2: '#1a1a2e', navTextMuted: '#cbd5e1', textMuted: '#5b6370', border: '#e2e5ea',
+        surface1: '#ffffff', surface2: '#ffffff', cardBg: '#ffffff', contentBg: '#f4f5f7',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#f9fafb', rowHover: '#eef2ff', selectedBg: '#dbeafe',
+        surface3: '#ffffff', sectionBg: '#eef2ff'
+      },
+      themeDark: {
+        accent: '#4a9eff', navBg: '#0f0f23', navText: '#ffffff', background: '#0f0f23', text: '#e2e8f0',
+        statusGreen: '#22c55e', statusYellow: '#eab308', statusRed: '#ef4444',
+        accentHover: '#6db3ff', navBg2: '#1a1a2e', navTextMuted: '#cbd5e1', textMuted: '#a8b8cc', border: '#334155',
+        surface1: '#1a1a2e', surface2: '#232340', cardBg: '#1a1a2e', contentBg: '#0f0f23',
+        detailBg: '#232340', inputBg: '#1e1e34', rowStripe: '#1e1e34', rowHover: '#2d2d50', selectedBg: '#1e3a5f',
+        surface3: '#2d2d50', sectionBg: '#1e1e34'
+      }
+    },
+    ocean: {
+      name: 'Ocean', desc: 'Deep blues & teals',
+      preview: ['#0077b6', '#03045e', '#f0f7fa', '#48cae4', '#15803d'],
+      theme: {
+        accent: '#0077b6', navBg: '#03045e', navText: '#ffffff', background: '#f0f7fa', text: '#0a1628',
+        statusGreen: '#15803d', statusYellow: '#a16207', statusRed: '#dc2626',
+        accentHover: '#0096d6', navBg2: '#023e8a', navTextMuted: '#90caf9', textMuted: '#4a6580', border: '#c8dce8',
+        surface1: '#ffffff', surface2: '#e8f4f8', cardBg: '#ffffff', contentBg: '#f0f7fa',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#f5fafd', rowHover: '#e0f0f8', selectedBg: '#bde0fe',
+        surface3: '#f5fafd', sectionBg: '#e0f0f8'
+      },
+      themeDark: {
+        accent: '#48cae4', navBg: '#03045e', navText: '#ffffff', background: '#0a1929', text: '#e0e7ef',
+        statusGreen: '#4ade80', statusYellow: '#facc15', statusRed: '#f87171',
+        accentHover: '#76d7ea', navBg2: '#012a4a', navTextMuted: '#90caf9', textMuted: '#8eafc4', border: '#1e3a5f',
+        surface1: '#0d2137', surface2: '#122d4a', cardBg: '#0d2137', contentBg: '#0a1929',
+        detailBg: '#122d4a', inputBg: '#0d2137', rowStripe: '#0d2137', rowHover: '#153450', selectedBg: '#1a4570',
+        surface3: '#153450', sectionBg: '#0d2137'
+      }
+    },
+    forest: {
+      name: 'Forest', desc: 'Greens & earth tones',
+      preview: ['#2d6a4f', '#1b3a2d', '#f2f7f4', '#52b788', '#15803d'],
+      theme: {
+        accent: '#2d6a4f', navBg: '#1b3a2d', navText: '#ffffff', background: '#f2f7f4', text: '#1a2e24',
+        statusGreen: '#15803d', statusYellow: '#a16207', statusRed: '#dc2626',
+        accentHover: '#40916c', navBg2: '#2d6a4f', navTextMuted: '#a3c4b5', textMuted: '#557063', border: '#c8dcd2',
+        surface1: '#ffffff', surface2: '#e8f0eb', cardBg: '#ffffff', contentBg: '#f2f7f4',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#f5faf7', rowHover: '#e4f0e8', selectedBg: '#c2e0cc',
+        surface3: '#f5faf7', sectionBg: '#e4f0e8'
+      },
+      themeDark: {
+        accent: '#52b788', navBg: '#1b3a2d', navText: '#ffffff', background: '#0d1f17', text: '#d8e8df',
+        statusGreen: '#4ade80', statusYellow: '#facc15', statusRed: '#f87171',
+        accentHover: '#74c69d', navBg2: '#14532d', navTextMuted: '#86b89a', textMuted: '#8aac9a', border: '#2d4a3a',
+        surface1: '#162e23', surface2: '#1d3a2d', cardBg: '#162e23', contentBg: '#0d1f17',
+        detailBg: '#1d3a2d', inputBg: '#162e23', rowStripe: '#162e23', rowHover: '#1f4030', selectedBg: '#265940',
+        surface3: '#1f4030', sectionBg: '#162e23'
+      }
+    },
+    sunset: {
+      name: 'Sunset', desc: 'Warm oranges & ambers',
+      preview: ['#c2410c', '#431407', '#fef7f2', '#fb923c', '#dc2626'],
+      theme: {
+        accent: '#c2410c', navBg: '#431407', navText: '#ffffff', background: '#fef7f2', text: '#1c0f06',
+        statusGreen: '#15803d', statusYellow: '#a16207', statusRed: '#dc2626',
+        accentHover: '#ea580c', navBg2: '#7c2d12', navTextMuted: '#fdba74', textMuted: '#6b5344', border: '#e8d5c8',
+        surface1: '#ffffff', surface2: '#fef0e6', cardBg: '#ffffff', contentBg: '#fef7f2',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#fefaf7', rowHover: '#fef0e0', selectedBg: '#fed7aa',
+        surface3: '#fefaf7', sectionBg: '#fef0e0'
+      },
+      themeDark: {
+        accent: '#fb923c', navBg: '#431407', navText: '#ffffff', background: '#1a0f08', text: '#f0ddd0',
+        statusGreen: '#4ade80', statusYellow: '#facc15', statusRed: '#f87171',
+        accentHover: '#fdba74', navBg2: '#7c2d12', navTextMuted: '#c2855a', textMuted: '#b09080', border: '#4a2a18',
+        surface1: '#261a10', surface2: '#332214', cardBg: '#261a10', contentBg: '#1a0f08',
+        detailBg: '#332214', inputBg: '#261a10', rowStripe: '#261a10', rowHover: '#3a2818', selectedBg: '#5c3518',
+        surface3: '#3a2818', sectionBg: '#261a10'
+      }
+    },
+    mono: {
+      name: 'Monochrome', desc: 'Pure grays, no color',
+      preview: ['#525252', '#171717', '#f5f5f5', '#a3a3a3', '#737373'],
+      theme: {
+        accent: '#525252', navBg: '#171717', navText: '#ffffff', background: '#f5f5f5', text: '#171717',
+        statusGreen: '#15803d', statusYellow: '#a16207', statusRed: '#dc2626',
+        accentHover: '#737373', navBg2: '#262626', navTextMuted: '#a3a3a3', textMuted: '#525252', border: '#d4d4d4',
+        surface1: '#ffffff', surface2: '#fafafa', cardBg: '#ffffff', contentBg: '#f5f5f5',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#fafafa', rowHover: '#efefef', selectedBg: '#e5e5e5',
+        surface3: '#fafafa', sectionBg: '#efefef'
+      },
+      themeDark: {
+        accent: '#a3a3a3', navBg: '#171717', navText: '#ffffff', background: '#0a0a0a', text: '#e5e5e5',
+        statusGreen: '#4ade80', statusYellow: '#facc15', statusRed: '#f87171',
+        accentHover: '#d4d4d4', navBg2: '#1a1a1a', navTextMuted: '#737373', textMuted: '#a3a3a3', border: '#333333',
+        surface1: '#171717', surface2: '#1f1f1f', cardBg: '#171717', contentBg: '#0a0a0a',
+        detailBg: '#1f1f1f', inputBg: '#171717', rowStripe: '#141414', rowHover: '#222222', selectedBg: '#2a2a2a',
+        surface3: '#222222', sectionBg: '#171717'
+      }
+    },
+    highContrast: {
+      name: 'High Contrast', desc: 'WCAG AAA, max readability',
+      preview: ['#0050a0', '#000000', '#ffffff', '#66b3ff', '#006400'],
+      theme: {
+        accent: '#0050a0', navBg: '#000000', navText: '#ffffff', background: '#ffffff', text: '#000000',
+        statusGreen: '#006400', statusYellow: '#7a5900', statusRed: '#b30000',
+        accentHover: '#0068cc', navBg2: '#1a1a1a', navTextMuted: '#e0e0e0', textMuted: '#333333', border: '#000000',
+        surface1: '#ffffff', surface2: '#f0f0f0', cardBg: '#ffffff', contentBg: '#ffffff',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#f0f0f0', rowHover: '#e0e8f5', selectedBg: '#cce0ff',
+        surface3: '#f0f0f0', sectionBg: '#e0e8f5'
+      },
+      themeDark: {
+        accent: '#66b3ff', navBg: '#000000', navText: '#ffffff', background: '#000000', text: '#ffffff',
+        statusGreen: '#66ff66', statusYellow: '#ffff00', statusRed: '#ff6666',
+        accentHover: '#99ccff', navBg2: '#0a0a0a', navTextMuted: '#cccccc', textMuted: '#cccccc', border: '#ffffff',
+        surface1: '#111111', surface2: '#1a1a1a', cardBg: '#111111', contentBg: '#000000',
+        detailBg: '#1a1a1a', inputBg: '#111111', rowStripe: '#0d0d0d', rowHover: '#1a2a3a', selectedBg: '#003366',
+        surface3: '#1a2a3a', sectionBg: '#111111'
+      },
+      nodeColors: { repeater: '#ff0000', companion: '#0066ff', room: '#009900', sensor: '#cc8800', observer: '#9933ff' },
+      typeColors: {
+        ADVERT: '#009900', GRP_TXT: '#0066ff', TXT_MSG: '#cc8800', ACK: '#666666',
+        REQUEST: '#9933ff', RESPONSE: '#0099cc', TRACE: '#cc0066', PATH: '#009999', ANON_REQ: '#cc3355'
+      }
+    },
+    midnight: {
+      name: 'Midnight', desc: 'Deep purples & indigos',
+      preview: ['#7c3aed', '#1e1045', '#f5f3ff', '#a78bfa', '#15803d'],
+      theme: {
+        accent: '#7c3aed', navBg: '#1e1045', navText: '#ffffff', background: '#f5f3ff', text: '#1a1040',
+        statusGreen: '#15803d', statusYellow: '#a16207', statusRed: '#dc2626',
+        accentHover: '#8b5cf6', navBg2: '#2e1065', navTextMuted: '#c4b5fd', textMuted: '#5b5075', border: '#d8d0e8',
+        surface1: '#ffffff', surface2: '#ede9fe', cardBg: '#ffffff', contentBg: '#f5f3ff',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#faf8ff', rowHover: '#ede9fe', selectedBg: '#ddd6fe',
+        surface3: '#faf8ff', sectionBg: '#ede9fe'
+      },
+      themeDark: {
+        accent: '#a78bfa', navBg: '#1e1045', navText: '#ffffff', background: '#0f0a24', text: '#e2ddf0',
+        statusGreen: '#4ade80', statusYellow: '#facc15', statusRed: '#f87171',
+        accentHover: '#c4b5fd', navBg2: '#2e1065', navTextMuted: '#9d8abf', textMuted: '#9a90b0', border: '#352a55',
+        surface1: '#1a1338', surface2: '#221a48', cardBg: '#1a1338', contentBg: '#0f0a24',
+        detailBg: '#221a48', inputBg: '#1a1338', rowStripe: '#1a1338', rowHover: '#2a2050', selectedBg: '#352a6a',
+        surface3: '#2a2050', sectionBg: '#1a1338'
+      }
+    },
+    ember: {
+      name: 'Ember', desc: 'Warm red/orange, cyberpunk',
+      preview: ['#dc2626', '#1a0a0a', '#faf5f5', '#ef4444', '#15803d'],
+      theme: {
+        accent: '#dc2626', navBg: '#1a0a0a', navText: '#ffffff', background: '#faf5f5', text: '#1a0a0a',
+        statusGreen: '#15803d', statusYellow: '#a16207', statusRed: '#dc2626',
+        accentHover: '#ef4444', navBg2: '#2a1010', navTextMuted: '#f0a0a0', textMuted: '#6b4444', border: '#e0c8c8',
+        surface1: '#ffffff', surface2: '#faf0f0', cardBg: '#ffffff', contentBg: '#faf5f5',
+        detailBg: '#ffffff', inputBg: '#ffffff', rowStripe: '#fdf8f8', rowHover: '#fce8e8', selectedBg: '#fecaca',
+        surface3: '#fdf8f8', sectionBg: '#fce8e8'
+      },
+      themeDark: {
+        accent: '#ef4444', navBg: '#1a0505', navText: '#ffffff', background: '#0d0505', text: '#f0dada',
+        statusGreen: '#4ade80', statusYellow: '#facc15', statusRed: '#f87171',
+        accentHover: '#f87171', navBg2: '#2a0a0a', navTextMuted: '#c07070', textMuted: '#b09090', border: '#4a2020',
+        surface1: '#1a0d0d', surface2: '#261414', cardBg: '#1a0d0d', contentBg: '#0d0505',
+        detailBg: '#261414', inputBg: '#1a0d0d', rowStripe: '#1a0d0d', rowHover: '#301818', selectedBg: '#4a1a1a',
+        surface3: '#301818', sectionBg: '#1a0d0d'
+      }
+    }
+  };
+
+  // ── Labels, hints, emojis (carried from v1) ──
+
+  var THEME_LABELS = {
+    accent: 'Brand Color', accentHover: 'Accent Hover',
+    navBg: 'Navigation', navBg2: 'Nav Gradient End', navText: 'Nav Text', navTextMuted: 'Nav Muted Text',
+    background: 'Background', text: 'Text', textMuted: 'Muted Text', border: 'Borders',
+    statusGreen: 'Healthy', statusYellow: 'Warning', statusRed: 'Error',
+    surface1: 'Cards', surface2: 'Panels', surface3: 'Tertiary Surface', sectionBg: 'Section Header', cardBg: 'Card Fill', contentBg: 'Content Area',
+    detailBg: 'Detail Panels', inputBg: 'Inputs', rowStripe: 'Table Stripe',
+    rowHover: 'Row Hover', selectedBg: 'Selected',
+    font: 'Body Font', mono: 'Mono Font'
+  };
+
+  var THEME_HINTS = {
+    accent: 'Buttons, links, active tabs, badges, charts — your primary brand color',
+    navBg: 'Top navigation bar', navText: 'Nav bar text, links, brand name, buttons',
+    background: 'Main page background', text: 'Primary text — muted text auto-derives',
+    statusGreen: 'Healthy/online indicators', statusYellow: 'Warning/degraded + hop conflicts',
+    statusRed: 'Error/offline indicators', accentHover: 'Hover state for accent elements',
+    navBg2: 'Darker end of nav gradient', navTextMuted: 'Inactive nav links, nav buttons',
+    textMuted: 'Labels, timestamps, secondary text', border: 'Dividers, table borders, card borders',
+    surface1: 'Card and panel backgrounds', surface2: 'Nested surfaces, secondary panels',
+    surface3: 'Tertiary surfaces, hover accents', sectionBg: 'Section header backgrounds',
+    cardBg: 'Detail panels, modals', contentBg: 'Content area behind cards',
+    detailBg: 'Modal, packet detail, side panels', inputBg: 'Text inputs, dropdowns',
+    rowStripe: 'Alternating table rows', rowHover: 'Table row hover', selectedBg: 'Selected/active rows',
+    font: 'System font stack for body text', mono: 'Monospace font for hex, code, hashes'
+  };
+
+  var NODE_LABELS = { repeater: 'Repeater', companion: 'Companion', room: 'Room Server', sensor: 'Sensor', observer: 'Observer' };
+  var NODE_HINTS = {
+    repeater: 'Infrastructure nodes that relay packets', companion: 'End-user devices',
+    room: 'Room/chat server nodes', sensor: 'Sensor/telemetry nodes', observer: 'MQTT observer stations'
+  };
+  var NODE_EMOJI = { repeater: '◆', companion: '●', room: '■', sensor: '▲', observer: '★' };
+
+  var TYPE_LABELS = {
+    ADVERT: 'Advertisement', GRP_TXT: 'Channel Message', TXT_MSG: 'Direct Message', ACK: 'Acknowledgment',
+    REQUEST: 'Request', RESPONSE: 'Response', TRACE: 'Traceroute', PATH: 'Path', ANON_REQ: 'Anonymous Request'
+  };
+  var TYPE_HINTS = {
+    ADVERT: 'Node advertisements', GRP_TXT: 'Group/channel messages', TXT_MSG: 'Direct messages',
+    ACK: 'Acknowledgments', REQUEST: 'Requests', RESPONSE: 'Responses',
+    TRACE: 'Traceroute', PATH: 'Path packets', ANON_REQ: 'Encrypted anonymous requests'
+  };
+  var TYPE_EMOJI = {
+    ADVERT: '📡', GRP_TXT: '💬', TXT_MSG: '✉️', ACK: '✓', REQUEST: '❓',
+    RESPONSE: '📨', TRACE: '🔍', PATH: '🛤️', ANON_REQ: '🕵️'
+  };
+
+  var BASIC_KEYS = ['accent', 'navBg', 'navText', 'background', 'text', 'statusGreen', 'statusYellow', 'statusRed'];
+  var ADVANCED_KEYS = ['accentHover', 'navBg2', 'navTextMuted', 'textMuted', 'border', 'surface1', 'surface2', 'cardBg', 'contentBg', 'detailBg', 'inputBg', 'rowStripe', 'rowHover', 'selectedBg'];
+  var FONT_KEYS = ['font', 'mono'];
+
+  // ── Validation helpers ──
+
+  var COLOR_RE = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+  var CSS_FUNC_RE = /^(?:rgb|rgba|hsl|hsla)\s*\(.*\)$/i;
+  // Basic list of CSS named colors (subset — covers common ones)
+  var NAMED_COLORS = 'aliceblue,antiquewhite,aqua,aquamarine,azure,beige,bisque,black,blanchedalmond,blue,blueviolet,brown,burlywood,cadetblue,chartreuse,chocolate,coral,cornflowerblue,cornsilk,crimson,cyan,darkblue,darkcyan,darkgoldenrod,darkgray,darkgreen,darkgrey,darkkhaki,darkmagenta,darkolivegreen,darkorange,darkorchid,darkred,darksalmon,darkseagreen,darkslateblue,darkslategray,darkslategrey,darkturquoise,darkviolet,deeppink,deepskyblue,dimgray,dimgrey,dodgerblue,firebrick,floralwhite,forestgreen,fuchsia,gainsboro,ghostwhite,gold,goldenrod,gray,green,greenyellow,grey,honeydew,hotpink,indianred,indigo,ivory,khaki,lavender,lavenderblush,lawngreen,lemonchiffon,lightblue,lightcoral,lightcyan,lightgoldenrodyellow,lightgray,lightgreen,lightgrey,lightpink,lightsalmon,lightseagreen,lightskyblue,lightslategray,lightslategrey,lightsteelblue,lightyellow,lime,limegreen,linen,magenta,maroon,mediumaquamarine,mediumblue,mediumorchid,mediumpurple,mediumseagreen,mediumslateblue,mediumspringgreen,mediumturquoise,mediumvioletred,midnightblue,mintcream,mistyrose,moccasin,navajowhite,navy,oldlace,olive,olivedrab,orange,orangered,orchid,palegoldenrod,palegreen,paleturquoise,palevioletred,papayawhip,peachpuff,peru,pink,plum,powderblue,purple,rebeccapurple,red,rosybrown,royalblue,saddlebrown,salmon,sandybrown,seagreen,seashell,sienna,silver,skyblue,slateblue,slategray,slategrey,snow,springgreen,steelblue,tan,teal,thistle,tomato,turquoise,violet,wheat,white,whitesmoke,yellow,yellowgreen,transparent,currentcolor,inherit'.split(',');
+  var NAMED_SET = null;
+
+  function isValidColor(val) {
+    if (typeof val !== 'string') return false;
+    if (COLOR_RE.test(val)) return true;
+    if (CSS_FUNC_RE.test(val)) return true;
+    if (!NAMED_SET) { NAMED_SET = new Set(NAMED_COLORS); }
+    return NAMED_SET.has(val.toLowerCase().trim());
+  }
+
+  function isValidOpacity(val) {
+    return typeof val === 'number' && isFinite(val) && val >= 0 && val <= 1;
+  }
+
+  var TS_ENUMS = {
+    defaultMode: ['ago', 'absolute'],
+    timezone: ['local', 'utc'],
+    formatPreset: ['iso', 'iso-seconds', 'locale']
+  };
+
+  // ── Core data functions (exported for testing via window._customizerV2) ──
+
+  /** @type {object|null} server defaults, set during init */
+  var _serverDefaults = null;
+  var _saveStatus = 'saved'; // 'saved' | 'saving' | 'error'
+  var _writeTimer = null;
+
+  function readOverrides() {
+    try {
+      var raw = localStorage.getItem(STORAGE_KEY);
+      if (raw == null) return {};
+      var parsed = JSON.parse(raw);
+      if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+      return parsed;
+    } catch (e) {
+      return {};
+    }
+  }
+
+  function _validateDelta(delta) {
+    // Validate color values in theme/themeDark/nodeColors/typeColors, numeric values, timestamp enums.
+    // Returns a cleaned copy (invalid values removed with console.warn).
+    var clean = {};
+    var colorSections = ['theme', 'themeDark', 'nodeColors', 'typeColors'];
+    for (var key in delta) {
+      if (!delta.hasOwnProperty(key)) continue;
+      if (colorSections.indexOf(key) !== -1 && typeof delta[key] === 'object' && delta[key] !== null) {
+        var section = {};
+        var src = delta[key];
+        for (var sk in src) {
+          if (!src.hasOwnProperty(sk)) continue;
+          // font/mono are not colors
+          if ((key === 'theme' || key === 'themeDark') && (sk === 'font' || sk === 'mono')) {
+            if (typeof src[sk] === 'string') section[sk] = src[sk];
+            continue;
+          }
+          if (typeof src[sk] === 'string' && isValidColor(src[sk])) {
+            section[sk] = src[sk];
+          } else {
+            console.warn('[customizer-v2] Invalid color value rejected:', key + '.' + sk, src[sk]);
+          }
+        }
+        if (Object.keys(section).length) clean[key] = section;
+      } else if (key === 'heatmapOpacity' || key === 'liveHeatmapOpacity') {
+        var numVal = typeof delta[key] === 'string' ? parseFloat(delta[key]) : delta[key];
+        if (isValidOpacity(numVal)) {
+          clean[key] = numVal;
+        } else {
+          console.warn('[customizer-v2] Invalid opacity value rejected:', key, delta[key]);
+        }
+      } else if (key === 'timestamps' && typeof delta[key] === 'object' && delta[key] !== null) {
+        var ts = {};
+        var tsrc = delta[key];
+        for (var tk in tsrc) {
+          if (!tsrc.hasOwnProperty(tk)) continue;
+          if (TS_ENUMS[tk]) {
+            if (TS_ENUMS[tk].indexOf(tsrc[tk]) !== -1) {
+              ts[tk] = tsrc[tk];
+            } else {
+              console.warn('[customizer-v2] Invalid timestamp enum rejected:', tk, tsrc[tk]);
+            }
+          } else if (tk === 'customFormat') {
+            if (typeof tsrc[tk] === 'string') ts[tk] = tsrc[tk];
+          } else {
+            ts[tk] = tsrc[tk]; // unknown timestamp keys pass through
+          }
+        }
+        if (Object.keys(ts).length) clean[key] = ts;
+      } else if (key === 'branding' || key === 'home') {
+        // Pass through as-is (object shape)
+        if (typeof delta[key] === 'object' && delta[key] !== null) {
+          clean[key] = JSON.parse(JSON.stringify(delta[key]));
+        }
+      } else {
+        // Unknown key — pass through for forward compatibility
+        clean[key] = delta[key];
+      }
+    }
+    return clean;
+  }
+
+  function writeOverrides(delta) {
+    if (delta == null || typeof delta !== 'object') return;
+    // If empty, remove key entirely
+    var keys = Object.keys(delta);
+    if (keys.length === 0) {
+      try { localStorage.removeItem(STORAGE_KEY); } catch (e) { /* ignore */ }
+      _updateSaveStatus('saved');
+      return;
+    }
+    var validated = _validateDelta(delta);
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(validated));
+      _updateSaveStatus('saved');
+    } catch (e) {
+      _updateSaveStatus('error');
+      console.error('[customizer-v2] localStorage quota exceeded:', e);
+      // Show visible warning
+      _showQuotaWarning();
+    }
+  }
+
+  function computeEffective(serverConfig, userOverrides) {
+    var effective = JSON.parse(JSON.stringify(serverConfig || {}));
+    if (!userOverrides || typeof userOverrides !== 'object') return effective;
+    for (var key in userOverrides) {
+      if (!userOverrides.hasOwnProperty(key)) continue;
+      var uv = userOverrides[key];
+      if (uv != null && typeof uv === 'object' && !Array.isArray(uv)) {
+        // Object section — shallow merge
+        if (!effective[key] || typeof effective[key] !== 'object') effective[key] = {};
+        var val = userOverrides[key];
+        for (var sk in val) {
+          if (val.hasOwnProperty(sk)) {
+            if (Array.isArray(val[sk])) {
+              effective[key][sk] = JSON.parse(JSON.stringify(val[sk])); // array: full replace
+            } else {
+              effective[key][sk] = val[sk];
+            }
+          }
+        }
+      } else if (Array.isArray(uv)) {
+        // Array — full replacement
+        effective[key] = JSON.parse(JSON.stringify(uv));
+      } else {
+        // Scalar — direct replacement
+        effective[key] = uv;
+      }
+    }
+    return effective;
+  }
+
+  function isDarkMode() {
+    var attr = document.documentElement.getAttribute('data-theme');
+    if (attr === 'dark') return true;
+    if (attr === 'light') return false;
+    return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+  }
+
+  function applyCSS(effectiveConfig) {
+    var dark = isDarkMode();
+    var themeSection = dark
+      ? Object.assign({}, effectiveConfig.theme || {}, effectiveConfig.themeDark || {})
+      : (effectiveConfig.theme || {});
+
+    var root = document.documentElement.style;
+
+    // Apply theme color/font CSS variables
+    for (var key in THEME_CSS_MAP) {
+      if (themeSection[key]) {
+        root.setProperty(THEME_CSS_MAP[key], themeSection[key]);
+      }
+    }
+
+    // Derived vars
+    if (themeSection.background) root.setProperty('--content-bg', themeSection.contentBg || themeSection.background);
+    if (themeSection.surface1) root.setProperty('--card-bg', themeSection.cardBg || themeSection.surface1);
+
+    // Node colors → CSS vars + global objects
+    var nc = effectiveConfig.nodeColors;
+    if (nc) {
+      for (var role in nc) {
+        root.setProperty('--node-' + role, nc[role]);
+        if (window.ROLE_COLORS && role in window.ROLE_COLORS) window.ROLE_COLORS[role] = nc[role];
+        if (window.ROLE_STYLE && window.ROLE_STYLE[role]) window.ROLE_STYLE[role].color = nc[role];
+      }
+    }
+
+    // Type colors → CSS vars + global objects
+    var tc = effectiveConfig.typeColors;
+    if (tc) {
+      for (var type in tc) {
+        root.setProperty('--type-' + type.toLowerCase(), tc[type]);
+        if (window.TYPE_COLORS && type in window.TYPE_COLORS) window.TYPE_COLORS[type] = tc[type];
+      }
+      if (window.syncBadgeColors) window.syncBadgeColors();
+    }
+
+    // Timestamps → sync to SITE_CONFIG
+    if (effectiveConfig.timestamps) {
+      if (!window.SITE_CONFIG) window.SITE_CONFIG = {};
+      if (!window.SITE_CONFIG.timestamps) window.SITE_CONFIG.timestamps = {};
+      var ts = effectiveConfig.timestamps;
+      if (ts.defaultMode) window.SITE_CONFIG.timestamps.defaultMode = ts.defaultMode;
+      if (ts.timezone) window.SITE_CONFIG.timestamps.timezone = ts.timezone;
+      if (ts.formatPreset) window.SITE_CONFIG.timestamps.formatPreset = ts.formatPreset;
+      if (ts.customFormat != null) window.SITE_CONFIG.timestamps.customFormat = ts.customFormat;
+    }
+
+    // Heatmap opacity → sync to localStorage for map pages
+    if (typeof effectiveConfig.heatmapOpacity === 'number') {
+      localStorage.setItem('meshcore-heatmap-opacity', effectiveConfig.heatmapOpacity);
+    }
+    if (typeof effectiveConfig.liveHeatmapOpacity === 'number') {
+      localStorage.setItem('meshcore-live-heatmap-opacity', effectiveConfig.liveHeatmapOpacity);
+    }
+
+    // Nav gradient
+    if (themeSection.navBg) {
+      var nav = document.querySelector('.top-nav');
+      if (nav) {
+        nav.style.background = 'linear-gradient(135deg, ' + themeSection.navBg + ' 0%, ' + (themeSection.navBg2 || themeSection.navBg) + ' 50%, ' + themeSection.navBg + ' 100%)';
+      }
+    }
+
+    // Branding
+    var br = effectiveConfig.branding;
+    if (br) {
+      if (br.siteName) {
+        document.title = br.siteName;
+        var brandEl = document.querySelector('.brand-text');
+        if (brandEl) brandEl.textContent = br.siteName;
+      }
+      if (br.logoUrl) {
+        var iconEl = document.querySelector('.brand-icon');
+        if (iconEl) iconEl.innerHTML = '<img src="' + br.logoUrl + '" style="height:24px" onerror="this.style.display=\'none\'">';
+      }
+      if (br.faviconUrl) {
+        var fav = document.querySelector('link[rel="icon"]');
+        if (fav) fav.href = br.faviconUrl;
+      }
+    }
+
+    // Dispatch theme-changed event (bare, no payload — matches existing behavior)
+    window.dispatchEvent(new CustomEvent('theme-changed'));
+  }
+
+  /** Run the full pipeline: read → merge → atomic assign → applyCSS */
+  function _runPipeline() {
+    var overrides = readOverrides();
+    var effective = computeEffective(_serverDefaults || {}, overrides);
+    window.SITE_CONFIG = effective;
+    applyCSS(effective);
+  }
+
+  // ── setOverride / clearOverride ──
+  // Uses _pendingOverrides accumulator to prevent data loss when rapid calls
+  // occur within the debounce window (each call would otherwise read stale
+  // overrides from localStorage before the previous write landed).
+
+  var _debounceTimer = null;
+  var _pendingOverrides = {};
+
+  function setOverride(section, key, value) {
+    if (section) {
+      if (!_pendingOverrides[section]) _pendingOverrides[section] = {};
+      _pendingOverrides[section][key] = value;
+    } else {
+      _pendingOverrides[key] = value;
+    }
+    _debouncedWrite();
+  }
+
+  function clearOverride(section, key) {
+    var delta = readOverrides();
+    if (section) {
+      if (delta[section]) {
+        delete delta[section][key];
+        if (Object.keys(delta[section]).length === 0) delete delta[section];
+      }
+    } else {
+      delete delta[key];
+    }
+    // Also clear from pending
+    if (section && _pendingOverrides[section]) {
+      delete _pendingOverrides[section][key];
+      if (Object.keys(_pendingOverrides[section]).length === 0) delete _pendingOverrides[section];
+    } else if (!section) {
+      delete _pendingOverrides[key];
+    }
+    // No debounce on reset — instant feedback
+    writeOverrides(delta);
+    _runPipeline();
+    _refreshPanel();
+  }
+
+  function _debouncedWrite() {
+    _updateSaveStatus('saving');
+    if (_debounceTimer) clearTimeout(_debounceTimer);
+    _debounceTimer = setTimeout(function () {
+      _debounceTimer = null;
+      var delta = readOverrides();
+      for (var sec in _pendingOverrides) {
+        if (typeof _pendingOverrides[sec] === 'object' && _pendingOverrides[sec] !== null) {
+          if (!delta[sec]) delta[sec] = {};
+          for (var k in _pendingOverrides[sec]) {
+            delta[sec][k] = _pendingOverrides[sec][k];
+          }
+        } else {
+          delta[sec] = _pendingOverrides[sec];
+        }
+      }
+      _pendingOverrides = {};
+      writeOverrides(delta);
+      _runPipeline();
+      _refreshPanel();
+    }, 300);
+  }
+
+  // ── Migration ──
+
+  function migrateOldKeys() {
+    // Skip if new key already exists
+    if (localStorage.getItem(STORAGE_KEY) != null) return null;
+
+    var hasLegacy = false;
+    for (var i = 0; i < LEGACY_KEYS.length; i++) {
+      if (localStorage.getItem(LEGACY_KEYS[i]) != null) { hasLegacy = true; break; }
+    }
+    if (!hasLegacy) return null;
+
+    var delta = {};
+
+    // meshcore-user-theme (JSON object with branding, theme, themeDark, nodeColors, typeColors, home)
+    try {
+      var raw = localStorage.getItem('meshcore-user-theme');
+      if (raw) {
+        var parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+          var allowedKeys = ['branding', 'theme', 'themeDark', 'nodeColors', 'typeColors', 'home'];
+          for (var k = 0; k < allowedKeys.length; k++) {
+            if (parsed[allowedKeys[k]] && typeof parsed[allowedKeys[k]] === 'object') {
+              delta[allowedKeys[k]] = JSON.parse(JSON.stringify(parsed[allowedKeys[k]]));
+            }
+          }
+        }
+      }
+    } catch (e) {
+      console.warn('[customizer-v2] Migration: invalid meshcore-user-theme JSON, skipping');
+    }
+
+    // Timestamp keys → delta.timestamps
+    var tsMode = localStorage.getItem('meshcore-timestamp-mode');
+    var tsTz = localStorage.getItem('meshcore-timestamp-timezone');
+    var tsFmt = localStorage.getItem('meshcore-timestamp-format');
+    var tsCustom = localStorage.getItem('meshcore-timestamp-custom-format');
+    if (tsMode || tsTz || tsFmt || tsCustom) {
+      delta.timestamps = {};
+      if (tsMode && (tsMode === 'ago' || tsMode === 'absolute')) delta.timestamps.defaultMode = tsMode;
+      if (tsTz && (tsTz === 'local' || tsTz === 'utc')) delta.timestamps.timezone = tsTz;
+      if (tsFmt && (tsFmt === 'iso' || tsFmt === 'iso-seconds' || tsFmt === 'locale')) delta.timestamps.formatPreset = tsFmt;
+      if (tsCustom != null && tsCustom !== '') delta.timestamps.customFormat = tsCustom;
+      if (Object.keys(delta.timestamps).length === 0) delete delta.timestamps;
+    }
+
+    // Heatmap opacities
+    var heatRaw = localStorage.getItem('meshcore-heatmap-opacity');
+    if (heatRaw != null && heatRaw !== '') {
+      var heatVal = parseFloat(heatRaw);
+      if (isFinite(heatVal)) delta.heatmapOpacity = Math.max(0, Math.min(1, heatVal));
+    }
+    var liveHeatRaw = localStorage.getItem('meshcore-live-heatmap-opacity');
+    if (liveHeatRaw != null && liveHeatRaw !== '') {
+      var liveHeatVal = parseFloat(liveHeatRaw);
+      if (isFinite(liveHeatVal)) delta.liveHeatmapOpacity = Math.max(0, Math.min(1, liveHeatVal));
+    }
+
+    // Write the migrated delta
+    writeOverrides(delta);
+
+    // Remove all legacy keys
+    for (var j = 0; j < LEGACY_KEYS.length; j++) {
+      localStorage.removeItem(LEGACY_KEYS[j]);
+    }
+
+    console.log('[customizer-v2] Migrated', Object.keys(delta).length, 'sections from legacy localStorage keys');
+    return delta;
+  }
+
+  // ── Validate shape (for import) ──
+
+  function validateShape(obj) {
+    var errors = [];
+    if (obj == null || typeof obj !== 'object' || Array.isArray(obj)) {
+      return { valid: false, errors: ['Input must be a plain object'] };
+    }
+
+    var colorSections = ['theme', 'themeDark', 'nodeColors', 'typeColors'];
+    for (var key in obj) {
+      if (!obj.hasOwnProperty(key)) continue;
+      if (VALID_SECTIONS.indexOf(key) === -1) {
+        console.warn('[customizer-v2] Unknown top-level key in import:', key);
+        continue; // warning, not error
+      }
+      // Check section types
+      if (OBJECT_SECTIONS.indexOf(key) !== -1) {
+        if (typeof obj[key] !== 'object' || obj[key] === null || Array.isArray(obj[key])) {
+          errors.push('Section "' + key + '" must be an object');
+          continue;
+        }
+      }
+      if (SCALAR_SECTIONS.indexOf(key) !== -1) {
+        var num = typeof obj[key] === 'string' ? parseFloat(obj[key]) : obj[key];
+        if (!isValidOpacity(num)) {
+          errors.push('"' + key + '" must be a number between 0 and 1');
+        }
+        continue;
+      }
+      // Validate colors in color sections
+      if (colorSections.indexOf(key) !== -1 && typeof obj[key] === 'object') {
+        for (var ck in obj[key]) {
+          if (!obj[key].hasOwnProperty(ck)) continue;
+          if ((key === 'theme' || key === 'themeDark') && (ck === 'font' || ck === 'mono')) continue;
+          if (typeof obj[key][ck] === 'string' && !isValidColor(obj[key][ck])) {
+            errors.push('Invalid color: ' + key + '.' + ck + ' = "' + obj[key][ck] + '"');
+          }
+        }
+      }
+      // Validate timestamps
+      if (key === 'timestamps' && typeof obj[key] === 'object') {
+        for (var tk in obj[key]) {
+          if (TS_ENUMS[tk] && TS_ENUMS[tk].indexOf(obj[key][tk]) === -1) {
+            errors.push('Invalid timestamp enum: ' + tk + ' = "' + obj[key][tk] + '"');
+          }
+        }
+      }
+    }
+    return { valid: errors.length === 0, errors: errors };
+  }
+
+  // ── Save status indicator ──
+
+  function _updateSaveStatus(status) {
+    _saveStatus = status;
+    var el = document.getElementById('cv2-save-status');
+    if (!el) return;
+    if (status === 'saved') { el.textContent = 'All changes saved'; el.style.color = 'var(--text-muted)'; }
+    else if (status === 'saving') { el.textContent = 'Saving...'; el.style.color = 'var(--text-muted)'; }
+    else if (status === 'error') { el.textContent = '⚠️ Storage full — changes may not be saved'; el.style.color = '#ef4444'; }
+  }
+
+  function _showQuotaWarning() {
+    // Surface a visible warning in the panel
+    _updateSaveStatus('error');
+  }
+
+  // ── Customizer panel UI ──
+
+  var _panelEl = null;
+  var _activeTab = 'branding';
+  var _styleEl = null;
+
+  function esc(s) { var d = document.createElement('div'); d.textContent = s || ''; return d.innerHTML; }
+  function escAttr(s) { return (s || '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;'); }
+
+  function _getEffective() { return window.SITE_CONFIG || computeEffective(_serverDefaults || {}, readOverrides()); }
+  function _getOverrides() { return readOverrides(); }
+  function _getServer() { return _serverDefaults || {}; }
+
+  /** Check if a specific field is overridden (differs from server default) */
+  function _isOverridden(section, key) {
+    var overrides = _getOverrides();
+    var server = _getServer();
+    if (section) {
+      if (!overrides[section] || !overrides[section].hasOwnProperty(key)) return false;
+      var serverSection = server[section] || {};
+      return overrides[section][key] !== serverSection[key];
+    }
+    if (!overrides.hasOwnProperty(key)) return false;
+    return overrides[key] !== server[key];
+  }
+
+  /** Count overridden fields in a section */
+  function _countOverrides(section) {
+    var overrides = _getOverrides();
+    if (!overrides[section] || typeof overrides[section] !== 'object') return 0;
+    return Object.keys(overrides[section]).length;
+  }
+
+  function _overrideDot(section, key) {
+    if (!_isOverridden(section, key)) return '';
+    return '<span class="cv2-override-dot" data-reset-s="' + (section || '') + '" data-reset-k="' + key + '" title="Reset to server default">●</span>';
+  }
+
+  function _injectStyles() {
+    if (_styleEl) return;
+    _styleEl = document.createElement('style');
+    _styleEl.textContent = [
+      '.cust-overlay{position:fixed;top:56px;right:12px;z-index:1050;width:480px;height:calc(100vh - 68px);background:var(--card-bg);border:1px solid var(--border);border-radius:10px;box-shadow:0 8px 32px rgba(0,0,0,.3);display:flex;flex-direction:column;resize:both;min-width:320px;min-height:300px;overflow:hidden}',
+      '.cust-overlay.hidden{display:none}',
+      '.cust-header{display:flex;align-items:center;justify-content:space-between;padding:12px 16px;border-bottom:1px solid var(--border);cursor:move;user-select:none;flex-shrink:0}',
+      '.cust-header h2{margin:0;font-size:15px}',
+      '.cv2-local-banner{font-size:10px;color:var(--text-muted);padding:4px 16px;background:var(--surface-1);border-bottom:1px solid var(--border);text-align:center;flex-shrink:0}',
+      '.cust-close{background:none;border:none;font-size:18px;cursor:pointer;color:var(--text-muted);padding:4px 8px;border-radius:4px}',
+      '.cust-close:hover{background:var(--surface-3);color:var(--text)}',
+      '.cust-inner{flex:1;display:flex;flex-direction:column;overflow:hidden;min-height:0}',
+      '.cust-body{flex:1;overflow-y:auto;min-height:0}',
+      '.cust-tabs{display:flex;gap:0;border-bottom:1px solid var(--border);flex-shrink:0}',
+      '.cust-tab{padding:8px 10px;cursor:pointer;border:none;background:none;color:var(--text-muted);font-size:12px;font-weight:500;border-bottom:2px solid transparent;margin-bottom:-1px;white-space:nowrap;flex:1;text-align:center}',
+      '.cust-tab-text{font-size:10px;display:block}',
+      '.cust-tab:hover{color:var(--text)}',
+      '.cust-tab.active{color:var(--accent);border-bottom-color:var(--accent)}',
+      '.cust-tab .cv2-tab-badge{font-size:9px;background:var(--accent);color:#fff;border-radius:8px;padding:0 4px;margin-left:2px}',
+      '.cust-panel{display:none;padding:12px 16px}',
+      '.cust-panel.active{display:block}',
+      '.cust-field{margin-bottom:12px}',
+      '.cust-field label{display:block;font-size:12px;font-weight:600;margin-bottom:3px;color:var(--text)}',
+      '.cust-field input[type="text"],.cust-field textarea{width:100%;padding:6px 8px;border:1px solid var(--border);border-radius:6px;font-size:13px;background:var(--input-bg);color:var(--text);box-sizing:border-box}',
+      '.cust-field input[type="text"]:focus,.cust-field textarea:focus{outline:none;border-color:var(--accent)}',
+      '.cust-color-row{display:flex;align-items:center;gap:8px;margin-bottom:10px}',
+      '.cust-color-row>div:first-child{min-width:160px;flex:1}',
+      '.cust-color-row label{font-size:12px;font-weight:600;margin:0;display:block}',
+      '.cust-hint{font-size:10px;color:var(--text-muted);margin-top:1px;line-height:1.2}',
+      '.cust-color-row input[type="color"]{width:40px;height:32px;border:1px solid var(--border);border-radius:6px;cursor:pointer;padding:2px;background:var(--input-bg)}',
+      '.cust-color-row .cust-hex{font-family:var(--mono);font-size:12px;color:var(--text-muted);min-width:70px}',
+      '.cv2-override-dot{color:var(--accent);cursor:pointer;font-size:10px;margin-left:4px;vertical-align:middle;title:"Reset to server default"}',
+      '.cv2-override-dot:hover{color:var(--status-red)}',
+      '.cust-node-dot{display:inline-block;width:16px;height:16px;border-radius:50%;vertical-align:middle}',
+      '.cust-preview-img{max-width:200px;max-height:60px;margin-top:6px;border-radius:6px;border:1px solid var(--border)}',
+      '.cust-list-item{display:flex;flex-direction:column;gap:4px;margin-bottom:8px;padding:8px;background:var(--surface-1);border:1px solid var(--border);border-radius:6px}',
+      '.cust-list-row{display:flex;gap:6px;align-items:center}',
+      '.cust-list-item input{flex:1;padding:5px 8px;border:1px solid var(--border);border-radius:4px;font-size:12px;background:var(--input-bg);color:var(--text);min-width:0}',
+      '.cust-list-item textarea{width:100%;padding:5px 8px;border:1px solid var(--border);border-radius:4px;font-size:11px;font-family:var(--mono);background:var(--input-bg);color:var(--text);resize:vertical;box-sizing:border-box}',
+      '.cust-list-item textarea:focus,.cust-list-item input:focus{outline:none;border-color:var(--accent)}',
+      '.cust-md-hint{font-size:9px;color:var(--text-muted);margin-top:2px}',
+      '.cust-md-hint code{background:var(--surface-2);padding:0 3px;border-radius:2px;font-size:9px}',
+      '.cust-list-item .cust-emoji-input{max-width:40px;text-align:center;flex:0 0 40px}',
+      '.cust-list-btn{padding:4px 10px;border:1px solid var(--border);border-radius:4px;background:var(--surface-2);color:var(--text-muted);cursor:pointer;font-size:12px}',
+      '.cust-list-btn:hover{background:var(--surface-3)}',
+      '.cust-list-btn.danger{color:#ef4444}',
+      '.cust-list-btn.danger:hover{background:#fef2f2}',
+      '.cust-add-btn{display:inline-flex;align-items:center;gap:4px;padding:6px 14px;border:1px dashed var(--border);border-radius:6px;background:none;color:var(--accent);cursor:pointer;font-size:13px;margin-top:4px}',
+      '.cust-add-btn:hover{background:var(--hover-bg)}',
+      '.cust-export-btns{display:flex;gap:8px;margin-top:8px;flex-wrap:wrap}',
+      '.cust-export-btns button{padding:6px 14px;border:none;border-radius:6px;cursor:pointer;font-size:12px;font-weight:500}',
+      '.cust-copy-btn{background:var(--accent);color:#fff}',
+      '.cust-copy-btn:hover{opacity:.9}',
+      '.cust-dl-btn{background:var(--surface-2);color:var(--text);border:1px solid var(--border)!important}',
+      '.cust-dl-btn:hover{background:var(--surface-3)}',
+      '.cust-reset-all{background:var(--surface-2);color:#ef4444;border:1px solid #ef4444!important}',
+      '.cust-reset-all:hover{background:#ef4444;color:#fff}',
+      '.cust-section-title{font-size:16px;font-weight:600;margin:0 0 12px}',
+      '.cust-preset-btn{display:flex;flex-direction:column;align-items:center;gap:4px;padding:8px 10px;border:2px solid var(--border);border-radius:8px;background:var(--surface-1);cursor:pointer;min-width:72px;color:var(--text)}',
+      '.cust-preset-btn.active{border-color:var(--accent);background:var(--selected-bg)}',
+      '.cv2-footer{padding:6px 16px;border-top:1px solid var(--border);font-size:11px;color:var(--text-muted);flex-shrink:0;display:flex;justify-content:space-between;align-items:center}',
+      '@media(max-width:600px){.cust-overlay{left:8px;right:8px;width:auto;top:56px}.cust-tabs{gap:0}.cust-tab{padding:6px 8px;font-size:11px}.cust-color-row>div:first-child{min-width:120px}}'
+    ].join('\n');
+    document.head.appendChild(_styleEl);
+  }
+
+  function _tabBadge(section) {
+    var n = _countOverrides(section);
+    return n ? ' <span class="cv2-tab-badge">' + n + '</span>' : '';
+  }
+
+  function _renderTabs() {
+    var tabs = [
+      { id: 'branding', label: '🏷️', title: 'Branding', badge: _tabBadge('branding') },
+      { id: 'theme', label: '🎨', title: 'Theme', badge: _tabBadge(isDarkMode() ? 'themeDark' : 'theme') },
+      { id: 'nodes', label: '🎯', title: 'Colors', badge: (function () { var n = _countOverrides('nodeColors') + _countOverrides('typeColors'); return n ? ' <span class="cv2-tab-badge">' + n + '</span>' : ''; })() },
+      { id: 'home', label: '🏠', title: 'Home', badge: _tabBadge('home') },
+      { id: 'display', label: '🖥️', title: 'Display', badge: _tabBadge('timestamps') },
+      { id: 'export', label: '📤', title: 'Export' }
+    ];
+    return '<div class="cust-tabs">' + tabs.map(function (t) {
+      return '<button class="cust-tab' + (t.id === _activeTab ? ' active' : '') + '" data-tab="' + t.id + '" title="' + t.title + '">' +
+        t.label + ' <span class="cust-tab-text">' + t.title + '</span>' + (t.badge || '') + '</button>';
+    }).join('') + '</div>';
+  }
+
+  function _renderColorRow(key, section, effectiveVal, serverDefault) {
+    var isFont = key === 'font' || key === 'mono';
+    var val = effectiveVal || '';
+    var def = serverDefault || '';
+    var dot = _overrideDot(section, key);
+    var inputHtml;
+    if (isFont) {
+      inputHtml = '<input type="text" data-cv2-field="' + section + '.' + key + '" value="' + escAttr(val) + '" style="width:160px;font-size:11px;font-family:var(--mono);padding:4px 6px;border:1px solid var(--border);border-radius:4px;background:var(--input-bg);color:var(--text)">';
+    } else {
+      // Ensure hex is 7 chars for color input
+      var hexVal = val.length === 7 ? val : (val.length === 4 ? '#' + val[1] + val[1] + val[2] + val[2] + val[3] + val[3] : val);
+      inputHtml = '<input type="color" data-cv2-field="' + section + '.' + key + '" value="' + hexVal + '">' +
+        '<span class="cust-hex">' + val + '</span>';
+    }
+    return '<div class="cust-color-row">' +
+      '<div><label>' + (THEME_LABELS[key] || key) + dot + '</label>' +
+      '<div class="cust-hint">' + (THEME_HINTS[key] || '') + '</div></div>' +
+      inputHtml +
+    '</div>';
+  }
+
+  function _detectActivePreset() {
+    var eff = _getEffective();
+    var effTheme = eff.theme || {};
+    var effDark = eff.themeDark || {};
+    for (var id in PRESETS) {
+      var p = PRESETS[id];
+      var match = true;
+      for (var i = 0; i < THEME_COLOR_KEYS.length && match; i++) {
+        var k = THEME_COLOR_KEYS[i];
+        if (effTheme[k] !== (p.theme || {})[k] || effDark[k] !== (p.themeDark || {})[k]) match = false;
+      }
+      if (match && p.nodeColors && eff.nodeColors) {
+        for (var nk in p.nodeColors) { if (eff.nodeColors[nk] !== p.nodeColors[nk]) { match = false; break; } }
+      }
+      if (match && p.typeColors && eff.typeColors) {
+        for (var tk in p.typeColors) { if (eff.typeColors[tk] !== p.typeColors[tk]) { match = false; break; } }
+      }
+      if (match) return id;
+    }
+    return null;
+  }
+
+  function _renderPresets() {
+    var active = _detectActivePreset();
+    var html = '<div style="margin-bottom:16px"><p class="cust-section-title">Theme Presets</p><div style="display:flex;gap:8px;flex-wrap:wrap">';
+    for (var id in PRESETS) {
+      var p = PRESETS[id];
+      var isActive = id === active;
+      var dots = '';
+      for (var di = 0; di < p.preview.length; di++) {
+        dots += '<span style="display:inline-block;width:12px;height:12px;border-radius:50%;background:' + p.preview[di] + ';border:1px solid rgba(128,128,128,.3)"></span>';
+      }
+      html += '<button class="cust-preset-btn' + (isActive ? ' active' : '') + '" data-preset="' + id + '">' +
+        '<div style="display:flex;gap:3px">' + dots + '</div>' +
+        '<span style="font-size:11px;font-weight:' + (isActive ? '700' : '500') + '">' + esc(p.name) + '</span>' +
+        '<span style="font-size:9px;color:var(--text-muted)">' + esc(p.desc) + '</span></button>';
+    }
+    html += '</div></div>';
+    return html;
+  }
+
+  function _renderBranding() {
+    var eff = _getEffective();
+    var b = eff.branding || {};
+    var logoPreview = b.logoUrl ? '<img class="cust-preview-img" src="' + escAttr(b.logoUrl) + '" alt="Logo preview" onerror="this.style.display=\'none\'">' : '';
+    return '<div class="cust-panel' + (_activeTab === 'branding' ? ' active' : '') + '" data-panel="branding">' +
+      '<div class="cust-field"><label>Site Name' + _overrideDot('branding', 'siteName') + '</label><input type="text" data-cv2-field="branding.siteName" value="' + escAttr(b.siteName || '') + '"></div>' +
+      '<div class="cust-field"><label>Tagline' + _overrideDot('branding', 'tagline') + '</label><input type="text" data-cv2-field="branding.tagline" value="' + escAttr(b.tagline || '') + '"></div>' +
+      '<div class="cust-field"><label>Logo URL' + _overrideDot('branding', 'logoUrl') + '</label><input type="text" data-cv2-field="branding.logoUrl" value="' + escAttr(b.logoUrl || '') + '" placeholder="https://...">' + logoPreview + '</div>' +
+      '<div class="cust-field"><label>Favicon URL' + _overrideDot('branding', 'faviconUrl') + '</label><input type="text" data-cv2-field="branding.faviconUrl" value="' + escAttr(b.faviconUrl || '') + '" placeholder="https://..."></div>' +
+    '</div>';
+  }
+
+  function _renderTheme() {
+    var dark = isDarkMode();
+    var section = dark ? 'themeDark' : 'theme';
+    var eff = _getEffective();
+    var server = _getServer();
+    var current = dark ? Object.assign({}, eff.theme || {}, eff.themeDark || {}) : (eff.theme || {});
+    var serverCurrent = dark ? Object.assign({}, server.theme || {}, server.themeDark || {}) : (server.theme || {});
+    var modeLabel = dark ? '🌙 Dark Mode' : '☀️ Light Mode';
+
+    var basicRows = '';
+    for (var i = 0; i < BASIC_KEYS.length; i++) basicRows += _renderColorRow(BASIC_KEYS[i], section, current[BASIC_KEYS[i]], serverCurrent[BASIC_KEYS[i]]);
+    var advancedRows = '';
+    for (var j = 0; j < ADVANCED_KEYS.length; j++) advancedRows += _renderColorRow(ADVANCED_KEYS[j], section, current[ADVANCED_KEYS[j]], serverCurrent[ADVANCED_KEYS[j]]);
+    var fontRows = '';
+    for (var f = 0; f < FONT_KEYS.length; f++) fontRows += _renderColorRow(FONT_KEYS[f], section, current[FONT_KEYS[f]], serverCurrent[FONT_KEYS[f]]);
+
+    return '<div class="cust-panel' + (_activeTab === 'theme' ? ' active' : '') + '" data-panel="theme">' +
+      _renderPresets() +
+      '<p class="cust-section-title">' + modeLabel + '</p>' +
+      '<p style="font-size:11px;color:var(--text-muted);margin:0 0 10px">Toggle ☀️/🌙 in nav to edit the other mode.</p>' +
+      basicRows +
+      '<details class="cust-advanced"><summary style="font-size:12px;font-weight:600;cursor:pointer;color:var(--text-muted);margin:12px 0 8px">Advanced (' + ADVANCED_KEYS.length + ' options)</summary>' + advancedRows + '</details>' +
+      '<details class="cust-fonts" style="margin-top:12px"><summary style="font-size:12px;font-weight:600;cursor:pointer;color:var(--text-muted);margin:12px 0 8px">Fonts</summary>' + fontRows + '</details>' +
+    '</div>';
+  }
+
+  function _renderNodes() {
+    var eff = _getEffective();
+    var server = _getServer();
+    var nc = eff.nodeColors || {};
+    var snc = server.nodeColors || {};
+    var rows = '';
+    for (var key in NODE_LABELS) {
+      var val = nc[key] || '#000000';
+      rows += '<div class="cust-color-row">' +
+        '<div><label>' + NODE_EMOJI[key] + ' ' + NODE_LABELS[key] + _overrideDot('nodeColors', key) + '</label>' +
+        '<div class="cust-hint">' + (NODE_HINTS[key] || '') + '</div></div>' +
+        '<input type="color" data-cv2-field="nodeColors.' + key + '" value="' + val + '">' +
+        '<span class="cust-node-dot" style="background:' + val + '"></span>' +
+        '<span class="cust-hex">' + val + '</span></div>';
+    }
+
+    var tc = eff.typeColors || {};
+    var stc = server.typeColors || {};
+    var typeRows = '';
+    for (var tkey in TYPE_LABELS) {
+      var tval = tc[tkey] || '#000000';
+      typeRows += '<div class="cust-color-row">' +
+        '<div><label>' + (TYPE_EMOJI[tkey] || '') + ' ' + TYPE_LABELS[tkey] + _overrideDot('typeColors', tkey) + '</label>' +
+        '<div class="cust-hint">' + (TYPE_HINTS[tkey] || '') + '</div></div>' +
+        '<input type="color" data-cv2-field="typeColors.' + tkey + '" value="' + tval + '">' +
+        '<span class="cust-node-dot" style="background:' + tval + '"></span>' +
+        '<span class="cust-hex">' + tval + '</span></div>';
+    }
+
+    // Heatmap opacity
+    var heatOpacity = typeof eff.heatmapOpacity === 'number' ? eff.heatmapOpacity : 0.25;
+    var heatPct = Math.round(heatOpacity * 100);
+    var liveHeatOpacity = typeof eff.liveHeatmapOpacity === 'number' ? eff.liveHeatmapOpacity : 0.3;
+    var liveHeatPct = Math.round(liveHeatOpacity * 100);
+
+    return '<div class="cust-panel' + (_activeTab === 'nodes' ? ' active' : '') + '" data-panel="nodes">' +
+      '<p class="cust-section-title">Node Role Colors</p>' + rows +
+      '<hr style="border:none;border-top:1px solid var(--border);margin:16px 0">' +
+      '<p class="cust-section-title">Packet Type Colors</p>' + typeRows +
+      '<hr style="border:none;border-top:1px solid var(--border);margin:16px 0">' +
+      '<p class="cust-section-title">Heatmap Opacity</p>' +
+      '<div class="cust-color-row"><div><label>🗺️ Nodes Map' + _overrideDot(null, 'heatmapOpacity') + '</label>' +
+        '<div class="cust-hint">Heatmap overlay on the Nodes → Map page (0–100%)</div></div>' +
+        '<input type="range" data-cv2-slider="heatmapOpacity" min="0" max="100" value="' + heatPct + '" style="width:120px;cursor:pointer">' +
+        '<span class="cust-hex" id="cv2HeatPct">' + heatPct + '%</span></div>' +
+      '<div class="cust-color-row"><div><label>📡 Live Map' + _overrideDot(null, 'liveHeatmapOpacity') + '</label>' +
+        '<div class="cust-hint">Heatmap overlay on the Live page (0–100%)</div></div>' +
+        '<input type="range" data-cv2-slider="liveHeatmapOpacity" min="0" max="100" value="' + liveHeatPct + '" style="width:120px;cursor:pointer">' +
+        '<span class="cust-hex" id="cv2LiveHeatPct">' + liveHeatPct + '%</span></div>' +
+    '</div>';
+  }
+
+  function _renderDisplay() {
+    var eff = _getEffective();
+    var ts = (eff.timestamps) || {};
+    var tsMode = ts.defaultMode === 'absolute' ? 'absolute' : 'ago';
+    var tsTz = ts.timezone === 'utc' ? 'utc' : 'local';
+    var tsFmt = (ts.formatPreset === 'iso-seconds' || ts.formatPreset === 'locale') ? ts.formatPreset : 'iso';
+    var customFmt = typeof ts.customFormat === 'string' ? ts.customFormat : '';
+    var canCustom = !!(eff.timestamps && eff.timestamps.allowCustomFormat === true);
+    var showAbs = tsMode === 'absolute' ? '' : ' style="display:none"';
+
+    return '<div class="cust-panel' + (_activeTab === 'display' ? ' active' : '') + '" data-panel="display">' +
+      '<p class="cust-section-title">Display Settings</p>' +
+      '<p style="font-size:12px;color:var(--text-muted);margin-bottom:12px">UI preferences that affect how data is shown across pages.</p>' +
+      '<p class="cust-section-title" style="font-size:14px;margin-bottom:8px">Timestamps</p>' +
+      '<div class="cust-field"><label>Timestamp Display' + _overrideDot('timestamps', 'defaultMode') + '</label>' +
+        '<select data-cv2-select="timestamps.defaultMode" style="width:100%;padding:6px 8px;border:1px solid var(--border);border-radius:6px;background:var(--input-bg);color:var(--text)">' +
+          '<option value="ago"' + (tsMode === 'ago' ? ' selected' : '') + '>Relative (3m ago)</option>' +
+          '<option value="absolute"' + (tsMode === 'absolute' ? ' selected' : '') + '>Absolute (ISO timestamp)</option></select></div>' +
+      '<div class="cust-field"><label>Timezone' + _overrideDot('timestamps', 'timezone') + '</label>' +
+        '<select data-cv2-select="timestamps.timezone" style="width:100%;padding:6px 8px;border:1px solid var(--border);border-radius:6px;background:var(--input-bg);color:var(--text)">' +
+          '<option value="local"' + (tsTz === 'local' ? ' selected' : '') + '>Local time</option>' +
+          '<option value="utc"' + (tsTz === 'utc' ? ' selected' : '') + '>UTC</option></select></div>' +
+      '<div class="cust-field" data-ts-abs="format"' + showAbs + '><label>Format' + _overrideDot('timestamps', 'formatPreset') + '</label>' +
+        '<select data-cv2-select="timestamps.formatPreset" style="width:100%;padding:6px 8px;border:1px solid var(--border);border-radius:6px;background:var(--input-bg);color:var(--text)">' +
+          '<option value="iso"' + (tsFmt === 'iso' ? ' selected' : '') + '>ISO (2024-01-15 14:30:00)</option>' +
+          '<option value="iso-seconds"' + (tsFmt === 'iso-seconds' ? ' selected' : '') + '>ISO + ms</option>' +
+          '<option value="locale"' + (tsFmt === 'locale' ? ' selected' : '') + '>Locale (browser)</option></select></div>' +
+      (canCustom ? '<div class="cust-field" data-ts-abs="custom"' + showAbs + '><label>Custom Format' + _overrideDot('timestamps', 'customFormat') + '</label>' +
+        '<input type="text" data-cv2-field="timestamps.customFormat" value="' + escAttr(customFmt) + '" placeholder="YYYY-MM-DD HH:mm:ss"></div>' : '') +
+    '</div>';
+  }
+
+  function _renderHome() {
+    var eff = _getEffective();
+    var h = eff.home || {};
+    var steps = h.steps || [];
+    var checklist = h.checklist || [];
+    var footerLinks = h.footerLinks || [];
+
+    var stepsHtml = steps.map(function (s, i) {
+      return '<div class="cust-list-item">' +
+        '<div class="cust-list-row">' +
+          '<input class="cust-emoji-input" data-cv2-home="steps.' + i + '.emoji" value="' + escAttr(s.emoji) + '" placeholder="📡">' +
+          '<input data-cv2-home="steps.' + i + '.title" value="' + escAttr(s.title) + '" placeholder="Title">' +
+          '<button class="cust-list-btn" data-cv2-move="steps.' + i + '.up">↑</button>' +
+          '<button class="cust-list-btn" data-cv2-move="steps.' + i + '.down">↓</button>' +
+          '<button class="cust-list-btn danger" data-cv2-rm="steps.' + i + '">✕</button>' +
+        '</div>' +
+        '<textarea data-cv2-home="steps.' + i + '.description" placeholder="Description" rows="2">' + esc(s.description) + '</textarea>' +
+        '<div class="cust-md-hint">Markdown: <code>**bold**</code> <code>*italic*</code> <code>`code`</code> <code>[text](url)</code></div></div>';
+    }).join('');
+
+    var checkHtml = checklist.map(function (c, i) {
+      return '<div class="cust-list-item">' +
+        '<div class="cust-list-row"><input data-cv2-home="checklist.' + i + '.question" value="' + escAttr(c.question) + '" placeholder="Question">' +
+          '<button class="cust-list-btn danger" data-cv2-rm="checklist.' + i + '">✕</button></div>' +
+        '<textarea data-cv2-home="checklist.' + i + '.answer" placeholder="Answer" rows="2">' + esc(c.answer) + '</textarea></div>';
+    }).join('');
+
+    var linksHtml = footerLinks.map(function (l, i) {
+      return '<div class="cust-list-item">' +
+        '<div class="cust-list-row"><input data-cv2-home="footerLinks.' + i + '.label" value="' + escAttr(l.label) + '" placeholder="Label">' +
+          '<button class="cust-list-btn danger" data-cv2-rm="footerLinks.' + i + '">✕</button></div>' +
+        '<input data-cv2-home="footerLinks.' + i + '.url" value="' + escAttr(l.url) + '" placeholder="URL"></div>';
+    }).join('');
+
+    return '<div class="cust-panel' + (_activeTab === 'home' ? ' active' : '') + '" data-panel="home">' +
+      '<div class="cust-field"><label>Hero Title' + _overrideDot('home', 'heroTitle') + '</label>' +
+        '<input type="text" data-cv2-field="home.heroTitle" value="' + escAttr(h.heroTitle || '') + '"></div>' +
+      '<div class="cust-field"><label>Hero Subtitle' + _overrideDot('home', 'heroSubtitle') + '</label>' +
+        '<input type="text" data-cv2-field="home.heroSubtitle" value="' + escAttr(h.heroSubtitle || '') + '"></div>' +
+      '<p class="cust-section-title" style="margin-top:20px">Steps</p>' + stepsHtml +
+      '<button class="cust-add-btn" data-cv2-add="steps">+ Add Step</button>' +
+      '<p class="cust-section-title" style="margin-top:24px">FAQ / Checklist</p>' + checkHtml +
+      '<button class="cust-add-btn" data-cv2-add="checklist">+ Add Question</button>' +
+      '<p class="cust-section-title" style="margin-top:24px">Footer Links</p>' + linksHtml +
+      '<button class="cust-add-btn" data-cv2-add="footerLinks">+ Add Link</button>' +
+    '</div>';
+  }
+
+  function _renderExport() {
+    var delta = readOverrides();
+    var json = JSON.stringify(delta, null, 2);
+    var hasDelta = Object.keys(delta).length > 0;
+
+    return '<div class="cust-panel' + (_activeTab === 'export' ? ' active' : '') + '" data-panel="export">' +
+      '<p class="cust-section-title">Export / Import</p>' +
+      '<p style="font-size:12px;color:var(--text-muted);margin-bottom:8px">Your customizations are stored in your browser. Export to share or back up.</p>' +
+      '<div class="cust-export-btns">' +
+        '<button class="cust-dl-btn" id="cv2Download">💾 Download JSON</button>' +
+        '<button class="cust-dl-btn" id="cv2ImportFile">📂 Import File</button>' +
+        '<input type="file" id="cv2ImportInput" accept=".json,application/json" style="display:none">' +
+        '<button class="cust-copy-btn" id="cv2Copy">📋 Copy</button>' +
+      '</div>' +
+      (hasDelta ? '<div style="margin-top:12px"><button class="cust-reset-all" id="cv2ResetAll">🗑️ Reset All Customizations</button></div>' : '') +
+      '<details style="margin-top:12px"><summary style="font-size:12px;font-weight:600;cursor:pointer;color:var(--text-muted)">Raw JSON</summary>' +
+        '<textarea id="cv2ExportJson" style="width:100%;min-height:200px;font-family:var(--mono);font-size:12px;background:var(--surface-1);border:1px solid var(--border);border-radius:6px;padding:12px;color:var(--text);resize:vertical;box-sizing:border-box;margin-top:8px">' + esc(json) + '</textarea>' +
+      '</details>' +
+    '</div>';
+  }
+
+  function _renderPanel(container) {
+    container.innerHTML =
+      _renderTabs() +
+      '<div class="cust-body">' +
+        _renderBranding() +
+        _renderTheme() +
+        _renderNodes() +
+        _renderHome() +
+        _renderDisplay() +
+        _renderExport() +
+      '</div>';
+    _bindEvents(container);
+  }
+
+  function _refreshPanel() {
+    if (!_panelEl) return;
+    var inner = _panelEl.querySelector('.cust-inner');
+    if (inner) _renderPanel(inner);
+  }
+
+  function _bindEvents(container) {
+    // Tab switching
+    container.querySelectorAll('.cust-tab').forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        _activeTab = btn.dataset.tab;
+        _renderPanel(container);
+      });
+    });
+
+    // Preset buttons
+    container.querySelectorAll('.cust-preset-btn').forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        var id = btn.dataset.preset;
+        var p = PRESETS[id];
+        if (!p) return;
+        // "Reset to Default" preset = clear all overrides (full reset per spec)
+        if (id === 'default') {
+          localStorage.removeItem(STORAGE_KEY);
+        } else {
+          // Other presets: write preset data as delta (replaces entire delta per spec)
+          var delta = {};
+          if (p.theme) delta.theme = JSON.parse(JSON.stringify(p.theme));
+          if (p.themeDark) delta.themeDark = JSON.parse(JSON.stringify(p.themeDark));
+          if (p.nodeColors) delta.nodeColors = JSON.parse(JSON.stringify(p.nodeColors));
+          if (p.typeColors) delta.typeColors = JSON.parse(JSON.stringify(p.typeColors));
+          writeOverrides(delta);
+        }
+        _runPipeline();
+        _renderPanel(container);
+      });
+    });
+
+    // Override dot reset buttons
+    container.querySelectorAll('.cv2-override-dot').forEach(function (dot) {
+      dot.addEventListener('click', function (e) {
+        e.stopPropagation();
+        var s = dot.dataset.resetS || null;
+        var k = dot.dataset.resetK;
+        if (s === '') s = null;
+        clearOverride(s, k);
+      });
+    });
+
+    // Text/color inputs (unified via data-cv2-field="section.key")
+    container.querySelectorAll('[data-cv2-field]').forEach(function (inp) {
+      var parts = inp.dataset.cv2Field.split('.');
+      var section = parts[0];
+      var key = parts[1];
+      // Optimistic CSS for color pickers on input event
+      if (inp.type === 'color') {
+        inp.addEventListener('input', function () {
+          // Optimistic CSS update (Decision #12)
+          var cssVar = THEME_CSS_MAP[key];
+          if (cssVar) document.documentElement.style.setProperty(cssVar, inp.value);
+          // Update hex display
+          var hex = inp.parentElement.querySelector('.cust-hex');
+          if (hex) hex.textContent = inp.value;
+          // Update node dot
+          var dot = inp.parentElement.querySelector('.cust-node-dot');
+          if (dot) dot.style.background = inp.value;
+        });
+        inp.addEventListener('change', function () {
+          setOverride(section, key, inp.value);
+        });
+      } else {
+        // Text inputs — debounced write on input
+        inp.addEventListener('input', function () {
+          setOverride(section, key, inp.value);
+          // Live branding updates
+          if (section === 'branding' && key === 'siteName') {
+            var el = document.querySelector('.brand-text');
+            if (el) el.textContent = inp.value;
+            document.title = inp.value;
+          }
+          if (section === 'branding' && key === 'logoUrl') {
+            var iconEl = document.querySelector('.brand-icon');
+            if (iconEl) {
+              if (inp.value) iconEl.innerHTML = '<img src="' + inp.value + '" style="height:24px" onerror="this.style.display=\'none\'">';
+              else iconEl.textContent = '📡';
+            }
+          }
+          if (section === 'branding' && key === 'faviconUrl') {
+            var link = document.querySelector('link[rel="icon"]');
+            if (link && inp.value) link.href = inp.value;
+          }
+        });
+      }
+    });
+
+    // Select elements
+    container.querySelectorAll('[data-cv2-select]').forEach(function (sel) {
+      sel.addEventListener('change', function () {
+        var parts = sel.dataset.cv2Select.split('.');
+        setOverride(parts[0], parts[1], sel.value);
+        // Show/hide absolute-only fields
+        if (parts[1] === 'defaultMode') {
+          container.querySelectorAll('[data-ts-abs]').forEach(function (el) {
+            el.style.display = sel.value === 'absolute' ? '' : 'none';
+          });
+        }
+        window.dispatchEvent(new CustomEvent('timestamp-mode-changed'));
+      });
+    });
+
+    // Slider inputs (heatmap opacity)
+    container.querySelectorAll('[data-cv2-slider]').forEach(function (inp) {
+      var key = inp.dataset.cv2Slider;
+      inp.addEventListener('input', function () {
+        var pct = parseInt(inp.value);
+        var label = key === 'heatmapOpacity' ? document.getElementById('cv2HeatPct') : document.getElementById('cv2LiveHeatPct');
+        if (label) label.textContent = pct + '%';
+        var opacity = pct / 100;
+        // Optimistic: update heatmap layer directly
+        if (key === 'heatmapOpacity' && window._meshcoreHeatLayer) {
+          var canvas = window._meshcoreHeatLayer._canvas || (window._meshcoreHeatLayer.getContainer && window._meshcoreHeatLayer.getContainer());
+          if (canvas) canvas.style.opacity = opacity;
+        }
+        if (key === 'liveHeatmapOpacity' && window._meshcoreLiveHeatLayer) {
+          var canvas2 = window._meshcoreLiveHeatLayer._canvas || (window._meshcoreLiveHeatLayer.getContainer && window._meshcoreLiveHeatLayer.getContainer());
+          if (canvas2) canvas2.style.opacity = opacity;
+        }
+      });
+      inp.addEventListener('change', function () {
+        setOverride(null, key, parseInt(inp.value) / 100);
+      });
+    });
+
+    // Home page list editing
+    container.querySelectorAll('[data-cv2-home]').forEach(function (inp) {
+      inp.addEventListener('input', function () {
+        // Parse: steps.0.title → home.steps[0].title
+        var path = inp.dataset.cv2Home.split('.');
+        var eff = _getEffective();
+        var home = JSON.parse(JSON.stringify(eff.home || {}));
+        var arr = home[path[0]];
+        if (arr && arr[parseInt(path[1])]) {
+          arr[parseInt(path[1])][path[2]] = inp.value;
+          setOverride('home', path[0], arr);
+        }
+      });
+    });
+
+    // Home list move/remove
+    container.querySelectorAll('[data-cv2-move]').forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        var parts = btn.dataset.cv2Move.split('.');
+        var listKey = parts[0];
+        var idx = parseInt(parts[1]);
+        var dir = parts[2] === 'up' ? -1 : 1;
+        var eff = _getEffective();
+        var home = JSON.parse(JSON.stringify(eff.home || {}));
+        var arr = home[listKey];
+        if (!arr) return;
+        var j = idx + dir;
+        if (j < 0 || j >= arr.length) return;
+        var tmp = arr[idx]; arr[idx] = arr[j]; arr[j] = tmp;
+        setOverride('home', listKey, arr);
+      });
+    });
+    container.querySelectorAll('[data-cv2-rm]').forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        var parts = btn.dataset.cv2Rm.split('.');
+        var listKey = parts[0];
+        var idx = parseInt(parts[1]);
+        var eff = _getEffective();
+        var home = JSON.parse(JSON.stringify(eff.home || {}));
+        var arr = home[listKey];
+        if (!arr) return;
+        arr.splice(idx, 1);
+        setOverride('home', listKey, arr);
+      });
+    });
+    container.querySelectorAll('[data-cv2-add]').forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        var listKey = btn.dataset.cv2Add;
+        var eff = _getEffective();
+        var home = JSON.parse(JSON.stringify(eff.home || {}));
+        var arr = home[listKey] || [];
+        if (listKey === 'steps') arr.push({ emoji: '📌', title: '', description: '' });
+        else if (listKey === 'checklist') arr.push({ question: '', answer: '' });
+        else if (listKey === 'footerLinks') arr.push({ label: '', url: '' });
+        setOverride('home', listKey, arr);
+      });
+    });
+
+    // Export buttons
+    var dlBtn = document.getElementById('cv2Download');
+    if (dlBtn) dlBtn.addEventListener('click', function () {
+      var json = JSON.stringify(readOverrides(), null, 2);
+      var blob = new Blob([json], { type: 'application/json' });
+      var a = document.createElement('a');
+      a.href = URL.createObjectURL(blob);
+      a.download = 'corescope-theme.json';
+      a.click();
+      URL.revokeObjectURL(a.href);
+    });
+
+    var copyBtn = document.getElementById('cv2Copy');
+    if (copyBtn) copyBtn.addEventListener('click', function () {
+      var json = JSON.stringify(readOverrides(), null, 2);
+      if (window.copyToClipboard) {
+        window.copyToClipboard(json, function () {
+          copyBtn.textContent = '✓ Copied!';
+          setTimeout(function () { copyBtn.textContent = '📋 Copy'; }, 2000);
+        });
+      }
+    });
+
+    // Import
+    var importBtn = document.getElementById('cv2ImportFile');
+    var importInput = document.getElementById('cv2ImportInput');
+    if (importBtn && importInput) {
+      importBtn.addEventListener('click', function () { importInput.click(); });
+      importInput.addEventListener('change', function () {
+        var file = importInput.files[0];
+        if (!file) return;
+        var reader = new FileReader();
+        reader.onload = function () {
+          try {
+            var data = JSON.parse(reader.result);
+            var result = validateShape(data);
+            if (!result.valid) {
+              importBtn.textContent = '✕ ' + result.errors[0];
+              setTimeout(function () { importBtn.textContent = '📂 Import File'; }, 3000);
+              return;
+            }
+            writeOverrides(data);
+            _runPipeline();
+            _renderPanel(container);
+            importBtn.textContent = '✓ Imported!';
+            setTimeout(function () { importBtn.textContent = '📂 Import File'; }, 2000);
+          } catch (e) {
+            importBtn.textContent = '✕ Invalid JSON';
+            setTimeout(function () { importBtn.textContent = '📂 Import File'; }, 3000);
+          }
+        };
+        reader.readAsText(file);
+        importInput.value = '';
+      });
+    }
+
+    // Reset All
+    var resetBtn = document.getElementById('cv2ResetAll');
+    if (resetBtn) resetBtn.addEventListener('click', function () {
+      if (!confirm('Reset all customizations to server defaults?')) return;
+      localStorage.removeItem(STORAGE_KEY);
+      _runPipeline();
+      _renderPanel(container);
+    });
+  }
+
+  // ── Panel toggle ──
+
+  function toggle() {
+    if (_panelEl) {
+      _panelEl.classList.toggle('hidden');
+      if (!_panelEl.classList.contains('hidden')) _refreshPanel();
+      return;
+    }
+    _injectStyles();
+    _panelEl = document.createElement('div');
+    _panelEl.className = 'cust-overlay';
+    _panelEl.innerHTML =
+      '<div class="cust-header"><h2>🎨 Customize</h2><button class="cust-close" title="Close">✕</button></div>' +
+      '<div class="cv2-local-banner">These settings are saved in your browser only and don\'t affect other users.</div>' +
+      '<div class="cust-inner"></div>' +
+      '<div class="cv2-footer"><span id="cv2-save-status">All changes saved</span></div>';
+    document.body.appendChild(_panelEl);
+
+    _panelEl.querySelector('.cust-close').addEventListener('click', function () { _panelEl.classList.add('hidden'); });
+
+    // Drag support
+    var header = _panelEl.querySelector('.cust-header');
+    header.addEventListener('mousedown', function (e) {
+      if (e.target.closest('.cust-close')) return;
+      var dragX = _panelEl.offsetLeft, dragY = _panelEl.offsetTop;
+      var startX = e.clientX, startY = e.clientY;
+      var onMove = function (ev) {
+        _panelEl.style.left = Math.max(0, dragX + ev.clientX - startX) + 'px';
+        _panelEl.style.top = Math.max(56, dragY + ev.clientY - startY) + 'px';
+        _panelEl.style.right = 'auto';
+      };
+      var onUp = function () { document.removeEventListener('mousemove', onMove); document.removeEventListener('mouseup', onUp); };
+      document.addEventListener('mousemove', onMove);
+      document.addEventListener('mouseup', onUp);
+    });
+
+    _renderPanel(_panelEl.querySelector('.cust-inner'));
+    _updateSaveStatus(_saveStatus);
+  }
+
+  // ── Initialization (runs immediately on script load) ──
+
+  // 1. Migration check
+  migrateOldKeys();
+
+  // 2. Read overrides and apply CSS immediately (before DOMContentLoaded)
+  // Server defaults will be set later when /api/config/theme completes.
+  // For now, apply whatever overrides exist on top of current SITE_CONFIG.
+  var earlyOverrides = readOverrides();
+  if (Object.keys(earlyOverrides).length > 0) {
+    var earlyServer = window.SITE_CONFIG || {};
+    var earlyEffective = computeEffective(earlyServer, earlyOverrides);
+    // Don't fully overwrite SITE_CONFIG yet — just apply CSS vars
+    var dark = isDarkMode();
+    var themeSection = dark
+      ? Object.assign({}, earlyEffective.theme || {}, earlyEffective.themeDark || {})
+      : (earlyEffective.theme || {});
+    var root = document.documentElement.style;
+    for (var key in THEME_CSS_MAP) {
+      if (themeSection[key]) root.setProperty(THEME_CSS_MAP[key], themeSection[key]);
+    }
+    if (themeSection.background) root.setProperty('--content-bg', themeSection.contentBg || themeSection.background);
+    if (themeSection.surface1) root.setProperty('--card-bg', themeSection.cardBg || themeSection.surface1);
+    // Apply node/type colors from overrides early
+    if (earlyOverrides.nodeColors) {
+      for (var role in earlyOverrides.nodeColors) {
+        if (window.ROLE_COLORS && role in window.ROLE_COLORS) window.ROLE_COLORS[role] = earlyOverrides.nodeColors[role];
+        if (window.ROLE_STYLE && window.ROLE_STYLE[role]) window.ROLE_STYLE[role].color = earlyOverrides.nodeColors[role];
+      }
+    }
+    if (earlyOverrides.typeColors && window.TYPE_COLORS) {
+      for (var type in earlyOverrides.typeColors) {
+        if (type in window.TYPE_COLORS) window.TYPE_COLORS[type] = earlyOverrides.typeColors[type];
+      }
+      if (window.syncBadgeColors) window.syncBadgeColors();
+    }
+  }
+
+  // 3. Wire up toggle button + watch dark mode changes (needs DOM)
+  document.addEventListener('DOMContentLoaded', function () {
+    var btn = document.getElementById('customizeToggle');
+    if (btn) btn.addEventListener('click', toggle);
+
+    // Re-apply branding from overrides once DOM is ready
+    var overrides = readOverrides();
+    if (overrides.branding) {
+      if (overrides.branding.siteName) {
+        var brandEl = document.querySelector('.brand-text');
+        if (brandEl) brandEl.textContent = overrides.branding.siteName;
+        document.title = overrides.branding.siteName;
+      }
+      if (overrides.branding.logoUrl) {
+        var iconEl = document.querySelector('.brand-icon');
+        if (iconEl) iconEl.innerHTML = '<img src="' + overrides.branding.logoUrl + '" style="height:24px" onerror="this.style.display=\'none\'">';
+      }
+      if (overrides.branding.faviconUrl) {
+        var link = document.querySelector('link[rel="icon"]');
+        if (link) link.href = overrides.branding.faviconUrl;
+      }
+    }
+
+    // Watch dark/light mode toggle and re-apply
+    new MutationObserver(function () {
+      _runPipeline();
+    }).observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+  });
+
+  // ── Public API for app.js integration ──
+
+  /**
+   * Called by app.js after /api/config/theme fetch completes.
+   * Sets server defaults and runs the full pipeline.
+   */
+  window._customizerV2 = {
+    init: function (serverConfig) {
+      _serverDefaults = serverConfig || {};
+      _runPipeline();
+    },
+    readOverrides: readOverrides,
+    writeOverrides: writeOverrides,
+    computeEffective: computeEffective,
+    setOverride: setOverride,
+    clearOverride: clearOverride,
+    migrateOldKeys: migrateOldKeys,
+    validateShape: validateShape,
+    applyCSS: applyCSS,
+    isValidColor: isValidColor,
+    isOverridden: _isOverridden,
+    THEME_CSS_MAP: THEME_CSS_MAP
+  };
+})();
diff --git a/public/index.html b/public/index.html
index b9b108bd..951601ce 100644
--- a/public/index.html
+++ b/public/index.html
@@ -86,7 +86,7 @@
 
   <script src="vendor/qrcode.js"></script>
   <script src="roles.js?v=__BUST__"></script>
-  <script src="customize.js?v=__BUST__" onerror="console.error('Failed to load:', this.src)"></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>
diff --git a/test-customizer-v2.js b/test-customizer-v2.js
new file mode 100644
index 00000000..2874e96a
--- /dev/null
+++ b/test-customizer-v2.js
@@ -0,0 +1,408 @@
+/* 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);
+});
+
+// ── Summary ──
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`);
+process.exit(failed > 0 ? 1 : 0);
diff --git a/test-e2e-playwright.js b/test-e2e-playwright.js
index a845af78..fab4f978 100644
--- a/test-e2e-playwright.js
+++ b/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 '';
@@ -1015,6 +1015,252 @@ 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"]');
+    // Clear any existing overrides
+    await page.evaluate(() => localStorage.removeItem('cs-theme-overrides'));
+    // Set an override via the API
+    const result = await page.evaluate(() => {
+      if (!window._customizerV2) return { error: 'customizerV2 not loaded' };
+      window._customizerV2.setOverride('theme', 'accent', '#ff0000');
+      // Wait for debounce
+      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.error, result.error || '');
+    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"]');
+    const result = await page.evaluate(() => {
+      if (!window._customizerV2) return { error: 'customizerV2 not loaded' };
+      // Get 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.error, result.error || '');
+    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'));
+  });
+
   // Extract frontend coverage if instrumented server is running
   try {
     const coverage = await page.evaluate(() => window.__coverage__);
diff --git a/test-frontend-helpers.js b/test-frontend-helpers.js
index 0fbbe6d5..9508b4fb 100644
--- a/test-frontend-helpers.js
+++ b/test-frontend-helpers.js
@@ -1942,263 +1942,87 @@ console.log('\n=== analytics.js: sortChannels ===');
 }
 
 
-// ===== CUSTOMIZE.JS: initState merge behavior =====
-console.log('\n=== customize.js: initState merge behavior ===');
+// ===== CUSTOMIZE-V2.JS: core behavior =====
+console.log('\n=== customize-v2.js: core behavior ===');
 {
-  function loadCustomizeExports(ctx) {
-    const src = fs.readFileSync('public/customize.js', 'utf8');
-    const withExports = src.replace(
-      /\}\)\(\);\s*$/,
-      'window.__customizeExport = { initState: initState, autoSave: autoSave, getState: function () { return state; }, getDefaults: function () { return deepClone(DEFAULTS); }, setInitialized: function (v) { _initialized = !!v; } };})();'
-    );
-    vm.runInContext(withExports, ctx);
+  function loadCustomizeV2(ctx) {
+    const src = fs.readFileSync('public/customize-v2.js', 'utf8');
+    vm.runInContext(src, ctx);
     for (const k of Object.keys(ctx.window)) ctx[k] = ctx.window[k];
-    return ctx.window.__customizeExport;
+    return ctx.window._customizerV2;
   }
 
-  test('autoSave no-ops before initialization on panel open path', () => {
+  test('readOverrides returns empty object when no localStorage data', () => {
     const ctx = makeSandbox();
-    let saveTimerCalls = 0;
-    ctx.setTimeout = function () { saveTimerCalls++; return 1; };
-    ctx.clearTimeout = function () {};
-    ctx.window.SITE_CONFIG = { home: { heroTitle: 'Server Hero' } };
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    ex.setInitialized(false);
-    ex.autoSave();
-    assert.strictEqual(saveTimerCalls, 0);
-    assert.strictEqual(ctx.localStorage.getItem('meshcore-user-theme'), null);
+    ctx.CustomEvent = function (type) { this.type = type; };
+    const v2 = loadCustomizeV2(ctx);
+    const overrides = v2.readOverrides();
+    assert.strictEqual(Object.keys(overrides).length, 0);
   });
 
-  test('server home config survives customizer open without modification', () => {
+  test('writeOverrides + readOverrides roundtrip', () => {
     const ctx = makeSandbox();
-    let saveTimerCalls = 0;
-    ctx.setTimeout = function () { saveTimerCalls++; return 1; };
-    ctx.clearTimeout = function () {};
-    ctx.window.SITE_CONFIG = {
-      home: {
-        heroTitle: 'Server Hero',
-        heroSubtitle: 'Server Subtitle',
-        steps: [{ emoji: 'S', title: 'Server Step', description: 'server' }],
-        checklist: [{ question: 'Server Q', answer: 'Server A' }],
-        footerLinks: [{ label: 'Server Link', url: '#/server' }]
-      }
-    };
-    const before = JSON.stringify(ctx.window.SITE_CONFIG.home);
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    ex.setInitialized(false);
-    ex.autoSave();
-    assert.strictEqual(saveTimerCalls, 0);
-    assert.strictEqual(JSON.stringify(ctx.window.SITE_CONFIG.home), before);
+    ctx.CustomEvent = function (type) { this.type = type; };
+    const v2 = loadCustomizeV2(ctx);
+    v2.writeOverrides({ theme: { accent: '#ff0000' } });
+    const result = v2.readOverrides();
+    assert.strictEqual(result.theme.accent, '#ff0000');
   });
 
-  test('post-init autoSave exports user theme without mutating SITE_CONFIG.home', () => {
+  test('computeEffective merges server defaults with overrides', () => {
     const ctx = makeSandbox();
-    let saveTimerCalls = 0;
-    ctx.setTimeout = function (fn) { saveTimerCalls++; fn(); return 1; };
-    ctx.clearTimeout = function () {};
-    ctx.HashChangeEvent = function HashChangeEvent(type) { this.type = type; };
-    ctx.window.SITE_CONFIG = {
-      home: {
-        heroTitle: 'Server Hero',
-        heroSubtitle: 'Server Subtitle',
-        steps: [{ emoji: 'S', title: 'Server Step', description: 'server' }],
-        checklist: [{ question: 'Server Q', answer: 'Server A' }],
-        footerLinks: [{ label: 'Server Link', url: '#/server' }]
-      }
-    };
-    const before = JSON.stringify(ctx.window.SITE_CONFIG.home);
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    ex.setInitialized(true);
-    ex.autoSave();
-    const saved = ctx.localStorage.getItem('meshcore-user-theme');
-    assert.strictEqual(saveTimerCalls, 1);
-    assert(saved && saved.length > 0, 'Expected autoSave to persist user theme');
-    assert.strictEqual(JSON.stringify(ctx.window.SITE_CONFIG.home), before);
+    ctx.CustomEvent = function (type) { this.type = type; };
+    const v2 = loadCustomizeV2(ctx);
+    const server = { theme: { accent: '#111111', navBg: '#222222' } };
+    const overrides = { theme: { accent: '#ff0000' } };
+    const effective = v2.computeEffective(server, overrides);
+    assert.strictEqual(effective.theme.accent, '#ff0000');
+    assert.strictEqual(effective.theme.navBg, '#222222');
   });
 
-  test('partial local checklist does not wipe steps/footerLinks and keeps server colors', () => {
+  test('isValidColor accepts hex, rgb, hsl, and named colors', () => {
     const ctx = makeSandbox();
-    ctx.window.SITE_CONFIG = {
-      home: {
-        heroTitle: 'Server Hero',
-        heroSubtitle: 'Server Subtitle',
-        steps: [{ emoji: '🧪', title: 'Server Step', description: 'from server' }],
-        checklist: [{ question: 'Server Q', answer: 'Server A' }],
-        footerLinks: [{ label: 'Server Link', url: '#/server' }]
-      },
-      theme: { accent: '#123456', navBg: '#222222' },
-      nodeColors: { repeater: '#aa0000' }
-    };
-    ctx.localStorage.setItem('meshcore-user-theme', JSON.stringify({
-      home: { checklist: [{ question: 'Local Q', answer: 'Local A' }] }
-    }));
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    const state = ex.getState();
-    assert.strictEqual(state.home.checklist[0].question, 'Local Q');
-    assert.strictEqual(state.home.steps[0].title, 'Server Step');
-    assert.strictEqual(state.home.footerLinks[0].label, 'Server Link');
-    assert.strictEqual(state.home.heroTitle, 'Server Hero');
-    assert.strictEqual(state.theme.accent, '#123456');
-    assert.strictEqual(state.nodeColors.repeater, '#aa0000');
+    ctx.CustomEvent = function (type) { this.type = type; };
+    const v2 = loadCustomizeV2(ctx);
+    assert.strictEqual(v2.isValidColor('#ff0000'), true);
+    assert.strictEqual(v2.isValidColor('#abc'), true);
+    assert.strictEqual(v2.isValidColor('rgb(255, 0, 0)'), true);
+    assert.strictEqual(v2.isValidColor('hsl(0, 100%, 50%)'), true);
+    assert.strictEqual(v2.isValidColor('red'), true);
+    assert.strictEqual(v2.isValidColor('notacolor'), false);
+    assert.strictEqual(v2.isValidColor(123), false);
   });
 
-  test('server values survive when localStorage has partial overrides', () => {
+  test('validateShape reports invalid color values', () => {
     const ctx = makeSandbox();
-    ctx.window.SITE_CONFIG = {
-      home: {
-        heroTitle: 'Server Hero',
-        heroSubtitle: 'Server Subtitle',
-        steps: [{ emoji: '1️⃣', title: 'Server Step', description: 'server' }],
-        footerLinks: [{ label: 'Server Footer', url: '#/s' }]
-      },
-      theme: { accent: '#111111', navBg: '#222222', navText: '#333333' },
-      typeColors: { ADVERT: '#00aa00', REQUEST: '#aa00aa' }
-    };
-    ctx.localStorage.setItem('meshcore-user-theme', JSON.stringify({
-      home: { heroTitle: 'Local Hero' },
-      theme: { accent: '#999999' },
-      typeColors: { ADVERT: '#ff00ff' }
-    }));
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    const state = ex.getState();
-    assert.strictEqual(state.home.heroTitle, 'Local Hero');
-    assert.strictEqual(state.home.heroSubtitle, 'Server Subtitle');
-    assert.strictEqual(state.home.steps[0].title, 'Server Step');
-    assert.strictEqual(state.home.footerLinks[0].label, 'Server Footer');
-    assert.strictEqual(state.theme.accent, '#999999');
-    assert.strictEqual(state.theme.navBg, '#222222');
-    assert.strictEqual(state.typeColors.ADVERT, '#ff00ff');
-    assert.strictEqual(state.typeColors.REQUEST, '#aa00aa');
+    ctx.CustomEvent = function (type) { this.type = type; };
+    const v2 = loadCustomizeV2(ctx);
+    const valid = v2.validateShape({ theme: { accent: '#ff0000', navBg: '#222222' } });
+    assert.strictEqual(valid.valid, true);
+    const invalid = v2.validateShape({ theme: { accent: '#ff0000', navBg: 'not-a-color' } });
+    assert.ok(invalid.errors.length > 0, 'should report invalid color');
+    assert.ok(invalid.errors[0].includes('navBg'), 'error should mention navBg');
   });
 
-  test('full localStorage values override server config', () => {
+  test('migrateOldKeys reads legacy localStorage keys', () => {
     const ctx = makeSandbox();
-    ctx.window.SITE_CONFIG = {
-      home: {
-        heroTitle: 'Server Hero',
-        heroSubtitle: 'Server Subtitle',
-        steps: [{ emoji: 'S', title: 'Server Step', description: 'server' }],
-        checklist: [{ question: 'Server Q', answer: 'Server A' }],
-        footerLinks: [{ label: 'Server Link', url: '#/server' }]
-      },
-      theme: { accent: '#101010' }
-    };
-    ctx.localStorage.setItem('meshcore-user-theme', JSON.stringify({
-      home: {
-        heroTitle: 'Local Hero',
-        heroSubtitle: 'Local Subtitle',
-        steps: [{ emoji: 'L', title: 'Local Step', description: 'local' }],
-        checklist: [{ question: 'Local Q', answer: 'Local A' }],
-        footerLinks: [{ label: 'Local Link', url: '#/local' }]
-      },
-      theme: { accent: '#abcdef', navBg: '#fedcba' }
-    }));
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    const state = ex.getState();
-    assert.strictEqual(state.home.heroTitle, 'Local Hero');
-    assert.strictEqual(state.home.heroSubtitle, 'Local Subtitle');
-    assert.strictEqual(state.home.steps[0].title, 'Local Step');
-    assert.strictEqual(state.home.checklist[0].question, 'Local Q');
-    assert.strictEqual(state.home.footerLinks[0].label, 'Local Link');
-    assert.strictEqual(state.theme.accent, '#abcdef');
-    assert.strictEqual(state.theme.navBg, '#fedcba');
+    ctx.CustomEvent = function (type) { this.type = type; };
+    ctx.localStorage.setItem('meshcore-theme', 'dark');
+    const v2 = loadCustomizeV2(ctx);
+    // migrateOldKeys should handle legacy keys without crashing
+    v2.migrateOldKeys();
   });
 
-  test('initState uses _SITE_CONFIG_ORIGINAL_HOME to bypass contaminated SITE_CONFIG.home', () => {
-    // Simulates: app.js called mergeUserHomeConfig which mutated SITE_CONFIG.home.steps = []
-    // The original server steps must still be recoverable via _SITE_CONFIG_ORIGINAL_HOME
+  test('THEME_CSS_MAP includes surface3 and sectionBg', () => {
     const ctx = makeSandbox();
-    ctx.setTimeout = function (fn) { fn(); return 1; };
-    ctx.clearTimeout = function () {};
-    // SITE_CONFIG.home is contaminated — steps wiped by mergeUserHomeConfig at page load
-    ctx.window.SITE_CONFIG = {
-      home: {
-        heroTitle: 'Server Hero',
-        steps: []   // contaminated — user had steps:[] in localStorage at page load
-      }
-    };
-    // app.js snapshots original before mutation
-    ctx.window._SITE_CONFIG_ORIGINAL_HOME = {
-      heroTitle: 'Server Hero',
-      steps: [{ emoji: '🧪', title: 'Original Step', description: 'from server' }]
-    };
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    const state = ex.getState();
-    assert.strictEqual(state.home.steps.length, 1, 'should restore from snapshot, not contaminated SITE_CONFIG');
-    assert.strictEqual(state.home.steps[0].title, 'Original Step');
-  });
-
-  test('initState uses DEFAULTS.home when no SITE_CONFIG and no snapshot', () => {
-    const ctx = makeSandbox();
-    ctx.setTimeout = function (fn) { fn(); return 1; };
-    ctx.clearTimeout = function () {};
-    // No SITE_CONFIG at all — pure DEFAULTS
-    const ex = loadCustomizeExports(ctx);
-    ex.initState();
-    const state = ex.getState();
-    assert.ok(state.home.steps.length > 0, 'should use DEFAULTS.home.steps when no server config');
-    assert.strictEqual(state.home.steps[0].title, 'Join the Bay Area MeshCore Discord');
+    ctx.CustomEvent = function (type) { this.type = type; };
+    const src = fs.readFileSync('public/customize-v2.js', 'utf8');
+    assert.ok(src.includes("surface3: '--surface-3'"), 'surface3 must map to --surface-3');
+    assert.ok(src.includes("sectionBg: '--section-bg'"), 'sectionBg must map to --section-bg');
   });
 }
 
-// ===== APP.JS: home rehydration merge =====
-console.log('\n=== app.js: home rehydration merge ===');
-{
-  test('mergeUserHomeConfig layers local home overrides on server home', () => {
-    const ctx = makeSandbox();
-    loadInCtx(ctx, 'public/roles.js');
-    loadInCtx(ctx, 'public/app.js');
-    const merged = ctx.mergeUserHomeConfig(
-      {
-        home: {
-          heroTitle: 'Server Hero',
-          heroSubtitle: 'Server Subtitle',
-          steps: [{ title: 'Server Step' }],
-          footerLinks: [{ label: 'Server Link' }]
-        }
-      },
-      {
-        home: {
-          heroSubtitle: 'Local Subtitle',
-          checklist: [{ question: 'Local Q', answer: 'Local A' }]
-        }
-      }
-    );
-    assert.strictEqual(merged.home.heroTitle, 'Server Hero');
-    assert.strictEqual(merged.home.heroSubtitle, 'Local Subtitle');
-    assert.strictEqual(merged.home.steps[0].title, 'Server Step');
-    assert.strictEqual(merged.home.footerLinks[0].label, 'Server Link');
-    assert.strictEqual(merged.home.checklist[0].question, 'Local Q');
-  });
-
-  test('mergeUserHomeConfig handles refresh-style localStorage payload', () => {
-    const ctx = makeSandbox();
-    loadInCtx(ctx, 'public/roles.js');
-    loadInCtx(ctx, 'public/app.js');
-    ctx.localStorage.setItem('meshcore-user-theme', JSON.stringify({
-      home: { heroTitle: 'Local Hero' }
-    }));
-    const cfg = {
-      home: {
-        heroTitle: 'Server Hero',
-        heroSubtitle: 'Server Subtitle',
-        steps: [{ title: 'Server Step' }]
-      }
-    };
-    const userTheme = JSON.parse(ctx.localStorage.getItem('meshcore-user-theme') || '{}');
-    const merged = ctx.mergeUserHomeConfig(cfg, userTheme);
-    assert.strictEqual(merged.home.heroTitle, 'Local Hero');
-    assert.strictEqual(merged.home.heroSubtitle, 'Server Subtitle');
-    assert.strictEqual(merged.home.steps[0].title, 'Server Step');
-  });
-}
+// ===== APP.JS: home rehydration merge (mergeUserHomeConfig removed — dead code) =====
 
 // ===== CHANNELS.JS: WS Region Filter helper =====
 console.log('\n=== channels.js: shouldProcessWSMessageForRegion ===');
@@ -4098,40 +3922,7 @@ console.log('\n=== app.js: debounce ===');
   });
 }
 
-// ===== APP.JS: mergeUserHomeConfig edge cases =====
-console.log('\n=== app.js: mergeUserHomeConfig edge cases ===');
-{
-  const ctx = makeSandbox();
-  loadInCtx(ctx, 'public/roles.js');
-  loadInCtx(ctx, 'public/app.js');
-  const merge = ctx.mergeUserHomeConfig;
-
-  test('returns siteConfig when userTheme is null', () => {
-    const cfg = { home: { heroTitle: 'Test' } };
-    assert.strictEqual(merge(cfg, null), cfg);
-  });
-
-  test('returns siteConfig when userTheme has no home', () => {
-    const cfg = { home: { heroTitle: 'Test' } };
-    assert.strictEqual(merge(cfg, { theme: {} }), cfg);
-  });
-
-  test('returns siteConfig when siteConfig is null', () => {
-    assert.strictEqual(merge(null, { home: { heroTitle: 'X' } }), null);
-  });
-
-  test('creates home on siteConfig when missing', () => {
-    const cfg = {};
-    merge(cfg, { home: { heroTitle: 'New' } });
-    assert.strictEqual(cfg.home.heroTitle, 'New');
-  });
-
-  test('userTheme.home non-object is ignored', () => {
-    const cfg = { home: { heroTitle: 'Test' } };
-    assert.strictEqual(merge(cfg, { home: 'string' }), cfg);
-    assert.strictEqual(cfg.home.heroTitle, 'Test');
-  });
-}
+// ===== APP.JS: mergeUserHomeConfig removed (dead code) =====
 
 // ===== APP.JS: formatAbsoluteTimestamp with custom format =====
 console.log('\n=== app.js: formatAbsoluteTimestamp (custom format) ===');