Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

Preserve terminal scrollback on TUI redraws (#331)

Seth Karten49c787336125
diff --git a/packages/coding-agent/test/edit-tool-no-full-redraw.test.ts b/packages/coding-agent/test/edit-tool-no-full-redraw.test.ts
index 7bd485d70e..57aa376951 100644
--- a/packages/coding-agent/test/edit-tool-no-full-redraw.test.ts
+++ b/packages/coding-agent/test/edit-tool-no-full-redraw.test.ts
@@ -2,6 +2,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Container, type Terminal, Text, TUI } from "@earendil-works/pi-tui";
+import stripAnsi from "strip-ansi";
import { afterEach, beforeAll, describe, expect, it } from "vitest";
import { createEditToolDefinition } from "../src/core/tools/edit.js";
import { computeEditsDiff, type Edit } from "../src/core/tools/edit-diff.js";
@@ -41,7 +42,7 @@ class FakeTerminal implements Terminal {
}
get fullClearCount(): number {
- return this.writes.filter((write) => write.includes("\x1b[2J\x1b[H\x1b[3J")).length;
+ return this.writes.filter((write) => write.includes("\x1b[2J\x1b[H")).length;
}
}
@@ -61,7 +62,7 @@ async function waitForRenderedText(
onRetry?.();
await waitForRender();
lastRender = getRender();
- if (lastRender.includes(expectedText)) {
+ if (stripAnsi(lastRender).includes(expectedText)) {
return lastRender;
}
}
@@ -135,8 +136,9 @@ describe("edit tool TUI rendering", () => {
"line 50 changed",
() => tui.requestRender(true),
);
- expect(callOnlyRender).toContain("edit");
- expect(callOnlyRender).toContain("line 950 changed");
+ const callOnlyRenderText = stripAnsi(callOnlyRender);
+ expect(callOnlyRenderText).toContain("edit");
+ expect(callOnlyRenderText).toContain("line 950 changed");
const redrawsBeforeResult = tui.fullRedraws;
const clearsBeforeResult = terminal.fullClearCount;
@@ -154,7 +156,7 @@ describe("edit tool TUI rendering", () => {
expect(tui.fullRedraws).toBe(redrawsBeforeResult);
expect(terminal.fullClearCount).toBe(clearsBeforeResult);
- const settledRender = component.render(80).join("\n");
+ const settledRender = stripAnsi(component.render(80).join("\n"));
expect(settledRender).toContain("line 50 changed");
expect(settledRender).toContain("line 950 changed");
expect(settledRender).not.toContain("Successfully replaced");
@@ -204,7 +206,7 @@ describe("edit tool TUI rendering", () => {
await waitForRender();
await waitForRender();
- const rendered = component.render(80).join("\n");
+ const rendered = stripAnsi(component.render(80).join("\n"));
expect(rendered).toContain("line 50 changed");
expect(rendered).toContain("line 150 changed");
});
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 544a667503..a8bdec40d6 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,7 @@
## [Unreleased]
+- Fixed full TUI redraws to preserve terminal scrollback on resize and shrink redraws ([#331](https://github.com/PrimeIntellect-ai/prime-agent/pull/331) by [@sethkarten](https://github.com/sethkarten)).
- Fixed fullscreen overlays that request native mouse behavior suspending mouse tracking while visible.
## [0.2.6] - 2026-07-06
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index e8e7c851c5..89d240fdc7 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -558,13 +558,12 @@ export class TUI extends Container {
requestRender(force = false): void {
if (force) {
this.fullscreen?.viewport.reset();
- this.previousLines = [];
+ // Keep the previous frame metadata so the forced full repaint can
+ // clean up only the visible viewport and avoid touching scrollback.
this.previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
- this.previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
this.cursorRow = 0;
this.hardwareCursorRow = 0;
this.maxLinesRendered = 0;
- this.previousViewportTop = 0;
if (this.renderTimer) {
clearTimeout(this.renderTimer);
this.renderTimer = undefined;
@@ -588,11 +587,11 @@ export class TUI extends Container {
/**
* Request a render that keeps the user anchored at their current scroll
* position. Normally, when content above the visible viewport changes, the
- * renderer falls back to a full redraw that clears scrollback and replays
- * the entire transcript from the top. For deliberate toggles (e.g. expanding
- * all tool output) that is jarring — it scrolls to the top and reprints
- * everything. This instead repaints only the visible viewport in place,
- * leaving scrollback untouched.
+ * renderer may fall back to a full screen redraw that replays the entire
+ * transcript from the top. For deliberate toggles (e.g. expanding all tool
+ * output) that is jarring: it scrolls to the top and reprints everything.
+ * This instead repaints only the visible viewport in place, leaving
+ * scrollback untouched.
*/
requestRenderPreservingViewport(): void {
this.preserveViewportOnNextRender = true;
@@ -1333,7 +1332,8 @@ export class TUI extends Container {
newLines = this.applyLineResets(newLines);
- // Helper to clear scrollback and viewport and render all new lines
+ // Helper to clear the viewport and repaint the current screen. Do not
+ // clear terminal scrollback: users rely on it to read long prior messages.
const fullRender = (clear: boolean, preserveViewport = false): void => {
this.fullRedrawCount += 1;
let buffer = "\x1b[?2026h"; // Begin synchronized output
@@ -1386,9 +1386,9 @@ export class TUI extends Container {
this.cursorRow = Math.max(0, newLines.length - 1);
this.hardwareCursorRow = this.cursorRow;
// Reset (not just grow) the high-water mark to the repainted content,
- // mirroring the scrollback-clearing path. Otherwise a preserving
- // collapse leaves maxLinesRendered inflated, and the next plain render
- // would re-trigger clearOnShrink and do a destructive full redraw.
+ // mirroring the full-redraw path. Otherwise a preserving collapse
+ // leaves maxLinesRendered inflated, and the next plain render would
+ // re-trigger clearOnShrink.
this.maxLinesRendered = newLines.length;
this.previousViewportTop = windowStart;
this.positionHardwareCursor(cursorPos, newLines.length);
@@ -1399,12 +1399,15 @@ export class TUI extends Container {
return;
}
+ const renderStart = clear && this.previousLines.length > 0 ? Math.max(0, newLines.length - height) : 0;
if (clear) {
- buffer += this.deleteKittyImages(this.previousKittyImageIds);
- buffer += "\x1b[2J\x1b[H\x1b[3J"; // Clear screen, home, then clear scrollback
+ const previousVisibleTop = Math.min(prevViewportTop, Math.max(0, this.previousLines.length - height));
+ const previousVisibleBottom = Math.min(this.previousLines.length - 1, previousVisibleTop + height - 1);
+ buffer += this.deleteChangedKittyImages(previousVisibleTop, previousVisibleBottom);
+ buffer += "\x1b[2J\x1b[H"; // Clear screen and home while preserving scrollback
}
- for (let i = 0; i < newLines.length; i++) {
- if (i > 0) buffer += "\r\n";
+ for (let i = renderStart; i < newLines.length; i++) {
+ if (i > renderStart) buffer += "\r\n";
buffer += newLines[i];
}
buffer += "\x1b[?2026l"; // End synchronized output
@@ -1554,8 +1557,8 @@ export class TUI extends Container {
//
// When the transcript is taller than the viewport — e.g. attaching to a
// long or still-streaming session, where off-screen tool results keep
- // resolving — clearing scrollback and replaying the whole transcript on
- // every such change is what makes the screen flicker and scroll from the
+ // resolving — replaying the whole transcript on every such change is what
+ // makes the screen flicker and scroll from the
// top. Repaint only the visible window in place instead, leaving
// scrollback (and the user's history) untouched. Short transcripts that
// fit on screen keep the cheap full redraw.
@@ -1563,8 +1566,8 @@ export class TUI extends Container {
// Only do this while the transcript is growing (the streaming case). A
// shrink — a rebuild or compaction that replaces the transcript with
// fewer lines — leaves the now-removed lines stale in scrollback above the
- // visible window, so it still needs the scrollback-clearing redraw. That
- // is a one-time event, so it costs no recurring flicker.
+ // visible window, so it still needs a full screen redraw. That is a
+ // one-time event, so it costs no recurring flicker.
if (firstChanged < prevViewportTop) {
logRedraw(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
const preserveScrollback = newLines.length > height && newLines.length >= this.previousLines.length;
diff --git a/packages/tui/test/tui-render.test.ts b/packages/tui/test/tui-render.test.ts
index 4caed81dd0..4c2a635d20 100644
--- a/packages/tui/test/tui-render.test.ts
+++ b/packages/tui/test/tui-render.test.ts
@@ -153,6 +153,34 @@ describe("TUI Kitty image cleanup", () => {
tui.stop();
});
+
+ it("deletes bottom visible Kitty images when height shrink clamps the previous viewport", async () => {
+ const terminal = new LoggingVirtualTerminal(40, 10);
+ const tui = new TUI(terminal);
+ const component = new TestComponent();
+ tui.addChild(component);
+
+ component.lines = [
+ "Line 0",
+ "Line 1",
+ encodeKitty("AAAA", { columns: 2, rows: 1, imageId: 303, moveCursor: false }),
+ ];
+ tui.start();
+ await terminal.waitForRender();
+ terminal.clearWrites();
+
+ terminal.resize(40, 2);
+ await terminal.waitForRender();
+
+ const writes = terminal.getWrites();
+ const deleteIndex = writes.indexOf(deleteKittyImage(303));
+ const clearIndex = writes.indexOf("\x1b[2J");
+ assert.ok(deleteIndex >= 0, "Bottom visible image should be deleted during the height-shrink redraw");
+ assert.ok(clearIndex >= 0, "Height shrink should clear the screen");
+ assert.ok(deleteIndex < clearIndex, "Visible image should be deleted before the screen is cleared");
+
+ tui.stop();
+ });
});
describe("TUI resize handling", () => {
@@ -666,7 +694,7 @@ describe("TUI viewport-preserving render", () => {
tui.stop();
});
- it("still clears scrollback when a tall transcript shrinks below the viewport", async () => {
+ it("preserves scrollback when a tall transcript shrinks below the viewport", async () => {
const terminal = new LoggingVirtualTerminal(40, 10);
const tui = new TUI(terminal);
const component = new TestComponent();
@@ -679,15 +707,14 @@ describe("TUI viewport-preserving render", () => {
terminal.clearWrites();
// Collapse to a handful of lines that fit on screen (e.g. a rebuild after
- // compaction). The visible window no longer maps onto the old scrollback,
- // so a destructive redraw that clears scrollback and replays is correct —
- // the in-place repaint is only used while the transcript stays taller than
- // the viewport.
+ // compaction). Redraw the visible screen, but preserve terminal scrollback
+ // so users can still read long prior output.
component.lines = ["Summary A", "Summary B", "Summary C"];
tui.requestRender();
await terminal.waitForRender();
- assert.ok(terminal.getWrites().includes("\x1b[3J"), "Shrinking below the viewport clears scrollback");
+ assert.ok(terminal.getWrites().includes("\x1b[2J"), "Shrinking below the viewport clears the screen");
+ assert.ok(!terminal.getWrites().includes("\x1b[3J"), "Shrinking below the viewport must not clear scrollback");
tui.stop();
});
@@ -722,6 +749,57 @@ describe("TUI viewport-preserving render", () => {
tui.stop();
});
+ it("only deletes visible Kitty images during screen-clearing redraws", async () => {
+ const terminal = new LoggingVirtualTerminal(40, 10);
+ const tui = new TUI(terminal);
+ const component = new TestComponent();
+ tui.addChild(component);
+
+ const aboveImage = encodeKitty("AAAA", { columns: 2, rows: 1, imageId: 101, moveCursor: false });
+ const visibleImage = encodeKitty("BBBB", { columns: 2, rows: 1, imageId: 202, moveCursor: false });
+ const lines = Array.from({ length: 30 }, (_, i) => `Line ${i}`);
+ lines[2] = aboveImage;
+ lines[25] = visibleImage;
+ component.lines = lines;
+ tui.start();
+ await terminal.waitForRender();
+ terminal.clearWrites();
+
+ terminal.resize(60, 10);
+ await terminal.waitForRender();
+
+ const writes = terminal.getWrites();
+ assert.ok(writes.includes("\x1b[2J"), "Width change should clear the screen before repainting");
+ assert.ok(writes.includes(deleteKittyImage(202)), "Visible image is deleted before the screen repaint");
+ assert.ok(!writes.includes(deleteKittyImage(101)), "Image in scrollback above the viewport must not be deleted");
+
+ tui.stop();
+ });
+
+ it("repaints only the visible window during screen-clearing redraws", async () => {
+ const terminal = new LoggingVirtualTerminal(40, 10);
+ const tui = new TUI(terminal);
+ const component = new TestComponent();
+ tui.addChild(component);
+
+ component.lines = Array.from({ length: 30 }, (_, i) => `Line ${i}`);
+ tui.start();
+ await terminal.waitForRender();
+ terminal.clearWrites();
+
+ terminal.resize(60, 10);
+ await terminal.waitForRender();
+
+ const writes = terminal.getWrites();
+ assert.ok(writes.includes("\x1b[2J"), "Width change should clear the screen before repainting");
+ assert.ok(!writes.includes("Line 0"), "Screen-clearing redraw must not replay scrollback lines");
+ assert.ok(!writes.includes("Line 19"), "Screen-clearing redraw must not replay lines above the viewport");
+ assert.ok(writes.includes("Line 20"), "Screen-clearing redraw should repaint the top visible line");
+ assert.ok(writes.includes("Line 29"), "Screen-clearing redraw should repaint the bottom visible line");
+
+ tui.stop();
+ });
+
it("does not leave maxLinesRendered inflated after a preserving collapse", async () => {
const terminal = new LoggingVirtualTerminal(40, 10);
const tui = new TUI(terminal);
@@ -742,7 +820,7 @@ describe("TUI viewport-preserving render", () => {
terminal.clearWrites();
// A subsequent plain render with unchanged content must not re-trigger a
- // clearOnShrink full redraw (which would clear scrollback and replay).
+ // clearOnShrink full redraw.
tui.requestRender();
await terminal.waitForRender();
@@ -758,9 +836,9 @@ describe("TUI above-viewport changes on a tall transcript", () => {
// Reproduces the attach-then-stream flicker: when a transcript is taller
// than the viewport and content above the visible window changes (e.g. an
// off-screen tool result resolving while the model streams), the renderer
- // used to clear scrollback and replay the whole transcript on every change,
- // flickering and scrolling from the top. It should now repaint only the
- // visible window in place, leaving scrollback and history intact.
+ // used to replay the whole transcript on every change, flickering and
+ // scrolling from the top. It should now repaint only the visible window
+ // in place, leaving scrollback and history intact.
const terminal = new LoggingVirtualTerminal(40, 10);
const tui = new TUI(terminal);
const component = new TestComponent();
@@ -794,12 +872,11 @@ describe("TUI above-viewport changes on a tall transcript", () => {
tui.stop();
});
- it("clears scrollback when a still-tall transcript shrinks (rebuild/compaction)", async () => {
+ it("preserves scrollback when a still-tall transcript shrinks (rebuild/compaction)", async () => {
// A rebuild or compaction can replace the transcript with fewer lines that
- // still exceed the viewport. Preserving scrollback there would leave the
- // removed lines stale above the visible window, so the shrink must take the
- // scrollback-clearing redraw even though the result is still taller than
- // the viewport.
+ // still exceed the viewport. It still needs a full screen redraw, but must
+ // not delete terminal scrollback because long prior output should remain
+ // readable.
const terminal = new LoggingVirtualTerminal(40, 10);
const tui = new TUI(terminal);
const component = new TestComponent();
@@ -816,7 +893,8 @@ describe("TUI above-viewport changes on a tall transcript", () => {
tui.requestRender();
await terminal.waitForRender();
- assert.ok(terminal.getWrites().includes("\x1b[3J"), "A still-tall shrink clears stale scrollback");
+ assert.ok(terminal.getWrites().includes("\x1b[2J"), "A still-tall shrink clears the screen");
+ assert.ok(!terminal.getWrites().includes("\x1b[3J"), "A still-tall shrink must not clear scrollback");
tui.stop();
});