@miiflow/assistant-ui 0.10.0 → 0.15.0

package/README.md

@@ -8,7 +8,7 @@ React components and hooks for building custom Miiflow chat interfaces. Install
 npm install @miiflow/assistant-ui
 ```
 
-**Peer dependencies:** `react >= 18`, `react-dom >= 18`
+**Peer dependencies:** `react >= 19`, `react-dom >= 19`, `zod >= 3`. Optionally `lexical >= 0.20` and `@lexical/react >= 0.20` — required only if you use the Lexical-based `MessageComposer` / `WelcomeScreen` input or the `/composer` entry. React 18 projects must stay on `0.10.x`.
 
 The styled components use [TailwindCSS](https://tailwindcss.com/). If your project doesn't use Tailwind, import the pre-built CSS instead:
 
@@ -44,6 +44,7 @@ function Chat() {
     streamingMessageId,
     sendMessage,
     uploadFile,
+    stopStreaming,
     startNewThread,
     branding,
     brandingCSSVars,
@@ -63,7 +64,8 @@ function Chat() {
       messages={messages}
       isStreaming={isStreaming}
       streamingMessageId={streamingMessageId}
-      onSendMessage={sendMessage}
+      onSendMessage={(content) => sendMessage(content)}
+      onStopStreaming={stopStreaming}
     >
       <div style={{ height: "100vh", ...brandingCSSVars }}>
         <ChatLayout
@@ -82,8 +84,9 @@ function Chat() {
               welcomeText={branding?.welcomeMessage}
               placeholders={branding?.rotatingPlaceholders}
               suggestions={branding?.presetQuestions}
-              onSubmit={sendMessage}
-              onSuggestionClick={sendMessage}
+              onSubmit={(message) => sendMessage(message)}
+              onSuggestionClick={(s) => sendMessage(s)}
+              disabled={isStreaming}
             />
           }
           messageList={
@@ -101,9 +104,12 @@ function Chat() {
           }
           composer={
             <MessageComposer
-              onSubmit={sendMessage}
+              onSubmit={(content, _files, attachmentIds) =>
+                sendMessage(content, attachmentIds)
+              }
               onUploadFile={uploadFile}
-              disabled={isStreaming}
+              isStreaming={isStreaming}
+              onStopStreaming={stopStreaming}
               placeholder={branding?.chatboxPlaceholder}
             />
           }
@@ -114,6 +120,8 @@ function Chat() {
 }
 ```
 
+Note the small signature adapters: the hook's `sendMessage` takes `(content, attachmentIds?)`, while `ChatProvider.onSendMessage` passes `(content, attachments?: File[])` and `MessageComposer.onSubmit` passes `(content, attachments?, attachmentIds?)` — wrap them as shown rather than passing `sendMessage` directly.
+
 ## Configuration Reference
 
 Pass a `MiiflowChatConfig` object to `useMiiflowChat`:
@@ -126,11 +134,70 @@ Pass a `MiiflowChatConfig` object to `useMiiflowChat`:
 | `userName` | `string` | No | User display name |
 | `userEmail` | `string` | No | User email |
 | `userMetadata` | `string` | No | JSON string of custom user metadata |
-| `hmac` | `string` | No | HMAC for identity verification |
-| `timestamp` | `string` | No | Timestamp for HMAC verification |
-| `baseUrl` | `string` | No | Override API endpoint (default: `https://api.miiflow.ai/api`) |
+| `userData` | `string` | No | The exact JSON string your server signed, sent verbatim. See [Verified identity](#verified-identity-hmac) |
+| `hmac` | `string` | No | Signature over `userData` + `timestamp`. See [Verified identity](#verified-identity-hmac) |
+| `timestamp` | `string` | No | Unix seconds (string) used in the signature |
+| `baseUrl` | `string` | No | API origin override (default: `https://api.miiflow.ai`). A trailing `/api` is stripped; the client appends `/api/...` per request |
 | `webSocketUrl` | `string` | No | WebSocket URL for tool invocations (auto-derived from `baseUrl` if not set) |
-| `responseTimeout` | `number` | No | SSE stream timeout in ms (default: `60000`) |
+| `initialBranding` | `BrandingData` | No | Branding rendered before session init so the shell paints instantly (SSR-safe). Server branding overrides it once init resolves |
+| `tools` | `ClientToolDefinition[]` | No | Client tools folded into the init round-trip instead of a separate `registerTools()` call |
+| `onToolInvocationFallback` | `(invocation: ToolInvocationRequest) => Promise<boolean>` | No | Handles tool invocations with no local handler (multi-widget routing); return `true` if handled |
+| `onUserMessageCreated` | `(message: { id: string; content: string }) => void` | No | Fired when a user message is created |
+| `onAssistantMessageComplete` | `(message: { id: string; content: string }) => void` | No | Fired when an assistant stream completes |
+
+## Verified identity (HMAC)
+
+By default a session is anonymous: the widget keys it on a random id in
+`localStorage`, and `userId`/`userName`/`userEmail` are untrusted hints the
+browser could set to anything. That is fine for a public help widget.
+
+If the assistant should act **as a signed-in person** — see their data, or use
+a connected integration on their behalf — the browser cannot be the one making
+that claim. Sign the identity on your server instead:
+
+```js
+// SERVER-SIDE ONLY. The private key must never reach the browser: anyone
+// holding it can impersonate any of your users to the assistant.
+import crypto from "node:crypto";
+
+const userData = JSON.stringify({
+  user_id: "your-internal-user-id",   // required — the session is keyed on this
+  name: "Ada Lovelace",               // optional
+  email: "ada@example.com",           // optional
+  tenant_scope: "acme-hvac",          // optional — see below
+});
+const timestamp = String(Math.floor(Date.now() / 1000));
+const hmac = crypto
+  .createHmac("sha256", process.env.MIIFLOW_EMBED_PRIVATE_KEY)
+  .update(`${userData}|${timestamp}`)
+  .digest("hex");
+```
+
+Pass all three to the hook and send nothing else:
+
+```tsx
+useMiiflowChat({ publicKey, assistantId, userData, hmac, timestamp });
+```
+
+Details that matter:
+
+- **The signature covers the exact bytes of `userData`.** Pass the same string
+  you signed — re-serializing it, even to equivalent JSON, invalidates the
+  signature. This is why `userData` is a string you supply rather than
+  something the SDK assembles for you.
+- **All three fields travel together.** Send a partial set and the session
+  falls back to anonymous rather than failing loudly.
+- **`timestamp` must be within 5 minutes** of server time. Sign per page load,
+  not once at build time.
+- **`user_id` is the session identity.** Two different signed-in users on the
+  same browser get separate sessions and separate chat histories, and neither
+  can reach the other's — an unsigned request cannot claim a signed identity.
+- **`tenant_scope`** names which of *your* tenants (workspace, shop, account)
+  the session is acting for, when one deployment serves many. It scopes the
+  credentials the assistant uses, so a session can only reach the tenant it was
+  signed for. Omit it if your users belong to exactly one.
+
+Rotate the private key from the Miiflow dashboard if it is ever exposed.
 
 ## Connecting to a Custom Backend
 
@@ -140,13 +207,13 @@ By default, the hook connects to `https://api.miiflow.ai`. To point to your own
 useMiiflowChat({
   publicKey: "pk_live_...",
   assistantId: "ast_...",
-  baseUrl: "https://your-server.example.com/api",
+  baseUrl: "https://your-server.example.com",
   // webSocketUrl is auto-derived from baseUrl; override if needed:
   // webSocketUrl: "wss://your-server.example.com/ws",
 });
 ```
 
-Your backend must implement the same API contract as the Miiflow platform (session init, SSE streaming, file upload, and tool-result endpoints).
+Pass the bare origin — the client appends `/api/...` to each request itself (a trailing `/api` on `baseUrl` is stripped). Your backend must implement the same API contract as the Miiflow platform (session init, SSE streaming, file upload, and tool-result endpoints).
 
 ## Hook API — `useMiiflowChat`
 
@@ -173,12 +240,17 @@ const result = useMiiflowChat(config);
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `sendMessage` | `(content: string, attachmentIds?: string[]) => Promise<void>` | Send a message to the assistant |
+| `sendMessage` | `(content: string, attachmentIds?: string[]) => Promise<void>` | Send a message; queued if init hasn't resolved yet |
 | `uploadFile` | `(file: File) => Promise<string>` | Upload a file and get an attachment ID |
-| `startNewThread` | `() => Promise<string>` | Start a new conversation thread |
+| `removeUploadedAttachment` | `(attachmentId: string) => void` | Drop uploaded-attachment metadata when the user removes it pre-send |
+| `stopStreaming` | `() => void` | Abort the in-flight stream, preserving partial content |
+| `startNewThread` | `() => Promise<string>` | Start a new conversation thread; re-registers client tools |
 | `registerTool` | `(tool: ClientToolDefinition) => Promise<void>` | Register a client-side tool |
 | `registerTools` | `(tools: ClientToolDefinition[]) => Promise<void>` | Register multiple tools |
-| `sendSystemEvent` | `(event: SystemEvent) => Promise<void>` | Send an invisible system event |
+| `sendSystemEvent` | `(event: SystemEvent) => Promise<void>` | Send an invisible system event (triggers a reply) |
+| `sendPageContext` | `(context: PageContext) => Promise<void>` | Append hidden page context to the thread (no reply) |
+| `handleToolInvocation` | `(invocation: ToolInvocationRequest) => Promise<boolean>` | Execute a tool invocation; `true` if handled locally |
+| `updateSession` | `(session: EmbedSession) => void` | Replace the session externally (e.g. after token refresh) |
 
 ## Components Reference
 
@@ -188,14 +260,18 @@ Wraps children and provides chat context via React context.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `messages` | `ChatMessage[]` | — | Messages to display |
+| `children` | `ReactNode` | — | **Required.** Subtree |
+| `messages` | `ChatMessage[]` | — | **Required.** Messages to display |
+| `onSendMessage` | `(content: string, attachments?: File[]) => Promise<void>` | — | **Required.** Message send handler |
 | `isStreaming` | `boolean` | `false` | Whether a response is streaming |
 | `streamingMessageId` | `string \| null` | `null` | ID of the streaming message |
 | `viewerRole` | `ParticipantRole` | `"user"` | Viewer's role (determines message alignment) |
-| `onSendMessage` | `(content: string, attachments?: File[]) => Promise<void>` | — | Message send handler |
-| `onStopStreaming` | `() => void` | — | Stop streaming handler |
-| `onRetryLastMessage` | `() => Promise<void>` | — | Retry last message handler |
-| `onVisualizationAction` | `(event: VisualizationActionEvent) => void` | — | Callback for form/card interactions |
+| `onStopStreaming` | `() => void` | — | Stop streaming handler (wire to the hook's `stopStreaming`) |
+| `onRetryLastMessage` | `() => Promise<void>` | — | Retry last message handler (host-implemented) |
+| `customData` | `Record<string, unknown>` | — | Arbitrary data passed through context |
+| `onVisualizationAction` | `(event: VisualizationActionEvent) => void` | — | Callback for form/card/auth interactions |
+| `resolveCommandToken` | `(id: string, kind: string) => { label?: string; tag?: ReactNode } \| undefined` | — | Customize inline command-token chip rendering |
+| `isDarkSurface` | `boolean` | `false` | Tells the package the host surface is dark — drives choices CSS variables can't express, currently the code-block syntax theme |
 
 ### `ChatLayout`
 
@@ -203,13 +279,12 @@ Handles the empty-to-active state transition with crossfade animation. Accepts r
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `isEmpty` | `boolean` | — | Whether the chat has no messages |
+| `isEmpty` | `boolean` | — | **Required.** Whether the chat has no messages |
 | `header` | `ReactNode` | — | Header slot (rendered in both states) |
 | `welcomeScreen` | `ReactNode` | — | Content for empty state |
 | `messageList` | `ReactNode` | — | Message list for active state |
 | `composer` | `ReactNode` | — | Composer for active state |
 | `footer` | `ReactNode` | — | Extra content between list and composer |
-| `variant` | `"standalone" \| "embedded" \| "widget"` | `"standalone"` | Layout variant |
 | `className` | `string` | — | Additional CSS classes |
 
 ### `WelcomeScreen`
@@ -220,38 +295,64 @@ Empty state with rotating placeholder text and suggestion cards.
 |------|------|---------|-------------|
 | `placeholders` | `string[]` | `[]` | Rotating placeholder strings |
 | `suggestions` | `string[]` | `[]` | Preset suggestion cards |
-| `onSubmit` | `(message: string) => void` | — | Submit handler for built-in input |
+| `onSubmit` | `(message: string, files?: File[]) => void` | — | Submit handler for built-in input |
 | `onSuggestionClick` | `(suggestion: string) => void` | — | Suggestion card click handler |
 | `welcomeText` | `string` | `"How can I help you today?"` | Heading text |
+| `supportsAttachments` | `boolean` | — | Show the attach button on the built-in input |
+| `disabled` | `boolean` | — | Block the built-in input (e.g. while streaming). Ignored when `composerSlot` is set |
 | `composerSlot` | `ReactNode` | — | Override default input with custom composer |
+| `commandProvider` | `CommandProvider \| null` | — | Slash-command typeahead provider |
+| `commandProviders` | `CommandProvider[]` | — | Multiple trigger providers; takes precedence over `commandProvider` |
+| `assistantAvatar` | `string` | — | Avatar URL; when set, welcome text renders in message format |
+| `assistantName` | `string` | — | Name shown alongside the avatar |
 | `className` | `string` | — | Additional CSS classes |
 
 ### `MessageList`
 
-Scrollable message container with auto-scroll.
+Scrollable message transcript built on a scroll engine that follows streamed output only while the reader is pinned to the live edge, and preserves the reader's position when earlier content changes height. Each direct child is wrapped in a scroll-anchored item.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children` | `ReactNode` | — | Message elements |
-| `autoScroll` | `boolean` | `true` | Auto-scroll to bottom on new messages |
-| `className` | `string` | — | Additional CSS classes |
+| `children` | `ReactNode` | — | **Required.** Message elements |
+| `autoScroll` | `boolean` | `true` | Follow streamed output while at the live edge (not "always jump to bottom") |
+| `showScrollToBottom` | `boolean` | `true` | Render the floating scroll-to-bottom button |
+| `className` | `string` | — | Classes applied to the inner transcript content container |
 
 ### `Message`
 
-Individual message with markdown rendering, reasoning panel, citations, and visualizations.
+Individual message with markdown rendering, reasoning panel, citations, visualizations, media, artifacts, and interactive panels (clarification, tool approval).
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `message` | `MessageData` | — | Message data object |
+| `message` | `MessageData` | — | **Required.** Message data object |
 | `viewerRole` | `ParticipantRole` | `"user"` | Viewer's role (determines alignment) |
 | `showAvatar` | `boolean` | `true` | Show participant avatar |
 | `showTimestamp` | `boolean` | `true` | Show message timestamp |
 | `renderMarkdown` | `boolean` | `true` | Render content as markdown |
 | `reasoning` | `StreamingChunk[]` | — | Reasoning/thinking chunks for collapsible panel |
+| `reasoningExpanded` | `boolean` | — | Controlled expansion of the reasoning panel |
+| `onReasoningExpandedChange` | `(expanded: boolean) => void` | — | Reasoning panel expansion callback |
+| `executionPlan` | `unknown` | — | Execution plan for completed agent messages |
+| `executionTimeline` | `unknown[]` | — | Execution timeline for completed messages |
+| `executionTime` | `number` | — | Total execution time in seconds (persisted) |
+| `streamStartedAt` | `number` | — | Epoch ms the in-progress run started, so the live elapsed counter survives remounts |
 | `suggestedActions` | `SuggestedAction[]` | — | Suggested follow-up actions |
 | `onSuggestedAction` | `(action: SuggestedAction) => void` | — | Suggested action click handler |
+| `renderInlineSuggestedAction` | `(id: string) => ReactNode` | — | Renderer for inline `[SA:id]` markers |
 | `citations` | `SourceReference[]` | — | Citation sources to display |
-| `visualizations` | `VisualizationChunkData[]` | — | Inline visualizations |
+| `visualizations` | `VisualizationChunkData[]` | — | Inline visualizations (`[VIZ:id]` markers) |
+| `medias` | `MediaChunkData[]` | — | Inline images/videos |
+| `artifacts` | `ArtifactChunkData[]` | — | Inline downloadable artifacts (PDF, HTML, …) |
+| `onArtifactOpen` | `(artifact: ArtifactChunkData) => void` | — | Artifact inline-card click handler |
+| `baselineFontSize` | `number` | — | Base font size multiplier for markdown |
+| `pendingClarification` | `ClarificationData` | — | Agent needs user input |
+| `onClarificationSubmit` | `(response: string) => void` | — | Clarification response handler |
+| `pendingToolApproval` | `ToolApprovalData` | — | Tool awaiting approval |
+| `onToolApprove` | `(modifiedInputs: Record<string, unknown>) => void` | — | Tool approval handler |
+| `onToolReject` | `(reason?: string) => void` | — | Tool rejection handler |
+| `onReportIncorrect` | `(reason?: string) => void` | — | Report the response as incorrect |
+| `onConfirmCorrect` | `() => void` | — | Confirm the response was helpful |
+| `onEditSubmit` | `(newText: string) => void` | — | Edit-and-resubmit for the viewer's own messages; enables the edit action in the hover bar |
 | `className` | `string` | — | Additional CSS classes |
 
 ### `MessageComposer`
@@ -260,15 +361,35 @@ Rich text editor (Lexical) with file upload, drag-and-drop, and Enter-to-send.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `onSubmit` | `(content: string, attachments?: File[]) => Promise<void>` | — | Submit handler |
+| `onSubmit` | `(content: string, attachments?: File[], attachmentIds?: string[]) => Promise<void>` | — | **Required.** Submit handler; `attachmentIds` carries server-uploaded IDs |
 | `onUploadFile` | `(file: File) => Promise<string>` | — | File upload handler (returns attachment ID) |
 | `onAttach` | `(files: File[]) => void` | — | Called when files are attached |
-| `disabled` | `boolean` | `false` | Disable the composer |
+| `onRemoveUploadedAttachment` | `(attachmentId: string) => void` | — | Called when an uploaded attachment is removed pre-send |
+| `disabled` | `boolean` | `false` | Disable the composer entirely |
 | `supportsAttachments` | `boolean` | `true` | Enable file attachments |
 | `allowedFileTypes` | `string[]` | images, docs, videos | Allowed MIME types |
 | `maxFileSize` | `number` | `104857600` (100MB) | Max file size in bytes |
 | `placeholder` | `string` | `"Type a message..."` | Placeholder text |
-| `isSubmitting` | `boolean` | `false` | Show loading state on send button |
+| `isSubmitting` | `boolean` | `false` | Guards the submit handshake only (loading state on send) |
+| `isStreaming` | `boolean` | `false` | Per-conversation gate while a response streams: blocks Enter and swaps Send for Stop |
+| `onStopStreaming` | `() => void` | — | Stop-button handler |
+| `centered` | `boolean` | `false` | Welcome-screen mode: bigger radius, more padding, larger shadow |
+| `commandProvider` | `CommandProvider \| null` | — | Slash-command typeahead provider |
+| `commandProviders` | `CommandProvider[]` | — | Multiple trigger providers; takes precedence |
+| `className` | `string` | — | Additional CSS classes |
+
+Use `isStreaming` (not `disabled`) while a response is streaming — it keeps the composer editable, blocks submission, and shows the Stop button.
+
+### `MessageAttachments`
+
+Attachment strip rendered inside messages. Image attachments render as inline thumbnails that open a shared lightbox (Esc to close, arrow-key paging, body scroll-lock); non-image files render as downloadable chips. Images whose URL fails to load fall back to the file chip.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `attachments` | `Attachment[]` | — | **Required.** Attachments to display |
+| `onDownload` | `(attachment: Attachment) => void` | — | Custom download handler |
+| `onPreview` | `(attachment: Attachment) => void` | — | Custom preview handler |
+| `align` | `"start" \| "end"` | `"start"` | Edge to align against; use `"end"` for right-aligned viewer messages |
 | `className` | `string` | — | Additional CSS classes |
 
 ### `ChatHeader`
@@ -307,14 +428,31 @@ The `brandingCSSVars` object from `useMiiflowChat` contains CSS custom propertie
 </div>
 ```
 
-Available CSS variables:
+Variables emitted by `brandingCSSVars`:
 
 | Variable | Source | Description |
 |----------|--------|-------------|
 | `--chat-primary` | `backgroundBubbleColor` | Primary accent color |
 | `--chat-user-message-bg` | `backgroundBubbleColor` | User message bubble background |
+| `--chat-user-message-text` | derived | Auto-computed contrast color for user bubbles |
 | `--chat-header-bg` | `headerBackgroundColor` | Header background color |
 | `--chat-message-font-size` | `messageFontSize` | Base message font size |
+| `--chat-font-family` | `fontFamily` | Base font stack |
+| `--chat-approval-accent` / `--chat-approval-accent-soft` | `approvalAccentColor` | Tool-approval panel accent |
+| `--chat-approve-bg` / `--chat-approve-bg-hover` | `approveButtonColor` | Approve button colors |
+| `--chat-reject-bg-hover` | `rejectButtonHoverColor` | Reject button hover |
+| `--chat-clarification-accent` / `--chat-clarification-accent-soft` | `clarificationAccentColor` | Clarification panel accent |
+| `--chat-activity` | `activityAccentColor` | In-progress indicators (falls back to `--chat-primary`) |
+
+Beyond these, the stylesheet declares many more host-overridable `--chat-*` tokens (surfaces, borders, text, radii, composer chrome, `--chat-font-mono` for code, and more) — see `styles.css` for the full set. Set them on any ancestor element to theme the components.
+
+### Dark surfaces
+
+CSS variables handle colors, but some choices can't be expressed in CSS — currently the syntax-highlighting theme for code blocks. If your app renders the chat on a dark surface, pass `isDarkSurface` to `ChatProvider` (the package does not infer dark mode from the OS `prefers-color-scheme`):
+
+```tsx
+<ChatProvider isDarkSurface {...rest}>
+```
 
 ### TailwindCSS Customization
 
@@ -332,13 +470,13 @@ Pass `onUploadFile={uploadFile}` to `MessageComposer` to enable server-side file
 const { sendMessage, uploadFile } = useMiiflowChat(config);
 
 <MessageComposer
-  onSubmit={sendMessage}
+  onSubmit={(content, _files, attachmentIds) => sendMessage(content, attachmentIds)}
   onUploadFile={uploadFile}
   supportsAttachments={true}
 />
 ```
 
-The composer handles file picking, validation, drag-and-drop, and preview thumbnails. Files are uploaded via `uploadFile()` which returns an attachment ID. The IDs are passed along when `sendMessage()` is called.
+The composer handles file picking, validation, drag-and-drop, and preview thumbnails. Files are uploaded via `uploadFile()` which returns an attachment ID; the IDs arrive as `onSubmit`'s third argument. A message with attachments and no text is valid — the composer allows attachment-only sends.
 
 ## Client-Side Tools
 
@@ -364,9 +502,9 @@ await registerTool({
 });
 ```
 
-Tools are automatically re-registered when starting a new thread via `startNewThread()`.
+Tools known at mount time can instead be passed via `config.tools` — they're folded into the session-init round-trip, saving a registration call. Tools are automatically re-registered when starting a new thread via `startNewThread()`.
 
-The `handler` function receives the parameters as a `Record<string, unknown>` and must return a `Promise`. Results are sent back to the assistant automatically. A 30-second timeout is enforced per invocation.
+The `handler` function receives the parameters as a `Record<string, unknown>` and must return a `Promise`. Results are sent back to the assistant automatically. A 30-second timeout is enforced per invocation. Invocations with no locally registered handler are offered to `config.onToolInvocationFallback` (useful when several widgets share one session).
 
 ## System Events
 
@@ -389,6 +527,8 @@ await sendSystemEvent({
 | `followUpInstruction` | `string` | Yes | Instruction for the assistant |
 | `metadata` | `Record<string, unknown>` | No | Additional structured data |
 
+A system event triggers an assistant reply. To attach silent context that the assistant only uses on the *next* user message, use `sendPageContext(context)` instead — it appends hidden context to the thread without generating a response.
+
 ## Identity Verification (HMAC)
 
 For secure identity verification, compute an HMAC on your server and pass it to the config:
@@ -421,6 +561,7 @@ Assistant messages can contain rich visualizations (charts, tables, forms, etc.)
 | `kpi` | `KpiVisualization` | Key performance indicator metrics with trends |
 | `code_preview` | `CodePreviewVisualization` | Syntax-highlighted code blocks |
 | `form` | `FormVisualization` | Interactive forms with validation |
+| `auth_prompt` | `AuthPromptVisualization` | "Connect this integration" card shown when the assistant needs an authorized provider; emits an `auth_connect` action via `onAction` (no button renders without it) |
 
 ### Visualization Registry
 
@@ -441,7 +582,7 @@ registerVisualization("my_widget", {
 
 // Check what's registered
 console.log(getRegisteredTypes());
-// ["chart", "table", "card", "kpi", "code_preview", "form", "my_widget"]
+// ["chart", "table", "card", "kpi", "code_preview", "form", "auth_prompt", "my_widget"]
 ```
 
 Your component receives these props:
@@ -452,6 +593,7 @@ interface VisualizationComponentProps {
   config?: VisualizationConfig;
   isStreaming?: boolean;
   onAction?: (event: VisualizationActionEvent) => void;
+  medias?: MediaChunkData[]; // for resolving media_ref:<id> values
 }
 ```
 
@@ -471,6 +613,7 @@ import {
   kpiVisualizationSchema,
   codePreviewVisualizationSchema,
   formVisualizationSchema,
+  authPromptVisualizationSchema,
 } from "@miiflow/assistant-ui/styled";
 
 const result = chartVisualizationSchema.safeParse(data);
@@ -499,7 +642,7 @@ registerVisualization("my_widget", {
 
 ### Interaction Callbacks
 
-Forms and cards can trigger user interactions (submit, cancel, button click). Instead of listening for global `CustomEvent`s, pass a callback through `ChatProvider`:
+Forms, cards, and auth prompts can trigger user interactions. Instead of listening for global `CustomEvent`s, pass a callback through `ChatProvider`:
 
 ```tsx
 function handleVisualizationAction(event: VisualizationActionEvent) {
@@ -514,12 +657,16 @@ function handleVisualizationAction(event: VisualizationActionEvent) {
     case "card_action":
       console.log("Card action clicked:", event.action);
       break;
+    case "auth_connect":
+      // Kick off your OAuth/connect flow for event.providerName
+      console.log("Connect requested:", event.providerName);
+      break;
   }
 }
 
 <ChatProvider
   messages={messages}
-  onSendMessage={sendMessage}
+  onSendMessage={(content) => sendMessage(content)}
   onVisualizationAction={handleVisualizationAction}
 >
   ...
@@ -532,9 +679,17 @@ The `VisualizationActionEvent` type is a discriminated union:
 type VisualizationActionEvent =
   | { type: "form_submit"; action: string; data: Record<string, unknown> }
   | { type: "form_cancel"; action: string }
-  | { type: "card_action"; action: string };
+  | { type: "card_action"; action: string }
+  | {
+      type: "auth_connect";
+      providerName: string;
+      mcpServerId?: string;
+      serviceProviderId?: string;
+    };
 ```
 
+Note the `auth_connect` variant has no `action` field — narrow on `event.type` before reading variant-specific fields.
+
 **Backward compatibility:** If no `onVisualizationAction` callback is provided, components fall back to dispatching `CustomEvent`s on `window` (`visualization-form-submit`, `visualization-form-cancel`, `visualization-action`).
 
 ### Using `VisualizationRenderer` Standalone
@@ -562,10 +717,11 @@ import { VisualizationRenderer } from "@miiflow/assistant-ui/styled";
 
 | Import | Description |
 |--------|-------------|
-| `@miiflow/assistant-ui` | Core types, context, hooks, primitives |
-| `@miiflow/assistant-ui/styled` | TailwindCSS-styled components, visualization registry, schemas |
-| `@miiflow/assistant-ui/client` | `useMiiflowChat` hook, session utilities, types |
+| `@miiflow/assistant-ui` | Core types, context, hooks, primitives — plus re-exports of the styled components and shared utils (`cn`, format/color helpers, `chatTokens`) |
+| `@miiflow/assistant-ui/styled` | TailwindCSS-styled components, visualization + artifact registries, schemas |
+| `@miiflow/assistant-ui/client` | `useMiiflowChat` hook, session utilities, tool validation, SSE helpers, types |
 | `@miiflow/assistant-ui/primitives` | Headless unstyled component primitives |
+| `@miiflow/assistant-ui/composer` | Lexical composer internals: `LexicalChatInput`, command-token node/plugin/view, `CommandProvider` types |
 | `@miiflow/assistant-ui/styles.css` | Full CSS (includes Tailwind preflight) |
 | `@miiflow/assistant-ui/styles-no-preflight.css` | CSS without preflight (for embedding in existing pages) |
 
@@ -575,7 +731,14 @@ import { VisualizationRenderer } from "@miiflow/assistant-ui/styled";
 `registerVisualization`, `getVisualization`, `getRegisteredTypes`, `VisualizationEntry`
 
 **Visualization Schemas:**
-`chartVisualizationSchema`, `tableVisualizationSchema`, `cardVisualizationSchema`, `kpiVisualizationSchema`, `codePreviewVisualizationSchema`, `formVisualizationSchema`
+`chartVisualizationSchema`, `tableVisualizationSchema`, `cardVisualizationSchema`, `kpiVisualizationSchema`, `codePreviewVisualizationSchema`, `formVisualizationSchema`, `authPromptVisualizationSchema`
+
+**Artifact Registry:**
+`registerArtifact`, `getArtifact`, `getRegisteredArtifactTypes`, `ArtifactInlineCard`, `ArtifactList`
 
 **Types:**
 `VisualizationActionEvent`, `VisualizationChunkData`, `VisualizationConfig`, `VisualizationType`
+
+### Key Exports from `@miiflow/assistant-ui/client`
+
+Beyond `useMiiflowChat`: session helpers (`initSession`, `createThread`, `uploadFile`, `sendSystemEvent`, `sendPageContext`, `sendToolResult`, `getBackendBaseUrl`), tool validation (`validateToolDefinition`, `serializeToolDefinition`, `ToolValidationError`), and SSE-reducer helpers for hosts with their own stream parsing (`findToolChunkIndex`, `MatchableToolChunk`, `ToolFrame`).

package/dist/{WelcomeScreen-Cbipi2rK.d.ts → WelcomeScreen-CSzlU0Yx.d.ts}

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
-import { A as Attachment, M as MessageData, P as ParticipantRole, d as SuggestedAction, S as SourceReference } from './message-D0oMw3tR.js';
-import { h as AvatarProps$1 } from './avatar-CD685KQV.js';
-import { S as StreamingChunk, V as VisualizationChunkData, M as MediaChunkData, A as ArtifactChunkData, C as ClarificationData, T as ToolApprovalData } from './streaming-CmQo_OOA.js';
+import { A as Attachment, M as MessageData, P as ParticipantRole, d as SuggestedAction, S as SourceReference } from './message-DTNTKSQr.js';
+import { h as AvatarProps$1 } from './avatar-B_AvYfE8.js';
+import { S as StreamingChunk, V as VisualizationChunkData, M as MediaChunkData, A as ArtifactChunkData, C as ClarificationData, T as ToolApprovalData } from './streaming-BfLEgW5u.js';
 import { C as CommandProvider } from './types-Du00UBst.js';
 
 interface AttachmentPreviewProps {
@@ -46,12 +46,19 @@ interface MarkdownContentProps {
     className?: string;
     /** Base font size multiplier for responsive scaling */
     baselineFontSize?: number;
-    /** Use dark theme for code blocks */
+    /** Use dark theme for code blocks. Falls back to the host surface's
+     * `isDarkSurface` from ChatProvider. */
     darkCodeTheme?: boolean;
 }
 /**
- * Styled markdown renderer with syntax highlighting, copy-to-clipboard,
- * and heading anchor links.
+ * Markdown renderer for chat messages.
+ *
+ * Appearance lives entirely in the `.chat-prose` rules in
+ * `src/styles/prose.css`; the overrides below carry only behaviour (heading
+ * anchors, the code-block copy button, inline command-token chips, and the
+ * image-URL swap). Keep it that way — the two used to be duplicated, and
+ * because react-markdown v9 dropped the `className` prop the CSS half was
+ * silently dead for the entire time both existed.
  */
 declare function MarkdownContent({ children, className, baselineFontSize, darkCodeTheme, }: MarkdownContentProps): react.JSX.Element;
 
@@ -70,9 +77,14 @@ interface MessageProps {
     renderMarkdown?: boolean;
     /** Streaming chunks for reasoning panel */
     reasoning?: StreamingChunk[];
-    /** Execution plan for completed Plan & Execute messages */
+    /**
+     * @deprecated No longer read. Host adapters already reconstruct these into
+     * `reasoning` chunks, so passing them separately made the same run
+     * describable two ways. Kept on the interface so existing callers compile;
+     * remove in the next major.
+     */
     executionPlan?: unknown;
-    /** Execution timeline for completed messages (all orchestrator modes) */
+    /** @deprecated No longer read — see `executionPlan`. */
     executionTimeline?: unknown[];
     /** Suggested actions */
     suggestedActions?: SuggestedAction[];
@@ -96,6 +108,15 @@ interface MessageProps {
     baselineFontSize?: number;
     /** Total execution time in seconds (persisted from streaming wall-clock) */
     executionTime?: number;
+    /** Epoch ms the in-progress run started. Supply the run's durable start
+     *  (e.g. from a server snapshot) so the streaming elapsed figure stays
+     *  correct across remounts; omit to time from when this component mounted. */
+    streamStartedAt?: number;
+    /** This turn finished moments ago. The streaming message and the completed
+     *  message are different elements, so this component cannot see that edge
+     *  itself — the host reports it, and it is what animates the reasoning
+     *  steps folding into the "Thought for …" line instead of snapping shut. */
+    justCompleted?: boolean;
     /** Pending clarification data (agent needs user input) */
     pendingClarification?: ClarificationData;
     /** Callback when user responds to a clarification */
@@ -113,6 +134,10 @@ interface MessageProps {
     onReportIncorrect?: (reason?: string) => void;
     /** Confirm this assistant response was correct/helpful */
     onConfirmCorrect?: () => void;
+    /** Edit-and-resubmit for the viewer's own messages (ChatGPT-style). When
+     *  provided, a pencil appears in the hover action bar; submitting replaces
+     *  this message and everything after it with a fresh agent turn. */
+    onEditSubmit?: (newText: string) => void;
 }
 /**
  * Styled Message component with grid layout matching the main app.
@@ -165,17 +190,21 @@ declare const MessageComposer: react.ForwardRefExoticComponent<MessageComposerPr
 interface MessageListProps {
     /** Messages to render */
     children: ReactNode;
-    /** Whether to auto-scroll to bottom */
+    /** Whether to auto-scroll to bottom while streaming (follows only when at the live edge) */
     autoScroll?: boolean;
     /** Whether to show the scroll-to-bottom button */
     showScrollToBottom?: boolean;
-    /** Additional CSS classes */
+    /** Additional CSS classes applied to the transcript container (e.g. horizontal padding) */
     className?: string;
 }
 /**
- * Styled MessageList with scrolling, spacing, and scroll-to-bottom button.
- * Uses the enhanced useAutoScroll hook directly instead of going through
- * the primitive, since we need reactive isAtBottom for the button.
+ * Styled MessageList — scroll container for a chat transcript.
+ *
+ * Scroll behavior is provided by shadcn's `@shadcn/react` message-scroller
+ * engine (auto-follow while at the live edge, position preservation, scroll
+ * anchoring) rather than the legacy `useAutoScroll` hook. The public API is
+ * unchanged: pass message rows as `children`; each direct child is wrapped in a
+ * `MessageScroller.Item` for measurement and anchoring.
  */
 declare const MessageList: react.ForwardRefExoticComponent<MessageListProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -221,9 +250,17 @@ declare const SuggestedActions: react.ForwardRefExoticComponent<SuggestedActions
 interface TypingIndicatorProps {
     /** Additional CSS classes */
     className?: string;
+    /** Optional status line rendered beside the mark (e.g. "Getting started…") */
+    label?: string | null;
+    /** Brand mark for the waiting state, supplied by the host. */
+    mark?: ReactNode;
 }
 /**
- * Styled TypingIndicator with animated dots.
+ * The pre-first-token waiting state.
+ *
+ * Kept as a thin wrapper over `ThinkingIndicator` so the primitive's semantics
+ * (and every existing `<TypingIndicator label=… />` call site) survive the
+ * change from three bouncing dots to a decoding line.
  */
 declare const TypingIndicator: react.ForwardRefExoticComponent<TypingIndicatorProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -320,6 +357,9 @@ interface WelcomeScreenProps {
     welcomeText?: string;
     /** Whether to show the attachment (paperclip) button */
     supportsAttachments?: boolean;
+    /** Blocks the built-in input (e.g. while a response is already streaming).
+     *  Ignored when `composerSlot` is provided — that composer owns its own gating. */
+    disabled?: boolean;
     /** Override the default plain-text input with a custom composer (e.g. chat-ui MessageComposer) */
     composerSlot?: ReactNode;
     /** Optional slash-command typeahead provider (e.g. for skill picker). */

package/dist/{avatar-CD685KQV.d.ts → avatar-B_AvYfE8.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode, TextareaHTMLAttributes, ButtonHTMLAttributes } from 'react';
-import { M as MessageData, P as ParticipantRole } from './message-D0oMw3tR.js';
+import { M as MessageData, P as ParticipantRole } from './message-DTNTKSQr.js';
 
 interface MessageContextValue {
     message: MessageData;
@@ -65,6 +65,9 @@ interface MessageComposerProps {
     onSubmit: (content: string, attachments?: File[]) => Promise<void>;
     /** Whether the composer is disabled */
     disabled?: boolean;
+    /** Whether the current conversation is mid-response. Blocks submitting a
+     *  second, concurrent turn into the same conversation. */
+    isStreaming?: boolean;
     /** Children to render inside the composer */
     children: ReactNode;
     /** Additional CSS classes */