Deferred Bootstrap

"/home/yossef/notes/git/projects/maplibra/decisions/Deferred Bootstrap.md"

path: maplibra/decisions/Deferred Bootstrap.md

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

Purpose: Why routing, search, and debug layers load lazily after the first floor render.

Decision

Load heavy subsystems (routing controller, search box, debug layers) only after the map is interactive and the first floor is rendered.

Time-to-first-render is the critical metric for user perception. The map should be visible within seconds.
Routing graph loading can take 1-3 seconds for large buildings. Blocking startup on this would make the app feel slow.
Search box is not needed immediately — users typically look at the map first.
Debug layers are developer-only and should never affect production startup.
Network variability — outdoor routing APIs may be slow or unavailable; deferring prevents timeout anxiety.

bootstrap-routing.js uses dynamic import() to lazy-load pathfinding-controller.js
bootstrap-search.js uses dynamic import() to lazy-load SearchBox.js
bootstrap-debug.js uses dynamic import() to lazy-load debug layer modules
script.js queues post-render tasks via scheduleStartupTask() with idle scheduling
PathfindingController is only initialized when the user first interacts with routing (clicks map, searches, etc.)

Pro: Faster startup, better perceived performance, lower initial bundle size
Con: First route computation may have a slight delay if the routing graph is still loading
Mitigation: warmGraphResources() preloads the graph in the background after idle

Phase 5+ of the product hardening effort. The deferred bootstrap pattern was added to support large buildings with heavy routing graphs.