@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/Chat/README.md

@@ -51,11 +51,13 @@ export function MyChat() {
 - **Rich attachments.** `AttachmentsGrid` for thumbnails, `AttachmentsList` for custom renderers; `onAttachmentOpen` for lightbox.
 - **Tool-payload dispatcher.** `dispatchToolPayload(matchers, fallback)` — pluggable predicates render `<LazyJsonTree>` / `<LazyMap>` / etc.
 - **Persisted dock prefs.** `headerSlots.modeToggle.persistAs: 'my.key'` stores `mode` / `side` / `width` in localStorage; the toggle lets users flip popover ↔ side and survives reloads. (`useChatDockPrefs()` is now owned by the launcher internally — no longer a consumer-facing hook.)
-- **UX guards.** Auto-focus composer on dock open, two-step Escape (textarea blur → close), click-to-focus on empty message area (Slack / Linear style), `useHotkey('mod+/')` toggle.
+- **UX guards.** Auto-focus composer on dock open, two-step Escape (textarea blur → close), click-to-focus on empty message area **and** on the composer surface padding (Slack / Linear / ChatGPT style), `useHotkey('mod+/')` toggle.
 - **ChatGPT-style autoscroll.** `MessageList` follows the bottom while the user is within `atBottomThreshold` px (default 120). Every user-sent message bumps `scrollAnchorId` and re-anchors the viewport with `behavior: 'smooth'` — sending no longer leaves your own bubble stuck above the fold. Scrolling up by hand breaks the lock; `<JumpToLatest>` brings it back.
-- **Voice composer slot.** `<VoiceComposerSlot />` drops into `composerToolbarEnd` with **zero props** — reads/writes the composer through the `ComposerHandle` registered in chat context. The built-in `<Composer>` and TipTap-backed `MarkdownEditor` register themselves automatically; custom composers wire it via `useRegisterComposer({ focus, moveCursorToEnd, getValue, setValue })`. Auto-gates on Firefox / in-app WebViews / missing `getUserMedia`, preserves typed prefix, 90-second countdown, silence auto-stop, Esc / Enter hotkeys, start / stop earcons. See [`SpeechRecognition`](../SpeechRecognition/README.md).
+- **Voice composer slot.** `<VoiceComposerSlot />` drops into `composer.slots.blockStart` with **zero props** — reads/writes the composer through the `ComposerHandle` registered in chat context. The built-in `<Composer>` and TipTap-backed `MarkdownEditor` register themselves automatically; custom composers wire it via `useRegisterComposer({ focus, moveCursorToEnd, getValue, setValue })`. Auto-gates on Firefox / in-app WebViews / missing `getUserMedia`, preserves typed prefix, 90-second countdown, silence auto-stop, Esc / Enter hotkeys, start / stop earcons. See [`SpeechRecognition`](../SpeechRecognition/README.md).
 - **Language flag button.** `headerSlots.languagePicker: true` slots a 28×28 country flag into the dock header — opens a searchable `<Combobox>` with 66 BCP-47 tags from the Chrome Web Speech catalogue. Selection persists via `useSpeechPrefs`, picked up by every `useSpeechRecognition` downstream. (Raw `<ChatHeaderLanguageButton>` still exported for custom shells.)
-- **Auto-focus on stream end.** `useAutoFocusOnStreamEnd()` (active inside `ChatRoot` by default) re-focuses the composer on the streaming → idle edge — type → send → read → keep typing without reaching for the mouse.
+- **Auto-focus on stream end.** `<ChatProvider>` re-focuses the registered composer on the streaming → idle edge — type → send → read → keep typing without reaching for the mouse. Works for **every** usage pattern (`ChatRoot`, hand-rolled `ChatProvider` + `Composer`, headless), not just `ChatRoot`. Opt out with `<ChatProvider autoFocusOnStreamEnd={false}>`. The standalone `useAutoFocusOnStreamEnd()` hook is still exported for advanced cases (focus a non-composer target, drive `isStreaming` from your own store).
+- **Page-context snapshot.** Optional `getDynamicMetadata` contributor on `<ChatProvider>` / `<ChatRoot>` — called fresh at send time, merged into transport `metadata`. Pairs with the `page-snapshot` engine (`src/lib/page-snapshot`) to attach a token-efficient, redacted snapshot of the page the user is looking at, so the assistant can answer in context. The snapshot rides a separate `metadata` field, never the message text.
+- **AI highlight directives.** `highlight/` — when the assistant returns `point` directives, `<HighlightOverlay>` resolves each CST ref to a live element and draws an SVG-mask spotlight (optionally moves focus). Read-only: it points at the UI, never changes data. See [`highlight/README.md`](./highlight/README.md).
 - **Centralized colors.** Role-aware className tokens (`BUBBLE_SURFACE` / `ANCHOR` / `TOGGLE` / `DESTRUCTIVE_SURFACE`) + hooks (`useChatBubbleStyles`, `useChatRoleStyles`, `useChatDestructiveStyles`).
 - **Responsive.** FAB `size='responsive'` (default): phone → `sm`, tablet → `md`, desktop → `lg`. Side mode is desktop-only and falls back to popover below `lg`.
 - **Mobile fullscreen.** Dock auto-fills viewport below 768px via `useIsMobile`. Heights use `dvh/svh/lvh` so iOS Safari URL bar doesn't clip the chat.
@@ -68,7 +70,7 @@ Transport (interface)              ←  Pydantic-AI / HTTP+SSE / Wails / mock
    ↓
 Reducer (pure state machine)
    ↓
-Hooks (useChat / useChatComposer / useChatScroll / useChatHistory / useChatLayout)
+Hooks (useChat / useChatComposer / useChatHistory / useChatLayout)
    ↓
 ChatProvider (context)
    ↓
@@ -79,18 +81,25 @@ ChatRoot (one-line preset)  ◄──  optionally wrapped by  ──►  ChatLau
 
 `ChatLauncher` mounts the `ChatProvider` itself — pass `transport` / `config` / `audio` / `initialSessionId` / `autoCreateSession` / `streaming` / `debug` to the launcher and use `<ChatRoot />` without props as the child. `ChatRoot` detects the ambient provider and reuses it; standalone `<ChatRoot transport={…}>` still works for non-launcher embeds. This is what makes declarative `headerSlots` (which render in the dock header) able to call `useChatContext()` and read `sessionId` / `clearMessages` / etc.
 
+`ChatProvider` also owns chat-wide UX behaviour that must hold regardless of which preset wraps it — notably **stream-end composer re-focus** (`autoFocusOnStreamEnd`, default `true`). Putting it in the provider means a hand-rolled `ChatProvider` + `MessageList` + `Composer` layout behaves identically to `ChatRoot` with no extra wiring.
+
 Module boundaries:
 
 | Layer            | May import                       | May NOT import           |
 | ---------------- | -------------------------------- | ------------------------ |
 | `types/`         | —                                | anything                 |
-| `core/transport` | `types/`                         | React, hooks, components |
+| `constants.ts`   | —                                | anything                 |
+| `core/transport` | `types/`                         | React, hooks, UI         |
 | `core/reducer`   | `types/`                         | React, transport         |
-| `hooks`          | `core/*`, `ui-core` hooks        | components               |
-| `context`        | `hooks`                          | components               |
-| `styles/`        | `types/`                         | hooks, components        |
-| `components`     | `hooks`, `context`, `styles`, `ui-core` UI | transport implementations |
-| `launcher/`      | `components`, `styles`, `ui-core` UI | transport implementations |
+| `hooks`          | `core/*`, `ui-core` hooks        | UI folders               |
+| `context`        | `hooks`                          | UI folders               |
+| `styles/`        | `types/`                         | hooks, UI folders        |
+| `utils/`         | `types/`                         | React, UI folders        |
+| `messages/`      | `hooks`, `context`, `styles`, `ui-core` UI | transport implementations |
+| `composer/`      | `hooks`, `context`, `styles`, `messages`, `ui-core` UI | transport implementations |
+| `shell/`         | `messages`, `composer`, `hooks`, `context`, `ui-core` UI | transport implementations |
+| `launcher/`      | `shell`, `messages`, `composer`, `styles`, `ui-core` UI | transport implementations |
+| `launcher/header/` | `context`, `hooks`, `launcher` siblings | transport implementations |
 
 ## Types
 
@@ -107,6 +116,7 @@ Single source of truth in [`types/`](./types/index.ts). Split by domain — impo
 | `events` | `ChatStreamEvent` SSE union |
 | `session` | `SessionInfo`, `HistoryPage`, `Stream/Send/CreateSessionOptions` |
 | `transport` | `ChatTransport` |
+| `block` | `MessageBlock` union + `BlockAppearance` (see Message blocks) |
 
 ## Launcher (FAB + Dock + Greeting)
 
@@ -525,6 +535,58 @@ function MyError() {
 }
 ```
 
+## Message blocks
+
+A message can carry typed, serializable rich content beyond its markdown
+`content`: an optional `blocks: MessageBlock[]`. `MessageBlock` is a
+discriminated union on `kind` — `text`, `markdown`, `audio`, `video`,
+`image`, `gallery`, `map`, `json`, `mermaid`, `code`, `lottie`, plus a
+`custom` escape hatch. Payloads are plain JSON, so blocks survive history
+persistence and SSE transport.
+
+`<MessageBubble>` renders blocks **after** the markdown bubble, before
+`toolCalls`. `text`/`markdown` blocks keep the bubble surface; media
+blocks render full-width below it. Legacy messages (no `blocks`) render
+byte-for-byte unchanged.
+
+```ts
+const msg: ChatMessage = {
+  id: 'm-42', role: 'assistant', createdAt: Date.now(), content: '',
+  blocks: [
+    { kind: 'markdown', id: 'b1', markdown: 'Recording from **vps-audi**:' },
+    { kind: 'audio', id: 'b2', src: 'https://cdn…/call.mp3', title: 'Call · 04:12' },
+    { kind: 'map', id: 'b3', caption: 'Server', center: { lat: 52.52, lng: 13.405 }, zoom: 11 },
+  ],
+};
+```
+
+### The registry
+
+Each `kind` maps to a `BlockRenderer` in a `BlockRegistry` — same idea as
+`AttachmentRendererMap`, but keyed by the discriminant. Built-in renderers
+cover the in-house tools (`BUILTIN_BLOCK_REGISTRY`); each is reached
+through a `React.lazy` chunk, so a chat with no map block never downloads
+MapLibre.
+
+Merge host overrides with `createBlockRegistry`:
+
+```ts
+const registry = createBlockRegistry({
+  json: (block) => <MyJsonCard data={block.data} />, // override one kind
+});
+```
+
+Pass it via `<ChatRoot messages={{ blockRegistry }}>` — it is threaded
+through context to every `<MessageBubble>`. `<MessageBubble>` also accepts
+a direct `blockRegistry` prop (prop beats context) for standalone /
+Storybook use. An unknown `kind` is skipped silently (lenient default);
+`<MessageBlocks strict>` surfaces a dev notice. Each block is wrapped in
+an error boundary so one malformed block can't blank the transcript.
+
+Exports (`@djangocfg/ui-tools/chat`): `MessageBlocks`,
+`createBlockRegistry`, `BUILTIN_BLOCK_REGISTRY`, and the `MessageBlock` /
+`BlockRegistry` / `BlockRenderer` / `BlockRenderContext` types.
+
 ## Transport contract
 
 A single I/O seam.
@@ -564,11 +626,169 @@ for await (const event of parseSSE(res, { map: createPydanticAISSEMap() })) {
 }
 ```
 
-## Slots
+## `ChatRoot` props
+
+`<ChatRootProps>` groups ~13 keys by concern — no flat `composer*` namespace:
+
+```tsx
+<ChatRoot
+  // core wiring
+  transport={transport}
+  config={{ greeting: 'Hi!' }}
+  session={{ initialId, autoCreate: true }}
+  streaming
+  audio={{}}
+  debug
+
+  // presentation
+  appearance="compact"            // 'compact' | 'full' — scales the whole chat
+  className="…"
+  listClassName="px-6 pt-6"       // padding inside the scroll viewport
+
+  // composition (grouped)
+  slots={{
+    banner: <QuotaWarning />,
+    header: (ctx) => <MyHeader sessionId={ctx.sessionId} />,  // node or fn
+    empty: ({ setValue, focus }) => <MyEmpty seed={setValue} />,  // node or fn
+    jumpToLatest: <MyPill />,
+  }}
+  composer={{
+    size: 'lg',                   // 'sm' | 'md' | 'lg'
+    layout: 'stacked',            // 'stacked' | 'inline'
+    className: '…',
+    hidden: false,                // unmount the composer (human-in-the-loop pause)
+    showAttachmentButton: true,
+    onPickFiles: () => openPicker(),
+    slots: { actionsStart, actionsEnd, blockStart },  // ComposerSlots
+    footer: { showCounter: true } /* | false to hide */,
+    render: ({ composer, config }) => <MyComposer composer={composer} />,
+  }}
+  messages={{
+    render: (m, i) => <MyBubble message={m} />,
+    renderAfter: (m) => <SideChannelWidget messageId={m.id} />,
+    toolCallsProps: { defaultExpanded: true },
+    attachmentRenderers: { image: MyImageTile },
+    onAttachmentOpen: (a) => openLightbox(a),
+  }}
+
+  // behavior
+  focusOnEmptyClick                // default true
+
+  // page context — extra metadata computed fresh per send
+  getDynamicMetadata={() => ({ pageContext })}
+/>
+```
+
+`getDynamicMetadata` is forwarded to the `<ChatProvider>` that `ChatRoot`
+creates; it is **ignored** when `ChatRoot` mounts under an ambient
+provider — set it on that provider instead. Typically wired from
+`usePageSnapshot().getChatMetadata` (see `src/lib/page-snapshot`).
+
+The `slots.header` / `slots.empty` accept either a `ReactNode` or a render
+function — there is no separate `renderHeader` / `renderEmpty` prop and no
+"which one wins" precedence. `composer.render` fully replaces the built-in
+`<Composer>`; it receives `{ composer, config }` — the live composer hook
+plus the same config object. See **[Slots inventory](#slots-inventory)** below.
+
+## Composer slot system
+
+`<Composer>` is a single bordered input surface — textarea on top, an
+action bar pinned to the bottom inside the same frame (attach
+bottom-left, mic + send bottom-right). Two layouts:
 
-`<ChatRoot>` exposes named-prop slots — `header`, `footer`, `banner`, `empty`, `composerToolbarStart/End`, `composerAttachmentTray`, `jumpToLatest`. None are required.
+- `layout="stacked"` (default) — Telegram-style two-tier surface.
+- `layout="inline"` — compact single row. `size="sm"` defaults to this.
 
-See **[Slots inventory](#slots-inventory)** below for the full list, plus `hideComposer` / `hideToolCalls` / `renderToolCall` / `renderAfterCalls` patterns.
+### Tier A — declarative actions
+
+Pass `ComposerAction[]` arrays; the composer renders consistent,
+correctly-aligned, fully-labelled buttons. Built-in send/stop/attach are
+themselves descriptors — host extras land between attach and mic/send.
+
+```tsx
+<Composer
+  composer={composer}
+  composerSlots={{
+    actionsStart: [{ id: 'emoji', icon: <Smile />, label: 'Emoji', onClick }],
+    actionsEnd: [{ id: 'model', icon: <Sparkles />, label: 'Model', onClick }],
+    blockStart: <ReplyBanner />,        // full-width row above the textarea
+  }}
+/>
+```
+
+`ComposerAction` fields: `id`, `icon`, `label` (required — `aria-label` +
+tooltip), `onClick`, `disabled?`, `pressed?` (→ `aria-pressed`),
+`variant?`, `hideWhen?` (`streaming` | `empty` | `hasText` | `disabled`),
+`order?`. Memoize the arrays so the action bar does not churn.
+
+### Tier B — slot replacement
+
+Replace a primitive entirely via `slots` / tweak its props via
+`slotProps`:
+
+```tsx
+<Composer composer={composer}
+  slots={{ SendButton: MyBrandedSend, Textarea: MyEditor }}
+  slotProps={{ textarea: { className: 'font-mono' } }}
+/>
+```
+
+Swappable: `SendButton`, `AttachButton`, `Textarea`, `ActionBar`.
+
+### mic ↔ send swap
+
+`micSendSwap` (default `true`) — Telegram behaviour: an action with
+`id: 'mic'` (or `hideWhen: 'hasText'`) shows only while the draft is
+empty; once there is text, send takes its place. Set `false` to keep
+both visible (voice-message hosts).
+
+### Footer toolbar
+
+`<ComposerFooter>` is the quiet strip below the surface — three zones:
+`start` (auto keyboard hint), `center` (host extras), `end` (auto char
+counter that only appears near `maxLength`). Configure via the
+`footer` prop on `<Composer>` or `composer.footer` on `<ChatRoot>`;
+pass `false` to hide.
+
+### Composer kit — ready-made slot widgets
+
+ChatGPT / Gemini-style controls that drop straight into `composerSlots`.
+All are exported from `@djangocfg/ui-tools/chat` and size-aware (they
+inherit the composer `size` via context, no prop needed).
+
+| Component | Slot | What it is |
+|---|---|---|
+| `<ComposerMenuButton items={MenuItem[]}>` | `inlineStart` | The ChatGPT `+` button — opens a declarative `MenuBuilder` dropdown (sections, submenus, shortcuts). |
+| `<ComposerToolPill icon label active onRemove>` | `inlineStart` | Gemini-style capsule for a selected tool/mode with an optional `×` to clear it. |
+| `<ComposerModelPicker value options onChange>` | `inlineEnd` | "Flash-Lite ▾" pill — opens a radio-group model picker. |
+| `<ComposerBanner variant title description actions onDismiss>` | `blockStart` | Standalone notice bubble above the composer (upsell / quota / info). |
+| `<ComposerRichTextarea mentions>` | `slots.Textarea` (Tier B) | Ready-made TipTap chat editor — unstyled, no toolbar, size-matched height, Enter-to-send, `@`-mention support. |
+
+```tsx
+<Composer
+  composer={composer}
+  composerSlots={{
+    blockStart: <ComposerBanner variant="upgrade" title="Free plan limit" … />,
+    inlineStart: <ComposerMenuButton items={MENU_ITEMS} />,
+    inlineEnd: <ComposerModelPicker value={model} options={MODELS} onChange={setModel} />,
+  }}
+/>
+```
+
+### `appearance` — compact vs full
+
+`<Composer appearance="full">` layers extra spaciousness (radius,
+padding, taller textarea, larger text) over the chosen `size` — for a
+full-page ChatGPT/Gemini surface. `compact` (default) keeps the embedded
+docked-chat geometry. Orthogonal to `size`; `<ChatRoot appearance="full">`
+threads it to both the composer and the message bubbles.
+
+### Click-to-focus surface
+
+The whole input panel reads as a text field — the padding around the
+editor shows a text caret and a `mousedown` on the bare surface (not a
+button) focuses the editor. Works for both the plain `<textarea>` and the
+TipTap (`contenteditable`) backend.
 
 ## Three usage patterns
 
@@ -627,7 +847,7 @@ type HttpTransportConfig, type MockTransportOptions, type ParseSSEOptions,
 type PydanticAIChatTransportOpts, type PydanticAIEvent, type ToolIdQueue
 
 // Hooks
-useChat, useChatComposer, useChatScroll, useChatHistory, useChatLayout,
+useChat, useChatComposer, useChatHistory, useChatLayout,
 useChatLightbox, useAutoFocusOnStreamEnd, useRegisterComposer,
 useChatReset, useVisitorFingerprint, useChatUnread, useChatUnreadNotifier,
 createBrowserNotifier, createCrossTabNotifier, createTitleRotator, createFaviconBadge,
@@ -682,22 +902,41 @@ JumpToLatest, StreamingIndicator
 // `MessageList` exposes `atBottomThreshold` (default 120 px) and
 // `scrollAnchorId` props for ChatGPT-style autoscroll — see "What you get".
 
+// Composer kit — slot widgets + types
+ComposerButton, ComposerActionBar, ComposerFooter,
+ComposerMenuButton, ComposerToolPill, ComposerModelPicker,
+ComposerBanner, ComposerRichTextarea, useComposerActions, useResolvedComposerSize
+type ComposerProps, type ComposerSize, type ComposerAppearance,
+type ComposerLayout, type ComposerAction, type ComposerActionVisibility,
+type ComposerSlots, type ComposerSlotComponents, type ComposerSlotProps,
+type ComposerFooterProps, type ComposerMenuButtonProps, type ComposerToolPillProps,
+type ComposerModelPickerProps, type ComposerModelOption,
+type ComposerBannerProps, type ComposerBannerAction, type ComposerRichTextareaProps,
+type ComposerTextareaProps, type SendButtonProps, type AttachButtonProps
+
+// Message blocks
+MessageBlocks, createBlockRegistry, BUILTIN_BLOCK_REGISTRY
+type MessageBlock, type BlockAppearance, type BlockRegistry,
+type BlockRenderer, type BlockRenderContext
+
 // Lazy preset
 LazyChat
 ```
 
 ## Storybook
 
-Stories live next to components — open `@djangocfg/playground`:
+Stories are grouped into five feature sub-groups under `UI Tools/Chat`,
+plus `Overview` (MDX) and `Showcase` (a one-screen living demo):
 
-- `Tools/Chat/Basic` — Default + Composition patterns.
-- `Tools/Chat/Bubbles` — every bubble state in one screen.
-- `Tools/Chat/ToolCalls` — streaming panels + JsonTree payload dispatch.
-- `Tools/Chat/Personas` — per-message persona overrides, multi-user transcripts.
-- `Tools/Chat/Launcher` — Default / Playground / LiveChatStyle / MobileFullscreen / WithLivePush / VariantsAndSizes.
-- `Tools/Chat/Header` — `ChatHeader` standalone, persistent dock prefs, side mode.
-- `Tools/Chat/Audio & Actions` — audio toggle auto-inject, reset with `window.dialog.confirm`.
-- `Tools/Chat/Voice composer` — `<VoiceComposerSlot>` wired into the composer toolbar with a mock STT engine.
+- **Getting Started** — `ChatRoot`, `Composition` (bring-your-own-layout),
+  `Appearance` (compact / full / huge).
+- **Messages** — `Bubbles`, `Markdown`, `Message Blocks`,
+  `Tool Calls & Sources`, `Streaming`, `Personas`.
+- **Composer** — `Playground`, `Layout & Actions`, `Menu & Tools`,
+  `Banner`, `Mentions`, `Speech & Attachments`.
+- **Launcher** — `Playground`, `Parts`, `Header`,
+  `Unread & Notifications`.
+- **Transports** — the three shipped transports with a stubbed `fetchImpl`.
 
 ---
 
@@ -705,37 +944,36 @@ Stories live next to components — open `@djangocfg/playground`:
 
 ## Slots inventory
 
-| Slot | Position | Render-prop variant |
+| Key | Position | Type |
 |---|---|---|
-| `header` | Above messages | `renderHeader({ messages })` |
-| `footer` | Below composer | `renderFooter({ canSend })` |
-| `banner` | Top of message list | `renderBanner({ error, dismiss, retry })` |
-| `empty` | Empty state | `renderEmpty({ config, send })` |
-| `composerToolbarStart` / `composerToolbarEnd` | Composer toolbar | — |
-| `composerAttachmentTray` | Above composer textarea | `renderAttachmentTray({ attachments })` |
-| `jumpToLatest` | Sticky overlay | `renderJumpToLatest({ unread, scrollToBottom })` |
-| `renderToolCall` | Per tool-call panel | `(call) => ReactNode` |
-| `renderAfterCalls` | After all tool panels | `(calls) => ReactNode` — **only renders when the message has tool calls** |
-| `renderAfterMessage` | Below every assistant bubble | `(message) => ReactNode` — fires for every message, independent of `toolCalls` |
+| `slots.banner` | Top of message list | `ReactNode` |
+| `slots.header` | Above messages | `ReactNode \| (ctx) => ReactNode` |
+| `slots.empty` | Empty state | `ReactNode \| ({ setValue, focus }) => ReactNode` |
+| `slots.jumpToLatest` | Sticky overlay | `ReactNode` |
+| `composer.slots.actionsStart` / `actionsEnd` | Composer action clusters | `ComposerAction[]` |
+| `composer.slots.blockStart` | Above composer textarea | `ReactNode` |
+| `composer.footer` | Below composer | `ComposerFooterProps \| false` |
+| `composer.render` | Replace `<Composer>` | `({ composer, config }) => ReactNode` |
+| `messages.render` | Replace each bubble | `(m, i) => ReactNode` |
+| `messages.renderAfter` | Below every assistant bubble | `(m) => ReactNode` — fires for every message, independent of `toolCalls` |
 
 Flags:
 
-- `hideComposer` — agent-pause / human-in-the-loop pause; composer is unmounted.
-- `hideToolCalls` — show only `renderAfterCalls` rich UI without raw tool panels.
+- `composer.hidden` — agent-pause / human-in-the-loop pause; composer is unmounted.
 
-### Which slot for product widgets — `renderAfterCalls` vs `renderAfterMessage`?
+### Which slot for product widgets — `renderAfterCalls` vs `messages.renderAfter`?
 
 Both put custom content under the assistant bubble; the difference is **what triggers them**.
 
 - `renderAfterCalls` is gated on `message.toolCalls?.length > 0`. Use it when the widget is **derived from raw tool output** (read `call.output`) and you can rely on the host streaming the `tool_call` / `tool_result` SSE frames. Admin / dev flows typically work this way.
-- `renderAfterMessage` fires **for every message**, regardless of `toolCalls`. Use it when the widget is driven by a side channel — e.g. typed `ui_payload` SSE frames the host emits independently of the raw tool surface. This is the correct slot when the public-prod stream **hides** `tool_call` events for security: the message lands with `toolCalls === undefined`, so `renderAfterCalls` would never mount, but `renderAfterMessage` still runs and the widget renders from the side channel.
+- `messages.renderAfter` fires **for every message**, regardless of `toolCalls`. Use it when the widget is driven by a side channel — e.g. typed `ui_payload` SSE frames the host emits independently of the raw tool surface. This is the correct slot when the public-prod stream **hides** `tool_call` events for security: the message lands with `toolCalls === undefined`, so `renderAfterCalls` would never mount, but `messages.renderAfter` still runs and the widget renders from the side channel.
 
 Recommended pairing for a "vehicle cards" / "tax breakdown" / "chart" widget on a public chat:
 
 ```tsx
 <ChatRoot
   transport={transport}
-  renderAfterMessage={(m) => <VehicleCardsForMessage messageId={m.id} />}
+  messages={{ renderAfter: (m) => <VehicleCardsForMessage messageId={m.id} /> }}
 />
 ```