# Native road lane markings and turn arrows

## Goal

Complete the native-road visual language for Nantaizi before any cross-area
migration: lane separators, travel-direction markers, and OSM-backed turn
arrows must be inspectable in the Road Workbench and visible in Blender and
Cesium output.

## Confirmed Facts

- Native output currently contains directed lane centerlines and connector
  curves, but it does not emit paintable lane-separator or turn-arrow polygons.
- The existing osm2streets path has tested arrow templates in
  `scripts/lib/turn-lane-arrows.js`, the `lane_arrows_webscale` material layer,
  and a matching Blender material. Reuse these instead of introducing a second
  arrow style.
- Earlier reviews established that direction markers must sit on the OSM / lane
  centerline, use a clearly directional sharp triangle, and never be treated as
  a road-surface decoration that drifts sideways.
- Turn arrows must follow the actual incoming lane and be placed before its
  junction, with OSM source way, direction, lane index, and maneuver retained
  as provenance.
- Scope remains Nantaizi only. Existing osm2streets output remains untouched.

## Requirements

- R1: Native compilation emits polygonal lane-separator markings derived from
  its own directed lane geometry.
- R2: Native compilation emits turn-arrow polygons for supported OSM
  `turn:lanes` maneuvers, using the existing tested arrow templates and the
  exact native incoming-lane centerline for placement.
- R2a: Native compilation emits repeated straight-ahead direction-arrow
  polygons along directed lanes, matching the visual role of osm2streets'
  ordinary road arrows. These are a separate layer from turn arrows, retain
  their own provenance, and leave a clear buffer around junction turn arrows.
- R3: Native output preserves provenance for every marking: native road/lane
  ID, OSM way IDs, direction, lane number, maneuver, and placement method.
- R4: The Workbench renders markings in a separately controllable layer and
  exposes those provenance fields on selection.
- R5: The native Blender adapter consumes native marking layers through the
  existing lane-separator and lane-arrow material layers; Cesium must receive
  the same geometry through the exported GLB.
- R6: Unsupported, unplaceable, or ambiguous arrow inputs become diagnostics;
  the compiler must not invent a maneuver.

## Acceptance Criteria

- [ ] Nantaizi native output contains valid polygon GeoJSON for generated lane
  separators, repeated road direction arrows, and every supported, explicitly
  tagged turn arrow.
- [ ] A Workbench user can toggle, select, and inspect a generated marker and
  see its lane, OSM, maneuver, and placement provenance.
- [ ] A selected direction marker is geometrically aligned to its directed lane
  centerline; a selected turn arrow is on its incoming lane before the junction.
- [ ] Blender scene output and Cesium GLB contain native lane markings and
  arrows with the existing visual material language.
- [ ] Unit tests cover a normal supported arrow, an unsupported maneuver, and
  an unsafe/too-short placement; native compile and final Nantaizi visual build
  pass without publishing `package/`.

## Out Of Scope

- Inventing turn arrows for untagged lanes, traffic-control semantics, changing
  QGIS/osm2streets layers, or processing another area.

## Key Decision

- Sharp travel-direction triangles remain a Workbench-only inspection aid.
  They explain raw OSM node order after a road is selected.
- Repeated `through` direction arrows are final road markings, distinct from
  both those debug triangles and OSM-backed junction turn arrows. They are
  placed on native lane centerlines at a fixed interval and enter the same
  Blender/Cesium material layer as turn arrows.