@allbluecn/web-app 0.17.1 → 0.18.0

package/src/design-engine/engine/engine-path.ts

@@ -0,0 +1,707 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import type { ILeaf } from "leafer-editor"
+
+import { serializePathAnchors, insertAnchorOnSegment, deleteAnchor, applyPointType, syncHandleOnDrag, hitTestPathEdit, pathValueToAnchors, cubicAt, type PathEditAnchor, type AnchorPointType, type PathEditHitModel, type PathEditHit } from "./path-anchors"
+import { isTypingTarget } from "@/components/design/canvas/tools/dom"
+import {
+  BOOLEAN_SHAPE_TYPES,
+  shapeToEditableAnchors,
+} from "./boolean-ops"
+import { DocEngine } from "./engine-doc"
+
+export class PathEditEngine extends DocEngine {
+  // ===== 路径锚点编辑（Enter 进入/退出，单选 path/pen-path）=====
+
+  // 锚点编辑状态：anchors 为节点局部坐标（与 props.path 同空间），装饰绘制
+  // 时换算 world → sky。selected 为锚点下标（画布点选，面板按钮作用于它）
+  protected pathEditState: {
+    nodeId: string
+    anchors: PathEditAnchor[]
+    closed: boolean
+    selected: number | null
+  } | null = null
+  private pathEditLeaves: Array<{ remove: () => void }> = []
+
+  get pathEditingNodeId(): string | null {
+    return this.pathEditState?.nodeId ?? null
+  }
+
+  // 面板查询：锚点数/闭合态/选中下标（快照读，不触发装饰）
+  getPathEditInfo(): { nodeId: string; count: number; closed: boolean; selected: number | null } | null {
+    if (!this.pathEditState) return null
+    return {
+      nodeId: this.pathEditState.nodeId,
+      count: this.pathEditState.anchors.length,
+      closed: this.pathEditState.closed,
+      selected: this.pathEditState.selected,
+    }
+  }
+
+  enterPathEdit(nodeId: string): boolean {
+    try {
+      return this.enterPathEditInner(nodeId)
+    } catch (error) {
+      return false
+    }
+  }
+
+  private enterPathEditInner(nodeId: string): boolean {
+    this.assertUsable()
+    const node = this.currentDoc.nodes.find((n) => n.id === nodeId)
+    if (!node || !BOOLEAN_SHAPE_TYPES.has(node.type)) {
+      return false
+    }
+    // 非 path 类型（矩形/椭圆/多边形/星形）进入编辑时转为矢量路径（Figma/
+    // Sketch 同语义：进入矢量编辑即栅格化为可编辑锚点）。用**最少锚点**模型
+    // （椭圆 4 锚 kappa 手柄、圆角矩形弧端交点、多边形顶点）而非布尔用的密
+    // 集采样轮廓；轮廓为**局部坐标**（不加 x/y 平移）——path 局部坐标 + 节点
+    // rotation 渲染 = 原视觉，避免旋转图形的双重错位。类型转换落一条 history
+    // （撤销恢复原图形类型）
+    if (node.type !== "path" && node.type !== "pen-path") {
+      const editable = shapeToEditableAnchors(node)
+      if (!editable || editable.anchors.length < 3) return false
+      const path = serializePathAnchors(editable.anchors, editable.closed)
+      this.history.push(this.currentDoc)
+      this.updateNodeGeometry(nodeId, { type: "path", props: { path } })
+    }
+    const current = this.currentDoc.nodes.find((n) => n.id === nodeId)
+    // props.path 缺失时从 leaf 兜底读取（导入/自动保存读回的 path 是 leafer
+    // 命令数组或原生属性，未提升到工具层 props 字符串约定）
+    let path: unknown = current?.props?.path
+    if (typeof path !== "string" && !Array.isArray(path)) {
+      const leaf = this.nodeIndex.get(nodeId) as unknown as { path?: unknown } | undefined
+      if (leaf && (typeof leaf.path === "string" || Array.isArray(leaf.path))) path = leaf.path
+    }
+    if (typeof path !== "string" && !Array.isArray(path)) {
+      return false
+    }
+    // 带手柄解析（C/Q 锚点保留 hIn/hOut；字符串与 leafer 命令数组双形态同
+    // 语义——自动保存读回命令数组不丢手柄）
+    const parsedPath = pathValueToAnchors(path)
+    if (!parsedPath || parsedPath.anchors.length < 2) {
+      return false
+    }
+    const anchors: PathEditAnchor[] = parsedPath.anchors
+    const closed = parsedPath.closed
+    if (anchors.length < 2) {
+      return false
+    }
+    this.exitPathEdit()
+    this.pathEditState = { nodeId, anchors, closed, selected: null }
+    this.setFrameInteractivity((frameId) => frameId === nodeId)
+    // 隐藏 editor 包围盒（Figma/Sketch：矢量编辑时选框不显示，锚点即选中态）。
+    // cancel 会触发空选中 SELECT 并清空权威选中态——路径编辑依赖 selection
+    // 定位编辑对象（面板/快捷键），取消后立即恢复
+    try {
+      this.app?.editor?.cancel()
+      this.selectionState = [nodeId]
+    } catch (error) {
+      this.selectionState = [nodeId]
+    }
+    this.drawPathEditDecor()
+    this.bindPathEditInteraction()
+    this.notifyDocChange()
+    return true
+  }
+
+  exitPathEdit(): void {
+    if (!this.pathEditState) return
+    const nodeId = this.pathEditState.nodeId
+    this.unbindPathEditInteraction()
+    this.clearPathEditDecor()
+    this.pathEditHitModel = { anchorPoints: [], segments: [] }
+    this.pathEditSegmentMap = []
+    this.pathEditState = null
+    // 恢复 editor 对该节点的选中（框重新显示）
+    this.select([nodeId])
+  }
+
+  // 画布点选锚点（装饰 leaf 点击回调；-1 = 点空白取消选中）
+  selectPathAnchor(index: number): void {
+    if (!this.pathEditState) return
+    this.pathEditState.selected = index >= 0 && index < this.pathEditState.anchors.length ? index : null
+    this.drawPathEditDecor()
+    this.notifySelectionChange()
+  }
+
+  // 拖拽锚点（世界坐标目标位 → 局部落库）。不入 history：START 时已 checkpoint
+  // 局部↔世界经 leaf 矩阵（getInnerPoint）：旋转/缩放/翻转节点下换算才正确
+  movePathAnchor(index: number, worldX: number, worldY: number): void {
+    const state = this.pathEditState
+    if (!state) return
+    const leaf = this.nodeIndex.get(state.nodeId)
+    const node = this.currentDoc.nodes.find((n) => n.id === state.nodeId)
+    if (!leaf || !node) return
+    const anchor = state.anchors[index]
+    if (!anchor) return
+    const inner = this.leafToInner(leaf, { x: worldX, y: worldY }) ?? { x: worldX - node.x, y: worldY - node.y }
+    // NaN 防线：拖拽中投影链瞬时的非有限值不得落锚点（实踩：NaN 写进 path
+    // 串永久损坏数据），直接丢弃本次
+    if (!Number.isFinite(inner.x) || !Number.isFinite(inner.y)) return
+    const dx = inner.x - anchor.x
+    const dy = inner.y - anchor.y
+    anchor.x = inner.x
+    anchor.y = inner.y
+    // 手柄随锚点平移（Figma/Sketch 语义）：否则曲线锚点一动控制点被留在原地，
+    // 形状撕裂
+    if (anchor.hIn) {
+      anchor.hIn.x += dx
+      anchor.hIn.y += dy
+    }
+    if (anchor.hOut) {
+      anchor.hOut.x += dx
+      anchor.hOut.y += dy
+    }
+    this.commitPathEdit()
+  }
+
+  // 拖拽选中锚点的手柄（which: in/out；世界坐标目标位）
+  movePathHandle(index: number, which: "in" | "out", worldX: number, worldY: number): void {
+    const state = this.pathEditState
+    if (!state) return
+    const leaf = this.nodeIndex.get(state.nodeId)
+    const node = this.currentDoc.nodes.find((n) => n.id === state.nodeId)
+    if (!leaf || !node) return
+    const anchor = state.anchors[index]
+    if (!anchor) return
+    const inner = this.leafToInner(leaf, { x: worldX, y: worldY }) ?? { x: worldX - node.x, y: worldY - node.y }
+    // 同 movePathAnchor：leaf 重建瞬间的非有限投影不落锚点
+    if (!Number.isFinite(inner.x) || !Number.isFinite(inner.y)) return
+    const handle = { x: inner.x, y: inner.y }
+    if (which === "in") anchor.hIn = handle
+    else anchor.hOut = handle
+    // 点类型联动：mirror 对称、asymmetric 反向共线（Sketch 语义）
+    syncHandleOnDrag(anchor, which)
+    this.commitPathEdit()
+  }
+
+  // 设置选中锚点的点类型（直角/镜像/不对称/断开，Sketch 点类型栏）
+  setAnchorPointType(type: AnchorPointType): boolean {
+    const state = this.pathEditState
+    if (!state || state.selected === null) return false
+    const anchor = state.anchors[state.selected]
+    if (!anchor) return false
+    applyPointType(anchor, type)
+    this.commitPathEdit()
+    return true
+  }
+
+  // 双击锚点：直角 ↔ 镜像切换（Sketch 惯例）
+  toggleAnchorType(): boolean {
+    const state = this.pathEditState
+    if (!state || state.selected === null) return false
+    const anchor = state.anchors[state.selected]
+    if (!anchor) return false
+    applyPointType(anchor, (anchor.pointType ?? "disconnected") === "straight" ? "mirror" : "straight")
+    this.commitPathEdit()
+    return true
+  }
+
+  // 面板查询：选中锚点详情（世界坐标 + 控制点长度/角度 + 点类型）
+  getSelectedAnchorInfo():
+    | {
+        x: number
+        y: number
+        pointType: AnchorPointType
+        handle?: { length: number; angle: number; which: "in" | "out" }
+      }
+    | null {
+    const state = this.pathEditState
+    if (!state || state.selected === null) return null
+    const anchor = state.anchors[state.selected]
+    const leaf = this.nodeIndex.get(state.nodeId)
+    if (!anchor || !leaf) return null
+    const world = this.leafToWorld(leaf, anchor) ?? { x: anchor.x, y: anchor.y }
+    const dragged = anchor.hIn ? ("in" as const) : anchor.hOut ? ("out" as const) : null
+    const handlePoint = dragged ? anchor[dragged === "in" ? "hIn" : "hOut"]! : null
+    return {
+      x: Math.round(world.x * 100) / 100,
+      y: Math.round(world.y * 100) / 100,
+      pointType: anchor.pointType ?? "disconnected",
+      handle: handlePoint
+        ? {
+            length: Math.round(Math.hypot(handlePoint.x - anchor.x, handlePoint.y - anchor.y) * 100) / 100,
+            angle: Math.round((Math.atan2(handlePoint.y - anchor.y, handlePoint.x - anchor.x) * 180) / Math.PI * 100) / 100,
+            which: dragged!,
+          }
+        : undefined,
+    }
+  }
+
+  // SAFETY: leafer ILeaf 运行时必有 getInnerPoint（声明在子接口未随 ILeaf
+  // 导出，同 board 插件 CoordinateLeaf 拆分惯例）；失败回退 null 由调用方兜底
+  private leafToInner(leaf: ILeaf, world: { x: number; y: number }): { x: number; y: number } | null {
+    try {
+      return (leaf as unknown as { getInnerPoint: (p: { x: number; y: number }) => { x: number; y: number } }).getInnerPoint(world)
+    } catch {
+      return null
+    }
+  }
+
+  protected leafToWorld(leaf: ILeaf, inner: { x: number; y: number }): { x: number; y: number } | null {
+    try {
+      // leafer 2.3.0 Leaf 公开 API：inner → world = getWorldPoint（返回值型；
+      // getLocalToWorld 是 void 写入 to，getWorldPointByInner 不存在——两个
+      // 错误尝试曾分别导致锚点回退手算漂移与整体投影失败）
+      return (leaf as unknown as {
+        getWorldPoint: (inner: { x: number; y: number }, relative?: unknown, distance?: boolean) => { x: number; y: number }
+      }).getWorldPoint(inner)
+    } catch {
+      return null
+    }
+  }
+
+  // client → world（tree 世界坐标）。⚠ leafer 2.3.0 的 client 点形态是
+  // {clientX, clientY}——getWorldPointByClient 委托 interaction.getLocal，其
+  // 内部只读 clientX/clientY，传 {x, y} 得 NaN（此前路径锚点拖拽被写坏 NaN
+  // 落库、toCanvas 系列消费方静默失效的共同根因）；返回值仍做非有限防御
+  protected clientToWorld(clientX: number, clientY: number): { x: number; y: number } | null {
+    const tree = this.app?.tree as unknown as
+      | { getWorldPointByClient?: (p: { clientX: number; clientY: number }, update?: boolean) => { x: number; y: number } }
+      | undefined
+    if (!tree) return null
+    try {
+      const world = tree.getWorldPointByClient?.({ clientX, clientY }, true) ?? null
+      if (!world || !Number.isFinite(world.x) || !Number.isFinite(world.y)) return null
+      return world
+    } catch {
+      return null
+    }
+  }
+
+  // 在选中锚点与其后锚点的段中点插入新锚点并选中
+  addPathAnchorAfterSelected(): boolean {
+    const state = this.pathEditState
+    if (!state) return false
+    const segIndex = state.selected ?? Math.max(0, state.anchors.length - 2)
+    const next = insertAnchorOnSegment(state.anchors, segIndex, state.closed)
+    if (!next) return false
+    state.anchors = next
+    state.selected = segIndex + 1
+    this.commitPathEdit()
+    return true
+  }
+
+  deleteSelectedPathAnchor(): boolean {
+    const state = this.pathEditState
+    if (!state || state.selected === null) return false
+    const next = deleteAnchor(state.anchors, state.selected)
+    if (!next) return false
+    state.anchors = next
+    state.selected = null
+    this.commitPathEdit()
+    return true
+  }
+
+  togglePathClosed(): boolean {
+    const state = this.pathEditState
+    if (!state) return false
+    state.closed = !state.closed
+    this.commitPathEdit()
+    return true
+  }
+
+  // 局部锚点 → props.path 落库（预览通道不入 history）+ 装饰重绘 + 面板推送
+  private commitPathEdit(): void {
+    const state = this.pathEditState
+    if (!state) return
+    // 末道防线：任何锚点/手柄含非有限坐标（上游防御漏网的投影污染）不序列化，
+    // 避免 "NaN" 字面量进 path 串破坏命令参数对齐
+    const finite = (v: number): boolean => Number.isFinite(v)
+    const valid = state.anchors.every(
+      (a) =>
+        finite(a.x) &&
+        finite(a.y) &&
+        (!a.hIn || (finite(a.hIn.x) && finite(a.hIn.y))) &&
+        (!a.hOut || (finite(a.hOut.x) && finite(a.hOut.y))),
+    )
+    if (!valid) return
+    const path = serializePathAnchors(state.anchors, state.closed)
+    this.updateNodeGeometry(state.nodeId, { props: { path } })
+    this.drawPathEditDecor()
+    this.notifyDocChange()
+  }
+
+  private clearPathEditDecor(): void {
+    for (const leaf of this.pathEditLeaves) {
+      try {
+        leaf.remove()
+      } catch {
+        // 目标可能已随树销毁
+      }
+    }
+    this.pathEditLeaves = []
+  }
+
+  // ===== 路径编辑交互（自算命中 + host 级 pointer 事件）=====
+  // 装饰只做渲染（hittable:false 纯视觉），命中/拖拽/插锚全部由 engine 依据
+  // client 命中模型自算（board 插件 pickLabel 先例）。此前挂靠 sky 装饰的
+  // leafer drag/click 事件在真实环境不触发，导致拖拽/选点完全失效——重做根因。
+
+  private pathEditHitModel: PathEditHitModel = { anchorPoints: [], segments: [] }
+  // 命中模型子段 → 锚点段参数映射（曲线细分产物；直线段恒等映射），与
+  // pathEditHitModel.segments 下标对齐
+  private pathEditSegmentMap: Array<{ seg: number; t0: number; t1: number }> = []
+  private pathEditDrag: { index: number } | null = null
+  private pathEditInteractionIds: Array<() => void> = []
+
+  // client 命中模型：锚点/线段的世界坐标投影（drawPathEditDecor 与命中共用）
+  protected buildPathEditHitModel(): void {
+    const state = this.pathEditState
+    const tree = this.app?.tree as unknown as
+      | { getClientPointByWorld: (w: { x: number; y: number }) => { x: number; y: number } }
+      | undefined
+    const leaf = state ? this.nodeIndex.get(state.nodeId) : undefined
+    if (!state || !tree || !leaf) {
+      this.pathEditHitModel = { anchorPoints: [], segments: [] }
+      return
+    }
+    // 官方交互同款：投影前强制布局（否则首次调用部分点的 __world 未就绪，
+    // getWorldPoint 对部分锚点失败 → 装饰回退局部坐标，出现「部分贴合部分漂移」）
+    try {
+      ;(leaf as unknown as { updateLayout: () => void }).updateLayout()
+    } catch {
+      // 布局不可用时按现状投影
+    }
+    // 视口 client → host 相对坐标（sky 无变换，装饰/hit 模型同用此坐标系；
+    // 曾因 sky.getWorldPointByClient 再叠加一次容器偏移导致装饰双重偏移）
+    const hostRect = this.host?.getBoundingClientRect() ?? { x: 0, y: 0 }
+    const toClient = (p: { x: number; y: number }): { x: number; y: number } => {
+      try {
+        const world = this.leafToWorld(leaf, p)
+        if (!world) return { x: 0, y: 0 }
+        const client = tree.getClientPointByWorld(world)
+        return { x: client.x - hostRect.x, y: client.y - hostRect.y }
+      } catch {
+        return { x: 0, y: 0 }
+      }
+    }
+    const anchorPoints = state.anchors.map(toClient)
+    const segments: PathEditHitModel["segments"] = []
+    // 曲线段细分映射：命中模型子段 → 锚点段全局 t（点曲线插锚时换算回贝塞尔
+    // 参数，de Casteljau 拆分才落在点击处）。直线段 t0/t1 = 0/1 恒等映射
+    const segSources: Array<{ seg: number; t0: number; t1: number }> = []
+    const segCount = state.closed ? state.anchors.length : state.anchors.length - 1
+    const CURVE_SUBDIV = 12
+    for (let i = 0; i < segCount; i++) {
+      const from = state.anchors[i]
+      const to = state.anchors[(i + 1) % state.anchors.length]
+      if (from.hOut || to.hIn) {
+        const c1 = from.hOut ?? { x: from.x, y: from.y }
+        const c2 = to.hIn ?? { x: to.x, y: to.y }
+        let prev = anchorPoints[i]
+        for (let s = 1; s <= CURVE_SUBDIV; s++) {
+          const t = s / CURVE_SUBDIV
+          const projected = toClient(cubicAt(from, c1, c2, to, t))
+          segments.push({ ax: prev.x, ay: prev.y, bx: projected.x, by: projected.y })
+          segSources.push({ seg: i, t0: (s - 1) / CURVE_SUBDIV, t1: t })
+          prev = projected
+        }
+      } else {
+        const a = anchorPoints[i]
+        const b = anchorPoints[(i + 1) % state.anchors.length]
+        segments.push({ ax: a.x, ay: a.y, bx: b.x, by: b.y })
+        segSources.push({ seg: i, t0: 0, t1: 1 })
+      }
+    }
+    this.pathEditHitModel = { anchorPoints, segments }
+    this.pathEditSegmentMap = segSources
+    if (typeof window !== "undefined") {
+      ;(window as unknown as Record<string, unknown>).__pathDebug = { anchorPoints, segments }
+    }
+  }
+
+  // host 内部坐标（client 相对视口 → 相对 host）：leafer 的 client 坐标系是
+  // 全局视口，命中模型的投影同为全局 client，故直接用 e.clientX/Y 比较
+  private pathEditHitAt(clientX: number, clientY: number): PathEditHit {
+    return hitTestPathEdit(this.pathEditHitModel, clientX, clientY)
+  }
+
+  // 在线段 index 的 t 处插入锚点并选中（Figma/Sketch：单击线段加锚点）。
+  // 插入落一条 history（可撤销回插入前）
+  insertPathAnchorAt(segIndex: number, t: number): boolean {
+    const state = this.pathEditState
+    if (!state) return false
+    const next = insertAnchorOnSegment(state.anchors, segIndex, state.closed, t)
+    if (!next) return false
+    this.history.push(this.currentDoc)
+    state.anchors = next
+    state.selected = segIndex + 1
+    this.commitPathEdit()
+    return true
+  }
+
+  private bindPathEditInteraction(): void {
+    const host = this.host
+    if (!host || typeof host.addEventListener !== "function") {
+      return
+    }
+    if (this.pathEditInteractionIds.length) {
+      return
+    }
+
+    // client → world 走数值求逆（见 clientToWorld），leafer 原生
+    // getWorldPointByClient 真机返回 NaN 不可用
+    const worldOfClient = (clientX: number, clientY: number): { x: number; y: number } | null =>
+      this.clientToWorld(clientX, clientY)
+
+    const onPointerDown = (e: PointerEvent): void => {
+      const state = this.pathEditState
+      if (!state || e.button !== 0) return
+      // 编辑模式独占 pointer：拦截 leafer 选中/框选（Figma 编辑态点其他元素不选中）
+      e.stopPropagation()
+      // 命中模型是 host 相对坐标（与装饰同系），事件全局坐标须同换算
+      const hostRect = host.getBoundingClientRect()
+      const hit = this.pathEditHitAt(e.clientX - hostRect.x, e.clientY - hostRect.y)
+      if (!hit) {
+        // 空白处：取消锚点选中（不退出编辑——Figma/Sketch 语义）
+        if (state.selected !== null) this.selectPathAnchor(-1)
+        return
+      }
+      let dragIndex: number
+      if (hit.kind === "anchor") {
+        this.selectPathAnchor(hit.index)
+        dragIndex = hit.index
+      } else {
+        // 单击线段 = 插入锚点并立即进入拖拽（Figma click-drag 语义）。曲线
+        // 段命中子段参数换算回锚点段全局 t，de Casteljau 拆分才落在点击处
+        const source = this.pathEditSegmentMap[hit.index] ?? { seg: hit.index, t0: 0, t1: 1 }
+        const t = source.t0 + (source.t1 - source.t0) * hit.t
+        this.insertPathAnchorAt(source.seg, t)
+        dragIndex = source.seg + 1
+      }
+      // 拖拽前置 checkpoint（拖拽过程 updateNodeGeometry 不入 history）
+      this.history.push(this.currentDoc)
+      this.pathEditDrag = { index: dragIndex }
+      try {
+        host.setPointerCapture(e.pointerId)
+      } catch {
+        // capture 不可用时 move 仍在 window 上收
+      }
+    }
+
+    // click/dblclick 一并拦截：防 canvas-root 的画板标签点击（pickFrameLabel）
+    // 与 React 层双击退出误触发（双击语义由 onDblClick 接管）
+    const swallow = (e: Event): void => {
+      if (this.pathEditState) e.stopPropagation()
+    }
+
+    const onDblClick = (e: MouseEvent): void => {
+      if (!this.pathEditState) return
+      e.stopPropagation()
+      const hostRect = host.getBoundingClientRect()
+      const hit = this.pathEditHitAt(e.clientX - hostRect.x, e.clientY - hostRect.y)
+      if (!hit) {
+        // 双击空白 = 退出编辑（Figma/Sketch 语义）
+        this.exitPathEdit()
+        return
+      }
+      if (hit.kind === "anchor") this.toggleAnchorType()
+    }
+
+    const onPointerMove = (e: PointerEvent): void => {
+      if (!this.pathEditDrag) return
+      const world = worldOfClient(e.clientX, e.clientY)
+      if (!world) return
+      this.movePathAnchor(this.pathEditDrag.index, world.x, world.y)
+    }
+
+    const onPointerUp = (): void => {
+      if (!this.pathEditDrag) return
+      this.pathEditDrag = null
+      // 拖拽结束落一条 history（与面板预览/提交同模式）
+      this.history.push(this.currentDoc)
+      this.notifyDocChange()
+    }
+
+    const onKey = (e: KeyboardEvent): void => {
+      const state = this.pathEditState
+      if (!state) return
+      if (isTypingTarget(e.target as HTMLElement)) return
+      // 捕获相：先于 document 的 useDeleteSelection，选中锚点时 Delete 只删锚点
+      if ((e.key === "Delete" || e.key === "Backspace") && state.selected !== null) {
+        e.preventDefault()
+        e.stopPropagation()
+        this.deleteSelectedPathAnchor()
+        return
+      }
+      const typeByKey: Record<string, AnchorPointType> = {
+        "1": "straight",
+        "2": "mirror",
+        "3": "asymmetric",
+        "4": "disconnected",
+      }
+      if (state.selected !== null && typeByKey[e.key]) {
+        e.preventDefault()
+        this.setAnchorPointType(typeByKey[e.key])
+      }
+    }
+
+    host.addEventListener("pointerdown", onPointerDown, true)
+    host.addEventListener("pointermove", onPointerMove)
+    host.addEventListener("pointerup", onPointerUp)
+    host.addEventListener("click", swallow, true)
+    host.addEventListener("dblclick", onDblClick, true)
+    window.addEventListener("keydown", onKey, true)
+    this.pathEditInteractionIds = [
+      () => host.removeEventListener("pointerdown", onPointerDown, true),
+      () => host.removeEventListener("pointermove", onPointerMove),
+      () => host.removeEventListener("pointerup", onPointerUp),
+      () => host.removeEventListener("click", swallow, true),
+      () => host.removeEventListener("dblclick", onDblClick, true),
+      () => window.removeEventListener("keydown", onKey, true),
+    ]
+  }
+
+  private unbindPathEditInteraction(): void {
+    for (const dispose of this.pathEditInteractionIds) dispose()
+    this.pathEditInteractionIds = []
+    this.pathEditDrag = null
+  }
+
+  // 锚点装饰（sky 层，纯渲染 hittable:false）：Sketch 式空心圆/实心选中圆/
+  // 菱形手柄。命中与拖拽由 bindPathEditInteraction 自算（不挂装饰事件）
+  protected drawPathEditDecor(): void {
+    const state = this.pathEditState
+    const sky = this.app?.sky as unknown as {
+      add: (child: unknown) => void
+      getWorldPointByClient: (p: { clientX: number; clientY: number }, update?: boolean) => { x: number; y: number }
+    }
+    const tree = this.app?.tree as unknown as {
+      getClientPointByWorld: (w: { x: number; y: number }) => { x: number; y: number }
+    }
+    const dbg = (msg: string): void => {
+      if (typeof window !== "undefined") {
+        const buf = ((window as unknown as Record<string, unknown>).__pathEditLog as string[] | undefined) ?? []
+        buf.push(msg)
+        ;(window as unknown as Record<string, unknown>).__pathEditLog = buf.slice(-30)
+      }
+    }
+    if (!state || !sky || !tree) {
+      dbg(`early-return sky=${Boolean(sky)} tree=${Boolean(tree)}`)
+      return
+    }
+    this.clearPathEditDecor()
+    const node = this.currentDoc.nodes.find((n) => n.id === state.nodeId)
+    if (!node) {
+      dbg(`early-return node missing ${state.nodeId}`)
+      return
+    }
+    const { Line, Rect, Ellipse } = this.mod
+    // 模块缺图形类（无头 mock）时静默降级为无装饰（同圆角拖拽守卫惯例）
+    if (!Line?.one || !Rect?.one || !Ellipse?.one) {
+      dbg("early-return mod classes missing")
+      return
+    }
+    dbg(`drawing decor for ${state.nodeId}`)
+
+    // 命中模型随装饰同步刷新（视口 CHANGE 由 bindCornerDragViewport 的
+    // 同款监听驱动本方法 drawPathEditDecor）
+    this.buildPathEditHitModel()
+    const { anchorPoints, segments } = this.pathEditHitModel
+
+    const make = (data: Record<string, unknown>): Record<string, unknown> => ({
+      hittable: false,
+      skipJSON: true,
+      ...data,
+    })
+    const attach = (leaf: { remove: () => void }): void => {
+      sky.add(leaf)
+      this.pathEditLeaves.push(leaf)
+    }
+
+    // 手柄（仅选中锚点）：连线 + 菱形
+    if (state.selected !== null) {
+      const anchor = state.anchors[state.selected]
+      const anchorPos = anchorPoints[state.selected]
+      if (anchor && anchorPos) {
+        for (const which of ["hIn", "hOut"] as const) {
+          const handle = anchor[which]
+          if (!handle) continue
+          const leaf = this.nodeIndex.get(state.nodeId)
+          const hWorld = (leaf && this.leafToWorld(leaf, handle)) ?? { x: node.x + handle.x, y: node.y + handle.y }
+          const hpos = (() => {
+            try {
+              const client = tree.getClientPointByWorld(hWorld)
+              return sky.getWorldPointByClient({ clientX: client.x, clientY: client.y }, true)
+            } catch {
+              return null
+            }
+          })()
+          if (!hpos) continue
+          attach(
+            Line.one(make({ points: [anchorPos.x, anchorPos.y, hpos.x, hpos.y], stroke: "rgba(99,102,241,0.9)", strokeWidth: 1 }), 0, 0) as never,
+          )
+          attach(
+            Rect.one(
+              make({
+                x: hpos.x - 4,
+                y: hpos.y - 4,
+                width: 8,
+                height: 8,
+                fill: "#ffffff",
+                stroke: "rgba(99,102,241,0.9)",
+                strokeWidth: 1,
+                rotation: 45,
+              }),
+              hpos.x - 4,
+              hpos.y - 4,
+            ) as never,
+          )
+        }
+      }
+    }
+
+    // 锚点圆（未选中空心 / 选中实心）
+    state.anchors.forEach((anchor, index) => {
+      const pos = anchorPoints[index]
+      if (!pos) return
+      const selected = index === state.selected
+      const radius = selected ? 5 : 4
+      attach(
+        Ellipse.one(
+          make({
+            x: pos.x - radius,
+            y: pos.y - radius,
+            width: radius * 2,
+            height: radius * 2,
+            fill: selected ? "rgba(99,102,241,0.9)" : "#ffffff",
+            stroke: selected ? "rgba(99,102,241,0.9)" : "rgba(99,102,241,0.75)",
+            strokeWidth: 1.4,
+          }),
+          pos.x - radius,
+          pos.y - radius,
+        ) as never,
+      )
+    })
+  }
+
+  toCanvas(clientX: number, clientY: number): { x: number; y: number } | null {
+    this.assertUsable({ allowUnmounted: true })
+    const tree = this.app?.tree
+    if (!tree) return null
+    // 原生 getWorldPointByClient 真机返回 NaN（含 {clientX,clientY} 传参形态
+    // 错误），统一走 clientToWorld 数值求逆；非有限值拒绝下发给消费方
+    const world = this.clientToWorld(clientX, clientY)
+    if (!world) return null
+    const local = tree.getInnerPoint(world)
+    if (!local || !Number.isFinite(local.x) || !Number.isFinite(local.y)) return null
+    return { x: Math.round(local.x), y: Math.round(local.y) }
+  }
+}