@djangocfg/ui-tools 2.1.334 → 2.1.336

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

@@ -0,0 +1,116 @@
+/**
+ * Server-Sent Events parser as an AsyncGenerator.
+ *
+ * Yields parsed events from a `Response` body. Handles the split-read case
+ * where `event:` and `data:` arrive in separate TCP packets. Skips malformed
+ * JSON gracefully. Honors AbortSignal (caller passes one to fetch).
+ */
+
+import type { ChatStreamEvent } from '../../types';
+import { LIMITS } from '../../config';
+
+interface RawEvent {
+  event?: string;
+  data?: string;
+}
+
+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;
+  idleTimeoutMs?: number;
+}
+
+const DEFAULT_MAP = (raw: RawEvent): ChatStreamEvent | null => {
+  if (!raw.data) return null;
+  try {
+    const parsed = JSON.parse(raw.data) as ChatStreamEvent;
+    if (raw.event && !('type' in parsed)) {
+      return { ...(parsed as object), type: raw.event } as ChatStreamEvent;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+export async function* parseSSE(
+  response: Response,
+  options: ParseSSEOptions = {},
+): AsyncGenerator<ChatStreamEvent, void, void> {
+  if (!response.body) {
+    throw new Error('SSE response has no body');
+  }
+
+  const map = options.map ?? DEFAULT_MAP;
+  const idleMs = options.idleTimeoutMs ?? LIMITS.sseIdleMs;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let lastChunkAt = Date.now();
+
+  const idleCheck = () => {
+    if (Date.now() - lastChunkAt > idleMs) {
+      throw new Error(`SSE idle timeout (${idleMs}ms)`);
+    }
+  };
+
+  try {
+    while (true) {
+      if (options.signal?.aborted) {
+        return;
+      }
+      const { value, done } = await reader.read();
+      if (done) break;
+
+      lastChunkAt = Date.now();
+      buffer += decoder.decode(value, { stream: true });
+
+      // Split on blank line which delimits SSE events.
+      let separator = buffer.indexOf('\n\n');
+      while (separator !== -1) {
+        const rawBlock = buffer.slice(0, separator);
+        buffer = buffer.slice(separator + 2);
+
+        const raw = parseEventBlock(rawBlock);
+        const evt = map(raw);
+        if (evt) yield evt;
+
+        separator = buffer.indexOf('\n\n');
+      }
+
+      idleCheck();
+    }
+
+    // Flush any trailing partial event.
+    if (buffer.trim()) {
+      const raw = parseEventBlock(buffer);
+      const evt = map(raw);
+      if (evt) yield evt;
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function parseEventBlock(block: string): RawEvent {
+  const out: RawEvent = {};
+  const lines = block.split(/\r?\n/);
+  const dataLines: string[] = [];
+  for (const line of lines) {
+    if (!line || line.startsWith(':')) continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const field = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).replace(/^ /, '');
+    if (field === 'event') out.event = value;
+    else if (field === 'data') dataLines.push(value);
+  }
+  if (dataLines.length) out.data = dataLines.join('\n');
+  return out;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Transport surface re-export. Lives in core so transport implementations
+ * never need to reach into the public types module.
+ */
+
+export type {
+  ChatTransport,
+  ChatStreamEvent,
+  CreateSessionOptions,
+  SessionInfo,
+  HistoryPage,
+  StreamOptions,
+  SendOptions,
+} from '../../types';
+
+export class TransportError extends Error {
+  code: string;
+
+  constructor(message: string, code = 'transport_error') {
+    super(message);
+    this.name = 'TransportError';
+    this.code = code;
+  }
+}

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

@@ -0,0 +1,26 @@
+'use client';
+
+export { useChat, type UseChatConfig, type UseChatReturn } from './useChat';
+export {
+  useChatComposer,
+  type UseChatComposerOptions,
+  type UseChatComposerReturn,
+} from './useChatComposer';
+export {
+  useChatScroll,
+  type UseChatScrollOptions,
+  type UseChatScrollReturn,
+} from './useChatScroll';
+export { useChatHistory, type UseChatHistoryOptions } from './useChatHistory';
+export {
+  useChatLayout,
+  type UseChatLayoutConfig,
+  type UseChatLayoutReturn,
+} from './useChatLayout';
+export { useChatAudio } from './useChatAudio';
+export {
+  useChatLightbox,
+  type UseChatLightboxReturn,
+  type ChatLightboxState,
+  type ChatLightboxScope,
+} from './useChatLightbox';

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

@@ -0,0 +1,440 @@
+'use client';
+
+import { useCallback, useEffect, useReducer, useRef } from 'react';
+
+import type {
+  ChatAttachment,
+  ChatMessage,
+  ChatPersona,
+  ChatStreamEvent,
+  ChatTransport,
+  ChatToolCall,
+} from '../types';
+import { LIMITS } from '../config';
+import {
+  type ChatState,
+  initialState,
+  reducer,
+  type ChatAction,
+} from '../core/reducer';
+import { createId } from '../core/ids';
+import { createTokenBuffer } from '../core/markdown';
+
+export interface UseChatConfig {
+  transport: ChatTransport;
+  initialSessionId?: string;
+  autoCreateSession?: boolean;
+  streaming?: boolean;
+  pageSize?: number;
+  onError?: (err: Error) => void;
+  /** Fires once an assistant message finishes streaming (or buffered send returns). */
+  onMessageEnd?: (msg: ChatMessage) => void;
+  /** Fires after a user message is added to the state (right before streaming starts). */
+  onMessageSent?: (msg: ChatMessage) => void;
+  /** Fires when the assistant placeholder is created (first byte / pre-stream). */
+  onStreamStart?: (assistantMessageId: string) => void;
+  metadata?: Record<string, unknown>;
+  /** Stamped on outgoing user messages as `message.sender`. */
+  userPersona?: ChatPersona;
+}
+
+export interface UseChatReturn extends ChatState {
+  sendMessage: (content: string, attachments?: ChatAttachment[]) => Promise<void>;
+  cancelStream: () => void;
+  regenerate: (messageId?: string) => Promise<void>;
+  editMessage: (id: string, content: string) => Promise<void>;
+  deleteMessage: (id: string) => void;
+  clearMessages: () => void;
+  loadMore: () => Promise<void>;
+  newSession: () => Promise<void>;
+  lastError: Error | null;
+}
+
+export function useChat(config: UseChatConfig): UseChatReturn {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  const stateRef = useRef(state);
+  stateRef.current = state;
+
+  const abortRef = useRef<AbortController | null>(null);
+  const lastErrorRef = useRef<Error | null>(null);
+  const initRef = useRef(false);
+  const streamingMsgIdRef = useRef<string | null>(null);
+
+  const { transport, autoCreateSession = true, streaming = true, pageSize = LIMITS.pageSize } =
+    config;
+
+  // Initial session bootstrap.
+  useEffect(() => {
+    if (initRef.current) return;
+    initRef.current = true;
+
+    let cancelled = false;
+    const run = async () => {
+      try {
+        if (config.initialSessionId) {
+          dispatch({
+            type: 'SESSION_SET',
+            sessionId: config.initialSessionId,
+          });
+          dispatch({ type: 'HISTORY_LOAD_START' });
+          const page = await transport.loadHistory(config.initialSessionId, null, pageSize);
+          if (cancelled) return;
+          dispatch({
+            type: 'HISTORY_LOAD_DONE',
+            messages: page.messages,
+            hasMore: page.hasMore,
+            cursor: page.nextCursor,
+          });
+        } else if (autoCreateSession) {
+          const info = await transport.createSession({ metadata: config.metadata });
+          if (cancelled) return;
+          dispatch({
+            type: 'SESSION_SET',
+            sessionId: info.sessionId,
+            messages: info.messages ?? [],
+            hasMore: info.hasMore ?? false,
+            cursor: info.cursor ?? null,
+          });
+        }
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        lastErrorRef.current = e;
+        dispatch({ type: 'ERROR_SET', error: e.message });
+        config.onError?.(e);
+      }
+    };
+    void run();
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const consumeStream = useCallback(
+    async (
+      sessionId: string,
+      content: string,
+      attachments?: ChatAttachment[],
+    ): Promise<void> => {
+      const ctrl = new AbortController();
+      abortRef.current = ctrl;
+      const assistantId = createId('a');
+      streamingMsgIdRef.current = assistantId;
+
+      dispatch({ type: 'STREAM_START', id: assistantId });
+      config.onStreamStart?.(assistantId);
+
+      const tokenBuffer = createTokenBuffer((delta) =>
+        dispatch({ type: 'STREAM_CHUNK', delta }),
+      );
+
+      let serverMessageId: string | null = null;
+
+      try {
+        const iterator = transport.stream(sessionId, content, {
+          signal: ctrl.signal,
+          attachments,
+          metadata: config.metadata,
+        });
+
+        for await (const ev of iterator) {
+          if (ctrl.signal.aborted) break;
+          handleEvent(ev);
+        }
+        tokenBuffer.flush();
+
+        // If transport never emitted message_end, finalize manually.
+        if (stateRef.current.isStreaming) {
+          dispatch({ type: 'STREAM_DONE', id: assistantId });
+        }
+
+        const finalMsg = stateRef.current.messages.find((m) => m.id === assistantId);
+        if (finalMsg) config.onMessageEnd?.(finalMsg);
+      } catch (err) {
+        tokenBuffer.close();
+        if (ctrl.signal.aborted) {
+          const partial =
+            stateRef.current.messages.find((m) => m.id === assistantId)?.content ?? '';
+          dispatch({ type: 'STREAM_CANCELLED', id: assistantId, partialText: partial });
+          return;
+        }
+        const e = err instanceof Error ? err : new Error(String(err));
+        lastErrorRef.current = e;
+        dispatch({ type: 'STREAM_ERROR', id: assistantId, message: e.message });
+        config.onError?.(e);
+      } finally {
+        tokenBuffer.close();
+        if (abortRef.current === ctrl) abortRef.current = null;
+        streamingMsgIdRef.current = null;
+      }
+
+      function handleEvent(ev: ChatStreamEvent) {
+        switch (ev.type) {
+          case 'message_start':
+            serverMessageId = ev.messageId;
+            return;
+          case 'chunk':
+            tokenBuffer.push(ev.delta);
+            return;
+          case 'tool_activity':
+            tokenBuffer.flush();
+            dispatch({ type: 'STREAM_TOOL_ACTIVITY', tool: ev.tool });
+            return;
+          case 'tool_call_start': {
+            tokenBuffer.flush();
+            const toolCall: ChatToolCall = {
+              id: ev.toolId,
+              name: ev.name,
+              input: ev.input,
+              status: 'running',
+              startedAt: Date.now(),
+              sourceHostname: ev.sourceHostname,
+            };
+            dispatch({
+              type: 'TOOL_CALL_START',
+              messageId: assistantId,
+              toolCall,
+            });
+            return;
+          }
+          case 'tool_call_delta':
+            dispatch({
+              type: 'TOOL_CALL_DELTA',
+              messageId: assistantId,
+              toolId: ev.toolId,
+              delta: ev.delta,
+            });
+            return;
+          case 'tool_call_end':
+            dispatch({
+              type: 'TOOL_CALL_END',
+              messageId: assistantId,
+              toolId: ev.toolId,
+              output: ev.output,
+              status: ev.status,
+            });
+            return;
+          case 'message_end':
+            tokenBuffer.flush();
+            dispatch({
+              type: 'STREAM_DONE',
+              id: assistantId,
+              tokensIn: ev.tokensIn,
+              tokensOut: ev.tokensOut,
+              sources: ev.sources,
+            });
+            return;
+          case 'error':
+            tokenBuffer.flush();
+            dispatch({
+              type: 'STREAM_ERROR',
+              id: assistantId,
+              message: ev.message,
+            });
+            return;
+        }
+        // unreachable; prevents unused-var on serverMessageId
+        void serverMessageId;
+      }
+    },
+    [transport, config],
+  );
+
+  const consumeBuffered = useCallback(
+    async (sessionId: string, content: string, attachments?: ChatAttachment[]): Promise<void> => {
+      const ctrl = new AbortController();
+      abortRef.current = ctrl;
+      try {
+        const reply = await transport.send(sessionId, content, {
+          signal: ctrl.signal,
+          attachments,
+          metadata: config.metadata,
+        });
+        const placeholderId = createId('a');
+        dispatch({ type: 'STREAM_START', id: placeholderId });
+        config.onStreamStart?.(placeholderId);
+        dispatch({ type: 'STREAM_CHUNK', delta: reply.content });
+        dispatch({ type: 'STREAM_DONE', id: placeholderId });
+        config.onMessageEnd?.(reply);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        lastErrorRef.current = e;
+        dispatch({ type: 'STREAM_ERROR', message: e.message });
+        config.onError?.(e);
+      } finally {
+        if (abortRef.current === ctrl) abortRef.current = null;
+      }
+    },
+    [transport, config],
+  );
+
+  const sendMessage = useCallback(
+    async (content: string, attachments?: ChatAttachment[]) => {
+      const sessionId = stateRef.current.sessionId;
+      if (!sessionId) {
+        const e = new Error('No active session');
+        lastErrorRef.current = e;
+        dispatch({ type: 'ERROR_SET', error: e.message });
+        config.onError?.(e);
+        return;
+      }
+      if (!content.trim() && !(attachments && attachments.length > 0)) return;
+      if (stateRef.current.isStreaming) return;
+
+      const userMsg: ChatMessage = {
+        id: createId('u'),
+        role: 'user',
+        content,
+        createdAt: Date.now(),
+        attachments,
+        sender: config.userPersona,
+      };
+      dispatch({ type: 'MESSAGE_USER_ADD', message: userMsg });
+      config.onMessageSent?.(userMsg);
+
+      if (streaming) {
+        await consumeStream(sessionId, content, attachments);
+      } else {
+        await consumeBuffered(sessionId, content, attachments);
+      }
+    },
+    [streaming, consumeStream, consumeBuffered, config],
+  );
+
+  const cancelStream = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
+
+  const regenerate = useCallback(
+    async (messageId?: string) => {
+      const messages = stateRef.current.messages;
+      let targetUserIdx = -1;
+      if (messageId) {
+        const idx = messages.findIndex((m) => m.id === messageId);
+        if (idx !== -1) {
+          targetUserIdx =
+            messages[idx].role === 'user' ? idx : findPreviousUserIndex(messages, idx);
+        }
+      } else {
+        targetUserIdx = findLastUserIndex(messages);
+      }
+      if (targetUserIdx === -1) return;
+      const userMsg = messages[targetUserIdx];
+      // Drop everything after this user message.
+      for (let i = messages.length - 1; i > targetUserIdx; i -= 1) {
+        dispatch({ type: 'MESSAGE_DELETE', id: messages[i].id });
+      }
+      const sessionId = stateRef.current.sessionId;
+      if (!sessionId) return;
+      if (streaming) {
+        await consumeStream(sessionId, userMsg.content, userMsg.attachments);
+      } else {
+        await consumeBuffered(sessionId, userMsg.content, userMsg.attachments);
+      }
+    },
+    [streaming, consumeStream, consumeBuffered],
+  );
+
+  const editMessage = useCallback(
+    async (id: string, content: string) => {
+      dispatch({ type: 'MESSAGE_EDIT', id, content });
+      const msg = stateRef.current.messages.find((m) => m.id === id);
+      if (msg?.role === 'user') {
+        await regenerate(id);
+      }
+    },
+    [regenerate],
+  );
+
+  const deleteMessage = useCallback((id: string) => {
+    dispatch({ type: 'MESSAGE_DELETE', id });
+  }, []);
+
+  const clearMessages = useCallback(() => {
+    abortRef.current?.abort();
+    dispatch({ type: 'MESSAGES_CLEAR' });
+  }, []);
+
+  const loadMore = useCallback(async () => {
+    const sessionId = stateRef.current.sessionId;
+    if (!sessionId) return;
+    if (stateRef.current.isLoadingMore || !stateRef.current.hasMore) return;
+    dispatch({ type: 'HISTORY_MORE_START' });
+    try {
+      const page = await transport.loadHistory(
+        sessionId,
+        stateRef.current.oldestCursor,
+        pageSize,
+      );
+      dispatch({
+        type: 'HISTORY_MORE_DONE',
+        messages: page.messages,
+        hasMore: page.hasMore,
+        cursor: page.nextCursor,
+      });
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      lastErrorRef.current = e;
+      dispatch({ type: 'ERROR_SET', error: e.message });
+      config.onError?.(e);
+    }
+  }, [transport, pageSize, config]);
+
+  const newSession = useCallback(async () => {
+    abortRef.current?.abort();
+    const previous = stateRef.current.sessionId;
+    if (previous) {
+      try {
+        await transport.closeSession(previous);
+      } catch {
+        /* ignore */
+      }
+    }
+    dispatch({ type: 'MESSAGES_CLEAR' });
+    try {
+      const info = await transport.createSession({ metadata: config.metadata });
+      dispatch({
+        type: 'SESSION_SET',
+        sessionId: info.sessionId,
+        messages: info.messages ?? [],
+        hasMore: info.hasMore ?? false,
+        cursor: info.cursor ?? null,
+      });
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      lastErrorRef.current = e;
+      dispatch({ type: 'ERROR_SET', error: e.message });
+      config.onError?.(e);
+    }
+  }, [transport, config]);
+
+  return {
+    ...state,
+    sendMessage,
+    cancelStream,
+    regenerate,
+    editMessage,
+    deleteMessage,
+    clearMessages,
+    loadMore,
+    newSession,
+    lastError: lastErrorRef.current,
+  };
+}
+
+function findLastUserIndex(messages: ChatMessage[]): number {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i].role === 'user') return i;
+  }
+  return -1;
+}
+
+function findPreviousUserIndex(messages: ChatMessage[], from: number): number {
+  for (let i = from - 1; i >= 0; i -= 1) {
+    if (messages[i].role === 'user') return i;
+  }
+  return -1;
+}
+
+// Suppress unused-action warnings if the action union grows.
+type _Used = ChatAction;