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.tsindex 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.mdindex 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-06diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.tsindex 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 clearthis.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.tsindex 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();});