"/home/yossef/notes/git/projects/maplibra/Development Workflow.md"

path: maplibra/Development Workflow.md

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

Development Workflow

Purpose: Practical workflow for changing and verifying this project.

Related: ./Home.md, ./Commands.md, ./Testing.md, ./Project Map.md

Local Loop

1. Start from the relevant module note in this vault.
2. Inspect the source files listed in ./Project Map.md.
3. Add or update focused Vitest coverage first for behavior changes.
4. Implement the smallest safe change.
5. Run focused tests, then run broader integration tests when routing behavior changes.
6. Use npm run dev for visual verification on map routes.

Startup Change Checklist

• Verify MVF loader still parses bundles correctly
• Check asset provider chain for new file types
• Ensure appContext flags are updated if new startup state is needed
• Run npx vitest run tests/bootstrap-*.test.js tests/startup-*.test.js
• Test all startup modes: URL, file, cache, asset root

Routing Change Checklist

• Update tests in the focused route area.
• Verify walkability validation still guards new geometry changes.
• Check whether JS, worker, binary, or WASM paths are affected.
• Run npx vitest run tests/route-smoothing.test.js tests/route-features.test.js.
• For graph or derived asset changes, also run tests/zip-node-builder.test.js and tests/integration-realmap.test.js.
• For outdoor routing changes, run tests/outdoor-routing.test.js and tests/unified-outdoor-route.test.js.
• For WASM changes, run tests/route-kernel-*.test.js and tests/path-worker-binary.test.js.

UI Change Checklist

• Verify accessibility attributes (aria-label, aria-expanded, role)
• Test mobile viewport sizing (--app-height variable)
• Check theme switching behavior (light → dark → light)
• Test native controls mode (add .native-controls class)
• Run npx vitest run tests/ui-manager-*.test.js tests/search-box-*.test.js

Layer/Debug Change Checklist

• Verify debug layers load lazily and do not bloat the main bundle
• Check floor visibility filtering after layer changes
• Ensure legend toggle state persists in localStorage
• Run npx vitest run tests/visibility-manager.test.js tests/legend-toggle-manager.test.js

Android Bridge Change Checklist

• Test bridge methods with window.AndroidBridge mock
• Verify notifyAndroidFloorState is called on floor changes
• Check onUploadReady is called in upload/clear modes
• Run npx vitest run tests/native-controls-layout.test.js

Performance Change Checklist

• Check startup perf marks are still recorded correctly
• Verify time-to-first-render and time-to-first-idle are measurable
• Run npm run perf:baseline and compare against docs/perf-baseline.md
• Run npx vitest run tests/perf-budget.test.js

Current Routing Note

The post-A* staircase straightener intentionally changes only route feature geometry after A* has returned node IDs. It does not change graph generation or WASM routing. See ./decisions/Post-A-Star Staircase Straightening.md.

Current Outdoor Routing Note

Outdoor routing requires network access for nearest-road and street-route APIs. In offline mode, the direct route solver around the building footprint is used instead.

Current Bootstrap Note

Deferred bootstrap (lazy loading of routing, search, debug) is intentional. The app should be interactive after the first floor render, even if routing assets are still building.

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