@djangocfg/ui-tools 2.1.393 → 2.1.395

package/src/tools/Chat/launcher/ChatLauncher.tsx

@@ -1,16 +1,24 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { ReactNode } from 'react';
 
 import { useHotkey } from '@djangocfg/ui-core/hooks';
 
+import { ChatProvider, useChatContextOptional } from '../context';
+import type { ChatAudioConfig } from '../core/audio/types';
+import type {
+  ChatConfig,
+  ChatMessage,
+  ChatTransport,
+} from '../types';
+
 import { ChatFAB, type ChatFABPosition, type ChatFABProps } from './ChatFAB';
 import { ChatDock, type ChatDockProps } from './ChatDock';
 import { ChatGreeting, type ChatGreetingProps } from './ChatGreeting';
-import { ChatHeaderAudioToggle } from './ChatHeaderAudioToggle';
 import { ChatUnreadPreview, type ChatUnreadPreviewProps } from './ChatUnreadPreview';
-import type { ChatMessage } from '../types';
+import { HeaderSlotsRenderer } from './HeaderSlots';
+import { resolveHeaderSlots, type ChatHeaderSlots } from './types';
 
 export interface ChatLauncherHotkey {
   /** Key (case-sensitive single char or named like 'Escape'). */
@@ -34,73 +42,73 @@ export interface ChatLauncherGreeting
 }
 
 export interface ChatLauncherProps {
-  /** Dock contents — typically a `<Chat>` instance. */
+  // ---- chat-provider wiring (mounts <ChatProvider> internally) -----------
+  /**
+   * Transport. Required unless the launcher is mounted inside an
+   * existing `<ChatProvider>` (in which case the ambient provider is
+   * reused and `transport` is ignored).
+   */
+  transport?: ChatTransport;
+  /** Optional chat config (labels, prefs, persona, etc.). */
+  config?: ChatConfig;
+  /** Pre-existing session to attach to. */
+  initialSessionId?: string;
+  /** Create a new backend session automatically when none is provided. */
+  autoCreateSession?: boolean;
+  /** Enable streaming. Defaults to transport's preference. */
+  streaming?: boolean;
+  /**
+   * Audio-trigger configuration (sounds map). The launcher owns the
+   * `useChatAudio()` hook internally; consumers no longer construct it
+   * themselves.
+   */
+  audio?: ChatAudioConfig;
+  /** Verbose dev logging via consola. */
+  debug?: boolean;
+  /** Rewrite outgoing content before transport. */
+  onBeforeSend?: (content: string) => string | Promise<string>;
+
+  // ---- visual chrome ------------------------------------------------------
+  /** Dock contents — typically a `<ChatRoot>` or custom chat shell. */
   children: ReactNode;
-  /** FAB customization (icon, position, label, pulse, badge, tooltip, variant, size). */
+  /** FAB customization. */
   fab?: Omit<ChatFABProps, 'onClick'>;
-  /** Dock customization (size, title, position, transition, mobileFullscreen). */
-  dock?: Omit<ChatDockProps, 'open' | 'onClose' | 'children'>;
+  /** Dock customization. `headerActions` is computed from `headerSlots`. */
+  dock?: Omit<ChatDockProps, 'open' | 'onClose' | 'children' | 'headerActions'>;
+  /**
+   * Declarative header buttons rendered INSIDE the launcher's
+   * `<ChatProvider>`. See `ChatHeaderSlots` for the available knobs.
+   */
+  headerSlots?: ChatHeaderSlots;
   /**
-   * Proactive greeting bubble shown next to the FAB before the user opens the chat.
-   * Set to a string or full config object. Omit to disable.
+   * Proactive greeting bubble shown next to the FAB before the user
+   * opens the chat.
    */
   greeting?: string | ChatLauncherGreeting;
   /** Open/close via a keyboard shortcut. */
   hotkey?: ChatLauncherHotkey;
   /** Initial open state for uncontrolled mode. @default false */
   defaultOpen?: boolean;
-  /** Controlled open state (pair with `onOpenChange`). */
+  /** Controlled open state. */
   open?: boolean;
   /** Controlled open state setter. */
   onOpenChange?: (open: boolean) => void;
-  /**
-   * Focus the composer textarea when the dock opens. Saves a click for
-   * every "FAB → start typing" interaction. @default true
-   */
+  /** Focus the composer when the dock opens. @default true */
   autoFocusComposerOnOpen?: boolean;
-  /**
-   * Close the dock on `Escape`. Mirrors standard popover / drawer UX.
-   * Set to `false` to disable (e.g. if you want Escape to do something
-   * else inside the chat). @default true
-   */
+  /** Close the dock on Escape. @default true */
   closeOnEscape?: boolean;
   /**
-   * Last inbound message (admin reply / system notice / agent push) the
-   * user hasn't seen yet. Drives the `<ChatUnreadPreview>` bubble next
-   * to the FAB and (by default) the FAB badge.
-   *
-   * Source it from `useChatUnread()` inside your `<ChatProvider>`.
+   * Last unread inbound message — drives `<ChatUnreadPreview>` and the
+   * FAB badge.
    */
   unreadMessage?: ChatMessage | null;
-  /**
-   * Called when the user opens the chat via FAB/preview/hotkey or
-   * dismisses the preview with ×. Wire to `useChatUnread().markRead`.
-   */
+  /** Called when the chat is opened or the preview dismissed. */
   onMarkRead?: () => void;
-  /**
-   * Customize the unread bubble (`truncate`, `dismissLabel`, …).
-   * `open`/`message`/`onClick`/`onDismiss`/`position`/`fabOffset` are
-   * wired automatically.
-   */
+  /** Customize the unread bubble. */
   unreadPreview?: Omit<
     ChatUnreadPreviewProps,
     'open' | 'message' | 'onClick' | 'onDismiss' | 'position' | 'fabOffset'
   >;
-  /**
-   * Auto-inject a mute / unmute button into the header. Pass the
-   * `useChatAudio()` (or any compatible `{ muted, toggleMute }`)
-   * instance — the launcher renders `<ChatHeaderAudioToggle>` in the
-   * header's actions slot when audio is actually configured (not silent).
-   *
-   * Hosts that manage their own header can ignore this prop and render
-   * `<ChatHeaderAudioToggle>` directly.
-   */
-  audio?: { muted: boolean; toggleMute: () => void; isSilent?: boolean } | null;
-  /**
-   * Suppress the auto-injected audio toggle even when `audio` is passed.
-   * @default false
-   */
-  hideAudioToggle?: boolean;
 }
 
 function readDismissed(storageKey: string | null | undefined): boolean {
@@ -124,15 +132,31 @@ function writeDismissed(storageKey: string | null | undefined): void {
 }
 
 /**
- * Floating chat launcher = FAB + Dock + presence + optional greeting + hotkey.
+ * Floating chat launcher = `<ChatProvider>` + FAB + Dock + presence
+ * + optional greeting + hotkey.
  *
- * 99% of hosts use this directly. For non-FAB triggers (e.g. an inline
- * link in the page) compose `<ChatDock>` with your own button.
+ * The provider lives at this level so:
+ *   - declarative `headerSlots` (e.g. `reset`) can read `sessionId` /
+ *     call `clearMessages()` via `useChatContext()` while rendering in
+ *     the dock header, which is a sibling of `children` (not a child).
+ *   - descendant `<ChatRoot>` instances detect the ambient provider and
+ *     skip wrapping in a second one.
  */
 export function ChatLauncher({
+  // provider wiring
+  transport,
+  config,
+  initialSessionId,
+  autoCreateSession,
+  streaming,
+  audio,
+  debug,
+  onBeforeSend,
+  // visual chrome
   children,
   fab,
   dock,
+  headerSlots,
   greeting,
   hotkey,
   defaultOpen = false,
@@ -143,8 +167,6 @@ export function ChatLauncher({
   unreadMessage,
   onMarkRead,
   unreadPreview,
-  audio,
-  hideAudioToggle = false,
 }: ChatLauncherProps) {
   const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
   const isControlled = controlledOpen !== undefined;
@@ -152,9 +174,6 @@ export function ChatLauncher({
   const dockContentRef = useRef<HTMLDivElement>(null);
 
   // Auto-focus the composer when the dock opens.
-  // We probe the dock subtree for the first textarea/input after the
-  // enter-transition settles. Keeps the hook self-contained — no need to
-  // bridge into the ChatProvider context which lives inside `children`.
   useEffect(() => {
     if (!autoFocusComposerOnOpen || !open) return;
     const t = setTimeout(() => {
@@ -177,12 +196,6 @@ export function ChatLauncher({
   );
   const toggleOpen = useCallback(() => setOpen(!open), [open, setOpen]);
 
-  // Two-step Escape (ChatGPT / Slack behaviour):
-  //   - When focus is inside a textarea / input / contenteditable, first Esc
-  //     just blurs — drafts survive accidental presses.
-  //   - When focus is elsewhere (the user already left the composer or never
-  //     focused it), Esc closes the dock.
-  // Disabled when chat is shut so we don't intercept page-level Esc bindings.
   useHotkey(
     'escape',
     (e) => {
@@ -227,7 +240,6 @@ export function ChatLauncher({
     return () => window.removeEventListener('keydown', handler);
   }, [hotkey?.key, hotkey?.meta, hotkey?.shift, hotkey?.alt, open, setOpen, hotkey]);
 
-  // Greeting visibility: respect dismissal, hideOnOpen, and the actual open state.
   const greetingOpen = !!greetingConfig
     && !dismissed
     && (greetingConfig.hideOnOpen === false || !open);
@@ -242,22 +254,14 @@ export function ChatLauncher({
 
   const handleGreetingClick = () => {
     setOpen(true);
-    // Tap-to-open also clears the proactive bubble — pushing it again on
-    // the same visit would feel spammy. Persisted dismissal honours the
-    // storage key so it doesn't reappear after navigation either.
     setDismissed(true);
     writeDismissed(greetingConfig?.dismissStorageKey);
   };
 
-  // Mark-as-read also fires when the chat opens through any path (FAB,
-  // hotkey, controlled state) — symmetric with click-to-open via the
-  // preview itself.
   useEffect(() => {
     if (open && unreadMessage) onMarkRead?.();
   }, [open, unreadMessage, onMarkRead]);
 
-  // Unread preview replaces the greeting when there's a real inbound
-  // message to surface — same anchor, more relevant content.
   const unreadOpen = !open && !!unreadMessage;
   const handleUnreadClick = () => {
     setOpen(true);
@@ -267,12 +271,40 @@ export function ChatLauncher({
     onMarkRead?.();
   };
 
-  // Auto-derive a "1" badge from unread when the host didn't set one.
   const resolvedFab = unreadMessage && fab?.badge === undefined
     ? { ...fab, badge: 1 }
     : fab;
 
-  return (
+  // Whether the audio prop wires up any actual sound. Used as the
+  // default for `headerSlots.audio` — no point auto-injecting the
+  // toggle when there's nothing to mute.
+  const audioConfigured = useMemo<boolean>(() => {
+    if (!audio) return false;
+    if (audio.silenced) return false;
+    const sounds = audio.sounds;
+    // `useChatAudio` falls back to DEFAULT_CHAT_SOUNDS when `sounds` is
+    // undefined and `silenced` is false. Treat that as "configured" too.
+    if (sounds === undefined) return true;
+    return Object.values(sounds).some(
+      (v) => typeof v === 'string' && v.length > 0,
+    );
+  }, [audio]);
+
+  const resolvedSlots = useMemo(
+    () => resolveHeaderSlots(headerSlots, audioConfigured),
+    [headerSlots, audioConfigured],
+  );
+
+  const hasAnySlot =
+    resolvedSlots.audio ||
+    resolvedSlots.modeToggle !== null ||
+    resolvedSlots.languagePicker !== null ||
+    resolvedSlots.reset !== null ||
+    resolvedSlots.custom !== null;
+
+  const ambient = useChatContextOptional();
+
+  const body = (
     <>
       <ChatFAB {...resolvedFab} onClick={toggleOpen} />
       {unreadMessage ? (
@@ -302,14 +334,7 @@ export function ChatLauncher({
         open={open}
         onClose={() => setOpen(false)}
         headerActions={
-          (audio && !audio.isSilent && !hideAudioToggle) || dock?.headerActions ? (
-            <>
-              {dock?.headerActions}
-              {audio && !audio.isSilent && !hideAudioToggle ? (
-                <ChatHeaderAudioToggle muted={audio.muted} onToggle={audio.toggleMute} />
-              ) : null}
-            </>
-          ) : undefined
+          hasAnySlot ? <HeaderSlotsRenderer slots={resolvedSlots} /> : undefined
         }
       >
         <div ref={dockContentRef} className="flex h-full min-h-0 min-w-0 flex-col">
@@ -318,4 +343,33 @@ export function ChatLauncher({
       </ChatDock>
     </>
   );
+
+  if (ambient) {
+    // Already inside a ChatProvider — reuse it. Provider-level props
+    // (transport / config / audio / debug / onBeforeSend) are ignored
+    // because they belong to the upstream provider.
+    return body;
+  }
+
+  if (!transport) {
+    // No ambient provider and no transport — programmer error.
+    throw new Error(
+      '<ChatLauncher> requires `transport` when mounted outside a <ChatProvider>.',
+    );
+  }
+
+  return (
+    <ChatProvider
+      transport={transport}
+      config={config}
+      initialSessionId={initialSessionId}
+      autoCreateSession={autoCreateSession}
+      streaming={streaming}
+      audio={audio}
+      debug={debug}
+      onBeforeSend={onBeforeSend}
+    >
+      {body}
+    </ChatProvider>
+  );
 }

package/src/tools/Chat/launcher/HeaderSlots.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import { Fragment } from 'react';
+
+import { useChatContext } from '../context';
+import { useChatDockPrefs } from '../hooks/useChatDockPrefs';
+
+import { ChatHeaderAudioToggle } from './ChatHeaderAudioToggle';
+import { ChatHeaderLanguageButton } from './ChatHeaderLanguageButton';
+import { ChatHeaderModeToggle } from './ChatHeaderModeToggle';
+import { ChatHeaderResetButton } from './ChatHeaderResetButton';
+import type { ResolvedChatHeaderSlots } from './types';
+
+export interface HeaderSlotsRendererProps {
+  slots: ResolvedChatHeaderSlots;
+}
+
+/**
+ * Renders the declarative `headerSlots` config inside the
+ * `<ChatProvider>` mounted by `<ChatLauncher>`.
+ *
+ * Order (left → right, before the close icon):
+ *   custom · languagePicker · modeToggle · audio · reset
+ */
+export function HeaderSlotsRenderer({ slots }: HeaderSlotsRendererProps) {
+  const ctx = useChatContext();
+  return (
+    <>
+      {slots.custom ? <Fragment>{slots.custom(ctx)}</Fragment> : null}
+      {slots.languagePicker ? (
+        <ChatHeaderLanguageButton
+          allowedTags={slots.languagePicker.allowedTags}
+          ariaLabel={slots.languagePicker.ariaLabel}
+          hideFallbackIcon={slots.languagePicker.hideFallbackIcon}
+        />
+      ) : null}
+      {slots.modeToggle ? <ModeToggleSlot slot={slots.modeToggle} /> : null}
+      {slots.audio && !ctx.audio.isSilent ? (
+        <ChatHeaderAudioToggle
+          muted={ctx.audio.muted}
+          onToggle={ctx.audio.toggleMute}
+        />
+      ) : null}
+      {slots.reset && ctx.sessionId ? <ResetSlot slot={slots.reset} /> : null}
+    </>
+  );
+}
+
+function ModeToggleSlot({
+  slot,
+}: {
+  slot: NonNullable<ResolvedChatHeaderSlots['modeToggle']>;
+}) {
+  const prefs = useChatDockPrefs({
+    storageKey: slot.persistAs,
+    defaults: slot.defaults,
+  });
+  return (
+    <ChatHeaderModeToggle
+      mode={prefs.mode}
+      onToggle={prefs.toggleMode}
+      forceVisible={slot.forceVisible ?? true}
+      expandLabel={slot.expandLabel}
+      collapseLabel={slot.collapseLabel}
+    />
+  );
+}
+
+function ResetSlot({
+  slot,
+}: {
+  slot: NonNullable<ResolvedChatHeaderSlots['reset']>;
+}) {
+  const ctx = useChatContext();
+  const handleSuccess = () => {
+    if (slot.onSuccess) {
+      slot.onSuccess(ctx);
+      return;
+    }
+    ctx.clearMessages();
+  };
+  return (
+    <ChatHeaderResetButton
+      onReset={slot.onReset}
+      onSuccess={handleSuccess}
+      onError={slot.onError}
+      confirm={slot.confirm}
+      confirmTitle={slot.confirmTitle}
+      confirmMessage={slot.confirmMessage}
+      ariaLabel={slot.ariaLabel}
+    />
+  );
+}

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

@@ -38,6 +38,12 @@ export {
   type ChatLauncherHotkey,
   type ChatLauncherGreeting,
 } from './ChatLauncher';
+export type {
+  ChatHeaderSlots,
+  ChatHeaderResetSlot,
+  ChatHeaderLanguageSlot,
+  ChatHeaderModeToggleSlot,
+} from './types';
 export { ChatGreeting, type ChatGreetingProps } from './ChatGreeting';
 export {
   ChatUnreadPreview,

package/src/tools/Chat/launcher/types.ts

@@ -0,0 +1,132 @@
+import type { ReactNode } from 'react';
+
+import type { ChatContextValue } from '../context';
+import type { ChatDockPrefs } from '../hooks/useChatDockPrefs';
+
+/**
+ * Declarative reset slot. The launcher renders the standard
+ * `<ChatHeaderResetButton>` wired to `onReset`, defaulting `onSuccess`
+ * to `ctx.clearMessages()`. The button hides itself until a `sessionId`
+ * exists on the chat context.
+ */
+export interface ChatHeaderResetSlot {
+  /** Backend reset call. Resolves to `true` on success. */
+  onReset: () => Promise<boolean>;
+  /** Show a confirm dialog before calling `onReset`. @default true */
+  confirm?: boolean;
+  /** Confirm dialog title. */
+  confirmTitle?: string;
+  /** Confirm dialog message. */
+  confirmMessage?: string;
+  /** Override tooltip / aria label. */
+  ariaLabel?: string;
+  /**
+   * Called after a successful reset. Defaults to `ctx.clearMessages()`.
+   * Override to also re-fetch history, navigate, fire analytics, etc.
+   */
+  onSuccess?: (ctx: ChatContextValue) => void;
+  /** Called on failure (returned `false` or threw). */
+  onError?: (err?: unknown) => void;
+}
+
+/** Declarative language-picker slot. */
+export interface ChatHeaderLanguageSlot {
+  /** Subset of BCP-47 tags to offer. */
+  allowedTags?: string[];
+  /** Override aria-label. */
+  ariaLabel?: string;
+  /** Hide the globe fallback icon when no flag resolves. */
+  hideFallbackIcon?: boolean;
+}
+
+/**
+ * Declarative mode-toggle slot. The launcher owns `useChatDockPrefs`
+ * internally — set `persistAs` to a localStorage key for persistence
+ * (omit for ephemeral / session-only mode toggling).
+ */
+export interface ChatHeaderModeToggleSlot {
+  /**
+   * localStorage key for `useChatDockPrefs`. When provided the toggle
+   * persists across reloads; omit to use an ephemeral in-memory toggle.
+   */
+  persistAs?: string;
+  /** Override the default `{ mode: 'popover', side: 'right', sideWidth: 420 }`. */
+  defaults?: Partial<ChatDockPrefs>;
+  /** Show the toggle even on viewports below `lg` (1024px). @default true */
+  forceVisible?: boolean;
+  /** Tooltip / aria for popover → side. */
+  expandLabel?: string;
+  /** Tooltip / aria for side → popover. */
+  collapseLabel?: string;
+}
+
+/**
+ * Header buttons rendered INSIDE the `<ChatProvider>` mounted by
+ * `<ChatLauncher>`. Each entry is rendered in the fixed order:
+ *
+ *   custom · languagePicker · modeToggle · audio · reset
+ *
+ * (close icon is always last, owned by `<ChatHeader>`).
+ *
+ * Slots that accept `boolean | object`:
+ *  - `true`  → render with default config
+ *  - `false` → hide explicitly
+ *  - object  → render with the given options
+ *
+ * Defaults:
+ *  - `audio`: rendered automatically when `audio` prop is passed to
+ *    `<ChatLauncher>` AND the resolved instance is not silent.
+ *  - `modeToggle`, `languagePicker`: off unless opted in.
+ *  - `reset`: off unless `onReset` is provided.
+ */
+export interface ChatHeaderSlots {
+  /** Auto-mute toggle. Defaults to true when launcher `audio` is configured. */
+  audio?: boolean;
+  /** Popover ↔ side mode toggle. */
+  modeToggle?: boolean | ChatHeaderModeToggleSlot;
+  /** Speech-recognition language picker. */
+  languagePicker?: boolean | ChatHeaderLanguageSlot;
+  /** Reset-conversation button. */
+  reset?: ChatHeaderResetSlot;
+  /** Arbitrary extra buttons rendered first (left-most). */
+  custom?: (ctx: ChatContextValue) => ReactNode;
+}
+
+/**
+ * Resolved mode-toggle config used by the launcher to pick between
+ * the dock's mode/side props and the prefs slot.
+ */
+export interface ResolvedChatHeaderSlots {
+  audio: boolean;
+  modeToggle: ChatHeaderModeToggleSlot | null;
+  languagePicker: ChatHeaderLanguageSlot | null;
+  reset: ChatHeaderResetSlot | null;
+  custom: ((ctx: ChatContextValue) => ReactNode) | null;
+}
+
+export function resolveHeaderSlots(
+  slots: ChatHeaderSlots | undefined,
+  audioConfigured: boolean,
+): ResolvedChatHeaderSlots {
+  const s = slots ?? {};
+  const audio = s.audio ?? audioConfigured;
+  const modeToggle: ChatHeaderModeToggleSlot | null =
+    s.modeToggle === true
+      ? {}
+      : s.modeToggle && typeof s.modeToggle === 'object'
+        ? s.modeToggle
+        : null;
+  const languagePicker: ChatHeaderLanguageSlot | null =
+    s.languagePicker === true
+      ? {}
+      : s.languagePicker && typeof s.languagePicker === 'object'
+        ? s.languagePicker
+        : null;
+  return {
+    audio,
+    modeToggle,
+    languagePicker,
+    reset: s.reset ?? null,
+    custom: s.custom ?? null,
+  };
+}

package/src/tools/Chat/lazy.tsx

@@ -136,9 +136,11 @@ export {
   DEFAULT_DOCK_PREFS,
   useFocusOnEmptyClick,
   useChatUnread,
+  useChatUnreadNotifier,
   useChatLightbox,
   type UseChatUnreadOptions,
   type UseChatUnreadReturn,
+  type UseChatUnreadNotifierOptions,
   type UseChatConfig,
   type UseChatReturn,
   type UseChatComposerOptions,
@@ -171,6 +173,24 @@ export {
   type UseChatAudioReturn,
 } from './core/audio';
 
+// Notifier — title rotation + favicon badge + cross-tab decorator. Pure
+// browser-API code, no React, no UI components.
+export {
+  createBrowserNotifier,
+  createNoopNotifier,
+  createTitleRotator,
+  createFaviconBadge,
+  createCrossTabNotifier,
+  isPageHidden,
+  onVisibilityChange,
+  type ChatNotifier,
+  type BrowserNotifierOptions,
+  type TitleRotatorOptions,
+  type TitleMode,
+  type FaviconBadgeOptions,
+  type CrossTabNotifierOptions,
+} from './notifier';
+
 // Tool-call payload dispatcher — pure
 export {
   dispatchToolPayload,
@@ -269,6 +289,10 @@ export type {
   ChatLauncherProps,
   ChatLauncherHotkey,
   ChatLauncherGreeting,
+  ChatHeaderSlots,
+  ChatHeaderResetSlot,
+  ChatHeaderLanguageSlot,
+  ChatHeaderModeToggleSlot,
   ChatFABProps,
   ChatFABPosition,
   ChatFABVariant,

package/src/tools/Chat/notifier/createBrowserNotifier.ts

@@ -0,0 +1,64 @@
+import type { ChatMessage } from '../types';
+
+import { createFaviconBadge, type FaviconBadgeOptions } from './faviconBadge';
+import { createTitleRotator, type TitleRotatorOptions } from './titleRotator';
+import type { ChatNotifier } from './types';
+
+export interface BrowserNotifierOptions {
+  /** Title rotation config. Pass `false` to disable title mutation. */
+  title?: TitleRotatorOptions | false;
+  /** Favicon badge config. Pass `false` to disable favicon mutation. */
+  favicon?: FaviconBadgeOptions | false;
+}
+
+const NOOP: ChatNotifier = { setUnread() {}, clear() {} };
+
+/**
+ * Facebook-style unread notifier: alternates `document.title` between
+ * the base title and an alert, plus paints a small badge over the
+ * favicon. Both surfaces are optional and individually toggleable.
+ *
+ * Returns a no-op in SSR or non-DOM environments — safe to construct
+ * unconditionally.
+ *
+ * The notifier itself is **stateless w.r.t. visibility** by design;
+ * the hook layer (`useChatUnreadNotifier`) decides when to call
+ * `setUnread` vs `clear` based on page focus. Keeping the policy in
+ * the hook lets hosts swap in their own notifier (Wails dock badge,
+ * cross-tab Zustand broadcaster) without duplicating the gating logic.
+ */
+export function createBrowserNotifier(opts: BrowserNotifierOptions = {}): ChatNotifier {
+  if (typeof document === 'undefined') return NOOP;
+
+  const title = opts.title === false ? null : createTitleRotator(opts.title);
+  const favicon = opts.favicon === false ? null : createFaviconBadge(opts.favicon);
+
+  let active = false;
+
+  return {
+    setUnread(count: number, latest?: ChatMessage | null) {
+      if (count <= 0) {
+        this.clear();
+        return;
+      }
+      if (active) {
+        title?.update(count, latest);
+        favicon?.set(count);
+      } else {
+        active = true;
+        title?.start(count, latest);
+        favicon?.set(count);
+      }
+    },
+    clear() {
+      if (!active) return;
+      active = false;
+      title?.stop();
+      favicon?.clear();
+    },
+  };
+}
+
+export function createNoopNotifier(): ChatNotifier {
+  return NOOP;
+}