@vuer-ai/vuer-rtc 0.4.2 → 0.5.0

package/test-coalescence.ts

@@ -0,0 +1,201 @@
+import { coalesceTextOperations } from './src/client/coalesceTextOperations.js';
+import type { InsertOp } from './src/crdt/Rope.js';
+import type { TextOperation } from './src/client/textTypes.js';
+
+// Test: Typing "Hello" quickly should create ONE operation
+function testHelloCoalescence() {
+  console.log('\n=== Test: Typing "Hello" ===\n');
+
+  const ops: TextOperation[] = [];
+
+  // Simulate typing "Hello" - each character creates a sequential operation
+  // Character 'H' at position 0
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:1',
+      content: 'H',
+      parentId: null,
+      seq: 1,
+      ts: 1000.0,
+    }
+  });
+
+  // Character 'e' at position 1 (parent is 'H')
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:2',
+      content: 'e',
+      parentId: 'alice:1',
+      seq: 2,
+      ts: 1000.1, // 100ms later
+    }
+  });
+
+  // Character 'l' at position 2 (parent is 'e')
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:3',
+      content: 'l',
+      parentId: 'alice:2',
+      seq: 3,
+      ts: 1000.2, // 200ms later
+    }
+  });
+
+  // Character 'l' at position 3 (parent is first 'l')
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:4',
+      content: 'l',
+      parentId: 'alice:3',
+      seq: 4,
+      ts: 1000.25, // 250ms later
+    }
+  });
+
+  // Character 'o' at position 4 (parent is second 'l')
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:5',
+      content: 'o',
+      parentId: 'alice:4',
+      seq: 5,
+      ts: 1000.29, // 290ms later
+    }
+  });
+
+  console.log('Input operations:');
+  ops.forEach((op, i) => {
+    const insertOp = op.op as InsertOp;
+    console.log(`  ${i + 1}. id=${insertOp.id}, content="${insertOp.content}", parentId=${insertOp.parentId}, ts=${insertOp.ts}`);
+  });
+
+  // Coalesce with 300ms threshold
+  const coalesced = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+  console.log('\nCoalesced operations:');
+  coalesced.forEach((op, i) => {
+    const insertOp = op.op as InsertOp;
+    console.log(`  ${i + 1}. id=${insertOp.id}, content="${insertOp.content}", parentId=${insertOp.parentId}, _lastCharId=${(insertOp as any)._lastCharId}`);
+  });
+
+  // Verify results
+  const success = coalesced.length === 1 && coalesced[0].op.content === 'Hello';
+  console.log('\n' + (success ? '✅ SUCCESS' : '❌ FAILURE') + ': Expected 1 operation with content="Hello"');
+  console.log(`   Got ${coalesced.length} operation(s) with content="${coalesced[0].op.content}"`);
+
+  if (success && (coalesced[0].op as any)._lastCharId) {
+    console.log(`   _lastCharId correctly set to: ${(coalesced[0].op as any)._lastCharId}`);
+  }
+
+  return success;
+}
+
+// Test: Typing "World" with longer delay should NOT coalesce
+function testWorldNoCoalescence() {
+  console.log('\n=== Test: Typing "World" with delays > 300ms ===\n');
+
+  const ops: TextOperation[] = [];
+
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:10',
+      content: 'W',
+      parentId: null,
+      seq: 10,
+      ts: 2000.0,
+    }
+  });
+
+  // 400ms delay - should NOT coalesce
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:11',
+      content: 'o',
+      parentId: 'alice:10',
+      seq: 11,
+      ts: 2000.4,
+    }
+  });
+
+  const coalesced = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+  console.log('Input operations: 2 (400ms apart)');
+  console.log('Coalesced operations:', coalesced.length);
+
+  const success = coalesced.length === 2;
+  console.log('\n' + (success ? '✅ SUCCESS' : '❌ FAILURE') + ': Expected 2 separate operations (delay too long)');
+
+  return success;
+}
+
+// Test: Broken YATA chain should NOT coalesce
+function testBrokenChain() {
+  console.log('\n=== Test: Broken YATA chain (non-sequential parents) ===\n');
+
+  const ops: TextOperation[] = [];
+
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:20',
+      content: 'A',
+      parentId: null,
+      seq: 20,
+      ts: 3000.0,
+    }
+  });
+
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:21',
+      content: 'B',
+      parentId: 'alice:20',
+      seq: 21,
+      ts: 3000.1,
+    }
+  });
+
+  // This operation's parent is NOT alice:21, breaking the chain
+  ops.push({
+    type: 'insert',
+    op: {
+      id: 'alice:22',
+      content: 'C',
+      parentId: 'alice:15', // Different parent!
+      seq: 22,
+      ts: 3000.2,
+    }
+  });
+
+  const coalesced = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+  console.log('Input operations: 3 (third has wrong parent)');
+  console.log('Coalesced operations:', coalesced.length);
+
+  const success = coalesced.length === 2; // First two should merge, third separate
+  console.log('\n' + (success ? '✅ SUCCESS' : '❌ FAILURE') + ': Expected 2 operations (AB merged, C separate)');
+
+  return success;
+}
+
+// Run all tests
+const results = [
+  testHelloCoalescence(),
+  testWorldNoCoalescence(),
+  testBrokenChain(),
+];
+
+console.log('\n=== SUMMARY ===');
+console.log(`Passed: ${results.filter(r => r).length}/${results.length}`);
+console.log(results.every(r => r) ? '✅ ALL TESTS PASSED' : '❌ SOME TESTS FAILED');
+
+process.exit(results.every(r => r) ? 0 : 1);

package/tests/client/actions.test.ts

@@ -795,4 +795,160 @@ describe('Client Actions', () => {
       expect(getText(alice.graph.nodes['doc']?.content)).toBe('Hello');
     });
   });
+
+  describe('coalescence metadata preservation', () => {
+    it('should preserve CRDT metadata in journal after commit', () => {
+      // Create a text document
+      let s = createInitialState('test-session');
+      s = onEdit(s, {
+        key: '',
+        otype: 'node.insert',
+        path: 'children',
+        value: { key: 'doc', tag: 'Text' },
+      });
+      const { state: s1 } = commitEdits(s);
+      s = s1;
+
+      // Initialize text
+      s = onEdit(s, {
+        key: 'doc',
+        otype: 'text.init',
+        path: 'content',
+        value: '',
+      } as any);
+      const { state: s2 } = commitEdits(s);
+      s = s2;
+
+      // Type multiple characters rapidly (simulating coalescence scenario)
+      s = onEdit(s, {
+        key: 'doc',
+        otype: 'text.insert',
+        path: 'content',
+        position: 0,
+        value: 'a',
+      } as any);
+
+      s = onEdit(s, {
+        key: 'doc',
+        otype: 'text.insert',
+        path: 'content',
+        position: 1,
+        value: 'b',
+      } as any);
+
+      s = onEdit(s, {
+        key: 'doc',
+        otype: 'text.insert',
+        path: 'content',
+        position: 2,
+        value: 'c',
+      } as any);
+
+      // Commit - this triggers coalescence
+      const { state: s3, msg } = commitEdits(s);
+      s = s3;
+
+      // Verify message was created
+      expect(msg).not.toBeNull();
+      expect(msg!.ops).toHaveLength(3); // Each op should be separate (not coalesced due to CRDT metadata)
+
+      // Verify all operations in the message have CRDT metadata
+      for (const op of msg!.ops) {
+        if (op.otype === 'text.insert') {
+          expect((op as any).id).toBeDefined();
+          expect(typeof (op as any).id).toBe('string');
+          expect((op as any).id).toMatch(/:/); // String format: "agent:seq"
+          expect((op as any).content).toBeDefined();
+          expect((op as any).seq).toBeDefined();
+          expect((op as any).ts).toBeDefined();
+          // parentId can be null for first operation
+          expect((op as any).parentId !== undefined).toBe(true);
+        }
+      }
+
+      // Verify journal has the operations with metadata
+      const journalEntry = s.journal[s.journal.length - 1];
+      expect(journalEntry.msg.ops).toHaveLength(3);
+
+      for (const op of journalEntry.msg.ops) {
+        if (op.otype === 'text.insert') {
+          expect((op as any).id).toBeDefined();
+          expect((op as any).content).toBeDefined();
+          expect((op as any).seq).toBeDefined();
+        }
+      }
+    });
+
+    it('should preserve metadata when receiving own message back from server', () => {
+      // This tests the full round-trip: send → server ACK → journal update
+      let s = createInitialState('test-session');
+
+      // Create text document
+      s = onEdit(s, {
+        key: '',
+        otype: 'node.insert',
+        path: 'children',
+        value: { key: 'doc', tag: 'Text' },
+      });
+      const { state: s1 } = commitEdits(s);
+      s = s1;
+
+      s = onEdit(s, {
+        key: 'doc',
+        otype: 'text.init',
+        path: 'content',
+        value: '',
+      } as any);
+      const { state: s2 } = commitEdits(s);
+      s = s2;
+
+      // Type two characters
+      s = onEdit(s, {
+        key: 'doc',
+        otype: 'text.insert',
+        path: 'content',
+        position: 0,
+        value: 'x',
+      } as any);
+
+      s = onEdit(s, {
+        key: 'doc',
+        otype: 'text.insert',
+        path: 'content',
+        position: 1,
+        value: 'y',
+      } as any);
+
+      // Commit
+      const { state: s3, msg } = commitEdits(s);
+      s = s3;
+
+      // Verify the message has metadata before it's sent
+      expect(msg).not.toBeNull();
+      const firstOp = msg!.ops[0];
+      if (firstOp.otype === 'text.insert') {
+        expect((firstOp as any).id).toBeDefined();
+      }
+
+      // Simulate server ACK by receiving the same message back
+      // (in real system, server would broadcast this to all clients including sender)
+      const journalBefore = s.journal.length;
+      s = onRemoteMessage(s, msg!);
+
+      // Journal shouldn't grow (duplicate message)
+      expect(s.journal.length).toBe(journalBefore);
+
+      // But verify the existing journal entry still has metadata
+      const journalEntry = s.journal.find(e => e.msg.id === msg!.id);
+      expect(journalEntry).toBeDefined();
+
+      for (const op of journalEntry!.msg.ops) {
+        if (op.otype === 'text.insert') {
+          expect((op as any).id).toBeDefined();
+          expect((op as any).content).toBeDefined();
+          expect((op as any).seq).toBeDefined();
+        }
+      }
+    });
+  });
 });

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

@@ -0,0 +1,327 @@
+/**
+ * Tests for coalesceTextOperations - verifying the bug fix for multi-character coalescence
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { coalesceTextOperations } from '../../src/client/coalesceTextOperations.js';
+import type { TextOperation } from '../../src/client/textTypes.js';
+import type { InsertOp } from '../../src/crdt/Rope.js';
+
+describe('coalesceTextOperations', () => {
+  describe('multi-character coalescence (bug fix verification)', () => {
+    it('should coalesce ALL consecutive characters within threshold, not just pairs', () => {
+      // Simulate typing "Hello" quickly (within 300ms)
+      const ops: TextOperation[] = [
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:1',
+            content: 'H',
+            parentId: null,
+            seq: 1,
+            ts: 1000.0,
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:2',
+            content: 'e',
+            parentId: 'alice:1', // Forms chain with previous
+            seq: 2,
+            ts: 1000.05, // 50ms later
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:3',
+            content: 'l',
+            parentId: 'alice:2', // Forms chain with previous
+            seq: 3,
+            ts: 1000.1, // 100ms from start
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:4',
+            content: 'l',
+            parentId: 'alice:3', // Forms chain with previous
+            seq: 4,
+            ts: 1000.15, // 150ms from start
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:5',
+            content: 'o',
+            parentId: 'alice:4', // Forms chain with previous
+            seq: 5,
+            ts: 1000.2, // 200ms from start
+          },
+        },
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+      // Should coalesce into ONE operation with content="Hello"
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe('insert');
+      expect((result[0] as any).op.content).toBe('Hello');
+      expect((result[0] as any).op.id).toBe('alice:1'); // Keep first ID
+      expect((result[0] as any).op.parentId).toBe(null); // Keep first parentId
+    });
+
+    it('should respect time threshold and create separate operations for slow typing', () => {
+      // Simulate typing "He" quickly, then pause, then "llo" quickly
+      const ops: TextOperation[] = [
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:1',
+            content: 'H',
+            parentId: null,
+            seq: 1,
+            ts: 1000.0,
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:2',
+            content: 'e',
+            parentId: 'alice:1',
+            seq: 2,
+            ts: 1000.05, // 50ms later - within threshold
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:3',
+            content: 'l',
+            parentId: 'alice:2',
+            seq: 3,
+            ts: 1000.5, // 450ms later - EXCEEDS threshold
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:4',
+            content: 'l',
+            parentId: 'alice:3',
+            seq: 4,
+            ts: 1000.55, // 50ms after 'l'
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:5',
+            content: 'o',
+            parentId: 'alice:4',
+            seq: 5,
+            ts: 1000.6, // 50ms after second 'l'
+          },
+        },
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+      // Should create TWO operations: "He" and "llo"
+      expect(result).toHaveLength(2);
+      expect((result[0] as any).op.content).toBe('He');
+      expect((result[0] as any).op.id).toBe('alice:1');
+      expect((result[1] as any).op.content).toBe('llo');
+      expect((result[1] as any).op.id).toBe('alice:3');
+    });
+
+    it('should handle single character operations (no coalescence)', () => {
+      const ops: TextOperation[] = [
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:1',
+            content: 'H',
+            parentId: null,
+            seq: 1,
+            ts: 1000.0,
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:2',
+            content: 'e',
+            parentId: 'alice:1',
+            seq: 2,
+            ts: 1001.5, // 1500ms later - exceeds threshold
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:3',
+            content: 'l',
+            parentId: 'alice:2',
+            seq: 3,
+            ts: 1003.0, // 1500ms later - exceeds threshold
+          },
+        },
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+      // Should create THREE separate operations (no coalescence)
+      expect(result).toHaveLength(3);
+      expect((result[0] as any).op.content).toBe('H');
+      expect((result[1] as any).op.content).toBe('e');
+      expect((result[2] as any).op.content).toBe('l');
+    });
+
+    it('should handle non-sequential IDs (different agents)', () => {
+      const ops: TextOperation[] = [
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:1',
+            content: 'H',
+            parentId: null,
+            seq: 1,
+            ts: 1000.0,
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'bob:1', // Different agent
+            content: 'e',
+            parentId: 'alice:1',
+            seq: 2,
+            ts: 1000.05,
+          },
+        },
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+      // Should NOT coalesce (different agents)
+      expect(result).toHaveLength(2);
+      expect((result[0] as any).op.content).toBe('H');
+      expect((result[1] as any).op.content).toBe('e');
+    });
+
+    it('should handle delete operations (flush pending inserts)', () => {
+      const ops: TextOperation[] = [
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:1',
+            content: 'H',
+            parentId: null,
+            seq: 1,
+            ts: 1000.0,
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:2',
+            content: 'e',
+            parentId: 'alice:1',
+            seq: 2,
+            ts: 1000.05,
+          },
+        },
+        {
+          type: 'delete',
+          op: {
+            id: 'alice:3',
+            length: 1,
+            seq: 3,
+            ts: 1000.1,
+          },
+        } as any,
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+      // Should flush "He" and then add the delete
+      expect(result).toHaveLength(2);
+      expect(result[0].type).toBe('insert');
+      expect((result[0] as any).op.content).toBe('He');
+      expect(result[1].type).toBe('delete');
+    });
+
+    it('should verify _lastCharId metadata is tracked correctly', () => {
+      const ops: TextOperation[] = [
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:1',
+            content: 'a',
+            parentId: null,
+            seq: 1,
+            ts: 1000.0,
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:2',
+            content: 'b',
+            parentId: 'alice:1',
+            seq: 2,
+            ts: 1000.05,
+          },
+        },
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:3',
+            content: 'c',
+            parentId: 'alice:2', // This should match _lastCharId after first merge
+            seq: 3,
+            ts: 1000.1,
+          },
+        },
+      ];
+
+      const result = coalesceTextOperations(ops, { thresholdMs: 300 });
+
+      // Should coalesce all three
+      expect(result).toHaveLength(1);
+      expect((result[0] as any).op.content).toBe('abc');
+      expect((result[0] as any).op._lastCharId).toBe('alice:3');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty operations array', () => {
+      const result = coalesceTextOperations([]);
+      expect(result).toHaveLength(0);
+    });
+
+    it('should handle single operation', () => {
+      const ops: TextOperation[] = [
+        {
+          type: 'insert',
+          op: {
+            id: 'alice:1',
+            content: 'H',
+            parentId: null,
+            seq: 1,
+            ts: 1000.0,
+          },
+        },
+      ];
+
+      const result = coalesceTextOperations(ops);
+      expect(result).toHaveLength(1);
+      expect((result[0] as any).op.content).toBe('H');
+    });
+  });
+});