@x12i/ai 0.0.0-stage → 1.1.0

package/dist/react.d.ts

@@ -0,0 +1,906 @@
+import * as react from 'react';
+import { ComponentPropsWithRef, ReactNode, Ref, RefObject, MouseEvent, JSX } from 'react';
+import { MessageRole, ToolState, ErrorKind, Message as Message$1, TextPart, ReasoningPart, ToolPart, SourcePart, FilePart, DataPart, ThreadStatus, ThreadError, BranchInfo, StreamEvent, ThreadState, ThreadAction } from './index.js';
+
+/**
+ * Every word the chat components show. The kit's components contain no
+ * user-facing text of their own: they read it from this catalog. English ships
+ * as `defaultMessages`. To translate, pass a partial override as the
+ * `messages` prop of a component (`strings` on `ChatThread`), or provide one
+ * for a whole subtree with `AiMessagesProvider`.
+ *
+ * Values that are functions take the dynamic parts (a tool name, a count, a
+ * duration) so a translation can put them anywhere in the sentence. Counts
+ * should use `Intl.PluralRules` in your translation when the language needs it.
+ * Values that are data, such as a tool name or a source title, are shown as
+ * they are.
+ */
+interface AiMessages {
+    /** Accessible name of the whole chat region. */
+    chat: string;
+    /** Accessible name of the scrolling message log. */
+    conversation: string;
+    jumpToLatest: string;
+    emptyTitle: string;
+    emptyDescription: string;
+    /** Shown under the prompt: never hide that content is AI-generated. */
+    disclaimer: string;
+    /** Accessible name of the follow-up suggestions list. */
+    suggestions: string;
+    roles: Record<MessageRole, string>;
+    /** The visible badge on assistant messages. */
+    aiGenerated: string;
+    /** The badge's accessible name. */
+    aiGeneratedLabel: string;
+    edited: string;
+    stopped: string;
+    failed: string;
+    /** Visually hidden while a message is being written. */
+    responding: string;
+    /** For example `1.2K tokens`. */
+    tokens: (count: string) => string;
+    /** `Message from {role}` for the message's accessible name. */
+    messageFrom: (role: string) => string;
+    promptLabel: string;
+    promptPlaceholder: string;
+    send: string;
+    stop: string;
+    attach: string;
+    attachments: string;
+    removeAttachment: (name: string) => string;
+    attachmentUploading: string;
+    attachmentFailed: string;
+    dropFiles: string;
+    /** For example `12 / 500`. */
+    characterCount: (count: number, max: number) => string;
+    characterLimitReached: string;
+    commands: string;
+    commandsAvailable: (count: number) => string;
+    reasoning: string;
+    thinking: string;
+    thought: string;
+    /** `duration` is already formatted, for example `4s`. */
+    thoughtFor: (duration: string) => string;
+    toolStates: Record<ToolState, string>;
+    toolCall: (name: string) => string;
+    toolInput: string;
+    toolOutput: string;
+    toolError: string;
+    /** Shown when the user stopped the run before the tool finished. */
+    toolAborted: string;
+    noInput: string;
+    noOutput: string;
+    approvalTitle: (toolName: string) => string;
+    approvalDescription: string;
+    approvalAction: string;
+    approve: string;
+    deny: string;
+    approveLabel: (toolName: string) => string;
+    denyLabel: (toolName: string) => string;
+    reasonLabel: string;
+    reasonPlaceholder: string;
+    sources: string;
+    sourcesCount: (count: number) => string;
+    /** The accessible name of an inline citation chip. */
+    citationLabel: (number: number, title: string) => string;
+    opensInNewTab: string;
+    noLink: string;
+    actions: string;
+    copy: string;
+    copied: string;
+    copyFailed: string;
+    regenerate: string;
+    edit: string;
+    goodResponse: string;
+    badResponse: string;
+    /** `Version 2 of 3`. */
+    versionLabel: (index: number, count: number) => string;
+    previousVersion: string;
+    nextVersion: string;
+    saveEdit: string;
+    cancelEdit: string;
+    editLabel: string;
+    attachmentsList: string;
+    download: (name: string) => string;
+    thinkingIndicator: string;
+    errorKinds: Record<ErrorKind, {
+        title: string;
+        description: string;
+    }>;
+    retry: string;
+    dismiss: string;
+    editInstead: string;
+    announceReply: (text: string) => string;
+    announceStopped: string;
+    announceApproval: (toolName: string) => string;
+    copyCode: string;
+    codeCopied: string;
+    /** Accessible name of a code block. `language` is empty when unknown. */
+    codeBlock: (language: string) => string;
+    plainText: string;
+    table: string;
+    taskDone: string;
+    taskTodo: string;
+    footnotes: string;
+    footnoteBack: string;
+    /** Shown instead of an image that is blocked. */
+    imageBlocked: string;
+    copyJson: string;
+    showMore: (hidden: number) => string;
+    showLess: string;
+}
+/** A partial catalog. The nested records may be partial too. */
+interface AiMessagesOverride extends Partial<Omit<AiMessages, "roles" | "toolStates" | "errorKinds">> {
+    roles?: Partial<AiMessages["roles"]>;
+    toolStates?: Partial<AiMessages["toolStates"]>;
+    errorKinds?: {
+        [K in ErrorKind]?: Partial<AiMessages["errorKinds"][K]>;
+    };
+}
+declare const defaultMessages: AiMessages;
+/**
+ * Merges catalogs, later ones winning. The record-valued entries (`roles`,
+ * `toolStates`, `errorKinds`) merge key by key, so you can translate a single
+ * tool state or error title.
+ */
+declare function mergeMessages(base: AiMessages, ...overrides: Array<AiMessagesOverride | undefined>): AiMessages;
+
+interface ConversationHandle {
+    /** Scrolls to the newest message and resumes following. */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+}
+interface ConversationProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    children?: ReactNode;
+    /** Pixels from the end that still count as "at the bottom". Default 48. */
+    stickThreshold?: number | undefined;
+    /** Called when the user scrolls away from, or back to, the end. */
+    onAtBottomChange?: ((atBottom: boolean) => void) | undefined;
+    /** Accessible name of the log. Defaults to `messages.conversation`. */
+    label?: string | undefined;
+    /** Imperative handle: `scrollToBottom()`. */
+    handleRef?: Ref<ConversationHandle> | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * The scrolling list of messages.
+ *
+ * - It follows new content (a streaming reply) while you are at the bottom,
+ *   and lets go the moment you scroll up. A "Jump to latest" button appears
+ *   while you are away from the end.
+ * - The scroller is `role="log"` with polite, additions-only live updates, and is
+ *   focusable so the keyboard can scroll it. A streaming message turns its
+ *   own text off (`aria-live="off"`), so a screen reader hears messages, not tokens.
+ */
+declare function Conversation({ children, stickThreshold, onAtBottomChange, label, handleRef, messages: override, className, ref, ...props }: ConversationProps): react.JSX.Element;
+
+interface PartRenderContext {
+    message: Message$1;
+    /** The part's position in `message.parts` (the first one, for grouped parts). */
+    index: number;
+    /** True while the message is still being written. */
+    streaming: boolean;
+    /** Renders the built-in view, so a custom renderer can wrap it. */
+    defaultRender: () => ReactNode;
+}
+/**
+ * Renders one part (or, for `sources` and `files`, all of them at once).
+ * Return `undefined` to use the built-in view and `null` to show nothing.
+ */
+type PartRenderer<P> = (part: P, context: PartRenderContext) => ReactNode | undefined;
+/**
+ * Overrides how parts render. Keys: `text`, `reasoning`, `tool`, `sources`,
+ * `files`, `data` (every data part) and `data:<kind>` for one kind, such as
+ * `data:chart`. A `data:<kind>` renderer wins over `data`.
+ */
+interface PartRenderers {
+    text?: PartRenderer<TextPart>;
+    reasoning?: PartRenderer<ReasoningPart>;
+    tool?: PartRenderer<ToolPart>;
+    sources?: PartRenderer<SourcePart[]>;
+    files?: PartRenderer<FilePart[]>;
+    data?: PartRenderer<DataPart>;
+    [key: `data:${string}`]: PartRenderer<DataPart> | undefined;
+}
+interface MessageProps extends Omit<ComponentPropsWithRef<"article">, "children"> {
+    message: Message$1;
+    /** Defaults to `message.status === "streaming"`. */
+    streaming?: boolean | undefined;
+    /** A decorative avatar. Give it `aria-hidden` if it has no text alternative. */
+    avatar?: ReactNode;
+    /** Display name. Defaults to the role's name from `messages.roles`. */
+    name?: string | undefined;
+    /** Show `createdAt` as a time. Default false. */
+    showTimestamp?: boolean | undefined;
+    /** Formats `createdAt`. Defaults to a short localized time. */
+    formatTimestamp?: ((iso: string, locale: string | undefined) => string) | undefined;
+    /** Show the token count of a finished reply. Default false. */
+    showUsage?: boolean | undefined;
+    locale?: string | undefined;
+    renderPart?: PartRenderers | undefined;
+    /** Called when the user decides on a tool call that needs approval. */
+    onToolDecision?: ((callId: string, decision: "approve" | "deny", reason?: string) => void) | undefined;
+    /** Retry button of the error banner, for a failed reply. */
+    onRetry?: (() => void) | undefined;
+    /** Edit mode for a user message: shows a text box with Save and Cancel. */
+    editing?: boolean | undefined;
+    onEditSubmit?: ((text: string) => void) | undefined;
+    onEditCancel?: (() => void) | undefined;
+    /** Rendered under the content, usually `MessageActions`. */
+    actions?: ReactNode;
+    /** Passed to `Markdown`: how images in replies are shown. */
+    images?: "inline" | "link" | "none" | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * One message: author, an "AI" label on assistant messages, an optional
+ * time, and its parts.
+ *
+ * - Assistant text is rendered as safe Markdown; user and system text stays plain.
+ * - Source parts become the numbered source list; `[1]` in the text links to it.
+ * - While streaming, the content is `aria-live="off"` and the article is
+ *   `aria-busy`, so assistive technology reads the finished reply once.
+ * - `renderPart` replaces any part's view, for example to draw a chart for a `data:chart` part.
+ */
+declare function Message({ message, streaming: streamingProp, avatar, name, showTimestamp, formatTimestamp, showUsage, locale, renderPart, onToolDecision, onRetry, editing, onEditSubmit, onEditCancel, actions, images, messages: override, className, ref, ...props }: MessageProps): react.JSX.Element;
+/** Alias of `Message`, for code that also imports the `Message` data type from `@x12i/ai`. */
+declare const ChatMessage: typeof Message;
+type ChatMessageProps = MessageProps;
+
+type Feedback = "up" | "down";
+interface MessageBranchControl {
+    /** The shown version, from 0. */
+    index: number;
+    /** How many versions exist. The control is hidden when there is only one. */
+    count: number;
+    onSelect: (index: number) => void;
+}
+interface MessageActionsProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    /** The text the copy button copies. Without it there is no copy button. */
+    text?: string | undefined;
+    onCopied?: ((text: string) => void) | undefined;
+    /** Shows a regenerate button. */
+    onRegenerate?: (() => void) | undefined;
+    /** Shows an edit button (for user messages). */
+    onEdit?: (() => void) | undefined;
+    /** The current rating. `null` or omitted means none. */
+    feedback?: Feedback | null | undefined;
+    /** Shows thumbs buttons. Called with the new rating, or `null` when it is withdrawn. */
+    onFeedback?: ((feedback: Feedback | null) => void) | undefined;
+    /** Previous / next version controls for an edited or regenerated message. */
+    branch?: MessageBranchControl | undefined;
+    /** Disables regenerate, edit and branch changes, for example while a reply is streaming. */
+    disabled?: boolean | undefined;
+    /** Your own actions, after the built-in ones. */
+    children?: ReactNode;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * The actions under a message: copy, regenerate, edit, thumbs up and down,
+ * and version navigation. Every control is a labelled button; the thumbs are
+ * toggle buttons (`aria-pressed`). The copy result is announced politely.
+ */
+declare function MessageActions({ text, onCopied, onRegenerate, onEdit, feedback, onFeedback, branch, disabled, children, messages: override, className, ref, ...props }: MessageActionsProps): react.JSX.Element;
+
+/** A file waiting to be sent with the next message. */
+interface PromptAttachment {
+    id: string;
+    name: string;
+    size?: number | undefined;
+    mediaType?: string | undefined;
+    /** `uploading` blocks sending; `error` shows a failure on the chip. Default `ready`. */
+    status?: "ready" | "uploading" | "error" | undefined;
+    /** The file itself, set when `PromptInput` collected it (uncontrolled attachments). */
+    file?: File | undefined;
+}
+/** A command the user can pick by typing `/` in the prompt. */
+interface SlashCommand {
+    id?: string;
+    /** The text after the slash, such as `summarize` for `/summarize`. */
+    name: string;
+    description?: string | undefined;
+}
+interface PromptInputProps extends Omit<ComponentPropsWithRef<"form">, "onSubmit" | "children" | "onChange"> {
+    /** Called with the trimmed text and the attachments when the user sends. */
+    onSubmit: (text: string, attachments: readonly PromptAttachment[]) => void;
+    /** Controlled text. Clear it yourself in `onSubmit`. */
+    value?: string | undefined;
+    defaultValue?: string | undefined;
+    onValueChange?: ((value: string) => void) | undefined;
+    /**
+     * The conversation's state. While `submitted` or `streaming` the send button
+     * becomes a stop button and Enter does nothing.
+     */
+    status?: ThreadStatus | undefined;
+    /** Called by the stop button, and by Escape when `stopOnEscape` is true. */
+    onStop?: (() => void) | undefined;
+    disabled?: boolean | undefined;
+    placeholder?: string | undefined;
+    /** Hard limit; the counter shows `n / max`. */
+    maxLength?: number | undefined;
+    /** Smallest height in lines. Default 1. */
+    minRows?: number | undefined;
+    /** The height at which the box stops growing and scrolls. Default 8 lines. */
+    maxRows?: number | undefined;
+    /** Enter sends and Shift+Enter adds a line. When false, Ctrl or Cmd+Enter sends. Default true. */
+    submitOnEnter?: boolean | undefined;
+    /** Escape stops a running reply. Default true. */
+    stopOnEscape?: boolean | undefined;
+    autoFocus?: boolean | undefined;
+    /** Attachments, controlled. Leave it out and `PromptInput` keeps the files itself. */
+    attachments?: readonly PromptAttachment[] | undefined;
+    onRemoveAttachment?: ((id: string) => void) | undefined;
+    /** Called with files from the attach button, a paste or a drop. Providing it turns on all three. */
+    onFiles?: ((files: File[]) => void) | undefined;
+    /**
+     * Show the attach button and accept pasted and dropped files. Defaults to true
+     * when `onFiles` or `attachments` is given. With `allowFiles` alone, `PromptInput`
+     * keeps the chosen files itself and hands them to `onSubmit` as `attachments[].file`.
+     */
+    allowFiles?: boolean | undefined;
+    /** The `accept` list of the file picker, for example `image/*,.pdf`. */
+    accept?: string | undefined;
+    /** Most files per message. */
+    maxFiles?: number | undefined;
+    /** Commands offered after typing `/` at the start. */
+    slashCommands?: readonly SlashCommand[] | undefined;
+    /** Called when a command is picked. By default, it inserts `/name ` into the text. */
+    onCommandSelect?: ((command: SlashCommand) => void) | undefined;
+    /** Content under the box, such as a disclaimer. */
+    footer?: ReactNode;
+    /** A ref to the textarea. */
+    textareaRef?: Ref<HTMLTextAreaElement> | undefined;
+    locale?: string | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * The message box. It grows with the text up to `maxRows`, sends on Enter
+ * (Shift+Enter adds a line, and Enter during IME composition never sends),
+ * turns the send button into a stop button while a reply runs, and supports
+ * attachments (button, paste, drop), a character counter and `/` commands.
+ *
+ * Accessibility: the textarea has an accessible name; the button's name says
+ * what it does now ("Send message" or "Stop generating"); nothing steals focus;
+ * the command list is announced and navigated with the arrow keys, with focus
+ * staying in the textarea.
+ */
+declare function PromptInput({ onSubmit, value: valueProp, defaultValue, onValueChange, status, onStop, disabled, placeholder, maxLength, minRows, maxRows, submitOnEnter, stopOnEscape, autoFocus, attachments: attachmentsProp, onRemoveAttachment, onFiles, allowFiles, accept, maxFiles, slashCommands, onCommandSelect, footer, textareaRef: textareaRefProp, locale, messages: override, className, style, ref, ...props }: PromptInputProps): react.JSX.Element;
+
+/** A suggestion is a string (shown and sent as it is), or a short label with a longer prompt behind it. */
+type Suggestion = string | {
+    id?: string;
+    label: string;
+    prompt?: string;
+};
+interface SuggestionsProps extends Omit<ComponentPropsWithRef<"div">, "children" | "onSelect"> {
+    suggestions: readonly Suggestion[];
+    /** Called with the text to send (the suggestion's `prompt`, or its label). */
+    onSelect: (prompt: string, suggestion: Suggestion) => void;
+    disabled?: boolean | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/** A row of follow-up or starter prompts. Each is a button; picking one is the same as sending that text. */
+declare function Suggestions({ suggestions, onSelect, disabled, messages: override, className, ref, ...props }: SuggestionsProps): react.JSX.Element | null;
+
+/**
+ * When the thread speaks a reply to a screen reader:
+ * - `complete`: once, when the reply is finished (default).
+ * - `sentences`: each finished sentence while it streams, then the rest.
+ * - `off`: never. The messages are still in the `role="log"`.
+ */
+type AnnounceMode = "complete" | "sentences" | "off";
+interface ChatThreadProps extends Omit<ComponentPropsWithRef<"section">, "children" | "onSubmit"> {
+    messages: readonly Message$1[];
+    /** The conversation's state. Defaults to `streaming` if the last message is streaming, otherwise `idle`. */
+    status?: ThreadStatus | undefined;
+    /** A failure that is not tied to a message. */
+    error?: ThreadError | null | undefined;
+    /** Called with the text and attachments when the user sends. */
+    onSend: (text: string, attachments?: readonly PromptAttachment[]) => void;
+    onStop?: (() => void) | undefined;
+    /** Shows a regenerate button on the last reply, and the retry button of an error. */
+    onRegenerate?: (() => void) | undefined;
+    /** Called when the user approves or denies a tool call. Without it the approval buttons are not shown. */
+    onToolDecision?: ((callId: string, decision: "approve" | "deny", reason?: string) => void) | undefined;
+    /** Shows an edit button on user messages. */
+    onEdit?: ((messageId: string, text: string) => void) | undefined;
+    /** Version navigation for edited messages, from `useThread().chatProps.branches`. */
+    branches?: Record<string, BranchInfo> | undefined;
+    onSwitchBranch?: ((parentId: string, index: number) => void) | undefined;
+    onDismissError?: (() => void) | undefined;
+    /** Shows thumbs buttons on replies. */
+    onFeedback?: ((messageId: string, feedback: Feedback | null) => void) | undefined;
+    /** Current ratings by message id. Omit to let the thread remember them. */
+    feedback?: Record<string, Feedback | null | undefined> | undefined;
+    /** Starter prompts, shown while the thread is empty. */
+    suggestions?: readonly Suggestion[] | undefined;
+    /** Follow-up prompts, shown under the last reply when nothing is running. */
+    followUps?: readonly Suggestion[] | undefined;
+    /** Replaces how parts render, for example to draw a chart for `data:chart`. Memoize it. */
+    renderPart?: PartRenderers | undefined;
+    /** Replaces the empty state. */
+    emptyState?: ReactNode;
+    /** Content above the conversation, such as a title bar. */
+    header?: ReactNode;
+    /** Text under the prompt. Defaults to the AI-generated notice. Pass `false` to hide it. */
+    disclaimer?: ReactNode | false | undefined;
+    /** Avatars by role (decorative). */
+    avatars?: {
+        user?: ReactNode;
+        assistant?: ReactNode;
+    } | undefined;
+    /** Display names by role. Defaults to `strings.roles`. */
+    names?: {
+        user?: string;
+        assistant?: string;
+    } | undefined;
+    showTimestamps?: boolean | undefined;
+    showUsage?: boolean | undefined;
+    /** How images in replies are shown. Default `"link"`. See `Markdown`. */
+    images?: "inline" | "link" | "none" | undefined;
+    announce?: AnnounceMode | undefined;
+    /** Disables the prompt. */
+    disabled?: boolean | undefined;
+    /** More props for the prompt box: `maxLength`, `slashCommands`, `onFiles`, `accept`, `placeholder`... */
+    promptProps?: Partial<Omit<PromptInputProps, "onSubmit" | "status" | "onStop" | "disabled">> | undefined;
+    locale?: string | undefined;
+    /** The words the thread shows. A partial catalog, merged over `defaultMessages`. (Named `strings` because `messages` is the list.) */
+    strings?: AiMessagesOverride | undefined;
+    /** Imperative handle of the conversation: `scrollToBottom()`. */
+    conversationRef?: Ref<ConversationHandle> | undefined;
+}
+/**
+ * The whole chat: message list, composer, errors, suggestions and live
+ * announcements, driven by props. Pair it with `useThread`:
+ *
+ * ```tsx
+ * const thread = useThread({ onSend });
+ * return <ChatThread {...thread.chatProps} suggestions={["Hello"]} />;
+ * ```
+ *
+ * It owns no conversation state: pass `messages` and `status` from anywhere.
+ */
+declare function ChatThread({ messages: threadMessages, status: statusProp, error, onSend, onStop, onRegenerate, onToolDecision, onEdit, branches, onSwitchBranch, onDismissError, onFeedback, feedback: feedbackProp, suggestions, followUps, renderPart, emptyState, header, disclaimer, avatars, names, showTimestamps, showUsage, images, announce, disabled, promptProps, locale, strings, conversationRef, className, ref, ...props }: ChatThreadProps): react.JSX.Element;
+
+type Awaitable<T> = T | Promise<T>;
+/** What a handler returns to stream a reply: any async iterable of stream events, such as an async generator. Return nothing to stream nothing. */
+type ThreadStreamResult = AsyncIterable<StreamEvent> | void | undefined;
+/** A file to send with a message. `PromptInput`'s attachments fit this shape. */
+interface SendAttachment {
+    id?: string | undefined;
+    name: string;
+    mediaType?: string | undefined;
+    size?: number | undefined;
+    /** Where the file can be read. Without it, a `file` is shown through a `blob:` URL. */
+    url?: string | undefined;
+    file?: File | undefined;
+}
+type ThreadTrigger = "send" | "regenerate" | "edit";
+interface ThreadRequest {
+    trigger: ThreadTrigger;
+    /** The user message this turn answers (the newest one). */
+    message: Message$1 | undefined;
+    /** Its text. */
+    text: string;
+    /** Its files. */
+    attachments: FilePart[];
+    /** Every message of the thread, including the new user message. A snapshot: it does not change. */
+    messages: readonly Message$1[];
+    /** Aborted by `stop()`. Pass it to `fetch` so the request is cancelled too. */
+    signal: AbortSignal;
+}
+interface ToolDecisionRequest {
+    callId: string;
+    toolName: string;
+    decision: "approve" | "deny";
+    reason: string | undefined;
+    /** Tool calls still waiting for a decision after this one. Resume the model only when it is 0. */
+    pending: number;
+    messages: readonly Message$1[];
+    signal: AbortSignal;
+}
+interface UseThreadOptions {
+    /** Messages to start with, for example loaded from your store. Read once. */
+    initialMessages?: readonly Message$1[] | undefined;
+    /** Called to answer a new user message. Return (or yield) stream events to write the reply. */
+    onSend?: ((request: ThreadRequest) => Awaitable<ThreadStreamResult>) | undefined;
+    /** Called to answer the last user message again. Defaults to `onSend` with `trigger: "regenerate"`. */
+    onRegenerate?: ((request: ThreadRequest) => Awaitable<ThreadStreamResult>) | undefined;
+    /**
+     * Called after the user approves or denies a tool call. Return a stream to
+     * continue the reply (it is written into the same message), or nothing.
+     * If the stream of the original reply is still open (because it is waiting
+     * for this decision), it is left running and not aborted.
+     */
+    onToolDecision?: ((request: ToolDecisionRequest) => Awaitable<ThreadStreamResult>) | undefined;
+    /** Called after the user stops a reply. The run's `signal` has already been aborted. */
+    onStop?: ((info: {
+        messages: readonly Message$1[];
+    }) => void) | undefined;
+    /** Called when a reply finishes normally. */
+    onFinish?: ((message: Message$1 | undefined) => void) | undefined;
+    /** Called when a reply fails. */
+    onError?: ((error: ThreadError) => void) | undefined;
+    /**
+     * Group stream events into one render per animation frame, so a fast stream
+     * does not render once per token. Default true. Turn it off in tests.
+     */
+    batch?: boolean | undefined;
+    /** Makes ids for user messages. Defaults to `crypto.randomUUID`. */
+    generateId?: (() => string) | undefined;
+    /** The clock, in epoch milliseconds. For tests. */
+    now?: (() => number) | undefined;
+}
+interface EditOptions {
+    /** `truncate` (default) replaces the message and drops what followed; `branch` keeps the old version. */
+    mode?: "truncate" | "branch" | undefined;
+}
+/** Props that `ChatThread` understands, so `<ChatThread {...thread.chatProps} />` just works. */
+interface ThreadChatProps {
+    messages: Message$1[];
+    status: ThreadStatus;
+    error: ThreadError | null;
+    branches: Record<string, BranchInfo>;
+    onSend: (text: string, attachments?: readonly SendAttachment[]) => void;
+    onStop: () => void;
+    onRegenerate: () => void;
+    onToolDecision: (callId: string, decision: "approve" | "deny", reason?: string) => void;
+    onEdit: (messageId: string, text: string) => void;
+    onSwitchBranch: (parentId: string, index: number) => void;
+    onDismissError: () => void;
+}
+interface UseThreadResult {
+    messages: Message$1[];
+    status: ThreadStatus;
+    error: ThreadError | null;
+    /** The whole state, including branches. */
+    state: ThreadState;
+    /** Adds a user message and asks `onSend` for the reply. Ignored while a reply is running. */
+    send: (text: string, attachments?: readonly SendAttachment[]) => Promise<void>;
+    /** Stops the running reply and keeps what was written. */
+    stop: () => void;
+    /** Answers the last user message again. */
+    regenerate: () => Promise<void>;
+    /** Approves a tool call that needs approval. */
+    approve: (callId: string, reason?: string) => Promise<void>;
+    /** Denies a tool call that needs approval. */
+    deny: (callId: string, reason?: string) => Promise<void>;
+    decide: (callId: string, decision: "approve" | "deny", reason?: string) => Promise<void>;
+    /** Edits a user message and asks for a new reply. */
+    edit: (messageId: string, text: string, options?: EditOptions) => Promise<void>;
+    /** Shows another version of an edited message. */
+    switchBranch: (parentId: string, index: number) => void;
+    dismissError: () => void;
+    /** Empties the thread and stops any reply. */
+    clear: () => void;
+    /** Replaces the thread. Stops any reply. */
+    setMessages: (messages: readonly Message$1[]) => void;
+    /** Applies a reducer action, for example to add a system note. */
+    dispatch: (action: ThreadAction) => void;
+    /** Applies one stream event yourself, for events that arrive outside `onSend`, such as from a WebSocket. */
+    applyEvent: (event: StreamEvent) => void;
+    /** Spread into `ChatThread`. */
+    chatProps: ThreadChatProps;
+}
+/**
+ * Chat state for any provider. It keeps the thread with `threadReducer`, runs
+ * your `onSend` (an async generator of stream events works), and gives you
+ * `send`, `stop`, `regenerate`, `approve` and `deny`.
+ *
+ * - Events are applied to the thread as they arrive but rendered once per
+ *   animation frame (`batch: false` to render each one).
+ * - `stop()` aborts the signal your handler received, ends the stream, and
+ *   keeps the text written so far.
+ * - A failure becomes `status: "error"` with a typed `error`; `regenerate()` retries.
+ * - Nothing is ever approved on its own: a tool call that needs approval waits
+ *   until `approve` or `deny` is called.
+ */
+declare function useThread(options?: UseThreadOptions): UseThreadResult;
+
+interface UseStickToBottomOptions {
+    /** How close to the end (in pixels) still counts as "at the bottom". Default 48. */
+    threshold?: number | undefined;
+    /** Called when the user moves away from, or returns to, the bottom. */
+    onAtBottomChange?: ((atBottom: boolean) => void) | undefined;
+}
+interface StickToBottom {
+    /** Put on the scrolling element. */
+    scrollerRef: RefObject<HTMLDivElement | null>;
+    /** Put on the element that holds the content, so growth is noticed. */
+    contentRef: RefObject<HTMLDivElement | null>;
+    /** True while the view is at (or near) the end, or following it. */
+    atBottom: boolean;
+    /** Scrolls to the end and resumes following. */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+}
+/**
+ * Keeps a scroller pinned to its end while content grows (a streaming reply),
+ * and stops as soon as the user scrolls up, so they can read in peace. It
+ * resumes when they scroll back to the bottom, or call `scrollToBottom`.
+ *
+ * A scroll the hook caused itself is told apart from the user's, so a long
+ * smooth scroll or a growing reply does not make it let go by mistake.
+ */
+declare function useStickToBottom({ threshold, onAtBottomChange }?: UseStickToBottomOptions): StickToBottom;
+
+/** How `![alt](url)` is shown. */
+type MarkdownImageMode = "inline" | "link" | "none";
+interface MarkdownProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    /** The Markdown text. Raw HTML in it is dropped, never rendered. */
+    children: string;
+    /** True while the text is still arriving. Sets `data-streaming`; finished blocks are not re-rendered either way. */
+    streaming?: boolean | undefined;
+    /**
+     * Added to heading levels so a `#` in a reply does not compete with the
+     * page's own headings: with the default 2, `#` renders as `<h3>`. Capped at `<h6>`.
+     */
+    headingOffset?: number | undefined;
+    /**
+     * What to do with images. `"link"` (default) shows a link to the image, `"inline"`
+     * renders it, `"none"` shows only the alt text. A model can leak data in an
+     * image URL, so inline images are opt-in. Unsafe URLs are never rendered.
+     */
+    images?: MarkdownImageMode | undefined;
+    /** Allow raster `data:image/...;base64` images when `images="inline"`. Default false. */
+    allowDataImages?: boolean | undefined;
+    /**
+     * Rewrites an image URL before it is rendered, for example to send it through
+     * your own proxy. Return `null` to block the image. The result is checked again.
+     */
+    transformImageUrl?: ((url: string) => string | null | undefined) | undefined;
+    /**
+     * Turn `[1]`, `[1, 2]` and `[1-3]` into citation chips. Defaults to true when
+     * `sources` is given or a surrounding `SourcesProvider` has sources. A number
+     * with no matching source stays as plain text.
+     */
+    citations?: boolean | undefined;
+    /** The sources the citations point at. Defaults to the surrounding `SourcesProvider`'s. */
+    sources?: readonly SourcePart[] | undefined;
+    /** Called when a link is clicked. Call `preventDefault` to handle navigation yourself. */
+    onLinkClick?: ((event: MouseEvent<HTMLAnchorElement>, url: string) => void) | undefined;
+    /** Called after a code block was copied. */
+    onCopyCode?: ((code: string, language: string) => void) | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * Renders Markdown from a model safely.
+ *
+ * - Raw HTML is dropped. Links keep only `http:`, `https:`, `mailto:`, `tel:`
+ *   and relative URLs; external links open in a new tab with
+ *   `rel="noopener noreferrer"` and a spoken "opens in a new tab".
+ * - GitHub Flavored Markdown: tables (in a scroll wrapper), task lists
+ *   (display only), strikethrough, autolinks and footnotes.
+ * - Fenced code becomes a `CodeBlock`: language label and copy button, no highlighting.
+ * - Text blocks are `dir="auto"`, so Hebrew or Arabic paragraphs align correctly.
+ * - Finished blocks are cached while text streams in.
+ */
+declare function Markdown({ children, streaming, headingOffset, images, allowDataImages, transformImageUrl, citations, sources, onLinkClick, onCopyCode, messages: override, className, ref, ...props }: MarkdownProps): JSX.Element;
+
+interface CodeBlockProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    /** The code, exactly as it should be copied. */
+    code: string;
+    /** The language label, such as `ts`. Empty or omitted shows a generic label. */
+    language?: string | undefined;
+    onCopied?: ((code: string) => void) | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * A code block with a language label and a copy button. It is always
+ * left-to-right, whatever the page direction, and is never highlighted or
+ * run: code from a model is shown as text only. When a line is wider than the
+ * block, the block becomes keyboard-focusable so it can be scrolled.
+ */
+declare function CodeBlock({ code, language, onCopied, messages: override, className, ref, ...props }: CodeBlockProps): react.JSX.Element;
+
+interface ReasoningProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    /** The model's reasoning text. Rendered as safe Markdown. */
+    text: string;
+    /** True while the reasoning is still arriving. The panel is open then, and collapses when it ends. */
+    streaming?: boolean | undefined;
+    /** How long the model thought, in milliseconds. Shown once it has finished. */
+    durationMs?: number | undefined;
+    open?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** Locale used to format the duration. */
+    locale?: string | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * A collapsible view of the model's reasoning. Open while it streams, then it
+ * folds itself away (unless you opened or closed it yourself) so the answer
+ * is what you see. The header reads "Thinking…" and then "Thought for 4s".
+ */
+declare function Reasoning({ text, streaming, durationMs, open: openProp, defaultOpen, onOpenChange, locale, messages: override, className, ref, ...props }: ReasoningProps): react.JSX.Element;
+
+interface ToolCallProps extends Omit<ComponentPropsWithRef<"div">, "children" | "part"> {
+    /** The tool part to show. (Shadows the unrelated HTML `part` attribute.) */
+    part: ToolPart;
+    open?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /**
+     * Called when the user decides on a call that needs approval. Without it, the
+     * approval buttons are not shown: the call is only displayed.
+     */
+    onDecision?: ((callId: string, decision: "approve" | "deny", reason?: string) => void) | undefined;
+    /** Replaces the JSON view of the input, for example with a table or a chart. */
+    renderInput?: ((input: unknown, part: ToolPart) => ReactNode) | undefined;
+    /** Replaces the JSON view of the output. */
+    renderOutput?: ((output: unknown, part: ToolPart) => ReactNode) | undefined;
+    locale?: string | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * Shows what the assistant is doing: the tool's name, its state as a badge,
+ * how long it took, and (collapsed by default) its input and output as JSON.
+ * A call that needs approval shows an `ApprovalPrompt` that stays visible even
+ * when the details are folded, so a decision can never be hidden.
+ */
+declare function ToolCall({ part, open, defaultOpen, onOpenChange, onDecision, renderInput, renderOutput, locale, messages: override, className, ref, ...props }: ToolCallProps): react.JSX.Element;
+
+interface ApprovalPromptProps extends Omit<ComponentPropsWithRef<"div">, "children" | "title" | "prompt"> {
+    /** The tool that wants to run. Shown as it is. */
+    toolName: string;
+    /** The exact arguments the tool will run with. Shown in full so the decision is informed. */
+    input?: unknown;
+    /** Why approval is needed, from the model or your policy. Falls back to a generic sentence. */
+    prompt?: string | undefined;
+    /** Called when the user approves. `reason` is the optional note they typed. */
+    onApprove: (reason?: string) => void;
+    /** Called when the user denies. `reason` is the optional note they typed. */
+    onDeny: (reason?: string) => void;
+    /**
+     * Move focus to the prompt when it appears, so a keyboard or screen-reader
+     * user notices it. It never focuses a button, so Enter cannot approve by
+     * accident. Skipped when focus is somewhere else on the page. Default true.
+     */
+    autoFocus?: boolean | undefined;
+    /** Where focus goes after a decision. Defaults to what was focused before, then the chat's prompt box. */
+    returnFocusTo?: RefObject<HTMLElement | null> | (() => HTMLElement | null | undefined) | undefined;
+    /** Show the optional "reason" field. Default true. */
+    allowReason?: boolean | undefined;
+    /** Replaces the JSON view of the input, for example with a form-like summary. */
+    renderInput?: ((input: unknown) => ReactNode) | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * Asks the user to allow or refuse an action. It is a non-modal group, not a
+ * dialog: nothing is blocked and there is no focus trap. It never decides on
+ * its own, and the buttons are the only way to answer.
+ *
+ * When it appears, focus moves to the prompt itself (not to a button). After
+ * a decision, focus returns to where it was.
+ */
+declare function ApprovalPrompt({ toolName, input, prompt, onApprove, onDeny, autoFocus, returnFocusTo, allowReason, renderInput, messages: override, className, ref, ...props }: ApprovalPromptProps): react.JSX.Element;
+
+interface SourcesProviderProps {
+    sources: readonly SourcePart[];
+    children?: ReactNode;
+}
+/**
+ * Connects inline citations to the source list. `Message` provides it; use it
+ * yourself when you render `Markdown` and `Sources` separately.
+ */
+declare function SourcesProvider({ sources, children }: SourcesProviderProps): react.JSX.Element;
+interface CitationProps extends Omit<ComponentPropsWithRef<"a">, "children" | "href"> {
+    /** The source number, from 1. */
+    index: number;
+    /**
+     * The source. Defaults to the n-th source of the surrounding
+     * `SourcesProvider`. Passing one makes the chip stand alone: it links to the
+     * source's URL instead of jumping to the provider's list.
+     */
+    source?: SourcePart | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * An inline numbered chip for a citation. Inside a `SourcesProvider` it jumps
+ * to the matching item of the source list (opening the list if it is
+ * folded); on its own it links to the source's URL. A source without a safe
+ * URL renders as a plain, non-interactive chip.
+ */
+declare function Citation({ index, source: sourceProp, messages: override, className, onClick, ref, ...props }: CitationProps): react.JSX.Element;
+interface SourceCardProps extends Omit<ComponentPropsWithRef<"li">, "children" | "id"> {
+    source: SourcePart;
+    /** The number shown and cited, from 1. */
+    index: number;
+    /** The DOM id, so citations can link here. */
+    id?: string;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * One source: number, title as a link, domain and snippet. No favicon is
+ * fetched, so listing sources never makes a request to the source's site.
+ */
+declare function SourceCard({ source, index, id, messages: override, className, ref, ...props }: SourceCardProps): react.JSX.Element;
+interface SourcesProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    /** Defaults to the sources of the surrounding `SourcesProvider`. */
+    sources?: readonly SourcePart[] | undefined;
+    open?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * A collapsible, numbered list of sources. Citations in the message jump here:
+ * the list opens and the cited source takes focus.
+ */
+declare function Sources({ sources: sourcesProp, open, defaultOpen, onOpenChange, messages: override, className, ref, ...props }: SourcesProps): react.JSX.Element | null;
+
+interface AttachmentsProps extends Omit<ComponentPropsWithRef<"ul">, "children"> {
+    files: readonly FilePart[];
+    locale?: string | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * The files of a message. Images show as thumbnails that open the full image;
+ * other files show as a chip with name and size that downloads. A file whose
+ * URL is not safe (`javascript:` and the like) is shown as a name only. SVG is
+ * never shown inline, because it can carry script.
+ */
+declare function Attachments({ files, locale, messages: override, className, ref, ...props }: AttachmentsProps): react.JSX.Element | null;
+
+interface StreamingIndicatorProps extends Omit<ComponentPropsWithRef<"span">, "children"> {
+    /** Replaces the spoken label. Defaults to `messages.thinkingIndicator`. */
+    label?: string | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * Three pulsing dots that show the assistant is working. The motion is CSS
+ * and stops under `prefers-reduced-motion`, leaving three still dots. The
+ * label is visually hidden and not live: the thread announces progress itself.
+ */
+declare function StreamingIndicator({ label, messages: override, className, ref, ...props }: StreamingIndicatorProps): react.JSX.Element;
+
+interface ErrorBannerProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    error: ThreadError;
+    /** Shows a retry button, unless the error says it is not retryable. */
+    onRetry?: (() => void) | undefined;
+    /** Shows a dismiss button. */
+    onDismiss?: (() => void) | undefined;
+    /** For a moderation error: lets the user go back and rephrase. */
+    onEdit?: (() => void) | undefined;
+    /** Show the provider's own message under the explanation. Default true. */
+    showDetail?: boolean | undefined;
+    messages?: AiMessagesOverride | undefined;
+}
+/**
+ * Explains a failed reply in plain words that depend on the kind of failure
+ * (network, rate limit, moderation, auth, unknown), with a retry where
+ * retrying can help. It is `role="alert"`, so it is announced when it appears.
+ */
+declare function ErrorBanner({ error, onRetry, onDismiss, onEdit, showDetail, messages: override, className, ref, ...props }: ErrorBannerProps): react.JSX.Element;
+
+interface EmptyThreadProps extends Omit<ComponentPropsWithRef<"div">, "title"> {
+    /** Defaults to `messages.emptyTitle`. */
+    title?: ReactNode;
+    /** Defaults to `messages.emptyDescription`. */
+    description?: ReactNode;
+    /** An icon or logo. Defaults to a sparkles glyph. */
+    icon?: ReactNode;
+    /** Usually `Suggestions`. */
+    children?: ReactNode;
+    messages?: AiMessagesOverride | undefined;
+}
+/** What an empty conversation shows: a title, a line of help and, as children, starter suggestions. */
+declare function EmptyThread({ title, description, icon, children, messages: override, className, ref, ...props }: EmptyThreadProps): react.JSX.Element;
+
+interface AiMessagesProviderProps {
+    /** A partial catalog, merged over `defaultMessages` (or over a parent provider). */
+    messages?: AiMessagesOverride;
+    children?: ReactNode;
+}
+/**
+ * Sets the strings for every chat component below it, so you translate once
+ * instead of passing `messages` to each component. A component's own
+ * `messages` prop still wins.
+ */
+declare function AiMessagesProvider({ messages, children }: AiMessagesProviderProps): react.JSX.Element;
+/**
+ * The strings a component should use: the nearest provider's catalog (or the
+ * English default) with the component's own override on top.
+ */
+declare function useAiMessages(override?: AiMessagesOverride): AiMessages;
+
+export { AiMessagesProvider, ApprovalPrompt, Attachments, ChatMessage, ChatThread, Citation, CodeBlock, Conversation, EmptyThread, ErrorBanner, Markdown, Message, MessageActions, PromptInput, Reasoning, SourceCard, Sources, SourcesProvider, StreamingIndicator, Suggestions, ToolCall, defaultMessages, mergeMessages, useAiMessages, useStickToBottom, useThread };
+export type { AiMessages, AiMessagesOverride, AiMessagesProviderProps, AnnounceMode, ApprovalPromptProps, AttachmentsProps, ChatMessageProps, ChatThreadProps, CitationProps, CodeBlockProps, ConversationHandle, ConversationProps, EditOptions, EmptyThreadProps, ErrorBannerProps, Feedback, MarkdownImageMode, MarkdownProps, MessageActionsProps, MessageBranchControl, MessageProps, PartRenderContext, PartRenderer, PartRenderers, PromptAttachment, PromptInputProps, ReasoningProps, SendAttachment, SlashCommand, SourceCardProps, SourcesProps, SourcesProviderProps, StickToBottom, StreamingIndicatorProps, Suggestion, SuggestionsProps, ThreadChatProps, ThreadRequest, ThreadStreamResult, ThreadTrigger, ToolCallProps, ToolDecisionRequest, UseStickToBottomOptions, UseThreadOptions, UseThreadResult };