gsd-pi 2.80.0 → 2.81.0-dev.3cddbbba2

package/packages/pi-tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-tui",
-  "version": "2.80.0",
+  "version": "2.81.0",
   "description": "Terminal User Interface library (vendored from pi-mono)",
   "type": "module",
   "gsd": {

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

@@ -124,10 +124,29 @@ function applySgr(state: SgrState, paramString: string): void {
 
 function stripAnsi(line: string): string {
 	// Remove CSI sequences. Good enough for these tests.
-	return line.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "");
+	return line
+		.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+		.replace(/\x1b\][\s\S]*?(?:\x07|\x1b\\)/g, "");
 }
 
 describe("compositeOverlays — backdrop", () => {
+	it("positions overlays against the visible terminal when base content is short", () => {
+		const base = ["footer-like content"];
+		const overlay = makeEntry(["TOP"], {
+			width: 3,
+			anchor: "top-left",
+		});
+
+		const result = compositeOverlays(base, [overlay], 20, 10, 1);
+
+		assert.equal(result.length, 10);
+		assert.ok(stripAnsi(result[0]).startsWith("TOP"), "top overlay should render on terminal row 0");
+		assert.ok(
+			stripAnsi(result.at(-1) ?? "").includes("footer-like content"),
+			"short base content remains bottom-anchored",
+		);
+	});
+
 	it("dims base lines outside the overlay when backdrop is true", () => {
 		const base = ["hello world", "second line"];
 		const overlay = makeEntry(["OVERLAY"], {

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

@@ -0,0 +1,76 @@
+// GSD2 - Tests for terminal style primitives
+
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import stripAnsi from "strip-ansi";
+
+import { style, visibleWidth } from "../index.js";
+
+describe("style", () => {
+	test("renders rule frames with title, right title, and body gutter", () => {
+		const lines = style()
+			.border("rule")
+			.title("• Tool Bash")
+			.titleRight("Running")
+			.render(["$ npm test"], 40);
+
+		const plain = lines.map((line) => stripAnsi(line));
+		assert.match(plain[0], /^─+$/);
+		assert.equal(visibleWidth(plain[0]), 40);
+		assert.ok(plain[1].includes("• Tool Bash"));
+		assert.ok(plain[1].includes("Running"));
+		assert.equal(visibleWidth(plain[1]), 40);
+		assert.ok(plain[2].startsWith("│ "));
+		assert.ok(plain[2].includes("$ npm test"));
+	});
+
+	test("renders boxed rounded borders with padded content", () => {
+		const lines = style()
+			.border("rounded")
+			.paddingX(1)
+			.render(["Done"], 12)
+			.map((line) => stripAnsi(line));
+
+		assert.equal(lines[0], "╭──────────╮");
+		assert.equal(lines[1], "│ Done     │");
+		assert.equal(lines[2], "╰──────────╯");
+	});
+
+	test("truncates content to the available visible width", () => {
+		const plain = style().border("rule").render(["abcdefghij"], 7).map((line) => stripAnsi(line));
+
+		assert.equal(plain[1], "│ abcde");
+		assert.equal(visibleWidth(plain[1]), 7);
+	});
+
+	test("renders minimal left-rule surfaces", () => {
+		const plain = style().border("minimal").title("note").render(["No full card"], 20).map((line) => stripAnsi(line));
+
+		assert.equal(plain[0], "│ note              ");
+		assert.equal(plain[1], "│ No full card      ");
+	});
+
+	test("applies dashboard density and body gutters", () => {
+		const plain = style()
+			.border("single")
+			.density("dashboard")
+			.bodyGutter("· ")
+			.render(["body"], 14)
+			.map((line) => stripAnsi(line));
+
+		assert.equal(plain[0], "┌────────────┐");
+		assert.equal(plain[1], "│            │");
+		assert.equal(plain[2], "│·  body     │");
+		assert.equal(plain[3], "│            │");
+		assert.equal(plain[4], "└────────────┘");
+	});
+
+	test("passes tone to toneColor when no explicit border color is set", () => {
+		const lines = style()
+			.border("minimal")
+			.tone("success", (tone, text) => `[${tone}]${text}`)
+			.render(["ok"], 8);
+
+		assert.equal(lines[0], "[success]│ ok    ");
+	});
+});

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

@@ -1,11 +1,13 @@
+// GSD-2 + packages/pi-tui/src/__tests__/tui.test.ts - Regression coverage for the TUI renderer and container lifecycle.
+
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 
-import { Container, TUI } from "../tui.js";
+import { Container, CURSOR_MARKER, TUI } from "../tui.js";
 import type { Component } from "../tui.js";
 import type { Terminal } from "../terminal.js";
 
-function makeTerminal(): Terminal {
+function makeTerminal(writes?: string[]): Terminal {
 	return {
 		isTTY: true,
 		columns: 80,
@@ -14,7 +16,9 @@ function makeTerminal(): Terminal {
 		start() {},
 		stop() {},
 		drainInput: async () => {},
-		write() {},
+		write(data: string) {
+			writes?.push(data);
+		},
 		moveBy() {},
 		hideCursor() {},
 		showCursor() {},
@@ -45,6 +49,28 @@ function makeTerminal(): Terminal {
 // separate refactor PR rather than shipping a tautology. See #4794.
 
 describe("TUI", () => {
+	it("updates an editor line from the real hardware cursor row", () => {
+		const writes: string[] = [];
+		const terminal = makeTerminal(writes);
+		let value = "input";
+		const tui = new TUI(terminal);
+		tui.addChild({
+			render: () => ["top", `${value}${CURSOR_MARKER}`, "  GSD  No project loaded - run /gsd to start"],
+			invalidate() {},
+		});
+		const anyTui = tui as any;
+
+		anyTui.doRender();
+		const writeCountAfterFirstRender = writes.length;
+
+		value = "input x";
+		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");
+	});
+
 	it("does not swallow a bare Escape keypress while waiting for the cell-size response", () => {
 		const tui = new TUI(makeTerminal());
 		const received: string[] = [];

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

@@ -1,5 +1,14 @@
 // Core TUI interfaces and classes
 
+// Style primitives
+export {
+	style,
+	TerminalStyle,
+	type TerminalBorderStyle,
+	type TerminalDensity,
+	type TerminalStyleSpec,
+	type TerminalTone,
+} from "./style.js";
 // Autocomplete support
 export {
 	type AutocompleteItem,

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

@@ -313,13 +313,16 @@ export function compositeOverlays(
 		minLinesNeeded = Math.max(minLinesNeeded, row + overlayLines.length);
 	}
 
-	// Ensure result covers the terminal working area to keep overlay positioning stable across resizes.
-	// maxLinesRendered can exceed current content length after a shrink; pad to keep viewportStart consistent.
-	const workingHeight = Math.max(maxLinesRendered, minLinesNeeded);
-
-	// Extend result with empty lines if content is too short for overlay placement or working area
-	while (result.length < workingHeight) {
-		result.push("");
+	// Ensure overlays are positioned against the visible terminal grid, not a
+	// short bottom-anchored render buffer. Without the terminal-height floor, a
+	// sparse app screen pushes "top" overlays down with the rest of the content.
+	const workingHeight = Math.max(termHeight, maxLinesRendered, minLinesNeeded);
+
+	// Extend upward when content is shorter than the working area. This keeps
+	// the app's normal content bottom-anchored while giving overlays a full
+	// viewport-sized coordinate system.
+	if (result.length < workingHeight) {
+		result.unshift(...Array.from({ length: workingHeight - result.length }, () => ""));
 	}
 
 	const viewportStart = Math.max(0, workingHeight - termHeight);

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

@@ -0,0 +1,225 @@
+// GSD2 - Terminal style primitives for framed TUI surfaces
+
+import { truncateToWidth, visibleWidth } from "./utils.js";
+
+export type TerminalBorderStyle = "none" | "rule" | "single" | "rounded" | "heavy" | "minimal";
+export type TerminalDensity = "compact" | "comfortable" | "dashboard";
+export type TerminalTone = "default" | "muted" | "running" | "success" | "error" | "current";
+
+export interface TerminalStyleSpec {
+	width?: number;
+	paddingX?: number;
+	paddingY?: number;
+	border?: TerminalBorderStyle;
+	density?: TerminalDensity;
+	tone?: TerminalTone;
+	borderColor?: (text: string) => string;
+	foreground?: (text: string) => string;
+	toneColor?: (tone: TerminalTone, text: string) => string;
+	title?: string;
+	titleRight?: string;
+	titleColor?: (text: string) => string;
+	titleRightColor?: (text: string) => string;
+	bodyGutter?: string;
+}
+
+type BorderChars = {
+	topLeft: string;
+	topRight: string;
+	bottomLeft: string;
+	bottomRight: string;
+	horizontal: string;
+	vertical: string;
+};
+
+const BORDER_CHARS: Record<Exclude<TerminalBorderStyle, "none" | "rule" | "minimal">, BorderChars> = {
+	single: {
+		topLeft: "┌",
+		topRight: "┐",
+		bottomLeft: "└",
+		bottomRight: "┘",
+		horizontal: "─",
+		vertical: "│",
+	},
+	rounded: {
+		topLeft: "╭",
+		topRight: "╮",
+		bottomLeft: "╰",
+		bottomRight: "╯",
+		horizontal: "─",
+		vertical: "│",
+	},
+	heavy: {
+		topLeft: "┏",
+		topRight: "┓",
+		bottomLeft: "┗",
+		bottomRight: "┛",
+		horizontal: "━",
+		vertical: "┃",
+	},
+};
+
+const DENSITY_PADDING: Record<TerminalDensity, { x: number; y: number }> = {
+	compact: { x: 0, y: 0 },
+	comfortable: { x: 1, y: 0 },
+	dashboard: { x: 1, y: 1 },
+};
+
+function padVisible(line: string, width: number): string {
+	return line + " ".repeat(Math.max(0, width - visibleWidth(line)));
+}
+
+function color(fn: ((text: string) => string) | undefined, text: string): string {
+	return fn ? fn(text) : text;
+}
+
+function normalizeWidth(spec: TerminalStyleSpec, width?: number): number {
+	return Math.max(1, Math.floor(width ?? spec.width ?? 80));
+}
+
+export class TerminalStyle {
+	private readonly spec: TerminalStyleSpec;
+
+	constructor(spec: TerminalStyleSpec = {}) {
+		this.spec = { ...spec };
+	}
+
+	width(width: number): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, width });
+	}
+
+	padding(x: number, y = x): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, paddingX: x, paddingY: y });
+	}
+
+	paddingX(paddingX: number): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, paddingX });
+	}
+
+	paddingY(paddingY: number): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, paddingY });
+	}
+
+	border(border: TerminalBorderStyle): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, border });
+	}
+
+	density(density: TerminalDensity): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, density });
+	}
+
+	tone(tone: TerminalTone, toneColor?: (tone: TerminalTone, text: string) => string): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, tone, toneColor });
+	}
+
+	borderColor(borderColor: (text: string) => string): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, borderColor });
+	}
+
+	foreground(foreground: (text: string) => string): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, foreground });
+	}
+
+	toneColor(toneColor: (tone: TerminalTone, text: string) => string): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, toneColor });
+	}
+
+	title(title: string, titleColor?: (text: string) => string): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, title, titleColor });
+	}
+
+	titleRight(titleRight: string, titleRightColor?: (text: string) => string): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, titleRight, titleRightColor });
+	}
+
+	rightTitle(titleRight: string, titleRightColor?: (text: string) => string): TerminalStyle {
+		return this.titleRight(titleRight, titleRightColor);
+	}
+
+	bodyGutter(bodyGutter: string): TerminalStyle {
+		return new TerminalStyle({ ...this.spec, bodyGutter });
+	}
+
+	render(contentLines: string[], width?: number): string[] {
+		const outerWidth = normalizeWidth(this.spec, width);
+		const border = this.spec.border ?? "none";
+		const densityPadding = DENSITY_PADDING[this.spec.density ?? "compact"];
+		const paddingX = Math.max(0, Math.floor(this.spec.paddingX ?? densityPadding.x));
+		const paddingY = Math.max(0, Math.floor(this.spec.paddingY ?? densityPadding.y));
+		const gutter = this.spec.bodyGutter ?? "";
+		const gutterWidth = visibleWidth(gutter);
+		const borderColumns = border === "none" ? 0 : 2;
+		const innerWidth = Math.max(1, outerWidth - borderColumns - paddingX * 2 - gutterWidth);
+		const emptyPaddedLine = " ".repeat(paddingX * 2 + innerWidth);
+		const sourceLines = contentLines.length > 0 ? contentLines : [""];
+		const paddedBody = [
+			...Array.from({ length: paddingY }, () => emptyPaddedLine),
+			...sourceLines.map((line) => {
+				const clipped = truncateToWidth(line, innerWidth, "");
+				const styled = color(this.spec.foreground, clipped);
+				return `${gutter}${" ".repeat(paddingX)}${padVisible(styled, innerWidth)}${" ".repeat(paddingX)}`;
+			}),
+			...Array.from({ length: paddingY }, () => emptyPaddedLine),
+		];
+		const borderColorFn = this.spec.borderColor ?? (this.spec.toneColor ? (value: string) => this.spec.toneColor?.(this.spec.tone ?? "default", value) ?? value : undefined);
+		const borderColor = (text: string) => color(borderColorFn, text);
+
+		if (border === "none") {
+			return paddedBody.map((line) => padVisible(line, outerWidth));
+		}
+
+		if (border === "rule") {
+			return [
+				borderColor("─".repeat(outerWidth)),
+				...this.renderTitleRows(outerWidth),
+				...paddedBody.map((line) => `${borderColor("│ ")}${truncateToWidth(line, Math.max(1, outerWidth - 2), "")}`),
+			];
+		}
+
+		if (border === "minimal") {
+			const contentWidth = Math.max(1, outerWidth - 2);
+			return [
+				...this.renderTitleRows(contentWidth).map((line) => `${borderColor("│ ")}${padVisible(line, contentWidth)}`),
+				...paddedBody.map((line) => `${borderColor("│ ")}${padVisible(line, contentWidth)}`),
+			];
+		}
+
+		const chars = BORDER_CHARS[border];
+		const horizontalWidth = Math.max(0, outerWidth - 2);
+		const top = borderColor(
+			`${chars.topLeft}${chars.horizontal.repeat(horizontalWidth)}${chars.topRight}`,
+		);
+		const bottom = borderColor(
+			`${chars.bottomLeft}${chars.horizontal.repeat(horizontalWidth)}${chars.bottomRight}`,
+		);
+		const contentWidth = Math.max(1, outerWidth - 2);
+		return [
+			top,
+			...this.renderTitleRows(contentWidth).map((line) =>
+				`${borderColor(chars.vertical)}${padVisible(line, contentWidth)}${borderColor(chars.vertical)}`,
+			),
+			...paddedBody.map((line) =>
+				`${borderColor(chars.vertical)}${padVisible(line, contentWidth)}${borderColor(chars.vertical)}`,
+			),
+			bottom,
+		];
+	}
+
+	private renderTitleRows(width: number): string[] {
+		const leftRaw = this.spec.title ?? "";
+		const rightRaw = this.spec.titleRight ?? "";
+		if (!leftRaw && !rightRaw) return [];
+
+		const leftBudget = rightRaw ? Math.max(1, width - visibleWidth(rightRaw) - 1) : width;
+		const left = color(this.spec.titleColor, truncateToWidth(leftRaw, leftBudget, ""));
+		const right = color(this.spec.titleRightColor, rightRaw);
+		const gap = rightRaw
+			? Math.max(1, width - visibleWidth(left) - visibleWidth(right))
+			: Math.max(0, width - visibleWidth(left));
+		return [`${left}${" ".repeat(gap)}${right}`];
+	}
+}
+
+export function style(spec: TerminalStyleSpec = {}): TerminalStyle {
+	return new TerminalStyle(spec);
+}

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

@@ -1,3 +1,4 @@
+// GSD-2 + packages/pi-tui/src/tui.ts - Terminal UI renderer with differential rendering.
 /**
  * Minimal TUI implementation with differential rendering
  */
@@ -250,7 +251,7 @@ export class TUI extends Container {
 	public onDebug?: () => void;
 	private renderRequested = false;
 	private cursorRow = 0; // Logical cursor row (end of rendered content)
-	private hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
+	private hardwareCursorRow = 0; // Logical content row of the terminal cursor; physical screen row = hardwareCursorRow - previousViewportTop
 	private inputBuffer = ""; // Buffer for parsing terminal responses
 	private cellSizeQueryPending = false;
 	private showHardwareCursor = process.env.PI_HARDWARE_CURSOR === "1" || process.env.TERM_PROGRAM === "WarpTerminal";
@@ -635,7 +636,8 @@ export class TUI extends Container {
 		if (this.stopped) return;
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
-		let viewportTop = Math.max(0, this.maxLinesRendered - height);
+		const getViewportTop = (lineCount: number): number => lineCount - height;
+		let viewportTop = getViewportTop(this.maxLinesRendered);
 		let prevViewportTop = this.previousViewportTop;
 		let hardwareCursorRow = this.hardwareCursorRow;
 		const computeLineDiff = (targetRow: number): number => {
@@ -672,14 +674,16 @@ export class TUI extends Container {
 		const fullRender = (clear: boolean): void => {
 			this.fullRedrawCount += 1;
 			let buffer = "\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
 				// block to the terminal bottom so the editor / belowEditor
 				// widgets do not jump to row 1 after a chat clear. When the
 				// block is taller than the viewport, Math.max(1, …) falls back
 				// to row 1 — same as the prior `\x1b[H` behavior.
-				const startRow = Math.max(1, height - Math.max(1, newLines.length) + 1);
 				buffer += `\x1b[2J\x1b[${startRow};1H`;
+			} else if (startRow > 1) {
+				buffer += `\x1b[${startRow};1H`;
 			}
 			for (let i = 0; i < newLines.length; i++) {
 				if (i > 0) buffer += "\r\n";
@@ -699,7 +703,7 @@ export class TUI extends Container {
 			} else {
 				this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
 			}
-			this.previousViewportTop = Math.max(0, this.maxLinesRendered - height);
+			this.previousViewportTop = getViewportTop(this.maxLinesRendered);
 			this.positionHardwareCursor(cursorPos, newLines.length);
 			this.previousLines = newLines;
 			this.previousWidth = width;
@@ -728,6 +732,15 @@ export class TUI extends Container {
 			return;
 		}
 
+		if (
+			newLines.length !== this.previousLines.length &&
+			(newLines.length <= height || this.previousLines.length <= height)
+		) {
+			logRedraw(`bottom-anchored short block resized (${this.previousLines.length} -> ${newLines.length})`);
+			fullRender(true);
+			return;
+		}
+
 		// Content shrunk below the working area and no overlays - re-render to clear empty rows
 		// (overlays need the padding, so only do this when no overlays are active)
 		// Configurable via setClearOnShrink() or PI_CLEAR_ON_SHRINK=0 env var
@@ -780,7 +793,7 @@ export class TUI extends Container {
 		// No changes - but still need to update hardware cursor position if it moved
 		if (firstChanged === -1) {
 			this.positionHardwareCursor(cursorPos, newLines.length);
-			this.previousViewportTop = Math.max(0, this.maxLinesRendered - height);
+			this.previousViewportTop = getViewportTop(this.maxLinesRendered);
 			this.previousHeight = height;
 			return;
 		}
@@ -821,13 +834,13 @@ export class TUI extends Container {
 			this.previousLines = newLines;
 			this.previousWidth = width;
 			this.previousHeight = height;
-			this.previousViewportTop = Math.max(0, this.maxLinesRendered - height);
+			this.previousViewportTop = getViewportTop(this.maxLinesRendered);
 			return;
 		}
 
 		// Check if firstChanged is above what was previously visible
 		// Use previousLines.length (not maxLinesRendered) to avoid false positives after content shrinks
-		const previousContentViewportTop = Math.max(0, this.previousLines.length - height);
+		const previousContentViewportTop = getViewportTop(this.previousLines.length);
 		if (firstChanged < previousContentViewportTop) {
 			// First change is above previous viewport - need full re-render
 			logRedraw(`firstChanged < viewportTop (${firstChanged} < ${previousContentViewportTop})`);
@@ -937,7 +950,7 @@ export class TUI extends Container {
 		this.hardwareCursorRow = finalCursorRow;
 		// Track terminal's working area (grows but doesn't shrink unless cleared)
 		this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
-		this.previousViewportTop = Math.max(0, this.maxLinesRendered - height);
+		this.previousViewportTop = getViewportTop(this.maxLinesRendered);
 
 		// Position hardware cursor for IME
 		this.positionHardwareCursor(cursorPos, newLines.length);