@alexkroman1/aai-ui 5.13.2 → 6.1.0

package/dist/index.js

@@ -1,13 +1,1603 @@
-import { i as loadClientConfig, n as buildAgentUrl, r as fetchClientConfig, t as createSessionCore } from "./session-core-BA8H3qtF.js";
+import { i as loadClientConfig, n as buildAgentUrl, r as fetchClientConfig, t as createSessionCore } from "./session-core-ClKdVgRU.js";
+import { n as Markdown, r as AutoScroll, t as MessageList } from "./message-list-BwA3rdPi.js";
 import { SessionProvider, ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
 import { Button } from "./components/button.js";
-import { t as ChatView } from "./chat-view-DadZOvJO.js";
-import { i as UiUrlChip, n as ApiUrlChip, r as SessionUrlChips, t as Controls } from "./controls-DzQEKq9c.js";
-import { n as Markdown, t as MessageList } from "./message-list-YdLocGoT.js";
-import { n as ToolConfigContext, r as ToolCallRow } from "./tool-call-block-CAscLGFy.js";
+import { t as ChatView } from "./chat-view-CK61bWWx.js";
+import { t as pageBaseUrl } from "./_utils-CsqbIVGI.js";
+import { i as UiUrlChip, n as ApiUrlChip, r as SessionUrlChips, t as Controls } from "./controls-Cy_YVfsa.js";
+import { n as ToolConfigContext, r as ToolCallRow } from "./tool-call-block-CrLN7xlI.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
 import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
-import { client } from "./define-client.js";
+import { client, mountRoot, resolveContainer } from "./define-client.js";
 import { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.js";
-export { ApiUrlChip, Button, ChatView, Controls, Markdown, MessageList, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, ThemeProvider, ToolCallRow, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, buildAgentUrl, client, createSessionCore, fetchClientConfig, loadClientConfig, useAgentState, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult };
+import clsx from "clsx";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createElement, useCallback, useEffect, useId, useRef, useState } from "react";
+import { errorMessage, isTerminal, isTerminal as isTerminal$1 } from "@alexkroman1/aai";
+import { isRecord, omitUndefined, safeJsonParse as safeJsonParse$1 } from "@alexkroman1/aai/utils";
+import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
+import { createParser } from "eventsource-parser";
+import { createEpoch } from "@alexkroman1/aai/internal";
+//#region components/_form-values.ts
+/**
+* Read one `<form>`'s named controls into a plain object.
+*
+* Exported for tests and for a caller doing its own submit handling.
+*
+* @internal
+*/
+async function collectValues(form) {
+	const values = {};
+	for (const element of Array.from(form.elements)) if (element instanceof HTMLInputElement) await readInput(element, values);
+	else if ((element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) && element.name !== "" && !element.disabled) values[element.name] = element instanceof HTMLSelectElement ? readSelect(element) : element.value;
+	return values;
+}
+/**
+* One `<select>`, by arity.
+*
+* `HTMLSelectElement.value` is the FIRST selected option and nothing more, so a
+* `<SelectField multiple>` — which type-checks, since the props extend
+* `SelectHTMLAttributes` — contributed one string where its schema is waiting
+* for a list. `selectedOptions` is the whole of what the user picked; nothing
+* selected contributes `[]`, which is the honest answer for a control that is
+* present and empty rather than one that was left blank.
+*/
+function readSelect(select) {
+	if (!select.multiple) return select.value;
+	return Array.from(select.selectedOptions, (option) => option.value);
+}
+/** One `<input>`, by type. */
+async function readInput(input, values) {
+	if (input.name === "" || input.disabled) return;
+	switch (input.type) {
+		case "checkbox":
+			values[input.name] = input.checked;
+			return;
+		case "radio":
+			if (input.checked) values[input.name] = input.value;
+			return;
+		case "number":
+		case "range": {
+			if (input.value === "") return;
+			const value = input.valueAsNumber;
+			values[input.name] = Number.isNaN(value) ? input.value : value;
+			return;
+		}
+		case "file": {
+			const files = Array.from(input.files ?? []);
+			if (files.length === 0) return;
+			const chosen = await readFiles(files, readMode(input.dataset.aaiRead));
+			values[input.name] = input.multiple ? chosen : chosen[0];
+			return;
+		}
+		default: values[input.name] = input.value;
+	}
+}
+/**
+* The chosen files, as the field's `read` mode says to contribute them.
+*
+* An UPLOAD field contributes each `File` UNREAD. Reading it here would mean
+* holding a 200 MB recording in memory to describe it, and the thing that needs
+* the bytes is the upload request `useWorkflowSubmit` makes — which streams the
+* same `File` object straight to the agent.
+*/
+function readFiles(files, read) {
+	if (read === "upload") return Promise.resolve([...files]);
+	return Promise.all(files.map((file) => describeFile(file, read)));
+}
+/** The `data-aai-read` attribute as a {@link FileRead}, defaulting to `"none"`. */
+function readMode(raw) {
+	return raw === "text" || raw === "dataUrl" || raw === "upload" ? raw : "none";
+}
+/** One chosen file as a {@link FileValue}. */
+async function describeFile(file, read) {
+	const described = {
+		name: file.name,
+		size: file.size,
+		type: file.type,
+		lastModified: file.lastModified
+	};
+	if (read === "none") return described;
+	return {
+		...described,
+		content: read === "text" ? await file.text() : await dataUrl(file)
+	};
+}
+/** A file as a `data:` URL. */
+function dataUrl(file) {
+	return new Promise((resolve, reject) => {
+		const reader = new FileReader();
+		reader.onerror = () => reject(reader.error ?? /* @__PURE__ */ new Error(`Could not read ${file.name}`));
+		reader.onload = () => resolve(String(reader.result));
+		reader.readAsDataURL(file);
+	});
+}
+//#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>
+*   );
+* }
+* ```
+*
+* @public
+*/
+function Form({ onSubmit, error, children, className, ...rest }) {
+	const theme = useTheme();
+	const [busy, setBusy] = useState(false);
+	return /* @__PURE__ */ jsxs("form", {
+		onSubmit: useCallback((event) => {
+			event.preventDefault();
+			if (busy) return;
+			const form = event.currentTarget;
+			setBusy(true);
+			(async () => {
+				try {
+					await onSubmit(await collectValues(form));
+				} finally {
+					setBusy(false);
+				}
+			})();
+		}, [busy, onSubmit]),
+		className: clsx("flex flex-col gap-5 font-aai", className),
+		...rest,
+		children: [/* @__PURE__ */ jsx("fieldset", {
+			disabled: busy,
+			className: "contents",
+			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.
+*
+* @public
+*/
+function Field({ label, hint, htmlFor, className, children }) {
+	const theme = useTheme();
+	return /* @__PURE__ */ jsxs("div", {
+		className: clsx("flex flex-col gap-1.5", className),
+		children: [
+			label !== void 0 && /* @__PURE__ */ jsx("label", {
+				htmlFor,
+				className: "text-[11px] font-medium uppercase tracking-[1.2px]",
+				style: { color: theme.text },
+				children: label
+			}),
+			children,
+			hint !== void 0 && /* @__PURE__ */ jsx("p", {
+				className: "text-xs opacity-60",
+				style: { color: theme.text },
+				children: hint
+			})
+		]
+	});
+}
+/** The shared control styling — one place, so the fields cannot drift apart. */
+function useControlProps() {
+	const theme = useTheme();
+	return {
+		className: clsx("w-full rounded-aai border px-3 py-2 text-sm font-aai", "outline-none focus-visible:[outline:2px_solid] focus-visible:[outline-offset:2px]", "disabled:cursor-not-allowed disabled:opacity-50"),
+		style: {
+			background: theme.surface,
+			color: theme.text,
+			borderColor: theme.border,
+			outlineColor: theme.primary
+		}
+	};
+}
+/**
+* The control styling for a file input.
+*
+* A file input is the one control whose BUTTON the browser draws, and every
+* engine draws it differently: left to the user agent it inherits the field's
+* own colours and can come out as invisible text on the surface it sits on —
+* which is what "the Choose file button doesn't display" is. So the button is
+* styled explicitly through `::file-selector-button` (Tailwind's `file:`
+* variant) in the theme's own colours, and the field's vertical padding is
+* reduced to the button's, since the button is what sets the row's height.
+*
+* The colours reach the variant as CSS CUSTOM PROPERTIES, because a Tailwind
+* class cannot read a JavaScript theme object and a pseudo-element cannot be
+* reached by a React `style` prop.
+*/
+function useFileControlProps() {
+	const theme = useTheme();
+	const control = useControlProps();
+	return {
+		className: clsx(control.className, "cursor-pointer py-1.5 pl-1.5", "file:mr-3 file:cursor-pointer file:rounded-aai file:border-0 file:px-3 file:py-1.5", "file:text-sm file:font-medium file:font-aai", "file:[background:var(--aai-file-button-bg)] file:[color:var(--aai-file-button-fg)]"),
+		style: {
+			...control.style,
+			"--aai-file-button-bg": theme.primary,
+			"--aai-file-button-fg": theme.surface
+		}
+	};
+}
+/**
+* A single-line text input.
+*
+* @public
+*/
+function TextField({ name, label, hint, className, ...rest }) {
+	const id = useId();
+	return /* @__PURE__ */ jsx(Field, {
+		label,
+		hint,
+		htmlFor: id,
+		className,
+		children: /* @__PURE__ */ jsx("input", {
+			id,
+			name,
+			type: "text",
+			...useControlProps(),
+			...rest
+		})
+	});
+}
+/**
+* A number input. Contributes a NUMBER to {@link FormValues}, or nothing when
+* left empty.
+*
+* @public
+*/
+function NumberField({ name, label, hint, className, ...rest }) {
+	const id = useId();
+	return /* @__PURE__ */ jsx(Field, {
+		label,
+		hint,
+		htmlFor: id,
+		className,
+		children: /* @__PURE__ */ jsx("input", {
+			id,
+			name,
+			type: "number",
+			...useControlProps(),
+			...rest
+		})
+	});
+}
+/**
+* A multi-line text input.
+*
+* @public
+*/
+function TextAreaField({ name, label, hint, className, rows = 4, ...rest }) {
+	const id = useId();
+	return /* @__PURE__ */ jsx(Field, {
+		label,
+		hint,
+		htmlFor: id,
+		className,
+		children: /* @__PURE__ */ jsx("textarea", {
+			id,
+			name,
+			rows,
+			...useControlProps(),
+			...rest
+		})
+	});
+}
+/**
+* A dropdown. Pass `options`, or `children` for full control over the
+* `<option>` elements.
+*
+* @public
+*/
+function SelectField({ name, label, hint, className, options, children, ...rest }) {
+	const id = useId();
+	return /* @__PURE__ */ jsx(Field, {
+		label,
+		hint,
+		htmlFor: id,
+		className,
+		children: /* @__PURE__ */ jsx("select", {
+			id,
+			name,
+			...useControlProps(),
+			...rest,
+			children: children ?? options?.map((option) => {
+				const value = typeof option === "string" ? option : option.value;
+				return /* @__PURE__ */ jsx("option", {
+					value,
+					children: typeof option === "string" ? option : option.label
+				}, value);
+			})
+		})
+	});
+}
+/**
+* A checkbox. Contributes a BOOLEAN to {@link FormValues}.
+*
+* @public
+*/
+function CheckboxField({ name, label, hint, className, ...rest }) {
+	const id = useId();
+	const theme = useTheme();
+	return /* @__PURE__ */ jsx(Field, {
+		hint,
+		className,
+		children: /* @__PURE__ */ jsxs("label", {
+			htmlFor: id,
+			className: "flex items-center gap-2 text-sm",
+			style: { color: theme.text },
+			children: [/* @__PURE__ */ jsx("input", {
+				id,
+				name,
+				type: "checkbox",
+				style: { accentColor: theme.primary },
+				...rest
+			}), label]
+		})
+	});
+}
+/**
+* A file picker. Contributes a {@link FileValue} (or an array, with `multiple`)
+* to {@link FormValues} — or nothing when no file was chosen.
+*
+* **`upload` is what a workflow input wants.** A run's input is serialized into
+* the run record and replayed from it on every resume, so a file's BYTES cannot
+* travel in it. With `upload` the field contributes the `File` itself,
+* `useWorkflowSubmit` stores it through `POST /workflows/uploads` before
+* starting the run, and the input carries the upload id — which a step reads
+* windows of with `readUpload`. Declaring the property in the workflow's
+* `uploads` list makes `<WorkflowFields>` render exactly this, so a declared
+* form needs no file markup at all.
+*
+* **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.
+*
+* @public
+*/
+function FileField({ name, label, hint, className, read = "none", upload = false, ...rest }) {
+	const id = useId();
+	const control = useFileControlProps();
+	return /* @__PURE__ */ jsx(Field, {
+		label,
+		hint,
+		htmlFor: id,
+		className,
+		children: /* @__PURE__ */ jsx("input", {
+			id,
+			name,
+			type: "file",
+			"data-aai-read": upload ? "upload" : read,
+			...control,
+			...rest
+		})
+	});
+}
+/**
+* The form's submit button, disabled and relabelled while a submit is in
+* flight.
+*
+* @public
+*/
+function SubmitButton({ children, pending = false, pendingLabel = "Working…", size, className }) {
+	return /* @__PURE__ */ jsx(Button, {
+		type: "submit",
+		disabled: pending,
+		...omitUndefined({
+			size,
+			className
+		}),
+		children: pending ? pendingLabel : children
+	});
+}
+//#endregion
+//#region workflow-client.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.
+*
+* @public
+*/
+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 _sse.ts
+/**
+* The server-sent-event parser both workflow streams read through.
+*
+* Split out when the second stream arrived: `workflow-events.ts` watches a run's
+* STATE and `use-workflow-progress.ts` reads what the run WROTE, and they parse
+* the identical wire format. A second copy of a stream parser is the kind of
+* duplication that goes wrong quietly — the two would drift on exactly the edges
+* documented below, and the symptom is a page that silently stops updating.
+*
+* @internal
+*/
+/**
+* Parse an SSE byte stream into frames, with `eventsource-parser`.
+*
+* The parser is `aai-studio-client`'s already (`src/api-events.ts`), and it is
+* catalogued — plus a transitive dependency of `@ai-sdk/provider-utils`, so it
+* is in this package's tree either way. Adopting it retired a hand-rolled line
+* splitter justified on the subset in use being "small and fixed" — true of our
+* own server, and not of what sits between it and the page:
+*
+* - It split on `"\n\n"` only. The spec permits `\n`, `\r\n` and `\r`, and a
+*   CRLF stream is `\r\n\r\n` — no two adjacent `\n`, so **not one frame ever
+*   parsed** and `pump` fell through to `"fallback"` on the clean end. Silently
+*   dropping to the poll is the exact cost the run-watch stream exists to avoid,
+*   and an intermediary re-terminating lines is not our choice to make.
+* - `line.startsWith("event: ")` required the space the spec makes optional.
+* - It kept only the LAST `data:` line rather than joining a multi-line one.
+*
+* Those three are what `workflow-events.test.ts` pins, and they are the three
+* that DISCRIMINATE — checked by running the specs against the old parser.
+* Comment frames and a leading BOM were already fine and are not credited here:
+* a heartbeat has no `event:` line, so the old parser dropped it anyway, and
+* `TextDecoder` strips the BOM before either parser sees a byte.
+*
+* Three properties of the parser this leans on. `feed` invokes `onEvent`
+* SYNCHRONOUSLY for every complete event in the chunk, so a batch is collected
+* per read and yielded in arrival order — the generator shape, and therefore
+* every caller, is unchanged. An event with no `data:` line at all is not
+* dispatched (also per spec); every frame these routes emit carries one, since
+* `workflow-api-events.ts` and `workflow-api-stream.ts` write `event:` and
+* `data:` together. And a chunk ending in a lone `\r` holds that byte back,
+* because it may yet turn out to be the first half of a `\r\n` — so a CR-ONLY
+* stream chunked per frame dispatches one frame behind, and its last frame not
+* at all (it would need `reset({ consume: true })`, which would also consume a
+* genuinely truncated frame as if it were whole). Nothing emits CR-only endings,
+* and the outcome if anything did is the safe one for both readers: a stream
+* that ends with no final frame is read as a dropped connection, which the run
+* watch answers by falling back to the poll and the progress reader by
+* re-opening.
+*/
+async function* sseFrames(body, signal) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let batch = [];
+	const parser = createParser({ onEvent: ({ event, data }) => {
+		if (event === void 0) return;
+		batch.push({
+			event,
+			data: safeJsonParse$1(data)
+		});
+	} });
+	try {
+		while (!signal.aborted) {
+			const { done, value } = await reader.read();
+			if (done) return;
+			parser.feed(decoder.decode(value, { stream: true }));
+			if (batch.length === 0) continue;
+			const frames = batch;
+			batch = [];
+			for (const frame of frames) yield frame;
+		}
+	} finally {
+		reader.cancel().catch(() => void 0);
+	}
+}
+//#endregion
+//#region workflow-events.ts
+/**
+* Watching a run over server-sent events — the PUSH half of `useWorkflowRun`.
+*
+* 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.
+*
+* @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 sseFrames(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
+	]);
+	return {
+		run,
+		error,
+		polling: runId !== void 0 && !stopped && !isTerminal$1(run)
+	};
+}
+//#endregion
+//#region use-workflow-form.ts
+/**
+* The two hooks a FORM needs, as against the one a status view does.
+*
+* `useWorkflowRun` (`workflow-client.ts`) watches a run you already have.
+* These two are what comes before it: `useWorkflows` reads the declared
+* workflows so `<WorkflowFields>` can render a form from a schema, and
+* `useWorkflowSubmit` starts a run and hands the id straight to
+* `useWorkflowRun`.
+*
+* ## `useWorkflowSubmit` — a form's two halves in one hook
+*
+* A page that submits a workflow always needs the same four pieces of state:
+* the run id, whether a submit is in flight, whether the RUN is still going, and
+* whichever of the two failed. `link-digest` writes them out by hand, which is
+* the right shape for a template teaching the primitives and the wrong shape to
+* write a third time — and it is easy to get subtly wrong: dropping the previous
+* run id before the new `POST` returns is what stops a finished result sitting
+* under a form that is already submitting again.
+*
+* So this is `api.start` plus {@link useWorkflowRun}, with the state between
+* them. It adds no transport of its own and holds no run state of its own; the
+* watching (stream first, poll as its fallback, terminal stops) is entirely
+* `useWorkflowRun`'s, and `run` here IS its run.
+*
+* ## Why it starts ASYNCHRONOUSLY even though a synchronous call exists
+*
+* `api.startAndWait` would collapse this to one request, and it is the wrong
+* default for a page: it holds a socket open for up to a minute, answers nothing
+* until it settles, and a page has `useWorkflowRun` — which survives a reload,
+* shows progress, and costs one stream. The synchronous call is for callers with
+* nowhere to put a watch (a script, a cron, a form POST from a server). Pass
+* `wait` here when the page really does want one request, and the run is
+* followed from the same id either way.
+*/
+/**
+* Read the agent's declared workflows.
+*
+* What `<WorkflowFields>` renders a form FROM: each summary carries the JSON
+* Schema of that workflow's input, converted server-side precisely so a browser
+* can read it.
+*
+* The failure is reported rather than swallowed, because the alternative is an
+* 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.
+*
+* @public
+*/
+function useWorkflows(opts = {}) {
+	const { api, skip = false } = opts;
+	const [state, setState] = useState({
+		workflows: [],
+		loading: !skip,
+		error: void 0
+	});
+	const getClient = useWorkflowApiRef(api);
+	useEffect(() => {
+		if (skip) return;
+		let cancelled = false;
+		getClient().list().then((workflows) => {
+			if (!cancelled) setState({
+				workflows,
+				loading: false,
+				error: void 0
+			});
+		}).catch((err) => {
+			if (cancelled) return;
+			setState({
+				workflows: [],
+				loading: false,
+				error: errorMessage(err)
+			});
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [skip, getClient]);
+	return state;
+}
+/**
+* Replace every `File` in a submitted form with the id of a stored upload.
+*
+* Sequential rather than `Promise.all`: these are large bodies, and a form with
+* two 200 MB recordings should send them one after another rather than compete
+* for the same connection.
+*
+* Anything that is not a `File` (or an array of them) passes through untouched,
+* so this is invisible to every form that has none — including one whose values
+* are not an object at all, which `submit` accepts.
+*/
+async function uploadFiles(api, input) {
+	if (!isRecord(input)) return input;
+	const entries = Object.entries(input);
+	const out = {};
+	for (const [name, value] of entries) if (value instanceof File) out[name] = (await api.upload(value)).id;
+	else if (Array.isArray(value) && value.length > 0 && value.every((one) => one instanceof File)) {
+		const ids = [];
+		for (const file of value) ids.push((await api.upload(file)).id);
+		out[name] = ids;
+	} else out[name] = value;
+	return out;
+}
+/**
+* Start a workflow from a form, and follow the run it creates.
+*
+* @typeParam R - The workflow's output type, which is what makes
+*   `run.status === "completed"` narrow to a typed `run.output`. Derive it with
+*   `WorkflowOutputOf<typeof myWorkflow>`.
+*
+* @example
+* ```tsx
+* import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+*
+* function DigestForm() {
+*   const { submit, run, pending, error } = useWorkflowSubmit("digest");
+*   return (
+*     <Form onSubmit={(values) => submit(values)} error={error}>
+*       <TextField name="url" label="Link" type="url" required />
+*       <SubmitButton pending={pending}>Digest</SubmitButton>
+*       {run?.status === "completed" && <p>Done.</p>}
+*     </Form>
+*   );
+* }
+* ```
+*
+* @public
+*/
+function useWorkflowSubmit(workflow, opts = {}) {
+	const { api, key, wait, intervalMs } = opts;
+	const [runId, setRunId] = useState(void 0);
+	const [starting, setStarting] = useState(false);
+	const [startError, setStartError] = useState(void 0);
+	const getClient = useWorkflowApiRef(api);
+	const tracked = useWorkflowRun(runId, {
+		...api && { api },
+		...omitUndefined({ intervalMs })
+	});
+	return {
+		submit: useCallback(async (input) => {
+			const client = getClient();
+			setStarting(true);
+			setStartError(void 0);
+			setRunId(void 0);
+			try {
+				const options = omitUndefined({ key });
+				const started = await uploadFiles(client, input);
+				setRunId(wait === void 0 ? await client.start(workflow, started, options) : (await client.startAndWait(workflow, started, {
+					...options,
+					wait
+				})).runId);
+			} catch (err) {
+				setStartError(errorMessage(err));
+			} finally {
+				setStarting(false);
+			}
+		}, [
+			workflow,
+			key,
+			wait,
+			getClient
+		]),
+		reset: useCallback(() => {
+			setRunId(void 0);
+			setStartError(void 0);
+		}, []),
+		run: tracked.run,
+		pending: starting || tracked.polling,
+		error: startError ?? tracked.error
+	};
+}
+//#endregion
+//#region components/workflow-fields.tsx
+/**
+* Render one field per scalar property of a workflow's input schema.
+*
+* Pass the workflow's NAME and the schema is fetched here; pass a
+* {@link WorkflowSummary} you already hold and nothing is fetched. The name form
+* is the one a page usually wants — it is the same string the submit hook takes,
+* and the alternative is three lines (`useWorkflows()`, a `.find()` by name, and
+* folding that lookup's error into the form's) whose only product is this
+* component's argument.
+*
+* Renders nothing when the workflow declared no schema — a workflow with no
+* declared input takes anything, and a form for "anything" is not a form — and
+* nothing while a named lookup is still in flight, so the hand-written fields
+* beside it are not reordered when the schema lands.
+*
+* @example
+* ```tsx
+* import { Form, SubmitButton, WorkflowFields, useWorkflowSubmit }
+*   from "@alexkroman1/aai-ui";
+*
+* function StartRun() {
+*   const { submit, pending, error } = useWorkflowSubmit("transcribe");
+*   return (
+*     <Form onSubmit={(values) => submit(values)} error={error}>
+*       <WorkflowFields workflow="transcribe" />
+*       <SubmitButton pending={pending}>Transcribe</SubmitButton>
+*     </Form>
+*   );
+* }
+* ```
+*
+* @public
+*/
+function WorkflowFields({ workflow }) {
+	const { workflows } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
+	const summary = typeof workflow === "string" ? workflows.find((entry) => entry.name === workflow) : workflow;
+	const schema = asObjectSchema(summary?.inputSchema);
+	if (!schema?.properties) return null;
+	const required = new Set(schema.required ?? []);
+	const uploads = new Set(summary?.uploads ?? []);
+	return /* @__PURE__ */ jsx(Fragment, { children: Object.entries(schema.properties).map(([name, property]) => /* @__PURE__ */ jsx(SchemaField, {
+		name,
+		property,
+		required: required.has(name),
+		upload: uploads.has(name)
+	}, name)) });
+}
+/** One property's control, or nothing when its type has no obvious one. */
+function SchemaField({ name, property, required, upload = false }) {
+	const label = humanize(name);
+	const hint = property.description === void 0 ? {} : { hint: property.description };
+	const defaults = property.default === void 0 ? {} : { defaultValue: String(property.default) };
+	if (upload) return /* @__PURE__ */ jsx(FileField, {
+		name,
+		label,
+		required,
+		upload: true,
+		...hint
+	});
+	if (Array.isArray(property.enum) && property.enum.length > 0) return /* @__PURE__ */ jsx(SelectField, {
+		name,
+		label,
+		required,
+		options: property.enum.map((value) => String(value)),
+		...hint,
+		...defaults
+	});
+	switch (typeOf(property)) {
+		case "boolean": return /* @__PURE__ */ jsx(CheckboxField, {
+			name,
+			label,
+			defaultChecked: property.default === true,
+			...hint
+		});
+		case "number":
+		case "integer": return /* @__PURE__ */ jsx(NumberField, {
+			name,
+			label,
+			required,
+			step: typeOf(property) === "integer" ? 1 : "any",
+			...hint,
+			...defaults
+		});
+		case "string": return /* @__PURE__ */ jsx(TextField, {
+			name,
+			label,
+			required,
+			...hint,
+			...defaults
+		});
+		default: return null;
+	}
+}
+/** A property's type, taking the first non-null member of a union. */
+function typeOf(property) {
+	const { type } = property;
+	if (typeof type === "string") return type;
+	return Array.isArray(type) ? type.find((member) => member !== "null") : void 0;
+}
+/** The listing's `unknown` schema as the object shape this reads, when it is one. */
+function asObjectSchema(schema) {
+	return isRecord(schema) ? schema : void 0;
+}
+/**
+* A property name as a label — `recordingId` → `Recording id`.
+*
+* A default, not a policy: a schema whose labels matter should carry a
+* `.describe()`, and an author who wants exact control writes the field.
+*/
+function humanize(name) {
+	const spaced = name.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim().toLowerCase();
+	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 sseFrames(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 */
+/**
+* What a run has said so far, rendered.
+*
+* The complement of a status line, and the reason both exist: a run is
+* `running` for its whole life, so a one-round job and a ten-round one look
+* identical while they happen. These lines come from the run itself (`report()`
+* in a `"use step"` body), which is the only channel a workflow has before it
+* produces an output.
+*
+* Three rules are baked in, and they are why this is a component rather than
+* three lines each page writes for itself — the two templates that had written
+* it had written all three, comments included:
+*
+* - **It renders nothing until there is something to render.** `supported` is
+*   what keeps this from being an empty box forever on an agent deployed before
+*   progress streams existed: "wrote nothing yet" and "serves no stream" are
+*   indistinguishable from the chunk list alone.
+* - **The lines are TEXT, not elements.** They are append-only and two rounds
+*   legitimately produce identical text, so there is no stable per-line key to
+*   give React. Joining sidesteps the question instead of suppressing the lint
+*   rule that asks it.
+* - **They REPLAY.** Chunks are retained with the run, so a reload mid-run —
+*   or opening a finished run tomorrow — shows how it got there rather than an
+*   empty box. That is `useWorkflowProgress`'s doing; this is what makes it
+*   visible.
+*
+* @example
+* ```tsx
+* import { WorkflowProgress } from "@alexkroman1/aai-ui";
+*
+* function RunPanel({ runId }: { runId: string }) {
+*   return <WorkflowProgress runId={runId} />;
+* }
+* ```
+*
+* @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.
+*
+* @public
+*/
+function WorkflowProgress({ runId, api, className, placeholder }) {
+	const { progress, streaming, supported } = useWorkflowProgress(runId, api ? { api } : {});
+	if (!supported || progress.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…"]
+	});
+}
+//#endregion
+//#region page.tsx
+/** @jsxImportSource react */
+/**
+* `page()` — mount a WORKFLOW APP's UI: React, theme, no session.
+*
+* The twin of `client()` for an agent whose front door is a form rather than a
+* microphone (`workflowApp()`). It is a separate entry rather than
+* an option on `client()` because of what `client()` unavoidably does: it
+* constructs a `SessionCore`, which owns a WebSocket URL provider, an audio
+* graph, and a microphone request. A flag would have to make all of that
+* conditional, and every session hook would then have to answer "what does this
+* mean with no session?" — so the honest split is two mounts. A page that wants
+* voice uses `client()`; a page that wants neither audio nor a socket uses this.
+*
+* Authoring is otherwise identical — the file is still `client.tsx`, still
+* React, still Tailwind, still the same theme tokens — so a workflow app reads
+* like every other agent. What it reaches for instead of `useSession()` is
+* `createWorkflowApi()` / `useWorkflowRun()`.
+*/
+/**
+* Mount a page for an agent whose work happens in workflows.
+*
+* There is deliberately no session, no microphone, and no socket: the component
+* talks to the agent over the workflow HTTP API
+* (`createWorkflowApi`/`useWorkflowRun`), which is durable and outlives the tab.
+*
+* @example
+* ```tsx
+* import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
+* import { useState } from "react";
+*
+* // Hoisted: a client built in render is a new object every render.
+* const api = createWorkflowApi();
+*
+* function App() {
+*   const [runId, setRunId] = useState<string>();
+*   const { run } = useWorkflowRun(runId, { api });
+*   return (
+*     <button
+*       type="button"
+*       onClick={() => void api.start("digest", { topic: "ai" }).then(setRunId)}
+*     >
+*       {run ? run.status : "Start"}
+*     </button>
+*   );
+* }
+*
+* page({ name: "Digest", component: App });
+* ```
+*
+* @throws If the target element is not found in the DOM.
+*
+* @public
+*/
+function page(config) {
+	const container = resolveContainer(config.target);
+	if (config.name && typeof document !== "undefined") document.title = config.name;
+	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.
+*
+* @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>;
+* }
+* ```
+*
+* @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;
+}
+//#endregion
+//#region use-workflow-runs.ts
+/**
+* The RUNS a workflow has had — the list a page shows beside its form.
+*
+* `useWorkflowRun` watches one run you already hold an id for, which is the
+* right shape for the run a page just started and the wrong one for everything
+* before it. A workflow app that only offers that leaves its own history
+* unreachable: a page reload drops the id, and the only way back to yesterday's
+* transcript is to have written the id down — which is what
+* `transcription-workflow` asked people to do, with a text box for pasting one.
+*
+* `GET /workflows/runs?workflow=…` has always been able to answer this. This is
+* the hook over it, so a page renders history instead of asking for an id.
+*
+* ## It re-reads on demand, and does not poll on its own
+*
+* A list is not a live view: the run a page cares about right now is already
+* being watched by `useWorkflowRun`, and a second polling loop over the whole
+* history would broker N requests a minute on the platform to re-learn what the
+* first one already knows. So this reads once and hands back `refresh` — which
+* a page calls when its own run settles, which is exactly when the list is
+* stale.
+*/
+/**
+* Read a workflow's recent runs.
+*
+* @typeParam R - The workflow's output type, so a completed run's `output` is
+*   typed rather than `unknown`. Derive it with `WorkflowOutputOf`.
+*
+* @example
+* ```tsx
+* import { useWorkflowRuns } from "@alexkroman1/aai-ui";
+*
+* function History() {
+*   const { runs } = useWorkflowRuns("transcribe", { limit: 10 });
+*   return <ul>{runs.map((run) => <li key={run.runId}>{run.status}</li>)}</ul>;
+* }
+* ```
+*
+* @public
+*/
+function useWorkflowRuns(workflow, opts = {}) {
+	const { api, limit, key, skip = false } = opts;
+	const [runs, setRuns] = useState([]);
+	const [loading, setLoading] = useState(!skip && workflow !== void 0);
+	const [error, setError] = useState(void 0);
+	const getClient = useWorkflowApiRef(api);
+	/**
+	* Every read carries the epoch it started in, and a read from an earlier one
+	* is DROPPED.
+	*
+	* Bumped by the unmount AND by each read as it starts, which is the half that
+	* was missing: with only the cleanup bumping, two `refresh()` calls captured
+	* the SAME epoch, so a slow earlier read overwrote a newer one's answer with
+	* a staler list — the exact case the drop exists for.
+	*/
+	const epochRef = useRef(void 0);
+	epochRef.current ??= createEpoch();
+	const epoch = epochRef.current;
+	const load = useCallback(() => {
+		if (skip || workflow === void 0) return;
+		const client = getClient();
+		epoch.bump();
+		const mine = epoch.current();
+		setLoading(true);
+		const options = limit === void 0 ? void 0 : { limit };
+		(key === void 0 ? client.recent(workflow, options) : client.find(workflow, key, options)).then((found) => {
+			if (!epoch.isCurrent(mine)) return;
+			setRuns(found);
+			setError(void 0);
+			setLoading(false);
+		}).catch((err) => {
+			if (!epoch.isCurrent(mine)) return;
+			setError(errorMessage(err));
+			setLoading(false);
+		});
+	}, [
+		workflow,
+		limit,
+		key,
+		skip,
+		getClient,
+		epoch
+	]);
+	useEffect(() => {
+		load();
+		return () => {
+			epoch.bump();
+		};
+	}, [load, epoch]);
+	return {
+		runs,
+		loading,
+		error,
+		refresh: load
+	};
+}
+//#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, VOICE_CAPTURE_CONSTRAINTS, WorkflowFields, WorkflowProgress, buildAgentUrl, client, createSessionCore, createWorkflowApi, fetchClientConfig, isTerminal, loadClientConfig, page, useAgentState, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowSubmit, useWorkflows };