@alexkroman1/aai-ui 0.12.3 → 0.13.0

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

@@ -0,0 +1,87 @@
+/**
+ * `useClientRuns` — the page half of `clientRunsRoutes()` on
+ * `@alexkroman1/aai`: the runs going on for this client, polled, with a
+ * cancel.
+ *
+ * `useRoute` over the list route plus `useRouteMutation` over the cancel one,
+ * so it inherits both halves' rules — the stale-read drop, data kept through a
+ * failed poll, the session's client as `?client=`, no state after unmount —
+ * and adds only what every "Running" panel re-wrote: the row type, the cancel
+ * URL (`DELETE <path>/<runId>`, the id encoded) and the re-read after it.
+ *
+ * @module
+ */
+import type { ClientRun } from "@alexkroman1/aai";
+/**
+ * Options for {@link useClientRuns}.
+ *
+ * @public
+ */
+export type UseClientRunsOptions = {
+    /** Read the list again every this many ms, while mounted. Default 5000; `0` never. */
+    pollMs?: number | undefined;
+    /**
+     * The `?client=` to send. Default: the session's client inside
+     * `mountClient()`, none on a page with no session.
+     */
+    client?: string | undefined;
+};
+/**
+ * What {@link useClientRuns} returns.
+ *
+ * @public
+ */
+export type UseClientRunsResult = {
+    /** The client's runs, oldest first — `undefined` until the first read lands. */
+    runs: ClientRun[] | undefined;
+    /** Why the last read or cancel failed — the route's `{ error }` when it said — or `undefined`. */
+    error: string | undefined;
+    /** Read the list again now. */
+    reload: () => void;
+    /**
+     * Cancel one run, then re-read the list. Resolves `true` when this call
+     * ended it, `false` when it had already finished or the cancel failed (the
+     * reason is in `error`). Never rejects.
+     */
+    cancel: (runId: string) => Promise<boolean>;
+    /** The run id whose cancel is in flight, or `undefined` — to disable its button. */
+    cancelling: string | undefined;
+};
+/**
+ * The runs going on for this client, from a `clientRunsRoutes()` pair — see
+ * this module's doc.
+ *
+ * @example A "Running" panel with a Cancel on each live reminder
+ * ```tsx
+ * import { useClientRuns } from "@alexkroman1/aai-ui";
+ *
+ * function Running() {
+ *   const { runs, error, cancel, cancelling } = useClientRuns();
+ *   if (!runs) return error ? <p role="alert">{error}</p> : null;
+ *   return (
+ *     <ul>
+ *       {runs.map((r) => (
+ *         <li key={r.runId}>
+ *           {r.title} — {r.status}
+ *           {r.detail && <small>{r.detail}</small>}
+ *           {r.status === "running" && (
+ *             <button type="button" disabled={cancelling === r.runId} onClick={() => void cancel(r.runId)}>
+ *               Cancel
+ *             </button>
+ *           )}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @param path - The `path` the routes were declared with, without `/api`.
+ *   Default `"/tasks"`, `clientRunsRoutes()`' own default.
+ * @param options - `pollMs` and `client`; see {@link UseClientRunsOptions}.
+ * @returns The rows, the last error, `reload`, `cancel` and the id being
+ *   cancelled; see {@link UseClientRunsResult}.
+ *
+ * @public
+ */
+export declare function useClientRuns(path?: string, options?: UseClientRunsOptions): UseClientRunsResult;

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

@@ -0,0 +1,86 @@
+/**
+ * `useConversationLog` — everything this page has said and heard, across
+ * sessions, kept in `localStorage`.
+ *
+ * `useConversation()` is the CURRENT session; a page beside a device holds a
+ * new resumable session every few turns, and wants the whole history on screen
+ * after a reload. This hook writes the live conversation into a persisted log
+ * as it happens — handling the replay a resumed session brings back, so no turn
+ * is logged twice (the rules are `conversation-log.ts`'s module doc) — plus the
+ * page's own notes, what the device said on its own, and, through `mirror`, the
+ * live conversation of the client's OTHER sessions (a linked speaker's).
+ *
+ * **It opens no inbox socket.** The inbox keeps one socket per (client, holder)
+ * and a second from the same tab REPLACES the first, so `mirror` is a handler
+ * to hand the page's one `useInbox({ onEvent })`.
+ *
+ * `<ConversationView log={entries}>` renders it with the kit's own rows.
+ *
+ * @module
+ */
+import { type ConversationLogEntry } from "./conversation-log.ts";
+import type { InboxEvent } from "./inbox-protocol.ts";
+/**
+ * Options for {@link useConversationLog}.
+ *
+ * @public
+ */
+export type UseConversationLogOptions = {
+    /**
+     * The `localStorage` key, read once on mount. Default: one per agent URL, so
+     * two agents on one origin keep separate logs.
+     */
+    storageKey?: string | undefined;
+    /** Entries kept; the oldest go first. Default 300 — `localStorage` holds a few MB per origin. */
+    max?: number | undefined;
+};
+/**
+ * What {@link useConversationLog} returns.
+ *
+ * @public
+ */
+export type UseConversationLogResult = {
+    /** The log, oldest first; the live session is its newest session entry. */
+    readonly entries: readonly ConversationLogEntry[];
+    /** Log a line of the page's own: "New session", "Continuing an earlier conversation". */
+    addNote(text: string): void;
+    /** Log what the agent said outside a session — a reminder read aloud — as an assistant turn. */
+    addSpoken(text: string): void;
+    /**
+     * Mirror a frame of the client's live conversation into the log — pass it as
+     * `useInbox({ onEvent: log.mirror })`. The page's own session is skipped (it
+     * logs itself); every other session of the client is logged as it happens.
+     */
+    mirror(event: InboxEvent): void;
+    /** Forget the whole log, stored copy included. */
+    clear(): void;
+};
+/**
+ * A transcript that outlives the session — see this module's doc.
+ *
+ * Must be used inside the provider `mountClient()` installs; call it once per
+ * page, since two logs over one key would overwrite each other.
+ *
+ * @example The whole history, with a note per new session and a linked speaker mirrored
+ * ```tsx
+ * import { ConversationView, useConversationLog, useInbox } from "@alexkroman1/aai-ui";
+ *
+ * function History() {
+ *   const log = useConversationLog();
+ *   useInbox({ onEvent: log.mirror, onNotice: (n) => log.addNote(n.event) });
+ *   return (
+ *     <ConversationView
+ *       log={log.entries}
+ *       className="flex-1 min-h-0"
+ *       renderMessage={(m) => <p data-role={m.role}>{m.content}</p>}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param options - Where it is stored and how much; see {@link UseConversationLogOptions}.
+ * @returns The entries and the ways to add to them; see {@link UseConversationLogResult}.
+ *
+ * @public
+ */
+export declare function useConversationLog(options?: UseConversationLogOptions): UseConversationLogResult;

package/dist/use-conversation.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `useConversation` — the exchange, already assembled, with nothing rendered.
+ *
+ * `<MessageList>` owns four decisions that are not obvious and are not
+ * derivable from the snapshot by eye: the message/tool-call INTERLEAVE, the
+ * streaming agent utterance, the live user transcript with its `null`-vs-`""`
+ * protocol distinction, and the thinking indicator's suppression rule. Its only
+ * prop is `className`, so the moment a client wants its own bubble markup it
+ * drops all four at once — and the three hand-rolled chromes in the template
+ * tree each shipped a strictly worse conversation for exactly that reason. One
+ * of them runs fifteen tools and its operator sees none of them, because the
+ * tool calls live in a second array nothing in that page ever reads.
+ *
+ * This is the headless half. `<MessageList>` is now a thin consumer of it —
+ * which is the only way to know the hook is complete, since a hook that the
+ * package's own list cannot be built from is a hook a custom chrome will find a
+ * hole in.
+ *
+ * ## It subscribes NARROWLY, and that is half the value
+ *
+ * The three custom chromes also call whole-page `useSession()`, which re-renders
+ * on *every* snapshot change — so a dispatch board re-renders at STT-partial
+ * rate. `<ChatView>` deliberately avoids that with per-field
+ * {@link useSessionSelector} calls, and so does this: a component that reads the
+ * conversation gets the conversation's own update rate, not the session's.
+ */
+import type { ChatMessage, ToolCallInfo } from "./types.ts";
+import { type UseUserTranscriptResult } from "./use-user-transcript.ts";
+/**
+ * One row of the conversation: a finalized message, or a tool invocation.
+ *
+ * A discriminated union rather than two arrays, because the ORDER between them
+ * 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.
+ *
+ * @public
+ */
+export type ConversationItem = {
+    kind: "message";
+    message: ChatMessage;
+} | {
+    kind: "tool";
+    toolCall: ToolCallInfo;
+};
+/**
+ * What {@link useConversation} returns.
+ *
+ * @public
+ */
+export type UseConversationResult = {
+    /**
+     * Messages and tool calls in one list, in the order they happened.
+     *
+     * Referentially stable while neither array changes, so a consumer may map it
+     * inside a `useMemo` keyed on it, or hand rows to `memo()`ed components,
+     * without rebuilding the list on unrelated snapshot updates.
+     */
+    items: readonly ConversationItem[];
+    /**
+     * The agent's utterance as it arrives, or `null` between turns.
+     *
+     * Not yet a member of `items`: it has no id and it is replaced wholesale on
+     * every delta, so it is rendered as its own trailing row and disappears when
+     * the finalized message takes its place.
+     */
+    streaming: string | null;
+    /**
+     * The caller's in-progress turn — {@link useUserTranscript}'s result,
+     * forwarded rather than re-derived, so the `null`-vs-`""` distinction is made
+     * in exactly one place.
+     */
+    transcript: UseUserTranscriptResult;
+    /**
+     * Whether to show a thinking indicator.
+     *
+     * The suppression rule, and it is why this is a field rather than
+     * `state === "thinking"`: the agent is `thinking` for a stretch during which
+     * something ELSE is already saying so. A pending tool call draws its own
+     * spinner, and a trailing agent message means the reply has begun landing —
+     * in both cases a second indicator underneath reads as a second thing
+     * happening. So it is on only while `thinking` with no pending tool call, and
+     * either no messages yet, a trailing USER message, or a settled tool call
+     * after it.
+     */
+    thinking: boolean;
+};
+/**
+ * Interleave messages and tool calls, ordered by insertion time.
+ *
+ * Each tool call belongs immediately after its anchor message
+ * (`afterMessageId`); tool calls whose anchor slid out of the retained window —
+ * or that were inserted before any message existed — come first, since there is
+ * nothing left for them to follow.
+ */
+export declare function interleave(messages: readonly ChatMessage[], toolCalls: readonly ToolCallInfo[]): ConversationItem[];
+/**
+ * Subscribe to the conversation: the interleaved exchange, the streaming
+ * utterance, the live transcript and the thinking rule — with no markup.
+ *
+ * Must be used inside the provider `mountClient()` installs.
+ *
+ * @example A custom bubble, keeping every rule `<MessageList>` knows
+ * ```tsx
+ * import { useConversation } from "@alexkroman1/aai-ui";
+ *
+ * function Transcript() {
+ *   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>
+ *         ),
+ *       )}
+ *       {streaming !== null && <p data-role="assistant">{streaming}</p>}
+ *       {transcript.speaking && <p data-role="user">{transcript.text}</p>}
+ *       {thinking && <p>…</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns See {@link UseConversationResult}.
+ *
+ * @public
+ */
+export declare function useConversation(): UseConversationResult;

package/dist/use-copy.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Copy-to-clipboard with a per-item flash on the button that triggered it.
+ *
+ * Anywhere a UI hands the reader a string to paste somewhere else — a session
+ * URL, a webhook, a `curl` line — the button wants the same three things, and
+ * two of them are easy to get wrong:
+ *
+ * - The flash is keyed by the copied TEXT, so one row's "Copied" does not light
+ *   up every button beside it.
+ * - A FAILED write is reported rather than swallowed. There is no clipboard in
+ *   an insecure context, and a browser may refuse the permission; a `catch`
+ *   that does nothing leaves a button that visibly does nothing when clicked,
+ *   which reads as a broken page rather than as a blocked capability.
+ * - The single-timer / clear-on-unmount half is {@link useFlash}'s.
+ */
+/**
+ * What {@link useCopy} hands back — the click handler and the two readings a
+ * button needs off one shared flash.
+ *
+ * @public
+ */
+export type UseCopyResult = {
+    /** Copy `text`, flashing the button that owns it. */
+    copy: (text: string) => void;
+    /**
+     * The button label for `text` — `idle` until it is clicked, then `"Copied"`
+     * or `"Failed"` for the length of the flash.
+     *
+     * Only the idle word is the caller's: it is the button's NAME (`"Copy"`,
+     * `"UI"`, `"Webhook URL"`), where the other two are the OUTCOME and are the
+     * one bit of state a reader can see. A caller wanting other words for those
+     * reads {@link UseCopyResult.didCopy} and writes its own.
+     */
+    label: (text: string, idle?: string) => string;
+    /** True when `text` was the last thing copied, successfully. */
+    didCopy: (text: string) => boolean;
+};
+/**
+ * One copier for a group of copy buttons.
+ *
+ * @remarks
+ * Call it ONCE per group and pass the {@link UseCopyResult} down, rather than once per
+ * button: the flash is shared, so clicking a second row clears the first row's
+ * "Copied" — which is what makes a list of URLs readable, since two rows
+ * claiming to be on the clipboard is a lie about one of them.
+ *
+ * A chip whose idle text is its own name rather than the word "Copy" passes
+ * that name to {@link UseCopyResult.label}; the two outcome words are fixed, for the
+ * reason that member's own doc gives.
+ *
+ * @example
+ * ```tsx
+ * import { useCopy } from "@alexkroman1/aai-ui";
+ *
+ * function UrlList({ urls }: { urls: readonly string[] }) {
+ *   const copier = useCopy();
+ *   return (
+ *     <ul>
+ *       {urls.map((url) => (
+ *         <li key={url}>
+ *           <code>{url}</code>
+ *           <button type="button" onClick={() => copier.copy(url)}>
+ *             {copier.label(url)}
+ *           </button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useCopy(): UseCopyResult;

package/dist/use-download-url.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `useDownloadUrl` — an upload id a run produced, as something `<audio>`,
+ * `<img>` or `<a download>` will accept.
+ *
+ * `api.download(id)` resolves a `Blob`, and it has to: the byte route takes the
+ * same bearer every workflow route does, and neither `<audio src>` nor
+ * `<a href>` can send one. So every page that plays back what a run WROTE ends
+ * up at the same four lines — `download` → `createObjectURL` → state — and the
+ * two that are really the point are the two the four lines are wrapped in:
+ *
+ * - **`URL.revokeObjectURL` on cleanup.** An object URL pins its blob for the
+ *   life of the DOCUMENT. Miss it and every completed run's audio stays resident
+ *   until the tab closes, which on a page people run all day is a leak measured
+ *   in the size of the files.
+ * - **A `cancelled` flag.** A second run settling while the first download is
+ *   still in flight otherwise sets state from the stale one, and the page plays
+ *   the previous run's audio under the current run's transcript — a wrong answer
+ *   that looks like a right one.
+ *
+ * Two templates had written this hook, identically, doc paragraph included, and
+ * `aai-ui` exported no download helper at all. Both also faked `pending` by
+ * checking `url === undefined && error === undefined`, which reads "idle" and
+ * "downloading" as the same thing — so this reports it.
+ */
+import type { WorkflowApi } from "./workflow-client.ts";
+/** Options for {@link useDownloadUrl}. */
+export type UseDownloadUrlOptions = {
+    /** The client to read the bytes with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+};
+/**
+ * What {@link useDownloadUrl} reports.
+ *
+ * @public
+ */
+export type UseDownloadUrlResult = {
+    /**
+     * An object URL for the stored bytes, once they are here. Valid until the id
+     * changes or the component unmounts — do not stash it anywhere that outlives
+     * the render that read it.
+     */
+    url?: string;
+    /** The read's failure, as the agent's own sentence where it gave one. */
+    error?: string;
+    /**
+     * True while the bytes are on their way.
+     *
+     * Its own field rather than "neither `url` nor `error`", which cannot tell a
+     * download in flight from no id to download — the two states a page most
+     * wants to render differently (a spinner, and nothing at all).
+     */
+    pending: boolean;
+};
+/**
+ * Read an upload's bytes and hand back a URL a DOM element can use.
+ *
+ * @param uploadId - The id a completed run reported, or `undefined` before one
+ *   exists — which is what a page passes straight through while it waits, and
+ *   reports as idle rather than pending.
+ * @param options - See {@link UseDownloadUrlOptions}.
+ * @returns See {@link UseDownloadUrlResult}.
+ *
+ * @example
+ * ```tsx no-check
+ * import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+ * import type { spokenSummary } from "./agent.ts";
+ *
+ * function Playback() {
+ *   const { run } = useWorkflowSubmit<typeof spokenSummary>("spokenSummary");
+ *   const output = run?.status === "completed" ? run.output : undefined;
+ *   const audio = useDownloadUrl(output?.audio);
+ *   if (audio.pending) return <p>Fetching audio…</p>;
+ *   if (audio.error !== undefined) return <p role="alert">{audio.error}</p>;
+ *   return audio.url === undefined ? null : (
+ *     <a href={audio.url} download="summary.mp3">
+ *       Download
+ *     </a>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useDownloadUrl(uploadId: string | undefined, options?: UseDownloadUrlOptions): UseDownloadUrlResult;

package/dist/use-flash.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A value that shows itself for a moment and then goes away.
+ *
+ * The "Copied" on a copy button, the "Saved" under an editor, the "Sent" on a
+ * submit. There were three hand-rolled copies of this — two in the studio
+ * front-end and one inside this package's own URL chips — each with the same
+ * 1500ms and the same comment explaining the same two things the naive version
+ * gets wrong. It is one primitive now, and it is PUBLIC because a custom chrome
+ * is exactly the caller that needs it: the moment a client renders its own copy
+ * button or its own save note, it is writing the timer again.
+ */
+/**
+ * What {@link useFlash} hands back.
+ *
+ * @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.
+ *
+ * @public
+ */
+export type UseFlashResult<T> = {
+    /** What is being shown right now, or `null` between flashes. */
+    readonly value: T | null;
+    /** Show `value` for the hook's duration, replacing any flash already up. */
+    readonly flash: (value: T) => void;
+};
+/**
+ * A transient value: set it, and it clears itself after `ms`.
+ *
+ * @remarks
+ * The two things this holds that a `useState` plus a `setTimeout` at the call
+ * site reliably gets wrong:
+ *
+ * - **At most ONE live timer.** A second flash while the first is still up
+ *   re-arms rather than stacking, so the new value gets its full window
+ *   instead of being cleared early by the previous click's timeout.
+ * - **Nothing fires after unmount.** The timer is cleared on teardown, so a
+ *   chip clicked and then scrolled out of the tree does not `setState` on a
+ *   component React has already thrown away.
+ *
+ * @example
+ * ```tsx
+ * import { useFlash } from "@alexkroman1/aai-ui";
+ *
+ * function SaveNote({ onSave }: { onSave: () => Promise<void> }) {
+ *   const { value: note, flash } = useFlash<string>();
+ *   return (
+ *     <button type="button" onClick={() => void onSave().then(() => flash("Saved"))}>
+ *       {note ?? "Save"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @typeParam T - What is being flashed.
+ * @param ms - How long the value stays up. Defaults to 1500ms, which is what
+ *   every caller wanted: long enough to read a word, short enough that the
+ *   control is back to its real label before the reader looks again.
+ *
+ * @public
+ */
+export declare function useFlash<T>(ms?: number): UseFlashResult<T>;

package/dist/use-inbox.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `useInbox()` — the session's client, reachable after the session has ended.
+ *
+ * A tool that starts a durable run (a reminder, a research job) hands the run
+ * `sessionClientId(ctx)`, and the run's `stepNotifyClient` delivers to whoever
+ * holds that client's `WS /inbox` socket when it is done — usually long after
+ * the voice session closed. This hook holds that socket for the page, under the
+ * SESSION's own client id (`mountClient({ client: "auto" })` is the one-word
+ * way to have one) and this tab's holder id, and plays each notice aloud.
+ *
+ * Three decisions a hand-written copy got wrong or had to rediscover:
+ *
+ * - **Busy by default while the session is running**, so a reminder never talks
+ *   over a reply: the page answers `busy`, the step's retry brings the notice
+ *   back, and it plays once the call is over. Override with `busy`.
+ * - **Callbacks are read at call time**, not captured at mount: a new `onNotice`
+ *   every render does not reconnect the socket. Only `events` does, because it
+ *   is part of the socket's URL.
+ * - **Playback is unlocked by the page's first gesture** (`notice-player.ts`):
+ *   the autoplay policy silences a context created without one, and a notice
+ *   arrives hours after any click.
+ * - **One tab plays: the one last touched.** Every tab is a holder of its own,
+ *   and the inbox sends a notice to each, so nine open tabs played it nine
+ *   times a few milliseconds apart — heard as one choppy, phasing voice. A
+ *   gesture claims the client's player in `localStorage`, which every tab of
+ *   the origin shares synchronously; the others still ack and still call
+ *   `onNotice`, they just stay quiet. A claimant that closes gives the claim
+ *   back, and with no claim every unlocked tab plays, as before.
+ *
+ * @module
+ */
+import type { InboxEvent, InboxNotice } from "./inbox-protocol.ts";
+/**
+ * Options for {@link useInbox}.
+ *
+ * @public
+ */
+export type UseInboxOptions = {
+    /**
+     * A notice arrived whole — once per delivery, after playback has started
+     * (when `play` is on). Log it, show it, or play it yourself with `play: false`.
+     */
+    onNotice?: ((notice: InboxNotice) => void) | undefined;
+    /**
+     * A frame of the client's live conversation — every session of this client,
+     * this page's own included (compare `sessionId` with `useSessionId()` to skip
+     * it). Giving one asks for the feed, unless `events` says otherwise.
+     */
+    onEvent?: ((event: InboxEvent) => void) | undefined;
+    /**
+     * Whether to refuse a notice for now (`busy`; it comes back later). Default:
+     * the session is running — connecting, listening, thinking or speaking.
+     */
+    busy?: (() => boolean) | undefined;
+    /**
+     * Play each notice's audio (PCM16LE mono, 16 kHz) through built-in playback.
+     * Default `true`.
+     */
+    play?: boolean | undefined;
+    /** Ask for the client's live conversation (`?events=1`). Default: whether `onEvent` is set. */
+    events?: boolean | undefined;
+};
+/**
+ * What {@link useInbox} returns.
+ *
+ * @public
+ */
+export type UseInboxResult = {
+    /** Whether the inbox socket is open now. */
+    readonly connected: boolean;
+    /** Silence a notice that is playing — e.g. when the user starts talking. */
+    stopPlayback(): void;
+};
+/**
+ * Hold this session's `WS /inbox` socket open for the life of the component,
+ * and play what arrives — see the module doc.
+ *
+ * The session needs a client id: `mountClient({ client: "auto" })`, or a
+ * `client` of your own. With none, no socket is opened (`connected` stays
+ * `false`) until the session's `client` getter answers one.
+ *
+ * @example
+ * ```tsx
+ * import { mountClient, useInbox } from "@alexkroman1/aai-ui";
+ *
+ * function App() {
+ *   const { connected } = useInbox({
+ *     onNotice: (notice) => console.log(notice.event, notice.data),
+ *   });
+ *   return <p>{connected ? "Reminders on" : "Reminders offline"}</p>;
+ * }
+ *
+ * mountClient({ client: "auto", component: App });
+ * ```
+ *
+ * @param options - What to do with a notice or a live event; see {@link UseInboxOptions}.
+ * @returns Whether the socket is open, and a way to stop playback.
+ *
+ * @public
+ */
+export declare function useInbox(options?: UseInboxOptions): UseInboxResult;