stikart CLAUDE.md

Stikart

Interactive map for Norwegian trail running and ultra race routes. Deployed at stikart.no via GitHub Pages.

Running locally

python3 server.py
# Open http://localhost:8000/index.html

The Python server is needed to avoid CORS errors when fetching local GPX files.

Integration tests

Playwright end-to-end tests in tests/ — the only npm usage in the repo (dev-only; the app itself still has no build step).

npm install && npx playwright install chromium   # one-time setup
npm test            # run all tests (starts server.py automatically)
npm run test:ui     # interactive UI mode
npx playwright test --project=mobile             # mobile only

• Two projects: desktop (Desktop Chrome) and mobile (Pixel 7 emulation — touch events + coarse pointer, so isTouchDevice/isMobile code paths run)
• tests/fixtures.js blocks analytics and serves blank map tiles (offline-safe), and has helpers: touchScrub (real CDP touch events for chart finger-scrubbing), expandPanel, openRaceDeepLink
• Tests reference the races nsm-ultra-2025 and lommedalen-rundt (TEST_RACE/DESCRIBED_RACE in fixtures) — update fixtures if those entries are ever removed
• Covered: race list/search, race selection + map highlight/dim, elevation chart mouse hover and touch scrub (cursor, km marker, freeze/lock), mobile welcome screen, minimized detail card, deep links

Tech stack

• Vanilla JS, HTML, CSS — no build step, no framework, no npm
• Leaflet.js 1.9.4 for the map
• leaflet-polylinedecorator for route arrows
• Kartverket (Norgeskart) and OpenStreetMap as base layers
• GoatCounter for privacy-friendly analytics

File structure

File	Purpose
js/config.js	Constants: WORKER_URL, isTouchDevice, darkColorPool, raceCategories
js/races.js	raceRoutes data array — one entry per race
js/utils.js	Pure utility functions: slugify, formatDate, haversineKm, fmtTime, fmtPace, etc.
js/map.js	Leaflet map init, tile layers, icons, layer state, loadRace/loadRaces, highlightRace, resetRaceStyles, regenerateColors, race picker popup, custom layer control
js/filters.js	Filter state and functions: applyFilters, filterByMonth, filterByCategory, filterBySearch, clearSearch
js/elevation.js	buildElevationProfile, renderElevationChart, updateElevCursor
js/cursor.js	Shared cursor state (dotFrozen, chartTouchMarker), enableDistanceDot/disableDistanceDot, enableChartMouse/enableChartTouch, minimizeDetail/expandDetail
js/pace-planner.js	Pace math (gradeFactor, fatiguedArrival, calcCheckpointSplits), renderPacePlanner, openPacePlanner/closePacePlanner/updatePacePlanner, zoomToCheckpoint
js/race-panel.js	Race list panel, race detail overlay, selectRace, showRaceDetailOverlay, closeRaceDetail, shareRace, changeRaceColor; extends applyFilters and regenerateColors
js/submission.js	Race submit/edit form: showSubmitRaceForm, openEditRaceForm, handleRaceSubmit, parseGPXForStats
js/main.js	Entry point: showInfoOverlay, downloadGpx, startup sequence (regenerateColors, URL params, initial loadRace/loadRaces)
gpx-parser.js	Parses GPX XML → GeoJSON; Haversine distance + elevation gain; extracts <wpt> waypoints
index.html	Shell: map div, filter bar, panels, overlays
style.css	All styles
server.py	Local dev server
worker.js	Cloudflare Worker — handles race submission/edit PRs server-side (holds GitHub PAT)
wrangler.toml	Cloudflare Worker config
race-calendar/	GPX files, one folder per race
.github/workflows/validate-race.yml	CI: validates GPX and auto-merges valid race PRs