@agent-native/toolkit 0.19.3 → 0.19.4-nightly-20260903220410

package/src/editor/surgical-apply.ts

@@ -41,6 +41,197 @@ export interface TopLevelDiff {
   toPos: number;
 }
 
+export interface TopLevelHunk {
+  baseFromIndex: number;
+  baseToIndex: number;
+  changedFromIndex: number;
+  changedToIndex: number;
+}
+
+export type BaseAwareReconcileResult =
+  | { status: "noop" }
+  | { status: "applied"; mergedDoc: ProseMirrorNode }
+  | { status: "conflict"; localDraft: ProseMirrorNode }
+  | { status: "failed"; reason: "schema" | "ambiguous" | "transaction" };
+
+function nodesEqual(left: ProseMirrorNode, right: ProseMirrorNode): boolean {
+  return left.eq(right);
+}
+
+/**
+ * Return every changed top-level run in base coordinates. The bounded LCS is
+ * intentionally conservative: large or duplicate-heavy ambiguous documents
+ * fail closed instead of guessing which identical block an edit targeted.
+ */
+export function diffTopLevelHunks(
+  baseDoc: ProseMirrorNode,
+  changedDoc: ProseMirrorNode,
+): TopLevelHunk[] | null {
+  const base = Array.from({ length: baseDoc.childCount }, (_, i) =>
+    baseDoc.child(i),
+  );
+  const changed = Array.from({ length: changedDoc.childCount }, (_, i) =>
+    changedDoc.child(i),
+  );
+  if (base.length * changed.length > 250_000) return null;
+
+  const width = changed.length + 1;
+  const lcs = new Uint32Array((base.length + 1) * width);
+  for (let i = base.length - 1; i >= 0; i--) {
+    for (let j = changed.length - 1; j >= 0; j--) {
+      lcs[i * width + j] = nodesEqual(base[i], changed[j])
+        ? 1 + lcs[(i + 1) * width + j + 1]
+        : Math.max(lcs[(i + 1) * width + j], lcs[i * width + j + 1]);
+    }
+  }
+
+  const matches: Array<[number, number]> = [];
+  let i = 0;
+  let j = 0;
+  while (i < base.length && j < changed.length) {
+    if (nodesEqual(base[i], changed[j])) {
+      matches.push([i++, j++]);
+      continue;
+    }
+    const skipBase = lcs[(i + 1) * width + j];
+    const skipChanged = lcs[i * width + j + 1];
+    if (skipBase === skipChanged) {
+      const insertion =
+        j + 1 < changed.length && nodesEqual(base[i], changed[j + 1]);
+      const deletion =
+        i + 1 < base.length && nodesEqual(base[i + 1], changed[j]);
+      if (insertion !== deletion) {
+        if (insertion) j++;
+        else i++;
+        continue;
+      }
+      // A plain substitution leaves the same suffix LCS after advancing both
+      // sides. Treat that as one changed run; only competing cross-matches are
+      // ambiguous enough to fail closed.
+      const skipBoth = lcs[(i + 1) * width + j + 1];
+      if (skipBoth === skipBase) {
+        i++;
+        j++;
+        continue;
+      }
+      return null;
+    }
+    if (skipBase > skipChanged) i++;
+    else j++;
+  }
+
+  const hunks: TopLevelHunk[] = [];
+  let baseCursor = 0;
+  let changedCursor = 0;
+  for (const [baseMatch, changedMatch] of [
+    ...matches,
+    [base.length, changed.length] as [number, number],
+  ]) {
+    if (baseCursor !== baseMatch || changedCursor !== changedMatch) {
+      hunks.push({
+        baseFromIndex: baseCursor,
+        baseToIndex: baseMatch,
+        changedFromIndex: changedCursor,
+        changedToIndex: changedMatch,
+      });
+    }
+    baseCursor = baseMatch + 1;
+    changedCursor = changedMatch + 1;
+  }
+  return hunks;
+}
+
+function hunksOverlap(left: TopLevelHunk, right: TopLevelHunk): boolean {
+  const leftInsert = left.baseFromIndex === left.baseToIndex;
+  const rightInsert = right.baseFromIndex === right.baseToIndex;
+  if (leftInsert && rightInsert) {
+    return left.baseFromIndex === right.baseFromIndex;
+  }
+  if (leftInsert) {
+    return (
+      left.baseFromIndex >= right.baseFromIndex &&
+      left.baseFromIndex <= right.baseToIndex
+    );
+  }
+  if (rightInsert) {
+    return (
+      right.baseFromIndex >= left.baseFromIndex &&
+      right.baseFromIndex <= left.baseToIndex
+    );
+  }
+  return (
+    left.baseFromIndex < right.baseToIndex &&
+    right.baseFromIndex < left.baseToIndex
+  );
+}
+
+function mappedLocalIndex(
+  baseIndex: number,
+  localHunks: readonly TopLevelHunk[],
+): number {
+  let mapped = baseIndex;
+  for (const hunk of localHunks) {
+    if (hunk.baseToIndex > baseIndex) break;
+    mapped +=
+      hunk.changedToIndex -
+      hunk.changedFromIndex -
+      (hunk.baseToIndex - hunk.baseFromIndex);
+  }
+  return mapped;
+}
+
+/** Apply authoritative server changes onto a locally edited document. */
+export function reconcileDocAgainstBase(
+  editor: Editor,
+  baseDoc: ProseMirrorNode,
+  serverDoc: ProseMirrorNode,
+): BaseAwareReconcileResult {
+  const liveDoc = editor.state.doc;
+  if (
+    baseDoc.type.schema !== editor.schema ||
+    serverDoc.type.schema !== editor.schema ||
+    baseDoc.type !== liveDoc.type ||
+    serverDoc.type !== liveDoc.type
+  ) {
+    return { status: "failed", reason: "schema" };
+  }
+  const localHunks = diffTopLevelHunks(baseDoc, liveDoc);
+  const serverHunks = diffTopLevelHunks(baseDoc, serverDoc);
+  if (!localHunks || !serverHunks) {
+    return { status: "failed", reason: "ambiguous" };
+  }
+  if (serverHunks.length === 0) return { status: "noop" };
+  if (
+    localHunks.some((local) =>
+      serverHunks.some((server) => hunksOverlap(local, server)),
+    )
+  ) {
+    return { status: "conflict", localDraft: liveDoc };
+  }
+
+  try {
+    const tr = editor.state.tr;
+    for (const hunk of [...serverHunks].reverse()) {
+      const fromIndex = mappedLocalIndex(hunk.baseFromIndex, localHunks);
+      const toIndex = mappedLocalIndex(hunk.baseToIndex, localHunks);
+      tr.replaceWith(
+        positionOfChild(tr.doc, fromIndex),
+        positionOfChild(tr.doc, toIndex),
+        serverDoc.content.cut(
+          positionOfChild(serverDoc, hunk.changedFromIndex),
+          positionOfChild(serverDoc, hunk.changedToIndex),
+        ),
+      );
+    }
+    tr.setMeta("addToHistory", false);
+    tr.setMeta(RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION, true);
+    editor.view.dispatch(tr);
+    return { status: "applied", mergedDoc: editor.state.doc };
+  } catch {
+    return { status: "failed", reason: "transaction" };
+  }
+}
+
 /**
  * Diff two documents at top-level-node granularity: trim the common prefix and
  * suffix (node equality via ProseMirror's `Node.eq`, which is deep) and return

package/src/editor/useCollabReconcile.concurrent.spec.ts

@@ -48,12 +48,16 @@ afterEach(() => {
 interface HarnessProps {
   value: string;
   contentUpdatedAt: string;
+  contentRevision?: string;
   editorOwnedFocus?: boolean;
 }
 
 interface CollabSeedHarnessProps {
   collabSynced: boolean;
   fragmentLength: number;
+  value?: string;
+  contentRevision?: string;
+  contentUpdatedAt?: string;
 }
 
 interface Captured {
@@ -61,6 +65,10 @@ interface Captured {
   emitted: string[];
   setContentCalls: number;
   registerEmitted?: (markdown: string) => boolean;
+  reconciled?: Array<{
+    status: "merged" | "conflict" | "failed";
+    content: string;
+  }>;
 }
 
 function makeHarness() {
@@ -69,6 +77,7 @@ function makeHarness() {
   function Harness({
     value,
     contentUpdatedAt,
+    contentRevision,
     editorOwnedFocus = false,
   }: HarnessProps) {
     const guardsRef = React.useRef<ReturnType<
@@ -92,6 +101,13 @@ function makeHarness() {
       editor,
       value,
       contentUpdatedAt,
+      contentRevision,
+      onBaseAwareReconcile: (result) => {
+        (captured.reconciled ??= []).push({
+          status: result.status,
+          content: result.content,
+        });
+      },
       editable: true,
       isEditorFocused: () => editorOwnedFocus,
       getMarkdown: getEditorMarkdown,
@@ -122,7 +138,13 @@ function makeHarness() {
 function makeCollabSeedHarness(initialContent = "") {
   const captured: Captured = { editor: null, emitted: [], setContentCalls: 0 };
 
-  function Harness({ collabSynced, fragmentLength }: CollabSeedHarnessProps) {
+  function Harness({
+    collabSynced,
+    fragmentLength,
+    value = "seeded content",
+    contentRevision,
+    contentUpdatedAt = "2024-01-01T00:00:01.000Z",
+  }: CollabSeedHarnessProps) {
     const guardsRef = React.useRef<ReturnType<
       typeof useCollabReconcile
     > | null>(null);
@@ -153,8 +175,15 @@ function makeCollabSeedHarness(initialContent = "") {
       editor,
       ydoc: fakeYdoc as never,
       collabSynced,
-      value: "seeded content",
-      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      value,
+      contentUpdatedAt,
+      contentRevision,
+      onBaseAwareReconcile: (result) => {
+        (captured.reconciled ??= []).push({
+          status: result.status,
+          content: result.content,
+        });
+      },
       editable: true,
       getMarkdown: getEditorMarkdown,
       setContent: (ed, v) => {
@@ -189,6 +218,62 @@ function render(
 }
 
 describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
+  it("merges a newer non-overlapping revision and reports the combined draft", async () => {
+    const { captured, Harness } = makeHarness();
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      contentRevision: "revision-1",
+    });
+    await flush();
+
+    act(() =>
+      captured.editor!.commands.setContent("Alpha local\n\nBravo\n\nCharlie"),
+    );
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie server",
+      contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+      contentRevision: "revision-2",
+    });
+    await flush();
+
+    expect(captured.reconciled).toEqual([
+      {
+        status: "merged",
+        content: "Alpha local\n\nBravo\n\nCharlie server",
+      },
+    ]);
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha local\n\nBravo\n\nCharlie server",
+    );
+  });
+
+  it("reports an overlap once and preserves the local draft", async () => {
+    const { captured, Harness } = makeHarness();
+    render(root, Harness, {
+      value: "Alpha\n\nBravo",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      contentRevision: "revision-1",
+    });
+    await flush();
+    act(() => captured.editor!.commands.setContent("Alpha local\n\nBravo"));
+
+    const newer = {
+      value: "Alpha server\n\nBravo",
+      contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+      contentRevision: "revision-2",
+    };
+    render(root, Harness, newer);
+    await flush();
+    render(root, Harness, newer);
+    await flush();
+
+    expect(getEditorMarkdown(captured.editor!)).toBe("Alpha local\n\nBravo");
+    expect(captured.reconciled).toEqual([
+      { status: "conflict", content: "Alpha local\n\nBravo" },
+    ]);
+  });
+
   it("persists the first local edit after a synced empty collaborative document", async () => {
     const captured: Captured = {
       editor: null,
@@ -296,6 +381,47 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
     expect(getEditorMarkdown(captured.editor!)).toBe("seeded content");
   });
 
+  it("uses the collaborative seed as the base for a later three-way merge", async () => {
+    const { captured, Harness } = makeCollabSeedHarness();
+    act(() => {
+      root.render(
+        React.createElement(Harness, {
+          collabSynced: true,
+          fragmentLength: 0,
+          value: "Alpha\n\nBravo\n\nCharlie",
+          contentRevision: "revision-1",
+        }),
+      );
+    });
+    await flush();
+
+    act(() =>
+      captured.editor!.commands.setContent("Alpha local\n\nBravo\n\nCharlie"),
+    );
+    act(() => {
+      root.render(
+        React.createElement(Harness, {
+          collabSynced: true,
+          fragmentLength: 1,
+          value: "Alpha\n\nBravo\n\nCharlie server",
+          contentRevision: "revision-2",
+          contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+        }),
+      );
+    });
+    await flush();
+
+    expect(captured.reconciled).toEqual([
+      {
+        status: "merged",
+        content: "Alpha local\n\nBravo\n\nCharlie server",
+      },
+    ]);
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha local\n\nBravo\n\nCharlie server",
+    );
+  });
+
   it("applies a deliberate REVERT to a previously-applied value after a local edit (not swallowed as echo)", async () => {
     // Regression for the revert-safety carve-out: the doc-equivalence echo
     // guards (value === lastAppliedValueRef) only fire when the editor is

package/src/editor/useCollabReconcile.ts

@@ -11,6 +11,7 @@ import {
   RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION,
   applyDocSurgically,
   defaultParseValue,
+  reconcileDocAgainstBase,
 } from "./surgical-apply.js";
 
 export { RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION };
@@ -60,6 +61,16 @@ export interface UseCollabReconcileOptions {
   value: string;
   /** Timestamp of the authoritative value; gates newer-than reconcile. */
   contentUpdatedAt?: string | null;
+  /** Opaque authoritative body revision. Enables base-aware reconciliation. */
+  contentRevision?: string | null;
+  /** Reports an automatic merge to persist, or a conflict whose local draft was preserved. */
+  onBaseAwareReconcile?: (result: {
+    status: "merged" | "conflict" | "failed";
+    content: string;
+    serverContent: string;
+    baseRevision: string;
+    serverRevision: string;
+  }) => void;
   /** Whether the editor accepts edits. Reconcile/seed only run for the live editor. */
   editable: boolean;
   /**
@@ -234,6 +245,8 @@ export function useCollabReconcile({
   awareness = null,
   value,
   contentUpdatedAt,
+  contentRevision,
+  onBaseAwareReconcile,
   editable,
   isEditorFocused = defaultIsEditorFocused,
   getMarkdown = getEditorMarkdown,
@@ -272,6 +285,11 @@ export function useCollabReconcile({
       ? initialAppliedUpdatedAt
       : (contentUpdatedAt ?? null),
   );
+  const authoritativeBaseRef = useRef<{
+    value: string;
+    revision: string;
+  } | null>(contentRevision ? { value, revision: contentRevision } : null);
+  const reportedConflictRevisionRef = useRef<string | null>(null);
 
   // Whether THIS client is the one that seeds the empty shared doc / applies an
   // authoritative external snapshot into it. Exactly one client does, so the
@@ -329,6 +347,10 @@ export function useCollabReconcile({
     if (!collab || !editor || editor.isDestroyed || !ydoc) return;
     if (seededRef.current) return;
     if (!collabSynced) return;
+    if (contentRevision) {
+      authoritativeBaseRef.current = { value, revision: contentRevision };
+      reportedConflictRevisionRef.current = null;
+    }
     // An empty SQL value has nothing to seed. Release the first real keystroke
     // immediately, but when a fragment already exists defer the ambiguous
     // reconcile decision for one task: active-peer or just-emitted local content
@@ -431,6 +453,7 @@ export function useCollabReconcile({
     value,
     isLeadClient,
     contentUpdatedAt,
+    contentRevision,
     getMarkdown,
     setContent,
     shouldSeed,
@@ -519,6 +542,10 @@ export function useCollabReconcile({
           (value === lastAppliedValueRef.current ||
             normalizedValue === lastAppliedSerializedRef.current))
       ) {
+        if (contentRevision) {
+          authoritativeBaseRef.current = { value, revision: contentRevision };
+          reportedConflictRevisionRef.current = null;
+        }
         if (contentUpdatedAt) {
           lastAppliedUpdatedAtRef.current = contentUpdatedAt;
         }
@@ -596,6 +623,74 @@ export function useCollabReconcile({
           return;
         }
         isSettingContentRef.current = true;
+        const authoritativeBase = authoritativeBaseRef.current;
+        if (
+          contentRevision &&
+          onBaseAwareReconcile &&
+          authoritativeBase &&
+          authoritativeBase.revision !== contentRevision
+        ) {
+          const parse =
+            parseValue === false ? null : (parseValue ?? defaultParseValue);
+          const baseDoc = parse?.(editor, authoritativeBase.value) ?? null;
+          const serverDoc = parse?.(editor, value) ?? null;
+          if (!baseDoc || !serverDoc) {
+            isSettingContentRef.current = false;
+            if (reportedConflictRevisionRef.current !== contentRevision) {
+              reportedConflictRevisionRef.current = contentRevision;
+              onBaseAwareReconcile({
+                status: "failed",
+                content: beforeMarkdown,
+                serverContent: value,
+                baseRevision: authoritativeBase.revision,
+                serverRevision: contentRevision,
+              });
+            }
+            return;
+          }
+          const reconciled = reconcileDocAgainstBase(
+            editor,
+            baseDoc,
+            serverDoc,
+          );
+          if (
+            reconciled.status === "conflict" ||
+            reconciled.status === "failed"
+          ) {
+            isSettingContentRef.current = false;
+            if (reportedConflictRevisionRef.current !== contentRevision) {
+              reportedConflictRevisionRef.current = contentRevision;
+              onBaseAwareReconcile({
+                status: reconciled.status,
+                content: beforeMarkdown,
+                serverContent: value,
+                baseRevision: authoritativeBase.revision,
+                serverRevision: contentRevision,
+              });
+            }
+            return;
+          }
+          const merged = getMarkdown(editor);
+          isSettingContentRef.current = false;
+          authoritativeBaseRef.current = { value, revision: contentRevision };
+          reportedConflictRevisionRef.current = null;
+          lastEmittedRef.current = merged;
+          pushEmittedRing(recentEmittedRef.current, merged);
+          lastAppliedValueRef.current = value;
+          lastAppliedSerializedRef.current = merged;
+          if (contentUpdatedAt)
+            lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+          if (reconciled.status === "applied" && merged !== normalized) {
+            onBaseAwareReconcile({
+              status: "merged",
+              content: merged,
+              serverContent: value,
+              baseRevision: authoritativeBase.revision,
+              serverRevision: contentRevision,
+            });
+          }
+          return;
+        }
         // Surgical path first: replace only the changed top-level run so
         // unchanged block NodeViews are never torn down and (under
         // Collaboration) Yjs sees a minimal edit instead of a full-fragment
@@ -623,6 +718,10 @@ export function useCollabReconcile({
         pushEmittedRing(recentEmittedRef.current, serialized);
         lastAppliedValueRef.current = value;
         lastAppliedSerializedRef.current = serialized;
+        if (contentRevision) {
+          authoritativeBaseRef.current = { value, revision: contentRevision };
+          reportedConflictRevisionRef.current = null;
+        }
         if (contentUpdatedAt) {
           lastAppliedUpdatedAtRef.current = contentUpdatedAt;
         }
@@ -637,6 +736,7 @@ export function useCollabReconcile({
     };
   }, [
     contentUpdatedAt,
+    contentRevision,
     editor,
     value,
     collab,
@@ -647,6 +747,7 @@ export function useCollabReconcile({
     parseValue,
     normalizeValue,
     isEditorFocused,
+    onBaseAwareReconcile,
   ]);
 
   const shouldIgnoreUpdate = (transaction: Transaction): boolean => {