@alexkroman1/aai-ui 13.2.0 → 14.0.0

package/dist/index.js

@@ -1,26 +1,190 @@
-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-BJYyuIcR.js";
-import { ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
-import { r as inkTint } from "./_colors-j8XMToi9.js";
+import { n as fetchClientConfig } from "./client-config-DJQHnYjm.js";
+import { i as AutoScroll, n as Markdown, r as useConversation, t as MessageList } from "./message-list-CdOnSh5m.js";
+import { ThemeProvider, useSession, useSessionActions, useSessionError, useSessionSelector, useSessionStatus, useTheme } from "./context.js";
+import { a as inkTint, i as focusRingStyle, n as FOCUS_RING } from "./_colors-CpZO-88A.js";
 import { Button } from "./components/button.js";
-import { n as ConsoleShell, t as ChatView } from "./chat-view-DDTtrh7N.js";
-import { n as setPageTitle } from "./_utils-B6498_bm.js";
+import { n as ConsoleShell, r as SessionErrorBanner, t as ChatView } from "./chat-view-C_3T7Ln8.js";
+import { n as setPageTitle } from "./_utils-DnQDM9Uy.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-tcPQAkcP.js";
+import { n as useUserTranscript } from "./use-user-transcript-uyHhzy4d.js";
+import { n as ToolCallRow } from "./tool-call-block-C2t_5fpp.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { a as useWorkflowRun, c as isTerminal, n as useWorkflowProgress, o as useWorkflowApiRef, s as createWorkflowApi } from "./use-workflow-progress-Cu0SxMyg.js";
-import { t as createSessionCore } from "./session-core-DxBYsfHA.js";
-import { client, mountRoot, resolveContainer } from "./define-client.js";
+import { a as useWorkflowProgress, c as isTerminal, o as useWorkflowApiRef, r as useWorkflowRun, s as createWorkflowApi } from "./use-workflow-run-CP2ekKPV.js";
+import { i as urlSlot, n as storageGet, r as storageSet, t as createBrowserSession } from "./session-core-gwePM95B.js";
+import { mountClient, 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 { createContext, createElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
 import { errorMessage } from "@alexkroman1/aai";
 import { formatBytes, isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { createEpoch } from "@alexkroman1/aai/internal";
-//#region components/_form-readiness.ts
+//#region src/agent-state-labels.ts
+/**
+* The default label per {@link AgentState}.
+*
+* Override the ones your page has a better word for and keep the rest:
+*
+* ```ts
+* import type { AgentState } from "@alexkroman1/aai-ui";
+* import { AGENT_STATE_LABELS } from "@alexkroman1/aai-ui";
+*
+* // A dispatch board that shouts, and renames one state.
+* const STATE_LABEL = { ...AGENT_STATE_LABELS, thinking: "Processing" };
+* const shout = (s: AgentState) => STATE_LABEL[s].toUpperCase();
+* ```
+*
+* **Sentence case, deliberately.** A template that wants caps applies its own
+* `.toUpperCase()`, and a template that wants Title Case is already there;
+* shipping the shouted form instead would leave the two chromes that do not
+* shout with a string they have to un-shout, which no case transform does
+* correctly.
+*
+* Two wordings are decisions rather than transliterations of the member name:
+*
+* - `disconnected` is **"Idle"**. It is the state a session is in BEFORE it has
+*   ever started as well as after it ends, so it is the first word most callers
+*   see; "Disconnected" reads as a fault on a page where nothing has gone
+*   wrong yet. Both chromes that mapped this state by hand chose "Idle" too.
+* - `connecting` and `thinking` carry an ellipsis, `listening` and `speaking`
+*   do not. The first two are waits with nothing for the caller to do; the
+*   other two describe someone actually talking. Same distinction
+*   `WORKFLOW_STATUS_LABELS` draws with its one "Working…".
+*
+* @public
+*/
+const AGENT_STATE_LABELS = {
+	disconnected: "Idle",
+	connecting: "Connecting…",
+	ready: "Ready",
+	listening: "Listening",
+	thinking: "Thinking…",
+	speaking: "Speaking",
+	error: "Error"
+};
+//#endregion
+//#region src/components/bullet-list.tsx
+/** @jsxImportSource react */
+/**
+* A disc-bulleted list of short strings — a run's key points, findings, risks.
+*
+* Five pages had written this, byte-identical apart from a `text-sm` suffix on
+* two of them, and all five had the same two defects. Both are the reason this
+* is a component rather than four lines a page repeats:
+*
+* - **All five keyed by the string itself, and these lists are MODEL OUTPUT.**
+*   Two identical bullets are entirely plausible — a summariser that repeats
+*   itself is a bad summary, not a bad program — and a repeated string is then
+*   a duplicate `key`: React warns, and the two `<li>`s contend for one slot in
+*   the reconciliation. What is keyed here instead is the content PLUS how many
+*   times that content has already appeared in this list, which is unique by
+*   construction and unchanged by a re-render that did not change the text.
+*   (Position alone would also be sound — these lists are replaced wholesale by
+*   each new output and never reordered — but it is what `noArrayIndexKey`
+*   exists to talk you out of, and a unique key is one `Map` away, so there is
+*   no reason to spend a lint suppression on it.)
+* - **Three of the five rendered an empty `<ul>` under a heading.** Two had
+*   hand-rolled `if (items.length === 0) return null` and three had not, so the
+*   same absent field was "nothing" on two pages and a stray heading with a
+*   void under it on three. Emptiness renders NOTHING here, `title` included:
+*   a heading over no bullets is a claim the run did not make.
+*
+* @example
+* ```tsx
+* import { BulletList } from "@alexkroman1/aai-ui";
+*
+* function Findings({ risks }: { risks: string[] }) {
+*   return <BulletList title="Risks" items={risks} size="sm" />;
+* }
+* ```
+*
+* @param props - Bullet-list props.
+*
+* @public
+*/
+function BulletList({ items, title, size = "base", className }) {
+	if (items.length === 0) return null;
+	const seen = /* @__PURE__ */ new Map();
+	const list = /* @__PURE__ */ jsx("ul", {
+		className: clsx("flex list-disc flex-col gap-1 pl-5", size === "sm" && "text-sm", className),
+		children: items.map((item) => {
+			const nth = seen.get(item) ?? 0;
+			seen.set(item, nth + 1);
+			return /* @__PURE__ */ jsx("li", { children: item }, `${nth}:${item}`);
+		})
+	});
+	const heading = title === void 0 || title === null || title === false ? void 0 : title;
+	if (heading === void 0) return list;
+	return /* @__PURE__ */ jsxs("section", {
+		className: "flex flex-col gap-1",
+		children: [/* @__PURE__ */ jsx("h3", {
+			className: "text-sm font-medium opacity-70",
+			children: heading
+		}), list]
+	});
+}
+//#endregion
+//#region src/components/facts.tsx
+/** @jsxImportSource react */
+/** What goes between two facts. A separator, not a bullet — U+00B7, not U+2022. */
+const FACT_SEPARATOR = " · ";
+/**
+* A muted line of run facts, joined by `·` — "6 segments · 12:04 of audio ·
+* 1,840 words".
+*
+* Nine pages had written this by hand under four different typographies for
+* one role, two of them (`call-audit` and `spoken-summary`) byte-identical down
+* to the payload. Three things it takes off the caller:
+*
+* - **The separator cannot be forgotten, and neither can the space around it.**
+*   Four of the nine carried a literal `{" "}` at the end of a line, because
+*   Prettier's wrap ate the space that made `· ` read as a separator rather
+*   than as punctuation glued to the next word. A line that is correct only
+*   because somebody remembered an invisible JSX expression is exactly the
+*   thing a component should own.
+* - **A fact worth omitting is omitted, and by the caller's own condition.**
+*   The hand-written shape for a conditional fact was to splice the separator
+*   into the string — `{x ? \` · budget exhausted\` : ""}` — which puts the
+*   punctuation in two places and gets the leading separator wrong the moment
+*   the fact before it also disappears. Passing the condition and letting this
+*   drop it keeps the separator in one place.
+* - **A line with nothing left to say renders NOTHING.** With every fact
+*   conditional, the alternative is a muted empty row, or a bare `·`.
+*
+* The facts are JOINED into one string rather than interleaved as elements, and
+* that is why the prop is text: joined, there is no per-fact `key` to invent —
+* the same reasoning `WorkflowProgress` gives for its log lines. A line that
+* genuinely needs an element in it (a link) wants its own markup.
+*
+* @example
+* ```tsx
+* import { Facts } from "@alexkroman1/aai-ui";
+*
+* function RunFacts({ words, cut }: { words: number; cut: number }) {
+*   return <Facts size="xs" items={[`${words} words`, cut > 0 && `${cut} blind cuts`]} />;
+* }
+* ```
+*
+* @param props - Facts-line props.
+*
+* @public
+*/
+function Facts({ items, size = "sm", as = "p", className }) {
+	const shown = items.filter((item) => item !== false && item !== null && item !== void 0 && item !== "");
+	if (shown.length === 0) return null;
+	const text = shown.join(FACT_SEPARATOR);
+	const classes = clsx(size === "xs" ? "text-xs opacity-60" : "text-sm opacity-70", className);
+	return as === "span" ? /* @__PURE__ */ jsx("span", {
+		className: classes,
+		children: text
+	}) : /* @__PURE__ */ jsx("p", {
+		className: classes,
+		children: text
+	});
+}
+//#endregion
+//#region src/components/_form-readiness.ts
 /**
 * Whether a form's own fields exist yet.
 *
@@ -47,7 +211,7 @@ import { createEpoch } from "@alexkroman1/aai/internal";
 * one describes an element that EXISTS. So this is a context rather than an
 * attribute, and it carries the one fact a DOM read cannot recover.
 *
-* A form with no such children is ready by definition — `useFormFieldsPending`
+* A form with no such children is ready by definition — `useFormReadiness`
 * outside a provider reports nothing pending, so every hand-written form is
 * unaffected and `Form` keeps working outside this package.
 */
@@ -106,7 +270,7 @@ function useDeclareFieldsPending(pending) {
 	]);
 }
 //#endregion
-//#region components/_form-values.ts
+//#region src/components/_form-values.ts
 /**
 * Read one `<form>`'s named controls into a plain object.
 *
@@ -173,7 +337,7 @@ 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"`. */
+/** The `data-aai-read` attribute as a {@link FileReadMode}, defaulting to `"none"`. */
 function readMode(raw) {
 	return raw === "text" || raw === "dataUrl" || raw === "upload" ? raw : "none";
 }
@@ -201,7 +365,7 @@ function dataUrl(file) {
 	});
 }
 //#endregion
-//#region components/form-fields.tsx
+//#region src/components/form-fields.tsx
 /** @jsxImportSource react */
 /**
 * The controls a form is made of — the shell, the six fields, and the styling
@@ -274,12 +438,12 @@ function Field({ label, hint, htmlFor, className, children }) {
 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"),
+		className: clsx("w-full rounded-aai border px-3 py-2 text-sm font-aai", FOCUS_RING, "disabled:cursor-not-allowed disabled:opacity-50"),
 		style: {
 			background: theme.surface,
 			color: theme.text,
 			borderColor: theme.border,
-			outlineColor: theme.primary
+			...focusRingStyle(theme.primary)
 		}
 	};
 }
@@ -311,16 +475,14 @@ 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.
+* `TextField` and `NumberField`, which differ only in the `type` they set.
 *
-* @public
+* Internal, because the two stay separate PUBLIC exports: each is named in the
+* `components` capability contract and in the API report, and a caller writes
+* the one whose value shape it wants — `NumberField` is the one that
+* contributes a number to {@link FormValues}.
 */
-function TextField({ name, label, hint, className, ...rest }) {
+function InputField({ defaultType, name, label, hint, className, ...rest }) {
 	const id = useId();
 	const control = useControlProps();
 	return /* @__PURE__ */ jsx(Field, {
@@ -331,13 +493,29 @@ function TextField({ name, label, hint, className, ...rest }) {
 		children: /* @__PURE__ */ jsx("input", {
 			id,
 			name,
-			type: "text",
+			type: defaultType,
 			...control,
 			...rest
 		})
 	});
 }
 /**
+* 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(props) {
+	return /* @__PURE__ */ jsx(InputField, {
+		defaultType: "text",
+		...props
+	});
+}
+/**
 * A number input. Contributes a NUMBER to {@link FormValues}, or nothing when
 * left empty.
 *
@@ -349,21 +527,10 @@ function TextField({ name, label, hint, className, ...rest }) {
 *
 * @public
 */
-function NumberField({ name, label, hint, className, ...rest }) {
-	const id = useId();
-	const control = useControlProps();
-	return /* @__PURE__ */ jsx(Field, {
-		label,
-		hint,
-		htmlFor: id,
-		className,
-		children: /* @__PURE__ */ jsx("input", {
-			id,
-			name,
-			type: "number",
-			...control,
-			...rest
-		})
+function NumberField(props) {
+	return /* @__PURE__ */ jsx(InputField, {
+		defaultType: "number",
+		...props
 	});
 }
 /**
@@ -474,14 +641,14 @@ function CheckboxField({ name, label, hint, className, ...rest }) {
 * 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
+* windows of with `stepReadUpload`. 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. See
-* {@link FileRead} for the four values; `upload` is shorthand for
+* {@link FileReadMode} for the four values; `upload` is shorthand for
 * `read="upload"`.
 *
 * Otherwise accepts every `<input>` attribute except `name`, `className` and
@@ -512,7 +679,7 @@ function FileField({ name, label, hint, className, read = "none", upload = false
 	});
 }
 //#endregion
-//#region components/form.tsx
+//#region src/components/form.tsx
 /** @jsxImportSource react */
 /**
 * Simple forms, for the pages that are not conversations.
@@ -654,7 +821,7 @@ function SubmitButton({ children, pending = false, pendingLabel = "Working…",
 	});
 }
 //#endregion
-//#region components/upload-progress.tsx
+//#region src/components/upload-progress.tsx
 /** @jsxImportSource react */
 /**
 * The track behind the fill, as a tint of the theme's own ink.
@@ -766,1287 +933,1418 @@ function UploadProgressBar({ upload, onPause, onResume, className }) {
 	});
 }
 //#endregion
-//#region _recover-run.ts
+//#region src/use-workflows.ts
 /**
-* Finding a run again when the page has lost its id.
-*
-* A run is durable and a page is not — which `useWorkflowRun`'s doc says, and
-* which was only half true of the hooks above it: the run id lived in plain
-* `useState`, so a refresh (or a same-tab navigation, or a crashed tab) left a
-* live run with nothing anywhere able to name it. The run really did continue;
-* the person really could not get back to it.
-*
-* `StartOptions.key` is the handle that survives that, and it always was — a
-* caller's own name for a run, indexed by the agent, read back with
-* `find(workflow, key)`. What was missing is the two lines that ASK. This is
-* them, plus the four decisions they turn out to carry.
-*
-* ## It is a MOUNT-time act, not "whenever there is no run"
-*
-* The tempting spelling is "if we hold no run id, look one up", and it breaks
-* `reset()`: a form put back to its initial state holds no run id, so the next
-* pass would re-adopt the very run the person had just dismissed — a Clear
-* button that clears nothing. So the lookup runs once per mount (and again only
-* if the KEY changes, which is a different person's run), and every later
-* absence of a run id is taken at face value.
-*
-* ## The lookup NEVER wins a race against a submit
+* The agent's declared workflows — what a form is rendered FROM.
 *
-* A person who reloads and immediately submits has started the run they want,
-* and an answer that was already in flight names an older one. The caller
-* therefore adopts through `current ?? found`: the recovered id fills an empty
-* slot and never replaces a full one.
+* Split out of `use-workflow-form.ts` at the 500-line cap, along the seam that
+* file's own doc already drew: it held "the two hooks a FORM needs", and only
+* one of them is about a RUN. This is the other one, and it shares nothing with
+* its former neighbours but the client ref every hook here uses — no state, no
+* run id, no upload.
+*/
+/**
+* Read the agent's declared workflows.
 *
-* ## A failed lookup is REPORTED
+* 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 alternative is a page that quietly shows an empty form to somebody whose
-* run is live, who then starts a second one — the duplicated work the key
-* exists to prevent, and on a workflow app that is real money. A person who has
-* never run anything pays a banner they can ignore. Same trade as
-* `useWorkflows`, for the same reason: an empty answer here is a confident
-* false statement.
+* 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.
 *
-* ## It is OPT-IN
+* @example
+* ```tsx
+* import { useWorkflows } from "@alexkroman1/aai-ui";
 *
-* A `key` on its own still means only "record this with the run", which is what
-* a voice agent's `ctx.workflows.start({ key })` means and what a page passing
-* an account id may well want. Adopting a run is a decision about the PAGE, so
-* it is `recover: true` and the two together read as what they do.
-*/
-/**
-* Look up the newest run for a key, once, as the component mounts.
+* // 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 RecoverRunOptions}.
-* @returns Whether the lookup is still out. A caller folds it into its own
-*   `pending`, because a form offering Submit while a live run is arriving is a
-*   form inviting a second one.
+* @param opts - See {@link UseWorkflowsOptions}.
+* @returns The listing, its loading flag and its failure — see
+* {@link UseWorkflowsResult}.
 *
-* @internal
+* @public
 */
-function useRecoveredRun(opts) {
-	const { workflow, key, enabled, getClient } = opts;
-	const [recovering, setRecovering] = useState(enabled && key !== void 0);
-	const handlers = useRef(opts);
-	handlers.current = opts;
+function useWorkflows(opts = {}) {
+	const { api, skip = false } = opts;
+	const [state, setState] = useState({
+		workflows: [],
+		loading: !skip,
+		error: void 0
+	});
+	const getClient = useWorkflowApiRef(api);
 	useEffect(() => {
-		if (!enabled || key === void 0) return;
+		if (skip) return;
 		let cancelled = false;
-		setRecovering(true);
-		getClient().find(workflow, key, { limit: 1 }).then((found) => {
-			if (cancelled) return;
-			const newest = found[0];
-			if (newest !== void 0) handlers.current.onFound(newest.runId);
-			setRecovering(false);
+		getClient().list().then((workflows) => {
+			if (!cancelled) setState({
+				workflows,
+				loading: false,
+				error: void 0
+			});
 		}).catch((err) => {
 			if (cancelled) return;
-			handlers.current.onError(errorMessage(err));
-			setRecovering(false);
+			setState({
+				workflows: [],
+				loading: false,
+				error: errorMessage(err)
+			});
 		});
 		return () => {
 			cancelled = true;
 		};
-	}, [
-		enabled,
-		key,
-		workflow,
-		getClient
-	]);
-	return recovering;
+	}, [skip, getClient]);
+	return state;
 }
 //#endregion
-//#region _run-controls.ts
+//#region src/components/workflow-fields.tsx
+/** @jsxImportSource react */
 /**
-* The two things a page does TO a run it started, bound to the run it has.
+* A form built from a workflow's declared input schema.
 *
-* `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.
+* `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.
 *
-* 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.
+* ## 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}.
 */
 /**
-* Bind `wake` and `cancel` to whatever run the hook is currently following.
+* Render one field per scalar property of a workflow's input schema.
 *
-* @param runId - The live run, or `undefined` before one exists.
-* @param getClient - The stable getter from `useWorkflowApiRef`.
-* @returns Two callbacks, stable while `runId` is.
+* 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.
 *
-* @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.
+* 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.
 *
-* A streamed upload is resumable because its id outlives the attempt that began
-* it — `_upload-files.ts` says so, and `_upload-session.ts` turns that into a
-* pause a person can press. Both of them hold the id in MEMORY: the walk's
-* `UploadSession` lives in a `useRef`, so a reload was the one interruption the
-* mechanism could not survive. Everything else was already in place — the windows
-* were still in the store, the agent could still name them
-* (`UploadInfo.ranges`), and the id was minted in the browser — and the browser
-* had thrown away the only name for them. So a person who refreshed at 90% of a
-* 200 MB recording sent the whole file again, which is the one interruption they
-* are most likely to cause on purpose.
-*
-* This is that name, written down. It is what tus-js-client's `urlStorage` and
-* Uppy's Golden Retriever sell, in the shape `session-resume-store.ts` already
-* uses for a session id.
-*
-* ## A FINGERPRINT, because a `File` has no name a page can address
-*
-* A file from a picker carries no path and no handle, so the key is what
-* tus-js-client fingerprints on: size, last-modified, type and name. Two
-* different files agreeing on all four is the case this cannot tell apart — and
-* the reason NOTHING here decides to resume. `_upload-files.ts` asks the agent
-* what the id actually holds before sending a byte to it, so a wrong hit costs
-* one `GET` and a fresh id rather than a corrupted upload.
-*
-* ## `sessionStorage`, deliberately
-*
-* The same call `session-resume-store.ts` makes, for a reason that happens to be
-* stronger here: a reload and a same-tab navigation are exactly what this is for,
-* and an id from yesterday names an upload the agent's sweep has very likely
-* already collected. A tab is also the boundary the walk itself has — two tabs
-* uploading the same recording are two submissions.
+* @example
+* ```tsx no-check
+* import { Form, SubmitButton, WorkflowFields, useWorkflowSubmit }
+*   from "@alexkroman1/aai-ui";
+* import type { transcribe } from "./agent.ts";
 *
-* Every access is guarded. Storage throws outright in Safari private mode and
-* under a blocking policy, and an upload that cannot be REMEMBERED must degrade
-* to the upload we would have done anyway rather than failing to start.
-*/
-const PREFIX$1 = "aai:upload:";
-/**
-* How many ids one form keeps.
+* function StartRun() {
+*   const { submitForm, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
+*   return (
+*     <Form onSubmit={submitForm} error={error}>
+*       <WorkflowFields workflow="transcribe" />
+*       <SubmitButton pending={pending}>Transcribe</SubmitButton>
+*     </Form>
+*   );
+* }
+* ```
 *
-* A cap rather than an expiry, because `sessionStorage` already expires with the
-* tab and an entry is ~80 bytes. What it bounds is the long-lived tab that
-* submits a hundred files: the oldest go first, and the id most likely to be
-* worth resuming is the one written last.
-*/
-const MAX_REMEMBERED = 32;
-/** One form's slot in storage. */
-function keyFor(scope) {
-	return `${PREFIX$1}${scope}`;
-}
-/**
-* What names this file across a reload.
+* @param props - Field-set props.
 *
-* The four fields a browser gives a picked file that do not change between loads.
-* `name` last because it is the one a person can read in a debugger.
+* @public
 */
-function fingerprint(file) {
-	return `${file.size}:${file.lastModified}:${file.type}:${file.name}`;
+function WorkflowFields({ workflow }) {
+	const { workflows, loading } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
+	const summary = typeof workflow === "string" ? workflows.find((entry) => entry.name === workflow) : workflow;
+	useDeclareFieldsPending(loading);
+	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)) });
 }
-/** This scope's remembered ids, or nothing at all — a parse failure is nothing. */
-function read(scope) {
-	try {
-		const raw = globalThis.sessionStorage?.getItem(keyFor(scope));
-		if (raw === null || raw === void 0) return {};
-		const parsed = JSON.parse(raw);
-		return isRecord(parsed) ? parsed : {};
-	} catch {
-		return {};
+/** 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
+	});
+	const type = typeOf(property);
+	switch (type) {
+		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: type === "integer" ? 1 : "any",
+			...hint,
+			...defaults
+		});
+		case "string": return /* @__PURE__ */ jsx(TextField, {
+			name,
+			label,
+			required,
+			...hint,
+			...defaults
+		});
+		default: return null;
 	}
 }
-function write(scope, entries) {
-	try {
-		globalThis.sessionStorage?.setItem(keyFor(scope), JSON.stringify(entries));
-	} catch {}
+/** 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;
 }
 /**
-* The id this file was last being stored under in this tab, if any.
-*
-* A hit is a CANDIDATE and never a decision — see the module doc.
+* A property name as a label — `recordingId` → `Recording id`.
 *
-* @internal
+* 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 recallUploadId(scope, file) {
-	const found = read(scope)[fingerprint(file)];
-	return typeof found === "string" ? found : void 0;
+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 src/components/workflow-progress.tsx
+/** @jsxImportSource react */
 /**
-* Remember the id this file is being stored under.
+* What a run has said so far, rendered.
 *
-* Called before the first byte leaves rather than after the last one lands: the
-* reload this exists for happens in between, and an id written at the end is an
-* id written for the one case that did not need it.
+* The complement of a status line, and the reason both exist: a run is
+* `running` for its whole life, so a one-round job and a ten-round one look
+* identical while they happen. These lines come from the run itself (`stepReport()`
+* in a `"use step"` body), which is the only channel a workflow has before it
+* produces an output.
 *
-* @internal
-*/
-function rememberUploadId(scope, file, id) {
-	const entries = read(scope);
-	const key = fingerprint(file);
-	delete entries[key];
-	entries[key] = id;
-	const keys = Object.keys(entries);
-	for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_REMEMBERED))) delete entries[stale];
-	write(scope, entries);
-}
-/**
-* Forget it: the agent holds nothing resumable under this id.
+* Four rules are baked in, and they are why this is a component rather than
+* three lines each page writes for itself — the two templates that had written
+* it had written three of them, comments included:
 *
-* The other half of the agent deciding. Without it a swept upload is re-read on
-* every submission of the same file for the life of the tab, which is a round
-* trip spent learning the same 404.
+* - **It renders nothing until there is something to render.** `supported` is
+*   what keeps this from being an empty box forever on an agent deployed before
+*   progress streams existed: "wrote nothing yet" and "serves no stream" are
+*   indistinguishable from the chunk list alone.
+* - **The lines are TEXT, not elements.** They are append-only and two rounds
+*   legitimately produce identical text, so there is no stable per-line key to
+*   give React. Joining sidesteps the question instead of suppressing the lint
+*   rule that asks it.
+* - **They REPLAY.** Chunks are retained with the run, so a reload mid-run —
+*   or opening a finished run tomorrow — shows how it got there rather than an
+*   empty box. That is `useWorkflowProgress`'s doing; this is what makes it
+*   visible.
+* - **They are ANNOUNCED**, for the reason the first paragraph gives: this is
+*   the only channel a run has before it produces an output, and a `<pre>` that
+*   grows is a silent one. A screen-reader user pressing "Digest" got nothing
+*   between the click and a terminal state minutes later — no "fetching", no
+*   "summarising", no evidence the button did anything. See `role="log"` below.
+*   The six pages that render this pass only `className`, so no template could
+*   have fixed it locally; that is what makes it this component's job.
 *
-* @internal
+* @example
+* ```tsx
+* import { WorkflowProgress } from "@alexkroman1/aai-ui";
+*
+* function RunPanel({ runId }: { runId: string }) {
+*   return <WorkflowProgress runId={runId} />;
+* }
+* ```
+*
+* @param props - Progress-log props.
+*
+* @public
 */
-function forgetUploadId(scope, file) {
-	const entries = read(scope);
-	const key = fingerprint(file);
-	if (!(key in entries)) return;
-	delete entries[key];
-	write(scope, entries);
+function WorkflowProgress({ runId, api, className, placeholder, lines }) {
+	const { progress, streaming, supported } = useWorkflowProgress(runId, omitUndefined({ api }));
+	const text = useMemo(() => {
+		const shown = lines === void 0 ? progress : progress.slice(Math.max(progress.length - lines, 0));
+		return shown.length === 0 ? null : shown.join("\n");
+	}, [progress, lines]);
+	if (!supported || text === null) return placeholder ?? null;
+	return /* @__PURE__ */ jsxs("pre", {
+		role: "log",
+		"aria-live": "polite",
+		"aria-atomic": "false",
+		className: clsx(className ?? "whitespace-pre-wrap border-l pl-4 text-xs opacity-70"),
+		children: [text, streaming && "\n…"]
+	});
 }
 //#endregion
-//#region _upload-session.ts
-/** Whether this rejection is an abort, in either of the two shapes runtimes throw. */
-function isAbortError(err) {
-	return err instanceof Error && err.name === "AbortError";
-}
-/** A fresh upload id: a capability, so it is random rather than derived. */
-function randomUploadId() {
-	return crypto.randomUUID().replaceAll("-", "");
-}
+//#region src/page.tsx
+/** @jsxImportSource react */
 /**
-* Send one file, waiting out however many pauses the person takes.
+* `mountPage()` — mount a WORKFLOW APP's UI: React, theme, no session.
 *
-* The loop from the module doc, written once: both hooks need exactly this and a
-* second copy of it is a second place for the abort/pause distinction to be got
-* wrong. `send` is handed whether this attempt must CLAIM the id as its own —
-* false the first time, since a fresh id has nothing to resume and saying
-* otherwise waives the refusal that makes a caller-chosen id safe.
+* The twin of `mountClient()` for an agent whose front door is a form rather than a
+* microphone (`workflowApp()`). It is a separate entry rather than
+* an option on `mountClient()` because of what `mountClient()` unavoidably does: it
+* constructs a `BrowserSession`, 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 `mountClient()`; a page that wants neither audio nor a socket uses this.
 *
-* Throws whatever `send` threw, except an abort the gate caused. A cancelled gate
-* throws too: the caller distinguishes it by reading `gate.cancelled`, which is
-* how an abandoned submission unwinds without being reported as a failure.
+* 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()`.
 */
-async function sendThroughGate(gate, send) {
-	let tried = false;
-	for (;;) {
-		await gate.settle();
-		if (gate.cancelled) throw new Error("Upload cancelled.");
-		const resume = tried;
-		tried = true;
-		try {
-			await send(resume);
-			return;
-		} catch (err) {
-			if (gate.cancelled || !isAbortError(err)) throw err;
-		}
-	}
-}
 /**
-* A gate, open.
+* Mount a page for an agent whose work happens in workflows.
 *
-* One per upload rather than one per hook: the id and the windows already stored
-* belong to a file, so a gate that outlived its file would resume something else.
-*/
-function createUploadGate() {
-	let controller = new AbortController();
-	let paused = false;
-	let cancelled = false;
-	let open;
-	let closed;
-	return {
-		get paused() {
-			return paused;
-		},
-		get cancelled() {
-			return cancelled;
-		},
-		get signal() {
-			return controller.signal;
-		},
-		pause() {
-			if (paused || cancelled) return;
-			paused = true;
-			const gate = Promise.withResolvers();
-			closed = gate.promise;
-			open = gate.resolve;
-			controller.abort();
-		},
-		resume() {
-			if (!paused || cancelled) return;
-			paused = false;
-			controller = new AbortController();
-			open?.();
-			open = void 0;
-			closed = void 0;
-		},
-		cancel() {
-			if (cancelled) return;
-			cancelled = true;
-			paused = false;
-			controller.abort();
-			open?.();
-			open = void 0;
-			closed = void 0;
-		},
-		async settle() {
-			if (closed) await closed;
-		}
-	};
-}
-//#endregion
-//#region _workflow-files.ts
-/**
-* Which of a submitted form's values are FILES.
+* 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.
 *
-* Its own module because both submit hooks need the identical answer and then do
-* two different things with it — `useWorkflowSubmit` stores each file and passes
-* its id, `useWorkflowStream` cuts it into parts and passes the group they share.
-* A second copy of this predicate would be a form field that one hook treats as a
-* file and the other does not, which is invisible until the run reads the wrong
-* kind of string.
-*/
-/**
-* The files a submitted field carries, if that is what it carries.
+* @example
+* ```tsx
+* import { createWorkflowApi, mountPage, useWorkflowRun } from "@alexkroman1/aai-ui";
+* import { useState } from "react";
 *
-* An array counts only when it is files ALL the way through — a mixed array is
-* some other field's value that happens to contain one, and turning half of it
-* into ids would corrupt it silently.
-*/
-function filesOf(value) {
-	if (value instanceof File) return [value];
-	if (!Array.isArray(value)) return [];
-	const files = value.filter((one) => one instanceof File);
-	return files.length > 0 && files.length === value.length ? files : [];
-}
-/**
-* The input properties still carrying a `File` — i.e. the ones that CANNOT survive
-* being sent.
+* // Hoisted: a client built in render is a new object every render.
+* const api = createWorkflowApi();
 *
-* A run input is JSON, and `JSON.stringify(new File(…))` is `{}` — no `toJSON`, no
-* own enumerable properties. So a File left in a payload does not fail to send: it
-* arrives as an empty object, and the workflow rejects it against whatever its own
-* schema says the property should be. Measured in production as
-* `Invalid input for workflow "transcribe": recording: Invalid input` — a message
-* about a type, on a form where the user had picked a perfectly good file.
+* 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>
+*   );
+* }
 *
-* Exported beside {@link filesOf} because it is the same question asked at the
-* other end: that one decides which fields to UPLOAD, this one checks that none
-* were missed. Both hooks are the callers.
-*/
-function fileFields(input) {
-	if (!isRecord(input)) return [];
-	return Object.entries(input).filter(([, value]) => filesOf(value).length > 0).map(([key]) => key);
-}
-//#endregion
-//#region _upload-files.ts
-/**
-* Turning a form's `File`s into stored upload ids, pauses and all.
+* mountPage({ name: "Digest", component: App });
+* ```
 *
-* Split out of `use-workflow-form.ts` for the 500-line cap, and the seam is a
-* real one: that module is the two HOOKS and the state between them, where this
-* is the walk over a submitted input — which is the only part of it that knows
-* what a `File` is, holds a loop, and survives being re-entered.
+* @throws If the target element is not found in the DOM.
 *
-* `_`-internal. `useWorkflowSubmit` is the only caller; `useWorkflowStream` sends
-* one file rather than walking an input and shares only the gate underneath both
-* (`_upload-session.ts`).
+* @public
 */
-/** A fresh session for one submission of `workflow`. */
-function createUploadSession(workflow) {
-	return {
-		scope: workflow,
-		ids: /* @__PURE__ */ new Map(),
-		stored: /* @__PURE__ */ new Map(),
-		tried: /* @__PURE__ */ new Set(),
-		gate: createUploadGate()
-	};
+function mountPage(config) {
+	const container = resolveContainer(config.target);
+	setPageTitle(config.name);
+	return mountRoot(container, createElement(ThemeProvider, { value: config.theme }, createElement(config.component)));
 }
+//#endregion
+//#region src/use-download-url.ts
 /**
-* The id to store this file under: the one a previous page load was using, or a
-* fresh one.
+* `useDownloadUrl` — an upload id a run produced, as something `<audio>`,
+* `<img>` or `<a download>` will accept.
 *
-* **The AGENT decides, never the fingerprint.** Two files can agree on every
-* field `_upload-recall.ts` keys by, so the recalled id is a candidate that has to
-* be checked before a byte is sent to it — and the check is cheap and exact,
-* because `uploadInfo` is the same record a resume already reads.
+* `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:
 *
-* Three answers, and the third is why this is not just a storage lookup:
+* - **`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.
 *
-* - **Complete.** Every byte is in from a load that is gone, so there is nothing
-*   to send: the caller takes the id and starts the run. This is the refresh that
-*   costs one `GET` instead of a second 200 MB upload.
-* - **Unfinished, with windows.** `UploadInfo.ranges` is what makes an
-*   upload resumable at all, so the id is reused and the attempt claims it.
-* - **Anything else.** A 404 (swept, or never seen), a failure, or an unfinished
-*   upload reporting NO windows — which is a partial single `PUT`, and a second
-*   `PUT` to that id is a 409 rather than an append (`streamUploadFile`). Reusing
-*   it would turn a reload into a failure the person cannot clear, so the entry is
-*   dropped and the file gets a fresh id.
+* 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.
 */
-async function claimId(api, session, file) {
-	const remembered = recallUploadId(session.scope, file);
-	if (remembered === void 0) return {
-		id: randomUploadId(),
-		complete: false
-	};
-	const info = await api.uploadInfo(remembered).catch(() => void 0);
-	if (info?.complete === true) return {
-		id: remembered,
-		complete: true
-	};
-	if (info !== void 0 && (info.ranges?.length ?? 0) > 0) {
-		session.tried.add(file);
-		return {
-			id: remembered,
-			complete: false
-		};
-	}
-	forgetUploadId(session.scope, file);
-	return {
-		id: randomUploadId(),
-		complete: false
-	};
-}
+/** 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 };
 /**
-* Replace every `File` in a submitted form with the id of a stored upload,
-* reporting how far each one has got.
-*
-* 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. That is also what makes a single bar honest — one
-* file is in flight at a time, and `index`/`count` say which.
+* Read an upload's bytes and hand back a URL a DOM element can use.
 *
-* 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.
+* @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}.
 *
-* ## `uploadStream`, not `upload`, and the id is the reason
+* @example
+* ```tsx no-check
+* import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+* import type { spokenSummary } from "./agent.ts";
 *
-* The difference between the two calls is only who mints the id — and that is
-* exactly what decides whether an interrupted upload can be picked up again. An
-* `upload` mints its own at the END and hands it back, so a caller whose upload
-* died has nothing to name what was stored and no choice but to send the file
-* again. A `uploadStream` is told the id up front, so the windows already in the
-* store are addressable, which is what both a pause and a server restart need.
+* function Playback() {
+*   const { run } = useWorkflowSubmit<typeof spokenSummary>("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>
+*   );
+* }
+* ```
 *
-* Nothing else about the submission changes: the run is still started after the
-* last byte lands, so the incomplete record a streamed upload leaves along the
-* way is one nobody reads.
+* @public
 */
-async function uploadFiles(api, input, report, parallel, session) {
-	if (!isRecord(input)) return input;
-	const entries = Object.entries(input);
-	const count = entries.reduce((total, [, value]) => total + filesOf(value).length, 0);
-	let index = 0;
-	const store = async (file) => {
-		index += 1;
-		const done = session.stored.get(file);
-		if (done !== void 0) return done;
-		const position = {
-			name: file.name,
-			index,
-			count
-		};
-		const known = session.ids.get(file);
-		const claimed = known === void 0 ? await claimId(api, session, file) : {
-			id: known,
-			complete: false
-		};
-		const id = claimed.id;
-		if (known === void 0) {
-			session.ids.set(file, id);
-			rememberUploadId(session.scope, file, id);
+function useDownloadUrl(uploadId, opts = {}) {
+	const [state, setState] = useState(IDLE);
+	const getClient = useWorkflowApiRef(opts.api);
+	useEffect(() => {
+		if (uploadId === void 0) {
+			setState(IDLE);
+			return;
 		}
-		if (claimed.complete) {
-			report({
-				...position,
-				loaded: file.size,
-				total: file.size,
-				fraction: 1,
-				paused: false
+		let cancelled = false;
+		let objectUrl;
+		setState(PENDING);
+		getClient().download(uploadId).then((blob) => {
+			if (cancelled) return;
+			objectUrl = URL.createObjectURL(blob);
+			setState({
+				url: objectUrl,
+				pending: false
 			});
-			session.stored.set(file, id);
-			return id;
-		}
-		await sendThroughGate(session.gate, async (resume) => {
-			await api.uploadStream(id, file, {
-				name: file.name,
-				signal: session.gate.signal,
-				onProgress: (progress) => report({
-					...position,
-					...progress,
-					paused: session.gate.paused
-				}),
-				...omitUndefined({
-					parallel,
-					resume: resume || session.tried.has(file) ? true : void 0
-				})
+		}).catch((err) => {
+			if (!cancelled) setState({
+				error: errorMessage(err),
+				pending: false
 			});
 		});
-		session.stored.set(file, id);
-		return id;
-	};
-	const out = {};
-	for (const [name, value] of entries) {
-		if (value instanceof File) {
-			out[name] = await store(value);
-			continue;
-		}
-		const chosen = filesOf(value);
-		if (chosen.length === 0) {
-			out[name] = value;
-			continue;
-		}
-		const ids = [];
-		for (const file of chosen) ids.push(await store(file));
-		out[name] = ids;
-	}
-	return out;
+		return () => {
+			cancelled = true;
+			if (objectUrl !== void 0) URL.revokeObjectURL(objectUrl);
+		};
+	}, [uploadId, getClient]);
+	return state;
 }
 //#endregion
-//#region _upload-pause.ts
+//#region src/use-run-key.ts
 /**
-* The two buttons a page puts over a live upload, bound to whichever gate the
-* submission is currently holding.
+* The handle a page keeps on the runs it started, across a reload.
 *
-* `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.
+* `useWorkflowSubmit` is what makes a run survivable — the run id is that
+* hook's own state, so a refresh loses it while the run carries on — and the
+* `key` is what it looks the run up BY, because it is a lookup CAPABILITY:
+* there is no per-user filtering behind `find`, so the key IS the scoping
+* mechanism. Choosing one is easy to get wrong in three separate ways, and six
+* shipped templates had each written the same twenty lines to get it right.
+* This is those lines.
+*
+* **`useWorkflowSubmit` now mints one for itself** ({@link useDefaultRunKey}),
+* so a page resumes its own run across a reload with nothing written at the
+* call site — six of six page templates passed `useRunKey()` and
+* `recover: true`, which is a default in the wrong place. The hook stays
+* PUBLIC for the page that wants to choose: an app with accounts passes the
+* ACCOUNT's own id instead, and a run then follows the person to a new device,
+* which is a promise only a login can keep; a page whose run outlives the tab
+* passes `useRunKey({ storage: "local" })`.
+*
+* ## Three properties, and the rejected alternatives are why each one matters
+*
+* - **Opaque** — `crypto.randomUUID()`, never derived from what was submitted.
+*   A key derived from the input collides the moment two people submit the same
+*   thing, and they then recover each other's runs; it also carries what they
+*   typed into a lookup token the platform deliberately stopped logging.
+* - **Short.** A `randomUUID` is 36 characters, well inside the 256 that
+*   `POST /workflows/runs` allows a key.
+* - **Minted once per load and written back for the next one**, which is the
+*   whole mechanism: the load that presses the button records the key with the
+*   run, and the load after it finds the run by producing the same key.
+*
+* Storage rather than the page's own URL, for all of them. A `?key=` parameter
+* survives more (a new tab, a bookmark, a shared link) and that is the problem:
+* a URL is pasted into chats, copied into referrers and kept in history, and
+* what a leaked one buys is somebody else's work — reading it, and `cancel()` on
+* it. An app with accounts should pass the ACCOUNT's own id here instead, and
+* then a run follows the person to a new device, which is a promise only a login
+* can keep.
+*
+* ## The storage is the caller's decision, and it is not a detail
+*
+* `"session"` (the default) dies with the tab, which covers exactly the
+* interruption most pages have — a reload, a same-tab navigation, a crashed tab
+* — and is the same lifetime as this package's other two stores, the session
+* resume id (`session-resume-store.ts`) and the upload recall
+* (`_upload-recall.ts`), so both halves of a reload make the same promise.
+*
+* `"local"` is for a run that outlives all of that BY DESIGN — one that sleeps
+* between digests and may live a month, where closing the browser on Tuesday and
+* coming back on Friday to press Stop is the ordinary case rather than an edge
+* one, and a tab-scoped key would answer that with an empty form beside a run
+* still posting somewhere. It is as far as a key can go without a login, and no
+* further. `podcast-digest` is that template, and the reason this hook is still
+* called by name anywhere; the other five take the tab-scoped default the
+* submit hook mints for them.
+*
+* ## Anything ELSE a page stores back must be VALIDATED on read
+*
+* This key needs no validation, and it is worth saying why, because it is the
+* exception: any string is a legal key, so a value from storage can only fail to
+* match a run. A page that remembers something more — which MODE submitted, say
+* — is remembering a value it will turn into a name, and storage hands back a
+* string some earlier version of that page wrote: a renamed mode, a hand-edited
+* value, a slot another app on the origin happens to share. Unchecked, that
+* starts a run called `undefined` and answers a 400 nobody typed. Check it
+* against the page's own list on the way out (`recalledMode` in
+* `transcription-workflow/recover.ts` is the worked example) — the recall is the
+* page's, the validation is not optional.
+*
+* ## The slot is keyed by the page's own URL
+*
+* Every deployed agent is served from one origin at `/:slug/`, so a fixed name
+* would have two agents scaffolded from the same template recover each other's
+* runs. The key is the page's own directory — resolved through `"./"`, which
+* drops the query and the hash, since a reload carrying `?foo` or `#bar` has to
+* find the same key. Same call `session-resume-store.ts` makes, for the same
+* reason.
+*
+* One key per PAGE is right even for a page driving several workflows: `find` is
+* scoped by workflow as well as by key, so three hooks sharing one key recover
+* three separate runs. `transcription-workflow` is that page.
+*
+* Every access is guarded. Storage THROWS outright in some contexts (Safari
+* private mode, an iframe blocked by policy) and is ABSENT in others (any
+* server-side render), and a page that cannot remember its key must degrade to
+* the behaviour it would have had anyway — one run per load — rather than
+* failing to render.
 */
+/** Where a run key lives, namespaced like this package's two other stores. */
+const PREFIX$1 = "aai:run-key:";
+/** This page's own slot — see "The slot is keyed by the page's own URL". */
+function slotFor() {
+	return urlSlot(PREFIX$1, "./");
+}
 /**
-* Bind pause/resume to the live submission's gate.
-*
-* @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.
+* Read the key this page already has, or mint and remember one.
 *
-* @internal
+* Not exported: a page that wants a key wants it for the life of a component,
+* which is what the hook is. Calling this per render would mint a fresh key and
+* hand `recover` one nothing was ever started under.
 */
-function useUploadPause(getGate, setUpload) {
-	const setPaused = useCallback((paused) => {
-		setUpload((current) => current ? {
-			...current,
-			paused
-		} : current);
-	}, [setUpload]);
-	return {
-		pauseUpload: useCallback(() => {
-			getGate()?.pause();
-			setPaused(true);
-		}, [getGate, setPaused]),
-		resumeUpload: useCallback(() => {
-			getGate()?.resume();
-			setPaused(false);
-		}, [getGate, setPaused])
-	};
+function mintRunKey(storage) {
+	const slot = slotFor();
+	const stored = storageGet(storage, slot);
+	if (stored !== void 0) return stored;
+	const minted = crypto.randomUUID();
+	storageSet(storage, slot, minted);
+	return minted;
 }
-//#endregion
-//#region use-workflow-form.ts
 /**
-* The two hooks a FORM needs, as against the one a status view does.
+* The key `useWorkflowSubmit` uses when the page named none.
 *
-* `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`.
+* Two things it does that a plain `useRunKey()` at the call site cannot, and
+* both are about a page that DID name one:
 *
-* ## `useWorkflowSubmit` — a form's two halves in one hook
+* - **It mints nothing when the caller has a key.** Minting writes to storage,
+*   so an unconditional `useRunKey()` inside the hook would leave a slot behind
+*   on every page that passes an account id and never reads it back.
+* - **It stays reactive to the caller's key.** A key that arrives late — an
+*   account id resolved after a login — must reach the lookup, which re-asks on
+*   a changed key by design; freezing it into `useState` would pin the page to
+*   whatever it held on its first render.
 *
-* 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.
+* The minted half is still frozen for the component's life, which is what
+* `useRunKey` freezes it for: a fresh key per render would record every run
+* under a name the next load cannot produce.
 *
-* 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.
+* @param explicit - The caller's own key, or undefined for a page with none.
+* @returns The key to record runs under and look them up by.
 *
-* ## Why it starts ASYNCHRONOUSLY even though a synchronous call exists
+* @internal
+*/
+function useDefaultRunKey(explicit) {
+	const [minted] = useState(() => explicit === void 0 ? mintRunKey("session") : "");
+	return explicit ?? minted;
+}
+/**
+* A lookup key for `useWorkflowSubmit({ key })`, stable across reloads.
 *
-* `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.
+* @param options - See the module doc for the whole argument. The storage kind
+*   is read once, when the key is minted: a value that changed afterwards would
+*   be asking to move a key that has already been recorded with a run.
+* @returns The key to record runs under and to look them up by — the same one
+*   for the life of the component, and for the next load in the same tab (or the
+*   same browser, under `"local"`).
 */
+function useRunKey(options = {}) {
+	const { storage = "session" } = options;
+	const [key] = useState(() => mintRunKey(storage));
+	return key;
+}
+//#endregion
+//#region src/_recover-run.ts
 /**
-* Read the agent's declared workflows.
+* Finding a run again when the page has lost its id.
 *
-* 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.
+* A run is durable and a page is not — which `useWorkflowRun`'s doc says, and
+* which was only half true of the hooks above it: the run id lived in plain
+* `useState`, so a refresh (or a same-tab navigation, or a crashed tab) left a
+* live run with nothing anywhere able to name it. The run really did continue;
+* the person really could not get back to 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.
+* `StartOptions.key` is the handle that survives that, and it always was — a
+* caller's own name for a run, indexed by the agent, read back with
+* `find(workflow, key)`. What was missing is the two lines that ASK. This is
+* them, plus the four decisions they turn out to carry.
 *
-* @example
-* ```tsx
-* import { useWorkflows } from "@alexkroman1/aai-ui";
+* ## It is a MOUNT-time act, not "whenever there is no run"
 *
-* // 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>
-*   );
-* }
-* ```
+* The tempting spelling is "if we hold no run id, look one up", and it breaks
+* `reset()`: a form put back to its initial state holds no run id, so the next
+* pass would re-adopt the very run the person had just dismissed — a Clear
+* button that clears nothing. So the lookup runs once per mount (and again only
+* if the KEY changes, which is a different person's run), and every later
+* absence of a run id is taken at face value.
 *
-* @param opts - See {@link UseWorkflowsOptions}.
-* @returns The listing, its loading flag and its failure — see
-* {@link UseWorkflowsResult}.
+* ## The lookup NEVER wins a race against a submit
 *
-* @public
+* A person who reloads and immediately submits has started the run they want,
+* and an answer that was already in flight names an older one. The caller
+* therefore adopts through `current ?? found`: the recovered id fills an empty
+* slot and never replaces a full one.
+*
+* ## A failed lookup is REPORTED
+*
+* The alternative is a page that quietly shows an empty form to somebody whose
+* run is live, who then starts a second one — the duplicated work the key
+* exists to prevent, and on a workflow app that is real money. A person who has
+* never run anything pays a banner they can ignore. Same trade as
+* `useWorkflows`, for the same reason: an empty answer here is a confident
+* false statement.
+*
+* ## It is ON by default, and it used to be opt-in
+*
+* The argument for opt-in was that a `key` on its own means only "record this
+* with the run" — which is what a voice agent's `ctx.workflows.start({ key })`
+* means, there being no page to put a run back on. A FORM is the other case: it
+* is the page, and losing the run is the thing it cannot recover from. Six of
+* six page templates wrote `useRunKey()` and `recover: true` together, which is
+* the same shape `session-resume-store.ts` names on the voice side — a default
+* in the wrong place — so `useWorkflowSubmit` now mints the key and asks.
+*
+* `enabled` remains, because `recover: false` remains: a page whose form must
+* always open empty says so, and then nothing here runs.
 */
-function useWorkflows(opts = {}) {
-	const { api, skip = false } = opts;
-	const [state, setState] = useState({
-		workflows: [],
-		loading: !skip,
-		error: void 0
-	});
-	const getClient = useWorkflowApiRef(api);
+/**
+* Look up the newest run for a key, once, as the component mounts.
+*
+* @param opts - See {@link RecoverRunOptions}.
+* @returns Whether the lookup is still out. A caller folds it into its own
+*   `pending`, because a form offering Submit while a live run is arriving is a
+*   form inviting a second one.
+*
+* @internal
+*/
+function useRecoveredRun(opts) {
+	const { workflow, key, enabled, getClient } = opts;
+	const [recovering, setRecovering] = useState(enabled);
+	const handlers = useRef(opts);
+	handlers.current = opts;
 	useEffect(() => {
-		if (skip) return;
+		if (!enabled) return;
 		let cancelled = false;
-		getClient().list().then((workflows) => {
-			if (!cancelled) setState({
-				workflows,
-				loading: false,
-				error: void 0
-			});
+		setRecovering(true);
+		getClient().find(workflow, key, { limit: 1 }).then((found) => {
+			if (cancelled) return;
+			const newest = found[0];
+			if (newest !== void 0) handlers.current.onFound(newest.runId);
+			setRecovering(false);
 		}).catch((err) => {
 			if (cancelled) return;
-			setState({
-				workflows: [],
-				loading: false,
-				error: errorMessage(err)
-			});
+			handlers.current.onError(errorMessage(err));
+			setRecovering(false);
 		});
 		return () => {
 			cancelled = true;
 		};
-	}, [skip, getClient]);
-	return state;
+	}, [
+		enabled,
+		key,
+		workflow,
+		getClient
+	]);
+	return recovering;
 }
+//#endregion
+//#region src/_run-controls.ts
 /**
-* Start a workflow from a form, and follow the run it creates.
+* The two things a page does TO a run it started, bound to the run it has.
 *
-* @typeParam D - The workflow DEFINITION, which types both halves of the
-*   submission: `submit(input)` takes what the workflow's schema parses to, and
-*   `run.status === "completed"` narrows to a typed `run.output`.
+* `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.
 *
-*   It used to be the OUTPUT type alone, and the asymmetry was the bug: a page
-*   already wrote `WorkflowOutputOf<typeof digest>` to get the output, while
-*   `submit` took `unknown`, so `submit({ ur1: 42 })` compiled and arrived as a
-*   400 in the browser. Naming the def instead types the input from the same
-*   declaration — and `import type` is ERASED, so it costs the bundle nothing.
-*   Passing an output type where a def belongs is now a compile error rather
-*   than a silent loss of typing, which is the point.
+* 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.
 *
-* @example
-* ```tsx no-check
-* import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
-* import type { digest } from "./agent.ts";
+* @param runId - The live run, or `undefined` before one exists.
+* @param getClient - The stable getter from `useWorkflowApiRef`.
+* @returns Two callbacks, stable while `runId` is.
 *
-* function DigestForm() {
-*   const { submit, run, pending, error } = useWorkflowSubmit<typeof digest>("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>{run.output.title}</p>}
-*     </Form>
-*   );
-* }
-* ```
+* @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 src/_upload-pause.ts
+/**
+* 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 useWorkflowSubmit(workflow, opts = {}) {
-	const { api, key, recover = false, wait, intervalMs, parallel } = opts;
+/**
+* Bind pause/resume to the live submission's gate.
+*
+* @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
+*/
+function useUploadPause(getGate, setUpload) {
+	const setPaused = useCallback((paused) => {
+		setUpload((current) => current ? {
+			...current,
+			paused
+		} : current);
+	}, [setUpload]);
+	return {
+		pauseUpload: useCallback(() => {
+			getGate()?.pause();
+			setPaused(true);
+		}, [getGate, setPaused]),
+		resumeUpload: useCallback(() => {
+			getGate()?.resume();
+			setPaused(false);
+		}, [getGate, setPaused])
+	};
+}
+//#endregion
+//#region src/_submission-state.ts
+/** The shared submission scaffold. See the module doc. */
+function useSubmissionState() {
 	const [runId, setRunId] = useState(void 0);
 	const [starting, setStarting] = useState(false);
 	const [startError, setStartError] = useState(void 0);
 	const [upload, setUpload] = useState(void 0);
-	const session = useRef(void 0);
-	const getClient = useWorkflowApiRef(api);
-	const tracked = useWorkflowRun(runId, omitUndefined({
-		api,
-		intervalMs
-	}));
-	const { wake, cancel } = useRunControls(runId, getClient);
-	const recovering = useRecoveredRun({
-		workflow,
-		key,
-		enabled: recover,
-		getClient,
-		onFound: (found) => {
-			setRunId((current) => current ?? found);
-		},
-		onError: setStartError
-	});
-	const submit = useCallback(async (input) => {
-		const client = getClient();
+	const current = useRef(void 0);
+	const begin = useCallback((token) => {
 		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
-	]);
+		current.current?.gate.cancel();
+		current.current = token;
+	}, []);
+	const end = useCallback((token) => {
+		if (current.current !== token) return;
+		current.current = void 0;
+		setStarting(false);
+		setUpload(void 0);
+	}, []);
 	const reset = useCallback(() => {
-		session.current?.gate.cancel();
-		session.current = void 0;
+		current.current?.gate.cancel();
+		current.current = void 0;
 		setRunId(void 0);
 		setStartError(void 0);
 		setUpload(void 0);
 	}, []);
-	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => session.current?.gate, []), setUpload);
+	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => current.current?.gate, []), setUpload);
 	return {
-		submit,
-		submitForm: submit,
-		reset,
-		wake,
-		cancel,
-		pauseUpload,
-		resumeUpload,
-		run: tracked.run,
-		pending: recovering || starting || tracked.polling,
+		runId,
+		starting,
+		startError,
 		upload,
-		error: startError ?? tracked.error
+		actions: useMemo(() => ({
+			setRunId,
+			setStartError,
+			setUpload,
+			begin,
+			end,
+			reset,
+			pauseUpload,
+			resumeUpload
+		}), [
+			begin,
+			end,
+			reset,
+			pauseUpload,
+			resumeUpload
+		])
 	};
 }
 //#endregion
-//#region components/workflow-fields.tsx
-/** @jsxImportSource react */
+//#region src/_upload-recall.ts
 /**
-* A form built from a workflow's declared input schema.
+* Where an upload's ID survives a page RELOAD.
 *
-* `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.
+* A streamed upload is resumable because its id outlives the attempt that began
+* it — `_upload-files.ts` says so, and `_upload-session.ts` turns that into a
+* pause a person can press. Both of them hold the id in MEMORY: the walk's
+* `UploadSession` lives in a `useRef`, so a reload was the one interruption the
+* mechanism could not survive. Everything else was already in place — the windows
+* were still in the store, the agent could still name them
+* (`UploadInfo.ranges`), and the id was minted in the browser — and the browser
+* had thrown away the only name for them. So a person who refreshed at 90% of a
+* 200 MB recording sent the whole file again, which is the one interruption they
+* are most likely to cause on purpose.
 *
-* ## It covers SCALARS, and says so rather than guessing
+* This is that name, written down. It is what tus-js-client's `urlStorage` and
+* Uppy's Golden Retriever sell, in the shape `session-resume-store.ts` already
+* uses for a session id.
 *
-* 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.
+* ## A FINGERPRINT, because a `File` has no name a page can address
 *
-* 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.
+* A file from a picker carries no path and no handle, so the key is what
+* tus-js-client fingerprints on: size, last-modified, type and name. Two
+* different files agreeing on all four is the case this cannot tell apart — and
+* the reason NOTHING here decides to resume. `_upload-files.ts` asks the agent
+* what the id actually holds before sending a byte to it, so a wrong hit costs
+* one `GET` and a fresh id rather than a corrupted upload.
 *
-* 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.
+* ## `sessionStorage`, deliberately
 *
-* @example
-* ```tsx no-check
-* import { Form, SubmitButton, WorkflowFields, useWorkflowSubmit }
-*   from "@alexkroman1/aai-ui";
-* import type { transcribe } from "./agent.ts";
+* The same call `session-resume-store.ts` makes, for a reason that happens to be
+* stronger here: a reload and a same-tab navigation are exactly what this is for,
+* and an id from yesterday names an upload the agent's sweep has very likely
+* already collected. A tab is also the boundary the walk itself has — two tabs
+* uploading the same recording are two submissions.
 *
-* function StartRun() {
-*   const { submitForm, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
-*   return (
-*     <Form onSubmit={submitForm} error={error}>
-*       <WorkflowFields workflow="transcribe" />
-*       <SubmitButton pending={pending}>Transcribe</SubmitButton>
-*     </Form>
-*   );
-* }
-* ```
+* Every access is guarded. Storage throws outright in Safari private mode and
+* under a blocking policy, and an upload that cannot be REMEMBERED must degrade
+* to the upload we would have done anyway rather than failing to start.
+*/
+const PREFIX = "aai:upload:";
+/**
+* How many ids one form keeps.
 *
-* @param props - Field-set props.
+* A cap rather than an expiry, because `sessionStorage` already expires with the
+* tab and an entry is ~80 bytes. What it bounds is the long-lived tab that
+* submits a hundred files: the oldest go first, and the id most likely to be
+* worth resuming is the one written last.
+*/
+const MAX_REMEMBERED = 32;
+/** One form's slot in storage. */
+function keyFor(scope) {
+	return `${PREFIX}${scope}`;
+}
+/**
+* What names this file across a reload.
 *
-* @public
+* The four fields a browser gives a picked file that do not change between loads.
+* `name` last because it is the one a person can read in a debugger.
 */
-function WorkflowFields({ workflow }) {
-	const { workflows, loading } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
-	const summary = typeof workflow === "string" ? workflows.find((entry) => entry.name === workflow) : workflow;
-	useDeclareFieldsPending(loading);
-	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)) });
+function fingerprint(file) {
+	return `${file.size}:${file.lastModified}:${file.type}:${file.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
-	});
-	const type = typeOf(property);
-	switch (type) {
-		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: type === "integer" ? 1 : "any",
-			...hint,
-			...defaults
-		});
-		case "string": return /* @__PURE__ */ jsx(TextField, {
-			name,
-			label,
-			required,
-			...hint,
-			...defaults
-		});
-		default: return null;
+/** This scope's remembered ids, or nothing at all — a parse failure is nothing. */
+function read(scope) {
+	const raw = storageGet("session", keyFor(scope));
+	if (raw === void 0) return {};
+	try {
+		const parsed = JSON.parse(raw);
+		return isRecord(parsed) ? parsed : {};
+	} catch {
+		return {};
 	}
 }
-/** 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;
+function write(scope, entries) {
+	storageSet("session", keyFor(scope), JSON.stringify(entries));
 }
 /**
-* A property name as a label — `recordingId` → `Recording id`.
+* The id this file was last being stored under in this tab, if any.
 *
-* A default, not a policy: a schema whose labels matter should carry a
-* `.describe()`, and an author who wants exact control writes the field.
+* A hit is a CANDIDATE and never a decision — see the module doc.
+*
+* @internal
 */
-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);
+function recallUploadId(scope, file) {
+	const found = read(scope)[fingerprint(file)];
+	return typeof found === "string" ? found : void 0;
 }
-//#endregion
-//#region components/workflow-progress.tsx
-/** @jsxImportSource react */
 /**
-* What a run has said so far, rendered.
+* Remember the id this file is being stored under.
 *
-* 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.
+* Called before the first byte leaves rather than after the last one lands: the
+* reload this exists for happens in between, and an id written at the end is an
+* id written for the one case that did not need it.
 *
-* 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:
+* @internal
+*/
+function rememberUploadId(scope, file, id) {
+	const entries = read(scope);
+	const key = fingerprint(file);
+	delete entries[key];
+	entries[key] = id;
+	const keys = Object.keys(entries);
+	for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_REMEMBERED))) delete entries[stale];
+	write(scope, entries);
+}
+/**
+* Forget it: the agent holds nothing resumable under this id.
 *
-* - **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.
+* The other half of the agent deciding. Without it a swept upload is re-read on
+* every submission of the same file for the life of the tab, which is a round
+* trip spent learning the same 404.
 *
-* @example
-* ```tsx
-* import { WorkflowProgress } from "@alexkroman1/aai-ui";
+* @internal
+*/
+function forgetUploadId(scope, file) {
+	const entries = read(scope);
+	const key = fingerprint(file);
+	if (!(key in entries)) return;
+	delete entries[key];
+	write(scope, entries);
+}
+//#endregion
+//#region src/_upload-session.ts
+/** Whether this rejection is an abort, in either of the two shapes runtimes throw. */
+function isAbortError(err) {
+	return err instanceof Error && err.name === "AbortError";
+}
+/** A fresh upload id: a capability, so it is random rather than derived. */
+function randomUploadId() {
+	return crypto.randomUUID().replaceAll("-", "");
+}
+/**
+* Send one file, waiting out however many pauses the person takes.
 *
-* function RunPanel({ runId }: { runId: string }) {
-*   return <WorkflowProgress runId={runId} />;
-* }
-* ```
+* The loop from the module doc, written once: both hooks need exactly this and a
+* second copy of it is a second place for the abort/pause distinction to be got
+* wrong. `send` is handed whether this attempt must CLAIM the id as its own —
+* false the first time, since a fresh id has nothing to resume and saying
+* otherwise waives the refusal that makes a caller-chosen id safe.
 *
-* @param props - Progress-log props.
+* Throws whatever `send` threw, except an abort the gate caused. A cancelled gate
+* throws too: the caller distinguishes it by reading `gate.cancelled`, which is
+* how an abandoned submission unwinds without being reported as a failure.
+*/
+async function sendThroughGate(gate, send) {
+	let tried = false;
+	for (;;) {
+		await gate.settle();
+		if (gate.cancelled) throw new Error("Upload cancelled.");
+		const resume = tried;
+		tried = true;
+		try {
+			await send(resume);
+			return;
+		} catch (err) {
+			if (gate.cancelled || !isAbortError(err)) throw err;
+		}
+	}
+}
+/**
+* A gate, open.
 *
-* @public
+* One per upload rather than one per hook: the id and the windows already stored
+* belong to a file, so a gate that outlived its file would resume something else.
 */
-function WorkflowProgress({ runId, api, className, placeholder, lines }) {
-	const { progress, streaming, supported } = useWorkflowProgress(runId, omitUndefined({ api }));
-	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: [shown.join("\n"), streaming && "\n…"]
-	});
+function createUploadGate() {
+	let controller = new AbortController();
+	let paused = false;
+	let cancelled = false;
+	let open;
+	let closed;
+	return {
+		get paused() {
+			return paused;
+		},
+		get cancelled() {
+			return cancelled;
+		},
+		get signal() {
+			return controller.signal;
+		},
+		pause() {
+			if (paused || cancelled) return;
+			paused = true;
+			const gate = Promise.withResolvers();
+			closed = gate.promise;
+			open = gate.resolve;
+			controller.abort();
+		},
+		resume() {
+			if (!paused || cancelled) return;
+			paused = false;
+			controller = new AbortController();
+			open?.();
+			open = void 0;
+			closed = void 0;
+		},
+		cancel() {
+			if (cancelled) return;
+			cancelled = true;
+			paused = false;
+			controller.abort();
+			open?.();
+			open = void 0;
+			closed = void 0;
+		},
+		async settle() {
+			if (closed) await closed;
+		}
+	};
 }
 //#endregion
-//#region page.tsx
-/** @jsxImportSource react */
+//#region src/_workflow-files.ts
 /**
-* `page()` — mount a WORKFLOW APP's UI: React, theme, no session.
+* Which of a submitted form's values are FILES.
 *
-* 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.
+* Its own module because both submit hooks need the identical answer and then do
+* two different things with it — `useWorkflowSubmit` stores each file and passes
+* its id, `useWorkflowStream` mints the id first so the run can start on it.
+* A second copy of this predicate would be a form field that one hook treats as a
+* file and the other does not, which is invisible until the run reads the wrong
+* kind of string.
+*/
+/**
+* The files a submitted field carries, if that is what it carries.
 *
-* 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()`.
+* An array counts only when it is files ALL the way through — a mixed array is
+* some other field's value that happens to contain one, and turning half of it
+* into ids would corrupt it silently.
 */
+function filesOf(value) {
+	if (value instanceof File) return [value];
+	if (!Array.isArray(value)) return [];
+	const files = value.filter((one) => one instanceof File);
+	return files.length > 0 && files.length === value.length ? files : [];
+}
 /**
-* Mount a page for an agent whose work happens in workflows.
+* The input properties still carrying a `File` — i.e. the ones that CANNOT survive
+* being sent.
 *
-* 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.
+* A run input is JSON, and `JSON.stringify(new File(…))` is `{}` — no `toJSON`, no
+* own enumerable properties. So a File left in a payload does not fail to send: it
+* arrives as an empty object, and the workflow rejects it against whatever its own
+* schema says the property should be. Measured in production as
+* `Invalid input for workflow "transcribe": recording: Invalid input` — a message
+* about a type, on a form where the user had picked a perfectly good file.
 *
-* @example
-* ```tsx
-* import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
-* import { useState } from "react";
+* Exported beside {@link filesOf} because it is the same question asked at the
+* other end: that one decides which fields to UPLOAD, this one checks that none
+* were missed. Both hooks are the callers.
+*/
+function fileFields(input) {
+	if (!isRecord(input)) return [];
+	return Object.entries(input).filter(([, value]) => filesOf(value).length > 0).map(([key]) => key);
+}
+//#endregion
+//#region src/_upload-files.ts
+/**
+* Turning a form's `File`s into stored upload ids, pauses and all.
 *
-* // Hoisted: a client built in render is a new object every render.
-* const api = createWorkflowApi();
+* Split out of `use-workflow-form.ts` for the 500-line cap, and the seam is a
+* real one: that module is the two HOOKS and the state between them, where this
+* is the walk over a submitted input — which is the only part of it that knows
+* what a `File` is, holds a loop, and survives being re-entered.
 *
-* 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>
-*   );
-* }
+* `_`-internal. `useWorkflowSubmit` is the only caller; `useWorkflowStream` sends
+* one file rather than walking an input and shares only the gate underneath both
+* (`_upload-session.ts`).
+*/
+/** A fresh session for one submission of `workflow`. */
+function createUploadSession(workflow) {
+	return {
+		scope: workflow,
+		ids: /* @__PURE__ */ new Map(),
+		stored: /* @__PURE__ */ new Map(),
+		tried: /* @__PURE__ */ new Set(),
+		gate: createUploadGate()
+	};
+}
+/**
+* The id to store this file under: the one a previous page load was using, or a
+* fresh one.
 *
-* page({ name: "Digest", component: App });
-* ```
+* **The AGENT decides, never the fingerprint.** Two files can agree on every
+* field `_upload-recall.ts` keys by, so the recalled id is a candidate that has to
+* be checked before a byte is sent to it — and the check is cheap and exact,
+* because `uploadInfo` is the same record a resume already reads.
 *
-* @throws If the target element is not found in the DOM.
+* Three answers, and the third is why this is not just a storage lookup:
 *
-* @public
+* - **Complete.** Every byte is in from a load that is gone, so there is nothing
+*   to send: the caller takes the id and starts the run. This is the refresh that
+*   costs one `GET` instead of a second 200 MB upload.
+* - **Unfinished, with windows.** `UploadInfo.ranges` is what makes an
+*   upload resumable at all, so the id is reused and the attempt claims it.
+* - **Anything else.** A 404 (swept, or never seen), a failure, or an unfinished
+*   upload reporting NO windows — which is a partial single `PUT`, and a second
+*   `PUT` to that id is a 409 rather than an append (`streamUploadFile`). Reusing
+*   it would turn a reload into a failure the person cannot clear, so the entry is
+*   dropped and the file gets a fresh id.
 */
-function page(config) {
-	const container = resolveContainer(config.target);
-	setPageTitle(config.name);
-	return mountRoot(container, createElement(ThemeProvider, { value: config.theme }, createElement(config.component)));
+async function claimId(api, session, file) {
+	const remembered = recallUploadId(session.scope, file);
+	if (remembered === void 0) return {
+		id: randomUploadId(),
+		complete: false
+	};
+	const info = await api.uploadInfo(remembered).catch(() => void 0);
+	if (info?.complete === true) return {
+		id: remembered,
+		complete: true
+	};
+	if (info !== void 0 && (info.ranges?.length ?? 0) > 0) {
+		session.tried.add(file);
+		return {
+			id: remembered,
+			complete: false
+		};
+	}
+	forgetUploadId(session.scope, file);
+	return {
+		id: randomUploadId(),
+		complete: false
+	};
 }
-//#endregion
-//#region use-download-url.ts
 /**
-* `useDownloadUrl` — an upload id a run produced, as something `<audio>`,
-* `<img>` or `<a download>` will accept.
+* Replace every `File` in a submitted form with the id of a stored upload,
+* reporting how far each one has got.
 *
-* `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:
+* 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. That is also what makes a single bar honest — one
+* file is in flight at a time, and `index`/`count` say which.
 *
-* - **`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.
+* 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.
 *
-* 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.
+* ## `uploadStream`, not `upload`, and the id is the reason
+*
+* The difference between the two calls is only who mints the id — and that is
+* exactly what decides whether an interrupted upload can be picked up again. An
+* `upload` mints its own at the END and hands it back, so a caller whose upload
+* died has nothing to name what was stored and no choice but to send the file
+* again. A `uploadStream` is told the id up front, so the windows already in the
+* store are addressable, which is what both a pause and a server restart need.
+*
+* Nothing else about the submission changes: the run is still started after the
+* last byte lands, so the incomplete record a streamed upload leaves along the
+* way is one nobody reads.
 */
-/** 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 };
+async function uploadFiles(api, input, report, parallel, session) {
+	if (!isRecord(input)) return input;
+	const entries = Object.entries(input);
+	const count = entries.reduce((total, [, value]) => total + filesOf(value).length, 0);
+	let index = 0;
+	const store = async (file) => {
+		index += 1;
+		const done = session.stored.get(file);
+		if (done !== void 0) return done;
+		const position = {
+			name: file.name,
+			index,
+			count
+		};
+		const known = session.ids.get(file);
+		const claimed = known === void 0 ? await claimId(api, session, file) : {
+			id: known,
+			complete: false
+		};
+		const id = claimed.id;
+		if (known === void 0) {
+			session.ids.set(file, id);
+			rememberUploadId(session.scope, file, id);
+		}
+		if (claimed.complete) {
+			report({
+				...position,
+				loaded: file.size,
+				total: file.size,
+				fraction: 1,
+				paused: false
+			});
+			session.stored.set(file, id);
+			return id;
+		}
+		await sendThroughGate(session.gate, async (resume) => {
+			await api.uploadStream(id, file, {
+				name: file.name,
+				signal: session.gate.signal,
+				onProgress: (progress) => report({
+					...position,
+					...progress,
+					paused: session.gate.paused
+				}),
+				...omitUndefined({
+					parallel,
+					resume: resume || session.tried.has(file) ? true : void 0
+				})
+			});
+		});
+		session.stored.set(file, id);
+		return id;
+	};
+	const out = {};
+	for (const [name, value] of entries) {
+		if (value instanceof File) {
+			out[name] = await store(value);
+			continue;
+		}
+		const chosen = filesOf(value);
+		if (chosen.length === 0) {
+			out[name] = value;
+			continue;
+		}
+		const ids = [];
+		for (const file of chosen) ids.push(await store(file));
+		out[name] = ids;
+	}
+	return out;
+}
+//#endregion
+//#region src/_upload-report.ts
 /**
-* 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 no-check
-* import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
-* import type { spokenSummary } from "./agent.ts";
+* What the bar draws, as a comparable string.
 *
-* function Playback() {
-*   const { run } = useWorkflowSubmit<typeof spokenSummary>("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>
-*   );
-* }
-* ```
+* The fraction is quantized to a tenth of a percent — finer than anything the
+* bar or the byte readout resolves. Everything else is compared exactly:
+* `paused` is a state change a person is waiting to see, and the name/index
+* pair moving means a different FILE, which must never be coalesced away.
+*/
+function renderKey(status) {
+	const { name, index, count, loaded, total, fraction, paused } = status;
+	const shown = fraction === void 0 ? loaded : Math.round(fraction * 1e3);
+	return `${paused} ${index} ${count} ${total ?? -1} ${shown} ${name}`;
+}
+/**
+* Wrap an `UploadStatus` setter so redundant reports never reach React.
 *
-* @public
+* Clearing the status (`undefined`) always passes and resets the comparison —
+* it ends one file's bar, and the next file must not be coalesced against the
+* previous one's last frame.
 */
-function useDownloadUrl(uploadId, opts = {}) {
-	const [state, setState] = useState(IDLE);
-	const getClient = useWorkflowApiRef(opts.api);
-	useEffect(() => {
-		if (uploadId === void 0) {
-			setState(IDLE);
+function coalesceUploadReports(set) {
+	let last;
+	return (status) => {
+		if (status === void 0) {
+			last = void 0;
+			set(void 0);
 			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;
+		const key = renderKey(status);
+		if (key === last) return;
+		last = key;
+		set(status);
+	};
 }
 //#endregion
-//#region use-run-key.ts
+//#region src/use-workflow-form.ts
 /**
-* The handle a page keeps on the runs it started, across a reload.
-*
-* `useWorkflowSubmit({ key, recover: true })` is what makes a run survivable —
-* the run id is that hook's own state, so a refresh loses it while the run
-* carries on — and the `key` is deliberately the caller's to choose, because it
-* is a lookup CAPABILITY: there is no per-user filtering behind `find`, so the
-* key IS the scoping mechanism. Choosing one is easy to get wrong in three
-* separate ways, and six shipped templates had each written the same twenty
-* lines to get it right. This is those lines.
-*
-* ## Three properties, and the rejected alternatives are why each one matters
-*
-* - **Opaque** — `crypto.randomUUID()`, never derived from what was submitted.
-*   A key derived from the input collides the moment two people submit the same
-*   thing, and they then recover each other's runs; it also carries what they
-*   typed into a lookup token the platform deliberately stopped logging.
-* - **Short.** A `randomUUID` is 36 characters, well inside the 256 that
-*   `POST /workflows/runs` allows a key.
-* - **Minted once per load and written back for the next one**, which is the
-*   whole mechanism: the load that presses the button records the key with the
-*   run, and the load after it finds the run by producing the same key.
-*
-* Storage rather than the page's own URL, for all of them. A `?key=` parameter
-* survives more (a new tab, a bookmark, a shared link) and that is the problem:
-* a URL is pasted into chats, copied into referrers and kept in history, and
-* what a leaked one buys is somebody else's work — reading it, and `cancel()` on
-* it. An app with accounts should pass the ACCOUNT's own id here instead, and
-* then a run follows the person to a new device, which is a promise only a login
-* can keep.
+* The hook a FORM needs, as against the one a status view does.
 *
-* ## The storage is the caller's decision, and it is not a detail
+* `useWorkflowRun` (`workflow-client.ts`) watches a run you already have.
+* This is what comes before it: `useWorkflowSubmit` starts a run and hands the
+* id straight to `useWorkflowRun`. Its sibling `useWorkflows` — the listing
+* `<WorkflowFields>` renders a form from — is `use-workflows.ts`.
 *
-* `"session"` (the default) dies with the tab, which covers exactly the
-* interruption most pages have — a reload, a same-tab navigation, a crashed tab
-* — and is the same lifetime as this package's other two stores, the session
-* resume id (`session-resume-store.ts`) and the upload recall
-* (`_upload-recall.ts`), so both halves of a reload make the same promise.
+* ## `useWorkflowSubmit` — a form's two halves in one hook
 *
-* `"local"` is for a run that outlives all of that BY DESIGN — one that sleeps
-* between digests and may live a month, where closing the browser on Tuesday and
-* coming back on Friday to press Stop is the ordinary case rather than an edge
-* one, and a tab-scoped key would answer that with an empty form beside a run
-* still posting somewhere. It is as far as a key can go without a login, and no
-* further. `podcast-digest` is that template; the other five ship the default.
+* 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.
 *
-* ## Anything ELSE a page stores back must be VALIDATED on read
+* 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.
 *
-* This key needs no validation, and it is worth saying why, because it is the
-* exception: any string is a legal key, so a value from storage can only fail to
-* match a run. A page that remembers something more — which MODE submitted, say
-* — is remembering a value it will turn into a name, and storage hands back a
-* string some earlier version of that page wrote: a renamed mode, a hand-edited
-* value, a slot another app on the origin happens to share. Unchecked, that
-* starts a run called `undefined` and answers a 400 nobody typed. Check it
-* against the page's own list on the way out (`recalledMode` in
-* `transcription-workflow/recover.ts` is the worked example) — the recall is the
-* page's, the validation is not optional.
+* ## Why it starts ASYNCHRONOUSLY even though a synchronous call exists
 *
-* ## The slot is keyed by the page's own URL
+* `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.
+*/
+/**
+* Start a workflow from a form, and follow the run it creates.
 *
-* Every deployed agent is served from one origin at `/:slug/`, so a fixed name
-* would have two agents scaffolded from the same template recover each other's
-* runs. The key is the page's own directory — resolved through `"./"`, which
-* drops the query and the hash, since a reload carrying `?foo` or `#bar` has to
-* find the same key. Same call `session-resume-store.ts` makes, for the same
-* reason.
+* @typeParam D - The workflow DEFINITION, which types both halves of the
+*   submission: `submit(input)` takes what the workflow's schema parses to, and
+*   `run.status === "completed"` narrows to a typed `run.output`.
 *
-* One key per PAGE is right even for a page driving several workflows: `find` is
-* scoped by workflow as well as by key, so three hooks sharing one key recover
-* three separate runs. `transcription-workflow` is that page.
+*   It used to be the OUTPUT type alone, and the asymmetry was the bug: a page
+*   already wrote `WorkflowOutputOf<typeof digest>` to get the output, while
+*   `submit` took `unknown`, so `submit({ ur1: 42 })` compiled and arrived as a
+*   400 in the browser. Naming the def instead types the input from the same
+*   declaration — and `import type` is ERASED, so it costs the bundle nothing.
+*   Passing an output type where a def belongs is now a compile error rather
+*   than a silent loss of typing, which is the point.
 *
-* Every access is guarded. Storage THROWS outright in some contexts (Safari
-* private mode, an iframe blocked by policy) and is ABSENT in others (any
-* server-side render), and a page that cannot remember its key must degrade to
-* the behaviour it would have had anyway — one run per load — rather than
-* failing to render.
-*/
-/** Where a run key lives, namespaced like this package's two other stores. */
-const PREFIX = "aai:run-key:";
-/** This page's own slot — see "The slot is keyed by the page's own URL". */
-function slotFor() {
-	const href = globalThis.location?.href;
-	if (href === void 0) return PREFIX;
-	try {
-		return `${PREFIX}${new URL("./", href).href}`;
-	} catch {
-		return `${PREFIX}${href}`;
-	}
-}
-/**
-* Read the key this page already has, or mint and remember one.
+* @example
+* ```tsx no-check
+* import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+* import type { digest } from "./agent.ts";
 *
-* Not exported: a page that wants a key wants it for the life of a component,
-* which is what the hook is. Calling this per render would mint a fresh key and
-* hand `recover` one nothing was ever started under.
-*/
-function mintRunKey(storage) {
-	try {
-		const store = storage === "local" ? globalThis.localStorage : globalThis.sessionStorage;
-		const slot = slotFor();
-		const stored = store?.getItem(slot);
-		if (stored !== null && stored !== void 0) return stored;
-		const minted = crypto.randomUUID();
-		store?.setItem(slot, minted);
-		return minted;
-	} catch {
-		return crypto.randomUUID();
-	}
-}
-/**
-* A lookup key for `useWorkflowSubmit({ key, recover: true })`, stable across
-* reloads.
+* function DigestForm() {
+*   const { submit, run, pending, error } = useWorkflowSubmit<typeof digest>("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>{run.output.title}</p>}
+*     </Form>
+*   );
+* }
+* ```
 *
-* @param options - See the module doc for the whole argument. The storage kind
-*   is read once, when the key is minted: a value that changed afterwards would
-*   be asking to move a key that has already been recorded with a run.
-* @returns The key to record runs under and to look them up by — the same one
-*   for the life of the component, and for the next load in the same tab (or the
-*   same browser, under `"local"`).
+* @public
 */
-function useRunKey(options = {}) {
-	const { storage = "session" } = options;
-	const [key] = useState(() => mintRunKey(storage));
-	return key;
+function useWorkflowSubmit(workflow, opts = {}) {
+	const { api, recover = true, wait, intervalMs, parallel } = opts;
+	const key = useDefaultRunKey(opts.key);
+	const state = useSubmissionState();
+	const { runId, actions } = state;
+	const getClient = useWorkflowApiRef(api);
+	const tracked = useWorkflowRun(runId, omitUndefined({
+		api,
+		intervalMs
+	}));
+	const { wake, cancel } = useRunControls(runId, getClient);
+	const [startedHere, setStartedHere] = useState(false);
+	const recovering = useRecoveredRun({
+		workflow,
+		key,
+		enabled: recover,
+		getClient,
+		onFound: (found) => {
+			actions.setRunId((current) => current ?? found);
+		},
+		onError: actions.setStartError
+	});
+	const submit = useCallback(async (input) => {
+		const client = getClient();
+		const current = createUploadSession(workflow);
+		setStartedHere(true);
+		actions.begin(current);
+		try {
+			const options = omitUndefined({ key });
+			const started = await uploadFiles(client, input, coalesceUploadReports(actions.setUpload), parallel, current);
+			actions.setRunId(wait === void 0 ? await client.start(workflow, started, options) : (await client.startAndWait(workflow, started, {
+				...options,
+				wait
+			})).runId);
+		} catch (err) {
+			if (!current.gate.cancelled) actions.setStartError(errorMessage(err));
+		} finally {
+			actions.end(current);
+		}
+	}, [
+		workflow,
+		key,
+		wait,
+		parallel,
+		getClient,
+		actions
+	]);
+	return {
+		submit,
+		submitForm: submit,
+		reset: useCallback(() => {
+			setStartedHere(false);
+			actions.reset();
+		}, [actions]),
+		wake,
+		cancel,
+		pauseUpload: actions.pauseUpload,
+		resumeUpload: actions.resumeUpload,
+		run: tracked.run,
+		startedHere,
+		pending: recovering || state.starting || tracked.polling,
+		upload: state.upload,
+		error: state.startError ?? tracked.error
+	};
 }
 //#endregion
-//#region use-workflow-runs.ts
+//#region src/use-workflow-runs.ts
 /**
 * The RUNS a workflow has had — the list a page shows beside its form.
 *
@@ -2144,7 +2442,7 @@ function useWorkflowRuns(workflow, opts = {}) {
 	};
 }
 //#endregion
-//#region use-workflow-stream.ts
+//#region src/use-workflow-stream.ts
 /**
 * Starting a run BEFORE its file has finished uploading.
 *
@@ -2172,7 +2470,7 @@ function useWorkflowRuns(workflow, opts = {}) {
 * earlier version of this hook took a `cut` callback and uploaded N parts into a
 * "group" that a separate call had to seal; it worked, and every piece of it was
 * something the caller had to get right. The whole of that is replaced by the store
-* publishing `size` as bytes land — which `readUpload` already clamped to — so the
+* publishing `size` as bytes land — which `stepReadUpload` already clamped to — so the
 * run does exactly what it does over a finished file and simply waits for windows to
 * become present.
 *
@@ -2250,25 +2548,21 @@ function useWorkflowRuns(workflow, opts = {}) {
 */
 function useWorkflowStream(workflow, opts = {}) {
 	const { api, key, intervalMs, parallel } = opts;
-	const [runId, setRunId] = useState(void 0);
-	const [starting, setStarting] = useState(false);
-	const [startError, setStartError] = useState(void 0);
-	const [upload, setUpload] = useState(void 0);
-	const gateRef = useRef(void 0);
+	const state = useSubmissionState();
+	const { runId, actions } = state;
 	const getClient = useWorkflowApiRef(api);
 	const tracked = useWorkflowRun(runId, omitUndefined({
 		api,
 		intervalMs
 	}));
 	const { wake, cancel } = useRunControls(runId, getClient);
+	const [startedHere, setStartedHere] = useState(false);
 	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;
+		const current = { gate: createUploadGate() };
+		const { gate } = current;
+		setStartedHere(true);
+		actions.begin(current);
 		let started;
 		try {
 			const id = randomUploadId();
@@ -2281,7 +2575,7 @@ function useWorkflowStream(workflow, opts = {}) {
 			});
 			started = begun.runId;
 			const chosen = begun.file;
-			setRunId(started);
+			actions.setRunId(started);
 			if (!chosen) return;
 			await streamFile({
 				client,
@@ -2289,45 +2583,38 @@ function useWorkflowStream(workflow, opts = {}) {
 				id,
 				file: chosen,
 				parallel,
-				report: setUpload
+				report: coalesceUploadReports(actions.setUpload)
 			});
 			await client.wake(started).catch(() => void 0);
 		} catch (err) {
-			if (!gate.cancelled) setStartError(errorMessage(err));
+			if (!gate.cancelled) actions.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);
-			}
+			actions.end(current);
 		}
 	}, [
 		workflow,
 		key,
 		parallel,
-		getClient
+		getClient,
+		actions
 	]);
-	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,
 		submitForm: submit,
-		reset,
+		reset: useCallback(() => {
+			setStartedHere(false);
+			actions.reset();
+		}, [actions]),
 		wake,
 		cancel,
-		pauseUpload,
-		resumeUpload,
+		pauseUpload: actions.pauseUpload,
+		resumeUpload: actions.resumeUpload,
 		run: tracked.run,
-		pending: starting || tracked.polling,
-		upload,
-		error: startError ?? tracked.error
+		startedHere,
+		pending: state.starting || tracked.polling,
+		upload: state.upload,
+		error: state.startError ?? tracked.error
 	};
 }
 /**
@@ -2423,7 +2710,7 @@ function fileAt(input, field) {
 	return filesOf(input[field])[0];
 }
 //#endregion
-//#region workflow-status-labels.ts
+//#region src/workflow-status-labels.ts
 /**
 * The default status line per {@link WorkflowRunStatus}.
 *
@@ -2449,4 +2736,4 @@ const WORKFLOW_STATUS_LABELS = {
 	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, useRunKey, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };
+export { AGENT_STATE_LABELS, AutoScroll, BulletList, Button, ChatView, CheckboxField, ConsoleShell, Controls, Facts, Field, FileField, Form, Markdown, MessageList, NumberField, SelectField, SessionErrorBanner, SidebarLayout, StartScreen, SubmitButton, TextAreaField, TextField, ToolCallRow, UploadProgressBar, WORKFLOW_STATUS_LABELS, WorkflowFields, WorkflowProgress, createBrowserSession, createWorkflowApi, fetchClientConfig, isTerminal, mountClient, mountPage, useAgentState, useConversation, useDownloadUrl, useEvent, useRunKey, useSession, useSessionActions, useSessionError, useSessionSelector, useSessionStatus, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };