@vuer-ai/vuer-rtc 0.7.0 → 0.8.2

package/src/client/coalescence/textDeletes.ts

@@ -4,14 +4,18 @@
  * Merges consecutive text delete operations.
  */
 
-import type { Operation } from '../../operations/OperationTypes.js';
 import { optimizeDeletions, parseItemId } from './utils.js';
 
+/**
+ * Text delete operation for graph coalescence.
+ * This is the wire format for text.delete operations (with key/path context).
+ * Uses compressed schema with tuple-based fields.
+ */
 export interface TextDeleteOp {
-  otype: 'text.delete';
-  key: string;
-  path: string;
-  deletions: Array<{ id: string; length: number }>; // Array of deletion ranges
+  ot: 'text.delete'; // Graph operation type
+  key: string; // Node key
+  path: string; // Property path
+  rm: Array<[string, number]>; // [[id, length], ...]
   // NOTE: TextDeleteOp does NOT have seq/ts fields (those are only on TextInsertOp)
   // Time-based coalescence is not available for delete operations
 }
@@ -25,13 +29,13 @@ export interface CoalesceOptions {
  * Sort and optimize deletions array.
  * Deletions must be sorted in ascending order for optimizeDeletions to work correctly.
  */
-function sortAndOptimizeDeletions(deletions: Array<{ id: string; length: number }>): Array<{ id: string; length: number }> {
+function sortAndOptimizeDeletions(deletions: Array<[string, number]>): Array<[string, number]> {
   if (deletions.length === 0) return deletions;
 
   // Sort deletions by agent, then by sequence number (ascending)
   const sorted = [...deletions].sort((a, b) => {
-    const aId = parseItemId(a.id);
-    const bId = parseItemId(b.id);
+    const aId = parseItemId(a[0]); // id is at [0]
+    const bId = parseItemId(b[0]); // id is at [0]
     if (aId.agent !== bId.agent) {
       return aId.agent.localeCompare(bId.agent);
     }
@@ -44,11 +48,11 @@ function sortAndOptimizeDeletions(deletions: Array<{ id: string; length: number
 /**
  * Check if an operation is a text delete with CRDT metadata
  */
-export function isTextDeleteOp(op: Operation): op is TextDeleteOp {
+export function isTextDeleteOp(op: any): op is TextDeleteOp {
   return (
-    op.otype === 'text.delete' &&
-    Array.isArray((op as any).deletions) &&
-    (op as any).deletions.length > 0
+    op.ot === 'text.delete' &&
+    Array.isArray(op.rm) &&
+    op.rm.length > 0
   );
 }
 
@@ -77,7 +81,7 @@ export function coalesceTextDeletes(
   for (const op of ops) {
     if (pending === null) {
       // Start new pending delete
-      pending = { ...op, deletions: [...op.deletions] };
+      pending = { ...op, rm: [...op.rm] };
     } else {
       // Check merge conditions
       const sameTarget = pending.key === op.key && pending.path === op.path;
@@ -87,16 +91,16 @@ export function coalesceTextDeletes(
       if (sameTarget) {
         // Merge operations - combine deletion lists
         const merged: TextDeleteOp = {
-          otype: 'text.delete',
+          ot: 'text.delete',
           key: pending.key,
           path: pending.path,
-          deletions: [...pending.deletions, ...op.deletions],
+          rm: [...pending.rm, ...op.rm],
         };
         pending = merged;
       } else {
         // Can't merge - flush pending and start new
         result.push(pending);
-        pending = { ...op, deletions: [...op.deletions] };
+        pending = { ...op, rm: [...op.rm] };
       }
     }
   }
@@ -104,13 +108,13 @@ export function coalesceTextDeletes(
   // Flush any remaining pending delete
   if (pending !== null) {
     // Sort and optimize deletions array before pushing
-    pending.deletions = sortAndOptimizeDeletions(pending.deletions);
+    pending.rm = sortAndOptimizeDeletions(pending.rm);
     result.push(pending);
   }
 
   // Also sort and optimize deletions in all previously pushed operations
   for (const op of result) {
-    op.deletions = sortAndOptimizeDeletions(op.deletions);
+    op.rm = sortAndOptimizeDeletions(op.rm);
   }
 
   return result;

package/src/client/coalescence/textInserts.ts

@@ -12,18 +12,38 @@
  * 5. Compatible YATA structure (forms a chain)
  */
 
-import type { Operation } from '../../operations/OperationTypes.js';
 import { parseItemId } from '../../crdt/Rope.js';
 
+/**
+ * Text insert operation for graph coalescence.
+ * This is the wire format for text.insert operations (with key/path context).
+ * Uses compressed schema with tuple-based fields.
+ */
 export interface TextInsertOp {
-  otype: 'text.insert';
-  key: string;
-  path: string;
-  id: string;
-  content: string;
-  parentId: string | null;
-  seq: number;
-  ts: number;
+  ot: 'text.insert'; // Graph operation type
+  key: string; // Node key
+  path: string; // Property path
+  id: string; // CRDT item ID
+  value: [string | null, string]; // [anchor, content]
+  seq: number; // Lamport timestamp
+  ts: number; // Wall-clock time
+}
+
+/**
+ * Calculate the last character ID for an insert operation.
+ * If the operation has _lastCharId metadata, use it. Otherwise calculate from id + content length.
+ */
+function getLastCharId(op: TextInsertOp): string {
+  // Check if operation has _lastCharId metadata (from previous coalescence)
+  const lastCharId = (op as any)._lastCharId;
+  if (lastCharId) return lastCharId;
+
+  // Calculate from id + content length
+  const content = op.value[1];
+  if (content.length === 0) return op.id;
+
+  const parsed = parseItemId(op.id);
+  return `${parsed.agent}:${parsed.seq + content.length - 1}`;
 }
 
 export interface CoalesceOptions {
@@ -34,13 +54,14 @@ export interface CoalesceOptions {
 /**
  * Check if an operation is a text insert with CRDT metadata
  */
-export function isTextInsertOp(op: Operation): op is TextInsertOp {
+export function isTextInsertOp(op: any): op is TextInsertOp {
   return (
-    op.otype === 'text.insert' &&
-    typeof (op as any).id === 'string' &&
-    typeof (op as any).content === 'string' &&
-    typeof (op as any).seq === 'number' &&
-    typeof (op as any).ts === 'number'
+    op.ot === 'text.insert' &&
+    typeof op.id === 'string' &&
+    Array.isArray(op.value) &&
+    op.value.length === 2 &&
+    typeof op.seq === 'number' &&
+    typeof op.ts === 'number'
   );
 }
 
@@ -79,9 +100,10 @@ export function coalesceTextInserts(
       const sameAgent = prevId.agent === currId.agent;
       const sameTarget = pending.key === op.key && pending.path === op.path;
 
-      // IDs must be sequential: next ID = prev ID + prev content length
-      // Example: prev="alice:5" content="hel"(3 chars) → next="alice:8"
-      const sequentialIds = currId.seq === prevId.seq + pending.content.length;
+      // IDs must be sequential: next ID = prev ID + prev value/content length
+      // Example: prev="alice:5" value="hel"(3 chars) → next="alice:8"
+      const pendingContent = pending.value[1]; // content is value[1]
+      const sequentialIds = currId.seq === prevId.seq + pendingContent.length;
 
       // Time threshold: operations must be close in time (ts is in seconds)
       const timeDiffMs = (op.ts - pending.ts) * 1000;
@@ -91,24 +113,26 @@ export function coalesceTextInserts(
       // Current op's parent should be the last character ID in the merged content
       // (not the first ID, which is what pending.id contains after merging)
       // OR both should have the same parent (inserting at same position)
-      const prevLastId = (pending as any)._lastCharId || pending.id;
+      const prevLastId = getLastCharId(pending);
+      const opAnchor = op.value[0]; // anchor is value[0] (can be null)
+      const pendingAnchor = pending.value[0]; // anchor is value[0] (can be null)
       const formsChain =
-        op.parentId === prevLastId ||
-        (pending.parentId === op.parentId && pending.parentId !== null);
+        opAnchor === prevLastId ||
+        (pendingAnchor === opAnchor && pendingAnchor !== null);
 
       if (sameAgent && sameTarget && sequentialIds && withinThreshold && formsChain) {
         // Merge operations
+        const opContent = op.value[1]; // content is value[1]
         const merged: TextInsertOp = {
-          otype: 'text.insert',
+          ot: 'text.insert',
           key: pending.key,
           path: pending.path,
           id: pending.id, // Keep first ID (anchor point)
-          content: pending.content + op.content, // Concatenate content
-          parentId: pending.parentId, // Keep first parentId
+          value: [pendingAnchor, pendingContent + opContent], // [anchor, merged content]
           seq: Math.max(pending.seq, op.seq), // Use max Lamport clock for ordering
           ts: pending.ts, // Keep first timestamp (when sequence started)
           // Track the last character ID for chain validation in next merge
-          _lastCharId: op.id,
+          _lastCharId: getLastCharId(op),
         } as any;
         pending = merged;
       } else {

package/src/client/coalescence/utils.ts

@@ -23,33 +23,36 @@ export function parseItemId(id: ItemId): { agent: string; seq: number } {
  * Optimize a deletions array by merging consecutive deletions from the same agent.
  *
  * Example:
- *   Input:  [{id: "alice:1", length: 1}, {id: "alice:2", length: 1}, {id: "alice:3", length: 1}]
- *   Output: [{id: "alice:1", length: 3}]
+ *   Input:  [["alice:1", 1], ["alice:2", 1], ["alice:3", 1]]
+ *   Output: [["alice:1", 3]]
  *
  * This reduces the size of deletion arrays when consecutive items are deleted.
  */
 export function optimizeDeletions(
-  deletions: Array<{ id: ItemId; length: number }>
-): Array<{ id: ItemId; length: number }> {
+  deletions: Array<[ItemId, number]>
+): Array<[ItemId, number]> {
   if (deletions.length === 0) return deletions;
 
-  const result: Array<{ id: ItemId; length: number }> = [];
-  let current = { ...deletions[0] };
+  const result: Array<[ItemId, number]> = [];
+  let current: [ItemId, number] = [...deletions[0]]; // Clone the tuple
 
   for (let i = 1; i < deletions.length; i++) {
     const deletion = deletions[i];
-    const currParsed = parseItemId(current.id);
-    const delParsed = parseItemId(deletion.id);
+    const currentId = current[0]; // id is at [0]
+    const deletionId = deletion[0]; // id is at [0]
+
+    const currParsed = parseItemId(currentId);
+    const delParsed = parseItemId(deletionId);
 
     // Can merge if: same agent AND current deletion ends where next starts
     if (currParsed.agent === delParsed.agent &&
-        currParsed.seq + current.length === delParsed.seq) {
+        currParsed.seq + current[1] === delParsed.seq) {
       // Merge: extend current deletion
-      current.length += deletion.length;
+      current[1] += deletion[1]; // length is at [1]
     } else {
       // Cannot merge: push current and start new
       result.push(current);
-      current = { ...deletion };
+      current = [...deletion]; // Clone the tuple
     }
   }
 

package/src/client/coalescence/vector3Operations.ts

@@ -16,7 +16,7 @@ export type { Vector3AddOp };
  */
 export function isVector3AddOp(op: Operation): op is Vector3AddOp {
   return (
-    op.otype === 'vector3.add' &&
+    op.ot === 'vector3.add' &&
     Array.isArray((op as any).value) &&
     (op as any).value.length === 3
   );
@@ -59,7 +59,7 @@ export function coalesceVector3Adds(
       if (sameTarget) {
         // Merge operations by summing vectors component-wise
         pending = {
-          otype: 'vector3.add',
+          ot: 'vector3.add',
           key: pending.key,
           path: pending.path,
           value: [

package/src/client/createGraph.ts

@@ -4,11 +4,11 @@
  * Usage:
  * ```typescript
  * const store = createGraph({
- *   sessionId: 'my-session',
+ *   client: 'my-session',
  *   onSend: (msg) => websocket.send(msg),
  * });
  *
- * store.edit({ otype: 'vector3.add', key: 'cube', path: 'position', value: [1, 0, 0] });
+ * store.edit({ ot: 'vector3.add', key: 'cube', path: 'position', value: [1, 0, 0] });
  * store.commit('Move cube');
  * store.undo();
  * ```
@@ -35,7 +35,7 @@ import type { VectorClock } from '../state/VectorClock.js';
  * Create a graph store
  */
 export function createGraph(options: CreateGraphOptions): GraphStore {
-  let state = createInitialState(options.sessionId, options.initialSnapshot);
+  let state = createInitialState(options.client, options.initialSnapshot);
   const listeners = new Set<() => void>();
   let coalescingTimer: ReturnType<typeof setTimeout> | null = null;
   let coalescingEnabled = options.coalescingEnabled ?? false;
@@ -136,7 +136,7 @@ export function createGraph(options: CreateGraphOptions): GraphStore {
     },
 
     loadServerState: (snapshot: Snapshot, journal: CRDTMessage[]) => {
-      dispatch(() => initFromServer(options.sessionId, snapshot, journal));
+      dispatch(() => initFromServer(options.client, snapshot, journal));
     },
 
     // Undo/redo

package/src/client/createTextDocument.ts

@@ -4,7 +4,7 @@
  * Usage:
  * ```typescript
  * const store = createTextDocument({
- *   sessionId: 'my-session',
+ *   client: 'my-session',
  *   onSend: (msg) => websocket.send(msg),
  * });
  *
@@ -38,7 +38,7 @@ import {
  * Create a text document store
  */
 export function createTextDocument(options: CreateTextDocumentOptions): TextDocumentStore {
-  let state = createInitialTextState(options.sessionId, options.initialSnapshot);
+  let state = createInitialTextState(options.client, options.initialSnapshot);
   const listeners = new Set<() => void>();
   let coalescingTimer: ReturnType<typeof setTimeout> | null = null;
   let coalescingEnabled = options.coalescingEnabled ?? false;
@@ -161,7 +161,7 @@ export function createTextDocument(options: CreateTextDocumentOptions): TextDocu
     },
 
     loadServerState: (snapshot: TextSnapshot, journal: TextMessage[]) => {
-      dispatch(() => initTextFromServer(options.sessionId, snapshot, journal));
+      dispatch(() => initTextFromServer(options.client, snapshot, journal));
     },
 
     // Undo/redo

package/src/client/hooks.tsx

@@ -5,7 +5,7 @@
  * ```tsx
  * function App() {
  *   return (
- *     <GraphProvider sessionId="my-session" onSend={sendToServer}>
+ *     <GraphProvider client="my-session" onSend={sendToServer}>
  *       <Scene />
  *     </GraphProvider>
  *   );
@@ -42,21 +42,21 @@ const GraphContext = createContext<GraphStore | null>(null);
 // ===========================================
 
 export interface GraphProviderProps {
-  sessionId: string;
+  client: string;
   initialSnapshot?: Snapshot;
   onSend?: (msg: CRDTMessage) => void;
   children: ReactNode;
 }
 
 export function GraphProvider({
-  sessionId,
+  client,
   initialSnapshot,
   onSend,
   children,
 }: GraphProviderProps): React.ReactElement {
   const [store] = useState(() =>
     createGraph({
-      sessionId,
+      client,
       initialSnapshot,
       onSend,
     })
@@ -205,7 +205,7 @@ export function useDrag(nodeKey: string, path: string) {
   const onDrag = useCallback(
     (delta: [number, number, number]) => {
       edit({
-        otype: 'vector3.add',
+        ot: 'vector3.add',
         key: nodeKey,
         path,
         value: delta,

package/src/client/textActions.ts

@@ -32,7 +32,7 @@ const clockManager = new VectorClockManager();
  * Create initial text document state
  */
 export function createInitialTextState(
-  sessionId: string,
+  client: string,
   initialSnapshot?: TextSnapshot
 ): TextDocumentState {
   if (initialSnapshot) {
@@ -41,26 +41,26 @@ export function createInitialTextState(
       journal: [],
       edits: { ops: [], baseText: null },
       snapshot: initialSnapshot,
-      lamportTime: initialSnapshot.lamportTime,
+      lt: initialSnapshot.lt,
       vectorClock: { ...initialSnapshot.vectorClock },
-      sessionId,
+      client: client,
     };
   }
 
-  const rope = createRope(sessionId);
+  const rope = createRope(client);
   return {
     rope,
     journal: [],
     edits: { ops: [], baseText: null },
     snapshot: {
       rope,
-      vectorClock: { [sessionId]: 0 },
-      lamportTime: 0,
+      vectorClock: { [client]: 0 },
+      lt: 0,
       journalIndex: 0,
     },
-    lamportTime: 0,
-    vectorClock: { [sessionId]: 0 },
-    sessionId,
+    lt: 0,
+    vectorClock: { [client]: 0 },
+    client: client,
   };
 }
 
@@ -82,9 +82,9 @@ export function onTextEdit(
 
   // Clone rope and apply operation (rope operations mutate in place)
   const rope = cloneRope(state.rope);
-  if (op.otype === 'insert') {
+  if (op.ot === 'insert') {
     ropeApply(rope, op);
-  } else if (op.otype === 'delete') {
+  } else if (op.ot === 'delete') {
     ropeApplyDelete(rope, op);
   }
 
@@ -108,17 +108,17 @@ export function commitTextEdits(
     ? coalesceTextOperations(state.edits.ops, { thresholdMs: coalescingThresholdMs })
     : state.edits.ops;
 
-  const msgId = `${state.sessionId}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-  const vectorClock = clockManager.increment(state.vectorClock, state.sessionId);
-  const lamportTime = state.lamportTime + 1;
+  const msgId = `${state.client}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const vectorClock = clockManager.increment(state.vectorClock, state.client);
+  const lamportTime = state.lt + 1;
 
   const msg: TextMessage = {
     msgId,
-    sessionId: state.sessionId,
+    client: state.client,
     operations,
     vectorClock,
-    lamportTime,
-    timestamp: Date.now(),
+    lt: lamportTime,
+    ts: Date.now(),
     description,
   };
 
@@ -133,7 +133,7 @@ export function commitTextEdits(
       journal: [...state.journal, entry],
       edits: { ops: [], baseText: null },
       vectorClock,
-      lamportTime,
+      lt: lamportTime,
     },
     msg,
   };
@@ -153,9 +153,9 @@ export function cancelTextEdits(state: TextDocumentState): TextDocumentState {
   for (const entry of state.journal) {
     if (entry.deletedAt) continue; // Skip undone entries
     for (const op of entry.msg.operations) {
-      if (op.otype === 'insert') {
+      if (op.ot === 'insert') {
         ropeApply(rope, op);
-      } else if (op.otype === 'delete') {
+      } else if (op.ot === 'delete') {
         ropeApplyDelete(rope, op);
       }
     }
@@ -196,9 +196,9 @@ export function onTextRemoteMessage(
   // Clone rope and apply remote operations
   const rope = cloneRope(state.rope);
   for (const op of msg.operations) {
-    if (op.otype === 'insert') {
+    if (op.ot === 'insert') {
       ropeApply(rope, op);
-    } else if (op.otype === 'delete') {
+    } else if (op.ot === 'delete') {
       ropeApplyDelete(rope, op);
     }
   }
@@ -210,14 +210,14 @@ export function onTextRemoteMessage(
 
   // Merge vector clocks
   const vectorClock = clockManager.merge(state.vectorClock, msg.vectorClock);
-  const lamportTime = Math.max(state.lamportTime, msg.lamportTime) + 1;
+  const lamportTime = Math.max(state.lt, msg.lt) + 1;
 
   return {
     ...state,
     rope,
     journal: [...state.journal, entry],
     vectorClock,
-    lamportTime,
+    lt: lamportTime,
   };
 }
 
@@ -225,11 +225,11 @@ export function onTextRemoteMessage(
  * Initialize from server state
  */
 export function initTextFromServer(
-  sessionId: string,
+  client: string,
   snapshot: TextSnapshot,
   journal: TextMessage[]
 ): TextDocumentState {
-  let state = createInitialTextState(sessionId, snapshot);
+  let state = createInitialTextState(client, snapshot);
 
   // Apply journal entries
   for (const msg of journal) {
@@ -249,7 +249,7 @@ export function undoText(
   let lastIdx = -1;
   for (let i = state.journal.length - 1; i >= 0; i--) {
     if (
-      state.journal[i].msg.sessionId === state.sessionId &&
+      state.journal[i].msg.client === state.client &&
       !state.journal[i].deletedAt
     ) {
       lastIdx = i;
@@ -271,24 +271,24 @@ export function undoText(
   for (const entry of journal) {
     if (entry.deletedAt) continue;
     for (const op of entry.msg.operations) {
-      if (op.otype === 'insert') {
+      if (op.ot === 'insert') {
         ropeApply(rope, op);
-      } else if (op.otype === 'delete') {
+      } else if (op.ot === 'delete') {
         ropeApplyDelete(rope, op);
       }
     }
   }
 
   // Create undo message
-  const vectorClock = clockManager.increment(state.vectorClock, state.sessionId);
-  const lamportTime = state.lamportTime + 1;
+  const vectorClock = clockManager.increment(state.vectorClock, state.client);
+  const lamportTime = state.lt + 1;
   const msg: TextMessage = {
-    msgId: `${state.sessionId}-undo-${Date.now()}`,
-    sessionId: state.sessionId,
-    operations: [{ otype: 'delete', deletions: [] }], // Placeholder for undo marker
+    msgId: `${state.client}-undo-${Date.now()}`,
+    client: state.client,
+    operations: [{ ot: 'delete', rm: [] }], // Placeholder for undo marker
     vectorClock,
-    lamportTime,
-    timestamp: Date.now(),
+    lt: lamportTime,
+    ts: Date.now(),
     description: 'undo',
   };
 
@@ -298,7 +298,7 @@ export function undoText(
       rope,
       journal,
       vectorClock,
-      lamportTime,
+      lt: lamportTime,
     },
     msg,
   };
@@ -314,7 +314,7 @@ export function redoText(
   let lastIdx = -1;
   for (let i = state.journal.length - 1; i >= 0; i--) {
     if (
-      state.journal[i].msg.sessionId === state.sessionId &&
+      state.journal[i].msg.client === state.client &&
       state.journal[i].deletedAt
     ) {
       lastIdx = i;
@@ -337,24 +337,24 @@ export function redoText(
   for (const e of journal) {
     if (e.deletedAt) continue;
     for (const op of e.msg.operations) {
-      if (op.otype === 'insert') {
+      if (op.ot === 'insert') {
         ropeApply(rope, op);
-      } else if (op.otype === 'delete') {
+      } else if (op.ot === 'delete') {
         ropeApplyDelete(rope, op);
       }
     }
   }
 
   // Create redo message
-  const vectorClock = clockManager.increment(state.vectorClock, state.sessionId);
-  const lamportTime = state.lamportTime + 1;
+  const vectorClock = clockManager.increment(state.vectorClock, state.client);
+  const lamportTime = state.lt + 1;
   const msg: TextMessage = {
-    msgId: `${state.sessionId}-redo-${Date.now()}`,
-    sessionId: state.sessionId,
+    msgId: `${state.client}-redo-${Date.now()}`,
+    client: state.client,
     operations: entry.msg.operations,
     vectorClock,
-    lamportTime,
-    timestamp: Date.now(),
+    lt: lamportTime,
+    ts: Date.now(),
     description: 'redo',
   };
 
@@ -364,7 +364,7 @@ export function redoText(
       rope,
       journal,
       vectorClock,
-      lamportTime,
+      lt: lamportTime,
     },
     msg,
   };