Archive Story 22 to stories/archive/

.living_spec/stories/archive/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
+- [x] When I scroll up in the chat, auto-scroll is temporarily disabled
+- [x] 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
+- [x] Auto-scroll works normally when I'm already at the bottom
+- [x] The detection works smoothly without flickering
+- [x] 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]);
+```