@djangocfg/ui-tools 2.1.335 → 2.1.337

package/src/tools/Chat/config.ts

@@ -0,0 +1,55 @@
+/**
+ * Chat defaults and constants.
+ */
+
+export const STORAGE_KEYS = {
+  mode: 'djc-chat-mode',
+  sidebarWidth: 'djc-chat-sidebar-width',
+  composerHistory: 'djc-chat-composer-history',
+} as const;
+
+export const CSS_VARS = {
+  reserve: '--djc-chat-reserve',
+} as const;
+
+export const DEFAULT_Z_INDEX = 9000;
+
+export const LIMITS = {
+  /** Max characters per single message. */
+  messageMaxLength: 8000,
+  /** Max attachments per message. */
+  attachmentsMax: 10,
+  /** Composer history slots. */
+  composerHistorySize: 50,
+  /** Coalesce stream tokens within this window before dispatching. */
+  streamCoalesceMs: 16,
+  /** Default history page size. */
+  pageSize: 50,
+  /** Virtualize list when >= this many messages (host-controlled threshold). */
+  virtualizeThreshold: 50,
+  /** SSE idle timeout. */
+  sseIdleMs: 45_000,
+} as const;
+
+export const DEFAULT_SIDEBAR = {
+  width: 420,
+  min: 320,
+  max: 720,
+} as const;
+
+export const HOTKEYS = {
+  send: 'mod+enter',
+  cancel: 'esc',
+  newChat: 'mod+shift+n',
+  toggleOpen: 'mod+/',
+  focusComposer: 'mod+l',
+} as const;
+
+export const CHAT_EVENT_NAME = 'djc:chat:send';
+
+export interface ChatEventDetail {
+  content: string;
+  sessionId?: string;
+  attachments?: unknown[];
+  metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,126 @@
+'use client';
+
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
+
+import type { ChatConfig, ChatLabels, ChatTransport } from '../types';
+import { DEFAULT_LABELS } from '../types';
+import { useChat, type UseChatReturn } from '../hooks/useChat';
+import { useChatLayout, type UseChatLayoutReturn } from '../hooks/useChatLayout';
+import { useChatAudio } from '../hooks/useChatAudio';
+import type { ChatAudioConfig, UseChatAudioReturn } from '../core/audio/types';
+
+export interface ChatContextValue extends UseChatReturn {
+  layout: UseChatLayoutReturn;
+  config: ChatConfig;
+  labels: ChatLabels;
+  audio: UseChatAudioReturn;
+}
+
+const Ctx = createContext<ChatContextValue | null>(null);
+
+export interface ChatProviderProps {
+  transport: ChatTransport;
+  config?: ChatConfig;
+  initialSessionId?: string;
+  autoCreateSession?: boolean;
+  streaming?: boolean;
+  /** Audio-trigger configuration. Off by default (no `sounds` map). */
+  audio?: ChatAudioConfig;
+  /** Enable verbose dev logging via consola. Defaults to `isDev`. */
+  debug?: boolean;
+  children?: ReactNode;
+}
+
+export function ChatProvider({
+  transport,
+  config = {},
+  initialSessionId,
+  autoCreateSession,
+  streaming,
+  audio,
+  debug,
+  children,
+}: ChatProviderProps) {
+  const audioApi = useChatAudio(audio ?? {});
+
+  // Keep latest audio API in a ref so the chat-callback closures stay
+  // referentially stable (don't re-mount transport on every audio change).
+  const audioRef = useRef(audioApi);
+  audioRef.current = audioApi;
+
+  const onMessageSent = useCallback(() => audioRef.current.play('messageSent'), []);
+  const onMessageEnd = useCallback(() => audioRef.current.play('messageReceived'), []);
+  const onStreamStart = useCallback(() => audioRef.current.play('streamStart'), []);
+  const onError = useCallback(() => audioRef.current.play('error'), []);
+
+  const chat = useChat({
+    transport,
+    initialSessionId,
+    autoCreateSession,
+    streaming,
+    debug,
+    metadata: {
+      locale: config.locale ?? config.prefs?.locale,
+      slug: config.slug,
+    },
+    userPersona: config.user,
+    onMessageSent,
+    onMessageEnd,
+    onStreamStart,
+    onError,
+  });
+  const layout = useChatLayout({ defaultMode: 'embedded' });
+
+  // Auto-unlock audio on the first user gesture inside the provider.
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (audioApi.isUnlocked) return;
+    const root = rootRef.current;
+    if (!root) return;
+    const handler = () => {
+      audioApi.unlock();
+    };
+    root.addEventListener('pointerdown', handler, { once: true, capture: true });
+    root.addEventListener('keydown', handler, { once: true, capture: true });
+    return () => {
+      root.removeEventListener('pointerdown', handler, { capture: true });
+      root.removeEventListener('keydown', handler, { capture: true });
+    };
+  }, [audioApi]);
+
+  const labels = useMemo<ChatLabels>(
+    () => ({ ...DEFAULT_LABELS, ...(config.labels ?? {}) }),
+    [config.labels],
+  );
+
+  const value = useMemo<ChatContextValue>(
+    () => ({ ...chat, layout, config, labels, audio: audioApi }),
+    [chat, layout, config, labels, audioApi],
+  );
+
+  return (
+    <Ctx.Provider value={value}>
+      <div ref={rootRef} style={{ display: 'contents' }}>
+        {children}
+      </div>
+    </Ctx.Provider>
+  );
+}
+
+export function useChatContext(): ChatContextValue {
+  const v = useContext(Ctx);
+  if (!v) throw new Error('useChatContext must be used inside <ChatProvider>');
+  return v;
+}
+
+export function useChatContextOptional(): ChatContextValue | null {
+  return useContext(Ctx);
+}

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

@@ -0,0 +1,9 @@
+'use client';
+
+export {
+  ChatProvider,
+  useChatContext,
+  useChatContextOptional,
+  type ChatContextValue,
+  type ChatProviderProps,
+} from './ChatProvider';

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

@@ -0,0 +1,172 @@
+// 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.
+
+import type { ChatAudioEvent, ChatAudioSounds } from './types';
+
+interface BusOptions {
+  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;
+}
+
+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,
+  };
+}

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

@@ -0,0 +1,8 @@
+export type {
+  ChatAudioEvent,
+  ChatAudioSounds,
+  ChatAudioConfig,
+  UseChatAudioReturn,
+} from './types';
+export { createAudioBus, type ChatAudioBus } from './audioBus';
+export { useChatAudioPrefs, type ChatAudioPrefsState } from './preferences';

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

@@ -0,0 +1,68 @@
+// Cross-tab persistent chat-audio prefs (master volume / muted / unlocked).
+//
+// Why Zustand here (vs. AudioPlayer's plain module-level store): the chat
+// audio system has more knobs (per-event toggles + volume + muted) and lives
+// behind a React context where multiple chat providers might exist. We get the
+// `subscribe()` + `useSyncExternalStore` plumbing for free, and the persist
+// middleware handles cross-tab sync via the `storage` event.
+//
+// We DO NOT close the AudioContext (matches AudioPlayer's ADR-004) and we
+// remain SSR-safe by gating window access in the bus, not here.
+
+'use client';
+
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+import type { ChatAudioEvent } from './types';
+
+const STORAGE_KEY = 'djangocfg-chat-audio:prefs';
+
+export interface ChatAudioPrefsState {
+  /** 0..1 master volume. */
+  volume: number;
+  /** Master mute (overrides per-event toggles). */
+  muted: boolean;
+  /** Per-event opt-out — `false` silences a single trigger. */
+  enabled: Partial<Record<ChatAudioEvent, boolean>>;
+
+  setVolume: (v: number) => void;
+  setMuted: (m: boolean) => void;
+  setEventEnabled: (event: ChatAudioEvent, enabled: boolean) => void;
+}
+
+const clamp01 = (v: number): number => {
+  if (!Number.isFinite(v)) return 1;
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+};
+
+export const useChatAudioPrefs = create<ChatAudioPrefsState>()(
+  persist(
+    (set) => ({
+      volume: 1,
+      muted: false,
+      enabled: {},
+
+      setVolume: (v) => set({ volume: clamp01(v) }),
+      setMuted: (m) => set({ muted: !!m }),
+      setEventEnabled: (event, enabled) =>
+        set((s) => ({ enabled: { ...s.enabled, [event]: enabled } })),
+    }),
+    {
+      name: STORAGE_KEY,
+      storage: createJSONStorage(() => {
+        // SSR-safe: zustand calls `getStorage()` lazily, but be defensive.
+        if (typeof window === 'undefined') {
+          return {
+            getItem: () => null,
+            setItem: () => undefined,
+            removeItem: () => undefined,
+          };
+        }
+        return window.localStorage;
+      }),
+      partialize: (s) => ({ volume: s.volume, muted: s.muted, enabled: s.enabled }),
+      version: 1,
+    },
+  ),
+);

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

@@ -0,0 +1,49 @@
+// Public types for the chat-audio subsystem.
+
+export type ChatAudioEvent =
+  | 'messageSent'
+  | 'messageReceived'
+  | 'streamStart'
+  | 'error'
+  | 'mention'
+  | 'notification';
+
+/** Map an event to a sound URL. `false` silences the event explicitly. */
+export type ChatAudioSounds = Partial<Record<ChatAudioEvent, string | false>>;
+
+export interface ChatAudioConfig {
+  /** Map event → asset URL. Omit (or set `false`) to silence one event. */
+  sounds?: ChatAudioSounds;
+  /** Master volume 0..1. Persisted via the global prefs store. */
+  volume?: number;
+  /** Master mute. */
+  muted?: boolean;
+  /** Custom predicate — return `false` to suppress a play call. */
+  shouldPlay?: (event: ChatAudioEvent) => boolean;
+  /** Default-suppress when user prefers reduced motion. Default: true. */
+  respectReducedMotion?: boolean;
+  /** Default-suppress when user prefers reduced data. Default: true. */
+  respectReducedData?: boolean;
+  /** Mute when host page is hidden (`visibilityState === 'hidden'`). Default: true. */
+  muteWhenHidden?: boolean;
+}
+
+export interface UseChatAudioReturn {
+  /** Play a sound for an event. No-ops if the event has no URL or is muted. */
+  play: (event: ChatAudioEvent) => void;
+  /** Eagerly load an event's audio (called automatically on mount). */
+  preload: (event: ChatAudioEvent) => void;
+  /** Manually unlock — useful in stories/tests. */
+  unlock: () => void;
+  /** True after the first user gesture inside the chat root. */
+  isUnlocked: boolean;
+  /** Master mute (persistent). */
+  muted: boolean;
+  setMuted: (m: boolean) => void;
+  /** Master volume 0..1 (persistent). */
+  volume: number;
+  setVolume: (v: number) => void;
+  /** Per-event opt-out (persistent). */
+  isEventEnabled: (event: ChatAudioEvent) => boolean;
+  setEventEnabled: (event: ChatAudioEvent, enabled: boolean) => void;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * ID generation. Uses crypto.randomUUID when available with a fallback
+ * for older environments (and SSR bundles that may not have crypto).
+ */
+
+let counter = 0;
+
+export function createId(prefix = 'm'): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return `${prefix}_${crypto.randomUUID()}`;
+  }
+  counter += 1;
+  return `${prefix}_${Date.now().toString(36)}_${counter.toString(36)}_${Math.random()
+    .toString(36)
+    .slice(2, 8)}`;
+}

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

@@ -0,0 +1,5 @@
+export { reducer, initialState, type ChatState, type ChatAction } from './reducer';
+export { createId } from './ids';
+export { createTokenBuffer, type TokenBuffer } from './markdown';
+export { resolvePersona, deriveInitials } from './persona';
+export * from './transport';

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

@@ -0,0 +1,73 @@
+/**
+ * Chat dev logger.
+ *
+ * A thin namespaced wrapper over `consola` that no-ops in production unless
+ * the host app explicitly opts in via `<ChatRoot debug />`. The default
+ * detection uses `isDev` from `@djangocfg/ui-core/lib/env` (NODE_ENV).
+ *
+ * Why a dedicated module: chat is async and event-heavy (bootstrap, transport,
+ * SSE chunks, tool calls, regenerate, …). Inline `console.log`s rot fast and
+ * leak into prod. A single `getChatLogger()` call gives every layer the same
+ * namespaced sub-logger and keeps zero-cost gating in one place.
+ *
+ * Sub-loggers:
+ *   bootstrap  — initial session bootstrap (createSession / loadHistory)
+ *   transport  — outbound transport calls + responses
+ *   stream     — SSE chunk / tool / message_end events
+ *   lifecycle  — sendMessage, regenerate, newSession, edits
+ *   tools      — tool_call_start / _delta / _end specifics
+ *   error      — caught errors (always emitted as `error` level)
+ */
+import { consola, type ConsolaInstance } from 'consola';
+
+import { isDev } from '@djangocfg/ui-core/lib';
+
+export type ChatLogScope = 'bootstrap' | 'transport' | 'stream' | 'lifecycle' | 'tools' | 'error';
+
+export interface ChatLogger {
+  bootstrap: ConsolaInstance;
+  transport: ConsolaInstance;
+  stream: ConsolaInstance;
+  lifecycle: ConsolaInstance;
+  tools: ConsolaInstance;
+  error: ConsolaInstance;
+  /** True when this logger is actually emitting (host opted in or NODE_ENV=development). */
+  enabled: boolean;
+}
+
+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>();
+
+function buildLogger(enabled: boolean): ChatLogger {
+  const root = consola.withTag('chat');
+  const subs = Object.fromEntries(
+    SCOPES.map((scope) => [scope, root.withTag(scope)]),
+  ) as Record<ChatLogScope, ConsolaInstance>;
+
+  if (!enabled) {
+    // Silence everything except `error` — surfaced errors should never go
+    // missing even if the host didn't opt in to debug logs.
+    for (const scope of SCOPES) {
+      if (scope === 'error') continue;
+      subs[scope].level = -999;
+    }
+  }
+
+  return { ...subs, enabled };
+}
+
+/**
+ * Get the chat logger.
+ * @param debug Explicit override from the host. `undefined` falls back to `isDev`.
+ */
+export function getChatLogger(debug?: boolean): ChatLogger {
+  const enabled = debug ?? isDev;
+  let logger = cache.get(enabled);
+  if (!logger) {
+    logger = buildLogger(enabled);
+    cache.set(enabled, logger);
+  }
+  return logger;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Token coalescer. Buffers stream tokens within a small time window before
+ * dispatching a single aggregated chunk. Prevents 60+ re-renders per second
+ * on fast streams.
+ */
+
+import { LIMITS } from '../config';
+
+export interface TokenBuffer {
+  /** Append a delta. Returns immediately. */
+  push(delta: string): void;
+  /** Force flush and resolve any pending timer. */
+  flush(): void;
+  /** Stop accepting tokens; flush whatever is buffered. */
+  close(): void;
+}
+
+export function createTokenBuffer(
+  onFlush: (delta: string) => void,
+  windowMs = LIMITS.streamCoalesceMs,
+): TokenBuffer {
+  let pending = '';
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let closed = false;
+
+  const flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (pending) {
+      const out = pending;
+      pending = '';
+      onFlush(out);
+    }
+  };
+
+  return {
+    push(delta: string) {
+      if (closed || !delta) return;
+      pending += delta;
+      if (windowMs <= 0) {
+        flush();
+        return;
+      }
+      if (timer === null) {
+        timer = setTimeout(flush, windowMs);
+      }
+    },
+    flush,
+    close() {
+      closed = true;
+      flush();
+    },
+  };
+}