@djangocfg/ui-tools 2.1.409 → 2.1.412

package/src/tools/Chat/constants.ts

@@ -12,7 +12,30 @@ export const CSS_VARS = {
   reserve: '--djc-chat-reserve',
 } as const;
 
-export const DEFAULT_Z_INDEX = 9000;
+/**
+ * Z-index tier for the floating chat surface.
+ *
+ * The chat dock is page furniture — a peer of page content, not a modal.
+ * It must sit ABOVE the page yet BELOW every `@djangocfg/ui-core` overlay
+ * (sheet 200, drawer 500, dialog 600, anchored overlays 700) so that any
+ * dialog — including one launched from inside the chat — always wins.
+ *
+ *   dock        100   the chat surface
+ *   companion    99   FAB / greeting / unread preview (behind the open dock)
+ *   tooltip     101   chat-header tooltips (just above the dock, still
+ *                     below ui-core's modal/overlay tiers)
+ */
+export const Z_INDEX = {
+  /** The chat dock surface. */
+  dock: 100,
+  /** FAB, greeting bubble and unread preview — sit just below the dock. */
+  companion: 99,
+  /** Tooltips portaled out of the chat header — just above the dock. */
+  tooltip: 101,
+} as const;
+
+/** @deprecated Use {@link Z_INDEX.dock}. Kept for the public API surface. */
+export const DEFAULT_Z_INDEX = Z_INDEX.dock;
 
 export const LIMITS = {
   /** Max characters per single message. */

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/hooks/useChat.ts

@@ -407,6 +407,38 @@ export function useChat(config: UseChatConfig): UseChatReturn {
               sources: ev.sources?.length ?? 0,
             });
             return;
+          case 'message_metrics':
+            // Non-terminal: attach per-turn metrics to the streaming
+            // message. The stream stays open until message_end / error.
+            dispatch({
+              type: 'MESSAGE_PATCH',
+              id: targetId,
+              patch: {
+                metrics: ev.metrics,
+                ...(ev.metrics.resolvedModel
+                  ? { resolvedModel: ev.metrics.resolvedModel }
+                  : {}),
+              },
+            });
+            log.stream.debug('message_metrics', {
+              turns: ev.metrics.turns,
+              toolCallCount: ev.metrics.toolCallCount,
+              resolvedModel: ev.metrics.resolvedModel,
+            });
+            return;
+          case 'resolved_model':
+            // Non-terminal: model alias was resolved mid-run.
+            dispatch({
+              type: 'MESSAGE_PATCH',
+              id: targetId,
+              patch: { resolvedModel: ev.resolvedModel },
+            });
+            log.stream.debug('resolved_model', {
+              originalAlias: ev.originalAlias,
+              resolvedModel: ev.resolvedModel,
+              upgraded: ev.upgraded,
+            });
+            return;
           case 'error':
             tokenBuffer.flush();
             dispatch({

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

@@ -50,6 +50,9 @@ export interface UseChatComposerReturn {
   setValue: (next: string) => void;
   attachments: ChatAttachment[];
   addAttachment: (a: ChatAttachment) => void;
+  /** Patch an existing attachment in place — used by the upload lifecycle
+   *  to flip `status` / `progress` / `url` without losing list order. */
+  updateAttachment: (id: string, patch: Partial<ChatAttachment>) => void;
   removeAttachment: (id: string) => void;
   isSubmitting: boolean;
   canSubmit: boolean;
@@ -192,6 +195,15 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
     [maxAttachments],
   );
 
+  const updateAttachment = useCallback(
+    (id: string, patch: Partial<ChatAttachment>) => {
+      setAttachments((prev) =>
+        prev.map((a) => (a.id === id ? { ...a, ...patch } : a)),
+      );
+    },
+    [],
+  );
+
   const removeAttachment = useCallback((id: string) => {
     setAttachments((prev) => prev.filter((a) => a.id !== id));
   }, []);
@@ -276,6 +288,7 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
     setValue,
     attachments,
     addAttachment,
+    updateAttachment,
     removeAttachment,
     isSubmitting,
     canSubmit,

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/messages/MessageBubble.tsx

@@ -264,7 +264,7 @@ const MessageBubbleInner = ({
         {message.blocks?.length ? (
           <MessageBlocks
             blocks={message.blocks}
-            registry={resolvedBlockRegistry}
+            registry={resolvedBlockRegistry ?? undefined}
             appearance={appearance}
             isUser={isUser}
           />

package/src/tools/Chat/public.ts

@@ -34,6 +34,7 @@ export type {
   ChatLabels,
   ChatTransport,
   ChatStreamEvent,
+  ChatMessageMetrics,
   CreateSessionOptions,
   SessionInfo,
   HistoryPage,
@@ -61,6 +62,7 @@ export { DEFAULT_LABELS } from './types';
 export {
   STORAGE_KEYS,
   CSS_VARS,
+  Z_INDEX,
   DEFAULT_Z_INDEX,
   LIMITS,
   DEFAULT_SIDEBAR,
@@ -151,6 +153,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,