@alexkroman1/aai-ui 6.11.0 → 7.0.0

package/dist/default-client/index.html

@@ -6,9 +6,9 @@
     <title>aai</title>
     <link rel="icon" href="./favicon.ico" />
     <style>html, body { background: #FBF8F2; margin: 0; }</style>
-    <script type="module" crossorigin src="./assets/index-DXODx_9r.js"></script>
+    <script type="module" crossorigin src="./assets/index-fEkrcZgo.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/client-audio-constants-Ck0IJO4c.js">
-    <link rel="stylesheet" crossorigin href="./assets/index-DTLrhtTF.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-S5fkKi6B.css">
   </head>
   <body>
     <main id="app"></main>

package/dist/define-client.d.ts

@@ -4,86 +4,90 @@ import { type ToolDisplayConfig } from "./components/tool-config-context.ts";
 import type { SessionCore } from "./session-core-types.ts";
 import type { ClientTheme, VoiceSessionOptions } from "./types.ts";
 /**
- * Options shared by both {@link client} tiers (config-only and custom
- * component).
+ * Configuration passed to {@link client}.
  *
  * The session-forwarded fields are picked from {@link VoiceSessionOptions}
  * (one source of truth for types and docs) rather than re-declared — a
- * re-declared copy is exactly how doc comments drift.
+ * re-declared copy is exactly how doc comments drift. It is NOT the session's
+ * own options type: that is {@link VoiceSessionOptions}, which
+ * `createSessionCore` takes and which three of these fields come from.
+ *
+ * @remarks
+ * **One flat type, not a union of tiers.** `component` is what decides which
+ * shell renders — absent, the default one (StartScreen + ChatView, optional
+ * sidebar); present, the caller's own component inside the same providers —
+ * and that decision is made at runtime, where every field can be honoured. It
+ * used to be a union whose two arms banned each other's fields with `?: never`,
+ * and the failure that shape produces is recorded twice in this file's history:
+ * `client({ name, component })` and `client({ component, tools })` were both
+ * the natural thing to write, both were refused with *"Type 'string' is not
+ * assignable to type 'undefined'"*, and both cost a build round each time
+ * before the ban was lifted. What was left banned was `sidebar` beside a
+ * `component`, which invited the identical failure for a combination
+ * {@link client} can simply render.
  *
  * @public
  */
-export type BaseOptions = Pick<VoiceSessionOptions, "onSessionId" | "resumeSessionId" | "WebSocket"> & {
+export type ClientConfig = Pick<VoiceSessionOptions, "onSessionId" | "resumeSessionId" | "WebSocket"> & {
     /** 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;
     /** Theme color overrides. */
     theme?: ClientTheme;
-};
-/**
- * Tier 1: config-only options — no `component`. Renders the default shell
- * (StartScreen + ChatView).
- *
- * @public
- */
-export type ConfigTier = BaseOptions & {
-    component?: never;
-    /** Agent name shown in the header and start screen. */
+    /**
+     * Full custom component to render instead of the default shell.
+     *
+     * It is rendered inside the same providers the default shell gets, so every
+     * session hook, `useTheme` and the tool display config work in it unchanged.
+     */
+    component?: ComponentType;
+    /**
+     * Agent name shown in the header and start screen — and, with a `component`,
+     * the page title, there being no shell header to put it in. Left out, the
+     * default shell asks the agent for its own declared name.
+     */
     name?: string;
-    /** Optional sidebar component rendered alongside the chat view. */
+    /**
+     * Optional sidebar component rendered alongside the main pane.
+     *
+     * Beside a `component` it is the custom component that becomes the main pane,
+     * in the same {@link SidebarLayout} the default shell uses.
+     */
     sidebar?: ComponentType;
     /** CSS width of the sidebar. Defaults to `"18rem"`. */
     sidebarWidth?: string;
-    /** Tool display config: icon and label overrides keyed by tool name. */
-    tools?: ToolDisplayConfig;
-};
-/**
- * Tier 2: custom component — renders the provided `component` inside the
- * providers instead of the default shell.
- *
- * @public
- */
-export type ComponentTier = BaseOptions & {
-    /** Full custom component to render instead of the default shell. */
-    component: ComponentType;
     /**
-     * Agent name. With a custom component there is no shell header to put it
-     * in, so it becomes the page title.
+     * Which side the sidebar sits on. Defaults to `"left"`.
      *
-     * Allowed here rather than `never` because `client({ name, component })` is
-     * the natural thing to write and two different models wrote it. As `never`
-     * it failed with *"Type 'string' is not assignable to type 'undefined'"*,
-     * which explains nothing, and cost a build round each time. There is a real
-     * use for the value — a custom-UI page otherwise inherits whatever title
-     * the HTML shell shipped with — so it is honoured instead of banned.
+     * Routed through the same {@link SidebarLayout} whether the main pane is the
+     * default shell or a `component`, for the reason `sidebar` itself is: the two
+     * branches build the same layout and a field honoured by only one of them is
+     * the shape this config used to have.
      */
-    name?: string;
-    sidebar?: never;
-    sidebarWidth?: never;
+    sidebarPosition?: "left" | "right";
     /**
-     * Tool display config: icon and label overrides keyed by tool name.
+     * Element rendered in place of the AAI logo — on the start card, and in the
+     * shell header once the session begins.
      *
-     * Allowed here for the same reason as `name` above, and it was found the
-     * same way: four starters across an eval run wrote
-     * `client({ component, tools })` and lost a build round each time to
-     * *"Type '{ … }' is not assignable to type 'undefined'"*.
+     * Both, because they are one mark: an agent whose start screen shows a slice
+     * of pizza and whose header shows our logo reads as two products.
+     */
+    icon?: ReactNode;
+    /** A line under the title on the start card. */
+    subtitle?: string;
+    /** Label of the start CTA. Defaults to `"Start Conversation"`. */
+    buttonText?: string;
+    /**
+     * Tool display config: icon and label overrides keyed by tool name.
      *
-     * Unlike `sidebar`/`sidebarWidth`, this is not a property of the default
-     * shell. `client()` below wraps BOTH tiers in `ToolConfigContext.Provider`
-     * from `config.tools ?? {}`, and the consumer is `ToolCallBlock` — which a
-     * custom component renders as soon as it uses `MessageList` or `ChatView`,
-     * the usual way to build one. So the value was always honoured at runtime;
-     * only the type refused it.
+     * Honoured with a custom `component` too: {@link client} installs it into
+     * `ToolConfigContext`, and the consumer is `ToolCallBlock` — which a custom
+     * component renders as soon as it uses `MessageList` or `ChatView`, the usual
+     * way to build one.
      */
     tools?: ToolDisplayConfig;
 };
-/**
- * Configuration passed to {@link client}.
- *
- * @public
- */
-export type ClientConfig = ConfigTier | ComponentTier;
 /**
  * Handle returned by {@link client} for cleanup.
  *
@@ -141,18 +145,19 @@ export declare function mountRoot(container: HTMLElement, node: ReactNode, onDis
 /**
  * Define and mount a client UI for a voice agent.
  *
- * **Tier 1 (config-only):** Pass options without `component` to get the
- * default shell (StartScreen + ChatView, optional sidebar).
+ * **Config only:** leave `component` out and the default shell renders
+ * (StartScreen + ChatView, optional sidebar).
  *
- * **Tier 2 (custom component):** Pass `component` to render a fully custom
- * root component inside the providers. In this tier a provided `name` also
- * sets `document.title` (there is no shell header to show it in).
+ * **A custom component:** pass `component` and it is rendered inside the same
+ * providers instead of the default shell — beside a `sidebar` if one is given,
+ * in the same {@link SidebarLayout}. A provided `name` then also sets
+ * `document.title`, there being no shell header to show it in.
  *
  * Mounts into `target` — a CSS selector or DOM element, defaulting to
  * `"#app"` — and throws `Element not found: <target>` when the selector
  * matches nothing.
  *
- * @example Tier 1
+ * @example The default shell
  * ```tsx
  * import { client } from "@alexkroman1/aai-ui";
  *
@@ -168,7 +173,7 @@ export declare function mountRoot(container: HTMLElement, node: ReactNode, onDis
  * });
  * ```
  *
- * @example Tier 2
+ * @example A custom component
  * ```tsx
  * import { client, useSession } from "@alexkroman1/aai-ui";
  *

package/dist/define-client.js

@@ -1,10 +1,11 @@
-import { r as fetchClientConfig, t as createSessionCore } from "./session-core-CAfYmUbg.js";
+import { n as fetchClientConfig } from "./client-config-B4nznRvH.js";
 import { SessionProvider, ThemeProvider } from "./context.js";
-import { t as ChatView } from "./chat-view-ByQFf94G.js";
+import { t as ChatView } from "./chat-view-BKsFfFZJ.js";
 import { n as setPageTitle, t as pageBaseUrl } from "./_utils-B6498_bm.js";
-import { n as ToolConfigContext } from "./tool-call-block-D6pTEPrT.js";
+import { t as ToolConfigContext } from "./tool-config-context-DzAofqi_.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
+import { t as createSessionCore } from "./session-core-C2JtLArh.js";
 import { jsx } from "react/jsx-runtime";
 import { createElement, useEffect, useState } from "react";
 import { flushSync } from "react-dom";
@@ -62,13 +63,20 @@ function mountRoot(container, node, onDispose) {
 * Default shell rendered in config tier.
 * Wraps StartScreen → (SidebarLayout →) ChatView.
 */
-function DefaultShell({ name, Sidebar, sidebarWidth }) {
-	const chat = /* @__PURE__ */ jsx(ChatView, { title: name });
+function DefaultShell({ name, icon, subtitle, buttonText, Sidebar, ...layout }) {
+	const chat = /* @__PURE__ */ jsx(ChatView, {
+		title: name,
+		icon
+	});
 	return /* @__PURE__ */ jsx(StartScreen, {
 		title: name,
+		icon,
+		subtitle,
+		buttonText,
 		children: Sidebar ? /* @__PURE__ */ jsx(SidebarLayout, {
 			sidebar: /* @__PURE__ */ jsx(Sidebar, {}),
-			sidebarWidth,
+			sidebarWidth: layout.sidebarWidth,
+			sidebarPosition: layout.sidebarPosition,
 			children: chat
 		}) : chat
 	});
@@ -90,7 +98,8 @@ function DefaultShell({ name, Sidebar, sidebarWidth }) {
 * reconnect land on a REPLACEMENT sandbox, so it may not be served from
 * anything this render already has.
 */
-function DefaultRoot({ platformUrl, name, Sidebar, sidebarWidth }) {
+function DefaultRoot({ platformUrl, ...display }) {
+	const { name } = display;
 	const [resolved, setResolved] = useState(null);
 	const needsLookup = name === void 0;
 	useEffect(() => {
@@ -104,26 +113,56 @@ function DefaultRoot({ platformUrl, name, Sidebar, sidebarWidth }) {
 		};
 	}, [platformUrl, needsLookup]);
 	return /* @__PURE__ */ jsx(DefaultShell, {
-		name: name ?? resolved?.name,
+		...display,
+		name: name ?? resolved?.name
+	});
+}
+/**
+* The tree under the providers: the caller's component, or the default shell.
+*
+* A custom component owns the whole page, so there is no header to hang a
+* `sidebar` off — but the layout the default shell uses is right here, and
+* `client({ component, sidebar })` names one pane and one aside, which is
+* exactly what it renders. Honouring the combination rather than ignoring it is
+* the same call this file already made for `name` and `tools`.
+*/
+function rootFor(config, platformUrl) {
+	const Custom = config.component;
+	const Sidebar = config.sidebar;
+	if (!Custom) return /* @__PURE__ */ jsx(DefaultRoot, {
+		platformUrl,
+		name: config.name,
+		icon: config.icon,
+		subtitle: config.subtitle,
+		buttonText: config.buttonText,
 		Sidebar,
-		sidebarWidth
+		sidebarWidth: config.sidebarWidth,
+		sidebarPosition: config.sidebarPosition
+	});
+	if (!Sidebar) return /* @__PURE__ */ jsx(Custom, {});
+	return /* @__PURE__ */ jsx(SidebarLayout, {
+		sidebar: /* @__PURE__ */ jsx(Sidebar, {}),
+		sidebarWidth: config.sidebarWidth,
+		sidebarPosition: config.sidebarPosition,
+		children: /* @__PURE__ */ jsx(Custom, {})
 	});
 }
 /**
 * Define and mount a client UI for a voice agent.
 *
-* **Tier 1 (config-only):** Pass options without `component` to get the
-* default shell (StartScreen + ChatView, optional sidebar).
+* **Config only:** leave `component` out and the default shell renders
+* (StartScreen + ChatView, optional sidebar).
 *
-* **Tier 2 (custom component):** Pass `component` to render a fully custom
-* root component inside the providers. In this tier a provided `name` also
-* sets `document.title` (there is no shell header to show it in).
+* **A custom component:** pass `component` and it is rendered inside the same
+* providers instead of the default shell — beside a `sidebar` if one is given,
+* in the same {@link SidebarLayout}. A provided `name` then also sets
+* `document.title`, there being no shell header to show it in.
 *
 * Mounts into `target` — a CSS selector or DOM element, defaulting to
 * `"#app"` — and throws `Element not found: <target>` when the selector
 * matches nothing.
 *
-* @example Tier 1
+* @example The default shell
 * ```tsx
 * import { client } from "@alexkroman1/aai-ui";
 *
@@ -139,7 +178,7 @@ function DefaultRoot({ platformUrl, name, Sidebar, sidebarWidth }) {
 * });
 * ```
 *
-* @example Tier 2
+* @example A custom component
 * ```tsx
 * import { client, useSession } from "@alexkroman1/aai-ui";
 *
@@ -166,12 +205,7 @@ function client(config) {
 		WebSocket: config.WebSocket
 	});
 	setPageTitle(config.name);
-	const rootNode = config.component ? createElement(config.component) : createElement(DefaultRoot, {
-		platformUrl,
-		name: config.name,
-		Sidebar: config.sidebar,
-		sidebarWidth: config.sidebarWidth
-	});
+	const rootNode = rootFor(config, platformUrl);
 	const toolConfig = config.tools ?? {};
 	return {
 		session,

package/dist/hooks.d.ts

@@ -1,18 +1,65 @@
 import type { DefaultToolResult, StateProjection } from "@alexkroman1/aai";
 import type { ToolCallInfo } from "./types.ts";
 /**
- * Fire a callback when a tool call settles, with the tool's JSON result.
+ * Fire a callback when ONE named tool settles, with its parsed JSON result.
  *
  * For new code prefer explicit events — `ctx.send(event, data)` in the tool
  * paired with {@link useEvent} here — over listening to tool results.
  *
+ * A component that mounts late still receives the results of calls that
+ * already completed, because a result is a value the UI is driven from rather
+ * than a moment. Each call fires exactly once per hook instance.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolResult } from "@alexkroman1/aai-ui";
+ *
+ * type Quote = { symbol: string; price: number };
+ *
+ * function QuoteCard() {
+ *   const [quote, setQuote] = useState<Quote>();
+ *   useToolResult<Quote>("get_quote", (result) => setQuote(result));
+ *   return quote ? <p>{quote.symbol}: {quote.price}</p> : null;
+ * }
+ * ```
+ *
  * @typeParam R - The result shape. Defaults to {@link DefaultToolResult}
  *   (`any`) so the ordinary untyped spelling compiles; pass the shape —
  *   `useToolResult<Quote>(…)` — for real checking.
+ * @param toolName - Only calls of this tool fire the callback.
+ * @param callback - Called with the parsed result and the call itself.
  *
  * @public
  */
 export declare function useToolResult<R = DefaultToolResult>(toolName: string, callback: (result: R, toolCall: ToolCallInfo) => void): void;
+/**
+ * Fire a callback when ANY tool call settles — the tool's name is the
+ * callback's first argument.
+ *
+ * The unfiltered form, for a chrome rendering a log of everything the agent
+ * did rather than reacting to one tool.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolResult } from "@alexkroman1/aai-ui";
+ *
+ * function ToolLog() {
+ *   const [lines, setLines] = useState<string[]>([]);
+ *   useToolResult((name, result) => {
+ *     setLines((prev) => [...prev, `${name}: ${JSON.stringify(result)}`]);
+ *   });
+ *   return <pre>{lines.join("\n")}</pre>;
+ * }
+ * ```
+ *
+ * @typeParam R - The result shape. Defaults to {@link DefaultToolResult}.
+ * @param callback - Called with the tool's name, the parsed result, and the
+ * call itself.
+ *
+ * @public
+ */
 export declare function useToolResult<R = DefaultToolResult>(callback: (name: string, result: R, toolCall: ToolCallInfo) => void): void;
 /**
  * The agent's projected session state, or `null` before the first push.
@@ -133,10 +180,48 @@ export declare function useAgentState<S = DefaultToolResult>(fallback: S): S;
  */
 export declare function useEvent<T = unknown>(event: string, callback: (data: T) => void): void;
 /**
- * Fire a callback when a tool call starts (before its result arrives).
- * Optionally filter by tool name.
+ * Fire a callback when ONE named tool starts, before its result arrives.
+ *
+ * A start is a MOMENT rather than a value, so unlike {@link useToolResult}
+ * this never replays: a component that mounts mid-session learns nothing about
+ * calls that started before it.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolCallStart } from "@alexkroman1/aai-ui";
+ *
+ * function Searching() {
+ *   const [busy, setBusy] = useState(false);
+ *   useToolCallStart("search_catalog", () => setBusy(true));
+ *   return busy ? <p>Searching the catalog…</p> : null;
+ * }
+ * ```
+ *
+ * @param toolName - Only calls of this tool fire the callback.
+ * @param callback - Called with the pending call.
  *
  * @public
  */
 export declare function useToolCallStart(toolName: string, callback: (toolCall: ToolCallInfo) => void): void;
+/**
+ * Fire a callback when ANY tool call starts — read the tool's name off the
+ * call itself (`toolCall.name`).
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolCallStart } from "@alexkroman1/aai-ui";
+ *
+ * function Activity() {
+ *   const [now, setNow] = useState<string>();
+ *   useToolCallStart((toolCall) => setNow(toolCall.name));
+ *   return now ? <p>Running {now}…</p> : null;
+ * }
+ * ```
+ *
+ * @param callback - Called with the pending call.
+ *
+ * @public
+ */
 export declare function useToolCallStart(callback: (toolCall: ToolCallInfo) => void): void;

package/dist/index.d.ts

@@ -1,34 +1,35 @@
-export { buildAgentUrl, type ClientConfigResponse, fetchClientConfig, loadClientConfig, } from "./client-config.ts";
+export { type ClientConfigResponse, fetchClientConfig, } from "./client-config.ts";
 export { AutoScroll } from "./components/auto-scroll.tsx";
 export { Button, type ButtonSize, type ButtonVariant } from "./components/button.tsx";
 export { ChatView } from "./components/chat-view.tsx";
-export { Controls } from "./components/controls.tsx";
+export { ConsoleShell, type ConsoleShellProps } from "./components/console-shell.tsx";
+export { Controls, type ControlsProps } from "./components/controls.tsx";
 export { CheckboxField, Field, type FieldShell, FileField, type FileRead, type FileValue, Form, type FormProps, type FormValues, NumberField, SelectField, SubmitButton, TextAreaField, TextField, } from "./components/form.tsx";
-export { Markdown, type MarkdownVariant } from "./components/markdown.tsx";
-export { MessageList } from "./components/message-list.tsx";
+export { Markdown, type MarkdownProps, type MarkdownVariant } from "./components/markdown.tsx";
+export { MessageList, type MessageListProps } from "./components/message-list.tsx";
 export { SidebarLayout } from "./components/sidebar-layout.tsx";
 export { StartScreen } from "./components/start-screen.tsx";
 export { ToolCallRow, type ToolCallRowProps, type ToolCallRowVariant, } from "./components/tool-call-row.tsx";
 export type { ToolDisplayConfig } from "./components/tool-config-context.ts";
-export { ToolConfigContext } from "./components/tool-config-context.ts";
 export { UploadProgressBar } from "./components/upload-progress.tsx";
-export { ApiUrlChip, SessionUrlChips, UiUrlChip } from "./components/url-chips.tsx";
 export { WorkflowFields } from "./components/workflow-fields.tsx";
 export { WorkflowProgress } from "./components/workflow-progress.tsx";
 export type { Session } from "./context.ts";
-export { SessionProvider, ThemeProvider, useSession, useSessionSelector, useTheme, } from "./context.ts";
-export type { BaseOptions, ClientConfig, ClientHandle, ComponentTier, ConfigTier, } from "./define-client.tsx";
+export { useSession, useSessionSelector, useTheme } from "./context.ts";
+export type { ClientConfig, ClientHandle } from "./define-client.tsx";
 export { client } from "./define-client.tsx";
 export { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.ts";
 export { type PageConfig, type PageHandle, page } from "./page.tsx";
 export { createSessionCore } from "./session-core.ts";
-export type { AgentCustomEvent, SessionCore, SessionCoreOptions, SessionSnapshot, } from "./session-core-types.ts";
+export type { AgentCustomEvent, SessionCore, SessionSnapshot, } from "./session-core-types.ts";
 export type { AgentState, ChatMessage, ClientTheme, SessionError, SessionErrorCode, ToolCallInfo, VoiceSessionOptions, WebSocketConstructor, } from "./types.ts";
-export { VOICE_CAPTURE_CONSTRAINTS } from "./types.ts";
+export { type ConversationItem, type UseConversationResult, useConversation, } from "./use-conversation.ts";
+export { type UseDownloadUrlOptions, type UseDownloadUrlResult, useDownloadUrl, } from "./use-download-url.ts";
 export { TRANSCRIBING_PLACEHOLDER, type UseUserTranscriptResult, useUserTranscript, } from "./use-user-transcript.ts";
 export { type UploadStatus, type UseWorkflowSubmitOptions, type UseWorkflowsOptions, type UseWorkflowsResult, useWorkflowSubmit, useWorkflows, type WorkflowSubmission, } from "./use-workflow-form.ts";
 export { DEFAULT_PROGRESS_POLL_MS, type UseWorkflowProgressResult, useWorkflowProgress, } from "./use-workflow-progress.ts";
 export { DEFAULT_WORKFLOW_POLL_MS, MAX_MISSING_READS, type UseWorkflowRunResult, useWorkflowRun, } from "./use-workflow-run.ts";
 export { type UseWorkflowRunsOptions, type UseWorkflowRunsResult, useWorkflowRuns, } from "./use-workflow-runs.ts";
 export { type UseWorkflowStreamOptions, useWorkflowStream, type WorkflowStreamSubmission, } from "./use-workflow-stream.ts";
-export { createWorkflowApi, isTerminal, type WorkflowApi, type WorkflowApiOptions, type WorkflowOutputOf, type WorkflowRun, type WorkflowSummary, } from "./workflow-client.ts";
+export { createWorkflowApi, isTerminal, type WorkflowApi, type WorkflowApiOptions, type WorkflowOutputOf, type WorkflowRun, type WorkflowRunStatus, type WorkflowSummary, } from "./workflow-client.ts";
+export { WORKFLOW_STATUS_LABELS } from "./workflow-status-labels.ts";