From be48511f380f0bc55322cfc605adfe92894f2964 Mon Sep 17 00:00:00 2001 From: echo6-autocommit Date: Sat, 2 May 2026 00:00:04 +0000 Subject: [PATCH] auto: docs sync 2026-05-02T00:00:04+00:00 Files changed: docs/navi/cc-rules.md docs/navi/deployment.md docs/navi/themes.md --- docs/navi/cc-rules.md | 75 ++++++++++++++++++++++++++ docs/navi/deployment.md | 55 +++++++++++++++++++ docs/navi/themes.md | 115 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 245 insertions(+) create mode 100644 docs/navi/cc-rules.md create mode 100644 docs/navi/deployment.md create mode 100644 docs/navi/themes.md diff --git a/docs/navi/cc-rules.md b/docs/navi/cc-rules.md new file mode 100644 index 0000000..9344f12 --- /dev/null +++ b/docs/navi/cc-rules.md @@ -0,0 +1,75 @@ +# Navi: Claude Code Rules + +## Repository & SSH + +**All Navi SSH goes to:** `recon-vm` (VM 1130, 192.168.1.130) + +**Never SSH to cortex for Navi work.** Previous attempt to deploy from cortex wrecked production by deploying from a stale clone. + +**Work directory:** `/home/zvx/projects/repos/navi` on VM 1130 + +**Never touch:** `/home/zvx/projects/navi-work` on cortex (stale clone, do not use) + +## Critical Constraints + +- **Never re-export namedTheme** through any intermediary module — import directly from protomaps-themes-base in MapView.jsx +- **Never use `git add -A`** — stage files explicitly +- **Never deploy without smoke tests** — run full checklist (see deployment.md) +- **Never start preview servers** — deploy to production and test there + +## Build & Deploy + +```bash +ssh recon-vm +cd /home/zvx/projects/repos/navi +npm run build && rsync -av --delete dist/ /mnt/nav/frontend/ +``` + +## Git Workflow + +- Feature branches: name descriptively (theme-*, fix-*, feat-*) +- Always merge to master before deploying +- Check for unmerged commits: `git log branch..master --oneline` + +## Code Patterns + +### queryRenderedFeatures for Optional Layers + +Guard with map.getLayer() — USFS/BLM hit layers may not exist: + +```javascript +const layers = [USFS_TRAILS_HIT, USFS_ROADS_HIT].filter(id => map.getLayer(id)) +const features = layers.length > 0 + ? map.queryRenderedFeatures(e.point, { layers }) + : [] +``` + +### buildStyle Theme Colors + +```javascript +const theme = getTheme(themeName) +const colors = theme.colors || namedTheme(themeName) // direct import +``` + +### PlaceCard useEffect Changes + +Investigation-before-implementation — fragile race conditions between: +- Boundary fetch from Wikidata/OSM +- selectedPlace state updates +- AbortController cleanup + +## Architecture Notes + +- **Boundary highlight** is NOT an overlay toggle — it's a dynamic click-response layer +- **Route polyline** uses GeoJSON source.setData() — silent failure if namedTheme is re-exported +- **Measure tool** also uses GeoJSON — same failure mode + +## Smoke Test Checklist + +After every deploy: + +- [ ] Route between two addresses — polyline renders +- [ ] Click city label — boundary outline appears +- [ ] Theme switching (all 4 themes) +- [ ] Overlay toggles (hillshade, contours, public lands) +- [ ] Console: no "bt is not defined" or "f is not defined" diff --git a/docs/navi/deployment.md b/docs/navi/deployment.md new file mode 100644 index 0000000..a6142c1 --- /dev/null +++ b/docs/navi/deployment.md @@ -0,0 +1,55 @@ +# Navi Deployment + +## Source Repository + +**Location:** VM 1130 (`192.168.1.130`) at `/home/zvx/projects/repos/navi` + +> **WARNING:** Never deploy from `/home/zvx/projects/navi-work` on cortex — that clone is stale. + +## Build & Deploy + +```bash +# SSH to VM 1130 +ssh recon-vm + +# Always backup first +cp -r /mnt/nav/frontend /mnt/nav/frontend.bak.$(date +%Y%m%d-%H%M%S) + +# Build and deploy +cd /home/zvx/projects/repos/navi +npm run build && rsync -av --delete dist/ /mnt/nav/frontend/ +``` + +## Infrastructure + +- **Nginx** on VM 1130 serves `/mnt/nav/frontend/` on port 8440 + - `index.html`: no-cache (always fresh) + - Hashed assets (`*.js`, `*.css`): cache forever +- **Caddy** on CT 101 routes `navi.echo6.co` → VM 1130:8440 + +## Pre-Deploy Checklist + +1. Merge feature branch to master before deploying +2. Check for unmerged upstream commits: + ```bash + git log your-branch..master --oneline + ``` +3. Create backup (see above) + +## Post-Deploy Smoke Tests + +Run after **every** deploy: + +- [ ] Route between two addresses — polyline renders +- [ ] Click city label — boundary outline appears +- [ ] Theme switching works (dark, light, clean, cyberpunk) +- [ ] Toggle overlays (hillshade, contours, public lands) +- [ ] Console: no `bt is not defined` or `f is not defined` errors + +## Rollback + +```bash +# If deploy fails, restore backup +rm -rf /mnt/nav/frontend +mv /mnt/nav/frontend.bak.YYYYMMDD-HHMMSS /mnt/nav/frontend +``` diff --git a/docs/navi/themes.md b/docs/navi/themes.md new file mode 100644 index 0000000..3e43a78 --- /dev/null +++ b/docs/navi/themes.md @@ -0,0 +1,115 @@ +# Navi Theme System + +## Architecture + +**Registry:** `src/themes/registry.js` +Central source for theme metadata, overlay config, UI CSS vars, and satellite adjustments. + +## Critical: namedTheme Import + +> **NEVER re-export namedTheme through registry.js or any other module.** + +namedTheme must be imported **directly** from protomaps-themes-base in MapView.jsx: + +```javascript +// CORRECT +import { layers, namedTheme } from 'protomaps-themes-base' +import { getTheme, getThemeSprite, getOverlayConfig } from '../themes/registry' + +function buildStyle(themeName) { + const theme = getTheme(themeName) + const colors = theme.colors || namedTheme(themeName) // direct import for built-ins + return { + // ... + layers: layers('protomaps', colors, { lang: 'en' }), + } +} +``` + +**Why:** Vite's bundling of namedTheme through a re-export breaks MapLibre's Web Worker, causing silent GeoJSON rendering failure (routes, boundaries, measure tool all invisible, "f is not defined" error in worker). + +## Theme Config Shape + +```javascript +{ + id: 'dark', // unique identifier + name: 'Dark', // display name + dark: true, // affects overlay styling, sprite fallback + swatch: ['#1c1917', '#7a9a6b', '#b8a88a'], // theme picker preview + fontImports: [], // Google Font URLs (empty = system fonts) + colors: null, // null = built-in, object = custom theme colors + satellite: null, // raster adjustments when satellite active + overlay: { ... }, // per-layer styling for overlays + ui: { ... }, // 32 CSS custom properties +} +``` + +## UI CSS Variables + +Applied by applyThemeUI() via document.documentElement.style.setProperty(): + +- Backgrounds: --bg-base, --bg-raised, --bg-overlay, --bg-input, --bg-inset, --bg-muted +- Text: --text-primary, --text-secondary, --text-tertiary, --text-inverse +- Borders: --border, --border-subtle +- Accent: --accent, --accent-hover, --accent-muted +- Pins: --pin-origin, --pin-destination, --pin-intermediate, --pin-stroke +- Status: --status-success, --status-warning, --status-danger, --success, --warning, --warning-muted +- Fonts: --font-sans, --font-mono, --font-heading +- Shadows: --shadow, --shadow-lg + +## Overlay Config + +Read via getOverlayConfig(themeId, layerKey) with spread-defaults fallback: + +- hillshade: exaggeration, illuminationDirection, shadowColor, highlightColor +- contours: colors, opacities, widths for minor/intermediate/index lines + labels +- publicLands: fill/outline colors per agency (NPS, USFS, BLM, etc.) +- usfsTrails: road/trail colors by use type (motorized, bicycle, hiker) +- blmTrails: route colors by vehicle class (4WD, ATV, non-mechanized) + +## Satellite Raster Adjustments + +Neutral defaults (no adjustment): + +```javascript +satellite: { + opacity: 1.0, + brightnessMin: 0.0, + brightnessMax: 1.0, + contrast: 0.0, // MapLibre uses -1 to 1 range + saturation: 0.0, // MapLibre uses -1 to 1 range + hueRotate: 0, +} +``` + +## Font Support + +fontImports array of Google Font URLs, managed on theme switch: + +```javascript +fontImports: [ + 'https://fonts.googleapis.com/css2?family=Orbitron&display=swap', + 'https://fonts.googleapis.com/css2?family=Share+Tech+Mono&display=swap', +] +``` + +Injected as tags, removed on theme switch. + +## Theme Picker + +ThemePicker.jsx — swatch popover in header, reads themeList() for [{id, name, dark, swatch}]. + +## Current Themes + +| ID | Name | Type | Description | +|----|------|------|-------------| +| light | Light | built-in | Default light theme | +| dark | Dark | built-in | Default dark theme | +| clean | Clean | custom | Google Maps-inspired, utilitarian | +| cyberpunk | Cyberpunk | custom | Neon palette, Orbitron + Share Tech Mono fonts | + +## Adding a New Theme + +1. Create src/themes/{name}.js with full theme config +2. Import and register in registry.js themes object +3. Theme auto-appears in picker via themeList()