@vuer-ai/vuer-rtc 0.0.1

package/src/operations/OperationTypes.ts

@@ -0,0 +1,340 @@
+/**
+ * Operation Types - New design with CRDT wrapper and dtype operations
+ *
+ * Design:
+ * - CRDTMessage: Envelope with CRDT metadata + batch of operations
+ * - Operations: Explicit dtype operations (number.set, vector3.add, etc.)
+ * - Batching: One message can contain multiple operations on multiple nodes
+ */
+
+import type { VectorClock } from '../state/VectorClock.js';
+
+/**
+ * CRDTMessage - Envelope containing CRDT metadata + batch of operations
+ */
+export interface CRDTMessage {
+  // === CRDT Metadata (wrapper) ===
+  id: string;              // Message ID (UUID)
+  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 (milliseconds since epoch)
+
+  // === Operations (batch) ===
+  ops: Operation[];        // One or more operations
+}
+
+/**
+ * Base Operation - All operations extend this
+ */
+export interface BaseOp {
+  key: string;     // Node key (human-friendly, e.g., 'cube-1', 'player', 'scene')
+  otype: string;   // dtype operation: 'number.set', 'vector3.add', etc.
+  path: string;    // Property path: 'color', 'transform.position', etc.
+}
+
+// ============================================
+// NUMBER Operations
+// ============================================
+
+export interface NumberSetOp extends BaseOp {
+  key: string;
+  otype: 'number.set';
+  path: string;
+  value: number;
+}
+
+export interface NumberAddOp extends BaseOp {
+  key: string;
+  otype: 'number.add';
+  path: string;
+  value: number;
+}
+
+export interface NumberMultiplyOp extends BaseOp {
+  key: string;
+  otype: 'number.multiply';
+  path: string;
+  value: number;
+}
+
+export interface NumberMinOp extends BaseOp {
+  key: string;
+  otype: 'number.min';
+  path: string;
+  value: number;
+}
+
+export interface NumberMaxOp extends BaseOp {
+  key: string;
+  otype: 'number.max';
+  path: string;
+  value: number;
+}
+
+// ============================================
+// STRING Operations
+// ============================================
+
+export interface StringSetOp extends BaseOp {
+  key: string;
+  otype: 'string.set';
+  path: string;
+  value: string;
+}
+
+export interface StringConcatOp extends BaseOp {
+  key: string;
+  otype: 'string.concat';
+  path: string;
+  value: string;
+  separator?: string;
+}
+
+// ============================================
+// BOOLEAN Operations
+// ============================================
+
+export interface BooleanSetOp extends BaseOp {
+  key: string;
+  otype: 'boolean.set';
+  path: string;
+  value: boolean;
+}
+
+export interface BooleanOrOp extends BaseOp {
+  key: string;
+  otype: 'boolean.or';
+  path: string;
+  value: boolean;
+}
+
+export interface BooleanAndOp extends BaseOp {
+  key: string;
+  otype: 'boolean.and';
+  path: string;
+  value: boolean;
+}
+
+// ============================================
+// VECTOR3 Operations
+// ============================================
+
+export interface Vector3SetOp extends BaseOp {
+  key: string;
+  otype: 'vector3.set';
+  path: string;
+  value: [number, number, number];
+}
+
+export interface Vector3AddOp extends BaseOp {
+  key: string;
+  otype: 'vector3.add';
+  path: string;
+  value: [number, number, number];
+}
+
+export interface Vector3MultiplyOp extends BaseOp {
+  key: string;
+  otype: 'vector3.multiply';
+  path: string;
+  value: [number, number, number];
+}
+
+// ============================================
+// QUATERNION Operations
+// ============================================
+
+export interface QuaternionSetOp extends BaseOp {
+  key: string;
+  otype: 'quaternion.set';
+  path: string;
+  value: [number, number, number, number];
+}
+
+export interface QuaternionMultiplyOp extends BaseOp {
+  key: string;
+  otype: 'quaternion.multiply';
+  path: string;
+  value: [number, number, number, number];
+}
+
+// ============================================
+// COLOR Operations
+// ============================================
+
+export interface ColorSetOp extends BaseOp {
+  key: string;
+  otype: 'color.set';
+  path: string;
+  value: string;  // Hex color
+}
+
+export interface ColorBlendOp extends BaseOp {
+  key: string;
+  otype: 'color.blend';
+  path: string;
+  value: string;
+}
+
+// ============================================
+// ARRAY Operations
+// ============================================
+
+export interface ArraySetOp extends BaseOp {
+  key: string;
+  otype: 'array.set';
+  path: string;
+  value: any[];
+}
+
+export interface ArrayPushOp extends BaseOp {
+  key: string;
+  otype: 'array.push';
+  path: string;
+  value: any;
+}
+
+export interface ArrayUnionOp extends BaseOp {
+  key: string;
+  otype: 'array.union';
+  path: string;
+  value: any[];
+}
+
+export interface ArrayRemoveOp extends BaseOp {
+  key: string;
+  otype: 'array.remove';
+  path: string;
+  value: any;
+}
+
+// ============================================
+// OBJECT Operations
+// ============================================
+
+export interface ObjectSetOp extends BaseOp {
+  key: string;
+  otype: 'object.set';
+  path: string;
+  value: Record<string, any>;
+}
+
+export interface ObjectMergeOp extends BaseOp {
+  key: string;
+  otype: 'object.merge';
+  path: string;
+  value: Record<string, any>;
+}
+
+// ============================================
+// SCENE GRAPH Operations
+// ============================================
+
+/**
+ * NODE.INSERT - Create new node as child of parent
+ */
+export interface NodeInsertOp extends BaseOp {
+  key: string;     // Parent node's key
+  otype: 'node.insert';
+  path: 'children';
+  value: {
+    key: string;   // New node's key
+    id: string;    // Node's UUID (for CRDT)
+    tag: string;   // 'Scene' | 'Mesh' | 'Group' | ...
+    name: string;
+    [key: string]: any;  // Initial properties
+  };
+}
+
+/**
+ * NODE.REMOVE - Remove node from parent (tombstone)
+ */
+export interface NodeRemoveOp extends BaseOp {
+  key: string;     // Parent node's key
+  otype: 'node.remove';
+  path: 'children';
+  value: string;   // Node key to remove
+}
+
+// ============================================
+// META Operations (undo/redo)
+// ============================================
+
+/**
+ * META.UNDO - Mark a message as undone
+ */
+export interface MetaUndoOp {
+  key: '_meta';
+  otype: 'meta.undo';
+  path: '_meta';
+  targetMsgId: string;  // Message ID to undo
+}
+
+/**
+ * META.REDO - Unmark a message as undone
+ */
+export interface MetaRedoOp {
+  key: '_meta';
+  otype: 'meta.redo';
+  path: '_meta';
+  targetMsgId: string;  // Message ID to redo
+}
+
+// ============================================
+// Union of all operations
+// ============================================
+
+export type Operation =
+  | NumberSetOp | NumberAddOp | NumberMultiplyOp | NumberMinOp | NumberMaxOp
+  | StringSetOp | StringConcatOp
+  | BooleanSetOp | BooleanOrOp | BooleanAndOp
+  | Vector3SetOp | Vector3AddOp | Vector3MultiplyOp
+  | QuaternionSetOp | QuaternionMultiplyOp
+  | ColorSetOp | ColorBlendOp
+  | ArraySetOp | ArrayPushOp | ArrayUnionOp | ArrayRemoveOp
+  | ObjectSetOp | ObjectMergeOp
+  | NodeInsertOp | NodeRemoveOp
+  | MetaUndoOp | MetaRedoOp;
+
+// ============================================
+// Scene Graph (state representation)
+// ============================================
+
+/**
+ * SceneNode - Node in the flattened scene graph
+ *
+ * Properties are stored directly on the node with dot-notation paths:
+ * - 'transform.position': [0, 0, 0]
+ * - 'color': '#ff0000'
+ * - 'opacity': 0.5
+ */
+export interface SceneNode {
+  // Identity
+  id: string;      // UUID (used for CRDT)
+  key: string;     // Map key (human-friendly, unique in scene)
+  tag: string;     // Node type
+  name: string;    // Display name
+
+  // Tree structure
+  children: string[];  // Child node keys (not IDs!)
+
+  // CRDT metadata
+  clock: VectorClock;
+  lamportTime: number;
+  createdAt: number;
+  updatedAt: number;
+  deletedAt?: number;  // Tombstone for soft delete
+
+  // Dynamic properties (flat with dot-notation paths)
+  // e.g., 'transform.position', 'color', 'opacity'
+  [path: string]: unknown;
+}
+
+/**
+ * SceneGraph - Complete scene representation
+ */
+export interface SceneGraph {
+  nodes: Record<string, SceneNode>;  // Flattened map by key
+  rootKey: string;                    // Root node key
+}

package/src/operations/OperationValidator.ts

@@ -0,0 +1,260 @@
+/**
+ * Operation Validator - Validates CRDTMessage and operations
+ *
+ * Validates:
+ * - CRDTMessage envelope (CRDT metadata)
+ * - Individual operations (dtype operations)
+ */
+
+import type { CRDTMessage, Operation } from './OperationTypes.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors?: string[];
+}
+
+export class OperationValidator {
+  /**
+   * Validate a CRDTMessage (envelope + operations)
+   */
+  validateMessage(msg: any): ValidationResult {
+    const errors: string[] = [];
+
+    // Validate envelope
+    if (!msg.id || typeof msg.id !== 'string') {
+      errors.push('id is required and must be a string');
+    }
+
+    if (!msg.sessionId || typeof msg.sessionId !== 'string') {
+      errors.push('sessionId is required and must be a string');
+    }
+
+    if (!msg.clock || typeof msg.clock !== 'object') {
+      errors.push('clock must be an object');
+    }
+
+    if (typeof msg.lamportTime !== 'number') {
+      errors.push('lamportTime must be a number');
+    }
+
+    if (typeof msg.timestamp !== 'number') {
+      errors.push('timestamp must be a number');
+    }
+
+    if (!Array.isArray(msg.ops)) {
+      errors.push('ops must be an array');
+      return { valid: false, errors };
+    }
+
+    if (msg.ops.length === 0) {
+      errors.push('ops array cannot be empty');
+    }
+
+    // Validate each operation
+    msg.ops.forEach((op: any, index: number) => {
+      const opErrors = this.validateOperation(op);
+      if (!opErrors.valid) {
+        errors.push(`op[${index}]: ${opErrors.errors?.join(', ')}`);
+      }
+    });
+
+    return errors.length > 0 ? { valid: false, errors } : { valid: true };
+  }
+
+  /**
+   * Validate a single operation
+   */
+  validateOperation(op: any): ValidationResult {
+    const errors: string[] = [];
+
+    // Validate base fields
+    if (!op.key || typeof op.key !== 'string') {
+      errors.push('key is required and must be a string');
+    }
+
+    if (!op.otype || typeof op.otype !== 'string') {
+      errors.push('otype is required and must be a string');
+    }
+
+    if (!op.path || typeof op.path !== 'string') {
+      errors.push('path is required and must be a string');
+    }
+
+    // Validate based on otype
+    if (op.otype) {
+      const [dtype, operation] = op.otype.split('.');
+
+      switch (dtype) {
+        case 'number':
+          this.validateNumberOp(op, operation, errors);
+          break;
+        case 'string':
+          this.validateStringOp(op, operation, errors);
+          break;
+        case 'boolean':
+          this.validateBooleanOp(op, operation, errors);
+          break;
+        case 'vector3':
+          this.validateVector3Op(op, operation, errors);
+          break;
+        case 'quaternion':
+          this.validateQuaternionOp(op, operation, errors);
+          break;
+        case 'color':
+          this.validateColorOp(op, operation, errors);
+          break;
+        case 'array':
+          this.validateArrayOp(op, operation, errors);
+          break;
+        case 'object':
+          this.validateObjectOp(op, operation, errors);
+          break;
+        case 'node':
+          this.validateNodeOp(op, operation, errors);
+          break;
+        case 'meta':
+          this.validateMetaOp(op, operation, errors);
+          break;
+        default:
+          errors.push(`Unknown dtype: ${dtype}`);
+      }
+    }
+
+    return errors.length > 0 ? { valid: false, errors } : { valid: true };
+  }
+
+  private validateNumberOp(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'add', 'multiply', 'min', 'max'].includes(operation)) {
+      errors.push(`Invalid number operation: ${operation}`);
+    }
+
+    if (typeof op.value !== 'number') {
+      errors.push('number operation requires value to be a number');
+    }
+  }
+
+  private validateStringOp(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'concat'].includes(operation)) {
+      errors.push(`Invalid string operation: ${operation}`);
+    }
+
+    if (typeof op.value !== 'string') {
+      errors.push('string operation requires value to be a string');
+    }
+  }
+
+  private validateBooleanOp(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'or', 'and'].includes(operation)) {
+      errors.push(`Invalid boolean operation: ${operation}`);
+    }
+
+    if (typeof op.value !== 'boolean') {
+      errors.push('boolean operation requires value to be a boolean');
+    }
+  }
+
+  private validateVector3Op(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'add', 'multiply'].includes(operation)) {
+      errors.push(`Invalid vector3 operation: ${operation}`);
+    }
+
+    if (
+      !Array.isArray(op.value) ||
+      op.value.length !== 3 ||
+      !op.value.every((v: any) => typeof v === 'number')
+    ) {
+      errors.push('vector3 operation requires value to be [number, number, number]');
+    }
+  }
+
+  private validateQuaternionOp(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'multiply'].includes(operation)) {
+      errors.push(`Invalid quaternion operation: ${operation}`);
+    }
+
+    if (
+      !Array.isArray(op.value) ||
+      op.value.length !== 4 ||
+      !op.value.every((v: any) => typeof v === 'number')
+    ) {
+      errors.push('quaternion operation requires value to be [number, number, number, number]');
+    }
+  }
+
+  private validateColorOp(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'blend'].includes(operation)) {
+      errors.push(`Invalid color operation: ${operation}`);
+    }
+
+    if (typeof op.value !== 'string') {
+      errors.push('color operation requires value to be a string');
+    }
+  }
+
+  private validateArrayOp(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'push', 'union', 'remove'].includes(operation)) {
+      errors.push(`Invalid array operation: ${operation}`);
+    }
+
+    if (operation === 'set' || operation === 'union') {
+      if (!Array.isArray(op.value)) {
+        errors.push(`array.${operation} requires value to be an array`);
+      }
+    }
+    // push and remove can be any value
+  }
+
+  private validateObjectOp(op: any, operation: string, errors: string[]): void {
+    if (!['set', 'merge'].includes(operation)) {
+      errors.push(`Invalid object operation: ${operation}`);
+    }
+
+    if (typeof op.value !== 'object' || Array.isArray(op.value)) {
+      errors.push('object operation requires value to be an object');
+    }
+  }
+
+  private validateNodeOp(op: any, operation: string, errors: string[]): void {
+    if (!['insert', 'remove'].includes(operation)) {
+      errors.push(`Invalid node operation: ${operation}`);
+    }
+
+    if (operation === 'insert') {
+      if (!op.value || typeof op.value !== 'object') {
+        errors.push('node.insert requires value to be an object');
+        return;
+      }
+
+      if (!op.value.id || typeof op.value.id !== 'string') {
+        errors.push('node.insert requires value.id (string)');
+      }
+
+      if (!op.value.tag || typeof op.value.tag !== 'string') {
+        errors.push('node.insert requires value.tag (string)');
+      }
+
+      if (!op.value.name || typeof op.value.name !== 'string') {
+        errors.push('node.insert requires value.name (string)');
+      }
+    }
+    // node.remove doesn't have value
+  }
+
+  private validateMetaOp(op: any, operation: string, errors: string[]): void {
+    if (!['undo', 'redo'].includes(operation)) {
+      errors.push(`Invalid meta operation: ${operation}`);
+    }
+
+    if (op.key !== '_meta') {
+      errors.push('meta operation requires key to be "_meta"');
+    }
+
+    if (op.path !== '_meta') {
+      errors.push('meta operation requires path to be "_meta"');
+    }
+
+    if (!op.targetMsgId || typeof op.targetMsgId !== 'string') {
+      errors.push('meta operation requires targetMsgId (string)');
+    }
+  }
+}

package/src/operations/apply/array.ts

@@ -0,0 +1,84 @@
+/**
+ * Array operations: set, push, remove, union
+ */
+
+import type { SceneGraph, ArraySetOp, ArrayPushOp, ArrayRemoveOp, ArrayUnionOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+/**
+ * array.set - Last-Write-Wins (replace the entire array)
+ */
+export function ArraySet(
+  draft: SceneGraph,
+  op: ArraySetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, [...op.value], meta);
+}
+
+/**
+ * array.push - Append item to an array
+ */
+export function ArrayPush(
+  draft: SceneGraph,
+  op: ArrayPushOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty<unknown[]>(node, op.path, []);
+  setNodeProperty(node, op.path, [...current, op.value], meta);
+}
+
+/**
+ * array.remove - Remove item from array (by value equality)
+ */
+export function ArrayRemove(
+  draft: SceneGraph,
+  op: ArrayRemoveOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty<unknown[]>(node, op.path, []);
+  const filtered = current.filter(item => {
+    // Handle primitive equality and object reference
+    if (typeof item === 'object' && typeof op.value === 'object') {
+      return JSON.stringify(item) !== JSON.stringify(op.value);
+    }
+    return item !== op.value;
+  });
+  setNodeProperty(node, op.path, filtered, meta);
+}
+
+/**
+ * array.union - Union of arrays (set-like, no duplicates)
+ */
+export function ArrayUnion(
+  draft: SceneGraph,
+  op: ArrayUnionOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty<unknown[]>(node, op.path, []);
+
+  // Use Set for primitives, manual check for objects
+  const result = [...current];
+  for (const item of op.value) {
+    const exists = result.some(existing => {
+      if (typeof existing === 'object' && typeof item === 'object') {
+        return JSON.stringify(existing) === JSON.stringify(item);
+      }
+      return existing === item;
+    });
+    if (!exists) {
+      result.push(item);
+    }
+  }
+
+  setNodeProperty(node, op.path, result, meta);
+}