@vuer-ai/vuer-rtc 0.0.1

package/docs/TYPE_BEHAVIORS.md

@@ -0,0 +1,348 @@
+# CRDT Type Behaviors: Comprehensive Reference
+
+Different data types have different natural merge semantics. This document defines the behavior of each type when concurrent operations occur.
+
+## Operation Type Format
+
+Operations use explicit `otype` that encodes both dtype and operation:
+- `number.set` / `number.add` / `number.multiply` / `number.min` / `number.max`
+- `vector3.set` / `vector3.add` / `vector3.multiply`
+- `color.set` / `color.blend`
+- `array.set` / `array.push` / `array.remove` / `array.union`
+- `node.insert` / `node.remove`
+
+---
+
+## Summary Table
+
+| otype | Merge Behavior | Use Case |
+|-------|---------------|----------|
+| `number.set` | LWW | Properties, measurements |
+| `number.add` | Sum | Counters, scores, deltas |
+| `number.multiply` | Product | Scale factors |
+| `number.min` | Minimum | Quality settings |
+| `number.max` | Maximum | High scores |
+| `string.set` | LWW | Names, labels |
+| `string.concat` | Concatenate | Logs (ordered by lamport) |
+| `boolean.set` | LWW | Flags, toggles |
+| `boolean.or` | OR | Feature flags (enable wins) |
+| `boolean.and` | AND | Permissions (disable wins) |
+| `vector3.set` | LWW | Absolute position/scale |
+| `vector3.add` | Component sum | Delta movement |
+| `vector3.multiply` | Component product | Scale gestures |
+| `quaternion.set` | LWW | Rotation |
+| `color.set` | LWW | Material color |
+| `array.set` | LWW | Replace array |
+| `array.push` | Append | Add item |
+| `array.remove` | Remove | Remove item |
+| `array.union` | Union | Merge sets |
+| `object.set` | LWW | Replace object |
+| `object.merge` | Deep merge | Merge properties |
+| `node.insert` | Idempotent | Create node |
+| `node.remove` | Tombstone | Delete node |
+
+## Table of Contents
+
+- [Primitive Types](#primitive-types)
+  - [Number](#number) - `set`, `add`, `multiply`, `min`, `max`
+  - [String](#string) - `set`, `concat`
+  - [Boolean](#boolean) - `set`, `or`, `and`
+- [Collection Types](#collection-types)
+  - [Array](#array) - `set`, `push`, `remove`, `union`
+  - [Object](#object) - `set`, `merge`
+- [Compound Types (3D Graphics)](#compound-types-3d-graphics)
+  - [Vector3](#vector3-position-scale) - `set`, `add`, `multiply`
+  - [Quaternion](#quaternion-rotation) - `set`, `multiply`
+  - [Color](#color) - `set`, `blend`
+- [Scene Graph Operations](#scene-graph-operations)
+  - [node.insert](#nodeinsert)
+  - [node.remove](#noderemove)
+- [Implementation Strategy](#implementation-strategy)
+
+---
+
+## Primitive Types
+
+### Number
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `number.set` | LWW | `{ otype: 'number.set', path: 'opacity', value: 0.5 }` |
+| `number.add` | Sum | `{ otype: 'number.add', path: 'score', value: 10 }` |
+| `number.multiply` | Product | `{ otype: 'number.multiply', path: 'scale', value: 2 }` |
+| `number.min` | Minimum | `{ otype: 'number.min', path: 'minScore', value: 100 }` |
+| `number.max` | Maximum | `{ otype: 'number.max', path: 'maxScore', value: 100 }` |
+
+**Examples:**
+```typescript
+// Additive counter (concurrent updates sum)
+{ key: 'cube-1', otype: 'number.add', path: 'score', value: 10 }
+// Alice: score += 10, Bob: score += 5 → Result: 15 ✅
+
+// LWW property (last write wins)
+{ key: 'cube-1', otype: 'number.set', path: 'opacity', value: 0.5 }
+// Alice: opacity = 0.3 (lamport: 100), Bob: opacity = 0.8 (lamport: 101)
+// Result: 0.8 ✅ (Bob wins)
+```
+
+---
+
+### String
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `string.set` | LWW | `{ otype: 'string.set', path: 'name', value: 'Cube' }` |
+| `string.concat` | Concatenate | `{ otype: 'string.concat', path: 'log', value: 'entry' }` |
+
+**Examples:**
+```typescript
+// LWW name
+{ key: 'cube-1', otype: 'string.set', path: 'name', value: 'Red Cube' }
+// Alice: "Red Cube" (lamport: 100), Bob: "Blue Sphere" (lamport: 101)
+// Result: "Blue Sphere" ✅
+```
+
+---
+
+### Boolean
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `boolean.set` | LWW | `{ otype: 'boolean.set', path: 'visible', value: true }` |
+| `boolean.or` | OR (enable wins) | `{ otype: 'boolean.or', path: 'enabled', value: true }` |
+| `boolean.and` | AND (disable wins) | `{ otype: 'boolean.and', path: 'allowed', value: false }` |
+
+**Examples:**
+```typescript
+// LWW visibility
+{ key: 'cube-1', otype: 'boolean.set', path: 'visible', value: false }
+
+// OR bias (enable wins regardless of lamport)
+{ key: 'cube-1', otype: 'boolean.or', path: 'enabled', value: true }
+// Alice: true, Bob: false → Result: true ✅
+```
+
+---
+
+## Collection Types
+
+### Array
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `array.set` | LWW (replace) | `{ otype: 'array.set', path: 'children', value: ['a', 'b'] }` |
+| `array.push` | Append | `{ otype: 'array.push', path: 'children', value: 'c' }` |
+| `array.remove` | Remove item | `{ otype: 'array.remove', path: 'children', value: 'a' }` |
+| `array.union` | Union | `{ otype: 'array.union', path: 'tags', value: ['new'] }` |
+
+**Examples:**
+```typescript
+// Replace entire array
+{ key: 'scene', otype: 'array.set', path: 'children', value: ['cube-1', 'sphere-1'] }
+
+// Append to array
+{ key: 'scene', otype: 'array.push', path: 'children', value: 'light-1' }
+
+// Remove from array
+{ key: 'scene', otype: 'array.remove', path: 'children', value: 'cube-1' }
+```
+
+---
+
+### Object
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `object.set` | LWW (replace) | `{ otype: 'object.set', path: 'metadata', value: {...} }` |
+| `object.merge` | Deep merge | `{ otype: 'object.merge', path: 'metadata', value: {...} }` |
+
+---
+
+## Compound Types (3D Graphics)
+
+### Vector3 (Position, Scale)
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `vector3.set` | LWW | `{ otype: 'vector3.set', path: 'transform.position', value: [0,5,0] }` |
+| `vector3.add` | Component sum | `{ otype: 'vector3.add', path: 'transform.position', value: [5,0,0] }` |
+| `vector3.multiply` | Component product | `{ otype: 'vector3.multiply', path: 'transform.scale', value: [2,2,2] }` |
+
+**Examples:**
+```typescript
+// Absolute position (inspector input)
+{ key: 'cube-1', otype: 'vector3.set', path: 'transform.position', value: [10, 5, 0] }
+// Alice: [10, 5, 0] (lamport: 100), Bob: [0, 10, 0] (lamport: 101)
+// Result: [0, 10, 0] ✅ (Bob wins)
+
+// Additive movement (drag)
+{ key: 'cube-1', otype: 'vector3.add', path: 'transform.position', value: [5, 0, 0] }
+// Alice: += [5, 0, 0], Bob: += [0, 3, 0]
+// Result: += [5, 3, 0] ✅ (both movements apply)
+```
+
+---
+
+### Quaternion (Rotation)
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `quaternion.set` | LWW | `{ otype: 'quaternion.set', path: 'transform.rotation', value: [0,0,0,1] }` |
+| `quaternion.multiply` | Composition | `{ otype: 'quaternion.multiply', path: 'transform.rotation', value: [...] }` |
+
+**Note:** Use `quaternion.set` (LWW) for predictable UX. Quaternion composition is unpredictable for users.
+
+---
+
+### Color
+
+| otype | Merge | Example |
+|-------|-------|---------|
+| `color.set` | LWW | `{ otype: 'color.set', path: 'color', value: '#ff0000' }` |
+| `color.blend` | Average | `{ otype: 'color.blend', path: 'color', value: '#00ff00' }` |
+
+---
+
+## Scene Graph Operations
+
+### node.insert
+
+Create a new node in the scene graph.
+
+```typescript
+{
+  key: 'cube-1',
+  otype: 'node.insert',
+  path: 'cube-1',
+  value: {
+    id: 'uuid-cube-001',
+    tag: 'Mesh',
+    name: 'Red Cube',
+    color: '#ff0000',
+    'transform.position': [0, 0, 0],
+    'transform.rotation': [0, 0, 0, 1],
+    'transform.scale': [1, 1, 1]
+  }
+}
+```
+
+**Behavior:**
+- Adds node to `nodes` map: `nodes[key] = node`
+- If key exists → idempotent (no-op)
+
+---
+
+### node.remove
+
+Delete node (tombstone).
+
+```typescript
+{
+  key: 'cube-1',
+  otype: 'node.remove',
+  path: 'cube-1'
+}
+```
+
+**Behavior:**
+1. Set `node.deletedAt = timestamp` (tombstone)
+2. Remove key from all parents' `children` arrays
+
+---
+
+## Implementation Strategy
+
+### Operation Registry Pattern
+
+```typescript
+// operations/registry.ts
+export { applyNumberSet } from './number.js';
+export { applyNumberAdd } from './number.js';
+export { applyVector3Set } from './vector3.js';
+export { applyVector3Add } from './vector3.js';
+export { applyArraySet } from './array.js';
+export { applyArrayPush } from './array.js';
+export { applyArrayRemove } from './array.js';
+export { applyNodeInsert } from './node.js';
+export { applyNodeRemove } from './node.js';
+// ...
+
+// index.ts
+import * as registry from './operations/registry.js';
+
+export type NumberSetOp = { otype: 'number.set'; ... };
+export type NumberAddOp = { otype: 'number.add'; ... };
+// ...
+```
+
+### Apply Function Signature
+
+```typescript
+import { produce } from 'immer';
+
+// Each apply function uses immer for immutable updates
+export function applyNumberSet(
+  draft: SceneGraph,
+  op: NumberSetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  node[op.path] = op.value;
+  node.lamportTime = meta.lamportTime;
+  node.updatedAt = meta.timestamp;
+}
+
+export function applyNumberAdd(
+  draft: SceneGraph,
+  op: NumberAddOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = (node[op.path] as number) ?? 0;
+  node[op.path] = current + op.value;
+  node.lamportTime = meta.lamportTime;
+  node.updatedAt = meta.timestamp;
+}
+```
+
+### Dispatcher
+
+```typescript
+import { produce } from 'immer';
+import * as registry from './operations/registry.js';
+
+const handlers: Record<string, (draft: SceneGraph, op: Operation, meta: OpMeta) => void> = {
+  'number.set': registry.applyNumberSet,
+  'number.add': registry.applyNumberAdd,
+  'vector3.set': registry.applyVector3Set,
+  'vector3.add': registry.applyVector3Add,
+  'array.set': registry.applyArraySet,
+  'array.push': registry.applyArrayPush,
+  'array.remove': registry.applyArrayRemove,
+  'node.insert': registry.applyNodeInsert,
+  'node.remove': registry.applyNodeRemove,
+  // ...
+};
+
+export function applyMessage(graph: SceneGraph, msg: CRDTMessage): SceneGraph {
+  return produce(graph, (draft) => {
+    const meta = {
+      sessionId: msg.sessionId,
+      clock: msg.clock,
+      lamportTime: msg.lamportTime,
+      timestamp: msg.timestamp,
+    };
+
+    for (const op of msg.ops) {
+      const handler = handlers[op.otype];
+      if (handler) {
+        handler(draft, op as any, meta);
+      } else {
+        console.warn(`Unknown otype: ${op.otype}`);
+      }
+    }
+  });
+}
+```

package/examples/01-basic-usage.ts

@@ -0,0 +1,139 @@
+/**
+ * Example 01: Basic Usage
+ *
+ * Demonstrates how to create a scene and apply operations.
+ * Run with: npx tsx examples/01-basic-usage.ts
+ */
+
+import { createEmptyGraph, applyMessage } from '../src/operations/index.js';
+import type { CRDTMessage } from '../src/operations/index.js';
+
+console.log('🎬 Example 01: Basic Usage\n');
+
+// Start with an empty scene graph
+let graph = createEmptyGraph();
+console.log('Initial graph:', graph);
+
+// ============================================
+// Step 1: Create a scene node
+// ============================================
+
+const msg1: CRDTMessage = {
+  id: 'msg-001',
+  sessionId: 'session-server',
+  clock: { 'session-server': 1 },
+  lamportTime: 1,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'scene',
+      otype: 'node.insert',
+      path: 'scene',
+      value: {
+        id: 'uuid-scene-001',
+        tag: 'Scene',
+        name: 'My Scene',
+        background: '#87CEEB',
+        'transform.position': [0, 0, 0],
+        'transform.rotation': [0, 0, 0, 1],
+        'transform.scale': [1, 1, 1],
+      },
+    },
+  ],
+};
+
+graph = applyMessage(graph, msg1);
+console.log('\n✅ After inserting scene:');
+console.log('  Root key:', graph.rootKey);
+console.log('  Scene node:', graph.nodes['scene']);
+
+// ============================================
+// Step 2: Add a cube to the scene
+// ============================================
+
+const msg2: CRDTMessage = {
+  id: 'msg-002',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 1 },
+  lamportTime: 2,
+  timestamp: Date.now(),
+  ops: [
+    // Insert the cube node and add to scene's children in one operation
+    {
+      key: 'cube-1',
+      otype: 'node.insert',
+      path: 'cube-1',
+      parent: 'scene', // Automatically adds to scene's children
+      value: {
+        id: '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],
+      },
+    },
+  ],
+};
+
+graph = applyMessage(graph, msg2);
+console.log('\n✅ After adding cube:');
+console.log('  Cube node:', graph.nodes['cube-1']);
+console.log('  Scene children:', graph.nodes['scene'].children);
+
+// ============================================
+// Step 3: Move the cube (additive)
+// ============================================
+
+const msg3: CRDTMessage = {
+  id: 'msg-003',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 2 },
+  lamportTime: 3,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'vector3.add',
+      path: 'transform.position',
+      value: [5, 0, 0], // Move right by 5
+    },
+  ],
+};
+
+graph = applyMessage(graph, msg3);
+console.log('\n✅ After moving cube (additive):');
+console.log('  Cube position:', graph.nodes['cube-1']['transform.position']);
+// Expected: [7, 1, 0] (original [2,1,0] + delta [5,0,0])
+
+// ============================================
+// Step 4: Change cube color
+// ============================================
+
+const msg4: CRDTMessage = {
+  id: 'msg-004',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 3 },
+  lamportTime: 4,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'color.set',
+      path: 'color',
+      value: '#00ff00', // Change to green
+    },
+  ],
+};
+
+graph = applyMessage(graph, msg4);
+console.log('\n✅ After changing color:');
+console.log('  Cube color:', graph.nodes['cube-1'].color);
+
+// ============================================
+// Final state
+// ============================================
+
+console.log('\n📊 Final Scene Graph:');
+console.log(JSON.stringify(graph, null, 2));

package/examples/02-concurrent-edits.ts

@@ -0,0 +1,208 @@
+/**
+ * Example 02: Concurrent Edits
+ *
+ * Demonstrates how CRDT handles concurrent edits from multiple users.
+ * Run with: npx tsx examples/02-concurrent-edits.ts
+ */
+
+import { createEmptyGraph, applyMessage } from '../src/operations/index.js';
+import type { CRDTMessage } from '../src/operations/index.js';
+
+console.log('🎬 Example 02: Concurrent Edits\n');
+console.log('Scenario: Alice and Bob both edit the same cube at the same time.\n');
+
+// Setup: Create a scene with a cube
+let graph = createEmptyGraph();
+
+const setupMsg: CRDTMessage = {
+  id: 'setup',
+  sessionId: 'server',
+  clock: { server: 1 },
+  lamportTime: 0,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube',
+      otype: 'node.insert',
+      path: 'cube',
+      value: {
+        key: 'uuid-cube',
+        tag: 'Mesh',
+        name: 'Shared Cube',
+        color: '#ffffff',
+        score: 0,
+        'transform.position': [0, 0, 0],
+      },
+    },
+  ],
+};
+
+graph = applyMessage(graph, setupMsg);
+console.log('Initial cube position:', graph.nodes['cube']['transform.position']);
+console.log('Initial cube score:', graph.nodes['cube'].score);
+
+// ============================================
+// Scenario 1: Concurrent Drag (Additive)
+// ============================================
+
+console.log('\n--- Scenario 1: Concurrent Drag (vector3.add) ---\n');
+
+// Alice drags the cube right by [5, 0, 0]
+const aliceDrag: CRDTMessage = {
+  id: 'alice-drag',
+  sessionId: 'alice',
+  clock: { alice: 1 },
+  lamportTime: 10,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube',
+      otype: 'vector3.add', // Additive!
+      path: 'transform.position',
+      value: [5, 0, 0],
+    },
+  ],
+};
+
+// Bob drags the cube up by [0, 3, 0] (concurrent with Alice)
+const bobDrag: CRDTMessage = {
+  id: 'bob-drag',
+  sessionId: 'bob',
+  clock: { bob: 1 },
+  lamportTime: 11,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube',
+      otype: 'vector3.add', // Additive!
+      path: 'transform.position',
+      value: [0, 3, 0],
+    },
+  ],
+};
+
+console.log('Alice drags: += [5, 0, 0]');
+console.log('Bob drags:   += [0, 3, 0]');
+
+// Apply both (order doesn't matter for additive!)
+graph = applyMessage(graph, aliceDrag);
+graph = applyMessage(graph, bobDrag);
+
+console.log('\n✅ Result: Both movements applied!');
+console.log('Final position:', graph.nodes['cube']['transform.position']);
+console.log('Expected:       [5, 3, 0]');
+
+// ============================================
+// Scenario 2: Concurrent Score Update (Additive)
+// ============================================
+
+console.log('\n--- Scenario 2: Concurrent Score Update (number.add) ---\n');
+
+// Alice adds 10 points
+const aliceScore: CRDTMessage = {
+  id: 'alice-score',
+  sessionId: 'alice',
+  clock: { alice: 2 },
+  lamportTime: 20,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube',
+      otype: 'number.add',
+      path: 'score',
+      value: 10,
+    },
+  ],
+};
+
+// Bob adds 5 points (concurrent)
+const bobScore: CRDTMessage = {
+  id: 'bob-score',
+  sessionId: 'bob',
+  clock: { bob: 2 },
+  lamportTime: 21,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube',
+      otype: 'number.add',
+      path: 'score',
+      value: 5,
+    },
+  ],
+};
+
+console.log('Alice: score += 10');
+console.log('Bob:   score += 5');
+
+graph = applyMessage(graph, aliceScore);
+graph = applyMessage(graph, bobScore);
+
+console.log('\n✅ Result: Both scores accumulated!');
+console.log('Final score:', graph.nodes['cube'].score);
+console.log('Expected:    15');
+
+// ============================================
+// Scenario 3: Concurrent Color Change (LWW)
+// ============================================
+
+console.log('\n--- Scenario 3: Concurrent Color Change (color.set - LWW) ---\n');
+
+// Alice sets color to red (lamport: 30)
+const aliceColor: CRDTMessage = {
+  id: 'alice-color',
+  sessionId: 'alice',
+  clock: { alice: 3 },
+  lamportTime: 30,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube',
+      otype: 'color.set', // LWW!
+      path: 'color',
+      value: '#ff0000',
+    },
+  ],
+};
+
+// Bob sets color to blue (lamport: 31 - higher, so Bob wins)
+const bobColor: CRDTMessage = {
+  id: 'bob-color',
+  sessionId: 'bob',
+  clock: { bob: 3 },
+  lamportTime: 31, // Higher lamport time
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube',
+      otype: 'color.set', // LWW!
+      path: 'color',
+      value: '#0000ff',
+    },
+  ],
+};
+
+console.log('Alice: color = #ff0000 (red)   [lamport: 30]');
+console.log('Bob:   color = #0000ff (blue)  [lamport: 31]');
+
+graph = applyMessage(graph, aliceColor);
+graph = applyMessage(graph, bobColor);
+
+console.log('\n✅ Result: Bob wins (higher lamport time)!');
+console.log('Final color:', graph.nodes['cube'].color);
+console.log('Expected:    #0000ff (blue)');
+
+// ============================================
+// Summary
+// ============================================
+
+console.log('\n📊 Summary:');
+console.log('─'.repeat(50));
+console.log('Additive operations (*.add): Values are SUMMED');
+console.log('  → Great for: drag, counters, deltas');
+console.log('  → Order doesn\'t matter!');
+console.log('');
+console.log('LWW operations (*.set): Last write wins');
+console.log('  → Great for: colors, absolute positions, names');
+console.log('  → Higher lamportTime wins');
+console.log('─'.repeat(50));