@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/components/workflow-pending-note.d.ts

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+import type { WorkflowRun } from "../workflow-client.ts";
+/**
+ * Props for {@link WorkflowPendingNote}.
+ *
+ * @public
+ */
+export type WorkflowPendingNoteProps = {
+    /**
+     * The submission the page is rendering — `useWorkflowSubmit`'s or
+     * `useWorkflowStream`'s result, or any object carrying these three fields.
+     * Nothing renders while `pending` is false.
+     */
+    submission: {
+        readonly pending: boolean;
+        readonly startedHere: boolean;
+        readonly run: WorkflowRun | undefined;
+    };
+    /**
+     * What the run produces, as the noun the sentences name: `"draft"`,
+     * `"summary"`, `"transcript"`. Default `"run"`.
+     */
+    subject?: string | undefined;
+    /**
+     * Where the key that finds the run again lives. `"tab"` (the default) is
+     * `useWorkflowSubmit`'s own `sessionStorage` key; `"browser"` is a page that
+     * passed `useRunKey({ storage: "local" })`, whose runs any tab on this browser
+     * can find — so the sentence says "this browser" and stops promising that
+     * closing the tab loses anything.
+     */
+    scope?: "tab" | "browser" | undefined;
+    /**
+     * ADDED to the note's own `text-sm opacity-70` rather than replacing it.
+     * There is no `tailwind-merge` in this package, so a class that CONFLICTS with
+     * a base one is not reliably the winner.
+     */
+    className?: string | undefined;
+};
+/**
+ * The one sentence a page says while a run is in flight — three situations,
+ * one line each — as a muted line under the form, and nothing otherwise.
+ *
+ * Six template pages had each written the function under this, byte-identical
+ * in control flow and different only in the noun, under a doc arguing the same
+ * two things. Both survive here, once:
+ *
+ * - **The reload case gets its own words.** `!startedHere && run` is a run in
+ *   front of somebody who did not press anything — a reload, or another tab on
+ *   the same key — and they are owed an explanation for work appearing, plus
+ *   the line that stops them starting it again. The sentence a page reaches for
+ *   instead ("you can close this tab") was true about the RUN and false about
+ *   the page for as long as a reload could not find its run.
+ * - **The lookup is a state, not an absence.** `!startedHere && !run` is the
+ *   stretch on a reload where the key is being resolved and an empty form would
+ *   read as "nothing is happening". It is the same length as the request.
+ *
+ * The render site had drifted too — three pages muted the line and two did not
+ * — so the typography is the component's, in the same `text-sm opacity-70`
+ * every other muted line on these pages uses.
+ *
+ * `startedHere`, `run` and `pending` are what {@link WorkflowSubmission}
+ * reports, which is why the prop is the submission itself rather than three
+ * booleans a page would re-derive. A page with a FOURTH situation — a run that a
+ * reload does not recover but ENDS, as `transcription-workflow`'s streaming
+ * flow has — writes its own sentence, and that template is the one doing so.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowSubmit, WorkflowPendingNote } from "@alexkroman1/aai-ui";
+ *
+ * function App() {
+ *   const submission = useWorkflowSubmit("redline");
+ *   return <WorkflowPendingNote submission={submission} subject="draft" />;
+ * }
+ * ```
+ *
+ * @param props - See {@link WorkflowPendingNoteProps}.
+ *
+ * @public
+ */
+export declare function WorkflowPendingNote({ submission, subject, scope, className, }: WorkflowPendingNoteProps): ReactNode;

package/dist/components/workflow-progress.d.ts

@@ -0,0 +1,81 @@
+import { type ReactNode } from "react";
+import type { WorkflowApi } from "../workflow-client.ts";
+/**
+ * What a run has said so far, rendered.
+ *
+ * The complement of a status line, and the reason both exist: a run is
+ * `running` for its whole life, so a one-round job and a ten-round one look
+ * identical while they happen. These lines come from the run itself (`stepReport()`
+ * in a `"use step"` body), which is the only channel a workflow has before it
+ * produces an output.
+ *
+ * Four rules are baked in, and they are why this is a component rather than
+ * three lines each page writes for itself — the two templates that had written
+ * it had written three of them, comments included:
+ *
+ * - **It renders nothing until there is something to render.** `supported` is
+ *   what keeps this from being an empty box forever on an agent deployed before
+ *   progress streams existed: "wrote nothing yet" and "serves no stream" are
+ *   indistinguishable from the chunk list alone.
+ * - **The lines are TEXT, not elements.** They are append-only and two rounds
+ *   legitimately produce identical text, so there is no stable per-line key to
+ *   give React. Joining sidesteps the question instead of suppressing the lint
+ *   rule that asks it.
+ * - **They REPLAY.** Chunks are retained with the run, so a reload mid-run —
+ *   or opening a finished run tomorrow — shows how it got there rather than an
+ *   empty box. That is `useWorkflowProgress`'s doing; this is what makes it
+ *   visible.
+ * - **They are ANNOUNCED**, for the reason the first paragraph gives: this is
+ *   the only channel a run has before it produces an output, and a `<pre>` that
+ *   grows is a silent one. A screen-reader user pressing "Digest" got nothing
+ *   between the click and a terminal state minutes later — no "fetching", no
+ *   "summarising", no evidence the button did anything. See `role="log"` below.
+ *   The six pages that render this pass only `className`, so no template could
+ *   have fixed it locally; that is what makes it this component's job.
+ *
+ * @example
+ * ```tsx
+ * import { WorkflowProgress } from "@alexkroman1/aai-ui";
+ *
+ * function RunPanel({ runId }: { runId: string }) {
+ *   return <WorkflowProgress runId={runId} />;
+ * }
+ * ```
+ *
+ * @param props - Progress-log props.
+ *
+ * @public
+ */
+export declare function WorkflowProgress({ runId, api, className, placeholder, lines, }: {
+    /**
+     * The run to read. `undefined` renders nothing, so a page may pass its state
+     * straight through before a run exists.
+     */
+    runId?: string | undefined;
+    /**
+     * The workflow API client, when the page holds its own. Defaults to the
+     * lazily-built one every workflow hook shares.
+     */
+    api?: WorkflowApi | undefined;
+    /**
+     * **Replaces** the default classes rather than extending them, so a custom
+     * chrome is not fighting a default it did not ask for.
+     */
+    className?: string | undefined;
+    /**
+     * Rendered instead of nothing while the run has said nothing yet — for a
+     * page that would otherwise reflow when the first line lands.
+     */
+    placeholder?: ReactNode | undefined;
+    /**
+     * How many of the newest lines to show. Undefined (the default) shows the
+     * whole log; `1` is the newest line only.
+     *
+     * A run's narration is append-only and unbounded, so a page with a fixed slot
+     * for it — a status strip, a card footer — wants a window rather than a log.
+     * `0` renders the placeholder, which is the consistent reading of "show none"
+     * and the one that keeps a computed `lines` from silently rendering
+     * everything.
+     */
+    lines?: number | undefined;
+}): ReactNode;

package/dist/components/workflow-run-error.d.ts

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+import type { WorkflowRun } from "../workflow-client.ts";
+/**
+ * Props for {@link WorkflowRunError}.
+ *
+ * @public
+ */
+export type WorkflowRunErrorProps = {
+    /** The run the page is following. Nothing renders unless it has FAILED. */
+    run: WorkflowRun | undefined;
+    /**
+     * ADDED to the alert's own `text-red-600` rather than replacing it. There is
+     * no `tailwind-merge` in this package, so a class that CONFLICTS with a base
+     * one is not reliably the winner.
+     */
+    className?: string | undefined;
+};
+/**
+ * The announced line for a run that failed: its error, or nothing at all while
+ * the run is anything else.
+ *
+ * Six workflow pages had written this paragraph by hand, and the one thing that
+ * mattered about it was the part a reviewer cannot see is missing:
+ * `role="alert"`. A run fails minutes after the reader looked away — days, for
+ * a scheduled one — and `<Form>` announces only the SUBMIT error, so without
+ * the role a screen reader is never told the outcome it waited for arrived.
+ * Three of the six also disagreed on the sentence ("That one failed", "That run
+ * failed", the bare message), which is the drift a component ends.
+ *
+ * Discriminated on `status`, so `error` is reachable without a cast — the
+ * reason {@link WorkflowRun} is a union rather than a flat object with optional
+ * fields.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowSubmit, WorkflowRunError } from "@alexkroman1/aai-ui";
+ *
+ * function App() {
+ *   const { run } = useWorkflowSubmit("digest");
+ *   return <WorkflowRunError run={run} />;
+ * }
+ * ```
+ *
+ * @param props - See {@link WorkflowRunErrorProps}.
+ *
+ * @public
+ */
+export declare function WorkflowRunError({ run, className }: WorkflowRunErrorProps): ReactNode;

package/dist/components/workflow-run-panel.d.ts

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+import type { WorkflowRunStatus } from "../workflow-client.ts";
+import { type WorkflowApi, type WorkflowRun } from "../workflow-client.ts";
+/**
+ * Props of {@link WorkflowRunPanel}.
+ *
+ * @typeParam O - The run's output type; `run.output` narrows to it in the
+ * completed slot.
+ *
+ * @public
+ */
+export type WorkflowRunPanelProps<O> = {
+    /** The run to show. Nothing here handles `undefined` — a page renders the panel once it has one. */
+    run: WorkflowRun<O>;
+    /**
+     * The status lines this page has a better word for — `{ running:
+     * "Writing…" }`. The rest come from {@link WORKFLOW_STATUS_LABELS}.
+     */
+    statusLabels?: Partial<Readonly<Record<WorkflowRunStatus, string>>> | undefined;
+    /** Renders a Clear button in the header that calls this. Absent, no button. */
+    onClear?: (() => void) | undefined;
+    /** The workflow API client, when the page holds its own. */
+    api?: WorkflowApi | undefined;
+    /**
+     * Rendered beneath the narration while the run is NOT terminal — a live
+     * transcript, a partial result. Nothing once it settles.
+     */
+    live?: ReactNode | undefined;
+    /**
+     * The completed body: what the run PRODUCED. A function receives the typed
+     * output; a node is rendered as it is. Either appears only while
+     * `run.status === "completed"`.
+     */
+    children?: ReactNode | ((output: O) => ReactNode) | undefined;
+    /** Additional CSS class names for the wrapping `<section>`, appended to its own. */
+    className?: string | undefined;
+};
+/**
+ * The bordered panel a workflow page shows one run in: a status line, a Clear
+ * button, the run's own narration, the live slot while it works, the completed
+ * body once it has, and the announced error if it failed.
+ *
+ * Two pages had written this shell — `document-redline-workflow` and `transcription-workflow` —
+ * with the same header, the same `text-xs underline` Clear, the same
+ * {@link WorkflowProgress} under it, the same `run.status === "completed"`
+ * discrimination above the same {@link WorkflowRunError}, and each spread
+ * {@link WORKFLOW_STATUS_LABELS} into a local map to change `running`. The
+ * ORDER is the part worth owning: the narration is the complement of the status
+ * line (a run is `running` for its whole life, so a one-round job and a
+ * ten-round one look identical without it), and the error goes last because it
+ * is the outcome the reader waited minutes for.
+ *
+ * `children` is discriminated on the run for the caller, so the body reads
+ * `run.output` typed, without a cast and without the page repeating the guard —
+ * the reason {@link WorkflowRun} is a union rather than a flat object with
+ * optional fields.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowRun, WorkflowRunPanel } from "@alexkroman1/aai-ui";
+ *
+ * // `useWorkflowRun<R>` is where a page names the output's shape; a page that
+ * // started the run itself has it typed already, from `useWorkflowSubmit<D>`.
+ * function Panel({ runId, onClear }: { runId: string; onClear: () => void }) {
+ *   const { run } = useWorkflowRun<{ draft: string }>(runId);
+ *   if (!run) return null;
+ *   return (
+ *     <WorkflowRunPanel run={run} statusLabels={{ running: "Writing…" }} onClear={onClear}>
+ *       {(output) => <article className="whitespace-pre-wrap">{output.draft}</article>}
+ *     </WorkflowRunPanel>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link WorkflowRunPanelProps}.
+ *
+ * @public
+ */
+export declare function WorkflowRunPanel<O = unknown>({ run, statusLabels, onClear, api, live, children, className, }: WorkflowRunPanelProps<O>): ReactNode;

package/dist/context.d.ts

@@ -0,0 +1,288 @@
+import { type ReactNode } from "react";
+import type { BrowserSession, SendTextOptions, SessionSnapshot } from "./session/index.ts";
+import type { AgentState, ClientTheme, SessionError } from "./types.ts";
+/**
+ * Provides the {@link BrowserSession} the session hooks read. `mountClient()`
+ * installs it automatically; a custom tree only needs it when bypassing
+ * `mountClient()` and mounting React itself.
+ *
+ * @internal
+ */
+export declare function SessionProvider({ value, children, }: {
+    value: BrowserSession;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<BrowserSession | null>>;
+/**
+ * The session's control methods, and nothing else — what a `client.tsx` may
+ * legitimately CALL on a session, as against what it may read.
+ *
+ * Declared once and merged into {@link Session} rather than written out at both
+ * places: the two lists have to be the same list, and a member added to one and
+ * not the other is a hook that cannot do what `useSession()` can.
+ *
+ * DECLARED here rather than picked out of {@link BrowserSession}: that handle is
+ * sealed and grows, and a `Pick` made every member it gained a candidate for
+ * this list without anyone deciding. Push-to-talk is the case in point — its
+ * three edges are `session.userTurn`, reached through `usePushToTalk`, and not
+ * actions every chrome is handed. `createBrowserSession` is what keeps each of
+ * these assignable from the session's own methods.
+ *
+ * @public
+ */
+export type SessionActions = {
+    /** Start the call for the first time — see {@link BrowserSession.start}. */
+    start(): void;
+    /** Cancel the current agent turn and discard in-flight TTS audio. */
+    cancel(): void;
+    /** Send a typed user turn, answered as if spoken — see {@link BrowserSession.sendText}. */
+    sendText(text: string, options?: SendTextOptions): void;
+    /** Mute or unmute the mic without dropping the session — see {@link BrowserSession.setMicMuted}. */
+    setMicMuted(muted: boolean): void;
+    /** Clear messages, transcripts and error state, keeping the connection. */
+    resetState(): void;
+    /** Clear state and reopen the connection — the same session id. */
+    reset(): void;
+    /** End the call and begin a fresh one — see {@link BrowserSession.restart}. */
+    restart(): void;
+    /** Continue an earlier session by its id — see {@link BrowserSession.resume}. */
+    resume(sessionId: string): void;
+    /** Close the WebSocket and release all audio resources. */
+    disconnect(): void;
+    /** Toggle between connected and disconnected (after `start()`). */
+    toggle(): void;
+    /** End the call and return to the not-started state — see {@link BrowserSession.end}. */
+    end(): void;
+};
+/**
+ * What {@link useSession} returns: the live {@link SessionSnapshot} fields
+ * (`state`, `messages`, `toolCalls`, `agentState`, live transcripts, `error`,
+ * `apiUrl`, `started`/`running`/`recording`, …) merged with the session's
+ * control methods (`start`, `toggle`, `reset`, `restart`, `resume`, `resetState`,
+ * `disconnect`, `cancel`, `end`, `sendText`, `setMicMuted`).
+ *
+ * `sendText(text)` is the one input besides the microphone: a typed turn the
+ * agent answers aloud, as if it had been spoken.
+ *
+ * @public
+ */
+export type Session = SessionSnapshot & SessionActions;
+/**
+ * Return the raw {@link BrowserSession} from context without subscribing to
+ * snapshot changes. Useful for accessing stable methods (`start`, `toggle`,
+ * `reset`, …) from components that select narrow state via
+ * {@link useSessionSelector}.
+ *
+ * Not part of the package's public export surface — internal to aai-ui
+ * components.
+ */
+export declare function useSessionCore(): BrowserSession;
+/** The session from context, or `null` outside the provider (`useRoute` on a `mountPage()` page). */
+export declare function useOptionalSessionCore(): BrowserSession | null;
+/**
+ * The session's control methods — `start`, `cancel`, `sendText`,
+ * `setMicMuted`, `resetState`, `reset`, `restart`, `resume`, `disconnect`,
+ * `toggle`, `end` — with **no snapshot subscription**.
+ * Push-to-talk is not among them: that is `usePushToTalk`.
+ *
+ * This is the narrow half of {@link useSession}, and it is the half a custom
+ * chrome could not reach. `<Controls>` and `<StartScreen>` in this package pair
+ * a one-field `useSessionSelector` with this package's own `useSessionCore`
+ * (`context.ts`, unpublished); a `client.tsx`
+ * could not, because that hook is not published — so a footer needing `start`
+ * and `toggle` held a WHOLE-SNAPSHOT `useSession()`, and `session/browser-session.ts`
+ * rebuilds the snapshot object on every change. Measured consequence: four
+ * components across three templates re-rendered on every STT partial and every
+ * streaming delta, in files whose every other component is narrowly subscribed
+ * on purpose. One of them (`text-adventure-agent`'s `TitleScreen`) reads nothing
+ * from the snapshot at all and subscribes to all of it for `session.start`.
+ *
+ * **Why publishing this does not reopen what `/internal` closed.**
+ * `useSessionCore` hands back the STORE — `subscribe`, `getSnapshot`,
+ * `connect`, `Symbol.dispose` — which is the framework's own plumbing, the same
+ * category as the providers and `buildAgentUrl` that live on
+ * `@alexkroman1/aai-ui/internal`. A client that holds it can subscribe out of
+ * band of React, dial a socket the mount did not, and dispose the session under
+ * the tree that is rendering it. What comes back from here is the SAME
+ * methods `useSession()` already publishes on its result, built into a fresh
+ * object rather than passed through, so the store is not reachable from it.
+ * There is no new capability here — only the existing one without the
+ * subscription tax.
+ *
+ * Identity-stable per core, so it is safe in a dependency array and in a
+ * `memo()` child's props: the methods are closures created once by
+ * `createBrowserSession`, and the object wrapping them is memoized on the core.
+ *
+ * Throws outside the provider `mountClient()` installs, like every session hook.
+ *
+ * @example A footer that acts on the session without re-rendering with it
+ * ```tsx
+ * import { useSessionActions, useSessionSelector } from "@alexkroman1/aai-ui";
+ *
+ * function Footer() {
+ *   // Two narrow subscriptions and no snapshot read: this row re-renders when
+ *   // `running` flips, and not on every transcript delta.
+ *   const running = useSessionSelector((s) => s.running);
+ *   const { toggle, end } = useSessionActions();
+ *   return (
+ *     <>
+ *       <button onClick={toggle}>{running ? "Pause" : "Resume"}</button>
+ *       <button onClick={end}>Hang up</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @returns The control methods — see {@link SessionActions}.
+ *
+ * @public
+ */
+export declare function useSessionActions(): SessionActions;
+/**
+ * Return the live {@link Session}: the current snapshot fields plus the
+ * control methods (`start`, `toggle`, `reset`, `resetState`, `disconnect`,
+ * `cancel`, `end`).
+ *
+ * Throws if used outside the provider `mountClient()` installs (the error names
+ * `<SessionProvider>` — you only mount that yourself when bypassing
+ * `mountClient()`). Re-renders the component on *every* snapshot change; for a
+ * component that reads one field, prefer {@link useSessionSelector} for a
+ * targeted subscription.
+ *
+ * @example
+ * ```tsx
+ * import { useSession } from "@alexkroman1/aai-ui";
+ *
+ * function Controls() {
+ *   const session = useSession();
+ *   if (!session.started) return <button onClick={session.start}>Start</button>;
+ *   return <button onClick={session.toggle}>{session.running ? "Pause" : "Resume"}</button>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useSession(): Session;
+/**
+ * Subscribe to a narrow slice of the session snapshot.
+ *
+ * Unlike {@link useSession} — which re-renders the component on *every*
+ * snapshot change — this only triggers a re-render when the selected value
+ * changes (per `isEqual`, default `Object.is`). Use it for components that
+ * read a single field, e.g. `useSessionSelector((s) => s.running)`.
+ *
+ * The selector must be pure. It may run on every snapshot change, so keep it
+ * cheap; when it returns a derived object, pass a custom `isEqual` to avoid
+ * re-renders on referentially-new-but-equal results.
+ *
+ * @example
+ * ```tsx
+ * import { useSessionSelector } from "@alexkroman1/aai-ui";
+ *
+ * // Re-renders when `running` flips, and on nothing else — not on every
+ * // transcript delta the way `useSession()` would.
+ * function MicDot() {
+ *   const running = useSessionSelector((snapshot) => snapshot.running);
+ *   return <span>{running ? "●" : "○"}</span>;
+ * }
+ * ```
+ *
+ * @param selector - Reads the slice out of the snapshot. Must be pure.
+ * @param isEqual - Compares two selected values. Defaults to `Object.is`.
+ * @returns The selected slice.
+ *
+ * @public
+ */
+export declare function useSessionSelector<T>(selector: (snapshot: SessionSnapshot) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * The agent's live {@link AgentState} — `disconnected`, `connecting`, `ready`,
+ * `listening`, `thinking`, `speaking`, `error` — on its own narrow
+ * subscription.
+ *
+ * `useSessionSelector((s) => s.state)` spelled once. It is one of exactly two
+ * snapshot fields that more than one custom chrome ever selects (the other is
+ * {@link useSessionError}), and it had been written inline at eight sites —
+ * including inside this package and, worse, in `ConsoleShell`'s own `@example`,
+ * which taught the inline form to everyone who read it.
+ *
+ * **Named `useSessionStatus`, not `useSessionState`.** `useAgentState` is the
+ * SLOT hook — the agent's own synced application state, whatever a
+ * `sessionSlot()` projects — and `AgentState` here is the phase of the CALL.
+ * Two different concepts one letter apart, so the shorter-sounding name is the
+ * one deliberately not taken.
+ *
+ * Pair it with {@link AGENT_STATE_LABELS} for a rendered word; the raw member
+ * is a wire value, not a label.
+ *
+ * @example
+ * ```tsx
+ * import { AGENT_STATE_LABELS, useSessionStatus } from "@alexkroman1/aai-ui";
+ *
+ * function StatusDot() {
+ *   const status = useSessionStatus();
+ *   return <span data-state={status}>{AGENT_STATE_LABELS[status]}</span>;
+ * }
+ * ```
+ *
+ * @returns The current agent state.
+ *
+ * @public
+ */
+export declare function useSessionStatus(): AgentState;
+/**
+ * The session's current {@link SessionError}, or `null` when there is none, on
+ * its own narrow subscription.
+ *
+ * The other half of {@link useSessionStatus} — the second of the two fields a
+ * custom chrome reads over and over, and the one whose absence is invisible:
+ * per the `fatalError` latch in `session/browser-session.ts` the error is the ONLY
+ * remaining signal that a session died, since the state beside it goes back to
+ * reading like a live one.
+ *
+ * A chrome rendering it owes `role="alert"` — which is what
+ * {@link SessionErrorBanner} is for, and why reaching for that beats reaching
+ * for this.
+ *
+ * @returns The current error, or `null`.
+ *
+ * @public
+ */
+export declare function useSessionError(): SessionError | null;
+/**
+ * Provides the theme the components read via `useTheme`. `mountClient()` installs
+ * it automatically (from `ClientConfig.theme`); a custom tree only needs it
+ * when bypassing `mountClient()` and mounting React itself.
+ *
+ * @internal
+ */
+export declare function ThemeProvider({ value, children, }: {
+    value?: ClientTheme | undefined;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Required<ClientTheme>>>;
+/**
+ * Read the resolved theme (every {@link ClientTheme} field filled with its
+ * default) from the nearest theme context. Returns the default theme when no
+ * provider is present, so components can call it unconditionally.
+ *
+ * This is how a custom component stays on the agent's palette: a
+ * `mountClient({ theme })` override reaches it here, where a hardcoded colour or a
+ * Tailwind class cannot see it.
+ *
+ * @example
+ * ```tsx
+ * import { useTheme } from "@alexkroman1/aai-ui";
+ *
+ * function Total({ amount }: { amount: string }) {
+ *   const theme = useTheme();
+ *   return (
+ *     <strong style={{ color: theme.primary, background: theme.surface }}>
+ *       {amount}
+ *     </strong>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Every {@link ClientTheme} field, filled in.
+ *
+ * @public
+ */
+export declare function useTheme(): Required<ClientTheme>;