@vuer-ai/vuer-rtc 0.5.3 → 0.6.0

package/src/client/coalesceTextOperations.ts

@@ -14,12 +14,33 @@
 import type { TextOperation } from './textTypes.js';
 import type { InsertOp } from '../crdt/Rope.js';
 import { parseItemId } from '../crdt/Rope.js';
+import { optimizeDeletions, parseItemId as parseId } from './coalescence/utils.js';
 
 export interface CoalesceOptions {
   /** Time threshold in milliseconds (default: 1000ms = 1 second) */
   thresholdMs?: number;
 }
 
+/**
+ * Sort and optimize deletions array.
+ * Deletions must be sorted in ascending order for optimizeDeletions to work correctly.
+ */
+function sortAndOptimizeDeletions(deletions: Array<{ id: string; length: number }>): Array<{ id: string; length: number }> {
+  if (deletions.length === 0) return deletions;
+
+  // Sort deletions by agent, then by sequence number (ascending)
+  const sorted = [...deletions].sort((a, b) => {
+    const aId = parseId(a.id);
+    const bId = parseId(b.id);
+    if (aId.agent !== bId.agent) {
+      return aId.agent.localeCompare(bId.agent);
+    }
+    return aId.seq - bId.seq;
+  });
+
+  return optimizeDeletions(sorted);
+}
+
 /**
  * Coalesce consecutive text insert operations.
  *
@@ -47,6 +68,8 @@ export function coalesceTextOperations(
     if (op.type === 'insert') {
       // Flush any pending delete before starting new insert
       if (pendingDelete !== null) {
+        // Sort and optimize deletions array before flushing
+        pendingDelete.op.deletions = sortAndOptimizeDeletions(pendingDelete.op.deletions);
         result.push(pendingDelete);
         pendingDelete = null;
       }
@@ -137,6 +160,8 @@ export function coalesceTextOperations(
         pendingInsert = null;
       }
       if (pendingDelete !== null) {
+        // Sort and optimize deletions array before flushing
+        pendingDelete.op.deletions = sortAndOptimizeDeletions(pendingDelete.op.deletions);
         result.push(pendingDelete);
         pendingDelete = null;
       }
@@ -149,6 +174,8 @@ export function coalesceTextOperations(
     result.push(pendingInsert);
   }
   if (pendingDelete !== null) {
+    // Sort and optimize deletions array before flushing
+    pendingDelete.op.deletions = sortAndOptimizeDeletions(pendingDelete.op.deletions);
     result.push(pendingDelete);
   }
 

package/src/client/coalescence/index.ts

@@ -16,3 +16,6 @@ export {
 
 export { coalesceTextInserts, isTextInsertOp, type TextInsertOp } from './textInserts.js';
 export { coalesceTextDeletes, isTextDeleteOp, type TextDeleteOp } from './textDeletes.js';
+export { coalesceNumberAdds, isNumberAddOp, type NumberAddOp } from './numberOperations.js';
+export { coalesceVector3Adds, isVector3AddOp, type Vector3AddOp } from './vector3Operations.js';
+export { coalesceLWWSets, isLWWSetOp, type LWWSetOp } from './lwwOperations.js';

package/src/client/coalescence/lwwOperations.ts

@@ -0,0 +1,104 @@
+/**
+ * Last-Write-Wins (LWW) Operations Coalescence
+ *
+ * Generic coalescer for all *.set operations.
+ * Set operations follow Last-Write-Wins semantics - only the last value matters.
+ *
+ * Supported operations:
+ * - number.set, string.set, boolean.set
+ * - vector3.set, euler.set, quaternion.set, color.set
+ * - array.set, object.set
+ */
+
+import type {
+  Operation,
+  NumberSetOp,
+  StringSetOp,
+  BooleanSetOp,
+  Vector3SetOp,
+  EulerSetOp,
+  QuaternionSetOp,
+  ColorSetOp,
+  ArraySetOp,
+  ObjectSetOp,
+} from '../../operations/OperationTypes.js';
+import type { CoalesceOptions } from './registry.js';
+
+// Union of all *.set operation types
+export type LWWSetOp =
+  | NumberSetOp
+  | StringSetOp
+  | BooleanSetOp
+  | Vector3SetOp
+  | EulerSetOp
+  | QuaternionSetOp
+  | ColorSetOp
+  | ArraySetOp
+  | ObjectSetOp;
+
+/**
+ * Check if an operation is a *.set operation
+ */
+export function isLWWSetOp(op: Operation): op is LWWSetOp {
+  return (
+    typeof op.otype === 'string' &&
+    op.otype.endsWith('.set') &&
+    (op as any).value !== undefined
+  );
+}
+
+/**
+ * Coalesce consecutive *.set operations using Last-Write-Wins semantics.
+ *
+ * Since set operations follow LWW, only the last value in a sequence matters.
+ * We can safely discard all but the last operation for the same target.
+ *
+ * Example:
+ * Input:  [set(key:"cube", path:"color", value:"red"), set(key:"cube", path:"color", value:"blue")]
+ * Output: [set(key:"cube", path:"color", value:"blue")]
+ *
+ * @param ops - Array of *.set operations
+ * @param options - Coalescence options
+ *   NOTE: Time threshold is ignored for Last-Write-Wins operations.
+ *   LWW semantics mean only the final value matters, regardless of timing,
+ *   so we keep only the last operation on each target.
+ * @returns New array with coalesced operations
+ */
+export function coalesceLWWSets(
+  ops: LWWSetOp[],
+  options: CoalesceOptions = {}
+): LWWSetOp[] {
+  if (ops.length === 0) return ops;
+
+  const result: LWWSetOp[] = [];
+  let pending: LWWSetOp | null = null;
+
+  for (const op of ops) {
+    if (pending === null) {
+      // Start new pending set
+      pending = { ...op };
+    } else {
+      // Check if operations target the same property AND same operation type
+      const sameTarget =
+        pending.key === op.key &&
+        pending.path === op.path &&
+        pending.otype === op.otype;
+
+      if (sameTarget) {
+        // LWW: Replace with newer value
+        pending = { ...op };
+      } else {
+        // Different target or type - flush pending and start new
+        result.push(pending);
+        pending = { ...op };
+      }
+    }
+  }
+
+  // Flush any remaining pending set
+  if (pending !== null) {
+    result.push(pending);
+  }
+
+  return result;
+}

package/src/client/coalescence/numberOperations.ts

@@ -0,0 +1,80 @@
+/**
+ * Number Operations Coalescence
+ *
+ * Merges consecutive number.add operations on the same target.
+ * Addition is commutative, so we can safely merge multiple adds into one.
+ */
+
+import type { Operation, NumberAddOp } from '../../operations/OperationTypes.js';
+import type { CoalesceOptions } from './registry.js';
+
+// Re-export type for convenience
+export type { NumberAddOp };
+
+/**
+ * Check if an operation is a number.add operation
+ */
+export function isNumberAddOp(op: Operation): op is NumberAddOp {
+  return (
+    op.otype === 'number.add' &&
+    typeof (op as any).value === 'number'
+  );
+}
+
+/**
+ * Coalesce consecutive number.add operations.
+ *
+ * Since addition is commutative (a + b = b + a), we can safely merge
+ * all consecutive adds into a single operation by summing the values.
+ *
+ * Example:
+ * Input:  [add(key:"score", path:"value", value:10), add(key:"score", path:"value", value:5)]
+ * Output: [add(key:"score", path:"value", value:15)]
+ *
+ * @param ops - Array of number.add operations
+ * @param options - Coalescence options
+ *   NOTE: Time threshold is ignored for commutative operations like addition.
+ *   Mathematically, a+b = b+a regardless of when they occurred, so we merge
+ *   all consecutive operations on the same target without time restrictions.
+ * @returns New array with coalesced operations
+ */
+export function coalesceNumberAdds(
+  ops: NumberAddOp[],
+  options: CoalesceOptions = {}
+): NumberAddOp[] {
+  if (ops.length === 0) return ops;
+
+  const result: NumberAddOp[] = [];
+  let pending: NumberAddOp | null = null;
+
+  for (const op of ops) {
+    if (pending === null) {
+      // Start new pending add
+      pending = { ...op };
+    } else {
+      // Check if operations target the same property
+      const sameTarget = pending.key === op.key && pending.path === op.path;
+
+      if (sameTarget) {
+        // Merge operations by summing values
+        pending = {
+          otype: 'number.add',
+          key: pending.key,
+          path: pending.path,
+          value: pending.value + op.value,
+        };
+      } else {
+        // Different target - flush pending and start new
+        result.push(pending);
+        pending = { ...op };
+      }
+    }
+  }
+
+  // Flush any remaining pending add
+  if (pending !== null) {
+    result.push(pending);
+  }
+
+  return result;
+}

package/src/client/coalescence/registry.ts

@@ -8,6 +8,9 @@
 import type { Operation } from '../../operations/OperationTypes.js';
 import { coalesceTextInserts, isTextInsertOp, type TextInsertOp } from './textInserts.js';
 import { coalesceTextDeletes, isTextDeleteOp, type TextDeleteOp } from './textDeletes.js';
+import { coalesceNumberAdds, isNumberAddOp } from './numberOperations.js';
+import { coalesceVector3Adds, isVector3AddOp } from './vector3Operations.js';
+import { coalesceLWWSets, isLWWSetOp } from './lwwOperations.js';
 
 export interface CoalesceOptions {
   /** Time threshold in milliseconds (default: 1000ms = 1 second) */
@@ -135,3 +138,22 @@ export function coalesceOperations(
 // 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>);
+registerCoalescer('number.add', isNumberAddOp as TypeGuard<any>, coalesceNumberAdds as CoalesceHandler<any>);
+registerCoalescer('vector3.add', isVector3AddOp as TypeGuard<any>, coalesceVector3Adds as CoalesceHandler<any>);
+
+// Register LWW coalescer for all *.set operations
+const LWW_SET_OPERATIONS = [
+  'number.set',
+  'string.set',
+  'boolean.set',
+  'vector3.set',
+  'euler.set',
+  'quaternion.set',
+  'color.set',
+  'array.set',
+  'object.set',
+] as const;
+
+for (const otype of LWW_SET_OPERATIONS) {
+  registerCoalescer(otype, isLWWSetOp as TypeGuard<any>, coalesceLWWSets as CoalesceHandler<any>);
+}

package/src/client/coalescence/textDeletes.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Operation } from '../../operations/OperationTypes.js';
-import { optimizeDeletions } from './utils.js';
+import { optimizeDeletions, parseItemId } from './utils.js';
 
 export interface TextDeleteOp {
   otype: 'text.delete';
@@ -21,6 +21,26 @@ export interface CoalesceOptions {
   thresholdMs?: number;
 }
 
+/**
+ * Sort and optimize deletions array.
+ * Deletions must be sorted in ascending order for optimizeDeletions to work correctly.
+ */
+function sortAndOptimizeDeletions(deletions: Array<{ id: string; length: number }>): Array<{ id: string; length: number }> {
+  if (deletions.length === 0) return deletions;
+
+  // Sort deletions by agent, then by sequence number (ascending)
+  const sorted = [...deletions].sort((a, b) => {
+    const aId = parseItemId(a.id);
+    const bId = parseItemId(b.id);
+    if (aId.agent !== bId.agent) {
+      return aId.agent.localeCompare(bId.agent);
+    }
+    return aId.seq - bId.seq;
+  });
+
+  return optimizeDeletions(sorted);
+}
+
 /**
  * Check if an operation is a text delete with CRDT metadata
  */
@@ -83,14 +103,14 @@ export function coalesceTextDeletes(
 
   // Flush any remaining pending delete
   if (pending !== null) {
-    // Optimize deletions array before pushing
-    pending.deletions = optimizeDeletions(pending.deletions);
+    // Sort and optimize deletions array before pushing
+    pending.deletions = sortAndOptimizeDeletions(pending.deletions);
     result.push(pending);
   }
 
-  // Also optimize deletions in all previously pushed operations
+  // Also sort and optimize deletions in all previously pushed operations
   for (const op of result) {
-    op.deletions = optimizeDeletions(op.deletions);
+    op.deletions = sortAndOptimizeDeletions(op.deletions);
   }
 
   return result;

package/src/client/coalescence/vector3Operations.ts

@@ -0,0 +1,85 @@
+/**
+ * Vector3 Operations Coalescence
+ *
+ * Merges consecutive vector3.add operations on the same target.
+ * Component-wise addition is commutative, so we can safely merge multiple adds.
+ */
+
+import type { Operation, Vector3AddOp } from '../../operations/OperationTypes.js';
+import type { CoalesceOptions } from './registry.js';
+
+// Re-export type for convenience
+export type { Vector3AddOp };
+
+/**
+ * Check if an operation is a vector3.add operation
+ */
+export function isVector3AddOp(op: Operation): op is Vector3AddOp {
+  return (
+    op.otype === 'vector3.add' &&
+    Array.isArray((op as any).value) &&
+    (op as any).value.length === 3
+  );
+}
+
+/**
+ * Coalesce consecutive vector3.add operations.
+ *
+ * Since component-wise addition is commutative, we can safely merge
+ * all consecutive adds into a single operation by summing the vectors.
+ *
+ * Example:
+ * Input:  [add(key:"player", path:"position", value:[1,0,0]), add(key:"player", path:"position", value:[0,2,0])]
+ * Output: [add(key:"player", path:"position", value:[1,2,0])]
+ *
+ * @param ops - Array of vector3.add operations
+ * @param options - Coalescence options
+ *   NOTE: Time threshold is ignored for commutative operations like vector addition.
+ *   Component-wise addition is commutative regardless of timing, so we merge
+ *   all consecutive operations on the same target without time restrictions.
+ * @returns New array with coalesced operations
+ */
+export function coalesceVector3Adds(
+  ops: Vector3AddOp[],
+  options: CoalesceOptions = {}
+): Vector3AddOp[] {
+  if (ops.length === 0) return ops;
+
+  const result: Vector3AddOp[] = [];
+  let pending: Vector3AddOp | null = null;
+
+  for (const op of ops) {
+    if (pending === null) {
+      // Start new pending add (copy value array to avoid mutations)
+      pending = { ...op, value: [...op.value] as [number, number, number] };
+    } else {
+      // Check if operations target the same property
+      const sameTarget = pending.key === op.key && pending.path === op.path;
+
+      if (sameTarget) {
+        // Merge operations by summing vectors component-wise
+        pending = {
+          otype: 'vector3.add',
+          key: pending.key,
+          path: pending.path,
+          value: [
+            pending.value[0] + op.value[0],
+            pending.value[1] + op.value[1],
+            pending.value[2] + op.value[2],
+          ],
+        };
+      } else {
+        // Different target - flush pending and start new
+        result.push(pending);
+        pending = { ...op, value: [...op.value] as [number, number, number] };
+      }
+    }
+  }
+
+  // Flush any remaining pending add
+  if (pending !== null) {
+    result.push(pending);
+  }
+
+  return result;
+}

package/tests/client/coalesce-text-operations.test.ts

@@ -298,6 +298,105 @@ describe('coalesceTextOperations', () => {
     });
   });
 
+  describe('delete operations coalescence', () => {
+    it('should merge consecutive delete operations and optimize deletions array', () => {
+      // Simulate pressing backspace 7 times (7 separate delete operations)
+      const ops: TextOperation[] = [
+        {
+          type: 'delete',
+          op: {
+            deletions: [{ id: 'alice:7', length: 1 }],
+          },
+        } as any,
+        {
+          type: 'delete',
+          op: {
+            deletions: [{ id: 'alice:6', length: 1 }],
+          },
+        } as any,
+        {
+          type: 'delete',
+          op: {
+            deletions: [{ id: 'alice:5', length: 1 }],
+          },
+        } as any,
+        {
+          type: 'delete',
+          op: {
+            deletions: [{ id: 'alice:4', length: 1 }],
+          },
+        } as any,
+        {
+          type: 'delete',
+          op: {
+            deletions: [{ id: 'alice:3', length: 1 }],
+          },
+        } as any,
+        {
+          type: 'delete',
+          op: {
+            deletions: [{ id: 'alice:2', length: 1 }],
+          },
+        } as any,
+        {
+          type: 'delete',
+          op: {
+            deletions: [{ id: 'alice:1', length: 1 }],
+          },
+        } as any,
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 1000 });
+
+      // Should merge into ONE delete operation
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe('delete');
+
+      // CRITICAL: Deletions array should be optimized (7 entries → 1 entry)
+      const deleteOp = result[0] as any;
+      expect(deleteOp.op.deletions).toBeDefined();
+      expect(deleteOp.op.deletions).toHaveLength(1);
+      expect(deleteOp.op.deletions[0]).toEqual({ id: 'alice:1', length: 7 });
+    });
+
+    it('should optimize deletions with gaps', () => {
+      // Deletions with non-consecutive IDs (can't be fully merged)
+      const ops: TextOperation[] = [
+        {
+          type: 'delete',
+          op: {
+            deletions: [
+              { id: 'alice:5', length: 1 },
+              { id: 'alice:4', length: 1 },
+            ],
+          },
+        } as any,
+        {
+          type: 'delete',
+          op: {
+            deletions: [
+              { id: 'alice:2', length: 1 }, // Gap! alice:3 is missing
+              { id: 'alice:1', length: 1 },
+            ],
+          },
+        } as any,
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 1000 });
+
+      // Should merge into ONE delete operation
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe('delete');
+
+      // Deletions should be optimized: [alice:4-5 (len 2), alice:1-2 (len 2)]
+      const deleteOp = result[0] as any;
+      expect(deleteOp.op.deletions).toBeDefined();
+      expect(deleteOp.op.deletions).toHaveLength(2); // Two ranges due to gap
+      expect(deleteOp.op.deletions).toContainEqual({ id: 'alice:4', length: 2 });
+      expect(deleteOp.op.deletions).toContainEqual({ id: 'alice:1', length: 2 });
+    });
+  });
+
   describe('edge cases', () => {
     it('should handle empty operations array', () => {
       const result = coalesceTextOperations([]);

package/tests/client/delete-coalescence-bug.test.ts

@@ -235,15 +235,15 @@ describe('Delete Coalescence Bug', () => {
       expect(coalesced).toHaveLength(1);
       expect(coalesced[0].type).toBe('delete');
 
-      // The deletions array should already be efficient from remove() optimization
+      // FIXED in v0.5.4: coalesceTextOperations now sorts and optimizes deletions!
       // Each individual remove() creates 1 deletion (only deleting 1 char)
-      // When coalesceTextOperations merges the 7 ops, it combines the deletions arrays
+      // When coalesceTextOperations merges the 7 ops, it:
+      // 1. Combines the deletions arrays: [{id:Alice:6,len:1}, ..., {id:Alice:0,len:1}]
+      // 2. Sorts them: [{id:Alice:0,len:1}, ..., {id:Alice:6,len:1}]
+      // 3. Optimizes them: [{id:Alice:0,len:7}]
       const coalescedOp = (coalesced[0] as any).op;
-      expect(coalescedOp.deletions).toHaveLength(7);
-
-      // Note: These 7 deletions are NOT consecutive because we deleted backwards (6→0)
-      // So they cannot be merged. If we add optimizeDeletions() to coalesceTextOperations,
-      // it would merge them if they were consecutive.
+      expect(coalescedOp.deletions).toHaveLength(1);
+      expect(coalescedOp.deletions[0]).toEqual({ id: 'Alice:0', length: 7 });
     });
   });
 });