Refactor area preview orchestration

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

@@ -488,6 +488,21 @@ File records use this shape:
 所有权属于独立 `preview` manifest。否则单跑 `--stages preview` 会把 Cesium manifest
 错误判 stale。
 
+### Preview Assembly Boundary
+
+`build-area.js` 是 stage orchestrator：它检查 GLB / metadata、按既有顺序写 route、vehicle、
+runtime 与 HTML，并写 preview manifest。预览内容实现不得回流到这里：
+
+- `lib/vehicle-route.js`：OSM XML -> route JSON object；保持坐标、排序、lane offset 和
+  `generatedAt` 语义。
+- `lib/vehicle-model.js`：-> preview vehicle glTF object；保持 mesh/material 名称和内嵌
+  buffer layout。
+- `lib/area-preview.js`：复制 browser runtime、生成 HTML、HTML/script JSON 转义和
+  preview summary。
+
+这是保持 standalone `--stages preview` 与 preview manifest ownership 不变的边界；这些模块
+不能读取 area config、写 stage manifest 或启动外部进程。
+
 `preview` manifest:
 
 - `inputs.config`
@@ -549,6 +564,10 @@ Manifest files are written atomically via `*.tmp` then `renameSync`.
 - `node --check scripts/build-area.js`
 - `node --check scripts/diagnose-area.js`
 - `node --check scripts/check-area.js`
+- `node --check scripts/lib/vehicle-route.js`
+- `node --check scripts/lib/vehicle-model.js`
+- `node --check scripts/lib/area-preview.js`
+- `npm run test:preview-assets`
 - `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages intermediates`
 - `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender`
 - `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages cesium`

.trellis/spec/pipeline/index.md

@@ -87,7 +87,7 @@ config/areas/<id>.json
 
 | 文件 | 行数 | 职责 |
 |---|---|---|
-| `build-area.js` | 961 | 主入口：区域配置读取、阶段调度、Cesium 预览页、车辆巡航和 stage manifest 写入 |
+| `build-area.js` | 约 530 | 主入口：区域配置读取、阶段调度、preview 文件写入和 stage manifest ownership |
 | `diagnose-area.js` | 36 | 快速诊断入口：调用共享 area diagnostics 并打印完整报告 |
 | `check-area.js` | 74 | 区域质量门入口：调用共享 area diagnostics，输出 PASS/FAIL 并设置退出码 |
 | `lib/area-diagnostics.js` | 776 | 共享区域诊断事实源：OSM、产物、metadata、stage manifest、GLB digest 和质量门分类 |
@@ -96,6 +96,9 @@ config/areas/<id>.json
 | `build-osm2streets-qgis.js` | 1468 | intermediates：osm2streets 解析、图层拆分、人行道转角合成、GeoPackage 与 QGIS 工程生成 |
 | `reimport-gpkg.js` | 179 | reimport：GeoPackage → GeoJSON 反向导出 |
 | `lib/scene-layers.js` | 164 | 九个图层的单一事实源 + 四个派生函数 |
+| `lib/vehicle-route.js` | 约 180 | 从 OSM 提取确定性预览巡航路线 |
+| `lib/vehicle-model.js` | 约 150 | 生成内嵌 buffer 的预览车辆 glTF |
+| `lib/area-preview.js` | 约 110 | 复制 preview runtime、生成 HTML 与转义配置注入 |
 | `lib/cesium-preview.js` / `.css` | 672 / 230 | 预览页运行时，见 [../preview/](../preview/index.md) |
 | `normalize-lane-arrows.py` | 182 | 合并 osm2streets 的三角网箭头（跑在 QGIS Python 里） |
 | `parity.js` | 270 | 产物一致性校验驱动 |

.trellis/spec/preview/index.md

@@ -1,6 +1,7 @@
 # Preview：Cesium 预览层
 
-> 覆盖 `scripts/lib/cesium-preview.js`（672 行）与 `cesium-preview.css`（230 行）。
+> 覆盖浏览器运行时 `scripts/lib/cesium-preview.js`（672 行）与
+> `cesium-preview.css`（230 行），以及 Node 侧的 `scripts/lib/area-preview.js`。
 > 运行时：浏览器。全仓唯一的 DOM 环境。
 
 ---
@@ -19,9 +20,9 @@
 ```
 scripts/lib/cesium-preview.js   ─── 原样 copyFileSync ──▶  outputs/<area>/cesium-preview.js
 scripts/lib/cesium-preview.css  ─── 原样 copyFileSync ──▶  outputs/<area>/cesium-preview.css
-                                                            （build-area.js:328-335）
+                                                            （area-preview.js:writeCesiumPreviewSupportFiles）
 <area>-cesium-preview.html      ─── 模板字符串生成 ────▶  同目录
-                                                            （build-area.js:697）
+                                                            （area-preview.js:cesiumPreviewHtml）
 ```
 
 所以：**没有打包、没有转译、没有 npm 依赖、没有模块系统**。浏览器直接吃。
@@ -40,18 +41,22 @@ const config = window.OSM_ASSET_PREVIEW_CONFIG || {};   // :4
 // config.areaId / .glbName / .metadataName / .routeName / .vehicleModelName
 ```
 
-生成侧在 `build-area.js:697 cesiumPreviewHtml()`，注入时**必须转义**：
+生成侧在 `scripts/lib/area-preview.js` 的 `cesiumPreviewHtml()`，注入时**必须转义**：
 
 | 场景 | 用 |
 |---|---|
-| HTML 文本/属性 | `escapeHtml()`（`build-area.js:759`） |
-| `<script>` 里的 JSON | `escapeScriptJson()`（`:767`） |
+| HTML 文本/属性 | `escapeHtml()` |
+| `<script>` 里的 JSON | `escapeScriptJson()` |
 
 `|| {}` 的兜底不能删——它让 JS 在没有配置块时也不至于在第一行就崩。
 
 **加一个新的可配置项**：`cesiumPreviewHtml()` 里加进注入的 JSON，JS 侧从 `config` 读，
 两边都要动。
 
+`build-area.js` 只保留 GLB / metadata 依赖检查、写入顺序和 preview manifest ownership；
+不要把 HTML 模板、runtime copy 或转义实现移回阶段调度器。路线 JSON 与车辆 glTF 分别由
+`vehicle-route.js` 和 `vehicle-model.js` 生成，二者都是不启动外部工具的 Node 模块。
+
 ---
 
 ## 加载流程