# Native Lane Markings Design

## Architecture

The native compiler remains the source of truth. It derives two new polygon
layers alongside its existing surface, sidewalk, lane-centerline, and
connector outputs:

```text
canonical directed roads + lane centerlines + junction cutbacks
    |
    +-- lane separators: paint polygons between adjacent same-direction lanes
    |
    +-- direction arrows: repeated through-arrow template on directed lanes,
    |   outside the reserved junction marking zone
    |
    +-- turn arrows: tested existing template, anchored to an incoming lane
          only when that lane has an explicit supported turn:lanes value
```

No OSM2streets rendered geometry is consumed by this path. The existing arrow
template library is reused only as a geometry/style asset, so the native lane
ID and OSM tags remain the evidence for placement.

## Contracts

- `layers/lane_separators.geojson`: polygon FeatureCollection. Each feature
  records `native_id`, directed `road_id`, adjacent lane indices, source OSM
  ways, and `native-road-lane-separator/v1` provenance.
- `layers/turn_arrows.geojson`: polygon FeatureCollection. Each feature records
  its `native_id`, `road_id`, `lane_id`, OSM way IDs, direction, lane index,
  maneuver, template asset, placement distance, and placement provenance.
- Unsupported turn values, a missing usable incoming-lane segment, or an
  insufficient pre-junction placement distance create a diagnostic and no
  arrow geometry.
- `layers/direction_arrows.geojson`: polygon FeatureCollection. Each feature
  records the native lane and directed road, OSM way IDs, a stable sequence
  index, its distance along the lane, and `native-road-direction-arrow/v1`
  provenance. It uses the tested `through` template but is not a turn claim.
- The workbench serves both layers, draws them separately from its current
  centerline/connector debug layer, and selects them by `native_id`.
- `catalog.NATIVE_ROAD_LAYERS` maps the two native sources to the existing
  `lane_separators` and `lane_arrows_webscale` Blender materials. The native
  adapter does not extend the osm2streets scene-layer registry.

## Placement

An incoming lane is oriented in driving direction. A turn arrow is sampled
from that lane's endpoint backwards by the configured safe distance, staying
outside the junction cutback. Its template basis uses the sampled lane tangent;
therefore it is on and aligned with the lane rather than the OSM centerline or
a screen-space direction. Multiple template rings remain separate polygons.

Lane separators are narrow polygons centered between adjacent lane centerlines
on a single directional carriageway. They stop at the same junction cutbacks as
the lane centerlines. A one-lane direction produces none.

Direction arrows are sampled at a fixed road-scale interval along the same
directed lane centerline. Their candidates exclude both endpoint buffers and
the turn-arrow reserve at the incoming end. This preserves a readable repeated
direction cue without overlapping a turn instruction at a junction.

## Compatibility And Rollback

All new files are additive under `native-road/layers/`. The existing
osm2streets/QGIS layer contract and `package/` are unchanged. Selecting
`--road-provider osm2streets` remains rollback. Missing native marking files
are a native Blender build error rather than a silent omission.

## Risks

- OSM turn tags can be incomplete or incompatible with the inferred lane
  count. These are diagnostics, not guessed arrows.
- Very short approaches can have no safe position before the cutback. They are
  skipped with a source-traceable diagnostic.
- Blender and Cesium need a real native build to verify the mesh/material
  contract, not only GeoJSON unit tests.