@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,583 @@
+// 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/>.
+
+// 画布本地编辑 → Y 转写与拖拽 awareness 影子测试（P4b，任务 28，规格 §7.2
+// 本地方向）：假引擎（可控事件发射）+ 真 Y.Doc + 真 Awareness（同 T25/T27
+// bindings 先例：脱离组件树与 Leafer 单测）。
+// 覆盖简报场景：① 单元素属性改 → 对应 Y.Map set 且仅一个节点变更（op 计数）
+// ② 新增/删除节点 Y 结构正确 ③ 拖拽全程 Y update 计数为 0（性能红线）、
+// 释放后恰 1 次 ④ 双客户端并发拖不同元素 merge 无丢失（makeRig 模板：
+// peer 独写种子 + applyUpdate 复制，op 历史不分叉）。
+// headless 限制（memrec）：不用 drag 真事件——引擎 fake 直接 emit 拖拽
+// 生命周期布尔（真实引擎 DragEvent.START/END → onDragChange 的转译由
+// engine 单测锁定）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+import { Awareness } from 'y-protocols/awareness'
+import { planSceneDiff } from '@/components/design/canvas/document/reconcile'
+import {
+  createBoardNode,
+  type SceneDocument,
+  type SceneNode,
+} from '@/components/design/canvas/document/types'
+import { sceneToYTree, yTreeToScene } from '@allbluecn/collab-core/canvas-tree'
+import type { CollabAwareness } from '../../provider'
+import { CANVAS_AWARENESS_KEY } from '../canvas-presence'
+import {
+  CANVAS_DRAG_FIELD,
+  CANVAS_DRAG_THROTTLE_MS,
+  CANVAS_LOCAL_ORIGIN,
+  createCanvasLocalBinding,
+  parseCanvasDragShadow,
+  type CanvasLocalEngineSource,
+} from '../canvas-local'
+import { createCanvasRemoteBinding } from '../canvas-remote'
+
+// ---------------------------------------------------------------------------
+// 夹具：SceneDocument 构造 + 假引擎 + 双 Y.Doc 仿真 + 真 Awareness
+// ---------------------------------------------------------------------------
+
+function boardNode(): SceneNode {
+  return createBoardNode('desktop')
+}
+
+function rectNode(id: string, x = 0, y = 0, parentId: string | null = 'board'): SceneNode {
+  return { id, kind: 'shape', type: 'rect', parentId, x, y, width: 100, height: 50 }
+}
+
+function docOf(nodes: SceneNode[]): SceneDocument {
+  return { version: 1, meta: { device: 'desktop' }, nodes }
+}
+
+/** engine 结构子集 fake：可控事件发射（真实 LeaferEngine 兼容直传） */
+function makeEngineFake(): CanvasLocalEngineSource & {
+  setDoc(doc: SceneDocument): void
+  setSelection(ids: string[]): void
+  emitDocChange(): void
+  emitDrag(dragging: boolean): void
+} & {
+  applyRemoteScene(doc: SceneDocument): boolean
+  rebuildRemoteScene(doc: SceneDocument): void
+} {
+  let current: SceneDocument = docOf([boardNode()])
+  let selection: string[] = []
+  const docListeners = new Set<(doc: SceneDocument) => void>()
+  const dragListeners = new Set<(dragging: boolean) => void>()
+  // 增量应用基线（真引擎 appliedDoc 同款口径）：applyRemoteScene 以「上次
+  // 应用的远端态」为 prev 跑 planSceneDiff，计划命中字段落到 current 上——
+  // 本地拖拽未入计划的字段不被远端收敛触碰。applied=null（基线未建）返回
+  // false 走 rebuild 兜底（同真引擎 applyRemoteScene 的 false 分支）
+  let applied: SceneDocument | null = null
+  const applyRemote = (doc: SceneDocument, incremental: boolean) => {
+    if (incremental) {
+      if (!applied) return false
+      const plan = planSceneDiff(applied, doc)
+      const docById = new Map(doc.nodes.map((node) => [node.id, node]))
+      const curIds = new Set(current.nodes.map((node) => node.id))
+      const nodes = current.nodes
+        .filter((node) => !plan.toRemove.includes(node.id))
+        .map((node) =>
+          plan.toPatch.includes(node.id) && docById.has(node.id)
+            ? (docById.get(node.id) as SceneNode)
+            : node,
+        )
+      for (const added of plan.toAdd) {
+        const fresh = docById.get(added.id)
+        if (fresh && !curIds.has(added.id)) nodes.push(fresh)
+      }
+      current = { ...current, nodes }
+    } else {
+      current = doc
+    }
+    applied = doc
+    for (const cb of [...docListeners]) cb(current)
+    return true
+  }
+  return {
+    getDoc: () => current,
+    getSelection: () => [...selection],
+    onDocChange(cb) {
+      docListeners.add(cb)
+      return () => {
+        docListeners.delete(cb)
+      }
+    },
+    onDragChange(cb) {
+      dragListeners.add(cb)
+      return () => {
+        dragListeners.delete(cb)
+      }
+    },
+    setDoc(doc) {
+      current = doc
+    },
+    setSelection(ids) {
+      selection = ids
+    },
+    emitDocChange() {
+      for (const cb of [...docListeners]) cb(current)
+    },
+    emitDrag(dragging) {
+      for (const cb of [...dragListeners]) cb(dragging)
+    },
+    applyRemoteScene: (doc) => applyRemote(doc, true),
+    rebuildRemoteScene: (doc) => {
+      applyRemote(doc, false)
+    },
+  }
+}
+
+type EngineFake = ReturnType<typeof makeEngineFake>
+
+const cleanups: Array<() => void> = []
+
+interface Rig {
+  doc: Y.Doc
+  peerDoc: Y.Doc
+  engine: EngineFake
+  awareness: Awareness
+  /** 拖拽冻结接力目标（T27 桥 / T25 presence 的 setFrozen 替身） */
+  frozen: boolean[]
+  binding: ReturnType<typeof createCanvasLocalBinding>
+  /** Y update 事件计数（事务级）+ origin 记录 */
+  updates: { count: number; origins: unknown[] }
+  /** 读本端 awareness 的 canvas key */
+  canvasState(): Record<string, unknown> | undefined
+}
+
+function makeRig(
+  seed: SceneDocument | null,
+  opts: { awareness?: boolean; seedUpdate?: Uint8Array } = {},
+): Rig {
+  const doc = new Y.Doc()
+  const peerDoc = new Y.Doc()
+  if (opts.seedUpdate) {
+    // 双 Doc 共享同一份种子 op 历史（makeRig 纪律）：独立种子化 = peer
+    // clientID 各异、op 历史分叉，后续 merge 测试的 update 会互相 shadow
+    Y.applyUpdate(doc, opts.seedUpdate, 'seed-replay')
+  } else if (seed) {
+    // 种子只写 peer，再经 applyUpdate 复制到本端——两端共享同一份 op 历史
+    // （同 clientID），独立种子化会导致 op 级 LWW 分叉（T27 makeRig 纪律）
+    seedToDoc(seed, peerDoc)
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(peerDoc), 'seed-replay')
+  }
+  const engine = makeEngineFake()
+  if (seed) engine.setDoc(seed)
+  const awareness = opts.awareness === false ? null : new Awareness(doc)
+  const frozen: boolean[] = []
+  const updates = { count: 0, origins: [] as unknown[] }
+  doc.on('update', (_update: Uint8Array, origin: unknown) => {
+    updates.count += 1
+    updates.origins.push(origin)
+  })
+  const binding = createCanvasLocalBinding({
+    doc,
+    engine,
+    awareness: (awareness as unknown as CollabAwareness | null) ?? null,
+    freezeTargets: [
+      {
+        setFrozen(next) {
+          frozen.push(next)
+        },
+      },
+    ],
+  })
+  cleanups.push(() => {
+    binding.destroy()
+    awareness?.destroy()
+    doc.destroy()
+    peerDoc.destroy()
+  })
+  return {
+    doc,
+    peerDoc,
+    engine,
+    awareness: awareness as Awareness,
+    frozen,
+    binding,
+    updates,
+    canvasState: () => {
+      const local = (awareness as Awareness | null)?.getLocalState() as
+        | Record<string, unknown>
+        | null
+      return local?.[CANVAS_AWARENESS_KEY] as Record<string, unknown> | undefined
+    },
+  }
+}
+
+/** 种子写入（不经绑定，直接对账式建树） */
+function seedToDoc(scene: SceneDocument, target: Y.Doc): void {
+  sceneToYTree(scene as never, target)
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// ① 单元素属性改 → 对应 Y.Map set 且仅一个节点变更（op 计数断言）
+// ---------------------------------------------------------------------------
+
+describe('本地属性改 → Y 转写', () => {
+  it('改 r1.x 只产生一次 update、nodes 只变更 r1 一个 key、origin 标记本端', () => {
+    // board 在种子与引擎 doc 间共享同一实例（createBoardNode 的 paint id
+    // 每次调用随机生成——不共享会被误判为 board 变更）
+    const board = boardNode()
+    const rig = makeRig(docOf([board, rectNode('r1', 10, 20), rectNode('r2', 30, 40), rectNode('r3', 50, 60)]))
+    const nodesY = rig.doc.getMap<Y.Map<unknown>>('canvas').get('nodes') as Y.Map<Y.Map<unknown>>
+    const keysChanges: string[][] = []
+    nodesY.observe((event) => {
+      keysChanges.push([...event.keysChanged])
+    })
+
+    rig.engine.setDoc(
+      docOf([board, rectNode('r1', 99, 20), rectNode('r2', 30, 40), rectNode('r3', 50, 60)]),
+    )
+    rig.engine.emitDocChange()
+
+    expect(rig.updates.count).toBe(1)
+    expect(rig.updates.origins[0]).toBe(CANVAS_LOCAL_ORIGIN)
+    expect(keysChanges).toEqual([['r1']])
+    const scene = yTreeToScene(rig.doc)
+    expect(scene?.nodes.find((node) => node.id === 'r1')?.x).toBe(99)
+    expect(scene?.nodes.find((node) => node.id === 'r2')?.x).toBe(30)
+  })
+
+  it('引擎内容与 Y 已一致（远端回灌）→ 零 update 不回写', () => {
+    const rig = makeRig(docOf([boardNode(), rectNode('r1', 10, 20)]))
+    rig.engine.emitDocChange() // 引擎 doc == Y 态（种子同步源）
+    expect(rig.updates.count).toBe(0)
+  })
+
+  it('投影盲区字段变化（aspectLocked/zIndex）→ 仍写 Y 不丢同步', () => {
+    const board = boardNode()
+    const rig = makeRig(docOf([board, rectNode('r1', 10, 20)]))
+    const blind = {
+      ...rectNode('r1', 10, 20),
+      aspectLocked: true,
+      zIndex: 7,
+    }
+    rig.engine.setDoc(docOf([board, blind]))
+    rig.engine.emitDocChange()
+    expect(rig.updates.count).toBe(1)
+    const scene = yTreeToScene(rig.doc)
+    const r1 = scene?.nodes.find((node) => node.id === 'r1')
+    expect(r1?.aspectLocked).toBe(true)
+    expect(r1?.zIndex).toBe(7)
+  })
+
+  it('boardMeta 变化（background）→ 写 Y', () => {
+    const board = boardNode()
+    const rig = makeRig(docOf([board, rectNode('r1', 10, 20)]))
+    rig.engine.setDoc({
+      version: 1,
+      meta: { device: 'desktop', background: '#ff0000' },
+      nodes: [board, rectNode('r1', 10, 20)],
+    })
+    rig.engine.emitDocChange()
+    expect(rig.updates.count).toBe(1)
+    const scene = yTreeToScene(rig.doc)
+    expect(scene?.meta.background).toBe('#ff0000')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ② 新增 / 删除节点 → Y 结构正确
+// ---------------------------------------------------------------------------
+
+describe('本地结构变更 → Y 结构', () => {
+  it('新增节点：nodes 增 key、根序扩展、round-trip 与引擎一致', () => {
+    const board = boardNode()
+    const rig = makeRig(docOf([board, rectNode('r1', 10, 20)]))
+
+    rig.engine.setDoc(docOf([board, rectNode('r1', 10, 20), rectNode('r2', 30, 40)]))
+    rig.engine.emitDocChange()
+
+    expect(rig.updates.count).toBe(1)
+    const scene = yTreeToScene(rig.doc)
+    expect(scene?.nodes.map((node) => node.id)).toEqual(['board', 'r1', 'r2'])
+  })
+
+  it('删除节点：nodes 摘 key、order 摘引用', () => {
+    const board = boardNode()
+    const rig = makeRig(docOf([board, rectNode('r1', 10, 20), rectNode('r2', 30, 40)]))
+
+    rig.engine.setDoc(docOf([board, rectNode('r1', 10, 20)]))
+    rig.engine.emitDocChange()
+
+    expect(rig.updates.count).toBe(1)
+    const scene = yTreeToScene(rig.doc)
+    expect(scene?.nodes.map((node) => node.id)).toEqual(['board', 'r1'])
+    // order 口径（T26 契约）：根层（parentId=null，恒为 board）用 __root__，
+    // board 的孩子挂在 key='board' 的 per-parent 序
+    const orderY = rig.doc.getMap<Y.Map<unknown>>('canvas').get('order') as Y.Map<Y.Array<string>>
+    expect(orderY.get('__root__')?.toJSON()).toEqual(['board'])
+    expect(orderY.get('board')?.toJSON()).toEqual(['r1'])
+  })
+
+  it('嵌套新增（frame + child）：per-parent 序正确', () => {
+    const board = boardNode()
+    const rig = makeRig(docOf([board, rectNode('r1', 10, 20)]))
+    const frame: SceneNode = {
+      id: 'f1',
+      kind: 'shape',
+      type: 'frame',
+      parentId: 'board',
+      name: '画板',
+      x: 0,
+      y: 0,
+      width: 390,
+      height: 844,
+    }
+    rig.engine.setDoc(docOf([board, rectNode('r1', 10, 20), frame, rectNode('c1', 1, 2, 'f1')]))
+    rig.engine.emitDocChange()
+
+    const scene = yTreeToScene(rig.doc)
+    expect(scene?.nodes.map((node) => node.id)).toEqual(['board', 'r1', 'f1', 'c1'])
+    const orderY = rig.doc.getMap<Y.Map<unknown>>('canvas').get('order') as Y.Map<Y.Array<string>>
+    expect(orderY.get('f1')?.toJSON()).toEqual(['c1'])
+    expect(orderY.get('board')?.toJSON()).toEqual(['r1', 'f1'])
+    expect(orderY.get('__root__')?.toJSON()).toEqual(['board'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③ 拖拽影子：全程 Y update = 0（性能红线）、awareness 节流、释放恰 1 次
+// ---------------------------------------------------------------------------
+
+describe('拖拽 awareness 影子与 Y 红线', () => {
+  it('拖拽全程 Y 零 update、影子 50ms 节流上报、释放后恰 1 次 update 且影子清除', () => {
+    const rig = makeRig(docOf([boardNode(), rectNode('r1', 0, 0), rectNode('r2', 30, 40)]))
+    rig.engine.setSelection(['r1'])
+    const setFieldSpy = vi.spyOn(rig.awareness, 'setLocalStateField')
+
+    // 拖拽开始：冻结接力 + leading 即时影子
+    rig.engine.emitDrag(true)
+    expect(rig.frozen).toEqual([true])
+    expect(rig.updates.count).toBe(0)
+    const drag0 = parseCanvasDragShadow(rig.canvasState()?.[CANVAS_DRAG_FIELD])
+    expect(drag0?.items).toEqual([{ id: 'r1', x: 0, y: 0 }])
+
+    // 拖拽中连续移动（每 10ms 一次，窗口内合并尾随）：Y 恒零写
+    for (let step = 1; step <= 4; step += 1) {
+      rig.engine.setDoc(docOf([boardNode(), rectNode('r1', step * 10, 0), rectNode('r2', 30, 40)]))
+      rig.engine.emitDocChange()
+      vi.advanceTimersByTime(10)
+      expect(rig.updates.count).toBe(0)
+    }
+    // 节流窗口收敛：leading(1) + 尾随(1) = 2 次 canvas 写（含影子）
+    vi.advanceTimersByTime(CANVAS_DRAG_THROTTLE_MS)
+    expect(rig.updates.count).toBe(0)
+    const dragWrites = setFieldSpy.mock.calls.filter(
+      ([key]) => key === CANVAS_AWARENESS_KEY,
+    )
+    expect(dragWrites.length).toBe(2)
+    const trailing = parseCanvasDragShadow(rig.canvasState()?.[CANVAS_DRAG_FIELD])
+    expect(trailing?.items).toEqual([{ id: 'r1', x: 40, y: 0 }])
+
+    // 释放：最终态恰 1 次 update、影子清除、解冻接力
+    rig.engine.setDoc(docOf([boardNode(), rectNode('r1', 123, 45), rectNode('r2', 30, 40)]))
+    rig.engine.emitDrag(false)
+    expect(rig.updates.count).toBe(1)
+    expect(rig.updates.origins[0]).toBe(CANVAS_LOCAL_ORIGIN)
+    expect(rig.canvasState()?.[CANVAS_DRAG_FIELD]).toBeUndefined()
+    expect(rig.frozen).toEqual([true, false])
+    const scene = yTreeToScene(rig.doc)
+    expect(scene?.nodes.find((node) => node.id === 'r1')?.x).toBe(123)
+    expect(scene?.nodes.find((node) => node.id === 'r1')?.y).toBe(45)
+
+    // 释放后的挂起影子 timer 不复活（清除后无尾随写）
+    vi.advanceTimersByTime(CANVAS_DRAG_THROTTLE_MS * 2)
+    expect(rig.canvasState()?.[CANVAS_DRAG_FIELD]).toBeUndefined()
+    expect(rig.updates.count).toBe(1)
+  })
+
+  it('释放时新位置直接进 Y（emitDrag(false) 前最后一次 doc 变化也被捕获）', () => {
+    const rig = makeRig(docOf([boardNode(), rectNode('r1', 0, 0)]))
+    rig.engine.setSelection(['r1'])
+    rig.engine.emitDrag(true)
+    rig.engine.setDoc(docOf([boardNode(), rectNode('r1', 55, 66)]))
+    rig.engine.emitDocChange()
+    // 不推进节流 timer，直接释放：最终态写 Y 不得依赖影子 timer
+    rig.engine.emitDrag(false)
+    const scene = yTreeToScene(rig.doc)
+    expect(scene?.nodes.find((node) => node.id === 'r1')?.x).toBe(55)
+    expect(scene?.nodes.find((node) => node.id === 'r1')?.y).toBe(66)
+    expect(rig.updates.count).toBe(1)
+  })
+
+  it('未选中的拖拽（画布平移）不写影子也不写 Y', () => {
+    const rig = makeRig(docOf([boardNode(), rectNode('r1', 0, 0)]))
+    rig.engine.setSelection([])
+    rig.engine.emitDrag(true)
+    expect(rig.canvasState()?.[CANVAS_DRAG_FIELD]).toBeUndefined()
+    rig.engine.emitDrag(false)
+    expect(rig.updates.count).toBe(0)
+  })
+
+  it('noop 模式（awareness null）：影子跳过、Y 写与冻结接力照常', () => {
+    const rig = makeRig(docOf([boardNode(), rectNode('r1', 0, 0)]), { awareness: false })
+    rig.engine.setSelection(['r1'])
+    rig.engine.emitDrag(true)
+    rig.engine.setDoc(docOf([boardNode(), rectNode('r1', 20, 30)]))
+    rig.engine.emitDrag(false)
+    expect(rig.frozen).toEqual([true, false])
+    expect(rig.updates.count).toBe(1)
+  })
+
+  it('destroy 于拖拽中：解冻接力目标、清影子、清挂起 timer、断订阅', () => {
+    const rig = makeRig(docOf([boardNode(), rectNode('r1', 0, 0)]))
+    rig.engine.setSelection(['r1'])
+    rig.engine.emitDrag(true)
+    rig.engine.setDoc(docOf([boardNode(), rectNode('r1', 10, 0)]))
+    rig.engine.emitDocChange() // 排入尾随节流
+    rig.binding.destroy()
+    // I2 防御：本绑定被单独重建（引擎 remount/HMR）时，冻结过的接力目标
+    // 必须解冻——否则 T27 永久冻结、远端回放停摆
+    expect(rig.frozen).toEqual([true, false])
+    vi.advanceTimersByTime(CANVAS_DRAG_THROTTLE_MS * 2)
+    expect(rig.canvasState()?.[CANVAS_DRAG_FIELD]).toBeUndefined()
+    expect(rig.updates.count).toBe(0)
+    // 订阅已断：引擎再变不写 Y
+    rig.engine.setDoc(docOf([boardNode(), rectNode('r1', 99, 0)]))
+    rig.engine.emitDocChange()
+    expect(rig.updates.count).toBe(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ④ 双客户端并发拖不同元素 → merge 无丢失（makeRig 双 Doc 模板）
+// ---------------------------------------------------------------------------
+
+describe('双客户端并发拖拽 merge', () => {
+  it('B 释放落在 A 拖拽中：A 释放不回滚 B 的 r2，Y 与双端引擎收敛一致', () => {
+    // 全栈真并发（审查 C1）：双端各持 本地桥 + T27 远端桥 + 有状态引擎
+    // fake（applyRemoteScene 真改 current 并 notify，同真引擎）。B 的释放经
+    // 中继（provider 层语义）落在 A 拖拽中——A 的 T27 冻结期仅记 pending
+    // 不 flush，引擎 r2 陈旧；A 释放若先写 Y 后解冻，全量对账会把 r2 回滚。
+    const board = boardNode()
+    const seed = docOf([board, rectNode('r1', 0, 0), rectNode('r2', 30, 40)])
+    // 共享种子：先建一份 seed op 历史，两端 apply 同一份二进制（独立种子化
+    // 会让 peer clientID 各异、op 历史分叉，merge 时同键写入互相 shadow）
+    const seedDoc = new Y.Doc()
+    seedToDoc(seed, seedDoc)
+    const seedUpdate = Y.encodeStateAsUpdate(seedDoc)
+    seedDoc.destroy()
+
+    const makeFullRig = () => {
+      const doc = new Y.Doc()
+      Y.applyUpdate(doc, seedUpdate, 'seed-replay')
+      const awareness = new Awareness(doc)
+      const engine = makeEngineFake()
+      engine.setDoc(seed)
+      const updates = { count: 0, origins: [] as unknown[] }
+      doc.on('update', (_u: Uint8Array, origin: unknown) => {
+        updates.count += 1
+        updates.origins.push(origin)
+      })
+      // T27 远端桥 + 本地桥（冻结接力目标即 T27 本体：setFrozen/reconcileNow
+      // 结构兼容 CanvasFreezeTarget）
+      const remoteBinding = createCanvasRemoteBinding(
+        { doc, engine },
+        { debounceMs: 20 },
+      )
+      const binding = createCanvasLocalBinding({
+        doc,
+        engine,
+        awareness: awareness as unknown as CollabAwareness,
+        freezeTargets: [remoteBinding],
+      })
+      cleanups.push(() => {
+        binding.destroy()
+        remoteBinding.destroy()
+        awareness.destroy()
+        doc.destroy()
+      })
+      return { doc, engine, binding, updates }
+    }
+    const a = makeFullRig()
+    const b = makeFullRig()
+    // 双向 update 中继（provider 层语义：Y update 全双工同步，绕过绑定层）
+    a.doc.on('update', (update: Uint8Array) => {
+      Y.applyUpdate(b.doc, update, 'relay-a2b')
+    })
+    b.doc.on('update', (update: Uint8Array) => {
+      Y.applyUpdate(a.doc, update, 'relay-b2a')
+    })
+    // 挂载种子对齐（wiring 语义）：T27 初始 reconcile 消化后引擎 appliedDoc
+    // 基线已建（否则首个远端 flush 走 rebuild 全量兜底，非拖拽期常态）
+    vi.advanceTimersByTime(30)
+    expect(a.engine.getDoc().nodes.map((node) => node.id)).toEqual(['board', 'r1', 'r2'])
+
+    // A 开始拖 r1（T27 冻结）
+    a.engine.setSelection(['r1'])
+    a.engine.emitDrag(true)
+
+    // B 拖 r2 并释放：写 Y_b → 中继落进 a.doc（A frozen → T27 只记 pending，
+    // A 引擎 r2 保持陈旧）
+    b.engine.setSelection(['r2'])
+    b.engine.emitDrag(true)
+    b.engine.setDoc(docOf([board, rectNode('r1', 0, 0), rectNode('r2', 300, 400)]))
+    b.engine.emitDocChange()
+    b.engine.emitDrag(false)
+    expect(a.updates.origins).toContain('relay-b2a')
+
+    // A 移动 r1 后释放：解冻 → T27 同步收敛 B 的 r2 进引擎 → 最终态写 Y
+    a.engine.setDoc(docOf([board, rectNode('r1', 100, 200), rectNode('r2', 30, 40)]))
+    a.engine.emitDrag(false)
+
+    // A 端（同步收敛后）：B 的 r2 移动在 Y 与引擎中都活着
+    const sceneA = yTreeToScene(a.doc)
+    expect(sceneA?.nodes.find((node) => node.id === 'r2')?.x).toBe(300)
+    expect(a.engine.getDoc().nodes.find((node) => node.id === 'r2')?.x).toBe(300)
+    expect(sceneA?.nodes.find((node) => node.id === 'r1')?.x).toBe(100)
+    expect(a.engine.getDoc().nodes.find((node) => node.id === 'r1')?.x).toBe(100)
+
+    // B 端：中继收到 A 的释放写，T27(B) 防抖 flush 后引擎收敛
+    vi.advanceTimersByTime(40)
+    const sceneB = yTreeToScene(b.doc)
+    expect(sceneB?.nodes.find((node) => node.id === 'r1')?.x).toBe(100)
+    expect(sceneB?.nodes.find((node) => node.id === 'r2')?.x).toBe(300)
+    expect(b.engine.getDoc().nodes.find((node) => node.id === 'r1')?.x).toBe(100)
+    expect(b.engine.getDoc().nodes.find((node) => node.id === 'r2')?.x).toBe(300)
+    expect(sceneB?.nodes.map((node) => node.id)).toEqual(['board', 'r1', 'r2'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 影子 schema 解析（远端渲染插件消费面）
+// ---------------------------------------------------------------------------
+
+describe('parseCanvasDragShadow', () => {
+  it('合法载荷解析、畸形 fail-closed 丢弃', () => {
+    expect(parseCanvasDragShadow({ items: [{ id: 'r1', x: 1, y: 2 }], ts: 5 })).toEqual({
+      items: [{ id: 'r1', x: 1, y: 2 }],
+      ts: 5,
+    })
+    expect(parseCanvasDragShadow(null)).toBeNull()
+    expect(parseCanvasDragShadow({ items: 'nope', ts: 5 })).toBeNull()
+    expect(parseCanvasDragShadow({ items: [{ id: 'r1', x: 'x', y: 2 }], ts: 5 })).toBeNull()
+    expect(parseCanvasDragShadow({ items: [], ts: Number.NaN })).toBeNull()
+  })
+})