@pylonsync/loro 0.22.34 → 0.22.35

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Campbell Venture Studio, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/loro",
-  "version": "0.22.34",
+  "version": "0.22.35",
   "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"
@@ -11,21 +11,41 @@
   "exports": {
     ".": "./src/index.ts",
     "./wire": "./src/wire.ts",
-    "./registry": "./src/registry.ts"
+    "./registry": "./src/registry.ts",
+    "./prosemirror": "./src/prosemirror.ts"
   },
   "scripts": {
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/react": "0.22.34",
-    "@pylonsync/sync": "0.22.34",
+    "@pylonsync/react": "0.22.35",
+    "@pylonsync/sync": "0.22.35",
     "loro-crdt": "^1.10.6"
   },
   "peerDependencies": {
-    "react": ">=19.0.0"
+    "react": ">=19.0.0",
+    "loro-prosemirror": ">=0.4.4 <1.0.0",
+    "prosemirror-model": "^1.22.0",
+    "prosemirror-state": "^1.4.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
-    "typescript": "^5.5"
-  }
+    "typescript": "^5.5",
+    "loro-prosemirror": "^0.4.4",
+    "prosemirror-model": "^1.25.0",
+    "prosemirror-state": "^1.4.3",
+    "prosemirror-schema-basic": "^1.2.4"
+  },
+  "peerDependenciesMeta": {
+    "loro-prosemirror": {
+      "optional": true
+    },
+    "prosemirror-model": {
+      "optional": true
+    },
+    "prosemirror-state": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
 }

package/src/prosemirror.test.ts

@@ -0,0 +1,134 @@
+// The ProseMirror helpers against the row-doc contract: the server creates
+// a prosemirror field's container under the "row" map when the row is
+// inserted (crates/crdt/src/prosemirror.rs); clients only bind to it.
+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 {
+  configureProseMirrorMarks,
+  findProseMirrorContainer,
+  readProseMirror,
+  waitForProseMirrorContainer,
+  writeProseMirror,
+} from "./prosemirror";
+
+// The basic schema plus a mark with an id, like a suggestion.
+const schema = new Schema({
+  nodes: basic.spec.nodes,
+  marks: basic.spec.marks.addToEnd("suggestion", {
+    attrs: { id: { default: null } },
+    inclusive: false,
+  }),
+});
+
+const doc = (...paragraphs: Array<Array<{ text: string; marks?: string[] }>>) =>
+  schema.node(
+    "doc",
+    null,
+    paragraphs.map((runs) =>
+      schema.node(
+        "paragraph",
+        null,
+        runs.map((r) =>
+          schema.text(
+            r.text,
+            (r.marks ?? []).map((m) => (m === "suggestion" ? schema.mark("suggestion", { id: "s1" }) : schema.mark(m))),
+          ),
+        ),
+      ),
+    ),
+  );
+
+function peer(id: bigint): LoroDoc {
+  const d = new LoroDoc();
+  d.setPeerId(id);
+  configureProseMirrorMarks(d, schema);
+  return d;
+}
+
+/** A row doc as the server makes it on insert: an empty container under row.body. */
+function serverRow(id: bigint): LoroDoc {
+  const d = peer(id);
+  d.getMap("row").set("title", "t");
+  d.getMap("row").setContainer("body", new LoroMap());
+  d.commit();
+  return d;
+}
+
+describe("ProseMirror documents in a row", () => {
+  test("the lookup never creates the container", () => {
+    const d = peer(1n);
+    expect(findProseMirrorContainer(d, "body")).toBeNull();
+    expect(d.getMap("row").get("body")).toBeUndefined();
+  });
+
+  // The case a review reproduced: useLoroDoc hands the editor an empty doc
+  // before the server's snapshot arrives. A container made then (cid:0@1)
+  // loses the key to the server's (cid:0@2), and the editor's edits never
+  // reach the row. Waiting binds to the server's container instead.
+  test("an editor that loads before the snapshot binds to the server's container", async () => {
+    const client = peer(1n);
+    const bound = waitForProseMirrorContainer(client, "body");
+    const server = serverRow(2n);
+    client.import(server.export({ mode: "snapshot" }));
+    const id = await bound;
+    expect(id).toBe(findProseMirrorContainer(server, "body")!);
+    expect(id).toContain("@2");
+
+    // The editor's first write lands in the container the server reads.
+    writeProseMirror(client, "body", schema, doc([{ text: "Typed " }, { text: "here", marks: ["strong"] }]));
+    server.import(client.export({ mode: "update", from: server.oplogVersion() }));
+    expect(readProseMirror(server, "body", schema)?.toJSON()).toEqual(
+      doc([{ text: "Typed " }, { text: "here", marks: ["strong"] }]).toJSON(),
+    );
+  });
+
+  test("waiting resolves at once when the container is there, and can be stopped", async () => {
+    const d = serverRow(2n);
+    expect(await waitForProseMirrorContainer(d, "body")).toBe(findProseMirrorContainer(d, "body")!);
+    const controller = new AbortController();
+    const pending = waitForProseMirrorContainer(peer(1n), "body", { signal: controller.signal });
+    controller.abort(new Error("closed"));
+    await expect(pending).rejects.toThrow("closed");
+  });
+
+  test("a write into a doc without the container throws instead of creating it", () => {
+    const d = peer(1n);
+    expect(() => writeProseMirror(d, "body", schema, doc([{ text: "x" }]))).toThrow("the server creates it");
+    expect(d.getMap("row").get("body")).toBeUndefined();
+  });
+
+  test("the server's empty container reads as null and takes a document", () => {
+    const d = serverRow(2n);
+    expect(readProseMirror(d, "body", schema)).toBeNull();
+    const source = doc([{ text: "Hello " }, { text: "world", marks: ["strong", "suggestion"] }], [{ text: "Second" }]);
+    writeProseMirror(d, "body", schema, source);
+    expect(readProseMirror(d, "body", schema)?.toJSON()).toEqual(source.toJSON());
+  });
+
+  test("concurrent edits from two peers converge", () => {
+    const a = serverRow(1n);
+    writeProseMirror(a, "body", schema, doc([{ text: "One" }], [{ text: "Two" }]));
+    const b = peer(2n);
+    b.import(a.export({ mode: "snapshot" }));
+    writeProseMirror(a, "body", schema, doc([{ text: "One!" }], [{ text: "Two" }]));
+    writeProseMirror(b, "body", schema, doc([{ text: "One" }], [{ text: "Two?" }]));
+    a.import(b.export({ mode: "update" }));
+    b.import(a.export({ mode: "update" }));
+    const left = readProseMirror(a, "body", schema)?.textContent;
+    expect(left).toBe(readProseMirror(b, "body", schema)?.textContent);
+    expect(left).toBe("One!Two?");
+  });
+
+  test("a server write reaches an editor's copy", () => {
+    const editor = serverRow(1n);
+    writeProseMirror(editor, "body", schema, doc([{ text: "Draft" }]));
+    const server = peer(2n);
+    server.import(editor.export({ mode: "snapshot" }));
+    const current = readProseMirror(server, "body", schema)!;
+    writeProseMirror(server, "body", schema, current.copy(current.content.append(doc([{ text: "Added by the server" }]).content)));
+    editor.import(server.export({ mode: "update", from: editor.oplogVersion() }));
+    expect(readProseMirror(editor, "body", schema)?.textContent).toBe("DraftAdded by the server");
+  });
+});

package/src/prosemirror.ts

@@ -0,0 +1,115 @@
+/**
+ * ProseMirror (Tiptap) documents in a Pylon row.
+ *
+ * A field declared `field.richtext().crdt("prosemirror")` keeps its
+ * document under its key of the row's `"row"` map, in the layout the
+ * `loro-prosemirror` binding writes. The server reads that tree and
+ * projects it to the row as ProseMirror JSON (crates/crdt).
+ *
+ * The server creates the field's container when the row is inserted.
+ * Clients never create it: `useLoroDoc` returns an empty doc before the
+ * server's snapshot arrives, and a container made in it would lose the
+ * key to the server's, leaving the editor bound to a container nothing
+ * reads. Wait for the server's instead, then bind:
+ *
+ *   const doc = useLoroDoc("Doc", id);
+ *   configureProseMirrorMarks(doc, schema);
+ *   const containerId = await waitForProseMirrorContainer(doc, "body");
+ *   const plugin = LoroSyncPlugin({ doc, containerId });
+ *
+ * In a server function, read and change the document without an editor
+ * with `readProseMirror` and `writeProseMirror`.
+ *
+ * A mark type holds one value per character: two marks of one type
+ * cannot overlap. Keep overlapping anchors (comment threads) as Loro
+ * cursors next to the document and draw them as decorations.
+ */
+import type { ContainerID, LoroDoc, LoroMap } from "loro-crdt";
+import { createNodeFromLoroObj, updateLoroToPmState } from "loro-prosemirror";
+import type { Node, Schema } from "prosemirror-model";
+import { EditorState } from "prosemirror-state";
+
+/** The root map every Pylon row doc keeps its fields in (crates/crdt). */
+const ROOT_MAP = "row";
+
+function fieldMap(doc: LoroDoc, field: string): LoroMap | null {
+  const value = doc.getMap(ROOT_MAP).get(field) as { kind?: () => string } | undefined;
+  return value && typeof value.kind === "function" && value.kind() === "Map"
+    ? (value as unknown as LoroMap)
+    : null;
+}
+
+/**
+ * The container of `field`'s document, or null when the doc does not hold
+ * it yet (the server's snapshot has not arrived). Never creates it.
+ */
+export function findProseMirrorContainer(doc: LoroDoc, field: string): ContainerID | null {
+  return fieldMap(doc, field)?.id ?? null;
+}
+
+/**
+ * The container of `field`'s document, once the doc holds it: at once when
+ * it is there, else when an import or edit brings it. Pass `signal` to stop
+ * waiting (the promise then rejects with the signal's reason).
+ */
+export function waitForProseMirrorContainer(
+  doc: LoroDoc,
+  field: string,
+  options: { signal?: AbortSignal } = {},
+): Promise<ContainerID> {
+  const found = findProseMirrorContainer(doc, field);
+  if (found) return Promise.resolve(found);
+  return new Promise((resolve, reject) => {
+    const { signal } = options;
+    const stop = doc.subscribe(() => {
+      const id = findProseMirrorContainer(doc, field);
+      if (!id) return;
+      stop();
+      signal?.removeEventListener("abort", onAbort);
+      resolve(id);
+    });
+    function onAbort() {
+      stop();
+      reject(signal?.reason ?? new Error("stopped waiting for the document"));
+    }
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Tell this copy of the doc how each mark of `schema` behaves at its
+ * edges, as the binding expects: a mark that is `inclusive` (the default)
+ * extends to text typed right after it. Every copy that writes marks
+ * needs this; Loro refuses a mark it has no style for.
+ */
+export function configureProseMirrorMarks(doc: LoroDoc, schema: Schema): void {
+  const styles: Record<string, { expand: "after" | "none" }> = {};
+  for (const [name, type] of Object.entries(schema.marks)) {
+    styles[name] = { expand: type.spec.inclusive !== false ? "after" : "none" };
+  }
+  doc.configTextStyle(styles);
+}
+
+/** The document in `field` as a ProseMirror node, or null when there is none. */
+export function readProseMirror(doc: LoroDoc, field: string, schema: Schema): Node | null {
+  const map = fieldMap(doc, field);
+  if (!map || map.get("nodeName") == null) return null;
+  return createNodeFromLoroObj(schema, map as never, new Map()) as Node;
+}
+
+/**
+ * Write `node` into `field` as a diff against what the doc holds, so edits
+ * other peers make at the same time still merge. Commits. Configures the
+ * schema's marks first. Throws when the doc has no container for the field
+ * (a row inserted by a server older than the field, or a doc that has not
+ * loaded); it never creates one.
+ */
+export function writeProseMirror(doc: LoroDoc, field: string, schema: Schema, node: Node): void {
+  const containerId = findProseMirrorContainer(doc, field);
+  if (!containerId) {
+    throw new Error(`The doc has no container for ${field}; the server creates it when the row is inserted.`);
+  }
+  configureProseMirrorMarks(doc, schema);
+  updateLoroToPmState(doc as never, new Map(), EditorState.create({ schema, doc: node }), containerId);
+}