@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/_tap-to-talk-state.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `useTapToTalk`'s decisions as a statechart, with no React and no session:
+ * what a tap does, when a call hangs itself up, and when a connection attempt
+ * has failed. The hook feeds it what the session DID (`SESSION`) and what the
+ * caller pressed (`TAP`, `TEXT`, `HANG_UP`), and it calls back through
+ * {@link TapToTalkEffects} — the pattern `session/audio-state.ts` uses, so
+ * `_tap-to-talk-state.test.ts` specs every timer without a browser.
+ *
+ * Two regions, because they move independently:
+ *
+ * - **`live`** — whether the caller has the mic open for a realtime
+ *   conversation. Only a tap enters it; a tap, a hang-up or the session going
+ *   down leaves it. The mic is muted on the way out and unmuted on the way in
+ *   (entry actions, so no path can forget).
+ * - **`session`** — the call as the session reports it: `idle`, `connecting`,
+ *   or `active` split by what the agent is doing, because each of those has
+ *   its own hang-up clock (`quiet`: the follow-up window; `thinking`: a longer
+ *   one, so a slow tool is not cut off; `speaking`: none). Any session
+ *   activity RE-ENTERS the active child, which restarts its clock — the
+ *   firmware's `agent_last_activity_ms()`.
+ *
+ * A clock only hangs up when `live` is `off`: a live conversation ends when
+ * the caller says so, as the device's does.
+ */
+import type { AgentState } from "./types.ts";
+/** What the session looks like to a tap: the three phases the hook publishes. */
+export type TapToTalkPhase = "idle" | "connecting" | "active";
+/** The three clocks, read per use so a re-render with new options takes effect. */
+export type TapToTalkTiming = {
+    /** Quiet, not live, not thinking or speaking: hang up after this long. */
+    idleHangupMs: number;
+    /** Thinking, not live: hang up after this long. */
+    thinkingHangupMs: number;
+    /** Connecting: give up (and report `failed`) after this long. */
+    connectTimeoutMs: number;
+};
+/** What the machine decides and cannot do itself. */
+export type TapToTalkEffects = {
+    /** Bring the session up if it is not meant to be running. Idempotent. */
+    connect(): void;
+    /** Hang up, resumably — `session.disconnect()`. */
+    hangUp(): void;
+    /** Stop the agent's current reply — `session.cancel()`. */
+    cancel(): void;
+    /** Mute (`true`) or open the mic. */
+    setMuted(muted: boolean): void;
+};
+/** Everything that moves the machine. */
+export type TapToTalkEvent = 
+/** The talk button or key. */
+{
+    type: "TAP";
+}
+/** Hang up now, whatever the state. */
+ | {
+    type: "HANG_UP";
+}
+/** A typed turn: it clears a previous failure like a tap does. */
+ | {
+    type: "TEXT";
+}
+/**
+ * The session moved or did something — sent on every activity (a content
+ * change too), not only a phase change; every one restarts the active clock.
+ */
+ | {
+    type: "SESSION";
+    phase: TapToTalkPhase;
+    agent: AgentState;
+}
+/** The session reported an error. */
+ | {
+    type: "ERROR";
+};
+/** What the hook renders from. A new object only when a field changes. */
+export type TapToTalkView = {
+    live: boolean;
+    failed: boolean;
+};
+/** One running machine: send events, read and subscribe to its view, stop it. */
+export type TapToTalkStore = {
+    send(event: TapToTalkEvent): void;
+    getView(): TapToTalkView;
+    subscribe(listener: () => void): () => void;
+    stop(): void;
+};
+/** Start a machine over `effects`. */
+export declare function createTapToTalk(effects: TapToTalkEffects, timing: () => TapToTalkTiming): TapToTalkStore;

package/dist/_utils-Mi-SCFA1.js

@@ -0,0 +1,47 @@
+import { safeJsonParse } from "@alexkroman1/aai";
+//#region src/_utils.ts
+/** Parse a JSON string, returning the input unchanged when it isn't valid JSON. */
+function tryParseJSON(str) {
+	if (!str) return str;
+	return safeJsonParse(str) ?? str;
+}
+/** Truncate a string to `max` characters, appending an ellipsis when cut. */
+function truncate(s, max = 80) {
+	return s.length > max ? `${s.slice(0, max)}...` : s;
+}
+/**
+* The page this UI is served from — the agent's base URL when none is
+* configured explicitly. One definition so `mountClient()`'s default and the
+* shareable-URL chip can never disagree about which agent the page is.
+*/
+function pageBaseUrl() {
+	if (typeof location === "undefined") return "";
+	return location.origin + location.pathname;
+}
+/**
+* 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 — `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.
+*/
+function setPageTitle(name) {
+	if (name && typeof document !== "undefined") document.title = name;
+}
+/**
+* True when a key event came from somewhere typing belongs — where Space is a
+* character, not a talk key. Shared by the two talk-button hooks
+* (`use-push-to-talk.ts`, `use-tap-to-talk.ts`) so they cannot disagree.
+*/
+function isTypingTarget(target) {
+	if (typeof HTMLElement === "undefined" || !(target instanceof HTMLElement)) return false;
+	return target.isContentEditable || [
+		"INPUT",
+		"TEXTAREA",
+		"SELECT"
+	].includes(target.tagName);
+}
+//#endregion
+export { tryParseJSON as a, truncate as i, pageBaseUrl as n, setPageTitle as r, isTypingTarget as t };

package/dist/_utils.d.ts

@@ -0,0 +1,26 @@
+/** Parse a JSON string, returning the input unchanged when it isn't valid JSON. */
+export declare function tryParseJSON(str: string | undefined): unknown;
+/** Truncate a string to `max` characters, appending an ellipsis when cut. */
+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 `mountClient()`'s default and the
+ * shareable-URL chip can never disagree about which agent the page is.
+ */
+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 — `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.
+ */
+export declare function setPageTitle(name: string | undefined): void;
+/**
+ * True when a key event came from somewhere typing belongs — where Space is a
+ * character, not a talk key. Shared by the two talk-button hooks
+ * (`use-push-to-talk.ts`, `use-tap-to-talk.ts`) so they cannot disagree.
+ */
+export declare function isTypingTarget(target: EventTarget | null): boolean;

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-api-ref.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The client preamble every workflow hook needs, once.
+ *
+ * Five hooks (`useWorkflowRun`, `useWorkflowProgress`, `useWorkflowRuns`,
+ * `useWorkflows`, `useWorkflowSubmit`) opened with the same two refs and the
+ * same two paragraphs explaining them, and both halves are load-bearing rather
+ * than stylistic — which is exactly why they should not be re-derived per hook:
+ *
+ * - **The caller's client lives in a REF, never in an effect's dependency
+ *   array.** The natural call site is
+ *   `useWorkflowRun(id, { api: createWorkflowApi() })`, which passes a NEW
+ *   object every render; as a dependency that tears the effect down and
+ *   restarts it on each one, and because a restart clears state and re-renders,
+ *   it schedules the next. The result is an unbounded request loop against the
+ *   agent — on the platform, against the BROKER — with `error` wiped before
+ *   anything can read it, presenting as "the page polls forever" rather than as
+ *   a mistake at the call site.
+ * - **The no-client default is built lazily and ONCE.** As a render-time
+ *   default (`api ?? createWorkflowApi()`) it is a fresh object per render,
+ *   which is the same hazard one layer down; built inside an effect it is a
+ *   fresh object per watch.
+ *
+ * The returned getter is stable for the life of the component and reads the ref
+ * on every call, so a caller that SWAPS clients mid-watch — a token arriving
+ * after login — is picked up by the next request without the watch restarting.
+ */
+import { type WorkflowApi } from "./workflow-client.ts";
+/**
+ * Resolve the client a workflow hook should use, now.
+ *
+ * @param api - The caller's client, or undefined for one aimed at the page's
+ *   own agent.
+ * @returns A stable getter. Call it per request, never once per watch.
+ *
+ * @internal
+ */
+export declare function useWorkflowApiRef(api: WorkflowApi | undefined): () => WorkflowApi;

package/dist/_workflow-files.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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` 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.
+ */
+/**
+ * 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.
+ */
+export declare function filesOf(value: unknown): File[];
+/**
+ * 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.
+ */
+export declare function fileFields(input: unknown): string[];

package/dist/_workflow-test-defs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Synthetic workflow DEF types for this package's specs.
+ *
+ * The workflow hooks take a def rather than an output type, and the def is
+ * REQUIRED — there is no untyped fallback, because an escape hatch nobody needs
+ * is one somebody uses. That leaves the specs, whose subject is upload plumbing
+ * and polling rather than typing, needing a def to name.
+ *
+ * Built structurally rather than with a schema library: `zod` is not a
+ * dependency of this package, and `StandardSchemaV1` is published on
+ * `@alexkroman1/aai/host-internal`, which a browser package may not import. The
+ * shape below is the part of that contract `InferSchemaOutput` reads — the
+ * `types.output` slot — and nothing else, which is all a type-level def needs.
+ *
+ * A `.ts` module rather than a `_test-utils` export because it is types only.
+ */
+import type { WorkflowDef } from "@alexkroman1/aai";
+/** A Standard-Schema-shaped type whose parsed output is `O`. Never constructed. */
+type SchemaOf<O extends Record<string, unknown>> = {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            readonly value: O;
+        };
+        readonly types?: {
+            readonly input: unknown;
+            readonly output: O;
+        } | undefined;
+    };
+};
+/** A workflow taking `I` and answering `O`. */
+export type TestWorkflow<I extends Record<string, unknown> = Record<string, unknown>, O = unknown> = WorkflowDef<SchemaOf<I>, O>;
+/** The shape most specs here need: one `recording` upload id, an unknown result. */
+export type UploadWorkflow = TestWorkflow<{
+    recording: unknown;
+}>;
+export {};

package/dist/aai-logo-D8pMVn9_.js

@@ -0,0 +1,85 @@
+import { useTheme } from "./context.js";
+import { memo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/aai-logo.tsx
+/** @jsxImportSource react */
+/**
+* The AssemblyAI wordmark (design-system "website refresh" asset).
+*
+* The mark keeps its brand blues; the letterforms inherit the theme's text
+* color so the logo works on the cream default and custom themes alike.
+*
+* @param size - Rendered height in px. Defaults to 20.
+* @internal
+*/
+const AaiLogo = memo(function AaiLogo({ size = 20 }) {
+	const theme = useTheme();
+	return /* @__PURE__ */ jsxs("svg", {
+		role: "img",
+		"aria-label": "AssemblyAI",
+		height: size,
+		viewBox: "0 0 141 24",
+		fill: "none",
+		xmlns: "http://www.w3.org/2000/svg",
+		style: {
+			display: "block",
+			color: theme.text
+		},
+		children: [
+			/* @__PURE__ */ jsx("path", {
+				d: "M37.698 16.7132L38.9234 13.4518H44.334L45.5782 16.7132H47.897L42.9766 3.51665H40.3939L35.4546 16.7132H37.698ZM41.6193 5.85433L43.7307 11.6042H39.5267L41.6193 5.85433Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M48.9176 13.5272C48.9741 15.6198 50.7462 16.8263 53.329 16.8263C55.6667 16.8263 57.4199 15.6575 57.4199 13.81C57.4199 11.6608 55.6289 11.2083 53.4232 10.9444C52.0282 10.7936 51.1044 10.6805 51.1044 9.77558C51.1044 9.00264 51.8962 8.51249 53.1028 8.51249C54.3093 8.51249 55.1388 9.13461 55.2519 10.0207H57.2502C57.1183 8.04118 55.4404 6.94775 53.065 6.94775C50.7462 6.9289 49.1061 8.11659 49.1061 9.94525C49.1061 11.9436 50.8405 12.4149 53.0462 12.6788C54.5355 12.8673 55.4216 12.9428 55.4216 13.9796C55.4216 14.7526 54.5921 15.2427 53.329 15.2427C51.8585 15.2427 50.9913 14.5263 50.9159 13.5272H48.9176Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M58.9645 13.5272C59.021 15.6198 60.7931 16.8263 63.3759 16.8263C65.7135 16.8263 67.4668 15.6575 67.4668 13.81C67.4668 11.6608 65.6758 11.2083 63.4701 10.9444C62.0751 10.7936 61.1513 10.6805 61.1513 9.77558C61.1513 9.00264 61.9431 8.51249 63.1497 8.51249C64.3562 8.51249 65.1857 9.13461 65.2988 10.0207H67.2971C67.1652 8.04118 65.4873 6.94775 63.1119 6.94775C60.7931 6.9289 59.153 8.11659 59.153 9.94525C59.153 11.9436 60.8874 12.4149 63.0931 12.6788C64.5824 12.8673 65.4685 12.9428 65.4685 13.9796C65.4685 14.7526 64.639 15.2427 63.3759 15.2427C61.9054 15.2427 61.0382 14.5263 60.9628 13.5272H58.9645Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M74.1913 16.8263C76.5855 16.8263 78.2068 15.3747 78.5462 13.4706H76.5101C76.2273 14.5452 75.3224 15.1673 74.0782 15.1673C72.4757 15.1673 71.4389 14.0927 71.3823 12.4526V12.3206H78.6593C78.697 12.0567 78.7158 11.7928 78.7158 11.5477C78.6593 8.71986 76.7929 6.94775 74.0028 6.94775C71.1561 6.94775 69.252 8.92723 69.252 11.9059C69.252 14.8657 71.1561 16.8263 74.1913 16.8263ZM71.4577 10.8313C71.6085 9.4551 72.7208 8.5879 74.0216 8.5879C75.4355 8.5879 76.4347 9.39854 76.6044 10.8313H71.4577Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M92.0314 6.94775C90.4478 6.94775 89.3544 7.64529 88.7322 8.70101C88.1478 7.45676 87.0167 6.94775 85.7536 6.94775C84.302 6.96661 83.4725 7.60758 82.9258 8.32396L82.6995 7.06087H80.9274V16.7132H82.9635V11.5477C82.9635 9.83214 83.8307 8.70101 85.2257 8.70101C86.5642 8.70101 87.2618 9.58706 87.2618 11.2838V16.7132H89.3167V11.4911C89.3167 9.75673 90.2027 8.70101 91.5978 8.70101C92.9174 8.70101 93.615 9.58706 93.615 11.2838V16.7132H95.651V11.1518C95.651 8.09774 94.0297 6.94775 92.0314 6.94775Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M103.228 6.94775C101.738 6.94775 100.739 7.62643 100.098 8.49363V3.51665H98.0623V16.7132H99.8344L100.079 15.3181C100.683 16.1853 101.72 16.8263 103.228 16.8263C105.867 16.8263 107.79 14.8468 107.79 11.887C107.79 8.77642 105.867 6.94775 103.228 6.94775ZM102.888 15.1108C101.192 15.1108 100.079 13.7722 100.079 11.8682C100.079 10.0018 101.192 8.68216 102.888 8.68216C104.585 8.68216 105.716 10.0018 105.716 11.887C105.716 13.7911 104.585 15.1108 102.888 15.1108Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M109.987 16.7132H112.023V3.51665H109.987V16.7132Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M117.375 16.7697L116.998 17.7124C116.696 18.5041 116.507 18.6927 115.716 18.6927H114.283V20.4836H116.47C117.884 20.4836 118.298 19.7861 118.902 18.2214L123.275 7.06087H121.107L118.487 14.3944L115.791 7.06087H113.623L117.375 16.7697Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M125.769 16.7132L126.994 13.4518H132.405L133.649 16.7132H135.968L131.047 3.51665H128.465L123.525 16.7132H125.769ZM129.69 5.85433L131.801 11.6042H127.597L129.69 5.85433Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M137.887 16.7132H140.055V3.51665H137.887V16.7132Z",
+				fill: "currentColor"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				fillRule: "evenodd",
+				clipRule: "evenodd",
+				d: "M12.2496 0C10.4867 0 8.90488 1.08157 8.26713 2.72302L0 24H6.28017L12.7874 7.25245H12.7902C12.9534 6.84425 13.353 6.55584 13.8199 6.55584C14.2869 6.55584 14.6864 6.84425 14.8497 7.25245H15.7167V3.85532H14.1073L15.6053 0H12.2496Z",
+				fill: "#2545D3"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				fillRule: "evenodd",
+				clipRule: "evenodd",
+				d: "M8.2677 2.72302C8.87959 1.1483 10.3603 0.0888597 12.0361 0.00532694L12.034 0H12.2501H14.6661H15.4972C17.2601 0 18.8419 1.08157 19.4797 2.72302L27.7468 24H21.3592L13.3424 3.36747C12.8835 2.35631 11.864 1.65296 10.6801 1.65296C9.49331 1.65296 8.47176 2.35976 8.0144 3.37493L8.2677 2.72302Z",
+				fill: "#566DE8"
+			})
+		]
+	});
+});
+//#endregion
+export { AaiLogo as t };

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

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ *
+ * `SessionStateDot` (`components/session-state-dot.tsx`) is the dot beside it,
+ * and this paragraph used to argue against one: the dot's palette is 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. It takes the palette as a PROP, so it does
+ * not: what it shares is the exhaustive colour lookup, this record as the label
+ * fallback, and the pulse rule, and the three chromes that had each written
+ * those fourteen lines around their own `satisfies Record<AgentState, string>`
+ * keep the record and lose the lines.
+ */
+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>>;

package/dist/agent-state.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Reading what the agent projects — `agent({ syncState })` — in the browser.
+ *
+ * The frame is KEYED by slot name (`{ [slot]: view }`), so every reader here
+ * selects ONE slot by the name the agent keyed it under. That is what lets a
+ * component re-render only when ITS slot changed: the session core keeps an
+ * unchanged slot's value referentially stable across pushes, and
+ * {@link selectAgentState} is a stable selector per key, so
+ * `useSessionSelector`'s `Object.is` comparison does the rest.
+ *
+ * Split out of `hooks.ts` at the source-length cap; re-exported from there.
+ */
+import type { DefaultToolResult, StateProjection } from "@alexkroman1/aai";
+import type { AgentStateFrame, SessionSnapshot } from "./session/index.ts";
+/**
+ * A `useSessionSelector` selector for ONE slot of the agent's projected state:
+ * its value, or `undefined` before the agent has pushed it.
+ *
+ * The same function for the same name on every call, which is load-bearing:
+ * `useSessionSelector` caches its selection on the selector's identity, and an
+ * inline arrow would re-run it on every snapshot.
+ *
+ * ```tsx
+ * import { selectAgentState, useSessionSelector } from "@alexkroman1/aai-ui";
+ *
+ * function CartBadge() {
+ *   // Re-renders when the `cart` slot changes, and on nothing else.
+ *   const cart = useSessionSelector(selectAgentState<{ count: number }>("cart"));
+ *   return <span>{cart?.count ?? 0}</span>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function selectAgentState<V = DefaultToolResult>(slot: string): (snapshot: SessionSnapshot) => V | undefined;
+/**
+ * The agent's whole projected frame — `{ [slot]: view }` for every slot its
+ * `syncState` names — or `null` before the first push. Prefer naming the slot
+ * (the overloads below): a component reading the whole frame re-renders when
+ * any slot changes.
+ *
+ * @public
+ */
+export declare function useAgentState(): AgentStateFrame | null;
+/**
+ * One slot's projected state, typed and defaulted by the SAME projection the
+ * agent pushes — pass `slot.projected` and there is no type argument to
+ * restate, no slot name to repeat and no empty frame to derive.
+ *
+ * ```tsx
+ * import { sessionSlot } from "@alexkroman1/aai";
+ * import { useAgentState } from "@alexkroman1/aai-ui";
+ *
+ * // In a real project the slot is declared beside the agent and imported here;
+ * // the agent declares `syncState: cartSlot.projected`.
+ * const cartSlot = sessionSlot("cart", () => ({ items: [] as string[] }), {
+ *   view: (cart) => ({ count: cart.items.length }),
+ * });
+ *
+ * function CartBadge() {
+ *   const cart = useAgentState(cartSlot.projected); // reads state.cart
+ *   return <span>{cart.count}</span>;
+ * }
+ * ```
+ *
+ * The projection carries its slot key, so this selects `state[projection.key]`
+ * — the key the agent's `syncState` frame is keyed by. Before the first
+ * push it answers `projection()`, the slot's DEFAULT through the same view,
+ * memoized on the projection's identity; `slot.projected` is built once with
+ * the slot, so that identity is stable for the life of the component.
+ *
+ * **The one case that cannot use this overload is a slot whose declaring
+ * module is expensive to IMPORT** (a seeded factory pulls its seed into the
+ * browser bundle): name the slot instead, with a fallback.
+ *
+ * @public
+ */
+export declare function useAgentState<V>(projection: StateProjection<V>): V;
+/**
+ * One slot's projected state by NAME, or `null` before the agent pushed it.
+ * Typed by the caller, as `useToolResult` is: the shape is the author's own
+ * projection, which this file cannot see.
+ *
+ * @public
+ */
+export declare function useAgentState<V = DefaultToolResult>(slot: string): V | null;
+/**
+ * One slot's projected state by NAME, falling back to `fallback` before the
+ * first push — for a slot whose module the browser should not import. Build the
+ * fallback by running the SAME view over an empty state, and hoist it to module
+ * scope so it is a stable reference.
+ *
+ * ```tsx
+ * import { useAgentState } from "@alexkroman1/aai-ui";
+ *
+ * type StoreView = { orders: string[] };
+ * // Hoisted, so it is one reference for the life of the component.
+ * const EMPTY: StoreView = { orders: [] };
+ *
+ * function Orders() {
+ *   const view = useAgentState("retail", EMPTY);
+ *   return <p>{view.orders.length} orders</p>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useAgentState<V>(slot: string, fallback: V): V;

package/dist/audio/capture.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Throw unless the browser honored a requested context sample rate. The
+ * requested rates are never advisory: captured audio is tagged with the
+ * requested rate on the wire, so a context running at some other rate ships
+ * audio that only sounds like speech to the wrong decoder. Every capture
+ * path must call this after context creation.
+ */
+export declare function assertGranted(granted: number, requested: number, side: string): void;
+/**
+ * The error a dead worklet processor reports.
+ *
+ * A processor exception permanently kills the node — no further messages or
+ * audio will ever arrive — so both sides log it and hand it on. One spelling of
+ * that, because the pair differed only in the word "capture"/"playback" and in
+ * what the playback side has to settle afterwards.
+ */
+export declare function workletCrash(side: "capture" | "playback"): Error;
+/**
+ * Release a microphone that was (or later gets) granted while another init
+ * step failed; if `getUserMedia` itself rejected, this is a no-op. Without
+ * it, a mic granted after a failed init keeps the browser's recording
+ * indicator lit with no way to turn it off.
+ */
+export declare function releaseStreamOnFailure(streamPromise: Promise<MediaStream>): void;
+/** Handle to one capture worklet node (`worklets/capture-processor.ts`). */
+export type CaptureNode = {
+    node: AudioWorkletNode;
+    /** Begin accumulating — the worklet gates capture on its start/stop protocol. */
+    start(): void;
+    /**
+     * Stop accumulating and wait (bounded by {@link CAPTURE_STOP_ACK_TIMEOUT_MS})
+     * for the 'stopped' ack that follows the worklet's final flush, so the tail
+     * of speech reaches `onChunk` before the node is torn down.
+     */
+    stop(): Promise<void>;
+};
+/**
+ * Wire one capture worklet node: node construction, the chunk/silent/stopped
+ * port protocol, and the stop→ack handshake. No `processorOptions`: the
+ * worklet reads the context rate from its global scope (callers assert the
+ * granted rate first) and owns its own batching default — re-spelling
+ * defaults caller-side is drift.
+ */
+export declare function createCaptureNode(ctx: AudioContext, onChunk: (pcm16: ArrayBuffer) => void, onSilent?: () => void): CaptureNode;

package/dist/audio/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The browser audio layer's import surface for the rest of the package: the
+ * {@link VoiceIO} a live call plays and captures through, and the pre-connect
+ * capture that buffers the mic before the server names its rates.
+ *
+ * `capture.ts` (the grant checks and the capture node both halves share) is
+ * private to this directory — guard-invariants rule 37 fails an import from
+ * outside `audio/` that names any module but this one.
+ *
+ * The session core reaches this module only through a DYNAMIC `import()`
+ * (`session/audio-setup.ts`, `session/preconnect.ts`), so it is a lazily
+ * fetched chunk; a static VALUE import of it from session code would put it
+ * back on the main bundle. Type imports are free.
+ *
+ * @module
+ */
+export { openPreConnectCapture, type PreConnectCapture } from "./preconnect.ts";
+export { createVoiceIO, type VoiceIO, type VoiceIOOptions } from "./voice-io.ts";