@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/design/canvas/panels/toolbar.tsx

@@ -16,6 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useEffect, useRef, useState, type ComponentType } from "react"
+import { useHotkeys } from "@tanstack/react-hotkeys"
 import {
   ArrowRight,
   ChevronDown,
@@ -148,26 +149,19 @@ export function useCanvasDrawing(shapeVariant?: string | null) {
     setTool(id)
   }
 
-  useEffect(() => {
-    if (!enabled) return
-    const hotkeyMap = new Map<string, ToolId>()
-    for (const definition of TOOL_DEFINITIONS) {
-      const hotkey = definition.hotkey
-      if (!hotkey) continue
-      hotkeyMap.set(hotkey.toLowerCase(), definition.id)
-    }
-    const handler = (e: KeyboardEvent) => {
-      if (isTypingTarget(e.target as HTMLElement)) return
-      if (e.ctrlKey || e.metaKey || e.altKey) return
-      const id = hotkeyMap.get(e.key.toLowerCase())
-      if (id) {
-        e.preventDefault()
-        selectTool(id)
-      }
-    }
-    document.addEventListener("keydown", handler)
-    return () => document.removeEventListener("keydown", handler)
-  }, [enabled])
+  // 收编手写 keydown（审计「canvas 工具单键」项）：TOOL_DEFINITIONS 单键 →
+  // useHotkeys 数组注册（动态长度安全，不违反 hooks 规则）。enabled 门控、
+  // 输入框守卫（ignoreInputs 等价旧 isTypingTarget 判断，范围更宽更安全）、
+  // preventDefault 均由官方通道承担；无修饰键 chord 与旧「仅拦 ctrl/meta/alt、
+  // 放行 shift」的差异是官方精确匹配修饰键（shift+单键不再触发，Figma 同款语义）
+  useHotkeys(
+    TOOL_DEFINITIONS.flatMap((definition) =>
+      definition.hotkey
+        ? [{ hotkey: definition.hotkey, callback: () => selectTool(definition.id) }]
+        : [],
+    ),
+    { enabled, ignoreInputs: true, preventDefault: true },
+  )
 
   useEffect(() => {
     if (!enabled || tool === "select") return
@@ -216,7 +210,10 @@ export function useCanvasDrawing(shapeVariant?: string | null) {
       window.addEventListener("pointerdown", onPointerDown, true)
       window.addEventListener("pointermove", onPointerMove)
       window.addEventListener("dblclick", onDoubleClick)
-      // keydown 捕获相：同钢笔分支，先于 document 冒泡相的删除监听
+      // keydown 捕获相：同钢笔分支，先于 document 冒泡相的删除监听。
+      // 豁免收编（audit 2026-10-31）：捕获相时序敏感——绘制态的删除键必须先于
+      // useDeleteSelection（useHotkeys，document 冒泡相）拦截，官方 API 无
+      // 「绘制态条件捕获相」的表达，保持手写监听
       window.addEventListener("keydown", onKeyDown, true)
       return () => {
         window.removeEventListener("pointerdown", onPointerDown, true)
@@ -272,7 +269,9 @@ export function useCanvasDrawing(shapeVariant?: string | null) {
       window.addEventListener("dblclick", onDoubleClick)
       // keydown 必须捕获相：useDeleteSelection 在 document 冒泡相（冒泡顺序
       // document 先于 window），冒泡相注册的 stopPropagation 来不及拦截——
-      // 「选中 A → 切钢笔 → 绘制中按 Backspace」会同时删 A 并回退锚点
+      // 「选中 A → 切钢笔 → 绘制中按 Backspace」会同时删 A 并回退锚点。
+      // 豁免收编（audit 2026-10-31）：捕获相时序敏感，官方 API 无
+      // 「绘制态条件捕获相」的表达，保持手写监听
       window.addEventListener("keydown", onKeyDown, true)
       return () => {
         window.removeEventListener("pointerdown", onPointerDown, true)

package/src/components/design/canvas/react/__tests__/canvas-context-load-echo.test.tsx

@@ -0,0 +1,199 @@
+// @vitest-environment jsdom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * CanvasProvider loadDoc 回显豁免回归（任务 2 审查修复轮 2 / 缺陷③）：
+ *
+ * engine.loadDoc → notifyDocChange → pushDoc → 父层 onDocChange（即
+ * useDesignAutoSave.handleDocChange → setCanvasDirty(true)）——打开/切页后
+ * ~2s 内 canvasDirty 幻影 true，未保存 guard 误拦（旧 beforeunload 同样误报）。
+ * 修复：pushDoc 在 loadDoc 同步执行窗口内只刷新 store 快照，不通知 React
+ * 父层；窗口 = loadDoc 调用栈，用户事件无法插入（无吞真实编辑的竞态）。
+ *
+ * 断言落到「父层通知 → handleDocChange → canvasDirty」链（真实
+ * useDesignAutoSave + 真实 CanvasProvider 接线，LeaferEngine 以替身驱动）。
+ * 引擎本体在 jsdom 不可真实驱动（Leafer WebGL），按审查许可取 notify 层
+ * 断言——取舍：不覆盖引擎内部 applyScene 的通知次数，但豁免按「同步窗口」
+ * 而非一次性开关实现，窗口内任意次回显通知都被吞掉，不依赖次数假设。
+ */
+
+import { describe, expect, it, vi, beforeEach } from "vitest"
+import { renderHook, act } from "@testing-library/react"
+import { render } from "@testing-library/react"
+import { useContext, useState } from "react"
+
+const engineSlots = vi.hoisted(() => ({
+  create: vi.fn(),
+}))
+
+vi.mock("@/design-engine/engine/app", () => ({
+  LeaferEngine: {
+    create: (opts: unknown) => engineSlots.create(opts),
+  },
+}))
+
+import { CanvasContext, CanvasProvider } from "../canvas-context"
+import { LeaferEngine } from "@/design-engine/engine/app"
+import { useDesignAutoSave } from "@/components/design/editor/layout/hooks/use-design-auto-save"
+import { createEmptyDoc, createBoardNode, type SceneDocument } from "@/components/design/canvas/document/types"
+import type { DocContent } from "@/components/design/editor/layout/design-editor-doc-utils"
+import { updateDesignPageFn } from "@/server/serverFns/design/pages"
+
+vi.mock("@/server/serverFns/design/pages", () => ({
+  updateDesignPageFn: vi.fn(async () => ({ id: "p1" })),
+}))
+
+type HookArgs = Parameters<typeof useDesignAutoSave>[0]
+
+const emptyScene: SceneDocument = createEmptyDoc("desktop")
+
+function userScene(): SceneDocument {
+  return {
+    version: 1,
+    meta: { device: "desktop" },
+    nodes: [
+      createBoardNode("desktop"),
+      {
+        id: "n_1",
+        kind: "shape",
+        type: "rect",
+        parentId: "board",
+        x: 10,
+        y: 10,
+        width: 40,
+        height: 40,
+        style: {},
+        props: {},
+      },
+    ],
+  } as unknown as SceneDocument
+}
+
+function baseArgs(over: Partial<HookArgs> = {}): HookArgs {
+  return {
+    activePageId: "page_1",
+    sceneDoc: emptyScene,
+    setSceneDoc: vi.fn(),
+    docContent: { html: "", markdown: "" },
+    setDocContent: vi.fn(),
+    canvasDirty: false,
+    setCanvasDirty: vi.fn(),
+    docDirty: false,
+    setDocDirty: vi.fn(),
+    isPreviewingRef: { current: false },
+    canvasLoadedRef: { current: true },
+    lastLoadedDocRef: { current: null },
+    timezone: "Asia/Shanghai",
+    setCanvasAutoSaveTime: vi.fn(),
+    setDocAutoSaveTime: vi.fn(),
+    docSaveFnRef: { current: async () => {} },
+    docDebouncer: { maybeExecute: vi.fn(), cancel: vi.fn() },
+    ...over,
+  }
+}
+
+type FakeEngine = {
+  mount: ReturnType<typeof vi.fn>
+  dispose: ReturnType<typeof vi.fn>
+  remount: ReturnType<typeof vi.fn>
+  setKeyEventEnabled: ReturnType<typeof vi.fn>
+  getZoom: () => number
+  history: { canUndo: boolean; canRedo: boolean }
+  onDocChange: (cb: (doc: SceneDocument) => void) => () => void
+  onSelectionChange: (cb: unknown) => () => void
+  onToolChange: (cb: unknown) => () => void
+  loadDoc: (doc: SceneDocument) => void
+}
+
+function installFakeEngine() {
+  let docListener: ((doc: SceneDocument) => void) | null = null
+  const loadDocSpy = vi.fn()
+  const fakeEngine = {
+    mount: vi.fn(),
+    dispose: vi.fn(),
+    remount: vi.fn(),
+    setKeyEventEnabled: vi.fn(),
+    getZoom: () => 1,
+    history: { canUndo: false, canRedo: false },
+    onDocChange: vi.fn((cb: (doc: SceneDocument) => void) => {
+      docListener = cb
+      return () => {}
+    }),
+    onSelectionChange: vi.fn(() => () => {}),
+    onToolChange: vi.fn(() => () => {}),
+    // 真实引擎 loadDoc 末尾同步 notifyDocChange（engine-doc.ts:164）——回显
+    loadDoc: vi.fn((doc: SceneDocument) => {
+      loadDocSpy(doc)
+      docListener?.(doc)
+    }),
+  }
+  engineSlots.create.mockResolvedValue(fakeEngine)
+  return { fakeEngine: fakeEngine as unknown as LeaferEngine & FakeEngine, notifyDoc: (doc: SceneDocument) => docListener?.(doc), loadDocSpy }
+}
+
+/** 把画布 host 挂进 provider（真实挂载链：attachHost → hostRef → create effect） */
+function HostMount() {
+  const canvas = useContext(CanvasContext)
+  return <div ref={(node) => canvas?.attachHost(node)} data-testid="canvas-host" />
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.mocked(updateDesignPageFn).mockClear()
+})
+
+describe("CanvasProvider loadDoc 回显豁免（审查修复③）", () => {
+  it("loadDoc 回显（挂载 + 切页）不置 canvasDirty；真实用户编辑同步置 dirty", async () => {
+    const { notifyDoc, loadDocSpy } = installFakeEngine()
+
+    // hook 持真实 state（dirty 断言目标），非可 mock 的 setter
+    const { result } = renderHook(() => {
+      const [canvasDirty, setCanvasDirty] = useState(false)
+      const [docDirty, setDocDirty] = useState(false)
+      const [sceneDoc, setSceneDoc] = useState(emptyScene)
+      const [docContent, setDocContent] = useState<DocContent>({ html: "", markdown: "" })
+      return useDesignAutoSave({
+        ...baseArgs(),
+        sceneDoc,
+        setSceneDoc,
+        docContent,
+        setDocContent,
+        canvasDirty,
+        setCanvasDirty,
+        docDirty,
+        setDocDirty,
+      })
+    })
+
+    const view = render(
+      <CanvasProvider initialDoc={emptyScene} onDocChange={(doc) => result.current.handleDocChange(doc)}>
+        <HostMount />
+      </CanvasProvider>,
+    )
+    // flush 引擎 create promise → mount → loadDoc(挂载回显)
+    await act(async () => {})
+
+    expect(loadDocSpy).toHaveBeenCalledTimes(1)
+    // 关键断言①：挂载 loadDoc 回显未置 dirty（修复前此处 true——幻影 dirty）
+    expect(result.current.canvasDirty).toBe(false)
+
+    // 切页：initialDoc 换新 → engine.loadDoc(新页) → 回显
+    await act(async () => {
+      view.rerender(
+        <CanvasProvider initialDoc={userScene()} onDocChange={(doc) => result.current.handleDocChange(doc)}>
+          <HostMount />
+        </CanvasProvider>,
+      )
+    })
+    expect(loadDocSpy).toHaveBeenCalledTimes(2)
+    // 关键断言②：切页 loadDoc 回显同样不置 dirty
+    expect(result.current.canvasDirty).toBe(false)
+
+    // 真实用户编辑一笔（引擎编辑路径：load 窗口外的 docChanged notify）
+    await act(async () => {
+      notifyDoc(userScene())
+    })
+    // 关键断言③：真实编辑同步置 dirty（豁免不吞编辑）
+    expect(result.current.canvasDirty).toBe(true)
+  })
+})

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

@@ -789,7 +789,16 @@ describe("canvas hooks", () => {
       await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
       expect(screen.getByTestId("pan-mode").textContent).toBe("false")
 
-      fireEvent.keyDown(screen.getByTestId("plain-input"), { key: " " })
+      // 真实浏览器中 keydown 恒派发给聚焦元素（e.target === activeElement）；
+      // 收编后的输入框门控走 typingFocus（focusin/focusout 事实源），故先
+      // 聚焦输入框再派发空格键
+      const input = screen.getByTestId("plain-input")
+      act(() => {
+        input.focus()
+      })
+      fireEvent.keyDown(input, { key: " " })
+      expect(screen.getByTestId("pan-mode").textContent).toBe("false")
+      fireEvent.keyUp(input, { key: " " })
       expect(screen.getByTestId("pan-mode").textContent).toBe("false")
 
       unmount()
@@ -808,7 +817,10 @@ describe("canvas hooks", () => {
       Object.defineProperty(editable, "isContentEditable", { value: true, configurable: true })
       document.body.appendChild(editable)
       try {
-        editable.focus()
+        // focus/blur 触发 focusin/focusout → CanvasProvider typingFocus setState，须包 act
+        act(() => {
+          editable.focus()
+        })
         fireEvent.keyDown(editable, { key: " " })
         expect(screen.getByTestId("pan-mode").textContent).toBe("false")
         // keyUp 也不应触发（panMode 从未变为 true）
@@ -816,7 +828,9 @@ describe("canvas hooks", () => {
         expect(screen.getByTestId("pan-mode").textContent).toBe("false")
       } finally {
         editable.remove()
-        if (document.activeElement instanceof HTMLElement) document.activeElement.blur()
+        act(() => {
+          if (document.activeElement instanceof HTMLElement) document.activeElement.blur()
+        })
       }
 
       unmount()

package/src/components/design/canvas/react/canvas-context.tsx

@@ -17,12 +17,16 @@
 
 import {
   createContext,
+  useCallback,
   useEffect,
   useRef,
+  useState,
   type ReactNode,
   type RefObject,
 } from "react"
 
+import { useHotkey, useKeyHold } from "@tanstack/react-hotkeys"
+
 import { isTypingTarget } from "../tools/dom"
 import { LeaferEngine } from "@/design-engine/engine/app"
 import { createEmptyDoc, type DeviceType, type SceneDocument, type ToolId } from "../document/types"
@@ -116,6 +120,21 @@ export function CanvasProvider({
   const engineRef = useRef<LeaferEngine | null>(null)
   const lastEmittedDocRef = useRef<SceneDocument | null>(null)
   const selectionNotifyRafRef = useRef<number | null>(null)
+  // loadDoc 回显豁免（任务 2 审查修复③）：loadDoc 末尾同步 notifyDocChange
+  // → pushDoc → 父层 onDocChange → handleDocChange 误置 canvasDirty（打开/
+  // 切页后幻影 dirty，未保存 guard 误拦）。窗口 = loadDoc 同步调用栈（用户
+  // 事件无法插入，无吞真实编辑竞态）；窗口内 pushDoc 仍刷新 store 快照
+  //（lastEmittedDocRef 供 initialDoc effect 判等、doc 供画布消费），仅跳过
+  // 父层通知。trackChanges/编辑路径不受影响（发生在窗口外，照常同步置 dirty）。
+  const loadEchoGateRef = useRef(false)
+  const loadDocSilently = useCallback((eng: LeaferEngine, doc: SceneDocument): void => {
+    loadEchoGateRef.current = true
+    try {
+      eng.loadDoc(doc)
+    } finally {
+      loadEchoGateRef.current = false
+    }
+  }, [])
 
   flagsRef.current = { readOnly }
   callbacksRef.current = { initialDoc, onDocChange }
@@ -182,7 +201,10 @@ export function CanvasProvider({
         lastEmittedDocRef.current = doc
         state.doc = doc
         if (doc.meta?.device) state.device = doc.meta.device
-        callbacksRef.current.onDocChange?.(doc)
+        // loadDoc 回显窗口内只刷新快照、不通知父层（注释见 loadEchoGateRef）
+        if (!loadEchoGateRef.current) {
+          callbacksRef.current.onDocChange?.(doc)
+        }
         refreshMetrics()
         rebuild()
       },
@@ -248,7 +270,7 @@ export function CanvasProvider({
         created.onToolChange(store.pushTool),
       )
       const initial = callbacksRef.current.initialDoc
-      if (initial) created.loadDoc(initial)
+      if (initial) loadDocSilently(created, initial)
       store.attach(created)
       // 诊断埋点：dev 环境暴露引擎引用，供真实页面逐层调试命中/选中链路
       if (import.meta.env.DEV) {
@@ -298,30 +320,24 @@ export function CanvasProvider({
     const eng = engineRef.current
     if (!eng || !initialDoc) return
     if (initialDoc === lastEmittedDocRef.current) return
-    eng.loadDoc(initialDoc)
-  }, [initialDoc])
+    loadDocSilently(eng, initialDoc)
+  }, [initialDoc, loadDocSilently])
 
-  // 空格键：按下进入 pan 模式（手型光标 + 左键可拖动），松开退出。
-  // 输入框/textarea/contenteditable 聚焦时不响应（否则会打断用户输入）。
-  // 与右键拖动并列：任一持有时 panMode 即为 true。
+  // 空格键（收编手写 keydown/keyup，审计「空格 pan」项）：按住进入 pan 模式
+  //（手型光标 + 左键可拖动），松开退出；与右键拖动并列，任一持有 panMode 即 true。
+  // hold 状态来自官方 KeyStateTracker（useKeyHold("Space")——tracker 归一化
+  // " "→"Space"，勿传字面空格），窗口失焦自动清位（旧实现 keyup 丢失会卡 pan）。
+  // tracker 无输入框概念，输入框聚焦不响应由下方 typingFocus 门控承担。
+  // 官方 API 缺口：useKeyHold 不做 preventDefault，空格的页面滚动/焦点控件
+  // 激活抑制由并行 "Space" chord 注册（preventDefault）承担；官方对聚焦
+  // button/link 的空格激活按 ignoreInputs 跳过（无障碍语义，旧实现一律拦死，
+  // 此处为对齐官方语义的有意放宽）。
+  const spaceHeld = useKeyHold("Space")
+  const [typingFocus, setTypingFocus] = useState(false)
   useEffect(() => {
-    const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key !== " ") return
-      if (isTypingTarget(e.target as HTMLElement)) return
-      store.setSpaceHeld(true)
-      e.preventDefault()
-    }
-    const onKeyUp = (e: KeyboardEvent) => {
-      if (e.key !== " ") return
-      store.setSpaceHeld(false)
-    }
-    document.addEventListener("keydown", onKeyDown)
-    document.addEventListener("keyup", onKeyUp)
-    return () => {
-      document.removeEventListener("keydown", onKeyDown)
-      document.removeEventListener("keyup", onKeyUp)
-    }
-  }, [store])
+    store.setSpaceHeld(spaceHeld && !typingFocus)
+  }, [spaceHeld, typingFocus, store])
+  useHotkey("Space", () => {}, { ignoreInputs: true, preventDefault: true })
 
   // 输入框聚焦时关闭 leafer-editor 的键盘监听（leafer-editor 官方方案）。
   // 从 leafer-editor 2.3.0 源码定位：
@@ -339,12 +355,17 @@ export function CanvasProvider({
       return isTypingTarget(el as HTMLElement | null)
     }
     const onDocFocus = (): void => {
-      engineRef.current?.setKeyEventEnabled(!isInsideTyping())
+      const inside = isInsideTyping()
+      // 焦点位置提升为 React 状态：空格 pan 的 typingFocus 门控复用同一事实源
+      setTypingFocus(inside)
+      engineRef.current?.setKeyEventEnabled(!inside)
     }
     document.addEventListener("focusin", onDocFocus)
     document.addEventListener("focusout", onDocFocus)
     // 初始状态同步一次（防止 mount 时焦点已在输入框）
-    engineRef.current?.setKeyEventEnabled(!isInsideTyping())
+    const initialInside = isInsideTyping()
+    setTypingFocus(initialInside)
+    engineRef.current?.setKeyEventEnabled(!initialInside)
     return () => {
       document.removeEventListener("focusin", onDocFocus)
       document.removeEventListener("focusout", onDocFocus)

package/src/components/design/canvas/react/hooks.ts

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useCallback, useEffect, type RefObject } from "react"
-import { useHotkey } from "@tanstack/react-hotkeys"
+import { useHotkey, useHotkeys } from "@tanstack/react-hotkeys"
 
 import { toast } from "@/components/ui/toast"
 import { m } from "@/paraglide/messages.js"
@@ -158,19 +158,17 @@ export function useDeleteSelection() {
   const engine = snapshot.engine
   const enabled = Boolean(engine) && !snapshot.readOnly
 
-  useEffect(() => {
-    if (!enabled || !engine) return
-    const handler = (e: KeyboardEvent) => {
-      if (e.key !== "Delete" && e.key !== "Backspace") return
-      if (e.ctrlKey || e.metaKey || e.altKey) return
-      const target = e.target as HTMLElement
-      if (isTypingTarget(target)) return
-      engine.deleteSelectedNodes()
-      e.preventDefault()
-    }
-    document.addEventListener("keydown", handler)
-    return () => document.removeEventListener("keydown", handler)
-  }, [enabled, engine])
+  // 收编手写 keydown（审计第 4 处）：Delete/Backspace 删除选中，改官方
+  // useHotkeys 双 chord——enabled 门控、ignoreInputs 输入框守卫、preventDefault
+  // 均由官方通道承担。仍为 document 冒泡相（useHotkeys 默认 target=document），
+  // toolbar 绘制中的捕获相 stopPropagation 拦截先于本注册生效，时序与旧实现一致
+  useHotkeys(
+    [
+      { hotkey: "Delete", callback: () => engine?.deleteSelectedNodes() },
+      { hotkey: "Backspace", callback: () => engine?.deleteSelectedNodes() },
+    ],
+    { enabled, ignoreInputs: true, preventDefault: true },
+  )
 }
 
 // 编组/解组快捷键（FS-4.2）：Mod+G 建组、Shift+Mod+G 解组；
@@ -252,34 +250,39 @@ export function useEditCommands(): void {
 }
 
 // 画布剪贴板快捷键：mod+A 全选 / mod+X 剪切 / mod+C 复制 / mod+V 粘贴；
-// 输入框聚焦时不拦截（属文本编辑器自身行为）
+// 输入框聚焦时不拦截（属文本编辑器自身行为）。
+// 收编手写 keydown（审计「Mod+C」项）：改官方 useHotkeys 四 chord 注册，
+// enabled 门控、ignoreInputs 守卫、preventDefault 拦截浏览器默认行为均由
+// 官方通道承担
 export function useCanvasClipboard(): void {
   const snapshot = useCanvasSnapshot()
   const engine = snapshot.engine
   const enabled = Boolean(engine) && !snapshot.readOnly
 
-  useEffect(() => {
-    if (!enabled || !engine) return
-    const handler = (e: KeyboardEvent) => {
-      if (!(e.metaKey || e.ctrlKey) || e.altKey) return
-      const key = e.key.toLowerCase()
-      if (key !== "a" && key !== "x" && key !== "c" && key !== "v") return
-      const target = e.target as HTMLElement
-      if (isTypingTarget(target)) return
-      if (key === "a") engine.selectAll()
-      else if (key === "x") engine.cutSelection()
-      else if (key === "c") engine.copySelection()
-      else engine.pasteClipboard()
-      e.preventDefault()
-    }
-    document.addEventListener("keydown", handler)
-    return () => document.removeEventListener("keydown", handler)
-  }, [enabled, engine])
+  const clipboardEdit = useCallback(
+    (op: "selectAll" | "cutSelection" | "copySelection" | "pasteClipboard") => {
+      engine?.[op]()
+    },
+    [engine],
+  )
+
+  useHotkeys(
+    [
+      { hotkey: "Mod+A", callback: () => clipboardEdit("selectAll") },
+      { hotkey: "Mod+X", callback: () => clipboardEdit("cutSelection") },
+      { hotkey: "Mod+C", callback: () => clipboardEdit("copySelection") },
+      { hotkey: "Mod+V", callback: () => clipboardEdit("pasteClipboard") },
+    ],
+    { enabled, ignoreInputs: true, preventDefault: true },
+  )
 }
 
 // Esc 逐级取消（Figma/Sketch 惯例）：路径锚点编辑 → 退出编辑；绘制工具 →
 // 退回选择工具；选择模式 → 清空选中（全选/多选/单选一律取消）。钢笔绘制中
-// 的 Esc 由 toolbar 的捕获相处理（结束路径 + 退工具），此处冒泡相同事件幂等
+// 的 Esc 由 toolbar 的捕获相处理（结束路径 + 退工具），此处冒泡相同事件幂等。
+// 豁免收编（audit 2026-10-31「捕获相时序敏感」类）：三态分支依赖 engine/工具
+// 状态的判断顺序，且收编即与全局 close-panel（Escape）形成同 chord 运行时
+// 注册冲突（findHotkeyConflicts 会告警）——保持手写监听
 export function useEscapeTool() {
   const { tool, setTool } = useTool()
   const engine = useCanvasSnapshotOptional()?.engine ?? null
@@ -309,7 +312,9 @@ export function useEscapeTool() {
   }, [tool, setTool, engine])
 }
 
-// Enter 进入/退出路径锚点编辑（单选 path/pen-path 时；Sketch 惯例）
+// Enter 进入/退出路径锚点编辑（单选 path/pen-path 时；Sketch 惯例）。
+// 豁免收编：Enter 是输入提交语义主键（表单/对话框/测试清单 case-checklist
+// 同用 Enter），收编即扩大同 chord 运行时冲突面，收益低——保持手写监听
 export function usePathEditHotkey() {
   const engine = useCanvasSnapshotOptional()?.engine ?? null
   const selection = useCanvasSnapshotOptional()?.selection ?? []

package/src/components/design/editor/layout/__tests__/collab-param-wiring.test.tsx

@@ -53,6 +53,7 @@ vi.mock('@/components/design/canvas/plugins/presence/presence-layer', () => ({
 
 vi.mock('@tanstack/react-hotkeys', () => ({
   useHotkey: () => {},
+  useAppHotkeys: () => appHotkeys,
 }))
 
 vi.mock('@/components/design/editor/layout/design-left-sidebar', () => ({
@@ -100,7 +101,23 @@ vi.mock('@/server/serverFns/design/designs', () => ({
   updateDesignFn: vi.fn(),
 }))
 
+// DesignEditorLayout 挂载 use-unsaved-guard（任务 2）：无 RouterProvider 的
+// 单测环境把 useBlocker 替换为 idle resolver（真实 blocker 注册属 router
+// 集成行为，见 hooks/__tests__/use-unsaved-guard.test.tsx）
+vi.mock('@tanstack/react-router', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useBlocker: () => ({
+    status: 'idle' as const,
+    current: undefined,
+    next: undefined,
+    action: undefined,
+    proceed: undefined,
+    reset: undefined,
+  }),
+}))
+
 import { DesignEditorLayout } from '../design-editor-layout'
+import { appHotkeys } from '@/lib/hotkeys/registry'
 import type { Design } from '@allbluecn/kernel'
 
 const designFixture = {

package/src/components/design/editor/layout/__tests__/context-menu.test.tsx

@@ -28,6 +28,7 @@ import { describe, expect, it, vi, beforeEach } from "vitest";
 import { render, fireEvent, waitFor, screen } from "@testing-library/react";
 
 import { CanvasContextMenu } from "../context-menu";
+import { appHotkeys } from "@/lib/hotkeys/registry";
 import { buildContextMenuItems, type ContextMenuItem } from "../context-menu-items";
 import { DesignEditorLayout } from "../design-editor-layout";
 import type { Design } from "@allbluecn/kernel";
@@ -105,7 +106,22 @@ vi.mock("@/server/serverFns/design/pages", () => ({
 vi.mock("@/server/serverFns/design/designs", () => ({
   updateDesignFn: vi.fn(() => Promise.resolve({})),
 }));
-vi.mock("@tanstack/react-hotkeys", () => ({ useHotkey: () => {} }));
+vi.mock("@tanstack/react-hotkeys", () => ({ useHotkey: () => {}, useAppHotkeys: () => appHotkeys }));
+
+// DesignEditorLayout 挂载 use-unsaved-guard（任务 2）：无 RouterProvider 的
+// 单测环境把 useBlocker 替换为 idle resolver（真实 blocker 注册属 router
+// 集成行为，见 hooks/__tests__/use-unsaved-guard.test.tsx）
+vi.mock("@tanstack/react-router", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useBlocker: () => ({
+    status: "idle" as const,
+    current: undefined,
+    next: undefined,
+    action: undefined,
+    proceed: undefined,
+    reset: undefined,
+  }),
+}));
 
 
 describe("CanvasContextMenu 组件", () => {

package/src/components/design/editor/layout/__tests__/no-page-save-toast.test.tsx

@@ -21,6 +21,22 @@ vi.mock("@tanstack/react-hotkeys", () => ({
   useHotkey: (_key: string, handler: () => void) => {
     hotkeyHandler = handler;
   },
+  useAppHotkeys: () => appHotkeys,
+}));
+
+// DesignEditorLayout 挂载 use-unsaved-guard（任务 2）：无 RouterProvider 的
+// 单测环境把 useBlocker 替换为 idle resolver（真实 blocker 注册属 router
+// 集成行为，见 hooks/__tests__/use-unsaved-guard.test.tsx）
+vi.mock("@tanstack/react-router", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useBlocker: () => ({
+    status: "idle" as const,
+    current: undefined,
+    next: undefined,
+    action: undefined,
+    proceed: undefined,
+    reset: undefined,
+  }),
 }));
 
 // 单机模式前提钉住（任务 30 装配后布局按 isCollabEnabled 门控保存让位）：
@@ -99,6 +115,7 @@ import { toast } from "@/components/ui/toast";
 import { getDesignPageFn, updateDesignPageFn } from "@/server/serverFns/design/pages";
 import { m } from "@/paraglide/messages.js";
 import { DesignEditorLayout } from "../design-editor-layout";
+import { appHotkeys } from "@/lib/hotkeys/registry";
 import type { Design } from "@allbluecn/kernel";
 
 const designFixture = {