// 简化的 OT 变换函数签名
function transform(op1: Operation, op2: Operation): [Operation, Operation] {
  // op1 与 op2 并发，返回变换后的 op1', op2'
  // 使得 apply(apply(doc, op1), op2') === apply(apply(doc, op2), op1')
}

// LWW-Register 示例：最后写入者胜出
interface LWWRegister<T> {
  value: T;
  timestamp: number;      // 逻辑时钟或混合逻辑时钟
  clientId: string;       // 打破平局
}

// GCounter (Grow-only Counter)
interface GCounter {
  counts: Map<string, number>;  // clientId -> count
  increment(clientId: string) { this.counts[clientId]++ }
  merge(other: GCounter) { /* 取每键最大值 */ }
  value() { return sum(this.counts.values()) }
}

Whiteboard (Y.Doc)
├── Awareness (光标、选区、用户状态)
├── Layers: Y.Map<string, Layer>          // 图层顺序用 Y.Array
│   └── Layer
│       ├── id: string
│       ├── zIndex: number (LWW-Register)
│       ├── visible: boolean (LWW-Register)
│       └── Objects: Y.Map<string, WhiteboardObject>
└── WhiteboardObject (多态)
    ├── type: 'stroke' | 'shape' | 'sticky' | 'text' | 'image'
    ├── geometry: Y.Map / Y.Array         // 坐标点、顶点、包围盒
    ├── style: Y.Map                      // 颜色、线宽、字体
    └── metadata: Y.Map                   // 创建者、时间、锁定态

// 笔迹分段：每 50~100 点切片，片内用 Delta 编码
interface StrokeSegment {
  start: Point;           // 绝对坐标
  deltas: Int16Array;     // 相对偏移量 (dx, dy, pressure, timestampDelta)
  version: number;        // 段版本号
}

// CRDT 映射：Y.Map<string, StrokeSegment> + Y.Array<string> (有序段ID)
// 仅同步变更段，渲染端按需解码

+----------------+      WebRTC DataChannel (P2P 首选)      +----------------+
|  Client A      | <------------------------------------> |  Client B      |
|  (Y.Doc)       |                                        |  (Y.Doc)       |
+-------+--------+                                        +--------+-------+
        |                                                         |
        | WebSocket (中继/信令/鉴权)                              |
        v                                                         v
+-------+---------------------------------------------------------+-------+
|                    Signaling & Relay Server                     |
|  - 房间管理、Token 下发、ICE 候选交换                           |
|  - 消息转发（P2P 打洞失败兜底）                                 |
|  - 持久化：定期快照 + 增量更新日志 (Kafka -> ClickHouse)         |
+-----------------------------------------------------------------+

graph LR
    A[Client Update] --> B{Redis Cache<br/>最近 5min 增量}
    B -->|定时 30s| C[Kafka Topic: whiteboard-updates]
    C --> D[Flink Job: 聚合/去重/快照]
    D --> E[ClickHouse: 全量历史]
    D --> F[Object Storage: 每日快照 .yjs.snap]
    F --> G[Client 首屏加载: 下载快照 + 增量回放]

// 拖拽意图识别：基于指针轨迹、时间窗口判定
function detectDragIntent(events: PointerEvent[]): DragIntent {
  const vector = computeDisplacementVector(events);
  return { targetId, startPos, endPos, confidence };
}

// 合并策略：最后提交胜出 + 视觉提示
function resolveConcurrentDrag(intents: DragIntent[]): Resolution {
  const winner = intents.sort((a,b) => b.timestamp - a.timestamp)[0];
  const losers = intents.slice(1);
  // 失败者位置回弹至 winner 位置，并触发 Toast 提示
  return { finalPos: winner.endPos, notifications: losers.map(l => l.clientId) };
}

// 每个客户端维护本地撤销栈：{ operationId, inverseOp, dependencies: Set<opId> }
function undo(clientId: string, targetOpId: string) {
  const op = history.get(targetOpId);
  // 1. 检查依赖：若有后续因果操作未撤销，拒绝或级联撤销
  // 2. 生成逆操作（CRDT 天然支持：删除->插入，移动->反向移动）
  // 3. 广播逆操作，其他端同步执行
}

// 利用 OPFS 绕过主线程、支持流式读写、避免序列化开销
class OPFSStorage implements IYjsPersistence {
  private root: FileSystemDirectoryHandle;
  private writerMap = new Map<string, FileSystemSyncAccessHandle>();

  async init() {
    this.root = await navigator.storage.getDirectory(); // 需 HTTPS + 用户手势
  }

  // 追加写入 Update 块，元数据单独存 SQLite (via sql.js-wasm)
  async appendUpdate(docName: string, update: Uint8Array, clock: number) {
    const handle = await this.root.getFileHandle(`${docName}.updates`, { create: true });
    const access = await handle.createSyncAccessHandle();
    const meta = this.encodeMeta(clock, update.length);
    access.write(meta); access.write(update); access.flush();
    this.writerMap.set(docName, access);
  }

  // 随机读取：二分查找元数据偏移量 -> 读取指定区间
  async getUpdatesSince(docName: string, knownClock: number): Promise<Uint8Array[]> { /* ... */ }
}

interface OfflineOpContext {
  clientId: string;
  baseStateVector: Map<string, number>; // 离线前的已知向量
  ops: Uint8Array[];                    // 离线期间的所有 Update
  semanticTags: SemanticTag[];          // 业务标记：{type: 'delete', targetId, refIds: []}
}

// 合并前预检
function preMergeCheck(local: OfflineOpContext, remote: Y.Doc): ConflictReport {
  const report = { conflicts: [], autoResolved: [] };
  for (const tag of local.semanticTags) {
    if (tag.type === 'delete' && remote.getMap('objects').has(tag.targetId)) {
      // 远端仍存在，且有新引用
      const refs = getReferencingObjects(remote, tag.targetId);
      if (refs.length > 0) {
        report.conflicts.push({ type: 'DELETE_REFERENCED', target: tag.targetId, refs });
      }
    }
  }
  return report;
}

// 核心接口：平台无关
interface IRenderer {
  // 坐标系：逻辑像素 (CSS px)，内部统一用 Float32Array [x, y, w, h]
  drawStroke(path: Float32Array, style: StrokeStyle): void;
  drawText(layout: TextLayout, style: TextStyle): void;
  drawImage(bitmap: ImageBitmap, rect: Rect): void;
  measureText(text: string, style: TextStyle): TextMetrics;
  // 导出一致性校验用的像素哈希
  snapshotHash(rect: Rect): Promise<string>; 
}

// Web 实现：OffscreenCanvas + Worker
class WebRenderer implements IRenderer {
  private ctx: OffscreenCanvasRenderingContext2D;
  constructor(canvas: OffscreenCanvas) { this.ctx = canvas.getContext('2d', { willReadFrequently: true })!; }
  // 统一关闭亚像素抗锯齿，强制灰度，消除跨浏览器字体渲染差异
  drawText(layout, style) { 
    this.ctx.textRendering = 'geometricPrecision'; 
    this.ctx.fontKerning = 'normal';
    // 手动布局 glyph 位置，避免浏览器自动 kerning 差异
    this.drawGlyphs(layout.glyphs, layout.positions); 
  }
}

// Native 实现：Skia (via JSI / Flutter CustomPainter)
class NativeSkiaRenderer implements IRenderer {
  private canvas: SkCanvas;
  drawText(layout, style) {
    // 复用 Web 端生成的 glyph 位置数组，直接绘制，保证像素级一致
    const blob = SkTextBlob.MakeFromGlyphs(layout.glyphs, layout.positions, font);
    this.canvas.drawTextBlob(blob, 0, 0, paint);
  }
}

+----------------+      gRPC Stream (Protobuf)       +---------------------+
|  Whiteboard    |  白板增量 Update (Yjs Lib0 编码)   |  AI Sidecar Pod     |
|  Server/Client | ---------------------------------> |  (GPU/CPU 混合部署)  |
|  (Producer)    |  仅发送几何/文本增量，不发原始图片  |                     |
+----------------+                                    |  1. Stroke Cleaner  |---> 矢量化/抖动抑制
                                                      |  2. Layout Analyzer |---> 结构化大纲/思维导图
                                                      |  3. OCR / LaTeX     |---> 公式/表格识别
                                                      |  4. Summarizer      |---> 实时纪要生成
                                                      |  5. Embedding Index |---> 语义检索/关联推荐
                                                      +----------+------------+
                                                                 |
                                                                 | CRDT Update (新增 AI 元数据对象)
                                                                 v
                                                      +------------------+
                                                      |  Whiteboard Doc  | (AI 结果作为普通对象参与协同)
                                                      +------------------+

// 宿主暴露的受限 API (Capability-based Security)
const hostAPI = {
  // 只读查询：返回结构化克隆，非 CRDT 引用
  query: (selector: QuerySelector) => Promise<readonly WhiteboardObject[]>,
  
  // 受控写入：需声明 intent，宿主校验权限后代理执行
  proposeUpdate: (intent: UpdateIntent) => Promise<{ accepted: boolean, reason?: string }>,
  
  // UI 交互：仅允许在指定容器渲染 React/Vue 组件 (via Remote UI / Web Components)
  renderUI: (slot: 'sidebar' | 'toolbar' | 'canvas-overlay', vnode: VNode) => void,
  
  // 网络请求：代理转发，强制域名白名单、超时、体积限制
  fetch: (url: string, init: RequestInit) => Promise<Response>,
  
  // 存储：隔离命名空间 Key-Value
  storage: { get: (k:string)=>Promise<any>, set: (k,v)=>Promise<void> }
};

// 插件入口 (运行在独立 Worker / iframe sandbox="allow-scripts allow-same-origin")
export default class MyPlugin implements PluginEntry {
  async onLoad(api: typeof hostAPI) {
    const selection = await api.query({ type: 'selection' });
    api.renderUI('sidebar', <VotePanel items={selection} />);
  }
}

# plugin-manifest.yaml
schema:
  namespace: "com.company.jira-sync"
  version: 2
  tables:
    - name: "IssueCard"
      type: "Y.Map"
      fields:
        issueKey: { type: "string", indexed: true }
        status: { type: "string", enum: ["TODO", "DOING", "DONE"] }
        assignee: { type: "string" }
        # 版本 2 新增
        storyPoints: { type: "number", default: 0, since: 2 } 
  migrations:
    - from: 1
      to: 2
      script: |
        // 运行在宿主主线程，原子事务
        doc.transact(() => {
          doc.getMap('IssueCard').forEach(card => {
            if (!card.has('storyPoints')) card.set('storyPoints', 0);
          });
        });

// 基于 fast-check (Property-Based Testing) 的收敛性测试
import { test, expect } from 'vitest';
import * as fc from 'fast-check';
import { YDoc, applyUpdates, encodeStateAsUpdate } from 'yjs';

// 定义操作生成器
const genOperation = fc.oneof(
  fc.record({ type: fc.constant('insert'), index: fc.nat(100), text: fc.string() }),
  fc.record({ type: fc.constant('delete'), index: fc.nat(100), length: fc.nat(10) }),
  fc.record({ type: fc.constant('format'), index: fc.nat(100), length: fc.nat(10), attrs: fc.record({ bold: fc.boolean() }) })
);

test.prop([fc.array(genOperation, { minLength: 1, maxLength: 50 })])(
  '并发编辑最终收敛', async (ops) => {
    // 1. 创建 3 个副本
    const docs = [new YDoc(), new YDoc(), new YDoc()];
    const texts = docs.map(d => d.getText('content'));
    
    // 2. 随机打乱操作顺序应用到不同副本 (模拟网络乱序)
    const shuffled = [...ops].sort(() => Math.random() - 0.5);
    for (const [i, op] of shuffled.entries()) {
      const targetDoc = docs[i % 3];
      applyOp(targetDoc.getText('content'), op); // 本地直接应用
    }
    
    // 3. 两两同步直到稳定 (模拟 Gossip)
    let changed = true;
    for (let round = 0; round < 10 && changed; round++) {
      changed = false;
      for (let i = 0; i < 3; i++) {
        for (let j = i + 1; j < 3; j++) {
          const update = encodeStateAsUpdate(docs[i]);
          const merged = applyUpdates(docs[j], [update]);
          if (merged) changed = true;
        }
      }
    }
    
    // 4. 断言：所有副本文本内容完全一致
    const contents = docs.map(d => d.getText('content').toString());
    expect(new Set(contents).size).toBe(1);
  }
);

---- Module WhiteboardLock ----
EXTENDS Integers, Sequences, TLC

CONSTANTS Users, Objects, MaxLockTime

VARIABLES locks, clock

TypeOK == 
  / locks in [Objects -> [holder: Users cup {None}, expiry: Nat, seq: Nat]]
  / clock in Nat

Acquire(u, o) ==
  / locks[o].holder = None
  / locks' = [locks EXCEPT ![o] = [holder |-> u, expiry |-> clock + MaxLockTime, seq |-> locks[o].seq + 1]]
  / clock' = clock + 1

Release(u, o) ==
  / locks[o].holder = u
  / locks' = [locks EXCEPT ![o] = [holder |-> None, expiry |-> 0, seq |-> locks[o].seq + 1]]
  / clock' = clock + 1

ForceExpire(o) ==
  / locks[o].holder # None
  / clock >= locks[o].expiry
  / locks' = [locks EXCEPT ![o] = [holder |-> None, expiry |-> 0, seq |-> locks[o].seq + 1]]
  / clock' = clock + 1

Next == / E u in Users, o in Objects: Acquire(u, o)
        / E u in Users, o in Objects: Release(u, o)
        / E o in Objects: ForceExpire(o)
        / ClockTick

Spec == Init / [][Next]_<<locks, clock>>

* 安全性：同一时刻最多一个持有者
Mutex == A o in Objects: Cardinality({u in Users: locks[o].holder = u}) <= 1

* 活性：锁最终会释放 (弱公平性假设)
Liveness == A u in Users, o in Objects: 
            <>[](locks[o].holder = u => <>(locks[o].holder = None))

THEOREM Spec => []Mutex
THEOREM Spec => WF_vars(Next) => Liveness

# 单白板会话健康度评分 (0-100)
whiteboard_health_score{room_id="$room"} = 
  (1 - clamp_max(rate(sync_errors_total[5m]) / rate(sync_total[5m]), 1)) * 30
+ (1 - clamp_max(histogram_quantile(0.99, sync_latency_bucket) / 300, 1)) * 25
+ (1 - clamp_max(active_conflicts / max_concurrent_users, 1)) * 20
+ (clamp_min(connected_clients / expected_clients, 1)) * 15
+ (1 - clamp_max(persist_lag_seconds / 10, 1)) * 10

# 内网穿透调试模式
kubectl port-forward -n wb svc/whiteboard-gateway 8080:80
# 本地启动调试客户端连接生产会话 (只读/影子模式)
npm run debug:shadow -- --room=abc123 --token=eyJhbGciOi...