@djangocfg/ui-tools 2.1.381 → 2.1.383

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

@@ -5,6 +5,7 @@ import { File as FileIcon, X } from 'lucide-react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { useChatDestructiveStyles } from '../styles';
 import type { ChatAttachment } from '../types';
 
 export interface AttachmentRendererArgs {
@@ -179,12 +180,16 @@ function AttachmentTile({ attachment, onClick, onRemove }: AttachmentRendererArg
 }
 
 function RemoveBtn({ onRemove }: { onRemove: () => void }) {
+  const styles = useChatDestructiveStyles();
   return (
     <button
       type="button"
       aria-label="Remove attachment"
       onClick={onRemove}
-      className="absolute -right-1.5 -top-1.5 grid h-4 w-4 place-items-center rounded-full border border-border bg-background text-muted-foreground hover:bg-destructive hover:text-destructive-foreground"
+      className={cn(
+        'absolute -right-1.5 -top-1.5 grid h-4 w-4 place-items-center rounded-full border border-border bg-background text-muted-foreground',
+        styles.hoverStrong,
+      )}
     >
       <X aria-hidden className="size-2.5" />
     </button>

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

@@ -1,13 +1,15 @@
 'use client';
 
-import { type ReactNode, useRef, useState } from 'react';
+import { type ReactNode, useMemo, useRef, useState } from 'react';
 
 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 { useAutoFocusOnStreamEnd } from '../hooks/useAutoFocusOnStreamEnd';
 import { useChatComposer, type UseChatComposerReturn } from '../hooks/useChatComposer';
+import { useFocusOnEmptyClick } from '../hooks/useFocusOnEmptyClick';
 import { Composer, type ComposerSize } from './Composer';
 import { EmptyState } from './EmptyState';
 import { ErrorBanner } from './ErrorBanner';
@@ -82,6 +84,12 @@ export interface ChatRootProps {
   listClassName?: string;
   /** Extra className forwarded to the `<Composer>` wrapper div. */
   composerClassName?: string;
+  /**
+   * Click in the message area → focus the composer (Slack / ChatGPT / Linear).
+   * Honours selection drag, interactive elements, and touch input.
+   * @default true
+   */
+  focusOnEmptyClick?: boolean;
 }
 
 export function ChatRoot(props: ChatRootProps) {
@@ -113,11 +121,30 @@ function ChatRootShell({ className, listClassName, slots }: ChatRootShellProps)
     onSubmit: (content, attachments) => chat.sendMessage(content, attachments),
     disabled: chat.isStreaming,
   });
+  const onMessagesMouseUp = useFocusOnEmptyClick({
+    enabled: slots.focusOnEmptyClick !== false,
+  });
+  // Re-focus the composer on the streaming → idle edge. Was dropped in
+  // a previous refactor — restored here so the standard chat UX (type
+  // → send → read → keep typing without clicking) works again.
+  useAutoFocusOnStreamEnd();
   // MessageList (virtuoso) owns the scroll viewport. We talk to it
   // via the imperative handle (scrollToBottom on JumpToLatest click)
   // and via the `onAtBottomChange` callback (drives the pill).
   const listRef = useRef<MessageListHandle | null>(null);
   const [isAtBottom, setIsAtBottom] = useState(true);
+  // The id of the most-recent user-sent message. We pass it as
+  // `scrollAnchorId` to MessageList so every send re-anchors the
+  // viewport — fixes "I sent a message but the chat didn't scroll
+  // down". Recomputed lazily; the resulting id only flips when a new
+  // user message lands.
+  const lastUserMessageId = useMemo(() => {
+    const msgs = chat.messages;
+    for (let i = msgs.length - 1; i >= 0; i -= 1) {
+      if (msgs[i].role === 'user') return msgs[i].id;
+    }
+    return null;
+  }, [chat.messages]);
   const handleStartReached = chat.hasMore && !chat.isLoadingMore
     ? () => void chat.loadMore()
     : undefined;
@@ -161,7 +188,7 @@ function ChatRootShell({ className, listClassName, slots }: ChatRootShellProps)
     <div className={cn('relative flex h-full min-h-0 flex-col overflow-hidden', className)}>
       {slots.banner ?? null}
       {headerNode ?? null}
-      <div className="relative flex min-h-0 flex-1 flex-col">
+      <div className="relative flex min-h-0 flex-1 flex-col" onMouseUp={onMessagesMouseUp}>
         <ErrorBanner
           error={chat.error}
           onDismiss={chat.error ? () => chat.clearMessages() : undefined}
@@ -174,6 +201,7 @@ function ChatRootShell({ className, listClassName, slots }: ChatRootShellProps)
           className={listClassName}
           onStartReached={handleStartReached}
           onAtBottomChange={setIsAtBottom}
+          scrollAnchorId={lastUserMessageId}
         />
         <div className="pointer-events-none absolute inset-x-0 bottom-2 flex justify-center">
           {slots.jumpToLatest ?? (

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { type ReactNode, forwardRef, useEffect } from 'react';
+import { type ReactNode, forwardRef, useEffect, useRef } from 'react';
 import { Paperclip, Send, Square } from 'lucide-react';
 
 import { Button, Textarea } from '@djangocfg/ui-core/components';
@@ -104,11 +104,28 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   // a ChatProvider.
   const register = ctx?.registerComposer;
   const composerFocus = composer.focus;
+  const composerSetValue = composer.setValue;
+  const textareaRef = composer.textareaRef;
+  // `getValue` reads the live ref instead of closing over `composer.value`
+  // so we don't need to re-register on every keystroke. Same trick for
+  // `setValue` — handler identity stays stable across renders.
+  const getValueRef = useRef<() => string>(() => composer.value);
+  getValueRef.current = () => composer.value;
   useEffect(() => {
     if (!register) return;
-    register({ focus: composerFocus });
+    register({
+      focus: composerFocus,
+      moveCursorToEnd: () => {
+        const el = textareaRef.current;
+        if (!el) return;
+        const end = el.value.length;
+        el.setSelectionRange(end, end);
+      },
+      getValue: () => getValueRef.current(),
+      setValue: composerSetValue,
+    });
     return () => register(null);
-  }, [register, composerFocus]);
+  }, [register, composerFocus, composerSetValue, textareaRef]);
 
   return (
     <div

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

@@ -4,6 +4,8 @@ import { AlertCircle, RefreshCw, X } from 'lucide-react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { useChatDestructiveStyles } from '../styles';
+
 export interface ErrorBannerProps {
   error: string | null;
   onDismiss?: () => void;
@@ -12,12 +14,14 @@ export interface ErrorBannerProps {
 }
 
 export function ErrorBanner({ error, onDismiss, onRetry, className }: ErrorBannerProps) {
+  const styles = useChatDestructiveStyles();
   if (!error) return null;
   return (
     <div
       role="alert"
       className={cn(
-        'mx-2.5 my-2 flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive',
+        'mx-2.5 my-2 flex items-start gap-2 rounded-md px-3 py-2 text-xs',
+        styles.banner,
         className,
       )}
     >
@@ -27,7 +31,7 @@ export function ErrorBanner({ error, onDismiss, onRetry, className }: ErrorBanne
         <button
           type="button"
           onClick={onRetry}
-          className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 hover:bg-destructive/15"
+          className={cn('inline-flex items-center gap-1 rounded px-1.5 py-0.5', styles.hover)}
         >
           <RefreshCw aria-hidden className="size-3" /> Retry
         </button>
@@ -37,7 +41,7 @@ export function ErrorBanner({ error, onDismiss, onRetry, className }: ErrorBanne
           type="button"
           aria-label="Dismiss"
           onClick={onDismiss}
-          className="rounded p-0.5 hover:bg-destructive/15"
+          className={cn('rounded p-0.5', styles.hover)}
         >
           <X aria-hidden className="size-3" />
         </button>

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

@@ -5,6 +5,7 @@ import { Copy, Pencil, RefreshCw, Trash } from 'lucide-react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { useChatDestructiveStyles } from '../styles';
 import type { ChatRole } from '../types';
 
 export interface MessageActionsProps {
@@ -64,6 +65,7 @@ const ActionButton = memo(function ActionButton({
   icon: typeof Copy;
   destructive?: boolean;
 }) {
+  const styles = useChatDestructiveStyles();
   return (
     <button
       type="button"
@@ -71,7 +73,7 @@ const ActionButton = memo(function ActionButton({
       aria-label={label}
       className={cn(
         'rounded p-1 text-muted-foreground hover:bg-accent hover:text-foreground',
-        destructive && 'hover:bg-destructive/15 hover:text-destructive',
+        destructive && cn(styles.hover, 'hover:text-destructive'),
       )}
     >
       <Icon aria-hidden className="size-3" />

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

@@ -16,6 +16,7 @@ import type {
 } from '../types';
 import { resolvePersona, deriveInitials } from '../core/persona';
 import { useChatContextOptional } from '../context';
+import { useChatBubbleStyles } from '../styles';
 import { StreamingIndicator } from './StreamingIndicator';
 import { Sources } from './Sources';
 import { ToolCalls } from './ToolCalls';
@@ -110,6 +111,10 @@ const MessageBubbleInner = ({
   const isUser = isUserProp ?? message.role === 'user';
   const isStreaming = !!message.isStreaming;
   const isErr = !!message.isError;
+  const { surface: bubbleSurface } = useChatBubbleStyles(
+    isUser ? 'user' : 'assistant',
+    isErr,
+  );
 
   const ctx = useChatContextOptional();
   const persona = resolvePersona(
@@ -174,11 +179,7 @@ const MessageBubbleInner = ({
         <div
           className={cn(
             'inline-block max-w-full rounded-2xl px-3.5 py-2 text-sm',
-            isUser
-              ? 'bg-primary text-primary-foreground rounded-tr-md'
-              : isErr
-                ? 'bg-destructive/10 text-destructive rounded-tl-md border border-destructive/30'
-                : 'bg-muted text-foreground rounded-tl-md',
+            bubbleSurface,
           )}
         >
           {isStreaming && message.toolActivity ? (

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

@@ -9,6 +9,7 @@ import {
   useImperativeHandle,
   useMemo,
   useRef,
+  useState,
 } from 'react';
 import { Virtuoso, type VirtuosoHandle } from 'react-virtuoso';
 
@@ -71,6 +72,20 @@ export interface MessageListProps {
    * `!isAtBottom`. Plan64.
    */
   onAtBottomChange?: (isAtBottom: boolean) => void;
+  /**
+   * Pixel distance from the bottom that still counts as "at bottom".
+   * Default 120 — generous enough that mid-message users keep getting
+   * sticky-followed (matches ChatGPT / Slack feel) while still letting
+   * a deliberate scroll-up break the lock. Plan11.
+   */
+  atBottomThreshold?: number;
+  /**
+   * Force-scroll to the bottom when this id changes. Wire to the id of
+   * the most-recently-sent user message: every send re-anchors the
+   * viewport so users always see their own bubble + the incoming
+   * reply, even if they were scrolled up. Plan11.
+   */
+  scrollAnchorId?: string | number | null;
 }
 
 export interface MessageListHandle {
@@ -90,6 +105,8 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
     noVirtualize = false,
     defaultItemHeight: _deprecatedDefaultItemHeight,
     onAtBottomChange,
+    atBottomThreshold = 120,
+    scrollAnchorId,
   },
   ref,
 ) {
@@ -100,6 +117,22 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
   const { copyToClipboard } = useCopy();
 
   const virtuosoRef = useRef<VirtuosoHandle | null>(null);
+  // Virtuoso's `atBottomStateChange` only fires when the list is
+  // scrollable AND the user actually scrolls. With ≤3 short bubbles the
+  // total height stays below the viewport, virtuoso never fires "at
+  // bottom", and the `<JumpToLatest>` pill stays stuck. Track the
+  // scroller directly: when content fits, force `atBottom=true`.
+  const scrollerRef = useRef<HTMLElement | Window | null>(null);
+  const [isScrollable, setIsScrollable] = useState(false);
+  const lastReportedAtBottomRef = useRef<boolean | null>(null);
+  const reportAtBottom = useCallback(
+    (value: boolean) => {
+      if (lastReportedAtBottomRef.current === value) return;
+      lastReportedAtBottomRef.current = value;
+      onAtBottomChange?.(value);
+    },
+    [onAtBottomChange],
+  );
   // Track whether we've already landed on the bottom for the initial
   // history. Virtuoso's `initialTopMostItemIndex` only fires on first
   // mount and uses the `messages` length at that moment. Chats almost
@@ -162,6 +195,51 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
     return () => cancelAnimationFrame(id);
   }, [messages.length]);
 
+  // Force-scroll to bottom whenever the consumer bumps `scrollAnchorId`
+  // (typically the id of the latest user-sent message). Two rAFs so
+  // Virtuoso has measured the freshly-pushed bubble before we land,
+  // otherwise the call lands on the previous height and clips the new
+  // message under the composer. The initial-mount effect above handles
+  // first paint, so we skip until it has run.
+  useEffect(() => {
+    if (scrollAnchorId == null) return;
+    if (!didInitialScrollRef.current) return;
+    let raf1 = 0;
+    let raf2 = 0;
+    raf1 = requestAnimationFrame(() => {
+      raf2 = requestAnimationFrame(() => {
+        virtuosoRef.current?.scrollToIndex({
+          index: 'LAST',
+          align: 'end',
+          behavior: 'smooth',
+        });
+      });
+    });
+    return () => {
+      cancelAnimationFrame(raf1);
+      cancelAnimationFrame(raf2);
+    };
+  }, [scrollAnchorId]);
+
+  // Watch the scroll container: when content fits (scrollHeight ≤ clientHeight)
+  // there's nothing to scroll, the user is by definition "at bottom", and the
+  // Jump-to-latest pill must stay hidden regardless of what virtuoso reports.
+  useEffect(() => {
+    const el = scrollerRef.current;
+    if (!el || el === window || !(el instanceof HTMLElement)) return;
+
+    const probe = () => {
+      const scrollable = el.scrollHeight > el.clientHeight + 1;
+      setIsScrollable(scrollable);
+      if (!scrollable) reportAtBottom(true);
+    };
+
+    probe();
+    const ro = new ResizeObserver(probe);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [reportAtBottom, messages.length]);
+
   // Virtuoso may invoke `computeItemKey` for an index briefly out of
   // sync with `data` during fast state churn (streaming chunks +
   // Strict Mode double-mount). `m` arrives undefined in that window.
@@ -265,8 +343,16 @@ export const MessageList = forwardRef<MessageListHandle, MessageListProps>(funct
       // extra bubbles re-rendering at 60Hz during a stream. Default
       // keeps the working set tight.
       initialTopMostItemIndex={messages.length > 0 ? messages.length - 1 : 0}
+      atBottomThreshold={atBottomThreshold}
       followOutput={(isAtBottom) => (isAtBottom ? 'auto' : false)}
-      atBottomStateChange={onAtBottomChange}
+      scrollerRef={(el) => {
+        scrollerRef.current = el;
+      }}
+      atBottomStateChange={(atBottom) => {
+        // Force `true` when the list isn't scrollable — virtuoso's signal
+        // can stall in `false` on short transcripts (no scroll events fire).
+        reportAtBottom(!isScrollable ? true : atBottom);
+      }}
       startReached={startReachedHandler}
       // Spinner while older history is loading. Rendering it as the
       // Header keeps it inside the virtualized scroll, so it doesn't

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { type ReactNode, useEffect, useRef, useState } from 'react';
+import { memo, type ReactNode, useEffect, useRef, useState } from 'react';
 import { ChevronDown, ChevronRight, Loader2 } from 'lucide-react';
 
 import { cn } from '@djangocfg/ui-core/lib';
@@ -93,7 +93,7 @@ interface ItemProps {
   renderPayload?: ToolCallsProps['renderPayload'];
 }
 
-function ToolCallItem({
+const ToolCallItem = memo(function ToolCallItem({
   call,
   defaultExpanded,
   expandWhileStreaming,
@@ -172,7 +172,25 @@ function ToolCallItem({
       ) : null}
     </div>
   );
-}
+}, (prev, next) => {
+  // Re-render only when the call's observable surface actually changed.
+  // Render-prop callbacks are accepted as referentially stable by callers —
+  // they live in toolCallsProps which itself rarely changes.
+  const a = prev.call;
+  const b = next.call;
+  return (
+    a.id === b.id &&
+    a.status === b.status &&
+    a.output === b.output &&
+    a.streamingText === b.streamingText &&
+    prev.defaultExpanded === next.defaultExpanded &&
+    prev.expandWhileStreaming === next.expandWhileStreaming &&
+    prev.renderInput === next.renderInput &&
+    prev.renderOutput === next.renderOutput &&
+    prev.renderStreaming === next.renderStreaming &&
+    prev.renderPayload === next.renderPayload
+  );
+});
 
 function DefaultPayload({ value, kind }: { value: unknown; kind: ToolPayloadKind }) {
   const isStreamingOrString = kind === 'streaming' || typeof value === 'string';

package/src/tools/Chat/context/ChatProvider.tsx

@@ -19,11 +19,29 @@ import { useChatLayout, type UseChatLayoutReturn } from '../hooks/useChatLayout'
 import { useChatAudio } from '../hooks/useChatAudio';
 import type { ChatAudioConfig, UseChatAudioReturn } from '../core/audio/types';
 
-/** Minimal handle a composer (built-in or custom) registers so other
- *  parts of the chat tree can drive it imperatively — `.focus()` is
- *  enough today; expand the surface as new needs arise. */
+/** Imperative handle a composer (built-in or custom) registers so
+ *  other parts of the chat tree can drive it without prop-drilling a
+ *  ref. `focus()` is the baseline; the rest is optional so non-textarea
+ *  hosts can keep returning `{ focus }` only.
+ *
+ *  Implemented by:
+ *   - built-in `<Composer>` — backed by `useChatComposer.textareaRef`.
+ *   - `@djangocfg/ui-tools/markdown-editor` — backed by the TipTap
+ *     editor (`editor.commands.focus('end')`).
+ *  Consumed by `VoiceComposerSlot` for the focus / move-caret behaviour
+ *  during live dictation.
+ */
 export interface ComposerHandle {
   focus: () => void;
+  /** Move the caret to the very end of the input. */
+  moveCursorToEnd?: () => void;
+  /** Read the current draft text. Needed by voice dictation to anchor
+   *  partial transcripts onto the user's already-typed prefix. */
+  getValue?: () => string;
+  /** Replace the current draft text. Voice dictation uses this to push
+   *  interim + final transcripts into the composer without owning a
+   *  controlled binding. */
+  setValue?: (value: string) => void;
 }
 
 export interface ChatContextValue extends UseChatReturn {

package/src/tools/Chat/core/audio/audioBus.ts

@@ -1,172 +1,19 @@
-// Per-provider audio bus.
-//
-// Owns the actual `<audio>` elements (one per (bus × event)) plus the global
-// "unlocked" flag. Pure module / class — no React. The hook layer is in
-// `hooks/useChatAudio.ts`.
-//
-// Pitfalls this addresses (lessons from AudioPlayer/audio):
-//  - Safari needs a user-gesture transaction to unlock playback. We pre-allocate
-//    an `<audio>` per event and call `play()` on each during the unlock event.
-//  - Multiple `play()` calls in quick succession on the same element: we clone
-//    a fresh `HTMLAudioElement` from the cache for each fire so they don't
-//    cancel each other (cheap — same `src` reuses the HTTP cache).
-//  - SSR safety: ALL DOM access is gated; the bus is only constructed in
-//    a `'use client'` component (the provider).
-//  - `play()` returns a Promise; uncaught rejections show up as warnings on
-//    Chrome. We attach `.catch()` everywhere.
-//  - Module unload cleanup: `dispose()` revokes blob URLs, drops listeners,
-//    and clears the cache.
+// Thin re-export — the audio bus implementation lives in `@djangocfg/ui-core/hooks`.
+// Kept as a re-export so existing imports keep working.
+
+import { createSoundBus, type SoundBus } from '@djangocfg/ui-core/hooks';
 
 import type { ChatAudioEvent, ChatAudioSounds } from './types';
 
-interface BusOptions {
+export type ChatAudioBus = SoundBus<ChatAudioEvent>;
+
+export function createAudioBus(options: {
   sounds: ChatAudioSounds;
-  /** Returns the current master volume 0..1. Read on each play. */
   getVolume: () => number;
-  /** Returns master mute. Read on each play. */
   getMuted: () => boolean;
-  /** Per-event predicate. */
   isEnabled: (event: ChatAudioEvent) => boolean;
+}): ChatAudioBus {
+  return createSoundBus<ChatAudioEvent>(options);
 }
 
-export interface ChatAudioBus {
-  play: (event: ChatAudioEvent) => void;
-  preload: (event: ChatAudioEvent) => void;
-  unlock: () => void;
-  isUnlocked: () => boolean;
-  /** Lets the provider re-publish unlock changes to React via a listener. */
-  subscribeUnlock: (cb: (unlocked: boolean) => void) => () => void;
-  /** Hot-swap the sounds map without re-creating the bus. */
-  setSounds: (sounds: ChatAudioSounds) => void;
-  dispose: () => void;
-}
-
-// One unlock state per tab — first gesture inside ANY <ChatProvider> unlocks
-// every bus. AudioPlayer follows the same "global per tab" rule for its
-// AudioContext (ADR-004).
-let unlocked = false;
-const unlockListeners = new Set<(v: boolean) => void>();
-
-function setUnlocked(value: boolean) {
-  if (unlocked === value) return;
-  unlocked = value;
-  for (const cb of unlockListeners) cb(value);
-}
-
-export function _resetUnlockForTesting(): void {
-  unlocked = false;
-  unlockListeners.clear();
-}
-
-export function createAudioBus(options: BusOptions): ChatAudioBus {
-  // SSR guard.
-  if (typeof window === 'undefined') {
-    return noopBus();
-  }
-
-  let sounds = options.sounds;
-  /** Cache of "template" audio elements per URL — reused across plays. */
-  const cache = new Map<string, HTMLAudioElement>();
-
-  const getOrCreate = (url: string): HTMLAudioElement => {
-    const hit = cache.get(url);
-    if (hit) return hit;
-    const el = new Audio(url);
-    el.preload = 'auto';
-    el.crossOrigin = 'anonymous';
-    cache.set(url, el);
-    return el;
-  };
-
-  const resolveUrl = (event: ChatAudioEvent): string | null => {
-    const v = sounds[event];
-    if (!v) return null;
-    return v;
-  };
-
-  const play = (event: ChatAudioEvent) => {
-    if (options.getMuted()) return;
-    if (!options.isEnabled(event)) return;
-    const url = resolveUrl(event);
-    if (!url) return;
-
-    // Use the cached template just for HTTP cache warming; clone so two rapid
-    // events don't cut each other off on the same element.
-    getOrCreate(url);
-    const fresh = new Audio(url);
-    fresh.preload = 'auto';
-    fresh.volume = options.getVolume();
-    // Fire-and-forget; the promise rejects when autoplay is blocked.
-    const p = fresh.play();
-    if (p && typeof p.catch === 'function') {
-      p.catch(() => {
-        // Browser blocked playback (no gesture yet) — ignore.
-      });
-    }
-  };
-
-  const preload = (event: ChatAudioEvent) => {
-    const url = resolveUrl(event);
-    if (!url) return;
-    const el = getOrCreate(url);
-    // Trigger a low-priority load.
-    try {
-      el.load();
-    } catch {
-      // ignore
-    }
-  };
-
-  const unlock = () => {
-    if (unlocked) return;
-    // Play (silently) every cached element in one user-gesture transaction so
-    // Safari/iOS lifts the autoplay block for the whole bus at once.
-    for (const el of cache.values()) {
-      const wasMuted = el.muted;
-      el.muted = true;
-      const p = el.play();
-      if (p && typeof p.then === 'function') {
-        p.then(() => {
-          el.pause();
-          el.currentTime = 0;
-          el.muted = wasMuted;
-        }).catch(() => {
-          el.muted = wasMuted;
-        });
-      } else {
-        el.pause();
-        el.muted = wasMuted;
-      }
-    }
-    setUnlocked(true);
-  };
-
-  return {
-    play,
-    preload,
-    unlock,
-    isUnlocked: () => unlocked,
-    subscribeUnlock(cb) {
-      unlockListeners.add(cb);
-      return () => unlockListeners.delete(cb);
-    },
-    setSounds(next) {
-      sounds = next;
-    },
-    dispose() {
-      cache.clear();
-    },
-  };
-}
-
-function noopBus(): ChatAudioBus {
-  return {
-    play: () => undefined,
-    preload: () => undefined,
-    unlock: () => undefined,
-    isUnlocked: () => false,
-    subscribeUnlock: () => () => undefined,
-    setSounds: () => undefined,
-    dispose: () => undefined,
-  };
-}
+export { _resetUnlockForTesting } from '@djangocfg/ui-core/hooks';

package/src/tools/Chat/core/audio/defaults.ts

@@ -0,0 +1,43 @@
+/**
+ * Built-in chat notification sounds.
+ *
+ * Bundled into the JS at build time as base64 data URLs (`tsup.config.ts`
+ * loader: `.mp3 → dataurl`). Total ≈ 136KB, gzipped ≈ 130KB — added to
+ * the lazy Chat tool so hosts get notification sounds with zero setup.
+ *
+ * Source files live in `./sounds/`. Re-encode via ffmpeg if you tweak:
+ *
+ *   ffmpeg -i in.mp3 -ac 2 -ar 44100 -b:a 128k -af 'atrim=0:1.4,afade=t=out:st=1.22:d=0.18' out.mp3
+ */
+
+import sent from './sounds/sent.mp3';
+import received from './sounds/received.mp3';
+import start from './sounds/start.mp3';
+import errorSound from './sounds/error.mp3';
+import mention from './sounds/mention.mp3';
+import notification from './sounds/notification.mp3';
+
+import type { ChatAudioSounds } from './types';
+
+/**
+ * Default chat notification sounds. Pass to `useChatAudio` (or spread
+ * into a custom map) so hosts don't have to ship assets themselves.
+ *
+ * @example
+ * ```tsx
+ * const audio = useChatAudio({ sounds: DEFAULT_CHAT_SOUNDS });
+ *
+ * // Override one event:
+ * const audio = useChatAudio({
+ *   sounds: { ...DEFAULT_CHAT_SOUNDS, mention: '/custom-mention.mp3' },
+ * });
+ * ```
+ */
+export const DEFAULT_CHAT_SOUNDS: ChatAudioSounds = {
+  messageSent: sent,
+  messageReceived: received,
+  streamStart: start,
+  error: errorSound,
+  mention,
+  notification,
+};