@allbluecn/web-app 0.17.2 → 0.18.1

package/src/design-engine/engine/__tests__/engine.test.ts

@@ -0,0 +1,1321 @@
+import { describe, expect, it, vi, beforeEach } from "vitest"
+import type { SceneDocument, SceneNode } from "@/components/design/canvas/document/types"
+import { applyConstraintsDiff } from "@/components/design/canvas/document/constraints"
+import { BOARD_NODE_ID, createBoardNode, createEmptyDoc } from "@/components/design/canvas/document/types"
+
+vi.mock("../../document/serialize", () => {
+  type MockNode = {
+  id: string
+  parent?: MockNode
+  x?: number
+  y?: number
+  children: MockNode[]
+  width?: number
+  height?: number
+  getBounds?: () => { x: number; y: number; width: number; height: number }
+  getInnerPoint?: (world: { x: number; y: number }) => { x: number; y: number }
+  getWorldPoint?: (inner: { x: number; y: number }) => { x: number; y: number }
+  set?: (config: Record<string, unknown>) => void
+  addAt?: (child: MockNode, index: number) => void
+  remove?: () => void
+}
+
+  function docToScene(doc: SceneDocument) {
+    // board 尺寸取自 doc 的 board 节点（新架构 board 作为 tree 子元素自带尺寸）
+    const boardMeta = doc.nodes.find((node) => node.id === BOARD_NODE_ID)
+    const boardWidth = boardMeta?.width ?? 0
+    const boardHeight = boardMeta?.height ?? 0
+    const board: MockNode = {
+      id: BOARD_NODE_ID,
+      children: [],
+      width: boardWidth,
+      height: boardHeight,
+      // 官方 ILeaf 包围盒 mock（fit() 回落 board 时读 world 包围盒）
+      getBounds: () => ({ x: 0, y: 0, width: boardWidth, height: boardHeight }),
+      // re-parent/标签拖拽的坐标换算 mock（identity）
+      getInnerPoint: (world: { x: number; y: number }) => ({ x: world.x, y: world.y }),
+      getWorldPoint: (inner: { x: number; y: number }) => ({ x: inner.x, y: inner.y }),
+    }
+    const nodeIndex = new Map<string, unknown>([[BOARD_NODE_ID, board]])
+    // 名称标签 mock：与 serialize 实现一致（board 层、id 内嵌画板 id、含 getBounds）
+    const frameLabels = new Map<string, unknown>()
+    for (const node of doc.nodes ?? []) {
+      if (node.id === BOARD_NODE_ID) continue
+      if (node.type !== "frame") continue
+      const x = node.x ?? 0
+      const y = (node.y ?? 0) - 28
+      frameLabels.set(node.id, {
+        id: `frame_label:${node.id}`,
+        x,
+        y,
+        // on 记录订阅（bindFrameLabelDrag 的 DRAG/END 监听可测试触发）
+        subs: [] as { type: string; cb: (e?: unknown) => void }[],
+        on: vi.fn(function (this: { subs: { type: string; cb: (e?: unknown) => void }[] }, type: string, cb: (e?: unknown) => void) {
+          this.subs.push({ type, cb })
+        }),
+        getBounds: () => ({ x, y, width: 80, height: 18 }),
+      })
+    }
+    for (const node of doc.nodes ?? []) {
+      if (node.id === BOARD_NODE_ID) continue
+      const leaf: MockNode = {
+        parent: board as unknown as MockNode,
+        id: node.id,
+        x: node.x ?? 0,
+        y: node.y ?? 0,
+        children: [],
+        width: node.width ?? 100,
+        height: node.height ?? 100,
+        // 官方 ILeaf 包围盒 mock（sync/zoomToFrame/focusNode 读 world 包围盒）
+        getBounds: () => ({
+          x: node.x ?? 0,
+          y: node.y ?? 0,
+          width: node.width ?? 100,
+          height: node.height ?? 100,
+        }),
+        // 官方 leaf.set：合并 config（增量 patch 路径）
+        set: (config: Record<string, unknown>) => Object.assign(leaf, config),
+        // 官方 addAt：按 index 插入 children（增量重排路径）
+        addAt: (child: MockNode, index: number) => {
+          const i = leaf.children.indexOf(child)
+          if (i >= 0) leaf.children.splice(i, 1)
+          leaf.children.splice(Math.min(index, leaf.children.length), 0, child)
+        },
+        // 官方 remove：从父 children 摘除（增量删除路径）
+        remove: () => {
+          for (const candidate of (nodeIndex as Map<string, MockNode>).values()) {
+            const i = candidate.children.indexOf(leaf)
+            if (i >= 0) {
+              candidate.children.splice(i, 1)
+              return
+            }
+          }
+        },
+      }
+      nodeIndex.set(node.id, leaf)
+      board.children.push(leaf)
+    }
+    return { leafer: board, nodeIndex, frameLabels }
+  }
+
+  function leaferToDoc(tree: { children?: SceneNode[]; width?: number; height?: number }, opts?: { device?: "desktop" | "tablet" | "mobile" }) {
+    // 新架构：board 是 tree 的直接子元素（id=BOARD_NODE_ID），子图形挂在 board 下；
+    // 兼容旧结构（图形直接挂在 tree 上）
+    const treeChildren = Array.isArray(tree.children) ? tree.children : []
+    const boardChild = treeChildren.find((child) => child.id === BOARD_NODE_ID)
+    const shapeChildren = boardChild && Array.isArray((boardChild as { children?: SceneNode[] }).children)
+      ? ((boardChild as { children?: SceneNode[] }).children as SceneNode[])
+      : treeChildren
+    const boardWidth = boardChild?.width ?? tree.width ?? 1200
+    const boardHeight = boardChild?.height ?? tree.height ?? 812
+    return {
+      version: 1 as const,
+      meta: { device: opts?.device },
+      nodes: [
+        {
+          id: BOARD_NODE_ID,
+          kind: "group" as const,
+          type: "board" as const,
+          parentId: null,
+          name: "Board",
+          x: 0,
+          y: 0,
+          width: boardWidth,
+          height: boardHeight,
+          style: { fill: "#ffffff" },
+          locked: true,
+        },
+        ...shapeChildren.map<SceneNode>((child) => ({
+          id: child.id,
+          kind: "shape",
+          type: "rect",
+          parentId: BOARD_NODE_ID,
+          name: "Rect",
+          x: 0,
+          y: 0,
+          width: child.width ?? 100,
+          height: child.height ?? 100,
+        })),
+      ],
+    }
+  }
+
+  // 增量 reconcile 路径共用构建（与 docToScene mock 的 leaf/label 形态一致）
+  function buildSceneElement(node: SceneNode) {
+    const leaf: MockNode = {
+      id: node.id,
+      x: node.x ?? 0,
+      y: node.y ?? 0,
+      children: [],
+      width: node.width ?? 100,
+      height: node.height ?? 100,
+      getBounds: () => ({ x: node.x ?? 0, y: node.y ?? 0, width: node.width ?? 100, height: node.height ?? 100 }),
+      set: (config: Record<string, unknown>) => Object.assign(leaf, config),
+    }
+    let label: MockNode | null = null
+    if (node.type === "frame" && typeof node.name === "string" && node.name) {
+      label = {
+        id: `frame_label:${node.id}`,
+        x: node.x ?? 0,
+        y: (node.y ?? 0) - 28,
+        children: [],
+        getBounds: () => ({ x: node.x ?? 0, y: (node.y ?? 0) - 28, width: 80, height: 18 }),
+        ...( {} as Pick<MockNode, never> & Record<string, unknown> ),
+      } as unknown as MockNode
+    }
+    return { element: leaf, label }
+  }
+  function leafConfigOf(node: SceneNode) {
+    return {
+      x: node.x,
+      y: node.y,
+      width: node.width,
+      height: node.height,
+      visible: node.visible ?? true,
+      locked: node.locked === true,
+      ...(node.style ?? {}),
+    }
+  }
+
+  return {
+    docToScene: vi.fn(docToScene),
+    leaferToDoc: vi.fn(leaferToDoc),
+    sanitizeScene: vi.fn((doc: SceneDocument) => doc),
+    addLeaf: (parent: MockNode, child: MockNode) => {
+      const i = parent.children.indexOf(child)
+      if (i >= 0) parent.children.splice(i, 1)
+      parent.children.push(child)
+    },
+    buildSceneElement: vi.fn(buildSceneElement),
+    leafConfigOf: vi.fn(leafConfigOf),
+    FRAME_LABEL_ID_PREFIX: "frame_label:",
+    FRAME_LABEL_OFFSET_Y: 28,
+  }
+})
+
+vi.mock("@/components/design/canvas/registry/builtin", () => ({ registerAllBuiltins: vi.fn() }))
+
+import { LeaferEngine } from "../app"
+
+type MockLeaf = { id: string; children: MockLeaf[]; width?: number; height?: number }
+type MockSub = { type: string; cb: (e?: unknown) => void }
+
+function makeTree() {
+  const tree = {
+    children: [] as MockLeaf[],
+    width: undefined as number | undefined,
+    height: undefined as number | undefined,
+    add: vi.fn((child: MockLeaf) => {
+      tree.children.push(child)
+    }),
+    remove: vi.fn((child: MockLeaf) => {
+      const index = tree.children.indexOf(child)
+      if (index >= 0) tree.children.splice(index, 1)
+    }),
+    // 官方坐标转换 mock：identity（client=world=sky 内部坐标）
+    getClientPointByWorld: vi.fn((world: { x: number; y: number }) => ({ x: world.x, y: world.y })),
+    getWorldPointByClient: vi.fn((p: { clientX: number; clientY: number }) => ({ x: p.clientX, y: p.clientY })),
+    getWorldPoint: vi.fn((inner: { x: number; y: number }) => ({ x: inner.x, y: inner.y })),
+    getInnerPoint: vi.fn((world: { x: number; y: number }) => ({ x: world.x, y: world.y })),
+    // 官方 find 插件 findOne('#id') mock：递归按 id 查找
+    findOne: vi.fn((condition: string): MockLeaf | undefined => {
+      if (!condition.startsWith("#")) return undefined
+      const id = condition.slice(1)
+      const walk = (node: { id?: string; children?: unknown[] }): MockLeaf | undefined => {
+        if (node.id === id) return node as MockLeaf
+        for (const child of node.children ?? []) {
+          const hit = walk(child as { id?: string; children?: unknown[] })
+          if (hit) return hit
+        }
+        return undefined
+      }
+      return walk(tree)
+    }),
+  }
+  return tree
+}
+
+function makeEditor() {
+  const editor = {
+    list: [] as MockLeaf[],
+    subs: [] as MockSub[],
+    select: vi.fn((target: MockLeaf | MockLeaf[]) => {
+      editor.list = Array.isArray(target) ? [...target] : [target]
+    }),
+    cancel: vi.fn(() => {
+      editor.list = []
+    }),
+    on_: vi.fn((type: string, cb: (e?: unknown) => void) => {
+      editor.subs.push({ type, cb })
+      return { type, current: editor, listener: cb, options: undefined }
+    }),
+    off_: vi.fn((ids: unknown) => {
+      const list = Array.isArray(ids) ? ids : [ids]
+      for (const id of list) {
+        const item = id as { type: string; listener: () => void }
+        editor.subs = editor.subs.filter(
+          (sub) => !(sub.type === item.type && sub.cb === item.listener),
+        )
+      }
+    }),
+  }
+  return editor
+}
+
+function makeApp(config: { editor?: Record<string, unknown> }) {
+  const editor = makeEditor()
+  const app = {
+    tree: makeTree(),
+    // sky 装饰层：与 tree 同构（add/remove/children），名称标签挂载于此
+    sky: makeTree(),
+    editor: config.editor ? editor : undefined,
+    mode: "normal" as string,
+    zoom: vi.fn(),
+    // zoomLayer mock：move 模拟官方相对位移语义（x += dx）；on_/off_ 走订阅表
+    zoomLayer: {
+      scaleX: 1,
+      x: undefined as number | undefined,
+      y: undefined as number | undefined,
+      subs: [] as MockSub[],
+      move: vi.fn(function (this: { x?: number; y?: number }, p: { x: number; y: number }) {
+        this.x = (this.x ?? 0) + p.x
+        this.y = (this.y ?? 0) + p.y
+      }),
+      on_: vi.fn(function (this: { subs: MockSub[] }, type: string, cb: (e?: unknown) => void) {
+        this.subs.push({ type, cb })
+        return { type, current: this, listener: cb, options: undefined }
+      }),
+      off_: vi.fn(function (this: { subs: MockSub[] }, ids: unknown) {
+        const list = Array.isArray(ids) ? ids : [ids]
+        for (const id of list) {
+          const item = id as { type: string; listener: () => void }
+          this.subs = this.subs.filter(
+            (sub) => !(sub.type === item.type && sub.cb === item.listener),
+          )
+        }
+      }),
+    },
+    // 官方拾取器 mock：默认未命中（target null），测试按需覆写
+    selector: {
+      getByPoint: vi.fn(
+        (_point: unknown, _radius: number, _options?: { findList?: unknown[] }): {
+          target: unknown
+        } => ({ target: null }),
+      ),
+    },
+    destroy: vi.fn(),
+    subs: [] as MockSub[],
+    on_: vi.fn((type: string, cb: (e?: unknown) => void) => {
+      app.subs.push({ type, cb })
+      return { type, current: app, listener: cb, options: undefined }
+    }),
+    off_: vi.fn((ids: unknown) => {
+      const list = Array.isArray(ids) ? ids : [ids]
+      for (const id of list) {
+        const item = id as { type: string; listener: () => void }
+        app.subs = app.subs.filter(
+          (sub) => !(sub.type === item.type && sub.cb === item.listener),
+        )
+      }
+    }),
+  }
+  // 标签插件的 zoomLayer 查找链：tree.leafer.zoomLayer（指向 app.zoomLayer）
+  ;(app.tree as unknown as { leafer?: { zoomLayer?: unknown } }).leafer = {
+    zoomLayer: app.zoomLayer,
+  }
+  return app
+}
+
+function makeMod() {
+  const apps = [] as ReturnType<typeof makeApp>[]
+  const App = vi.fn(function (config: { editor?: Record<string, unknown> }) {
+    const app = makeApp(config)
+    apps.push(app)
+    return app
+  })
+
+  return {
+    App,
+    apps,
+    // 标签插件 createLabel 用（one 返回 MockElement，含 getBounds 供命中/投影）
+    // 标签插件 createLabel 用：one 返回带 getBounds/subs/remove 的 mock 标签
+    Text: {
+      one: vi.fn((config: Record<string, unknown> = {}) => {
+        const label: Record<string, unknown> = {
+          ...config,
+          children: [] as unknown[],
+          getBounds: () => ({
+            x: (label.x as number) ?? 0,
+            y: (label.y as number) ?? 0,
+            width: 80,
+            height: 18,
+          }),
+          subs: [] as { type: string; cb: (e?: unknown) => void }[],
+          remove: vi.fn(() => {}),
+        }
+        ;(label as { on: (t: string, cb: (e?: unknown) => void) => void }).on = (
+          t: string,
+          cb: (e?: unknown) => void,
+        ) => {
+          ;(label.subs as { type: string; cb: (e?: unknown) => void }[]).push({ type: t, cb })
+        }
+        return label
+      }),
+    },
+    fire(editor: ReturnType<typeof makeEditor>, type: string) {
+      for (const sub of [...editor.subs]) {
+        if (sub.type === type) sub.cb()
+      }
+    },
+    EditorEvent: { SELECT: "editor.select" },
+    EditorMoveEvent: { MOVE: "editor.move" },
+    EditorScaleEvent: { SCALE: "editor.scale" },
+    EditorRotateEvent: { ROTATE: "editor.rotate" },
+    EditorSkewEvent: { SKEW: "editor.skew" },
+    DragEvent: { START: "drag.start", END: "drag.end", DRAG: "drag.drag" },
+    PropertyEvent: { CHANGE: "property.change" },
+    PointerEvent: { DOUBLE_CLICK: "double_click" },
+    fireApp(app: ReturnType<typeof makeApp>, type: string, event?: unknown) {
+      for (const sub of [...app.subs]) {
+        if (sub.type === type) sub.cb(event)
+      }
+    },
+  }
+}
+
+function shapeNode(overrides: Partial<SceneNode> = {}): SceneNode {
+  return {
+    id: "n1",
+    kind: "shape",
+    type: "rect",
+    parentId: BOARD_NODE_ID,
+    name: "Rect",
+    x: 10,
+    y: 20,
+    width: 100,
+    height: 50,
+    ...overrides,
+  }
+}
+
+function docWith(...shapes: SceneNode[]): SceneDocument {
+  return { version: 1, meta: { device: "desktop" }, nodes: [createBoardNode("desktop"), ...shapes] }
+}
+
+let mod: ReturnType<typeof makeMod>
+let el: HTMLElement
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mod = makeMod()
+  el = { } as HTMLElement
+})
+
+function liveLeaves(): MockLeaf[] {
+  const tree = mod.apps[0].tree
+  const board = (tree.children ?? []).find((child) => child.id === BOARD_NODE_ID) as MockLeaf | undefined
+  return board?.children ?? []
+}
+
+describe("LeaferEngine", () => {
+  it("mount 后 getDoc 返回仅含 board 的空文档", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const cb = vi.fn()
+    engine.onDocChange(cb)
+
+    const doc = engine.getDoc()
+    expect(doc.nodes).toHaveLength(1)
+    expect(doc.nodes[0].id).toBe(BOARD_NODE_ID)
+    expect(cb).not.toHaveBeenCalled()
+  })
+
+  it("重复 mount 抛错", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+
+    expect(() => engine.mount(el)).toThrow(/already mounted/)
+  })
+
+  it("setTool 切换后 getTool 一致且回调收到新值", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const cb = vi.fn()
+    engine.onToolChange(cb)
+
+    engine.setTool("text")
+
+    expect(engine.getTool()).toBe("text")
+    expect(cb).toHaveBeenCalledTimes(1)
+    expect(cb).toHaveBeenLastCalledWith("text")
+    expect(mod.apps[0].mode).toBe("draw")
+
+    engine.setTool("select")
+    expect(engine.getTool()).toBe("select")
+    expect(mod.apps[0].mode).toBe("normal")
+  })
+
+  it("loadDoc 触发 onDocChange，且 getDoc 反映载入内容", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const cb = vi.fn()
+    engine.onDocChange(cb)
+
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+
+    expect(cb).toHaveBeenCalledTimes(1)
+    const doc = engine.getDoc()
+    expect(doc.nodes).toHaveLength(2)
+    expect(doc.nodes[1]).toMatchObject({ id: "a", width: 100 })
+  })
+
+  it("applyNodePatch 后 getDoc 反映新值、写入 history 且只触发一次 onDocChange", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a", width: 100 })))
+    const cb = vi.fn()
+    engine.onDocChange(cb)
+
+    engine.applyNodePatch("a", { width: 300 })
+
+    expect(engine.history.canUndo).toBe(true)
+    expect(cb).toHaveBeenCalledTimes(1)
+    expect(engine.getDoc().nodes[1]).toMatchObject({ id: "a", width: 300 })
+  })
+
+  it("loadDoc 重置 history", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+    engine.applyNodesAppend([shapeNode({ id: "b" })])
+    expect(engine.history.canUndo).toBe(true)
+
+    engine.loadDoc(docWith(shapeNode({ id: "c" })))
+
+    expect(engine.history.canUndo).toBe(false)
+    expect(engine.history.canRedo).toBe(false)
+  })
+
+  it("applyNodesAppend 追加后只触发一次 onDocChange", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+    const cb = vi.fn()
+    engine.onDocChange(cb)
+
+    engine.applyNodesAppend([shapeNode({ id: "b" }), shapeNode({ id: "c" })])
+
+    expect(cb).toHaveBeenCalledTimes(1)
+    const doc = engine.getDoc()
+    expect(doc.nodes.map((node) => node.id)).toEqual([BOARD_NODE_ID, "a", "b", "c"])
+  })
+
+  it("删除选中节点后 editor.list 清空，不残留已 detach 的悬挂选中项", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+    const editor = mod.apps[0].editor!
+    engine.select(["a"])
+    expect(editor.list.map((leaf) => (leaf as MockLeaf).id)).toEqual(["a"])
+
+    engine.deleteSelectedNodes()
+
+    expect(engine.getSelection()).toEqual([])
+    expect(editor.list).toEqual([])
+  })
+
+  it("追加节点保留原有选中，不残留重建前已 detach 的悬挂选中项", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+    const editor = mod.apps[0].editor!
+    engine.select(["a"])
+
+    engine.applyNodesAppend([shapeNode({ id: "b" })])
+
+    expect(engine.getSelection()).toEqual(["a"])
+    expect(editor.list.map((leaf) => (leaf as MockLeaf).id)).toEqual(["a"])
+    expect(liveLeaves()).toContain(editor.list[0])
+  })
+
+  it("undo 与 redo 对称恢复文档", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+
+    engine.applyNodesAppend([shapeNode({ id: "b" })])
+    expect(engine.getDoc().nodes).toHaveLength(3)
+
+    engine.undo()
+    expect(engine.getDoc().nodes.map((node) => node.id)).toEqual([BOARD_NODE_ID, "a"])
+
+    engine.redo()
+    expect(engine.getDoc().nodes.map((node) => node.id)).toEqual([BOARD_NODE_ID, "a", "b"])
+  })
+
+  it("selection 事件转发给 onSelectionChange", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+    const cb = vi.fn()
+    engine.onSelectionChange(cb)
+
+    const editor = mod.apps[0].editor!
+    editor.select({ id: "a", children: [] } as MockLeaf)
+    mod.fire(editor, "editor.select")
+
+    expect(cb).toHaveBeenCalledTimes(1)
+    expect(cb).toHaveBeenLastCalledWith(["a"])
+  })
+
+  it("剪贴板：复制/粘贴重映射 id 保持父子关系，剪切删除原节点", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const frame: SceneNode = {
+      id: "a_1",
+      kind: "group",
+      type: "frame",
+      parentId: BOARD_NODE_ID,
+      name: "画板 1",
+      x: 0,
+      y: 0,
+      width: 300,
+      height: 400,
+    }
+    const rect: SceneNode = shapeNode({ id: "n_1", parentId: "a_1", x: 10, y: 10 })
+    engine.loadDoc({
+      version: 1,
+      meta: {},
+      nodes: [createBoardNode("desktop"), frame, rect],
+    })
+
+    // 全选：非 board 节点全部选中
+    engine.selectAll()
+    const editor = mod.apps[0].editor!
+    expect(editor.list.map((leaf) => (leaf as { id?: string }).id).sort()).toEqual(["a_1", "n_1"])
+
+    // 复制 + 粘贴：id 重映射、顶层偏移、父子关系保持
+    // （getDoc 走 mock leaferToDoc 读回不可靠，用 onDocChange 拿引擎真实 currentDoc）
+    let latestDoc: SceneDocument | null = null
+    engine.onDocChange((doc) => {
+      latestDoc = doc
+    })
+    engine.copySelection()
+    engine.pasteClipboard()
+    expect(latestDoc).not.toBeNull()
+    const pastedFrame = latestDoc!.nodes.find((node) => node.id === "a_2")
+    const pastedRect = latestDoc!.nodes.find((node) => node.id === "n_2")
+    expect(pastedFrame).toMatchObject({ type: "frame", x: 20, y: 20 })
+    expect(pastedRect).toMatchObject({ parentId: "a_2", x: 30, y: 30 })
+    // 选中粘贴后的顶层节点
+    expect(
+      editor.list.map((leaf) => (leaf as { id?: string }).id),
+    ).toEqual(["a_2"])
+
+    // 剪切：复制并删除选中
+    engine.cutSelection()
+    const afterCut = latestDoc!.nodes
+    expect(afterCut.some((node) => node.id === "a_2")).toBe(false)
+  })
+
+  it("剪贴板：多选粘贴不丢节点（同前缀 id 均映射到不同新 id）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const r1 = shapeNode({ id: "n_1", x: 0, y: 0 })
+    const r2 = shapeNode({ id: "n_2", x: 100, y: 100 })
+    engine.loadDoc({
+      version: 1,
+      meta: {},
+      nodes: [createBoardNode("desktop"), r1, r2],
+    })
+    let latestDoc: SceneDocument | null = null
+    engine.onDocChange((doc) => {
+      latestDoc = doc
+    })
+    engine.select(["n_1", "n_2"])
+    engine.copySelection()
+    engine.pasteClipboard()
+    const ids = latestDoc!.nodes.map((node) => node.id)
+    // 原有 n_1/n_2 + 粘贴的 n_3/n_4，不能出现重复 id
+    expect(ids.filter((id) => id === "n_3")).toHaveLength(1)
+    expect(ids.filter((id) => id === "n_4")).toHaveLength(1)
+    expect(new Set(ids).size).toBe(ids.length)
+    const n3 = latestDoc!.nodes.find((node) => node.id === "n_3")
+    const n4 = latestDoc!.nodes.find((node) => node.id === "n_4")
+    expect(n3).toMatchObject({ x: 20, y: 20 })
+    expect(n4).toMatchObject({ x: 120, y: 120 })
+  })
+
+  it("pickFrameLabel 在 sky 空间按标签包围盒命中，未命中返回 null", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const frame: SceneNode = {
+      id: "f1",
+      kind: "group",
+      type: "frame",
+      parentId: BOARD_NODE_ID,
+      name: "画板 1",
+      x: 0,
+      y: 0,
+      width: 300,
+      height: 400,
+    }
+    engine.loadDoc({
+      version: 1,
+      meta: {},
+      nodes: [createBoardNode("desktop"), frame],
+    })
+
+    // client → sky mock：identity，client 坐标即 sky 内部坐标
+    const app = mod.apps[0]
+    const sky = app.sky as unknown as {
+      getWorldPointByClient: ReturnType<typeof vi.fn>
+    }
+    sky.getWorldPointByClient = vi.fn((p: { clientX: number; clientY: number }) => ({
+      x: p.clientX,
+      y: p.clientY,
+    }))
+
+    // 标签挂 sky 装饰层，不挂 tree（不参与序列化）
+    const skyLabels = app.sky.children.filter((child) =>
+      String((child as { id?: string }).id).startsWith("frame_label:"),
+    )
+    expect(skyLabels).toHaveLength(1)
+    expect(
+      app.tree.children.some((child) =>
+        String((child as { id?: string }).id).startsWith("frame_label:"),
+      ),
+    ).toBe(false)
+
+    // 标签 bounds (0,-28,80,18)，pad 4（sky 不缩放，恒屏幕像素）：
+    // sky(20,-20) 在范围内 → 命中
+    expect(engine.pickFrameLabel(20, -20)).toBe("f1")
+    // 画板内部 (20,300) 超出标签区域 → 未命中
+    expect(engine.pickFrameLabel(20, 300)).toBeNull()
+  })
+
+  it("pickFrameLabel 命中含 4px 屏幕容差（字间空隙可点）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const frame: SceneNode = {
+      id: "f2",
+      kind: "group",
+      type: "frame",
+      parentId: BOARD_NODE_ID,
+      name: "画板 2",
+      x: 0,
+      y: 0,
+      width: 300,
+      height: 400,
+    }
+    engine.loadDoc({
+      version: 1,
+      meta: {},
+      nodes: [createBoardNode("desktop"), frame],
+    })
+
+    // 标签 box (0,-28,80,18)，容差 4：sky(82,-20) 在 x+4 内
+    expect(engine.pickFrameLabel(82, -20)).toBe("f2")
+    // 超出容差 miss
+    expect(engine.pickFrameLabel(90, -20)).toBeNull()
+  })
+
+  it("视口变化（zoomLayer CHANGE）时 sky 标签跟随画板投影", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const frame: SceneNode = {
+      id: "f3",
+      kind: "group",
+      type: "frame",
+      parentId: BOARD_NODE_ID,
+      name: "画板 3",
+      x: 100,
+      y: 100,
+      width: 300,
+      height: 400,
+    }
+    engine.loadDoc({
+      version: 1,
+      meta: {},
+      nodes: [createBoardNode("desktop"), frame],
+    })
+    const app = mod.apps[0]
+    const sky = app.sky as unknown as {
+      getWorldPointByClient: ReturnType<typeof vi.fn>
+    }
+    // world → client：平移 (541, 53)；client → sky：identity
+    const tree = app.tree as unknown as {
+      getClientPointByWorld: ReturnType<typeof vi.fn>
+    }
+    tree.getClientPointByWorld = vi.fn((world: { x: number; y: number }) => ({
+      x: world.x + 541,
+      y: world.y + 53,
+    }))
+    sky.getWorldPointByClient = vi.fn((p: { clientX: number; clientY: number }) => ({
+      x: p.clientX,
+      y: p.clientY,
+    }))
+
+    // 模拟视口缩放（官方 zoom/panBy 均写 zoomLayer 属性 → CHANGE）
+    const zoomSub = app.zoomLayer.subs.find((sub) => sub.type === "property.change")
+    expect(zoomSub).toBeDefined()
+    zoomSub!.cb()
+
+    const label = app.sky.children.find((child) =>
+      String((child as { id?: string }).id).startsWith("frame_label:"),
+    ) as { x?: number; y?: number }
+    // 画板 world 左上 (100,100) → client (641,153) → sky；y 再上移 OFFSET_Y(28)
+    expect(label.x).toBe(641)
+    expect(label.y).toBe(125)
+  })
+
+  it("拖名称标签（sky 空间）反推画板 board inner 坐标", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const frame: SceneNode = {
+      id: "f4",
+      kind: "group",
+      type: "frame",
+      parentId: BOARD_NODE_ID,
+      name: "画板 4",
+      x: 100,
+      y: 100,
+      width: 300,
+      height: 400,
+    }
+    engine.loadDoc({
+      version: 1,
+      meta: {},
+      nodes: [createBoardNode("desktop"), frame],
+    })
+    const app = mod.apps[0]
+    const sky = app.sky as unknown as {
+      getClientPointByWorld: ReturnType<typeof vi.fn>
+    }
+    const tree = app.tree as unknown as {
+      getWorldPointByClient: ReturnType<typeof vi.fn>
+      getClientPointByWorld: ReturnType<typeof vi.fn>
+    }
+    sky.getClientPointByWorld = vi.fn((p: { x: number; y: number }) => ({ x: p.x, y: p.y }))
+    tree.getWorldPointByClient = vi.fn((p: { clientX: number; clientY: number }) => ({
+      x: p.clientX,
+      y: p.clientY,
+    }))
+    // board 的 world→inner 换算（app.ts 反推调用 board.getInnerPoint）：/2 模拟缩放
+    const board = app.tree.children.find(
+      (child) => (child as { id?: string }).id === BOARD_NODE_ID,
+    ) as unknown as { getInnerPoint: ReturnType<typeof vi.fn> }
+    board.getInnerPoint = vi.fn((world: { x: number; y: number }) => ({
+      x: world.x / 2,
+      y: world.y / 2,
+    }))
+
+    // 标签 DRAG（位移驱动）：drag.start 锚定画板左上（getBounds world (100,100)
+    // → getClientPointByWorld 恒等 mock → startClient (100,100)），
+    // drag(totalX=100, totalY=50) → world (200,150) → board inner (100,75)
+    const label = app.sky.children.find((child) =>
+      String((child as { id?: string }).id).startsWith("frame_label:"),
+    ) as unknown as { x: number; y: number; subs: MockSub[] }
+    tree.getClientPointByWorld = vi.fn((p: { x: number; y: number }) => ({
+      x: p.x,
+      y: p.y,
+    }))
+    const startSub = label.subs.find((sub) => sub.type === "drag.start")
+    expect(startSub).toBeDefined()
+    startSub!.cb()
+    const dragSub = label.subs.find((sub) => sub.type === "drag.drag")
+    expect(dragSub).toBeDefined()
+    dragSub!.cb({ totalX: 100, totalY: 50 })
+
+    const frameLeaf = app.tree.children
+      .find((child) => (child as { id?: string }).id === BOARD_NODE_ID)
+      ?.children?.find((child) => (child as { id?: string }).id === "f4") as {
+      x?: number
+      y?: number
+    }
+    expect(frameLeaf?.x).toBe(100)
+    expect(frameLeaf?.y).toBe(75)
+  })
+
+  it("toCanvas 经 tree 逆变换换算（含 zoomLayer 平移与缩放）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const tree = mod.apps[0].tree as unknown as {
+      getWorldPointByClient: ReturnType<typeof vi.fn>
+      getInnerPoint: ReturnType<typeof vi.fn>
+    }
+    tree.getWorldPointByClient = vi.fn(() => ({ x: 359, y: 297 }))
+    tree.getInnerPoint = vi.fn((world: { x: number; y: number }) => ({
+      x: (world.x + 201) / 1.11,
+      y: (world.y - 30) / 1.11,
+    }))
+
+    const point = engine.toCanvas(900, 350)
+
+    expect(tree.getWorldPointByClient).toHaveBeenCalledWith({ clientX: 900, clientY: 350 }, true)
+    expect(tree.getInnerPoint).toHaveBeenCalledWith({ x: 359, y: 297 })
+    expect(point).toEqual({ x: Math.round(560 / 1.11), y: Math.round(267 / 1.11) })
+  })
+
+  it("fromCanvas 经 tree 正向变换换算（本地坐标 → client 坐标）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const tree = mod.apps[0].tree as unknown as {
+      getWorldPoint: ReturnType<typeof vi.fn>
+      getClientPointByWorld: ReturnType<typeof vi.fn>
+    }
+    tree.getWorldPoint = vi.fn((inner: { x: number; y: number }) => ({
+      x: inner.x * 1.11 - 201,
+      y: inner.y * 1.11 + 30,
+    }))
+    tree.getClientPointByWorld = vi.fn((world: { x: number; y: number }) => ({
+      x: world.x + 541,
+      y: world.y + 53,
+    }))
+
+    const client = engine.fromCanvas(504, 241)
+
+    expect(tree.getWorldPoint).toHaveBeenCalledWith({ x: 504, y: 241 })
+    expect(tree.getClientPointByWorld).toHaveBeenCalled()
+    expect(client).toEqual({
+      x: Math.round(504 * 1.11 - 201 + 541),
+      y: Math.round(241 * 1.11 + 30 + 53),
+    })
+  })
+
+  it("updateNodeGeometry 触发 onDocChange（拖拽结束后几何同步到 React doc）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a", width: 1, height: 1 })))
+    const cb = vi.fn()
+    engine.onDocChange(cb)
+
+    engine.updateNodeGeometry("a", { x: 100, y: 200, width: 150, height: 120 })
+
+    expect(cb).toHaveBeenCalledTimes(1)
+    const pushed = cb.mock.calls[0][0] as SceneDocument
+    const node = pushed.nodes.find((candidate) => candidate.id === "a")
+    expect(node).toMatchObject({ id: "a", x: 100, y: 200, width: 150, height: 120 })
+  })
+
+  it("zoomTo 转发到 app.zoom", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+
+    engine.zoomTo(2.5)
+
+    expect(mod.apps[0].zoom).toHaveBeenCalledWith(2.5)
+  })
+
+  it("panBy 转发官方 zoomLayer.move（相对位移语义，多次调用累加）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+
+    // 初始：x/y 未定义（leafer 未初始化平移）
+    expect(mod.apps[0].zoomLayer.x).toBeUndefined()
+    expect(mod.apps[0].zoomLayer.y).toBeUndefined()
+
+    engine.panBy(30, 40)
+    expect(mod.apps[0].zoomLayer.x).toBe(30)
+    expect(mod.apps[0].zoomLayer.y).toBe(40)
+
+    // 多次累加：第二次相对上次 x/y（官方 move 为增量语义）
+    engine.panBy(10, 20)
+    expect(mod.apps[0].zoomLayer.x).toBe(40)
+    expect(mod.apps[0].zoomLayer.y).toBe(60)
+
+    // 负向增量反向平移
+    engine.panBy(-10, -20)
+    expect(mod.apps[0].zoomLayer.x).toBe(30)
+    expect(mod.apps[0].zoomLayer.y).toBe(40)
+
+    // panBy 不影响 scaleX（zoom 与平移独立属性）
+    expect(mod.apps[0].zoomLayer.scaleX).toBe(1)
+  })
+
+  it("fit/zoomToFrame/focusNode 转发官方 zoom(ILeaf|ILeaf[]) 语义", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const frame: SceneNode = {
+      id: "f3",
+      kind: "group",
+      type: "frame",
+      parentId: BOARD_NODE_ID,
+      name: "画板 3",
+      x: 100,
+      y: 100,
+      width: 300,
+      height: 400,
+    }
+    engine.loadDoc({ version: 1, meta: {}, nodes: [createBoardNode("desktop"), frame] })
+    const app = mod.apps[0]
+    app.zoom.mockClear()
+
+    // fit：有 frame 时 zoom(frames[], 30)
+    engine.fit()
+    expect(app.zoom).toHaveBeenCalledTimes(1)
+    const fitArg = app.zoom.mock.calls[0][0] as { id?: string }[]
+    expect(Array.isArray(fitArg)).toBe(true)
+    expect(fitArg.map((leaf) => leaf.id)).toEqual(["f3"])
+    expect(app.zoom.mock.calls[0][1]).toBe(30)
+
+    // zoomToFrame：删 1x1 极小 bounds hack，官方 zoom(leaf) fit 画板
+    engine.zoomToFrame("f3")
+    expect(app.zoom).toHaveBeenCalledTimes(2)
+    expect(app.zoom.mock.calls[1][0]).toMatchObject({ id: "f3" })
+    expect(app.zoom.mock.calls[1][1]).toBe(30)
+
+    // focusNode：官方 zoom(leaf)
+    engine.focusNode("f3")
+    expect(app.zoom).toHaveBeenCalledTimes(3)
+    expect(app.zoom.mock.calls[2][0]).toMatchObject({ id: "f3" })
+
+    // findLeaf 官方 findOne 兜底：缓存 miss 时按 '#id' 查找仍能命中
+    expect(engine.getLeaf("f3")).toMatchObject({ id: "f3" })
+  })
+
+  it("onDocChange 的取消函数停止监听", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const cb = vi.fn()
+    const off = engine.onDocChange(cb)
+
+    off()
+    engine.applyNodesAppend([shapeNode({ id: "a" })])
+
+    expect(cb).not.toHaveBeenCalled()
+  })
+
+  it("dispose 后所有方法抛错", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+
+    engine.dispose()
+
+    expect(() => engine.getDoc()).toThrow()
+    expect(() => engine.applyNodesAppend([shapeNode({ id: "a" })])).toThrow()
+    expect(() => engine.select(["a"])).toThrow()
+    expect(() => engine.setTool("rect")).toThrow()
+    expect(() => engine.mount(el)).toThrow()
+    expect(() => engine.dispose()).toThrow()
+    expect(mod.apps[0].destroy).toHaveBeenCalledTimes(1)
+  })
+
+  it("未 mount 时调用抛错", () => {
+    const engine = new LeaferEngine(mod as never)
+
+    expect(() => engine.getDoc()).toThrow()
+    expect(() => engine.applyNodesAppend([shapeNode({ id: "a" })])).toThrow()
+    expect(() => engine.select(["a"])).toThrow()
+    expect(() => engine.setTool("rect")).toThrow()
+    expect(() => engine.loadDoc(createEmptyDoc())).toThrow()
+  })
+
+  it("readOnly 模式不创建 editor", () => {
+    const engine = new LeaferEngine(mod as never, { readOnly: true })
+    engine.mount(el)
+
+    expect(mod.apps[0].editor).toBeUndefined()
+    expect(engine.getSelection()).toEqual([])
+    expect(() => engine.select(["a"])).not.toThrow()
+  })
+})
+
+describe("约束与多选事务", () => {
+  it("applyNodePatch 改 group 尺寸时对子节点应用约束，undo 后几何层由 diff 覆盖", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc({
+      version: 1,
+      meta: { device: "desktop" },
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 800, height: 600 },
+        { id: "g", kind: "group", type: "group", parentId: "board", x: 0, y: 0, width: 100, height: 100 },
+        {
+          id: "c",
+          kind: "shape",
+          type: "rect",
+          parentId: "g",
+          x: 10,
+          y: 10,
+          width: 30,
+          height: 30,
+          constraints: { horizontal: "scale", vertical: "scale" },
+        },
+      ],
+    })
+    const snapshots: SceneDocument[] = []
+    engine.onDocChange((doc) => snapshots.push(doc))
+    engine.applyNodePatch("g", { width: 200, height: 100 })
+    const patched = snapshots.at(-1)!
+    expect(patched.nodes.find((n) => n.id === "g")?.width).toBe(200)
+    expect(patched.nodes.find((n) => n.id === "c")).toMatchObject({ x: 20, width: 60 })
+
+    engine.undo()
+    const undone = snapshots.at(-1)!
+    expect(engine.getDoc().nodes.map((n) => n.id)).toEqual(["board", "g", "c"])
+    expect(undone.nodes.find((n) => n.id === "c")).toMatchObject({ x: 10, width: 30, y: 10, height: 30 })
+  })
+
+  it("applyMultiNodePatch 单条 history 批量修改，undo 一步全恢复", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc({
+      version: 1,
+      meta: { device: "desktop" },
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 800, height: 600 },
+        { id: "a", kind: "shape", type: "rect", parentId: "board", x: 0, y: 0, width: 10, height: 10 },
+        { id: "b", kind: "shape", type: "rect", parentId: "board", x: 50, y: 50, width: 10, height: 10 },
+      ],
+    })
+    const snapshots: SceneDocument[] = []
+    engine.onDocChange((doc) => snapshots.push(doc))
+    engine.applyMultiNodePatch(["a", "b"], () => ({ y: 100 }))
+    const patched = snapshots.at(-1)!
+    expect(patched.nodes.find((n) => n.id === "a")?.y).toBe(100)
+    expect(patched.nodes.find((n) => n.id === "b")?.y).toBe(100)
+    expect(engine.history.canUndo).toBe(true)
+
+    engine.undo()
+    const undone = snapshots.at(-1)!
+    expect(undone.nodes.find((n) => n.id === "a")?.y).toBe(0)
+    expect(undone.nodes.find((n) => n.id === "b")?.y).toBe(50)
+  })
+
+  it("applyMultiNodePatch 收到全空 patch 不落 history（均分端点回传空 patch）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc({
+      version: 1,
+      meta: { device: "desktop" },
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 800, height: 600 },
+        { id: "a", kind: "shape", type: "rect", parentId: "board", x: 0, y: 0, width: 10, height: 10 },
+        { id: "b", kind: "shape", type: "rect", parentId: "board", x: 50, y: 0, width: 10, height: 10 },
+        { id: "c", kind: "shape", type: "rect", parentId: "board", x: 100, y: 0, width: 10, height: 10 },
+      ],
+    })
+    engine.applyMultiNodePatch(["a", "b", "c"], () => ({}))
+    expect(engine.history.canUndo).toBe(false)
+  })
+
+  it("applyConstraintsDiff 在 group resize 传播路径上按 5 模式覆盖 applyNodePatch 输出", () => {
+    const prevDoc: SceneDocument = {
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 800, height: 600 },
+        { id: "g", kind: "group", type: "group", parentId: "board", x: 0, y: 0, width: 100, height: 100 },
+        {
+          id: "c",
+          kind: "shape",
+          type: "rect",
+          parentId: "g",
+          x: 10,
+          y: 10,
+          width: 30,
+          height: 30,
+          constraints: { horizontal: "scale", vertical: "scale" },
+        },
+      ],
+    }
+    const nextDoc: SceneDocument = {
+      ...prevDoc,
+      nodes: prevDoc.nodes.map((n) => (n.id === "g" ? { ...n, width: 200, height: 100 } : n)),
+    }
+    const patched = applyConstraintsDiff(prevDoc, nextDoc)
+    expect(patched.find((n) => n.id === "g")).toMatchObject({ width: 200, height: 100 })
+    expect(patched.find((n) => n.id === "c")).toMatchObject({ x: 20, width: 60 })
+  })
+})
+
+describe("R1 增量更新（消除全量重建）", () => {
+  it("applyNodePatch 走增量：不重建树，board 引用不变，patch 写入 leaf", async () => {
+    const { docToScene } = await import("../../document/serialize")
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" }), shapeNode({ id: "b" })))
+    vi.mocked(docToScene).mockClear()
+
+    const tree = mod.apps[0].tree as unknown as { children: MockLeaf[] }
+    const boardBefore = tree.children.find((c) => (c as { id?: string }).id === BOARD_NODE_ID)
+    const leafA = boardBefore?.children.find((c) => (c as { id?: string }).id === "a") as unknown as { x: number; y: number }
+
+    engine.applyNodePatch("a", { x: 555, y: 666 })
+
+    // 全量建树不再被调用（增量路径生效）
+    expect(docToScene).not.toHaveBeenCalled()
+    // board 引用不变（无清空重挂）
+    expect(tree.children.find((c) => (c as { id?: string }).id === BOARD_NODE_ID)).toBe(boardBefore)
+    // patch 落到 leaf
+    expect(leafA.x).toBe(555)
+    expect(leafA.y).toBe(666)
+    // 另一节点 leaf 引用不变
+    const leafB = boardBefore?.children.find((c) => (c as { id?: string }).id === "b")
+    expect(leafB).toBeDefined()
+  })
+
+  it("applyNodesAppend 走局部 add：既有 leaf 引用不变", async () => {
+    const { docToScene } = await import("../../document/serialize")
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+    vi.mocked(docToScene).mockClear()
+    const tree = mod.apps[0].tree as unknown as { children: MockLeaf[] }
+    const boardBefore = tree.children.find((c) => (c as { id?: string }).id === BOARD_NODE_ID)
+    const leafA = boardBefore?.children.find((c) => (c as { id?: string }).id === "a")
+
+    engine.applyNodesAppend([shapeNode({ id: "new1", x: 1, y: 2 })])
+
+    expect(docToScene).not.toHaveBeenCalled()
+    expect(tree.children.find((c) => (c as { id?: string }).id === BOARD_NODE_ID)).toBe(boardBefore)
+    expect(leafA).toBeDefined()
+    expect(boardBefore?.children.some((c) => (c as { id?: string }).id === "new1")).toBe(true)
+  })
+
+  it("deleteSelectedNodes 走局部 remove：board 引用不变", async () => {
+    const { docToScene } = await import("../../document/serialize")
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" }), shapeNode({ id: "b" })))
+    engine.select(["a"])
+    vi.mocked(docToScene).mockClear()
+    const tree = mod.apps[0].tree as unknown as { children: MockLeaf[] }
+    const boardBefore = tree.children.find((c) => (c as { id?: string }).id === BOARD_NODE_ID)
+
+    engine.deleteSelectedNodes()
+
+    expect(docToScene).not.toHaveBeenCalled()
+    expect(tree.children.find((c) => (c as { id?: string }).id === BOARD_NODE_ID)).toBe(boardBefore)
+    expect(boardBefore?.children.some((c) => (c as { id?: string }).id === "a")).toBe(false)
+    expect(boardBefore?.children.some((c) => (c as { id?: string }).id === "b")).toBe(true)
+  })
+
+  it("undo/redo 保持全量重建语义", async () => {
+    const { docToScene } = await import("../../document/serialize")
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(shapeNode({ id: "a" })))
+    engine.applyNodePatch("a", { x: 100 })
+    vi.mocked(docToScene).mockClear()
+
+    engine.undo()
+
+    // undo 走全量重建（历史快照语义），docToScene 再次被调用
+    expect(docToScene).toHaveBeenCalled()
+  })
+})
+
+// ===== shader 接线（R19 发现 2：fake runtime 经 useShaderRuntime 注入，覆盖接线顺序）=====
+// jsdom 无法静态加载真实 shader-bridge（leafer-editor 导入即崩），运行时实例由
+// create() 异步装配；测试经注入点覆盖「applyScene 后 sync、attach 后 leaf 重设、
+// readOnly staticFrame、dispose 清理」的接线顺序。
+
+import type { ShaderPaint } from "@/components/design/canvas/document/style/paints"
+
+function makeShaderNode(overrides: Partial<SceneNode> = {}): SceneNode {
+  return {
+    id: "n_shader",
+    kind: "shape",
+    type: "rect",
+    parentId: BOARD_NODE_ID,
+    x: 10,
+    y: 20,
+    width: 100,
+    height: 50,
+    fills: [
+      {
+        id: "p1",
+        type: "shader",
+        shaderId: "mesh-gradient",
+        props: { colors: ["#ff0000"] },
+        speed: 1,
+        opacity: 1,
+        visible: true,
+      } as ShaderPaint,
+    ],
+    ...overrides,
+  }
+}
+
+function makeFakeShaderRuntime() {
+  return {
+    attach: vi.fn(),
+    updatePaint: vi.fn(),
+    resize: vi.fn(),
+    detach: vi.fn(),
+    detachAll: vi.fn(),
+    setPaused: vi.fn(),
+    renderStaticFrame: vi.fn(),
+    animatingNodeIds: vi.fn((): string[] => []),
+    activeCount: 0,
+  }
+}
+
+describe("shader 接线（fake runtime 注入）", () => {
+  it("applyScene（增量）后同步 runtime：新增 attach、删除 detach", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const fake = makeFakeShaderRuntime()
+    engine.useShaderRuntime(fake as never)
+
+    engine.applyNodesAppend([makeShaderNode()])
+    expect(fake.attach).toHaveBeenCalledTimes(1)
+    expect(fake.attach).toHaveBeenCalledWith(
+      "n_shader",
+      "p1",
+      expect.objectContaining({ type: "shader", shaderId: "mesh-gradient" }),
+      100,
+      50,
+    )
+
+    engine.select(["n_shader"])
+    engine.deleteSelectedNodes()
+    expect(fake.detach).toHaveBeenCalledWith("n_shader", "p1")
+    engine.dispose()
+  })
+
+  it("attach 后对新挂载 leaf 重设投影（leafConfigOf 产出 → leaf.set）", async () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.useShaderRuntime(makeFakeShaderRuntime() as never)
+
+    engine.applyNodesAppend([makeShaderNode()])
+
+    // 重设走 leafConfigOf（buildSceneElement mock 不经它，增量路径唯一调用点
+    // = attach 后的投影重设）
+    const { leafConfigOf } = await import("../../document/serialize")
+    expect(leafConfigOf).toHaveBeenCalledWith(expect.objectContaining({ id: "n_shader" }))
+    // leaf 收到合并 config（mock set = Object.assign）：locked 键来自 leafConfigOf 产出
+    const leaf = liveLeaves().find((l) => l.id === "n_shader") as (MockLeaf & { locked?: boolean }) | undefined
+    expect(leaf?.locked).toBe(false)
+    engine.dispose()
+  })
+
+  it("readOnly 引擎：sync 以 staticFrame 语义调用（attach 收到 speed 0 的 paint）", () => {
+    const engine = new LeaferEngine(mod as never, { readOnly: true })
+    engine.mount(el)
+    const fake = makeFakeShaderRuntime()
+    engine.useShaderRuntime(fake as never)
+
+    engine.applyNodesAppend([makeShaderNode()])
+    expect(fake.attach).toHaveBeenCalledWith(
+      "n_shader",
+      "p1",
+      expect.objectContaining({ type: "shader", speed: 0 }),
+      100,
+      50,
+    )
+    engine.dispose()
+  })
+
+  it("dispose 清理：runtime.detachAll 被调", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    const fake = makeFakeShaderRuntime()
+    engine.useShaderRuntime(fake as never)
+    engine.dispose()
+    expect(fake.detachAll).toHaveBeenCalled()
+  })
+})