@alexkroman1/aai-ui 6.7.2 → 6.9.1

package/dist/index.js

@@ -590,6 +590,14 @@ function formatBytes(bytes) {
 * - **The file is NAMED, and counted when there is more than one.** Files are
 *   sent one after another, so a single bar otherwise appears to restart from
 *   zero partway through with nothing to say why.
+* - **A paused upload SAYS SO, rather than being a bar that stopped.** Those look
+*   identical, which is the whole reason `UploadStatus.paused` exists, and the
+*   fill stops animating so the difference is visible without reading.
+*
+* The pause control appears only when a handler for it is passed. That is not
+* politeness about props: a button whose press does nothing is worse than no
+* button, and a page holding an `upload` it did not produce (a saved status, a
+* parent's state) has nothing to pause.
 *
 * @example
 * ```tsx
@@ -609,16 +617,20 @@ function formatBytes(bytes) {
 *
 * @param upload - What `useWorkflowSubmit` reports. `undefined` renders nothing,
 *   so a page may pass its state straight through.
+* @param onPause - The hook's `pauseUpload`. Pass it together with `onResume` to
+*   get the control; pass neither for a bar that only reports.
+* @param onResume - The hook's `resumeUpload`.
 * @param className - Replaces the default classes rather than extending them,
 *   so a custom chrome is not fighting a default it did not ask for.
 *
 * @public
 */
-function UploadProgressBar({ upload, className }) {
+function UploadProgressBar({ upload, onPause, onResume, className }) {
 	const theme = useTheme();
 	const labelId = useId();
 	if (!upload) return null;
-	const { name, index, count, loaded, total, fraction } = upload;
+	const { name, index, count, loaded, total, fraction, paused } = upload;
+	const control = onPause && onResume ? paused ? onResume : onPause : void 0;
 	const percent = fraction === void 0 ? void 0 : Math.round(fraction * 100);
 	const faint = inkTint(theme.text, theme.surface, 65);
 	return /* @__PURE__ */ jsxs("div", {
@@ -629,11 +641,20 @@ function UploadProgressBar({ upload, className }) {
 				id: labelId,
 				className: "truncate",
 				style: { color: faint },
-				children: count > 1 ? `Uploading ${name} (${index} of ${count})` : `Uploading ${name}`
-			}), /* @__PURE__ */ jsx("span", {
-				className: "shrink-0 tabular-nums",
-				style: { color: faint },
-				children: total === void 0 ? formatBytes(loaded) : `${formatBytes(loaded)} of ${formatBytes(total)}`
+				children: `${paused ? "Paused" : "Uploading"} ${name}${count > 1 ? ` (${index} of ${count})` : ""}`
+			}), /* @__PURE__ */ jsxs("div", {
+				className: "flex shrink-0 items-baseline gap-3",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "tabular-nums",
+					style: { color: faint },
+					children: total === void 0 ? formatBytes(loaded) : `${formatBytes(loaded)} of ${formatBytes(total)}`
+				}), control && /* @__PURE__ */ jsx(Button, {
+					type: "button",
+					variant: "ghost",
+					className: "h-6 px-2 text-[0.625rem]",
+					onClick: control,
+					children: paused ? "Resume" : "Pause"
+				})]
 			})]
 		}), /* @__PURE__ */ jsx("div", {
 			role: "progressbar",
@@ -644,7 +665,7 @@ function UploadProgressBar({ upload, className }) {
 			className: "h-1.5 w-full overflow-hidden rounded-full",
 			style: { backgroundColor: inkTint(theme.text, theme.surface, TRACK_TINT_PCT) },
 			children: /* @__PURE__ */ jsx("div", {
-				className: clsx("h-full rounded-full transition-[width] duration-200 ease-out", percent === void 0 && "animate-pulse"),
+				className: clsx("h-full rounded-full transition-[width] duration-200 ease-out", percent === void 0 && !paused && "animate-pulse"),
 				style: {
 					backgroundColor: theme.primary,
 					width: percent === void 0 ? "100%" : `${percent}%`
@@ -654,6 +675,431 @@ function UploadProgressBar({ upload, className }) {
 	});
 }
 //#endregion
+//#region _upload-recall.ts
+/**
+* Where an upload's ID survives a page RELOAD.
+*
+* A streamed upload is resumable because its id outlives the attempt that began
+* it — `_upload-files.ts` says so, and `_upload-session.ts` turns that into a
+* pause a person can press. Both of them hold the id in MEMORY: the walk's
+* `UploadSession` lives in a `useRef`, so a reload was the one interruption the
+* mechanism could not survive. Everything else was already in place — the windows
+* were still in the store, the agent could still name them
+* (`UploadInfo.ranges`), and the id was minted in the browser — and the browser
+* had thrown away the only name for them. So a person who refreshed at 90% of a
+* 200 MB recording sent the whole file again, which is the one interruption they
+* are most likely to cause on purpose.
+*
+* This is that name, written down. It is what tus-js-client's `urlStorage` and
+* Uppy's Golden Retriever sell, in the shape `session-resume-store.ts` already
+* uses for a session id.
+*
+* ## A FINGERPRINT, because a `File` has no name a page can address
+*
+* A file from a picker carries no path and no handle, so the key is what
+* tus-js-client fingerprints on: size, last-modified, type and name. Two
+* different files agreeing on all four is the case this cannot tell apart — and
+* the reason NOTHING here decides to resume. `_upload-files.ts` asks the agent
+* what the id actually holds before sending a byte to it, so a wrong hit costs
+* one `GET` and a fresh id rather than a corrupted upload.
+*
+* ## `sessionStorage`, deliberately
+*
+* The same call `session-resume-store.ts` makes, for a reason that happens to be
+* stronger here: a reload and a same-tab navigation are exactly what this is for,
+* and an id from yesterday names an upload the agent's sweep has very likely
+* already collected. A tab is also the boundary the walk itself has — two tabs
+* uploading the same recording are two submissions.
+*
+* Every access is guarded. Storage throws outright in Safari private mode and
+* 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:";
+/**
+* How many ids one form keeps.
+*
+* A cap rather than an expiry, because `sessionStorage` already expires with the
+* tab and an entry is ~80 bytes. What it bounds is the long-lived tab that
+* submits a hundred files: the oldest go first, and the id most likely to be
+* worth resuming is the one written last.
+*/
+const MAX_REMEMBERED = 32;
+/** One form's slot in storage. */
+function keyFor(scope) {
+	return `${PREFIX}${scope}`;
+}
+/**
+* What names this file across a reload.
+*
+* The four fields a browser gives a picked file that do not change between loads.
+* `name` last because it is the one a person can read in a debugger.
+*/
+function fingerprint(file) {
+	return `${file.size}:${file.lastModified}:${file.type}:${file.name}`;
+}
+/** This scope's remembered ids, or nothing at all — a parse failure is nothing. */
+function read(scope) {
+	try {
+		const raw = globalThis.sessionStorage?.getItem(keyFor(scope));
+		if (raw === null || raw === void 0) return {};
+		const parsed = JSON.parse(raw);
+		return isRecord(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+function write(scope, entries) {
+	try {
+		globalThis.sessionStorage?.setItem(keyFor(scope), JSON.stringify(entries));
+	} catch {}
+}
+/**
+* The id this file was last being stored under in this tab, if any.
+*
+* A hit is a CANDIDATE and never a decision — see the module doc.
+*
+* @internal
+*/
+function recallUploadId(scope, file) {
+	const found = read(scope)[fingerprint(file)];
+	return typeof found === "string" ? found : void 0;
+}
+/**
+* Remember the id this file is being stored under.
+*
+* Called before the first byte leaves rather than after the last one lands: the
+* reload this exists for happens in between, and an id written at the end is an
+* id written for the one case that did not need it.
+*
+* @internal
+*/
+function rememberUploadId(scope, file, id) {
+	const entries = read(scope);
+	const key = fingerprint(file);
+	delete entries[key];
+	entries[key] = id;
+	const keys = Object.keys(entries);
+	for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_REMEMBERED))) delete entries[stale];
+	write(scope, entries);
+}
+/**
+* Forget it: the agent holds nothing resumable under this id.
+*
+* The other half of the agent deciding. Without it a swept upload is re-read on
+* every submission of the same file for the life of the tab, which is a round
+* trip spent learning the same 404.
+*
+* @internal
+*/
+function forgetUploadId(scope, file) {
+	const entries = read(scope);
+	const key = fingerprint(file);
+	if (!(key in entries)) return;
+	delete entries[key];
+	write(scope, entries);
+}
+//#endregion
+//#region _upload-session.ts
+/** Whether this rejection is an abort, in either of the two shapes runtimes throw. */
+function isAbortError(err) {
+	return err instanceof Error && err.name === "AbortError";
+}
+/** A fresh upload id: a capability, so it is random rather than derived. */
+function randomUploadId() {
+	return crypto.randomUUID().replaceAll("-", "");
+}
+/**
+* Send one file, waiting out however many pauses the person takes.
+*
+* The loop from the module doc, written once: both hooks need exactly this and a
+* second copy of it is a second place for the abort/pause distinction to be got
+* wrong. `send` is handed whether this attempt must CLAIM the id as its own —
+* false the first time, since a fresh id has nothing to resume and saying
+* otherwise waives the refusal that makes a caller-chosen id safe.
+*
+* Throws whatever `send` threw, except an abort the gate caused. A cancelled gate
+* throws too: the caller distinguishes it by reading `gate.cancelled`, which is
+* how an abandoned submission unwinds without being reported as a failure.
+*/
+async function sendThroughGate(gate, send) {
+	let tried = false;
+	for (;;) {
+		await gate.settle();
+		if (gate.cancelled) throw new Error("Upload cancelled.");
+		const resume = tried;
+		tried = true;
+		try {
+			await send(resume);
+			return;
+		} catch (err) {
+			if (gate.cancelled || !isAbortError(err)) throw err;
+		}
+	}
+}
+/**
+* A gate, open.
+*
+* One per upload rather than one per hook: the id and the windows already stored
+* belong to a file, so a gate that outlived its file would resume something else.
+*/
+function createUploadGate() {
+	let controller = new AbortController();
+	let paused = false;
+	let cancelled = false;
+	let open;
+	let closed;
+	return {
+		get paused() {
+			return paused;
+		},
+		get cancelled() {
+			return cancelled;
+		},
+		get signal() {
+			return controller.signal;
+		},
+		pause() {
+			if (paused || cancelled) return;
+			paused = true;
+			const gate = Promise.withResolvers();
+			closed = gate.promise;
+			open = gate.resolve;
+			controller.abort();
+		},
+		resume() {
+			if (!paused || cancelled) return;
+			paused = false;
+			controller = new AbortController();
+			open?.();
+			open = void 0;
+			closed = void 0;
+		},
+		cancel() {
+			if (cancelled) return;
+			cancelled = true;
+			paused = false;
+			controller.abort();
+			open?.();
+			open = void 0;
+			closed = void 0;
+		},
+		async settle() {
+			if (closed) await closed;
+		}
+	};
+}
+//#endregion
+//#region _workflow-files.ts
+/**
+* Which of a submitted form's values are FILES.
+*
+* Its own module because both submit hooks need the identical answer and then do
+* two different things with it — `useWorkflowSubmit` stores each file and passes
+* its id, `useWorkflowStream` cuts it into parts and passes the group they share.
+* A second copy of this predicate would be a form field that one hook treats as a
+* file and the other does not, which is invisible until the run reads the wrong
+* kind of string.
+*/
+/**
+* The files a submitted field carries, if that is what it carries.
+*
+* An array counts only when it is files ALL the way through — a mixed array is
+* some other field's value that happens to contain one, and turning half of it
+* into ids would corrupt it silently.
+*/
+function filesOf(value) {
+	if (value instanceof File) return [value];
+	if (!Array.isArray(value)) return [];
+	const files = value.filter((one) => one instanceof File);
+	return files.length > 0 && files.length === value.length ? files : [];
+}
+/**
+* The input properties still carrying a `File` — i.e. the ones that CANNOT survive
+* being sent.
+*
+* A run input is JSON, and `JSON.stringify(new File(…))` is `{}` — no `toJSON`, no
+* own enumerable properties. So a File left in a payload does not fail to send: it
+* arrives as an empty object, and the workflow rejects it against whatever its own
+* schema says the property should be. Measured in production as
+* `Invalid input for workflow "transcribe": recording: Invalid input` — a message
+* about a type, on a form where the user had picked a perfectly good file.
+*
+* Exported beside {@link filesOf} because it is the same question asked at the
+* other end: that one decides which fields to UPLOAD, this one checks that none
+* were missed. Both hooks are the callers.
+*/
+function fileFields(input) {
+	if (!isRecord(input)) return [];
+	return Object.entries(input).filter(([, value]) => filesOf(value).length > 0).map(([key]) => key);
+}
+//#endregion
+//#region _upload-files.ts
+/**
+* Turning a form's `File`s into stored upload ids, pauses and all.
+*
+* Split out of `use-workflow-form.ts` for the 500-line cap, and the seam is a
+* real one: that module is the two HOOKS and the state between them, where this
+* is the walk over a submitted input — which is the only part of it that knows
+* what a `File` is, holds a loop, and survives being re-entered.
+*
+* `_`-internal. `useWorkflowSubmit` is the only caller; `useWorkflowStream` sends
+* one file rather than walking an input and shares only the gate underneath both
+* (`_upload-session.ts`).
+*/
+/** A fresh session for one submission of `workflow`. */
+function createUploadSession(workflow) {
+	return {
+		scope: workflow,
+		ids: /* @__PURE__ */ new Map(),
+		stored: /* @__PURE__ */ new Map(),
+		tried: /* @__PURE__ */ new Set(),
+		gate: createUploadGate()
+	};
+}
+/**
+* The id to store this file under: the one a previous page load was using, or a
+* fresh one.
+*
+* **The AGENT decides, never the fingerprint.** Two files can agree on every
+* field `_upload-recall.ts` keys by, so the recalled id is a candidate that has to
+* be checked before a byte is sent to it — and the check is cheap and exact,
+* because `uploadInfo` is the same record a resume already reads.
+*
+* Three answers, and the third is why this is not just a storage lookup:
+*
+* - **Complete.** Every byte is in from a load that is gone, so there is nothing
+*   to send: the caller takes the id and starts the run. This is the refresh that
+*   costs one `GET` instead of a second 200 MB upload.
+* - **Unfinished, with windows.** `UploadInfo.ranges` is what makes an
+*   upload resumable at all, so the id is reused and the attempt claims it.
+* - **Anything else.** A 404 (swept, or never seen), a failure, or an unfinished
+*   upload reporting NO windows — which is a partial single `PUT`, and a second
+*   `PUT` to that id is a 409 rather than an append (`streamUploadFile`). Reusing
+*   it would turn a reload into a failure the person cannot clear, so the entry is
+*   dropped and the file gets a fresh id.
+*/
+async function claimId(api, session, file) {
+	const remembered = recallUploadId(session.scope, file);
+	if (remembered === void 0) return {
+		id: randomUploadId(),
+		complete: false
+	};
+	const info = await api.uploadInfo(remembered).catch(() => void 0);
+	if (info?.complete === true) return {
+		id: remembered,
+		complete: true
+	};
+	if (info !== void 0 && (info.ranges?.length ?? 0) > 0) {
+		session.tried.add(file);
+		return {
+			id: remembered,
+			complete: false
+		};
+	}
+	forgetUploadId(session.scope, file);
+	return {
+		id: randomUploadId(),
+		complete: false
+	};
+}
+/**
+* Replace every `File` in a submitted form with the id of a stored upload,
+* reporting how far each one has got.
+*
+* Sequential rather than `Promise.all`: these are large bodies, and a form with
+* two 200 MB recordings should send them one after another rather than compete
+* for the same connection. That is also what makes a single bar honest — one
+* file is in flight at a time, and `index`/`count` say which.
+*
+* Anything that is not a `File` (or an array of them) passes through untouched,
+* so this is invisible to every form that has none — including one whose values
+* are not an object at all, which `submit` accepts.
+*
+* ## `uploadStream`, not `upload`, and the id is the reason
+*
+* The difference between the two calls is only who mints the id — and that is
+* exactly what decides whether an interrupted upload can be picked up again. An
+* `upload` mints its own at the END and hands it back, so a caller whose upload
+* died has nothing to name what was stored and no choice but to send the file
+* again. A `uploadStream` is told the id up front, so the windows already in the
+* store are addressable, which is what both a pause and a server restart need.
+*
+* Nothing else about the submission changes: the run is still started after the
+* last byte lands, so the incomplete record a streamed upload leaves along the
+* way is one nobody reads.
+*/
+async function uploadFiles(api, input, report, parallel, session) {
+	if (!isRecord(input)) return input;
+	const entries = Object.entries(input);
+	const count = entries.reduce((total, [, value]) => total + filesOf(value).length, 0);
+	let index = 0;
+	const store = async (file) => {
+		index += 1;
+		const done = session.stored.get(file);
+		if (done !== void 0) return done;
+		const position = {
+			name: file.name,
+			index,
+			count
+		};
+		const known = session.ids.get(file);
+		const claimed = known === void 0 ? await claimId(api, session, file) : {
+			id: known,
+			complete: false
+		};
+		const id = claimed.id;
+		if (known === void 0) {
+			session.ids.set(file, id);
+			rememberUploadId(session.scope, file, id);
+		}
+		if (claimed.complete) {
+			report({
+				...position,
+				loaded: file.size,
+				total: file.size,
+				fraction: 1,
+				paused: false
+			});
+			session.stored.set(file, id);
+			return id;
+		}
+		await sendThroughGate(session.gate, async (resume) => {
+			await api.uploadStream(id, file, {
+				name: file.name,
+				signal: session.gate.signal,
+				onProgress: (progress) => report({
+					...position,
+					...progress,
+					paused: session.gate.paused
+				}),
+				...omitUndefined({
+					parallel,
+					resume: resume || session.tried.has(file) ? true : void 0
+				})
+			});
+		});
+		session.stored.set(file, id);
+		return id;
+	};
+	const out = {};
+	for (const [name, value] of entries) {
+		if (value instanceof File) {
+			out[name] = await store(value);
+			continue;
+		}
+		const chosen = filesOf(value);
+		if (chosen.length === 0) {
+			out[name] = value;
+			continue;
+		}
+		const ids = [];
+		for (const file of chosen) ids.push(await store(file));
+		out[name] = ids;
+	}
+	return out;
+}
+//#endregion
 //#region workflow-client.ts
 /**
 * Create a workflow API client aimed at the agent serving this page.
@@ -720,50 +1166,6 @@ function useWorkflowApiRef(api) {
 	}, []);
 }
 //#endregion
-//#region _workflow-files.ts
-/**
-* Which of a submitted form's values are FILES.
-*
-* Its own module because both submit hooks need the identical answer and then do
-* two different things with it — `useWorkflowSubmit` stores each file and passes
-* its id, `useWorkflowStream` cuts it into parts and passes the group they share.
-* A second copy of this predicate would be a form field that one hook treats as a
-* file and the other does not, which is invisible until the run reads the wrong
-* kind of string.
-*/
-/**
-* The files a submitted field carries, if that is what it carries.
-*
-* An array counts only when it is files ALL the way through — a mixed array is
-* some other field's value that happens to contain one, and turning half of it
-* into ids would corrupt it silently.
-*/
-function filesOf(value) {
-	if (value instanceof File) return [value];
-	if (!Array.isArray(value)) return [];
-	const files = value.filter((one) => one instanceof File);
-	return files.length > 0 && files.length === value.length ? files : [];
-}
-/**
-* The input properties still carrying a `File` — i.e. the ones that CANNOT survive
-* being sent.
-*
-* A run input is JSON, and `JSON.stringify(new File(…))` is `{}` — no `toJSON`, no
-* own enumerable properties. So a File left in a payload does not fail to send: it
-* arrives as an empty object, and the workflow rejects it against whatever its own
-* schema says the property should be. Measured in production as
-* `Invalid input for workflow "transcribe": recording: Invalid input` — a message
-* about a type, on a form where the user had picked a perfectly good file.
-*
-* Exported beside {@link filesOf} because it is the same question asked at the
-* other end: that one decides which fields to UPLOAD, this one checks that none
-* were missed. Both hooks are the callers.
-*/
-function fileFields(input) {
-	if (!isRecord(input)) return [];
-	return Object.entries(input).filter(([, value]) => filesOf(value).length > 0).map(([key]) => key);
-}
-//#endregion
 //#region _repeat-until.ts
 /**
 * A bounded read, re-armed from the SETTLED read — the loop both workflow
@@ -1170,56 +1572,6 @@ function useWorkflows(opts = {}) {
 	return state;
 }
 /**
-* Replace every `File` in a submitted form with the id of a stored upload,
-* reporting how far each one has got.
-*
-* Sequential rather than `Promise.all`: these are large bodies, and a form with
-* two 200 MB recordings should send them one after another rather than compete
-* for the same connection. That is also what makes a single bar honest — one
-* file is in flight at a time, and `index`/`count` say which.
-*
-* Anything that is not a `File` (or an array of them) passes through untouched,
-* so this is invisible to every form that has none — including one whose values
-* are not an object at all, which `submit` accepts.
-*/
-async function uploadFiles(api, input, report, parallel) {
-	if (!isRecord(input)) return input;
-	const entries = Object.entries(input);
-	const count = entries.reduce((total, [, value]) => total + filesOf(value).length, 0);
-	let index = 0;
-	const store = async (file) => {
-		index += 1;
-		const position = {
-			name: file.name,
-			index,
-			count
-		};
-		return (await api.upload(file, {
-			onProgress: (progress) => report({
-				...position,
-				...progress
-			}),
-			...omitUndefined({ parallel })
-		})).id;
-	};
-	const out = {};
-	for (const [name, value] of entries) {
-		if (value instanceof File) {
-			out[name] = await store(value);
-			continue;
-		}
-		const chosen = filesOf(value);
-		if (chosen.length === 0) {
-			out[name] = value;
-			continue;
-		}
-		const ids = [];
-		for (const file of chosen) ids.push(await store(file));
-		out[name] = ids;
-	}
-	return out;
-}
-/**
 * Start a workflow from a form, and follow the run it creates.
 *
 * @typeParam R - The workflow's output type, which is what makes
@@ -1250,6 +1602,7 @@ function useWorkflowSubmit(workflow, opts = {}) {
 	const [starting, setStarting] = useState(false);
 	const [startError, setStartError] = useState(void 0);
 	const [upload, setUpload] = useState(void 0);
+	const session = useRef(void 0);
 	const getClient = useWorkflowApiRef(api);
 	const tracked = useWorkflowRun(runId, omitUndefined({
 		api,
@@ -1261,18 +1614,24 @@ function useWorkflowSubmit(workflow, opts = {}) {
 			setStarting(true);
 			setStartError(void 0);
 			setRunId(void 0);
+			session.current?.gate.cancel();
+			const current = createUploadSession(workflow);
+			session.current = current;
 			try {
 				const options = omitUndefined({ key });
-				const started = await uploadFiles(client, input, setUpload, parallel);
+				const started = await uploadFiles(client, input, setUpload, parallel, current);
 				setRunId(wait === void 0 ? await client.start(workflow, started, options) : (await client.startAndWait(workflow, started, {
 					...options,
 					wait
 				})).runId);
 			} catch (err) {
-				setStartError(errorMessage(err));
+				if (!current.gate.cancelled) setStartError(errorMessage(err));
 			} finally {
-				setStarting(false);
-				setUpload(void 0);
+				if (session.current === current) {
+					session.current = void 0;
+					setStarting(false);
+					setUpload(void 0);
+				}
 			}
 		}, [
 			workflow,
@@ -1282,10 +1641,26 @@ function useWorkflowSubmit(workflow, opts = {}) {
 			getClient
 		]),
 		reset: useCallback(() => {
+			session.current?.gate.cancel();
+			session.current = void 0;
 			setRunId(void 0);
 			setStartError(void 0);
 			setUpload(void 0);
 		}, []),
+		pauseUpload: useCallback(() => {
+			session.current?.gate.pause();
+			setUpload((current) => current ? {
+				...current,
+				paused: true
+			} : current);
+		}, []),
+		resumeUpload: useCallback(() => {
+			session.current?.gate.resume();
+			setUpload((current) => current ? {
+				...current,
+				paused: false
+			} : current);
+		}, []),
 		run: tracked.run,
 		pending: starting || tracked.polling,
 		upload,
@@ -1944,18 +2319,33 @@ function useWorkflowRuns(workflow, opts = {}) {
 * - **Reporting the bytes.** The same `UploadStatus` `useWorkflowSubmit` reports,
 *   so `<UploadProgressBar>` renders either without knowing which hook it came from.
 *
-* ## A failed upload is RESUMED once, and only then cancels the run
+* ## A failed upload is RESUMED, and only a spent budget cancels the run
 *
 * An upload that dies stays in the store, incomplete, and `complete` never becomes
 * true — so a run left behind polls until its own abandonment bound and then fails,
 * minutes after the page has already reported the error.
 *
 * That used to be the whole story, and it threw away a run and a file together for
-* what is usually one dropped connection near the end. So a failure gets one more
-* attempt with `resume: true`, which sends only the windows the store does not
-* already have (`UploadInfo.ranges`) — the run is still waiting on the same id, so
-* a resume that succeeds is invisible to it. Cancelling is what happens when THAT
-* fails too, and it is the honest end to a submission that did not happen.
+* what is usually one dropped connection near the end. **The resume lives in the
+* SDK now** (`aai/sdk/_upload-resume.ts`): a round that fails for a reason that
+* looks like an outage is re-entered with `resume: true`, sending only the windows
+* the store does not already have, on a budget sized to outlast a redeploy. The run
+* is still waiting on the same id, so a resume that succeeds is invisible to it.
+*
+* This hook used to hand-roll one such retry and no longer does — one resume with
+* no wait in front of it covers a dropped connection and cannot cover the case that
+* actually strands people, which is the agent restarting underneath the upload.
+* Cancelling the run is what happens when the whole budget is spent, and it is the
+* honest end to a submission that did not happen.
+*
+* ## Pausing is the same mechanism, asked for
+*
+* `pauseUpload()` aborts the bytes in flight and holds the uploader;
+* `resumeUpload()` sends what is missing. The store cannot tell that from an
+* outage, because there is nothing to tell apart — see `_upload-session.ts`. The
+* RUN is untouched either way: it goes on polling the id it was started with, and
+* `stream.ts`'s idle bound (five minutes of no new bytes) is what decides that a
+* pause has become an abandonment.
 */
 /**
 * Start a workflow run and stream a file into it while it works.
@@ -1988,6 +2378,7 @@ function useWorkflowStream(workflow, opts = {}) {
 	const [starting, setStarting] = useState(false);
 	const [startError, setStartError] = useState(void 0);
 	const [upload, setUpload] = useState(void 0);
+	const gateRef = useRef(void 0);
 	const getClient = useWorkflowApiRef(api);
 	const tracked = useWorkflowRun(runId, omitUndefined({
 		api,
@@ -1999,42 +2390,41 @@ function useWorkflowStream(workflow, opts = {}) {
 			setStarting(true);
 			setStartError(void 0);
 			setRunId(void 0);
+			gateRef.current?.cancel();
+			const gate = createUploadGate();
+			gateRef.current = gate;
 			let started;
 			try {
-				const field = await uploadField(client, workflow);
-				const chosen = field === void 0 ? void 0 : fileAt(input, field);
 				const id = randomUploadId();
-				const payload = chosen && field ? {
-					...input,
-					[field]: id
-				} : input;
-				assertSendable(workflow, payload, field);
-				started = await client.start(workflow, payload, omitUndefined({ key }));
+				const begun = await beginRun({
+					client,
+					workflow,
+					input,
+					id,
+					...omitUndefined({ key })
+				});
+				started = begun.runId;
+				const chosen = begun.file;
 				setRunId(started);
 				if (!chosen) return;
-				const send = async (resume) => {
-					await client.uploadStream(id, chosen, {
-						name: chosen.name,
-						onProgress: (progress) => setUpload({
-							...progress,
-							name: chosen.name,
-							index: 1,
-							count: 1
-						}),
-						...omitUndefined({
-							parallel,
-							resume: resume ? true : void 0
-						})
-					});
-				};
-				await send(false).catch(async () => await send(true));
+				await streamFile({
+					client,
+					gate,
+					id,
+					file: chosen,
+					parallel,
+					report: setUpload
+				});
 				await client.wake(started).catch(() => void 0);
 			} catch (err) {
-				setStartError(errorMessage(err));
+				if (!gate.cancelled) setStartError(errorMessage(err));
 				if (started) await client.cancel(started).catch(() => void 0);
 			} finally {
-				setStarting(false);
-				setUpload(void 0);
+				if (gateRef.current === gate) {
+					gateRef.current = void 0;
+					setStarting(false);
+					setUpload(void 0);
+				}
 			}
 		}, [
 			workflow,
@@ -2043,10 +2433,26 @@ function useWorkflowStream(workflow, opts = {}) {
 			getClient
 		]),
 		reset: useCallback(() => {
+			gateRef.current?.cancel();
+			gateRef.current = void 0;
 			setRunId(void 0);
 			setStartError(void 0);
 			setUpload(void 0);
 		}, []),
+		pauseUpload: useCallback(() => {
+			gateRef.current?.pause();
+			setUpload((current) => current ? {
+				...current,
+				paused: true
+			} : current);
+		}, []),
+		resumeUpload: useCallback(() => {
+			gateRef.current?.resume();
+			setUpload((current) => current ? {
+				...current,
+				paused: false
+			} : current);
+		}, []),
 		run: tracked.run,
 		pending: starting || tracked.polling,
 		upload,
@@ -2054,6 +2460,56 @@ function useWorkflowStream(workflow, opts = {}) {
 	};
 }
 /**
+* Read the declaration, substitute the id, and start the run.
+*
+* Everything that has to happen BEFORE a byte moves, which is the inversion this
+* hook exists for. One small `list()` per submit, deliberately: holding the
+* listing in state would make a submit before it landed a race, and the failure
+* mode of that race is a `File` reaching a run input.
+*/
+async function beginRun(opts) {
+	const { client, workflow, input, id } = opts;
+	const field = await uploadField(client, workflow);
+	const chosen = field === void 0 ? void 0 : fileAt(input, field);
+	const payload = chosen && field ? {
+		...input,
+		[field]: id
+	} : input;
+	assertSendable(workflow, payload, field);
+	return {
+		runId: await client.start(workflow, payload, omitUndefined({ key: opts.key })),
+		file: chosen
+	};
+}
+/**
+* Send the file, waiting out however many pauses the person takes.
+*
+* Its own function rather than a block inside `submit` because `submit` is
+* already carrying the ORDER this hook exists for — read the declaration, mint
+* the id, start the run, then the bytes, then the wake — and the sending is the
+* one step of that list with a loop in it.
+*/
+async function streamFile(opts) {
+	const { client, gate, id, file, parallel, report } = opts;
+	await sendThroughGate(gate, async (resume) => {
+		await client.uploadStream(id, file, {
+			name: file.name,
+			signal: gate.signal,
+			onProgress: (progress) => report({
+				...progress,
+				name: file.name,
+				index: 1,
+				count: 1,
+				paused: gate.paused
+			}),
+			...omitUndefined({
+				parallel,
+				resume: resume ? true : void 0
+			})
+		});
+	});
+}
+/**
 * Refuse a payload carrying a `File`, before a run is started over it.
 *
 * A File cannot be SENT: a run input is JSON and `JSON.stringify(new File(…))` is
@@ -2080,10 +2536,6 @@ function assertSendable(workflow, payload, field) {
 	const declares = field === void 0 ? "" : ` (it declares "${field}")`;
 	throw new Error(`Cannot start "${workflow}": ${unsendable.join(", ")} ${carries} the workflow does not declare as an upload${declares}. Add the property to \`workflow({ uploads: [...] })\`, or submit an upload id.`);
 }
-/** A fresh upload id: a capability, so it is random rather than derived. */
-function randomUploadId() {
-	return crypto.randomUUID().replaceAll("-", "");
-}
 /**
 * Which input property this workflow says carries an upload id.
 *