perf(tui): improve scroll performance and pagination in log viewer

Increase buffer multiplier from 1.2x to 3x for smoother backward pagination
Implement scroll lock mechanism during content prepend to prevent flickering
Add preloading when user is 15 lines from top for better user experience

Author: moazbuilds

src/cli/tui/routes/workflow/components/output/output-window.tsx

@@ -70,6 +70,8 @@ export function OutputWindow(props: OutputWindowProps) {
   const themeCtx = useTheme()
   const [scrollRef, setScrollRef] = createSignal<ScrollBoxRenderable | undefined>()
   const [userScrolledAway, setUserScrolledAway] = createSignal(false)
+  // Scroll lock prevents ALL scroll handling during content prepend operations
+  const [scrollLock, setScrollLock] = createSignal(false)
 
   // Reset userScrolledAway when agent changes
   // Use on() to explicitly track only the agent name, not other props
@@ -90,7 +92,17 @@ export function OutputWindow(props: OutputWindowProps) {
       debug('[OutputWindow] Scroll effect running, ref exists: %s', !!ref)
       if (!ref) return
 
+      // PRELOAD_THRESHOLD: Load earlier for smoother experience
+      // When user is 15 lines from top, start loading
+      const PRELOAD_THRESHOLD = 15
+
       const handleScrollChange = () => {
+        // Absolute lock during content prepend operations - prevents ALL interference
+        if (scrollLock()) {
+          debug('[OutputWindow] Scroll event ignored - scroll lock active')
+          return
+        }
+
         const scrollTop = ref.scrollTop
         const scrollHeight = ref.scrollHeight
         const viewportHeight = ref.height
@@ -108,13 +120,40 @@ export function OutputWindow(props: OutputWindowProps) {
           setUserScrolledAway(false)
         }
 
-        // Trigger load when near the top (within 3 lines) - skip if already loading
-        if (scrollTop <= 3 && props.hasMoreAbove && props.onLoadMore && !props.isLoadingEarlier) {
-          debug('[OutputWindow] Loading earlier lines...')
+        // Preload when near the top
+        if (scrollTop <= PRELOAD_THRESHOLD && props.hasMoreAbove && props.onLoadMore && !props.isLoadingEarlier) {
+          debug('[OutputWindow] Preloading earlier lines (scrollTop=%d, threshold=%d)...', scrollTop, PRELOAD_THRESHOLD)
+
+          // 1. Lock and detach listener to prevent any scroll events during operation
+          setScrollLock(true)
+          ref.verticalScrollBar?.off("change", handleScrollChange)
+
+          // 2. Capture current scroll position BEFORE loading
+          const originalScrollTop = scrollTop
+
+          // 3. Load content (this updates state and triggers re-render)
           const linesLoaded = props.onLoadMore()
           debug('[OutputWindow] Lines loaded: %d', linesLoaded)
+
           if (linesLoaded > 0) {
-            ref.scrollTop = linesLoaded  // Maintain view position
+            // 4. SYNCHRONOUS scroll adjustment - no async delay
+            // Set scroll position immediately in the same execution frame
+            // This prevents the flash by adjusting before the next paint
+            const newScrollTop = originalScrollTop + linesLoaded
+            ref.scrollTop = newScrollTop
+            debug('[OutputWindow] Scroll restored (sync): original=%d, added=%d, new=%d',
+              originalScrollTop, linesLoaded, ref.scrollTop)
+
+            // 5. Use setImmediate only for re-attaching listener (after scroll is stable)
+            setImmediate(() => {
+              ref.verticalScrollBar?.on("change", handleScrollChange)
+              setScrollLock(false)
+              debug('[OutputWindow] Scroll lock released, listener re-attached')
+            })
+          } else {
+            // No lines loaded, re-attach and unlock immediately
+            ref.verticalScrollBar?.on("change", handleScrollChange)
+            setScrollLock(false)
           }
         }
       }
@@ -126,7 +165,8 @@ export function OutputWindow(props: OutputWindowProps) {
   )
 
   // Compute whether stickyScroll should be active
-  const shouldStickyScroll = () => !userScrolledAway()
+  // Disable during scroll lock to prevent interference with scroll position restoration
+  const shouldStickyScroll = () => !userScrolledAway() && !scrollLock()
 
   // Notify parent when user scrolls away (to pause trimming in log stream)
   createEffect(

src/cli/tui/routes/workflow/hooks/useLogStream.ts

@@ -209,10 +209,13 @@ function getFileSize(path: string): number {
 
 /**
  * Calculate window size based on visible lines
+ * Uses 3x multiplier to ensure smooth scrolling with large buffer
+ * This means we keep 3x the visible lines in memory, allowing seamless
+ * backward pagination without visible loading
  */
 function calculateWindowSize(visibleLineCount: number): number {
   const visible = visibleLineCount || 30
-  return Math.ceil(visible * 1.2) // 20% buffer
+  return Math.ceil(visible * 3) // 3x buffer for smooth pagination
 }
 
 /**
@@ -380,6 +383,9 @@ export function useLogStream(
    * Load earlier lines when user scrolls to top of windowed view
    * Returns the number of lines loaded (for scroll position adjustment)
    * Includes debouncing (won't load if already loading) and error handling
+   *
+   * Loads 2x the window size to ensure user has plenty of content above
+   * This creates a large buffer that makes pagination invisible to the user
    */
   function loadEarlierLines(): number {
     // Debounce: don't load if already loading
@@ -399,6 +405,7 @@ export function useLogStream(
 
     try {
       const visibleLines = opts.visibleLineCount?.() || 30
+      // Load 1x window size (which is already 3x visible) - balanced for smooth scrolling
       const linesToLoad = calculateWindowSize(visibleLines)
 
       // Read full file and filter