@alexkroman1/aai-ui 0.16.0 → 0.18.0

package/dist/use-conversation.d.ts

@@ -33,6 +33,12 @@ import { type UseUserTranscriptResult } from "./use-user-transcript.ts";
  * is the thing this hook computes — handing back two lists would hand back the
  * problem. `kind` is what a `switch` in a custom renderer narrows on.
  *
+ * `"other"` is the row this version cannot describe — today, an item a newer
+ * page wrote into a stored conversation log (`type` is the `kind` it was
+ * stored under). It is a member from the start so that a row kind added
+ * later is a value an existing `switch` already has a branch for, not a
+ * compile error: render nothing for it, or a placeholder.
+ *
  * @public
  */
 export type ConversationItem = {
@@ -41,10 +47,14 @@ export type ConversationItem = {
 } | {
     kind: "tool";
     toolCall: ToolCallInfo;
+} | {
+    kind: "other";
+    type: string;
 };
 /**
  * What {@link useConversation} returns.
  *
+ * @sealed
  * @public
  */
 export type UseConversationResult = {
@@ -107,15 +117,20 @@ export declare function interleave(messages: readonly ChatMessage[], 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>}

package/dist/use-copy.d.ts

@@ -17,6 +17,7 @@
  * What {@link useCopy} hands back — the click handler and the two readings a
  * button needs off one shared flash.
  *
+ * @sealed
  * @public
  */
 export type UseCopyResult = {

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-download-url.d.ts

@@ -23,7 +23,11 @@
  * "downloading" as the same thing — so this reports it.
  */
 import type { WorkflowApi } from "./workflow-client.ts";
-/** Options for {@link useDownloadUrl}. */
+/**
+ * Options for {@link useDownloadUrl}.
+ *
+ * @input
+ */
 export type UseDownloadUrlOptions = {
     /** The client to read the bytes with. Defaults to one for the page's own agent. */
     api?: WorkflowApi;
@@ -31,6 +35,7 @@ export type UseDownloadUrlOptions = {
 /**
  * What {@link useDownloadUrl} reports.
  *
+ * @sealed
  * @public
  */
 export type UseDownloadUrlResult = {

package/dist/use-flash.d.ts

@@ -15,6 +15,7 @@
  * @typeParam T - What is being flashed. A `string` for a label; a record for a
  *   flash that has to say WHICH thing it belongs to, as `useCopy` does.
  *
+ * @sealed
  * @public
  */
 export type UseFlashResult<T> = {

package/dist/use-inbox.d.ts

@@ -33,6 +33,7 @@ import type { InboxEvent, InboxNotice } from "./inbox-protocol.ts";
 /**
  * Options for {@link useInbox}.
  *
+ * @input
  * @public
  */
 export type UseInboxOptions = {
@@ -63,6 +64,7 @@ export type UseInboxOptions = {
 /**
  * What {@link useInbox} returns.
  *
+ * @sealed
  * @public
  */
 export type UseInboxResult = {

package/dist/use-push-to-talk.d.ts

@@ -21,7 +21,11 @@
  * And one that is a nuisance rather than a stuck turn: the hold key is ignored
  * while focus is in a text field, where Space is a character.
  */
-/** Options for {@link usePushToTalk}. */
+/**
+ * Options for {@link usePushToTalk}.
+ *
+ * @input
+ */
 export type UsePushToTalkOptions = {
     /**
      * The keyboard key that holds the turn open, as a `KeyboardEvent.code` —
@@ -34,6 +38,7 @@ export type UsePushToTalkOptions = {
 /**
  * What {@link usePushToTalk} returns.
  *
+ * @sealed
  * @public
  */
 export type UsePushToTalkResult = {

package/dist/use-route-mutation.d.ts

@@ -26,6 +26,7 @@ import { type RouteMethod } from "./route-fetch.ts";
 /**
  * Options for {@link useRouteMutation}.
  *
+ * @input
  * @public
  */
 export type UseRouteMutationOptions = {
@@ -45,6 +46,7 @@ export type UseRouteMutationOptions = {
 /**
  * Options for one {@link UseRouteMutationResult.run} call.
  *
+ * @input
  * @public
  */
 export type RouteMutationRunOptions = {
@@ -58,6 +60,7 @@ export type RouteMutationRunOptions = {
 /**
  * What {@link useRouteMutation} returns.
  *
+ * @sealed
  * @public
  */
 export type UseRouteMutationResult = {

package/dist/use-route.d.ts

@@ -7,33 +7,62 @@
  * 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
  */
 /**
  * Options for {@link useRoute}.
  *
+ * @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.
  *
+ * @sealed
  * @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;
@@ -42,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
@@ -72,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-session-controls.d.ts

@@ -14,6 +14,7 @@
 /**
  * What {@link useSessionControls} returns.
  *
+ * @sealed
  * @public
  */
 export type UseSessionControlsResult = {

package/dist/use-tap-to-talk.d.ts

@@ -31,6 +31,7 @@
 /**
  * Options for {@link useTapToTalk}.
  *
+ * @input
  * @public
  */
 export type UseTapToTalkOptions = {
@@ -56,14 +57,16 @@ export type UseTapToTalkOptions = {
 /**
  * What {@link useTapToTalk} returns.
  *
+ * @sealed
  * @public
  */
 export type UseTapToTalkResult = {
     /**
      * The call: `"idle"` (not meant to be running), `"connecting"`, or
-     * `"active"` — up, whatever the agent is doing.
+     * `"active"` — up, whatever the agent is doing. Open (`| (string & {})`) so
+     * a phase added later is not a break.
      */
-    phase: "idle" | "connecting" | "active";
+    phase: "idle" | "connecting" | "active" | (string & {});
     /** Whether the caller is live — mic open, in a realtime conversation. The button is ON. */
     live: boolean;
     /**

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
 /**

package/dist/use-user-transcript.d.ts

@@ -33,7 +33,11 @@
  * @internal
  */
 export declare const TRANSCRIBING_PLACEHOLDER = "\u2026";
-/** What {@link useUserTranscript} returns. */
+/**
+ * What {@link useUserTranscript} returns.
+ *
+ * @sealed
+ */
 export interface UseUserTranscriptResult {
     /**
      * True while the caller holds the turn — from speech detection to the final