@tai42/studio-sdk 0.12.0 → 0.13.0

package/dist/navigation/context.js

@@ -1,13 +1,189 @@
-import { createContext, createElement, useCallback, useContext, } from 'react';
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+/** Shell-provided navigation; no default, so use outside {@link NavigationProvider} throws. */
+const NavigationContext = createContext(null);
 /**
- * Shell-provided navigation. The context has no default: a feature rendered
- * outside the shell's {@link NavigationProvider} is a wiring bug, so
- * {@link useNavigation} raises loudly rather than silently no-op'ing a
- * transition.
+ * The guards active under one {@link NavigationProvider} — the single registry
+ * every SDK-controlled navigation consults, so feature and plugin-page guards
+ * compose against the same set. `run` stops at the first veto (at most one confirm
+ * dialog); `subscribe` re-evaluates browser-level listeners when the armed set changes.
  */
-const NavigationContext = createContext(null);
+class NavigationGuardRegistry {
+    guards = new Set();
+    listeners = new Set();
+    /** Register a guard; returns the unregister function. */
+    add(entry) {
+        this.guards.add(entry);
+        this.emit();
+        return () => {
+            this.guards.delete(entry);
+            this.emit();
+        };
+    }
+    /** Notify subscribers that a guard's `when` may have changed. */
+    touch() {
+        this.emit();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    hasArmedGuards() {
+        for (const entry of this.guards) {
+            if (entry.when)
+                return true;
+        }
+        return false;
+    }
+    /** Resolve `true` only if every armed guard allows the navigation. */
+    async run() {
+        for (const entry of this.guards) {
+            if (!entry.when)
+                continue;
+            const allowed = await entry.handler();
+            if (!allowed)
+                return false;
+        }
+        return true;
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * Carries the provider's guard registry to {@link useNavigationGuard}. Separate from
+ * {@link NavigationContext} so the shell-supplied value stays exactly the shell's
+ * contract — the registry is SDK-owned.
+ */
+const GuardRegistryContext = createContext(null);
+function useGuardRegistry() {
+    const registry = useContext(GuardRegistryContext);
+    if (registry === null) {
+        throw new Error('useNavigationGuard must be used within a <NavigationProvider> (the shell provides it).');
+    }
+    return registry;
+}
 export function NavigationProvider({ value, children, }) {
-    return createElement(NavigationContext.Provider, { value }, children);
+    const registryRef = useRef(null);
+    registryRef.current ??= new NavigationGuardRegistry();
+    const registry = registryRef.current;
+    // The last committed history entry the SDK observed (URL + `history.state`): what a
+    // canceled back/forward restores to. URL changes made outside the SDK's navigate
+    // entry points are unobservable by design at this layer.
+    const committedRef = useRef(null);
+    // Mirror the registry's armed state into React so the browser listeners attach only
+    // while at least one guard is armed.
+    const [armed, setArmed] = useState(false);
+    useEffect(() => {
+        setArmed(registry.hasArmedGuards());
+        return registry.subscribe(() => {
+            setArmed(registry.hasArmedGuards());
+        });
+    }, [registry]);
+    useEffect(() => {
+        if (!armed)
+            return;
+        // The protected entry (URL + state); a back/forward landing elsewhere is first
+        // canceled back to here while the guard is consulted.
+        committedRef.current = { href: window.location.href, state: window.history.state };
+        // Set while replaying a guard-approved back/forward, so its `popstate` passes
+        // through instead of being re-intercepted.
+        let bypass = false;
+        // Latched while a decision is pending, so a second Back mid-decision keeps canceling
+        // without starting a concurrent `registry.run()` — one gesture, one dialog.
+        let pending = false;
+        // Restore pushes stacked for the pending decision, so an approved replay unwinds
+        // exactly that far in one `go(-depth)`. Reset per decision.
+        let restores = 0;
+        const onPopState = () => {
+            if (bypass) {
+                bypass = false;
+                committedRef.current = { href: window.location.href, state: window.history.state };
+                return;
+            }
+            if (!registry.hasArmedGuards()) {
+                committedRef.current = { href: window.location.href, state: window.history.state };
+                return;
+            }
+            const committed = committedRef.current;
+            if (committed === null)
+                return;
+            // Cancel the browser's move by pushing the committed entry on top of wherever it
+            // landed. popstate exposes no direction/distance and the router owns
+            // `history.state`, so restore can only push, not delete. A vetoed forward thus
+            // strands a stub entry — an accepted limit the next pushState truncates.
+            window.history.pushState(committed.state, '', committed.href);
+            restores += 1;
+            if (pending)
+                return;
+            pending = true;
+            void registry.run().then((allowed) => {
+                pending = false;
+                const depth = restores;
+                restores = 0;
+                if (!allowed)
+                    return;
+                bypass = true;
+                window.history.go(-depth);
+            });
+        };
+        const onBeforeUnload = (event) => {
+            event.preventDefault();
+            // Browsers below the floor (Chrome 108) gate the prompt on a set `returnValue`,
+            // not `preventDefault` alone; the string is ignored. Typed deprecated, still required.
+            // eslint-disable-next-line @typescript-eslint/no-deprecated -- required beforeunload trigger for the supported browser range.
+            event.returnValue = '';
+        };
+        window.addEventListener('popstate', onPopState);
+        window.addEventListener('beforeunload', onBeforeUnload);
+        return () => {
+            committedRef.current = null;
+            window.removeEventListener('popstate', onPopState);
+            window.removeEventListener('beforeunload', onBeforeUnload);
+        };
+    }, [armed, registry]);
+    // Wrap the shell's transitions so an armed guard is consulted before they commit.
+    // With no guard armed the call stays synchronous — identical to the raw shell value.
+    const guarded = useMemo(() => {
+        const navigate = (token, search) => {
+            if (!registry.hasArmedGuards()) {
+                value.navigate(token, search);
+                return;
+            }
+            void registry.run().then((allowed) => {
+                if (!allowed)
+                    return;
+                value.navigate(token, search);
+                // Advance the committed entry to the resolved destination (the router may commit
+                // async, so `window.location` would be stale). Its router state is unobservable
+                // here, hence `state: null`.
+                if (committedRef.current !== null) {
+                    committedRef.current = { href: value.resolvePath(token, search), state: null };
+                }
+            });
+        };
+        const navigatePlugin = (pluginId, pagePath, params, search) => {
+            if (!registry.hasArmedGuards()) {
+                value.navigatePlugin(pluginId, pagePath, params, search);
+                return;
+            }
+            void registry.run().then((allowed) => {
+                if (!allowed)
+                    return;
+                value.navigatePlugin(pluginId, pagePath, params, search);
+                if (committedRef.current !== null) {
+                    committedRef.current = {
+                        href: value.resolvePluginPath(pluginId, pagePath, params, search),
+                        state: null,
+                    };
+                }
+            });
+        };
+        return { ...value, navigate, navigatePlugin };
+    }, [value, registry]);
+    return createElement(GuardRegistryContext.Provider, { value: registry }, createElement(NavigationContext.Provider, { value: guarded }, children));
 }
 function useNavigation() {
     const ctx = useContext(NavigationContext);
@@ -24,6 +200,28 @@ export function useAppNavigate() {
 export function useResolvePath() {
     return useNavigation().resolvePath;
 }
+/**
+ * Block navigation away from the current page while `when` is true. `handler` is
+ * consulted before any SDK-controlled navigation commits — a route-token navigate,
+ * a plugin navigate, or a browser back/forward — and the navigation proceeds only if
+ * it resolves `true`; a promise lets the handler drive a confirm dialog. A full-page
+ * unload (tab close / refresh) is additionally covered by a native `beforeunload`
+ * prompt that fires whenever any guard is armed.
+ *
+ * Guards compose against the provider's shared registry: a feature and a plugin page
+ * may each arm one, and any veto blocks.
+ */
+export function useNavigationGuard(when, handler) {
+    const registry = useGuardRegistry();
+    const entryRef = useRef({ when, handler });
+    // Keep the registered entry pointing at the latest inputs without re-registering.
+    entryRef.current.when = when;
+    entryRef.current.handler = handler;
+    useEffect(() => registry.add(entryRef.current), [registry]);
+    useEffect(() => {
+        registry.touch();
+    }, [registry, when]);
+}
 /**
  * Plugin-page navigation: `navigatePlugin` drives a client-side transition to a
  * runtime plugin path, `resolvePluginPath` yields its href. These are the ONLY

package/dist/navigation/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/navigation/context.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,GAIX,MAAM,OAAO,CAAC;AAIf;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,aAAa,CAAgC,IAAI,CAAC,CAAC;AAE7E,MAAM,UAAU,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GAIT;IACC,OAAO,aAAa,CAAC,iBAAiB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,GAAG,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC1C,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,mFAAmF,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc;IAC5B,OAAO,aAAa,EAAE,CAAC,QAAQ,CAAC;AAClC,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,cAAc;IAC5B,OAAO,aAAa,EAAE,CAAC,WAAW,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB;IAIjC,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,GAAG,aAAa,EAAE,CAAC;IAC9D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;AAC/C,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAuB,EAC5C,EAAE,EACF,MAAM,EACN,QAAQ,EACR,SAAS,EACT,YAAY,EAAE,SAAS,EACvB,cAAc,EAAE,WAAW,GACX;IAChB,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,aAAa,EAAE,CAAC;IAClD,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,KAAoC,EAAE,EAAE;QACvC,IAAI,KAAK,CAAC,gBAAgB;YAAE,OAAO;QACnC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM;YACxF,OAAO;QACT,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACvB,CAAC,EACD,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,CACvB,CAAC;IACF,OAAO,aAAa,CAClB,GAAG,EACH,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,OAAO,EAAE,EAClF,QAAQ,CACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/navigation/context.tsx"],"names":[],"mappings":"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"}

package/dist/navigation/index.d.ts

@@ -1,4 +1,4 @@
-export { NavigationProvider, AppLink, useAppNavigate, useResolvePath, usePluginNavigation, } from './context';
+export { NavigationProvider, AppLink, useAppNavigate, useResolvePath, usePluginNavigation, useNavigationGuard, } from './context';
 export type { AppLinkProps } from './context';
-export type { RouteToken, RouteSearch, RouteSearchByToken, PageProps, NavigationContextValue, PluginSearch, } from './types';
+export type { RouteToken, RouteSearch, RouteSearchByToken, PageProps, NavigationContextValue, PluginSearch, NavigationGuardHandler, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/navigation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,cAAc,EACd,cAAc,EACd,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,sBAAsB,EACtB,YAAY,GACb,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,sBAAsB,EACtB,YAAY,EACZ,sBAAsB,GACvB,MAAM,SAAS,CAAC"}

package/dist/navigation/index.js

@@ -1,2 +1,2 @@
-export { NavigationProvider, AppLink, useAppNavigate, useResolvePath, usePluginNavigation, } from './context';
+export { NavigationProvider, AppLink, useAppNavigate, useResolvePath, usePluginNavigation, useNavigationGuard, } from './context';
 //# sourceMappingURL=index.js.map

package/dist/navigation/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,cAAc,EACd,cAAc,EACd,mBAAmB,GACpB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,OAAO,EACP,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC"}

package/dist/navigation/types.d.ts

@@ -108,4 +108,15 @@ export interface NavigationContextValue {
     navigatePlugin: (pluginId: string, pagePath: string, params?: string, search?: PluginSearch) => void;
     resolvePluginPath: (pluginId: string, pagePath: string, params?: string, search?: PluginSearch) => string;
 }
+/**
+ * A navigation guard's decision function, run while armed before any SDK-controlled
+ * navigation commits ({@link NavigationContextValue.navigate},
+ * {@link NavigationContextValue.navigatePlugin}, or a browser back/forward). Returns
+ * `true` to proceed, `false` to veto; a promise lets it await a confirm dialog.
+ *
+ * Guards compose — navigation proceeds only if every armed guard allows, and the first
+ * veto blocks (at most one dialog). A full-page unload can't await, so it is covered by
+ * a `beforeunload` prompt independent of this handler.
+ */
+export type NavigationGuardHandler = () => boolean | Promise<boolean>;
 //# sourceMappingURL=types.d.ts.map

package/dist/navigation/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/navigation/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/navigation/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tai42/studio-sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The Studio plugin contract, shared UI components, and hooks that every feature builds on.",
   "license": "Apache-2.0",
   "author": "tai42 <oss@tai42.ai>",
@@ -89,7 +89,7 @@
     "@radix-ui/react-select": "^2.3.2",
     "@radix-ui/react-tabs": "^1.1.16",
     "@radix-ui/react-tooltip": "^1.2.11",
-    "@tai42/api-client": "0.12.0"
+    "@tai42/api-client": "0.13.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json && node scripts/copy-assets.mjs",

package/src/components/code-block.tsx

@@ -1,16 +1,23 @@
 /**
  * `CodeBlock` — escaped, monospaced preformatted text for tool results and string
  * payloads, on the design system's terminal ground (`tai-code-block`). The content
- * is a React text child inside `<pre><code>`, so it is escaped by React and
- * rendered verbatim; this component is NEVER an HTML sink (no
+ * is a React text child inside `<pre><code>`; NEVER an HTML sink (no
  * `dangerouslySetInnerHTML`).
  *
- * The `<pre>` IS the scrolling box, so it carries the region attributes itself
- * rather than sitting inside a `ScrollRegion` wrapper that would add a second
- * scroller: a long line makes it a named keyboard target, a short one leaves it
- * an ordinary block.
+ * The `<pre>` IS the scrolling box, carrying the region attributes itself rather
+ * than nesting a `ScrollRegion` that would add a second scroller.
+ *
+ * A top-right copy button sits OUTSIDE the `<pre>`, pinned to a relatively-positioned
+ * frame, so horizontal scroll never carries it off-screen. Its accessible name is
+ * the state it shows ("Copy code" / "Copied"), so it is never named by words it has
+ * stopped saying (WCAG 2.5.3). A clipboard failure renders as a visible `role="alert"`
+ * naming the reason, never the payload — see {@link useClipboardCopy}.
  */
+import type { CSSProperties } from 'react';
+
+import { CheckIcon, CopyIcon, XCircleIcon } from './icons';
 import { useOverflowRegion } from './scroll-region';
+import { COPIED_LABEL, useClipboardCopy } from '../hooks/useClipboardCopy';
 
 export interface CodeBlockProps {
   readonly code: string;
@@ -21,17 +28,73 @@ export interface CodeBlockProps {
 /** The region's name when no language caption supplies one. */
 const DEFAULT_LABEL = 'Code';
 
+/** The button's resting accessible name; whichever face shows is also its name. */
+const COPY_LABEL = 'Copy code';
+
+/** Shown when the browser offers no clipboard at all (any non-secure context). */
+const NO_CLIPBOARD =
+  'This browser will not write to the clipboard here. Select the code and copy it.';
+
+/** Shown when the write is offered and refused. */
+function writeFailed(reason: unknown): string {
+  const detail = reason instanceof Error ? reason.message : String(reason);
+  return `Copy failed: ${detail}. Select the code and copy it.`;
+}
+
+/** The frame the copy button is pinned to, over the top-right of the code. */
+const frameStyle: CSSProperties = { position: 'relative' };
+
+const copyButtonStyle: CSSProperties = {
+  position: 'absolute',
+  top: 'var(--tai-space-2)',
+  right: 'var(--tai-space-2)',
+};
+
 export function CodeBlock({ code, language }: CodeBlockProps) {
   // No consumer ref: the measurement's own callback ref is the only thing that
   // needs the `<pre>`, and this component publishes no `ref` prop.
   const region = useOverflowRegion(undefined, language ?? DEFAULT_LABEL);
 
+  const {
+    copied,
+    error: copyError,
+    announcement,
+    copy,
+  } = useClipboardCopy({
+    noClipboard: NO_CLIPBOARD,
+    writeFailed,
+  });
+
+  const handleCopy = (): void => {
+    void copy(() => code);
+  };
+
   return (
     <div className="tai-stack tai-stack-2">
       {language !== undefined ? <span className="tai-label">{language}</span> : null}
-      <pre className="tai-code-block" {...region}>
-        <code>{code}</code>
-      </pre>
+      <div style={frameStyle}>
+        <pre className="tai-code-block" {...region}>
+          <code>{code}</code>
+        </pre>
+        <button
+          type="button"
+          className="tai-icon-btn"
+          style={copyButtonStyle}
+          aria-label={copied ? COPIED_LABEL : COPY_LABEL}
+          onClick={handleCopy}
+        >
+          {copied ? <CheckIcon /> : <CopyIcon />}
+        </button>
+        <span aria-live="polite" className="tai-visually-hidden">
+          {announcement}
+        </span>
+      </div>
+      {copyError !== undefined ? (
+        <span role="alert" className="tai-field-error">
+          <XCircleIcon />
+          {copyError}
+        </span>
+      ) : null}
     </div>
   );
 }

package/src/components/components.css

@@ -1316,6 +1316,26 @@
     color: var(--tai-color-text);
   }
 
+  /* Fullscreen variant: fills the viewport instead of centring at a fixed size.
+     Composes with `.tai-dialog`, overriding only geometry and edge chrome. */
+  .tai-dialog-fullscreen {
+    top: 0;
+    left: 0;
+    transform: none;
+    /* `border-box` so `100vw` is the outer edge and never overflows; declared here,
+       not inherited from `.tai-dialog`. */
+    box-sizing: border-box;
+    width: 100vw;
+    max-width: none;
+    /* `dvh` is the live viewport with a `vh` fallback for browsers below the `dvh` floor. */
+    height: 100vh;
+    height: 100dvh;
+    max-height: none;
+    padding: 0;
+    border: 0;
+    border-radius: 0;
+  }
+
   .tai-dialog-title {
     margin: 0 0 var(--tai-space-2);
     font-size: var(--tai-text-section);

package/src/components/copy-field.tsx

@@ -1,32 +1,24 @@
 /**
- * `CopyField` — a show-once box for a freshly-minted secret (an API key or a
- * minted backup key). It renders the value in a monospace, break-all,
- * select-all box beside a copy button that writes the value to the clipboard and
- * shows a transient "Copied" affordance. It is PRESENTATIONAL: the caller owns
- * the value; this component fetches nothing and never re-reads the secret.
+ * `CopyField` — a show-once box for a freshly-minted secret (an API or backup key)
+ * beside a copy button that writes it to the clipboard and shows a transient "Copied"
+ * affordance. PRESENTATIONAL: the caller owns the value; this fetches nothing and
+ * never re-reads the secret.
  *
- * The button holds BOTH states stacked in one grid cell, so the widest of them
- * sets the width once and the flip never reflows the row. Only the active state
- * is exposed to assistive tech, and that state's own words are the button's
- * accessible name: a constant `aria-label` would leave a button reading "Copied"
- * named "Copy", which fails WCAG 2.5.3 (Label in Name) and leaves a voice-control
- * user naming a control they cannot see. The polite live region beside the button
- * is what actually announces the flip.
+ * The button holds BOTH states stacked in one grid cell, so the wider one sets the
+ * width once and the flip never reflows. Only the active state is exposed to
+ * assistive tech, and its own words are the button's accessible name — a constant
+ * `aria-label` would leave a "Copied" button named "Copy" (WCAG 2.5.3).
  *
- * A clipboard write can FAIL — a permissions policy blocks it, or the page is
- * not in a secure context, where `navigator.clipboard` does not exist at all.
- * Either way the value is a secret shown once, so the failure is rendered as a
- * visible `role="alert"` telling the reader to copy it by hand: throwing it at
- * the console would leave the button looking inert and the secret unrecoverable.
+ * A clipboard failure renders as a visible `role="alert"` telling the reader to copy
+ * by hand — the secret is shown once, so a swallowed failure leaves it unrecoverable.
  *
- * SAFETY: the value and caption render as TEXT (React escapes them) — never an
- * HTML sink. The value is never logged, and neither is a failure — the alert
- * names the reason, never the value. Pinned by a test.
+ * SAFETY: value and caption render as TEXT — never an HTML sink. The value is never
+ * logged, and the alert names the reason, never the value. Pinned by a test.
  */
-import { useEffect, useRef, useState } from 'react';
 import type { CSSProperties } from 'react';
 
 import { CheckIcon, CopyIcon, XCircleIcon } from './icons';
+import { COPIED_LABEL, useClipboardCopy } from '../hooks/useClipboardCopy';
 
 export interface CopyFieldProps {
   readonly value: string;
@@ -35,29 +27,8 @@ export interface CopyFieldProps {
   readonly label?: string;
 }
 
-const COPIED_RESET_MS = 2000;
-
-/** The button's two faces. Whichever is exposed is also its accessible name. */
+/** The button's resting face; whichever face is exposed is also its accessible name. */
 const COPY_LABEL = 'Copy';
-const COPIED_LABEL = 'Copied';
-
-/** Announced once, and worded so it is never mistaken for the visible label. */
-const COPIED_ANNOUNCEMENT = 'Copied to clipboard';
-
-/**
- * `lib.dom` declares `navigator.clipboard` as always present, but the platform
- * exposes it only in a SECURE CONTEXT — over plain http it is not there at all.
- * Reading the navigator through this shape admits the absence the DOM types deny,
- * so the guard below is a real check rather than a cast around one.
- */
-interface MaybeClipboard {
-  readonly clipboard?: Clipboard;
-}
-
-/** The clipboard this browser actually offers, or `undefined` when it offers none. */
-function clipboardOf(host: MaybeClipboard): Clipboard | undefined {
-  return host.clipboard;
-}
 
 /** Shown when the browser offers no clipboard at all (any non-secure context). */
 const NO_CLIPBOARD =
@@ -91,45 +62,18 @@ const stateStyle: CSSProperties = {
 };
 
 export function CopyField({ value, caption, idPrefix = 'copy-field', label }: CopyFieldProps) {
-  const [copied, setCopied] = useState(false);
-  const [copyError, setCopyError] = useState<string | undefined>(undefined);
-  const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  // The clipboard write is async, so a copy can still be in flight when the
-  // component goes away — the caller's dialog closes on the same click. Clearing
-  // the timer alone would not cover that: at unmount there is no timer yet, and
-  // the resolution that follows would start one nothing is left to clear. This
-  // flag is what the resolution checks before it touches state at all.
-  const mounted = useRef(true);
-
-  useEffect(() => {
-    mounted.current = true;
-    return () => {
-      mounted.current = false;
-      if (resetTimer.current !== null) clearTimeout(resetTimer.current);
-    };
-  }, []);
+  const {
+    copied,
+    error: copyError,
+    announcement,
+    copy,
+  } = useClipboardCopy({
+    noClipboard: NO_CLIPBOARD,
+    writeFailed,
+  });
 
   const handleCopy = (): void => {
-    const clipboard = clipboardOf(navigator);
-    if (clipboard === undefined) {
-      setCopyError(NO_CLIPBOARD);
-      return;
-    }
-    setCopyError(undefined);
-    void clipboard.writeText(value).then(
-      () => {
-        if (!mounted.current) return;
-        setCopied(true);
-        if (resetTimer.current !== null) clearTimeout(resetTimer.current);
-        resetTimer.current = setTimeout(() => {
-          setCopied(false);
-        }, COPIED_RESET_MS);
-      },
-      (error: unknown) => {
-        if (!mounted.current) return;
-        setCopyError(writeFailed(error));
-      },
-    );
+    void copy(() => value);
   };
 
   return (
@@ -163,7 +107,7 @@ export function CopyField({ value, caption, idPrefix = 'copy-field', label }: Co
           </span>
         </button>
         <span aria-live="polite" className="tai-visually-hidden">
-          {copied ? COPIED_ANNOUNCEMENT : ''}
+          {announcement}
         </span>
       </div>
       {copyError !== undefined ? (