feat: add native preview traffic simulation

docs/native-preview-traffic-simulation.md

@@ -0,0 +1,64 @@
+# Native Preview Traffic Simulation
+
+This document defines the portable preview contract for native road traffic demonstrations. It is
+not a legal navigation format or a full microscopic traffic simulator.
+
+## Data Flow
+
+```text
+native-road/compiled.json + layers/
+  -> native-preview-traffic-simulation/v1 descriptor
+package/runtime/traffic-signals.json
+  -> signal phase clock and stop constraints
+descriptor + package/manifest.json
+  -> Cesium preview vehicles, signals, queues, diagnostics
+```
+
+The descriptor is generated from native artifacts and is independent of QGIS/osm2streets. Copying
+the descriptor, package, and preview runtime to another platform is sufficient to reproduce the
+visual simulation.
+
+## Existing Signal Contract
+
+Signal identity is `signal_uid`; it must not be renamed when `display_id` changes. `phase_group`
+selects the existing signal phase. `mast_heading_deg`, `face_heading_deg`, `pose.*`, stop-line
+coordinates, and `enabled` are consumed from `package/runtime/traffic-signals.json`. Disabled signals
+are absent from runtime control. Consumers must not recalculate lamp or pole geometry.
+
+## Vehicle Rules
+
+Each vehicle advances along a route distance. Its target speed is the minimum of desired speed,
+signal-safe speed, and leader-safe speed. Red/yellow signals create a stop target before the native
+stop line. Following vehicles apply the configured minimum gap and decelerate behind the leader.
+The simulation is deterministic for a fixed descriptor, clock start, and settings.
+
+The descriptor records WGS84 route coordinates. The static package remains local ENU and is placed by
+the package manifest. Consumers must use the package placement/model matrix for GLB assets and WGS84
+coordinates for route entities; do not mix a fixed meters-per-degree approximation into either path.
+
+Route geometry is taken from `native-road/layers/lane_centerlines.geojson` when that native layer is
+available, keyed by `road_id`; the compiled road centerline is only a compatibility fallback for old
+native outputs. Each road/connector boundary is checked in meters. Candidates with a missing
+connector or an endpoint gap over 35 m are omitted from `routes` and retained in `rejectedRoutes`
+with structured diagnostics. This prevents a malformed movement from becoming a visible diagonal
+track across an intersection.
+
+`diagnostics` contains the route-generation warnings, while `rejectedRoutes` preserves the candidate
+id and the specific movement checks that failed. A consumer should display these as data-quality
+warnings rather than silently reconstructing a route from legacy QGIS files.
+
+## Migration Checklist
+
+1. Load `package/manifest.json` and resolve all package-relative assets.
+2. Load the traffic-signal runtime and preserve `signal_uid`/`phase_group` values.
+3. Load the versioned simulation descriptor and verify its source hashes if reproducibility matters.
+4. Implement the update loop using the descriptor settings and stop/leader constraints.
+5. Place route coordinates in the same WGS84 scene as the package placement and preserve ENU model
+   placement for static assets.
+6. Expose route count, signal count, stopped vehicles, and queue length as diagnostics.
+
+## Rollback
+
+Deleting or ignoring the optional simulation descriptor returns the native preview to a usable static
+scene with signal visualization but no vehicle cruise. The QGIS baseline remains available through
+`qgis-original-baseline-20260818`; it is not required by this contract.