fix: clamp cursor-up to viewport height, preventing terminal scroll-to-top

[MagnetonIO]

Summary

• Clamps all eraseLines() and cursorUp() calls in log-update.ts to stream.rows (viewport height)
• Prevents ANSI cursor-up sequences from moving the cursor above the visible viewport into terminal scrollback
• Falls back to Infinity (no clamping) for non-TTY streams
• Adds 6 new tests verifying viewport clamping in both standard and incremental rendering modes

Root Cause

When Ink re-renders content that exceeds the terminal viewport, eraseLines(previousLineCount) and cursorUp(previousLines.length - 1) emit cursor-up escape sequences (\e[NA) where N can far exceed the viewport height. Terminals follow the cursor above the visible area and snap to the top of scrollback history.

This affects all terminals — iTerm2, VS Code, tmux, Windows Terminal, kitty, GNOME Terminal, and xterm.js embeddings.

The Fix

Two small helpers read stream.rows from TTY streams and clamp line counts:

const getViewportRows = (stream: Writable): number =>
    (stream as NodeJS.WriteStream).rows || Infinity;

const clampToViewport = (lineCount: number, stream: Writable): number =>
    Math.min(lineCount, getViewportRows(stream));

Applied to all 6 eraseLines/cursorUp call sites in both createStandard and createIncremental. The clamp is semantically correct: lines above the viewport have already scrolled into scrollback and cannot be erased or navigated to.

Tests

• All 944 existing tests pass with zero regressions
• 6 new tests verify clamping behavior:
  • Standard/incremental: eraseLines clamped when content exceeds viewport
  • Standard/incremental: cursorUp clamped when content exceeds viewport
  • Standard/incremental: no clamping when content fits within viewport

Downstream Impact

This is the root cause behind a wave of scroll-to-top bugs in tools built on Ink, most notably Claude Code:

• Terminal randomly scrolls to top and auto-scrolls to bottom during output, breaking scrollback navigation anthropics/claude-code#34845 (146+ reactions, 12+ comments)
• [BUG] Forces scroll to top when outputting code (NOT just when scrolling) anthropics/claude-code#33814
• [BUG] Console scrolling top of history when claude add text to the console anthropics/claude-code#826
• Terminal keeps scrolling to top when conversation gets long anthropics/claude-code#36582
• Scrolling during streaming output jumps to top of session anthropics/claude-code#35403
• Terminal keeps scrolling to top of conversation during active session anthropics/claude-code#36816

Also affects Gemini CLI and any Ink-based TUI that renders content taller than the viewport.

🤖 Generated with Claude Code

[MorningLightMountain713]

Send it

[sindresorhus]

I think this is still incomplete.

buildCursorSuffix() still emits an unclamped cursorUp(visibleLineCount - cursorPosition.y). I manually checked the branch with a 5-row fake TTY and 20 lines of output, and both standard and incremental rendering still write \x1b[20A as soon as a cursor position is set. So anything using useCursor can still trigger the same scroll-to-top behavior. The new tests only cover the erase/rewrite paths, so this sneaks through.

Also, CI is failing.

[OutThisLife]

Need this asap

[yasuda0320]

#982 has been merged and changes the same line in buildCursorSuffix(), so this PR will conflict.

The first parameter changed from visibleLineCount to bottomLine — always lines.length - 1, whether or not the output ends with a newline — and the call sites were updated to match.

I'd expect the resolution to be:

const moveUp = Math.min(bottomLine - cursorPosition.y, viewportHeight);