scrollback-freeze-optimization

SKILL: Scrollback Freeze Optimization

Domain: terminal-ui Trigger: Apply whenever you render active widgets that can scroll into terminal history and would otherwise force full-screen updates. Source Pattern: Distilled from reviewed terminal rendering, layout, animation, and accessibility implementations.

Core Method

Wrap any timer-driven subtree with a viewport-aware container that caches the last visible React element in a ref. When the viewport reports hidden, always return the cached node instead of the live children; React's diffing sees no change and the terminal renderer skips the expensive full-screen redraw.

Key Rules

• Use viewport visibility for the specific widget you are freezing and keep an explicit reference to the last rendered children.
• Only update the cache while the element is visible; otherwise return the cached subtree so React can reuse the same reference.
• Disable memoization on the freeze wrapper (explicit 'use no memo') so React doesn't bail out before the cached reference is read.
• Keep the cached node simple so it can be safely reused after long pauses and still produce the correct layout.

Example Application

Wrap a spinner in scrollback with the freeze wrapper so once you scroll past it, log-update never touches the spinner subtree even though its timer continues running when visible.

Anti-Patterns (What NOT to do)

• Let the spinner still re-render while offscreen, which triggers repeated full-screen resets.
• Put the cache update inside a memoized component that never reads the cached ref.
• Assume scrollback nodes can simply be hidden with CSS; the terminal renderer still re-renders them.