@vuer-ai/vuer-rtc 0.0.1

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@vuer-ai/vuer-rtc",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "CRDT-based real-time collaborative data structures",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./operations": {
+      "types": "./dist/operations/index.d.ts",
+      "import": "./dist/operations/index.js"
+    },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "import": "./dist/state/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/node": "^22.10.1",
+    "@types/react": "^18.2.0",
+    "jest": "^30.2.0",
+    "react": "^18.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "immer": "^11.0.1"
+  }
+}

package/src/client/EditBuffer.ts

@@ -0,0 +1,105 @@
+/**
+ * Edit Buffer
+ *
+ * Accumulates uncommitted operations during gestures (e.g., dragging).
+ * Merges additive operations to reduce message size.
+ */
+
+import type { Operation } from '../operations/OperationTypes.js';
+
+/**
+ * Check if an operation type is additive (can be merged)
+ */
+export function isAdditiveOp(otype: string): boolean {
+  return otype === 'vector3.add' ||
+         otype === 'number.add' ||
+         otype === 'number.multiply' ||
+         otype === 'quaternion.multiply';
+}
+
+/**
+ * Merge two values for additive operations
+ */
+export function mergeValues(otype: string, a: unknown, b: unknown): unknown {
+  switch (otype) {
+    case 'vector3.add': {
+      const va = a as [number, number, number];
+      const vb = b as [number, number, number];
+      return [va[0] + vb[0], va[1] + vb[1], va[2] + vb[2]];
+    }
+    case 'number.add':
+      return (a as number) + (b as number);
+    case 'number.multiply':
+      return (a as number) * (b as number);
+    case 'quaternion.multiply': {
+      // Quaternion multiplication: q1 * q2
+      const q1 = a as [number, number, number, number];
+      const q2 = b as [number, number, number, number];
+      return [
+        q1[3] * q2[0] + q1[0] * q2[3] + q1[1] * q2[2] - q1[2] * q2[1],
+        q1[3] * q2[1] - q1[0] * q2[2] + q1[1] * q2[3] + q1[2] * q2[0],
+        q1[3] * q2[2] + q1[0] * q2[1] - q1[1] * q2[0] + q1[2] * q2[3],
+        q1[3] * q2[3] - q1[0] * q2[0] - q1[1] * q2[1] - q1[2] * q2[2],
+      ];
+    }
+    default:
+      return b; // For LWW, later value wins
+  }
+}
+
+/**
+ * Edit buffer class
+ */
+export class EditBufferImpl {
+  private opsMap: Map<string, Operation> = new Map();
+  private opOrder: string[] = [];
+
+  /**
+   * Add or merge an operation
+   */
+  add(op: Operation): void {
+    const key = `${op.key}:${op.path}`;
+    const existing = this.opsMap.get(key);
+
+    if (existing && existing.otype === op.otype && isAdditiveOp(op.otype)) {
+      // Merge additive ops
+      const mergedValue = mergeValues(op.otype, (existing as any).value, (op as any).value);
+      this.opsMap.set(key, { ...existing, value: mergedValue } as Operation);
+    } else {
+      // New op or LWW replacement
+      if (!this.opsMap.has(key)) {
+        this.opOrder.push(key);
+      }
+      this.opsMap.set(key, op);
+    }
+  }
+
+  /**
+   * Get ops in order (for committing)
+   */
+  getOps(): Operation[] {
+    return this.opOrder.map(k => this.opsMap.get(k)!);
+  }
+
+  /**
+   * Clear buffer
+   */
+  clear(): void {
+    this.opsMap.clear();
+    this.opOrder = [];
+  }
+
+  /**
+   * Check if empty
+   */
+  isEmpty(): boolean {
+    return this.opsMap.size === 0;
+  }
+
+  /**
+   * Get count
+   */
+  size(): number {
+    return this.opsMap.size;
+  }
+}

package/src/client/actions.ts

@@ -0,0 +1,397 @@
+/**
+ * Client State Actions
+ *
+ * Pure functions that transform ClientState.
+ * Used by createGraph and React hooks.
+ */
+
+import { produce } from 'immer';
+import type { CRDTMessage, Operation, SceneGraph } from '../operations/OperationTypes.js';
+import type { ClientState, JournalEntry, Snapshot } from './types.js';
+import { applyMessage, applyOperation, createEmptyGraph } from '../operations/dispatcher.js';
+import { VectorClockManager, type VectorClock } from '../state/VectorClock.js';
+import { isAdditiveOp, mergeValues } from './EditBuffer.js';
+
+const clockManager = new VectorClockManager();
+
+/**
+ * Generate a UUID
+ */
+export function generateUUID(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Create initial client state
+ */
+export function createInitialState(sessionId: string, initialSnapshot?: Snapshot): ClientState {
+  const emptyGraph = createEmptyGraph();
+  const snapshot = initialSnapshot ?? {
+    graph: emptyGraph,
+    vectorClock: {},
+    journalIndex: 0,
+  };
+
+  return {
+    graph: snapshot.graph,
+    journal: [],
+    edits: { ops: [], startGraph: null },
+    snapshot,
+    lamportTime: 0,
+    vectorClock: clockManager.create(sessionId),
+    sessionId,
+  };
+}
+
+/**
+ * Rebuild graph from snapshot + journal + edits
+ */
+export function rebuildGraph(
+  snapshot: Snapshot,
+  journal: JournalEntry[],
+  pendingOps: Operation[]
+): SceneGraph {
+  let graph = snapshot.graph;
+
+  // Apply journal (skip deleted entries and meta ops)
+  for (const entry of journal) {
+    if (entry.deletedAt) continue;
+
+    const realOps = entry.msg.ops.filter(op => !op.otype.startsWith('meta.'));
+    if (realOps.length > 0) {
+      graph = applyMessage(graph, { ...entry.msg, ops: realOps });
+    }
+  }
+
+  // Apply pending edits
+  if (pendingOps.length > 0) {
+    graph = produce(graph, draft => {
+      for (const op of pendingOps) {
+        applyOperation(draft, op, {
+          sessionId: 'local',
+          clock: {},
+          lamportTime: 0,
+          timestamp: Date.now(),
+        });
+      }
+    });
+  }
+
+  return graph;
+}
+
+/**
+ * Action: Edit (uncommitted)
+ */
+export function onEdit(state: ClientState, op: Operation): ClientState {
+  return produce(state, draft => {
+    // Save start graph for cancel (first edit only)
+    // Use state.graph (immutable original), not draft.graph (mutable proxy)
+    if (draft.edits.ops.length === 0) {
+      draft.edits.startGraph = state.graph;
+    }
+
+    // Merge into edit buffer
+    const key = `${op.key}:${op.path}`;
+    const existingIdx = draft.edits.ops.findIndex(
+      o => `${o.key}:${o.path}` === key
+    );
+
+    if (existingIdx >= 0) {
+      const existing = draft.edits.ops[existingIdx];
+      if (existing.otype === op.otype && isAdditiveOp(op.otype)) {
+        // Merge additive ops
+        const mergedValue = mergeValues(op.otype, (existing as any).value, (op as any).value);
+        draft.edits.ops[existingIdx] = { ...existing, value: mergedValue } as Operation;
+      } else {
+        // Replace
+        draft.edits.ops[existingIdx] = op;
+      }
+    } else {
+      draft.edits.ops.push(op);
+    }
+
+    // Apply to graph immediately (optimistic)
+    // Note: applyOperation mutates draft.graph in place
+    applyOperation(draft.graph, op, {
+      sessionId: draft.sessionId,
+      clock: draft.vectorClock,
+      lamportTime: draft.lamportTime,
+      timestamp: Date.now(),
+    });
+  });
+}
+
+/**
+ * Action: Commit edits
+ */
+export function commitEdits(
+  state: ClientState,
+  _description?: string
+): { state: ClientState; msg: CRDTMessage | null } {
+  if (state.edits.ops.length === 0) {
+    return { state, msg: null };
+  }
+
+  const newClock = clockManager.increment(state.vectorClock, state.sessionId);
+  const msg: CRDTMessage = {
+    id: generateUUID(),
+    sessionId: state.sessionId,
+    clock: newClock,
+    lamportTime: state.lamportTime + 1,
+    timestamp: Date.now(),
+    ops: [...state.edits.ops],
+  };
+
+  const newState = produce(state, draft => {
+    // Add to journal (unacknowledged)
+    draft.journal.push({ msg, ack: false });
+
+    // Clear edit buffer
+    draft.edits = { ops: [], startGraph: null };
+
+    // Update clocks
+    draft.lamportTime = msg.lamportTime;
+    draft.vectorClock = newClock;
+  });
+
+  return { state: newState, msg };
+}
+
+/**
+ * Action: Cancel edits (revert to start graph)
+ */
+export function cancelEdits(state: ClientState): ClientState {
+  if (state.edits.ops.length === 0) {
+    return state;
+  }
+
+  return produce(state, draft => {
+    // Revert to start graph
+    if (draft.edits.startGraph) {
+      draft.graph = draft.edits.startGraph;
+    }
+    // Clear edit buffer
+    draft.edits = { ops: [], startGraph: null };
+  });
+}
+
+/**
+ * Action: Server acknowledgement
+ */
+export function onServerAck(state: ClientState, msgId: string): ClientState {
+  return produce(state, draft => {
+    const entry = draft.journal.find(e => e.msg.id === msgId);
+    if (entry) {
+      entry.ack = true;
+    }
+  });
+}
+
+/**
+ * Action: Receive remote message
+ */
+export function onRemoteMessage(state: ClientState, msg: CRDTMessage): ClientState {
+  // Skip duplicates
+  if (state.journal.some(e => e.msg.id === msg.id)) {
+    return state;
+  }
+
+  return produce(state, draft => {
+    // Add to journal (already acked - came from server)
+    draft.journal.push({ msg, ack: true });
+
+    // Process meta ops (undo/redo)
+    for (const op of msg.ops) {
+      if (op.otype === 'meta.undo') {
+        const targetMsgId = (op as any).targetMsgId;
+        const target = draft.journal.find(e => e.msg.id === targetMsgId);
+        if (target) target.deletedAt = msg.timestamp;
+      } else if (op.otype === 'meta.redo') {
+        const targetMsgId = (op as any).targetMsgId;
+        const target = draft.journal.find(e => e.msg.id === targetMsgId);
+        if (target) delete target.deletedAt;
+      }
+    }
+
+    // Merge clocks
+    draft.vectorClock = clockManager.merge(draft.vectorClock, msg.clock);
+    draft.lamportTime = Math.max(draft.lamportTime, msg.lamportTime);
+
+    // Rebuild graph
+    draft.graph = rebuildGraph(draft.snapshot, draft.journal, draft.edits.ops);
+  });
+}
+
+/**
+ * Action: Undo
+ */
+export function undo(state: ClientState): { state: ClientState; msg: CRDTMessage | null } {
+  let currentState = state;
+  let targetMsgId: string;
+
+  // If edit buffer not empty, commit first then mark as deleted
+  if (state.edits.ops.length > 0) {
+    const { state: committed, msg } = commitEdits(state);
+    if (!msg) return { state, msg: null };
+    currentState = committed;
+    targetMsgId = msg.id;
+  } else {
+    // Find last non-deleted message from this session
+    const lastActive = [...currentState.journal]
+      .reverse()
+      .find(e => !e.deletedAt && e.msg.sessionId === currentState.sessionId);
+
+    if (!lastActive) return { state: currentState, msg: null };
+    targetMsgId = lastActive.msg.id;
+  }
+
+  // Create undo message
+  const newClock = clockManager.increment(currentState.vectorClock, currentState.sessionId);
+  const undoMsg: CRDTMessage = {
+    id: generateUUID(),
+    sessionId: currentState.sessionId,
+    clock: newClock,
+    lamportTime: currentState.lamportTime + 1,
+    timestamp: Date.now(),
+    ops: [{ otype: 'meta.undo', key: '_meta', path: '_meta', targetMsgId }],
+  };
+
+  // Apply locally
+  const newState = produce(currentState, draft => {
+    // Add undo message to journal
+    draft.journal.push({ msg: undoMsg, ack: false });
+
+    // Mark target as deleted
+    const target = draft.journal.find(e => e.msg.id === targetMsgId);
+    if (target) target.deletedAt = undoMsg.timestamp;
+
+    // Update clocks
+    draft.lamportTime = undoMsg.lamportTime;
+    draft.vectorClock = newClock;
+
+    // Rebuild graph
+    draft.graph = rebuildGraph(draft.snapshot, draft.journal, draft.edits.ops);
+  });
+
+  return { state: newState, msg: undoMsg };
+}
+
+/**
+ * Action: Redo
+ */
+export function redo(state: ClientState): { state: ClientState; msg: CRDTMessage | null } {
+  // Find last deleted message from this session
+  const lastDeleted = [...state.journal]
+    .reverse()
+    .find(e => e.deletedAt && e.msg.sessionId === state.sessionId);
+
+  if (!lastDeleted) return { state, msg: null };
+
+  // Create redo message
+  const newClock = clockManager.increment(state.vectorClock, state.sessionId);
+  const redoMsg: CRDTMessage = {
+    id: generateUUID(),
+    sessionId: state.sessionId,
+    clock: newClock,
+    lamportTime: state.lamportTime + 1,
+    timestamp: Date.now(),
+    ops: [{ otype: 'meta.redo', key: '_meta', path: '_meta', targetMsgId: lastDeleted.msg.id }],
+  };
+
+  // Apply locally
+  const newState = produce(state, draft => {
+    // Add redo message to journal
+    draft.journal.push({ msg: redoMsg, ack: false });
+
+    // Clear deletedAt on target
+    const target = draft.journal.find(e => e.msg.id === lastDeleted.msg.id);
+    if (target) delete target.deletedAt;
+
+    // Update clocks
+    draft.lamportTime = redoMsg.lamportTime;
+    draft.vectorClock = newClock;
+
+    // Rebuild graph
+    draft.graph = rebuildGraph(draft.snapshot, draft.journal, draft.edits.ops);
+  });
+
+  return { state: newState, msg: redoMsg };
+}
+
+/**
+ * Action: Compact (create snapshot from acked entries)
+ */
+export function compact(state: ClientState): ClientState {
+  const lastAckedIdx = state.journal.findLastIndex(e => e.ack);
+  if (lastAckedIdx < 0) return state;
+
+  return produce(state, draft => {
+    // Build new snapshot (skip deleted entries and meta ops)
+    let snapshotGraph = draft.snapshot.graph;
+    for (let i = 0; i <= lastAckedIdx; i++) {
+      const entry = draft.journal[i];
+      if (entry.deletedAt) continue;
+
+      const realOps = entry.msg.ops.filter(op => !op.otype.startsWith('meta.'));
+      if (realOps.length > 0) {
+        snapshotGraph = applyMessage(snapshotGraph, { ...entry.msg, ops: realOps });
+      }
+    }
+
+    draft.snapshot = {
+      graph: snapshotGraph,
+      vectorClock: draft.journal[lastAckedIdx].msg.clock,
+      journalIndex: draft.snapshot.journalIndex + lastAckedIdx + 1,
+    };
+
+    // Remove compacted entries
+    draft.journal = draft.journal.slice(lastAckedIdx + 1);
+  });
+}
+
+/**
+ * Initialize from server snapshot + journal
+ */
+export function initFromServer(
+  sessionId: string,
+  snapshot: Snapshot,
+  journal: CRDTMessage[]
+): ClientState {
+  let graph = snapshot.graph;
+  const journalEntries: JournalEntry[] = [];
+  let maxLamport = 0;
+  let mergedClock: VectorClock = snapshot.vectorClock;
+
+  for (const msg of journal) {
+    // Process meta ops
+    for (const op of msg.ops) {
+      if (op.otype === 'meta.undo') {
+        const targetMsgId = (op as any).targetMsgId;
+        const target = journalEntries.find(e => e.msg.id === targetMsgId);
+        if (target) target.deletedAt = msg.timestamp;
+      } else if (op.otype === 'meta.redo') {
+        const targetMsgId = (op as any).targetMsgId;
+        const target = journalEntries.find(e => e.msg.id === targetMsgId);
+        if (target) delete target.deletedAt;
+      }
+    }
+
+    journalEntries.push({ msg, ack: true });
+    maxLamport = Math.max(maxLamport, msg.lamportTime);
+    mergedClock = clockManager.merge(mergedClock, msg.clock);
+  }
+
+  // Rebuild graph
+  graph = rebuildGraph(snapshot, journalEntries, []);
+
+  return {
+    graph,
+    journal: journalEntries,
+    edits: { ops: [], startGraph: null },
+    snapshot,
+    lamportTime: maxLamport,
+    vectorClock: clockManager.increment(mergedClock, sessionId),
+    sessionId,
+  };
+}

package/src/client/createGraph.ts

@@ -0,0 +1,132 @@
+/**
+ * createGraph - Factory function for creating a graph store
+ *
+ * Usage:
+ * ```typescript
+ * const store = createGraph({
+ *   sessionId: 'my-session',
+ *   onSend: (msg) => websocket.send(msg),
+ * });
+ *
+ * store.edit({ otype: 'vector3.add', key: 'cube', path: 'position', value: [1, 0, 0] });
+ * store.commit('Move cube');
+ * store.undo();
+ * ```
+ */
+
+import { enableMapSet } from 'immer';
+import type { CRDTMessage, Operation } from '../operations/OperationTypes.js';
+import type { ClientState, CreateGraphOptions, GraphStore, Snapshot } from './types.js';
+import {
+  createInitialState,
+  onEdit,
+  commitEdits,
+  cancelEdits,
+  onServerAck,
+  onRemoteMessage,
+  undo,
+  redo,
+  compact,
+  initFromServer,
+} from './actions.js';
+
+// Enable immer support for Map and Set
+enableMapSet();
+
+/**
+ * Create a graph store
+ */
+export function createGraph(options: CreateGraphOptions): GraphStore {
+  let state = createInitialState(options.sessionId, options.initialSnapshot);
+  const listeners = new Set<() => void>();
+
+  function dispatch(fn: (s: ClientState) => ClientState): void {
+    state = fn(state);
+    options.onStateChange?.(state);
+    listeners.forEach(l => l());
+  }
+
+  return {
+    // State access
+    getState: () => state,
+
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    // Edit operations
+    edit: (op: Operation) => {
+      dispatch(s => onEdit(s, op));
+    },
+
+    commit: (_description?: string) => {
+      const result = commitEdits(state, _description);
+      dispatch(() => result.state);
+      if (result.msg) {
+        options.onSend?.(result.msg);
+      }
+      return result.msg;
+    },
+
+    // Server communication
+    receive: (msg: CRDTMessage) => {
+      dispatch(s => onRemoteMessage(s, msg));
+    },
+
+    ack: (msgId: string) => {
+      dispatch(s => onServerAck(s, msgId));
+    },
+
+    // Undo/redo
+    undo: () => {
+      const result = undo(state);
+      dispatch(() => result.state);
+      if (result.msg) {
+        options.onSend?.(result.msg);
+      }
+      return { msg: result.msg };
+    },
+
+    redo: () => {
+      const result = redo(state);
+      dispatch(() => result.state);
+      if (result.msg) {
+        options.onSend?.(result.msg);
+      }
+      return { msg: result.msg };
+    },
+
+    // Maintenance
+    compact: () => {
+      dispatch(s => compact(s));
+    },
+  };
+}
+
+/**
+ * Create a graph store initialized from server state
+ */
+export function createGraphFromServer(
+  options: CreateGraphOptions & {
+    snapshot: Snapshot;
+    journal: CRDTMessage[];
+  }
+): GraphStore {
+  const store = createGraph(options);
+
+  // Replace state with server-initialized state
+  const serverState = initFromServer(
+    options.sessionId,
+    options.snapshot,
+    options.journal
+  );
+
+  // Hack: directly set state (since we don't expose setState)
+  (store as any)._state = serverState;
+
+  return store;
+}
+
+// Re-export types
+export type { ClientState, CreateGraphOptions, GraphStore, Snapshot, JournalEntry, EditBuffer } from './types.js';