# Design

## Provider Boundary

`build-area.js` will resolve a native provider by default. Native stages consume only OSM, native
road overrides, and `native-road/` outputs. Legacy `intermediates`, `reimport`, and osm2streets
Blender input remain behind explicit legacy selection and keep their existing output contract.

## Native Data Flow

```text
OSM + native-road-overrides.json
  -> compile-native-roads.js
  -> native-road/layers/*.geojson + compiled.json + traffic-signals.json
  -> Blender generate_scene.py --native-road --traffic-signals
  -> .blend
  -> Cesium/package GLB + manifest + runtime/traffic-signals.json
  -> preview HTML + optional native vehicle route
```

The native compiler is the sole authority for road geometry, lane semantics, intersection surfaces,
stop lines, and signal runtime. No native stage reads `geojsonDir` or legacy assembly files.

## Preview Route

Add a native route adapter that derives route segments from `compiled.json` model roads/endpoints and
native lane/connector geometry. If the native route cannot be built for a valid area, preview remains
usable without vehicles and records a warning; missing legacy osm2streets lane polygons is never a
hard failure on the native path.

## Package Runtime

The package stage will copy the native-road signal runtime into its staging runtime directory and
declare it in the package manifest. Preview receives the package-relative runtime URI. Legacy signal
runtime publication remains conditional on the legacy provider.

## Configuration And Compatibility

`roadProvider` defaults to `native`; native stages are the default stage set. QGIS config fields and
legacy stage aliases remain accepted for explicit migration/debug commands, but native manifests and
docs do not claim them as inputs.

The Workbench may continue to read an existing `geojsonDir` only for an explicitly labeled reference
layer and comparison counters. Those reads are optional, isolated from native compile state, and must
never become required inputs for `/api/state`, native editing, package publication, or preview.

## Rollback

The original QGIS/osm2streets branch baseline is tagged
`qgis-original-baseline-20260818` on `main`. Reverting the native-only work can therefore use the tag
or switch to `main`; no destructive cleanup of legacy scripts is required.