@vuer-ai/vuer-rtc 0.0.1

package/src/state/DType.ts

@@ -0,0 +1,333 @@
+/**
+ * DType - Data type system with merge operations
+ *
+ * Based on test-data/datatypes.ts
+ *
+ * Each dtype has supported operations that define merge behavior
+ * for concurrent updates.
+ */
+
+/**
+ * PropertyValue with metadata
+ */
+export interface ValueWithMeta<T = any> {
+  value: T;
+  lamportTime: number;
+  sessionId?: string;
+}
+
+/**
+ * Merge function signature
+ */
+export type MergeFn<T = any> = (values: ValueWithMeta<T>[]) => T;
+
+/**
+ * DType definitions
+ */
+export const DType = {
+  // ============================================
+  // PRIMITIVES
+  // ============================================
+
+  /**
+   * Number operations
+   */
+  number: {
+    /**
+     * SET - Last-Write-Wins
+     */
+    set: ((values: ValueWithMeta<number>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<number>,
+
+    /**
+     * ADD - Sum all values
+     */
+    add: ((values: ValueWithMeta<number>[]) => {
+      return values.reduce((sum, v) => sum + v.value, 0);
+    }) as MergeFn<number>,
+
+    /**
+     * MULTIPLY - Multiply all values
+     */
+    multiply: ((values: ValueWithMeta<number>[]) => {
+      return values.reduce((product, v) => product * v.value, 1);
+    }) as MergeFn<number>,
+
+    /**
+     * MIN - Take minimum
+     */
+    min: ((values: ValueWithMeta<number>[]) => {
+      return Math.min(...values.map((v) => v.value));
+    }) as MergeFn<number>,
+
+    /**
+     * MAX - Take maximum
+     */
+    max: ((values: ValueWithMeta<number>[]) => {
+      return Math.max(...values.map((v) => v.value));
+    }) as MergeFn<number>,
+  },
+
+  /**
+   * String operations
+   */
+  string: {
+    /**
+     * SET - Last-Write-Wins
+     */
+    set: ((values: ValueWithMeta<string>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<string>,
+
+    /**
+     * CONCAT - Concatenate (ordered by lamport)
+     */
+    concat: ((values: ValueWithMeta<string>[], separator = '\n') => {
+      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      return sorted.map((v) => v.value).join(separator);
+    }) as MergeFn<string>,
+  },
+
+  /**
+   * Boolean operations
+   */
+  boolean: {
+    /**
+     * SET - Last-Write-Wins
+     */
+    set: ((values: ValueWithMeta<boolean>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<boolean>,
+
+    /**
+     * OR - Logical OR (enable wins)
+     */
+    or: ((values: ValueWithMeta<boolean>[]) => {
+      return values.some((v) => v.value === true);
+    }) as MergeFn<boolean>,
+
+    /**
+     * AND - Logical AND (disable wins)
+     */
+    and: ((values: ValueWithMeta<boolean>[]) => {
+      return values.every((v) => v.value === true);
+    }) as MergeFn<boolean>,
+  },
+
+  // ============================================
+  // COMPOUND TYPES (3D GRAPHICS)
+  // ============================================
+
+  /**
+   * Vector3 operations - [x, y, z]
+   */
+  vector3: {
+    /**
+     * SET - Replace entire vector (preserves user intent)
+     */
+    set: ((values: ValueWithMeta<[number, number, number]>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<[number, number, number]>,
+
+    /**
+     * ADD - Component-wise addition
+     */
+    add: ((values: ValueWithMeta<[number, number, number]>[]) => {
+      const sum: [number, number, number] = [0, 0, 0];
+      for (const v of values) {
+        sum[0] += v.value[0];
+        sum[1] += v.value[1];
+        sum[2] += v.value[2];
+      }
+      return sum;
+    }) as MergeFn<[number, number, number]>,
+
+    /**
+     * MULTIPLY - Component-wise multiplication
+     */
+    multiply: ((values: ValueWithMeta<[number, number, number]>[]) => {
+      const product: [number, number, number] = [1, 1, 1];
+      for (const v of values) {
+        product[0] *= v.value[0];
+        product[1] *= v.value[1];
+        product[2] *= v.value[2];
+      }
+      return product;
+    }) as MergeFn<[number, number, number]>,
+  },
+
+  /**
+   * Quaternion operations - [x, y, z, w]
+   */
+  quaternion: {
+    /**
+     * SET - Replace entire quaternion
+     */
+    set: ((values: ValueWithMeta<[number, number, number, number]>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<[number, number, number, number]>,
+
+    /**
+     * MULTIPLY - Quaternion multiplication (composition)
+     */
+    multiply: ((values: ValueWithMeta<[number, number, number, number]>[]) => {
+      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      let result = sorted[0].value;
+
+      for (let i = 1; i < sorted.length; i++) {
+        result = multiplyQuaternions(result, sorted[i].value);
+      }
+
+      return result;
+    }) as MergeFn<[number, number, number, number]>,
+  },
+
+  /**
+   * Color operations
+   */
+  color: {
+    /**
+     * SET - Replace color
+     */
+    set: ((values: ValueWithMeta<string>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<string>,
+
+    /**
+     * BLEND - Average colors
+     */
+    blend: ((values: ValueWithMeta<string>[]) => {
+      const rgbs = values.map((v) => hexToRgb(v.value));
+      const avgR = Math.round(rgbs.reduce((sum, rgb) => sum + rgb.r, 0) / rgbs.length);
+      const avgG = Math.round(rgbs.reduce((sum, rgb) => sum + rgb.g, 0) / rgbs.length);
+      const avgB = Math.round(rgbs.reduce((sum, rgb) => sum + rgb.b, 0) / rgbs.length);
+      return rgbToHex(avgR, avgG, avgB);
+    }) as MergeFn<string>,
+  },
+
+  // ============================================
+  // COLLECTIONS
+  // ============================================
+
+  /**
+   * Array operations
+   */
+  array: {
+    /**
+     * SET - Replace entire array
+     */
+    set: ((values: ValueWithMeta<any[]>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<any[]>,
+
+    /**
+     * UNION - Merge unique elements
+     */
+    union: ((values: ValueWithMeta<any[]>[]) => {
+      const allElements = values.flatMap((v) => v.value);
+      return [...new Set(allElements)];
+    }) as MergeFn<any[]>,
+
+    /**
+     * APPEND - Append all (ordered by lamport)
+     */
+    append: ((values: ValueWithMeta<any[]>[]) => {
+      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      return sorted.flatMap((v) => v.value);
+    }) as MergeFn<any[]>,
+  },
+
+  /**
+   * Object operations
+   */
+  object: {
+    /**
+     * SET - Replace entire object
+     */
+    set: ((values: ValueWithMeta<Record<string, any>>[]) => {
+      const sorted = [...values].sort((a, b) => b.lamportTime - a.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn<Record<string, any>>,
+
+    /**
+     * LWW_PER_KEY - Last-Write-Wins per key
+     */
+    lwwPerKey: ((values: ValueWithMeta<Record<string, any>>[]) => {
+      const result: Record<string, any> = {};
+      const latestTimes: Record<string, number> = {};
+
+      for (const v of values) {
+        for (const [key, value] of Object.entries(v.value)) {
+          if (!latestTimes[key] || v.lamportTime > latestTimes[key]) {
+            result[key] = value;
+            latestTimes[key] = v.lamportTime;
+          }
+        }
+      }
+
+      return result;
+    }) as MergeFn<Record<string, any>>,
+  },
+
+  // ============================================
+  // SPECIAL
+  // ============================================
+
+  /**
+   * Immutable - Cannot be changed
+   */
+  immutable: {
+    set: ((values: ValueWithMeta[]) => {
+      // Return first value (creation value)
+      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      return sorted[0].value;
+    }) as MergeFn,
+  },
+};
+
+/**
+ * Helper: Multiply quaternions
+ */
+function multiplyQuaternions(
+  a: [number, number, number, number],
+  b: [number, number, number, number]
+): [number, number, number, number] {
+  const [ax, ay, az, aw] = a;
+  const [bx, by, bz, bw] = b;
+
+  return [
+    aw * bx + ax * bw + ay * bz - az * by,
+    aw * by - ax * bz + ay * bw + az * bx,
+    aw * bz + ax * by - ay * bx + az * bw,
+    aw * bw - ax * bx - ay * by - az * bz,
+  ];
+}
+
+/**
+ * Helper: Hex to RGB
+ */
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+        r: parseInt(result[1], 16),
+        g: parseInt(result[2], 16),
+        b: parseInt(result[3], 16),
+      }
+    : { r: 0, g: 0, b: 0 };
+}
+
+/**
+ * Helper: RGB to Hex
+ */
+function rgbToHex(r: number, g: number, b: number): string {
+  return '#' + [r, g, b].map((x) => x.toString(16).padStart(2, '0')).join('');
+}

package/src/state/Schema.ts

@@ -0,0 +1,236 @@
+/**
+ * Schema - Property schema definitions
+ *
+ * Defines dtype and operation for each property,
+ * determining how concurrent updates are merged.
+ *
+ * Based on test-data/schema-example.ts
+ */
+
+/**
+ * Property Schema Definition
+ */
+export interface PropertySchema {
+  dtype:
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'vector3'
+    | 'quaternion'
+    | 'color'
+    | 'array'
+    | 'object'
+    | 'any';
+
+  operation:
+    | 'set' // LWW
+    | 'add' // Additive
+    | 'multiply' // Multiplicative
+    | 'min' // Minimum
+    | 'max' // Maximum
+    | 'or' // Logical OR
+    | 'and' // Logical AND
+    | 'union' // Set union
+    | 'append' // Append (ordered)
+    | 'rga' // Replicated Growable Array
+    | 'lww-per-key' // LWW per object key
+    | 'lww-per-component' // LWW per component
+    | 'blend' // Blend/average
+    | 'immutable'; // Cannot change
+
+  default?: any;
+}
+
+/**
+ * Scene Node Schema
+ *
+ * Defines merge behavior for all scene node properties.
+ */
+export const sceneNodeSchema: Record<string, PropertySchema> = {
+  // ========================================
+  // Identity (immutable)
+  // ========================================
+  id: {
+    dtype: 'string',
+    operation: 'immutable',
+  },
+
+  tag: {
+    dtype: 'string',
+    operation: 'immutable',
+  },
+
+  key: {
+    dtype: 'string',
+    operation: 'set',
+    default: '',
+  },
+
+  name: {
+    dtype: 'string',
+    operation: 'set',
+    default: '',
+  },
+
+  // ========================================
+  // Tree Structure
+  // ========================================
+  children: {
+    dtype: 'array',
+    operation: 'set', // Phase 2: Simple LWW
+    default: [],
+  },
+
+  // ========================================
+  // Transform (LWW)
+  // ========================================
+  'transform.position': {
+    dtype: 'vector3',
+    operation: 'set',
+    default: [0, 0, 0],
+  },
+
+  'transform.rotation': {
+    dtype: 'quaternion',
+    operation: 'set',
+    default: [0, 0, 0, 1],
+  },
+
+  'transform.scale': {
+    dtype: 'vector3',
+    operation: 'set',
+    default: [1, 1, 1],
+  },
+
+  // ========================================
+  // Common Properties (LWW)
+  // ========================================
+  visible: {
+    dtype: 'boolean',
+    operation: 'set',
+    default: true,
+  },
+
+  color: {
+    dtype: 'color',
+    operation: 'set',
+    default: '#ffffff',
+  },
+
+  opacity: {
+    dtype: 'number',
+    operation: 'set',
+    default: 1.0,
+  },
+
+  // ========================================
+  // Material Properties (LWW)
+  // ========================================
+  material: {
+    dtype: 'string',
+    operation: 'set',
+    default: '',
+  },
+
+  geometry: {
+    dtype: 'string',
+    operation: 'set',
+    default: '',
+  },
+
+  metalness: {
+    dtype: 'number',
+    operation: 'set',
+    default: 0,
+  },
+
+  roughness: {
+    dtype: 'number',
+    operation: 'set',
+    default: 1,
+  },
+
+  // ========================================
+  // Additive Properties
+  // ========================================
+  score: {
+    dtype: 'number',
+    operation: 'add',
+    default: 0,
+  },
+
+  damage: {
+    dtype: 'number',
+    operation: 'add',
+    default: 0,
+  },
+
+  // ========================================
+  // Collection Properties
+  // ========================================
+  tags: {
+    dtype: 'array',
+    operation: 'union',
+    default: [],
+  },
+
+  // ========================================
+  // Object Properties (LWW per key)
+  // ========================================
+  properties: {
+    dtype: 'object',
+    operation: 'lww-per-key',
+    default: {},
+  },
+
+  // ========================================
+  // CRDT Metadata
+  // ========================================
+  clock: {
+    dtype: 'object',
+    operation: 'lww-per-key',
+    default: {},
+  },
+
+  lamportTime: {
+    dtype: 'number',
+    operation: 'set',
+    default: 0,
+  },
+
+  createdAt: {
+    dtype: 'number',
+    operation: 'immutable',
+  },
+
+  updatedAt: {
+    dtype: 'number',
+    operation: 'set',
+  },
+
+  deletedAt: {
+    dtype: 'number',
+    operation: 'set',
+  },
+};
+
+/**
+ * Get schema for a property
+ * Returns default schema if not found
+ */
+export function getPropertySchema(propertyName: string): PropertySchema {
+  return (
+    sceneNodeSchema[propertyName] || {
+      dtype: 'any',
+      operation: 'set', // Default to LWW
+    }
+  );
+}
+
+/**
+ * Check if a property is immutable
+ */
+export function isImmutable(propertyName: string): boolean {
+  const schema = getPropertySchema(propertyName);
+  return schema.operation === 'immutable';
+}

package/src/state/VectorClock.ts

@@ -0,0 +1,98 @@
+/**
+ * VectorClock - CRDT-inspired vector clock implementation
+ *
+ * Vector clocks provide causal ordering of operations in a distributed system.
+ * Each session maintains a counter, and clocks are compared to detect:
+ * - Causal ordering (A happened before B)
+ * - Concurrent operations (A and B are independent)
+ */
+
+export type VectorClock = Record<string, number>;
+
+export class VectorClockManager {
+  /**
+   * Create a new vector clock for a session
+   * Initializes the session's counter to 0
+   */
+  create(sessionId: string): VectorClock {
+    return { [sessionId]: 0 };
+  }
+
+  /**
+   * Increment the counter for a session
+   * Returns a new clock (immutable)
+   */
+  increment(clock: VectorClock, sessionId: string): VectorClock {
+    const currentValue = clock[sessionId] || 0;
+    return {
+      ...clock,
+      [sessionId]: currentValue + 1,
+    };
+  }
+
+  /**
+   * Merge two vector clocks
+   * Takes the maximum value for each session
+   * Used when receiving remote operations
+   */
+  merge(clock1: VectorClock, clock2: VectorClock): VectorClock {
+    const merged: VectorClock = { ...clock1 };
+
+    Object.entries(clock2).forEach(([sessionId, count]) => {
+      merged[sessionId] = Math.max(merged[sessionId] || 0, count);
+    });
+
+    return merged;
+  }
+
+  /**
+   * Compare two vector clocks
+   *
+   * Returns:
+   *  1 if clock1 > clock2 (clock1 causally after clock2)
+   * -1 if clock1 < clock2 (clock1 causally before clock2)
+   *  0 if concurrent (neither causally precedes the other)
+   */
+  compare(clock1: VectorClock, clock2: VectorClock): number {
+    const allSessionIds = new Set([
+      ...Object.keys(clock1),
+      ...Object.keys(clock2),
+    ]);
+
+    let clock1Greater = false;
+    let clock2Greater = false;
+
+    allSessionIds.forEach((sessionId) => {
+      const val1 = clock1[sessionId] || 0;
+      const val2 = clock2[sessionId] || 0;
+
+      if (val1 > val2) {
+        clock1Greater = true;
+      }
+      if (val2 > val1) {
+        clock2Greater = true;
+      }
+    });
+
+    // If clock1 is greater in all dimensions, it causally follows clock2
+    if (clock1Greater && !clock2Greater) {
+      return 1;
+    }
+
+    // If clock2 is greater in all dimensions, it causally follows clock1
+    if (clock2Greater && !clock1Greater) {
+      return -1;
+    }
+
+    // Otherwise, they are concurrent (or identical)
+    return 0;
+  }
+
+  /**
+   * Check if two operations are concurrent
+   * (neither causally precedes the other)
+   */
+  areConcurrent(clock1: VectorClock, clock2: VectorClock): boolean {
+    return this.compare(clock1, clock2) === 0;
+  }
+}

package/src/state/index.ts

@@ -0,0 +1,14 @@
+/**
+ * State module exports
+ *
+ * - VectorClock: Used by client for causal ordering
+ * - DType, Schema, ConflictResolver: Server-side conflict resolution for concurrent updates
+ */
+
+// Vector clock (used by client and server)
+export { VectorClockManager, type VectorClock } from './VectorClock.js';
+
+// Server-side conflict resolution utilities
+export { DType, type ValueWithMeta, type MergeFn } from './DType.js';
+export { sceneNodeSchema, getPropertySchema, isImmutable, type PropertySchema } from './Schema.js';
+export { ConflictResolver } from './ConflictResolver.js';