@djangocfg/ui-tools 2.1.336 → 2.1.337

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

@@ -18,6 +18,7 @@ import {
   type ChatAction,
 } from '../core/reducer';
 import { createId } from '../core/ids';
+import { getChatLogger } from '../core/logger';
 import { createTokenBuffer } from '../core/markdown';
 
 export interface UseChatConfig {
@@ -36,6 +37,12 @@ export interface UseChatConfig {
   metadata?: Record<string, unknown>;
   /** Stamped on outgoing user messages as `message.sender`. */
   userPersona?: ChatPersona;
+  /**
+   * Enable verbose dev-mode logging (consola, namespace `chat:*`).
+   * Defaults to `isDev` from `@djangocfg/ui-core/lib`. Pass `false` to silence
+   * even in development; `true` to force on in production.
+   */
+  debug?: boolean;
 }
 
 export interface UseChatReturn extends ChatState {
@@ -59,9 +66,15 @@ export function useChat(config: UseChatConfig): UseChatReturn {
   const lastErrorRef = useRef<Error | null>(null);
   const initRef = useRef(false);
   const streamingMsgIdRef = useRef<string | null>(null);
+  // Promise resolved once the initial session is available (or `null` when the
+  // bootstrap finished without producing one — e.g. autoCreateSession=false).
+  // Action methods (sendMessage, regenerate, …) await this so users who type
+  // before the first network round-trip resolves don't hit "No active session".
+  const bootstrapRef = useRef<Promise<string | null> | null>(null);
 
   const { transport, autoCreateSession = true, streaming = true, pageSize = LIMITS.pageSize } =
     config;
+  const log = getChatLogger(config.debug);
 
   // Initial session bootstrap.
   useEffect(() => {
@@ -69,25 +82,50 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     initRef.current = true;
 
     let cancelled = false;
-    const run = async () => {
+    // Show "loading" state immediately so the UI doesn't look idle while we
+    // wait for createSession / loadHistory to come back.
+    if (config.initialSessionId || autoCreateSession) {
+      dispatch({ type: 'HISTORY_LOAD_START' });
+    }
+
+    log.bootstrap.info('start', {
+      mode: config.initialSessionId ? 'resume' : autoCreateSession ? 'create' : 'idle',
+      initialSessionId: config.initialSessionId,
+    });
+
+    const run = async (): Promise<string | null> => {
+      const t0 = performance.now();
       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;
+          if (cancelled) {
+            log.bootstrap.debug('cancelled (post-loadHistory)');
+            return null;
+          }
           dispatch({
             type: 'HISTORY_LOAD_DONE',
             messages: page.messages,
             hasMore: page.hasMore,
             cursor: page.nextCursor,
           });
-        } else if (autoCreateSession) {
+          log.bootstrap.success('resumed', {
+            sessionId: config.initialSessionId,
+            messages: page.messages.length,
+            hasMore: page.hasMore,
+            elapsedMs: Math.round(performance.now() - t0),
+          });
+          return config.initialSessionId;
+        }
+        if (autoCreateSession) {
           const info = await transport.createSession({ metadata: config.metadata });
-          if (cancelled) return;
+          if (cancelled) {
+            log.bootstrap.debug('cancelled (post-createSession)');
+            return null;
+          }
           dispatch({
             type: 'SESSION_SET',
             sessionId: info.sessionId,
@@ -95,21 +133,55 @@ export function useChat(config: UseChatConfig): UseChatReturn {
             hasMore: info.hasMore ?? false,
             cursor: info.cursor ?? null,
           });
+          // SESSION_SET implicitly clears `error` and leaves isLoading from
+          // the earlier HISTORY_LOAD_START set; mark history as done so the
+          // composer un-disables.
+          dispatch({
+            type: 'HISTORY_LOAD_DONE',
+            messages: info.messages ?? [],
+            hasMore: info.hasMore ?? false,
+            cursor: info.cursor ?? null,
+          });
+          log.bootstrap.success('created', {
+            sessionId: info.sessionId,
+            resumed: info.resumed ?? false,
+            elapsedMs: Math.round(performance.now() - t0),
+          });
+          return info.sessionId;
         }
+        log.bootstrap.debug('idle (no initialSessionId, autoCreateSession=false)');
+        return null;
       } catch (err) {
+        if (cancelled) {
+          log.bootstrap.debug('cancelled (in catch)');
+          return null;
+        }
         const e = err instanceof Error ? err : new Error(String(err));
         lastErrorRef.current = e;
         dispatch({ type: 'ERROR_SET', error: e.message });
         config.onError?.(e);
+        log.error.error('bootstrap failed', { message: e.message, elapsedMs: Math.round(performance.now() - t0) });
+        return null;
       }
     };
-    void run();
+    bootstrapRef.current = run();
     return () => {
       cancelled = true;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  /** Wait for the initial session bootstrap to settle, then return whatever
+   * sessionId is now in state. Safe to call multiple times. */
+  const awaitSession = useCallback(async (): Promise<string | null> => {
+    if (stateRef.current.sessionId) return stateRef.current.sessionId;
+    if (bootstrapRef.current) {
+      const id = await bootstrapRef.current;
+      if (id) return id;
+    }
+    return stateRef.current.sessionId;
+  }, []);
+
   const consumeStream = useCallback(
     async (
       sessionId: string,
@@ -123,12 +195,16 @@ export function useChat(config: UseChatConfig): UseChatReturn {
 
       dispatch({ type: 'STREAM_START', id: assistantId });
       config.onStreamStart?.(assistantId);
+      log.stream.info('start', { sessionId, assistantId, chars: content.length });
 
       const tokenBuffer = createTokenBuffer((delta) =>
         dispatch({ type: 'STREAM_CHUNK', delta }),
       );
 
       let serverMessageId: string | null = null;
+      let chunkCount = 0;
+      let charsReceived = 0;
+      const t0 = performance.now();
 
       try {
         const iterator = transport.stream(sessionId, content, {
@@ -150,18 +226,26 @@ export function useChat(config: UseChatConfig): UseChatReturn {
 
         const finalMsg = stateRef.current.messages.find((m) => m.id === assistantId);
         if (finalMsg) config.onMessageEnd?.(finalMsg);
+        log.stream.success('done', {
+          assistantId,
+          chunks: chunkCount,
+          chars: charsReceived,
+          elapsedMs: Math.round(performance.now() - t0),
+        });
       } 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 });
+          log.stream.warn('cancelled', { assistantId, partialChars: partial.length });
           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);
+        log.error.error('stream failed', { assistantId, message: e.message });
       } finally {
         tokenBuffer.close();
         if (abortRef.current === ctrl) abortRef.current = null;
@@ -172,13 +256,17 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         switch (ev.type) {
           case 'message_start':
             serverMessageId = ev.messageId;
+            log.stream.debug('message_start', { messageId: ev.messageId });
             return;
           case 'chunk':
             tokenBuffer.push(ev.delta);
+            chunkCount += 1;
+            charsReceived += ev.delta.length;
             return;
           case 'tool_activity':
             tokenBuffer.flush();
             dispatch({ type: 'STREAM_TOOL_ACTIVITY', tool: ev.tool });
+            log.tools.debug('activity', { tool: ev.tool, status: ev.status });
             return;
           case 'tool_call_start': {
             tokenBuffer.flush();
@@ -195,6 +283,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
               messageId: assistantId,
               toolCall,
             });
+            log.tools.info('call_start', { toolId: ev.toolId, name: ev.name });
             return;
           }
           case 'tool_call_delta':
@@ -213,6 +302,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
               output: ev.output,
               status: ev.status,
             });
+            log.tools.info('call_end', { toolId: ev.toolId, status: ev.status });
             return;
           case 'message_end':
             tokenBuffer.flush();
@@ -223,6 +313,11 @@ export function useChat(config: UseChatConfig): UseChatReturn {
               tokensOut: ev.tokensOut,
               sources: ev.sources,
             });
+            log.stream.debug('message_end', {
+              tokensIn: ev.tokensIn,
+              tokensOut: ev.tokensOut,
+              sources: ev.sources?.length ?? 0,
+            });
             return;
           case 'error':
             tokenBuffer.flush();
@@ -231,6 +326,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
               id: assistantId,
               message: ev.message,
             });
+            log.error.error('stream event error', { code: ev.code, message: ev.message });
             return;
         }
         // unreachable; prevents unused-var on serverMessageId
@@ -270,16 +366,31 @@ export function useChat(config: UseChatConfig): UseChatReturn {
 
   const sendMessage = useCallback(
     async (content: string, attachments?: ChatAttachment[]) => {
-      const sessionId = stateRef.current.sessionId;
+      // Wait for the initial session bootstrap if it's still in flight.
+      // Without this, fast typers hit "No active session" before
+      // transport.createSession resolves.
+      log.lifecycle.info('sendMessage', {
+        chars: content.length,
+        attachments: attachments?.length ?? 0,
+        hasSession: !!stateRef.current.sessionId,
+      });
+      const sessionId = await awaitSession();
       if (!sessionId) {
         const e = new Error('No active session');
         lastErrorRef.current = e;
         dispatch({ type: 'ERROR_SET', error: e.message });
         config.onError?.(e);
+        log.error.error('sendMessage aborted: no session');
+        return;
+      }
+      if (!content.trim() && !(attachments && attachments.length > 0)) {
+        log.lifecycle.debug('sendMessage skipped (empty)');
+        return;
+      }
+      if (stateRef.current.isStreaming) {
+        log.lifecycle.debug('sendMessage skipped (already streaming)');
         return;
       }
-      if (!content.trim() && !(attachments && attachments.length > 0)) return;
-      if (stateRef.current.isStreaming) return;
 
       const userMsg: ChatMessage = {
         id: createId('u'),
@@ -298,7 +409,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         await consumeBuffered(sessionId, content, attachments);
       }
     },
-    [streaming, consumeStream, consumeBuffered, config],
+    [streaming, consumeStream, consumeBuffered, config, awaitSession],
   );
 
   const cancelStream = useCallback(() => {
@@ -307,6 +418,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
 
   const regenerate = useCallback(
     async (messageId?: string) => {
+      log.lifecycle.info('regenerate', { messageId: messageId ?? '(last)' });
       const messages = stateRef.current.messages;
       let targetUserIdx = -1;
       if (messageId) {
@@ -324,7 +436,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
       for (let i = messages.length - 1; i > targetUserIdx; i -= 1) {
         dispatch({ type: 'MESSAGE_DELETE', id: messages[i].id });
       }
-      const sessionId = stateRef.current.sessionId;
+      const sessionId = await awaitSession();
       if (!sessionId) return;
       if (streaming) {
         await consumeStream(sessionId, userMsg.content, userMsg.attachments);
@@ -332,7 +444,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         await consumeBuffered(sessionId, userMsg.content, userMsg.attachments);
       }
     },
-    [streaming, consumeStream, consumeBuffered],
+    [streaming, consumeStream, consumeBuffered, awaitSession],
   );
 
   const editMessage = useCallback(
@@ -381,6 +493,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
   }, [transport, pageSize, config]);
 
   const newSession = useCallback(async () => {
+    log.lifecycle.info('newSession', { previous: stateRef.current.sessionId });
     abortRef.current?.abort();
     const previous = stateRef.current.sessionId;
     if (previous) {
@@ -400,11 +513,13 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         hasMore: info.hasMore ?? false,
         cursor: info.cursor ?? null,
       });
+      log.lifecycle.success('newSession ok', { sessionId: info.sessionId });
     } 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);
+      log.error.error('newSession failed', { message: e.message });
     }
   }, [transport, config]);
 

package/src/tools/Chat/index.ts

@@ -109,6 +109,9 @@ export {
 export { useChatLightbox, type UseChatLightboxReturn, type ChatLightboxState } from './hooks';
 export { collectImageAttachments } from './utils/collectImageAttachments';
 
+// Dev logger (consola-based, namespace "chat:*")
+export { getChatLogger, type ChatLogger, type ChatLogScope } from './core/logger';
+
 // Context
 export {
   ChatProvider,

package/dist/ChatRoot-IIYQEWUU.mjs

@@ -1,5 +0,0 @@
-export { ChatRoot } from './chunk-KRETIZU6.mjs';
-import './chunk-2ZLKZ5VR.mjs';
-import './chunk-N2XQF2OL.mjs';
-//# sourceMappingURL=ChatRoot-IIYQEWUU.mjs.map
-//# sourceMappingURL=ChatRoot-IIYQEWUU.mjs.map

package/dist/ChatRoot-UUKTYM4N.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var chunkNRXYYO5V_cjs = require('./chunk-NRXYYO5V.cjs');
-require('./chunk-B5AWZOHJ.cjs');
-require('./chunk-OLISEQHS.cjs');
-
-
-
-Object.defineProperty(exports, "ChatRoot", {
-  enumerable: true,
-  get: function () { return chunkNRXYYO5V_cjs.ChatRoot; }
-});
-//# sourceMappingURL=ChatRoot-UUKTYM4N.cjs.map
-//# sourceMappingURL=ChatRoot-UUKTYM4N.cjs.map