"/home/yossef/notes/git/projects/maplibra/Home.md"

path: maplibra/Home.md

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

Home

Purpose: Entry point for understanding the MapLibre indoor navigation system.

Start Here

• ./Project Map.md
• ./Architecture.md
• ./Development Workflow.md
• ./Commands.md
• ./Testing.md
• ./Glossary.md

Main Areas

App Foundation

• ./modules/Bootstrap System.md — Startup orchestration, lazy loading, performance budgets
• ./modules/MVF Loading.md — ZIP bundle parsing, Web Worker, manifest processing
• ./modules/Asset System.md — Asset providers, derived asset cache, offline support
• ./modules/Layer Management.md — Map layers, visibility, debug overlays, theme switching
• ./modules/UI Components.md — Search, floor controls, theme, navigation panels
• ./modules/Android Bridge.md — WebView integration, native controls, floor state sync

Pathfinding & Routing

• ./modules/Pathfinding.md — A* search, graph structures, route computation
• ./modules/Route Smoothing.md — Shortcut smoothing, Bezier curves, human-like polylines
• ./modules/Snapping.md — Snap user clicks to graph nodes
• ./modules/Doors and Rooms.md — Door feature extraction, room containment
• ./modules/WASM Routing.md — JS-to-WASM bridge, C kernel
• ./modules/Outdoor Routing.md — Campus-scale indoor/outdoor route stitching
• ./modules/MVF Format.md — Bundle structure, debug node layers

Rendering & Data

• ./modules/Map Rendering.md — Floor data, fast render, prepared geometry
• ./modules/Path Renderer.md — Route line animation, layer rendering

Offline & Infrastructure

• ./modules/Offline Basemaps and PMTiles.md — PMTiles protocol, remote basemap policy
• ./modules/Service Worker and Offline.md — SW registration, offline manifest, pre-caching

Flows

• ./flows/Startup Sequence.md — Full app initialization from URL, file, or cache
• ./flows/Map Render.md — Floor loading, fast render, prepared swap
• ./flows/Route Computation.md — Snap → A* → smooth → render
• ./flows/Graph Construction.md — Offline graph generation from MVF data
• ./flows/Asset Loading.md — ZIP, network, hybrid, and overlay providers
• ./flows/Theme Change.md — Style swap, color reapplication, layer refresh
• ./flows/Outdoor Route.md — Indoor/outdoor stitching, nearest road, street routing
• ./flows/Wall Detection.md — Sampling-based wall checks

Decisions

• ./decisions/Sampling vs Intersection.md
• ./decisions/Multi-Candidate A-Star.md
• ./decisions/Post-A-Star Staircase Straightening.md
• ./decisions/Large Room Strict Exit Heuristic.md
• ./decisions/Local Zigzag Shortcut Smoothing.md
• ./decisions/Safe Direct Route Smoothing.md
• ./decisions/Elastic Route Smoothing.md
• ./decisions/Deferred Bootstrap.md
• ./decisions/Dual Routing Engine.md
• ./decisions/Caching Strategy.md

Observability

• ./observability/Runtime Flags and Observability.md — Hub for rollout flags, telemetry, perf
• ./observability/Runtime Flags.md — URL query routing config (engine, graph format, parity)
• ./observability/Rollout Telemetry.md — Fire-and-forget telemetry via sendBeacon/fetch
• ./observability/Startup Perf and Budgets.md — Performance marks, measures, long-task observation
• ./observability/Bootstrap Debug Imports.md — Lazy debug layer imports
• ./observability/Observability Risks.md — Silent flag collapse, telemetry failure, sparse metrics

Risks & Debug

Risk Index

• ./risks/Risk Map.md — Consolidated risk inventory with status
• ./risks/Test Gaps.md — Where test coverage is weakest
• ./risks/Regression Targets.md — Behaviors worth protecting with future tests
• ./risks/Debug Routing.md — Practical debugging decision tree for route bugs
• ./risks/Source Map.md — Source file → vault note cross-reference

Routing Risks

• ./risks/Wrong Door Risk.md — Route endpoint choosing wrong door (3 fixed modes, remaining risk)
• ./risks/Cross Wall Risk.md — Route line appearing to cross a wall (3 fixed modes)
• ./risks/Slice Serializer Cross Floor Bug.md — Serializer drops cross-floor edges (FIXED)

Theme Risks

• ./risks/Theme Risk Index.md — Consolidated theme risk audit with fix priority
• ./risks/Theme Controller Risks.md — ThemeController listener-cleanup and duplicate-event risks
• ./risks/Theme Controller Listener Cleanup.md — Broken listener teardown causing lifecycle leaks
• ./risks/Broad Map Layer ID Matching.md — Broad includes() matching hiding app-owned layers
• ./risks/Host Mode Style Resolution.md — Remote styles chosen when PMTiles should be preferred
• ./risks/Offline Basemap Theme Drift.md — Static JSON vs dynamic style drift
• ./risks/LayerManager Theme Reapply State.md — Missed doors, wrong paint property, wall heuristics
• ./risks/Theme Tests and Fix Plan.md — Missing theme tests and practical fix sequence

Shell & Bootstrap Risks

• ./risks/Shell Bootstrap Risks.md — Keyboard not invoked, cached promise, listener teardown, DOM ID drift
• ./risks/Keyboard and Joystick Input.md — WASD/arrow panning and joystick navigation helpers

Layer & UI Risks

• ./risks/Layer Visibility Risks.md — Visibility desync, filter blanking, layer-ID classification
• ./risks/Debug Layers and Node Overlays.md — Developer-only overlays for walkable/entrance/stairs/elevator nodes
• ./risks/Error Toast and Location Validation.md — Toast system and location sanity checks
• ./risks/Search and Selection Risks.md — Incomplete index, hardcoded sourceType, listener teardown

Offline Risks

• ./risks/Offline Packaging Risks.md — Incomplete precache, manifest drift, SW alignment

Open Questions

• How are polygon holes handled in the WASM spatial bundle?

• Is the graph rebuild automated in CI or manual?

• How does the outdoor routing handle building footprint changes at runtime?

• What is the memory eviction policy for floor cache under heavy pressure?

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