@alexkroman1/aai-ui 16.1.0 → 18.0.0

package/dist/index.js

@@ -1,24 +1,24 @@
-import { a as AGENT_STATE_LABELS, i as SessionErrorBanner, n as ConsoleShell, r as SessionStateDot, t as ChatView } from "./chat-view-DsylXJsw.js";
-import { n as fetchClientConfig } from "./client-config-DJQHnYjm.js";
-import { a as AutoScroll, i as useConversation, n as Markdown, r as ConversationView, t as MessageList } from "./message-list-BLyPRS1Q.js";
-import { ThemeProvider, useSession, useSessionActions, useSessionError, useSessionSelector, useSessionStatus, useTheme } from "./context.js";
+import { a as AGENT_STATE_LABELS, i as SessionErrorBanner, n as ConsoleShell, r as SessionStateDot, t as ChatView } from "./chat-view-P12pHKQU.js";
+import { n as setPageTitle } from "./_utils-DnQDM9Uy.js";
+import { n as fetchClientConfig } from "./client-config-CFhkMkmv.js";
+import { a as AutoScroll, i as useConversation, n as Markdown, r as ConversationView, t as MessageList } from "./message-list-CJX560b5.js";
+import { ThemeProvider, useSession, useSessionActions, useSessionCore, 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 setPageTitle } from "./_utils-DnQDM9Uy.js";
-import { a as useFlash, i as useCopy } from "./url-chips-D62RTz7v.js";
+import { a as useFlash, i as useCopy } from "./url-chips-0n35fPJY.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-C2t_5fpp.js";
+import { n as ToolCallRow } from "./tool-call-block-4gXoL_eP.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-CNahvlgL.js";
-import { i as urlSlot, n as storageGet, r as storageSet, t as createBrowserSession } from "./session-core-gwePM95B.js";
+import { a as useWorkflowProgress, c as isTerminal, o as useWorkflowApiRef, r as useWorkflowRun, s as createWorkflowApi } from "./use-workflow-run-ZqJWJn2-.js";
+import { i as urlSlot, n as storageGet, r as storageSet, t as createBrowserSession } from "./session-core-TOdm_Con.js";
 import { mountClient, mountRoot, resolveContainer } from "./define-client.js";
 import { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.js";
+import { errorMessage } from "@alexkroman1/aai";
 import clsx from "clsx";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Fragment as Fragment$1, 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/components/audio-result.tsx
@@ -893,7 +893,7 @@ function SubmitButton({ children, pending = false, pendingLabel = "Working…",
 * unusual for even that component's render slot takes the hook alone.
 */
 const selectStarted = (snapshot) => snapshot.started;
-const selectRunning = (snapshot) => snapshot.running;
+const selectRunning$1 = (snapshot) => snapshot.running;
 /**
 * The state and the actions a Start / Pause–Resume / New conversation / End row
 * renders from, on two one-field subscriptions.
@@ -923,7 +923,7 @@ const selectRunning = (snapshot) => snapshot.running;
 function useSessionControls() {
 	const { start, toggle, restart, end } = useSessionActions();
 	const started = useSessionSelector(selectStarted);
-	const running = useSessionSelector(selectRunning);
+	const running = useSessionSelector(selectRunning$1);
 	return useMemo(() => ({
 		started,
 		running,
@@ -1747,447 +1747,142 @@ function WorkflowRunPanel({ run, statusLabels, onClear, api, live, children, cla
 	});
 }
 //#endregion
-//#region src/page.tsx
-/** @jsxImportSource react */
+//#region src/_recover-run.ts
 /**
-* `mountPage()` — mount a WORKFLOW APP's UI: React, theme, no session.
-*
-* The twin of `mountClient()` for an agent whose front door is a form rather than a
-* microphone (`workflowApp()`). It is a separate entry rather than
-* an option on `mountClient()` because of what `mountClient()` unavoidably does: it
-* constructs a `BrowserSession`, which owns a WebSocket URL provider, an audio
-* graph, and a microphone request. A flag would have to make all of that
-* conditional, and every session hook would then have to answer "what does this
-* mean with no session?" — so the honest split is two mounts. A page that wants
-* voice uses `mountClient()`; a page that wants neither audio nor a socket uses this.
+* Finding a run again when the page has lost its id.
 *
-* Authoring is otherwise identical — the file is still `client.tsx`, still
-* React, still Tailwind, still the same theme tokens — so a workflow app reads
-* like every other agent. What it reaches for instead of `useSession()` is
-* `createWorkflowApi()` / `useWorkflowRun()`.
-*/
-/**
-* Mount a page for an agent whose work happens in workflows.
+* A run is durable and a page is not — which `useWorkflowRun`'s doc says, and
+* which was only half true of the hooks above it: the run id lived in plain
+* `useState`, so a refresh (or a same-tab navigation, or a crashed tab) left a
+* live run with nothing anywhere able to name it. The run really did continue;
+* the person really could not get back to it.
 *
-* There is deliberately no session, no microphone, and no socket: the component
-* talks to the agent over the workflow HTTP API
-* (`createWorkflowApi`/`useWorkflowRun`), which is durable and outlives the tab.
+* `StartOptions.key` is the handle that survives that, and it always was — a
+* caller's own name for a run, indexed by the agent, read back with
+* `find(workflow, key)`. What was missing is the two lines that ASK. This is
+* them, plus the four decisions they turn out to carry.
 *
-* @example
-* ```tsx
-* import { createWorkflowApi, mountPage, useWorkflowRun } from "@alexkroman1/aai-ui";
-* import { useState } from "react";
+* ## It is a MOUNT-time act, not "whenever there is no run"
 *
-* // Hoisted: a client built in render is a new object every render.
-* const api = createWorkflowApi();
+* The tempting spelling is "if we hold no run id, look one up", and it breaks
+* `reset()`: a form put back to its initial state holds no run id, so the next
+* pass would re-adopt the very run the person had just dismissed — a Clear
+* button that clears nothing. So the lookup runs once per mount (and again only
+* if the KEY changes, which is a different person's run), and every later
+* absence of a run id is taken at face value.
 *
-* function App() {
-*   const [runId, setRunId] = useState<string>();
-*   const { run } = useWorkflowRun(runId, { api });
-*   return (
-*     <button
-*       type="button"
-*       onClick={() => void api.start("digest", { topic: "ai" }).then(setRunId)}
-*     >
-*       {run ? run.status : "Start"}
-*     </button>
-*   );
-* }
+* ## The lookup NEVER wins a race against a submit
 *
-* mountPage({ name: "Digest", component: App });
-* ```
+* A person who reloads and immediately submits has started the run they want,
+* and an answer that was already in flight names an older one. The caller
+* therefore adopts through `current ?? found`: the recovered id fills an empty
+* slot and never replaces a full one.
 *
-* @throws If the target element is not found in the DOM.
+* ## A failed lookup is REPORTED
 *
-* @public
-*/
-function mountPage(config) {
-	const container = resolveContainer(config.target);
-	setPageTitle(config.name);
-	return mountRoot(container, createElement(ThemeProvider, { value: config.theme }, createElement(config.component)));
-}
-//#endregion
-//#region src/use-download-url.ts
-/**
-* `useDownloadUrl` — an upload id a run produced, as something `<audio>`,
-* `<img>` or `<a download>` will accept.
+* The alternative is a page that quietly shows an empty form to somebody whose
+* run is live, who then starts a second one — the duplicated work the key
+* exists to prevent, and on a workflow app that is real money. A person who has
+* never run anything pays a banner they can ignore. Same trade as
+* `useWorkflows`, for the same reason: an empty answer here is a confident
+* false statement.
 *
-* `api.download(id)` resolves a `Blob`, and it has to: the byte route takes the
-* same bearer every workflow route does, and neither `<audio src>` nor
-* `<a href>` can send one. So every page that plays back what a run WROTE ends
-* up at the same four lines — `download` → `createObjectURL` → state — and the
-* two that are really the point are the two the four lines are wrapped in:
+* ## It is ON by default, and it used to be opt-in
 *
-* - **`URL.revokeObjectURL` on cleanup.** An object URL pins its blob for the
-*   life of the DOCUMENT. Miss it and every completed run's audio stays resident
-*   until the tab closes, which on a page people run all day is a leak measured
-*   in the size of the files.
-* - **A `cancelled` flag.** A second run settling while the first download is
-*   still in flight otherwise sets state from the stale one, and the page plays
-*   the previous run's audio under the current run's transcript — a wrong answer
-*   that looks like a right one.
+* The argument for opt-in was that a `key` on its own means only "record this
+* with the run" — which is what a voice agent's `ctx.workflows.start({ key })`
+* means, there being no page to put a run back on. A FORM is the other case: it
+* is the page, and losing the run is the thing it cannot recover from. Six of
+* six page templates wrote `useRunKey()` and `recover: true` together, which is
+* the same shape `session-resume-store.ts` names on the voice side — a default
+* in the wrong place — so `useWorkflowSubmit` now mints the key and asks.
 *
-* Two templates had written this hook, identically, doc paragraph included, and
-* `aai-ui` exported no download helper at all. Both also faked `pending` by
-* checking `url === undefined && error === undefined`, which reads "idle" and
-* "downloading" as the same thing — so this reports it.
+* `enabled` remains, because `recover: false` remains: a page whose form must
+* always open empty says so, and then nothing here runs.
 */
-/** No id: nothing pending, nothing to show. A shared object so `setState` no-ops. */
-const IDLE = { pending: false };
-/** Bytes in flight. Shared for the same reason as {@link IDLE}. */
-const PENDING = { pending: true };
 /**
-* Read an upload's bytes and hand back a URL a DOM element can use.
-*
-* @param uploadId - The id a completed run reported, or `undefined` before one
-*   exists — which is what a page passes straight through while it waits, and
-*   reports as idle rather than pending.
-* @param options - See {@link UseDownloadUrlOptions}.
-* @returns See {@link UseDownloadUrlResult}.
-*
-* @example
-* ```tsx no-check
-* import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
-* import type { spokenSummary } from "./agent.ts";
+* Look up the newest run for a key, once, as the component mounts.
 *
-* function Playback() {
-*   const { run } = useWorkflowSubmit<typeof spokenSummary>("spokenSummary");
-*   const output = run?.status === "completed" ? run.output : undefined;
-*   const audio = useDownloadUrl(output?.audio);
-*   if (audio.pending) return <p>Fetching audio…</p>;
-*   if (audio.error !== undefined) return <p role="alert">{audio.error}</p>;
-*   return audio.url === undefined ? null : (
-*     <a href={audio.url} download="summary.mp3">
-*       Download
-*     </a>
-*   );
-* }
-* ```
+* @param opts - See {@link RecoverRunOptions}.
+* @returns Whether the lookup is still out. A caller folds it into its own
+*   `pending`, because a form offering Submit while a live run is arriving is a
+*   form inviting a second one.
 *
-* @public
+* @internal
 */
-function useDownloadUrl(uploadId, options = {}) {
-	const [state, setState] = useState(IDLE);
-	const getClient = useWorkflowApiRef(options.api);
+function useRecoveredRun(opts) {
+	const { workflow, key, enabled, getClient } = opts;
+	const [recovering, setRecovering] = useState(enabled);
+	const handlers = useRef(opts);
+	handlers.current = opts;
 	useEffect(() => {
-		if (uploadId === void 0) {
-			setState(IDLE);
-			return;
-		}
+		if (!enabled) return;
 		let cancelled = false;
-		let objectUrl;
-		setState(PENDING);
-		getClient().download(uploadId).then((blob) => {
+		setRecovering(true);
+		getClient().find(workflow, key, { limit: 1 }).then((found) => {
 			if (cancelled) return;
-			objectUrl = URL.createObjectURL(blob);
-			setState({
-				url: objectUrl,
-				pending: false
-			});
+			const newest = found[0];
+			if (newest !== void 0) handlers.current.onFound(newest.runId);
+			setRecovering(false);
 		}).catch((err) => {
-			if (!cancelled) setState({
-				error: errorMessage(err),
-				pending: false
-			});
+			if (cancelled) return;
+			handlers.current.onError(errorMessage(err));
+			setRecovering(false);
 		});
 		return () => {
 			cancelled = true;
-			if (objectUrl !== void 0) URL.revokeObjectURL(objectUrl);
 		};
-	}, [uploadId, getClient]);
-	return state;
+	}, [
+		enabled,
+		key,
+		workflow,
+		getClient
+	]);
+	return recovering;
 }
 //#endregion
-//#region src/use-run-key.ts
+//#region src/_run-controls.ts
 /**
-* The handle a page keeps on the runs it started, across a reload.
-*
-* `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" })`.
+* The two things a page does TO a run it started, bound to the run it has.
 *
-* ## Three properties, and the rejected alternatives are why each one matters
+* `useWorkflowSubmit` and `useWorkflowStream` both hold a run id and neither
+* handed it back, so a page that wanted "send it now" or "stop" had to hold an
+* `api` of its own purely to write `api.wake(runId)` — which is the whole reason
+* the two raw-primitive template pages keep a client at module scope. That is a
+* page carrying the transport to make up for a hook withholding its own state.
 *
-* - **Opaque** — `crypto.randomUUID()`, never derived from what was submitted.
-*   A key derived from the input collides the moment two people submit the same
-*   thing, and they then recover each other's runs; it also carries what they
-*   typed into a lookup token the platform deliberately stopped logging.
-* - **Short.** A `randomUUID` is 36 characters, well inside the 256 that
-*   `POST /workflows/runs` allows a key.
-* - **Minted once per load and written back for the next one**, which is the
-*   whole mechanism: the load that presses the button records the key with the
-*   run, and the load after it finds the run by producing the same key.
+* Both calls answer rather than fail when there is nothing to act on — `0`
+* sleeps ended, `false` this call did not end it — which is the SDK's own
+* contract for them (two tabs pressing Stop is ordinary), and it is what lets
+* the no-run case be the same answer rather than a special one a caller has to
+* branch on.
+*/
+/**
+* Bind `wake` and `cancel` to whatever run the hook is currently following.
 *
-* Storage rather than the page's own URL, for all of them. A `?key=` parameter
-* survives more (a new tab, a bookmark, a shared link) and that is the problem:
-* a URL is pasted into chats, copied into referrers and kept in history, and
-* what a leaked one buys is somebody else's work — reading it, and `cancel()` on
-* it. An app with accounts should pass the ACCOUNT's own id here instead, and
-* then a run follows the person to a new device, which is a promise only a login
-* can keep.
+* @param runId - The live run, or `undefined` before one exists.
+* @param getClient - The stable getter from `useWorkflowApiRef`.
+* @returns Two callbacks, stable while `runId` is.
 *
-* ## The storage is the caller's decision, and it is not a detail
-*
-* `"session"` (the default) dies with the tab, which covers exactly the
-* interruption most pages have — a reload, a same-tab navigation, a crashed tab
-* — and is the same lifetime as this package's other two stores, the session
-* resume id (`session-resume-store.ts`) and the upload recall
-* (`_upload-recall.ts`), so both halves of a reload make the same promise.
-*
-* `"local"` is for a run that outlives all of that BY DESIGN — one that sleeps
-* between digests and may live a month, where closing the browser on Tuesday and
-* coming back on Friday to press Stop is the ordinary case rather than an edge
-* one, and a tab-scoped key would answer that with an empty form beside a run
-* still posting somewhere. It is as far as a key can go without a login, and no
-* further. `podcast-digest-workflow` is that template, and the reason this hook is still
-* called by name anywhere; the other five take the tab-scoped default the
-* submit hook mints for them.
-*
-* ## Anything ELSE a page stores back must be VALIDATED on read
-*
-* This key needs no validation, and it is worth saying why, because it is the
-* exception: any string is a legal key, so a value from storage can only fail to
-* match a run. A page that remembers something more — which MODE submitted, say
-* — is remembering a value it will turn into a name, and storage hands back a
-* string some earlier version of that page wrote: a renamed mode, a hand-edited
-* value, a slot another app on the origin happens to share. Unchecked, that
-* starts a run called `undefined` and answers a 400 nobody typed. Check it
-* against the page's own list on the way out (`recalledMode` in
-* `transcription-workflow/recover.ts` is the worked example) — the recall is the
-* page's, the validation is not optional.
-*
-* ## The slot is keyed by the page's own URL
-*
-* Every deployed agent is served from one origin at `/:slug/`, so a fixed name
-* would have two agents scaffolded from the same template recover each other's
-* runs. The key is the page's own directory — resolved through `"./"`, which
-* drops the query and the hash, since a reload carrying `?foo` or `#bar` has to
-* find the same key. Same call `session-resume-store.ts` makes, for the same
-* reason.
-*
-* One key per PAGE is right even for a page driving several workflows: `find` is
-* scoped by workflow as well as by key, so three hooks sharing one key recover
-* three separate runs. `transcription-workflow` is that page.
-*
-* Every access is guarded. Storage THROWS outright in some contexts (Safari
-* private mode, an iframe blocked by policy) and is ABSENT in others (any
-* server-side render), and a page that cannot remember its key must degrade to
-* the behaviour it would have had anyway — one run per load — rather than
-* failing to render.
-*/
-/** Where a run key lives, namespaced like this package's two other stores. */
-const PREFIX$1 = "aai:run-key:";
-/** This page's own slot — see "The slot is keyed by the page's own URL". */
-function slotFor() {
-	return urlSlot(PREFIX$1, "./");
-}
-/**
-* Read the key this page already has, or mint and remember one.
-*
-* Not exported: a page that wants a key wants it for the life of a component,
-* which is what the hook is. Calling this per render would mint a fresh key and
-* hand `recover` one nothing was ever started under.
-*/
-function mintRunKey(storage) {
-	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.
-*
-* 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
-*/
-function useDefaultRunKey(explicit) {
-	const [minted] = useState(() => explicit === void 0 ? mintRunKey("session") : "");
-	return explicit ?? minted;
-}
-/**
-* 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
-*   be asking to move a key that has already been recorded with a run.
-* @returns The key to record runs under and to look them up by — the same one
-*   for the life of the component, and for the next load in the same tab (or the
-*   same browser, under `"local"`).
-*/
-function useRunKey(options = {}) {
-	const { storage = "session" } = options;
-	const [key] = useState(() => mintRunKey(storage));
-	return key;
-}
-//#endregion
-//#region src/_recover-run.ts
-/**
-* Finding a run again when the page has lost its id.
-*
-* A run is durable and a page is not — which `useWorkflowRun`'s doc says, and
-* which was only half true of the hooks above it: the run id lived in plain
-* `useState`, so a refresh (or a same-tab navigation, or a crashed tab) left a
-* live run with nothing anywhere able to name it. The run really did continue;
-* the person really could not get back to it.
-*
-* `StartOptions.key` is the handle that survives that, and it always was — a
-* caller's own name for a run, indexed by the agent, read back with
-* `find(workflow, key)`. What was missing is the two lines that ASK. This is
-* them, plus the four decisions they turn out to carry.
-*
-* ## It is a MOUNT-time act, not "whenever there is no run"
-*
-* The tempting spelling is "if we hold no run id, look one up", and it breaks
-* `reset()`: a form put back to its initial state holds no run id, so the next
-* pass would re-adopt the very run the person had just dismissed — a Clear
-* button that clears nothing. So the lookup runs once per mount (and again only
-* if the KEY changes, which is a different person's run), and every later
-* absence of a run id is taken at face value.
-*
-* ## The lookup NEVER wins a race against a submit
-*
-* A person who reloads and immediately submits has started the run they want,
-* and an answer that was already in flight names an older one. The caller
-* therefore adopts through `current ?? found`: the recovered id fills an empty
-* slot and never replaces a full one.
-*
-* ## A failed lookup is REPORTED
-*
-* The alternative is a page that quietly shows an empty form to somebody whose
-* run is live, who then starts a second one — the duplicated work the key
-* exists to prevent, and on a workflow app that is real money. A person who has
-* never run anything pays a banner they can ignore. Same trade as
-* `useWorkflows`, for the same reason: an empty answer here is a confident
-* false statement.
-*
-* ## It is ON by default, and it used to be opt-in
-*
-* The argument for opt-in was that a `key` on its own means only "record this
-* with the run" — which is what a voice agent's `ctx.workflows.start({ key })`
-* means, there being no page to put a run back on. A FORM is the other case: it
-* is the page, and losing the run is the thing it cannot recover from. Six of
-* six page templates wrote `useRunKey()` and `recover: true` together, which is
-* the same shape `session-resume-store.ts` names on the voice side — a default
-* in the wrong place — so `useWorkflowSubmit` now mints the key and asks.
-*
-* `enabled` remains, because `recover: false` remains: a page whose form must
-* always open empty says so, and then nothing here runs.
-*/
-/**
-* Look up the newest run for a key, once, as the component mounts.
-*
-* @param opts - See {@link RecoverRunOptions}.
-* @returns Whether the lookup is still out. A caller folds it into its own
-*   `pending`, because a form offering Submit while a live run is arriving is a
-*   form inviting a second one.
-*
-* @internal
-*/
-function useRecoveredRun(opts) {
-	const { workflow, key, enabled, getClient } = opts;
-	const [recovering, setRecovering] = useState(enabled);
-	const handlers = useRef(opts);
-	handlers.current = opts;
-	useEffect(() => {
-		if (!enabled) return;
-		let cancelled = false;
-		setRecovering(true);
-		getClient().find(workflow, key, { limit: 1 }).then((found) => {
-			if (cancelled) return;
-			const newest = found[0];
-			if (newest !== void 0) handlers.current.onFound(newest.runId);
-			setRecovering(false);
-		}).catch((err) => {
-			if (cancelled) return;
-			handlers.current.onError(errorMessage(err));
-			setRecovering(false);
-		});
-		return () => {
-			cancelled = true;
-		};
-	}, [
-		enabled,
-		key,
-		workflow,
-		getClient
-	]);
-	return recovering;
-}
-//#endregion
-//#region src/_run-controls.ts
-/**
-* The two things a page does TO a run it started, bound to the run it has.
-*
-* `useWorkflowSubmit` and `useWorkflowStream` both hold a run id and neither
-* handed it back, so a page that wanted "send it now" or "stop" had to hold an
-* `api` of its own purely to write `api.wake(runId)` — which is the whole reason
-* the two raw-primitive template pages keep a client at module scope. That is a
-* page carrying the transport to make up for a hook withholding its own state.
-*
-* Both calls answer rather than fail when there is nothing to act on — `0`
-* sleeps ended, `false` this call did not end it — which is the SDK's own
-* contract for them (two tabs pressing Stop is ordinary), and it is what lets
-* the no-run case be the same answer rather than a special one a caller has to
-* branch on.
-*/
-/**
-* Bind `wake` and `cancel` to whatever run the hook is currently following.
-*
-* @param runId - The live run, or `undefined` before one exists.
-* @param getClient - The stable getter from `useWorkflowApiRef`.
-* @returns Two callbacks, stable while `runId` is.
-*
-* @internal
-*/
-function useRunControls(runId, getClient) {
-	return {
-		wake: useCallback(async () => {
-			if (runId === void 0) return 0;
-			return await getClient().wake(runId);
-		}, [runId, getClient]),
-		cancel: useCallback(async () => {
-			if (runId === void 0) return false;
-			return await getClient().cancel(runId);
-		}, [runId, getClient])
-	};
-}
-//#endregion
-//#region src/_upload-pause.ts
-/**
-* The two buttons a page puts over a live upload, bound to whichever gate the
-* submission is currently holding.
+* @internal
+*/
+function useRunControls(runId, getClient) {
+	return {
+		wake: useCallback(async () => {
+			if (runId === void 0) return 0;
+			return await getClient().wake(runId);
+		}, [runId, getClient]),
+		cancel: useCallback(async () => {
+			if (runId === void 0) return false;
+			return await getClient().cancel(runId);
+		}, [runId, getClient])
+	};
+}
+//#endregion
+//#region src/_upload-pause.ts
+/**
+* The two buttons a page puts over a live upload, bound to whichever gate the
+* submission is currently holding.
 *
 * `useWorkflowSubmit` and `useWorkflowStream` both own an {@link UploadGate} and
 * both reported the pause the same way: park the gate, then fold `paused` into
@@ -2317,7 +2012,7 @@ function useSubmissionState() {
 * under a blocking policy, and an upload that cannot be REMEMBERED must degrade
 * to the upload we would have done anyway rather than failing to start.
 */
-const PREFIX = "aai:upload:";
+const PREFIX$1 = "aai:upload:";
 /**
 * How many ids one form keeps.
 *
@@ -2329,7 +2024,7 @@ const PREFIX = "aai:upload:";
 const MAX_REMEMBERED = 32;
 /** One form's slot in storage. */
 function keyFor(scope) {
-	return `${PREFIX}${scope}`;
+	return `${PREFIX$1}${scope}`;
 }
 /**
 * What names this file across a reload.
@@ -2736,16 +2431,170 @@ function coalesceUploadReports(set) {
 	};
 }
 //#endregion
-//#region src/use-workflow-form.ts
+//#region src/use-run-key.ts
 /**
-* The hook a FORM needs, as against the one a status view does.
-*
-* `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`.
-*
-* ## `useWorkflowSubmit` — a form's two halves in one hook
+* The handle a page keeps on the runs it started, across a reload.
+*
+* `useWorkflowSubmit` is what makes a run survivable — the run id is that
+* hook's own state, so a refresh loses it while the run carries on — and the
+* `key` is what it looks the run up BY, because it is a lookup CAPABILITY:
+* there is no per-user filtering behind `find`, so the key IS the scoping
+* mechanism. Choosing one is easy to get wrong in three separate ways, and six
+* shipped templates had each written the same twenty lines to get it right.
+* This is those lines.
+*
+* **`useWorkflowSubmit` now mints one for itself** ({@link useDefaultRunKey}),
+* so a page resumes its own run across a reload with nothing written at the
+* call site — six of six page templates passed `useRunKey()` and
+* `recover: true`, which is a default in the wrong place. The hook stays
+* PUBLIC for the page that wants to choose: an app with accounts passes the
+* ACCOUNT's own id instead, and a run then follows the person to a new device,
+* which is a promise only a login can keep; a page whose run outlives the tab
+* passes `useRunKey({ storage: "local" })`.
+*
+* ## Three properties, and the rejected alternatives are why each one matters
+*
+* - **Opaque** — `crypto.randomUUID()`, never derived from what was submitted.
+*   A key derived from the input collides the moment two people submit the same
+*   thing, and they then recover each other's runs; it also carries what they
+*   typed into a lookup token the platform deliberately stopped logging.
+* - **Short.** A `randomUUID` is 36 characters, well inside the 256 that
+*   `POST /workflows/runs` allows a key.
+* - **Minted once per load and written back for the next one**, which is the
+*   whole mechanism: the load that presses the button records the key with the
+*   run, and the load after it finds the run by producing the same key.
+*
+* Storage rather than the page's own URL, for all of them. A `?key=` parameter
+* survives more (a new tab, a bookmark, a shared link) and that is the problem:
+* a URL is pasted into chats, copied into referrers and kept in history, and
+* what a leaked one buys is somebody else's work — reading it, and `cancel()` on
+* it. An app with accounts should pass the ACCOUNT's own id here instead, and
+* then a run follows the person to a new device, which is a promise only a login
+* can keep.
+*
+* ## The storage is the caller's decision, and it is not a detail
+*
+* `"session"` (the default) dies with the tab, which covers exactly the
+* interruption most pages have — a reload, a same-tab navigation, a crashed tab
+* — and is the same lifetime as this package's other two stores, the session
+* resume id (`session-resume-store.ts`) and the upload recall
+* (`_upload-recall.ts`), so both halves of a reload make the same promise.
+*
+* `"local"` is for a run that outlives all of that BY DESIGN — one that sleeps
+* between digests and may live a month, where closing the browser on Tuesday and
+* coming back on Friday to press Stop is the ordinary case rather than an edge
+* one, and a tab-scoped key would answer that with an empty form beside a run
+* still posting somewhere. It is as far as a key can go without a login, and no
+* further. `podcast-digest-workflow` is that template, and the reason this hook is still
+* called by name anywhere; the other five take the tab-scoped default the
+* submit hook mints for them.
+*
+* ## Anything ELSE a page stores back must be VALIDATED on read
+*
+* This key needs no validation, and it is worth saying why, because it is the
+* exception: any string is a legal key, so a value from storage can only fail to
+* match a run. A page that remembers something more — which MODE submitted, say
+* — is remembering a value it will turn into a name, and storage hands back a
+* string some earlier version of that page wrote: a renamed mode, a hand-edited
+* value, a slot another app on the origin happens to share. Unchecked, that
+* starts a run called `undefined` and answers a 400 nobody typed. Check it
+* against the page's own list on the way out (`recalledMode` in
+* `transcription-workflow/recover.ts` is the worked example) — the recall is the
+* page's, the validation is not optional.
+*
+* ## The slot is keyed by the page's own URL
+*
+* Every deployed agent is served from one origin at `/:slug/`, so a fixed name
+* would have two agents scaffolded from the same template recover each other's
+* runs. The key is the page's own directory — resolved through `"./"`, which
+* drops the query and the hash, since a reload carrying `?foo` or `#bar` has to
+* find the same key. Same call `session-resume-store.ts` makes, for the same
+* reason.
+*
+* One key per PAGE is right even for a page driving several workflows: `find` is
+* scoped by workflow as well as by key, so three hooks sharing one key recover
+* three separate runs. `transcription-workflow` is that page.
+*
+* Every access is guarded. Storage THROWS outright in some contexts (Safari
+* private mode, an iframe blocked by policy) and is ABSENT in others (any
+* server-side render), and a page that cannot remember its key must degrade to
+* the behaviour it would have had anyway — one run per load — rather than
+* failing to render.
+*/
+/** Where a run key lives, namespaced like this package's two other stores. */
+const PREFIX = "aai:run-key:";
+/** This page's own slot — see "The slot is keyed by the page's own URL". */
+function slotFor() {
+	return urlSlot(PREFIX, "./");
+}
+/**
+* Read the key this page already has, or mint and remember one.
+*
+* Not exported: a page that wants a key wants it for the life of a component,
+* which is what the hook is. Calling this per render would mint a fresh key and
+* hand `recover` one nothing was ever started under.
+*/
+function mintRunKey(storage) {
+	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.
+*
+* 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
+*/
+function useDefaultRunKey(explicit) {
+	const [minted] = useState(() => explicit === void 0 ? mintRunKey("session") : "");
+	return explicit ?? minted;
+}
+/**
+* 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
+*   be asking to move a key that has already been recorded with a run.
+* @returns The key to record runs under and to look them up by — the same one
+*   for the life of the component, and for the next load in the same tab (or the
+*   same browser, under `"local"`).
+*/
+function useRunKey(options = {}) {
+	const { storage = "session" } = options;
+	const [key] = useState(() => mintRunKey(storage));
+	return key;
+}
+//#endregion
+//#region src/use-workflow-form.ts
+/**
+* The hook a FORM needs, as against the one a status view does.
+*
+* `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`.
+*
+* ## `useWorkflowSubmit` — a form's two halves in one hook
 *
 * A page that submits a workflow always needs the same four pieces of state:
 * the run id, whether a submit is in flight, whether the RUN is still going, and
@@ -2870,6 +2719,458 @@ function useWorkflowSubmit(workflow, options = {}) {
 	};
 }
 //#endregion
+//#region src/_page-shell.tsx
+/**
+* The agent's own `name` and `greeting`, once the lookup lands.
+*
+* **Not skipped when the mount named the agent**, which is where this differs
+* from `mountClient()`'s `DefaultRoot`: there the response's only consumer is
+* the name fallback, so an explicit `name` made the request pure waste. Here the
+* GREETING is rendered too, and no argument to `mountPage()` supplies it.
+*
+* Every failure path already degrades to "the agent declared nothing" —
+* `fetchClientConfig` owns that — so there is nothing to report and nothing to
+* catch.
+*/
+function useAgentConfig() {
+	const [config, setConfig] = useState();
+	useEffect(() => {
+		let cancelled = false;
+		fetchClientConfig().then((answer) => {
+			if (!cancelled) setConfig(answer);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+	return config;
+}
+/**
+* One workflow's form, its run, and what the run said.
+*
+* Its own component because `useWorkflowSubmit` is per WORKFLOW: the hook holds
+* the run id, so switching workflows has to start over rather than show one
+* workflow's run under another's form. The shell below mounts this with
+* `key={name}`, which is what makes that reset happen.
+*/
+function WorkflowRunner({ workflow }) {
+	const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit(workflow.name);
+	return /* @__PURE__ */ jsxs("section", {
+		className: "flex flex-col gap-4",
+		children: [
+			workflow.description === void 0 ? null : /* @__PURE__ */ jsx("p", {
+				className: "text-sm opacity-70",
+				children: workflow.description
+			}),
+			/* @__PURE__ */ jsxs(Form, {
+				onSubmit: (values) => submitForm(values),
+				error,
+				className: "flex flex-col gap-4",
+				children: [/* @__PURE__ */ jsx(WorkflowFields, { workflow }), /* @__PURE__ */ jsx(SubmitButton, {
+					pending,
+					children: "Start"
+				})]
+			}),
+			/* @__PURE__ */ jsx(UploadProgressBar, {
+				upload,
+				onPause: pauseUpload,
+				onResume: resumeUpload
+			}),
+			/* @__PURE__ */ jsx(WorkflowProgress, { runId: run?.runId }),
+			/* @__PURE__ */ jsx(WorkflowRunError, { run }),
+			run?.status === "completed" && /* @__PURE__ */ jsx("pre", {
+				className: "overflow-x-auto rounded-md border p-4 text-xs",
+				children: JSON.stringify(run.output, null, 2)
+			})
+		]
+	});
+}
+/**
+* The default page: the agent, its workflows, and one form.
+*
+* A picker appears only when there is more than one workflow — an agent with a
+* single workflow is the common case and a select with one option is chrome
+* about nothing.
+*/
+function DefaultPageShell({ name }) {
+	const config = useAgentConfig();
+	const { workflows, loading, error } = useWorkflows();
+	const [picked, setPicked] = useState();
+	const selected = workflows.find((entry) => entry.name === picked) ?? workflows[0];
+	return /* @__PURE__ */ jsxs("main", {
+		className: "mx-auto flex max-w-2xl flex-col gap-6 p-8",
+		children: [
+			/* @__PURE__ */ jsxs("header", {
+				className: "flex flex-col gap-1",
+				children: [/* @__PURE__ */ jsx("h1", {
+					className: "text-2xl font-medium",
+					children: name ?? config?.name ?? "Workflows"
+				}), config?.greeting === void 0 ? null : /* @__PURE__ */ jsx("p", {
+					className: "text-sm opacity-70",
+					children: config.greeting
+				})]
+			}),
+			error === void 0 ? null : /* @__PURE__ */ jsx("p", {
+				role: "alert",
+				className: "text-red-600",
+				children: error
+			}),
+			loading && /* @__PURE__ */ jsx("p", {
+				className: "text-sm opacity-70",
+				children: "Loading workflows…"
+			}),
+			!loading && error === void 0 && workflows.length === 0 && /* @__PURE__ */ jsx("p", {
+				className: "text-sm opacity-70",
+				children: "This agent declares no workflows."
+			}),
+			workflows.length > 1 && /* @__PURE__ */ jsxs("label", {
+				className: "flex flex-col gap-1 text-sm",
+				children: ["Workflow", /* @__PURE__ */ jsx("select", {
+					value: selected?.name ?? "",
+					onChange: (event) => setPicked(event.target.value),
+					className: "rounded-md border px-3 py-2",
+					children: workflows.map((entry) => /* @__PURE__ */ jsx("option", {
+						value: entry.name,
+						children: entry.name
+					}, entry.name))
+				})]
+			}),
+			selected && /* @__PURE__ */ jsx(WorkflowRunner, { workflow: selected }, selected.name)
+		]
+	});
+}
+//#endregion
+//#region src/page.tsx
+/** @jsxImportSource react */
+/**
+* `mountPage()` — mount a WORKFLOW APP's UI: React, theme, no session.
+*
+* The twin of `mountClient()` for an agent whose front door is a form rather than a
+* microphone (`workflowApp()`). It is a separate entry rather than
+* an option on `mountClient()` because of what `mountClient()` unavoidably does: it
+* constructs a `BrowserSession`, which owns a WebSocket URL provider, an audio
+* graph, and a microphone request. A flag would have to make all of that
+* conditional, and every session hook would then have to answer "what does this
+* mean with no session?" — so the honest split is two mounts. A page that wants
+* voice uses `mountClient()`; a page that wants neither audio nor a socket uses this.
+*
+* Authoring is otherwise identical — the file is still `client.tsx`, still
+* React, still Tailwind, still the same theme tokens — so a workflow app reads
+* like every other agent. What it reaches for instead of `useSession()` is
+* `useWorkflowSubmit()` / `useWorkflowRun()`, neither of which needs a client
+* built for it.
+*
+* And `component` is OPTIONAL, the way `mountClient()`'s is: with none, this
+* mounts the generated shell in `_page-shell.tsx`. That is also what a workflow
+* app with NO `client.tsx` at all now gets — `default-client.tsx`, the prebuilt
+* page, branches on the agent's declared front door and mounts this.
+*/
+/**
+* Mount a page for an agent whose work happens in workflows.
+*
+* There is deliberately no session, no microphone, and no socket: the page talks
+* to the agent over the workflow HTTP API (`useWorkflowSubmit`/`useWorkflowRun`),
+* which is durable and outlives the tab.
+*
+* **Config only:** leave `component` out and the generated shell renders — a
+* form per declared workflow, the run's progress, its failure, its output.
+*
+* **A custom component:** pass `component` and it is rendered inside the theme
+* provider instead. The pieces the default shell is built from are all published
+* (`useWorkflows`, `<WorkflowFields>`, `useWorkflowSubmit`,
+* `<WorkflowProgress>`, `<WorkflowRunError>`), so replacing the shell does not
+* mean starting from `fetch`.
+*
+* @example The default shell
+* ```tsx
+* import { mountPage } from "@alexkroman1/aai-ui";
+*
+* mountPage({ name: "Digest" });
+* ```
+*
+* @example A custom component
+* ```tsx
+* import { mountPage, useWorkflows } from "@alexkroman1/aai-ui";
+*
+* function App() {
+*   // No client to build and none to hoist: every workflow hook defaults to one
+*   // aimed at the agent serving this page, built lazily and once.
+*   const { workflows, loading } = useWorkflows();
+*   if (loading) return <p>Loading…</p>;
+*   return (
+*     <ul>
+*       {workflows.map((entry) => (
+*         <li key={entry.name}>{entry.description ?? entry.name}</li>
+*       ))}
+*     </ul>
+*   );
+* }
+*
+* mountPage({ name: "Digest", component: App });
+* ```
+*
+* @throws If the target element is not found in the DOM.
+*
+* @public
+*/
+function mountPage(config = {}) {
+	const container = resolveContainer(config.target);
+	setPageTitle(config.name);
+	const Root = config.component;
+	return mountRoot(container, createElement(ThemeProvider, { value: config.theme }, Root ? createElement(Root) : createElement(DefaultPageShell, { name: config.name })));
+}
+//#endregion
+//#region src/use-download-url.ts
+/**
+* `useDownloadUrl` — an upload id a run produced, as something `<audio>`,
+* `<img>` or `<a download>` will accept.
+*
+* `api.download(id)` resolves a `Blob`, and it has to: the byte route takes the
+* same bearer every workflow route does, and neither `<audio src>` nor
+* `<a href>` can send one. So every page that plays back what a run WROTE ends
+* up at the same four lines — `download` → `createObjectURL` → state — and the
+* two that are really the point are the two the four lines are wrapped in:
+*
+* - **`URL.revokeObjectURL` on cleanup.** An object URL pins its blob for the
+*   life of the DOCUMENT. Miss it and every completed run's audio stays resident
+*   until the tab closes, which on a page people run all day is a leak measured
+*   in the size of the files.
+* - **A `cancelled` flag.** A second run settling while the first download is
+*   still in flight otherwise sets state from the stale one, and the page plays
+*   the previous run's audio under the current run's transcript — a wrong answer
+*   that looks like a right one.
+*
+* Two templates had written this hook, identically, doc paragraph included, and
+* `aai-ui` exported no download helper at all. Both also faked `pending` by
+* checking `url === undefined && error === undefined`, which reads "idle" and
+* "downloading" as the same thing — so this reports it.
+*/
+/** No id: nothing pending, nothing to show. A shared object so `setState` no-ops. */
+const IDLE = { pending: false };
+/** Bytes in flight. Shared for the same reason as {@link IDLE}. */
+const PENDING = { pending: true };
+/**
+* Read an upload's bytes and hand back a URL a DOM element can use.
+*
+* @param uploadId - The id a completed run reported, or `undefined` before one
+*   exists — which is what a page passes straight through while it waits, and
+*   reports as idle rather than pending.
+* @param options - See {@link UseDownloadUrlOptions}.
+* @returns See {@link UseDownloadUrlResult}.
+*
+* @example
+* ```tsx no-check
+* import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+* import type { spokenSummary } from "./agent.ts";
+*
+* function Playback() {
+*   const { run } = useWorkflowSubmit<typeof spokenSummary>("spokenSummary");
+*   const output = run?.status === "completed" ? run.output : undefined;
+*   const audio = useDownloadUrl(output?.audio);
+*   if (audio.pending) return <p>Fetching audio…</p>;
+*   if (audio.error !== undefined) return <p role="alert">{audio.error}</p>;
+*   return audio.url === undefined ? null : (
+*     <a href={audio.url} download="summary.mp3">
+*       Download
+*     </a>
+*   );
+* }
+* ```
+*
+* @public
+*/
+function useDownloadUrl(uploadId, options = {}) {
+	const [state, setState] = useState(IDLE);
+	const getClient = useWorkflowApiRef(options.api);
+	useEffect(() => {
+		if (uploadId === void 0) {
+			setState(IDLE);
+			return;
+		}
+		let cancelled = false;
+		let objectUrl;
+		setState(PENDING);
+		getClient().download(uploadId).then((blob) => {
+			if (cancelled) return;
+			objectUrl = URL.createObjectURL(blob);
+			setState({
+				url: objectUrl,
+				pending: false
+			});
+		}).catch((err) => {
+			if (!cancelled) setState({
+				error: errorMessage(err),
+				pending: false
+			});
+		});
+		return () => {
+			cancelled = true;
+			if (objectUrl !== void 0) URL.revokeObjectURL(objectUrl);
+		};
+	}, [uploadId, getClient]);
+	return state;
+}
+//#endregion
+//#region src/use-push-to-talk.ts
+/**
+* `usePushToTalk` — a hold-to-speak button, for an agent that declares
+* `turnDetection: "manual"`.
+*
+* The three session edges underneath (`session.userTurn`'s `start`, `commit`
+* and `clear`) are one line each; what a button needs on top of them is
+* where hand-written versions go wrong, and every one of the four is a turn
+* that is left OPEN — the microphone live and nothing ever answered:
+*
+* - **The pointer leaves.** A `mouseup` outside the button never reaches it.
+*   The handlers here capture the pointer on the way down, so the release
+*   arrives wherever it happens; an `onPointerCancel` (a scroll gesture, a
+*   system dialog) DISCARDS the turn rather than answering half a sentence.
+* - **The key repeats.** Holding a key fires `keydown` over and over, and each
+*   one would re-open the turn. Only the first counts.
+* - **The window loses focus mid-hold.** The `keyup` goes to another window
+*   and is never delivered, so the turn is committed on `blur` — what the
+*   caller would have done had the release been seen.
+* - **The component unmounts mid-hold.** The turn is discarded on the way out.
+*
+* And one that is a nuisance rather than a stuck turn: the hold key is ignored
+* while focus is in a text field, where Space is a character.
+*/
+const selectRunning = (snapshot) => snapshot.running;
+/** True when a key event came from somewhere typing belongs. */
+function isTypingTarget(target) {
+	if (typeof HTMLElement === "undefined" || !(target instanceof HTMLElement)) return false;
+	return target.isContentEditable || [
+		"INPUT",
+		"TEXTAREA",
+		"SELECT"
+	].includes(target.tagName);
+}
+/**
+* Hold-to-speak over the session's push-to-talk methods, with the four ways a
+* turn gets stuck open handled — see this module's doc.
+*
+* Must be used inside the provider `mountClient()` installs, against an agent
+* declaring `turnDetection: "manual"`; any other agent ignores the commands and
+* its server says so once.
+*
+* @example A hold-to-talk button
+* ```tsx
+* import { usePushToTalk } from "@alexkroman1/aai-ui";
+*
+* function TalkButton() {
+*   const { talking, buttonProps } = usePushToTalk();
+*   return (
+*     <button type="button" {...buttonProps}>
+*       {talking ? "Listening… release to send" : "Hold to talk (or hold Space)"}
+*     </button>
+*   );
+* }
+* ```
+*
+* @public
+*/
+function usePushToTalk(options = {}) {
+	const holdKey = options.holdKey ?? "Space";
+	const { userTurn } = useSessionCore();
+	const ready = useSessionSelector(selectRunning);
+	const [talking, setTalking] = useState(false);
+	const held = useRef(false);
+	const press = useCallback(() => {
+		if (held.current || !ready) return;
+		held.current = true;
+		setTalking(true);
+		userTurn.start();
+	}, [ready, userTurn]);
+	const release = useCallback(() => {
+		if (!held.current) return;
+		held.current = false;
+		setTalking(false);
+		userTurn.commit();
+	}, [userTurn]);
+	const cancel = useCallback(() => {
+		if (!held.current) return;
+		held.current = false;
+		setTalking(false);
+		userTurn.clear();
+	}, [userTurn]);
+	useEffect(() => {
+		if (!ready && held.current) {
+			held.current = false;
+			setTalking(false);
+		}
+	}, [ready]);
+	useEffect(() => {
+		if (holdKey === false || typeof window === "undefined") return;
+		const down = (event) => {
+			if (event.code !== holdKey || event.repeat || isTypingTarget(event.target)) return;
+			event.preventDefault();
+			press();
+		};
+		const up = (event) => {
+			if (event.code !== holdKey) return;
+			event.preventDefault();
+			release();
+		};
+		window.addEventListener("keydown", down);
+		window.addEventListener("keyup", up);
+		window.addEventListener("blur", release);
+		return () => {
+			window.removeEventListener("keydown", down);
+			window.removeEventListener("keyup", up);
+			window.removeEventListener("blur", release);
+		};
+	}, [
+		holdKey,
+		press,
+		release
+	]);
+	const cancelRef = useRef(cancel);
+	cancelRef.current = cancel;
+	useEffect(() => () => cancelRef.current(), []);
+	const buttonProps = useMemo(() => ({
+		onPointerDown: (event) => {
+			event.currentTarget.setPointerCapture?.(event.pointerId);
+			press();
+		},
+		onPointerUp: release,
+		onPointerCancel: cancel,
+		onKeyDown: (event) => {
+			if (event.key !== " " && event.key !== "Enter" || event.repeat) return;
+			event.preventDefault();
+			press();
+		},
+		onKeyUp: (event) => {
+			if (event.key !== " " && event.key !== "Enter") return;
+			event.preventDefault();
+			release();
+		},
+		onContextMenu: (event) => event.preventDefault(),
+		disabled: !ready,
+		"aria-pressed": talking
+	}), [
+		press,
+		release,
+		cancel,
+		ready,
+		talking
+	]);
+	return useMemo(() => ({
+		talking,
+		ready,
+		press,
+		release,
+		cancel,
+		buttonProps
+	}), [
+		talking,
+		ready,
+		press,
+		release,
+		cancel,
+		buttonProps
+	]);
+}
+//#endregion
 //#region src/use-workflow-runs.ts
 /**
 * The RUNS a workflow has had — the list a page shows beside its form.
@@ -3236,4 +3537,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, createBrowserSession, createWorkflowApi, fetchClientConfig, fieldKindFor, isTerminal, mountClient, mountPage, useAgentState, useConversation, useCopy, useDownloadUrl, useEvent, useFlash, useRunKey, useSession, useSessionActions, useSessionControls, useSessionError, useSessionSelector, useSessionStatus, 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, createBrowserSession, createWorkflowApi, fetchClientConfig, fieldKindFor, isTerminal, mountClient, mountPage, useAgentState, useConversation, useCopy, useDownloadUrl, useEvent, useFlash, usePushToTalk, useRunKey, useSession, useSessionActions, useSessionControls, useSessionError, useSessionSelector, useSessionStatus, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };