@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/design/canvas/plugins/presence/__tests__/canvas-collab-wiring.test.tsx

@@ -0,0 +1,660 @@
+// @vitest-environment jsdom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 画布协同装配接线测试（任务 30）：presence-layer 是装配点——四件
+// （presence binding / canvas-remote 桥 / canvas-local 桥 + freezeTargets 接力
+// / auto-save collab 参数）在此收敛。本文件验证组件装配行为：
+//   ① collab=true + 引擎就绪 → room 建连 + 三绑定挂载 + 初始补种（reconcileNow）
+//   ② 本地引擎变更 → 写 Y（canvas-local 通道）；拖拽中 Y 零写 + drag 影子 +
+//      freeze 接力（拖拽期间远端 Y 变更不回放、释放后收敛）
+//   ③ 远端 Y 变更 → applyRemoteScene（canvas-remote 通道）；本地 origin 回声过滤
+//   ④ loadDoc 防覆盖守卫：sceneDoc prop 换新（DB 取页完成）触发的引擎通知被
+//      抑制并 reconcileNow 恢复 Y 权威（防陈旧 DB 快照回写覆盖协同态）
+//   ⑤ collab=false → 全短路：不建连、零绑定、引擎变更不写 Y、UI 不渲染
+// headless 纪律（memrec）：provider 模块 mock（jsdom 无 WS），引擎注 fake
+// （结构子集，同 bindings 测试口径）。
+
+import React from 'react'
+import { cleanup, render, act } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+import {
+  Awareness,
+  applyAwarenessUpdate,
+  encodeAwarenessUpdate,
+} from 'y-protocols/awareness'
+import { sceneToYTree, yTreeToScene } from '@allbluecn/collab-core/canvas-tree'
+import {
+  BOARD_NODE_ID,
+  createBoardNode,
+  type SceneDocument,
+  type SceneNode,
+} from '@/components/design/canvas/document/types'
+import type { CollabProviderHandle } from '@/lib/collab/provider'
+import { CANVAS_AWARENESS_KEY } from '@/lib/collab/bindings/canvas-presence'
+import { CANVAS_DRAG_FIELD } from '@/lib/collab/bindings/canvas-local'
+
+// ---- vi.hoisted 共享态（mock 工厂与测试体共享，规避提升 TDZ） ----------------
+
+const harness = vi.hoisted(() => {
+  return {
+    envEnabled: true,
+    providerCreated: [] as string[],
+    providerDestroyed: [] as string[],
+    handles: new Map<
+      string,
+      CollabProviderHandle & { awareness: Awareness; doc: import('yjs').Doc }
+    >(),
+    engine: null as unknown,
+    snapshot: null as unknown,
+  }
+})
+
+vi.mock('@/lib/collab/env', () => ({
+  isCollabEnabled: () => harness.envEnabled,
+  getCollabWsUrl: () => (harness.envEnabled ? 'ws://collab.test' : ''),
+}))
+
+vi.mock('@/lib/collab/provider', async () => {
+  const actual = await vi.importActual<typeof import('@/lib/collab/provider')>(
+    '@/lib/collab/provider',
+  )
+  const Y = await import('yjs')
+  const { Awareness } = await import('y-protocols/awareness')
+  return {
+    ...actual,
+    getOrCreateProvider: (roomName: string) => {
+      harness.providerCreated.push(roomName)
+      let handle = harness.handles.get(roomName)
+      if (!handle) {
+        const doc = new Y.Doc()
+        const awareness = new Awareness(doc)
+        const listeners = new Set<(s: 'connecting' | 'synced' | 'offline') => void>()
+        handle = {
+          roomName,
+          doc,
+          awareness,
+          getStatus: () => 'synced' as const,
+          onStatusChange(listener) {
+            listeners.add(listener)
+            listener('synced')
+            return () => {
+              listeners.delete(listener)
+            }
+          },
+          on: () => () => {},
+          off: () => {},
+          destroy: () => {},
+        } as CollabProviderHandle & { awareness: Awareness; doc: Y.Doc }
+        harness.handles.set(roomName, handle)
+      }
+      return handle
+    },
+    destroyProvider: (roomName: string) => {
+      harness.providerDestroyed.push(roomName)
+    },
+  }
+})
+
+vi.mock('@/lib/collab/use-self-profile-broadcast', () => ({
+  useSelfProfileBroadcast: () => {},
+}))
+
+vi.mock('@/server/serverFns/collab', () => ({
+  createCollabTicketFn: async () => ({ ticket: 'test-ticket' }),
+}))
+
+vi.mock('../../../react/hooks', () => ({
+  useCanvasEngineOptional: () => harness.engine,
+}))
+
+vi.mock('../../../react/canvas-hooks', () => ({
+  useCanvasSnapshotOptional: () => harness.snapshot,
+}))
+
+// ---- 假引擎（结构子集，可控事件发射；含 T27/T28 消费面） --------------------
+
+const engineState = {
+  doc: null as SceneDocument | null,
+  selection: [] as string[],
+  applied: [] as SceneDocument[],
+  rebuilt: [] as SceneDocument[],
+}
+const docListeners = new Set<(doc: SceneDocument) => void>()
+const dragListeners = new Set<(dragging: boolean) => void>()
+const selectionListeners = new Set<(ids: string[]) => void>()
+
+function makeFakeEngine() {
+  return {
+    getDoc: () => engineState.doc as SceneDocument,
+    getSelection: () => [...engineState.selection],
+    onDocChange(cb: (doc: SceneDocument) => void) {
+      docListeners.add(cb)
+      return () => {
+        docListeners.delete(cb)
+      }
+    },
+    onDragChange(cb: (dragging: boolean) => void) {
+      dragListeners.add(cb)
+      return () => {
+        dragListeners.delete(cb)
+      }
+    },
+    onSelectionChange(cb: (ids: string[]) => void) {
+      selectionListeners.add(cb)
+      return () => {
+        selectionListeners.delete(cb)
+      }
+    },
+    getZoom: () => 1,
+    toCanvas: (x: number, y: number) => ({ x, y }),
+    fromCanvas: (x: number, y: number) => ({ x, y }),
+    applyRemoteScene(doc: SceneDocument): boolean {
+      engineState.applied.push(doc)
+      engineState.doc = doc
+      for (const cb of [...docListeners]) cb(engineState.doc)
+      return true
+    },
+    rebuildRemoteScene(doc: SceneDocument): void {
+      engineState.rebuilt.push(doc)
+      engineState.doc = doc
+      for (const cb of [...docListeners]) cb(engineState.doc)
+    },
+  }
+}
+
+function emitDoc(): void {
+  for (const cb of [...docListeners]) cb(engineState.doc as SceneDocument)
+}
+
+function emitDrag(dragging: boolean): void {
+  for (const cb of [...dragListeners]) cb(dragging)
+}
+
+// ---- 被测组件 ----------------------------------------------------------------
+
+import { CanvasPresenceLayer } from '../presence-layer'
+
+// ---- 夹具 --------------------------------------------------------------------
+
+function boardNode(): SceneNode {
+  return createBoardNode('desktop')
+}
+function rectNode(id: string, x = 0, y = 0): SceneNode {
+  return { id, kind: 'shape', type: 'rect', parentId: BOARD_NODE_ID, x, y, width: 100, height: 50 }
+}
+function docOf(nodes: SceneNode[]): SceneDocument {
+  return { version: 1, meta: { device: 'desktop' }, nodes: [...nodes] }
+}
+
+function yScene(handle: { doc: Y.Doc }): SceneDocument | null {
+  return yTreeToScene(handle.doc) as unknown as SceneDocument | null
+}
+
+function seedRoom(roomName: string, scene: SceneDocument): void {
+  const handle = harness.handles.get(roomName)
+  if (!handle) throw new Error('handle not created yet')
+  sceneToYTree(scene as never, handle.doc)
+}
+
+function mountLayer(
+  opts: {
+    collab?: boolean
+    pageId?: string | null
+    sceneDoc?: SceneDocument | null
+    /** 页装载门控（缺省 true——既有用例均为装载完成态；C1 窗口用例显式传 false） */
+    pageLoaded?: boolean
+    /** 预览态（I2）：snapshot.readOnly */
+    readOnly?: boolean
+  } = {},
+) {
+  const build = (p: typeof opts) => (
+    <CanvasPresenceLayer
+      pageId={p.pageId ?? 'page-1'}
+      collab={p.collab ?? true}
+      loadedSceneDoc={p.sceneDoc ?? null}
+      pageLoaded={p.pageLoaded ?? true}
+    />
+  )
+  // 原位变异 readOnly（beforeEach 重建的 snapshot 对象带 live doc getter，
+  // 展开会冻结 doc 引用）
+  ;(harness.snapshot as { readOnly: boolean }).readOnly = opts.readOnly ?? false
+  const view = render(build(opts))
+  return {
+    rerender(next: typeof opts) {
+      ;(harness.snapshot as { readOnly: boolean }).readOnly = next.readOnly ?? false
+      view.rerender(build(next))
+    },
+    unmount: view.unmount,
+    container: view.container,
+  }
+}
+
+const ROOM = 'canvas:design:page-1'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  harness.envEnabled = true
+  harness.providerCreated = []
+  harness.providerDestroyed = []
+  for (const handle of harness.handles.values()) handle.awareness.destroy()
+  harness.handles.clear()
+  docListeners.clear()
+  dragListeners.clear()
+  selectionListeners.clear()
+  engineState.doc = docOf([boardNode(), rectNode('r1')])
+  engineState.selection = []
+  engineState.applied = []
+  engineState.rebuilt = []
+  harness.engine = makeFakeEngine()
+  harness.snapshot = {
+    ready: true,
+    readOnly: false,
+    zoom: 1,
+    get doc() {
+      return engineState.doc
+    },
+  }
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+  for (const handle of harness.handles.values()) handle.awareness.destroy()
+  harness.handles.clear()
+})
+
+// ---------------------------------------------------------------------------
+// ① 装配：建连 + 三绑定 + 初始补种
+// ---------------------------------------------------------------------------
+
+describe('装配接线（collab=true）', () => {
+  it('room 建连 + 补种：room 已有 Y 树（中途加入）→ applyRemoteScene 收敛引擎', () => {
+    mountLayer()
+    expect(harness.providerCreated).toContain(ROOM)
+    seedRoom(ROOM, docOf([boardNode(), rectNode('r1', 10), rectNode('r2', 20)]))
+    act(() => {
+      vi.advanceTimersByTime(200)
+    })
+    expect(engineState.applied).toHaveLength(1)
+    expect(engineState.applied[0]?.nodes.map((n) => n.id).sort()).toEqual([
+      'board', 'r1', 'r2',
+    ])
+  })
+
+  it('本地引擎变更 → 恰一次写 Y（canvas-local 通道）', () => {
+    mountLayer()
+    const handle = harness.handles.get(ROOM)
+    expect(handle).toBeTruthy()
+    engineState.doc = docOf([boardNode(), rectNode('r1', 42)])
+    act(() => {
+      emitDoc()
+    })
+    expect(yScene(handle!)?.nodes.find((n) => n.id === 'r1')?.x).toBe(42)
+  })
+
+  it('远端 Y 变更（非本地 origin）→ applyRemoteScene（canvas-remote 通道）', () => {
+    mountLayer()
+    engineState.applied = []
+    const handle = harness.handles.get(ROOM)!
+    act(() => {
+      handle.doc.transact(() => {
+        sceneToYTree(docOf([boardNode(), rectNode('r1', 77)]) as never, handle.doc)
+      }, 'remote-peer')
+    })
+    act(() => {
+      vi.advanceTimersByTime(150)
+    })
+    expect(engineState.applied.length).toBeGreaterThan(0)
+    expect(engineState.applied.at(-1)?.nodes.find((n) => n.id === 'r1')?.x).toBe(77)
+  })
+
+  it('本地 origin 回声被过滤：本地写 Y 不触发 applyRemoteScene', () => {
+    mountLayer()
+    engineState.applied = []
+    const handle = harness.handles.get(ROOM)!
+    act(() => {
+      handle.doc.transact(() => {
+        sceneToYTree(docOf([boardNode(), rectNode('r1', 5)]) as never, handle.doc)
+      }, 'canvas-local')
+    })
+    act(() => {
+      vi.advanceTimersByTime(200)
+    })
+    expect(engineState.applied).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ② 拖拽：Y 零写 + drag 影子 + freeze 接力
+// ---------------------------------------------------------------------------
+
+describe('拖拽接力（freezeTargets + 影子）', () => {
+  it('拖拽全程 Y 零写、drag 影子上报、释放后恰一次写 Y 并摘影子', () => {
+    mountLayer()
+    const handle = harness.handles.get(ROOM)!
+    let updates = 0
+    handle.doc.on('update', () => {
+      updates += 1
+    })
+    engineState.selection = ['r1']
+    act(() => {
+      for (const cb of [...selectionListeners]) cb(engineState.selection)
+    })
+    act(() => {
+      emitDrag(true)
+    })
+    const updatesAtDragStart = updates
+    engineState.doc = docOf([boardNode(), rectNode('r1', 30)])
+    act(() => {
+      emitDoc()
+    })
+    act(() => {
+      vi.advanceTimersByTime(60)
+    })
+    expect(updates).toBe(updatesAtDragStart)
+    const local = handle.awareness.getLocalState() as Record<string, unknown>
+    const canvas = local[CANVAS_AWARENESS_KEY] as Record<string, unknown>
+    expect((canvas[CANVAS_DRAG_FIELD] as { items: { x: number }[] }).items[0]?.x).toBe(30)
+    act(() => {
+      emitDrag(false)
+    })
+    expect(yScene(handle)?.nodes.find((n) => n.id === 'r1')?.x).toBe(30)
+    const localAfter = handle.awareness.getLocalState() as Record<string, unknown>
+    expect(
+      (localAfter[CANVAS_AWARENESS_KEY] as Record<string, unknown>)[CANVAS_DRAG_FIELD],
+    ).toBeUndefined()
+  })
+
+  it('拖拽期间远端 Y 变更不回放（冻结接力），释放后收敛进引擎', () => {
+    mountLayer()
+    engineState.applied = []
+    engineState.selection = ['r1']
+    const handle = harness.handles.get(ROOM)!
+    act(() => {
+      emitDrag(true)
+    })
+    act(() => {
+      handle.doc.transact(() => {
+        sceneToYTree(docOf([boardNode(), rectNode('r1', 1), rectNode('r9', 300)]) as never, handle.doc)
+      }, 'remote-peer')
+    })
+    act(() => {
+      vi.advanceTimersByTime(300)
+    })
+    expect(engineState.applied).toHaveLength(0)
+    act(() => {
+      emitDrag(false)
+    })
+    expect(engineState.applied.length).toBeGreaterThan(0)
+    expect(engineState.applied.at(-1)?.nodes.find((n) => n.id === 'r9')).toBeTruthy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③ loadDoc 防覆盖守卫（审查 I3 诚实语义：被抑制的装载通知内容从引擎丢弃、
+// 由 reconcileNow 以 Y 覆写——对「装载通知=陈旧 DB 快照」这是预期丢弃；
+// 武装与 loadDoc 同 commit 相邻 effect，用户编辑无法进入武装窗口）
+// ---------------------------------------------------------------------------
+
+describe('loadDoc 防覆盖守卫', () => {
+  it('sceneDoc 换新触发的引擎通知被抑制：Y 不被陈旧 DB 快照回写，reconcileNow 恢复 Y 权威', async () => {
+    const staleDb = docOf([boardNode(), rectNode('r1', 0)])
+    const view = mountLayer({ sceneDoc: staleDb })
+    seedRoom(ROOM, docOf([boardNode(), rectNode('r1', 0), rectNode('r-remote', 500)]))
+    act(() => {
+      vi.advanceTimersByTime(200)
+    })
+    expect(engineState.applied.at(-1)?.nodes.find((n) => n.id === 'r-remote')).toBeTruthy()
+    engineState.applied = []
+
+    // DB 重新取页 → sceneDoc prop 换「新对象」（内容可为旧值）：守卫据引用
+    // 换新重新武装（effect deps 按引用比较）
+    const staleDbReload = docOf([boardNode(), rectNode('r1', 0)])
+    engineState.doc = staleDbReload
+    view.rerender({ sceneDoc: staleDbReload })
+    // await act：守卫恢复走 queueMicrotask，需让出微任务检查点
+    await act(async () => {
+      emitDoc()
+    })
+    act(() => {
+      vi.advanceTimersByTime(50)
+    })
+    const handle = harness.handles.get(ROOM)!
+    expect(yScene(handle)?.nodes.find((n) => n.id === 'r-remote')).toBeTruthy()
+    expect(engineState.applied.at(-1)?.nodes.find((n) => n.id === 'r-remote')).toBeTruthy()
+  })
+
+  it('Y 空时武装通知放行（非抑制）：DB 装载写 Y 为合法首种，后续编辑正常写 Y', async () => {
+    const db = docOf([boardNode(), rectNode('r1', 0)])
+    const view = mountLayer({ sceneDoc: db })
+    const handle = harness.handles.get(ROOM)!
+    await act(async () => {
+      emitDoc() // Y 空：武装通知放行，写 Y 是首种而非回滚
+    })
+    engineState.doc = docOf([boardNode(), rectNode('r1', 88)])
+    act(() => {
+      emitDoc()
+    })
+    expect(yScene(handle)?.nodes.find((n) => n.id === 'r1')?.x).toBe(88)
+  })
+
+  it('Y 已种子 + 武装通知 → 本地桥抑制且引擎被 Y 覆写（丢弃内容=陈旧 DB 快照，诚实断言）', async () => {
+    const staleDb = docOf([boardNode(), rectNode('r1', 0)])
+    const view = mountLayer({ sceneDoc: staleDb })
+    seedRoom(ROOM, docOf([boardNode(), rectNode('r1', 0), rectNode('r-live', 400)]))
+    await act(async () => {
+      vi.advanceTimersByTime(200)
+    })
+    engineState.applied = []
+    // 装载通知（内容 ≠ Y）：抑制 + reconcileNow 覆写引擎。
+    // sceneDoc prop 须换「新对象」（守卫按引用换新武装，effect deps 引用比较）
+    const reloadedDb = docOf([boardNode(), rectNode('r1', 0)])
+    engineState.doc = docOf([boardNode(), rectNode('r1', 0), rectNode('r-stray', 999)])
+    view.rerender({ sceneDoc: reloadedDb })
+    await act(async () => {
+      emitDoc()
+    })
+    const handle = harness.handles.get(ROOM)!
+    // Y 未被回写：r-live 仍在、r-stray 未入 Y
+    const scene = yScene(handle)
+    expect(scene?.nodes.find((n) => n.id === 'r-live')).toBeTruthy()
+    expect(scene?.nodes.find((n) => n.id === 'r-stray')).toBeUndefined()
+    // 引擎被 reconcileNow 拉回 Y 态：r-stray 从引擎消失（诚实口径——丢弃）
+    expect(engineState.doc?.nodes.find((n) => n.id === 'r-stray')).toBeUndefined()
+    expect(engineState.applied.at(-1)?.nodes.find((n) => n.id === 'r-live')).toBeTruthy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③' 装载窗口门控（审查 C1）：loadPage 先 setActivePageId 再异步取页——
+// 「activePageId 先行、sceneDoc 未到」窗口内引擎持旧页文档，编辑面整体
+// 不装配（零远端回放/零本地回写），防旧页内容污染新 room 的 Y
+// ---------------------------------------------------------------------------
+
+describe('装载窗口门控（C1）', () => {
+  it('pageLoaded=false 窗口：编辑面不装配（无补种/无回放/本地变更零 Y 写）', async () => {
+    const view = mountLayer({ pageLoaded: false, sceneDoc: null })
+    const handle = harness.handles.get(ROOM)!
+    // 无补种：room 已种子也不回放（引擎保持旧页文档不被覆写）
+    seedRoom(ROOM, docOf([boardNode(), rectNode('r-new', 500)]))
+    await act(async () => {
+      vi.advanceTimersByTime(300)
+    })
+    expect(engineState.applied).toHaveLength(0)
+    // 窗口内引擎变更（旧页内容/异步 settle）→ 零 Y 写（C1 核心断言）
+    let updates = 0
+    handle.doc.on('update', () => {
+      updates += 1
+    })
+    engineState.doc = docOf([boardNode(), rectNode('r-old', 42)])
+    await act(async () => {
+      emitDoc()
+    })
+    expect(updates).toBe(0)
+    // 窗口内变更内容（旧页 r-old）未入 Y（Y 里只有此前种子化的新页内容）
+    expect(yScene(handle)?.nodes.find((n) => n.id === 'r-old')).toBeUndefined()
+    // presence 只读在场仍装配（徽标/面板数据面不中断）
+    engineState.selection = ['r-old']
+    await act(async () => {
+      vi.advanceTimersByTime(60)
+    })
+    expect(
+      (handle.awareness.getLocalState() as Record<string, unknown>)[CANVAS_AWARENESS_KEY],
+    ).toBeTruthy()
+  })
+
+  it('pageLoaded 翻转 true：编辑面装配（补种收敛引擎）+ 本地写通道开启', async () => {
+    const view = mountLayer({ pageLoaded: false, sceneDoc: null })
+    seedRoom(ROOM, docOf([boardNode(), rectNode('r1', 7)]))
+    const handle = harness.handles.get(ROOM)!
+    // 装载完成（sceneDoc 到达同 commit）：补种生效
+    const dbDoc = docOf([boardNode(), rectNode('r1', 7)])
+    view.rerender({ pageLoaded: true, sceneDoc: dbDoc })
+    await act(async () => {
+      vi.advanceTimersByTime(200)
+    })
+    expect(engineState.applied.length).toBeGreaterThan(0)
+    expect(engineState.applied.at(-1)?.nodes.find((n) => n.id === 'r1')?.x).toBe(7)
+    // 装载通知（loadDoc(DB)）到达：武装消费 + Y 已种子 → 抑制 + 引擎收敛 Y
+    engineState.doc = dbDoc
+    await act(async () => {
+      emitDoc()
+    })
+    // 其后真实编辑 → 正常写 Y（本地写通道开启）
+    engineState.doc = docOf([boardNode(), rectNode('r1', 66)])
+    await act(async () => {
+      emitDoc()
+    })
+    expect(yScene(handle)?.nodes.find((n) => n.id === 'r1')?.x).toBe(66)
+  })
+
+  it('装载窗口内拖拽不产生影子会话（编辑面不存在，拖拽生命周期不挂）', async () => {
+    mountLayer({ pageLoaded: false, sceneDoc: null })
+    const handle = harness.handles.get(ROOM)!
+    engineState.selection = ['r-old']
+    await act(async () => {
+      emitDrag(true)
+    })
+    await act(async () => {
+      vi.advanceTimersByTime(120)
+    })
+    const local = handle.awareness.getLocalState() as Record<string, unknown>
+    const canvas = local[CANVAS_AWARENESS_KEY] as Record<string, unknown> | undefined
+    expect(canvas?.[CANVAS_DRAG_FIELD]).toBeUndefined()
+    await act(async () => {
+      emitDrag(false)
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③'' 预览门控（审查 I2）：版本预览（readOnly）引擎持历史版本——编辑面
+// 跳过（无补种/无远端回放），防 Y 现行态覆写历史预览
+// ---------------------------------------------------------------------------
+
+describe('预览门控（I2）', () => {
+  it('readOnly（预览）期间：无补种、远端变更不回放，历史版本不被覆写', async () => {
+    const view = mountLayer({ readOnly: true })
+    const handle = harness.handles.get(ROOM)!
+    // 引擎持「历史版本」文档
+    engineState.doc = docOf([boardNode(), rectNode('r-history', 11)])
+    seedRoom(ROOM, docOf([boardNode(), rectNode('r1', 1), rectNode('r-current', 200)]))
+    await act(async () => {
+      vi.advanceTimersByTime(300)
+    })
+    // 无补种（历史版本不被 Y 现行态覆写）
+    expect(engineState.applied).toHaveLength(0)
+    expect(engineState.doc?.nodes.find((n) => n.id === 'r-history')).toBeTruthy()
+    // 预览期间远端变更也不回放
+    act(() => {
+      handle.doc.transact(() => {
+        sceneToYTree(docOf([boardNode(), rectNode('r1', 3)]) as never, handle.doc)
+      }, 'remote-peer')
+    })
+    await act(async () => {
+      vi.advanceTimersByTime(200)
+    })
+    expect(engineState.applied).toHaveLength(0)
+  })
+
+  it('预览结束（readOnly=false）：编辑面装配，reconcileNow 收敛到 Y 现行态', async () => {
+    const view = mountLayer({ readOnly: true })
+    seedRoom(ROOM, docOf([boardNode(), rectNode('r1', 1), rectNode('r-current', 200)]))
+    expect(engineState.applied).toHaveLength(0)
+    view.rerender({ readOnly: false })
+    await act(async () => {
+      vi.advanceTimersByTime(50)
+    })
+    expect(engineState.applied.at(-1)?.nodes.find((n) => n.id === 'r-current')).toBeTruthy()
+    expect(engineState.doc?.nodes.find((n) => n.id === 'r-current')).toBeTruthy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ④ 卸载清理 + collab=false 短路
+// ---------------------------------------------------------------------------
+
+describe('卸载与短路', () => {
+  it('卸载：绑定销毁（canvas key 摘除）+ provider 释放', () => {
+    const view = mountLayer()
+    const handle = harness.handles.get(ROOM)!
+    engineState.selection = ['r1']
+    act(() => {
+      for (const cb of [...selectionListeners]) cb(engineState.selection)
+    })
+    act(() => {
+      vi.advanceTimersByTime(60)
+    })
+    expect((handle.awareness.getLocalState() as Record<string, unknown>)[CANVAS_AWARENESS_KEY]).toBeTruthy()
+    view.unmount()
+    expect((handle.awareness.getLocalState() as Record<string, unknown>)[CANVAS_AWARENESS_KEY]).toBeUndefined()
+    expect(harness.providerDestroyed).toContain(ROOM)
+  })
+
+  it('collab=false 全短路：不建连、引擎变更不写 Y、UI 不渲染', () => {
+    const view = mountLayer({ collab: false })
+    expect(harness.providerCreated).toHaveLength(0)
+    engineState.doc = docOf([boardNode(), rectNode('r1', 123)])
+    act(() => {
+      emitDoc()
+    })
+    expect(engineState.applied).toHaveLength(0)
+    expect(view.container.querySelector('[data-testid="canvas-collab-panel"]')).toBeNull()
+    expect(view.container.querySelector('[data-testid="canvas-presence-overlay"]')).toBeNull()
+    expect(view.container.querySelector('[data-testid="canvas-presence-badge"]')).toBeNull()
+  })
+
+  it('isCollabEnabled false（desktop/未配置 WS）同样短路（env 门控双保险）', () => {
+    harness.envEnabled = false
+    mountLayer({ collab: true })
+    expect(harness.providerCreated).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ⑤ 面板装配冒烟（remotes → 面板可见）
+// ---------------------------------------------------------------------------
+
+describe('面板装配冒烟', () => {
+  it('远端在场 → 面板渲染', () => {
+    const view = mountLayer()
+    const handle = harness.handles.get(ROOM)!
+    const peer = new Awareness(new Y.Doc())
+    peer.setLocalStateField(CANVAS_AWARENESS_KEY, {
+      selection: ['r1'],
+      viewport: { x: 0, y: 0, zoom: 1 },
+      user: { id: 'u-2', name: '小蓝' },
+      ts: 1,
+    })
+    act(() => {
+      const update = encodeAwarenessUpdate(peer, [peer.clientID])
+      applyAwarenessUpdate(handle.awareness, update, 'test')
+    })
+    peer.destroy()
+    expect(view.container.querySelector('[data-testid="canvas-collab-panel"]')).not.toBeNull()
+  })
+})