Offline Basemaps and PMTiles

"/home/yossef/notes/git/projects/maplibra/modules/Offline Basemaps and PMTiles.md"

path: maplibra/modules/Offline Basemaps and PMTiles.md

- **fileName**: Offline Basemaps and PMTiles
- **Created on**: 2026-06-16 00:48:42

Offline Basemaps and PMTiles

Purpose: Offline basemap configuration, PMTiles protocol, and remote basemap policy.

Migrated from: obs_vault

What It Does

The app supports offline basemap tiles via PMTiles protocol. When running in Android WebView or offline mode, the app uses locally-served tile sets instead of remote Mapbox styles.

PMTiles Protocol

PMTiles is a cloud-optimized archival format for map tiles. The app registers a custom protocol handler via mapRuntime.initBasemapProtocol() that intercepts tile requests and serves them from the PMTiles archive.

Remote Basemap Policy

src/app/offline-config.js controls whether remote basemap tiles are allowed:

shouldAllowNetworkRouting() — checks if network routing APIs are available
offlineBasemapConfig.prefetchIndoorTiles — triggers indoor tile prefetching after first floor render
Android host detection (appassets.androidplatform.net) affects basemap style selection

Offline Style Resolution

When offline or in Android host mode:

resolveMapStyle() prefers local PMTiles/JSON styles over remote Mapbox URLs
window.__INGUIDE_BASEMAP_STYLE__ is set by the Android host for style control
Static offline JSON files can drift from dynamically generated styles (see ../risks/Offline Basemap Theme Drift.md)

Important Files

src/app/offline-config.js
src/app/basemap-style.js
src/app/offline-basemap.js
src/app/map-runtime.js

How It Connects

bootstrapShell registers the service worker for offline caching
script.js calls mapRuntime.initBasemapProtocol() when the style is offline
bootstrapMap creates the map with the resolved style
Android bridge sets window.__INGUIDE_BASEMAP_STYLE__ for host-controlled styling
Theme changes re-resolve the basemap style

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