@pylonsync/loro 0.3.311 → 0.3.312

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/loro",
-  "version": "0.3.311",
+  "version": "0.3.312",
   "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"
@@ -17,8 +17,8 @@
   "check": "tsc -p tsconfig.json --noEmit"
 },
 "dependencies": {
-  "@pylonsync/react": "0.3.311",
-  "@pylonsync/sync": "0.3.311",
+  "@pylonsync/react": "0.3.312",
+  "@pylonsync/sync": "0.3.312",
   "loro-crdt": "^1.10.6"
 },
 "peerDependencies": {

package/src/contract.test.ts

@@ -0,0 +1,82 @@
+// The client ↔ server doc-shape contract. The server (crates/crdt) puts
+// every entity field inside ONE root LoroMap named "row" — a
+// `crdt: "text"` field is a LoroText CHILD of that map, seeded at insert
+// and projected back to SQL after every merge. The client accessors must
+// resolve through that map: the old top-level `doc.getText(field)` put
+// edits in a container the server never reads, so seeded content rendered
+// empty in the editor and typed content never projected to the row.
+import { describe, expect, test } from "bun:test";
+import { LoroDoc, LoroText } from "loro-crdt";
+import { getLoroText, getLoroMap } from "./index";
+
+/** Build a doc the way the server's apply_patch does: root "row" map
+ *  with a seeded Text child for the field. */
+function serverSeededDoc(field: string, initial: string): LoroDoc {
+  const doc = new LoroDoc();
+  const row = doc.getMap("row");
+  const text = row.setContainer(field, new LoroText());
+  text.insert(0, initial);
+  doc.commit();
+  return doc;
+}
+
+describe("row-map contract", () => {
+  test("getLoroText resolves the server-seeded container (initial value visible)", () => {
+    const doc = serverSeededDoc("content", "# Welcome");
+    const text = getLoroText(doc, "content");
+    expect(text.toString()).toBe("# Welcome");
+  });
+
+  test("edits land inside the row map where the server projects from", () => {
+    const doc = serverSeededDoc("content", "abc");
+    const text = getLoroText(doc, "content");
+    text.insert(3, "def");
+    doc.commit();
+    // The server reads doc.getMap("row").get(field) — the edit must be
+    // visible THERE, not in a top-level container.
+    const json = doc.toJSON() as { row?: { content?: string } };
+    expect(json.row?.content).toBe("abcdef");
+    // And nothing leaked into the legacy top-level namespace.
+    expect(doc.getText("content").toString()).toBe("");
+  });
+
+  test("creates the container under row/ for rows that predate CRDT seeding", () => {
+    const doc = new LoroDoc();
+    const text = getLoroText(doc, "content");
+    text.insert(0, "x");
+    doc.commit();
+    const json = doc.toJSON() as { row?: { content?: string } };
+    expect(json.row?.content).toBe("x");
+  });
+
+  test("edits after a catch-up import land in the winning container", () => {
+    // The race: a component creates the field container eagerly BEFORE the
+    // server's catch-up snapshot arrives; the merge then makes one of the
+    // two containers win the row-map key LWW. Edits must follow the WINNER
+    // (what row.content projects to), not a handle captured pre-merge —
+    // pre-fix, every keystroke went into the orphaned loser and the server
+    // never saw it.
+    const server = serverSeededDoc("content", "seeded");
+    const snapshot = server.export({ mode: "snapshot" });
+
+    const client = new LoroDoc();
+    getLoroText(client, "content").insert(0, "early");
+    client.commit();
+    client.import(snapshot);
+
+    const live = getLoroText(client, "content");
+    live.insert(live.length, "!");
+    client.commit();
+    const json = client.toJSON() as { row?: { content?: string } };
+    expect(json.row?.content?.endsWith("!")).toBe(true);
+  });
+
+  test("getLoroMap resolves a field-level map child of row/", () => {
+    const doc = new LoroDoc();
+    const m = getLoroMap(doc, "meta");
+    m.set("k", "v");
+    doc.commit();
+    const json = doc.toJSON() as { row?: { meta?: { k?: string } } };
+    expect(json.row?.meta?.k).toBe("v");
+  });
+});

package/src/index.ts

@@ -20,6 +20,10 @@
 import { useSyncExternalStore, useEffect, useRef } from "react";
 import type { FormEvent, RefObject } from "react";
 import type { LoroDoc, LoroText, LoroMap } from "loro-crdt";
+import {
+  LoroText as LoroTextCtor,
+  LoroMap as LoroMapCtor,
+} from "loro-crdt";
 import { db, getBaseUrl, getReactStorage, storageKey } from "@pylonsync/react";
 import { pylonFetch, type SyncEngine } from "@pylonsync/sync";
 import { globalRegistry, LoroRegistry } from "./registry";
@@ -117,30 +121,84 @@ export function useLoroDoc(entity: string, id: string): LoroDoc {
     };
   }, [entity, id]);
 
-  // useSyncExternalStore drives re-renders. The snapshot is the doc
-  // itself (referentially stable across calls — same instance from
-  // the registry), so React's bail-out keeps re-renders bounded to
-  // when the registry's listener actually fires.
+  // useSyncExternalStore drives re-renders. The SNAPSHOT is the row's
+  // monotonic version counter, not the doc: the doc instance is
+  // intentionally stable across renders, and React bails out of
+  // re-rendering when the snapshot is Object.is-equal — a stable doc
+  // snapshot would swallow every notification. The version bumps on
+  // each applied frame AND on each local `touch()` after a commit, so
+  // consumers re-render optimistically on their own edits instead of
+  // waiting for the server's post-merge echo.
   const subscribe = (notify: () => void) =>
     globalRegistry.subscribe(entity, id, notify);
-  const getSnapshot = () => globalRegistry.doc(entity, id);
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const getVersion = () => globalRegistry.version(entity, id);
+  useSyncExternalStore(subscribe, getVersion, getVersion);
+  return globalRegistry.doc(entity, id);
 }
 
 /**
- * Convenience: get a `LoroText` container at the given top-level key,
- * creating it if absent. Wraps `doc.getText(key)` so callers don't
- * have to import loro-crdt directly for the common case.
+ * The server's projection contract (crates/crdt): each entity row's doc
+ * holds ONE root `LoroMap` named "row"; its keys are the entity's field
+ * names, and a `crdt: "text"` field is a `LoroText` CHILD of that map.
+ * The server seeds those containers at insert and projects them back to
+ * SQL columns after every merge — a text container anywhere else in the
+ * doc is invisible to it. Every field accessor here must resolve through
+ * this map or client edits silently diverge from the server's view.
+ */
+const ROOT_MAP = "row";
+
+function containerOfKind<C>(value: unknown, kind: string): C | null {
+  if (
+    value &&
+    typeof value === "object" &&
+    typeof (value as { kind?: unknown }).kind === "function" &&
+    (value as { kind: () => string }).kind() === kind
+  ) {
+    return value as C;
+  }
+  return null;
+}
+
+/**
+ * Read-only resolve of the field's `LoroText` under the `"row"` root
+ * map. Returns null when the container doesn't exist yet — crucially it
+ * NEVER creates one: a read-path create races the server's catch-up
+ * snapshot, and when the server's seeded container wins the map-key LWW
+ * the eagerly-created one is orphaned — every edit made through a
+ * captured handle then mutates a container nothing projects or renders.
+ */
+export function resolveLoroText(doc: LoroDoc, key: string): LoroText | null {
+  return containerOfKind<LoroText>(doc.getMap(ROOT_MAP).get(key), "Text");
+}
+
+/**
+ * Get the `LoroText` for an entity FIELD, resolving through the server's
+ * `"row"` root map. The server seeds the container at insert, so the
+ * common case finds it (carrying the row's initial value); creation only
+ * happens on the WRITE path for rows that predate CRDT mode. Callers
+ * must re-resolve per operation rather than capture the handle — after a
+ * catch-up snapshot merges, the live container can be a different
+ * instance than the one an earlier render saw. Identified by `kind()`
+ * rather than instanceof so a duplicated loro-crdt module in the bundle
+ * can't break the check.
  */
 export function getLoroText(doc: LoroDoc, key: string): LoroText {
-  return doc.getText(key);
+  const existing = resolveLoroText(doc, key);
+  if (existing) return existing;
+  return doc
+    .getMap(ROOT_MAP)
+    .setContainer(key, new LoroTextCtor()) as LoroText;
 }
 
 /**
- * Convenience: get a `LoroMap` container at the given top-level key.
+ * Get the `LoroMap` for an entity FIELD (a map child of the `"row"`
+ * root). For the root map itself use `doc.getMap("row")` directly.
  */
 export function getLoroMap(doc: LoroDoc, key: string): LoroMap {
-  return doc.getMap(key);
+  const row = doc.getMap(ROOT_MAP);
+  const existing = containerOfKind<LoroMap>(row.get(key), "Map");
+  if (existing) return existing;
+  return row.setContainer(key, new LoroMapCtor()) as LoroMap;
 }
 
 /**
@@ -172,9 +230,11 @@ export function useCollabText(
   field: string,
 ): [string, (next: string) => void] {
   const doc = useLoroDoc(entity, id);
-  const text = doc.getText(field);
-  const value = text.toString();
+  // Re-resolved every render/operation, never captured: the live
+  // container can change identity when the catch-up snapshot merges.
+  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})`
@@ -188,6 +248,8 @@ export function useCollabText(
       text.insert(0, next);
     }
     doc.commit();
+    // Optimistic render: notify every consumer of this row NOW.
+    globalRegistry.touch(entity, id);
 
     const update = doc.export({ mode: "update", from: beforeVv });
     if (update.length === 0) {
@@ -243,8 +305,10 @@ export function useCollabTextarea<
   onInput: (e: FormEvent<T>) => void;
 } {
   const doc = useLoroDoc(entity, id);
-  const text = doc.getText(field);
-  const value = text.toString(); // re-renders on every applied frame
+  // Re-resolved every render, never captured: the live container can
+  // change identity when the catch-up snapshot merges (see
+  // resolveLoroText), and a stale handle would edit an orphan.
+  const value = resolveLoroText(doc, field)?.toString() ?? ""; // re-renders on every applied frame
   const ref = useRef<T | null>(null);
   // The value we last reconciled into the DOM element. Lets us tell our own
   // edits (element already correct — skip) from remote frames (patch the DOM).
@@ -279,12 +343,18 @@ export function useCollabTextarea<
     const prev = domValue.current;
     if (next === prev) return;
     const { index, deleteCount, insert } = spliceDiff(prev, next);
-    // Capture the version vector BEFORE mutating so we ship exactly the new ops.
+    // Resolve the container per keystroke (see resolveLoroText) and
+    // capture the version vector BEFORE mutating so we ship exactly the
+    // new ops.
+    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.
+    globalRegistry.touch(entity, id);
     const update = doc.export({ mode: "update", from: beforeVv });
     if (update.length > 0) void pushCrdtUpdate(entity, id, update);
   };

package/src/registry.test.ts

@@ -4,7 +4,7 @@
 // ---------------------------------------------------------------------------
 
 import { test, expect } from "bun:test";
-import { LoroDoc } from "loro-crdt";
+import { LoroDoc, LoroText } from "loro-crdt";
 import { LoroRegistry } from "./registry";
 import { CRDT_FRAME_SNAPSHOT, encodeCrdtFrame } from "./wire";
 
@@ -150,3 +150,16 @@ test("two registries hydrated from snapshots converge after exchange", () => {
   expect(aText).toBe(bText);
   expect(aText.length).toBeGreaterThan(0);
 });
+
+test("touch bumps the version and notifies — optimistic local renders", () => {
+  const reg = new LoroRegistry();
+  const doc = reg.doc("Doc", "r1");
+  let notified = 0;
+  reg.subscribe("Doc", "r1", () => notified++);
+  const before = reg.version("Doc", "r1");
+  doc.getMap("row").setContainer("content", new LoroText()).insert(0, "x");
+  doc.commit();
+  reg.touch("Doc", "r1");
+  expect(reg.version("Doc", "r1")).toBe(before + 1);
+  expect(notified).toBe(1);
+});

package/src/registry.ts

@@ -31,6 +31,12 @@ type Listener = () => void;
 interface DocEntry {
   doc: LoroDoc;
   listeners: Set<Listener>;
+  /** Bumped on every applied frame, local touch, and eviction. Hooks
+   *  use this as their useSyncExternalStore snapshot: the doc instance
+   *  is intentionally stable across renders, and a stable snapshot
+   *  makes React bail out of re-rendering — so notifications must be
+   *  accompanied by a value that actually changes. */
+  version: number;
 }
 
 export class LoroRegistry {
@@ -82,6 +88,7 @@ export class LoroRegistry {
       );
       return false;
     }
+    entry.version += 1;
     for (const listener of entry.listeners) {
       try {
         listener();
@@ -92,6 +99,29 @@ export class LoroRegistry {
     return true;
   }
 
+  /** Monotonic per-row change counter — the render snapshot for hooks.
+   *  Zero for rows the registry hasn't seen. */
+  version(entity: string, rowId: string): number {
+    return this.docs.get(this.key(entity, rowId))?.version ?? 0;
+  }
+
+  /** Record a LOCAL mutation on a row's doc (the hooks call this right
+   *  after `doc.commit()`): bumps the version and notifies subscribers
+   *  so every component reading the row re-renders NOW, optimistically
+   *  — not when the server's post-merge broadcast echoes back. */
+  touch(entity: string, rowId: string): void {
+    const entry = this.docs.get(this.key(entity, rowId));
+    if (!entry) return;
+    entry.version += 1;
+    for (const listener of entry.listeners) {
+      try {
+        listener();
+      } catch (err) {
+        console.warn("[loro] listener threw:", err);
+      }
+    }
+  }
+
   /** Drop the cached doc for a row. Tests + the eventual eviction
    *  policy. Subscribers receive a final notify before the entry
    *  is removed so they can detect the drop and re-create their
@@ -100,6 +130,7 @@ export class LoroRegistry {
     const key = this.key(entity, rowId);
     const entry = this.docs.get(key);
     if (!entry) return;
+    entry.version += 1;
     for (const listener of entry.listeners) {
       try {
         listener();
@@ -119,7 +150,7 @@ export class LoroRegistry {
     const key = this.key(entity, rowId);
     let entry = this.docs.get(key);
     if (!entry) {
-      entry = { doc: new LoroDoc(), listeners: new Set() };
+      entry = { doc: new LoroDoc(), listeners: new Set(), version: 0 };
       this.docs.set(key, entry);
     }
     return entry;