tempest-react-sdk 0.33.2 → 0.35.0

package/dist/tempest-react-sdk.d.ts

@@ -158,6 +158,307 @@ export declare interface AccordionProps {
     className?: string;
 }
 
+/**
+ * A conversation with a model: role-based turns, Markdown answers, a reasoning
+ * block, a streaming caret, per-turn actions and a composer that turns into a stop
+ * button while a turn is generating.
+ *
+ * This is the shape ChatGPT, Claude and DeepSeek converged on, and it is a different
+ * component from {@link Chat}, not a variant of it. A human thread is addressed by
+ * author and cares about delivery state; a model transcript is addressed by role,
+ * has no delivery state at all, and needs three things a human thread never does —
+ * partial output, reasoning separate from the answer, and re-asking.
+ *
+ * Presentational and controlled, like the rest of the SDK: it takes a list and emits
+ * intent (`onSend`, `onStop`, `onRegenerate`, `onEditSubmit`, `onFeedback`). The
+ * transport stays with the app, because "how do I stream from my backend" has a
+ * different answer per provider — the SDK's `createEventStream` covers SSE, `fetch`
+ * with a `ReadableStream` covers the rest, and either way the app owns the
+ * `AbortController` it hands to `onStop`.
+ *
+ * @example
+ * <AIChat
+ *     messages={turns}
+ *     pending={pending}
+ *     onSend={(text) => ask(text)}
+ *     onStop={() => controller.current?.abort()}
+ *     onRegenerate={(turn) => reask(turn)}
+ *     onFeedback={(turn, vote) => track("answer_rated", { id: turn.id, vote })}
+ *     suggestions={["Resuma o último relatório", "Quais pedidos atrasaram?"]}
+ * />
+ */
+export declare function AIChat({ messages, onSend, onStop, onRegenerate, onEditSubmit, onFeedback, onRetry, pending, suggestions, renderAvatar, renderContent, votes, header, emptyState, showSystem, defaultReasoningOpen, showLineNumbers, locale, placeholder, composerActions, composerFooter, composerDisabled, maxRows, onSendError, className, ...rest }: AIChatProps): JSX.Element;
+
+/** A file carried by a turn — an upload on the way in, a document on the way out. */
+export declare interface AIChatAttachment {
+    /** Stable identity. Used as the React key. */
+    id: string;
+    /** Name shown in the chip. */
+    name: string;
+    /** Size in bytes. Formatted for display when given. */
+    size?: number;
+    /** Image URL. When set the attachment renders as a thumbnail instead of a chip. */
+    url?: string;
+    /** MIME type. Used as the chip's secondary label when there is no size. */
+    mimeType?: string;
+}
+
+/**
+ * The prompt field of a conversation with a model: a textarea that grows with its
+ * content, sends on `Enter`, keeps `Shift+Enter` for a newline, and turns into a
+ * stop button while a turn is streaming.
+ *
+ * Uncontrolled on purpose. A draft changes on every keystroke, and lifting that into
+ * app state re-renders the whole transcript per character — with a streaming answer
+ * above, that is the one place where "controlled by default" costs something
+ * visible. Apps that need the draft (a persisted composer, a slash-command menu)
+ * read it from `onChange` or drive it through the ref.
+ *
+ * @example
+ * <AIChatComposer
+ *     generating={generating}
+ *     onSend={(text) => ask(text)}
+ *     onStop={() => controller.abort()}
+ *     footer={<small>Claude Opus 5 · pode errar</small>}
+ * />
+ */
+export declare const AIChatComposer: ForwardRefExoticComponent<AIChatComposerProps & RefAttributes<AIChatComposerHandle>>;
+
+/** Imperative handle, so a thread can focus or refill the field. */
+export declare interface AIChatComposerHandle {
+    focus: () => void;
+    /** Replace the draft — used to put a prompt back in the field. */
+    setValue: (text: string) => void;
+}
+
+export declare interface AIChatComposerProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, OverriddenDomProps_5> {
+    /** Called with the trimmed prompt. The field clears only when this does not throw. */
+    onSend: (text: string) => void | Promise<void>;
+    /**
+     * Abort the turn in flight.
+     *
+     * When given together with `generating`, the send button becomes a stop button
+     * and `Escape` aborts too.
+     */
+    onStop?: () => void;
+    /** A turn is being generated. Replaces send with stop and refuses to send. */
+    generating?: boolean;
+    /** Locale for the placeholder and the button labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Left of the send button — an attach control, a model picker, a tool toggle. */
+    actions?: ReactNode;
+    /** Under the field — a token count, the model name, a disclaimer. */
+    footer?: ReactNode;
+    /** Largest height the field grows to, in lines. Default 8. */
+    maxRows?: number;
+    /**
+     * Called when `onSend` rejects. The draft is kept either way.
+     *
+     * Without it the rejection is swallowed after the draft is preserved: re-throwing
+     * out of a DOM event handler surfaces as an unhandled promise rejection, which is
+     * console noise for the developer and nothing the user can act on. The visible
+     * signal is the prompt still sitting in the field; wire this to a toast to say why.
+     */
+    onError?: (error: unknown) => void;
+}
+
+/** One turn of a conversation with a model. */
+export declare interface AIChatMessage {
+    /** Stable identity. Used as the React key and by every callback. */
+    id: string;
+    role: AIChatRole;
+    /**
+     * The text of the turn.
+     *
+     * An assistant turn is rendered as Markdown; a user turn is rendered as plain
+     * text with newlines preserved. That asymmetry is deliberate: a model emits
+     * Markdown by contract, while a person typing `2 * 3 * 4` did not mean to open
+     * an emphasis span.
+     */
+    content: string;
+    /**
+     * Reasoning the model exposed before answering — extended thinking, a
+     * chain-of-thought trace.
+     *
+     * Rendered in its own collapsible block above the answer, so a long trace never
+     * pushes the answer off screen.
+     */
+    reasoning?: string;
+    /**
+     * The turn is still arriving.
+     *
+     * Shows the caret, marks the block `aria-busy`, and hides the action row —
+     * copying or rating half an answer is never what somebody meant to do.
+     */
+    streaming?: boolean;
+    /** Generation failed. Shown under whatever streamed, with the retry control. */
+    error?: string;
+    /** Epoch milliseconds. */
+    createdAt?: number;
+    /** Model that produced the turn. Shown in the meta row of an assistant turn. */
+    model?: string;
+    attachments?: readonly AIChatAttachment[];
+    /** Anything the app wants to carry through to its own renderers. */
+    data?: Record<string, unknown>;
+}
+
+export declare interface AIChatProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_4> {
+    /** The transcript, **oldest first**. Never reordered by the component. */
+    messages: readonly AIChatMessage[];
+    /** Renders the composer when given. Receives the trimmed prompt. */
+    onSend?: (text: string) => void | Promise<void>;
+    /** Abort the turn in flight. Shows the stop button while generating. */
+    onStop?: () => void;
+    /** Ask again for the newest assistant turn. */
+    onRegenerate?: (message: AIChatMessage) => void;
+    /** Re-submit an edited user turn. The app decides what to drop after it. */
+    onEditSubmit?: (message: AIChatMessage, text: string) => void | Promise<void>;
+    /** Rating on an assistant turn. */
+    onFeedback?: (message: AIChatMessage, vote: AIChatVote) => void;
+    /** Retry a turn that carries an `error`. */
+    onRetry?: (message: AIChatMessage) => void;
+    /**
+     * The request is out and nothing has arrived yet.
+     *
+     * Distinct from a turn with `streaming: true`: apps that only push a message
+     * once the first token lands need somewhere to say "we asked", and without it the
+     * screen is frozen for however long the model takes to start.
+     */
+    pending?: boolean;
+    /** Prompts offered on an empty transcript. Clicking one sends it. */
+    suggestions?: readonly string[];
+    /** Avatar for a turn — an `<Avatar>`, an `<Icon>`, a logo. */
+    renderAvatar?: (message: AIChatMessage) => ReactNode;
+    /** Render a body yourself — a tool-call card, a chart, a citation list. */
+    renderContent?: (message: AIChatMessage) => ReactNode;
+    /** Ratings to show as pressed, by message id. Omit to keep them local. */
+    votes?: Readonly<Record<string, AIChatVote>>;
+    /** Rendered above the transcript, inside the panel. */
+    header?: ReactNode;
+    /** Shown when there are no turns and no suggestions. */
+    emptyState?: ReactNode;
+    /** Show `"system"` turns. Default `false`. */
+    showSystem?: boolean;
+    /** Reasoning blocks start expanded. Default `false`. */
+    defaultReasoningOpen?: boolean;
+    /** Show line numbers in fenced code. Default `false`. */
+    showLineNumbers?: boolean;
+    /** Locale for labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Placeholder for the composer. */
+    placeholder?: string;
+    /** Extra controls inside the composer, before the send button. */
+    composerActions?: ReactNode;
+    /** Under the composer field — token count, model name, a disclaimer. */
+    composerFooter?: ReactNode;
+    /** Disable the composer — no credits, conversation archived, offline. */
+    composerDisabled?: boolean;
+    /** Largest height the composer grows to, in lines. Default 8. */
+    maxRows?: number;
+    /**
+     * Called when `onSend` **or** `onEditSubmit` rejects. The draft stays in the field
+     * either way.
+     */
+    onSendError?: (error: unknown) => void;
+}
+
+/** Who produced a turn. */
+export declare type AIChatRole = "user" | "assistant" | "system";
+
+/** Labels the conversation needs, per locale. */
+export declare interface AIChatStrings {
+    thread: string;
+    empty: string;
+    emptyHint: string;
+    placeholder: string;
+    send: string;
+    stop: string;
+    regenerate: string;
+    copy: string;
+    copied: string;
+    edit: string;
+    save: string;
+    cancel: string;
+    editing: string;
+    good: string;
+    bad: string;
+    reasoning: string;
+    thinking: string;
+    generating: string;
+    done: string;
+    stopped: string;
+    you: string;
+    assistant: string;
+    system: string;
+    retry: string;
+    jumpToLatest: string;
+    attachment: string;
+    turnActions: string;
+}
+
+/** Locale strings for the conversation. */
+export declare function aiChatStrings(locale: "pt-BR" | "en"): AIChatStrings;
+
+/**
+ * One turn of a conversation with a model.
+ *
+ * Exported for apps that build their own transcript layout (a split view, a diff of
+ * two answers) but still want the SDK's turn: Markdown body, reasoning block,
+ * attachments, streaming caret, error state and the action row.
+ *
+ * @example
+ * <AIChatTurn message={turn} canRegenerate onRegenerate={(m) => reask(m)} />
+ */
+export declare function AIChatTurn({ message, locale, canRegenerate, onRegenerate, onFeedback, onEditSubmit, onEditError, onRetry, renderAvatar, renderContent, vote, defaultReasoningOpen, showLineNumbers, }: AIChatTurnProps): JSX.Element;
+
+export declare interface AIChatTurnProps {
+    /** The turn to render. */
+    message: AIChatMessage;
+    /** Locale for the labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /**
+     * Offer the regenerate control.
+     *
+     * Only the newest assistant turn should get it — re-asking an older one throws
+     * away every turn after it, which is a different operation and needs its own
+     * confirmation.
+     */
+    canRegenerate?: boolean;
+    onRegenerate?: (message: AIChatMessage) => void;
+    onFeedback?: (message: AIChatMessage, vote: AIChatVote) => void;
+    /** Enables the edit control on a user turn. Receives the edited prompt. */
+    onEditSubmit?: (message: AIChatMessage, text: string) => void | Promise<void>;
+    /**
+     * Called when `onEditSubmit` rejects. The editor stays open with the draft either
+     * way.
+     *
+     * Without it the rejection is swallowed after the draft is preserved: re-throwing
+     * out of a click handler surfaces as an unhandled promise rejection, which is
+     * console noise for the developer and nothing the user can act on.
+     */
+    onEditError?: (error: unknown) => void;
+    /** Enables the retry control on a turn that carries an `error`. */
+    onRetry?: (message: AIChatMessage) => void;
+    renderAvatar?: (message: AIChatMessage) => ReactNode;
+    /** Render the body yourself — a tool-call card, a chart, a citation list. */
+    renderContent?: (message: AIChatMessage) => ReactNode;
+    /**
+     * Rating to show as pressed.
+     *
+     * Pass it to keep votes in app state (persisted across a reload); leave it out
+     * and the pressed state is kept locally, which is enough for a fire-and-forget
+     * `onFeedback`.
+     */
+    vote?: AIChatVote;
+    /** Reasoning blocks start expanded. Default `false`. */
+    defaultReasoningOpen?: boolean;
+    /** Show line numbers in fenced code. Default `false`. */
+    showLineNumbers?: boolean;
+}
+
+/** Rating an app can collect on an assistant turn. */
+export declare type AIChatVote = "up" | "down";
+
 /**
  * Inline alert / notice with tone (info/success/warning/danger) and appearance
  * (soft/solid/outline). Accepts optional `icon`, `title`, `description` and
@@ -913,6 +1214,30 @@ export declare const CACHE_TIME: {
     readonly LONG: number;
 };
 
+/**
+ * How large the assets a page precached actually are.
+ *
+ * Reads the `Content-Length` of a stored response instead of its body:
+ * materializing a cached ONNX model or WASM binary to learn its length would
+ * pull tens of megabytes into memory on every measurement.
+ */
+/**
+ * Byte size of a response sitting in a Cache Storage bucket.
+ *
+ * @param cacheName The cache bucket to look in.
+ * @param url The request URL the response was stored under.
+ * @returns The size in bytes, or `null` when Cache Storage is unavailable,
+ *   the entry is absent, or the stored response carries no usable
+ *   `Content-Length` (a chunked transfer, typically).
+ *
+ * @example
+ * ```typescript
+ * const bytes = await cachedResponseBytes("app-models", "/models/detect.onnx");
+ * console.log(bytes === null ? "—" : formatBytes(bytes)); // "12.0 MB"
+ * ```
+ */
+export declare function cachedResponseBytes(cacheName: string, url: string): Promise<number | null>;
+
 /** A cache-name matcher: a prefix string, a `RegExp`, or a predicate. */
 export declare type CacheFilter = string | RegExp | ((name: string) => boolean);
 
@@ -1936,6 +2261,46 @@ export declare interface CreateI18nOptions {
     messages: Catalog;
 }
 
+/**
+ * Timing and cost accounting for a pipeline that runs on the user's device.
+ */
+/**
+ * Create a profiler for one run of a pipeline.
+ *
+ * Wrap each step in {@link InferenceProfiler.stage}, fold in durations you
+ * already have (an SDK `speed` breakdown, say) with
+ * {@link InferenceProfiler.mark}, then call `report()` once the run finishes.
+ *
+ * Stages are timed independently rather than as a tiling of the run, so
+ * concurrent work is charged its real wall-clock span to each stage and the
+ * timings can sum to more than `totalMs`. Surface that to users when you
+ * render the breakdown — a bar chart implying a partition of the total would
+ * be wrong for a pipeline that overlaps stages.
+ *
+ * @returns A profiler bound to the moment it was created.
+ *
+ * @example
+ * ```typescript
+ * import { createInferenceProfiler } from "tempest-react-sdk";
+ * import { Detector } from "tempest-react-sdk/vision";
+ *
+ * const profiler = createInferenceProfiler();
+ * const detector = await profiler.stage("load-model", () =>
+ *     Detector.create("/models/detect.onnx"),
+ * );
+ * const results = await profiler.stage("detect", () => detector.predict(blob));
+ * profiler.mark("forward-pass", results[0].speed.inference);
+ *
+ * const report = await profiler.report({
+ *     models: [
+ *         { name: "detector", cacheName: "app-models", url: "/models/detect.onnx" },
+ *     ],
+ * });
+ * console.log(report.timings, report.totalMs, report.device, report.models);
+ * ```
+ */
+export declare function createInferenceProfiler(): InferenceProfiler;
+
 /**
  * Trivial in-memory adapter. Suitable for tests, local development, or as a
  * fallback wrapping the real provider while it loads.
@@ -2456,10 +2821,36 @@ export declare interface CreateWebSocketOptions<T> {
     /**
      * Ping interval (ms). When set, the client sends `pingPayload` periodically
      * to keep the socket alive. Default: 0 (disabled).
+     *
+     * Leave it off against a `tempest-fastapi-sdk` server: that server pings on
+     * its own and answers a client-sent `{"type":"ping"}` with nothing, while a
+     * strict handler rejects the unknown frame. What it needs from the client
+     * is the `pong` reply, which `respondToPing` sends for you.
      */
     pingInterval?: number;
     /** Payload sent on each ping. Default: `JSON.stringify({ type: "ping" })`. */
     pingPayload?: string | Blob | BufferSource;
+    /**
+     * Reply to a server `{"type":"ping"}` with `pongPayload`. Default: true.
+     *
+     * `tempest-fastapi-sdk` closes a socket with code `4408` when no `pong`
+     * arrives within `WS_HEARTBEAT_TIMEOUT_SECONDS`, so a client that stays
+     * silent is dropped once per timeout. The ping is still forwarded to
+     * `onMessage` — the reply is sent before your handler runs.
+     */
+    respondToPing?: boolean;
+    /** Payload sent in reply to a server ping. Default: `JSON.stringify({ type: "pong" })`. */
+    pongPayload?: string | Blob | BufferSource;
+    /**
+     * Buffer payloads sent while the socket is not open and flush them on the
+     * next `open`. Default: false — `send()` returns false and drops.
+     *
+     * Without it, an action fired during reconnect backoff vanishes and the UI
+     * cannot tell "never sent" from "sent and ignored".
+     */
+    queueWhileClosed?: boolean;
+    /** Cap on buffered payloads when `queueWhileClosed` is on. Default: 100. */
+    maxQueuedMessages?: number;
     /** Parse incoming frames. Default: JSON with raw-string fallback. */
     parser?: (raw: string) => T;
     onOpen?: (event: Event) => void;
@@ -2855,6 +3246,31 @@ export declare interface DescriptionListProps extends HTMLAttributes<HTMLDListEl
     items: DescriptionListItem[];
 }
 
+/**
+ * Shapes describing what an on-device inference run cost.
+ *
+ * The browser exposes no energy counter and no FLOP counter, so "cost" here
+ * is assembled from what a page can actually observe: how long each stage
+ * took, how much parallelism and memory the device reports, and how large the
+ * cached model weights are. Anything the platform does not expose stays
+ * `null` — a UI can then render "—" instead of a fabricated number.
+ */
+/**
+ * Device capabilities as reported by the browser.
+ *
+ * Every field is best-effort. `deviceMemoryGb` and `jsHeapUsedMb` come from
+ * Chromium-only APIs (`navigator.deviceMemory`, `performance.memory`) and are
+ * `null` everywhere else, including Firefox and Safari.
+ */
+export declare interface DeviceProfile {
+    /** Logical cores available to workers, or `null` when unreported. */
+    hardwareConcurrency: number | null;
+    /** Approximate device RAM in GiB (coarse, Chromium-only), or `null`. */
+    deviceMemoryGb: number | null;
+    /** Used JS heap in MiB (Chromium-only), or `null`. */
+    jsHeapUsedMb: number | null;
+}
+
 export declare interface DisclosureHandlers {
     open: () => void;
     close: () => void;
@@ -3316,7 +3732,7 @@ export declare interface Filter {
  */
 export declare function FilterBar({ fields, value, onChange, locale, actions, className, ...rest }: FilterBarProps): JSX.Element;
 
-export declare interface FilterBarProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_7> {
+export declare interface FilterBarProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_9> {
     /** Fields the user may filter by. */
     fields: readonly FilterField[];
     /** Applied filters. Controlled. */
@@ -3574,6 +3990,31 @@ export declare function formatDate(value: string | Date): string;
  */
 export declare function formatDateTime(value: string | Date): string;
 
+/**
+ * Rendering helpers for the numbers a profiler produces.
+ */
+/**
+ * Format a millisecond duration for display.
+ *
+ * Sub-second values keep millisecond resolution — the interesting range for a
+ * single forward pass — and anything longer switches to seconds so a cold
+ * start that pays a model download does not read as a five-digit number.
+ * Durations under `1 ms` render as `"<1 ms"` rather than `"0 ms"`, which
+ * would read as "not measured".
+ *
+ * @param value Duration in milliseconds.
+ * @returns The formatted string, or `"—"` for a non-finite or negative input.
+ *
+ * @example
+ * ```typescript
+ * formatDurationMs(0.04);   // "<1 ms"
+ * formatDurationMs(142.6);  // "143 ms"
+ * formatDurationMs(4321);   // "4.32 s"
+ * formatDurationMs(NaN);    // "—"
+ * ```
+ */
+export declare function formatDurationMs(value: number): string;
+
 /**
  * Format a fraction (0-1) as a percentage with one decimal.
  *
@@ -4151,6 +4592,70 @@ export declare interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElem
     lazy?: boolean;
 }
 
+/**
+ * Records how long each stage of a pipeline took.
+ *
+ * Stages are measured **independently**, not as a tiling of the whole run:
+ * two stages started concurrently are each charged their full wall-clock
+ * span, so the sum can exceed {@link InferenceReport.totalMs}. That is the
+ * honest reading for a pipeline that decodes an image while the model
+ * sessions are still loading.
+ */
+export declare interface InferenceProfiler {
+    /**
+     * Run an async stage and record its duration.
+     *
+     * @param name Stage label used as the key in the report.
+     * @param run The work to time.
+     * @returns Whatever `run` resolved to.
+     */
+    stage<T>(name: string, run: () => Promise<T>): Promise<T>;
+    /**
+     * Run a synchronous stage and record its duration.
+     *
+     * @param name Stage label used as the key in the report.
+     * @param run The work to time.
+     * @returns Whatever `run` returned.
+     */
+    stageSync<T>(name: string, run: () => T): T;
+    /**
+     * Record a duration measured elsewhere — a `speed` breakdown returned by
+     * `tempest-react-sdk/vision`, for instance.
+     *
+     * Repeated names accumulate, so folding two passes of the same kind into
+     * one row is a matter of calling `mark` twice.
+     *
+     * @param name Stage label used as the key in the report.
+     * @param durationMs How long it took, in milliseconds.
+     */
+    mark(name: string, durationMs: number): void;
+    /**
+     * Assemble the report for everything recorded so far.
+     *
+     * @param options Which models to size up in Cache Storage.
+     * @returns The finished report.
+     */
+    report(options?: InferenceReportOptions): Promise<InferenceReport>;
+}
+
+/** What one profiled run cost. */
+export declare interface InferenceReport {
+    /** Duration in milliseconds per stage name, in the order first recorded. */
+    timings: Readonly<Record<string, number>>;
+    /** Milliseconds from profiler creation to the `report()` call. */
+    totalMs: number;
+    device: DeviceProfile;
+    models: readonly ProfiledModelSize[];
+    /** Epoch millis at which the report was assembled. */
+    measuredAt: number;
+}
+
+/** Options for {@link InferenceProfiler.report}. */
+export declare interface InferenceReportOptions {
+    /** Models to measure in Cache Storage. Omit to report none. */
+    models?: readonly ProfiledModel[];
+}
+
 export declare interface InMemoryFlagsOptions {
     initial?: Record<string, FlagValue>;
 }
@@ -4459,6 +4964,9 @@ export declare function isDefined<T>(value: T | null | undefined): value is T;
  */
 export declare function isEmpty(value: unknown): boolean;
 
+/** Whether any turn in the thread is still streaming. */
+export declare function isGenerating(messages: readonly AIChatMessage[]): boolean;
+
 /**
  * Detects iOS / iPadOS Safari, including modern iPads that report `MacIntel`
  * plus multi-touch instead of an `iPad` user agent.
@@ -4695,6 +5203,15 @@ export declare interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement
     required?: boolean;
 }
 
+/**
+ * Id of the newest assistant turn, or `null` when there is none.
+ *
+ * Only that turn gets the regenerate control: re-asking an older one would throw
+ * away every turn after it, which is a different operation ("branch here") and
+ * needs its own confirmation.
+ */
+export declare function lastAssistantId(messages: readonly AIChatMessage[]): string | null;
+
 /**
  * Conflict-resolution helpers for the `applyRemote` callback of
  * {@link createOfflineSync}. Each takes the current local record (or
@@ -5024,7 +5541,7 @@ export declare type MarkdownInline = {
     type: "break";
 };
 
-export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_6> {
+export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_8> {
     /** The Markdown source. */
     source: string;
     /**
@@ -5062,7 +5579,7 @@ export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElemen
  */
 export declare function Masonry<T>({ items, children, itemKey, columns, gap, className, style, ...rest }: MasonryProps<T>): JSX.Element;
 
-export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_5> {
+export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_7> {
     /** What to lay out. */
     items: readonly T[];
     /** Render one card. */
@@ -6021,16 +6538,22 @@ declare type OverriddenDomProps_2 = "children" | "onSubmit";
 declare type OverriddenDomProps_3 = "onSubmit" | "value" | "defaultValue" | "rows";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_4 = "children" | "onChange" | "defaultValue";
+declare type OverriddenDomProps_4 = "children" | "onSubmit";
+
+/** DOM attributes the composer redefines. */
+declare type OverriddenDomProps_5 = "onSubmit" | "value" | "defaultValue" | "rows";
+
+/** DOM attributes this component redefines. */
+declare type OverriddenDomProps_6 = "children" | "onChange" | "defaultValue";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_5 = "children";
+declare type OverriddenDomProps_7 = "children";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_6 = "children";
+declare type OverriddenDomProps_8 = "children";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_7 = "children" | "onChange";
+declare type OverriddenDomProps_9 = "children" | "onChange";
 
 /**
  * Page wrapper with header + (optional) toolbar + content + footer. Pairs
@@ -6388,6 +6911,23 @@ export declare interface PostHogLike {
     reset?: () => void;
 }
 
+/** A model whose cached size should appear in the report. */
+export declare interface ProfiledModel {
+    /** Label for the report row, e.g. `"detector"`. */
+    name: string;
+    /** Cache Storage bucket holding the response, e.g. `"app-models"`. */
+    cacheName: string;
+    /** Request URL the model was cached under. */
+    url: string;
+}
+
+/** A model's size as found in the cache. */
+export declare interface ProfiledModelSize {
+    name: string;
+    /** Size in bytes, or `null` when uncached or the size is unreported. */
+    bytes: number | null;
+}
+
 /**
  * Linear progress bar with determinate / indeterminate modes.
  *
@@ -6705,6 +7245,22 @@ export declare interface RatingStarsProps {
  */
 export declare function readableForeground(background: string, light?: string, dark?: string): string;
 
+/**
+ * Sample the device capabilities the browser reports.
+ *
+ * Safe to call during SSR: without a `navigator` every field is `null`.
+ *
+ * @returns The profile, with `null` for anything this platform withholds.
+ *
+ * @example
+ * ```typescript
+ * const device = readDeviceProfile();
+ * console.log(device.hardwareConcurrency); // 8
+ * console.log(device.deviceMemoryGb);      // 8 on Chromium, null on Safari
+ * ```
+ */
+export declare function readDeviceProfile(): DeviceProfile;
+
 /**
  * Read a token's computed value from an element (default: `<html>`).
  *
@@ -7026,6 +7582,9 @@ export declare interface RoleAccessControlConfig {
     role?: string | string[];
 }
 
+/** Role label used in the turn header and by screen readers. */
+export declare function roleLabel(role: AIChatRole, strings: AIChatStrings): string;
+
 export { Route }
 
 /**
@@ -8188,6 +8747,21 @@ export declare type TagSize = "sm" | "md" | "lg";
 
 export declare type TagVariant = "neutral" | "primary" | "success" | "warning" | "danger" | "info";
 
+/**
+ * A value that changes whenever the tail of the thread grows.
+ *
+ * The scroll effect cannot depend on the `messages` array alone. Streaming appends
+ * to the **last** turn, and an app that mutates that object in place — or that
+ * re-renders from a store holding the same array identity — would keep the same
+ * dependency while the text grows, so the view would stop following the answer.
+ * Length of the array, identity of the tail and length of its text together cover
+ * both shapes.
+ *
+ * @param messages - The thread, oldest first.
+ * @returns An opaque signature; compare with `===`.
+ */
+export declare function tailSignature(messages: readonly AIChatMessage[]): string;
+
 export declare interface TelemetryAdapter {
     /** Optional. Called when the provider mounts. */
     init?: () => void | Promise<void>;
@@ -8872,7 +9446,7 @@ export declare interface TransferItem {
     data?: Record<string, unknown>;
 }
 
-export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_4> {
+export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_6> {
     /** The whole catalogue. Both panes are derived from it. */
     items: readonly TransferItem[];
     /** Ids on the target side. Controlled. */
@@ -9021,6 +9595,15 @@ export declare interface TruncateTextProps extends HTMLAttributes<HTMLDivElement
     children: ReactNode;
 }
 
+/**
+ * Clock label for a turn — the time, not a relative phrase.
+ *
+ * A transcript is read top to bottom in one sitting, so "há 2 minutos" on every turn
+ * is noise that also has to be re-rendered on a timer. The wall clock is stable and
+ * enough to answer the only question anyone asks of it ("was this today?").
+ */
+export declare function turnTime(timestamp: number, locale?: "pt-BR" | "en"): string;
+
 /** Sentence for the typing indicator, or `null` when nobody is typing. */
 export declare function typingLabel(names: readonly string[], locale?: "pt-BR" | "en"): string | null;
 
@@ -10782,6 +11365,17 @@ export { useWatch }
 /**
  * React hook around {@link createWebSocket}. Manages the connection lifecycle
  * for the host component and tears it down on unmount.
+ *
+ * Every callback is read through a ref, so `onOpen` / `onMessage` / `onClose` /
+ * `onError` always run the latest closure — an inline arrow function is fine
+ * and never reopens the socket. Connection-shaping options (`protocols`,
+ * `maxRetries`, `initialBackoff`, `maxBackoff`, `pingInterval`,
+ * `queueWhileClosed`) are baked into the connection, so changing one reopens
+ * it with the new value rather than being silently ignored.
+ *
+ * @param url - Full ws:// or wss:// URL.
+ * @param options - Connection configuration and callbacks.
+ * @returns Status, last frame, and the `send` / `reconnect` controls.
  */
 export declare function useWebSocket<T = unknown>(url: string, options?: UseWebSocketOptions<T>): UseWebSocketResult<T>;
 
@@ -10792,7 +11386,15 @@ export declare interface UseWebSocketOptions<T> extends Omit<CreateWebSocketOpti
 
 export declare interface UseWebSocketResult<T> {
     status: WebSocketStatus;
-    /** Last decoded frame received. */
+    /**
+     * Last decoded frame received.
+     *
+     * A snapshot, not a stream: two frames arriving in the same tick collapse
+     * into a single render and only the later one is ever visible. One server
+     * action often emits several frames in a row, so anything that must see
+     * every message has to use `onMessage`, which fires once per frame. Read
+     * `lastMessage` for "what is the current state" rendering only.
+     */
     lastMessage: WebSocketMessage<T> | null;
     /** Send a payload through the active connection. Returns false when not open. */
     send: (payload: string | Blob | BufferSource) => boolean;
@@ -10995,6 +11597,21 @@ export declare interface VirtualTableSort<T> {
 
 export declare type VirtualTableSortDirection = "asc" | "desc";
 
+/**
+ * Turns to render, in order.
+ *
+ * System turns are dropped unless asked for: a system prompt is configuration, and
+ * an app that shows it by default leaks its own instructions into the transcript.
+ *
+ * @param params.messages - The thread, oldest first. Never reordered.
+ * @param params.showSystem - Keep `"system"` turns. Default `false`.
+ * @returns The visible turns, in the given order.
+ */
+export declare function visibleTurns({ messages, showSystem, }: {
+    messages: readonly AIChatMessage[];
+    showSystem?: boolean;
+}): AIChatMessage[];
+
 /**
  * Render content that is hidden visually but remains available to screen
  * readers — the standard "sr-only" pattern. Useful for accessible labels on