@alexkroman1/aai-ui 16.1.0 → 18.0.0

package/dist/session-core-audio-effects.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The session core's side of the audio path: every socket frame and snapshot
+ * write the statechart decides on but cannot make itself.
+ *
+ * The split is the one `s2s-lifecycle.ts` draws in the runtime. WHEN a
+ * microphone opens, whether an opening is still wanted, and where audio goes
+ * before there is anywhere to play it are `session-core-audio-state.ts`'s;
+ * this module is HOW — and it is the only half that touches `conn`, the
+ * snapshot, or the wire, which is what lets the machine be specced without a
+ * browser.
+ */
+import type { SessionCommand } from "@alexkroman1/aai/protocol";
+import type { AudioPathEffects } from "./session-core-audio-state.ts";
+import type { SessionStateMachine } from "./session-core-state.ts";
+import { type ConnState, type SessionSnapshot } from "./session-core-types.ts";
+/** What the audio effects need from the owning session core. */
+export type AudioEffectsDeps = {
+    conn: ConnState;
+    updateState: (partial: Partial<SessionSnapshot>) => void;
+    /** The session's state and error, as one fact — see `session-core-state.ts`. */
+    agentState: SessionStateMachine;
+    sendJson: (msg: SessionCommand) => void;
+    sendAudio: (bytes: ArrayBuffer) => void;
+};
+/** Build the effects for one session's audio path. */
+export declare function createAudioEffects(deps: AudioEffectsDeps): AudioPathEffects;

package/dist/session-core-audio-setup.d.ts

@@ -1,20 +1,15 @@
-import type { SessionCommand } from "@alexkroman1/aai/protocol";
+/**
+ * How the audio path is OPENED: the module load, the mic grant, the worklet
+ * registration, and the {@link VoiceIO} those three produce.
+ *
+ * WHEN one is opened, whether it is still wanted by the time it settles, and
+ * what happens to audio that arrives meanwhile all live in
+ * `session-core-audio-state.ts` — the same split `s2s-lifecycle.ts` and
+ * `pipeline-speech-edges.ts` draw in the runtime, and for the same reason:
+ * nothing here reads or writes session state, so it is callable from an
+ * invoked actor and testable without one.
+ */
 import type { VoiceIO } from "./audio.ts";
-import type { SessionStateMachine } from "./session-core-state.ts";
-import { type ConnState, type SessionSnapshot } from "./session-core-types.ts";
-/** Dependencies `initAudioCapture` needs from the owning session core. */
-export type AudioSetupDeps = {
-    sendJson: (msg: SessionCommand) => void;
-    sendAudio: (bytes: ArrayBuffer) => void;
-    updateState: (partial: Partial<SessionSnapshot>) => void;
-    /** The session's state and error, as one fact — see `session-core-state.ts`. */
-    agentState: SessionStateMachine;
-    /** Turn-boundary-guarded drain from the message handlers — replays a
-     *  buffered `audio_done` without stomping a barge-in's state. */
-    settleWhenAudioDrained: (io: VoiceIO) => void;
-    /** Release the mic/VoiceIO (used when the audio path dies non-fatally). */
-    cleanupAudio: () => void;
-};
 type AudioModules = [typeof import("./audio.ts"), string, string];
 /**
  * Load the audio module and worklet sources, memoized so a prefetch at
@@ -23,23 +18,35 @@ type AudioModules = [typeof import("./audio.ts"), string, string];
  * load clears the memo so the next attempt retries the import.
  */
 export declare function loadAudioModules(): Promise<AudioModules>;
+/** The audio parameters the server's `config` frame carries. */
+export type AudioPathConfig = {
+    sampleRate: number;
+    ttsSampleRate: number;
+};
 /**
- * Initialize audio capture and playback after the server sends a ready config.
+ * What a live audio path reports back.
  *
- * Lifecycle: dynamically import audio modules -> request microphone access ->
- * register AudioWorklet processors -> create a `VoiceIO` instance -> send
- * `audio_ready` to the server -> transition state to `"listening"`.
- *
- * Uses the connection `generation` counter to detect if `connect()` was called
- * (or a reconnect happened) while awaiting async operations; if so, the stale
- * VoiceIO is closed immediately to prevent it from being assigned to a newer
- * connection.
+ * Both of the last two used to be guarded at the callback by
+ * `conn.generation.isCurrent(gen)`; they are plain reports now, and whether
+ * one still matters is the state machine's answer — see
+ * `session-core-audio-state.ts`.
+ */
+export type AudioPathCallbacks = {
+    /** Buffered PCM16 from the microphone, for the socket. */
+    onMicData(pcm16: ArrayBuffer): void;
+    /** Unplayed agent audio in the buffer, in ms — the host's closed playback loop. */
+    onProgress(bufferedMs: number): void;
+    /** A worklet processor died after setup: the audio path is gone. */
+    onFailure(message: string): void;
+};
+/**
+ * Open one audio path: load the worklets, ask for the microphone, and build
+ * the {@link VoiceIO} wired to `callbacks`.
  *
- * A failure is fatal: a voice session can't function without the mic, so it
- * sets the error state and ends the session.
+ * Rejects when any of the three refuses — a denied mic prompt being the
+ * ordinary case. The caller owns closing what this resolves: a path that comes
+ * up for a connection nobody wants any more is a live microphone, and no
+ * amount of cancellation upstream releases the device.
  */
-export declare function initAudioCapture(conn: ConnState, msg: {
-    sampleRate: number;
-    ttsSampleRate: number;
-}, deps: AudioSetupDeps): Promise<void>;
+export declare function openAudioPath(config: AudioPathConfig, callbacks: AudioPathCallbacks): Promise<VoiceIO>;
 export {};

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

@@ -0,0 +1,152 @@
+/**
+ * The browser session's AUDIO PATH — the mic grant, the worklets, and the
+ * {@link VoiceIO} they produce — as a statechart.
+ *
+ * It was a latch, an epoch counter and three buffers spread across
+ * `ConnState`, and every one of them was a question the position already
+ * answers:
+ *
+ * - **`audioSetupInFlight` was a dedup, and dedup is a state.**
+ *   `initAudioCapture` opened with `if (conn.audioSetupInFlight) return` and
+ *   closed with "only the init that still owns the flag may clear it", which is
+ *   an ownership problem a boolean cannot express and a position does not have.
+ *   Here `starting` simply does not handle `START`, and there is no flag to
+ *   hand back.
+ * - **`conn.generation` existed for this module and nothing else.** Four
+ *   `bump()` sites, four `isCurrent(gen)` reads, and its own field on
+ *   `ConnState`. All four bumps sat immediately after a `cleanupAudio()` that
+ *   had *just* cleared the in-flight flag — the reconnect close handler said so
+ *   outright ("cleanupAudio just cleared the in-flight flag, so a survivor
+ *   would otherwise pass the same-generation guard and double-run"). Two
+ *   mechanisms for one question, the second one layered on because the first
+ *   could not stop the work already running. A stopped `invoke` can, so the
+ *   counter is gone.
+ * - **A counter cannot tell two bring-ups in ONE generation apart, and they
+ *   happen.** A repeated `config` frame on a live connection re-opened the path
+ *   without bumping anything, so the outgoing `VoiceIO`'s `onError` still
+ *   passed `isCurrent(gen)` and could tear down the replacement that had just
+ *   taken its slot. `PROGRESS` and `IO_FAILED` carry the instance that fired
+ *   them now, and identity is exact where a counter was approximate.
+ * - **`preInitAudio` / `preInitDone` are only meaningful while the path is
+ *   down.** As connection fields they were readable — and writable — from
+ *   anywhere; as context of `down`/`starting` they are cleared by entering
+ *   `down` rather than by three call sites remembering to.
+ *
+ * ## What cancellation does NOT do, and the one guard that had to survive
+ *
+ * Stopping the `bringUp` actor hides its resolution; it does not close a
+ * microphone the browser has already granted. So `bringUp` checks its own
+ * `signal` after `openAudioPath` settles and releases what it built. That is
+ * the single remaining "is this still wanted?" test, and it lives in the
+ * producer — which owns the value nobody adopted — rather than at the four
+ * consumer sites that used to re-ask.
+ *
+ * ## Effects stay in the session core
+ *
+ * The machine owns WHEN. Every HOW — the socket frame, the snapshot write, the
+ * turn-boundary drain — arrives as an injected {@link AudioPathEffects} call,
+ * the same shape `s2s-lifecycle.ts` uses. So this module touches no socket and
+ * no snapshot.
+ */
+import type { VoiceIO } from "./audio.ts";
+import type { AudioPathCallbacks, AudioPathConfig } from "./session-core-audio-setup.ts";
+/** Where the audio path is. */
+export type AudioPathPhase = "down" | "starting" | "up";
+/**
+ * The session core's side of the machine: everything the audio path decides to
+ * do but does not know how to.
+ */
+export type AudioPathEffects = {
+    /**
+     * Open one audio path — `openAudioPath` in `session-core-audio-setup.ts`.
+     * Injected rather than imported so this module needs no browser: the specs
+     * hand it a promise they resolve by hand, which is the only way to hold a
+     * bring-up open across the events that abandon it.
+     */
+    open(config: AudioPathConfig, callbacks: AudioPathCallbacks): Promise<VoiceIO>;
+    /** Relay captured microphone audio to the server. */
+    sendMicAudio(pcm16: ArrayBuffer): void;
+    /** Tell the server how much agent audio is still unplayed. */
+    reportProgress(bufferedMs: number): void;
+    /** Tell the server the microphone is live. */
+    announceReady(): void;
+    /** The microphone is live: the snapshot's `recording`. */
+    micLive(): void;
+    /** Back to the mic, with no audio left to wait for. */
+    listen(): void;
+    /**
+     * Wait for `io` to drain, then listen — guarded by the turn boundary, so a
+     * completion landing after a barge-in or a teardown is discarded.
+     */
+    settleWhenDrained(io: VoiceIO): void;
+    /**
+     * Report a non-fatal audio failure and stop the mic. Non-fatal because the
+     * socket may well still be fine, so a later server frame is allowed to
+     * recover the banner — see `session-core-state.ts`.
+     */
+    reportFailure(message: string): void;
+    /**
+     * The audio path is gone: end whatever turn it was playing.
+     *
+     * Paired with the release below rather than folded into it, because the
+     * bump has to happen on every path into `down` — including a bring-up that
+     * failed before there was anything to close.
+     */
+    endTurn(): void;
+    /** Close `io` and let go of the microphone. Best-effort. */
+    release(io: VoiceIO): void;
+};
+/** Everything that happens to the audio path. */
+export type AudioPathEvent = 
+/** The server's `config` frame: bring the path up for these rates. */
+{
+    type: "START";
+    config: AudioPathConfig;
+}
+/** A PCM16 chunk arrived for playback. */
+ | {
+    type: "CHUNK";
+    chunk: ArrayBuffer;
+}
+/** The server finished sending this turn's audio. */
+ | {
+    type: "DONE";
+}
+/** A live path reported its unplayed depth. */
+ | {
+    type: "PROGRESS";
+    io: VoiceIO;
+    bufferedMs: number;
+}
+/** A live path's worklet died. */
+ | {
+    type: "IO_FAILED";
+    io: VoiceIO;
+    message: string;
+}
+/** Release the audio path: hang-up, reconnect, fatal frame, session end. */
+ | {
+    type: "TEARDOWN";
+};
+/** The session core's handle on its audio path. */
+export type AudioPath = {
+    /** Where the path is. */
+    phase(): AudioPathPhase;
+    /** The server named the audio rates: bring the path up. */
+    start(config: AudioPathConfig): void;
+    /** Play a chunk, or hold it until there is somewhere to play it. */
+    enqueue(chunk: ArrayBuffer): void;
+    /** The server finished this turn's audio. */
+    done(): void;
+    /**
+     * Barge-in: discard what is queued for playback.
+     *
+     * A read rather than an event — it moves the path nowhere, and a turn
+     * boundary is the caller's to declare (see `bargeIn`).
+     */
+    flush(): void;
+    /** Release the microphone and forget anything buffered. */
+    teardown(): void;
+};
+/** Create the audio path for one browser session. */
+export declare function createAudioPath(effects: AudioPathEffects): AudioPath;

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

@@ -1,3 +1,4 @@
+import type { AudioPath } from "./session-core-audio-state.ts";
 import type { SessionStateMachine } from "./session-core-state.ts";
 import { type ConnState, type SessionSnapshot } from "./session-core-types.ts";
 /**
@@ -28,8 +29,14 @@ type MessageHandlerDeps = {
     conn: ConnState;
     /** The session's state and error, as one fact — see `session-core-state.ts`. */
     agentState: SessionStateMachine;
-    /** Release the microphone/VoiceIO (the session core's `cleanupAudio`). */
-    cleanupAudio: () => void;
+    /**
+     * The microphone and the playback queue — see
+     * `session-core-audio-state.ts`. Frames say what happened (`enqueue`,
+     * `done`, `teardown`); whether the path is up, and what to do with audio
+     * that arrives before it is, are the machine's answers rather than this
+     * module's.
+     */
+    audio: AudioPath;
 };
 type MessageHandlers = {
     /**
@@ -42,14 +49,6 @@ type MessageHandlers = {
      * otherwise `undefined`.
      */
     handleMessage(data: unknown): SessionConfigMessage | undefined;
-    /**
-     * Wait for `io`'s playback queue to drain, then transition to `"listening"`
-     * — guarded by the same turn-boundary generation the live `audio.completed`
-     * path uses. `initAudioCapture` routes the pre-init greeting replay
-     * through this so a barge-in mid-greeting can't be stomped by the
-     * replayed completion resolving late.
-     */
-    settleWhenAudioDrained(io: NonNullable<ConnState["voiceIO"]>): void;
 };
 /**
  * Create the server→client message handlers for one session core.

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

@@ -4,7 +4,7 @@
  * Split out of `session-core.ts` to keep that module focused on behaviour.
  */
 import type { Epoch } from "@alexkroman1/aai/internal";
-import type { VoiceIO } from "./audio.ts";
+import type { AudioPath } from "./session-core-audio-state.ts";
 import type { AgentState, ChatMessage, SessionError, ToolCallInfo, WebSocketConstructor } from "./types.ts";
 /**
  * A custom event emitted by the agent via `ctx.send(event, data)` — the
@@ -140,6 +140,45 @@ export type SessionSnapshot = {
      */
     readonly running: boolean;
 };
+/**
+ * The seal on a {@link BrowserSession}.
+ *
+ * TYPE-ONLY — there is no value at run time, so an object literal cannot carry
+ * the key and only `createBrowserSession` mints a session. That is what lets
+ * the handle grow a member without breaking anybody: push-to-talk added three
+ * REQUIRED methods and broke every hand-written double, which is the failure a
+ * handle a caller RECEIVES should not be able to cause.
+ *
+ * @public
+ */
+export declare const browserSessionBrand: unique symbol;
+/**
+ * Push-to-talk's three edges on a {@link BrowserSession} — `session.userTurn`.
+ *
+ * Only an agent declaring `turnDetection: "manual"` honours them; any other
+ * agent logs once and ignores them, because its transcriber already ends each
+ * turn on a pause. `usePushToTalk` is the hook a button is built on, and the
+ * way a `client.tsx` reaches these: a sub-handle rather than three methods on
+ * the session, so a feature one agent in many declares is not three members
+ * every session carries in its autocomplete.
+ *
+ * @public
+ */
+export type UserTurnControls = {
+    /**
+     * OPEN a turn — the button went down. Stops the agent if it is speaking
+     * (discarding its queued audio here at once, rather than a round trip later)
+     * and lets the microphone through to the transcriber.
+     */
+    start(): void;
+    /** CLOSE the turn and have the agent answer everything said since `start()` — the button came up. */
+    commit(): void;
+    /**
+     * Close the turn and THROW AWAY what was said in it — a cancelled press (the
+     * pointer left the button, Escape). The agent answers nothing.
+     */
+    clear(): void;
+};
 /**
  * A framework-agnostic voice session that manages WebSocket communication,
  * audio capture/playback, and agent state transitions.
@@ -147,9 +186,15 @@ export type SessionSnapshot = {
  * Uses a subscribe/getSnapshot pattern (compatible with React's
  * `useSyncExternalStore`). Implements `Disposable` for resource cleanup.
  *
+ * @sealed Only `createBrowserSession` produces one — see
+ * {@link browserSessionBrand}. A test double for a component is a real
+ * session with no socket, not an object literal.
+ *
  * @public
  */
 export type BrowserSession = {
+    /** The seal — see {@link browserSessionBrand}. */
+    readonly [browserSessionBrand]: true;
     /** Return the current immutable state snapshot. */
     getSnapshot(): SessionSnapshot;
     /** Subscribe to state changes. Returns an unsubscribe function. */
@@ -166,6 +211,8 @@ export type BrowserSession = {
     }): void;
     /** Cancel the current agent turn and discard in-flight TTS audio. */
     cancel(): void;
+    /** Push-to-talk's three edges — see {@link UserTurnControls}. */
+    readonly userTurn: UserTurnControls;
     /**
      * Clear messages, transcripts, and error state while keeping the current
      * connection (unlike `reset()`, which also reconnects).
@@ -223,11 +270,18 @@ export type BrowserSession = {
     [Symbol.dispose](): void;
 };
 /**
- * Shared mutable connection state for audio initialization.
+ * Shared mutable connection state.
+ *
+ * **It used to carry the audio path too**, and the four fields that went are
+ * worth naming because the shape recurs: a `voiceIO` slot, an
+ * `audioSetupInFlight` latch, a `generation` epoch whose only readers were the
+ * bring-up's four staleness checks, and the two pre-init buffers. Each was a
+ * question about a position the connection did not have, readable and writable
+ * from anywhere. They are the audio path's own statechart now — see
+ * `session-core-audio-state.ts`.
  *
- * Tracks the active WebSocket, VoiceIO instance, and a generation counter
- * that prevents stale async operations (e.g. a slow `initAudioCapture`) from
- * assigning their results to a newer connection after a reconnect.
+ * What is left is what the CONNECTION really owns: the socket, the server's
+ * idle retirement, and the turn boundary.
  */
 export type ConnState = {
     ws: InstanceType<WebSocketConstructor> | null;
@@ -242,12 +296,6 @@ export type ConnState = {
      * reconnect on demand).
      */
     retiredByServer: boolean;
-    voiceIO: VoiceIO | null;
-    audioSetupInFlight: boolean;
-    /** Connection epoch, bumped on each connect()/retry (see `createEpoch`).
-     *  Prevents a stale initAudioCapture from assigning its voiceIO to a newer
-     *  connection. */
-    generation: Epoch;
     /**
      * Turn epoch, bumped at every turn boundary — a committed user turn, a
      * barge-in, a reset, AND every audio-path teardown (`cleanupAudio`).
@@ -261,15 +309,6 @@ export type ConnState = {
      * later — a dead session reporting a live mic.
      */
     turn: Epoch;
-    /** Audio chunks that arrived before `voiceIO` was initialized — drained into
-     *  the playback worklet once init completes. Closes the race between the
-     *  server starting greeting audio (immediately on S2S connect) and the
-     *  client awaiting mic permission + worklet registration. */
-    preInitAudio: ArrayBuffer[];
-    /** True if `audio_done` arrived before `voiceIO` was initialized. The done
-     *  signal must be replayed after draining preInitAudio, or a short greeting
-     *  buffered during mic-permission never finishes playing. */
-    preInitDone: boolean;
 };
 /**
  * The two liveness fields at rest.
@@ -303,4 +342,4 @@ export declare const STOPPED: {
  * bump on its own now reads as a deliberate choice rather than a forgotten
  * flush.
  */
-export declare function bargeIn(conn: ConnState): void;
+export declare function bargeIn(conn: ConnState, audio: AudioPath): void;

package/dist/session-core-user-turn.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Push-to-talk's three edges on the browser session — `session.userTurn`'s
+ * `start`, `commit` and `clear` — for an agent that declares
+ * `turnDetection: "manual"`.
+ *
+ * Split out of `session-core.ts` at the source-length cap. Each is a frame to
+ * the server; what the server does with it is `aai-runtime`'s
+ * `pipeline-manual-turn.ts`. The two things done HERE rather than waiting a
+ * round trip for are the reason these are more than `sendJson` calls: a press
+ * stops the agent's queued audio at once, and a discarded turn's caption is
+ * cleared because no transcript for it will ever arrive.
+ *
+ * @module
+ */
+import type { SessionCommand } from "@alexkroman1/aai/protocol";
+import type { SessionStateMachine } from "./session-core-state.ts";
+import type { SessionSnapshot, UserTurnControls } from "./session-core-types.ts";
+/** What the three edges need from the session around them. @internal */
+export type UserTurnDeps = {
+    snapshot: () => SessionSnapshot;
+    /** A socket is open and can carry a frame. */
+    connected: () => boolean;
+    /** The local turn boundary — see `bargeIn` in `session-core-types.ts`. */
+    bargeIn: () => void;
+    agentState: SessionStateMachine;
+    updateState: (partial: Partial<SessionSnapshot>) => void;
+    sendJson: (msg: SessionCommand) => void;
+};
+/** Build the three push-to-talk edges. @internal */
+export declare function createUserTurnActions(deps: UserTurnDeps): UserTurnControls;

package/dist/session-core.js

@@ -1,2 +1,2 @@
-import { t as createBrowserSession } from "./session-core-gwePM95B.js";
+import { t as createBrowserSession } from "./session-core-TOdm_Con.js";
 export { createBrowserSession };

package/dist/use-push-to-talk.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `usePushToTalk` — a hold-to-speak button, for an agent that declares
+ * `turnDetection: "manual"`.
+ *
+ * The three session edges underneath (`session.userTurn`'s `start`, `commit`
+ * and `clear`) are one line each; what a button needs on top of them is
+ * where hand-written versions go wrong, and every one of the four is a turn
+ * that is left OPEN — the microphone live and nothing ever answered:
+ *
+ * - **The pointer leaves.** A `mouseup` outside the button never reaches it.
+ *   The handlers here capture the pointer on the way down, so the release
+ *   arrives wherever it happens; an `onPointerCancel` (a scroll gesture, a
+ *   system dialog) DISCARDS the turn rather than answering half a sentence.
+ * - **The key repeats.** Holding a key fires `keydown` over and over, and each
+ *   one would re-open the turn. Only the first counts.
+ * - **The window loses focus mid-hold.** The `keyup` goes to another window
+ *   and is never delivered, so the turn is committed on `blur` — what the
+ *   caller would have done had the release been seen.
+ * - **The component unmounts mid-hold.** The turn is discarded on the way out.
+ *
+ * And one that is a nuisance rather than a stuck turn: the hold key is ignored
+ * while focus is in a text field, where Space is a character.
+ */
+/** Options for {@link usePushToTalk}. */
+export type UsePushToTalkOptions = {
+    /**
+     * The keyboard key that holds the turn open, as a `KeyboardEvent.code` —
+     * `"Space"` by default, so the whole page is a walkie-talkie. `false` turns
+     * the global key off; the button itself still answers Space and Enter while
+     * it has focus.
+     */
+    holdKey?: string | false;
+};
+/**
+ * What {@link usePushToTalk} returns.
+ *
+ * @public
+ */
+export type UsePushToTalkResult = {
+    /** Whether a turn is being held open right now — the button is DOWN. */
+    talking: boolean;
+    /**
+     * Whether pressing would do anything: the call is live. False before Start
+     * and while paused, which is when a button should render disabled.
+     */
+    ready: boolean;
+    /** Open a turn. Interrupts the agent if it is speaking. Ignored while held. */
+    press: () => void;
+    /** Close the turn and have the agent answer it. Ignored unless held. */
+    release: () => void;
+    /** Close the turn and discard it — nothing is answered. Ignored unless held. */
+    cancel: () => void;
+    /**
+     * Spread onto a `<button>`: pointer capture, the keyboard pair, and
+     * `aria-pressed`. The handlers are the whole contract — style it however you
+     * like.
+     */
+    buttonProps: {
+        onPointerDown: (event: {
+            currentTarget: Element;
+            pointerId: number;
+        }) => void;
+        onPointerUp: () => void;
+        onPointerCancel: () => void;
+        onKeyDown: (event: {
+            key: string;
+            repeat: boolean;
+            preventDefault(): void;
+        }) => void;
+        onKeyUp: (event: {
+            key: string;
+            preventDefault(): void;
+        }) => void;
+        onContextMenu: (event: {
+            preventDefault(): void;
+        }) => void;
+        disabled: boolean;
+        "aria-pressed": boolean;
+    };
+};
+/**
+ * Hold-to-speak over the session's push-to-talk methods, with the four ways a
+ * turn gets stuck open handled — see this module's doc.
+ *
+ * Must be used inside the provider `mountClient()` installs, against an agent
+ * declaring `turnDetection: "manual"`; any other agent ignores the commands and
+ * its server says so once.
+ *
+ * @example A hold-to-talk button
+ * ```tsx
+ * import { usePushToTalk } from "@alexkroman1/aai-ui";
+ *
+ * function TalkButton() {
+ *   const { talking, buttonProps } = usePushToTalk();
+ *   return (
+ *     <button type="button" {...buttonProps}>
+ *       {talking ? "Listening… release to send" : "Hold to talk (or hold Space)"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function usePushToTalk(options?: UsePushToTalkOptions): UsePushToTalkResult;

package/dist/{use-workflow-run-CNahvlgL.js → use-workflow-run-ZqJWJn2-.js}

@@ -1,8 +1,8 @@
 import { t as pageBaseUrl } from "./_utils-DnQDM9Uy.js";
-import { useCallback, useEffect, useRef, useState } from "react";
 import { errorMessage } from "@alexkroman1/aai";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { omitUndefined } from "@alexkroman1/aai/utils";
-import { createWorkflowApiClient, isTerminal, isTerminal as isTerminal$1, readEventStream } from "@alexkroman1/aai/workflow-api";
+import { createAgentClient, isTerminal, isTerminal as isTerminal$1, readEventStream } from "@alexkroman1/aai/workflow-api";
 //#region src/workflow-client.ts
 /**
 * Browser client for the workflow HTTP API (`aai/host/workflow-api.ts`).
@@ -31,20 +31,28 @@ import { createWorkflowApiClient, isTerminal, isTerminal as isTerminal$1, readEv
 * fast path under it in `workflow-events.ts`.
 */
 /**
-* Create a workflow API client aimed at the agent serving this page.
+* Create a client for the agent serving this page.
+*
+* **You usually do not need one.** Every hook and component here builds this
+* exact client lazily and once when no `api` is passed
+* (`_workflow-api-ref.ts`), so `useWorkflowSubmit("digest")` already talks to
+* the right agent. Reach for this when the client has to be DIFFERENT from that
+* default — another agent's `baseUrl`, or a `token` — or when a page wants
+* `config()` and the run calls on one object.
 *
-* Hoist it out of the component that uses it. `useWorkflowRun` holds the client
-* in a ref precisely so a fresh object per render does not restart its watch,
-* but a client built in render is still a new `fetch` closure every time and
-* reads as though it were free.
+* If you do build one, hoist it out of the component that uses it.
+* `useWorkflowRun` holds the client in a ref precisely so a fresh object per
+* render does not restart its watch, but a client built in render is still a new
+* `fetch` closure every time and reads as though it were free.
 *
 * @example
 * ```tsx
 * import { createWorkflowApi, useWorkflowRun } from "@alexkroman1/aai-ui";
 * import { useState } from "react";
 *
-* // Module scope, not render scope — see above.
-* const api = createWorkflowApi();
+* // A DIFFERENT agent than the one serving this page, so the client is
+* // explicit — and module scope, not render scope, per above.
+* const api = createWorkflowApi({ baseUrl: "https://agents.example/digest" });
 *
 * function StartDigest() {
 *   const [runId, setRunId] = useState<string>();
@@ -62,12 +70,17 @@ import { createWorkflowApiClient, isTerminal, isTerminal as isTerminal$1, readEv
 *
 * @param options - See {@link WorkflowApiOptions}. Both fields are optional; the
 * default base URL is the page's own origin and path.
-* @returns The call set — see {@link WorkflowApi}.
+* @returns Every workflow call plus `config()` and `baseUrl` — see
+* {@link AgentClient}. It was the narrow {@link WorkflowApi}, which left a page
+* that also wanted the agent's own name building a SECOND client (or a bare
+* `fetch` and a hand-written URL join) for one read; the SDK documents
+* `createAgentClient` as a superset of the same routes, so delegating to it
+* widens the return without a second implementation of anything.
 *
 * @public
 */
 function createWorkflowApi(options = {}) {
-	return createWorkflowApiClient({
+	return createAgentClient({
 		baseUrl: options.baseUrl ?? pageBaseUrl(),
 		...omitUndefined({ token: options.token })
 	});