@alexkroman1/aai-ui 0.12.2 → 1.0.2

package/dist/session-core.js

@@ -0,0 +1,437 @@
+import { WS_OPEN, errorMessage } from "@alexkroman1/aai";
+import { ReadyConfigSchema, ServerMessageSchema, lenientParse } from "@alexkroman1/aai/protocol";
+//#region session-core.ts
+/**
+* Framework-agnostic voice session core.
+*
+* Manages WebSocket communication, audio capture/playback, and agent state
+* transitions using a subscribe/getSnapshot pattern compatible with React's
+* `useSyncExternalStore` and other external store consumers.
+*
+* No dependency on React, Preact, or any UI framework.
+*/
+/**
+* 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 `"disconnected"`.
+*/
+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.updateState({ state: "listening" });
+	} catch (err) {
+		if (conn.generation !== gen || !conn.ws || conn.ws.readyState !== WS_OPEN) return;
+		deps.updateState({
+			state: "error",
+			error: {
+				code: "audio",
+				message: `Microphone access failed: ${errorMessage(err)}`
+			},
+			running: false
+		});
+	} 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 framework-agnostic voice session core that connects to an AAI
+* server via WebSocket.
+*
+* Uses a subscribe/getSnapshot pattern for state management, compatible with
+* React's `useSyncExternalStore` and other external store integrations.
+*
+* @param options - Session configuration including the platform server URL.
+* @returns A {@link SessionCore} handle for controlling the session.
+*
+* @public
+*/
+function createSessionCore(options) {
+	const WS = options.WebSocket ?? WebSocket;
+	let currentSnapshot = {
+		state: "disconnected",
+		messages: [],
+		toolCalls: [],
+		userTranscript: null,
+		agentTranscript: null,
+		error: null,
+		started: false,
+		running: false
+	};
+	const subscribers = /* @__PURE__ */ new Set();
+	function notify() {
+		for (const sub of subscribers) sub();
+	}
+	function updateState(partial) {
+		currentSnapshot = {
+			...currentSnapshot,
+			...partial
+		};
+		notify();
+	}
+	function getSnapshot() {
+		return currentSnapshot;
+	}
+	function subscribe(callback) {
+		subscribers.add(callback);
+		return () => {
+			subscribers.delete(callback);
+		};
+	}
+	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() {
+		updateState({
+			messages: [],
+			toolCalls: [],
+			userTranscript: null,
+			agentTranscript: null,
+			error: 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,
+		updateState
+	};
+	/** Incremented on each turn boundary -- stale async callbacks compare against this. */
+	let handlerGeneration = 0;
+	function handleUserTranscriptEvent(text) {
+		handlerGeneration++;
+		updateState({
+			userTranscript: null,
+			messages: [...currentSnapshot.messages, {
+				role: "user",
+				content: text
+			}],
+			state: "thinking"
+		});
+	}
+	function handleAgentTranscriptEvent(text) {
+		updateState({
+			agentTranscript: null,
+			messages: [...currentSnapshot.messages, {
+				role: "assistant",
+				content: text
+			}]
+		});
+	}
+	/** Single entry point for all server->client session events. */
+	function handleEvent(e) {
+		if (currentSnapshot.state === "error" && e.type !== "error") updateState({
+			state: "disconnected",
+			error: null
+		});
+		switch (e.type) {
+			case "speech_started":
+				updateState({ userTranscript: "" });
+				break;
+			case "speech_stopped": break;
+			case "user_transcript":
+				handleUserTranscriptEvent(e.text);
+				break;
+			case "agent_transcript":
+				handleAgentTranscriptEvent(e.text);
+				break;
+			case "tool_call":
+				updateState({ toolCalls: [...currentSnapshot.toolCalls, {
+					callId: e.toolCallId,
+					name: e.toolName,
+					args: e.args,
+					status: "pending",
+					afterMessageIndex: currentSnapshot.messages.length - 1
+				}] });
+				break;
+			case "tool_call_done": {
+				const tcs = currentSnapshot.toolCalls;
+				const idx = tcs.findIndex((tc) => tc.callId === e.toolCallId);
+				if (idx !== -1) {
+					const updated = [...tcs];
+					const existing = updated[idx];
+					if (existing) updated[idx] = {
+						...existing,
+						status: "done",
+						result: e.result
+					};
+					updateState({ toolCalls: updated });
+				}
+				break;
+			}
+			case "reply_done":
+				updateState({ state: "listening" });
+				break;
+			case "cancelled":
+				handlerGeneration++;
+				conn.voiceIO?.flush();
+				updateState({
+					userTranscript: null,
+					agentTranscript: null,
+					state: "listening"
+				});
+				break;
+			case "reset":
+				handlerGeneration++;
+				conn.voiceIO?.flush();
+				updateState({
+					messages: [],
+					toolCalls: [],
+					userTranscript: null,
+					agentTranscript: null,
+					error: null,
+					state: "listening"
+				});
+				break;
+			case "error":
+				console.error("Agent error:", e.message);
+				updateState({
+					state: "error",
+					error: {
+						code: e.code,
+						message: e.message
+					},
+					running: false
+				});
+				break;
+			default: break;
+		}
+	}
+	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
+	function playAudioChunk(chunk) {
+		if (currentSnapshot.state === "disconnected" && currentSnapshot.error !== null) return;
+		if (currentSnapshot.state !== "speaking") updateState({ state: "speaking" });
+		if (chunk.buffer instanceof ArrayBuffer) conn.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 `handlerGeneration` counter to discard stale completions from interrupted turns.
+	*/
+	function playAudioDone() {
+		const gen = handlerGeneration;
+		const io = conn.voiceIO;
+		if (io) io.done().then(() => {
+			if (handlerGeneration !== gen) return;
+			updateState({ state: "listening" });
+		}).catch((err) => {
+			console.warn("Audio playback done failed:", err);
+		});
+		else updateState({ state: "listening" });
+	}
+	/** Parse a JSON text frame into a ServerMessage, or null if invalid/unknown. */
+	function parseTextFrame(data) {
+		try {
+			const result = lenientParse(ServerMessageSchema, JSON.parse(data));
+			if (!result.ok) {
+				if (result.malformed) console.warn("Ignoring invalid server message:", result.error);
+				return null;
+			}
+			return result.data;
+		} catch {
+			return null;
+		}
+	}
+	/** Try to extract a ReadyConfig from a config message, or null. */
+	function parseConfig(msg) {
+		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;
+	}
+	/**
+	* Dispatch an incoming WebSocket message (text or binary).
+	*
+	* Returns the parsed config if the message is a `config` message,
+	* otherwise `null`.
+	*/
+	function handleMessage(data) {
+		if (data instanceof ArrayBuffer) {
+			playAudioChunk(new Uint8Array(data));
+			return null;
+		}
+		const msg = parseTextFrame(data);
+		if (!msg) return null;
+		if (msg.type === "config") return parseConfig(msg);
+		if (msg.type === "audio_done") {
+			playAudioDone();
+			return null;
+		}
+		handleEvent(msg);
+		return null;
+	}
+	function connect(opts) {
+		updateState({
+			state: "connecting",
+			error: null
+		});
+		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;
+		socket.addEventListener("open", () => {
+			updateState({ state: "ready" });
+		}, { signal: sig });
+		socket.addEventListener("message", (event) => {
+			const config = handleMessage(event.data);
+			if (config) {
+				if (config.sessionId) options.onSessionId?.(config.sessionId);
+				const isReconnect = hasConnected;
+				hasConnected = true;
+				initAudioCapture(conn, config, audioDeps).catch((err) => {
+					audioDeps.updateState({
+						state: "error",
+						error: {
+							code: "audio",
+							message: `Audio capture failed: ${errorMessage(err)}`
+						},
+						running: false
+					});
+				});
+				if (isReconnect && currentSnapshot.messages.length > 0) send({
+					type: "history",
+					messages: currentSnapshot.messages.map((m) => ({
+						role: m.role,
+						content: m.content
+					}))
+				});
+			}
+		}, { signal: sig });
+		socket.addEventListener("close", () => {
+			if (sig.aborted) return;
+			controller.abort();
+			cleanupAudio();
+			updateState({
+				state: "disconnected",
+				running: false
+			});
+		}, { signal: sig });
+	}
+	function cancel() {
+		conn.voiceIO?.flush();
+		updateState({ state: "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;
+		updateState({
+			state: "disconnected",
+			running: false
+		});
+	}
+	function start() {
+		updateState({
+			started: true,
+			running: true
+		});
+		connect();
+	}
+	function toggle() {
+		if (currentSnapshot.running) disconnect();
+		else {
+			updateState({ running: true });
+			connect();
+		}
+	}
+	return {
+		getSnapshot,
+		subscribe,
+		connect,
+		cancel,
+		resetState,
+		reset,
+		disconnect,
+		start,
+		toggle,
+		[Symbol.dispose]() {
+			disconnect();
+		}
+	};
+}
+//#endregion
+export { createSessionCore };

package/dist/tool-call-block-CCuChsFm.js

@@ -0,0 +1,131 @@
+import { useTheme } from "./context.js";
+import clsx from "clsx";
+import { createContext, useContext, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region components/tool-config-context.ts
+/**
+* Context for tool display configuration.
+* Provided by `client` or manually via `ToolConfigContext.Provider`.
+*
+* @public
+*/
+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) {
+	try {
+		return JSON.stringify(JSON.parse(result), null, 2);
+	} catch {
+		return result;
+	}
+}
+/**
+* Renders a tool invocation with an optional icon/emoji, title, subtitle, and a
+* collapsible result viewer.
+*
+* Tool display is configured via `ToolConfigContext`. If no config is found
+* for a tool name, the raw tool name is shown as the title.
+*
+* While the tool call is pending a shimmer animation is shown. Once
+* complete, clicking the block expands the formatted JSON result.
+*
+* @example
+* ```tsx
+* <ToolCallBlock toolCall={toolCall} />
+* ```
+*
+* @param toolCall - The tool call to render (see {@link ToolCallInfo}).
+* @param className - Additional CSS class names.
+*
+* @public
+*/
+function ToolCallBlock({ toolCall, className }) {
+	const [isOpen, setIsOpen] = useState(false);
+	const theme = useTheme();
+	const config = useToolConfig()[toolCall.name];
+	const isPending = toolCall.status === "pending";
+	const title = config?.label || toolCall.name;
+	const icon = config?.icon;
+	const canExpand = !isPending && Boolean(toolCall.result);
+	const formatted = useMemo(() => toolCall.result ? formatResult(toolCall.result) : "", [toolCall.result]);
+	const subtitle = useMemo(() => {
+		const args = toolCall.args;
+		if (toolCall.name === "run_code" && args.code) {
+			const firstLine = String(args.code).split("\n")[0] ?? "";
+			return firstLine.length > 80 ? `${firstLine.slice(0, 80)}...` : firstLine;
+		}
+		for (const key of [
+			"query",
+			"url",
+			"question"
+		]) if (args[key]) return String(args[key]);
+		const summary = JSON.stringify(args);
+		return summary.length > 80 ? `${summary.slice(0, 80)}...` : summary;
+	}, [toolCall.name, toolCall.args]);
+	return /* @__PURE__ */ jsxs("div", {
+		className: clsx("flex flex-col", className),
+		children: [/* @__PURE__ */ jsxs("button", {
+			type: "button",
+			"aria-expanded": canExpand ? isOpen : void 0,
+			disabled: isPending,
+			className: clsx("flex items-center gap-2 px-3 py-2 rounded-aai border select-none text-left w-full", canExpand && "cursor-pointer"),
+			style: {
+				borderColor: theme.border,
+				background: "rgba(255,255,255,0.031)"
+			},
+			onClick: () => {
+				if (canExpand) setIsOpen(!isOpen);
+			},
+			children: [
+				icon && /* @__PURE__ */ jsx("span", {
+					className: "w-4 h-4 shrink-0 text-center leading-4",
+					children: icon
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: clsx("text-sm font-medium", isPending && "tool-shimmer"),
+					style: { color: theme.text },
+					children: title
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "text-sm truncate flex-1 min-w-0",
+					style: { color: "rgba(255,255,255,0.422)" },
+					children: subtitle
+				}),
+				canExpand && /* @__PURE__ */ jsx("span", {
+					className: "text-xs shrink-0",
+					style: { color: "rgba(255,255,255,0.422)" },
+					children: isOpen ? "▾" : "▸"
+				})
+			]
+		}), isOpen && /* @__PURE__ */ jsxs("div", {
+			className: "border-x border-b rounded-b-aai max-h-64 overflow-auto",
+			style: {
+				borderColor: theme.border,
+				background: theme.surface
+			},
+			children: [toolCall.name === "run_code" && Boolean(toolCall.args.code) && /* @__PURE__ */ jsx("pre", {
+				className: "text-xs p-2 whitespace-pre-wrap border-b font-mono",
+				style: {
+					color: theme.text,
+					borderColor: theme.border
+				},
+				children: String(toolCall.args.code)
+			}), formatted && /* @__PURE__ */ jsx("pre", {
+				className: "text-xs p-2 whitespace-pre-wrap",
+				style: { color: "rgba(255,255,255,0.422)" },
+				children: formatted
+			})]
+		})]
+	});
+}
+//#endregion
+export { ToolConfigContext as n, ToolCallBlock as t };

package/dist/types.d.ts

@@ -24,8 +24,8 @@ export type ChatMessage = {
  * @public
  */
 export type ToolCallInfo = {
-    toolCallId: string;
-    toolName: string;
+    callId: string;
+    name: string;
     args: Record<string, unknown>;
     status: "pending" | "done";
     result?: string | undefined;
@@ -44,14 +44,6 @@ export type SessionError = {
     /** A human-readable description of the error. */
     readonly message: string;
 };
-/**
- * Minimal reactive container. Compatible with `@preact/signals` `Signal<T>`.
- *
- * @public
- */
-export type Reactive<T> = {
-    value: T;
-};
 /**
  * Options for creating a voice session.
  *
@@ -60,18 +52,6 @@ export type Reactive<T> = {
 export type VoiceSessionOptions = {
     /** Base URL of the AAI platform server. */
     platformUrl: string;
-    /**
-     * Factory for creating reactive state containers.
-     * Defaults to a plain mutable wrapper. Pass `signal` from
-     * `@preact/signals` for automatic Preact component re-rendering.
-     */
-    reactiveFactory?: <T>(initial: T) => Reactive<T>;
-    /**
-     * Function to batch multiple reactive updates.
-     * Defaults to calling the function directly. Pass `batch` from
-     * `@preact/signals` for optimized batched updates.
-     */
-    batch?: (fn: () => void) => void;
     /**
      * Called when the server sends a session ID in the config message.
      * Use this to store the ID (e.g. in localStorage) for reconnection
@@ -99,3 +79,20 @@ export type WebSocketConstructor = {
     new (url: string | URL, protocols?: string | string[]): WebSocket;
     readonly OPEN: number;
 };
+/**
+ * Theme color overrides for the AAI UI components.
+ *
+ * @public
+ */
+export type ClientTheme = {
+    /** 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;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "0.12.2",
+  "version": "1.0.2",
   "type": "module",
   "files": [
     "dist",
@@ -13,19 +13,16 @@
       "import": "./dist/index.js"
     },
     "./styles.css": "./styles.css",
-    "./session": {
-      "@dev/source": "./session.ts",
-      "types": "./dist/session.d.ts",
-      "import": "./dist/session.js"
-    }
+    "./package.json": "./package.json",
+    "./default-client/*": "./dist/default-client/*"
   },
   "dependencies": {
     "clsx": "^2.1.1",
-    "@alexkroman1/aai": "0.12.2"
+    "@alexkroman1/aai": "1.0.2"
   },
   "peerDependencies": {
-    "@preact/signals": "^2.8.2",
-    "preact": "^10.29.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tailwindcss": "^4.2.1"
   },
   "peerDependenciesMeta": {
@@ -34,15 +31,22 @@
     }
   },
   "devDependencies": {
-    "@preact/signals": "^2.8.2",
-    "@testing-library/preact": "^3.2.4",
-    "jsdom": "^29.0.1",
-    "preact": "^10.29.0",
-    "tsdown": "^0.21.5",
-    "vitest": "^4.1.1"
+    "@tailwindcss/vite": "^4.2.1",
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.0.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsdown": "^0.21.7",
+    "tsx": "^4.21.0",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.3"
   },
   "engines": {
-    "node": ">=22.6"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",
@@ -50,10 +54,12 @@
     "directory": "packages/aai-ui"
   },
   "scripts": {
-    "build": "tsdown && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "build": "tsdown && tsc -p tsconfig.build.json && tsx build-default-client.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "check:publint": "publint",
-    "check:attw": "attw --pack --profile esm-only --entrypoints . ./session"
+    "check:attw": "attw --pack --profile esm-only --entrypoints ."
   }
 }