@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/bindings/__tests__/canvas-remote.test.ts

@@ -0,0 +1,454 @@
+// 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.
+
+// 画布远端变更增量应用桥测试（P4b，任务 27，规格 §7.2 远端方向）：
+// 真 Y.Doc 双端仿真（peer 作者 → applyUpdate 模拟远端到达）+ 记录调用的假引擎
+//（同 canvas-presence/fields 先例：bindings 层脱离组件树与 Leafer 单测）。
+// 覆盖简报场景：① 远端 add/remove/patch/order 各产生正确 SceneDiffPlan 应用
+// ② 防抖合并连续 update ③ 交互冻结期挂起、解冻一次应用最新态（非队列回放）
+// ④ rebuild 兜底触发（apply 抛异常/返回 false → rebuildRemoteScene + 恢复）
+// ⑤ 空 Y 树跳过、反序列化异常不炸桥 ⑥ 卸载清理。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+import { planSceneDiff } from '@/components/design/canvas/document/reconcile'
+import {
+  createBoardNode,
+  type SceneDocument,
+  type SceneNode,
+} from '@/components/design/canvas/document/types'
+import {
+  sceneToYTree,
+  type CollabSceneDocument,
+} from '@allbluecn/collab-core/canvas-tree'
+import {
+  createCanvasRemoteBinding,
+  type CanvasRemoteBinding,
+  type CanvasRemoteEngineTarget,
+} from '../canvas-remote'
+import { CANVAS_LOCAL_ORIGIN } from '../canvas-local'
+
+// ---------------------------------------------------------------------------
+// 夹具：SceneDocument 构造 + 双 Y.Doc 仿真 + 假引擎
+// ---------------------------------------------------------------------------
+
+const DEBOUNCE_MS = 20
+
+function boardNode(): SceneNode {
+  return createBoardNode('desktop')
+}
+
+function rectNode(id: string, x = 0, y = 0, parentId = 'board'): SceneNode {
+  return { id, kind: 'shape', type: 'rect', parentId, x, y, width: 100, height: 50 }
+}
+
+function frameNode(id: string, name: string): SceneNode {
+  return {
+    id,
+    kind: 'shape',
+    type: 'frame',
+    parentId: 'board',
+    name,
+    x: 0,
+    y: 0,
+    width: 390,
+    height: 844,
+  }
+}
+
+function docOf(nodes: SceneNode[]): SceneDocument {
+  return { version: 1, meta: { device: 'desktop' }, nodes }
+}
+
+type EngineCall = { op: 'apply' | 'rebuild'; doc: SceneDocument }
+
+/** 记录调用的假引擎（真实 DocEngine 的结构子集；applyMode 可运行时切换） */
+function makeEngineFake(): CanvasRemoteEngineTarget & {
+  calls: EngineCall[]
+  applyMode: 'ok' | 'fail-bool' | 'throw'
+} {
+  const calls: EngineCall[] = []
+  return {
+    calls,
+    applyMode: 'ok',
+    applyRemoteScene(doc) {
+      calls.push({ op: 'apply', doc })
+      if (this.applyMode === 'fail-bool') return false
+      if (this.applyMode === 'throw') throw new Error('增量应用爆炸（仿真）')
+      return true
+    },
+    rebuildRemoteScene(doc) {
+      calls.push({ op: 'rebuild', doc })
+    },
+  }
+}
+
+const cleanups: Array<() => void> = []
+
+interface Rig {
+  localDoc: Y.Doc
+  engine: ReturnType<typeof makeEngineFake>
+  binding: CanvasRemoteBinding
+  applyCalls(): EngineCall[]
+  lastApplied(): SceneDocument
+  /** 远端作者编辑：peerDoc 对账式写入 → applyUpdate 同步到本端（模拟远端到达） */
+  remoteEdit(scene: SceneDocument): void
+}
+
+function makeRig(seed: SceneDocument | null): Rig {
+  const localDoc = new Y.Doc()
+  const peerDoc = new Y.Doc()
+  if (seed) {
+    // 种子只写 peer，再经 applyUpdate 复制到 local——两端必须共享同一份 op
+    // 历史（同 clientID）：独立种子化的两份 doc 经 update 合并时 Y.Map 是
+    // op 级 LWW 而非状态覆盖，后续远端 delete 无法 tombstone 本端自己的 add
+    sceneToYTree(seed as unknown as CollabSceneDocument, peerDoc)
+    Y.applyUpdate(localDoc, Y.encodeStateAsUpdate(peerDoc), 'seed-replay')
+  }
+  const engine = makeEngineFake()
+  const binding = createCanvasRemoteBinding(
+    { doc: localDoc, engine },
+    { debounceMs: DEBOUNCE_MS },
+  )
+  cleanups.push(() => {
+    binding.destroy()
+    localDoc.destroy()
+    peerDoc.destroy()
+  })
+  return {
+    localDoc,
+    engine,
+    binding,
+    applyCalls: () => engine.calls.filter((call) => call.op === 'apply'),
+    lastApplied: () => {
+      const applies = engine.calls.filter((call) => call.op === 'apply')
+      expect(applies.length).toBeGreaterThan(0)
+      return applies[applies.length - 1].doc
+    },
+    remoteEdit(scene) {
+      sceneToYTree(scene as unknown as CollabSceneDocument, peerDoc)
+      // yjs 13 无 Doc.applyUpdate 实例方法：统一走静态 Y.applyUpdate（origin 标记远端到达）
+      Y.applyUpdate(localDoc, Y.encodeStateAsUpdate(peerDoc), 'remote-peer')
+    },
+  }
+}
+
+/** 消化挂载初始种子 flush（绑定创建即调度一次对账）后回到静默基线，返回种子文档 */
+function settle(rig: Rig): SceneDocument {
+  vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+  expect(rig.applyCalls().length).toBe(1)
+  const seeded = rig.lastApplied()
+  rig.engine.calls.length = 0
+  return seeded
+}
+
+const baseline = (): SceneDocument => docOf([boardNode(), rectNode('r1', 10, 20)])
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// 远端 add / remove / patch / order → 引擎收到的文档经 planSceneDiff 产出正确计划
+// ---------------------------------------------------------------------------
+
+describe('远端变更 → 增量应用', () => {
+  it('远端 add：引擎收到含新节点的文档，diff 计划 toAdd 命中', () => {
+    const rig = makeRig(baseline())
+    const prev = settle(rig)
+
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 10, 20), rectNode('r2', 30, 40)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1)
+    expect(calls[0].doc.nodes.map((node) => node.id)).toEqual(['board', 'r1', 'r2'])
+    const plan = planSceneDiff(prev, calls[0].doc)
+    expect(plan.toAdd.map((node) => node.id)).toEqual(['r2'])
+    expect(plan.toRemove).toEqual([])
+    expect(plan.toPatch).toEqual([])
+    expect(plan.orderChanged).toBe(true) // 根层序 [r1] → [r1, r2]
+  })
+
+  it('远端 remove：引擎收到缺删节点的文档，diff 计划 toRemove 命中', () => {
+    const seeded = docOf([boardNode(), rectNode('r1', 10, 20), rectNode('r2', 30, 40)])
+    const rig = makeRig(seeded)
+    const prev = settle(rig)
+
+    rig.remoteEdit(baseline())
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1)
+    expect(calls[0].doc.nodes.map((node) => node.id)).toEqual(['board', 'r1'])
+    const plan = planSceneDiff(prev, calls[0].doc)
+    expect(plan.toRemove).toEqual(['r2'])
+    expect(plan.toAdd).toEqual([])
+    expect(plan.toPatch).toEqual([])
+  })
+
+  it('远端 patch：引擎收到更新字段的文档，diff 计划 toPatch 命中且序不变', () => {
+    const rig = makeRig(baseline())
+    const prev = settle(rig)
+
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 50, 60)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1)
+    const patched = calls[0].doc.nodes.find((node) => node.id === 'r1')
+    expect(patched?.x).toBe(50)
+    expect(patched?.y).toBe(60)
+    const plan = planSceneDiff(prev, calls[0].doc)
+    expect(plan.toPatch).toEqual(['r1'])
+    expect(plan.toAdd).toEqual([])
+    expect(plan.toRemove).toEqual([])
+    expect(plan.orderChanged).toBe(false)
+  })
+
+  it('远端 order：引擎收到新兄弟序的文档，diff 计划 orderChanged 且无增删改', () => {
+    const seeded = docOf([boardNode(), rectNode('r1', 10, 20), rectNode('r2', 30, 40)])
+    const rig = makeRig(seeded)
+    const prev = settle(rig)
+
+    // 同内容仅换根层序：[r1, r2] → [r2, r1]
+    rig.remoteEdit(docOf([boardNode(), rectNode('r2', 30, 40), rectNode('r1', 10, 20)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1)
+    expect(calls[0].doc.nodes.map((node) => node.id)).toEqual(['board', 'r2', 'r1'])
+    const plan = planSceneDiff(prev, calls[0].doc)
+    expect(plan.orderChanged).toBe(true)
+    expect(plan.toAdd).toEqual([])
+    expect(plan.toRemove).toEqual([])
+    expect(plan.toPatch).toEqual([])
+  })
+
+  it('防抖合并：窗口内连续两次远端变更只应用一次（最新态）', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 10, 20), rectNode('r2', 30, 40)]))
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 99, 98), rectNode('r2', 30, 40)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1)
+    const r1 = calls[0].doc.nodes.find((node) => node.id === 'r1')
+    expect(r1?.x).toBe(99) // 合并到最新态，不是逐条回放
+    expect(calls[0].doc.nodes.some((node) => node.id === 'r2')).toBe(true)
+  })
+
+  it('frame 改名（顶层标签节点）经桥同步到引擎文档', () => {
+    const rig = makeRig(docOf([boardNode(), frameNode('f1', '首页')]))
+    const prev = settle(rig)
+
+    rig.remoteEdit(docOf([boardNode(), frameNode('f1', '列表页')]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1)
+    expect(calls[0].doc.nodes.find((node) => node.id === 'f1')?.name).toBe('列表页')
+    const plan = planSceneDiff(prev, calls[0].doc)
+    expect(plan.toPatch).toEqual(['f1'])
+    expect(plan.labelsRename).toEqual([{ id: 'f1', name: '列表页' }])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 交互冻结：挂起不应用，解冻后对最新快照一次 diff 应用（非队列回放）
+// ---------------------------------------------------------------------------
+
+describe('交互冻结', () => {
+  it('冻结期远端变更不应用，解冻后一次应用最新态', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    rig.binding.setFrozen(true)
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 10, 20), rectNode('r2', 30, 40)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    expect(rig.applyCalls().length).toBe(0) // 冻结期不应用
+
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 77, 88), rectNode('r2', 30, 40)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    expect(rig.applyCalls().length).toBe(0) // 持续冻结持续挂起
+
+    rig.binding.setFrozen(false)
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1) // 一次性应用，非队列回放
+    const r1 = calls[0].doc.nodes.find((node) => node.id === 'r1')
+    expect(r1?.x).toBe(77) // 直接对最新快照 diff（中间态被丢弃）
+    expect(calls[0].doc.nodes.some((node) => node.id === 'r2')).toBe(true)
+  })
+
+  it('冻结期 reconcileNow 也不应用，解冻后补应用', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    rig.binding.setFrozen(true)
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 55, 66)]))
+    expect(() => {
+      rig.binding.reconcileNow()
+      vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    }).not.toThrow()
+    expect(rig.applyCalls().length).toBe(0)
+
+    rig.binding.setFrozen(false)
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    expect(rig.applyCalls().length).toBe(1)
+    expect(rig.applyCalls()[0].doc.nodes.find((node) => node.id === 'r1')?.x).toBe(55)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// rebuild 兜底：增量失败（抛异常 / 返回 false）→ rebuildRemoteScene 同快照兜底
+// ---------------------------------------------------------------------------
+
+describe('rebuild 兜底', () => {
+  it('applyRemoteScene 抛异常 → rebuildRemoteScene 收到同一快照，恢复后继续增量', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    rig.engine.applyMode = 'throw'
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 11, 22)]))
+    expect(() => vi.advanceTimersByTime(DEBOUNCE_MS + 5)).not.toThrow()
+
+    const calls = rig.engine.calls
+    expect(calls.length).toBe(2)
+    expect(calls[0].op).toBe('apply')
+    expect(calls[1].op).toBe('rebuild')
+    expect(calls[1].doc).toBe(calls[0].doc) // 同一快照直通兜底
+
+    // 兜底后基线已重置（引擎侧 appliedDoc=doc）：恢复增量模式继续正常应用
+    rig.engine.applyMode = 'ok'
+    rig.engine.calls.length = 0
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 33, 44)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    expect(rig.applyCalls().length).toBe(1)
+    expect(rig.engine.calls.every((call) => call.op === 'apply')).toBe(true)
+  })
+
+  it('applyRemoteScene 返回 false 同样触发 rebuildRemoteScene', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    rig.engine.applyMode = 'fail-bool'
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 12, 23)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+
+    const calls = rig.engine.calls
+    expect(calls.length).toBe(2)
+    expect(calls[0].op).toBe('apply')
+    expect(calls[1].op).toBe('rebuild')
+    expect(calls[1].doc).toBe(calls[0].doc)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 边界：初始种子 / 空 Y 树 / 反序列化异常 / reconcileNow / 卸载清理
+// ---------------------------------------------------------------------------
+
+describe('边界与生命周期', () => {
+  it('绑定创建即调度初始种子：已种子化的 room 首次对账应用当前态', () => {
+    const rig = makeRig(baseline())
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    const calls = rig.applyCalls()
+    expect(calls.length).toBe(1)
+    expect(calls[0].doc.nodes.map((node) => node.id)).toEqual(['board', 'r1'])
+    expect(rig.engine.calls.every((call) => call.op === 'apply')).toBe(true)
+  })
+
+  it('空 Y 树（room 未种子化）跳过应用；种子到达后正常应用', () => {
+    const rig = makeRig(null)
+    vi.advanceTimersByTime(DEBOUNCE_MS * 3)
+    expect(rig.applyCalls().length).toBe(0) // yTreeToScene null → 跳过
+
+    rig.remoteEdit(baseline())
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    expect(rig.applyCalls().length).toBe(1)
+  })
+
+  it('Y 树被写坏（反序列化异常）不炸桥、不误用引擎', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    // 直接把 nodes 分面写坏（非 Y.Map）→ yTreeToScene 抛错 → 桥吞掉等下一次
+    rig.localDoc.getMap('canvas').set('nodes', 42)
+    expect(() => vi.advanceTimersByTime(DEBOUNCE_MS + 5)).not.toThrow()
+    expect(rig.applyCalls().length).toBe(0)
+
+    // 后续远端 update 到达仍不炸桥不误用（写坏的 per-key LWW 态在被更高时钟
+    // 的写入覆盖前持续抛错——桥的职责是稳住页面，不猜状态）
+    expect(() => {
+      rig.remoteEdit(docOf([boardNode(), rectNode('r1', 70, 80)]))
+      vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    }).not.toThrow()
+  })
+
+  it('reconcileNow 绕过防抖立即应用', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 15, 25)]))
+    expect(rig.applyCalls().length).toBe(0) // 未经 timer 推进尚未应用
+
+    rig.binding.reconcileNow()
+    expect(rig.applyCalls().length).toBe(1)
+    expect(rig.applyCalls()[0].doc.nodes.find((node) => node.id === 'r1')?.x).toBe(15)
+  })
+
+  it('destroy 后不再响应远端变更；重复 destroy 幂等', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    rig.binding.destroy()
+    expect(() => rig.binding.destroy()).not.toThrow()
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 91, 92)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS * 3)
+    expect(rig.applyCalls().length).toBe(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 本地回声抑制（任务 28 验收点）：本端写 Y 带 CANVAS_LOCAL_ORIGIN → 桥跳过
+// ---------------------------------------------------------------------------
+
+describe('本地 origin 回声过滤', () => {
+  it('CANVAS_LOCAL_ORIGIN 的 update 不触发对账；远端 origin 照常', () => {
+    const rig = makeRig(baseline())
+    settle(rig)
+
+    // 任务 28 本地写 Y 的形态：transact + CANVAS_LOCAL_ORIGIN（引擎是写入源，
+    // appliedDoc 已是该态——回声对账是纯浪费）
+    rig.localDoc.transact(() => {
+      sceneToYTree(
+        docOf([boardNode(), rectNode('r1', 50, 60)]) as unknown as CollabSceneDocument,
+        rig.localDoc,
+      )
+    }, CANVAS_LOCAL_ORIGIN)
+    vi.advanceTimersByTime(DEBOUNCE_MS * 3)
+    expect(rig.applyCalls().length).toBe(0)
+
+    // 远端到达（remote-peer origin）不受过滤影响。远端编辑走「新增 r2」：
+    // 同键（r1）远端写入的时钟低于本端刚才的写，Y.Map LWW 会被本端压制，
+    // 断言会误判过滤行为
+    rig.remoteEdit(docOf([boardNode(), rectNode('r1', 50, 60), rectNode('r2', 30, 40)]))
+    vi.advanceTimersByTime(DEBOUNCE_MS + 5)
+    expect(rig.applyCalls().length).toBe(1)
+    expect(rig.lastApplied().nodes.find((node) => node.id === 'r2')?.x).toBe(30)
+  })
+})

package/src/lib/collab/bindings/__tests__/canvas-tree-perf.test.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 画布协同数据面性能逻辑基准（任务 30，§15「性能」的自动化腿）：
+// 大文档（1000 节点）场景下 sceneToYTree / yTreeToScene / planSceneDiff 的
+// 耗时上界与线性度守卫——防 O(n²) 回归。⚠ 非帧率测量：真浏览器 60fps 拖拽
+// 帧率属待人工验收（__canvasEngine 诊断钩子 + Chrome DevTools Performance，
+// 稳态/瞬态分开，方法对齐 memrec leafer-large-doc-perf），本套件只锁
+// 「数据面单次 round-trip 成本随规模线性」这一可自动化口径。
+//
+// 断言设计（CI 稳定优先）：
+//   1. 绝对上界：1000 节点单次操作 < 750ms / round-trip < 2000ms（宽松
+//      tripwire——线性实现实测为毫秒级，命中上界即说明已退化数量级）
+//   2. 线性度：t(1000)/t(250) < 12（O(n) 理论 4x + 2x 噪声余量；O(n²) 理论
+//      16x 起，必然越界）——噪声用三次取样取最小值压平
+
+import { describe, expect, it } from 'vitest'
+import { planSceneDiff } from '@/components/design/canvas/document/reconcile'
+import {
+  BOARD_NODE_ID,
+  createBoardNode,
+  type SceneDocument,
+  type SceneNode,
+} from '@/components/design/canvas/document/types'
+import { sceneToYTree, yTreeToScene } from '@allbluecn/collab-core/canvas-tree'
+import * as Y from 'yjs'
+
+function bigDoc(nodeCount: number): SceneDocument {
+  const nodes: SceneNode[] = [createBoardNode('desktop')]
+  for (let i = 0; i < nodeCount; i++) {
+    nodes.push({
+      id: `n${i}`,
+      kind: 'shape',
+      type: 'rect',
+      parentId: BOARD_NODE_ID,
+      x: (i % 50) * 120,
+      y: Math.floor(i / 50) * 80,
+      width: 100,
+      height: 60,
+      name: `rect-${i}`,
+    })
+  }
+  return { version: 1, meta: { device: 'desktop' }, nodes }
+}
+
+/** 三次取样取最小（压平 GC/JIT 噪声；首次运行含预热） */
+function timeOf(fn: () => void): number {
+  let best = Number.POSITIVE_INFINITY
+  for (let round = 0; round < 3; round++) {
+    const start = performance.now()
+    fn()
+    const cost = performance.now() - start
+    if (cost < best) best = cost
+  }
+  return best
+}
+
+describe('canvas 数据面性能逻辑基准（防 O(n²) 回归，非帧率）', () => {
+  it('1000 节点 sceneToYTree 单次写入有界', () => {
+    const doc = new Y.Doc()
+    const scene = bigDoc(1000)
+    const cost = timeOf(() => {
+      doc.transact(() => {
+        sceneToYTree(scene as never, doc)
+      })
+    })
+    expect(cost).toBeLessThan(750)
+  })
+
+  it('1000 节点 yTreeToScene 单次反序列化有界', () => {
+    const doc = new Y.Doc()
+    sceneToYTree(bigDoc(1000) as never, doc)
+    const cost = timeOf(() => {
+      const scene = yTreeToScene(doc)
+      expect(scene).not.toBeNull()
+      expect(scene!.nodes).toHaveLength(1001)
+    })
+    expect(cost).toBeLessThan(750)
+  })
+
+  it('1000 节点 planSceneDiff 单次计划有界', () => {
+    const prev = bigDoc(1000)
+    const next = bigDoc(1000)
+    const patched = next.nodes.map((n) => (n.id === 'n500' ? { ...n, x: n.x + 5 } : n))
+    const cost = timeOf(() => {
+      const plan = planSceneDiff(prev, { ...next, nodes: patched })
+      expect(plan.toPatch).toEqual(['n500'])
+    })
+    expect(cost).toBeLessThan(750)
+  })
+
+  it('1000 节点完整 round-trip（读→diff→写）有界', () => {
+    const doc = new Y.Doc()
+    sceneToYTree(bigDoc(1000) as never, doc)
+    const next = bigDoc(1000)
+    const patched = { ...next, nodes: next.nodes.map((n) => (n.id === 'n250' ? { ...n, y: n.y + 9 } : n)) }
+    // 写入目标用一次性 scratch doc（幂等取样：timeOf 三轮重复执行，被测面
+    // 不得自变更——否则第二轮起 diff 恒空、断言退化为平凡真）
+    const cost = timeOf(() => {
+      const fromY = yTreeToScene(doc) as unknown as SceneDocument
+      const plan = planSceneDiff(fromY, patched)
+      expect(plan.toPatch).toEqual(['n250'])
+      const scratch = new Y.Doc()
+      scratch.transact(() => {
+        sceneToYTree(patched as never, scratch)
+      })
+    })
+    expect(cost).toBeLessThan(2000)
+  })
+
+  it('线性度：1000 节点耗时 / 250 节点耗时 < 12（O(n) 理论 4x；O(n²) 16x 起必红）', () => {
+    const writeAt = (n: number): number => {
+      const doc = new Y.Doc()
+      const scene = bigDoc(n)
+      return timeOf(() => {
+        doc.transact(() => {
+          sceneToYTree(scene as never, doc)
+        })
+      })
+    }
+    const readAt = (n: number): number => {
+      const doc = new Y.Doc()
+      sceneToYTree(bigDoc(n) as never, doc)
+      return timeOf(() => {
+        yTreeToScene(doc)
+      })
+    }
+    const writeRatio = writeAt(1000) / Math.max(writeAt(250), 0.001)
+    const readRatio = readAt(1000) / Math.max(readAt(250), 0.001)
+    expect(writeRatio).toBeLessThan(12)
+    expect(readRatio).toBeLessThan(12)
+  })
+})