@alexkroman1/aai-ui 6.11.0 → 7.0.0

package/dist/index.js

@@ -1,23 +1,23 @@
-import { i as loadClientConfig, n as buildAgentUrl, r as fetchClientConfig, t as createSessionCore } from "./session-core-CAfYmUbg.js";
-import { n as Markdown, r as AutoScroll, t as MessageList } from "./message-list-CpPV7dGx.js";
-import { SessionProvider, ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
+import { n as fetchClientConfig } from "./client-config-B4nznRvH.js";
+import { a as useUserTranscript, i as TRANSCRIBING_PLACEHOLDER, n as Markdown, o as AutoScroll, r as useConversation, t as MessageList } from "./message-list-DHddO4QC.js";
+import { ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
 import { r as inkTint } from "./_colors-CcAi2FOU.js";
 import { Button } from "./components/button.js";
-import { t as ChatView } from "./chat-view-ByQFf94G.js";
+import { n as ConsoleShell, t as ChatView } from "./chat-view-BKsFfFZJ.js";
 import { n as setPageTitle, t as pageBaseUrl } from "./_utils-B6498_bm.js";
-import { i as UiUrlChip, n as ApiUrlChip, r as SessionUrlChips, t as Controls } from "./controls-CjG91QJ4.js";
-import { n as ToolConfigContext, r as ToolCallRow } from "./tool-call-block-D6pTEPrT.js";
+import { Controls } from "./components/controls.js";
+import { n as ToolCallRow } from "./tool-call-block-DoF-cSIZ.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
+import { t as createSessionCore } from "./session-core-C2JtLArh.js";
 import { client, mountRoot, resolveContainer } from "./define-client.js";
 import { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.js";
 import clsx from "clsx";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { createContext, createElement, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
-import { errorMessage, isTerminal, isTerminal as isTerminal$1 } from "@alexkroman1/aai";
+import { errorMessage } from "@alexkroman1/aai";
 import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
-import { createWorkflowApiClient, readEventStream } from "@alexkroman1/aai/workflow-api";
+import { createWorkflowApiClient, isTerminal, isTerminal as isTerminal$1, readEventStream } from "@alexkroman1/aai/workflow-api";
 import { createEpoch } from "@alexkroman1/aai/internal";
 //#region components/_form-readiness.ts
 /**
@@ -200,104 +200,52 @@ function dataUrl(file) {
 	});
 }
 //#endregion
-//#region components/form.tsx
+//#region components/form-fields.tsx
 /** @jsxImportSource react */
 /**
-* Simple forms, for the pages that are not conversations.
-*
-* A workflow app's front door is a form: name a recording, upload a file, press
-* submit. Nothing here knew how to render one — the components in this package
-* are all about a live session (a transcript, a mic button, a tool-call row) —
-* so every such page started by hand-rolling labels, inputs, a submit button and
-* the value collection between them, and did it differently each time.
+* The controls a form is made of — the shell, the six fields, and the styling
+* they share.
 *
-* ## Values come off the DOM, not out of React state
+* Split out of `form.tsx` when that file crossed the repo's source-file line
+* cap; `form.tsx` re-exports every name here, so it stays the one import path
+* for everything a form needs and nothing a caller writes changed.
 *
-* {@link Form} reads its own `<form>` element on submit and builds one plain
-* object from the named controls. That is what makes a field here nothing more
-* than a styled `<input>`: no registration, no controlled-component ceremony,
-* and a plain `<input name="x">` a caller writes themselves works exactly like
-* the ones below.
+* ## Every field takes its element's own attributes
 *
-* It also means the values are TYPED rather than all-strings, which a
-* `new FormData(form)` cannot give: a number field yields a number, a checkbox a
-* boolean, an empty optional field nothing at all. That matters because these
-* values go straight into a workflow's input, where a zod schema is waiting —
-* `"3"` against `z.number()` is a rejected run, and the browser is the only
-* place that still knows the field was `type="number"`.
+* Each control is `FieldShell & Omit<…HTMLAttributes, "name" | "className">`,
+* so `required`, `placeholder`, `accept`, `min`/`max`, `aria-*` and the rest
+* pass straight through to the element. `name` and `className` are owned here:
+* `name` is the key the field contributes to {@link FormValues} and is put on
+* the control itself, and `className` styles the field's WRAPPER, the control
+* taking the shared styling below.
 *
-* ## A file field either describes a file or uploads it
-*
-* See {@link FileField}. A workflow input is journaled and replayed on every
-* resume, so file BYTES do not belong in it — `upload` is the field that sends
-* them somewhere a step can read them and contributes the handle instead.
+* Note this means the per-property doc comments on the intersections do not
+* reach the published reference — see "A memoized component must NAME its
+* props type" in `packages/aai-ui/CLAUDE.md` — which is why each component's
+* own description carries what a caller needs.
 */
 /**
-* A form that hands its values to `onSubmit` as one object.
+* Label + control + hint, in the layout every field here uses.
 *
-* Native validation still applies — a `required` field blocks the submit and the
-* browser says so, which is better than anything this could render.
+* Exported so a caller's own control gets the same shell rather than an
+* approximation of it.
 *
 * @example
 * ```tsx
-* import { Form, SubmitButton, TextField } from "@alexkroman1/aai-ui";
+* import { Field, Form } from "@alexkroman1/aai-ui";
 *
-* function NameForm() {
+* function ColorForm() {
 *   return (
-*     <Form onSubmit={(values) => console.log(values.topic)}>
-*       <TextField name="topic" label="Topic" required />
-*       <SubmitButton>Start</SubmitButton>
+*     <Form onSubmit={() => undefined}>
+*       <Field label="Accent" hint="Any CSS color." htmlFor="accent">
+*         <input id="accent" name="accent" type="color" />
+*       </Field>
 *     </Form>
 *   );
 * }
 * ```
 *
-* @public
-*/
-function Form({ onSubmit, error, children, className, ...rest }) {
-	const theme = useTheme();
-	const [busy, setBusy] = useState(false);
-	const { pending: fieldsPending, declare } = useFormReadiness();
-	return /* @__PURE__ */ jsxs("form", {
-		onSubmit: useCallback((event) => {
-			event.preventDefault();
-			if (busy || fieldsPending) return;
-			const form = event.currentTarget;
-			setBusy(true);
-			(async () => {
-				try {
-					await onSubmit(await collectValues(form));
-				} finally {
-					setBusy(false);
-				}
-			})();
-		}, [
-			busy,
-			fieldsPending,
-			onSubmit
-		]),
-		className: clsx("flex flex-col gap-5 font-aai", className),
-		...rest,
-		children: [/* @__PURE__ */ jsx("fieldset", {
-			disabled: busy || fieldsPending,
-			className: "contents",
-			children: /* @__PURE__ */ jsx(FormReadinessProvider, {
-				value: declare,
-				children
-			})
-		}), error !== void 0 && error !== "" && /* @__PURE__ */ jsx("p", {
-			role: "alert",
-			className: "text-sm",
-			style: { color: theme.primary },
-			children: error
-		})]
-	});
-}
-/**
-* Label + control + hint, in the layout every field here uses.
-*
-* Exported so a caller's own control gets the same shell rather than an
-* approximation of it.
+* @param props - Field-shell props.
 *
 * @public
 */
@@ -364,6 +312,11 @@ function useFileControlProps() {
 /**
 * A single-line text input.
 *
+* Accepts every `<input>` attribute except `name` and `className`, which this
+* component owns, plus the shared {@link FieldShell} props.
+*
+* @param props - {@link FieldShell} props plus `<input>` attributes.
+*
 * @public
 */
 function TextField({ name, label, hint, className, ...rest }) {
@@ -386,6 +339,12 @@ function TextField({ name, label, hint, className, ...rest }) {
 * A number input. Contributes a NUMBER to {@link FormValues}, or nothing when
 * left empty.
 *
+* Accepts every `<input>` attribute except `name`, `className` and `type`,
+* plus the shared {@link FieldShell} props — so `min`, `max` and `step` are
+* passed straight through.
+*
+* @param props - {@link FieldShell} props plus `<input>` attributes.
+*
 * @public
 */
 function NumberField({ name, label, hint, className, ...rest }) {
@@ -407,6 +366,11 @@ function NumberField({ name, label, hint, className, ...rest }) {
 /**
 * A multi-line text input.
 *
+* Accepts every `<textarea>` attribute except `name` and `className`, plus the
+* shared {@link FieldShell} props. `rows` defaults to 4.
+*
+* @param props - {@link FieldShell} props plus `<textarea>` attributes.
+*
 * @public
 */
 function TextAreaField({ name, label, hint, className, rows = 4, ...rest }) {
@@ -426,8 +390,19 @@ function TextAreaField({ name, label, hint, className, rows = 4, ...rest }) {
 	});
 }
 /**
-* A dropdown. Pass `options`, or `children` for full control over the
-* `<option>` elements.
+* A dropdown.
+*
+* `options` is the short form — a list of strings, or of
+* `{ value, label }` pairs when the two differ. Pass `children` instead for
+* full control over the `<option>` elements; `children` wins when both are
+* given.
+*
+* Otherwise accepts every `<select>` attribute except `name` and `className`,
+* plus the shared {@link FieldShell} props. Note `multiple` works and
+* contributes an ARRAY (`[]` when nothing is chosen).
+*
+* @param props - {@link FieldShell} props, `options`, and `<select>`
+* attributes.
 *
 * @public
 */
@@ -456,6 +431,12 @@ function SelectField({ name, label, hint, className, options, children, ...rest
 /**
 * A checkbox. Contributes a BOOLEAN to {@link FormValues}.
 *
+* Accepts every `<input>` attribute except `name`, `className` and `type`,
+* plus the shared {@link FieldShell} props. The label renders beside the box
+* rather than above it, so `hint` is the place for guidance.
+*
+* @param props - {@link FieldShell} props plus `<input>` attributes.
+*
 * @public
 */
 function CheckboxField({ name, label, hint, className, ...rest }) {
@@ -493,7 +474,16 @@ function CheckboxField({ name, label, hint, className, ...rest }) {
 *
 * **Without it the field describes the file and does not read it.** `read`
 * exists for the cases where the bytes really are small and really are the
-* input — a CSV of ids, a config — and the size is the author's to check.
+* input — a CSV of ids, a config — and the size is the author's to check. See
+* {@link FileRead} for the four values; `upload` is shorthand for
+* `read="upload"`.
+*
+* Otherwise accepts every `<input>` attribute except `name`, `className` and
+* `type`, plus the shared {@link FieldShell} props — so `accept` and
+* `multiple` are passed straight through.
+*
+* @param props - {@link FieldShell} props, `read`/`upload`, and `<input>`
+* attributes.
 *
 * @public
 */
@@ -515,20 +505,144 @@ function FileField({ name, label, hint, className, read = "none", upload = false
 		})
 	});
 }
+//#endregion
+//#region components/form.tsx
+/** @jsxImportSource react */
+/**
+* Simple forms, for the pages that are not conversations.
+*
+* A workflow app's front door is a form: name a recording, upload a file, press
+* submit. Nothing here knew how to render one — the components in this package
+* are all about a live session (a transcript, a mic button, a tool-call row) —
+* so every such page started by hand-rolling labels, inputs, a submit button and
+* the value collection between them, and did it differently each time.
+*
+* ## Values come off the DOM, not out of React state
+*
+* {@link Form} reads its own `<form>` element on submit and builds one plain
+* object from the named controls. That is what makes a field here nothing more
+* than a styled `<input>`: no registration, no controlled-component ceremony,
+* and a plain `<input name="x">` a caller writes themselves works exactly like
+* the ones below.
+*
+* It also means the values are TYPED rather than all-strings, which a
+* `new FormData(form)` cannot give: a number field yields a number, a checkbox a
+* boolean, an empty optional field nothing at all. That matters because these
+* values go straight into a workflow's input, where a zod schema is waiting —
+* `"3"` against `z.number()` is a rejected run, and the browser is the only
+* place that still knows the field was `type="number"`.
+*
+* ## A file field either describes a file or uploads it
+*
+* See {@link FileField}. A workflow input is journaled and replayed on every
+* resume, so file BYTES do not belong in it — `upload` is the field that sends
+* them somewhere a step can read them and contributes the handle instead.
+*/
+/**
+* A form that hands its values to `onSubmit` as one object.
+*
+* Native validation still applies — a `required` field blocks the submit and the
+* browser says so, which is better than anything this could render.
+*
+* @example
+* ```tsx
+* import { Form, SubmitButton, TextField } from "@alexkroman1/aai-ui";
+*
+* function NameForm() {
+*   return (
+*     <Form onSubmit={(values) => console.log(values.topic)}>
+*       <TextField name="topic" label="Topic" required />
+*       <SubmitButton>Start</SubmitButton>
+*     </Form>
+*   );
+* }
+* ```
+*
+* @param props - See {@link FormProps}. Every `<form>` attribute except
+* `onSubmit` and `className` is passed through.
+*
+* @public
+*/
+function Form({ onSubmit, error, children, className, ...rest }) {
+	const theme = useTheme();
+	const [busy, setBusy] = useState(false);
+	const { pending: fieldsPending, declare } = useFormReadiness();
+	return /* @__PURE__ */ jsxs("form", {
+		onSubmit: useCallback((event) => {
+			event.preventDefault();
+			if (busy || fieldsPending) return;
+			const form = event.currentTarget;
+			setBusy(true);
+			(async () => {
+				try {
+					await onSubmit(await collectValues(form));
+				} finally {
+					setBusy(false);
+				}
+			})();
+		}, [
+			busy,
+			fieldsPending,
+			onSubmit
+		]),
+		className: clsx("flex flex-col gap-5 font-aai", className),
+		...rest,
+		children: [/* @__PURE__ */ jsx("fieldset", {
+			disabled: busy || fieldsPending,
+			className: "contents",
+			children: /* @__PURE__ */ jsx(FormReadinessProvider, {
+				value: declare,
+				children
+			})
+		}), error !== void 0 && error !== "" && /* @__PURE__ */ jsx("p", {
+			role: "alert",
+			className: "text-sm",
+			style: { color: theme.primary },
+			children: error
+		})]
+	});
+}
 /**
 * The form's submit button, disabled and relabelled while a submit is in
 * flight.
 *
+* Accepts all standard `<button>` HTML attributes except `type` and `disabled`,
+* in addition to the props below — so `aria-label` on an icon-only submit,
+* `form`, `id`, `title` and `onClick` all work here exactly as they do on
+* {@link Button}. `type` and `disabled` stay owned: this component sets both
+* from `pending`, and letting a caller set either is how a form gets a submit
+* button that does not submit.
+*
+* @example
+* ```tsx
+* import { Form, SubmitButton, TextField } from "@alexkroman1/aai-ui";
+*
+* function Digest({ pending }: { pending: boolean }) {
+*   return (
+*     <Form onSubmit={() => undefined}>
+*       <TextField name="url" label="Link" required />
+*       <SubmitButton pending={pending} variant="secondary" size="lg">
+*         Summarize
+*       </SubmitButton>
+*     </Form>
+*   );
+* }
+* ```
+*
+* @param props - Button props.
+*
 * @public
 */
-function SubmitButton({ children, pending = false, pendingLabel = "Working…", size, className }) {
+function SubmitButton({ children, pending = false, pendingLabel = "Working…", size, variant, className, ...rest }) {
 	return /* @__PURE__ */ jsx(Button, {
 		type: "submit",
 		disabled: pending,
 		...omitUndefined({
 			size,
+			variant,
 			className
 		}),
+		...rest,
 		children: pending ? pendingLabel : children
 	});
 }
@@ -614,13 +728,7 @@ function formatBytes(bytes) {
 * }
 * ```
 *
-* @param upload - What `useWorkflowSubmit` reports. `undefined` renders nothing,
-*   so a page may pass its state straight through.
-* @param onPause - The hook's `pauseUpload`. Pass it together with `onResume` to
-*   get the control; pass neither for a bar that only reports.
-* @param onResume - The hook's `resumeUpload`.
-* @param className - Replaces the default classes rather than extending them,
-*   so a custom chrome is not fighting a default it did not ask for.
+* @param props - Progress-bar props.
 *
 * @public
 */
@@ -674,6 +782,44 @@ function UploadProgressBar({ upload, onPause, onResume, className }) {
 	});
 }
 //#endregion
+//#region _run-controls.ts
+/**
+* The two things a page does TO a run it started, bound to the run it has.
+*
+* `useWorkflowSubmit` and `useWorkflowStream` both hold a run id and neither
+* handed it back, so a page that wanted "send it now" or "stop" had to hold an
+* `api` of its own purely to write `api.wake(runId)` — which is the whole reason
+* the two raw-primitive template pages keep a client at module scope. That is a
+* page carrying the transport to make up for a hook withholding its own state.
+*
+* Both calls answer rather than fail when there is nothing to act on — `0`
+* sleeps ended, `false` this call did not end it — which is the SDK's own
+* contract for them (two tabs pressing Stop is ordinary), and it is what lets
+* the no-run case be the same answer rather than a special one a caller has to
+* branch on.
+*/
+/**
+* Bind `wake` and `cancel` to whatever run the hook is currently following.
+*
+* @param runId - The live run, or `undefined` before one exists.
+* @param getClient - The stable getter from `useWorkflowApiRef`.
+* @returns Two callbacks, stable while `runId` is.
+*
+* @internal
+*/
+function useRunControls(runId, getClient) {
+	return {
+		wake: useCallback(async () => {
+			if (runId === void 0) return 0;
+			return await getClient().wake(runId);
+		}, [runId, getClient]),
+		cancel: useCallback(async () => {
+			if (runId === void 0) return false;
+			return await getClient().cancel(runId);
+		}, [runId, getClient])
+	};
+}
+//#endregion
 //#region _upload-recall.ts
 /**
 * Where an upload's ID survives a page RELOAD.
@@ -1101,6 +1247,32 @@ async function uploadFiles(api, input, report, parallel, session) {
 //#endregion
 //#region workflow-client.ts
 /**
+* Browser client for the workflow HTTP API (`aai/host/workflow-api.ts`).
+*
+* This is the whole client half of a WORKFLOW APP: an agent whose front door is
+* a form rather than a microphone (`workflowApp()`) starts runs
+* here and watches them for the answer. It deliberately does NOT go through
+* `SessionCore` — there is no socket, no audio graph, and no session to resume.
+*
+* **The requests themselves are the SDK's now**
+* (`createWorkflowApiClient`, `@alexkroman1/aai/workflow-api`), and what is left
+* here is the one thing that is genuinely a BROWSER's: the default base URL.
+* Every route, every query, the 404-is-an-answer rule and the `wait` clamp were
+* written three times over — here, in the studio's Workflows card, and in
+* `aai workflow` — and the parts the copies disagreed on were exactly the ones a
+* reader cannot check by eye. The SDK module's doc carries that argument; this
+* file must not grow a second implementation of any of it.
+*
+* The one thing worth knowing before using it: **a run outlives the page.**
+* Starting one resolves as soon as the run is created, so `runId` is the only
+* handle that matters and it stays valid across a reload, a different device, or
+* `curl` — which is what makes `useWorkflowRun` a watch rather than a
+* subscription to something the page owns.
+*
+* The loop that keeps asking lives in `use-workflow-run.ts`, and the streaming
+* fast path under it in `workflow-events.ts`.
+*/
+/**
 * Create a workflow API client aimed at the agent serving this page.
 *
 * Hoist it out of the component that uses it. `useWorkflowRun` holds the client
@@ -1108,6 +1280,32 @@ async function uploadFiles(api, input, report, parallel, session) {
 * but a client built in render is still a new `fetch` closure every time and
 * reads as though it were free.
 *
+* @example
+* ```tsx
+* import { createWorkflowApi, useWorkflowRun } from "@alexkroman1/aai-ui";
+* import { useState } from "react";
+*
+* // Module scope, not render scope — see above.
+* const api = createWorkflowApi();
+*
+* function StartDigest() {
+*   const [runId, setRunId] = useState<string>();
+*   const { run } = useWorkflowRun(runId, { api });
+*   return (
+*     <button
+*       type="button"
+*       onClick={() => void api.start("digest", { url: "…" }).then(setRunId)}
+*     >
+*       {run ? run.status : "Start"}
+*     </button>
+*   );
+* }
+* ```
+*
+* @param opts - See {@link WorkflowApiOptions}. Both fields are optional; the
+* default base URL is the page's own origin and path.
+* @returns The call set — see {@link WorkflowApi}.
+*
 * @public
 */
 function createWorkflowApi(opts = {}) {
@@ -1365,10 +1563,45 @@ function pollUntilTerminal(getClient, runId, intervalMs, onRun, onError, onStopp
 * STOPS on a terminal status, so a finished run costs nothing; passing
 * `undefined` (nothing started yet) also costs nothing.
 *
+* @example
+* ```tsx
+* import type { ToolInputSchema, WorkflowDef } from "@alexkroman1/aai";
+* import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+* import { useWorkflowRun } from "@alexkroman1/aai-ui";
+*
+* // A real page writes `import type { digest } from "./agent.ts"`. Stood in
+* // for here so the example compiles on its own.
+* declare const digest: WorkflowDef<ToolInputSchema, Promise<{ points: string[] }>>;
+*
+* type Digest = WorkflowOutputOf<typeof digest>;
+*
+* function RunPanel({ runId }: { runId: string | undefined }) {
+*   // The type argument is what makes `run.output` a `Digest` below.
+*   const { run, error, polling } = useWorkflowRun<Digest>(runId);
+*   if (error !== undefined) return <p role="alert">{error}</p>;
+*   if (run?.status === "completed") {
+*     return (
+*       <ul>
+*         {run.output.points.map((point) => (
+*           <li key={point}>{point}</li>
+*         ))}
+*       </ul>
+*     );
+*   }
+*   return <p>{polling ? "Working…" : "Nothing running."}</p>;
+* }
+* ```
+*
 * @typeParam R - The workflow's output type. Supplying it is what makes
 *   `run.status === "completed"` narrow to a typed `run.output` instead of
 *   `unknown`. Derive it with `WorkflowOutputOf<typeof myWorkflow>` — a
 *   type-only import of `agent.ts` is erased, so it costs the bundle nothing.
+* @param runId - The run to watch. `undefined` costs nothing, so a page may
+*   pass its state straight through before a run exists.
+* @param opts - `api` when the page holds its own client; `intervalMs` to
+*   change the poll interval the stream falls back to.
+* @returns The latest snapshot, the last read's error, and whether the watch
+*   is still going — see {@link UseWorkflowRunResult}.
 *
 * @public
 */
@@ -1460,6 +1693,35 @@ function useWorkflowRun(runId, opts = {}) {
 * empty list — which renders as a form with no fields and reads as "this agent
 * declares no workflows" about an agent that was merely unreachable.
 *
+* @example
+* ```tsx
+* import { useWorkflows } from "@alexkroman1/aai-ui";
+*
+* // A page rendering its own chrome from the listing — a picker, say. A form
+* // for ONE workflow wants `<WorkflowFields workflow="name" />` instead,
+* // which does this lookup itself.
+* function WorkflowPicker({ onPick }: { onPick: (name: string) => void }) {
+*   const { workflows, loading, error } = useWorkflows();
+*   if (loading) return <p>Loading…</p>;
+*   if (error !== undefined) return <p role="alert">{error}</p>;
+*   return (
+*     <ul>
+*       {workflows.map((summary) => (
+*         <li key={summary.name}>
+*           <button type="button" onClick={() => onPick(summary.name)}>
+*             {summary.description ?? summary.name}
+*           </button>
+*         </li>
+*       ))}
+*     </ul>
+*   );
+* }
+* ```
+*
+* @param opts - See {@link UseWorkflowsOptions}.
+* @returns The listing, its loading flag and its failure — see
+* {@link UseWorkflowsResult}.
+*
 * @public
 */
 function useWorkflows(opts = {}) {
@@ -1530,6 +1792,7 @@ function useWorkflowSubmit(workflow, opts = {}) {
 		api,
 		intervalMs
 	}));
+	const { wake, cancel } = useRunControls(runId, getClient);
 	return {
 		submit: useCallback(async (input) => {
 			const client = getClient();
@@ -1569,6 +1832,8 @@ function useWorkflowSubmit(workflow, opts = {}) {
 			setStartError(void 0);
 			setUpload(void 0);
 		}, []),
+		wake,
+		cancel,
 		pauseUpload: useCallback(() => {
 			session.current?.gate.pause();
 			setUpload((current) => current ? {
@@ -1591,6 +1856,26 @@ function useWorkflowSubmit(workflow, opts = {}) {
 }
 //#endregion
 //#region components/workflow-fields.tsx
+/** @jsxImportSource react */
+/**
+* A form built from a workflow's declared input schema.
+*
+* `GET workflows` reports each workflow's `inputSchema` as JSON Schema — the
+* zod schema an author wrote in `agent.ts`, converted at listing time precisely
+* so a browser can read it. This is what reads it: one `<WorkflowFields>` and a
+* workflow's form matches its schema by construction, so adding a field to the
+* schema adds it to the page and nothing can drift.
+*
+* ## It covers SCALARS, and says so rather than guessing
+*
+* A string, number, integer, boolean or enum has one obvious control each. A
+* nested object or an array does not — every choice (a JSON textarea, a repeater,
+* a comma-separated string) is a guess about what the author meant, and a guess
+* that produces a value the schema then rejects is worse than no field at all.
+* So those are SKIPPED, and the fields for them are written by hand: every field
+* in this package is a plain named control, so a hand-written one composes with
+* a generated one inside the same {@link Form}.
+*/
 /**
 * Render one field per scalar property of a workflow's input schema.
 *
@@ -1622,6 +1907,8 @@ function useWorkflowSubmit(workflow, opts = {}) {
 * }
 * ```
 *
+* @param props - Field-set props.
+*
 * @public
 */
 function WorkflowFields({ workflow }) {
@@ -1946,24 +2233,17 @@ function useWorkflowProgress(runId, opts = {}) {
 * }
 * ```
 *
-* @param runId - The run to read. `undefined` renders nothing, so a page may
-*   pass its state straight through before a run exists.
-* @param api - The workflow API client, when the page holds its own. Defaults
-*   to the one `page()` installs.
-* @param className - Replaces the default classes rather than extending them,
-*   so a custom chrome is not fighting a default it did not ask for.
-* @param placeholder - Rendered instead of nothing while the run has said
-*   nothing yet — for a page that would otherwise reflow when the first line
-*   lands.
+* @param props - Progress-log props.
 *
 * @public
 */
-function WorkflowProgress({ runId, api, className, placeholder }) {
+function WorkflowProgress({ runId, api, className, placeholder, lines }) {
 	const { progress, streaming, supported } = useWorkflowProgress(runId, omitUndefined({ api }));
-	if (!supported || progress.length === 0) return placeholder ?? null;
+	const shown = lines === void 0 ? progress : progress.slice(Math.max(progress.length - lines, 0));
+	if (!supported || shown.length === 0) return placeholder ?? null;
 	return /* @__PURE__ */ jsxs("pre", {
 		className: clsx(className ?? "whitespace-pre-wrap border-l pl-4 text-xs opacity-70"),
-		children: [progress.join("\n"), streaming && "\n…"]
+		children: [shown.join("\n"), streaming && "\n…"]
 	});
 }
 //#endregion
@@ -2027,69 +2307,94 @@ function page(config) {
 	return mountRoot(container, createElement(ThemeProvider, { value: config.theme }, createElement(config.component)));
 }
 //#endregion
-//#region use-user-transcript.ts
-/**
-* `useUserTranscript` — what the caller is saying RIGHT NOW, read correctly.
-*
-* `SessionSnapshot.userTranscript` is `string | null`, and the two falsy values
-* mean different things:
-*
-* - `null` — nobody is speaking. There is no partial turn.
-* - `""` — speech HAS been detected and no words have come back yet. A live
-*   session sits here for a few hundred milliseconds at the start of every turn.
-*
-* Read as one falsy check, those collapse and the indicator never appears at the
-* start of a turn — which is the moment it is for. So every custom chrome writes
-* `transcript !== null && (transcript === "" ? "…" : transcript)`, three
-* templates did exactly that, and each one re-derived a protocol distinction
-* from the type rather than from anything that told them.
-*
-* This is the same distinction as two named booleans, so a component can say
-* what it means: render on `speaking`, show `text`, and use the SDK's own
-* placeholder when there is nothing to show yet.
-*/
-/**
-* Placeholder for "listening, no words yet" — the `""` case above.
-*
-* A one-character ellipsis rather than three dots, because it is read by a
-* screen reader as an ellipsis and it does not reflow the row when the first
-* real word replaces it.
-*
-* @public
-*/
-const TRANSCRIBING_PLACEHOLDER = "…";
-/**
-* Subscribe to the caller's in-progress turn.
-*
-* Narrowly subscribed — a component using this re-renders at STT-partial rate,
-* which is exactly what it is for and exactly what a whole-page `useSession()`
-* should not do.
+//#region use-download-url.ts
+/**
+* `useDownloadUrl` — an upload id a run produced, as something `<audio>`,
+* `<img>` or `<a download>` will accept.
+*
+* `api.download(id)` resolves a `Blob`, and it has to: the byte route takes the
+* same bearer every workflow route does, and neither `<audio src>` nor
+* `<a href>` can send one. So every page that plays back what a run WROTE ends
+* up at the same four lines — `download` → `createObjectURL` → state — and the
+* two that are really the point are the two the four lines are wrapped in:
+*
+* - **`URL.revokeObjectURL` on cleanup.** An object URL pins its blob for the
+*   life of the DOCUMENT. Miss it and every completed run's audio stays resident
+*   until the tab closes, which on a page people run all day is a leak measured
+*   in the size of the files.
+* - **A `cancelled` flag.** A second run settling while the first download is
+*   still in flight otherwise sets state from the stale one, and the page plays
+*   the previous run's audio under the current run's transcript — a wrong answer
+*   that looks like a right one.
+*
+* Two templates had written this hook, identically, doc paragraph included, and
+* `aai-ui` exported no download helper at all. Both also faked `pending` by
+* checking `url === undefined && error === undefined`, which reads "idle" and
+* "downloading" as the same thing — so this reports it.
+*/
+/** No id: nothing pending, nothing to show. A shared object so `setState` no-ops. */
+const IDLE = { pending: false };
+/** Bytes in flight. Shared for the same reason as {@link IDLE}. */
+const PENDING = { pending: true };
+/**
+* Read an upload's bytes and hand back a URL a DOM element can use.
+*
+* @param uploadId - The id a completed run reported, or `undefined` before one
+*   exists — which is what a page passes straight through while it waits, and
+*   reports as idle rather than pending.
+* @param opts - See {@link UseDownloadUrlOptions}.
+* @returns See {@link UseDownloadUrlResult}.
 *
 * @example
 * ```tsx
-* import { useUserTranscript } from "@alexkroman1/aai-ui";
-*
-* function LiveTranscript() {
-*   const { speaking, text } = useUserTranscript();
-*   if (!speaking) return null;
-*   return <div className="italic opacity-60">{text}</div>;
+* import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+*
+* function Playback() {
+*   const { run } = useWorkflowSubmit<{ audio: string }>("spokenSummary");
+*   const output = run?.status === "completed" ? run.output : undefined;
+*   const audio = useDownloadUrl(output?.audio);
+*   if (audio.pending) return <p>Fetching audio…</p>;
+*   if (audio.error !== undefined) return <p role="alert">{audio.error}</p>;
+*   return audio.url === undefined ? null : (
+*     <a href={audio.url} download="summary.mp3">
+*       Download
+*     </a>
+*   );
 * }
 * ```
 *
 * @public
 */
-function useUserTranscript() {
-	const partial = useSessionSelector((snapshot) => snapshot.userTranscript);
-	return {
-		speaking: partial !== null,
-		text: displayText(partial),
-		partial
-	};
-}
-/** The three cases, spelled out: silent, detected-but-wordless, and words. */
-function displayText(partial) {
-	if (partial === null) return "";
-	return partial === "" ? "…" : partial;
+function useDownloadUrl(uploadId, opts = {}) {
+	const [state, setState] = useState(IDLE);
+	const getClient = useWorkflowApiRef(opts.api);
+	useEffect(() => {
+		if (uploadId === void 0) {
+			setState(IDLE);
+			return;
+		}
+		let cancelled = false;
+		let objectUrl;
+		setState(PENDING);
+		getClient().download(uploadId).then((blob) => {
+			if (cancelled) return;
+			objectUrl = URL.createObjectURL(blob);
+			setState({
+				url: objectUrl,
+				pending: false
+			});
+		}).catch((err) => {
+			if (!cancelled) setState({
+				error: errorMessage(err),
+				pending: false
+			});
+		});
+		return () => {
+			cancelled = true;
+			if (objectUrl !== void 0) URL.revokeObjectURL(objectUrl);
+		};
+	}, [uploadId, getClient]);
+	return state;
 }
 //#endregion
 //#region use-workflow-runs.ts
@@ -2306,6 +2611,7 @@ function useWorkflowStream(workflow, opts = {}) {
 		api,
 		intervalMs
 	}));
+	const { wake, cancel } = useRunControls(runId, getClient);
 	return {
 		submit: useCallback(async (input) => {
 			const client = getClient();
@@ -2361,6 +2667,8 @@ function useWorkflowStream(workflow, opts = {}) {
 			setStartError(void 0);
 			setUpload(void 0);
 		}, []),
+		wake,
+		cancel,
 		pauseUpload: useCallback(() => {
 			gateRef.current?.pause();
 			setUpload((current) => current ? {
@@ -2474,4 +2782,30 @@ function fileAt(input, field) {
 	return filesOf(input[field])[0];
 }
 //#endregion
-export { ApiUrlChip, AutoScroll, Button, ChatView, CheckboxField, Controls, DEFAULT_PROGRESS_POLL_MS, DEFAULT_WORKFLOW_POLL_MS, Field, FileField, Form, MAX_MISSING_READS, Markdown, MessageList, NumberField, SelectField, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, SubmitButton, TRANSCRIBING_PLACEHOLDER, TextAreaField, TextField, ThemeProvider, ToolCallRow, ToolConfigContext, UiUrlChip, UploadProgressBar, VOICE_CAPTURE_CONSTRAINTS, WorkflowFields, WorkflowProgress, buildAgentUrl, client, createSessionCore, createWorkflowApi, fetchClientConfig, isTerminal, loadClientConfig, page, useAgentState, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };
+//#region workflow-status-labels.ts
+/**
+* The default status line per {@link WorkflowRunStatus}.
+*
+* Override the ones your page has a better word for and keep the rest:
+*
+* ```ts
+* import { WORKFLOW_STATUS_LABELS } from "@alexkroman1/aai-ui";
+*
+* const STATUS_LINE = { ...WORKFLOW_STATUS_LABELS, running: "Writing…" };
+* ```
+*
+* The wording is deliberately about the RUN rather than about the work — a page
+* knows what its workflow does and this does not, so `running` is the neutral
+* "Working…" and every page that cares replaces exactly that key.
+*
+* @public
+*/
+const WORKFLOW_STATUS_LABELS = {
+	pending: "Queued",
+	running: "Working…",
+	completed: "Done",
+	failed: "Failed",
+	cancelled: "Cancelled"
+};
+//#endregion
+export { AutoScroll, Button, ChatView, CheckboxField, ConsoleShell, Controls, DEFAULT_PROGRESS_POLL_MS, DEFAULT_WORKFLOW_POLL_MS, Field, FileField, Form, MAX_MISSING_READS, Markdown, MessageList, NumberField, SelectField, SidebarLayout, StartScreen, SubmitButton, TRANSCRIBING_PLACEHOLDER, TextAreaField, TextField, ToolCallRow, UploadProgressBar, WORKFLOW_STATUS_LABELS, WorkflowFields, WorkflowProgress, client, createSessionCore, createWorkflowApi, fetchClientConfig, isTerminal, page, useAgentState, useConversation, useDownloadUrl, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };