meridian-sdk 1.2.0 → 1.3.0

package/src/undo/UndoManager.ts

@@ -0,0 +1,369 @@
+import { RGAHandle } from "../crdt/rga.js";
+import { TreeHandle } from "../crdt/tree.js";
+import type {
+  UndoBatch,
+  UndoEntry,
+  RgaInsertEntry,
+  TreeAddEntry,
+  TreeDeleteEntry,
+  TreeMoveEntry,
+  TreeUpdateEntry,
+} from "./types.js";
+
+const MAX_STACK_DEPTH = 100;
+const RGA_DEBOUNCE_MS = 250;
+
+type SupportedHandle = RGAHandle | TreeHandle;
+
+/**
+ * CRDT-aware per-client undo/redo manager.
+ *
+ * Wraps an RGAHandle or TreeHandle. Intercept mutating methods via the manager
+ * instead of the handle directly to record undo history.
+ *
+ * Rules:
+ * - Undo sends a new valid CrdtOp (never a state rollback).
+ * - Only the local client's ops are tracked — remote ops are unaffected.
+ * - RGA Delete is NOT recorded (tombstones are final).
+ * - Stack is capped at 100 batches; oldest entries are dropped silently.
+ *
+ * @example
+ * ```ts
+ * const manager = new UndoManager(client.rga("doc"));
+ * manager.insert(0, "hello");
+ * manager.undo(); // sends 5 × RgaOp::Delete
+ * ```
+ */
+export class UndoManager<H extends SupportedHandle> {
+  private readonly handle: H;
+  private undoStack: UndoBatch[] = [];
+  private redoStack: UndoBatch[] = [];
+  private readonly stackListeners = new Set<() => void>();
+
+  // Batch accumulation
+  private openBatch: UndoEntry[] | null = null;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(handle: H) {
+    this.handle = handle;
+  }
+
+  // ─── Stack state ────────────────────────────────────────────────────────────
+
+  get canUndo(): boolean {
+    return this.undoStack.length > 0;
+  }
+
+  get canRedo(): boolean {
+    return this.redoStack.length > 0;
+  }
+
+  /**
+   * Subscribe to stack change notifications (fired after any undo/redo/record).
+   * @returns Unsubscribe function.
+   */
+  onStackChange(listener: () => void): () => void {
+    this.stackListeners.add(listener);
+    return () => { this.stackListeners.delete(listener); };
+  }
+
+  // ─── Manual batching ────────────────────────────────────────────────────────
+
+  /** Begin accumulating entries into a single undo step. */
+  startBatch(): void {
+    if (this.openBatch === null) {
+      this.openBatch = [];
+    }
+  }
+
+  /** Commit the open batch as one entry on the undo stack. No-op if no batch is open. */
+  commitBatch(): void {
+    if (this.openBatch !== null && this.openBatch.length > 0) {
+      this.pushUndo({ entries: this.openBatch });
+    }
+    this.openBatch = null;
+  }
+
+  /** Discard the open batch without recording anything. */
+  cancelBatch(): void {
+    this.openBatch = null;
+  }
+
+  // ─── Undo / Redo ────────────────────────────────────────────────────────────
+
+  undo(): void {
+    const batch = this.undoStack.pop();
+    if (batch === undefined) return;
+    const inverseEntries: UndoEntry[] = [];
+
+    // Apply inverse ops in reverse entry order.
+    for (let i = batch.entries.length - 1; i >= 0; i--) {
+      const entry = batch.entries[i]!;
+      const inverse = this.applyInverse(entry);
+      if (inverse !== null) inverseEntries.unshift(inverse);
+    }
+
+    if (inverseEntries.length > 0) {
+      this.redoStack.push({ entries: inverseEntries });
+    }
+    this.notifyStackChange();
+  }
+
+  redo(): void {
+    const batch = this.redoStack.pop();
+    if (batch === undefined) return;
+    const inverseEntries: UndoEntry[] = [];
+
+    for (let i = batch.entries.length - 1; i >= 0; i--) {
+      const entry = batch.entries[i]!;
+      const inverse = this.applyInverse(entry);
+      if (inverse !== null) inverseEntries.unshift(inverse);
+    }
+
+    if (inverseEntries.length > 0) {
+      this.undoStack.push({ entries: inverseEntries });
+      if (this.undoStack.length > MAX_STACK_DEPTH) {
+        this.undoStack.shift();
+      }
+    }
+    this.notifyStackChange();
+  }
+
+  // ─── RGA handle proxy methods ────────────────────────────────────────────────
+
+  /**
+   * Insert text at visible position. Records undo entry with HLC node IDs.
+   * Uses 250ms debounce — consecutive inserts within the window form one batch.
+   */
+  insert(pos: number, text: string, ttlMs?: number): string[] {
+    const handle = this.asRGA();
+    const nodeIds = handle.insert(pos, text, ttlMs);
+
+    for (let i = 0; i < nodeIds.length; i++) {
+      const entry: RgaInsertEntry = {
+        kind: "rga_insert",
+        crdtId: handle.id,
+        nodeId: nodeIds[i]!,
+        pos: pos + i,
+        content: text[i]!,
+      };
+      this.recordWithDebounce(entry);
+    }
+
+    this.clearRedo();
+    return nodeIds;
+  }
+
+  /**
+   * Delete characters by position. NOT recorded — RGA delete is non-undoable
+   * (tombstones are final; content is irrecoverable).
+   * clearRedo() is intentional: a destructive untracked op should invalidate
+   * any pending redo history, matching ProseMirror/Yjs behaviour.
+   */
+  delete(pos: number, length: number, ttlMs?: number): void {
+    this.asRGA().delete(pos, length, ttlMs);
+    this.clearRedo();
+  }
+
+  // ─── Tree handle proxy methods ───────────────────────────────────────────────
+
+  addNode(parentId: string | null, position: string, value: string, ttlMs?: number): string {
+    const handle = this.asTree();
+    const nodeId = handle.addNode(parentId, position, value, ttlMs);
+    const entry: TreeAddEntry = {
+      kind: "tree_add",
+      crdtId: this.getCrdtId(),
+      nodeId,
+      parentId,
+      position,
+      value,
+    };
+    this.record(entry);
+    this.clearRedo();
+    return nodeId;
+  }
+
+  moveNode(nodeId: string, newParentId: string | null, newPosition: string, ttlMs?: number): void {
+    const handle = this.asTree();
+    const meta = handle.getNodeMeta(nodeId);
+    handle.moveNode(nodeId, newParentId, newPosition, ttlMs);
+    const entry: TreeMoveEntry = {
+      kind: "tree_move",
+      crdtId: this.getCrdtId(),
+      nodeId,
+      oldParentId: meta?.parentId ?? null,
+      oldPosition: meta?.position ?? "a0",
+      newParentId,
+      newPosition,
+    };
+    this.record(entry);
+    this.clearRedo();
+  }
+
+  updateNode(nodeId: string, value: string, ttlMs?: number): void {
+    const handle = this.asTree();
+    const meta = handle.getNodeMeta(nodeId);
+    handle.updateNode(nodeId, value, ttlMs);
+    const entry: TreeUpdateEntry = {
+      kind: "tree_update",
+      crdtId: this.getCrdtId(),
+      nodeId,
+      previousValue: meta?.value ?? "",
+      previousUpdatedAt: meta?.updatedAt ?? nodeId,
+      newValue: value,
+    };
+    this.record(entry);
+    this.clearRedo();
+  }
+
+  deleteNode(nodeId: string, ttlMs?: number): void {
+    const handle = this.asTree();
+    const meta = handle.getNodeMeta(nodeId);
+    handle.deleteNode(nodeId, ttlMs);
+    const entry: TreeDeleteEntry = {
+      kind: "tree_delete",
+      crdtId: this.getCrdtId(),
+      nodeId,
+      parentId: meta?.parentId ?? null,
+      position: meta?.position ?? "a0",
+      value: meta?.value ?? "",
+      updatedAt: meta?.updatedAt ?? nodeId,
+    };
+    this.record(entry);
+    this.clearRedo();
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────────
+
+  private applyInverse(entry: UndoEntry): UndoEntry | null {
+    switch (entry.kind) {
+      case "rga_insert": {
+        this.asRGA().deleteById(entry.nodeId);
+        // Inverse of an insert is a delete — not re-recordable as an undo entry.
+        return null;
+      }
+
+      case "tree_add": {
+        this.asTree().deleteNode(entry.nodeId);
+        // Inverse: a delete entry (for redo — re-add the node).
+        const inverse: TreeDeleteEntry = {
+          kind: "tree_delete",
+          crdtId: entry.crdtId,
+          nodeId: entry.nodeId,
+          parentId: entry.parentId,
+          position: entry.position,
+          value: entry.value,
+          updatedAt: entry.nodeId,
+        };
+        return inverse;
+      }
+
+      case "tree_delete": {
+        // Re-add with original state. Gets a new nodeId (tombstone is permanent).
+        const newNodeId = this.asTree().addNode(
+          entry.parentId,
+          entry.position,
+          entry.value,
+        );
+        const inverse: TreeAddEntry = {
+          kind: "tree_add",
+          crdtId: entry.crdtId,
+          nodeId: newNodeId,
+          parentId: entry.parentId,
+          position: entry.position,
+          value: entry.value,
+        };
+        return inverse;
+      }
+
+      case "tree_move": {
+        this.asTree().moveNode(entry.nodeId, entry.oldParentId, entry.oldPosition);
+        const inverse: TreeMoveEntry = {
+          kind: "tree_move",
+          crdtId: entry.crdtId,
+          nodeId: entry.nodeId,
+          oldParentId: entry.newParentId,
+          oldPosition: entry.newPosition,
+          newParentId: entry.oldParentId,
+          newPosition: entry.oldPosition,
+        };
+        return inverse;
+      }
+
+      case "tree_update": {
+        this.asTree().updateNode(entry.nodeId, entry.previousValue);
+        const inverse: TreeUpdateEntry = {
+          kind: "tree_update",
+          crdtId: entry.crdtId,
+          nodeId: entry.nodeId,
+          previousValue: entry.newValue,
+          previousUpdatedAt: entry.previousUpdatedAt,
+          newValue: entry.previousValue,
+        };
+        return inverse;
+      }
+    }
+  }
+
+  private record(entry: UndoEntry): void {
+    if (this.openBatch !== null) {
+      this.openBatch.push(entry);
+    } else {
+      this.pushUndo({ entries: [entry] });
+    }
+  }
+
+  /** Record with 250ms debounce — consecutive calls within window share one batch. */
+  private recordWithDebounce(entry: UndoEntry): void {
+    if (this.debounceTimer === null) {
+      // Start a new debounce batch.
+      this.openBatch = [entry];
+    } else {
+      // Extend the current batch.
+      clearTimeout(this.debounceTimer);
+      this.openBatch?.push(entry);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      this.commitBatch();
+    }, RGA_DEBOUNCE_MS);
+  }
+
+  private pushUndo(batch: UndoBatch): void {
+    this.undoStack.push(batch);
+    if (this.undoStack.length > MAX_STACK_DEPTH) {
+      this.undoStack.shift();
+    }
+    this.notifyStackChange();
+  }
+
+  private clearRedo(): void {
+    if (this.redoStack.length > 0) {
+      this.redoStack = [];
+      this.notifyStackChange();
+    }
+  }
+
+  private notifyStackChange(): void {
+    for (const listener of this.stackListeners) listener();
+  }
+
+  private asRGA(): RGAHandle {
+    if (!(this.handle instanceof RGAHandle)) {
+      throw new Error("UndoManager: handle is not an RGAHandle");
+    }
+    return this.handle;
+  }
+
+  private asTree(): TreeHandle {
+    if (!(this.handle instanceof TreeHandle)) {
+      throw new Error("UndoManager: handle is not a TreeHandle");
+    }
+    return this.handle;
+  }
+
+  private getCrdtId(): string {
+    return this.handle.id;
+  }
+}

package/src/undo/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Undo/redo entry types for CRDT-aware per-client history.
+ *
+ * Each entry stores enough information to produce the inverse operation.
+ * RGA Delete is intentionally not recorded — tombstones are final and
+ * the content is not recoverable (same semantics as ProseMirror/Yjs).
+ */
+
+export interface RgaInsertEntry {
+  readonly kind: "rga_insert";
+  readonly crdtId: string;
+  /** HLC string "wall_ms:logical:node_id" of the inserted node. Undo = deleteById(nodeId). */
+  readonly nodeId: string;
+  /** Original visible position — used for redo re-insert. */
+  readonly pos: number;
+  /** The character that was inserted. */
+  readonly content: string;
+}
+
+export interface TreeAddEntry {
+  readonly kind: "tree_add";
+  readonly crdtId: string;
+  /** Node ID returned by addNode(). Undo = deleteNode(nodeId). */
+  readonly nodeId: string;
+  /** Stored for redo: re-add with same parent/position/value. */
+  readonly parentId: string | null;
+  readonly position: string;
+  readonly value: string;
+}
+
+export interface TreeDeleteEntry {
+  readonly kind: "tree_delete";
+  readonly crdtId: string;
+  readonly nodeId: string;
+  /** State captured before the delete — used to reconstruct addNode for undo. */
+  readonly parentId: string | null;
+  readonly position: string;
+  readonly value: string;
+  readonly updatedAt: string;
+}
+
+export interface TreeMoveEntry {
+  readonly kind: "tree_move";
+  readonly crdtId: string;
+  readonly nodeId: string;
+  readonly oldParentId: string | null;
+  readonly oldPosition: string;
+  /** Stored for redo. */
+  readonly newParentId: string | null;
+  readonly newPosition: string;
+}
+
+export interface TreeUpdateEntry {
+  readonly kind: "tree_update";
+  readonly crdtId: string;
+  readonly nodeId: string;
+  /** Captured before the update — used for undo. */
+  readonly previousValue: string;
+  readonly previousUpdatedAt: string;
+  /** Stored for redo. */
+  readonly newValue: string;
+}
+
+export type UndoEntry =
+  | RgaInsertEntry
+  | TreeAddEntry
+  | TreeDeleteEntry
+  | TreeMoveEntry
+  | TreeUpdateEntry;
+
+/** A batch groups one or more entries into a single logical undo step. */
+export interface UndoBatch {
+  readonly entries: readonly UndoEntry[];
+}

package/src/utils/fractional.ts

@@ -0,0 +1,166 @@
+/**
+ * Fractional indexing helpers for TreeCRDT sibling ordering.
+ *
+ * Positions are lexicographically ordered strings over the alphabet [a-z0-9].
+ * They can be compared with plain string comparison: "a0" < "b0" < "z9".
+ *
+ * Use these helpers to compute positions when inserting nodes between, before,
+ * or after existing siblings — without having to manage the alphabet manually.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ *
+ * const first = fi.start();            // "a0"
+ * const last  = fi.end();              // "z9"
+ * const mid   = fi.between("a0","z9"); // "m4" (midpoint)
+ * const prev  = fi.before("a0");       // "V9" (below a0)
+ * const next  = fi.after("z9");        // "{0" (above z9, still valid)
+ * ```
+ */
+
+/** Characters used in fractional index strings, in ascending order. */
+const CHARS = "0123456789abcdefghijklmnopqrstuvwxyz";
+const BASE = BigInt(CHARS.length); // 36
+
+/** Encode a position string to a BigInt for arithmetic. */
+function toNum(s: string): bigint {
+  let n = 0n;
+  for (const c of s) {
+    const idx = CHARS.indexOf(c);
+    if (idx === -1) throw new Error(`Invalid fractional index character: "${c}"`);
+    n = n * BASE + BigInt(idx);
+  }
+  return n;
+}
+
+/** Decode a BigInt back to a fixed-length position string. */
+function toStr(n: bigint, len: number): string {
+  let s = "";
+  for (let i = 0; i < len; i++) {
+    s = (CHARS[Number(n % BASE)] ?? "0") + s;
+    n = n / BASE;
+  }
+  return s;
+}
+
+/** Increment a position string by 1 in base-36. */
+function increment(s: string): string {
+  const n = toNum(s) + 1n;
+  // If the result requires more digits, extend by one char
+  const maxForLen = BASE ** BigInt(s.length) - 1n;
+  if (n > maxForLen) return toStr(n, s.length + 1);
+  return toStr(n, s.length);
+}
+
+/** Decrement a position string by 1 in base-36, trimming trailing zeros. */
+function decrement(s: string): string {
+  const n = toNum(s) - 1n;
+  let result = toStr(n < 0n ? 0n : n, s.length);
+  // Trim trailing zeros beyond length 1
+  while (result.length > 1 && result.endsWith("0")) result = result.slice(0, -1);
+  // If underflow, prepend a zero digit
+  if (n < 0n) return "0" + result;
+  return result;
+}
+
+/**
+ * Returns a position string strictly between `a` and `b`.
+ *
+ * Both `a` and `b` must be valid fractional index strings, and `a < b`
+ * lexicographically. Uses BigInt arithmetic to find the exact midpoint,
+ * appending an extra character when the gap is too small.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ */
+export function between(a: string, b: string): string {
+  if (a >= b) throw new Error(`between: a must be < b (got "${a}" >= "${b}")`);
+
+  // Pad both to the same length + 1 extra digit for precision
+  const len = Math.max(a.length, b.length) + 1;
+  const aPadded = a.padEnd(len, "0");
+  const bPadded = b.padEnd(len, "0");
+
+  const an = toNum(aPadded);
+  const bn = toNum(bPadded);
+  const mid = (an + bn) / 2n;
+
+  let result = toStr(mid, len);
+  // Trim trailing zeros for cleaner output (keep min length 1)
+  while (result.length > 1 && result.endsWith("0")) result = result.slice(0, -1);
+  return result;
+}
+
+/**
+ * Returns a position string that sorts before `a`.
+ *
+ * @param a - The reference position.
+ */
+export function before(a: string): string {
+  return decrement(a);
+}
+
+/**
+ * Returns a position string that sorts after `b`.
+ *
+ * @param b - The reference position.
+ */
+export function after(b: string): string {
+  return increment(b);
+}
+
+/**
+ * Returns the canonical start position — the lowest recommended initial value.
+ */
+export function start(): string {
+  return "a0";
+}
+
+/**
+ * Returns the canonical end position — the highest recommended initial value.
+ */
+export function end(): string {
+  return "z9";
+}
+
+/**
+ * Computes an array of `n` evenly-spaced positions between `a` and `b`
+ * (exclusive). Useful for bulk-inserting nodes in order.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ * @param n - Number of positions to generate.
+ */
+export function spread(a: string, b: string, n: number): string[] {
+  if (n <= 0) return [];
+  if (n === 1) return [between(a, b)];
+
+  const positions: string[] = [];
+  let lo = a;
+  for (let i = 0; i < n; i++) {
+    // Divide the remaining range into (n - i) equal slots
+    const remaining = n - i;
+    // Approximate: compute a position 1/(remaining+1) through [lo, b]
+    // We do this iteratively by bisecting
+    let hi = b;
+    for (let step = 0; step < Math.ceil(Math.log2(remaining + 1)); step++) {
+      hi = between(lo, b);
+    }
+    const pos = between(lo, b);
+    positions.push(pos);
+    lo = pos;
+  }
+  return positions;
+}
+
+/**
+ * Namespace object for convenient import.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ * const pos = fi.between("a0", "z9");
+ * ```
+ */
+export const fi = { between, before, after, start, end, spread };