@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,420 @@
+// 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/>.
+
+// 画布 awareness 绑定层（P4a，任务 25，规格 §7.2「画布桥」awareness-only 部分）。
+//
+// ⚠ P4a 边界（与 P4b 编辑协同的任务 26-29 分界）：本模块只做「只读远端在场」
+// 的 awareness 读写——选中集 + 视口位置 + user brief。不建 Y 树（room 的
+// Y.Doc 保持空文档）、不碰画布序列化、不回放任何远端 patch 到本地画布。
+//
+// ── awareness schema（任务 27/28 复用契约，禁止另起 key 约定）──────────────
+//
+// room：`canvas:design:{pageId}`（§3.1，buildRoomName({ kind: 'design-canvas' })）。
+// awareness local state（每个客户端各自写入，跨端经 awareness 协议同步）：
+//
+//   state['canvas']（本模块独占 key，摘除外科手术式、不碰 profile 兄弟字段）：
+//     {
+//       selection: string[]        // 元素 id 数组（engine 权威选中态原样上报）
+//       viewport: { x, y, zoom }   // 视口中心（board 坐标）+ 缩放——P4a 精度低
+//                                  //（仅「谁在看此页」展示），不承诺实时跟随
+//                                  // 平移；P4b 远端视口指示器复用此字段
+//       user: { id, name }         // user brief（署名：options.identity →
+//                                  // awareness profile → `client:{clientID}` 降级，
+//                                  // 空名降级先例同协同头像/fields editing）
+//       ts: number                 // 写入时刻（Date.now()，新鲜度/排序）
+//     }
+//   state['profile']（既有 use-self-profile-broadcast 广播，本模块不写只读）：
+//     头像摘要 { id, username, avatarConfig?, bgShape?, bgColor? }——远端
+//     渲染侧可用来补头像；身份键以 canvas.user.id 为准。
+//
+//   生命周期：engine 选中变化 / setViewport → 50ms 节流写入（交互级高频走
+//   awareness，绝不产生 Y 增量——同 fields editing 的性能红线口径）/ offline
+//   自动摘除（对端靠 awareness 超时+removed 感知离场）/ synced 重放最新缓存 /
+//   冻结期（setFrozen，拖拽/变换预留接口）仅暂停上报不销毁订阅，解冻补报 /
+//   卸载 destroy 摘除。presence-layer 另挂 15s setViewport 心跳：覆盖平移
+//   漂移（pan 不触发 zoom 快照变化）+ ts 新鲜度续报。
+//
+//   drag 子字段（P4b 任务 28 起写入、任务 30 渲染消费）：canvas key 内可选
+//   `drag: { items: [{id,x,y}], ts }`——拖拽会话中本地桥外科手术式写入（不碰
+//   selection/viewport/user），presence flush 的整键写不含 drag（冻结接力保证
+//   拖拽期不被抹掉）；readRemotes 透传解析后的 drag 供影子渲染，畸形丢弃。
+//
+// 分层：无 React / 无 Leafer 依赖（engine 以结构子集注入，可脱离组件树单测
+// ——双客户端真实 Y.Doc + Awareness 直连验证，同 bindings-fields 先例）。
+
+import type {
+  CollabAwareness,
+  CollabConnectionStatus,
+} from '../provider'
+
+/** awareness state 中本模块独占的 key（任务 27/28 复用） */
+export const CANVAS_AWARENESS_KEY = 'canvas'
+
+/**
+ * 上报节流窗口：选中集变化是交互级高频（拖拽框选逐帧触发），落在性能红线
+ * 30-60ms 档（约 1-2 帧，肉眼无感延迟）。leading 首报即时 + 窗口内合并尾随。
+ */
+export const CANVAS_PRESENCE_THROTTLE_MS = 50
+
+/** 视口位置（board 坐标系中心 + 缩放；P4a 低精度，见 schema 注释） */
+export interface CanvasViewport {
+  x: number
+  y: number
+  zoom: number
+}
+
+/** awareness `canvas` key 的值形态（任务 27/28 复用） */
+export interface CanvasPresenceState {
+  selection: string[]
+  viewport: CanvasViewport
+  user: { id: string; name: string }
+  ts: number
+}
+
+/** 一个远端协作者的在场快照（渲染插件数据面：选中框 + 名牌 + 查看徽标） */
+export interface RemoteCanvasPresence {
+  /** awareness clientID（多 tab 同人区分；React key / 排序稳定键） */
+  clientId: number
+  userId: string
+  name: string
+  selection: string[]
+  viewport: CanvasViewport
+  ts: number
+  /**
+   * 拖拽影子（任务 30，P4b）：canvas key 的 drag 子字段（本地桥拖拽会话
+   * 写入），null/缺省 = 未在拖拽。渲染插件据此画半透明轮廓。
+   */
+  drag?: CanvasDragShadow | null
+}
+
+// ===== drag 子字段（任务 28 本地桥写入面，schema 归 awareness 侧管理；任务 30
+// 渲染消费经本模块透传，禁止渲染层再解析 awareness 裸状态）=====================
+
+/**
+ * awareness canvas key 内影子子字段的 key（T28 本地桥 + 任务 30 渲染共用，
+ * 禁止硬编码 'drag' 字面量）。
+ */
+export const CANVAS_DRAG_FIELD = 'drag'
+
+/** 单个拖拽影子的位置快照（board 坐标系内节点的父相对 x/y，远端渲染插件按
+ * 本地 doc 父链补齐绝对偏移后投影定位画幽灵框） */
+export interface CanvasDragShadowItem {
+  id: string
+  x: number
+  y: number
+}
+
+/**
+ * 拖拽 awareness 影子（T25 canvas key 的 drag 子字段值形态）：
+ * 一次拖拽会话的全量位置快照（非增量 delta——远端迟到加入直接可用）。
+ */
+export interface CanvasDragShadow {
+  items: CanvasDragShadowItem[]
+  ts: number
+}
+
+/**
+ * 校验一份远端 awareness drag 子字段（fail-closed：畸形丢弃不抛错，
+ * 同 parseCanvasPresence 口径）。畸形仅影响影子，不影响 presence 主体。
+ */
+export function parseCanvasDragShadow(raw: unknown): CanvasDragShadow | null {
+  if (typeof raw !== 'object' || raw === null) return null
+  const record = raw as Record<string, unknown>
+  if (!Array.isArray(record.items)) return null
+  const items: CanvasDragShadowItem[] = []
+  for (const item of record.items) {
+    if (typeof item !== 'object' || item === null) return null
+    const entry = item as Record<string, unknown>
+    if (typeof entry.id !== 'string' || entry.id.length === 0) return null
+    if (!isFiniteNumber(entry.x) || !isFiniteNumber(entry.y)) return null
+    items.push({ id: entry.id, x: entry.x, y: entry.y })
+  }
+  if (!isFiniteNumber(record.ts)) return null
+  return { items, ts: record.ts }
+}
+
+/**
+ * engine 结构子集（真实 LeaferEngine 兼容直传：getSelection 返回权威选中
+ * 态、onSelectionChange 订阅选中变化；测试注入 fake）。
+ */
+export interface CanvasSelectionSource {
+  getSelection(): string[]
+  onSelectionChange(cb: (ids: string[]) => void): () => void
+}
+
+export interface CanvasPresenceBindingSource {
+  /** noop 模式（协同不可用）为 null：全链路安全空操作 */
+  readonly awareness: CollabAwareness | null
+  /** 连接状态订阅（真实 handle 契约：订阅即回放当前状态） */
+  onStatusChange(listener: (status: CollabConnectionStatus) => void): () => void
+  readonly selection: CanvasSelectionSource
+}
+
+/** 上报署名（缺省走 awareness profile → clientID 降级，同 fields 先例） */
+export interface CanvasPresenceIdentity {
+  userId: string
+  name: string
+}
+
+export interface CanvasPresenceBindingOptions {
+  /** 显式署名；仅在 createCanvasPresenceBinding 时生效（同 provider getTicket 惯例） */
+  identity?: CanvasPresenceIdentity
+  /** 节流窗口覆盖（单测用；缺省 CANVAS_PRESENCE_THROTTLE_MS） */
+  throttleMs?: number
+}
+
+export interface CanvasPresenceBinding {
+  /** 单调递增变更计数（React useSyncExternalStore 快照缓存键） */
+  version(): number
+  /**
+   * 上报视口（board 坐标中心 + zoom；低频：挂载 / zoom 快照变化 / 15s 心跳）。
+   * 走与选中集相同的节流通道（挂起时与下一次 flush 合并）。
+   */
+  setViewport(viewport: CanvasViewport): void
+  /**
+   * 交互冻结（P4b 拖拽/变换期间纪律的先行落地，规格 §7.2）：冻结期仅暂停
+   * awareness 上报、不销毁任何订阅（引擎选中照常缓存为最新值），解冻即补报。
+   * P4a 只上报不应用远端 patch，故本端不激活此开关（接线随 P4b 落地）。
+   */
+  setFrozen(frozen: boolean): void
+  /**
+   * 远端在场快照（自身除外；畸形 fail-closed 丢弃；按 clientID 升序稳定
+   * 排序——徽标/名牌顺序不随上报频率抖动）。
+   */
+  readRemotes(): RemoteCanvasPresence[]
+  /** 订阅变更（远端或本端写入触发的 awareness update；不立即回调） */
+  subscribe(listener: () => void): () => void
+  /** 清理：摘 observer、摘本端 canvas key（保留 profile 兄弟字段）、断订阅、幂等 */
+  destroy(): void
+}
+
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v)
+}
+
+/**
+ * 校验一份远端 awareness `canvas` state（fail-closed：畸形丢弃不抛错，
+ * 同 fields parseEditor / presence-store 口径）。
+ */
+export function parseCanvasPresence(
+  raw: unknown,
+): Omit<RemoteCanvasPresence, 'clientId'> | null {
+  if (typeof raw !== 'object' || raw === null) return null
+  const record = raw as Record<string, unknown>
+  if (!Array.isArray(record.selection)) return null
+  if (!record.selection.every((id) => typeof id === 'string')) return null
+  if (typeof record.viewport !== 'object' || record.viewport === null) return null
+  const viewport = record.viewport as Record<string, unknown>
+  if (!isFiniteNumber(viewport.x) || !isFiniteNumber(viewport.y) || !isFiniteNumber(viewport.zoom)) {
+    return null
+  }
+  if (typeof record.user !== 'object' || record.user === null) return null
+  const user = record.user as Record<string, unknown>
+  if (typeof user.id !== 'string' || user.id.length === 0) return null
+  if (typeof user.name !== 'string') return null
+  if (!isFiniteNumber(record.ts)) return null
+  // drag 子字段（任务 30）：可选；畸形仅丢弃影子，不影响 presence 主体
+  const drag = record.drag === undefined ? null : parseCanvasDragShadow(record.drag)
+  return {
+    userId: user.id,
+    name: user.name,
+    selection: record.selection as string[],
+    viewport: { x: viewport.x, y: viewport.y, zoom: viewport.zoom },
+    ts: record.ts,
+    drag,
+  }
+}
+
+/** 从 awareness local state 读 profile 署名（use-self-profile-broadcast 广播） */
+function profileIdentity(awareness: CollabAwareness): CanvasPresenceIdentity | null {
+  const profile = awareness.getLocalState()?.profile as
+    | { id?: unknown; username?: unknown }
+    | undefined
+  if (
+    typeof profile?.id === 'string' &&
+    profile.id.length > 0 &&
+    typeof profile.username === 'string'
+  ) {
+    return { userId: profile.id, name: profile.username }
+  }
+  return null
+}
+
+/** 外科手术式摘除本端 canvas key（保留 profile 等兄弟字段，同 fields 先例） */
+function removeCanvasKey(awareness: CollabAwareness): void {
+  const local = awareness.getLocalState()
+  if (!local) return
+  const next: Record<string, unknown> = { ...local }
+  if (!(CANVAS_AWARENESS_KEY in next)) return
+  delete next[CANVAS_AWARENESS_KEY]
+  awareness.setLocalState(next)
+}
+
+export function createCanvasPresenceBinding(
+  source: CanvasPresenceBindingSource,
+  options: CanvasPresenceBindingOptions = {},
+): CanvasPresenceBinding {
+  const { awareness } = source
+  const throttleMs = options.throttleMs ?? CANVAS_PRESENCE_THROTTLE_MS
+
+  let version = 0
+  let destroyed = false
+  let frozen = false
+  let status: CollabConnectionStatus = 'connecting'
+  const listeners = new Set<() => void>()
+  /** 最新本地态缓存（冻结/offline 期间照常更新，仅不上报） */
+  let latestSelection: string[] = []
+  let latestViewport: CanvasViewport = { x: 0, y: 0, zoom: 1 }
+
+  let flushTimer: ReturnType<typeof setTimeout> | null = null
+  let lastFlushAt = 0
+
+  const notify = () => {
+    version += 1
+    for (const listener of listeners) listener()
+  }
+
+  const resolveIdentity = (): CanvasPresenceIdentity => {
+    if (options.identity) return options.identity
+    if (awareness) {
+      const fromProfile = profileIdentity(awareness)
+      if (fromProfile) return fromProfile
+      return { userId: `client:${awareness.clientID}`, name: '' }
+    }
+    return { userId: 'client:0', name: '' }
+  }
+
+  const flush = () => {
+    if (!awareness || destroyed || frozen || status === 'offline') return
+    const identity = resolveIdentity()
+    const state: CanvasPresenceState = {
+      selection: [...latestSelection],
+      viewport: { ...latestViewport },
+      // schema 序列化口径 user:{id,name}（与 fields editing 的 userId 键区分：
+      // canvas state 自包含远端可解析，消费方无需二次映射）
+      user: { id: identity.userId, name: identity.name },
+      ts: Date.now(),
+    }
+    awareness.setLocalStateField(CANVAS_AWARENESS_KEY, state)
+  }
+
+  /** leading 即时 + 窗口内合并尾随（50ms 交互级节流） */
+  const scheduleFlush = () => {
+    if (destroyed || !awareness) return
+    if (frozen || status === 'offline') return
+    const elapsed = Date.now() - lastFlushAt
+    if (elapsed >= throttleMs) {
+      lastFlushAt = Date.now()
+      flush()
+      return
+    }
+    if (flushTimer) return
+    flushTimer = setTimeout(() => {
+      flushTimer = null
+      // 冻结/offline 在窗口内翻转：落地前再查一次（仅暂停不销毁语义）
+      if (destroyed || frozen || status === 'offline') return
+      lastFlushAt = Date.now()
+      flush()
+    }, throttleMs - elapsed)
+  }
+
+  const onEngineSelection = (ids: string[]) => {
+    if (destroyed) return
+    latestSelection = ids
+    scheduleFlush()
+  }
+  const unsubscribeEngine = source.selection.onSelectionChange(onEngineSelection)
+  // 订阅即取一次权威态（挂载前已有选中的场景）
+  latestSelection = source.selection.getSelection()
+
+  const onAwarenessUpdate = () => notify()
+  if (awareness) awareness.on('update', onAwarenessUpdate)
+
+  const unsubscribeStatus = source.onStatusChange((next) => {
+    if (destroyed) return
+    const prev = status
+    status = next
+    if (next === 'offline') {
+      // 断连自动清：对端靠 awareness 超时/removed 感知离场；缓存保留供重放；
+      // 挂起的尾随上报作废（offline 期间 scheduleFlush/flush 均短路）
+      if (flushTimer) {
+        clearTimeout(flushTimer)
+        flushTimer = null
+      }
+      if (awareness && prev !== 'offline') removeCanvasKey(awareness)
+    } else if (prev === 'offline' && next === 'synced') {
+      // 恢复重放最新缓存（detach/attach 往返可能丢 local state，同 fields 防御）
+      scheduleFlush()
+    }
+  })
+
+  return {
+    version: () => version,
+
+    setViewport: (viewport) => {
+      if (destroyed) return
+      latestViewport = viewport
+      scheduleFlush()
+    },
+
+    setFrozen: (next) => {
+      if (destroyed || frozen === next) return
+      frozen = next
+      if (!next) scheduleFlush() // 解冻补报最新缓存
+    },
+
+    readRemotes: () => {
+      if (!awareness) return []
+      const remotes: RemoteCanvasPresence[] = []
+      for (const [clientId, state] of awareness.getStates()) {
+        if (clientId === awareness.clientID) continue // 只显示他人
+        const parsed = parseCanvasPresence(
+          (state ?? {})[CANVAS_AWARENESS_KEY],
+        )
+        if (!parsed) continue
+        remotes.push({ clientId, ...parsed })
+      }
+      // clientID 升序：稳定排序（徽标/名牌不随上报节奏抖动）
+      remotes.sort((a, b) => a.clientId - b.clientId)
+      return remotes
+    },
+
+    subscribe: (listener) => {
+      if (destroyed) return () => {}
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+
+    destroy: () => {
+      if (destroyed) return
+      destroyed = true
+      if (flushTimer) {
+        clearTimeout(flushTimer)
+        flushTimer = null
+      }
+      unsubscribeEngine()
+      if (awareness) {
+        awareness.off('update', onAwarenessUpdate)
+        removeCanvasKey(awareness)
+      }
+      unsubscribeStatus()
+      listeners.clear()
+    },
+  }
+}

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

@@ -0,0 +1,226 @@
+// 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/>.
+
+// 画布远端变更增量应用桥（P4b，任务 27，规格 §7.2「画布桥」远端方向）。
+//
+// 数据流（规格逐字）：Y observe → 组装最新 SceneDocument（纯函数 yTreeToScene）
+// → applyRemoteScene（引擎内复用 planSceneDiff 的增量管线）→ 失败兜底
+// rebuildRemoteScene（现有 rebuildScene 回退路径，appliedDoc 基线随重建重置）。
+//
+// ── 基线归属（与 §7.2「复用 planSceneDiff」的对接口径）─────────────────────
+//
+// diff 基线（「当前已应用场景」）由引擎持有（appliedDoc），不在桥上维护：
+// 增量应用必须以「引擎真正渲染中的树」为 prev 才安全——若桥自持基线，本地
+// 编辑（引擎侧变更）会让桥基线过期，算出的计划与引擎状态错位（重复挂载/
+// 漏删），树直接损坏。引擎 applyRemoteScene 内部以 appliedDoc 重跑
+// planSceneDiff，本地/远端并发编辑天然正确；桥只负责把最新 Y 态送进引擎并
+// 依返回值决定是否全量兜底。§7.2「粒度适配」（toPatch 整节点 Y set 等）是
+// 任务 28 本地→Y 方向对同一 diff 计划的适配，与本桥无涉。
+//
+// ── 行为契约 ────────────────────────────────────────────────────────────────
+//
+// - 观察：根 Y.Map（CANVAS_ROOT_KEY）observeDeep——只对画布树变更响应，
+//   同 room 的 TipTap Design 文档（default XmlFragment 双载体）击键不触发对账
+//   （observeDeep 先例同 bindings/steps）。
+// - 防抖：连续 update 合并到窗口尾（CANVAS_REMOTE_DEBOUNCE_MS），每次 flush
+//   对「当前 Y 态」反序列化一次——中间态天然丢弃。
+// - 冻结：setFrozen(true)（拖拽/变换中）挂起应用不销毁订阅；解冻后对最新
+//   快照一次 diff 应用（非队列回放，同 canvas-presence 冻结语义）。
+// - 兜底：applyRemoteScene 返回 false 或抛异常 → rebuildRemoteScene（同一
+//   快照直通，引擎内 rebuildScene + appliedDoc 重置）；重建再抛（引擎未挂载
+//   /已销毁）吞掉等下一次 update 重试——桥绝不向上抛错炸页面。
+// - 初始种子：绑定创建即调度一次对账——room 已有内容（中途加入/快照加载前
+//   到达的 update）时引擎收敛到 Y 态；引擎未就绪（未挂载）安全跳过，由
+//   wiring 侧在引擎就绪后调 reconcileNow() 补种。
+// - 空树：yTreeToScene 返回 null（room 未种子化）跳过，不触碰引擎。
+// - 回声：本端经任务 28 写 Y 的事务带 CANVAS_LOCAL_ORIGIN（canvas-local 写入
+//   收敛在该 origin 内）——observeDeep 按 origin 跳过本地回声（引擎是写入源，
+//   appliedDoc 已是该态，回声对账是纯浪费）；远端到达（provider applyUpdate）
+//   与种子回放 origin 不同，不受过滤。
+//
+// 分层：无 React / 无 Leafer 依赖（引擎以结构子集注入，可脱离组件树单测
+// ——同 canvas-presence/fields 先例）。
+
+import type * as Y from 'yjs'
+import type { SceneDocument } from '@/components/design/canvas/document/types'
+import {
+  CANVAS_ROOT_KEY,
+  yTreeToScene,
+  type CollabSceneDocument,
+} from '@allbluecn/collab-core/canvas-tree'
+import { CANVAS_LOCAL_ORIGIN } from './canvas-local'
+
+/**
+ * 远端 update → flush 防抖窗口：远端画布编辑是手柄释放级低频（§7.1：拖拽中
+ * 只走 awareness，Y 只记最终态），100ms 合并多节点操作（粘贴/编组）的连发
+ * update，同时保持远端到达的可感延迟低于一帧余。
+ */
+export const CANVAS_REMOTE_DEBOUNCE_MS = 100
+
+/**
+ * 引擎结构子集（真实 DocEngine 兼容直传：applyRemoteScene 增量优先、
+ * rebuildRemoteScene 全量兜底——两者是引擎 §7.2 远端方向的公开门面；
+ * 测试注入记录调用的 fake）。
+ */
+export interface CanvasRemoteEngineTarget {
+  /** 增量应用（引擎内以已应用场景为基线 planSceneDiff）；false/抛错 = 增量失败 */
+  applyRemoteScene(doc: SceneDocument): boolean
+  /** 全量重建兜底（现有 rebuildScene 回退门面；appliedDoc 基线随重建重置） */
+  rebuildRemoteScene(doc: SceneDocument): void
+}
+
+export interface CanvasRemoteBindingSource {
+  /** canvas room 的 Y.Doc（本端实例，远端变更经 provider applyUpdate 到达） */
+  readonly doc: Y.Doc
+  readonly engine: CanvasRemoteEngineTarget
+}
+
+export interface CanvasRemoteBindingOptions {
+  /** 防抖窗口覆盖（单测用；缺省 CANVAS_REMOTE_DEBOUNCE_MS） */
+  debounceMs?: number
+}
+
+export interface CanvasRemoteBinding {
+  /**
+   * 交互冻结（规格 §7.2：拖拽/变换中本地元素不回放远端 patch）：冻结期挂起
+   * 应用、不销毁订阅；解冻若存在挂起变更，**同步**对最新快照一次 diff 应用
+   * （返回时引擎已收敛——任务 28 释放写序依赖此保证，见 canvas-local
+   * CanvasFreezeTarget 契约）。
+   */
+  setFrozen(frozen: boolean): void
+  /** 立即对账一次（绕过防抖；仍尊重冻结）。wiring 在引擎就绪后补种初始态。 */
+  reconcileNow(): void
+  /** 清理：摘 observer、取消挂起 timer；幂等 */
+  destroy(): void
+}
+
+/** collab-core 结构镜像 → web SceneDocument（T26 canvas-tree 对账测试锁定字段集合严格一致；运行时防御由引擎入口 sanitizeScene 承担） */
+function toSceneDocument(scene: CollabSceneDocument): SceneDocument {
+  return scene as unknown as SceneDocument
+}
+
+export function createCanvasRemoteBinding(
+  source: CanvasRemoteBindingSource,
+  options: CanvasRemoteBindingOptions = {},
+): CanvasRemoteBinding {
+  const debounceMs = options.debounceMs ?? CANVAS_REMOTE_DEBOUNCE_MS
+  // 根 Y.Map 实例在 doc 生命周期内稳定（sceneToYTree/yTreeToScene 同例）；
+  // observeDeep 覆盖 nodes/order/extensions/boardMeta 全部嵌套变更
+  const rootMap = source.doc.getMap<unknown>(CANVAS_ROOT_KEY)
+
+  let destroyed = false
+  let frozen = false
+  // 冻结期有 update 到达（或 flush 被冻结打断）→ 解冻后需补一次对账
+  let pending = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const flush = () => {
+    timer = null
+    if (destroyed) return
+    if (frozen) {
+      pending = true
+      return
+    }
+    pending = false
+    let scene: CollabSceneDocument | null = null
+    try {
+      scene = yTreeToScene(source.doc)
+    } catch {
+      // 反序列化异常（远端写坏 Y 树）：跳过本轮，下一次 update 再对账
+      return
+    }
+    if (!scene) return // room 未种子化，不触碰引擎
+
+    const next = toSceneDocument(scene)
+    let applied = false
+    try {
+      applied = source.engine.applyRemoteScene(next)
+    } catch {
+      applied = false
+    }
+    if (applied) return
+    // 增量失败 → 全量兜底（同一快照直通；引擎内 rebuildScene + appliedDoc
+    // 重置）。引擎未挂载/已销毁时 assertUsable 抛错吞掉——wiring 时序问题，
+    // 下一次 update 或 reconcileNow 重试
+    try {
+      source.engine.rebuildRemoteScene(next)
+    } catch {
+      // 引擎不可用：跳过本轮
+    }
+  }
+
+  const schedule = () => {
+    if (destroyed || timer) return
+    timer = setTimeout(flush, debounceMs)
+  }
+
+  // observeDeep 回调签名经 Parameters 提取（YEvent 泛型约束 AbstractType，
+  // 手写泛型实参会 tsc 报错；transaction.origin 为本地回声过滤的依据）
+  const onCanvasChange: Parameters<Y.Map<unknown>['observeDeep']>[0] = (
+    _events,
+    transaction,
+  ) => {
+    if (destroyed) return
+    // 本地回声抑制（任务 28 验收点）：本端写 Y 的事务按 origin 跳过——引擎
+    // 是写入源，无需回灌；远端到达与种子回放 origin 各异，照常对账
+    if (transaction.origin === CANVAS_LOCAL_ORIGIN) return
+    pending = true
+    schedule()
+  }
+
+  rootMap.observeDeep(onCanvasChange)
+  // 挂载初始种子：room 已有内容（中途加入）时首次对账；引擎未就绪安全跳过
+  schedule()
+
+  return {
+    setFrozen: (next) => {
+      if (destroyed || frozen === next) return
+      frozen = next
+      if (!next && pending) {
+        // 解冻即同步补应用（对最新快照一次 diff，非队列回放；同时关掉挂起
+        // timer 防二次）：任务 28 本地桥的释放写序依赖「setFrozen(false) 返回
+        // 时冻结期到达的远端变更已收敛进引擎」——先收敛再写 Y，否则全量对账
+        // 会回滚拖拽期间到达的远端变更（审查 C1）。即时化同时收口 T27 审查
+        // minor②「解冻补应用过防抖窗」
+        if (timer) {
+          clearTimeout(timer)
+          timer = null
+        }
+        flush()
+      }
+    },
+
+    reconcileNow: () => {
+      if (destroyed) return
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+      flush()
+    },
+
+    destroy: () => {
+      if (destroyed) return
+      destroyed = true
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+      rootMap.unobserveDeep(onCanvasChange)
+    },
+  }
+}