@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,378 @@
+// 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.
+
+// 画布 awareness 绑定层测试（P4a，任务 25，规格 §7.2）：
+// 双客户端真实 Y.Doc + Awareness 仿真（同 bindings-fields 先例）。
+// 覆盖简报四场景：① 选中集变化节流上报（leading 即时 + 窗口合并尾随）
+// ② 远端 awareness → 回调（id 数组 + user brief）③ 断线清理（外科手术式
+// 摘 canvas key 不碰 profile，synced 重放）④ 交互冻结（仅暂停上报不销毁，
+// 解冻补报最新）；另补 noop 降级、卸载清理、视口上报。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+import {
+  Awareness,
+  applyAwarenessUpdate,
+  encodeAwarenessUpdate,
+} from 'y-protocols/awareness'
+import type {
+  CollabAwareness,
+  CollabConnectionStatus,
+} from '../../provider'
+import {
+  CANVAS_AWARENESS_KEY,
+  createCanvasPresenceBinding,
+  parseCanvasPresence,
+  type CanvasSelectionSource,
+} from '../canvas-presence'
+
+// ---------------------------------------------------------------------------
+// 双客户端仿真：真实 Y.Doc + 真实 Awareness + 可手控的 status 状态机 + fake engine
+// ---------------------------------------------------------------------------
+
+/** engine 结构子集 fake（真实 LeaferEngine 兼容：getSelection + onSelectionChange） */
+function makeEngineFake(): CanvasSelectionSource & {
+  emit(ids: string[]): void
+} {
+  let selection: string[] = []
+  const listeners = new Set<(ids: string[]) => void>()
+  return {
+    getSelection: () => [...selection],
+    onSelectionChange(cb) {
+      listeners.add(cb)
+      return () => {
+        listeners.delete(cb)
+      }
+    },
+    emit(ids) {
+      selection = ids
+      for (const cb of [...listeners]) cb(ids)
+    },
+  }
+}
+
+interface TestClient {
+  doc: Y.Doc
+  awareness: Awareness
+  engine: ReturnType<typeof makeEngineFake>
+  binding: ReturnType<typeof createCanvasPresenceBinding>
+  /** 手动推动连接状态机（fake handle 契约：订阅即回放） */
+  setStatus(status: CollabConnectionStatus): void
+  /** 把本端 awareness 状态经真协议编码广播到对方（模拟远端到达） */
+  broadcastAwarenessTo(other: Awareness): void
+}
+
+const cleanups: Array<() => void> = []
+
+function makeClient(): TestClient {
+  const doc = new Y.Doc()
+  const awareness = new Awareness(doc)
+  const engine = makeEngineFake()
+  const statusListeners = new Set<(status: CollabConnectionStatus) => void>()
+  let status: CollabConnectionStatus = 'connecting'
+  const binding = createCanvasPresenceBinding(
+    {
+      awareness: awareness as unknown as CollabAwareness,
+      onStatusChange(listener) {
+        statusListeners.add(listener)
+        listener(status)
+        return () => statusListeners.delete(listener)
+      },
+      selection: engine,
+    },
+    { identity: { userId: 'u-1', name: '阿蓝' } },
+  )
+  cleanups.push(() => {
+    binding.destroy()
+    awareness.destroy()
+    doc.destroy()
+  })
+  return {
+    doc,
+    awareness,
+    engine,
+    binding,
+    setStatus(next) {
+      status = next
+      for (const listener of statusListeners) listener(next)
+    },
+    broadcastAwarenessTo(other) {
+      const update = encodeAwarenessUpdate(awareness, [awareness.clientID])
+      applyAwarenessUpdate(other, update, 'test-wire')
+    },
+  }
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+/** 读本端 awareness 的 canvas key（本地写入面断言用） */
+function localCanvas(client: TestClient): Record<string, unknown> | undefined {
+  const local = client.awareness.getLocalState() as Record<string, unknown> | null
+  return local?.[CANVAS_AWARENESS_KEY] as Record<string, unknown> | undefined
+}
+
+// ---------------------------------------------------------------------------
+// 场景 ①：选中集变化节流上报（leading 首报即时 + 窗口内合并尾随最新值）
+// ---------------------------------------------------------------------------
+
+describe('选中集变化节流上报', () => {
+  it('首报 leading 即时写入 awareness（选中集 + user brief + ts）', () => {
+    const a = makeClient()
+    a.engine.emit(['node-1', 'node-2'])
+    const state = localCanvas(a)
+    expect(state).toBeDefined()
+    expect(state?.selection).toEqual(['node-1', 'node-2'])
+    expect(state?.user).toEqual({ id: 'u-1', name: '阿蓝' })
+    expect(typeof state?.ts).toBe('number')
+  })
+
+  it('窗口内的多次变化合并为一次尾随上报（最新值）', () => {
+    const a = makeClient()
+    a.engine.emit(['first'])
+    const writesAfterLeading = localCanvas(a)?.ts
+    a.engine.emit(['second'])
+    a.engine.emit(['third'])
+    // 窗口内：仍是 leading 那次的值
+    expect(localCanvas(a)?.selection).toEqual(['first'])
+    vi.advanceTimersByTime(50)
+    // 尾随一次：直接落到最新值（中间值被合并）
+    expect(localCanvas(a)?.selection).toEqual(['third'])
+    expect(localCanvas(a)?.ts).not.toBe(writesAfterLeading)
+  })
+
+  it('setViewport 触发同一节流通道（窗口内与选中集尾随合并）', () => {
+    const a = makeClient()
+    a.engine.emit(['n'])
+    a.binding.setViewport({ x: 10, y: 20, zoom: 1.5 })
+    // 同一节流通道：窗口内不重复广播，尾随一次带上最新 viewport + selection
+    vi.advanceTimersByTime(50)
+    const state = localCanvas(a)
+    expect(state?.viewport).toEqual({ x: 10, y: 20, zoom: 1.5 })
+    expect(state?.selection).toEqual(['n'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ②：远端 awareness → 回调（id 数组 + user brief；自身过滤 + 畸形丢弃）
+// ---------------------------------------------------------------------------
+
+describe('远端 awareness 回调', () => {
+  it('远端选中集到达 readRemotes（userId/name/selection/clientId），自身被过滤', () => {
+    const a = makeClient()
+    const b = makeClient()
+    b.engine.emit(['b-node'])
+    b.broadcastAwarenessTo(a.awareness)
+
+    const remotes = a.binding.readRemotes()
+    expect(remotes).toHaveLength(1)
+    expect(remotes[0]).toMatchObject({
+      userId: 'u-1',
+      name: '阿蓝',
+      selection: ['b-node'],
+      clientId: b.awareness.clientID,
+    })
+    // 自身不在远端列表
+    a.engine.emit(['self'])
+    expect(a.binding.readRemotes()).toHaveLength(1)
+  })
+
+  it('subscribe 在远端变化时收到通知（version 递增）', () => {
+    const a = makeClient()
+    const b = makeClient()
+    const versions: number[] = []
+    a.binding.subscribe(() => versions.push(a.binding.version()))
+    b.engine.emit(['x'])
+    b.broadcastAwarenessTo(a.awareness)
+    expect(versions.length).toBeGreaterThan(0)
+    expect(a.binding.readRemotes()[0]?.selection).toEqual(['x'])
+  })
+
+  it('畸形远端 state fail-closed 丢弃（不抛错不出现在列表）', () => {
+    const a = makeClient()
+    const b = makeClient()
+    // 直接写坏数据再广播（绕过 binding 写入面的类型保障）
+    b.awareness.setLocalStateField(CANVAS_AWARENESS_KEY, { broken: true })
+    b.broadcastAwarenessTo(a.awareness)
+    expect(a.binding.readRemotes()).toHaveLength(0)
+    // parseCanvasPresence 单测：null / 缺字段 / id 空串均丢弃
+    expect(parseCanvasPresence(null)).toBeNull()
+    expect(parseCanvasPresence({ selection: 'no-array' })).toBeNull()
+    expect(parseCanvasPresence({ selection: [], viewport: {}, user: { id: '', name: '' }, ts: 1 })).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ③：断线清理（外科手术式摘 canvas key 不碰 profile；synced 重放）
+// ---------------------------------------------------------------------------
+
+describe('断线清理', () => {
+  it('offline 摘除本端 canvas key（保留 profile 兄弟字段），offline 期间暂停上报', () => {
+    const a = makeClient()
+    a.awareness.setLocalStateField('profile', { id: 'u-1', username: '阿蓝' })
+    a.engine.emit(['keep'])
+    expect(localCanvas(a)).toBeDefined()
+
+    a.setStatus('offline')
+    expect(localCanvas(a)).toBeUndefined()
+    expect(
+      (a.awareness.getLocalState() as Record<string, unknown>).profile,
+    ).toEqual({ id: 'u-1', username: '阿蓝' })
+
+    // offline 期间引擎选中变化不上报（订阅仍在，仅缓存）
+    a.engine.emit(['paused'])
+    expect(localCanvas(a)).toBeUndefined()
+  })
+
+  it('synced 恢复后重放最新缓存（offline 期间的选中不丢）', () => {
+    const a = makeClient()
+    a.engine.emit(['before'])
+    a.setStatus('offline')
+    a.engine.emit(['during'])
+    a.setStatus('synced')
+    vi.advanceTimersByTime(50) // 重放走同一节流通道（尾随 ≤50ms）
+    expect(localCanvas(a)?.selection).toEqual(['during'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ④：交互冻结（仅暂停上报不销毁；解冻补报最新）
+// ---------------------------------------------------------------------------
+
+describe('交互冻结', () => {
+  it('冻结期选中变化不写入 awareness（订阅与引擎订阅均保留）', () => {
+    const a = makeClient()
+    a.binding.setFrozen(true)
+    a.engine.emit(['frozen'])
+    expect(localCanvas(a)).toBeUndefined()
+    // 引擎订阅未销毁：解冻后 emit 仍能到达上报通道
+    a.binding.setFrozen(false)
+    vi.advanceTimersByTime(50)
+    expect(localCanvas(a)?.selection).toEqual(['frozen'])
+  })
+
+  it('冻结期挂起的尾随上报不落地，解冻后补报最新值', () => {
+    const a = makeClient()
+    a.engine.emit(['first'])
+    a.binding.setFrozen(true)
+    a.engine.emit(['second'])
+    vi.advanceTimersByTime(200)
+    expect(localCanvas(a)?.selection).toEqual(['first'])
+    a.binding.setFrozen(false)
+    vi.advanceTimersByTime(50)
+    expect(localCanvas(a)?.selection).toEqual(['second'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 卸载清理 / noop 降级
+// ---------------------------------------------------------------------------
+
+describe('卸载清理与降级', () => {
+  it('destroy 摘除 canvas key（不碰 profile）、拆除订阅、幂等', () => {
+    const a = makeClient()
+    a.awareness.setLocalStateField('profile', { id: 'u-1', username: '阿蓝' })
+    a.engine.emit(['x'])
+    a.binding.destroy()
+    expect(localCanvas(a)).toBeUndefined()
+    expect(
+      (a.awareness.getLocalState() as Record<string, unknown>).profile,
+    ).toEqual({ id: 'u-1', username: '阿蓝' })
+    a.engine.emit(['y'])
+    expect(localCanvas(a)).toBeUndefined()
+    expect(() => a.binding.destroy()).not.toThrow()
+  })
+
+  it('awareness 为 null（noop 降级）全链路安全空操作', () => {
+    const engine = makeEngineFake()
+    const binding = createCanvasPresenceBinding({
+      awareness: null,
+      onStatusChange: () => () => {},
+      selection: engine,
+    })
+    expect(() => {
+      engine.emit(['x'])
+      binding.setViewport({ x: 0, y: 0, zoom: 1 })
+    }).not.toThrow()
+    expect(binding.readRemotes()).toEqual([])
+    expect(() => binding.setFrozen(true)).not.toThrow()
+    binding.destroy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ⑥（任务 30）：drag 子字段透传——T28 本地桥写 canvas.drag，本 binding
+// 只读解析（fail-closed：drag 畸形仅丢弃 drag，presence 主体保留）
+// ---------------------------------------------------------------------------
+
+describe('drag 子字段透传（任务 30 影子渲染数据面）', () => {
+  it('parseCanvasPresence 提取合法 drag 子字段；缺失时为 null', () => {
+    const drag = { items: [{ id: 'r1', x: 10, y: 20 }], ts: 99 }
+    const parsed = parseCanvasPresence({
+      selection: ['r1'],
+      viewport: { x: 0, y: 0, zoom: 1 },
+      user: { id: 'u-2', name: '小蓝' },
+      ts: 1,
+      drag,
+    })
+    expect(parsed).not.toBeNull()
+    expect(parsed?.drag).toEqual(drag)
+
+    const withoutDrag = parseCanvasPresence({
+      selection: [],
+      viewport: { x: 0, y: 0, zoom: 1 },
+      user: { id: 'u-2', name: '小蓝' },
+      ts: 1,
+    })
+    expect(withoutDrag?.drag ?? null).toBeNull()
+  })
+
+  it('drag 畸形 fail-closed：仅丢弃 drag，presence 主体保留', () => {
+    const parsed = parseCanvasPresence({
+      selection: ['r1'],
+      viewport: { x: 0, y: 0, zoom: 1 },
+      user: { id: 'u-2', name: '小蓝' },
+      ts: 1,
+      drag: { items: 'not-an-array', ts: 'x' },
+    })
+    expect(parsed).not.toBeNull()
+    expect(parsed?.drag ?? null).toBeNull()
+  })
+
+  it('readRemotes 携带远端 drag（远端拖拽中 → 影子数据到达）', () => {
+    const a = makeClient()
+    // 远端 peer：独立 Y.Doc + Awareness（clientID 天然不同），模拟本地桥写入 drag
+    const peerDoc = new Y.Doc()
+    const peerAwareness = new Awareness(peerDoc)
+    cleanups.push(() => {
+      peerAwareness.destroy()
+      peerDoc.destroy()
+    })
+    const canvas = {
+      selection: ['r1'],
+      viewport: { x: 0, y: 0, zoom: 1 },
+      user: { id: 'u-2', name: '小蓝' },
+      ts: 1,
+      drag: { items: [{ id: 'r1', x: 5, y: 6 }], ts: 2 },
+    }
+    peerAwareness.setLocalStateField(CANVAS_AWARENESS_KEY, canvas)
+    const update = encodeAwarenessUpdate(peerAwareness, [peerAwareness.clientID])
+    applyAwarenessUpdate(a.awareness, update, 'test-wire')
+    const remotes = a.binding.readRemotes()
+    expect(remotes).toHaveLength(1)
+    expect(remotes[0]?.drag).toEqual({ items: [{ id: 'r1', x: 5, y: 6 }], ts: 2 })
+  })
+})