@allbluecn/web-app 0.17.1 → 0.18.0

package/src/components/design/canvas/plugins/leafer-x-clipboard/__tests__/clipboard.test.ts

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: MIT
+
+// leafer-x-clipboard 插件测试：真实 leafer 树（stub canvas，纯 node 环境）。
+
+import { describe, expect, it, vi } from "vitest"
+
+vi.stubGlobal("CanvasRenderingContext2D", class {})
+vi.stubGlobal("DOMMatrix", class {})
+vi.stubGlobal("ImageData", class {})
+vi.stubGlobal("Path2D", class {})
+vi.stubGlobal("OffscreenCanvas", class {})
+vi.stubGlobal("createImageBitmap", async () => ({ width: 1, height: 1, close() {} }))
+vi.stubGlobal("devicePixelRatio", 1)
+vi.stubGlobal("matchMedia", () => ({ matches: false, addListener() {}, removeListener() {} }))
+vi.stubGlobal("requestAnimationFrame", (f: () => void) => setTimeout(f, 0))
+vi.stubGlobal("cancelAnimationFrame", (i: number) => clearTimeout(i))
+
+function makeEventClass(name: string) {
+  return class {
+    type = ""
+    constructor(_type?: string, _init?: unknown) {
+      this.type = _type ?? ""
+    }
+    static get name() {
+      return name
+    }
+    preventDefault() {}
+    stopPropagation() {}
+  }
+}
+
+for (const name of [
+  "Event",
+  "MouseEvent",
+  "KeyboardEvent",
+  "PointerEvent",
+  "TouchEvent",
+  "WheelEvent",
+  "DragEvent",
+  "ClipboardEvent",
+  "AnimationEvent",
+  "TransitionEvent",
+  "MessageEvent",
+  "ErrorEvent",
+  "FocusEvent",
+  "DeviceOrientationEvent",
+  "DeviceMotionEvent",
+  "OrientationEvent",
+  "CustomEvent",
+]) {
+  if (typeof (globalThis as Record<string, unknown>)[name] === "function") continue
+  vi.stubGlobal(name, makeEventClass(name))
+}
+
+const stub2d = new Proxy(
+  {},
+  {
+    get(_t, k) {
+      if (k === "measureText")
+        return () => ({ width: 10, actualBoundingBoxAscent: 10, actualBoundingBoxDescent: 3 })
+      if (k === "getImageData") return () => ({ data: new Uint8ClampedArray(4) })
+      if (k === "createLinearGradient" || k === "createRadialGradient")
+        return () => ({ addColorStop() {} })
+      if (k === "createPattern") return () => ({})
+      return () => undefined
+    },
+    set() {
+      return true
+    },
+  },
+)
+
+vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(
+  stub2d as unknown as CanvasRenderingContext2D,
+)
+
+import { installWithModule } from "../index"
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+describe("leafer-x-clipboard", async () => {
+  const leafer = await import("leafer-editor")
+
+  async function makeTree() {
+    const lf = new leafer.Leafer({ width: 1000, height: 800, trackChanges: true })
+    for (let i = 0; i < 40; i++) {
+      if ((lf as unknown as { created?: boolean }).created) break
+      await sleep(20)
+    }
+    return lf
+  }
+
+  it("copy → paste 重建子树并按偏移错位", async () => {
+    const lf = await makeTree()
+    const clipboard = installWithModule(leafer as never, { tree: lf })
+    const rect = new leafer.Rect({ id: "src", x: 100, y: 100, width: 80, height: 60, fill: "#000" })
+    lf.add(rect)
+    await sleep(30)
+
+    clipboard.copy([rect])
+    expect(clipboard.isEmpty).toBe(false)
+
+    const pasted = clipboard.paste()
+    expect(pasted).toHaveLength(1)
+    const copy = pasted![0] as unknown as {
+      id?: string
+      getBounds: (t: string, r: string) => { x: number; y: number; width: number; height: number }
+    }
+    // 偏移 20（首次粘贴）
+    const cb = copy.getBounds("box", "world")
+    expect(cb.x).toBeCloseTo(120, 5)
+    expect(cb.y).toBeCloseTo(120, 5)
+    expect(cb.width).toBeCloseTo(80, 5)
+
+    lf.destroy()
+  })
+
+  it("多次粘贴偏移累加", async () => {
+    const lf = await makeTree()
+    const clipboard = installWithModule(leafer as never, { tree: lf })
+    const rect = new leafer.Rect({ id: "src", x: 0, y: 0, width: 50, height: 50 })
+    lf.add(rect)
+    await sleep(30)
+
+    clipboard.copy([rect])
+    const first = clipboard.paste()![0]
+    const second = clipboard.paste()![0]
+    const b1 = (first as unknown as {
+      getBounds: (t: string, r: string) => { x: number }
+    }).getBounds("box", "world")
+    const b2 = (second as unknown as {
+      getBounds: (t: string, r: string) => { x: number }
+    }).getBounds("box", "world")
+    expect(b1.x).toBeCloseTo(20, 5)
+    expect(b2.x).toBeCloseTo(40, 5)
+
+    lf.destroy()
+  })
+
+  it("多选复制保持相对位置", async () => {
+    const lf = await makeTree()
+    const clipboard = installWithModule(leafer as never, { tree: lf })
+    const a = new leafer.Rect({ id: "a", x: 0, y: 0, width: 50, height: 50 })
+    const b = new leafer.Rect({ id: "b", x: 100, y: 40, width: 50, height: 50 })
+    lf.add(a)
+    lf.add(b)
+    await sleep(30)
+
+    clipboard.copy([a, b])
+    const pasted = clipboard.paste()!
+    expect(pasted).toHaveLength(2)
+    const pa = pasted.find((l) => (l as unknown as { id: string }).id === "a") as unknown as {
+      getBounds: (t: string, r: string) => { x: number; y: number }
+    }
+    const pb = pasted.find((l) => (l as unknown as { id: string }).id === "b") as unknown as {
+      getBounds: (t: string, r: string) => { x: number; y: number }
+    }
+    // 相对位置保持：b 相对 a 的偏移 (100, 40) 不变（整体 +20 错位）
+    expect(pb.getBounds("box", "world").x - pa.getBounds("box", "world").x).toBeCloseTo(100, 5)
+    expect(pb.getBounds("box", "world").y - pa.getBounds("box", "world").y).toBeCloseTo(40, 5)
+
+    lf.destroy()
+  })
+
+  it("cut 移除原元素后粘贴恢复", async () => {
+    const lf = await makeTree()
+    const clipboard = installWithModule(leafer as never, { tree: lf })
+    const rect = new leafer.Rect({ id: "cutme", x: 10, y: 10, width: 50, height: 50 })
+    lf.add(rect)
+    await sleep(30)
+
+    clipboard.cut([rect])
+    expect((lf as unknown as { children: unknown[] }).children.length).toBe(0)
+
+    const restored = clipboard.paste()!
+    expect(restored).toHaveLength(1)
+    expect((lf as unknown as { children: unknown[] }).children.length).toBe(1)
+
+    lf.destroy()
+  })
+
+  it("clear/空槽边界", async () => {
+    const lf = await makeTree()
+    const clipboard = installWithModule(leafer as never, { tree: lf })
+    expect(clipboard.isEmpty).toBe(true)
+    expect(clipboard.paste()).toBeNull()
+
+    const rect = new leafer.Rect({ id: "x", x: 0, y: 0, width: 10, height: 10 })
+    lf.add(rect)
+    clipboard.copy([rect])
+    clipboard.clear()
+    expect(clipboard.isEmpty).toBe(true)
+    expect(clipboard.paste()).toBeNull()
+
+    lf.destroy()
+  })
+})

package/src/components/design/canvas/plugins/leafer-x-clipboard/index.ts

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: MIT
+//
+// leafer-x-clipboard — leafer 层复制/剪切/粘贴插件
+// （LeaferJS 社区插件规范，leafer-x 系列）
+//
+// 以官方 toJSON/UI.one 序列化为媒介的内部剪贴板：复制选中子树快照，
+// 粘贴时重建并按偏移量错位（多次粘贴累加），多选保持相对位置。
+// 跨页/跨文档天然可用（槽内是 JSON 与实例解耦）。
+//
+// 契约（自包含，可整体搬移发布）：
+// - 仅 type import leafer 类型 + 插件自身文件；运行时经 installWithModule
+//   注入；零业务依赖——文档层克隆语义（id 重映射、父子关系重建）由消费方
+//   在文档模型层自行处理
+
+import type { ILeaf, IUI } from "leafer-editor"
+
+export interface ClipboardSlotItem {
+  /** 子树快照（官方 toJSON 产物） */
+  json: Record<string, unknown>
+  /** 复制时的视觉左上（world），粘贴时用于保持相对位置 */
+  world: { x: number; y: number }
+  /** 原父 innerId（粘贴时优先回原父，父不存在则回落根） */
+  parentInnerId: number
+}
+
+export interface ClipboardOptions {
+  /** 粘贴偏移（默认 20，多次粘贴累加） */
+  offset?: number
+  /** 粘贴目标根（默认 target.tree；槽内父不存在时的回落容器） */
+  root?: ILeaf
+}
+
+export interface ClipboardPlugin {
+  /** 复制：记录子树快照（多选保持相对位置） */
+  copy(leaves: IUI[]): void
+  /** 剪切：copy 后从树移除 */
+  cut(leaves: IUI[]): void
+  /** 粘贴：重建子树并偏移错位，返回新实例（空槽返回 null） */
+  paste(): IUI[] | null
+  get isEmpty(): boolean
+  clear(): void
+  destroy(): void
+}
+
+export interface LeaferClipboardModule {
+  UI: { one: (data: unknown, x?: number, y?: number) => IUI }
+}
+
+const DEFAULT_OFFSET = 20
+
+type LeafLike = ILeaf & {
+  parent?: ILeaf
+  innerId?: number
+}
+
+function worldTopLeft(leaf: ILeaf): { x: number; y: number } {
+  const b = leaf.getBounds("box", "world")
+  return { x: b.x, y: b.y }
+}
+
+function findByInnerId(root: ILeaf, innerId: number): ILeaf | undefined {
+  if (innerId < 0) return undefined
+  if (innerIdOf(root) === innerId) return root
+  const children = (root as unknown as { children?: ILeaf[] }).children
+  if (!children) return undefined
+  for (const child of children) {
+    const hit = findByInnerId(child, innerId)
+    if (hit) return hit
+  }
+  return undefined
+}
+
+// 别名：leaf 直接用（上面 findByInnerId 参数名笔误防护）
+function innerIdOf(leaf: unknown): number {
+  return (leaf as { innerId?: number }).innerId ?? -1
+}
+
+class Clipboard implements ClipboardPlugin {
+  private mod: LeaferClipboardModule
+  private root: ILeaf
+  private offset: number
+  private slot: ClipboardSlotItem[] = []
+  private pasteCount = 0
+
+  constructor(mod: LeaferClipboardModule, root: ILeaf, options: ClipboardOptions = {}) {
+    this.mod = mod
+    this.root = root
+    this.offset = options.offset ?? DEFAULT_OFFSET
+  }
+
+  copy(leaves: IUI[]): void {
+    this.slot = leaves.map((leaf) => ({
+      json: (leaf as unknown as { toJSON: () => Record<string, unknown> }).toJSON(),
+      world: worldTopLeft(leaf),
+      parentInnerId: innerIdOf((leaf as unknown as LeafLike).parent),
+    }))
+    this.pasteCount = 0
+  }
+
+  cut(leaves: IUI[]): void {
+    this.copy(leaves)
+    for (const leaf of leaves) {
+      const parent = (leaf as unknown as LeafLike).parent
+      parent?.remove(leaf)
+    }
+  }
+
+  paste(): IUI[] | null {
+    if (!this.slot.length) return null
+    const bounds = this.slot.map((item) => item.world)
+    const minX = Math.min(...bounds.map((b) => b.x))
+    const minY = Math.min(...bounds.map((b) => b.y))
+    const dx = this.offset * (this.pasteCount + 1)
+    const dy = this.offset * (this.pasteCount + 1)
+    this.pasteCount++
+    const created: IUI[] = []
+    for (const item of this.slot) {
+      const UI = this.mod.UI
+      // 深拷贝槽内快照：粘贴多次互不影响，且与槽内引用解耦
+      const leaf = UI.one(JSON.parse(JSON.stringify(item.json)) as unknown) as ILeaf
+      const parent =
+        findByInnerId(this.root, item.parentInnerId) ?? this.root
+      const branch = parent as unknown as {
+        add?: (child: ILeaf) => void
+        addAt?: (child: ILeaf, index: number) => void
+      }
+      branch.add?.(leaf)
+      // 相对位置保持：整体平移 dx/dy（世界空间差量，经父变换由 leafer 布局承担）
+      const now = worldTopLeft(leaf)
+      const target = { x: item.world.x - minX + dx + minX, y: item.world.y - minY + dy + minY }
+      shiftByWorld(leaf, target.x - now.x, target.y - now.y)
+      created.push(leaf as unknown as IUI)
+    }
+    return created
+  }
+
+  get isEmpty(): boolean {
+    return this.slot.length === 0
+  }
+
+  clear(): void {
+    this.slot = []
+    this.pasteCount = 0
+  }
+
+  destroy(): void {
+    this.clear()
+  }
+}
+
+function shiftByWorld(leaf: ILeaf, dx: number, dy: number): void {
+  if (dx === 0 && dy === 0) return
+  const target = leaf as LeafLike
+  const parent = target.parent
+  if (!parent) return
+  const from = { x: 0, y: 0 }
+  parent.worldToLocal(from)
+  const to = { x: dx, y: dy }
+  parent.worldToLocal(to)
+  const t = target as { x?: number; y?: number }
+  if (t.x !== undefined) t.x += to.x - from.x
+  if (t.y !== undefined) t.y += to.y - from.y
+}
+
+function resolveRoot(target: unknown, options: ClipboardOptions): ILeaf | null {
+  if (options.root) return options.root
+  const asApp = target as { tree?: ILeaf }
+  if (asApp.tree) return asApp.tree
+  if ((target as { innerId?: number }).innerId !== undefined) return target as ILeaf
+  return null
+}
+
+/** 安装剪贴板插件（参数与 leafer-x 系列一致） */
+export function installWithModule(
+  mod: LeaferClipboardModule,
+  target: unknown,
+  options: ClipboardOptions = {},
+): ClipboardPlugin {
+  const root = resolveRoot(target, options)
+  if (!root) throw new Error("[leafer-x-clipboard] target must be an App or ILeaf with tree")
+  return new Clipboard(mod, root, options)
+}

package/src/components/design/canvas/plugins/leafer-x-history-lite/README.md

@@ -0,0 +1,70 @@
+# leafer-x-history-lite
+
+轻量撤销/重做历史插件（LeaferJS 社区插件规范，leafer-x 系列）。
+
+基于 LeaferJS 官方 `PropertyEvent` / `ChildEvent` 的 **diff 快照栈**（官方「历史记录」页推荐做法的实现），以增量变更记录替代全量快照，内存占用与树规模解耦。官方编辑器不内置 undo/redo 栈，本插件补位该能力。
+
+## 特性
+
+- **增量 diff**：只记录属性/结构变更（`{kind, innerId, key, before, after}` / `{kind, json, parentInnerId, index}`），不做全量树快照
+- **步语义**：一批变更合为一步（undo/redo 以步为原子）；官方推荐的 `drag.start/drag.end` 交互切步 + 微批聚合双模式
+- **同键合并**：同一同步段内同元素同属性的连续修改合并为一条（before 取最早值）
+- **注入式持久化**：`options.storage` 接口（`load/save`），IndexedDB/localStorage/远端由消费方决定，插件不绑定具体存储
+- **框架无关**：零业务依赖，React/Vue/原生均可使用
+- `pause/resume`：程序化批量变更（导入/算法重排）时暂停记录
+
+## 安装使用
+
+```ts
+// leafer-editor 已内置所需事件（PropertyEvent/ChildEvent/官方 DragEvent）
+import { installWithModule } from "./leafer-x-history-lite"
+
+const mod = await import("leafer-editor")
+const app = new mod.App({ view: el })
+
+const history = installWithModule(mod, app, {
+  limit: 50,
+  // 可选：持久化注入
+  storage: {
+    load: () => idbGet("canvas-history"),
+    save: (steps) => idbSet("canvas-history", steps),
+  },
+})
+
+history.undo() // 撤销
+history.redo() // 重做
+history.canUndo / history.canRedo / history.steps
+history.pause() / history.resume() / history.commit() / history.clear() / history.destroy()
+```
+
+`target` 支持：
+
+- `App` —— 监听其 `tree`（推荐，编辑器场景）
+- 任意 `ILeaf` 分支 —— 只记录该子树内的变更
+
+## 事件机制（重要前置）
+
+Leafer 的属性/子事件链路有两层前置条件，消费方需知悉：
+
+1. **`trackChanges` 配置**：属性/子事件仅在 `leafer.config.trackChanges` 开启时向树根派发（`App`/`Leafer` 构造参数传入 `trackChanges: true`）。
+2. **初始化时序**：`__setAttr` 有 `leaferIsCreated` 守卫——leafer 异步初始化完成（`created`）之前的赋值不派发事件。`installWithModule` 应在 leafer 就绪后调用，或接受「就绪前的初始建树不入历史」（这通常正是期望语义：初始状态无需撤销）。
+
+## 已知限制
+
+- **remove 的 z 序**：`ChildEvent.REMOVE` 派发时子元素已脱离父容器，原 index 不可得（leafer 事件模型边界）。undo 重建时 append 到原父末尾，z 序可能与删除前不同。对以 `drag.end` 切步的编辑器交互，后续步骤通常会修正顺序。
+- **跨会话恢复**：持久化恢复只保留属性步（重建步的 innerId 别名跨会话失效，自动丢弃）。
+- **引用语义**：`before/after` 持有变更时的值引用；leafer 数据层为不可变替换（set 新引用）时无失真风险，外部原地 mutate 共享对象除外。
+- **依赖**：peer 依赖 `leafer-editor >= 2.0`（或等效提供 `PropertyEvent`/`ChildEvent`/`DragEvent`/`UI.one` 的 leafer 场景包）。
+
+## 发布形态（晋升到独立包时）
+
+仓内孵化期无 `package.json`；发布前补：
+
+- `name: "leafer-x-history-lite"`（发布前 `npm view leafer-x-history-lite` 查重）
+- `peerDependencies: { "leafer-editor": ">=2.0.0" }`、`"type": "module"`、MIT
+- leafer 相关模块 external
+- 英文版 README（本文档即中英双语）
+
+## License
+
+MIT

package/src/components/design/canvas/plugins/leafer-x-history-lite/__tests__/history-lite.test.ts

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: MIT
+
+// leafer-x-history-lite 插件测试：真实 leafer 树（stub canvas，纯 node 环境跑）。
+// 关键前置：leafer 初始化是异步链，属性/子事件仅在 leafer.created 后派发
+// （__setAttr 的 leaferIsCreated 守卫），测试统一等待 created 再操作。
+
+import { describe, expect, it, vi } from "vitest"
+
+vi.stubGlobal("CanvasRenderingContext2D", class {})
+vi.stubGlobal("DOMMatrix", class {})
+vi.stubGlobal("ImageData", class {})
+vi.stubGlobal("Path2D", class {})
+vi.stubGlobal("OffscreenCanvas", class {})
+vi.stubGlobal("createImageBitmap", async () => ({ width: 1, height: 1, close() {} }))
+vi.stubGlobal("devicePixelRatio", 1)
+vi.stubGlobal("matchMedia", () => ({ matches: false, addListener() {}, removeListener() {} }))
+vi.stubGlobal("requestAnimationFrame", (f: () => void) => setTimeout(f, 0))
+vi.stubGlobal("cancelAnimationFrame", (i: number) => clearTimeout(i))
+
+function makeEventClass(name: string) {
+  return class {
+    type = ""
+    constructor(_type?: string, _init?: unknown) {
+      this.type = _type ?? ""
+    }
+    static get name() {
+      return name
+    }
+    preventDefault() {}
+    stopPropagation() {}
+  }
+}
+
+for (const name of [
+  "Event",
+  "MouseEvent",
+  "KeyboardEvent",
+  "PointerEvent",
+  "TouchEvent",
+  "WheelEvent",
+  "DragEvent",
+  "ClipboardEvent",
+  "AnimationEvent",
+  "TransitionEvent",
+  "MessageEvent",
+  "ErrorEvent",
+  "FocusEvent",
+  "DeviceOrientationEvent",
+  "DeviceMotionEvent",
+  "OrientationEvent",
+  "CustomEvent",
+]) {
+  if (typeof (globalThis as Record<string, unknown>)[name] === "function") continue
+  vi.stubGlobal(name, makeEventClass(name))
+}
+
+const stub2d = new Proxy(
+  {},
+  {
+    get(_t, k) {
+      if (k === "measureText")
+        return () => ({ width: 10, actualBoundingBoxAscent: 10, actualBoundingBoxDescent: 3 })
+      if (k === "getImageData") return () => ({ data: new Uint8ClampedArray(4) })
+      if (k === "createLinearGradient" || k === "createRadialGradient")
+        return () => ({ addColorStop() {} })
+      if (k === "createPattern") return () => ({})
+      return () => undefined
+    },
+    set() {
+      return true
+    },
+  },
+)
+
+vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(
+  stub2d as unknown as CanvasRenderingContext2D,
+)
+
+import { installWithModule, type HistoryLite, type HistoryStep } from "../index"
+
+
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+type LeaferInstance = InstanceType<(typeof import("leafer-editor"))["Leafer"]>
+
+async function makeTree(leafer: typeof import("leafer-editor")): Promise<LeaferInstance> {
+  const lf = new leafer.Leafer({ width: 800, height: 600, trackChanges: true })
+  // 等待 leafer 异步初始化（created 后事件链路才开启）
+  for (let i = 0; i < 40; i++) {
+    if ((lf as unknown as { created?: boolean }).created) break
+    await sleep(20)
+  }
+  return lf
+}
+
+async function settled(history: HistoryLite): Promise<void> {
+  await sleep(20)
+  history.commit()
+}
+
+describe("leafer-x-history-lite", async () => {
+  const leafer = await import("leafer-editor")
+
+  it("属性变更记录 + undo/redo 恢复", async () => {
+    const lf = await makeTree(leafer)
+    const history = installWithModule(leafer as never, lf)
+    const rect = new leafer.Rect({ id: "r1", x: 10, y: 20, width: 100, height: 50 })
+    lf.add(rect)
+    await settled(history)
+
+    rect.set({ x: 555 })
+    await settled(history)
+    expect(history.canUndo).toBe(true)
+
+    expect(history.undo()).toBe(true)
+    expect((rect as unknown as { x: number }).x).toBe(10)
+    expect(history.canRedo).toBe(true)
+
+    expect(history.redo()).toBe(true)
+    expect((rect as unknown as { x: number }).x).toBe(555)
+
+    history.destroy()
+    lf.destroy()
+  })
+
+  it("子树 add/remove 记录 + undo 重建", async () => {
+    const lf = await makeTree(leafer)
+    const history = installWithModule(leafer as never, lf)
+    await settled(history)
+
+    const rect = new leafer.Rect({ id: "r2", x: 1, y: 2, width: 30, height: 40, fill: "#000" })
+    lf.add(rect)
+    await settled(history)
+    expect(history.canUndo).toBe(true)
+
+    // undo → 新增的 rect 被移除
+    expect(history.undo()).toBe(true)
+    expect((lf as unknown as { children: unknown[] }).children.length).toBe(0)
+
+    // redo → 重建
+    expect(history.redo()).toBe(true)
+    const children = (lf as unknown as { children: unknown[] }).children
+    expect(children.length).toBe(1)
+    const rebuilt = children[0] as { id?: string; x?: number }
+    expect(rebuilt.id).toBe("r2")
+    expect(rebuilt.x).toBe(1)
+
+    history.destroy()
+    lf.destroy()
+  })
+
+  it("同步段同 key 连改合并，before 取最早值", async () => {
+    const lf = await makeTree(leafer)
+    const history = installWithModule(leafer as never, lf)
+    const rect = new leafer.Rect({ id: "r3", x: 0, y: 0, width: 10, height: 10 })
+    lf.add(rect)
+    await settled(history)
+
+    rect.set({ x: 5 })
+    rect.set({ x: 9 })
+    await settled(history)
+
+    expect(history.undo()).toBe(true)
+    expect((rect as unknown as { x: number }).x).toBe(0)
+
+    history.destroy()
+    lf.destroy()
+  })
+
+  it("pause/resume 跳过记录", async () => {
+    const lf = await makeTree(leafer)
+    const history = installWithModule(leafer as never, lf)
+    const rect = new leafer.Rect({ id: "r4", x: 0, y: 0, width: 10, height: 10 })
+    lf.add(rect)
+    await settled(history)
+    const stepsBefore = history.steps
+
+    history.pause()
+    rect.set({ x: 77 })
+    await settled(history)
+    history.resume()
+
+    // pause 期间的属性变更不入历史（步数不变），但变更本身生效
+    expect(history.steps).toBe(stepsBefore)
+    expect((rect as unknown as { x: number }).x).toBe(77)
+
+    history.destroy()
+    lf.destroy()
+  })
+
+  it("limit 淘汰最旧步", async () => {
+    const lf = await makeTree(leafer)
+    const history = installWithModule(leafer as never, lf, { limit: 3 })
+    const rect = new leafer.Rect({ id: "r5", x: 0, y: 0, width: 10, height: 10 })
+    lf.add(rect)
+    await settled(history)
+
+    for (let i = 1; i <= 5; i++) {
+      rect.set({ x: i })
+      await settled(history)
+    }
+    expect(history.steps).toBe(3)
+
+    history.destroy()
+    lf.destroy()
+  })
+
+  it("storage 注入持久化 roundtrip", async () => {
+    let saved: HistoryStep[] | unknown = null
+    const history = installWithModule(leafer as never, await makeTree(leafer), {
+      storage: {
+        load: async () => null,
+        save: async (steps) => {
+          saved = steps
+        },
+      },
+    })
+    const rect = new leafer.Rect({ id: "r6", x: 0, y: 0, width: 10, height: 10 })
+    const lf = (history as unknown as { root: { add: (c: unknown) => void } }).root
+    lf.add(rect)
+    await settled(history)
+
+    expect(saved).not.toBeNull()
+    expect((saved as HistoryStep[] | null)?.length ?? 0).toBe(1)
+
+    history.destroy()
+  })
+
+  it("无变更时 undo/redo 返回 false", async () => {
+    const lf = await makeTree(leafer)
+    const history = installWithModule(leafer as never, lf)
+    await settled(history)
+
+    expect(history.undo()).toBe(false)
+    expect(history.redo()).toBe(false)
+    expect(history.canUndo).toBe(false)
+    expect(history.canRedo).toBe(false)
+
+    history.destroy()
+    lf.destroy()
+  })
+})