gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.04f5ccf82

package/packages/pi-tui/src/__tests__/terminal.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { describe, it, type TestContext } from "node:test";
+
+import { ProcessTerminal } from "../terminal.js";
+
+function replaceProcessProperty(
+	t: TestContext,
+	target: object,
+	key: string,
+	value: unknown
+): void {
+	const descriptor = Object.getOwnPropertyDescriptor(target, key);
+	Object.defineProperty(target, key, {
+		configurable: true,
+		writable: true,
+		value,
+	});
+	t.after(() => {
+		if (descriptor) {
+			Object.defineProperty(target, key, descriptor);
+			return;
+		}
+		delete (target as Record<string, unknown>)[key];
+	});
+}
+
+describe("ProcessTerminal", () => {
+	it("restores terminal state when the process exits without an explicit stop", (t) => {
+		t.mock.timers.enable({ apis: ["setTimeout"] });
+
+		const writes: string[] = [];
+		const rawModes: boolean[] = [];
+		const resizeHandlers = new Set<(...args: unknown[]) => void>();
+		const stdinHandlers = new Set<(data: string) => void>();
+		let resumed = false;
+		let paused = false;
+		let encoding = "";
+		let sigwinchSent = false;
+
+		replaceProcessProperty(t, process.stdout, "isTTY", true);
+		replaceProcessProperty(t, process.stdout, "write", (data: string) => {
+			writes.push(data);
+			return true;
+		});
+		replaceProcessProperty(t, process.stdout, "on", (event: string, handler: (...args: unknown[]) => void) => {
+			if (event === "resize") resizeHandlers.add(handler);
+			return process.stdout;
+		});
+		replaceProcessProperty(
+			t,
+			process.stdout,
+			"removeListener",
+			(event: string, handler: (...args: unknown[]) => void) => {
+				if (event === "resize") resizeHandlers.delete(handler);
+				return process.stdout;
+			}
+		);
+
+		replaceProcessProperty(t, process.stdin, "isRaw", false);
+		replaceProcessProperty(t, process.stdin, "setRawMode", (enabled: boolean) => {
+			rawModes.push(enabled);
+			return process.stdin;
+		});
+		replaceProcessProperty(t, process.stdin, "setEncoding", (nextEncoding: BufferEncoding) => {
+			encoding = nextEncoding;
+			return process.stdin;
+		});
+		replaceProcessProperty(t, process.stdin, "resume", () => {
+			resumed = true;
+			return process.stdin;
+		});
+		replaceProcessProperty(t, process.stdin, "pause", () => {
+			paused = true;
+			return process.stdin;
+		});
+		replaceProcessProperty(t, process.stdin, "on", (event: string, handler: (data: string) => void) => {
+			if (event === "data") stdinHandlers.add(handler);
+			return process.stdin;
+		});
+		replaceProcessProperty(t, process.stdin, "removeListener", (event: string, handler: (data: string) => void) => {
+			if (event === "data") stdinHandlers.delete(handler);
+			return process.stdin;
+		});
+		replaceProcessProperty(t, process, "kill", (pid: number, signal?: NodeJS.Signals | number) => {
+			assert.equal(pid, process.pid);
+			assert.equal(signal, "SIGWINCH");
+			sigwinchSent = true;
+			return true;
+		});
+
+		const terminal = new ProcessTerminal();
+		const exitListenersBeforeStart = process.listeners("exit");
+
+		terminal.start(() => {}, () => {});
+
+		const processExitHandler = process
+			.listeners("exit")
+			.find((listener) => !exitListenersBeforeStart.includes(listener));
+		assert.ok(processExitHandler);
+		assert.deepEqual(rawModes, [true]);
+		assert.equal(encoding, "utf8");
+		assert.equal(resumed, true);
+		assert.equal(sigwinchSent, process.platform !== "win32");
+		assert.equal(resizeHandlers.size, 1);
+		assert.equal(stdinHandlers.size, 1);
+		assert.deepEqual(writes, ["\x1b[?2004h", "\x1b[?u"]);
+
+		processExitHandler(0);
+
+		assert.deepEqual(rawModes, [true, false]);
+		assert.equal(paused, true);
+		assert.equal(resizeHandlers.size, 0);
+		assert.equal(stdinHandlers.size, 0);
+		assert.equal(process.listeners("exit").includes(processExitHandler), false);
+		assert.deepEqual(writes, ["\x1b[?2004h", "\x1b[?u", "\x1b[?2004l"]);
+
+		terminal.stop();
+
+		assert.deepEqual(writes, ["\x1b[?2004h", "\x1b[?u", "\x1b[?2004l"]);
+	});
+});

package/packages/pi-tui/src/__tests__/tui.test.ts

@@ -7,11 +7,11 @@ import { Container, CURSOR_MARKER, TUI } from "../tui.js";
 import type { Component } from "../tui.js";
 import type { Terminal } from "../terminal.js";
 
-function makeTerminal(writes?: string[]): Terminal {
+function makeTerminal(writes?: string[], rows = 24): Terminal {
 	return {
 		isTTY: true,
 		columns: 80,
-		rows: 24,
+		rows,
 		kittyProtocolActive: false,
 		start() {},
 		stop() {},
@@ -67,8 +67,94 @@ describe("TUI", () => {
 		anyTui.doRender();
 
 		const renderWrite = writes[writeCountAfterFirstRender];
-		assert.ok(renderWrite.startsWith("\x1b[?2026h\r"), "editor diff should start at the current cursor row");
-		assert.ok(!renderWrite.startsWith("\x1b[?2026h\x1b[1A\r"), "editor diff must not move above the cursor row");
+		const withoutSyncWrapper = renderWrite.replace(/^\x1b\[\?2026h/, "");
+		assert.ok(withoutSyncWrapper.startsWith("\r"), "editor diff should start at the current cursor row");
+		assert.ok(!withoutSyncWrapper.startsWith("\x1b[1A\r"), "editor diff must not move above the cursor row");
+	});
+
+	it("omits synchronized-output wrappers when PI_DISABLE_SYNC_OUTPUT is enabled", () => {
+		const previous = process.env.PI_DISABLE_SYNC_OUTPUT;
+		process.env.PI_DISABLE_SYNC_OUTPUT = "1";
+		try {
+			const writes: string[] = [];
+			const tui = new TUI(makeTerminal(writes));
+			tui.addChild({
+				render: () => ["content"],
+				invalidate() {},
+			});
+
+			(tui as any).doRender();
+
+			const rendered = writes.join("");
+			assert.ok(rendered.includes("content"), "render should still write component output");
+			assert.ok(
+				!rendered.includes("\x1b[?2026h") && !rendered.includes("\x1b[?2026l"),
+				"PI_DISABLE_SYNC_OUTPUT=1 must suppress synchronized-output escape sequences",
+			);
+		} finally {
+			if (previous === undefined) {
+				delete process.env.PI_DISABLE_SYNC_OUTPUT;
+			} else {
+				process.env.PI_DISABLE_SYNC_OUTPUT = previous;
+			}
+		}
+	});
+
+	it("does not full-clear when a tall buffer shrinks (flicker regression #6130)", () => {
+		// Tall-buffer-shrink path: both prev and new exceed viewport height. The fix
+		// falls through to differential render instead of emitting \x1b[2J, which used
+		// to cause the bottom panel to flash on every shrink.
+		const writes: string[] = [];
+		const terminal = makeTerminal(writes, 10);
+		const tui = new TUI(terminal);
+		let lines = Array.from({ length: 20 }, (_, i) => `line-${i}`);
+		tui.addChild({
+			render: () => lines,
+			invalidate() {},
+		});
+		const anyTui = tui as any;
+
+		anyTui.doRender();
+		const writeCountAfterFirstRender = writes.length;
+
+		// Shrink: still taller than viewport, but smaller than before.
+		lines = Array.from({ length: 15 }, (_, i) => `line-${i}`);
+		anyTui.doRender();
+
+		const shrinkWrites = writes.slice(writeCountAfterFirstRender).join("");
+		assert.ok(
+			!shrinkWrites.includes("\x1b[2J"),
+			"tall buffer shrink must not emit \\x1b[2J — that causes the bottom panel to flash",
+		);
+	});
+
+	it("does not full-clear when firstChanged is above the viewport (flicker regression #6130)", () => {
+		// firstChanged-above-viewport path: a line above the current viewport changes.
+		// The fix clamps firstChanged to the viewport top and repaints in place instead
+		// of emitting \x1b[2J + full repaint, which used to cause a bottom-panel flash.
+		const writes: string[] = [];
+		const terminal = makeTerminal(writes, 10);
+		const tui = new TUI(terminal);
+		let lines = Array.from({ length: 20 }, (_, i) => `line-${i}`);
+		tui.addChild({
+			render: () => lines,
+			invalidate() {},
+		});
+		const anyTui = tui as any;
+
+		anyTui.doRender();
+		const writeCountAfterFirstRender = writes.length;
+
+		// Change a line above the viewport (viewportTop = 20 - 10 = 10, so line 0 is above).
+		lines = lines.slice();
+		lines[0] = "changed-above-viewport";
+		anyTui.doRender();
+
+		const clampWrites = writes.slice(writeCountAfterFirstRender).join("");
+		assert.ok(
+			!clampWrites.includes("\x1b[2J"),
+			"firstChanged-above-viewport must not emit \\x1b[2J — that causes the bottom panel to flash",
+		);
 	});
 
 	it("does not swallow a bare Escape keypress while waiting for the cell-size response", () => {

package/packages/pi-tui/src/components/loader.ts

@@ -53,6 +53,9 @@ export class Loader extends Text {
 				this.ui.requestRender();
 			}
 		}, 80);
+		// The loader animation is purely cosmetic — it must never keep the Node
+		// event loop alive on its own (otherwise a process can hang on exit).
+		this.intervalId.unref?.();
 		// Trigger initial render
 		if (this.ui) {
 			this.ui.requestRender();

package/packages/pi-tui/src/terminal.ts

@@ -58,6 +58,10 @@ export interface Terminal {
 export class ProcessTerminal implements Terminal {
 	private static _vtHandles: { GetConsoleMode: any; SetConsoleMode: any; handle: any } | null = null;
 	private wasRaw = false;
+	private started = false;
+	private readonly processExitHandler = () => {
+		this.stop();
+	};
 	private inputHandler?: (data: string) => void;
 	private resizeHandler?: () => void;
 	private _kittyProtocolActive = false;
@@ -81,6 +85,8 @@ export class ProcessTerminal implements Terminal {
 		if (!this.isTTY) {
 			return;
 		}
+		if (this.started) return;
+		this.started = true;
 
 		this.inputHandler = onInput;
 		this.resizeHandler = onResize;
@@ -115,6 +121,7 @@ export class ProcessTerminal implements Terminal {
 		// The query handler intercepts input temporarily, then installs the user's handler
 		// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
 		this.queryAndEnableKittyProtocol();
+		process.once("exit", this.processExitHandler);
 	}
 
 	/**
@@ -267,6 +274,10 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	stop(): void {
+		if (!this.started) return;
+		this.started = false;
+		process.removeListener("exit", this.processExitHandler);
+
 		// Disable bracketed paste mode
 		process.stdout.write("\x1b[?2004l");
 

package/packages/pi-tui/src/tui.ts

@@ -261,6 +261,8 @@ export class TUI extends Container {
 	private previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
 	private fullRedrawCount = 0;
 	private stopped = false;
+	private readonly useSynchronizedOutput =
+		process.platform !== "win32" && process.env.PI_DISABLE_SYNC_OUTPUT !== "1";
 	private _lastRenderedComponents: string[] | null = null;
 
 	// Overlay stack for modal components rendered on top of base content
@@ -673,7 +675,7 @@ export class TUI extends Container {
 		// Helper to clear scrollback and viewport and render all new lines
 		const fullRender = (clear: boolean): void => {
 			this.fullRedrawCount += 1;
-			let buffer = "\x1b[?2026h"; // Begin synchronized output
+			let buffer = this.useSynchronizedOutput ? "\x1b[?2026h" : ""; // Begin synchronized output
 			const startRow = Math.max(1, height - Math.max(1, newLines.length) + 1);
 			if (clear) {
 				// Clear viewport (scrollback preserved) and anchor the rendered
@@ -693,7 +695,7 @@ export class TUI extends Container {
 				}
 				buffer += line;
 			}
-			buffer += "\x1b[?2026l"; // End synchronized output
+			if (this.useSynchronizedOutput) buffer += "\x1b[?2026l"; // End synchronized output
 			this.terminal.write(buffer);
 			this.cursorRow = Math.max(0, newLines.length - 1);
 			this.hardwareCursorRow = this.cursorRow;
@@ -733,17 +735,60 @@ export class TUI extends Container {
 		}
 
 		if (
-			newLines.length !== this.previousLines.length &&
+			newLines.length < this.previousLines.length &&
 			(newLines.length <= height || this.previousLines.length <= height)
 		) {
-			logRedraw(`bottom-anchored short block resized (${this.previousLines.length} -> ${newLines.length})`);
+			logRedraw(`bottom-anchored short block shrunk (${this.previousLines.length} -> ${newLines.length})`);
 			fullRender(true);
 			return;
 		}
 
-		if (newLines.length < this.previousLines.length && newLines.length > height) {
-			logRedraw(`bottom-anchored tall block shrunk (${this.previousLines.length} -> ${newLines.length})`);
-			fullRender(true);
+		// Tall→tall shrink with viewport baseline shift. Both buffers fill the
+		// viewport, but newLines is shorter, so the viewport baseline must move
+		// from (previousLines.length - height) down to (newLines.length - height).
+		// The differential render below would see no diff in the overlapping
+		// indices (content[20..39] is identical between frames) and would leave
+		// the screen showing stale rows from the old viewport.
+		//
+		// Repaint the visible viewport in place without \x1b[2J — the four-pass
+		// flicker fix exists exactly to avoid that full-screen clear — then reset
+		// maxLinesRendered and previousViewportTop so subsequent diffs anchor
+		// against the new baseline.
+		if (
+			this.previousLines.length > height &&
+			newLines.length > height &&
+			newLines.length < this.previousLines.length &&
+			this.overlayStack.length === 0
+		) {
+			logRedraw(`tall→tall shrink viewport realign (${this.previousLines.length} -> ${newLines.length})`);
+			const newViewportTop = getViewportTop(newLines.length);
+			const currentScreenRow = Math.max(0, hardwareCursorRow - prevViewportTop);
+			let buffer = this.useSynchronizedOutput ? "\x1b[?2026h" : "";
+			if (currentScreenRow > 0) {
+				buffer += `\x1b[${currentScreenRow}A`;
+			}
+			buffer += "\r";
+			for (let i = 0; i < height; i++) {
+				const idx = newViewportTop + i;
+				if (i > 0) buffer += "\r\n";
+				buffer += "\x1b[2K";
+				let line = newLines[idx] ?? "";
+				if (!isImageLine(line) && visibleWidth(line) > width) {
+					line = truncateToWidth(line, width);
+				}
+				buffer += line;
+			}
+			if (this.useSynchronizedOutput) buffer += "\x1b[?2026l";
+			this.terminal.write(buffer);
+			this.cursorRow = newLines.length - 1;
+			this.hardwareCursorRow = newLines.length - 1;
+			this.maxLinesRendered = newLines.length;
+			this.previousViewportTop = newViewportTop;
+			this.positionHardwareCursor(cursorPos, newLines.length);
+			this.previousLines = newLines;
+			this.previousWidth = width;
+			this.previousHeight = height;
+			this._shrinkDebounceActive = false;
 			return;
 		}
 
@@ -794,7 +839,7 @@ export class TUI extends Container {
 			}
 			lastChanged = newLines.length - 1;
 		}
-		const appendStart = appendedLines && firstChanged === this.previousLines.length && firstChanged > 0;
+		let appendStart = appendedLines && firstChanged === this.previousLines.length && firstChanged > 0;
 
 		// No changes - but still need to update hardware cursor position if it moved
 		if (firstChanged === -1) {
@@ -807,7 +852,7 @@ export class TUI extends Container {
 		// All changes are in deleted lines (nothing to render, just clear)
 		if (firstChanged >= newLines.length) {
 			if (this.previousLines.length > newLines.length) {
-				let buffer = "\x1b[?2026h";
+				let buffer = this.useSynchronizedOutput ? "\x1b[?2026h" : "";
 				// Move to end of new content (clamp to 0 for empty content)
 				const targetRow = Math.max(0, newLines.length - 1);
 				const lineDiff = computeLineDiff(targetRow);
@@ -831,7 +876,7 @@ export class TUI extends Container {
 				if (extraLines > 0) {
 					buffer += `\x1b[${extraLines}A`;
 				}
-				buffer += "\x1b[?2026l";
+				if (this.useSynchronizedOutput) buffer += "\x1b[?2026l";
 				this.terminal.write(buffer);
 				this.cursorRow = targetRow;
 				this.hardwareCursorRow = targetRow;
@@ -844,19 +889,34 @@ export class TUI extends Container {
 			return;
 		}
 
-		// Check if firstChanged is above what was previously visible
-		// Use previousLines.length (not maxLinesRendered) to avoid false positives after content shrinks
+		// Check if firstChanged is above what was previously visible.
+		// Use previousLines.length (not maxLinesRendered) to avoid false positives after content shrinks.
 		const previousContentViewportTop = getViewportTop(this.previousLines.length);
+		let clampedToViewport = false;
 		if (firstChanged < previousContentViewportTop) {
-			// First change is above previous viewport - need full re-render
-			logRedraw(`firstChanged < viewportTop (${firstChanged} < ${previousContentViewportTop})`);
-			fullRender(true);
-			return;
+			// First change is above the viewport. Avoid a full screen clear (\x1b[2J)
+			// which causes the bottom panel to flicker. Instead redraw from the actual
+			// viewport top down through the bottom of new content so every visible row
+			// gets the correct line, even if the viewport shifted (content shrank).
+			//
+			// Pick the smaller of the two viewport tops so any row currently on screen
+			// is covered. Force lastChanged to the end of new content so the render loop
+			// repaints the bottom rows that may now hold stale content from the previous
+			// frame (the case that caused "empty screen until next tick" after the clamp).
+			const newViewportTop = getViewportTop(newLines.length);
+			const clampedFirst = Math.max(0, Math.min(previousContentViewportTop, newViewportTop));
+			logRedraw(
+				`firstChanged < viewportTop (${firstChanged} < ${previousContentViewportTop}) — repaint from ${clampedFirst}`,
+			);
+			firstChanged = clampedFirst;
+			lastChanged = Math.max(lastChanged, newLines.length - 1);
+			appendStart = false;
+			clampedToViewport = true;
 		}
 
 		// Render from first changed line to end
 		// Build buffer with all updates wrapped in synchronized output
-		let buffer = "\x1b[?2026h"; // Begin synchronized output
+		let buffer = this.useSynchronizedOutput ? "\x1b[?2026h" : ""; // Begin synchronized output
 		const prevViewportBottom = prevViewportTop + height - 1;
 		const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;
 		if (moveTargetRow > prevViewportBottom) {
@@ -899,23 +959,38 @@ export class TUI extends Container {
 		// Track where cursor ended up after rendering
 		let finalCursorRow = renderEnd;
 
-		// If we had more lines before, clear them and move cursor back
-		if (this.previousLines.length > newLines.length) {
-			// Move to end of new content first if we stopped before it
-			if (renderEnd < newLines.length - 1) {
-				const moveDown = newLines.length - 1 - renderEnd;
-				buffer += `\x1b[${moveDown}B`;
-				finalCursorRow = newLines.length - 1;
-			}
-			const extraLines = this.previousLines.length - newLines.length;
-			for (let i = newLines.length; i < this.previousLines.length; i++) {
-				buffer += "\r\n\x1b[2K";
+		// If we had more lines before, clear ghost lines — but only when they are
+		// actually visible. For tall buffers (both counts > height) the viewport shifts
+		// up so the differential render already overwrites the old bottom rows; emitting
+		// \r\n at screen-bottom would cause spurious terminal scrolling.
+		//
+		// Also skip ghost clearing when the clamp-to-viewport path was taken: that path
+		// renders from clampedFirst through newLines.length-1, filling the entire visible
+		// viewport. There are no ghost lines below renderEnd, and the local `viewportTop`
+		// is based on the stale (larger) maxLinesRendered, so the renderEndScreenRow
+		// check below would compute a negative value and incorrectly fire the cleanup —
+		// which then emits \r\n past screen-bottom and scrolls correct lines into
+		// scrollback while filling the viewport with blanks.
+		if (this.previousLines.length > newLines.length && !clampedToViewport) {
+			const renderEndScreenRow = renderEnd - viewportTop;
+			const ghostLinesVisible = renderEndScreenRow < height - 1;
+			if (ghostLinesVisible) {
+				// Move to end of new content first if we stopped before it
+				if (renderEnd < newLines.length - 1) {
+					const moveDown = newLines.length - 1 - renderEnd;
+					buffer += `\x1b[${moveDown}B`;
+					finalCursorRow = newLines.length - 1;
+				}
+				const extraLines = this.previousLines.length - newLines.length;
+				for (let i = newLines.length; i < this.previousLines.length; i++) {
+					buffer += "\r\n\x1b[2K";
+				}
+				// Move cursor back to end of new content
+				buffer += `\x1b[${extraLines}A`;
 			}
-			// Move cursor back to end of new content
-			buffer += `\x1b[${extraLines}A`;
 		}
 
-		buffer += "\x1b[?2026l"; // End synchronized output
+		if (this.useSynchronizedOutput) buffer += "\x1b[?2026l"; // End synchronized output
 
 		if (process.env.PI_TUI_DEBUG === "1") {
 			const debugDir = path.join(os.tmpdir(), "tui");
@@ -954,8 +1029,16 @@ export class TUI extends Container {
 		// hardwareCursorRow tracks actual terminal cursor position (for movement)
 		this.cursorRow = Math.max(0, newLines.length - 1);
 		this.hardwareCursorRow = finalCursorRow;
-		// Track terminal's working area (grows but doesn't shrink unless cleared)
-		this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
+		// Track terminal's working area (grows but doesn't shrink unless cleared).
+		// Exception: when the clamp-to-viewport path repainted shrunk content, the
+		// visible viewport now anchors to newLines.length, so subsequent
+		// computeLineDiff calls need viewportTop = newLines.length - height.
+		// Without this reset, hardwareCursorRow's physical row goes negative.
+		if (clampedToViewport && newLines.length < this.maxLinesRendered) {
+			this.maxLinesRendered = newLines.length;
+		} else {
+			this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
+		}
 		this.previousViewportTop = getViewportTop(this.maxLinesRendered);
 
 		// Position hardware cursor for IME