@djangocfg/ui-tools 2.1.381 → 2.1.382

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

@@ -6,3 +6,4 @@ export type {
 } from './types';
 export { createAudioBus, type ChatAudioBus } from './audioBus';
 export { useChatAudioPrefs, type ChatAudioPrefsState } from './preferences';
+export { DEFAULT_CHAT_SOUNDS } from './defaults';

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

@@ -1,68 +1,14 @@
-// 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.
+// Thin re-export — audio prefs storage now lives in `@djangocfg/ui-core/hooks`.
+// Existing direct consumers (`AudioToggle`) keep working through this wrapper.
 
 'use client';
 
-import { create } from 'zustand';
-import { persist, createJSONStorage } from 'zustand/middleware';
+import { createAudioPrefsStore, type AudioPrefsState } from '@djangocfg/ui-core/hooks';
 
 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>>;
+export type ChatAudioPrefsState = AudioPrefsState<ChatAudioEvent>;
 
-  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,
-    },
-  ),
-);
+export const useChatAudioPrefs = createAudioPrefsStore<ChatAudioEvent>(STORAGE_KEY);

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

@@ -16,6 +16,19 @@ export interface ChatAudioConfig {
   sounds?: ChatAudioSounds;
   /** Master volume 0..1. Persisted via the global prefs store. */
   volume?: number;
+  /**
+   * Per-event volume multipliers (0..1). Applied on top of `volume`.
+   * Defaults applied by `useChatAudio` if not provided:
+   *   - error: 0.25  (gentle — error UI is the loud signal, not the sound)
+   *   - mention: 1.0 (louder than baseline received)
+   *   - messageSent: 0.5  (subtle self-confirmation)
+   *   - messageReceived: 0.7
+   *   - streamStart: 0.3  (very subtle, fires often)
+   *   - notification: 0.9
+   *
+   * Pass `{}` to disable defaults; pass overrides to tweak.
+   */
+  eventVolumes?: Partial<Record<ChatAudioEvent, number>>;
   /** Master mute. */
   muted?: boolean;
   /** Custom predicate — return `false` to suppress a play call. */
@@ -26,6 +39,17 @@ export interface ChatAudioConfig {
   respectReducedData?: boolean;
   /** Mute when host page is hidden (`visibilityState === 'hidden'`). Default: true. */
   muteWhenHidden?: boolean;
+  /**
+   * Skip web playback entirely — `play()` becomes a no-op. Pair with
+   * `onSoundEvent` for native hosts (cmdop_go / Tauri) that play sounds
+   * outside the browser.
+   */
+  silenced?: boolean;
+  /**
+   * Side-channel fired whenever `play(event)` is called. Stays active
+   * even when `silenced=true`. Use to bridge into a native audio backend.
+   */
+  onSoundEvent?: (event: ChatAudioEvent) => void;
 }
 
 export interface UseChatAudioReturn {
@@ -40,10 +64,14 @@ export interface UseChatAudioReturn {
   /** Master mute (persistent). */
   muted: boolean;
   setMuted: (m: boolean) => void;
+  /** Flip mute state — convenience. */
+  toggleMute: () => 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;
+  /** True when no sounds are configured (or `silenced`). */
+  isSilent: boolean;
 }

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

@@ -83,6 +83,8 @@ export type ChatAction =
   | { type: 'STREAM_RESUME_EXISTING' }
   | { type: 'MESSAGE_EDIT'; id: string; content: string }
   | { type: 'MESSAGE_DELETE'; id: string }
+  | { type: 'MESSAGE_INJECT'; message: ChatMessage; position?: 'append' | 'prepend' }
+  | { type: 'MESSAGE_PATCH'; id: string; patch: Partial<ChatMessage> }
   | { type: 'MESSAGES_CLEAR' }
   | { type: 'ERROR_SET'; error: string | null }
   | {
@@ -327,6 +329,37 @@ export function reducer(state: ChatState, action: ChatAction): ChatState {
         messages: state.messages.filter((m) => m.id !== action.id),
       };
 
+    case 'MESSAGE_INJECT': {
+      // De-dupe by id: if a message with this id already exists, merge
+      // instead of duplicating. Avoids double-render when external code
+      // re-emits the same payload (Centrifugo replay, SWR retry, …).
+      const existingIdx = state.messages.findIndex((m) => m.id === action.message.id);
+      if (existingIdx >= 0) {
+        const messages = state.messages.slice();
+        const prev = messages[existingIdx]!;
+        messages[existingIdx] = {
+          ...prev,
+          ...action.message,
+          version: (prev.version ?? 0) + 1,
+        };
+        return { ...state, messages };
+      }
+      const next =
+        action.position === 'prepend'
+          ? [action.message, ...state.messages]
+          : [...state.messages, action.message];
+      return { ...state, messages: next };
+    }
+
+    case 'MESSAGE_PATCH': {
+      const messages = patchMessageById(state.messages, action.id, (m) => ({
+        ...m,
+        ...action.patch,
+        version: (m.version ?? 0) + 1,
+      }));
+      return { ...state, messages };
+    }
+
     case 'MESSAGES_CLEAR':
       return {
         ...state,

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

@@ -11,3 +11,16 @@ export type {
   StreamOptions,
   SendOptions,
 } from './types';
+
+export {
+  createPydanticAIChatTransport,
+  type PydanticAIChatTransportOpts,
+} from './pydantic-ai-transport';
+
+export {
+  createToolIdQueue,
+  mapPydanticAIEvent,
+  createPydanticAISSEMap,
+  type PydanticAIEvent,
+  type ToolIdQueue,
+} from './mappers';

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

@@ -0,0 +1,6 @@
+export {
+  createToolIdQueue,
+  mapPydanticAIEvent,
+  createPydanticAISSEMap,
+} from './pydantic-ai';
+export type { PydanticAIEvent, ToolIdQueue } from './pydantic-ai';

package/src/tools/Chat/core/transport/mappers/pydantic-ai.ts

@@ -0,0 +1,142 @@
+/**
+ * Pydantic-AI SSE event mapper.
+ *
+ * Translates the event shape emitted by pydantic-AI–style Django backends
+ * (text_delta / tool_call / tool_result / done / error / approval_required)
+ * into the canonical `ChatStreamEvent` stream consumed by the Chat reducer.
+ *
+ * Backends that don't expose a stable `tool_call_id` are supported via a
+ * per-stream FIFO queue keyed by tool name. The earlier "Map<name, toolId>"
+ * approach lost the first toolId when a tool was invoked twice in one turn
+ * (e.g. `list_tasks` for search and again for confirmation) — using a queue
+ * keeps each call/result pair correctly matched.
+ */
+
+import type { ChatStreamEvent } from '../../../types';
+import type { ParseSSEOptions } from '../sse';
+
+export interface PydanticAIEvent {
+  type:
+    | 'text_delta'
+    | 'tool_call'
+    | 'tool_result'
+    | 'done'
+    | 'error'
+    | 'approval_required';
+  delta?: string;
+  tool?: string;
+  args?: unknown;
+  result?: unknown;
+  /**
+   * Structured frontend payload — present on `tool_result` when the tool has
+   * a `result_schema`. The LLM sees only `result` (compact text); the
+   * frontend uses `data` to render rich UI (e.g. vehicle cards).
+   */
+  data?: unknown;
+  total_tokens?: number;
+  error?: string;
+  tool_call_id?: string;
+  session_id?: string;
+}
+
+/** Per-stream FIFO queue keyed by tool name. Created via `createToolIdQueue`. */
+export interface ToolIdQueue {
+  /** Allocate a new toolId for a `tool_call` event and enqueue it under `name`. */
+  push(name: string): string;
+  /** Pop the oldest toolId for `name` (or return an orphan marker if none). */
+  shift(name: string): string;
+  /** Reset all queues (e.g. on stream close). */
+  clear(): void;
+}
+
+export function createToolIdQueue(): ToolIdQueue {
+  const queues = new Map<string, string[]>();
+  let counter = 0;
+  return {
+    push(name) {
+      const id = `${name}-${counter++}-${Date.now()}`;
+      const q = queues.get(name) ?? [];
+      q.push(id);
+      queues.set(name, q);
+      return id;
+    },
+    shift(name) {
+      return queues.get(name)?.shift() ?? `${name}-orphan-${counter++}`;
+    },
+    clear() {
+      queues.clear();
+    },
+  };
+}
+
+/**
+ * Translate a single pydantic-AI event into zero or more `ChatStreamEvent`s.
+ * Pass a `ToolIdQueue` shared across the lifetime of one stream so that
+ * `tool_call` / `tool_result` pairs match correctly.
+ */
+export function* mapPydanticAIEvent(
+  ev: PydanticAIEvent,
+  toolIds: ToolIdQueue,
+): Generator<ChatStreamEvent> {
+  switch (ev.type) {
+    case 'text_delta':
+      if (ev.delta) yield { type: 'chunk', delta: ev.delta };
+      return;
+
+    case 'tool_call': {
+      const name = ev.tool ?? 'tool';
+      const toolId = toolIds.push(name);
+      yield { type: 'tool_call_start', toolId, name, input: ev.args };
+      return;
+    }
+
+    case 'tool_result': {
+      const name = ev.tool ?? 'tool';
+      const toolId = toolIds.shift(name);
+      // `data` is the structured JSON for the frontend; `result` is the LLM-facing text.
+      const output: unknown = ev.data !== undefined ? ev.data : ev.result;
+      yield { type: 'tool_call_end', toolId, output, status: 'success' };
+      return;
+    }
+
+    case 'done':
+      yield { type: 'message_end', tokensOut: ev.total_tokens };
+      return;
+
+    case 'error':
+      yield { type: 'error', code: 'backend_error', message: ev.error ?? 'Unknown error' };
+      return;
+
+    case 'approval_required':
+      // Surfaced via a separate side-channel (see ResumableTransport in
+      // host packages). Not translated to a ChatStreamEvent here.
+      return;
+  }
+}
+
+/**
+ * Convenience factory: returns a `ParseSSEOptions['map']` callback that
+ * decodes raw SSE frames as `PydanticAIEvent` JSON and yields zero or
+ * more `ChatStreamEvent`s through `mapPydanticAIEvent`.
+ *
+ * Allocates an internal `ToolIdQueue` — call this once per stream.
+ */
+export function createPydanticAISSEMap(): NonNullable<ParseSSEOptions['map']> {
+  const toolIds = createToolIdQueue();
+  return (raw) => {
+    if (!raw.data) return null;
+    let parsed: PydanticAIEvent;
+    try {
+      parsed = JSON.parse(raw.data) as PydanticAIEvent;
+    } catch {
+      return null;
+    }
+    const out: ChatStreamEvent[] = [];
+    for (const evt of mapPydanticAIEvent(parsed, toolIds)) {
+      out.push(evt);
+    }
+    if (out.length === 0) return null;
+    if (out.length === 1) return out[0]!;
+    return out;
+  };
+}

package/src/tools/Chat/core/transport/pydantic-ai-transport.ts

@@ -0,0 +1,208 @@
+/**
+ * High-level transport factory for pydantic-AI–style backends.
+ *
+ * Composes:
+ *   - `parseSSE` for spec-compliant SSE framing (multi-line `data:`, comments, idle timeout).
+ *   - `createPydanticAISSEMap` for normalizing pydantic-AI events into `ChatStreamEvent`.
+ *
+ * Use when your backend speaks the canonical pydantic-AI stream shape
+ * (`text_delta` / `tool_call` / `tool_result` / `done` / `error`).
+ * URL building, auth headers, history loading, and optional session
+ * bootstrapping are caller responsibilities — pass them in.
+ */
+
+import type {
+  ChatMessage,
+  ChatStreamEvent,
+  ChatTransport,
+  CreateSessionOptions,
+  HistoryPage,
+  SendOptions,
+  SessionInfo,
+  StreamOptions,
+} from '../../types';
+import { TransportError } from './types';
+import { parseSSE } from './sse';
+import {
+  createPydanticAISSEMap,
+  mapPydanticAIEvent,
+  createToolIdQueue,
+  type PydanticAIEvent,
+} from './mappers';
+
+export interface PydanticAIChatTransportOpts {
+  /**
+   * Build the SSE stream URL for a user message turn.
+   * @example (sessionId, message) => `${base}/stream?session_id=${sessionId}&message=${encodeURIComponent(message)}`
+   */
+  buildStreamUrl: (sessionId: string, message: string) => string | URL;
+
+  /** Optional history loader. If omitted, `loadHistory` returns an empty page. */
+  loadHistory?: (sessionId: string, cursor?: string | null) => Promise<HistoryPage>;
+
+  /**
+   * Optional session bootstrap. Called from `createSession`. Useful for
+   * backends that need a `POST /sessions` round-trip or want to pre-seed
+   * history.
+   */
+  bootstrapSession?: (opts?: CreateSessionOptions) => Promise<SessionInfo>;
+
+  /** Optional session teardown. */
+  closeSession?: (sessionId: string) => Promise<void>;
+
+  /**
+   * Optional non-streaming send (for hosts that need a buffered fallback,
+   * e.g. when the user disables streaming). Defaults to throwing — most
+   * hosts only use streaming.
+   */
+  send?: (
+    sessionId: string,
+    content: string,
+    options?: SendOptions,
+  ) => Promise<ChatMessage>;
+
+  /** Request headers (Authorization, content-type, etc.). */
+  buildHeaders?: () => HeadersInit | Promise<HeadersInit>;
+
+  /** Override fetch (tests, retry layers). */
+  fetchImpl?: typeof fetch;
+
+  /**
+   * HTTP method for the stream request. Defaults to `'POST'` with
+   * `{ content, attachments, metadata }` JSON body. Set to `'GET'` if
+   * your backend embeds the message in the URL via `buildStreamUrl`.
+   */
+  streamMethod?: 'GET' | 'POST';
+
+  /** Idle timeout for the SSE connection, in ms. Forwarded to `parseSSE`. */
+  idleTimeoutMs?: number;
+
+  /**
+   * Side-channel for events that don't translate to `ChatStreamEvent`
+   * (e.g. `approval_required` — surfaces interactive prompts outside the
+   * normal message stream). Called synchronously while parsing the SSE
+   * frame; mutate caller-owned state, don't `await` long work here.
+   */
+  onPydanticEvent?: (event: PydanticAIEvent) => void;
+}
+
+const DEFAULT_SESSION_ID = 'default';
+
+function mapStatusToCode(status: number): string {
+  if (status === 401 || status === 403) return 'unauthorized';
+  if (status === 404) return 'not_found';
+  if (status === 408) return 'timeout';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500) return 'server_error';
+  return 'error';
+}
+
+export function createPydanticAIChatTransport(
+  opts: PydanticAIChatTransportOpts,
+): ChatTransport {
+  const fetchImpl = opts.fetchImpl ?? fetch.bind(globalThis);
+  const streamMethod = opts.streamMethod ?? 'POST';
+
+  async function resolvedHeaders(extra?: Record<string, string>): Promise<Headers> {
+    const base = opts.buildHeaders ? await opts.buildHeaders() : {};
+    const headers = new Headers(base as HeadersInit);
+    if (extra) {
+      for (const [k, v] of Object.entries(extra)) headers.set(k, v);
+    }
+    return headers;
+  }
+
+  return {
+    async createSession(createOpts) {
+      if (opts.bootstrapSession) return opts.bootstrapSession(createOpts);
+      return { sessionId: DEFAULT_SESSION_ID };
+    },
+
+    async loadHistory(sessionId, cursor) {
+      if (opts.loadHistory) return opts.loadHistory(sessionId, cursor);
+      return { messages: [], hasMore: false, nextCursor: null };
+    },
+
+    async *stream(
+      sessionId: string,
+      content: string,
+      options: StreamOptions,
+    ): AsyncGenerator<ChatStreamEvent, void, void> {
+      const url = opts.buildStreamUrl(sessionId, content);
+
+      const headers = await resolvedHeaders({ Accept: 'text/event-stream' });
+      const init: RequestInit = {
+        method: streamMethod,
+        headers,
+        signal: options.signal,
+      };
+      if (streamMethod === 'POST') {
+        headers.set('Content-Type', 'application/json');
+        init.body = JSON.stringify({
+          content,
+          attachments: options.attachments ?? [],
+          metadata: options.metadata ?? {},
+        });
+      }
+
+      const res = await fetchImpl(typeof url === 'string' ? url : url.toString(), init);
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new TransportError(
+          `stream failed (${res.status}): ${text || res.statusText}`,
+          mapStatusToCode(res.status),
+        );
+      }
+
+      const sideChannel = opts.onPydanticEvent;
+      if (!sideChannel) {
+        yield* parseSSE(res, {
+          signal: options.signal,
+          idleTimeoutMs: opts.idleTimeoutMs,
+          map: createPydanticAISSEMap(),
+        });
+        return;
+      }
+
+      // Side-channel mode: parse the raw pydantic event, fire callback,
+      // then forward through the canonical mapper.
+      const toolIds = createToolIdQueue();
+      yield* parseSSE(res, {
+        signal: options.signal,
+        idleTimeoutMs: opts.idleTimeoutMs,
+        map: (raw) => {
+          if (!raw.data) return null;
+          let parsed: PydanticAIEvent;
+          try {
+            parsed = JSON.parse(raw.data) as PydanticAIEvent;
+          } catch {
+            return null;
+          }
+          try {
+            sideChannel(parsed);
+          } catch {
+            // Side-channel handler must not break the stream.
+          }
+          const out: ChatStreamEvent[] = [];
+          for (const evt of mapPydanticAIEvent(parsed, toolIds)) out.push(evt);
+          if (out.length === 0) return null;
+          if (out.length === 1) return out[0]!;
+          return out;
+        },
+      });
+    },
+
+    async send(sessionId, content, sendOpts) {
+      if (opts.send) return opts.send(sessionId, content, sendOpts);
+      throw new TransportError(
+        'Buffered send is not supported by this transport',
+        'unsupported',
+      );
+    },
+
+    async closeSession(sessionId) {
+      if (opts.closeSession) await opts.closeSession(sessionId);
+    },
+  };
+}

package/src/tools/Chat/core/transport/sse.ts

@@ -16,9 +16,10 @@ interface RawEvent {
 
 export interface ParseSSEOptions {
   signal?: AbortSignal;
-  /** Map a raw SSE event to a ChatStreamEvent. Default: parse `data` as JSON
-   *  and assume the JSON shape already matches `ChatStreamEvent`. */
-  map?: (raw: RawEvent) => ChatStreamEvent | null;
+  /** Map a raw SSE event to zero, one, or many `ChatStreamEvent`s.
+   *  Default: parse `data` as JSON and assume the JSON shape already
+   *  matches `ChatStreamEvent`. */
+  map?: (raw: RawEvent) => ChatStreamEvent | ChatStreamEvent[] | null;
   idleTimeoutMs?: number;
 }
 
@@ -75,7 +76,13 @@ export async function* parseSSE(
 
         const raw = parseEventBlock(rawBlock);
         const evt = map(raw);
-        if (evt) yield evt;
+        if (evt) {
+          if (Array.isArray(evt)) {
+            for (const e of evt) yield e;
+          } else {
+            yield evt;
+          }
+        }
 
         separator = buffer.indexOf('\n\n');
       }
@@ -87,7 +94,13 @@ export async function* parseSSE(
     if (buffer.trim()) {
       const raw = parseEventBlock(buffer);
       const evt = map(raw);
-      if (evt) yield evt;
+      if (evt) {
+        if (Array.isArray(evt)) {
+          for (const e of evt) yield e;
+        } else {
+          yield evt;
+        }
+      }
     }
   } finally {
     try {

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

@@ -30,3 +30,28 @@ export {
   type UseAutoFocusOnStreamEndOptions,
   type Focusable,
 } from './useAutoFocusOnStreamEnd';
+export {
+  useChatReset,
+  type UseChatResetOptions,
+  type UseChatResetReturn,
+} from './useChatReset';
+export {
+  useVisitorFingerprint,
+  type UseVisitorFingerprintOptions,
+} from './useVisitorFingerprint';
+export {
+  useChatDockPrefs,
+  DEFAULT_DOCK_PREFS,
+  type ChatDockPrefs,
+  type UseChatDockPrefsOptions,
+  type UseChatDockPrefsReturn,
+} from './useChatDockPrefs';
+export {
+  useFocusOnEmptyClick,
+  type UseFocusOnEmptyClickOptions,
+} from './useFocusOnEmptyClick';
+export {
+  useChatUnread,
+  type UseChatUnreadOptions,
+  type UseChatUnreadReturn,
+} from './useChatUnread';

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

@@ -117,12 +117,14 @@ export function useAutoFocusOnStreamEnd(
  *
  * No-op when called outside a `<ChatProvider>`.
  */
-export function useRegisterComposer(focus: () => void): void {
+export function useRegisterComposer(handle: ComposerHandle): void {
   const ctx = useChatContextOptional();
   const register = ctx?.registerComposer;
+  const focus = handle.focus;
+  const moveCursorToEnd = handle.moveCursorToEnd;
   useEffect(() => {
     if (!register) return;
-    register({ focus });
+    register({ focus, moveCursorToEnd });
     return () => register(null);
-  }, [register, focus]);
+  }, [register, focus, moveCursorToEnd]);
 }