@pylonsync/loro 0.22.35 → 0.22.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/loro",
-  "version": "0.22.35",
+  "version": "0.22.39",
   "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"
@@ -12,14 +12,15 @@
     ".": "./src/index.ts",
     "./wire": "./src/wire.ts",
     "./registry": "./src/registry.ts",
-    "./prosemirror": "./src/prosemirror.ts"
+    "./prosemirror": "./src/prosemirror/index.ts",
+    "./prosemirror/react": "./src/prosemirror/react.ts"
   },
   "scripts": {
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/react": "0.22.35",
-    "@pylonsync/sync": "0.22.35",
+    "@pylonsync/react": "0.22.39",
+    "@pylonsync/sync": "0.22.39",
     "loro-crdt": "^1.10.6"
   },
   "peerDependencies": {

package/src/index.ts

@@ -27,6 +27,7 @@ import {
 import { db, getBaseUrl, getReactStorage, storageKey } from "@pylonsync/react";
 import { pylonFetch, type SyncEngine } from "@pylonsync/sync";
 import { globalRegistry, LoroRegistry } from "./registry";
+import { CrdtOutbox, type OutboxState } from "./outbox";
 
 export { LoroRegistry, globalRegistry } from "./registry";
 export {
@@ -36,6 +37,8 @@ export {
   CRDT_FRAME_UPDATE,
 } from "./wire";
 export type { CrdtFrame } from "./wire";
+export { CrdtOutbox, isRetryable } from "./outbox";
+export type { OutboxSend, OutboxState, OutboxOptions } from "./outbox";
 
 // ---------------------------------------------------------------------------
 // Sync engine ↔ registry wiring
@@ -73,12 +76,61 @@ function ensureAttached(): void {
   // lingering with stale state until the tab closes.
   unsubscribeRowEviction = sync.addRowEvictionListener(
     (entity: string, rowId: string) => {
+      disposeOutbox(entity, rowId);
       globalRegistry.evict(entity, rowId);
     },
   );
+  attachPageListeners();
   attachedSync = sync;
 }
 
+// ---------------------------------------------------------------------------
+// Outboxes — one per row doc, sending its local edits (see ./outbox.ts)
+//
+// Created the first time a component reads the row's doc and kept as long
+// as the doc: an editor that unmounts must not drop edits still in flight.
+// A row eviction (policy revoked) disposes both.
+// ---------------------------------------------------------------------------
+
+const outboxes = new Map<string, { doc: LoroDoc; outbox: CrdtOutbox }>();
+
+function outboxKey(entity: string, rowId: string): string {
+  return `${entity}:${rowId}`;
+}
+
+function outboxFor(entity: string, rowId: string, doc: LoroDoc): CrdtOutbox {
+  const key = outboxKey(entity, rowId);
+  const existing = outboxes.get(key);
+  if (existing && existing.doc === doc) return existing.outbox;
+  existing?.outbox.dispose();
+  const outbox = new CrdtOutbox(doc, (update, { keepalive }) =>
+    pushCrdtUpdate(entity, rowId, update, keepalive),
+  );
+  // A state change re-renders the row's readers (useLoroSendState).
+  outbox.subscribe(() => globalRegistry.touch(entity, rowId));
+  outboxes.set(key, { doc, outbox });
+  return outbox;
+}
+
+function disposeOutbox(entity: string, rowId: string): void {
+  const key = outboxKey(entity, rowId);
+  outboxes.get(key)?.outbox.dispose();
+  outboxes.delete(key);
+}
+
+let pageListenersAttached = false;
+
+function attachPageListeners(): void {
+  if (pageListenersAttached || typeof window === "undefined") return;
+  pageListenersAttached = true;
+  window.addEventListener("online", () => {
+    for (const { outbox } of outboxes.values()) outbox.retryNow();
+  });
+  window.addEventListener("pagehide", () => {
+    for (const { outbox } of outboxes.values()) outbox.flushOnHide();
+  });
+}
+
 // ---------------------------------------------------------------------------
 // React hooks
 // ---------------------------------------------------------------------------
@@ -133,7 +185,24 @@ export function useLoroDoc(entity: string, id: string): LoroDoc {
     globalRegistry.subscribe(entity, id, notify);
   const getVersion = () => globalRegistry.version(entity, id);
   useSyncExternalStore(subscribe, getVersion, getVersion);
-  return globalRegistry.doc(entity, id);
+  const doc = globalRegistry.doc(entity, id);
+  // Local edits (an editor binding's included) reach the server through
+  // the row's outbox.
+  useEffect(() => {
+    outboxFor(entity, id, doc);
+  }, [entity, id, doc]);
+  return doc;
+}
+
+/**
+ * Whether this tab's edits to a row have reached the server, for a
+ * "Saving" indicator or an error notice. See {@link OutboxState}.
+ * `rejected` means the server refused them (for example the person lost
+ * edit access); they stay in this tab only.
+ */
+export function useLoroSendState(entity: string, id: string): OutboxState {
+  useLoroDoc(entity, id);
+  return outboxes.get(outboxKey(entity, id))?.outbox.state ?? "idle";
 }
 
 /**
@@ -235,11 +304,6 @@ export function useCollabText(
   const value = resolveLoroText(doc, field)?.toString() ?? "";
   const setValue = (next: string): void => {
     const text = getLoroText(doc, field);
-    // 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);
@@ -248,14 +312,9 @@ export function useCollabText(
       text.insert(0, next);
     }
     doc.commit();
-    // Optimistic render: notify every consumer of this row NOW.
+    // Optimistic render: notify every consumer of this row NOW. The
+    // row's outbox sends the edit.
     globalRegistry.touch(entity, id);
-
-    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];
 }
@@ -343,20 +402,16 @@ export function useCollabTextarea<
     const prev = domValue.current;
     if (next === prev) return;
     const { index, deleteCount, insert } = spliceDiff(prev, next);
-    // Resolve the container per keystroke (see resolveLoroText) and
-    // capture the version vector BEFORE mutating so we ship exactly the
-    // new ops.
+    // Resolve the container per keystroke (see resolveLoroText).
     const text = getLoroText(doc, field);
-    const beforeVv = doc.oplogVersion();
     if (deleteCount > 0) text.delete(index, deleteCount);
     if (insert.length > 0) text.insert(index, insert);
     doc.commit();
     domValue.current = next;
     // Optimistic render: the preview (and any other consumer of this
-    // row) updates on the local commit, not on the server echo.
+    // row) updates on the local commit, not on the server echo. The row's
+    // outbox sends the edit.
     globalRegistry.touch(entity, id);
-    const update = doc.export({ mode: "update", from: beforeVv });
-    if (update.length > 0) void pushCrdtUpdate(entity, id, update);
   };
 
   return { ref, value, onInput };
@@ -416,29 +471,27 @@ async function pushCrdtUpdate(
   entity: string,
   id: string,
   update: Uint8Array,
+  keepalive: boolean,
 ): 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);
-  }
+  // Server acknowledges with {ok: true}. The merged-state broadcast
+  // arrives over the WS, applied automatically by the registry. A
+  // failure throws (PylonHttpError carries the status); the outbox
+  // decides whether to retry.
+  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) },
+      keepalive,
+    },
+  );
 }
 
 function bytesToHex(bytes: Uint8Array): string {
@@ -455,6 +508,8 @@ function bytesToHex(bytes: Uint8Array): string {
  * need to call it.
  */
 export function detachLoro(): void {
+  for (const { outbox } of outboxes.values()) outbox.dispose();
+  outboxes.clear();
   if (unsubscribeBinaryHandler) {
     unsubscribeBinaryHandler();
     unsubscribeBinaryHandler = null;

package/src/outbox.test.ts

@@ -0,0 +1,312 @@
+// CrdtOutbox against real LoroDocs. A fake server holds its own doc, merges
+// what clients send, and relays each merge to the other clients, the way
+// POST /api/crdt and the binary broadcast do.
+import { describe, expect, test } from "bun:test";
+import { LoroDoc, LoroMap } from "loro-crdt";
+import { Schema } from "prosemirror-model";
+import { schema as basic } from "prosemirror-schema-basic";
+import { CrdtOutbox, isRetryable, type OutboxSend } from "./outbox";
+import { readProseMirror, writeProseMirror } from "./prosemirror/index";
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+async function settle(): Promise<void> {
+  for (let i = 0; i < 20; i++) await tick();
+}
+
+function httpError(status: number): Error & { status: number } {
+  return Object.assign(new Error(`status ${status}`), { status });
+}
+
+class FakeServer {
+  readonly doc = new LoroDoc();
+  readonly received: Uint8Array[] = [];
+  private readonly clients = new Set<LoroDoc>();
+
+  connect(client: LoroDoc): void {
+    client.import(this.doc.export({ mode: "snapshot" }));
+    this.clients.add(client);
+  }
+
+  /** A send that merges into the server doc and relays to every client. */
+  sender(): OutboxSend {
+    return async (update) => {
+      this.received.push(update);
+      this.doc.import(update);
+      const merged = this.doc.export({ mode: "snapshot" });
+      for (const c of this.clients) c.import(merged);
+    };
+  }
+}
+
+function text(doc: LoroDoc): string {
+  return doc.getText("t").toString();
+}
+
+describe("CrdtOutbox", () => {
+  test("a local edit reaches the server and the other client", async () => {
+    const server = new FakeServer();
+    const a = new LoroDoc();
+    const b = new LoroDoc();
+    server.connect(a);
+    server.connect(b);
+    const outbox = new CrdtOutbox(a, server.sender());
+    a.getText("t").insert(0, "hello");
+    a.commit();
+    await settle();
+    expect(text(server.doc)).toBe("hello");
+    expect(text(b)).toBe("hello");
+    expect(outbox.state).toBe("idle");
+    expect(outbox.hasUnsent()).toBe(false);
+  });
+
+  test("two clients editing at once converge", async () => {
+    const server = new FakeServer();
+    const a = new LoroDoc();
+    const b = new LoroDoc();
+    server.connect(a);
+    server.connect(b);
+    new CrdtOutbox(a, server.sender());
+    new CrdtOutbox(b, server.sender());
+    a.getText("t").insert(0, "left ");
+    a.commit();
+    b.getText("t").insert(0, "right");
+    b.commit();
+    await settle();
+    expect(text(a)).toBe(text(b));
+    expect(text(server.doc)).toBe(text(a));
+    expect(text(a)).toContain("left");
+    expect(text(a)).toContain("right");
+  });
+
+  test("commits made during a request go out together in the next one", async () => {
+    const server = new FakeServer();
+    const a = new LoroDoc();
+    server.connect(a);
+    let release: () => void = () => {};
+    let calls = 0;
+    const send: OutboxSend = async (update, opts) => {
+      calls += 1;
+      if (calls === 1) await new Promise<void>((r) => (release = r));
+      await server.sender()(update, opts);
+    };
+    const outbox = new CrdtOutbox(a, send);
+    a.getText("t").insert(0, "a");
+    a.commit();
+    await tick();
+    expect(outbox.state).toBe("sending");
+    for (const ch of ["b", "c", "d"]) {
+      a.getText("t").insert(a.getText("t").length, ch);
+      a.commit();
+    }
+    await tick();
+    expect(calls).toBe(1);
+    release();
+    await settle();
+    expect(calls).toBe(2);
+    expect(text(server.doc)).toBe("abcd");
+  });
+
+  test("a failed request is sent again, with the edits made since", async () => {
+    const server = new FakeServer();
+    const a = new LoroDoc();
+    server.connect(a);
+    const timers: Array<() => void> = [];
+    let fail = true;
+    const send: OutboxSend = async (update, opts) => {
+      if (fail) throw new Error("network down");
+      await server.sender()(update, opts);
+    };
+    const outbox = new CrdtOutbox(a, send, {
+      setTimer: (fn) => timers.push(fn),
+      clearTimer: () => {},
+    });
+    a.getText("t").insert(0, "one ");
+    a.commit();
+    await settle();
+    expect(outbox.state).toBe("retrying");
+    expect(text(server.doc)).toBe("");
+    a.getText("t").insert(4, "two");
+    a.commit();
+    await settle();
+    expect(timers.length).toBe(1); // no second request while waiting
+    fail = false;
+    timers.shift()!();
+    await settle();
+    expect(text(server.doc)).toBe("one two");
+    expect(outbox.state).toBe("idle");
+  });
+
+  test("retry delays double up to the limit", async () => {
+    const a = new LoroDoc();
+    const delays: number[] = [];
+    const timers: Array<() => void> = [];
+    const outbox = new CrdtOutbox(a, async () => Promise.reject(httpError(503)), {
+      retryBaseMs: 100,
+      retryMaxMs: 300,
+      setTimer: (fn, ms) => {
+        delays.push(ms);
+        timers.push(fn);
+      },
+      clearTimer: () => {},
+    });
+    a.getText("t").insert(0, "x");
+    a.commit();
+    for (let i = 0; i < 4; i++) {
+      await settle();
+      timers.shift()!();
+    }
+    await settle();
+    expect(delays).toEqual([100, 200, 300, 300, 300]);
+    expect(outbox.state).toBe("retrying");
+  });
+
+  test("retryNow skips the wait", async () => {
+    const server = new FakeServer();
+    const a = new LoroDoc();
+    server.connect(a);
+    let fail = true;
+    const outbox = new CrdtOutbox(
+      a,
+      async (u, o) => {
+        if (fail) throw new Error("offline");
+        await server.sender()(u, o);
+      },
+      { setTimer: () => "handle", clearTimer: () => {} },
+    );
+    a.getText("t").insert(0, "x");
+    a.commit();
+    await settle();
+    fail = false;
+    outbox.retryNow();
+    await settle();
+    expect(text(server.doc)).toBe("x");
+  });
+
+  test("a refused edit stops the outbox", async () => {
+    const a = new LoroDoc();
+    let calls = 0;
+    const outbox = new CrdtOutbox(a, async () => {
+      calls += 1;
+      throw httpError(403);
+    });
+    a.getText("t").insert(0, "x");
+    a.commit();
+    await settle();
+    expect(outbox.state).toBe("rejected");
+    expect((outbox.error as { status: number }).status).toBe(403);
+    a.getText("t").insert(1, "y");
+    a.commit();
+    await settle();
+    expect(calls).toBe(1);
+    expect(outbox.hasUnsent()).toBe(true);
+  });
+
+  test("edits that came from the server are not sent back", async () => {
+    const server = new FakeServer();
+    const a = new LoroDoc();
+    const b = new LoroDoc();
+    server.connect(a);
+    server.connect(b);
+    new CrdtOutbox(b, server.sender());
+    // A large edit from b reaches a through the server.
+    b.getText("t").insert(0, "x".repeat(5000));
+    b.commit();
+    await settle();
+    const sends: Uint8Array[] = [];
+    const send = server.sender();
+    new CrdtOutbox(a, async (u, o) => {
+      sends.push(u);
+      await send(u, o);
+    });
+    a.getText("t").insert(0, "!");
+    a.commit();
+    await settle();
+    expect(sends.length).toBe(1);
+    expect(sends[0].length).toBeLessThan(200);
+    expect(text(b).startsWith("!")).toBe(true);
+  });
+
+  test("edits made before the outbox existed are sent", async () => {
+    const server = new FakeServer();
+    const a = new LoroDoc();
+    server.connect(a);
+    a.getText("t").insert(0, "early");
+    a.commit();
+    new CrdtOutbox(a, server.sender());
+    await settle();
+    expect(text(server.doc)).toBe("early");
+  });
+
+  test("flushOnHide sends with keepalive while a request is in flight", async () => {
+    const a = new LoroDoc();
+    const seen: boolean[] = [];
+    let release: () => void = () => {};
+    const outbox = new CrdtOutbox(a, async (_u, { keepalive }) => {
+      seen.push(keepalive);
+      if (!keepalive) await new Promise<void>((r) => (release = r));
+    });
+    a.getText("t").insert(0, "x");
+    a.commit();
+    await tick();
+    outbox.flushOnHide();
+    await settle();
+    expect(seen).toEqual([false, true]);
+    expect(outbox.hasUnsent()).toBe(false);
+    release();
+    await settle();
+  });
+
+  test("dispose stops sending", async () => {
+    const a = new LoroDoc();
+    let calls = 0;
+    const outbox = new CrdtOutbox(a, async () => {
+      calls += 1;
+    });
+    outbox.dispose();
+    a.getText("t").insert(0, "x");
+    a.commit();
+    await settle();
+    expect(calls).toBe(0);
+  });
+
+  test("a ProseMirror document edited in two copies converges", async () => {
+    const schema = new Schema({ nodes: basic.spec.nodes, marks: basic.spec.marks });
+    const server = new FakeServer();
+    // The server creates the field's container on insert.
+    server.doc.getMap("row").setContainer("body", new LoroMap());
+    server.doc.commit();
+    const a = new LoroDoc();
+    const b = new LoroDoc();
+    server.connect(a);
+    server.connect(b);
+    new CrdtOutbox(a, server.sender());
+    new CrdtOutbox(b, server.sender());
+    const para = (s: string) => schema.node("paragraph", null, [schema.text(s)]);
+    writeProseMirror(a, "body", schema, schema.node("doc", null, [para("from a")]));
+    await settle();
+    const current = readProseMirror(b, "body", schema)!;
+    writeProseMirror(b, "body", schema, current.copy(current.content.append(schema.node("doc", null, [para("from b")]).content)));
+    await settle();
+    const expected = ["from a", "from b"];
+    for (const d of [a, b, server.doc]) {
+      const node = readProseMirror(d, "body", schema)!;
+      const paragraphs: string[] = [];
+      node.forEach((n) => paragraphs.push(n.textContent));
+      expect(paragraphs).toEqual(expected);
+    }
+  });
+});
+
+describe("isRetryable", () => {
+  test("network errors, 5xx, 408 and 429 retry; other 4xx do not", () => {
+    expect(isRetryable(new Error("x"))).toBe(true);
+    expect(isRetryable(httpError(500))).toBe(true);
+    expect(isRetryable(httpError(503))).toBe(true);
+    expect(isRetryable(httpError(408))).toBe(true);
+    expect(isRetryable(httpError(429))).toBe(true);
+    expect(isRetryable(httpError(400))).toBe(false);
+    expect(isRetryable(httpError(403))).toBe(false);
+    expect(isRetryable(httpError(404))).toBe(false);
+  });
+});

package/src/outbox.ts

@@ -0,0 +1,214 @@
+// ---------------------------------------------------------------------------
+// CrdtOutbox — sends a doc's local edits to the server
+//
+// Every edit made on this copy of a row's doc (by an editor binding, a
+// hook, or app code) has to reach `POST /api/crdt/<entity>/<id>`. The
+// outbox listens for local commits and sends the edits the server has not
+// confirmed:
+//
+//   - One request at a time, so edits arrive in order. Commits made while
+//     a request is in flight go out together in the next one.
+//   - What it sends is every op of this peer after the last confirmed one,
+//     so a failed request loses nothing: the next send carries it again.
+//     Ops of other peers are never sent back; they came from the server.
+//   - A network error or a 5xx, 408 or 429 retries with backoff. Any other
+//     4xx (policy denied, row gone, bad update) stops the outbox: sending
+//     the same edits again would fail the same way.
+//
+// The server merges idempotently, so an edit sent twice (a response lost
+// after the server applied it) does no harm.
+// ---------------------------------------------------------------------------
+
+import { VersionVector, type LoroDoc } from "loro-crdt";
+
+/** Send one update. Resolve when the server accepted it; reject otherwise.
+ *  A rejection with a numeric `status` is treated as the HTTP status. */
+export type OutboxSend = (update: Uint8Array, options: { keepalive: boolean }) => Promise<void>;
+
+/**
+ * - `idle`: the server has every local edit.
+ * - `sending`: a request is in flight.
+ * - `retrying`: the last request failed and a retry is scheduled.
+ * - `rejected`: the server refused the edits; nothing more is sent.
+ */
+export type OutboxState = "idle" | "sending" | "retrying" | "rejected";
+
+export interface OutboxOptions {
+  /** First retry delay. Doubles per failure up to `retryMaxMs`. */
+  retryBaseMs?: number;
+  retryMaxMs?: number;
+  /** Timer functions, replaceable in tests. */
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}
+
+/** True for an error the same request could get past by trying again. */
+export function isRetryable(err: unknown): boolean {
+  const status = (err as { status?: unknown } | null)?.status;
+  if (typeof status !== "number") return true; // network error, abort, timeout
+  return status >= 500 || status === 408 || status === 429;
+}
+
+export class CrdtOutbox {
+  private readonly doc: LoroDoc;
+  private readonly send: OutboxSend;
+  private readonly retryBaseMs: number;
+  private readonly retryMaxMs: number;
+  private readonly setTimer: (fn: () => void, ms: number) => unknown;
+  private readonly clearTimer: (handle: unknown) => void;
+  private readonly stopListening: () => void;
+  private readonly listeners = new Set<() => void>();
+
+  /** This peer's op counter the server has confirmed (exclusive end). */
+  private confirmed = 0;
+  private inFlight = false;
+  private retryHandle: unknown = null;
+  private failures = 0;
+  private disposed = false;
+  private _state: OutboxState = "idle";
+  private _error: unknown = null;
+
+  constructor(doc: LoroDoc, send: OutboxSend, options: OutboxOptions = {}) {
+    this.doc = doc;
+    this.send = send;
+    this.retryBaseMs = options.retryBaseMs ?? 500;
+    this.retryMaxMs = options.retryMaxMs ?? 10_000;
+    this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    this.clearTimer = options.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+    this.stopListening = doc.subscribeLocalUpdates(() => this.schedule());
+    // Edits made before the outbox existed go out now.
+    this.schedule();
+  }
+
+  get state(): OutboxState {
+    return this._state;
+  }
+
+  /** The error that made the outbox `rejected` or `retrying`. */
+  get error(): unknown {
+    return this._error;
+  }
+
+  /** True while some local edit has not been confirmed by the server. */
+  hasUnsent(): boolean {
+    return this.ownCounter() > this.confirmed;
+  }
+
+  /** Call `listener` on every state change. Returns the unsubscribe. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Send unconfirmed edits now, unless a request is already in flight. */
+  schedule(): void {
+    if (this.disposed || this._state === "rejected") return;
+    if (this.inFlight || this.retryHandle !== null) return; // picked up when that settles
+    void this.flush(false);
+  }
+
+  /** Skip the backoff wait (the browser came back online). */
+  retryNow(): void {
+    if (this.retryHandle === null) return;
+    this.clearTimer(this.retryHandle);
+    this.retryHandle = null;
+    this.schedule();
+  }
+
+  /**
+   * Last chance before the page goes away: send what is unconfirmed with
+   * `keepalive`, so the browser finishes the request after the page is gone.
+   * Runs even while a request is in flight; the server merges duplicates.
+   */
+  flushOnHide(): void {
+    if (this.disposed || this._state === "rejected") return;
+    const update = this.unsent();
+    if (!update) return;
+    const target = this.ownCounter();
+    this.send(update, { keepalive: true }).then(
+      () => this.confirm(target),
+      () => {
+        /* the regular path retries if the page stays */
+      },
+    );
+  }
+
+  /** Stop listening and cancel a pending retry. Edits not sent are dropped. */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.stopListening();
+    if (this.retryHandle !== null) {
+      this.clearTimer(this.retryHandle);
+      this.retryHandle = null;
+    }
+    this.listeners.clear();
+  }
+
+  private ownCounter(): number {
+    return this.doc.oplogVersion().get(this.doc.peerIdStr) ?? 0;
+  }
+
+  /** This peer's ops after `confirmed`, or null when there are none. */
+  private unsent(): Uint8Array | null {
+    if (!this.hasUnsent()) return null;
+    // Start from everything the doc has, then roll this peer back to what
+    // the server confirmed: the export is exactly this peer's new ops.
+    const from = this.doc.oplogVersion().toJSON();
+    if (this.confirmed > 0) from.set(this.doc.peerIdStr, this.confirmed);
+    else from.delete(this.doc.peerIdStr);
+    return this.doc.export({ mode: "update", from: VersionVector.parseJSON(from) });
+  }
+
+  private confirm(counter: number): void {
+    if (counter > this.confirmed) this.confirmed = counter;
+  }
+
+  private async flush(keepalive: boolean): Promise<void> {
+    const update = this.unsent();
+    if (!update) {
+      this.setState("idle", null);
+      return;
+    }
+    const target = this.ownCounter();
+    this.inFlight = true;
+    this.setState("sending", null);
+    try {
+      await this.send(update, { keepalive });
+      this.confirm(target);
+      this.failures = 0;
+    } catch (err) {
+      this.inFlight = false;
+      if (this.disposed) return;
+      if (!isRetryable(err)) {
+        this.setState("rejected", err);
+        return;
+      }
+      this.failures += 1;
+      const delay = Math.min(this.retryMaxMs, this.retryBaseMs * 2 ** (this.failures - 1));
+      this.setState("retrying", err);
+      this.retryHandle = this.setTimer(() => {
+        this.retryHandle = null;
+        this.schedule();
+      }, delay);
+      return;
+    }
+    this.inFlight = false;
+    if (this.disposed) return;
+    if (this.hasUnsent()) void this.flush(false);
+    else this.setState("idle", null);
+  }
+
+  private setState(state: OutboxState, error: unknown): void {
+    if (this._state === state && this._error === error) return;
+    this._state = state;
+    this._error = error;
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch (err) {
+        console.warn("[loro] outbox listener threw:", err);
+      }
+    }
+  }
+}

package/src/{prosemirror.test.ts → prosemirror/index.test.ts}

@@ -11,7 +11,7 @@ import {
   readProseMirror,
   waitForProseMirrorContainer,
   writeProseMirror,
-} from "./prosemirror";
+} from "./index";
 
 // The basic schema plus a mark with an id, like a suggestion.
 const schema = new Schema({

package/src/prosemirror/react.ts

@@ -0,0 +1,31 @@
+/**
+ * React binding for a ProseMirror (Tiptap) field.
+ *
+ *   const { doc, containerId } = useProseMirrorDoc("Doc", id, "body", schema);
+ *   if (!containerId) return <Loading />;
+ *   const plugins = [LoroSyncPlugin({ doc, containerId }), LoroUndoPlugin({ doc })];
+ *
+ * `containerId` is null until the server's snapshot brings the field's
+ * container; mount the editor after that (see ./index.ts for why a client
+ * never creates it). Edits the editor makes reach the server through the
+ * row's outbox, like every edit on a `useLoroDoc` doc.
+ */
+import type { ContainerID, LoroDoc } from "loro-crdt";
+import type { Schema } from "prosemirror-model";
+import { useMemo } from "react";
+import { useLoroDoc } from "../index";
+import { configureProseMirrorMarks, findProseMirrorContainer } from "./index";
+
+export function useProseMirrorDoc(
+  entity: string,
+  id: string,
+  field: string,
+  schema: Schema,
+): { doc: LoroDoc; containerId: ContainerID | null } {
+  const doc = useLoroDoc(entity, id);
+  // Before any binding writes a mark. Idempotent, so once per doc is enough.
+  useMemo(() => configureProseMirrorMarks(doc, schema), [doc, schema]);
+  // useLoroDoc re-renders on every applied frame, so this picks up the
+  // container as soon as the snapshot lands.
+  return { doc, containerId: findProseMirrorContainer(doc, field) };
+}