@alexkroman1/aai-ui 6.11.0 → 8.0.0

package/dist/index.js

@@ -1,23 +1,24 @@
-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 { r as inkTint } from "./_colors-CcAi2FOU.js";
+import { n as fetchClientConfig } from "./client-config-BT_kWID5.js";
+import { i as AutoScroll, n as Markdown, r as useConversation, t as MessageList } from "./message-list-Dtl03sGr.js";
+import { ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
+import { r as inkTint } from "./_colors-j8XMToi9.js";
 import { Button } from "./components/button.js";
-import { t as ChatView } from "./chat-view-ByQFf94G.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 { n as ConsoleShell, t as ChatView } from "./chat-view-BJ6sOARu.js";
+import { n as setPageTitle } from "./_utils-B6498_bm.js";
+import { Controls } from "./components/controls.js";
+import { n as useUserTranscript } from "./use-user-transcript-C14qWFu2.js";
+import { n as ToolCallRow } from "./tool-call-block-B7KlhaWl.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
+import { a as useWorkflowRun, c as isTerminal, n as useWorkflowProgress, o as useWorkflowApiRef, s as createWorkflowApi } from "./use-workflow-progress-C4KgVldr.js";
+import { t as createSessionCore } from "./session-core-CMEpwRP1.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 { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
-import { createWorkflowApiClient, readEventStream } from "@alexkroman1/aai/workflow-api";
+import { errorMessage } from "@alexkroman1/aai";
+import { formatBytes, isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { createEpoch } from "@alexkroman1/aai/internal";
 //#region components/_form-readiness.ts
 /**
@@ -200,104 +201,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.
+* The controls a form is made of — the shell, the six fields, and the styling
+* they share.
 *
-* 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.
+* 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.
 *
-* ## Values come off the DOM, not out of React state
+* ## Every field takes its element's own attributes
 *
-* {@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.
+* 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.
 *
-* 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.
+* 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 +313,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 +340,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 +367,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 +391,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 +432,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 +475,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 +506,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
 	});
 }
@@ -543,30 +658,6 @@ function SubmitButton({ children, pending = false, pendingLabel = "Working…",
 * as a groove against the page.
 */
 const TRACK_TINT_PCT = 12;
-/** Bytes per KB/MB/GB step, as a file manager counts them. */
-const BYTE_STEP = 1024;
-/** Unit labels, largest last — the index is how many times the size divides. */
-const BYTE_UNITS = [
-	"B",
-	"KB",
-	"MB",
-	"GB"
-];
-/**
-* A size a person can read, because the number that matters is the SCALE.
-*
-* `12.4 MB of 48.0 MB` says how much is left in the terms someone chose the
-* file in; `13002343 of 50331648` says the same thing and answers nothing.
-*/
-function formatBytes(bytes) {
-	let value = bytes;
-	let unit = 0;
-	while (value >= BYTE_STEP && unit < BYTE_UNITS.length - 1) {
-		value /= BYTE_STEP;
-		unit += 1;
-	}
-	return `${unit === 0 ? value : value.toFixed(1)} ${BYTE_UNITS[unit]}`;
-}
 /**
 * How far a form's files have got, rendered as a bar.
 *
@@ -614,13 +705,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 +759,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.
@@ -1099,318 +1222,43 @@ async function uploadFiles(api, input, report, parallel, session) {
 	return out;
 }
 //#endregion
-//#region workflow-client.ts
+//#region _upload-pause.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
-* in a ref precisely so a fresh object per render does not restart its watch,
-* but a client built in render is still a new `fetch` closure every time and
-* reads as though it were free.
+* The two buttons a page puts over a live upload, bound to whichever gate the
+* submission is currently holding.
 *
-* @public
+* `useWorkflowSubmit` and `useWorkflowStream` both own an {@link UploadGate} and
+* both reported the pause the same way: park the gate, then fold `paused` into
+* the status the bar is already drawing. Folded rather than replaced, because
+* everything else about that status — which file, how far, of how many — is
+* still true. Two copies of that rule are two copies that can stop agreeing
+* about what a paused bar says.
 */
-function createWorkflowApi(opts = {}) {
-	return createWorkflowApiClient({
-		baseUrl: opts.baseUrl ?? pageBaseUrl(),
-		...omitUndefined({ token: opts.token })
-	});
-}
-//#endregion
-//#region _workflow-api-ref.ts
-/**
-* The client preamble every workflow hook needs, once.
-*
-* Five hooks (`useWorkflowRun`, `useWorkflowProgress`, `useWorkflowRuns`,
-* `useWorkflows`, `useWorkflowSubmit`) opened with the same two refs and the
-* same two paragraphs explaining them, and both halves are load-bearing rather
-* than stylistic — which is exactly why they should not be re-derived per hook:
-*
-* - **The caller's client lives in a REF, never in an effect's dependency
-*   array.** The natural call site is
-*   `useWorkflowRun(id, { api: createWorkflowApi() })`, which passes a NEW
-*   object every render; as a dependency that tears the effect down and
-*   restarts it on each one, and because a restart clears state and re-renders,
-*   it schedules the next. The result is an unbounded request loop against the
-*   agent — on the platform, against the BROKER — with `error` wiped before
-*   anything can read it, presenting as "the page polls forever" rather than as
-*   a mistake at the call site.
-* - **The no-client default is built lazily and ONCE.** As a render-time
-*   default (`api ?? createWorkflowApi()`) it is a fresh object per render,
-*   which is the same hazard one layer down; built inside an effect it is a
-*   fresh object per watch.
-*
-* The returned getter is stable for the life of the component and reads the ref
-* on every call, so a caller that SWAPS clients mid-watch — a token arriving
-* after login — is picked up by the next request without the watch restarting.
-*/
-/**
-* Resolve the client a workflow hook should use, now.
-*
-* @param api - The caller's client, or undefined for one aimed at the page's
-*   own agent.
-* @returns A stable getter. Call it per request, never once per watch.
-*
-* @internal
-*/
-function useWorkflowApiRef(api) {
-	const apiRef = useRef(api);
-	apiRef.current = api;
-	const fallbackRef = useRef(void 0);
-	return useCallback(() => {
-		const current = apiRef.current;
-		if (current) return current;
-		fallbackRef.current ??= createWorkflowApi();
-		return fallbackRef.current;
-	}, []);
-}
-//#endregion
-//#region _repeat-until.ts
-/**
-* A bounded read, re-armed from the SETTLED read — the loop both workflow
-* watchers are built out of.
-*
-* `pollUntilTerminal` (`use-workflow-run.ts`) and `readProgressUntilComplete`
-* (`use-workflow-progress.ts`) each open a request, decide from its answer
-* whether to come back, and stop when told to. What they had in common was not
-* the decision — one reads a snapshot, the other drains an SSE body — but the
-* scaffold around it, and that scaffold is where the two rules live:
-*
-* - **Re-armed from the settled read, never on an interval.** A slow response
-*   would otherwise stack overlapping requests on an agent that is already
-*   struggling, and on the platform every one of them BROKERS.
-* - **Cancellation is a signal, not a flag.** The teardown has to reach the
-*   in-flight request too — an abandoned progress read otherwise keeps pulling
-*   chunks out of a run for a page that has navigated away — so `step` is
-*   handed the signal rather than being trusted to check a boolean.
-*/
-/**
-* Call `step` until it reports it is finished, or until the returned stop
-* function is called.
-*
-* `step` resolves `true` when there is nothing left to come back for. It is
-* responsible for its own failures: a rejection would leave the loop stopped
-* with nobody told, so each caller decides whether its failure is terminal or
-* just another reason to try again.
-*
-* @internal
-*/
-function repeatUntil(intervalMs, step) {
-	const controller = new AbortController();
-	let timer;
-	const tick = async () => {
-		if (await step(controller.signal) || controller.signal.aborted) return;
-		timer = setTimeout(() => void tick(), intervalMs);
-	};
-	tick();
-	return () => {
-		controller.abort();
-		if (timer !== void 0) clearTimeout(timer);
-	};
-}
-//#endregion
-//#region workflow-events.ts
 /**
-* Watching a run over server-sent events — the PUSH half of `useWorkflowRun`.
+* Bind pause/resume to the live submission's gate.
 *
-* Its own module because the seam is clean: everything in `workflow-client.ts`
-* is request/response shaping plus the poll, and this is one long-lived stream
-* and the SSE parser it needs.
+* @param getGate - Reads the gate out of the caller's ref, so the callbacks stay
+*   stable across submissions rather than being re-created per gate.
+* @param setUpload - The status setter the progress bar renders from.
 *
 * @internal
 */
-/**
-* Watch a run over SSE, falling back to the caller's poll on any failure.
-*
-* The poll stays the fallback rather than being replaced, and that is the whole
-* shape of this: a stream is an optimisation over a mechanism that already
-* works, so every way it can fail — an older agent with no `/events` route, a
-* proxy that buffers, a network that drops it — has to degrade to the thing that
-* does. What it buys is real, though: on the platform every polled read BROKERS,
-* so N open tabs at `DEFAULT_WORKFLOW_POLL_MS` is N/2 brokered requests a
-* second, each able to boot a sandbox. One stream per tab replaces all of it.
-*
-* `EventSource` is not used, for two reasons that both matter here: it cannot
-* send an `Authorization` header (an agent with `AAI_WORKFLOW_API_TOKEN` set
-* would be unreachable), and it reconnects on its own schedule, which would
-* fight the caller's. A `fetch` stream gives both back.
-*
-* Returns a stop function. `onFallback` is called at most once, when this stream
-* cannot be relied on and the poll should take over.
-*/
-function watchRunEvents(getClient, runId, onRun, onSettled, onFallback) {
-	const controller = new AbortController();
-	let handedOver = false;
-	const handOver = () => {
-		if (handedOver || controller.signal.aborted) return;
-		handedOver = true;
-		onFallback();
-	};
-	/**
-	* Consume the stream. Resolves `"settled"` when the run reached a state
-	* nothing will change, and `"fallback"` for every other ending — including a
-	* clean end with no final frame, which is a dropped connection.
-	*
-	* A named function rather than an inline IIFE so `watchRunEvents` stays under
-	* the cognitive-complexity cap, and so the two outcomes are a return value
-	* instead of two callbacks invoked from six places.
-	*/
-	const pump = async () => {
-		const res = await getClient().watch(runId, controller.signal);
-		if (!(res.ok && res.body)) return "fallback";
-		for await (const frame of readEventStream(res.body, controller.signal)) {
-			if (frame.event === "run" && frame.data) onRun(frame.data);
-			const outcome = endingFor(frame.event);
-			if (outcome) return outcome;
-		}
-		return "fallback";
-	};
-	pump().then((outcome) => outcome === "settled" ? onSettled() : handOver(), () => handOver());
-	return () => controller.abort();
-}
-/**
-* Does this frame END the stream, and does the run need watching afterwards?
-*
-* `done` and `missing` are both final and neither wants a reconnect: the run is
-* terminal, or the id will never exist (a 404 is a stable answer — the world's
-* record is durable). `idle` is the stream handing ITSELF back after its
-* duration cap, so that one falls back to the poll. Anything else is not an
-* ending.
-*/
-function endingFor(event) {
-	if (event === "done" || event === "missing") return "settled";
-	return event === "idle" ? "fallback" : void 0;
-}
-//#endregion
-//#region use-workflow-run.ts
-/**
-* `useWorkflowRun` — watch one run until it settles.
-*
-* Split from `workflow-client.ts` on the seam that module's doc already draws:
-* everything there is a REQUEST (one call, one answer, no React), and everything
-* here is the loop that keeps asking. They are read for different reasons — the
-* client is what a script or a `curl` equivalent needs, this is what a page needs
-* — and only this half imports React.
-*
-* `workflow-events.ts` sits under it as the streaming fast path, and
-* `use-workflow-form.ts` above it as the form-shaped caller.
-*/
-/** How often {@link useWorkflowRun} re-reads a live run when it has to poll. */
-const DEFAULT_WORKFLOW_POLL_MS = 2e3;
-/**
-* Consecutive "no such run" reads {@link useWorkflowRun} tolerates before giving
-* up on the id.
-*
-* Small on purpose: a 404 is a stable answer, so the budget exists only to
-* absorb a first read that races the run's creation — not to keep hoping.
-* Unbounded, a stale id polls (and, on the platform, BROKERS) for as long as the
-* tab is open.
-*/
-const MAX_MISSING_READS = 3;
-/**
-* Poll `runId` until it is terminal, reporting each read. Returns a stop
-* function.
-*
-* Module-level rather than inline in the hook below, so neither function carries
-* the whole loop's branching — and so the loop can be read without React in the
-* way.
-*/
-function pollUntilTerminal(getClient, runId, intervalMs, onRun, onError, onStopped) {
-	let missing = 0;
-	/**
-	* A read that came back empty. Resolves whether the loop should STOP.
-	*
-	* A 404 is a STABLE answer — a run the agent does not know about now will not
-	* appear later — and retrying it unbounded is how a stale id (one restored
-	* from `localStorage`, or one whose agent was redeployed onto a fresh
-	* database) polls forever: the page stays `polling` and therefore busy, and on
-	* the platform every read BROKERS, so a tab's worth of dead ids keeps
-	* sandboxes resident. A small budget is kept anyway, because the first read
-	* can race a replica that has not yet seen the run.
-	*/
-	const onMissing = (signal) => {
-		missing += 1;
-		if (missing < 3) return false;
-		if (!signal.aborted) onError(`No workflow run ${runId}`);
-		return true;
-	};
-	const read = async (signal) => {
-		try {
-			const next = await getClient().get(runId);
-			if (signal.aborted) return true;
-			if (!next) return onMissing(signal);
-			missing = 0;
-			onRun(next);
-			return isTerminal$1(next);
-		} catch (err) {
-			if (!signal.aborted) onError(errorMessage(err));
-			return false;
-		}
-	};
-	return repeatUntil(intervalMs, async (signal) => {
-		if (!await read(signal)) return false;
-		if (!signal.aborted) onStopped();
-		return true;
-	});
-}
-/**
-* Watch one run until it reaches a terminal status.
-*
-* A watch rather than a subscription because a run is durable and the page is
-* not: it can complete while the tab is closed, on a different sandbox, hours
-* later. There is no session to reconnect — the id is the whole state.
-*
-* The stream (`GET /runs/:id/events`) is tried first and the poll is its
-* fallback, so an agent deployed before that route existed still works. Watching
-* STOPS on a terminal status, so a finished run costs nothing; passing
-* `undefined` (nothing started yet) also costs nothing.
-*
-* @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.
-*
-* @public
-*/
-function useWorkflowRun(runId, opts = {}) {
-	const { api, intervalMs = DEFAULT_WORKFLOW_POLL_MS } = opts;
-	const [run, setRun] = useState(void 0);
-	const [error, setError] = useState(void 0);
-	/**
-	* Has the watch stopped for a reason the snapshot does not show?
-	*
-	* Only one such reason exists — an id the agent kept reporting as unknown,
-	* past {@link MAX_MISSING_READS} — and it leaves `run` undefined, so `polling`
-	* derived from `isTerminal(run)` alone would stay true forever.
-	*/
-	const [stopped, setStopped] = useState(false);
-	const getClient = useWorkflowApiRef(api);
-	useEffect(() => {
-		setRun(void 0);
-		setError(void 0);
-		setStopped(false);
-		if (!runId) return;
-		const onRun = (next) => {
-			setRun(next);
-			setError(void 0);
-		};
-		let stopPoll;
-		const stopStream = watchRunEvents(getClient, runId, onRun, () => setStopped(true), () => {
-			stopPoll = pollUntilTerminal(getClient, runId, intervalMs, onRun, setError, () => setStopped(true));
-		});
-		return () => {
-			stopStream();
-			stopPoll?.();
-		};
-	}, [
-		runId,
-		intervalMs,
-		getClient
-	]);
+function useUploadPause(getGate, setUpload) {
+	const setPaused = useCallback((paused) => {
+		setUpload((current) => current ? {
+			...current,
+			paused
+		} : current);
+	}, [setUpload]);
 	return {
-		run,
-		error,
-		polling: runId !== void 0 && !stopped && !isTerminal$1(run)
+		pauseUpload: useCallback(() => {
+			getGate()?.pause();
+			setPaused(true);
+		}, [getGate, setPaused]),
+		resumeUpload: useCallback(() => {
+			getGate()?.resume();
+			setPaused(false);
+		}, [getGate, setPaused])
 	};
 }
 //#endregion
@@ -1460,6 +1308,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,59 +1407,53 @@ function useWorkflowSubmit(workflow, opts = {}) {
 		api,
 		intervalMs
 	}));
-	return {
-		submit: useCallback(async (input) => {
-			const client = getClient();
-			setStarting(true);
-			setStartError(void 0);
-			setRunId(void 0);
-			session.current?.gate.cancel();
-			const current = createUploadSession(workflow);
-			session.current = current;
-			try {
-				const options = omitUndefined({ key });
-				const started = await uploadFiles(client, input, setUpload, parallel, current);
-				setRunId(wait === void 0 ? await client.start(workflow, started, options) : (await client.startAndWait(workflow, started, {
-					...options,
-					wait
-				})).runId);
-			} catch (err) {
-				if (!current.gate.cancelled) setStartError(errorMessage(err));
-			} finally {
-				if (session.current === current) {
-					session.current = void 0;
-					setStarting(false);
-					setUpload(void 0);
-				}
+	const { wake, cancel } = useRunControls(runId, getClient);
+	const submit = useCallback(async (input) => {
+		const client = getClient();
+		setStarting(true);
+		setStartError(void 0);
+		setRunId(void 0);
+		session.current?.gate.cancel();
+		const current = createUploadSession(workflow);
+		session.current = current;
+		try {
+			const options = omitUndefined({ key });
+			const started = await uploadFiles(client, input, setUpload, parallel, current);
+			setRunId(wait === void 0 ? await client.start(workflow, started, options) : (await client.startAndWait(workflow, started, {
+				...options,
+				wait
+			})).runId);
+		} catch (err) {
+			if (!current.gate.cancelled) setStartError(errorMessage(err));
+		} finally {
+			if (session.current === current) {
+				session.current = void 0;
+				setStarting(false);
+				setUpload(void 0);
 			}
-		}, [
-			workflow,
-			key,
-			wait,
-			parallel,
-			getClient
-		]),
-		reset: useCallback(() => {
-			session.current?.gate.cancel();
-			session.current = void 0;
-			setRunId(void 0);
-			setStartError(void 0);
-			setUpload(void 0);
-		}, []),
-		pauseUpload: useCallback(() => {
-			session.current?.gate.pause();
-			setUpload((current) => current ? {
-				...current,
-				paused: true
-			} : current);
-		}, []),
-		resumeUpload: useCallback(() => {
-			session.current?.gate.resume();
-			setUpload((current) => current ? {
-				...current,
-				paused: false
-			} : current);
-		}, []),
+		}
+	}, [
+		workflow,
+		key,
+		wait,
+		parallel,
+		getClient
+	]);
+	const reset = useCallback(() => {
+		session.current?.gate.cancel();
+		session.current = void 0;
+		setRunId(void 0);
+		setStartError(void 0);
+		setUpload(void 0);
+	}, []);
+	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => session.current?.gate, []), setUpload);
+	return {
+		submit,
+		reset,
+		wake,
+		cancel,
+		pauseUpload,
+		resumeUpload,
 		run: tracked.run,
 		pending: starting || tracked.polling,
 		upload,
@@ -1591,6 +1462,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 +1513,8 @@ function useWorkflowSubmit(workflow, opts = {}) {
 * }
 * ```
 *
+* @param props - Field-set props.
+*
 * @public
 */
 function WorkflowFields({ workflow }) {
@@ -1707,208 +1600,6 @@ function humanize(name) {
 	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 }
 //#endregion
-//#region use-workflow-progress.ts
-/**
-* `useWorkflowProgress` — read what a run has WRITTEN while it runs.
-*
-* The sibling of `useWorkflowRun`, and the split between them is the whole
-* reason this exists. That hook reports a run's STATE: the status transitions
-* the world records, which every run has. This reports what the run itself
-* wrote through `getWritable()`, which is the only thing a long run can say
-* before it finishes — a snapshot carries a status and, once terminal, an
-* output, and nothing in between. A page that shows only status shows
-* "Working…" for ten minutes and then a result.
-*
-* ## There is no poll fallback, and that is not an omission
-*
-* `useWorkflowRun` degrades to polling `GET /runs/:id` because a run's STATE is
-* readable that way. A run's written chunks are not: the stream is the only
-* route to them, so an agent that does not serve it has no progress to give and
-* `supported` says so once, rather than a poll pretending to look for something
-* that is not there. A page renders its status line either way.
-*
-* ## Chunks are RETAINED, so this is a replay as much as a tail
-*
-* The run's stream keeps every chunk, so a page that mounts late — a reload, a
-* second tab, a link opened tomorrow — reads the whole history from index 0 and
-* arrives at the same list as one that watched throughout. That is what makes a
-* durable run's progress durable too, and it is why the default `startIndex` is
-* 0 rather than "from now": a tail-only default would make the same page show
-* different things depending on when it opened.
-*
-* ## It RE-OPENS while the run is live, because a progress read is bounded
-*
-* The route answers with the chunks written when the request arrived and then
-* ends, reporting `complete` — whether the run itself was terminal. It has to:
-* a workflow stream signals its end only once CLOSED, and a progress channel
-* written by one step after another is never closed, so a read that waited for
-* the end would hang forever on a finished run. (It did: see the route's own
-* doc.)
-*
-* So this hook re-opens from where it left off until a read comes back
-* `complete`. That is a poll, and the honest description of progress is a durable
-* log rather than a socket — but it is a poll of a CHEAP shape: each read asks
-* only for chunks past the last index it saw, so a quiet run costs an empty
-* answer rather than the whole log again.
-*/
-/** How often a live run's progress is re-read once a bounded read has ended. */
-const DEFAULT_PROGRESS_POLL_MS = 1e3;
-/**
-* Drain one bounded read's frames, reporting how it ended and everything it
-* carried.
-*
-* The chunks are RETURNED rather than handed over one at a time, and that is
-* what lets the hook commit a whole read in one React update: a per-chunk
-* callback re-rendered the page once per progress line and rebuilt the list
-* each time, which for a fan-out writing a line per segment is an O(n²) copy of
-* the log a reader can already only see one frame at a time. A read is bounded
-* by construction (see the module doc), so buffering one is bounded too.
-*/
-async function consumeFrames(body, signal) {
-	const chunks = [];
-	let ending = "partial";
-	for await (const frame of readEventStream(body, signal)) if (frame.event === "chunk") chunks.push(frame.data);
-	else if (frame.event === "done") ending = frame.data?.complete ? "complete" : "partial";
-	else if (frame.event === "missing") return {
-		ending: "complete",
-		chunks
-	};
-	return {
-		ending,
-		chunks
-	};
-}
-/**
-* Read one run's progress until it is complete, reporting each read's chunks.
-*
-* Module-level rather than inline in the hook, so the loop reads without React in
-* the way — the same split `useWorkflowRun` makes with `pollUntilTerminal`.
-*
-* Every re-open asks from an ABSOLUTE position past the last chunk read, so a
-* read only ever fetches what this reader has not seen. That is what keeps the
-* poll cheap: a quiet run answers with a bare `done` rather than the whole log
-* again.
-*
-* ## A negative `startIndex` is resolved on the FIRST read, not carried
-*
-* "The last N lines" names no position a later read can resume from — the tail
-* it counts back from moves with every line the run writes. Carrying it meant a
-* re-open asking for everything from 0 and dropping `seen` chunks off the
-* FRONT, which is a different set entirely: a reader that opened at
-* `startIndex: -3` on a 10-line log holds lines 7-9, and its next read handed
-* over lines 3 onwards — four lines it never asked for, then the three it
-* already had, in that order. The dedupe the old comment claimed would need the
-* first read's absolute tail, which the reader never learned.
-*
-* So the first read is issued from 0 instead, and only its last N chunks are
-* handed over. The window the caller asked for is unchanged, and the reader now
-* knows exactly where it is — every read after it is the ordinary absolute case.
-* The cost is that the first read transfers the whole log, which is what the
-* DEFAULT (`startIndex: 0`, "replay everything") already does.
-*/
-function readProgressUntilComplete(getClient, runId, options, intervalMs, onChunks, onEnded) {
-	const start = options.startIndex ?? 0;
-	const tail = start < 0 ? -start : void 0;
-	let next = tail === void 0 ? start : 0;
-	let firstRead = true;
-	/** One bounded read. Resolves how it ended. */
-	const readOnce = async (signal) => {
-		const res = await getClient().streamOutput(runId, {
-			...omitUndefined({
-				namespace: options.namespace,
-				startIndex: next === 0 ? void 0 : next
-			}),
-			signal
-		});
-		if (!(res.ok && res.body)) return "unsupported";
-		const { ending, chunks } = await consumeFrames(res.body, signal);
-		next += chunks.length;
-		const fresh = firstRead && tail !== void 0 ? chunks.slice(-tail) : chunks;
-		firstRead = false;
-		if (fresh.length > 0 && !signal.aborted) onChunks(fresh);
-		return ending;
-	};
-	return repeatUntil(intervalMs, async (signal) => {
-		let ending;
-		try {
-			ending = await readOnce(signal);
-		} catch {
-			ending = "partial";
-		}
-		if (signal.aborted) return true;
-		if (ending === "partial") return false;
-		onEnded(ending);
-		return true;
-	});
-}
-/**
-* Follow one run's progress stream.
-*
-* Passing `undefined` (nothing started yet) costs nothing, and reading stops for
-* good once a read reports the run terminal — so a finished run costs one read.
-*
-* @example
-* ```tsx
-* import { useWorkflowProgress } from "@alexkroman1/aai-ui";
-*
-* function Progress({ runId }: { runId?: string }) {
-*   const { progress, streaming, supported } = useWorkflowProgress(runId);
-*   if (!supported) return null;
-*   return (
-*     <pre>
-*       {progress.join("\n")}
-*       {streaming && "\n…"}
-*     </pre>
-*   );
-* }
-* ```
-*
-* @typeParam T - What the workflow writes. Defaults to `string`, which is what
-*   a progress channel usually carries; a workflow writing objects names its own
-*   shape. Nothing in the browser can verify it — the route describes no type —
-*   so this is the page's assertion about its own agent, narrowed once here
-*   rather than at every read.
-*
-* @public
-*/
-function useWorkflowProgress(runId, opts = {}) {
-	const { api, namespace, startIndex, intervalMs = DEFAULT_PROGRESS_POLL_MS } = opts;
-	const [progress, setProgress] = useState([]);
-	const [streaming, setStreaming] = useState(false);
-	const [supported, setSupported] = useState(true);
-	const getClient = useWorkflowApiRef(api);
-	useEffect(() => {
-		setProgress([]);
-		setSupported(true);
-		setStreaming(false);
-		if (!runId) return;
-		setStreaming(true);
-		const stop = readProgressUntilComplete(getClient, runId, {
-			namespace,
-			startIndex
-		}, intervalMs, (chunks) => setProgress((seen) => [...seen, ...chunks]), (ending) => {
-			setStreaming(false);
-			if (ending === "unsupported") setSupported(false);
-		});
-		return () => {
-			stop();
-			setStreaming(false);
-		};
-	}, [
-		runId,
-		namespace,
-		startIndex,
-		intervalMs,
-		getClient
-	]);
-	return {
-		progress,
-		latest: progress.at(-1),
-		streaming,
-		supported
-	};
-}
-//#endregion
 //#region components/workflow-progress.tsx
 /** @jsxImportSource react */
 /**
@@ -1946,24 +1637,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 +1711,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,75 +2015,69 @@ function useWorkflowStream(workflow, opts = {}) {
 		api,
 		intervalMs
 	}));
-	return {
-		submit: useCallback(async (input) => {
-			const client = getClient();
-			setStarting(true);
-			setStartError(void 0);
-			setRunId(void 0);
-			gateRef.current?.cancel();
-			const gate = createUploadGate();
-			gateRef.current = gate;
-			let started;
-			try {
-				const id = randomUploadId();
-				const begun = await beginRun({
-					client,
-					workflow,
-					input,
-					id,
-					...omitUndefined({ key })
-				});
-				started = begun.runId;
-				const chosen = begun.file;
-				setRunId(started);
-				if (!chosen) return;
-				await streamFile({
-					client,
-					gate,
-					id,
-					file: chosen,
-					parallel,
-					report: setUpload
-				});
-				await client.wake(started).catch(() => void 0);
-			} catch (err) {
-				if (!gate.cancelled) setStartError(errorMessage(err));
-				if (started) await client.cancel(started).catch(() => void 0);
-			} finally {
-				if (gateRef.current === gate) {
-					gateRef.current = void 0;
-					setStarting(false);
-					setUpload(void 0);
-				}
+	const { wake, cancel } = useRunControls(runId, getClient);
+	const submit = useCallback(async (input) => {
+		const client = getClient();
+		setStarting(true);
+		setStartError(void 0);
+		setRunId(void 0);
+		gateRef.current?.cancel();
+		const gate = createUploadGate();
+		gateRef.current = gate;
+		let started;
+		try {
+			const id = randomUploadId();
+			const begun = await beginRun({
+				client,
+				workflow,
+				input,
+				id,
+				...omitUndefined({ key })
+			});
+			started = begun.runId;
+			const chosen = begun.file;
+			setRunId(started);
+			if (!chosen) return;
+			await streamFile({
+				client,
+				gate,
+				id,
+				file: chosen,
+				parallel,
+				report: setUpload
+			});
+			await client.wake(started).catch(() => void 0);
+		} catch (err) {
+			if (!gate.cancelled) setStartError(errorMessage(err));
+			if (started) await client.cancel(started).catch(() => void 0);
+		} finally {
+			if (gateRef.current === gate) {
+				gateRef.current = void 0;
+				setStarting(false);
+				setUpload(void 0);
 			}
-		}, [
-			workflow,
-			key,
-			parallel,
-			getClient
-		]),
-		reset: useCallback(() => {
-			gateRef.current?.cancel();
-			gateRef.current = void 0;
-			setRunId(void 0);
-			setStartError(void 0);
-			setUpload(void 0);
-		}, []),
-		pauseUpload: useCallback(() => {
-			gateRef.current?.pause();
-			setUpload((current) => current ? {
-				...current,
-				paused: true
-			} : current);
-		}, []),
-		resumeUpload: useCallback(() => {
-			gateRef.current?.resume();
-			setUpload((current) => current ? {
-				...current,
-				paused: false
-			} : current);
-		}, []),
+		}
+	}, [
+		workflow,
+		key,
+		parallel,
+		getClient
+	]);
+	const reset = useCallback(() => {
+		gateRef.current?.cancel();
+		gateRef.current = void 0;
+		setRunId(void 0);
+		setStartError(void 0);
+		setUpload(void 0);
+	}, []);
+	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => gateRef.current, []), setUpload);
+	return {
+		submit,
+		reset,
+		wake,
+		cancel,
+		pauseUpload,
+		resumeUpload,
 		run: tracked.run,
 		pending: starting || tracked.polling,
 		upload,
@@ -2474,4 +2177,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, Field, FileField, Form, Markdown, MessageList, NumberField, SelectField, SidebarLayout, StartScreen, SubmitButton, 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 };