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

path: maplibra/modules/Bootstrap System.md

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

Bootstrap System

Purpose: Orchestrates startup from shell initialization through lazy feature loading.

Related: ../Home.md, ../Architecture.md, ./MVF Loading.md, ./Asset System.md, ../flows/Startup Sequence.md

What It Does

The bootstrap system is a staged pipeline that brings the app from an empty page to an interactive map while deferring heavy work. It is implemented across src/bootstrap/ and coordinated by script.js.

Bootstrap Stages

1. Shell Bootstrap (src/bootstrap/bootstrap-shell.js)

• Initializes theme (light/dark) and applies it to the document
• Sets up global error handling (ErrorHandler + ErrorToast)
• Registers service worker (production only)
• Fixes mobile viewport height (--app-height CSS variable)

2. Map Bootstrap (src/bootstrap/bootstrap-map.js)

• Creates the Mapbox GL map instance
• Creates LayerManager bound to the map
• Creates UIManager bound to map + layer manager

3. Data Bootstrap (src/bootstrap/bootstrap-data.js)

• Calls initApp() (the main app initialization in script.js)
• Stores the app handle for later startup phases
• Exposes attachDerivedAssets and primeMapExperience

4. Deferred Bootstraps

• Routing (src/bootstrap/bootstrap-routing.js): Lazy-loads PathfindingController only when needed
• Search (src/bootstrap/bootstrap-search.js): Lazy-loads SearchBox on first interaction
• Debug (src/bootstrap/bootstrap-debug.js): Lazy-loads debug layers when requested

App Context

src/bootstrap/create-app-context.js creates a shared context object passed through all stages:

• perf — startup performance marks and measures
• telemetry — rollout telemetry (opt-in)
• rollout — requested vs active routing engine and graph format
• flags — startup readiness state (routingReady, searchReady, debugReady)
• services — mutable registry of created instances (map, uiManager, layerManager, pathfindingController, searchBox)

Performance Budget

src/bootstrap/perf-budget.js defines startup time budgets and warns when exceeded.

Rollout Telemetry

src/bootstrap/rollout-telemetry.js provides a fire-and-forget telemetry sink for routing engine fallback and startup performance events. Delivery order: navigator.sendBeacon → fetch({ keepalive: true }) → silent drop.

Runtime Flags

src/bootstrap/runtime-flags.js parses URL query parameters for routing configuration:

• routing.engine=js|wasm
• graph.format=json|bin
• routing.telemetry=1|true
• routing.wasmParity=1|true
• routing.spatialKernel=1|true
• routing.spatialParity=1|true

Important Files

• src/bootstrap/bootstrap-shell.js
• src/bootstrap/bootstrap-map.js
• src/bootstrap/bootstrap-data.js
• src/bootstrap/bootstrap-routing.js
• src/bootstrap/bootstrap-search.js
• src/bootstrap/bootstrap-debug.js
• src/bootstrap/create-app-context.js
• src/bootstrap/startup-perf.js
• src/bootstrap/runtime-flags.js
• src/bootstrap/rollout-telemetry.js
• src/bootstrap/perf-budget.js

How It Connects

• Shell → Map → Data → Deferred (routing, search, debug)

• Each stage stores its output in appContext.services so later stages can read it

• script.js coordinates the entire flow and exposes the final window.InGuide API

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