"/home/yossef/notes/git/projects/maplibra/risks/Offline Packaging Risks.md"

path: maplibra/risks/Offline Packaging Risks.md

- **fileName**: Offline Packaging Risks
- **Created on**: 2026-06-16 00:48:42

Offline Packaging Risks

Purpose: Offline-specific bugs and drift points for packaged maps.

Related: ../Home.md, ./Risk Map.md, ../modules/Service Worker and Offline.md, ../modules/Android Bridge.md, ../decisions/Caching Strategy.md

Migrated from: obs_vault

Key Risks

• Incomplete precache — offline-assets.json can drift from the actual build output, causing missing files offline
• Manifest drift — service worker manifest not updated after build changes
• sw.js alignment — service worker file and registration version can diverge
• Opportunistic cache writes — runtime cache entries may conflict with manifest entries; write-back failures can go unnoticed
• Host rule alignment — src/app/service-worker.js and public/sw.js must stay aligned on host rules or Android app-assets behavior becomes confusing
• Manifest identity — the service worker cache is versioned, but the manifest content itself has no visible package identity, so drift can be subtle
• Packaged map routing failure — a package can open but still fail to route if derived assets are incomplete

Common Failure Modes

1. Package opens but routing fails → derived assets missing or stale
2. Offline basemap blank → PMTiles URL wrong or tiles not cached
3. Theme drift in offline → static JSON style vs dynamic style mismatch (see ./Offline Basemap Theme Drift.md)
4. Cache clear doesn't fully reset → service worker still serves stale data

Debugging

1. Check offline-assets.json matches the build output
2. Verify sw.js install handler caches the right files
3. Test with ?clear to force a clean state
4. Check IndexedDB for stale derived asset entries
5. Verify CACHED_MVF_SCHEMA_VERSION matches current app version

Important Files

• src/app/offline-config.js

• src/app/service-worker.js

• public/sw.js

• docs/offline-packaging.md

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