@stigmer/react 3.12.0 → 3.12.2

package/src/index.ts

@@ -1,5 +1,6 @@
 // Provider and context
 export { StigmerProvider, type StigmerProviderProps } from "./provider.js";
+export { type ApprovalDefaults } from "./approval-defaults-context.js";
 export { StigmerContext } from "./context.js";
 
 // Runner adapter
@@ -39,7 +40,9 @@ export {
   modelKey,
   parseModelKey,
   fetchModelRegistry,
+  fetchModelRegistryDocument,
   parseRegistryJson,
+  parseRegistryDocument,
   useModelRegistry,
   ModelRegistryContext,
   ModelSelector,
@@ -51,6 +54,7 @@ export {
 } from "./models/index.js";
 export type {
   ModelInfo,
+  ModelRegistryDocument,
   ModelRegistryState,
   ParsedModelKey,
   Provider,
@@ -60,6 +64,7 @@ export type {
   ModelSelectorProps,
   HarnessSelectorProps,
   HarnessOption,
+  VisionLimits,
 } from "./models/index.js";
 
 // Workspace — behavior hooks and styled components
@@ -215,6 +220,7 @@ export type {
   ExecutionTargetOption,
   RuntimeEnvProvider,
   SessionAudience,
+  SessionPanelMode,
   SetupTabProps,
   SetupTabMutationCallbacks,
 } from "./session/index.js";
@@ -257,6 +263,7 @@ export {
   ExecutionPhaseBadge,
   InteractionModeBadge,
   SetupProgress,
+  LivenessStatusLine,
   ExecutionProgress,
   TodoList,
   TodoCard,
@@ -279,6 +286,7 @@ export {
   ResultView,
   summarizeResultView,
   TerminalSession,
+  TerminalTail,
   useToolPresentation,
   registerToolPresenter,
   getToolPresenter,
@@ -296,6 +304,7 @@ export {
   SubAgentSection,
   MessageEntry,
   MessageThread,
+  ExecutionErrorNotice,
   ThreadSkeleton,
   FollowUpInput,
   ApprovalCard,
@@ -380,6 +389,7 @@ export type {
   ExecutionPhaseBadgeProps,
   InteractionModeBadgeProps,
   SetupProgressProps,
+  LivenessStatusLineProps,
   ExecutionProgressProps,
   TodoListProps,
   TodoCardProps,
@@ -398,6 +408,7 @@ export type {
   ToolCallDetailProps,
   ResultViewProps,
   TerminalSessionProps,
+  TerminalTailProps,
   ToolPresentation,
   ToolPresenter,
   ToolDisclosure,
@@ -409,6 +420,8 @@ export type {
   SubAgentSectionProps,
   MessageEntryProps,
   MessageThreadProps,
+  MessageThreadSlots,
+  ExecutionErrorNoticeProps,
   ThreadContentColumn,
   ThreadSkeletonProps,
   FollowUpInputProps,
@@ -466,13 +479,14 @@ export type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agent
 export { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 // Attachment — file upload behavior hook, styled chip list, clipboard paste,
-// and vision-resolution image preparation
+// vision-resolution image preparation, and vision preflight warnings
 export {
   useAttachments,
   AttachmentChipList,
   MAX_ATTACHMENT_BYTES,
   MAX_VISION_LONG_EDGE_PX,
   MAX_VISION_PIXELS,
+  assessVisionPreflight,
   detectContentType,
   exceedsVisionResolution,
   extractClipboardFiles,
@@ -481,15 +495,22 @@ export {
   prepareImageForVision,
   uniquifyFilename,
   validateAttachmentSize,
+  visionPreflightMessage,
 } from "./attachment/index.js";
 export type {
   AttachmentPhase,
   AttachmentEntry,
+  AssessVisionPreflightOptions,
   ClipboardFilesSource,
   UseAttachmentsOptions,
   UseAttachmentsReturn,
   AttachmentChipListProps,
   VisionFitSize,
+  VisionPreflight,
+  VisionPreflightAttachment,
+  VisionPreflightMessageOptions,
+  VisionPreflightReason,
+  VisionPreflightWarning,
 } from "./attachment/index.js";
 
 // File Reference — workspace file-reference behavior hook and styled chip list
@@ -1868,6 +1889,7 @@ export type {
   WorkflowTaskListProps,
   WorkflowDetailViewProps,
   WorkflowExecutionViewerProps,
+  WorkflowExecutionPanelMode,
   WorkflowExecutionHeaderProps,
   WorkflowExecutionPanelController,
   UseWorkflowExecutionPanelOptions,

package/src/internal/DecisionButton.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { cn } from "@stigmer/theme";
+import { SpinnerIcon } from "../internal/thread-card/glyphs.js";
 
 /** The visual weight of a {@link DecisionButton}. */
 export type DecisionVariant = "primary" | "ghost" | "danger";
@@ -106,23 +107,3 @@ export function DecisionButton({
   );
 }
 
-// ---------------------------------------------------------------------------
-// Inline SVG icon
-// ---------------------------------------------------------------------------
-
-function SpinnerIcon() {
-  return (
-    <svg
-      width="10"
-      height="10"
-      viewBox="0 0 12 12"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="1.5"
-      className="stg: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/SpinnerIcon.tsx

@@ -0,0 +1,42 @@
+import { cn } from "@stigmer/theme";
+
+/**
+ * The SDK's canonical in-flight spinner: a three-quarter arc on a 16×16
+ * grid, colored by `currentColor` so the consumer's text token drives it
+ * (never hardcoded values — Dont-Do #3). Extracted from ~33 identical
+ * per-component copies (stigmer-cloud#270); new busy states import this
+ * instead of pasting another one.
+ *
+ * `size` is the rendered box; the glyph scales from the same viewBox, so
+ * every size renders the identical shape. Decorative by contract
+ * (`aria-hidden`) — pair it with visible or `sr-only` text when the busy
+ * state itself must be announced.
+ *
+ * The thread-card rows deliberately use a finer quarter-arc micro-glyph
+ * instead — see `internal/thread-card/glyphs.tsx`.
+ *
+ * @internal Not part of the public API.
+ */
+export function SpinnerIcon({
+  size = 16,
+  className,
+}: {
+  readonly size?: number;
+  readonly className?: string;
+} = {}) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      className={cn("stg:animate-spin", className)}
+      aria-hidden="true"
+    >
+      <path d="M8 2a6 6 0 1 0 6 6" />
+    </svg>
+  );
+}

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

@@ -1,9 +1,9 @@
 // Contract tests for the shared thread-card shell (T05/T06): the chrome
-// axes (bordered vs divider row, gate accent), the header gestures
-// (`expand` / `none` — `select` died with the Inspect drill-down, T06)
-// with their ARIA semantics, and the nested-button keydown guard. The two
-// consuming threads pin their own compositions; this file pins what they
-// share.
+// tiers (card / nested divider row / quiet unboxed line, gate accent), the
+// header gestures (`expand` / `none` — `select` died with the Inspect
+// drill-down, T06) with their ARIA semantics, and the nested-button keydown
+// guard. The two consuming threads pin their own compositions; this file
+// pins what they share.
 
 import { describe, it, expect, vi, afterEach } from "vitest";
 import { render, screen, fireEvent, cleanup } from "@testing-library/react";
@@ -16,7 +16,7 @@ import {
 afterEach(cleanup);
 
 describe("ThreadCardShell chrome", () => {
-  it("renders a bordered card by default and a divider row when nested", () => {
+  it("renders a bordered card by default, a divider row when nested, and no chrome when quiet", () => {
     const { rerender, container } = render(
       <ThreadCardShell cursorTarget="row">
         <ThreadCardHeader>content</ThreadCardHeader>
@@ -27,12 +27,22 @@ describe("ThreadCardShell chrome", () => {
     expect(root().className).toContain("stg:border-border-prominent");
 
     rerender(
-      <ThreadCardShell cursorTarget="row" bordered={false}>
+      <ThreadCardShell cursorTarget="row" variant="row">
         <ThreadCardHeader>content</ThreadCardHeader>
       </ThreadCardShell>,
     );
     expect(root().className).toContain("stg:border-b");
     expect(root().className).not.toContain("stg:border-border-prominent");
+
+    rerender(
+      <ThreadCardShell cursorTarget="row" variant="quiet">
+        <ThreadCardHeader>content</ThreadCardHeader>
+      </ThreadCardShell>,
+    );
+    // The quiet tier is an unboxed line: no card border, no divider.
+    expect(root().className).not.toContain("stg:border-border-prominent");
+    expect(root().className).not.toContain("stg:border-b");
+    expect(root().className).not.toContain("stg:rounded-lg");
   });
 
   it("carries the gate accent", () => {
@@ -44,6 +54,19 @@ describe("ThreadCardShell chrome", () => {
     const root = container.querySelector('[data-cursor-target="row"]') as HTMLElement;
     expect(root.className).toContain("stg:border-l-warning");
   });
+
+  it("never draws the gate accent on a quiet shell — escalation is the caller's job", () => {
+    // The quiet tier deliberately ignores `accent`: a gated row must be
+    // escalated to variant="card" by its component, never rendered as an
+    // accented bare line (see ThreadCardVariant).
+    const { container } = render(
+      <ThreadCardShell cursorTarget="row" variant="quiet" accent="warning">
+        <ThreadCardHeader>content</ThreadCardHeader>
+      </ThreadCardShell>,
+    );
+    const root = container.querySelector('[data-cursor-target="row"]') as HTMLElement;
+    expect(root.className).not.toContain("stg:border-l-warning");
+  });
 });
 
 describe("ThreadCardHeader gestures", () => {
@@ -102,4 +125,17 @@ describe("ThreadCardBody", () => {
     render(<ThreadCardBody id="detail-1">body</ThreadCardBody>);
     expect(document.getElementById("detail-1")?.textContent).toBe("body");
   });
+
+  it("swaps the card padding for a left rail when the body is quiet-contained", () => {
+    const { rerender } = render(<ThreadCardBody id="detail-1">body</ThreadCardBody>);
+    const el = () => document.getElementById("detail-1")!;
+    expect(el().className).not.toContain("stg:border-l-2");
+
+    rerender(
+      <ThreadCardBody id="detail-1" rail>
+        body
+      </ThreadCardBody>,
+    );
+    expect(el().className).toContain("stg:border-l-2");
+  });
 });

package/src/internal/__tests__/useCopyFeedback.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useCopyFeedback } from "../useCopyFeedback";
+
+describe("useCopyFeedback", () => {
+  let writeText: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    writeText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("resolves true and flashes `copied` for a successful write", async () => {
+    const { result } = renderHook(() => useCopyFeedback());
+
+    let outcome: boolean | undefined;
+    await act(async () => {
+      outcome = await result.current.copy("hello");
+    });
+
+    expect(outcome).toBe(true);
+    expect(writeText).toHaveBeenCalledWith("hello");
+    expect(result.current.copied).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("resolves false and never claims `copied` for a rejected write", async () => {
+    writeText.mockRejectedValue(new Error("denied"));
+    const { result } = renderHook(() => useCopyFeedback());
+
+    let outcome: boolean | undefined;
+    await act(async () => {
+      outcome = await result.current.copy("secret");
+    });
+
+    expect(outcome).toBe(false);
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("restarts the feedback window on a rapid second copy", async () => {
+    const { result } = renderHook(() => useCopyFeedback());
+
+    await act(async () => {
+      await result.current.copy("one");
+    });
+    act(() => {
+      vi.advanceTimersByTime(1500);
+    });
+    await act(async () => {
+      await result.current.copy("two");
+    });
+
+    // 1.5s into the second window: still showing feedback.
+    act(() => {
+      vi.advanceTimersByTime(1500);
+    });
+    expect(result.current.copied).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("does not set state after unmount when the timer would fire", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { result, unmount } = renderHook(() => useCopyFeedback());
+
+    await act(async () => {
+      await result.current.copy("bye");
+    });
+    unmount();
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+
+    // React warns on setState-after-unmount via console.error; silence means
+    // the unmount cleanup cleared the pending timer.
+    expect(errorSpy).not.toHaveBeenCalled();
+    errorSpy.mockRestore();
+  });
+});

package/src/internal/isUnimplemented.ts

@@ -0,0 +1,26 @@
+/**
+ * Detect gRPC/Connect UNIMPLEMENTED (code 12) from any error the SDK
+ * client can throw.
+ *
+ * UNIMPLEMENTED is how the shared SDK discovers edition capabilities:
+ * the OSS server deliberately leaves hosted-only RPCs unimplemented
+ * (e.g. the org-OAuth-app override surface, stigmer/stigmer#558), and
+ * hooks probe for it to degrade gracefully instead of surfacing an
+ * error. The SDK's generated CODE_MAP does not include Unimplemented —
+ * a `StigmerError` wrapping one reports `code: "unknown"` — so
+ * detection must go through `connectCode` (or the message shapes used
+ * by transports that never produce a structured error).
+ *
+ * @internal
+ */
+export function isUnimplemented(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  if (
+    "connectCode" in err &&
+    (err as { connectCode: unknown }).connectCode === 12
+  ) {
+    return true;
+  }
+  const msg = (err as { message?: string }).message ?? "";
+  return msg.includes("[unimplemented]") || msg.includes("UNIMPLEMENTED");
+}

package/src/internal/select-element-text.ts

@@ -0,0 +1,17 @@
+/**
+ * Select an element's text content, replacing any existing selection.
+ *
+ * The honest fallback for one-time secret reveals (API keys, invite URLs,
+ * client secrets) when the clipboard write is rejected (insecure context,
+ * denied permission): instead of claiming "Copied" for a copy that didn't
+ * happen, the revealed value is selected so the user can copy it manually.
+ * Pair with `useCopyFeedback` — branch on its `copy()` result.
+ */
+export function selectElementText(el: HTMLElement): void {
+  const selection = window.getSelection();
+  if (!selection) return;
+  const range = document.createRange();
+  range.selectNodeContents(el);
+  selection.removeAllRanges();
+  selection.addRange(range);
+}

package/src/internal/thread-card/ThreadCardShell.tsx

@@ -14,7 +14,8 @@ import { ChevronIcon } from "./glyphs.js";
  * Three pieces, composed via children (slots-as-children, never a
  * mega-prop card — each thread's composition stays explicit):
  *
- * - {@link ThreadCardShell} — the chrome: bordered card vs divider row,
+ * - {@link ThreadCardShell} — the chrome tier: bordered card, nested divider
+ *   row, or quiet unboxed line ({@link ThreadCardVariant}), plus the
  *   pending-gate accent.
  * - {@link ThreadCardHeader} — the one-line header region with a
  *   primary gesture: `expand` (summary rows, `aria-expanded`, appends
@@ -41,15 +42,25 @@ import { ChevronIcon } from "./glyphs.js";
 // Shell — the card chrome
 // ---------------------------------------------------------------------------
 
+/**
+ * The chrome tier of a thread row (the density axis at the shell level):
+ *
+ * - `"card"` — a self-contained bordered card (the default).
+ * - `"row"` — a divider-separated row for rows nested inside a container
+ *   that already provides the frame (e.g. an expanded `ToolRunGroup` fold),
+ *   avoiding a card-in-a-card.
+ * - `"quiet"` — no chrome at all: an unboxed line for metadata-only rows
+ *   whose header IS the complete information (reads, listings, thoughts).
+ *   The gate accent is deliberately not drawn in this tier — a row carrying
+ *   an accent must be escalated to `"card"` by the caller, never rendered
+ *   as an accented bare line.
+ */
+export type ThreadCardVariant = "card" | "row" | "quiet";
+
 /** Props for {@link ThreadCardShell}. */
 export interface ThreadCardShellProps {
-  /**
-   * Whether the row renders as its own self-contained card (a thin rounded
-   * border). Set to `false` when nested inside a container that already
-   * provides the border — e.g. the folded `ToolRunGroup` chip — where the
-   * row degrades to a divider-separated row to avoid a card-in-a-card.
-   */
-  readonly bordered?: boolean;
+  /** The chrome tier — see {@link ThreadCardVariant}. Defaults to `"card"`. */
+  readonly variant?: ThreadCardVariant;
   /**
    * A restrained left accent for a row awaiting a human decision —
    * `"warning"` for ordinary gates, `"destructive"` for delete gates.
@@ -64,25 +75,31 @@ export interface ThreadCardShellProps {
   readonly children: ReactNode;
 }
 
+const VARIANT_CHROME: Record<Exclude<ThreadCardVariant, "card">, string> = {
+  row: "stg:border-b stg:border-border-muted stg:last:border-b-0",
+  quiet: "",
+};
+
 /** The thread card's outer chrome. See the module doc for the full contract. */
 export function ThreadCardShell({
-  bordered = true,
+  variant = "card",
   accent = null,
   cursorTarget,
   className,
   ref,
   children,
 }: ThreadCardShellProps) {
-  const chrome = bordered
-    ? cn(
-        // border-prominent (not border): a transparent card needs a line the
-        // eye actually catches — the default border token is white at 14%
-        // opacity, which vanishes on the dark thread surface.
-        "stg:rounded-lg stg:border stg:border-border-prominent stg:overflow-hidden",
-        accent === "warning" && "stg:border-l-2 stg:border-l-warning",
-        accent === "destructive" && "stg:border-l-2 stg:border-l-destructive",
-      )
-    : "stg:border-b stg:border-border-muted stg:last:border-b-0";
+  const chrome =
+    variant === "card"
+      ? cn(
+          // border-prominent (not border): a transparent card needs a line the
+          // eye actually catches — the default border token is white at 14%
+          // opacity, which vanishes on the dark thread surface.
+          "stg:rounded-lg stg:border stg:border-border-prominent stg:overflow-hidden",
+          accent === "warning" && "stg:border-l-2 stg:border-l-warning",
+          accent === "destructive" && "stg:border-l-2 stg:border-l-destructive",
+        )
+      : VARIANT_CHROME[variant];
 
   return (
     <div ref={ref} data-cursor-target={cursorTarget} className={cn(chrome, className)}>
@@ -176,13 +193,28 @@ export interface ThreadCardBodyProps {
   readonly id?: string;
   /** Rendered as `data-cursor-target` for e2e targeting. */
   readonly cursorTarget?: string;
+  /**
+   * Body containment for a `"quiet"` shell: with no card border around it, a
+   * disclosed body needs its own boundary — a light left rail (the
+   * `ThinkingMessage` expanded-state precedent) instead of the card's padding
+   * box. Ignored for card/row shells, whose frame already bounds the body.
+   */
+  readonly rail?: boolean;
   readonly children: ReactNode;
 }
 
 /** The thread card's body padding contract. */
-export function ThreadCardBody({ id, cursorTarget, children }: ThreadCardBodyProps) {
+export function ThreadCardBody({ id, cursorTarget, rail = false, children }: ThreadCardBodyProps) {
   return (
-    <div id={id} data-cursor-target={cursorTarget} className="stg:px-2.5 stg:pb-2.5 stg:pt-1">
+    <div
+      id={id}
+      data-cursor-target={cursorTarget}
+      className={
+        rail
+          ? "stg:ml-1.5 stg:border-l-2 stg:border-border-muted stg:py-1 stg:pl-3 stg:pr-2.5"
+          : "stg:px-2.5 stg:pb-2.5 stg:pt-1"
+      }
+    >
       {children}
     </div>
   );

package/src/internal/thread-card/glyphs.tsx

@@ -13,10 +13,31 @@ import { cn } from "@stigmer/theme";
  * @internal Not part of the public API.
  */
 
-/** Quarter-arc spinner for an in-flight item. */
-export function SpinnerIcon() {
+/**
+ * Quarter-arc spinner for an in-flight item. Deliberately finer than the
+ * SDK-wide `internal/SpinnerIcon` (1.5 stroke on a 12 grid vs 2 on 16) —
+ * the micro-row weight this vocabulary is built around. Card-adjacent
+ * surfaces that used to carry their own copies (tool-run groups, file
+ * review, decision buttons) size it up via `size` instead.
+ */
+export function SpinnerIcon({
+  size = 10,
+  className,
+}: {
+  readonly size?: number;
+  readonly className?: string;
+} = {}) {
   return (
-    <svg width="10" height="10" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" className="stg:animate-spin">
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      className={cn("stg:animate-spin", className)}
+      aria-hidden="true"
+    >
       <path d="M6 1.5A4.5 4.5 0 1 1 1.5 6" strokeLinecap="round" />
     </svg>
   );

package/src/internal/thread-card/index.ts

@@ -2,6 +2,7 @@ export {
   ThreadCardShell,
   ThreadCardHeader,
   ThreadCardBody,
+  type ThreadCardVariant,
   type ThreadCardShellProps,
   type ThreadCardHeaderProps,
   type ThreadCardHeaderGesture,

package/src/internal/useCopyFeedback.ts

@@ -0,0 +1,61 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+/** How long the transient `copied` flag stays true after a successful copy. */
+const COPIED_FEEDBACK_MS = 2000;
+
+/** Return value of {@link useCopyFeedback}. */
+export interface UseCopyFeedbackReturn {
+  /**
+   * Write `text` to the clipboard. Resolves `true` when the write landed and
+   * `false` when it was rejected (insecure context, denied permission); a
+   * rejected write leaves `copied` false so the affordance never claims a
+   * copy that didn't happen. Callers with a manual fallback (e.g. selecting
+   * the on-screen text for a hand copy) branch on the result; plain
+   * affordances can ignore it.
+   */
+  readonly copy: (text: string) => Promise<boolean>;
+
+  /**
+   * `true` for a brief window after a successful copy (drives "Copied"
+   * affordance feedback), then resets automatically.
+   */
+  readonly copied: boolean;
+}
+
+/**
+ * Behavior hook for the copy-with-feedback shape: write locally-held text to
+ * the clipboard and flash a transient `copied` flag for the affordance swap.
+ *
+ * This is the fetch-free sibling of `useArtifactCopy` (which resolves remote
+ * artifact bytes at click time); use it wherever the text to copy is already
+ * in hand — message content, identifiers, code blocks. One implementation
+ * keeps the feedback window and the unmount-safety identical across surfaces.
+ */
+export function useCopyFeedback(): UseCopyFeedbackReturn {
+  const [copied, setCopied] = useState(false);
+
+  // Clear the pending "copied" timer on unmount so a resolved copy never sets
+  // state on an unmounted component.
+  const copiedTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    return () => {
+      if (copiedTimer.current !== null) clearTimeout(copiedTimer.current);
+    };
+  }, []);
+
+  const copy = useCallback(async (text: string) => {
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      return false;
+    }
+    setCopied(true);
+    if (copiedTimer.current !== null) clearTimeout(copiedTimer.current);
+    copiedTimer.current = setTimeout(() => setCopied(false), COPIED_FEEDBACK_MS);
+    return true;
+  }, []);
+
+  return useMemo(() => ({ copy, copied }), [copy, copied]);
+}