@vuer-ai/vuer-rtc 0.4.2 → 0.5.0

package/src/client/EditBuffer.ts

@@ -81,7 +81,7 @@ export function isPositionTextDeleteOp(op: Operation): op is PositionTextDeleteO
 }
 
 /**
- * Coalesce consecutive text operations in an operation array.
+ * Coalesce consecutive text operations (position-based format only).
  * Merges sequential text.insert and text.delete operations.
  *
  * Insert: Consecutive inserts at adjacent positions
@@ -93,6 +93,18 @@ export function isPositionTextDeleteOp(op: Operation): op is PositionTextDeleteO
  *   - Backward (Backspace): Position moves left by length
  *     del(10, 1), del(9, 1) → del(9, 2)
  *
+ * IMPORTANT: This function is for POSITION-BASED coalescence only.
+ * Operations with CRDT metadata (id, parentId, seq) are skipped and passed through unchanged.
+ * For CRDT-level coalescence, use coalesceGraphOps() instead.
+ *
+ * Why the distinction?
+ * - Position-based: Coalesce before CRDT conversion (edit buffer stage)
+ * - CRDT-level: Coalesce after CRDT conversion (journal/network stage)
+ *
+ * Currently, the graph store flow applies CRDT metadata during onEdit(),
+ * so this function is not used for graph text operations.
+ * See coalesceGraphOps() for CRDT-level coalescence.
+ *
  * Returns a new array with coalesced operations.
  */
 export function coalesceTextOps(ops: Operation[]): Operation[] {
@@ -104,13 +116,31 @@ export function coalesceTextOps(ops: Operation[]): Operation[] {
 
   for (const op of ops) {
     if (isPositionTextInsertOp(op)) {
+      // Check if operation has CRDT metadata - if so, don't coalesce it
+      const hasCRDTMetadata = (op as any).id !== undefined;
+
+      if (hasCRDTMetadata) {
+        // Flush any pending operations
+        if (pendingInsert !== null) {
+          result.push(pendingInsert as unknown as Operation);
+          pendingInsert = null;
+        }
+        if (pendingDelete !== null) {
+          result.push(pendingDelete as unknown as Operation);
+          pendingDelete = null;
+        }
+        // Pass through operations with CRDT metadata unchanged
+        result.push(op as unknown as Operation);
+        continue;
+      }
+
       // Flush any pending delete
       if (pendingDelete !== null) {
         result.push(pendingDelete as unknown as Operation);
         pendingDelete = null;
       }
 
-      // Coalesce inserts
+      // Coalesce inserts (only for position-based operations without CRDT metadata)
       if (pendingInsert === null) {
         // Start new pending insert
         pendingInsert = {
@@ -145,13 +175,31 @@ export function coalesceTextOps(ops: Operation[]): Operation[] {
         };
       }
     } else if (isPositionTextDeleteOp(op)) {
+      // Check if operation has CRDT metadata - if so, don't coalesce it
+      const hasCRDTMetadata = (op as any).deletions !== undefined;
+
+      if (hasCRDTMetadata) {
+        // Flush any pending operations
+        if (pendingInsert !== null) {
+          result.push(pendingInsert as unknown as Operation);
+          pendingInsert = null;
+        }
+        if (pendingDelete !== null) {
+          result.push(pendingDelete as unknown as Operation);
+          pendingDelete = null;
+        }
+        // Pass through operations with CRDT metadata unchanged
+        result.push(op as unknown as Operation);
+        continue;
+      }
+
       // Flush any pending insert
       if (pendingInsert !== null) {
         result.push(pendingInsert as unknown as Operation);
         pendingInsert = null;
       }
 
-      // Coalesce deletes
+      // Coalesce deletes (only for position-based operations without CRDT metadata)
       if (pendingDelete === null) {
         pendingDelete = {
           otype: 'text.delete',

package/src/client/actions.ts

@@ -13,8 +13,9 @@ import type { CRDTMessage, Operation, SceneGraph, SceneNode } from '../operation
 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, opDedupKey, coalesceTextOps } from './EditBuffer.js';
+import { isAdditiveOp, mergeValues, opDedupKey } from './EditBuffer.js';
 import { TextRope, snapshot as cloneRope, compact as compactRope } from '../crdt/Rope.js';
+import { coalesceGraphOps } from './coalesceGraphOps.js';
 
 const clockManager = new VectorClockManager();
 
@@ -237,15 +238,11 @@ export function onEdit(state: ClientState, op: Operation): ClientState {
 
   for (const k of new Set(keysToClone)) {
     const orig = graph.nodes[k];
+    // Shallow clone preserves TextRope references (they're mutated in place)
     const cloned: SceneNode = {
       ...orig,
       children: orig.children ? [...orig.children] : [],
     };
-    for (const prop of Object.keys(cloned)) {
-      if (cloned[prop] instanceof TextRope) {
-        cloned[prop] = cloneRope(cloned[prop] as TextRope);
-      }
-    }
     graph.nodes[k] = cloned;
   }
 
@@ -265,10 +262,15 @@ export function onEdit(state: ClientState, op: Operation): ClientState {
 
 /**
  * Action: Commit edits
+ *
+ * @param state - Current client state
+ * @param description - Optional message description
+ * @param coalescingThresholdMs - Time threshold for operation coalescence (default: no coalescence)
  */
 export function commitEdits(
   state: ClientState,
-  _description?: string
+  description?: string,
+  coalescingThresholdMs?: number
 ): { state: ClientState; msg: CRDTMessage | null } {
   if (state.edits.ops.length === 0) {
     return { state, msg: null };
@@ -277,8 +279,10 @@ export function commitEdits(
   const newClock = clockManager.increment(state.vectorClock, state.sessionId);
   const newLamport = state.lamportTime + 1;
 
-  // Coalesce consecutive text operations before sending
-  const coalescedOps = coalesceTextOps(state.edits.ops);
+  // Coalesce CRDT operations before sending (if threshold specified)
+  const coalescedOps = coalescingThresholdMs !== undefined
+    ? coalesceGraphOps(state.edits.ops, { thresholdMs: coalescingThresholdMs })
+    : state.edits.ops;
 
   const msg: CRDTMessage = {
     id: `${state.sessionId}:${newLamport}`,

package/src/client/coalesceGraphOps.ts

@@ -0,0 +1,40 @@
+/**
+ * Graph Operation Coalescence
+ *
+ * Coalesces graph CRDT operations using the coalescence registry.
+ * This is the main API for coalescing operations in the graph store.
+ */
+
+import type { Operation } from '../operations/OperationTypes.js';
+import { coalesceOperations, type CoalesceOptions } from './coalescence/index.js';
+
+/**
+ * Coalesce graph operations for network transmission or journal storage.
+ *
+ * Uses the coalescence registry to merge consecutive operations:
+ * - text.insert: Merges consecutive inserts from same agent
+ * - text.delete: Merges consecutive deletes on same target
+ * - Future: vector3.add, number.add, etc.
+ *
+ * Example:
+ * ```typescript
+ * const ops = [
+ *   { otype: 'text.insert', id: 'alice:1', content: 'h', ... },
+ *   { otype: 'text.insert', id: 'alice:2', content: 'e', ... },
+ *   { otype: 'text.insert', id: 'alice:3', content: 'l', ... },
+ * ];
+ *
+ * const coalesced = coalesceGraphOps(ops, { thresholdMs: 300 });
+ * // Result: [{ otype: 'text.insert', id: 'alice:1', content: 'hel', ... }]
+ * ```
+ *
+ * @param ops - Array of graph operations
+ * @param options - Coalescence options
+ * @returns New array with coalesced operations
+ */
+export function coalesceGraphOps(
+  ops: Operation[],
+  options: CoalesceOptions = {}
+): Operation[] {
+  return coalesceOperations(ops, options);
+}

package/src/client/coalesceTextOperations.ts

@@ -0,0 +1,134 @@
+/**
+ * Coalesce Text Operations
+ *
+ * Merges consecutive CRDT insert operations to reduce network traffic and storage.
+ * Uses the same comparison logic as the graph CRDT: seq → ts → id.
+ *
+ * Merge conditions:
+ * 1. Same agent
+ * 2. Sequential IDs (ID seq numbers are consecutive)
+ * 3. Within time threshold (ts difference)
+ * 4. Compatible YATA structure (forms a chain)
+ */
+
+import type { TextOperation } from './textTypes.js';
+import type { InsertOp } from '../crdt/Rope.js';
+import { parseItemId } from '../crdt/Rope.js';
+
+export interface CoalesceOptions {
+  /** Time threshold in milliseconds (default: 1000ms = 1 second) */
+  thresholdMs?: number;
+}
+
+/**
+ * Coalesce consecutive text insert operations.
+ *
+ * Example:
+ * Input:  [insert(id:"alice:1", "h"), insert(id:"alice:2", "e"), insert(id:"alice:3", "l")]
+ * Output: [insert(id:"alice:1", "hel")]
+ *
+ * @param ops - Array of text operations
+ * @param options - Coalescence options
+ * @returns New array with coalesced operations
+ */
+export function coalesceTextOperations(
+  ops: TextOperation[],
+  options: CoalesceOptions = {}
+): TextOperation[] {
+  const { thresholdMs = 1000 } = options;
+
+  if (ops.length === 0) return ops;
+
+  const result: TextOperation[] = [];
+  let pendingInsert: { type: 'insert'; op: InsertOp } | null = null;
+
+  for (const op of ops) {
+    if (op.type === 'insert') {
+      if (pendingInsert === null) {
+        // Start new pending insert
+        pendingInsert = { type: 'insert', op: { ...op.op } };
+      } else {
+        const prevOp = pendingInsert.op;
+        const currOp = op.op;
+
+        // Parse IDs to extract agent and local sequence numbers
+        const prevId = parseItemId(prevOp.id);
+        const currId = parseItemId(currOp.id);
+
+        // Check merge conditions
+        const sameAgent = prevId.agent === currId.agent;
+
+        // IDs must be sequential: next ID = prev ID + prev content length
+        // Example: prev="alice:5" content="hel"(3 chars) → next="alice:8"
+        const sequentialIds = currId.seq === prevId.seq + prevOp.content.length;
+
+        // Time threshold: operations must be close in time (ts is in seconds)
+        const timeDiffMs = (currOp.ts - prevOp.ts) * 1000;
+        const withinThreshold = timeDiffMs <= thresholdMs;
+
+        // YATA structure: check if operations form a valid chain
+        // Current op's parent should be the last character ID in the merged content
+        // (not the first ID, which is what prevOp.id contains after merging)
+        // OR both should have the same parent (inserting at same position)
+        const prevLastId = (prevOp as any)._lastCharId || prevOp.id;
+        const formsChain =
+          currOp.parentId === prevLastId ||
+          (prevOp.parentId === currOp.parentId && prevOp.parentId !== null);
+
+        if (sameAgent && sequentialIds && withinThreshold && formsChain) {
+          // Merge operations
+          const mergedOp: InsertOp = {
+            id: prevOp.id, // Keep first ID (anchor point)
+            content: prevOp.content + currOp.content, // Concatenate content
+            parentId: prevOp.parentId, // Keep first parentId
+            seq: Math.max(prevOp.seq, currOp.seq), // Use max Lamport clock for ordering
+            ts: prevOp.ts, // Keep first timestamp (when sequence started)
+            // Track the last character ID for chain validation in next merge
+            _lastCharId: currOp.id,
+          } as any;
+          pendingInsert = { type: 'insert', op: mergedOp };
+        } else {
+          // Debug: Log why merge failed
+          if (!sameAgent) console.log('[coalesce] Different agents:', prevId.agent, 'vs', currId.agent);
+          if (!sequentialIds) console.log('[coalesce] Non-sequential IDs:', currId.seq, '!==', prevId.seq + prevOp.content.length);
+          if (!withinThreshold) console.log('[coalesce] Time threshold exceeded:', timeDiffMs, 'ms >', thresholdMs, 'ms');
+          if (!formsChain) console.log('[coalesce] Not a YATA chain:', { currParent: currOp.parentId, prevId: prevOp.id, prevParent: prevOp.parentId, currOp: currOp.id });
+
+          // Can't merge - flush pending and start new
+          result.push(pendingInsert);
+          pendingInsert = { type: 'insert', op: { ...currOp } };
+        }
+      }
+    } else {
+      // Delete operation - flush any pending insert
+      if (pendingInsert !== null) {
+        result.push(pendingInsert);
+        pendingInsert = null;
+      }
+      result.push(op);
+    }
+  }
+
+  // Flush any remaining pending insert
+  if (pendingInsert !== null) {
+    result.push(pendingInsert);
+  }
+
+  return result;
+}
+
+/**
+ * Comparison logic for text operations (matches graph CRDT):
+ * 1. Compare by Lamport clock (seq)
+ * 2. If equal, compare by wall-clock time (ts)
+ * 3. If equal, compare by ID (lexicographic)
+ *
+ * @param a - First operation
+ * @param b - Second operation
+ * @returns Negative if a < b, positive if a > b, 0 if equal
+ */
+export function compareTextOps(a: InsertOp, b: InsertOp): number {
+  if (a.seq !== b.seq) return a.seq - b.seq; // Lamport clock
+  if (a.ts !== b.ts) return a.ts - b.ts; // Wall-clock time
+  return a.id.localeCompare(b.id); // Final fallback
+}

package/src/client/coalescence/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Coalescence Utilities
+ *
+ * Extensible operation coalescence system with registration pattern.
+ */
+
+export {
+  coalesceOperations,
+  registerCoalescer,
+  getCoalescer,
+  hasCoalescer,
+  type CoalesceOptions,
+  type CoalesceHandler,
+  type TypeGuard,
+} from './registry.js';
+
+export { coalesceTextInserts, isTextInsertOp, type TextInsertOp } from './textInserts.js';
+export { coalesceTextDeletes, isTextDeleteOp, type TextDeleteOp } from './textDeletes.js';

package/src/client/coalescence/registry.ts

@@ -0,0 +1,137 @@
+/**
+ * Coalescence Registry
+ *
+ * Maps operation types to their coalescence handlers.
+ * Allows extensible operation coalescence with a consistent interface.
+ */
+
+import type { Operation } from '../../operations/OperationTypes.js';
+import { coalesceTextInserts, isTextInsertOp, type TextInsertOp } from './textInserts.js';
+import { coalesceTextDeletes, isTextDeleteOp, type TextDeleteOp } from './textDeletes.js';
+
+export interface CoalesceOptions {
+  /** Time threshold in milliseconds (default: 1000ms = 1 second) */
+  thresholdMs?: number;
+}
+
+/**
+ * Coalescence handler function type
+ */
+export type CoalesceHandler<T extends Operation = Operation> = (
+  ops: T[],
+  options: CoalesceOptions
+) => T[];
+
+/**
+ * Type guard function type
+ */
+export type TypeGuard<T extends Operation = Operation> = (op: Operation) => op is T;
+
+/**
+ * Registry entry combining type guard and handler
+ */
+interface RegistryEntry<T extends Operation = Operation> {
+  guard: TypeGuard<T>;
+  handler: CoalesceHandler<T>;
+}
+
+/**
+ * Global coalescence registry
+ */
+const registry = new Map<string, RegistryEntry>();
+
+/**
+ * Register a coalescence handler for an operation type
+ */
+export function registerCoalescer<T extends Operation>(
+  otype: string,
+  guard: TypeGuard<T>,
+  handler: CoalesceHandler<T>
+): void {
+  registry.set(otype, {
+    guard: guard as unknown as TypeGuard,
+    handler: handler as unknown as CoalesceHandler
+  });
+}
+
+/**
+ * Get coalescence handler for an operation type
+ */
+export function getCoalescer(otype: string): RegistryEntry | undefined {
+  return registry.get(otype);
+}
+
+/**
+ * Check if an operation type has a registered coalescer
+ */
+export function hasCoalescer(otype: string): boolean {
+  return registry.has(otype);
+}
+
+/**
+ * Coalesce operations by grouping by type and applying registered handlers
+ *
+ * @param ops - Array of operations
+ * @param options - Coalescence options
+ * @returns New array with coalesced operations
+ */
+export function coalesceOperations(
+  ops: Operation[],
+  options: CoalesceOptions = {}
+): Operation[] {
+  if (ops.length === 0) return ops;
+
+  const result: Operation[] = [];
+  let pendingGroup: Operation[] = [];
+  let currentType: string | null = null;
+
+  for (const op of ops) {
+    const entry = registry.get(op.otype);
+
+    if (entry && entry.guard(op)) {
+      // Operation has a coalescer
+      if (currentType === op.otype) {
+        // Same type - add to pending group
+        pendingGroup.push(op);
+      } else {
+        // Different type - flush pending and start new group
+        if (currentType !== null && pendingGroup.length > 0) {
+          const prevEntry = registry.get(currentType);
+          if (prevEntry) {
+            const coalesced = prevEntry.handler(pendingGroup as any, options);
+            result.push(...coalesced);
+          }
+        }
+        currentType = op.otype;
+        pendingGroup = [op];
+      }
+    } else {
+      // No coalescer - flush pending and pass through
+      if (currentType !== null && pendingGroup.length > 0) {
+        const prevEntry = registry.get(currentType);
+        if (prevEntry) {
+          const coalesced = prevEntry.handler(pendingGroup as any, options);
+          result.push(...coalesced);
+        }
+      }
+      currentType = null;
+      pendingGroup = [];
+      result.push(op);
+    }
+  }
+
+  // Flush any remaining pending group
+  if (currentType !== null && pendingGroup.length > 0) {
+    const entry = registry.get(currentType);
+    if (entry) {
+      const coalesced = entry.handler(pendingGroup as any, options);
+      result.push(...coalesced);
+    }
+  }
+
+  return result;
+}
+
+// Register built-in coalescers
+registerCoalescer('text.insert', isTextInsertOp as TypeGuard<any>, coalesceTextInserts as CoalesceHandler<any>);
+registerCoalescer('text.delete', isTextDeleteOp as TypeGuard<any>, coalesceTextDeletes as CoalesceHandler<any>);

package/src/client/coalescence/textDeletes.ts

@@ -0,0 +1,94 @@
+/**
+ * Text Delete Coalescence Utility
+ *
+ * Merges consecutive text delete operations.
+ */
+
+import type { Operation } from '../../operations/OperationTypes.js';
+
+export interface TextDeleteOp {
+  otype: 'text.delete';
+  key: string;
+  path: string;
+  deletions: Array<{ id: string; length: number }>; // Array of deletion ranges
+  seq: number;
+  ts: number;
+}
+
+export interface CoalesceOptions {
+  /** Time threshold in milliseconds (default: 1000ms = 1 second) */
+  thresholdMs?: number;
+}
+
+/**
+ * Check if an operation is a text delete with CRDT metadata
+ */
+export function isTextDeleteOp(op: Operation): op is TextDeleteOp {
+  return (
+    op.otype === 'text.delete' &&
+    Array.isArray((op as any).deletions) &&
+    typeof (op as any).seq === 'number' &&
+    typeof (op as any).ts === 'number'
+  );
+}
+
+/**
+ * Coalesce consecutive text delete operations.
+ *
+ * Example:
+ * Input:  [delete(["alice:5"]), delete(["alice:6", "alice:7"])]
+ * Output: [delete(["alice:5", "alice:6", "alice:7"])]
+ *
+ * @param ops - Array of text delete operations
+ * @param options - Coalescence options
+ * @returns New array with coalesced operations
+ */
+export function coalesceTextDeletes(
+  ops: TextDeleteOp[],
+  options: CoalesceOptions = {}
+): TextDeleteOp[] {
+  const { thresholdMs = 1000 } = options;
+
+  if (ops.length === 0) return ops;
+
+  const result: TextDeleteOp[] = [];
+  let pending: TextDeleteOp | null = null;
+
+  for (const op of ops) {
+    if (pending === null) {
+      // Start new pending delete
+      pending = { ...op, deletions: [...op.deletions] };
+    } else {
+      // Check merge conditions
+      const sameTarget = pending.key === op.key && pending.path === op.path;
+
+      // Time threshold: operations must be close in time (ts is in seconds)
+      const timeDiffMs = (op.ts - pending.ts) * 1000;
+      const withinThreshold = timeDiffMs <= thresholdMs;
+
+      if (sameTarget && withinThreshold) {
+        // Merge operations - combine deletion lists
+        const merged: TextDeleteOp = {
+          otype: 'text.delete',
+          key: pending.key,
+          path: pending.path,
+          deletions: [...pending.deletions, ...op.deletions],
+          seq: Math.max(pending.seq, op.seq), // Use max Lamport clock for ordering
+          ts: pending.ts, // Keep first timestamp (when sequence started)
+        };
+        pending = merged;
+      } else {
+        // Can't merge - flush pending and start new
+        result.push(pending);
+        pending = { ...op, deletions: [...op.deletions] };
+      }
+    }
+  }
+
+  // Flush any remaining pending delete
+  if (pending !== null) {
+    result.push(pending);
+  }
+
+  return result;
+}