Merge pull request #431 from Mng-dev-ai/improve/frontend-comments-and-renames

Improve frontend naming and add contextual comments

Author: Mng-dev-ai

frontend/src/hooks/useActiveViews.ts

@@ -11,6 +11,9 @@ function arraysEqual(a: ViewType[], b: ViewType[]): boolean {
   return true;
 }
 
+// Derives the list of visible view panes from the mosaic layout. Uses a ref
+// to return a referentially stable array when the leaf set hasn't changed,
+// preventing downstream re-renders from Zustand selector identity changes.
 export function useActiveViews(): ViewType[] {
   const prevRef = useRef<ViewType[]>([]);
 

frontend/src/hooks/useChatStreaming.ts

@@ -72,6 +72,10 @@ function findActiveStreamForChat(chatId: string) {
   return undefined;
 }
 
+// Top-level hook that wires together the streaming pipeline for a single chat view.
+// Composes useStreamCallbacks (envelope processing), useStreamReconnect (resume on
+// navigation), useMessageActions (send/stop), and useInputState (draft persistence).
+// Returns the full set of state and handlers consumed by the chat UI components.
 export function useChatStreaming({
   chatId,
   currentChat,
@@ -152,10 +156,13 @@ export function useChatStreaming({
     onPendingUserMessageIdChange: setPendingUserMessageIdState,
   });
 
+  // Keep the global stream store's callbacks in sync with the latest hook closures.
+  // Streams outlive individual renders, so without this the store would dispatch
+  // events through stale callbacks that close over outdated chatId/messages.
   useEffect(() => {
     if (!chatId) return;
 
-    const updateCallbacks = () => {
+    const syncCallbacksToStore = () => {
       const existingStream = findActiveStreamForChat(chatId);
       if (existingStream) {
         useStreamStore.getState().updateStreamCallbacks(chatId, existingStream.messageId, {
@@ -167,13 +174,13 @@ export function useChatStreaming({
       }
     };
 
-    updateCallbacks();
+    syncCallbacksToStore();
 
     let prevStreams = useStreamStore.getState().activeStreams;
     const unsubscribe = useStreamStore.subscribe((state) => {
       if (state.activeStreams !== prevStreams) {
         prevStreams = state.activeStreams;
-        updateCallbacks();
+        syncCallbacksToStore();
       }
     });
     return () => unsubscribe();
@@ -189,10 +196,13 @@ export function useChatStreaming({
     setMessages([]);
   }
 
+  // Subscribes to the stream store and mirrors active-stream presence into
+  // local React state (streamState, currentMessageId). This is the bridge
+  // between the global EventSource lifecycle and the per-chat UI indicators.
   useEffect(() => {
     if (!chatId) return;
 
-    const syncStreamState = () => {
+    const reconcileStreamState = () => {
       const activeStreamForChat = findActiveStreamForChat(chatId);
 
       if (activeStreamForChat) {
@@ -215,9 +225,9 @@ export function useChatStreaming({
       }
     };
 
-    syncStreamState();
+    reconcileStreamState();
 
-    const unsubscribe = useStreamStore.subscribe(syncStreamState);
+    const unsubscribe = useStreamStore.subscribe(reconcileStreamState);
     return () => unsubscribe();
   }, [chatId]);
 
@@ -261,7 +271,10 @@ export function useChatStreaming({
     replayStream,
   });
 
-  const handleStopStream = useCallback(
+  // Sends stop requests for one or all active streams in the current chat.
+  // Immediately marks the UI as idle (optimistic) and tracks pending stops
+  // so incoming envelopes for the stopping stream are ignored.
+  const stopActiveStreams = useCallback(
     async (messageId?: string) => {
       const pendingIds = new Set<string>();
       const stopPromises: Promise<void>[] = [];
@@ -306,9 +319,9 @@ export function useChatStreaming({
   }, [currentMessageId]);
 
   const handleStop = useCallback(() => {
-    void handleStopStream(currentMessageIdRef.current || undefined);
+    void stopActiveStreams(currentMessageIdRef.current || undefined);
     clearInput();
-  }, [handleStopStream, clearInput]);
+  }, [stopActiveStreams, clearInput]);
 
   useMountEffect(() => {
     cleanupExpiredPdfBlobs();

frontend/src/hooks/useContextUsageState.ts

@@ -13,6 +13,11 @@ interface UseContextUsageStateResult {
   updateContextUsage: (data: ContextUsage, chatId?: string) => void;
 }
 
+// Three sources feed token usage, each arriving at different times:
+// (1) the chat object's cached `context_token_usage` for instant display on
+// navigation, (2) the dedicated context-usage query for accurate numbers
+// after load, and (3) live SSE system envelopes during streaming via
+// `updateContextUsage`. Whichever writes last wins.
 export function useContextUsageState(
   chatId: string | undefined,
   currentChat: Chat | undefined,
@@ -52,6 +57,8 @@ export function useContextUsageState(
     setTokensUsed(contextUsageData.tokens_used ?? 0);
   }, [chatId, contextUsageData]);
 
+  // Called from SSE system envelopes during streaming. Ignores updates for
+  // off-screen chats so token counts don't bleed across chat switches.
   const updateContextUsage = useCallback((data: ContextUsage, incomingChatId?: string) => {
     if (incomingChatId && incomingChatId !== currentChatIdRef.current) {
       return;

frontend/src/hooks/useDragAndDrop.ts

@@ -7,6 +7,9 @@ interface UseDragAndDropOptions {
 
 export function useDragAndDrop({ onFilesDrop, disabled = false }: UseDragAndDropOptions = {}) {
   const [isDragging, setIsDragging] = useState(false);
+  // Tracks enter/leave balance across child elements — dragenter/dragleave
+  // fire for every descendant, so a simple boolean would flicker. Only reset
+  // isDragging when the counter reaches 0 (cursor left the drop zone entirely).
   const dragCounter = useRef(0);
 
   const handleDragIn = useCallback(

frontend/src/hooks/useGlobalStream.ts

@@ -6,45 +6,48 @@ import { chatService } from '@/services/chatService';
 
 interface UseGlobalStreamOptions {
   enabled?: boolean;
-  onValidationComplete?: () => void;
+  onPruneComplete?: () => void;
 }
 
+// On app mount, reconciles the in-memory stream store with the server — streams
+// tracked locally (e.g., across a page refresh) but no longer active on the
+// backend get pruned so the UI doesn't show stale "streaming" indicators.
 export function useGlobalStream(options?: UseGlobalStreamOptions) {
-  const hasValidatedRef = useRef(false);
+  const hasPrunedRef = useRef(false);
   const enabled = options?.enabled ?? true;
-  const onValidationComplete = options?.onValidationComplete;
+  const onPruneComplete = options?.onPruneComplete;
 
   useEffect(() => {
     if (!enabled) return;
-    if (hasValidatedRef.current) return;
-    hasValidatedRef.current = true;
+    if (hasPrunedRef.current) return;
+    hasPrunedRef.current = true;
 
-    const validateStreams = async () => {
+    const pruneStaleStreams = async () => {
       const metadata = useStreamStore.getState().activeStreamMetadata;
 
       if (metadata.length === 0) return;
 
-      const validationPromises = metadata.map(async (streamMeta) => {
+      const prunePromises = metadata.map(async (streamMeta) => {
         try {
           const status = await chatService.checkChatStatus(streamMeta.chatId);
 
           if (!status?.has_active_task) {
             useStreamStore.getState().removeStreamMetadata(streamMeta.chatId);
           }
         } catch (error) {
-          logger.error('Stream validation failed', 'useGlobalStream', error);
+          logger.error('Stream prune check failed', 'useGlobalStream', error);
           useStreamStore.getState().removeStreamMetadata(streamMeta.chatId);
         }
       });
 
-      await Promise.allSettled(validationPromises);
-      onValidationComplete?.();
+      await Promise.allSettled(prunePromises);
+      onPruneComplete?.();
     };
 
-    const timeoutId = setTimeout(validateStreams, 500);
+    const timeoutId = setTimeout(pruneStaleStreams, 500);
 
     return () => clearTimeout(timeoutId);
-  }, [enabled, onValidationComplete]);
+  }, [enabled, onPruneComplete]);
 
   const stopAllStreams = useCallback(async () => {
     await streamService.stopAllStreams();

frontend/src/hooks/useMessageActions.ts

@@ -34,11 +34,17 @@ interface UseMessageActionsParams {
   isStreaming: boolean;
 }
 
+// Detects a leftover empty assistant message (e.g., from a previous failed
+// stream start) so sendMessage can replace it rather than stacking duplicates.
 const isEmptyBotPlaceholder = (msg?: Message) =>
   !!msg?.is_bot &&
   (!msg?.content_render?.events || msg.content_render.events.length === 0) &&
   !msg.content_text;
 
+// Exposes two layers: `sendMessage` opens the SSE stream and injects the
+// assistant placeholder into state; `handleMessageSend` is the form-level
+// wrapper that validates input size, creates the optimistic user message,
+// and rolls it back on failure.
 export function useMessageActions({
   chatId,
   selectedModelId,
@@ -120,6 +126,7 @@ export function useMessageActions({
           model_id: selectedModelId ?? undefined,
         };
 
+        // Replace a trailing empty placeholder if present, otherwise append.
         setMessages((prev) => {
           const lastMessage = prev[prev.length - 1];
           if (isEmptyBotPlaceholder(lastMessage)) {

frontend/src/hooks/useMessageCache.ts

@@ -9,6 +9,11 @@ interface UseMessageCacheParams {
   queryClient: QueryClient;
 }
 
+// Direct query-cache mutators for messages. These write into the react-query
+// infinite-query pages structure (pages[].items[]) so that optimistic UI updates
+// (streaming content, new messages, deletions) are visible without a refetch.
+// Scoped to the current chatId — callers needing cross-chat writes must use
+// queryClient directly with the target chatId.
 export function useMessageCache({ chatId, queryClient }: UseMessageCacheParams) {
   const updateMessageInCache = useCallback(
     (messageId: string, updater: (msg: Message) => Message) => {
@@ -31,6 +36,8 @@ export function useMessageCache({ chatId, queryClient }: UseMessageCacheParams)
     [chatId, queryClient],
   );
 
+  // Uses unshift into page 0 so newest messages match the backend's DESC
+  // ordering. Optionally prepends the paired user message when both arrive together.
   const addMessageToCache = useCallback(
     (message: Message, userMessage?: Message) => {
       if (!chatId) return;

frontend/src/hooks/useMessageInitialization.ts

@@ -18,6 +18,10 @@ interface UseMessageInitializationParams {
   setInitialPrompt: (prompt: string) => void;
 }
 
+// Normalizes fetched messages (attachment file types, default fields) and
+// seeds local state. Also handles the "initial prompt" flow where a new chat
+// is created from a route param or navigation state — injects a synthetic
+// user message so the chat starts without waiting for the first API round-trip.
 export function useMessageInitialization({
   fetchedMessages,
   chatId,
@@ -40,7 +44,7 @@ export function useMessageInitialization({
     // but always allow initialization when switching to a different chat
     if (isStreaming && initializedChatRef.current === chatId) return;
 
-    const formattedMessages = fetchedMessages.map((msg: Message) => {
+    const normalizedMessages = fetchedMessages.map((msg: Message) => {
       const processedAttachments = msg.attachments?.map((attachment) => {
         const fileType = detectFileType(
           attachment.filename || '',
@@ -66,7 +70,9 @@ export function useMessageInitialization({
       };
     });
 
-    const latestKnownSeq = formattedMessages.reduce((maxSeq, message) => {
+    // Persist the highest seq from fetched messages so stream reconnection
+    // (useStreamReconnect) can resume from the correct cursor on page refresh.
+    const latestKnownSeq = normalizedMessages.reduce((maxSeq, message) => {
       const seq = Number(message.last_seq ?? 0);
       return Number.isFinite(seq) && seq > maxSeq ? seq : maxSeq;
     }, 0);
@@ -76,7 +82,7 @@ export function useMessageInitialization({
 
     if (
       initialPromptFromRoute &&
-      formattedMessages.length === 0 &&
+      normalizedMessages.length === 0 &&
       !initialPromptSent &&
       selectedModelId
     ) {
@@ -89,9 +95,9 @@ export function useMessageInitialization({
       );
       setMessages([initialMessage]);
       setInitialPrompt(initialPromptFromRoute);
-    } else if (formattedMessages.length > 0) {
+    } else if (normalizedMessages.length > 0) {
       initializedChatRef.current = chatId;
-      setMessages(formattedMessages);
+      setMessages(normalizedMessages);
     }
   }, [
     fetchedMessages,

frontend/src/hooks/usePermissionRequest.ts

@@ -21,6 +21,10 @@ function isExpiredRequestError(error: unknown): boolean {
   return (error as ApiError)?.status === 404;
 }
 
+// Manages the tool-permission approval flow for a single chat. Reads the
+// pending request from the global permission store, sends approve/reject
+// responses to the backend, and auto-dismisses 404s (expired requests where
+// the backend already timed out or the stream moved on).
 export function usePermissionRequest(chatId: string | undefined): UsePermissionRequestReturn {
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -31,6 +35,8 @@ export function usePermissionRequest(chatId: string | undefined): UsePermissionR
   const pendingRequest = chatId ? (pendingRequests.get(chatId) ?? null) : null;
   const prevRequestIdRef = useRef(pendingRequest?.request_id);
 
+  // Clear stale error when a new permission request arrives, so errors from
+  // a previous request don't bleed into the new approval dialog.
   if (prevRequestIdRef.current !== pendingRequest?.request_id) {
     prevRequestIdRef.current = pendingRequest?.request_id;
     if (error !== null) setError(null);