meridian-sdk 1.0.1 → 1.2.0

package/src/agents.ts

@@ -0,0 +1,277 @@
+/**
+ * Meridian × Anthropic Claude tool use helpers.
+ *
+ * Generates Anthropic-compatible `Tool` definitions from a list of CRDT IDs
+ * and executes tool calls against a Meridian server via HTTP (no WebSocket).
+ *
+ * Usage:
+ * ```ts
+ * import { getMeridianTools, executeMeridianTool } from "meridian-sdk";
+ *
+ * const tools = getMeridianTools({ baseUrl, token, namespace, crdtIds: ["counter", "tasks"] });
+ *
+ * // Pass tools to Anthropic messages.create(...)
+ * // Then for each tool_use block in the response:
+ * const result = await executeMeridianTool({ baseUrl, token, namespace }, toolUseBlock);
+ * ```
+ */
+
+import { encode, uuidToBytes } from "./codec.js";
+
+export interface Tool {
+  name: string;
+  description: string;
+  input_schema: {
+    type: "object";
+    properties: Record<string, { type: string; description: string }>;
+    required?: string[];
+  };
+}
+
+export interface ToolUseBlock {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface MeridianAgentConfig {
+  /** HTTP base URL of the Meridian server (e.g. https://meridian.example.com) */
+  baseUrl: string;
+  /** Bearer token with read+write permissions for the namespace */
+  token: string;
+  /** Namespace scoping all CRDT operations */
+  namespace: string;
+}
+
+/**
+ * Returns an Anthropic `Tool[]` array for the given CRDT IDs.
+ *
+ * Each CRDT exposes up to 3 tools:
+ * - `meridian_read_{id}`      — read current JSON state
+ * - `meridian_increment_{id}` — GCounter/PNCounter increment (amount)
+ * - `meridian_set_{id}`       — LwwRegister set (value as JSON string)
+ * - `meridian_add_{id}`       — ORSet add (element as JSON string)
+ */
+export function getMeridianTools(
+  config: MeridianAgentConfig,
+  crdtIds: string[],
+): Tool[] {
+  const tools: Tool[] = [];
+
+  for (const id of crdtIds) {
+    const safeName = id.replace(/[^a-zA-Z0-9_]/g, "_");
+
+    tools.push({
+      name: `meridian_read_${safeName}`,
+      description: `Read the current state of the "${id}" CRDT in namespace "${config.namespace}". Returns a JSON object with the CRDT value.`,
+      input_schema: {
+        type: "object",
+        properties: {},
+      },
+    });
+
+    tools.push({
+      name: `meridian_increment_${safeName}`,
+      description: `Increment the "${id}" counter CRDT by a given amount. Works for GCounter (positive only) and PNCounter (positive or negative).`,
+      input_schema: {
+        type: "object",
+        properties: {
+          amount: { type: "number", description: "The amount to increment (positive for GCounter, positive or negative for PNCounter)" },
+          client_id: { type: "number", description: "Unique numeric client ID for this agent (e.g. 1)" },
+        },
+        required: ["amount", "client_id"],
+      },
+    });
+
+    tools.push({
+      name: `meridian_set_${safeName}`,
+      description: `Set the value of the "${id}" LWW register CRDT. The value is serialized as a JSON string.`,
+      input_schema: {
+        type: "object",
+        properties: {
+          value: { type: "string", description: "The new value as a JSON string (e.g. '\"hello\"' or '{\"key\": 1}')" },
+          client_id: { type: "number", description: "Unique numeric client ID for this agent" },
+        },
+        required: ["value", "client_id"],
+      },
+    });
+
+    tools.push({
+      name: `meridian_add_${safeName}`,
+      description: `Add an element to the "${id}" ORSet CRDT.`,
+      input_schema: {
+        type: "object",
+        properties: {
+          element: { type: "string", description: "The element to add (as a JSON string)" },
+          client_id: { type: "number", description: "Unique numeric client ID for this agent" },
+        },
+        required: ["element", "client_id"],
+      },
+    });
+  }
+
+  return tools;
+}
+
+/**
+ * Execute a Meridian tool call returned by Claude.
+ *
+ * Returns a JSON string suitable for the `content` field of a `tool_result` block.
+ */
+export async function executeMeridianTool(
+  config: MeridianAgentConfig,
+  toolUse: ToolUseBlock,
+): Promise<string> {
+  const { baseUrl, token, namespace } = config;
+  const { name, input } = toolUse;
+
+  // Detect operation type and crdt_id from tool name
+  const readMatch = name.match(/^meridian_read_(.+)$/);
+  const incrementMatch = name.match(/^meridian_increment_(.+)$/);
+  const setMatch = name.match(/^meridian_set_(.+)$/);
+  const addMatch = name.match(/^meridian_add_(.+)$/);
+
+  if (readMatch?.[1]) {
+    const crdtId = readMatch[1].replace(/_/g, "-");
+    return readCrdt(baseUrl, token, namespace, crdtId);
+  }
+
+  if (incrementMatch?.[1]) {
+    const crdtId = incrementMatch[1].replace(/_/g, "-");
+    const amount = Number(input.amount ?? 1);
+    const clientId = Number(input.client_id ?? 1);
+    return applyCounterOp(baseUrl, token, namespace, crdtId, clientId, amount);
+  }
+
+  if (setMatch?.[1]) {
+    const crdtId = setMatch[1].replace(/_/g, "-");
+    const raw = String(input.value ?? "null");
+    let value: unknown;
+    try { value = JSON.parse(raw); } catch { value = raw; }
+    const clientId = Number(input.client_id ?? 1);
+    return applyLwwOp(baseUrl, token, namespace, crdtId, clientId, value);
+  }
+
+  if (addMatch?.[1]) {
+    const crdtId = addMatch[1].replace(/_/g, "-");
+    // Always store as a string so useORSet<string> can read it back directly.
+    // If Claude passes a JSON object, re-serialize it to a stable string.
+    const rawEl = input.element;
+    const element: string = typeof rawEl === "string" ? rawEl : JSON.stringify(rawEl ?? null);
+    const clientId = Number(input.client_id ?? 1);
+    return applyOrSetOp(baseUrl, token, namespace, crdtId, clientId, element);
+  }
+
+  return JSON.stringify({ error: `Unknown tool: ${name}` });
+}
+
+async function readCrdt(
+  baseUrl: string,
+  token: string,
+  ns: string,
+  id: string,
+): Promise<string> {
+  const res = await fetch(`${baseUrl}/v1/namespaces/${ns}/crdts/${id}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) {
+    return JSON.stringify({ error: `HTTP ${res.status}`, crdt_id: id });
+  }
+  const body = await res.json();
+  return JSON.stringify({ crdt_id: id, value: body });
+}
+
+async function applyCounterOp(
+  baseUrl: string,
+  token: string,
+  ns: string,
+  id: string,
+  clientId: number,
+  amount: number,
+): Promise<string> {
+  // Encode as GCounter op if positive, PNCounter op if negative
+  const op = amount >= 0
+    ? { GCounter: { client_id: clientId, amount } }
+    : { PNCounter: { client_id: clientId, amount } };
+
+  const body = encode(op);
+  const res = await fetch(`${baseUrl}/v1/namespaces/${ns}/crdts/${id}/ops`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/msgpack",
+    },
+    body,
+  });
+
+  if (!res.ok) {
+    return JSON.stringify({ error: `HTTP ${res.status}`, crdt_id: id });
+  }
+  return JSON.stringify({ ok: true, crdt_id: id, op: "increment", amount });
+}
+
+async function applyLwwOp(
+  baseUrl: string,
+  token: string,
+  ns: string,
+  id: string,
+  clientId: number,
+  value: unknown,
+): Promise<string> {
+  const nowMs = Date.now();
+  const op = {
+    LwwRegister: {
+      author: clientId,
+      value,
+      hlc: { wall_ms: nowMs, logical: 0, node_id: clientId },
+    },
+  };
+
+  const body = encode(op);
+  const res = await fetch(`${baseUrl}/v1/namespaces/${ns}/crdts/${id}/ops`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/msgpack",
+    },
+    body,
+  });
+
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    return JSON.stringify({ error: `HTTP ${res.status}`, crdt_id: id, detail });
+  }
+  return JSON.stringify({ ok: true, crdt_id: id, op: "set", value });
+}
+
+async function applyOrSetOp(
+  baseUrl: string,
+  token: string,
+  ns: string,
+  id: string,
+  clientId: number,
+  element: unknown,
+): Promise<string> {
+  const op = {
+    ORSet: {
+      Add: { client_id: clientId, element, tag: uuidToBytes(crypto.randomUUID()) },
+    },
+  };
+
+  const body = encode(op);
+  const res = await fetch(`${baseUrl}/v1/namespaces/${ns}/crdts/${id}/ops`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/msgpack",
+    },
+    body,
+  });
+
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    return JSON.stringify({ error: `HTTP ${res.status}`, crdt_id: id, detail });
+  }
+  return JSON.stringify({ ok: true, crdt_id: id, op: "add", element });
+}

package/src/client.ts

@@ -10,6 +10,7 @@ import { LwwRegisterHandle } from "./crdt/lwwregister.js";
 import { PresenceHandle } from "./crdt/presence.js";
 import { CRDTMapHandle } from "./crdt/crdtmap.js";
 import { AwarenessHandle } from "./crdt/awareness.js";
+import { RGAHandle } from "./crdt/rga.js";
 import {
   decodeGCounterDelta,
   decodePNCounterDelta,
@@ -17,6 +18,7 @@ import {
   decodeLwwDelta,
   decodePresenceDelta,
   decodeCRDTMapDelta,
+  decodeRGADelta,
 } from "./sync/delta.js";
 import { parseAndValidateToken } from "./auth/token.js";
 import type { ServerMsg, TokenClaims } from "./schema.js";
@@ -56,13 +58,19 @@ export interface CRDTMapSnapshotEntry {
   crdtId: string;
   value: Readonly<CrdtMapValue>;
 }
+export interface RGASnapshotEntry {
+  type: "rga";
+  crdtId: string;
+  text: string;
+}
 export type CRDTSnapshotEntry =
   | GCounterSnapshotEntry
   | PNCounterSnapshotEntry
   | ORSetSnapshotEntry
   | LwwRegisterSnapshotEntry
   | PresenceSnapshotEntry
-  | CRDTMapSnapshotEntry;
+  | CRDTMapSnapshotEntry
+  | RGASnapshotEntry;
 
 export interface DeltaEvent {
   crdtId: string;
@@ -127,6 +135,7 @@ export class MeridianClient {
   private readonly prHandles = new Map<string, PresenceHandle<unknown>>();
   private readonly cmHandles = new Map<string, CRDTMapHandle>();
   private readonly awHandles = new Map<string, AwarenessHandle<unknown>>();
+  private readonly rgaHandles = new Map<string, RGAHandle>();
 
   private readonly anyListeners = new Set<() => void>();
   private readonly deltaListeners = new Set<(event: DeltaEvent) => void>();
@@ -358,6 +367,32 @@ export class MeridianClient {
     return handle;
   }
 
+  /**
+   * Returns a handle for an RGA (Replicated Growable Array) CRDT — collaborative text editing.
+   *
+   * Handles are cached by `crdtId`; calling this method multiple times with the
+   * same id returns the same handle instance and creates only one subscription.
+   *
+   * @param crdtId - Unique identifier for the CRDT within this namespace.
+   *
+   * @example
+   * ```ts
+   * const doc = client.rga('doc:content');
+   * doc.insert(0, 'Hello');
+   * doc.onChange(text => console.log(text));
+   * ```
+   */
+  rga(crdtId: string): RGAHandle {
+    let handle = this.rgaHandles.get(crdtId);
+    if (!handle) {
+      handle = new RGAHandle({ crdtId, clientId: this.clientId, transport: this.transport });
+      this.rgaHandles.set(crdtId, handle);
+      this.transport.subscribe(crdtId);
+      this.handleUnsubs.push(handle.onChange(() => { this.notifyAnyChange(); }));
+    }
+    return handle;
+  }
+
   /**
    * Returns a handle for an ephemeral awareness channel.
    *
@@ -399,6 +434,11 @@ export class MeridianClient {
     return this.transport.pendingOpCount;
   }
 
+  /** P50 and P99 op round-trip latency in ms. Returns null if not enough samples. */
+  getLatencyStats(): { p50: number; p99: number; count: number } | null {
+    return this.transport.getLatencyStats();
+  }
+
   /**
    * Subscribe to connection state changes. Returns an unsubscribe function.
    * Useful for building "syncing" indicators in the UI.
@@ -445,6 +485,8 @@ export class MeridianClient {
       crdts.push({ type: "presence", crdtId, online: h.online() as { clientId: number; data: unknown; expiresAtMs: number }[] });
     for (const [crdtId, h] of this.cmHandles)
       crdts.push({ type: "crdtmap", crdtId, value: h.value() });
+    for (const [crdtId, h] of this.rgaHandles)
+      crdts.push({ type: "rga", crdtId, text: h.value() });
     return {
       namespace: this.namespace,
       clientId: this.clientId,
@@ -522,6 +564,12 @@ export class MeridianClient {
     if (cmHandle) {
       try { cmHandle.applyDelta(decodeCRDTMapDelta(delta_bytes)); } catch { /* stale */ }
       this.notifyDelta(crdt_id, "crdtmap");
+      return;
+    }
+    const rgaHandle = this.rgaHandles.get(crdt_id);
+    if (rgaHandle) {
+      try { rgaHandle.applyDelta(decodeRGADelta(delta_bytes)); } catch { /* stale */ }
+      this.notifyDelta(crdt_id, "rga");
     }
   }
 

package/src/crdt/awareness.ts

@@ -1,12 +1,8 @@
-import { Schema as S } from "effect";
+import { Chunk, Effect, Schema as S, Stream } from "effect";
 import type { Schema } from "effect";
 import { encode, decode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 
-// ---------------------------------------------------------------------------
-// AwarenessEntry
-// ---------------------------------------------------------------------------
-
 /**
  * A single peer's awareness state on a given channel.
  *
@@ -22,10 +18,6 @@ export interface AwarenessEntry<T> {
   receivedAt: number;
 }
 
-// ---------------------------------------------------------------------------
-// AwarenessHandle
-// ---------------------------------------------------------------------------
-
 /**
  * Handle for an ephemeral awareness channel.
  *
@@ -142,6 +134,14 @@ export class AwarenessHandle<T = unknown> {
     };
   }
 
+  /** Returns a Stream that emits the peer entries on every change. */
+  stream(): Stream.Stream<AwarenessEntry<T>[], never, never> {
+    return Stream.async<AwarenessEntry<T>[]>((emit) => {
+      const unsub = this.onChange((entries) => { void emit(Effect.succeed(Chunk.of(entries))); });
+      return Effect.sync(unsub);
+    });
+  }
+
   private emit(): void {
     const entries = this.peers();
     for (const fn of this.listeners) fn(entries);

package/src/crdt/crdtmap.ts

@@ -1,3 +1,4 @@
+import { Chunk, Effect, Stream } from "effect";
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { CRDTMapDelta, CrdtValueDelta } from "../sync/delta.js";
@@ -56,6 +57,14 @@ export class CRDTMapHandle {
     return () => { this.listeners.delete(listener); };
   }
 
+  /** Returns a Stream that emits the map value on every change. */
+  stream(): Stream.Stream<CrdtMapValue, never, never> {
+    return Stream.async<CrdtMapValue>((emit) => {
+      const unsub = this.onChange((value) => { void emit(Effect.succeed(Chunk.of(value))); });
+      return Effect.sync(unsub);
+    });
+  }
+
   /** Increment a GCounter key by `amount` (default `1`). */
   incrementCounter(key: string, amount: number = 1, ttlMs?: number): void {
     if (amount <= 0) throw new RangeError("CRDTMap.incrementCounter: amount must be > 0");

package/src/crdt/gcounter.ts

@@ -1,3 +1,4 @@
+import { Chunk, Effect, Stream } from "effect";
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { GCounterDelta } from "../sync/delta.js";
@@ -55,6 +56,14 @@ export class GCounterHandle {
     return () => { this.listeners.delete(listener); };
   }
 
+  /** Returns an Effect Stream that emits the counter value on every change. */
+  stream(): Stream.Stream<number, never, never> {
+    return Stream.async<number>((emit) => {
+      const unsub = this.onChange((value) => { void emit(Effect.succeed(Chunk.of(value))); });
+      return Effect.sync(unsub);
+    });
+  }
+
   /**
    * Increments the counter by `amount` (default `1`) and broadcasts the delta.
    *

package/src/crdt/lwwregister.ts

@@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import { Chunk, Effect, Schema, Stream } from "effect";
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { LwwDelta, LwwEntry } from "../sync/delta.js";
@@ -59,6 +59,14 @@ export class LwwRegisterHandle<T> {
     return () => { this.listeners.delete(listener); };
   }
 
+  /** Returns a Stream that emits the register value (or null) on every change. */
+  stream(): Stream.Stream<T | null, never, never> {
+    return Stream.async<T | null>((emit) => {
+      const unsub = this.onChange((value) => { void emit(Effect.succeed(Chunk.of(value))); });
+      return Effect.sync(unsub);
+    });
+  }
+
   /**
    * Writes `value` to the register and broadcasts the operation.
    *

package/src/crdt/orset.ts

@@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import { Chunk, Effect, Schema, Stream } from "effect";
 import { encode, uuidToBytes } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { ORSetDelta } from "../sync/delta.js";
@@ -54,6 +54,14 @@ export class ORSetHandle<T> {
     return () => { this.listeners.delete(listener); };
   }
 
+  /** Returns a Stream that emits the set elements on every change. */
+  stream(): Stream.Stream<T[], never, never> {
+    return Stream.async<T[]>((emit) => {
+      const unsub = this.onChange((elements) => { void emit(Effect.succeed(Chunk.of(elements))); });
+      return Effect.sync(unsub);
+    });
+  }
+
   /**
    * Adds `element` to the set and broadcasts the operation.
    *

package/src/crdt/pncounter.ts

@@ -1,3 +1,4 @@
+import { Chunk, Effect, Stream } from "effect";
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { PNCounterDelta } from "../sync/delta.js";
@@ -50,6 +51,14 @@ export class PNCounterHandle {
     return () => { this.listeners.delete(listener); };
   }
 
+  /** Returns a Stream that emits the counter value on every change. */
+  stream(): Stream.Stream<number, never, never> {
+    return Stream.async<number>((emit) => {
+      const unsub = this.onChange((value) => { void emit(Effect.succeed(Chunk.of(value))); });
+      return Effect.sync(unsub);
+    });
+  }
+
   /**
    * Increments the counter by `amount` (default `1`) and broadcasts the delta.
    *

package/src/crdt/presence.ts

@@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import { Chunk, Effect, Schema, Stream } from "effect";
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { PresenceDelta, PresenceEntryDelta } from "../sync/delta.js";
@@ -60,6 +60,14 @@ export class PresenceHandle<T> {
     return () => { this.listeners.delete(listener); };
   }
 
+  /** Returns a Stream that emits the online entries on every change. */
+  stream(): Stream.Stream<PresenceEntry<T>[], never, never> {
+    return Stream.async<PresenceEntry<T>[]>((emit) => {
+      const unsub = this.onChange((entries) => { void emit(Effect.succeed(Chunk.of(entries))); });
+      return Effect.sync(unsub);
+    });
+  }
+
   /**
    * Broadcasts a heartbeat that marks the current client as online for `ttlMs`
    * milliseconds (default `30 000`).

package/src/crdt/rga.ts

@@ -0,0 +1,136 @@
+import { Chunk, Effect, Stream } from "effect";
+import { encode } from "../codec.js";
+import type { WsTransport } from "../transport/websocket.js";
+import type { RGADelta } from "../sync/delta.js";
+
+/**
+ * Low-level handle for an RGA (Replicated Growable Array) CRDT — collaborative text editing.
+ *
+ * Obtained via `MeridianClient.rga()`. The RGA converges concurrent edits from multiple
+ * clients using Hybrid Logical Clock IDs and left-origin insertion ordering.
+ *
+ * Operations use visible-position indices (tombstones are invisible to callers).
+ */
+export class RGAHandle {
+  private text = "";
+  private readonly crdtId: string;
+  private readonly clientId: number;
+  private readonly transport: WsTransport;
+  private readonly listeners = new Set<(value: string) => void>();
+
+  constructor(opts: {
+    crdtId: string;
+    clientId: number;
+    transport: WsTransport;
+  }) {
+    this.crdtId = opts.crdtId;
+    this.clientId = opts.clientId;
+    this.transport = opts.transport;
+  }
+
+  /** Returns the current text content. */
+  value(): string {
+    return this.text;
+  }
+
+  /**
+   * Registers a listener called whenever the text changes.
+   *
+   * @returns An unsubscribe function.
+   */
+  onChange(listener: (value: string) => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /** Returns an Effect Stream that emits the text on every change. */
+  stream(): Stream.Stream<string, never, never> {
+    return Stream.async<string>((emit) => {
+      const unsub = this.onChange((value) => { void emit(Effect.succeed(Chunk.of(value))); });
+      return Effect.sync(unsub);
+    });
+  }
+
+  /**
+   * Inserts `text` at visible position `pos` (0 = before all characters).
+   * Characters are inserted one by one in order using the RGA Insert op.
+   *
+   * @param pos  - Visible character position (0-indexed).
+   * @param text - String to insert.
+   * @param ttlMs - Optional TTL for the op.
+   */
+  insert(pos: number, text: string, ttlMs?: number): void {
+    if (text.length === 0) return;
+
+    // Optimistic local update.
+    this.text = this.text.slice(0, pos) + text + this.text.slice(pos);
+    this.emit();
+
+    // Send each character as a separate RGA Insert op. The server reorders
+    // them using their HLC IDs — sending individually preserves per-char identity.
+    const wallMs = Date.now();
+    for (let i = 0; i < text.length; i++) {
+      const op = encode({
+        RGA: {
+          Insert: {
+            id: { wall_ms: wallMs, logical: i, node_id: this.clientId },
+            origin_id: pos + i === 0 ? null : null, // server resolves via WAL
+            content: text[i],
+          },
+        },
+      });
+      this.transport.send({
+        Op: {
+          crdt_id: this.crdtId,
+          op_bytes: op,
+          ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
+        },
+      });
+    }
+  }
+
+  /**
+   * Deletes `length` visible characters starting at visible position `pos`.
+   *
+   * @param pos    - Visible character position (0-indexed).
+   * @param length - Number of characters to delete.
+   * @param ttlMs  - Optional TTL for the op.
+   */
+  delete(pos: number, length: number, ttlMs?: number): void {
+    if (length <= 0) return;
+
+    // Optimistic local update.
+    this.text = this.text.slice(0, pos) + this.text.slice(pos + length);
+    this.emit();
+
+    // Send a single Delete op per character position.
+    // The server resolves the actual RGA node IDs from position.
+    for (let i = 0; i < length; i++) {
+      const op = encode({
+        RGA: {
+          Delete: {
+            pos: pos + i,
+          },
+        },
+      });
+      this.transport.send({
+        Op: {
+          crdt_id: this.crdtId,
+          op_bytes: op,
+          ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
+        },
+      });
+    }
+  }
+
+  /** Apply a delta received from the server. Replaces local text with authoritative state. */
+  applyDelta(delta: RGADelta): void {
+    if (delta.text === this.text) return;
+    this.text = delta.text;
+    this.emit();
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) listener(this.text);
+  }
+}