@vuer-ai/vuer-rtc 0.0.1

package/dist/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2CAA2C;AAC3C,OAAO,EAAE,kBAAkB,EAAoB,MAAM,kBAAkB,CAAC;AAExE,4CAA4C;AAC5C,OAAO,EAAE,KAAK,EAAoC,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,WAAW,EAAuB,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/docs/OPERATION_HINTS.md

@@ -0,0 +1,222 @@
+# Explicit Operation Types: Additive vs Absolute Updates
+
+## The Problem
+
+In a collaborative 3D editor, the frontend knows the user's **intent**:
+- **Additive**: `position.x += 5` (relative movement)
+- **Absolute**: `position.x = 10` (set to specific value)
+
+## The Solution: Explicit otype
+
+Operations use explicit `otype` that encodes both dtype and operation:
+- `vector3.add` = additive vector operation
+- `vector3.set` = absolute vector operation
+- `number.add` = additive number operation
+- `number.set` = absolute number operation
+
+### CRDTMessage Structure
+
+```typescript
+interface CRDTMessage {
+  // === CRDT Metadata (envelope) ===
+  id: string;              // Message ID
+  sessionId: string;       // Session that created this message
+  clock: VectorClock;      // Vector clock for causal ordering
+  lamportTime: number;     // Lamport timestamp for total ordering
+  timestamp: number;       // Wall-clock time
+
+  // === Operations (batch) ===
+  ops: Operation[];        // One or more operations
+}
+```
+
+### Operation Structure
+
+```typescript
+interface BaseOp {
+  key: string;     // Node key (e.g., 'cube-1', 'player')
+  otype: string;   // Explicit dtype.operation (e.g., 'vector3.add')
+  path: string;    // Property path (e.g., 'transform.position')
+}
+```
+
+## Frontend Use Cases
+
+### Case 1: Additive Transform (Relative Movement)
+
+User drags object by [5, 0, 0]:
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-001',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 1 },
+  lamportTime: 1,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'vector3.add',  // Explicit additive!
+      path: 'transform.position',
+      value: [5, 0, 0]
+    }
+  ]
+};
+```
+
+**Result**: If two users drag simultaneously, both movements apply:
+- Alice: `position += [5, 0, 0]`
+- Bob: `position += [0, 3, 0]`
+- Final: `position += [5, 3, 0]` ✅
+
+### Case 2: Absolute Transform (Set Position)
+
+User enters exact coordinates in inspector:
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-002',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 2 },
+  lamportTime: 2,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'sphere-1',
+      otype: 'vector3.set',  // Explicit absolute!
+      path: 'transform.position',
+      value: [10, 5, 0]
+    }
+  ]
+};
+```
+
+**Result**: If two users set position simultaneously, last-write-wins:
+- Alice: `position = [10, 5, 0]` (lamport: 100)
+- Bob: `position = [0, 10, 0]` (lamport: 101)
+- Final: `position = [0, 10, 0]` (Bob wins) ✅
+
+### Case 3: Score Counter (Always Additive)
+
+User collects 10 points:
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-003',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 3 },
+  lamportTime: 3,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'number.add',  // Additive counter
+      path: 'score',
+      value: 10
+    }
+  ]
+};
+```
+
+**Result**: Concurrent score updates sum:
+- Alice: `score += 10`
+- Bob: `score += 5`
+- Final: `score = 15` ✅
+
+### Case 4: Color (Always LWW)
+
+User changes material color:
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-004',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 4 },
+  lamportTime: 4,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'color.set',
+      path: 'color',
+      value: '#ff0000'
+    }
+  ]
+};
+```
+
+**Result**: Concurrent color changes resolve to latest:
+- Alice: `color = '#ff0000'` (lamport: 100)
+- Bob: `color = '#00ff00'` (lamport: 101)
+- Final: `color = '#00ff00'` (Bob wins) ✅
+
+## Batching: Multiple Operations in One Message
+
+### Same Node, Multiple Properties
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-005',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 5 },
+  lamportTime: 5,
+  timestamp: Date.now(),
+  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] }
+  ]
+};
+```
+
+### Multi-Select Drag (Multiple Nodes)
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-006',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 6 },
+  lamportTime: 6,
+  timestamp: Date.now(),
+  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] }
+  ]
+};
+```
+
+## Available Operation Types
+
+| otype | Description | Example |
+|-------|-------------|---------|
+| `number.set` | LWW number | `opacity = 0.5` |
+| `number.add` | Additive | `score += 10` |
+| `number.multiply` | Multiplicative | `scale *= 2` |
+| `number.min` | Take minimum | `minScore = min(current, new)` |
+| `number.max` | Take maximum | `maxScore = max(current, new)` |
+| `vector3.set` | LWW vector | `position = [0, 5, 0]` |
+| `vector3.add` | Additive | `position += [5, 0, 0]` |
+| `color.set` | LWW color | `color = '#ff0000'` |
+| `array.set` | Replace array | `children = ['a', 'b']` |
+| `array.push` | Append item | `children.push('c')` |
+| `array.remove` | Remove item | `children.remove('a')` |
+| `node.insert` | Create node | New node in scene |
+| `node.remove` | Delete node | Tombstone |
+
+## Example: Transform Gestures
+
+| Gesture | otype | path | value |
+|---------|-------|------|-------|
+| Drag (translate) | `vector3.add` | `transform.position` | `[dx, dy, dz]` |
+| Inspector input | `vector3.set` | `transform.position` | `[x, y, z]` |
+| Scale gesture | `vector3.multiply` | `transform.scale` | `[sx, sy, sz]` |
+| Snap to grid | `vector3.set` | `transform.position` | `[gx, gy, gz]` |
+
+## Key Design Points
+
+1. **Explicit otype**: `vector3.add` vs `vector3.set` - no ambiguity
+2. **Operations use `key`**: Human-friendly node keys, not UUIDs
+3. **True batching**: One message, multiple ops, atomic
+4. **Clean structure**: No nested "properties" or "operations" objects
+
+See `docs/TYPE_BEHAVIORS.md` for complete merge semantics.

package/docs/SCENE_GRAPH.md

@@ -0,0 +1,373 @@
+# Scene Graph Data Structure
+
+Hierarchical tree structure for collaborative 3D editing with **instancing support** via flattened map format.
+
+## Table of Contents
+
+- [Scene Graph Schema](#scene-graph-schema)
+- [Scene Node Schema](#scene-node-schema)
+- [CRDTMessage Structure](#crdtmessage-structure)
+- [Operations](#operations)
+  - [node.insert](#nodeinsert)
+  - [node.remove](#noderemove)
+  - [Property Operations](#property-operations)
+  - [Array Operations](#array-operations)
+- [Tree Operations](#tree-operations)
+  - [Reparent (Compound)](#reparent-compound)
+- [Instancing](#instancing)
+- [Query Patterns](#query-patterns)
+
+---
+
+## Scene Graph Schema
+
+```typescript
+interface SceneGraph {
+  nodes: Record<string, SceneNode>;  // Flattened map by key
+  rootKey: string;                    // Root node key
+}
+```
+
+**Design:** Flattened map (similar to glTF) for O(1) lookup and stable references.
+
+**Example:**
+```typescript
+{
+  nodes: {
+    'scene': { key: 'scene', tag: 'Scene', children: ['forest', 'player'], ... },
+    'forest': { key: 'forest', tag: 'Group', children: ['tree-1'], ... },
+    'tree-1': { key: 'tree-1', tag: 'Mesh', children: [], ... },
+    'player': { key: 'player', tag: 'Mesh', children: [], ... }
+  },
+  rootKey: 'scene'
+}
+```
+
+---
+
+## Scene Node Schema
+
+```typescript
+interface SceneNode {
+  // Identity
+  id: string;                  // UUID (for CRDT)
+  key: string;                 // Map key (human-friendly, unique in scene)
+  tag: string;                 // "Scene" | "Group" | "Mesh" | "Light" | "Camera"
+  name: string;                // Display name
+
+  // Tree structure (children-only for instancing)
+  children: string[];          // Child keys (not IDs!)
+
+  // Properties (flat structure with dot-notation paths)
+  // e.g., 'transform.position': [0, 0, 0], 'color': '#ff0000'
+  [key: string]: any;
+
+  // CRDT metadata
+  clock: VectorClock;
+  lamportTime: number;
+  createdAt: number;
+  updatedAt: number;
+  deletedAt?: number;          // Tombstone (soft delete)
+}
+```
+
+**Key Design Decisions:**
+- **Flattened map** by `key` (not nested tree)
+- **No `parentId`** → supports **instancing** (same node can have multiple parents)
+- **Operations use `key`** → human-readable references
+- **Children use keys** (not IDs) → human-readable tree structure
+
+---
+
+## CRDTMessage Structure
+
+All operations are wrapped in a `CRDTMessage` envelope:
+
+```typescript
+interface CRDTMessage {
+  // === CRDT Metadata (envelope) ===
+  id: string;              // Message ID
+  sessionId: string;       // Session that created this message
+  clock: VectorClock;      // Vector clock for causal ordering
+  lamportTime: number;     // Lamport timestamp for total ordering
+  timestamp: number;       // Wall-clock time
+
+  // === Operations (batch) ===
+  ops: Operation[];        // One or more operations
+}
+
+interface BaseOp {
+  key: string;     // Node key (e.g., 'cube-1', 'scene')
+  otype: string;   // dtype.operation (e.g., 'vector3.add', 'node.insert')
+  path: string;    // Property path (e.g., 'transform.position')
+}
+```
+
+---
+
+## Operations
+
+### node.insert
+
+Create a new node in the scene graph.
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-001',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 1 },
+  lamportTime: 1,
+  timestamp: Date.now(),
+  ops: [
+    {
+      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]
+      }
+    }
+  ]
+};
+
+// Result: Added to nodes map
+// nodes['cube-1'] = { id: 'uuid-cube-001', key: 'cube-1', tag: 'Mesh', ... }
+```
+
+**Behavior:**
+- Adds node to `nodes` map: `nodes[key] = node`
+- If `key` already exists → idempotent (no-op)
+- Does NOT auto-add to parent (use separate `array.push` on parent's `children`)
+
+**Conflicts:**
+- Different keys → both succeed
+- Same key → first wins (idempotent)
+
+---
+
+### node.remove
+
+Delete node (tombstone) + remove from all parents' children.
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-002',
+  sessionId: 'session-bob',
+  clock: { 'session-bob': 1 },
+  lamportTime: 2,
+  timestamp: Date.now(),
+  ops: [
+    {
+      key: 'cube-1',
+      otype: 'node.remove',
+      path: 'cube-1'
+    }
+  ]
+};
+```
+
+**Behavior:**
+1. Set `node.deletedAt = timestamp` (tombstone)
+2. Remove `cube-1` from all parents' `children` arrays
+
+**Conflicts:**
+- remove **wins** over concurrent property update
+- Multiple removes → idempotent
+
+---
+
+### Property Operations
+
+Update node properties using explicit otype:
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-003',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 2 },
+  lamportTime: 3,
+  timestamp: Date.now(),
+  ops: [
+    // Additive transform (drag)
+    { key: 'cube-1', otype: 'vector3.add', path: 'transform.position', value: [5, 0, 0] },
+
+    // Absolute transform (inspector input)
+    { key: 'sphere-1', otype: 'vector3.set', path: 'transform.position', value: [0, 5, 0] },
+
+    // Color change (LWW)
+    { key: 'cube-1', otype: 'color.set', path: 'color', value: '#00ff00' },
+
+    // Additive counter
+    { key: 'cube-1', otype: 'number.add', path: 'score', value: 10 },
+
+    // LWW number
+    { key: 'cube-1', otype: 'number.set', path: 'opacity', value: 0.5 }
+  ]
+};
+```
+
+**Available Property otypes:**
+
+| otype | Merge Behavior | Example |
+|-------|---------------|---------|
+| `number.set` | LWW | `opacity = 0.5` |
+| `number.add` | Sum | `score += 10` |
+| `number.multiply` | Product | `scale *= 2` |
+| `number.min` | Minimum | `min(current, new)` |
+| `number.max` | Maximum | `max(current, new)` |
+| `vector3.set` | LWW | `position = [0,5,0]` |
+| `vector3.add` | Component-wise sum | `position += [5,0,0]` |
+| `quaternion.set` | LWW | `rotation = [0,0,0,1]` |
+| `color.set` | LWW | `color = '#ff0000'` |
+| `string.set` | LWW | `name = 'Cube'` |
+| `boolean.set` | LWW | `visible = true` |
+
+---
+
+### Array Operations
+
+Manipulate arrays (like `children`):
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-004',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 3 },
+  lamportTime: 4,
+  timestamp: Date.now(),
+  ops: [
+    // 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' }
+  ]
+};
+```
+
+---
+
+## Tree Operations
+
+### Reparent (Compound)
+
+Move node from one parent to another using batched operations:
+
+```typescript
+const msg: CRDTMessage = {
+  id: 'msg-005',
+  sessionId: 'session-alice',
+  clock: { 'session-alice': 4 },
+  lamportTime: 5,
+  timestamp: Date.now(),
+  ops: [
+    // 1. Create new parent (optional)
+    {
+      key: 'group-1',
+      otype: 'node.insert',
+      path: 'group-1',
+      value: {
+        id: 'uuid-group-001',
+        tag: 'Group',
+        name: 'My Group',
+        'transform.position': [0, 0, 0],
+        'transform.rotation': [0, 0, 0, 1],
+        'transform.scale': [1, 1, 1]
+      }
+    },
+    // 2. Remove from old parent
+    { key: 'scene', otype: 'array.remove', path: 'children', value: 'cube-1' },
+    // 3. Add to new parent
+    { key: 'group-1', otype: 'array.push', path: 'children', value: 'cube-1' }
+  ]
+};
+// → cube-1 moved from scene to group-1 (atomic)
+```
+
+**Why compound operations?**
+- Children-only model (no parentId to update)
+- Supports instancing (node can have multiple parents)
+- Atomic: all operations in same message
+
+---
+
+## Instancing
+
+Same node can appear in multiple places (multiple parents reference it).
+
+```typescript
+// Shared tree node
+{ key: 'tree-model', tag: 'Mesh', geometry: 'tree.glb', ... }
+
+// Parent A references it
+{ key: 'forest-A', tag: 'Group', children: ['tree-model', ...] }
+
+// Parent B also references it
+{ key: 'forest-B', tag: 'Group', children: ['tree-model', ...] }
+```
+
+`tree-model` appears in **both** `forest-A` and `forest-B`.
+
+**Transform:**
+- Each parent's transform combines with `tree-model`'s local transform
+- World transform = parent.transform × tree-model.transform
+
+**Delete:**
+- If `tree-model` is removed via `node.remove`, it's deleted from **all** parents' children arrays
+
+---
+
+## Query Patterns
+
+```typescript
+// Get node by key
+getNode(key: string): SceneNode | undefined
+
+// Get active nodes (exclude tombstones)
+getActiveNodes(): SceneNode[]
+
+// Get children
+getChildren(key: string): SceneNode[]
+
+// Find parents (requires reverse index)
+getParents(key: string): SceneNode[]
+
+// Build reverse index
+function buildParentIndex(nodes: Record<string, SceneNode>): Map<string, string[]> {
+  const index = new Map();
+  for (const node of Object.values(nodes)) {
+    for (const childKey of node.children) {
+      if (!index.has(childKey)) index.set(childKey, []);
+      index.get(childKey).push(node.key);
+    }
+  }
+  return index;
+}
+
+// Check cycles
+isDescendant(key: string, ancestorKey: string): boolean
+
+// Get world transform
+getWorldTransform(key: string, throughParentKey: string): Transform3D
+```
+
+---
+
+## Design Rationale
+
+- ✅ **Instancing support** (multiple parents)
+- ✅ **Simpler model** (one-way references only)
+- ✅ **CRDT-friendly** (no bidirectional constraints)
+- ✅ **True batching** (multiple ops, atomic)
+- ✅ **Explicit otype** (no ambiguity: `vector3.add` vs `vector3.set`)
+- ✅ **Human-friendly keys** (not UUIDs)
+- ❌ **Parent lookup requires reverse index** (not persisted)