@agent-native/toolkit 0.10.4 → 0.10.6

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

@@ -1,9 +1,12 @@
 // @vitest-environment happy-dom
 
+import { Editor as CoreEditor } from "@tiptap/core";
 import { useEditor, type Editor } from "@tiptap/react";
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Awareness } from "y-protocols/awareness";
+import * as Y from "yjs";
 
 import { createRichMarkdownExtensions } from "./RichMarkdownEditor.js";
 import { useCollabReconcile, getEditorMarkdown } from "./useCollabReconcile.js";
@@ -38,6 +41,7 @@ beforeEach(() => {
 
 afterEach(() => {
   act(() => root.unmount());
+  vi.useRealTimers();
   container.remove();
 });
 
@@ -330,6 +334,37 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
     expect(results).toEqual([true]);
   });
 
+  it("allows the first user edit after an authoritative empty doc finishes loading", async () => {
+    let shouldIgnoreUpdate:
+      | ((transaction: Editor["state"]["tr"]) => boolean)
+      | null = null;
+    let editor: Editor | null = null;
+
+    function Probe() {
+      editor = useEditor({
+        extensions: createRichMarkdownExtensions({ dialect: "gfm" }),
+        content: "",
+      });
+      const fakeYdoc = { clientID: 1, getXmlFragment: () => ({ length: 0 }) };
+      const guards = useCollabReconcile({
+        editor,
+        ydoc: fakeYdoc as never,
+        collabSynced: true,
+        value: "",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+      });
+      shouldIgnoreUpdate = guards.shouldIgnoreUpdate;
+      return React.createElement("div", null);
+    }
+
+    act(() => root.render(React.createElement(Probe)));
+
+    expect(editor).not.toBeNull();
+    expect(shouldIgnoreUpdate).not.toBeNull();
+    expect(shouldIgnoreUpdate!(editor!.state.tr)).toBe(false);
+  });
+
   it("refuses to persist an empty doc in collab mode (registerEmitted guard)", async () => {
     // Directly exercise the guard contract: in collab mode an empty markdown
     // string must not be registered/persisted (would clobber stored content
@@ -399,6 +434,240 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
     expect(setContentValues).toEqual(["second seed"]);
   });
 
+  it("does not seed beside persisted Y.Doc content projected during initial sync", async () => {
+    const persistedYdoc = new Y.Doc();
+    const persistedEditor = new CoreEditor({
+      extensions: createRichMarkdownExtensions({
+        dialect: "gfm",
+        ydoc: persistedYdoc,
+      }),
+    });
+    persistedEditor.commands.setContent("persisted collab body");
+    const persistedUpdate = Y.encodeStateAsUpdate(persistedYdoc);
+    persistedEditor.destroy();
+    persistedYdoc.destroy();
+
+    const liveYdoc = new Y.Doc();
+    const setContentValues: string[] = [];
+    let capturedEditor: Editor | null = null;
+
+    function Probe({ collabSynced }: { collabSynced: boolean }) {
+      const editor = useEditor({
+        extensions: createRichMarkdownExtensions({
+          dialect: "gfm",
+          ydoc: liveYdoc,
+        }),
+      });
+      capturedEditor = editor;
+      useCollabReconcile({
+        editor,
+        ydoc: liveYdoc,
+        collabSynced,
+        value: "persisted collab body",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+        setContent: (_editor, nextValue) => {
+          setContentValues.push(nextValue);
+        },
+      });
+      return React.createElement("div", null);
+    }
+
+    act(() => root.render(React.createElement(Probe, { collabSynced: false })));
+    act(() => Y.applyUpdate(liveYdoc, persistedUpdate, "remote"));
+    act(() => root.render(React.createElement(Probe, { collabSynced: true })));
+    await flush();
+
+    expect(getEditorMarkdown(capturedEditor!)).toBe("persisted collab body");
+    expect(setContentValues).toEqual([]);
+    expect(
+      getEditorMarkdown(capturedEditor!).match(/persisted collab body/g),
+    ).toHaveLength(1);
+    liveYdoc.destroy();
+  });
+
+  it("adopts a nonempty synced Y.Doc instead of reconciling an empty SQL snapshot", async () => {
+    vi.useFakeTimers();
+    const persistedYdoc = new Y.Doc();
+    const persistedEditor = new CoreEditor({
+      extensions: createRichMarkdownExtensions({
+        dialect: "gfm",
+        ydoc: persistedYdoc,
+      }),
+    });
+    persistedEditor.commands.setContent("live collaborator body");
+    const liveYdoc = new Y.Doc();
+    Y.applyUpdate(liveYdoc, Y.encodeStateAsUpdate(persistedYdoc), "remote");
+    persistedEditor.destroy();
+    persistedYdoc.destroy();
+
+    const awareness = new Awareness(liveYdoc);
+    const setContentValues: string[] = [];
+    let capturedEditor: Editor | null = null;
+
+    function Probe() {
+      const editor = useEditor({
+        extensions: createRichMarkdownExtensions({
+          dialect: "gfm",
+          ydoc: liveYdoc,
+        }),
+      });
+      capturedEditor = editor;
+      useCollabReconcile({
+        editor,
+        ydoc: liveYdoc,
+        awareness,
+        collabSynced: true,
+        value: "",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+        setContent: (_editor, nextValue) => {
+          setContentValues.push(nextValue);
+        },
+      });
+      return React.createElement("div", null);
+    }
+
+    act(() => root.render(React.createElement(Probe)));
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+    // The document state can finish syncing before the first awareness poll.
+    // Publish the active peer after mount to cover that real transport order.
+    act(() => {
+      awareness.getStates().set(4_294_967_295, {
+        user: { name: "Active peer" },
+        visible: true,
+      });
+      awareness.emit("change", [
+        { added: [4_294_967_295], updated: [], removed: [] },
+        "remote",
+      ]);
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(2500));
+
+    expect(getEditorMarkdown(capturedEditor!)).toBe("live collaborator body");
+    expect(setContentValues).toEqual([]);
+    vi.useRealTimers();
+    awareness.destroy();
+    liveYdoc.destroy();
+  });
+
+  it("lets canonical empty SQL clear stale persisted Y.Doc content with no active peer", async () => {
+    const persistedYdoc = new Y.Doc();
+    const persistedEditor = new CoreEditor({
+      extensions: createRichMarkdownExtensions({
+        dialect: "gfm",
+        ydoc: persistedYdoc,
+      }),
+    });
+    persistedEditor.commands.setContent("stale persisted body");
+    const liveYdoc = new Y.Doc();
+    Y.applyUpdate(liveYdoc, Y.encodeStateAsUpdate(persistedYdoc), "remote");
+    persistedEditor.destroy();
+    persistedYdoc.destroy();
+
+    const setContentValues: string[] = [];
+    let capturedEditor: Editor | null = null;
+    const awareness = new Awareness(liveYdoc);
+
+    function Probe() {
+      const editor = useEditor({
+        extensions: createRichMarkdownExtensions({
+          dialect: "gfm",
+          ydoc: liveYdoc,
+        }),
+      });
+      capturedEditor = editor;
+      useCollabReconcile({
+        editor,
+        ydoc: liveYdoc,
+        awareness,
+        collabSynced: true,
+        value: "",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+        setContent: (editorToClear, nextValue) => {
+          setContentValues.push(nextValue);
+          editorToClear.commands.setContent(nextValue);
+        },
+      });
+      return React.createElement("div", null);
+    }
+
+    vi.useFakeTimers();
+    act(() => root.render(React.createElement(Probe)));
+    await act(async () => vi.advanceTimersByTimeAsync(2499));
+    expect(setContentValues).toEqual([]);
+    await act(async () => vi.advanceTimersByTimeAsync(51));
+
+    expect(setContentValues).toContain("");
+    expect(getEditorMarkdown(capturedEditor!)).toBe("");
+    vi.useRealTimers();
+    awareness.destroy();
+    liveYdoc.destroy();
+  });
+
+  it("preserves and permits a first local edit during the awareness settle window", async () => {
+    const persistedYdoc = new Y.Doc();
+    const persistedEditor = new CoreEditor({
+      extensions: createRichMarkdownExtensions({
+        dialect: "gfm",
+        ydoc: persistedYdoc,
+      }),
+    });
+    persistedEditor.commands.setContent("stale persisted body");
+    const liveYdoc = new Y.Doc();
+    Y.applyUpdate(liveYdoc, Y.encodeStateAsUpdate(persistedYdoc), "remote");
+    persistedEditor.destroy();
+    persistedYdoc.destroy();
+
+    const awareness = new Awareness(liveYdoc);
+    let capturedEditor: Editor | null = null;
+    let guards: ReturnType<typeof useCollabReconcile> | null = null;
+    const setContentValues: string[] = [];
+
+    function Probe() {
+      const editor = useEditor({
+        extensions: createRichMarkdownExtensions({
+          dialect: "gfm",
+          ydoc: liveYdoc,
+        }),
+      });
+      capturedEditor = editor;
+      guards = useCollabReconcile({
+        editor,
+        ydoc: liveYdoc,
+        awareness,
+        collabSynced: true,
+        value: "",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+        setContent: (editorToSet, nextValue) => {
+          setContentValues.push(nextValue);
+          editorToSet.commands.setContent(nextValue);
+        },
+      });
+      return React.createElement("div", null);
+    }
+
+    vi.useFakeTimers();
+    act(() => root.render(React.createElement(Probe)));
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    expect(guards).not.toBeNull();
+    expect(capturedEditor).not.toBeNull();
+    expect(guards!.shouldIgnoreUpdate(capturedEditor!.state.tr)).toBe(false);
+    expect(guards!.registerEmitted("first local edit")).toBe(true);
+    act(() => capturedEditor!.commands.setContent("first local edit"));
+
+    await act(async () => vi.advanceTimersByTimeAsync(2500));
+    expect(getEditorMarkdown(capturedEditor!)).toBe("first local edit");
+    expect(setContentValues).toEqual([]);
+
+    vi.useRealTimers();
+    awareness.destroy();
+    liveYdoc.destroy();
+  });
+
   it("applies a genuinely newer external value once the user is no longer focused", async () => {
     const { captured, Harness } = makeHarness();
 

package/src/editor/useCollabReconcile.ts

@@ -33,6 +33,11 @@ export function getEditorMarkdown(editor: Editor): string {
  * is identical, so skipping it is safe by construction.
  */
 const EMITTED_RING_MAX = 16;
+// The hosted awareness transport polls every 2s when its SSE gateway cannot
+// forward presence. Give that first snapshot one poll plus margin before an
+// empty SQL value is allowed to clear a nonempty Y.Doc. This is the same settle
+// window used below when a known peer may deliver an edit through Yjs.
+const PEER_SETTLE_MS = 2500;
 function pushEmittedRing(ring: string[], value: string): void {
   if (!value) return;
   if (ring[ring.length - 1] === value) return;
@@ -264,6 +269,11 @@ export function useCollabReconcile({
   // arrives via Yjs, so external markdown reconcile must defer (avoid applying
   // the same change through both Yjs and setContent).
   const peerCountRef = useRef(0);
+  // Briefly gates the first empty-SQL reconcile while Collaboration projects
+  // a nonempty fragment. `seededRef` is still released immediately so a real
+  // first keystroke can persist; this ref only postpones the ambiguous clear
+  // decision until we can distinguish an active/local edit from stale CRDT.
+  const emptySnapshotDecisionPendingRef = useRef(false);
   useEffect(() => {
     if (!collab || !awareness || !ydoc) {
       setIsLeadClient(true);
@@ -299,25 +309,73 @@ export function useCollabReconcile({
     if (!collab || !editor || editor.isDestroyed || !ydoc) return;
     if (seededRef.current) return;
     if (!collabSynced) return;
-    if (!isLeadClient) return;
-    if (!value.trim()) return;
-    const fragment = ydoc.getXmlFragment("default");
-    const currentMarkdown = getMarkdown(editor);
-    // Seed only when the shared doc is genuinely empty — either the fragment has
-    // no nodes yet, or it holds no semantic markdown (an empty paragraph, or an
-    // app's sentinel-empty filler via a custom `shouldSeed`).
-    if (
-      !shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })
-    ) {
+    // 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
+    // is live and must be adopted; stale persisted CRDT with no active writer is
+    // cleared by the canonical SQL snapshot.
+    if (!value.trim()) {
       seededRef.current = true;
-      return;
-    }
+      const fragment = ydoc.getXmlFragment("default");
+      const currentMarkdown = getMarkdown(editor);
+      if (fragment.length === 0 && !currentMarkdown.trim()) return;
 
+      emptySnapshotDecisionPendingRef.current = true;
+      let cancelled = false;
+      const adoptTimer = setTimeout(
+        () => {
+          if (cancelled || editor.isDestroyed) return;
+          const projectedMarkdown = getMarkdown(editor);
+          const isOwnFreshEdit =
+            projectedMarkdown.trim() &&
+            (projectedMarkdown === lastEmittedRef.current ||
+              recentEmittedRef.current.includes(projectedMarkdown));
+          if (
+            projectedMarkdown.trim() &&
+            (peerCountRef.current > 0 || isOwnFreshEdit)
+          ) {
+            lastAppliedValueRef.current = value;
+            lastAppliedSerializedRef.current = projectedMarkdown;
+            if (contentUpdatedAt) {
+              lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+            }
+          }
+          emptySnapshotDecisionPendingRef.current = false;
+        },
+        awareness ? PEER_SETTLE_MS : 0,
+      );
+      return () => {
+        cancelled = true;
+        clearTimeout(adoptTimer);
+        emptySnapshotDecisionPendingRef.current = false;
+      };
+    }
+    if (!isLeadClient) return;
     let cancelled = false;
     // Defer via a timer task (NOT a microtask — microtasks can still run
     // inside React's commit and trigger flushSync-from-lifecycle warnings).
+    // Read the editor and fragment INSIDE that task. The collaboration
+    // extension can finish projecting an already-populated Y.Doc into
+    // ProseMirror after this effect is scheduled. Capturing the pre-projection
+    // empty editor here would incorrectly seed the SQL snapshot alongside the
+    // existing CRDT content, duplicating the whole document after reload.
     const seedTimer = setTimeout(() => {
       if (cancelled || editor.isDestroyed) return;
+      const fragment = ydoc.getXmlFragment("default");
+      const currentMarkdown = getMarkdown(editor);
+      // Seed only when the shared doc is genuinely empty — either the fragment
+      // has no nodes yet, or it holds no semantic markdown (an empty paragraph,
+      // or an app's sentinel-empty filler via a custom `shouldSeed`).
+      if (
+        !shouldSeed({
+          value,
+          currentMarkdown,
+          fragmentLength: fragment.length,
+        })
+      ) {
+        seededRef.current = true;
+        return;
+      }
       isSettingContentRef.current = true;
       try {
         setContent(editor, value, {});
@@ -362,16 +420,26 @@ export function useCollabReconcile({
     // With peers present, a peer's edit also arrives via Yjs. Defer one poll
     // cycle (+margin) and re-check before applying via setContent so the same
     // change isn't inserted twice (Yjs + setContent → duplicated region).
-    const PEER_SETTLE_MS = 2500;
-
     const apply = (deferred = false) => {
       if (cancelled || editor.isDestroyed) return;
       // In collab mode, defer all reconcile until the shared doc is seeded so we
       // never setContent over an unseeded fragment.
-      if (collab && (!collabSynced || !seededRef.current)) {
+      if (collab && !collabSynced) {
         retry = setTimeout(() => apply(deferred), 300);
         return;
       }
+      // The seed decision itself is deferred one task so Collaboration can
+      // project persisted Y.Doc state before we inspect it. Poll that short
+      // handoff promptly: waiting the full provider cadence here makes a newer
+      // canonical SQL snapshot visibly stale after reload.
+      if (collab && !seededRef.current) {
+        retry = setTimeout(() => apply(deferred), 25);
+        return;
+      }
+      if (collab && emptySnapshotDecisionPendingRef.current) {
+        retry = setTimeout(() => apply(deferred), 50);
+        return;
+      }
       const currentMarkdown = getMarkdown(editor);
       // Compare against the canonical form the editor would emit so a serializer
       // that re-normalizes (Content's NFM) still recognizes "already in sync".

package/src/ui/button.tsx

@@ -22,8 +22,7 @@ const buttonVariants = cva(
         default: "bg-primary text-primary-foreground hover:bg-primary/90",
         destructive:
           "bg-destructive text-destructive-foreground hover:bg-destructive/90",
-        outline:
-          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        outline: "bg-accent text-accent-foreground hover:bg-accent/80",
         secondary:
           "bg-secondary text-secondary-foreground hover:bg-secondary/80",
         ghost: "hover:bg-accent hover:text-accent-foreground",

package/src/ui/card.tsx

@@ -9,7 +9,7 @@ const Card = React.forwardRef<
   <div
     ref={ref}
     className={cn(
-      "rounded-lg border bg-card text-card-foreground shadow-sm",
+      "rounded-lg bg-card text-card-foreground shadow-sm",
       className,
     )}
     {...props}

package/src/ui/table.tsx

@@ -20,7 +20,7 @@ const TableHeader = React.forwardRef<
   HTMLTableSectionElement,
   React.HTMLAttributes<HTMLTableSectionElement>
 >(({ className, ...props }, ref) => (
-  <thead ref={ref} className={cn("[&_tr]:border-b", className)} {...props} />
+  <thead ref={ref} className={className} {...props} />
 ));
 TableHeader.displayName = "TableHeader";
 
@@ -28,11 +28,7 @@ const TableBody = React.forwardRef<
   HTMLTableSectionElement,
   React.HTMLAttributes<HTMLTableSectionElement>
 >(({ className, ...props }, ref) => (
-  <tbody
-    ref={ref}
-    className={cn("[&_tr:last-child]:border-0", className)}
-    {...props}
-  />
+  <tbody ref={ref} className={className} {...props} />
 ));
 TableBody.displayName = "TableBody";
 
@@ -42,10 +38,7 @@ const TableFooter = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <tfoot
     ref={ref}
-    className={cn(
-      "border-t bg-muted/50 font-medium [&>tr]:last:border-b-0",
-      className,
-    )}
+    className={cn("bg-muted/50 font-medium", className)}
     {...props}
   />
 ));
@@ -58,7 +51,7 @@ const TableRow = React.forwardRef<
   <tr
     ref={ref}
     className={cn(
-      "border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
+      "transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
       className,
     )}
     {...props}