@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/Chat/index.ts

@@ -3,77 +3,37 @@
 /**
  * @djangocfg/ui-tools — Chat
  *
+ * Root barrel: the shared light surface (`./public`) + the heavy,
+ * synchronously-loaded UI surface (components + launcher).
+ *
  * Decomposed, transport-agnostic chat. See @dev/@refactoring7-chat/ for design.
  */
 
-// Types
-export type {
-  ChatRole,
-  ChatMessage,
-  ChatPersona,
-  ChatToolCall,
-  ChatAttachment,
-  ChatSource,
-  ChatDisplayMode,
-  ChatUserContext,
-  ChatAssistantContext,
-  ChatPrefs,
-  ChatConfig,
-  ChatLabels,
-  ChatTransport,
-  ChatStreamEvent,
-  CreateSessionOptions,
-  SessionInfo,
-  HistoryPage,
-  StreamOptions,
-  SendOptions,
-} from './types';
-export { DEFAULT_LABELS } from './types';
-
-// Config
-export {
-  STORAGE_KEYS,
-  CSS_VARS,
-  DEFAULT_Z_INDEX,
-  LIMITS,
-  DEFAULT_SIDEBAR,
-  HOTKEYS,
-  CHAT_EVENT_NAME,
-  type ChatEventDetail,
-} from './config';
+// Light surface — types, constants, core, transport, hooks, notifier,
+// payload-dispatch, logger, utils, styles, context.
+export * from './public';
 
-// Core (pure)
-export {
-  reducer,
-  initialState,
-  createId,
-  createTokenBuffer,
-  resolvePersona,
-  deriveInitials,
-  type ChatState,
-  type ChatAction,
-  type TokenBuffer,
-} from './core';
+// Heavy sync surface — message rendering + composer + shell (presentation).
+export * from './messages';
+export * from './composer';
+export * from './shell';
 
-// Transport
+// Highlight — AI-driven `point` directives (spotlight + focus overlay).
 export {
-  createHttpTransport,
-  createMockTransport,
-  parseSSE,
-  TransportError,
-  createPydanticAIChatTransport,
-  createToolIdQueue,
-  mapPydanticAIEvent,
-  createPydanticAISSEMap,
-  type HttpTransportConfig,
-  type MockTransportOptions,
-  type ParseSSEOptions,
-  type PydanticAIChatTransportOpts,
-  type PydanticAIEvent,
-  type ToolIdQueue,
-} from './core/transport';
-
-// Launcher (FAB + Dock + Header + Greeting composition)
+  HighlightOverlay,
+  SpotlightCanvas,
+  useHighlightTargets,
+  resolveRefs,
+  type HighlightOverlayProps,
+  type SpotlightCanvasProps,
+  type RefResolver,
+  type PointDirective,
+  type HighlightTarget,
+  type SpotlightRect,
+  type CSTRefId,
+} from './highlight';
+
+// Launcher — FAB + Dock + Header + Greeting composition (heavy, sync).
 export {
   ChatFAB,
   ChatDock,
@@ -112,160 +72,6 @@ export {
   type ChatPresencePhase,
 } from './launcher';
 
-// Hooks
-export {
-  useChat,
-  useChatComposer,
-  useChatScroll,
-  useChatHistory,
-  useChatLayout,
-  useChatAudio,
-  useAutoFocusOnStreamEnd,
-  useRegisterComposer,
-  useChatReset,
-  useVisitorFingerprint,
-  useChatDockPrefs,
-  DEFAULT_DOCK_PREFS,
-  useFocusOnEmptyClick,
-  useChatUnread,
-  useChatUnreadNotifier,
-  type UseChatUnreadOptions,
-  type UseChatUnreadReturn,
-  type UseChatUnreadNotifierOptions,
-  type UseChatConfig,
-  type UseChatReturn,
-  type UseChatComposerOptions,
-  type UseChatComposerReturn,
-  type UseChatScrollOptions,
-  type UseChatScrollReturn,
-  type UseChatHistoryOptions,
-  type UseChatLayoutConfig,
-  type UseChatLayoutReturn,
-  type UseAutoFocusOnStreamEndOptions,
-  type Focusable,
-  type UseChatResetOptions,
-  type UseChatResetReturn,
-  type UseVisitorFingerprintOptions,
-  type ChatDockPrefs,
-  type UseChatDockPrefsOptions,
-  type UseChatDockPrefsReturn,
-  type UseFocusOnEmptyClickOptions,
-} from './hooks';
-
-// Notifier — title rotation + favicon badge + page-visibility + cross-tab
-export {
-  createBrowserNotifier,
-  createNoopNotifier,
-  createTitleRotator,
-  createFaviconBadge,
-  createCrossTabNotifier,
-  isPageHidden,
-  onVisibilityChange,
-  type ChatNotifier,
-  type BrowserNotifierOptions,
-  type TitleRotatorOptions,
-  type TitleMode,
-  type FaviconBadgeOptions,
-  type CrossTabNotifierOptions,
-} from './notifier';
-
-// Audio
-export type {
-  ChatAudioEvent,
-  ChatAudioSounds,
-  ChatAudioConfig,
-  UseChatAudioReturn,
-} from './core/audio';
-export { useChatAudioPrefs, DEFAULT_CHAT_SOUNDS } from './core/audio';
-
-// Tool-call payload dispatcher
-export {
-  dispatchToolPayload,
-  isPlainObject,
-  isLatLng,
-  isGeoJSONFeatureCollection,
-  isStringValue,
-  type ToolPayloadMatcher,
-  type ToolPayloadFallback,
-} from './core/payload-dispatch';
-
-// Lightbox helpers
-export { useChatLightbox, type UseChatLightboxReturn, type ChatLightboxState } from './hooks';
-
-// Styles — role-aware className tokens + hooks
-export {
-  BUBBLE_SURFACE,
-  ANCHOR,
-  TOGGLE,
-  DESTRUCTIVE_SURFACE,
-  TOOL_CALL,
-  useChatBubbleStyles,
-  useChatRoleStyles,
-  useChatDestructiveStyles,
-  type ChatBubbleSurface,
-  type ChatBubbleStyles,
-  type ChatRoleStyles,
-  type ChatDestructiveStyles,
-} from './styles';
-export { collectImageAttachments } from './utils/collectImageAttachments';
-
-// Draft sanitation — trim, collapse runs, strip zero-width chars.
-// Wire into your composer's submit handler / Send-button gate so
-// empty-after-cleanup drafts don't fire bogus messages.
-export { sanitizeDraft, isSubmittableDraft } from './utils/sanitizeDraft';
-
-// Dev logger (consola-based, namespace "chat:*")
-export { getChatLogger, type ChatLogger, type ChatLogScope } from './core/logger';
-
-// Context
-export {
-  ChatProvider,
-  useChatContext,
-  useChatContextOptional,
-  type ChatContextValue,
-  type ChatProviderProps,
-} from './context';
-
-// Components
-export {
-  ChatRoot,
-  MessageList,
-  MessageBubble,
-  MessageActions,
-  Composer,
-  Sources,
-  ToolCalls,
-  Attachments,
-  AttachmentsGrid,
-  AttachmentsList,
-  EmptyState,
-  ErrorBanner,
-  JumpToLatest,
-  StreamingIndicator,
-  AudioToggle,
-  type ChatRootProps,
-  type MessageListProps,
-  type MessageListHandle,
-  type MessageBubbleProps,
-  type MessageActionsProps,
-  type ComposerProps,
-  type ComposerSize,
-  type SourcesProps,
-  type ToolCallsProps,
-  type ToolPayloadKind,
-  type AttachmentsProps,
-  type AttachmentsGridProps,
-  type AttachmentsListProps,
-  type AttachmentRenderer,
-  type AttachmentRendererArgs,
-  type AttachmentRendererMap,
-  type EmptyStateProps,
-  type ErrorBannerProps,
-  type JumpToLatestProps,
-  type StreamingIndicatorProps,
-  type AudioToggleProps,
-} from './components';
-
 // Lazy preset
 export { LazyChat } from './lazy';
 

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

@@ -7,7 +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 { ChatHeader } from './ChatHeader';
+import { ChatHeader } from './header';
 import { useChatPresence } from './useChatPresence';
 import type { ChatFABPosition } from './ChatFAB';
 

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

@@ -17,7 +17,7 @@ import { ChatFAB, type ChatFABPosition, type ChatFABProps } from './ChatFAB';
 import { ChatDock, type ChatDockProps } from './ChatDock';
 import { ChatGreeting, type ChatGreetingProps } from './ChatGreeting';
 import { ChatUnreadPreview, type ChatUnreadPreviewProps } from './ChatUnreadPreview';
-import { HeaderSlotsRenderer } from './HeaderSlots';
+import { HeaderSlotsRenderer } from './header';
 import { resolveHeaderSlots, type ChatHeaderSlots } from './types';
 
 export interface ChatLauncherHotkey {

package/src/tools/Chat/launcher/{ChatHeader.tsx → header/ChatHeader.tsx}

@@ -3,7 +3,13 @@
 import { Bot, X } from 'lucide-react';
 import type { ReactNode } from 'react';
 
-import { Button } from '@djangocfg/ui-core/components';
+import {
+  Button,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 export interface ChatHeaderProps {
@@ -20,7 +26,7 @@ export interface ChatHeaderProps {
   showClose?: boolean;
   /** Close click handler. */
   onClose?: () => void;
-  /** ARIA label for the close button. @default 'Close' */
+  /** ARIA label + tooltip for the close button. @default 'Close' */
   closeLabel?: string;
   /** Replace the close button entirely (rare — most hosts want the default). */
   closeSlot?: ReactNode;
@@ -60,15 +66,22 @@ export function ChatHeader({
         {actions}
         {closeSlot ??
           (showClose && onClose && (
-            <Button
-              variant="ghost"
-              size="sm"
-              onClick={onClose}
-              aria-label={closeLabel}
-              className="-mr-1 h-7 w-7 p-0"
-            >
-              <X className="h-4 w-4" />
-            </Button>
+            <TooltipProvider delayDuration={300}>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    onClick={onClose}
+                    aria-label={closeLabel}
+                    className="-mr-1 h-7 w-7 p-0"
+                  >
+                    <X className="h-4 w-4" />
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent side="bottom">{closeLabel}</TooltipContent>
+              </Tooltip>
+            </TooltipProvider>
           ))}
       </div>
     </header>

package/src/tools/Chat/launcher/{ChatHeaderActionButton.tsx → header/ChatHeaderActionButton.tsx}

@@ -3,14 +3,26 @@
 import { forwardRef } from 'react';
 import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 export interface ChatHeaderActionButtonProps
   extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
   /** Icon (required). */
   icon: ReactNode;
-  /** Accessible label + native tooltip. */
+  /** Accessible label — also drives the hover/focus tooltip. */
   ariaLabel: string;
+  /**
+   * Tooltip copy. Defaults to `ariaLabel`. Pass to show a friendlier
+   * label than the (sometimes terse) aria string. Set `false` to opt
+   * out of the floating tooltip entirely (native `title` still applies).
+   */
+  tooltip?: ReactNode | false;
   /** Optional unread / status badge — small number on top-right. */
   badge?: number;
   /** Mark as destructive — uses destructive hover tokens. */
@@ -25,6 +37,9 @@ export interface ChatHeaderActionButtonProps
  * Standard chrome: 28×28 ghost button, hover bg-accent, focus ring, optional
  * destructive variant, optional numeric badge for unread / pending.
  *
+ * Shows a floating tooltip (ui-core `<Tooltip>`) on hover *and* keyboard
+ * focus; falls back to the native `title` attribute as well.
+ *
  * @example
  * ```tsx
  * <ChatHeader
@@ -50,10 +65,10 @@ export interface ChatHeaderActionButtonProps
  */
 export const ChatHeaderActionButton = forwardRef<HTMLButtonElement, ChatHeaderActionButtonProps>(
   function ChatHeaderActionButton(
-    { icon, ariaLabel, badge, destructive, loading, disabled, className, ...rest },
+    { icon, ariaLabel, tooltip, badge, destructive, loading, disabled, className, ...rest },
     ref,
   ) {
-    return (
+    const button = (
       <button
         ref={ref}
         type="button"
@@ -83,5 +98,21 @@ export const ChatHeaderActionButton = forwardRef<HTMLButtonElement, ChatHeaderAc
         )}
       </button>
     );
+
+    // Opted out — keep the native `title` only.
+    if (tooltip === false) return button;
+
+    // Floating tooltip on hover *and* keyboard focus. Self-contained
+    // `<TooltipProvider>` so the button works standalone without the
+    // host wiring an ambient provider; Radix dedupes nested providers.
+    const tooltipLabel = tooltip ?? ariaLabel;
+    return (
+      <TooltipProvider delayDuration={300}>
+        <Tooltip>
+          <TooltipTrigger asChild>{button}</TooltipTrigger>
+          <TooltipContent side="bottom">{tooltipLabel}</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    );
   },
 );

package/src/tools/Chat/launcher/{ChatHeaderLanguageButton.tsx → header/ChatHeaderLanguageButton.tsx}

@@ -11,14 +11,14 @@ import {
 } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
-import { findSpeechLanguage } from '../../SpeechRecognition';
+import { findSpeechLanguage } from '../../../SpeechRecognition';
 
 import {
   WEB_SPEECH_LANGUAGES,
   countryFromTag,
   useResolvedLanguage,
   useSpeechPrefs,
-} from '../../SpeechRecognition';
+} from '../../../SpeechRecognition';
 
 export interface ChatHeaderLanguageButtonProps {
   /** Override aria-label. Default "Speech language". */

package/src/tools/Chat/launcher/{ChatHeaderModeToggle.tsx → header/ChatHeaderModeToggle.tsx}

@@ -5,7 +5,7 @@ import { PanelRightOpen, PanelRightClose } from 'lucide-react';
 import { useIsTabletOrBelow } from '@djangocfg/ui-core/hooks';
 
 import { ChatHeaderActionButton } from './ChatHeaderActionButton';
-import type { ChatDockMode } from './ChatDock';
+import type { ChatDockMode } from '../ChatDock';
 
 export interface ChatHeaderModeToggleProps {
   /** Current dock mode. */

package/src/tools/Chat/launcher/{ChatHeaderResetButton.tsx → header/ChatHeaderResetButton.tsx}

@@ -2,7 +2,7 @@
 
 import { RotateCcw } from 'lucide-react';
 
-import { useChatReset } from '../hooks/useChatReset';
+import { useChatReset } from '../../hooks/useChatReset';
 import { ChatHeaderActionButton } from './ChatHeaderActionButton';
 
 export interface ChatHeaderResetButtonProps {
@@ -85,6 +85,7 @@ export function ChatHeaderResetButton({
     <ChatHeaderActionButton
       icon={<RotateCcw className="h-3.5 w-3.5" />}
       ariaLabel={ariaLabel}
+      tooltip="Reset conversation"
       onClick={handleClick}
       loading={isResetting}
       destructive

package/src/tools/Chat/launcher/{HeaderSlots.tsx → header/HeaderSlots.tsx}

@@ -2,14 +2,14 @@
 
 import { Fragment } from 'react';
 
-import { useChatContext } from '../context';
-import { useChatDockPrefs } from '../hooks/useChatDockPrefs';
+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';
+import type { ResolvedChatHeaderSlots } from '../types';
 
 export interface HeaderSlotsRendererProps {
   slots: ResolvedChatHeaderSlots;

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

@@ -0,0 +1,26 @@
+'use client';
+
+/** Launcher header — the docked chat header and its slot buttons. */
+
+export { ChatHeader, type ChatHeaderProps } from './ChatHeader';
+export {
+  ChatHeaderActionButton,
+  type ChatHeaderActionButtonProps,
+} from './ChatHeaderActionButton';
+export {
+  ChatHeaderModeToggle,
+  type ChatHeaderModeToggleProps,
+} from './ChatHeaderModeToggle';
+export {
+  ChatHeaderAudioToggle,
+  type ChatHeaderAudioToggleProps,
+} from './ChatHeaderAudioToggle';
+export {
+  ChatHeaderResetButton,
+  type ChatHeaderResetButtonProps,
+} from './ChatHeaderResetButton';
+export {
+  ChatHeaderLanguageButton,
+  type ChatHeaderLanguageButtonProps,
+} from './ChatHeaderLanguageButton';
+export { HeaderSlotsRenderer } from './HeaderSlots';

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

@@ -11,27 +11,20 @@ export {
   type ChatDockMode,
   type ChatDockSide,
 } from './ChatDock';
-export { ChatHeader, type ChatHeaderProps } from './ChatHeader';
 export {
+  ChatHeader,
+  type ChatHeaderProps,
   ChatHeaderActionButton,
   type ChatHeaderActionButtonProps,
-} from './ChatHeaderActionButton';
-export {
   ChatHeaderModeToggle,
   type ChatHeaderModeToggleProps,
-} from './ChatHeaderModeToggle';
-export {
   ChatHeaderAudioToggle,
   type ChatHeaderAudioToggleProps,
-} from './ChatHeaderAudioToggle';
-export {
   ChatHeaderResetButton,
   type ChatHeaderResetButtonProps,
-} from './ChatHeaderResetButton';
-export {
   ChatHeaderLanguageButton,
   type ChatHeaderLanguageButtonProps,
-} from './ChatHeaderLanguageButton';
+} from './header';
 export {
   ChatLauncher,
   type ChatLauncherProps,