@pylonsync/loro 0.3.281

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@pylonsync/loro",
+  "version": "0.3.281",
+  "description": "Pylon's local-first React layer — wraps loro-crdt with a registry, useLoroDoc hook, and the binary WS wire-format decoder that mirrors crates/router/encode_crdt_frame.",
+  "publishConfig": {
+  "access": "public"
+},
+"type": "module",
+"main": "src/index.ts",
+"types": "src/index.ts",
+"exports": {
+  ".": "./src/index.ts",
+  "./wire": "./src/wire.ts",
+  "./registry": "./src/registry.ts"
+},
+"scripts": {
+  "check": "tsc -p tsconfig.json --noEmit"
+},
+"dependencies": {
+  "@pylonsync/react": "0.3.281",
+  "@pylonsync/sync": "0.3.281",
+  "loro-crdt": "^1.10.6"
+},
+"peerDependencies": {
+  "react": ">=19.0.0"
+},
+"devDependencies": {
+  "@types/react": "^19.0.0",
+  "typescript": "^5.5"
+}
+}

package/src/index.ts

@@ -0,0 +1,398 @@
+// ---------------------------------------------------------------------------
+// @pylonsync/loro
+//
+// Local-first React layer on top of Pylon's CRDT broadcast.
+//
+//   import { useLoroDoc, getLoroText } from "@pylonsync/loro";
+//
+//   function MessageBody({ messageId }: { messageId: string }) {
+//     const doc = useLoroDoc("Message", messageId);
+//     const text = getLoroText(doc, "body").toString();
+//     return <p>{text}</p>;
+//   }
+//
+// The hook subscribes to binary CRDT frames the server broadcasts on
+// every CRDT-mode write. Two browser tabs editing the same row
+// converge through Loro's CRDT merge — concurrent same-field writes
+// don't lose data the way LWW would.
+// ---------------------------------------------------------------------------
+
+import { useSyncExternalStore, useEffect, useRef } from "react";
+import type { FormEvent, RefObject } from "react";
+import type { LoroDoc, LoroText, LoroMap } from "loro-crdt";
+import { db, getBaseUrl, getReactStorage, storageKey } from "@pylonsync/react";
+import { pylonFetch, type SyncEngine } from "@pylonsync/sync";
+import { globalRegistry, LoroRegistry } from "./registry";
+
+export { LoroRegistry, globalRegistry } from "./registry";
+export {
+  decodeCrdtFrame,
+  encodeCrdtFrame,
+  CRDT_FRAME_SNAPSHOT,
+  CRDT_FRAME_UPDATE,
+} from "./wire";
+export type { CrdtFrame } from "./wire";
+
+// ---------------------------------------------------------------------------
+// Sync engine ↔ registry wiring
+//
+// Connect once, lazily — the first useLoroDoc call sets up the binary
+// handler. Subsequent calls reuse the same registration. Re-registers
+// transparently on hot module reload (the registry's Set semantics
+// dedup the handler).
+// ---------------------------------------------------------------------------
+
+let attachedSync: SyncEngine | null = null;
+let unsubscribeBinaryHandler: (() => void) | null = null;
+let unsubscribeRowEviction: (() => void) | null = null;
+
+function ensureAttached(): void {
+  const sync = db.sync;
+  if (attachedSync === sync) return;
+
+  // Tear down the previous engine's handlers if init() swapped it
+  // (test harness or re-init at runtime).
+  if (unsubscribeBinaryHandler) {
+    unsubscribeBinaryHandler();
+    unsubscribeBinaryHandler = null;
+  }
+  if (unsubscribeRowEviction) {
+    unsubscribeRowEviction();
+    unsubscribeRowEviction = null;
+  }
+  unsubscribeBinaryHandler = sync.onBinaryFrame((bytes: Uint8Array) => {
+    globalRegistry.applyBinaryFrame(bytes);
+  });
+  // The server's `row-revoked` envelope signals that the subscriber's
+  // policy was revoked mid-session for a specific row. Drop the
+  // cached LoroDoc so the collaborative handle unmounts instead of
+  // lingering with stale state until the tab closes.
+  unsubscribeRowEviction = sync.addRowEvictionListener(
+    (entity: string, rowId: string) => {
+      globalRegistry.evict(entity, rowId);
+    },
+  );
+  attachedSync = sync;
+}
+
+// ---------------------------------------------------------------------------
+// React hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to the LoroDoc for a row. Returns the same doc instance
+ * across renders for the same `(entity, id)` pair. The doc updates
+ * in place as binary CRDT frames arrive from the server; React
+ * re-renders the calling component on every applied frame via
+ * `useSyncExternalStore`.
+ *
+ * The doc is the *source of truth* for CRDT-mode entities — local
+ * mutations should go through doc operations (`getText().insert(...)`,
+ * `getMap().set(...)`) rather than `db.update`. The server's
+ * SQLite-projected row catches up via the next binary frame.
+ *
+ * For `crdt: false` entities the LoroDoc stays empty (the server
+ * never broadcasts a frame for them). Use `db.useQueryOne(entity, id)`
+ * for those instead.
+ */
+export function useLoroDoc(entity: string, id: string): LoroDoc {
+  ensureAttached();
+
+  // Tell the server we want binary CRDT frames for this row. Refcounted
+  // inside the sync engine, so two components watching the same row
+  // don't fight over the subscription. Without this the server never
+  // sends a binary frame and the LoroDoc stays empty forever — the
+  // notifier filters by subscriber set rather than fanning out to
+  // every WS client.
+  //
+  // We use `useEffect` (not `useSyncExternalStore`'s subscribe) because
+  // the subscribe call is a side effect on the network, not a React
+  // store subscription. The store subscription stays registry-local
+  // and fires on every applied frame.
+  useEffect(() => {
+    const sync = db.sync;
+    sync.subscribeCrdt(entity, id);
+    return () => {
+      sync.unsubscribeCrdt(entity, id);
+    };
+  }, [entity, id]);
+
+  // useSyncExternalStore drives re-renders. The snapshot is the doc
+  // itself (referentially stable across calls — same instance from
+  // the registry), so React's bail-out keeps re-renders bounded to
+  // when the registry's listener actually fires.
+  const subscribe = (notify: () => void) =>
+    globalRegistry.subscribe(entity, id, notify);
+  const getSnapshot = () => globalRegistry.doc(entity, id);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Convenience: get a `LoroText` container at the given top-level key,
+ * creating it if absent. Wraps `doc.getText(key)` so callers don't
+ * have to import loro-crdt directly for the common case.
+ */
+export function getLoroText(doc: LoroDoc, key: string): LoroText {
+  return doc.getText(key);
+}
+
+/**
+ * Convenience: get a `LoroMap` container at the given top-level key.
+ */
+export function getLoroMap(doc: LoroDoc, key: string): LoroMap {
+  return doc.getMap(key);
+}
+
+/**
+ * High-level hook for the most common CRDT case: a single text field
+ * shared across clients. Returns `[value, setValue]` matching React's
+ * useState shape so existing controlled-input components drop in.
+ *
+ * Two tabs editing the same `(entity, id, field)` converge through
+ * Loro's text CRDT — concurrent same-position writes interleave
+ * deterministically rather than one stomping the other.
+ *
+ * `setValue` performs a whole-text replace on every call. Loro's
+ * text-CRDT update path treats this as a delete-then-insert against
+ * the prior version vector, so concurrent edits to disjoint regions
+ * still merge correctly. After applying locally, the hook ships the
+ * incremental update to the server (POST /api/crdt/<entity>/<id>),
+ * which re-projects to SQLite and broadcasts the merged snapshot
+ * back to every connected tab. A future variant could expose lower-
+ * level insert/delete ops for IME-friendly diff-aware editing.
+ *
+ * For boring CRUD use `db.useQueryOne` instead — this hook only
+ * lights up for entities marked `crdt: true` (the default) AND
+ * fields with `crdt: "text"` (or `richtext` type, which defaults
+ * to LoroText).
+ */
+export function useCollabText(
+  entity: string,
+  id: string,
+  field: string,
+): [string, (next: string) => void] {
+  const doc = useLoroDoc(entity, id);
+  const text = doc.getText(field);
+  const value = text.toString();
+  const setValue = (next: string): void => {
+    // Capture the version vector BEFORE the mutation so we can ship
+    // exactly the new ops to the server (incremental delta, not the
+    // whole snapshot). Loro's `export({mode: "update", from: vv})`
+    // returns the bytes the server hasn't seen.
+    const beforeVv = doc.oplogVersion();
+    const len = text.length;
+    if (len > 0) {
+      text.delete(0, len);
+    }
+    if (next.length > 0) {
+      text.insert(0, next);
+    }
+    doc.commit();
+
+    const update = doc.export({ mode: "update", from: beforeVv });
+    if (update.length === 0) {
+      return; // No-op (e.g. setValue called with the same value)
+    }
+    void pushCrdtUpdate(entity, id, update);
+  };
+  return [value, setValue];
+}
+
+/**
+ * Diff-aware collaborative binding for a `<textarea>` / `<input>` — the
+ * editor-grade counterpart to {@link useCollabText}.
+ *
+ * `useCollabText`'s `setValue` deletes the whole field and re-inserts it on
+ * every keystroke, which converges but moves the caret — fine for a one-line
+ * topic, jarring in a document editor. This hook instead computes the MINIMAL
+ * single splice between the old and new value (shared prefix + shared suffix)
+ * and applies just that `insert`/`delete` to the `LoroText`, shipping only the
+ * incremental delta. Remote frames are merged back into the element with the
+ * local caret remapped across the change, so two people typing in the same
+ * document don't fight over the cursor.
+ *
+ * LoroText indices are UTF-16 (matching JS string offsets and
+ * `selectionStart`/`selectionEnd`), so the prefix/suffix diff computed on the
+ * raw element value lines up with Loro exactly — no codepoint conversion, and
+ * astral characters (emoji) splice correctly.
+ *
+ * Spread the returned `ref` + `onInput` onto the element, and use
+ * `defaultValue` (NOT `value`) so the element stays uncontrolled and React
+ * re-renders never clobber the caret. `value` is the live text, handy for a
+ * side-by-side preview:
+ *
+ * ```tsx
+ * const { ref, value, onInput } = useCollabTextarea("Document", id, "content");
+ * return (
+ *   <>
+ *     <textarea ref={ref} defaultValue={value} onInput={onInput} />
+ *     <MarkdownPreview source={value} />
+ *   </>
+ * );
+ * ```
+ */
+export function useCollabTextarea<
+  T extends HTMLTextAreaElement | HTMLInputElement = HTMLTextAreaElement,
+>(
+  entity: string,
+  id: string,
+  field: string,
+): {
+  ref: RefObject<T | null>;
+  value: string;
+  onInput: (e: FormEvent<T>) => void;
+} {
+  const doc = useLoroDoc(entity, id);
+  const text = doc.getText(field);
+  const value = text.toString(); // re-renders on every applied frame
+  const ref = useRef<T | null>(null);
+  // The value we last reconciled into the DOM element. Lets us tell our own
+  // edits (element already correct — skip) from remote frames (patch the DOM).
+  const domValue = useRef<string>(value);
+
+  // Apply REMOTE changes to the element, preserving the caret. Runs after each
+  // render whose doc text differs from what the element currently shows.
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (el.value === value) {
+      domValue.current = value;
+      return;
+    }
+    const prev = el.value;
+    const selStart = el.selectionStart ?? prev.length;
+    const selEnd = el.selectionEnd ?? prev.length;
+    el.value = value;
+    try {
+      el.setSelectionRange(
+        remapCaret(prev, value, selStart),
+        remapCaret(prev, value, selEnd),
+      );
+    } catch {
+      // Some element types don't support setSelectionRange — ignore.
+    }
+    domValue.current = value;
+  }, [value]);
+
+  const onInput = (e: FormEvent<T>): void => {
+    const next = (e.target as T).value;
+    const prev = domValue.current;
+    if (next === prev) return;
+    const { index, deleteCount, insert } = spliceDiff(prev, next);
+    // Capture the version vector BEFORE mutating so we ship exactly the new ops.
+    const beforeVv = doc.oplogVersion();
+    if (deleteCount > 0) text.delete(index, deleteCount);
+    if (insert.length > 0) text.insert(index, insert);
+    doc.commit();
+    domValue.current = next;
+    const update = doc.export({ mode: "update", from: beforeVv });
+    if (update.length > 0) void pushCrdtUpdate(entity, id, update);
+  };
+
+  return { ref, value, onInput };
+}
+
+/**
+ * The minimal single splice that turns `prev` into `next`: shared prefix of
+ * length `index`, shared suffix, with the differing middle of `prev`
+ * (`deleteCount` chars) replaced by `insert`. UTF-16 units throughout to match
+ * LoroText.
+ */
+function spliceDiff(
+  prev: string,
+  next: string,
+): { index: number; deleteCount: number; insert: string } {
+  const max = Math.min(prev.length, next.length);
+  let p = 0;
+  while (p < max && prev.charCodeAt(p) === next.charCodeAt(p)) p++;
+  let s = 0;
+  while (
+    s < max - p &&
+    prev.charCodeAt(prev.length - 1 - s) === next.charCodeAt(next.length - 1 - s)
+  ) {
+    s++;
+  }
+  return {
+    index: p,
+    deleteCount: prev.length - p - s,
+    insert: next.slice(p, next.length - s),
+  };
+}
+
+/**
+ * Map a caret offset in `prev` to the equivalent offset in `next` across the
+ * single splice between them. Before the change → unchanged; after → shifted
+ * by the length delta; inside the replaced region → clamped to the splice end.
+ */
+function remapCaret(prev: string, next: string, caret: number): number {
+  const { index, deleteCount, insert } = spliceDiff(prev, next);
+  if (caret <= index) return caret;
+  if (caret >= index + deleteCount) {
+    return caret + (insert.length - deleteCount);
+  }
+  return index + insert.length;
+}
+
+// ---------------------------------------------------------------------------
+// Upstream push — POST /api/crdt/<entity>/<row_id>
+//
+// Wraps the binary Loro update in a JSON envelope ({update: hex}) so it
+// flows through Pylon's existing UTF-8-only HTTP body channel. Hex
+// (vs base64) keeps the encoder zero-dep on both sides; bandwidth
+// overhead is 2x, fine for the typical sub-1KB CRDT delta.
+// ---------------------------------------------------------------------------
+
+async function pushCrdtUpdate(
+  entity: string,
+  id: string,
+  update: Uint8Array,
+): Promise<void> {
+  try {
+    // Server acknowledges with {ok: true}. The merged-state broadcast
+    // arrives over the WS, applied automatically by the registry — no
+    // need to read the response body here, but pylonFetch surfaces
+    // structured errors so failed pushes log instead of vanishing.
+    await pylonFetch(
+      {
+        baseUrl: getBaseUrl(),
+        getToken: () =>
+          (getReactStorage().get(storageKey("token")) ?? undefined) as
+            | string
+            | undefined,
+      },
+      `/api/crdt/${encodeURIComponent(entity)}/${encodeURIComponent(id)}`,
+      {
+        method: "POST",
+        json: { update: bytesToHex(update) },
+      },
+    );
+  } catch (err) {
+    console.warn(`[loro] CRDT push failed for ${entity}/${id}:`, err);
+  }
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  const out = new Array<string>(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    out[i] = bytes[i].toString(16).padStart(2, "0");
+  }
+  return out.join("");
+}
+
+/**
+ * Manual teardown. Tests use this to drop the binary handler when
+ * spinning up multiple engines in sequence; production apps don't
+ * need to call it.
+ */
+export function detachLoro(): void {
+  if (unsubscribeBinaryHandler) {
+    unsubscribeBinaryHandler();
+    unsubscribeBinaryHandler = null;
+  }
+  if (unsubscribeRowEviction) {
+    unsubscribeRowEviction();
+    unsubscribeRowEviction = null;
+  }
+  attachedSync = null;
+}
+

package/src/registry.test.ts

@@ -0,0 +1,152 @@
+// ---------------------------------------------------------------------------
+// Registry tests. Exercise the doc cache + binary frame routing
+// in isolation from the WebSocket / SyncEngine plumbing.
+// ---------------------------------------------------------------------------
+
+import { test, expect } from "bun:test";
+import { LoroDoc } from "loro-crdt";
+import { LoroRegistry } from "./registry";
+import { CRDT_FRAME_SNAPSHOT, encodeCrdtFrame } from "./wire";
+
+test("doc() returns the same instance for the same row across calls", () => {
+  const reg = new LoroRegistry();
+  const a = reg.doc("Note", "n1");
+  const b = reg.doc("Note", "n1");
+  expect(a).toBe(b); // referential identity, not just equal
+});
+
+test("distinct (entity, rowId) pairs get distinct docs", () => {
+  const reg = new LoroRegistry();
+  const a = reg.doc("Note", "n1");
+  const b = reg.doc("Note", "n2");
+  const c = reg.doc("Other", "n1");
+  expect(a).not.toBe(b);
+  expect(a).not.toBe(c);
+  expect(b).not.toBe(c);
+  expect(reg.cachedRows()).toBe(3);
+});
+
+test("applyBinaryFrame imports a server snapshot into the right doc", () => {
+  // Build a Loro snapshot the way the server would.
+  const upstream = new LoroDoc();
+  upstream.getText("body").insert(0, "hello");
+  upstream.commit();
+  const snap = upstream.export({ mode: "snapshot" });
+  const frame = encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, "Note", "n1", snap);
+
+  const reg = new LoroRegistry();
+  const ok = reg.applyBinaryFrame(frame);
+  expect(ok).toBe(true);
+
+  const local = reg.doc("Note", "n1");
+  expect(local.getText("body").toString()).toBe("hello");
+});
+
+test("subscribe() fires on every applied frame", () => {
+  const reg = new LoroRegistry();
+  let calls = 0;
+  const unsub = reg.subscribe("Note", "n1", () => {
+    calls += 1;
+  });
+
+  const upstream = new LoroDoc();
+  upstream.getText("body").insert(0, "first");
+  upstream.commit();
+  reg.applyBinaryFrame(
+    encodeCrdtFrame(
+      CRDT_FRAME_SNAPSHOT,
+      "Note",
+      "n1",
+      upstream.export({ mode: "snapshot" }),
+    ),
+  );
+
+  upstream.getText("body").insert(5, " update");
+  upstream.commit();
+  reg.applyBinaryFrame(
+    encodeCrdtFrame(
+      CRDT_FRAME_SNAPSHOT,
+      "Note",
+      "n1",
+      upstream.export({ mode: "snapshot" }),
+    ),
+  );
+
+  expect(calls).toBe(2);
+  unsub();
+
+  // After unsub, future frames don't fire the listener.
+  upstream.getText("body").insert(0, "post-unsub ");
+  upstream.commit();
+  reg.applyBinaryFrame(
+    encodeCrdtFrame(
+      CRDT_FRAME_SNAPSHOT,
+      "Note",
+      "n1",
+      upstream.export({ mode: "snapshot" }),
+    ),
+  );
+  expect(calls).toBe(2);
+});
+
+test("subscribe() listener is per-row — sibling rows don't fire it", () => {
+  const reg = new LoroRegistry();
+  let n1Calls = 0;
+  let n2Calls = 0;
+  reg.subscribe("Note", "n1", () => (n1Calls += 1));
+  reg.subscribe("Note", "n2", () => (n2Calls += 1));
+
+  const doc = new LoroDoc();
+  doc.getText("body").insert(0, "x");
+  doc.commit();
+  const snap = doc.export({ mode: "snapshot" });
+
+  reg.applyBinaryFrame(encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, "Note", "n1", snap));
+  expect(n1Calls).toBe(1);
+  expect(n2Calls).toBe(0);
+
+  reg.applyBinaryFrame(encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, "Note", "n2", snap));
+  expect(n1Calls).toBe(1);
+  expect(n2Calls).toBe(1);
+});
+
+test("malformed binary frame returns false without crashing", () => {
+  const reg = new LoroRegistry();
+  expect(reg.applyBinaryFrame(new Uint8Array([0x10, 0x00]))).toBe(false);
+});
+
+test("unknown frame type returns false", () => {
+  const reg = new LoroRegistry();
+  // Type byte 0xFF isn't a recognized snapshot/update marker.
+  const frame = encodeCrdtFrame(0xff, "Note", "n1", new Uint8Array(0));
+  expect(reg.applyBinaryFrame(frame)).toBe(false);
+});
+
+test("two registries hydrated from snapshots converge after exchange", () => {
+  // End-to-end "two browser tabs" simulation. Each tab has its own
+  // registry; they exchange snapshots and converge to the same state.
+  const a = new LoroRegistry();
+  const b = new LoroRegistry();
+
+  // Tab A locally writes "from-a".
+  a.doc("Note", "n1").getText("body").insert(0, "from-a");
+  a.doc("Note", "n1").commit();
+  // Tab B locally writes "from-b".
+  b.doc("Note", "n1").getText("body").insert(0, "from-b");
+  b.doc("Note", "n1").commit();
+
+  // Each tab broadcasts its snapshot to the other.
+  const snapA = a.doc("Note", "n1").export({ mode: "snapshot" });
+  const snapB = b.doc("Note", "n1").export({ mode: "snapshot" });
+
+  a.applyBinaryFrame(encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, "Note", "n1", snapB));
+  b.applyBinaryFrame(encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, "Note", "n1", snapA));
+
+  // Both registries' docs converge — the result contains BOTH writes'
+  // characters in some deterministic Loro-merged order. The exact
+  // output isn't pinned (Loro picks one) but both replicas agree.
+  const aText = a.doc("Note", "n1").getText("body").toString();
+  const bText = b.doc("Note", "n1").getText("body").toString();
+  expect(aText).toBe(bText);
+  expect(aText.length).toBeGreaterThan(0);
+});

package/src/registry.ts

@@ -0,0 +1,138 @@
+// ---------------------------------------------------------------------------
+// LoroRegistry — per-row LoroDoc cache + binary-frame router
+//
+// One process-wide registry. The SyncEngine's binary handler routes
+// every incoming CRDT frame here; this class:
+//
+//   1. Decodes the frame
+//   2. Looks up (or creates) the LoroDoc for (entity, row_id)
+//   3. Imports the snapshot/update into the doc
+//   4. Notifies subscribers so React re-renders
+//
+// Architectural note: the server-side broadcast is currently
+// "send every CRDT update to every connected client" (see
+// docs/RUNTIME.md / loro_store.rs). The registry honors the same
+// shape — it doesn't filter incoming frames by interest. Apps that
+// don't subscribe to a row still create+update its LoroDoc as
+// frames arrive; harmless extra work, kept here so that when the
+// server eventually adds per-client subscriptions the client side
+// is ready to consume them.
+// ---------------------------------------------------------------------------
+
+import { LoroDoc } from "loro-crdt";
+import {
+  decodeCrdtFrame,
+  CRDT_FRAME_SNAPSHOT,
+  CRDT_FRAME_UPDATE,
+} from "./wire";
+
+type Listener = () => void;
+
+interface DocEntry {
+  doc: LoroDoc;
+  listeners: Set<Listener>;
+}
+
+export class LoroRegistry {
+  /** (entity, row_id) → cached LoroDoc + subscribers. Map key is
+   *  joined `entity:row_id` to keep the hash one-dimensional. */
+  private docs: Map<string, DocEntry> = new Map();
+
+  /** Get-or-create the doc for a row. The returned doc is the same
+   *  instance across calls so subscribers and consumers all see the
+   *  same CRDT state. Loro's per-doc peer_id is generated on first
+   *  construction; re-fetching the same row never produces a new
+   *  peer_id (which would fragment the merge graph). */
+  doc(entity: string, rowId: string): LoroDoc {
+    return this.entry(entity, rowId).doc;
+  }
+
+  /** Subscribe to changes on a row's doc. Returns an unsubscribe fn.
+   *  Calls the listener after every applied frame (snapshot or
+   *  update) and after every local mutation that triggers Loro's
+   *  internal subscribe events. */
+  subscribe(entity: string, rowId: string, listener: Listener): () => void {
+    const entry = this.entry(entity, rowId);
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+      // Don't drop the doc when listeners hit 0 — a future hook
+      // remount on the same row should see the same state. Eviction
+      // policy comes alongside the per-row subscribe protocol.
+    };
+  }
+
+  /** Apply a binary frame from the WebSocket. Decodes then routes to
+   *  the matching doc; notifies subscribers. Returns true when the
+   *  frame parsed and an entry was updated, false on decode failure
+   *  or unknown frame type. */
+  applyBinaryFrame(bytes: Uint8Array): boolean {
+    const frame = decodeCrdtFrame(bytes);
+    if (!frame) return false;
+    if (frame.type !== CRDT_FRAME_SNAPSHOT && frame.type !== CRDT_FRAME_UPDATE) {
+      return false;
+    }
+    const entry = this.entry(frame.entity, frame.rowId);
+    try {
+      entry.doc.import(frame.payload);
+    } catch (err) {
+      console.warn(
+        `[loro] import failed for ${frame.entity}/${frame.rowId}:`,
+        err,
+      );
+      return false;
+    }
+    for (const listener of entry.listeners) {
+      try {
+        listener();
+      } catch (err) {
+        console.warn("[loro] listener threw:", err);
+      }
+    }
+    return true;
+  }
+
+  /** Drop the cached doc for a row. Tests + the eventual eviction
+   *  policy. Subscribers receive a final notify before the entry
+   *  is removed so they can detect the drop and re-create their
+   *  view if needed. */
+  evict(entity: string, rowId: string): void {
+    const key = this.key(entity, rowId);
+    const entry = this.docs.get(key);
+    if (!entry) return;
+    for (const listener of entry.listeners) {
+      try {
+        listener();
+      } catch {
+        /* swallow — we're tearing down anyway */
+      }
+    }
+    this.docs.delete(key);
+  }
+
+  /** Number of cached docs. Diagnostic. */
+  cachedRows(): number {
+    return this.docs.size;
+  }
+
+  private entry(entity: string, rowId: string): DocEntry {
+    const key = this.key(entity, rowId);
+    let entry = this.docs.get(key);
+    if (!entry) {
+      entry = { doc: new LoroDoc(), listeners: new Set() };
+      this.docs.set(key, entry);
+    }
+    return entry;
+  }
+
+  private key(entity: string, rowId: string): string {
+    return `${entity}:${rowId}`;
+  }
+}
+
+/** Process-wide singleton. The React hook reaches for this rather than
+ *  threading the registry through context — every Pylon app is
+ *  single-tenant per process, so a global registry is the simpler
+ *  shape and matches how `db.useQuery` (singleton SyncEngine) already
+ *  works. */
+export const globalRegistry = new LoroRegistry();

package/src/wire.test.ts

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// Wire-format tests. Mirror the Rust-side tests in
+// `crates/router/src/lib.rs::crdt_frame_tests` so any divergence
+// between encoder and decoder fails loud here before it ships.
+// Run via: `bun test packages/loro/src/wire.test.ts`
+// ---------------------------------------------------------------------------
+
+import { test, expect } from "bun:test";
+import {
+  CRDT_FRAME_SNAPSHOT,
+  CRDT_FRAME_UPDATE,
+  decodeCrdtFrame,
+  encodeCrdtFrame,
+} from "./wire";
+
+test("encode + decode round-trips a snapshot frame", () => {
+  const payload = new Uint8Array([0xab, 0xcd, 0xef]);
+  const frame = encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, "Message", "msg_123", payload);
+  // Header: 1 + 2 + 7 ("Message") + 2 + 7 ("msg_123") + 3 = 22 bytes.
+  expect(frame.length).toBe(22);
+
+  const decoded = decodeCrdtFrame(frame);
+  expect(decoded).not.toBeNull();
+  expect(decoded!.type).toBe(CRDT_FRAME_SNAPSHOT);
+  expect(decoded!.entity).toBe("Message");
+  expect(decoded!.rowId).toBe("msg_123");
+  expect(Array.from(decoded!.payload)).toEqual([0xab, 0xcd, 0xef]);
+});
+
+test("matches Rust encoder byte-for-byte for the same input", () => {
+  // Identical to the `roundtrip_header_layout` test in
+  // crates/router/src/lib.rs::crdt_frame_tests. If this fails the
+  // wire formats have drifted between Rust and TS.
+  const frame = encodeCrdtFrame(
+    CRDT_FRAME_SNAPSHOT,
+    "Message",
+    "msg_123",
+    new Uint8Array([0xab, 0xcd, 0xef]),
+  );
+  expect(frame[0]).toBe(0x10);
+  expect(Array.from(frame.subarray(1, 3))).toEqual([0, 7]);
+  expect(new TextDecoder().decode(frame.subarray(3, 10))).toBe("Message");
+  expect(Array.from(frame.subarray(10, 12))).toEqual([0, 7]);
+  expect(new TextDecoder().decode(frame.subarray(12, 19))).toBe("msg_123");
+  expect(Array.from(frame.subarray(19, 22))).toEqual([0xab, 0xcd, 0xef]);
+});
+
+test("empty payload still carries headers", () => {
+  const frame = encodeCrdtFrame(CRDT_FRAME_UPDATE, "X", "y", new Uint8Array(0));
+  expect(frame.length).toBe(7);
+  expect(frame[0]).toBe(0x11);
+
+  const decoded = decodeCrdtFrame(frame);
+  expect(decoded!.entity).toBe("X");
+  expect(decoded!.rowId).toBe("y");
+  expect(decoded!.payload.length).toBe(0);
+});
+
+test("entity > u16 max throws", () => {
+  const huge = "x".repeat(0x10000);
+  expect(() =>
+    encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, huge, "y", new Uint8Array(0)),
+  ).toThrow(/exceeds u16/);
+});
+
+test("row_id > u16 max throws", () => {
+  const huge = "x".repeat(0x10000);
+  expect(() =>
+    encodeCrdtFrame(CRDT_FRAME_SNAPSHOT, "X", huge, new Uint8Array(0)),
+  ).toThrow(/exceeds u16/);
+});
+
+test("decodes a truncated frame as null instead of throwing", () => {
+  // A frame that claims entity_len=10 but only carries 3 bytes of entity.
+  const truncated = new Uint8Array([
+    CRDT_FRAME_SNAPSHOT,
+    0x00,
+    0x0a, // entity_len = 10
+    0x41,
+    0x42,
+    0x43, // only "ABC" — 3 bytes, not 10
+  ]);
+  expect(decodeCrdtFrame(truncated)).toBeNull();
+});
+
+test("decodes a too-short header (<5 bytes) as null", () => {
+  expect(decodeCrdtFrame(new Uint8Array([0x10, 0x00]))).toBeNull();
+  expect(decodeCrdtFrame(new Uint8Array(0))).toBeNull();
+});
+
+test("UTF-8 multi-byte chars in entity / row_id round-trip", () => {
+  // 文書 = 6 bytes UTF-8, not 2 chars × 1 byte. Entity-name length
+  // should be the BYTE length the encoder writes — exercising the
+  // u16-as-bytes-not-chars contract on both sides.
+  const frame = encodeCrdtFrame(
+    CRDT_FRAME_SNAPSHOT,
+    "文書",
+    "行_42",
+    new Uint8Array(0),
+  );
+  const decoded = decodeCrdtFrame(frame);
+  expect(decoded!.entity).toBe("文書");
+  expect(decoded!.rowId).toBe("行_42");
+});

package/src/wire.ts

@@ -0,0 +1,108 @@
+// ---------------------------------------------------------------------------
+// CRDT WebSocket wire format
+//
+// Mirror of `crates/router/src/lib.rs::encode_crdt_frame`. Frame layout:
+//
+//   [type: u8] [entity_len: u16 BE] [entity utf8]
+//   [row_id_len: u16 BE] [row_id utf8] [payload bytes]
+//
+// Type bytes:
+//   0x10 = full Loro snapshot
+//   0x11 = incremental Loro update
+//
+// Keep this in sync with the Rust encoder. A change to either side
+// without a matching change to the other corrupts every CRDT message
+// in flight.
+// ---------------------------------------------------------------------------
+
+export const CRDT_FRAME_SNAPSHOT = 0x10;
+export const CRDT_FRAME_UPDATE = 0x11;
+
+export interface CrdtFrame {
+  /** 0x10 (snapshot) or 0x11 (incremental update). */
+  type: number;
+  /** Entity name as declared in the manifest. */
+  entity: string;
+  /** Row ID — 40-char hex for Pylon-generated rows. */
+  rowId: string;
+  /** Loro binary payload. Snapshot or update bytes depending on `type`. */
+  payload: Uint8Array;
+}
+
+/**
+ * Decode a binary CRDT frame received over the WebSocket. Returns
+ * `null` on any parse failure (truncated frame, length-header overrun)
+ * — caller logs and drops; the next valid frame is independent.
+ *
+ * The router encoder bails on entity / row_id strings >65 KiB, so the
+ * decoder's malformed-input path is genuinely unreachable for frames
+ * the server emits. The defensive checks exist for cases where the
+ * client receives bytes from a custom proxy / test fixture / future
+ * protocol extension.
+ */
+export function decodeCrdtFrame(bytes: Uint8Array): CrdtFrame | null {
+  // Header is at minimum: type(1) + entity_len(2) + row_id_len(2) = 5 bytes.
+  if (bytes.length < 5) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const type = view.getUint8(0);
+  const entityLen = view.getUint16(1, false /* big-endian */);
+  const entityStart = 3;
+  const entityEnd = entityStart + entityLen;
+  if (entityEnd + 2 > bytes.length) return null;
+
+  const rowIdLen = view.getUint16(entityEnd, false);
+  const rowIdStart = entityEnd + 2;
+  const rowIdEnd = rowIdStart + rowIdLen;
+  if (rowIdEnd > bytes.length) return null;
+
+  const decoder = new TextDecoder();
+  const entity = decoder.decode(bytes.subarray(entityStart, entityEnd));
+  const rowId = decoder.decode(bytes.subarray(rowIdStart, rowIdEnd));
+  const payload = bytes.subarray(rowIdEnd);
+
+  return { type, entity, rowId, payload };
+}
+
+/**
+ * Encode a frame in the same format. Useful for tests / for any
+ * eventual client-to-server CRDT push (not yet wired). Throws on
+ * length-header overrun rather than truncating, matching the Rust
+ * encoder's failure mode.
+ */
+export function encodeCrdtFrame(
+  type: number,
+  entity: string,
+  rowId: string,
+  payload: Uint8Array,
+): Uint8Array {
+  const encoder = new TextEncoder();
+  const entityBytes = encoder.encode(entity);
+  const rowIdBytes = encoder.encode(rowId);
+  if (entityBytes.length > 0xffff) {
+    throw new Error(
+      `CRDT frame: entity name ${entityBytes.length} bytes exceeds u16 length limit (65535)`,
+    );
+  }
+  if (rowIdBytes.length > 0xffff) {
+    throw new Error(
+      `CRDT frame: row_id ${rowIdBytes.length} bytes exceeds u16 length limit (65535)`,
+    );
+  }
+  const out = new Uint8Array(
+    1 + 2 + entityBytes.length + 2 + rowIdBytes.length + payload.length,
+  );
+  const view = new DataView(out.buffer);
+  let offset = 0;
+  view.setUint8(offset, type);
+  offset += 1;
+  view.setUint16(offset, entityBytes.length, false);
+  offset += 2;
+  out.set(entityBytes, offset);
+  offset += entityBytes.length;
+  view.setUint16(offset, rowIdBytes.length, false);
+  offset += 2;
+  out.set(rowIdBytes, offset);
+  offset += rowIdBytes.length;
+  out.set(payload, offset);
+  return out;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "target": "ES2022"
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}