Native preview traffic simulation and migration contract

Goal

Extend the native road compiler preview with a deterministic, portable vehicle traffic demonstration that consumes native road topology and the already-validated traffic-signal runtime. The result must be useful as a visual validation tool and as a migration reference for Cesium, Blender, or another platform consuming the generated area package.

Confirmed Baseline

Native road compilation is the production authority; QGIS/osm2streets is not a runtime input.
The previous traffic-signal work is the source of truth and must remain compatible: deterministic signal_uid, phase_group, mast_heading_deg, face_heading_deg, stop-line anchors, shared pose.*, dynamic lens/countdown assets, and disabled-signal filtering.
Existing browser preview already has signal phase timing, signal visualization, route stop matching, vehicle incident cards, and a missing-route fallback. Native preview currently omits the route.
Native road output contains compiled roads/connectors and vehicle_stop_lines.geojson; the native package contains runtime/traffic-signals.json.
The feature is preview-level deterministic behavior, not a legal navigation or microscopic traffic simulator.

Requirements

R1: Generate a native route artifact from native-road/compiled.json and native layer geometry; it must not read osm2streets_web_out, QGIS files, or legacy route files.
R2: Preserve and consume the existing traffic-signal contract without deriving a second signal layout in the browser.
R3: Vehicles must stop before a red/yellow signal at the native stop line, resume on green, and expose the active stop reason in preview diagnostics.
R4: Multiple vehicles on the same route must maintain a configurable minimum gap; a stopped front vehicle must cause following vehicles to decelerate and queue rather than overlap it.
R5: Route, signal, vehicle, stop-event, and following-distance data must be written as versioned, package-adjacent JSON with stable ENU/WGS84 and migration metadata. Another platform must be able to consume the artifact without executing the Node compiler.
R6: The browser preview must degrade gracefully when there are no valid routes or signals; the primary scene remains usable and diagnostics explain the missing optional capability.
R7: Documentation must describe the data flow, schemas, coordinate conventions, signal identity, stop-line association, update loop, and migration/rollback guidance.

Acceptance Criteria

Native build emits a versioned route/traffic-simulation descriptor under the area output and preview loads it without any legacy directory present.
At least one route crosses a native connector and contains a native stop-line association.
A red/yellow phase visibly stops a vehicle before the stop line; green releases it.
Two or more vehicles never overlap and maintain the configured minimum gap while cruising and while queued at a signal.
Disabled native signals are absent from runtime control and do not create vehicle stops.
Preview diagnostics report route count, signal count, stopped vehicles, queue length, and the active simulation descriptor version.
Migration documentation and focused tests allow another consumer to reproduce route, signal, stopping, and gap behavior from generated assets alone.
Existing traffic-signal tests and native road tests remain green; legacy provider behavior is unchanged.

Decided Scope

Simulation fidelity: MVP is a deterministic preview simulation with configurable speed, acceleration/deceleration, reaction time, and minimum gap. A full lane-changing, collision, priority, and multi-intersection traffic engine is deferred.

3.7 KiB Raw Blame History