TrixandOpenCode a0b4e6cf5f fix(nodes): light-mode map follows tile picks, key and theme changes (#1470/#1420) (#2386)
fix(nodes): light-mode map follows tile picks, key and theme changes
(#1470/#1420)

## Problem

The node-detail maps (`#/nodes/<pubkey>` full page + side pane — and
their
reusers `node-reach-map.js`, `rx-coverage.js`) pick a different basemap
in
**light mode** than the rest of the app:

- hardcode Carto Positron: the user's *Light Mode Provider* customizer
pick
  and the operator's `map.tiles.lightDefault` are ignored
- render Carto's `API KEY REQUIRED` watermark when `/api/config/client`
lands after the map is created — the tile requests stay keyless until a
  remount (they come back HTTP 200, so nothing surfaces as an error)
- never react to a theme flip or provider change while the page is open

Dark mode is unaffected, which is why it only shows up in light mode.

Reproduce on `master`: open `#/nodes/<id>` in light mode with
`mc-light-tile-provider = carto-voyager` — the inset requests
`light_all`
while the main map requests `rastertiles/voyager`.

## Root cause

`_applyTilesToNodeMap` (`public/nodes.js`) asked `window.getTileUrl()`
for a
single URL string, and roles.js's light branch returned the frozen
`TILE_LIGHT` scalar — the dark branch was the only one that consulted
the
runtime registry (`public/map-tile-providers.js`), which is what owns
localStorage picks, server defaults, the Carto key, and per-provider
attribution/maxZoom/refUrl/invertFilter. map.js and live.js keep the
only
other registry-aware resolvers of the same logic.

## What this PR does

- adds one resolver, `MC_resolveTile(isDark)`, in map-tile-providers.js,
  returning the full descriptor
  `{ type, id, url, attribution, maxZoom, refUrl, invertFilter }`:
  - `url` is always a resolved string — function-typed providers are
    invoked at call time (contract of #1614)
  - one precedence rule everywhere: explicit operator overrides
    (`cfg.tiles.dark|light`, `map.tiles.darkUrl|lightUrl`, tracked via
    `MC_LEGACY_TILE_OVERRIDE`) > user/server registry pick >
    `TILE_DARK`/`TILE_LIGHT` constants — **this is a deliberate behavior
    change on map.js/live.js, see below**
- fully lazy: registry rebuilds / pick changes are picked up by the next
    resolve, so config landing after page load fixes itself
- roles.js `getTileUrl()` becomes a thin wrapper over it; the public API
and
the #1614 sandbox contract are unchanged; `getActiveTileProvider()`
keeps
  its documented null-in-light contract
- `nodes.js _applyTilesToNodeMap` resolves through the descriptor and
stays
reactive: one shared `mc-tile-provider-changed` listener + one
`data-theme`
MutationObserver re-sync every registered map in place — old layers
removed
before the new ones are added, never stacked; maps whose container left
the
  DOM are pruned at sync time, so SPA navigation cannot leak listeners
- map.js `_resolveTileUrl` / live.js `_liveResolveTile` delegate to the
  shared resolver (their legacy bodies remain only as sandbox fallbacks)
- provider `maxZoom` replaces the hardcoded 18/19 caps (OpenTopoMap 17
and
  USGS 16 used to 404 above their max zoom)
- analytics.js subpath minimap gets provider `maxZoom` as well

## Behavior change (deliberate): operator URL overrides now win on every
surface

On `master`, the two tile-selection mechanisms conflicted and each
surface
resolved the conflict differently:

- `map.js` / `live.js`: user/server **registry pick won** — an
operator's
  `tiles.dark|light` / `map.tiles.darkUrl|lightUrl` was effectively dead
  config on those pages
- the legacy roles.js path (nodes page, reach map, rx-coverage,
analytics
  minimap): **operator override won**

This PR unifies on **operator-override-wins**, because that is the only
reading that gives live operator config a consistent meaning:

- these keys are still applied today. The deprecation warning says they
  would "be ignored in v3.5.0", and v3.5.0 shipped 2026-04-08 — the
instance line is now at v3.16.0 and the keys still take effect, so they
  are live configuration, not dead letters. An explicit operator pin
  should not be silently defeated by a per-user pick on some pages and
honored on others; whichever way the mechanism eventually goes, it must
  behave identically everywhere until it is actually removed.
- user choice is not reduced in the general case: picks remain
  authoritative for every provider the registry offers, and overrides
  only exist where an operator explicitly wrote a literal URL.

If maintainers would rather have pick-wins (operator URL acts only as a
fallback default), flipping the precedence in `MC_resolveTile` is a
small,
well-tested change — say so in review and it will be reworked.

Related cleanup, out of scope here: the stale "ignored in v3.5.0"
deprecation warning in `cmd/server/config.go` should either be honored
or
reworded now that the project is past v3.16.0.

## No change without operator overrides or picks

## Verification

Unit (all deterministic, `vm`-sandbox based):

- new `tests/unit/test-tile-resolver.js` — 22 cases: light/dark pick
honored,
operator `lightDefault`, disabled-provider fallback, override
precedence,
lazy function-URLs, key-after-async-config, in-place swap without
stacking,
  detached-map prune, multi-map single-listener sync, provider maxZoom;
  listed in `test-all.sh`
- existing suites green: `test-issue-1420-tile-providers` (47),
`test-issue-1470-node-tile-helper` (6),
`test-issue-1614-tile-url-function`
  (3), `test-frontend-helpers` (79), `test-settings-sync`,
  `test-packet-filter` (105), `test-aging`
- every one of the 227 suites listed in `test-all.sh`, run individually:
  all green except `test-manage-workflow` (2 failures that are local-env
only — CRLF bootstrap artifact — and pass in CI; `sh test-all.sh` aborts
  there locally under `set -e`, which is why the suites were run one by
  one this time; the scripted pipeline runs fully in CI)
- `eslint` on all six touched files: 0 errors

Browser (headless Chromium against this branch, `/api/config/client`
delayed
~800 ms to force the config race):

- light + `/#/nodes/<key>`: 12 keyless tile requests before config, 12
keyed
  re-requests after — no reload, no stacked layer
- light pick `carto-voyager`: inset requests `rastertiles/voyager` from
the
  start (parity with the main map)
- theme flip on an open node page: `dark_all` swaps in in place
- dark defaults unchanged (`dark_all`, keyed after config)

The Playwright E2E suite was not run locally — no Go toolchain on the
workstation to serve the backend — CI will cover it.

## Scope / follow-ups (intentionally not here)

- `home.js` mini-map (OSM only) and the geo-filter mini-maps in the
customizers are untouched on purpose: they are outside this bug's path,
  and migrating them to `MC_resolveTile` later is mechanical

## Performance

Not a hot path: one registry lookup + string build per map creation and
per
provider/theme-change event (each is rare); no per-packet or per-render
work;
the listener footprint is O(1) app-wide (single shared listener pair + a
pruned registry), so there is no growth across SPA navigations.

Co-authored-by: OpenCode <git-llm@trix.moe>
Co-authored-by: OpenCode:GLM-5.3-Flash <git-llm@trix.moe>
Assisted-by: OpenCode:GLM-5.3-Flash eslint

---------

Co-authored-by: OpenCode <git-llm@trix.moe>
2026-11-11 18:22:42 +01:00
2026-04-05 06:36:03 +00:00
2026-03-20 05:38:23 +00:00

CoreScope

Go Server Coverage Go Ingestor Coverage E2E Tests Frontend Coverage Deploy

High-performance mesh network analyzer powered by Go. Sub-millisecond packet queries, ~300 MB memory for 56K+ packets, real-time WebSocket broadcast, full channel decryption.

Self-hosted, open-source MeshCore packet analyzer. Collects MeshCore packets via MQTT, decodes them in real time, and presents a full web UI with live packet feed, interactive maps, channel chat, packet tracing, and per-node analytics.

⚡ Performance

The Go backend serves its packet and analytics API from an in-memory packet store with 7 indexes (hash, txID, obsID, observer, node, path hop, payload type). SQLite is for persistence only — reads never touch disk.

Metric Value
Packet queries < 1 ms (in-memory)
All API endpoints < 100 ms
Memory (56K packets) ~300 MB (vs 1.3 GB on Node.js)
WebSocket broadcast Real-time to all connected browsers
Channel decryption AES-128-ECB with rainbow table
GOMEMLIMIT (memory-constrained hosts) set to ≥1.5× working set (e.g. 1536 MiB on a 2 GB Pi for a ~1 GB store). Lower values trigger a GC death-spiral. Configure via the GOMEMLIMIT env var or runtime.maxMemoryMB in config.json; env wins. Applies to both server and ingestor. See #1010.

See PERFORMANCE.md for full benchmarks.

✨ Features

📡 Live Trace Map

Real-time animated map with packet route visualization, VCR-style playback controls, and a retro LCD clock. Replay the last 24 hours of mesh activity, scrub through the timeline, or watch packets flow live at up to 8× speed.

Live VCR playback — watch packets flow across the Bay Area mesh

📦 Packet Feed

Filterable real-time packet stream with byte-level breakdown, Excel-like resizable columns, and a detail pane. Toggle "My Nodes" to focus on your mesh.

Packets view

🗺️ Network Overview

At-a-glance mesh stats — node counts, packet volume, observer coverage.

Network overview

📊 Node Analytics

Per-node deep dive with interactive charts: activity timeline, packet type breakdown, SNR distribution, hop count analysis, peer network graph, and hourly heatmap.

Node analytics

💬 Channel Chat

Decoded group messages with sender names, @mentions, timestamps — like reading a Discord channel for your mesh.

Channels

📱 Mobile Ready

Full experience on your phone — proper touch controls, iOS safe area support, and a compact VCR bar.

Live view on iOS

And More

  • 17 Analytics Tabs — RF, topology, channels, hash stats, distance, route patterns, scopes, and more
  • Node Directory — searchable list with role tabs, detail panel, QR codes, advert timeline
  • Packet Tracing — follow individual packets across observers with SNR/RSSI timeline
  • Observer Status — health monitoring, packet counts, uptime, per-observer analytics
  • Hash Collision Matrix — detect address collisions across the mesh
  • Scope Audit: per repeater, which declared regions show no forwarding and which scopes it forwards without declaring them
  • Channel Key Auto-Derivation — hashtag channels (#channel) keys derived via SHA256
  • Multi-Broker MQTT — connect to multiple brokers with per-source IATA filtering
  • Dark / Light Mode — auto-detects system preference, map tiles swap too
  • Theme Customizer — design your theme in-browser, export as theme.json
  • Global Search — search packets, nodes, and channels (Ctrl+K)
  • Shareable URLs — deep links to packets, channels, and observer detail pages
  • Protobuf API Contract — typed API definitions in proto/
  • Accessible — ARIA patterns, keyboard navigation, screen reader support

Optional Features

Off by default, enabled in config.json:

  • User Accounts: registration with email activation, settings sync, an admin area, hashtag channel proposals, mail notifications for watched nodes, and a personal data export. The dashboard stays public. See docs/user-guide/accounts.md
  • Mobile RX Coverage: crowdsourced coverage from phones connected to a companion radio, drawn as hex bins on the RX Coverage page and on each node's Reach page. See docs/client-rx-coverage.md

Quick Start

No build step required — just run:

docker run -d --name corescope \
  --restart=unless-stopped \
  -p 80:80 -p 1883:1883 \
  -v /your/data:/app/data \
  ghcr.io/kpa-clawbot/corescope:latest

Open http://localhost — done. No config file needed; CoreScope starts with sensible defaults.

For HTTPS with a custom domain, add -p 443:443 and mount your Caddyfile:

docker run -d --name corescope \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 -p 1883:1883 \
  -v /your/data:/app/data \
  -v /your/Caddyfile:/etc/caddy/Caddyfile:ro \
  -v /your/caddy-data:/data/caddy \
  ghcr.io/kpa-clawbot/corescope:latest

Disable built-in services with -e DISABLE_MOSQUITTO=true or -e DISABLE_CADDY=true, or drop a .env file in your data volume. See docs/deployment.md for the full reference.

Build from Source

git clone https://github.com/Kpa-clawbot/CoreScope.git
cd CoreScope
./manage.sh setup

The setup wizard walks you through config, domain, HTTPS, build, and run.

./manage.sh status       # Health check + packet/node counts
./manage.sh logs         # Follow logs
./manage.sh backup       # Backup database
./manage.sh update       # Pull latest + rebuild + restart
./manage.sh mqtt-test    # Check if observer data is flowing
./manage.sh help         # All commands

Configure

Copy config.example.json to config.json and edit:

{
  "port": 3000,
  "mqtt": {
    "broker": "mqtt://localhost:1883",
    "topic": "meshcore/+/+/packets"
  },
  "mqttSources": [
    {
      "name": "remote-feed",
      "broker": "mqtts://remote-broker:8883",
      "topics": ["meshcore/+/+/packets"],
      "username": "user",
      "password": "pass",
      "iataFilter": ["SJC", "SFO", "OAK"]
    }
  ],
  "channelKeys": {
    "public": "8b3387e9c5cdea6ac9e5edbaa115cd72"
  },
  "defaultRegion": "SJC"
}
Field Description
port HTTP server port (default: 3000)
mqtt.broker Local MQTT broker URL ("" to disable)
mqttSources External MQTT broker connections (optional)
channelKeys Channel decryption keys (hex). Hashtag channels auto-derived via SHA256
defaultRegion Default IATA region code for the UI
dbPath SQLite database path (default: data/meshcore.db)

Environment Variables

Variable Description
DB_PATH Override SQLite database path
GOMEMLIMIT Go soft memory limit, wins over runtime.maxMemoryMB

The HTTP port is set with port in config.json or the server's -port flag.

Architecture

                           ┌─────────────────────────────────────────────┐
                           │              Docker Container               │
                           │                                             │
Observer → USB →           │  Mosquitto ──→ Go Ingestor ──→ SQLite DB   │
  meshcoretomqtt → MQTT ──→│                    │                        │
                           │              Go HTTP Server ──→ WebSocket   │
                           │                    │               │        │
                           │              Caddy (HTTPS) ←───────┘        │
                           └────────────────────┼────────────────────────┘
                                                │
                                             Browser

Two-process model: The Go ingestor handles MQTT ingestion and packet decoding. The Go HTTP server loads all packets into an in-memory store on startup (5 indexes for fast lookups) and serves the REST API + WebSocket broadcast. Both are managed by supervisord inside a single container with Caddy for HTTPS and Mosquitto for local MQTT.

MQTT Setup

  1. Flash an observer node with MESH_PACKET_LOGGING=1 build flag
  2. Connect via USB to a host running meshcoretomqtt
  3. Configure meshcoretomqtt with your IATA region code and MQTT broker address
  4. Packets appear on topic meshcore/{IATA}/{PUBKEY}/packets

To decode a single raw hex packet without storing it, use POST /api/decode.

Project Structure

corescope/
├── cmd/
│   ├── server/              # Go HTTP server + WebSocket + REST API
│   │   ├── main.go          # Entry point
│   │   ├── routes.go        # 40+ API endpoint handlers
│   │   ├── store.go         # In-memory packet store (5 indexes)
│   │   ├── db.go            # SQLite persistence layer
│   │   ├── decoder.go       # MeshCore packet decoder
│   │   ├── websocket.go     # WebSocket broadcast
│   │   └── *_test.go        # Server tests
│   └── ingestor/            # Go MQTT ingestor
│       ├── main.go          # MQTT subscription + packet processing
│       ├── decoder.go       # Packet decoder (shared logic)
│       ├── db.go            # SQLite write path
│       └── *_test.go        # Ingestor tests
├── proto/                   # Protobuf API definitions
├── public/                  # Vanilla JS frontend (no build step)
│   ├── index.html           # SPA shell
│   ├── app.js               # Router, WebSocket, utilities
│   ├── packets.js           # Packet feed + hex breakdown
│   ├── map.js               # Leaflet map + route visualization
│   ├── live.js              # Live trace + VCR playback
│   ├── channels.js          # Channel chat
│   ├── nodes.js             # Node directory + detail views
│   ├── analytics.js         # Analytics dashboard
│   └── style.css            # CSS variable theming (light/dark)
├── docker/
│   ├── supervisord-go.conf  # Process manager (server + ingestor)
│   ├── mosquitto.conf       # MQTT broker config
│   ├── Caddyfile            # Reverse proxy + HTTPS
│   └── entrypoint-go.sh     # Container entrypoint
├── Dockerfile               # Multi-stage Go build + Alpine runtime
├── config.example.json      # Example configuration
├── tests/                   # Node.js test suite: unit/ (test-all.sh) and e2e/ (Playwright)
├── test-all.sh              # Runs every suite in tests/unit
└── tools/                   # Generators, E2E tests, utilities

For Developers

Building

make build        # all four binaries for your machine, into dist/
make build-server # just one
make crossbuild   # static linux/amd64 + linux/arm64 binaries

The SQLite driver is mattn/go-sqlite3, which is cgo, so a plain GOOS=linux go build from a Mac will not work: cross-compiling needs a C compiler that can target the other platform. make crossbuild uses zig as that compiler (install it and it just works) and links statically against musl, so the result is one self-contained file that runs on Alpine or scratch. The container build does the same thing — see Dockerfile.

Test Suite

Go tests cover the backend, Node.js unit tests in tests/unit/ cover the frontend logic, and Playwright tests in tests/e2e/ validate the UI in a browser.

# Go backend tests
cd cmd/server && go test ./... -v
cd cmd/ingestor && go test ./... -v

# Or across all 16 modules at once
make test

# Node.js frontend + integration tests
npm test

# Playwright E2E (requires running server on localhost:3000)
node tests/e2e/test-e2e-playwright.js

Generate Test Data

node tools/generate-packets.js --api --count 200

Migrating from Node.js

If you're running an existing Node.js deployment, see docs/go-migration.md for a step-by-step guide. The Go engine reads the same SQLite database and config.json — no data migration needed.

Contributing

Contributions welcome. Please read AGENTS.md for coding conventions, testing requirements, and engineering principles before submitting a PR.

Live instance: analyzer.on8ar.eu: all read endpoints are public, no auth required.

API Documentation: CoreScope auto-generates an OpenAPI 3.0 spec. Browse the interactive Swagger UI at /api/docs or fetch the machine-readable spec at /api/spec.

License

GPL-3.0-or-later

S
Description
No description provided
Readme GPL-3.0
139 MiB
0 Stars 1 Watchers 0 Forks
Languages
JavaScript 49.1%
Go 45.7%
CSS 2.8%
Shell 1.5%
HTML 0.5%
Other 0.2%