@alexkroman1/aai-ui 13.3.0 → 14.0.0

package/dist/components/form-fields.d.ts

@@ -1,5 +1,5 @@
 import type { InputHTMLAttributes, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from "react";
-import type { FieldShell, FileRead } from "./form-types.ts";
+import type { FieldShell, FileReadMode } from "./form-types.ts";
 /**
  * Label + control + hint, in the layout every field here uses.
  *
@@ -47,7 +47,7 @@ export declare function Field({ label, hint, htmlFor, className, children, }: {
  *
  * @public
  */
-export declare function TextField({ name, label, hint, className, ...rest }: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className">): import("react").JSX.Element;
+export declare function TextField(props: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className">): import("react").JSX.Element;
 /**
  * A number input. Contributes a NUMBER to {@link FormValues}, or nothing when
  * left empty.
@@ -60,7 +60,7 @@ export declare function TextField({ name, label, hint, className, ...rest }: Fie
  *
  * @public
  */
-export declare function NumberField({ name, label, hint, className, ...rest }: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;
+export declare function NumberField(props: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;
 /**
  * A multi-line text input.
  *
@@ -116,14 +116,14 @@ export declare function CheckboxField({ name, label, hint, className, ...rest }:
  * travel in it. With `upload` the field contributes the `File` itself,
  * `useWorkflowSubmit` stores it through `POST /workflows/uploads` before
  * starting the run, and the input carries the upload id — which a step reads
- * windows of with `readUpload`. Declaring the property in the workflow's
+ * windows of with `stepReadUpload`. Declaring the property in the workflow's
  * `uploads` list makes `<WorkflowFields>` render exactly this, so a declared
  * form needs no file markup at all.
  *
  * **Without it the field describes the file and does not read it.** `read`
  * exists for the cases where the bytes really are small and really are the
  * input — a CSV of ids, a config — and the size is the author's to check. See
- * {@link FileRead} for the four values; `upload` is shorthand for
+ * {@link FileReadMode} for the four values; `upload` is shorthand for
  * `read="upload"`.
  *
  * Otherwise accepts every `<input>` attribute except `name`, `className` and
@@ -136,7 +136,7 @@ export declare function CheckboxField({ name, label, hint, className, ...rest }:
  * @public
  */
 export declare function FileField({ name, label, hint, className, read, upload, ...rest }: FieldShell & {
-    read?: FileRead;
+    read?: FileReadMode;
     /** Shorthand for `read="upload"` — see above. */
     upload?: boolean;
 } & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;

package/dist/components/form-types.d.ts

@@ -46,7 +46,7 @@ export type FileValue = {
  *
  * @public
  */
-export type FileRead = "none" | "text" | "dataUrl" | "upload";
+export type FileReadMode = "none" | "text" | "dataUrl" | "upload";
 /**
  * The props every field in `form.tsx` shares.
  *

package/dist/components/form.d.ts

@@ -2,7 +2,7 @@ import type { ButtonHTMLAttributes, FormHTMLAttributes, ReactNode } from "react"
 import { type ButtonSize, type ButtonVariant } from "./button.tsx";
 import type { FormValues } from "./form-types.ts";
 export { CheckboxField, Field, FileField, NumberField, SelectField, TextAreaField, TextField, } from "./form-fields.tsx";
-export type { FieldShell, FileRead, FileValue, FormValues } from "./form-types.ts";
+export type { FieldShell, FileReadMode, FileValue, FormValues } from "./form-types.ts";
 /** Props of {@link Form}. */
 export type FormProps = {
     /**

package/dist/components/message-list.js

@@ -1,3 +1,3 @@
-import { t as MessageList } from "../message-list-C0pL7x41.js";
+import { t as MessageList } from "../message-list-CdOnSh5m.js";
 import "../context.js";
 export { MessageList };

package/dist/components/session-error-banner.d.ts

@@ -0,0 +1,69 @@
+import type { ReactNode } from "react";
+/**
+ * Props of {@link SessionErrorBanner}.
+ *
+ * Every field is optional, so `<SessionErrorBanner />` is the whole call. It is
+ * a NAMED type all the same, for the reason `ControlsProps` and
+ * `ConsoleShellProps` are: an inline object literal in the signature leaves a
+ * `createElement(SessionErrorBanner, { className })` caller unable to infer the
+ * props at all, and gives the reference page nothing to link to.
+ *
+ * @public
+ */
+export type SessionErrorBannerProps = {
+    /** Additional CSS class names for the banner, appended to its own. */
+    className?: string | undefined;
+};
+/**
+ * The announced banner for a failed session: the error's message and code, or
+ * nothing at all when the session is fine.
+ *
+ * **This used to be four lines inside `ConsoleShell`, and that is why it is its
+ * own component.** The banner was the reason `ConsoleShell` was published —
+ * `role="alert"` is the one part of that component a reviewer cannot see is
+ * missing, since per the `fatalError` latch in `session-core.ts` the banner is
+ * the ONLY remaining signal a session died (the state eyebrow beside it goes
+ * back to reading like a live session), and a screen reader is never told an
+ * unannounced one appeared. But `ConsoleShell` is a whole FRAME: a centred
+ * `max-w-190` column with its own header and footer. Every full-bleed chrome —
+ * a two-pane board, a CRT — therefore could not adopt it, rebuilt the banner
+ * instead, and the three that did had ALREADY drifted: one rendered
+ * `ERROR: {message}` and dropped the code entirely, one `ERROR: {message}
+ * ({code})`, one `{message} ({code})`. Splitting the banner out is what lets a
+ * chrome take the announced-error decision without taking the layout, and
+ * `ConsoleShell` composes this rather than keeping a second copy, so the two
+ * cannot drift again.
+ *
+ * **It reads the session itself.** There is no `error` prop: a banner that
+ * takes its text from the caller is a banner a caller can forget to wire, which
+ * is exactly the failure above with an extra step. It subscribes narrowly via
+ * {@link useSessionError}, so a page that renders it does not re-render with
+ * the transcript.
+ *
+ * **The code is shown, always.** `SessionError.code` is the eight-member wire
+ * union — it is what a user pastes into a bug report and the only part of the
+ * error that is stable across wordings — and the chrome that dropped it left
+ * its readers with a sentence and no way to say which failure it was.
+ *
+ * Must be rendered inside the providers `client()` installs.
+ *
+ * @example A full-bleed chrome that wants the banner and not the frame
+ * ```tsx
+ * import { SessionErrorBanner } from "@alexkroman1/aai-ui";
+ *
+ * function Board() {
+ *   return (
+ *     <div className="grid grid-cols-[1fr_320px] h-screen">
+ *       <main>…</main>
+ *       <aside>…</aside>
+ *       <SessionErrorBanner className="col-span-2" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link SessionErrorBannerProps}.
+ *
+ * @public
+ */
+export declare function SessionErrorBanner({ className }: SessionErrorBannerProps): ReactNode;

package/dist/components/start-screen.js

@@ -1,5 +1,5 @@
 import { useSessionCore, useSessionSelector, useTheme } from "../context.js";
-import { r as inkTint } from "../_colors-CZ6OlPbL.js";
+import { a as inkTint } from "../_colors-CpZO-88A.js";
 import { Button } from "./button.js";
 import { t as AaiLogo } from "../aai-logo-CFlomZlS.js";
 import { t as Eyebrow } from "../eyebrow-UfmSz9yy.js";

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

@@ -1,3 +1,3 @@
 import "../context.js";
-import { t as ToolCallBlock } from "../tool-call-block-Bunc6rCw.js";
+import { t as ToolCallBlock } from "../tool-call-block-C2t_5fpp.js";
 export { ToolCallBlock };

package/dist/components/tool-config-context.d.ts

@@ -8,7 +8,7 @@ export type ToolDisplayConfig = Record<string, {
     label?: string;
 }>;
 /**
- * Context for tool display configuration. Installed by `client()` from
+ * Context for tool display configuration. Installed by `mountClient()` from
  * `ClientConfig.tools`; the built-in components read it via `useToolConfig`.
  *
  * @internal

package/dist/components/workflow-progress.d.ts

@@ -1,17 +1,17 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import type { WorkflowApi } from "../workflow-client.ts";
 /**
  * What a run has said so far, rendered.
  *
  * The complement of a status line, and the reason both exist: a run is
  * `running` for its whole life, so a one-round job and a ten-round one look
- * identical while they happen. These lines come from the run itself (`report()`
+ * identical while they happen. These lines come from the run itself (`stepReport()`
  * in a `"use step"` body), which is the only channel a workflow has before it
  * produces an output.
  *
- * Three rules are baked in, and they are why this is a component rather than
+ * Four rules are baked in, and they are why this is a component rather than
  * three lines each page writes for itself — the two templates that had written
- * it had written all three, comments included:
+ * it had written three of them, comments included:
  *
  * - **It renders nothing until there is something to render.** `supported` is
  *   what keeps this from being an empty box forever on an agent deployed before
@@ -25,6 +25,13 @@ import type { WorkflowApi } from "../workflow-client.ts";
  *   or opening a finished run tomorrow — shows how it got there rather than an
  *   empty box. That is `useWorkflowProgress`'s doing; this is what makes it
  *   visible.
+ * - **They are ANNOUNCED**, for the reason the first paragraph gives: this is
+ *   the only channel a run has before it produces an output, and a `<pre>` that
+ *   grows is a silent one. A screen-reader user pressing "Digest" got nothing
+ *   between the click and a terminal state minutes later — no "fetching", no
+ *   "summarising", no evidence the button did anything. See `role="log"` below.
+ *   The six pages that render this pass only `className`, so no template could
+ *   have fixed it locally; that is what makes it this component's job.
  *
  * @example
  * ```tsx

package/dist/context.d.ts

@@ -1,34 +1,45 @@
 import { type ReactNode } from "react";
-import type { SessionCore, SessionSnapshot } from "./session-core-types.ts";
-import type { ClientTheme } from "./types.ts";
+import type { BrowserSession, SessionSnapshot } from "./session-core-types.ts";
+import type { AgentState, ClientTheme, SessionError } from "./types.ts";
 /**
- * Provides the {@link SessionCore} the session hooks read. `client()`
+ * Provides the {@link BrowserSession} the session hooks read. `mountClient()`
  * installs it automatically; a custom tree only needs it when bypassing
- * `client()` and mounting React itself.
+ * `mountClient()` and mounting React itself.
  *
  * @internal
  */
-export declare function SessionProvider({ value, children }: {
-    value: SessionCore;
+export declare function SessionProvider({ value, children, }: {
+    value: BrowserSession;
     children?: ReactNode;
-}): import("react").FunctionComponentElement<import("react").ProviderProps<SessionCore | null>>;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<BrowserSession | null>>;
+/**
+ * The session's control methods, and nothing else — what a `client.tsx` may
+ * legitimately CALL on a session, as against what it may read.
+ *
+ * Declared once and merged into {@link Session} rather than written out at both
+ * places: the two lists have to be the same list, and a member added to one and
+ * not the other is a hook that cannot do what `useSession()` can.
+ *
+ * Method signatures come from {@link BrowserSession} — one source of truth.
+ *
+ * @public
+ */
+export type SessionActions = Pick<BrowserSession, "start" | "cancel" | "resetState" | "reset" | "restart" | "disconnect" | "toggle" | "end">;
 /**
  * What {@link useSession} returns: the live {@link SessionSnapshot} fields
  * (`state`, `messages`, `toolCalls`, `agentState`, live transcripts, `error`,
  * `apiUrl`, `started`/`running`/`recording`, …) merged with the session's
- * control methods (`start`, `toggle`, `reset`, `resetState`, `disconnect`,
- * `cancel`, `end`).
+ * control methods (`start`, `toggle`, `reset`, `restart`, `resetState`,
+ * `disconnect`, `cancel`, `end`).
  *
  * Note there is no text-send method — sessions are voice-only; the only
  * client→server inputs are audio and the control methods above.
  *
- * Method signatures come from {@link SessionCore} — one source of truth.
- *
  * @public
  */
-export type Session = SessionSnapshot & Pick<SessionCore, "start" | "cancel" | "resetState" | "reset" | "disconnect" | "toggle" | "end">;
+export type Session = SessionSnapshot & SessionActions;
 /**
- * Return the raw {@link SessionCore} from context without subscribing to
+ * Return the raw {@link BrowserSession} from context without subscribing to
  * snapshot changes. Useful for accessing stable methods (`start`, `toggle`,
  * `reset`, …) from components that select narrow state via
  * {@link useSessionSelector}.
@@ -36,15 +47,73 @@ export type Session = SessionSnapshot & Pick<SessionCore, "start" | "cancel" | "
  * Not part of the package's public export surface — internal to aai-ui
  * components.
  */
-export declare function useSessionCore(): SessionCore;
+export declare function useSessionCore(): BrowserSession;
+/**
+ * The session's control methods — `start`, `cancel`, `resetState`, `reset`,
+ * `restart`, `disconnect`, `toggle`, `end` — with **no snapshot
+ * subscription**.
+ *
+ * This is the narrow half of {@link useSession}, and it is the half a custom
+ * chrome could not reach. `<Controls>` and `<StartScreen>` in this package pair
+ * a one-field `useSessionSelector` with this package's own `useSessionCore`
+ * (`context.ts`, unpublished); a `client.tsx`
+ * could not, because that hook is not published — so a footer needing `start`
+ * and `toggle` held a WHOLE-SNAPSHOT `useSession()`, and `session-core.ts`
+ * rebuilds the snapshot object on every change. Measured consequence: four
+ * components across three templates re-rendered on every STT partial and every
+ * streaming delta, in files whose every other component is narrowly subscribed
+ * on purpose. One of them (`infocom-adventure`'s `TitleScreen`) reads nothing
+ * from the snapshot at all and subscribes to all of it for `session.start`.
+ *
+ * **Why publishing this does not reopen what `/internal` closed.**
+ * `useSessionCore` hands back the STORE — `subscribe`, `getSnapshot`,
+ * `connect`, `Symbol.dispose` — which is the framework's own plumbing, the same
+ * category as the providers and `buildAgentUrl` that live on
+ * `@alexkroman1/aai-ui/internal`. A client that holds it can subscribe out of
+ * band of React, dial a socket the mount did not, and dispose the session under
+ * the tree that is rendering it. What comes back from here is the SAME eight
+ * methods `useSession()` already publishes on its result, built into a fresh
+ * object rather than passed through, so the store is not reachable from it.
+ * There is no new capability here — only the existing one without the
+ * subscription tax.
+ *
+ * Identity-stable per core, so it is safe in a dependency array and in a
+ * `memo()` child's props: the methods are closures created once by
+ * `createBrowserSession`, and the object wrapping them is memoized on the core.
+ *
+ * Throws outside the provider `mountClient()` installs, like every session hook.
+ *
+ * @example A footer that acts on the session without re-rendering with it
+ * ```tsx
+ * import { useSessionActions, useSessionSelector } from "@alexkroman1/aai-ui";
+ *
+ * function Footer() {
+ *   // Two narrow subscriptions and no snapshot read: this row re-renders when
+ *   // `running` flips, and not on every transcript delta.
+ *   const running = useSessionSelector((s) => s.running);
+ *   const { toggle, end } = useSessionActions();
+ *   return (
+ *     <>
+ *       <button onClick={toggle}>{running ? "Pause" : "Resume"}</button>
+ *       <button onClick={end}>Hang up</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @returns The eight control methods — see {@link SessionActions}.
+ *
+ * @public
+ */
+export declare function useSessionActions(): SessionActions;
 /**
  * Return the live {@link Session}: the current snapshot fields plus the
  * control methods (`start`, `toggle`, `reset`, `resetState`, `disconnect`,
  * `cancel`, `end`).
  *
- * Throws if used outside the provider `client()` installs (the error names
+ * Throws if used outside the provider `mountClient()` installs (the error names
  * `<SessionProvider>` — you only mount that yourself when bypassing
- * `client()`). Re-renders the component on *every* snapshot change; for a
+ * `mountClient()`). Re-renders the component on *every* snapshot change; for a
  * component that reads one field, prefer {@link useSessionSelector} for a
  * targeted subscription.
  *
@@ -94,9 +163,63 @@ export declare function useSession(): Session;
  */
 export declare function useSessionSelector<T>(selector: (snapshot: SessionSnapshot) => T, isEqual?: (a: T, b: T) => boolean): T;
 /**
- * Provides the theme the components read via `useTheme`. `client()` installs
+ * The agent's live {@link AgentState} — `disconnected`, `connecting`, `ready`,
+ * `listening`, `thinking`, `speaking`, `error` — on its own narrow
+ * subscription.
+ *
+ * `useSessionSelector((s) => s.state)` spelled once. It is one of exactly two
+ * snapshot fields that more than one custom chrome ever selects (the other is
+ * {@link useSessionError}), and it had been written inline at eight sites —
+ * including inside this package and, worse, in `ConsoleShell`'s own `@example`,
+ * which taught the inline form to everyone who read it.
+ *
+ * **Named `useSessionStatus`, not `useSessionState`.** `useAgentState` is the
+ * SLOT hook — the agent's own synced application state, whatever a
+ * `sessionSlot()` projects — and `AgentState` here is the phase of the CALL.
+ * Two different concepts one letter apart, so the shorter-sounding name is the
+ * one deliberately not taken.
+ *
+ * Pair it with {@link AGENT_STATE_LABELS} for a rendered word; the raw member
+ * is a wire value, not a label.
+ *
+ * @example
+ * ```tsx
+ * import { AGENT_STATE_LABELS, useSessionStatus } from "@alexkroman1/aai-ui";
+ *
+ * function StatusDot() {
+ *   const status = useSessionStatus();
+ *   return <span data-state={status}>{AGENT_STATE_LABELS[status]}</span>;
+ * }
+ * ```
+ *
+ * @returns The current agent state.
+ *
+ * @public
+ */
+export declare function useSessionStatus(): AgentState;
+/**
+ * The session's current {@link SessionError}, or `null` when there is none, on
+ * its own narrow subscription.
+ *
+ * The other half of {@link useSessionStatus} — the second of the two fields a
+ * custom chrome reads over and over, and the one whose absence is invisible:
+ * per the `fatalError` latch in `session-core.ts` the error is the ONLY
+ * remaining signal that a session died, since the state beside it goes back to
+ * reading like a live one.
+ *
+ * A chrome rendering it owes `role="alert"` — which is what
+ * {@link SessionErrorBanner} is for, and why reaching for that beats reaching
+ * for this.
+ *
+ * @returns The current error, or `null`.
+ *
+ * @public
+ */
+export declare function useSessionError(): SessionError | null;
+/**
+ * Provides the theme the components read via `useTheme`. `mountClient()` installs
  * it automatically (from `ClientConfig.theme`); a custom tree only needs it
- * when bypassing `client()` and mounting React itself.
+ * when bypassing `mountClient()` and mounting React itself.
  *
  * @internal
  */
@@ -110,7 +233,7 @@ export declare function ThemeProvider({ value, children, }: {
  * provider is present, so components can call it unconditionally.
  *
  * This is how a custom component stays on the agent's palette: a
- * `client({ theme })` override reaches it here, where a hardcoded colour or a
+ * `mountClient({ theme })` override reaches it here, where a hardcoded colour or a
  * Tailwind class cannot see it.
  *
  * @example

package/dist/context.js

@@ -10,9 +10,9 @@ const DEFAULT_THEME = {
 };
 const SessionCtx = createContext(null);
 /**
-* Provides the {@link SessionCore} the session hooks read. `client()`
+* Provides the {@link BrowserSession} the session hooks read. `mountClient()`
 * installs it automatically; a custom tree only needs it when bypassing
-* `client()` and mounting React itself.
+* `mountClient()` and mounting React itself.
 *
 * @internal
 */
@@ -20,7 +20,7 @@ function SessionProvider({ value, children }) {
 	return createElement(SessionCtx.Provider, { value }, children);
 }
 /**
-* Return the raw {@link SessionCore} from context without subscribing to
+* Return the raw {@link BrowserSession} from context without subscribing to
 * snapshot changes. Useful for accessing stable methods (`start`, `toggle`,
 * `reset`, …) from components that select narrow state via
 * {@link useSessionSelector}.
@@ -34,13 +34,83 @@ function useSessionCore() {
 	return core;
 }
 /**
+* The session's control methods — `start`, `cancel`, `resetState`, `reset`,
+* `restart`, `disconnect`, `toggle`, `end` — with **no snapshot
+* subscription**.
+*
+* This is the narrow half of {@link useSession}, and it is the half a custom
+* chrome could not reach. `<Controls>` and `<StartScreen>` in this package pair
+* a one-field `useSessionSelector` with this package's own `useSessionCore`
+* (`context.ts`, unpublished); a `client.tsx`
+* could not, because that hook is not published — so a footer needing `start`
+* and `toggle` held a WHOLE-SNAPSHOT `useSession()`, and `session-core.ts`
+* rebuilds the snapshot object on every change. Measured consequence: four
+* components across three templates re-rendered on every STT partial and every
+* streaming delta, in files whose every other component is narrowly subscribed
+* on purpose. One of them (`infocom-adventure`'s `TitleScreen`) reads nothing
+* from the snapshot at all and subscribes to all of it for `session.start`.
+*
+* **Why publishing this does not reopen what `/internal` closed.**
+* `useSessionCore` hands back the STORE — `subscribe`, `getSnapshot`,
+* `connect`, `Symbol.dispose` — which is the framework's own plumbing, the same
+* category as the providers and `buildAgentUrl` that live on
+* `@alexkroman1/aai-ui/internal`. A client that holds it can subscribe out of
+* band of React, dial a socket the mount did not, and dispose the session under
+* the tree that is rendering it. What comes back from here is the SAME eight
+* methods `useSession()` already publishes on its result, built into a fresh
+* object rather than passed through, so the store is not reachable from it.
+* There is no new capability here — only the existing one without the
+* subscription tax.
+*
+* Identity-stable per core, so it is safe in a dependency array and in a
+* `memo()` child's props: the methods are closures created once by
+* `createBrowserSession`, and the object wrapping them is memoized on the core.
+*
+* Throws outside the provider `mountClient()` installs, like every session hook.
+*
+* @example A footer that acts on the session without re-rendering with it
+* ```tsx
+* import { useSessionActions, useSessionSelector } from "@alexkroman1/aai-ui";
+*
+* function Footer() {
+*   // Two narrow subscriptions and no snapshot read: this row re-renders when
+*   // `running` flips, and not on every transcript delta.
+*   const running = useSessionSelector((s) => s.running);
+*   const { toggle, end } = useSessionActions();
+*   return (
+*     <>
+*       <button onClick={toggle}>{running ? "Pause" : "Resume"}</button>
+*       <button onClick={end}>Hang up</button>
+*     </>
+*   );
+* }
+* ```
+*
+* @returns The eight control methods — see {@link SessionActions}.
+*
+* @public
+*/
+function useSessionActions() {
+	const core = useSessionCore();
+	return useMemo(() => ({
+		start: core.start,
+		cancel: core.cancel,
+		resetState: core.resetState,
+		reset: core.reset,
+		restart: core.restart,
+		disconnect: core.disconnect,
+		toggle: core.toggle,
+		end: core.end
+	}), [core]);
+}
+/**
 * Return the live {@link Session}: the current snapshot fields plus the
 * control methods (`start`, `toggle`, `reset`, `resetState`, `disconnect`,
 * `cancel`, `end`).
 *
-* Throws if used outside the provider `client()` installs (the error names
+* Throws if used outside the provider `mountClient()` installs (the error names
 * `<SessionProvider>` — you only mount that yourself when bypassing
-* `client()`). Re-renders the component on *every* snapshot change; for a
+* `mountClient()`). Re-renders the component on *every* snapshot change; for a
 * component that reads one field, prefer {@link useSessionSelector} for a
 * targeted subscription.
 *
@@ -60,16 +130,11 @@ function useSessionCore() {
 function useSession() {
 	const core = useSessionCore();
 	const snapshot = useSyncExternalStore(core.subscribe, core.getSnapshot);
+	const actions = useSessionActions();
 	return useMemo(() => ({
 		...snapshot,
-		start: core.start,
-		cancel: core.cancel,
-		resetState: core.resetState,
-		reset: core.reset,
-		disconnect: core.disconnect,
-		toggle: core.toggle,
-		end: core.end
-	}), [snapshot, core]);
+		...actions
+	}), [snapshot, actions]);
 }
 /**
 * Subscribe to a narrow slice of the session snapshot.
@@ -105,11 +170,84 @@ function useSessionSelector(selector, isEqual = Object.is) {
 	const core = useSessionCore();
 	return useSyncExternalStoreWithSelector(core.subscribe, core.getSnapshot, core.getSnapshot, selector, isEqual);
 }
+/**
+* The two selectors below are MODULE-SCOPE functions, and that is load-bearing
+* rather than tidy.
+*
+* `useSyncExternalStoreWithSelector` caches its selection keyed on the selector
+* it was handed: a fresh arrow per render invalidates that memo every render,
+* so the selector re-runs and the `isEqual` short-circuit protects only the
+* re-RENDER, never the work. Hoisting them means the two fields more than one
+* chrome ever reads are selected by one stable function for the life of the
+* program — which is also the thing a caller writing the arrow inline cannot
+* do for themselves, and the reason these two are hooks at all rather than a
+* documented one-liner.
+*/
+const selectState = (s) => s.state;
+const selectError = (s) => s.error;
+/**
+* The agent's live {@link AgentState} — `disconnected`, `connecting`, `ready`,
+* `listening`, `thinking`, `speaking`, `error` — on its own narrow
+* subscription.
+*
+* `useSessionSelector((s) => s.state)` spelled once. It is one of exactly two
+* snapshot fields that more than one custom chrome ever selects (the other is
+* {@link useSessionError}), and it had been written inline at eight sites —
+* including inside this package and, worse, in `ConsoleShell`'s own `@example`,
+* which taught the inline form to everyone who read it.
+*
+* **Named `useSessionStatus`, not `useSessionState`.** `useAgentState` is the
+* SLOT hook — the agent's own synced application state, whatever a
+* `sessionSlot()` projects — and `AgentState` here is the phase of the CALL.
+* Two different concepts one letter apart, so the shorter-sounding name is the
+* one deliberately not taken.
+*
+* Pair it with {@link AGENT_STATE_LABELS} for a rendered word; the raw member
+* is a wire value, not a label.
+*
+* @example
+* ```tsx
+* import { AGENT_STATE_LABELS, useSessionStatus } from "@alexkroman1/aai-ui";
+*
+* function StatusDot() {
+*   const status = useSessionStatus();
+*   return <span data-state={status}>{AGENT_STATE_LABELS[status]}</span>;
+* }
+* ```
+*
+* @returns The current agent state.
+*
+* @public
+*/
+function useSessionStatus() {
+	return useSessionSelector(selectState);
+}
+/**
+* The session's current {@link SessionError}, or `null` when there is none, on
+* its own narrow subscription.
+*
+* The other half of {@link useSessionStatus} — the second of the two fields a
+* custom chrome reads over and over, and the one whose absence is invisible:
+* per the `fatalError` latch in `session-core.ts` the error is the ONLY
+* remaining signal that a session died, since the state beside it goes back to
+* reading like a live one.
+*
+* A chrome rendering it owes `role="alert"` — which is what
+* {@link SessionErrorBanner} is for, and why reaching for that beats reaching
+* for this.
+*
+* @returns The current error, or `null`.
+*
+* @public
+*/
+function useSessionError() {
+	return useSessionSelector(selectError);
+}
 const ThemeCtx = createContext(DEFAULT_THEME);
 /**
-* Provides the theme the components read via `useTheme`. `client()` installs
+* Provides the theme the components read via `useTheme`. `mountClient()` installs
 * it automatically (from `ClientConfig.theme`); a custom tree only needs it
-* when bypassing `client()` and mounting React itself.
+* when bypassing `mountClient()` and mounting React itself.
 *
 * @internal
 */
@@ -208,7 +346,7 @@ function useThemeStyles(theme) {
 * provider is present, so components can call it unconditionally.
 *
 * This is how a custom component stays on the agent's palette: a
-* `client({ theme })` override reaches it here, where a hardcoded colour or a
+* `mountClient({ theme })` override reaches it here, where a hardcoded colour or a
 * Tailwind class cannot see it.
 *
 * @example
@@ -233,4 +371,4 @@ function useTheme() {
 	return useContext(ThemeCtx);
 }
 //#endregion
-export { SessionProvider, ThemeProvider, useSession, useSessionCore, useSessionSelector, useTheme };
+export { SessionProvider, ThemeProvider, useSession, useSessionActions, useSessionCore, useSessionError, useSessionSelector, useSessionStatus, useTheme };

package/dist/default-client/assets/{audio-BuDICbPf.js → audio-9zQsNc1w.js}

@@ -1 +1 @@
-import{a as e,o as t}from"./client-audio-constants-CP13UQZt.js";var n={echoCancellation:!0,noiseSuppression:!1,autoGainControl:!1,voiceIsolation:!1};function r(e,t,n){if(e!==t)throw Error(`Browser refused the ${n} sample rate: asked for ${t} Hz, got ${e} Hz`)}function i(e){let t=Error(`Audio ${e} worklet crashed`);return console.error(`[aai-ui]`,t.message),t}function a(e){e.then(e=>{for(let t of e.getTracks())t.stop()}).catch(()=>{})}function o(e,t,n){let r=new AudioWorkletNode(e,`capture-processor`,{channelCount:1,channelCountMode:`explicit`}),i=null;return r.port.onmessage=e=>{let r=e.data;r.event===`chunk`&&r.buffer?t(r.buffer):r.event===`silent`?n?.():r.event===`stopped`&&(i?.(),i=null)},{node:r,start(){r.port.postMessage({event:`start`})},stop(){let{promise:e,resolve:t}=Promise.withResolvers(),n=setTimeout(t,250);return i=()=>{clearTimeout(n),t()},r.port.postMessage({event:`stop`}),e}}}async function s(s){let{sttSampleRate:c,ttsSampleRate:l,captureWorkletSrc:u,playbackWorkletSrc:d,onMicData:f,onError:p,onPlaybackStats:m,onPlaybackProgress:h,onMicSilent:g}=s,_=new AudioContext({sampleRate:l,latencyHint:`playback`}),v=c===l,y=v?_:new AudioContext({sampleRate:c,latencyHint:`interactive`});async function b(){let e=v?[_]:[_,y];await Promise.all(e.map(e=>e.close().catch(e=>{console.warn(`AudioContext close failed:`,e)})))}let x=navigator.mediaDevices.getUserMedia({audio:{deviceId:{ideal:`default`},...n}}),S;try{[S]=await Promise.all([x,_.resume(),y.resume(),y.audioWorklet.addModule(u),_.audioWorklet.addModule(d)]),r(y.sampleRate,c,`capture`),r(_.sampleRate,l,`playback`)}catch(e){throw a(x),await b(),e}let C=y.createMediaStreamSource(S),w=o(y,f,g);C.connect(w.node),w.node.onprocessorerror=()=>p?.(i(`capture`)),w.start();let T=null,E=null,D=0,O=null,k=new AbortController;function A(){E?.(),E=null,O=null}function j(e){e.stats&&e.stats.concealedSamples>0&&m?.(e.stats),e.reason!==`interrupt`&&(O===null||e.turn===O)&&A()}function M(){if(T)return T;let e=new AudioWorkletNode(_,`playback-processor`);return e.connect(_.destination),e.port.onmessage=e=>{e.data.event===`stop`?j(e.data):e.data.event===`progress`&&h?.(e.data.bufferedMs)},e.onprocessorerror=()=>{let e=i(`playback`);A(),p?.(e)},T=e,e}let N={enqueue(e){k.signal.aborted||e.byteLength!==0&&M().port.postMessage({event:`write`,buffer:new Uint8Array(e)},[e])},done(){if(!T)return Promise.resolve();let n=++D;if(T.port.postMessage({event:`done`,turn:n}),_.state!==`running`)return O=null,Promise.resolve();let{promise:r,resolve:i}=Promise.withResolvers();E?.();let a=()=>{clearInterval(o),clearTimeout(s),E===a&&(E=null,O=null),i()},o=setInterval(()=>{_.state!==`running`&&a()},t),s=setTimeout(a,e);return E=a,O=n,r},flush(){T&&(A(),T.port.postMessage({event:`interrupt`}))},async close(){if(!k.signal.aborted){k.abort(),await w.stop(),C.disconnect(),w.node.disconnect(),T&&T.disconnect();for(let e of S.getTracks())e.stop();await b()}},async[Symbol.asyncDispose](){await N.close()}};return N}export{s as createVoiceIO};
+import{a as e,o as t}from"./client-audio-constants-CP13UQZt.js";var n={echoCancellation:!0,noiseSuppression:!1,autoGainControl:!1,voiceIsolation:!1};function r(e,t,n){if(e!==t)throw Error(`Browser refused the ${n} sample rate: asked for ${t} Hz, got ${e} Hz`)}function i(e){let t=Error(`Audio ${e} worklet crashed`);return console.error(`[aai-ui]`,t.message),t}function a(e){e.then(e=>{for(let t of e.getTracks())t.stop()}).catch(()=>{})}function o(e,t,n){let r=new AudioWorkletNode(e,`capture-processor`,{channelCount:1,channelCountMode:`explicit`}),i=null;return r.port.onmessage=e=>{let r=e.data;r.event===`chunk`&&r.buffer?t(r.buffer):r.event===`silent`?n?.():r.event===`stopped`&&(i?.(),i=null)},{node:r,start(){r.port.postMessage({event:`start`})},stop(){let{promise:e,resolve:t}=Promise.withResolvers(),n=setTimeout(t,250);return i=()=>{clearTimeout(n),t()},r.port.postMessage({event:`stop`}),e}}}async function s(s){let{sttSampleRate:c,ttsSampleRate:l,captureWorkletSrc:u,playbackWorkletSrc:d,onMicData:f,onError:p,onPlaybackStats:m,onPlaybackProgress:h,onMicSilent:g}=s,_=new AudioContext({sampleRate:l,latencyHint:`playback`}),v=c===l,y=v?_:new AudioContext({sampleRate:c,latencyHint:`interactive`});async function b(){let e=v?[_]:[_,y];await Promise.all(e.map(e=>e.close().catch(e=>{console.warn(`AudioContext close failed:`,e)})))}let x=navigator.mediaDevices.getUserMedia({audio:{deviceId:{ideal:`default`},...n}}),S;try{[S]=await Promise.all([x,_.resume(),y.resume(),y.audioWorklet.addModule(u),_.audioWorklet.addModule(d)]),r(y.sampleRate,c,`capture`),r(_.sampleRate,l,`playback`)}catch(e){throw a(x),await b(),e}let C=y.createMediaStreamSource(S),w=o(y,f,g);C.connect(w.node),w.node.onprocessorerror=()=>p?.(i(`capture`)),w.start();let T=null,E=0,D=null,O=new AbortController;function k(){let e=D;D=null,e?.settle()}function A(e){e.stats&&e.stats.concealedSamples>0&&m?.(e.stats),e.reason!==`interrupt`&&(D===null||e.turn===D.turn)&&k()}function j(){if(T)return T;let e=new AudioWorkletNode(_,`playback-processor`);return e.connect(_.destination),e.port.onmessage=e=>{e.data.event===`stop`?A(e.data):e.data.event===`progress`&&h?.(e.data.bufferedMs)},e.onprocessorerror=()=>{let e=i(`playback`);k(),p?.(e)},T=e,e}let M={enqueue(e){O.signal.aborted||e.byteLength!==0&&j().port.postMessage({event:`write`,buffer:new Uint8Array(e)},[e])},done(){if(!T)return Promise.resolve();let n=++E;if(T.port.postMessage({event:`done`,turn:n}),_.state!==`running`)return k(),Promise.resolve();let{promise:r,resolve:i}=Promise.withResolvers();k();let a=()=>{clearInterval(o),clearTimeout(s),D?.settle===a&&(D=null),i()},o=setInterval(()=>{_.state!==`running`&&a()},t),s=setTimeout(a,e);return D={turn:n,settle:a},r},flush(){T&&(k(),T.port.postMessage({event:`interrupt`}))},async close(){if(!O.signal.aborted){O.abort(),await w.stop(),C.disconnect(),w.node.disconnect(),T&&T.disconnect();for(let e of S.getTracks())e.stop();await b()}},async[Symbol.asyncDispose](){await M.close()}};return M}export{s as createVoiceIO};