@alexkroman1/aai-ui 13.3.0 → 15.0.0

package/dist/index.js

@@ -1,25 +1,190 @@
-import { n as fetchClientConfig } from "./client-config-DD820zHn.js";
-import { i as AutoScroll, n as Markdown, r as useConversation, t as MessageList } from "./message-list-C0pL7x41.js";
-import { ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
-import { r as inkTint } from "./_colors-CZ6OlPbL.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-Bv5VFJIE.js";
-import { n as setPageTitle } from "./_utils-CyzjK0gW.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 { a as useFlash, i as useCopy } from "./url-chips-D62RTz7v.js";
 import { Controls } from "./components/controls.js";
-import { n as useUserTranscript } from "./use-user-transcript-DFTSEuZN.js";
-import { n as ToolCallRow } from "./tool-call-block-Bunc6rCw.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 useWorkflowProgress, c as isTerminal, o as useWorkflowApiRef, r as useWorkflowRun, s as createWorkflowApi } from "./use-workflow-run-CXGEcM0l.js";
-import { t as createSessionCore } from "./session-core-C9elBIdu.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-CNahvlgL.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 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 +212,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.
 */
@@ -173,7 +338,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";
 }
@@ -274,12 +439,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 +476,14 @@ function useFileControlProps() {
 	};
 }
 /**
-* A single-line text input.
+* `TextField` and `NumberField`, which differ only in the `type` they set.
 *
-* 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
+* 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 +494,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 +528,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 +642,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
@@ -812,14 +980,14 @@ function UploadProgressBar({ upload, onPause, onResume, className }) {
 * }
 * ```
 *
-* @param opts - See {@link UseWorkflowsOptions}.
+* @param options - See {@link UseWorkflowsOptions}.
 * @returns The listing, its loading flag and its failure — see
 * {@link UseWorkflowsResult}.
 *
 * @public
 */
-function useWorkflows(opts = {}) {
-	const { api, skip = false } = opts;
+function useWorkflows(options = {}) {
+	const { api, skip = false } = options;
 	const [state, setState] = useState({
 		workflows: [],
 		loading: !skip,
@@ -850,6 +1018,100 @@ function useWorkflows(opts = {}) {
 	return state;
 }
 //#endregion
+//#region src/workflow-field-kind.ts
+/**
+* Which control one property of a workflow's input schema renders as.
+*
+* `<WorkflowFields>` walks a workflow's `inputSchema` and picks a control per
+* property. This is that decision with nothing rendered — ONE function, called
+* by `SchemaField` itself, so a reader outside the component can ask the same
+* question and get the same answer.
+*
+* **Why it is published.** The rule is not derivable from the schema by
+* inspection: an upload property IS a plain `string` there, and the ORDER
+* matters in a way no reader can see. The studio's API pane documents the
+* form-to-JSON correspondence for every workflow app, and it was carrying a
+* hand-kept mirror of the switch below — "a declared upload beats everything,
+* then `enum`, then …" — with a comment admitting as much and a test pinning
+* the order to catch the drift. A copy that drifted would name a control the
+* reader cannot find on their own page. Nothing else could be done about it
+* while the decision was private, and the same reasoning already settled the
+* 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.
+*/
+/**
+* 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
+* `<WorkflowFields>` needs past it (an integer's `step`).
+*/
+function schemaTypeOf(schema) {
+	if (!isRecord(schema)) return void 0;
+	const { type } = schema;
+	if (typeof type === "string") return type;
+	return Array.isArray(type) ? type.find((member) => member !== "null") : void 0;
+}
+/**
+* Which control `<WorkflowFields>` renders for one property of an input schema.
+*
+* @remarks
+* The ORDER is the contract, and it is the half a reader cannot infer:
+*
+* 1. **A declared upload wins outright.** It is a plain `string` in the schema
+*    — the id — so testing the type first would render a text box asking a
+*    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.
+* 3. **Then the type** — `boolean`, `number`/`integer`, `string`.
+* 4. **Anything else is `"none"`** rather than a guess. See
+*    {@link WorkflowFieldKind}.
+*
+* @example
+* ```ts
+* import { fieldKindFor, type WorkflowFieldKind } from "@alexkroman1/aai-ui";
+* import type { WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+*
+* function kindsOf(summary: WorkflowSummary): Record<string, WorkflowFieldKind> {
+*   const uploads = new Set(summary.uploads ?? []);
+*   const schema = summary.inputSchema as { properties?: Record<string, unknown> };
+*   return Object.fromEntries(
+*     Object.entries(schema.properties ?? {}).map(([name, property]) => [
+*       name,
+*       fieldKindFor(property, { upload: uploads.has(name) }),
+*     ]),
+*   );
+* }
+* ```
+*
+* @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.
+*
+* @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)) {
+		case "boolean": return "checkbox";
+		case "number":
+		case "integer": return "number";
+		case "string": return "text";
+		default: return "none";
+	}
+}
+//#endregion
 //#region src/components/workflow-fields.tsx
 /** @jsxImportSource react */
 /**
@@ -927,39 +1189,37 @@ 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, {
+	switch (fieldKindFor(property, { upload })) {
+		case "file": return /* @__PURE__ */ jsx(FileField, {
+			name,
+			label,
+			required,
+			upload: true,
+			...hint
+		});
+		case "select": return /* @__PURE__ */ jsx(SelectField, {
+			name,
+			label,
+			required,
+			options: (property.enum ?? []).map((value) => String(value)),
+			...hint,
+			...defaults
+		});
+		case "checkbox": return /* @__PURE__ */ jsx(CheckboxField, {
 			name,
 			label,
 			defaultChecked: property.default === true,
 			...hint
 		});
-		case "number":
-		case "integer": return /* @__PURE__ */ jsx(NumberField, {
+		case "number": return /* @__PURE__ */ jsx(NumberField, {
 			name,
 			label,
 			required,
-			step: type === "integer" ? 1 : "any",
+			step: schemaTypeOf(property) === "integer" ? 1 : "any",
 			...hint,
 			...defaults
 		});
-		case "string": return /* @__PURE__ */ jsx(TextField, {
+		case "text": return /* @__PURE__ */ jsx(TextField, {
 			name,
 			label,
 			required,
@@ -969,12 +1229,6 @@ function SchemaField({ name, property, required, upload = false }) {
 		default: return null;
 	}
 }
-/** A property's type, taking the first non-null member of a union. */
-function typeOf(property) {
-	const { type } = property;
-	if (typeof type === "string") return type;
-	return Array.isArray(type) ? type.find((member) => member !== "null") : void 0;
-}
 /** The listing's `unknown` schema as the object shape this reads, when it is one. */
 function asObjectSchema(schema) {
 	return isRecord(schema) ? schema : void 0;
@@ -997,13 +1251,13 @@ function humanize(name) {
 *
 * 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()`
+* 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.
 *
-* Three rules are baked in, and they are why this is a component rather than
+* 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 all three, comments included:
+* it had written three of them, comments included:
 *
 * - **It renders nothing until there is something to render.** `supported` is
 *   what keeps this from being an empty box forever on an agent deployed before
@@ -1017,6 +1271,13 @@ function humanize(name) {
 *   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.
 *
 * @example
 * ```tsx
@@ -1033,27 +1294,33 @@ function humanize(name) {
 */
 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;
+	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: [shown.join("\n"), streaming && "\n…"]
+		children: [text, streaming && "\n…"]
 	});
 }
 //#endregion
 //#region src/page.tsx
 /** @jsxImportSource react */
 /**
-* `page()` — mount a WORKFLOW APP's UI: React, theme, no session.
+* `mountPage()` — mount a WORKFLOW APP's UI: React, theme, no session.
 *
-* The twin of `client()` for an agent whose front door is a form rather than a
+* 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 `client()` because of what `client()` unavoidably does: it
-* constructs a `SessionCore`, which owns a WebSocket URL provider, an audio
+* 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 `client()`; a page that wants neither audio nor a socket uses this.
+* voice uses `mountClient()`; a page that wants neither audio nor a socket uses this.
 *
 * Authoring is otherwise identical — the file is still `client.tsx`, still
 * React, still Tailwind, still the same theme tokens — so a workflow app reads
@@ -1069,7 +1336,7 @@ function WorkflowProgress({ runId, api, className, placeholder, lines }) {
 *
 * @example
 * ```tsx
-* import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
+* import { createWorkflowApi, mountPage, useWorkflowRun } from "@alexkroman1/aai-ui";
 * import { useState } from "react";
 *
 * // Hoisted: a client built in render is a new object every render.
@@ -1088,14 +1355,14 @@ function WorkflowProgress({ runId, api, className, placeholder, lines }) {
 *   );
 * }
 *
-* page({ name: "Digest", component: App });
+* mountPage({ name: "Digest", component: App });
 * ```
 *
 * @throws If the target element is not found in the DOM.
 *
 * @public
 */
-function page(config) {
+function mountPage(config) {
 	const container = resolveContainer(config.target);
 	setPageTitle(config.name);
 	return mountRoot(container, createElement(ThemeProvider, { value: config.theme }, createElement(config.component)));
@@ -1136,7 +1403,7 @@ const PENDING = { pending: true };
 * @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}.
+* @param options - See {@link UseDownloadUrlOptions}.
 * @returns See {@link UseDownloadUrlResult}.
 *
 * @example
@@ -1160,9 +1427,9 @@ const PENDING = { pending: true };
 *
 * @public
 */
-function useDownloadUrl(uploadId, opts = {}) {
+function useDownloadUrl(uploadId, options = {}) {
 	const [state, setState] = useState(IDLE);
-	const getClient = useWorkflowApiRef(opts.api);
+	const getClient = useWorkflowApiRef(options.api);
 	useEffect(() => {
 		if (uploadId === void 0) {
 			setState(IDLE);
@@ -1286,13 +1553,7 @@ function useDownloadUrl(uploadId, opts = {}) {
 const PREFIX$1 = "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$1;
-	try {
-		return `${PREFIX$1}${new URL("./", href).href}`;
-	} catch {
-		return `${PREFIX$1}${href}`;
-	}
+	return urlSlot(PREFIX$1, "./");
 }
 /**
 * Read the key this page already has, or mint and remember one.
@@ -1302,17 +1563,12 @@ function slotFor() {
 * 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();
-	}
+	const slot = slotFor();
+	const stored = storageGet(storage, slot);
+	if (stored !== void 0) return stored;
+	const minted = crypto.randomUUID();
+	storageSet(storage, slot, minted);
+	return minted;
 }
 /**
 * The key `useWorkflowSubmit` uses when the page named none.
@@ -1338,7 +1594,7 @@ function mintRunKey(storage) {
 * @internal
 */
 function useDefaultRunKey(explicit) {
-	const [minted] = useState(() => explicit === void 0 ? mintRunKey("session") : crypto.randomUUID());
+	const [minted] = useState(() => explicit === void 0 ? mintRunKey("session") : "");
 	return explicit ?? minted;
 }
 /**
@@ -1422,11 +1678,11 @@ function useRunKey(options = {}) {
 */
 function useRecoveredRun(opts) {
 	const { workflow, key, enabled, getClient } = opts;
-	const [recovering, setRecovering] = useState(enabled && key !== void 0);
+	const [recovering, setRecovering] = useState(enabled);
 	const handlers = useRef(opts);
 	handlers.current = opts;
 	useEffect(() => {
-		if (!enabled || key === void 0) return;
+		if (!enabled) return;
 		let cancelled = false;
 		setRecovering(true);
 		getClient().find(workflow, key, { limit: 1 }).then((found) => {
@@ -1489,6 +1745,99 @@ function useRunControls(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.
+*
+* `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.
+*/
+/**
+* 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 current = useRef(void 0);
+	const begin = useCallback((token) => {
+		setStarting(true);
+		setStartError(void 0);
+		setRunId(void 0);
+		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(() => {
+		current.current?.gate.cancel();
+		current.current = void 0;
+		setRunId(void 0);
+		setStartError(void 0);
+		setUpload(void 0);
+	}, []);
+	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => current.current?.gate, []), setUpload);
+	return {
+		runId,
+		starting,
+		startError,
+		upload,
+		actions: useMemo(() => ({
+			setRunId,
+			setStartError,
+			setUpload,
+			begin,
+			end,
+			reset,
+			pauseUpload,
+			resumeUpload
+		}), [
+			begin,
+			end,
+			reset,
+			pauseUpload,
+			resumeUpload
+		])
+	};
+}
+//#endregion
 //#region src/_upload-recall.ts
 /**
 * Where an upload's ID survives a page RELOAD.
@@ -1554,9 +1903,9 @@ function fingerprint(file) {
 }
 /** 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 raw = globalThis.sessionStorage?.getItem(keyFor(scope));
-		if (raw === null || raw === void 0) return {};
 		const parsed = JSON.parse(raw);
 		return isRecord(parsed) ? parsed : {};
 	} catch {
@@ -1564,9 +1913,7 @@ function read(scope) {
 	}
 }
 function write(scope, entries) {
-	try {
-		globalThis.sessionStorage?.setItem(keyFor(scope), JSON.stringify(entries));
-	} catch {}
+	storageSet("session", keyFor(scope), JSON.stringify(entries));
 }
 /**
 * The id this file was last being stored under in this tab, if any.
@@ -1710,7 +2057,7 @@ function createUploadGate() {
 *
 * 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.
+* 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.
@@ -1914,43 +2261,39 @@ async function uploadFiles(api, input, report, parallel, session) {
 	return out;
 }
 //#endregion
-//#region src/_upload-pause.ts
+//#region src/_upload-report.ts
 /**
-* The two buttons a page puts over a live upload, bound to whichever gate the
-* submission is currently holding.
+* What the bar draws, as a comparable string.
 *
-* `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.
+* 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}`;
+}
 /**
-* Bind pause/resume to the live submission's gate.
+* Wrap an `UploadStatus` setter so redundant reports never reach React.
 *
-* @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
+* 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 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 coalesceUploadReports(set) {
+	let last;
+	return (status) => {
+		if (status === void 0) {
+			last = void 0;
+			set(void 0);
+			return;
+		}
+		const key = renderKey(status);
+		if (key === last) return;
+		last = key;
+		set(status);
 	};
 }
 //#endregion
@@ -2022,81 +2365,69 @@ function useUploadPause(getGate, setUpload) {
 *
 * @public
 */
-function useWorkflowSubmit(workflow, opts = {}) {
-	const { api, recover = true, wait, intervalMs, parallel } = opts;
-	const key = useDefaultRunKey(opts.key);
-	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);
+function useWorkflowSubmit(workflow, options = {}) {
+	const { api, recover = true, wait, intervalMs, parallel } = options;
+	const key = useDefaultRunKey(options.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) => {
-			setRunId((current) => current ?? found);
+			actions.setRunId((current) => current ?? found);
 		},
-		onError: setStartError
+		onError: actions.setStartError
 	});
 	const submit = useCallback(async (input) => {
 		const client = getClient();
-		setStarting(true);
-		setStartError(void 0);
-		setRunId(void 0);
-		session.current?.gate.cancel();
 		const current = createUploadSession(workflow);
-		session.current = current;
+		setStartedHere(true);
+		actions.begin(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, {
+			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) setStartError(errorMessage(err));
+			if (!current.gate.cancelled) actions.setStartError(errorMessage(err));
 		} finally {
-			if (session.current === current) {
-				session.current = void 0;
-				setStarting(false);
-				setUpload(void 0);
-			}
+			actions.end(current);
 		}
 	}, [
 		workflow,
 		key,
 		wait,
 		parallel,
-		getClient
+		getClient,
+		actions
 	]);
-	const reset = useCallback(() => {
-		session.current?.gate.cancel();
-		session.current = void 0;
-		setRunId(void 0);
-		setStartError(void 0);
-		setUpload(void 0);
-	}, []);
-	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => session.current?.gate, []), setUpload);
 	return {
 		submit,
 		submitForm: submit,
-		reset,
+		reset: useCallback(() => {
+			setStartedHere(false);
+			actions.reset();
+		}, [actions]),
 		wake,
 		cancel,
-		pauseUpload,
-		resumeUpload,
+		pauseUpload: actions.pauseUpload,
+		resumeUpload: actions.resumeUpload,
 		run: tracked.run,
-		pending: recovering || starting || tracked.polling,
-		upload,
-		error: startError ?? tracked.error
+		startedHere,
+		pending: recovering || state.starting || tracked.polling,
+		upload: state.upload,
+		error: state.startError ?? tracked.error
 	};
 }
 //#endregion
@@ -2141,8 +2472,8 @@ function useWorkflowSubmit(workflow, opts = {}) {
 *
 * @public
 */
-function useWorkflowRuns(workflow, opts = {}) {
-	const { api, limit, key, skip = false } = opts;
+function useWorkflowRuns(workflow, options = {}) {
+	const { api, limit, key, skip = false } = options;
 	const [runs, setRuns] = useState([]);
 	const [loading, setLoading] = useState(!skip && workflow !== void 0);
 	const [error, setError] = useState(void 0);
@@ -2226,7 +2557,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.
 *
@@ -2302,27 +2633,23 @@ function useWorkflowRuns(workflow, opts = {}) {
 *
 * @public
 */
-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);
+function useWorkflowStream(workflow, options = {}) {
+	const { api, key, intervalMs, parallel } = options;
+	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();
@@ -2335,7 +2662,7 @@ function useWorkflowStream(workflow, opts = {}) {
 			});
 			started = begun.runId;
 			const chosen = begun.file;
-			setRunId(started);
+			actions.setRunId(started);
 			if (!chosen) return;
 			await streamFile({
 				client,
@@ -2343,45 +2670,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
 	};
 }
 /**
@@ -2392,8 +2712,8 @@ function useWorkflowStream(workflow, opts = {}) {
 * listing in state would make a submit before it landed a race, and the failure
 * mode of that race is a `File` reaching a run input.
 */
-async function beginRun(opts) {
-	const { client, workflow, input, id } = opts;
+async function beginRun(options) {
+	const { client, workflow, input, id } = options;
 	const field = await uploadField(client, workflow);
 	const chosen = field === void 0 ? void 0 : fileAt(input, field);
 	const payload = chosen && field ? {
@@ -2402,7 +2722,7 @@ async function beginRun(opts) {
 	} : input;
 	assertSendable(workflow, payload, field);
 	return {
-		runId: await client.start(workflow, payload, omitUndefined({ key: opts.key })),
+		runId: await client.start(workflow, payload, omitUndefined({ key: options.key })),
 		file: chosen
 	};
 }
@@ -2414,8 +2734,8 @@ async function beginRun(opts) {
 * the id, start the run, then the bytes, then the wake — and the sending is the
 * one step of that list with a loop in it.
 */
-async function streamFile(opts) {
-	const { client, gate, id, file, parallel, report } = opts;
+async function streamFile(options) {
+	const { client, gate, id, file, parallel, report } = options;
 	await sendThroughGate(gate, async (resume) => {
 		await client.uploadStream(id, file, {
 			name: file.name,
@@ -2503,4 +2823,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, fieldKindFor, isTerminal, mountClient, mountPage, useAgentState, useConversation, useCopy, useDownloadUrl, useEvent, useFlash, useRunKey, useSession, useSessionActions, useSessionError, useSessionSelector, useSessionStatus, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };