@pylonsync/loro 0.22.40 → 0.22.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/loro",
-  "version": "0.22.40",
+  "version": "0.22.43",
   "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"
@@ -14,14 +14,16 @@
     "./registry": "./src/registry.ts",
     "./prosemirror": "./src/prosemirror/index.ts",
     "./prosemirror/react": "./src/prosemirror/react.ts",
-    "./prosemirror/sync": "./src/prosemirror/sync.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.40",
-    "@pylonsync/sync": "0.22.40",
+    "@pylonsync/react": "0.22.43",
+    "@pylonsync/sync": "0.22.43",
     "loro-crdt": "^1.10.6"
   },
   "peerDependencies": {

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

@@ -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/sync.test.ts

@@ -14,7 +14,7 @@ import { EditorView } from "prosemirror-view";
 import { configureProseMirrorMarks, findProseMirrorContainer } from "./index";
 import { ProseMirrorSyncPlugin, ProseMirrorUndoPlugin } from "./sync";
 
-const schema = new Schema({ nodes: basic.spec.nodes, marks: basic.spec.marks });
+const defaultSchema = new Schema({ nodes: basic.spec.nodes, marks: basic.spec.marks });
 const tick = () => new Promise((r) => setTimeout(r, 0));
 
 const views: EditorView[] = [];
@@ -22,12 +22,14 @@ afterEach(() => {
   for (const v of views.splice(0)) v.destroy();
 });
 
-/** A server doc with the field's container, and two clients synced to it. */
-function setup() {
+/**
+ * A server doc with the field's container, and two editors synced to it:
+ * on two client docs, or with `shared` on one (two editors in one tab).
+ */
+function setup({ schema = defaultSchema, shared = false }: { schema?: Schema; shared?: boolean } = {}) {
   // The empty document the server makes on insert (crates/crdt prosemirror.rs).
   const server = new LoroDoc();
   const body = server.getMap("row").setContainer("body", new LoroMap());
-  body.set("nodeName", "doc");
   body.setContainer("attributes", new LoroMap());
   body.setContainer("children", new LoroList());
   server.commit();
@@ -47,7 +49,7 @@ function setup() {
     views.push(view);
     return view;
   };
-  const [a, b] = [make(docs[0]), make(docs[1])];
+  const [a, b] = [make(docs[0]), make(shared ? docs[0] : docs[1])];
   const sync = () => {
     for (const from of docs) {
       const bytes = from.export({ mode: "update", from: server.oplogVersion() });
@@ -56,7 +58,7 @@ function setup() {
     const all = server.export({ mode: "snapshot" });
     for (const to of docs) to.import(all);
   };
-  return { a, b, docs, sync };
+  return { a, b, docs, server, sync };
 }
 
 const text = (v: EditorView) => v.state.doc.textBetween(0, v.state.doc.content.size, "\n");
@@ -191,3 +193,131 @@ describe("ProseMirrorSyncPlugin", () => {
     expect(text(b)).toBe("A:base");
   });
 });
+
+// Regressions from the Codex review of 2026-10-17.
+describe("ProseMirrorSyncPlugin review fixes", () => {
+  test("the first edit in a new document can be undone", async () => {
+    const { a, b, sync } = setup();
+    await tick();
+    type(a, "first words");
+    sync();
+    expect(text(b)).toBe("first words");
+    await new Promise((r) => setTimeout(r, 600));
+    type(a, " more");
+    undo(a.state, a.dispatch);
+    undo(a.state, a.dispatch);
+    sync();
+    expect(text(a)).toBe("");
+    expect(text(b)).toBe("");
+  });
+
+  test("two editors on one doc see each other's edits", async () => {
+    const { a, b, server, sync } = setup({ shared: true });
+    await tick();
+    type(a, "base");
+    expect(text(b)).toBe("base");
+    caretAt(b, 5);
+    type(b, "B");
+    expect(text(a)).toBe("baseB");
+    sync();
+    expect(JSON.stringify(server.getMap("row").get("body"))).toBeDefined();
+    expect(text(a)).toBe("baseB");
+  });
+
+  test("the top node's attributes load and are not overwritten", async () => {
+    const langSchema = new Schema({
+      nodes: defaultSchema.spec.nodes.update("doc", { ...defaultSchema.spec.nodes.get("doc")!, attrs: { lang: { default: "en" } } }),
+      marks: defaultSchema.spec.marks,
+    });
+    const { a, b, docs, sync } = setup({ schema: langSchema });
+    await tick();
+    a.dispatch(a.state.tr.setDocAttribute("lang", "fr"));
+    type(a, "bonjour");
+    sync();
+    expect(b.state.doc.attrs.lang).toBe("fr");
+    type(b, "!");
+    sync();
+    expect(a.state.doc.attrs.lang).toBe("fr");
+    const attrs = (docs[0].getMap("row").get("body") as LoroMap).get("attributes") as LoroMap;
+    expect(attrs.get("lang")).toBe("fr");
+  });
+
+  test("clearing the document does not add a paragraph per editor", async () => {
+    const { a, b, docs, server, sync } = setup();
+    await tick();
+    type(a, "text");
+    sync();
+    const children = (server.getMap("row").get("body") as LoroMap).get("children") as LoroList;
+    children.delete(0, children.length);
+    server.commit();
+    for (const d of docs) d.import(server.export({ mode: "snapshot" }));
+    sync();
+    expect(children.length).toBe(0);
+    expect(text(a)).toBe("");
+    expect(text(b)).toBe("");
+  });
+
+  test("a schema whose top node is not doc can edit a new document", async () => {
+    const custom = new Schema({
+      topNode: "document",
+      nodes: defaultSchema.spec.nodes.remove("doc").addToStart("document", { content: "block+" }),
+      marks: defaultSchema.spec.marks,
+    });
+    const { a, b, sync } = setup({ schema: custom });
+    await tick();
+    type(a, "hello");
+    sync();
+    expect(text(b)).toBe("hello");
+    expect(b.state.doc.type.name).toBe("document");
+  });
+
+  test("a caret after an emoji stays after it", async () => {
+    const { a, b, sync } = setup();
+    await tick();
+    type(a, "x😀");
+    sync();
+    caretAt(b, 4); // after the emoji (1 + 1 + 2)
+    caretAt(a, 1);
+    type(a, "AB");
+    sync();
+    expect(text(b)).toBe("ABx😀");
+    expect(b.state.selection.head).toBe(6);
+  });
+
+  test("a caret after an inline node with content stays put", async () => {
+    const nodes = defaultSchema.spec.nodes.addToEnd("chip", {
+      group: "inline",
+      inline: true,
+      content: "text*",
+      toDOM: () => ["span", { class: "chip" }, 0],
+    });
+    const chipSchema = new Schema({ nodes, marks: defaultSchema.spec.marks });
+    const { a, b, sync } = setup({ schema: chipSchema });
+    await tick();
+    type(a, "ab");
+    a.dispatch(a.state.tr.insert(3, chipSchema.node("chip", null, [chipSchema.text("XX")])));
+    caretAt(a, 7); // after the chip
+    type(a, "cd");
+    sync();
+    caretAt(b, 9); // after "cd"
+    caretAt(a, 1);
+    type(a, "Z");
+    sync();
+    expect(b.state.selection.head).toBe(10);
+  });
+
+  test("a selected node stays selected through a remote edit", async () => {
+    const { a, b, sync } = setup();
+    await tick();
+    type(a, "pic ");
+    a.dispatch(a.state.tr.insert(5, defaultSchema.node("image", { src: "x.png" })));
+    sync();
+    const { NodeSelection } = await import("prosemirror-state");
+    b.dispatch(b.state.tr.setSelection(NodeSelection.create(b.state.doc, 5)));
+    caretAt(a, 1);
+    type(a, "A ");
+    sync();
+    expect(b.state.selection).toBeInstanceOf(NodeSelection);
+    expect((b.state.selection as InstanceType<typeof NodeSelection>).node.type.name).toBe("image");
+  });
+});

package/src/prosemirror/sync.ts

@@ -39,7 +39,7 @@ import {
   updateLoroToPmState,
 } from "loro-prosemirror";
 import type { Node } from "prosemirror-model";
-import { Plugin, TextSelection, type EditorState } from "prosemirror-state";
+import { Plugin, TextSelection, type EditorState, type Transaction } from "prosemirror-state";
 import type { EditorView } from "prosemirror-view";
 
 type Mapping = Map<ContainerID, Node | Node[]>;
@@ -65,6 +65,19 @@ export interface ProseMirrorSyncPluginProps {
 }
 
 export function ProseMirrorSyncPlugin({ doc, containerId }: ProseMirrorSyncPluginProps): Plugin {
+  // True while this editor writes to the doc. Loro reports a commit to
+  // subscribers synchronously, in the middle of this editor's own dispatch;
+  // those events are this editor's own edits. Every other change (another
+  // editor on the same doc, app code, an undo, the server) is applied.
+  let writing = false;
+  const write = (fn: () => void) => {
+    writing = true;
+    try {
+      fn();
+    } finally {
+      writing = false;
+    }
+  };
   return new Plugin({
     key: loroSyncPluginKey,
     props: {
@@ -81,22 +94,27 @@ export function ProseMirrorSyncPlugin({ doc, containerId }: ProseMirrorSyncPlugi
         switch (meta?.type) {
           case "doc-changed":
             if (!undoState?.isUndoing?.current) {
-              updateLoroToPmState(doc as never, state.mapping as never, newEditorState, containerId);
+              write(() => updateLoroToPmState(doc as never, state.mapping as never, newEditorState, containerId));
             }
             break;
-          case "update-state":
+          case "update-state": {
             state = { ...state, ...meta.state };
-            state.doc.commit({ origin: "sys:init", timestamp: Date.now() });
+            const committing = state.doc;
+            write(() => committing.commit({ origin: "sys:init", timestamp: Date.now() }));
             break;
+          }
         }
         return state;
       },
     },
-    // After a remote change too, as LoroSyncPlugin does: the write is a no-op
-    // when the editor and the doc agree, and it points the mapping at the
-    // editor's own nodes again.
+    // Only this editor's own changes are written to the doc. A change that
+    // came from the doc is there already, and the empty document an editor
+    // shows for an emptied field must not be written back: every editor
+    // would add its own.
     appendTransaction: (transactions, _old, newState) =>
-      transactions.some((tr) => tr.docChanged)
+      transactions.some(
+        (tr) => tr.docChanged && (tr.getMeta(loroSyncPluginKey) as { type?: string } | undefined)?.type !== "non-local-updates",
+      )
         ? newState.tr.setMeta(loroSyncPluginKey, { type: "doc-changed" })
         : null,
     view: (view) => {
@@ -108,12 +126,20 @@ export function ProseMirrorSyncPlugin({ doc, containerId }: ProseMirrorSyncPlugi
       const timer = setTimeout(() => {
         if (view.isDestroyed) return;
         unsubscribe = doc.getContainerById(containerId)!.subscribe((event) => {
-          // Local edits came from this editor, so it already shows them.
-          // An undo is local to Loro but new to the editor.
-          if (event.by === "local" && event.origin !== "undo") return;
+          if (writing) return;
           applyRemote(view, doc, containerId, event, cursors);
           remember();
         });
+        // A new document has no top node name yet; the server leaves it to
+        // the schema. Write it now, as setup (`sys:init`, which undo skips),
+        // so the person's first edit is an edit they can undo.
+        const root = doc.getContainerById(containerId) as LoroMap;
+        if (root.get("nodeName") == null) {
+          write(() => {
+            root.set("nodeName", view.state.schema.topNodeType.name);
+            doc.commit({ origin: "sys:init" });
+          });
+        }
         loadInitial(view, doc, containerId);
         remember();
       }, 0);
@@ -156,12 +182,14 @@ function field(doc: LoroDoc, containerId: ContainerID): LoroMap {
 
 /**
  * The browser's selection in the editor, when it differs from the editor
- * state's. A click or an arrow key moves the DOM selection first, and the
- * editor reads it a little later; a remote change in between would put the
- * caret back where it was.
+ * state's and the window has focus. A click or an arrow key moves the DOM
+ * selection first, and the editor reads it a little later; a remote change
+ * in between would put the caret back where it was.
  */
 function domSelectionIfMoved(view: EditorView): { anchor: number; head: number } | null {
-  if (!view.hasFocus()) return null;
+  // A window without focus keeps a stale DOM selection: the editor does not
+  // write its selection to the DOM while it is in the background.
+  if (!view.hasFocus() || !view.dom.ownerDocument.hasFocus()) return null;
   const sel = (view.root as Document).getSelection?.();
   if (!sel?.anchorNode || !sel.focusNode || !view.dom.contains(sel.anchorNode)) return null;
   try {
@@ -194,11 +222,21 @@ function loadInitial(view: EditorView, doc: LoroDoc, containerId: ContainerID):
   if (node && node.childCount > 0) {
     tr = tr.replaceWith(0, view.state.doc.content.size, node.content);
   }
+  if (node) tr = withTopAttrs(tr, node);
   tr.setMeta(loroSyncPluginKey, { type: "update-state", state: { mapping, snapshot: null } });
   tr.setMeta("addToHistory", false);
   view.dispatch(tr);
 }
 
+/** Set the top node's attributes to `node`'s where they differ. */
+function withTopAttrs(tr: Transaction, node: Node): Transaction {
+  const current = tr.doc.attrs;
+  for (const [name, value] of Object.entries(node.attrs)) {
+    if (current[name] !== value) tr = tr.setDocAttribute(name, value);
+  }
+  return tr;
+}
+
 /** Drop cached nodes for every container an event touched, and their ancestors. */
 function forgetChanged(doc: LoroDoc, event: { events: Array<{ target: ContainerID }> }, mapping: Mapping): void {
   for (const e of event.events) {
@@ -240,6 +278,17 @@ function applyRemote(
     }
     tr = tr.replace(start, endA, next.slice(start, endB));
   }
+  tr = withTopAttrs(tr, next);
+  // Nothing this editor shows changed (an echo, a change elsewhere in the row).
+  if (!tr.docChanged) return;
+  // A node selection, a cell selection: ProseMirror maps it through the
+  // replace and keeps its kind; a caret rebuilt from cursors would not.
+  if (!(view.state.selection instanceof TextSelection)) {
+    tr.setMeta(loroSyncPluginKey, { type: "non-local-updates" });
+    tr.setMeta("addToHistory", false);
+    view.dispatch(tr);
+    return;
+  }
   if (moved) {
     // The person moved the caret after the cursors were taken: map where it
     // is now through the replace.
@@ -316,26 +365,54 @@ export function positionToCursor(root: Node, pos: number, doc: LoroDoc, containe
   if (!$pos.parent.inlineContent) {
     return children.getCursor(childIndexFor($pos.parent, $pos.index()) + ($pos.index() >= $pos.parent.childCount ? 1 : 0)) ?? null;
   }
-  // Walk the textblock's children: text runs count their characters, every
-  // other inline node counts one.
-  let offset = $pos.parentOffset;
-  for (let i = 0; i < children.length; i++) {
-    const child = children.get(i);
-    if (child instanceof LoroText) {
-      if (offset <= child.length) {
-        // Bind to the character on the left (side 1: just after it). At the
-        // start of a run there is none, so bind to the first character.
-        return (offset > 0 ? child.getCursor(offset - 1, 1) : child.getCursor(0, 0)) ?? null;
+  // Walk the textblock's children alongside the editor's: a run of text
+  // nodes is one LoroText, every other inline node one child of its size.
+  const parent = $pos.parent;
+  const offset = $pos.parentOffset;
+  let group = -1;
+  let pmOffset = 0;
+  let runStart = -1;
+  for (let i = 0; i < parent.childCount; i++) {
+    const child = parent.child(i);
+    if (child.isText) {
+      if (runStart < 0) {
+        group += 1;
+        runStart = pmOffset;
       }
-      offset -= child.length;
     } else {
-      if (offset === 0) return children.getCursor(i) ?? null;
-      offset -= 1;
+      // The caret at the end of a text run binds to that run, so typing
+      // there continues it.
+      if (runStart >= 0 && offset <= pmOffset) return textCursor(children.get(group), offset - runStart);
+      runStart = -1;
+      group += 1;
+      if (offset === pmOffset) return children.getCursor(group) ?? null;
     }
+    pmOffset += child.nodeSize;
   }
+  if (runStart >= 0 && offset <= pmOffset) return textCursor(children.get(group), offset - runStart);
   return children.getCursor(children.length) ?? null;
 }
 
+/** True for the second half of a UTF-16 surrogate pair (an emoji's, say). */
+function isLowSurrogate(text: string): boolean {
+  const code = text.charCodeAt(0);
+  return code >= 0xdc00 && code <= 0xdfff;
+}
+
+/**
+ * A cursor `offset` UTF-16 units into a text run, bound to the character on
+ * its left (side 1: just after it), the whole character when it is a
+ * surrogate pair. At the start of the run there is none, so it binds to the
+ * first character.
+ */
+function textCursor(text: unknown, offset: number): Cursor | null {
+  if (!(text instanceof LoroText)) return null;
+  if (offset <= 0) return text.getCursor(0, 0) ?? null;
+  let start = Math.min(offset, text.length) - 1;
+  if (start > 0 && isLowSurrogate(text.slice(start, start + 1))) start -= 1;
+  return text.getCursor(start, 1) ?? null;
+}
+
 /** Size in the editor of a container's node, from the binding's mapping. */
 function mappedSize(mapping: Mapping, id: ContainerID): number | null {
   const mapped = mapping.get(id);
@@ -347,7 +424,13 @@ function mappedSize(mapping: Mapping, id: ContainerID): number | null {
  * The document position a cursor points at now. Uses the mapping, which
  * createNodeFromLoroObj has just filled for the whole tree.
  */
-export function cursorToPosition(cursor: Cursor, doc: LoroDoc, containerId: ContainerID, mapping: Mapping): number | null {
+export function cursorToPosition(
+  cursor: Cursor,
+  doc: LoroDoc,
+  containerId: ContainerID,
+  mapping: Mapping,
+  options: { acceptMoved?: boolean } = {},
+): number | null {
   const rootId = field(doc, containerId).id;
   const target = cursor.containerId();
   let index: number;
@@ -357,7 +440,7 @@ export function cursorToPosition(cursor: Cursor, doc: LoroDoc, containerId: Cont
     const list = doc.getContainerById(target) as LoroList | undefined;
     const pos = doc.getCursorPos(cursor);
     const owner = list?.parent() as LoroMap | undefined;
-    if (!list || !pos || pos.update || !owner) return null;
+    if (!list || !pos || (pos.update && !options.acceptMoved) || !owner) return null;
     // Inside a node with no text, or before an inline node: count the
     // children before it.
     index = 0;
@@ -375,11 +458,16 @@ export function cursorToPosition(cursor: Cursor, doc: LoroDoc, containerId: Cont
     const text = doc.getContainerById(target) as LoroText | undefined;
     const pos = doc.getCursorPos(cursor);
     // `update` means the character was deleted (a split moves text into a
-    // new paragraph as a delete and an insert). ProseMirror's own mapping
-    // through the replace places the caret better then.
-    if (!text || !pos || pos.update) return null;
-    // The cursor names a character; side 1 means just after it.
-    index = pos.offset + (pos.side === 1 ? 1 : 0);
+    // new paragraph as a delete and an insert). For this editor's own caret,
+    // ProseMirror's mapping through the replace places it better; another
+    // person's caret has no mapping, so it takes Loro's nearest position
+    // (`acceptMoved`).
+    if (!text || !pos || (pos.update && !options.acceptMoved)) return null;
+    // The cursor names a character; side 1 means just after it, which is
+    // two UTF-16 units for a surrogate pair.
+    const width =
+      pos.side === 1 ? (pos.offset + 1 < text.length && isLowSurrogate(text.slice(pos.offset + 1, pos.offset + 2)) ? 2 : 1) : 0;
+    index = pos.offset + width;
     childId = text.id;
     node = (text.parent() as LoroList | undefined)?.parent() as LoroMap | undefined;
   }

package/src/server.test.ts

@@ -0,0 +1,138 @@
+// LiveDoc and editProseMirror against a fake ctx.crdt whose "server" is a
+// LoroDoc, the way the host's store merges and serves a row's document.
+import { describe, expect, test } from "bun:test";
+import { LoroDoc, LoroList, LoroMap, VersionVector } from "loro-crdt";
+import { Schema } from "prosemirror-model";
+import { schema as basic } from "prosemirror-schema-basic";
+import { editProseMirror, readProseMirror, writeProseMirror, configureProseMirrorMarks } from "./prosemirror/index";
+import { openLiveDoc, type CrdtOps, type LiveDocContext } from "./server";
+
+function fakeHost(server: LoroDoc | null) {
+  const applied: Uint8Array[] = [];
+  const calls: string[] = [];
+  const ops = (label: string): CrdtOps => ({
+    async snapshot() {
+      calls.push(`${label}snapshot`);
+      return server ? server.export({ mode: "snapshot" }) : null;
+    },
+    async since(_e, _i, version) {
+      calls.push(`${label}since`);
+      return server ? server.export({ mode: "update", from: VersionVector.decode(version) }) : null;
+    },
+    async apply(_e, _i, update) {
+      calls.push(`${label}apply`);
+      applied.push(update);
+      server!.import(update);
+    },
+  });
+  const ctx: LiveDocContext = { crdt: { ...ops(""), unsafe: ops("unsafe:") } };
+  return { ctx, applied, calls };
+}
+
+function rowDoc(): LoroDoc {
+  const d = new LoroDoc();
+  d.getMap("row").set("title", "start");
+  d.commit();
+  return d;
+}
+
+describe("LiveDoc", () => {
+  test("an edit reaches the server", async () => {
+    const server = rowDoc();
+    const { ctx } = fakeHost(server);
+    const live = await openLiveDoc(ctx, "Doc", "d1");
+    await live.edit((doc) => doc.getMap("row").set("status", "done"));
+    expect(server.getMap("row").get("status")).toBe("done");
+  });
+
+  test("edit pulls in what others wrote after the doc was opened", async () => {
+    const server = rowDoc();
+    const text = server.getMap("row").setContainer("body", new (await import("loro-crdt")).LoroText());
+    server.commit();
+    const { ctx } = fakeHost(server);
+    const live = await openLiveDoc(ctx, "Doc", "d1");
+    // Someone types at the server's copy meanwhile.
+    text.insert(0, "person ");
+    server.commit();
+    await live.edit((doc) => {
+      const t = doc.getMap("row").get("body") as { insert(i: number, s: string): void; length: number };
+      t.insert(t.length, "function");
+    });
+    expect(text.toString()).toBe("person function");
+  });
+
+  test("commit sends only this function's ops, once", async () => {
+    const server = rowDoc();
+    const big = new LoroDoc();
+    big.import(server.export({ mode: "snapshot" }));
+    big.getMap("row").set("blob", "x".repeat(5000));
+    big.commit();
+    server.import(big.export({ mode: "update" }));
+    const { ctx, applied } = fakeHost(server);
+    const live = await openLiveDoc(ctx, "Doc", "d1");
+    live.doc.getMap("row").set("n", 1);
+    expect(await live.commit()).toBe(true);
+    expect(await live.commit()).toBe(false);
+    expect(applied.length).toBe(1);
+    expect(applied[0].length).toBeLessThan(200);
+  });
+
+  test("a row without a document is NOT_FOUND", async () => {
+    const { ctx } = fakeHost(null);
+    await expect(openLiveDoc(ctx, "Doc", "nope")).rejects.toMatchObject({ code: "NOT_FOUND" });
+  });
+
+  test("unsafe goes through ctx.crdt.unsafe", async () => {
+    const server = rowDoc();
+    const { ctx, calls } = fakeHost(server);
+    const live = await openLiveDoc(ctx, "Doc", "d1", { unsafe: true });
+    await live.edit((doc) => doc.getMap("row").set("k", 1));
+    expect(calls).toEqual(["unsafe:snapshot", "unsafe:since", "unsafe:apply"]);
+  });
+});
+
+describe("editProseMirror", () => {
+  const schema = new Schema({ nodes: basic.spec.nodes, marks: basic.spec.marks });
+  const para = (s: string) => schema.node("paragraph", null, s ? [schema.text(s)] : []);
+
+  function serverWithBody(): LoroDoc {
+    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();
+    return server;
+  }
+
+  test("a function's edit and a person's edit at the same time both land", async () => {
+    const server = serverWithBody();
+    configureProseMirrorMarks(server, schema);
+    writeProseMirror(server, "body", schema, schema.node("doc", null, [para("Hello")]));
+    const { ctx } = fakeHost(server);
+    const live = await openLiveDoc(ctx, "Doc", "d1");
+    // A person adds a paragraph after the function opened the doc.
+    const now = readProseMirror(server, "body", schema)!;
+    writeProseMirror(server, "body", schema, now.copy(now.content.append(schema.node("doc", null, [para("from a person")]).content)));
+    const written = await editProseMirror(live, "body", schema, (state) => state.tr.insertText("Summary: ", 1));
+    expect(written).not.toBeNull();
+    const result: string[] = [];
+    readProseMirror(server, "body", schema)!.forEach((n) => result.push(n.textContent));
+    expect(result).toEqual(["Summary: Hello", "from a person"]);
+  });
+
+  test("an empty document starts from the schema's empty document", async () => {
+    const server = serverWithBody();
+    const { ctx } = fakeHost(server);
+    const live = await openLiveDoc(ctx, "Doc", "d1");
+    await editProseMirror(live, "body", schema, (state) => state.tr.insertText("first", 1));
+    expect(readProseMirror(server, "body", schema)!.textContent).toBe("first");
+  });
+
+  test("returning nothing changes nothing", async () => {
+    const server = serverWithBody();
+    const { ctx, applied } = fakeHost(server);
+    const live = await openLiveDoc(ctx, "Doc", "d1");
+    expect(await editProseMirror(live, "body", schema, () => undefined)).toBeNull();
+    expect(applied.length).toBe(0);
+  });
+});

package/src/server.ts

@@ -0,0 +1,99 @@
+/**
+ * A row's live CRDT document in a server function (an action), through
+ * `ctx.crdt`:
+ *
+ *   import { openLiveDoc } from "@pylonsync/loro/server";
+ *
+ *   const live = await openLiveDoc(ctx, "Doc", id);
+ *   await live.edit((doc) => doc.getMap("row").set("status", "done"));
+ *
+ * `edit` pulls in what others wrote since the doc was opened, runs the
+ * change, and sends only this function's ops. Everyone editing sees them as
+ * they land. For a ProseMirror field, `editProseMirror` in
+ * `@pylonsync/loro/prosemirror` does the same with a ProseMirror document.
+ *
+ * Each `openLiveDoc` is a new Loro peer, so two functions editing one row
+ * at once merge like two people do.
+ */
+import { LoroDoc } from "loro-crdt";
+import { exportOwnOps, ownCounter } from "./outbox";
+
+/** The byte operations `ctx.crdt` provides (`@pylonsync/functions` `Crdt`). */
+export interface CrdtOps {
+  snapshot(entity: string, id: string): Promise<Uint8Array | null>;
+  since(entity: string, id: string, version: Uint8Array): Promise<Uint8Array | null>;
+  apply(entity: string, id: string, update: Uint8Array): Promise<void>;
+}
+
+export interface LiveDocContext {
+  crdt: CrdtOps & { unsafe: CrdtOps };
+}
+
+export interface OpenLiveDocOptions {
+  /** Server trust even under strict function policies (`ctx.crdt.unsafe`). */
+  unsafe?: boolean;
+}
+
+export class LiveDoc {
+  readonly doc: LoroDoc;
+  readonly entity: string;
+  readonly id: string;
+  private readonly ops: CrdtOps;
+  /** This peer's op counter the server has merged (exclusive end). */
+  private confirmed = 0;
+
+  private constructor(ops: CrdtOps, entity: string, id: string, doc: LoroDoc) {
+    this.ops = ops;
+    this.entity = entity;
+    this.id = id;
+    this.doc = doc;
+  }
+
+  /** Open the row's document. Throws NOT_FOUND when there is none to open. */
+  static async open(ctx: LiveDocContext, entity: string, id: string, options: OpenLiveDocOptions = {}): Promise<LiveDoc> {
+    const ops = options.unsafe ? ctx.crdt.unsafe : ctx.crdt;
+    const snapshot = await ops.snapshot(entity, id);
+    if (!snapshot) {
+      throw Object.assign(new Error(`${entity} ${id} has no document to open`), { code: "NOT_FOUND" });
+    }
+    const doc = new LoroDoc();
+    doc.import(snapshot);
+    return new LiveDoc(ops, entity, id, doc);
+  }
+
+  /** Pull in what others wrote since this doc last heard from the server. */
+  async refresh(): Promise<void> {
+    const update = await this.ops.since(this.entity, this.id, this.doc.oplogVersion().encode());
+    if (update && update.length > 0) this.doc.import(update);
+  }
+
+  /**
+   * Send this function's ops the server has not merged yet. Commits pending
+   * changes first. Returns false when there was nothing to send.
+   */
+  async commit(): Promise<boolean> {
+    this.doc.commit();
+    const target = ownCounter(this.doc);
+    if (target <= this.confirmed) return false;
+    await this.ops.apply(this.entity, this.id, exportOwnOps(this.doc, this.confirmed));
+    this.confirmed = target;
+    return true;
+  }
+
+  /** Refresh, run `change` on the doc, and send the result. */
+  async edit(change: (doc: LoroDoc) => void | Promise<void>): Promise<void> {
+    await this.refresh();
+    await change(this.doc);
+    await this.commit();
+  }
+}
+
+/** See {@link LiveDoc.open}. */
+export function openLiveDoc(
+  ctx: LiveDocContext,
+  entity: string,
+  id: string,
+  options: OpenLiveDocOptions = {},
+): Promise<LiveDoc> {
+  return LiveDoc.open(ctx, entity, id, options);
+}