"/home/yossef/notes/git/projects/maplibra/modules/Asset System.md"

path: maplibra/modules/Asset System.md

- **fileName**: Asset System
- **Created on**: 2026-06-16 00:48:42

Asset System

Purpose: Normalizes file access across ZIP bundles, generated overlays, network assets, and cached data.

Related: ../Home.md, ../Architecture.md, ./MVF Loading.md, ./Map Rendering.md, ./Pathfinding.md

What It Does

The asset system provides a unified interface for reading files from multiple sources. It supports ZIP bundles, network HTTP, in-memory overlays, hybrid combinations, and IndexedDB caching.

Asset Provider Types

1. ZIP Asset Provider (createZipAssetProvider)

• Reads from a JSZip instance
• Supports multiple root paths (e.g., bundleRoot, bundleRoot/assets)
• Caches JSON and text up to 32 entries
• Provides getText, getJson, getBlob, getBuffer, getObjectUrl

2. Network Asset Provider (createNetworkAssetProvider)

• Reads from a server path via fetch
• No caching (relies on browser/network cache)
• Same interface as ZIP provider

3. Overlay Asset Provider (createOverlayAssetProvider)

• Wraps a base provider with in-memory overrides
• Used to inject derived assets (routing graphs, debug nodes) without writing files
• Supports json, text, blob, buffer overrides

4. Hybrid Provider (createHybridAssetProvider in script.js)

• Combines ZIP provider + network provider
• Tries ZIP first, falls back to network
• Used for URL-loaded bundles that may reference additional server assets

Derived Asset Cache

src/app/derived-asset-cache.js stores pre-built routing graphs and debug assets in IndexedDB:

• Cache key: derived-v2:<SHA-256>:<optionsKey>
• Meta index: localStorage side index for fast lookup by file name, size, or offline package ID
• Serialization: JSON objects and ArrayBuffers are stored; Maps are serialized to plain objects
• Schema versioning: CACHED_MVF_SCHEMA_VERSION prevents stale cache reads

Cache Lookup Flow

1. Check localStorage meta index by file name/size/package ID
2. If miss, scan IndexedDB entries and refresh the index
3. Verify schema version matches current app version
4. Deserialize assets (JSON + ArrayBuffers)

Important Files

• src/app/asset-provider.js — ZIP, network, overlay providers
• src/app/derived-asset-cache.js — IndexedDB cache, meta index, hashing
• src/app/derived-asset-builder.js — Build routing graphs from MVF data
• src/app/startup-derived-assets.js — Select cached vs bundled assets at startup
• src/app/startup-routing-assets.js — Build missing routing assets after map load

How It Connects

• Asset providers feed data to LayerManager (styles, geometry), PathfindingController (graphs, walkable areas), and debug layers

• Derived asset cache avoids re-building routing graphs on every map open

• Overlay provider lets runtime-generated assets (e.g., computed routes) be read like static files

• Hybrid provider enables offline-first bundles with network fallback for missing files

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