@townco/ui 0.1.72 → 0.1.74

package/dist/gui/components/HookNotification.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { AlertCircle, AlertTriangle, Archive, CheckCircle2, ChevronDown, Loader2, Scissors, } from "lucide-react";
+import React, { useEffect, useState } from "react";
+/**
+ * Get display information for a hook type
+ */
+function getHookDisplayInfo(hookType, _callback, status) {
+    const isTriggered = status === "triggered";
+    if (hookType === "context_size") {
+        return {
+            icon: Archive,
+            title: isTriggered ? "Compacting Context..." : "Context Compacted",
+        };
+    }
+    if (hookType === "tool_response") {
+        return {
+            icon: Scissors,
+            title: isTriggered ? "Compacting Response..." : "Tool Response Compacted",
+        };
+    }
+    // Fallback for unknown hook types
+    return {
+        icon: Archive,
+        title: isTriggered ? "Running Hook..." : "Hook Executed",
+    };
+}
+/**
+ * Format a number with thousand separators
+ */
+function formatNumber(num) {
+    return num.toLocaleString();
+}
+/**
+ * HookNotification component - displays a hook notification inline with messages
+ * Shows triggered (loading), completed, or error states
+ */
+export function HookNotification({ notification }) {
+    const [isExpanded, setIsExpanded] = useState(false);
+    const [elapsedTime, setElapsedTime] = useState(0);
+    const { icon: IconComponent, title } = getHookDisplayInfo(notification.hookType, notification.callback, notification.status);
+    const isTriggered = notification.status === "triggered";
+    const isCompleted = notification.status === "completed";
+    const isError = notification.status === "error";
+    // Update elapsed time while hook is running
+    useEffect(() => {
+        if (!isTriggered || !notification.triggeredAt) {
+            return;
+        }
+        // Calculate initial elapsed time
+        const updateElapsed = () => {
+            const elapsed = (Date.now() - notification.triggeredAt) / 1000;
+            setElapsedTime(elapsed);
+        };
+        // Update immediately
+        updateElapsed();
+        // Update every 100ms for smooth display
+        const interval = setInterval(updateElapsed, 100);
+        return () => clearInterval(interval);
+    }, [isTriggered, notification.triggeredAt]);
+    // Build subtitle showing key info
+    let subtitle = "";
+    if (isTriggered && notification.currentPercentage !== undefined) {
+        subtitle = `Context at ${notification.currentPercentage.toFixed(1)}% (threshold: ${notification.threshold}%)`;
+    }
+    else if (isCompleted && notification.metadata?.tokensSaved !== undefined) {
+        const { tokensSaved, originalTokens } = notification.metadata;
+        // For tool_response hooks - show percentage reduced of the tool response
+        if (originalTokens !== undefined && originalTokens > 0) {
+            const percentageSaved = ((tokensSaved ?? 0) / originalTokens) * 100;
+            subtitle = `${percentageSaved.toFixed(0)}% reduced`;
+        }
+        // For context_size hooks - calculate % of overall context saved
+        // We have currentPercentage (e.g., 81.3%) from triggered notification
+        // tokensSaved / (currentPercentage% of 200k) = % of context saved
+        else if (notification.currentPercentage !== undefined &&
+            notification.currentPercentage > 0) {
+            // currentPercentage is the % of context used before compaction
+            // So the total tokens before = (currentPercentage / 100) * modelContextWindow
+            // We default to 200k if not specified
+            const modelContextWindow = 200000;
+            const totalTokensBefore = (notification.currentPercentage / 100) * modelContextWindow;
+            const percentageOfContextSaved = ((tokensSaved ?? 0) / totalTokensBefore) * 100;
+            subtitle = `${percentageOfContextSaved.toFixed(1)}% context freed`;
+        }
+        // Fallback to absolute tokens
+        else {
+            subtitle = `${formatNumber(tokensSaved)} tokens saved`;
+        }
+    }
+    else if (isError && notification.error) {
+        subtitle = notification.error;
+    }
+    // Check for truncation warning in metadata
+    const truncationWarning = notification.metadata?.truncationWarning;
+    return (_jsxs("div", { className: "flex flex-col my-3", children: [_jsxs("button", { type: "button", className: "flex flex-col items-start gap-0.5 cursor-pointer bg-transparent border-none p-0 text-left group w-fit", onClick: () => setIsExpanded(!isExpanded), "aria-expanded": isExpanded, children: [_jsxs("div", { className: "flex items-center gap-1.5 text-[11px] font-medium text-muted-foreground", children: [_jsx("div", { className: isError ? "text-destructive" : "text-muted-foreground", children: _jsx(IconComponent, { className: "h-3 w-3" }) }), _jsx("span", { className: "text-paragraph-sm text-muted-foreground", children: title }), isTriggered && (_jsxs(_Fragment, { children: [_jsx(Loader2, { className: "h-3 w-3 text-muted-foreground animate-spin" }), _jsxs("span", { className: "text-muted-foreground/70 tabular-nums", children: [elapsedTime.toFixed(1), "s"] })] })), isCompleted && _jsx(CheckCircle2, { className: "h-3 w-3 text-green-500" }), isError && _jsx(AlertCircle, { className: "h-3 w-3 text-destructive" }), !isTriggered && (_jsx(ChevronDown, { className: `h-3 w-3 text-muted-foreground/70 transition-transform duration-200 ${isExpanded ? "rotate-180" : ""}` }))] }), subtitle && (_jsx("span", { className: `text-paragraph-sm pl-4.5 ${isError ? "text-destructive/70" : "text-muted-foreground/70"}`, children: subtitle }))] }), isExpanded && !isTriggered && (_jsxs("div", { className: "mt-2 text-sm border border-border rounded-lg bg-card overflow-hidden w-full", children: [_jsxs("div", { className: "p-3 border-b border-border", children: [_jsx("div", { className: "text-[10px] font-bold text-muted-foreground uppercase tracking-wider mb-1.5 font-sans", children: "Hook Details" }), _jsxs("div", { className: "space-y-1 text-[11px]", children: [_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Type:" }), _jsx("span", { className: "text-foreground font-mono", children: notification.hookType })] }), _jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Callback:" }), _jsx("span", { className: "text-foreground font-mono", children: notification.callback })] }), notification.threshold !== undefined && (_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Threshold:" }), _jsxs("span", { className: "text-foreground", children: [notification.threshold, "%"] })] })), notification.currentPercentage !== undefined && (_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Context Usage:" }), _jsxs("span", { className: "text-foreground", children: [notification.currentPercentage.toFixed(1), "%"] })] }))] })] }), notification.metadata && (_jsxs("div", { className: "p-3 border-b border-border last:border-0", children: [_jsx("div", { className: "text-[10px] font-bold text-muted-foreground uppercase tracking-wider mb-1.5 font-sans", children: "Result" }), _jsxs("div", { className: "space-y-1 text-[11px]", children: [notification.metadata.action && (_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Action:" }), _jsx("span", { className: "text-foreground", children: notification.metadata.action })] })), notification.metadata.messagesRemoved !== undefined && (_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Messages Removed:" }), _jsx("span", { className: "text-foreground", children: formatNumber(notification.metadata.messagesRemoved) })] })), notification.metadata.tokensSaved !== undefined && (_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Tokens Saved:" }), _jsx("span", { className: "text-green-500 font-medium", children: formatNumber(notification.metadata.tokensSaved) })] })), notification.metadata.originalTokens !== undefined && (_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Original Size:" }), _jsxs("span", { className: "text-foreground", children: [formatNumber(notification.metadata.originalTokens), " ", "tokens"] })] })), notification.metadata.finalTokens !== undefined && (_jsxs("div", { className: "flex gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: "Final Size:" }), _jsxs("span", { className: "text-foreground", children: [formatNumber(notification.metadata.finalTokens), " tokens"] })] }))] })] })), truncationWarning && (_jsxs("div", { className: "p-3 border-b border-border last:border-0 bg-yellow-500/5", children: [_jsxs("div", { className: "flex items-center gap-1.5 text-[10px] font-bold text-yellow-600 dark:text-yellow-500 uppercase tracking-wider mb-1.5 font-sans", children: [_jsx(AlertTriangle, { className: "h-3 w-3" }), "Warning"] }), _jsx("div", { className: "text-[11px] text-yellow-700 dark:text-yellow-400", children: truncationWarning })] })), notification.error && (_jsxs("div", { className: "p-3 border-b border-border last:border-0", children: [_jsx("div", { className: "text-[10px] font-bold text-destructive uppercase tracking-wider mb-1.5 font-sans", children: "Error" }), _jsx("div", { className: "text-[11px] text-destructive font-mono", children: notification.error })] })), _jsxs("div", { className: "p-2 bg-muted/50 border-t border-border text-[10px] text-muted-foreground font-sans space-y-0.5", children: [notification.triggeredAt && (_jsxs("div", { children: ["Started:", " ", new Date(notification.triggeredAt).toLocaleTimeString()] })), notification.completedAt && (_jsxs("div", { children: ["Completed:", " ", new Date(notification.completedAt).toLocaleTimeString()] })), notification.triggeredAt && notification.completedAt && (_jsxs("div", { children: ["Duration:", " ", ((notification.completedAt - notification.triggeredAt) /
+                                        1000).toFixed(1), "s"] }))] })] }))] }));
+}

package/dist/gui/components/MessageContent.js

@@ -6,6 +6,7 @@ import { useChatStore } from "../../core/store/chat-store.js";
 import { isPreliminaryToolCall } from "../../core/utils/tool-call-state.js";
 import { getDuration, getTransition, motionEasing, shimmerTransition, } from "../lib/motion.js";
 import { cn } from "../lib/utils.js";
+import { HookNotification } from "./HookNotification.js";
 import { Reasoning } from "./Reasoning.js";
 import { Response } from "./Response.js";
 import { ToolOperation } from "./ToolOperation.js";
@@ -185,11 +186,72 @@ export const MessageContent = React.forwardRef(({ role: roleProp, variant, isStr
                         // Single tool call
                         return (_jsx(ToolOperation, { toolCalls: [item], isGrouped: false }, item.id));
                     };
+                    // Get hook notifications and sort by content position
+                    const hookNotifications = (message.hookNotifications || [])
+                        .slice()
+                        .sort((a, b) => (a.contentPosition ?? Infinity) -
+                        (b.contentPosition ?? Infinity));
                     // If no tool calls or they don't have positions, render simplified way
                     if (sortedToolCalls.length === 0 ||
                         !sortedToolCalls.some((tc) => tc.contentPosition !== undefined)) {
                         const groupedToolCalls = groupToolCalls(sortedToolCalls);
-                        return (_jsxs(_Fragment, { children: [groupedToolCalls.length > 0 && (_jsx(AnimatePresence, { mode: "popLayout", children: _jsx("div", { className: "flex flex-col gap-2 mb-1", children: groupedToolCalls.map((item, index) => renderToolCallOrGroup(item, index)) }) })), _jsx(motion.div, { initial: {
+                        // Check if hook notifications have positions for inline rendering
+                        const hasHookPositions = hookNotifications.some((n) => n.contentPosition !== undefined);
+                        if (!hasHookPositions) {
+                            // No positions - render hooks at top, then tool calls, then content
+                            return (_jsxs(_Fragment, { children: [hookNotifications.length > 0 && (_jsx("div", { className: "flex flex-col gap-2 mb-1", children: hookNotifications.map((notification) => (_jsx(HookNotification, { notification: notification }, notification.id))) })), groupedToolCalls.length > 0 && (_jsx(AnimatePresence, { mode: "popLayout", children: _jsx("div", { className: "flex flex-col gap-2 mb-1", children: groupedToolCalls.map((item, index) => renderToolCallOrGroup(item, index)) }) })), _jsx(motion.div, { initial: {
+                                            filter: "blur(12px)",
+                                            opacity: 0,
+                                            y: 12,
+                                        }, animate: {
+                                            filter: "blur(0px)",
+                                            opacity: 1,
+                                            y: 0,
+                                        }, exit: {
+                                            filter: "blur(12px)",
+                                            opacity: 0,
+                                            y: -12,
+                                        }, transition: getTransition(shouldReduceMotion ?? false, {
+                                            duration: 0.4,
+                                            ease: motionEasing.smooth,
+                                        }), children: _jsx(Response, { content: message.content, isStreaming: message.isStreaming, showEmpty: false }) })] }));
+                        }
+                        // Hooks have positions - render them inline with content
+                        const elements = [];
+                        let currentPosition = 0;
+                        hookNotifications.forEach((notification) => {
+                            const position = notification.contentPosition ?? message.content.length;
+                            // Add text before this hook notification
+                            if (position > currentPosition) {
+                                const textChunk = message.content.slice(currentPosition, position);
+                                if (textChunk) {
+                                    elements.push(_jsx(motion.div, { initial: {
+                                            filter: "blur(12px)",
+                                            opacity: 0,
+                                            y: 12,
+                                        }, animate: {
+                                            filter: "blur(0px)",
+                                            opacity: 1,
+                                            y: 0,
+                                        }, exit: {
+                                            filter: "blur(12px)",
+                                            opacity: 0,
+                                            y: -12,
+                                        }, transition: getTransition(shouldReduceMotion ?? false, {
+                                            duration: 0.4,
+                                            ease: motionEasing.smooth,
+                                        }), children: _jsx(Response, { content: textChunk, isStreaming: false, showEmpty: false }) }, `text-before-hook-${notification.id}`));
+                                }
+                            }
+                            // Add hook notification
+                            elements.push(_jsx(HookNotification, { notification: notification }, notification.id));
+                            currentPosition = position;
+                        });
+                        // Add remaining text
+                        if (currentPosition < message.content.length) {
+                            const remainingText = message.content.slice(currentPosition);
+                            if (remainingText) {
+                                elements.push(_jsx(motion.div, { initial: {
                                         filter: "blur(12px)",
                                         opacity: 0,
                                         y: 12,
@@ -204,11 +266,41 @@ export const MessageContent = React.forwardRef(({ role: roleProp, variant, isStr
                                     }, transition: getTransition(shouldReduceMotion ?? false, {
                                         duration: 0.4,
                                         ease: motionEasing.smooth,
-                                    }), children: _jsx(Response, { content: message.content, isStreaming: message.isStreaming, showEmpty: false }) })] }));
+                                    }), children: _jsx(Response, { content: remainingText, isStreaming: message.isStreaming, showEmpty: false }) }, "text-end-hooks"));
+                            }
+                        }
+                        // Add tool calls at the end
+                        if (groupedToolCalls.length > 0) {
+                            groupedToolCalls.forEach((item, index) => {
+                                elements.push(renderToolCallOrGroup(item, index));
+                            });
+                        }
+                        return (_jsx(AnimatePresence, { mode: "popLayout", children: elements }));
                     }
-                    // Render content interleaved with tool calls
+                    // Render content interleaved with tool calls and hook notifications
                     // Group consecutive tool calls with the same batchId or same title
                     const elements = [];
+                    const positionedItems = [];
+                    // Add non-preliminary tool calls with positions
+                    const preliminaryToolCalls = sortedToolCalls.filter(isPreliminaryToolCall);
+                    const nonPreliminaryToolCalls = sortedToolCalls.filter((tc) => !isPreliminaryToolCall(tc));
+                    nonPreliminaryToolCalls.forEach((tc) => {
+                        positionedItems.push({
+                            type: "toolCall",
+                            item: tc,
+                            position: tc.contentPosition ?? message.content.length,
+                        });
+                    });
+                    // Add hook notifications with positions
+                    hookNotifications.forEach((n) => {
+                        positionedItems.push({
+                            type: "hookNotification",
+                            item: n,
+                            position: n.contentPosition ?? 0, // Default to start if no position
+                        });
+                    });
+                    // Sort by position
+                    positionedItems.sort((a, b) => a.position - b.position);
                     let currentPosition = 0;
                     let currentBatch = [];
                     let currentBatchId;
@@ -225,18 +317,18 @@ export const MessageContent = React.forwardRef(({ role: roleProp, variant, isStr
                         currentBatchId = undefined;
                         currentBatchTitle = undefined;
                     };
-                    // Separate preliminary tool calls - they should render at the end, not break text
-                    const preliminaryToolCalls = sortedToolCalls.filter(isPreliminaryToolCall);
-                    const nonPreliminaryToolCalls = sortedToolCalls.filter((tc) => !isPreliminaryToolCall(tc));
-                    // Process non-preliminary tool calls inline with text
-                    nonPreliminaryToolCalls.forEach((toolCall, index) => {
-                        const position = toolCall.contentPosition ?? message.content.length;
-                        // Add text before this tool call
+                    // Process positioned items (tool calls and hook notifications) inline with text
+                    positionedItems.forEach((positionedItem, index) => {
+                        const position = positionedItem.position;
+                        // Add text before this item
                         if (position > currentPosition) {
                             // Flush any pending batch before adding text
                             flushBatch();
                             const textChunk = message.content.slice(currentPosition, position);
                             if (textChunk) {
+                                const itemId = positionedItem.type === "toolCall"
+                                    ? positionedItem.item.id
+                                    : positionedItem.item.id;
                                 elements.push(_jsx(motion.div, { initial: {
                                         filter: "blur(12px)",
                                         opacity: 0,
@@ -252,37 +344,46 @@ export const MessageContent = React.forwardRef(({ role: roleProp, variant, isStr
                                     }, transition: getTransition(shouldReduceMotion ?? false, {
                                         duration: 0.4,
                                         ease: motionEasing.smooth,
-                                    }), children: _jsx(Response, { content: textChunk, isStreaming: false, showEmpty: false }) }, `text-before-${toolCall.id}`));
+                                    }), children: _jsx(Response, { content: textChunk, isStreaming: false, showEmpty: false }) }, `text-before-${itemId}`));
                             }
                         }
-                        // Check if this tool call should be batched (by batchId or consecutive same title)
-                        if (toolCall.batchId) {
-                            if (currentBatchId === toolCall.batchId) {
-                                // Same batch, add to current batch
+                        if (positionedItem.type === "hookNotification") {
+                            // Flush any pending tool call batch before adding hook
+                            flushBatch();
+                            // Add hook notification
+                            elements.push(_jsx(HookNotification, { notification: positionedItem.item }, positionedItem.item.id));
+                        }
+                        else {
+                            // Tool call - check if it should be batched
+                            const toolCall = positionedItem.item;
+                            if (toolCall.batchId) {
+                                if (currentBatchId === toolCall.batchId) {
+                                    // Same batch, add to current batch
+                                    currentBatch.push(toolCall);
+                                }
+                                else {
+                                    // Different batch, flush previous and start new
+                                    flushBatch();
+                                    currentBatchId = toolCall.batchId;
+                                    currentBatchTitle = toolCall.title;
+                                    currentBatch = [toolCall];
+                                }
+                            }
+                            else if (currentBatchTitle === toolCall.title &&
+                                !currentBatchId) {
+                                // Same title as previous (no batchId), continue grouping
                                 currentBatch.push(toolCall);
                             }
                             else {
-                                // Different batch, flush previous and start new
+                                // Different title or switching from batchId to title grouping
                                 flushBatch();
-                                currentBatchId = toolCall.batchId;
                                 currentBatchTitle = toolCall.title;
                                 currentBatch = [toolCall];
                             }
                         }
-                        else if (currentBatchTitle === toolCall.title &&
-                            !currentBatchId) {
-                            // Same title as previous (no batchId), continue grouping
-                            currentBatch.push(toolCall);
-                        }
-                        else {
-                            // Different title or switching from batchId to title grouping
-                            flushBatch();
-                            currentBatchTitle = toolCall.title;
-                            currentBatch = [toolCall];
-                        }
                         currentPosition = position;
                         // Flush batch at the end
-                        if (index === nonPreliminaryToolCalls.length - 1) {
+                        if (index === positionedItems.length - 1) {
                             flushBatch();
                         }
                     });

package/dist/gui/components/index.d.ts

@@ -22,6 +22,7 @@ export { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMe
 export { FileSystemItem, type FileSystemItemProps, } from "./FileSystemItem.js";
 export { FileSystemView, type FileSystemViewProps, } from "./FileSystemView.js";
 export { HeightTransition } from "./HeightTransition.js";
+export { HookNotification, type HookNotificationProps, } from "./HookNotification.js";
 export { IconButton, type IconButtonProps } from "./IconButton.js";
 export { Input, type InputProps, inputVariants } from "./Input.js";
 export { Label } from "./Label.js";

package/dist/gui/components/index.js

@@ -29,6 +29,7 @@ export { FileSystemItem, } from "./FileSystemItem.js";
 export { FileSystemView, } from "./FileSystemView.js";
 // Utility components
 export { HeightTransition } from "./HeightTransition.js";
+export { HookNotification, } from "./HookNotification.js";
 export { IconButton } from "./IconButton.js";
 export { Input, inputVariants } from "./Input.js";
 export { Label } from "./Label.js";

package/dist/gui/hooks/index.d.ts

@@ -1 +1,2 @@
 export { useIsMobile } from "./use-mobile.js";
+export { useScrollToBottom } from "./use-scroll-to-bottom.js";

package/dist/gui/hooks/index.js

@@ -1 +1,2 @@
 export { useIsMobile } from "./use-mobile.js";
+export { useScrollToBottom } from "./use-scroll-to-bottom.js";

package/dist/gui/hooks/use-scroll-to-bottom.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hook for managing auto-scrolling behavior in a chat container.
+ * Inspired by shadcn.io/ai-chatbot implementation.
+ *
+ * Key features:
+ * - Tracks user scroll position and whether they're actively scrolling
+ * - Auto-scrolls to bottom when content changes (streaming) if user was at bottom
+ * - Respects user scrolling - won't auto-scroll if user is manually scrolling
+ * - Uses MutationObserver for DOM changes and ResizeObserver for size changes
+ */
+export declare function useScrollToBottom(): {
+    containerRef: import("react").RefObject<HTMLDivElement | null>;
+    endRef: import("react").RefObject<HTMLDivElement | null>;
+    isAtBottom: boolean;
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+    onViewportEnter: () => void;
+    onViewportLeave: () => void;
+};

package/dist/gui/hooks/use-scroll-to-bottom.js

@@ -0,0 +1,120 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+/**
+ * Hook for managing auto-scrolling behavior in a chat container.
+ * Inspired by shadcn.io/ai-chatbot implementation.
+ *
+ * Key features:
+ * - Tracks user scroll position and whether they're actively scrolling
+ * - Auto-scrolls to bottom when content changes (streaming) if user was at bottom
+ * - Respects user scrolling - won't auto-scroll if user is manually scrolling
+ * - Uses MutationObserver for DOM changes and ResizeObserver for size changes
+ */
+export function useScrollToBottom() {
+    const containerRef = useRef(null);
+    const endRef = useRef(null);
+    const [isAtBottom, setIsAtBottom] = useState(true);
+    const isAtBottomRef = useRef(true);
+    const isUserScrollingRef = useRef(false);
+    // Keep ref in sync with state
+    useEffect(() => {
+        isAtBottomRef.current = isAtBottom;
+    }, [isAtBottom]);
+    const checkIfAtBottom = useCallback(() => {
+        if (!containerRef.current) {
+            return true;
+        }
+        const { scrollTop, scrollHeight, clientHeight } = containerRef.current;
+        // Consider "at bottom" if within 100px of the bottom
+        return scrollTop + clientHeight >= scrollHeight - 100;
+    }, []);
+    const scrollToBottom = useCallback((behavior = "smooth") => {
+        if (!containerRef.current) {
+            return;
+        }
+        containerRef.current.scrollTo({
+            top: containerRef.current.scrollHeight,
+            behavior,
+        });
+    }, []);
+    // Handle user scroll events
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+        let scrollTimeout;
+        const handleScroll = () => {
+            // Mark as user scrolling
+            isUserScrollingRef.current = true;
+            clearTimeout(scrollTimeout);
+            // Update isAtBottom state
+            const atBottom = checkIfAtBottom();
+            setIsAtBottom(atBottom);
+            isAtBottomRef.current = atBottom;
+            // Reset user scrolling flag after scroll ends (150ms debounce)
+            scrollTimeout = setTimeout(() => {
+                isUserScrollingRef.current = false;
+            }, 150);
+        };
+        container.addEventListener("scroll", handleScroll, { passive: true });
+        return () => {
+            container.removeEventListener("scroll", handleScroll);
+            clearTimeout(scrollTimeout);
+        };
+    }, [checkIfAtBottom]);
+    // Auto-scroll when content changes
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+        const scrollIfNeeded = () => {
+            // Only auto-scroll if user was at bottom and isn't actively scrolling
+            if (isAtBottomRef.current && !isUserScrollingRef.current) {
+                requestAnimationFrame(() => {
+                    container.scrollTo({
+                        top: container.scrollHeight,
+                        behavior: "instant",
+                    });
+                    setIsAtBottom(true);
+                    isAtBottomRef.current = true;
+                });
+            }
+        };
+        // Watch for DOM changes (content streaming)
+        const mutationObserver = new MutationObserver(scrollIfNeeded);
+        mutationObserver.observe(container, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+        });
+        // Watch for size changes
+        const resizeObserver = new ResizeObserver(scrollIfNeeded);
+        resizeObserver.observe(container);
+        // Also observe children for size changes
+        Array.from(container.children).forEach((child) => {
+            resizeObserver.observe(child);
+        });
+        return () => {
+            mutationObserver.disconnect();
+            resizeObserver.disconnect();
+        };
+    }, []);
+    // Callbacks for viewport enter/leave (if using intersection observer externally)
+    function onViewportEnter() {
+        setIsAtBottom(true);
+        isAtBottomRef.current = true;
+    }
+    function onViewportLeave() {
+        setIsAtBottom(false);
+        isAtBottomRef.current = false;
+    }
+    return {
+        containerRef,
+        endRef,
+        isAtBottom,
+        scrollToBottom,
+        onViewportEnter,
+        onViewportLeave,
+    };
+}