@tnotesjs/ui 0.1.4 → 0.2.0

package/src/excalidraw/editorHost.ts

@@ -0,0 +1,110 @@
+/**
+ * Excalidraw 编辑器宿主（Desk 专用）。
+ *
+ * 关键行为：
+ * - 稳定实例：切换卡片/全屏/标签页时只**移动承载 DOM 节点**，不重建 React 树，
+ *   否则场景与原生撤销历史都会丢（E0 已实证）
+ * - 承载位置交接后必须重建键盘焦点：E0 实测「blur 当前焦点 + 给交互画布加
+ *   tabindex + canvas.focus()」是唯一有效路径；不重建则快捷键（撤销等）失效
+ * - 内容变化只在需要持久化时回调（宿主用 persistedSceneSignature 过滤）
+ */
+import { createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { Excalidraw, serializeAsJSON } from '@excalidraw/excalidraw'
+// 官方样式表必须由宿主 import 一次：缺它的容器高度会算成 2^24，画布不可见且点不到
+import '@excalidraw/excalidraw/index.css'
+
+import { setExcalidrawAssetPath } from './fonts'
+import { restoreCanvasKeyboardFocusWhenReady } from './focus'
+
+import type {
+  ExcalidrawImperativeAPI,
+  ExcalidrawInitialDataState
+} from '@excalidraw/excalidraw/types'
+
+export interface MountExcalidrawHostOptions {
+  host: HTMLElement
+  /** 初始磁盘内容（唯一真相源） */
+  content: string
+  theme: 'light' | 'dark'
+  /** 本地字体基址；离线必须设置 */
+  fontBase?: string
+  /**
+   * 场景序列化回调。
+   *
+   * 注意：Excalidraw 载入磁盘场景时会补齐自己的字段（groupIds/roundness/gridSize…），
+   * 挂载后的第一次回调就是这份「规范化」结果，**不是用户编辑**。调用方要把它当作
+   * 新的持久化基线（`session.adopt`），否则只读打开也会回写一份规范化副本。
+   */
+  onChange: (content: string) => void
+  onReady?: (api: ExcalidrawImperativeAPI) => void
+}
+
+export interface ExcalidrawHostHandle {
+  /** 只移动承载节点，保持实例与撤销历史 */
+  transferTo(target: HTMLElement): void
+  /** 重建键盘焦点（交接后必须调用） */
+  focus(): void
+  /** 跟随宿主主题切换；不重建实例，只改 appState.theme */
+  setTheme(theme: 'light' | 'dark'): void
+  getApi(): ExcalidrawImperativeAPI | null
+  destroy(): void
+}
+
+/** 磁盘 JSON 的形状由 kb 层保证；这里只做最必要的兜底。 */
+function parseInitial(content: string): ExcalidrawInitialDataState {
+  try {
+    const parsed = JSON.parse(content) as ExcalidrawInitialDataState
+    return {
+      elements: Array.isArray(parsed.elements) ? parsed.elements : [],
+      appState: parsed.appState ?? {},
+      files: parsed.files ?? {}
+    }
+  } catch {
+    return { elements: [], appState: {}, files: {} }
+  }
+}
+
+export { restoreCanvasKeyboardFocus, restoreCanvasKeyboardFocusWhenReady } from './focus'
+
+export function mountExcalidrawHost(options: MountExcalidrawHostOptions): ExcalidrawHostHandle {
+  if (options.fontBase) setExcalidrawAssetPath(options.fontBase)
+  const initial = parseInitial(options.content)
+  let api: ExcalidrawImperativeAPI | null = null
+  const appState = {
+    ...initial.appState,
+    theme: options.theme,
+    // 不做「整篇替换」的展示状态，交给 Excalidraw 自己维护
+    collaborators: new Map()
+  }
+
+  const root: Root = createRoot(options.host)
+  root.render(
+    createElement(Excalidraw, {
+      initialData: { elements: initial.elements, appState, files: initial.files },
+      theme: options.theme,
+      excalidrawAPI: (next: ExcalidrawImperativeAPI) => {
+        api = next
+        options.onReady?.(next)
+      },
+      onChange: (elements, nextAppState, files) => {
+        options.onChange(serializeAsJSON(elements, nextAppState, files, 'local'))
+      }
+    })
+  )
+
+  return {
+    transferTo: (target: HTMLElement) => {
+      if (options.host.parentElement !== target) target.append(options.host)
+      // 换了承载容器：画布尺寸与命中区域都要重算，否则指针事件落在旧几何上
+      api?.refresh?.()
+      restoreCanvasKeyboardFocusWhenReady(options.host)
+    },
+    focus: () => restoreCanvasKeyboardFocusWhenReady(options.host),
+    setTheme: (theme: 'light' | 'dark') => {
+      api?.updateScene({ appState: { theme } })
+    },
+    getApi: () => api,
+    destroy: () => root.unmount()
+  }
+}

package/src/excalidraw/editorSession.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { createExcalidrawSession, persistedSceneSignature } from './editorSession'
+
+const scene = (overrides: Record<string, unknown> = {}) =>
+  JSON.stringify({
+    type: 'excalidraw',
+    elements: [{ id: 'rect-1' }],
+    appState: { viewBackgroundColor: '#ffffff' },
+    files: {},
+    ...overrides
+  })
+
+/** 只改展示状态：appState 必须与基础场景合并，否则是「删掉了背景色」这种真变化 */
+const viewChanged = (appState: Record<string, unknown>) =>
+  scene({ appState: { viewBackgroundColor: '#ffffff', ...appState } })
+
+function setup(options: { save?: ReturnType<typeof vi.fn>; initial?: string } = {}) {
+  const save =
+    options.save ??
+    vi.fn(async ({ content }: { content: string }) => ({
+      ok: true as const,
+      revision: `rev-${content.length}-${Math.random().toString(16).slice(2, 6)}`
+    }))
+  const session = createExcalidrawSession({
+    initialContent: options.initial ?? scene(),
+    initialRevision: 'rev-0',
+    save: save as never,
+    debounceMs: 200,
+    maxWaitMs: 1000
+  })
+  return { session, save }
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('画布编辑会话', () => {
+  it('展示状态变化（平移/缩放/选中）不触发写盘', async () => {
+    const { session, save } = setup()
+    session.update(viewChanged({ scrollX: 120, zoom: { value: 2 } }))
+    await vi.advanceTimersByTimeAsync(1500)
+
+    expect(save).not.toHaveBeenCalled()
+    expect(session.state.value).toBe('idle')
+  })
+
+  it('内容变化防抖 200ms 后写入一次', async () => {
+    const { session, save } = setup()
+    session.update(scene({ elements: [{ id: 'rect-1' }, { id: 'rect-2' }] }))
+    expect(session.state.value).toBe('pending')
+
+    await vi.advanceTimersByTimeAsync(199)
+    expect(save).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(1)
+
+    expect(save).toHaveBeenCalledTimes(1)
+    expect(session.state.value).toBe('idle')
+  })
+
+  it('连续变化时最大等待 1s 强制落盘，不会被防抖无限推迟', async () => {
+    const { session, save } = setup()
+    for (let index = 0; index < 12; index += 1) {
+      session.update(
+        scene({ elements: Array.from({ length: index + 2 }, (_, i) => ({ id: `r${i}` })) })
+      )
+      await vi.advanceTimersByTimeAsync(100)
+    }
+
+    expect(save).toHaveBeenCalled()
+  })
+
+  it('写入串行：进行中的写入不会被并发覆盖，且旧完成回调不清掉新状态', async () => {
+    const pending: Array<(value: { ok: true; revision: string }) => void> = []
+    const save = vi.fn(
+      () =>
+        new Promise<{ ok: true; revision: string }>((resolve) => {
+          pending.push(resolve)
+        })
+    )
+    const { session } = setup({ save: save as never })
+
+    session.update(scene({ elements: [{ id: 'first' }] }))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(save).toHaveBeenCalledTimes(1)
+
+    session.update(scene({ elements: [{ id: 'second' }] }))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(save).toHaveBeenCalledTimes(1) // 仍在写入中，不并发
+
+    pending[0]?.({ ok: true, revision: 'rev-1' })
+    await vi.advanceTimersByTimeAsync(0)
+    expect(save).toHaveBeenCalledTimes(2) // 写完后补写最新内容
+
+    pending[1]?.({ ok: true, revision: 'rev-2' })
+    await vi.advanceTimersByTimeAsync(0)
+    expect(session.state.value).toBe('idle')
+    expect(session.revision.value).toBe('rev-2')
+  })
+
+  it('写入失败保留最新内容并进入 failed，重试成功后回到 idle', async () => {
+    const save = vi
+      .fn()
+      .mockResolvedValueOnce({ ok: false, code: 'error', message: '磁盘满' })
+      .mockResolvedValueOnce({ ok: true, revision: 'rev-ok' })
+    const { session } = setup({ save: save as never })
+
+    const latest = scene({ elements: [{ id: 'latest' }] })
+    session.update(latest)
+    await vi.advanceTimersByTimeAsync(200)
+
+    expect(session.state.value).toBe('failed')
+    expect(session.lastError.value).toBe('磁盘满')
+    expect(session.currentContent()).toBe(latest) // 内容没丢
+
+    await session.retry()
+    expect(session.state.value).toBe('idle')
+    expect(session.revision.value).toBe('rev-ok')
+  })
+
+  it('冲突单独标记，内容保留供用户选择', async () => {
+    const save = vi.fn(async () => ({
+      ok: false as const,
+      code: 'conflict' as const,
+      message: '已被外部修改'
+    }))
+    const { session } = setup({ save: save as never })
+    session.update(scene({ elements: [{ id: 'mine' }] }))
+    await vi.advanceTimersByTimeAsync(200)
+
+    expect(session.state.value).toBe('conflict')
+    // 冲突时保留我的内容等待用户决定，不能被清掉
+    expect(session.hasPending()).toBe(true)
+    expect(session.currentContent()).toContain('mine')
+  })
+
+  it('flush 立即写盘（切换承载位置/关闭入口）', async () => {
+    const { session, save } = setup()
+    session.update(scene({ elements: [{ id: 'pending' }] }))
+    expect(save).not.toHaveBeenCalled()
+
+    await session.flush()
+    expect(save).toHaveBeenCalledTimes(1)
+  })
+
+  it('dispose 之后不再写盘', async () => {
+    const { session, save } = setup()
+    session.update(scene({ elements: [{ id: 'x' }] }))
+    session.dispose()
+    await vi.advanceTimersByTimeAsync(2000)
+    expect(save).not.toHaveBeenCalled()
+  })
+
+  it('adopt 把首帧规范化结果当基线：不写盘，且之后相同内容不触发写入', async () => {
+    const { session, save } = setup()
+    // 模拟 Excalidraw 载入后补齐字段：元素与 appState 都被规范化
+    const normalized = scene({
+      elements: [{ id: 'rect-1', groupIds: [], frameId: null, roundness: null }],
+      appState: { viewBackgroundColor: '#ffffff', gridSize: 20, gridStep: 5 }
+    })
+    session.update(normalized)
+    expect(session.state.value).toBe('pending')
+
+    session.adopt(normalized, 'rev-normalized')
+
+    expect(session.state.value).toBe('idle')
+    expect(session.hasPending()).toBe(false)
+    expect(session.revision.value).toBe('rev-normalized')
+    await vi.advanceTimersByTimeAsync(2000)
+    expect(save).not.toHaveBeenCalled()
+
+    // 同一份规范化内容再来一次（编辑器抖动）也不写
+    session.update(normalized)
+    await vi.advanceTimersByTimeAsync(2000)
+    expect(save).not.toHaveBeenCalled()
+
+    // 真正的内容变化照常写盘
+    session.update(scene({ elements: [{ id: 'rect-1' }, { id: 'rect-2' }] }))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(save).toHaveBeenCalledTimes(1)
+  })
+
+  it('adopt 之后 revision 不变时，写入仍会用最新 revision', async () => {
+    const { session, save } = setup()
+    session.adopt(scene({ elements: [{ id: 'normalized' }] }))
+    expect(session.revision.value).toBe('rev-0')
+    session.update(scene({ elements: [{ id: 'drawn' }] }))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(save).toHaveBeenCalledWith(expect.objectContaining({ expectedRevision: 'rev-0' }))
+  })
+
+  it('持久化指纹忽略展示状态但包含元素与内嵌文件', () => {
+    const a = persistedSceneSignature(scene())
+    expect(persistedSceneSignature(viewChanged({ scrollX: 10, zoom: { value: 1.5 } }))).toBe(a)
+    expect(persistedSceneSignature(scene({ elements: [{ id: 'changed' }] }))).not.toBe(a)
+    expect(
+      persistedSceneSignature(scene({ files: { f1: { id: 'f1', dataURL: 'data:image/png' } } }))
+    ).not.toBe(a)
+  })
+})

package/src/excalidraw/editorSession.ts

@@ -0,0 +1,224 @@
+/**
+ * 画布编辑会话（宿主无关）。
+ *
+ * 计划 E3 的硬约束：
+ * - 内容变化自动写盘，无保存按钮；连续变化合并（200ms）但有最大等待上限（1s），
+ *   避免一直拖动手势导致永不落盘
+ * - 写入严格有序：同一文件的写请求串行；旧完成的回调不能清掉更新的状态
+ * - 没有手动保存流程，但必须有 pending/writing/failed/conflict 状态，
+ *   失败时保留最新内存场景，不能显示成"已持久化"
+ * - 只有真正需要持久化的内容变化才触发写入（平移/缩放/选中不算）
+ */
+import { ref, type Ref } from 'vue'
+
+import { parseExcalidrawScene } from './scene'
+
+export type ExcalidrawWriteState = 'idle' | 'pending' | 'writing' | 'failed' | 'conflict'
+
+export interface ExcalidrawSaveInput {
+  content: string
+  expectedRevision: string
+}
+
+export type ExcalidrawSaveResult =
+  { ok: true; revision: string } | { ok: false; code: 'conflict' | 'error'; message: string }
+
+export interface ExcalidrawSessionOptions {
+  initialContent: string
+  initialRevision: string
+  save: (input: ExcalidrawSaveInput) => Promise<ExcalidrawSaveResult>
+  debounceMs?: number
+  maxWaitMs?: number
+}
+
+export interface ExcalidrawSession {
+  state: Ref<ExcalidrawWriteState>
+  lastError: Ref<string>
+  revision: Ref<string>
+  /** 编辑器内容变化回调（只在持久化内容真的变了时才调用） */
+  update(content: string): void
+  /** 立即写入：失去焦点、关闭入口、切换承载位置时调用 */
+  flush(): Promise<void>
+  /** 失败后重试（内容仍在内存里） */
+  retry(): Promise<void>
+  /**
+   * 把一段内容当作「已持久化」的基线：丢弃待写队列、更新 revision。
+   *
+   * 用途：编辑器首帧会把磁盘场景规范化（补齐 groupIds/roundness/gridSize 等字段），
+   * 那不是用户编辑，不能因此回写一份「规范化副本」；也可能用于放弃本地修改。
+   */
+  adopt(content: string, revision?: string): void
+  currentContent(): string
+  pendingContent(): string | null
+  hasPending(): boolean
+  dispose(): void
+}
+
+/**
+ * 只有元素 / 内嵌文件 / 与文档语义有关的 appState 才算"需要持久化"。
+ * 平移、缩放、选中、当前工具、滚动位置都属于展示状态，改了不该写盘。
+ */
+const PERSISTED_APP_STATE_KEYS = [
+  'viewBackgroundColor',
+  'gridSize',
+  'currentItemFontFamily',
+  'currentItemStrokeColor',
+  'currentItemBackgroundColor',
+  'currentItemFillStyle',
+  'currentItemStrokeWidth',
+  'currentItemRoughness',
+  'currentItemOpacity',
+  'name'
+] as const
+
+/** 提取用于比较的持久化指纹；解析失败时退回整串内容（保证坏数据也会被写回报告）。 */
+export function persistedSceneSignature(content: string): string {
+  const parsed = parseExcalidrawScene(content)
+  if (!parsed.ok) return content
+  const appState: Record<string, unknown> = {}
+  for (const key of PERSISTED_APP_STATE_KEYS) {
+    if (key in parsed.scene.appState) appState[key] = parsed.scene.appState[key]
+  }
+  return JSON.stringify({ elements: parsed.scene.elements, files: parsed.scene.files, appState })
+}
+
+export function createExcalidrawSession(options: ExcalidrawSessionOptions): ExcalidrawSession {
+  const debounceMs = options.debounceMs ?? 200
+  const maxWaitMs = options.maxWaitMs ?? 1000
+  const state = ref<ExcalidrawWriteState>('idle')
+  const lastError = ref('')
+  const revision = ref(options.initialRevision)
+
+  let savedSignature = persistedSceneSignature(options.initialContent)
+  let savedContent = options.initialContent
+  let queued: string | null = null
+  let writing = false
+  let writeAgain = false
+  let disposed = false
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  let maxTimer: ReturnType<typeof setTimeout> | null = null
+
+  function clearTimers(): void {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    if (maxTimer) clearTimeout(maxTimer)
+    debounceTimer = null
+    maxTimer = null
+  }
+
+  function schedule(): void {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null
+      void flush()
+    }, debounceMs)
+    // 最大等待：连续编辑时至少每 maxWaitMs 落盘一次
+    if (!maxTimer) {
+      maxTimer = setTimeout(() => {
+        maxTimer = null
+        void flush()
+      }, maxWaitMs)
+    }
+  }
+
+  function update(content: string): void {
+    if (disposed) return
+    const signature = persistedSceneSignature(content)
+    if (signature === savedSignature && queued === null) return // 展示状态变化，不写盘
+    queued = content
+    if (state.value !== 'writing') state.value = 'pending'
+    schedule()
+  }
+
+  async function runWrite(): Promise<void> {
+    if (writing || disposed) {
+      if (writing) writeAgain = true
+      return
+    }
+    const content = queued
+    if (content === null) return
+    if (persistedSceneSignature(content) === savedSignature) {
+      queued = null
+      state.value = 'idle'
+      return
+    }
+
+    writing = true
+    state.value = 'writing'
+    const writingSignature = persistedSceneSignature(content)
+    try {
+      const result = await options.save({ content, expectedRevision: revision.value })
+      if (disposed) return
+      if (result.ok) {
+        revision.value = result.revision
+        savedContent = content
+        savedSignature = writingSignature
+        lastError.value = ''
+        // 旧回调不能清掉更新的状态：只有当前队列就是刚写成功的内容才算干净
+        if (queued !== null && persistedSceneSignature(queued) === writingSignature) {
+          queued = null
+        }
+        state.value = queued === null ? 'idle' : 'pending'
+      } else if (result.code === 'conflict') {
+        state.value = 'conflict'
+        lastError.value = result.message
+      } else {
+        state.value = 'failed'
+        lastError.value = result.message
+      }
+    } catch (error) {
+      if (!disposed) {
+        state.value = 'failed'
+        lastError.value = error instanceof Error ? error.message : String(error)
+      }
+    } finally {
+      writing = false
+      if (writeAgain) {
+        writeAgain = false
+        void runWrite()
+      }
+    }
+  }
+
+  async function flush(): Promise<void> {
+    if (disposed) return
+    clearTimers()
+    await runWrite()
+  }
+
+  async function retry(): Promise<void> {
+    if (disposed) return
+    if (state.value === 'failed' && queued === null) queued = savedContent
+    await flush()
+  }
+
+  function adopt(content: string, nextRevision?: string): void {
+    if (disposed) return
+    clearTimers()
+    queued = null
+    savedContent = content
+    savedSignature = persistedSceneSignature(content)
+    if (nextRevision !== undefined) revision.value = nextRevision
+    lastError.value = ''
+    state.value = 'idle'
+  }
+
+  function dispose(): void {
+    disposed = true
+    clearTimers()
+    queued = null
+  }
+
+  return {
+    state,
+    lastError,
+    revision,
+    update,
+    flush,
+    retry,
+    adopt,
+    currentContent: () => queued ?? savedContent,
+    pendingContent: () => queued,
+    hasPending: () => queued !== null,
+    dispose
+  }
+}

package/src/excalidraw/exporter.ts

@@ -0,0 +1,50 @@
+/**
+ * 懒加载的导出适配：**唯一**静态引用 @excalidraw/excalidraw 的地方。
+ * 宿主（Desk 卡片 / SSG 客户端）通过动态 import 使用它，避免把编辑器打进首屏。
+ */
+import { exportToSvg } from '@excalidraw/excalidraw'
+
+import { getExcalidrawAssetPath, inlineExcalidrawFonts } from './fonts'
+
+import type { ExcalidrawScene } from './scene'
+
+export interface ExcalidrawExportOptions {
+  /** 深色主题导出；只影响显示，不修改磁盘 appState */
+  dark: boolean
+  /** 导出背景；文档自身语义优先，默认沿用场景里的 viewBackgroundColor */
+  background?: boolean
+  /** 本地字体基址；缺省用 window.EXCALIDRAW_ASSET_PATH */
+  fontBase?: string
+  /** 便于测试注入 */
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * 生成自包含的 SVG 字符串。实测官方导出会内嵌 @font-face 与内联图片 data URL，
+ * 因此可以安全地作为 <img src="data:image/svg+xml…"> 渲染：没有脚本执行、
+ * 没有外部网络请求。
+ */
+export async function renderExcalidrawSvg(
+  scene: ExcalidrawScene,
+  options: ExcalidrawExportOptions
+): Promise<string> {
+  const svg = await exportToSvg({
+    elements: scene.elements as never,
+    appState: {
+      ...(scene.appState as Record<string, unknown>),
+      exportWithDarkMode: options.dark,
+      ...(options.background === undefined ? {} : { exportBackground: options.background })
+    },
+    files: (scene.files ?? {}) as never
+  })
+  // 只读路径必须自包含：把 CDN/相对字体换成 data URL，离线与 <img> 渲染才不掉字体
+  const inlined = await inlineExcalidrawFonts(svg.outerHTML, {
+    base: options.fontBase ?? getExcalidrawAssetPath(),
+    fetchImpl: options.fetchImpl
+  })
+  if (inlined.remaining.length > 0) {
+    // 不能静默：宿主据此提示「字体未内联，离线可能掉字体」
+    console.warn('[tnotes] excalidraw fonts not inlined', inlined.remaining.slice(0, 3))
+  }
+  return inlined.svg
+}

package/src/excalidraw/focus.test.ts

@@ -0,0 +1,60 @@
+// @vitest-environment happy-dom
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { restoreCanvasKeyboardFocus, restoreCanvasKeyboardFocusWhenReady } from './focus'
+
+function fixture(height: number): { host: HTMLDivElement; canvas: HTMLCanvasElement } {
+  const host = document.createElement('div')
+  const canvas = document.createElement('canvas')
+  canvas.className = 'excalidraw__canvas interactive'
+  canvas.getBoundingClientRect = () => ({ height, width: 400 }) as DOMRect
+  host.append(canvas)
+  document.body.append(host)
+  return { host, canvas }
+}
+
+afterEach(() => {
+  document.body.replaceChildren()
+  vi.restoreAllMocks()
+})
+
+describe('画布键盘焦点', () => {
+  it('补 tabindex 并把焦点交给交互画布', () => {
+    const { host, canvas } = fixture(600)
+
+    expect(restoreCanvasKeyboardFocus(host)).toBe(true)
+    expect(canvas.getAttribute('tabindex')).toBe('0')
+    expect(document.activeElement).toBe(canvas)
+  })
+
+  it('没有交互画布时不抢焦点并返回 false', () => {
+    const host = document.createElement('div')
+    const button = document.createElement('button')
+    host.append(button)
+    document.body.append(host)
+    button.focus()
+
+    expect(restoreCanvasKeyboardFocus(host)).toBe(false)
+    // blur 掉当前焦点后没有可聚焦目标：焦点回到 body，不会落到别的控件上
+    expect(document.activeElement).toBe(document.body)
+  })
+
+  it('画布还在 display:none 里（高度 0）时不聚焦，等布局就绪后再聚焦', () => {
+    const { host, canvas } = fixture(0)
+    const frames: Array<() => void> = []
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      frames.push(() => callback(0))
+      return frames.length
+    })
+
+    restoreCanvasKeyboardFocusWhenReady(host)
+    // 关键回归点：还没布局就 focus() 会静默失败、焦点留在 body，快捷键收不到
+    expect(document.activeElement).not.toBe(canvas)
+    expect(frames.length).toBeGreaterThan(0)
+
+    canvas.getBoundingClientRect = () => ({ height: 600, width: 400 }) as DOMRect
+    frames.forEach((run) => run())
+    expect(document.activeElement).toBe(canvas)
+  })
+})

package/src/excalidraw/focus.ts

@@ -0,0 +1,33 @@
+/**
+ * 画布键盘焦点。
+ *
+ * 背景（E0/E3 实测）：Excalidraw 把键盘快捷键挂在容器上，宿主节点被搬动
+ * （卡片 → 全屏 → 标签页）之后焦点会留在触发交接的控件上，快捷键不再送达编辑器；
+ * 指针路径正常。恢复方式只有一条：blur 当前焦点 → 给交互画布补 tabindex → focus。
+ *
+ * E4 补充：标签页/分栏切回来时承载容器可能还在 `display:none` 里（组件 watcher
+ * 触发的 DOM 更新还没落地），此时 `focus()` 静默失败、焦点留在 body。
+ * 因此用 `restoreCanvasKeyboardFocusWhenReady` 等到画布真的有高度再聚焦。
+ */
+export function restoreCanvasKeyboardFocus(host: HTMLElement): boolean {
+  if (typeof document === 'undefined') return false
+  const active = document.activeElement
+  if (active instanceof HTMLElement) active.blur()
+  const canvas = host.querySelector<HTMLElement>('.excalidraw__canvas.interactive')
+  if (!canvas) return false
+  if (!canvas.hasAttribute('tabindex')) canvas.setAttribute('tabindex', '0')
+  canvas.focus()
+  return document.activeElement === canvas
+}
+
+/** 等画布真的有布局（高度 > 0）再聚焦；最多重试 30 帧。 */
+export function restoreCanvasKeyboardFocusWhenReady(host: HTMLElement, attempt = 0): void {
+  if (typeof document === 'undefined') return
+  const canvas = host.querySelector<HTMLElement>('.excalidraw__canvas.interactive')
+  const laidOut = canvas ? canvas.getBoundingClientRect().height > 0 : false
+  if (laidOut || typeof requestAnimationFrame !== 'function' || attempt >= 30) {
+    restoreCanvasKeyboardFocus(host)
+    return
+  }
+  requestAnimationFrame(() => restoreCanvasKeyboardFocusWhenReady(host, attempt + 1))
+}