Lumen/SPIKE-03-MAP-REPRESENTATION.md

SPIKE-03 — Map Representation

• Phase: Architecture Validation
• Date: 2026-08-30
• Decision under test: ADR-008 (raster WebP base ≤2 levels + DOM POI overlay + CSS-transform pan/zoom + Facilities list; no online tiles; no GPS).
• Method: structured evaluation against all candidate representations; decode-memory analysis; headless synthetic benchmark (experiments/exp3-map-bench.html) with strict interpretation limits.

1. Candidates

	S1 Single SVG map	S2 Raster base + DOM overlay (proposed)	S3 Canvas	S4 Pre-cached raster tile pyramid	S5 Hybrid vector-POI over raster (variant of S2)
Offline completeness	Yes	Yes	Yes	Yes	Yes
Organizer workflow	Needs vector art skills; illustrated maps are raster	Art as-is (illustrated PNG/WebP)	Same as S2	Same as S2	Same as S2
Low-end pan/zoom	Degrades with path count	GPU transform of 1 image — cheap, constant	Full redraw per frame	Tile management code	Same as S2
Accessibility	Awkward at scale	POIs are real buttons; list view first-class	Needs parallel text tree	Same as S3	Same as S2
Zoom quality	Infinite	Bounded by 2 levels (venue-scale adequate)	Same as S2	Good	Same as S2
File size	Art-dependent	WebP excellent for illustrated art	Same	+ overhead per tile	Same
POI interaction	DOM/SVG events	DOM buttons (48 px targets trivial)	Manual hit-testing	Same as S3	Same as S2
Search / dynamic filtering	Possible	Trivial (data-driven markers, class toggles)	Manual	Manual	Trivial
Dark mode	Styleable	Needs dimming strategy (see §4)	Manual	Manual	Same as S2
Maintainability / update flow	Re-export vector	Replace image + POI sheet → new package	Same as S2	Same	Same
Code surface	Medium	Low	Higher	Highest	Low

2. Benchmark evidence (EXP-3) and its limits

Headless desktop run (see experiments/README.md for caveats): all three mechanically viable variants (S2, S1, S3) measured ≈ 0 ms synchronous JS per animation frame at 100 and 300 POIs.

Interpretation (deliberately conservative): desktop JS cost does not discriminate the candidates. The costs that matter on low-end mobile — GPU compositing of transformed layers, texture upload of large images, decode latency, RAM pressure — are invisible to this benchmark. Therefore EXP-3 confirms only: (a) no candidate has a disqualifying JS-side cost; (b) the DOM-overlay and SVG transform mechanics work as designed. The final choice rests on memory, accessibility, workflow, and robustness reasoning below, with a mandatory device protocol in §7.

3. Memory analysis (the decisive axis on mobile)

Decoded image cost ≈ width × height × 4 bytes (RGBA):

Base image	Encoded (WebP, illustrated art)	Decoded in RAM
1600×1200 (overview cap)	~0.3–0.7 MB	~7.3 MB
2048×1536	~0.5–1.2 MB	~12 MB
3072×2304 (detail cap)	~1.5–3.5 MB	~27 MB
4096×3072 (previous cap)	~2.5–6 MB	~48 MB
4096×4096	—	~64 MB

Findings:

• F-1 (change): ARCH §15.3's "≤ 4096 px per side" cap was chosen for GPU texture limits but is insufficient as a memory constraint. On a 3–4 GB low-end Android, holding a 48–64 MB decoded bitmap alongside the app, list caches, and browser overhead is a jetsam/OOM risk. New caps: overview ≤ 1600 px longest edge; detail ≤ 3072 px longest edge; total decoded map memory ≤ ~35 MB; at most one detail-level image resident (overview is swapped out or downscaled when detail is shown). Some older GPUs cap textures at 2048 px; Chromium tiles oversized textures internally (works, at a cost) — the 3072 cap plus an overview-only fallback mode covers this.
• F-2: WebP encoded sizes at these dimensions fit the 28 MB asset budget with margin, including per-POI icons.
• F-3: IDs/object URLs: create object URLs lazily per visible level; revoke on level switch to free decode memory.

4. Criteria-by-criteria results for the chosen representation

• Initial load: overview WebP (~0.5 MB) + map.json renders the usable map immediately; detail level lazy-loads on zoom-in. CONFIRMED by design.
• Zoom/pan: single-container CSS transform; markers counter-scaled. Mechanics CONFIRMED viable by EXP-3; fps on device UNVERIFIED (§7).
• Retina/high-density: base authored at ~2× intended display size; downscale-on-fit keeps quality. INFERRED.
• Accessibility / screen readers: POIs are real DOM buttons with labels; Facilities list is a first-class, non-visual equivalent (not a fallback). Base image carries descriptive alt. CONFIRMED by design.
• POI interaction: tap → detail sheet; 48 px targets. CONFIRMED by design.
• Search: shared search component indexes POI names/categories; results highlight markers + list entries. CONFIRMED by design.
• Dynamic filtering: category chips toggle marker visibility (data-driven, class/attribute toggles; no re-layout of the base). CONFIRMED by design.
• Dark mode (F-4, change): festival art is typically day-illustrated. Default: CSS filter: brightness(.72) saturate(.85) on the base image in dark theme + full-brightness markers/labels (cheap, GPU-composited). Optional: organizer-supplied night-variant asset (schema hook: asset role map-base/overview-night). No white flash, no re-download required.
• Organizer workflow: illustrated art delivered as raster + POI coordinate capture step (tap-tool over the image in pipeline tooling, or surveyed normalized coordinates). Map update = new package version; no app change. INFERRED — needs confirmation with real art (OQ-6, AQ-19).
• Offline use: all bytes local; no tile service, no GPS. CONFIRMED.

5. When the decision would flip

• Organizers supply vector art (SVG) of good quality → reconsider S1/S5 (crisp zoom, smaller files) — SPIKE verdict remains valid either way because POI overlay + list view are representation-agnostic.
• Real art exceeds 3072 px requirement for legibility → tile-split the detail level (2×2), still local; bounded extra complexity (DD-9).
• Device protocol (§7) shows transform jank on the low-end Android target → fallback: overview-only mode + reduced marker count; canvas remains the escape hatch but is not preemptively adopted.

6. Cross-checks with other decisions

• ADR-004: assets as Blobs in the slot DB — consistent; object-URL lifecycle managed by MapService (F-3).
• SPIKE-05: map missing ⇒ PARTIAL with list still available if POI data present — consistent.
• ADR-012: POI optional lat/lng hook preserved; no GPS in V1 — consistent.

7. Mandatory physical-device protocol (before production)

On the low-end Android target and an iPhone:

1. Pan/zoom sustained 10 s at 60 Hz intent with 200 POIs → observe fps/frame drops (target ≥ 30 fps).
2. Detail-level first zoom-in: decode latency and memory peak (performance.memory on Chrome; Instruments on iOS).
3. Overview→detail→overview cycling: no leaked object URLs/memory growth.
4. Dark-mode filter visual quality + performance cost.
5. Screen-reader pass over POI markers and Facilities list (TalkBack, VoiceOver).
6. Older-GPU device (2048 texture cap) with a 3072 px detail image: renders correctly via Chromium tiling; measure cost; exercise overview-only fallback.

8. Verdict

ACCEPT WITH CHANGES.

Representation stands: raster WebP base (≤2 levels) + DOM POI overlay + CSS-transform pan/zoom + first-class Facilities list, no tiles, no GPS. Changes (to ADR-008): image dimension/memory caps tightened (F-1), object-URL lifecycle rule (F-3), dark-mode treatment (F-4), night-variant asset hook. Condition: device protocol §7 must pass before the map is declared production-ready; fallbacks are predefined.