Refactor area preview orchestration

.trellis/tasks/08-04-split-area-build-orchestration/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/08-04-split-area-build-orchestration/design.md

@@ -0,0 +1,24 @@
+# Split area build orchestration design
+
+## Module Boundaries
+
+```text
+scripts/lib/vehicle-route.js   OSM XML -> preview route object
+scripts/lib/vehicle-model.js   -> vehicle glTF object
+scripts/lib/area-preview.js    HTML/template + runtime file copy + preview summary
+scripts/build-area.js          dependency checks, writes, stage timing, manifest ownership
+```
+
+`vehicle-route.js` and `vehicle-model.js` are pure Node modules. `area-preview.js` may use Node filesystem and path, but receives all names/paths through arguments; it must not import area config, stage manifest or spawn processes.
+
+## Preview Flow
+
+`build-area.writeCesiumPreview()` continues to ensure GLB/metadata, establish timing, write route/model/runtime/HTML in the existing order, and write `preview.manifest.json`. It delegates route construction, vehicle construction, support copy and HTML generation to the three modules.
+
+## Compatibility
+
+Public CLI and all generated filenames remain unchanged. The route's `generatedAt` naturally changes on each generation and is not a stable parity field; route segments, vehicle glTF structure and preview config are the stable contract. No Blender/GLB parity run is needed because no Blender or GLB generation code changes.
+
+## Rollback
+
+Restore the extracted functions to `build-area.js` and delete the three modules; no data migration or output cleanup is required.

.trellis/tasks/08-04-split-area-build-orchestration/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/08-04-split-area-build-orchestration/implement.md

@@ -0,0 +1,20 @@
+# Split area build orchestration implementation plan
+
+1. Extract vehicle route helpers into `vehicle-route.js`; add unit coverage using fixture OSM.
+2. Extract vehicle glTF builder into `vehicle-model.js`; assert schema, mesh/material counts and data URI.
+3. Extract preview support-file copy, HTML template, escaping and summary into `area-preview.js`.
+4. Replace `build-area.js` bodies with imports/calls while preserving preview manifest ownership and ordering.
+5. Run Node syntax/unit tests, then only the nantaizi `preview`, diagnose and quality gate commands.
+6. Update pipeline/preview specs and changelog; inspect diff for accidental stage or output changes.
+
+## Validation
+
+- `node --check scripts/build-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 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`
+- `git diff --check`

.trellis/tasks/08-04-split-area-build-orchestration/prd.md

@@ -0,0 +1,41 @@
+# Split area build orchestration
+
+## Goal
+
+将区域构建入口收敛为阶段调度器，把车辆路线、车辆 glTF 和 Cesium preview 组装移到职责明确的模块，降低后续修改预览功能时触碰 QGIS/Blender/Cesium 调度逻辑的风险。
+
+## Confirmed Facts
+
+- `scripts/build-area.js` 负责阶段调度，但其 440-928 行还包含 preview manifest、OSM 路线解析、路线几何、车辆 glTF 建模、HTML 模板和转义。
+- `preview` 已有独立 manifest ownership；`cesium` 调用 preview 生成，但 standalone `--stages preview` 必须继续有效。
+- preview HTML 向浏览器运行时注入 `areaId`、GLB、metadata、route 和 vehicle model 文件名；HTML / script JSON 使用不同转义函数。
+- 车辆路线和车辆 glTF 是预览辅助产物，不改变主 GLB；其内容仍属于 preview manifest 输出。
+- 本任务只验证南台子，不能改动 `hanyang-block` 或主动重跑重型阶段。
+
+## Requirements
+
+1. 新建纯 Node 模块承载 OSM 到车辆路线的解析与几何计算，保持 route JSON 的字段、排序、lane offset、时间戳语义和 deterministic coordinates 不变。
+2. 新建纯 Node 模块承载 preview 车辆 glTF 生成，保持 glTF schema、mesh/material 名称和二进制布局不变。
+3. 新建 preview assembly 模块承载 runtime 文件复制、HTML 模板与安全转义；`build-area.js` 仍拥有 preview 阶段依赖检查、文件写入顺序和 manifest 写入。
+4. 主入口不再定义以上预览/车辆实现细节，只通过模块 API 组装 preview 阶段。
+5. 不改变 CLI、stage 名称/aliases、stdout marker、manifest 字段、输出路径、默认行为或浏览器运行时。
+6. 对抽出的纯逻辑补 Node 测试，验证路线与 vehicle glTF 结构；通过南台子 preview 阶段和 diagnostics/check 确认真实产物仍有效。
+
+## Acceptance Criteria
+
+- [x] `build-area.js` 不再含路线解析、车辆 glTF mesh 构建、preview HTML 模板或转义实现。
+- [x] 新模块在不依赖 Blender/QGIS 的 Node 测试中覆盖路线和车辆 glTF 关键结构。
+- [x] 南台子 `--stages preview` 成功，preview manifest 仍 fresh，route / vehicle / HTML 文件可读且配置文件名不变。
+- [x] `diagnose:area` 和 `check:area` 对南台子仍通过。
+- [x] 所有修改脚本通过 Node 语法检查、`git diff --check`，且不运行 `hanyang-block`。
+
+## Out Of Scope
+
+- 不改变车辆路线算法、车模型外观、预览 HTML/UI、Cesium runtime 或 GLB 导出。
+- 不拆分 QGIS、Blender、Cesium 或 compression 的阶段实现。
+- 不新增前端构建系统或运行时依赖。
+
+## Key Decisions
+
+- 这是保守纯重构；输出内容和 manifest 契约比文件行数更重要。
+- preview assembly 依赖注入 filesystem/path/manifest 所需值，避免模块反向读取区域配置或启动外部进程。

.trellis/tasks/08-04-split-area-build-orchestration/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "split-area-build-orchestration",
+  "name": "split-area-build-orchestration",
+  "title": "Split area build orchestration",
+  "description": "Extract vehicle route, vehicle model, and preview assembly from build-area.js without changing area outputs.",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "dingkang",
+  "assignee": "dingkang",
+  "createdAt": "2026-08-04",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}