"/home/yossef/notes/git/projects/maplibra/flows/Asset Loading.md"

path: maplibra/flows/Asset Loading.md

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

Asset Loading

Purpose: How the app resolves file paths across ZIP, network, overlay, and cached sources.

Related: ../Home.md, ../Architecture.md, ../modules/Asset System.md, ../modules/MVF Loading.md, ../modules/Pathfinding.md

Provider Hierarchy

The app creates a chain of asset providers depending on the startup mode:

File Upload Mode

ZIP Provider (mvfLoader.zip)
  → Overlay Provider (derived assets)
    → PathfindingController.assetProvider

URL Mode

ZIP Provider (mvfLoader.zip)
  + Network Provider (/assets)
    → Hybrid Provider
      → Overlay Provider (derived assets)
        → PathfindingController.assetProvider

Asset Root Mode

Network Provider (/assets)
  → PathfindingController.assetProvider

Cache Restore Mode

Network Provider (/assets)
  → Overlay Provider (cached derived assets)
    → PathfindingController.assetProvider

Provider Resolution Order

When a file is requested (e.g., routing/graph.json):

1. Overlay Provider — check in-memory overrides first
2. ZIP Provider — check the ZIP bundle
3. Network Provider — fetch from server
4. Return null if all fail

ZIP Provider Details

• Uses JSZip instance
• Supports multiple root paths (bundle root + assets/ subdirectories)
• Caches JSON and text up to 32 entries
• Provides getText, getJson, getBlob, getBuffer, getObjectUrl
• revokeAll() cleans up object URLs

Network Provider Details

• Builds URLs as /${root}/${path}
• Uses fetch with optional AbortSignal
• No internal caching (relies on HTTP cache)

Overlay Provider Details

• Wraps a base provider with a Map of overrides
• Override values can be json, text, blob, or buffer
• Used to inject runtime-generated assets (e.g., computed routing graphs)
• Does not modify the underlying ZIP or network data

Important Files

• src/app/asset-provider.js — All provider implementations
• script.js — Provider chain construction (createHybridAssetProvider)
• src/app/derived-asset-cache.js — IndexedDB caching

How It Connects

• PathfindingController uses assetProvider to load routing graphs, walkable areas, entrance nodes

• LayerManager uses asset provider to load debug node GeoJSON and icon SVGs

• script.js rebuilds the provider chain when derived assets are attached

• OverlayProvider is the mechanism for attaching runtime-built routing graphs

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