"/home/yossef/notes/git/projects/maplibra/risks/Host Mode Style Resolution.md"

path: maplibra/risks/Host Mode Style Resolution.md

- **fileName**: Host Mode Style Resolution
- **Created on**: 2026-06-16 00:48:42

Host Mode Style Resolution

Migrated from: obs_vault

Parent: ./Theme Risk Index.md

Severity: high for offline or Android deployments.

Summary

resolveMapStyle() can choose remote Mapbox or OSM network styles in host modes where the product may expect bundled PMTiles. Token presence, PMTiles flags, and runtime overrides are split across multiple checks, which makes offline behavior fragile.

Code Evidence

• theme.js: lines 47-55 choose Mapbox styles on appassets.androidplatform.net whenever a token is configured, before checking local PMTiles.
• theme.js: lines 21-35 only detect local PMTiles from window.__INGUIDE_HAS_LOCAL_PMTILES__ or ?hasPmtiles=1.
• src/app/offline-config.js: lines 27-45 allow PMTiles URLs through __INGUIDE_BASEMAP_PM__, __INGUIDE_BASEMAP_PM_FULL__, or config defaults, but those do not automatically make hasLocalPmtiles() true.
• tests/theme-host-mode.test.js: lines 24-28 currently assert that Android host prefers online Mapbox styles over bundled PMTiles when a token exists.

Trigger Conditions

• Android WebView or appassets.androidplatform.net host.
• window.__MAPBOX_TOKEN__ or mapboxgl.accessToken is present.
• Local PMTiles exist, but remote network is unavailable or intentionally disabled.
• PMTiles URL is injected without also setting __INGUIDE_HAS_LOCAL_PMTILES__.

Likely Symptoms

• Offline Android app tries to load mapbox://styles/mapbox/....
• Basemap is blank when network is unavailable.
• OSM raster fallback is selected even when PMTiles URL is configured.
• Same package behaves differently depending on token injection.

Why It Matters

Offline behavior should not silently depend on whether a token exists. Token presence is not the same as permission or ability to use remote basemaps.

Current Tests

• tests/theme-host-mode.test.js covers the current remote-preferred behavior on Android host.
• tests/basemap-style.test.js only covers the network fallback style structure.

Missing Tests

• appassets host with token local PMTiles and remote disabled uses offline style.
• appassets host recognizes __INGUIDE_BASEMAP_PM__ as local PMTiles availability.
• no PMTiles protocol and no Mapbox token uses fallback background style.
• remote basemap is only selected when explicit remote permission exists.

How To Make Better

• Prefer local PMTiles on app-assets hosts unless __INGUIDE_ALLOW_REMOTE_BASEMAP__ === true.
• Treat explicit PMTiles URLs as local basemap availability.
• Derive local availability from getBasemapPmtilesUrl() instead of a separate boolean when possible.
• If PMTiles protocol is unsupported and remote is not allowed, return createFallbackBasemapStyle() instead of Mapbox URL.
• If remote is allowed but no Mapbox token exists, use createNetworkBasemapStyle() instead of Mapbox URL.

Debug Steps

1. Log host, token presence, hasPmtiles, __INGUIDE_BASEMAP_PM__, and __INGUIDE_ALLOW_REMOTE_BASEMAP__.
2. Call resolveMapStyle('dark') and inspect whether it returns Mapbox URL, static JSON, dynamic offline style, or network raster style.
3. Confirm whether the chosen style can load without network.

See Also

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

• ./Offline Packaging Risks.md

• ./Offline Basemap Theme Drift.md

• ./Theme Tests and Fix Plan.md

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