# Native Road Control Markings Design

## Architecture

The native compiler remains the source of truth. It extends its canonical OSM
parse with marked crossing nodes, then derives two additive polygon layers from
the crossing evidence, native directed lanes, and native junction plans:

```text
OSM crossing node + native directed lane centerlines + junction plans
    |
    +-- crosswalks.geojson: six zebra stripe polygons per safe crossing
    |
    +-- vehicle_stop_lines.geojson: one safe approach stop-line polygon
```

No osm2streets GeoJSON is read. Existing crossing geometry helpers may be
extracted or adapted only when they operate on native lane data and retain
native provenance.

## Source And Placement

- A source node is eligible only when `highway=crossing` and
  `crossing:markings` is not `no`, `none`, or `unmarked`.
- The compiler finds native roads containing the crossing's OSM node and uses
  the nearest compatible directed lane centerline to obtain the road tangent.
- Crosswalk stripes are perpendicular to that tangent and constrained to the
  native road width. Existing fixed zebra dimensions are retained initially:
  six 0.45m stripes with 0.45m gaps, 0.45m stripe width, and a highway-based
  stripe length.
- A stop line is generated only when the crossing can be associated with a
  supported junction approach and a safe outside-of-junction side. Otherwise
  the crosswalk may remain valid but the missing stop line is diagnostic.
- Duplicate nearby crossing nodes use a stable cluster representative so one
  physical crosswalk does not produce duplicate stripes.

## Contracts

`layers/crosswalks.geojson` and `layers/vehicle_stop_lines.geojson` are Polygon
FeatureCollections. Each feature records its crossing OSM node, source OSM way,
native directed road/lane when available, direction, placement method, and
`native-road-crosswalk/v1` or `native-road-stop-line/v1` provenance.

The Workbench API returns both layers as `state.layers.crosswalks` and
`state.layers.vehicleStopLines`. Its browser map uses separate toggleable
layers and selection evidence; the scene-preview toggle leaves real control
markings visible.

`catalog.NATIVE_ROAD_LAYERS` maps the sources to existing `crosswalks` and
`vehicle_stop_lines` material layers. This native adapter must not add them to
the osm2streets `ROAD_LAYERS` / `SCENE_LAYERS` registry.

## Compatibility And Rollback

The new files are additive under `native-road/layers/`. Existing osm2streets
output and QGIS input are unchanged. Selecting `--road-provider osm2streets`
remains rollback. A native Blender build treats a missing new layer as an error
rather than silently omitting a visible marking.

## Risks

- Crossing nodes can be detached from a routable road or lie on an ambiguous
  multi-road segment. These become diagnostics rather than guessed geometry.
- A physical crossing split into several OSM nodes must deduplicate stably.
- A crosswalk near a non-supported junction may get stripes but no valid stop
  line; this difference must be exposed in workbench provenance.