@alexkroman1/aai-ui 15.0.0 → 16.0.0

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

@@ -18,10 +18,15 @@
  * page overriding one member keeps that: spreading a complete record cannot
  * drop a key.
  *
- * There is deliberately no `StatusDot` component beside it. The dot markup and
- * its palette are what each chrome exists to look like — a CRT's glow, a
- * dispatch board's alert colours — and a component would take the one part
- * that is genuinely shared (the words) hostage to the part that is not.
+ * `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";
 /**

package/dist/{chat-view-C_3T7Ln8.js → chat-view-DsylXJsw.js}

@@ -1,4 +1,4 @@
-import { t as MessageList } from "./message-list-CdOnSh5m.js";
+import { t as MessageList } from "./message-list-BLyPRS1Q.js";
 import { useSessionError, useSessionStatus, useTheme } from "./context.js";
 import { a as inkTint, r as THINKING_COLOR, t as ERROR_COLOR } from "./_colors-CpZO-88A.js";
 import { t as AaiLogo } from "./aai-logo-CFlomZlS.js";
@@ -6,6 +6,50 @@ import { t as Eyebrow } from "./eyebrow-UfmSz9yy.js";
 import { Controls } from "./components/controls.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/agent-state-labels.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
+*/
+const AGENT_STATE_LABELS = {
+	disconnected: "Idle",
+	connecting: "Connecting…",
+	ready: "Ready",
+	listening: "Listening",
+	thinking: "Thinking…",
+	speaking: "Speaking",
+	error: "Error"
+};
+//#endregion
 //#region src/components/session-error-banner.tsx
 /** @jsxImportSource react */
 /**
@@ -80,6 +124,110 @@ function SessionErrorBanner({ className }) {
 	});
 }
 //#endregion
+//#region src/components/session-state-dot.tsx
+/** @jsxImportSource react */
+/**
+* One `aai-pulse` cycle per pulsing state, in milliseconds. The two states
+* that pulse are the two in which the agent is DOING something the reader
+* cannot otherwise see — the microphone is open, or a reply is being worked
+* out — and `thinking` beats faster because it is the shorter wait. `speaking`
+* has the audio itself for a signal and stays still.
+*/
+const PULSE_MS = {
+	listening: 1500,
+	thinking: 800
+};
+/**
+* The dot itself: a coloured circle, pulsing or still.
+*
+* Shared by {@link SessionStateDot} and `ConsoleShell`, which computes its
+* colour from the theme rather than from a palette prop and decides for itself
+* when to pulse. Not on the package barrel — the public component is the one
+* that reads the session.
+*
+* The colour is written to `background` AND `color`, so a caller can extend
+* the dot with a `currentColor` utility (`shadow-[0_0_6px_currentColor]` for a
+* glow) without restating the palette.
+*
+* @internal
+*/
+function StateDot({ color, pulseMs, className, title }) {
+	return /* @__PURE__ */ jsx("span", {
+		className: clsx("rounded-full inline-block shrink-0", className),
+		style: {
+			background: color,
+			color,
+			animation: pulseMs === null ? "none" : `aai-pulse ${pulseMs}ms ease-in-out infinite`
+		},
+		title
+	});
+}
+/**
+* The live session state as a coloured dot and a word, on its own narrow
+* subscription.
+*
+* Three custom chromes had each written this: a `satisfies Record<AgentState,
+* string>` palette (kept — it is the prop), a `STATE_LABELS` spread over
+* {@link AGENT_STATE_LABELS} (kept — it is `labels`), and then the same
+* fourteen lines of markup around them, including the same two-arm ternary
+* deciding which states pulse and how fast. `agent-state-labels.ts` argued
+* against a dot component on the grounds that it would take the shared part
+* (the words) hostage to the part that is not (the palette); this takes the
+* palette as a prop precisely so it does not. What is shared is the structure
+* — the exhaustive colour lookup, the label fallback, the pulse rule, the
+* `useSessionStatus()` subscription that keeps the rest of the header from
+* re-rendering at STT-partial rate.
+*
+* Must be rendered inside the providers `mountClient()` installs.
+*
+* @example A dispatch board's readout: its own colours, three of its own words
+* ```tsx
+* import type { AgentState } from "@alexkroman1/aai-ui";
+* import { SessionStateDot } from "@alexkroman1/aai-ui";
+*
+* const STATE_COLORS = {
+*   disconnected: "#6b7280",
+*   connecting: "#6b7280",
+*   ready: "#22c55e",
+*   listening: "#22c55e",
+*   thinking: "#eab308",
+*   speaking: "#3b82f6",
+*   error: "#6b7280",
+* } satisfies Record<AgentState, string>;
+*
+* function StatusReadout() {
+*   return (
+*     <SessionStateDot
+*       colors={STATE_COLORS}
+*       labels={{ listening: "LISTENING", thinking: "PROCESSING", speaking: "TRANSMITTING" }}
+*       labelClassName="text-[11px] uppercase"
+*     />
+*   );
+* }
+* ```
+*
+* @param props - See {@link SessionStateDotProps}.
+*
+* @public
+*/
+function SessionStateDot({ colors, labels, pulse = true, className, dotClassName, labelClassName }) {
+	const state = useSessionStatus();
+	const pulseMs = pulse ? PULSE_MS[state] ?? null : null;
+	return /* @__PURE__ */ jsxs("span", {
+		className: clsx("inline-flex items-center gap-2", className),
+		"data-state": state,
+		children: [/* @__PURE__ */ jsx(StateDot, {
+			color: colors[state],
+			pulseMs,
+			className: dotClassName ?? "w-2 h-2",
+			title: state
+		}), /* @__PURE__ */ jsx("span", {
+			className: labelClassName,
+			children: labels?.[state] ?? AGENT_STATE_LABELS[state]
+		})]
+	});
+}
+//#endregion
 //#region src/components/console-shell.tsx
 /** @jsxImportSource react */
 /**
@@ -183,12 +331,10 @@ function ConsoleShell({ icon, title, state, pulsing, children, footer, className
 				}), /* @__PURE__ */ jsxs(Eyebrow, {
 					className: "shrink-0",
 					"data-state": state,
-					children: [/* @__PURE__ */ jsx("span", {
-						className: "w-[7px] h-[7px] rounded-full",
-						style: {
-							background: stateColor(state, theme.primary, inkTint(theme.text, theme.bg, 65)),
-							animation: pulsing ? "aai-pulse 1.6s ease-in-out infinite" : "none"
-						}
+					children: [/* @__PURE__ */ jsx(StateDot, {
+						color: stateColor(state, theme.primary, inkTint(theme.text, theme.bg, 65)),
+						pulseMs: pulsing ? 1600 : null,
+						className: "w-[7px] h-[7px]"
 					}), state]
 				})]
 			}),
@@ -247,4 +393,4 @@ function ChatView({ icon, title, className }) {
 	});
 }
 //#endregion
-export { ConsoleShell as n, SessionErrorBanner as r, ChatView as t };
+export { AGENT_STATE_LABELS as a, SessionErrorBanner as i, ConsoleShell as n, SessionStateDot as r, ChatView as t };

package/dist/components/audio-result.d.ts

@@ -0,0 +1,94 @@
+import type { ReactNode } from "react";
+import type { UseDownloadUrlResult } from "../use-download-url.ts";
+/**
+ * A one-cue caption track for {@link AudioResult}: the words the clip speaks,
+ * spanning its whole length.
+ *
+ * @public
+ */
+export type AudioResultCaptions = {
+    /** The spoken text — the one cue. */
+    text: string;
+    /** The clip's length, which is where the cue ends. */
+    durationMs: number;
+    /** The track's `label`. Defaults to the player's `label`. */
+    label?: string | undefined;
+    /** The track's `srcLang`. Default `"en"`. */
+    srcLang?: string | undefined;
+};
+/**
+ * Props of {@link AudioResult}.
+ *
+ * @public
+ */
+export type AudioResultProps = {
+    /** What {@link useDownloadUrl} returned for the run's audio upload. */
+    download: UseDownloadUrlResult;
+    /** The name the download link saves as — `"summary.wav"`, `"audit.mp3"`. */
+    filename: string;
+    /** The player's `aria-label`: what this audio IS — `"Summary read aloud"`. */
+    label: string;
+    /**
+     * The heading over the player — typically the duration and size, which the
+     * run's output carries. Omitted, there is no heading.
+     */
+    heading?: ReactNode | undefined;
+    /**
+     * The spoken text as a caption track. Omit it deliberately when the same
+     * words are rendered in full beside the player (see the component doc);
+     * pass it when they are not, or when a real track is what a page needs.
+     */
+    captions?: AudioResultCaptions | undefined;
+    /** Additional CSS class names for the wrapping `<section>`, appended to its own. */
+    className?: string | undefined;
+    /** Rendered under the player — the spoken text, usually. */
+    children?: ReactNode;
+};
+/**
+ * The player for a file a RUN produced: a heading, the fetch's pending line,
+ * its announced error, the `<audio>` with an optional caption track, the
+ * download link, and whatever the page renders beneath — the spoken text.
+ *
+ * Two templates exist because of the audio round trip, and both had written
+ * this block over {@link useDownloadUrl} identically: the same pending
+ * sentence, the same `role="alert"` paragraph, the same `<audio controls>` over
+ * the object URL, the same anchor with `download` set. The `download` attribute
+ * works on an object URL because the bytes are already in the tab — it was the
+ * `href` that could not carry the agent's bearer token, never the attribute —
+ * and that is the whole reason both pages hand this a hook result rather than a
+ * path.
+ *
+ * **A caption track is a judgement, not a default.** `spoken-summary` passes
+ * `captions`: the summary was written before it was spoken, so one cue
+ * spanning the clip is an honest transcript of it. `call-audit` deliberately
+ * does not: the spoken text is rendered in full immediately below the player,
+ * which is the same information a track would carry. Both are right, which is
+ * why the prop is optional in both directions.
+ *
+ * @example
+ * ```tsx
+ * import { AudioResult, createWorkflowApi, useDownloadUrl } from "@alexkroman1/aai-ui";
+ *
+ * const api = createWorkflowApi();
+ *
+ * function Player({ id, spoken, ms }: { id: string; spoken: string; ms: number }) {
+ *   const audio = useDownloadUrl(id, { api });
+ *   return (
+ *     <AudioResult
+ *       download={audio}
+ *       filename="summary.wav"
+ *       label="Summary read aloud"
+ *       heading="Read aloud"
+ *       captions={{ text: spoken, durationMs: ms }}
+ *     >
+ *       <p className="text-sm opacity-70">{spoken}</p>
+ *     </AudioResult>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link AudioResultProps}.
+ *
+ * @public
+ */
+export declare function AudioResult({ download, filename, label, heading, captions, className, children, }: AudioResultProps): ReactNode;

package/dist/components/chat-view.js

@@ -1,3 +1,3 @@
+import { t as ChatView } from "../chat-view-DsylXJsw.js";
 import "../context.js";
-import { t as ChatView } from "../chat-view-C_3T7Ln8.js";
 export { ChatView };

package/dist/components/conversation-view.d.ts

@@ -0,0 +1,108 @@
+/** @jsxImportSource react */
+import type { CSSProperties, ReactNode } from "react";
+import type { ChatMessage, ToolCallInfo } from "../types.ts";
+import type { UseUserTranscriptResult } from "../use-user-transcript.ts";
+/**
+ * Props of {@link ConversationView}.
+ *
+ * @public
+ */
+export type ConversationViewProps = {
+    /** One finalized message, in this chrome's own markup. */
+    renderMessage: (message: ChatMessage) => ReactNode;
+    /**
+     * One tool invocation. Absent, a compact {@link ToolCallRow} naming the tool,
+     * shimmering while it is pending.
+     */
+    renderTool?: ((toolCall: ToolCallInfo) => ReactNode) | undefined;
+    /**
+     * The agent's reply as it arrives. Absent, `renderMessage` is called with a
+     * synthetic assistant message carrying the text so far (its `id` is `-1`,
+     * which no real message has) — every chrome so far rendered the two the same
+     * way, and this keeps them from drifting.
+     */
+    renderStreaming?: ((text: string) => ReactNode) | undefined;
+    /**
+     * The caller's in-progress turn. Rendered only while `transcript.speaking`,
+     * which is the `null`-vs-`""` distinction {@link useUserTranscript} makes
+     * (`""` is speech detected with no words yet — render on it, and read
+     * `transcript.text` for the placeholder). Absent, a muted italic line.
+     */
+    renderTranscript?: ((transcript: UseUserTranscriptResult) => ReactNode) | undefined;
+    /**
+     * Where the transcript row goes. `"inline"` (the default) is the last row
+     * inside the scroll region, as `MessageList` places it; `"below"` renders it
+     * after the scroll region as a sibling — the strip a two-pane board pins to
+     * the bottom of its conversation column, outside the scroll.
+     */
+    transcriptPosition?: "inline" | "below" | undefined;
+    /** Rendered inside the scroll region while there is nothing to show at all. */
+    empty?: ReactNode | undefined;
+    /**
+     * The `aria-label` of the thinking row. Default `"Thinking"`. Say who: the
+     * dots are the only sign the agent is working, and to a screen reader they
+     * are punctuation.
+     */
+    thinkingLabel?: string | undefined;
+    /** What the thinking row shows. Default: three pulsing dots. */
+    thinkingIndicator?: ReactNode | undefined;
+    /** CSS class names for the thinking row itself (the `role="status"` element). */
+    thinkingClassName?: string | undefined;
+    /**
+     * Classes for the {@link AutoScroll} container. It must end up with a
+     * bounded height (`flex-1 min-h-0`, `h-full`) or nothing pins.
+     */
+    className?: string | undefined;
+    /** Classes for the scroll region's content element — padding, gap, direction. */
+    contentClassName?: string | undefined;
+    /** Classes for the scrolling element itself. See {@link AutoScroll}. */
+    scrollClassName?: string | undefined;
+    /** Inline styles for the scroll container. */
+    style?: CSSProperties | undefined;
+};
+/**
+ * The conversation's skeleton over {@link useConversation}, with every row a
+ * render slot: a pinned scroll region holding the empty state, the interleaved
+ * messages and tool calls, the streaming reply and the announced thinking row,
+ * plus the live transcript — inside the scroll or pinned beneath it.
+ *
+ * `useConversation()` already made the DATA one thing: the interleave, the
+ * streaming utterance, the `null`-vs-`""` transcript distinction and the
+ * thinking-suppression rule. What three custom chromes then each wrote around
+ * it was the same fifty lines of STRUCTURE: an `AutoScroll` with a bounded
+ * height, an empty-state guard on `items.length === 0 && streaming === null`,
+ * the map with its keys, the streaming row, the thinking row with its
+ * `role="status"` and `aria-label` (and the same comment about screen readers
+ * hearing punctuation), the transcript guarded on `speaking`. The bubbles are
+ * the part each template exists to show, so those are slots; the order and the
+ * accessibility contract are this component's.
+ *
+ * {@link MessageList} is this with the stock bubbles filled in.
+ *
+ * Must be rendered inside the providers `mountClient()` installs.
+ *
+ * @example A board's radio log: its own bubbles, the stock tool row, the transcript pinned below
+ * ```tsx
+ * import { ConversationView } from "@alexkroman1/aai-ui";
+ *
+ * function RadioLog() {
+ *   return (
+ *     <ConversationView
+ *       contentClassName="p-4 flex flex-col gap-2"
+ *       empty={<p className="text-center opacity-60">Standing by.</p>}
+ *       renderMessage={({ role, content }) => (
+ *         <div className={role === "assistant" ? "self-start" : "self-end"}>{content}</div>
+ *       )}
+ *       renderTranscript={({ text }) => <div className="px-4 py-2 italic">{text}</div>}
+ *       transcriptPosition="below"
+ *       thinkingLabel="Dispatch is thinking"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link ConversationViewProps}.
+ *
+ * @public
+ */
+export declare function ConversationView({ renderMessage, renderTool, renderStreaming, renderTranscript, transcriptPosition, empty, thinkingLabel, thinkingIndicator, thinkingClassName, className, contentClassName, scrollClassName, style, }: ConversationViewProps): ReactNode;

package/dist/components/message-list.js

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

package/dist/components/session-controls.d.ts

@@ -0,0 +1,125 @@
+import { type ReactNode } from "react";
+/**
+ * Which of the four buttons a {@link SessionControlButton} is.
+ *
+ * @public
+ */
+export type SessionControlAction = "start" | "toggle" | "restart" | "end";
+/**
+ * One button of {@link SessionControls}, as handed to `renderButton`.
+ *
+ * @public
+ */
+export type SessionControlButton = {
+    /** Which button this is. A custom renderer switches on it for its look. */
+    action: SessionControlAction;
+    /** The label to show — the caller's own word, or the default. */
+    label: string;
+    /** The handler. Already bound; wire it to `onClick` as it is. */
+    onClick: () => void;
+    /**
+     * Whether the call is live. Meaningful on `toggle`, whose label already says
+     * which way it will flip, and handed to every button so a renderer can dim
+     * the others while paused.
+     */
+    running: boolean;
+};
+/**
+ * The five words {@link SessionControls} renders, every one overridable.
+ *
+ * @public
+ */
+export type SessionControlsLabels = {
+    /** The button shown before the call starts. Default `"Start"`. */
+    start: string;
+    /** The toggle's label while running. Default `"Pause"`. */
+    pause: string;
+    /** The toggle's label while paused. Default `"Resume"`. */
+    resume: string;
+    /** Hang up and dial again. Default `"New Conversation"`. */
+    restart: string;
+    /** Hang up. Default `"End"`. */
+    end: string;
+};
+/**
+ * Props of {@link SessionControls}.
+ *
+ * @public
+ */
+export type SessionControlsProps = {
+    /** The words this chrome has its own term for; the rest keep the defaults. */
+    labels?: Partial<SessionControlsLabels> | undefined;
+    /**
+     * Renders one button. Absent, each is a stock {@link Button}. A chrome
+     * with its own look renders its own `<button>` from the
+     * {@link SessionControlButton} it is handed — the component still decides
+     * WHICH buttons exist and what each one does.
+     */
+    renderButton?: ((button: SessionControlButton) => ReactNode) | undefined;
+    /** Additional CSS class names for the row, appended to its own layout classes. */
+    className?: string | undefined;
+    /** Rendered after the buttons — a count, a spacer, a status line. */
+    children?: ReactNode;
+};
+/**
+ * The full control row of a custom chrome: **Start** before the call, then
+ * **Pause / Resume**, **New Conversation** and **End** once it is up.
+ *
+ * {@link Controls} is the stock console's footer — Stop/Resume and New
+ * Conversation, with the URL chips — and it has no Start branch and no End,
+ * because the default shell shows a start SCREEN and a session there ends by
+ * closing the tab. A chrome that owns its whole frame has no start screen, so
+ * three of them each wrote this row: the same `!started` branch, the same
+ * three buttons behind it, and the same twelve-line comment on why the middle
+ * one is `end(); start()` and not `reset()`. The buttons' look is the
+ * chrome's — `renderButton` — and everything else is here once.
+ *
+ * **Why `restart` is `end()` then `start()`, and never `reset()`.** `reset()`
+ * clears the transcript and reconnects carrying the same session id, so every
+ * `sessionSlot` on the agent survives: a caller who pressed "New Conversation"
+ * on a stateful agent got a blank transcript in front of their old cart, game
+ * or incident board, with nothing on screen saying so, and the next tool call
+ * repopulated it. `end()` drops the resume identity, so the redial is a
+ * brand-new session — fresh state, greeting included — and `start()` puts the
+ * chrome straight back on the call rather than at its Start button.
+ *
+ * **Why End is `end()`.** It hangs up and flips `started` back, so the row
+ * returns to its Start button and the next start is a new session. `reset()`
+ * would keep the call live — the buttons never toggle back.
+ *
+ * Reads the session through {@link useSessionControls}: two one-field
+ * subscriptions, so the row re-renders when a flag flips and not on every
+ * transcript partial.
+ *
+ * @example A board's controls in its own colours, with a trailing count
+ * ```tsx
+ * import { SessionControls } from "@alexkroman1/aai-ui";
+ *
+ * const BUTTON = "px-4 py-2 rounded-md text-xs font-semibold cursor-pointer";
+ *
+ * function ShiftControls({ logged }: { logged: number }) {
+ *   return (
+ *     <SessionControls
+ *       labels={{ start: "Start Dispatch", end: "End Shift" }}
+ *       renderButton={({ action, label, onClick }) => (
+ *         <button
+ *           type="button"
+ *           className={BUTTON}
+ *           style={{ background: action === "end" ? "#dc2626" : "#2563eb", color: "white" }}
+ *           onClick={onClick}
+ *         >
+ *           {label}
+ *         </button>
+ *       )}
+ *     >
+ *       <span className="ml-auto text-[10px]">{logged} incidents logged</span>
+ *     </SessionControls>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link SessionControlsProps}.
+ *
+ * @public
+ */
+export declare function SessionControls({ labels, renderButton, className, children, }: SessionControlsProps): ReactNode;

package/dist/components/session-state-dot.d.ts

@@ -0,0 +1,111 @@
+import type { ReactNode } from "react";
+import type { AgentState } from "../types.ts";
+/**
+ * The dot itself: a coloured circle, pulsing or still.
+ *
+ * Shared by {@link SessionStateDot} and `ConsoleShell`, which computes its
+ * colour from the theme rather than from a palette prop and decides for itself
+ * when to pulse. Not on the package barrel — the public component is the one
+ * that reads the session.
+ *
+ * The colour is written to `background` AND `color`, so a caller can extend
+ * the dot with a `currentColor` utility (`shadow-[0_0_6px_currentColor]` for a
+ * glow) without restating the palette.
+ *
+ * @internal
+ */
+export declare function StateDot({ color, pulseMs, className, title, }: {
+    /** The dot's colour. */
+    color: string;
+    /** Length of one pulse cycle, or `null` for a still dot. */
+    pulseMs: number | null;
+    /** Size and any extras; the shape classes are the dot's own. */
+    className?: string | undefined;
+    /** Tooltip text, typically the raw state. */
+    title?: string | undefined;
+}): ReactNode;
+/**
+ * Props of {@link SessionStateDot}.
+ *
+ * @public
+ */
+export type SessionStateDotProps = {
+    /**
+     * The dot's colour per {@link AgentState} — the chrome's own palette. A
+     * complete record, so a state added upstream is a compile error here rather
+     * than a silently unpainted dot; `satisfies Record<AgentState, string>` on the
+     * caller's literal is the shape to write it in.
+     */
+    colors: Readonly<Record<AgentState, string>>;
+    /**
+     * The words this chrome has a better term for. Anything not named falls back
+     * to {@link AGENT_STATE_LABELS}, so a page overrides one member (`speaking:
+     * "Narrating"`) without restating the union.
+     */
+    labels?: Partial<Readonly<Record<AgentState, string>>> | undefined;
+    /**
+     * Whether the dot pulses while `listening` (slowly) and `thinking` (faster).
+     * Defaults to `true`; a chrome whose dot glows rather than beats passes
+     * `false`.
+     */
+    pulse?: boolean | undefined;
+    /** Additional CSS class names for the wrapping `<span>`, appended to its own. */
+    className?: string | undefined;
+    /**
+     * REPLACES the dot's default size (`w-2 h-2`) rather than adding to it —
+     * there is no `tailwind-merge` in this package, so two conflicting width
+     * utilities would not have a reliable winner. The dot's shape classes stay.
+     */
+    dotClassName?: string | undefined;
+    /** Additional CSS class names for the label `<span>`. */
+    labelClassName?: string | undefined;
+};
+/**
+ * The live session state as a coloured dot and a word, on its own narrow
+ * subscription.
+ *
+ * Three custom chromes had each written this: a `satisfies Record<AgentState,
+ * string>` palette (kept — it is the prop), a `STATE_LABELS` spread over
+ * {@link AGENT_STATE_LABELS} (kept — it is `labels`), and then the same
+ * fourteen lines of markup around them, including the same two-arm ternary
+ * deciding which states pulse and how fast. `agent-state-labels.ts` argued
+ * against a dot component on the grounds that it would take the shared part
+ * (the words) hostage to the part that is not (the palette); this takes the
+ * palette as a prop precisely so it does not. What is shared is the structure
+ * — the exhaustive colour lookup, the label fallback, the pulse rule, the
+ * `useSessionStatus()` subscription that keeps the rest of the header from
+ * re-rendering at STT-partial rate.
+ *
+ * Must be rendered inside the providers `mountClient()` installs.
+ *
+ * @example A dispatch board's readout: its own colours, three of its own words
+ * ```tsx
+ * import type { AgentState } from "@alexkroman1/aai-ui";
+ * import { SessionStateDot } from "@alexkroman1/aai-ui";
+ *
+ * const STATE_COLORS = {
+ *   disconnected: "#6b7280",
+ *   connecting: "#6b7280",
+ *   ready: "#22c55e",
+ *   listening: "#22c55e",
+ *   thinking: "#eab308",
+ *   speaking: "#3b82f6",
+ *   error: "#6b7280",
+ * } satisfies Record<AgentState, string>;
+ *
+ * function StatusReadout() {
+ *   return (
+ *     <SessionStateDot
+ *       colors={STATE_COLORS}
+ *       labels={{ listening: "LISTENING", thinking: "PROCESSING", speaking: "TRANSMITTING" }}
+ *       labelClassName="text-[11px] uppercase"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link SessionStateDotProps}.
+ *
+ * @public
+ */
+export declare function SessionStateDot({ colors, labels, pulse, className, dotClassName, labelClassName, }: SessionStateDotProps): ReactNode;