veryfront 0.1.997 → 0.1.998

package/esm/src/react/components/chat/chat/index.js

@@ -10,23 +10,21 @@
  *
  * export default function Page() {
  *   const chat = useChat();
- *   return (
- *     <Chat
- *       messages={chat.messages}
- *       input={chat.input}
- *       onChange={chat.handleInputChange}
- *       onSubmit={chat.handleSubmit}
- *     />
- *   );
+ *   return <Chat chat={chat} />;
  * }
  * ```
  *
+ * @example App mode (black box — no wiring)
+ * ```tsx
+ * <Chat agentId="support" api="/api/ag-ui" />
+ * ```
+ *
  * @example Custom layout (composition)
  * ```tsx
  * <Chat.Root messages={messages} input={input}>
  *   <Chat.Empty title="Ask anything" />
  *   <Chat.MessageList messages={messages} />
- *   <Chat.Composer input={input} onChange={onChange} />
+ *   <Chat.Input input={input} onChange={onChange} />
  * </Chat.Root>
  * ```
  *
@@ -44,94 +42,140 @@
  * @module react/components/chat
  */
 import * as React from "../../../../../react/react.js";
-import { useVoiceInput } from "../../../../agent/react/index.js";
+import { useChat, useVoiceInput } from "../../../../agent/react/index.js";
+import { useAgentMetadata } from "../../../../agent/react/use-agent-metadata.js";
 import { defaultChatTheme, mergeThemes } from "../theme.js";
+import { useUpload } from "./hooks/use-upload.js";
 // Composition imports (used in the Chat preset)
 import { ChatRoot } from "./composition/chat-root.js";
-import { ChatComposer } from "./composition/chat-composer.js";
+import { ChatInput } from "./composition/chat-composer.js";
 import { ChatMessageList } from "./composition/chat-message-list.js";
 import { ChatEmpty } from "./composition/chat-empty.js";
+import { AgentAvatar } from "./composition/agent-avatar.js";
 import { ChatIf } from "./composition/chat-if.js";
 import { ErrorBanner } from "./composition/error-banner.js";
 import { Message } from "./composition/message.js";
-import { DropZoneOverlay } from "./components/drop-zone.js";
+import { ChatMessagesSkeleton } from "./components/chat-messages-skeleton.js";
 import { TabSwitcher } from "./components/tab-switcher.js";
-import { UploadsPanel } from "./components/uploads-panel.js";
+import { AttachmentsPanel } from "./components/attachments-panel.js";
 import { InferenceBadge } from "./components/inference-badge.js";
 import { QuickActions as QuickActionsComponent } from "./components/quick-actions.js";
 // ---------------------------------------------------------------------------
 // Re-exports — sub-components
 // ---------------------------------------------------------------------------
 export { FadeIn, Loader, Shimmer } from "./components/animations.js";
-export { ReasoningCard } from "./components/reasoning.js";
+export { Reasoning, ReasoningCard, useReasoning, } from "./components/reasoning.js";
 export { ConversationEmptyState, ConversationScrollButton, Suggestion, Suggestions, } from "./components/empty-state.js";
-export { MessageActions } from "./components/message-actions.js";
+export { MessageActionBar } from "./components/message-actions.js";
 export { MessageEditForm } from "./components/message-edit-form.js";
 export { BranchPicker } from "./components/branch-picker.js";
 export { DropZoneOverlay } from "./components/drop-zone.js";
+export { ChatMessagesSkeleton, } from "./components/chat-messages-skeleton.js";
 export { SkillBadge } from "./components/skill-badge.js";
-export { ToolCallCard, ToolStatusBadge } from "./components/tool-ui.js";
+export { ToolCall, ToolCallCard, ToolStatusBadge, useToolCall, } from "./components/tool-ui.js";
 export { InferenceBadge } from "./components/inference-badge.js";
-export { Sources } from "./components/sources.js";
+export { SourcePill, Sources, useSources, } from "./components/sources.js";
 export { InlineCitation } from "./components/inline-citation.js";
 export { MessageFeedback, } from "./components/message-feedback.js";
-export { AttachmentPill, } from "./components/attachment-pill.js";
+export { AttachmentPill, useAttachmentPill, } from "./components/attachment-pill.js";
 export { RichCodeBlock } from "./components/code-block.js";
-export { StepIndicator } from "./components/step-indicator.js";
-export { ChatSidebar } from "./components/sidebar.js";
+export { StepIndicator, useStepIndicator, } from "./components/step-indicator.js";
+// The sub-components (`ChatSidebar.Root` / `.Item` / …) hang off the compound
+// object, so only the preset needs to be a runtime export. The rest are
+// type-only — they annotate props without widening the public runtime surface.
+export { ChatSidebar, } from "./components/sidebar.js";
 export { TabSwitcher } from "./components/tab-switcher.js";
 export { QuickActions, } from "./components/quick-actions.js";
-export { UploadsPanel, } from "./components/uploads-panel.js";
+export { AttachmentsPanel, useAttachmentsPanel, } from "./components/attachments-panel.js";
 // Re-exports — hooks
-export { useThreads, } from "./hooks/use-threads.js";
+export { useConversations, } from "./hooks/use-conversations.js";
+export { useConversation, } from "./hooks/use-conversation.js";
+export { ConversationsContextProvider, ConversationsProvider, useConversationsContext, useConversationsContextOptional, } from "./contexts/conversations-context.js";
+// Local binding for the `<Chat>` optional-provider integration below (the line
+// above only re-exports; it does not import the name for use in this module).
+import { useConversationsContextOptional } from "./contexts/conversations-context.js";
+import { createEmptyConversation, DEFAULT_CONVERSATION_TITLE, deriveTitle, } from "./hooks/use-conversations.js";
+export { localConversationStore, } from "./persistence/local-conversation-store.js";
+export { memoryConversationStore } from "./persistence/memory-conversation-store.js";
+export { useUpload } from "./hooks/use-upload.js";
+export { useUploadsRegistry, } from "./hooks/use-uploads-registry.js";
+export { useStickToBottom, } from "./hooks/use-stick-to-bottom.js";
 // Re-exports — utils
 export { extractSourcesFromParts, getTextContent, groupPartsInOrder, isReasoningPart, isSkillToolPart, isToolPart, } from "./utils/message-parts.js";
 export { downloadMarkdown, exportAsMarkdown } from "./utils/export.js";
 // Re-exports — composition
-export { AgentAvatar, ChatComposer, ChatEmpty, ChatIf, ChatMessageList, ChatRoot, ErrorBanner, Message, ModelAvatar, } from "./composition/api.js";
+export { AgentAvatar, ChatEmpty, ChatEmptyState, ChatIf, ChatInput, ChatMessageList, ChatRoot, ErrorBanner, Message, ModelAvatar, } from "./composition/api.js";
 // Re-exports — contexts
-export { ChatContextProvider, ComposerContextProvider, MessageContextProvider, ThreadListContextProvider, useChatContext, useChatContextOptional, useComposerContext, useComposerContextOptional, useMessageContext, useMessageContextOptional, useThreadListContext, useThreadListContextOptional, } from "./contexts/index.js";
+export { ChatContextProvider, ComposerContextProvider, MessageContextProvider, useChatContext, useChatContextOptional, useComposerContext, useComposerContextOptional, useMessageContext, useMessageContextOptional, } from "./contexts/index.js";
 // ---------------------------------------------------------------------------
 // Chat — Preset component
 //
-// Composes ChatRoot, ChatMessageList, ChatComposer, ChatEmpty, etc. into a
+// Composes ChatRoot, ChatMessageList, ChatInput, ChatEmpty, etc. into a
 // full-featured chat UI with sensible defaults. For custom layouts, use the
 // building blocks directly.
 // ---------------------------------------------------------------------------
-/** Render chat. */
-export const Chat = React.forwardRef(function Chat({ messages, input, onChange, onSubmit, stop, reload, enableVoice = false, onVoice, setInput, isLoading, error, placeholder = "Type a message...", maxHeight = "100%", className, theme: userTheme, renderMessage, renderTool, suggestions, onSuggestionClick, emptyState, showScrollButton = false, showMessageActions = true, models, model, activeModel, onModelChange, inferenceMode, showSources = false, onSourceClick, onAttach, onSelectAttachment, onDrop, attachAccept, attachments, onRemoveAttachment, showExport = false, onFeedback, editMessage, getBranches, switchBranch, showSteps = false, showTabs = false, activeTab: controlledTab, onTabChange: controlledTabChange, uploads, onRemoveUpload, quickActions, onQuickAction, hideTabSwitcher = false, children, }, ref) {
-    const theme = React.useMemo(() => mergeThemes(defaultChatTheme, userTheme), [userTheme]);
-    // --- Drag-and-drop ---
-    const dropHandler = onDrop ?? onAttach;
-    const [dragOver, setDragOver] = React.useState(false);
-    const dragCounter = React.useRef(0);
-    const handleDragEnter = React.useCallback((e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        dragCounter.current++;
-        if (e.dataTransfer.types.includes("Files"))
-            setDragOver(true);
-    }, []);
-    const handleDragLeave = React.useCallback((e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        dragCounter.current--;
-        if (dragCounter.current === 0)
-            setDragOver(false);
-    }, []);
-    const handleDragOver = React.useCallback((e) => {
-        e.preventDefault();
-        e.stopPropagation();
-    }, []);
-    const handleFileDrop = React.useCallback((e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        dragCounter.current = 0;
-        setDragOver(false);
-        if (e.dataTransfer.files.length > 0 && dropHandler) {
-            dropHandler(e.dataTransfer.files);
+/** Render the controlled chat (caller supplies `messages`/`input`). */
+const ControlledChat = React.forwardRef(function ControlledChat({ messages = [], input = "", onChange = () => { }, onSubmit, sendMessage, stop, reload, enableVoice = false, onVoice, setInput, isLoading, error, placeholder = "Type a message...", maxHeight = "100%", className, theme: userTheme, renderMessage, renderTool, suggestions, onSuggestionClick, emptyState, initializing = false, skeleton, agent, showScrollButton = false, showMessageActions = true, models, model, activeModel, onModelChange, inferenceMode, showSources = false, onSourceClick, enableAttachments = true, uploadApi, onAttach, onSelectAttachment, onDrop, attachAccept, attachments, onRemoveAttachment, showExport = false, onFeedback, editMessage, getBranches, switchBranch, showSteps = false, showTabs = false, activeTab: controlledTab, onTabChange: controlledTabChange, uploads, onRemoveUpload, quickActions, onQuickAction, toolbarStart, hideTabSwitcher = false, children, }, ref) {
+    const theme = React.useMemo(() => mergeThemes(defaultChatTheme, userTheme), [
+        userTheme,
+    ]);
+    // --- Attachments (batteries-included) ---
+    // The composer's `+` menu and drag-to-attach are on by default: when the
+    // caller wires none of the attachment props, `<Chat>` manages the pending
+    // files itself so `<Chat />` "just works". Pass any attachment prop to take
+    // control; pass `enableAttachments={false}` to hide the control entirely.
+    const isAttachControlled = onAttach !== undefined ||
+        onDrop !== undefined ||
+        attachments !== undefined ||
+        onRemoveAttachment !== undefined ||
+        onSelectAttachment !== undefined;
+    // When the caller wires no attachment props, `<Chat>` self-manages pending
+    // files through `useUpload` — the SAME hook app-mode uses — so drag/`+`
+    // uploads get an instant thumbnail (`preview`) and a resolved `url` (base64
+    // `data:` by default, or a durable POST when `uploadApi` is set). The old
+    // path only recorded name/size, so pills had no preview and never sent.
+    const upload = useUpload({ api: uploadApi });
+    const manageAttachments = enableAttachments && !isAttachControlled;
+    const effectiveOnAttach = !enableAttachments
+        ? undefined
+        : isAttachControlled
+            ? onAttach
+            : upload.upload;
+    const effectiveOnDrop = !enableAttachments
+        ? undefined
+        : isAttachControlled
+            ? onDrop
+            : upload.upload;
+    const effectiveAttachments = isAttachControlled ? attachments : upload.attachments;
+    const effectiveOnRemove = !enableAttachments
+        ? undefined
+        : isAttachControlled
+            ? onRemoveAttachment
+            : upload.remove;
+    // Self-managed attachments must ride along on submit: the caller's
+    // `onSubmit` only carries the input text, so fold the uploaded files into
+    // `sendMessage({ text, files })` (then clear). Falls back to `onSubmit` for
+    // a text-only turn, when the caller controls attachments, or when no
+    // `sendMessage` is available.
+    const handleSubmit = React.useCallback((e) => {
+        if (manageAttachments && sendMessage) {
+            // Wait for pending uploads: sending now would carry only the resolved
+            // files and silently drop the one still in flight.
+            if (hasPendingAttachments(upload.attachments)) {
+                e?.preventDefault();
+                return;
+            }
+            const files = attachmentsToFileParts(upload.attachments);
+            if (files.length > 0) {
+                e?.preventDefault();
+                void sendMessage({ text: input.trim(), files });
+                setInput?.("");
+                upload.clear();
+                return;
+            }
         }
-    }, [dropHandler]);
+        onSubmit?.(e);
+    }, [manageAttachments, sendMessage, upload, input, setInput, onSubmit]);
     // --- Tab state ---
     const [internalTab, setInternalTab] = React.useState("chat");
     const currentTab = controlledTab ?? internalTab;
@@ -152,37 +196,287 @@ export const Chat = React.forwardRef(function Chat({ messages, input, onChange,
         return undefined;
     }, [onVoice, enableVoice, voice.isSupported, voice.toggle, setInput]);
     const isEmpty = messages.length === 0;
-    const isDocsTab = showTabs && currentTab === "uploads";
-    const dragProps = dropHandler
-        ? {
-            onDragEnter: handleDragEnter,
-            onDragLeave: handleDragLeave,
-            onDragOver: handleDragOver,
-            onDrop: handleFileDrop,
-        }
-        : {};
-    return (React.createElement(ChatRoot, { ref: ref, messages: messages, input: input, isLoading: isLoading, error: error, setInput: setInput, onSubmit: onSubmit, onStop: stop, onReload: reload, model: model, models: models, onModelChange: onModelChange, attachments: attachments, onAttach: onAttach, onRemoveAttachment: onRemoveAttachment, editMessage: editMessage, getBranches: getBranches, switchBranch: switchBranch, onFeedback: onFeedback, showSources: showSources, onSourceClick: onSourceClick, theme: userTheme, maxHeight: maxHeight, className: className, ...dragProps },
-        dropHandler && React.createElement(DropZoneOverlay, { visible: dragOver, accept: attachAccept }),
+    const isDocsTab = showTabs && currentTab === "attachments";
+    return (React.createElement(ChatRoot, { ref: ref, messages: messages, input: input, isLoading: isLoading, error: error, setInput: setInput, onSubmit: handleSubmit, onStop: stop, onReload: reload, model: model, models: models, onModelChange: onModelChange, agent: agent, attachments: effectiveAttachments, onAttach: effectiveOnAttach, onRemoveAttachment: effectiveOnRemove, editMessage: editMessage, getBranches: getBranches, switchBranch: switchBranch, onFeedback: onFeedback, showSources: showSources, onSourceClick: onSourceClick, theme: userTheme, maxHeight: maxHeight, className: className },
         showTabs && !hideTabSwitcher && (React.createElement(TabSwitcher, { activeTab: currentTab, onTabChange: handleTabChange })),
         isDocsTab
-            ? (React.createElement(UploadsPanel, { uploads: uploads, onRemoveUpload: onRemoveUpload, onAttach: onAttach, attachAccept: attachAccept, className: "flex-1 min-h-0" }))
-            : isEmpty
-                ? (React.createElement(ChatEmpty, { icon: emptyState?.icon, title: emptyState?.title, description: emptyState?.description, suggestions: suggestions, onSuggestionClick: onSuggestionClick }))
-                : (React.createElement(ChatMessageList, { messages: messages, isLoading: isLoading, theme: theme, renderMessage: renderMessage, renderTool: renderTool, model: activeModel || model, showMessageActions: showMessageActions, showSources: showSources, showSteps: showSteps, showScrollButton: showScrollButton, onSourceClick: onSourceClick, inferenceMode: inferenceMode, editMessage: editMessage, getBranches: getBranches, switchBranch: switchBranch, onFeedback: onFeedback })),
+            ? (React.createElement(AttachmentsPanel, { uploads: uploads, onRemoveUpload: onRemoveUpload, onAttach: effectiveOnAttach, attachAccept: attachAccept, onClose: () => handleTabChange("chat"), className: "flex-1 min-h-0" }))
+            : isEmpty && (isLoading || initializing)
+                // Thread still loading its history (or agent metadata still
+                // resolving) → skeleton, not an idle placeholder.
+                ? (skeleton ?? React.createElement(ChatMessagesSkeleton, null))
+                : isEmpty && emptyState
+                    // Idle hero is opt-in: only rendered when the consumer supplies an
+                    // `emptyState`. Otherwise an empty thread is just a blank canvas +
+                    // composer — no "What can I help with?" placeholder.
+                    ? (React.createElement(ChatEmpty, { icon: emptyState.icon, title: emptyState.title, description: emptyState.description, suggestions: suggestions, onSuggestionClick: onSuggestionClick }))
+                    : (React.createElement(ChatMessageList, { messages: messages, isLoading: isLoading, theme: theme, renderMessage: renderMessage, renderTool: renderTool, model: activeModel || model, showMessageActions: showMessageActions, showSources: showSources, showSteps: showSteps, showScrollButton: showScrollButton, onSourceClick: onSourceClick, inferenceMode: inferenceMode, editMessage: editMessage, getBranches: getBranches, switchBranch: switchBranch, onFeedback: onFeedback })),
         error && React.createElement(ErrorBanner, { error: error, onRetry: reload }),
-        !isDocsTab && (React.createElement(ChatComposer, { input: voice.isListening ? voice.transcript || input : input, onChange: onChange, onSubmit: onSubmit, isLoading: isLoading, placeholder: voice.isListening ? "Listening..." : placeholder, theme: theme, stop: voice.isListening ? undefined : stop, onVoice: voiceHandler, isListening: voice.isListening, transcript: voice.transcript, models: models, model: model, onModelChange: onModelChange, onAttach: onAttach, onSelectAttachment: onSelectAttachment, attachAccept: attachAccept, attachments: attachments, onRemoveAttachment: onRemoveAttachment, showExport: showExport, messages: messages },
+        !isDocsTab && (React.createElement(ChatInput, { input: voice.isListening ? voice.transcript || input : input, onChange: onChange, onSubmit: handleSubmit, isLoading: isLoading, placeholder: voice.isListening ? "Listening..." : placeholder, theme: theme, stop: voice.isListening ? undefined : stop, onVoice: voiceHandler, isListening: voice.isListening, transcript: voice.transcript, models: models, model: model, onModelChange: onModelChange, onAttach: effectiveOnAttach, onSelectAttachment: onSelectAttachment, onDrop: effectiveOnDrop, attachAccept: attachAccept, attachments: effectiveAttachments, onRemoveAttachment: effectiveOnRemove, showExport: showExport, messages: messages, toolbarStart: toolbarStart },
             inferenceMode && inferenceMode !== "cloud" && (React.createElement(InferenceBadge, { inferenceMode: inferenceMode })),
             isEmpty && quickActions && quickActions.length > 0 && (React.createElement(QuickActionsComponent, { actions: quickActions, onActionClick: onQuickAction })))),
         children));
 });
-Chat.displayName = "Chat";
+ControlledChat.displayName = "ControlledChat";
+/**
+ * Map agent-metadata suggestions to `{ label, prompt }`. The chip shows the
+ * short `title` ("Triage login issue") while the click sends the full `prompt`
+ * ("Triage a customer who cannot sign in after a release.") — so the empty
+ * state stays scannable without truncating what the agent actually receives.
+ */
+function agentSuggestionItems(suggestions) {
+    const list = suggestions?.suggestions;
+    if (!Array.isArray(list))
+        return [];
+    return list.flatMap((s) => {
+        if (s.type !== "prompt" || !("prompt" in s) || !s.prompt)
+            return [];
+        const title = s.title;
+        const label = typeof title === "string" && title.length > 0 ? title : s.prompt;
+        return [{ label, prompt: s.prompt }];
+    });
+}
+/**
+ * Map uploaded attachments to `file` message parts. Only attachments that
+ * finished uploading (have a resolved `url`) are sent — pending/errored ones
+ * are skipped so a half-uploaded file never reaches the agent.
+ */
+function attachmentsToFileParts(items) {
+    return items
+        .filter((a) => Boolean(a.url))
+        .map((a) => ({
+        type: "file",
+        mediaType: a.type ?? "application/octet-stream",
+        url: a.url,
+        filename: a.name,
+        ...(a.size != null ? { size: a.size } : {}),
+    }));
+}
+/** True while any attachment is still resolving its `url`; submits must wait
+ * or the fold above would silently drop the pending file. */
+function hasPendingAttachments(items) {
+    return items.some((a) => a.state === "uploading" || a.state === "processing");
+}
+const UncontrolledChat = React.forwardRef(function UncontrolledChat({ agentId, api = "/api/ag-ui", initialMessages, onError, onUpdate, models, suggestions: suggestionsProp, onSuggestionClick, emptyState, 
+// App mode defaults the scroll-to-bottom button on (batteries-included).
+showScrollButton = true, 
+// Attachments: default-wired through `useUpload` unless the caller
+// controls them. With no `uploadApi`, files inline as base64 `data:` URLs
+// (guest mode — zero backend). Set `uploadApi` to POST to a durable
+// upload endpoint (multipart `file` → `{ url }`) for real users + a project.
+uploadApi, enableAttachments = true, onAttach: userOnAttach, onDrop: userOnDrop, attachments: userAttachments, onRemoveAttachment: userOnRemoveAttachment, onSubmit: userOnSubmit, ...rest }, ref) {
+    // Inside a `ConversationsProvider`, bind to the active conversation — seed
+    // from its messages/agent and persist changes back. No props: the context
+    // carries it, so standalone `<Chat>` (no provider) is unchanged. `active`
+    // must match `activeId` so we never seed from a still-loading thread.
+    const conversations = useConversationsContextOptional();
+    const bound = conversations?.active && conversations.active.id === conversations.activeId
+        ? conversations.active
+        : null;
+    const resolvedAgentId = bound?.agentId ?? agentId;
+    const chat = useChat({
+        api,
+        initialMessages: bound ? bound.messages : initialMessages,
+        onError,
+        body: resolvedAgentId ? { agentId: resolvedAgentId } : undefined,
+    });
+    const { agent, error: agentError } = useAgentMetadata(resolvedAgentId);
+    // --- Persistence sink (explicit prop → provider default → ephemeral) ------
+    // Resolve WHERE the live thread persists: an explicit `onUpdate` wins, else
+    // a surrounding `ConversationsProvider`'s `save`, else nothing. The sink
+    // takes the whole updated conversation; `<Chat>` owns building it (title
+    // included) so `useConversations` stays dumb about titling and `useChat`
+    // never touches the store.
+    const persist = onUpdate ?? conversations?.save;
+    // Identity for the emitted conversation: in a provider we ride the bound
+    // conversation (id/agentId/createdAt); standalone (explicit `onUpdate`, no
+    // provider) we mint one stable id so updates target a single record.
+    const syntheticRef = React.useRef(null);
+    const persistRef = React.useRef(persist);
+    persistRef.current = persist;
+    const boundRef = React.useRef(bound);
+    boundRef.current = bound;
+    const agentIdRef = React.useRef(resolvedAgentId);
+    agentIdRef.current = resolvedAgentId;
+    // Emit the whole conversation when the live messages change. Keyed on
+    // `chat.messages` + `boundId` only (sink/identity read via refs) so the
+    // save→setActive round-trip inside a provider can't feed a render loop.
+    // Seeded with the mount-time messages so merely *opening* a thread never
+    // re-saves it (a fresh `updatedAt` would jump it to the top of the sidebar).
+    const boundId = bound?.id;
+    const lastEmittedRef = React.useRef(null);
+    if (lastEmittedRef.current === null)
+        lastEmittedRef.current = chat.messages;
+    React.useEffect(() => {
+        const sink = persistRef.current;
+        if (!sink)
+            return;
+        if (chat.messages === lastEmittedRef.current)
+            return;
+        lastEmittedRef.current = chat.messages;
+        let base = boundRef.current;
+        if (!base) {
+            syntheticRef.current ??= createEmptyConversation({ agentId: agentIdRef.current });
+            base = syntheticRef.current;
+        }
+        const keepTitle = base.title !== "" && base.title !== DEFAULT_CONVERSATION_TITLE;
+        const title = keepTitle ? base.title : (deriveTitle(chat.messages) || base.title);
+        const conversation = {
+            ...base,
+            messages: chat.messages,
+            title,
+            updatedAt: Date.now(),
+        };
+        // Fold the derived title back onto the synthetic identity so later emits
+        // don't re-derive it every keystroke of a streamed reply.
+        if (base === syntheticRef.current)
+            syntheticRef.current = conversation;
+        sink(conversation);
+    }, [chat.messages, boundId]);
+    // App mode owns the loading signal: from the very first paint until the
+    // agent resolves (or errors) we render the skeleton — never flash an idle
+    // placeholder first. Keyed off "agent not yet here" rather than the hook's
+    // `isLoading` flag so there's no one-frame gap on mount. Works out of the
+    // box — no `isLoading` wiring from the consumer.
+    const agentInitializing = Boolean(resolvedAgentId) && !agent && !agentError;
+    // Agent-driven empty state: avatar + name + description, shown once the
+    // agent resolves (the skeleton covers the load, so the generic
+    // "What can I help with?" placeholder never flashes). A consumer-supplied
+    // `emptyState` still wins.
+    const derivedEmptyState = React.useMemo(() => {
+        if (emptyState)
+            return emptyState;
+        if (!agent)
+            return undefined;
+        return {
+            icon: (React.createElement(AgentAvatar, { name: agent.name, avatarUrl: agent.avatarUrl ?? undefined, className: "size-12" })),
+            title: agent.name,
+            description: agent.description ?? undefined,
+        };
+    }, [emptyState, agent]);
+    // Chips show the short `title`; the click sends the full `prompt`.
+    const suggestionItems = React.useMemo(() => agentSuggestionItems(agent?.suggestions), [agent]);
+    const derivedSuggestions = suggestionsProp ??
+        (suggestionItems.length > 0 ? suggestionItems.map((s) => s.label) : undefined);
+    const handleSuggestion = onSuggestionClick ??
+        ((label) => {
+            const item = suggestionItems.find((s) => s.label === label);
+            void chat.sendMessage({ text: item?.prompt ?? label });
+        });
+    // Batteries-included attachments: unless the caller controls them, files
+    // uploaded via the `+` menu / drag land here, ride along on submit as
+    // `file` parts, and clear once sent.
+    const upload = useUpload({ api: uploadApi });
+    const attachControlled = userOnAttach !== undefined ||
+        userOnDrop !== undefined ||
+        userAttachments !== undefined ||
+        userOnRemoveAttachment !== undefined;
+    const manageAttachments = enableAttachments && !attachControlled;
+    const submitWithAttachments = React.useCallback((e) => {
+        e?.preventDefault();
+        if (chat.isLoading)
+            return;
+        // Never send while a file is still uploading: the fold below only
+        // carries resolved urls, so submitting now would silently drop the
+        // pending attachment (and `clear()` would abort its upload).
+        if (hasPendingAttachments(upload.attachments))
+            return;
+        const text = chat.input.trim();
+        const files = attachmentsToFileParts(upload.attachments);
+        if (!text && files.length === 0)
+            return;
+        chat.setInput("");
+        upload.clear();
+        void chat.sendMessage({ text, files });
+    }, [chat, upload]);
+    return (React.createElement(ControlledChat, { ref: ref, messages: chat.messages, input: chat.input, onChange: chat.onChange, onSubmit: manageAttachments ? submitWithAttachments : (userOnSubmit ?? chat.onSubmit), stop: chat.stop, reload: () => void chat.reload(), setInput: chat.setInput, isLoading: chat.isLoading, error: chat.error, model: chat.model, activeModel: chat.activeModel, onModelChange: chat.onModelChange, inferenceMode: chat.inferenceMode, models: models, editMessage: chat.editMessage, getBranches: chat.getBranches, switchBranch: chat.switchBranch, emptyState: derivedEmptyState, agent: agent ? { name: agent.name, avatarUrl: agent.avatarUrl ?? undefined } : undefined, initializing: agentInitializing, suggestions: derivedSuggestions, onSuggestionClick: handleSuggestion, showScrollButton: showScrollButton, enableAttachments: enableAttachments, onAttach: manageAttachments ? upload.upload : userOnAttach, onDrop: manageAttachments ? upload.upload : userOnDrop, attachments: manageAttachments ? upload.attachments : userAttachments, onRemoveAttachment: manageAttachments ? upload.remove : userOnRemoveAttachment, ...rest }));
+});
+UncontrolledChat.displayName = "UncontrolledChat";
+/**
+ * App-mode `<Chat>` with conversation-thread lifecycle when a
+ * `ConversationsProvider` is present: keys by the active id so switching threads
+ * remounts `UncontrolledChat` (fresh `useChat` seed), and holds the skeleton
+ * while the active thread's messages load from the store. No provider → renders
+ * `UncontrolledChat` unchanged.
+ */
+const ConversationBoundChat = React.forwardRef(function ConversationBoundChat(props, ref) {
+    const conversations = useConversationsContextOptional();
+    if (!conversations || conversations.activeId == null) {
+        return React.createElement(UncontrolledChat, { ref: ref, ...props });
+    }
+    const { active, activeId } = conversations;
+    // Wait for the active thread's messages before mounting, so `useChat` seeds
+    // from the right thread rather than a still-loading one.
+    if (active?.id !== activeId) {
+        return React.createElement(React.Fragment, null, props.skeleton ?? React.createElement(ChatMessagesSkeleton, null));
+    }
+    return React.createElement(UncontrolledChat, { key: activeId, ref: ref, ...props });
+});
+ConversationBoundChat.displayName = "ConversationBoundChat";
+/**
+ * Normalize the consolidated `chat={useChat()}` / `agent={…}` objects onto the
+ * flat props `ControlledChat` consumes. The object API wins; the legacy flat
+ * props remain as a one-release fallback. Agent-driven content (`models`,
+ * `suggestions`) folds in too.
+ */
+function resolveControlledProps(props) {
+    const { chat, agent } = props;
+    const merged = {
+        ...props,
+        models: agent?.models ?? props.models,
+        suggestions: props.suggestions ?? agent?.suggestions,
+    };
+    if (chat) {
+        merged.messages = chat.messages;
+        merged.input = chat.input;
+        merged.onChange = chat.onChange;
+        merged.onSubmit = props.onSubmit ?? chat.onSubmit;
+        merged.sendMessage = chat.sendMessage;
+        merged.stop = chat.stop;
+        merged.reload = () => void chat.reload();
+        merged.setInput = chat.setInput;
+        merged.isLoading = chat.isLoading;
+        merged.error = chat.error;
+        merged.model = chat.model;
+        merged.activeModel = chat.activeModel;
+        merged.onModelChange = chat.onModelChange;
+        merged.inferenceMode = chat.inferenceMode;
+        merged.editMessage = chat.editMessage;
+        merged.getBranches = chat.getBranches;
+        merged.switchBranch = chat.switchBranch;
+    }
+    return merged;
+}
+/**
+ * Chat — batteries-included chat surface.
+ *
+ * - **App mode (uncontrolled):** omit `chat`/`messages` and pass `agentId` +
+ *   `api`; `<Chat>` wires `useChat` + `useAgentMetadata` internally. Inside a
+ *   `ConversationsProvider` it also binds to the active conversation.
+ * - **Controlled mode:** pass `chat={useChat()}` (preferred) or the legacy
+ *   flat `messages` + `input` props to drive it yourself.
+ */
+const ChatBase = React.forwardRef(function Chat(props, ref) {
+    // Controlled when the caller supplies a `chat` session (or the legacy flat
+    // message/input state); otherwise the component self-drives (app mode).
+    const isControlled = props.chat !== undefined ||
+        (props.messages !== undefined && props.input !== undefined);
+    return isControlled
+        ? React.createElement(ControlledChat, { ref: ref, ...resolveControlledProps(props) })
+        : React.createElement(ConversationBoundChat, { ref: ref, ...props });
+});
+ChatBase.displayName = "Chat";
 /** Render chat components. */
-export const ChatComponents = Object.assign(Chat, {
+export const Chat = Object.assign(ChatBase, {
     Root: ChatRoot,
     MessageList: ChatMessageList,
-    Composer: ChatComposer,
+    Input: ChatInput,
+    Composer: ChatInput,
     Empty: ChatEmpty,
+    Skeleton: ChatMessagesSkeleton,
     If: ChatIf,
     Message: Message,
     ErrorBanner: ErrorBanner,
 });
+/** @deprecated Back-compat alias — `Chat` is now the compound itself. */
+export const ChatComponents = Chat;

package/esm/src/react/components/chat/chat/persistence/conversation-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ConversationStore — the async, swappable persistence adapter behind
+ * {@link useConversations}. Mirrors the `BlobStorage` / `CacheStore` house
+ * style: async methods, one action per method, optional capability methods.
+ *
+ * Swap the whole store (localStorage / IndexedDB / your API) or override a
+ * single action by wrapping another store. The React hook drives the calls —
+ * `list()` on mount, `load(id)` when active changes, `save()` (debounced) on
+ * message/title change, `delete()` on remove — so adapters stay dumb and
+ * batching lives in the hook.
+ *
+ * Two decisions that matter the moment you leave localStorage:
+ * - `list()` returns **summaries** (no messages) so a sidebar never hauls every
+ *   message of every conversation; `load(id)` fetches the full thread on open.
+ * - ids are minted client-side, so `save()` is a create-or-update **upsert**
+ *   (REST: idempotent `PUT {base}/{id}`) — no async "create returns id" dance.
+ *
+ * @module react/components/chat/persistence/conversation-store
+ */
+import type { ChatMessage } from "../../../../../agent/react/index.js";
+/** Fields shared by a conversation and its list summary. */
+interface ConversationMeta {
+    id: string;
+    title: string;
+    /** Last agent this conversation talked to — lets a switcher restore per-thread. */
+    agentId?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Lightweight conversation metadata — what a list / sidebar needs (no messages). */
+export interface ConversationSummary extends ConversationMeta {
+    /** Number of messages, so a list can show "empty" / reuse an empty draft
+     *  without loading the message blob. Derived from the conversation on save. */
+    messageCount: number;
+}
+/** A full conversation — metadata + its messages. Fetched via {@link ConversationStore.load}. */
+export interface Conversation extends ConversationMeta {
+    messages: ChatMessage[];
+}
+/**
+ * Async persistence contract for conversations. Implement all four methods;
+ * `subscribe`/`dispose` are optional capabilities (feature-detect them).
+ */
+export interface ConversationStore {
+    /** All conversations as summaries (no messages), newest first. */
+    list(): Promise<ConversationSummary[]>;
+    /** Load one full conversation (with messages). `null` if it does not exist. */
+    load(id: string): Promise<Conversation | null>;
+    /** Create-or-update by id (upsert). */
+    save(conversation: Conversation): Promise<void>;
+    /** Delete a conversation. Idempotent — deleting a missing id is not an error. */
+    delete(id: string): Promise<void>;
+    /**
+     * Optional: notify when conversations change out-of-band (another tab or
+     * device). Returns an unsubscribe fn. Backends that can push (IndexedDB via
+     * BroadcastChannel, an API via SSE) implement it; localStorage omits it.
+     */
+    subscribe?(onChange: (ids: string[]) => void): () => void;
+    /** Optional: release resources (sockets, db handles). */
+    dispose?(): void;
+}
+export {};
+//# sourceMappingURL=conversation-store.d.ts.map

package/esm/src/react/components/chat/chat/persistence/conversation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-store.d.ts","sourceRoot":"","sources":["../../../../../../../src/src/react/components/chat/chat/persistence/conversation-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAEvE,4DAA4D;AAC5D,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D;mFAC+E;IAC/E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,iGAAiG;AACjG,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IACvC,+EAA+E;IAC/E,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC/C,uCAAuC;IACvC,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,iFAAiF;IACjF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC;;;;OAIG;IACH,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC1D,yDAAyD;IACzD,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB"}

package/esm/src/react/components/chat/chat/persistence/conversation-store.js

@@ -0,0 +1 @@
+export {};

package/esm/src/react/components/chat/chat/persistence/local-conversation-store.d.ts

@@ -0,0 +1,13 @@
+import type { ConversationStore } from "./conversation-store.js";
+/** The slice of the Web Storage API this adapter needs. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * localStorage-backed conversation persistence. Pass a `storage` to back it with
+ * something else (tests inject an in-memory store); defaults to `localStorage`.
+ */
+export declare function localConversationStore(storageKey?: string, storage?: StorageLike): ConversationStore;
+//# sourceMappingURL=local-conversation-store.d.ts.map

package/esm/src/react/components/chat/chat/persistence/local-conversation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-conversation-store.d.ts","sourceRoot":"","sources":["../../../../../../../src/src/react/components/chat/chat/persistence/local-conversation-store.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAgB,iBAAiB,EAAuB,MAAM,yBAAyB,CAAC;AAEpG,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAmCD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,GAAE,MAAoB,EAChC,OAAO,GAAE,WAA8B,GACtC,iBAAiB,CAiDnB"}