@alexkroman1/aai-ui 0.16.0 → 0.18.0

package/dist/index.js

@@ -1,28 +1,58 @@
-import { a as AGENT_STATE_LABELS, i as SessionErrorBanner, n as ConsoleShell, r as SessionStateDot, t as ChatView } from "./chat-view-DIwPoAEG.js";
-import { n as pageBaseUrl, r as setPageTitle, t as isTypingTarget } from "./_utils-Mi-SCFA1.js";
-import { n as fetchClientConfig, t as buildAgentUrl } from "./client-config-C7fQrioM.js";
-import { a as ticketCarriage, c as resolveReported, d as storageSet, f as urlSlot, i as resolveSessionTokenSync, l as storageGet, r as resolveSessionToken, s as browserClientId, t as createBrowserSession, u as storageRemove } from "./session-CYdjRvbl.js";
-import { ThemeProvider, useOptionalSessionCore, useSession, useSessionActions, useSessionCore, useSessionError, useSessionSelector, useSessionStatus, useTheme } from "./context.js";
-import { a as useAgentState, i as selectAgentState, n as useToolCallStart, r as useToolResult, t as useEvent } from "./hooks-DN4gHYsj.js";
-import { a as useConversation, i as interleave, n as Markdown, o as AutoScroll, r as ConversationView, t as MessageList } from "./message-list-DHZcLhRA.js";
+import { a as AGENT_STATE_LABELS, i as SessionErrorBanner, n as ConsoleShell, r as SessionStateDot, t as ChatView } from "./chat-view-BwKpF0MN.js";
+import { n as pageBaseUrl, r as setPageTitle, t as isTypingTarget } from "./_utils-BlZBJPdj.js";
+import { n as fetchClientConfig, t as buildAgentUrl } from "./client-config-DcMCWmkO.js";
+import { a as ticketCarriage, c as resolveReported, d as storageSet, f as urlSlot, i as resolveSessionTokenSync, l as storageGet, r as resolveSessionToken, s as browserClientId, t as createBrowserSession, u as storageRemove } from "./session-Rud8mmU-.js";
+import { a as useSessionActions, c as useSessionSelector, i as useSession, l as useSessionStatus, n as ThemeProvider, o as useSessionCore, r as useOptionalSessionCore, s as useSessionError, u as useTheme } from "./context-BF0KsI9X.js";
+import { a as useAgentState, i as selectAgentState, n as useToolCallStart, r as useToolResult, t as useEvent } from "./hooks-1CoQY_Fc.js";
+import { a as useConversation, i as interleave, n as Markdown, o as AutoScroll, r as ConversationView, t as MessageList } from "./message-list-BBHLK05X.js";
 import { a as inkTint, i as focusRingStyle, n as FOCUS_RING } from "./_colors-CpZO-88A.js";
 import { Button } from "./components/button.js";
-import { a as useFlash, i as useCopy } from "./url-chips-oyy_Eiqh.js";
+import { a as useFlash, i as useCopy } from "./url-chips-C_SHU6fq.js";
 import { Controls } from "./components/controls.js";
-import { n as useUserTranscript } from "./use-user-transcript-uyHhzy4d.js";
-import { n as ToolCallRow } from "./tool-call-block-uXtMOUWN.js";
+import { n as useUserTranscript } from "./use-user-transcript-lOu_uMnf.js";
+import { n as ToolCallRow } from "./tool-call-block-C8s6AhjS.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { a as useWorkflowProgress, c as isTerminal, o as useWorkflowApiRef, r as useWorkflowRun, s as createWorkflowApi } from "./use-workflow-run-DdhWmbx-.js";
+import { a as useWorkflowProgress, c as createWorkflowApi, l as isTerminal, o as repeatUntil, r as useWorkflowRun, s as useWorkflowApiRef } from "./use-workflow-run-BTEemod0.js";
 import { mountClient, mountRoot, resolveContainer } from "./define-client.js";
 import { errorMessage, errorMessage as errorMessage$1 } from "@alexkroman1/aai";
 import { InboxServerFrameSchema } from "@alexkroman1/aai/protocol";
 import { CLIENT_ID_RE, createBackoffLoop, createEpoch } from "@alexkroman1/aai/internal";
 import { Fragment, createContext, createElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { formatBytes, isRecord, omitUndefined, safeJsonParse as safeJsonParse$1 } from "@alexkroman1/aai/utils";
 import clsx from "clsx";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-import { formatBytes, isRecord, omitUndefined, safeJsonParse as safeJsonParse$1 } from "@alexkroman1/aai/utils";
 import { assign, createActor, fromPromise, raise, setup, stateIn } from "xstate";
+import { DICTATION_MAX_SECONDS, DICTATION_SAMPLE_RATE } from "@alexkroman1/aai/experimental";
+//#region src/append-dictation.ts
+/**
+* `appendDictation(draft, text)` — where dictated words land in a text box
+* that may already hold some.
+*/
+/**
+* `draft` with `text` added after it, joined by exactly one space: a draft
+* ending in whitespace or a newline does not grow a double space, and an empty
+* or blank draft is replaced rather than given a leading one.
+*
+* Never REPLACES what was typed — the words someone said are an addition to
+* the box, which is what makes speaking into a half-written prompt safe.
+*
+* @example
+* ```ts
+* import { appendDictation } from "@alexkroman1/aai-ui";
+*
+* appendDictation("Build me an agent", "that books tables."); // "Build me an agent that books tables."
+* appendDictation("", "Hello"); // "Hello"
+* ```
+*
+* @public
+*/
+function appendDictation(draft, text) {
+	const words = text.trim();
+	if (!words) return draft;
+	return draft.trim() ? `${draft.trimEnd()} ${words}` : words;
+}
+//#endregion
 //#region src/client-tool.ts
 /**
 * The page's half of a `clientTool`: run the handler when the agent calls the
@@ -399,10 +429,27 @@ function useDeclareFieldsPending(pending) {
 async function collectValues(form) {
 	const values = {};
 	for (const element of Array.from(form.elements)) if (element instanceof HTMLInputElement) await readInput(element, values);
-	else if ((element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) && element.name !== "" && !element.disabled) values[element.name] = element instanceof HTMLSelectElement ? readSelect(element) : element.value;
+	else if ((element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) && element.name !== "" && !element.disabled) values[element.name] = element instanceof HTMLSelectElement ? readSelect(element) : readTextArea(element);
 	return values;
 }
 /**
+* One `<textarea>`: its string, or with `split="lines"` the non-blank lines
+* trimmed — "one point per line", for a schema's `string[]`. Blank lines go, so
+* a trailing newline is not a requirement to cover `""`.
+*/
+function readTextArea(textarea) {
+	if (splitMode(textarea.dataset.aaiSplit) !== "lines") return textarea.value;
+	return textarea.value.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+}
+/** The `data-aai-split` attribute as a {@link TextSplitMode}, defaulting to `"none"`. */
+function splitMode(raw) {
+	return raw === "lines" ? raw : "none";
+}
+/** The `data-aai-as` attribute as a {@link FileValueShape}, defaulting to `"file"`. */
+function valueShape(raw) {
+	return raw === "namedText" ? raw : "file";
+}
+/**
 * One `<select>`, by arity.
 *
 * `HTMLSelectElement.value` is the FIRST selected option and nothing more, so a
@@ -411,10 +458,22 @@ async function collectValues(form) {
 * for a list. `selectedOptions` is the whole of what the user picked; nothing
 * selected contributes `[]`, which is the honest answer for a control that is
 * present and empty rather than one that was left blank.
+*
+* `data-aai-value="number"` (set by `<WorkflowFields>` for a numeric choice
+* set) reads each chosen option back as a NUMBER: an `<option>` can only hold a
+* string, and `"1"` against `z.literal([1, 2])` is a refused submission. An
+* option that is not numeric stays a string, as a number input's does.
 */
 function readSelect(select) {
-	if (!select.multiple) return select.value;
-	return Array.from(select.selectedOptions, (option) => option.value);
+	const read = select.dataset.aaiValue === "number" ? asNumber : (value) => value;
+	if (!select.multiple) return read(select.value);
+	return Array.from(select.selectedOptions, (option) => read(option.value));
+}
+/** The option's value as a number where it is one — `""` and prose stay strings. */
+function asNumber(value) {
+	if (value.trim() === "") return value;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : value;
 }
 /** One `<input>`, by type. */
 async function readInput(input, values) {
@@ -436,7 +495,7 @@ async function readInput(input, values) {
 		case "file": {
 			const files = Array.from(input.files ?? []);
 			if (files.length === 0) return;
-			const chosen = await readFiles(files, readMode(input.dataset.aaiRead));
+			const chosen = await readFiles(files, readMode(input.dataset.aaiRead), valueShape(input.dataset.aaiAs));
 			values[input.name] = input.multiple ? chosen : chosen[0];
 			return;
 		}
@@ -451,8 +510,12 @@ async function readInput(input, values) {
 * the bytes is the upload request `useWorkflowSubmit` makes — which streams the
 * same `File` object straight to the agent.
 */
-function readFiles(files, read) {
+function readFiles(files, read, shape) {
 	if (read === "upload") return Promise.resolve([...files]);
+	if (shape === "namedText") return Promise.all(files.map(async (file) => ({
+		name: file.name,
+		text: await file.text()
+	})));
 	return Promise.all(files.map((file) => describeFile(file, read)));
 }
 /** The `data-aai-read` attribute as a {@link FileReadMode}, defaulting to `"none"`. */
@@ -657,11 +720,18 @@ function NumberField(props) {
 * Accepts every `<textarea>` attribute except `name` and `className`, plus the
 * shared {@link FieldShell} props. `rows` defaults to 4.
 *
-* @param props - {@link FieldShell} props plus `<textarea>` attributes.
+* **`split="lines"` contributes a `string[]`** — one entry per non-blank line,
+* trimmed — which is the control for a schema's `z.array(z.string())`: "one
+* point per line". `document-redline-workflow` reshaped the textarea's string
+* by hand on submit; the field does it now, so `<WorkflowFields>` can render
+* it for a `string[]` property and a hand-written one can match. See
+* {@link TextSplitMode}.
+*
+* @param props - {@link FieldShell} props, `split`, and `<textarea>` attributes.
 *
 * @public
 */
-function TextAreaField({ name, label, hint, className, rows = 4, ...rest }) {
+function TextAreaField({ name, label, hint, className, rows = 4, split = "none", ...rest }) {
 	const id = useId();
 	const control = useControlProps();
 	return /* @__PURE__ */ jsx(Field, {
@@ -673,6 +743,7 @@ function TextAreaField({ name, label, hint, className, rows = 4, ...rest }) {
 			id,
 			name,
 			rows,
+			"data-aai-split": split,
 			...control,
 			...rest
 		})
@@ -750,6 +821,10 @@ function CheckboxField({ name, label, hint, className, ...rest }) {
 		})
 	});
 }
+/** The read a non-upload field makes: `namedText` is a reading of the text, so it asks for it. */
+function readModeFor(read, as) {
+	return as === "namedText" && read === "none" ? "text" : read;
+}
 /**
 * A file picker. Contributes a {@link FileValue} (or an array, with `multiple`)
 * to {@link FormValues} — or nothing when no file was chosen.
@@ -769,18 +844,26 @@ function CheckboxField({ name, label, hint, className, ...rest }) {
 * {@link FileReadMode} for the four values; `upload` is shorthand for
 * `read="upload"`.
 *
+* **`as="namedText"` contributes `{ name, text }`** ({@link NamedTextValue})
+* instead of the metadata-bearing {@link FileValue}, and implies
+* `read="text"`: the shape a schema declares for a draft to redline or a
+* config to apply, and the one `<WorkflowFields>` renders for an object
+* property of exactly that shape. `document-redline-workflow` reshaped the
+* `FileValue` by hand on submit; the field does it now.
+*
 * Otherwise accepts every `<input>` attribute except `name`, `className` and
 * `type`, plus the shared {@link FieldShell} props — so `accept` and
 * `multiple` are passed straight through.
 *
-* @param props - {@link FieldShell} props, `read`/`upload`, and `<input>`
+* @param props - {@link FieldShell} props, `read`/`upload`/`as`, and `<input>`
 * attributes.
 *
 * @public
 */
-function FileField({ name, label, hint, className, read = "none", upload = false, ...rest }) {
+function FileField({ name, label, hint, className, read = "none", upload = false, as = "file", ...rest }) {
 	const id = useId();
 	const control = useFileControlProps();
+	const mode = upload ? "upload" : readModeFor(read, as);
 	return /* @__PURE__ */ jsx(Field, {
 		label,
 		hint,
@@ -790,13 +873,35 @@ function FileField({ name, label, hint, className, read = "none", upload = false
 			id,
 			name,
 			type: "file",
-			"data-aai-read": upload ? "upload" : read,
+			"data-aai-read": mode,
+			"data-aai-as": as,
 			...control,
 			...rest
 		})
 	});
 }
 //#endregion
+//#region src/components/form-types.ts
+/**
+* What a form's controls CONTRIBUTE — the types both halves of the form code
+* share, and {@link isFileValue}, the guard that reads one back.
+*
+* Their own module because `form.tsx` (the components) and `_form-values.ts`
+* (the DOM read) both need them, and a type living in one of those would make
+* the pair import each other.
+*/
+/**
+* Whether one {@link FormValues} entry is what a {@link FileField} contributed.
+*
+* A field with nothing chosen contributes no key at all, so the absent case is
+* the ordinary one — this is `false` for `undefined`, not an error.
+*
+* @public
+*/
+function isFileValue(value) {
+	return isRecord(value) && typeof value.name === "string" && typeof value.size === "number" && typeof value.type === "string" && typeof value.lastModified === "number" && (value.content === void 0 || typeof value.content === "string");
+}
+//#endregion
 //#region src/components/form.tsx
 /** @jsxImportSource react */
 /**
@@ -1019,7 +1124,7 @@ const DEFAULT_VARIANT = {
 };
 function defaultButton({ action, label, onClick }) {
 	return /* @__PURE__ */ jsx(Button, {
-		variant: DEFAULT_VARIANT[action],
+		variant: DEFAULT_VARIANT[action] ?? "secondary",
 		onClick,
 		children: label
 	});
@@ -1339,21 +1444,88 @@ function useWorkflows(options = {}) {
 * studio's SDK-subpath list: mirroring "would just move the drift somewhere
 * new".
 *
-* So a NEW control added to `<WorkflowFields>` is a new member of
-* {@link WorkflowFieldKind}, and every reader of the rule finds out from the
-* type rather than from a table somebody remembered to edit.
+* So a NEW control added to `<WorkflowFields>` is a new value of
+* {@link WorkflowFieldKind}. The set is open, so that addition is not a break:
+* a reader's `switch` keeps a `default` and treats a kind it does not know the
+* way it treats `"none"`.
 */
 /**
+* Whether `schema` is an object of exactly `{ name: string, text: string }`,
+* both required — the one object shape with a declared control.
+*/
+function isNamedTextSchema(schema) {
+	if (schemaTypeOf(schema) !== "object" || !isRecord(schema.properties)) return false;
+	const keys = Object.keys(schema.properties);
+	if (keys.length !== 2 || !keys.includes("name") || !keys.includes("text")) return false;
+	const required = Array.isArray(schema.required) ? schema.required : [];
+	return required.includes("name") && required.includes("text") && schemaTypeOf(schema.properties.name) === "string" && schemaTypeOf(schema.properties.text) === "string";
+}
+/** Whether `schema` is an array of strings. */
+function isStringListSchema(schema) {
+	return schemaTypeOf(schema) === "array" && schemaTypeOf(schema.items) === "string";
+}
+/** The members of a schema's `anyOf`/`oneOf`, when it is a union at all. */
+function unionMembersOf(schema) {
+	const members = schema.anyOf ?? schema.oneOf;
+	return Array.isArray(members) ? members : void 0;
+}
+/** `{ type: "null" }` — the half of a nullable union that wants no control. */
+function isNullSchema(member) {
+	return isRecord(member) && member.type === "null";
+}
+/**
+* The schema with a NULLABLE union unwrapped: `anyOf: [X, { type: "null" }]`
+* reads as `X`, the way `type: ["string", "null"]` reads as `"string"`.
+*
+* Zod 4 converts `z.enum([…]).nullable()` (and any nullable whose inner schema
+* carries keywords of its own) to that `anyOf`, where a bare
+* `z.string().nullable()` becomes the type list — so a required nullable enum
+* used to reach the type switch with no `type` at all, render NO control, and
+* leave a required property out of every submission. A union with two or more
+* non-null members is some other shape and is answered as itself; a schema
+* that is not an object has no answer.
+*
+* Not exported from the package barrel, like {@link schemaTypeOf}.
+*/
+function nonNullSchemaOf(schema) {
+	if (!isRecord(schema)) return void 0;
+	const members = unionMembersOf(schema);
+	if (members === void 0) return schema;
+	const rest = members.filter((member) => !isNullSchema(member));
+	return rest.length === 1 ? nonNullSchemaOf(rest[0]) : schema;
+}
+/**
+* The choices a select renders for `schema`, or undefined when it is not a
+* closed set: a non-empty `enum`, or the `const` of each member of a union of
+* literals — which is how zod 4 converts `z.union([z.literal("p"),
+* z.literal("q")])`, where `z.enum` and `z.literal([1, 2])` convert to `enum`.
+* The values keep their own type (`[1, 2]` stays numeric), so the control can
+* submit what the schema declared.
+*
+* Not exported from the package barrel, like {@link schemaTypeOf}.
+*/
+function schemaChoicesOf(schema) {
+	const inner = nonNullSchemaOf(schema);
+	if (inner === void 0) return void 0;
+	if (Array.isArray(inner.enum)) return inner.enum.length > 0 ? inner.enum : void 0;
+	const members = unionMembersOf(inner)?.filter((member) => !isNullSchema(member));
+	if (members === void 0 || members.length === 0) return void 0;
+	const consts = members.map((member) => isRecord(member) ? member.const : void 0);
+	return consts.every((value) => value !== void 0) ? consts : void 0;
+}
+/**
 * A property's declared type, taking the first non-null member of a union.
 *
 * `["string", "null"]` is how an optional-and-nullable field converts; the
-* control is the one the non-null half wants. Not exported from the package
-* barrel — the published question is the KIND, and this is the one detail
+* control is the one the non-null half wants. A nullable `anyOf` is read the
+* same way ({@link nonNullSchemaOf}). Not exported from the package barrel —
+* the published question is the KIND, and this is the one detail
 * `<WorkflowFields>` needs past it (an integer's `step`).
 */
 function schemaTypeOf(schema) {
-	if (!isRecord(schema)) return void 0;
-	const { type } = schema;
+	const inner = nonNullSchemaOf(schema);
+	if (inner === void 0) return void 0;
+	const { type } = inner;
 	if (typeof type === "string") return type;
 	return Array.isArray(type) ? type.find((member) => member !== "null") : void 0;
 }
@@ -1368,10 +1540,18 @@ function schemaTypeOf(schema) {
 *    person to type an id no person has. The declaration is the workflow's
 *    (`workflow({ uploads: [...] })`), not the schema's, precisely because a
 *    marker inside the schema would only work for the library that carried it.
-* 2. **Then a non-empty `enum`**, before the type switch: an enum of strings
-*    is a `string` too, and a select is the narrower, better control.
+* 2. **Then a closed set of choices**, before the type switch: a non-empty
+*    `enum`, or a union of `const` literals (`schemaChoicesOf`) — an enum
+*    of strings is a `string` too, and a select is the narrower, better
+*    control. A nullable union (`anyOf: [X, { type: "null" }]`) is read as `X`
+*    throughout, as `type: [X, "null"]` already was.
 * 3. **Then the type** — `boolean`, `number`/`integer`, `string`.
-* 4. **Anything else is `"none"`** rather than a guess. See
+* 4. **Then the two non-scalar shapes with a control** — an array of strings
+*    is `"lines"`, an object of exactly `{ name: string, text: string }` is
+*    `"namedText"`. A page may also name either through `render`, which beats
+*    the schema for that property (it is the author saying what the shape
+*    means) but never a declared upload.
+* 5. **Anything else is `"none"`** rather than a guess. See
 *    {@link WorkflowFieldKind}.
 *
 * @example
@@ -1394,20 +1574,24 @@ function schemaTypeOf(schema) {
 * @param schema - The property's JSON Schema, as `GET workflows` reports it.
 *   Anything that is not an object reads as `"none"`.
 * @param options - `upload` says the property is named in the workflow's own
-*   `uploads` declaration, which is what step 1 above tests.
+*   `uploads` declaration, which is what step 1 above tests; `render` is the
+*   page's own choice for the property (`<WorkflowFields render>`).
 *
 * @public
 */
 function fieldKindFor(schema, options) {
 	if (options?.upload === true) return "file";
-	if (!isRecord(schema)) return "none";
-	const { enum: choices } = schema;
-	if (Array.isArray(choices) && choices.length > 0) return "select";
-	switch (schemaTypeOf(schema)) {
+	if (options?.render !== void 0) return options.render;
+	const inner = nonNullSchemaOf(schema);
+	if (inner === void 0) return "none";
+	if (schemaChoicesOf(inner) !== void 0) return "select";
+	switch (schemaTypeOf(inner)) {
 		case "boolean": return "checkbox";
 		case "number":
 		case "integer": return "number";
 		case "string": return "text";
+		case "array": return isStringListSchema(inner) ? "lines" : "none";
+		case "object": return isNamedTextSchema(inner) ? "namedText" : "none";
 		default: return "none";
 	}
 }
@@ -1423,18 +1607,28 @@ function fieldKindFor(schema, options) {
 * workflow's form matches its schema by construction, so adding a field to the
 * schema adds it to the page and nothing can drift.
 *
-* ## It covers SCALARS, and says so rather than guessing
+* ## It covers SCALARS and two more shapes, 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 string, number, integer, boolean or enum has one obvious control each. Most
+* nested objects and arrays do 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}.
+*
+* Two non-scalar shapes DO have an honest control, and are rendered: an array
+* of strings as `<TextAreaField split="lines">` (one per line), and an object
+* of exactly `{ name: string, text: string }` as `<FileField read="text"
+* as="namedText">` (a draft, read in the browser). A page may also ask for
+* either by property name through `render`, for a schema that is one of those
+* but does not say so plainly. Both were the hand-written half of
+* `document-redline-workflow`'s mixed form, reshaped on submit; the fields
+* contribute the schema's shape now, so the form is all declared.
 */
 /**
-* Render one field per scalar property of a workflow's input schema.
+* Render one field per property of a workflow's input schema that has an
+* honest control — every scalar, an array of strings, a `{ name, text }` object.
 *
 * 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
@@ -1465,31 +1659,45 @@ function fieldKindFor(schema, options) {
 * }
 * ```
 *
-* @param props - Field-set props.
+* @param props - See {@link WorkflowFieldsProps}.
 *
 * @public
 */
-function WorkflowFields({ workflow }) {
-	const { workflows, loading } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
+function WorkflowFields({ workflow, render }) {
+	const { workflows, loading, error } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
 	const summary = typeof workflow === "string" ? workflows.find((entry) => entry.name === workflow) : workflow;
 	useDeclareFieldsPending(loading);
+	const unknownName = typeof workflow === "string" && !loading && error === void 0 && summary === void 0;
+	const declared = workflows.map((entry) => entry.name).join(", ");
+	useEffect(() => {
+		if (!unknownName) return;
+		console.warn(`[aai-ui] <WorkflowFields workflow=${JSON.stringify(workflow)}> matches no workflow the agent declares (${declared === "" ? "none listed" : declared}); it renders no fields. Check the name against agent({ workflows }).`);
+	}, [
+		unknownName,
+		workflow,
+		declared
+	]);
 	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$1, { children: Object.entries(schema.properties).map(([name, property]) => /* @__PURE__ */ jsx(SchemaField, {
+	return /* @__PURE__ */ jsx(Fragment$1, { children: Object.entries(schema.properties).map(([name, property]) => isRecord(property) ? /* @__PURE__ */ jsx(SchemaField, {
 		name,
 		property,
 		required: required.has(name),
-		upload: uploads.has(name)
-	}, name)) });
+		upload: uploads.has(name),
+		render: render?.[name]
+	}, name) : null) });
 }
 /** One property's control, or nothing when its type has no obvious one. */
-function SchemaField({ name, property, required, upload = false }) {
+function SchemaField({ name, property, required, upload = false, render }) {
 	const label = humanize(name);
 	const hint = property.description === void 0 ? {} : { hint: property.description };
 	const defaults = property.default === void 0 ? {} : { defaultValue: String(property.default) };
-	switch (fieldKindFor(property, { upload })) {
+	switch (fieldKindFor(property, {
+		upload,
+		render
+	})) {
 		case "file": return /* @__PURE__ */ jsx(FileField, {
 			name,
 			label,
@@ -1497,14 +1705,35 @@ function SchemaField({ name, property, required, upload = false }) {
 			upload: true,
 			...hint
 		});
-		case "select": return /* @__PURE__ */ jsx(SelectField, {
+		case "lines": return /* @__PURE__ */ jsx(TextAreaField, {
 			name,
 			label,
 			required,
-			options: (property.enum ?? []).map((value) => String(value)),
-			...hint,
-			...defaults
+			split: "lines",
+			rows: 3,
+			...hint
+		});
+		case "namedText": return /* @__PURE__ */ jsx(FileField, {
+			name,
+			label,
+			required,
+			read: "text",
+			as: "namedText",
+			...hint
 		});
+		case "select": {
+			const choices = schemaChoicesOf(property) ?? [];
+			const numeric = choices.length > 0 && choices.every((value) => typeof value === "number");
+			return /* @__PURE__ */ jsx(SelectField, {
+				name,
+				label,
+				required,
+				options: choices.map((value) => String(value)),
+				...omitUndefined({ "data-aai-value": numeric ? "number" : void 0 }),
+				...hint,
+				...defaults
+			});
+		}
 		case "checkbox": return /* @__PURE__ */ jsx(CheckboxField, {
 			name,
 			label,
@@ -1547,7 +1776,7 @@ function humanize(name) {
 //#region src/components/workflow-pending-note.tsx
 /** @jsxImportSource react */
 /**
-* The one sentence a page says while a run is in flight — three situations,
+* The one sentence a page says while a run is in flight — five situations,
 * one line each — as a muted line under the form, and nothing otherwise.
 *
 * Six template pages had each written the function under this, byte-identical
@@ -1570,9 +1799,18 @@ function humanize(name) {
 *
 * `startedHere`, `run` and `pending` are what {@link WorkflowSubmission}
 * reports, which is why the prop is the submission itself rather than three
-* booleans a page would re-derive. A page with a FOURTH situation — a run that a
-* reload does not recover but ENDS, as `transcription-workflow`'s streaming
-* flow has — writes its own sentence, and that template is the one doing so.
+* booleans a page would re-derive. The two situations past those three read
+* two more of its fields, and used to be the one page that wrote its own note:
+*
+* - **A run nothing will find again** (`scope: "none"` — `useWorkflowStream`,
+*   whose run reads the recording as this page sends it and gives up on one
+*   that stops arriving, or `recover: false`): "keep this tab open", because
+*   a reload does not orphan that run, it ENDS it. A page telling a reader they
+*   can close the tab would be wrong in exactly that mode.
+* - **A PAUSED upload** is that same fact arriving through a button, which is
+*   why it is tested first and why its two sentences differ: with no run yet
+*   a pause costs nothing, and in the streaming mode the run is already
+*   watching an upload it will give up on.
 *
 * @example
 * ```tsx
@@ -1588,15 +1826,18 @@ function humanize(name) {
 *
 * @public
 */
-function WorkflowPendingNote({ submission, subject = "run", scope = "tab", className }) {
+function WorkflowPendingNote({ submission, subject = "run", scope, className }) {
 	if (!submission.pending) return null;
 	return /* @__PURE__ */ jsx("p", {
 		className: clsx("text-sm opacity-70", className),
-		children: pendingNote(submission, subject, scope)
+		children: pendingNote(submission, subject, scope ?? submission.scope ?? "tab")
 	});
 }
-/** The sentence itself, over the three states the doc above names. */
+/** The sentence itself, over the five states the doc above names. */
 function pendingNote(submission, subject, scope) {
+	const recoverable = scope !== "none";
+	if (submission.upload?.paused === true) return recoverable ? "Upload paused — nothing has started yet, so resume whenever you are ready." : `Upload paused — resume within a few minutes: the ${subject} has already started and gives up on a file that stops arriving.`;
+	if (!recoverable) return `Keep this tab open — the ${subject} is being made from what this page sends, so a reload ends it.`;
 	const here = scope === "browser" ? "this browser" : "this tab";
 	if (submission.startedHere) return scope === "browser" ? `You can close this tab — this browser will find the ${subject} again.` : `Reloading is safe — this page will find the ${subject} again.`;
 	if (submission.run === void 0) return `Looking for the ${subject} ${here} started earlier…`;
@@ -1835,7 +2076,7 @@ function WorkflowRunPanel({ run, statusLabels, onClear, api, live, children, cla
 */
 /** The item as the log keeps it: a tool call's `result` dropped. */
 function logItem(item) {
-	if (item.kind === "message" || item.toolCall.result === void 0) return item;
+	if (item.kind !== "tool" || item.toolCall.result === void 0) return item;
 	const { result: _result, ...toolCall } = item.toolCall;
 	return {
 		kind: "tool",
@@ -1845,7 +2086,11 @@ function logItem(item) {
 /** One item's identity as a turn — ignoring ids and a tool call going pending → done. */
 function turnKey(item) {
 	if (!item) return "";
-	return item.kind === "message" ? `m${item.message.role}:${item.message.content}` : `t${item.toolCall.name}:${JSON.stringify(item.toolCall.args)}`;
+	switch (item.kind) {
+		case "message": return `m${item.message.role}:${item.message.content}`;
+		case "tool": return `t${item.toolCall.name}:${JSON.stringify(item.toolCall.args)}`;
+		default: return `o${item.type}`;
+	}
 }
 /** The same turn in the same state — what makes a rewrite a no-op. */
 function sameItem(a, b) {
@@ -1976,11 +2221,15 @@ function parseItem(raw) {
 	if (!isRecord(raw)) return void 0;
 	if (raw.kind === "message" && isRecord(raw.message)) return parseMessage(raw.message);
 	if (raw.kind === "tool" && isRecord(raw.toolCall)) return parseToolCall(raw.toolCall);
+	if (typeof raw.kind === "string" && raw.kind !== "message" && raw.kind !== "tool") return {
+		kind: "other",
+		type: raw.kind === "other" && typeof raw.type === "string" ? raw.type : raw.kind
+	};
 }
 function parseMessage(raw) {
 	const { id, role, content } = raw;
 	if (typeof id !== "number" || typeof content !== "string") return void 0;
-	return role === "user" || role === "assistant" ? message(id, role, content) : void 0;
+	return typeof role === "string" && role !== "" ? message(id, role, content) : void 0;
 }
 function parseToolCall(raw) {
 	const { callId, name, args, status, seq, afterMessageId } = raw;
@@ -2029,6 +2278,58 @@ function parseLog(raw, max) {
 	if (!Array.isArray(parsed)) return [];
 	return trim(parsed.map(parseEntry).filter((e) => e !== void 0), max);
 }
+//#endregion
+//#region src/dictation-transcriber.ts
+/**
+* `dictationTranscriber(url)` — the `transcribe` callback `useDictation` needs,
+* for a server answering the SDK's `handleDictationRequest`.
+*
+* Every page that dictates writes the same few lines: POST the clip, read
+* `{ text }`, and turn a refusal into an error whose message is the SERVER's
+* sentence ("Recording too long — keep it under 120 seconds", "Transcription
+* is rate limited — try again shortly") rather than a bare status. This is
+* those lines, against the one reply shape the SDK route answers with.
+*/
+/**
+* A `transcribe` for `useDictation` that POSTs each clip to `url` and
+* reads the `{ text } | { error }` reply `handleDictationRequest` answers with.
+*
+* Rejects with the server's own `error` sentence on a refusal, and with a
+* status-naming message when the reply is not that shape (a proxy's HTML error
+* page) — `useDictation` shows either as its `error`.
+*
+* @param url - The route, resolved like any `fetch` URL (relative to the page).
+*
+* @example
+* ```ts
+* import { dictationTranscriber } from "@alexkroman1/aai-ui";
+*
+* export const transcribe = dictationTranscriber("/api/dictation", {
+*   headers: () => ({ authorization: `Bearer ${localStorage.getItem("token") ?? ""}` }),
+* });
+* ```
+*
+* @public
+*/
+function dictationTranscriber(url, options = {}) {
+	return async (audio, { signal }) => {
+		const send = options.fetch ?? fetch;
+		const extra = typeof options.headers === "function" ? options.headers() : options.headers;
+		const res = await send(url, {
+			method: "POST",
+			body: audio,
+			headers: {
+				"Content-Type": audio.type || "audio/wav",
+				...extra
+			},
+			signal
+		});
+		const body = await res.json().catch(() => void 0);
+		if (res.ok && isRecord(body) && typeof body.text === "string") return body.text;
+		if (isRecord(body) && typeof body.error === "string") throw new Error(body.error);
+		throw new Error(`Dictation failed (HTTP ${res.status})`);
+	};
+}
 /** Parse a text frame as one of the wire's server frames, or undefined. */
 function parseServerFrame(json) {
 	const parsed = InboxServerFrameSchema.safeParse(safeJsonParse$1(json));
@@ -2055,15 +2356,27 @@ function parseNoticeHeader(json) {
 		bytes
 	};
 }
+/** The wire frame types this version knows; anything else is an `"other"` event. */
+const KNOWN_FRAME_TYPES = /* @__PURE__ */ new Set([
+	"notice",
+	"session_event",
+	"session_ended"
+]);
 /**
-* A live-event frame, or undefined for anything else (a notice header, say).
-* The wire's live frames are returned as the published {@link InboxEvent}, so
-* that view cannot drift from what the server sends without this failing to
-* compile.
+* A live-event frame, or undefined for a notice header or a frame that is not
+* one at all. The wire's live frames are returned as the published
+* {@link InboxEvent}, so that view cannot drift from what the server sends
+* without this failing to compile; a well-formed frame of a type this version
+* does not know is `{ type: "other" }`.
 */
 function parseInboxEvent(json) {
-	const frame = parseServerFrame(json);
-	return frame === void 0 || frame.type === "notice" ? void 0 : frame;
+	const raw = safeJsonParse$1(json);
+	if (isRecord(raw) && typeof raw.type === "string" && !KNOWN_FRAME_TYPES.has(raw.type)) return {
+		type: "other",
+		frameType: raw.type
+	};
+	const parsed = InboxServerFrameSchema.safeParse(raw);
+	return !parsed.success || parsed.data.type === "notice" ? void 0 : parsed.data;
 }
 /**
 * The receiving state machine of one socket — see the module doc for its four
@@ -2811,6 +3124,131 @@ function useSubmissionState(recover) {
 	};
 }
 //#endregion
+//#region src/_submission-timing.ts
+/**
+* The press-to-settle stopwatch both submit hooks report as
+* `WorkflowSubmission.timing`: the mark `submit()` was called at, and the mark
+* the submission settled at, read off the one flag that spans both waits.
+*
+* It is the half of `transcription-workflow`'s `useTotalLatency` that is a
+* fact about the SUBMISSION rather than about the page: that template kept
+* `startedAt`/`frozenMs` in its own state, armed by its own submit handler
+* and cleared by its own Clear button — shadow state for two instants only
+* the hook can place exactly. The rendering half (the interval that re-draws
+* a running clock, the "before the run / inside it" split) stays on the page,
+* because it is the page that decides how to print a duration.
+*
+* Two details it would be easy to get wrong, both kept from the template:
+*
+* - **The settle is measured in the effect that sees `pending` fall**, so the
+*   mark is the moment the run settled rather than whenever the page next
+*   drew. And only after `pending` has been seen TRUE since the press — a
+*   press that lands one render before the submission reports itself in
+*   flight would otherwise freeze the clock at zero.
+* - **`performance.now()`, not `Date.now()`.** Monotonic; see
+*   `WorkflowSubmissionTiming`.
+*/
+const NONE = {};
+/**
+* The stopwatch over `pending` — see the module doc.
+*
+* @param pending - The submission's own `pending`: true from the press until
+*   the run settles, which is the whole of what the clock covers.
+*/
+function useSubmissionTiming(pending) {
+	const [timing, setTiming] = useState(NONE);
+	const began = useRef(false);
+	useEffect(() => {
+		if (timing.submittedAt === void 0 || timing.settledAt !== void 0) return;
+		if (pending) {
+			began.current = true;
+			return;
+		}
+		if (began.current) {
+			const settledAt = performance.now();
+			setTiming((at) => at.settledAt === void 0 ? {
+				...at,
+				settledAt
+			} : at);
+		}
+	}, [pending, timing]);
+	return {
+		timing,
+		markSubmitted: useCallback(() => {
+			began.current = false;
+			setTiming({ submittedAt: performance.now() });
+		}, []),
+		clear: useCallback(() => {
+			began.current = false;
+			setTiming(NONE);
+		}, [])
+	};
+}
+//#endregion
+//#region src/_submission.ts
+/**
+* Everything a submit hook is, bar its BODY.
+*
+* `useWorkflowSubmit` (`use-workflow-form.ts`) and `useWorkflowStream`
+* (`use-workflow-stream.ts`) differ in one thing — when the run is created
+* relative to the bytes — and that one thing is the submission body each hands
+* to the form's statechart. Everything after the body was written out twice,
+* identically: the watch over the run id (`useWorkflowRun`), the two controls
+* bound to it (`_run-controls.ts`), `pending` as "the machine is busy or the
+* watch is still polling", the press-to-settle stopwatch
+* (`_submission-timing.ts`), a `reset` that clears both, and the fourteen-field
+* `WorkflowSubmission` assembled from all of it. Two copies of a return object
+* that have to agree field for field are two copies that can stop agreeing —
+* the stream hook's type is an ALIAS of the form hook's for the same reason —
+* so the tail is one function, and each hook keeps only what makes it itself.
+*/
+/**
+* The shared tail of a submit hook: the statechart, the watch, the controls,
+* the stopwatch, and the `WorkflowSubmission` built from them. See the module
+* doc.
+*/
+function useSubmission(options) {
+	const { getClient, api, intervalMs, recover, scope, begin } = options;
+	const form = useSubmissionState(recover);
+	const { runId, actions } = form;
+	const tracked = useWorkflowRun(runId, omitUndefined({
+		api,
+		intervalMs
+	}));
+	const { wake, cancel } = useRunControls(runId, getClient);
+	const pending = form.busy || tracked.polling;
+	const { timing, markSubmitted, clear: clearTiming } = useSubmissionTiming(pending);
+	const submit = useCallback((input) => {
+		markSubmitted();
+		const { gate, work } = begin(input, getClient());
+		return actions.submit(gate, work);
+	}, [
+		begin,
+		getClient,
+		actions,
+		markSubmitted
+	]);
+	return {
+		submit,
+		submitForm: submit,
+		reset: useCallback(() => {
+			clearTiming();
+			actions.reset();
+		}, [actions, clearTiming]),
+		wake,
+		cancel,
+		pauseUpload: actions.pauseUpload,
+		resumeUpload: actions.resumeUpload,
+		run: tracked.run,
+		startedHere: form.startedHere,
+		pending,
+		upload: form.upload,
+		error: form.startError ?? tracked.error,
+		timing,
+		scope
+	};
+}
+//#endregion
 //#region src/_workflow-files.ts
 /**
 * Which of a submitted form's values are FILES.
@@ -3382,6 +3820,20 @@ function mintRunKey(storage) {
 	return minted;
 }
 /**
+* Refuse a caller's key that is empty or whitespace.
+*
+* A key is the lookup CAPABILITY (see the module doc), so one that computes to
+* `""` is not "no key": it is ONE key, SHARED by every visitor whose key came
+* out the same way — `user?.id ?? ""` before the login resolves is the natural
+* way to write it — and they then record and recover each other's runs. The
+* server refuses the same value with a 400 (`workflow/api/runs.ts`), but a
+* refusal at the hook names the line that computed it.
+*/
+function assertUsableRunKey(key) {
+	if (key.trim() !== "") return;
+	throw new Error(`useWorkflowSubmit({ key }) was given ${JSON.stringify(key)}, an empty key. A key is the lookup capability runs are recorded under, so an empty one would be SHARED by every visitor whose key computed to "" (a \`user?.id ?? ""\` before login is the usual cause). Pass undefined until the key is known — the hook mints a per-page key of its own — or a non-blank string.`);
+}
+/**
 * The key `useWorkflowSubmit` uses when the page named none.
 *
 * Two things it does that a plain `useRunKey()` at the call site cannot, and
@@ -3401,12 +3853,15 @@ function mintRunKey(storage) {
 *
 * @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.
+* @throws When the caller's key is empty or whitespace — see
+*   {@link assertUsableRunKey}.
 *
 * @internal
 */
 function useDefaultRunKey(explicit) {
-	const [minted] = useState(() => explicit === void 0 ? mintRunKey("session") : "");
-	return explicit ?? minted;
+	if (typeof explicit === "string") assertUsableRunKey(explicit);
+	const [minted] = useState(() => typeof explicit === "string" ? "" : mintRunKey(explicit?.storage ?? "session"));
+	return typeof explicit === "string" ? explicit : minted;
 }
 /**
 * A lookup key for `useWorkflowSubmit({ key })`, stable across reloads.
@@ -3431,7 +3886,8 @@ function useRunKey(options = {}) {
 * `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`.
+* `<WorkflowFields>` renders a form from — is `use-workflows.ts`. What it hands
+* back is `WorkflowSubmission` (`workflow-submission.ts`).
 *
 * ## `useWorkflowSubmit` — a form's two halves in one hook
 *
@@ -3459,89 +3915,53 @@ function useRunKey(options = {}) {
 * followed from the same id either way.
 */
 /**
-* Start a workflow from a form, and follow the run it creates.
-*
-* @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`.
-*
-*   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.
-*
-* @example
-* ```tsx no-check
-* import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
-* import type { digest } from "./agent.ts";
-*
-* 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>
-*   );
-* }
-* ```
-*
-* @public
+* Who can find the run again, from the two options that decide it — see
+* `WorkflowSubmissionScope`. A page-supplied string key is read as
+* `"browser"`: it is at least that wide (an account id is wider still), and
+* "close this tab" is true of it.
 */
+function scopeOf(key, recover) {
+	if (!recover) return "none";
+	if (typeof key === "string") return "browser";
+	return key?.storage === "local" ? "browser" : "tab";
+}
 function useWorkflowSubmit(workflow, options = {}) {
 	const { api, recover = true, wait, intervalMs, parallel } = options;
 	const key = useDefaultRunKey(options.key);
+	const scope = scopeOf(options.key, recover);
 	const getClient = useWorkflowApiRef(api);
-	const form = useSubmissionState({
-		workflow,
-		key,
-		enabled: recover,
-		getClient
-	});
-	const { runId, actions } = form;
-	const tracked = useWorkflowRun(runId, omitUndefined({
-		api,
-		intervalMs
-	}));
-	const { wake, cancel } = useRunControls(runId, getClient);
-	const submit = useCallback((input) => {
-		const client = getClient();
+	const begin = useCallback((input, client) => {
 		const session = createUploadSession(workflow);
-		return actions.submit(session.gate, async ({ progress, started }) => {
-			const options = omitUndefined({ key });
-			const report = coalesceUploadReports(progress);
-			const stored = await uploadFiles(client, input, report, parallel, session);
-			started(wait === void 0 ? await client.start(workflow, stored, options) : (await client.startAndWait(workflow, stored, {
-				...options,
-				wait
-			})).runId);
-		});
+		return {
+			gate: session.gate,
+			work: async ({ progress, started }) => {
+				const options = omitUndefined({ key });
+				const stored = await uploadFiles(client, input, coalesceUploadReports(progress), parallel, session);
+				started(wait === void 0 ? await client.start(workflow, stored, options) : (await client.startAndWait(workflow, stored, {
+					...options,
+					wait
+				})).runId);
+			}
+		};
 	}, [
 		workflow,
 		key,
 		wait,
-		parallel,
-		getClient,
-		actions
+		parallel
 	]);
-	return {
-		submit,
-		submitForm: submit,
-		reset: actions.reset,
-		wake,
-		cancel,
-		pauseUpload: actions.pauseUpload,
-		resumeUpload: actions.resumeUpload,
-		run: tracked.run,
-		startedHere: form.startedHere,
-		pending: form.busy || tracked.polling,
-		upload: form.upload,
-		error: form.startError ?? tracked.error
-	};
+	return useSubmission({
+		getClient,
+		api,
+		intervalMs,
+		recover: {
+			workflow,
+			key,
+			enabled: recover,
+			getClient
+		},
+		scope,
+		begin
+	});
 }
 //#endregion
 //#region src/_page-shell.tsx
@@ -3835,7 +4255,7 @@ function phoneE164(typed, options = {}) {
 * @param method - The route's method.
 * @param path - The route's path as declared, starting with `/`; `?query` allowed.
 * @param body - Sent as JSON when given.
-* @param options - `client`, `baseUrl` and `signal`; see {@link RouteFetchOptions}.
+* @param options - `client`, `baseUrl`, `headers` and `signal`; see {@link RouteFetchOptions}.
 * @returns The parsed JSON body.
 *
 * @public
@@ -3844,13 +4264,18 @@ async function routeFetch(method, path, body, options = {}) {
 	const base = options.baseUrl ?? pageBaseUrl();
 	const url = new URL(`api${path.startsWith("/") ? path : `/${path}`}`, base);
 	if (options.client) url.searchParams.set("client", options.client);
+	const given = Object.fromEntries(Object.entries(options.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
+	const headers = omitUndefined({
+		"content-type": body === void 0 ? void 0 : "application/json",
+		...given
+	});
 	const res = await fetch(url, {
 		method,
-		...body === void 0 ? {} : {
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify(body)
-		},
-		...omitUndefined({ signal: options.signal })
+		...omitUndefined({
+			headers: Object.keys(headers).length > 0 ? headers : void 0,
+			body: body === void 0 ? void 0 : JSON.stringify(body),
+			signal: options.signal
+		})
 	});
 	const json = await res.json().catch(() => ({}));
 	if (!res.ok) {
@@ -3998,12 +4423,20 @@ function useStoredValue(source, initial) {
 * dropped — `useWorkflowRuns`' rule), a read landing after unmount, and a
 * failure rendered as an empty answer. `data` is KEPT through a failed re-read,
 * so a poll that hiccups does not blank the panel; `error` says it is stale.
+* It is NOT kept across a change of `path`: the answer is remembered with the
+* path it came from, so a page switching from one record to the next never
+* shows the previous one under the new id while the first read is in flight.
+*
+* The poll is `repeatUntil`'s loop (`_repeat-until.ts`), re-armed from the
+* SETTLED read rather than on an interval — a slow route would otherwise
+* stack overlapping reads — and stopped by `until`, by a change of what is
+* read, and by unmount, with the in-flight request aborted on the same signal.
 *
 * @module
 */
 /**
 * `GET` one of the agent's own routes, on mount, on `reload()` and every
-* `pollMs` — see this module's doc.
+* `pollMs` until `until` says so — see this module's doc.
 *
 * @example A list that re-reads after each delete
 * ```tsx
@@ -4033,9 +4466,24 @@ function useStoredValue(source, initial) {
 * }
 * ```
 *
+* @example A call followed until it is over
+* ```tsx
+* import { useRoute } from "@alexkroman1/aai-ui";
+*
+* type Call = { status: string; transcript: { role: string; text: string }[] };
+*
+* function LiveCall({ id }: { id: string }) {
+*   const { data } = useRoute<Call>(`/calls/${id}`, {
+*     pollMs: 2000,
+*     until: (call) => call.status === "completed",
+*   });
+*   return <ol>{data?.transcript.map((line, i) => <li key={String(i)}>{line.text}</li>)}</ol>;
+* }
+* ```
+*
 * @typeParam T - The shape the route answers. Not checked.
 * @param path - The route's path as declared, without `/api`. `null` reads nothing.
-* @param options - `pollMs` and `client`; see {@link UseRouteOptions}.
+* @param options - `pollMs`, `until`, `client` and `headers`; see {@link UseRouteOptions}.
 * @returns The answer, the last error, and `reload`; see {@link UseRouteResult}.
 *
 * @public
@@ -4043,49 +4491,85 @@ function useStoredValue(source, initial) {
 function useRoute(path, options = {}) {
 	const session = useOptionalSessionCore();
 	const { pollMs, client } = options;
-	const [data, setData] = useState(void 0);
-	const [error, setError] = useState(void 0);
+	if (pollMs !== void 0 && !(Number.isFinite(pollMs) && pollMs >= 0)) throw new Error(`useRoute: pollMs must be a non-negative number, not ${String(pollMs)}`);
+	const [answer, setAnswer] = useState(void 0);
 	const [loading, setLoading] = useState(path !== null);
+	const perRequest = useRef({
+		until: options.until,
+		headers: options.headers
+	});
+	perRequest.current = {
+		until: options.until,
+		headers: options.headers
+	};
 	const epochRef = useRef(void 0);
 	epochRef.current ??= createEpoch();
 	const epoch = epochRef.current;
-	const reload = useCallback(() => {
-		if (path === null) return;
+	/**
+	* One read. Resolves whether the poll (if any) is FINISHED: `until` was
+	* satisfied. A read that was superseded by a newer one (a `reload()`, or the
+	* unmount's bump) answers `false` — its ANSWER is nobody's, but the poll is
+	* still owed its next tick: `true` here would stop `repeatUntil` for good on
+	* the first reload during a poll. The unmount is what stops the loop, through
+	* its own `stop()`, and a loop whose signal is aborted never re-arms.
+	*/
+	const read = useCallback(async (signal) => {
+		if (path === null) return true;
 		epoch.bump();
 		const mine = epoch.current();
 		setLoading(true);
-		const who = client ?? session?.identity.clientId();
-		routeFetch("GET", path, void 0, who ? { client: who } : {}).then((answer) => {
-			if (!epoch.isCurrent(mine)) return;
-			setData(answer);
-			setError(void 0);
+		const { until, headers } = perRequest.current;
+		try {
+			const answer = await routeFetch("GET", path, void 0, { ...omitUndefined({
+				client: client ?? session?.identity.clientId(),
+				headers,
+				signal
+			}) });
+			if (!epoch.isCurrent(mine)) return false;
+			setAnswer({
+				path,
+				data: answer,
+				error: void 0
+			});
 			setLoading(false);
-		}).catch((err) => {
-			if (!epoch.isCurrent(mine)) return;
-			setError(errorMessage$1(err));
+			return until?.(answer) === true;
+		} catch (err) {
+			if (!epoch.isCurrent(mine)) return false;
+			setAnswer((prior) => ({
+				path,
+				data: prior?.path === path ? prior.data : void 0,
+				error: errorMessage$1(err)
+			}));
 			setLoading(false);
-		});
+			return false;
+		}
 	}, [
 		path,
 		client,
 		session,
 		epoch
 	]);
+	const reload = useCallback(() => {
+		read();
+	}, [read]);
 	useEffect(() => {
-		reload();
-		const timer = pollMs ? setInterval(reload, pollMs) : void 0;
+		const stop = pollMs !== void 0 && pollMs > 0 ? repeatUntil(pollMs, read) : ((controller) => {
+			read(controller.signal);
+			return () => controller.abort();
+		})(new AbortController());
 		return () => {
-			clearInterval(timer);
+			stop();
 			epoch.bump();
 		};
 	}, [
-		reload,
+		read,
 		pollMs,
 		epoch
 	]);
+	const current = answer?.path === path ? answer : void 0;
 	return {
-		data,
-		error,
+		data: current?.data,
+		error: current?.error,
 		loading,
 		reload
 	};
@@ -4405,7 +4889,7 @@ function useConversationLog(options = {}) {
 	own.current = sessionId;
 	const mirrored = useRef(/* @__PURE__ */ new Map());
 	const mirror = useCallback((event) => {
-		if (event.sessionId === own.current) return;
+		if (event.type === "other" || event.sessionId === own.current) return;
 		if (event.type === "session_ended") {
 			mirrored.current.delete(event.sessionId);
 			return;
@@ -4465,6 +4949,209 @@ function append(list, event) {
 	return item ? [...list, item] : void 0;
 }
 //#endregion
+//#region src/use-dictation.ts
+/**
+* `useDictation` — speak into a text box: record a clip, have it transcribed,
+* hand the words to the page.
+*
+* Not a session. There is no agent on the other end and no socket: the clip
+* goes to AssemblyAI's dictation API in ONE request, through a `transcribe`
+* callback the page supplies — on the far side of which is a server holding
+* the key, calling `transcribeDictation` from `@alexkroman1/aai/experimental`.
+* The key never reaches the browser, which is why this hook takes a callback
+* rather than a credential.
+*
+* The two ends that are not this hook are published too: `dictationTranscriber`
+* is the `transcribe` for a server answering `handleDictationRequest`'s
+* `{ text } | { error }`, and `appendDictation` adds the words to a draft.
+*
+* What it owns, because each is a way a hand-written mic button goes wrong:
+*
+* - **The recording indicator goes out.** Every way out — stop, cancel, the
+*   length cap, an unmount mid-recording — releases the microphone.
+* - **A late answer lands nowhere.** A transcription that settles after a
+*   cancel, a newer recording or an unmount is dropped, never typed into the
+*   box the user has moved on from.
+* - **The button cannot be pressed into a bad state.** `buttonProps` keeps a
+*   recording stoppable while `disabled`, and takes no press mid-transition.
+* - **The clip fits the endpoint.** Recording stops by itself at `maxSeconds`
+*   and is transcribed, rather than growing into a clip the service refuses
+*   whole.
+*/
+const openRecorder = async (opts) => {
+	const [audio, captureWorkletSrc] = await Promise.all([import("./audio/index.js"), import("./worklets/capture-processor.js").then((m) => m.default)]);
+	return audio.openDictationRecorder({
+		...opts,
+		captureWorkletSrc
+	});
+};
+/** Stop `rec` and transcribe the clip; `""` when aborted before the request. */
+async function transcribeRecording(rec, signal, transcribe) {
+	const wav = await rec.stop();
+	if (signal.aborted) return "";
+	return (await transcribe(new Blob([wav], { type: "audio/wav" }), { signal })).trim();
+}
+function browserCanRecord() {
+	return typeof navigator !== "undefined" && typeof navigator.mediaDevices?.getUserMedia === "function" && typeof AudioContext !== "undefined" && typeof AudioWorkletNode !== "undefined";
+}
+/**
+* Record what the user says and hand it back as text — a microphone button
+* for a text box.
+*
+* @example
+* ```tsx
+* import { appendDictation, dictationTranscriber, useDictation } from "@alexkroman1/aai-ui";
+* import { useState } from "react";
+*
+* // `POST /dictation` on your own server is `handleDictationRequest`
+* // (`@alexkroman1/aai/experimental`), which holds the API key.
+* const transcribe = dictationTranscriber("/dictation");
+*
+* export function SpokenNote() {
+*   const [draft, setDraft] = useState("");
+*   const dictation = useDictation({
+*     transcribe,
+*     onText: (text) => setDraft((d) => appendDictation(d, text)),
+*   });
+*   return (
+*     <div>
+*       <textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
+*       {dictation.supported && (
+*         <button type="button" {...dictation.buttonProps}>
+*           {dictation.phase === "recording" ? "Stop" : "Speak"}
+*         </button>
+*       )}
+*     </div>
+*   );
+* }
+* ```
+*
+* @public
+*/
+function useDictation(options) {
+	return useDictationWith(options, openRecorder);
+}
+/**
+* {@link useDictation} over an injected recorder — the seam the specs drive.
+* Not on the barrel.
+*/
+function useDictationWith(options, open) {
+	const [phase, setPhase] = useState("idle");
+	const [error, setError] = useState(null);
+	const supported = useMemo(browserCanRecord, []);
+	const latest = useRef(options);
+	latest.current = options;
+	const openRef = useRef(open);
+	openRef.current = open;
+	const epoch = useRef(createEpoch()).current;
+	const phaseRef = useRef("idle");
+	const recorder = useRef(null);
+	const inflight = useRef(null);
+	const cap = useRef(null);
+	const move = useCallback((next) => {
+		phaseRef.current = next;
+		setPhase(next);
+	}, []);
+	const clearCap = useCallback(() => {
+		if (cap.current !== null) clearTimeout(cap.current);
+		cap.current = null;
+	}, []);
+	/** Drop whatever is running, releasing the microphone. Leaves `phase` alone. */
+	const abandon = useCallback(() => {
+		epoch.bump();
+		clearCap();
+		inflight.current?.abort();
+		inflight.current = null;
+		const rec = recorder.current;
+		recorder.current = null;
+		rec?.cancel();
+	}, [epoch, clearCap]);
+	const stop = useCallback(() => {
+		const rec = recorder.current;
+		if (phaseRef.current !== "recording" || !rec) return;
+		recorder.current = null;
+		clearCap();
+		move("transcribing");
+		const gen = epoch.current();
+		const controller = new AbortController();
+		inflight.current = controller;
+		const settle = () => {
+			inflight.current = null;
+			move("idle");
+		};
+		transcribeRecording(rec, controller.signal, latest.current.transcribe).then((text) => {
+			if (!epoch.isCurrent(gen)) return;
+			if (text) latest.current.onText(text);
+			settle();
+		}, (err) => {
+			if (!epoch.isCurrent(gen)) return;
+			setError(errorMessage$1(err));
+			settle();
+		});
+	}, [
+		epoch,
+		clearCap,
+		move
+	]);
+	const start = useCallback(() => {
+		if (phaseRef.current !== "idle" || latest.current.disabled === true) return;
+		setError(null);
+		move("starting");
+		const gen = epoch.current();
+		const maxSeconds = latest.current.maxSeconds ?? DICTATION_MAX_SECONDS;
+		openRef.current({
+			sampleRate: DICTATION_SAMPLE_RATE,
+			maxSeconds
+		}).then((rec) => {
+			if (!epoch.isCurrent(gen)) {
+				rec.cancel();
+				return;
+			}
+			recorder.current = rec;
+			move("recording");
+			cap.current = setTimeout(stop, maxSeconds * 1e3);
+		}).catch((err) => {
+			if (!epoch.isCurrent(gen)) return;
+			setError(errorMessage$1(err));
+			move("idle");
+		});
+	}, [
+		epoch,
+		move,
+		stop
+	]);
+	const cancel = useCallback(() => {
+		if (phaseRef.current === "idle") return;
+		abandon();
+		move("idle");
+	}, [abandon, move]);
+	const toggle = useCallback(() => {
+		if (phaseRef.current === "idle") start();
+		else if (phaseRef.current === "recording") stop();
+	}, [start, stop]);
+	useEffect(() => abandon, [abandon]);
+	const recording = phase === "recording";
+	const blocked = phase === "starting" || phase === "transcribing" || options.disabled === true && !recording;
+	return {
+		phase,
+		error,
+		supported,
+		start,
+		stop,
+		cancel,
+		toggle,
+		buttonProps: useMemo(() => ({
+			onClick: toggle,
+			disabled: blocked,
+			"aria-pressed": recording
+		}), [
+			toggle,
+			blocked,
+			recording
+		])
+	};
+}
+//#endregion
 //#region src/use-download-url.ts
 /**
 * `useDownloadUrl` — an upload id a run produced, as something `<audio>`,
@@ -5325,24 +6012,6 @@ function useTapToTalk(options = {}) {
 * a page calls when its own run settles, which is exactly when the list is
 * stale.
 */
-/**
-* Read a workflow's recent runs.
-*
-* @typeParam R - The workflow's output type, so a completed run's `output` is
-*   typed rather than `unknown`. Derive it with `WorkflowOutputOf`.
-*
-* @example
-* ```tsx
-* import { useWorkflowRuns } from "@alexkroman1/aai-ui";
-*
-* function History() {
-*   const { runs } = useWorkflowRuns("transcribe", { limit: 10 });
-*   return <ul>{runs.map((run) => <li key={run.runId}>{run.status}</li>)}</ul>;
-* }
-* ```
-*
-* @public
-*/
 function useWorkflowRuns(workflow, options = {}) {
 	const { api, limit, key, skip = false } = options;
 	const [runs, setRuns] = useState([]);
@@ -5479,94 +6148,53 @@ function useWorkflowRuns(workflow, options = {}) {
 * `stream.ts`'s idle bound (five minutes of no new bytes) is what decides that a
 * pause has become an abandonment.
 */
-/**
-* Start a workflow run and stream a file into it while it works.
-*
-* The workflow declares which input property carries the upload
-* (`workflow({ uploads: ["recording"] })`) — the same declaration
-* `useWorkflowSubmit` reads, because what the property carries is an upload id
-* either way. What differs is only WHEN the id becomes valid.
-*
-* @typeParam R - The workflow's output type, which is what makes
-*   `run.status === "completed"` narrow to a typed `run.output`. Derive it with
-*   `WorkflowOutputOf<typeof myWorkflow>`.
-*
-* @example
-* ```tsx no-check
-* const { submit, run, upload, pending, error } = useWorkflowStream("transcribe");
-*
-* <Form onSubmit={(values) => submit(values)} error={error}>
-*   <WorkflowFields workflow="transcribe" />
-*   <UploadProgressBar upload={upload} />
-*   <SubmitButton pending={pending}>Transcribe</SubmitButton>
-* </Form>
-* ```
-*
-* @public
-*/
 function useWorkflowStream(workflow, options = {}) {
 	const { api, key, intervalMs, parallel } = options;
-	const getClient = useWorkflowApiRef(api);
-	const form = useSubmissionState();
-	const { runId, actions } = form;
-	const tracked = useWorkflowRun(runId, omitUndefined({
+	return useSubmission({
+		getClient: useWorkflowApiRef(api),
 		api,
-		intervalMs
-	}));
-	const { wake, cancel } = useRunControls(runId, getClient);
-	const submit = useCallback((input) => {
-		const client = getClient();
-		const gate = createUploadGate();
-		return actions.submit(gate, async ({ progress, started: adopt }) => {
-			let started;
-			try {
-				const id = randomUploadId();
-				const begun = await beginRun({
-					client,
-					workflow,
-					input,
-					id,
-					...omitUndefined({ key })
-				});
-				started = begun.runId;
-				const chosen = begun.file;
-				adopt(started);
-				if (!chosen) return;
-				await streamFile({
-					client,
-					gate,
-					id,
-					file: chosen,
-					parallel,
-					report: coalesceUploadReports(progress)
-				});
-				await client.wake(started).catch(() => void 0);
-			} catch (err) {
-				if (started) await client.cancel(started).catch(() => void 0);
-				throw err;
-			}
-		});
-	}, [
-		workflow,
-		key,
-		parallel,
-		getClient,
-		actions
-	]);
-	return {
-		submit,
-		submitForm: submit,
-		reset: actions.reset,
-		wake,
-		cancel,
-		pauseUpload: actions.pauseUpload,
-		resumeUpload: actions.resumeUpload,
-		run: tracked.run,
-		startedHere: form.startedHere,
-		pending: form.busy || tracked.polling,
-		upload: form.upload,
-		error: form.startError ?? tracked.error
-	};
+		intervalMs,
+		scope: "none",
+		begin: useCallback((input, client) => {
+			const gate = createUploadGate();
+			return {
+				gate,
+				work: async ({ progress, started: adopt }) => {
+					let started;
+					try {
+						const id = randomUploadId();
+						const begun = await beginRun({
+							client,
+							workflow,
+							input,
+							id,
+							...omitUndefined({ key })
+						});
+						started = begun.runId;
+						const chosen = begun.file;
+						adopt(started);
+						if (!chosen) return;
+						await streamFile({
+							client,
+							gate,
+							id,
+							file: chosen,
+							parallel,
+							report: coalesceUploadReports(progress)
+						});
+						await client.wake(started).catch(() => void 0);
+					} catch (err) {
+						if (started) await client.cancel(started).catch(() => void 0);
+						throw err;
+					}
+				}
+			};
+		}, [
+			workflow,
+			key,
+			parallel
+		])
+	});
 }
 /**
 * Read the declaration, substitute the id, and start the run.
@@ -5661,4 +6289,4 @@ function fileAt(input, field) {
 	return filesOf(input[field])[0];
 }
 //#endregion
-export { AGENT_STATE_LABELS, AudioResult, AutoScroll, BulletList, Button, ChatView, CheckboxField, ConsoleShell, Controls, ConversationView, Facts, Field, FileField, Form, Markdown, MessageList, NumberField, SelectField, SessionControls, SessionErrorBanner, SessionStateDot, SidebarLayout, StartScreen, SubmitButton, TextAreaField, TextField, ToolCallRow, UploadProgressBar, WORKFLOW_STATUS_LABELS, WorkflowFields, WorkflowPendingNote, WorkflowProgress, WorkflowRunError, WorkflowRunPanel, browserClientId, createBrowserSession, createInbox, createLinkedClient, createStoredValue, createWorkflowApi, errorMessage, fetchClientConfig, fieldKindFor, inboxEventToItem, isTerminal, mountClient, mountPage, phoneE164, routeFetch, selectAgentState, useAgentState, useClientId, useClientRuns, useClientTool, useConversation, useConversationLog, useCopy, useDownloadUrl, useEvent, useFlash, useInbox, usePushToTalk, useRoute, useRouteMutation, useRunKey, useSession, useSessionActions, useSessionControls, useSessionError, useSessionId, useSessionSelector, useSessionStatus, useStoredValue, useTapToTalk, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };
+export { AGENT_STATE_LABELS, AudioResult, AutoScroll, BulletList, Button, ChatView, CheckboxField, ConsoleShell, Controls, ConversationView, Facts, Field, FileField, Form, Markdown, MessageList, NumberField, SelectField, SessionControls, SessionErrorBanner, SessionStateDot, SidebarLayout, StartScreen, SubmitButton, TextAreaField, TextField, ToolCallRow, UploadProgressBar, WORKFLOW_STATUS_LABELS, WorkflowFields, WorkflowPendingNote, WorkflowProgress, WorkflowRunError, WorkflowRunPanel, appendDictation, browserClientId, createBrowserSession, createInbox, createLinkedClient, createStoredValue, createWorkflowApi, dictationTranscriber, errorMessage, fetchClientConfig, fieldKindFor, inboxEventToItem, isFileValue, isTerminal, mountClient, mountPage, phoneE164, routeFetch, selectAgentState, useAgentState, useClientId, useClientRuns, useClientTool, useConversation, useConversationLog, useCopy, useDictation, useDownloadUrl, useEvent, useFlash, useInbox, usePushToTalk, useRoute, useRouteMutation, useRunKey, useSession, useSessionActions, useSessionControls, useSessionError, useSessionId, useSessionSelector, useSessionStatus, useStoredValue, useTapToTalk, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };