@djangocfg/ui-tools 2.1.393 → 2.1.395

package/README.md

@@ -111,7 +111,6 @@ import {
   ChatLauncher,
   ChatRoot,
   createPydanticAIChatTransport,
-  useChatAudio,
 } from '@djangocfg/ui-tools/chat';
 
 const transport = createPydanticAIChatTransport({
@@ -121,16 +120,25 @@ const transport = createPydanticAIChatTransport({
 });
 
 function Chat() {
-  const audio = useChatAudio();          // zero setup — uses built-in sounds bundled into the lazy chunk
+  // ChatLauncher mounts <ChatProvider> internally — pass transport / audio /
+  // config here, then render <ChatRoot /> as a child without props.
   return (
     <ChatLauncher
+      transport={transport}
+      audio={{}}                         // ChatAudioConfig (sounds map). `{}` uses bundled defaults.
       hotkey={{ key: '/', meta: true }}
       fab={{ variant: 'animated' }}     // size='responsive' default — phone/tablet/desktop
       dock={{ title: 'Assistant', height: 600 }}
       greeting="Hi 👋 Need help?"
-      audio={audio}                      // auto-injects mute toggle into header
+      headerSlots={{                     // declarative header buttons, rendered inside the provider
+        languagePicker: true,
+        modeToggle: { persistAs: 'my.chat.dock' },
+        reset: {
+          onReset: async () => { await api.clearChat(); return true; },
+        },
+      }}
     >
-      <ChatRoot transport={transport} />
+      <ChatRoot />
     </ChatLauncher>
   );
 }
@@ -138,7 +146,7 @@ function Chat() {
 
 **What's wired by default:** desktop side-mode toggle (auto-hides on narrow screens), persisted dock prefs, two-step Escape, click-to-focus composer, mobile fullscreen with `dvh` heights, push-preview bubble for inbound messages while closed, **ChatGPT-style autoscroll** (sticky-to-bottom within 120 px, every user-send re-anchors the viewport), **bundled chat notification sounds** (sent/received/start/error/mention/notification, ~136KB inlined as `data:`-URLs inside the lazy chat chunk — zero host setup). Native hosts (cmdop_go / Tauri) pass `audio={{ silenced: true, onSoundEvent }}` to keep web silent while routing triggers to the backend.
 
-Drop `<VoiceComposerSlot />` from `@djangocfg/ui-tools/speech-recognition` into `composerToolbarEnd` for live mic-to-text — **zero props**, reads / writes the composer through `ComposerHandle` registered in chat context. Drop `<ChatHeaderLanguageButton />` into `dock.headerActions` for a flag-button language picker (66 BCP-47 tags). Both auto-hide on Firefox / in-app browsers / missing `getUserMedia`. See [`SpeechRecognition`](#speech-recognition--quick-start) below.
+Drop `<VoiceComposerSlot />` from `@djangocfg/ui-tools/speech-recognition` into `composerToolbarEnd` for live mic-to-text — **zero props**, reads / writes the composer through `ComposerHandle` registered in chat context. Set `headerSlots={{ languagePicker: true }}` on `<ChatLauncher>` for a flag-button language picker (66 BCP-47 tags). Both auto-hide on Firefox / in-app browsers / missing `getUserMedia`. See [`SpeechRecognition`](#speech-recognition--quick-start) below.
 
 Full docs: [`Chat/README.md`](src/tools/Chat/README.md). Stories: `Tools/Chat/{Basic,Bubbles,ToolCalls,Personas,Launcher,Header,Audio & Actions,Voice composer}`.
 
@@ -182,7 +190,7 @@ import {
 />
 
 // Plus a flag-button language picker in the dock header:
-<ChatLauncher dock={{ headerActions: <ChatHeaderLanguageButton /> }}>
+<ChatLauncher headerSlots={{ languagePicker: true }} ... >
 ```
 
 **What's wired by default:** auto-hide on Firefox / in-app WebViews / missing `getUserMedia` (via `useVoiceSupport`); live interim+final stream into the composer via `ComposerHandle` (works transparently for the built-in textarea Composer and a TipTap MarkdownEditor); typed prefix anchored; focus + cursor-to-end on start and every partial; 90-second countdown + 2.5-second silence auto-stop; Esc cancels (without closing the chat) / Enter finishes (without submitting); persisted prefs (`djangocfg-stt:prefs`); `<SpeechRecognitionProvider>` for sharing engine state across the tree. Language picker shows 66 BCP-47 tags sourced from the Chrome Web Speech demo with country flags. Custom engines through `createHttpEngine` (REST/Whisper), `createWebSocketEngine` (Deepgram-style streaming), or `createExternalEngine` (Wails / Tauri / native sidecar — `onStart` / `onStop` / `subscribe` and you're done).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.393",
+  "version": "2.1.395",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -154,8 +154,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.393",
-    "@djangocfg/ui-core": "^2.1.393",
+    "@djangocfg/i18n": "^2.1.395",
+    "@djangocfg/ui-core": "^2.1.395",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -209,9 +209,9 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.393",
-    "@djangocfg/typescript-config": "^2.1.393",
-    "@djangocfg/ui-core": "^2.1.393",
+    "@djangocfg/i18n": "^2.1.395",
+    "@djangocfg/typescript-config": "^2.1.395",
+    "@djangocfg/ui-core": "^2.1.395",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/components/FloatingToolbar/FloatingToolbar.css

@@ -1,5 +1,5 @@
 /* Focus ring when scroll isolation is unlocked */
 .scroll-unlocked {
-  box-shadow: 0 0 0 2px hsl(var(--ring));
+  box-shadow: 0 0 0 2px var(--ring);
   transition: box-shadow 150ms;
 }

package/src/tools/Chat/README.md

@@ -16,12 +16,19 @@ const transport = createPydanticAIChatTransport({
 export function MyChat() {
   return (
     <ChatLauncher
+      transport={transport}
+      config={{ greeting: 'How can I help?' }}
+      audio={{}}
       hotkey={{ key: '/', meta: true }}
       fab={{ variant: 'animated', tooltip: 'Open chat (⌘/)' }}
       dock={{ title: 'Assistant', height: 600 }}
       greeting="Hi 👋 Need help?"
+      headerSlots={{
+        languagePicker: true,
+        modeToggle: { persistAs: 'my.chat.dock' },
+      }}
     >
-      <ChatRoot transport={transport} config={{ greeting: 'How can I help?' }} />
+      <ChatRoot />
     </ChatLauncher>
   );
 }
@@ -31,22 +38,23 @@ export function MyChat() {
 
 - **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).
+- **Header actions.** Declarative `headerSlots` prop on `<ChatLauncher>` — `audio` / `modeToggle` / `languagePicker` / `reset` / `custom`. Renders inside the provider, every slot has `useChatContext()` access. Raw `ChatHeader` / `ChatHeaderActionButton` / `ChatHeaderModeToggle` / `ChatHeaderAudioToggle` / `ChatHeaderResetButton` / `ChatHeaderLanguageButton` still exported for advanced custom shells.
 - **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. 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.
+- **Facebook-style unread notifier.** `useChatUnreadNotifier()` prefixes `document.title` with `(N)` and paints a small red dot over the favicon while the tab is in background. Sober by default — the favicon is the attention signal, the title stays readable. Title rotation is available as opt-in (`title: { mode: 'rotate' }`) for hosts without a favicon. Cross-tab coordinated via `useActiveTab` from `@djangocfg/ui-core`: only the elected leader tab mutates title/favicon, the count is broadcast so every tab's FAB badge stays in sync. Pluggable `ChatNotifier` interface lets Wails / Electron hosts route to a native dock badge instead.
 - **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).
+- **Audio.** Pass `audio: ChatAudioConfig` (sounds map) to `<ChatLauncher>` — the hook runs internally. Built on `@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) — `audio={{}}` 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.
+- **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.
 - **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.
+- **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.
 - **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`.
@@ -69,6 +77,8 @@ Components (MessageList, MessageBubble, Composer, Sources, ToolCalls, …)
 ChatRoot (one-line preset)  ◄──  optionally wrapped by  ──►  ChatLauncher (FAB + Dock + Greeting)
 ```
 
+`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.
+
 Module boundaries:
 
 | Layer            | May import                       | May NOT import           |
@@ -109,11 +119,12 @@ Picks the highest level that fits.
 | `<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`) |
+| `headerSlots` (prop on `<ChatLauncher>`) | Declarative header buttons — `audio` / `modeToggle` / `languagePicker` / `reset` / `custom`. Renders inside the provider, so every slot has `useChatContext()` access. **Prefer this over the raw header components below.** |
+| `<ChatHeader>` + `<ChatHeaderActionButton>` | Custom header chrome (advanced — when you build your own dock shell) |
+| `<ChatHeaderModeToggle>` | Popover ↔ side toggle (desktop-only, auto-hides below `lg`). Used internally by `headerSlots.modeToggle`. |
+| `<ChatHeaderAudioToggle>` | Mute / unmute notification sounds. Used internally by `headerSlots.audio`. |
+| `<ChatHeaderResetButton>` | Clear conversation with `window.dialog.confirm`. Used internally by `headerSlots.reset`. |
+| `<ChatHeaderLanguageButton>` | Flag-button language picker (66 BCP-47 tags, persists in `useSpeechPrefs`). Used internally by `headerSlots.languagePicker`. |
 
 ### FAB
 
@@ -145,26 +156,55 @@ dock={{
   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 ... />,
 }}
 ```
 
-**Side mode is desktop-only.** Below `lg` (1024px) it silently falls back to popover and the `<ChatHeaderModeToggle>` hides itself.
+**Side mode is desktop-only.** Below `lg` (1024px) it silently falls back to popover and the mode-toggle slot hides itself.
+
+**Header buttons go through `headerSlots`** (see below), not `dock.headerActions` (removed). The launcher computes header actions from the declarative slot config and forwards them to `<ChatDock>` internally.
 
-**Persisted prefs.** `useChatDockPrefs()` stores `mode` / `side` / `sideWidth` in localStorage. Drop it into your launcher to give users a remembered layout:
+### Header slots
+
+Declarative header buttons rendered inside the launcher's `<ChatProvider>`. Every slot has access to `sessionId`, `clearMessages`, etc. via `useChatContext()` — no JSX plumbing.
 
 ```tsx
-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} />,
+  transport={transport}
+  audio={{}}                              // ChatAudioConfig (sounds map)
+  dock={{ title: 'Assistant' }}
+  headerSlots={{
+    languagePicker: true,                 // 66 BCP-47 tags
+    modeToggle: {
+      persistAs: 'crm.chat.dock',         // localStorage key for useChatDockPrefs
+      defaults: { mode: 'popover', side: 'right' },
+    },
+    reset: {
+      onReset: async () => {              // backend call — return true on success
+        await api.clearChat();
+        return true;
+      },
+      confirmMessage: "Forget this conversation?",
+      // onSuccess defaults to ctx.clearMessages(); override for analytics, refetch, …
+    },
+    custom: (ctx) => <MyButton sessionId={ctx.sessionId} />,
   }}
->{children}</ChatLauncher>
+>
+  <ChatRoot />
+</ChatLauncher>
 ```
 
+Order is fixed left → right: `custom · languagePicker · modeToggle · audio · reset` (close icon stays right-most, owned by `<ChatHeader>`).
+
+| Slot | Value | Default |
+|---|---|---|
+| `audio` | `boolean` | auto-on when launcher `audio` is configured and not silent |
+| `modeToggle` | `boolean \| { persistAs?, defaults?, forceVisible? }` | off |
+| `languagePicker` | `boolean \| { allowedTags?, ariaLabel?, hideFallbackIcon? }` | off |
+| `reset` | `{ onReset, confirm?, confirmMessage?, onSuccess?, onError? }` | off (no `onReset`) |
+| `custom` | `(ctx: ChatContextValue) => ReactNode` | off |
+
+`useChatDockPrefs()` is now absorbed by `headerSlots.modeToggle.persistAs` — the launcher owns the hook internally. Set the key, get persisted `mode` / `side` / `sideWidth` across reloads. Below `lg` the toggle hides itself unless `forceVisible: true`.
+
 #### Side-mode body reserve + the `--chat-dock-reserve` token
 
 When the dock is in `mode='side'` it pushes the rest of the page out of its way by writing two things to `<body>`:
@@ -304,16 +344,42 @@ function Launcher() {
 
 `<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.
 
+### Tab/favicon notifier (Facebook-style)
+
+For when the user is in another tab and you want them to notice. Drop-in replacement for `useChatUnread`:
+
+```tsx
+function Launcher() {
+  const [open, setOpen] = useState(false);
+  // Same shape as useChatUnread, plus mutates document.title + favicon
+  // when the tab is hidden + count > 0. Restores on focus / open.
+  const { unread, count, markRead } = useChatUnreadNotifier({ open });
+  // …
+}
+```
+
+Defaults are sober: `document.title` becomes `(N) Original Title` (no rotation, no emoji — the favicon is the attention signal). Favicon gets a small red dot in the corner. Switch to title rotation when there's no favicon to lean on: `useChatUnreadNotifier({ browser: { title: { mode: 'rotate' } } })`. Number-in-badge: `useChatUnreadNotifier({ browser: { favicon: { showCount: true } } })`.
+
+**Cross-tab.** Three tabs open, a message arrives — only one tab (the elected leader) blinks the title; all three show the same FAB-badge count. Built on `useActiveTab` in `@djangocfg/ui-core/hooks` (BroadcastChannel + leader election). Disable with `crossTab: false` for single-tab hosts (Wails / Electron).
+
+**Native hosts.** Pass your own `notifier: ChatNotifier` to skip the browser implementation and emit Wails / Electron / Tauri events instead:
+
+```tsx
+const dockBadge: ChatNotifier = {
+  setUnread: (count) => window.runtime.EventsEmit('chat:unread', count),
+  clear:     ()       => window.runtime.EventsEmit('chat:unread', 0),
+};
+useChatUnreadNotifier({ open, notifier: dockBadge, crossTab: false });
+```
+
 ### Audio
 
-Wire `useChatAudio` once and pass it to `ChatLauncher` — the header gets an auto-injected mute toggle:
+Pass an `audio` config (`ChatAudioConfig` — the sounds map) to `<ChatLauncher>` and the header auto-injects a mute toggle. The launcher owns `useChatAudio()` internally; consumers no longer wire the hook themselves.
 
 ```tsx
 // Zero-setup — built-in sounds are bundled as base64 data URLs
-const audio = useChatAudio();
-
-<ChatLauncher audio={audio} dock={{ title: 'Helper' }}>
-  <ChatRoot transport={transport} />
+<ChatLauncher transport={transport} audio={{}} dock={{ title: 'Helper' }}>
+  <ChatRoot />
 </ChatLauncher>
 ```
 
@@ -322,13 +388,13 @@ const audio = useChatAudio();
 Customize:
 
 ```tsx
-import { useChatAudio, DEFAULT_CHAT_SOUNDS } from '@djangocfg/ui-tools/chat';
+import { DEFAULT_CHAT_SOUNDS } from '@djangocfg/ui-tools/chat';
 
 // Override one event, keep the rest
-useChatAudio({ sounds: { ...DEFAULT_CHAT_SOUNDS, mention: '/sfx/custom.mp3' } });
+<ChatLauncher audio={{ sounds: { ...DEFAULT_CHAT_SOUNDS, mention: '/sfx/custom.mp3' } }} ... />
 
-// Disable entirely (header toggle hides itself)
-useChatAudio({ sounds: {} });
+// Disable entirely (header toggle auto-hides via headerSlots.audio = false default)
+<ChatLauncher audio={{ sounds: {} }} ... />
 ```
 
 Per-event volume defaults — Slack / Linear / Intercom style:
@@ -344,31 +410,46 @@ Per-event volume defaults — Slack / Linear / Intercom style:
 
 Override via `eventVolumes: { error: 0, mention: 0.8 }`. Pass `eventVolumes: {}` to skip defaults entirely.
 
-`audio.muted` / `audio.toggleMute()` are persisted in localStorage. Header `<ChatHeaderAudioToggle>` is hidden automatically when `audio.isSilent` (no sounds wired).
+`muted` / `toggleMute()` state is persisted in localStorage by the internal hook. The `headerSlots.audio` toggle auto-hides when the resolved audio instance is silent (no sounds wired, or `silenced: true`).
 
 **Native hosts (cmdop_go / Tauri / Electron).** Skip web playback but keep the trigger as a side-channel:
 
 ```tsx
-const audio = useChatAudio({
-  silenced: true,
-  onSoundEvent: (e) => window.go.playSound(e),
-});
+<ChatLauncher
+  audio={{ silenced: true, onSoundEvent: (e) => window.go.playSound(e) }}
+  ...
+/>
 ```
 
 See [`@djangocfg/ui-core` Audio docs](../../../../ui-core/README.md#audio) for the underlying `useNotificationSounds` primitives.
 
 ### Reset / clear conversation
 
+Use `headerSlots.reset` — declarative, no JSX. `sessionId` and `clearMessages()` are pulled from chat context automatically; the button is hidden until a `sessionId` exists.
+
 ```tsx
-<ChatHeaderResetButton
-  onReset={api.clearChat}            // your backend POST /chat/reset
-  onSuccess={() => chat.clearMessages()}
-  confirmMessage="Forget this conversation? The assistant won't remember it."
-/>
+<ChatLauncher
+  transport={transport}
+  headerSlots={{
+    reset: {
+      onReset: async () => {                        // backend POST /chat/reset
+        await api.clearChat();
+        return true;                                // resolve `true` on success
+      },
+      confirmMessage: "Forget this conversation? The assistant won't remember it.",
+      // onSuccess defaults to ctx.clearMessages(); override to re-fetch history,
+      // navigate, fire analytics, etc.
+    },
+  }}
+>
+  <ChatRoot />
+</ChatLauncher>
 ```
 
 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 custom dock shells that don't use `headerSlots`, the raw `<ChatHeaderResetButton onReset onSuccess confirmMessage />` is still exported.
+
 ### Anti-patterns
 
 | Don't | Why |
@@ -378,7 +459,9 @@ Calls `window.dialog.confirm` (destructive variant) from `@djangocfg/ui-core/lib
 | 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) |
+| Forgetting `<DialogProvider>` for `headerSlots.reset` (or raw `<ChatHeaderResetButton>`) | Falls back to native browser confirm (ugly) |
+| Passing `dock.headerActions` (removed in the new launcher) | Use `headerSlots` instead — it renders inside the provider so reset can read `sessionId` / `clearMessages` |
+| Calling `useChatAudio()` in consumer code | Pass `audio={{}}` (or `{ sounds: {…} }`) to `<ChatLauncher>` — the launcher owns the hook now |
 | Mixing **root barrel** and **subpath** imports | Loads the package twice → two React contexts → `useChatContextOptional()` returns `null` → VoiceComposerSlot silently drops transcripts. See **Import discipline** below. |
 
 #### Import discipline
@@ -545,9 +628,12 @@ type PydanticAIChatTransportOpts, type PydanticAIEvent, type ToolIdQueue
 
 // Hooks
 useChat, useChatComposer, useChatScroll, useChatHistory, useChatLayout,
-useChatAudio, useChatLightbox, useAutoFocusOnStreamEnd, useRegisterComposer,
-useChatReset, useVisitorFingerprint, useChatDockPrefs, useChatUnread,
+useChatLightbox, useAutoFocusOnStreamEnd, useRegisterComposer,
+useChatReset, useVisitorFingerprint, useChatUnread, useChatUnreadNotifier,
+createBrowserNotifier, createCrossTabNotifier, createTitleRotator, createFaviconBadge,
 useFocusOnEmptyClick
+// `useChatAudio` and `useChatDockPrefs` are still exported for advanced custom
+// shells, but `<ChatLauncher>` owns them via `audio` prop + `headerSlots.modeToggle.persistAs`.
 type ChatDockPrefs, DEFAULT_DOCK_PREFS
 
 // Styles — role-aware tokens + hooks
@@ -566,6 +652,8 @@ type ChatHeaderAudioToggleProps, type ChatHeaderResetButtonProps,
 type ChatHeaderLanguageButtonProps,
 type ChatGreetingProps, type ChatUnreadPreviewProps,
 type ChatLauncherProps, type ChatLauncherHotkey, type ChatLauncherGreeting,
+type ChatHeaderSlots, type ChatHeaderResetSlot, type ChatHeaderLanguageSlot,
+type ChatHeaderModeToggleSlot,
 type ChatPresencePhase
 
 // Audio

package/src/tools/Chat/components/ChatRoot.tsx

@@ -6,7 +6,12 @@ import { cn } from '@djangocfg/ui-core/lib';
 
 import type { ChatAttachment, ChatConfig, ChatMessage, ChatTransport } from '../types';
 import type { ChatAudioConfig } from '../core/audio/types';
-import { ChatProvider, useChatContext, type ChatContextValue } from '../context';
+import {
+  ChatProvider,
+  useChatContext,
+  useChatContextOptional,
+  type ChatContextValue,
+} from '../context';
 import { useAutoFocusOnStreamEnd } from '../hooks/useAutoFocusOnStreamEnd';
 import { useChatComposer, type UseChatComposerReturn } from '../hooks/useChatComposer';
 import { useFocusOnEmptyClick } from '../hooks/useFocusOnEmptyClick';
@@ -21,7 +26,13 @@ import type { ToolCallsProps } from './ToolCalls';
 
 export interface ChatRootProps {
   // ---- core wiring -------------------------------------------------------
-  transport: ChatTransport;
+  /**
+   * Transport. Required UNLESS `<ChatRoot>` is rendered inside an
+   * existing `<ChatProvider>` (e.g. mounted by `<ChatLauncher>`), in
+   * which case the ambient provider is reused and `transport` is
+   * ignored.
+   */
+  transport?: ChatTransport;
   config?: ChatConfig;
   initialSessionId?: string;
   autoCreateSession?: boolean;
@@ -94,6 +105,19 @@ export interface ChatRootProps {
 
 export function ChatRoot(props: ChatRootProps) {
   const { transport, config, initialSessionId, autoCreateSession, streaming, audio, debug, className, listClassName, ...slots } = props;
+  // When mounted under a launcher-owned `<ChatProvider>`, reuse that
+  // provider instead of wrapping in a second one. This lets host code
+  // freely nest `<ChatRoot>` inside `<ChatLauncher>` without losing
+  // `headerSlots` access to the same session / clearMessages / audio.
+  const ambient = useChatContextOptional();
+  if (ambient) {
+    return <ChatRootShell className={className} listClassName={listClassName} slots={slots} />;
+  }
+  if (!transport) {
+    throw new Error(
+      '<ChatRoot> requires `transport` when mounted outside a <ChatProvider>.',
+    );
+  }
   return (
     <ChatProvider
       transport={transport}

package/src/tools/Chat/hooks/index.ts

@@ -55,3 +55,7 @@ export {
   type UseChatUnreadOptions,
   type UseChatUnreadReturn,
 } from './useChatUnread';
+export {
+  useChatUnreadNotifier,
+  type UseChatUnreadNotifierOptions,
+} from './useChatUnreadNotifier';

package/src/tools/Chat/hooks/useChatUnreadNotifier.ts

@@ -0,0 +1,134 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { useActiveTabStore } from '@djangocfg/ui-core/hooks';
+
+import {
+  createBrowserNotifier,
+  createCrossTabNotifier,
+  isPageHidden,
+  onVisibilityChange,
+  type BrowserNotifierOptions,
+  type ChatNotifier,
+} from '../notifier';
+
+import { useChatUnread, type UseChatUnreadOptions } from './useChatUnread';
+
+export interface UseChatUnreadNotifierOptions extends UseChatUnreadOptions {
+  /**
+   * Custom notifier. Pass a host-specific implementation (Wails dock
+   * badge etc.) to opt out of the built-in browser title/favicon
+   * mutation. If omitted, a `createBrowserNotifier` instance is used.
+   */
+  notifier?: ChatNotifier;
+  /**
+   * Options forwarded to the default browser notifier. Ignored when an
+   * explicit `notifier` is provided.
+   */
+  browser?: BrowserNotifierOptions;
+  /**
+   * Master switch. Default `true`. Set false to keep the unread
+   * tracking but skip all environment mutation.
+   */
+  enabled?: boolean;
+  /**
+   * Cross-tab coordination. When enabled (default), only the elected
+   * leader tab mutates `document.title` / favicon — other tabs stay
+   * silent. The unread count is broadcast so every tab's FAB badge UI
+   * still reflects reality.
+   *
+   * Pass `false` to disable; pass an options object to customise the
+   * BroadcastChannel name. Disable in single-tab hosts (Wails / Electron)
+   * where leadership is moot.
+   */
+  crossTab?: boolean | { channel?: string };
+}
+
+/**
+ * Glue between `useChatUnread` and a `ChatNotifier`.
+ *
+ * Inputs that drive the notifier:
+ *   1. `useChatUnread` — provider-state-derived `{ count, unread }`.
+ *   2. Page visibility — clear when visible; re-arm when hidden+count>0.
+ *   3. Tab leadership (when `crossTab` enabled) — only leader mutates
+ *      title/favicon; followers receive count broadcasts so their
+ *      in-tab badge UI stays in sync.
+ *
+ * Returns `useChatUnread`'s shape, with the `count` overridden by
+ * cross-tab broadcasts when this tab is a follower (so the FAB badge
+ * shows the same number across every tab).
+ */
+export function useChatUnreadNotifier(opts: UseChatUnreadNotifierOptions = {}) {
+  const {
+    notifier: notifierProp,
+    browser,
+    enabled = true,
+    crossTab = true,
+    ...unreadOpts
+  } = opts;
+  const unread = useChatUnread(unreadOpts);
+
+  // Cross-tab count from peers (followers see this; leader publishes).
+  const [peerCount, setPeerCount] = useState<number | null>(null);
+
+  const crossTabChannel =
+    typeof crossTab === 'object' ? crossTab.channel : undefined;
+  const crossTabEnabled = crossTab !== false;
+
+  // Build the notifier. Inner = host-supplied OR built-in browser.
+  // Wrap with cross-tab decorator when enabled.
+  const notifier = useMemo<ChatNotifier>(() => {
+    const inner = notifierProp ?? createBrowserNotifier(browser);
+    if (!crossTabEnabled) return inner;
+    return createCrossTabNotifier({
+      inner,
+      isLeader: () => useActiveTabStore.getState().isLeader,
+      channel: crossTabChannel,
+      onPeerUpdate: (count) => setPeerCount(count),
+    });
+  }, [notifierProp, browser, crossTabEnabled, crossTabChannel]);
+
+  const lastSyncedCount = useRef(0);
+
+  // Visibility-driven sync. Single effect owns both the listener and
+  // the imperative calls to keep ordering deterministic.
+  useEffect(() => {
+    if (!enabled) {
+      notifier.clear();
+      return;
+    }
+
+    const sync = () => {
+      const hidden = isPageHidden();
+      if (hidden && unread.count > 0) {
+        notifier.setUnread(unread.count, unread.unread);
+        lastSyncedCount.current = unread.count;
+      } else {
+        notifier.clear();
+        lastSyncedCount.current = 0;
+      }
+    };
+
+    sync();
+    const unsub = onVisibilityChange(sync);
+    return () => {
+      unsub();
+      notifier.clear();
+    };
+  }, [enabled, notifier, unread.count, unread.unread]);
+
+  // Final cleanup — release any host-side resources.
+  useEffect(() => () => notifier.dispose?.(), [notifier]);
+
+  // Effective count: max of local (this tab's own unread tracking) and
+  // peer broadcast. The max handles the case where a peer hasn't sent
+  // a broadcast yet (peerCount === null) — we trust local.
+  const effectiveCount =
+    peerCount !== null ? Math.max(unread.count, peerCount) : unread.count;
+
+  return {
+    ...unread,
+    count: effectiveCount,
+  };
+}

package/src/tools/Chat/index.ts

@@ -103,6 +103,10 @@ export {
   type ChatLauncherProps,
   type ChatLauncherHotkey,
   type ChatLauncherGreeting,
+  type ChatHeaderSlots,
+  type ChatHeaderResetSlot,
+  type ChatHeaderLanguageSlot,
+  type ChatHeaderModeToggleSlot,
   type ChatGreetingProps,
   type ChatUnreadPreviewProps,
   type ChatPresencePhase,
@@ -124,8 +128,10 @@ export {
   DEFAULT_DOCK_PREFS,
   useFocusOnEmptyClick,
   useChatUnread,
+  useChatUnreadNotifier,
   type UseChatUnreadOptions,
   type UseChatUnreadReturn,
+  type UseChatUnreadNotifierOptions,
   type UseChatConfig,
   type UseChatReturn,
   type UseChatComposerOptions,
@@ -146,6 +152,23 @@ export {
   type UseFocusOnEmptyClickOptions,
 } from './hooks';
 
+// Notifier — title rotation + favicon badge + page-visibility + cross-tab
+export {
+  createBrowserNotifier,
+  createNoopNotifier,
+  createTitleRotator,
+  createFaviconBadge,
+  createCrossTabNotifier,
+  isPageHidden,
+  onVisibilityChange,
+  type ChatNotifier,
+  type BrowserNotifierOptions,
+  type TitleRotatorOptions,
+  type TitleMode,
+  type FaviconBadgeOptions,
+  type CrossTabNotifierOptions,
+} from './notifier';
+
 // Audio
 export type {
   ChatAudioEvent,