@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/client-dir.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Filesystem location of the prebuilt default client — **Node only**.
+ *
+ * Its own subpath rather than the root barrel because it imports `node:module`
+ * and `node:path`: the root export is browser code, and pulling Node builtins
+ * into it would break every bundler that consumes this package.
+ *
+ * This exists because locating the directory is otherwise three lines of module
+ * archaeology plus knowledge of an internal `dist/` layout, and everybody
+ * serving the default UI has to write them — `aai-cli`'s dev server had its own
+ * copy, as did every self-hosted example. Three places that would all silently
+ * serve nothing if the build output moved.
+ *
+ * @module client-dir
+ */
+/**
+ * Absolute path to the prebuilt browser client's static files — pass it to
+ * `createServerForRuntime`/`createAgentServer` as `clientDir`.
+ *
+ * A function, not a constant: resolution touches the module graph and throws
+ * when the package is missing, and a module-level constant would move that
+ * failure to import time — where it fires for callers that never wanted the
+ * client, and before any of their own error handling is in place.
+ *
+ * Resolved through this package's own `package.json` rather than relative to
+ * this module, so it lands in the same place whether the caller resolved the
+ * `@dev/source` TypeScript entry or the compiled one under `dist/`.
+ *
+ * @example
+ * ```ts
+ * import { agent } from "@alexkroman1/aai";
+ * import { createAgentServer } from "@alexkroman1/aai-runtime";
+ * import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+ *
+ * const server = createAgentServer({
+ *   agent: agent({ name: "Support" }),
+ *   env: {},
+ *   clientDir: defaultClientDir(),
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function defaultClientDir(): string;

package/dist/client-dir.js

@@ -0,0 +1,58 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+//#region src/client-dir.ts
+/**
+* Filesystem location of the prebuilt default client — **Node only**.
+*
+* Its own subpath rather than the root barrel because it imports `node:module`
+* and `node:path`: the root export is browser code, and pulling Node builtins
+* into it would break every bundler that consumes this package.
+*
+* This exists because locating the directory is otherwise three lines of module
+* archaeology plus knowledge of an internal `dist/` layout, and everybody
+* serving the default UI has to write them — `aai-cli`'s dev server had its own
+* copy, as did every self-hosted example. Three places that would all silently
+* serve nothing if the build output moved.
+*
+* @module client-dir
+*/
+const require = createRequire(import.meta.url);
+/**
+* Absolute path to the prebuilt browser client's static files — pass it to
+* `createServerForRuntime`/`createAgentServer` as `clientDir`.
+*
+* A function, not a constant: resolution touches the module graph and throws
+* when the package is missing, and a module-level constant would move that
+* failure to import time — where it fires for callers that never wanted the
+* client, and before any of their own error handling is in place.
+*
+* Resolved through this package's own `package.json` rather than relative to
+* this module, so it lands in the same place whether the caller resolved the
+* `@dev/source` TypeScript entry or the compiled one under `dist/`.
+*
+* @example
+* ```ts
+* import { agent } from "@alexkroman1/aai";
+* import { createAgentServer } from "@alexkroman1/aai-runtime";
+* import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+*
+* const server = createAgentServer({
+*   agent: agent({ name: "Support" }),
+*   env: {},
+*   clientDir: defaultClientDir(),
+* });
+* ```
+*
+* @public
+*/
+function defaultClientDir() {
+	let pkgPath;
+	try {
+		pkgPath = require.resolve("@alexkroman1/aai-ui/package.json");
+	} catch (err) {
+		throw new Error("Could not locate the default client UI — is @alexkroman1/aai-ui installed? Try reinstalling dependencies (pnpm install).", { cause: err });
+	}
+	return path.join(path.dirname(pkgPath), "dist", "default-client");
+}
+//#endregion
+export { defaultClientDir };

package/dist/client-identity.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Who this browser is to an agent: the id `mountClient({ client: "auto" })`
+ * sends as `?client=`, the inbox HOLDER id of this tab, and the
+ * `session.identity` handle both are read from.
+ *
+ * ## Why the SDK mints the client id
+ *
+ * A client id is what a tool hands a workflow run (`sessionClientId(ctx)`) so
+ * the run's `stepNotifyClient` can reach this browser AFTER the session that
+ * started it has closed — a reminder due tomorrow is delivered to whoever holds
+ * the id tomorrow. So it must be the SAME id on the session socket and on the
+ * inbox socket, and it must outlive the tab. Every app that wanted a reminder in
+ * a browser wrote the same thirty lines (a `localStorage` read, a validity
+ * check, a fallback for private mode) and got the second half of this module
+ * wrong: see the holder below.
+ *
+ * - **`localStorage`, keyed by the agent's URL** (`_web-storage.ts`'s rule). Two
+ *   agents served from one origin — every deployed agent, at `/:slug/` — must
+ *   not share one: the id is the ONLY credential for a client's durable
+ *   conversation (`VoiceSessionOptions.client`), so agent A's server, which
+ *   receives it, could otherwise present it to agent B and read B's history.
+ * - **Unguessable**: 128 random bits, from `crypto.getRandomValues` — which,
+ *   unlike `crypto.randomUUID`, exists outside a secure context, and `aai dev`
+ *   on a LAN address is plain `http:`.
+ * - **Private mode** (storage throws or is absent) degrades to an id for THIS
+ *   TAB, held in memory: the session and inbox still agree, a reminder set in
+ *   the tab reaches the tab, and nothing outlives it.
+ *
+ * ## Why the holder is per TAB, not per browser
+ *
+ * The inbox keeps one socket per (client, holder) pair, and the same pair again
+ * REPLACES the old socket — right for a device back from a Wi-Fi drop, whose old
+ * socket is half-dead. Every tab of a browser shares `localStorage`, so an app
+ * that used the browser-wide id as the holder had two tabs presenting the same
+ * pair: each connect knocked the other tab off, the other reconnected on its
+ * backoff and knocked this one off, about once a second, forever. The holder is
+ * the browser id plus a suffix minted once per PAGE LOAD, so tabs coexist as
+ * holders of one client and every one of them is offered the notice.
+ *
+ * @module
+ */
+/**
+ * This browser's stable client id for the agent at `platformUrl` —
+ * `browser-<32 hex>`, minted once and kept in `localStorage`. The id
+ * `mountClient({ client: "auto" })` sends; call it yourself to compose it, e.g.
+ * a page joined to a speaker that sends the speaker's id instead:
+ *
+ * @example
+ * ```ts
+ * import { browserClientId, mountClient } from "@alexkroman1/aai-ui";
+ *
+ * declare function linkedSpeaker(): string | undefined;
+ *
+ * mountClient({ client: () => linkedSpeaker() ?? browserClientId() });
+ * ```
+ *
+ * A stored value that is not a valid client id (letters, digits, `-`, `_`, at
+ * most 64) is replaced. Where storage is unavailable the id lasts for this tab.
+ *
+ * @param platformUrl - The agent's base URL; the id is per agent. Defaults to
+ *   the page's own, which is `mountClient()`'s default too.
+ * @returns The id — the same one on every call for the same agent.
+ *
+ * @public
+ */
+export declare function browserClientId(platformUrl?: string): string;
+/**
+ * This TAB's inbox holder id for the agent at `platformUrl`: the browser id
+ * plus a per-page-load suffix. Never the browser id alone — see the module doc
+ * for the two tabs that knocked each other off once a second.
+ *
+ * @internal
+ */
+export declare function inboxHolderId(platformUrl: string): string;
+/**
+ * Who a session is to its agent — `session.identity`. Everything here is read
+ * NOW (a getter `client` can change between attempts), and nothing is a
+ * subscription: `useClientId()` and `useSessionId()` are the reactive reads.
+ *
+ * @sealed Only `createBrowserSession` produces one.
+ *
+ * @public
+ */
+export type SessionIdentity = {
+    /** The agent's base URL the session dials — `VoiceSessionOptions.platformUrl`. */
+    readonly platformUrl: string;
+    /**
+     * The client id the next connection attempt sends as `?client=`, trimmed, or
+     * `undefined` when it sends none. With `client: "auto"` it is
+     * {@link browserClientId}; with a getter it is the getter's answer now.
+     */
+    clientId(): string | undefined;
+    /**
+     * This tab's `?holder=` for the client's `WS /inbox` socket — per TAB, so two
+     * tabs of one browser coexist instead of replacing each other's socket.
+     */
+    holderId(): string;
+    /**
+     * The server's id for the current session: `undefined` until the first
+     * `config` frame of a session, and again after `end()`. A resume or a new
+     * session sets it from its own `config` frame. Sensitive — see
+     * `VoiceSessionOptions.onSessionId`.
+     */
+    sessionId(): string | undefined;
+    /**
+     * A session ticket for ANOTHER socket on the same server — what `useInbox()`
+     * presents on `WS /inbox`, which a gated server checks exactly like
+     * `/websocket`. The session's own `token` option when it has one; otherwise a
+     * fresh one from the server's `client-config` (`aai dev` with
+     * `AAI_SESSION_SECRET`), until a lookup shows the server issues none.
+     * `undefined` means "present none". Fresh on every call: tickets are short-lived.
+     */
+    ticket(): string | undefined | Promise<string | undefined>;
+};
+/** The client option as the dialer reads it: `"auto"` resolved, everything else as given. */
+export declare function resolveClientOption(client: string | (() => string | undefined) | undefined, platformUrl: string): string | (() => string | undefined) | undefined;
+/** A string-or-getter option resolved NOW, trimmed; an empty answer is none. */
+export declare function resolveReported(value: string | (() => string | undefined) | undefined): string | undefined;
+/** What the identity reads from the session's dialer. */
+type IdentitySource = Pick<SessionIdentity, "sessionId" | "ticket">;
+/**
+ * Build a session's {@link SessionIdentity}. `sessionId` and `ticket` are the
+ * dialer's (read through `source`, which may answer nothing): it owns the id
+ * because it sees every `config` frame, `end()` and `resume()`, and the ticket
+ * because it holds the `token` option and the server's `client-config` latch.
+ */
+export declare function createSessionIdentity(options: {
+    platformUrl: string;
+    client?: string | (() => string | undefined) | undefined;
+}, source: () => IdentitySource | undefined): SessionIdentity;
+export {};

package/dist/client-tool.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The page's half of a `clientTool`: run the handler when the agent calls the
+ * tool, and send what it returned back as the call's result.
+ *
+ * Built on {@link useToolCallStart}, so it inherits that hook's dedup — one run
+ * per `toolCallId` per mounted hook — and its mount rule: a call still PENDING
+ * when the hook mounts is run (the server may be waiting on it, e.g. across a
+ * resume), a call that already completed is history and is not.
+ *
+ * @module
+ */
+import type { ToolCallInfo } from "./types.ts";
+/**
+ * Run a `clientTool` in this page and answer the agent with its result.
+ *
+ * When the model calls the tool named `toolName`, `handler` runs with the
+ * call's arguments. What it returns (or resolves to) is JSON-serialized and
+ * becomes the tool's result — the value the model reads. A handler that throws
+ * or rejects fails the call, and the model is told the error's message, as it
+ * would be for a server tool.
+ *
+ * The server waits only as long as the tool's `timeoutMs` (default 30 s); an
+ * answer after that, or while disconnected, is dropped. Mount the hook once per
+ * tool: two mounted handlers both run, and only the first answer counts.
+ *
+ * @example Let the agent ask for the caller's location
+ * ```tsx
+ * import { useClientTool } from "@alexkroman1/aai-ui";
+ *
+ * function LocationTool() {
+ *   useClientTool("get_location", () =>
+ *     new Promise((resolve, reject) =>
+ *       navigator.geolocation.getCurrentPosition(
+ *         (p) => resolve({ lat: p.coords.latitude, lon: p.coords.longitude }),
+ *         (err) => reject(new Error(err.message)),
+ *       ),
+ *     ),
+ *   );
+ *   return null;
+ * }
+ * ```
+ *
+ * @typeParam A - The tool's argument shape. Name it, or derive it with a
+ *   TYPE-ONLY import of the server tool: `useClientTool<InferToolInput<typeof
+ *   getLocation>>(…)`.
+ * @param toolName - The name of the `clientTool` — its `tools/<name>.ts` file.
+ * @param handler - Runs the call; its return value is the result.
+ *
+ * @public
+ */
+export declare function useClientTool<A = ToolCallInfo["args"]>(toolName: string, handler: (args: A, toolCall: ToolCallInfo) => unknown): void;

package/dist/components/_colors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared tints used by the default components (AssemblyAI design system,
+ * "website refresh": warm neutrals over the cream/white surfaces).
+ *
+ * These sit on top of the {@link ClientTheme} colors, which own the opaque
+ * palette. The neutral text steps are **derived from the theme** rather than
+ * hardcoded: `ClientTheme` documents `bg`/`surface`/`text` as free-form
+ * colors, so a client is free to hand the components a dark ground — and a
+ * fixed warm-grey scale tuned for cream leaves the AGENT/TOOL labels, every
+ * tool-call args preview, the chevron and both URL chips below WCAG AA while
+ * the prose and bubbles around them follow the theme correctly. Measured on a
+ * plausible dark theme before this was derived: 14 text nodes under 4.5:1
+ * (the faint step at 3.2–3.5:1, the muted step at 2.5:1), against zero on the
+ * default light theme.
+ *
+ * `ERROR_COLOR` and `THINKING_COLOR` stay fixed: they are *semantic* colors
+ * whose hue carries the meaning, so they cannot be re-derived from a theme
+ * that knows nothing about severity.
+ */
+/**
+ * Blend `text` into `surface` by `pct`, giving a neutral step that stays on
+ * the theme's own ink/ground axis. On a light theme this walks *down* from
+ * the surface toward the ink; on a dark one it walks *up* from the ground
+ * toward the light ink — the same call reads correctly either way, which is
+ * the whole reason to derive rather than hardcode.
+ */
+export declare function inkTint(text: string, surface: string, pct: number): string;
+/**
+ * Muted text — subtitles, secondary labels, thinking dots (fg-muted).
+ * 75% lands within a couple of RGB steps of the design system's `#57534B`
+ * on the default theme.
+ */
+export declare const INK_MUTED_PCT = 75;
+/**
+ * Faint text — live transcripts, state indicator, start-screen subtitle.
+ * 65% reproduces the design system's `#6F6A60` on the default theme.
+ */
+export declare const INK_FAINT_PCT = 65;
+/** Subtle surface tint — inline code, tool-call chips, message bubbles. */
+export declare const INK_SURFACE_PCT = 3;
+/** Error red tuned for warm light surfaces. */
+export declare const ERROR_COLOR = "#B3261E";
+/** Amber used by the "thinking" state indicator. */
+export declare const THINKING_COLOR = "#B98900";
+/**
+ * Derive the user-bubble fill/edge from the theme primary (the mock's
+ * indigo-50 background with an indigo-100 border), so custom themes keep a
+ * coherent tinted bubble instead of a hardcoded indigo.
+ */
+export declare function primaryTint(primary: string, surface: string, pct: number): string;
+/**
+ * The focus ring, as the class half of a pair.
+ *
+ * The ring is the only thing a keyboard user gets, and it has regressed to
+ * invisible twice — `outline-none` shipped here with no replacement, on the
+ * button and then on the URL chips, which is WCAG 2.4.7 on every control in the
+ * default client. Written as a SHORTHAND so it cannot be undone by Tailwind's
+ * shared `--tw-outline-style` variable.
+ *
+ * It is inert on its own: an outline with no colour draws nothing, so a control
+ * using this must also spread {@link focusRingStyle}. Naming the two together
+ * is what stops the next control shipping one without the other.
+ */
+export declare const FOCUS_RING = "outline-none focus-visible:[outline:2px_solid] focus-visible:[outline-offset:2px]";
+/**
+ * The style half of {@link FOCUS_RING} — the colour the outline draws in.
+ *
+ * A real CSS property rather than a variant class, so the `focus-visible` rule
+ * only has to turn the outline on.
+ */
+export declare function focusRingStyle(primary: string): {
+    outlineColor: string;
+};

package/dist/components/_form-readiness.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Whether a form's own fields exist yet.
+ *
+ * `<Form>` leans entirely on NATIVE validation — it is a real `<form>` with no
+ * `noValidate`, so a `required` field is what stops an empty submit, and the
+ * module doc next door says so. That has one hole, and it is the whole reason
+ * this exists: a field set declared REMOTELY is not in the DOM while its
+ * declaration is in flight, so there is nothing for the browser to validate and
+ * an empty submit sails through.
+ *
+ * It is not theoretical. `<WorkflowFields>` renders `null` until the workflow
+ * listing lands, so the transcription desk's first click — before the one-request
+ * lookup answered — submitted a form holding only its button. The browser was
+ * happy, the payload was `{}`, and the run was refused by the agent with
+ * `Invalid input for workflow "transcribeStream": recording: Invalid input`: a
+ * schema complaint about a field the person had not been shown, naming a workflow
+ * they did not choose by name, for a file picker that appeared a moment later.
+ *
+ * ## Readiness is DECLARED by the children, because only they know
+ *
+ * `Form` cannot ask. It renders `{children}` and reads the DOM on submit, and a
+ * pending fetch leaves no trace in the DOM at all — which is exactly the
+ * difference from `data-aai-read`, the other thing a child tells the form: that
+ * one describes an element that EXISTS. So this is a context rather than an
+ * attribute, and it carries the one fact a DOM read cannot recover.
+ *
+ * A form with no such children is ready by definition — `useFormReadiness`
+ * outside a provider reports nothing pending, so every hand-written form is
+ * unaffected and `Form` keeps working outside this package.
+ */
+/** What a child calls to say whether its own fields are ready. */
+type Readiness = (key: string, pending: boolean) => void;
+export declare const FormReadinessProvider: import("react").Provider<Readiness | undefined>;
+/**
+ * Track which children are still waiting for their fields.
+ *
+ * A SET keyed by the child's own `useId`, not a counter: a child that re-renders
+ * while pending must not increment twice, and one that unmounts mid-flight must
+ * not leave the form disabled forever. Both are the ordinary lifecycle here — a
+ * page that switches workflows swaps one `<WorkflowFields>` for another.
+ */
+export declare function useFormReadiness(): {
+    pending: boolean;
+    declare: Readiness;
+};
+/**
+ * Declare from a child that its fields are, or are no longer, still loading.
+ *
+ * Reports through an EFFECT rather than during render, because this writes to a
+ * parent's state — doing it in the render body is the "cannot update a component
+ * while rendering a different component" warning, and under StrictMode it is a
+ * double report the parent has to be idempotent about anyway. The cleanup
+ * releases the claim, so an unmounted field set never holds the form shut.
+ */
+export declare function useDeclareFieldsPending(pending: boolean): void;
+export {};

package/dist/components/_form-values.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reading a `<form>`'s named controls into a plain object.
+ *
+ * Split from `form.tsx` because it is the half with no JSX in it and the half
+ * that carries the rules: what a control CONTRIBUTES is the contract — the
+ * object goes straight into a workflow's input, where a zod schema is waiting —
+ * and each branch below is a decision about that rather than about rendering.
+ *
+ * See `form.tsx`'s module doc for why the values come off the DOM at all.
+ */
+import type { FormValues } from "./form-types.ts";
+/**
+ * Read one `<form>`'s named controls into a plain object.
+ *
+ * Exported for tests and for a caller doing its own submit handling.
+ *
+ * @internal
+ */
+export declare function collectValues(form: HTMLFormElement): Promise<FormValues>;

package/dist/components/aai-logo.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The AssemblyAI wordmark (design-system "website refresh" asset).
+ *
+ * The mark keeps its brand blues; the letterforms inherit the theme's text
+ * color so the logo works on the cream default and custom themes alike.
+ *
+ * @param size - Rendered height in px. Defaults to 20.
+ * @internal
+ */
+export declare const AaiLogo: import("react").MemoExoticComponent<({ size }: {
+    size?: number;
+}) => import("react").JSX.Element>;

package/dist/components/audio-result.d.ts

@@ -0,0 +1,94 @@
+import type { ReactNode } from "react";
+import type { UseDownloadUrlResult } from "../use-download-url.ts";
+/**
+ * A one-cue caption track for {@link AudioResult}: the words the clip speaks,
+ * spanning its whole length.
+ *
+ * @public
+ */
+export type AudioResultCaptions = {
+    /** The spoken text — the one cue. */
+    text: string;
+    /** The clip's length, which is where the cue ends. */
+    durationMs: number;
+    /** The track's `label`. Defaults to the player's `label`. */
+    label?: string | undefined;
+    /** The track's `srcLang`. Default `"en"`. */
+    srcLang?: string | undefined;
+};
+/**
+ * Props of {@link AudioResult}.
+ *
+ * @public
+ */
+export type AudioResultProps = {
+    /** What {@link useDownloadUrl} returned for the run's audio upload. */
+    download: UseDownloadUrlResult;
+    /** The name the download link saves as — `"summary.wav"`, `"audit.mp3"`. */
+    filename: string;
+    /** The player's `aria-label`: what this audio IS — `"Summary read aloud"`. */
+    label: string;
+    /**
+     * The heading over the player — typically the duration and size, which the
+     * run's output carries. Omitted, there is no heading.
+     */
+    heading?: ReactNode | undefined;
+    /**
+     * The spoken text as a caption track. Omit it deliberately when the same
+     * words are rendered in full beside the player (see the component doc);
+     * pass it when they are not, or when a real track is what a page needs.
+     */
+    captions?: AudioResultCaptions | undefined;
+    /** Additional CSS class names for the wrapping `<section>`, appended to its own. */
+    className?: string | undefined;
+    /** Rendered under the player — the spoken text, usually. */
+    children?: ReactNode;
+};
+/**
+ * The player for a file a RUN produced: a heading, the fetch's pending line,
+ * its announced error, the `<audio>` with an optional caption track, the
+ * download link, and whatever the page renders beneath — the spoken text.
+ *
+ * Two templates exist because of the audio round trip, and both had written
+ * this block over {@link useDownloadUrl} identically: the same pending
+ * sentence, the same `role="alert"` paragraph, the same `<audio controls>` over
+ * the object URL, the same anchor with `download` set. The `download` attribute
+ * works on an object URL because the bytes are already in the tab — it was the
+ * `href` that could not carry the agent's bearer token, never the attribute —
+ * and that is the whole reason both pages hand this a hook result rather than a
+ * path.
+ *
+ * **A caption track is a judgement, not a default.** `spoken-summary-workflow` passes
+ * `captions`: the summary was written before it was spoken, so one cue
+ * spanning the clip is an honest transcript of it. `call-audit-workflow` deliberately
+ * does not: the spoken text is rendered in full immediately below the player,
+ * which is the same information a track would carry. Both are right, which is
+ * why the prop is optional in both directions.
+ *
+ * @example
+ * ```tsx
+ * import { AudioResult, createWorkflowApi, useDownloadUrl } from "@alexkroman1/aai-ui";
+ *
+ * const api = createWorkflowApi();
+ *
+ * function Player({ id, spoken, ms }: { id: string; spoken: string; ms: number }) {
+ *   const audio = useDownloadUrl(id, { api });
+ *   return (
+ *     <AudioResult
+ *       download={audio}
+ *       filename="summary.wav"
+ *       label="Summary read aloud"
+ *       heading="Read aloud"
+ *       captions={{ text: spoken, durationMs: ms }}
+ *     >
+ *       <p className="text-sm opacity-70">{spoken}</p>
+ *     </AudioResult>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link AudioResultProps}.
+ *
+ * @public
+ */
+export declare function AudioResult({ download, filename, label, heading, captions, className, children, }: AudioResultProps): ReactNode;

package/dist/components/auto-scroll.d.ts

@@ -0,0 +1,74 @@
+import type { CSSProperties, ReactNode } from "react";
+/**
+ * A scroll container that stays pinned to the bottom as its content grows,
+ * releases when the reader scrolls up, and re-engages once they return to the
+ * bottom.
+ *
+ * For clients that render their own chat chrome instead of using
+ * {@link MessageList} — a terminal, a dispatch board, a themed transcript.
+ * `MessageList` already behaves this way; this is the same mechanism with no
+ * opinion about what goes inside it.
+ *
+ * @remarks
+ * The pattern this replaces is a `useEffect` that calls
+ * `ref.current?.scrollIntoView()` on every message change. That version has
+ * three faults, and they compound: it fights the reader, since scrolling up to
+ * re-read is undone by the next transcript delta; it misses growth that is not
+ * a new message, because a streamed reply, an expanding tool block or a
+ * markdown reflow changes height without changing the dependency array; and it
+ * needs a synthetic dependency (`messages.length + transcript.length`) to fire
+ * at all, which is where the dead `if (version < 0) return;` line comes from.
+ * A `ResizeObserver` on the content — what this uses — has none of those.
+ *
+ * @example
+ * ```tsx
+ * import { AutoScroll, useSession } from "@alexkroman1/aai-ui";
+ *
+ * function Transcript() {
+ *   const session = useSession();
+ *   return (
+ *     <AutoScroll className="flex-1 min-h-0" contentClassName="flex flex-col gap-2 p-4">
+ *       {session.messages.map((m) => (
+ *         <div key={m.id}>{m.content}</div>
+ *       ))}
+ *     </AutoScroll>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Scroll container props.
+ *
+ * @public
+ */
+export declare function AutoScroll({ children, className, contentClassName, scrollClassName, style, initial, resize, }: {
+    /** The scrollable content. */
+    children: ReactNode;
+    /**
+     * Classes for the outer container, appended to its own.
+     *
+     * **The container must end up with a bounded height** (`flex-1 min-h-0`,
+     * `h-full`, a fixed height). This is the one constraint callers get wrong:
+     * an unbounded container grows with its content and never scrolls, so
+     * nothing pins and the component silently does nothing.
+     */
+    className?: string | undefined;
+    /**
+     * Classes for the inner content element, where padding and the children's
+     * own layout belong.
+     */
+    contentClassName?: string | undefined;
+    /**
+     * Classes for the scrolling element itself. Defaults to hiding the
+     * scrollbar; pass `"overflow-y-auto"` to show a native one.
+     */
+    scrollClassName?: string | undefined;
+    /** Inline styles for the outer container. */
+    style?: CSSProperties | undefined;
+    /**
+     * Scroll behavior on mount. Defaults to `"instant"` — start at the latest
+     * content without animating a scroll the reader did not ask for.
+     */
+    initial?: "instant" | "smooth" | undefined;
+    /** Scroll behavior when pinned content grows. Defaults to `"smooth"`. */
+    resize?: "instant" | "smooth" | undefined;
+}): ReactNode;