@vuer-ai/vuer-rtc 0.7.0 → 0.8.2

package/src/operations/OperationTypes.ts

@@ -15,10 +15,10 @@ import type { VectorClock } from '../state/VectorClock.js';
 export interface CRDTMessage {
   // === CRDT Metadata (wrapper) ===
   id: string;              // Message ID (UUID)
-  sessionId: string;       // Session that created this message
+  client: 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 (seconds since epoch)
+  lt: number;              // Lamport timestamp for total ordering
+  ts: number;              // Wall-clock time (seconds since epoch)
 
   // === Operations (batch) ===
   ops: Operation[];        // One or more operations
@@ -29,7 +29,7 @@ export interface CRDTMessage {
  */
 export interface BaseOp {
   key: string;     // Node key (human-friendly, e.g., 'cube-1', 'player', 'scene')
-  otype: string;   // dtype operation: 'number.set', 'vector3.add', etc.
+  ot: string;   // dtype operation: 'number.set', 'vector3.add', etc.
   path: string;    // Property path: 'color', 'transform.position', etc.
 }
 
@@ -39,35 +39,35 @@ export interface BaseOp {
 
 export interface NumberSetOp extends BaseOp {
   key: string;
-  otype: 'number.set';
+  ot: 'number.set';
   path: string;
   value: number;
 }
 
 export interface NumberAddOp extends BaseOp {
   key: string;
-  otype: 'number.add';
+  ot: 'number.add';
   path: string;
   value: number;
 }
 
 export interface NumberMultiplyOp extends BaseOp {
   key: string;
-  otype: 'number.multiply';
+  ot: 'number.multiply';
   path: string;
   value: number;
 }
 
 export interface NumberMinOp extends BaseOp {
   key: string;
-  otype: 'number.min';
+  ot: 'number.min';
   path: string;
   value: number;
 }
 
 export interface NumberMaxOp extends BaseOp {
   key: string;
-  otype: 'number.max';
+  ot: 'number.max';
   path: string;
   value: number;
 }
@@ -78,14 +78,14 @@ export interface NumberMaxOp extends BaseOp {
 
 export interface StringSetOp extends BaseOp {
   key: string;
-  otype: 'string.set';
+  ot: 'string.set';
   path: string;
   value: string;
 }
 
 export interface StringConcatOp extends BaseOp {
   key: string;
-  otype: 'string.concat';
+  ot: 'string.concat';
   path: string;
   value: string;
   separator?: string;
@@ -101,7 +101,7 @@ export interface StringConcatOp extends BaseOp {
  */
 export interface TextInitOp extends BaseOp {
   key: string;
-  otype: 'text.init';
+  ot: 'text.init';
   path: string;
   value?: string;  // Optional initial content
 }
@@ -113,7 +113,7 @@ export interface TextInitOp extends BaseOp {
  */
 export interface TextInsertOp extends BaseOp {
   key: string;
-  otype: 'text.insert';
+  ot: 'text.insert';
   path: string;
   // Position-based format (local convenience)
   position?: number;
@@ -133,13 +133,13 @@ export interface TextInsertOp extends BaseOp {
  */
 export interface TextDeleteOp extends BaseOp {
   key: string;
-  otype: 'text.delete';
+  ot: 'text.delete';
   path: string;
   // Position-based format (local convenience)
   position?: number;
   length?: number;
-  // CRDT metadata format (network sync)
-  deletions?: Array<{ id: string; length: number }>;  // ItemId string format
+  // CRDT metadata format (network sync) - compressed tuple format
+  deletions?: Array<[string, number]>;  // [[itemId, length], ...]
 }
 
 /**
@@ -149,7 +149,7 @@ export interface TextDeleteOp extends BaseOp {
  */
 export interface TextReplaceOp extends BaseOp {
   key: string;
-  otype: 'text.replace';
+  ot: 'text.replace';
   path: string;
   // Position-based format (local convenience)
   position?: number;
@@ -170,21 +170,21 @@ export interface TextReplaceOp extends BaseOp {
 
 export interface BooleanSetOp extends BaseOp {
   key: string;
-  otype: 'boolean.set';
+  ot: 'boolean.set';
   path: string;
   value: boolean;
 }
 
 export interface BooleanOrOp extends BaseOp {
   key: string;
-  otype: 'boolean.or';
+  ot: 'boolean.or';
   path: string;
   value: boolean;
 }
 
 export interface BooleanAndOp extends BaseOp {
   key: string;
-  otype: 'boolean.and';
+  ot: 'boolean.and';
   path: string;
   value: boolean;
 }
@@ -195,21 +195,21 @@ export interface BooleanAndOp extends BaseOp {
 
 export interface Vector3SetOp extends BaseOp {
   key: string;
-  otype: 'vector3.set';
+  ot: 'vector3.set';
   path: string;
   value: [number, number, number];
 }
 
 export interface Vector3AddOp extends BaseOp {
   key: string;
-  otype: 'vector3.add';
+  ot: 'vector3.add';
   path: string;
   value: [number, number, number];
 }
 
 export interface Vector3MultiplyOp extends BaseOp {
   key: string;
-  otype: 'vector3.multiply';
+  ot: 'vector3.multiply';
   path: string;
   value: [number, number, number];
 }
@@ -232,15 +232,15 @@ export type EulerOrder = 'XYZ' | 'XZY' | 'YXZ' | 'YZX' | 'ZXY' | 'ZYX';
  *
  * @example
  * // Intrinsic XYZ rotation (default): rotate around body's X, then Y, then Z
- * { otype: 'vector3.applyEuler', key: 'arm', path: 'direction', value: [0, Math.PI/2, 0] }
+ * { ot: 'vector3.applyEuler', key: 'arm', path: 'direction', value: [0, Math.PI/2, 0] }
  *
  * // Extrinsic XYZ rotation: rotate around fixed X, then Y, then Z
  * // Note: Extrinsic XYZ is equivalent to Intrinsic ZYX
- * { otype: 'vector3.applyEuler', key: 'arm', path: 'direction', value: [0, Math.PI/2, 0], intrinsic: false }
+ * { ot: 'vector3.applyEuler', key: 'arm', path: 'direction', value: [0, Math.PI/2, 0], intrinsic: false }
  */
 export interface Vector3ApplyEulerOp extends BaseOp {
   key: string;
-  otype: 'vector3.applyEuler';
+  ot: 'vector3.applyEuler';
   path: string;
   value: [number, number, number];
   order?: EulerOrder;
@@ -249,7 +249,7 @@ export interface Vector3ApplyEulerOp extends BaseOp {
 
 export interface Vector3ApplyQuaternionOp extends BaseOp {
   key: string;
-  otype: 'vector3.applyQuaternion';
+  ot: 'vector3.applyQuaternion';
   path: string;
   value: [number, number, number, number];  // [x, y, z, w]
 }
@@ -260,14 +260,14 @@ export interface Vector3ApplyQuaternionOp extends BaseOp {
 
 export interface EulerSetOp extends BaseOp {
   key: string;
-  otype: 'euler.set';
+  ot: 'euler.set';
   path: string;
   value: [number, number, number];  // [x, y, z] in radians
 }
 
 export interface EulerAddOp extends BaseOp {
   key: string;
-  otype: 'euler.add';
+  ot: 'euler.add';
   path: string;
   value: [number, number, number];  // [x, y, z] in radians
 }
@@ -278,14 +278,14 @@ export interface EulerAddOp extends BaseOp {
 
 export interface QuaternionSetOp extends BaseOp {
   key: string;
-  otype: 'quaternion.set';
+  ot: 'quaternion.set';
   path: string;
   value: [number, number, number, number];
 }
 
 export interface QuaternionMultiplyOp extends BaseOp {
   key: string;
-  otype: 'quaternion.multiply';
+  ot: 'quaternion.multiply';
   path: string;
   value: [number, number, number, number];
 }
@@ -296,14 +296,14 @@ export interface QuaternionMultiplyOp extends BaseOp {
 
 export interface ColorSetOp extends BaseOp {
   key: string;
-  otype: 'color.set';
+  ot: 'color.set';
   path: string;
   value: string;  // Hex color
 }
 
 export interface ColorBlendOp extends BaseOp {
   key: string;
-  otype: 'color.blend';
+  ot: 'color.blend';
   path: string;
   value: string;
 }
@@ -314,28 +314,28 @@ export interface ColorBlendOp extends BaseOp {
 
 export interface ArraySetOp extends BaseOp {
   key: string;
-  otype: 'array.set';
+  ot: 'array.set';
   path: string;
   value: any[];
 }
 
 export interface ArrayPushOp extends BaseOp {
   key: string;
-  otype: 'array.push';
+  ot: 'array.push';
   path: string;
   value: any;
 }
 
 export interface ArrayUnionOp extends BaseOp {
   key: string;
-  otype: 'array.union';
+  ot: 'array.union';
   path: string;
   value: any[];
 }
 
 export interface ArrayRemoveOp extends BaseOp {
   key: string;
-  otype: 'array.remove';
+  ot: 'array.remove';
   path: string;
   value: any;
 }
@@ -346,14 +346,14 @@ export interface ArrayRemoveOp extends BaseOp {
 
 export interface ObjectSetOp extends BaseOp {
   key: string;
-  otype: 'object.set';
+  ot: 'object.set';
   path: string;
   value: Record<string, any>;
 }
 
 export interface ObjectMergeOp extends BaseOp {
   key: string;
-  otype: 'object.merge';
+  ot: 'object.merge';
   path: string;
   value: Record<string, any>;
 }
@@ -367,7 +367,7 @@ export interface ObjectMergeOp extends BaseOp {
  */
 export interface NodeInsertOp extends BaseOp {
   key: string;     // Parent node's key
-  otype: 'node.insert';
+  ot: 'node.insert';
   path: 'children';
   value: {
     key: string;   // New node's key (also used as id)
@@ -382,7 +382,7 @@ export interface NodeInsertOp extends BaseOp {
  */
 export interface NodeRemoveOp extends BaseOp {
   key: string;     // Parent node's key
-  otype: 'node.remove';
+  ot: 'node.remove';
   path: 'children';
   value: string;   // Node key to remove
 }
@@ -392,7 +392,7 @@ export interface NodeRemoveOp extends BaseOp {
  */
 export interface NodeMoveOp extends BaseOp {
   key: string;     // Old parent node's key
-  otype: 'node.move';
+  ot: 'node.move';
   path: 'children';
   value: {
     nodeKey: string;    // Node key to move
@@ -409,7 +409,7 @@ export interface NodeMoveOp extends BaseOp {
  */
 export interface MetaUndoOp {
   key: '_meta';
-  otype: 'meta.undo';
+  ot: 'meta.undo';
   path: '_meta';
   targetMsgId: string;  // Message ID to undo
 }
@@ -419,7 +419,7 @@ export interface MetaUndoOp {
  */
 export interface MetaRedoOp {
   key: '_meta';
-  otype: 'meta.redo';
+  ot: 'meta.redo';
   path: '_meta';
   targetMsgId: string;  // Message ID to redo
 }
@@ -450,8 +450,8 @@ export type Operation =
  * Per-property LWW metadata
  */
 export interface PropertyLWW {
-  lamportTime: number;
-  sessionId: string;
+  lt: number;
+  client: string;
 }
 
 /**
@@ -484,6 +484,6 @@ export interface SceneNode {
 export interface SceneGraph {
   nodes: Record<string, SceneNode>;     // Flattened map by key
   rootKey: string;                       // Root node key
-  lww: Record<string, PropertyLWW>;      // Global LWW map: "nodeKey.path" → {lamportTime, sessionId}
+  lww: Record<string, PropertyLWW>;      // Global LWW map: "nodeKey.path" → {lamportTime, client}
   tombstones: Record<string, number>;    // Deleted nodes: nodeKey → deletedAt timestamp
 }

package/src/operations/OperationValidator.ts

@@ -25,20 +25,20 @@ export class OperationValidator {
       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.client || typeof msg.client !== 'string') {
+      errors.push('client 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.lt !== 'number') {
+      errors.push('lt must be a number');
     }
 
-    if (typeof msg.timestamp !== 'number') {
-      errors.push('timestamp must be a number');
+    if (typeof msg.ts !== 'number') {
+      errors.push('ts must be a number');
     }
 
     if (!Array.isArray(msg.ops)) {
@@ -72,17 +72,17 @@ export class OperationValidator {
       errors.push('key must be a string');
     }
 
-    if (!op.otype || typeof op.otype !== 'string') {
-      errors.push('otype is required and must be a string');
+    if (!op.ot || typeof op.ot !== 'string') {
+      errors.push('ot 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('.');
+    // Validate based on ot
+    if (op.ot) {
+      const [dtype, operation] = op.ot.split('.');
 
       switch (dtype) {
         case 'number':

package/src/operations/apply/node.ts

@@ -50,8 +50,8 @@ export function NodeInsert(
       // Register in LWW map
       const lwwKey = `${nodeKey}.${propKey}`;
       draft.lww[lwwKey] = {
-        lamportTime: meta.lamportTime,
-        sessionId: meta.sessionId,
+        lt: meta.lt,
+        client: meta.client,
       };
     }
   }
@@ -89,7 +89,7 @@ export function NodeRemove(
   }
 
   // Tombstone: mark as deleted at root level
-  draft.tombstones[nodeKey] = meta.timestamp;
+  draft.tombstones[nodeKey] = meta.ts;
 
   // Remove from parent's children
   const parentNode = draft.nodes[op.key];

package/src/operations/apply/text.ts

@@ -101,7 +101,7 @@ export function TextInit(
   const node = draft.nodes[op.key];
   if (!node) return;
 
-  const rope = getOrCreateRope(node, op.path, meta.sessionId);
+  const rope = getOrCreateRope(node, op.path, meta.client);
 
   if (op.value && op.value.length > 0) {
     insert(rope, 0, op.value);
@@ -121,25 +121,26 @@ export function TextInsert(
   const node = draft.nodes[op.key];
   if (!node) return;
 
-  const rope = getOrCreateRope(node, op.path, meta.sessionId);
+  const rope = getOrCreateRope(node, op.path, meta.client);
 
-  if (op.id !== undefined && op.content !== undefined && op.seq !== undefined) {
+  const value = (op as any).value;
+
+  if (op.id !== undefined && value !== undefined && op.seq !== undefined) {
     // CRDT metadata format (replay from journal)
+    // Value is already [anchor, content] tuple
     apply(rope, {
-      otype: 'insert',
+      ot: 'insert',
       id: op.id,
-      content: op.content,
-      parentId: op.parentId ?? null,
+      value,  // Pass tuple as-is
       seq: op.seq,
       ts: op.ts ?? Date.now() / 1000,
     });
   } else if (op.position !== undefined && op.value !== undefined) {
     // Position-based format (local edit) → convert to CRDT metadata in-place
-    // so the op is order-independent when replayed from a different journal order.
-    const crdtOp = insertWithSplit(rope, op.position, op.value, meta.sessionId);
+    const crdtOp = insertWithSplit(rope, op.position, op.value, meta.client);
     op.id = crdtOp.id;
-    op.content = crdtOp.content;
-    op.parentId = crdtOp.parentId;
+    // Pack tuple: [anchor, content] - crdtOp.value is already [anchor, content]
+    (op as any).value = crdtOp.value;
     op.seq = crdtOp.seq;
     op.ts = crdtOp.ts;
   }
@@ -161,13 +162,17 @@ export function TextDelete(
   const rope = getRope(node, op.path);
   if (!rope) return;
 
-  if (op.deletions !== undefined) {
+  const deletionsArray = (op as any).rm;
+
+  if (deletionsArray !== undefined) {
     // CRDT metadata format (replay from journal)
-    applyDelete(rope, { otype: 'delete', deletions: op.deletions });
+    // rm is already in tuple format: [[id, len], ...]
+    applyDelete(rope, { ot: 'delete', rm: deletionsArray });
   } else if (op.position !== undefined && op.length !== undefined) {
     // Position-based format (local edit) → convert to CRDT metadata in-place
     const crdtOp = remove(rope, op.position, op.length);
-    op.deletions = crdtOp.deletions;
+    // rm is already in tuple format from remove()
+    (op as any).rm = crdtOp.rm;
   }
 
   // node[path] is the mutated TextRope
@@ -184,31 +189,32 @@ export function TextReplace(
   const node = draft.nodes[op.key];
   if (!node) return;
 
-  const rope = getOrCreateRope(node, op.path, meta.sessionId);
+  const rope = getOrCreateRope(node, op.path, meta.client);
+
+  const deletionsArray = (op as any).rm;
+  const value = (op as any).value;
 
-  if (op.deletions !== undefined && op.id !== undefined && op.seq !== undefined) {
+  if (deletionsArray !== undefined && op.id !== undefined && op.seq !== undefined) {
     // CRDT metadata format (replay from journal)
+    // Value is already [anchor, content] tuple
     applyReplace(rope, {
-      otype: 'replace',
-      delete: { otype: 'delete', deletions: op.deletions },
-      insert: {
-        otype: 'insert',
-        id: op.id,
-        content: op.content ?? '',
-        parentId: op.parentId ?? null,
-        seq: op.seq,
-        ts: op.ts ?? Date.now() / 1000,
-      },
+      ot: 'replace',
+      rm: deletionsArray,
+      id: op.id,
+      value: value ?? [null, ''],  // Pass tuple as-is
+      seq: op.seq,
+      ts: op.ts ?? Date.now() / 1000,
     });
   } else if (op.position !== undefined && op.length !== undefined && op.value !== undefined) {
     // Position-based format (local edit) → convert to CRDT metadata in-place
-    const crdtOp = replace(rope, op.position, op.length, op.value, meta.sessionId);
-    op.deletions = crdtOp.delete.deletions;
-    op.id = crdtOp.insert.id;
-    op.content = crdtOp.insert.content;
-    op.parentId = crdtOp.insert.parentId;
-    op.seq = crdtOp.insert.seq;
-    op.ts = crdtOp.insert.ts;
+    const crdtOp = replace(rope, op.position, op.length, op.value, meta.client);
+    // rm is already in tuple format from replace()
+    (op as any).rm = crdtOp.rm;
+    op.id = crdtOp.id;
+    // Pack tuple: [anchor, content] - crdtOp.value is already [anchor, content]
+    (op as any).value = crdtOp.value;
+    op.seq = crdtOp.seq;
+    op.ts = crdtOp.ts;
   }
 
   // node[path] is the mutated TextRope

package/src/operations/apply/types.ts

@@ -9,10 +9,10 @@ import type { SceneGraph, SceneNode } from '../OperationTypes.js';
  * Operation metadata from the CRDTMessage envelope
  */
 export interface OpMeta {
-  sessionId: string;
+  client: string;
   clock: VectorClock;
-  lamportTime: number;
-  timestamp: number;
+  lt: number;
+  ts: number;
 }
 
 /**
@@ -59,8 +59,8 @@ function getLWW(graph: SceneGraph, nodeKey: string, path: string): PropertyLWW |
 function setLWW(graph: SceneGraph, nodeKey: string, path: string, meta: OpMeta): void {
   const key = `${nodeKey}.${path}`;
   graph.lww[key] = {
-    lamportTime: meta.lamportTime,
-    sessionId: meta.sessionId,
+    lt: meta.lt,
+    client: meta.client,
   };
 }
 
@@ -69,7 +69,7 @@ function setLWW(graph: SceneGraph, nodeKey: string, path: string, meta: OpMeta):
  *
  * Resolution is **per-property**: concurrent writes to different paths
  * on the same node never conflict. For two writes to the same path,
- * higher lamportTime wins. On tie, higher sessionId wins (lexicographic).
+ * higher lamportTime wins. On tie, higher client ID wins (lexicographic).
  * This ensures deterministic conflict resolution regardless of
  * message arrival order.
  */
@@ -89,16 +89,16 @@ export function setNodePropertyLWW(
     return;
   }
 
-  if (meta.lamportTime > current.lamportTime) {
+  if (meta.lt > current.lt) {
     // Strictly higher — always wins
     node[path] = value;
     setLWW(graph, node.key, path, meta);
-  } else if (meta.lamportTime === current.lamportTime) {
-    // Tie: higher sessionId wins, or same session (last-write-wins within message)
-    if (meta.sessionId >= current.sessionId) {
+  } else if (meta.lt === current.lt) {
+    // Tie: higher client wins, or same client (last-write-wins within message)
+    if (meta.client >= current.client) {
       node[path] = value;
       setLWW(graph, node.key, path, meta);
     }
   }
-  // meta.lamportTime < current.lamportTime → skip (stale write)
+  // meta.lt < current.lt → skip (stale write)
 }