Add feature registry dispatch

.trellis/spec/blender/index.md

@@ -38,6 +38,7 @@
 │   osmassets/materials.py  材质构建（消费 catalog 的声明）  │
 │   osmassets/tree.py       树实例化                        │
 │   osmassets/water.py grass.py scrub.py                    │
+│   osmassets/features.py    要素分发注册                  │
 │   osmassets/building.py fountain.py roads.py   要素装配   │
 │                                                          │
 │   generate_scene.py   export_cesium.py   两个入口         │
@@ -59,7 +60,7 @@
 
 | | `generate_scene.py` | `export_cesium.py` |
 |---|---|---|
-| 行数 | 999 | 624 |
+| 行数 | 895 | 647 |
 | 调用 | `--background --factory-startup --python` | `--background --python` |
 | 输入 | `--osm` + `--geojson`（可选） | `--blend` |
 | 输出 | `--output`(.blend)、`--render`(.png) | `--glb`、`--metadata`(.json) |
@@ -121,7 +122,7 @@
 
 | 文件 | 行数 | 层 |
 |---|---|---|
-| `generate_scene.py` | 869 | bpy · 入口 |
+| `generate_scene.py` | 895 | bpy · 入口 |
 | `export_cesium.py` | 647 | bpy · 入口 |
 | `osmassets/tree.py` | 318 | bpy |
 | `osmassets/geom.py` | 241 | 纯 |
@@ -129,6 +130,7 @@
 | `osmassets/catalog.py` | 197 | 纯 |
 | `osmassets/mesh.py` | 126 | bpy |
 | `osmassets/osm.py` | 89 | 纯 |
+| `osmassets/features.py` | 20 | bpy · 分发 |
 | `osmassets/building.py` / `fountain.py` / `roads.py` | 56 / 49 / 40 | bpy |
 | `osmassets/water.py` / `grass.py` / `scrub.py` | 15 / 22 / 13 | bpy |
 | `tools/scene_digest.py` | 171 | bpy · 工具 |

.trellis/spec/blender/module-structure.md

@@ -24,6 +24,7 @@
      osmassets/mesh.py       MeshBatch、prism、polyline
      osmassets/materials.py  材质构建
      osmassets/tree.py       树实例化
+     osmassets/features.py   要素分发注册
      osmassets/water.py  grass.py  scrub.py
      osmassets/building.py  fountain.py  roads.py       要素装配
      generate_scene.py  export_cesium.py      两个入口脚本
@@ -50,6 +51,7 @@
 | `catalog.py` | 纯 | `ROAD_LAYERS`、`MATERIALS`、`road_material_specs()`、`check_layers()` |
 | `mesh.py` | bpy | `MeshBatch`、`make_prism`、`add_roof`、`add_wall_panel`、`add_polyline`、集合管理 |
 | `materials.py` | bpy | 把 `catalog` 的规格变成真实材质：`from_spec()`、贴图、程序化噪声、tint、alpha-clip |
+| `features.py` | bpy | `FeatureHandler` 和 `dispatch_ways()`，保持 OSM way 要素 first-match 分发顺序 |
 | `tree.py` | bpy | 两个 vendored 模型 → 一套可实例化的运行时形状 |
 | `water.py` / `grass.py` / `scrub.py` | bpy | 单一 OSM 面要素的装配 |
 | `building.py` | bpy | 单一 OSM 面要素 `building=*` 的装配 |
@@ -124,22 +126,48 @@ def assemble_osm_fallback(ways, projector, collection, material): ...
 `scene["road_feature_counts"]` / `SCENE_DONE["road_features"]`。模块只负责把已选定的
 GeoJSON layer 或 OSM fallback ways 变成 `Road_<layer_id>` / `OSM_Road_<way_id>` 对象。
 
+### OSM way 要素注册
+
+`features.py` 只负责分发机制，不拥有 feature state：
+
+```python
+FeatureHandler = namedtuple("FeatureHandler", ("name", "matches", "handle"))
+dispatch_ways(ways, projector, handlers)
+```
+
+`dispatch_ways()` 的契约：
+
+- 对每个 way 先执行 `any(projector.inside(c) for c in way["coords"])`，不在范围内就跳过
+- 只投影一次 `ring = projector.ring(way["coords"])`
+- 按传入的 `handlers` 顺序检查
+- 第一个 `matches(way, tag, ring)` 为真的 handler 执行 `handle(way, tag, ring)` 后停止
+
+当前注册顺序必须等同旧 `if` / `elif` 链：
+
+```text
+water -> grass -> scrub -> tree_row -> building
+```
+
+这只是保守 registry，不是 ownership 反转。`generate_scene.py` 仍负责 collection /
+material 创建顺序、`counts`、`focus_points`、`tree_rows`、`scrub_trees`、scene metadata
+和 `SCENE_DONE`。不要把这些状态藏进 `features.py` 的全局变量里。
+
 ### 加一种新 OSM 要素
 
-目标形态：**新增一个模块 + 注册一行，不改 `build()`**。
+目标形态：**新增一个模块 + 在 OSM way handler 表里注册一项，不改主分发循环**。
 
 1. 新建 `osmassets/<feature>.py`，写 `assemble(...)`，签名照抄上面
 2. 只 import 需要的：`from osmassets.geom import clip_polygon`、
    `from osmassets.mesh import MeshBatch`
 3. 材质规格加进 `catalog.MATERIALS`（**追加到末尾**，顺序决定 GLB 材质索引）
-4. `generate_scene.py` 的要素分发处加一行调用
+4. `generate_scene.py` 的 OSM way handler 注册表里追加 handler，保持顺序语义明确
 5. 纯几何部分若有新函数，放 `geom.py` 并**补 `blender/tests/test_pure.py`**
 
 ---
 
 ## 两个入口脚本
 
-| | `generate_scene.py` (899行) | `export_cesium.py` (647行) |
+| | `generate_scene.py` (895行) | `export_cesium.py` (647行) |
 |---|---|---|
 | 调用 | `--background --factory-startup --python` | `--background --python` |
 | 输入 | `--osm` + `--geojson` | `--blend` |

.trellis/spec/guides/artifact-parity-guide.md

@@ -163,7 +163,7 @@ capturedAt / durationMs / label
 |---|---|---|
 | P0 | 抽纯函数到 `osmassets/{osm,geom}.py` | ✅ 已完成 |
 | P1 | `catalog.py` 单一定义源 + `check_layers` | ✅ 已完成 |
-| P2 | 要素注册表 | ⚠️ **部分**——`water/grass/scrub/tree/fountain/building/roads.py` 已拆出，但**没有 `features/` 注册表** |
+| P2 | 要素注册表 | ✅ 已完成（保守版）——`features.py` 注册 OSM way 分发顺序；`water/grass/scrub/tree/fountain/building/roads.py` 已拆出。材质、计数、metadata ownership 仍保留在 `generate_scene.py` |
 | P3 | 材质契约化（自定义属性传递 spec） | ✅ 已完成——`catalog.MATERIALS[*]["cesium"]` 经 `materials.from_spec()` 写入 `material["cesium_export"]`，`export_cesium.py` 优先读该属性；四张材质名表仅作旧 `.blend` 回退 |
 
 ### 已知缺陷（记录在案，本轮不修）