@alexkroman1/aai-ui 0.12.3 → 0.14.0

package/dist/stored-value.d.ts

@@ -0,0 +1,103 @@
+/**
+ * A string a page remembers in this browser — a setting, a phone number, a
+ * linked device — readable outside React (a `mountClient({ phone })` getter
+ * asked on every connect) and reactive inside it.
+ *
+ * Built on `_web-storage.ts`, so it inherits that module's rule: every access
+ * is guarded, and a browser that refuses storage (private mode, a blocked
+ * iframe) degrades to a value held in memory for the tab — the page still
+ * works, it just forgets on reload. On top of that:
+ *
+ * - **Every holder of a key sees a write** — two components, a component and a
+ *   getter, and other TABS (the `storage` event), so a setting changed in one
+ *   place is not stale in another.
+ * - **An empty value is no value**: writing `""` REMOVES the entry, so the next
+ *   read is the `initial` again rather than a stored blank.
+ *
+ * @module
+ */
+/**
+ * Options for {@link createStoredValue}.
+ *
+ * @public
+ */
+export type StoredValueOptions = {
+    /** What a read answers while nothing is stored. Default `""`. */
+    initial?: string | undefined;
+    /** `"local"` (the default) outlives the tab; `"session"` does not. */
+    storage?: "local" | "session" | undefined;
+};
+/**
+ * One remembered string — see {@link createStoredValue}.
+ *
+ * @public
+ */
+export type StoredValue = {
+    /** The storage key, as given. */
+    readonly key: string;
+    /** The value now: what is stored, else the `initial`. */
+    get(): string;
+    /** Remember `value`; `""` or `undefined` forgets it. Every holder of the key is told. */
+    set(value: string | undefined): void;
+    /** Be told when the value changes — here, in another holder, or in another tab. */
+    subscribe(listener: () => void): () => void;
+};
+/**
+ * A string remembered in this browser under `key` — see this module's doc.
+ *
+ * Create it once at module scope and share it: `get()` in a getter outside
+ * React, {@link useStoredValue} in a component.
+ *
+ * The key is used as given, so choose one that is yours (`"my-app:phone"`);
+ * two agents on one origin share a key they both name.
+ *
+ * @example A phone number for the session, edited in a settings field
+ * ```tsx
+ * import { createStoredValue, mountClient, phoneE164, useStoredValue } from "@alexkroman1/aai-ui";
+ *
+ * const phone = createStoredValue("my-speaker:phone");
+ *
+ * function PhoneField() {
+ *   const [value, setValue] = useStoredValue(phone);
+ *   return <input defaultValue={value} onBlur={(e) => setValue(e.currentTarget.value.trim())} />;
+ * }
+ *
+ * mountClient({ phone: () => phoneE164(phone.get()), component: PhoneField });
+ * ```
+ *
+ * @param key - The storage key.
+ * @param options - `initial` and which storage; see {@link StoredValueOptions}.
+ * @returns The value's handle; see {@link StoredValue}.
+ *
+ * @public
+ */
+export declare function createStoredValue(key: string, options?: StoredValueOptions): StoredValue;
+/**
+ * A remembered string as React state: the value, and a setter that writes it
+ * through to storage — see this module's doc.
+ *
+ * Pass the key (and an `initial`) for a value one component owns, or a
+ * {@link StoredValue} shared with code outside React.
+ *
+ * @example
+ * ```tsx
+ * import { useStoredValue } from "@alexkroman1/aai-ui";
+ *
+ * function Units() {
+ *   const [units, setUnits] = useStoredValue("my-app:units", "metric");
+ *   return (
+ *     <button type="button" onClick={() => setUnits(units === "metric" ? "imperial" : "metric")}>
+ *       {units}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @param source - A storage key, or a {@link StoredValue}.
+ * @param initial - With a key: what to answer while nothing is stored. Default `""`.
+ *   Ignored with a `StoredValue`, which carries its own.
+ * @returns `[value, setValue]`; `setValue("")` forgets it.
+ *
+ * @public
+ */
+export declare function useStoredValue(source: StoredValue | string, initial?: string): [string, (value: string | undefined) => void];

package/dist/tool-call-block-uXtMOUWN.js

@@ -0,0 +1,204 @@
+import { a as tryParseJSON, i as truncate } from "./_utils-Mi-SCFA1.js";
+import { useTheme } from "./context.js";
+import { a as inkTint } from "./_colors-CpZO-88A.js";
+import { t as Eyebrow } from "./eyebrow-UfmSz9yy.js";
+import { n as useToolConfig } from "./tool-config-context-Es4YUzV2.js";
+import { memo, useMemo, useState } from "react";
+import clsx from "clsx";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/tool-call-row.tsx
+/** @jsxImportSource react */
+const VARIANT_CLASSES = {
+	default: {
+		button: "gap-2.5 px-3.5 py-2.5",
+		title: "text-[13px]",
+		chevron: "text-[10px]"
+	},
+	compact: {
+		button: "gap-2 px-3 py-2",
+		title: "text-[11px]",
+		chevron: "text-[9px]"
+	}
+};
+/**
+* The design system's console row for one tool invocation: a small outlined
+* "TOOL" chip (or a custom `icon`), the tool title in mono, a truncated
+* detail preview, and a rotating chevron that expands to the panel content.
+*
+* Purely presentational — callers own the mapping from their tool-call data
+* to `title`/`detail`/`pending` and the expanded panel. The deployed agent
+* UI's message list renders it via its tool-call block, and the studio's
+* chat transcript renders it with `variant="compact"`, so the two surfaces
+* read as one component.
+*
+* Colors come from the nearest theme context (see {@link useTheme}); without
+* a provider the default AssemblyAI theme applies.
+*
+* @example
+* ```tsx
+* import { ToolCallRow, useSession } from "@alexkroman1/aai-ui";
+*
+* // A custom chrome's tool log, from the snapshot's own `toolCalls`.
+* function ToolLog() {
+*   const { toolCalls } = useSession();
+*   return (
+*     <div>
+*       {toolCalls.map((call) => (
+*         <ToolCallRow
+*           key={call.callId}
+*           title={call.name}
+*           detail={call.result}
+*           pending={call.status === "pending"}
+*         />
+*       ))}
+*     </div>
+*   );
+* }
+* ```
+*
+* @param props - See {@link ToolCallRowProps}.
+*
+* @public
+*/
+function ToolCallRow({ title, detail, pending = false, icon, variant = "default", className, children }) {
+	const [isOpen, setIsOpen] = useState(false);
+	const theme = useTheme();
+	const sizes = VARIANT_CLASSES[variant];
+	const canExpand = children != null;
+	const faint = inkTint(theme.text, theme.bg, 65);
+	return /* @__PURE__ */ jsxs("div", {
+		className: clsx("flex flex-col rounded-md border overflow-hidden", className),
+		style: {
+			borderColor: theme.border,
+			background: theme.bg
+		},
+		children: [/* @__PURE__ */ jsxs("button", {
+			type: "button",
+			"aria-expanded": canExpand ? isOpen : void 0,
+			disabled: !canExpand,
+			className: clsx("flex items-center select-none text-left w-full appearance-none border-none bg-transparent", sizes.button, canExpand && "cursor-pointer"),
+			onClick: () => {
+				if (canExpand) setIsOpen(!isOpen);
+			},
+			children: [
+				icon ? /* @__PURE__ */ jsx("span", {
+					className: "w-4 h-4 shrink-0 text-center leading-4",
+					children: icon
+				}) : /* @__PURE__ */ jsx(Eyebrow, {
+					className: "shrink-0",
+					style: { color: faint },
+					children: "Tool"
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: clsx("min-w-0 truncate font-aai-mono font-medium", sizes.title, pending && "tool-shimmer"),
+					style: { color: theme.text },
+					children: title
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: clsx("font-aai-mono truncate flex-1 min-w-0", sizes.title),
+					style: { color: faint },
+					children: detail
+				}),
+				canExpand && /* @__PURE__ */ jsx("span", {
+					className: clsx("shrink-0 transition-transform duration-150", sizes.chevron, isOpen && "rotate-90"),
+					style: { color: faint },
+					children: "▶"
+				})
+			]
+		}), isOpen && canExpand && /* @__PURE__ */ jsx("div", {
+			className: "border-t max-h-64 overflow-auto",
+			style: {
+				borderColor: theme.border,
+				background: theme.surface
+			},
+			children
+		})]
+	});
+}
+//#endregion
+//#region src/components/tool-call-block.tsx
+/** @jsxImportSource react */
+function formatResult(result) {
+	const parsed = tryParseJSON(result);
+	return parsed === result ? result : JSON.stringify(parsed, null, 2);
+}
+/**
+* The expanded result pane.
+*
+* Its own component so the parse-and-pretty-print happens only when the row is
+* actually OPEN. `ToolCallRow` renders `children` under `isOpen && canExpand`,
+* and a row starts closed — so computing this in the parent meant every row
+* paid `JSON.parse` + `JSON.stringify(_, null, 2)` over its whole result, and
+* then RETAINED the pretty string, for a panel nobody clicked. The burst case
+* is `history.restored`, which mounts up to `MAX_CLIENT_MESSAGES` rows in one
+* commit.
+*
+* Creating this element is free; React only runs the body once it is mounted.
+*/
+function ToolCallResult({ result }) {
+	const theme = useTheme();
+	const formatted = useMemo(() => formatResult(result), [result]);
+	if (!formatted) return null;
+	return /* @__PURE__ */ jsx("pre", {
+		className: "font-aai-mono text-xs px-3.5 py-3 m-0 whitespace-pre-wrap wrap-break-word",
+		style: { color: inkTint(theme.text, theme.surface, 75) },
+		children: formatted
+	});
+}
+/**
+* Renders a tool invocation as the design system's console row (see
+* `ToolCallRow`): a small outlined "TOOL" chip (or the tool's configured
+* icon), the tool name in mono, a truncated args preview, and a rotating
+* chevron that expands the formatted result.
+*
+* Tool display is configured via `ToolConfigContext`. If no config is found
+* for a tool name, the raw tool name is shown as the title.
+*
+* While the tool call is pending a shimmer animation is shown. Once
+* complete, clicking the row expands the formatted JSON result.
+*
+* Memoized: tool-call objects are referentially stable across session
+* snapshots and rows are keyed on the stable `callId`, so a list update only
+* re-renders the rows whose tool call actually changed.
+*
+* @param toolCall - The tool call to render (see {@link ToolCallInfo}).
+* @param className - Additional CSS class names.
+*
+* @internal Not exported from the package — rendered by `MessageList`.
+*/
+const ToolCallBlock = memo(function ToolCallBlock({ toolCall, className }) {
+	const theme = useTheme();
+	const toolConfig = useToolConfig();
+	const config = Object.hasOwn(toolConfig, toolCall.name) ? toolConfig[toolCall.name] : void 0;
+	const isPending = toolCall.status === "pending";
+	const title = config?.label || toolCall.name;
+	const icon = config?.icon;
+	const canExpand = !isPending && Boolean(toolCall.result);
+	const subtitle = useMemo(() => {
+		const args = toolCall.args;
+		if (toolCall.name === "run_code" && args.code) return truncate(String(args.code).split("\n")[0] ?? "");
+		for (const key of [
+			"query",
+			"url",
+			"question"
+		]) if (args[key]) return String(args[key]);
+		return truncate(JSON.stringify(args));
+	}, [toolCall.name, toolCall.args]);
+	return /* @__PURE__ */ jsx(ToolCallRow, {
+		title,
+		detail: subtitle,
+		pending: isPending,
+		icon,
+		className,
+		children: canExpand ? /* @__PURE__ */ jsxs(Fragment$1, { children: [toolCall.name === "run_code" && Boolean(toolCall.args.code) && /* @__PURE__ */ jsx("pre", {
+			className: "font-aai-mono text-xs px-3.5 py-3 m-0 whitespace-pre-wrap wrap-break-word border-b",
+			style: {
+				color: theme.text,
+				borderColor: theme.border
+			},
+			children: String(toolCall.args.code)
+		}), toolCall.result && /* @__PURE__ */ jsx(ToolCallResult, { result: toolCall.result })] }) : void 0
+	});
+});
+//#endregion
+export { ToolCallRow as n, ToolCallBlock as t };

package/dist/tool-config-context-Es4YUzV2.js

@@ -0,0 +1,19 @@
+import { createContext, useContext } from "react";
+//#region src/components/tool-config-context.ts
+/**
+* Context for tool display configuration. Installed by `mountClient()` from
+* `ClientConfig.tools`; the built-in components read it via `useToolConfig`.
+*
+* @internal
+*/
+const ToolConfigContext = createContext({});
+/**
+* Read tool display configuration from the nearest `ToolConfigContext.Provider`.
+*
+* @internal
+*/
+function useToolConfig() {
+	return useContext(ToolConfigContext);
+}
+//#endregion
+export { useToolConfig as n, ToolConfigContext as t };

package/dist/types.d.ts

@@ -1,8 +1,60 @@
+import type { DefaultToolResult } from "@alexkroman1/aai";
 import type { SessionErrorCode } from "@alexkroman1/aai/protocol";
-/** Microphone buffer duration in seconds before sending to the server. */
-export declare const MIC_BUFFER_SECONDS = 0.1;
+export { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PACER_BURST_MS, PIPELINE_PLAYBACK_GRACE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_FILL_MS, PLAYBACK_PROGRESS_INTERVAL_MS, } from "@alexkroman1/aai/internal";
 /**
- * Current state of the voice agent session.
+ * `getUserMedia` audio constraints for every capture path in this package.
+ *
+ * Defined once because four copies of this object drifted apart trivially, and
+ * the flags are not cosmetic — each one rewrites the signal before STT (and
+ * before the sync path's energy VAD) ever sees it:
+ *
+ * - **`autoGainControl: false`** — AGC continuously retargets level, which
+ *   means riding the noise floor up through silence. An energy VAD calibrated
+ *   against a moving floor is calibrated against nothing.
+ * - **`noiseSuppression: false`** / **`voiceIsolation: false`** — both discard
+ *   signal to make speech sound cleaner to a human, and both can gate a quiet
+ *   room to *exact* zeros, which is also what a dead microphone looks like
+ *   (see `MIC_SILENCE_PROBE_MS`).
+ * - **`echoCancellation: true`** — this one stays on. The mic is open while
+ *   the agent speaks (barge-in needs it), so without AEC the agent hears
+ *   itself and interrupts its own reply.
+ *
+ * Cast because `voiceIsolation` is newer than TypeScript's DOM lib.
+ *
+ * On `@alexkroman1/aai-ui/internal` rather than the root barrel, for the same
+ * reason as the audio budgets above: it is a framework decision with no
+ * `mountClient()` field to set, and the root is the authoring surface. A custom
+ * chrome that bypasses `mountClient()` and opens its own microphone reaches it there
+ * alongside the providers it also needs.
+ */
+export declare const VOICE_CAPTURE_CONSTRAINTS: MediaTrackConstraints;
+/**
+ * Current state of the voice agent session — the `state` field of
+ * {@link SessionSnapshot}, and what a chrome paints its status indicator from.
+ *
+ * @remarks
+ * The seven members, in the order a call passes through them:
+ *
+ * - `"disconnected"` — no socket. The state before the first `start()` and
+ *   after `disconnect()` / `end()`.
+ * - `"connecting"` — dialling. Covers the broker lookup and every automatic
+ *   reconnect attempt, so a session flickers back through it mid-call.
+ * - `"ready"` — the socket is open and the handshake is done, but no turn has
+ *   happened yet. **The default chrome paints this with the same live
+ *   indicator as `"listening"`**, which is deliberate — to a caller they are
+ *   the same "the agent is there" — but they are not the same thing, and a
+ *   session can wedge here (see `session/handshake.ts`).
+ * - `"listening"` — the microphone is open and the agent is waiting for the
+ *   caller. Check {@link SessionSnapshot.recording} for whether the mic is
+ *   actually live.
+ * - `"thinking"` — the caller's turn is committed and the agent is working:
+ *   the LLM step, and any tool calls under it.
+ * - `"speaking"` — the agent's reply is playing. A caller may still barge in;
+ *   the mic stays open throughout.
+ * - `"error"` — the session reported a failure. See
+ *   {@link SessionSnapshot.error} for what it was. A FATAL error latches here
+ *   until the next completed handshake, so a later frame cannot quietly paint
+ *   over the banner explaining a dead call.
  *
  * @public
  */
@@ -10,9 +62,20 @@ export type AgentState = "disconnected" | "connecting" | "ready" | "listening" |
 /**
  * A chat message exchanged between user and assistant.
  *
+ * `role` is `"user" | "assistant"` only — unlike the SDK's `Message`, there
+ * is no `"tool"` role here. Tool activity never arrives as messages: it is
+ * surfaced via `SessionSnapshot.toolCalls` (or `useEvent` for `ctx.send`
+ * events).
+ *
  * @public
  */
 export type ChatMessage = {
+    /**
+     * Monotonically increasing, session-unique message id assigned at append
+     * time. Stable across snapshot updates and window slides — use it as a
+     * render key.
+     */
+    id: number;
     /** The sender of the message. */
     role: "user" | "assistant";
     /** The text content of the message. */
@@ -24,14 +87,43 @@ export type ChatMessage = {
  * @public
  */
 export type ToolCallInfo = {
-    toolCallId: string;
-    toolName: string;
-    args: Record<string, unknown>;
+    callId: string;
+    name: string;
+    /**
+     * The tool's arguments, as the model sent them.
+     *
+     * Values are {@link DefaultToolResult} — `any` — for the same reason a tool
+     * *result* is: the shape is the author's own Zod schema, which the framework
+     * cannot see from here. As `Record<string, unknown>` the ordinary
+     * `toolCall.args.url` was a compile error in a client that runs correctly,
+     * and the escape hatch agents reached for next (`args as FetchJsonArgs`) is
+     * itself an error — TypeScript rejects the cast as insufficiently
+     * overlapping. That pair cost two build rounds in one run.
+     *
+     * Annotate at the read site for real checking:
+     * `const { url } = toolCall.args as { url: string }` is still available, and
+     * now actually compiles.
+     */
+    args: Record<string, DefaultToolResult>;
     status: "pending" | "done";
     result?: string | undefined;
-    /** Index in the messages array where this tool call should appear. */
-    afterMessageIndex: number;
+    /**
+     * Monotonically increasing, session-unique insertion sequence number.
+     * Tool calls in a snapshot are always sorted ascending by `seq`.
+     */
+    seq: number;
+    /**
+     * `id` of the last {@link ChatMessage} present when this tool call was
+     * inserted (`-1` when there were none). The tool call renders immediately
+     * after that message; if the anchor message has slid out of the retained
+     * window, the tool call renders before all messages.
+     */
+    afterMessageId: number;
 };
+/**
+ * Re-exported from `@alexkroman1/aai/protocol` (the canonical definition)
+ * so client code needs only this package.
+ */
 export type { SessionErrorCode } from "@alexkroman1/aai/protocol";
 /**
  * Error reported by the voice session.
@@ -43,50 +135,179 @@ export type SessionError = {
     readonly code: SessionErrorCode;
     /** A human-readable description of the error. */
     readonly message: string;
+    /**
+     * Whether the session is OVER.
+     *
+     * `false` means surface the message and keep the session interactive — a
+     * turn-level failure over a server that kept running. `true` means the call
+     * is dead and the microphone has been released.
+     *
+     * Required rather than optional, because the wire always carries it
+     * (`error.reported` declares `fatal: z.boolean()`) and a client that cannot
+     * tell the two apart has to guess which banner to render. It was dropped one
+     * line before reaching here for long enough that this type's own doc, and
+     * the reference page generated from it, described a field that did not
+     * exist.
+     */
+    readonly fatal: boolean;
 };
 /**
- * Minimal reactive container. Compatible with `@preact/signals` `Signal<T>`.
- *
- * @public
- */
-export type Reactive<T> = {
-    value: T;
-};
-/**
- * Options for creating a voice session.
+ * Options for creating a voice session — the shared field set accepted by
+ * both `mountClient()` and `createBrowserSession`. The one difference: `mountClient()`
+ * defaults `platformUrl` from `location.href`, while `createBrowserSession`
+ * requires it.
  *
  * @public
  */
 export type VoiceSessionOptions = {
     /** Base URL of the AAI platform server. */
     platformUrl: string;
-    /**
-     * Factory for creating reactive state containers.
-     * Defaults to a plain mutable wrapper. Pass `signal` from
-     * `@preact/signals` for automatic Preact component re-rendering.
-     */
-    reactiveFactory?: <T>(initial: T) => Reactive<T>;
-    /**
-     * Function to batch multiple reactive updates.
-     * Defaults to calling the function directly. Pass `batch` from
-     * `@preact/signals` for optimized batched updates.
-     */
-    batch?: (fn: () => void) => void;
     /**
      * Called when the server sends a session ID in the config message.
      * Use this to store the ID (e.g. in localStorage) for reconnection
      * via `resumeSessionId`.
+     *
+     * Treat session IDs as sensitive: whoever holds one can resume the
+     * session and read its replayed history. They travel as a WebSocket
+     * query parameter (browsers cannot set WS headers), so they may appear
+     * in proxy and server access logs — don't put them in shared URLs.
      */
     onSessionId?: ((sessionId: string) => void) | undefined;
     /**
-     * Session ID from a previous connection. When set, the server will
-     * attempt to restore persisted session state (if the agent has
-     * `persistence` enabled).
+     * Session ID from a previous connection. When set, the server resumes
+     * that session if its per-session state is still within the resume grace
+     * window (`SESSION_RESUME_GRACE_MS`), replaying history into the new
+     * connection. Sensitive — see {@link onSessionId}.
      */
     resumeSessionId?: string | undefined;
     /**
-     * WebSocket constructor override. Defaults to the native `WebSocket`.
-     * Primarily useful for testing with a mock WebSocket.
+     * Where the client is — e.g. a street address or `"Portland, Oregon"` — sent
+     * as `?location=` on every connection attempt (the first, a resume and each
+     * reconnect, brokered or not). Location-aware builtins read it: `open_meteo`
+     * falls back to it when the model names no place, and `google_places` biases
+     * its searches toward it.
+     *
+     * A string, or a getter asked on EVERY attempt — so a UI whose location can
+     * change (a settings field) passes `() => current` and the next reconnect
+     * carries the new value without a remount. An empty or `undefined` answer
+     * sends none. The server strips control characters and ignores a value
+     * longer than 200 characters.
+     *
+     * Treat it as personal data: like the session id it travels as a query
+     * parameter (browsers cannot set WebSocket headers), so it may appear in
+     * proxy and access logs.
+     */
+    location?: string | (() => string | undefined) | undefined;
+    /**
+     * The phone number of whoever owns this client — sent as `?phone=` on every
+     * connection attempt, with the same rules as {@link location}: a string or a
+     * getter asked per attempt, trimmed, an empty answer sends none. A tool reads
+     * it with `sessionClientPhone(ctx)`, e.g. to text the caller a link.
+     *
+     * Give it in E.164 form, with the `+` and country code (`"+1 503 555 0123"`):
+     * the server strips spaces, dashes, dots and parentheses and then needs a `+`
+     * and 8–15 digits. A bare `"5035550123"` is NOT assumed to be North American
+     * — it is dropped (the server logs that it was, never the value).
+     *
+     * The server takes it on the client's word. Personal data: it travels as a
+     * query parameter, so it may appear in proxy and access logs.
+     */
+    phone?: string | (() => string | undefined) | undefined;
+    /**
+     * The name of THIS client — a device id — sent as `?client=` on every
+     * connection attempt, with the same rules as {@link location}: a string or a
+     * getter asked per attempt, trimmed, an empty answer sends none.
+     *
+     * **`"auto"`** has the SDK mint and keep one: this browser's
+     * `browserClientId()` — `browser-<32 hex>`, stored in `localStorage` per
+     * agent URL (for this tab only where storage is unavailable). It is the id
+     * `useInbox()` holds the inbox under too, with a holder id per TAB so two tabs
+     * of one browser do not replace each other's inbox socket. Read it back with
+     * `useClientId()` or `session.identity.clientId()`. (So `"auto"` itself can
+     * never be a client id.)
+     *
+     * It is the id a tool reads with `sessionClientId(ctx)` and the one a client
+     * holds its `WS /inbox?client=` socket open under, so a tool can hand it to a
+     * workflow run and the run's `stepNotifyClient` reaches this client AFTER the
+     * voice session has ended (a reminder, a finished research job). Send the
+     * same id the inbox socket uses, or the run delivers to a client that is not
+     * listening.
+     *
+     * Letters, digits, `-` and `_`, at most 64 characters: the server checks it
+     * against the same pattern the inbox uses and ignores one that does not
+     * match — the session still opens, it just has no client id.
+     *
+     * It is also the key of this client's DURABLE conversation: every connection
+     * that sends it is seeded with that client's earlier sessions. The server
+     * takes it on the client's word and authenticates nothing, so on a server
+     * reachable from a network (a LAN-listening dev server, a self-hosted one)
+     * the id is the ONLY credential for that history — anyone who can reach the
+     * server and knows the id reads what was said. Use an unguessable id.
+     */
+    client?: string | (() => string | undefined) | undefined;
+    /**
+     * Open the microphone when the session connects, rather than once the
+     * server has configured it, and send what the caller said in between ahead
+     * of the live audio — so an opener spoken while the agent is still joining
+     * (a handshake, or a sandbox boot on the platform) reaches it instead of
+     * being lost. The latest 10 seconds are kept.
+     *
+     * Default `true`. `false` asks for the microphone only after the server's
+     * `config` frame, as before; a UI that wants the permission prompt to
+     * follow its own greeting might.
+     */
+    preConnectAudio?: boolean | undefined;
+    /**
+     * The session ticket this client presents — for a server that requires one
+     * (`AAI_SESSION_SECRET`, or `createSessionAuth()` on
+     * `@alexkroman1/aai-runtime/auth`).
+     *
+     * A string, or a getter asked on EVERY connection attempt — the first, each
+     * reconnect and each resume — so a short-lived ticket (60 s by default) is
+     * fresh each time. Fetch it from your own backend, which checks its own login
+     * and mints with `createSessionToken()`; the secret must never reach the
+     * browser. The getter is told the session the attempt RESUMES (`undefined`
+     * for a new one), so a backend can bind a resume ticket to it
+     * (`createSessionToken({ sessionId })`) — what a resume needs after the
+     * server restarted.
+     *
+     * It travels in `Sec-WebSocket-Protocol` as `aai.auth.<ticket>` beside the
+     * plain `aai.session` protocol, never in the URL, so it stays out of access
+     * logs (a value that is not a valid protocol token falls back to `?token=`).
+     * An empty or `undefined` answer sends none, and so does a getter that throws
+     * or rejects: the attempt still dials, and a server that requires a ticket
+     * refuses it with a reason. Give a fetch inside the getter a deadline — the
+     * attempt waits for it. With an injected {@link WebSocket} the getter must
+     * answer synchronously.
+     *
+     * When omitted, a ticket the server's `client-config` issued is used — which
+     * `aai dev` does for its own client when `AAI_SESSION_SECRET` is set.
+     *
+     * @example
+     * ```ts
+     * import { mountClient } from "@alexkroman1/aai-ui";
+     *
+     * mountClient({
+     *   token: async ({ sessionId }) => {
+     *     const res = await fetch("/my-backend/session-ticket", {
+     *       method: "POST",
+     *       body: JSON.stringify({ sessionId }),
+     *       signal: AbortSignal.timeout(5000),
+     *     });
+     *     return (await res.json()).token;
+     *   },
+     * });
+     * ```
+     */
+    token?: string | ((attempt: {
+        readonly sessionId: string | undefined;
+    }) => string | undefined | Promise<string | undefined>) | undefined;
+    /**
+     * WebSocket constructor override. Primarily useful for testing with a mock
+     * WebSocket. When omitted, the session uses a reconnecting WebSocket
+     * (partysocket) that retries with exponential backoff after an unexpected
+     * close and resumes the session; an injected constructor is used as-is and
+     * never reconnects on its own.
      */
     WebSocket?: WebSocketConstructor | undefined;
 };
@@ -99,3 +320,20 @@ export type WebSocketConstructor = {
     new (url: string | URL, protocols?: string | string[]): WebSocket;
     readonly OPEN: number;
 };
+/**
+ * Theme color overrides for the AAI UI components.
+ *
+ * @public
+ */
+export type ClientTheme = {
+    /** Background color, also painted on `html`/`body`. Default: `#FBF8F2`. */
+    bg?: string;
+    /** Primary accent color. Default: `#3F2BC1`. */
+    primary?: string;
+    /** Main text color. Default: `#1B1A18`. */
+    text?: string;
+    /** Surface/card color. Default: `#FFFFFF`. */
+    surface?: string;
+    /** Border color. Default: `#DCD7CC`. */
+    border?: string;
+};