@pylonsync/loro 0.22.39 → 0.22.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/loro",
-  "version": "0.22.39",
+  "version": "0.22.41",
   "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"
@@ -13,21 +13,25 @@
     "./wire": "./src/wire.ts",
     "./registry": "./src/registry.ts",
     "./prosemirror": "./src/prosemirror/index.ts",
-    "./prosemirror/react": "./src/prosemirror/react.ts"
+    "./prosemirror/react": "./src/prosemirror/react.ts",
+    "./prosemirror/sync": "./src/prosemirror/sync.ts",
+    "./server": "./src/server.ts",
+    "./prosemirror/cursors": "./src/prosemirror/cursors.ts"
   },
   "scripts": {
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/react": "0.22.39",
-    "@pylonsync/sync": "0.22.39",
+    "@pylonsync/react": "0.22.41",
+    "@pylonsync/sync": "0.22.41",
     "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",
@@ -35,7 +39,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": {
@@ -46,6 +52,9 @@
     },
     "prosemirror-state": {
       "optional": true
+    },
+    "prosemirror-view": {
+      "optional": true
     }
   },
   "license": "MIT"

package/src/outbox.ts

@@ -42,6 +42,22 @@ export interface OutboxOptions {
   clearTimer?: (handle: unknown) => void;
 }
 
+/** This peer's op counter in `doc` (exclusive end). */
+export function ownCounter(doc: LoroDoc): number {
+  return doc.oplogVersion().get(doc.peerIdStr) ?? 0;
+}
+
+/**
+ * This peer's ops after counter `confirmed`, and no one else's: start from
+ * everything the doc has, then roll this peer back to `confirmed`.
+ */
+export function exportOwnOps(doc: LoroDoc, confirmed: number): Uint8Array {
+  const from = doc.oplogVersion().toJSON();
+  if (confirmed > 0) from.set(doc.peerIdStr, confirmed);
+  else from.delete(doc.peerIdStr);
+  return doc.export({ mode: "update", from: VersionVector.parseJSON(from) });
+}
+
 /** 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;
@@ -146,18 +162,13 @@ export class CrdtOutbox {
   }
 
   private ownCounter(): number {
-    return this.doc.oplogVersion().get(this.doc.peerIdStr) ?? 0;
+    return ownCounter(this.doc);
   }
 
   /** 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) });
+    return exportOwnOps(this.doc, this.confirmed);
   }
 
   private confirm(counter: number): void {

package/src/prosemirror/cursors.test.ts

@@ -0,0 +1,112 @@
+// Remote carets between two real editors (happy-dom) bound to two LoroDocs.
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+if (!globalThis.document) GlobalRegistrator.register();
+
+import { afterEach, expect, test } from "bun:test";
+import { LoroDoc, LoroList, LoroMap, type ContainerID } from "loro-crdt";
+import { Schema } from "prosemirror-model";
+import { schema as basic } from "prosemirror-schema-basic";
+import { EditorState, TextSelection } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+import { proseMirrorCursorsKey, ProseMirrorCursorsPlugin, encodeSelection, setRemoteCursors, type EncodedSelection } from "./cursors";
+import { configureProseMirrorMarks, findProseMirrorContainer } from "./index";
+import { ProseMirrorSyncPlugin } from "./sync";
+
+const schema = new Schema({ nodes: basic.spec.nodes, marks: basic.spec.marks });
+const tick = () => new Promise((r) => setTimeout(r, 0));
+const views: EditorView[] = [];
+afterEach(() => {
+  for (const v of views.splice(0)) v.destroy();
+});
+
+function setup() {
+  const server = new LoroDoc();
+  const body = server.getMap("row").setContainer("body", new LoroMap());
+  body.setContainer("attributes", new LoroMap());
+  body.setContainer("children", new LoroList());
+  server.commit();
+  const docs = [new LoroDoc(), new LoroDoc()];
+  for (const d of docs) {
+    d.import(server.export({ mode: "snapshot" }));
+    configureProseMirrorMarks(d, schema);
+  }
+  const containerId = findProseMirrorContainer(docs[0], "body") as ContainerID;
+  const sent: EncodedSelection[] = [];
+  const make = (doc: LoroDoc, onSelection?: (s: EncodedSelection) => void) => {
+    const view = new EditorView(document.createElement("div"), {
+      state: EditorState.create({
+        schema,
+        plugins: [ProseMirrorSyncPlugin({ doc, containerId }), ProseMirrorCursorsPlugin({ doc, containerId, onSelection })],
+      }),
+    });
+    views.push(view);
+    return view;
+  };
+  const a = make(docs[0], (s) => sent.push(s));
+  const b = make(docs[1]);
+  const sync = () => {
+    for (const from of docs) server.import(from.export({ mode: "update", from: server.oplogVersion() }));
+    const all = server.export({ mode: "snapshot" });
+    for (const to of docs) to.import(all);
+  };
+  return { a, b, docs, containerId, sync, sent };
+}
+
+const type = (v: EditorView, s: string) => {
+  for (const ch of s) v.dispatch(v.state.tr.insertText(ch));
+};
+const caretAt = (v: EditorView, pos: number) => v.dispatch(v.state.tr.setSelection(TextSelection.create(v.state.doc, pos)));
+function decorationsOf(v: EditorView): Array<{ from: number; to: number; spec: { key?: string } }> {
+  const plugin = v.state.plugins.find((p) => p.spec.key === proseMirrorCursorsKey)!;
+  const set = plugin.props.decorations!.call(plugin, v.state) as { find(): Array<{ from: number; to: number; spec: { key?: string } }> };
+  return set.find();
+}
+const caretPositions = (v: EditorView) =>
+  decorationsOf(v)
+    .filter((d) => d.spec.key?.startsWith("caret-"))
+    .map((d) => d.from);
+
+test("a remote caret appears where the other person's caret is, and stays on its words", async () => {
+  const { a, b, docs, containerId, sync } = setup();
+  await tick();
+  type(a, "hello world");
+  sync();
+  caretAt(a, 7); // after "hello "
+  const selection = encodeSelection(a.state, docs[0], containerId);
+  setRemoteCursors(b, [{ id: "a", name: "Ann", color: "#2563eb", selection }]);
+  expect(caretPositions(b)).toEqual([7]);
+  // B types before Ann's caret: it moves with her words.
+  caretAt(b, 1);
+  type(b, "oh ");
+  expect(caretPositions(b)).toEqual([10]);
+});
+
+test("a selection is drawn as a range", async () => {
+  const { a, b, docs, containerId, sync } = setup();
+  await tick();
+  type(a, "select me");
+  sync();
+  a.dispatch(a.state.tr.setSelection(TextSelection.create(a.state.doc, 1, 7)));
+  setRemoteCursors(b, [{ id: "a", name: "Ann", color: "#2563eb", selection: encodeSelection(a.state, docs[0], containerId) }]);
+  expect(decorationsOf(b).some((d) => d.from === 1 && d.to === 7)).toBe(true);
+});
+
+test("no peers, no decorations", async () => {
+  const { b } = setup();
+  await tick();
+  setRemoteCursors(b, []);
+  expect(caretPositions(b)).toEqual([]);
+});
+
+test("a remote caret stays when the character it follows is deleted", async () => {
+  const { a, b, docs, containerId, sync } = setup();
+  await tick();
+  type(a, "hello world");
+  sync();
+  caretAt(a, 7); // after "hello "
+  setRemoteCursors(b, [{ id: "a", name: "Ann", color: "#2563eb", selection: encodeSelection(a.state, docs[0], containerId) }]);
+  expect(caretPositions(b)).toEqual([7]);
+  // B deletes the space Ann's caret follows.
+  b.dispatch(b.state.tr.delete(6, 7));
+  expect(caretPositions(b)).toEqual([6]);
+});

package/src/prosemirror/cursors.ts

@@ -0,0 +1,172 @@
+/**
+ * Other people's carets and selections in a ProseMirror editor bound with
+ * ProseMirrorSyncPlugin.
+ *
+ * Each person's selection travels as two Loro cursors (encoded, base64),
+ * which point at characters, not positions: a caret stays on its words while
+ * anyone edits before it. Send them through the room tied to the row
+ * (`useRoom({ entity, id })`), so only people who may read the document see
+ * them:
+ *
+ *   const room = useRoom({ entity: "Doc", id }, me.id);
+ *   const plugin = ProseMirrorCursorsPlugin({
+ *     doc, containerId,
+ *     onSelection: (selection) => room.setPresence({ name, color, selection }),
+ *   });
+ *   // whenever room.peers changes:
+ *   setRemoteCursors(view, room.peers.map((p) => ({ id: p.id, ...p.presence })));
+ */
+import { type ContainerID, Cursor, type LoroDoc } from "loro-crdt";
+import { loroSyncPluginKey } from "loro-prosemirror";
+import type { Node } from "prosemirror-model";
+import { type EditorState, Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet, type EditorView } from "prosemirror-view";
+import { cursorToPosition, selectionToCursors } from "./sync";
+
+/** A selection as encoded Loro cursors. Null where there is no text to bind to. */
+export interface EncodedSelection {
+  anchor: string | null;
+  head: string | null;
+}
+
+/** Someone else in the document. */
+export interface RemoteCursor {
+  /** Stable per person (the room peer id). */
+  id: string;
+  name: string;
+  /** A CSS color for the caret and the selection. */
+  color: string;
+  selection?: EncodedSelection | null;
+}
+
+export interface ProseMirrorCursorsPluginProps {
+  doc: LoroDoc;
+  containerId: ContainerID;
+  /** Called when this person's selection moves, with its encoded cursors. */
+  onSelection?: (selection: EncodedSelection) => void;
+}
+
+export const proseMirrorCursorsKey = new PluginKey<RemoteCursor[]>("pylonRemoteCursors");
+
+function toBase64(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+
+function fromBase64(text: string): Uint8Array {
+  const s = atob(text);
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+
+/** This editor's selection as encoded Loro cursors. */
+export function encodeSelection(state: EditorState, doc: LoroDoc, containerId: ContainerID): EncodedSelection {
+  const { anchor, head } = selectionToCursors(state, doc, containerId);
+  return {
+    anchor: anchor ? toBase64(anchor.encode()) : null,
+    head: head ? toBase64(head.encode()) : null,
+  };
+}
+
+/** Show these people's carets and selections. Replaces the previous list. */
+export function setRemoteCursors(view: EditorView, cursors: RemoteCursor[]): void {
+  view.dispatch(view.state.tr.setMeta(proseMirrorCursorsKey, cursors).setMeta("addToHistory", false));
+}
+
+function caret(cursor: RemoteCursor): HTMLElement {
+  const el = document.createElement("span");
+  el.className = "pylon-remote-caret";
+  el.style.borderLeft = `2px solid ${cursor.color}`;
+  el.style.marginLeft = "-1px";
+  el.style.marginRight = "-1px";
+  el.style.position = "relative";
+  el.setAttribute("aria-hidden", "true");
+  const label = document.createElement("span");
+  label.className = "pylon-remote-caret-label";
+  label.textContent = cursor.name;
+  label.style.position = "absolute";
+  label.style.left = "-2px";
+  label.style.bottom = "100%";
+  label.style.whiteSpace = "nowrap";
+  label.style.background = cursor.color;
+  label.style.color = "white";
+  label.style.fontSize = "11px";
+  label.style.lineHeight = "1.4";
+  label.style.padding = "0 4px";
+  label.style.borderRadius = "3px 3px 3px 0";
+  label.style.pointerEvents = "none";
+  el.appendChild(label);
+  return el;
+}
+
+function resolve(encoded: string | null | undefined, doc: LoroDoc, containerId: ContainerID, state: EditorState): number | null {
+  if (!encoded) return null;
+  const sync = loroSyncPluginKey.getState(state) as { mapping?: Map<ContainerID, Node | Node[]> } | undefined;
+  if (!sync?.mapping) return null;
+  try {
+    // A deleted character's cursor moves to Loro's nearest position, so the
+    // caret stays visible until its owner sends a new selection.
+    const pos = cursorToPosition(Cursor.decode(fromBase64(encoded)), doc, containerId, sync.mapping, {
+      acceptMoved: true,
+    });
+    return pos != null && pos >= 0 && pos <= state.doc.content.size ? pos : null;
+  } catch {
+    return null;
+  }
+}
+
+function decorations(state: EditorState, cursors: RemoteCursor[], doc: LoroDoc, containerId: ContainerID): DecorationSet {
+  const decos: Decoration[] = [];
+  for (const cursor of cursors) {
+    const head = resolve(cursor.selection?.head, doc, containerId, state);
+    if (head == null) continue;
+    const anchor = resolve(cursor.selection?.anchor, doc, containerId, state) ?? head;
+    if (anchor !== head) {
+      decos.push(
+        Decoration.inline(Math.min(anchor, head), Math.max(anchor, head), {
+          style: `background-color: color-mix(in srgb, ${cursor.color} 22%, transparent)`,
+          class: "pylon-remote-selection",
+        }),
+      );
+    }
+    decos.push(Decoration.widget(head, () => caret(cursor), { key: `caret-${cursor.id}-${cursor.color}-${cursor.name}`, side: -1 }));
+  }
+  return DecorationSet.create(state.doc, decos);
+}
+
+export function ProseMirrorCursorsPlugin({ doc, containerId, onSelection }: ProseMirrorCursorsPluginProps): Plugin {
+  // Decorations are recomputed for each new document or peer list.
+  let cache: { doc: Node; cursors: RemoteCursor[]; set: DecorationSet } | null = null;
+  return new Plugin<RemoteCursor[]>({
+    key: proseMirrorCursorsKey,
+    state: {
+      init: () => [],
+      apply: (tr, value) => (tr.getMeta(proseMirrorCursorsKey) as RemoteCursor[] | undefined) ?? value,
+    },
+    props: {
+      decorations(state) {
+        const cursors = proseMirrorCursorsKey.getState(state) ?? [];
+        if (cursors.length === 0) return DecorationSet.empty;
+        if (cache && cache.doc === state.doc && cache.cursors === cursors) return cache.set;
+        const set = decorations(state, cursors, doc, containerId);
+        cache = { doc: state.doc, cursors, set };
+        return set;
+      },
+    },
+    view: () => {
+      let last = "";
+      return {
+        update(view) {
+          if (!onSelection || !view.hasFocus()) return;
+          const encoded = encodeSelection(view.state, doc, containerId);
+          const key = `${encoded.anchor}|${encoded.head}`;
+          if (key === last) return;
+          last = key;
+          onSelection(encoded);
+        },
+      };
+    },
+  });
+}

package/src/prosemirror/index.ts

@@ -15,7 +15,7 @@
  *   const doc = useLoroDoc("Doc", id);
  *   configureProseMirrorMarks(doc, schema);
  *   const containerId = await waitForProseMirrorContainer(doc, "body");
- *   const plugin = LoroSyncPlugin({ doc, containerId });
+ *   const plugin = ProseMirrorSyncPlugin({ doc, containerId }); // ./sync
  *
  * In a server function, read and change the document without an editor
  * with `readProseMirror` and `writeProseMirror`.
@@ -27,7 +27,7 @@
 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";
+import { EditorState, Transaction } from "prosemirror-state";
 
 /** The root map every Pylon row doc keeps its fields in (crates/crdt). */
 const ROOT_MAP = "row";
@@ -113,3 +113,38 @@ export function writeProseMirror(doc: LoroDoc, field: string, schema: Schema, no
   configureProseMirrorMarks(doc, schema);
   updateLoroToPmState(doc as never, new Map(), EditorState.create({ schema, doc: node }), containerId);
 }
+
+/** What {@link editProseMirror} needs of a live doc (`LiveDoc` from `@pylonsync/loro/server`). */
+export interface LiveProseMirrorDoc {
+  readonly doc: LoroDoc;
+  refresh(): Promise<void>;
+  commit(): Promise<boolean>;
+}
+
+/**
+ * Change `field`'s document from a server function and send the change to
+ * everyone editing. `change` gets an editor state on the document as it is
+ * now (an empty document when there is none) and returns a transaction or
+ * a new document; returning nothing changes nothing. The write is a diff,
+ * so edits people make at the same time still merge. Returns the document
+ * written, or null when nothing changed.
+ *
+ *   await editProseMirror(live, "body", schema, (state) =>
+ *     state.tr.insertText("Summary: ", 1));
+ */
+export async function editProseMirror(
+  live: LiveProseMirrorDoc,
+  field: string,
+  schema: Schema,
+  change: (state: EditorState) => Transaction | Node | null | undefined | void,
+): Promise<Node | null> {
+  await live.refresh();
+  const current = readProseMirror(live.doc, field, schema) ?? schema.topNodeType.createAndFill();
+  if (!current) throw new Error(`The schema's ${schema.topNodeType.name} has no empty form to start from.`);
+  const result = change(EditorState.create({ schema, doc: current }));
+  const next = result instanceof Transaction ? result.doc : result;
+  if (!next || next.eq(current)) return null;
+  writeProseMirror(live.doc, field, schema, next);
+  await live.commit();
+  return next;
+}

package/src/prosemirror/react.ts

@@ -3,7 +3,7 @@
  *
  *   const { doc, containerId } = useProseMirrorDoc("Doc", id, "body", schema);
  *   if (!containerId) return <Loading />;
- *   const plugins = [LoroSyncPlugin({ doc, containerId }), LoroUndoPlugin({ doc })];
+ *   const plugins = [ProseMirrorSyncPlugin({ doc, containerId }), ProseMirrorUndoPlugin({ 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