@vuer-ai/vuer-rtc 0.0.1

package/src/operations/apply/boolean.ts

@@ -0,0 +1,48 @@
+/**
+ * Boolean operations: set, or, and
+ */
+
+import type { SceneGraph, BooleanSetOp, BooleanOrOp, BooleanAndOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+/**
+ * boolean.set - Last-Write-Wins
+ */
+export function BooleanSet(
+  draft: SceneGraph,
+  op: BooleanSetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, op.value, meta);
+}
+
+/**
+ * boolean.or - Logical OR (enable wins)
+ */
+export function BooleanOr(
+  draft: SceneGraph,
+  op: BooleanOrOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty(node, op.path, false);
+  setNodeProperty(node, op.path, current || op.value, meta);
+}
+
+/**
+ * boolean.and - Logical AND (disable wins)
+ */
+export function BooleanAnd(
+  draft: SceneGraph,
+  op: BooleanAndOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty(node, op.path, true);
+  setNodeProperty(node, op.path, current && op.value, meta);
+}

package/src/operations/apply/color.ts

@@ -0,0 +1,65 @@
+/**
+ * Color operations: set, blend
+ */
+
+import type { SceneGraph, ColorSetOp, ColorBlendOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+/**
+ * color.set - Last-Write-Wins
+ */
+export function ColorSet(
+  draft: SceneGraph,
+  op: ColorSetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, op.value, meta);
+}
+
+/**
+ * Parse hex color to RGB components
+ */
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '');
+  return [
+    parseInt(h.substring(0, 2), 16),
+    parseInt(h.substring(2, 4), 16),
+    parseInt(h.substring(4, 6), 16),
+  ];
+}
+
+/**
+ * Convert RGB to hex color
+ */
+function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (n: number) => Math.round(Math.max(0, Math.min(255, n))).toString(16).padStart(2, '0');
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+/**
+ * color.blend - Average/blend colors
+ */
+export function ColorBlend(
+  draft: SceneGraph,
+  op: ColorBlendOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+
+  const currentHex = getNodeProperty(node, op.path, '#000000');
+  const [r1, g1, b1] = hexToRgb(currentHex);
+  const [r2, g2, b2] = hexToRgb(op.value);
+
+  // Simple average blend
+  const result = rgbToHex(
+    (r1 + r2) / 2,
+    (g1 + g2) / 2,
+    (b1 + b2) / 2
+  );
+
+  setNodeProperty(node, op.path, result, meta);
+}

package/src/operations/apply/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Operation Apply Registry
+ *
+ * Exports all apply functions as a registry.
+ * Usage: import * as registry from './apply/index.js'
+ */
+
+// Types
+export type { OpMeta, ApplyFn } from './types.js';
+export { getNodeProperty, setNodeProperty } from './types.js';
+
+// Number operations
+export { NumberSet, NumberAdd, NumberMultiply, NumberMin, NumberMax } from './number.js';
+
+// String operations
+export { StringSet, StringConcat } from './string.js';
+
+// Boolean operations
+export { BooleanSet, BooleanOr, BooleanAnd } from './boolean.js';
+
+// Vector3 operations
+export { Vector3Set, Vector3Add, Vector3Multiply } from './vector3.js';
+
+// Quaternion operations
+export { QuaternionSet, QuaternionMultiply } from './quaternion.js';
+
+// Color operations
+export { ColorSet, ColorBlend } from './color.js';
+
+// Array operations
+export { ArraySet, ArrayPush, ArrayRemove, ArrayUnion } from './array.js';
+
+// Object operations
+export { ObjectSet, ObjectMerge } from './object.js';
+
+// Node operations
+export { NodeInsert, NodeRemove } from './node.js';

package/src/operations/apply/node.ts

@@ -0,0 +1,98 @@
+/**
+ * Node operations: insert, remove
+ */
+
+import type { SceneGraph, SceneNode, NodeInsertOp, NodeRemoveOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+
+/**
+ * node.insert - Create new node as child of parent
+ *
+ * op.key = parent node's key
+ * op.path = 'children'
+ * op.value.key = new node's key
+ *
+ * Idempotent: if node key exists, no-op
+ */
+export function NodeInsert(
+  draft: SceneGraph,
+  op: NodeInsertOp,
+  meta: OpMeta
+): void {
+  const nodeKey = op.value.key;
+
+  // Idempotent: skip if key already exists
+  if (draft.nodes[nodeKey]) {
+    return;
+  }
+
+  // Extract core fields from value
+  const { key, id, tag, name, ...properties } = op.value;
+
+  // Create new node
+  const newNode: SceneNode = {
+    id,
+    key: nodeKey,
+    tag,
+    name,
+    children: [],
+    clock: { ...meta.clock },
+    lamportTime: meta.lamportTime,
+    createdAt: meta.timestamp,
+    updatedAt: meta.timestamp,
+  };
+
+  // Copy all remaining properties (flat structure with dot-notation)
+  for (const [propKey, propValue] of Object.entries(properties)) {
+    if (propKey === 'children') {
+      newNode.children = Array.isArray(propValue) ? [...propValue] : [];
+    } else {
+      newNode[propKey] = propValue;
+    }
+  }
+
+  // Add to graph
+  draft.nodes[nodeKey] = newNode;
+
+  // Set as root if first node
+  if (!draft.rootKey) {
+    draft.rootKey = nodeKey;
+  }
+
+  // Add to parent's children
+  const parentNode = draft.nodes[op.key];
+  if (parentNode && !parentNode.children.includes(nodeKey)) {
+    parentNode.children.push(nodeKey);
+  }
+}
+
+/**
+ * node.remove - Remove node from parent and soft delete (tombstone)
+ *
+ * op.key = parent node's key
+ * op.path = 'children'
+ * op.value = node key to remove
+ */
+export function NodeRemove(
+  draft: SceneGraph,
+  op: NodeRemoveOp,
+  meta: OpMeta
+): void {
+  const nodeKey = op.value;
+  const node = draft.nodes[nodeKey];
+
+  if (!node) {
+    return; // Node doesn't exist, ignore
+  }
+
+  // Tombstone: mark as deleted
+  node.deletedAt = meta.timestamp;
+  node.lamportTime = meta.lamportTime;
+  node.updatedAt = meta.timestamp;
+
+  // Remove from parent's children
+  const parentNode = draft.nodes[op.key];
+  if (parentNode) {
+    parentNode.children = parentNode.children.filter(childKey => childKey !== nodeKey);
+  }
+}

package/src/operations/apply/number.ts

@@ -0,0 +1,76 @@
+/**
+ * Number operations: set, add, multiply, min, max
+ */
+
+import type { SceneGraph, NumberSetOp, NumberAddOp, NumberMultiplyOp, NumberMinOp, NumberMaxOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+/**
+ * number.set - Last-Write-Wins
+ */
+export function NumberSet(
+  draft: SceneGraph,
+  op: NumberSetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, op.value, meta);
+}
+
+/**
+ * number.add - Additive (sum concurrent values)
+ */
+export function NumberAdd(
+  draft: SceneGraph,
+  op: NumberAddOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty(node, op.path, 0);
+  setNodeProperty(node, op.path, current + op.value, meta);
+}
+
+/**
+ * number.multiply - Multiplicative (product of concurrent values)
+ */
+export function NumberMultiply(
+  draft: SceneGraph,
+  op: NumberMultiplyOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty(node, op.path, 1);
+  setNodeProperty(node, op.path, current * op.value, meta);
+}
+
+/**
+ * number.min - Take minimum value
+ */
+export function NumberMin(
+  draft: SceneGraph,
+  op: NumberMinOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty(node, op.path, Infinity);
+  setNodeProperty(node, op.path, Math.min(current, op.value), meta);
+}
+
+/**
+ * number.max - Take maximum value
+ */
+export function NumberMax(
+  draft: SceneGraph,
+  op: NumberMaxOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty(node, op.path, -Infinity);
+  setNodeProperty(node, op.path, Math.max(current, op.value), meta);
+}

package/src/operations/apply/object.ts

@@ -0,0 +1,63 @@
+/**
+ * Object operations: set, merge
+ */
+
+import type { SceneGraph, ObjectSetOp, ObjectMergeOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+/**
+ * object.set - Last-Write-Wins (replace entire object)
+ */
+export function ObjectSet(
+  draft: SceneGraph,
+  op: ObjectSetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, { ...op.value }, meta);
+}
+
+/**
+ * Deep merge helper
+ */
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = result[key];
+
+    if (
+      sourceVal !== null &&
+      typeof sourceVal === 'object' &&
+      !Array.isArray(sourceVal) &&
+      targetVal !== null &&
+      typeof targetVal === 'object' &&
+      !Array.isArray(targetVal)
+    ) {
+      result[key] = deepMerge(
+        targetVal as Record<string, unknown>,
+        sourceVal as Record<string, unknown>
+      );
+    } else {
+      result[key] = sourceVal;
+    }
+  }
+  return result;
+}
+
+/**
+ * object.merge - Deep merge objects
+ */
+export function ObjectMerge(
+  draft: SceneGraph,
+  op: ObjectMergeOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty<Record<string, unknown>>(node, op.path, {});
+  const merged = deepMerge(current, op.value);
+  setNodeProperty(node, op.path, merged, meta);
+}

package/src/operations/apply/quaternion.ts

@@ -0,0 +1,47 @@
+/**
+ * Quaternion operations: set, multiply
+ */
+
+import type { SceneGraph, QuaternionSetOp, QuaternionMultiplyOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+type Quaternion = [number, number, number, number];
+
+/**
+ * quaternion.set - Last-Write-Wins
+ */
+export function QuaternionSet(
+  draft: SceneGraph,
+  op: QuaternionSetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, [...op.value] as Quaternion, meta);
+}
+
+/**
+ * quaternion.multiply - Quaternion multiplication (composition)
+ * Result = current * op.value (Hamilton product)
+ */
+export function QuaternionMultiply(
+  draft: SceneGraph,
+  op: QuaternionMultiplyOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const [ax, ay, az, aw] = getNodeProperty<Quaternion>(node, op.path, [0, 0, 0, 1]);
+  const [bx, by, bz, bw] = op.value;
+
+  // Hamilton product: a * b
+  const result: Quaternion = [
+    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,
+  ];
+
+  setNodeProperty(node, op.path, result, meta);
+}

package/src/operations/apply/string.ts

@@ -0,0 +1,36 @@
+/**
+ * String operations: set, concat
+ */
+
+import type { SceneGraph, StringSetOp, StringConcatOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+/**
+ * string.set - Last-Write-Wins
+ */
+export function StringSet(
+  draft: SceneGraph,
+  op: StringSetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, op.value, meta);
+}
+
+/**
+ * string.concat - Concatenate (append)
+ */
+export function StringConcat(
+  draft: SceneGraph,
+  op: StringConcatOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty(node, op.path, '');
+  const separator = op.separator ?? '';
+  const newValue = current ? `${current}${separator}${op.value}` : op.value;
+  setNodeProperty(node, op.path, newValue, meta);
+}

package/src/operations/apply/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared types for apply functions
+ */
+
+import type { VectorClock } from '../../state/VectorClock.js';
+import type { SceneGraph, SceneNode } from '../OperationTypes.js';
+
+/**
+ * Operation metadata from the CRDTMessage envelope
+ */
+export interface OpMeta {
+  sessionId: string;
+  clock: VectorClock;
+  lamportTime: number;
+  timestamp: number;
+}
+
+/**
+ * Apply function signature - mutates draft in place (immer)
+ */
+export type ApplyFn<TOp> = (
+  draft: SceneGraph,
+  op: TOp,
+  meta: OpMeta
+) => void;
+
+/**
+ * Helper to get or initialize a node property with a default value
+ */
+export function getNodeProperty<T>(node: SceneNode, path: string, defaultValue: T): T {
+  const value = node[path as keyof SceneNode];
+  return value !== undefined ? (value as T) : defaultValue;
+}
+
+/**
+ * Helper to set a node property (for additive operations)
+ * Does NOT update lamportTime - only LWW operations should do that
+ */
+export function setNodeProperty(
+  node: SceneNode,
+  path: string,
+  value: unknown,
+  meta: OpMeta
+): void {
+  node[path] = value;
+  node.updatedAt = meta.timestamp;
+}
+
+/**
+ * Helper to set a node property with LWW semantics
+ * Only updates if incoming lamportTime >= current lamportTime
+ * (>= allows multiple ops in the same message to apply)
+ */
+export function setNodePropertyLWW(
+  node: SceneNode,
+  path: string,
+  value: unknown,
+  meta: OpMeta
+): void {
+  // LWW: only update if incoming lamport time is higher or equal
+  if (meta.lamportTime >= node.lamportTime) {
+    node[path] = value;
+    node.lamportTime = meta.lamportTime;
+    node.updatedAt = meta.timestamp;
+  }
+}

package/src/operations/apply/vector3.ts

@@ -0,0 +1,60 @@
+/**
+ * Vector3 operations: set, add, multiply
+ */
+
+import type { SceneGraph, Vector3SetOp, Vector3AddOp, Vector3MultiplyOp } from '../OperationTypes.js';
+import type { OpMeta } from './types.js';
+import { getNodeProperty, setNodeProperty, setNodePropertyLWW } from './types.js';
+
+type Vector3 = [number, number, number];
+
+/**
+ * vector3.set - Last-Write-Wins
+ */
+export function Vector3Set(
+  draft: SceneGraph,
+  op: Vector3SetOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  setNodePropertyLWW(node, op.path, [...op.value] as Vector3, meta);
+}
+
+/**
+ * vector3.add - Component-wise addition (additive deltas)
+ */
+export function Vector3Add(
+  draft: SceneGraph,
+  op: Vector3AddOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty<Vector3>(node, op.path, [0, 0, 0]);
+  const result: Vector3 = [
+    current[0] + op.value[0],
+    current[1] + op.value[1],
+    current[2] + op.value[2],
+  ];
+  setNodeProperty(node, op.path, result, meta);
+}
+
+/**
+ * vector3.multiply - Component-wise multiplication (scale)
+ */
+export function Vector3Multiply(
+  draft: SceneGraph,
+  op: Vector3MultiplyOp,
+  meta: OpMeta
+): void {
+  const node = draft.nodes[op.key];
+  if (!node || node.deletedAt) return;
+  const current = getNodeProperty<Vector3>(node, op.path, [1, 1, 1]);
+  const result: Vector3 = [
+    current[0] * op.value[0],
+    current[1] * op.value[1],
+    current[2] * op.value[2],
+  ];
+  setNodeProperty(node, op.path, result, meta);
+}