@alexkroman1/aai-ui 0.14.0 → 0.14.2

package/dist/index.js

@@ -1,7 +1,7 @@
 import { a as AGENT_STATE_LABELS, i as SessionErrorBanner, n as ConsoleShell, r as SessionStateDot, t as ChatView } from "./chat-view-BCbI7gD4.js";
 import { n as pageBaseUrl, r as setPageTitle, t as isTypingTarget } from "./_utils-Mi-SCFA1.js";
 import { n as fetchClientConfig, t as buildAgentUrl } from "./client-config-C7fQrioM.js";
-import { a as ticketCarriage, c as resolveReported, d as storageSet, f as urlSlot, i as resolveSessionTokenSync, l as storageGet, r as resolveSessionToken, s as browserClientId, t as createBrowserSession, u as storageRemove } from "./session-D9jM5-TF.js";
+import { a as ticketCarriage, c as resolveReported, d as storageSet, f as urlSlot, i as resolveSessionTokenSync, l as storageGet, r as resolveSessionToken, s as browserClientId, t as createBrowserSession, u as storageRemove } from "./session-CYdjRvbl.js";
 import { ThemeProvider, useOptionalSessionCore, useSession, useSessionActions, useSessionCore, useSessionError, useSessionSelector, useSessionStatus, useTheme } from "./context.js";
 import { a as useAgentState, i as selectAgentState, n as useToolCallStart, r as useToolResult, t as useEvent } from "./hooks-DN4gHYsj.js";
 import { a as useConversation, i as interleave, n as Markdown, o as AutoScroll, r as ConversationView, t as MessageList } from "./message-list-DHZcLhRA.js";
@@ -17,12 +17,12 @@ import { a as useWorkflowProgress, c as isTerminal, o as useWorkflowApiRef, r as
 import { mountClient, mountRoot, resolveContainer } from "./define-client.js";
 import { errorMessage, errorMessage as errorMessage$1 } from "@alexkroman1/aai";
 import { InboxServerFrameSchema } from "@alexkroman1/aai/protocol";
-import { CLIENT_ID_RE, createEpoch, jitteredBackoff } from "@alexkroman1/aai/internal";
+import { CLIENT_ID_RE, createBackoffLoop, createEpoch } from "@alexkroman1/aai/internal";
 import { Fragment, createContext, createElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import clsx from "clsx";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { formatBytes, isRecord, omitUndefined, safeJsonParse as safeJsonParse$1 } from "@alexkroman1/aai/utils";
-import { assign, createActor, raise, setup, stateIn } from "xstate";
+import { assign, createActor, fromPromise, raise, setup, stateIn } from "xstate";
 //#region src/client-tool.ts
 /**
 * The page's half of a `clientTool`: run the handler when the agent calls the
@@ -2160,7 +2160,8 @@ function createNoticeAssembler(busy) {
 * half is `aai-runtime`'s `aai-runtime/src/inbox/inbox.ts`.
 *
 * - **Held from creation, reconnected until `close()`**, on a jittered backoff
-*   from 1 s doubling to 30 s (`jitteredBackoff`), reset by every open. The
+*   from 1 s doubling to 30 s (`createBackoffLoop` with `jitter`), reset by
+*   every open. The
 *   jitter matters here more than for most loops: an agent restart drops every
 *   open inbox at once, and every tab of every user comes back together.
 * - **Its own socket, not partysocket.** The session's reconnecting socket
@@ -2227,23 +2228,12 @@ function createInbox(options) {
 	const subscribers = /* @__PURE__ */ new Set();
 	let socket;
 	let open = false;
-	let closed = false;
-	let failures = 0;
-	let retry;
 	const assembler = createNoticeAssembler(() => options.busy?.() ?? false);
 	function setOpen(next) {
 		if (open === next) return;
 		open = next;
 		for (const callback of subscribers) callback();
 	}
-	function scheduleRetry() {
-		if (closed) return;
-		failures++;
-		retry = setTimeout(connect, jitteredBackoff(failures, {
-			baseMs: INBOX_RECONNECT_BASE_MS,
-			maxMs: INBOX_RECONNECT_MAX_MS
-		}));
-	}
 	function url(client, queryToken) {
 		const target = buildAgentUrl(options.platformUrl, "inbox");
 		target.protocol = target.protocol === "https:" ? "wss:" : "ws:";
@@ -2272,11 +2262,9 @@ function createInbox(options) {
 		return typeof answer === "string" || answer === void 0 ? resolveSessionTokenSync(answer, attempt) : resolveSessionToken(() => answer, attempt);
 	}
 	function connect() {
-		retry = void 0;
-		if (closed) return;
 		const client = resolveReported(options.client);
 		if (!(client && CLIENT_ID_RE.test(client))) {
-			scheduleRetry();
+			loop.retry();
 			return;
 		}
 		const token = askToken();
@@ -2285,7 +2273,7 @@ function createInbox(options) {
 			return;
 		}
 		token.then((answer) => {
-			if (!closed) dial(client, answer);
+			if (!loop.stopped()) dial(client, answer);
 		});
 	}
 	function dial(client, token) {
@@ -2300,7 +2288,7 @@ function createInbox(options) {
 			ws.send(JSON.stringify(out.reply));
 		};
 		ws.addEventListener("open", () => {
-			failures = 0;
+			loop.reset();
 			setOpen(true);
 		});
 		ws.addEventListener("message", (e) => {
@@ -2317,10 +2305,15 @@ function createInbox(options) {
 			socket = void 0;
 			setOpen(false);
 			assembler.reset();
-			scheduleRetry();
+			loop.retry();
 		});
 	}
-	connect();
+	const loop = createBackoffLoop(connect, {
+		baseMs: INBOX_RECONNECT_BASE_MS,
+		maxMs: INBOX_RECONNECT_MAX_MS,
+		jitter: true
+	});
+	loop.start();
 	return {
 		connected: () => open,
 		subscribe(callback) {
@@ -2330,8 +2323,7 @@ function createInbox(options) {
 			};
 		},
 		close() {
-			closed = true;
-			clearTimeout(retry);
+			loop.stop();
 			const ws = socket;
 			socket = void 0;
 			ws?.close();
@@ -2395,100 +2387,6 @@ function createLinkedClient(options) {
 	});
 }
 //#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$1(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.
@@ -2527,6 +2425,392 @@ function useRunControls(runId, getClient) {
 	};
 }
 //#endregion
+//#region src/_recover-run.ts
+/**
+* Look up the newest run for a key.
+*
+* @returns The run's id, or `undefined` for a key with no runs. A failure
+*   REJECTS, so the machine can report it — see "A failed lookup is REPORTED".
+*/
+async function findRecoveredRun(client, workflow, key) {
+	return (await client.find(workflow, key, { limit: 1 }))[0]?.runId;
+}
+//#endregion
+//#region src/_actor-store.ts
+/** Start `actor` and expose it through `read`, its memoized projection. */
+function actorStore(actor, read) {
+	actor.start();
+	return {
+		send: (event) => actor.send(event),
+		getView: read,
+		subscribe(listener) {
+			const sub = actor.subscribe(() => listener());
+			return () => sub.unsubscribe();
+		},
+		stop: () => actor.stop()
+	};
+}
+//#endregion
+//#region src/_workflow-form-state.ts
+/**
+* A workflow form's submission as a statechart, with no React: the mount-time
+* lookup, the submission in flight, the person's pause, and what the page is
+* left holding afterwards. `useWorkflowSubmit` and `useWorkflowStream` feed it
+* through `_submission-state.ts`; `_workflow-form-state.test.ts` specs it
+* without a renderer. The pattern is `_tap-to-talk-state.ts`'s and
+* `session/audio-state.ts`'s: a `setup()` machine, effects in `input`,
+* cancellable work as a `fromPromise` invoke.
+*
+* ```text
+*   idle ──RECOVER──► recovering ──found──► following
+*     ▲                   │ └──none──► idle
+*     │                   └──failed──► failed
+*   RESET (anywhere)
+*   SUBMIT (anywhere) ──► submitting { active ⇄ paused } ──done──► following
+*                                                       └─failed─► failed
+* ```
+*
+* It replaces four `useState`s, a `startedHere` flag, a `recovering` flag and
+* a ref holding the live submission, and three rules that were each a patch
+* over a race the position now answers:
+*
+* - **A superseded submission owns nothing.** It used to be dropped by a token
+*   compare in `end()` (`current !== token`). A `SUBMIT` now RE-ENTERS
+*   `submitting`, which stops the old invoke: its signal aborts, which cancels
+*   its gate, and XState drops its result. Reports from it are refused at the
+*   producer, on the same signal — the one "is this still wanted?" test, in the
+*   one place that knows the answer.
+* - **The lookup never wins a race against a submit.** It used to be
+*   `setRunId(current => current ?? found)`. The lookup is an invoke of
+*   `recovering` now, so a `SUBMIT` (or a `RESET`) that leaves it stops it,
+*   and an answer that lands afterwards is an answer nobody asked for.
+* - **`pending` was three hooks' flags OR-ed together.** Two of the three were
+*   positions in this machine; {@link WorkflowFormView.busy} is both. The
+*   third, the run's own `polling`, stays outside on purpose: it is
+*   `useWorkflowRun`'s and cannot be derived from the snapshot (see that hook).
+*
+* ## What `submitting` does not split
+*
+* Uploading and starting are not child states. The two hooks run them in
+* OPPOSITE orders — `useWorkflowSubmit` stores the bytes and then starts the
+* run, `useWorkflowStream` starts the run and then streams the bytes — so a
+* fixed `uploading → starting` order would be wrong for one of them, and
+* nothing this machine decides depends on which step is current. `active` /
+* `paused` is the split that does matter: it is the gate, and the bar's
+* `paused` flag, moving together.
+*/
+const machine$1 = setup({
+	types: {},
+	actors: {
+		lookup: fromPromise(({ input }) => input.find()),
+		/**
+		* One submission. An invoke rather than a fire-and-forget call so that
+		* leaving `submitting` — a superseding `SUBMIT`, a `RESET`, an unmount —
+		* stops it, and stopping it is what abandons it.
+		*/
+		submission: fromPromise(async ({ input, signal }) => {
+			const { gate, work, settle, send } = input;
+			signal.addEventListener("abort", () => gate?.cancel(), { once: true });
+			const live = (event) => {
+				if (!signal.aborted) send(event);
+			};
+			try {
+				await work?.({
+					progress: (upload) => live({
+						type: "PROGRESS",
+						upload
+					}),
+					started: (runId) => live({
+						type: "STARTED",
+						runId
+					})
+				});
+			} finally {
+				if (signal.aborted) settle?.();
+			}
+		})
+	},
+	guards: {
+		found: ({ event }) => "output" in event && typeof event.output === "string",
+		hasRun: ({ context }) => context.runId !== void 0,
+		noRun: ({ context }) => context.runId === void 0
+	},
+	actions: {
+		open: assign(({ event }) => event.type === "SUBMIT" ? {
+			gate: event.gate,
+			work: event.work,
+			settle: event.settle,
+			runId: void 0,
+			startError: void 0,
+			upload: void 0,
+			startedHere: true
+		} : {}),
+		/**
+		* Leaving `submitting`, by whichever edge. The bar goes too: from here the
+		* wait belongs to the RUN, and a bar left at 100% under a running workflow
+		* reads as the thing taking the time.
+		*/
+		close: assign({
+			gate: void 0,
+			work: void 0,
+			settle: void 0,
+			upload: void 0
+		}),
+		/**
+		* `submit()`'s promise. Before `close`, which forgets it; and before the
+		* edge's own actions only in program order — a resolution runs its
+		* continuation as a microtask, after the whole transition has landed, so
+		* an awaiting caller already reads the error or the run.
+		*/
+		settle: ({ context }) => context.settle?.(),
+		clear: assign({
+			runId: void 0,
+			startError: void 0,
+			startedHere: false
+		}),
+		pauseGate: ({ context }) => context.gate?.pause(),
+		resumeGate: ({ context }) => context.gate?.resume(),
+		/** Folded rather than replaced: which file and how far are still true. */
+		markPaused: assign({ upload: ({ context }) => context.upload ? {
+			...context.upload,
+			paused: true
+		} : void 0 }),
+		markResumed: assign({ upload: ({ context }) => context.upload ? {
+			...context.upload,
+			paused: false
+		} : void 0 })
+	}
+}).createMachine({
+	id: "workflowForm",
+	context: ({ input }) => ({
+		effects: input,
+		runId: void 0,
+		startError: void 0,
+		upload: void 0,
+		startedHere: false,
+		gate: void 0,
+		work: void 0,
+		settle: void 0
+	}),
+	initial: "idle",
+	on: {
+		SUBMIT: {
+			target: ".submitting",
+			reenter: true,
+			actions: "open"
+		},
+		RESET: {
+			target: ".idle",
+			actions: "clear"
+		}
+	},
+	states: {
+		idle: { on: { RECOVER: "recovering" } },
+		/**
+		* The mount-time lookup (`_recover-run.ts`). Leaving by any other edge —
+		* a submit, a reset — stops it, so a late answer adopts nothing.
+		*/
+		recovering: {
+			entry: assign({ startError: void 0 }),
+			invoke: {
+				src: "lookup",
+				input: ({ context }) => context.effects,
+				onDone: [{
+					guard: "found",
+					target: "following",
+					actions: assign({ runId: ({ event }) => event.output })
+				}, { target: "idle" }],
+				onError: {
+					target: "failed",
+					actions: assign({ startError: ({ event }) => errorMessage$1(event.error) })
+				}
+			}
+		},
+		submitting: {
+			initial: "active",
+			exit: ["settle", "close"],
+			invoke: {
+				src: "submission",
+				input: ({ context, self }) => ({
+					gate: context.gate,
+					work: context.work,
+					settle: context.settle,
+					send: (event) => {
+						self.send(event);
+					}
+				}),
+				onDone: [{
+					guard: "hasRun",
+					target: "following"
+				}, { target: "idle" }],
+				onError: {
+					target: "failed",
+					actions: assign({ startError: ({ event }) => errorMessage$1(event.error) })
+				}
+			},
+			on: {
+				PROGRESS: { actions: assign({ upload: ({ event }) => event.upload }) },
+				STARTED: { actions: assign({ runId: ({ event }) => event.runId }) }
+			},
+			states: {
+				active: { on: { PAUSE: {
+					target: "paused",
+					actions: ["pauseGate", "markPaused"]
+				} } },
+				paused: { on: { RESUME: {
+					target: "active",
+					actions: ["resumeGate", "markResumed"]
+				} } }
+			}
+		},
+		/** A run on the page — started here, or adopted by the lookup. */
+		following: {},
+		/**
+		* The submission's or the lookup's own failure. A stream submission can
+		* land here WITH a run (started, then its upload failed and it was
+		* cancelled), which is why `RECOVER` is guarded rather than plain.
+		*/
+		failed: { on: { RECOVER: {
+			guard: "noRun",
+			target: "recovering"
+		} } }
+	}
+});
+/** Start a machine over `effects`. */
+function createWorkflowForm(effects) {
+	const actor = createActor(machine$1, { input: effects });
+	let view = {
+		runId: void 0,
+		startError: void 0,
+		upload: void 0,
+		startedHere: false,
+		busy: false
+	};
+	const read = () => {
+		const at = actor.getSnapshot();
+		const { runId, startError, upload, startedHere } = at.context;
+		const busy = at.matches("recovering") || at.matches("submitting");
+		if (runId !== view.runId || startError !== view.startError || upload !== view.upload || startedHere !== view.startedHere || busy !== view.busy) view = {
+			runId,
+			startError,
+			upload,
+			startedHere,
+			busy
+		};
+		return view;
+	};
+	return actorStore(actor, read);
+}
+//#endregion
+//#region src/_submission-state.ts
+/**
+* The state a form submission carries, for both hooks that make one: the
+* form's statechart (`_workflow-form-state.ts`) bridged into React with
+* `useSyncExternalStore`, the way `use-tap-to-talk.ts` bridges its own.
+*
+* `useWorkflowSubmit` and `useWorkflowStream` stay separate hooks — they differ
+* in WHEN the run is created relative to the bytes, which is the whole reason
+* the streaming one exists — but everything around that ordering is shared:
+* the run id, the submission's own failure, the bar, `startedHere`, the
+* supersede rule, `reset` and the pause pair. Each hook still owns its own
+* submission BODY, handed to {@link SubmissionActions.submit}.
+*
+* Nothing here decides anything. The decisions are positions of the machine,
+* which is why this module holds no token, no ref to a live submission, and no
+* "is this still the current one?" check.
+*/
+const IDLE_VIEW$1 = {
+	runId: void 0,
+	startError: void 0,
+	upload: void 0,
+	startedHere: false,
+	busy: false
+};
+/**
+* The frames before the machine exists, for a page that will look its run up.
+* Busy from the FIRST render rather than from the effect, so there is no frame
+* in which a page about to adopt a run reads as idle.
+*/
+const RECOVERING_VIEW = {
+	...IDLE_VIEW$1,
+	busy: true
+};
+const NO_SUBSCRIPTION$1 = () => () => void 0;
+const idleView = () => IDLE_VIEW$1;
+const recoveringView = () => RECOVERING_VIEW;
+/** What a lookup is FOR, so a re-render asking the same question asks nothing. */
+function questionOf(recover) {
+	return recover?.enabled ? `${recover.workflow}\n${recover.key}` : void 0;
+}
+/**
+* The shared submission scaffold. See the module doc.
+*
+* @param recover - The mount-time lookup (`_recover-run.ts`), or nothing for a
+*   hook that refuses it (`useWorkflowStream`).
+*/
+function useSubmissionState(recover) {
+	const lookup = useRef(recover);
+	lookup.current = recover;
+	const asked = useRef(void 0);
+	const live = useRef(null);
+	const [store, setStore] = useState(null);
+	useEffect(() => {
+		const next = createWorkflowForm({ find: async () => {
+			const at = lookup.current;
+			if (!at) return;
+			return await findRecoveredRun(at.getClient(), at.workflow, at.key);
+		} });
+		asked.current = questionOf(lookup.current);
+		if (asked.current !== void 0) next.send({ type: "RECOVER" });
+		live.current = next;
+		setStore(next);
+		return () => {
+			next.stop();
+			live.current = null;
+			asked.current = void 0;
+			setStore(null);
+		};
+	}, []);
+	const question = questionOf(recover);
+	useEffect(() => {
+		if (!store || question === asked.current) return;
+		asked.current = question;
+		if (question !== void 0) store.send({ type: "RECOVER" });
+	}, [store, question]);
+	const beforeStore = question === void 0 ? idleView : recoveringView;
+	const view = useSyncExternalStore(store?.subscribe ?? NO_SUBSCRIPTION$1, store ? store.getView : beforeStore);
+	const submit = useCallback((gate, work) => {
+		const machine = live.current;
+		if (!machine) return Promise.resolve();
+		const done = Promise.withResolvers();
+		machine.send({
+			type: "SUBMIT",
+			gate,
+			work,
+			settle: () => done.resolve()
+		});
+		return done.promise;
+	}, []);
+	const reset = useCallback(() => live.current?.send({ type: "RESET" }), []);
+	const pauseUpload = useCallback(() => live.current?.send({ type: "PAUSE" }), []);
+	const resumeUpload = useCallback(() => live.current?.send({ type: "RESUME" }), []);
+	const actions = useMemo(() => ({
+		submit,
+		reset,
+		pauseUpload,
+		resumeUpload
+	}), [
+		submit,
+		reset,
+		pauseUpload,
+		resumeUpload
+	]);
+	return {
+		...view,
+		actions
+	};
+}
+//#endregion
 //#region src/_workflow-files.ts
 /**
 * Which of a submitted form's values are FILES.
@@ -2739,44 +3023,44 @@ async function sendThroughGate(gate, send) {
 */
 function createUploadGate() {
 	let controller = new AbortController();
-	let paused = false;
-	let cancelled = false;
+	let phase = "running";
 	let open;
 	let closed;
+	/** Wake an uploader parked on `settle()`, whichever way the gate is opening. */
+	const release = () => {
+		open?.();
+		open = void 0;
+		closed = void 0;
+	};
 	return {
 		get paused() {
-			return paused;
+			return phase === "paused";
 		},
 		get cancelled() {
-			return cancelled;
+			return phase === "cancelled";
 		},
 		get signal() {
 			return controller.signal;
 		},
 		pause() {
-			if (paused || cancelled) return;
-			paused = true;
+			if (phase !== "running") return;
+			phase = "paused";
 			const gate = Promise.withResolvers();
 			closed = gate.promise;
 			open = gate.resolve;
 			controller.abort();
 		},
 		resume() {
-			if (!paused || cancelled) return;
-			paused = false;
+			if (phase !== "paused") return;
+			phase = "running";
 			controller = new AbortController();
-			open?.();
-			open = void 0;
-			closed = void 0;
+			release();
 		},
 		cancel() {
-			if (cancelled) return;
-			cancelled = true;
-			paused = false;
+			if (phase === "cancelled") return;
+			phase = "cancelled";
 			controller.abort();
-			open?.();
-			open = void 0;
-			closed = void 0;
+			release();
 		},
 		async settle() {
 			if (closed) await closed;
@@ -2950,46 +3234,6 @@ async function uploadFiles(api, input, report, parallel, session) {
 	return out;
 }
 //#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/upload/report.ts
 /**
 * What the bar draws, as a comparable string.
@@ -3026,59 +3270,6 @@ function coalesceUploadReports(set) {
 	};
 }
 //#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/use-run-key.ts
 /**
 * The handle a page keeps on the runs it started, across a reload.
@@ -3304,42 +3495,31 @@ function useRunKey(options = {}) {
 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 form = useSubmissionState({
+		workflow,
+		key,
+		enabled: recover,
+		getClient
+	});
+	const { runId, actions } = form;
 	const tracked = useWorkflowRun(runId, omitUndefined({
 		api,
 		intervalMs
 	}));
 	const { wake, cancel } = useRunControls(runId, getClient);
-	const [startedHere, setStartedHere] = useState(false);
-	const recovering = useRecoveredRun({
-		workflow,
-		key,
-		enabled: recover,
-		getClient,
-		onFound: (found) => {
-			actions.setRunId((current) => current ?? found);
-		},
-		onError: actions.setStartError
-	});
-	const submit = useCallback(async (input) => {
+	const submit = useCallback((input) => {
 		const client = getClient();
-		const current = createUploadSession(workflow);
-		setStartedHere(true);
-		actions.begin(current);
-		try {
+		const session = createUploadSession(workflow);
+		return actions.submit(session.gate, async ({ progress, started }) => {
 			const options = omitUndefined({ key });
-			const started = await uploadFiles(client, input, coalesceUploadReports(actions.setUpload), parallel, current);
-			actions.setRunId(wait === void 0 ? await client.start(workflow, started, options) : (await client.startAndWait(workflow, started, {
+			const report = coalesceUploadReports(progress);
+			const stored = await uploadFiles(client, input, report, parallel, session);
+			started(wait === void 0 ? await client.start(workflow, stored, options) : (await client.startAndWait(workflow, stored, {
 				...options,
 				wait
 			})).runId);
-		} catch (err) {
-			if (!current.gate.cancelled) actions.setStartError(errorMessage$1(err));
-		} finally {
-			actions.end(current);
-		}
+		});
 	}, [
 		workflow,
 		key,
@@ -3351,19 +3531,16 @@ function useWorkflowSubmit(workflow, options = {}) {
 	return {
 		submit,
 		submitForm: submit,
-		reset: useCallback(() => {
-			setStartedHere(false);
-			actions.reset();
-		}, [actions]),
+		reset: actions.reset,
 		wake,
 		cancel,
 		pauseUpload: actions.pauseUpload,
 		resumeUpload: actions.resumeUpload,
 		run: tracked.run,
-		startedHere,
-		pending: recovering || state.starting || tracked.polling,
-		upload: state.upload,
-		error: state.startError ?? tracked.error
+		startedHere: form.startedHere,
+		pending: form.busy || tracked.polling,
+		upload: form.upload,
+		error: form.startError ?? tracked.error
 	};
 }
 //#endregion
@@ -4926,16 +5103,7 @@ function createTapToTalk(effects, timing) {
 		};
 		return view;
 	};
-	actor.start();
-	return {
-		send: (event) => actor.send(event),
-		getView: read,
-		subscribe(listener) {
-			const sub = actor.subscribe(() => listener());
-			return () => sub.unsubscribe();
-		},
-		stop: () => actor.stop()
-	};
+	return actorStore(actor, read);
 }
 //#endregion
 //#region src/use-tap-to-talk.ts
@@ -5338,50 +5506,46 @@ function useWorkflowRuns(workflow, options = {}) {
 */
 function useWorkflowStream(workflow, options = {}) {
 	const { api, key, intervalMs, parallel } = options;
-	const state = useSubmissionState();
-	const { runId, actions } = state;
 	const getClient = useWorkflowApiRef(api);
+	const form = useSubmissionState();
+	const { runId, actions } = form;
 	const tracked = useWorkflowRun(runId, omitUndefined({
 		api,
 		intervalMs
 	}));
 	const { wake, cancel } = useRunControls(runId, getClient);
-	const [startedHere, setStartedHere] = useState(false);
-	const submit = useCallback(async (input) => {
+	const submit = useCallback((input) => {
 		const client = getClient();
-		const current = { gate: createUploadGate() };
-		const { gate } = current;
-		setStartedHere(true);
-		actions.begin(current);
-		let started;
-		try {
-			const id = randomUploadId();
-			const begun = await beginRun({
-				client,
-				workflow,
-				input,
-				id,
-				...omitUndefined({ key })
-			});
-			started = begun.runId;
-			const chosen = begun.file;
-			actions.setRunId(started);
-			if (!chosen) return;
-			await streamFile({
-				client,
-				gate,
-				id,
-				file: chosen,
-				parallel,
-				report: coalesceUploadReports(actions.setUpload)
-			});
-			await client.wake(started).catch(() => void 0);
-		} catch (err) {
-			if (!gate.cancelled) actions.setStartError(errorMessage$1(err));
-			if (started) await client.cancel(started).catch(() => void 0);
-		} finally {
-			actions.end(current);
-		}
+		const gate = createUploadGate();
+		return actions.submit(gate, async ({ progress, started: adopt }) => {
+			let started;
+			try {
+				const id = randomUploadId();
+				const begun = await beginRun({
+					client,
+					workflow,
+					input,
+					id,
+					...omitUndefined({ key })
+				});
+				started = begun.runId;
+				const chosen = begun.file;
+				adopt(started);
+				if (!chosen) return;
+				await streamFile({
+					client,
+					gate,
+					id,
+					file: chosen,
+					parallel,
+					report: coalesceUploadReports(progress)
+				});
+				await client.wake(started).catch(() => void 0);
+			} catch (err) {
+				if (started) await client.cancel(started).catch(() => void 0);
+				throw err;
+			}
+		});
 	}, [
 		workflow,
 		key,
@@ -5392,19 +5556,16 @@ function useWorkflowStream(workflow, options = {}) {
 	return {
 		submit,
 		submitForm: submit,
-		reset: useCallback(() => {
-			setStartedHere(false);
-			actions.reset();
-		}, [actions]),
+		reset: actions.reset,
 		wake,
 		cancel,
 		pauseUpload: actions.pauseUpload,
 		resumeUpload: actions.resumeUpload,
 		run: tracked.run,
-		startedHere,
-		pending: state.starting || tracked.polling,
-		upload: state.upload,
-		error: state.startError ?? tracked.error
+		startedHere: form.startedHere,
+		pending: form.busy || tracked.polling,
+		upload: form.upload,
+		error: form.startError ?? tracked.error
 	};
 }
 /**