@agent-native/toolkit 0.20.4-nightly-20260917183518 → 0.20.4

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

@@ -49,6 +49,7 @@ interface HarnessProps {
   value: string;
   contentUpdatedAt: string;
   contentRevision?: string;
+  compareContentRevisions?: (first: string, second: string) => number | null;
   acknowledgedLocalSnapshot?: {
     value: string;
     revision: string;
@@ -86,6 +87,7 @@ function makeHarness() {
     value,
     contentUpdatedAt,
     contentRevision,
+    compareContentRevisions,
     acknowledgedLocalSnapshot,
     editorOwnedFocus = false,
     isEditorFocused,
@@ -112,6 +114,7 @@ function makeHarness() {
       value,
       contentUpdatedAt,
       contentRevision,
+      compareContentRevisions,
       acknowledgedLocalSnapshot,
       onBaseAwareReconcile: (result) => {
         (captured.reconciled ??= []).push({
@@ -629,6 +632,50 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
     },
   );
 
+  it("does not replay sequential SQL acknowledgements over two-tab Yjs edits", async () => {
+    const harness = makeConnectedEditorHarness(false);
+    const baseline = "Alpha\n\nBravo";
+    const firstSave = "Alpha\n\nBravo from first tab";
+    const merged = "Second tab Alpha\n\nBravo from first tab";
+    vi.useFakeTimers();
+    try {
+      render(root, harness.Harness, {
+        value: baseline,
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        contentRevision: "revision-1",
+      });
+      await act(async () => vi.advanceTimersByTimeAsync(30));
+
+      act(() => harness.editors[0]!.commands.setContent(firstSave));
+      act(() => harness.editors[1]!.commands.setContent(merged));
+      expect(harness.markdown()).toEqual([merged, merged]);
+
+      render(root, harness.Harness, {
+        value: firstSave,
+        contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+        contentRevision: "revision-2",
+      });
+      await act(async () => vi.advanceTimersByTimeAsync(2501));
+      render(root, harness.Harness, {
+        value: merged,
+        contentUpdatedAt: "2024-01-01T00:00:03.000Z",
+        contentRevision: "revision-3",
+      });
+      await act(async () => vi.advanceTimersByTimeAsync(2501));
+
+      expect(harness.markdown()).toEqual([merged, merged]);
+      expect(harness.markdown()[0]!.match(/Second tab Alpha/g)).toHaveLength(1);
+      expect(
+        harness.markdown()[0]!.match(/Bravo from first tab/g),
+      ).toHaveLength(1);
+      expect(harness.reconciled).toEqual([
+        { status: "merged", content: merged },
+      ]);
+    } finally {
+      harness.dispose();
+    }
+  });
+
   it("uses the latest callback at the original peer deadline, including the default normalizer", async () => {
     const harness = makePeerReconcileHarness();
     vi.useFakeTimers();
@@ -1224,6 +1271,316 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
     ]);
   });
 
+  it("does not replace an external base with an acknowledgement at the same timestamp", async () => {
+    vi.useFakeTimers();
+    const { captured, Harness } = makeHarness();
+    const compareContentRevisions = (first: string, second: string) =>
+      Number(first.split("-")[1]) - Number(second.split("-")[1]);
+    render(root, Harness, {
+      value: "Alpha saved\n\nBravo\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      contentRevision: "revision-1",
+      compareContentRevisions,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    act(() =>
+      captured.editor!.commands.setContent(
+        "Alpha saved\n\nBravo\n\nCharlie local",
+      ),
+    );
+    render(root, Harness, {
+      value: "Alpha saved\n\nBravo server\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+      contentRevision: "revision-3",
+      compareContentRevisions,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha saved\n\nBravo server\n\nCharlie local",
+    );
+
+    const staleAcknowledgement = {
+      value: "Alpha saved\n\nBravo\n\nCharlie",
+      revision: "revision-2",
+      updatedAt: "2024-01-01T00:00:02.000Z",
+      sequence: 1,
+    };
+    render(root, Harness, {
+      value: staleAcknowledgement.value,
+      contentUpdatedAt: staleAcknowledgement.updatedAt,
+      contentRevision: staleAcknowledgement.revision,
+      compareContentRevisions,
+      acknowledgedLocalSnapshot: staleAcknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    render(root, Harness, {
+      value: "Alpha saved\n\nBravo remote\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:03.000Z",
+      contentRevision: "revision-4",
+      compareContentRevisions,
+      acknowledgedLocalSnapshot: staleAcknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha saved\n\nBravo remote\n\nCharlie local",
+    );
+    expect(captured.reconciled).toEqual([
+      {
+        status: "merged",
+        content: "Alpha saved\n\nBravo server\n\nCharlie local",
+      },
+      {
+        status: "merged",
+        content: "Alpha saved\n\nBravo remote\n\nCharlie local",
+      },
+    ]);
+  });
+
+  it("restores the prior base when an external revision follows an equal-timestamp acknowledgement", async () => {
+    vi.useFakeTimers();
+    const { captured, Harness } = makeHarness();
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      contentRevision: "revision-1",
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    act(() =>
+      captured.editor!.commands.setContent(
+        "Alpha local\n\nBravo\n\nCharlie local",
+      ),
+    );
+    const acknowledgement = {
+      value: "Alpha local\n\nBravo\n\nCharlie",
+      revision: "revision-2",
+      updatedAt: "2024-01-01T00:00:02.000Z",
+      sequence: 1,
+    };
+    render(root, Harness, {
+      value: acknowledgement.value,
+      contentUpdatedAt: acknowledgement.updatedAt,
+      contentRevision: acknowledgement.revision,
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha local\n\nBravo\n\nCharlie local",
+    );
+
+    render(root, Harness, {
+      value: "Alpha external\n\nBravo server\n\nCharlie",
+      contentUpdatedAt: acknowledgement.updatedAt,
+      contentRevision: "revision-3",
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha local\n\nBravo\n\nCharlie local",
+    );
+    expect(captured.reconciled).toEqual([
+      {
+        status: "conflict",
+        content: "Alpha local\n\nBravo\n\nCharlie local",
+      },
+    ]);
+  });
+
+  it("preserves the prior base when an acknowledgement precedes its canonical snapshot", async () => {
+    vi.useFakeTimers();
+    const { captured, Harness } = makeHarness();
+    const initial = {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      contentRevision: "revision-1",
+    };
+    render(root, Harness, initial);
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    act(() =>
+      captured.editor!.commands.setContent(
+        "Alpha local\n\nBravo\n\nCharlie local",
+      ),
+    );
+    const acknowledgement = {
+      value: "Alpha local\n\nBravo\n\nCharlie",
+      revision: "revision-2",
+      updatedAt: "2024-01-01T00:00:02.000Z",
+      sequence: 1,
+    };
+    render(root, Harness, {
+      ...initial,
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    render(root, Harness, {
+      value: "Alpha external\n\nBravo server\n\nCharlie",
+      contentUpdatedAt: acknowledgement.updatedAt,
+      contentRevision: "revision-3",
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha local\n\nBravo\n\nCharlie local",
+    );
+    expect(captured.reconciled).toEqual([
+      {
+        status: "conflict",
+        content: "Alpha local\n\nBravo\n\nCharlie local",
+      },
+    ]);
+  });
+
+  it("ignores a delayed different revision at an accepted timestamp", async () => {
+    vi.useFakeTimers();
+    const { captured, Harness } = makeHarness();
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      contentRevision: "revision-1",
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    act(() =>
+      captured.editor!.commands.setContent("Alpha\n\nBravo\n\nCharlie local"),
+    );
+    render(root, Harness, {
+      value: "Alpha\n\nBravo server\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+      contentRevision: "body:3:sha256:newest",
+      compareContentRevisions: (first, second) =>
+        Number(first.split(":")[1]) - Number(second.split(":")[1]),
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha\n\nBravo server\n\nCharlie local",
+    );
+
+    render(root, Harness, {
+      value: "Alpha stale\n\nBravo\n\nCharlie",
+      contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+      contentRevision: "body:2:sha256:delayed",
+      compareContentRevisions: (first, second) =>
+        Number(first.split(":")[1]) - Number(second.split(":")[1]),
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha\n\nBravo server\n\nCharlie local",
+    );
+    expect(captured.reconciled).toEqual([
+      {
+        status: "merged",
+        content: "Alpha\n\nBravo server\n\nCharlie local",
+      },
+    ]);
+  });
+
+  it("accepts a newer acknowledgement at an observed timestamp as the merge base", async () => {
+    vi.useFakeTimers();
+    const { captured, Harness } = makeHarness();
+    const compareContentRevisions = (first: string, second: string) =>
+      Number(first.split(":")[1]) - Number(second.split(":")[1]);
+    const timestamp = "2024-01-01T00:00:02.000Z";
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: timestamp,
+      contentRevision: "body:1:sha256:initial",
+      compareContentRevisions,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    act(() =>
+      captured.editor!.commands.setContent(
+        "Alpha local\n\nBravo\n\nCharlie local",
+      ),
+    );
+    const acknowledgement = {
+      value: "Alpha local\n\nBravo\n\nCharlie",
+      revision: "body:2:sha256:acknowledged",
+      updatedAt: timestamp,
+      sequence: 1,
+    };
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: timestamp,
+      contentRevision: "body:1:sha256:initial",
+      compareContentRevisions,
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    render(root, Harness, {
+      value: "Alpha external\n\nBravo server\n\nCharlie",
+      contentUpdatedAt: timestamp,
+      contentRevision: "body:3:sha256:external",
+      compareContentRevisions,
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha external\n\nBravo server\n\nCharlie local",
+    );
+    expect(captured.reconciled?.at(-1)).toEqual({
+      status: "merged",
+      content: "Alpha external\n\nBravo server\n\nCharlie local",
+    });
+  });
+
+  it("accepts an opaque acknowledgement at an observed timestamp as the merge base", async () => {
+    vi.useFakeTimers();
+    const { captured, Harness } = makeHarness();
+    const timestamp = "2024-01-01T00:00:02.000Z";
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: timestamp,
+      contentRevision: "initial",
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    act(() =>
+      captured.editor!.commands.setContent(
+        "Alpha local\n\nBravo\n\nCharlie local",
+      ),
+    );
+    const acknowledgement = {
+      value: "Alpha local\n\nBravo\n\nCharlie",
+      revision: "acknowledged",
+      updatedAt: timestamp,
+      sequence: 1,
+    };
+    render(root, Harness, {
+      value: "Alpha\n\nBravo\n\nCharlie",
+      contentUpdatedAt: timestamp,
+      contentRevision: "initial",
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    render(root, Harness, {
+      value: "Alpha external\n\nBravo server\n\nCharlie",
+      contentUpdatedAt: timestamp,
+      contentRevision: "external",
+      acknowledgedLocalSnapshot: acknowledgement,
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(0));
+
+    expect(getEditorMarkdown(captured.editor!)).toBe(
+      "Alpha external\n\nBravo server\n\nCharlie local",
+    );
+    expect(captured.reconciled?.at(-1)).toEqual({
+      status: "merged",
+      content: "Alpha external\n\nBravo server\n\nCharlie local",
+    });
+  });
+
   it("persists the first local edit after a synced empty collaborative document", async () => {
     const captured: Captured = {
       editor: null,

package/src/editor/useCollabReconcile.ts

@@ -63,6 +63,12 @@ export interface UseCollabReconcileOptions {
   contentUpdatedAt?: string | null;
   /** Opaque authoritative body revision. Enables base-aware reconciliation. */
   contentRevision?: string | null;
+  /**
+   * Orders two revision identities when their timestamps tie. Return a positive
+   * number when the first revision is newer, zero when equivalent, a negative
+   * number when older, or null when this revision format cannot be ordered.
+   */
+  compareContentRevisions?: (first: string, second: string) => number | null;
   /**
    * A server-confirmed snapshot written by this editor. This is deliberately
    * separate from `registerEmitted`: an emitted value may still fail to save,
@@ -263,6 +269,7 @@ export function useCollabReconcile({
   value,
   contentUpdatedAt,
   contentRevision,
+  compareContentRevisions,
   acknowledgedLocalSnapshot,
   collabContentRevision,
   requestCollabSync,
@@ -323,6 +330,14 @@ export function useCollabReconcile({
   const latestObservedUpdatedAtRef = useRef<string | null>(
     contentUpdatedAt ?? null,
   );
+  const latestObservedRevisionRef = useRef<string | null>(
+    contentRevision ?? null,
+  );
+  const acknowledgementBaseRollbackRef = useRef<{
+    acknowledgementRevision: string;
+    updatedAt: string;
+    base: { value: string; revision: string } | null;
+  } | null>(null);
   const acknowledgedCollabRef = useRef<{ ydoc: YDoc; revision: string } | null>(
     null,
   );
@@ -616,28 +631,115 @@ export function useCollabReconcile({
     // change isn't inserted twice (Yjs + setContent → duplicated region).
     const apply = (deferred = false) => {
       if (cancelled || editor.isDestroyed) return;
-      if (
-        contentUpdatedAt &&
-        (!latestObservedUpdatedAtRef.current ||
-          contentUpdatedAt > latestObservedUpdatedAtRef.current)
-      ) {
-        latestObservedUpdatedAtRef.current = contentUpdatedAt;
+      if (contentUpdatedAt) {
+        const rollback = acknowledgementBaseRollbackRef.current;
+        const conflictsWithAcceptedAcknowledgement =
+          contentRevision &&
+          rollback?.updatedAt === contentUpdatedAt &&
+          rollback.acknowledgementRevision !== contentRevision;
+        if (conflictsWithAcceptedAcknowledgement) {
+          const order = compareContentRevisions?.(
+            contentRevision,
+            rollback.acknowledgementRevision,
+          );
+          if (order !== undefined && order !== null && order <= 0) {
+            return;
+          }
+          // The acknowledgement advanced our base before its SQL snapshot was
+          // observed, but another revision won at the same timestamp. Restore
+          // the common base and treat this first canonical winner as the
+          // authoritative revision for that otherwise unordered timestamp.
+          if (
+            authoritativeBaseRef.current?.revision ===
+            rollback.acknowledgementRevision
+          ) {
+            authoritativeBaseRef.current = rollback.base;
+          }
+          acknowledgementBaseRollbackRef.current = null;
+          latestObservedUpdatedAtRef.current = contentUpdatedAt;
+          latestObservedRevisionRef.current = contentRevision;
+        } else if (
+          !latestObservedUpdatedAtRef.current ||
+          contentUpdatedAt > latestObservedUpdatedAtRef.current
+        ) {
+          latestObservedUpdatedAtRef.current = contentUpdatedAt;
+          latestObservedRevisionRef.current = contentRevision ?? null;
+          acknowledgementBaseRollbackRef.current = null;
+        } else if (
+          contentUpdatedAt === latestObservedUpdatedAtRef.current &&
+          contentRevision &&
+          latestObservedRevisionRef.current !== contentRevision
+        ) {
+          const order = latestObservedRevisionRef.current
+            ? compareContentRevisions?.(
+                contentRevision,
+                latestObservedRevisionRef.current,
+              )
+            : null;
+          if (order !== undefined && order !== null && order <= 0) {
+            return;
+          }
+          // Legacy opaque revisions cannot be ordered. Preserve their existing
+          // reconcile behavior; ordered body revisions retain the newest
+          // identity so a delayed snapshot cannot roll it back.
+          latestObservedRevisionRef.current =
+            order !== undefined && order !== null ? contentRevision : null;
+        }
       }
+      let rejectedMatchingAcknowledgement = false;
       if (acknowledgedLocalSnapshot) {
         const acceptedAcknowledgement = acknowledgedLocalSnapshotRef.current;
         const acknowledgementIsNewestAccepted =
           !acceptedAcknowledgement ||
           acknowledgedLocalSnapshot.sequence > acceptedAcknowledgement.sequence;
+        const acknowledgementRevisionOrder =
+          acknowledgedLocalSnapshot.updatedAt ===
+            latestObservedUpdatedAtRef.current &&
+          latestObservedRevisionRef.current
+            ? compareContentRevisions?.(
+                acknowledgedLocalSnapshot.revision,
+                latestObservedRevisionRef.current,
+              )
+            : null;
         const acknowledgementIsNotSuperseded =
           !latestObservedUpdatedAtRef.current ||
-          acknowledgedLocalSnapshot.updatedAt >=
-            latestObservedUpdatedAtRef.current;
+          acknowledgedLocalSnapshot.updatedAt >
+            latestObservedUpdatedAtRef.current ||
+          (acknowledgedLocalSnapshot.updatedAt ===
+            latestObservedUpdatedAtRef.current &&
+            (latestObservedRevisionRef.current ===
+              acknowledgedLocalSnapshot.revision ||
+              acknowledgementRevisionOrder === undefined ||
+              acknowledgementRevisionOrder === null ||
+              acknowledgementRevisionOrder >= 0));
         if (acknowledgementIsNewestAccepted && acknowledgementIsNotSuperseded) {
           acknowledgedLocalSnapshotRef.current = acknowledgedLocalSnapshot;
+          const existingRollback = acknowledgementBaseRollbackRef.current;
+          if (
+            existingRollback?.acknowledgementRevision !==
+              acknowledgedLocalSnapshot.revision ||
+            existingRollback.updatedAt !== acknowledgedLocalSnapshot.updatedAt
+          ) {
+            acknowledgementBaseRollbackRef.current = {
+              acknowledgementRevision: acknowledgedLocalSnapshot.revision,
+              updatedAt: acknowledgedLocalSnapshot.updatedAt,
+              base: authoritativeBaseRef.current,
+            };
+          }
           authoritativeBaseRef.current = {
             value: acknowledgedLocalSnapshot.value,
             revision: acknowledgedLocalSnapshot.revision,
           };
+          if (
+            acknowledgedLocalSnapshot.updatedAt ===
+              latestObservedUpdatedAtRef.current &&
+            acknowledgementRevisionOrder !== undefined &&
+            acknowledgementRevisionOrder !== null &&
+            acknowledgementRevisionOrder > 0
+          ) {
+            latestObservedRevisionRef.current =
+              acknowledgedLocalSnapshot.revision;
+          }
           if (
             !lastAppliedUpdatedAtRef.current ||
             acknowledgedLocalSnapshot.updatedAt >
@@ -646,8 +748,14 @@ export function useCollabReconcile({
             lastAppliedUpdatedAtRef.current =
               acknowledgedLocalSnapshot.updatedAt;
           }
+        } else if (
+          contentRevision === acknowledgedLocalSnapshot.revision &&
+          value === acknowledgedLocalSnapshot.value
+        ) {
+          rejectedMatchingAcknowledgement = true;
         }
       }
+      if (rejectedMatchingAcknowledgement) return;
       const acknowledged = acknowledgedLocalSnapshotRef.current;
       if (
         acknowledged &&
@@ -656,7 +764,9 @@ export function useCollabReconcile({
       ) {
         const acknowledgementWasSuperseded =
           latestObservedUpdatedAtRef.current !== null &&
-          acknowledged.updatedAt < latestObservedUpdatedAtRef.current;
+          (acknowledged.updatedAt < latestObservedUpdatedAtRef.current ||
+            (acknowledged.updatedAt === latestObservedUpdatedAtRef.current &&
+              latestObservedRevisionRef.current !== acknowledged.revision));
         if (!acknowledgementWasSuperseded) {
           authoritativeBaseRef.current = {
             value: acknowledged.value,
@@ -990,6 +1100,7 @@ export function useCollabReconcile({
   }, [
     contentUpdatedAt,
     contentRevision,
+    compareContentRevisions,
     acknowledgedLocalSnapshot,
     editor,
     ydoc,

package/src/provider.tsx

@@ -65,6 +65,7 @@ export function ToolkitProvider({
       children,
       intent,
       emphasis,
+      inset,
       size,
       pending,
       leadingIcon,
@@ -75,15 +76,17 @@ export function ToolkitProvider({
       ...props
     }: ActionButtonProps) {
       const variant =
-        emphasis === "ghost"
-          ? "ghost"
-          : emphasis === "outline"
-            ? "outline"
-            : intent === "danger"
-              ? "destructive"
-              : intent === "primary"
-                ? "default"
-                : "secondary";
+        inset && emphasis === "ghost"
+          ? "ghost-inset"
+          : emphasis === "ghost"
+            ? "ghost"
+            : emphasis === "outline"
+              ? "outline"
+              : intent === "danger"
+                ? "destructive"
+                : intent === "primary"
+                  ? "default"
+                  : "secondary";
       const legacySize =
         size === "compact" ? "sm" : size === "large" ? "lg" : "default";
       return (

package/src/ui/button.tsx

@@ -14,6 +14,8 @@ import type {
 import { useToolkitComponent } from "../provider.js";
 import { cn } from "../utils.js";
 
+export type ButtonEmphasis = DesignSystemEmphasis | "ghost-inset";
+
 const buttonVariants = cva(
   "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-[color,background-color,border-color,box-shadow,transform,scale] duration-150 active:scale-[0.98] motion-reduce:active:scale-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
   {
@@ -26,6 +28,8 @@ const buttonVariants = cva(
         secondary:
           "bg-secondary text-secondary-foreground hover:bg-secondary/80",
         ghost: "hover:bg-accent hover:text-accent-foreground",
+        "ghost-inset":
+          "text-muted-foreground hover:bg-accent/40 hover:text-foreground focus-visible:ring-inset focus-visible:ring-offset-0",
         link: "text-primary underline-offset-4 hover:underline",
       },
       size: {
@@ -50,7 +54,7 @@ export interface ButtonProps
   /** Semantic meaning forwarded to a registered design-system ActionButton. */
   intent?: DesignSystemIntent;
   /** Semantic prominence forwarded independently of the default visual variant. */
-  emphasis?: DesignSystemEmphasis;
+  emphasis?: ButtonEmphasis;
 }
 
 const ButtonBase = React.forwardRef<HTMLButtonElement, ButtonProps>(
@@ -104,13 +108,21 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
           : variant === "default"
             ? "primary"
             : "neutral");
-      const semanticEmphasis =
-        emphasis ??
-        (variant === "outline"
-          ? "outline"
-          : variant === "ghost" || variant === "link"
-            ? "ghost"
-            : "solid");
+      const semanticEmphasis: DesignSystemEmphasis =
+        emphasis === "ghost-inset"
+          ? "ghost"
+          : (emphasis ??
+            (variant === "outline"
+              ? "outline"
+              : variant === "ghost-inset"
+                ? "ghost"
+                : variant === "ghost" || variant === "link"
+                  ? "ghost"
+                  : "solid"));
+      const inset =
+        semanticEmphasis === "ghost" &&
+        (emphasis === "ghost-inset" ||
+          (!emphasis && variant === "ghost-inset"));
       const semanticSize =
         size === "sm" ? "compact" : size === "lg" ? "large" : "default";
       return (
@@ -128,6 +140,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
             disabled={props.disabled}
             intent={semanticIntent}
             emphasis={semanticEmphasis}
+            inset={inset || undefined}
             size={semanticSize}
             onPress={(event) =>
               props.onClick?.(