@alexkroman1/aai-ui 0.16.0 → 0.18.0

package/dist/internal.d.ts

@@ -34,7 +34,7 @@
  * @module internal
  */
 export { buildAgentUrl, loadClientConfig } from "./client-config.ts";
-export { ToolConfigContext } from "./components/tool-config-context.ts";
+export { ToolConfigContext, type ToolDisplayConfig } from "./components/tool-config-context.ts";
 export { ApiUrlChip, SessionUrlChips, UiUrlChip } from "./components/url-chips.tsx";
 export { SessionProvider, ThemeProvider } from "./context.ts";
 export { VOICE_CAPTURE_CONSTRAINTS } from "./types.ts";

package/dist/internal.js

@@ -1,8 +1,8 @@
-import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-C7fQrioM.js";
-import { SessionProvider, ThemeProvider } from "./context.js";
-import { n as SessionUrlChips, r as UiUrlChip, t as ApiUrlChip } from "./url-chips-oyy_Eiqh.js";
-import { t as TRANSCRIBING_PLACEHOLDER } from "./use-user-transcript-uyHhzy4d.js";
-import { t as ToolConfigContext } from "./tool-config-context-Es4YUzV2.js";
-import { i as DEFAULT_PROGRESS_POLL_MS, n as MAX_MISSING_READS, t as DEFAULT_WORKFLOW_POLL_MS } from "./use-workflow-run-DdhWmbx-.js";
+import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-DcMCWmkO.js";
+import { n as ThemeProvider, t as SessionProvider } from "./context-BF0KsI9X.js";
+import { n as SessionUrlChips, r as UiUrlChip, t as ApiUrlChip } from "./url-chips-C_SHU6fq.js";
+import { t as TRANSCRIBING_PLACEHOLDER } from "./use-user-transcript-lOu_uMnf.js";
+import { n as ToolConfigContext } from "./tool-config-context-Bd-7xrfP.js";
+import { i as DEFAULT_PROGRESS_POLL_MS, n as MAX_MISSING_READS, t as DEFAULT_WORKFLOW_POLL_MS } from "./use-workflow-run-BTEemod0.js";
 import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
 export { ApiUrlChip, DEFAULT_PROGRESS_POLL_MS, DEFAULT_WORKFLOW_POLL_MS, MAX_MISSING_READS, SessionProvider, SessionUrlChips, TRANSCRIBING_PLACEHOLDER, ThemeProvider, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, buildAgentUrl, loadClientConfig };

package/dist/linked-client.d.ts

@@ -17,6 +17,7 @@
 /**
  * Options for {@link createLinkedClient}.
  *
+ * @input
  * @public
  */
 export type LinkedClientOptions = {
@@ -31,6 +32,7 @@ export type LinkedClientOptions = {
 /**
  * Which client a page is — see {@link createLinkedClient}.
  *
+ * @sealed
  * @public
  */
 export type LinkedClient = {

package/dist/{message-list-DHZcLhRA.js → message-list-BBHLK05X.js}

@@ -1,7 +1,7 @@
-import { useSessionSelector, useTheme } from "./context.js";
+import { c as useSessionSelector, u as useTheme } from "./context-BF0KsI9X.js";
 import { a as inkTint, o as primaryTint } from "./_colors-CpZO-88A.js";
-import { n as useUserTranscript } from "./use-user-transcript-uyHhzy4d.js";
-import { n as ToolCallRow, t as ToolCallBlock } from "./tool-call-block-uXtMOUWN.js";
+import { n as useUserTranscript } from "./use-user-transcript-lOu_uMnf.js";
+import { n as ToolCallRow, t as ToolCallBlock } from "./tool-call-block-C8s6AhjS.js";
 import { memo, useCallback, useMemo } from "react";
 import clsx from "clsx";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
@@ -152,15 +152,20 @@ function isThinking(state, messages, toolCalls) {
 *   const { items, streaming, transcript, thinking } = useConversation();
 *   return (
 *     <div>
-*       {items.map((item) =>
-*         item.kind === "message" ? (
-*           <p key={item.message.id} data-role={item.message.role}>
-*             {item.message.content}
-*           </p>
-*         ) : (
-*           <code key={item.toolCall.callId}>{item.toolCall.name}</code>
-*         ),
-*       )}
+*       {items.map((item) => {
+*         switch (item.kind) {
+*           case "message":
+*             return (
+*               <p key={item.message.id} data-role={item.message.role}>
+*                 {item.message.content}
+*               </p>
+*             );
+*           case "tool":
+*             return <code key={item.toolCall.callId}>{item.toolCall.name}</code>;
+*           default:
+*             return null;
+*         }
+*       })}
 *       {streaming !== null && <p data-role="assistant">{streaming}</p>}
 *       {transcript.speaking && <p data-role="user">{transcript.text}</p>}
 *       {thinking && <p>…</p>}
@@ -280,7 +285,13 @@ function ConversationView({ renderMessage, renderTool = defaultTool, renderStrea
 	const { items, streaming, transcript, thinking } = useConversation();
 	const liveItems = log ? void 0 : items;
 	const rows = useMemo(() => {
-		const renderItem = (item, key) => item.kind === "message" ? renderKeyed(`${key}m${item.message.id}`, renderMessage(item.message)) : renderKeyed(`${key}t${item.toolCall.callId}`, renderTool(item.toolCall));
+		const renderItem = (item, key) => {
+			switch (item.kind) {
+				case "message": return renderKeyed(`${key}m${item.message.id}`, renderMessage(item.message));
+				case "tool": return renderKeyed(`${key}t${item.toolCall.callId}`, renderTool(item.toolCall));
+				default: return null;
+			}
+		};
 		if (!log) return (liveItems ?? []).map((item) => renderItem(item, ""));
 		return logRows(log, renderItem, renderMessage, renderNote, renderSessionHeader);
 	}, [

package/dist/page.d.ts

@@ -27,6 +27,7 @@ import type { ClientTheme } from "./types.ts";
 /**
  * Configuration for {@link mountPage}.
  *
+ * @input
  * @public
  */
 export type PageConfig = {
@@ -55,6 +56,7 @@ export type PageConfig = {
 /**
  * Handle returned by {@link mountPage}. `Disposable`, so `using` works.
  *
+ * @sealed
  * @public
  */
 export type PageHandle = {

package/dist/phone.d.ts

@@ -12,6 +12,7 @@
 /**
  * Options for {@link phoneE164}.
  *
+ * @input
  * @public
  */
 export type PhoneE164Options = {

package/dist/route-fetch.d.ts

@@ -29,6 +29,7 @@ export type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /**
  * Options for {@link routeFetch}.
  *
+ * @input
  * @public
  */
 export type RouteFetchOptions = {
@@ -40,6 +41,12 @@ export type RouteFetchOptions = {
     client?: string | undefined;
     /** The agent's base URL. Default: the page's own directory. */
     baseUrl?: string | undefined;
+    /**
+     * Extra request headers — an `authorization` for a route behind
+     * `apiKeyRoute`, say. Names are case-insensitive, so a `content-type` (or
+     * `Content-Type`) here beats the JSON one a body would set.
+     */
+    headers?: Readonly<Record<string, string>> | undefined;
     /** Abort the request. */
     signal?: AbortSignal | undefined;
 };
@@ -71,7 +78,7 @@ export type RouteFetchOptions = {
  * @param method - The route's method.
  * @param path - The route's path as declared, starting with `/`; `?query` allowed.
  * @param body - Sent as JSON when given.
- * @param options - `client`, `baseUrl` and `signal`; see {@link RouteFetchOptions}.
+ * @param options - `client`, `baseUrl`, `headers` and `signal`; see {@link RouteFetchOptions}.
  * @returns The parsed JSON body.
  *
  * @public

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

@@ -53,5 +53,5 @@ export type AudioPathCallbacks = {
  * up for a connection nobody wants any more is a live microphone, and no
  * amount of cancellation upstream releases the device.
  */
-export declare function openAudioPath(config: AudioPathConfig, callbacks: AudioPathCallbacks, preConnect?: Promise<PreConnectCapture | null> | null): Promise<VoiceIO>;
+export declare function openAudioPath(config: AudioPathConfig, callbacks: AudioPathCallbacks, preConnect?: Promise<PreConnectCapture | null> | null, signal?: AbortSignal): Promise<VoiceIO>;
 export {};

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

@@ -32,14 +32,14 @@
  *   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
+ * ## Cancellation follows the microphone's ownership
  *
  * 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.
+ * `signal` after `openAudioPath` settles and releases what it built. The same
+ * signal reaches the opening path and the transferred pre-connect capture,
+ * so cancellation before the lazy modules load prevents a permission request
+ * in the first place. Both checks live with the producer that owns the device.
  *
  * ## Effects stay in the session core
  *
@@ -63,7 +63,7 @@ export type AudioPathEffects = {
      * 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>;
+    open(config: AudioPathConfig, callbacks: AudioPathCallbacks, signal: AbortSignal): Promise<VoiceIO>;
     /** Relay captured microphone audio to the server. */
     sendMicAudio(pcm16: ArrayBuffer): void;
     /**

package/dist/session/index.js

@@ -1,2 +1,2 @@
-import { a as ticketCarriage, i as resolveSessionTokenSync, n as CLEARED_SESSION_STATE, o as loadAudioModules, r as resolveSessionToken, t as createBrowserSession } from "../session-CYdjRvbl.js";
+import { a as ticketCarriage, i as resolveSessionTokenSync, n as CLEARED_SESSION_STATE, o as loadAudioModules, r as resolveSessionToken, t as createBrowserSession } from "../session-Rud8mmU-.js";
 export { CLEARED_SESSION_STATE, createBrowserSession, loadAudioModules, resolveSessionToken, resolveSessionTokenSync, ticketCarriage };

package/dist/session/messages.d.ts

@@ -7,15 +7,7 @@ import { type ConnState, type SessionSnapshot } from "./types.ts";
  * The empty arrays are safe to share: snapshot collections are never mutated
  * in place, only replaced.
  */
-export declare const CLEARED_SESSION_STATE: {
-    messages: never[];
-    toolCalls: never[];
-    customEvents: never[];
-    agentState: null;
-    userTranscript: null;
-    agentTranscript: null;
-    error: null;
-};
+export declare const CLEARED_SESSION_STATE: Readonly<Pick<SessionSnapshot, "messages" | "toolCalls" | "customEvents" | "agentState" | "userTranscript" | "agentTranscript" | "error">>;
 /** Config payload extracted from a `config` server message. */
 export type SessionConfigMessage = {
     sampleRate: number;

package/dist/session/preconnect.d.ts

@@ -40,7 +40,7 @@ export type PreConnectAudio = {
      */
     begin(): void;
     /** Hand the held capture to a bring-up, or `null` when none is held. */
-    take(): Promise<PreConnectCapture | null> | null;
+    take(signal?: AbortSignal): Promise<PreConnectCapture | null> | null;
     /** Release a held capture: the session is over or starting afresh. */
     release(): void;
 };

package/dist/session/types.d.ts

@@ -15,6 +15,7 @@ import type { AudioPath } from "./audio-state.ts";
  * Deliberately NOT the DOM `CustomEvent`: it shares nothing with that
  * interface, and the old name shadowed the global in `.tsx` files.
  *
+ * @sealed
  * @public
  */
 export type AgentCustomEvent = {
@@ -47,6 +48,7 @@ export type AgentStateFrame = Readonly<Record<string, unknown>>;
  * | `recording` | Is the microphone actually live right now? |
  * | `state` | What is the agent doing — see {@link AgentState}. |
  *
+ * @sealed
  * @public
  */
 export type SessionSnapshot = {
@@ -179,6 +181,7 @@ export declare const browserSessionBrand: unique symbol;
  * the session, so a feature one agent in many declares is not three members
  * every session carries in its autocomplete.
  *
+ * @sealed
  * @public
  */
 export type UserTurnControls = {
@@ -209,6 +212,7 @@ export type ToolCallOutcome = {
 /**
  * Options for {@link BrowserSession.sendText}.
  *
+ * @input
  * @public
  */
 export type SendTextOptions = {

package/dist/{session-CYdjRvbl.js → session-Rud8mmU-.js}

@@ -1,8 +1,8 @@
-import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
-import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-C7fQrioM.js";
+import { n as pageBaseUrl } from "./_utils-BlZBJPdj.js";
+import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-DcMCWmkO.js";
 import { MIC_SEND_MAX_BUFFERED_BYTES } from "./types.js";
-import { SessionEventSchema, errorMessage, safeJsonParse } from "@alexkroman1/aai";
-import { SESSION_AUTH_PROTOCOL_PREFIX, SESSION_PROTOCOL, lenientParse } from "@alexkroman1/aai/protocol";
+import { errorMessage, safeJsonParse } from "@alexkroman1/aai";
+import { SESSION_AUTH_PROTOCOL_PREFIX, SESSION_PROTOCOL, SessionEventSchema, lenientParse } from "@alexkroman1/aai/protocol";
 import { CLIENT_ID_RE, MAX_CLIENT_MESSAGES, RESUME_ID_RE, WS_OPEN, createEpoch, toArgsRecord } from "@alexkroman1/aai/internal";
 import { omitUndefined } from "@alexkroman1/aai/utils";
 import { and, assign, createActor, fromPromise, not, setup, stateIn } from "xstate";
@@ -213,17 +213,19 @@ function loadAudioModules() {
 * up for a connection nobody wants any more is a live microphone, and no
 * amount of cancellation upstream releases the device.
 */
-async function openAudioPath(config, callbacks, preConnect) {
+async function openAudioPath(config, callbacks, preConnect, signal) {
 	const pre = await preConnect ?? void 0;
 	try {
-		return await openVoiceIO(config, callbacks, pre);
+		signal?.throwIfAborted();
+		return await openVoiceIO(config, callbacks, pre, signal);
 	} catch (err) {
 		pre?.close();
 		throw err;
 	}
 }
-async function openVoiceIO(config, callbacks, pre) {
+async function openVoiceIO(config, callbacks, pre, signal) {
 	const [{ createVoiceIO }, captureWorklet, playbackWorklet] = await loadAudioModules();
+	signal?.throwIfAborted();
 	return createVoiceIO({
 		preConnect: pre,
 		onPreConnectAudio: callbacks.onPreConnectAudio,
@@ -297,7 +299,7 @@ function createAudioEffects(deps) {
 		});
 	}
 	return {
-		open: (config, callbacks) => (deps.openAudioPath ?? openAudioPath)(config, callbacks, preConnect.take()),
+		open: (config, callbacks, signal) => (deps.openAudioPath ?? openAudioPath)(config, callbacks, preConnect.take(signal), signal),
 		sendMicAudio: (pcm16) => {
 			try {
 				mic.sendAudio(pcm16);
@@ -379,14 +381,14 @@ function createAudioEffects(deps) {
 *   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
+* ## Cancellation follows the microphone's ownership
 *
 * 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.
+* `signal` after `openAudioPath` settles and releases what it built. The same
+* signal reaches the opening path and the transferred pre-connect capture,
+* so cancellation before the lazy modules load prevents a permission request
+* in the first place. Both checks live with the producer that owns the device.
 *
 * ## Effects stay in the session core
 *
@@ -438,7 +440,7 @@ bringUp: fromPromise(async ({ input, signal }) => {
 					message
 				});
 			}
-		});
+		}, signal);
 		if (signal.aborted) {
 			input.effects.release(io);
 			throw ABANDONED;
@@ -1651,10 +1653,19 @@ function createPreConnectAudio(enabled) {
 				maxSeconds: 10
 			})).catch(() => null);
 		},
-		take() {
+		take(signal) {
 			const taken = held;
+			const current = attempt;
 			held = null;
 			attempt = null;
+			if (taken && current && signal) {
+				const release = () => {
+					current.released = true;
+				};
+				if (signal.aborted) release();
+				else signal.addEventListener("abort", release, { once: true });
+				return taken.finally(() => signal.removeEventListener("abort", release));
+			}
 			return taken;
 		},
 		release() {

package/dist/stored-value.d.ts

@@ -19,6 +19,7 @@
 /**
  * Options for {@link createStoredValue}.
  *
+ * @input
  * @public
  */
 export type StoredValueOptions = {
@@ -30,6 +31,7 @@ export type StoredValueOptions = {
 /**
  * One remembered string — see {@link createStoredValue}.
  *
+ * @sealed
  * @public
  */
 export type StoredValue = {

package/dist/{tool-call-block-uXtMOUWN.js → tool-call-block-C8s6AhjS.js}

@@ -1,8 +1,8 @@
-import { a as tryParseJSON, i as truncate } from "./_utils-Mi-SCFA1.js";
-import { useTheme } from "./context.js";
+import { a as tryParseJSON, i as truncate } from "./_utils-BlZBJPdj.js";
+import { u as useTheme } from "./context-BF0KsI9X.js";
 import { a as inkTint } from "./_colors-CpZO-88A.js";
-import { t as Eyebrow } from "./eyebrow-UfmSz9yy.js";
-import { n as useToolConfig } from "./tool-config-context-Es4YUzV2.js";
+import { t as Eyebrow } from "./eyebrow-Bp4y1rZ9.js";
+import { r as useToolConfig } from "./tool-config-context-Bd-7xrfP.js";
 import { memo, useMemo, useState } from "react";
 import clsx from "clsx";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";

package/dist/tool-config-context-Bd-7xrfP.js

@@ -0,0 +1,28 @@
+import { createContext, useContext } from "react";
+//#region src/components/tool-config-context.ts
+/**
+* The value the context holds before the lookup lands (and forever, when the
+* lookup fails): one frozen object, so the provider's value is stable across
+* renders rather than a fresh `{}` per commit.
+*
+* @internal
+*/
+const EMPTY_TOOL_DISPLAY = Object.freeze({});
+/**
+* Context for tool display configuration. Installed by `mountClient()` from
+* the agent's `GET /client-config` `tools`; the built-in components read it
+* via `useToolConfig`.
+*
+* @internal
+*/
+const ToolConfigContext = createContext(EMPTY_TOOL_DISPLAY);
+/**
+* Read tool display configuration from the nearest `ToolConfigContext.Provider`.
+*
+* @internal
+*/
+function useToolConfig() {
+	return useContext(ToolConfigContext);
+}
+//#endregion
+export { ToolConfigContext as n, useToolConfig as r, EMPTY_TOOL_DISPLAY as t };

package/dist/types.d.ts

@@ -56,9 +56,13 @@ export declare const VOICE_CAPTURE_CONSTRAINTS: MediaTrackConstraints;
  *   until the next completed handshake, so a later frame cannot quietly paint
  *   over the banner explaining a dead call.
  *
+ * The set is OPEN (`| (string & {})`): a later release may add a state, so a
+ * `switch` over it needs a `default`, and a lookup keyed by it needs a
+ * fallback for a state it has no entry for.
+ *
  * @public
  */
-export type AgentState = "disconnected" | "connecting" | "ready" | "listening" | "thinking" | "speaking" | "error";
+export type AgentState = "disconnected" | "connecting" | "ready" | "listening" | "thinking" | "speaking" | "error" | (string & {});
 /**
  * A chat message exchanged between user and assistant.
  *
@@ -67,6 +71,7 @@ export type AgentState = "disconnected" | "connecting" | "ready" | "listening" |
  * surfaced via `SessionSnapshot.toolCalls` (or `useEvent` for `ctx.send`
  * events).
  *
+ * @sealed
  * @public
  */
 export type ChatMessage = {
@@ -76,14 +81,19 @@ export type ChatMessage = {
      * render key.
      */
     id: number;
-    /** The sender of the message. */
-    role: "user" | "assistant";
+    /**
+     * The sender of the message. Open (`| (string & {})`) so a later sender is
+     * not a break: render anything that is not `"user"` the way you render
+     * `"assistant"`, or skip it.
+     */
+    role: "user" | "assistant" | (string & {});
     /** The text content of the message. */
     content: string;
 };
 /**
  * Info about a tool call for display in the UI.
  *
+ * @sealed
  * @public
  */
 export type ToolCallInfo = {
@@ -105,7 +115,13 @@ export type ToolCallInfo = {
      * now actually compiles.
      */
     args: Record<string, DefaultToolResult>;
-    status: "pending" | "done";
+    /**
+     * `"pending"` until the tool returns, then `"done"`. A tool that FAILED is
+     * `"done"` too: the wire reports a failure as a completion whose `result` is
+     * the error text the model read. Open (`| (string & {})`) so a later status
+     * is not a break — treat anything but `"pending"` as settled.
+     */
+    status: "pending" | "done" | (string & {});
     result?: string | undefined;
     /**
      * Monotonically increasing, session-unique insertion sequence number.
@@ -128,6 +144,7 @@ export type { SessionErrorCode } from "@alexkroman1/aai/protocol";
 /**
  * Error reported by the voice session.
  *
+ * @sealed
  * @public
  */
 export type SessionError = {
@@ -157,6 +174,7 @@ export type SessionError = {
  * defaults `platformUrl` from `location.href`, while `createBrowserSession`
  * requires it.
  *
+ * @input
  * @public
  */
 export type VoiceSessionOptions = {
@@ -314,6 +332,7 @@ export type VoiceSessionOptions = {
 /**
  * Minimal WebSocket constructor type accepted by {@link VoiceSessionOptions}.
  *
+ * @input
  * @public
  */
 export type WebSocketConstructor = {
@@ -321,11 +340,13 @@ export type WebSocketConstructor = {
     readonly OPEN: number;
 };
 /**
- * Theme color overrides for the AAI UI components.
+ * The five theme tokens, each optional — the long form of {@link ClientTheme},
+ * for a page that names its own ground and surfaces.
  *
+ * @input
  * @public
  */
-export type ClientTheme = {
+export type ClientThemeTokens = {
     /** Background color, also painted on `html`/`body`. Default: `#FAFAFA`. */
     bg?: string;
     /** Primary accent color. Default: `#18181B`. */
@@ -337,3 +358,71 @@ export type ClientTheme = {
     /** Border color. Default: `#E4E4E7`. */
     border?: string;
 };
+/**
+ * The short form of {@link ClientTheme}: one accent and a light or dark
+ * ground, from which `bg`, `surface`, `text` and `border` are DERIVED.
+ *
+ * Most pages that themed at all set `primary` and nothing else — and the few
+ * that wanted a dark page had to look up four neutrals that go together.
+ * `{ primary: "#e55", mode: "dark" }` is that lookup done once
+ * (`resolveClientTheme`, `_theme.ts`); `mode` defaults to `"light"`, which is
+ * the default palette, so `{ primary }` means the same thing in both forms.
+ *
+ * @input
+ * @public
+ */
+export type ClientThemePreset = {
+    /** Primary accent color. */
+    primary: string;
+    /** The ground the neutrals are derived for. Default: `"light"`. */
+    mode?: "dark" | "light";
+};
+/**
+ * Theme color overrides for the AAI UI components: the five tokens
+ * ({@link ClientThemeTokens}), or an accent plus a light/dark mode
+ * ({@link ClientThemePreset}). Either resolves to a {@link ResolvedClientTheme}.
+ *
+ * The two forms are EXCLUSIVE: a theme naming `mode` may name no token but
+ * `primary`, and a theme naming a token may not name `mode`. Without the
+ * guards a mixed `{ primary, mode: "dark", bg }` compiled (an object literal is
+ * checked against the union as a whole, so a key from either member passed)
+ * and `bg` was silently dropped — the preset's derived neutrals won. The guard
+ * is `?: undefined` rather than `?: never` so an options bag that spells a hole
+ * as `undefined` still fits. `{ primary }` alone is both forms and resolves
+ * alike.
+ *
+ * @input
+ * @public
+ */
+export type ClientTheme = (ClientThemeTokens & {
+    mode?: undefined;
+}) | (ClientThemePreset & {
+    bg?: undefined;
+    text?: undefined;
+    surface?: undefined;
+    border?: undefined;
+});
+/**
+ * The theme a component reads back from `useTheme()`: every
+ * {@link ClientTheme} field, filled with its default where the client set
+ * none.
+ *
+ * Its own type rather than `Required<ClientTheme>`, because the two travel in
+ * opposite directions — an author BUILDS a `ClientTheme` and only READS this —
+ * so a token added later can be optional on one and present on the other.
+ *
+ * @sealed
+ * @public
+ */
+export type ResolvedClientTheme = {
+    /** Background color, also painted on `html`/`body`. */
+    readonly bg: string;
+    /** Primary accent color. */
+    readonly primary: string;
+    /** Main text color. */
+    readonly text: string;
+    /** Surface/card color. */
+    readonly surface: string;
+    /** Border color. */
+    readonly border: string;
+};

package/dist/{url-chips-oyy_Eiqh.js → url-chips-C_SHU6fq.js}

@@ -1,5 +1,5 @@
-import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
-import { useSessionSelector, useTheme } from "./context.js";
+import { n as pageBaseUrl } from "./_utils-BlZBJPdj.js";
+import { c as useSessionSelector, u as useTheme } from "./context-BF0KsI9X.js";
 import { a as inkTint, i as focusRingStyle, n as FOCUS_RING } from "./_colors-CpZO-88A.js";
 import { useEffect, useRef, useState } from "react";
 import clsx from "clsx";

package/dist/use-client-runs.d.ts

@@ -15,6 +15,7 @@ import type { ClientRun } from "@alexkroman1/aai";
 /**
  * Options for {@link useClientRuns}.
  *
+ * @input
  * @public
  */
 export type UseClientRunsOptions = {
@@ -29,6 +30,7 @@ export type UseClientRunsOptions = {
 /**
  * What {@link useClientRuns} returns.
  *
+ * @sealed
  * @public
  */
 export type UseClientRunsResult = {

package/dist/use-conversation-log.d.ts

@@ -23,6 +23,7 @@ import type { InboxEvent } from "./inbox-protocol.ts";
 /**
  * Options for {@link useConversationLog}.
  *
+ * @input
  * @public
  */
 export type UseConversationLogOptions = {
@@ -37,6 +38,7 @@ export type UseConversationLogOptions = {
 /**
  * What {@link useConversationLog} returns.
  *
+ * @sealed
  * @public
  */
 export type UseConversationLogResult = {