@allbluecn/web-app 0.17.1 → 0.18.0

package/src/components/design/canvas/react/__tests__/hooks.test.tsx

@@ -0,0 +1,1009 @@
+// 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 { validateHotkey, type Hotkey } from "@tanstack/hotkeys"
+import { HotkeysProvider } from "@tanstack/react-hotkeys"
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react"
+import { useEffect, useState } from "react"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+import type { SceneDocument, ToolId } from "../../document/types"
+import { BOARD_NODE_ID, createBoardNode, createEmptyDoc } from "../../document/types"
+import { LeaferEngine } from "@/design-engine/engine/app"
+import { CanvasProvider } from "../canvas-context"
+import { useCanvasHost } from "../canvas-hooks"
+import { CanvasRoot } from "../canvas-root"
+import {
+  DUPLICATE_HOTKEY,
+  GROUP_HOTKEY,
+  HIDE_HOTKEY,
+  LAYER_BACK_HOTKEY,
+  LAYER_BACKWARD_HOTKEY,
+  LAYER_FORWARD_HOTKEY,
+  LAYER_FRONT_HOTKEY,
+  LOCK_HOTKEY,
+  REDO_HOTKEY,
+  UNGROUP_HOTKEY,
+  UNDO_HOTKEY,
+  useDeleteSelection,
+  useEditCommands,
+  useGroupUngroup,
+  usePanMode,
+  useSceneDoc,
+  useSelection,
+  useTool,
+  useUndoRedo,
+} from "../hooks"
+
+vi.mock("@/design-engine/engine/app", () => ({
+  LeaferEngine: { create: vi.fn() },
+}))
+
+vi.mock("@allbluecn/ui/toast", () => ({
+  toast: {
+    success: vi.fn(),
+    error: vi.fn(),
+    warning: vi.fn(),
+    info: vi.fn(),
+    loading: vi.fn(),
+    message: vi.fn(),
+    dismiss: vi.fn(),
+    promise: vi.fn(),
+  },
+}))
+
+type ListenerMap = {
+  doc: Set<(doc: SceneDocument) => void>
+  selection: Set<(ids: string[]) => void>
+  tool: Set<(tool: ToolId) => void>
+}
+
+function makeFakeEngine() {
+  const listeners: ListenerMap = {
+    doc: new Set(),
+    selection: new Set(),
+    tool: new Set(),
+  }
+  let doc: SceneDocument = createEmptyDoc("desktop")
+  const fireDoc = (next: SceneDocument) => {
+    doc = next
+    for (const cb of listeners.doc) cb(doc)
+  }
+  return {
+    mount: vi.fn(),
+    dispose: vi.fn(),
+    getZoom: vi.fn(() => 1),
+    panBy: vi.fn(),
+    // canvas-context 在 document focus/blur 时调用（TextEditor 官方键盘开关）
+    setKeyEventEnabled: vi.fn(),
+    // 预设画板创建后 frame-tool 调用（自动定位到新画板）
+    zoomToFrame: vi.fn(),
+    setTool: vi.fn((tool: ToolId) => {
+      for (const cb of listeners.tool) cb(tool)
+    }),
+    undo: vi.fn(),
+    redo: vi.fn(),
+    history: { canUndo: false, canRedo: false },
+    listeners,
+    fireDoc,
+    fireSelection: (ids: string[]) => {
+      for (const cb of listeners.selection) cb(ids)
+    },
+    getDoc: vi.fn(() => doc),
+    loadDoc: vi.fn(),
+    onDocChange: vi.fn((cb: (doc: SceneDocument) => void) => {
+      listeners.doc.add(cb)
+      return () => {
+        listeners.doc.delete(cb)
+      }
+    }),
+    onSelectionChange: vi.fn((cb: (ids: string[]) => void) => {
+      listeners.selection.add(cb)
+      return () => {
+        listeners.selection.delete(cb)
+      }
+    }),
+    onFrameRenameRequest: vi.fn(() => () => {}),
+    frameRenameClientPos: vi.fn(() => null),
+    onToolChange: vi.fn((cb: (tool: ToolId) => void) => {
+      listeners.tool.add(cb)
+      return () => {
+        listeners.tool.delete(cb)
+      }
+    }),
+    zoomTo: vi.fn(),
+    fit: vi.fn(),
+    focusNode: vi.fn(),
+    select: vi.fn(),
+    getSelection: vi.fn(() => []),
+    deleteSelectedNodes: vi.fn(),
+    groupSelection: vi.fn<() => string | null>(() => "group_1"),
+    ungroupSelection: vi.fn(),
+    applyNodePatch: vi.fn(),
+    applyNodesAppend: vi.fn(),
+    // FS-5.3/FS-5.4：菜单命令族与快捷键
+    duplicateSelection: vi.fn(),
+    reorderNodes: vi.fn(),
+    setNodesLocked: vi.fn(),
+    setNodesVisible: vi.fn(),
+  }
+}
+
+function docWithRect(): SceneDocument {
+  return {
+    version: 1,
+    meta: { device: "desktop" },
+    nodes: [
+      createBoardNode("desktop"),
+      {
+        id: "n1",
+        kind: "shape",
+        type: "rect",
+        parentId: BOARD_NODE_ID,
+        name: "矩形",
+        x: 10,
+        y: 10,
+        width: 120,
+        height: 60,
+      },
+    ],
+  }
+}
+
+function Probe() {
+  const doc = useSceneDoc()
+  const selection = useSelection()
+  const { tool, setTool } = useTool()
+  const { canUndo, canRedo, undo } = useUndoRedo()
+  const hostRef = useCanvasHost()
+
+  return (
+    <>
+      <div ref={hostRef} data-testid="host" />
+      <span data-testid="node-count">{doc.nodes.length}</span>
+      <span data-testid="node-1-width">{doc.nodes[1]?.width ?? "-"}</span>
+      <span data-testid="selection">{selection.join(",")}</span>
+      <span data-testid="tool">{tool}</span>
+      <span data-testid="can-undo">{String(canUndo)}</span>
+      <span data-testid="can-redo">{String(canRedo)}</span>
+      <button type="button" data-testid="switch-tool" onClick={() => setTool("rect")}>
+        矩形
+      </button>
+      <button type="button" data-testid="undo" onClick={undo}>
+        撤销
+      </button>
+      <input data-testid="plain-input" />
+    </>
+  )
+}
+
+describe("canvas hooks", () => {
+  let engine: ReturnType<typeof makeFakeEngine>
+
+  beforeEach(() => {
+    engine = makeFakeEngine()
+    vi.mocked(LeaferEngine.create).mockReset()
+    vi.mocked(LeaferEngine.create).mockResolvedValue(engine as never)
+  })
+
+  function renderProbe(props: { readOnly?: boolean; device?: "desktop" | "tablet" | "mobile"; onDocChange?: (doc: SceneDocument) => void } = {}) {
+    return render(
+      <HotkeysProvider>
+        <CanvasProvider readOnly={props.readOnly} device={props.device} onDocChange={props.onDocChange}>
+          <Probe />
+        </CanvasProvider>
+      </HotkeysProvider>,
+    )
+  }
+
+  it("onDocChange 驱动 useSceneDoc 与 useSelection 更新", async () => {
+    renderProbe()
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+    expect(screen.getByTestId("node-count").textContent).toBe("1")
+    expect(screen.getByTestId("selection").textContent).toBe("")
+
+    engine.fireDoc(docWithRect())
+    engine.fireSelection(["n1"])
+
+    await waitFor(() => expect(screen.getByTestId("node-count").textContent).toBe("2"))
+    expect(screen.getByTestId("node-1-width").textContent).toBe("120")
+    // selection 通知经 rAF 合并（防 leafer 异步空选中闪断属性面板）
+    await waitFor(() => expect(screen.getByTestId("selection").textContent).toBe("n1"))
+  })
+
+  it("onDocChange prop 与 hook 订阅同步触发一次", async () => {
+    const onDocChange = vi.fn()
+    renderProbe({ onDocChange })
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+    expect(onDocChange).not.toHaveBeenCalled()
+
+    engine.fireDoc(docWithRect())
+
+    await waitFor(() => expect(onDocChange).toHaveBeenCalledTimes(1))
+  })
+
+  it("useTool 切换后状态更新并调用 engine.setTool", async () => {
+    renderProbe()
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+    expect(screen.getByTestId("tool").textContent).toBe("select")
+
+    fireEvent.click(screen.getByTestId("switch-tool"))
+
+    await waitFor(() => expect(screen.getByTestId("tool").textContent).toBe("rect"))
+    expect(engine.setTool).toHaveBeenCalledWith("rect")
+  })
+
+  it("readOnly 与 device 透传给 engine.mount", async () => {
+    renderProbe({ readOnly: true, device: "mobile" })
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+    const [host, opts] = engine.mount.mock.calls[0] as [HTMLElement, { readOnly?: boolean; device?: "desktop" | "tablet" | "mobile" }]
+    expect(host).toBeInstanceOf(HTMLElement)
+    expect(opts).toMatchObject({ readOnly: true, device: "mobile" })
+  })
+
+  it("卸载时 dispose 并退订全部监听", async () => {
+    const { unmount } = renderProbe()
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+    expect(engine.listeners.doc.size).toBe(1)
+    expect(engine.listeners.selection.size).toBe(1)
+    expect(engine.listeners.tool.size).toBe(1)
+    expect(engine.dispose).not.toHaveBeenCalled()
+
+    unmount()
+
+    expect(engine.dispose).toHaveBeenCalledTimes(1)
+    expect(engine.listeners.doc.size).toBe(0)
+    expect(engine.listeners.selection.size).toBe(0)
+    expect(engine.listeners.tool.size).toBe(0)
+  })
+
+  it("useUndoRedo 反映 history 状态并调用 engine.undo", async () => {
+    engine.history.canUndo = true
+    engine.history.canRedo = false
+    renderProbe()
+
+    await waitFor(() => expect(screen.getByTestId("can-undo").textContent).toBe("true"))
+    expect(screen.getByTestId("can-redo").textContent).toBe("false")
+
+    fireEvent.click(screen.getByTestId("undo"))
+
+    expect(engine.undo).toHaveBeenCalledTimes(1)
+  })
+
+  it("焦点在 body（点击画布后）时 Mod+Z/Mod+Shift+Z 触发撤销重做", async () => {
+    const { unmount } = renderProbe()
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+    fireEvent.keyDown(document.body, { key: "z", ctrlKey: true })
+    expect(engine.undo).toHaveBeenCalledTimes(1)
+
+    fireEvent.keyDown(document.body, { key: "z", ctrlKey: true, shiftKey: true })
+    expect(engine.redo).toHaveBeenCalledTimes(1)
+
+    unmount()
+  })
+
+  it("焦点在输入框时 Mod+Z 不触发画布撤销", async () => {
+    const { unmount } = renderProbe()
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+    fireEvent.keyDown(screen.getByTestId("plain-input"), { key: "z", ctrlKey: true })
+    expect(engine.undo).not.toHaveBeenCalled()
+
+    unmount()
+  })
+
+  it("provider 之外使用 hooks 抛错", () => {
+    expect(() => render(<Probe />)).toThrow(/CanvasProvider/)
+  })
+
+  it("undo/redo 快捷键语法通过 @tanstack/hotkeys 校验", () => {
+    for (const hotkey of [UNDO_HOTKEY, REDO_HOTKEY, GROUP_HOTKEY, UNGROUP_HOTKEY] as Hotkey[]) {
+      const result = validateHotkey(hotkey)
+      expect(result.errors, hotkey).toEqual([])
+      expect(result.warnings, hotkey).toEqual([])
+    }
+  })
+
+  it("FS-5.4 新增快捷键语法通过 @tanstack/hotkeys 校验", () => {
+    for (const hotkey of [
+      DUPLICATE_HOTKEY,
+      LAYER_FORWARD_HOTKEY,
+      LAYER_BACKWARD_HOTKEY,
+      LAYER_FRONT_HOTKEY,
+      LAYER_BACK_HOTKEY,
+      LOCK_HOTKEY,
+      HIDE_HOTKEY,
+    ] as Hotkey[]) {
+      const result = validateHotkey(hotkey)
+      expect(result.errors, hotkey).toEqual([])
+      expect(result.warnings, hotkey).toEqual([])
+    }
+  })
+
+  function lateDocHarness(onReady: (setDoc: (doc: SceneDocument) => void) => void) {
+    function Host() {
+      const hostRef = useCanvasHost()
+      return <div ref={hostRef} data-testid="host" />
+    }
+    function Harness() {
+      const [doc, setDoc] = useState<SceneDocument>(createEmptyDoc("desktop"))
+      useEffect(() => {
+        onReady(setDoc)
+      }, [onReady])
+
+      return (
+        <CanvasProvider initialDoc={doc} onDocChange={setDoc}>
+          <Host />
+        </CanvasProvider>
+      )
+    }
+    return render(
+      <HotkeysProvider>
+        <Harness />
+      </HotkeysProvider>,
+    )
+  }
+
+  it("initialDoc 晚于引擎创建到达时推入引擎（服务端加载/页面切换）", async () => {
+    let setDoc!: (doc: SceneDocument) => void
+    lateDocHarness((fn) => {
+      setDoc = fn
+    })
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+    expect(engine.loadDoc).toHaveBeenCalledTimes(1)
+
+    const loaded = docWithRect()
+    await act(async () => {
+      setDoc(loaded)
+    })
+
+    await waitFor(() => expect(engine.loadDoc).toHaveBeenCalledTimes(2))
+    expect(engine.loadDoc.mock.calls[1]?.[0]).toBe(loaded)
+  })
+
+  it("引擎发出的 doc 回流不会重复 loadDoc（无同步环）", async () => {
+    lateDocHarness(() => {})
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+    expect(engine.loadDoc).toHaveBeenCalledTimes(1)
+
+    await act(async () => {
+      engine.fireDoc(docWithRect())
+    })
+
+    expect(engine.loadDoc).toHaveBeenCalledTimes(1)
+  })
+
+  describe("useGroupUngroup", () => {
+    function GroupHost() {
+      const hostRef = useCanvasHost()
+      useGroupUngroup()
+      return (
+        <>
+          <div ref={hostRef} data-testid="host" />
+          <input data-testid="plain-input" />
+        </>
+      )
+    }
+
+    function renderGroupProbe(readOnly = false) {
+      return render(
+        <HotkeysProvider>
+          <CanvasProvider readOnly={readOnly}>
+            <GroupHost />
+          </CanvasProvider>
+        </HotkeysProvider>,
+      )
+    }
+
+    it("焦点在 body（点击画布后）时 Mod+G 触发 engine.groupSelection", async () => {
+      const { unmount } = renderGroupProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "g", ctrlKey: true })
+      expect(engine.groupSelection).toHaveBeenCalledTimes(1)
+
+      unmount()
+    })
+
+    it("Shift+Mod+G 触发 engine.ungroupSelection", async () => {
+      const { unmount } = renderGroupProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "G", ctrlKey: true, shiftKey: true })
+      expect(engine.ungroupSelection).toHaveBeenCalledTimes(1)
+      // Shift+Mod+G 不得误触建组
+      expect(engine.groupSelection).not.toHaveBeenCalled()
+
+      unmount()
+    })
+
+    it("groupSelection 返回 null 时 toast 提示（请选择同一画板下的元素）", async () => {
+      const { toast } = await import("@allbluecn/ui/toast")
+      engine.groupSelection.mockReturnValueOnce(null)
+      const { unmount } = renderGroupProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "g", ctrlKey: true })
+      expect(toast.warning).toHaveBeenCalledTimes(1)
+
+      unmount()
+    })
+
+    it("焦点在输入框时不触发编组/解组", async () => {
+      const { unmount } = renderGroupProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: "g", ctrlKey: true })
+      fireEvent.keyDown(screen.getByTestId("plain-input"), {
+        key: "G",
+        ctrlKey: true,
+        shiftKey: true,
+      })
+      expect(engine.groupSelection).not.toHaveBeenCalled()
+      expect(engine.ungroupSelection).not.toHaveBeenCalled()
+
+      unmount()
+    })
+
+    it("readOnly 画布不绑定编组/解组快捷键", async () => {
+      const { unmount } = renderGroupProbe(true)
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "g", ctrlKey: true })
+      fireEvent.keyDown(document.body, { key: "G", ctrlKey: true, shiftKey: true })
+      expect(engine.groupSelection).not.toHaveBeenCalled()
+      expect(engine.ungroupSelection).not.toHaveBeenCalled()
+
+      unmount()
+    })
+  })
+
+  describe("useEditCommands", () => {
+    function EditHost() {
+      const hostRef = useCanvasHost()
+      const selection = useSelection()
+      const doc = useSceneDoc()
+      useEditCommands()
+      const n1 = doc.nodes.find((node) => node.id === "n1")
+      return (
+        <>
+          <div ref={hostRef} data-testid="host" />
+          {/* selection 经 rAF 合并通知、doc 更新为异步 re-render：用 DOM 回显
+              等待状态进入 snapshot（快捷键闭包依赖） */}
+          <span data-testid="edit-selection">{selection.join(",")}</span>
+          <span data-testid="edit-n1-state">
+            {n1 ? `${n1.locked === true ? "L" : "l"}${n1.visible === false ? "H" : "h"}` : "-"}
+          </span>
+          <input data-testid="plain-input" />
+        </>
+      )
+    }
+
+    function renderEditProbe(readOnly = false) {
+      return render(
+        <HotkeysProvider>
+          <CanvasProvider readOnly={readOnly}>
+            <EditHost />
+          </CanvasProvider>
+        </HotkeysProvider>,
+      )
+    }
+
+    async function selectAndWait(ids: string[]) {
+      engine.fireSelection(ids)
+      await waitFor(() =>
+        expect(screen.getByTestId("edit-selection").textContent).toBe(ids.join(",")),
+      )
+    }
+
+    it("Mod+D 触发 duplicateSelection（副本）", async () => {
+      const { unmount } = renderEditProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "d", ctrlKey: true })
+      expect(engine.duplicateSelection).toHaveBeenCalledTimes(1)
+
+      unmount()
+    })
+
+    it("] 上移一层 / Mod+] 置顶 / [ 下移一层 / Mod+[ 置底", async () => {
+      const { unmount } = renderEditProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      await selectAndWait(["n1"])
+
+      fireEvent.keyDown(document.body, { key: "]" })
+      expect(engine.reorderNodes).toHaveBeenLastCalledWith(["n1"], "forward")
+
+      fireEvent.keyDown(document.body, { key: "]", ctrlKey: true })
+      expect(engine.reorderNodes).toHaveBeenLastCalledWith(["n1"], "front")
+
+      fireEvent.keyDown(document.body, { key: "[" })
+      expect(engine.reorderNodes).toHaveBeenLastCalledWith(["n1"], "backward")
+
+      fireEvent.keyDown(document.body, { key: "[", ctrlKey: true })
+      expect(engine.reorderNodes).toHaveBeenLastCalledWith(["n1"], "back")
+
+      unmount()
+    })
+
+    it("Shift+Mod+L 锁定（选中未锁定 → locked=true）", async () => {
+      const { unmount } = renderEditProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      engine.fireDoc(docWithRect())
+      await waitFor(() => expect(screen.getByTestId("edit-n1-state").textContent).toBe("lh"))
+      await selectAndWait(["n1"])
+
+      fireEvent.keyDown(document.body, { key: "L", ctrlKey: true, shiftKey: true })
+      expect(engine.setNodesLocked).toHaveBeenCalledTimes(1)
+      expect(engine.setNodesLocked).toHaveBeenCalledWith(["n1"], true)
+
+      unmount()
+    })
+
+    it("锁定为切换语义：选中全锁定 → Shift+Mod+L 解锁", async () => {
+      const { unmount } = renderEditProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      engine.fireDoc(docWithRect())
+      await waitFor(() => expect(screen.getByTestId("edit-n1-state").textContent).toBe("lh"))
+      await selectAndWait(["n1"])
+
+      fireEvent.keyDown(document.body, { key: "L", ctrlKey: true, shiftKey: true })
+      expect(engine.setNodesLocked).toHaveBeenLastCalledWith(["n1"], true)
+
+      // doc 回流：节点已锁定（等待 snapshot 更新使 toggleLock 闭包拿到新 doc）
+      engine.fireDoc({
+        version: 1,
+        meta: { device: "desktop" },
+        nodes: [
+          createBoardNode("desktop"),
+          { ...docWithRect().nodes[1], locked: true },
+        ],
+      })
+      await waitFor(() => expect(screen.getByTestId("edit-n1-state").textContent).toBe("Lh"))
+      fireEvent.keyDown(document.body, { key: "L", ctrlKey: true, shiftKey: true })
+      expect(engine.setNodesLocked).toHaveBeenLastCalledWith(["n1"], false)
+
+      unmount()
+    })
+
+    it("Shift+Mod+H 隐藏（选中可见 → visible=false），全隐藏时切换为显示", async () => {
+      const { unmount } = renderEditProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      engine.fireDoc(docWithRect())
+      await waitFor(() => expect(screen.getByTestId("edit-n1-state").textContent).toBe("lh"))
+      await selectAndWait(["n1"])
+
+      fireEvent.keyDown(document.body, { key: "H", ctrlKey: true, shiftKey: true })
+      expect(engine.setNodesVisible).toHaveBeenLastCalledWith(["n1"], false)
+
+      engine.fireDoc({
+        version: 1,
+        meta: { device: "desktop" },
+        nodes: [
+          createBoardNode("desktop"),
+          { ...docWithRect().nodes[1], visible: false },
+        ],
+      })
+      await waitFor(() => expect(screen.getByTestId("edit-n1-state").textContent).toBe("lH"))
+      fireEvent.keyDown(document.body, { key: "H", ctrlKey: true, shiftKey: true })
+      expect(engine.setNodesVisible).toHaveBeenLastCalledWith(["n1"], true)
+
+      unmount()
+    })
+
+    it("无选中时层级/锁定/隐藏 no-op", async () => {
+      const { unmount } = renderEditProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "]" })
+      fireEvent.keyDown(document.body, { key: "L", ctrlKey: true, shiftKey: true })
+      fireEvent.keyDown(document.body, { key: "H", ctrlKey: true, shiftKey: true })
+      expect(engine.reorderNodes).not.toHaveBeenCalled()
+      expect(engine.setNodesLocked).not.toHaveBeenCalled()
+      expect(engine.setNodesVisible).not.toHaveBeenCalled()
+
+      unmount()
+    })
+
+    it("焦点在输入框时不触发编辑命令快捷键", async () => {
+      const { unmount } = renderEditProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      await selectAndWait(["n1"])
+
+      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: "d", ctrlKey: true })
+      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: "]" })
+      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: "L", ctrlKey: true, shiftKey: true })
+      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: "H", ctrlKey: true, shiftKey: true })
+      expect(engine.duplicateSelection).not.toHaveBeenCalled()
+      expect(engine.reorderNodes).not.toHaveBeenCalled()
+      expect(engine.setNodesLocked).not.toHaveBeenCalled()
+      expect(engine.setNodesVisible).not.toHaveBeenCalled()
+
+      unmount()
+    })
+
+    it("readOnly 画布不绑定编辑命令快捷键", async () => {
+      const { unmount } = renderEditProbe(true)
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "d", ctrlKey: true })
+      fireEvent.keyDown(document.body, { key: "]" })
+      expect(engine.duplicateSelection).not.toHaveBeenCalled()
+      expect(engine.reorderNodes).not.toHaveBeenCalled()
+
+      unmount()
+    })
+  })
+
+  describe("useDeleteSelection", () => {
+    function DeleteHost() {
+      const hostRef = useCanvasHost()
+      useDeleteSelection()
+      return (
+        <>
+          <div ref={hostRef} data-testid="host" />
+          <input data-testid="plain-input" />
+        </>
+      )
+    }
+
+    function renderDeleteProbe(readOnly = false) {
+      return render(
+        <HotkeysProvider>
+          <CanvasProvider readOnly={readOnly}>
+            <DeleteHost />
+          </CanvasProvider>
+        </HotkeysProvider>,
+      )
+    }
+
+    it("焦点在 body（点击画布后）时按 Delete/Backspace 触发 deleteSelectedNodes", async () => {
+      const { unmount } = renderDeleteProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "Delete" })
+      expect(engine.deleteSelectedNodes).toHaveBeenCalledTimes(1)
+
+      fireEvent.keyDown(document.body, { key: "Backspace" })
+      expect(engine.deleteSelectedNodes).toHaveBeenCalledTimes(2)
+
+      unmount()
+    })
+
+    it("焦点在输入框时不触发删除", async () => {
+      const { unmount } = renderDeleteProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: "Delete" })
+      expect(engine.deleteSelectedNodes).not.toHaveBeenCalled()
+
+      unmount()
+    })
+
+    it("readOnly 画布不绑定删除快捷键", async () => {
+      const { unmount } = renderDeleteProbe(true)
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.keyDown(document.body, { key: "Delete" })
+      expect(engine.deleteSelectedNodes).not.toHaveBeenCalled()
+
+      unmount()
+    })
+
+    it("卸载后移除 document 监听器", async () => {
+      const { unmount } = renderDeleteProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      unmount()
+
+      fireEvent.keyDown(document.body, { key: "Delete" })
+      expect(engine.deleteSelectedNodes).not.toHaveBeenCalled()
+    })
+  })
+
+  describe("usePanMode", () => {
+    function PanModeProbe() {
+      const { panMode } = usePanMode()
+      const hostRef = useCanvasHost()
+      return (
+        <>
+          <div ref={hostRef} data-testid="host" />
+          <span data-testid="pan-mode">{String(panMode)}</span>
+          <input data-testid="plain-input" />
+        </>
+      )
+    }
+
+    function renderPanModeProbe() {
+      return render(
+        <HotkeysProvider>
+          <CanvasProvider>
+            <PanModeProbe />
+          </CanvasProvider>
+        </HotkeysProvider>,
+      )
+    }
+
+    it("空格按下进入 pan 模式，松开退出", async () => {
+      const { unmount } = renderPanModeProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      act(() => {
+        fireEvent.keyDown(document.body, { key: " " })
+      })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("true")
+
+      act(() => {
+        fireEvent.keyUp(document.body, { key: " " })
+      })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      unmount()
+    })
+
+    it("输入框聚焦时空格不触发 pan", async () => {
+      const { unmount } = renderPanModeProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: " " })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      unmount()
+    })
+
+    it("contenteditable 聚焦时空格不触发 pan（isTypingTarget 守卫覆盖）", async () => {
+      const { unmount } = renderPanModeProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      const editable = document.createElement("div")
+      editable.setAttribute("contenteditable", "true")
+      // jsdom 未实现 Element.isContentEditable（undefined），浏览器会因 contenteditable="true" 属性自动为 true。
+      // 用 Object.defineProperty 模拟浏览器真实行为以验证 isTypingTarget 守卫。
+      Object.defineProperty(editable, "isContentEditable", { value: true, configurable: true })
+      document.body.appendChild(editable)
+      try {
+        editable.focus()
+        fireEvent.keyDown(editable, { key: " " })
+        expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+        // keyUp 也不应触发（panMode 从未变为 true）
+        fireEvent.keyUp(editable, { key: " " })
+        expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+      } finally {
+        editable.remove()
+        if (document.activeElement instanceof HTMLElement) document.activeElement.blur()
+      }
+
+      unmount()
+    })
+  })
+
+  describe("右键与空格拖动画布", () => {
+    function PanDragProbe() {
+      const { panMode } = usePanMode()
+      return <span data-testid="pan-mode">{String(panMode)}</span>
+    }
+
+    function renderPanDragProbe() {
+      return render(
+        <HotkeysProvider>
+          <CanvasProvider>
+            <CanvasRoot>
+              <PanDragProbe />
+            </CanvasRoot>
+          </CanvasProvider>
+        </HotkeysProvider>,
+      )
+    }
+
+    it("右键按下画布空白时进入 pan 并拖动平移", async () => {
+      const { unmount } = renderPanDragProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      const hostDiv = document.querySelector("div.absolute.inset-0")
+      expect(hostDiv).toBeTruthy()
+      fireEvent.pointerDown(hostDiv!, { button: 2, clientX: 100, clientY: 100 })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("true")
+
+      fireEvent.pointerMove(document.body, { clientX: 130, clientY: 140 })
+      expect(engine.panBy).toHaveBeenCalledTimes(1)
+      expect(engine.panBy).toHaveBeenLastCalledWith(30, 40)
+
+      fireEvent.pointerUp(document.body)
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      unmount()
+    })
+
+    it("右键按下 UI 区域时不进入 pan", async () => {
+      const { unmount } = render(
+        <HotkeysProvider>
+          <CanvasProvider>
+            <CanvasRoot>
+              <PanDragProbe />
+              <div data-testid="ui" data-canvas-ui>
+                <button type="button" data-testid="ui-button">UI</button>
+              </div>
+            </CanvasRoot>
+          </CanvasProvider>
+        </HotkeysProvider>,
+      )
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      fireEvent.pointerDown(screen.getByTestId("ui-button"), { button: 2, clientX: 100, clientY: 100 })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+      expect(engine.panBy).not.toHaveBeenCalled()
+
+      fireEvent.pointerUp(document.body)
+
+      unmount()
+    })
+
+    it("空格按住 + 右键拖动进行中，只松开空格时 panMode 仍为 true 且 panning 继续", async () => {
+      const { unmount } = renderPanDragProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      const hostDiv = document.querySelector("div.absolute.inset-0")
+      expect(hostDiv).toBeTruthy()
+
+      // 按下空格 → spaceHeld=true → panMode=true
+      fireEvent.keyDown(document.body, { key: " " })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("true")
+
+      // 右键按下 → rightHeld=true（panMode 已 true，不变）
+      fireEvent.pointerDown(hostDiv!, { button: 2, clientX: 100, clientY: 100 })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("true")
+
+      // 关键边界：只松开空格（右键源仍在）
+      fireEvent.keyUp(document.body, { key: " " })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("true")
+
+      // panning 状态仍由右键源维持 → 继续平移，delta 正确
+      fireEvent.pointerMove(document.body, { clientX: 140, clientY: 160 })
+      expect(engine.panBy).toHaveBeenCalledTimes(1)
+      expect(engine.panBy).toHaveBeenLastCalledWith(40, 60)
+
+      // 松开右键 → rightHeld=false → panMode=false
+      fireEvent.pointerUp(document.body)
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      // 松开右键后再次移动不再触发 panBy
+      fireEvent.pointerMove(document.body, { clientX: 200, clientY: 200 })
+      expect(engine.panBy).toHaveBeenCalledTimes(1)
+
+      unmount()
+    })
+
+    it("空格按住 + 左键按下拖动平移画布（space-drag 主路径）", async () => {
+      const { unmount } = renderPanDragProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      const hostDiv = document.querySelector("div.absolute.inset-0")
+      expect(hostDiv).toBeTruthy()
+
+      // 按下空格 → panMode=true
+      fireEvent.keyDown(document.body, { key: " " })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("true")
+
+      // 左键按下（空格持有期间）→ space-drag effect 进入 panning
+      fireEvent.pointerDown(hostDiv!, { button: 0, clientX: 50, clientY: 50 })
+      expect(engine.panBy).not.toHaveBeenCalled()
+
+      // 拖到 (80, 90) → delta (30, 40)
+      fireEvent.pointerMove(document.body, { clientX: 80, clientY: 90 })
+      expect(engine.panBy).toHaveBeenCalledTimes(1)
+      expect(engine.panBy).toHaveBeenLastCalledWith(30, 40)
+
+      // 再拖到 (110, 130) → delta (30, 40) 相对上次 lastX/lastY
+      fireEvent.pointerMove(document.body, { clientX: 110, clientY: 130 })
+      expect(engine.panBy).toHaveBeenCalledTimes(2)
+      expect(engine.panBy).toHaveBeenLastCalledWith(30, 40)
+
+      // 松开左键 → panning=false，但 panMode 仍 true（空格仍在）
+      fireEvent.pointerUp(document.body)
+      expect(screen.getByTestId("pan-mode").textContent).toBe("true")
+
+      // 松开左键后移动不再触发 panBy
+      fireEvent.pointerMove(document.body, { clientX: 200, clientY: 200 })
+      expect(engine.panBy).toHaveBeenCalledTimes(2)
+
+      // 松开空格 → panMode=false
+      fireEvent.keyUp(document.body, { key: " " })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      unmount()
+    })
+
+    it("空格未按住时左键按下不进入 pan 拖动", async () => {
+      const { unmount } = renderPanDragProbe()
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      const hostDiv = document.querySelector("div.absolute.inset-0")
+      expect(hostDiv).toBeTruthy()
+
+      // 未按住空格 → panMode=false
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+
+      // 左键按下 → space-drag effect 的 onPointerDown 因 panMode=false 提前返回
+      fireEvent.pointerDown(hostDiv!, { button: 0, clientX: 50, clientY: 50 })
+
+      // 拖动 → 无 panBy 调用
+      fireEvent.pointerMove(document.body, { clientX: 80, clientY: 90 })
+      expect(engine.panBy).not.toHaveBeenCalled()
+
+      fireEvent.pointerUp(document.body)
+
+      unmount()
+    })
+  })
+
+  describe("canvas root contextmenu", () => {
+    it("右键画布时 contextmenu 被 preventDefault", async () => {
+      render(
+        <HotkeysProvider>
+          <CanvasProvider>
+            <CanvasRoot />
+          </CanvasProvider>
+        </HotkeysProvider>,
+      )
+
+      await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+      const hostDiv = document.querySelector("div.absolute.inset-0")
+      expect(hostDiv).toBeTruthy()
+      const event = new MouseEvent("contextmenu", { bubbles: true, cancelable: true })
+      hostDiv!.dispatchEvent(event)
+      expect(event.defaultPrevented).toBe(true)
+    })
+  })
+})