chore(road-editor): plan direct-edit task tree and add client test infra

Planning: parent design.md becomes the single authoritative contract
(constraint model with 6 kinds, handle manifest, coordinate/unit
layering, preview sequencing, storage layout and lazy migration, area
config snapshot, API contract). Work is split into four independently
verifiable child tasks with per-step gates and rollback points.

Test infra: pin vitest 4.1.11, add test:client:unit for client pure
logic, extend prettier globs to root *.ts so vitest.config.ts is checked.

Add .gitignore: the repo had none, so inputs/, outputs/, workbench-data/
and the client build output were untracked rather than ignored.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.trellis/tasks/08-26-direct-manipulation-road-editor/research/canvas-integration.md

@@ -0,0 +1,108 @@
+# Canvas 与控制柄工具方案
+
+## OpenLayers 能力确认
+
+当前项目使用 `ol@10.10.0`。OpenLayers `VectorLayer` 默认由 Canvas renderer 绘制，当前工作台正是这种模式。类型声明可确认：
+
+- `ol/interaction/Modify` 支持对 source/feature collection 的顶点修改，带 `modifystart` / `modifyend`、自定义 vertex style、pixel tolerance 与 hit detection。
+- `ol/interaction/Snap` 支持顶点、边、交点吸附，且会改写交互事件的 coordinate/pixel，供其他 pointer interaction 使用。
+- `ol/interaction/Translate` 支持 feature 集合的拖动和 start/move/end 事件。
+
+因此，OL 具备 Canvas 渲染、命中测试、投影换算、视口同步与低层 pointer 交互所需的基础能力。它没有白板编辑器的命令历史、语义控制柄、约束求解、工具状态或多对象选择模型。
+
+## 不使用原生 `Modify` 直接编辑道路面
+
+`Modify` 会直接改变传入 feature 的 geometry 坐标，也允许插入/删除顶点。这适合通用 GIS 几何编辑，但不适合本项目：道路面和路口面是编译产物，顶点没有稳定的编辑语义，直接修改会使车道、标线和 connector 脱节。
+
+它可被借鉴的只是事件生命周期、Canvas 命中与样式机制；道路源图层必须保持只读。
+
+## 建议架构
+
+```text
+OpenLayers Map / VectorLayer (Canvas)
+  - 基线与预览 GeoJSON 图层：只读、由编译器/preview solver 提供
+  - editHandles VectorLayer：Point/LineString feature，Canvas 画柄与影响区间
+  - EditPointerInteraction：命中 handle -> 投影拖拽方向 -> 更新 draft command
+  - Snap：只对批准的语义锚点/网格 source 生效
+       |
+       v
+React EditSession（selection、draft、undo/redo）
+       |
+       v
+constraint preview solver -> 仅更新受影响 source
+```
+
+控制柄是独立的、可丢弃的 UI feature；它的 properties 只携带 `handleId`，并通过 manifest 反查 semantic anchor。任何鼠标移动都先被投影为结构化约束值，再重算预览，绝不把 handle 的地理坐标直接写为道路 polygon 坐标。
+
+## 引入独立 Canvas 白板库的判断
+
+将 tldraw、Fabric、Konva 等作为覆盖层或替换 OL，均会引入第二个 viewport、平移/缩放手势、坐标系与 hit-test 系统。与地理坐标、OL hit detection、原有图层开关和地图导航同步的成本很高，且不能自动提供道路领域的约束模型。
+
+除非“Quickdraw”是一个能在既有地图 Canvas 内以 OpenLayers coordinate/pointer API 运行的明确库，否则首选是继续把 OL 作为唯一 Canvas 和视口，使用它成熟的 interaction primitives，加一个小而领域化的 `EditPointerInteraction`。这不是手写画布；渲染、坐标、事件和吸附都由 OL 提供，新增代码只负责道路语义。
+
+## 成熟的 OpenLayers 扩展：ol-ext
+
+`ol-ext` 是当前最匹配的成熟扩展候选：npm 最新版为 `4.0.38`（2026-02-23），BSD-3-Clause，仓库仍持续维护。其 `interaction/Transform` 明确提供：
+
+- 单独的 Canvas overlay layer 与可定制的 transform handles；
+- 与 `Select` 交互同步选择；
+- feature translate / scale / stretch / rotate；
+- `translatestart`、`translating`、`translateend`、`scalestart`、`scaling`、`scaleend` 等生命周期事件；
+- 通过 `PointerInteraction` 实现，因此共享 OpenLayers 的地图坐标、事件分发与视口。
+
+这能承担通用控制柄的视觉和 pointer 生命周期，消除自行实现 hover、命中、capture、拖拽状态机和控制柄绘制的大部分工作。
+
+### 不能委托给 ol-ext 的部分
+
+`Transform` 的最终行为仍是缩放、旋转或平移传入 feature 几何。其控制柄是矩形 bounding box，而道路编辑需要沿道路法线的 edge offset、沿中心线的范围控制和路口特定的 cutback/corner radius；这些语义并非该扩展的能力。
+
+推荐将 ol-ext 只绑定到**短生命周期 proxy feature**：
+
+```text
+语义 handle manifest -> proxy feature / ol-ext Transform
+  -> transform event -> 约束值（法向偏移、station interval、cutback、radius）
+  -> preview solver -> 新预览几何与新的 proxy
+```
+
+真实编译产物图层不可传给 `Transform`。对于不能表达为标准 translate/scale 的角部圆角和区间范围控制，仍需一个很小的领域 adapter；但它只做“事件到约束”的投影，不维护自己的 Canvas 或通用手势系统。
+
+## 建议的验证闸门
+
+在正式实现前完成一个隔离技术验证：将 `ol-ext` 的 Transform 绑定到单道路的临时 proxy，确认它能在当前 `ol@10.10.0`、React map 生命周期下稳定工作，并验证一次拖拽只更新 proxy/preview source、不会改写基线 source、不会重建地图。通过后再将它固定为依赖；不通过则保留 OpenLayers 原生 interaction 方案，避免在主分支承诺未经验证的扩展。
+
+## 有限探针与回退策略
+
+`ol-ext` 不是架构前提。探针只允许解决一个问题：复用通用 handle 的命中、pointer lifecycle 和视觉反馈。它有明确的时间上限和退出条件：
+
+| 结果 | 动作 |
+| --- | --- |
+| 可在临时 proxy 上平稳拖拽，且不写基线 source、不重建 Map | 作为标准 transform 代理的可选依赖 |
+| 与 `ol@10.10.0` 或 React 生命周期不兼容 | 删除探针，不迁移现有 MapCanvas；走原生 OL 方案 |
+| 能运行但矩形 scale/rotate 模型妨碍道路法线/路口约束 | 不把它用于道路手柄；仅保留可复用部分或删除 |
+| 探针超过预设时间仍无法达到以上条件 | 停止排障，按回退方案推进 |
+
+回退方案按优先顺序：
+
+1. **OpenLayers 原生 proxy + 小型 `PointerInteraction` adapter**：Point/LineString proxy 仍由 OL Canvas 绘制和命中，使用 `Snap` 处理吸附；adapter 只处理已命中的少量语义 handle 到 constraint 的投影。它不重写渲染、相机、图层或通用选择，工作量受限。
+2. **DOM handle overlay + 成熟手势库**：仅在当前选中道路/路口上放置少数固定像素的 React/HTML controls，用成熟拖拽手势库处理 pointer capture；每个地图 postrender 将它们用 `map.getPixelFromCoordinate()` 对齐。地图仍是唯一视口，未命中 handle 的事件继续交给 OL。适合复杂的范围、数值标签和路口控制，但不是 Canvas 风格。
+3. **不采用的方向**：迁移到 MapLibre/Leaflet 仅为获取绘制插件，或把 Quickdraw 叠到 OL 上。这会更换地图/视口基础设施，成本远高于有限 adapter，且不能解决道路语义。
+
+无论哪个输入 adapter 运行，`HandleManifest -> RoadEditOperation -> RoadConstraint -> preview solver` 的数据合同保持不变。因此探针失败最多替换输入层，不会推翻 schema、求解器或已保存编辑。
+
+## Drawtonomy 的关系
+
+公开 checkout 未包含 `Canvas.tsx`，也未在 package manifests 或 lockfile 中暴露 `tldraw`、Konva、Fabric、Excalidraw 或名为 Quickdraw 的依赖。因此不能从该源码确认其编辑器具体使用了哪个成熟 Canvas 库，只能借鉴其公开的对象图原则。
+
+## Quickdraw 核查结论
+
+检查 `/tmp/quickdraw` 后，确认它是 MIT 许可、零运行时依赖的完整无限白板 SDK，而不是地图编辑器控制柄库：
+
+- `packages/core/src/editor.js` 在传入 container 内创建自己的 scene canvas 和 overlay canvas，并实现独立 camera（`x/y/z`）、平移、缩放、pinch、pointer capture、hit test、selection 和 resize/rotate/arrow handles。
+- `packages/core/src/store.js` 使用不可变 record、transaction、diff、batch undo/redo；同一手势的连续更新会合并为一个 history entry。
+- 内建形状和工具是封闭集合（笔、箭头、几何形状、文字等），公开资料中没有可把 OpenLayers feature 注册为原生 shape/handle 或让它共享外部 map camera 的扩展接口。
+
+### 结论
+
+不将 Quickdraw 作为覆盖层或替代 OpenLayers：二者都会处理 pointer、wheel、pinch、屏幕到世界坐标转换和 camera，接入后要持续同步两套视口，且会破坏当前 OL 地图导航和图层命中。也不将 Quickdraw 的 flat drawing document 作为道路约束的存储格式。
+
+可直接借鉴的成熟实现原则是：固定像素尺寸的控制柄、overlay 与场景分离、pointer capture、一个 gesture 对应一个 transaction、不可变 diff 的 undo/redo、以及局部渲染。项目自身的 `EditSession` 应采用相同语义，但以 `RoadEditOperation` / `RoadConstraint` 为数据而非 Quickdraw shape。