TextRope - Collaborative Text CRDT

import { createEmptyGraph, applyMessage } from '@vuer-ai/vuer-rtc';

let graph = createEmptyGraph();
let lamport = 0;

const msg = (ops) => ({
  id: `msg-${++lamport}`,
  sessionId: 'alice',
  clock: { alice: lamport },
  lamportTime: lamport,
  timestamp: Date.now(),
  ops,
});

// Create a text document node
graph = applyMessage(graph, msg([
  { otype: 'node.insert', key: '', path: 'children',
    value: { key: 'doc-1', tag: 'TextDocument', name: 'My Doc' } },
]));

// Initialize text content
graph = applyMessage(graph, msg([
  { otype: 'text.init', key: 'doc-1', path: 'content', value: 'Hello' },
]));

// Insert more text
graph = applyMessage(graph, msg([
  { otype: 'text.insert', key: 'doc-1', path: 'content', position: 5, value: ' World' },
]));

console.log(graph.nodes['doc-1'].content);  // "Hello World"

// Delete text
graph = applyMessage(graph, msg([
  { otype: 'text.delete', key: 'doc-1', path: 'content', position: 5, length: 6 },
]));

console.log(graph.nodes['doc-1'].content);  // "Hello"

// Alice's graph
let graphA = createEmptyGraph();
graphA = applyMessage(graphA, msgA([
  { otype: 'node.insert', key: '', path: 'children',
    value: { key: 'doc-1', tag: 'TextDocument', name: 'Shared Doc' } },
  { otype: 'text.init', key: 'doc-1', path: 'content', value: 'Hello' },
]));

// Bob syncs Alice's state
let graphB = graphA;

// Alice inserts at the beginning
const aliceOp = msgA([
  { otype: 'text.insert', key: 'doc-1', path: 'content', position: 0, value: 'A: ' },
]);
graphA = applyMessage(graphA, aliceOp);

// Bob inserts at the end (concurrently)
const bobOp = msgB([
  { otype: 'text.insert', key: 'doc-1', path: 'content', position: 5, value: ' -Bob' },
]);
graphB = applyMessage(graphB, bobOp);

// Sync operations
graphA = applyMessage(graphA, bobOp);
graphB = applyMessage(graphB, aliceOp);

// Both converge
console.log(graphA.nodes['doc-1'].content);  // "A: Hello -Bob"
console.log(graphB.nodes['doc-1'].content);  // "A: Hello -Bob"

import { getTextDocument } from '@vuer-ai/vuer-rtc';

const rope = getTextDocument(graph, 'doc-1', 'content');

console.log(rope?.items);     // Internal items
console.log(rope?.agentId);   // Agent ID
console.log(rope?.clock);     // Lamport clock

import {
  create, getText, insert, remove, replace,
  apply, applyDelete, applyReplace, toRaw, fromRaw,
} from '@vuer-ai/vuer-rtc/crdt';

// Create a rope — returns a TextRope class instance
const rope = create('agent-1');

// insert() mutates rope and returns an InsertOp for syncing
const op1 = insert(rope, 0, 'Hello');
const op2 = insert(rope, 5, ' World');
console.log(getText(rope));  // "Hello World"

// remove() mutates rope and returns a DeleteOp
const op3 = remove(rope, 5, 6);
console.log(getText(rope));  // "Hello"

// replace() does delete + insert atomically
const op4 = replace(rope, 0, 5, 'Hi');
console.log(getText(rope));  // "Hi"

// Sync to another rope
const rope2 = create('agent-2');
apply(rope2, op1);
apply(rope2, op2);
console.log(getText(rope2));  // "Hello World"

// Save to storage (minimal format)
const raw = toRaw(rope);
localStorage.setItem('doc', JSON.stringify(raw));

// Restore from storage
const restored = fromRaw(JSON.parse(localStorage.getItem('doc')!));

class TextRope {
  _tree: ItemTree;                       // B-tree of text spans
  _agentIndex: Map<string, SpanEntry[]>; // Per-agent sorted index for O(log m) ID lookups
  agentId: string;                       // This agent's ID
  clock: number;                         // Local sequence counter
  maxSeq: number;                        // Max Lamport timestamp seen
}

interface Item {
  id: ItemId;              // Unique identifier { agent, seq }
  content: string;         // Text content
  isDeleted: boolean;      // Tombstone flag
  parentId: ItemId | null; // Insert position reference
  seq: number;             // Lamport timestamp
}

// Full snapshot (includes tombstones)
const snap = snapshot(rope);

// Compacted snapshot (removes tombstones, merges consecutive spans)
const compacted = compact(rope);

// Restore from snapshot
const restored = fromSnapshot(snap);

// Restore with new agent ID
const newSession = fromSnapshot(snap, 'new-agent-id');

import { toRaw, fromRaw, type RawTextRope } from '@vuer-ai/vuer-rtc/crdt';

// Convert to raw array format
const raw: RawTextRope = toRaw(rope);
// Format: [agentId, clock, maxSeq, [[agent, seq, content, parentAgent, parentSeq], ...]]

// Store as JSON (very compact)
const json = JSON.stringify(raw);

// Restore from raw
const restored = fromRaw(raw);

// Restore with new agent ID
const newSession = fromRaw(raw, 'new-agent-id');

interface InsertOp {
  id: ItemId;
  content: string;
  parentId: ItemId | null;
  seq: number;
}

interface DeleteOp {
  deletions: Array<{ id: ItemId; length: number }>;
}

interface MoveOp {
  delete: DeleteOp;
  insert: InsertOp;
}

interface ReplaceOp {
  delete: DeleteOp;
  insert: InsertOp;
}

interface ItemId {
  agent: string;
  seq: number;
}

insert(rope, 0, 'h');
insert(rope, 1, 'e');
insert(rope, 2, 'l');
insert(rope, 3, 'l');
insert(rope, 4, 'o');
// May be stored as one item with content "hello"

insert(rope, 0, 'hello');  // One item
insertWithSplit(rope, 2, 'XX');
// Result: "heXXllo"
// Items: ["he", "XX", "llo"]

// Agent 1 has "hello" as one span → inserts at position 2
const op = insertWithSplit(rope1, 2, 'X');
// op.parentId = { agent: 'agent-1', seq: 1 }  (the 'e' character)

// Agent 2 also has "hello" as one span
apply(rope2, op);
// Agent 2 splits "hello" → "he" | "X" | "llo"
// Both agents: "heXllo" ✓

// Agent 1 deletes "ell" from "hello" → returns:
// { deletions: [{ id: { agent: 'agent-1', seq: 1 }, length: 3 }] }
//
// Agent 2 may have "hello" split differently, but applyDelete
// matches by agent + seq range, not by item position

┌─────────────────────────────────────────────────────┐
│                 1. StringRope                       │
│                (Pure Data Structure)                │
├─────────────────────────────────────────────────────┤
│  Simple mutable string wrapper                      │
│  - insert(position, text)                           │
│  - delete(position, length)                         │
│  - toString() → string                              │
│  - toJSON() → string (serializes as plain string)   │
│  - Can be upgraded to B-tree later for O(log n)     │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│                 2. TextCRDT (TextRope)              │
│              (Standalone Text Documents)            │
├─────────────────────────────────────────────────────┤
│  Full CRDT with B-tree + metadata                   │
│  _tree: ItemTree   ← B-tree of text spans           │
│  _agentIndex: Map  ← per-agent sorted index         │
│  agentId: string   ← this agent's ID                │
│  clock: number     ← local sequence counter         │
│  maxSeq: number    ← max Lamport time seen          │
│                                                      │
│  Used for: Standalone Text objects                  │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│                 3. GraphTextCRDT                    │
│             (Graph Node Text Coordination)          │
├─────────────────────────────────────────────────────┤
│  Manages TextRope instances for graph properties    │
│  - Any string property can accept text.* ops        │
│  - Addressed via key + path                         │
│  - CRDT state stored in _textRope.{path}            │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│                    SceneGraph                       │
│  (manual spread-based immutable updates)            │
├─────────────────────────────────────────────────────┤
│  nodes['doc-1']                                     │
│    ├── content: "Hello World"  ← visible string     │
│    └── _textRope.content: TextRope ← CRDT state     │
└─────────────────────────────────────────────────────┘