osmWorkflow/.trellis/tasks/archive/2026-08/08-18-native-preview-traffic-simulation/implement.md

Implementation Plan

1. Add a native route compiler module that consumes native-road/compiled.json and native layers, emits native-preview-traffic-simulation/v1, and records source hashes and migration metadata.
2. Wire native preview generation to write the descriptor and keep legacy osm2streets route generation unchanged.
3. Extend the browser preview with shared deterministic vehicle state, signal stop constraints, leader following, queue diagnostics, and graceful empty-route behavior.
4. Preserve the existing signal phase, signal_uid, pose, dynamic lens, countdown, disabled-signal, and incident-card contracts; add focused regression tests for each boundary.
5. Add docs/native-preview-traffic-simulation.md with schema, example, coordinate rules, update loop, migration checklist, and rollback notes.
6. Run focused Node tests, native compile/check, a native build with no legacy directory, and browser preview validation in the available Blender/Cesium environment.

Validation Commands

node --check scripts/lib/native-preview-traffic-simulation.js
node --check scripts/build-area.js
npm run test:native-road
npm run test:traffic-signals
npm run test:preview-assets
npm run test:native-preview-traffic
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,compress,package,preview

Risk Controls

• Do not change scripts/lib/traffic-signals.js geometry or phase semantics unless a test proves a migration bug; prefer adapter code.
• Do not add route data to the static package manifest; it belongs beside _preview/ and is optional.
• If native route generation produces no valid route, emit a valid descriptor with diagnostics and keep preview usable.
• Keep all route and simulation math unit-testable without Cesium.