freemap-v3-react: Instructions file for Codex

Project notes for AI agents

(This file is also exposed as CLAUDE.md via a symlink so Claude Code loads it.)

Reference docs

Deeper format/architecture references live in doc/. Consult them before designing changes in the same area:

• Architecture & code-layout reference — the feature-folder convention, the Redux store wiring (rootReducer.ts / processors.ts), the processor middleware that owns all side effects, state persistence + rehydration, URL-hash sync, the global vs. per-feature i18n split, path aliases, and the layer/tool registries. Read this before adding a feature, a side effect, persisted state, or a new menu/tool/modal — it saves re-reading the tree.
• Translation style — how each language addresses the user: formal everywhere it distinguishes (vykanie, Sie, vous, Lei, önözés, vikanje), neutral Polish, neutral wording preferred, and the exceptions for button labels and search keywords. Read this before writing or translating any UI string.
• Drawing feature export/import format mapping — GPX/GeoJSON write+read for drawing points/lines/polygons, the fm:* lossless-shadow design, and the curated Garmin/OsmAnd icon dictionaries. Read this before changing anything in src/features/export/ or in the drawing-conversion processors.
• Track data: import, elevation, colorize, export — the shared elevation-acquisition layer (src/shared/elevation.ts: fetchElevations/enrichElevations/densifyAlong), the shared colorizers (src/shared/colorizers/, isAvailable-gated per feature), the render-only densified geometry that's never exported, the per-consumer elevation policy (route auto-fill vs. track prompt vs. tracking keep-recorded), and KML/KMZ/TCX import + lossless GeoJSON↔GPX transfer. Read this before touching elevation, colorize, the elevation chart, or track-file import/export across routePlanner/dataViewer/tracking/mapFeaturesExport.
• What a history entry shows — how src/app/url/entryContent.ts puts an entry's features back from link params, a snapshot, a track-uid=/import-url= download or a saved map: reads tagged with the entry that asked and joined when already in flight, the entry's own content over the map's, remote tracks imported and then dropped from the URL, and entryLoading() holding back every writer. Read this before touching restore on reload or Back/Forward, mapsRestoreProcessor, or trackStore.ts.
• GPS recorder integration — how the PWA drives the standalone Android recorder APK over its 127.0.0.1 HTTP API: the Android-only availability gate, the loopback/Local-Network-Access connection rules, the wire contract (protocol.ts is the single place to change it), the start-via-intent:// flow, how the three failure causes are told apart, and the /track?since= + SSE catch-up. Read this before touching src/features/gpsRecorder/ or anything that talks to the recorder.
• Panorama viewer — the 360° terrain view: why the terrain service is addressed directly (it takes the bearer token, but bounds only what one request may cost — the client is what holds an account to its tier), why a render is only ever started by an explicit act and must abort the one in flight, the split between the store and renderHolder, the off-thread decode and the canvas the picture is panned on, the label layout, and how a second label source plugs in via the distance buffer. Read this before touching src/features/panorama/.
• Viewshed overlay — the v layer over the terrain service's POST /viewshed: why it is a layer with a toolbar rather than a tool, the radius/scale pair the service validates together, what its alpha means, the render key that decides when Update appears, and the shared render queue. Read this before touching src/features/viewshed/.
• Weather radar layer — the animated R overlay over the two-feed cache.bigware.sk API: why every request must set its own referrerPolicy (the upstream authenticates by Referer, and the app is served no-referrer), the wire contract and per-feed zoom bands, the premium bands on the timeline and why locked frames stay on the track, the transient/persisted slice split, the polling processor's deliberate exceptions, and the per-frame tile-layer pool with its cross-fade and pan-drop rules. Read this before touching src/features/weatherRadar/ or the radar layer's tile source.
• Tile attribution — what the outdoor map credits, decided by the tiles rather than by the countries in view: the dataset codes and the two ways they arrive (Server-Timing: attr for a tile on screen, since an <img> yields no response; X-Attribution for anything holding one, such as the offline downloader), the two gates — Timing-Allow-Origin and Access-Control-Expose-Headers — and how either one missing looks exactly like a tile reporting nothing, the painted-tile union and the three Leaflet traps in it, /licenses as the authority for what a code means, what is credited when no codes arrive, and the rules that keep an offline map's stored union honest. Read this before touching src/shared/tileAttribution.ts, tileLicenses.ts, Attribution.tsx, exportCredits.ts, or the code capture in cacheTilesProcessor.ts.
• WebMCP agent tools — the tools src/features/webMcp/ registers on document.modelContext so a browser AI agent can drive the running app through the store: the API shape and its traps (it is document, not navigator; secure context; the tools permissions policy), the lazy registration from index.tsx, defineTool's zod → JSON Schema wrapping, and waitForState for the two tools that must await a processor's answer. Read this before adding or changing an agent tool.
• SEO bot-prerender architecture — how crawlers get static HTML snapshots while humans get the SPA: the sitemap-generator/ (homepages, layer/tool hub pages, per-feature POI pages), the nginx /__prerender routing, and the rspack index-<lang> variants. Read this before changing sitemap-generator/, the sitemap/robots wiring, or the bot routing in the nginx vhost.
• Self-hosted Photon geocoder — the search backend on fm5 that replaces nominatim.openstreetmap.org: why the prebuilt photon-db-* tarballs are unusable (four languages only) and we import the JSONL dump ourselves, the -languages set and why widening it costs a re-import, the install layout, the systemd unit and nginx vhost (rate limit, 24 h cache, gzip_types), and the import/re-import runbook. Read this before touching the geocoder host, re-importing a dump, or pointing search at Photon.
• Map library — every non-custom map is a library entry the user installs: the decisions (installed controls only what the UI offers, ids stable forever, library maps are not custom maps), the split registry (src/shared/mapLibrary/mapIndex.tsx + one body file per map in defs/, bundled vs lazily loaded bodies, the mapLibrary slice and which selector to read), open questions, next steps (library modal, coverage union, harvesting) and the catalog research (ELI, JOSM, QMS, licences). Read this before touching layer definitions, how they load, install state, or the library.
• Build & deploy gotchas — the DEPLOYMENT env var (not --mode) selects the prod build, native CSS nesting must be downleveled via LightningCSS, JS built-ins are core-js-polyfilled per use, and the nginx cache-header rules (entry HTML no-store, only hashed assets immutable). Read this before changing rspack.config.ts, the CSS pipeline, or the nginx vhosts.
• React Compiler — the app is compiled with the React Compiler (jsc.transform.reactCompiler in rspack.config.ts): why ESLint exists here only for its diagnostics and parses with Babel rather than typescript-eslint, why the bail-out is per function (so manual memoization must stay wherever the compiler skips), the three ways it has actually broken this app (a render-time read of Leaflet/DOM/module state gets frozen, state that only forces a re-render stops working, a binding shadowing an intrinsic tag renames the tag), and scripts/react-compiler-check.mjs, which catches what reading the source cannot. Read this before removing a useMemo/useCallback, adding 'use no memo', or debugging a component that renders stale values.
• Events UX plan — where the events feature (branch events, both repos) is heading and the steps to get there: an event is viewed in an event mode of its own, never loaded into the user's map; the read-only map rendering it rests on; participants, follows, discussion. Read this before working on src/features/events/, and tick its steps as they land.
• UI conventions — what each react-bootstrap button variant means by role (dark = dismiss/close, primary = main CTA, secondary = default neutral action, danger = destructive, outline-primary = toggle, warning = upsell). Read this before picking a variant for a new <Button>.
• User manual — the in-app manual's chapters (src/manual/, English fallback, #show=manual/<chapter>), how to write them (UI labels verbatim, formal address, no emoji), the :FaIcon: syntax and the rule to show the UI's own glyph, the screenshot script (scripts/manual-screenshots.mjs: 2× capture, 8 px map margin, manifest sizes, the 820 px full screen), and moving a document into the manual. Read this before writing or changing a manual chapter or its screenshots.
• Feature-announcement log — what has shipped and is worth posting about (with the commits that carry it), and what has already gone out on Facebook / Mastodon. Update the backlog when a user-visible feature lands, and move a topic to Posted once it goes out. Market-intro posts live in the roadmap's Outreach log instead.
• Product reality & market position — what Freemap actually is, written from the code rather than from marketing copy: exact coverage (46 countries; the 33 national high-res terrain datasets — per territory, so Germany counts as its 16 states — and the big markets without), the feature inventory, the business model (€15/yr, self-served ads shown to non-premium users, no user tracking), honest strengths and weaknesses (no mobile app, no community tour content), the competitor table with prices, and the positioning that follows. Read this before writing any promotional copy or choosing a market, and verify load-bearing claims against the code it cites.
• Italy outreach working file — the live state of the Italian push: venue research (which communities already know Freemap and must never be "introduced" again vs. which are cold), the finished Italian post drafts, forum-account status and blockers, and a "start here" handoff list. Read this before doing anything on Italy; log posted outcomes to the roadmap's Outreach log.
• Austria outreach working file — the German-language push: why Austria goes first (engagement and reusable copy — the terrain hook now covers all of Germany too), the gipfeltreffen.at warm channel and its three-year-old unanswered objection, the German post draft, and venue/registration state. Read this before working on AT/DE/CH.
• Foreign-growth promotion roadmap — data-driven plan (from Matomo country/language/referrer cuts) for growing usage and premium conversions outside Slovakia: which markets to target (Italy, Poland, Hungary, Austria, …), which UI languages to add next (Slovenian, then French), and the phased outreach steps. Read this before working on foreign promotion, deciding the next UI localization, or interpreting the audience analytics.