@alexkroman1/aai-ui 0.12.2 → 1.0.2

package/dist/session-CWB7vmqz.js

@@ -1,429 +0,0 @@
-import { errorMessage } from "@alexkroman1/aai/utils";
-import { ReadyConfigSchema, ServerMessageSchema } from "@alexkroman1/aai/protocol";
-//#region client-handler.ts
-/**
-* Handles server→client messages and updates reactive Preact signals
-* accordingly (state transitions, transcripts, messages, audio playback).
-*
-* @internal Exported for testing only.
-*/
-var ClientHandler = class {
-	#state;
-	#messages;
-	#toolCalls;
-	#userUtterance;
-	#agentUtterance;
-	#error;
-	#voiceIO;
-	#batch;
-	/** Incremented on each turn boundary — stale async callbacks compare against this. */
-	#generation = 0;
-	/** Accumulated chat_delta text for real-time display. */
-	#deltaAccum = "";
-	constructor(opts) {
-		this.#state = opts.state;
-		this.#messages = opts.messages;
-		this.#toolCalls = opts.toolCalls;
-		this.#userUtterance = opts.userUtterance;
-		this.#agentUtterance = opts.agentUtterance;
-		this.#error = opts.error;
-		this.#voiceIO = opts.voiceIO;
-		this.#batch = opts.batch;
-	}
-	/** Single entry point for all server→client session events. */
-	event(e) {
-		switch (e.type) {
-			case "speech_started":
-				this.#userUtterance.value = "";
-				break;
-			case "speech_stopped": break;
-			case "transcript":
-				this.#userUtterance.value = e.text;
-				break;
-			case "turn":
-				this.#generation++;
-				this.#deltaAccum = "";
-				this.#batch(() => {
-					this.#userUtterance.value = null;
-					this.#messages.value = [...this.#messages.value, {
-						role: "user",
-						content: e.text
-					}];
-					this.#state.value = "thinking";
-				});
-				break;
-			case "chat_delta":
-				this.#deltaAccum += (this.#deltaAccum ? " " : "") + e.text;
-				this.#agentUtterance.value = this.#deltaAccum;
-				break;
-			case "chat":
-				this.#deltaAccum = "";
-				this.#batch(() => {
-					this.#agentUtterance.value = null;
-					this.#messages.value = [...this.#messages.value, {
-						role: "assistant",
-						content: e.text
-					}];
-				});
-				break;
-			case "tool_call_start":
-				this.#toolCalls.value = [...this.#toolCalls.value, {
-					toolCallId: e.toolCallId,
-					toolName: e.toolName,
-					args: e.args,
-					status: "pending",
-					afterMessageIndex: this.#messages.value.length - 1
-				}];
-				break;
-			case "tool_call_done": {
-				const tcs = this.#toolCalls.value;
-				const idx = tcs.findIndex((tc) => tc.toolCallId === e.toolCallId);
-				if (idx !== -1) {
-					const updated = [...tcs];
-					const existing = updated[idx];
-					if (existing) updated[idx] = {
-						...existing,
-						status: "done",
-						result: e.result
-					};
-					this.#toolCalls.value = updated;
-				}
-				break;
-			}
-			case "tts_done":
-				this.#state.value = "listening";
-				break;
-			case "cancelled":
-				this.#generation++;
-				this.#voiceIO()?.flush();
-				this.#batch(() => {
-					this.#userUtterance.value = null;
-					this.#agentUtterance.value = null;
-					this.#state.value = "listening";
-				});
-				break;
-			case "reset":
-				this.#generation++;
-				this.#voiceIO()?.flush();
-				this.#batch(() => {
-					this.#messages.value = [];
-					this.#toolCalls.value = [];
-					this.#userUtterance.value = null;
-					this.#agentUtterance.value = null;
-					this.#error.value = null;
-					this.#state.value = "listening";
-				});
-				break;
-			case "error":
-				console.error("Agent error:", e.message);
-				this.#batch(() => {
-					this.#error.value = {
-						code: e.code,
-						message: e.message
-					};
-					this.#state.value = "error";
-				});
-				break;
-			default: break;
-		}
-	}
-	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
-	playAudioChunk(chunk) {
-		if (this.#state.value === "error") return;
-		if (this.#state.value !== "speaking") this.#state.value = "speaking";
-		if (chunk.buffer instanceof ArrayBuffer) this.#voiceIO()?.enqueue(chunk.buffer);
-	}
-	/**
-	* Signal that the server has finished sending audio for this turn.
-	* Waits for the audio queue to drain, then transitions state to `"listening"`.
-	* Uses the `#generation` counter to discard stale completions from interrupted turns.
-	*/
-	playAudioDone() {
-		const gen = this.#generation;
-		const io = this.#voiceIO();
-		if (io) io.done().then(() => {
-			if (this.#generation !== gen) return;
-			this.#state.value = "listening";
-		}).catch((err) => {
-			console.warn("Audio playback done failed:", err);
-		});
-		else this.#state.value = "listening";
-	}
-	/**
-	* Dispatch an incoming WebSocket message (text or binary).
-	*
-	* Returns the parsed config if the message is a `config` message,
-	* otherwise `null`.
-	*/
-	handleMessage(data) {
-		if (data instanceof ArrayBuffer) {
-			this.playAudioChunk(new Uint8Array(data));
-			return null;
-		}
-		let msg;
-		try {
-			const parsed = ServerMessageSchema.safeParse(JSON.parse(data));
-			if (!parsed.success) {
-				console.warn("Ignoring invalid server message:", parsed.error.message);
-				return null;
-			}
-			msg = parsed.data;
-		} catch {
-			return null;
-		}
-		if (msg.type === "config") {
-			const { type: _, sessionId, ...config } = msg;
-			const parsed = ReadyConfigSchema.safeParse(config);
-			if (!parsed.success) {
-				console.warn("Unsupported server config:", parsed.error.message);
-				return null;
-			}
-			return sessionId ? {
-				...parsed.data,
-				sessionId
-			} : parsed.data;
-		}
-		if (msg.type === "audio_done") {
-			this.playAudioDone();
-			return null;
-		}
-		this.event(msg);
-		return null;
-	}
-};
-//#endregion
-//#region session.ts
-const WS_OPEN = 1;
-/**
-* Initialize audio capture and playback after the server sends a ready config.
-*
-* 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
-* while awaiting async operations; if so, the stale VoiceIO is closed immediately
-* to prevent it from being assigned to a newer connection.
-*
-* On failure (e.g. microphone permission denied, WebSocket closed mid-setup),
-* sets the error state and transitions to `"error"`.
-*
-* @param conn - The shared mutable connection state (WebSocket, VoiceIO, generation).
-* @param msg - The `ReadyConfig` from the server containing audio sample rates.
-* @param deps.send - Send a typed client message over the WebSocket.
-* @param deps.sendBinary - Send raw binary audio data over the WebSocket.
-* @param deps.state - Reactive state signal for the agent's current state.
-* @param deps.error - Reactive signal for session errors.
-* @param deps.batch - Batching function for grouping reactive updates.
-*/
-async function initAudioCapture(conn, msg, deps) {
-	if (conn.audioSetupInFlight) return;
-	conn.audioSetupInFlight = true;
-	const gen = conn.generation;
-	try {
-		const [{ createVoiceIO }, captureWorklet, playbackWorklet] = await Promise.all([
-			import("./audio.js"),
-			import("./worklets/capture-processor.js").then((m) => m.default),
-			import("./worklets/playback-processor.js").then((m) => m.default)
-		]);
-		const io = await createVoiceIO({
-			sttSampleRate: msg.sampleRate,
-			ttsSampleRate: msg.ttsSampleRate,
-			captureWorkletSrc: captureWorklet,
-			playbackWorkletSrc: playbackWorklet,
-			onMicData: (pcm16) => {
-				try {
-					deps.sendBinary(pcm16);
-				} catch {
-					console.debug("[aai-ui] sendBinary dropped: connection closed");
-				}
-			}
-		});
-		if (conn.generation !== gen || !conn.ws || conn.ws.readyState !== WS_OPEN) {
-			io.close();
-			return;
-		}
-		conn.voiceIO = io;
-		deps.send({ type: "audio_ready" });
-		deps.state.value = "listening";
-	} catch (err) {
-		if (conn.generation !== gen || !conn.ws || conn.ws.readyState !== WS_OPEN) return;
-		deps.batch(() => {
-			deps.error.value = {
-				code: "audio",
-				message: `Microphone access failed: ${errorMessage(err)}`
-			};
-			deps.state.value = "error";
-		});
-	} finally {
-		conn.audioSetupInFlight = false;
-	}
-}
-function buildWsUrl(platformUrl, resume, sessionId) {
-	const wsUrl = new URL("websocket", platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`);
-	wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
-	if (sessionId) wsUrl.searchParams.set("sessionId", sessionId);
-	else if (resume) wsUrl.searchParams.set("resume", "1");
-	return wsUrl;
-}
-/**
-* 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
-*/
-function createVoiceSession(options) {
-	const WS = options.WebSocket ?? WebSocket;
-	const reactive = options.reactiveFactory ?? ((initial) => ({ value: initial }));
-	const batchFn = options.batch ?? ((fn) => fn());
-	const state = reactive("disconnected");
-	const messages = reactive([]);
-	const toolCalls = reactive([]);
-	const userUtterance = reactive(null);
-	const agentUtterance = reactive(null);
-	const error = reactive(null);
-	const disconnected = reactive(null);
-	const conn = {
-		ws: null,
-		voiceIO: null,
-		audioSetupInFlight: false,
-		generation: 0
-	};
-	let connectionController = null;
-	let hasConnected = false;
-	function cleanupAudio() {
-		conn.audioSetupInFlight = false;
-		conn.voiceIO?.close();
-		conn.voiceIO = null;
-	}
-	function resetState() {
-		batchFn(() => {
-			messages.value = [];
-			toolCalls.value = [];
-			userUtterance.value = null;
-			agentUtterance.value = null;
-			error.value = null;
-		});
-	}
-	function send(msg) {
-		if (conn.ws && conn.ws.readyState === WS_OPEN) conn.ws.send(JSON.stringify(msg));
-	}
-	function sendBinary(data) {
-		if (conn.ws && conn.ws.readyState === WS_OPEN) conn.ws.send(data);
-	}
-	const audioDeps = {
-		send,
-		sendBinary,
-		state,
-		error,
-		batch: batchFn
-	};
-	function connect(opts) {
-		disconnected.value = null;
-		state.value = "connecting";
-		connectionController?.abort();
-		cleanupAudio();
-		conn.ws?.close();
-		conn.ws = null;
-		conn.generation++;
-		const controller = new AbortController();
-		connectionController = controller;
-		const { signal: sig } = controller;
-		if (opts?.signal) opts.signal.addEventListener("abort", () => disconnect(), { signal: sig });
-		const resumeId = !hasConnected ? options.resumeSessionId : void 0;
-		const socket = new WS(buildWsUrl(options.platformUrl, hasConnected, resumeId).toString());
-		socket.binaryType = "arraybuffer";
-		conn.ws = socket;
-		const handler = new ClientHandler({
-			state,
-			messages,
-			toolCalls,
-			userUtterance,
-			agentUtterance,
-			error,
-			voiceIO: () => conn.voiceIO,
-			batch: batchFn
-		});
-		socket.addEventListener("open", () => {
-			state.value = "ready";
-		}, { signal: sig });
-		socket.addEventListener("message", (event) => {
-			const config = handler.handleMessage(event.data);
-			if (config) {
-				if (config.sessionId) options.onSessionId?.(config.sessionId);
-				const isReconnect = hasConnected;
-				hasConnected = true;
-				initAudioCapture(conn, config, audioDeps).catch((err) => {
-					audioDeps.batch(() => {
-						audioDeps.error.value = {
-							code: "audio",
-							message: `Audio capture failed: ${errorMessage(err)}`
-						};
-						audioDeps.state.value = "error";
-					});
-				});
-				if (isReconnect && messages.value.length > 0) send({
-					type: "history",
-					messages: messages.value.map((m) => ({
-						role: m.role,
-						content: m.content
-					}))
-				});
-			}
-		}, { signal: sig });
-		socket.addEventListener("close", () => {
-			if (sig.aborted) return;
-			controller.abort();
-			disconnected.value = { intentional: false };
-			cleanupAudio();
-			state.value = "disconnected";
-		}, { signal: sig });
-	}
-	function cancel() {
-		conn.voiceIO?.flush();
-		state.value = "listening";
-		send({ type: "cancel" });
-	}
-	function reset() {
-		conn.voiceIO?.flush();
-		if (conn.ws && conn.ws.readyState === WS_OPEN) {
-			send({ type: "reset" });
-			return;
-		}
-		resetState();
-		disconnect();
-		connect();
-	}
-	function disconnect() {
-		connectionController?.abort();
-		connectionController = null;
-		cleanupAudio();
-		conn.ws?.close();
-		conn.ws = null;
-		state.value = "disconnected";
-		disconnected.value = { intentional: true };
-	}
-	return {
-		state,
-		messages,
-		toolCalls,
-		userUtterance,
-		agentUtterance,
-		error,
-		disconnected,
-		connect,
-		cancel,
-		resetState,
-		reset,
-		disconnect,
-		[Symbol.dispose]() {
-			disconnect();
-		}
-	};
-}
-//#endregion
-export { ClientHandler as n, createVoiceSession as t };

package/dist/session.d.ts

@@ -1,69 +0,0 @@
-import type { AgentState, ChatMessage, Reactive, SessionError, ToolCallInfo, VoiceSessionOptions } from "./types.ts";
-export { ClientHandler } from "./client-handler.ts";
-export type { AgentState, ChatMessage, Reactive, SessionError, SessionErrorCode, ToolCallInfo, VoiceSessionOptions, WebSocketConstructor, } from "./types.ts";
-/**
- * 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<ChatMessage[]>;
-    /** 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;
-};
-/**
- * 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: VoiceSessionOptions): VoiceSession;

package/dist/session.js

@@ -1,2 +0,0 @@
-import { n as ClientHandler, t as createVoiceSession } from "./session-CWB7vmqz.js";
-export { ClientHandler, createVoiceSession };

package/dist/signals.d.ts

@@ -1,120 +0,0 @@
-import { type Signal } from "@preact/signals";
-import type { ComponentChildren, JSX, RefObject } from "preact";
-import type { VoiceSession } from "./session.ts";
-import type { ToolCallInfo } from "./types.ts";
-/**
- * Reactive session controls wrapping a {@link VoiceSession} with Preact signals.
- *
- * Components access reactive data via `session` (e.g. `session.state`,
- * `session.messages`). UI-only state (`started`, `running`) and actions
- * (`start`, `toggle`, `reset`) live directly on this object.
- *
- * @public
- */
-export type SessionSignals = {
-    /** The underlying voice session — all reactive data lives here. */
-    session: VoiceSession;
-    /** Whether the session has been started by the user. */
-    started: Signal<boolean>;
-    /** Whether the session is currently running (connected or connecting). */
-    running: Signal<boolean>;
-    /** Dispose the reactive effect that tracks error state. */
-    dispose(): void;
-    /** Start the session for the first time (sets `started` and `running`). */
-    start(): void;
-    /** Toggle between connected and disconnected states. */
-    toggle(): void;
-    /** Reset the session: clear state and reconnect. */
-    reset(): void;
-    /** Alias for `dispose` for use with `using`. */
-    [Symbol.dispose](): void;
-};
-/**
- * Wrap a {@link VoiceSession} in Preact signals for reactive UI binding.
- *
- * Creates higher-level controls (start, toggle, reset) on top of the raw
- * session, and automatically sets `running` to `false` when the session
- * enters an error state.
- *
- * @param session - The voice session to wrap.
- * @returns A {@link SessionSignals} object for use in Preact components.
- *
- * @public
- */
-export declare function createSessionControls(session: VoiceSession): SessionSignals;
-/**
- * Preact context provider that makes session signals available to descendant
- * components via {@link useSession}.
- *
- * @param props - Provider props. `value` is the session signals to provide. `children` are child components that may consume the context.
- * @returns A Preact VNode wrapping children in the session context.
- *
- * @public
- */
-export declare function SessionProvider({ value, children, }: {
-    value: SessionSignals;
-    children?: ComponentChildren;
-}): JSX.Element;
-/**
- * Hook to access session signals from within a {@link SessionProvider}.
- *
- * @returns The {@link SessionSignals} from the nearest provider.
- * @throws If called outside of a `SessionProvider`.
- *
- * @public
- */
-export declare function useSession(): SessionSignals;
-/**
- * Hook that fires a callback exactly once for each newly completed tool call.
- *
- * Handles deduplication internally — safe to use with `useState` setters
- * without worrying about duplicates. The `result` argument is the parsed
- * JSON result from the tool (or the raw string if parsing fails).
- *
- * Automatically resets tracking when the session is reset (toolCalls cleared).
- *
- * @example
- * ```tsx
- * // Filter by tool name with a typed result:
- * useToolResult<Recipe>("get_recipe", (result, toolCall) => {
- *   setRecipe(result);
- * });
- *
- * // Receive all tool results (untyped):
- * useToolResult((toolName, result, toolCall) => {
- *   console.log(toolName, result);
- * });
- * ```
- *
- * @public
- */
-export declare function useToolResult<R = unknown>(toolName: string, callback: (result: R, toolCall: ToolCallInfo) => void): void;
-/**
- * Hook that fires a callback exactly once for each newly completed tool call.
- *
- * @param callback - Called once per completed tool call with the tool name,
- *   parsed result, and full {@link ToolCallInfo}.
- *
- * @public
- */
-export declare function useToolResult(callback: (toolName: string, result: unknown, toolCall: ToolCallInfo) => void): void;
-/**
- * Hook that fires a callback when a new tool call starts (status: "pending").
- *
- * Use this to show a loading/skeleton UI immediately when the agent invokes
- * a tool, rather than waiting for the full result. The callback receives the
- * tool name, parsed arguments, and the full {@link ToolCallInfo}.
- *
- * @param callback - Called once per new tool call at start time.
- *
- * @public
- */
-export declare function useToolCallStart(callback: (toolName: string, args: Record<string, unknown>, toolCall: ToolCallInfo) => void): void;
-/**
- * Auto-scroll a container to the bottom when messages, tool calls,
- * or utterances change. Returns a ref to attach to a sentinel `<div>`
- * at the bottom of the scrollable area.
- *
- * @public
- */
-export declare function useAutoScroll(): RefObject<HTMLDivElement>;