@alexkroman1/aai-ui 0.17.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-CzvWmw4X.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/{message-list-BsaBkBgo.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";

package/dist/route-fetch.d.ts

@@ -41,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;
 };
@@ -72,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/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-3lgPYNNO.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-3lgPYNNO.js → session-Rud8mmU-.js}

@@ -1,5 +1,5 @@
-import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
-import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-CzvWmw4X.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 { errorMessage, safeJsonParse } from "@alexkroman1/aai";
 import { SESSION_AUTH_PROTOCOL_PREFIX, SESSION_PROTOCOL, SessionEventSchema, lenientParse } from "@alexkroman1/aai/protocol";

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

@@ -340,12 +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`. */
@@ -357,6 +358,50 @@ 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

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-dictation.d.ts

@@ -0,0 +1,145 @@
+/**
+ * `useDictation` — speak into a text box: record a clip, have it transcribed,
+ * hand the words to the page.
+ *
+ * Not a session. There is no agent on the other end and no socket: the clip
+ * goes to AssemblyAI's dictation API in ONE request, through a `transcribe`
+ * callback the page supplies — on the far side of which is a server holding
+ * the key, calling `transcribeDictation` from `@alexkroman1/aai/experimental`.
+ * The key never reaches the browser, which is why this hook takes a callback
+ * rather than a credential.
+ *
+ * The two ends that are not this hook are published too: `dictationTranscriber`
+ * is the `transcribe` for a server answering `handleDictationRequest`'s
+ * `{ text } | { error }`, and `appendDictation` adds the words to a draft.
+ *
+ * What it owns, because each is a way a hand-written mic button goes wrong:
+ *
+ * - **The recording indicator goes out.** Every way out — stop, cancel, the
+ *   length cap, an unmount mid-recording — releases the microphone.
+ * - **A late answer lands nowhere.** A transcription that settles after a
+ *   cancel, a newer recording or an unmount is dropped, never typed into the
+ *   box the user has moved on from.
+ * - **The button cannot be pressed into a bad state.** `buttonProps` keeps a
+ *   recording stoppable while `disabled`, and takes no press mid-transition.
+ * - **The clip fits the endpoint.** Recording stops by itself at `maxSeconds`
+ *   and is transcribed, rather than growing into a clip the service refuses
+ *   whole.
+ */
+import type { DictationRecorder } from "./audio/index.ts";
+/**
+ * Options for {@link useDictation}.
+ *
+ * @input
+ */
+export type UseDictationOptions = {
+    /**
+     * Turn one clip — a mono 16-bit WAV — into text. Called once per recording,
+     * with a signal that aborts when the result would no longer be used. Usually
+     * a `POST` to the page's own server, which forwards the clip to the
+     * dictation API under its key. A rejection is shown as `error`.
+     */
+    transcribe: (audio: Blob, options: {
+        signal: AbortSignal;
+    }) => Promise<string>;
+    /**
+     * The words, once a recording is transcribed. Not called for an empty
+     * transcript (the user said nothing) or for a recording that was cancelled.
+     */
+    onText: (text: string) => void;
+    /**
+     * The longest recording, in seconds: it stops and is transcribed by itself
+     * then. Defaults to the dictation API's own ceiling, 120.
+     */
+    maxSeconds?: number;
+    /**
+     * Refuse to START a recording — the text box is not accepting input right
+     * now. A recording already running can still be stopped and transcribed, so
+     * the words said before the box went dead are not lost. Default `false`.
+     */
+    disabled?: boolean;
+};
+/**
+ * What {@link useDictation} returns.
+ *
+ * @sealed
+ * @public
+ */
+export type UseDictationResult = {
+    /**
+     * Where the hook is: `"idle"`, `"starting"` (asking for the microphone),
+     * `"recording"` or `"transcribing"`.
+     */
+    phase: "idle" | "starting" | "recording" | "transcribing" | (string & {});
+    /** Why the last recording produced no text, or `null`. Cleared by `start`. */
+    error: string | null;
+    /**
+     * Whether this browser can record at all — a microphone API, an
+     * `AudioContext` and audio worklets. A button should not render without it.
+     */
+    supported: boolean;
+    /** Ask for the microphone and start recording. Ignored unless idle, and while `disabled`. */
+    start: () => void;
+    /** Stop recording and transcribe what was said. Ignored unless recording. */
+    stop: () => void;
+    /** Throw the recording (or the transcription in flight) away. */
+    cancel: () => void;
+    /** `start` when idle, `stop` when recording — one button. */
+    toggle: () => void;
+    /**
+     * Spread onto a `<button>`: `toggle`, and the two rules a hand-written one
+     * gets wrong — a recording can ALWAYS be stopped (even with `disabled` set),
+     * and nothing can be pressed while the microphone opens or the clip is
+     * transcribing. Label and style it however you like.
+     */
+    buttonProps: {
+        onClick: () => void;
+        disabled: boolean;
+        "aria-pressed": boolean;
+    };
+};
+/** How a recorder is opened; the real one loads the audio chunk on first use. */
+export type OpenDictationRecorder = (opts: {
+    sampleRate: number;
+    maxSeconds: number;
+}) => Promise<DictationRecorder>;
+/**
+ * Record what the user says and hand it back as text — a microphone button
+ * for a text box.
+ *
+ * @example
+ * ```tsx
+ * import { appendDictation, dictationTranscriber, useDictation } from "@alexkroman1/aai-ui";
+ * import { useState } from "react";
+ *
+ * // `POST /dictation` on your own server is `handleDictationRequest`
+ * // (`@alexkroman1/aai/experimental`), which holds the API key.
+ * const transcribe = dictationTranscriber("/dictation");
+ *
+ * export function SpokenNote() {
+ *   const [draft, setDraft] = useState("");
+ *   const dictation = useDictation({
+ *     transcribe,
+ *     onText: (text) => setDraft((d) => appendDictation(d, text)),
+ *   });
+ *   return (
+ *     <div>
+ *       <textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
+ *       {dictation.supported && (
+ *         <button type="button" {...dictation.buttonProps}>
+ *           {dictation.phase === "recording" ? "Stop" : "Speak"}
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useDictation(options: UseDictationOptions): UseDictationResult;
+/**
+ * {@link useDictation} over an injected recorder — the seam the specs drive.
+ * Not on the barrel.
+ */
+export declare function useDictationWith(options: UseDictationOptions, open: OpenDictationRecorder): UseDictationResult;

package/dist/use-route.d.ts

@@ -7,6 +7,14 @@
  * dropped — `useWorkflowRuns`' rule), a read landing after unmount, and a
  * failure rendered as an empty answer. `data` is KEPT through a failed re-read,
  * so a poll that hiccups does not blank the panel; `error` says it is stale.
+ * It is NOT kept across a change of `path`: the answer is remembered with the
+ * path it came from, so a page switching from one record to the next never
+ * shows the previous one under the new id while the first read is in flight.
+ *
+ * The poll is `repeatUntil`'s loop (`_repeat-until.ts`), re-armed from the
+ * SETTLED read rather than on an interval — a slow route would otherwise
+ * stack overlapping reads — and stopped by `until`, by a change of what is
+ * read, and by unmount, with the in-flight request aborted on the same signal.
  *
  * @module
  */
@@ -16,15 +24,31 @@
  * @input
  * @public
  */
-export type UseRouteOptions = {
-    /** Read again every this many ms, while mounted. Default: never. */
+export type UseRouteOptions<T = unknown> = {
+    /**
+     * Read again every this many ms, while mounted. `0` or unset: never. A
+     * negative or `NaN` value throws rather than polling as fast as the route
+     * answers.
+     */
     pollMs?: number | undefined;
+    /**
+     * Stop polling once an answer satisfies this — a call that is over, a job
+     * that has settled. Judged on every read, the first included; `reload()`
+     * still works afterwards. Read per request, so an inline function is fine.
+     */
+    until?: ((value: T) => boolean) | undefined;
     /**
      * The `?client=` to send. Default: the session's client
      * (`session.identity.clientId()`, read per request) inside `mountClient()`,
      * none on a page with no session.
      */
     client?: string | undefined;
+    /**
+     * Extra request headers, as `routeFetch`'s — an `authorization` for a route
+     * behind `apiKeyRoute`. Read per request, so an inline object does not
+     * re-trigger the read.
+     */
+    headers?: Readonly<Record<string, string>> | undefined;
 };
 /**
  * What {@link useRoute} returns.
@@ -33,9 +57,12 @@ export type UseRouteOptions = {
  * @public
  */
 export type UseRouteResult<T> = {
-    /** The last answer, kept through a failed re-read. `undefined` until the first. */
+    /**
+     * The last answer for THIS `path`, kept through a failed re-read.
+     * `undefined` until the first, and again whenever `path` changes.
+     */
     data: T | undefined;
-    /** Why the LAST read failed — the route's `{ error }` when it said — or `undefined`. */
+    /** Why the LAST read of this `path` failed — the route's `{ error }` when it said — or `undefined`. */
     error: string | undefined;
     /** Whether a read is in flight. */
     loading: boolean;
@@ -44,7 +71,7 @@ export type UseRouteResult<T> = {
 };
 /**
  * `GET` one of the agent's own routes, on mount, on `reload()` and every
- * `pollMs` — see this module's doc.
+ * `pollMs` until `until` says so — see this module's doc.
  *
  * @example A list that re-reads after each delete
  * ```tsx
@@ -74,11 +101,26 @@ export type UseRouteResult<T> = {
  * }
  * ```
  *
+ * @example A call followed until it is over
+ * ```tsx
+ * import { useRoute } from "@alexkroman1/aai-ui";
+ *
+ * type Call = { status: string; transcript: { role: string; text: string }[] };
+ *
+ * function LiveCall({ id }: { id: string }) {
+ *   const { data } = useRoute<Call>(`/calls/${id}`, {
+ *     pollMs: 2000,
+ *     until: (call) => call.status === "completed",
+ *   });
+ *   return <ol>{data?.transcript.map((line, i) => <li key={String(i)}>{line.text}</li>)}</ol>;
+ * }
+ * ```
+ *
  * @typeParam T - The shape the route answers. Not checked.
  * @param path - The route's path as declared, without `/api`. `null` reads nothing.
- * @param options - `pollMs` and `client`; see {@link UseRouteOptions}.
+ * @param options - `pollMs`, `until`, `client` and `headers`; see {@link UseRouteOptions}.
  * @returns The answer, the last error, and `reload`; see {@link UseRouteResult}.
  *
  * @public
  */
-export declare function useRoute<T = unknown>(path: string | null, options?: UseRouteOptions): UseRouteResult<T>;
+export declare function useRoute<T = unknown>(path: string | null, options?: UseRouteOptions<T>): UseRouteResult<T>;

package/dist/use-run-key.d.ts

@@ -87,6 +87,7 @@
  * the behaviour it would have had anyway — one run per load — rather than
  * failing to render.
  */
+import { type StorageKind } from "./_web-storage.ts";
 /**
  * The key `useWorkflowSubmit` uses when the page named none.
  *
@@ -107,10 +108,14 @@
  *
  * @param explicit - The caller's own key, or undefined for a page with none.
  * @returns The key to record runs under and look them up by.
+ * @throws When the caller's key is empty or whitespace — see
+ *   {@link assertUsableRunKey}.
  *
  * @internal
  */
-export declare function useDefaultRunKey(explicit: string | undefined): string;
+export declare function useDefaultRunKey(explicit: string | {
+    readonly storage?: StorageKind | undefined;
+} | undefined): string;
 /**
  * A lookup key for `useWorkflowSubmit({ key })`, stable across reloads.
  *

package/dist/{use-user-transcript-uyHhzy4d.js → use-user-transcript-lOu_uMnf.js}

@@ -1,4 +1,4 @@
-import { useSessionSelector } from "./context.js";
+import { c as useSessionSelector } from "./context-BF0KsI9X.js";
 import { useMemo } from "react";
 //#region src/use-user-transcript.ts
 /**