@allbluecn/web-app 0.17.2 → 0.18.1

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

@@ -0,0 +1,1181 @@
+// 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/>.
+
+/**
+ * FS-5.3 菜单命令族引擎测试（mock leafer 无头环境，doc 级断言）：
+ * duplicateSelection / pasteClipboardAt / pasteIntoFrame / setNodesLocked /
+ * setNodesVisible + FS-4.3 reparent group 落点。
+ */
+import { describe, expect, it, vi, beforeEach } from "vitest"
+import type { SceneDocument, SceneNode } from "@/components/design/canvas/document/types"
+import { BOARD_NODE_ID, createBoardNode } from "@/components/design/canvas/document/types"
+
+type MockLeaf = {
+  id: string
+  parent?: MockLeaf
+  x?: number
+  y?: number
+  children: MockLeaf[]
+  width?: number
+  height?: number
+  editable?: boolean
+  locked?: boolean
+  visible?: boolean
+  name?: string
+  tag?: string
+  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: MockLeaf, index: number) => void
+  remove?: () => void
+  dropTo?: (parent: MockLeaf, index?: number) => void
+}
+
+vi.mock("../../document/serialize", () => {
+  function docToScene(doc: SceneDocument) {
+    const boardMeta = doc.nodes.find((node) => node.id === BOARD_NODE_ID)
+    const boardWidth = boardMeta?.width ?? 0
+    const boardHeight = boardMeta?.height ?? 0
+    const board: MockLeaf = {
+      id: BOARD_NODE_ID,
+      children: [],
+      width: boardWidth,
+      height: boardHeight,
+      editable: false,
+      getBounds: () => ({ x: 0, y: 0, width: boardWidth, height: boardHeight }),
+      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]])
+    const frameLabels = new Map<string, unknown>()
+    const makeLeaf = (node: SceneNode, parent: MockLeaf): MockLeaf => {
+      const leaf: MockLeaf = {
+        parent,
+        id: node.id,
+        x: node.x ?? 0,
+        y: node.y ?? 0,
+        children: [],
+        width: node.width ?? 100,
+        height: node.height ?? 100,
+        editable: node.type !== "frame",
+        // world/inner 互转含自身平移（真实 leaf 语义），reparent 坐标换算测试依赖
+        getBounds: () => ({
+          x: leaf.x ?? 0,
+          y: leaf.y ?? 0,
+          width: leaf.width ?? 100,
+          height: leaf.height ?? 100,
+        }),
+        getWorldPoint: (inner: { x: number; y: number }) => ({
+          x: inner.x + (leaf.x ?? 0),
+          y: inner.y + (leaf.y ?? 0),
+        }),
+        getInnerPoint: (world: { x: number; y: number }) => ({
+          x: world.x - (leaf.x ?? 0),
+          y: world.y - (leaf.y ?? 0),
+        }),
+        set: (config: Record<string, unknown>) => Object.assign(leaf, config),
+        addAt: (child: MockLeaf, 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: () => {
+          const p = leaf.parent
+          if (!p) return
+          const i = p.children.indexOf(leaf)
+          if (i >= 0) p.children.splice(i, 1)
+        },
+        // 官方 dropTo：re-parent + 世界坐标守恒（mock 内 world=board inner，守恒
+        // 即父空间坐标平移差值）
+        dropTo: (target: MockLeaf) => {
+          const world = { x: (leaf.x ?? 0) + (leaf.parent?.x ?? 0), y: (leaf.y ?? 0) + (leaf.parent?.y ?? 0) }
+          const oldParent = leaf.parent
+          if (oldParent) {
+            const i = oldParent.children.indexOf(leaf)
+            if (i >= 0) oldParent.children.splice(i, 1)
+          }
+          leaf.parent = target
+          target.children.push(leaf)
+          leaf.x = world.x - (target.x ?? 0)
+          leaf.y = world.y - (target.y ?? 0)
+        },
+      }
+      nodeIndex.set(node.id, leaf)
+      parent.children.push(leaf)
+      for (const child of doc.nodes ?? []) {
+        if (child.parentId !== node.id) continue
+        makeLeaf(child, leaf)
+      }
+      return leaf
+    }
+    for (const node of doc.nodes ?? []) {
+      if (node.id === BOARD_NODE_ID) continue
+      // mock 平面化守卫：仅挂顶层（parentId 空/board），子节点经 makeLeaf 递归
+      if (node.parentId && node.parentId !== BOARD_NODE_ID) continue
+      if (node.type === "frame" && typeof node.name === "string" && node.name) {
+        const x = node.x ?? 0
+        const y = (node.y ?? 0) - 28
+        frameLabels.set(node.id, {
+          id: `frame_label:${node.id}`,
+          x,
+          y,
+          // 标签插件 bindDrag 的 DRAG/END 监听订阅（与 engine.test.ts mock 同款）
+          subs: [] as { type: string; cb: (e?: unknown) => void }[],
+          on(type: string, cb: (e?: unknown) => void) {
+            ;(this as unknown as { subs: { type: string; cb: (e?: unknown) => void }[] }).subs.push({ type, cb })
+          },
+          getBounds: () => ({ x, y, width: 80, height: 18 }),
+        })
+      }
+      makeLeaf(node, board)
+    }
+    return { leafer: board, nodeIndex, frameLabels }
+  }
+
+  // 嵌套感知读回：按 leaf 树递归还原 parentId（reparent 断言依赖）
+  function leaferToDoc(
+    tree: { children?: MockLeaf[]; width?: number; height?: number },
+    opts?: { device?: "desktop" | "tablet" | "mobile" },
+  ): SceneDocument {
+    const treeChildren = Array.isArray(tree.children) ? tree.children : []
+    const boardChild = treeChildren.find((child) => child.id === BOARD_NODE_ID)
+    const boardWidth = boardChild?.width ?? tree.width ?? 1200
+    const boardHeight = boardChild?.height ?? tree.height ?? 812
+    const nodes: SceneNode[] = [
+      {
+        id: BOARD_NODE_ID,
+        kind: "group",
+        type: "board",
+        parentId: null,
+        name: "Board",
+        x: 0,
+        y: 0,
+        width: boardWidth,
+        height: boardHeight,
+        style: { fill: "#ffffff" },
+        locked: true,
+      },
+    ]
+    const walk = (leaf: MockLeaf, parentId: string): void => {
+      for (const child of leaf.children ?? []) {
+        nodes.push({
+          id: child.id,
+          kind: child.tag === "Frame" ? "group" : "shape",
+          type: child.tag === "Frame" ? "frame" : "rect",
+          parentId,
+          name: child.name,
+          x: child.x ?? 0,
+          y: child.y ?? 0,
+          width: child.width ?? 100,
+          height: child.height ?? 100,
+        })
+        walk(child, child.id)
+      }
+    }
+    if (boardChild) walk(boardChild, BOARD_NODE_ID)
+    return { version: 1, meta: { device: opts?.device }, nodes }
+  }
+
+  function buildSceneElement(node: SceneNode) {
+    const leaf: MockLeaf = {
+      id: node.id,
+      x: node.x ?? 0,
+      y: node.y ?? 0,
+      children: [],
+      width: node.width ?? 100,
+      height: node.height ?? 100,
+      editable: node.type !== "frame",
+      getBounds: () => ({ x: leaf.x ?? 0, y: leaf.y ?? 0, width: leaf.width ?? 100, height: leaf.height ?? 100 }),
+      set: (config: Record<string, unknown>) => Object.assign(leaf, config),
+    }
+    if (node.type === "frame") {
+      leaf.tag = "Frame"
+      leaf.editable = false
+      if (typeof node.name === "string") leaf.name = node.name
+    }
+    let label: MockLeaf | 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: leaf.x ?? 0, y: (leaf.y ?? 0) - 28, width: 80, height: 18 }),
+      }
+    }
+    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,
+      // 与真实实现同口径：frame 不投影 locked（框选剪枝子树），locked 剪 editable
+      locked: node.type !== "frame" && node.locked === true,
+      editable: node.type === "frame" ? false : node.locked !== true,
+      ...(node.style ?? {}),
+    }
+  }
+
+  return {
+    docToScene: vi.fn(docToScene),
+    leaferToDoc: vi.fn(leaferToDoc),
+    sanitizeScene: vi.fn((doc: SceneDocument) => doc),
+    addLeaf: (parent: MockLeaf, child: MockLeaf) => {
+      const i = parent.children.indexOf(child)
+      if (i >= 0) parent.children.splice(i, 1)
+      child.parent = parent
+      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"
+import { parsePathAnchors } from "../path-anchors"
+
+type MockSub = { type: string; cb: (e?: unknown) => void }
+
+function makeTree() {
+  const tree = {
+    children: [] as MockLeaf[],
+    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)
+    }),
+    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 })),
+    lockLayout: vi.fn(),
+    unlockLayout: vi.fn(),
+    findOne: vi.fn(),
+  }
+  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(),
+  }
+  return editor
+}
+
+function makeApp() {
+  const editor = makeEditor()
+  const app = {
+    tree: makeTree(),
+    sky: makeTree(),
+    editor,
+    mode: "normal" as string,
+    zoom: vi.fn(),
+    zoomLayer: {
+      scaleX: 1,
+      x: undefined as number | undefined,
+      y: undefined as number | undefined,
+      subs: [] as MockSub[],
+      move: vi.fn(),
+      on_: vi.fn((type: string, cb: (e?: unknown) => void) => {
+        app.zoomLayer.subs.push({ type, cb })
+        return { type, current: app.zoomLayer, listener: cb, options: undefined }
+      }),
+      off_: vi.fn(),
+    },
+    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(),
+  }
+  ;(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 () {
+    const app = makeApp()
+    apps.push(app)
+    return app
+  })
+  return {
+    App,
+    apps,
+    Text: {
+      one: vi.fn((config: Record<string, unknown> = {}) => {
+        const label: Record<string, unknown> = {
+          ...config,
+          children: [],
+          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
+      }),
+    },
+    fireApp(app: ReturnType<typeof makeApp>, type: string, event?: unknown) {
+      for (const sub of [...app.subs]) {
+        if (sub.type === type) sub.cb(event)
+      }
+    },
+    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" },
+  }
+}
+
+function rectNode(overrides: Partial<SceneNode> = {}): SceneNode {
+  return {
+    id: "n_1",
+    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 boardLeaf(): MockLeaf {
+  const tree = mod.apps[0].tree
+  return (tree.children ?? []).find((child) => child.id === BOARD_NODE_ID) as MockLeaf
+}
+
+function liveLeaf(id: string): MockLeaf | undefined {
+  const walk = (leaf: MockLeaf): MockLeaf | undefined => {
+    if (leaf.id === id) return leaf
+    for (const child of leaf.children ?? []) {
+      const hit = walk(child)
+      if (hit) return hit
+    }
+    return undefined
+  }
+  return walk(boardLeaf())
+}
+
+/** 收集引擎真实 currentDoc（mock leaferToDoc 读回不可靠，走 onDocChange 通知） */
+function trackDoc(engine: LeaferEngine): { latest: SceneDocument | null } {
+  const state: { latest: SceneDocument | null } = { latest: null }
+  engine.onDocChange((doc) => {
+    state.latest = doc
+  })
+  return state
+}
+
+describe("duplicateSelection（FS-5.3 副本）", () => {
+  it("新 id + 原位 +20/+20 偏移 + 选中 + 单条 history", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1", x: 10, y: 20 })))
+    const state = trackDoc(engine)
+    engine.select(["n_1"])
+
+    engine.duplicateSelection()
+
+    const doc = state.latest!
+    const copy = doc.nodes.find((node) => node.id === "n_2")
+    expect(copy).toBeDefined()
+    expect(copy).toMatchObject({ x: 30, y: 40, parentId: BOARD_NODE_ID })
+    expect(engine.getSelection()).toEqual(["n_2"])
+    expect(engine.history.canUndo).toBe(true)
+    // 原节点不动
+    expect(doc.nodes.find((node) => node.id === "n_1")).toMatchObject({ x: 10, y: 20 })
+  })
+
+  it("空选中时为 no-op（不落 history）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" })))
+
+    engine.duplicateSelection()
+
+    expect(engine.history.canUndo).toBe(false)
+    expect(engine.getSelection()).toEqual([])
+  })
+
+  // 最终审查 F1：copySelection 对空选中清空剪贴板，Mod+D 会静默丢掉
+  // 「复制 → 取消选中 → Mod+D」场景的剪贴板内容
+  it("空选中不清空剪贴板（复制 → 取消选中 → Mod+D 仍可粘贴）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1", x: 10, y: 20 })))
+    engine.select(["n_1"])
+    engine.copySelection()
+    expect(engine.hasClipboard()).toBe(true)
+
+    // 取消选中后 Mod+D：剪贴板必须保留
+    engine.select([])
+    engine.duplicateSelection()
+    expect(engine.hasClipboard()).toBe(true)
+
+    // 剪贴板内容仍可正常粘贴
+    const state = trackDoc(engine)
+    engine.pasteClipboard()
+    expect(state.latest?.nodes.find((node) => node.id === "n_2")).toBeDefined()
+  })
+})
+
+describe("pasteClipboardAt（FS-5.3 粘贴到此处）", () => {
+  it("粘贴后剪贴板内容整体左上角 = 给定点", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1", x: 100, y: 200 })))
+    const state = trackDoc(engine)
+    engine.select(["n_1"])
+    engine.copySelection()
+
+    engine.pasteClipboardAt({ x: 300, y: 400 })
+
+    const copy = state.latest!.nodes.find((node) => node.id === "n_2")
+    expect(copy).toMatchObject({ x: 300, y: 400 })
+    expect(engine.getSelection()).toEqual(["n_2"])
+  })
+
+  it("多节点 union 左上角对齐给定点（内部节点保持相对位置）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(rectNode({ id: "n_1", x: 100, y: 200 }), rectNode({ id: "n_2", x: 150, y: 260 })),
+    )
+    const state = trackDoc(engine)
+    engine.select(["n_1", "n_2"])
+    engine.copySelection()
+
+    engine.pasteClipboardAt({ x: 500, y: 400 })
+
+    const c1 = state.latest!.nodes.find((node) => node.id === "n_3")
+    const c2 = state.latest!.nodes.find((node) => node.id === "n_4")
+    expect(c1).toMatchObject({ x: 500, y: 400 })
+    expect(c2).toMatchObject({ x: 550, y: 460 })
+  })
+
+  it("空剪贴板 no-op", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" })))
+    const state = trackDoc(engine)
+
+    engine.pasteClipboardAt({ x: 0, y: 0 })
+
+    expect(state.latest).toBeNull()
+  })
+})
+
+describe("pasteIntoFrame（FS-5.3 粘贴到画板内）", () => {
+  it("批内顶层 reparent 进画板，board 空间坐标换算为画板局部（原点平移）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "a_1",
+          kind: "group",
+          type: "frame",
+          parentId: BOARD_NODE_ID,
+          name: "画板 1",
+          x: 50,
+          y: 50,
+          width: 300,
+          height: 400,
+        },
+        rectNode({ id: "n_1", x: 100, y: 200 }),
+      ),
+    )
+    const state = trackDoc(engine)
+    engine.select(["n_1"])
+    engine.copySelection()
+
+    engine.pasteIntoFrame("a_1")
+
+    const copy = state.latest!.nodes.find((node) => node.id === "n_2")
+    expect(copy).toMatchObject({ parentId: "a_1", x: 50, y: 150 })
+    expect(engine.getSelection()).toEqual(["n_2"])
+  })
+
+  it("目标画板不存在 / 空剪贴板 no-op", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" })))
+    const state = trackDoc(engine)
+
+    engine.pasteIntoFrame("missing")
+    expect(state.latest).toBeNull()
+
+    engine.select(["n_1"])
+    engine.copySelection()
+    engine.pasteIntoFrame("missing")
+    expect(state.latest).toBeNull()
+  })
+})
+
+describe("setNodesLocked / setNodesVisible（FS-5.3 锁定/隐藏）", () => {
+  it("锁定写入 doc + leaf（locked + editable:false），单条 history，undo 恢复", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" })))
+    const state = trackDoc(engine)
+
+    engine.setNodesLocked(["n_1"], true)
+
+    expect(state.latest!.nodes.find((node) => node.id === "n_1")?.locked).toBe(true)
+    const leaf = liveLeaf("n_1")
+    expect(leaf?.locked).toBe(true)
+    expect(leaf?.editable).toBe(false)
+    expect(engine.history.canUndo).toBe(true)
+
+    engine.undo()
+    expect(state.latest!.nodes.find((node) => node.id === "n_1")?.locked).toBeUndefined()
+  })
+
+  it("解锁还原 doc 与 leaf（locked 清除 + editable 恢复）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1", locked: true })))
+
+    engine.setNodesLocked(["n_1"], false)
+
+    const leaf = liveLeaf("n_1")
+    expect(leaf?.locked).toBe(false)
+    expect(leaf?.editable).toBe(true)
+  })
+
+  it("锁定后 selectAll 不再选中锁定节点（不可选中语义）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" }), rectNode({ id: "n_2" })))
+
+    engine.setNodesLocked(["n_1"], true)
+    engine.selectAll()
+
+    expect(engine.getSelection()).toEqual(["n_2"])
+  })
+
+  it("隐藏写入 doc + leaf visible:false，显示还原", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" })))
+    const state = trackDoc(engine)
+
+    engine.setNodesVisible(["n_1"], false)
+
+    expect(state.latest!.nodes.find((node) => node.id === "n_1")?.visible).toBe(false)
+    expect(liveLeaf("n_1")?.visible).toBe(false)
+    expect(engine.history.canUndo).toBe(true)
+
+    engine.setNodesVisible(["n_1"], true)
+    expect(state.latest!.nodes.find((node) => node.id === "n_1")?.visible).toBeUndefined()
+    expect(liveLeaf("n_1")?.visible).toBe(true)
+  })
+})
+
+describe("replaceNodes（FS-8.4 组件级重生成）", () => {
+  it("删旧 + 加新同一条 history 快照：新节点继承 removeIds[0] 的 parentId/x/y，undo 一次整体恢复，新节点自动选中", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "a_1",
+          kind: "group",
+          type: "frame",
+          parentId: BOARD_NODE_ID,
+          name: "画板 1",
+          x: 50,
+          y: 50,
+          width: 300,
+          height: 400,
+        },
+        rectNode({ id: "n_1", parentId: "a_1", x: 100, y: 200, width: 120, height: 44 }),
+      ),
+    )
+    const state = trackDoc(engine)
+
+    engine.replaceNodes(
+      ["n_1"],
+      [
+        {
+          id: "n_ai_x_1",
+          kind: "component",
+          type: "button",
+          parentId: null,
+          name: "新按钮",
+          x: 0,
+          y: 0,
+          width: 120,
+          height: 44,
+        },
+      ],
+    )
+
+    const doc = state.latest!
+    expect(doc.nodes.find((node) => node.id === "n_1")).toBeUndefined()
+    // 继承锚点：父级挂回原父，位置 = 锚点 x/y + 新节点相对坐标（单节点 0,0 → 原位）
+    expect(doc.nodes.find((node) => node.id === "n_ai_x_1")).toMatchObject({
+      parentId: "a_1",
+      x: 100,
+      y: 200,
+    })
+    // 新节点自动选中
+    expect(engine.getSelection()).toEqual(["n_ai_x_1"])
+    // 单条 history 快照：undo 一次恢复原子树
+    expect(engine.history.canUndo).toBe(true)
+    engine.undo()
+    const restored = state.latest!
+    expect(restored.nodes.find((node) => node.id === "n_1")).toBeDefined()
+    expect(restored.nodes.find((node) => node.id === "n_ai_x_1")).toBeUndefined()
+  })
+
+  it("removeIds 的后代一并删除（同一快照内，undo 同步还原）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "a_1",
+          kind: "group",
+          type: "frame",
+          parentId: BOARD_NODE_ID,
+          name: "画板 1",
+          x: 0,
+          y: 0,
+          width: 300,
+          height: 400,
+        },
+        rectNode({ id: "g_1", kind: "group", type: "group", parentId: "a_1", x: 10, y: 10, width: 100, height: 100 }),
+        rectNode({ id: "n_2", parentId: "g_1", x: 5, y: 5, width: 40, height: 20 }),
+      ),
+    )
+    const state = trackDoc(engine)
+
+    engine.replaceNodes(
+      ["g_1"],
+      [{ id: "n_ai_x_1", kind: "shape", type: "rect", parentId: null, x: 0, y: 0, width: 100, height: 100 }],
+    )
+
+    const doc = state.latest!
+    expect(doc.nodes.find((node) => node.id === "g_1")).toBeUndefined()
+    expect(doc.nodes.find((node) => node.id === "n_2")).toBeUndefined()
+    expect(doc.nodes.find((node) => node.id === "n_ai_x_1")).toMatchObject({ parentId: "a_1" })
+    engine.undo()
+    expect(state.latest!.nodes.find((node) => node.id === "g_1")).toBeDefined()
+    expect(state.latest!.nodes.find((node) => node.id === "n_2")).toBeDefined()
+  })
+
+  it("多节点替换保持相对布局：整批平移 removeIds[0] 锚点并全部选中", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "a_1",
+          kind: "group",
+          type: "frame",
+          parentId: BOARD_NODE_ID,
+          name: "画板 1",
+          x: 0,
+          y: 0,
+          width: 300,
+          height: 400,
+        },
+        rectNode({ id: "n_1", parentId: "a_1", x: 100, y: 200, width: 120, height: 44 }),
+      ),
+    )
+    const state = trackDoc(engine)
+
+    engine.replaceNodes(
+      ["n_1"],
+      [
+        { id: "n_ai_x_1", kind: "shape", type: "rect", parentId: null, x: 0, y: 0, width: 120, height: 44 },
+        { id: "n_ai_x_2", kind: "shape", type: "text", parentId: null, x: 50, y: 10, width: 60, height: 20 },
+      ],
+    )
+
+    const doc = state.latest!
+    expect(doc.nodes.find((node) => node.id === "n_ai_x_1")).toMatchObject({ parentId: "a_1", x: 100, y: 200 })
+    expect(doc.nodes.find((node) => node.id === "n_ai_x_2")).toMatchObject({ parentId: "a_1", x: 150, y: 210 })
+    expect(engine.getSelection()).toEqual(["n_ai_x_1", "n_ai_x_2"])
+    engine.undo()
+    expect(state.latest!.nodes.find((node) => node.id === "n_1")).toMatchObject({ x: 100, y: 200 })
+  })
+
+  it("board 不可删；removeIds 均不存在时 no-op（不落 history）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" })))
+    const state = trackDoc(engine)
+
+    engine.replaceNodes(
+      [BOARD_NODE_ID],
+      [{ id: "n_ai_x_1", kind: "shape", type: "rect", parentId: null, x: 0, y: 0, width: 10, height: 10 }],
+    )
+    expect(engine.history.canUndo).toBe(false)
+
+    engine.replaceNodes(
+      ["missing"],
+      [{ id: "n_ai_x_2", kind: "shape", type: "rect", parentId: null, x: 0, y: 0, width: 10, height: 10 }],
+    )
+    expect(state.latest).toBeNull()
+    expect(engine.history.canUndo).toBe(false)
+  })
+
+  it("nodes 为空时 no-op（不落 history）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1" })))
+    const state = trackDoc(engine)
+
+    engine.replaceNodes(["n_1"], [])
+
+    expect(state.latest).toBeNull()
+    expect(engine.history.canUndo).toBe(false)
+    expect(engine.getSelection()).toEqual([])
+  })
+})
+
+describe("applyNodePatch 编组布局约束（画框移除后编组承接容器约束语义）", () => {
+  it("面板改组宽高 → 成员按 constraints 重排（min 不动 / stretch 吃满增量）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "group_1",
+          kind: "group",
+          type: "group",
+          parentId: BOARD_NODE_ID,
+          name: "编组 1",
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 100,
+        },
+        rectNode({
+          id: "n_1",
+          parentId: "group_1",
+          x: 0,
+          y: 0,
+          width: 50,
+          height: 50,
+          constraints: { horizontal: "min", vertical: "min" },
+        }),
+        rectNode({
+          id: "n_2",
+          parentId: "group_1",
+          x: 50,
+          y: 0,
+          width: 50,
+          height: 100,
+          constraints: { horizontal: "stretch", vertical: "stretch" },
+        }),
+      ),
+    )
+    const state = trackDoc(engine)
+    engine.select(["group_1"])
+
+    engine.applyNodePatch("group_1", { width: 200, height: 200 })
+
+    // min：位置尺寸不动；stretch：位置不变、尺寸吃满 (100,100) 增量
+    expect(state.latest!.nodes.find((n) => n.id === "n_1")).toMatchObject({
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+    })
+    expect(state.latest!.nodes.find((n) => n.id === "n_2")).toMatchObject({
+      x: 50,
+      y: 0,
+      width: 150,
+      height: 200,
+    })
+    expect(engine.history.canUndo).toBe(true)
+  })
+})
+
+describe("applyBooleanOp（图形布尔运算）", () => {
+  it("两个重叠 rect union → 结果 path 节点替换成员并选中", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        rectNode({ id: "n_1", x: 0, y: 0, width: 100, height: 100 }),
+        rectNode({ id: "n_2", x: 50, y: 50, width: 100, height: 100 }),
+      ),
+    )
+    const state = trackDoc(engine)
+    engine.select(["n_1", "n_2"])
+
+    expect(engine.applyBooleanOp("union")).toBe(true)
+
+    // 两个原成员被删除，新 path 节点生成：150×150 @ (0,0)，继承底图样式
+    const ids = state.latest!.nodes.map((node) => node.id)
+    expect(ids).not.toContain("n_1")
+    expect(ids).not.toContain("n_2")
+    const created = state.latest!.nodes.find((node) => node.type === "path")
+    expect(created).toMatchObject({ x: 0, y: 0, width: 150, height: 150, parentId: BOARD_NODE_ID })
+    expect(String(created!.props?.path)).toContain("M")
+    expect(engine.getSelection()).toEqual([created!.id])
+    expect(engine.history.canUndo).toBe(true)
+  })
+
+  it("intersect 面积缩为重叠区", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        rectNode({ id: "n_1", x: 0, y: 0, width: 100, height: 100 }),
+        rectNode({ id: "n_2", x: 50, y: 50, width: 100, height: 100 }),
+      ),
+    )
+    const state = trackDoc(engine)
+    engine.select(["n_1", "n_2"])
+
+    expect(engine.applyBooleanOp("intersect")).toBe(true)
+    const created = state.latest!.nodes.find((node) => node.type === "path")
+    expect(created).toMatchObject({ x: 50, y: 50, width: 50, height: 50 })
+  })
+
+  it("跨父 / 单选 / 不支持类型返回 false 且不落 history", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        rectNode({ id: "n_1" }),
+        rectNode({ id: "n_2" }),
+        {
+          id: "a_1",
+          kind: "group",
+          type: "frame",
+          parentId: BOARD_NODE_ID,
+          name: "画板 1",
+          x: 0,
+          y: 0,
+          width: 300,
+          height: 300,
+        },
+        rectNode({ id: "n_3", parentId: "a_1" }),
+        { ...rectNode({ id: "t_1" }), type: "text" as never },
+      ),
+    )
+    const state = trackDoc(engine)
+
+    engine.select(["n_1"])
+    expect(engine.applyBooleanOp("union")).toBe(false)
+    engine.select(["n_1", "n_3"])
+    expect(engine.applyBooleanOp("union")).toBe(false)
+    // 类型不支持
+    engine.select(["t_1", "n_1"])
+    expect(engine.applyBooleanOp("union")).toBe(false)
+
+    expect(engine.history.canUndo).toBe(false)
+    expect(state.latest).toBeNull()
+  })
+})
+
+describe("路径锚点编辑（enterPathEdit）", () => {
+  it("rect 进入编辑：自动转为 path（闭合采样轮廓）并可拖拽锚点", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "n_1", x: 0, y: 0, width: 100, height: 50 })))
+    engine.select(["n_1"])
+    const state = trackDoc(engine)
+
+    expect(engine.enterPathEdit("n_1")).toBe(true)
+    expect(engine.pathEditingNodeId).toBe("n_1")
+
+    // rect → path：闭合轮廓采样（直角矩形 4 锚点）
+    const node = state.latest!.nodes.find((n) => n.id === "n_1")
+    expect(node?.type).toBe("path")
+    const anchors = engine.getPathEditInfo()
+    expect(anchors).toMatchObject({ nodeId: "n_1", closed: true, selected: null })
+    expect(anchors!.count).toBeGreaterThanOrEqual(4)
+
+    // 拖拽锚点 0 到 (50, -10)（世界坐标 → 局部落库）
+    engine.movePathAnchor(0, 50, -10)
+    const moved = state.latest!.nodes.find((n) => n.id === "n_1")
+    expect(String(moved?.props?.path)).toContain("M 50 -10")
+
+    // 退出编辑
+    engine.exitPathEdit()
+    expect(engine.pathEditingNodeId).toBeNull()
+  })
+
+  it("ellipse 进入编辑：4 锚点（kappa 手柄），锚点拖拽携带手柄", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(docWith(rectNode({ id: "e_1", type: "ellipse", name: "Ellipse", x: 0, y: 0 })))
+    engine.select(["e_1"])
+    const state = trackDoc(engine)
+
+    expect(engine.enterPathEdit("e_1")).toBe(true)
+    const info = engine.getPathEditInfo()
+    expect(info).toMatchObject({ nodeId: "e_1", closed: true, count: 4 })
+
+    // 转换产物含 C 段（贝塞尔而非 64 点采样折线）
+    const node = state.latest!.nodes.find((n) => n.id === "e_1")
+    expect(node?.type).toBe("path")
+    expect(String(node?.props?.path).match(/C /g)).toHaveLength(4)
+
+    // 拖顶点锚点：锚点与手柄同步平移（曲线形状不被撕裂）
+    engine.selectPathAnchor(0)
+    engine.movePathAnchor(0, 60, -5)
+    const moved = state.latest!.nodes.find((n) => n.id === "e_1")
+    const parsed = parsePathAnchors(String(moved?.props?.path))
+    expect(parsed.anchors[0].x).toBeCloseTo(60, 0)
+    expect(parsed.anchors[0].hOut).toBeDefined()
+    engine.exitPathEdit()
+    expect(engine.pathEditingNodeId).toBeNull()
+  })
+
+  it("path 节点直接进入（无类型转换）；text 拒绝", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "p_1",
+          kind: "shape",
+          type: "path",
+          parentId: BOARD_NODE_ID,
+          name: "Path",
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 100,
+          props: { path: "M 0 0 L 100 0 L 50 100 Z" },
+        },
+        { ...rectNode({ id: "t_1" }), type: "text" as never },
+      ),
+    )
+
+    expect(engine.enterPathEdit("p_1")).toBe(true)
+    expect(engine.getPathEditInfo()).toMatchObject({ count: 3, closed: true })
+    engine.exitPathEdit()
+
+    engine.select(["t_1"])
+    expect(engine.enterPathEdit("t_1")).toBe(false)
+    expect(engine.pathEditingNodeId).toBeNull()
+  })
+})
+
+describe("reparentOnDrop group 落点（FS-4.3）", () => {
+  it("拖到顶层 group 内：dropTo group，读回 doc parentId 为 group（worldToLocal 守恒）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "g_1",
+          kind: "group",
+          type: "group",
+          parentId: BOARD_NODE_ID,
+          x: 100,
+          y: 100,
+          width: 200,
+          height: 200,
+        },
+        rectNode({ id: "n_1", x: 120, y: 120, width: 40, height: 40 }),
+      ),
+    )
+    const state = trackDoc(engine)
+    engine.select(["n_1"])
+
+    const app = mod.apps[0]
+    mod.fireApp(app, "drag.end")
+
+    // dropTo 目标为 group leaf，且世界坐标守恒（mock 内 board 原点 0 → group 内
+    // 相对坐标 = 原父空间坐标 − group 原点 = (20,20)）
+    const leaf = liveLeaf("n_1")
+    expect(leaf?.parent?.id).toBe("g_1")
+    expect(leaf?.x).toBe(20)
+    expect(leaf?.y).toBe(20)
+    // 读回 doc：parentId 已是 group
+    expect(state.latest?.nodes.find((node) => node.id === "n_1")?.parentId).toBe("g_1")
+  })
+
+  // 最终审查 B3：dropTo 挂载不触发 leafer 的组尺寸维护（仅子元素 MOVE 事件内
+  // 更新）——组 bounds 停留在建组时值，落在 bounds 外的成员点击命中丢失
+  it("拖入成员后组 bounds 重算（leaf 与 doc 同步为孩子们 union）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "g_1",
+          kind: "group",
+          type: "group",
+          parentId: BOARD_NODE_ID,
+          x: 100,
+          y: 100,
+          width: 200,
+          height: 200,
+        },
+        rectNode({ id: "n_1", x: 120, y: 120, width: 40, height: 40 }),
+      ),
+    )
+    const state = trackDoc(engine)
+    engine.select(["n_1"])
+    mod.fireApp(mod.apps[0], "drag.end")
+
+    // n_1 落组内相对 (20,20) 尺寸 40×40 → 组尺寸 union = 60×60（原 200×200）
+    const groupLeaf = liveLeaf("g_1")
+    expect(groupLeaf?.width).toBe(60)
+    expect(groupLeaf?.height).toBe(60)
+    expect(state.latest?.nodes.find((node) => node.id === "g_1")).toMatchObject({
+      width: 60,
+      height: 60,
+    })
+  })
+
+  it("子元素拖出 group 到空白区：doc parentId 同步为 board（回修 Important）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "g_1",
+          kind: "group",
+          type: "group",
+          parentId: BOARD_NODE_ID,
+          x: 100,
+          y: 100,
+          width: 200,
+          height: 200,
+        },
+        // 子元素初始在组内（doc parentId=g_1，组空间坐标）
+        { id: "n_child", kind: "shape", type: "rect", parentId: "g_1", x: 20, y: 20, width: 40, height: 40 },
+      ),
+    )
+    const state = trackDoc(engine)
+    engine.select(["n_child"])
+    // 成员 leaf 挪到组外空白区（组空间 (500,500)，在 g_1 bounds (100..300)
+    // 的 world 命中范围之外 → pickDropContainer 无命中 → dropTo(board)）
+    const leaf = liveLeaf("n_child")
+    if (!leaf) throw new Error("n_child leaf not found")
+    ;(leaf as { set: (config: Record<string, unknown>) => void }).set({ x: 500, y: 500 })
+    mod.fireApp(mod.apps[0], "drag.end")
+
+    // dropTo(board) 已在树层执行：leaf 父级为 board
+    expect(liveLeaf("n_child")?.parent?.id).toBe(BOARD_NODE_ID)
+    // doc 层必须同步（此路径唯一同步点），不能停留 g_1
+    expect(state.latest?.nodes.find((node) => node.id === "n_child")?.parentId).toBe(BOARD_NODE_ID)
+  })
+
+  it("落点不在任何容器内：保持 board 顶层不动", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith(
+        {
+          id: "g_1",
+          kind: "group",
+          type: "group",
+          parentId: BOARD_NODE_ID,
+          x: 100,
+          y: 100,
+          width: 200,
+          height: 200,
+        },
+        rectNode({ id: "n_1", x: 500, y: 500, width: 40, height: 40 }),
+      ),
+    )
+    engine.select(["n_1"])
+
+    mod.fireApp(mod.apps[0], "drag.end")
+
+    expect(liveLeaf("n_1")?.parent?.id).toBe(BOARD_NODE_ID)
+  })
+
+  it("拖 group 进自己/后代被排除（exclude 语义）", () => {
+    const engine = new LeaferEngine(mod as never)
+    engine.mount(el)
+    engine.loadDoc(
+      docWith({
+        id: "g_1",
+        kind: "group",
+        type: "group",
+        parentId: BOARD_NODE_ID,
+        x: 100,
+        y: 100,
+        width: 200,
+        height: 200,
+      }),
+    )
+    engine.select(["g_1"])
+
+    // group 中心在自己 bounds 内，但 exclude 阻止 self-drop
+    mod.fireApp(mod.apps[0], "drag.end")
+
+    expect(liveLeaf("g_1")?.parent?.id).toBe(BOARD_NODE_ID)
+  })
+})