@meetsmore-oss/use-ai-client 1.2.4 → 1.3.0

package/dist/{chunk-EGD4LT6R.js → chunk-AKQM6IWU.js}

@@ -43,4 +43,4 @@ export {
   generateChatId,
   generateMessageId
 };
-//# sourceMappingURL=chunk-EGD4LT6R.js.map
+//# sourceMappingURL=chunk-AKQM6IWU.js.map

package/dist/chunk-AKQM6IWU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/chatRepository/types.ts"],"sourcesContent":["import type { PersistedFileMetadata } from '../../fileUpload/types';\n\n/**\n * Arbitrary metadata attached to a chat.\n * Use this to store context about the chat (e.g., how it was invoked, document type being processed).\n */\nexport type ChatMetadata = Record<string, unknown>;\n\n/**\n * Display mode for chat messages.\n * Determines the visual styling of the message bubble.\n */\nexport type MessageDisplayMode = 'default' | 'error';\n\n/**\n * Text content part for persisted messages.\n */\nexport interface PersistedTextContent {\n  type: 'text';\n  text: string;\n}\n\n/**\n * File content part for persisted messages.\n * Only stores metadata, not the actual file data.\n */\nexport interface PersistedFileContent {\n  type: 'file';\n  file: PersistedFileMetadata;\n}\n\n/**\n * Content part for persisted messages.\n * Can be text or file metadata.\n */\nexport type PersistedContentPart = PersistedTextContent | PersistedFileContent;\n\n/**\n * Content that can be persisted.\n * Simple string for text-only messages, or array for multimodal content.\n */\nexport type PersistedMessageContent = string | PersistedContentPart[];\n\n/**\n * Message format for persisted chat history.\n * Compatible with AI SDK's UIMessage format for future integration.\n */\nexport interface PersistedMessage {\n  id: string;\n  role: 'user' | 'assistant' | 'tool';\n  /** Content can be a string or multimodal content array */\n  content: PersistedMessageContent;\n  createdAt: Date;\n  displayMode?: MessageDisplayMode;\n}\n\n/**\n * Represents a stored chat conversation.\n */\nexport interface Chat {\n  id: string;\n  title?: string;\n  messages: PersistedMessage[];\n  createdAt: Date;\n  updatedAt: Date;\n  /** Arbitrary metadata attached to the chat */\n  metadata?: ChatMetadata;\n}\n\n/**\n * Options for creating a new chat.\n */\nexport interface CreateChatOptions {\n  title?: string;\n  /** Initial metadata for the chat */\n  metadata?: ChatMetadata;\n}\n\n/**\n * Options for listing chats.\n */\nexport interface ListChatsOptions {\n  limit?: number;\n  offset?: number;\n}\n\n/**\n * Abstract repository interface for chat persistence.\n * Implementations can store chats locally (localStorage, IndexedDB)\n * or remotely (REST API, GraphQL, etc.)\n */\nexport interface ChatRepository {\n  /**\n   * Creates a new chat and returns its ID.\n   * @param options Optional configuration for the new chat\n   * @returns Promise resolving to the new chat ID\n   */\n  createChat(options?: CreateChatOptions): Promise<string>;\n\n  /**\n   * Loads a chat by ID.\n   * @param id Chat ID to load\n   * @returns Promise resolving to the chat, or null if not found\n   */\n  loadChat(id: string): Promise<Chat | null>;\n\n  /**\n   * Saves or updates a chat.\n   * @param chat Chat to save\n   * @returns Promise resolving when save is complete\n   */\n  saveChat(chat: Chat): Promise<void>;\n\n  /**\n   * Deletes a chat by ID.\n   * @param id Chat ID to delete\n   * @returns Promise resolving when deletion is complete\n   */\n  deleteChat(id: string): Promise<void>;\n\n  /**\n   * Lists all available chats (metadata only, without full message history).\n   * @param options Optional pagination and filtering options\n   * @returns Promise resolving to array of chat metadata\n   */\n  listChats(options?: ListChatsOptions): Promise<Array<Omit<Chat, 'messages'>>>;\n\n  /**\n   * Deletes all stored chats.\n   * @returns Promise resolving when all chats are deleted\n   */\n  deleteAll(): Promise<void>;\n\n  /**\n   * Updates metadata for a chat.\n   * By default, merges with existing metadata. Set `overwrite: true` to replace entirely.\n   * @param id Chat ID\n   * @param metadata Metadata to set/merge\n   * @param overwrite If true, replaces all metadata instead of merging\n   * @returns Promise resolving when update is complete\n   */\n  updateMetadata(id: string, metadata: ChatMetadata, overwrite?: boolean): Promise<void>;\n}\n\n/**\n * Generates a unique chat ID.\n */\nexport function generateChatId(): string {\n  return `chat_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n}\n\n/**\n * Generates a unique message ID.\n */\nexport function generateMessageId(): string {\n  return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmJO,SAAS,iBAAyB;AACvC,SAAO,QAAQ,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,GAAG,CAAC,CAAC;AACzE;AAKO,SAAS,oBAA4B;AAC1C,SAAO,OAAO,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,GAAG,CAAC,CAAC;AACxE;","names":[]}

package/dist/{chunk-EGKUR4C7.js → chunk-QTQR7MAU.js}

@@ -10,4 +10,4 @@ export {
   generateChatId,
   generateMessageId
 };
-//# sourceMappingURL=chunk-EGKUR4C7.js.map
+//# sourceMappingURL=chunk-QTQR7MAU.js.map

package/dist/chunk-QTQR7MAU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/chatRepository/types.ts"],"sourcesContent":["import type { PersistedFileMetadata } from '../../fileUpload/types';\n\n/**\n * Arbitrary metadata attached to a chat.\n * Use this to store context about the chat (e.g., how it was invoked, document type being processed).\n */\nexport type ChatMetadata = Record<string, unknown>;\n\n/**\n * Display mode for chat messages.\n * Determines the visual styling of the message bubble.\n */\nexport type MessageDisplayMode = 'default' | 'error';\n\n/**\n * Text content part for persisted messages.\n */\nexport interface PersistedTextContent {\n  type: 'text';\n  text: string;\n}\n\n/**\n * File content part for persisted messages.\n * Only stores metadata, not the actual file data.\n */\nexport interface PersistedFileContent {\n  type: 'file';\n  file: PersistedFileMetadata;\n}\n\n/**\n * Content part for persisted messages.\n * Can be text or file metadata.\n */\nexport type PersistedContentPart = PersistedTextContent | PersistedFileContent;\n\n/**\n * Content that can be persisted.\n * Simple string for text-only messages, or array for multimodal content.\n */\nexport type PersistedMessageContent = string | PersistedContentPart[];\n\n/**\n * Message format for persisted chat history.\n * Compatible with AI SDK's UIMessage format for future integration.\n */\nexport interface PersistedMessage {\n  id: string;\n  role: 'user' | 'assistant' | 'tool';\n  /** Content can be a string or multimodal content array */\n  content: PersistedMessageContent;\n  createdAt: Date;\n  displayMode?: MessageDisplayMode;\n}\n\n/**\n * Represents a stored chat conversation.\n */\nexport interface Chat {\n  id: string;\n  title?: string;\n  messages: PersistedMessage[];\n  createdAt: Date;\n  updatedAt: Date;\n  /** Arbitrary metadata attached to the chat */\n  metadata?: ChatMetadata;\n}\n\n/**\n * Options for creating a new chat.\n */\nexport interface CreateChatOptions {\n  title?: string;\n  /** Initial metadata for the chat */\n  metadata?: ChatMetadata;\n}\n\n/**\n * Options for listing chats.\n */\nexport interface ListChatsOptions {\n  limit?: number;\n  offset?: number;\n}\n\n/**\n * Abstract repository interface for chat persistence.\n * Implementations can store chats locally (localStorage, IndexedDB)\n * or remotely (REST API, GraphQL, etc.)\n */\nexport interface ChatRepository {\n  /**\n   * Creates a new chat and returns its ID.\n   * @param options Optional configuration for the new chat\n   * @returns Promise resolving to the new chat ID\n   */\n  createChat(options?: CreateChatOptions): Promise<string>;\n\n  /**\n   * Loads a chat by ID.\n   * @param id Chat ID to load\n   * @returns Promise resolving to the chat, or null if not found\n   */\n  loadChat(id: string): Promise<Chat | null>;\n\n  /**\n   * Saves or updates a chat.\n   * @param chat Chat to save\n   * @returns Promise resolving when save is complete\n   */\n  saveChat(chat: Chat): Promise<void>;\n\n  /**\n   * Deletes a chat by ID.\n   * @param id Chat ID to delete\n   * @returns Promise resolving when deletion is complete\n   */\n  deleteChat(id: string): Promise<void>;\n\n  /**\n   * Lists all available chats (metadata only, without full message history).\n   * @param options Optional pagination and filtering options\n   * @returns Promise resolving to array of chat metadata\n   */\n  listChats(options?: ListChatsOptions): Promise<Array<Omit<Chat, 'messages'>>>;\n\n  /**\n   * Deletes all stored chats.\n   * @returns Promise resolving when all chats are deleted\n   */\n  deleteAll(): Promise<void>;\n\n  /**\n   * Updates metadata for a chat.\n   * By default, merges with existing metadata. Set `overwrite: true` to replace entirely.\n   * @param id Chat ID\n   * @param metadata Metadata to set/merge\n   * @param overwrite If true, replaces all metadata instead of merging\n   * @returns Promise resolving when update is complete\n   */\n  updateMetadata(id: string, metadata: ChatMetadata, overwrite?: boolean): Promise<void>;\n}\n\n/**\n * Generates a unique chat ID.\n */\nexport function generateChatId(): string {\n  return `chat_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n}\n\n/**\n * Generates a unique message ID.\n */\nexport function generateMessageId(): string {\n  return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n}\n"],"mappings":";AAmJO,SAAS,iBAAyB;AACvC,SAAO,QAAQ,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,GAAG,CAAC,CAAC;AACzE;AAKO,SAAS,oBAA4B;AAC1C,SAAO,OAAO,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,GAAG,CAAC,CAAC;AACxE;","names":[]}

package/dist/index.d.ts

@@ -316,6 +316,11 @@ interface FileAttachment {
     file: File;
     /** Data URL for image thumbnails (generated on attach for preview) */
     preview?: string;
+    /**
+     * Transformed content (if a transformer matched this file's MIME type).
+     * Populated asynchronously after attachment - check processingState for status.
+     */
+    transformedContent?: string;
 }
 /**
  * Abstract file upload backend interface.
@@ -337,6 +342,55 @@ interface FileUploadBackend {
      */
     prepareForSend(file: File): Promise<string>;
 }
+/**
+ * Context provided to file transformers.
+ */
+interface FileTransformerContext {
+    /** The current chat (includes metadata) */
+    chat: Chat | null;
+}
+/**
+ * A transformer that converts files into string representations for the AI.
+ */
+interface FileTransformer {
+    /**
+     * Transform the file into a string representation for the AI.
+     *
+     * @param file - The file to transform
+     * @param context - Context including the current chat and its metadata
+     * @param onProgress - Optional callback for reporting progress (0-100).
+     *                     If called, UI shows progress bar; otherwise shows spinner.
+     * @returns A string representation the AI will receive
+     * @throws If transformation fails
+     */
+    transform(file: File, context: FileTransformerContext, onProgress?: (progress: number) => void): Promise<string>;
+}
+/**
+ * Map of MIME type patterns to transformers.
+ *
+ * Keys are MIME type patterns:
+ * - Exact match: 'application/pdf'
+ * - Partial wildcard: 'image/*'
+ * - Global wildcard: '*' or '*\/*'
+ *
+ * When multiple patterns match, the most specific one wins:
+ * 1. Exact match (e.g., 'application/pdf')
+ * 2. Partial wildcard (e.g., 'image/*')
+ * 3. Global wildcard ('*' or '*\/*')
+ */
+type FileTransformerMap = Record<string, FileTransformer>;
+/**
+ * Status of file processing during send.
+ */
+type FileProcessingStatus = 'idle' | 'processing' | 'done' | 'error';
+/**
+ * Processing state for a file attachment.
+ */
+interface FileProcessingState {
+    status: FileProcessingStatus;
+    /** Progress 0-100, or undefined for indeterminate (spinner) */
+    progress?: number;
+}
 /**
  * Configuration for file uploads in UseAIProvider.
  */
@@ -357,8 +411,19 @@ interface FileUploadConfig {
      * If undefined, all types are accepted.
      */
     acceptedTypes?: string[];
+    /**
+     * Map of MIME type patterns to transformers.
+     * Files matching a transformer pattern will be converted to text
+     * before being sent to the AI.
+     */
+    transformers?: FileTransformerMap;
 }
 
+/**
+ * Arbitrary metadata attached to a chat.
+ * Use this to store context about the chat (e.g., how it was invoked, document type being processed).
+ */
+type ChatMetadata = Record<string, unknown>;
 /**
  * Display mode for chat messages.
  * Determines the visual styling of the message bubble.
@@ -410,12 +475,16 @@ interface Chat {
     messages: PersistedMessage[];
     createdAt: Date;
     updatedAt: Date;
+    /** Arbitrary metadata attached to the chat */
+    metadata?: ChatMetadata;
 }
 /**
  * Options for creating a new chat.
  */
 interface CreateChatOptions {
     title?: string;
+    /** Initial metadata for the chat */
+    metadata?: ChatMetadata;
 }
 /**
  * Options for listing chats.
@@ -465,6 +534,15 @@ interface ChatRepository {
      * @returns Promise resolving when all chats are deleted
      */
     deleteAll(): Promise<void>;
+    /**
+     * Updates metadata for a chat.
+     * By default, merges with existing metadata. Set `overwrite: true` to replace entirely.
+     * @param id Chat ID
+     * @param metadata Metadata to set/merge
+     * @param overwrite If true, replaces all metadata instead of merging
+     * @returns Promise resolving when update is complete
+     */
+    updateMetadata(id: string, metadata: ChatMetadata, overwrite?: boolean): Promise<void>;
 }
 /**
  * Generates a unique chat ID.
@@ -743,6 +821,8 @@ interface UseAIChatPanelProps {
     onLoadChat?: (chatId: string) => Promise<void>;
     onDeleteChat?: (chatId: string) => Promise<void>;
     onListChats?: () => Promise<Array<Omit<Chat, 'messages'>>>;
+    /** Gets the current chat */
+    onGetChat?: () => Promise<Chat | null>;
     suggestions?: string[];
     availableAgents?: AgentInfo[];
     defaultAgent?: string | null;
@@ -760,7 +840,7 @@ interface UseAIChatPanelProps {
  * Chat panel content - fills its container.
  * Use directly for embedded mode, or wrap with UseAIFloatingChatWrapper for floating mode.
  */
-declare function UseAIChatPanel({ onSendMessage, messages, loading, connected, streamingText, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, commands, onSaveCommand, onRenameCommand, onDeleteCommand, closeButton, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
+declare function UseAIChatPanel({ onSendMessage, messages, loading, connected, streamingText, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, onGetChat, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, commands, onSaveCommand, onRenameCommand, onDeleteCommand, closeButton, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Handler for AG-UI events from the server.
@@ -980,6 +1060,105 @@ declare class UseAIClient {
     isConnected(): boolean;
 }
 
+/**
+ * Options for programmatically sending a message via sendMessage().
+ */
+interface SendMessageOptions {
+    /** Start a new chat before sending. Default: false (continue existing chat) */
+    newChat?: boolean;
+    /** File attachments to include with the message */
+    attachments?: File[];
+    /** Open the chat panel after sending. Default: true */
+    openChat?: boolean;
+    /** Metadata to set on the new chat (only used when newChat: true) */
+    metadata?: ChatMetadata;
+}
+interface UseChatManagementOptions {
+    /** Chat repository for persistence */
+    repository: ChatRepository;
+    /** Reference to the UseAIClient (can be null during initialization) */
+    clientRef: React.MutableRefObject<UseAIClient | null>;
+    /** Callback to send a message (from UseAIProvider) */
+    onSendMessage?: (message: string, attachments?: FileAttachment[]) => Promise<void>;
+    /** Callback to open/close the chat panel */
+    setOpen?: (open: boolean) => void;
+    /** Whether the client is connected */
+    connected?: boolean;
+    /** Whether the AI is currently loading/processing a response */
+    loading?: boolean;
+}
+interface UseChatManagementReturn {
+    /** Current active chat ID where AI responses are saved */
+    currentChatId: string | null;
+    /** Chat loaded for viewing but not yet active for AI responses */
+    pendingChatId: string | null;
+    /** Current messages in the chat */
+    messages: Message[];
+    /** The displayed chat ID (pending or current) */
+    displayedChatId: string | null;
+    /** Creates a new chat and switches to it */
+    createNewChat: (options?: CreateChatOptions) => Promise<string>;
+    /** Loads an existing chat by ID */
+    loadChat: (chatId: string) => Promise<void>;
+    /** Deletes a chat by ID */
+    deleteChat: (chatId: string) => Promise<void>;
+    /** Lists all available chats */
+    listChats: () => Promise<Array<Omit<Chat, 'messages'>>>;
+    /** Clears the current chat messages */
+    clearCurrentChat: () => Promise<void>;
+    /** Activates the pending chat (called when user sends first message) */
+    activatePendingChat: () => string | null;
+    /** Saves a user message to storage and reloads messages */
+    saveUserMessage: (chatId: string, content: PersistedMessageContent) => Promise<boolean>;
+    /** Saves an AI response to storage and optionally reloads messages */
+    saveAIResponse: (content: string, displayMode?: 'default' | 'error') => Promise<void>;
+    /** Reloads messages from storage for the given chat ID */
+    reloadMessages: (chatId: string) => Promise<void>;
+    /**
+     * Programmatically send a message to the chat.
+     * Throws on failure (e.g., not connected, no onSendMessage callback).
+     */
+    sendMessage: (message: string, options?: SendMessageOptions) => Promise<void>;
+    /** Get the current chat object. Metadata is frozen to prevent accidental mutation. */
+    getCurrentChat: () => Promise<Chat | null>;
+    /** Update metadata for the current chat */
+    updateMetadata: (metadata: ChatMetadata, overwrite?: boolean) => Promise<void>;
+    /** Snapshot refs for use in event handlers */
+    currentChatIdSnapshot: React.MutableRefObject<string | null>;
+    pendingChatIdSnapshot: React.MutableRefObject<string | null>;
+}
+/**
+ * Hook for managing chat lifecycle operations.
+ *
+ * Features:
+ * - Creates, loads, deletes chats
+ * - Manages pending/active chat state machine
+ * - Saves user messages and AI responses
+ * - Auto-generates chat titles
+ * - Initializes with most recent chat or creates new one
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   currentChatId,
+ *   pendingChatId,
+ *   messages,
+ *   createNewChat,
+ *   loadChat,
+ *   deleteChat,
+ *   listChats,
+ *   clearCurrentChat,
+ *   activatePendingChat,
+ *   saveUserMessage,
+ *   saveAIResponse,
+ * } = useChatManagement({
+ *   repository: chatRepository,
+ *   clientRef,
+ * });
+ * ```
+ */
+declare function useChatManagement({ repository, clientRef, onSendMessage, setOpen, connected, loading, }: UseChatManagementOptions): UseChatManagementReturn;
+
 /**
  * Chat management context (from useChatManagement hook).
  */
@@ -987,7 +1166,7 @@ interface ChatContextValue {
     /** The current chat ID */
     currentId: string | null;
     /** Creates a new chat and switches to it */
-    create: () => Promise<string>;
+    create: (options?: CreateChatOptions) => Promise<string>;
     /** Loads an existing chat by ID */
     load: (chatId: string) => Promise<void>;
     /** Deletes a chat by ID */
@@ -996,6 +1175,19 @@ interface ChatContextValue {
     list: () => Promise<Array<Omit<Chat, 'messages'>>>;
     /** Clears the current chat messages */
     clear: () => Promise<void>;
+    /**
+     * Programmatically send a message to the chat.
+     * Throws on failure (e.g., not connected).
+     */
+    sendMessage: (message: string, options?: SendMessageOptions) => Promise<void>;
+    /** Get the current chat object. Metadata is frozen to prevent accidental mutation. */
+    get: () => Promise<Chat | null>;
+    /**
+     * Update metadata for the current chat.
+     * @param metadata Metadata to set/merge
+     * @param overwrite If true, replaces all metadata instead of merging (default: false)
+     */
+    updateMetadata: (metadata: ChatMetadata, overwrite?: boolean) => Promise<void>;
 }
 /**
  * Agent selection context (from useAgentSelection hook).
@@ -1207,6 +1399,30 @@ interface UseAIProviderProps extends UseAIConfig {
      * ```
      */
     visibleAgentIds?: AgentInfo['id'][];
+    /**
+     * Callback when the chat open state should change.
+     * Called by programmatic actions like `sendMessage({ openChat: true })`.
+     * Useful when `renderChat=false` and you control the chat panel's visibility externally.
+     *
+     * @example
+     * ```tsx
+     * const [sidebarOpen, setSidebarOpen] = useState(false);
+     *
+     * <UseAIProvider
+     *   serverUrl="ws://localhost:8081"
+     *   renderChat={false}
+     *   onOpenChange={(isOpen) => {
+     *     // Sync with external sidebar state
+     *     setSidebarOpen(isOpen);
+     *   }}
+     * >
+     *   <Sidebar isOpen={sidebarOpen} onClose={() => setSidebarOpen(false)}>
+     *     <UseAIChat />
+     *   </Sidebar>
+     * </UseAIProvider>
+     * ```
+     */
+    onOpenChange?: (isOpen: boolean) => void;
 }
 /**
  * Provider component that manages AI client connection and tool registration.
@@ -1236,7 +1452,7 @@ interface UseAIProviderProps extends UseAIConfig {
  * }
  * ```
  */
-declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, mcpHeadersProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, }: UseAIProviderProps): react_jsx_runtime.JSX.Element;
+declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, mcpHeadersProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, onOpenChange, }: UseAIProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the UseAI context.
  * When used outside a UseAIProvider, returns a no-op context and logs a warning.
@@ -1356,6 +1572,7 @@ declare class LocalStorageChatRepository implements ChatRepository {
     deleteChat(id: string): Promise<void>;
     listChats(options?: ListChatsOptions): Promise<Array<Omit<Chat, 'messages'>>>;
     deleteAll(): Promise<void>;
+    updateMetadata(id: string, metadata: ChatMetadata, overwrite?: boolean): Promise<void>;
     private getChatKey;
     private getIndex;
     private addToIndex;
@@ -1415,6 +1632,8 @@ interface DropZoneProps {
     onDrop: (e: React$1.DragEvent) => void;
 }
 interface UseFileUploadOptions {
+    /** Function to get the current chat (for transformer context) */
+    getCurrentChat: () => Promise<Chat | null>;
     /** Configuration for file uploads. If undefined, file upload is disabled. */
     config?: FileUploadConfig;
     /** Whether file operations should be disabled (e.g., during loading) */
@@ -1435,6 +1654,8 @@ interface UseFileUploadReturn {
     maxFileSize: number;
     /** Accepted MIME types */
     acceptedTypes?: string[];
+    /** Processing state for each file (by attachment ID) */
+    processingState: Map<string, FileProcessingState>;
     /** Ref to attach to hidden file input */
     fileInputRef: React$1.MutableRefObject<HTMLInputElement | null>;
     /** Validates and adds files to attachments */
@@ -1490,7 +1711,69 @@ interface UseFileUploadReturn {
  * });
  * ```
  */
-declare function useFileUpload({ config, disabled, resetDependency, }: UseFileUploadOptions): UseFileUploadReturn;
+declare function useFileUpload({ config, disabled, resetDependency, getCurrentChat, }: UseFileUploadOptions): UseFileUploadReturn;
+
+/**
+ * Check if a MIME type matches a pattern.
+ * Supports exact match and wildcard patterns ending with '*'.
+ *
+ * Examples:
+ * - 'application/pdf' matches 'application/pdf' (exact)
+ * - 'image/png' matches 'image/*' (partial wildcard)
+ * - 'text/plain' matches '*' (global wildcard)
+ * - 'text/plain' matches '*\/*' (global wildcard)
+ */
+declare function matchesMimeType(mimeType: string, pattern: string): boolean;
+/**
+ * Find the most specific transformer for a MIME type.
+ *
+ * Specificity rules:
+ * 1. Exact match (no wildcard) always wins
+ * 2. Among wildcard patterns, longer pattern = more specific
+ *
+ * Example for 'image/png':
+ * - 'image/png' (exact, wins)
+ * - 'image/*' (length 7, second)
+ * - '*' (length 1, last)
+ */
+declare function findTransformer(mimeType: string, transformers: FileTransformerMap | undefined): FileTransformer | undefined;
+
+/**
+ * Configuration for processing file attachments.
+ */
+interface ProcessAttachmentsConfig {
+    /** Function to get the current chat (for transformer context) */
+    getCurrentChat: () => Promise<Chat | null>;
+    /** Backend for converting files to URLs (default: EmbedFileUploadBackend) */
+    backend?: FileUploadBackend;
+    /** Map of MIME type patterns to transformers */
+    transformers?: FileTransformerMap;
+    /** Called when a file's processing state changes */
+    onFileProgress?: (fileId: string, state: FileProcessingState) => void;
+}
+/**
+ * Process file attachments into multimodal content for AI.
+ * Handles transformation (with caching) or URL encoding.
+ *
+ * @param attachments - The file attachments to process
+ * @param config - Processing configuration
+ * @returns Array of multimodal content parts
+ * @throws On any processing error - caller should handle and show to user
+ *
+ * @example
+ * ```typescript
+ * const content = await processAttachments(attachments, {
+ *   transformers: { 'application/pdf': pdfTransformer },
+ *   onFileProgress: (id, state) => setProgress(prev => new Map(prev).set(id, state)),
+ * });
+ * ```
+ */
+declare function processAttachments(attachments: FileAttachment[], config: ProcessAttachmentsConfig): Promise<MultimodalContent[]>;
+/**
+ * Clear the transformation cache.
+ * Useful for testing or when memory needs to be freed.
+ */
+declare function clearTransformationCache(): void;
 
 /**
  * LocalStorage-based implementation of CommandRepository.
@@ -1630,75 +1913,6 @@ interface UseSlashCommandsReturn {
  */
 declare function useSlashCommands({ commands, onCommandSelect, onSaveCommand, onRenameCommand, onDeleteCommand, }: UseSlashCommandsOptions): UseSlashCommandsReturn;
 
-interface UseChatManagementOptions {
-    /** Chat repository for persistence */
-    repository: ChatRepository;
-    /** Reference to the UseAIClient (can be null during initialization) */
-    clientRef: React.MutableRefObject<UseAIClient | null>;
-}
-interface UseChatManagementReturn {
-    /** Current active chat ID where AI responses are saved */
-    currentChatId: string | null;
-    /** Chat loaded for viewing but not yet active for AI responses */
-    pendingChatId: string | null;
-    /** Current messages in the chat */
-    messages: Message[];
-    /** The displayed chat ID (pending or current) */
-    displayedChatId: string | null;
-    /** Creates a new chat and switches to it */
-    createNewChat: () => Promise<string>;
-    /** Loads an existing chat by ID */
-    loadChat: (chatId: string) => Promise<void>;
-    /** Deletes a chat by ID */
-    deleteChat: (chatId: string) => Promise<void>;
-    /** Lists all available chats */
-    listChats: () => Promise<Array<Omit<Chat, 'messages'>>>;
-    /** Clears the current chat messages */
-    clearCurrentChat: () => Promise<void>;
-    /** Activates the pending chat (called when user sends first message) */
-    activatePendingChat: () => string | null;
-    /** Saves a user message to storage and reloads messages */
-    saveUserMessage: (chatId: string, content: PersistedMessageContent) => Promise<boolean>;
-    /** Saves an AI response to storage and optionally reloads messages */
-    saveAIResponse: (content: string, displayMode?: 'default' | 'error') => Promise<void>;
-    /** Reloads messages from storage for the given chat ID */
-    reloadMessages: (chatId: string) => Promise<void>;
-    /** Snapshot refs for use in event handlers */
-    currentChatIdSnapshot: React.MutableRefObject<string | null>;
-    pendingChatIdSnapshot: React.MutableRefObject<string | null>;
-}
-/**
- * Hook for managing chat lifecycle operations.
- *
- * Features:
- * - Creates, loads, deletes chats
- * - Manages pending/active chat state machine
- * - Saves user messages and AI responses
- * - Auto-generates chat titles
- * - Initializes with most recent chat or creates new one
- *
- * @example
- * ```typescript
- * const {
- *   currentChatId,
- *   pendingChatId,
- *   messages,
- *   createNewChat,
- *   loadChat,
- *   deleteChat,
- *   listChats,
- *   clearCurrentChat,
- *   activatePendingChat,
- *   saveUserMessage,
- *   saveAIResponse,
- * } = useChatManagement({
- *   repository: chatRepository,
- *   clientRef,
- * });
- * ```
- */
-declare function useChatManagement({ repository, clientRef, }: UseChatManagementOptions): UseChatManagementReturn;
-
 interface UseAgentSelectionOptions {
     /** Reference to the UseAIClient (can be null during initialization) */
     clientRef: React.MutableRefObject<UseAIClient | null>;
@@ -1948,4 +2162,4 @@ interface UseDropdownStateOptions {
  */
 declare function useDropdownState(options?: UseDropdownStateOptions): UseDropdownStateReturn;
 
-export { type AgentContextValue, type Chat, type ChatContextValue, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type FileAttachment, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolRegistryReturn, type WorkflowProgress, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, generateChatId, generateCommandId, generateMessageId, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFileUpload, usePromptState, useSlashCommands, useStableTools, useStrings, useTheme, useToolRegistry, validateCommandName };
+export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolRegistryReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformer, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFileUpload, usePromptState, useSlashCommands, useStableTools, useStrings, useTheme, useToolRegistry, validateCommandName };