The-Agency/SCROLLING_FIX_SUMMARY.md

Chat View Scrolling Fix Summary

Problem Analysis

The chat view had inconsistent scroll thumb behavior where it would "jump around" during use. This was caused by:

1. Aggressive auto-scrolling: The _scrollToBottom() function was called on every build when messages were present
2. Interference with user scrolling: During message streaming, the chat provider calls notifyListeners() frequently (on each text delta), triggering rebuilds and auto-scrolling
3. No user scroll detection: The system couldn't distinguish between user-initiated scrolling and auto-scrolling

Solution Implemented

1. Smart Auto-Scrolling Logic

• Only auto-scrolls when new messages arrive AND user is near the bottom (within 150px)
• Uses _isNearBottom() to check scroll position
• Tracks actual message content changes, not just rebuilds

2. User Scroll Detection

• Uses ScrollController listener to detect when user is scrolling
• Implements 150ms debouncing to detect when scrolling stops
• Sets _isUserScrolling flag to prevent auto-scrolling while user is interacting

3. Jump-to-Bottom Button

• When user scrolls away from bottom (>200px) and new messages arrive, shows a "New messages" button
• Button appears in bottom-right corner with subtle animation
• Clicking it smoothly scrolls to bottom and hides the button
• Button only shows when there are actually new messages while user is scrolled away

4. Message Change Tracking

• Tracks previous message contents to detect actual changes (not just re-renders)
• Prevents unnecessary auto-scrolling on provider updates that don't change message content

Technical Details

Key Variables

• _isUserScrolling: Tracks if user is actively scrolling
• _showJumpToBottom: Whether to show the jump-to-bottom button
• _hasNewMessagesWhileScrolledAway: Whether new messages arrived while user was scrolled away
• _previousMessageContents: List of previous message contents for change detection

Scroll Thresholds

• Near bottom: Within 150px of bottom (triggers auto-scroll)
• Far from bottom: More than 200px from bottom (shows jump button)
• Debounce timeout: 150ms (detects scroll stop)

Benefits

1. Smooth scrolling: No more jumpy scroll thumb during streaming
2. User control: Users can scroll up to read previous messages without being forced back to bottom
3. Clear UX: Jump-to-bottom button provides clear indication of new messages
4. Performance: Reduces unnecessary scroll animations

Testing

To test the fix:

1. Send multiple messages to create a scrollable chat
2. Scroll up to read previous messages during streaming
3. Observe that auto-scroll doesn't interfere
4. See the jump-to-bottom button appear when new messages arrive
5. Click the button to smoothly return to bottom

The fix maintains the original behavior for users who are at/near the bottom while preventing the disruptive scrolling behavior for users actively reading previous messages.