chore: record journal

.trellis/spec/blender/asset-generation.md

@@ -205,6 +205,28 @@ tilt_y       = TILT_JITTER * math.cos(index * 0.927295)
 模型保持在**局部 ENU 坐标系**（X 东、Y 北、Z 上），靠伴生 JSON 配合
 `Cesium.Transforms.eastNorthUpToFixedFrame` 摆放。
 
+### WGS84 ENU 坐标契约
+
+Blender 中所有经纬度几何必须通过 `osmassets.osm.Projector` 转换。该转换必须与 Cesium
+的 `eastNorthUpToFixedFrame(anchor)` 使用同一个 WGS84 椭球语义：先将经纬度转换为
+ECEF，再将相对锚点的向量投影到 East/North 轴。禁止用固定 `111320 m/deg` 的
+equirectangular（等距圆柱）近似生成场景坐标。
+
+固定米/度近似只会在锚点附近碰巧重合；纬向比例与 WGS84 实际比例不同，误差会随离锚点
+距离增长。表现为 Cesium Entity 路线在部分道路居中、在其他道路相对整个 GLB 路面同向
+平移。只验证 route 与 GeoJSON 自洽无法发现此问题，必须重新生成
+`blender,cesium,preview` 并在最终 Cesium 画面中核对。
+
+修改 `Projector` 后至少执行：
+
+```bash
+python3 -m unittest blender.tests.test_pure
+npm run build:area -- --config config/areas/<area>.json --stages blender,cesium,preview
+```
+
+`blender.tests.test_pure.ProjectorTest` 必须断言锚点为原点、East/North 方向正确，以及局部
+经纬度增量符合 WGS84 椭球曲率半径。
+
 ### Cesium contract
 
 新生成场景的 Cesium 导出调色写在 `catalog.MATERIALS[*]["cesium"]`，由
@@ -278,6 +300,7 @@ tilt_y       = TILT_JITTER * math.cos(index * 0.927295)
 | 直接 append vendored 资产的材质 | alpha-clip 缺失，树冠渲染成一块 |
 | 删掉"试过不行"的注释 | 下一个人重新踩同一个坑 |
 | 从 `scene-layers.js` 的 hex 换算 Blender 颜色 | 抹掉独立调过的配色 |
+| 用固定米/度比例投影经纬度 | GLB 与 Cesium Entity 随离锚点距离产生位置漂移 |
 | 加新资产不配 Cesium 调色 | Cesium 里显得发黑 |
 | 靠调 `FOLIAGE_EMISSION` 提亮植被 | 用错了旋钮，该调 albedo gain |
 | 在 `MATERIALS` 中间插入条目 | GLB 材质索引整体平移 |

.trellis/spec/guides/cross-layer-thinking-guide.md

@@ -46,6 +46,7 @@ cesium-preview.js            浏览器
 - [ ] 你在改任何被 `execFileSync` / `spawnSync` 调起的东西
 - [ ] 你在改 stage 的 stdout 打印
 - [ ] 你要新增一种在 Blender 里生成、要在 Cesium 里看的资产
+- [ ] Blender GLB 与 Cesium Entity、polyline 或 label 必须在地理位置上重合
 
 ---
 
@@ -144,6 +145,36 @@ OSM way 的端点不一定在原始 XML 中有三个以上相连 way；osm2stree
 
 **教训**：**跨阶段契约必须随产物保存；兼容旧产物的字符串回退也要被审查**。
 
+### 坑 6：部分构建复用了过期的交通信号运行时数据
+
+`intermediates` 才能根据当前 OSM 的 `highway=traffic_signals` 控制节点、
+`vehicle_stop_lines.geojson` 和 `intersection_surface.geojson` 初始化可编辑的
+`traffic_signal_assemblies.geojson`。此后该 GeoJSON 是 QGIS 编辑生命周期内的事实源；
+`traffic_signals.json` 只是严格校验后派生的运行时数据。Blender 将其中每个稳定的
+`signal_uid` 导出为静态设施、三个动态灯节点和一组倒计时节点，
+`scripts/lib/cesium-preview.js` 再按相同 id 控制它们。
+
+因此执行 `blender,cesium,preview` 这类部分构建时，必须在 Blender stage 入口从当前
+`traffic_signal_assemblies.geojson` 重建运行时 JSON，但绝不能重新从 OSM 初始化位置，
+否则会覆盖 QGIS 中移动、旋转或禁用设施的编辑。该刷新由
+`scripts/build-area.js:buildBlenderScene()` 负责。
+
+**教训**：**跨阶段运行时 JSON 必须在最早消费它的 stage 从当前权威产物重建；同时要
+区分“初始化来源”和“编辑后的事实源”，不能用早期输入覆盖人工编辑。**
+
+### 坑 7：GeoJSON 内部正确，但 GLB 与 Cesium 路线仍然错位
+
+巡航路线曾经与 osm2streets Driving polygon 中轴逐点吻合到厘米级，仍在最终预览中出现
+部分路段偏离车道中心。原因是路线由 Cesium 直接按 WGS84 经纬度放置，而 Blender GLB
+使用固定 `111320 m/deg` 的近似投影后再放到 WGS84 ENU 锚点。两套坐标仅在锚点附近
+重合，误差随距离增长。
+
+**教训**：跨坐标运行时不能只验证源数据内部自洽。凡是 Blender GLB 与 Cesium Entity
+需要重合，必须检查 `GeoJSON -> Blender local ENU -> GLB modelMatrix` 与
+`GeoJSON -> Cesium Cartesian3` 的端到端契约，并在最终画面做横截面对齐验证。
+
+→ [资产生成：WGS84 ENU 坐标契约](../blender/asset-generation.md#wgs84-enu-坐标契约)
+
 ---
 
 ## 加东西时的检查清单

.trellis/spec/pipeline/cli-and-stages.md

@@ -343,13 +343,14 @@ out.vehicleStopLines = crosswalkData.stopLines;
 // 原生 lane_markings 停止线不得复制到输出。
 ```
 
-## 信号锚点的跨阶段消费
+## 可编辑信号设施与运行时锚点的跨阶段消费
 
 ### 1. Scope / Trigger
 
 路口信号设施需要同时被 Blender 主 GLB 和 Cesium 预览消费时，使用
-`<geojsonDir>/traffic_signals.json`。它是附属 intermediates 产物，而不是第十个
-osm2streets/QGIS 图层。
+`<geojsonDir>/traffic_signal_assemblies.geojson` 是 GeoPackage/QGIS 中的附属可编辑点图层；
+`<geojsonDir>/traffic_signals.json` 是从它严格校验并派生的运行时产物。前者不属于九个
+`SCENE_LAYERS`，后者不进入 GeoPackage。
 
 ### 2. Signatures
 
@@ -366,15 +367,19 @@ area.outputs.trafficSignals
 
 ### 3. Contracts
 
-- `build-area.js:writeTrafficSignals()` 是锚点 JSON 的生产者，调用
-  `traffic-signals.js:readTrafficSignals()`，输入为 `vehicle_stop_lines.geojson` 和
-  `intersection_surface.geojson`。
-- `intermediates` 与 `reimport` 都必须在其 GeoJSON 产物稳定后重写锚点，确保 QGIS
-  人工修补反导入后，Blender 和 preview 仍使用同一事实。
+- `intermediates` 从 OSM control、停止线和路口面初始化 `traffic_signal_assemblies.geojson`，
+  并将其作为附属点层导入 GeoPackage；完整重跑 intermediates 会像道路图层一样覆盖人工编辑。
+- `reimport` 必须与九个场景层一起暂存导出附属层，先校验全部信号要素，再替换任何输出。
+- `build-area.js:writeTrafficSignals()` 只从当前 `traffic_signal_assemblies.geojson` 重建运行时
+  `traffic_signals.json`。Blender 入口也执行这一步，但不得重新从 OSM 初始化位置。
 - `blender` 和 `preview` 在启动前必须检查该文件存在；前者把静态设施写进 `05_Props`，
   后者只叠加动态灯珠、倒计时和车辆相位。
-- `traffic_signals.json` 不得加入 `SCENE_LAYERS`、GeoPackage 或 QGIS 工程；这些层只能
-  继续包含九个道路场景图层。
+- `traffic_signal_assemblies.geojson` 必须加入 GeoPackage/QGIS 工程，但不得加入
+  `SCENE_LAYERS`、合并道路场景或栅格预览；`traffic_signals.json` 仍不得加入 GeoPackage。
+- `signal_uid` 必须由 control id、source way id 和相邻 arm node id 确定性生成；运行时 `id`
+  使用该技术 id。`display_id` 可编辑且非空时唯一，修改它不得重命名 GLB 节点。
+- Point 几何是灯杆地面点；`stop_lon`/`stop_lat` 独立保存，移动杆件不得移动车辆停止点。
+- `enabled=false` 的要素保留在编辑层但不进入运行时 signals。
 - `layout.countdownLateralMeters` 等几何字段是 Blender/preview 的共同事实源；横向正值统一
   表示相对来车方向的右侧。不得在任一消费方用独立的负号约定替代它。
 - `layout.mastHeightMeters` 与 `layout.headCenterHeightMeters` 必须相等，表示横杆与灯壳的
@@ -385,9 +390,9 @@ area.outputs.trafficSignals
 
 | 条件 | 结果 |
 |---|---|
-| `intermediates` 或 `reimport` 有合法停止线和路口面 | 写出 `version` 与 `signals` 数组，即使数组为空 |
+| `intermediates` 或 `reimport` 有合法编辑层 | 写出 `version` 与 `signals` 数组，即使数组为空 |
 | 直接运行 `blender` / `preview` 但锚点不存在 | 在启动外部工具前报 `Traffic signal anchors not found` |
-| 单个停止线无法可靠关联路口 | 锚点生成器跳过该项，其他进口照常输出 |
+| `signal_uid` 缺失/重复、非空 `display_id` 重复、字段或 Point 无效 | 重导入在替换任何输出前失败 |
 | 用户仅修改 QGIS 后运行 `reimport` | 重新生成锚点，不沿用旧坐标 |
 
 ### 5. Good/Base/Bad Cases
@@ -741,6 +746,9 @@ runtime 与 HTML，并写 preview manifest。预览内容实现不得回流到
 - `inputs.osm`
 - `inputs.glb`
 - `inputs.metadata`
+- `inputs.lanePolygons`
+- `inputs.network`
+- `inputs.intersectionSurface`
 - `inputs.previewCss`
 - `inputs.previewJs`
 - `outputs.cesiumPreview`

.trellis/spec/preview/index.md

@@ -112,6 +112,9 @@ setLoadingMessage("Preparing view")
 window.osmPreview = { viewer, metadata, placement, assets, cruise, cameras };
 ```
 
+预览加载的生成式 JSON（路线和交通信号）使用 `fetch(..., { cache: "no-store" })`，因为
+这些文件保持稳定文件名但会被单独重生成；浏览器不得继续显示旧的巡航路线。
+
 调试和无头检查都靠它。**加新的顶层对象就往这里挂**，不要再开新全局。
 
 ---

.trellis/spec/preview/vehicle-routes.md

@@ -11,9 +11,9 @@
 ## 2. Signatures
 
 ```js
-buildVehicleRoute(osmPath) => {
-  source, bounds, generatedAt, speedMetersPerSecond, loop,
-  routes, segments
+buildVehicleRoute(osmPath, lanePolygonsPath, networkPath, intersectionSurfacePath) => {
+  source, laneSource, networkSource, intersectionSource, bounds, generatedAt, speedMetersPerSecond, loop,
+  routes, segments, diagnostics
 }
 
 allowedTurns(tags, direction) => Set<"left" | "through" | "right">
@@ -28,7 +28,14 @@ classifyConnection(incomingEdge, outgoingEdge) =>
 
 - `routes` 是当前主字段；`segments` 必须是同一数组的兼容别名，供旧预览使用。
 - 每个路线至少包含 `id`、`coordinates`、`centerlineCoordinates`、`lengthMeters`、
-  `maneuvers` 与 `edgeIds`。`coordinates` 是右侧车道偏移后的闭合巡航轨迹。
+  `maneuvers`、`edgeIds`、`laneSegments` 与 `connectors`。道路区间来自匹配的 Driving lane polygon 中轴。
+- 路线拓扑以 `network.json` 的 internal road 和 intersection 为准；禁止把整个 OSM way 直接当作一条不可分割 edge。
+- connector 必须绑定同一个 internal intersection，并位于对应 `intersection_surface.geojson` 内或允许的边界容差内；越界时拒绝候选路线。
+- preview 必须将 `lane_polygons.geojson`、`network.json` 和 `intersection_surface.geojson` 作为强制输入；缺失或无效时在写产物前失败。
+- route 经纬度由 Cesium 按 WGS84 直接放置；最终道路 GLB 必须由 WGS84 ECEF→ENU
+  `Projector` 生成。禁止以固定米/度近似投影道路，否则即使 route 与 lane polygon
+  完全一致，最终画面仍会随离锚点距离产生横向偏移。
+- 单条路线无法可靠匹配时跳过并写结构化 `diagnostics`，不得回退固定或默认车道宽度。
 - 有 `oneway=yes`（及等价真值）的 way 只能按 OSM 原始方向生成 edge，绝不能生成反向
   `:backward` edge；`oneway=-1` 仅允许反向 edge。
 - 去程在路口按入边方向读取 `turn:lanes:forward` 或 `turn:lanes:backward`，只有标签中的
@@ -36,6 +43,7 @@ classifyConnection(incomingEdge, outgoingEdge) =>
 - 返程是展示路线的原路回返，不以反向 `turn:lanes` 再次否决，但依旧不可逆行单行道。
 - 路网没有闭环时，在去程和返程端点插入平滑调头曲线；不得在 way 端点或路口瞬移。
 - 选择菜单使用 `#编号 · 长度 m · 左 N / 右 N / 直 N`，因为一条路线可跨越多个道路名称。
+- 预览只显示当前下拉框选中车辆的 route polyline，避免多条闭环轨迹在路口重叠造成错误的偏移判断。
 
 ## 4. Validation & Error Matrix
 
@@ -62,6 +70,8 @@ classifyConnection(incomingEdge, outgoingEdge) =>
   `node --check scripts/lib/cesium-preview.js`：保证 Node 与浏览器直载脚本语法可用。
 - 对目标区域运行 `npm run build:area -- --config config/areas/<area>.json --stages preview`，确认
   `routes` 中存在左、右、直动作，且 Cesium 下拉标签显示编号、长度与动作统计。
+- 修改地理投影时必须运行 `blender,cesium,preview`，不能只重跑 preview；最终检查青色路线
+  到黄色中心线及道路边缘的横截面距离，确认两侧路线分别位于各自车道中心。
 
 ## 7. Wrong vs Correct
 

.trellis/tasks/archive/2026-08/08-07-qgis-traffic-signal-overrides/check.jsonl

@@ -0,0 +1,5 @@
+{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"Check stage ownership, diagnostics, and traffic signal contract compliance"}
+{"file":".trellis/spec/pipeline/external-tools.md","reason":"Check atomic reimport behavior and external-tool handling"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"Check full editable-layer to runtime JSON to Blender/Cesium data flow"}
+{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"Check intended and unintended scene/GLB structural differences"}
+{"file":".trellis/spec/blender/testing.md","reason":"Check appropriate pure and Blender validation coverage"}

.trellis/tasks/archive/2026-08/08-07-qgis-traffic-signal-overrides/design.md

@@ -0,0 +1,100 @@
+# Design: QGIS Traffic Signal Overrides
+
+## Architecture
+
+Introduce a separate auxiliary-edit-layer registry rather than adding traffic signals to `SCENE_LAYERS`. The initial registry contains one layer:
+
+```text
+traffic_signal_assemblies.geojson
+  geometry: Point (pole ground position, EPSG:4326)
+  properties: stable identity, source identity, heading, phase, reach, stop point, enabled, z offset
+```
+
+The existing runtime file remains:
+
+```text
+traffic_signals.json
+  version/layout/signals[] with full pose.* data
+```
+
+The editable GeoJSON is the placement source; the runtime JSON is a derived consumer artifact.
+
+## Data Flow
+
+```text
+OSM controls + topology + stop lines + intersections
+                         |
+                   intermediates only
+                         v
+             traffic_signal_assemblies.geojson
+                         |
+                import into GeoPackage
+                         |
+                    edit in QGIS
+                         |
+                      reimport
+                         v
+             traffic_signal_assemblies.geojson
+                         |
+                 validate + derive pose
+                         v
+                  traffic_signals.json
+                    /             \
+                 Blender         preview/Cesium
+```
+
+`blender` reruns the final validation/derivation arrow from the editable GeoJSON so derived JSON cannot be stale, but it never reruns the OSM initialization arrow.
+
+## Editable Feature Contract
+
+Recommended properties:
+
+| Property | Type | Ownership |
+|---|---|---|
+| `signal_uid` | string | generated, immutable technical identity |
+| `display_id` | string | user-editable unique label/number |
+| `control_id` | string | generated OSM control id |
+| `approach_id` | string | generated physical approach identity |
+| `source_way_id` | string | generated matching/diagnostic field |
+| `heading_deg` | number | user-editable assembly facing direction |
+| `phase_group` | integer 0/1 | user-editable current two-phase group |
+| `mast_reach_m` | positive number | user-editable arm reach |
+| `stop_lon`, `stop_lat` | finite numbers | generated vehicle stop point, preserved when pole moves |
+| `enabled` | boolean/integer | user-editable suppression flag |
+| `z_offset_m` | finite number | user-editable vertical adjustment |
+
+Point geometry is the pole longitude/latitude. The runtime `id` should be derived from `signal_uid`, not display numbering, so changing `display_id` does not rename GLB nodes or break preview control.
+
+## Stable Identity
+
+Extend parsed OSM arm data to retain enough deterministic source identity (control node, way, adjacent arm direction/node). Generate a technical key from those source values. Do not use sorted array index or rounded heading as the primary key.
+
+If topology changes on a future `intermediates` run, the rebuilt GeoPackage may produce new identities. This is consistent with current road-edit lifecycle and is explicitly out of scope for MVP migration. Validation still reports duplicate identities and malformed source fields.
+
+## QGIS Integration
+
+- Add an auxiliary layer definition separate from the nine render layers.
+- Import it into the same GeoPackage after render layers.
+- Include it in the generated project but exclude it from the merged scene and 2D raster preview unless deliberately enabled for editing visibility.
+- Use a point marker plus rotated direction indicator driven by `heading_deg` and label by `display_id`, falling back to `signal_uid`.
+- Configure read-only/editor widgets where practical: technical/source ids read-only; phase group constrained to 0/1; numeric fields constrained to valid ranges; enabled as checkbox.
+
+## Reimport and Atomicity
+
+Extend the reimport layer manifest to include auxiliary editable layers while keeping render-scene merge derived only from `SCENE_LAYERS`. Export every layer into staging, parse and validate all editable features, then replace output files. Runtime JSON is written only after the staged auxiliary layer passes validation.
+
+## Compatibility
+
+- The next `intermediates` run bootstraps existing areas; no old JSON migration is required.
+- Main `.blend`/GLB geometry changes intentionally when a QGIS edit changes a signal.
+- Dynamic and countdown GLBs continue using runtime signal ids, now stable across ordinary reimport edits.
+- Current two-phase simulation remains unchanged.
+
+## Risks and Controls
+
+- **OSM way splitting changes source ids:** accepted across a full intermediates rebuild; ordinary reimport is stable.
+- **QGIS boolean/string coercion:** normalize known GDAL representations before strict validation and test the round-trip output.
+- **Accidental source-field editing:** mark technical fields read-only in QGIS and validate identity format during reimport.
+- **Partial overwrite on invalid auxiliary data:** retain the existing staging-before-replace discipline.
+- **Old spec conflict:** update pipeline specs that currently forbid traffic-signal anchors in GeoPackage, clarifying the distinction between editable assembly points and derived runtime anchors.
+

.trellis/tasks/archive/2026-08/08-07-qgis-traffic-signal-overrides/implement.jsonl

@@ -0,0 +1,6 @@
+{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"Traffic signal stage ownership, reimport lifecycle, manifests, and current anchor contract"}
+{"file":".trellis/spec/pipeline/layer-registry.md","reason":"Keep the auxiliary editable layer separate from the nine render layers and preserve their order"}
+{"file":".trellis/spec/pipeline/external-tools.md","reason":"GeoPackage import/export and staging-before-replace requirements"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"OSM to GeoJSON/GPKG to Blender/Cesium contract review"}
+{"file":".trellis/spec/blender/asset-generation.md","reason":"Signal pose and dynamic asset generation constraints"}
+{"file":".trellis/spec/preview/vehicle-routes.md","reason":"Vehicle stop coordinates and runtime signal data coupling"}

.trellis/tasks/archive/2026-08/08-07-qgis-traffic-signal-overrides/implement.md

@@ -0,0 +1,53 @@
+# Implementation Plan: QGIS Traffic Signal Overrides
+
+## 1. Contracts and Pure Logic
+
+- [x] Add an auxiliary editable-layer definition without modifying `SCENE_LAYERS` ordering.
+- [x] Extend OSM arm parsing with deterministic approach identity inputs.
+- [x] Split traffic-signal logic into automatic editable-feature generation, feature validation/normalization, and runtime pose derivation.
+- [x] Use stable technical ids for runtime signal ids; keep `display_id` as editable metadata.
+- [x] Add pure Node tests for T/cross counts, stable ids, movement/heading reconstruction, disabled features, duplicate ids, and invalid values.
+
+## 2. Intermediates and QGIS
+
+- [x] Write `traffic_signal_assemblies.geojson` after stop-line/intersection outputs are stable.
+- [x] Import the auxiliary point layer into the GeoPackage after the nine render layers.
+- [x] Extend generated QGIS project code with point/direction styling, labels, and field widgets/constraints.
+- [x] Confirm the auxiliary layer is excluded from merged road scene ordering and raster preview behavior.
+
+## 3. Reimport and Stage Ownership
+
+- [x] Extend `reimport-gpkg.js` to discover/export render and auxiliary layers through staging.
+- [x] Validate the staged editable layer before replacing any output artifact.
+- [x] Rebuild runtime `traffic_signals.json` from editable GeoJSON after `intermediates`, `reimport`, and at Blender entry.
+- [x] Remove Blender-entry OSM placement regeneration so QGIS edits remain authoritative.
+- [x] Extend stage manifests and diagnostics with auxiliary input/output records and feature counts.
+
+## 4. Cross-Layer Consumers
+
+- [x] Preserve `display_id` and stable runtime ids through Blender and Cesium metadata where useful.
+- [x] Verify static signal objects, dynamic lenses, countdown nodes, and vehicle stop behavior all consume the same enabled runtime records.
+- [x] Update pipeline specifications to replace the old prohibition with the editable-layer/derived-runtime distinction.
+
+## 5. Validation
+
+- [x] Run Node syntax checks and focused unit tests.
+- [x] Run existing preview-assets, preflight, budget, and relevant pipeline tests.
+- [x] Run `intermediates` and inspect the GeoPackage/QGIS project feature schema and styling.
+- [ ] Make a controlled QGIS edit to one signal (display id, point, heading), run `reimport,blender,cesium,preview`, and verify only the intended assembly changes. (`reimport` and Blender passed; Cesium/preview refresh was not repeated.)
+- [x] Confirm an invalid/duplicate edit fails before overwriting valid outputs.
+- [ ] Inspect Blender/Cesium structural digests and Safari preview for T and cross junctions. (Blocked this run by Blender 4.5.12 Metal startup SIGSEGV before project Python.)
+
+## Risky Files / Rollback Points
+
+- `scripts/lib/traffic-signals.js`: identity and pose contract; land pure tests before pipeline integration.
+- `scripts/build-osm2streets-qgis.js`: GeoPackage recreation and generated QGIS Python; verify auxiliary import independently before styling.
+- `scripts/reimport-gpkg.js`: atomic overwrite boundary; preserve staging semantics.
+- `scripts/build-area.js`: stage ownership; ensure Blender derives from editable GeoJSON rather than overwriting it.
+- `blender/osmassets/traffic_signals.py` and preview runtime should require minimal or no geometry changes; unexpected edits here indicate contract leakage.
+
+## Review Gate Before Start
+
+- [ ] User approves the final planning summary.
+- [ ] `prd.md`, `design.md`, and `implement.md` agree on full editable layer ownership and out-of-scope intermediates persistence.
+- [ ] No unresolved product decision remains.

.trellis/tasks/archive/2026-08/08-07-qgis-traffic-signal-overrides/notes.md

@@ -0,0 +1,14 @@
+# Debug Notes
+
+## 2026-08-07 countdown node-name regression
+
+Stable `signal_uid` values are intentionally descriptive and can exceed Blender's
+63-byte object-name limit. Using them directly in dynamic lens/countdown node
+names caused Blender to truncate names while Cesium looked up the untruncated
+strings. The countdown GLBs then exposed all digits without the runtime being
+able to hide the inactive values, appearing as overlapping/blurred numbers.
+
+Runtime signal records now carry a deterministic short `nodeKey` (`ts_` plus
+the first 16 hex characters of SHA-256 of `signal_uid`). Blender uses it for
+dynamic object names and Cesium uses the same key for lookups. Preview keeps a
+fallback to `signal.id` for older metadata files.

.trellis/tasks/archive/2026-08/08-07-qgis-traffic-signal-overrides/prd.md

@@ -0,0 +1,67 @@
+# QGIS Traffic Signal Overrides
+
+## Goal
+
+Make every automatically generated vehicle traffic signal independently identifiable and editable in QGIS. A user must be able to assign a display number, move a pole, rotate its assembly, adjust supported placement attributes, run `reimport`, and have Blender and Cesium consume that edited result without OSM regeneration overwriting it.
+
+## Background
+
+- Current traffic signals are derived from OSM `highway=traffic_signals` controls, road topology, `vehicle_stop_lines.geojson`, and `intersection_surface.geojson` by `scripts/lib/traffic-signals.js`.
+- Current sequential ids such as `signal-1` depend on generation order and are not suitable as persistent edit identities.
+- Current `<geojsonDir>/traffic_signals.json` contains fully derived `pose.*` data but is deliberately excluded from the GeoPackage and QGIS project.
+- Existing road editing establishes the desired lifecycle: `intermediates` initializes a GeoPackage, the user edits it in QGIS, and `reimport` exports the edited data back to GeoJSON. Running `intermediates` again may discard manual edits; that behavior remains explicit and unchanged.
+
+## Requirements
+
+### R1. Editable auxiliary layer
+
+- `intermediates` must create a point FeatureCollection containing one feature per physical signal assembly and import it into the area GeoPackage.
+- The generated QGIS project must expose the layer with a visible directional symbol and a label suitable for identifying individual signals.
+- The auxiliary layer must not join `SCENE_LAYERS` or the merged road scene because it is an editing/control artifact, not a road render layer.
+
+### R2. Stable identity and numbering
+
+- Every generated feature must contain an immutable technical `signal_uid` derived deterministically from its OSM control and physical approach identity, rather than array order.
+- Every feature must contain an editable `display_id` intended for user-facing numbering.
+- Build/reimport validation must reject duplicate or missing `signal_uid` values and duplicate non-empty `display_id` values with an actionable error.
+
+### R3. Editable placement contract
+
+- Point geometry represents the pole ground position.
+- Editable attributes must include at least `display_id`, `heading_deg`, `phase_group`, `mast_reach_m`, `enabled`, and `z_offset_m`.
+- Source/control attributes required for matching and diagnostics must be preserved, including `control_id` and approach identity.
+- Vehicle stop coordinates remain independent attributes; moving the pole must not silently move the vehicle stop point.
+- After reimport, the pipeline must deterministically rebuild `pose.pole`, `pose.arm`, `pose.head`, `pose.lenses`, and `pose.countdown` from the edited point and attributes.
+
+### R4. Stage ownership
+
+- `intermediates` initializes the editable signal layer from current OSM/topology and derives the runtime `traffic_signals.json` from it.
+- `reimport` must stage, validate, and export the editable signal layer along with the existing road layers, then rebuild the runtime JSON.
+- `blender` must rebuild runtime `traffic_signals.json` from the current editable signal GeoJSON. It must not recompute signal placement directly from OSM and erase QGIS edits.
+- `cesium` and `preview` continue consuming artifacts derived from the same runtime JSON and retain matching signal node ids.
+
+### R5. Diagnostics and compatibility
+
+- Invalid geometry, invalid numeric fields, duplicate identities, unsupported phase groups, and unmatched source references must fail before replacing valid output artifacts.
+- `enabled=false` suppresses a signal without requiring feature deletion, so automatic regeneration cannot accidentally resurrect an intentionally disabled assembly within the same edit lifecycle.
+- Existing areas without an editable signal layer must receive one on their next `intermediates` run. No migration of previously hand-edited traffic signal JSON is required.
+
+## Acceptance Criteria
+
+- [ ] A clean `intermediates` run creates the editable traffic-signal GeoJSON, a GeoPackage layer with the same feature count, and a QGIS project layer with labels and directional symbols.
+- [ ] T junctions produce three editable features and cross junctions produce four, each with a unique deterministic `signal_uid`.
+- [ ] Moving one point in QGIS and changing its `display_id` and `heading_deg`, followed by `reimport,blender,cesium,preview`, changes only that signal assembly's placement/identity-facing metadata while preserving its vehicle stop point.
+- [ ] Re-running `blender` after reimport does not overwrite the QGIS-edited pole position or heading from OSM.
+- [ ] Setting one feature to disabled removes its static and dynamic signal assets while leaving the other signals intact.
+- [ ] Duplicate `signal_uid` or non-empty `display_id`, invalid geometry, and invalid placement fields abort reimport without partially replacing GeoJSON outputs.
+- [ ] Blender/Cesium node counts and ids match the enabled features in the final runtime JSON; lights and countdowns continue switching correctly.
+- [ ] Existing road GeoPackage import/reimport behavior and merged scene layer order remain unchanged.
+- [ ] Unit/integration tests cover stable ids, editable-feature validation, override-to-pose reconstruction, auxiliary GeoPackage round-trip, and stage ownership.
+
+## Out Of Scope
+
+- Preserving QGIS edits across a subsequent full `intermediates` rebuild; as with road edits, users must preserve or reapply edits before regenerating the GeoPackage.
+- A complete traffic-controller timing editor or arbitrary multi-phase signal program.
+- Independent editing of each lens or countdown glyph position; those remain derived from the assembly point, heading, and shared layout.
+- Automatically assigning a stable identity to a brand-new signal feature drawn manually in QGIS.
+

.trellis/tasks/archive/2026-08/08-07-qgis-traffic-signal-overrides/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "qgis-traffic-signal-overrides",
+  "name": "qgis-traffic-signal-overrides",
+  "title": "QGIS traffic signal overrides",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "dingkang",
+  "assignee": "dingkang",
+  "createdAt": "2026-08-07",
+  "completedAt": "2026-08-07",
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}

.trellis/tasks/archive/2026-08/08-08-cesium-lane-centered-route/check.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/archive/2026-08/08-08-cesium-lane-centered-route/design.md

@@ -0,0 +1,130 @@
+# 自动匹配 Cesium 巡航车道中心：技术设计
+
+## 设计目标
+
+巡航路线以 osm2streets internal road topology 与已渲染的 Driving lane polygon 为几何事实源。道路区间直接使用 polygon 的中轴，不再对 OSM way 中心线施加固定米数偏移；OSM 只提供原始标签和转向语义，不再作为最终路口拓扑。
+
+## 数据流
+
+```text
+network.json ──▶ internal road/intersection directed graph
+OSM XML ──▶ turn:lanes semantics
+                                  │
+lane_polygons.geojson ──▶ validated Driving lane centerlines
+                                  │
+                                  ▼
+                    maneuver-aware lane selection
+                                  │
+                                  ▼
+       internal road lane sections + surface-constrained junction curves
+                                  │
+                                  ▼
+                      vehicle-route.json + diagnostics
+```
+
+`scripts/build-area.js` 在 preview stage 调用 `buildVehicleRoute(osmPath, lanePolygonsPath)`。`lane_polygons.geojson` 同时写入 preview manifest inputs，`scripts/lib/area-diagnostics.js` 使用既有 SHA-256 freshness 检查自动识别过期路线。
+
+## 模块边界
+
+### `scripts/lib/lane-geometry.js`
+
+新增纯几何共享模块，承载：
+
+- 校验 Driving `Polygon` ring；
+- 通过 polygon 两侧对应顶点中点提取 lane centerline；
+- 米制距离、方向对齐、端点排序和 polyline 拼接所需的无副作用 helper。
+
+`scripts/lib/turn-lane-arrows.js` 改为导入共享 `laneCenterline()`，确保箭头和巡航对 osm2streets polygon 顺序使用同一契约。
+
+### `scripts/lib/vehicle-route.js`
+
+保留现有 OSM 路线拓扑搜索，替换 `LANE_OFFSET_METERS` / `offsetClosedRouteRight()` 路径：
+
+1. 加载并严格校验 `lane_polygons.geojson` 为 FeatureCollection。
+2. 按 `road`、lane `index` 和 `direction=Fwd|Back` 建立 Driving lane 索引；`osm_way_ids` 仅用于追溯 OSM 标签。
+3. 对每条 directed edge，使用实际横向位置按行驶方向排列同向车道；renderer `index` 只作为稳定 tie-breaker，不单独决定车道顺序。
+4. 将 edge 末端的 maneuver 与 `turn:lanes:forward|backward` 对齐。左转/掉头选最左兼容车道，右转选最右兼容车道，直行选最右兼容车道；无显式 lane restriction 时按相同位置规则选择。
+5. 每个 edge 对应一个 osm2streets internal road；禁止把同一 OSM way 下多个 internal road 当作无语义 fragment 直接拼接。
+6. 车道中轴端点之间使用 tangent Bezier / U-turn 连接，并绑定共同的 internal intersection；全部采样点必须落在对应 `intersection_surface` 内或边界容差内。
+7. 任一 edge 无法可靠匹配时丢弃该候选 route；继续搜索其他候选，最多输出 5 条。
+
+## 输出契约
+
+保留顶层 `routes`、兼容别名 `segments`、`loop`、`speedMetersPerSecond`，以及每条路线的 `coordinates`、`centerlineCoordinates`、`edgeIds`、`maneuvers` 和 `lengthMeters`。
+
+每条路线新增 `laneSegments`，每段至少记录：
+
+- `edgeId`、`osmWayId`、`direction`；
+- `laneIndex`、`widthMeters`、`centerOffsetMeters`；
+- `maneuver`、`source="lane_polygon_centerline"`；
+- 参与拼接的 polygon/road 标识。
+
+顶层新增 `diagnostics`，按稳定 reason code 汇总被拒绝的 edge/route，例如 `missing_lane_polygon`、`invalid_lane_polygon`、`ambiguous_lane_order`、`no_compatible_turn_lane` 和 `disconnected_lane_fragments`。固定 `laneOffsetMeters` 不再作为几何输入；为避免伪造单值，不以平均偏移替代逐段事实。
+
+## 错误与降级语义
+
+- 整个 lane polygon 文件缺失、JSON 无法解析或不是 FeatureCollection：preview stage 在写产物前失败。
+- 单个 polygon 无效：记录诊断，该 polygon 不参与匹配。
+- directed edge 缺少唯一可信车道：候选 route 被拒绝，生成器继续选择其他 route。
+- 所有候选都被拒绝：生成合法的空 `routes` 和完整诊断；Cesium 场景仍可加载，但不显示巡航车辆。
+- 禁止回退到固定 `1.3 m`、固定 `1.5 m` 或默认 lane width。
+
+## 兼容性
+
+- Blender scene 经纬度投影改为 WGS84 ECEF→ENU，与 Cesium
+  `eastNorthUpToFixedFrame` 的锚点坐标系一致；这是 route 与最终 GLB 道路重合的必要
+  跨层契约。
+- `segments` 继续与 `routes` 引用相同数组。
+- Cesium runtime 当前只消费 `coordinates` 等既有字段，无需理解 `laneSegments` 即可运行。
+- preview manifest 新增 lane polygon input 后，旧 manifest 会被诊断为缺少记录并要求重建，这是预期迁移行为。
+
+## 验证策略
+
+- 纯几何测试：四边形、曲线 polygon、反向 geometry、坏 ring。
+- 路线 fixture：不同宽度、双向/单向、多车道和转向车道选择。
+- 精度断言：路线道路区间采样点到 polygon 中轴距离不超过 `0.10 m`。
+- 连续性断言：车道变化和路口连接处没有由数据拼接产生的异常横跳。
+- 集成验证：目标区域重跑 preview，检查 route JSON diagnostics、manifest freshness、区域质量门和 Cesium 实际显示。
+- 端到端视觉验证：重跑 `blender,cesium,preview`，对最终画面做道路横截面检查；不能用
+  route 与 lane polygon 的厘米级一致性代替 GLB/Entity 对齐验证。
+
+## Bug Analysis：GLB 与巡航路线随距离漂移
+
+### 1. Root Cause Category
+
+- **Category**：B - Cross-Layer Contract；D - Test Coverage Gap。
+- **Specific Cause**：Blender 使用固定米/度的平面近似，Cesium 使用 WGS84 椭球 ENU；
+  两层没有共享坐标转换契约。
+
+### 2. Why Fixes Failed
+
+1. 固定车道偏移：只处理症状，且假定所有车道宽度相同。
+2. 从 Driving polygon 重建中轴：解决了车道宽度与 lane 选择，但只证明 GeoJSON 内部正确。
+3. 路口切线连接：改善了 connector，却没有解释直线路段整套坐标同向平移。
+
+### 3. Prevention Mechanisms
+
+| Priority | Mechanism | Specific Action | Status |
+|---|---|---|---|
+| P0 | Architecture | `Projector` 使用 WGS84 ECEF→ENU，与 Cesium 锚点一致 | DONE |
+| P0 | Test Coverage | 测试 WGS84 局部经纬度比例与 ENU 方向 | DONE |
+| P1 | Documentation | 在 Blender、preview 与 cross-layer spec 固化契约 | DONE |
+| P1 | Integration | 坐标变更后强制重跑 `blender,cesium,preview` 并视觉核对 | DONE |
+
+### 4. Systematic Expansion
+
+- **Similar Issues**：交通信号、语义模型、route polyline 等所有叠加在 GLB 上的 Cesium
+  Entity 都依赖同一契约。
+- **Design Improvement**：坐标转换只有 `Projector` 一个 Blender 事实源。
+- **Process Improvement**：跨运行时几何必须验证最终组合画面，不能停在单层数值测试。
+
+### 5. Knowledge Capture
+
+- [x] 更新 Blender asset generation spec。
+- [x] 更新 preview vehicle route spec。
+- [x] 更新 cross-layer thinking guide。
+- [x] 增加 `ProjectorTest` WGS84 断言。
+
+## 回滚
+
+代码回滚只涉及 preview 路线生成和共享 JS helper；重跑 preview 即可恢复旧路线产物，不需要重建 Blender/GLB。用户已有区域配置修改保持不动。

.trellis/tasks/archive/2026-08/08-08-cesium-lane-centered-route/implement.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/archive/2026-08/08-08-cesium-lane-centered-route/implement.md

@@ -0,0 +1,43 @@
+# 自动匹配 Cesium 巡航车道中心：实施计划
+
+## 实施顺序
+
+- [x] 1. 新增 `scripts/lib/lane-geometry.js`，从 `turn-lane-arrows.js` 迁移并导出 Driving polygon 中轴提取与必要的纯几何 helper；补充共享几何测试，确认箭头行为不变。
+- [x] 2. 扩展 `scripts/lib/vehicle-route.js` 输入校验和车道索引，按 OSM way、行驶方向、实际横向位置及 maneuver 选择目标 Driving lane。
+- [x] 3. 实现同车道多 fragment 的方向校验、确定性拼接和 lane centerline 路线生成；删除固定偏移路径，加入稳定 reason-code diagnostics 与 `laneSegments` 溯源。
+- [x] 4. 更新 `scripts/test-preview-assets.js` fixture，覆盖 `3.0 m` / `3.5 m`、双向单车道、同向多车道、oneway、正反方向、左/直/右选择、坏 polygon 和缺失匹配。
+- [x] 5. 修改 `scripts/build-area.js`，在任何 preview 写入前校验 `lane_polygons.geojson`，传给路线生成器并记录到 stage manifest inputs。
+- [x] 6. 修改 `scripts/lib/area-diagnostics.js` 的 preview expected inputs，并补充 manifest freshness 回归测试或等价断言。
+- [x] 7. 更新 README 巡航说明，移除固定 `1.3 m` 描述，说明实际车道中轴、跳过语义和诊断字段。
+- [x] 8. 重生成目标区域 preview 路线，检查所有 route 的 lane 溯源、空/拒绝诊断和直线路段 `<= 0.10 m` 中心误差。
+- [x] 9. 将路线拓扑切换到 `network.json` internal road/intersection，并对 connector 执行 `intersection_surface` 越界拒绝；预览仅显示当前选中 route，等待用户做最终视觉复核。
+
+## 当前验证状态
+
+- 目标区域只读生成验证通过：`5` 条路线、`56` 个 lane segment、`116` 个中轴顶点最大误差 `0 m`，覆盖 left/right/through/u_turn，实际 center offset 范围 `1.415–1.588 m`。
+- 第 8、9 步暂未完成：preview stage 在写产物前因既有 `traffic_signal_assemblies.geojson` 和 `traffic_signals.json` 缺失而失败。
+- `check:area` 的 3 个 failure 均来自既有 intermediates/blender/preview manifest stale；修复需要重跑会重建 GeoPackage 的 intermediates，未获用户授权前不执行。
+
+## 验证命令
+
+```bash
+node --check scripts/lib/lane-geometry.js
+node --check scripts/lib/vehicle-route.js
+node --check scripts/lib/turn-lane-arrows.js
+node --check scripts/build-area.js
+npm run test:turn-lane-arrows
+npm run test:preview-assets
+npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages preview
+npm run diagnose:area -- --config config/areas/nantaizi-lake-innovation-valley.json
+npm run check:area -- --config config/areas/nantaizi-lake-innovation-valley.json
+```
+
+若仓库已有覆盖 manifest freshness 的独立测试入口，一并运行；否则在现有最接近的 Node 测试中加入定向断言。
+
+## 风险与检查点
+
+- polygon fragment 拼接是最高风险点：完成第 3 步后先用目标区域做只读匹配统计，确认不会因 osm2streets 分段导致全部路线被拒绝，再继续 stage 集成。
+- 多车道 lane order 不得只依赖 renderer `index`；必须用行驶方向下的实际横向位置验证顺序。
+- 不把 OSM `width` 或默认宽度作为无声回退；任何覆盖率下降必须能从 diagnostics 定位。
+- 不修改用户已有的 `config/areas/nantaizi-lake-innovation-valley.json` Linux 路径变更。
+- 不需要 GLB parity；本任务不改变 Blender/GLB。但必须重跑 preview manifest 和区域质量门。

.trellis/tasks/archive/2026-08/08-08-cesium-lane-centered-route/prd.md

@@ -0,0 +1,49 @@
+# 自动匹配 Cesium 巡航车道中心
+
+## Goal
+
+Cesium 预览巡航路线应根据实际车道数据自动落在所选行车道中心，消除固定横向偏移带来的位置误差，为后续车辆仿真提供可靠的几何基础。
+
+## Background
+
+- `scripts/lib/vehicle-route.js:9` 当前使用固定 `LANE_OFFSET_METERS = 1.3`，并在 `makeRoute()` 中对整条平滑后的道路中心线统一向右偏移。
+- 当前区域的 `lane_polygons.geojson` 中 Driving lane 宽度为 `3.0 m`，单车道中心距道路中心线应为 `1.5 m`，现有路线存在约 `0.2 m` 横向误差。
+- `lane_polygons.geojson` 已包含 `direction`、`width`、`index`、`osm_way_ids` 和车道 polygon；这些数据与最终渲染道路来自同一 osm2streets 中间产物。
+- OSM 输入包含 `lanes`、`lanes:forward`、`lanes:backward` 和 `turn:lanes:*`，但不保证包含明确的 `width`，不能单独作为所有区域的精确宽度来源。
+- 历史提交 `30846b6` 引入连续巡航路线时沿用了实验阶段的 `1.3 m` 固定值，没有建立路线与 osm2streets 车道几何之间的契约。
+
+## Requirements
+
+- R1：路线生成以 osm2streets 实际 Driving lane 数据为主事实源，不再使用全局固定偏移常量。
+- R2：按 OSM way、行驶方向和车道顺序匹配目标车道，并根据各路段的真实宽度及横向位置计算车道中心。
+- R3：不同宽度、不同车道数或不同方向配置的连续道路必须逐路段计算偏移，路口连接处保持连续且不产生横向跳变。
+- R4：多车道路段必须选择一条明确的目标车道；车道选择和转向可行性应使用 `direction`、`index`、`allowed_turns` / `turn:lanes:*` 数据，而不是只看总车道数。
+- R4.1：同向多车道按下一次 maneuver 选择兼容车道；左转/掉头优先最左侧兼容车道，右转优先最右侧兼容车道，直行默认最右侧兼容车道。没有兼容车道时跳过该候选路线并记录诊断。
+- R5：每条输出路线记录所用车道、宽度/偏移来源及诊断信息，使下游能够识别精确匹配、次级推导和跳过的路段。
+- R5.1：缺少、歧义或无法验证车道数据的路段必须跳过并输出结构化诊断；禁止回退到固定偏移或默认车道宽度。
+- R6：保留现有 `routes`、兼容别名 `segments`、闭环路线、信号灯停车和 Cesium 动画消费契约。
+- R7：preview stage manifest 将参与路线计算的车道数据列为输入，使车道几何变化能够正确判定预览产物 stale。
+- R8：不得修改 Blender/GLB 主资产；本任务只修正预览巡航路线及其生成契约。
+
+## Acceptance Criteria
+
+- [x] AC1：当前南台子湖区域重新生成后，普通直线路段的巡航点位于匹配 Driving lane 的几何中心，允许误差不超过 `0.10 m`。
+- [x] AC2：测试 fixture 覆盖至少 `3.0 m`、`3.5 m` 两种车道宽度，输出中心偏移分别随实际车道数据变化，不存在 `1.3 m` 或 `1.5 m` 全局常量依赖。
+- [x] AC3：测试 fixture 覆盖双向单车道、同向多车道、`oneway=yes` 和正反方向，验证目标车道选择及偏移方向正确。
+- [x] AC4：连续路段车道宽度变化或车道数变化时，路线在衔接区连续；相邻采样点不得出现由偏移切换导致的异常横跳。
+- [x] AC5：路线 JSON 能追溯每段匹配到的 `osm_way_ids`、方向、lane index、width、center offset 和数据来源。
+- [ ] AC6：既有 preview asset tests、路线闭环测试和区域质量门通过，信号灯停车与车辆朝向行为不回归。
+- [x] AC7：preview manifest 记录车道数据文件；该文件改变后诊断能够将 preview 标记为 stale。
+
+## Out of Scope
+
+- 车辆在运行时动态换道、超车或避障。
+- 交通流量、车辆间距和碰撞模型。
+- 修改 osm2streets 生成的车道 polygon 或 Blender 道路网格。
+- 将实验性预览巡航升级为通用交通仿真引擎。
+
+## Technical Constraints
+
+- 本任务涉及 OSM、osm2streets GeoJSON、stage manifest 和 Cesium route JSON 的跨层契约，按复杂任务处理；规划收敛后需要 `design.md` 和 `implement.md`。
+- Driving lane polygon 的相对两边中点算法已在 `scripts/lib/turn-lane-arrows.js:265` 验证；巡航路线应复用同一纯几何实现，不维护第二份 polygon 解析逻辑。
+- `preview` 保持可独立执行，但现在明确依赖已有 `lane_polygons.geojson`；车道文件整体缺失或格式无效属于 stage 输入错误，单个路段无法可靠匹配则跳过并写诊断。

.trellis/tasks/archive/2026-08/08-08-cesium-lane-centered-route/research/osm2streets-lane-centers.md

@@ -0,0 +1,23 @@
+# osm2streets 车道中心线研究
+
+## 上游实现
+
+- 调研版本：`osm2streets-js-node 0.1.4`，上游 `osm2streets` commit `fc119c47dac567d030c6ce7c24a48896f58ed906`。
+- `Road::get_untrimmed_center_line()` 先根据 OSM reference line、`reference_line_placement`、道路总宽度和驾驶方向生成 road full-width centerline。
+- `Road::get_lane_center_lines()` 按 `lane_specs_ltr` 从左到右累计真实 lane width，再调用 `center_line.shift_from_center(total_width, width_from_left_side)` 生成每条 lane 的中心线。
+- `to_lane_polygons_geojson()` 先取得上述 lane centerline，再调用 `pl.make_polygons(lane.width)` 生成 Driving polygon。因此 lane polygon 是 lane centerline 的派生产物。
+- `PolyLine::make_polygons()` 使用两侧等距平移和 miter 交点生成 polygon ring；ring 前半边与反向后的后半边一一对应，其中点可恢复原始 lane centerline。
+
+## 当前区域审计
+
+- `54` 个 Driving polygon：`32` 个四边形，其余包含 `6/8/10/18` 个非闭合顶点。
+- 使用 `network.json` 的 `road.center_line`、`lane_specs_ltr` 和 geom miter 算法重建所有 lane centerline。
+- 与 `scripts/lib/lane-geometry.js:laneCenterline()` 结果逐点比较，最大误差为 `0.006 m`。
+- 结论：道路区间的 polygon 中轴提取与 osm2streets 权威 lane centerline 一致，不是肉眼所见大偏移的来源。
+
+## 路口 movement 限制
+
+- osm2streets 的公开 JS API 没有导出可直接用于车辆行驶的 lane-to-lane movement centerline。
+- `debugMovementsFromLaneGeojson()` 只是调试箭头：在双向 road centerline 上使用固定 `1.3 m` 偏移，再用直线连接 road endpoints；它不是 lane-aware 仿真轨迹，不能复用。
+- 当前项目的大偏移排查应限定在：selected lane 与 internal road 的映射、junction connector、U-turn，以及多条闭环 route 同时显示造成的视觉混淆。
+- 后续 connector 必须显式关联 `network.json` 的 internal road/intersection，并受 `intersection_surface.geojson` 约束；不得修改已验证的 lane section centerline。

.trellis/tasks/archive/2026-08/08-08-cesium-lane-centered-route/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "cesium-lane-centered-route",
+  "name": "cesium-lane-centered-route",
+  "title": "自动匹配 Cesium 巡航车道中心",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "que01",
+  "assignee": "que01",
+  "createdAt": "2026-08-08",
+  "completedAt": "2026-08-08",
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}

.trellis/workspace/dingkang/index.md

@@ -8,8 +8,8 @@
 
 <!-- @@@auto:current-status -->
 - **Active File**: `journal-1.md`
-- **Total Sessions**: 25
-- **Last Active**: 2026-08-06
+- **Total Sessions**: 27
+- **Last Active**: 2026-08-07
 <!-- @@@/auto:current-status -->
 
 ---
@@ -19,7 +19,7 @@
 <!-- @@@auto:active-documents -->
 | File | Lines | Status |
 |------|-------|--------|
-| `journal-1.md` | ~533 | Active |
+| `journal-1.md` | ~575 | Active |
 <!-- @@@/auto:active-documents -->
 
 ---
@@ -29,6 +29,8 @@
 <!-- @@@auto:session-history -->
 | # | Date | Title | Commits | Branch |
 |---|------|-------|---------|--------|
+| 27 | 2026-08-07 | QGIS traffic signal editing and countdown stability | `e153a1c` | `main` |
+| 26 | 2026-08-07 | 交通信号拓扑与部分构建同步修复 | `1c077a3` | `main` |
 | 25 | 2026-08-06 | Cesium traffic signal countdowns | `0e1574f` | `main` |
 | 24 | 2026-08-05 | 拆分 LowPoly Cars 车辆资产 | `3108336`, `2489b8a` | `main` |
 | 23 | 2026-08-05 | 车辆连续巡航与转弯 | `30846b6` | `main` |

.trellis/workspace/dingkang/journal-1.md

@@ -531,3 +531,45 @@ Added shared 7LED countdown geometry, split dynamic Cesium assets by phase group
 ### Status
 
 [OK] **Completed**
+
+
+## Session 26: 交通信号拓扑与部分构建同步修复
+
+**Date**: 2026-08-07
+**Task**: 交通信号拓扑与部分构建同步修复
+**Branch**: `main`
+
+### Summary
+
+基于 OSM highway=traffic_signals 控制节点生成 T/十字路口信号，复用共享 OSM 解析；Blender stage 每次重写交通信号锚点，避免部分构建沿用旧 JSON 导致 GLB 与 Cesium 预览 signal id 错位。验证了 nantaizi 区域 35 盏信号、动态/倒计时 GLB、Safari 预览和 preview-assets 测试。
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `1c077a3` | (see git log) |
+
+### Status
+
+[OK] **Completed**
+
+
+## Session 27: QGIS traffic signal editing and countdown stability
+
+**Date**: 2026-08-07
+**Task**: QGIS traffic signal editing and countdown stability
+**Branch**: `main`
+
+### Summary
+
+Implemented editable traffic signal assemblies in QGIS with stable IDs, position/heading overrides, reimport ownership, source validation, and Blender/Cesium runtime derivation. Fixed long signal IDs overflowing Blender node names with short nodeKey values, and changed QGIS SVG symbols to direct heading_deg field rotation so QGIS rotation edits write back to the field. Verified real GeoPackage round-trip, focused Node tests, preview tests, and 59 Blender tests. Safari cache caused stale GLB symptoms and was resolved with a hard refresh.
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `e153a1c` | (see git log) |
+
+### Status
+
+[OK] **Completed**

.trellis/workspace/que01/index.md

@@ -0,0 +1,41 @@
+# Workspace Index - que01
+
+> Journal tracking for AI development sessions.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Active File**: `journal-1.md`
+- **Total Sessions**: 1
+- **Last Active**: 2026-08-08
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|-------|--------|
+| `journal-1.md` | ~28 | Active |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commits | Branch |
+|---|------|-------|---------|--------|
+| 1 | 2026-08-08 | 修正 Cesium 巡航车道中心对齐 | `5658e73` | `main` |
+<!-- @@@/auto:session-history -->
+
+---
+
+## Notes
+
+- Sessions are appended to journal files
+- New journal file created when current exceeds 2000 lines
+- Use `add_session.py` to record sessions

.trellis/workspace/que01/journal-1.md

@@ -0,0 +1,28 @@
+# Journal - que01 (Part 1)
+
+> AI development session journal
+> Started: 2026-08-08
+
+---
+
+
+
+## Session 1: 修正 Cesium 巡航车道中心对齐
+
+**Date**: 2026-08-08
+**Task**: 修正 Cesium 巡航车道中心对齐
+**Branch**: `main`
+
+### Summary
+
+巡航路线改用 osm2streets Driving lane polygon 中轴和 internal road 拓扑；Blender 改用与 Cesium 一致的 WGS84 ECEF 到 ENU 投影，修复随锚点距离增长的整体偏移，并补齐连接器、预览、manifest、投影测试与项目规范。
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `5658e73` | (see git log) |
+
+### Status
+
+[OK] **Completed**

README.md

@@ -113,7 +113,9 @@ outputs/<area-id>/_pipeline/stages/compress.manifest.json
 
 manifest 记录阶段输入/输出文件的 bytes、mtime、sha256、耗时和结构摘要：前段记录 OSM /
 GeoJSON feature counts，Blender 记录 `.blend` / render，Cesium/压缩记录 GLB digest，
-preview 记录 GLB、metadata、车辆路线和 runtime 文件。`diagnose:area` 会读取这些
+preview 记录 GLB、metadata、`lane_polygons.geojson`、`network.json`、`intersection_surface.geojson`、
+车辆路线和 runtime 文件。巡航道路区间按 osm2streets internal road 匹配真实 Driving lane 中轴，
+路口 connector 必须通过 intersection surface 越界检查。`diagnose:area` 会读取这些
 manifest；缺失或当前输入/输出 sha/bytes 不一致会在 `Stage manifests` 和 `Warnings`
 里标出来。
 
@@ -224,7 +226,7 @@ python3 -m http.server 8765
 
 ## 实验：车辆巡航
 
-`preview` 和 `cesium` 阶段会额外生成 `<area-id>-vehicle-route.json` 和 `<area-id>-vehicle-car.gltf`。路线文件从 OSM bounds 内的可行驶 `highway` way 提取道路中心线，并向右偏移约 1.3 米作为车辆行驶线，避免车辆压道路中心线。Cesium 预览页会加载多条道路段并显示多辆实验车辆循环巡航；`Vehicle` 下拉框决定 `Follow` 跟随哪一辆车。
+`preview` 和 `cesium` 阶段会额外生成 `<area-id>-vehicle-route.json` 和 `<area-id>-vehicle-car.gltf`。OSM 提供可行驶拓扑与转向语义，实际巡航坐标来自 osm2streets 的 `Driving` lane polygon 中轴；同向多车道按下一次 maneuver 选择兼容车道。路线中的 `laneSegments` 记录每个 polygon fragment 的 OSM way、方向、lane index、width、center offset 和来源。车道数据缺失、歧义、断裂或没有兼容转向车道时，候选路线会被跳过并写入顶层 `diagnostics`，不会回退到固定偏移或默认宽度。Cesium 预览页会加载多条道路段并显示多辆实验车辆循环巡航；`Vehicle` 下拉框决定 `Follow` 跟随哪一辆车。
 
 这是用于验证高精度巡航可用性的预览层功能，不会改变 Blender/GLB 主资产本身。车辆模型是无 logo 的轻量预览模型，生成在输出目录中。
 

assets/qgis/traffic-signal-direction.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <path d="M 50 96 L 24 50 L 76 50 Z"
+        fill="#e12d37" stroke="#7d0f19" stroke-width="4" stroke-linejoin="round"/>
+</svg>

blender/osmassets/osm.py

@@ -149,23 +149,55 @@ def parse_height(feature_tags, default):
 
 
 class Projector:
-    """Equirectangular projection about the centre of the OSM bounds.
+    """WGS84 ECEF to local ENU projection about the OSM bounds centre.
 
     Output is metres in a local ENU frame (X east, Y north), which is what both
-    the Blender scene and the Cesium GLB are authored in.
+    the Blender scene and the Cesium GLB are authored in.  Cesium places the
+    GLB with eastNorthUpToFixedFrame, so using the same ellipsoid transform is
+    required to keep route coordinates aligned across the whole scene.
     """
 
+    WGS84_A = 6378137.0
+    WGS84_E2 = 6.6943799901413165e-3
+
     def __init__(self, bounds):
         self.bounds = bounds
         self.lon0 = (bounds["min_lon"] + bounds["max_lon"]) / 2
         self.lat0 = (bounds["min_lat"] + bounds["max_lat"]) / 2
-        self.m_per_lat = 111320.0
-        self.m_per_lon = 111320.0 * math.cos(math.radians(self.lat0))
+        self._lon0_rad = math.radians(self.lon0)
+        self._lat0_rad = math.radians(self.lat0)
+        self._sin_lon0 = math.sin(self._lon0_rad)
+        self._cos_lon0 = math.cos(self._lon0_rad)
+        self._sin_lat0 = math.sin(self._lat0_rad)
+        self._cos_lat0 = math.cos(self._lat0_rad)
+        self._origin_ecef = self._ecef(self._lon0_rad, self._lat0_rad)
+
+        denominator = math.sqrt(1.0 - self.WGS84_E2 * self._sin_lat0 ** 2)
+        prime_vertical_radius = self.WGS84_A / denominator
+        meridional_radius = self.WGS84_A * (1.0 - self.WGS84_E2) / denominator ** 3
+        radians_per_degree = math.pi / 180.0
+        self.m_per_lon = prime_vertical_radius * self._cos_lat0 * radians_per_degree
+        self.m_per_lat = meridional_radius * radians_per_degree
 
     def xy(self, lon_lat):
         lon, lat = lon_lat
-        return ((lon - self.lon0) * self.m_per_lon,
-                (lat - self.lat0) * self.m_per_lat)
+        x, y, z = self._ecef(math.radians(lon), math.radians(lat))
+        dx = x - self._origin_ecef[0]
+        dy = y - self._origin_ecef[1]
+        dz = z - self._origin_ecef[2]
+        east = -self._sin_lon0 * dx + self._cos_lon0 * dy
+        north = (-self._sin_lat0 * self._cos_lon0 * dx
+                 - self._sin_lat0 * self._sin_lon0 * dy
+                 + self._cos_lat0 * dz)
+        return east, north
+
+    def _ecef(self, lon_rad, lat_rad):
+        sin_lat = math.sin(lat_rad)
+        cos_lat = math.cos(lat_rad)
+        radius = self.WGS84_A / math.sqrt(1.0 - self.WGS84_E2 * sin_lat ** 2)
+        return (radius * cos_lat * math.cos(lon_rad),
+                radius * cos_lat * math.sin(lon_rad),
+                radius * (1.0 - self.WGS84_E2) * sin_lat)
 
     def inside(self, lon_lat, pad=0.00035):
         lon, lat = lon_lat

blender/osmassets/traffic_signals.py

@@ -129,8 +129,9 @@ def assemble_dynamic(signal_data, projector, collection, materials):
         active_lens_depth = min(0.025, layout["lensDepthMeters"])
         active_lens_radius = layout["lensRadiusMeters"] * 0.88
         active_lens_offset = (layout["lensDepthMeters"] + active_lens_depth) / 2 + 0.003
+        node_key = signal.get("nodeKey") or signal["id"]
         for state in ("red", "yellow", "green"):
-            batch = MeshBatch("TrafficSignalDynamic_%s_%s" % (signal["id"], state), collection, materials[state])
+            batch = MeshBatch("TrafficSignalDynamic_%s_%s" % (node_key, state), collection, materials[state])
             for index in (0, 1, 2):
                 point = pose["lenses"][index]
                 if point["state"] == state:
@@ -149,7 +150,7 @@ def assemble_dynamic(signal_data, projector, collection, materials):
         phase_group = int(signal.get("phaseGroup") or 0) % 2
         for value, mesh in countdown_meshes[phase_group].items():
             objects.append(_countdown_instance(
-                "TrafficSignalDynamic_%s_countdown_%s" % (signal["id"], value),
+                "TrafficSignalDynamic_%s_countdown_%s" % (node_key, value),
                 mesh, collection, text_x, text_y, board_z, lateral, face))
     return objects
 

blender/tests/test_pure.py

@@ -238,14 +238,23 @@ class ProjectorTest(unittest.TestCase):
         self.assertGreater(east, 0.0)
         self.assertGreater(north, 0.0)
 
-    def test_longitude_metres_shrink_with_latitude(self):
-        self.assertAlmostEqual(
-            self.projector.m_per_lon,
-            111320.0 * math.cos(math.radians(30.005)),
-            places=6,
-        )
+    def test_wgs84_local_scale_matches_ellipsoid(self):
+        latitude = math.radians(30.005)
+        denominator = math.sqrt(1.0 - Projector.WGS84_E2 * math.sin(latitude) ** 2)
+        expected_lon = (Projector.WGS84_A / denominator
+                        * math.cos(latitude) * math.pi / 180.0)
+        expected_lat = (Projector.WGS84_A * (1.0 - Projector.WGS84_E2)
+                        / denominator ** 3 * math.pi / 180.0)
+        self.assertAlmostEqual(self.projector.m_per_lon, expected_lon, places=6)
+        self.assertAlmostEqual(self.projector.m_per_lat, expected_lat, places=6)
         self.assertLess(self.projector.m_per_lon, self.projector.m_per_lat)
 
+    def test_projection_matches_local_wgs84_scale(self):
+        east, _ = self.projector.xy((114.006, 30.005))
+        _, north = self.projector.xy((114.005, 30.006))
+        self.assertAlmostEqual(east, self.projector.m_per_lon * 0.001, places=4)
+        self.assertAlmostEqual(north, self.projector.m_per_lat * 0.001, places=4)
+
     def test_inside_honours_the_pad(self):
         self.assertTrue(self.projector.inside((114.005, 30.005)))
         # Default pad is 0.00035 degrees, so just outside the box still counts.

package.json

@@ -16,6 +16,7 @@
     "test:preview-assets": "node scripts/test-preview-assets.js",
     "test:compress-glb": "node scripts/test-compress-glb.js",
     "test:turn-lane-arrows": "node scripts/test-turn-lane-arrows.js",
+    "test:traffic-signals": "node scripts/test-traffic-signals.js",
     "render:turn-lane-arrow-samples": "node scripts/render-turn-lane-arrow-samples.js"
   },
   "dependencies": {

scripts/build-area.js

@@ -153,6 +153,7 @@ function writeDerivedConfig(area) {
     gpkg: area.outputs.gpkg,
     project: area.outputs.qgisProject,
     preview: area.outputs.qgisPreview,
+    trafficSignalAssemblies: area.outputs.trafficSignalAssemblies,
     arrowScale: area.qgis.arrowScale,
     arrowMergeTriangles: area.qgis.arrowMergeTriangles,
     arrowOutlineSimplifyMeters: area.qgis.arrowOutlineSimplifyMeters,
@@ -200,6 +201,7 @@ function buildIntermediates(area) {
       derivedConfig: fileRecord(derivedConfigPath),
       geojsonDir: fileRecord(area.outputs.geojsonDir),
       ...sceneGeojsonRecords(area),
+      trafficSignalAssemblies: fileRecord(area.outputs.trafficSignalAssemblies),
       trafficSignals: fileRecord(area.outputs.trafficSignals),
       gpkg: fileRecord(area.outputs.gpkg),
       qgisProject: fileRecord(area.outputs.qgisProject),
@@ -207,6 +209,7 @@ function buildIntermediates(area) {
     },
     summary: {
       geojson: geojsonFeatureCounts(area),
+      trafficSignalAssemblies: featureCount(area.outputs.trafficSignalAssemblies),
     },
     warnings: [],
   });
@@ -241,10 +244,12 @@ function reimportGpkg(area) {
     outputs: {
       geojsonDir: fileRecord(area.outputs.geojsonDir),
       ...sceneGeojsonRecords(area),
+      trafficSignalAssemblies: fileRecord(area.outputs.trafficSignalAssemblies),
       trafficSignals: fileRecord(area.outputs.trafficSignals),
     },
     summary: {
       geojson: geojsonFeatureCounts(area),
+      trafficSignalAssemblies: featureCount(area.outputs.trafficSignalAssemblies),
     },
     warnings: [],
   });
@@ -253,6 +258,10 @@ function reimportGpkg(area) {
 function buildBlenderScene(area) {
   ensureFile(blenderExecutable(area), "Blender executable");
   ensureFile(path.join(repoRoot, "blender", "generate_scene.py"), "Blender scene generator");
+  ensureFile(area.outputs.trafficSignalAssemblies, "Editable traffic signal assemblies");
+  // Blender consumes the editable assembly layer; OSM only initializes it in
+  // intermediates, so QGIS edits remain authoritative across later stages.
+  writeTrafficSignals(area);
   ensureFile(area.outputs.trafficSignals, "Traffic signal anchors");
   fs.mkdirSync(path.dirname(area.outputs.blend), { recursive: true });
   fs.mkdirSync(path.dirname(area.outputs.render), { recursive: true });
@@ -295,6 +304,7 @@ function buildBlenderScene(area) {
       osm: fileRecord(area.input),
       geojsonDir: fileRecord(area.outputs.geojsonDir),
       ...sceneGeojsonRecords(area),
+      trafficSignalAssemblies: fileRecord(area.outputs.trafficSignalAssemblies),
       trafficSignals: fileRecord(area.outputs.trafficSignals),
     },
     outputs: {
@@ -483,11 +493,19 @@ function writeCesiumPreview(area) {
   ensureFile(area.outputs.glb, "Cesium GLB");
   ensureFile(area.outputs.metadata, "Cesium metadata");
   ensureFile(area.outputs.trafficSignals, "Traffic signal anchors");
+  const lanePolygons = path.join(area.outputs.geojsonDir, "lane_polygons.geojson");
+  const network = path.join(area.outputs.geojsonDir, "network.json");
+  const intersectionSurface = path.join(area.outputs.geojsonDir, "intersection_surface.geojson");
+  ensureFile(lanePolygons, "Driving lane polygons");
+  ensureFile(network, "osm2streets network");
+  ensureFile(intersectionSurface, "Intersection surfaces");
+  // 在创建或覆盖任何 preview 产物前完成权威车道输入的解析与路线计算。
+  const vehicleRoute = buildPreviewVehicleRoute(area.input, lanePolygons, network, intersectionSurface);
   const htmlPath = area.outputs.cesiumPreview;
   const started = Date.now();
   const startedAt = new Date(started).toISOString();
   fs.mkdirSync(path.dirname(htmlPath), { recursive: true });
-  writeVehicleRoute(area);
+  writeVehicleRoute(area, vehicleRoute);
   const vehicleModelNames = writeVehicleModel(area);
   writeCesiumPreviewSupportFiles(path.dirname(htmlPath));
   const glbName = path.basename(area.outputs.glb);
@@ -509,6 +527,9 @@ function writeCesiumPreview(area) {
       osm: fileRecord(area.input),
       glb: fileRecord(area.outputs.glb),
       metadata: fileRecord(area.outputs.metadata),
+      lanePolygons: fileRecord(lanePolygons),
+      network: fileRecord(network),
+      intersectionSurface: fileRecord(intersectionSurface),
       previewCss: fileRecord(path.join(repoRoot, "scripts", "lib", "cesium-preview.css")),
       previewJs: fileRecord(path.join(repoRoot, "scripts", "lib", "cesium-preview.js")),
     },
@@ -524,10 +545,7 @@ function writeCesiumPreview(area) {
 }
 
 function writeTrafficSignals(area) {
-  const signals = readTrafficSignals(
-    path.join(area.outputs.geojsonDir, "vehicle_stop_lines.geojson"),
-    path.join(area.outputs.geojsonDir, "intersection_surface.geojson"),
-  );
+  const signals = readTrafficSignals(area.outputs.trafficSignalAssemblies, area.input);
   fs.writeFileSync(area.outputs.trafficSignals, `${JSON.stringify(signals, null, 2)}\n`);
   console.log(`Traffic signals: ${signals.signals.length} anchors in ${area.outputs.trafficSignals}`);
 }
@@ -536,8 +554,7 @@ function previewRelativePath(fromDir, target) {
   return path.relative(fromDir, target).split(path.sep).join("/");
 }
 
-function writeVehicleRoute(area) {
-  const route = buildPreviewVehicleRoute(area.input);
+function writeVehicleRoute(area, route) {
   fs.mkdirSync(path.dirname(area.outputs.vehicleRoute), { recursive: true });
   fs.writeFileSync(area.outputs.vehicleRoute, `${JSON.stringify(route, null, 2)}\n`);
   console.log(`Vehicle route: ${area.outputs.vehicleRoute}`);

scripts/build-osm2streets-qgis.js

@@ -7,8 +7,10 @@ const { execFileSync } = require("child_process");
 const { JsStreetNetwork } = require("osm2streets-js-node");
 const { qgisPaths } = require("./lib/tool-paths");
 const { buildCustomTurnLaneArrows } = require("./lib/turn-lane-arrows");
+const { readTrafficSignalFeatures } = require("./lib/traffic-signals");
 const {
   SCENE_LAYERS,
+  AUXILIARY_EDIT_LAYERS,
   SCENE_FILE,
   SCENE_STYLE_FILE,
   layerFile,
@@ -39,6 +41,11 @@ const clipPad = Number(config.clipPad);
 const canvasPad = Number(config.canvasPad);
 const previewPad = Number(config.previewPad);
 const layerPrefix = config.layerPrefix || "osm2streets";
+const trafficSignalLayer = AUXILIARY_EDIT_LAYERS.find((layer) => layer.id === "traffic_signal_assemblies");
+if (!trafficSignalLayer) throw new Error("Missing traffic_signal_assemblies auxiliary layer definition");
+const trafficSignalAssembliesPath = path.resolve(
+  config.trafficSignalAssemblies || path.join(outDir, trafficSignalLayer.file),
+);
 
 if (!Number.isFinite(arrowScale) || arrowScale <= 0) {
   throw new Error(`Invalid arrowScale: ${config.arrowScale}`);
@@ -116,6 +123,11 @@ fs.writeFileSync(
 for (const layer of SCENE_LAYERS) {
   writeJson(path.join(outDir, layerFile(layer)), split[layer.splitKey]);
 }
+writeJson(trafficSignalAssembliesPath, readTrafficSignalFeatures(
+  path.join(outDir, "vehicle_stop_lines.geojson"),
+  path.join(outDir, "intersection_surface.geojson"),
+  inputPath,
+));
 if (arrowMergeTriangles) {
   normalizeLaneArrows(path.join(outDir, "lane_arrows_webscale.geojson"), arrowOutlineSimplifyMeters);
   split.laneArrows = JSON.parse(fs.readFileSync(path.join(outDir, "lane_arrows_webscale.geojson"), "utf8"));
@@ -134,6 +146,7 @@ const ogrEnv = qgis.env;
 SCENE_LAYERS.forEach((layer, index) => {
   importLayer(gpkgPath, path.join(outDir, layerFile(layer)), layer.id, index > 0, ogrEnv);
 });
+importLayer(gpkgPath, trafficSignalAssembliesPath, trafficSignalLayer.id, true, ogrEnv);
 
 const qgisScript = path.join(outDir, "_create_qgis_project.py");
 const previewFeature = split.crosswalks.features[0] || split.laneArrows.features[0] || split.roadSurface.features[0];
@@ -149,6 +162,7 @@ fs.writeFileSync(qgisScript, makeQgisScript({
   layerPrefix,
   canvasExtent: config.canvasExtent || extentString(expandBounds(bbox, canvasPad)),
   previewExtent: config.previewExtent || defaultPreviewExtent,
+  trafficSignalSymbolPath: path.join(repoRoot, "assets", "qgis", "traffic-signal-direction.svg"),
 }));
 
 execFileSync(qgisPython, [qgisScript], {
@@ -1437,16 +1451,25 @@ from qgis.PyQt.QtGui import QColor, QImage, QPainter
 from qgis.core import (
     QgsApplication,
     QgsCoordinateReferenceSystem,
+    QgsEditorWidgetSetup,
+    QgsFieldConstraints,
     QgsFillSymbol,
+    QgsMarkerSymbol,
     QgsMapRendererCustomPainterJob,
     QgsMapSettings,
     QgsProject,
+    QgsPalLayerSettings,
+    QgsProperty,
     QgsRectangle,
     QgsSingleSymbolRenderer,
+    QgsSymbolLayer,
+    QgsSvgMarkerSymbolLayer,
+    QgsVectorLayerSimpleLabeling,
     QgsVectorLayer,
 )
 
 QGIS_PREFIX = ${JSON.stringify(options.qgisPrefix)}
+TRAFFIC_SIGNAL_SYMBOL = ${JSON.stringify(options.trafficSignalSymbolPath)}
 GPKG = ${JSON.stringify(options.gpkgPath)}
 PROJECT_PATH = ${JSON.stringify(options.projectPath)}
 PREVIEW_PATH = ${JSON.stringify(options.previewPath)}
@@ -1459,6 +1482,11 @@ try:
 except AttributeError:
     IMAGE_FORMAT = QImage.Format_ARGB32_Premultiplied
 
+try:
+    NOT_NULL_CONSTRAINT = QgsFieldConstraints.Constraint.ConstraintNotNull
+except AttributeError:
+    NOT_NULL_CONSTRAINT = QgsFieldConstraints.ConstraintNotNull
+
 def fill_symbol(color, outline="0,0,0,0", outline_width="0"):
     return QgsFillSymbol.createSimple({
         "color": color,
@@ -1475,6 +1503,38 @@ def make_layer(layer_name, title, color, outline="0,0,0,0", outline_width="0"):
     layer.setRenderer(QgsSingleSymbolRenderer(fill_symbol(color, outline, outline_width)))
     return layer
 
+def make_signal_layer():
+    layer = QgsVectorLayer(f"{GPKG}|layername=traffic_signal_assemblies", f"{LAYER_PREFIX} traffic signal assemblies", "ogr")
+    if not layer.isValid():
+        raise RuntimeError("Invalid traffic signal assemblies layer")
+    symbol = QgsMarkerSymbol()
+    svg_layer = QgsSvgMarkerSymbolLayer(TRAFFIC_SIGNAL_SYMBOL, 9)
+    svg_layer.setDataDefinedProperty(
+        QgsSymbolLayer.Property.Angle,
+        QgsProperty.fromField("heading_deg"),
+    )
+    symbol.changeSymbolLayer(0, svg_layer)
+    layer.setRenderer(QgsSingleSymbolRenderer(symbol))
+    labels = QgsPalLayerSettings()
+    labels.fieldName = "if(trim(display_id) = '', signal_uid, display_id)"
+    labels.isExpression = True
+    layer.setLabeling(QgsVectorLayerSimpleLabeling(labels))
+    layer.setLabelsEnabled(True)
+    for field_name in ("signal_uid", "control_id", "approach_id", "source_way_id", "stop_lon", "stop_lat"):
+        index = layer.fields().indexOf(field_name)
+        if index >= 0:
+            layer.setFieldConstraint(index, NOT_NULL_CONSTRAINT)
+            form = layer.editFormConfig()
+            form.setReadOnly(index, True)
+            layer.setEditFormConfig(form)
+    enabled_index = layer.fields().indexOf("enabled")
+    if enabled_index >= 0:
+        layer.setEditorWidgetSetup(enabled_index, QgsEditorWidgetSetup("CheckBox", {"CheckedState": "1", "UncheckedState": "0"}))
+    phase_index = layer.fields().indexOf("phase_group")
+    if phase_index >= 0:
+        layer.setEditorWidgetSetup(phase_index, QgsEditorWidgetSetup("ValueMap", {"map": [{"Phase 0": 0}, {"Phase 1": 1}]}))
+    return layer
+
 QgsApplication.setPrefixPath(QGIS_PREFIX, True)
 app = QgsApplication([], False)
 app.initQgis()
@@ -1495,12 +1555,16 @@ layers = {
     )
     for spec in LAYER_SPECS
 }
+signal_layer = make_signal_layer()
+layers["traffic_signal_assemblies"] = signal_layer
 draw_order = [spec["id"] for spec in LAYER_SPECS]
 for key in draw_order:
     project.addMapLayer(layers[key], False)
+project.addMapLayer(signal_layer, False)
 root = project.layerTreeRoot()
 for key in draw_order:
     root.insertLayer(0, layers[key])
+root.insertLayer(0, signal_layer)
 if not project.write(PROJECT_PATH):
     raise RuntimeError(f"Failed to write {PROJECT_PATH}")
 

scripts/lib/area-config.js

@@ -58,8 +58,11 @@ function normalizeAreaConfig(raw, options = {}) {
     ),
     vehicleRoute: path.resolve(outputOverrides.vehicleRoute || path.join(areaDir, `${fileStem}-vehicle-route.json`)),
     vehicleModel: path.resolve(outputOverrides.vehicleModel || path.join(areaDir, `${fileStem}-vehicle-car.gltf`)),
-    // Signals are an auxiliary intermediates artifact shared by Blender and
-    // the browser preview. They deliberately are not one of the QGIS layers.
+    trafficSignalAssemblies: path.resolve(
+      outputOverrides.trafficSignalAssemblies || path.join(geojsonDir, "traffic_signal_assemblies.geojson"),
+    ),
+    // Runtime poses are derived from the editable assembly layer and shared by
+    // Blender and the browser preview.
     trafficSignals: path.resolve(outputOverrides.trafficSignals || path.join(geojsonDir, "traffic_signals.json")),
     pipelineDir,
     stageManifestDir: path.resolve(outputOverrides.stageManifestDir || path.join(pipelineDir, "stages")),

scripts/lib/area-diagnostics.js

@@ -327,6 +327,8 @@ function artifactStatus(area) {
     ["GeoPackage", area.outputs.gpkg, true, "file"],
     ["QGIS project", area.outputs.qgisProject, true, "file"],
     ["QGIS preview", area.outputs.qgisPreview, true, "file"],
+    ["Traffic signal assemblies", area.outputs.trafficSignalAssemblies, true, "file"],
+    ["Traffic signal runtime", area.outputs.trafficSignals, true, "file"],
     ["Blend scene", area.outputs.blend, true, "file"],
     ["Render PNG", area.outputs.render, true, "file"],
     ["Cesium GLB", area.outputs.glb, true, "file"],
@@ -400,6 +402,8 @@ function stageManifestStatus(area, configPath = null) {
         derivedConfig,
         geojsonDir: area.outputs.geojsonDir,
         ...sceneGeojsonFiles(area),
+        trafficSignalAssemblies: area.outputs.trafficSignalAssemblies,
+        trafficSignals: area.outputs.trafficSignals,
         gpkg: area.outputs.gpkg,
         qgisProject: area.outputs.qgisProject,
         qgisPreview: optionalExpectedFile(area.outputs.qgisPreview),
@@ -416,6 +420,8 @@ function stageManifestStatus(area, configPath = null) {
       outputs: {
         geojsonDir: area.outputs.geojsonDir,
         ...sceneGeojsonFiles(area),
+        trafficSignalAssemblies: area.outputs.trafficSignalAssemblies,
+        trafficSignals: area.outputs.trafficSignals,
       },
     },
     {
@@ -426,6 +432,8 @@ function stageManifestStatus(area, configPath = null) {
         osm: area.input,
         geojsonDir: area.outputs.geojsonDir,
         ...sceneGeojsonFiles(area),
+        trafficSignalAssemblies: area.outputs.trafficSignalAssemblies,
+        trafficSignals: area.outputs.trafficSignals,
       },
       outputs: {
         blend: area.outputs.blend,
@@ -451,6 +459,9 @@ function stageManifestStatus(area, configPath = null) {
         osm: area.input,
         glb: area.outputs.glb,
         metadata: area.outputs.metadata,
+        lanePolygons: path.join(area.outputs.geojsonDir, "lane_polygons.geojson"),
+        network: path.join(area.outputs.geojsonDir, "network.json"),
+        intersectionSurface: path.join(area.outputs.geojsonDir, "intersection_surface.geojson"),
         previewCss: path.join(path.resolve(__dirname, ".."), "lib", "cesium-preview.css"),
         previewJs: path.join(path.resolve(__dirname, ".."), "lib", "cesium-preview.js"),
       },

scripts/lib/area-preview.js

@@ -50,6 +50,7 @@ function cesiumPreviewHtml(glbName, metadataName, routeName, vehicleModelName, a
         <button type="button" data-view-mode="inspect" aria-pressed="false">Inspect</button>
       </span>
       <label><input id="toggleScene" type="checkbox" checked> Scene</label>
+      <label><input id="toggleBuildingGhost" type="checkbox"> Building ghost</label>
       <span id="assetToggles" class="control-subgroup"></span>
       <span id="semanticToggles" class="control-subgroup hidden"></span>
       <label><input id="toggleRoutes" type="checkbox" checked> Routes</label>

scripts/lib/cesium-preview.js

@@ -8,6 +8,7 @@
   const toggleCruise = document.getElementById("toggleCruise");
   const toggleFollow = document.getElementById("toggleFollow");
   const toggleScene = document.getElementById("toggleScene");
+  const toggleBuildingGhost = document.getElementById("toggleBuildingGhost");
   const toggleRoutes = document.getElementById("toggleRoutes");
   const toggleVehicles = document.getElementById("toggleVehicles");
   const toggleSignals = document.getElementById("toggleSignals");
@@ -66,7 +67,9 @@
   }
 
   async function fetchJson(url) {
-    const response = await fetch(url);
+    // Generated preview JSON keeps a stable filename; bypass browser caches so
+    // route regeneration is visible immediately during inspection.
+    const response = await fetch(url, { cache: "no-store" });
     if (!response.ok) {
       throw new Error("Could not load " + url + ": " + response.status);
     }
@@ -287,8 +290,60 @@
     const hasSemanticAssets = semanticAssets(assets).length > 0;
     const sceneLabel = toggleScene.closest("label");
     let viewMode = "scene";
+    let buildingGhostActive = false;
+
+    async function setBuildingGhost(enabled) {
+      const roads = assets.find((asset) => asset.id === "roads");
+      const buildings = assets.find((asset) => asset.id === "buildings");
+      const props = assets.find((asset) => asset.id === "vegetation");
+      const main = assets.find((asset) => asset.id === "main");
+      if (!roads || !buildings || !props || !main) {
+        toggleBuildingGhost.checked = false;
+        toggleBuildingGhost.disabled = true;
+        return;
+      }
+      if (enabled) {
+        const loaded = await Promise.all([
+          loadAsset(viewer, roads, placement),
+          loadAsset(viewer, buildings, placement),
+          loadAsset(viewer, props, placement),
+        ]);
+        if (!loaded[0] || !loaded[1] || !loaded[2]) {
+          toggleBuildingGhost.checked = false;
+          setStatus("Building transparency unavailable");
+          return;
+        }
+        main.model.show = false;
+        roads.model.show = true;
+        buildings.model.show = true;
+        // The semantic vegetation asset also owns the static traffic-signal
+        // poles/housings from the 05_Props collection.
+        props.model.show = true;
+        buildings.model.color = Cesium.Color.WHITE.withAlpha(0.22);
+        buildings.model.colorBlendMode = Cesium.ColorBlendMode.REPLACE;
+        buildings.model.colorBlendAmount = 1.0;
+        for (const asset of liveAssets(assets)) {
+          if (asset.id !== "main") asset.model.show = asset.category === "dynamic" || asset.category === "countdown"
+            ? toggleSignals.checked : asset.model.show;
+        }
+        trafficSignals.show = toggleSignals.checked;
+        buildingGhostActive = true;
+        setStatus("Buildings transparent");
+      } else {
+        for (const asset of semanticAssets(assets)) {
+          if (asset.model) asset.model.show = false;
+        }
+        main.model.show = toggleScene.checked;
+        for (const asset of liveAssets(assets)) {
+          if (asset.id !== "main") asset.model.show = toggleSignals.checked;
+        }
+        buildingGhostActive = false;
+        setStatus("Buildings opaque");
+      }
+    }
 
     toggleScene.addEventListener("change", () => {
+      if (buildingGhostActive) return;
       for (const asset of liveAssets(assets)) {
         asset.model.show = toggleScene.checked;
         if (asset.toggle) asset.toggle.checked = toggleScene.checked;
@@ -297,7 +352,7 @@
       setStatus(toggleScene.checked ? "Scene visible" : "Scene hidden");
     });
     toggleRoutes.addEventListener("change", () => {
-      for (const vehicle of cruise.vehicles) vehicle.routeEntity.show = toggleRoutes.checked;
+      syncSelectedRouteVisibility(cruise);
     });
     toggleVehicles.addEventListener("change", () => {
       for (const vehicle of cruise.vehicles) vehicle.entity.show = toggleVehicles.checked;
@@ -316,6 +371,14 @@
     toggleDiagnostics.addEventListener("change", () => {
       diagnosticsEl.classList.toggle("hidden", !toggleDiagnostics.checked);
     });
+    toggleBuildingGhost.addEventListener("change", () => {
+      void setBuildingGhost(toggleBuildingGhost.checked);
+    });
+    if (!semanticAssets(assets).some((asset) => asset.id === "roads") ||
+        !semanticAssets(assets).some((asset) => asset.id === "buildings") ||
+        !semanticAssets(assets).some((asset) => asset.id === "vegetation")) {
+      toggleBuildingGhost.disabled = true;
+    }
 
     async function setViewMode(nextMode) {
       if (nextMode === viewMode) return;
@@ -329,6 +392,10 @@
       if (sceneLabel) sceneLabel.classList.toggle("hidden", inspecting);
 
       if (!inspecting) {
+        if (buildingGhostActive) {
+          toggleBuildingGhost.checked = false;
+          await setBuildingGhost(false);
+        }
         for (const asset of semanticAssets(assets)) {
           if (asset.model) asset.model.show = false;
         }
@@ -418,6 +485,7 @@
     });
     vehicleSelect.addEventListener("change", () => {
       cruise.state.selectedIndex = Number(vehicleSelect.value || 0);
+      syncSelectedRouteVisibility(cruise);
       setStatus(selectedVehicle(cruise).label);
     });
 
@@ -462,11 +530,19 @@
       vehicleSelect.appendChild(option);
       return vehicle;
     });
-    return {
+    const cruise = {
       vehicles,
       baseSpeed: speed,
       state: { selectedIndex: 0 }
     };
+    syncSelectedRouteVisibility(cruise);
+    return cruise;
+  }
+
+  function syncSelectedRouteVisibility(cruise) {
+    for (let index = 0; index < cruise.vehicles.length; index += 1) {
+      cruise.vehicles[index].routeEntity.show = toggleRoutes.checked && index === cruise.state.selectedIndex;
+    }
   }
 
   function addTrafficSignals(viewer, signalData, start, assets) {
@@ -482,6 +558,7 @@
       const state = { elapsedSeconds: 0, phase: "" };
       const entities = [];
       const nodes = new Map();
+      const countdownNodes = new WeakMap();
       const node = (name) => {
         if (nodes.has(name)) return nodes.get(name);
         let value = null;
@@ -496,16 +573,29 @@
         if (value) nodes.set(name, value);
         return value;
       };
+      const countdownNode = (model, name) => {
+        let modelNodes = countdownNodes.get(model);
+        if (!modelNodes) {
+          modelNodes = new Map();
+          countdownNodes.set(model, modelNodes);
+        }
+        if (modelNodes.has(name)) return modelNodes.get(name);
+        let value = null;
+        try { value = model.getNode(name); } catch (error) { /* model node table is still loading */ }
+        if (value) modelNodes.set(name, value);
+        return value;
+      };
       const update = (elapsedSeconds) => {
         Cesium.JulianDate.addSeconds(start, elapsedSeconds, phaseTime);
         let changed = false;
         const groupPhases = new Map();
         for (const signal of signals) {
+          const nodeKey = signal.nodeKey || signal.id;
           const phase = signalPhase(signal.phaseGroup, phaseTime, start);
           groupPhases.set(signal.phaseGroup, phase.active);
           if (signal === signals[0]) state.phase = `${phase.active} ${String(phase.remaining).padStart(2, "0")}`;
           for (const state of ["red", "yellow", "green"]) {
-            const value = node(`TrafficSignalDynamic_${signal.id}_${state}`);
+            const value = node(`TrafficSignalDynamic_${nodeKey}_${state}`);
             if (value && value.show !== (state === phase.active)) {
               value.show = state === phase.active;
               changed = true;
@@ -514,9 +604,9 @@
           const visibleCountdown = String(phase.remaining).padStart(2, "0");
           const countdownModel = countdownModels.get(Number(signal.phaseGroup));
           for (let value = 0; value < 20; value += 1) {
-            const name = `TrafficSignalDynamic_${signal.id}_countdown_${String(value).padStart(2, "0")}`;
+            const name = `TrafficSignalDynamic_${nodeKey}_countdown_${String(value).padStart(2, "0")}`;
             let countdown = null;
-            try { countdown = countdownModel.getNode(name); } catch (error) { /* model node table is still loading */ }
+            countdown = countdownNode(countdownModel, name);
             if (countdown && countdown.show !== (String(value).padStart(2, "0") === visibleCountdown)) {
               countdown.show = String(value).padStart(2, "0") === visibleCountdown;
               changed = true;
@@ -544,6 +634,13 @@
       // countdown must remain visibly periodic.
       const timer = setInterval(render, 250);
       render();
+      // Countdown GLBs may expose their node table a few frames after the
+      // model object exists. Re-apply the initial state once both models are
+      // ready so every hidden digit is explicitly hidden before the first
+      // user-visible frame.
+      for (const model of countdownModels.values()) {
+        if (model.readyPromise) model.readyPromise.then(() => update(0)).catch(() => {});
+      }
       return {
         entities, count: signals.length, dynamic, state, timer,
         set show(value) {

scripts/lib/lane-geometry.js

@@ -0,0 +1,161 @@
+"use strict";
+
+const EARTH_RADIUS_METERS = 6371008.8;
+
+function laneCenterline(lane) {
+  const ring = lane?.geometry?.type === "Polygon" ? lane.geometry.coordinates?.[0] : null;
+  if (!Array.isArray(ring) || ring.length < 5 || !sameCoordinate(ring[0], ring.at(-1))) return null;
+  const vertices = ring.slice(0, -1);
+  if (!vertices.every(validCoordinate)) return null;
+  const half = vertices.length / 2;
+  if (!Number.isInteger(half) || half < 2) return null;
+  const centerline = vertices.slice(0, half).map((point, index) => [
+    (point[0] + vertices[vertices.length - 1 - index][0]) / 2,
+    (point[1] + vertices[vertices.length - 1 - index][1]) / 2,
+  ]);
+  return polylineLength(centerline) > 0.01 ? centerline : null;
+}
+
+function orientPolyline(polyline, reference) {
+  if (!polyline?.length || !reference?.length) return null;
+  const forward = projectedDistanceAlong(reference, polyline.at(-1)) - projectedDistanceAlong(reference, polyline[0]);
+  if (Math.abs(forward) < 0.01) return null;
+  return forward > 0 ? polyline.map(copyCoordinate) : [...polyline].reverse().map(copyCoordinate);
+}
+
+function stitchPolylines(polylines, maxGapMeters) {
+  if (!polylines.length) return null;
+  const result = [];
+  for (const polyline of polylines) {
+    if (!polyline?.length) return null;
+    if (result.length && haversineMeters(result.at(-1), polyline[0]) > maxGapMeters) return null;
+    appendCoordinates(result, polyline);
+  }
+  return result;
+}
+
+function projectedDistanceAlong(polyline, point) {
+  let traversed = 0;
+  let best = { distance: Infinity, along: 0, lateral: 0 };
+  for (let index = 1; index < polyline.length; index += 1) {
+    const start = polyline[index - 1];
+    const end = polyline[index];
+    const meters = metersAt((start[1] + end[1]) / 2);
+    const dx = (end[0] - start[0]) * meters.lon;
+    const dy = (end[1] - start[1]) * meters.lat;
+    const px = (point[0] - start[0]) * meters.lon;
+    const py = (point[1] - start[1]) * meters.lat;
+    const length = Math.hypot(dx, dy);
+    if (length < 0.001) continue;
+    const ratio = Math.max(0, Math.min(1, (px * dx + py * dy) / (length * length)));
+    const offsetX = px - dx * ratio;
+    const offsetY = py - dy * ratio;
+    const distance = Math.hypot(offsetX, offsetY);
+    if (distance < best.distance) {
+      const rightX = dy / length;
+      const rightY = -dx / length;
+      best = {
+        distance,
+        along: traversed + length * ratio,
+        lateral: offsetX * rightX + offsetY * rightY,
+      };
+    }
+    traversed += length;
+  }
+  return best.along;
+}
+
+function lateralOffsetFrom(polyline, point) {
+  let best = null;
+  for (let index = 1; index < polyline.length; index += 1) {
+    const start = polyline[index - 1];
+    const end = polyline[index];
+    const meters = metersAt((start[1] + end[1]) / 2);
+    const dx = (end[0] - start[0]) * meters.lon;
+    const dy = (end[1] - start[1]) * meters.lat;
+    const px = (point[0] - start[0]) * meters.lon;
+    const py = (point[1] - start[1]) * meters.lat;
+    const length = Math.hypot(dx, dy);
+    if (length < 0.001) continue;
+    const ratio = Math.max(0, Math.min(1, (px * dx + py * dy) / (length * length)));
+    const offsetX = px - dx * ratio;
+    const offsetY = py - dy * ratio;
+    const distance = Math.hypot(offsetX, offsetY);
+    if (!best || distance < best.distance) {
+      best = { distance, lateral: offsetX * dy / length - offsetY * dx / length };
+    }
+  }
+  return best;
+}
+
+function polylineMidpoint(polyline) {
+  const target = polylineLength(polyline) / 2;
+  let traversed = 0;
+  for (let index = 1; index < polyline.length; index += 1) {
+    const length = haversineMeters(polyline[index - 1], polyline[index]);
+    if (traversed + length >= target) {
+      const ratio = length ? (target - traversed) / length : 0;
+      return [
+        polyline[index - 1][0] + (polyline[index][0] - polyline[index - 1][0]) * ratio,
+        polyline[index - 1][1] + (polyline[index][1] - polyline[index - 1][1]) * ratio,
+      ];
+    }
+    traversed += length;
+  }
+  return polyline.length ? copyCoordinate(polyline.at(-1)) : null;
+}
+
+function polylineLength(polyline) {
+  let total = 0;
+  for (let index = 1; index < (polyline?.length || 0); index += 1) {
+    total += haversineMeters(polyline[index - 1], polyline[index]);
+  }
+  return total;
+}
+
+function haversineMeters(a, b) {
+  const lat1 = degreesToRadians(a[1]);
+  const lat2 = degreesToRadians(b[1]);
+  const dLat = degreesToRadians(b[1] - a[1]);
+  const dLon = degreesToRadians(b[0] - a[0]);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_RADIUS_METERS * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+function appendCoordinates(target, coordinates) {
+  for (const coordinate of coordinates) {
+    if (!sameCoordinate(target.at(-1), coordinate)) target.push(copyCoordinate(coordinate));
+  }
+}
+
+function validCoordinate(value) {
+  return Array.isArray(value) && value.length >= 2 && Number.isFinite(value[0]) && Number.isFinite(value[1]);
+}
+
+function sameCoordinate(a, b) {
+  return Boolean(a && b && a[0] === b[0] && a[1] === b[1]);
+}
+
+function copyCoordinate(coordinate) {
+  return [coordinate[0], coordinate[1]];
+}
+
+function metersAt(latitude) {
+  return { lon: 111320 * Math.cos(degreesToRadians(latitude)), lat: 111320 };
+}
+
+function degreesToRadians(value) {
+  return value * Math.PI / 180;
+}
+
+module.exports = {
+  appendCoordinates,
+  haversineMeters,
+  laneCenterline,
+  lateralOffsetFrom,
+  orientPolyline,
+  polylineLength,
+  polylineMidpoint,
+  projectedDistanceAlong,
+  stitchPolylines,
+};

scripts/lib/osm.js

@@ -0,0 +1,102 @@
+"use strict";
+
+function parseOsm(xml) {
+  const boundsMatch = xml.match(/<bounds\b([^>]*)\/?\s*>/);
+  const boundsAttrs = boundsMatch ? xmlAttrs(boundsMatch[1]) : {};
+  const candidateBounds = {
+    minLon: Number(boundsAttrs.minlon), minLat: Number(boundsAttrs.minlat),
+    maxLon: Number(boundsAttrs.maxlon), maxLat: Number(boundsAttrs.maxlat),
+  };
+  const bounds = Object.values(candidateBounds).every(Number.isFinite) ? candidateBounds : null;
+  const nodes = new Map();
+  const trafficSignalControls = [];
+  const nodePattern = /<node\b([^>]*?)(?:\/>|>([\s\S]*?)<\/node>)/g;
+  for (const match of xml.matchAll(nodePattern)) {
+    const attrs = xmlAttrs(match[1]);
+    if (attrs.action === "delete" || !attrs.id || attrs.lon === undefined || attrs.lat === undefined) continue;
+    const coordinate = [Number(attrs.lon), Number(attrs.lat)];
+    if (!coordinate.every(Number.isFinite)) continue;
+    nodes.set(attrs.id, coordinate);
+    const tags = parseTags(match[2] || "");
+    if (tags.highway === "traffic_signals") {
+      trafficSignalControls.push({ id: attrs.id, longitude: coordinate[0], latitude: coordinate[1], tags });
+    }
+  }
+  const ways = [];
+  for (const match of xml.matchAll(/<way\b([^>]*)>([\s\S]*?)<\/way>/g)) {
+    const attrs = xmlAttrs(match[1]);
+    if (attrs.action === "delete") continue;
+    const body = match[2];
+    const refs = [];
+    for (const ndMatch of body.matchAll(/<nd\b([^>]*)\/?\s*>/g)) {
+      const ref = xmlAttrs(ndMatch[1]).ref;
+      if (ref && nodes.has(ref)) refs.push(ref);
+    }
+    if (refs.length >= 2) ways.push({ id: attrs.id || `way-${ways.length + 1}`, refs, tags: parseTags(body) });
+  }
+  for (const control of trafficSignalControls) {
+    const arms = [];
+    for (const way of ways) {
+      if (!isMotorRoad(way.tags)) continue;
+      for (let index = 0; index < way.refs.length; index += 1) {
+        if (way.refs[index] !== control.id) continue;
+        for (const neighborIndex of [index - 1, index + 1]) {
+          const neighbor = way.refs[neighborIndex];
+          if (!neighbor || !nodes.has(neighbor)) continue;
+          const neighborPoint = nodes.get(neighbor);
+          arms.push({
+            headingDegrees: headingBetween(control, neighborPoint),
+            wayId: String(way.id),
+            neighborNodeId: String(neighbor),
+          });
+        }
+      }
+    }
+    control.arms = dedupeHeadings(arms);
+    control.junctionType = control.arms.length === 3 ? "T" : control.arms.length === 4 ? "cross" : "other";
+  }
+  return { bounds, nodes, ways, trafficSignalControls };
+}
+
+function isMotorRoad(tags) {
+  const highway = tags.highway || "";
+  return highway && tags.area !== "yes" && !new Set([
+    "footway", "path", "pedestrian", "steps", "cycleway", "service", "track",
+    "bridleway", "corridor", "elevator", "platform", "construction",
+  ]).has(highway);
+}
+
+function headingBetween(from, to) {
+  const latitude = (from.latitude + to[1]) / 2 * Math.PI / 180;
+  return Math.atan2((to[0] - from.longitude) * Math.cos(latitude), to[1] - from.latitude) * 180 / Math.PI;
+}
+
+function dedupeHeadings(arms) {
+  const normalized = (value) => ((value % 360) + 360) % 360;
+  const distance = (a, b) => Math.abs(((a - b + 540) % 360) - 180);
+  const result = [];
+  for (const arm of arms) {
+    arm.headingDegrees = normalized(arm.headingDegrees);
+    if (!result.some((other) => distance(other.headingDegrees, arm.headingDegrees) <= 25)) result.push(arm);
+  }
+  return result.sort((a, b) => a.headingDegrees - b.headingDegrees);
+}
+
+function xmlAttrs(text) {
+  const attrs = {};
+  for (const match of text.matchAll(/([:\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    attrs[match[1]] = match[2] !== undefined ? match[2] : match[3];
+  }
+  return attrs;
+}
+
+function parseTags(body) {
+  const tags = {};
+  for (const match of body.matchAll(/<tag\b([^>]*)\/?\s*>/g)) {
+    const tag = xmlAttrs(match[1]);
+    if (tag.k) tags[tag.k] = tag.v || "";
+  }
+  return tags;
+}
+
+module.exports = { parseOsm };

scripts/lib/scene-layers.js

@@ -97,6 +97,17 @@ const SCENE_LAYERS = [
   },
 ];
 
+// Editable control layers share the GeoPackage/QGIS lifecycle but never enter
+// the merged render scene or its draw order.
+const AUXILIARY_EDIT_LAYERS = [
+  {
+    id: "traffic_signal_assemblies",
+    file: "traffic_signal_assemblies.geojson",
+    title: "traffic signal assemblies",
+    geometry: "Point",
+  },
+];
+
 const SCENE_FILE = "osm2streets_scene.geojson";
 const SCENE_STYLE_FILE = "osm2streets_scene_style.json";
 
@@ -155,6 +166,7 @@ function qgisRgba(hex, alpha = 255) {
 
 module.exports = {
   SCENE_LAYERS,
+  AUXILIARY_EDIT_LAYERS,
   SCENE_FILE,
   SCENE_STYLE_FILE,
   layerFile,

scripts/lib/traffic-signals.js

@@ -1,43 +1,29 @@
 "use strict";
 
 const fs = require("fs");
+const crypto = require("crypto");
+const { parseOsm } = require("./osm");
 
 const EARTH_RADIUS = 6371008.8;
 const CURB_OFFSET_METERS = 5.2;
 const MAST_REACH_METERS = 4.5;
-// This layout is serialized with the anchors so Blender's static structure and
-// Cesium's dynamic overlay cannot independently drift in size or handedness.
-// Lateral offsets use the approach travel direction: positive is the driver's
-// right. The countdown board therefore sits at +1.15m from the signal head.
 const SIGNAL_LAYOUT = Object.freeze({
-  poleHeightMeters: 6.7,
-  poleRadiusMeters: 0.13,
-  armWidthMeters: 0.21,
-  // The mast arm and the signal head share this centre elevation.
-  mastHeightMeters: 6.25,
-  headCenterHeightMeters: 6.25,
-  headWidthMeters: 0.68,
-  headDepthMeters: 0.30,
-  headBodyHeightMeters: 1.62,
-  lensRadiusMeters: 0.22,
-  lensDepthMeters: 0.07,
-  lensFaceOffsetMeters: 0.18,
+  poleHeightMeters: 6.7, poleRadiusMeters: 0.13, armWidthMeters: 0.21,
+  mastHeightMeters: 6.25, headCenterHeightMeters: 6.25,
+  headWidthMeters: 0.68, headDepthMeters: 0.30, headBodyHeightMeters: 1.62,
+  lensRadiusMeters: 0.22, lensDepthMeters: 0.07, lensFaceOffsetMeters: 0.18,
   lensVerticalOffsetsMeters: [0.49, -0.01, -0.51],
-  countdownLateralMeters: 1.15,
-  countdownFaceOffsetMeters: 0.05,
-  countdownWidthMeters: 0.82,
-  countdownDepthMeters: 0.14,
-  countdownHeightMeters: 0.56,
-  // The countdown board is fixed on the mast arm, not hung below it.
-  countdownVerticalOffsetMeters: 0.0,
+  countdownLateralMeters: 1.15, countdownFaceOffsetMeters: 0.05,
+  countdownWidthMeters: 0.82, countdownDepthMeters: 0.14,
+  countdownHeightMeters: 0.56, countdownVerticalOffsetMeters: 0.0,
 });
 
-function buildTrafficSignals(stopLines, intersections) {
+function buildTrafficSignalFeatures(stopLines, intersections, controls = []) {
   const centers = (intersections.features || []).map((feature, index) => {
     const point = polygonCenter(feature.geometry);
     return { id: `intersection-${index + 1}`, point, radius: polygonRadius(feature.geometry, point) };
   }).filter((entry) => entry.point);
-  const signals = [];
+  const candidates = [];
   for (const feature of stopLines.features || []) {
     const center = polygonCenter(feature.geometry);
     if (!center) continue;
@@ -45,102 +31,238 @@ function buildTrafficSignals(stopLines, intersections) {
     if (!intersection || metersBetween(center, intersection.point) > 32) continue;
     const axis = roadAxis(feature.geometry, center, intersection.point);
     if (!axis) continue;
-    // A vehicle signal belongs beyond the junction, facing back toward the
-    // approaching stop line. Use the far edge of the intersection, never the
-    // near-side stop-line area where it would read as a pedestrian signal.
     const right = [axis[1], -axis[0]];
     const farSide = moveMeters(intersection.point, axis, intersection.radius + 3.2);
-    // The pole is on the far-side sidewalk, not at the stop line or inside
-    // the intersection. Its mast then reaches back above the approach lanes.
-    const point = moveMeters(farSide, right, CURB_OFFSET_METERS);
-    signals.push({
-      id: `signal-${signals.length + 1}`,
-      intersectionId: intersection.id,
-      phaseGroup: signals.length % 2,
-      longitude: point[0],
-      latitude: point[1],
-      stopLongitude: center[0],
-      stopLatitude: center[1],
-      headingDegrees: Math.atan2(axis[0], axis[1]) * 180 / Math.PI,
-      mastReachMeters: MAST_REACH_METERS,
-      pose: buildSignalPose(point, axis, MAST_REACH_METERS),
+    candidates.push({
+      intersectionId: intersection.id, center, axis,
+      point: moveMeters(farSide, right, CURB_OFFSET_METERS),
+      headingDegrees: normalizeDegrees(Math.atan2(axis[0], axis[1]) * 180 / Math.PI),
     });
   }
+  const features = [];
+  for (const control of controls) {
+    const controlPoint = [Number(control.longitude), Number(control.latitude)];
+    if (!controlPoint.every(Number.isFinite) || !Array.isArray(control.arms) || control.arms.length < 3) continue;
+    const intersection = nearestCenter(controlPoint, centers);
+    if (!intersection || metersBetween(controlPoint, intersection.point) > 32) continue;
+    const arms = matchOsmArms(candidates.filter((item) => item.intersectionId === intersection.id), controlPoint, control.arms);
+    const groups = phaseGroups(arms);
+    arms.forEach((candidate, index) => {
+      const fallbackArmId = `heading-${Math.round(normalizeDegrees(candidate.osmArm?.headingDegrees || 0) * 1000)}`;
+      const sourceWayId = String(candidate.osmArm?.wayId || "legacy");
+      const neighborNodeId = String(candidate.osmArm?.neighborNodeId || fallbackArmId);
+      const approachId = `${sourceWayId}:${neighborNodeId}`;
+      const signalUid = `osm-${String(control.id)}-${sourceWayId}-${neighborNodeId}`;
+      features.push({
+        type: "Feature",
+        geometry: { type: "Point", coordinates: candidate.point.slice() },
+        properties: {
+          signal_uid: signalUid, display_id: signalUid, control_id: String(control.id),
+          approach_id: approachId, source_way_id: sourceWayId,
+          heading_deg: candidate.headingDegrees, phase_group: groups[index],
+          mast_reach_m: MAST_REACH_METERS,
+          stop_lon: candidate.center[0], stop_lat: candidate.center[1],
+          enabled: true, z_offset_m: 0,
+        },
+      });
+    });
+  }
+  return validateTrafficSignalFeatures({ type: "FeatureCollection", features });
+}
+
+function validateTrafficSignalFeatures(collection) {
+  if (collection?.type !== "FeatureCollection" || !Array.isArray(collection.features)) {
+    throw new Error("Traffic signal assemblies must be a FeatureCollection");
+  }
+  const uids = new Set();
+  const displayIds = new Set();
+  const features = collection.features.map((feature, index) => {
+    const label = `traffic signal feature ${index + 1}`;
+    if (feature?.geometry?.type !== "Point" || !Array.isArray(feature.geometry.coordinates) ||
+        feature.geometry.coordinates.length < 2 || !feature.geometry.coordinates.slice(0, 2).every(Number.isFinite)) {
+      throw new Error(`${label}: geometry must be a finite Point`);
+    }
+    const input = feature.properties || {};
+    const text = (key, required = true) => {
+      const value = input[key] == null ? "" : String(input[key]).trim();
+      if (required && !value) throw new Error(`${label}: missing ${key}`);
+      return value;
+    };
+    const number = (key, options = {}) => {
+      if (input[key] === null || input[key] === undefined || input[key] === "") {
+        throw new Error(`${label}: missing ${key}`);
+      }
+      const value = Number(input[key]);
+      if (!Number.isFinite(value) || (options.min != null && value < options.min) || (options.max != null && value > options.max)) {
+        throw new Error(`${label}: invalid ${key} '${input[key]}'`);
+      }
+      return value;
+    };
+    const signalUid = text("signal_uid");
+    if (!/^osm-[A-Za-z0-9_.:-]+$/.test(signalUid)) throw new Error(`${label}: invalid signal_uid '${signalUid}'`);
+    if (uids.has(signalUid)) throw new Error(`Duplicate signal_uid '${signalUid}'`);
+    uids.add(signalUid);
+    const displayId = text("display_id", false);
+    if (displayId && displayIds.has(displayId)) throw new Error(`Duplicate display_id '${displayId}'`);
+    if (displayId) displayIds.add(displayId);
+    const phaseGroup = number("phase_group", { min: 0, max: 1 });
+    if (!Number.isInteger(phaseGroup)) throw new Error(`${label}: phase_group must be 0 or 1`);
+    const enabled = normalizeBoolean(input.enabled, label);
+    const controlId = text("control_id");
+    const approachId = text("approach_id");
+    const sourceWayId = text("source_way_id");
+    if (!approachId.startsWith(`${sourceWayId}:`)) throw new Error(`${label}: approach_id does not match source_way_id`);
+    const expectedUid = `osm-${controlId}-${approachId.replace(":", "-")}`;
+    if (signalUid !== expectedUid) throw new Error(`${label}: signal_uid does not match source identity (expected '${expectedUid}')`);
+    return {
+      type: "Feature",
+      geometry: { type: "Point", coordinates: feature.geometry.coordinates.slice(0, 2).map(Number) },
+      properties: {
+        ...input, signal_uid: signalUid, display_id: displayId,
+        control_id: controlId, approach_id: approachId,
+        source_way_id: sourceWayId, heading_deg: normalizeDegrees(number("heading_deg")),
+        phase_group: phaseGroup, mast_reach_m: number("mast_reach_m", { min: 0.1, max: 30 }),
+        stop_lon: number("stop_lon", { min: -180, max: 180 }),
+        stop_lat: number("stop_lat", { min: -90, max: 90 }),
+        enabled, z_offset_m: number("z_offset_m", { min: -20, max: 100 }),
+      },
+    };
+  });
+  return { type: "FeatureCollection", features };
+}
+
+function buildTrafficSignalsFromFeatures(collection) {
+  const normalized = validateTrafficSignalFeatures(collection);
+  const signals = normalized.features.filter((feature) => feature.properties.enabled).map((feature) => {
+    const p = feature.properties;
+    const point = feature.geometry.coordinates;
+    const axis = headingVector(p.heading_deg);
+    return {
+      id: p.signal_uid, signalUid: p.signal_uid, displayId: p.display_id,
+      nodeKey: signalNodeKey(p.signal_uid),
+      controlId: p.control_id, approachId: p.approach_id, sourceWayId: p.source_way_id,
+      phaseGroup: p.phase_group, longitude: point[0], latitude: point[1],
+      stopLongitude: p.stop_lon, stopLatitude: p.stop_lat,
+      headingDegrees: p.heading_deg, mastReachMeters: p.mast_reach_m,
+      zOffsetMeters: p.z_offset_m,
+      pose: buildSignalPose(point, axis, p.mast_reach_m, p.z_offset_m),
+    };
+  });
   return { version: 3, layout: SIGNAL_LAYOUT, signals };
 }
 
-function buildSignalPose(pole, axis, mastReach) {
-  const lateral = [axis[1], -axis[0]];
-  const face = [-axis[0], -axis[1]];
-  const head = moveMeters(pole, lateral, -mastReach);
-  const faceHeadingDegrees = Math.atan2(face[0], face[1]) * 180 / Math.PI;
-  const position = (point, height) => ({ longitude: point[0], latitude: point[1], height });
-  const lensPoint = moveMeters(head, face, SIGNAL_LAYOUT.lensFaceOffsetMeters);
-  const board = moveMeters(
-    moveMeters(head, lateral, SIGNAL_LAYOUT.countdownLateralMeters),
-    face, SIGNAL_LAYOUT.countdownFaceOffsetMeters,
-  );
-  return {
-    pole: position(pole, 0),
-    arm: {
-      from: position(pole, SIGNAL_LAYOUT.mastHeightMeters),
-      to: position(head, SIGNAL_LAYOUT.mastHeightMeters),
-    },
-    head: { ...position(head, SIGNAL_LAYOUT.headCenterHeightMeters), faceHeadingDegrees },
-    lenses: ["red", "yellow", "green"].map((state, index) => ({
-      state,
-      ...position(lensPoint, SIGNAL_LAYOUT.headCenterHeightMeters + SIGNAL_LAYOUT.lensVerticalOffsetsMeters[index]),
-    })),
-    countdown: { ...position(board, SIGNAL_LAYOUT.mastHeightMeters), faceHeadingDegrees },
-  };
+function signalNodeKey(signalUid) {
+  return `ts_${crypto.createHash("sha256").update(signalUid).digest("hex").slice(0, 16)}`;
 }
 
-function readTrafficSignals(stopLinePath, intersectionPath) {
-  return buildTrafficSignals(JSON.parse(fs.readFileSync(stopLinePath, "utf8")), JSON.parse(fs.readFileSync(intersectionPath, "utf8")));
-}
-
-function polygonCenter(geometry) {
-  const ring = geometry?.type === "Polygon" ? geometry.coordinates?.[0] : null;
-  if (!ring || ring.length < 4) return null;
-  const points = ring.slice(0, -1);
-  return [points.reduce((sum, point) => sum + point[0], 0) / points.length, points.reduce((sum, point) => sum + point[1], 0) / points.length];
-}
-
-function polygonRadius(geometry, center) {
-  const ring = geometry?.type === "Polygon" ? geometry.coordinates?.[0] : null;
-  if (!ring || !center) return 0;
-  return Math.max(...ring.slice(0, -1).map((point) => metersBetween(center, point)), 0);
-}
-
-function roadAxis(geometry, center, target) {
-  const ring = geometry?.coordinates?.[0];
-  if (!ring || ring.length < 3) return null;
-  let longest = null;
-  for (let i = 0; i < ring.length - 1; i += 1) {
-    const dx = (ring[i + 1][0] - ring[i][0]) * Math.cos(center[1] * Math.PI / 180);
-    const dy = ring[i + 1][1] - ring[i][1];
-    const length = Math.hypot(dx, dy);
-    if (!longest || length > longest.length) longest = { dx, dy, length };
+function validateTrafficSignalSourceReferences(collection, controls) {
+  const normalized = validateTrafficSignalFeatures(collection);
+  const approachesByControl = new Map((controls || []).map((control) => [
+    String(control.id),
+    new Set((control.arms || []).map((arm) => `${String(arm.wayId)}:${String(arm.neighborNodeId)}`)),
+  ]));
+  for (const [index, feature] of normalized.features.entries()) {
+    const { control_id: controlId, approach_id: approachId } = feature.properties;
+    const approaches = approachesByControl.get(controlId);
+    if (!approaches) {
+      throw new Error(`traffic signal feature ${index + 1}: control_id '${controlId}' is not present in the current OSM`);
     }
-  if (!longest?.length) return null;
-  let axis = [-longest.dy / longest.length, longest.dx / longest.length];
-  const toward = [(target[0] - center[0]) * Math.cos(center[1] * Math.PI / 180), target[1] - center[1]];
-  if (axis[0] * toward[0] + axis[1] * toward[1] < 0) axis = [-axis[0], -axis[1]];
-  return axis;
+    if (!approaches.has(approachId)) {
+      throw new Error(
+        `traffic signal feature ${index + 1}: approach_id '${approachId}' is not present on OSM control '${controlId}'`,
+      );
+    }
+  }
+  return normalized;
 }
 
-function nearestCenter(point, centers) {
-  return centers.map((entry) => ({ ...entry, distance: metersBetween(point, entry.point) })).sort((a, b) => a.distance - b.distance)[0] || null;
+function buildTrafficSignals(stopLines, intersections, controls = []) {
+  return buildTrafficSignalsFromFeatures(buildTrafficSignalFeatures(stopLines, intersections, controls));
 }
 
-function metersBetween(a, b) {
-  const lat = (a[1] + b[1]) / 2 * Math.PI / 180;
-  return Math.hypot((a[0] - b[0]) * Math.cos(lat), a[1] - b[1]) * Math.PI / 180 * EARTH_RADIUS;
+function readTrafficSignalFeatures(stopLinePath, intersectionPath, osmPath) {
+  const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
+  return buildTrafficSignalFeatures(
+    JSON.parse(fs.readFileSync(stopLinePath, "utf8")),
+    JSON.parse(fs.readFileSync(intersectionPath, "utf8")), controls,
+  );
 }
 
-function moveMeters(point, vector, meters) {
-  const scale = 180 / Math.PI / EARTH_RADIUS;
-  return [point[0] + vector[0] * meters * scale / Math.cos(point[1] * Math.PI / 180), point[1] + vector[1] * meters * scale];
+function readTrafficSignals(editablePath, osmPath = null) {
+  const collection = JSON.parse(fs.readFileSync(editablePath, "utf8"));
+  if (osmPath) {
+    const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
+    validateTrafficSignalSourceReferences(collection, controls);
+  }
+  return buildTrafficSignalsFromFeatures(collection);
 }
 
-module.exports = { SIGNAL_LAYOUT, buildTrafficSignals, readTrafficSignals };
+function normalizeBoolean(value, label) {
+  if (value === true || value === 1 || value === "1" || String(value).toLowerCase() === "true" || String(value).toLowerCase() === "yes") return true;
+  if (value === false || value === 0 || value === "0" || String(value).toLowerCase() === "false" || String(value).toLowerCase() === "no") return false;
+  throw new Error(`${label}: invalid enabled '${value}'`);
+}
+
+function uniqueApproachArms(candidates, controlPoint) {
+  const sorted = candidates.map((candidate) => ({ ...candidate, armHeading: normalizeDegrees(headingBetween(controlPoint, candidate.center)), controlDistance: metersBetween(controlPoint, candidate.center) }))
+    .sort((a, b) => a.armHeading - b.armHeading || a.controlDistance - b.controlDistance);
+  const arms = [];
+  for (const candidate of sorted) if (!arms.some((arm) => angularDistance(arm.armHeading, candidate.armHeading) <= 25)) arms.push(candidate);
+  return arms;
+}
+
+function matchOsmArms(candidates, controlPoint, osmArms) {
+  const remaining = candidates.map((candidate) => ({ ...candidate, armHeading: normalizeDegrees(headingBetween(controlPoint, candidate.center)) }));
+  if (!osmArms.length) return uniqueApproachArms(remaining, controlPoint);
+  return osmArms.map((osmArm) => {
+    let bestIndex = -1; let bestDistance = Infinity;
+    remaining.forEach((item, index) => { const distance = angularDistance(item.armHeading, osmArm.headingDegrees); if (distance < bestDistance) { bestDistance = distance; bestIndex = index; } });
+    const candidate = bestIndex >= 0 && bestDistance <= 45 ? remaining.splice(bestIndex, 1)[0] : fallbackCandidate(controlPoint, osmArm);
+    return { ...candidate, osmArm };
+  });
+}
+
+function fallbackCandidate(controlPoint, osmArm) {
+  const outward = headingVector(osmArm.headingDegrees); const axis = [-outward[0], -outward[1]];
+  const center = moveMeters(controlPoint, outward, 8); const farSide = moveMeters(controlPoint, axis, 3.2);
+  return { center, axis, point: moveMeters(farSide, [axis[1], -axis[0]], CURB_OFFSET_METERS), armHeading: normalizeDegrees(osmArm.headingDegrees), headingDegrees: normalizeDegrees(Math.atan2(axis[0], axis[1]) * 180 / Math.PI), fallback: true };
+}
+
+function phaseGroups(arms) {
+  const groups = Array(arms.length).fill(1); if (arms.length < 2) return groups;
+  let main = [0, 1]; let best = -1;
+  for (let a = 0; a < arms.length; a += 1) for (let b = a + 1; b < arms.length; b += 1) { const opposition = angularDistance(arms[a].armHeading, arms[b].armHeading); if (opposition > best) { best = opposition; main = [a, b]; } }
+  groups[main[0]] = 0; groups[main[1]] = 0; return groups;
+}
+
+function buildSignalPose(pole, axis, mastReach, zOffset = 0) {
+  const lateral = [axis[1], -axis[0]]; const face = [-axis[0], -axis[1]];
+  const head = moveMeters(pole, lateral, -mastReach); const faceHeadingDegrees = Math.atan2(face[0], face[1]) * 180 / Math.PI;
+  const position = (point, height) => ({ longitude: point[0], latitude: point[1], height: height + zOffset });
+  const lensPoint = moveMeters(head, face, SIGNAL_LAYOUT.lensFaceOffsetMeters);
+  const board = moveMeters(moveMeters(head, lateral, SIGNAL_LAYOUT.countdownLateralMeters), face, SIGNAL_LAYOUT.countdownFaceOffsetMeters);
+  return { pole: position(pole, 0), arm: { from: position(pole, SIGNAL_LAYOUT.mastHeightMeters), to: position(head, SIGNAL_LAYOUT.mastHeightMeters) }, head: { ...position(head, SIGNAL_LAYOUT.headCenterHeightMeters), faceHeadingDegrees }, lenses: ["red", "yellow", "green"].map((state, index) => ({ state, ...position(lensPoint, SIGNAL_LAYOUT.headCenterHeightMeters + SIGNAL_LAYOUT.lensVerticalOffsetsMeters[index]) })), countdown: { ...position(board, SIGNAL_LAYOUT.mastHeightMeters), faceHeadingDegrees } };
+}
+
+function polygonCenter(geometry) { const ring = geometry?.type === "Polygon" ? geometry.coordinates?.[0] : null; if (!ring || ring.length < 4) return null; const points = ring.slice(0, -1); return [points.reduce((s, p) => s + p[0], 0) / points.length, points.reduce((s, p) => s + p[1], 0) / points.length]; }
+function polygonRadius(geometry, center) { const ring = geometry?.type === "Polygon" ? geometry.coordinates?.[0] : null; return ring && center ? Math.max(...ring.slice(0, -1).map((point) => metersBetween(center, point)), 0) : 0; }
+function roadAxis(geometry, center, target) { const ring = geometry?.coordinates?.[0]; if (!ring || ring.length < 3) return null; let longest; for (let i = 0; i < ring.length - 1; i += 1) { const dx = (ring[i + 1][0] - ring[i][0]) * Math.cos(center[1] * Math.PI / 180); const dy = ring[i + 1][1] - ring[i][1]; const length = Math.hypot(dx, dy); if (!longest || length > longest.length) longest = { dx, dy, length }; } if (!longest?.length) return null; let axis = [-longest.dy / longest.length, longest.dx / longest.length]; const toward = [(target[0] - center[0]) * Math.cos(center[1] * Math.PI / 180), target[1] - center[1]]; if (axis[0] * toward[0] + axis[1] * toward[1] < 0) axis = [-axis[0], -axis[1]]; return axis; }
+function nearestCenter(point, centers) { return centers.map((entry) => ({ ...entry, distance: metersBetween(point, entry.point) })).sort((a, b) => a.distance - b.distance)[0] || null; }
+function metersBetween(a, b) { const lat = (a[1] + b[1]) / 2 * Math.PI / 180; return Math.hypot((a[0] - b[0]) * Math.cos(lat), a[1] - b[1]) * Math.PI / 180 * EARTH_RADIUS; }
+function moveMeters(point, vector, meters) { const scale = 180 / Math.PI / EARTH_RADIUS; return [point[0] + vector[0] * meters * scale / Math.cos(point[1] * Math.PI / 180), point[1] + vector[1] * meters * scale]; }
+function headingBetween(from, to) { const latitude = (from[1] + to[1]) / 2 * Math.PI / 180; return Math.atan2((to[0] - from[0]) * Math.cos(latitude), to[1] - from[1]) * 180 / Math.PI; }
+function headingVector(degrees) { const radians = degrees * Math.PI / 180; return [Math.sin(radians), Math.cos(radians)]; }
+function normalizeDegrees(value) { return ((value % 360) + 360) % 360; }
+function angularDistance(a, b) { return Math.abs(((a - b + 540) % 360) - 180); }
+
+module.exports = {
+  SIGNAL_LAYOUT,
+  signalNodeKey,
+  buildTrafficSignalFeatures,
+  validateTrafficSignalFeatures,
+  validateTrafficSignalSourceReferences,
+  buildTrafficSignalsFromFeatures,
+  buildTrafficSignals,
+  readTrafficSignalFeatures,
+  readTrafficSignals,
+};

scripts/lib/turn-lane-arrows.js

@@ -2,6 +2,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const { laneCenterline } = require("./lane-geometry");
 
 const ASSET_MANIFEST = path.resolve(__dirname, "..", "..", "assets", "lane-icons", "manifest.json");
 const LANE_WIDTH_METERS = 3.2;
@@ -262,23 +263,6 @@ function closestPointOnSegment(point, start, end, meters) {
   return [start[0] + ratio * (end[0] - start[0]), start[1] + ratio * (end[1] - start[1])];
 }
 
-function laneCenterline(lane) {
-  const ring = lane?.geometry?.type === "Polygon" ? lane.geometry.coordinates?.[0] : null;
-  // A straight osm2streets Driving lane is commonly a closed quadrilateral:
-  // four distinct vertices plus the repeated closing vertex. Its opposing
-  // edges still provide the same two-point centerline as longer lane shapes.
-  if (!ring || ring.length < 5) return null;
-  // osm2streets Driving polygons are ordered along one boundary then back
-  // along the other. Midpoints of paired vertices form the rendered lane axis.
-  const vertices = ring.slice(0, -1);
-  const half = vertices.length / 2;
-  if (!Number.isInteger(half) || half < 2) return null;
-  return vertices.slice(0, half).map((point, index) => [
-    (point[0] + vertices[vertices.length - 1 - index][0]) / 2,
-    (point[1] + vertices[vertices.length - 1 - index][1]) / 2,
-  ]);
-}
-
 function axisForLane(ordered, meters) {
   return normalizeMetersVector(subtractPoint(ordered[0], ordered[1]), meters);
 }

scripts/lib/vehicle-route.js

@@ -1,72 +1,119 @@
 "use strict";
 
 const fs = require("fs");
+const { parseOsm } = require("./osm");
+const {
+  appendCoordinates,
+  haversineMeters,
+  laneCenterline,
+  lateralOffsetFrom,
+  orientPolyline,
+  polylineLength,
+  polylineMidpoint,
+} = require("./lane-geometry");
 
 const MAX_ROUTES = 5;
 const MAX_PATH_EDGES = 7;
 const MIN_ROUTE_EDGES = 3;
-const LANE_OFFSET_METERS = 1.3;
+const MAX_LANE_DISTANCE_METERS = 20;
+const MIN_LATERAL_SEPARATION_METERS = 0.25;
 const JUNCTION_TRIM_METERS = 6.0;
+const CONNECTOR_SURFACE_TOLERANCE_METERS = 0.35;
 const ALL_TURNS = new Set(["left", "through", "right"]);
 
-function buildVehicleRoute(osmPath) {
+function buildVehicleRoute(osmPath, lanePolygonsPath, networkPath, intersectionSurfacePath) {
+  if (!lanePolygonsPath || !networkPath || !intersectionSurfacePath) {
+    throw new Error("Lane polygons, osm2streets network, and intersection surface paths are required for vehicle route generation");
+  }
   const osm = parseOsm(fs.readFileSync(osmPath, "utf8"));
-  const edges = directedRoadEdges(osm.ways, osm.nodes, osm.bounds);
-  const routes = selectRoutes(findReturnRoutes(edges));
+  const lanePolygons = readLanePolygons(lanePolygonsPath);
+  const network = readJsonObject(networkPath, "osm2streets network");
+  const intersectionSurfaces = readFeatureCollection(intersectionSurfacePath, "intersection surfaces");
+  const diagnostics = [];
+  const laneIndex = indexDrivingLanes(lanePolygons.features, diagnostics);
+  const intersections = indexIntersections(network, intersectionSurfaces.features);
+  const edges = directedRoadEdges(network, osm.ways, diagnostics);
+  const candidates = findReturnRoutes(edges);
+  const routes = [];
+  for (const candidate of candidates) {
+    const route = makeRoute(candidate, laneIndex, intersections, diagnostics);
+    if (route) routes.push(route);
+  }
+  const selected = selectRoutes(routes);
   return {
     source: osmPath,
+    laneSource: lanePolygonsPath,
+    networkSource: networkPath,
+    intersectionSource: intersectionSurfacePath,
     bounds: osm.bounds,
     generatedAt: new Date().toISOString(),
     speedMetersPerSecond: 8.0,
     loop: true,
-    routes,
-    // Older previews read `segments`; keep it as an alias while new previews
-    // use the more accurate route name.
-    segments: routes,
+    routes: selected,
+    diagnostics,
+    // 旧预览仍读取 segments；保持与 routes 为同一个数组引用。
+    segments: selected,
   };
 }
 
-function parseOsm(xml) {
-  const boundsMatch = xml.match(/<bounds\b([^>]*)\/?\s*>/);
-  const boundsAttrs = boundsMatch ? xmlAttrs(boundsMatch[1]) : {};
-  const bounds = {
-    minLon: Number(boundsAttrs.minlon), minLat: Number(boundsAttrs.minlat),
-    maxLon: Number(boundsAttrs.maxlon), maxLat: Number(boundsAttrs.maxlat),
-  };
-  const validBounds = Object.values(bounds).every(Number.isFinite) ? bounds : null;
-  const nodes = new Map();
-  for (const match of xml.matchAll(/<node\b([^>]*)\/?\s*>/g)) {
-    const attrs = xmlAttrs(match[1]);
-    if (!attrs.id || attrs.lon === undefined || attrs.lat === undefined) continue;
-    const coord = [Number(attrs.lon), Number(attrs.lat)];
-    if (coord.every(Number.isFinite)) nodes.set(attrs.id, coord);
-  }
-  const ways = [];
-  for (const match of xml.matchAll(/<way\b([^>]*)>([\s\S]*?)<\/way>/g)) {
-    const attrs = xmlAttrs(match[1]);
-    const body = match[2];
-    const tags = {};
-    for (const tagMatch of body.matchAll(/<tag\b([^>]*)\/?\s*>/g)) {
-      const tag = xmlAttrs(tagMatch[1]);
-      if (tag.k) tags[tag.k] = tag.v || "";
-    }
-    if (!isCruiseHighway(tags)) continue;
-    const refs = [];
-    for (const ndMatch of body.matchAll(/<nd\b([^>]*)\/?\s*>/g)) {
-      const ref = xmlAttrs(ndMatch[1]).ref;
-      if (ref && nodes.has(ref)) refs.push(ref);
-    }
-    if (refs.length >= 2) ways.push({ id: attrs.id || `way-${ways.length + 1}`, refs, tags });
-  }
-  return { bounds: validBounds, nodes, ways };
+function readLanePolygons(file) {
+  return readFeatureCollection(file, "lane polygons");
 }
 
-function xmlAttrs(text) {
-  const attrs = {};
-  for (const match of text.matchAll(/([:\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
-    attrs[match[1]] = match[2] !== undefined ? match[2] : match[3];
+function readFeatureCollection(file, label) {
+  const collection = readJsonObject(file, label);
+  if (collection?.type !== "FeatureCollection" || !Array.isArray(collection.features)) {
+    throw new Error(`Invalid ${label} GeoJSON '${file}': expected FeatureCollection`);
   }
-  return attrs;
+  return collection;
+}
+
+function readJsonObject(file, label) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected JSON object");
+    return value;
+  } catch (error) {
+    throw new Error(`Invalid ${label} JSON '${file}': ${error.message}`);
+  }
+}
+
+function indexDrivingLanes(features, diagnostics) {
+  const index = new Map();
+  features.forEach((feature, featureIndex) => {
+    if (feature?.properties?.type !== "Driving") return;
+    const centerline = laneCenterline(feature);
+    const direction = feature.properties.direction;
+    const widthMeters = Number(feature.properties.width);
+    const road = Number(feature.properties.road);
+    if (!centerline || !["Fwd", "Back"].includes(direction) || !Number.isFinite(widthMeters) || widthMeters <= 0 || !Number.isInteger(road)) {
+      diagnostics.push({
+        reason: "invalid_lane_polygon",
+        featureIndex,
+        road: feature?.properties?.road ?? null,
+        laneIndex: feature?.properties?.index ?? null,
+      });
+      return;
+    }
+    const lane = {
+      featureIndex,
+      polygonId: feature.id ?? `${feature.properties.road ?? "road"}:${direction}:${feature.properties.index ?? featureIndex}`,
+      road,
+      laneIndex: feature.properties.index,
+      widthMeters,
+      allowedTurns: normalizeAllowedTurns(feature.properties.allowed_turns),
+      centerline,
+    };
+    const key = laneKey(road, direction);
+    if (!index.has(key)) index.set(key, []);
+    index.get(key).push(lane);
+  });
+  return index;
+}
+
+function normalizeAllowedTurns(value) {
+  if (!Array.isArray(value)) return new Set();
+  return new Set(value.map(normalizeTurn).filter(Boolean));
 }
 
 function isCruiseHighway(tags) {
@@ -78,69 +125,100 @@ function isCruiseHighway(tags) {
   ]).has(highway);
 }
 
-function directedRoadEdges(ways, nodes, bounds) {
-  const edges = [];
-  for (const way of ways) {
-    const refs = compactRefs(way.refs);
-    if (refs.length < 2) continue;
-    const coords = refs.map((ref) => nodes.get(ref));
-    if (!routeInsideBounds(coords, bounds) || routeLength(coords) < 12) continue;
-    const oneway = String(way.tags.oneway || "").toLowerCase();
-    if (oneway !== "-1") edges.push(makeEdge(way, refs, coords, "forward"));
-    if (!isOneWay(oneway)) {
-      edges.push(makeEdge(way, [...refs].reverse(), [...coords].reverse(), "backward"));
+function directedRoadEdges(network, ways, diagnostics) {
+  if (!Array.isArray(network.roads) || !network.gps_bounds) {
+    throw new Error("Invalid osm2streets network: expected roads and gps_bounds");
   }
+  const waysById = new Map(ways.map((way) => [String(way.id), way]));
+  const edges = [];
+  for (const entry of network.roads) {
+    const road = Array.isArray(entry) ? entry[1] : null;
+    if (!road || !Number.isInteger(Number(road.id)) || !Array.isArray(road.lane_specs_ltr)) continue;
+    const wayIds = Array.isArray(road.osm_ids) ? road.osm_ids.map(String) : [];
+    const sourceWays = wayIds.map((id) => waysById.get(id)).filter(Boolean);
+    const sourceWay = sourceWays[0] || null;
+    const tags = sourceWay?.tags || { highway: road.highway_type || "" };
+    if (!isCruiseHighway(tags)) continue;
+    if (sourceWays.length > 1 && sourceWays.some((way) => JSON.stringify(way.tags) !== JSON.stringify(sourceWay.tags))) {
+      addDiagnostic(diagnostics, { reason: "ambiguous_internal_road_source", road: road.id, osmWayIds: wayIds });
+      continue;
+    }
+    const coordinates = networkPolylineToGps(road.center_line, network.gps_bounds);
+    if (coordinates.length < 2 || routeLength(coordinates) < 12) continue;
+    const directions = new Set(road.lane_specs_ltr
+      .filter((lane) => lane.lt === "Driving")
+      .map((lane) => lane.dir));
+    if (directions.has("Fwd")) edges.push(makeEdge(road, sourceWay, wayIds, coordinates, "forward"));
+    if (directions.has("Back")) edges.push(makeEdge(road, sourceWay, wayIds, [...coordinates].reverse(), "backward"));
   }
   return edges.sort((a, b) => a.id.localeCompare(b.id));
 }
 
-function makeEdge(way, refs, coordinates, direction) {
+function makeEdge(road, way, wayIds, coordinates, direction) {
+  const forward = direction === "forward";
+  const tags = way?.tags || {};
   return {
-    id: `${way.id}:${direction}`,
-    wayId: way.id,
+    id: `road-${road.id}:${direction}`,
+    roadId: Number(road.id),
+    wayId: wayIds[0] || "",
+    osmWayIds: wayIds,
     direction,
-    name: way.tags.name || way.tags.highway || "road",
-    highway: way.tags.highway || "",
-    oneWay: way.tags.oneway || "",
-    startNode: refs[0],
-    endNode: refs[refs.length - 1],
+    name: road.name || tags.name || road.highway_type || "road",
+    highway: road.highway_type || tags.highway || "",
+    oneWay: directionsForRoad(road).size === 1 ? "yes" : "",
+    startNode: forward ? Number(road.src_i) : Number(road.dst_i),
+    endNode: forward ? Number(road.dst_i) : Number(road.src_i),
     coordinates,
-    allowedTurns: allowedTurns(way.tags, direction),
+    allowedTurns: allowedTurns(tags, direction),
+    turnLanes: turnLanes(tags, direction),
   };
 }
 
+function directionsForRoad(road) {
+  return new Set(road.lane_specs_ltr.filter((lane) => lane.lt === "Driving").map((lane) => lane.dir));
+}
+
+function networkPolylineToGps(polyline, bounds) {
+  const points = Array.isArray(polyline?.pts) ? polyline.pts : [];
+  const widthMeters = haversineMeters([bounds.min_lon, bounds.min_lat], [bounds.max_lon, bounds.min_lat]);
+  const heightMeters = haversineMeters([bounds.min_lon, bounds.min_lat], [bounds.min_lon, bounds.max_lat]);
+  if (!(widthMeters > 0) || !(heightMeters > 0)) return [];
+  return points.map((point) => {
+    const x = Number(point.x) / 10000;
+    const y = Number(point.y) / 10000;
+    return [
+      bounds.min_lon + x / widthMeters * (bounds.max_lon - bounds.min_lon),
+      bounds.min_lat + (bounds.max_lat - bounds.min_lat) * (heightMeters - y) / heightMeters,
+    ];
+  }).filter((coordinate) => coordinate.every(Number.isFinite));
+}
+
 function isOneWay(value) {
   return ["yes", "true", "1"].includes(value);
 }
 
-function compactRefs(refs) {
-  return refs.filter((ref, index) => index === 0 || ref !== refs[index - 1]);
-}
-
-function routeInsideBounds(coords, bounds) {
-  if (!bounds) return true;
-  return coords.some((coord) => insideBounds(coord, bounds));
-}
-
-function insideBounds(coord, bounds) {
-  const pad = 0.00002;
-  return coord[0] >= bounds.minLon - pad && coord[0] <= bounds.maxLon + pad &&
-    coord[1] >= bounds.minLat - pad && coord[1] <= bounds.maxLat + pad;
-}
-
 function allowedTurns(tags, direction) {
-  const value = tags[`turn:lanes:${direction}`] || tags["turn:lanes"];
-  if (!value) return ALL_TURNS;
-  const turns = new Set();
-  for (const lane of String(value).split("|")) {
-    for (const maneuver of lane.split(";")) {
-      const normalized = maneuver.trim().replace(/^slight_/, "");
-      if (ALL_TURNS.has(normalized)) turns.add(normalized);
-    }
-  }
+  const lanes = turnLanes(tags, direction);
+  if (!lanes) return ALL_TURNS;
+  const turns = new Set(lanes.flatMap((lane) => [...lane]).filter((turn) => ALL_TURNS.has(turn)));
   return turns.size ? turns : ALL_TURNS;
 }
 
+function turnLanes(tags, direction) {
+  const value = tags[`turn:lanes:${direction}`] ?? tags["turn:lanes"];
+  if (value === undefined || value === "") return null;
+  return String(value).split("|").map((lane) => {
+    const turns = new Set(String(lane).split(";").map(normalizeTurn).filter(Boolean));
+    return turns.size ? turns : new Set(ALL_TURNS);
+  });
+}
+
+function normalizeTurn(value) {
+  const turn = String(value || "").trim().replace(/^slight_/, "");
+  if (turn === "reverse") return "u_turn";
+  return [...ALL_TURNS, "u_turn"].includes(turn) ? turn : null;
+}
+
 function findReturnRoutes(edges) {
   const outgoing = new Map();
   const byId = new Map();
@@ -151,14 +229,12 @@ function findReturnRoutes(edges) {
   }
   const candidates = [];
   const seen = new Set();
-  for (const first of edges) {
-    walkToTerminal([first], [], outgoing, byId, candidates, seen);
-  }
+  for (const first of edges) walkToTerminal([first], [], outgoing, byId, candidates, seen);
   return candidates.sort((a, b) => a.signature.localeCompare(b.signature));
 }
 
 function walkToTerminal(path, maneuvers, outgoing, byId, candidates, seen) {
-  const current = path[path.length - 1];
+  const current = path.at(-1);
   if (path.length >= MIN_ROUTE_EDGES) {
     const route = returnRoute(path, maneuvers, byId);
     if (route && !seen.has(route.signature)) {
@@ -180,7 +256,7 @@ function walkToTerminal(path, maneuvers, outgoing, byId, candidates, seen) {
 }
 
 function classifyConnection(incoming, outgoing) {
-  if (incoming.wayId === outgoing.wayId) return null;
+  if (incoming.roadId === outgoing.roadId) return null;
   const inVector = directionVector(incoming.coordinates.at(-2), incoming.coordinates.at(-1));
   const outVector = directionVector(outgoing.coordinates[0], outgoing.coordinates[1]);
   const dot = inVector.x * outVector.x + inVector.y * outVector.y;
@@ -192,7 +268,7 @@ function classifyConnection(incoming, outgoing) {
 }
 
 function directionVector(a, b) {
-  const scale = 111320.0;
+  const scale = 111320;
   const x = (b[0] - a[0]) * scale * Math.cos(degreesToRadians((a[1] + b[1]) / 2));
   const y = (b[1] - a[1]) * scale;
   const length = Math.hypot(x, y) || 1;
@@ -200,7 +276,7 @@ function directionVector(a, b) {
 }
 
 function returnRoute(path, forwardManeuvers, byId) {
-  const reverse = path.slice().reverse().map((edge) => byId.get(`${edge.wayId}:${oppositeDirection(edge.direction)}`));
+  const reverse = path.slice().reverse().map((edge) => byId.get(`road-${edge.roadId}:${oppositeDirection(edge.direction)}`));
   if (reverse.some((edge) => !edge)) return null;
   const returnManeuvers = [];
   for (let index = 1; index < reverse.length; index += 1) {
@@ -208,67 +284,312 @@ function returnRoute(path, forwardManeuvers, byId) {
     if (!maneuver) return null;
     returnManeuvers.push(maneuver);
   }
-  const signature = path.map((edge) => edge.wayId).sort().join(">");
-  return makeRoute(
-    [...path, ...reverse],
-    [...forwardManeuvers, "u_turn", ...returnManeuvers, "u_turn"],
+  const signature = path.map((edge) => edge.roadId).join(">");
+  return {
+    edges: [...path, ...reverse],
+    maneuvers: [...forwardManeuvers, "u_turn", ...returnManeuvers, "u_turn"],
+    forwardEdgeCount: path.length,
     signature,
-  );
+  };
 }
 
 function oppositeDirection(direction) {
   return direction === "forward" ? "backward" : "forward";
 }
 
-function makeRoute(edges, maneuvers, signature) {
-  const coordinates = smoothRoute(edges);
+function makeRoute(candidate, laneIndex, intersections, diagnostics) {
+  const selectedLanes = [];
+  for (let index = 0; index < candidate.edges.length; index += 1) {
+    const edge = candidate.edges[index];
+    const match = selectLaneForEdge(edge, candidate.maneuvers[index], laneIndex, {
+      // 仅去程中的真实路口受 turn:lanes 严格约束；端点调头与展示返程不能被反向标签否决。
+      enforceTurnRestrictions: index < candidate.forwardEdgeCount - 1,
+    });
+    if (!match.ok) {
+      addDiagnostic(diagnostics, {
+        reason: match.reason,
+        routeSignature: candidate.signature,
+        edgeId: edge.id,
+        road: edge.roadId,
+        osmWayId: edge.wayId,
+        direction: edge.direction,
+        maneuver: candidate.maneuvers[index],
+        detail: match.detail,
+      });
+      return null;
+    }
+    selectedLanes.push(match.lane);
+  }
+  const smoothed = smoothLaneRoute(candidate.edges, selectedLanes, intersections);
+  if (!smoothed.ok) {
+    addDiagnostic(diagnostics, { reason: smoothed.reason, routeSignature: candidate.signature, ...smoothed.detail });
+    return null;
+  }
+  const coordinates = smoothed.coordinates;
+  const centerlineCoordinates = smoothRoute(candidate.edges);
   const route = {
-    id: `route-${signature.replace(/[^\w]+/g, "-")}`,
-    highway: edges[0].highway,
-    oneWay: edges.some((edge) => isOneWay(String(edge.oneWay).toLowerCase())) ? "partial" : "",
-    edgeIds: edges.map((edge) => edge.id),
-    maneuvers,
+    id: `route-${candidate.signature.replace(/[^\w]+/g, "-")}`,
+    highway: candidate.edges[0].highway,
+    oneWay: candidate.edges.some((edge) => isOneWay(String(edge.oneWay).toLowerCase())) ? "partial" : "",
+    edgeIds: candidate.edges.map((edge) => edge.id),
+    maneuvers: candidate.maneuvers,
     lengthMeters: routeLength(coordinates),
-    laneOffsetMeters: LANE_OFFSET_METERS,
-    coordinates: offsetClosedRouteRight(coordinates, LANE_OFFSET_METERS),
-    centerlineCoordinates: coordinates,
+    coordinates,
+    centerlineCoordinates,
+    laneSegments: selectedLanes.flatMap((lane, edgeIndex) => lane.fragments.map((fragment) => ({
+      edgeId: candidate.edges[edgeIndex].id,
+      osmWayId: candidate.edges[edgeIndex].wayId,
+      direction: candidate.edges[edgeIndex].direction,
+      laneIndex: lane.laneIndex,
+      widthMeters: fragment.widthMeters,
+      centerOffsetMeters: Number(fragment.centerOffsetMeters.toFixed(3)),
+      maneuver: candidate.maneuvers[edgeIndex],
+      source: "lane_polygon_centerline",
+      polygonId: fragment.polygonId,
+      featureIndex: fragment.featureIndex,
+      road: fragment.road,
+    }))),
+    connectors: smoothed.connectors,
   };
-  Object.defineProperty(route, "signature", { value: signature });
+  Object.defineProperty(route, "signature", { value: candidate.signature });
   return route;
 }
 
+function selectLaneForEdge(edge, maneuver, laneIndex, options = {}) {
+  const enforceTurnRestrictions = options.enforceTurnRestrictions !== false;
+  const expectedDirection = edge.direction === "forward" ? "Fwd" : "Back";
+  const candidates = laneIndex.get(laneKey(edge.roadId, expectedDirection)) || [];
+  if (!candidates.length) return { ok: false, reason: "missing_lane_polygon" };
+  const lanes = [];
+  for (const fragment of candidates) {
+    const centerline = orientPolyline(fragment.centerline, edge.coordinates);
+    if (!centerline) return { ok: false, reason: "invalid_lane_polygon", detail: "direction_alignment" };
+    const midpoint = polylineMidpoint(centerline);
+    const offset = lateralOffsetFrom(edge.coordinates, midpoint);
+    if (!offset || offset.distance > MAX_LANE_DISTANCE_METERS) {
+      return { ok: false, reason: "missing_lane_polygon", detail: "geometry_too_far_from_internal_road" };
+    }
+    lanes.push({
+      laneIndex: fragment.laneIndex,
+      centerline,
+      centerOffsetMeters: offset.lateral,
+      allowedTurns: fragment.allowedTurns,
+      fragments: [{ ...fragment, centerline, centerOffsetMeters: offset.lateral }],
+    });
+  }
+  lanes.sort((a, b) => a.centerOffsetMeters - b.centerOffsetMeters || String(a.laneIndex).localeCompare(String(b.laneIndex)));
+  for (let index = 1; index < lanes.length; index += 1) {
+    if (lanes[index].centerOffsetMeters - lanes[index - 1].centerOffsetMeters < MIN_LATERAL_SEPARATION_METERS) {
+      return { ok: false, reason: "ambiguous_lane_order" };
+    }
+  }
+  if (enforceTurnRestrictions && edge.turnLanes && edge.turnLanes.length !== lanes.length) {
+    return { ok: false, reason: "ambiguous_lane_order", detail: "turn_lane_count_mismatch" };
+  }
+  let compatible = lanes.filter((lane, index) => laneSupportsManeuver(lane, edge.turnLanes?.[index], maneuver));
+  if (!compatible.length && !enforceTurnRestrictions) compatible = lanes;
+  if (!compatible.length) return { ok: false, reason: "no_compatible_turn_lane" };
+  const chooseLeft = maneuver === "left" || maneuver === "u_turn";
+  return { ok: true, lane: chooseLeft ? compatible[0] : compatible.at(-1) };
+}
+
+function laneSupportsManeuver(lane, osmTurns, maneuver) {
+  const expected = maneuver === "u_turn" ? "left" : maneuver;
+  if (osmTurns && !osmTurns.has(expected) && !(maneuver === "u_turn" && osmTurns.has("u_turn"))) return false;
+  if (lane.allowedTurns.size && !lane.allowedTurns.has(expected) && !(maneuver === "u_turn" && lane.allowedTurns.has("u_turn"))) return false;
+  return true;
+}
+
+function laneKey(roadId, direction) {
+  return `${String(roadId)}:${direction}`;
+}
+
+function addDiagnostic(diagnostics, entry) {
+  const key = JSON.stringify(entry);
+  if (!diagnostics.some((current) => JSON.stringify(current) === key)) diagnostics.push(entry);
+}
+
+function indexIntersections(network, features) {
+  if (!Array.isArray(network.intersections)) throw new Error("Invalid osm2streets network: expected intersections");
+  const surfaces = new Map(features
+    .filter((feature) => feature?.geometry?.type === "Polygon" && Number.isInteger(Number(feature.properties?.id)))
+    .map((feature) => [Number(feature.properties.id), feature.geometry.coordinates[0]]));
+  const intersections = new Map();
+  for (const entry of network.intersections) {
+    const intersection = Array.isArray(entry) ? entry[1] : null;
+    if (!intersection || !Number.isInteger(Number(intersection.id))) continue;
+    intersections.set(Number(intersection.id), {
+      id: Number(intersection.id),
+      osmNodeIds: Array.isArray(intersection.osm_ids) ? intersection.osm_ids.map(String) : [],
+      surface: surfaces.get(Number(intersection.id)) || null,
+    });
+  }
+  return intersections;
+}
+
+function smoothLaneRoute(edges, selectedLanes, intersections) {
+  const route = [];
+  const connectors = [];
+  for (let index = 0; index < edges.length; index += 1) {
+    const current = selectedLanes[index].centerline;
+    appendCoordinates(route, current);
+    const nextIndex = (index + 1) % edges.length;
+    const next = selectedLanes[nextIndex].centerline;
+    const incomingEdge = edges[index];
+    const outgoingEdge = edges[nextIndex];
+    if (incomingEdge.endNode !== outgoingEdge.startNode) {
+      return { ok: false, reason: "disconnected_internal_roads", detail: { fromRoad: incomingEdge.roadId, toRoad: outgoingEdge.roadId } };
+    }
+    const intersection = intersections.get(incomingEdge.endNode);
+    if (!intersection?.surface) {
+      return { ok: false, reason: "missing_intersection_surface", detail: { intersectionId: incomingEdge.endNode } };
+    }
+    const isUTurn = incomingEdge.roadId === outgoingEdge.roadId;
+    const turn = constrainedConnector(current, next, incomingEdge.coordinates.at(-1), intersection.surface, isUTurn);
+    if (!turn) {
+      return {
+        ok: false,
+        reason: "connector_outside_intersection",
+        detail: { intersectionId: intersection.id, fromRoad: incomingEdge.roadId, toRoad: outgoingEdge.roadId },
+      };
+    }
+    appendCoordinates(route, turn.slice(1));
+    connectors.push({
+      intersectionId: intersection.id,
+      osmNodeIds: intersection.osmNodeIds,
+      fromRoad: incomingEdge.roadId,
+      toRoad: outgoingEdge.roadId,
+      maneuver: isUTurn ? "u_turn" : classifyConnection(incomingEdge, outgoingEdge),
+      source: "intersection_surface_constrained",
+      coordinates: turn,
+    });
+  }
+  if (route.length) route[route.length - 1] = [...route[0]];
+  return { ok: true, coordinates: route, connectors };
+}
+
+function constrainedConnector(incoming, outgoing, junction, surface, isUTurn) {
+  const scales = isUTurn ? [1, 0.8, 0.6, 0.4, 0.25] : [1, 0.75, 0.5, 0.3, 0.15];
+  for (const scale of scales) {
+    const connector = isUTurn
+      ? uTurnConnector(incoming, outgoing, junction, 20, scale)
+      : tangentBezierTurn(incoming, outgoing, 16, scale);
+    if (connector.length && connector.every((point) => pointInPolygonOrNear(point, surface, CONNECTOR_SURFACE_TOLERANCE_METERS))) {
+      return connector;
+    }
+  }
+  return null;
+}
+
+function pointInPolygonOrNear(point, ring, toleranceMeters) {
+  if (!Array.isArray(ring) || ring.length < 4) return false;
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i, i += 1) {
+    const a = ring[i];
+    const b = ring[j];
+    if ((a[1] > point[1]) !== (b[1] > point[1]) &&
+        point[0] < (b[0] - a[0]) * (point[1] - a[1]) / (b[1] - a[1]) + a[0]) inside = !inside;
+    if (distanceToSegmentMeters(point, a, b) <= toleranceMeters) return true;
+  }
+  return inside;
+}
+
+function distanceToSegmentMeters(point, start, end) {
+  const latitude = (point[1] + start[1] + end[1]) / 3;
+  const metersLon = 111320 * Math.cos(degreesToRadians(latitude));
+  const dx = (end[0] - start[0]) * metersLon;
+  const dy = (end[1] - start[1]) * 111320;
+  const px = (point[0] - start[0]) * metersLon;
+  const py = (point[1] - start[1]) * 111320;
+  const lengthSquared = dx * dx + dy * dy;
+  const ratio = lengthSquared ? Math.max(0, Math.min(1, (px * dx + py * dy) / lengthSquared)) : 0;
+  return Math.hypot(px - dx * ratio, py - dy * ratio);
+}
+
 function smoothRoute(edges) {
   const trimmed = edges.map((edge) => trimPolyline(edge.coordinates, JUNCTION_TRIM_METERS));
   const route = [];
   for (let index = 0; index < edges.length; index += 1) {
     appendCoordinates(route, trimmed[index]);
     const nextIndex = (index + 1) % edges.length;
-    const junction = edges[index].coordinates.at(-1);
-    const turn = edges[index].wayId === edges[nextIndex].wayId
-      ? uTurn(trimmed[index].at(-1), junction, trimmed[nextIndex][0])
-      : bezierTurn(trimmed[index].at(-1), junction, trimmed[nextIndex][0], 6);
+    const turn = edges[index].roadId === edges[nextIndex].roadId
+      ? uTurnConnector(trimmed[index], trimmed[nextIndex], edges[index].coordinates.at(-1))
+      : tangentBezierTurn(trimmed[index], trimmed[nextIndex]);
     appendCoordinates(route, turn.slice(1));
   }
   if (route.length) route[route.length - 1] = [...route[0]];
   return route;
 }
 
-function uTurn(start, junction, end) {
-  const tangent = directionVector(start, junction);
-  const left = offsetCoordinate(junction, -tangent.y * 3.0, tangent.x * 3.0);
-  const right = offsetCoordinate(junction, tangent.y * 3.0, -tangent.x * 3.0);
-  return [
-    start,
-    lerpCoordinate(start, junction, 0.72),
-    left,
-    right,
-    lerpCoordinate(end, junction, 0.72),
-    end,
-  ];
+function tangentBezierTurn(incoming, outgoing, samples = 16, scale = 1) {
+  if (incoming.length < 2 || outgoing.length < 2) return [];
+  const start = incoming.at(-1);
+  const end = outgoing[0];
+  const incomingTangent = directionVector(incoming.at(-2), start);
+  const outgoingTangent = directionVector(end, outgoing[1]);
+  const incomingSpan = haversineMeters(incoming.at(-2), start);
+  const outgoingSpan = haversineMeters(end, outgoing[1]);
+  const intersection = intersectTangentRays(start, end, incomingTangent, outgoingTangent);
+  let controlA;
+  let controlB;
+  if (intersection && intersection.a >= 0 && intersection.b >= 0) {
+    // 两条车道切线的前向交点定义了转弯的几何目标，Bezier 控制点取三分之一距离。
+    const maxA = Math.min(8, Math.max(0.75, incomingSpan * 2.4));
+    const maxB = Math.min(8, Math.max(0.75, outgoingSpan * 2.4));
+    const distanceA = Math.min(intersection.a, maxA) * scale;
+    const distanceB = Math.min(intersection.b, maxB) * scale;
+    controlA = offsetCoordinate(start, incomingTangent.x * distanceA / 3, incomingTangent.y * distanceA / 3);
+    controlB = offsetCoordinate(end, -outgoingTangent.x * distanceB / 3, -outgoingTangent.y * distanceB / 3);
+  } else {
+    // 平行、反向或交点在车道后方时，使用受限 fallback，避免生成反向回环。
+    const chordMeters = haversineMeters(start, end);
+    const controlMeters = boundedControlDistance(chordMeters, incomingSpan, outgoingSpan, 0.42, 8) * scale;
+    controlA = offsetCoordinate(start, incomingTangent.x * controlMeters, incomingTangent.y * controlMeters);
+    controlB = offsetCoordinate(end, -outgoingTangent.x * controlMeters, -outgoingTangent.y * controlMeters);
+  }
+  return cubicBezier(start, controlA, controlB, end, samples);
+}
+
+function intersectTangentRays(start, end, incomingTangent, outgoingTangent) {
+  const latitude = (start[1] + end[1]) / 2;
+  const metersLon = 111320 * Math.cos(degreesToRadians(latitude));
+  const qx = (end[0] - start[0]) * metersLon;
+  const qy = (end[1] - start[1]) * 111320;
+  const cross = incomingTangent.x * outgoingTangent.y - incomingTangent.y * outgoingTangent.x;
+  if (Math.abs(cross) < 1e-6) return null;
+  const crossQOutgoing = qx * outgoingTangent.y - qy * outgoingTangent.x;
+  const crossQIncoming = qx * incomingTangent.y - qy * incomingTangent.x;
+  return {
+    a: crossQOutgoing / cross,
+    b: crossQIncoming / cross,
+  };
+}
+
+function uTurnConnector(incoming, outgoing, junction, samples = 20, scale = 1) {
+  if (incoming.length < 2 || outgoing.length < 2) return [];
+  const start = incoming.at(-1);
+  const end = outgoing[0];
+  const incomingTangent = directionVector(incoming.at(-2), start);
+  const outgoingTangent = directionVector(end, outgoing[1]);
+  const chordMeters = haversineMeters(start, end);
+  const approachMeters = Math.max(haversineMeters(start, junction), haversineMeters(end, junction));
+  const incomingSpan = haversineMeters(incoming.at(-2), start);
+  const outgoingSpan = haversineMeters(end, outgoing[1]);
+  const availableMeters = Math.max(0.5, Math.min(10, incomingSpan * 0.8, outgoingSpan * 0.8));
+  const controlMeters = Math.min(availableMeters, Math.max(Math.min(2, availableMeters), chordMeters * 1.1, approachMeters * 0.6)) * scale;
+  const controlA = offsetCoordinate(start, incomingTangent.x * controlMeters, incomingTangent.y * controlMeters);
+  const controlB = offsetCoordinate(end, -outgoingTangent.x * controlMeters, -outgoingTangent.y * controlMeters);
+  return cubicBezier(start, controlA, controlB, end, samples);
+}
+
+function boundedControlDistance(chordMeters, incomingSpan, outgoingSpan, ratio, maximumMeters) {
+  const lowerMeters = Math.min(1.5, chordMeters * 0.35);
+  const upperMeters = Math.max(0.25, Math.min(maximumMeters, chordMeters * 0.65, incomingSpan * 0.8, outgoingSpan * 0.8));
+  return Math.min(upperMeters, Math.max(lowerMeters, chordMeters * ratio));
 }
 
 function offsetCoordinate(coord, eastMeters, northMeters) {
-  const metersPerLat = 111320.0;
+  const metersPerLat = 111320;
   const metersPerLon = metersPerLat * Math.cos(degreesToRadians(coord[1]));
   return [coord[0] + eastMeters / metersPerLon, coord[1] + northMeters / metersPerLat];
 }
@@ -290,9 +611,7 @@ function pointAlong(coords, distance) {
   return [...coords.at(-1)];
 }
 
-function bezierTurn(start, junction, end, samples) {
-  const controlA = lerpCoordinate(start, junction, 0.72);
-  const controlB = lerpCoordinate(end, junction, 0.72);
+function cubicBezier(start, controlA, controlB, end, samples) {
   const points = [];
   for (let index = 0; index <= samples; index += 1) {
     const t = index / samples;
@@ -305,19 +624,6 @@ function bezierTurn(start, junction, end, samples) {
   return points;
 }
 
-function appendCoordinates(target, coordinates) {
-  for (const coord of coordinates) {
-    const last = target.at(-1);
-    if (!last || last[0] !== coord[0] || last[1] !== coord[1]) target.push([...coord]);
-  }
-}
-
-function offsetClosedRouteRight(coords, offset) {
-  const shifted = offsetPolylineRight(coords, offset);
-  if (shifted.length) shifted[shifted.length - 1] = [...shifted[0]];
-  return shifted;
-}
-
 function selectRoutes(candidates) {
   const selected = [];
   const covered = new Set();
@@ -336,43 +642,25 @@ function routeScore(route, covered) {
   return novelty * 100000 + route.lengthMeters;
 }
 
-function offsetPolylineRight(coords, offsetMeters) {
-  if (coords.length < 2 || offsetMeters === 0) return coords.map((coord) => [...coord]);
-  const refLat = coords.reduce((sum, coord) => sum + coord[1], 0) / coords.length;
-  const metersPerLat = 111320.0;
-  const metersPerLon = 111320.0 * Math.cos(degreesToRadians(refLat));
-  const points = coords.map((coord) => ({ x: coord[0] * metersPerLon, y: coord[1] * metersPerLat, lon: coord[0], lat: coord[1] }));
-  return points.map((point, index) => {
-    const prev = points[Math.max(0, index - 1)];
-    const next = points[Math.min(points.length - 1, index + 1)];
-    const length = Math.hypot(next.x - prev.x, next.y - prev.y);
-    if (length < 0.001) return [point.lon, point.lat];
-    const dx = (next.x - prev.x) / length;
-    const dy = (next.y - prev.y) / length;
-    return [(point.x + dy * offsetMeters) / metersPerLon, (point.y - dx * offsetMeters) / metersPerLat];
-  });
-}
-
 function routeLength(coords) {
-  let total = 0;
-  for (let index = 1; index < coords.length; index += 1) total += haversineMeters(coords[index - 1], coords[index]);
-  return total;
-}
-
-function haversineMeters(a, b) {
-  const radius = 6371008.8;
-  const lat1 = degreesToRadians(a[1]);
-  const lat2 = degreesToRadians(b[1]);
-  const dLat = degreesToRadians(b[1] - a[1]);
-  const dLon = degreesToRadians(b[0] - a[0]);
-  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
-  return 2 * radius * Math.asin(Math.min(1, Math.sqrt(h)));
+  return polylineLength(coords);
 }
 
 function lerpCoordinate(a, b, t) {
   return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
 }
 
-function degreesToRadians(value) { return value * Math.PI / 180; }
+function degreesToRadians(value) {
+  return value * Math.PI / 180;
+}
 
-module.exports = { buildVehicleRoute, classifyConnection, allowedTurns };
+module.exports = {
+  allowedTurns,
+  buildVehicleRoute,
+  classifyConnection,
+  readLanePolygons,
+  selectLaneForEdge,
+  tangentBezierTurn,
+  turnLanes,
+  uTurnConnector,
+};

scripts/reimport-gpkg.js

@@ -17,8 +17,13 @@ const path = require("path");
 const os = require("os");
 const { execFileSync } = require("child_process");
 const { qgisPaths } = require("./lib/tool-paths");
+const { parseOsm } = require("./lib/osm");
+const {
+  validateTrafficSignalSourceReferences,
+} = require("./lib/traffic-signals");
 const {
   SCENE_LAYERS,
+  AUXILIARY_EDIT_LAYERS,
   SCENE_FILE,
   SCENE_STYLE_FILE,
   layerFile,
@@ -34,6 +39,10 @@ const ogr2ogr = qgis.ogr2ogr;
 const ogrinfo = qgis.ogrinfo;
 const outDir = path.resolve(requireText(config.outDir, "outDir"));
 const gpkgPath = path.resolve(requireText(config.gpkg, "gpkg"));
+const inputPath = path.resolve(requireText(config.input, "input"));
+const trafficSignalAssembliesPath = path.resolve(
+  config.trafficSignalAssemblies || path.join(outDir, "traffic_signal_assemblies.geojson"),
+);
 
 for (const exe of [ogr2ogr, ogrinfo]) {
   if (!fs.existsSync(exe)) {
@@ -43,6 +52,9 @@ for (const exe of [ogr2ogr, ogrinfo]) {
 if (!fs.existsSync(gpkgPath)) {
   throw new Error(`GeoPackage not found: ${gpkgPath}\nRun the intermediates stage first.`);
 }
+if (!fs.existsSync(inputPath)) {
+  throw new Error(`Input OSM XML not found: ${inputPath}`);
+}
 if (!fs.existsSync(outDir)) {
   throw new Error(`GeoJSON output directory not found: ${outDir}`);
 }
@@ -51,6 +63,7 @@ console.log(`Reimport: ${gpkgPath}`);
 console.log(`Target:   ${outDir}`);
 
 const present = gpkgLayers();
+const trafficSignalControls = parseOsm(fs.readFileSync(inputPath, "utf8")).trafficSignalControls;
 const missing = SCENE_LAYERS.filter((layer) => !present.has(layer.id)).map((layer) => layer.id);
 if (missing.length) {
   throw new Error(
@@ -68,11 +81,25 @@ try {
     console.log(`${layer.id}\tfeatures=${collection.features.length}`);
     return { layer, stagedPath, collection };
   });
+  const auxiliary = AUXILIARY_EDIT_LAYERS.map((layer) => {
+    if (!present.has(layer.id)) throw new Error(`GeoPackage is missing auxiliary layer '${layer.id}'`);
+    const stagedPath = path.join(stagingDir, layer.file);
+    exportLayer(layer.id, stagedPath);
+    const collection = readCollection(stagedPath, layer.id);
+    const validated = validateTrafficSignalSourceReferences(collection, trafficSignalControls);
+    console.log(`${layer.id}\tfeatures=${validated.features.length}`);
+    return { layer, stagedPath, collection: validated };
+  });
 
   for (const item of staged) {
     // Copy rather than rename: the staging dir may be on another filesystem.
     fs.copyFileSync(item.stagedPath, path.join(outDir, layerFile(item.layer)));
   }
+  for (const item of auxiliary) {
+    const destination = item.layer.id === "traffic_signal_assemblies"
+      ? trafficSignalAssembliesPath : path.join(outDir, item.layer.file);
+    fs.copyFileSync(item.stagedPath, destination);
+  }
 
   const byId = new Map(staged.map((item) => [item.layer.id, item.collection]));
   const scene = mergeScene((layer) => byId.get(layer.id));
@@ -117,7 +144,7 @@ function loadConfig(cliArgs) {
     }
     Object.assign(base, JSON.parse(fs.readFileSync(file, "utf8")));
   }
-  for (const key of ["qgisApp", "outDir", "gpkg"]) {
+  for (const key of ["qgisApp", "input", "outDir", "gpkg", "trafficSignalAssemblies"]) {
     if (cliArgs[key] !== undefined) base[key] = cliArgs[key];
   }
   return base;

scripts/test-asset-budgets.js

@@ -6,8 +6,14 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { normalizeAreaConfig } = require("./lib/area-config");
+const { stageManifestStatus } = require("./lib/area-diagnostics");
 const { digestGltf } = require("./glb-digest");
-const { evaluateGlbBudget, BUDGETS } = require("./lib/stage-manifest");
+const { evaluateGlbBudget, BUDGETS, fileRecord, writeStageManifest } = require("./lib/stage-manifest");
+
+const qgisBuildSource = fs.readFileSync(path.join(__dirname, "build-osm2streets-qgis.js"), "utf8");
+assert.match(qgisBuildSource, /QgsFieldConstraints\.Constraint\.ConstraintNotNull/);
+assert.match(qgisBuildSource, /QgsFieldConstraints\.ConstraintNotNull/);
+assert.doesNotMatch(qgisBuildSource, /setFieldConstraint\(index, 1\)/);
 
 const gltf = {
   nodes: [
@@ -40,6 +46,10 @@ assert.equal(
   normalizeAreaConfig(base).outputs.trafficSignals,
   path.join(tempDir, "test-area", "osm2streets_web_out", "traffic_signals.json"),
 );
+assert.equal(
+  normalizeAreaConfig(base).outputs.trafficSignalAssemblies,
+  path.join(tempDir, "test-area", "osm2streets_web_out", "traffic_signal_assemblies.geojson"),
+);
 assert.equal(normalizeAreaConfig({ ...base, budget: { nodes: 800 } }).budget.glbNodes, 800);
 assert.throws(
   () => normalizeAreaConfig({ ...base, budget: { nodes: 1200 } }),
@@ -57,6 +67,63 @@ assert.equal(
   normalizeAreaConfig({ ...base, budget: { nodes: 1200, reason: "Dense campus vegetation" } }).budget.glbNodes,
   1200,
 );
+
+const configPath = path.join(tempDir, "area.json");
+fs.writeFileSync(configPath, `${JSON.stringify(base)}\n`);
+const area = normalizeAreaConfig(base);
+fs.mkdirSync(area.outputs.geojsonDir, { recursive: true });
+for (const file of [area.outputs.glb, area.outputs.metadata, area.outputs.cesiumPreview, area.outputs.vehicleRoute, area.outputs.vehicleModel]) {
+  fs.writeFileSync(file, "fixture\n");
+}
+const lanePolygons = path.join(area.outputs.geojsonDir, "lane_polygons.geojson");
+const emptyFeatureCollection = '{"type":"FeatureCollection","features":[]}\n';
+const emptyNetwork = '{"roads":[],"intersections":[],"gps_bounds":{}}\n';
+fs.writeFileSync(lanePolygons, emptyFeatureCollection);
+const network = path.join(area.outputs.geojsonDir, "network.json");
+fs.writeFileSync(network, emptyNetwork);
+const intersectionSurface = path.join(area.outputs.geojsonDir, "intersection_surface.geojson");
+fs.writeFileSync(intersectionSurface, emptyFeatureCollection);
+const previewCss = path.join(__dirname, "lib", "cesium-preview.css");
+const previewJs = path.join(__dirname, "lib", "cesium-preview.js");
+writeStageManifest(area, {
+  stage: "preview",
+  status: "ok",
+  config: configPath,
+  inputs: {
+    config: fileRecord(configPath),
+    osm: fileRecord(input),
+    glb: fileRecord(area.outputs.glb),
+    metadata: fileRecord(area.outputs.metadata),
+    lanePolygons: fileRecord(lanePolygons),
+    network: fileRecord(network),
+    intersectionSurface: fileRecord(intersectionSurface),
+    previewCss: fileRecord(previewCss),
+    previewJs: fileRecord(previewJs),
+  },
+  outputs: {
+    cesiumPreview: fileRecord(area.outputs.cesiumPreview),
+    vehicleRoute: fileRecord(area.outputs.vehicleRoute),
+    vehicleModel: fileRecord(area.outputs.vehicleModel),
+  },
+  summary: {},
+  warnings: [],
+});
+let previewManifest = stageManifestStatus(area, configPath).find((manifest) => manifest.stage === "preview");
+assert.equal(previewManifest.fresh, true);
+fs.appendFileSync(lanePolygons, " \n");
+previewManifest = stageManifestStatus(area, configPath).find((manifest) => manifest.stage === "preview");
+assert.equal(previewManifest.fresh, false);
+assert.ok(previewManifest.issues.some((issue) => issue.includes("lanePolygons")));
+fs.writeFileSync(lanePolygons, emptyFeatureCollection);
+fs.appendFileSync(network, " \n");
+previewManifest = stageManifestStatus(area, configPath).find((manifest) => manifest.stage === "preview");
+assert.equal(previewManifest.fresh, false);
+assert.ok(previewManifest.issues.some((issue) => issue.includes("network")));
+fs.writeFileSync(network, emptyNetwork);
+fs.appendFileSync(intersectionSurface, " \n");
+previewManifest = stageManifestStatus(area, configPath).find((manifest) => manifest.stage === "preview");
+assert.equal(previewManifest.fresh, false);
+assert.ok(previewManifest.issues.some((issue) => issue.includes("intersectionSurface")));
 fs.rmSync(tempDir, { recursive: true, force: true });
 
 console.log("Asset budget tests passed.");

scripts/test-preview-assets.js

@@ -8,11 +8,22 @@ const path = require("path");
 const { cesiumPreviewHtml } = require("./lib/area-preview");
 const { makeVehicleGltf } = require("./lib/vehicle-model");
 const { VEHICLE_IDS, REVERSED_MODEL_IDS, writePreviewVehicleLibrary } = require("./lib/vehicle-library");
-const { allowedTurns, buildVehicleRoute, classifyConnection } = require("./lib/vehicle-route");
+const {
+  allowedTurns,
+  buildVehicleRoute,
+  classifyConnection,
+  tangentBezierTurn,
+  uTurnConnector,
+} = require("./lib/vehicle-route");
 const { buildTrafficSignals } = require("./lib/traffic-signals");
+const { haversineMeters, laneCenterline } = require("./lib/lane-geometry");
+const { parseOsm } = require("./lib/osm");
 
 const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "preview-assets-"));
 const osmPath = path.join(tempDir, "fixture.osm");
+const lanePolygonsPath = path.join(tempDir, "lane_polygons.geojson");
+const networkPath = path.join(tempDir, "network.json");
+const intersectionSurfacePath = path.join(tempDir, "intersection_surface.geojson");
 
 fs.writeFileSync(osmPath, `<?xml version="1.0"?>
 <osm version="0.6">
@@ -24,11 +35,11 @@ fs.writeFileSync(osmPath, `<?xml version="1.0"?>
   <node id="5" lon="120.009" lat="30.002"/>
   <way id="west-road">
     <nd ref="1"/><nd ref="2"/>
-    <tag k="highway" v="primary"/><tag k="turn:lanes:forward" v="left|through"/>
+    <tag k="highway" v="primary"/><tag k="lanes" v="4"/><tag k="lanes:forward" v="2"/><tag k="lanes:backward" v="2"/><tag k="turn:lanes:forward" v="left|through"/>
   </way>
   <way id="turn-road">
     <nd ref="2"/><nd ref="3"/>
-    <tag k="highway" v="residential"/><tag k="turn:lanes:forward" v="through|left"/>
+    <tag k="highway" v="residential"/><tag k="lanes" v="3"/><tag k="lanes:forward" v="2"/><tag k="lanes:backward" v="1"/><tag k="turn:lanes:forward" v="through|left"/><tag k="turn:lanes:backward" v="right"/>
   </way>
   <way id="east-road">
     <nd ref="3"/><nd ref="4"/><tag k="highway" v="residential"/>
@@ -42,8 +53,44 @@ fs.writeFileSync(osmPath, `<?xml version="1.0"?>
 </osm>
 `);
 
-const route = buildVehicleRoute(osmPath);
+const roadCoordinates = {
+  "west-road": [[120.001, 30.001], [120.003, 30.001]],
+  "turn-road": [[120.003, 30.001], [120.005, 30.002]],
+  "east-road": [[120.005, 30.002], [120.007, 30.002]],
+};
+const laneFeatures = [
+  ...directionalLanes("west-road", 0, roadCoordinates["west-road"], "Back", 3.5, [5.25, 1.75], 0),
+  ...directionalLanes("west-road", 0, roadCoordinates["west-road"], "Fwd", 3.5, [1.75, 5.25], 2),
+  ...directionalLanes("turn-road", 1, roadCoordinates["turn-road"], "Back", 3.0, [1.5], 0),
+  ...directionalLanes("turn-road", 1, roadCoordinates["turn-road"], "Fwd", 3.0, [1.5, 4.5], 1),
+  ...directionalLanes("east-road", 2, roadCoordinates["east-road"], "Back", 3.5, [1.75], 0),
+  ...directionalLanes("east-road", 2, roadCoordinates["east-road"], "Fwd", 3.5, [1.75], 1),
+  { type: "Feature", properties: { type: "Driving", direction: "Fwd", index: 99, width: 3, road: 99, osm_way_ids: ["broken"] }, geometry: { type: "Polygon", coordinates: [[]] } },
+];
+fs.writeFileSync(lanePolygonsPath, `${JSON.stringify({ type: "FeatureCollection", features: laneFeatures })}\n`);
+const fixtureBounds = { min_lon: 120, min_lat: 30, max_lon: 120.01, max_lat: 30.01 };
+const networkRoads = [
+  networkRoad(0, "west-road", 0, 1, roadCoordinates["west-road"], [laneSpec("Back", 3.5), laneSpec("Back", 3.5), laneSpec("Fwd", 3.5), laneSpec("Fwd", 3.5)], fixtureBounds, "primary"),
+  networkRoad(1, "turn-road", 1, 2, roadCoordinates["turn-road"], [laneSpec("Back", 3), laneSpec("Fwd", 3), laneSpec("Fwd", 3)], fixtureBounds),
+  networkRoad(2, "east-road", 2, 3, roadCoordinates["east-road"], [laneSpec("Back", 3.5), laneSpec("Fwd", 3.5)], fixtureBounds),
+  networkRoad(3, "oneway-spur", 3, 4, [[120.007, 30.002], [120.009, 30.002]], [laneSpec("Fwd", 3.5)], fixtureBounds),
+];
+fs.writeFileSync(networkPath, `${JSON.stringify({
+  roads: networkRoads.map((road) => [road.id, road]),
+  intersections: [0, 1, 2, 3, 4].map((id) => [id, { id, osm_ids: [String(id + 1)] }]),
+  gps_bounds: fixtureBounds,
+})}\n`);
+fs.writeFileSync(intersectionSurfacePath, `${JSON.stringify({
+  type: "FeatureCollection",
+  features: [[120.001, 30.001], [120.003, 30.001], [120.005, 30.002], [120.007, 30.002], [120.009, 30.002]]
+    .map((coordinate, id) => intersectionFeature(id, coordinate, 9)),
+})}\n`);
+
+const route = buildVehicleRoute(osmPath, lanePolygonsPath, networkPath, intersectionSurfacePath);
 assert.equal(route.source, osmPath);
+assert.equal(route.laneSource, lanePolygonsPath);
+assert.equal(route.networkSource, networkPath);
+assert.equal(route.intersectionSource, intersectionSurfacePath);
 assert.deepEqual(route.bounds, {
   minLon: 120,
   minLat: 30,
@@ -58,16 +105,97 @@ assert.ok(route.routes.every((segment) => segment.edgeIds.length >= 6));
 assert.ok(route.routes.every((segment) => segment.maneuvers.includes("u_turn")));
 assert.ok(route.routes.every((segment) => segment.maneuvers.some((value) => ["left", "right", "through"].includes(value))));
 assert.ok(route.routes.every((segment) => JSON.stringify(segment.coordinates[0]) === JSON.stringify(segment.coordinates.at(-1))));
-assert.ok(route.routes.every((segment) => !segment.edgeIds.includes("oneway-spur:backward")));
+assert.ok(route.routes.every((segment) => !segment.edgeIds.includes("road-3:backward")));
 assert.notDeepEqual(route.routes[0].coordinates, route.routes[0].centerlineCoordinates);
+assert.ok(route.routes.every((segment) => !Object.hasOwn(segment, "laneOffsetMeters")));
+assert.ok(route.routes.every((segment) => segment.laneSegments.length >= segment.edgeIds.length));
+assert.ok(route.routes.every((segment) => segment.connectors.length === segment.edgeIds.length));
+assert.ok(route.routes.flatMap((segment) => segment.connectors).every((connector) =>
+  connector.source === "intersection_surface_constrained" && connector.coordinates.length >= 2
+));
+assert.ok(route.routes.flatMap((segment) => segment.laneSegments).some((segment) => segment.widthMeters === 3));
+assert.ok(route.routes.flatMap((segment) => segment.laneSegments).some((segment) => segment.widthMeters === 3.5));
+assert.ok(route.routes.flatMap((segment) => segment.laneSegments).every((segment) =>
+  segment.source === "lane_polygon_centerline" && Number.isFinite(segment.centerOffsetMeters)
+));
+for (const segment of route.routes) {
+  for (const lane of segment.laneSegments) {
+    const polygonCenterline = laneCenterline(laneFeatures[lane.featureIndex]);
+    assert.ok(polygonCenterline, "selected lane polygon has a valid centerline");
+    assert.ok(polygonCenterline.every((point) =>
+      Math.min(...segment.coordinates.map((coordinate) => haversineMeters(point, coordinate))) <= 0.10
+    ), "route coordinates retain every selected lane centerline point within 0.10 m");
+  }
+}
+assert.ok(route.diagnostics.some((entry) => entry.reason === "invalid_lane_polygon"));
+const westThrough = route.routes.flatMap((segment) => segment.laneSegments).find((lane) =>
+  lane.osmWayId === "west-road" && lane.direction === "forward" && lane.maneuver === "through" && lane.laneIndex === 3
+);
+assert.ok(westThrough, "through uses the rightmost compatible lane on west-road");
+assert.ok(Math.abs(westThrough.centerOffsetMeters - 5.25) <= 0.01, "3.5 m lane geometry produces the 5.25 m outer-lane center");
+const turnThrough = route.routes.flatMap((segment) => segment.laneSegments).find((lane) =>
+  lane.osmWayId === "turn-road" && lane.direction === "forward" && lane.maneuver === "through" && lane.laneIndex === 1
+);
+assert.ok(turnThrough, "turn lane restrictions override the default rightmost choice");
+assert.ok(Math.abs(turnThrough.centerOffsetMeters - 1.5) <= 0.01, "3.0 m lane geometry produces the 1.5 m inner-lane center");
+assert.ok(route.routes.some((segment) => segment.laneSegments.some((lane) =>
+  lane.osmWayId === "turn-road" && lane.direction === "backward" && lane.maneuver === "through"
+)), "display return survives an incompatible reverse turn:lanes tag");
+const missingLanePath = path.join(tempDir, "missing-lane.geojson");
+fs.writeFileSync(missingLanePath, `${JSON.stringify({ type: "FeatureCollection", features: laneFeatures.filter((feature) =>
+  !feature.properties.osm_way_ids.includes("east-road")
+) })}\n`);
+const missingLaneRoute = buildVehicleRoute(osmPath, missingLanePath, networkPath, intersectionSurfacePath);
+assert.equal(missingLaneRoute.routes.length, 0);
+assert.ok(missingLaneRoute.diagnostics.some((entry) => entry.reason === "missing_lane_polygon"));
+const tinyIntersectionSurfacePath = path.join(tempDir, "tiny-intersection-surface.geojson");
+fs.writeFileSync(tinyIntersectionSurfacePath, `${JSON.stringify({
+  type: "FeatureCollection",
+  features: [[120.001, 30.001], [120.003, 30.001], [120.005, 30.002], [120.007, 30.002], [120.009, 30.002]]
+    .map((coordinate, id) => intersectionFeature(id, coordinate, 0.1)),
+})}\n`);
+const rejectedConnectors = buildVehicleRoute(osmPath, lanePolygonsPath, networkPath, tinyIntersectionSurfacePath);
+assert.equal(rejectedConnectors.routes.length, 0);
+assert.ok(rejectedConnectors.diagnostics.some((entry) => entry.reason === "connector_outside_intersection"));
+assert.throws(() => buildVehicleRoute(osmPath, path.join(tempDir, "absent.geojson"), networkPath, intersectionSurfacePath), /Invalid lane polygons JSON/);
+const quad = laneFeatures[0];
+assert.equal(laneCenterline(quad).length, 2);
+assert.equal(laneCenterline({ geometry: { type: "Polygon", coordinates: [[[0, 0], [1, 0], [0, 0]]] } }), null);
 assert.deepEqual(
   [...allowedTurns({ "turn:lanes:forward": "left|through;right" }, "forward")].sort(),
   ["left", "right", "through"],
 );
-const incoming = { wayId: "in", coordinates: [[120, 30], [120.001, 30]] };
-assert.equal(classifyConnection(incoming, { wayId: "left", coordinates: [[120.001, 30], [120.001, 30.001]] }), "left");
-assert.equal(classifyConnection(incoming, { wayId: "right", coordinates: [[120.001, 30], [120.001, 29.999]] }), "right");
-assert.equal(classifyConnection(incoming, { wayId: "through", coordinates: [[120.001, 30], [120.002, 30]] }), "through");
+const incoming = { roadId: 1, coordinates: [[120, 30], [120.001, 30]] };
+assert.equal(classifyConnection(incoming, { roadId: 2, coordinates: [[120.001, 30], [120.001, 30.001]] }), "left");
+assert.equal(classifyConnection(incoming, { roadId: 3, coordinates: [[120.001, 30], [120.001, 29.999]] }), "right");
+assert.equal(classifyConnection(incoming, { roadId: 4, coordinates: [[120.001, 30], [120.002, 30]] }), "through");
+
+const connectorOrigin = [120, 30];
+const incomingLane = [metersCoordinate(connectorOrigin, -12, -1.5), metersCoordinate(connectorOrigin, -5, -1.5)];
+const leftOutgoingLane = [metersCoordinate(connectorOrigin, 1.5, 5), metersCoordinate(connectorOrigin, 1.5, 12)];
+const rightOutgoingLane = [metersCoordinate(connectorOrigin, -1.5, -5), metersCoordinate(connectorOrigin, -1.5, -12)];
+for (const [label, outgoingLane] of [["left", leftOutgoingLane], ["right", rightOutgoingLane]]) {
+  const connector = tangentBezierTurn(incomingLane, outgoingLane);
+  assert.deepEqual(connector[0], incomingLane.at(-1), `${label} connector retains the incoming lane endpoint`);
+  assert.deepEqual(connector.at(-1), outgoingLane[0], `${label} connector retains the outgoing lane endpoint`);
+  assert.ok(tangentMismatchDegrees(incomingLane.at(-2), incomingLane.at(-1), connector[0], connector[1]) < 5,
+    `${label} connector enters along the incoming lane tangent`);
+  assert.ok(tangentMismatchDegrees(connector.at(-2), connector.at(-1), outgoingLane[0], outgoingLane[1]) < 5,
+    `${label} connector exits along the outgoing lane tangent`);
+  assert.ok(maxStepMeters(connector) < 1.5, `${label} connector sampling has no abnormal position jump`);
+}
+
+const uTurnOutgoingLane = [metersCoordinate(connectorOrigin, -5, 1.5), metersCoordinate(connectorOrigin, -12, 1.5)];
+const uTurn = uTurnConnector(incomingLane, uTurnOutgoingLane, connectorOrigin);
+assert.deepEqual(uTurn[0], incomingLane.at(-1));
+assert.deepEqual(uTurn.at(-1), uTurnOutgoingLane[0]);
+assert.ok(tangentMismatchDegrees(incomingLane.at(-2), incomingLane.at(-1), uTurn[0], uTurn[1]) < 5,
+  "U-turn enters along the incoming lane tangent");
+assert.ok(tangentMismatchDegrees(uTurn.at(-2), uTurn.at(-1), uTurnOutgoingLane[0], uTurnOutgoingLane[1]) < 5,
+  "U-turn exits along the outgoing lane tangent");
+assert.ok(maxStepMeters(uTurn) < 1, "U-turn sampling has no abnormal position jump");
+assert.ok(Math.max(...uTurn.map((coordinate) => eastMeters(connectorOrigin, coordinate))) > -3,
+  "U-turn forms a forward loop instead of a fixed lateral polyline");
 
 const vehicle = makeVehicleGltf();
 assert.equal(vehicle.asset.version, "2.0");
@@ -123,6 +251,7 @@ assert.match(html, /"glbName":"scene\\u003c\\u0026\\u003e\.glb"/);
 assert.match(html, /"vehicleModelNames":\["car-a\.gltf","truck-a\.gltf"\]/);
 assert.match(html, /"trafficSignalsName":"traffic-signals\.json"/);
 assert.match(html, /id="toggleSignals"/);
+assert.match(html, /id="toggleBuildingGhost"/);
 assert.match(html, /id="viewMode"/);
 assert.match(html, /data-view-mode="inspect"/);
 assert.match(html, /id="semanticToggles" class="control-subgroup hidden"/);
@@ -134,8 +263,12 @@ assert.doesNotMatch(previewRuntime, /cylinder: \{ length: 6\.7/);
 assert.doesNotMatch(previewRuntime, /Traffic Signal Housing/);
 assert.match(previewRuntime, /asset\.category === "dynamic"/);
 assert.match(previewRuntime, /TrafficSignalDynamic_/);
-assert.match(previewRuntime, /countdown_\$\{String\(value\)\.padStart\(2, "0"\)\}/);
+assert.match(previewRuntime, /TrafficSignalDynamic_\$\{nodeKey\}_countdown_\$\{String\(value\)\.padStart\(2, "0"\)\}/);
 assert.match(previewRuntime, /ColorBlendMode\.REPLACE/);
+assert.match(previewRuntime, /setBuildingGhost/);
+assert.match(previewRuntime, /fetch\(url, \{ cache: "no-store" \}\)/);
+assert.match(previewRuntime, /syncSelectedRouteVisibility\(cruise\)/);
+assert.match(previewRuntime, /buildings\.model\.color = Cesium\.Color\.WHITE\.withAlpha\(0\.22\)/);
 assert.match(previewRuntime, /asset\.category === "countdown"/);
 assert.doesNotMatch(previewRuntime, /createCountdownDigits/);
 assert.doesNotMatch(previewRuntime, /digitMap/);
@@ -144,24 +277,53 @@ assert.match(previewRuntime, /scene\.requestRender/);
 assert.doesNotMatch(previewRuntime, /function addTrafficSignals\(viewer, signalData, start, placement\)/);
 assert.doesNotMatch(previewRuntime, /ellipsoid:/);
 
-const signals = buildTrafficSignals(
-  { type: "FeatureCollection", features: [
-    rectangle(120.0000, 30.0000, 0.00003, 0.000006),
-    rectangle(120.0002, 30.0000, 0.00003, 0.000006),
-  ] },
-  { type: "FeatureCollection", features: [
+const trafficIntersection = { type: "FeatureCollection", features: [
   { type: "Feature", geometry: { type: "Polygon", coordinates: [[
     [119.9998, 29.9998], [120.0004, 29.9998], [120.0004, 30.0003], [119.9998, 30.0003], [119.9998, 29.9998],
   ]] } },
+] };
+const tStopLines = { type: "FeatureCollection", features: [
+  rectangle(119.99995, 30.00005, 0.00003, 0.000006),
+  rectangle(120.00010, 30.00025, 0.00003, 0.000006),
+  rectangle(120.00035, 30.00005, 0.00003, 0.000006),
+] };
+const control = {
+  id: "traffic-t", longitude: 120.0001, latitude: 30.00005,
+  arms: [{ headingDegrees: 270 }, { headingDegrees: 0 }, { headingDegrees: 90 }],
+};
+const noControlSignals = buildTrafficSignals(tStopLines, trafficIntersection);
+assert.equal(noControlSignals.signals.length, 0, "untagged intersections must not create traffic signals");
+
+const tSignals = buildTrafficSignals(tStopLines, trafficIntersection, [control]);
+assert.equal(tSignals.version, 3);
+assert.equal(tSignals.signals.length, 3, "a tagged T junction has one signal per physical approach");
+assert.deepEqual(tSignals.signals.map((signal) => signal.phaseGroup).sort(), [0, 0, 1]);
+assert.ok(tSignals.signals.every((signal) => Number.isFinite(signal.headingDegrees)));
+assert.equal(tSignals.layout.countdownLateralMeters, 1.15);
+assert.equal(tSignals.layout.countdownWidthMeters, 0.82);
+assert.ok(tSignals.signals.every((signal) => signal.pose?.head && signal.pose.lenses.length === 3));
+
+const crossSignals = buildTrafficSignals(
+  { type: "FeatureCollection", features: [
+    rectangle(119.99995, 30.00005, 0.00003, 0.000006),
+    rectangle(120.00010, 30.00025, 0.00003, 0.000006),
+    rectangle(120.00035, 30.00005, 0.00003, 0.000006),
+    rectangle(120.00010, 29.99985, 0.00003, 0.000006),
   ] },
+  trafficIntersection,
+  [{ ...control, arms: [{ headingDegrees: 270 }, { headingDegrees: 0 }, { headingDegrees: 90 }, { headingDegrees: 180 }] }],
 );
-assert.equal(signals.version, 3);
-assert.equal(signals.signals.length, 2);
-assert.deepEqual(signals.signals.map((signal) => signal.phaseGroup), [0, 1]);
-assert.ok(signals.signals.every((signal) => Number.isFinite(signal.headingDegrees)));
-assert.equal(signals.layout.countdownLateralMeters, 1.15);
-assert.equal(signals.layout.countdownWidthMeters, 0.82);
-assert.ok(signals.signals.every((signal) => signal.pose?.head && signal.pose.lenses.length === 3));
+assert.equal(crossSignals.signals.length, 4, "a tagged cross junction retains all four approaches");
+assert.deepEqual(crossSignals.signals.map((signal) => signal.phaseGroup).sort(), [0, 0, 1, 1]);
+
+const parsedSignalControls = parseOsm(`
+  <osm><bounds minlon="119" minlat="29" maxlon="121" maxlat="31" />
+    <node id="active" lon="120" lat="30"><tag k="highway" v="traffic_signals" /><tag k="traffic_signals:direction" v="both" /></node>
+    <node id="directionless" lon="120" lat="30"><tag k="highway" v="traffic_signals" /></node>
+    <node id="deleted" lon="120" lat="30" action="delete"><tag k="highway" v="traffic_signals" /></node>
+    <node id="crossing" lon="120" lat="30"><tag k="highway" v="crossing" /><tag k="crossing" v="traffic_signals" /></node>
+  </osm>`).trafficSignalControls;
+assert.deepEqual(parsedSignalControls.map((entry) => entry.id), ["active", "directionless"], "only active highway=traffic_signals nodes control vehicle signals");
 
 fs.rmSync(tempDir, { recursive: true, force: true });
 console.log("Preview asset tests passed.");
@@ -172,3 +334,100 @@ function rectangle(lon, lat, halfWidth, halfHeight) {
     [lon + halfWidth, lat + halfHeight], [lon - halfWidth, lat + halfHeight], [lon - halfWidth, lat - halfHeight],
   ]] } };
 }
+
+function directionalLanes(osmWayId, roadId, coordinates, direction, widthMeters, offsets, firstIndex) {
+  const oriented = direction === "Fwd" ? coordinates : [...coordinates].reverse();
+  return offsets.map((offsetMeters, index) => lanePolygon(
+    osmWayId, roadId, oriented, direction, firstIndex + index, widthMeters, offsetMeters,
+  ));
+}
+
+function lanePolygon(osmWayId, roadId, coordinates, direction, index, widthMeters, offsetMeters) {
+  const centerline = offsetLineRight(coordinates, offsetMeters);
+  const left = offsetLineRight(centerline, -widthMeters / 2);
+  const right = offsetLineRight(centerline, widthMeters / 2);
+  return {
+    type: "Feature",
+    properties: {
+      type: "Driving",
+      direction,
+      index,
+      width: widthMeters,
+      road: roadId,
+      osm_way_ids: [osmWayId],
+      allowed_turns: [],
+    },
+    geometry: { type: "Polygon", coordinates: [[...left, ...right.reverse(), left[0]]] },
+  };
+}
+
+function laneSpec(direction, widthMeters) {
+  return { lt: "Driving", dir: direction, width: widthMeters * 10000, allowed_turns: 0 };
+}
+
+function networkRoad(id, osmWayId, src, dst, coordinates, laneSpecs, bounds, highwayType = "residential") {
+  return {
+    id,
+    osm_ids: [osmWayId],
+    src_i: src,
+    dst_i: dst,
+    highway_type: highwayType,
+    name: osmWayId,
+    center_line: { pts: coordinates.map((coordinate) => networkPoint(coordinate, bounds)) },
+    lane_specs_ltr: laneSpecs,
+  };
+}
+
+function networkPoint([lon, lat], bounds) {
+  const widthMeters = haversineMeters([bounds.min_lon, bounds.min_lat], [bounds.max_lon, bounds.min_lat]);
+  const heightMeters = haversineMeters([bounds.min_lon, bounds.min_lat], [bounds.min_lon, bounds.max_lat]);
+  return {
+    x: Math.round((lon - bounds.min_lon) / (bounds.max_lon - bounds.min_lon) * widthMeters * 10000),
+    y: Math.round((heightMeters - (lat - bounds.min_lat) / (bounds.max_lat - bounds.min_lat) * heightMeters) * 10000),
+  };
+}
+
+function intersectionFeature(id, coordinate, halfSizeMeters) {
+  const west = metersCoordinate(coordinate, -halfSizeMeters, 0)[0];
+  const east = metersCoordinate(coordinate, halfSizeMeters, 0)[0];
+  const south = metersCoordinate(coordinate, 0, -halfSizeMeters)[1];
+  const north = metersCoordinate(coordinate, 0, halfSizeMeters)[1];
+  return {
+    type: "Feature",
+    properties: { id, type: "intersection" },
+    geometry: { type: "Polygon", coordinates: [[[west, south], [east, south], [east, north], [west, north], [west, south]]] },
+  };
+}
+
+function offsetLineRight(coordinates, offsetMeters) {
+  const [start, end] = coordinates;
+  const latitude = (start[1] + end[1]) / 2;
+  const metersLon = 111320 * Math.cos(latitude * Math.PI / 180);
+  const dx = (end[0] - start[0]) * metersLon;
+  const dy = (end[1] - start[1]) * 111320;
+  const length = Math.hypot(dx, dy);
+  const east = dy / length * offsetMeters;
+  const north = -dx / length * offsetMeters;
+  return coordinates.map(([lon, lat]) => [lon + east / metersLon, lat + north / 111320]);
+}
+
+function metersCoordinate(origin, east, north) {
+  const metersLon = 111320 * Math.cos(origin[1] * Math.PI / 180);
+  return [origin[0] + east / metersLon, origin[1] + north / 111320];
+}
+
+function eastMeters(origin, coordinate) {
+  return (coordinate[0] - origin[0]) * 111320 * Math.cos(origin[1] * Math.PI / 180);
+}
+
+function tangentMismatchDegrees(a, b, c, d) {
+  const metersLon = 111320 * Math.cos((b[1] + c[1]) / 2 * Math.PI / 180);
+  const first = [(b[0] - a[0]) * metersLon, (b[1] - a[1]) * 111320];
+  const second = [(d[0] - c[0]) * metersLon, (d[1] - c[1]) * 111320];
+  const cosine = (first[0] * second[0] + first[1] * second[1]) / (Math.hypot(...first) * Math.hypot(...second));
+  return Math.acos(Math.max(-1, Math.min(1, cosine))) * 180 / Math.PI;
+}
+
+function maxStepMeters(coordinates) {
+  return Math.max(...coordinates.slice(1).map((coordinate, index) => haversineMeters(coordinates[index], coordinate)));
+}

scripts/test-traffic-signals.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const {
+  buildTrafficSignalFeatures,
+  buildTrafficSignalsFromFeatures,
+  validateTrafficSignalFeatures,
+  validateTrafficSignalSourceReferences,
+} = require("./lib/traffic-signals");
+
+function rectangle(lon, lat, dx = 0.00003, dy = 0.000006) {
+  return { type: "Feature", geometry: { type: "Polygon", coordinates: [[
+    [lon - dx, lat - dy], [lon + dx, lat - dy], [lon + dx, lat + dy],
+    [lon - dx, lat + dy], [lon - dx, lat - dy],
+  ]] }, properties: {} };
+}
+
+const intersections = { type: "FeatureCollection", features: [rectangle(120.0001, 30.00005, 0.0003, 0.00025)] };
+const stops = { type: "FeatureCollection", features: [
+  rectangle(119.99995, 30.00005), rectangle(120.00010, 30.00025),
+  rectangle(120.00035, 30.00005), rectangle(120.00010, 29.99985),
+] };
+const arms = [
+  { headingDegrees: 270, wayId: "west", neighborNodeId: "w1" },
+  { headingDegrees: 0, wayId: "north", neighborNodeId: "n1" },
+  { headingDegrees: 90, wayId: "east", neighborNodeId: "e1" },
+  { headingDegrees: 180, wayId: "south", neighborNodeId: "s1" },
+];
+const control = { id: "control-1", longitude: 120.0001, latitude: 30.00005, arms };
+
+const cross = buildTrafficSignalFeatures(stops, intersections, [control]);
+assert.equal(cross.features.length, 4);
+assert.equal(new Set(cross.features.map((feature) => feature.properties.signal_uid)).size, 4);
+const t = buildTrafficSignalFeatures(stops, intersections, [{ ...control, arms: arms.slice(0, 3) }]);
+assert.equal(t.features.length, 3);
+assert.deepEqual(
+  buildTrafficSignalFeatures(stops, intersections, [control]).features.map((feature) => feature.properties.signal_uid),
+  cross.features.map((feature) => feature.properties.signal_uid),
+  "technical ids are deterministic",
+);
+
+const edited = structuredClone(cross);
+const first = edited.features[0];
+const originalStop = [first.properties.stop_lon, first.properties.stop_lat];
+first.geometry.coordinates[0] += 0.0001;
+first.properties.display_id = "A-01";
+first.properties.heading_deg = 42;
+first.properties.z_offset_m = 1.25;
+const runtime = buildTrafficSignalsFromFeatures(edited);
+assert.equal(new Set(runtime.signals.map((signal) => signal.nodeKey)).size, runtime.signals.length);
+for (const signal of runtime.signals) {
+  assert.match(signal.nodeKey, /^ts_[0-9a-f]{16}$/);
+  assert.ok(
+    `TrafficSignalDynamic_${signal.nodeKey}_countdown_19`.length <= 63,
+    "dynamic node names must stay below Blender's name limit",
+  );
+}
+const changed = runtime.signals.find((signal) => signal.id === first.properties.signal_uid);
+assert.equal(changed.displayId, "A-01");
+assert.equal(changed.longitude, first.geometry.coordinates[0]);
+assert.equal(changed.headingDegrees, 42);
+assert.deepEqual([changed.stopLongitude, changed.stopLatitude], originalStop, "moving a pole preserves the stop point");
+assert.equal(changed.pose.pole.height, 1.25);
+assert.equal(changed.pose.arm.from.height, 7.5);
+
+edited.features[1].properties.enabled = "0";
+assert.equal(buildTrafficSignalsFromFeatures(edited).signals.length, 3, "disabled assemblies are omitted");
+
+const duplicateUid = structuredClone(cross);
+duplicateUid.features[1].properties.signal_uid = duplicateUid.features[0].properties.signal_uid;
+assert.throws(() => validateTrafficSignalFeatures(duplicateUid), /Duplicate signal_uid/);
+const duplicateDisplay = structuredClone(cross);
+duplicateDisplay.features[1].properties.display_id = duplicateDisplay.features[0].properties.display_id;
+assert.throws(() => validateTrafficSignalFeatures(duplicateDisplay), /Duplicate display_id/);
+const invalid = structuredClone(cross);
+invalid.features[0].properties.mast_reach_m = -1;
+assert.throws(() => validateTrafficSignalFeatures(invalid), /invalid mast_reach_m/);
+const invalidGeometry = structuredClone(cross);
+invalidGeometry.features[0].geometry = { type: "LineString", coordinates: [[120, 30], [121, 31]] };
+assert.throws(() => validateTrafficSignalFeatures(invalidGeometry), /geometry must be a finite Point/);
+const mismatchedIdentity = structuredClone(cross);
+mismatchedIdentity.features[0].properties.approach_id = "other-way:w1";
+assert.throws(() => validateTrafficSignalFeatures(mismatchedIdentity), /approach_id does not match source_way_id/);
+const invalidEnabled = structuredClone(cross);
+invalidEnabled.features[0].properties.enabled = "maybe";
+assert.throws(() => validateTrafficSignalFeatures(invalidEnabled), /invalid enabled/);
+assert.doesNotThrow(() => validateTrafficSignalSourceReferences(cross, [control]));
+assert.throws(
+  () => validateTrafficSignalSourceReferences(cross, [{ ...control, arms: arms.slice(1) }]),
+  /approach_id .* is not present on OSM control/,
+);
+assert.throws(
+  () => validateTrafficSignalSourceReferences(cross, []),
+  /control_id .* is not present in the current OSM/,
+);
+for (const disabledValue of [false, 0, "0", "false", "no"]) {
+  const disabled = structuredClone(cross);
+  disabled.features[0].properties.enabled = disabledValue;
+  assert.equal(buildTrafficSignalsFromFeatures(disabled).signals.length, 3);
+}
+for (const key of ["heading_deg", "phase_group", "stop_lon", "stop_lat", "z_offset_m"]) {
+  const missingNumber = structuredClone(cross);
+  missingNumber.features[0].properties[key] = null;
+  assert.throws(
+    () => validateTrafficSignalFeatures(missingNumber),
+    new RegExp(`missing ${key}`),
+    `${key} must not silently coerce null to zero`,
+  );
+}
+
+console.log("Traffic signal tests passed.");