@alexkroman1/aai-ui 13.2.0 → 14.0.0

package/dist/session-core-types.d.ts

@@ -149,7 +149,7 @@ export type SessionSnapshot = {
  *
  * @public
  */
-export type SessionCore = {
+export type BrowserSession = {
     /** Return the current immutable state snapshot. */
     getSnapshot(): SessionSnapshot;
     /** Subscribe to state changes. Returns an unsubscribe function. */
@@ -195,6 +195,30 @@ export type SessionCore = {
      * per-session tool state, greeting included.
      */
     end(): void;
+    /**
+     * End the current call and immediately begin a new one — `end()` then
+     * `start()`, which is what "New Conversation" means for an agent that keeps
+     * SESSION-SCOPED STATE.
+     *
+     * `reset()` is the one whose name suggests this and it is not the same
+     * thing: it clears the transcript and reconnects, but the reconnect carries
+     * the same `?sessionId=`, so every `sessionSlot` on the server survives —
+     * the game world, the incident board, the cart. A caller who asked to start
+     * over gets a blank transcript in front of the old state. This drops the
+     * session id, so the next connect mints a fresh one and the greeting plays
+     * again.
+     *
+     * Three templates had each written `session.end(); session.start();` with
+     * the same paragraph explaining why `reset()` was wrong; the six on the
+     * stock shell could not, because {@link Controls} called `reset()` for them.
+     *
+     * @example
+     * ```ts
+     * declare const session: import("@alexkroman1/aai-ui").Session;
+     * session.restart();
+     * ```
+     */
+    restart(): void;
     /** Alias for `disconnect` for use with `using`. */
     [Symbol.dispose](): void;
 };
@@ -247,3 +271,36 @@ export type ConnState = {
      *  buffered during mic-permission never finishes playing. */
     preInitDone: boolean;
 };
+/**
+ * The two liveness fields at rest.
+ *
+ * `running` and `recording` ride with almost every state transition and were
+ * spread as a pair of literals at seven sites across three modules — the same
+ * shape `session-core-state.ts` folded `state` and `error` out of, one field
+ * short. Naming it relates them: a transition that ends the call says so once,
+ * and a reader looking for "what stops the mic" finds one symbol rather than a
+ * grep.
+ *
+ * It is deliberately NOT the whole snapshot patch — a transition still supplies
+ * its own `agentState.apply(...)` projection beside this.
+ */
+export declare const STOPPED: {
+    readonly running: false;
+    readonly recording: false;
+};
+/**
+ * A turn boundary: end the current turn and settle whatever it was playing.
+ *
+ * The two calls are one fact and were written out at four sites — `cancel()`
+ * and `reset()` here, `reply.cancelled` and `session.reset` on the server side
+ * — where the pair is load-bearing in both halves. The bump stops a stale drain
+ * continuation from stamping `"listening"` over a state the session has since
+ * moved to; the flush settles the interrupted turn's `done()` so it cannot
+ * strand.
+ *
+ * Two further sites bump WITHOUT flushing (`cleanupAudio`, a committed user
+ * transcript) and stay spelled out, which is the point of naming this one: a
+ * bump on its own now reads as a deliberate choice rather than a forgotten
+ * flush.
+ */
+export declare function bargeIn(conn: ConnState): void;

package/dist/session-core.d.ts

@@ -1,4 +1,4 @@
-import type { SessionCore } from "./session-core-types.ts";
+import { type BrowserSession } from "./session-core-types.ts";
 import { type VoiceSessionOptions } from "./types.ts";
 /**
  * Create a framework-agnostic voice session core that connects to an AAI
@@ -7,24 +7,24 @@ import { type VoiceSessionOptions } from "./types.ts";
  * Uses a subscribe/getSnapshot pattern for state management, compatible with
  * React's `useSyncExternalStore` and other external store integrations.
  *
- * Most clients never call this: `client()` creates a core and installs it in
+ * Most clients never call this: `mountClient()` creates a core and installs it in
  * React context for the hooks. Reach for it directly when building a
  * non-React UI (or wiring the session into another framework's store).
  *
  * @example
  * ```ts
- * import { createSessionCore, type SessionSnapshot } from "@alexkroman1/aai-ui";
+ * import { createBrowserSession, type SessionSnapshot } from "@alexkroman1/aai-ui";
  *
  * declare function render(snapshot: SessionSnapshot): void;
  *
- * const session = createSessionCore({ platformUrl: "https://host/my-agent/" });
+ * const session = createBrowserSession({ platformUrl: "https://host/my-agent/" });
  * session.subscribe(() => render(session.getSnapshot()));
  * session.start();
  * ```
  *
  * @param options - Session configuration including the platform server URL.
- * @returns A {@link SessionCore} handle for controlling the session.
+ * @returns A {@link BrowserSession} handle for controlling the session.
  *
  * @public
  */
-export declare function createSessionCore(options: VoiceSessionOptions): SessionCore;
+export declare function createBrowserSession(options: VoiceSessionOptions): BrowserSession;

package/dist/session-core.js

@@ -1,2 +1,2 @@
-import { t as createSessionCore } from "./session-core-DxBYsfHA.js";
-export { createSessionCore };
+import { t as createBrowserSession } from "./session-core-gwePM95B.js";
+export { createBrowserSession };

package/dist/session-resume-store.d.ts

@@ -23,9 +23,9 @@
  * Keyed by the agent's own URL, so two agents served from one origin — which is
  * every deployed agent, at `/:slug/` — cannot inherit each other's session.
  *
- * Every access is guarded: storage throws outright in some contexts (Safari
- * private mode, storage blocked by policy), and a session that cannot be
- * remembered must degrade to today's behaviour rather than failing to start.
+ * Every access is guarded, and the guard lives in `_web-storage.ts`: a session
+ * that cannot be remembered must degrade to today's behaviour rather than
+ * failing to start.
  */
 /** The stored session id for this agent, or undefined. @internal */
 export declare function readStoredSessionId(platformUrl: string): string | undefined;

package/dist/{tool-call-block-tcPQAkcP.js → tool-call-block-C2t_5fpp.js}

@@ -1,12 +1,12 @@
 import { useTheme } from "./context.js";
-import { r as inkTint } from "./_colors-j8XMToi9.js";
-import { t as Eyebrow } from "./eyebrow-C6ZFuiz6.js";
-import { i as tryParseJSON, r as truncate } from "./_utils-B6498_bm.js";
-import { n as useToolConfig } from "./tool-config-context-DzAofqi_.js";
+import { a as inkTint } from "./_colors-CpZO-88A.js";
+import { t as Eyebrow } from "./eyebrow-UfmSz9yy.js";
+import { i as tryParseJSON, r as truncate } from "./_utils-DnQDM9Uy.js";
+import { n as useToolConfig } from "./tool-config-context-Es4YUzV2.js";
 import clsx from "clsx";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { memo, useMemo, useState } from "react";
-//#region components/tool-call-row.tsx
+//#region src/components/tool-call-row.tsx
 /** @jsxImportSource react */
 const VARIANT_CLASSES = {
 	default: {
@@ -116,13 +116,36 @@ function ToolCallRow({ title, detail, pending = false, icon, variant = "default"
 	});
 }
 //#endregion
-//#region components/tool-call-block.tsx
+//#region src/components/tool-call-block.tsx
 /** @jsxImportSource react */
 function formatResult(result) {
 	const parsed = tryParseJSON(result);
 	return parsed === result ? result : JSON.stringify(parsed, null, 2);
 }
 /**
+* The expanded result pane.
+*
+* Its own component so the parse-and-pretty-print happens only when the row is
+* actually OPEN. `ToolCallRow` renders `children` under `isOpen && canExpand`,
+* and a row starts closed — so computing this in the parent meant every row
+* paid `JSON.parse` + `JSON.stringify(_, null, 2)` over its whole result, and
+* then RETAINED the pretty string, for a panel nobody clicked. The burst case
+* is `history.restored`, which mounts up to `DEFAULT_MAX_HISTORY` rows in one
+* commit.
+*
+* Creating this element is free; React only runs the body once it is mounted.
+*/
+function ToolCallResult({ result }) {
+	const theme = useTheme();
+	const formatted = useMemo(() => formatResult(result), [result]);
+	if (!formatted) return null;
+	return /* @__PURE__ */ jsx("pre", {
+		className: "font-aai-mono text-xs px-3.5 py-3 m-0 whitespace-pre-wrap wrap-break-word",
+		style: { color: inkTint(theme.text, theme.surface, 75) },
+		children: formatted
+	});
+}
+/**
 * Renders a tool invocation as the design system's console row (see
 * `ToolCallRow`): a small outlined "TOOL" chip (or the tool's configured
 * icon), the tool name in mono, a truncated args preview, and a rotating
@@ -151,7 +174,6 @@ const ToolCallBlock = memo(function ToolCallBlock({ toolCall, className }) {
 	const title = config?.label || toolCall.name;
 	const icon = config?.icon;
 	const canExpand = !isPending && Boolean(toolCall.result);
-	const formatted = useMemo(() => toolCall.result ? formatResult(toolCall.result) : "", [toolCall.result]);
 	const subtitle = useMemo(() => {
 		const args = toolCall.args;
 		if (toolCall.name === "run_code" && args.code) return truncate(String(args.code).split("\n")[0] ?? "");
@@ -175,11 +197,7 @@ const ToolCallBlock = memo(function ToolCallBlock({ toolCall, className }) {
 				borderColor: theme.border
 			},
 			children: String(toolCall.args.code)
-		}), formatted && /* @__PURE__ */ jsx("pre", {
-			className: "font-aai-mono text-xs px-3.5 py-3 m-0 whitespace-pre-wrap wrap-break-word",
-			style: { color: inkTint(theme.text, theme.surface, 75) },
-			children: formatted
-		})] }) : void 0
+		}), toolCall.result && /* @__PURE__ */ jsx(ToolCallResult, { result: toolCall.result })] }) : void 0
 	});
 });
 //#endregion

package/dist/{tool-config-context-DzAofqi_.js → tool-config-context-Es4YUzV2.js}

@@ -1,7 +1,7 @@
 import { createContext, useContext } from "react";
-//#region components/tool-config-context.ts
+//#region src/components/tool-config-context.ts
 /**
-* Context for tool display configuration. Installed by `client()` from
+* Context for tool display configuration. Installed by `mountClient()` from
 * `ClientConfig.tools`; the built-in components read it via `useToolConfig`.
 *
 * @internal

package/dist/types.d.ts

@@ -23,8 +23,8 @@ export { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS,
  *
  * On `@alexkroman1/aai-ui/internal` rather than the root barrel, for the same
  * reason as the audio budgets above: it is a framework decision with no
- * `client()` field to set, and the root is the authoring surface. A custom
- * chrome that bypasses `client()` and opens its own microphone reaches it there
+ * `mountClient()` field to set, and the root is the authoring surface. A custom
+ * chrome that bypasses `mountClient()` and opens its own microphone reaches it there
  * alongside the providers it also needs.
  */
 export declare const VOICE_CAPTURE_CONSTRAINTS: MediaTrackConstraints;
@@ -135,11 +135,26 @@ export type SessionError = {
     readonly code: SessionErrorCode;
     /** A human-readable description of the error. */
     readonly message: string;
+    /**
+     * Whether the session is OVER.
+     *
+     * `false` means surface the message and keep the session interactive — a
+     * turn-level failure over a server that kept running. `true` means the call
+     * is dead and the microphone has been released.
+     *
+     * Required rather than optional, because the wire always carries it
+     * (`error.reported` declares `fatal: z.boolean()`) and a client that cannot
+     * tell the two apart has to guess which banner to render. It was dropped one
+     * line before reaching here for long enough that this type's own doc, and
+     * the reference page generated from it, described a field that did not
+     * exist.
+     */
+    readonly fatal: boolean;
 };
 /**
  * Options for creating a voice session — the shared field set accepted by
- * both `client()` and `createSessionCore`. The one difference: `client()`
- * defaults `platformUrl` from `location.href`, while `createSessionCore`
+ * both `mountClient()` and `createBrowserSession`. The one difference: `mountClient()`
+ * defaults `platformUrl` from `location.href`, while `createBrowserSession`
  * requires it.
  *
  * @public

package/dist/types.js

@@ -1,5 +1,5 @@
 import { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PACER_BURST_MS, PIPELINE_PLAYBACK_GRACE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_FILL_MS, PLAYBACK_PROGRESS_INTERVAL_MS } from "@alexkroman1/aai/internal";
-//#region types.ts
+//#region src/types.ts
 /**
 * `getUserMedia` audio constraints for every capture path in this package.
 *
@@ -22,8 +22,8 @@ import { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS,
 *
 * On `@alexkroman1/aai-ui/internal` rather than the root barrel, for the same
 * reason as the audio budgets above: it is a framework decision with no
-* `client()` field to set, and the root is the authoring surface. A custom
-* chrome that bypasses `client()` and opens its own microphone reaches it there
+* `mountClient()` field to set, and the root is the authoring surface. A custom
+* chrome that bypasses `mountClient()` and opens its own microphone reaches it there
 * alongside the providers it also needs.
 */
 const VOICE_CAPTURE_CONSTRAINTS = {

package/dist/{url-chips-YqhCjWfQ.js → url-chips-BxhzZgk2.js}

@@ -1,10 +1,10 @@
 import { useSessionSelector, useTheme } from "./context.js";
-import { r as inkTint } from "./_colors-j8XMToi9.js";
-import { t as pageBaseUrl } from "./_utils-B6498_bm.js";
+import { a as inkTint, i as focusRingStyle, n as FOCUS_RING } from "./_colors-CpZO-88A.js";
+import { t as pageBaseUrl } from "./_utils-DnQDM9Uy.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
-//#region components/url-chips.tsx
+//#region src/components/url-chips.tsx
 /** @jsxImportSource react */
 /** How long the "Copied" confirmation replaces the label after a click. */
 const COPIED_FEEDBACK_MS = 1500;
@@ -32,12 +32,12 @@ function UrlChip({ label, url, hint, testId, className }) {
 		type: "button",
 		onClick: copy,
 		title: `${hint} (click to copy)\n${url}`,
-		className: clsx("flex items-center gap-1.5 min-w-0 appearance-none m-0 px-2 py-1 rounded-aai border cursor-pointer text-[11px] leading-none font-aai-mono", "outline-none focus-visible:[outline:2px_solid] focus-visible:[outline-offset:2px]", className),
+		className: clsx("flex items-center gap-1.5 min-w-0 appearance-none m-0 px-2 py-1 rounded-aai border cursor-pointer text-[11px] leading-none font-aai-mono", FOCUS_RING, className),
 		style: {
 			background: inkTint(theme.text, theme.surface, 3),
 			borderColor: theme.border,
 			color: inkTint(theme.text, theme.surface, 65),
-			outlineColor: theme.primary
+			...focusRingStyle(theme.primary)
 		},
 		"data-testid": testId,
 		children: [/* @__PURE__ */ jsx("span", {

package/dist/use-conversation.d.ts

@@ -88,7 +88,7 @@ export type UseConversationResult = {
  * Subscribe to the conversation: the interleaved exchange, the streaming
  * utterance, the live transcript and the thinking rule — with no markup.
  *
- * Must be used inside the provider `client()` installs.
+ * Must be used inside the provider `mountClient()` installs.
  *
  * @example A custom bubble, keeping every rule `<MessageList>` knows
  * ```tsx

package/dist/use-run-key.d.ts

@@ -1,13 +1,22 @@
 /**
  * The handle a page keeps on the runs it started, across a reload.
  *
- * `useWorkflowSubmit({ key, recover: true })` is what makes a run survivable —
- * the run id is that hook's own state, so a refresh loses it while the run
- * carries on — and the `key` is deliberately the caller's to choose, because it
- * is a lookup CAPABILITY: there is no per-user filtering behind `find`, so the
- * key IS the scoping mechanism. Choosing one is easy to get wrong in three
- * separate ways, and six shipped templates had each written the same twenty
- * lines to get it right. This is those lines.
+ * `useWorkflowSubmit` is what makes a run survivable — the run id is that
+ * hook's own state, so a refresh loses it while the run carries on — and the
+ * `key` is what it looks the run up BY, because it is a lookup CAPABILITY:
+ * there is no per-user filtering behind `find`, so the key IS the scoping
+ * mechanism. Choosing one is easy to get wrong in three separate ways, and six
+ * shipped templates had each written the same twenty lines to get it right.
+ * This is those lines.
+ *
+ * **`useWorkflowSubmit` now mints one for itself** ({@link useDefaultRunKey}),
+ * so a page resumes its own run across a reload with nothing written at the
+ * call site — six of six page templates passed `useRunKey()` and
+ * `recover: true`, which is a default in the wrong place. The hook stays
+ * PUBLIC for the page that wants to choose: an app with accounts passes the
+ * ACCOUNT's own id instead, and a run then follows the person to a new device,
+ * which is a promise only a login can keep; a page whose run outlives the tab
+ * passes `useRunKey({ storage: "local" })`.
  *
  * ## Three properties, and the rejected alternatives are why each one matters
  *
@@ -42,7 +51,9 @@
  * coming back on Friday to press Stop is the ordinary case rather than an edge
  * one, and a tab-scoped key would answer that with an empty form beside a run
  * still posting somewhere. It is as far as a key can go without a login, and no
- * further. `podcast-digest` is that template; the other five ship the default.
+ * further. `podcast-digest` is that template, and the reason this hook is still
+ * called by name anywhere; the other five take the tab-scoped default the
+ * submit hook mints for them.
  *
  * ## Anything ELSE a page stores back must be VALIDATED on read
  *
@@ -77,8 +88,31 @@
  * failing to render.
  */
 /**
- * A lookup key for `useWorkflowSubmit({ key, recover: true })`, stable across
- * reloads.
+ * The key `useWorkflowSubmit` uses when the page named none.
+ *
+ * Two things it does that a plain `useRunKey()` at the call site cannot, and
+ * both are about a page that DID name one:
+ *
+ * - **It mints nothing when the caller has a key.** Minting writes to storage,
+ *   so an unconditional `useRunKey()` inside the hook would leave a slot behind
+ *   on every page that passes an account id and never reads it back.
+ * - **It stays reactive to the caller's key.** A key that arrives late — an
+ *   account id resolved after a login — must reach the lookup, which re-asks on
+ *   a changed key by design; freezing it into `useState` would pin the page to
+ *   whatever it held on its first render.
+ *
+ * The minted half is still frozen for the component's life, which is what
+ * `useRunKey` freezes it for: a fresh key per render would record every run
+ * under a name the next load cannot produce.
+ *
+ * @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.
+ *
+ * @internal
+ */
+export declare function useDefaultRunKey(explicit: string | undefined): string;
+/**
+ * A lookup key for `useWorkflowSubmit({ key })`, stable across reloads.
  *
  * @param options - See the module doc for the whole argument. The storage kind
  *   is read once, when the key is minted: a value that changed afterwards would

package/dist/{use-user-transcript-C14qWFu2.js → use-user-transcript-uyHhzy4d.js}

@@ -1,5 +1,6 @@
 import { useSessionSelector } from "./context.js";
-//#region use-user-transcript.ts
+import { useMemo } from "react";
+//#region src/use-user-transcript.ts
 /**
 * `useUserTranscript` — what the caller is saying RIGHT NOW, read correctly.
 *
@@ -57,11 +58,11 @@ const TRANSCRIBING_PLACEHOLDER = "…";
 */
 function useUserTranscript() {
 	const partial = useSessionSelector((snapshot) => snapshot.userTranscript);
-	return {
+	return useMemo(() => ({
 		speaking: partial !== null,
 		text: displayText(partial),
 		partial
-	};
+	}), [partial]);
 }
 /** The three cases, spelled out: silent, detected-but-wordless, and words. */
 function displayText(partial) {

package/dist/use-workflow-form.d.ts

@@ -1,11 +1,10 @@
 /**
- * The two hooks a FORM needs, as against the one a status view does.
+ * The hook a FORM needs, as against the one a status view does.
  *
  * `useWorkflowRun` (`workflow-client.ts`) watches a run you already have.
- * These two are what comes before it: `useWorkflows` reads the declared
- * workflows so `<WorkflowFields>` can render a form from a schema, and
- * `useWorkflowSubmit` starts a run and hands the id straight to
- * `useWorkflowRun`.
+ * 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`.
  *
  * ## `useWorkflowSubmit` — a form's two halves in one hook
  *
@@ -32,76 +31,10 @@
  * `wait` here when the page really does want one request, and the run is
  * followed from the same id either way.
  */
-import type { AnyWorkflowDef, UploadParallel, UploadProgress, WorkflowOutputOf, WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+import type { AnyWorkflowDef, UploadParallelOption, UploadProgress, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import type { FormValues } from "./components/form-types.ts";
 import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
 import type { SubmitInputOf } from "./workflow-def-types.ts";
-/** Options for {@link useWorkflows}. */
-export type UseWorkflowsOptions = {
-    /** The client to read the listing with. Defaults to one for the page's own agent. */
-    api?: WorkflowApi;
-    /**
-     * Skip the lookup entirely, reporting an empty listing that is not loading.
-     *
-     * For a caller that may or may not need the listing and cannot decide with a
-     * conditional hook — `<WorkflowFields>` handed a summary rather than a name is
-     * the one in this package. It reports `loading: false`, because a skipped
-     * lookup is finished rather than pending.
-     */
-    skip?: boolean;
-};
-/** What {@link useWorkflows} reports. */
-export type UseWorkflowsResult = {
-    /** The agent's declared workflows, each with the JSON Schema of its input. */
-    workflows: WorkflowSummary[];
-    /** True until the listing lands, so a form can hold its fields back. */
-    loading: boolean;
-    /** The lookup's failure. Set alongside an EMPTY list, which is why it exists. */
-    error: string | undefined;
-};
-/**
- * Read the agent's declared workflows.
- *
- * What `<WorkflowFields>` renders a form FROM: each summary carries the JSON
- * Schema of that workflow's input, converted server-side precisely so a browser
- * can read it.
- *
- * The failure is reported rather than swallowed, because the alternative is an
- * empty list — which renders as a form with no fields and reads as "this agent
- * declares no workflows" about an agent that was merely unreachable.
- *
- * @example
- * ```tsx
- * import { useWorkflows } from "@alexkroman1/aai-ui";
- *
- * // A page rendering its own chrome from the listing — a picker, say. A form
- * // for ONE workflow wants `<WorkflowFields workflow="name" />` instead,
- * // which does this lookup itself.
- * function WorkflowPicker({ onPick }: { onPick: (name: string) => void }) {
- *   const { workflows, loading, error } = useWorkflows();
- *   if (loading) return <p>Loading…</p>;
- *   if (error !== undefined) return <p role="alert">{error}</p>;
- *   return (
- *     <ul>
- *       {workflows.map((summary) => (
- *         <li key={summary.name}>
- *           <button type="button" onClick={() => onPick(summary.name)}>
- *             {summary.description ?? summary.name}
- *           </button>
- *         </li>
- *       ))}
- *     </ul>
- *   );
- * }
- * ```
- *
- * @param opts - See {@link UseWorkflowsOptions}.
- * @returns The listing, its loading flag and its failure — see
- * {@link UseWorkflowsResult}.
- *
- * @public
- */
-export declare function useWorkflows(opts?: UseWorkflowsOptions): UseWorkflowsResult;
 /**
  * What {@link WorkflowSubmission.upload} reports while the bytes are going.
  *
@@ -186,6 +119,38 @@ export type WorkflowSubmission<R = unknown, I = unknown> = {
     cancel: () => Promise<boolean>;
     /** The run, once started, followed to completion. */
     run: WorkflowRun<R> | undefined;
+    /**
+     * True from `submit()` on this mount until `reset()` — did THIS page start
+     * the run it is showing?
+     *
+     * A page needs it to say the right sentence and cannot derive it: a run
+     * ADOPTED by the mount-time lookup after a reload looks exactly like one this
+     * page started. Six templates kept a `useState(false)` next to this hook, set
+     * it in their `onSubmit` and mirrored it in their `onClear` — shadow state
+     * for a fact only this hook can know, since it is the thing that decides
+     * between `submit()` and the recovery lookup. One of the six grew a fourth
+     * branch and had to move the whole note into its own module with its own
+     * spec, which is what a seam missing one layer down looks like.
+     *
+     * The RAW fact rather than a derived "recovered", deliberately: with `run`
+     * these are three states, not two, and the third is the one a page most needs
+     * to explain. `startedHere` is "you pressed the button"; `!startedHere &&
+     * !run` is the mount-time lookup still going; `!startedHere && run` is a run
+     * this browser started earlier, now in front of somebody who did not press
+     * anything. A boolean meaning only the last of those cannot express the
+     * middle one.
+     *
+     * @example
+     * ```ts
+     * declare const submission: import("@alexkroman1/aai-ui").WorkflowSubmission;
+     * const note = submission.startedHere
+     *   ? "You can close this tab or reload it — this page will find the run again."
+     *   : submission.run === undefined
+     *     ? "Looking for a run this tab started earlier…"
+     *     : "Still working on the run this tab started earlier. Reloading is safe.";
+     * ```
+     */
+    startedHere: boolean;
     /**
      * True from `submit()` until the run reaches a terminal status.
      *
@@ -229,29 +194,37 @@ export type WorkflowSubmission<R = unknown, I = unknown> = {
 export type UseWorkflowSubmitOptions = {
     /** The client to start runs with. Defaults to one for the page's own agent. */
     api?: WorkflowApi;
-    /** Correlation key recorded with the run, for finding it again without the id. */
+    /**
+     * Correlation key recorded with the run, for finding it again without the id.
+     *
+     * **Defaulted**, to an opaque per-page key in `sessionStorage` that the next
+     * load produces again — `useRunKey()`'s, minted by the hook. Pass one to
+     * scope runs to something the page knows better: an ACCOUNT's own id, which
+     * is what makes a run follow the person to a new device, or
+     * `useRunKey({ storage: "local" })` for a run that outlives the tab by
+     * design. The key is a lookup CAPABILITY (there is no per-user filtering
+     * behind `find`), it must fit the route's 256-character bound, and anything
+     * derived from a person's own input both collides and carries what they
+     * typed — `use-run-key.ts` argues every alternative.
+     */
     key?: string;
     /**
      * On mount, adopt the newest run this `key` already has.
      *
-     * **This is what makes a reload survivable.** The run id is this hook's own
-     * state, so a refresh loses it while the run carries on — and a page that
-     * cannot name a run cannot show it, cancel it or wake it. With a `key` and
-     * this flag the hook asks `find(workflow, key)` once as it mounts and follows
-     * whatever comes back, so the answer, the progress and the controls are all
-     * there again.
-     *
-     * Inert without a `key`, because the key IS the lookup. Opt-in because a
-     * `key` on its own means only "record this with the run", which is what a
-     * page passing an account id may well want; adopting a run is a decision
-     * about the page.
+     * **This is what makes a reload survivable, and it is ON.** The run id is
+     * this hook's own state, so a refresh loses it while the run carries on — and
+     * a page that cannot name a run cannot show it, cancel it or wake it. The
+     * hook asks `find(workflow, key)` once as it mounts and follows whatever
+     * comes back, so the answer, the progress and the controls are all there
+     * again.
      *
-     * The key has to be one the next load can produce, and choosing it is the
-     * caller's: it is a lookup CAPABILITY (there is no per-user filtering behind
-     * `find`), it must fit the route's 256-character bound, and anything derived
-     * from a person's own input both collides and carries what they typed.
-     * `useRunKey()` is that key, and its module argues every alternative; a page
-     * with accounts passes the account's own id instead.
+     * It used to be opt-in, on the argument that a `key` alone means only "record
+     * this with the run" — true of `ctx.workflows.start({ key })`, where there is
+     * no page to put a run back on, and not of a form: six of six page templates
+     * passed `useRunKey()` and `recover: true` together, which is a default in
+     * the wrong place. `false` is the opt-out, and what it buys is a form that
+     * always opens empty — no lookup on mount, and a live run reachable only by
+     * an id the page has already lost.
      */
     recover?: boolean;
     /**
@@ -273,7 +246,7 @@ export type UseWorkflowSubmitOptions = {
      * the default costs nothing where it would not have paid. See
      * `UploadOptions.parallel`.
      */
-    parallel?: UploadParallel;
+    parallel?: UploadParallelOption;
 };
 /**
  * Start a workflow from a form, and follow the run it creates.