@pylonsync/loro 0.22.38 → 0.22.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/loro",
-  "version": "0.22.38",
+  "version": "0.22.40",
   "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,21 +12,24 @@
     ".": "./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",
+    "./prosemirror/sync": "./src/prosemirror/sync.ts"
   },
   "scripts": {
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/react": "0.22.38",
-    "@pylonsync/sync": "0.22.38",
+    "@pylonsync/react": "0.22.40",
+    "@pylonsync/sync": "0.22.40",
     "loro-crdt": "^1.10.6"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
     "loro-prosemirror": ">=0.4.4 <1.0.0",
     "prosemirror-model": "^1.22.0",
-    "prosemirror-state": "^1.4.0"
+    "prosemirror-state": "^1.4.0",
+    "prosemirror-view": "^1.33.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
@@ -34,7 +37,9 @@
     "loro-prosemirror": "^0.4.4",
     "prosemirror-model": "^1.25.0",
     "prosemirror-state": "^1.4.3",
-    "prosemirror-schema-basic": "^1.2.4"
+    "prosemirror-schema-basic": "^1.2.4",
+    "prosemirror-view": "^1.42.3",
+    "@happy-dom/global-registrator": "^20.10.0"
   },
   "peerDependenciesMeta": {
     "loro-prosemirror": {
@@ -45,6 +50,9 @@
     },
     "prosemirror-state": {
       "optional": true
+    },
+    "prosemirror-view": {
+      "optional": true
     }
   },
   "license": "MIT"

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);
+  });
+});