@vuer-ai/vuer-rtc-server 0.1.1

package/tests/README.md

@@ -0,0 +1,112 @@
+# Test Examples and Demo
+
+## 🎬 Working Demo
+
+Run the interactive demo:
+
+```bash
+npx tsx tests/demo.ts
+```
+
+This demonstrates:
+- Creating a scene with INSERT operations
+- Updating properties with concurrent updates
+- Conflict resolution (LWW and additive)
+- Moving nodes (reparenting)
+- Removing nodes (soft delete)
+
+## 📚 Test Data Examples
+
+### `test-data/scene-example.ts`
+Example scene graphs showing:
+- Flattened map format: `{ nodes: Record<key, Node>, rootKey }`
+- Dual identifiers (id + key)
+- Children-only references (instancing support)
+
+```typescript
+import { exampleScene, exampleSceneWithInstancing } from './test-data/scene-example.js';
+
+// Forest scene with trees and player
+console.log(exampleScene);
+
+// Scene demonstrating instancing (same node, multiple parents)
+console.log(exampleSceneWithInstancing);
+```
+
+### `test-data/operations-example.ts`
+Example operations showing:
+- INSERT, UPDATE, REMOVE, SET operations
+- Concurrent update scenarios
+- Move operations (reparenting)
+
+```typescript
+import {
+  exampleInsertOperation,
+  exampleUpdatePosition,
+  exampleConcurrentUpdates,
+} from './test-data/operations-example.js';
+```
+
+### `test-data/datatypes.ts`
+Complete dtype definitions with:
+- Merge functions for each operation
+- Examples for each data type
+- All supported operations
+
+```typescript
+import { NumberType, Vector3Type, ArrayType } from './test-data/datatypes.js';
+
+// Example: Number with ADD operation
+const summed = NumberType.add.merge([
+  { value: 10, lamportTime: 100 },
+  { value: 5, lamportTime: 101 },
+]);
+// Result: 15
+```
+
+## 🧪 Running Tests
+
+Vector clock tests (from Phase 1):
+```bash
+pnpm test
+```
+
+## 📖 Documentation
+
+See `/docs` for detailed documentation:
+- `SCENE_GRAPH.md` - Scene graph data structure
+- `TYPE_BEHAVIORS.md` - CRDT type behaviors reference
+
+## 🎯 Quick Start
+
+```typescript
+import { StateManager } from '../src/state/StateManager.js';
+
+// Create state manager
+const manager = new StateManager();
+
+// Apply an INSERT operation
+manager.applyOperation({
+  otype: 'insert',
+  id: 'op-001',
+  target: 'uuid-node-001',
+  sessionId: 'session-1',
+  clock: { 'session-1': 1 },
+  lamportTime: 1,
+  timestamp: Date.now(),
+  data: {
+    key: 'my-cube',
+    tag: 'Mesh',
+    name: 'My Cube',
+    properties: {
+      color: '#ff0000',
+      'transform.position': [0, 0, 0],
+    },
+  },
+});
+
+// Get current state
+const state = manager.getState();
+const node = state.getNode('my-cube');
+console.log(node?.name); // "My Cube"
+```

package/tests/demo.ts

@@ -0,0 +1,555 @@
+/**
+ * Demo - CRDT Scene Graph with Operation Batching
+ *
+ * This demonstrates the new design:
+ * 1. CRDTMessage wrapper (envelope) with metadata
+ * 2. Batch operations with explicit dtypes (number.set, vector3.add, etc.)
+ * 3. Operations use `key` (node key) instead of UUID
+ * 4. True batching - multiple ops on multiple nodes in one message
+ *
+ * Run with: npx tsx tests/demo.ts
+ */
+
+// Type definitions for the new design
+type VectorClock = Record<string, number>;
+
+interface CRDTMessage {
+  id: string;
+  sessionId: string;
+  clock: VectorClock;
+  lamportTime: number;
+  timestamp: number;
+  ops: Operation[];
+}
+
+interface BaseOp {
+  key: string;
+  otype: string;
+  path: string;
+}
+
+interface NodeInsertOp extends BaseOp {
+  key: string;
+  otype: 'node.insert';
+  path: string;
+  value: {
+    key: string;
+    tag: string;
+    name: string;
+    [key: string]: any;
+  };
+}
+
+interface NodeRemoveOp extends BaseOp {
+  key: string;
+  otype: 'node.remove';
+  path: string;
+}
+
+interface NumberSetOp extends BaseOp {
+  key: string;
+  otype: 'number.set';
+  path: string;
+  value: number;
+}
+
+interface NumberAddOp extends BaseOp {
+  key: string;
+  otype: 'number.add';
+  path: string;
+  value: number;
+}
+
+interface Vector3SetOp extends BaseOp {
+  key: string;
+  otype: 'vector3.set';
+  path: string;
+  value: [number, number, number];
+}
+
+interface Vector3AddOp extends BaseOp {
+  key: string;
+  otype: 'vector3.add';
+  path: string;
+  value: [number, number, number];
+}
+
+interface ColorSetOp extends BaseOp {
+  key: string;
+  otype: 'color.set';
+  path: string;
+  value: string;
+}
+
+interface ArraySetOp extends BaseOp {
+  key: string;
+  otype: 'array.set';
+  path: string;
+  value: any[];
+}
+
+interface ArrayPushOp extends BaseOp {
+  key: string;
+  otype: 'array.push';
+  path: string;
+  value: any;
+}
+
+interface ArrayRemoveOp extends BaseOp {
+  key: string;
+  otype: 'array.remove';
+  path: string;
+  value: any;
+}
+
+type Operation =
+  | NodeInsertOp
+  | NodeRemoveOp
+  | NumberSetOp
+  | NumberAddOp
+  | Vector3SetOp
+  | Vector3AddOp
+  | ColorSetOp
+  | ArraySetOp
+  | ArrayPushOp
+  | ArrayRemoveOp;
+
+console.log('🎬 CRDT Scene Graph Demo - Operation Batching\n');
+console.log('='.repeat(60));
+
+// ========================================
+// 1. CREATE SCENE
+// ========================================
+console.log('\n📦 Step 1: Create Scene\n');
+
+const msg1: CRDTMessage = {
+  // === CRDT Wrapper (envelope) ===
+  id: 'msg-001',
+  sessionId: 'session-server',
+  clock: { 'session-server': 1 },
+  lamportTime: 1,
+  timestamp: Date.now() / 1000,
+
+  // === Operations (batch) ===
+  ops: [
+    {
+      key: 'scene',
+      otype: 'node.insert',
+      path: 'scene',
+      value: {
+        key: 'uuid-scene-001',
+        tag: 'Scene',
+        name: 'Main Scene',
+        background: '#87CEEB',
+        'transform.position': [0, 0, 0],
+        'transform.rotation': [0, 0, 0, 1],
+        'transform.scale': [1, 1, 1],
+      },
+    },
+  ],
+};
+
+console.log('Message 1:');
+console.log('  Envelope: id=%s, session=%s, lamport=%d', msg1.id, msg1.sessionId, msg1.lamportTime);
+console.log('  Operations: %d ops', msg1.ops.length);
+const op1 = msg1.ops[0];
+if (op1.otype === 'node.insert') {
+  console.log('    ✓ %s: %s (tag=%s)', op1.otype, op1.key, op1.value.tag);
+}
+
+// ========================================
+// 2. BATCH INSERT - Multiple nodes in one message
+// ========================================
+console.log('\n📦 Step 2: Batch Insert - Multiple Nodes\n');
+
+const msg2: CRDTMessage = {
+  id: 'msg-002',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 1 },
+  lamportTime: 2,
+  timestamp: Date.now() / 1000,
+  ops: [
+    // Insert cube
+    {
+      key: 'cube-1',
+      otype: 'node.insert',
+      path: 'cube-1',
+      value: {
+        key: 'uuid-cube-001',
+        tag: 'Mesh',
+        name: 'Red Cube',
+        color: '#ff0000',
+        'transform.position': [2, 1, 0],
+        'transform.rotation': [0, 0, 0, 1],
+        'transform.scale': [1, 1, 1],
+      },
+    },
+    // Insert sphere
+    {
+      key: 'sphere-1',
+      otype: 'node.insert',
+      path: 'sphere-1',
+      value: {
+        key: 'uuid-sphere-001',
+        tag: 'Mesh',
+        name: 'Blue Sphere',
+        color: '#0000ff',
+        'transform.position': [-2, 1, 0],
+        'transform.rotation': [0, 0, 0, 1],
+        'transform.scale': [1, 1, 1],
+      },
+    },
+    // Add both to scene's children
+    {
+      key: 'scene',
+      otype: 'array.set',
+      path: 'children',
+      value: ['cube-1', 'sphere-1'],
+    },
+  ],
+};
+
+console.log('Message 2 (BATCH):');
+console.log('  Envelope: id=%s, session=%s, lamport=%d', msg2.id, msg2.sessionId, msg2.lamportTime);
+console.log('  Operations: %d ops (BATCHED!)', msg2.ops.length);
+msg2.ops.forEach((op) => {
+  if (op.otype === 'node.insert') {
+    console.log('    ✓ %s: %s (tag=%s)', op.otype, op.key, op.value.tag);
+  } else {
+    console.log('    ✓ %s: %s.%s', op.otype, op.key, op.path);
+  }
+});
+
+// ========================================
+// 3. ADDITIVE TRANSFORM (Relative Movement)
+// ========================================
+console.log('\n🎯 Step 3: Additive Transform (Drag)\n');
+
+const msg3: CRDTMessage = {
+  id: 'msg-003',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 2 },
+  lamportTime: 3,
+  timestamp: Date.now() / 1000,
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'vector3.add', // Additive!
+      path: 'transform.position',
+      value: [5, 0, 0], // Drag by +5 on X
+    },
+  ],
+};
+
+console.log('Message 3 (Additive):');
+const op3 = msg3.ops[0] as Vector3AddOp;
+console.log('  ✓ %s: %s.%s += %s', op3.otype, op3.key, op3.path, JSON.stringify(op3.value));
+console.log('  → Relative movement (position.x += 5)');
+
+// ========================================
+// 4. ABSOLUTE TRANSFORM (Set Position)
+// ========================================
+console.log('\n🎯 Step 4: Absolute Transform (Set)\n');
+
+const msg4: CRDTMessage = {
+  id: 'msg-004',
+  sessionId: 'session-bob',
+  clock: { 'session-bob': 1 },
+  lamportTime: 4,
+  timestamp: Date.now() / 1000,
+  ops: [
+    {
+      key: 'sphere-1',
+      otype: 'vector3.set', // Absolute!
+      path: 'transform.position',
+      value: [0, 5, 0], // Set to the exact position
+    },
+  ],
+};
+
+console.log('Message 4 (Absolute):');
+const op4 = msg4.ops[0] as Vector3SetOp;
+console.log('  ✓ %s: %s.%s = %s', op4.otype, op4.key, op4.path, JSON.stringify(op4.value));
+console.log('  → Absolute position (position = [0, 5, 0])');
+
+// ========================================
+// 5. BATCH UPDATE - Multiple properties on same node
+// ========================================
+console.log('\n🔄 Step 5: Batch Update - Same Node\n');
+
+const msg5: CRDTMessage = {
+  id: 'msg-005',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 3 },
+  lamportTime: 5,
+  timestamp: Date.now() / 1000,
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'color.set',
+      path: 'color',
+      value: '#00ff00',
+    },
+    {
+      key: 'cube-1',
+      otype: 'number.set',
+      path: 'opacity',
+      value: 0.5,
+    },
+    {
+      key: 'cube-1',
+      otype: 'vector3.add',
+      path: 'transform.position',
+      value: [0, 2, 0], // Move up by 2
+    },
+  ],
+};
+
+console.log('Message 5 (Batch - Same Node):');
+console.log('  Envelope: lamport=%d', msg5.lamportTime);
+console.log('  Operations on "%s": %d ops', msg5.ops[0].key, msg5.ops.length);
+msg5.ops.forEach((op) => {
+  if ('value' in op) {
+    console.log('    ✓ %s: %s = %s', op.otype, op.path, JSON.stringify(op.value));
+  }
+});
+
+// ========================================
+// 6. COMPOUND UPDATE - Multiple nodes
+// ========================================
+console.log('\n🔀 Step 6: Compound Update - Multiple Nodes\n');
+
+const msg6: CRDTMessage = {
+  id: 'msg-006',
+  sessionId: 'session-bob',
+  clock: { 'session-bob': 2 },
+  lamportTime: 6,
+  timestamp: Date.now() / 1000,
+  ops: [
+    // Update cube
+    {
+      key: 'cube-1',
+      otype: 'number.set',
+      path: 'metalness',
+      value: 0.8,
+    },
+    // Update sphere
+    {
+      key: 'sphere-1',
+      otype: 'color.set',
+      path: 'color',
+      value: '#ffff00',
+    },
+  ],
+};
+
+console.log('Message 6 (Compound - Different Nodes):');
+console.log('  Envelope: lamport=%d', msg6.lamportTime);
+console.log('  Operations: %d nodes updated', new Set(msg6.ops.map((op) => op.key)).size);
+msg6.ops.forEach((op) => {
+  if ('value' in op) {
+    console.log('    ✓ %s: %s.%s = %s', op.otype, op.key, op.path, JSON.stringify(op.value));
+  }
+});
+
+// ========================================
+// 7. MULTI-SELECT DRAG - Additive on multiple nodes
+// ========================================
+console.log('\n🎯 Step 7: Multi-Select Drag\n');
+
+const msg7: CRDTMessage = {
+  id: 'msg-007',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 4 },
+  lamportTime: 7,
+  timestamp: Date.now() / 1000,
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'vector3.add',
+      path: 'transform.position',
+      value: [3, 0, 0],
+    },
+    {
+      key: 'sphere-1',
+      otype: 'vector3.add',
+      path: 'transform.position',
+      value: [3, 0, 0],
+    },
+  ],
+};
+
+console.log('Message 7 (Multi-Select Drag):');
+console.log('  Selected nodes: %d', msg7.ops.length);
+msg7.ops.forEach((op) => {
+  if ('value' in op) {
+    console.log('    ✓ %s += %s', op.key, JSON.stringify(op.value));
+  }
+});
+console.log('  → All selected nodes dragged by [3, 0, 0]');
+
+// ========================================
+// 8. ADDITIVE SCORE - Concurrent updates
+// ========================================
+console.log('\n➕ Step 8: Additive Score (Concurrent)\n');
+
+const msg8a: CRDTMessage = {
+  id: 'msg-008a',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 5 },
+  lamportTime: 8,
+  timestamp: Date.now() / 1000,
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'number.add',
+      path: 'score',
+      value: 10,
+    },
+  ],
+};
+
+const msg8b: CRDTMessage = {
+  id: 'msg-008b',
+  sessionId: 'session-bob',
+  clock: { 'session-bob': 3 },
+  lamportTime: 9,
+  timestamp: Date.now() / 1000,
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'number.add',
+      path: 'score',
+      value: 5,
+    },
+  ],
+};
+
+console.log('Message 8a (Alice):');
+console.log('  ✓ %s: cube-1.score += 10', msg8a.ops[0].otype);
+console.log('Message 8b (Bob - concurrent):');
+console.log('  ✓ %s: cube-1.score += 5', msg8b.ops[0].otype);
+console.log('  → Final score: 15 (both additions applied!)');
+
+// ========================================
+// 9. REPARENT - Compound operation
+// ========================================
+console.log('\n🔄 Step 9: Reparent Node\n');
+
+const msg9: CRDTMessage = {
+  id: 'msg-009',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 6 },
+  lamportTime: 10,
+  timestamp: Date.now() / 1000,
+  ops: [
+    // Create new parent
+    {
+      key: 'group-1',
+      otype: 'node.insert',
+      path: 'group-1',
+      value: {
+        key: 'uuid-group-001',
+        tag: 'Group',
+        name: 'My Group',
+        'transform.position': [0, 0, 0],
+        'transform.rotation': [0, 0, 0, 1],
+        'transform.scale': [1, 1, 1],
+      },
+    },
+    // Remove from old parent
+    {
+      key: 'scene',
+      otype: 'array.remove',
+      path: 'children',
+      value: 'cube-1',
+    },
+    // Add to new parent
+    {
+      key: 'group-1',
+      otype: 'array.push',
+      path: 'children',
+      value: 'cube-1',
+    },
+  ],
+};
+
+console.log('Message 9 (Reparent - Compound):');
+console.log('  Operations: %d ops (atomic)', msg9.ops.length);
+msg9.ops.forEach((op, i) => {
+  if (op.otype === 'node.insert') {
+    console.log('    %d. Create group: %s', i + 1, op.key);
+  } else if (op.otype === 'array.remove') {
+    console.log('    %d. Remove from %s.children: "%s"', i + 1, op.key, op.value);
+  } else if (op.otype === 'array.push') {
+    console.log('    %d. Add to %s.children: "%s"', i + 1, op.key, op.value);
+  }
+});
+console.log('  → cube-1 moved from scene to group-1');
+
+// ========================================
+// 10. DELETE - Remove node
+// ========================================
+console.log('\n🗑️  Step 10: Delete Node\n');
+
+const msg10: CRDTMessage = {
+  id: 'msg-010',
+  sessionId: 'session-bob',
+  clock: { 'session-bob': 4 },
+  lamportTime: 11,
+  timestamp: Date.now() / 1000,
+  ops: [
+    // Remove from parent
+    {
+      key: 'scene',
+      otype: 'array.remove',
+      path: 'children',
+      value: 'sphere-1',
+    },
+    // Delete node (tombstone)
+    {
+      key: 'sphere-1',
+      otype: 'node.remove',
+      path: 'sphere-1',
+    },
+  ],
+};
+
+console.log('Message 10 (Delete):');
+msg10.ops.forEach((op, i) => {
+  if (op.otype === 'array.remove') {
+    console.log('  %d. Remove from parent: %s', i + 1, op.value);
+  } else if (op.otype === 'node.remove') {
+    console.log('  %d. Delete node: %s (tombstone)', i + 1, op.key);
+  }
+});
+
+// ========================================
+// SUMMARY
+// ========================================
+console.log('\n📊 Summary\n');
+console.log('='.repeat(60));
+console.log('\nTotal messages: 10');
+console.log('Total operations: %d', [msg1, msg2, msg3, msg4, msg5, msg6, msg7, msg8a, msg8b, msg9, msg10].reduce((sum, msg) => sum + msg.ops.length, 0));
+
+console.log('\n✨ Features Demonstrated:\n');
+console.log('  ✅ CRDT Wrapper (envelope) with metadata');
+console.log('  ✅ Operation batching (multiple ops per message)');
+console.log('  ✅ Compound updates (multiple nodes per message)');
+console.log('  ✅ Explicit dtypes: number.set, vector3.add, color.set, etc.');
+console.log('  ✅ Node keys (not UUIDs) for operations');
+console.log('  ✅ Additive transforms: vector3.add (position += delta)');
+console.log('  ✅ Absolute transforms: vector3.set (position = value)');
+console.log('  ✅ Multi-select drag (batch additive on multiple nodes)');
+console.log('  ✅ Additive counters: number.add (concurrent updates sum)');
+console.log('  ✅ Reparenting (compound: remove + insert + array ops)');
+console.log('  ✅ Node deletion (remove from parent + tombstone)');
+
+console.log('\n' + '='.repeat(60));
+console.log('\n💡 Key Design Points:\n');
+console.log('  • CRDTMessage = envelope (metadata) + ops (batch)');
+console.log('  • Operations use `key` (human-friendly) not UUID');
+console.log('  • otype is explicit: "vector3.add" vs "vector3.set"');
+console.log('  • True batching: one message, many nodes, atomic');
+console.log('  • No nested "properties" - clean operation structure');
+console.log('\n' + '='.repeat(60));