"/home/yossef/notes/git/projects/maplibra/risks/Offline Basemap Theme Drift.md"

path: maplibra/risks/Offline Basemap Theme Drift.md

- **fileName**: Offline Basemap Theme Drift
- **Created on**: 2026-06-16 00:48:42

Offline Basemap Theme Drift

Migrated from: obs_vault

Parent: ./Theme Risk Index.md

Severity: medium-high.

Summary

The app has both dynamic offline style generation and static offline JSON files. The static files can drift from the dynamic builder and can ignore runtime choices such as light theme, full/campus mode, or custom PMTiles URLs.

Code Evidence

• src/app/basemap-style.js: lines 58-124 dynamically generate an offline vector style with isLight and runtime pmtilesUrl.
• public/assets/offline-style.json: static dark style points to pmtiles://assets/tiles/campus.pmtiles.
• public/assets/basemap-style.json: another static style can drift from the dynamic builder.
• theme.js: lines 51-52 return /assets/offline-style.json in Android host local-PMTiles mode.
• theme.js: lines 188-227 apply only partial layer repainting and do not repaint static land or park layers.

Trigger Conditions

• Android app-assets host with local PMTiles.
• User selects light theme while static offline style remains dark.
• Runtime wants full.pmtiles or custom PMTiles path.
• Dynamic createOfflineBasemapStyle() changes but static JSON is not regenerated.

Likely Symptoms

• Light theme still shows dark land/park layers.
• Static campus tiles load when full tiles were requested.
• Offline basemap looks different from the dynamic style path.
• Theme switch changes roads/background but leaves other vector layers dark.

Why It Matters

Static offline JSON is easy to forget. If it becomes a second source of truth, offline behavior can diverge from browser behavior and from tests that only cover the JS builder.

Current Tests

• tests/basemap-style.test.js covers only network raster fallback.
• No parity tests compare public/assets/offline-style.json with createOfflineBasemapStyle().

Missing Tests

• createOfflineBasemapStyle creates normalized pmtiles URL.
• createOfflineBasemapStyle uses light palette for land park water roads.
• static offline-style json matches dynamic dark campus style.
• applyThemeToMap updates offline land and park layers or style regeneration handles them.
• full basemap mode changes pmtiles URL in offline style.

How To Make Better

• Prefer dynamic createOfflineBasemapStyle({ pmtilesUrl, isLight }) when PMTiles protocol is available.
• If static JSON is required for WebView, generate it from the JS builder during build.
• Add separate static variants for light/dark and campus/full if static files remain necessary.
• Extend applyThemeToMap() to handle known offline vector layer IDs like land and park, or stop partial repainting and regenerate style on theme changes.

Debug Steps

1. Compare resolveMapStyle('light') result on Android host to browser host.
2. Inspect the active style source URL for campus.pmtiles vs full.pmtiles.
3. Inspect active paint colors for land, park, water, and roads after theme switch.
4. Compare static JSON with createOfflineBasemapStyle({ pmtilesUrl: '/assets/tiles/campus.pmtiles', isLight: false }).

See Also

• ../modules/Offline Basemaps and PMTiles.md

• ./Service Worker Risks.md

• ./Host Mode Style Resolution.md

• ./Theme Tests and Fix Plan.md

  continue:[[]]
  before:[[]]