@alexkroman1/aai-ui 0.12.3 → 0.14.0

package/dist/components/tool-call-block.js

@@ -1,118 +1,3 @@
-import { BoltIcon, ChatBubbleIcon, DownloadIcon, ExternalLinkIcon, SearchIcon, TerminalIcon } from "./tool-icons.js";
-import clsx from "clsx";
-import { useComputed, useSignal } from "@preact/signals";
-import { jsx, jsxs } from "preact/jsx-runtime";
-//#region components/tool-call-block.tsx
-const argField = (key) => (args) => String(args[key] ?? "");
-const TOOL_CONFIG = {
-	web_search: {
-		Icon: SearchIcon,
-		title: "Web Search",
-		subtitle: argField("query")
-	},
-	visit_webpage: {
-		Icon: ExternalLinkIcon,
-		title: "Visit Page",
-		subtitle: argField("url")
-	},
-	run_code: {
-		Icon: TerminalIcon,
-		title: "Run Code",
-		subtitle: (args) => {
-			const firstLine = String(args.code ?? "").split("\n")[0] ?? "";
-			return firstLine.length > 80 ? `${firstLine.slice(0, 80)}...` : firstLine;
-		}
-	},
-	fetch_json: {
-		Icon: DownloadIcon,
-		title: "Fetch JSON",
-		subtitle: argField("url")
-	},
-	user_input: {
-		Icon: ChatBubbleIcon,
-		title: "Asking User",
-		subtitle: argField("question")
-	}
-};
-const DEFAULT_CONFIG = {
-	Icon: BoltIcon,
-	title: "",
-	subtitle: (args) => {
-		const summary = JSON.stringify(args);
-		return summary.length > 80 ? `${summary.slice(0, 80)}...` : summary;
-	}
-};
-function formatResult(result) {
-	try {
-		return JSON.stringify(JSON.parse(result), null, 2);
-	} catch {
-		return result;
-	}
-}
-/**
-* Renders a tool invocation with an icon, title, subtitle, and a
-* collapsible result viewer.
-*
-* Built-in tool types (`web_search`, `visit_webpage`, `run_code`,
-* `fetch_json`, `user_input`) get custom icons and labels. Unknown tools
-* fall back to a generic bolt icon.
-*
-* While the tool call is pending a shimmer animation is shown. Once
-* complete, clicking the block expands the formatted JSON result.
-*
-* @example
-* ```tsx
-* <ToolCallBlock toolCall={toolCall} />
-* ```
-*
-* @param toolCall - The tool call to render (see {@link ToolCallInfo}).
-* @param className - Additional CSS class names.
-*
-* @public
-*/
-function ToolCallBlock({ toolCall, className }) {
-	const isOpen = useSignal(false);
-	const config = TOOL_CONFIG[toolCall.toolName] ?? DEFAULT_CONFIG;
-	const isPending = toolCall.status === "pending";
-	const title = config.title || toolCall.toolName;
-	const canExpand = !isPending && Boolean(toolCall.result);
-	const formatted = useComputed(() => toolCall.result ? formatResult(toolCall.result) : "");
-	return /* @__PURE__ */ jsxs("div", {
-		class: clsx("flex flex-col", className),
-		children: [/* @__PURE__ */ jsxs("button", {
-			type: "button",
-			"aria-expanded": canExpand ? isOpen.value : void 0,
-			disabled: isPending,
-			class: clsx("flex items-center gap-2 px-3 py-2 rounded-aai border border-aai-border bg-aai-surface-faint select-none text-left w-full", canExpand && "cursor-pointer"),
-			onClick: () => {
-				if (canExpand) isOpen.value = !isOpen.value;
-			},
-			children: [
-				/* @__PURE__ */ jsx(config.Icon, { class: "w-4 h-4 text-aai-text-dim shrink-0" }),
-				/* @__PURE__ */ jsx("span", {
-					class: clsx("text-sm font-medium text-aai-text", isPending && "tool-shimmer"),
-					children: title
-				}),
-				/* @__PURE__ */ jsx("span", {
-					class: "text-sm text-aai-text-dim truncate flex-1 min-w-0",
-					children: config.subtitle(toolCall.args)
-				}),
-				canExpand && /* @__PURE__ */ jsx("span", {
-					class: "text-xs text-aai-text-dim shrink-0",
-					children: isOpen.value ? "▾" : "▸"
-				})
-			]
-		}), isOpen.value && /* @__PURE__ */ jsxs("div", {
-			class: "border-x border-b border-aai-border rounded-b-aai bg-aai-surface max-h-64 overflow-auto",
-			children: [toolCall.toolName === "run_code" && toolCall.args.code && /* @__PURE__ */ jsx("pre", {
-				class: "text-xs text-aai-text p-2 whitespace-pre-wrap border-b border-aai-border font-mono",
-				children: String(toolCall.args.code)
-			}), formatted.value && /* @__PURE__ */ jsx("pre", {
-				class: "text-xs text-aai-text-dim p-2 whitespace-pre-wrap",
-				children: formatted.value
-			})]
-		})]
-	});
-}
-//#endregion
+import "../context.js";
+import { t as ToolCallBlock } from "../tool-call-block-uXtMOUWN.js";
 export { ToolCallBlock };

package/dist/components/tool-call-row.d.ts

@@ -0,0 +1,75 @@
+import { type ReactNode } from "react";
+/**
+ * Size preset for {@link ToolCallRow}: `"default"` is the deployed agent
+ * UI's scale, `"compact"` the studio transcript's denser one.
+ *
+ * @public
+ */
+export type ToolCallRowVariant = "default" | "compact";
+/**
+ * Props for {@link ToolCallRow}.
+ *
+ * @public
+ */
+export interface ToolCallRowProps {
+    /** Tool title, rendered in mono (shimmers while `pending`). */
+    title: ReactNode;
+    /** One-line detail (typically an args preview), truncated to the row. */
+    detail?: ReactNode | undefined;
+    /** True while the call is in flight — animates the title with a shimmer. */
+    pending?: boolean | undefined;
+    /** Optional icon rendered in place of the outlined "TOOL" chip. */
+    icon?: ReactNode | undefined;
+    /** Size preset; defaults to `"default"`. */
+    variant?: ToolCallRowVariant | undefined;
+    /** Additional CSS class names for the outer container. */
+    className?: string | undefined;
+    /**
+     * Expanded panel content. When present the row is expandable: a chevron is
+     * shown and clicking toggles the panel. When absent the row is inert (the
+     * button is disabled). Content provides its own padding and typography;
+     * the panel supplies the top border, surface background, and a max height.
+     */
+    children?: ReactNode;
+}
+/**
+ * The design system's console row for one tool invocation: a small outlined
+ * "TOOL" chip (or a custom `icon`), the tool title in mono, a truncated
+ * detail preview, and a rotating chevron that expands to the panel content.
+ *
+ * Purely presentational — callers own the mapping from their tool-call data
+ * to `title`/`detail`/`pending` and the expanded panel. The deployed agent
+ * UI's message list renders it via its tool-call block, and the studio's
+ * chat transcript renders it with `variant="compact"`, so the two surfaces
+ * read as one component.
+ *
+ * Colors come from the nearest theme context (see {@link useTheme}); without
+ * a provider the default AssemblyAI theme applies.
+ *
+ * @example
+ * ```tsx
+ * import { ToolCallRow, useSession } from "@alexkroman1/aai-ui";
+ *
+ * // A custom chrome's tool log, from the snapshot's own `toolCalls`.
+ * function ToolLog() {
+ *   const { toolCalls } = useSession();
+ *   return (
+ *     <div>
+ *       {toolCalls.map((call) => (
+ *         <ToolCallRow
+ *           key={call.callId}
+ *           title={call.name}
+ *           detail={call.result}
+ *           pending={call.status === "pending"}
+ *         />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link ToolCallRowProps}.
+ *
+ * @public
+ */
+export declare function ToolCallRow({ title, detail, pending, icon, variant, className, children, }: ToolCallRowProps): ReactNode;

package/dist/components/tool-config-context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Display configuration for a tool call in the UI.
+ *
+ * @public
+ */
+export type ToolDisplayConfig = Record<string, {
+    icon?: string;
+    label?: string;
+}>;
+/**
+ * Context for tool display configuration. Installed by `mountClient()` from
+ * `ClientConfig.tools`; the built-in components read it via `useToolConfig`.
+ *
+ * @internal
+ */
+export declare const ToolConfigContext: import("react").Context<ToolDisplayConfig>;
+/**
+ * Read tool display configuration from the nearest `ToolConfigContext.Provider`.
+ *
+ * @internal
+ */
+export declare function useToolConfig(): ToolDisplayConfig;

package/dist/components/upload-progress.d.ts

@@ -0,0 +1,76 @@
+import { type ReactNode } from "react";
+import type { UploadStatus } from "../use-workflow-form.ts";
+/**
+ * How far a form's files have got, rendered as a bar.
+ *
+ * The wait this covers is the one a run cannot describe: a workflow run does not
+ * EXIST until its input is stored, so from the moment a form is submitted until
+ * the last byte lands there is no run id, no status, and nothing for
+ * `<WorkflowProgress>` to read — which for a 200 MB recording is minutes of a
+ * page that looks stuck. `useWorkflowSubmit` reports the bytes as they go and
+ * this is what draws them.
+ *
+ * Three things it decides, so a page does not:
+ *
+ * - **It renders nothing when there is nothing to describe.** `upload` is
+ *   undefined before the first byte and again from the moment the last one
+ *   lands, so `<UploadProgressBar upload={upload} />` is correct unguarded and a
+ *   form with no files never shows a bar at all.
+ * - **An unknown total is INDETERMINATE, not zero.** A body whose length the
+ *   transport cannot state up front (see `UploadProgress.total`) has no honest
+ *   width, and a bar pinned at 0% reads as an upload that is not moving.
+ * - **The file is NAMED, and counted when there is more than one.** Files are
+ *   sent one after another, so a single bar otherwise appears to restart from
+ *   zero partway through with nothing to say why.
+ * - **A paused upload SAYS SO, rather than being a bar that stopped.** Those look
+ *   identical, which is the whole reason `UploadStatus.paused` exists, and the
+ *   fill stops animating so the difference is visible without reading.
+ *
+ * The pause control appears only when a handler for it is passed. That is not
+ * politeness about props: a button whose press does nothing is worse than no
+ * button, and a page holding an `upload` it did not produce (a saved status, a
+ * parent's state) has nothing to pause.
+ *
+ * @example
+ * ```tsx no-check
+ * import { Form, SubmitButton, UploadProgressBar, useWorkflowSubmit, WorkflowFields } from "@alexkroman1/aai-ui";
+ * import type { transcribe } from "./agent.ts";
+ *
+ * function TranscribeForm() {
+ *   const { submitForm, upload, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
+ *   return (
+ *     <Form onSubmit={submitForm} error={error}>
+ *       <WorkflowFields workflow="transcribe" />
+ *       <UploadProgressBar upload={upload} />
+ *       <SubmitButton pending={pending}>Transcribe</SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Progress-bar props.
+ *
+ * @public
+ */
+export declare function UploadProgressBar({ upload, onPause, onResume, className, }: {
+    /**
+     * What `useWorkflowSubmit` / `useWorkflowStream` report as `upload`.
+     * `undefined` renders nothing, so a page may pass its state straight through
+     * and never guard the element.
+     */
+    upload?: UploadStatus | undefined;
+    /**
+     * The hook's `pauseUpload`. **Pass it together with `onResume`** to get the
+     * pause control; pass neither for a bar that only reports. One without the
+     * other is a one-way door drawn as a toggle, so the control is hidden unless
+     * both are present.
+     */
+    onPause?: (() => void) | undefined;
+    /** The hook's `resumeUpload`. See `onPause` — the two travel together. */
+    onResume?: (() => void) | undefined;
+    /**
+     * **Replaces** the default classes rather than extending them, so a custom
+     * chrome is not fighting a default it did not ask for.
+     */
+    className?: string | undefined;
+}): ReactNode;

package/dist/components/url-chips.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The session's shareable UI URL — the page this UI is served from, what
+ * you'd send someone to talk to the agent.
+ *
+ * @internal
+ */
+export declare function UiUrlChip({ className }: {
+    className?: string | undefined;
+}): import("react").JSX.Element;
+/**
+ * The session's programmatic WebSocket endpoint — the URL a script or backend
+ * can connect to directly instead of using this UI.
+ *
+ * @internal
+ */
+export declare function ApiUrlChip({ className }: {
+    className?: string | undefined;
+}): import("react").JSX.Element;
+/**
+ * The UI and API URLs side by side. They answer the same question — "how do I
+ * reach this agent?" — so they belong together and each needs its label to be
+ * told apart. Rendered by the default shell in every session mode (S2S,
+ * pipeline).
+ *
+ * @internal
+ */
+export declare function SessionUrlChips({ className }: {
+    className?: string | undefined;
+}): import("react").JSX.Element;

package/dist/components/workflow-fields.d.ts

@@ -0,0 +1,46 @@
+import type { WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+/**
+ * Render one field per scalar property of a workflow's input schema.
+ *
+ * Pass the workflow's NAME and the schema is fetched here; pass a
+ * {@link WorkflowSummary} you already hold and nothing is fetched. The name form
+ * is the one a page usually wants — it is the same string the submit hook takes,
+ * and the alternative is three lines (`useWorkflows()`, a `.find()` by name, and
+ * folding that lookup's error into the form's) whose only product is this
+ * component's argument.
+ *
+ * Renders nothing when the workflow declared no schema — a workflow with no
+ * declared input takes anything, and a form for "anything" is not a form — and
+ * nothing while a named lookup is still in flight, so the hand-written fields
+ * beside it are not reordered when the schema lands.
+ *
+ * @example
+ * ```tsx no-check
+ * import { Form, SubmitButton, WorkflowFields, useWorkflowSubmit }
+ *   from "@alexkroman1/aai-ui";
+ * import type { transcribe } from "./agent.ts";
+ *
+ * function StartRun() {
+ *   const { submitForm, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
+ *   return (
+ *     <Form onSubmit={submitForm} error={error}>
+ *       <WorkflowFields workflow="transcribe" />
+ *       <SubmitButton pending={pending}>Transcribe</SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Field-set props.
+ *
+ * @public
+ */
+export declare function WorkflowFields({ workflow, }: {
+    /**
+     * The workflow whose input schema to render. A NAME is looked up here (one
+     * `GET workflows`); a {@link WorkflowSummary} the page already holds fetches
+     * nothing. `undefined` renders nothing, so a page may pass a selection
+     * straight through before one is made.
+     */
+    workflow?: WorkflowSummary | string | undefined;
+}): import("react").JSX.Element | null;

package/dist/components/workflow-pending-note.d.ts

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+import type { WorkflowRun } from "../workflow-client.ts";
+/**
+ * Props for {@link WorkflowPendingNote}.
+ *
+ * @public
+ */
+export type WorkflowPendingNoteProps = {
+    /**
+     * The submission the page is rendering — `useWorkflowSubmit`'s or
+     * `useWorkflowStream`'s result, or any object carrying these three fields.
+     * Nothing renders while `pending` is false.
+     */
+    submission: {
+        readonly pending: boolean;
+        readonly startedHere: boolean;
+        readonly run: WorkflowRun | undefined;
+    };
+    /**
+     * What the run produces, as the noun the sentences name: `"draft"`,
+     * `"summary"`, `"transcript"`. Default `"run"`.
+     */
+    subject?: string | undefined;
+    /**
+     * Where the key that finds the run again lives. `"tab"` (the default) is
+     * `useWorkflowSubmit`'s own `sessionStorage` key; `"browser"` is a page that
+     * passed `useRunKey({ storage: "local" })`, whose runs any tab on this browser
+     * can find — so the sentence says "this browser" and stops promising that
+     * closing the tab loses anything.
+     */
+    scope?: "tab" | "browser" | undefined;
+    /**
+     * ADDED to the note's own `text-sm opacity-70` rather than replacing it.
+     * There is no `tailwind-merge` in this package, so a class that CONFLICTS with
+     * a base one is not reliably the winner.
+     */
+    className?: string | undefined;
+};
+/**
+ * The one sentence a page says while a run is in flight — three situations,
+ * one line each — as a muted line under the form, and nothing otherwise.
+ *
+ * Six template pages had each written the function under this, byte-identical
+ * in control flow and different only in the noun, under a doc arguing the same
+ * two things. Both survive here, once:
+ *
+ * - **The reload case gets its own words.** `!startedHere && run` is a run in
+ *   front of somebody who did not press anything — a reload, or another tab on
+ *   the same key — and they are owed an explanation for work appearing, plus
+ *   the line that stops them starting it again. The sentence a page reaches for
+ *   instead ("you can close this tab") was true about the RUN and false about
+ *   the page for as long as a reload could not find its run.
+ * - **The lookup is a state, not an absence.** `!startedHere && !run` is the
+ *   stretch on a reload where the key is being resolved and an empty form would
+ *   read as "nothing is happening". It is the same length as the request.
+ *
+ * The render site had drifted too — three pages muted the line and two did not
+ * — so the typography is the component's, in the same `text-sm opacity-70`
+ * every other muted line on these pages uses.
+ *
+ * `startedHere`, `run` and `pending` are what {@link WorkflowSubmission}
+ * reports, which is why the prop is the submission itself rather than three
+ * booleans a page would re-derive. A page with a FOURTH situation — a run that a
+ * reload does not recover but ENDS, as `transcription-workflow`'s streaming
+ * flow has — writes its own sentence, and that template is the one doing so.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowSubmit, WorkflowPendingNote } from "@alexkroman1/aai-ui";
+ *
+ * function App() {
+ *   const submission = useWorkflowSubmit("redline");
+ *   return <WorkflowPendingNote submission={submission} subject="draft" />;
+ * }
+ * ```
+ *
+ * @param props - See {@link WorkflowPendingNoteProps}.
+ *
+ * @public
+ */
+export declare function WorkflowPendingNote({ submission, subject, scope, className, }: WorkflowPendingNoteProps): ReactNode;

package/dist/components/workflow-progress.d.ts

@@ -0,0 +1,81 @@
+import { type ReactNode } from "react";
+import type { WorkflowApi } from "../workflow-client.ts";
+/**
+ * What a run has said so far, rendered.
+ *
+ * The complement of a status line, and the reason both exist: a run is
+ * `running` for its whole life, so a one-round job and a ten-round one look
+ * identical while they happen. These lines come from the run itself (`stepReport()`
+ * in a `"use step"` body), which is the only channel a workflow has before it
+ * produces an output.
+ *
+ * Four rules are baked in, and they are why this is a component rather than
+ * three lines each page writes for itself — the two templates that had written
+ * it had written three of them, comments included:
+ *
+ * - **It renders nothing until there is something to render.** `supported` is
+ *   what keeps this from being an empty box forever on an agent deployed before
+ *   progress streams existed: "wrote nothing yet" and "serves no stream" are
+ *   indistinguishable from the chunk list alone.
+ * - **The lines are TEXT, not elements.** They are append-only and two rounds
+ *   legitimately produce identical text, so there is no stable per-line key to
+ *   give React. Joining sidesteps the question instead of suppressing the lint
+ *   rule that asks it.
+ * - **They REPLAY.** Chunks are retained with the run, so a reload mid-run —
+ *   or opening a finished run tomorrow — shows how it got there rather than an
+ *   empty box. That is `useWorkflowProgress`'s doing; this is what makes it
+ *   visible.
+ * - **They are ANNOUNCED**, for the reason the first paragraph gives: this is
+ *   the only channel a run has before it produces an output, and a `<pre>` that
+ *   grows is a silent one. A screen-reader user pressing "Digest" got nothing
+ *   between the click and a terminal state minutes later — no "fetching", no
+ *   "summarising", no evidence the button did anything. See `role="log"` below.
+ *   The six pages that render this pass only `className`, so no template could
+ *   have fixed it locally; that is what makes it this component's job.
+ *
+ * @example
+ * ```tsx
+ * import { WorkflowProgress } from "@alexkroman1/aai-ui";
+ *
+ * function RunPanel({ runId }: { runId: string }) {
+ *   return <WorkflowProgress runId={runId} />;
+ * }
+ * ```
+ *
+ * @param props - Progress-log props.
+ *
+ * @public
+ */
+export declare function WorkflowProgress({ runId, api, className, placeholder, lines, }: {
+    /**
+     * The run to read. `undefined` renders nothing, so a page may pass its state
+     * straight through before a run exists.
+     */
+    runId?: string | undefined;
+    /**
+     * The workflow API client, when the page holds its own. Defaults to the
+     * lazily-built one every workflow hook shares.
+     */
+    api?: WorkflowApi | undefined;
+    /**
+     * **Replaces** the default classes rather than extending them, so a custom
+     * chrome is not fighting a default it did not ask for.
+     */
+    className?: string | undefined;
+    /**
+     * Rendered instead of nothing while the run has said nothing yet — for a
+     * page that would otherwise reflow when the first line lands.
+     */
+    placeholder?: ReactNode | undefined;
+    /**
+     * How many of the newest lines to show. Undefined (the default) shows the
+     * whole log; `1` is the newest line only.
+     *
+     * A run's narration is append-only and unbounded, so a page with a fixed slot
+     * for it — a status strip, a card footer — wants a window rather than a log.
+     * `0` renders the placeholder, which is the consistent reading of "show none"
+     * and the one that keeps a computed `lines` from silently rendering
+     * everything.
+     */
+    lines?: number | undefined;
+}): ReactNode;

package/dist/components/workflow-run-error.d.ts

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+import type { WorkflowRun } from "../workflow-client.ts";
+/**
+ * Props for {@link WorkflowRunError}.
+ *
+ * @public
+ */
+export type WorkflowRunErrorProps = {
+    /** The run the page is following. Nothing renders unless it has FAILED. */
+    run: WorkflowRun | undefined;
+    /**
+     * ADDED to the alert's own `text-red-600` rather than replacing it. There is
+     * no `tailwind-merge` in this package, so a class that CONFLICTS with a base
+     * one is not reliably the winner.
+     */
+    className?: string | undefined;
+};
+/**
+ * The announced line for a run that failed: its error, or nothing at all while
+ * the run is anything else.
+ *
+ * Six workflow pages had written this paragraph by hand, and the one thing that
+ * mattered about it was the part a reviewer cannot see is missing:
+ * `role="alert"`. A run fails minutes after the reader looked away — days, for
+ * a scheduled one — and `<Form>` announces only the SUBMIT error, so without
+ * the role a screen reader is never told the outcome it waited for arrived.
+ * Three of the six also disagreed on the sentence ("That one failed", "That run
+ * failed", the bare message), which is the drift a component ends.
+ *
+ * Discriminated on `status`, so `error` is reachable without a cast — the
+ * reason {@link WorkflowRun} is a union rather than a flat object with optional
+ * fields.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowSubmit, WorkflowRunError } from "@alexkroman1/aai-ui";
+ *
+ * function App() {
+ *   const { run } = useWorkflowSubmit("digest");
+ *   return <WorkflowRunError run={run} />;
+ * }
+ * ```
+ *
+ * @param props - See {@link WorkflowRunErrorProps}.
+ *
+ * @public
+ */
+export declare function WorkflowRunError({ run, className }: WorkflowRunErrorProps): ReactNode;

package/dist/components/workflow-run-panel.d.ts

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+import type { WorkflowRunStatus } from "../workflow-client.ts";
+import { type WorkflowApi, type WorkflowRun } from "../workflow-client.ts";
+/**
+ * Props of {@link WorkflowRunPanel}.
+ *
+ * @typeParam O - The run's output type; `run.output` narrows to it in the
+ * completed slot.
+ *
+ * @public
+ */
+export type WorkflowRunPanelProps<O> = {
+    /** The run to show. Nothing here handles `undefined` — a page renders the panel once it has one. */
+    run: WorkflowRun<O>;
+    /**
+     * The status lines this page has a better word for — `{ running:
+     * "Writing…" }`. The rest come from {@link WORKFLOW_STATUS_LABELS}.
+     */
+    statusLabels?: Partial<Readonly<Record<WorkflowRunStatus, string>>> | undefined;
+    /** Renders a Clear button in the header that calls this. Absent, no button. */
+    onClear?: (() => void) | undefined;
+    /** The workflow API client, when the page holds its own. */
+    api?: WorkflowApi | undefined;
+    /**
+     * Rendered beneath the narration while the run is NOT terminal — a live
+     * transcript, a partial result. Nothing once it settles.
+     */
+    live?: ReactNode | undefined;
+    /**
+     * The completed body: what the run PRODUCED. A function receives the typed
+     * output; a node is rendered as it is. Either appears only while
+     * `run.status === "completed"`.
+     */
+    children?: ReactNode | ((output: O) => ReactNode) | undefined;
+    /** Additional CSS class names for the wrapping `<section>`, appended to its own. */
+    className?: string | undefined;
+};
+/**
+ * The bordered panel a workflow page shows one run in: a status line, a Clear
+ * button, the run's own narration, the live slot while it works, the completed
+ * body once it has, and the announced error if it failed.
+ *
+ * Two pages had written this shell — `document-redline-workflow` and `transcription-workflow` —
+ * with the same header, the same `text-xs underline` Clear, the same
+ * {@link WorkflowProgress} under it, the same `run.status === "completed"`
+ * discrimination above the same {@link WorkflowRunError}, and each spread
+ * {@link WORKFLOW_STATUS_LABELS} into a local map to change `running`. The
+ * ORDER is the part worth owning: the narration is the complement of the status
+ * line (a run is `running` for its whole life, so a one-round job and a
+ * ten-round one look identical without it), and the error goes last because it
+ * is the outcome the reader waited minutes for.
+ *
+ * `children` is discriminated on the run for the caller, so the body reads
+ * `run.output` typed, without a cast and without the page repeating the guard —
+ * the reason {@link WorkflowRun} is a union rather than a flat object with
+ * optional fields.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowRun, WorkflowRunPanel } from "@alexkroman1/aai-ui";
+ *
+ * // `useWorkflowRun<R>` is where a page names the output's shape; a page that
+ * // started the run itself has it typed already, from `useWorkflowSubmit<D>`.
+ * function Panel({ runId, onClear }: { runId: string; onClear: () => void }) {
+ *   const { run } = useWorkflowRun<{ draft: string }>(runId);
+ *   if (!run) return null;
+ *   return (
+ *     <WorkflowRunPanel run={run} statusLabels={{ running: "Writing…" }} onClear={onClear}>
+ *       {(output) => <article className="whitespace-pre-wrap">{output.draft}</article>}
+ *     </WorkflowRunPanel>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link WorkflowRunPanelProps}.
+ *
+ * @public
+ */
+export declare function WorkflowRunPanel<O = unknown>({ run, statusLabels, onClear, api, live, children, className, }: WorkflowRunPanelProps<O>): ReactNode;