@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,415 @@
+// 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
+// 「画布桥」本地方向）。
+//
+// 数据流（规格逐字）：引擎 onChange（engine onDocChange，编辑/拖拽释放级）→
+// 以「Y 当前状态反序列化的 prev scene vs 引擎最新 next scene」跑 planSceneDiff
+// → 差异转 Y 写操作。粒度适配（§7.2 复审定稿）：toAdd/toRemove 直接映射、
+// toPatch 整节点 Y set、orderChanged per-parent 重排——三者由 T26 sceneToYTree
+// 的对账式写入统一承载（其内部即「未变节点不重写 + 变更节点整体覆盖 + per-parent
+// 序重建」，规格锚点 L：复用 sceneToYTree 不另写写入），本桥职责是变更检测
+// （跳过无差异通知，避免空 transact 与回声放大）+ 单 transact origin 标记。
+//
+// ── origin 标记（T27 桥回声抑制的验收点）──────────────────────────────────
+//
+// 本端写 Y 一律收敛在 doc.transact(..., CANVAS_LOCAL_ORIGIN) 内：T27 桥的
+// observeDeep 按 origin 跳过本端回声（引擎是写入源，appliedDoc 已是该态，
+// 回声对账是纯浪费）；远端到达（provider applyUpdate）不受过滤影响。
+//
+// ── 拖拽 awareness 影子（性能红线，审查重点 #5）────────────────────────────
+//
+// 拖拽中元素位置走 awareness ephemeral（~50ms 节流广播，30-60ms 交互级红线档），
+// Y 只记手柄释放后的最终态——拖拽全程 Y update 计数恒为 0。影子数据放在 T25
+// awareness schema 的 canvas 子结构内扩展（drag 子字段，禁止另起 key 纪律）；
+// 写入是外科手术式 read-modify-write（不碰 selection/viewport/user 兄弟字段）。
+// 拖拽会话内 T25 presence / T27 远端桥经 freezeTargets 接力 setFrozen(true)
+// （presence 冻结即暂停上报——否则其整键覆写会抹掉 drag 子字段；远端桥冻结即
+// 挂起 patch 回放）。释放写序（审查 C1，真并发丢数据防线）：作废挂起影子 →
+// 解冻 + T27 同步补应用（拖拽期间经 provider 到达的远端变更先灌进引擎）→
+// 最终态恰一次写 Y（此时对账不回滚远端字段）→ 摘影子。若先写 Y 后解冻，
+// next=引擎（远端字段陈旧）会把 Y 里已到达的远端变更回滚、再经解冻 flush
+// 灌回引擎，双端永久丢失。
+//
+// 拖拽生命周期源：引擎 DragEvent.START/END → onDragChange(dragging)（任务 28
+// 同步在引擎公开的订阅口，engine 单测锁定 START/END 转译；headless 测试以
+// fake 引擎直接 emit 布尔）。
+//
+// ── 变更检测口径（planSceneDiff 盲区闭合）──────────────────────────────────
+//
+// planSceneDiff 只感知投影面（x/y/w/h/rotation/name/visible/locked/style/props/
+// fills/strokes/effects/corners/blendMode + parentId 结构 + board 尺寸）。Y 面
+// 字段全集（T26 镜像对账锁定）中的投影盲区可变字段——zIndex/overrides/exports/
+// constraints/aspectLocked/refCorner——由 hasBlindDrift 补检（引用相等快路径，
+// mergeNodePatch 对未变节点保留对象引用），meta（device/background）浅比较补检；
+// 盲区清单以编译期哨兵锁死（SceneNode 新增字段既不进投影也不进盲区清单 →
+// tsc 报错，防清单腐化）。任一信号命中才触发 sceneToYTree 对账写。
+//
+// 分层：无 React / 无 Leafer 依赖（引擎以结构子集注入，可脱离组件树单测
+// ——canvas-presence/canvas-remote 先例）。
+
+import * as Y from 'yjs'
+import { planSceneDiff } from '@/components/design/canvas/document/reconcile'
+import {
+  BOARD_NODE_ID,
+  type SceneDocument,
+  type SceneNode,
+} from '@/components/design/canvas/document/types'
+import {
+  sceneToYTree,
+  yTreeToScene,
+  type CollabSceneDocument,
+  type CollabSceneNode,
+} from '@allbluecn/collab-core/canvas-tree'
+import type { CollabAwareness } from '../provider'
+
+/**
+ * 本端写 Y 的事务 origin 标记（T27 桥 observeDeep 据此跳过本地回声；
+ * provider 远端到达 origin 与之不同，不受过滤）。
+ *
+ * ⚠ 专用禁令：此 origin 仅限本桥「引擎 → Y」回写通道。任务 29 服务端
+ * 持久化（exporter/种子化）写 Y **禁止**复用此 origin——服务端写入若带上
+ * 该标记，所有已连客户端的 T27 桥都会把它当本地回声跳过，远端变更静默
+ * 不到达（种子化丢失即数据不一致）。种子化请走独立 origin（如 'server'）。
+ */
+export const CANVAS_LOCAL_ORIGIN = 'canvas-local'
+
+/**
+ * awareness canvas key 内影子子字段的 key（schema 归 canvas-presence 管理，
+ * 此处 re-export 保持任务 28 消费面稳定——渲染插件经 canvas-presence 透传，
+ * 不再直接消费本导出）。
+ */
+export { CANVAS_DRAG_FIELD, parseCanvasDragShadow } from './canvas-presence'
+export type {
+  CanvasDragShadow,
+  CanvasDragShadowItem,
+} from './canvas-presence'
+
+import {
+  CANVAS_AWARENESS_KEY,
+  CANVAS_DRAG_FIELD,
+  type CanvasDragShadow,
+  type CanvasDragShadowItem,
+} from './canvas-presence'
+
+/**
+ * 拖拽影子上报节流窗口：拖拽中间态是帧级高频（编辑器 MOVE 逐帧读回），
+ * 落在性能红线 30-60ms 档（约 1-2 帧，远端影子肉眼连贯）；leading 首报
+ * 即时（拖拽起点即刻可见）+ 窗口内合并尾随。Y 全程零写，仅 awareness。
+ */
+export const CANVAS_DRAG_THROTTLE_MS = 50
+
+/**
+ * engine 结构子集（真实 LeaferEngine 兼容直传：getDoc 权威读、getSelection
+ * 权威选中、onDocChange 变更流、onDragChange 拖拽生命周期；测试注入 fake）。
+ */
+export interface CanvasLocalEngineSource {
+  getDoc(): SceneDocument
+  getSelection(): string[]
+  onDocChange(cb: (doc: SceneDocument) => void): () => void
+  onDragChange(cb: (dragging: boolean) => void): () => void
+}
+
+/**
+ * 冻结接力目标（拖拽开始/结束逐个调用）：T27 远端桥 + T25 presence，二者
+ * 结构兼容，wiring 直接传绑定本体即可。
+ *
+ * 契约（审查 C1）：setFrozen(false) 若存在冻结期挂起的远端应用，**必须同步
+ * 补应用**（返回时引擎已收敛）——本桥释放写序在解冻之后立即写 Y，若解冻仅
+ * 挂起不收敛，全量对账会把拖拽期间到达的远端变更回滚。T27 桥已实现该语义
+ * （解冻即同步 flush）；无 Y 交互的目标（T25 presence 仅 awareness 上报）
+ * 可自行防抖。
+ */
+export interface CanvasFreezeTarget {
+  setFrozen(frozen: boolean): void
+}
+
+export interface CanvasLocalBindingSource {
+  /** canvas room 的 Y.Doc（本端实例；本地编辑写这里） */
+  readonly doc: Y.Doc
+  readonly engine: CanvasLocalEngineSource
+  /** noop 模式（协同不可用）为 null：影子链路空操作，Y 写与冻结接力照常 */
+  readonly awareness: CollabAwareness | null
+  /** 冻结接力：拖拽开始/结束逐个调用（解冻同步收敛契约见 CanvasFreezeTarget） */
+  readonly freezeTargets?: ReadonlyArray<CanvasFreezeTarget>
+}
+
+export interface CanvasLocalBindingOptions {
+  /** 影子节流窗口覆盖（单测用；缺省 CANVAS_DRAG_THROTTLE_MS） */
+  throttleMs?: number
+}
+
+export interface CanvasLocalBinding {
+  /** 清理：断订阅、作废挂起影子 timer、摘影子；幂等 */
+  destroy(): void
+}
+
+// ===== planSceneDiff 盲区清单（编译期哨兵锁死，见文件头「变更检测口径」） =====
+
+type PlanSeenField =
+  | 'parentId'
+  | 'x'
+  | 'y'
+  | 'width'
+  | 'height'
+  | 'rotation'
+  | 'name'
+  | 'visible'
+  | 'locked'
+  | 'style'
+  | 'props'
+  | 'fills'
+  | 'strokes'
+  | 'effects'
+  | 'corners'
+  | 'blendMode'
+
+/** 投影盲区的 Y 面可变字段（SceneNode 全字段 − 计划可见 − 不可变标识） */
+type BlindField = Exclude<keyof CollabSceneNode, PlanSeenField | 'id' | 'kind' | 'type'>
+
+const BLIND_FIELDS_COVERED: Record<BlindField, true> = {
+  zIndex: true,
+  overrides: true,
+  exports: true,
+  constraints: true,
+  aspectLocked: true,
+  refCorner: true,
+}
+
+/** 投影盲区逐字段比较（引用相等快路径 + 内容兜底；undefined 归一） */
+function blindNodeDrift(before: SceneNode, node: SceneNode): boolean {
+  if ((before.zIndex ?? null) !== (node.zIndex ?? null)) return true
+  if ((before.aspectLocked ?? null) !== (node.aspectLocked ?? null)) return true
+  if ((before.refCorner ?? null) !== (node.refCorner ?? null)) return true
+  if (!looseEqual(before.overrides, node.overrides)) return true
+  if (!looseEqual(before.exports, node.exports)) return true
+  if (!looseEqual(before.constraints, node.constraints)) return true
+  return false
+}
+
+function looseEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+}
+
+function hasBlindDrift(prev: SceneDocument | null, next: SceneDocument): boolean {
+  if (!prev) return false
+  const prevById = new Map(prev.nodes.map((node) => [node.id, node]))
+  for (const node of next.nodes) {
+    const before = prevById.get(node.id)
+    // prev 缺该节点 = toAdd（计划已覆盖）；board 同样纳入盲区检查
+    if (!before) continue
+    if (blindNodeDrift(before, node)) return true
+  }
+  return false
+}
+
+function metaEqual(
+  prev: SceneDocument['meta'] | undefined,
+  next: SceneDocument['meta'],
+): boolean {
+  const meta = prev ?? {}
+  return (
+    (meta.device ?? undefined) === (next.device ?? undefined) &&
+    (meta.background ?? undefined) === (next.background ?? undefined)
+  )
+}
+
+export function createCanvasLocalBinding(
+  source: CanvasLocalBindingSource,
+  options: CanvasLocalBindingOptions = {},
+): CanvasLocalBinding {
+  const throttleMs = options.throttleMs ?? CANVAS_DRAG_THROTTLE_MS
+  const { doc, engine } = source
+  const awareness = source.awareness
+  const freezeTargets = source.freezeTargets ?? []
+
+  let destroyed = false
+  let dragging = false
+  /** 拖拽会话的元素集（拖拽开始时快照权威选中集；画板永不出现在选中态） */
+  let dragIds: string[] = []
+  /** 引擎最新文档缓存（onDocChange 载荷；影子节流 flush 用，避免重复 getDoc 读树） */
+  let latestDoc: SceneDocument | null = null
+
+  let shadowTimer: ReturnType<typeof setTimeout> | null = null
+  let lastShadowAt = 0
+
+  // ---- 本地 → Y（§7.2 本地方向）----
+
+  const writeSceneToY = (next: SceneDocument): void => {
+    // 单 transact 收敛（sceneToYTree 内层 transact 并入外层）+ origin 标记
+    // （T27 桥 observeDeep 据此跳过本地回声）
+    doc.transact(() => {
+      sceneToYTree(next as unknown as CollabSceneDocument, doc)
+    }, CANVAS_LOCAL_ORIGIN)
+  }
+
+  /** 变更检测（计划 + 盲区 + meta）命中才写；无差异零 transact 零 update */
+  const syncEngineToY = (next: SceneDocument): void => {
+    let prev: SceneDocument | null = null
+    try {
+      prev = yTreeToScene(doc) as unknown as SceneDocument | null
+    } catch {
+      // Y 树损坏（远端写坏等）：跳过本轮不猜状态（同 T27 桥口径），
+      // 下一次引擎变更重试
+      return
+    }
+    const plan = planSceneDiff(prev ?? { version: 1, meta: {}, nodes: [] }, next)
+    const changed =
+      plan.toAdd.length > 0 ||
+      plan.toRemove.length > 0 ||
+      plan.toPatch.length > 0 ||
+      plan.orderChanged ||
+      plan.boardSize !== null ||
+      !metaEqual(prev?.meta, next.meta) ||
+      hasBlindDrift(prev, next)
+    if (!changed) return
+    try {
+      writeSceneToY(next)
+    } catch {
+      // Y 写异常（树损坏等）：跳过本轮，不向引擎 notify 链路穿透
+      // （doc-change 路径在引擎 notifyDocChange 内同步执行，抛错会炸触发方）
+      return
+    }
+  }
+
+  // ---- 拖拽 awareness 影子（性能红线：Y 全程零写）----
+
+  /** 外科手术式写/摘 canvas key 的 drag 子字段（不碰 selection/viewport/user） */
+  const setDragField = (shadow: CanvasDragShadow | null): void => {
+    if (!awareness) return
+    const local = awareness.getLocalState() as Record<string, unknown> | null
+    const raw = local?.[CANVAS_AWARENESS_KEY]
+    const canvas: Record<string, unknown> =
+      typeof raw === 'object' && raw !== null ? { ...raw } : {}
+    if (shadow) canvas[CANVAS_DRAG_FIELD] = shadow
+    else delete canvas[CANVAS_DRAG_FIELD]
+    awareness.setLocalStateField(CANVAS_AWARENESS_KEY, canvas)
+  }
+
+  const writeDragShadow = (): void => {
+    if (!awareness || destroyed || !dragging) return
+    const scene = latestDoc ?? engine.getDoc()
+    const byId = new Map(scene.nodes.map((node) => [node.id, node]))
+    const items: CanvasDragShadowItem[] = []
+    for (const id of dragIds) {
+      const node = byId.get(id)
+      if (node) items.push({ id, x: node.x, y: node.y })
+    }
+    if (items.length === 0) return // 空选中拖拽（画布平移）：无影子
+    setDragField({ items, ts: Date.now() })
+  }
+
+  /** leading 即时 + 窗口内合并尾随（同 canvas-presence 节流形态） */
+  const flushShadow = (): void => {
+    shadowTimer = null
+    if (destroyed || !dragging) return
+    lastShadowAt = Date.now()
+    writeDragShadow()
+  }
+
+  const scheduleShadow = (): void => {
+    if (destroyed || !awareness || !dragging) return
+    const elapsed = Date.now() - lastShadowAt
+    if (elapsed >= throttleMs) {
+      flushShadow()
+      return
+    }
+    if (shadowTimer) return
+    shadowTimer = setTimeout(flushShadow, throttleMs - elapsed)
+  }
+
+  // ---- 拖拽生命周期接线（冻结接力 + 影子会话 + 释放最终态写 Y）----
+
+  const onDragChange = (next: boolean): void => {
+    if (destroyed || dragging === next) return
+    dragging = next
+    if (next) {
+      // 冻结接力先行：远端桥挂起回放、presence 暂停上报（其整键覆写会抹 drag）
+      for (const target of freezeTargets) target.setFrozen(true)
+      dragIds = engine
+        .getSelection()
+        .filter((id) => id !== BOARD_NODE_ID)
+      lastShadowAt = 0
+      scheduleShadow() // leading 即时影子（拖拽起点位置即刻可见）
+      return
+    }
+    // 释放写序（审查 C1，顺序不可换）：真并发下拖拽期间可能有远端释放经
+    // provider 落进本端 Y（本端 T27 冻结只记 pending，引擎未收敛）——若先写
+    // Y 后解冻，全量对账的 next=引擎（远端字段陈旧）会把 Y 里的远端变更
+    // 回滚，且解冻 flush 再把回滚态灌回引擎，远端数据双端永久丢失。
+    // 1) 作废挂起影子 timer（防释放后复活）
+    if (shadowTimer) {
+      clearTimeout(shadowTimer)
+      shadowTimer = null
+    }
+    // 2) 摘拖拽态先行：解冻引发的引擎收敛（T27 flush → notifyDocChange）
+    //    走普通 doc-change 通道（diff 空零写），不再进影子节流
+    dragging = false
+    dragIds = []
+    // 3) 解冻接力：T27 桥 setFrozen(false) 即同步补应用（CanvasFreezeTarget
+    //    契约）——冻结期到达的远端变更先灌进引擎，本端拖拽字段不受增量
+    //    计划触碰
+    for (const target of freezeTargets) target.setFrozen(false)
+    // 4) 最终态恰一次写 Y：next=引擎（已含远端收敛），对账基线=Y（含远端）
+    //    ——仅本端拖拽字段进计划，远端变更不被触碰
+    try {
+      syncEngineToY(engine.getDoc())
+    } catch {
+      // 引擎不可用（未挂载/已销毁）：wiring 时序问题，不炸页面
+    }
+    // 5) 影子清除（presence 解冻补报的整键写不含 drag，两侧一致）
+    setDragField(null)
+  }
+
+  const onEngineDocChange = (docNext: SceneDocument): void => {
+    if (destroyed) return
+    latestDoc = docNext
+    if (dragging) {
+      // 拖拽中间态：只走 awareness 影子，Y 零写（性能红线）
+      scheduleShadow()
+      return
+    }
+    syncEngineToY(docNext)
+  }
+
+  const unsubscribeDoc = engine.onDocChange(onEngineDocChange)
+  const unsubscribeDrag = engine.onDragChange(onDragChange)
+
+  return {
+    destroy: () => {
+      if (destroyed) return
+      destroyed = true
+      if (shadowTimer) {
+        clearTimeout(shadowTimer)
+        shadowTimer = null
+      }
+      unsubscribeDoc()
+      unsubscribeDrag()
+      if (dragging) {
+        // 拖拽中断线清理（审查 I2）：解冻本桥冻结过的接力目标——wiring 可能
+        // 只重建本绑定（引擎 remount/HMR），不解冻则 T27 永久冻结、远端回放
+        // 停摆。不写 Y（终态以对端与 room 为准），影子照常摘除
+        dragging = false
+        dragIds = []
+        for (const target of freezeTargets) target.setFrozen(false)
+        setDragField(null)
+      }
+    },
+  }
+}