@robota-sdk/agent-ui-web 0.0.0-stage → 3.0.0-beta.94

package/docs/README.md

@@ -0,0 +1,62 @@
+# @robota-sdk/agent-ui-web
+
+The **GUI presentation layer** for an agent session — the graphical analog of `@robota-sdk/agent-ui-terminal`.
+It reconstructs conversation state from the transport-neutral `TServerMessage` stream and renders it as React
+components. Its public `/client` entry supplies the browser-safe reducer, WebSocket client, session shell
+and runtime-host contract for a consumer-owned renderer. The same components serve the repository's GUI
+web app and browser-remote surface.
+
+## What it owns
+
+- `useSessionClient(makeClient)` — the transport-neutral session reducer (generic over the status type).
+- `useWsSession(url)` + `createWsSessionClient` — the localhost WebSocket binding.
+- `resolveClientRuntimeHost(environment)` — a browser endpoint resolver or a narrow desktop bridge
+  adapter. The desktop bridge owns trust, endpoint validation and runtime lifecycle; a renderer asks
+  `trustQuestion` before `getEndpoint` and calls `signalReady` after connection.
+- Prompt state: `applyPromptEvent`, `permissionResponse`, `askResponse`.
+- UI-intent state: `guiScreenForUiIntent` (the GUI screen a command's UI intent opens, if any) and
+  `describeUiIntentForGui` (the explicit "not available on this surface" line otherwise).
+- Components: `SessionSurface`, `CenteredChrome`, `ConversationView`, `AgentActivityPanel`,
+  `PermissionPrompt`, `SessionSidebar` (the host's sessions; switch or start one), `SessionMonitor` (a
+  self-contained session page for a WebSocket URL), and `PersonalUsageDashboard` (7- and 30-day usage).
+- Brand marks: `ProductMark`, `ProductWordmark` — render them inside a `agent-ui` scope.
+- `styles/surface.css` — the design scoped to `.agent-ui` (bundled Pretendard, light and dark tokens, Tailwind
+  token map, base layers); import it into a host app's Tailwind entry to embed the surface.
+- `styles/theme.css` — `surface.css` plus what a page that is only the surface owns (height, background,
+  scrollbars); that page puts `agent-ui` on its `<html>`.
+
+## Using it
+
+```tsx
+import { useWsSession, SessionSurface } from '@robota-sdk/agent-ui-web/client';
+
+export function App({ url }: { url: string }) {
+  const state = useWsSession(url);
+  return <SessionSurface state={state} surface="app" />;
+}
+```
+
+The components author Tailwind utility classes and ship **no compiled CSS** — the consumer owns the Tailwind
+entry and sources this package's `src`:
+
+```css
+/* app entry css */
+@import 'tailwindcss';
+@import '@robota-sdk/agent-ui-web/styles/theme.css';
+@source '../../node_modules/@robota-sdk/agent-ui-web/src';
+@source './';
+```
+
+A different transport supplies its own `makeClient` (a `TMakeSessionClient<TStatus>`) and, if it adds
+connection states, instantiates `useSessionClient<ItsStatus>` — see `useRtcSession` in `@robota-sdk/agent-transport-webrtc-web`.
+
+See [SPEC.md](./SPEC.md) for the full contract.
+
+The source repository's Cedar renderer fixture shows a consumer-owned toolbar calling a custom
+command, desktop trust admission, session restoration and reconnect. Its local-pack
+build is prerelease evidence; a clean registry-installed build is required after publication.
+
+The package tarball includes source styles, declarations and its AGPL license. React is a peer dependency;
+the consumer supplies React, React DOM, Tailwind v4 and a bundler. Third-party runtime dependencies are
+declared in `package.json`; a distributable renderer must include their notices and licenses in its own
+artifact. The package does not include the private GUI web app or Electron shell.

package/docs/SPEC.md

@@ -0,0 +1,124 @@
+# SPEC.md — @robota-sdk/agent-ui-web
+
+## Transport Admission
+
+transport-admission: none — a presentation layer. It renders a server-message stream that some
+other transport has already admitted a peer onto, and opens no socket of its own.
+
+## Purpose
+
+The GUI presentation layer for a running agent session — the graphical analog of the terminal
+presentation package. It reconstructs conversation state from the transport-neutral server-message
+stream and renders it as React components, and it ships the session shell (title/status bar,
+conversation column, background-activity rail, and a composer with the pending question docked above
+it). It is consumed by the GUI web app — which the desktop app loads and the CLI serves — and by the
+browser-remote surface.
+
+This package sits in the transport/presentation layer. It is a pure UI + wire-reducer library — it
+does not own session lifecycle, conversation history, or agent runtime state.
+
+## Contract and guarantees
+
+- The session reducer is generic over the connection-status type, so a transport can widen the
+  status union (e.g. to add pairing/failure states) without this package depending on that
+  transport.
+- Every server-message wire variant is assigned an explicit disposition — a specialized reducer
+  path, transport lifecycle handling, or an explicit "intentionally not rendered" marker. An
+  unrecognized or not-yet-supported message never falls through silently.
+- The conversation carries what the CLI's transcript carries: a typed command's outcome and a
+  finished turn's tool calls sit in it where they happened, and never push the composer out of view —
+  the same whether they streamed in live or were rebuilt from a reload, reconnect, or session resume's
+  history replay, never falling back to bare text once a tool call is gone from what a live stream
+  would have shown. A change made through a status control instead confirms itself through the
+  control's own label — never a conversation entry — with a failed change surfaced as a toast instead.
+  Session and protocol failures are also toasts, beside the conversation rather than in it.
+- A tool call's diff or output is server-computed and shown on demand, preserving its observation
+  types, call identity and success or denial/failure through live delivery and replay. Resource references remain inert because
+  displaying a contributor's URI grants no read authority; unsupported media is explained rather than
+  silently discarded. Output is never recomputed here or buried behind a truncated path or argument; an internal signal tool never renders as a call,
+  and a projected `/command` tool shows the command it ran, not the provider-facing tool name.
+- A UI-intent opens its GUI screen when there is one — the session picker is the session sidebar
+  (unless the host cannot list sessions), settings and the plugin manager both open the Settings
+  modal (the plugin manager on its Plugins section), and the agent switcher is a sheet listing the
+  session's agent definitions with the current one checked. A command with no GUI path at all (its
+  presentation belongs to a terminal, or the product has deliberately left it out — see
+  `packages/agent-gui-web/docs/SPEC.md`) never reaches the session from this surface in the first
+  place: it is caught on the way out and answered with its own plain sentence naming what to use
+  instead. Any other UI-intent this surface simply has no screen for yet answers the same way, in its
+  own words — never the generic "not available on this surface" line, and never a silent no-op — in
+  place of the command's own reply when this surface's command awaits one, at once otherwise; an
+  intent kind not yet known when this package was written still gets an explicit, honest line.
+- The session sidebar lists the host's sessions by a stable title — never the latest reply, which
+  changes every turn — and never loses one silently: a record unreadable and belonging to this
+  workspace is folded into one plain line rather than shown as a row; a record belonging to another
+  workspace, or whose workspace cannot be told, is not this surface's business and is left off the
+  list entirely. A switch replaces everything the surface shows with what the new session holds; a
+  refused switch shows the host's reason. A row can be renamed or deleted from the list itself,
+  without switching to it first; a refusal states why.
+- The agent switcher's roster and current selection are a typed read (`get-agent-definitions`), but
+  choosing a row is not a dedicated write: it sends `/agent <name>` through the same `command` path
+  typing it would, and the sheet shows that command's own reply as a plain line — never a
+  conversation card, unlike every other command result this reducer renders.
+- The Agents panel's Scheduled group and Goal row are additive to the execution-workspace rail:
+  a schedule or a goal alone (no running background task or loop) still opens the rail, and a
+  schedule's Pause/Resume and Delete, and a goal's Cancel, run the same command/control paths their
+  slash commands already use — the panel adds no write this package did not already expose.
+- The title bar and the page title both name the workspace folder the session works in, once the
+  host has said one; the desktop window follows the page title.
+- A pending permission or ask prompt is visible whatever view is open, because a gated turn waits
+  on it. It never takes focus from a field the person is typing in, and its keys answer it only once
+  it has that focus; a click answers at once.
+- Nothing typed is lost to a lost connection: while the transport is not `connected`, the composer
+  keeps its draft and refuses to submit it, and a banner above the conversation — never a full-screen
+  replacement — says so: retrying while attempts continue, and once they give up, either the
+  host-supplied reconnect action or how to reopen the page.
+- A session-rename or history-clear broadcast from any other surface is folded into this reducer's
+  state, so co-driving surfaces stay in sync.
+- The personal usage dashboard is opt-in per surface (browser/remote consumers stay opted out by
+  default) and correlates its own requests, keeping latest-request-wins semantics on responses.
+- A background-activity entry opens a detail sheet (status, what it was asked, its paginated
+  transcript, its result) on click — except the main-thread entry, which instead returns to the
+  conversation already shown beside it. A stoppable entry's Stop is routed by whether the entry
+  carries a loop id, never guessed from its name or task kind: a `/loop`-managed entry (fixed or
+  self-paced) sends `/loop stop <id>`, because a self-paced loop's own background-task
+  representation, when it has one, is only its disposable wake timer — cancelling that would leave
+  the loop itself running. Every other entry sends `cancel-background-task`.
+- The Project panel (git status, one file's diff, project memory) correlates its own requests the
+  same way, and every file status it shows is a plain word, never a raw git XY code (#3277 "usable by
+  anyone"); a workspace that is not a git repository, or a diff whose path the host refused, is one
+  plain sentence, never left as a stuck loading state.
+- A session error finalizes any partial streamed text and clears thinking/running-tool state
+  before the next turn begins.
+- Malformed server frames are surfaced through the client's callback path and never thrown inside
+  the socket handler.
+- The package ships no compiled CSS — it authors Tailwind utility classes as source, and the
+  consumer owns the Tailwind entry point that compiles them. Its design applies only inside the
+  `agent-ui` scope that each of its root components opens, so a host with tokens of its own under the
+  same names can embed the surface without either overriding the other.
+- Its public browser entry exposes a narrow runtime-host contract: a native host owns trust and
+  endpoint authority, while a renderer can ask for trust before connecting, observe lifecycle
+  changes, and offer reconnect without importing the native implementation.
+
+## Non-goals / boundaries
+
+- Does not own the wire protocol framing (message types) — that belongs to the transport package.
+- Does not own the transport-facing contract types (interaction/event/workspace) — those belong to
+  the transport-interface package.
+- Does not own session/runtime contracts or agent-core types, and has no dependency on the
+  agent framework, session, or core packages.
+- Does not own the CLI sidecar server.
+- Does not own the WebRTC remote peer or pairing flow — that is a separate package that consumes
+  this package's reducer and components and widens the status union.
+- Does not own the Electron shell or sidecar process supervision — that is the desktop app.
+- Is not re-exported through a sibling product package; consumers import it directly.
+
+## Design decisions
+
+- The reducer is generic over its status type rather than importing a widened status union from
+  the WebRTC package, because importing that union would create a package cycle.
+- The session shell component holds no session/transport logic of its own — it only forwards user
+  intent through the reducer's send/answer handles — so a new GUI surface can reuse it purely by
+  supplying its own client factory.
+- There is deliberately no built-in screen for every UI-intent kind; unhandled kinds get an
+  explicit notice instead of a screen, so a future surface can add a real screen incrementally
+  without ever risking a silent drop in the meantime.

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@robota-sdk/agent-ui-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.0-beta.94",
+  "description": "Browser-safe React session presentation, wire reducer, WebSocket client and runtime-host contract for consumer-owned agent renderers.",
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": {
+        "types": "./dist/node/index.d.ts",
+        "default": "./dist/node/index.js"
+      },
+      "require": {
+        "types": "./dist/node/index.d.cts",
+        "default": "./dist/node/index.cjs"
+      },
+      "default": "./dist/node/index.js"
+    },
+    "./client": {
+      "source": "./src/index.ts",
+      "import": {
+        "types": "./dist/browser/index.d.ts",
+        "default": "./dist/browser/index.js"
+      },
+      "default": "./dist/browser/index.js"
+    },
+    "./styles/theme.css": {
+      "types": "./src/styles/theme.css.d.mts",
+      "browser": "./src/styles/theme.css",
+      "import": "./src/styles/theme.css"
+    },
+    "./styles/surface.css": {
+      "types": "./src/styles/surface.css.d.mts",
+      "browser": "./src/styles/surface.css",
+      "import": "./src/styles/surface.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__/**",
+    "!src/testing/**",
+    "README.md",
+    "docs/README.md",
+    "docs/SPEC.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "lucide-react": "^1.26.0",
+    "pretendard": "^1.3.9",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.94",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.94",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.94",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.94",
+    "@robota-sdk/agent-transport": "3.0.0-beta.94"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^25.0.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "rimraf": "^5.0.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota"
+  },
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "homepage": "https://robota.io/",
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "clean": "rimraf dist"
+  }
 }

package/src/client/runtime-host.ts

@@ -0,0 +1,84 @@
+import type { IPickedFile } from '../components/Composer.js';
+
+/** Runtime events delivered by a native host. Browser pages have no process to supervise. */
+export type TClientRuntimeState = 'starting' | 'ready' | 'fatal';
+
+/** A folder decision must be shown before requesting the runtime endpoint. */
+export interface IClientTrustQuestion {
+  readonly folder: string;
+  readonly loads: readonly string[];
+}
+
+export type TClientTrustChoice = 'trust' | 'restricted' | 'quit';
+
+/**
+ * Browser-safe shape for a narrow native preload bridge. The native host implements validation,
+ * trust, process lifecycle, and endpoint ownership; the renderer receives only these operations.
+ */
+export interface IClientRuntimeBridge {
+  readonly runtimeMode?: 'local' | 'remote';
+  getEndpoint(): Promise<string | null>;
+  signalReady(): void;
+  onState(listener: (state: TClientRuntimeState, detail?: string) => void): () => void;
+  restartRuntime(): Promise<void>;
+  trustQuestion(): Promise<IClientTrustQuestion | null>;
+  answerTrust(choice: TClientTrustChoice): Promise<{ error?: string }>;
+  pickFiles?(): Promise<readonly IPickedFile[]>;
+  getPathForFile?(file: File): string;
+  onOpenSettings?(listener: () => void): () => void;
+  openPath?(path: string): Promise<{ error?: string }>;
+}
+
+/** A React renderer can use this contract with either a desktop bridge or a browser endpoint. */
+export interface IClientRuntimeHost {
+  readonly kind: 'desktop' | 'browser';
+  getEndpoint(): Promise<string | null>;
+  signalReady(): void;
+  onState(listener: (state: TClientRuntimeState, detail?: string) => void): () => void;
+  readonly restartRuntime?: () => Promise<void>;
+  readonly trustQuestion?: () => Promise<IClientTrustQuestion | null>;
+  readonly answerTrust?: (choice: TClientTrustChoice) => Promise<{ error?: string }>;
+  readonly pickFiles?: () => Promise<readonly IPickedFile[]>;
+  readonly getPathForFile?: (file: File) => string;
+  onOpenSettings(listener: () => void): () => void;
+  readonly openMemoryInEditor?: (path: string) => void;
+}
+
+export interface IClientRuntimeEnvironment {
+  readonly bridge?: IClientRuntimeBridge;
+  readonly document: Pick<Document, 'querySelector'>;
+  readonly location: Pick<Location, 'search' | 'host' | 'protocol'>;
+}
+
+/** Resolve host capabilities without importing Electron or a Node CLI into the browser graph. */
+export function resolveClientRuntimeHost(environment: IClientRuntimeEnvironment): IClientRuntimeHost {
+  const { bridge } = environment;
+  if (bridge) {
+    const local = bridge.runtimeMode !== 'remote';
+    return {
+      kind: 'desktop',
+      getEndpoint: () => bridge.getEndpoint(),
+      signalReady: () => bridge.signalReady(),
+      onState: (listener) => bridge.onState(listener),
+      restartRuntime: () => bridge.restartRuntime(),
+      trustQuestion: local ? () => bridge.trustQuestion() : undefined,
+      answerTrust: local ? (choice) => bridge.answerTrust(choice) : undefined,
+      pickFiles: local && bridge.pickFiles ? () => bridge.pickFiles!() : undefined,
+      getPathForFile: local && bridge.getPathForFile ? (file) => bridge.getPathForFile!(file) : undefined,
+      onOpenSettings: (listener) => bridge.onOpenSettings?.(listener) ?? (() => {}),
+      openMemoryInEditor: local && bridge.openPath ? (path) => { void bridge.openPath!(path); } : undefined,
+    };
+  }
+
+  const injected = environment.document.querySelector('meta[name="ws-url"]')?.getAttribute('content')?.trim();
+  const query = new URLSearchParams(environment.location.search).get('ws')?.trim();
+  const protocol = environment.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  const endpoint = injected || query || `${protocol}//${environment.location.host}`;
+  return {
+    kind: 'browser',
+    getEndpoint: async () => endpoint,
+    signalReady: () => {},
+    onState: () => () => {},
+    onOpenSettings: () => () => {},
+  };
+}

package/src/client/ws-session-client.ts

@@ -0,0 +1,131 @@
+/**
+ * Browser WebSocket client for a running agent-cli sidecar session.
+ * Wraps the native WebSocket API with typed agent-transport-ws messages.
+ */
+
+import { decodeFrame, decodeServerMessage } from '@robota-sdk/agent-transport/client';
+
+import type { TServerMessage, TClientMessage } from '@robota-sdk/agent-transport';
+
+export type { TServerMessage, TClientMessage };
+
+export type TConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+export interface IWsSessionClientCallbacks {
+  onMessage: (msg: TServerMessage) => void;
+  onStatusChange: (status: TConnectionStatus) => void;
+  /**
+   * The connection is gone for good: the retries ran out without reaching the server again. The status
+   * stays `disconnected`; this is what tells a host the runtime is not coming back by itself.
+   */
+  onGiveUp?: () => void;
+}
+
+export interface IWsSessionClient {
+  connect: () => void;
+  disconnect: () => void;
+  send: (msg: TClientMessage) => void;
+  status: () => TConnectionStatus;
+}
+
+const RECONNECT_DELAY_MS = 2000;
+const MAX_RECONNECT_ATTEMPTS = 10;
+
+export function createWsSessionClient(
+  url: string,
+  callbacks: IWsSessionClientCallbacks,
+): IWsSessionClient {
+  let ws: WebSocket | null = null;
+  let currentStatus: TConnectionStatus = 'disconnected';
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectAttempts = 0;
+  let intentionalDisconnect = false;
+
+  function setStatus(s: TConnectionStatus): void {
+    currentStatus = s;
+    callbacks.onStatusChange(s);
+  }
+
+  function scheduleReconnect(): void {
+    if (intentionalDisconnect) return;
+    if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      callbacks.onGiveUp?.();
+      return;
+    }
+    reconnectTimer = setTimeout(() => {
+      reconnectAttempts++;
+      doConnect();
+    }, RECONNECT_DELAY_MS);
+  }
+
+  function doConnect(): void {
+    setStatus('connecting');
+    ws = new WebSocket(url);
+
+    ws.onopen = (): void => {
+      reconnectAttempts = 0;
+      setStatus('connected');
+      // Request full message history on connect
+      send({ type: 'get-messages' });
+    };
+
+    ws.onmessage = (event: MessageEvent): void => {
+      const data = event.data;
+      if (typeof data !== 'string') return;
+      // Issue #2045: `raw → owner decoder → typed`. A malformed frame (invalid JSON or an invalid
+      // shape) must not throw inside the handler (it would break the socket's message pump and
+      // freeze the UI) and must not be cast onward; surface it via the normal path.
+      const decoded = decodeFrame(data, decodeServerMessage);
+      if (!decoded.ok) {
+        callbacks.onMessage({
+          type: 'protocol_error',
+          message: `Malformed message from server (${decoded.reason})`,
+        });
+        return;
+      }
+      callbacks.onMessage(decoded.message);
+    };
+
+    ws.onclose = (): void => {
+      ws = null;
+      if (!intentionalDisconnect) {
+        setStatus('disconnected');
+        scheduleReconnect();
+      } else {
+        setStatus('disconnected');
+      }
+    };
+
+    ws.onerror = (): void => {
+      setStatus('error');
+    };
+  }
+
+  function connect(): void {
+    intentionalDisconnect = false;
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    doConnect();
+  }
+
+  function disconnect(): void {
+    intentionalDisconnect = true;
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    ws?.close();
+    ws = null;
+    setStatus('disconnected');
+  }
+
+  function send(msg: TClientMessage): void {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+
+  return { connect, disconnect, send, status: () => currentStatus };
+}

package/src/clipboard.ts

@@ -0,0 +1,81 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Copies `text` to the clipboard for the "Copy code" / "Copy message" buttons (#3289 §2): the async
+ * Clipboard API first, and — for a page that denies it (no permission granted yet, a browser that
+ * never implements it, or a context that disallows it outright) — a same-tick `execCommand('copy')`
+ * fallback through a throwaway, invisible textarea. Rejects only once both have failed, so a caller
+ * can show its own "Couldn't copy" message rather than a browser one.
+ */
+export async function copyToClipboard(text: string): Promise<void> {
+  if (navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return;
+    } catch {
+      // Falls through to the legacy path — some browsers reject outside a user gesture, or before a
+      // permission prompt has ever been answered.
+    }
+  }
+  if (!legacyCopy(text)) throw new Error('copy failed');
+}
+
+/**
+ * `execCommand('copy')` needs a selection in the page, so the text is staged in an offscreen field —
+ * which needs focus to be selectable, so whatever had focus (typically the "Copy code" / "Copy
+ * message" button a keyboard user just activated) is restored afterward rather than left on `<body>`.
+ */
+function legacyCopy(text: string): boolean {
+  if (typeof document === 'undefined' || typeof document.execCommand !== 'function') return false;
+  const previouslyFocused =
+    document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  const field = document.createElement('textarea');
+  field.value = text;
+  field.setAttribute('readonly', '');
+  field.style.position = 'fixed';
+  field.style.top = '0';
+  field.style.left = '0';
+  field.style.opacity = '0';
+  field.style.pointerEvents = 'none';
+  document.body.appendChild(field);
+  field.focus();
+  field.select();
+  let ok = false;
+  try {
+    ok = document.execCommand('copy');
+  } catch {
+    ok = false;
+  }
+  document.body.removeChild(field);
+  previouslyFocused?.focus();
+  return ok;
+}
+
+export type TCopyStatus = 'idle' | 'copied' | 'error';
+
+/** How long the "Copied" / "Couldn't copy" feedback holds before the button reads its normal label again. */
+const FEEDBACK_MS = 2000;
+
+/**
+ * The "Copy code" / "Copy message" buttons' shared feedback state: `copied` or `error` for a couple of
+ * seconds, then back to `idle` — drives both the button's own label swap and an `aria-live` region a
+ * screen reader announces without moving focus (#3289 §2).
+ */
+export function useCopyFeedback(): { status: TCopyStatus; copy: (text: string) => void } {
+  const [status, setStatus] = useState<TCopyStatus>('idle');
+
+  useEffect(() => {
+    if (status === 'idle') return undefined;
+    const timer = setTimeout(() => setStatus('idle'), FEEDBACK_MS);
+    return () => clearTimeout(timer);
+  }, [status]);
+
+  const copy = (text: string): void => {
+    copyToClipboard(text).then(
+      () => setStatus('copied'),
+      () => setStatus('error'),
+    );
+  };
+
+  return { status, copy };
+}