@alexkroman1/aai-ui 0.9.0

package/dist/_components/tool-icons.js

@@ -0,0 +1,128 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+//#region _components/tool-icons.tsx
+/** Magnifying glass icon for web_search. */
+function SearchIcon(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		"stroke-width": "1.5",
+		class: props.class,
+		children: [/* @__PURE__ */ jsx("circle", {
+			cx: "7",
+			cy: "7",
+			r: "4.5"
+		}), /* @__PURE__ */ jsx("path", {
+			d: "M10.5 10.5L14 14",
+			"stroke-linecap": "round"
+		})]
+	});
+}
+/** External link icon for visit_webpage. */
+function ExternalLinkIcon(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		"stroke-width": "1.5",
+		class: props.class,
+		children: [
+			/* @__PURE__ */ jsx("path", {
+				d: "M6 2H3a1 1 0 00-1 1v10a1 1 0 001 1h10a1 1 0 001-1v-3",
+				"stroke-linecap": "round"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M9 2h5v5",
+				"stroke-linecap": "round",
+				"stroke-linejoin": "round"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M14 2L7 9",
+				"stroke-linecap": "round"
+			})
+		]
+	});
+}
+/** Terminal icon for run_code. */
+function TerminalIcon(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		"stroke-width": "1.5",
+		class: props.class,
+		children: [
+			/* @__PURE__ */ jsx("rect", {
+				x: "1",
+				y: "2",
+				width: "14",
+				height: "12",
+				rx: "1.5"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M4 6l3 2.5L4 11",
+				"stroke-linecap": "round",
+				"stroke-linejoin": "round"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M9 11h3",
+				"stroke-linecap": "round"
+			})
+		]
+	});
+}
+/** Download icon for fetch_json. */
+function DownloadIcon(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		"stroke-width": "1.5",
+		class: props.class,
+		children: [
+			/* @__PURE__ */ jsx("path", {
+				d: "M8 2v9",
+				"stroke-linecap": "round"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M4.5 8L8 11.5 11.5 8",
+				"stroke-linecap": "round",
+				"stroke-linejoin": "round"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M2 13h12",
+				"stroke-linecap": "round"
+			})
+		]
+	});
+}
+/** Chat bubble icon for user_input. */
+function ChatBubbleIcon(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		"stroke-width": "1.5",
+		class: props.class,
+		children: /* @__PURE__ */ jsx("path", {
+			d: "M2 3a1 1 0 011-1h10a1 1 0 011 1v7a1 1 0 01-1 1H5l-3 3V3z",
+			"stroke-linejoin": "round"
+		})
+	});
+}
+/** Bolt/lightning icon for default/unknown tools. */
+function BoltIcon(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		"stroke-width": "1.5",
+		class: props.class,
+		children: /* @__PURE__ */ jsx("path", {
+			d: "M9 1L3 9h5l-1 6 6-8H8l1-6z",
+			"stroke-linejoin": "round"
+		})
+	});
+}
+//#endregion
+export { BoltIcon, ChatBubbleIcon, DownloadIcon, ExternalLinkIcon, SearchIcon, TerminalIcon };

package/dist/_components/transcript.d.ts

@@ -0,0 +1,7 @@
+import type * as preact from "preact";
+import type { Reactive } from "../types.ts";
+/** @public */
+export declare function Transcript({ userUtterance, className, }: {
+    userUtterance: Reactive<string | null>;
+    className?: string;
+}): preact.JSX.Element | null;

package/dist/_components/transcript.js

@@ -0,0 +1,17 @@
+import { ThinkingIndicator } from "./thinking-indicator.js";
+import clsx from "clsx";
+import { jsx } from "preact/jsx-runtime";
+//#region _components/transcript.tsx
+/** @public */
+function Transcript({ userUtterance, className }) {
+	if (userUtterance.value === null) return null;
+	return /* @__PURE__ */ jsx("div", {
+		class: clsx("flex flex-col items-end w-full", className),
+		children: /* @__PURE__ */ jsx("div", {
+			class: "max-w-[min(82%,64ch)] whitespace-pre-wrap wrap-break-word text-sm leading-[150%] text-aai-text-muted bg-aai-surface-faint border border-aai-border px-3 py-2 rounded-aai ml-auto",
+			children: userUtterance.value || /* @__PURE__ */ jsx(ThinkingIndicator, {})
+		})
+	});
+}
+//#endregion
+export { Transcript };

package/dist/audio.d.ts

@@ -0,0 +1,45 @@
+/** Configuration for creating a {@link VoiceIO} instance. */
+export type VoiceIOOptions = {
+    /** Sample rate in Hz expected by the STT engine (e.g. 16000). */
+    sttSampleRate: number;
+    /** Sample rate in Hz used by the TTS engine (e.g. 22050). */
+    ttsSampleRate: number;
+    /** Source URL or data URI for the capture AudioWorklet processor. */
+    captureWorkletSrc: string;
+    /** Source URL or data URI for the playback AudioWorklet processor. */
+    playbackWorkletSrc: string;
+    /** Callback invoked with buffered PCM16 microphone data to send to the server. */
+    onMicData: (pcm16: ArrayBuffer) => void;
+    /** Callback invoked with the current playback position in samples. */
+    onPlaybackProgress?: (samplesPlayed: number) => void;
+};
+/**
+ * Audio I/O interface for voice capture and playback.
+ *
+ * Manages microphone capture via an AudioWorklet, resampling to the STT
+ * sample rate, and TTS audio playback through a second AudioWorklet. Implements
+ * {@link AsyncDisposable} for resource cleanup.
+ */
+export type VoiceIO = AsyncDisposable & {
+    /** Enqueue a PCM16 audio buffer for playback through the TTS pipeline. */
+    enqueue(pcm16Buffer: ArrayBuffer): void;
+    /** Signal that all TTS audio for the current turn has been enqueued.
+     *  Resolves when the worklet has finished playing all buffered audio. */
+    done(): Promise<void>;
+    /** Immediately stop playback and discard any buffered TTS audio. */
+    flush(): void;
+    /** Release all audio resources (microphone, AudioContext, worklets). */
+    close(): Promise<void>;
+};
+/**
+ * Create a {@link VoiceIO} instance that captures microphone audio and
+ * plays back TTS audio using the Web Audio API.
+ *
+ * The AudioContext runs at the TTS sample rate for playback fidelity.
+ * Captured audio is resampled to the STT rate when the rates differ.
+ *
+ * @param opts - Voice I/O configuration options.
+ * @returns A promise that resolves to a {@link VoiceIO} handle.
+ * @throws If microphone access is denied or AudioWorklet registration fails.
+ */
+export declare function createVoiceIO(opts: VoiceIOOptions): Promise<VoiceIO>;

package/dist/audio.js

@@ -0,0 +1,111 @@
+import { MIC_BUFFER_SECONDS } from "./types.js";
+//#region audio.ts
+/**
+* Create a {@link VoiceIO} instance that captures microphone audio and
+* plays back TTS audio using the Web Audio API.
+*
+* The AudioContext runs at the TTS sample rate for playback fidelity.
+* Captured audio is resampled to the STT rate when the rates differ.
+*
+* @param opts - Voice I/O configuration options.
+* @returns A promise that resolves to a {@link VoiceIO} handle.
+* @throws If microphone access is denied or AudioWorklet registration fails.
+*/
+async function createVoiceIO(opts) {
+	const { sttSampleRate, ttsSampleRate, captureWorkletSrc, playbackWorkletSrc, onMicData } = opts;
+	const contextRate = ttsSampleRate;
+	const ctx = new AudioContext({
+		sampleRate: contextRate,
+		latencyHint: "playback"
+	});
+	await ctx.resume();
+	const stream = await navigator.mediaDevices.getUserMedia({ audio: {
+		sampleRate: contextRate,
+		echoCancellation: true,
+		noiseSuppression: true,
+		autoGainControl: true
+	} });
+	try {
+		await Promise.all([ctx.audioWorklet.addModule(captureWorkletSrc), ctx.audioWorklet.addModule(playbackWorkletSrc)]);
+	} catch (err) {
+		for (const t of stream.getTracks()) t.stop();
+		await ctx.close().catch(() => {});
+		throw err;
+	}
+	const mic = ctx.createMediaStreamSource(stream);
+	const capNode = new AudioWorkletNode(ctx, "capture-processor", {
+		channelCount: 1,
+		channelCountMode: "explicit",
+		processorOptions: {
+			contextRate,
+			sttSampleRate
+		}
+	});
+	mic.connect(capNode);
+	const chunkSizeBytes = Math.floor(sttSampleRate * MIC_BUFFER_SECONDS) * 2;
+	const capBuf = new Uint8Array(chunkSizeBytes * 2);
+	let capOffset = 0;
+	capNode.port.postMessage({ event: "start" });
+	capNode.port.onmessage = (e) => {
+		if (e.data.event !== "chunk") return;
+		const chunk = new Uint8Array(e.data.buffer);
+		capBuf.set(chunk, capOffset);
+		capOffset += chunk.byteLength;
+		if (capOffset >= chunkSizeBytes) {
+			onMicData(capBuf.slice(0, capOffset).buffer);
+			capOffset = 0;
+		}
+	};
+	let playNode = null;
+	let onPlaybackStop = null;
+	const lifecycle = new AbortController();
+	const { onPlaybackProgress } = opts;
+	function ensurePlayNode() {
+		if (playNode) return playNode;
+		const node = new AudioWorkletNode(ctx, "playback-processor", { processorOptions: { sampleRate: contextRate } });
+		node.connect(ctx.destination);
+		node.port.onmessage = (e) => {
+			if (e.data.event === "stop") {
+				node.disconnect();
+				if (playNode === node) playNode = null;
+				onPlaybackStop?.();
+				onPlaybackStop = null;
+			} else if (e.data.event === "progress") onPlaybackProgress?.(e.data.readPos);
+		};
+		playNode = node;
+		return node;
+	}
+	const io = {
+		enqueue(pcm16Buffer) {
+			if (lifecycle.signal.aborted) return;
+			if (pcm16Buffer.byteLength === 0) return;
+			ensurePlayNode().port.postMessage({
+				event: "write",
+				buffer: new Uint8Array(pcm16Buffer)
+			}, [pcm16Buffer]);
+		},
+		done() {
+			if (!playNode) return Promise.resolve();
+			return new Promise((resolve) => {
+				onPlaybackStop = resolve;
+				playNode?.port.postMessage({ event: "done" });
+			});
+		},
+		flush() {
+			if (playNode) playNode.port.postMessage({ event: "interrupt" });
+		},
+		async close() {
+			if (lifecycle.signal.aborted) return;
+			lifecycle.abort();
+			capNode.port.postMessage({ event: "stop" });
+			for (const t of stream.getTracks()) t.stop();
+			await ctx.close().catch(() => {});
+		},
+		async [Symbol.asyncDispose]() {
+			await io.close();
+		}
+	};
+	return io;
+}
+//#endregion
+export { createVoiceIO };

package/dist/components.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Preact UI components for AAI voice agents.
+ *
+ * Provides ready-made components, session context, and mount helpers.
+ *
+ * @example
+ * ```tsx
+ * import { App, mount } from "@aai/ui/components";
+ *
+ * mount(App, { target: "#app" });
+ * ```
+ */
+export { App } from "./_components/app.tsx";
+export { Button } from "./_components/button.tsx";
+export { ChatView } from "./_components/chat-view.tsx";
+export { Controls } from "./_components/controls.tsx";
+export { ErrorBanner } from "./_components/error-banner.tsx";
+export { MessageBubble } from "./_components/message-bubble.tsx";
+export { MessageList } from "./_components/message-list.tsx";
+export { SidebarLayout } from "./_components/sidebar-layout.tsx";
+export { StartScreen } from "./_components/start-screen.tsx";
+export { StateIndicator } from "./_components/state-indicator.tsx";
+export { ThinkingIndicator } from "./_components/thinking-indicator.tsx";
+export { ToolCallBlock } from "./_components/tool-call-block.tsx";
+export { Transcript } from "./_components/transcript.tsx";
+export type { MountHandle, MountOptions } from "./mount.tsx";
+export { mount } from "./mount.tsx";
+export type { MountConfig, MountTheme } from "./mount-context.ts";
+export { useMountConfig } from "./mount-context.ts";
+export type { SessionSignals } from "./signals.ts";
+export { createSessionControls, SessionProvider, useAutoScroll, useSession, useToolResult, } from "./signals.ts";

package/dist/components.js

@@ -0,0 +1,17 @@
+import { useMountConfig } from "./mount-context.js";
+import { SessionProvider, createSessionControls, useAutoScroll, useSession, useToolResult } from "./signals.js";
+import { Button } from "./_components/button.js";
+import { Controls } from "./_components/controls.js";
+import { ErrorBanner } from "./_components/error-banner.js";
+import { MessageBubble } from "./_components/message-bubble.js";
+import { ThinkingIndicator } from "./_components/thinking-indicator.js";
+import { ToolCallBlock } from "./_components/tool-call-block.js";
+import { Transcript } from "./_components/transcript.js";
+import { MessageList } from "./_components/message-list.js";
+import { StateIndicator } from "./_components/state-indicator.js";
+import { ChatView } from "./_components/chat-view.js";
+import { StartScreen } from "./_components/start-screen.js";
+import { App } from "./_components/app.js";
+import { SidebarLayout } from "./_components/sidebar-layout.js";
+import { mount } from "./mount.js";
+export { App, Button, ChatView, Controls, ErrorBanner, MessageBubble, MessageList, SessionProvider, SidebarLayout, StartScreen, StateIndicator, ThinkingIndicator, ToolCallBlock, Transcript, createSessionControls, mount, useAutoScroll, useMountConfig, useSession, useToolResult };

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser client library for AAI voice agents.
+ *
+ * Provides WebSocket session management, audio capture/playback,
+ * and Preact UI components. For narrower imports, use the sub-path exports:
+ *
+ * - `@aai/ui/session` — WebSocket session only (no Preact dependency)
+ * - `@aai/ui/components` — Preact components, mount helpers, and signals
+ *
+ * @example
+ * ```tsx
+ * import { App, mount } from "@aai/ui";
+ *
+ * mount(App, { target: "#app" });
+ * ```
+ */
+export * from "./components.ts";
+export type { VoiceSession } from "./session.ts";
+export { createVoiceSession } from "./session.ts";
+export type { AgentState, Message, Reactive, SessionError, SessionErrorCode, SessionOptions, ToolCallInfo, } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,19 @@
+import { useMountConfig } from "./mount-context.js";
+import { SessionProvider, createSessionControls, useAutoScroll, useSession, useToolResult } from "./signals.js";
+import { Button } from "./_components/button.js";
+import { Controls } from "./_components/controls.js";
+import { ErrorBanner } from "./_components/error-banner.js";
+import { MessageBubble } from "./_components/message-bubble.js";
+import { ThinkingIndicator } from "./_components/thinking-indicator.js";
+import { ToolCallBlock } from "./_components/tool-call-block.js";
+import { Transcript } from "./_components/transcript.js";
+import { MessageList } from "./_components/message-list.js";
+import { StateIndicator } from "./_components/state-indicator.js";
+import { ChatView } from "./_components/chat-view.js";
+import { StartScreen } from "./_components/start-screen.js";
+import { App } from "./_components/app.js";
+import { SidebarLayout } from "./_components/sidebar-layout.js";
+import { createVoiceSession } from "./session.js";
+import { mount } from "./mount.js";
+import "./components.js";
+export { App, Button, ChatView, Controls, ErrorBanner, MessageBubble, MessageList, SessionProvider, SidebarLayout, StartScreen, StateIndicator, ThinkingIndicator, ToolCallBlock, Transcript, createSessionControls, createVoiceSession, mount, useAutoScroll, useMountConfig, useSession, useToolResult };

package/dist/mount-context.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Theme overrides for the default UI. Applied as CSS custom properties.
+ *
+ * @public
+ */
+export type MountTheme = {
+    /** Background color. Default: `#101010`. */
+    bg?: string;
+    /** Primary accent color. Default: `#fab283`. */
+    primary?: string;
+    /** Main text color. */
+    text?: string;
+    /** Surface/card color. */
+    surface?: string;
+    /** Border color. */
+    border?: string;
+};
+/**
+ * Resolved mount-level configuration available to default UI components.
+ *
+ * @public
+ */
+export type MountConfig = {
+    title?: string | undefined;
+    theme?: MountTheme | undefined;
+};
+export declare const MountConfigProvider: import("preact").Provider<MountConfig>;
+/**
+ * Read mount config (title, theme) from the nearest provider.
+ *
+ * @public
+ */
+export declare function useMountConfig(): MountConfig;

package/dist/mount-context.js

@@ -0,0 +1,15 @@
+import { createContext } from "preact";
+import { useContext } from "preact/hooks";
+//#region mount-context.ts
+const Ctx = createContext({});
+const MountConfigProvider = Ctx.Provider;
+/**
+* Read mount config (title, theme) from the nearest provider.
+*
+* @public
+*/
+function useMountConfig() {
+	return useContext(Ctx);
+}
+//#endregion
+export { MountConfigProvider, useMountConfig };

package/dist/mount.d.ts

@@ -0,0 +1,51 @@
+import type { ComponentType } from "preact";
+import { type MountTheme } from "./mount-context.ts";
+import { type VoiceSession } from "./session.ts";
+import { type SessionSignals } from "./signals.ts";
+/**
+ * Options for {@link mount}.
+ *
+ * @public
+ */
+export type MountOptions = {
+    /** CSS selector or DOM element to render into. Defaults to `"#app"`. */
+    target?: string | HTMLElement;
+    /** Base URL of the AAI platform server. Derived from `location.href` by default. */
+    platformUrl?: string;
+    /** Agent title shown in the header and start screen. */
+    title?: string;
+    /** Theme color overrides. */
+    theme?: MountTheme;
+};
+/**
+ * Handle returned by {@link mount} for cleanup.
+ *
+ * Implements `Disposable` so it can be used with `using`.
+ *
+ * @public
+ */
+export type MountHandle = {
+    /** The underlying voice session. */
+    session: VoiceSession;
+    /** Reactive session controls for the mounted UI. */
+    signals: SessionSignals;
+    /** Unmount the UI, remove injected styles, and disconnect the session. */
+    dispose(): void;
+    /** Alias for `dispose` for use with `using`. */
+    [Symbol.dispose](): void;
+};
+/**
+ * Mount a Preact component with voice session wiring.
+ *
+ * Creates a {@link VoiceSession}, wraps it in
+ * {@link SessionSignals}, and renders the component
+ * inside a {@link SessionProvider}.
+ *
+ * @param Component - The Preact component to render.
+ * @param options - Mount options (target element, platform URL).
+ * @returns A {@link MountHandle} for cleanup.
+ * @throws If the target element is not found in the DOM.
+ *
+ * @public
+ */
+export declare function mount(Component: ComponentType<any>, options?: MountOptions): MountHandle;

package/dist/mount.js

@@ -0,0 +1,70 @@
+import { MountConfigProvider } from "./mount-context.js";
+import { SessionProvider, createSessionControls } from "./signals.js";
+import { createVoiceSession } from "./session.js";
+import { render } from "preact";
+import { batch, signal } from "@preact/signals";
+import { jsx } from "preact/jsx-runtime";
+//#region mount.tsx
+function resolveContainer(target = "#app") {
+	const el = typeof target === "string" ? document.querySelector(target) : target;
+	if (!el) throw new Error(`Element not found: ${target}`);
+	return el;
+}
+/**
+* Mount a Preact component with voice session wiring.
+*
+* Creates a {@link VoiceSession}, wraps it in
+* {@link SessionSignals}, and renders the component
+* inside a {@link SessionProvider}.
+*
+* @param Component - The Preact component to render.
+* @param options - Mount options (target element, platform URL).
+* @returns A {@link MountHandle} for cleanup.
+* @throws If the target element is not found in the DOM.
+*
+* @public
+*/
+function mount(Component, options) {
+	const container = resolveContainer(options?.target);
+	const session = createVoiceSession({
+		platformUrl: options?.platformUrl ?? globalThis.location.origin + globalThis.location.pathname,
+		signal,
+		batch
+	});
+	const signals = createSessionControls(session);
+	const mountConfig = {
+		title: options?.title,
+		theme: options?.theme
+	};
+	if (options?.theme) {
+		const t = options.theme;
+		const el = container;
+		if (t.bg) el.style.setProperty("--color-aai-bg", t.bg);
+		if (t.primary) el.style.setProperty("--color-aai-primary", t.primary);
+		if (t.text) el.style.setProperty("--color-aai-text", t.text);
+		if (t.surface) el.style.setProperty("--color-aai-surface", t.surface);
+		if (t.border) el.style.setProperty("--color-aai-border", t.border);
+	}
+	render(/* @__PURE__ */ jsx(MountConfigProvider, {
+		value: mountConfig,
+		children: /* @__PURE__ */ jsx(SessionProvider, {
+			value: signals,
+			children: /* @__PURE__ */ jsx(Component, {})
+		})
+	}), container);
+	const handle = {
+		session,
+		signals,
+		dispose() {
+			render(null, container);
+			signals.dispose();
+			session.disconnect();
+		},
+		[Symbol.dispose]() {
+			handle.dispose();
+		}
+	};
+	return handle;
+}
+//#endregion
+export { mount };

package/dist/session.d.ts

@@ -0,0 +1,100 @@
+import type { ClientEvent, ReadyConfig } from "@alexkroman1/aai/protocol";
+import type { VoiceIO } from "./audio.ts";
+import type { AgentState, Message, Reactive, SessionError, SessionErrorCode, SessionOptions, ToolCallInfo } from "./types.ts";
+export type { AgentState, Message, Reactive, SessionError, SessionErrorCode, SessionOptions, ToolCallInfo, };
+type BatchFn = (fn: () => void) => void;
+/**
+ * A reactive voice session that manages WebSocket communication,
+ * audio capture/playback, and agent state transitions.
+ *
+ * Uses plain JSON text frames and binary audio frames for communication
+ * and native WebSocket for the connection.
+ *
+ * Implements `Disposable` for resource cleanup via `using`.
+ *
+ * @public
+ */
+export type VoiceSession = {
+    /** Current agent state (connecting, listening, thinking, etc.). */
+    readonly state: Reactive<AgentState>;
+    /** Chat message history for the session. */
+    readonly messages: Reactive<Message[]>;
+    /** Active tool calls for the current turn. */
+    readonly toolCalls: Reactive<ToolCallInfo[]>;
+    /**
+     * Live user utterance from STT/VAD.
+     * `null` = not speaking, `""` = speech detected but no text yet,
+     * non-empty string = partial/final transcript text.
+     */
+    readonly userUtterance: Reactive<string | null>;
+    /**
+     * Streaming agent response text.
+     * `null` = not speaking, non-empty string = accumulated delta text.
+     * Cleared when the final `chat` message arrives.
+     */
+    readonly agentUtterance: Reactive<string | null>;
+    /** Current session error, or `null` if no error. */
+    readonly error: Reactive<SessionError | null>;
+    /** Disconnection info, or `null` if connected. */
+    readonly disconnected: Reactive<{
+        intentional: boolean;
+    } | null>;
+    /**
+     * Open a WebSocket connection to the server and begin audio capture.
+     *
+     * @param options - Optional connection options. `signal` is an AbortSignal that, when aborted, disconnects the session.
+     */
+    connect(options?: {
+        signal?: AbortSignal;
+    }): void;
+    /** Cancel the current agent turn and discard in-flight TTS audio. */
+    cancel(): void;
+    /** Clear messages, transcript, and error state without disconnecting. */
+    resetState(): void;
+    /** Reset the session: clear state and reconnect. */
+    reset(): void;
+    /** Close the WebSocket and release all audio resources. */
+    disconnect(): void;
+    /** Alias for `disconnect` for use with `using`. */
+    [Symbol.dispose](): void;
+};
+/**
+ * Handles server→client messages and updates reactive Preact signals
+ * accordingly (state transitions, transcripts, messages, audio playback).
+ */
+/** @internal Exported for testing only. */
+export declare class ClientHandler {
+    #private;
+    constructor(opts: {
+        state: Reactive<AgentState>;
+        messages: Reactive<Message[]>;
+        toolCalls: Reactive<ToolCallInfo[]>;
+        userUtterance: Reactive<string | null>;
+        agentUtterance: Reactive<string | null>;
+        error: Reactive<SessionError | null>;
+        voiceIO: () => VoiceIO | null;
+        batch: BatchFn;
+    });
+    /** Single entry point for all server→client session events. */
+    event(e: ClientEvent): void;
+    playAudioChunk(chunk: Uint8Array): void;
+    playAudioDone(): void;
+    /**
+     * Dispatch an incoming WebSocket message (text or binary).
+     *
+     * Returns the parsed config if the message is a `config` message,
+     * otherwise `null`.
+     */
+    handleMessage(data: string | ArrayBuffer): ReadyConfig | null;
+}
+/**
+ * Create a voice session that connects to an AAI server via WebSocket.
+ *
+ * Uses plain JSON text frames and binary audio frames for communication.
+ *
+ * @param options - Session configuration including the platform server URL.
+ * @returns A {@link VoiceSession} handle for controlling the session.
+ *
+ * @public
+ */
+export declare function createVoiceSession(options: SessionOptions): VoiceSession;