@alexkroman1/aai-ui 13.3.0 → 14.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @alexkroman1/aai-ui
 
-The browser client for aai agents: React 19 components, hooks, and a
+The browser client for aai agents: React 19 hooks and components over a
 framework-agnostic session core (WebSocket + microphone + playback).
 
 ```sh
@@ -11,64 +11,156 @@ 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`.
 
-**Two front doors, two mounts.** A voice agent's page calls `client()` and
+## 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({ page: "static" })`) calls `page()` and talks to the workflow HTTP
+`agent({ page: "static" })`) 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.
 
-## A custom voice client
+### 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[] }));
+
+export default agent({
+  name: "Market Desk",
+  systemPrompt: "You look up quotes and keep the caller's watchlist.",
+  syncState: desk.projection((state) => ({ symbols: state.symbols })),
+});
+```
+
+### 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 };
+  },
+});
+```
 
-`client()` mounts the default chat shell with your sidebar, or replaces the
-whole UI with a custom component:
+### 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 "@alexkroman1/aai-ui/styles.css";
-import { client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
+import { useState } from "react";
+import { useToolResult } from "@alexkroman1/aai-ui";
 
-type OrderView = { items: string[]; total: string };
+type Quote = { symbol: string; price: number };
 
-function OrderSidebar() {
-  const theme = useTheme();
-  // Server state projected by the agent's `syncState`, pushed after every
-  // tool call.
-  const order = useAgentState<OrderView>() ?? { items: [], total: "$0.00" };
+export default function QuoteCard() {
+  const [quote, setQuote] = useState<Quote>();
+  useToolResult<Quote>("get_quote", (result) => setQuote(result));
+
+  if (!quote) return null;
   return (
-    <div style={{ color: theme.text }}>
-      {order.items.map((item) => (
-        <div key={item}>{item}</div>
-      ))}
-      <strong style={{ color: theme.primary }}>{order.total}</strong>
+    <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() {
+  // Whatever `syncState` projected, live. Null until the first push, which is
+  // a moment the UI has to render.
+  const desk = useAgentState<{ symbols: string[] }>();
+  return (
+    <div>
+      <QuoteCard />
+      {desk?.symbols.map((symbol) => <div key={symbol}>{symbol}</div>)}
     </div>
   );
 }
 
-// `sidebar` takes the COMPONENT, not an element — the shell renders it.
-client({ sidebar: OrderSidebar });
+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
 
-`page()` mounts a form over the agent's workflows. `<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:
+`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 no-check
+```tsx
 import "@alexkroman1/aai-ui/styles.css";
 import {
   Form,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
-// Type-only, so it is ERASED — the agent module is not in this bundle.
-import type { digest } from "./agent.ts";
 
 function App() {
-  const { submitForm, run, pending, upload, error } = useWorkflowSubmit<typeof digest>("digest");
+  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}>
@@ -78,45 +170,56 @@ function App() {
       {/* 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 `report()` in its steps. */}
+      {/* What the run has SAID, from `stepReport()` in its steps. */}
       <WorkflowProgress runId={run?.runId} />
       {run?.status === "completed" && <pre>{JSON.stringify(run.output)}</pre>}
     </main>
   );
 }
 
-page({ name: "Digest", component: App });
+mountPage({ name: "Digest", component: App });
 ```
 
-`WorkflowOutputOf<typeof myWorkflow>` is what makes
-`run.status === "completed"` narrow to a typed `run.output` — a type-only
-import of `agent.ts` is erased, so it pulls no server code into the bundle.
+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 reference below groups by TypeScript kind. This is the same surface
-grouped by what it is for.
-
-**Mounts** — `client()`, `page()`, 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 `client()` does for itself.
-
-**The live call** — `useSession()` for the whole snapshot,
-`useSessionSelector()` for one slice, `useUserTranscript()` for the caller's
-in-progress turn. `createSessionCore()` is the same session as a plain store,
-for a non-React client. `SessionSnapshot`, `AgentState`, `ChatMessage`,
+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()` (the `syncState` projection),
 `useToolResult()` / `useToolCallStart()` (tool calls as they run), and
-`useEvent()` (custom events from `ctx.send`).
+`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; `MessageList`, `Controls`,
-`Markdown`, `ToolCallRow`, `StartScreen`, `SidebarLayout`, `AutoScroll` and
+**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`,
@@ -127,9 +230,11 @@ them from a schema. A plain `<input name="x">` works identically.
 `useWorkflowSubmit()` / `useWorkflowStream()` (start one and watch it),
 `useWorkflowRun()` (watch one by id), `useWorkflowRuns()` (the history),
 `useWorkflowProgress()` (what a run has written), `useWorkflows()` (the
-listing). `<WorkflowProgress>` and `<UploadProgressBar>` are the rendered
-halves. `WorkflowRun`, `WorkflowSummary`, `WorkflowOutputOf` and
-`isTerminal()` are the vocabulary.
+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`.
 
@@ -140,23 +245,8 @@ 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 `createServer({ clientDir })` wants |
-| `/internal` | never, from application code: the plumbing `client()` 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 |
-
-## Hooks
-
-Inside components rendered by `client()`:
-
-- `useSession()` — connection state, transcript, and the call controls:
-  `start`, `toggle`, `cancel`, `reset`, `resetState`, `disconnect`, `end`.
-- `useAgentState<T>()` — the agent's `syncState` projection, live.
-- `useToolResult(name, cb)` / `useToolCallStart(name, cb)` — observe tool
-  calls as they run (e.g. to render a card per result).
-- `useEvent(name, cb)` — custom events the agent pushes with `ctx.send`.
-- `useTheme()` — the resolved theme colors for custom components.
-
-For a non-React integration, `createSessionCore()` exposes the same session
-as a plain store with an immutable snapshot per change.
+| `/client-dir` | serving the prebuilt default client from Node — `defaultClientDir()`, the filesystem path `createRuntimeServer({ 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
 

package/dist/{_colors-CZ6OlPbL.js → _colors-CpZO-88A.js}

@@ -51,5 +51,28 @@ function primaryTint(primary, surface, pct) {
 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 { primaryTint as i, THINKING_COLOR as n, inkTint as r, ERROR_COLOR as t };
+export { inkTint as a, focusRingStyle as i, FOCUS_RING as n, primaryTint as o, THINKING_COLOR as r, ERROR_COLOR as t };

package/dist/_recover-run.d.ts

@@ -55,8 +55,8 @@ import type { WorkflowApi } from "./workflow-client.ts";
 export type RecoverRunOptions = {
     /** The workflow whose runs are indexed under `key`. */
     workflow: string;
-    /** The caller's handle on its own run, or undefined for a page with none. */
-    key: string | undefined;
+    /** 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`. */

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-session.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>;

package/dist/_upload-files.d.ts

@@ -10,7 +10,7 @@
  * one file rather than walking an input and shares only the gate underneath both
  * (`_upload-session.ts`).
  */
-import type { UploadParallel } from "@alexkroman1/aai/workflow-api";
+import type { UploadParallelOption } from "@alexkroman1/aai/workflow-api";
 import { type UploadGate } from "./_upload-session.ts";
 import type { UploadStatus } from "./use-workflow-form.ts";
 import type { WorkflowApi } from "./workflow-client.ts";
@@ -80,4 +80,4 @@ export declare function createUploadSession(workflow: string): UploadSession;
  * last byte lands, so the incomplete record a streamed upload leaves along the
  * way is one nobody reads.
  */
-export declare function uploadFiles(api: WorkflowApi, input: unknown, report: (status: UploadStatus) => void, parallel: UploadParallel | undefined, session: UploadSession): Promise<unknown>;
+export declare function uploadFiles(api: WorkflowApi, input: unknown, report: (status: UploadStatus) => void, parallel: UploadParallelOption | undefined, session: UploadSession): Promise<unknown>;

package/dist/_upload-report.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Rate-limiting the upload progress report to what a bar can actually show.
+ *
+ * `onProgress` fires on every `XMLHttpRequest` progress event, and the parts
+ * uploader runs `UPLOAD_PART_CONCURRENCY` of those at once — so the raw rate is
+ * on the order of a hundred reports a second, sustained for the whole upload,
+ * which for the multi-hundred-megabyte files this feature exists for is
+ * minutes. Each one is a `setState`, and each re-renders the enclosing `<Form>`
+ * subtree: every field `<WorkflowFields>` rendered, the bar, and
+ * `<WorkflowProgress>` beside it. Progress events arrive as separate
+ * macrotasks, so React's automatic batching does not merge them.
+ *
+ * The bar has at most ~100 visually distinct states. Dropping a report that
+ * would render identically is therefore free, and it is the whole mechanism —
+ * no timer, so the LAST report of a burst is never left unrendered waiting for
+ * a window to close.
+ */
+import type { UploadStatus } from "./use-workflow-form.ts";
+/**
+ * Wrap an `UploadStatus` setter so redundant reports never reach React.
+ *
+ * Clearing the status (`undefined`) always passes and resets the comparison —
+ * it ends one file's bar, and the next file must not be coalesced against the
+ * previous one's last frame.
+ */
+export declare function coalesceUploadReports(set: (status: UploadStatus | undefined) => void): (status: UploadStatus | undefined) => void;

package/dist/{_utils-CyzjK0gW.js → _utils-DnQDM9Uy.js}

@@ -11,7 +11,7 @@ function truncate(s, max = 80) {
 }
 /**
 * The page this UI is served from — the agent's base URL when none is
-* configured explicitly. One definition so `client()`'s default and the
+* configured explicitly. One definition so `mountClient()`'s default and the
 * shareable-URL chip can never disagree about which agent the page is.
 */
 function pageBaseUrl() {
@@ -22,8 +22,8 @@ function pageBaseUrl() {
 * Set the document title, when there is one to set and a document to set it on.
 *
 * Both mounts do this and neither may clobber a title the page's own HTML
-* declared — `client()`'s custom-component tier because there is no shell header
-* to show the name in, `page()` because there is no shell at all. One copy, for
+* declared — `mountClient()`'s custom-component tier because there is no shell header
+* to show the name in, `mountPage()` because there is no shell at all. One copy, for
 * the reason `resolveContainer` and `mountRoot` are shared: the rule is the
 * same, so the two mounts must not be able to disagree about it.
 */

package/dist/_utils.d.ts

@@ -4,7 +4,7 @@ export declare function tryParseJSON(str: string | undefined): unknown;
 export declare function truncate(s: string, max?: number): string;
 /**
  * The page this UI is served from — the agent's base URL when none is
- * configured explicitly. One definition so `client()`'s default and the
+ * configured explicitly. One definition so `mountClient()`'s default and the
  * shareable-URL chip can never disagree about which agent the page is.
  */
 export declare function pageBaseUrl(): string;
@@ -12,8 +12,8 @@ export declare function pageBaseUrl(): string;
  * Set the document title, when there is one to set and a document to set it on.
  *
  * Both mounts do this and neither may clobber a title the page's own HTML
- * declared — `client()`'s custom-component tier because there is no shell header
- * to show the name in, `page()` because there is no shell at all. One copy, for
+ * declared — `mountClient()`'s custom-component tier because there is no shell header
+ * to show the name in, `mountPage()` because there is no shell at all. One copy, for
  * the reason `resolveContainer` and `mountRoot` are shared: the rule is the
  * same, so the two mounts must not be able to disagree about it.
  */

package/dist/_web-storage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Guarded access to the browser's key-value stores.
+ *
+ * Three modules in this package remember something across a load — the session
+ * id (`session-resume-store.ts`), the upload ids a form has minted
+ * (`_upload-recall.ts`) and a page's run correlation key (`use-run-key.ts`) —
+ * and each had written out the same two rules by hand, eight `try`/`catch`
+ * blocks and two URL-derived key builders between them. The tell was that each
+ * module's doc cited the others as precedent, which is a convention held by
+ * authors reading each other's comments rather than by code.
+ *
+ * Both rules are here once:
+ *
+ * - **Every access is guarded.** Storage THROWS outright in some contexts
+ *   (Safari private mode, an iframe blocked by policy) and is ABSENT in others
+ *   (any server-side render) — and reaching for the PROPERTY is itself what
+ *   throws, before a method is called, which is why the guard has to wrap the
+ *   lookup and not just the call. A caller that cannot remember must degrade to
+ *   the behaviour it would have had anyway, never fail to render.
+ * - **A slot is namespaced by the page's own URL**, so two agents served from
+ *   one origin — every deployed agent, at `/:slug/` — cannot inherit each
+ *   other's state.
+ */
+/** Which of the two stores; they differ only in how long an entry outlives the tab. */
+export type StorageKind = "session" | "local";
+/** The stored value, or undefined — for a missing entry and an absent store alike. */
+export declare function storageGet(kind: StorageKind, key: string): string | undefined;
+/** Remember a value. A store that refuses is a no-op, never a throw. */
+export declare function storageSet(kind: StorageKind, key: string, value: string): void;
+/** Forget a value. Nothing stored and no store are the same outcome. */
+export declare function storageRemove(kind: StorageKind, key: string): void;
+/**
+ * A storage key namespaced by a URL.
+ *
+ * `target` is resolved against the document, so a relative path ("./", the
+ * default-client case) and the absolute form of the same agent agree on one
+ * key.
+ *
+ * @param prefix - The owning module's namespace, e.g. `"aai:session:"`.
+ * @param target - What to resolve — an agent's `platformUrl`, or `"./"` for the
+ *   page's own directory.
+ */
+export declare function urlSlot(prefix: string, target: string): string;

package/dist/_workflow-files.d.ts

@@ -3,7 +3,7 @@
  *
  * 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.
+ * its id, `useWorkflowStream` mints the id first so the run can start on it.
  * 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.

package/dist/agent-state-labels.d.ts

@@ -0,0 +1,60 @@
+/**
+ * One word for where the CALL has got to, for each {@link AgentState} there is.
+ *
+ * The sibling of `WORKFLOW_STATUS_LABELS` next door, for the same reason and
+ * with the same shape. Three custom chromes carried three renderings of this
+ * one seven-member union, all written as a chain of ternaries over the raw
+ * member: one mapped `speaking` to "Narrating" and fell through to "Idle" for
+ * everything it had not listed, one shouted (`thinking` → "PROCESSING"), and
+ * the third rendered the enum member itself — so a caller of that agent read a
+ * lowercase `disconnected` in the header of a page nobody had decided to say
+ * that on.
+ *
+ * The exhaustiveness argument is the one that makes this worth exporting rather
+ * than documenting. A `Record` over {@link AgentState} means a state ADDED to
+ * the union is a compile error HERE, in one place every page inherits, instead
+ * of falling through each page's own `: "Idle"` tail into whichever word that
+ * page happened to end on — which is a silent wrong label, not a missing one. A
+ * page overriding one member keeps that: spreading a complete record cannot
+ * drop a key.
+ *
+ * There is deliberately no `StatusDot` component beside it. The dot markup and
+ * its palette are what each chrome exists to look like — a CRT's glow, a
+ * dispatch board's alert colours — and a component would take the one part
+ * that is genuinely shared (the words) hostage to the part that is not.
+ */
+import type { AgentState } from "./types.ts";
+/**
+ * The default label per {@link AgentState}.
+ *
+ * Override the ones your page has a better word for and keep the rest:
+ *
+ * ```ts
+ * import type { AgentState } from "@alexkroman1/aai-ui";
+ * import { AGENT_STATE_LABELS } from "@alexkroman1/aai-ui";
+ *
+ * // A dispatch board that shouts, and renames one state.
+ * const STATE_LABEL = { ...AGENT_STATE_LABELS, thinking: "Processing" };
+ * const shout = (s: AgentState) => STATE_LABEL[s].toUpperCase();
+ * ```
+ *
+ * **Sentence case, deliberately.** A template that wants caps applies its own
+ * `.toUpperCase()`, and a template that wants Title Case is already there;
+ * shipping the shouted form instead would leave the two chromes that do not
+ * shout with a string they have to un-shout, which no case transform does
+ * correctly.
+ *
+ * Two wordings are decisions rather than transliterations of the member name:
+ *
+ * - `disconnected` is **"Idle"**. It is the state a session is in BEFORE it has
+ *   ever started as well as after it ends, so it is the first word most callers
+ *   see; "Disconnected" reads as a fault on a page where nothing has gone
+ *   wrong yet. Both chromes that mapped this state by hand chose "Idle" too.
+ * - `connecting` and `thinking` carry an ellipsis, `listening` and `speaking`
+ *   do not. The first two are waits with nothing for the caller to do; the
+ *   other two describe someone actually talking. Same distinction
+ *   `WORKFLOW_STATUS_LABELS` draws with its one "Working…".
+ *
+ * @public
+ */
+export declare const AGENT_STATE_LABELS: Readonly<Record<AgentState, string>>;