From 88e2a9c0bc336bee7a90b9fba4b3946882c696dc Mon Sep 17 00:00:00 2001
From: Dave <futurechimp@users.noreply.github.com>
Date: Sat, 27 Dec 2025 17:09:32 +0000
Subject: [PATCH] Add Story 22: Smart auto-scroll that respects user scrolling

---
 .living_spec/stories/22_smart_autoscroll.md | 48 +++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 .living_spec/stories/22_smart_autoscroll.md

diff --git a/.living_spec/stories/22_smart_autoscroll.md b/.living_spec/stories/22_smart_autoscroll.md
new file mode 100644
index 0000000..63e9584
--- /dev/null
+++ b/.living_spec/stories/22_smart_autoscroll.md
@@ -0,0 +1,48 @@
+# 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
+```tsx
+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]);
+```