@dudousxd/nestjs-agent-react 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -3,8 +3,8 @@ import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } fro
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
 import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaView, QuotaReport, ModelCatalogView, AgentCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogEntry, QuotaWindow, QuotaBlock, StoredMessage } from '@dudousxd/nestjs-agent-core';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
-import React__default from 'react';
-import { a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile, T as TranscriptUiBlock } from './model-gHqjNjLJ.cjs';
+import React__default, { ReactNode, Context } from 'react';
+import { T as TranscriptUiBlock, a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile } from './model-gHqjNjLJ.cjs';
 export { f as ApprovalBlockOptions, B as BuildBlocksOptions, g as CoercibleQuestion, D as DescribeToolCallOptions, E as ElicitationBlockOptions, G as GroupToolActivityOptions, R as RawAnswer, h as ResolvedReading, i as ResolvedResultView, j as RetrievedPassage, S as SettleAction, k as ToolActivityGroup, l as ToolCallDescription, m as ToolCallState, n as ToolCallStatus, o as TranscriptApproval, p as TranscriptApprovalStatus, q as TranscriptElicitationBlock, r as TranscriptElicitationOutcome, s as TranscriptFilesBlock, t as TranscriptQuestion, u as TranscriptQuestionOption, v as TranscriptReasoningBlock, w as TranscriptSettleState, x as TranscriptSource, y as TranscriptSourcesBlock, z as TranscriptTextBlock, F as TranscriptToolBlock, H as TranscriptToolCall, I as buildTranscriptBlocks, J as coerceAnswer, K as correctedCallIds, L as describeTimestamp, N as describeToolCall, O as describeUsage, P as extractMessageText, Q as fillTemplate, V as formatRelativeTime, W as groupToolActivity, X as inferResultView, Y as isActionCall, Z as phraseFor, _ as readPath, $ as resolveResultView, a0 as toolCallState, a1 as toolCatalogFrom } from './model-gHqjNjLJ.cjs';
 
 /**
@@ -294,6 +294,138 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private toChunkStream;
 }
 
+/** How a renderer is likely to show a file. */
+type MessageFileKind = 'image' | 'pdf' | 'text' | 'audio' | 'video' | 'other';
+/** One file on a message, live or replayed, with what a renderer needs to decide how to show it. */
+interface MessageFile {
+    url: string;
+    mediaType: string;
+    /** The original name, or `null` when the part carried none. */
+    filename: string | null;
+    kind: MessageFileKind;
+    /** Lower-case extension from the name (`'pdf'`), or `null`. */
+    extension: string | null;
+    /** The stored media id — present on files replayed from history (`StoredMessage.attachments`). */
+    mediaId: string | null;
+}
+/** The {@link MessageFileKind} of a MIME type. */
+declare function fileKind(mediaType: string): MessageFileKind;
+/**
+ * The files on a message — the user's attachments (live, or replayed from `StoredMessage.attachments`
+ * by `storedMessageToUiMessage`) and any the model produced — in part order. Data only: pair it with
+ * your own thumbnails/links.
+ */
+declare function messageFiles(message: Pick<UIMessage, 'parts'>): MessageFile[];
+/**
+ * Whether `file` matches an `accept` list in the `<input accept>` grammar: MIME types
+ * (`application/pdf`), wildcards (`image/*`) and extensions (`.csv`). An empty list accepts all.
+ */
+declare function acceptsFile(accept: string | readonly string[] | undefined, file: Pick<File, 'name' | 'type'>): boolean;
+/** Files carried by a paste — screenshots and copied files. Text-only pastes give `[]`. */
+declare function filesFromClipboard(data: DataTransfer | null | undefined): File[];
+/** Whether a drag carries files (as opposed to text or a link) — gate your drop highlight on it. */
+declare function dragHasFiles(data: DataTransfer | null | undefined): boolean;
+
+/** Where one staged file stands. `rejected` never uploaded (validation); `error` can be retried. */
+type StagedAttachmentStatus = 'uploading' | 'ready' | 'error' | 'rejected';
+interface StagedAttachment {
+    /** Local id, stable for the item's life — use it as the React key and for `remove`/`retry`. */
+    id: string;
+    file: File;
+    name: string;
+    size: number;
+    type: string;
+    status: StagedAttachmentStatus;
+    /** 0..1 while uploading (0 until the backend reports progress), 1 once ready. */
+    progress: number;
+    /** Why it was rejected or failed. */
+    error?: string;
+    /** What the server returned — present once `ready`. */
+    attachment?: MessageAttachment;
+    /** An object URL for image previews (revoked on remove/unmount), when the runtime has one. */
+    previewUrl?: string;
+}
+/** Why a file was turned away before any upload. */
+type AttachmentRejection = 'type' | 'size' | 'count';
+interface UseAttachmentsOptions {
+    /**
+     * Upload one file — defaults to `backend.uploadAttachment`. Resolve with what the server
+     * answered; honour `signal` so `remove` can cancel; call `onProgress(0..1)` if you can.
+     */
+    upload?: (file: File, options: UploadAttachmentOptions) => Promise<MessageAttachment>;
+    /** Used for the default `upload`. One of `upload` / `backend` is required. */
+    backend?: AgentBackend;
+    /** `<input accept>` grammar: `'image/*,.pdf'` or `['image/*', 'application/pdf']`. */
+    accept?: string | readonly string[];
+    /** Per-file ceiling, in bytes. */
+    maxBytes?: number;
+    /** How many files may be staged at once (rejected ones do not count). */
+    maxFiles?: number;
+    /** Words for a rejection; default English. */
+    describeRejection?: (reason: AttachmentRejection, file: File) => string;
+}
+interface AttachmentsState {
+    items: StagedAttachment[];
+    /** Stage files: validate, then upload each that passes. */
+    add: (files: Iterable<File> | ArrayLike<File> | null | undefined) => void;
+    /** Drop an item, cancelling its upload. */
+    remove: (id: string) => void;
+    /** Upload a failed item again. */
+    retry: (id: string) => void;
+    /** Drop everything — call after a send. */
+    clear: () => void;
+    /** An upload is still running — hold the send button. */
+    isUploading: boolean;
+    /** What to send: the ready uploads, in order. */
+    attachments: MessageAttachment[];
+    /** The same, as the `{ mediaId }` refs `POST <base>/chat` takes. */
+    refs: Array<{
+        mediaId: string;
+    }>;
+    /** Props for a hidden `<input type="file">`: `accept`, `multiple`, `onChange`. */
+    inputProps: {
+        type: 'file';
+        accept: string | undefined;
+        multiple: boolean;
+        onChange: (event: {
+            currentTarget: HTMLInputElement;
+        }) => void;
+    };
+    /** Handlers for any element that should take dropped files. */
+    dropZoneProps: {
+        onDragEnter: (event: DragLikeEvent) => void;
+        onDragOver: (event: DragLikeEvent) => void;
+        onDragLeave: (event: DragLikeEvent) => void;
+        onDrop: (event: DragLikeEvent) => void;
+    };
+    /** Files are being dragged over the drop zone — for a highlight. */
+    isDragging: boolean;
+    /** Paste handler for the composer: stages pasted files (screenshots), leaves text alone. */
+    onPaste: (event: ClipboardLikeEvent) => void;
+}
+/** The slice of a React/DOM drag event these handlers read. */
+interface DragLikeEvent {
+    dataTransfer: DataTransfer | null;
+    preventDefault: () => void;
+}
+/** The slice of a React/DOM clipboard event `onPaste` reads. */
+interface ClipboardLikeEvent {
+    clipboardData: DataTransfer | null;
+    preventDefault: () => void;
+}
+/**
+ * Staged attachments for a composer, headless: validation (`accept`, `maxBytes`, `maxFiles`),
+ * one upload per file with progress and cancel, retry, previews, and the event handlers for a file
+ * input, a drop zone and paste — no markup, no styles. Send `attachments` (or `refs`) with the
+ * message, then `clear()`:
+ *
+ * ```ts
+ * await chat.sendMessage({ text }, { body: { attachments: files.refs } });
+ * files.clear();
+ * ```
+ */
+declare function useAttachments(options: UseAttachmentsOptions): AttachmentsState;
+
 interface UseAgentsOptions {
     /** `useAgentChat(...).backend`, or your own. Must implement `listAgents`. */
     backend: AgentBackend;
@@ -570,6 +702,7 @@ declare class AgentClient implements AgentBackend {
      * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
      */
     uploadAttachment(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
+    private uploadWithProgress;
     promoteThread(id: string): Promise<OkResult>;
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
     /** `GET /agent/models?agent=` — the models this caller may pick, grouped by provider. */
@@ -620,6 +753,20 @@ declare class AgentClient implements AgentBackend {
     private handleResponse;
 }
 
+/** Draws a server-pushed component block. */
+type AmbientRenderUi = (block: TranscriptUiBlock) => ReactNode;
+/**
+ * How pushed components are drawn when no `renderUi` is passed — set by `<GenuiProvider>` (the
+ * `/genui` subpath) and read by `MessageItem`.
+ */
+declare const AmbientRenderUiContext: Context<AmbientRenderUi | null>;
+/**
+ * The renderer `<GenuiProvider>` installed for pushed components, or `null` outside one. For a
+ * custom transcript built on `useTranscriptItem`: draw a `ui` block with it and you get what
+ * `MessageItem` draws.
+ */
+declare function useAmbientRenderUi(): AmbientRenderUi | null;
+
 interface ChatInputProps {
     onSubmit: (text: string) => void;
     disabled?: boolean;
@@ -858,8 +1005,8 @@ type RenderTextFn = (text: string, ctx: {
 type RenderFilesFn = (files: TranscriptFile[]) => React__default.ReactNode;
 /**
  * Render a component the server pushed into the message — look `block.component` up in your own
- * registry. Omitted → pushed components are not drawn (there is no sensible default for an app's
- * own component).
+ * registry. Omitted → drawn by the enclosing `<GenuiProvider>` (`/genui`) if there is one, else not
+ * drawn (there is no sensible default for an app's own component).
  */
 type RenderUiFn = (block: TranscriptUiBlock) => React__default.ReactNode;
 /** Render the body of a reasoning run; the disclosure toggle around it stays this component's. */
@@ -894,7 +1041,10 @@ interface MessageRenderSlots {
     renderReasoning?: RenderReasoningFn;
     /** Draw files yourself — a gallery, a viewer. Omitted → images inline, everything else a link. */
     renderFiles?: RenderFilesFn;
-    /** Draw a server-pushed component (a `ui` stream frame). Omitted → not drawn. */
+    /**
+     * Draw a server-pushed component (a `ui` stream frame). Omitted → the enclosing `<GenuiProvider>`
+     * draws it; without one, not drawn.
+     */
     renderUi?: RenderUiFn;
     /**
      * Extra content for the action row, after the built-in affordances and before usage — a badge
@@ -937,7 +1087,7 @@ interface MessageItemViewProps extends MessageRenderSlots {
  */
 declare function MessageItem({ message, isStreaming, editable, onEditSubmit, regeneratable, onRegenerate, onFork, usage, createdAt, ...slots }: MessageItemProps): React__default.JSX.Element;
 /** The default markup for one modelled message — what `MessageItem` renders once it has an item. */
-declare function MessageItemView({ item, ...slots }: MessageItemViewProps): React__default.JSX.Element;
+declare function MessageItemView({ item, ...given }: MessageItemViewProps): React__default.JSX.Element;
 
 interface MessageListClassNames {
     root?: string;
@@ -1607,4 +1757,4 @@ declare class QuotaBlockedError extends Error {
     constructor(block: QuotaBlock);
 }
 
-export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatStreamRequest, type ChatStreamResponse, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type MessageFeedbackInput, type MessageFeedbackState, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, type QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type ResumeStreamRequest, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadPatch, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AttachmentRejection, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatStreamRequest, type ChatStreamResponse, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type MessageFeedbackInput, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, type QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type ResumeStreamRequest, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadPatch, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } fro
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
 import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaView, QuotaReport, ModelCatalogView, AgentCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogEntry, QuotaWindow, QuotaBlock, StoredMessage } from '@dudousxd/nestjs-agent-core';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
-import React__default from 'react';
-import { a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile, T as TranscriptUiBlock } from './model-gHqjNjLJ.js';
+import React__default, { ReactNode, Context } from 'react';
+import { T as TranscriptUiBlock, a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile } from './model-gHqjNjLJ.js';
 export { f as ApprovalBlockOptions, B as BuildBlocksOptions, g as CoercibleQuestion, D as DescribeToolCallOptions, E as ElicitationBlockOptions, G as GroupToolActivityOptions, R as RawAnswer, h as ResolvedReading, i as ResolvedResultView, j as RetrievedPassage, S as SettleAction, k as ToolActivityGroup, l as ToolCallDescription, m as ToolCallState, n as ToolCallStatus, o as TranscriptApproval, p as TranscriptApprovalStatus, q as TranscriptElicitationBlock, r as TranscriptElicitationOutcome, s as TranscriptFilesBlock, t as TranscriptQuestion, u as TranscriptQuestionOption, v as TranscriptReasoningBlock, w as TranscriptSettleState, x as TranscriptSource, y as TranscriptSourcesBlock, z as TranscriptTextBlock, F as TranscriptToolBlock, H as TranscriptToolCall, I as buildTranscriptBlocks, J as coerceAnswer, K as correctedCallIds, L as describeTimestamp, N as describeToolCall, O as describeUsage, P as extractMessageText, Q as fillTemplate, V as formatRelativeTime, W as groupToolActivity, X as inferResultView, Y as isActionCall, Z as phraseFor, _ as readPath, $ as resolveResultView, a0 as toolCallState, a1 as toolCatalogFrom } from './model-gHqjNjLJ.js';
 
 /**
@@ -294,6 +294,138 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private toChunkStream;
 }
 
+/** How a renderer is likely to show a file. */
+type MessageFileKind = 'image' | 'pdf' | 'text' | 'audio' | 'video' | 'other';
+/** One file on a message, live or replayed, with what a renderer needs to decide how to show it. */
+interface MessageFile {
+    url: string;
+    mediaType: string;
+    /** The original name, or `null` when the part carried none. */
+    filename: string | null;
+    kind: MessageFileKind;
+    /** Lower-case extension from the name (`'pdf'`), or `null`. */
+    extension: string | null;
+    /** The stored media id — present on files replayed from history (`StoredMessage.attachments`). */
+    mediaId: string | null;
+}
+/** The {@link MessageFileKind} of a MIME type. */
+declare function fileKind(mediaType: string): MessageFileKind;
+/**
+ * The files on a message — the user's attachments (live, or replayed from `StoredMessage.attachments`
+ * by `storedMessageToUiMessage`) and any the model produced — in part order. Data only: pair it with
+ * your own thumbnails/links.
+ */
+declare function messageFiles(message: Pick<UIMessage, 'parts'>): MessageFile[];
+/**
+ * Whether `file` matches an `accept` list in the `<input accept>` grammar: MIME types
+ * (`application/pdf`), wildcards (`image/*`) and extensions (`.csv`). An empty list accepts all.
+ */
+declare function acceptsFile(accept: string | readonly string[] | undefined, file: Pick<File, 'name' | 'type'>): boolean;
+/** Files carried by a paste — screenshots and copied files. Text-only pastes give `[]`. */
+declare function filesFromClipboard(data: DataTransfer | null | undefined): File[];
+/** Whether a drag carries files (as opposed to text or a link) — gate your drop highlight on it. */
+declare function dragHasFiles(data: DataTransfer | null | undefined): boolean;
+
+/** Where one staged file stands. `rejected` never uploaded (validation); `error` can be retried. */
+type StagedAttachmentStatus = 'uploading' | 'ready' | 'error' | 'rejected';
+interface StagedAttachment {
+    /** Local id, stable for the item's life — use it as the React key and for `remove`/`retry`. */
+    id: string;
+    file: File;
+    name: string;
+    size: number;
+    type: string;
+    status: StagedAttachmentStatus;
+    /** 0..1 while uploading (0 until the backend reports progress), 1 once ready. */
+    progress: number;
+    /** Why it was rejected or failed. */
+    error?: string;
+    /** What the server returned — present once `ready`. */
+    attachment?: MessageAttachment;
+    /** An object URL for image previews (revoked on remove/unmount), when the runtime has one. */
+    previewUrl?: string;
+}
+/** Why a file was turned away before any upload. */
+type AttachmentRejection = 'type' | 'size' | 'count';
+interface UseAttachmentsOptions {
+    /**
+     * Upload one file — defaults to `backend.uploadAttachment`. Resolve with what the server
+     * answered; honour `signal` so `remove` can cancel; call `onProgress(0..1)` if you can.
+     */
+    upload?: (file: File, options: UploadAttachmentOptions) => Promise<MessageAttachment>;
+    /** Used for the default `upload`. One of `upload` / `backend` is required. */
+    backend?: AgentBackend;
+    /** `<input accept>` grammar: `'image/*,.pdf'` or `['image/*', 'application/pdf']`. */
+    accept?: string | readonly string[];
+    /** Per-file ceiling, in bytes. */
+    maxBytes?: number;
+    /** How many files may be staged at once (rejected ones do not count). */
+    maxFiles?: number;
+    /** Words for a rejection; default English. */
+    describeRejection?: (reason: AttachmentRejection, file: File) => string;
+}
+interface AttachmentsState {
+    items: StagedAttachment[];
+    /** Stage files: validate, then upload each that passes. */
+    add: (files: Iterable<File> | ArrayLike<File> | null | undefined) => void;
+    /** Drop an item, cancelling its upload. */
+    remove: (id: string) => void;
+    /** Upload a failed item again. */
+    retry: (id: string) => void;
+    /** Drop everything — call after a send. */
+    clear: () => void;
+    /** An upload is still running — hold the send button. */
+    isUploading: boolean;
+    /** What to send: the ready uploads, in order. */
+    attachments: MessageAttachment[];
+    /** The same, as the `{ mediaId }` refs `POST <base>/chat` takes. */
+    refs: Array<{
+        mediaId: string;
+    }>;
+    /** Props for a hidden `<input type="file">`: `accept`, `multiple`, `onChange`. */
+    inputProps: {
+        type: 'file';
+        accept: string | undefined;
+        multiple: boolean;
+        onChange: (event: {
+            currentTarget: HTMLInputElement;
+        }) => void;
+    };
+    /** Handlers for any element that should take dropped files. */
+    dropZoneProps: {
+        onDragEnter: (event: DragLikeEvent) => void;
+        onDragOver: (event: DragLikeEvent) => void;
+        onDragLeave: (event: DragLikeEvent) => void;
+        onDrop: (event: DragLikeEvent) => void;
+    };
+    /** Files are being dragged over the drop zone — for a highlight. */
+    isDragging: boolean;
+    /** Paste handler for the composer: stages pasted files (screenshots), leaves text alone. */
+    onPaste: (event: ClipboardLikeEvent) => void;
+}
+/** The slice of a React/DOM drag event these handlers read. */
+interface DragLikeEvent {
+    dataTransfer: DataTransfer | null;
+    preventDefault: () => void;
+}
+/** The slice of a React/DOM clipboard event `onPaste` reads. */
+interface ClipboardLikeEvent {
+    clipboardData: DataTransfer | null;
+    preventDefault: () => void;
+}
+/**
+ * Staged attachments for a composer, headless: validation (`accept`, `maxBytes`, `maxFiles`),
+ * one upload per file with progress and cancel, retry, previews, and the event handlers for a file
+ * input, a drop zone and paste — no markup, no styles. Send `attachments` (or `refs`) with the
+ * message, then `clear()`:
+ *
+ * ```ts
+ * await chat.sendMessage({ text }, { body: { attachments: files.refs } });
+ * files.clear();
+ * ```
+ */
+declare function useAttachments(options: UseAttachmentsOptions): AttachmentsState;
+
 interface UseAgentsOptions {
     /** `useAgentChat(...).backend`, or your own. Must implement `listAgents`. */
     backend: AgentBackend;
@@ -570,6 +702,7 @@ declare class AgentClient implements AgentBackend {
      * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
      */
     uploadAttachment(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
+    private uploadWithProgress;
     promoteThread(id: string): Promise<OkResult>;
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
     /** `GET /agent/models?agent=` — the models this caller may pick, grouped by provider. */
@@ -620,6 +753,20 @@ declare class AgentClient implements AgentBackend {
     private handleResponse;
 }
 
+/** Draws a server-pushed component block. */
+type AmbientRenderUi = (block: TranscriptUiBlock) => ReactNode;
+/**
+ * How pushed components are drawn when no `renderUi` is passed — set by `<GenuiProvider>` (the
+ * `/genui` subpath) and read by `MessageItem`.
+ */
+declare const AmbientRenderUiContext: Context<AmbientRenderUi | null>;
+/**
+ * The renderer `<GenuiProvider>` installed for pushed components, or `null` outside one. For a
+ * custom transcript built on `useTranscriptItem`: draw a `ui` block with it and you get what
+ * `MessageItem` draws.
+ */
+declare function useAmbientRenderUi(): AmbientRenderUi | null;
+
 interface ChatInputProps {
     onSubmit: (text: string) => void;
     disabled?: boolean;
@@ -858,8 +1005,8 @@ type RenderTextFn = (text: string, ctx: {
 type RenderFilesFn = (files: TranscriptFile[]) => React__default.ReactNode;
 /**
  * Render a component the server pushed into the message — look `block.component` up in your own
- * registry. Omitted → pushed components are not drawn (there is no sensible default for an app's
- * own component).
+ * registry. Omitted → drawn by the enclosing `<GenuiProvider>` (`/genui`) if there is one, else not
+ * drawn (there is no sensible default for an app's own component).
  */
 type RenderUiFn = (block: TranscriptUiBlock) => React__default.ReactNode;
 /** Render the body of a reasoning run; the disclosure toggle around it stays this component's. */
@@ -894,7 +1041,10 @@ interface MessageRenderSlots {
     renderReasoning?: RenderReasoningFn;
     /** Draw files yourself — a gallery, a viewer. Omitted → images inline, everything else a link. */
     renderFiles?: RenderFilesFn;
-    /** Draw a server-pushed component (a `ui` stream frame). Omitted → not drawn. */
+    /**
+     * Draw a server-pushed component (a `ui` stream frame). Omitted → the enclosing `<GenuiProvider>`
+     * draws it; without one, not drawn.
+     */
     renderUi?: RenderUiFn;
     /**
      * Extra content for the action row, after the built-in affordances and before usage — a badge
@@ -937,7 +1087,7 @@ interface MessageItemViewProps extends MessageRenderSlots {
  */
 declare function MessageItem({ message, isStreaming, editable, onEditSubmit, regeneratable, onRegenerate, onFork, usage, createdAt, ...slots }: MessageItemProps): React__default.JSX.Element;
 /** The default markup for one modelled message — what `MessageItem` renders once it has an item. */
-declare function MessageItemView({ item, ...slots }: MessageItemViewProps): React__default.JSX.Element;
+declare function MessageItemView({ item, ...given }: MessageItemViewProps): React__default.JSX.Element;
 
 interface MessageListClassNames {
     root?: string;
@@ -1607,4 +1757,4 @@ declare class QuotaBlockedError extends Error {
     constructor(block: QuotaBlock);
 }
 
-export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatStreamRequest, type ChatStreamResponse, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type MessageFeedbackInput, type MessageFeedbackState, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, type QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type ResumeStreamRequest, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadPatch, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AttachmentRejection, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatStreamRequest, type ChatStreamResponse, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type MessageFeedbackInput, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, type QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type ResumeStreamRequest, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadPatch, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };