@djangocfg/ui-tools 2.1.409 → 2.1.411

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

@@ -15,6 +15,7 @@ import type { ChatConfig, ChatLabels, ChatTransport } from '../types';
 import { DEFAULT_LABELS } from '../types';
 import type { BlockRegistry } from '../messages/blocks';
 
+import { setBridgeSender } from '../../../lib/browser-bridge';
 import { useChat, type UseChatReturn } from '../hooks/useChat';
 import { useChatLayout, type UseChatLayoutReturn } from '../hooks/useChatLayout';
 import { useChatAudio } from '../hooks/useChatAudio';
@@ -212,14 +213,28 @@ export function ChatProvider({
     };
   }, [audioApi]);
 
+  // Publish `sendMessage` to the browser bridge so the dev-only
+  // `window.__chatBridge.sendMessage(...)` can drive the chat from the
+  // console. `setBridgeSender` no-ops outside dev; cleared on unmount.
+  useEffect(() => {
+    setBridgeSender(chat.sendMessage);
+    return () => setBridgeSender(null);
+  }, [chat.sendMessage]);
+
   const labels = useMemo<ChatLabels>(
     () => ({ ...DEFAULT_LABELS, ...(config.labels ?? {}) }),
     [config.labels],
   );
 
+  // True when audio is wired up — drives the auto-injected mute toggle.
+  // `audio={{}}` counts: `useChatAudio` falls back to the bundled
+  // DEFAULT_CHAT_SOUNDS, so an empty config still has sounds to mute.
+  // Only an absent `audio` prop or `silenced` means "nothing to mute".
   const hasAudio = useMemo<boolean>(() => {
-    const sounds = audio?.sounds;
-    if (!sounds) return false;
+    if (!audio) return false;
+    if (audio.silenced) return false;
+    const sounds = audio.sounds;
+    if (sounds === undefined) return true;
     return Object.values(sounds).some(
       (v) => typeof v === 'string' && v.length > 0,
     );

package/src/tools/Chat/core/logger.ts

@@ -22,7 +22,13 @@ import { consola, type ConsolaInstance } from 'consola';
 
 import { isDev } from '@djangocfg/ui-core/lib';
 
-export type ChatLogScope = 'bootstrap' | 'transport' | 'stream' | 'lifecycle' | 'tools' | 'error';
+export type ChatLogScope =
+  | 'bootstrap'
+  | 'transport'
+  | 'stream'
+  | 'lifecycle'
+  | 'tools'
+  | 'error';
 
 export interface ChatLogger {
   bootstrap: ConsolaInstance;
@@ -35,7 +41,14 @@ export interface ChatLogger {
   enabled: boolean;
 }
 
-const SCOPES: ChatLogScope[] = ['bootstrap', 'transport', 'stream', 'lifecycle', 'tools', 'error'];
+const SCOPES: ChatLogScope[] = [
+  'bootstrap',
+  'transport',
+  'stream',
+  'lifecycle',
+  'tools',
+  'error',
+];
 
 /** Module-level cache so all hooks/components share the same logger instance per `enabled` mode. */
 const cache = new Map<boolean, ChatLogger>();

package/src/tools/Chat/index.ts

@@ -18,12 +18,24 @@ export * from './messages';
 export * from './composer';
 export * from './shell';
 
-// Highlight — AI-driven `point` directives (spotlight + focus overlay).
+// Bridge — AI-driven `point` directives (spotlight + focus overlay).
 export {
   HighlightOverlay,
   SpotlightCanvas,
   useHighlightTargets,
   resolveRefs,
+  useChatDirectives,
+  pushDirectives,
+  clearDirectives,
+  parseDirectives,
+  installChatBridge,
+  registerBridgeCommand,
+  getBridgeCommand,
+  setBridgeResolver,
+  setBridgeSender,
+  type BridgeCommand,
+  type BridgeSender,
+  type ChatBridge,
   type HighlightOverlayProps,
   type SpotlightCanvasProps,
   type RefResolver,
@@ -31,7 +43,27 @@ export {
   type HighlightTarget,
   type SpotlightRect,
   type CSTRefId,
-} from './highlight';
+} from '../../lib/browser-bridge';
+
+// Page-context snapshot — capture engine + React surface. The host
+// wires `getChatMetadata` into `getDynamicMetadata` so the assistant
+// receives a snapshot of the page the user is looking at.
+export {
+  PageSnapshotProvider,
+  usePageSnapshot,
+  usePageSnapshotToggle,
+  PageSnapshotChip,
+  PageSnapshotPreview,
+  PageSnapshotEngine,
+  type PageSnapshotProviderProps,
+  type PageSnapshotContextValue,
+  type PageSnapshotToggle,
+  type PageSnapshotChipProps,
+  type PageSnapshotPreviewProps,
+  type CaptureEngineOptions,
+  type CaptureResult,
+  type PageContextPayload,
+} from '../../lib/page-snapshot';
 
 // Launcher — FAB + Dock + Header + Greeting composition (heavy, sync).
 export {

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

@@ -7,6 +7,7 @@ import { Portal } from '@djangocfg/ui-core/components';
 import { useIsMobile, useIsTabletOrBelow } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { Z_INDEX } from '../constants';
 import { ChatHeader } from './header';
 import { useChatPresence } from './useChatPresence';
 import type { ChatFABPosition } from './ChatFAB';
@@ -52,7 +53,11 @@ export interface ChatDockProps {
   offset?: { horizontal?: number; vertical?: number };
   /** Transition duration in ms — should match CSS animation. @default 200 */
   exitDurationMs?: number;
-  /** z-index. @default 10000 */
+  /**
+   * z-index. @default 100 — page furniture: above page content but below
+   * every ui-core overlay (sheet/drawer/dialog/popover), so a dialog always
+   * covers the chat, including one opened from inside the chat itself.
+   */
   zIndex?: number;
   /** Accessible dialog label. */
   ariaLabel?: string;
@@ -118,7 +123,7 @@ export function ChatDock({
   position = 'bottom-right',
   offset,
   exitDurationMs = 200,
-  zIndex = 10000,
+  zIndex = Z_INDEX.dock,
   ariaLabel,
   className,
   mobileFullscreen = true,
@@ -236,7 +241,12 @@ export function ChatDock({
       <div
         role="dialog"
         aria-label={ariaLabel ?? (typeof title === 'string' ? title : 'Chat')}
-        aria-hidden={phase === 'leaving'}
+        // While leaving, mark the panel `inert` rather than `aria-hidden`.
+        // `aria-hidden` on an ancestor of the still-focused element (e.g.
+        // the close button just clicked, or the composer) trips the
+        // browser's "Blocked aria-hidden ... descendant retained focus"
+        // warning. `inert` hides it from the a11y tree AND blanks focus.
+        inert={phase === 'leaving' ? true : undefined}
         className={cn(
           'bg-popover text-popover-foreground border-border',
           'flex flex-col overflow-hidden shadow-2xl',

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

@@ -6,6 +6,8 @@ import type { CSSProperties, ReactNode } from 'react';
 import { useIsPhone, useIsTabletOrBelow } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { Z_INDEX } from '../constants';
+
 export type ChatFABPosition =
   | 'bottom-right'
   | 'bottom-left'
@@ -30,7 +32,7 @@ export interface ChatFABProps {
   position?: ChatFABPosition;
   /** Pixel offset from screen edges. @default 24 */
   offset?: number;
-  /** z-index for the button. @default 9999 */
+  /** z-index for the button. @default 99 — just below the open dock. */
   zIndex?: number;
   /** Show a small attention dot (unread / new). */
   pulse?: boolean;
@@ -145,7 +147,7 @@ export function ChatFAB({
   size = 'responsive',
   position = 'bottom-right',
   offset = 24,
-  zIndex = 9999,
+  zIndex = Z_INDEX.companion,
   pulse = false,
   badge,
   tooltip,

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

@@ -6,6 +6,7 @@ import type { CSSProperties, ReactNode } from 'react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { Z_INDEX } from '../constants';
 import { useChatPresence } from './useChatPresence';
 import type { ChatFABPosition } from './ChatFAB';
 
@@ -32,7 +33,7 @@ export interface ChatGreetingProps {
   fabClearance?: number;
   /** Delay before the greeting appears, in ms. @default 1500 */
   delayMs?: number;
-  /** z-index. @default 9998 (just below the default FAB at 9999). */
+  /** z-index. @default 99 — companion tier, just below the open dock. */
   zIndex?: number;
   /** Override classes on the bubble. */
   className?: string;
@@ -110,7 +111,7 @@ export function ChatGreeting({
   fabOffset = 24,
   fabClearance = 96,
   delayMs = 1500,
-  zIndex = 9998,
+  zIndex = Z_INDEX.companion,
   className,
   style,
   avatar,

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

@@ -7,6 +7,7 @@ import { useHotkey } from '@djangocfg/ui-core/hooks';
 
 import { ChatProvider, useChatContextOptional } from '../context';
 import type { ChatAudioConfig } from '../core/audio/types';
+import { useChatDockPrefs } from '../hooks/useChatDockPrefs';
 import type {
   ChatConfig,
   ChatMessage,
@@ -275,10 +276,21 @@ export function ChatLauncher({
     ? { ...fab, badge: 1 }
     : fab;
 
-  // 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.
+  // Reused below for the ambient-provider branch; read up here so
+  // `audioConfigured` can fall back to the ambient provider's audio.
+  const ambient = useChatContextOptional();
+
+  // Whether audio wires up any actual sound. Used as the default for
+  // `headerSlots.audio` — no point auto-injecting the toggle when
+  // there's nothing to mute.
+  //
+  // When the launcher is rendered inside an existing `<ChatProvider>`
+  // (the host owns the provider), audio was configured there, not via
+  // this component's `audio` prop — so honor the ambient provider's
+  // `hasAudio` too. Without this the dock-header mute toggle silently
+  // never appears for host-owned-provider setups.
   const audioConfigured = useMemo<boolean>(() => {
+    if (ambient?.hasAudio) return true;
     if (!audio) return false;
     if (audio.silenced) return false;
     const sounds = audio.sounds;
@@ -288,13 +300,25 @@ export function ChatLauncher({
     return Object.values(sounds).some(
       (v) => typeof v === 'string' && v.length > 0,
     );
-  }, [audio]);
+  }, [audio, ambient?.hasAudio]);
 
   const resolvedSlots = useMemo(
     () => resolveHeaderSlots(headerSlots, audioConfigured),
     [headerSlots, audioConfigured],
   );
 
+  // Single source of truth for dock layout prefs. The mode-toggle slot
+  // and `<ChatDock>` live in separate subtrees — if each called
+  // `useChatDockPrefs` independently they'd hold isolated `useState`
+  // (no same-tab cross-instance sync), so the toggle would flip
+  // localStorage but never re-render the dock. Owning the hook here and
+  // threading both the values and the toggle down keeps them in sync.
+  const modeToggleSlot = resolvedSlots.modeToggle;
+  const dockPrefs = useChatDockPrefs({
+    storageKey: modeToggleSlot?.persistAs,
+    defaults: modeToggleSlot?.defaults,
+  });
+
   const hasAnySlot =
     resolvedSlots.audio ||
     resolvedSlots.modeToggle !== null ||
@@ -302,8 +326,6 @@ export function ChatLauncher({
     resolvedSlots.reset !== null ||
     resolvedSlots.custom !== null;
 
-  const ambient = useChatContextOptional();
-
   const body = (
     <>
       <ChatFAB {...resolvedFab} onClick={toggleOpen} />
@@ -331,10 +353,23 @@ export function ChatLauncher({
       ) : null}
       <ChatDock
         {...dock}
+        // When the mode-toggle slot is active, dock prefs are the source
+        // of truth so the header toggle actually re-docks the panel.
+        // Otherwise fall back to the static `dock` props. `sideWidth`
+        // only governs side mode — leave popover width to `dock.width`.
+        mode={modeToggleSlot ? dockPrefs.mode : dock?.mode}
+        side={modeToggleSlot ? dockPrefs.side : dock?.side}
+        width={
+          modeToggleSlot && dockPrefs.mode === 'side'
+            ? dockPrefs.sideWidth
+            : dock?.width
+        }
         open={open}
         onClose={() => setOpen(false)}
         headerActions={
-          hasAnySlot ? <HeaderSlotsRenderer slots={resolvedSlots} /> : undefined
+          hasAnySlot ? (
+            <HeaderSlotsRenderer slots={resolvedSlots} dockPrefs={dockPrefs} />
+          ) : undefined
         }
       >
         <div ref={dockContentRef} className="flex h-full min-h-0 min-w-0 flex-col">

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

@@ -6,6 +6,7 @@ import type { CSSProperties, ReactNode } from 'react';
 import { Avatar, AvatarFallback, AvatarImage } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { Z_INDEX } from '../constants';
 import type { ChatMessage, ChatPersona } from '../types';
 import type { ChatFABPosition } from './ChatFAB';
 import { useChatPresence } from './useChatPresence';
@@ -27,7 +28,7 @@ export interface ChatUnreadPreviewProps {
   fabClearance?: number;
   /** Lines of body text before ellipsis. @default 2 */
   truncate?: number;
-  /** z-index. @default 9998 */
+  /** z-index. @default 99 — companion tier, just below the open dock. */
   zIndex?: number;
   /** Render in-place (stories / previews). @default false */
   inline?: boolean;
@@ -100,7 +101,7 @@ export function ChatUnreadPreview({
   fabOffset = 24,
   fabClearance = 96,
   truncate = 2,
-  zIndex = 9998,
+  zIndex = Z_INDEX.companion,
   inline = false,
   className,
   style,

package/src/tools/Chat/launcher/header/ChatHeader.tsx

@@ -79,6 +79,8 @@ export function ChatHeader({
                     <X className="h-4 w-4" />
                   </Button>
                 </TooltipTrigger>
+                {/* Tooltip portals to <body> in ui-core's anchored-overlay
+                    tier, already above the dock — no override needed. */}
                 <TooltipContent side="bottom">{closeLabel}</TooltipContent>
               </Tooltip>
             </TooltipProvider>

package/src/tools/Chat/launcher/header/ChatHeaderActionButton.tsx

@@ -110,6 +110,8 @@ export const ChatHeaderActionButton = forwardRef<HTMLButtonElement, ChatHeaderAc
       <TooltipProvider delayDuration={300}>
         <Tooltip>
           <TooltipTrigger asChild>{button}</TooltipTrigger>
+          {/* Tooltip portals to <body> in ui-core's anchored-overlay tier,
+              already above the dock — no z-index override needed. */}
           <TooltipContent side="bottom">{tooltipLabel}</TooltipContent>
         </Tooltip>
       </TooltipProvider>

package/src/tools/Chat/launcher/header/ChatHeaderLanguageButton.tsx

@@ -99,9 +99,9 @@ export function ChatHeaderLanguageButton({
         );
       }}
       // Popover width follows the trigger by default (28px → narrow).
-      // Force a usable width and bump z-index above ChatDock (z-10000).
+      // Force a usable width; the popover already portals into ui-core's
+      // anchored-overlay tier, above the dock — no z-index override needed.
       contentClassName="w-[280px]"
-      contentStyle={{ zIndex: 10001 }}
       // Custom row: country flag + native language label + BCP-47 tag.
       // ui-core Combobox default rendering only shows label/description
       // — feeding the flag here keeps every list row instantly

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

@@ -3,7 +3,7 @@
 import { Fragment } from 'react';
 
 import { useChatContext } from '../../context';
-import { useChatDockPrefs } from '../../hooks/useChatDockPrefs';
+import type { UseChatDockPrefsReturn } from '../../hooks/useChatDockPrefs';
 
 import { ChatHeaderAudioToggle } from './ChatHeaderAudioToggle';
 import { ChatHeaderLanguageButton } from './ChatHeaderLanguageButton';
@@ -13,6 +13,13 @@ import type { ResolvedChatHeaderSlots } from '../types';
 
 export interface HeaderSlotsRendererProps {
   slots: ResolvedChatHeaderSlots;
+  /**
+   * Shared dock-prefs instance owned by `<ChatLauncher>`. The mode
+   * toggle MUST use the same instance the dock reads from — a separate
+   * `useChatDockPrefs` call would hold isolated state and the toggle
+   * would no-op.
+   */
+  dockPrefs: UseChatDockPrefsReturn;
 }
 
 /**
@@ -22,7 +29,7 @@ export interface HeaderSlotsRendererProps {
  * Order (left → right, before the close icon):
  *   custom · languagePicker · modeToggle · audio · reset
  */
-export function HeaderSlotsRenderer({ slots }: HeaderSlotsRendererProps) {
+export function HeaderSlotsRenderer({ slots, dockPrefs }: HeaderSlotsRendererProps) {
   const ctx = useChatContext();
   return (
     <>
@@ -34,7 +41,9 @@ export function HeaderSlotsRenderer({ slots }: HeaderSlotsRendererProps) {
           hideFallbackIcon={slots.languagePicker.hideFallbackIcon}
         />
       ) : null}
-      {slots.modeToggle ? <ModeToggleSlot slot={slots.modeToggle} /> : null}
+      {slots.modeToggle ? (
+        <ModeToggleSlot slot={slots.modeToggle} dockPrefs={dockPrefs} />
+      ) : null}
       {slots.audio && !ctx.audio.isSilent ? (
         <ChatHeaderAudioToggle
           muted={ctx.audio.muted}
@@ -48,17 +57,15 @@ export function HeaderSlotsRenderer({ slots }: HeaderSlotsRendererProps) {
 
 function ModeToggleSlot({
   slot,
+  dockPrefs,
 }: {
   slot: NonNullable<ResolvedChatHeaderSlots['modeToggle']>;
+  dockPrefs: UseChatDockPrefsReturn;
 }) {
-  const prefs = useChatDockPrefs({
-    storageKey: slot.persistAs,
-    defaults: slot.defaults,
-  });
   return (
     <ChatHeaderModeToggle
-      mode={prefs.mode}
-      onToggle={prefs.toggleMode}
+      mode={dockPrefs.mode}
+      onToggle={dockPrefs.toggleMode}
       forceVisible={slot.forceVisible ?? true}
       expandLabel={slot.expandLabel}
       collapseLabel={slot.collapseLabel}

package/src/tools/Chat/lazy.tsx

@@ -75,12 +75,24 @@ export * from './composer';
 export * from './shell';
 export * from './launcher';
 
-// Highlight — AI-driven `point` directives (lightweight, no heavy deps).
+// Bridge — AI-driven `point` directives (lightweight, no heavy deps).
 export {
   HighlightOverlay,
   SpotlightCanvas,
   useHighlightTargets,
   resolveRefs,
+  useChatDirectives,
+  pushDirectives,
+  clearDirectives,
+  parseDirectives,
+  installChatBridge,
+  registerBridgeCommand,
+  getBridgeCommand,
+  setBridgeResolver,
+  setBridgeSender,
+  type BridgeCommand,
+  type BridgeSender,
+  type ChatBridge,
   type HighlightOverlayProps,
   type SpotlightCanvasProps,
   type RefResolver,
@@ -88,4 +100,24 @@ export {
   type HighlightTarget,
   type SpotlightRect,
   type CSTRefId,
-} from './highlight';
+} from '../../lib/browser-bridge';
+
+// Page-context snapshot — capture engine + React surface. The host
+// wires `getChatMetadata` into `getDynamicMetadata` so the assistant
+// receives a snapshot of the page the user is looking at.
+export {
+  PageSnapshotProvider,
+  usePageSnapshot,
+  usePageSnapshotToggle,
+  PageSnapshotChip,
+  PageSnapshotPreview,
+  PageSnapshotEngine,
+  type PageSnapshotProviderProps,
+  type PageSnapshotContextValue,
+  type PageSnapshotToggle,
+  type PageSnapshotChipProps,
+  type PageSnapshotPreviewProps,
+  type CaptureEngineOptions,
+  type CaptureResult,
+  type PageContextPayload,
+} from '../../lib/page-snapshot';

package/src/tools/Chat/public.ts

@@ -61,6 +61,7 @@ export { DEFAULT_LABELS } from './types';
 export {
   STORAGE_KEYS,
   CSS_VARS,
+  Z_INDEX,
   DEFAULT_Z_INDEX,
   LIMITS,
   DEFAULT_SIDEBAR,
@@ -151,6 +152,21 @@ export {
   type UseChatAudioReturn,
 } from './core/audio';
 
+// Settings — the single, centralized home for chat-owned persisted
+// settings. Every chat feature reads/writes its slice through this hook.
+export {
+  useChatSettings,
+  CHAT_SETTINGS_STORAGE_KEY,
+  DEFAULT_CHAT_SETTINGS,
+  type ChatSettings,
+  type ChatDockSettings,
+  type ChatAudioSettings,
+  type ChatSpeechSettings,
+  type ChatPageContextSettings,
+  type UseChatSettingsOptions,
+  type UseChatSettingsReturn,
+} from './settings';
+
 // Notifier — title rotation + favicon badge + page-visibility + cross-tab
 export {
   createBrowserNotifier,

package/src/tools/Chat/settings/README.md

@@ -0,0 +1,87 @@
+# Chat settings — `tools/Chat/settings/`
+
+The single, centralized home for every **chat-owned persisted setting**.
+
+## Why this exists
+
+Chat features used to each call `useLocalStorage` (or zustand `persist`)
+with their own ad-hoc storage key. That made it impossible to reason
+about, export, or reset "the chat's settings" as one thing, and
+scattered the SSR / migration / coalescing concerns across the codebase.
+
+This module gives chat **one typed object, one storage key, one hook**:
+
+- `ChatSettings` — the typed shape of all chat-owned settings.
+- `useChatSettings()` — the only hook a chat feature should use to read or
+  write a persisted preference. Built on the improved `useLocalStorage`
+  from `@djangocfg/ui-core`, which gives us:
+  - **Coalesced writes** — several features patching different slices in
+    the same render commit collapse into one `localStorage` write.
+  - **Cross-instance / cross-tab sync** — two `useChatSettings()`
+    consumers stay in lockstep, same tab and across tabs.
+  - **Safe partial updates** — a slice updater that changes nothing is a
+    no-op (no write, no re-render).
+
+## API
+
+```ts
+const {
+  settings,            // full typed ChatSettings object
+  patch,               // grouped patch over whole slices
+  updateDock,          // updateDock({ side: 'left' })
+  updateAudio,
+  updateSpeech,
+  updatePageContext,
+  setAudioMuted,       // shortcut
+  setPageContextLinked,// shortcut
+  reset,
+} = useChatSettings();
+```
+
+Storage key: `djc.chat.settings`.
+
+## Migration status
+
+### Migrated
+
+- **Page-context opt-in** — `lib/page-snapshot/react/provider.tsx` now
+  reads/writes `ChatSettings.pageContext.linked` via `useChatSettings`
+  instead of its own `useLocalStorage('djc.page-snapshot.linked')`.
+  Note: this changes the storage key, so an existing user's prior opt-in
+  is not carried over — they start from the default (`linked: false`).
+  That is acceptable: page-context is opt-in and a fresh default is safe.
+
+### To migrate (safe follow-up — deferred to keep this pass low-risk)
+
+These are mature, working call sites. They each persist correctly today;
+moving them into `ChatSettings` is a clear next step but was deliberately
+deferred so a single PR does not churn the whole chat. Each migration
+also changes a storage key (acceptable — fresh defaults).
+
+- **Dock / layout prefs**
+  - `tools/Chat/hooks/useChatDockPrefs.ts` — key `chat.dock.prefs`,
+    shape `{ mode, side, sideWidth }` → `ChatSettings.dock`.
+  - `tools/Chat/hooks/useChatLayout.ts` — keys `djc-chat-mode`
+    (`STORAGE_KEYS.mode`) and `djc-chat-sidebar-width`
+    (`STORAGE_KEYS.sidebarWidth`) → `ChatSettings.dock.mode` /
+    `ChatSettings.dock.width`. Note `useChatLayout` stores `mode` and
+    width as two separate keys; consolidate into the `dock` slice.
+  - Constants live in `tools/Chat/constants.ts` (`STORAGE_KEYS`).
+
+- **Audio prefs**
+  - `tools/Chat/hooks/useChatAudio.ts` delegates to ui-core's
+    `useNotificationSounds`, which persists under
+    `djangocfg-chat-audio:prefs`. Migrating means either teaching
+    `useNotificationSounds` to accept an external value/setter, or
+    syncing `ChatSettings.audio` ⇆ that hook. Non-trivial — leave as is.
+
+- **Speech / language prefs**
+  - `tools/SpeechRecognition/store/prefsStore.ts` — a zustand `persist`
+    store under `djangocfg-stt:prefs`, shape `{ language, deviceId,
+    engineId, earcons }` → `ChatSettings.speech`. This is a different
+    persistence mechanism (zustand, not `useLocalStorage`); migrating it
+    means reconciling the store with `useChatSettings` and is the
+    highest-effort of the three. Leave as is.
+
+When migrating any of the above: update the consuming components, delete
+the old key from `STORAGE_KEYS` where applicable, and update this file.