@djangocfg/ui-tools 2.1.381 → 2.1.382

package/src/tools/Chat/README.md

@@ -1,22 +1,28 @@
 # Chat
 
-Decomposed, transport-agnostic chat. Streaming-aware, markdown-native, mobile-ready.
+Decomposed, transport-agnostic chat. Streaming-aware, markdown-native, mobile-ready, role-aware styling, pluggable backends.
 
 ## TL;DR
 
 ```tsx
-import { ChatRoot, createHttpTransport } from '@djangocfg/ui-tools';
+import { ChatRoot, createPydanticAIChatTransport, ChatLauncher } from '@djangocfg/ui-tools';
 
-const transport = createHttpTransport({
-  baseUrl: '/api/chat',
-  getAuthHeader: () => ({ Authorization: `Bearer ${getToken()}` }),
+const transport = createPydanticAIChatTransport({
+  buildStreamUrl: (sid, msg) => `${API}/chat/sessions/${sid}/stream?message=${encodeURIComponent(msg)}`,
+  streamMethod: 'GET',
+  buildHeaders: async () => ({ Authorization: `Bearer ${getToken()}` }),
 });
 
 export function MyChat() {
   return (
-    <div className="h-[600px]">
+    <ChatLauncher
+      hotkey={{ key: '/', meta: true }}
+      fab={{ variant: 'animated', tooltip: 'Open chat (⌘/)' }}
+      dock={{ title: 'Assistant', height: 600 }}
+      greeting="Hi 👋 Need help?"
+    >
       <ChatRoot transport={transport} config={{ greeting: 'How can I help?' }} />
-    </div>
+    </ChatLauncher>
   );
 }
 ```
@@ -24,23 +30,33 @@ export function MyChat() {
 ## What you get
 
 - **Headless first.** Pure reducer + hooks; UI is optional and replaceable.
+- **Launcher primitives.** `ChatLauncher` / `ChatFAB` (3 variants, responsive sizing) / `ChatDock` (popover + side modes, mobile fullscreen) / `ChatGreeting` (proactive invite) / `ChatUnreadPreview` (live-push notification).
+- **Header actions.** `ChatHeader` + `ChatHeaderActionButton` + ready-made `ChatHeaderModeToggle` / `ChatHeaderAudioToggle` / `ChatHeaderResetButton` (with `window.dialog.confirm`) / `ChatHeaderLanguageButton` (flag picker for speech-recognition language).
 - **Decomposed.** `MessageList`, `MessageBubble`, `Composer`, `Sources`, `ToolCalls`, `Attachments`, `EmptyState`, `ErrorBanner`, `JumpToLatest`, `StreamingIndicator` — every part exported.
 - **Markdown-native.** Sits on top of `MarkdownMessage` (GFM, code, mermaid, sanitized HTML).
-- **Streaming.** SSE-based `AsyncGenerator` transport. Token coalescing, cancel, regenerate, partial-keep on cancel.
-- **Tool calls.** Live streaming panels — auto-open while running, auto-close on completion. User toggles are remembered.
-- **Personas.** `config.user` + `config.assistant` for default identity; `message.sender` for per-message overrides (multi-user / multi-bot).
-- **Audio triggers.** Optional sounds on `messageSent`, `messageReceived`, `streamStart`, `error`, `mention`, `notification`. iOS/Safari unlock handled automatically.
-- **Rich attachments.** `AttachmentsGrid` for thumbnails, `AttachmentsList` for custom renderers; `onAttachmentOpen` for host-side lightbox.
-- **Tool-payload dispatcher.** `dispatchToolPayload(matchers, fallback)` — pluggable predicates choose `<LazyJsonTree>` / `<LazyMap>` / etc. without ui-tools owning those deps.
-- **Sources.** RAG citation chips on assistant messages.
-- **Slots everywhere.** `header`, `footer`, `banner`, `empty`, `composerToolbarStart/End`, `composerAttachmentTray`, `jumpToLatest` — plus render-prop variants.
-- **Mobile.** `100dvh`, safe-area inset, 16px textarea (no iOS zoom), responsive `useChatLayout`.
+- **Streaming.** SSE-based `AsyncGenerator` transport. Spec-compliant `parseSSE`, token coalescing, cancel, regenerate.
+- **Pydantic-AI mapper.** Built-in adapter for Django/pydantic-AI backends — `text_delta` / `tool_call` / `tool_result` → canonical `ChatStreamEvent`. FIFO tool-id queue.
+- **Tool calls.** Live streaming panels, auto-open while running, auto-close on completion. Per-call `memo` so streaming one tool doesn't re-render siblings.
+- **Live push.** `chat.injectMessage(msg)` / `updateMessage(id, patch)` for admin takeover / Centrifugo / WebSocket inbound. `useChatUnread()` tracks unseen; `<ChatUnreadPreview>` surfaces them next to the FAB.
+- **Personas.** `config.user` + `config.assistant` for default identity; `message.sender` for per-message overrides.
+- **Audio.** `useChatAudio` over `@djangocfg/ui-core/hooks/useNotificationSounds` — Safari unlock, persisted mute, per-event toggles, reduced-motion respect. Slack/Linear-style per-event volume scale (error ≈ 0.25, mention ≈ 1.0). **Built-in sounds bundled as base64 data URLs** in the lazy chat chunk (~136KB) — `useChatAudio()` with no arguments just works. `silenced` + `onSoundEvent` for native hosts (cmdop_go / Tauri).
+- **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.** `useChatDockPrefs()` stores `mode` / `side` / `width` in localStorage; `<ChatHeaderModeToggle>` lets users flip popover ↔ side and survives reloads.
+- **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.
+- **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).
+- **Language flag button.** `<ChatHeaderLanguageButton />` slots into the dock header — 28×28 country flag 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.
+- **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.
+- **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.
 - **A11y.** `role="log"` + polite live region, `aria-busy` on streaming bubbles, `role="alert"` errors, focus-visible actions.
 
 ## Architecture
 
 ```
-Transport (interface)              ←  HTTP+SSE / Wails / WebSocket / mock
+Transport (interface)              ←  Pydantic-AI / HTTP+SSE / Wails / mock
    ↓
 Reducer (pure state machine)
    ↓
@@ -50,507 +66,342 @@ ChatProvider (context)
    ↓
 Components (MessageList, MessageBubble, Composer, Sources, ToolCalls, …)
    ↓
-ChatRoot (one-line preset)
+ChatRoot (one-line preset)  ◄──  optionally wrapped by  ──►  ChatLauncher (FAB + Dock + Greeting)
 ```
 
 Module boundaries:
 
 | Layer            | May import                       | May NOT import           |
 | ---------------- | -------------------------------- | ------------------------ |
-| `core/transport` | `core/types`                     | React, hooks, components |
-| `core/reducer`   | `core/types`                     | React, transport         |
+| `types/`         | —                                | anything                 |
+| `core/transport` | `types/`                         | React, hooks, components |
+| `core/reducer`   | `types/`                         | React, transport         |
 | `hooks`          | `core/*`, `ui-core` hooks        | components               |
 | `context`        | `hooks`                          | components               |
-| `components`     | `hooks`, `context`, `ui-core` UI | transport implementations |
-
-## Slots
-
-`<ChatRoot>` exposes named-prop slots for the most common roles. None are required; omit any slot to fall back to the default.
+| `styles/`        | `types/`                         | hooks, components        |
+| `components`     | `hooks`, `context`, `styles`, `ui-core` UI | transport implementations |
+| `launcher/`      | `components`, `styles`, `ui-core` UI | transport implementations |
+
+## Types
+
+Single source of truth in [`types/`](./types/index.ts). Split by domain — import from the top-level `@djangocfg/ui-tools` barrel.
+
+| Domain | What's there |
+|---|---|
+| `persona` | `ChatRole`, `ChatPersona`, `ChatUserContext`, `ChatAssistantContext` |
+| `message` | `ChatMessage` |
+| `tool-call` | `ChatToolCall` |
+| `attachment` | `ChatAttachment`, `ChatSource` |
+| `labels` | `ChatLabels` + `DEFAULT_LABELS` |
+| `config` | `ChatConfig`, `ChatPrefs`, `ChatDisplayMode` |
+| `events` | `ChatStreamEvent` SSE union |
+| `session` | `SessionInfo`, `HistoryPage`, `Stream/Send/CreateSessionOptions` |
+| `transport` | `ChatTransport` |
+
+## Launcher (FAB + Dock + Greeting)
+
+Picks the highest level that fits.
+
+| Component | Use when |
+|---|---|
+| `<ChatLauncher>` | FAB + dock + greeting + push-preview + hotkey + audio toggle (~99% of cases) |
+| `<ChatDock>` | Custom trigger (header button, inline link). Popover or side mode. |
+| `<ChatFAB>` | Floating button only |
+| `<ChatGreeting>` | Standalone proactive bubble |
+| `<ChatUnreadPreview>` | Standalone push-notification bubble |
+| `<ChatHeader>` + `<ChatHeaderActionButton>` | Custom header chrome |
+| `<ChatHeaderModeToggle>` | Popover ↔ side toggle (desktop-only, auto-hides below `lg`) |
+| `<ChatHeaderAudioToggle>` | Mute / unmute notification sounds |
+| `<ChatHeaderResetButton>` | Clear conversation with `window.dialog.confirm` |
+| `<ChatHeaderLanguageButton>` | Flag-button language picker (66 BCP-47 tags, persists in `useSpeechPrefs`) |
+
+### FAB
 
 ```tsx
-<ChatRoot
-  transport={transport}
-  config={{ greeting: 'Hi!' }}
-
-  // ReactNode slots
-  banner={<UpgradeBanner />}              // sticky note above the conversation
-  header={<MyChatHeader />}               // title / actions row
-  footer={<Disclaimer />}                 // below the composer
-  empty={<MyEmptyState />}                // replaces default <EmptyState>
-  composerToolbarStart={<VoiceButton />}  // left of the textarea
-  composerToolbarEnd={<MentionButton />}  // right of the textarea
-  composerAttachmentTray={<MyTray />}     // replaces default attachment tray
-  jumpToLatest={<MyJumpPill />}           // replaces floating "↓ N new" pill
-
-  // Render-prop slots (need access to data)
-  renderMessage={(m, i) => <MyBubble message={m} />}
-  renderHeader={(ctx) => (ctx.isStreaming ? <Streaming /> : <Idle />)}
-  renderEmpty={({ setValue, focus }) => <MyOnboarding onPick={setValue} />}
-
-  // Tool-call payload renderers — forwarded to <MessageBubble toolCallsProps>
-  toolCallsProps={{
-    defaultExpanded: true,
-    renderInput:  (v) => <LazyJsonTree data={v} mode="compact" />,
-    renderOutput: (v) => <LazyJsonTree data={v} mode="compact" />,
-  }}
-
-  // Hide composer while agent is paused waiting for human input
-  hideComposer={hasPendingApprovals}
-/>
-```
-
-### Slot inventory
-
-```
-┌───────────────────────────────┐
-│ banner          (sticky)      │
-├───────────────────────────────┤
-│ header                        │
-├───────────────────────────────┤
-│ messages    (jumpToLatest)    │
-├───────────────────────────────┤
-│ composerToolbarStart          │  ← hidden when hideComposer={true}
-│   [textarea]   composerToolbarEnd │
-│ composerAttachmentTray        │
-├───────────────────────────────┤
-│ footer                        │  ← use for approval panels, disclaimers
-└───────────────────────────────┘
+fab={{
+  variant: 'simple' | 'animated' | 'glass',   // default 'simple'
+  size: 'responsive',                         // default — phone=sm/tablet=md/desktop=lg
+  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left',
+  offset: 24,
+  pulse: true,                                // attention dot + ping
+  badge: 5,                                   // unread count (renders "9+")
+  tooltip: 'Open chat',                       // hover/focus label
+  icon: <Sparkles />,
+  inline: true,                               // no fixed positioning (stories/previews)
+}}
 ```
 
-### hideComposer — agent-pause / human-in-the-loop
-
-Set `hideComposer={true}` to remove the composer while the agent is waiting for a human decision (approval gate, HITL). Combine with `footer` to show action buttons:
+### Dock
 
 ```tsx
-<ChatRoot
-  transport={transport}
-  hideComposer={pendingActions.length > 0}
-  footer={
-    pendingActions.length > 0 ? (
-      <AgentActions actions={pendingActions} onResult={handleResult} />
-    ) : null
-  }
-/>
+dock={{
+  title: 'Assistant',
+  mode: 'popover' | 'side',                   // default 'popover'; 'side' = full-height edge panel
+  side: 'left' | 'right',                     // default 'right' (only for mode='side')
+  width: 480, height: 720,
+  position: 'bottom-right',                   // popover mode only
+  offset: { horizontal: 24, vertical: 96 },
+  mobileFullscreen: true,                     // default — fills viewport < 768px
+  reserveBodySpace: true,                     // side mode — sets body padding so content shifts
+  disablePortal: true,                        // render in-place (stories/iframes)
+  hideHeader: true,                           // children render their own header
+  headerActions: <ChatHeaderResetButton ... />,
+}}
 ```
 
-The composer reappears automatically once `hideComposer` returns `false`.
-
-### ToolCalls — expand behavior
+**Side mode is desktop-only.** Below `lg` (1024px) it silently falls back to popover and the `<ChatHeaderModeToggle>` hides itself.
 
-Panels are **collapsed by default**. While a tool is `running`, the panel auto-expands so you can see live `streamingText`; on completion it auto-collapses again. Manual user toggles (open or close) are remembered and override the auto-behavior for that call.
+**Persisted prefs.** `useChatDockPrefs()` stores `mode` / `side` / `sideWidth` in localStorage. Drop it into your launcher to give users a remembered layout:
 
 ```tsx
-<ToolCalls
-  calls={message.toolCalls}
-  // Defaults:
-  defaultExpanded={false}        // start closed
-  expandWhileStreaming={true}    // open during run, close on completion
-/>
+const prefs = useChatDockPrefs({ storageKey: 'crm.chat.dock' });
+<ChatLauncher
+  dock={{
+    mode: prefs.mode,
+    side: prefs.side,
+    width: prefs.mode === 'side' ? prefs.sideWidth : 480,
+    headerActions: <ChatHeaderModeToggle mode={prefs.mode} onToggle={prefs.toggleMode} />,
+  }}
+>{children}</ChatLauncher>
 ```
 
-Force every panel open from the start (e.g. for debug views) with `defaultExpanded`.
-
-### ToolCalls payload renderers
-
-`<ToolCalls>` (and `<MessageBubble toolCallsProps>` / `<ChatRoot toolCallsProps>`) accept payload renderers so you control how tool input / output / streaming text is displayed. Defaults render a cheap `<pre>`. For a richer experience, plug in `LazyJsonTree` from `@djangocfg/ui-tools/json-tree` with `mode="compact"`:
+### Greeting
 
 ```tsx
-import { LazyJsonTree } from '@djangocfg/ui-tools/json-tree';
+// Short
+greeting="Got a minute? I'm here to help."
 
-<ToolCalls
-  calls={message.toolCalls}
-  renderInput={(input) => <LazyJsonTree data={input} mode="compact" />}
-  renderOutput={(output) => <LazyJsonTree data={output} mode="compact" />}
-/>
+// Full config
+greeting={{
+  content: <>Looking for something? <strong>Chat with us</strong>.</>,
+  senderName: 'Anna · Support',
+  avatar: <Avatar><AvatarImage src="…" /></Avatar>,
+  delayMs: 1500,
+  dismissStorageKey: 'crm-greeting-v1',
+  hideOnOpen: true,
+}}
 ```
 
-`renderInput` / `renderOutput` / `renderStreaming` take precedence; `renderPayload(value, kind, call)` is a single fallback if you want one renderer for all three.
-
-We don't import `LazyJsonTree` automatically — keeping the chat dep-light. The host opts in.
-
-### ToolCalls — rich UI after panels (`renderAfterCalls`)
-
-`renderAfterCalls` renders **outside and below** all collapsible panels — always visible, regardless of whether panels are expanded or hidden. It receives the full `calls` array so you can aggregate across multiple tool calls (e.g. collect all vehicle IDs from `search_vehicles` + `get_vehicle` and render cards).
+### Hotkey
 
 ```tsx
-<ChatRoot
-  toolCallsProps={{
-    // Rich UI below all panels — always visible, never inside collapsed accordions
-    renderAfterCalls: (calls) => <VehicleCardList calls={calls} />,
-  }}
-/>
+hotkey={{ key: '/', meta: true }}           // ⌘/ or Ctrl+/
+hotkey={{ key: 'K', meta: true, shift: true }}
 ```
 
-#### hideToolCalls — show only rich UI, no raw panels
+When `meta` is unset, modifier-bearing combos do **not** trigger — prevents shadowing native shortcuts.
 
-Set `hideToolCalls={true}` to suppress accordion panels entirely while `renderAfterCalls` still renders. Use when you want clean product UI without raw tool payloads visible.
+### Controlled mode
 
 ```tsx
-<ChatRoot
-  toolCallsProps={{
-    hideToolCalls: true,                             // hides accordion panels
-    renderAfterCalls: (calls) => <VehicleCards calls={calls} />,  // still runs
-  }}
-/>
-```
+const [open, setOpen] = useState(false);
 
-`hideToolCalls` only affects the accordion panels — `renderAfterCalls` is always independent.
+<ChatLauncher open={open} onOpenChange={setOpen} dock={{ title: 'Helper' }}>
+  <Chat />
+</ChatLauncher>
+```
 
-#### renderToolCall — custom per-call panel renderer
+### Live push notifications
 
-Replace the default `<ToolCallItem>` accordion with your own UI. Return `null` to suppress a specific call.
+Inbound messages from outside the chat session (admin takeover, server-pushed alerts, Centrifugo broadcasts) flow through the same reducer as normal turns:
 
 ```tsx
-<ChatRoot
-  toolCallsProps={{
-    renderToolCall: (call) => (
-      <div className="flex items-center gap-2 rounded border px-2 py-1 text-xs">
-        <span className="font-mono">{call.name}</span>
-        <span className="ml-auto">{call.status}</span>
-      </div>
-    ),
-  }}
-/>
+// Inside ChatProvider — anywhere
+const chat = useChatContext();
+
+centrifugo.on('chat:inbound', (msg) => {
+  chat.injectMessage({
+    id: msg.id,
+    role: 'assistant',
+    content: msg.text,
+    createdAt: Date.now(),
+    sender: { name: msg.from, avatarUrl: msg.avatar },
+  });
+});
+
+chat.updateMessage(id, { content: editedText });   // live-edit by admin
+chat.deleteMessage(id);                            // retract
 ```
 
-#### Full example — vehicle cards from tool output
+Surface them next to the FAB while the dock is closed:
 
 ```tsx
-import { buildVamcarToolCallsProps } from './chat/toolPayloads';
-
-// toolPayloads.tsx:
-export function buildVamcarToolCallsProps(): Omit<ToolCallsProps, 'calls'> {
-  return {
-    renderAfterCalls: (calls) => <VehicleCardsFromCalls calls={calls} />,
-  };
+function Launcher() {
+  const [open, setOpen] = useState(false);
+  const { unread, markRead } = useChatUnread({ open });  // inside ChatProvider
+  return (
+    <ChatLauncher
+      open={open}
+      onOpenChange={setOpen}
+      unreadMessage={unread}
+      onMarkRead={markRead}
+      // FAB badge "1" derived automatically; override via `fab.badge`
+    >…</ChatLauncher>
+  );
 }
-
-// In your chat component:
-const toolCallsProps = useMemo(() => buildVamcarToolCallsProps(), []);
-<ChatRoot transport={transport} toolCallsProps={toolCallsProps} />
 ```
 
-## Personas (user & assistant identity)
+`<ChatUnreadPreview>` (auto-rendered by `ChatLauncher` when `unreadMessage` is set) shows avatar + sender + 2-line truncated body + timestamp. Click → open + mark read. × → mark read without opening.
 
-Pass identities once on `<ChatRoot config>` — every bubble gets the right name, avatar and `aria-label`. Outgoing user messages get the `sender` field auto-stamped from `config.user`.
+### Audio
 
-```tsx
-<ChatRoot
-  transport={transport}
-  config={{
-    user: {
-      name: 'Mark',
-      avatarUrl: '/me.jpg',
-      description: 'Senior engineer',
-    },
-    assistant: {
-      name: 'Claude',
-      avatarUrl: '/claude.png',
-      model: 'claude-opus-4-7',
-    },
-  }}
-/>
-```
+Wire `useChatAudio` once and pass it to `ChatLauncher` — the header gets an auto-injected mute toggle:
 
-Resolution cascade per bubble:
+```tsx
+// Zero-setup — built-in sounds are bundled as base64 data URLs
+const audio = useChatAudio();
 
-1. `message.sender` — per-message override (multi-user / multi-bot chats)
-2. `config.user` / `config.assistant` — provider-level default
-3. Hardcoded `'You'` / `'AI'` fallback
+<ChatLauncher audio={audio} dock={{ title: 'Helper' }}>
+  <ChatRoot transport={transport} />
+</ChatLauncher>
+```
 
-Multi-user example — server returns `sender` per message:
+**Built-in sounds.** The chat tool ships its own notification pack (`messageSent`, `messageReceived`, `streamStart`, `error`, `mention`, `notification`) inlined into the lazy chunk via tsup's `dataurl` loader. ~136KB total, ~180KB after base64 — paid only by hosts that actually import Chat. No assets to copy, no CDN to host.
 
-```ts
-{
-  id: 'm3',
-  role: 'user',
-  content: 'Flag the auth migration section.',
-  sender: { name: 'Anna', avatarUrl: '/anna.jpg' },
-}
-```
+Customize:
 
-Initials are auto-derived from `name` (`'Mark Olofsen'` → `MO`); set `initials` explicitly to override.
+```tsx
+import { useChatAudio, DEFAULT_CHAT_SOUNDS } from '@djangocfg/ui-tools';
 
-Helpers exposed for hosts that build their own bubbles:
+// Override one event, keep the rest
+useChatAudio({ sounds: { ...DEFAULT_CHAT_SOUNDS, mention: '/sfx/custom.mp3' } });
 
-```ts
-import { resolvePersona, deriveInitials } from '@djangocfg/ui-tools';
-const persona = resolvePersona(message, config.user, config.assistant);
-const fallback = deriveInitials(persona, message.role);
+// Disable entirely (header toggle hides itself)
+useChatAudio({ sounds: {} });
 ```
 
-## Attachments
+Per-event volume defaults — Slack / Linear / Intercom style:
 
-Two specialised components plus a backwards-compatible facade:
+| Event | Scale | Why |
+|---|---|---|
+| `error` | 0.25 | The destructive UI is the loud signal; sound is a soft ack |
+| `streamStart` | 0.3 | Fires often, must stay subtle |
+| `messageSent` | 0.5 | Self-confirmation |
+| `messageReceived` | 0.7 | Baseline |
+| `notification` | 0.9 | Push to a background tab — needs to be heard |
+| `mention` | 1.0 | Louder than baseline — personal |
 
-| Component           | Layout         | Use it for                                   |
-| ------------------- | -------------- | -------------------------------------------- |
-| `<AttachmentsGrid>` | `flex-wrap`    | Thumbnails, file chips, no custom renderers  |
-| `<AttachmentsList>` | `flex-col`     | Custom renderers (audio, video, doc viewer)  |
-| `<Attachments>`     | picks for you  | Backwards-compat: stacks when `renderers` is given, wraps otherwise |
+Override via `eventVolumes: { error: 0, mention: 0.8 }`. Pass `eventVolumes: {}` to skip defaults entirely.
 
-`<MessageBubble>` automatically uses `AttachmentsList` when you pass `attachmentRenderers` and `AttachmentsGrid` otherwise — `flex-wrap` shrinks block-level renderers to min-content, so picking the right component matters.
+`audio.muted` / `audio.toggleMute()` are persisted in localStorage. Header `<ChatHeaderAudioToggle>` is hidden automatically when `audio.isSilent` (no sounds wired).
 
-```tsx
-import { AttachmentsList } from '@djangocfg/ui-tools';
+**Native hosts (cmdop_go / Tauri / Electron).** Skip web playback but keep the trigger as a side-channel:
 
-<AttachmentsList
-  attachments={msg.attachments}
-  renderers={{
-    audio: ({ attachment }) => <LazyAudioPlayer src={attachment.url} variant="compact" />,
-  }}
-/>
+```tsx
+const audio = useChatAudio({
+  silenced: true,
+  onSoundEvent: (e) => window.go.playSound(e),
+});
 ```
 
-## Audio triggers
-
-Optional sound effects on chat events. Off by default — you opt in with a `sounds` map. Six events:
+See [`@djangocfg/ui-core` Audio docs](../../../../ui-core/README.md#audio) for the underlying `useNotificationSounds` primitives.
 
-| Event              | Fires when                                          |
-| ------------------ | --------------------------------------------------- |
-| `messageSent`      | After `useChat.sendMessage()` adds the user message |
-| `messageReceived`  | On `STREAM_DONE` (final assistant message)          |
-| `streamStart`      | First token / placeholder created                   |
-| `error`            | `STREAM_ERROR` or transport throw                   |
-| `mention`          | Host-fired (e.g. assistant addressed the user)      |
-| `notification`     | Generic — host triggers manually                    |
+### Reset / clear conversation
 
 ```tsx
-<ChatRoot
-  transport={transport}
-  audio={{
-    sounds: {
-      messageSent:     '/audio/chat/sent.mp3',
-      messageReceived: '/audio/chat/received.mp3',
-      streamStart:     '/audio/chat/start.mp3',
-      error:           '/audio/chat/error.mp3',
-    },
-    // Defaults: muteWhenHidden: true, respectReducedMotion: true, respectReducedData: true
-  }}
+<ChatHeaderResetButton
+  onReset={api.clearChat}            // your backend POST /chat/reset
+  onSuccess={() => chat.clearMessages()}
+  confirmMessage="Forget this conversation? The assistant won't remember it."
 />
 ```
 
-Pitfalls handled inside (lifted from `AudioPlayer/audio`):
-
-- **iOS/Safari autoplay block.** First `pointerdown` / `keydown` inside `<ChatProvider>` runs a transactional unlock — every cached `<audio>` is poked once with `muted=true`, then released.
-- **Same-element race.** Each `play()` clones a fresh `Audio(url)` so two rapid events don't cancel each other; the cached element warms the HTTP cache.
-- **Cross-tab sync.** Volume / mute / per-event toggles live in a Zustand `persist` store with `localStorage` + the native `storage` event.
-- **Visibility.** Auto-mute while `document.visibilityState === 'hidden'`.
-- **Reduced motion / data.** Auto-suppress on `prefers-reduced-motion: reduce` and `prefers-reduced-data: reduce` (configurable).
-- **SSR-safe.** `audioBus` falls back to a no-op when `window` is undefined.
+Calls `window.dialog.confirm` (destructive variant) from `@djangocfg/ui-core/lib/dialog-service`. Host must mount `<DialogProvider>`. Falls back to native `window.confirm` if the dialog service isn't installed.
 
-For programmatic control (e.g. mute toggle in your header):
+### Anti-patterns
 
-```tsx
-const ctx = useChatContext();
-ctx.audio.setMuted(!ctx.audio.muted);
-ctx.audio.setVolume(0.6);
-ctx.audio.setEventEnabled('messageSent', false);
-ctx.audio.play('mention');         // host-fired
-ctx.audio.isUnlocked;              // boolean
-```
+| Don't | Why |
+|---|---|
+| Two `<ChatLauncher>` on one page | Hotkey opens both at once |
+| `hotkey={{ key: '/' }}` (no modifier) | Fires when user types `/` in any input |
+| Mismatched `exitDurationMs` vs CSS | Dock unmounts before/after animation |
+| Reusing `dismissStorageKey` across products | Greeting won't show on the second product |
+| Calling `useChatUnread()` outside `ChatProvider` | Hook reads the messages store; throws without provider |
+| Forgetting `<DialogProvider>` for `<ChatHeaderResetButton confirm>` | Falls back to native browser confirm (ugly) |
 
-Or directly: `useChatAudio(config)` — returns the same surface, no provider required.
+## Styling — role-aware tokens
 
-## Composer focus & auto-focus on stream end
+Every chat surface that depends on role/error state uses the centralized tokens, not inline Tailwind literals. Change `bg-primary`/contrast in one file — fixes every consumer.
 
-The chat context exposes a small composer registry so other parts of
-the tree can drive the composer imperatively without prop-drilling a
-ref. The built-in `<Composer>` registers itself on mount; custom
-composers opt in with a one-line hook.
+```ts
+import { BUBBLE_SURFACE, ANCHOR, TOGGLE, DESTRUCTIVE_SURFACE } from '@djangocfg/ui-tools';
 
-```tsx
-import { useChatContext, useRegisterComposer } from '@djangocfg/ui-tools';
+// Token shape
+BUBBLE_SURFACE.user        // 'bg-primary text-primary-foreground rounded-tr-md'
+BUBBLE_SURFACE.assistant   // 'bg-muted text-foreground rounded-tl-md'
+BUBBLE_SURFACE.error       // 'bg-destructive/10 text-destructive rounded-tl-md border border-destructive/30'
 
-// Inside any custom composer:
-function MyComposer() {
-  const focus = useCallback(() => myEditorRef.current?.commands.focus(), []);
-  useRegisterComposer(focus);
-  // ...
-}
+ANCHOR.user                // legible on bg-primary (uses primary-foreground, not white)
+ANCHOR.assistant           // brand-primary on neutral bubble
 
-// Then anywhere inside <ChatProvider>:
-const ctx = useChatContext();
-ctx.composer?.focus();   // null until any composer has mounted
+DESTRUCTIVE_SURFACE.banner / .hover / .hoverStrong / .text / .menuItem
 ```
 
-### `useAutoFocusOnStreamEnd` — refocus when the reply lands
-
-Standard chat UX: user types → sends → reads the reply → starts
-typing again without reaching for the mouse. The hook listens for the
-streaming → idle transition and calls `.focus()` exactly once. Reading
-mid-stream is undisturbed.
-
-Zero-config (default: focuses the registered composer):
+Prefer hooks in components — they memoize and present a stable facade:
 
 ```tsx
-import { useAutoFocusOnStreamEnd } from '@djangocfg/ui-tools';
+import { useChatBubbleStyles, useChatRoleStyles, useChatDestructiveStyles } from '@djangocfg/ui-tools';
 
-function MyChatShell() {
-  useAutoFocusOnStreamEnd();      // reads isStreaming + composer from context
-  return <ChatProvider>{/* … */}</ChatProvider>;
+function MyBubble({ message }) {
+  const { surface, anchor } = useChatBubbleStyles(message.role, !!message.isError);
+  return <div className={cn('rounded-2xl px-3 py-2', surface)}>…</div>;
 }
-```
-
-Options:
-
-| option        | default                | when to set                                                                 |
-|---------------|------------------------|-----------------------------------------------------------------------------|
-| `isStreaming` | `ctx.isStreaming`      | Driving stream state from your own store (e.g. an external event bus).      |
-| `targetRef`   | registered composer    | Focus something other than the composer — an "approve" button, etc.         |
-| `enabled`     | `true`                 | User preference toggle (off without unmounting the hook).                   |
-| `delayMs`     | `0` (next rAF)         | 50–150ms helps when the composer re-mounts after the final chunk.           |
-
-The hook only fires on the `true → false` edge — flipping `enabled`
-mid-stream won't steal focus.
 
-## Draft sanitation (pre-submit)
-
-`useChatComposer.submit()` cleans the draft before handing it to your
-`onSubmit` — mirroring what ChatGPT / Claude / Telegram ship. The
-helper is also exported standalone for custom composers:
-
-```ts
-import { sanitizeDraft, isSubmittableDraft } from '@djangocfg/ui-tools'
+function MyToggle({ isUser }) {
+  const { toggle } = useChatRoleStyles(isUser);
+  return <button className={toggle}>Read more</button>;
+}
 
-sanitizeDraft('  \n\nhello   world​\n  ')   // → 'hello   world'
-isSubmittableDraft('   \n  ')                     // → false
+function MyError() {
+  const { banner, hover } = useChatDestructiveStyles();
+  return <div className={banner}>…<button className={hover}>Dismiss</button></div>;
+}
 ```
 
-### Rules (intentionally minimal)
-
-| Rule | Action | Why |
-|---|---|---|
-| Trim outer whitespace | ✅ | Stray newlines/spaces at the edges are never intentional. |
-| Normalise `\r\n` / `\r` → `\n` | ✅ | Deterministic shape for LLM tokeniser + markdown render. |
-| Strip ZWSP / ZWNJ / ZWJ / BOM | ✅ | Pasted from rich web pages, invisible, break tokenisation. |
-| **Collapse internal whitespace runs** | ❌ | Would mangle code indentation. |
-| **Cap consecutive blank lines** | ❌ | Could be intentional separator (markdown / structured prompt). |
-| **Strip bidi overrides** (LRM/RLM/U+202A..E) | ❌ | Legitimately used in Arabic/Hebrew RTL content. |
-| Touch tabs vs spaces, emoji, mentions, URLs | ❌ | Passthrough. |
-
-Idempotent: `sanitizeDraft(sanitizeDraft(x)) === sanitizeDraft(x)`.
-
-### Escape hatch — `preserveExactValue`
+## Transport contract
 
-Niche flows (clipboard inspector, raw-prompt debug tool) want
-byte-perfect passthrough. Opt out per-composer:
+A single I/O seam.
 
 ```ts
-const composer = useChatComposer({
-  onSubmit,
-  preserveExactValue: true,   // skip sanitation; raw textarea value goes through
-})
+interface ChatTransport {
+  createSession(opts?): Promise<SessionInfo>;
+  loadHistory(sessionId, cursor?, limit?): Promise<HistoryPage>;
+  stream(sessionId, content, { signal, attachments, metadata }): AsyncGenerator<ChatStreamEvent>;
+  send(sessionId, content, options?): Promise<ChatMessage>;
+  closeSession(sessionId): Promise<void>;
+}
 ```
 
-`canSubmit` still gates on `value.trim().length > 0` in this mode —
-an empty message is rarely intentional even when sanitation is off.
-
-## Attachment renderers (registry)
+Shipped implementations:
 
-`<Attachments>` and `<ChatRoot>` accept a per-type renderer map. Default tile is used when no renderer matches. Plug in heavy viewers (`LazyAudioPlayer`, `LazyImageViewer`, `LazyMap`) host-side without forcing `ui-tools/Chat` to depend on them.
+- **`createPydanticAIChatTransport({ buildStreamUrl, buildHeaders, bootstrapSession, loadHistory, ... })`** — for Django/pydantic-AI–style backends. Composes `parseSSE` + `mapPydanticAIEvent` + tool-id FIFO queue. Side-channel via `onPydanticEvent` for non-stream events (e.g. `approval_required`).
+- **`createHttpTransport({ baseUrl, getAuthHeader, slug })`** — fetch + SSE for the canonical `POST /sessions/:id/messages` shape.
+- **`createMockTransport({ replies, latencyMs })`** — scripted in-memory replies for stories/tests.
 
-```tsx
-import { LazyPlayer as LazyAudioPlayer } from '@djangocfg/ui-tools/audio-player';
-
-<ChatRoot
-  transport={transport}
-  attachmentRenderers={{
-    audio: ({ attachment }) => (
-      <div className="my-1 max-w-md">
-        <LazyAudioPlayer src={attachment.url} title={attachment.name} variant="compact" />
-      </div>
-    ),
-    // image / video / file / default — all optional
-  }}
-  onAttachmentOpen={(att) => openLightbox(att)}
-/>
-```
+Build a custom transport directly when none of the above fit.
 
-Renderer signature:
+### Pydantic-AI shortcuts
 
 ```ts
-type AttachmentRenderer = (args: {
-  attachment: ChatAttachment;
-  isInComposer: boolean;     // true in the composer staging tray
-  onClick?: () => void;      // forwarded from <ChatRoot onAttachmentOpen>
-  onRemove?: () => void;     // present in the composer tray
-}) => ReactNode;
-```
-
-`<MessageBubble attachmentsRenderer>` (a wholesale slot) still wins over the registry — use it when you need to swap the entire attachments block.
-
-## Image lightbox helpers
-
-```tsx
 import {
-  useChatLightbox,
-  collectImageAttachments,
+  createPydanticAIChatTransport,
+  createPydanticAISSEMap,
+  mapPydanticAIEvent,
+  createToolIdQueue,
 } from '@djangocfg/ui-tools';
-import { LazyImageViewer } from '@djangocfg/ui-tools/image-viewer';
-
-function MyChat() {
-  const lightbox = useChatLightbox();
-  const ctx = useChatContext();
-  const gallery = useMemo(() => collectImageAttachments(ctx.messages), [ctx.messages]);
 
-  return (
-    <>
-      <ChatRoot
-        transport={transport}
-        onAttachmentOpen={(att) => att.type === 'image' && lightbox.open(att, gallery)}
-      />
-      <Dialog open={!!lightbox.state} onOpenChange={(o) => !o && lightbox.close()}>
-        <DialogContent className="max-w-5xl">
-          {lightbox.state && (
-            <LazyImageViewer
-              images={lightbox.state.gallery.map((a) => ({
-                file: { name: a.name ?? a.id, path: a.id },
-                src: a.url,
-              }))}
-              initialIndex={lightbox.state.index}
-              inDialog
-            />
-          )}
-        </DialogContent>
-      </Dialog>
-    </>
-  );
+// In a custom transport / hand-rolled stream loop:
+const toolIds = createToolIdQueue();
+for await (const event of parseSSE(res, { map: createPydanticAISSEMap() })) {
+  yield event;
 }
 ```
 
-`useChatLightbox` is just a tiny `{ gallery, index } | null` state container — the host owns the modal + viewer mount, so `<LazyImageViewer>` (~50 KB) stays out of `ui-tools/Chat`.
-
-## Tool-payload dispatcher
-
-For tool-call panels, `dispatchToolPayload(matchers, fallback)` lets you pick a renderer per payload shape — without writing your own switch each time.
+## Slots
 
-```tsx
-import {
-  dispatchToolPayload,
-  isLatLng,
-  isPlainObject,
-  isGeoJSONFeatureCollection,
-} from '@djangocfg/ui-tools';
-import { LazyJsonTree } from '@djangocfg/ui-tools/json-tree';
-import { LazyMap } from '@djangocfg/ui-tools';
-
-const renderPayload = dispatchToolPayload(
-  [
-    {
-      match: (v) => isGeoJSONFeatureCollection(v),
-      render: (v) => <LazyMap geojson={v as GeoJSON.FeatureCollection} />,
-    },
-    { match: (v) => isLatLng(v), render: (v) => <LazyMap markers={[v as { lat: number; lng: number }]} /> },
-    { match: (v) => isPlainObject(v), render: (v) => <LazyJsonTree data={v} mode="compact" /> },
-  ],
-  (v) => <pre className="text-[11px]">{String(v)}</pre>,
-);
-
-<ChatRoot toolCallsProps={{ defaultExpanded: true, renderPayload }} />;
-```
+`<ChatRoot>` exposes named-prop slots — `header`, `footer`, `banner`, `empty`, `composerToolbarStart/End`, `composerAttachmentTray`, `jumpToLatest`. None are required.
 
-First match wins. Predicates `isLatLng` / `isPlainObject` / `isGeoJSONFeatureCollection` / `isStringValue` are exported as building blocks.
+See **[Slots inventory](#slots-inventory)** below for the full list, plus `hideComposer` / `hideToolCalls` / `renderToolCall` / `renderAfterCalls` patterns.
 
 ## Three usage patterns
 
@@ -562,8 +413,6 @@ First match wins. Predicates `isLatLng` / `isPlainObject` / `isGeoJSONFeatureCol
 
 ### 2. Composition
 
-Bring your own layout, reuse the parts.
-
 ```tsx
 <ChatProvider transport={transport}>
   <MyHeader />
@@ -572,170 +421,138 @@ Bring your own layout, reuse the parts.
 </ChatProvider>
 ```
 
-### 3. Headless (just hooks)
+### 3. Headless
 
 ```tsx
 const chat = useChat({ transport });
 const composer = useChatComposer({ onSubmit: chat.sendMessage });
-// render however you want
-```
-
-## Transport contract
-
-A single I/O seam.
-
-```ts
-interface ChatTransport {
-  createSession(opts?): Promise<SessionInfo>;
-  loadHistory(sessionId, cursor?, limit?): Promise<HistoryPage>;
-  stream(sessionId, content, { signal, attachments, metadata }): AsyncGenerator<ChatStreamEvent>;
-  send(sessionId, content, options?): Promise<ChatMessage>;
-  closeSession(sessionId): Promise<void>;
-}
 ```
 
-Shipped implementations:
+## Mobile & a11y
 
-- **`createHttpTransport({ baseUrl, getAuthHeader, slug })`** — fetch + SSE, default for web.
-- **`createMockTransport({ replies, latencyMs })`** — scripted in-memory replies for stories/tests.
-
-Custom hosts (Wails RPC, WebSocket, gRPC) implement the same interface — see [`@dev/@refactoring7-chat/06-integration.md`](../../../@dev/@refactoring7-chat/06-integration.md) for adapter recipes.
+- `useChatLayout` collapses `sidebar`/`floating` to `fullscreen` below `(max-width: 640px)`.
+- `ChatDock` fills the viewport below 768px (`mobileFullscreen` prop, default `true`).
+- Composer textarea is `font-size: 16px` to disable iOS focus-zoom; container uses `100dvh` and `env(safe-area-inset-bottom)`.
+- `MessageList` is `role="log"` with `aria-live="polite"`; streaming bubbles set `aria-busy`.
+- `ErrorBanner` is `role="alert"`.
+- `JumpToLatest` announces unread count via `aria-live="polite"`.
+- All visible Boundary fallbacks and the Greeting bubble carry `role="alert"` / `aria-live`.
 
 ## Public surface
 
 ```ts
-// Types
+// Types (re-exported from types/)
 ChatMessage, ChatRole, ChatPersona, ChatToolCall, ChatAttachment, ChatSource,
-ChatConfig, ChatUserContext, ChatAssistantContext, ChatPrefs, ChatLabels,
+ChatConfig, ChatUserContext, ChatAssistantContext, ChatPrefs, ChatLabels, DEFAULT_LABELS,
 ChatTransport, ChatStreamEvent, ChatDisplayMode,
-SessionInfo, HistoryPage, StreamOptions, SendOptions
+SessionInfo, HistoryPage, StreamOptions, SendOptions, CreateSessionOptions
 
-// Core (pure)
+// Core
 reducer, initialState, createId, createTokenBuffer,
 resolvePersona, deriveInitials
-type ChatState, type ChatAction
+type ChatState, type ChatAction, type TokenBuffer
 
 // Transport
-createHttpTransport, createMockTransport, parseSSE, TransportError
+createHttpTransport, createMockTransport, createPydanticAIChatTransport,
+mapPydanticAIEvent, createPydanticAISSEMap, createToolIdQueue,
+parseSSE, TransportError
+type HttpTransportConfig, type MockTransportOptions, type ParseSSEOptions,
+type PydanticAIChatTransportOpts, type PydanticAIEvent, type ToolIdQueue
 
 // Hooks
 useChat, useChatComposer, useChatScroll, useChatHistory, useChatLayout,
-useChatAudio, useChatLightbox,
-useAutoFocusOnStreamEnd, useRegisterComposer,
-type UseAutoFocusOnStreamEndOptions, type Focusable
+useChatAudio, useChatLightbox, useAutoFocusOnStreamEnd, useRegisterComposer,
+useChatReset, useVisitorFingerprint, useChatDockPrefs, useChatUnread,
+useFocusOnEmptyClick
+type ChatDockPrefs, DEFAULT_DOCK_PREFS
+
+// Styles — role-aware tokens + hooks
+BUBBLE_SURFACE, ANCHOR, TOGGLE, DESTRUCTIVE_SURFACE, TOOL_CALL,
+useChatBubbleStyles, useChatRoleStyles, useChatDestructiveStyles
+type ChatBubbleSurface, type ChatBubbleStyles, type ChatRoleStyles, type ChatDestructiveStyles
+
+// Launcher
+ChatFAB, ChatDock, ChatHeader, ChatHeaderActionButton, ChatHeaderModeToggle,
+ChatHeaderAudioToggle, ChatHeaderResetButton, ChatHeaderLanguageButton,
+ChatLauncher, ChatGreeting, ChatUnreadPreview, useChatPresence
+type ChatFABProps, type ChatFABVariant, type ChatFABSize, type ChatFABPosition,
+type ChatDockProps, type ChatDockMode, type ChatDockSide,
+type ChatHeaderProps, type ChatHeaderActionButtonProps, type ChatHeaderModeToggleProps,
+type ChatHeaderAudioToggleProps, type ChatHeaderResetButtonProps,
+type ChatHeaderLanguageButtonProps,
+type ChatGreetingProps, type ChatUnreadPreviewProps,
+type ChatLauncherProps, type ChatLauncherHotkey, type ChatLauncherGreeting,
+type ChatPresencePhase
 
 // Audio
 ChatAudioConfig, ChatAudioEvent, ChatAudioSounds, UseChatAudioReturn,
-useChatAudioPrefs
+useChatAudioPrefs, DEFAULT_CHAT_SOUNDS
 
 // Tool-payload dispatch
 dispatchToolPayload, isPlainObject, isLatLng,
 isGeoJSONFeatureCollection, isStringValue,
-type ToolPayloadMatcher, type ToolPayloadFallback,
-type ToolPayloadKind, type ToolCallsProps
+type ToolPayloadMatcher, type ToolPayloadFallback, type ToolPayloadKind, type ToolCallsProps
 
-// Lightbox helpers
-collectImageAttachments
-
-// Draft sanitation (pre-submit cleanup; see "Draft sanitation" above)
+// Draft sanitation
 sanitizeDraft, isSubmittableDraft
 
 // Context
-ChatProvider, useChatContext, useChatContextOptional,
-type ComposerHandle
+ChatProvider, useChatContext, useChatContextOptional, type ComposerHandle
+// `ComposerHandle` shape: { focus, moveCursorToEnd?, getValue?, setValue? }.
+// Voice slot, autoFocus hook, and any external driver read it from
+// context — built-in Composer registers itself, custom composers use
+// `useRegisterComposer({...})`.
 
 // Components
 ChatRoot, MessageList, MessageBubble, MessageActions, Composer,
 Sources, ToolCalls, Attachments, EmptyState, ErrorBanner,
 JumpToLatest, StreamingIndicator
+// `MessageList` exposes `atBottomThreshold` (default 120 px) and
+// `scrollAnchorId` props for ChatGPT-style autoscroll — see "What you get".
 
 // Lazy preset
 LazyChat
 ```
 
-## Mobile & a11y notes
-
-- `useChatLayout` collapses `sidebar`/`floating` to `fullscreen` below `(max-width: 640px)`.
-- Composer textarea is `font-size: 16px` to disable iOS focus-zoom; container uses `100dvh` and `env(safe-area-inset-bottom)`.
-- `MessageList` is `role="log"` with `aria-live="polite"`; streaming bubbles set `aria-busy`.
-- `ErrorBanner` is `role="alert"`.
-- `JumpToLatest` announces unread count via `aria-live="polite"`.
-
-## Hotkeys
-
-| Key                | Behavior                                |
-| ------------------ | --------------------------------------- |
-| `Enter`            | Send (configurable to `Cmd/Ctrl+Enter`) |
-| `Shift+Enter`      | Newline                                 |
-| `↑` (empty input)  | Recall previous submission              |
-| `↓`                | Recall next                             |
-| `Esc`              | (host-bound) cancel stream              |
-
-> **Custom composers built on `MarkdownEditor`:** pass `onSubmit` to
-> the editor for the same behaviour. A React `onKeyDown` wrapper does
-> NOT reliably intercept Enter before Tiptap commits the HardBreak
-> — see `MarkdownEditor/README.md#submit-on-enter` for the full
-> incident write-up and the keymap-extension fix.
-
-## Performance
+## Storybook
 
-- **Token coalescing.** `createTokenBuffer` aggregates stream chunks within ~16ms before dispatching → ≤1 render per frame.
-- **Plain text during stream.** `MessageBubble` skips ReactMarkdown until the message finishes, then re-renders once with full markdown.
-- **Memoized bubbles.** Memo key `(id, content, isStreaming, version, toolActivity, toolCalls, sources, attachments)` — references only.
-- **Virtualization is on by default.** As of plan64, `<MessageList>` is built on [`react-virtuoso`](https://virtuoso.dev/). Sticky-bottom + auto-follow on streaming come from `followOutput`, top-of-list pagination from `startReached`, scroll-anchor preservation on prepend from `firstItemIndex`. No host-side virtualizer needed. Set `noVirtualize` on `<MessageList>` to opt out (stories / DevTools tracing).
+Stories live next to components — open `@djangocfg/playground`:
 
-### Scroll API
+- `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.
 
-`<MessageList>` exposes an imperative handle:
+---
 
-```tsx
-const listRef = useRef<MessageListHandle>(null);
+<a id="slots-inventory"></a>
 
-<MessageList
-  ref={listRef}
-  onAtBottomChange={setIsAtBottom}     // drives "Jump to latest" pill
-  onStartReached={() => void loadMore()} // top-of-list pagination
-/>;
-
-listRef.current?.scrollToBottom(true);  // smooth jump
-listRef.current?.scrollToIndex(42);     // jump to a specific bubble
-```
+## Slots inventory
 
-The legacy `useChatScroll` hook is kept for hosts that render their
-own (non-virtualized) scroll container, but is `@deprecated` for use
-with `<MessageList>` — the component owns sticky-bottom internally.
-
-## Design docs
+| Slot | Position | Render-prop variant |
+|---|---|---|
+| `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` (rich UI like vehicle cards) |
 
-Full implementation plan and rationale lives at [`@dev/@refactoring7-chat/`](../../../@dev/@refactoring7-chat/):
+Flags:
 
-- `00-overview.md` — file layout & public API
-- `01-architecture.md` — layered model, dataflow, transport contract
-- `02-state-model.md` — reducer actions and invariants
-- `03-hooks.md` — every hook signature
-- `04-components.md` — every component prop shape
-- `05-mobile-and-a11y.md` — breakpoints, iOS, ARIA, focus, RTL
-- `06-integration.md` — adapter recipes
-- `07-testing.md` — reducer / hook / component / a11y tests
-- `08-migration.md` — step-by-step rollout
+- `hideComposer` — agent-pause / human-in-the-loop pause; composer is unmounted.
+- `hideToolCalls` — show only `renderAfterCalls` rich UI without raw tool panels.
 
-## Storybook
+## Hotkeys
 
-`Tools/Chat` covers:
-
-- `Default` — full ChatRoot with mock transport and suggestions
-- `WithToolCalls` — scripted tool invocation + sources
-- `Composition` — bring your own layout (`<ChatProvider>` + parts)
-- `Bubbles` — visual matrix of message states
-- `Parts` — every decomposed component on its own (incl. `ToolCalls` + `LazyJsonTree` compact)
-- `WithSlots` — every named slot at once (banner / header / empty / composer toolbar / footer)
-- `WithJsonTreePayload` — `<ChatRoot toolCallsProps>` with `LazyJsonTree` payload renderers
-- `WithAudio` — chat-event sound triggers + unlock-state badge
-- `WithAudioAttachment` — attachment registry mounts `<LazyAudioPlayer>` for `audio` items
-- `WithImageLightbox` — `useChatLightbox` + host-side `<Dialog>` + `<LazyImageViewer>`
-- `WithMapPayload` — `dispatchToolPayload` with `LazyJsonTree` fallback
-- `WithPersonas` — config-level `user` + `assistant` identity (avatar, name)
-- `MultiUser` — per-message `sender` overrides (multi-user / multi-bot)
-- `WithHideComposer` — `hideComposer` + `footer` approval gate (HITL / agent-pause pattern)
-- `WithRenderAfterCalls` — `renderAfterCalls` (vehicle cards outside panels), `hideToolCalls`, `renderToolCall` (custom per-call renderer) — knob-controlled
-- `Playground` — knobs (latency, streaming, suggestions)
+- `Enter` — send (or `Cmd+Enter` if `prefs.submitOn = 'cmd+enter'`).
+- `Shift+Enter` — newline.
+- `Esc` — cancel current streaming turn (when focused inside the composer).
+- Launcher hotkey: configurable via `<ChatLauncher hotkey={…}>` (e.g. `⌘/`).