@alexkroman1/aai-ui 0.12.3 → 0.14.0

package/dist/components/conversation-view.d.ts

@@ -0,0 +1,130 @@
+/** @jsxImportSource react */
+import type { CSSProperties, ReactNode } from "react";
+import type { ConversationLogEntry } from "../conversation-log.ts";
+import type { ChatMessage, ToolCallInfo } from "../types.ts";
+import type { UseUserTranscriptResult } from "../use-user-transcript.ts";
+/**
+ * Props of {@link ConversationView}.
+ *
+ * @public
+ */
+export type ConversationViewProps = {
+    /** One finalized message, in this chrome's own markup. */
+    renderMessage: (message: ChatMessage) => ReactNode;
+    /**
+     * One tool invocation. Absent, a compact {@link ToolCallRow} naming the tool,
+     * shimmering while it is pending.
+     */
+    renderTool?: ((toolCall: ToolCallInfo) => ReactNode) | undefined;
+    /**
+     * The agent's reply as it arrives. Absent, `renderMessage` is called with a
+     * synthetic assistant message carrying the text so far (its `id` is `-1`,
+     * which no real message has) — every chrome so far rendered the two the same
+     * way, and this keeps them from drifting.
+     */
+    renderStreaming?: ((text: string) => ReactNode) | undefined;
+    /**
+     * The caller's in-progress turn. Rendered only while `transcript.speaking`,
+     * which is the `null`-vs-`""` distinction {@link useUserTranscript} makes
+     * (`""` is speech detected with no words yet — render on it, and read
+     * `transcript.text` for the placeholder). Absent, a muted italic line.
+     */
+    renderTranscript?: ((transcript: UseUserTranscriptResult) => ReactNode) | undefined;
+    /**
+     * Where the transcript row goes. `"inline"` (the default) is the last row
+     * inside the scroll region, as `MessageList` places it; `"below"` renders it
+     * after the scroll region as a sibling — the strip a two-pane board pins to
+     * the bottom of its conversation column, outside the scroll.
+     */
+    transcriptPosition?: "inline" | "below" | undefined;
+    /**
+     * A persisted transcript to render IN PLACE of the live session's items —
+     * `useConversationLog().entries`, whose newest session entry already is the
+     * live conversation. Session entries render through `renderMessage` /
+     * `renderTool`, each after `renderSessionHeader`; a `spoken` entry is
+     * `renderMessage` over an assistant message (id `-2`); a `note` is
+     * `renderNote`. The streaming reply, the transcript and the thinking row are
+     * rendered after it as usual.
+     */
+    log?: readonly ConversationLogEntry[] | undefined;
+    /** A log `note`. Absent, a small centred muted line. */
+    renderNote?: ((entry: Extract<ConversationLogEntry, {
+        kind: "note";
+    }>) => ReactNode) | undefined;
+    /**
+     * What goes above each log `session` entry — a timestamp, a "continue"
+     * button. Absent, nothing.
+     */
+    renderSessionHeader?: ((entry: Extract<ConversationLogEntry, {
+        kind: "session";
+    }>) => ReactNode) | undefined;
+    /** Rendered inside the scroll region while there is nothing to show at all. */
+    empty?: ReactNode | undefined;
+    /**
+     * The `aria-label` of the thinking row. Default `"Thinking"`. Say who: the
+     * dots are the only sign the agent is working, and to a screen reader they
+     * are punctuation.
+     */
+    thinkingLabel?: string | undefined;
+    /** What the thinking row shows. Default: three pulsing dots. */
+    thinkingIndicator?: ReactNode | undefined;
+    /** CSS class names for the thinking row itself (the `role="status"` element). */
+    thinkingClassName?: string | undefined;
+    /**
+     * Classes for the {@link AutoScroll} container. It must end up with a
+     * bounded height (`flex-1 min-h-0`, `h-full`) or nothing pins.
+     */
+    className?: string | undefined;
+    /** Classes for the scroll region's content element — padding, gap, direction. */
+    contentClassName?: string | undefined;
+    /** Classes for the scrolling element itself. See {@link AutoScroll}. */
+    scrollClassName?: string | undefined;
+    /** Inline styles for the scroll container. */
+    style?: CSSProperties | undefined;
+};
+/**
+ * The conversation's skeleton over {@link useConversation}, with every row a
+ * render slot: a pinned scroll region holding the empty state, the interleaved
+ * messages and tool calls, the streaming reply and the announced thinking row,
+ * plus the live transcript — inside the scroll or pinned beneath it.
+ *
+ * `useConversation()` already made the DATA one thing: the interleave, the
+ * streaming utterance, the `null`-vs-`""` transcript distinction and the
+ * thinking-suppression rule. What three custom chromes then each wrote around
+ * it was the same fifty lines of STRUCTURE: an `AutoScroll` with a bounded
+ * height, an empty-state guard on `items.length === 0 && streaming === null`,
+ * the map with its keys, the streaming row, the thinking row with its
+ * `role="status"` and `aria-label` (and the same comment about screen readers
+ * hearing punctuation), the transcript guarded on `speaking`. The bubbles are
+ * the part each template exists to show, so those are slots; the order and the
+ * accessibility contract are this component's.
+ *
+ * {@link MessageList} is this with the stock bubbles filled in.
+ *
+ * Must be rendered inside the providers `mountClient()` installs.
+ *
+ * @example A board's radio log: its own bubbles, the stock tool row, the transcript pinned below
+ * ```tsx
+ * import { ConversationView } from "@alexkroman1/aai-ui";
+ *
+ * function RadioLog() {
+ *   return (
+ *     <ConversationView
+ *       contentClassName="p-4 flex flex-col gap-2"
+ *       empty={<p className="text-center opacity-60">Standing by.</p>}
+ *       renderMessage={({ role, content }) => (
+ *         <div className={role === "assistant" ? "self-start" : "self-end"}>{content}</div>
+ *       )}
+ *       renderTranscript={({ text }) => <div className="px-4 py-2 italic">{text}</div>}
+ *       transcriptPosition="below"
+ *       thinkingLabel="Dispatch is thinking"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link ConversationViewProps}.
+ *
+ * @public
+ */
+export declare function ConversationView({ renderMessage, renderTool, renderStreaming, renderTranscript, transcriptPosition, log, renderNote, renderSessionHeader, empty, thinkingLabel, thinkingIndicator, thinkingClassName, className, contentClassName, scrollClassName, style, }: ConversationViewProps): ReactNode;

package/dist/components/eyebrow.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+/**
+ * Eyebrow label — the design system's small outlined pill with ALL-CAPS,
+ * tracked text ("VOICE AGENT", "LISTENING", …). Used as a section label on
+ * the start screen and as the live status chip in the chat header.
+ *
+ * @internal
+ */
+export declare function Eyebrow({ children, className, style, ...rest }: {
+    children: ReactNode;
+    className?: string | undefined;
+} & Omit<React.HTMLAttributes<HTMLSpanElement>, "className">): ReactNode;

package/dist/components/facts.d.ts

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+/**
+ * Props for {@link Facts}.
+ *
+ * @public
+ */
+export type FactsProps = {
+    /**
+     * The facts, in reading order. Anything `false`, `null`, `undefined` or the
+     * empty string is DROPPED, so a page writes `cond && \`${n} skipped\`` inline
+     * instead of splicing a separator into a conditional string.
+     *
+     * `0` is NOT dropped — it is a fact ("0 words"), and treating it as absent is
+     * the bug a plain truthiness filter would ship.
+     *
+     * They are TEXT rather than `ReactNode`: every one of the nine lines this
+     * replaced was a string, and taking strings is what lets this JOIN them (see
+     * the component doc) instead of interleaving keyed separator elements.
+     */
+    items: readonly (string | number | false | null | undefined)[];
+    /**
+     * Which of the two muted typographies the pages use. `"sm"` is
+     * `text-sm opacity-70`, `"xs"` is `text-xs opacity-60` — the size and the
+     * muting move together, because that is the pair every site had.
+     */
+    size?: "sm" | "xs" | undefined;
+    /**
+     * The element to render. `"p"` by default; `"span"` for a line that sits
+     * inside phrasing content, where a `<p>` is invalid nesting the browser will
+     * reparent out from under React.
+     */
+    as?: "p" | "span" | undefined;
+    /**
+     * ADDED to the base classes rather than replacing them — `tabular-nums`,
+     * `uppercase tracking-[1.2px]`. 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;
+};
+/**
+ * A muted line of run facts, joined by `·` — "6 segments · 12:04 of audio ·
+ * 1,840 words".
+ *
+ * Nine pages had written this by hand under four different typographies for
+ * one role, two of them (`call-audit-workflow` and `spoken-summary-workflow`) byte-identical down
+ * to the payload. Three things it takes off the caller:
+ *
+ * - **The separator cannot be forgotten, and neither can the space around it.**
+ *   Four of the nine carried a literal `{" "}` at the end of a line, because
+ *   Prettier's wrap ate the space that made `· ` read as a separator rather
+ *   than as punctuation glued to the next word. A line that is correct only
+ *   because somebody remembered an invisible JSX expression is exactly the
+ *   thing a component should own.
+ * - **A fact worth omitting is omitted, and by the caller's own condition.**
+ *   The hand-written shape for a conditional fact was to splice the separator
+ *   into the string — `{x ? \` · budget exhausted\` : ""}` — which puts the
+ *   punctuation in two places and gets the leading separator wrong the moment
+ *   the fact before it also disappears. Passing the condition and letting this
+ *   drop it keeps the separator in one place.
+ * - **A line with nothing left to say renders NOTHING.** With every fact
+ *   conditional, the alternative is a muted empty row, or a bare `·`.
+ *
+ * The facts are JOINED into one string rather than interleaved as elements, and
+ * that is why the prop is text: joined, there is no per-fact `key` to invent —
+ * the same reasoning `WorkflowProgress` gives for its log lines. A line that
+ * genuinely needs an element in it (a link) wants its own markup.
+ *
+ * @example
+ * ```tsx
+ * import { Facts } from "@alexkroman1/aai-ui";
+ *
+ * function RunFacts({ words, cut }: { words: number; cut: number }) {
+ *   return <Facts size="xs" items={[`${words} words`, cut > 0 && `${cut} blind cuts`]} />;
+ * }
+ * ```
+ *
+ * @param props - Facts-line props.
+ *
+ * @public
+ */
+export declare function Facts({ items, size, as, className }: FactsProps): ReactNode;

package/dist/components/form-fields.d.ts

@@ -0,0 +1,142 @@
+import type { InputHTMLAttributes, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from "react";
+import type { FieldShell, FileReadMode } from "./form-types.ts";
+/**
+ * Label + control + hint, in the layout every field here uses.
+ *
+ * Exported so a caller's own control gets the same shell rather than an
+ * approximation of it.
+ *
+ * @example
+ * ```tsx
+ * import { Field, Form } from "@alexkroman1/aai-ui";
+ *
+ * function ColorForm() {
+ *   return (
+ *     <Form onSubmit={() => undefined}>
+ *       <Field label="Accent" hint="Any CSS color." htmlFor="accent">
+ *         <input id="accent" name="accent" type="color" />
+ *       </Field>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Field-shell props.
+ *
+ * @public
+ */
+export declare function Field({ label, hint, htmlFor, className, children, }: {
+    /** Visible label. Omitted leaves the control unlabelled. */
+    label?: string | undefined;
+    /** One line of guidance under the control. */
+    hint?: string | undefined;
+    /** Id of the control this labels. */
+    htmlFor?: string | undefined;
+    /** Additional CSS class names for the wrapper, appended to its own. */
+    className?: string | undefined;
+    /** The control itself. */
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A single-line text input.
+ *
+ * Accepts every `<input>` attribute except `name` and `className`, which this
+ * component owns, plus the shared {@link FieldShell} props.
+ *
+ * @param props - {@link FieldShell} props plus `<input>` attributes.
+ *
+ * @public
+ */
+export declare function TextField(props: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className">): import("react").JSX.Element;
+/**
+ * A number input. Contributes a NUMBER to {@link FormValues}, or nothing when
+ * left empty.
+ *
+ * Accepts every `<input>` attribute except `name`, `className` and `type`,
+ * plus the shared {@link FieldShell} props — so `min`, `max` and `step` are
+ * passed straight through.
+ *
+ * @param props - {@link FieldShell} props plus `<input>` attributes.
+ *
+ * @public
+ */
+export declare function NumberField(props: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;
+/**
+ * A multi-line text input.
+ *
+ * Accepts every `<textarea>` attribute except `name` and `className`, plus the
+ * shared {@link FieldShell} props. `rows` defaults to 4.
+ *
+ * @param props - {@link FieldShell} props plus `<textarea>` attributes.
+ *
+ * @public
+ */
+export declare function TextAreaField({ name, label, hint, className, rows, ...rest }: FieldShell & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "name" | "className">): import("react").JSX.Element;
+/**
+ * A dropdown.
+ *
+ * `options` is the short form — a list of strings, or of
+ * `{ value, label }` pairs when the two differ. Pass `children` instead for
+ * full control over the `<option>` elements; `children` wins when both are
+ * given.
+ *
+ * Otherwise accepts every `<select>` attribute except `name` and `className`,
+ * plus the shared {@link FieldShell} props. Note `multiple` works and
+ * contributes an ARRAY (`[]` when nothing is chosen).
+ *
+ * @param props - {@link FieldShell} props, `options`, and `<select>`
+ * attributes.
+ *
+ * @public
+ */
+export declare function SelectField({ name, label, hint, className, options, children, ...rest }: FieldShell & {
+    options?: readonly (string | {
+        value: string;
+        label: string;
+    })[];
+} & Omit<SelectHTMLAttributes<HTMLSelectElement>, "name" | "className">): import("react").JSX.Element;
+/**
+ * A checkbox. Contributes a BOOLEAN to {@link FormValues}.
+ *
+ * Accepts every `<input>` attribute except `name`, `className` and `type`,
+ * plus the shared {@link FieldShell} props. The label renders beside the box
+ * rather than above it, so `hint` is the place for guidance.
+ *
+ * @param props - {@link FieldShell} props plus `<input>` attributes.
+ *
+ * @public
+ */
+export declare function CheckboxField({ name, label, hint, className, ...rest }: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;
+/**
+ * A file picker. Contributes a {@link FileValue} (or an array, with `multiple`)
+ * to {@link FormValues} — or nothing when no file was chosen.
+ *
+ * **`upload` is what a workflow input wants.** A run's input is serialized into
+ * the run record and replayed from it on every resume, so a file's BYTES cannot
+ * travel in it. With `upload` the field contributes the `File` itself,
+ * `useWorkflowSubmit` stores it through `POST /workflows/uploads` before
+ * starting the run, and the input carries the upload id — which a step reads
+ * windows of with `stepReadUpload`. Declaring the property in the workflow's
+ * `uploads` list makes `<WorkflowFields>` render exactly this, so a declared
+ * form needs no file markup at all.
+ *
+ * **Without it the field describes the file and does not read it.** `read`
+ * exists for the cases where the bytes really are small and really are the
+ * input — a CSV of ids, a config — and the size is the author's to check. See
+ * {@link FileReadMode} for the four values; `upload` is shorthand for
+ * `read="upload"`.
+ *
+ * Otherwise accepts every `<input>` attribute except `name`, `className` and
+ * `type`, plus the shared {@link FieldShell} props — so `accept` and
+ * `multiple` are passed straight through.
+ *
+ * @param props - {@link FieldShell} props, `read`/`upload`, and `<input>`
+ * attributes.
+ *
+ * @public
+ */
+export declare function FileField({ name, label, hint, className, read, upload, ...rest }: FieldShell & {
+    read?: FileReadMode;
+    /** Shorthand for `read="upload"` — see above. */
+    upload?: boolean;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;

package/dist/components/form-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What a form's controls CONTRIBUTE — the three types both halves of the form
+ * code share.
+ *
+ * Their own module because `form.tsx` (the components) and `_form-values.ts`
+ * (the DOM read) both need them, and a type living in one of those would make
+ * the pair import each other.
+ */
+/**
+ * One submitted form, as a plain object keyed by field name.
+ *
+ * `unknown` values rather than `string`: see the module doc — a number field
+ * yields a number and a file field yields a {@link FileValue}.
+ *
+ * @public
+ */
+export type FormValues = Record<string, unknown>;
+/**
+ * What a {@link FileField} contributes to {@link FormValues}.
+ *
+ * @public
+ */
+export type FileValue = {
+    name: string;
+    /** Size in bytes. */
+    size: number;
+    /** MIME type the browser reported, or `""` when it could not tell. */
+    type: string;
+    /** Last modified, as epoch ms. */
+    lastModified: number;
+    /**
+     * The file's contents, present only when the field asked for them — see
+     * {@link FileField}'s `read` prop. A `data:` URL for `"dataUrl"`, decoded text
+     * for `"text"`.
+     */
+    content?: string;
+};
+/**
+ * How much of a chosen file a {@link FileField} reads.
+ *
+ * `"upload"` is the odd one and the one a workflow input wants: the field
+ * contributes the `File` ITSELF rather than a description of it, and
+ * `useWorkflowSubmit` then stores it through `POST /workflows/uploads` and puts
+ * the id in the run input. Bytes cannot travel in a run input — see
+ * {@link FileField} — so this is how a form takes a file at all.
+ *
+ * @public
+ */
+export type FileReadMode = "none" | "text" | "dataUrl" | "upload";
+/**
+ * The props every field in `form.tsx` shares.
+ *
+ * Public because it is part of each field's own signature — a type reachable
+ * from a documented one has to be reachable from the entry point too, which the
+ * docs build enforces.
+ *
+ * @public
+ */
+export type FieldShell = {
+    /** Key this field contributes to {@link FormValues}. */
+    name: string;
+    /** Visible label. Omitted leaves the control unlabelled — pass `aria-label` instead. */
+    label?: string | undefined;
+    /** One line of guidance under the control. */
+    hint?: string | undefined;
+    /**
+     * Additional CSS class names for the field's WRAPPER (label + control +
+     * hint), appended to its own layout classes. The control itself takes the
+     * shared field styling; pass `style` or a `data-` hook through the native
+     * attributes to reach it.
+     */
+    className?: string | undefined;
+};

package/dist/components/form.d.ts

@@ -0,0 +1,96 @@
+import type { ButtonHTMLAttributes, FormHTMLAttributes, ReactNode } from "react";
+import { type ButtonSize, type ButtonVariant } from "./button.tsx";
+import type { FormValues } from "./form-types.ts";
+export { CheckboxField, Field, FileField, NumberField, SelectField, TextAreaField, TextField, } from "./form-fields.tsx";
+export type { FieldShell, FileReadMode, FileValue, FormValues } from "./form-types.ts";
+/** Props of {@link Form}. */
+export type FormProps = {
+    /**
+     * Called with the collected values. May be async — the form stays disabled
+     * for the duration, so a double-click cannot submit twice.
+     */
+    onSubmit: (values: FormValues) => void | Promise<void>;
+    /**
+     * A failure to show above the fields. The caller owns it, because the
+     * interesting failures are the server's (`useWorkflowSubmit`'s `error`) and
+     * this component never sees them.
+     */
+    error?: string | undefined;
+    children?: ReactNode;
+    className?: string | undefined;
+} & Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "className">;
+/**
+ * A form that hands its values to `onSubmit` as one object.
+ *
+ * Native validation still applies — a `required` field blocks the submit and the
+ * browser says so, which is better than anything this could render.
+ *
+ * @example
+ * ```tsx
+ * import { Form, SubmitButton, TextField } from "@alexkroman1/aai-ui";
+ *
+ * function NameForm() {
+ *   return (
+ *     <Form onSubmit={(values) => console.log(values.topic)}>
+ *       <TextField name="topic" label="Topic" required />
+ *       <SubmitButton>Start</SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link FormProps}. Every `<form>` attribute except
+ * `onSubmit` and `className` is passed through.
+ *
+ * @public
+ */
+export declare function Form({ onSubmit, error, children, className, ...rest }: FormProps): import("react").JSX.Element;
+/**
+ * The form's submit button, disabled and relabelled while a submit is in
+ * flight.
+ *
+ * Accepts all standard `<button>` HTML attributes except `type` and `disabled`,
+ * in addition to the props below — so `aria-label` on an icon-only submit,
+ * `form`, `id`, `title` and `onClick` all work here exactly as they do on
+ * {@link Button}. `type` and `disabled` stay owned: this component sets both
+ * from `pending`, and letting a caller set either is how a form gets a submit
+ * button that does not submit.
+ *
+ * @example
+ * ```tsx
+ * import { Form, SubmitButton, TextField } from "@alexkroman1/aai-ui";
+ *
+ * function Digest({ pending }: { pending: boolean }) {
+ *   return (
+ *     <Form onSubmit={() => undefined}>
+ *       <TextField name="url" label="Link" required />
+ *       <SubmitButton pending={pending} variant="secondary" size="lg">
+ *         Summarize
+ *       </SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Button props.
+ *
+ * @public
+ */
+export declare function SubmitButton({ children, pending, pendingLabel, size, variant, className, ...rest }: {
+    /** Button label. Replaced by `pendingLabel` while `pending`. */
+    children?: ReactNode;
+    /**
+     * Whether the WORK this form started is still going. Separate from the
+     * submit itself, which {@link Form} disables on its own: a workflow run
+     * outlives its `POST`, and the button should stay busy until the run is done.
+     */
+    pending?: boolean;
+    /** Label shown in place of `children` while `pending`. Defaults to `"Working…"`. */
+    pendingLabel?: string;
+    /** Size preset, passed through to {@link Button}. */
+    size?: ButtonSize | undefined;
+    /** Visual style, passed through to {@link Button}. Defaults to `"default"`. */
+    variant?: ButtonVariant | undefined;
+    /** Additional CSS class names, appended to {@link Button}'s own. */
+    className?: string | undefined;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "disabled" | "className">): import("react").JSX.Element;

package/dist/components/markdown.d.ts

@@ -0,0 +1,57 @@
+import { type FunctionComponent, type MemoExoticComponent } from "react";
+/**
+ * Type scale for {@link Markdown}: `"default"` is the deployed agent UI's
+ * scale, `"compact"` a notch smaller for denser surfaces (the studio's chat
+ * transcript). Colors are unaffected — they come from the theme either way.
+ *
+ * @public
+ */
+export type MarkdownVariant = "default" | "compact";
+/**
+ * Props of {@link Markdown}.
+ *
+ * @public
+ */
+export type MarkdownProps = {
+    /**
+     * The Markdown source. Required — this is the prose to render, normally one
+     * agent message or the streaming tail of one.
+     */
+    text: string;
+    /**
+     * Type scale. Defaults to `"default"`, the deployed agent UI's scale; pass
+     * `"compact"` for a denser surface. Colors are unaffected either way.
+     */
+    variant?: MarkdownVariant;
+};
+/**
+ * Agent prose, rendered as Markdown.
+ *
+ * Pipeline and S2S models write emphasis, lists, `code`, and links; before
+ * this they arrived as literal asterisks and backticks. Styling is
+ * per-element (theme colors via inline styles, spacing via Tailwind) so it
+ * stays on the default client's type scale and follows custom themes.
+ * The optional `variant` selects the type scale (see
+ * {@link MarkdownVariant}).
+ * GFM is on for tables and strikethrough. react-markdown does not render
+ * raw HTML unless rehype-raw is added — keep it that way, this text comes
+ * from a model.
+ *
+ * Memoized alongside `MessageBubble`: message content is referentially
+ * stable across snapshots, so only the streaming row re-parses.
+ *
+ * @example
+ * ```tsx
+ * import { Markdown, useSessionSelector } from "@alexkroman1/aai-ui";
+ *
+ * // The agent's reply as it streams, rendered rather than shown as literal
+ * // asterisks and backticks.
+ * function LiveReply() {
+ *   const text = useSessionSelector((snapshot) => snapshot.agentTranscript);
+ *   return text === null ? null : <Markdown text={text} variant="compact" />;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const Markdown: MemoExoticComponent<FunctionComponent<MarkdownProps>>;

package/dist/components/message-list.d.ts

@@ -1,21 +1,48 @@
+/** @jsxImportSource react */
+import { type FunctionComponent, type MemoExoticComponent } from "react";
+import type { ConversationLogEntry } from "../conversation-log.ts";
+/**
+ * Props of {@link MessageList}.
+ *
+ * @public
+ */
+export type MessageListProps = {
+    /**
+     * Additional CSS class names for the outer scroll container, appended to its
+     * own rather than replacing them.
+     *
+     * The container is an {@link AutoScroll}, so it must end up with a BOUNDED
+     * height (`flex-1 min-h-0`, `h-full`, a fixed height). Unbounded, it grows
+     * with the conversation and never scrolls, so nothing pins to the newest
+     * message.
+     */
+    className?: string;
+    /**
+     * A persisted transcript to show in place of the live session's items —
+     * `useConversationLog().entries`, rendered as {@link ConversationView} renders it.
+     */
+    log?: readonly ConversationLogEntry[] | undefined;
+};
 /**
  * Scrollable list of all chat messages, tool-call blocks, live transcript,
  * streaming agent utterance, and a thinking indicator.
  *
  * Messages and tool calls are interleaved in the correct order. The list
- * auto-scrolls to the latest content via {@link useAutoScroll}.
+ * auto-scrolls to the latest content.
  *
- * Must be rendered inside a {@link SessionProvider}.
+ * Must be rendered inside a `SessionProvider`.
  *
  * @example
  * ```tsx
- * <MessageList className="flex-1" />
+ * import { MessageList } from "@alexkroman1/aai-ui";
+ *
+ * function Conversation() {
+ *   return <MessageList className="flex-1" />;
+ * }
  * ```
  *
- * @param className - Additional CSS class names applied to the scroll container.
+ * @param props - Container props.
  *
  * @public
  */
-export declare function MessageList({ className }: {
-    className?: string;
-}): import("preact").JSX.Element;
+export declare const MessageList: MemoExoticComponent<FunctionComponent<MessageListProps>>;