- State tracking (.setup-state) — resume from where you left off
- Every step checks what's already done and skips it
- Safe to Ctrl+C and re-run at any point
- Auto-generates random API key on first config creation
- HTTPS choice menu: domain (auto), Cloudflare/proxy (HTTP), or later
- DNS validation with IP comparison
- Port 80 conflict detection
- Status shows packet/node counts, DB size, per-service health
- Backup auto-creates ./backups/ dir, restore backs up current first
- Reset command (keeps data + config, removes container + image)
- .setup-state in .gitignore
- Added HTTPS Options section: auto (Caddy), bring your own cert,
Cloudflare Tunnel, behind existing proxy, HTTP-only
- Expanded MQTT Security into its own section with 3 options + recommendation
- Fixed DB backup to use volume path not docker cp
- Added restore instructions
- Expanded troubleshooting table (rate limits → use own cert or different subdomain)
- Clarified that MQTT 1883 is NOT exposed by default in quick start
- Added tip to save docker run as a script
- Restructured for cleaner TOC
- Removed condescension, kept clarity
Added: what is Docker, how to install it, what is a server,
where to get a domain, how to open ports. Every command explained.
Assumes zero DevOps knowledge.
Step-by-step for users with limited DevOps experience. Covers:
- Quick start (5 minutes to running)
- Connecting observers (public broker vs your own)
- Common gotchas: port 80 for ACME, MQTT security, DB backups,
DNS before container, read-only config, skip internal HTTPS
- Customization and branding
- Troubleshooting table
- Architecture diagram
- server.js disambiguateHops() now delegates to server-helpers.js
(was a full copy of the same algorithm, ~70 lines removed)
- live.js resolveHopPositions() now delegates to shared HopResolver
(was a standalone reimplementation, ~50 lines removed)
- HopResolver.init() called when live page loads/updates node data
- Net -106 lines, same behavior, single source of truth
All unit tests pass (241). E2E 13/16 (3 pre-existing Chromium crashes).
Test-First, YAGNI, Refactor Mercilessly, Simple Design,
Pair Programming (subagent→review→push), CI as gate not cleanup,
10-Minute Build, Collective Code Ownership, Small Releases.
Each with concrete examples from today's failures.
DRY, SOLID, code reuse, dependency injection, testability,
type safety, performance. These were being violated repeatedly
(5 implementations of disambiguation, .toFixed on strings, etc).
Now explicitly codified as rules.
zoomend handler was gated on filters.hashLabels — decollision only
re-ran on zoom when hash labels were enabled. Now always re-renders
markers on zoom so pixel offsets stay correct at every zoom level.
Added map.on('resize') handler that re-renders markers, recalculating
pixel-based decollision offsets for the new container size. Previously
only zoomend triggered re-render — resize left stale offsets.
Added E2E test verifying markers survive a viewport resize.
Visual step-by-step showing why two passes are needed — forward
pass can't resolve hops at the start of the path, backward pass
catches them by anchoring from the right.
Comprehensive documentation of how MeshCore Analyzer resolves
truncated hash prefixes (1-3 bytes) to node identities across
the entire codebase. Covers firmware encoding, server-side
disambiguation (3 implementations), client-side HopResolver,
live feed's independent implementation, and consistency analysis.
Notable findings:
- /api/resolve-hops has regional filtering that disambiguateHops() lacks
- live.js reimplements disambiguation independently without HopResolver
- Inline resolveHop() in analytics resolves hops without path context
- These are not bugs but worth knowing about for future refactoring
On SPA navigation, the map container may not have its final dimensions
when markers render, causing latLngToLayerPoint to return incorrect
pixel coordinates for decollision. This resulted in overlapping markers
that only resolved on a full page refresh.
Fix: call map.invalidateSize() at the start of every renderMarkers()
call, ensuring correct container dimensions before deconfliction runs.
6 tests covering string, number, null, negative, and integer
values through the Number(x).toFixed() pattern used across
observer-detail, home, traces, and live pages.
Observer detail, home health timeline, and traces all called
.toFixed() on snr/rssi values that may be strings from the DB.
Wrapping in Number() matches what live.js already does.
Root cause: addFeedItem had no dedup logic — each WS message created
a new feed entry regardless of hash. Dedup only worked when the
'Realistic propagation' toggle was ON (which buffers by hash before
calling animateRealisticPropagation). Default mode called animatePacket
directly for every observation, producing duplicate feed entries.
Fix: Added feedHashMap (hash -> {element, count, pkt, addedAt}) that
tracks recent feed items by packet hash. When a packet with a known
hash arrives within 30s, the existing feed item is updated in-place:
- Observation count badge incremented
- Item flashed and moved to top of feed
- No duplicate DOM element created
Also adds data-hash attribute to feed items for testability.
Tests: 5 new Playwright tests in test-live-dedup.js covering:
- Same hash different observers → single entry
- Different hashes → separate entries
- 5 rapid sequential duplicates → single entry with count 5
- Same hash same observer → still deduplicates
- Packets without hash → not deduplicated
- Live page showHeatMap() now reads meshcore-live-heatmap-opacity from
localStorage and applies it to the canvas element (was hardcoded 0.3)
- Customizer now has two clearly labeled sliders:
🗺️ Nodes Map — controls the static map page heatmap
📡 Live Map — controls the live page heatmap
- Each uses its own localStorage key (meshcore-heatmap-opacity vs
meshcore-live-heatmap-opacity)
- Added E2E tests for live opacity persistence and dual slider existence
- 13/15 E2E tests pass locally (2 fail due to ARM chromium OOM after
heavy live page tests — CI on x64 will handle them)
Closes#119 properly this time.
Recover from stale localStorage state where heat checkbox stayed
disabled even after matrix/ghosts mode was turned off. Explicitly
sets ht.disabled = false in the else branch of matrix init.
13/13 E2E tests pass locally.
Live page liveHeatToggle now saves to localStorage (meshcore-live-heatmap).
Map page was already fixed but live page was missed.
Added E2E test that verifies persistence across reload.
13/13 E2E tests pass locally.
When new data arrived, toggleHeatmap() destroyed and recreated the
heat layer, causing a brief flash at full opacity before the CSS
opacity was applied via setTimeout. Now reuses the existing layer
via setLatLngs() for data updates, and hooks the 'add' event for
immediate opacity on first creation. No more flash.
All 12 E2E tests pass locally.
- Heat checkbox persists in localStorage across reload
- Heat checkbox is clickable (not disabled)
- Live page heat disabled when ghosts/matrix mode active
- Heatmap opacity value persists and applies to canvas
4 new tests, all verified locally before push.
The previous implementation used L.heatLayer's minOpacity which only
controlled the opacity of the coolest (blue) gradient stops. Now sets
CSS opacity on the canvas element directly, affecting all gradient
colors uniformly. Closes#119 properly.
Backend-only change: ~1 min (unit tests, skip Playwright/coverage)
Frontend-only change: ~2-5 min (E2E + coverage, skip backend suite)
Both changed: full suite (~14 min)
CI/test infra changed: full suite (safety net)
Detects changed files via git diff HEAD~1, runs appropriate suite.
The page.evaluate() calls corrupting localStorage and firing fake events
caused page error-reloads, losing accumulated coverage. Reverting to
the 42% version which was the actual high water mark.
- Full test file list with all 12+ test files
- Feature development workflow: write code → write tests → run locally → push
- Playwright defaults to localhost:3000, NEVER prod
- Coverage infrastructure explained (Istanbul instrument → Playwright → nyc)
- ARM testing notes (basic tests work, heavy coverage use CI)
- 4 new pitfalls from today's session
Exercise every major code path across all frontend files:
app.js: all routes, bad routes, hashchange, theme toggle x4,
hamburger menu, favorites dropdown, global search, Ctrl+K,
apiPerf(), timeAgo/truncate/routeTypeName utils
nodes.js: sort every column (both directions), every role tab,
every status filter, cycle all Last Heard options, click rows
for side pane, navigate to detail page, copy URL, show all
paths, node analytics day buttons (1/7/30/365), scroll target
packets.js: 12 filter expressions including bad ones, cycle all
time windows, group by hash toggle, My Nodes toggle, observer
menu, type filter menu, hash input, node filter, observer sort,
column toggle menu, hex hash toggle, pause button, resize handle,
deep-link to packet hash
map.js: all role checkboxes toggle, clusters/heatmap/neighbors/
hash labels toggles, cycle Last Heard, status filter buttons,
jump buttons, markers, zoom controls, dark mode tile swap
analytics.js: all 9 tabs clicked, deep-link to each tab via URL,
observer selector on topology, navigate rows on collisions/
subpaths, sortable headers on nodes tab, region filter
customize.js: all 5 tabs, all preset themes, branding text inputs,
theme color inputs, node color inputs, type color inputs, reset
buttons, home tab fields (hero, journey steps, checklist, links),
export tab, reset preview/user theme
live.js: VCR pause/speed/missed/prompt buttons, all visualization
toggles (heat/ghost/realistic/favorites/matrix/rain), audio
toggle + BPM slider, timeline click, resize event
channels.js: click rows, navigate to specific channel
observers.js: click rows, navigate to detail, cycle days select
traces.js: click rows
perf.js: refresh + reset buttons
home.js: both chooser paths, search + suggest, my-node cards,
health/packets buttons, remove buttons, toggle level, timeline
Also exercises packet-filter parser and region-filter directly.
