QUICK_START

Streaming UI Optimization - Quick Start Guide

What Was Implemented

A complete streaming UI optimization system for FastAgentPanel that ensures smooth 30-60fps rendering with per-step updates and no layout thrashing.

Key Components

1. Frame-Aligned Streaming Buffer

File: hooks/useStreamingBuffer.ts

Batches streaming updates and flushes them on animation frames.

const { addUpdate, flush, start, stop, isActive, bufferSize } = useStreamingBuffer(
  (updates) => setMessages(applyUpdates(messages, updates)),
  { maxBufferSize: 50, flushIntervalMs: 33 }
);

start();
addUpdate({ type: 'token', data: 'hello', timestamp: Date.now() });
stop();

2. Smart Auto-Scroll

File: hooks/useSmartAutoScroll.ts

Intelligent auto-scroll that respects user scroll position.

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

useEffect(() => {
  autoScroll(); // Only scrolls if user is near bottom
}, [messages.length, autoScroll]);

3. Memoized Timeline Items

File: StepTimelineItem.tsx

Prevents unnecessary re-renders of timeline steps.

const StepTimelineItem = memo(Component, (prev, next) => {
  return prev.step === next.step && prev.isExpanded === next.isExpanded;
});

4. GPU-Accelerated Animations

File: FastAgentPanel.animations.css

All animations use transform and opacity for GPU acceleration.

.animate-fadeIn {
  animation: fadeInSmooth 0.2s ease-out;
}

.timeline-item {
  transform: translateZ(0); /* Enable GPU acceleration */
  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}

5. Deferred Value Processing

File: FastAgentPanel.UIMessageStream.tsx

Defers heavy message filtering to prevent UI blocking.

const deferredMessages = useDeferredValue(messages);

const filteredMessages = useMemo(() => {
  return deferredMessages.filter(...); // Heavy work deferred
}, [deferredMessages]);

Performance Targets