@stigmer/react 3.0.9-dev.20260615153829 → 3.1.0

package/src/internal/BoundedContent.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import { useIsOverflowing } from "./useIsOverflowing";
+import { RevealToggle } from "./RevealToggle";
+
+/**
+ * The single shared height budget for a bounded tool-card block. Tall enough
+ * to show a screenshot or a handful of diff lines at a glance, short enough
+ * that a turn of several cards still scans as a timeline rather than a wall.
+ * One constant so the settled edit/write diff and the HITL approval gate diff
+ * are visually identical — change it here to retune both at once.
+ */
+export const PREVIEW_MAX_HEIGHT = "max-h-48";
+
+/** Props for {@link BoundedContent}. */
+export interface BoundedContentProps {
+  /** The content to bound — a diff (the only consumer today). */
+  readonly children: ReactNode;
+  /**
+   * Tailwind `max-h-*` clamp applied while collapsed. Defaults to the shared
+   * {@link PREVIEW_MAX_HEIGHT} budget; override only with deliberate reason.
+   */
+  readonly maxHeightClass?: string;
+  /** Stable hook for e2e/visual targeting on the reveal control. */
+  readonly cursorTarget?: string;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Bounds a visual block to one shared height budget with a bottom fade and an
+ * in-place {@link RevealToggle} — the "clamp + fade + Show more" shape used by
+ * the settled edit/write diff and the approval gate diff.
+ *
+ * This is the **pixel-clamp** truncation mechanism, for content that has no
+ * internal cap of its own (a diff table). Text and terminal output instead use
+ * the **line-count** mechanism ({@link CollapsiblePre} / {@link
+ * CollapsibleCode}); both render the same {@link RevealToggle}, so the two
+ * mechanisms share one visual language without ever double-bounding the same
+ * block. Never wrap content that already self-truncates in this.
+ *
+ * The control and fade appear only when {@link useIsOverflowing} reports the
+ * content is actually clipped (or the user expanded it). The fade uses
+ * `from-background`, matching every surface that consumes this today; a surface
+ * on a different token must supply its own fade.
+ *
+ * @internal Not part of the public API.
+ *
+ * @example
+ * ```tsx
+ * <BoundedContent><FileChangeDiff change={change} /></BoundedContent>
+ * ```
+ */
+export function BoundedContent({
+  children,
+  maxHeightClass = PREVIEW_MAX_HEIGHT,
+  cursorTarget,
+  className,
+}: BoundedContentProps) {
+  const [expanded, setExpanded] = useState(false);
+
+  // The clamp is applied while collapsed; measurement is only meaningful then.
+  const clamped = !expanded;
+  const { ref, isOverflowing } = useIsOverflowing<HTMLDivElement>(clamped);
+
+  // The control appears only when there is something hidden — either the
+  // content overflows now, or it was expanded (so "Show less" stays reachable).
+  const showControl = isOverflowing || expanded;
+  const showFade = clamped && isOverflowing;
+
+  return (
+    <div className={className}>
+      <div
+        ref={ref}
+        className={cn("relative overflow-hidden", clamped && maxHeightClass)}
+      >
+        {children}
+        {showFade && (
+          <div
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-x-0 bottom-0 h-8 bg-gradient-to-t from-background to-transparent"
+          />
+        )}
+      </div>
+      {showControl && (
+        <RevealToggle
+          expanded={expanded}
+          onToggle={() => setExpanded((v) => !v)}
+          cursorTarget={cursorTarget}
+        />
+      )}
+    </div>
+  );
+}

package/src/internal/DecisionButton.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** The visual weight of a {@link DecisionButton}. */
+export type DecisionVariant = "primary" | "ghost" | "danger";
+
+/** Props for {@link DecisionButton}. */
+export interface DecisionButtonProps {
+  /** Visible button text; also used as the accessible name. */
+  readonly label: string;
+  /**
+   * Visual weight. `primary` is the quiet neutral chip (the single recommended
+   * action), `ghost` is the lowest-weight neutral action, and `danger` is a
+   * ghost that reveals a destructive cue on hover/focus.
+   */
+  readonly variant: DecisionVariant;
+  /** Invoked on click. */
+  readonly onClick: () => void;
+  /** True while ANY decision RPC is in flight — disables every button. */
+  readonly isSubmitting?: boolean;
+  /** True when THIS button's RPC is the one in flight — shows the spinner. */
+  readonly isActive?: boolean;
+  /**
+   * Disables the button independent of {@link isSubmitting} — e.g. an action that
+   * is structurally unavailable (approving an incomplete, unreviewable diff).
+   */
+  readonly disabled?: boolean;
+  /** Extra classes (e.g. `ml-auto` to visually separate a demoted action). */
+  readonly className?: string;
+  /** Stable hook for e2e/visual targeting (`data-cursor-target`). */
+  readonly cursorTarget?: string;
+  /**
+   * Id of an element that explains this button — wired to `aria-describedby` so a
+   * disabled, structurally-unavailable action (e.g. approving an unreviewable
+   * change) is associated with the notice stating why.
+   */
+  readonly ariaDescribedby?: string;
+}
+
+const BASE = cn(
+  "inline-flex items-center justify-center gap-1.5 rounded-md px-3 py-1.5",
+  "text-xs font-medium transition-colors",
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+  // Disabled dimming is ELEMENT opacity (allowed), never a `bg-token/NN` opacity
+  // modifier — each preset keeps full control of the token colors themselves.
+  "disabled:cursor-not-allowed disabled:opacity-50 disabled:pointer-events-none",
+);
+
+// Quiet, Cursor-grade, token-only.
+const VARIANT: Record<DecisionVariant, string> = {
+  // Neutral chip: the single primary action. It reads as primary by fill-weight
+  // and border against the ghost actions — NOT by hue — so the hierarchy holds
+  // without color being the only channel (a11y).
+  primary:
+    "border border-border bg-accent text-accent-foreground hover:bg-accent-hover",
+  // The canonical SDK ghost: no fill at rest, neutral wash on hover.
+  ghost: "text-muted-foreground hover:text-foreground hover:bg-accent-hover",
+  // Quiet at rest; the destructive cue is revealed on hover AND keyboard focus
+  // (parity for keyboard users — not hover-only). A persistent red button is
+  // unnecessary: rejecting is the safe action, and a destructive tool gate is
+  // already flagged by the card's accent.
+  danger: cn(
+    "text-muted-foreground",
+    "hover:bg-destructive-subtle hover:text-destructive",
+    "focus-visible:bg-destructive-subtle focus-visible:text-destructive",
+  ),
+};
+
+/**
+ * The shared decision-action button for every approval surface — the agent
+ * tool gate ({@link ApprovalCard}) and the two workflow approval cards
+ * ({@link WorkflowTaskApprovalCard}, {@link WorkflowExecutionApprovalCard}).
+ *
+ * One source of truth for the quiet, Cursor-grade button system so the three
+ * surfaces can never visually drift, and so the spinner and base chrome live in
+ * exactly one place. Every visual property flows through `--stgm-*` tokens.
+ *
+ * @internal Not part of the public API.
+ */
+export function DecisionButton({
+  label,
+  variant,
+  onClick,
+  isSubmitting = false,
+  isActive = false,
+  disabled = false,
+  className,
+  cursorTarget,
+  ariaDescribedby,
+}: DecisionButtonProps) {
+  return (
+    <button
+      type="button"
+      disabled={isSubmitting || disabled}
+      onClick={onClick}
+      aria-label={label}
+      aria-describedby={ariaDescribedby}
+      data-cursor-target={cursorTarget}
+      className={cn(BASE, VARIANT[variant], className)}
+    >
+      {isActive && isSubmitting ? <SpinnerIcon /> : null}
+      {label}
+    </button>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icon
+// ---------------------------------------------------------------------------
+
+function SpinnerIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      className="animate-spin"
+      aria-hidden="true"
+    >
+      <path d="M6 1.5A4.5 4.5 0 1 1 1.5 6" strokeLinecap="round" />
+    </svg>
+  );
+}

package/src/internal/InCardDecisionError.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+/** Props for {@link InCardDecisionError}. */
+export interface InCardDecisionErrorProps {
+  /** The failure to surface. Its `message` is shown verbatim (the actionable part). */
+  readonly error: Error;
+  /**
+   * The verb phrase completing "Couldn't ___" — e.g. `"submit decision"` or
+   * `"save"`. Kept short; the server `message` carries the detail.
+   */
+  readonly leadIn: string;
+  /** Stable hook for e2e/visual targeting (`data-cursor-target`). */
+  readonly cursorTarget: string;
+}
+
+/**
+ * The shared in-card failure notice for a decision that did not take — used by
+ * every decision surface that surfaces errors beside the control that failed:
+ * the agent tool gate ({@link ApprovalCard}/{@link ApprovalCardBody}) and the
+ * file-review card ({@link FileReviewCard}, whole-set and per-file).
+ *
+ * One source of truth so those surfaces can never drift in tone, copy shape, or
+ * accessibility. `role="alert"` (matching the thread's other inline failures)
+ * announces it the moment it appears, since it is a dynamic reaction to the
+ * reviewer's action — by the time it renders the optimistic verdict has already
+ * reverted, and this explains why. The server `message` is shown verbatim
+ * because it is the actionable part (e.g. a digest mismatch means the captured
+ * content moved on); the lead-in stays short. Every visual property flows
+ * through `--stgm-*` tokens.
+ *
+ * @internal Not part of the public API.
+ */
+export function InCardDecisionError({
+  error,
+  leadIn,
+  cursorTarget,
+}: InCardDecisionErrorProps) {
+  return (
+    <p
+      role="alert"
+      className="text-[11px] text-destructive"
+      data-cursor-target={cursorTarget}
+    >
+      Couldn&rsquo;t {leadIn} — {error.message}
+    </p>
+  );
+}

package/src/internal/RevealToggle.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link RevealToggle}. */
+export interface RevealToggleProps {
+  /** Whether the governed content is currently fully revealed. */
+  readonly expanded: boolean;
+  /** Flips the reveal state. */
+  readonly onToggle: () => void;
+  /** Label shown while collapsed. Defaults to `"Show more"`. */
+  readonly moreLabel?: string;
+  /** Label shown while expanded. Defaults to `"Show less"`. */
+  readonly lessLabel?: string;
+  /** Stable hook for e2e/visual targeting (`data-cursor-target`). */
+  readonly cursorTarget?: string;
+  /** Additional CSS class names for the control. */
+  readonly className?: string;
+}
+
+/**
+ * The single "reveal more / less" control for every bounded block on the
+ * execution surface — the diff/gate clamp ({@link BoundedContent}) and the
+ * line-count text/terminal blocks ({@link CollapsiblePre} / {@link
+ * CollapsibleCode}).
+ *
+ * It is the Cursor-style affordance the design calls for: a light, centered
+ * chevron at the bottom-middle (down to reveal, up to collapse) with a quiet
+ * label. Extracting it is what guarantees one disclosure *language* across two
+ * truncation *mechanisms* (pixel clamp for visual blocks, line count for text)
+ * — the surfaces can never visually drift because they render the same control.
+ *
+ * Presentational only: it owns no state. The caller holds the reveal state and
+ * passes `expanded` + `onToggle`. It carries `aria-expanded` for the block it
+ * governs; the owning tool-call row's header chevron (when present) carries the
+ * row-level disclosure, so the two axes never collide.
+ *
+ * @internal Not part of the public API.
+ */
+export function RevealToggle({
+  expanded,
+  onToggle,
+  moreLabel = "Show more",
+  lessLabel = "Show less",
+  cursorTarget,
+  className,
+}: RevealToggleProps) {
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-expanded={expanded}
+      data-cursor-target={cursorTarget}
+      className={cn(
+        "mt-1 flex w-full items-center justify-center gap-1 rounded py-0.5",
+        "text-xs font-medium text-muted-foreground transition-colors hover:text-foreground",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className,
+      )}
+    >
+      <span>{expanded ? lessLabel : moreLabel}</span>
+      <ChevronIcon expanded={expanded} />
+    </button>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icon
+// ---------------------------------------------------------------------------
+
+function ChevronIcon({ expanded }: { expanded: boolean }) {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 10 10"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={cn(
+        "shrink-0 transition-transform duration-150",
+        expanded && "rotate-180",
+      )}
+      aria-hidden="true"
+    >
+      <path d="M2.5 3.5L5 6.5L7.5 3.5" />
+    </svg>
+  );
+}

package/src/internal/VirtualizedThread.tsx

@@ -18,8 +18,11 @@ import {
 } from "../execution/MessageThread";
 import { FilePathContext, type FilePathContextValue } from "../execution/FilePathContext";
 import { SandboxContext, type SandboxContextValue } from "../execution/SandboxContext";
+import { ApprovalContext, type ApprovalContextValue } from "../execution/ApprovalContext";
+import { FileReviewContext, type FileReviewContextValue } from "../execution/FileReviewContext";
 import { DevProfiler, useDomNodeCount } from "./dev";
 import { JumpToLatestButton } from "./JumpToLatestButton";
+import { ApprovalPeekBar } from "./ApprovalPeekBar";
 import { ThreadItemWrapper } from "./ThreadItemWrapper";
 
 // ---------------------------------------------------------------------------
@@ -35,8 +38,12 @@ export interface VirtualizedThreadProps {
     comment?: string,
   ) => void;
   readonly submittingApprovalIds?: ReadonlySet<string>;
+  readonly approvalErrors?: ReadonlyMap<string, Error>;
   readonly filePathCtx: FilePathContextValue;
   readonly sandboxCtx: SandboxContextValue;
+  readonly approvalCtx: ApprovalContextValue;
+  readonly fileReviewCtx: FileReviewContextValue;
+  readonly unresolvedApprovalCount: number;
   readonly onBuildFromPlan?: () => void;
   readonly org?: string;
   readonly planActionsDisabled?: boolean;
@@ -98,8 +105,12 @@ export function VirtualizedThread({
   formatToolCallSummary,
   onApprovalSubmit,
   submittingApprovalIds,
+  approvalErrors,
   filePathCtx,
   sandboxCtx,
+  approvalCtx,
+  fileReviewCtx,
+  unresolvedApprovalCount,
   onBuildFromPlan,
   org,
   planActionsDisabled,
@@ -135,6 +146,7 @@ export function VirtualizedThread({
       formatToolCallSummary,
       onApprovalSubmit,
       submittingApprovalIds,
+      approvalErrors,
       onBuildFromPlan,
       org,
       planActionsDisabled,
@@ -142,13 +154,15 @@ export function VirtualizedThread({
       onRetryExecution,
       onEditMessage,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan, org, planActionsDisabled, onRetrySend, onRetryExecution, onEditMessage],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, org, planActionsDisabled, onRetrySend, onRetryExecution, onEditMessage],
   );
 
   return (
     <>
       <SandboxContext.Provider value={sandboxCtx}>
       <FilePathContext.Provider value={filePathCtx}>
+      <ApprovalContext.Provider value={approvalCtx}>
+      <FileReviewContext.Provider value={fileReviewCtx}>
       <DevProfiler id="MessageThread:virtualized">
         <Virtuoso
           ref={virtuosoRef}
@@ -174,9 +188,21 @@ export function VirtualizedThread({
           )}
         />
       </DevProfiler>
+      </FileReviewContext.Provider>
+      </ApprovalContext.Provider>
       </FilePathContext.Provider>
       </SandboxContext.Provider>
-      <JumpToLatestButton onClick={jumpToLatest} visible={!isAtBottom} />
+      {/* The peek bar takes the jump button's slot while approvals are pending,
+          so the two never overlap — a gate is the louder of the two signals. */}
+      <JumpToLatestButton
+        onClick={jumpToLatest}
+        visible={!isAtBottom && unresolvedApprovalCount === 0}
+      />
+      <ApprovalPeekBar
+        visible={!isAtBottom && unresolvedApprovalCount > 0}
+        count={unresolvedApprovalCount}
+        onClick={jumpToLatest}
+      />
     </>
   );
 }

package/src/internal/__tests__/ApprovalPeekBar.test.tsx

@@ -0,0 +1,34 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { ApprovalPeekBar } from "../ApprovalPeekBar";
+
+afterEach(cleanup);
+
+describe("ApprovalPeekBar", () => {
+  it("is interactive and labelled when visible", () => {
+    render(<ApprovalPeekBar visible count={1} onClick={() => {}} />);
+    const btn = screen.getByRole("button");
+    expect(btn.getAttribute("aria-hidden")).toBe("false");
+    expect(btn.getAttribute("tabindex")).toBe("0");
+    expect(screen.getByText("1 approval needed")).toBeTruthy();
+  });
+
+  it("is inert (mounted for transitions) when not visible", () => {
+    render(<ApprovalPeekBar visible={false} count={2} onClick={() => {}} />);
+    const btn = screen.getByRole("button", { hidden: true });
+    expect(btn.getAttribute("aria-hidden")).toBe("true");
+    expect(btn.getAttribute("tabindex")).toBe("-1");
+  });
+
+  it("pluralizes the count", () => {
+    render(<ApprovalPeekBar visible count={3} onClick={() => {}} />);
+    expect(screen.getByText("3 approvals needed")).toBeTruthy();
+  });
+
+  it("invokes onClick (jump-to-latest) when pressed", () => {
+    const onClick = vi.fn();
+    render(<ApprovalPeekBar visible count={1} onClick={onClick} />);
+    fireEvent.click(screen.getByRole("button"));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/internal/__tests__/BoundedContent.test.tsx

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+
+// happy-dom does not compute layout, so the real overflow measurement always
+// reports false there (scrollHeight === clientHeight === 0). We mock the hook so
+// the overflow-driven branches (fade + reveal control) are deterministically
+// testable here; the *rendered* clamp/fade is exercised against a real browser
+// in test/e2e/tests/interactive-approval/tool-card-ux.spec.ts.
+let mockOverflowing = false;
+vi.mock("../useIsOverflowing", () => ({
+  useIsOverflowing: () => ({ ref: { current: null }, isOverflowing: mockOverflowing }),
+}));
+
+const { BoundedContent, PREVIEW_MAX_HEIGHT } = await import("../BoundedContent");
+
+beforeEach(() => {
+  mockOverflowing = false;
+});
+afterEach(cleanup);
+
+/** The collapsed clamp element: `overflow-hidden` + the shared budget. */
+function clampEl(container: HTMLElement): Element | null {
+  return container.querySelector(`.overflow-hidden.${PREVIEW_MAX_HEIGHT}`);
+}
+
+describe("BoundedContent", () => {
+  it("renders its children", () => {
+    render(
+      <BoundedContent>
+        <p>diff body</p>
+      </BoundedContent>,
+    );
+    expect(screen.getByText("diff body")).toBeTruthy();
+  });
+
+  it("clamps the body to the single shared budget while collapsed", () => {
+    const { container } = render(
+      <BoundedContent>
+        <p>diff body</p>
+      </BoundedContent>,
+    );
+    expect(clampEl(container)).not.toBeNull();
+  });
+
+  it("shows no reveal control when the content fits the budget", () => {
+    mockOverflowing = false;
+    render(
+      <BoundedContent>
+        <p>short</p>
+      </BoundedContent>,
+    );
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("shows 'Show more' when the content overflows and expands it in place to 'Show less', dropping the clamp", () => {
+    mockOverflowing = true;
+    const { container } = render(
+      <BoundedContent>
+        <p>long body</p>
+      </BoundedContent>,
+    );
+
+    // Collapsed: clamped, with a "Show more" reveal that owns the disclosure.
+    const control = screen.getByRole("button", { name: /Show more/ });
+    expect(control.getAttribute("aria-expanded")).toBe("false");
+    expect(clampEl(container)).not.toBeNull();
+
+    // Expanding removes the clamp (natural height) and flips the control.
+    fireEvent.click(control);
+    expect(
+      screen.getByRole("button", { name: /Show less/ }).getAttribute("aria-expanded"),
+    ).toBe("true");
+    expect(clampEl(container)).toBeNull();
+
+    // Collapsing restores the clamp.
+    fireEvent.click(screen.getByRole("button", { name: /Show less/ }));
+    expect(screen.getByRole("button", { name: /Show more/ })).toBeTruthy();
+    expect(clampEl(container)).not.toBeNull();
+  });
+
+  it("forwards the e2e cursor-target hook onto the control", () => {
+    mockOverflowing = true;
+    render(
+      <BoundedContent cursorTarget="file-diff-expand">
+        <p>body</p>
+      </BoundedContent>,
+    );
+    expect(
+      screen.getByRole("button").getAttribute("data-cursor-target"),
+    ).toBe("file-diff-expand");
+  });
+});

package/src/internal/__tests__/DecisionButton.test.tsx

@@ -0,0 +1,107 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { DecisionButton } from "../DecisionButton";
+
+afterEach(cleanup);
+
+// happy-dom cannot resolve `@layer`/the cascade, so these assert the class
+// CONTRACT (the quiet, token-only treatment), not rendered pixels. The rendered
+// outcome is covered by the e2e computed-style guard in tool-card-ux.spec.ts.
+describe("DecisionButton", () => {
+  it("renders the label as the accessible name and invokes onClick", () => {
+    const onClick = vi.fn();
+    render(<DecisionButton label="Approve" variant="primary" onClick={onClick} />);
+    const btn = screen.getByRole("button", { name: "Approve" });
+    fireEvent.click(btn);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("primary is a neutral chip (bordered fill), never the loud success green", () => {
+    render(<DecisionButton label="Approve" variant="primary" onClick={() => {}} />);
+    const cls = screen.getByRole("button").className;
+    expect(cls).toContain("border");
+    expect(cls).toContain("bg-accent");
+    expect(cls).toContain("text-accent-foreground");
+    expect(cls).not.toContain("bg-success");
+  });
+
+  it("ghost carries no fill at rest (lowest weight)", () => {
+    render(<DecisionButton label="Skip" variant="ghost" onClick={() => {}} />);
+    const cls = screen.getByRole("button").className;
+    expect(cls).toContain("text-muted-foreground");
+    // No resting background — only a neutral hover wash.
+    expect(cls).not.toMatch(/(?:^|\s)bg-/);
+    expect(cls).toContain("hover:bg-accent-hover");
+  });
+
+  it("danger is a quiet ghost that reveals the destructive cue on hover AND focus, never the loud red fill", () => {
+    render(<DecisionButton label="Reject" variant="danger" onClick={() => {}} />);
+    const cls = screen.getByRole("button").className;
+    expect(cls).toContain("text-muted-foreground");
+    expect(cls).not.toMatch(/(?:^|\s)bg-/); // transparent at rest
+    expect(cls).toContain("hover:text-destructive");
+    expect(cls).toContain("hover:bg-destructive-subtle");
+    // Keyboard parity: the cue is not hover-only.
+    expect(cls).toContain("focus-visible:text-destructive");
+    expect(cls).not.toContain("bg-destructive text-destructive-foreground");
+  });
+
+  it("uses NO `bg-token/NN` opacity modifiers in any variant", () => {
+    for (const variant of ["primary", "ghost", "danger"] as const) {
+      const { unmount } = render(
+        <DecisionButton label="x" variant={variant} onClick={() => {}} />,
+      );
+      const cls = screen.getByRole("button").className;
+      // No utility ends in `/<digits>` (e.g. bg-success/90, hover:bg-destructive/10).
+      expect(cls).not.toMatch(/\/\d+(?:\s|$)/);
+      unmount();
+    }
+  });
+
+  it("disables every button while a submission is in flight", () => {
+    render(
+      <DecisionButton label="Approve" variant="primary" onClick={() => {}} isSubmitting />,
+    );
+    expect((screen.getByRole("button") as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it("shows the spinner only on the active button that is submitting", () => {
+    const { rerender } = render(
+      <DecisionButton
+        label="Approve"
+        variant="primary"
+        onClick={() => {}}
+        isSubmitting
+        isActive
+      />,
+    );
+    expect(screen.getByRole("button").querySelector("svg.animate-spin")).toBeTruthy();
+
+    // In-flight, but a DIFFERENT button is the active one — no spinner here.
+    rerender(
+      <DecisionButton
+        label="Approve"
+        variant="primary"
+        onClick={() => {}}
+        isSubmitting
+        isActive={false}
+      />,
+    );
+    expect(screen.getByRole("button").querySelector("svg.animate-spin")).toBeNull();
+  });
+
+  it("forwards className and the data-cursor-target hook", () => {
+    render(
+      <DecisionButton
+        label="Approve all"
+        variant="ghost"
+        onClick={() => {}}
+        className="ml-auto"
+        cursorTarget="approve-all-button"
+      />,
+    );
+    const btn = screen.getByRole("button");
+    expect(btn.className).toContain("ml-auto");
+    expect(btn.getAttribute("data-cursor-target")).toBe("approve-all-button");
+  });
+});