chore(task): archive 08-26-direct-edit-map-editor

.trellis/tasks/archive/2026-08/08-26-direct-edit-map-editor/research/client-synthesised-range-handles.md

@@ -0,0 +1,63 @@
+# 区间范围手柄由客户端合成
+
+第 4 步的实现决定，与 `design.md`「Handle manifest」小节的字面规则有偏离，故单独记录。
+决定人：dingkang，2026-08-27。
+
+## 偏离了什么
+
+`design.md` 写明：
+
+> 服务端从同一语义模型生成手柄清单，**客户端不自行推导手柄位置或可拖方向**。
+
+而区间范围手柄（第 4 类可拖能力）由客户端 `selection.ts` 的 `intervalRangeHandles()` 合成，
+位置由 `meters.ts` 的 `coordinateAtStation()` 从中心线插值得到。
+
+## 为什么这样定
+
+**1. manifest schema 装不下它。**
+`EditHandle.kind` 的类型是 `RoadConstraintKind`，而 `design.md` 的 kind 表明确声明
+「这 6 个 kind 与 PRD 首期范围一一对应，没有多余项也没有缺口」。
+范围手柄不是一种约束——它改的是既有约束 `anchor` 的 `startStation` / `endStation`。
+要下发就得加第 7 个求解器根本不认的假 kind，或加一个平行数组。为派生数据改合约不划算。
+
+**2. 它的位置是服务端已发数据的纯函数。**
+区间来自服务端算好并下发的 `anchor.startStation` / `endStation`，
+合法窗口来自 `manifest.reserves`，拖拽轴是道路切线。
+服务端下发等于把自己刚发的东西再算一遍回显，正是 `cross-layer-thinking-guide.md` 
+警告的「derived state 另立第二个游标」。
+
+**3. 决定性的一条：客户端本来就需要 station → 坐标的插值。**
+`design.md` 要求 ghost 画「半透明预估轮廓」，即在道路上标出受影响的区间带。
+画这条带子必须把 station 插值成坐标，**与范围手柄由谁产出无关**。
+`coordinateAtStation()` 因此是客户端的既有需求；有了它，合成范围手柄几乎免费，
+服务端改动买不到任何东西。
+
+**4. `projectIntervalEnd()` 已交付并测试**，签名恰好就是这些输入。
+
+## 为什么认为符合规则的意图
+
+那条规则防的是客户端发明**语义**——哪个约束、哪个方向、什么范围合法。
+范围手柄一样都没发明：
+
+| 语义 | 来源 |
+| --- | --- |
+| 合法窗口 | `manifest.reserves`（服务端） |
+| 区间当前值 | 约束 `anchor` 的 station（服务端） |
+| 拖拽轴 | 道路中心线切线（编译模型，服务端） |
+| 屏幕位置 | 客户端插值 ← **仅此一项是派生的** |
+
+客户端只做「把服务端已选定的 station 插值成屏幕位置」这一件事。
+
+## 已接受的代价
+
+`coordinateAtStation()` 是 `src/compile/direct-edit-solver.js` 里 `coordinateAt()` 的
+第二份实现。二者都用弧长插值，但分属不同 runtime（CommonJS 服务端 / ESM 浏览器），
+且客户端那份只服务于 ghost 渲染，不参与任何持久化或求解。
+`meters.ts` 的注释已标明这层关系，防止后来者误以为可以随意改动其中一份。
+
+## 若要改回服务端下发
+
+新增 manifest 字段 `rangeHandles: IntervalRangeHandle[]`（不要塞进 `handles`），
+由服务端用既有 `coordinateAt()` 算位置。客户端删掉 `intervalRangeHandles()` 即可，
+`projectIntervalEnd()` 与拖拽链路不受影响。
+`coordinateAtStation()` 仍需保留，因为 ghost 的区间带还要用。

.trellis/tasks/archive/2026-08/08-26-direct-edit-map-editor/research/interval-not-applied.md

@@ -0,0 +1,60 @@
+# 几何编译器不施加 `road-interval` 区间
+
+第 4 步手测时发现：区间范围手柄拖动有 ghost 反馈，但松手后几何毫无变化。
+经排查这是服务端的能力缺口，不是客户端拖拽逻辑的问题。
+
+## 事实
+
+`grep "\.interval\b" src/compile/native-road.js` 返回空。
+
+求解器写入了区间与过渡，几何阶段一个都不读：
+
+| profile 字段 | solver 写入 | `compileGeometry()` 读取 |
+| --- | --- | --- |
+| `edgeOffsets.left/right` | ✅ | ✅ `centerlineShift`（native-road.js:825） |
+| `widthMeters` | ✅ | ✅ native-road.js:832 |
+| `sidewalkWidths.left/right` | ✅ | ✅ 真实宽度，`sidewalkRing`（native-road.js:1666-1671） |
+| `laneDividerOffsets` | ✅ | ✅ native-road.js:1946 |
+| **`interval`** | ✅ direct-edit-solver.js:274-277、418 | ❌ **零消费者** |
+| **`transitions`** | ✅ direct-edit-solver.js:293、303、322 | ❌ **零消费者** |
+
+## 后果
+
+1. **每一次直接编辑都作用于整条路。** `anchor.startStation` / `endStation` 被存储、被
+   `validateEditDocument()` 校验、被带进 `resolveDirectEditConstraints()` 的结果，然后被忽略。
+2. **区间范围手柄在几何上不可能有效果。** 客户端的 `intervalRangeHandles()`、
+   `projectIntervalEnd()`、`coordinateAtStation()` 都正确且有单测，但下游无人接收。
+3. **`transition: 'smoothstep' | 'linear'` 是死字段。** 父任务 design.md 承诺
+   「作用于 interval 两端回归基线的过渡段」，实际没有任何过渡。
+
+## 已采取的处置
+
+`workbench/client/src/edit/flag.ts` 增加 `intervalEditingSupported = false`，
+范围手柄的 UI 据此隐藏。纯逻辑与测试全部保留。
+
+理由：一个拖起来有反馈、松手却没效果的控件比没有这个控件更糟——它会持续产生
+bug 报告，并让人怀疑整个编辑器的其余部分。区间生效的那个提交把这个常量翻成 `true` 即可，
+客户端不需要其他改动。
+
+## 对验收标准的影响
+
+父任务 prd.md 的这条**当前无法通过**：
+
+> 区间范围手柄可修改影响区间，两端平滑过渡回基线。
+
+`08-26-direct-edit-map-editor/prd.md` 的同名条目同理。这不是客户端欠工，
+而是需要 `compileGeometry()` 具备按 station 施加横断面 profile 的能力。
+
+## 若要实现（未排期）
+
+用户 2026-08-27 判断影响不大，故未开任务，仅记录。真要做时的形状：
+
+1. `native-road.js` 的横断面生成需要接受「沿中心线变化的 profile」而非单一常量宽度。
+   目前 `applyDirectEditProfiles()`（约 818-838 行）返回的是整条路一个 `widthMeters`
+   和一次 `offsetLine()` 整体平移，没有沿 station 变化的余地。
+2. 区间两端按 `transitions[kind]` 做 smoothstep / linear 插值回基线值。
+3. 车道线、标线、connector、步行带都由横断面派生，必须一并跟随，否则会脱节
+   （父任务 research/joint-solver.md 的依赖链）。
+4. `test/fixtures` 基线会变化，需要显式 update-baseline 并人工核对。
+
+这是 `compileGeometry` 的实质改动，属已归档的 `direct-edit-solver-api` 任务范围。

.trellis/tasks/archive/2026-08/08-26-direct-edit-map-editor/research/ol-ext-probe-result.md

@@ -0,0 +1,73 @@
+# ol-ext Transform 探针结论
+
+`implement.md` 第 1 步的门禁结果。人工验证由 dingkang 在浏览器完成，2026-08-27。
+
+## 门禁结果：三条全过
+
+| 门禁 | 结果 | 证据 |
+| --- | --- | --- |
+| OL `Map` 未重建 | 通过 | 实例 #2 / 累计构造 2 次（StrictMode 双挂载），2438 次 React 渲染下未重建 |
+| 基线 source 未被写入 | 通过 | 60 次拖拽，写入 0 次，几何指纹未变 |
+| proxy 拖拽稳定且事件能转成 draft 值 | 通过 | 1377 个 `translating` 事件；跟手连续、不跳数；松手不回弹；反复几十次不失手、不报错 |
+
+投影链路同时被验证：钳位范围内 `raw 3.924 / draft 3.924` 完全相等，说明
+`signedMetersAlongAxis()` → `projectHandleValue()` 的换算与钳位都正确。
+
+## 但不把 ol-ext 用于道路手柄
+
+门禁通过只意味着 ol-ext **可以**用（决策表第一行的「可选依赖」），不意味着它是更好的选择。
+探针同时暴露了决策表第三行的情况，因此按该行处置。
+
+### 决定性证据：手柄与约束值脱钩
+
+```
+translateend -> raw -24.146 / draft -5.400
+```
+
+`Transform` 的 translate 分支按原始 delta 调 `geometry.translate()`，不知道也不关心我们的钳位。
+于是手柄被拖到 -24.1 米处，而约束只到 -5.4 米——手柄停在道路永远不会变成的位置上。
+
+生产要求相反：手柄必须贴着钳位边界停下，位置由**约束值反算**而来，而不是跟随光标。
+这意味着位置更新必须由我们自己拥有。用 ol-ext 就得每帧撤销它刚做的 translate；
+自己写 `PointerInteraction` 则直接不移动过界。
+
+### 其余理由
+
+- 我们实际用到的只有「Point proxy 上的 translate + start/move/end 生命周期 + hitTolerance 命中」。
+  这些 `ol/interaction/Translate` 原生就有，且自带一等 TypeScript 类型。
+  ol-ext 的增量价值是 bounding box 的 scale / stretch / rotate —— 而道路法线偏移、
+  区间范围、路口 cutback 都用不上它，`canvas-integration.md` 早已指出这点。
+- ol-ext 4.0.38 不带类型，也没有 `@types/ol-ext`。采用它就要长期自己维护一份声明文件。
+  探针期间已经踩到一次：它的自定义事件名不在 OL 的事件类型联合里，
+  `on` / `un` 无法直接声明在类上，只能另设接口做一次转换。
+- 每个 mousemove 都会走 `handleMoveEvent_ → getFeatureAtPixel_ → forEachFeatureAtPixel`，
+  触发 OL 的 canvas 回读（控制台 `Canvas2D getImageData` 警告即来自此）。
+  这不是崩溃原因，但属于固有开销。
+
+## 探针期间发现的、与 ol-ext 无关的教训
+
+浏览器白屏一度被误当成 ol-ext 的稳定性问题，实际是探针自身的 bug：
+
+```
+at projectHandleValue (projection.ts:49)
+at ProbeMap.tsx:133
+at basicStateReducer → updateReducer → useState
+```
+
+几何计算被写在了 `setState` 的 updater 函数里。React 会延迟、且在 StrictMode 下重复调用
+updater；真正执行时闭包里的 `start` 已被 `translateend` 置为 `null`，于是 `toLonLat(null)` 抛错。
+`start!` 的非空断言正是把运行时问题藏过类型检查的地方。
+
+**教训（适用于第 3、4 步）**：绝不在 `setState` updater 内做几何计算或读取实时 OL 状态。
+先在事件处理器里算出普通值，再传进 updater。
+
+另一条：逐个 `translating` 事件更新 React state 会产生上千次渲染。探针用
+`requestAnimationFrame` 合并后才可用。生产要更进一步——ghost 直接写自己的 OL source，
+绝不为每次指针移动重渲染 React 树。
+
+## 结论
+
+按回退方案 1 推进：原生 OL `Snap` + 小型 `PointerInteraction` adapter，位置由约束值反算。
+
+`HandleManifest → RoadEditOperation → RoadConstraint → preview solver` 数据合约不变，
+第 2 步已交付的 `EditSession` / `projection` / `meters` 全部保留，探针已验证它们可用。

.trellis/tasks/archive/2026-08/08-26-direct-edit-map-editor/research/reserve-handles-unreachable.md

@@ -0,0 +1,70 @@
+# reserve 内手柄在当前服务端实现下不可达
+
+第 3 步人工验证时发现：点遍所有道路都看不到灰色（不可拖）手柄。经实测确认这是**正确行为**，不是漏测。
+
+## 实测数据
+
+`test/fixtures/fengshu-er-road.osm`，24 条方向道路、32 个 reserve：
+
+```
+road handles        : 126
+road NOT editable   : 0
+with disabledReason : 0
+junction handles    : 96   （JunctionTools 所有，主地图已过滤）
+```
+
+## 为什么不可达
+
+`makeRoadHandles()` 里 `editable: false` 的唯一来源是 `unavailable`：
+
+```js
+const start = Math.min(1, startReserve);
+const end = Math.max(0, 1 - endReserve);
+const unavailable = start >= end;
+```
+
+而 `junctionReserves()` 给每端的保留区比例有硬上限：
+
+```js
+const fraction = Math.min(0.45, cutback / length);
+```
+
+于是 `startReserve ≤ 0.45`、`endReserve ≤ 0.45`，即 `start ≤ 0.45` 且 `end ≥ 0.55`。
+`start >= end` 结构上永远为假，`unavailable` 分支是死代码。
+
+实测输出里能直接看到上限生效的样子——两端都撞到 0.45 的短路段：
+
+```
+segment:way/858770822/1   window=[0.450,0.550]
+segment:way/117947564/0   window=[0.450,0.550]
+segment:way/851989492/2   window=[0.450,0.550]
+```
+
+另外手柄的 station 取自 `(start + end) / 2`，即无保留区窗口的正中，
+所以三类道路手柄的位置也永远不会落进 reserve。
+
+## 对验收标准的影响
+
+prd.md 的「落在 junction reserve 内的手柄不可拖动，并提示进入 JunctionTools」
+对当前三类道路手柄是**空真**：它们永远不落在 reserve 内，所以约束自动成立。
+
+客户端一侧的置灰与原因提示路径有单测覆盖（`selection.test.ts`：disabled 手柄被保留、
+`disabledReasonOf` 始终给出原因），只是服务端从不产生这种输入。因此第 3 步不需要改动。
+
+reserve 边界真正变得用户可见是在第 4 步的**区间范围手柄**：它可以被拖向 reserve 边界，
+由 `projectIntervalEnd()` 钳到 `window.minStation` / `maxStation`。届时这条边界才有可演示的行为。
+
+## 留给用户决定的设计问题
+
+那个死分支暗示原作者期望「短路段应完全归 JunctionTools」。但 0.45 的上限把结果改成了：
+一条几何上被两个大路口主导的短路，仍然会在正中间得到一条仅占全长 10% 的可编辑带
+（上面 `[0.450,0.550]` 那几条）。
+
+两种取向都讲得通，需要产品判断：
+
+- 保持现状：任何道路都留一条可编辑带，哪怕很窄。
+- 改为：当 `cutback / length` 两端之和超过某阈值时，整条路标 `editable: false`，
+  引导用户进入 JunctionTools。这会让死分支复活，也让验收标准变成可演示的。
+
+改动落在 `src/compile/direct-edit-solver.js`（属已归档的 `direct-edit-solver-api` 任务范围），
+不在本任务范围内，故此处只记录不实施。