@alexkroman1/aai-ui 0.12.3 → 0.14.0

package/README.md

@@ -0,0 +1,253 @@
+# @alexkroman1/aai-ui
+
+The browser client for AssemblyAI Agent SDK agents: React 19 hooks and
+components over a framework-agnostic session core (WebSocket + microphone +
+playback).
+
+```sh
+npm i @alexkroman1/aai-ui react react-dom
+```
+
+Every agent gets this UI for free — `aai dev` and deployed agents serve a
+default client built from this package. Install it directly when the agent has
+its own `client.tsx`.
+
+## UI integration
+
+The hooks here are what a page reads an agent with: the live call, the state the
+agent projects, the tool calls as they run, and the durable runs it started.
+**There is no route to write.** The agent server already serves the session
+socket and the workflow HTTP API, so a component talks to a live agent with no
+glue file in between — a client is one `client.tsx` calling one mount.
+
+**Two front doors, two mounts.** A voice agent's page calls `mountClient()` and
+talks to a live session. A workflow app's page (`workflowApp()`, or
+`agent({ mode: "workflow-app" })`) calls `mountPage()` and talks to the workflow
+HTTP API — no session, no socket, no microphone. Both are still `client.tsx`,
+still React, still the same theme tokens.
+
+### Agent `agent.ts`
+
+The session's state lives in a slot, and `syncState` is what the browser sees —
+pushed after every tool call, so the client never rebuilds it from events:
+
+```ts
+import { agent, sessionSlot } from "@alexkroman1/aai";
+
+const desk = sessionSlot("desk", () => ({ symbols: [] as string[] }), {
+  view: (state) => ({ symbols: state.symbols }),
+});
+
+export default agent({
+  name: "Market Desk",
+  systemPrompt: "You look up quotes and keep the caller's watchlist.",
+  syncState: desk.projected,
+});
+```
+
+### Tool `tools/get_quote.ts`
+
+A tool is a **file**, named by its own filename. Nothing registers it, and
+`agent()` takes no `tools` field:
+
+```ts
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+
+export default tool({
+  description: "Look up the latest price for one ticker symbol",
+  inputSchema: z.object({ symbol: z.string() }),
+  execute: async ({ symbol }, ctx) => {
+    const res = await fetch(`https://api.example.com/quote/${symbol}`, {
+      headers: { authorization: `Bearer ${ctx.env.QUOTES_API_KEY}` },
+      signal: ctx.signal,
+    });
+    return (await res.json()) as { symbol: string; price: number };
+  },
+});
+```
+
+### UI component for a tool `quote-card.tsx`
+
+`useToolResult` fires once per settled call of one named tool, with the result
+already parsed. A component that mounts late still receives the results of calls
+that finished before it — a result is a value the UI is driven from, not a
+moment:
+
+```tsx
+import { useState } from "react";
+import { useToolResult } from "@alexkroman1/aai-ui";
+
+type Quote = { symbol: string; price: number };
+
+export default function QuoteCard() {
+  const [quote, setQuote] = useState<Quote>();
+  useToolResult<Quote>("get_quote", (result) => setQuote(result));
+
+  if (!quote) return null;
+  return (
+    <p>
+      {quote.symbol} — {quote.price.toFixed(2)}
+    </p>
+  );
+}
+```
+
+`useToolCallStart` is the same hook for the other end of the call — the pending
+invocation and its arguments, for a spinner rather than a value. Either one
+takes the tool's own shape as a type argument, derived from the tool module by a
+**type-only** import that is erased and so pulls no server code into the bundle:
+`useToolResult<InferToolOutput<typeof getQuote>>(…)` for the result,
+`useToolCallStart<InferToolInput<typeof getQuote>>(…)` for the arguments.
+
+### Client `client.tsx`
+
+`mountClient()` mounts the default chat shell — start screen, transcript,
+controls — with your components in it. `sidebar` takes the COMPONENT, not an
+element:
+
+```tsx no-check
+import "@alexkroman1/aai-ui/styles.css";
+import { mountClient, useAgentState } from "@alexkroman1/aai-ui";
+import QuoteCard from "./quote-card.tsx";
+
+function Watchlist() {
+  // The `desk` slot `syncState` projected, live. Null until the first push,
+  // which is a moment the UI has to render.
+  const desk = useAgentState<{ symbols: string[] }>("desk");
+  return (
+    <div>
+      <QuoteCard />
+      {desk?.symbols.map((symbol) => <div key={symbol}>{symbol}</div>)}
+    </div>
+  );
+}
+
+mountClient({
+  name: "Market Desk",
+  sidebar: Watchlist,
+  // Icon and label per tool, for the transcript's tool rows.
+  tools: { get_quote: { icon: "📈", label: "Fetching quote" } },
+  theme: { primary: "#2f9e44" },
+});
+```
+
+The type argument above restates a shape the agent already knows. Move the slot
+and its projection into a `shared.ts` both ends import, pass the projection
+itself — `useAgentState(deskProjection)` — and the state is typed from the
+projection and the pre-first-push frame derived from it, so there is nothing to
+restate and no branch for the first render.
+
+Pass `component` instead of `sidebar` to replace the whole shell. It renders
+inside the same providers, so every hook here works in it unchanged.
+
+## A workflow app
+
+`mountPage()` mounts a form over the agent's workflows and installs no session.
+`<WorkflowFields>` renders one control per scalar property of the workflow's own
+input schema, so adding a field to the schema adds it to the page:
+
+```tsx
+import "@alexkroman1/aai-ui/styles.css";
+import {
+  Form,
+  mountPage,
+  SubmitButton,
+  UploadProgressBar,
+  useWorkflowSubmit,
+  WorkflowFields,
+  WorkflowProgress,
+} from "@alexkroman1/aai-ui";
+
+function App() {
+  const { submitForm, run, pending, upload, error } =
+    useWorkflowSubmit("digest");
+  return (
+    <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
+      <Form onSubmit={submitForm} error={error}>
+        <WorkflowFields workflow="digest" />
+        <SubmitButton pending={pending}>Summarize</SubmitButton>
+      </Form>
+      {/* The upload is its own wait: the run does not exist until the bytes
+          are in, so nothing else on the page can describe it. */}
+      <UploadProgressBar upload={upload} />
+      {/* What the run has SAID, from `stepReport()` in its steps. */}
+      <WorkflowProgress runId={run?.runId} />
+      {run?.status === "completed" && <pre>{JSON.stringify(run.output)}</pre>}
+    </main>
+  );
+}
+
+mountPage({ name: "Digest", component: App });
+```
+
+Naming the workflow's def — `useWorkflowSubmit<typeof digest>("digest")`, off a
+**type-only** import of `agent.ts` — is what makes `submit()` take the declared
+input and `run.status === "completed"` narrow to a typed `run.output`. The
+import is erased, so it pulls no server code into the bundle.
+
+## What is in the package
+
+The [API reference](https://alexkroman.github.io/agent/) groups by TypeScript
+kind. This is the same surface grouped by what it is for.
+
+**Mounts** — `mountClient()`, `mountPage()`, the config each takes and the
+handle each returns (`ClientConfig`, `ClientHandle`, `PageConfig`,
+`PageHandle`). `fetchClientConfig()` reads the agent's declared
+`name`/`greeting` on a page, which `mountClient()` does for itself.
+
+**The live call** — `useSession()` for the whole snapshot plus the controls
+(`start`, `toggle`, `cancel`, `reset`, `resetState`, `restart`, `disconnect`,
+`end`); `useSessionSelector()` for one slice, with `useSessionStatus()`,
+`useSessionError()` and `useSessionActions()` as the narrow reads a custom
+chrome repeats; `useUserTranscript()` for the caller's in-progress turn, which
+keeps `null` (silent) and `""` (speech, no words yet) apart; `useConversation()`
+for the interleaved transcript with nothing rendered. `createBrowserSession()`
+is the same session as a plain store with an immutable snapshot per change, for
+a non-React client. `SessionSnapshot`, `AgentState`, `ChatMessage`,
+`ToolCallInfo`, `SessionError` and `SessionErrorCode` come with it.
+
+**What the agent pushes** — `useAgentState(slot.projected)` (that slot's entry
+in the agent's `syncState`; `selectAgentState(slot)` for `useSessionSelector`),
+`useToolResult()` / `useToolCallStart()` (tool calls as they run), and
+`useEvent()` (custom events from `ctx.send`, and the one to prefer in new code
+over reading tool results).
+
+**Chat chrome** — `ChatView` is the whole surface; `ConsoleShell`,
+`MessageList`, `Controls`, `Markdown`, `ToolCallRow`, `SessionErrorBanner`,
+`StartScreen`, `SidebarLayout`, `AutoScroll`, `BulletList`, `Facts` and `Button`
+are its parts, exported so a custom chrome reuses them rather than approximating
+them. `AutoScroll` is the one to reach for directly: it is the only
+scroll-pinning implementation here, and it needs a **bounded height**.
+`AGENT_STATE_LABELS` and `WORKFLOW_STATUS_LABELS` are the default state words,
+so a chrome overrides the one term it has a better word for.
+
+**Forms** — `Form` collects typed values off the DOM on submit. `Field`,
+`TextField`, `NumberField`, `TextAreaField`, `SelectField`, `CheckboxField`,
+`FileField` and `SubmitButton` are the controls; `WorkflowFields` generates them
+from a schema. A plain `<input name="x">` works identically.
+
+**Workflows** — `createWorkflowApi()` is the client; `useWorkflowSubmit()` /
+`useWorkflowStream()` (start one and watch it), `useWorkflowRun()` (watch one by
+id), `useWorkflowRuns()` (the history), `useWorkflowProgress()` (what a run has
+written), `useWorkflows()` (the listing), `useDownloadUrl()` (an upload a run
+produced, as a URL a DOM element accepts), `useRunKey()` (the storage-backed key
+a submission is recovered by). `<WorkflowProgress>` and `<UploadProgressBar>`
+are the rendered halves. `WorkflowRun`, `WorkflowSummary`, `WorkflowInputOf`,
+`WorkflowOutputOf` and `isTerminal()` are the vocabulary.
+
+**Theme** — `useTheme()` and `ClientTheme`.
+
+## Other subpaths
+
+The root export is the whole client API. Two subpaths sit beside it, neither of
+them something a `client.tsx` reaches for:
+
+| Subpath       | Reach for it when                                                                                                                                                                                                                               |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/client-dir` | serving the prebuilt default client from Node — `defaultClientDir()`, the filesystem path `createServerForRuntime({ clientDir })` wants                                                                                                         |
+| `/internal`   | never, from application code: the plumbing `mountClient()` installs for itself (the session and theme providers, the default shell's URL chips, the tool-config context, the pre-connection lookup). Not a public API and not covered by semver |
+
+## Documentation
+
+Full API reference: <https://alexkroman.github.io/agent/>

package/dist/_colors-CpZO-88A.js

@@ -0,0 +1,78 @@
+//#region src/components/_colors.ts
+/**
+* Shared tints used by the default components (AssemblyAI design system,
+* "website refresh": warm neutrals over the cream/white surfaces).
+*
+* These sit on top of the {@link ClientTheme} colors, which own the opaque
+* palette. The neutral text steps are **derived from the theme** rather than
+* hardcoded: `ClientTheme` documents `bg`/`surface`/`text` as free-form
+* colors, so a client is free to hand the components a dark ground — and a
+* fixed warm-grey scale tuned for cream leaves the AGENT/TOOL labels, every
+* tool-call args preview, the chevron and both URL chips below WCAG AA while
+* the prose and bubbles around them follow the theme correctly. Measured on a
+* plausible dark theme before this was derived: 14 text nodes under 4.5:1
+* (the faint step at 3.2–3.5:1, the muted step at 2.5:1), against zero on the
+* default light theme.
+*
+* `ERROR_COLOR` and `THINKING_COLOR` stay fixed: they are *semantic* colors
+* whose hue carries the meaning, so they cannot be re-derived from a theme
+* that knows nothing about severity.
+*/
+/**
+* Blend `text` into `surface` by `pct`, giving a neutral step that stays on
+* the theme's own ink/ground axis. On a light theme this walks *down* from
+* the surface toward the ink; on a dark one it walks *up* from the ground
+* toward the light ink — the same call reads correctly either way, which is
+* the whole reason to derive rather than hardcode.
+*/
+function inkTint(text, surface, pct) {
+	return mixInto(text, surface, pct);
+}
+/** Error red tuned for warm light surfaces. */
+const ERROR_COLOR = "#B3261E";
+/** Amber used by the "thinking" state indicator. */
+const THINKING_COLOR = "#B98900";
+/**
+* Derive the user-bubble fill/edge from the theme primary (the mock's
+* indigo-50 background with an indigo-100 border), so custom themes keep a
+* coherent tinted bubble instead of a hardcoded indigo.
+*/
+function primaryTint(primary, surface, pct) {
+	return mixInto(primary, surface, pct);
+}
+/**
+* The blend itself — `pct` of `color` over `ground`, in sRGB.
+*
+* One definition rather than one per axis: {@link inkTint} and
+* {@link primaryTint} differ in WHICH theme color they walk from, which is what
+* their names carry, and not in how the walk is spelled. Two copies of the
+* `color-mix()` string are two places a change of color space has to land.
+*/
+function mixInto(color, ground, pct) {
+	return `color-mix(in srgb, ${color} ${pct}%, ${ground})`;
+}
+/**
+* The focus ring, as the class half of a pair.
+*
+* The ring is the only thing a keyboard user gets, and it has regressed to
+* invisible twice — `outline-none` shipped here with no replacement, on the
+* button and then on the URL chips, which is WCAG 2.4.7 on every control in the
+* default client. Written as a SHORTHAND so it cannot be undone by Tailwind's
+* shared `--tw-outline-style` variable.
+*
+* It is inert on its own: an outline with no colour draws nothing, so a control
+* using this must also spread {@link focusRingStyle}. Naming the two together
+* is what stops the next control shipping one without the other.
+*/
+const FOCUS_RING = "outline-none focus-visible:[outline:2px_solid] focus-visible:[outline-offset:2px]";
+/**
+* The style half of {@link FOCUS_RING} — the colour the outline draws in.
+*
+* A real CSS property rather than a variant class, so the `focus-visible` rule
+* only has to turn the outline on.
+*/
+function focusRingStyle(primary) {
+	return { outlineColor: primary };
+}
+//#endregion
+export { inkTint as a, focusRingStyle as i, FOCUS_RING as n, primaryTint as o, THINKING_COLOR as r, ERROR_COLOR as t };

package/dist/_module-url-C13kAJ87.js

@@ -0,0 +1,15 @@
+//#region src/worklets/_module-url.ts
+/**
+* Blob-URL module for an inlined AudioWorklet processor source.
+*
+* A blob URL rather than a data URI because the agent page's CSP allows
+* `script-src blob:` but not `data:` — a data-URI module fails `addModule`
+* with the opaque "Unable to load a worklet's module". Every inline worklet
+* in this package must load through this helper so that constraint lives in
+* one place.
+*/
+function workletModuleUrl(source) {
+	return URL.createObjectURL(new Blob([source], { type: "application/javascript" }));
+}
+//#endregion
+export { workletModuleUrl as t };

package/dist/_page-shell.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from "react";
+/**
+ * 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.
+ */
+export declare function DefaultPageShell({ name }: {
+    name?: string | undefined;
+}): ReactNode;

package/dist/_recover-run.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ */
+import type { WorkflowApi } from "./workflow-client.ts";
+/** What {@link useRecoveredRun} needs. */
+export type RecoverRunOptions = {
+    /** The workflow whose runs are indexed under `key`. */
+    workflow: string;
+    /** The caller's handle on its own run. `useDefaultRunKey` always supplies one. */
+    key: string;
+    /** Whether the caller asked for this at all — `recover` at the call site. */
+    enabled: boolean;
+    /** The stable getter from `useWorkflowApiRef`. */
+    getClient: () => WorkflowApi;
+    /** Adopt this run. Called at most once, and never with an empty answer. */
+    onFound: (runId: string) => void;
+    /** The lookup failed, and the page has to say so. */
+    onError: (message: string) => void;
+};
+/**
+ * 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
+ */
+export declare function useRecoveredRun(opts: RecoverRunOptions): boolean;

package/dist/_repeat-until.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A bounded read, re-armed from the SETTLED read — the loop both workflow
+ * watchers are built out of.
+ *
+ * `pollUntilTerminal` (`use-workflow-run.ts`) and `readProgressUntilComplete`
+ * (`use-workflow-progress.ts`) each open a request, decide from its answer
+ * whether to come back, and stop when told to. What they had in common was not
+ * the decision — one reads a snapshot, the other drains an SSE body — but the
+ * scaffold around it, and that scaffold is where the two rules live:
+ *
+ * - **Re-armed from the settled read, never on an interval.** A slow response
+ *   would otherwise stack overlapping requests on an agent that is already
+ *   struggling, and on the platform every one of them BROKERS.
+ * - **Cancellation is a signal, not a flag.** The teardown has to reach the
+ *   in-flight request too — an abandoned progress read otherwise keeps pulling
+ *   chunks out of a run for a page that has navigated away — so `step` is
+ *   handed the signal rather than being trusted to check a boolean.
+ */
+/**
+ * Call `step` until it reports it is finished, or until the returned stop
+ * function is called.
+ *
+ * `step` resolves `true` when there is nothing left to come back for. It is
+ * responsible for its own failures: a rejection would leave the loop stopped
+ * with nobody told, so each caller decides whether its failure is terminal or
+ * just another reason to try again.
+ *
+ * @internal
+ */
+export declare function repeatUntil(intervalMs: number, step: (signal: AbortSignal) => Promise<boolean>): () => void;

package/dist/_run-controls.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+import type { WorkflowApi } from "./workflow-client.ts";
+/** What {@link useRunControls} returns — see {@link WorkflowSubmission}. */
+export type RunControls = {
+    /** End the run's `sleep()` early; resolves how many sleeps it interrupted. */
+    wake: () => Promise<number>;
+    /** Stop the run; resolves whether this call is what ended it. */
+    cancel: () => Promise<boolean>;
+};
+/**
+ * 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
+ */
+export declare function useRunControls(runId: string | undefined, getClient: () => WorkflowApi): RunControls;

package/dist/_submission-state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The state a form submission carries, for both hooks that make one.
+ *
+ * `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 was written
+ * twice: the same four `useState`s, the same ref holding the live submission,
+ * the same prologue, the same superseded-submission guard, the same `reset`,
+ * and the same pause pair. Roughly forty-five lines and thirty of comment.
+ *
+ * The copy had already diverged in ways nobody chose, which is the argument for
+ * this module rather than for tidiness. What is here is only the scaffold; each
+ * hook still owns its own `submit` body.
+ *
+ * ## The superseded-submission rule
+ *
+ * A submission that has been replaced owns none of this state any more. Its
+ * walk unwinds AFTER the next one has already set `starting`, so clearing
+ * unconditionally in a `finally` would report the live submission as finished
+ * and drop the bar it is drawing. {@link SubmissionState.end} is that check,
+ * made once here instead of at each hook's own `finally`.
+ */
+import type { Dispatch, SetStateAction } from "react";
+import type { UploadGate } from "./upload/index.ts";
+import type { UploadStatus } from "./use-workflow-form.ts";
+/**
+ * What a hook installs as its live submission.
+ *
+ * Generic over the token because the two hooks hold different things —
+ * `useWorkflowSubmit` an `UploadSession` (the walk needs its id maps),
+ * `useWorkflowStream` a bare gate in a wrapper — and all this module needs from
+ * either is the gate, which is what a supersede and a `reset` cancel.
+ */
+export type SubmissionToken = {
+    gate: UploadGate;
+};
+/**
+ * The stable half: everything a `submit` body calls.
+ *
+ * Split from the values deliberately. A `submit` is a `useCallback` and this is
+ * one of its dependencies, so a bag that changed identity whenever `upload`
+ * changed would rebuild `submit` — and with it the `onSubmit` handed to
+ * `<Form>` — on every progress report. Every member here is a `useState`
+ * setter or a `useCallback` with no changing dependency, so the bag is stable
+ * for the component's life.
+ */
+export type SubmissionActions<S extends SubmissionToken> = {
+    /**
+     * The full dispatch, not a plain setter: `useWorkflowSubmit`'s recovery
+     * lookup writes `(current) => current ?? found`, so that a run the person has
+     * already started this session is never displaced by one read back from the
+     * key index.
+     */
+    setRunId: Dispatch<SetStateAction<string | undefined>>;
+    setStartError: Dispatch<SetStateAction<string | undefined>>;
+    setUpload: Dispatch<SetStateAction<UploadStatus | undefined>>;
+    /**
+     * Open a submission: supersede whatever was in flight and install `token`.
+     *
+     * Cancels the previous gate first, so a stale submission cannot park the new
+     * one, and clears the previous run id BEFORE the request rather than when it
+     * returns — a finished result sitting under a form that is already submitting
+     * again is the one wrong answer this can give, and it looks like a right one.
+     */
+    begin: (token: S) => void;
+    /**
+     * Close `token`, if it is still the live one. See "The superseded-submission
+     * rule" above.
+     */
+    end: (token: S) => void;
+    /** Put the form back: abandon the bytes and drop the result. */
+    reset: () => void;
+    /** Park the bytes and say so on the bar. */
+    pauseUpload: () => void;
+    /** Send the rest. */
+    resumeUpload: () => void;
+};
+/** What {@link useSubmissionState} hands back. */
+export type SubmissionState<S extends SubmissionToken> = {
+    /** The run this submission started, once it has one. */
+    runId: string | undefined;
+    /** Whether a submission is in flight — the POST and the bytes, not the run. */
+    starting: boolean;
+    /** The submission's own failure, as against the run's. */
+    startError: string | undefined;
+    /** The bar's state, or nothing when there is no upload to describe. */
+    upload: UploadStatus | undefined;
+    /** See {@link SubmissionActions} for why these are their own bag. */
+    actions: SubmissionActions<S>;
+};
+/** The shared submission scaffold. See the module doc. */
+export declare function useSubmissionState<S extends SubmissionToken>(): SubmissionState<S>;