@townco/ui 0.1.83 → 0.1.96

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

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { Source } from "../../core/schemas/source.js";
 /**
  * Response component inspired by shadcn.io/ai
  * Streaming-optimized markdown renderer using streamdown for incremental parsing
@@ -12,5 +13,7 @@ export interface ResponseProps extends React.HTMLAttributes<HTMLDivElement> {
     showEmpty?: boolean;
     /** Custom empty state message */
     emptyMessage?: string;
+    /** Citation sources for rendering inline citations */
+    sources?: Source[];
 }
 export declare const Response: React.NamedExoticComponent<ResponseProps & React.RefAttributes<HTMLDivElement>>;

package/dist/gui/components/Response.js

@@ -1,9 +1,35 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
+import remarkGfm from "remark-gfm";
 import { Streamdown } from "streamdown";
+import { remarkCitations } from "../lib/remark-citations.js";
 import { cn } from "../lib/utils.js";
-export const Response = React.memo(React.forwardRef(({ content, isStreaming = false, showEmpty = true, emptyMessage = "", className, ...props }, ref) => {
+import { CitationChip } from "./CitationChip.js";
+export const Response = React.memo(React.forwardRef(({ content, isStreaming = false, showEmpty = true, emptyMessage = "", sources = [], className, ...props }, ref) => {
+    // Memoize the remark plugins array to prevent re-renders
+    // remarkGfm adds support for tables, strikethrough, autolinks, task lists
+    const remarkPlugins = React.useMemo(() => [remarkGfm, remarkCitations], []);
+    // Memoize the custom components to prevent re-renders
+    // We use 'as Record<string, unknown>' because Streamdown's Components type
+    // doesn't include all the props we need
+    const customComponents = React.useMemo(() => ({
+        // Custom span component that intercepts citation markers
+        // The remark-citations plugin creates spans with class "citation-marker"
+        // and data-citation-id attribute
+        // Note: Streamdown may pass 'class' instead of 'className'
+        span: (spanProps) => {
+            const { className, class: classAttr, "data-citation-id": citationId, children, ...restProps } = spanProps;
+            // Check both className and class (Streamdown may use either)
+            const cssClass = className || classAttr;
+            // Check if this span is a citation marker
+            if (cssClass === "citation-marker" && citationId) {
+                return _jsx(CitationChip, { sourceId: citationId, sources: sources });
+            }
+            // Otherwise render as normal span
+            return (_jsx("span", { className: cssClass, ...restProps, children: children }));
+        },
+    }), [sources]);
     // Show empty state during streaming if no content yet
     if (!content && isStreaming && showEmpty) {
         return (_jsx("div", { ref: ref, className: cn("opacity-70 italic text-paragraph-sm", className), ...props, children: emptyMessage }));
@@ -11,6 +37,7 @@ export const Response = React.memo(React.forwardRef(({ content, isStreaming = fa
     if (!content) {
         return null;
     }
-    return (_jsx("div", { ref: ref, ...props, children: _jsx(Streamdown, { className: cn("size-full", "[&>*:first-child]:mt-0 [&>*:last-child]:mb-0", "[&_code]:whitespace-pre-wrap [&_code]:break-words", "[&_pre]:max-w-full [&_pre]:overflow-x-auto", className), children: content }) }));
-}), (prevProps, nextProps) => prevProps.content === nextProps.content);
+    return (_jsx("div", { ref: ref, ...props, children: _jsx(Streamdown, { className: cn("size-full", "[&>*:first-child]:mt-0 [&>*:last-child]:mb-0", "[&_code]:whitespace-pre-wrap [&_code]:break-words", "[&_pre]:max-w-full [&_pre]:overflow-x-auto", className), remarkPlugins: remarkPlugins, components: customComponents, children: content }) }));
+}), (prevProps, nextProps) => prevProps.content === nextProps.content &&
+    prevProps.sources === nextProps.sources);
 Response.displayName = "Response";

package/dist/gui/components/Sidebar.js

@@ -109,7 +109,7 @@ const SidebarInset = React.forwardRef(({ className, children, ...props }, ref) =
     const { isMobile, open } = useSidebar();
     // Desktop: Add padding when sidebar is open
     // Mobile: No changes (overlay handles visibility)
-    return (_jsx("main", { className: cn("relative flex w-full flex-1 flex-col bg-background transition-all duration-500", 
+    return (_jsx("main", { className: cn("relative flex w-full flex-1 flex-col bg-background transition-all duration-250", 
         // Add left padding on desktop when sidebar is open
         !isMobile && open && "md:pl-64", className), ref: ref, ...props, children: children }));
 });

package/dist/gui/components/TodoSubline.js

@@ -22,6 +22,6 @@ export function TodoSubline({ todos, className }) {
     const displayText = displayItem.status === "in_progress"
         ? displayItem.activeForm || displayItem.content
         : displayItem.content;
-    return (_jsxs("span", { className: cn("flex items-center gap-1.5", className), children: [displayItem.status === "completed" ? (_jsx(CircleCheck, { className: "size-3 text-muted-foreground shrink-0" })) : displayItem.status === "in_progress" ? (_jsx("span", { className: "size-2 rounded-full bg-foreground animate-pulse-scale shrink-0" })) : (_jsx(Circle, { className: "size-3 text-foreground shrink-0" })), _jsx("span", { className: "truncate", children: displayText })
+    return (_jsxs("span", { className: cn("flex items-center gap-1.5", className), children: [displayItem.status === "completed" ? (_jsx(CircleCheck, { className: "size-3 text-muted-foreground shrink-0" })) : displayItem.status === "pending" ? (_jsx(Circle, { className: "size-3 text-foreground shrink-0" })) : null, _jsx("span", { className: "truncate", children: displayText })
         ] }));
 }

package/dist/gui/components/WorkProgress.js

@@ -29,6 +29,13 @@ export function WorkProgress({ thinking, isThinkingStreaming = false, toolCalls
             }
         };
         for (const toolCall of toolCalls) {
+            // todo_write should never be grouped with other tool calls
+            const isTodoWrite = toolCall.title === "todo_write";
+            if (isTodoWrite) {
+                flushSelectingGroup();
+                result.push({ type: "single", toolCall });
+                continue;
+            }
             // Handle batch groups (parallel operations)
             if (toolCall.batchId) {
                 flushSelectingGroup();

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

@@ -2,22 +2,26 @@ export { toast } from "sonner";
 export { MockFileSystemProvider, mockFileSystemData, } from "../data/mockFileSystemData.js";
 export { mockSourceData } from "../data/mockSourceData.js";
 export type { FileSystemData, FileSystemItem as FileSystemItemData, FileSystemItemType, FileSystemProvider, } from "../types/filesystem.js";
+export { Action, type ActionProps, Actions, type ActionsProps, } from "./Actions.js";
 export { AppSidebar, type AppSidebarProps, } from "./AppSidebar.js";
 export { Button, type ButtonProps, buttonVariants } from "./Button.js";
 export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, } from "./Card.js";
 export { ChatEmptyState, type ChatEmptyStateProps } from "./ChatEmptyState.js";
 export * as ChatHeader from "./ChatHeader.js";
-export { Actions as ChatInputActions, Attachment as ChatInputAttachment, type ChatInputActionsProps, type ChatInputAttachmentProps, type ChatInputCommandMenuProps, type ChatInputFieldProps, type ChatInputRootProps, type ChatInputSubmitProps, type ChatInputToolbarProps, type ChatInputVoiceInputProps, CommandMenu as ChatInputCommandMenu, type CommandMenuItem, Field as ChatInputField, Root as ChatInputRoot, Submit as ChatInputSubmit, Toolbar as ChatInputToolbar, VoiceInput as ChatInputVoiceInput, } from "./ChatInput.js";
+export { Actions as ChatInputActions, Attachment as ChatInputAttachment, type ChatInputActionsProps, type ChatInputAttachmentProps, type ChatInputCommandMenuProps, type ChatInputFieldProps, type ChatInputRootProps, type ChatInputStopProps, type ChatInputSubmitProps, type ChatInputToolbarProps, type ChatInputVoiceInputProps, CommandMenu as ChatInputCommandMenu, type CommandMenuItem, Field as ChatInputField, Root as ChatInputRoot, Stop as ChatInputStop, Submit as ChatInputSubmit, Toolbar as ChatInputToolbar, VoiceInput as ChatInputVoiceInput, } from "./ChatInput.js";
+export { ChatInputParameters, type ChatInputParametersProps, } from "./ChatInputParameters.js";
 export * as ChatLayout from "./ChatLayout.js";
 export { DatabaseTabContent, type DatabaseTabContentProps, FilesTabContent, type FilesTabContentProps, SettingsTabContent, type SettingsTabContentProps, SourcesTabContent, type SourcesTabContentProps, TodoTabContent, type TodoTabContentProps, } from "./ChatPanelTabContent.js";
 export { ChatSecondaryPanel, type ChatSecondaryPanelProps, } from "./ChatSecondaryPanel.js";
 export * as ChatSidebar from "./ChatSidebar.js";
 export { ChatStatus, type ChatStatusProps } from "./ChatStatus.js";
 export { ChatView, type ChatViewProps } from "./ChatView.js";
+export { CitationChip, type CitationChipProps } from "./CitationChip.js";
 export { ContextUsageButton, type ContextUsageButtonProps, } from "./ContextUsageButton.js";
 export { Conversation, type ConversationProps } from "./Conversation.js";
 export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, } from "./Dialog.js";
 export { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, } from "./DropdownMenu.js";
+export { EditableUserMessage, type EditableUserMessageProps, } from "./EditableUserMessage.js";
 export { FileSystemItem, type FileSystemItemProps, } from "./FileSystemItem.js";
 export { FileSystemView, type FileSystemViewProps, } from "./FileSystemView.js";
 export { HeightTransition } from "./HeightTransition.js";
@@ -27,6 +31,7 @@ export { Input, type InputProps, inputVariants } from "./Input.js";
 export { Label } from "./Label.js";
 export { MarkdownRenderer } from "./MarkdownRenderer.js";
 export { Message, type MessageProps } from "./Message.js";
+export { MessageActions, type MessageActionsProps, } from "./MessageActions.js";
 export { MessageContent, type MessageContentProps } from "./MessageContent.js";
 export type { DisplayMessage } from "./MessageList.js";
 export { PanelTabsHeader, type PanelTabsHeaderProps, } from "./PanelTabsHeader.js";

package/dist/gui/components/index.js

@@ -2,6 +2,7 @@
 export { toast } from "sonner";
 export { MockFileSystemProvider, mockFileSystemData, } from "../data/mockFileSystemData.js";
 export { mockSourceData } from "../data/mockSourceData.js";
+export { Action, Actions, } from "./Actions.js";
 // Sidebar components
 export { AppSidebar, } from "./AppSidebar.js";
 export { Button, buttonVariants } from "./Button.js";
@@ -9,7 +10,8 @@ export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle,
 export { ChatEmptyState } from "./ChatEmptyState.js";
 export * as ChatHeader from "./ChatHeader.js";
 // Chat components - composable primitives
-export { Actions as ChatInputActions, Attachment as ChatInputAttachment, CommandMenu as ChatInputCommandMenu, Field as ChatInputField, Root as ChatInputRoot, Submit as ChatInputSubmit, Toolbar as ChatInputToolbar, VoiceInput as ChatInputVoiceInput, } from "./ChatInput.js";
+export { Actions as ChatInputActions, Attachment as ChatInputAttachment, CommandMenu as ChatInputCommandMenu, Field as ChatInputField, Root as ChatInputRoot, Stop as ChatInputStop, Submit as ChatInputSubmit, Toolbar as ChatInputToolbar, VoiceInput as ChatInputVoiceInput, } from "./ChatInput.js";
+export { ChatInputParameters, } from "./ChatInputParameters.js";
 // Chat layout components
 export * as ChatLayout from "./ChatLayout.js";
 export { DatabaseTabContent, FilesTabContent, SettingsTabContent, SourcesTabContent, TodoTabContent, } from "./ChatPanelTabContent.js";
@@ -17,6 +19,7 @@ export { ChatSecondaryPanel, } from "./ChatSecondaryPanel.js";
 export * as ChatSidebar from "./ChatSidebar.js";
 export { ChatStatus } from "./ChatStatus.js";
 export { ChatView } from "./ChatView.js";
+export { CitationChip } from "./CitationChip.js";
 export { ContextUsageButton, } from "./ContextUsageButton.js";
 // Chat components - shadcn.io/ai inspired primitives
 export { Conversation } from "./Conversation.js";
@@ -24,6 +27,7 @@ export { Conversation } from "./Conversation.js";
 export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, } from "./Dialog.js";
 // DropdownMenu components
 export { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, } from "./DropdownMenu.js";
+export { EditableUserMessage, } from "./EditableUserMessage.js";
 export { FileSystemItem, } from "./FileSystemItem.js";
 // FileSystem components
 export { FileSystemView, } from "./FileSystemView.js";
@@ -35,6 +39,7 @@ export { Input, inputVariants } from "./Input.js";
 export { Label } from "./Label.js";
 export { MarkdownRenderer } from "./MarkdownRenderer.js";
 export { Message } from "./Message.js";
+export { MessageActions, } from "./MessageActions.js";
 export { MessageContent } from "./MessageContent.js";
 export { PanelTabsHeader, } from "./PanelTabsHeader.js";
 export { Reasoning } from "./Reasoning.js";

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

@@ -1,3 +1,4 @@
+export { useDocumentTitle, useFavicon } from "./use-favicon.js";
 export { useLockBodyScroll } from "./use-lock-body-scroll.js";
 export { useIsMobile } from "./use-mobile.js";
 export { useScrollToBottom } from "./use-scroll-to-bottom.js";

package/dist/gui/hooks/index.js

@@ -1,3 +1,4 @@
+export { useDocumentTitle, useFavicon } from "./use-favicon.js";
 export { useLockBodyScroll } from "./use-lock-body-scroll.js";
 export { useIsMobile } from "./use-mobile.js";
 export { useScrollToBottom } from "./use-scroll-to-bottom.js";

package/dist/gui/hooks/use-favicon.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hook that updates the document title to show loading dots when the agent is working
+ * @param agentName - The name of the agent to display in the title
+ */
+export declare function useDocumentTitle(agentName: string | undefined): void;
+export declare const useFavicon: typeof useDocumentTitle;

package/dist/gui/hooks/use-favicon.js

@@ -0,0 +1,47 @@
+import { useEffect, useRef } from "react";
+import { useChatStore } from "../../core/store/chat-store.js";
+// Animation settings
+const DOT_CYCLE_MS = 500; // Time between dot changes (500ms per dot)
+/**
+ * Hook that updates the document title to show loading dots when the agent is working
+ * @param agentName - The name of the agent to display in the title
+ */
+export function useDocumentTitle(agentName) {
+    const isStreaming = useChatStore((state) => state.isStreaming);
+    const intervalRef = useRef(null);
+    const dotCountRef = useRef(0);
+    useEffect(() => {
+        // Set base title when agent name changes
+        if (agentName && !isStreaming) {
+            document.title = agentName;
+        }
+    }, [agentName, isStreaming]);
+    useEffect(() => {
+        if (!agentName)
+            return;
+        const updateTitle = () => {
+            // Cycle through 0, 1, 2, 3 dots
+            const dots = ".".repeat(dotCountRef.current);
+            document.title = `${agentName}${dots}`;
+            dotCountRef.current = (dotCountRef.current + 1) % 4;
+        };
+        if (isStreaming) {
+            // Start dot animation
+            dotCountRef.current = 0;
+            updateTitle(); // Initial update
+            intervalRef.current = setInterval(updateTitle, DOT_CYCLE_MS);
+            return () => {
+                // Stop animation
+                if (intervalRef.current) {
+                    clearInterval(intervalRef.current);
+                    intervalRef.current = null;
+                }
+                // Restore title without dots
+                document.title = agentName;
+            };
+        }
+        return undefined;
+    }, [isStreaming, agentName]);
+}
+// Keep the old export name for backwards compatibility
+export const useFavicon = useDocumentTitle;

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

@@ -7,6 +7,7 @@
  * - 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
+ * - Tracks when the last user message is scrolled above the viewport
  */
 export declare function useScrollToBottom(): {
     containerRef: import("react").RefObject<HTMLDivElement | null>;
@@ -15,4 +16,17 @@ export declare function useScrollToBottom(): {
     scrollToBottom: (behavior?: ScrollBehavior) => void;
     onViewportEnter: () => void;
     onViewportLeave: () => void;
+    isUserMessageAboveFold: boolean;
+    hasMoreUserMessagesBelow: boolean;
+    userMessagesAboveCount: number;
+    userMessagesBelowCount: number;
+    scrollToPreviousUserMessage: (behavior?: ScrollBehavior) => void;
+    scrollToNextUserMessage: (behavior?: ScrollBehavior) => void;
+    scrollToUserMessageByIndex: (index: number, behavior?: ScrollBehavior) => void;
+    getUserMessagePreviews: () => {
+        index: number;
+        preview: string;
+        element: HTMLElement;
+    }[];
+    resetUserMessageCycle: () => void;
 };

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

@@ -8,6 +8,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
  * - 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
+ * - Tracks when the last user message is scrolled above the viewport
  */
 export function useScrollToBottom() {
     const containerRef = useRef(null);
@@ -15,6 +16,19 @@ export function useScrollToBottom() {
     const [isAtBottom, setIsAtBottom] = useState(true);
     const isAtBottomRef = useRef(true);
     const isUserScrollingRef = useRef(false);
+    // Track when any user message is above the fold
+    const [isUserMessageAboveFold, setIsUserMessageAboveFold] = useState(false);
+    // Track whether there are more user messages below the current one
+    const [hasMoreUserMessagesBelow, setHasMoreUserMessagesBelow] = useState(false);
+    // Track counts of messages above and below
+    const [userMessagesAboveCount, setUserMessagesAboveCount] = useState(0);
+    const [userMessagesBelowCount, setUserMessagesBelowCount] = useState(0);
+    // Track the index of the last user message we scrolled to (for cycling through messages)
+    // -1 means we haven't scrolled to any yet, so start from the bottom-most above fold
+    const lastScrolledUserMessageIndexRef = useRef(-1);
+    // Flag to prevent jittery updates during programmatic scroll
+    const isNavigatingRef = useRef(false);
+    const navigationTimeoutRef = useRef(null);
     // Keep ref in sync with state
     useEffect(() => {
         isAtBottomRef.current = isAtBottom;
@@ -27,6 +41,129 @@ export function useScrollToBottom() {
         // Consider "at bottom" if within 100px of the bottom
         return scrollTop + clientHeight >= scrollHeight - 100;
     }, []);
+    // Find all user message elements
+    const findAllUserMessages = useCallback(() => {
+        if (!containerRef.current) {
+            return [];
+        }
+        // User messages have aria-label="user message"
+        const userMessages = containerRef.current.querySelectorAll('[aria-label="user message"]');
+        return Array.from(userMessages);
+    }, []);
+    // Get user message data for messages above the fold (index, preview text, element)
+    const getUserMessagePreviews = useCallback(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return [];
+        }
+        const containerRect = container.getBoundingClientRect();
+        const allUserMessages = findAllUserMessages();
+        // Only include messages that are above the fold
+        return allUserMessages
+            .map((element, index) => {
+            const messageRect = element.getBoundingClientRect();
+            const isAboveFold = messageRect.bottom < containerRect.top + 50;
+            // Get the text content, truncated for preview
+            const textContent = element.textContent || "";
+            const preview = textContent.slice(0, 100) + (textContent.length > 100 ? "..." : "");
+            return { index, preview, element, isAboveFold };
+        })
+            .filter(({ isAboveFold }) => isAboveFold)
+            .map(({ index, preview, element }) => ({ index, preview, element }));
+    }, [findAllUserMessages]);
+    // Scroll to a specific user message by index
+    const scrollToUserMessageByIndex = useCallback((index, behavior = "smooth") => {
+        const allUserMessages = findAllUserMessages();
+        if (index < 0 || index >= allUserMessages.length) {
+            return;
+        }
+        const targetMessage = allUserMessages[index];
+        if (targetMessage) {
+            // Set navigating flag to prevent jittery updates
+            isNavigatingRef.current = true;
+            if (navigationTimeoutRef.current) {
+                clearTimeout(navigationTimeoutRef.current);
+            }
+            targetMessage.scrollIntoView({
+                behavior,
+                block: "start",
+            });
+            lastScrolledUserMessageIndexRef.current = index;
+            // Update all states consistently
+            setUserMessagesAboveCount(index);
+            const belowCount = allUserMessages.length - 1 - index;
+            setUserMessagesBelowCount(belowCount);
+            setHasMoreUserMessagesBelow(belowCount > 0);
+            // Clear navigating flag after scroll animation completes
+            navigationTimeoutRef.current = setTimeout(() => {
+                isNavigatingRef.current = false;
+            }, 500);
+        }
+    }, [findAllUserMessages]);
+    // Find user messages that are above the visible viewport
+    const findUserMessagesAboveFold = useCallback(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return [];
+        }
+        const containerRect = container.getBoundingClientRect();
+        const allUserMessages = findAllUserMessages();
+        // Filter to messages whose bottom edge is above the container's visible area
+        // We add a small threshold (50px) so the button appears before the message fully disappears
+        return allUserMessages.filter((message) => {
+            const messageRect = message.getBoundingClientRect();
+            return messageRect.bottom < containerRect.top + 50;
+        });
+    }, [findAllUserMessages]);
+    // Check if any user message is above the visible viewport
+    const _checkIfUserMessageAboveFold = useCallback(() => {
+        const messagesAbove = findUserMessagesAboveFold();
+        return messagesAbove.length > 0;
+    }, [findUserMessagesAboveFold]);
+    // Find the user message currently visible at the top of the viewport
+    const findCurrentUserMessageIndex = useCallback(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return -1;
+        }
+        const containerRect = container.getBoundingClientRect();
+        const allUserMessages = findAllUserMessages();
+        // Find the user message that's currently at or near the top of the viewport
+        for (let i = 0; i < allUserMessages.length; i++) {
+            const messageRect = allUserMessages[i]?.getBoundingClientRect();
+            if (!messageRect)
+                continue;
+            // Message is "current" if its top is near the top of the container (within 100px)
+            // or if it spans across the top of the viewport
+            if ((messageRect.top >= containerRect.top - 50 &&
+                messageRect.top < containerRect.top + 150) ||
+                (messageRect.top < containerRect.top &&
+                    messageRect.bottom > containerRect.top + 50)) {
+                return i;
+            }
+        }
+        // If no message is at the top, find the last message that's above the fold
+        for (let i = allUserMessages.length - 1; i >= 0; i--) {
+            const messageRect = allUserMessages[i]?.getBoundingClientRect();
+            if (!messageRect)
+                continue;
+            if (messageRect.bottom < containerRect.top + 50) {
+                return i;
+            }
+        }
+        return -1;
+    }, [findAllUserMessages]);
+    // Check if there are more user messages below the current one
+    const _checkHasMoreUserMessagesBelow = useCallback(() => {
+        const allUserMessages = findAllUserMessages();
+        const currentIndex = lastScrolledUserMessageIndexRef.current !== -1
+            ? lastScrolledUserMessageIndexRef.current
+            : findCurrentUserMessageIndex();
+        if (currentIndex === -1) {
+            return false;
+        }
+        return currentIndex < allUserMessages.length - 1;
+    }, [findAllUserMessages, findCurrentUserMessageIndex]);
     const scrollToBottom = useCallback((behavior = "smooth") => {
         if (!containerRef.current) {
             return;
@@ -35,6 +172,142 @@ export function useScrollToBottom() {
             top: containerRef.current.scrollHeight,
             behavior,
         });
+        // Reset user message cycle when scrolling to bottom
+        lastScrolledUserMessageIndexRef.current = -1;
+    }, []);
+    // Scroll to the previous user message (up - older messages)
+    const scrollToPreviousUserMessage = useCallback((behavior = "smooth") => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+        const allUserMessages = findAllUserMessages();
+        if (allUserMessages.length === 0) {
+            return;
+        }
+        const containerRect = container.getBoundingClientRect();
+        // Find user messages that are above the fold (not visible)
+        const messagesAboveFold = [];
+        for (let i = 0; i < allUserMessages.length; i++) {
+            const messageRect = allUserMessages[i]?.getBoundingClientRect();
+            if (!messageRect)
+                continue;
+            if (messageRect.bottom < containerRect.top + 50) {
+                messagesAboveFold.push(i);
+            }
+        }
+        if (messagesAboveFold.length === 0) {
+            return; // No messages above to scroll to
+        }
+        let targetIndex;
+        if (lastScrolledUserMessageIndexRef.current === -1) {
+            // First click: go to the most recent message above the fold (closest to viewport)
+            const lastAbove = messagesAboveFold[messagesAboveFold.length - 1];
+            if (lastAbove === undefined)
+                return;
+            targetIndex = lastAbove;
+        }
+        else {
+            // Find messages above the fold that are also above our current position
+            const messagesAboveCurrentPosition = messagesAboveFold.filter((i) => i < lastScrolledUserMessageIndexRef.current);
+            if (messagesAboveCurrentPosition.length > 0) {
+                // Go to the closest one above current position
+                const lastAbovePosition = messagesAboveCurrentPosition[messagesAboveCurrentPosition.length - 1];
+                if (lastAbovePosition === undefined)
+                    return;
+                targetIndex = lastAbovePosition;
+            }
+            else {
+                // Already at the top, stay at the first message above fold
+                const firstAbove = messagesAboveFold[0];
+                if (firstAbove === undefined)
+                    return;
+                targetIndex = firstAbove;
+            }
+        }
+        if (targetIndex >= 0 && targetIndex < allUserMessages.length) {
+            const targetMessage = allUserMessages[targetIndex];
+            if (targetMessage) {
+                // Set navigating flag to prevent jittery updates
+                isNavigatingRef.current = true;
+                if (navigationTimeoutRef.current) {
+                    clearTimeout(navigationTimeoutRef.current);
+                }
+                targetMessage.scrollIntoView({
+                    behavior,
+                    block: "start",
+                });
+                lastScrolledUserMessageIndexRef.current = targetIndex;
+                // Update all states consistently
+                setUserMessagesAboveCount(targetIndex);
+                const belowCount = allUserMessages.length - 1 - targetIndex;
+                setUserMessagesBelowCount(belowCount);
+                setHasMoreUserMessagesBelow(belowCount > 0);
+                // Clear navigating flag after scroll animation completes
+                navigationTimeoutRef.current = setTimeout(() => {
+                    isNavigatingRef.current = false;
+                }, 500);
+            }
+        }
+    }, [findAllUserMessages]);
+    // Scroll to the next user message (down - newer messages)
+    const scrollToNextUserMessage = useCallback((behavior = "smooth") => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+        const allUserMessages = findAllUserMessages();
+        if (allUserMessages.length === 0) {
+            return;
+        }
+        // If we have a tracked index, go to the next one
+        if (lastScrolledUserMessageIndexRef.current !== -1) {
+            const nextIndex = lastScrolledUserMessageIndexRef.current + 1;
+            if (nextIndex < allUserMessages.length) {
+                const targetMessage = allUserMessages[nextIndex];
+                if (targetMessage) {
+                    // Set navigating flag to prevent jittery updates
+                    isNavigatingRef.current = true;
+                    if (navigationTimeoutRef.current) {
+                        clearTimeout(navigationTimeoutRef.current);
+                    }
+                    targetMessage.scrollIntoView({
+                        behavior,
+                        block: "start",
+                    });
+                    lastScrolledUserMessageIndexRef.current = nextIndex;
+                    // Update all states consistently
+                    setUserMessagesAboveCount(nextIndex);
+                    const belowCount = allUserMessages.length - 1 - nextIndex;
+                    setUserMessagesBelowCount(belowCount);
+                    setHasMoreUserMessagesBelow(belowCount > 0);
+                    // Clear navigating flag after scroll animation completes
+                    navigationTimeoutRef.current = setTimeout(() => {
+                        isNavigatingRef.current = false;
+                    }, 500);
+                }
+            }
+        }
+    }, [findAllUserMessages]);
+    // Check if we can navigate to previous (older) user message
+    const _canScrollToPreviousUserMessage = useCallback(() => {
+        if (lastScrolledUserMessageIndexRef.current > 0) {
+            return true;
+        }
+        // Also check if there are messages above the fold
+        return findUserMessagesAboveFold().length > 0;
+    }, [findUserMessagesAboveFold]);
+    // Check if we can navigate to next (newer) user message
+    const _canScrollToNextUserMessage = useCallback(() => {
+        const allUserMessages = findAllUserMessages();
+        if (lastScrolledUserMessageIndexRef.current === -1) {
+            return false;
+        }
+        return lastScrolledUserMessageIndexRef.current < allUserMessages.length - 1;
+    }, [findAllUserMessages]);
+    // Reset the cycle when user scrolls to bottom or scrolls down significantly
+    const resetUserMessageCycle = useCallback(() => {
+        lastScrolledUserMessageIndexRef.current = -1;
     }, []);
     // Handle user scroll events
     useEffect(() => {
@@ -51,6 +324,34 @@ export function useScrollToBottom() {
             const atBottom = checkIfAtBottom();
             setIsAtBottom(atBottom);
             isAtBottomRef.current = atBottom;
+            // Check if there are any messages above the fold (component visibility)
+            const messagesAboveFold = findUserMessagesAboveFold();
+            const userMessageAbove = messagesAboveFold.length > 0;
+            setIsUserMessageAboveFold(userMessageAbove);
+            // Skip count updates if we're in the middle of a programmatic scroll
+            // This prevents jittery number changes during animation
+            if (!isNavigatingRef.current) {
+                // Update the current user message index based on scroll position
+                const currentIndex = findCurrentUserMessageIndex();
+                if (currentIndex !== -1) {
+                    lastScrolledUserMessageIndexRef.current = currentIndex;
+                }
+                // All counts and states
+                const allMessages = findAllUserMessages();
+                // Above count: number of messages above the fold (what you can scroll up to)
+                setUserMessagesAboveCount(messagesAboveFold.length);
+                // Get the effective current index for below count
+                const effectiveIndex = lastScrolledUserMessageIndexRef.current !== -1
+                    ? lastScrolledUserMessageIndexRef.current
+                    : currentIndex;
+                // Below count: how many messages are after current position (can navigate down to)
+                const belowCount = effectiveIndex !== -1 && effectiveIndex < allMessages.length - 1
+                    ? allMessages.length - 1 - effectiveIndex
+                    : 0;
+                setUserMessagesBelowCount(belowCount);
+                // Has more below: consistent with below count
+                setHasMoreUserMessagesBelow(belowCount > 0);
+            }
             // Reset user scrolling flag after scroll ends (150ms debounce)
             scrollTimeout = setTimeout(() => {
                 isUserScrollingRef.current = false;
@@ -61,7 +362,12 @@ export function useScrollToBottom() {
             container.removeEventListener("scroll", handleScroll);
             clearTimeout(scrollTimeout);
         };
-    }, [checkIfAtBottom]);
+    }, [
+        checkIfAtBottom,
+        findCurrentUserMessageIndex,
+        findAllUserMessages,
+        findUserMessagesAboveFold,
+    ]);
     // Auto-scroll when content changes
     useEffect(() => {
         const container = containerRef.current;
@@ -116,5 +422,15 @@ export function useScrollToBottom() {
         scrollToBottom,
         onViewportEnter,
         onViewportLeave,
+        // User message navigation
+        isUserMessageAboveFold,
+        hasMoreUserMessagesBelow,
+        userMessagesAboveCount,
+        userMessagesBelowCount,
+        scrollToPreviousUserMessage,
+        scrollToNextUserMessage,
+        scrollToUserMessageByIndex,
+        getUserMessagePreviews,
+        resetUserMessageCycle,
     };
 }

package/dist/gui/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./components/index.js";
-export { useIsMobile } from "./hooks/index.js";
+export { useDocumentTitle, useFavicon, useIsMobile } from "./hooks/index.js";
 export { cn } from "./lib/utils.js";

package/dist/gui/index.js

@@ -1,6 +1,6 @@
 // Re-export all components
 export * from "./components/index.js";
 // Re-export hooks
-export { useIsMobile } from "./hooks/index.js";
+export { useDocumentTitle, useFavicon, useIsMobile } from "./hooks/index.js";
 // Re-export utilities
 export { cn } from "./lib/utils.js";