STREAMING_OPTIMIZATION

Streaming UI Optimization Guide

Overview

This document describes the streaming UI optimization patterns implemented in FastAgentPanel to ensure smooth, animated streaming with per-step updates at 30-60fps without layout thrashing.

Architecture

1. Frame-Aligned Streaming Buffer (useStreamingBuffer)

Purpose: Accumulate streaming updates and flush them on animation frames to prevent excessive re-renders.

How it works:

• Collects tokens, tool steps, and status updates in a ring buffer
• Flushes updates on requestAnimationFrame or at configurable intervals (default: 33ms ≈ 30fps)
• Automatically flushes when buffer exceeds max size (default: 50 updates)
• Prevents UI blocking by batching updates

Usage:

const { addUpdate, flush, start, stop, isActive, bufferSize } = useStreamingBuffer(
  (updates) => {
    // Apply batched updates to state
    setMessages(applyUpdates(messages, updates));
  },
  { maxBufferSize: 50, flushIntervalMs: 33, enableLogging: false }
);

// Start streaming
start();

// Add updates as they arrive
addUpdate({ type: 'token', data: 'hello', timestamp: Date.now() });

// Stop and flush remaining
stop();

2. Smart Auto-Scroll (useSmartAutoScroll)

Purpose: Intelligent auto-scroll that respects user scroll position and prevents scroll fighting.

Features:

• Only auto-scrolls when user is near bottom (configurable threshold, default: 80px)
• Pauses auto-scroll when user scrolls up
• Resumes when user scrolls back to bottom
• Uses scroll anchoring to prevent layout thrash
• Respects prefers-reduced-motion for accessibility

Usage:

const { autoScroll, isNearBottom, scrollToBottom, reset, userHasScrolledUp } = useSmartAutoScroll(
  scrollRef,
  { nearBottomThreshold: 80, enableLogging: false }
);

// Auto-scroll when new messages arrive
useEffect(() => {
  autoScroll();
}, [messages.length, autoScroll]);

// Reset when starting new conversation
useEffect(() => {
  reset();
}, [reset]);