@alexkroman1/aai-ui 6.11.0 → 7.0.0

package/dist/session-core-state.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The browser session's {@link AgentState}, and the error beside it, as a
+ * statechart.
+ *
+ * These two were written independently from thirteen sites across
+ * `session-core.ts`, `session-core-messages.ts` and
+ * `session-core-audio-setup.ts`, each one deciding for itself whether its write
+ * was legal by reading the snapshot back first. Three shipped bugs came out of
+ * that, and all three are the same shape — a transition nothing forbade:
+ *
+ * - **A straggler audio chunk flipped an errored session to `"speaking"`.**
+ *   Guarded by hand at the call site
+ *   (`if (snap.state === "error" || (snap.state === "disconnected" && …))`).
+ *   Here `error` simply does not handle `SPEAK`.
+ * - **The frame that announced a session's death also wiped the banner
+ *   reporting it.** Every fatal path in the host tears the transport down, and
+ *   tearing down EMITS — so `reply.cancelled` arrived right behind the error and
+ *   `toListening()` painted a live-mic state over it. A missing provider key is
+ *   the case that made it visible: the one message that says exactly what to fix
+ *   was on screen for a few hundred milliseconds and left a session that looked
+ *   live and was deaf.
+ * - **A later frame RECOVERED the state.** `clearRecoveredError` reads a
+ *   non-error frame as proof the session works, which is right for a
+ *   turn-level failure and wrong for a server error that ended the call.
+ *
+ * The second and third were fixed with a `conn.fatalError` boolean that every
+ * writer had to remember to consult. It is the `fatal` region here, so
+ * forgetting is not available: `LISTEN` and `ACTIVITY` are declined in one
+ * place rather than at each of their five call sites.
+ *
+ * ## Two regions, because the fatal latch OUTLIVES the error state
+ *
+ * `fatal` is not a substate of `error`, tempting as that looks. It is cleared by
+ * exactly one thing — the next `config` frame, i.e. a completed handshake — and
+ * that is per CONNECTION rather than per session, so a reconnect that really
+ * works is not pinned to a dead session's banner. Between the error and that
+ * frame the phase runs `error → connecting → ready` while the latch stays set,
+ * which a substate cannot express.
+ *
+ * ## The published surface is unchanged
+ *
+ * {@link AgentState} is a public type in the versioned `aai-ui:session`
+ * capability, so {@link AgentStateSnapshot.state} is one of its seven names and
+ * nothing here widens it. The internal distinctions live in the second region
+ * and in context, not in the projection.
+ */
+import type { AgentState, SessionError } from "./types.ts";
+/** What the session core folds into its snapshot after each transition. */
+export type AgentStateSnapshot = {
+    state: AgentState;
+    error: SessionError | null;
+};
+/**
+ * Everything that moves the session's state.
+ *
+ * Named for what HAPPENED rather than for the state wanted, which is the point:
+ * `reply.cancelled` sends `LISTEN` and gets `"error"` back when the session is
+ * fatally over, and the caller neither knows nor needs to.
+ */
+export type AgentStateEvent = 
+/** A connect attempt started — including a reconnect or a handshake retry. */
+{
+    type: "CONNECT";
+}
+/** The socket opened; the handshake has not completed yet. */
+ | {
+    type: "SOCKET_OPEN";
+}
+/** A completed handshake: a live session, whatever ended the last one. */
+ | {
+    type: "HANDSHAKE_COMPLETE";
+}
+/** A turn boundary, or the audio path coming up: back to the mic. */
+ | {
+    type: "LISTEN";
+}
+/** A reset: back to the mic AND the conversation cleared. */
+ | {
+    type: "RESET";
+}
+/** The agent is working. */
+ | {
+    type: "THINK";
+}
+/** Audio for this turn reached the client. */
+ | {
+    type: "SPEAK";
+}
+/** A non-error frame arrived, so the session demonstrably works. */
+ | {
+    type: "ACTIVITY";
+}
+/** A turn-level failure: a banner over a session that keeps running. */
+ | {
+    type: "TURN_ERROR";
+    error: SessionError;
+}
+/** The session is over. */
+ | {
+    type: "FATAL";
+    error: SessionError;
+}
+/**
+ * A failure that stops the session but might not be the end of it: the
+ * handshake exhausting its retries, a socket error close, or the audio path
+ * dying. The `fatal` latch stays clear, so a later non-error frame recovers
+ * — which is right for a client-side failure and is exactly what a FATAL
+ * server error must not get.
+ */
+ | {
+    type: "FAILED";
+    error: SessionError;
+}
+/** The socket closed for good. */
+ | {
+    type: "CLOSED";
+}
+/** The caller hung up. */
+ | {
+    type: "DISCONNECT";
+}
+/** The caller ended the session and forgot it. */
+ | {
+    type: "END";
+};
+/** The session core's handle on its own state. */
+export type SessionStateMachine = {
+    /** The published state and the error beside it. */
+    snapshot(): AgentStateSnapshot;
+    /**
+     * Apply `event` and return the resulting projection.
+     *
+     * Returns rather than writes so the caller folds it into ONE `updateState`
+     * call: a snapshot is published on every write, and splitting one transition
+     * into two would let a subscriber render half of it.
+     */
+    apply(event: AgentStateEvent): AgentStateSnapshot;
+    /**
+     * Is the session fatally over? Asked by the one caller that has to clear the
+     * CONVERSATION and not merely the state — a `session.reset` on a dead session
+     * keeps its whole banner.
+     */
+    fatal(): boolean;
+};
+/** Create the state machine for one browser session. */
+export declare function createSessionStateMachine(): SessionStateMachine;

package/dist/session-core-types.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Epoch } from "@alexkroman1/aai/internal";
 import type { VoiceIO } from "./audio.ts";
-import type { AgentState, ChatMessage, SessionError, ToolCallInfo, VoiceSessionOptions, WebSocketConstructor } from "./types.ts";
+import type { AgentState, ChatMessage, SessionError, ToolCallInfo, WebSocketConstructor } from "./types.ts";
 /**
  * A custom event emitted by the agent via `ctx.send(event, data)` — the
  * payload the session records in `SessionSnapshot.customEvents` (`id` is a
@@ -27,11 +27,30 @@ export type AgentCustomEvent = {
  * Consumers (e.g. React hooks via `useSyncExternalStore`) read this to render.
  * A new object reference is created on every state change.
  *
+ * @remarks
+ * **Four fields describe liveness and they answer different questions.** They
+ * are routinely collapsed into one truthy check, which is how a chrome ends up
+ * showing a live indicator over a call that has ended:
+ *
+ * | Field | The question it answers |
+ * | --- | --- |
+ * | `started` | Has the caller pressed Start? `end()` puts it back to `false`; `disconnect()` does not. |
+ * | `running` | Is the socket MEANT to be up? `toggle()` is what flips it. |
+ * | `recording` | Is the microphone actually live right now? |
+ * | `state` | What is the agent doing — see {@link AgentState}. |
+ *
  * @public
  */
 export type SessionSnapshot = {
+    /** What the agent is doing. See {@link AgentState} for the seven members. */
     readonly state: AgentState;
-    /** True while the microphone is live and streaming to the server. */
+    /**
+     * True while the microphone is live and streaming to the server.
+     *
+     * This is the mic, not the session: a session can be `running` with the mic
+     * still opening, and a failure to acquire it leaves this `false` with the
+     * socket up.
+     */
     readonly recording: boolean;
     /**
      * The WebSocket URL a program can connect to directly — the long-living
@@ -50,8 +69,24 @@ export type SessionSnapshot = {
      * never collides when the capped arrays slide.
      */
     readonly contentVersion: number;
+    /**
+     * The conversation so far, oldest first — user and assistant turns only.
+     * Tool activity is NOT in here; it is in `toolCalls`. Capped, so the oldest
+     * entries slide off a long call.
+     */
     readonly messages: ChatMessage[];
+    /**
+     * Every tool call the agent has made this session, in order, each carrying
+     * its own pending/settled state. Capped like `messages`. `useToolResult` and
+     * `useToolCallStart` are the narrow readers; this is the whole log.
+     */
     readonly toolCalls: ToolCallInfo[];
+    /**
+     * Custom events the agent pushed with `ctx.send(event, data)`, in order.
+     * A LOG rather than a value — `useEvent(name, cb)` is the reader that
+     * delivers each one exactly once; reading this array directly means owning
+     * the cursor yourself.
+     */
     readonly customEvents: AgentCustomEvent[];
     /**
      * Latest state the agent projected via `syncState`, or `null` before the
@@ -59,10 +94,50 @@ export type SessionSnapshot = {
      * reads current state rather than replaying events it missed.
      */
     readonly agentState: unknown;
+    /**
+     * The caller's in-progress turn, as STT reports it.
+     *
+     * **`null` and `""` are different turns, and collapsing them is the mistake
+     * this field invites.** `null` is silence; `""` is speech DETECTED with no
+     * words back yet — where a live session sits for a few hundred milliseconds
+     * at the start of every turn. Read as one falsy check, the live-transcript
+     * row appears a beat late, on the first word rather than on the first sound,
+     * which is the moment it exists for.
+     *
+     * Prefer {@link useUserTranscript}, which returns the distinction as two
+     * named things (`speaking` to render on, `text` with a placeholder) rather
+     * than leaving each chrome to re-derive the ternary.
+     *
+     * Cleared when the turn is committed to `messages`.
+     */
     readonly userTranscript: string | null;
+    /**
+     * The agent's reply as it streams, or `null` when it is not speaking.
+     * Cleared when the reply is committed to `messages`, so a chrome renders
+     * this row and the finished message, never both.
+     */
     readonly agentTranscript: string | null;
+    /**
+     * The session's current failure, or `null`. Carries a `code`
+     * ({@link SessionErrorCode}), a message, and whether it was FATAL.
+     *
+     * A fatal error LATCHES: nothing clears it but the next completed handshake,
+     * because the frame announcing a session's death is also the frame that used
+     * to wipe the message explaining it. A non-fatal one is retired by later
+     * activity, which is what the recovery was written for.
+     */
     readonly error: SessionError | null;
+    /**
+     * Whether the caller has pressed Start. `false` until the first `start()`,
+     * and back to `false` after `end()` — which is what makes a start-screen
+     * chrome show its Start control again. `disconnect()` leaves it `true`.
+     */
     readonly started: boolean;
+    /**
+     * Whether the session is MEANT to be connected — the pause/resume state
+     * `toggle()` flips, not a report of the socket. A reconnecting session is
+     * still `running`.
+     */
     readonly running: boolean;
 };
 /**
@@ -123,14 +198,6 @@ export type SessionCore = {
     /** Alias for `disconnect` for use with `using`. */
     [Symbol.dispose](): void;
 };
-/**
- * Options accepted by `createSessionCore` — an alias of
- * {@link VoiceSessionOptions}, which documents every field. Two names, one
- * type: `client()` and `createSessionCore` share the same session options.
- *
- * @public
- */
-export type SessionCoreOptions = VoiceSessionOptions;
 /**
  * Shared mutable connection state for audio initialization.
  *
@@ -151,28 +218,6 @@ export type ConnState = {
      * reconnect on demand).
      */
     retiredByServer: boolean;
-    /**
-     * A FATAL error has been reported for this connection — the session is
-     * over, and no later frame may take its banner off the screen.
-     *
-     * The recovery rule below it (`clearRecoveredError`) reads a non-error
-     * frame as proof the session works, which is right for a client-side or
-     * turn-level failure and wrong for a server error that ended the call:
-     * every fatal path in the host tears the transport down, and tearing down
-     * EMITS — `terminate()` calls `onCancelled()` immediately after
-     * `emitError`. So the very next frame recovered the state to "listening"
-     * and wiped the message. A missing provider key is the case that made this
-     * visible: the one error that says exactly what to go and fix
-     * ("Cartesia TTS: missing API key. Set CARTESIA_API_KEY in the agent env.")
-     * was on screen for a few hundred milliseconds and left a session that
-     * looked live and was deaf.
-     *
-     * Cleared by exactly one thing — the next `config` frame, i.e. a completed
-     * handshake. That is per CONNECTION rather than per session, so a
-     * reconnect that really works is not pinned to a dead session's banner,
-     * and it is the only frame a dying session cannot produce.
-     */
-    fatalError: boolean;
     voiceIO: VoiceIO | null;
     audioSetupInFlight: boolean;
     /** Connection epoch, bumped on each connect()/retry (see `createEpoch`).

package/dist/session-core.d.ts

@@ -1,4 +1,5 @@
-import type { SessionCore, SessionCoreOptions } from "./session-core-types.ts";
+import type { SessionCore } from "./session-core-types.ts";
+import { type VoiceSessionOptions } from "./types.ts";
 /**
  * Create a framework-agnostic voice session core that connects to an AAI
  * server via WebSocket.
@@ -26,4 +27,4 @@ import type { SessionCore, SessionCoreOptions } from "./session-core-types.ts";
  *
  * @public
  */
-export declare function createSessionCore(options: SessionCoreOptions): SessionCore;
+export declare function createSessionCore(options: VoiceSessionOptions): SessionCore;

package/dist/session-core.js

@@ -1,2 +1,2 @@
-import { t as createSessionCore } from "./session-core-CAfYmUbg.js";
+import { t as createSessionCore } from "./session-core-C2JtLArh.js";
 export { createSessionCore };

package/dist/{tool-call-block-D6pTEPrT.js → tool-call-block-DoF-cSIZ.js}

@@ -2,9 +2,10 @@ import { useTheme } from "./context.js";
 import { r as inkTint } from "./_colors-CcAi2FOU.js";
 import { t as Eyebrow } from "./eyebrow-C6ZFuiz6.js";
 import { i as tryParseJSON, r as truncate } from "./_utils-B6498_bm.js";
+import { n as useToolConfig } from "./tool-config-context-DzAofqi_.js";
 import clsx from "clsx";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { createContext, memo, useContext, useMemo, useState } from "react";
+import { memo, useMemo, useState } from "react";
 //#region components/tool-call-row.tsx
 /** @jsxImportSource react */
 const VARIANT_CLASSES = {
@@ -33,6 +34,30 @@ const VARIANT_CLASSES = {
 * 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 }) {
@@ -91,23 +116,6 @@ function ToolCallRow({ title, detail, pending = false, icon, variant = "default"
 	});
 }
 //#endregion
-//#region components/tool-config-context.ts
-/**
-* Context for tool display configuration. Installed by `client()` 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
 //#region components/tool-call-block.tsx
 /** @jsxImportSource react */
 function formatResult(result) {
@@ -174,4 +182,4 @@ const ToolCallBlock = memo(function ToolCallBlock({ toolCall, className }) {
 	});
 });
 //#endregion
-export { ToolConfigContext as n, ToolCallRow as r, ToolCallBlock as t };
+export { ToolCallRow as n, ToolCallBlock as t };

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

@@ -0,0 +1,19 @@
+import { createContext, useContext } from "react";
+//#region components/tool-config-context.ts
+/**
+* Context for tool display configuration. Installed by `client()` 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

@@ -21,14 +21,40 @@ export { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS,
  *
  * Cast because `voiceIsolation` is newer than TypeScript's DOM lib.
  *
- * Public so a custom client that opens its own microphone gets the same
- * signal the built-in capture paths do.
- *
- * @public
+ * 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
+ * `client()` field to set, and the root is the authoring surface. A custom
+ * chrome that bypasses `client()` 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.
+ * 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-core-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
  */

package/dist/types.js

@@ -20,10 +20,11 @@ import { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS,
 *
 * Cast because `voiceIsolation` is newer than TypeScript's DOM lib.
 *
-* Public so a custom client that opens its own microphone gets the same
-* signal the built-in capture paths do.
-*
-* @public
+* 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
+* `client()` field to set, and the root is the authoring surface. A custom
+* chrome that bypasses `client()` and opens its own microphone reaches it there
+* alongside the providers it also needs.
 */
 const VOICE_CAPTURE_CONSTRAINTS = {
 	echoCancellation: true,

package/dist/{controls-CjG91QJ4.js → url-chips-DpM7Oocj.js}

@@ -1,10 +1,9 @@
-import { useSessionCore, useSessionSelector, useTheme } from "./context.js";
+import { useSessionSelector, useTheme } from "./context.js";
 import { r as inkTint } from "./_colors-CcAi2FOU.js";
-import { Button } from "./components/button.js";
 import { t as pageBaseUrl } from "./_utils-B6498_bm.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { memo, useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 //#region components/url-chips.tsx
 /** @jsxImportSource react */
 /** How long the "Copied" confirmation replaces the label after a click. */
@@ -97,46 +96,4 @@ function SessionUrlChips({ className }) {
 	});
 }
 //#endregion
-//#region components/controls.tsx
-/** @jsxImportSource react */
-/**
-* Session control buttons: **Stop / Resume** and **New Conversation**.
-*
-* Reads session state from {@link useSession}. Must be rendered inside a
-* `SessionProvider`.
-*
-* @example
-* ```tsx
-* import { Controls } from "@alexkroman1/aai-ui";
-*
-* function Footer() {
-*   return <Controls className="justify-end" />;
-* }
-* ```
-*
-* @param className - Additional CSS class names applied to the container.
-*
-* @public
-*/
-const Controls = memo(function Controls({ className }) {
-	const running = useSessionSelector((s) => s.running);
-	const { toggle, reset } = useSessionCore();
-	return /* @__PURE__ */ jsxs("div", {
-		className: clsx("flex flex-wrap items-center gap-3 shrink-0", className),
-		children: [
-			/* @__PURE__ */ jsx(Button, {
-				variant: "secondary",
-				onClick: toggle,
-				children: running ? "Stop" : "Resume"
-			}),
-			/* @__PURE__ */ jsx(Button, {
-				variant: "ghost",
-				onClick: reset,
-				children: "New Conversation"
-			}),
-			/* @__PURE__ */ jsx(SessionUrlChips, { className: "basis-full sm:basis-auto sm:ml-auto sm:max-w-[60%]" })
-		]
-	});
-});
-//#endregion
-export { UiUrlChip as i, ApiUrlChip as n, SessionUrlChips as r, Controls as t };
+export { SessionUrlChips as n, UiUrlChip as r, ApiUrlChip as t };

package/dist/use-conversation.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `useConversation` — the exchange, already assembled, with nothing rendered.
+ *
+ * `<MessageList>` owns four decisions that are not obvious and are not
+ * derivable from the snapshot by eye: the message/tool-call INTERLEAVE, the
+ * streaming agent utterance, the live user transcript with its `null`-vs-`""`
+ * protocol distinction, and the thinking indicator's suppression rule. Its only
+ * prop is `className`, so the moment a client wants its own bubble markup it
+ * drops all four at once — and the three hand-rolled chromes in the template
+ * tree each shipped a strictly worse conversation for exactly that reason. One
+ * of them runs fifteen tools and its operator sees none of them, because the
+ * tool calls live in a second array nothing in that page ever reads.
+ *
+ * This is the headless half. `<MessageList>` is now a thin consumer of it —
+ * which is the only way to know the hook is complete, since a hook that the
+ * package's own list cannot be built from is a hook a custom chrome will find a
+ * hole in.
+ *
+ * ## It subscribes NARROWLY, and that is half the value
+ *
+ * The three custom chromes also call whole-page `useSession()`, which re-renders
+ * on *every* snapshot change — so a dispatch board re-renders at STT-partial
+ * rate. `<ChatView>` deliberately avoids that with per-field
+ * {@link useSessionSelector} calls, and so does this: a component that reads the
+ * conversation gets the conversation's own update rate, not the session's.
+ */
+import type { ChatMessage, ToolCallInfo } from "./types.ts";
+import { type UseUserTranscriptResult } from "./use-user-transcript.ts";
+/**
+ * One row of the conversation: a finalized message, or a tool invocation.
+ *
+ * A discriminated union rather than two arrays, because the ORDER between them
+ * is the thing this hook computes — handing back two lists would hand back the
+ * problem. `kind` is what a `switch` in a custom renderer narrows on.
+ *
+ * @public
+ */
+export type ConversationItem = {
+    kind: "message";
+    message: ChatMessage;
+} | {
+    kind: "tool";
+    toolCall: ToolCallInfo;
+};
+/**
+ * What {@link useConversation} returns.
+ *
+ * @public
+ */
+export type UseConversationResult = {
+    /**
+     * Messages and tool calls in one list, in the order they happened.
+     *
+     * Referentially stable while neither array changes, so a consumer may map it
+     * inside a `useMemo` keyed on it, or hand rows to `memo()`ed components,
+     * without rebuilding the list on unrelated snapshot updates.
+     */
+    items: readonly ConversationItem[];
+    /**
+     * The agent's utterance as it arrives, or `null` between turns.
+     *
+     * Not yet a member of `items`: it has no id and it is replaced wholesale on
+     * every delta, so it is rendered as its own trailing row and disappears when
+     * the finalized message takes its place.
+     */
+    streaming: string | null;
+    /**
+     * The caller's in-progress turn — {@link useUserTranscript}'s result,
+     * forwarded rather than re-derived, so the `null`-vs-`""` distinction is made
+     * in exactly one place.
+     */
+    transcript: UseUserTranscriptResult;
+    /**
+     * Whether to show a thinking indicator.
+     *
+     * The suppression rule, and it is why this is a field rather than
+     * `state === "thinking"`: the agent is `thinking` for a stretch during which
+     * something ELSE is already saying so. A pending tool call draws its own
+     * spinner, and a trailing agent message means the reply has begun landing —
+     * in both cases a second indicator underneath reads as a second thing
+     * happening. So it is on only while `thinking` with no pending tool call, and
+     * either no messages yet, a trailing USER message, or a settled tool call
+     * after it.
+     */
+    thinking: boolean;
+};
+/**
+ * Subscribe to the conversation: the interleaved exchange, the streaming
+ * utterance, the live transcript and the thinking rule — with no markup.
+ *
+ * Must be used inside the provider `client()` installs.
+ *
+ * @example A custom bubble, keeping every rule `<MessageList>` knows
+ * ```tsx
+ * import { useConversation } from "@alexkroman1/aai-ui";
+ *
+ * function Transcript() {
+ *   const { items, streaming, transcript, thinking } = useConversation();
+ *   return (
+ *     <div>
+ *       {items.map((item) =>
+ *         item.kind === "message" ? (
+ *           <p key={item.message.id} data-role={item.message.role}>
+ *             {item.message.content}
+ *           </p>
+ *         ) : (
+ *           <code key={item.toolCall.callId}>{item.toolCall.name}</code>
+ *         ),
+ *       )}
+ *       {streaming !== null && <p data-role="assistant">{streaming}</p>}
+ *       {transcript.speaking && <p data-role="user">{transcript.text}</p>}
+ *       {thinking && <p>…</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns See {@link UseConversationResult}.
+ *
+ * @public
+ */
+export declare function useConversation(): UseConversationResult;