fix(tui): preserve scrollback on content-driven full redraws

[joemcurry]

Summary

Stops pi-tui from wiping the terminal's scrollback buffer on content-driven full redraws. Previously, fullRender(true) always emitted \x1b[2J\x1b[H\x1b[3J, which clears scrollback as well as the visible screen. Because pi-tui deliberately renders in normal-screen mode (not alt-screen) so that conversation history stays scrollable, that scrollback wipe was actively destructive.

Why

firstChanged < prevViewportTop triggers fullRender(true) whenever any line above the previous viewport changes. During long streaming markdown the renderer re-flows the entire message body on every chunk; once the message has grown past the visible area, even a small reshuffle (paragraph boundary moving, code-fence opening, list re-indent) can put firstChanged above prevViewportTop. Each time that fired, the user lost:

• Any pre-existing shell history that was in the terminal's scrollback before pi-tui started.
• Any TUI lines that had naturally scrolled out during prior renders.

Width changes are different — wrapping changes mean the existing scrollback is visually misaligned at the new width, so clearing it there is defensible. But for content-driven redraws there's no need to throw it away.

Change

Split the clear parameter on the local fullRender helper:

const fullRender = (clear: boolean | "scrollback"): void => {
    if (clear === "scrollback") {
        buffer += "\x1b[2J\x1b[H\x1b[3J"; // clear screen + home + clear scrollback
    } else if (clear === true) {
        buffer += "\x1b[2J\x1b[H";        // clear screen + home, preserve scrollback
    }
    // when not wiping scrollback, write only the bottom `height` lines so we
    // don't push duplicate copies into scrollback that prior renders already
    // pushed there
    const startLine = clear === true ? Math.max(0, newLines.length - height) : 0;
    for (let i = startLine; i < newLines.length; i++) { /* ... */ }
    // ...
};

Call sites:

Trigger	Before	After
widthChanged	fullRender(true)	fullRender("scrollback")
heightChanged (non-Termux)	fullRender(true)	fullRender(true) (preserves scrollback)
clearOnShrink	fullRender(true)	fullRender(true) (preserves scrollback)
targetRow < prevViewportTop	fullRender(true)	fullRender(true) (preserves scrollback)
extraLines > height	fullRender(true)	fullRender(true) (preserves scrollback)
firstChanged < prevViewportTop	fullRender(true)	fullRender(true) (preserves scrollback)

Only widthChanged keeps the scrollback wipe.

Edge case considered

Writing all of newLines after \x1b[2J\x1b[H (without \x1b[3J) would push newLines.length - height lines into scrollback via the natural-scroll path, duplicating content that earlier differential renders already pushed there. The patch addresses this by writing only the bottom height lines on clear === true. The viewport ends up populated with the latest content; scrollback retains whatever the prior renders left there. That history may be slightly stale relative to the current state of an above-viewport line, but it's strictly better than losing it entirely — and the differential renderer already accepts some scrollback drift (it never updates lines that have scrolled out).

Tests

Adds two regression tests in packages/tui/test/tui-render.test.ts:

1. preserves shell scrollback across a content-driven full redraw — pre-populates the virtual terminal's scrollback with shell-style lines, runs the TUI long enough to hit the above-viewport path, and asserts the pre-existing lines are still in getScrollBuffer(). Fails on main (not ok), passes with this patch.
2. clears scrollback on width change (wrapping invalidates prior render) — sanity check that the widthChanged branch still triggers a full redraw.

Existing 554 tests continue to pass (npm test from packages/tui).

Reported downstream

Filed as openclaw/openclaw#78017 — long messages "vanish" in the OpenClaw TUI after streaming. The OpenClaw TUI consumes pi-tui directly, so the fix lands at this layer.

Risk

Low. The fix only changes which escape sequences are emitted on the full-redraw paths and how many lines are written; the line-tracking state (previousLines, previousViewportTop, hardwareCursorRow, cursorRow) is updated identically to before, so subsequent differential renders continue to operate on the same coordinate system.

[github-actions]

This PR was auto-closed. Only contributors approved with lgtm can open PRs. Open an issue first.

Maintainers review auto-closed issues daily. Issues that do not meet the quality bar in CONTRIBUTING.md will not be reopened or receive a reply.

If a maintainer replies lgtmi, your future issues will stay open. If a maintainer replies lgtm, your future issues and PRs will stay open.

See CONTRIBUTING.md.

[Copilot]

Pull request overview

This PR updates the TUI renderer so content-driven full redraws no longer erase terminal scrollback, while keeping scrollback wipes for width changes where reflow invalidates prior output.

Changes:

• Split full redraw behavior into viewport-only clears vs. scrollback-clearing redraws.
• Route width changes through the scrollback-clearing path and preserve scrollback for content/height/shrink-driven full redraws.
• Add regression tests around scrollback preservation and width-change redraw behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
packages/tui/src/tui.ts	Changes full redraw semantics and updates the redraw call sites.
packages/tui/test/tui-render.test.ts	Adds regression coverage for scrollback preservation and width-change redraws.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.