gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -1,29 +1,49 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { setTimeout as delay } from "node:timers/promises";
 
 import { StdinBuffer } from "../stdin-buffer.js";
 
+// These tests use node:test's mock.timers to advance virtual time.
+// They previously relied on wall-clock delays (delay(20), delay(150))
+// racing the OS scheduler. On Windows the default setTimeout resolution is
+// ~15.6ms, so a real-time delay of 20ms sometimes fired only one of two
+// pending timers — hence the flake referenced in issue #4795.
+//
+// By mocking setTimeout/clearTimeout we control exactly when the buffer's
+// sequence timeout and stale timeout fire, eliminating scheduler-induced
+// flake and making the tests deterministic on every platform.
+
 describe("StdinBuffer", () => {
-	it("flushes a lone Escape keypress", async () => {
+	it("flushes a lone Escape keypress after the sequence timeout", (t) => {
+		t.mock.timers.enable({ apis: ["setTimeout"] });
 		const buffer = new StdinBuffer({ timeout: 5 });
 		const received: string[] = [];
 		buffer.on("data", (sequence) => received.push(sequence));
 
 		buffer.process("\x1b");
-		await delay(20);
+
+		// Before the timeout fires the lone ESC is still buffered.
+		assert.deepEqual(received, []);
+		assert.equal(buffer.getBuffer(), "\x1b");
+
+		// Advance past the sequence timeout.
+		t.mock.timers.tick(5);
 
 		assert.deepEqual(received, ["\x1b"]);
 		assert.equal(buffer.getBuffer(), "");
 	});
 
-	it("keeps split CSI focus and mouse sequences buffered until completion", async () => {
+	it("keeps split CSI focus and mouse sequences buffered until completion", (t) => {
+		t.mock.timers.enable({ apis: ["setTimeout"] });
 		const buffer = new StdinBuffer({ timeout: 5 });
 		const received: string[] = [];
 		buffer.on("data", (sequence) => received.push(sequence));
 
 		buffer.process("\x1b[");
-		await delay(20);
+		// Even after the normal timeout elapses, an incomplete CSI prefix must
+		// remain buffered (not emitted as literal text) so split escape
+		// sequences stay intact.
+		t.mock.timers.tick(5);
 		assert.deepEqual(received, []);
 		assert.equal(buffer.getBuffer(), "\x1b[");
 
@@ -32,7 +52,7 @@ describe("StdinBuffer", () => {
 		assert.equal(buffer.getBuffer(), "");
 
 		buffer.process("\x1b[<35;20;");
-		await delay(20);
+		t.mock.timers.tick(5);
 		assert.deepEqual(received, ["\x1b[I"]);
 		assert.equal(buffer.getBuffer(), "\x1b[<35;20;");
 
@@ -40,4 +60,40 @@ describe("StdinBuffer", () => {
 		assert.deepEqual(received, ["\x1b[I", "\x1b[<35;20;5m"]);
 		assert.equal(buffer.getBuffer(), "");
 	});
+
+	it("flushes a stale incomplete escape prefix after the stale timeout", (t) => {
+		t.mock.timers.enable({ apis: ["setTimeout"] });
+		const buffer = new StdinBuffer({ timeout: 20, staleTimeout: 40 });
+		const received: string[] = [];
+		buffer.on("data", (sequence) => received.push(sequence));
+
+		buffer.process("\x1b[");
+
+		// Sequence timeout: keeps the incomplete prefix buffered and starts
+		// the stale timer.
+		t.mock.timers.tick(20);
+		assert.deepEqual(received, []);
+		assert.equal(buffer.getBuffer(), "\x1b[");
+
+		// Stale timer fires — prefix is emitted as-is.
+		t.mock.timers.tick(40);
+
+		assert.deepEqual(received, ["\x1b["]);
+		assert.equal(buffer.getBuffer(), "");
+	});
+
+	it("still allows an incomplete escape prefix to complete before the stale timeout", (t) => {
+		t.mock.timers.enable({ apis: ["setTimeout"] });
+		const buffer = new StdinBuffer({ timeout: 5, staleTimeout: 30 });
+		const received: string[] = [];
+		buffer.on("data", (sequence) => received.push(sequence));
+
+		buffer.process("\x1b[");
+		// Advance past the sequence timeout (but not the stale timeout).
+		t.mock.timers.tick(10);
+		buffer.process("I");
+
+		assert.deepEqual(received, ["\x1b[I"]);
+		assert.equal(buffer.getBuffer(), "");
+	});
 });

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

@@ -25,43 +25,24 @@ function makeTerminal(): Terminal {
 	};
 }
 
-describe("TUI clearOnShrink debounce", () => {
-	it("defers full redraw on first shrink and commits on second", () => {
-		const tui = new TUI(makeTerminal());
-		const anyTui = tui as any;
-
-		// Enable clearOnShrink and simulate prior rendering state
-		anyTui.clearOnShrink = true;
-		anyTui.maxLinesRendered = 10;
-		anyTui._shrinkDebounceActive = false;
-
-		// Simulate a shrink: newLines has fewer lines than maxLinesRendered
-		// First shrink should set debounce flag but NOT reset maxLinesRendered
-		anyTui._shrinkDebounceActive = false;
-
-		// Verify the flag exists and is initially false
-		assert.equal(anyTui._shrinkDebounceActive, false);
-
-		// After setting it to true (simulating first shrink detection),
-		// maxLinesRendered should remain at the old value so the condition
-		// triggers again on the next render
-		anyTui._shrinkDebounceActive = true;
-		assert.equal(anyTui.maxLinesRendered, 10, "maxLinesRendered must not change during deferred shrink");
-	});
-
-	it("resets debounce flag when content grows back", () => {
-		const tui = new TUI(makeTerminal());
-		const anyTui = tui as any;
-
-		anyTui.clearOnShrink = true;
-		anyTui._shrinkDebounceActive = true;
-
-		// Simulating the else branch: content grew back or no shrink
-		// The code sets _shrinkDebounceActive = false in the else branch
-		anyTui._shrinkDebounceActive = false;
-		assert.equal(anyTui._shrinkDebounceActive, false);
-	});
-});
+// TUI clearOnShrink debounce — tests removed in #4794 (ref #4784).
+//
+// The previous tests mutated private fields (`_shrinkDebounceActive`,
+// `maxLinesRendered`) and then asserted the values they just wrote —
+// pure tautologies that never exercised the real debounce path in
+// `renderNow()` (tui.ts:734-754). A regression that narrowed the
+// condition, reversed the flag flip, or dropped the "keep
+// maxLinesRendered" rule would have passed all of them.
+//
+// A proper test would (a) render a component that produces N lines to
+// establish `maxLinesRendered`, (b) swap in a component that produces
+// N-k lines to trigger the shrink branch, and (c) observe terminal
+// writes to confirm the debounce defers/commits the full redraw on the
+// expected render call.
+//
+// That test setup requires exposing enough of the render path (or
+// extracting the debounce decision into a pure helper) — deferred to a
+// separate refactor PR rather than shipping a tautology. See #4794.
 
 describe("TUI", () => {
 	it("does not swallow a bare Escape keypress while waiting for the cell-size response", () => {

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

@@ -37,11 +37,27 @@ describe("Input", () => {
 		const input = new Input();
 		input.secure = true;
 		input.focused = true;
-		input.handleInput("secret123");
+		const SECRET = "secret123";
+		input.handleInput(SECRET);
 
 		const line = input.render(40)[0] ?? "";
-		assert.ok(!line.includes("secret123"), "rendered line must not expose raw secret text");
-		assert.ok(line.includes("*********"), "rendered line should include masked characters");
+		// Previous assertion was `line.includes("*********")` — a literal
+		// 9-star string that silently goes stale if SECRET is renamed to
+		// a different length (#4796). Match any run of asterisks and
+		// assert its length covers the secret.
+		assert.ok(
+			!line.includes(SECRET),
+			"rendered line must not expose raw secret text",
+		);
+		const maskMatch = line.match(/\*+/);
+		assert.ok(
+			maskMatch,
+			`rendered line must include masked characters, got: ${JSON.stringify(line)}`,
+		);
+		assert.ok(
+			maskMatch[0].length >= SECRET.length,
+			`mask must cover at least the secret length (${SECRET.length}), got ${maskMatch[0].length} asterisks`,
+		);
 	});
 
 	it("maps kitty keypad digits to text instead of inserting private-use glyphs", () => {

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

@@ -1,45 +1,122 @@
 // pi-tui Loader component regression tests
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// The previous version of this file contained 3 tests that called
+// `start()`/`stop()`/`dispose()` with no assertions at all — the claimed
+// regression ("interval leak") would not have failed any of them. See
+// #4794 / #4784.
+//
+// This rewrite uses Node's `mock.timers` to observe the interval that
+// `Loader` registers internally, and `mock.fn()` on the mock TUI to
+// count render requests. Each test asserts on observable behaviour:
+// how many `requestRender` calls happen per tick, whether the interval
+// is cleared on stop/dispose, and whether post-dispose stop() is safe.
 
 import { describe, it, mock, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import { Loader } from "../loader.js";
 
-function makeMockTUI() {
-	return { requestRender: mock.fn() } as any;
+interface MockTui {
+  requestRender: ReturnType<typeof mock.fn>;
+}
+
+function makeMockTUI(): MockTui {
+  return { requestRender: mock.fn() };
 }
 
 describe("Loader", () => {
-	let loader: Loader;
-	let tui: ReturnType<typeof makeMockTUI>;
-
-	beforeEach(() => {
-		tui = makeMockTUI();
-	});
-
-	afterEach(() => {
-		loader?.stop();
-	});
-
-	it("start() is idempotent — calling twice does not leak intervals", () => {
-		loader = new Loader(tui, (s) => s, (s) => s, "test");
-		// Constructor calls start() once, call it again
-		loader.start();
-		// stop() should clear the interval cleanly without orphaned timers
-		loader.stop();
-	});
-
-	it("dispose() stops the interval and nulls the TUI reference", () => {
-		loader = new Loader(tui, (s) => s, (s) => s, "test");
-		loader.dispose();
-		// After dispose, calling stop() again should be safe (no-op)
-		loader.stop();
-	});
-
-	it("stop() is safe to call multiple times", () => {
-		loader = new Loader(tui, (s) => s, (s) => s, "test");
-		loader.stop();
-		loader.stop();
-		loader.stop();
-	});
+  let loader: Loader;
+  let tui: MockTui;
+
+  beforeEach(() => {
+    tui = makeMockTUI();
+    mock.timers.enable({ apis: ["setInterval"] });
+  });
+
+  afterEach(() => {
+    try {
+      loader?.stop();
+    } catch {
+      /* best-effort */
+    }
+    mock.timers.reset();
+  });
+
+  it("constructor starts a spinner that ticks every 80ms and requests renders", () => {
+    loader = new Loader(tui as never, (s) => s, (s) => s, "test");
+    // Initial render request from start().
+    const initial = tui.requestRender.mock.callCount();
+    assert.ok(
+      initial >= 1,
+      `constructor should trigger at least one render (got ${initial})`,
+    );
+
+    // Advance 80ms — one interval tick should call requestRender once more.
+    mock.timers.tick(80);
+    assert.equal(
+      tui.requestRender.mock.callCount(),
+      initial + 1,
+      "80ms tick should advance the spinner and call requestRender",
+    );
+
+    // Advance another 240ms — three more ticks.
+    mock.timers.tick(240);
+    assert.equal(
+      tui.requestRender.mock.callCount(),
+      initial + 4,
+      "four total ticks after the initial render",
+    );
+  });
+
+  it("start() is idempotent — calling twice does not leak intervals", () => {
+    loader = new Loader(tui as never, (s) => s, (s) => s, "test");
+    // Constructor already started one interval. Call start() again.
+    loader.start();
+
+    const before = tui.requestRender.mock.callCount();
+    mock.timers.tick(80);
+    const after = tui.requestRender.mock.callCount();
+    // Exactly ONE tick's worth of work should happen — if the second
+    // start() leaked an interval, we'd see two increments per tick.
+    assert.equal(
+      after - before,
+      1,
+      "double-start must not double-tick (interval leak would show 2 increments)",
+    );
+  });
+
+  it("stop() clears the interval — no more ticks advance requestRender", () => {
+    loader = new Loader(tui as never, (s) => s, (s) => s, "test");
+    loader.stop();
+
+    const beforeTick = tui.requestRender.mock.callCount();
+    mock.timers.tick(400); // 5 tick intervals
+    assert.equal(
+      tui.requestRender.mock.callCount(),
+      beforeTick,
+      "stopped loader must not advance renders",
+    );
+  });
+
+  it("dispose() stops the interval and nulls the TUI reference", () => {
+    loader = new Loader(tui as never, (s) => s, (s) => s, "test");
+    loader.dispose();
+
+    const beforeTick = tui.requestRender.mock.callCount();
+    mock.timers.tick(400);
+    assert.equal(
+      tui.requestRender.mock.callCount(),
+      beforeTick,
+      "disposed loader must not advance renders",
+    );
+
+    // Calling stop() after dispose() must not throw.
+    assert.doesNotThrow(() => loader.stop());
+  });
+
+  it("stop() is safe to call multiple times without throwing", () => {
+    loader = new Loader(tui as never, (s) => s, (s) => s, "test");
+    loader.stop();
+    assert.doesNotThrow(() => loader.stop());
+    assert.doesNotThrow(() => loader.stop());
+  });
 });

package/packages/pi-tui/src/components/__tests__/markdown-maxlines.test.ts

@@ -69,7 +69,14 @@ test("Markdown trims trailing empty lines", () => {
 	const text = "Some text\n\n";
 	const md = new Markdown(text, 0, 0, noopTheme());
 	const lines = md.render(80);
-	// Last line should not be empty (trailing empties are trimmed)
+	// Previous assertion was `lastLine.trim().length > 0 || lines.length === 1`
+	// — the `|| lines.length === 1` disjunction trivially passed for any
+	// single-line render, so a regression that returned `['']` still
+	// passed (#4796). Assert the trim invariant directly.
+	assert.ok(lines.length > 0, "render must produce at least one line");
 	const lastLine = lines[lines.length - 1];
-	assert.ok(lastLine.trim().length > 0 || lines.length === 1, "trailing empty lines should be trimmed");
+	assert.ok(
+		lastLine.trim().length > 0,
+		`last line must have visible content after trim, got: ${JSON.stringify(lastLine)}`,
+	);
 });

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

@@ -197,6 +197,7 @@ export class Editor implements Component, Focusable {
 
 	public onSubmit?: (text: string) => void;
 	public onChange?: (text: string) => void;
+	public onPasteImagePath?: (filePath: string) => void;
 	public disableSubmit: boolean = false;
 
 	constructor(tui: TUI, theme: EditorTheme, options: EditorOptions = {}) {
@@ -1029,10 +1030,31 @@ export class Editor implements Component, Focusable {
 		}, Editor.AUTOCOMPLETE_DEBOUNCE_MS);
 	}
 
+	/**
+	 * Image file extensions recognized when pasted as a file path.
+	 *
+	 * Restricted to formats commonly accepted by AI vision APIs and that have
+	 * reliable magic-byte signatures for content verification. SVG is excluded
+	 * (XML/JS-bearing); BMP/TIFF/HEIC/HEIF/AVIF excluded for compatibility and
+	 * verification simplicity — users can convert before pasting.
+	 *
+	 * Detection assumes terminal emulators (iTerm2, Warp, etc.) paste a single
+	 * absolute file path on drag-drop. Multi-line pastes and bare extensions
+	 * are intentionally not matched.
+	 */
+	private static readonly IMAGE_EXTENSIONS = /\.(png|jpe?g|gif|webp)$/i;
+
 	private handlePaste(pastedText: string): void {
 		this.historyIndex = -1; // Exit history browsing mode
 		this.lastAction = null;
 
+		// Detect pasted image file paths (from terminal emulators like iTerm2)
+		const trimmed = pastedText.trim();
+		if (this.onPasteImagePath && !trimmed.includes("\n") && Editor.IMAGE_EXTENSIONS.test(trimmed)) {
+			this.onPasteImagePath(trimmed);
+			return;
+		}
+
 		this.pushUndoSnapshot();
 
 		// Clean the pasted text

package/packages/pi-tui/src/components/image.test.ts

@@ -10,12 +10,17 @@ import { Image } from "./image.js";
 describe("Image component (#3455)", () => {
 	const theme = { fallbackColor: (s: string) => s };
 
-	test("getDimensions returns undefined before resolution", () => {
-		// Pass explicit dimensions to avoid async parsing
+	test("getDimensions returns undefined when constructed without explicit dims", () => {
+		// Previously this test was titled "returns undefined before resolution"
+		// but only asserted `typeof getDimensions === 'function'`. The title
+		// and the assertion had nothing to do with each other (#4794).
+		// Now actually assert the undefined return.
 		const img = new Image("base64data", "image/png", theme, {});
-		// Without explicit dims, getDimensions should be undefined until async resolve
-		// But we can't easily test async here, so verify the method exists
-		assert.equal(typeof img.getDimensions, "function");
+		assert.equal(
+			img.getDimensions(),
+			undefined,
+			"without pre-resolved dims, getDimensions must return undefined until async resolve",
+		);
 	});
 
 	test("getDimensions returns dimensions when provided at construction", () => {

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

@@ -32,6 +32,9 @@ export interface EditorComponent extends Component {
 	/** Called when text changes */
 	onChange?: (text: string) => void;
 
+	/** Called when an image file path is pasted via terminal emulator */
+	onPasteImagePath?: (filePath: string) => void;
+
 	// =========================================================================
 	// History support (optional)
 	// =========================================================================

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

@@ -229,6 +229,11 @@ export type StdinBufferOptions = {
 	 * After this time, the buffer is flushed even if incomplete
 	 */
 	timeout?: number;
+	/**
+	 * Maximum time to retain an incomplete escape prefix after the normal
+	 * sequence timeout has fired (default: 1000ms).
+	 */
+	staleTimeout?: number;
 };
 
 export type StdinBufferEventMap = {
@@ -243,13 +248,16 @@ export type StdinBufferEventMap = {
 export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	private buffer: string = "";
 	private timeout: ReturnType<typeof setTimeout> | null = null;
+	private staleTimeout: ReturnType<typeof setTimeout> | null = null;
 	private readonly timeoutMs: number;
+	private readonly staleTimeoutMs: number;
 	private pasteMode: boolean = false;
 	private pasteBuffer: string = "";
 
 	constructor(options: StdinBufferOptions = {}) {
 		super();
 		this.timeoutMs = options.timeout ?? 10;
+		this.staleTimeoutMs = options.staleTimeout ?? 1000;
 	}
 
 	public process(data: string | Buffer): void {
@@ -258,6 +266,10 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			clearTimeout(this.timeout);
 			this.timeout = null;
 		}
+		if (this.staleTimeout) {
+			clearTimeout(this.staleTimeout);
+			this.staleTimeout = null;
+		}
 
 		// Handle high-byte conversion (for compatibility with parseKeypress)
 		// If buffer has single byte > 127, convert to ESC + (byte - 128)
@@ -365,6 +377,16 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		// sequences do not get emitted as literal text on timeout.
 		// A lone ESC is still flushed so an actual Escape keypress is not lost.
 		if (this.buffer.length > 1 && this.buffer.startsWith(ESC) && isCompleteSequence(this.buffer) === "incomplete") {
+			if (!this.staleTimeout) {
+				this.staleTimeout = setTimeout(() => {
+					this.staleTimeout = null;
+					if (this.buffer.length > 0 && this.buffer.startsWith(ESC) && isCompleteSequence(this.buffer) === "incomplete") {
+						const stale = this.buffer;
+						this.buffer = "";
+						this.emit("data", stale);
+					}
+				}, this.staleTimeoutMs);
+			}
 			return [];
 		}
 
@@ -378,6 +400,10 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			clearTimeout(this.timeout);
 			this.timeout = null;
 		}
+		if (this.staleTimeout) {
+			clearTimeout(this.staleTimeout);
+			this.staleTimeout = null;
+		}
 		this.buffer = "";
 		this.pasteMode = false;
 		this.pasteBuffer = "";