Files

Dave 57826dc5ee Story 22: Implement smart auto-scroll that respects user scrolling

User Story:
As a user, I want to be able to scroll up to review previous messages
while the AI is streaming or adding new content, without being
constantly dragged back to the bottom.

Implementation:
- Replaced position-based threshold detection with user-intent tracking
- Detects when user scrolls UP and disables auto-scroll completely
- Auto-scroll only re-enables when user manually returns to bottom (<5px)
- Uses refs to track scroll position and direction for smooth operation
- Works seamlessly during rapid token streaming and tool execution

Technical Details:
- lastScrollTopRef: Tracks previous scroll position to detect direction
- userScrolledUpRef: Flag set when upward scrolling is detected
- Direct scrollTop manipulation for instant, non-fighting scroll behavior
- Threshold of 5px from absolute bottom to re-enable auto-scroll

Spec Updates:
- Added comprehensive Smart Auto-Scroll section to UI_UX.md
- Documented the problem, solution, requirements, and implementation
- Includes code examples and edge case handling

Acceptance Criteria Met:
✅ Auto-scroll disabled when scrolling up
✅ Auto-scroll resumes when returning to bottom
✅ Works normally when already at bottom
✅ Smooth detection without flickering
✅ Works during streaming and tool execution

Files Changed:
- src/components/Chat.tsx: Implemented user-intent tracking
- .living_spec/specs/functional/UI_UX.md: Added Smart Auto-Scroll spec
- .living_spec/stories/22_smart_autoscroll.md: Marked complete

2025-12-27 19:21:34 +00:00

1.9 KiB

Raw Blame History

Story 22: Smart Auto-Scroll (Respects User Scrolling)

User Story

As a user, I want to be able to scroll up to review previous messages while the AI is streaming or adding new content, without being constantly dragged back to the bottom.

Acceptance Criteria

When I scroll up in the chat, auto-scroll is temporarily disabled
Auto-scroll resumes when I scroll back to (or near) the bottom
There's a visual indicator when auto-scroll is paused (optional)
Clicking a "Jump to Bottom" button (if added) re-enables auto-scroll
Auto-scroll works normally when I'm already at the bottom
The detection works smoothly without flickering
Works during both streaming responses and tool execution

Out of Scope

Manual scroll position restoration after page refresh
Scroll position memory across sessions
Keyboard shortcuts for scrolling
Custom scroll speed or animation settings

Technical Notes

Detect if user is scrolled to bottom: scrollHeight - scrollTop === clientHeight (with small threshold)
Only auto-scroll if user is at/near bottom (e.g., within 100px)
Track scroll position in state or ref
Add scroll event listener to detect when user manually scrolls
Consider debouncing the scroll detection for performance

Design Considerations

Threshold for "near bottom": 100-150px is typical
Optional: Show a "↓ New messages" badge when auto-scroll is paused
Should feel natural and not interfere with reading
Balance between auto-scroll convenience and user control

Implementation Approach

const isScrolledToBottom = () => {
  const element = scrollContainerRef.current;
  if (!element) return true;
  const threshold = 150; // pixels from bottom
  return element.scrollHeight - element.scrollTop - element.clientHeight < threshold;
};

useEffect(() => {
  if (isScrolledToBottom()) {
    scrollToBottom();
  }
}, [messages, streamingContent]);

1.9 KiB Raw Blame History