@gajae-code/tui 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-05-31
+
+### Changed
+
+- Refreshed TUI package metadata for the GJC 0.2.2 release.
+
+## [0.2.1] - 2026-05-30
+
+### Fixed
+
+- Made TUI terminal writes tolerate `EIO`/closed PTY failures by marking output unavailable, swallowing render/cursor cleanup write errors, and suppressing later render writes after detach.
+
 ## [0.2.0] - 2026-05-28
 
 ### Changed
@@ -833,4 +845,4 @@ Initial release under @gajae-code scope. See previous releases at [badlogic/pi-m
 
 ### Fixed
 
-- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))
+- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))

package/dist/types/autocomplete.d.ts

@@ -10,6 +10,11 @@ export interface SlashCommand {
     name: string;
     description?: string;
     argumentHint?: string;
+    /**
+     * Higher values surface first in autocomplete, ahead of fuzzy-score ordering.
+     * Use this to pin first-class commands (e.g. bundled GJC skills) to the top.
+     */
+    priority?: number;
     getArgumentCompletions?(argumentPrefix: string): Awaitable<AutocompleteItem[] | null>;
     /** Return inline hint text for the current argument state (shown as dim ghost text after cursor) */
     getInlineHint?(argumentText: string): string | null;

package/dist/types/terminal.d.ts

@@ -16,6 +16,7 @@ export interface Terminal {
      */
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     write(data: string): void;
+    get available(): boolean;
     get columns(): number;
     get rows(): number;
     get kittyProtocolActive(): boolean;
@@ -48,6 +49,7 @@ export declare class ProcessTerminal implements Terminal {
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;
     write(data: string): void;
+    get available(): boolean;
     get columns(): number;
     get rows(): number;
     moveBy(lines: number): void;

package/dist/types/tui.d.ts

@@ -154,6 +154,7 @@ export declare class TUI extends Container {
     hasOverlay(): boolean;
     invalidate(): void;
     start(): void;
+    get terminalAvailable(): boolean;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.2.0",
-		"@gajae-code/utils": "0.2.0",
+		"@gajae-code/natives": "0.2.2",
+		"@gajae-code/utils": "0.2.2",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/autocomplete.ts

@@ -162,6 +162,11 @@ export interface SlashCommand {
 	name: string;
 	description?: string;
 	argumentHint?: string;
+	/**
+	 * Higher values surface first in autocomplete, ahead of fuzzy-score ordering.
+	 * Use this to pin first-class commands (e.g. bundled GJC skills) to the top.
+	 */
+	priority?: number;
 	// Function to get argument completions for this command
 	// Returns null if no argument completion is available
 	getArgumentCompletions?(argumentPrefix: string): Awaitable<AutocompleteItem[] | null>;
@@ -283,15 +288,17 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 						const hint = "argumentHint" in cmd && cmd.argumentHint ? cmd.argumentHint : undefined;
 						const desc = cmd.description ?? "";
 						const fullDesc = hint ? (desc ? `${hint} — ${desc}` : hint) : desc;
+						const priority = "priority" in cmd && typeof cmd.priority === "number" ? cmd.priority : 0;
 						return {
 							value: name,
 							label: "name" in cmd ? cmd.name : cmd.label,
 							score: Math.max(nameScore, descScore),
+							priority,
 							...(fullDesc && { description: fullDesc }),
 						};
 					})
-					.sort((a, b) => b.score - a.score)
-					.map(({ score: _, ...rest }) => rest);
+					.sort((a, b) => b.priority - a.priority || b.score - a.score)
+					.map(({ score: _score, priority: _priority, ...rest }) => rest);
 
 				if (matches.length === 0) return null;
 
@@ -820,15 +827,17 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				const hint = "argumentHint" in cmd && cmd.argumentHint ? cmd.argumentHint : undefined;
 				const desc = cmd.description ?? "";
 				const fullDesc = hint ? (desc ? `${hint} — ${desc}` : hint) : desc;
+				const priority = "priority" in cmd && typeof cmd.priority === "number" ? cmd.priority : 0;
 				return {
 					value: name,
 					label: "name" in cmd ? cmd.name : cmd.label,
 					score: Math.max(nameScore, descScore),
+					priority,
 					...(fullDesc && { description: fullDesc }),
-				} as AutocompleteItem & { score: number };
+				} as AutocompleteItem & { score: number; priority: number };
 			})
-			.sort((a, b) => b.score - a.score)
-			.map(({ score: _, ...rest }) => rest);
+			.sort((a, b) => b.priority - a.priority || b.score - a.score)
+			.map(({ score: _score, priority: _priority, ...rest }) => rest);
 
 		if (matches.length === 0) return null;
 		return { items: matches, prefix: textBeforeCursor };

package/src/terminal.ts

@@ -1,6 +1,6 @@
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as fs from "node:fs";
-import { $env, logger } from "@gajae-code/utils";
+import { $env } from "@gajae-code/utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
 
@@ -67,6 +67,9 @@ export interface Terminal {
 	// Write output to terminal
 	write(data: string): void;
 
+	// Whether terminal output is still writable
+	get available(): boolean;
+
 	// Get terminal dimensions
 	get columns(): number;
 	get rows(): number;
@@ -121,7 +124,9 @@ export class ProcessTerminal implements Terminal {
 	#stdinDataHandler?: (data: string) => void;
 	#dead = false;
 	#writeLogPath = $env.PI_TUI_WRITE_LOG || "";
+	#detachLogPath = $env.PI_TUI_TERMINAL_DETACH_LOG || "";
 	#windowsVTInputRestore?: () => void;
+	#stdoutErrorHandler?: (err: Error) => void;
 	#appearanceCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
 	#appearance: TerminalAppearance | undefined;
 	#osc11Pending = false;
@@ -166,6 +171,10 @@ export class ProcessTerminal implements Terminal {
 
 		// Set up resize handler immediately
 		process.stdout.on("resize", this.#resizeHandler);
+		this.#stdoutErrorHandler = (err: Error) => {
+			this.#markUnavailable(err, "stdout-error");
+		};
+		process.stdout.on("error", this.#stdoutErrorHandler);
 
 		// Refresh terminal dimensions - they may be stale after suspend/resume
 		// (SIGWINCH is lost while process is stopped). Unix only.
@@ -611,6 +620,10 @@ export class ProcessTerminal implements Terminal {
 			process.stdout.removeListener("resize", this.#resizeHandler);
 			this.#resizeHandler = undefined;
 		}
+		if (this.#stdoutErrorHandler) {
+			process.stdout.removeListener("error", this.#stdoutErrorHandler);
+			this.#stdoutErrorHandler = undefined;
+		}
 
 		// Pause stdin to prevent any buffered input (e.g., Ctrl+D) from being
 		// re-interpreted after raw mode is disabled. This fixes a race condition
@@ -639,13 +652,59 @@ export class ProcessTerminal implements Terminal {
 		// Skip control sequences when stdout isn't a TTY (piped output, tests, log
 		// files). They serve no purpose there and would surface as visible noise.
 		if (!process.stdout.isTTY) return;
+		if (
+			!process.stdout.writable ||
+			process.stdout.destroyed ||
+			process.stdout.closed ||
+			process.stdout.writableEnded
+		) {
+			this.#markUnavailable(undefined, "stdout-closed");
+			return;
+		}
 		try {
 			process.stdout.write(data);
 		} catch (err) {
-			// Any write failure means terminal is dead - no recovery possible
-			this.#dead = true;
-			logger.warn("terminal is dead - no recovery possible", { error: err, data });
+			this.#markUnavailable(err, "write");
+		}
+	}
+
+	#markUnavailable(err: unknown, operation: string): void {
+		if (this.#dead) return;
+		this.#dead = true;
+		this.#clearProgressTimer();
+		this.#stopOsc11Poll();
+		if (this.#mode2031DebounceTimer) {
+			clearTimeout(this.#mode2031DebounceTimer);
+			this.#mode2031DebounceTimer = undefined;
 		}
+		if (this.#modifyOtherKeysTimeout) {
+			clearTimeout(this.#modifyOtherKeysTimeout);
+			this.#modifyOtherKeysTimeout = undefined;
+		}
+		this.#appendDetachDebugEvent(operation, err);
+	}
+
+	#appendDetachDebugEvent(operation: string, err: unknown): void {
+		if (!this.#detachLogPath) return;
+		const error = err instanceof Error ? err : undefined;
+		const code =
+			typeof (err as { code?: unknown } | undefined)?.code === "string" ? (err as { code: string }).code : undefined;
+		const line = JSON.stringify({
+			at: new Date().toISOString(),
+			operation,
+			code,
+			name: error?.name,
+			message: error?.message,
+		});
+		try {
+			fs.appendFileSync(this.#detachLogPath, `${line}\n`, { encoding: "utf8" });
+		} catch {
+			// Ignore debug logging errors; the terminal is already unavailable.
+		}
+	}
+
+	get available(): boolean {
+		return !this.#dead;
 	}
 
 	get columns(): number {

package/src/tui.ts

@@ -256,6 +256,7 @@ export class TUI extends Container {
 	#maxLinesRendered = 0; // Line count from last render, used for viewport calculation
 	#fullRedrawCount = 0;
 	#stopped = false;
+	#terminalUnavailable = false;
 
 	// Overlay stack for modal components rendered on top of base content
 	overlayStack: {
@@ -285,7 +286,7 @@ export class TUI extends Container {
 		if (this.#showHardwareCursor === enabled) return;
 		this.#showHardwareCursor = enabled;
 		if (!enabled) {
-			this.terminal.hideCursor();
+			this.#hideCursor();
 		}
 		this.requestRender();
 	}
@@ -328,7 +329,7 @@ export class TUI extends Container {
 		if (this.#isOverlayVisible(entry)) {
 			this.setFocus(component);
 		}
-		this.terminal.hideCursor();
+		this.#hideCursor();
 		this.requestRender();
 
 		// Return handle for controlling this overlay
@@ -342,7 +343,7 @@ export class TUI extends Container {
 						const topVisible = this.#getTopmostVisibleOverlay();
 						this.setFocus(topVisible?.component ?? entry.preFocus);
 					}
-					if (this.overlayStack.length === 0) this.terminal.hideCursor();
+					if (this.overlayStack.length === 0) this.#hideCursor();
 					this.requestRender();
 				}
 			},
@@ -375,7 +376,7 @@ export class TUI extends Container {
 		// Find topmost visible overlay, or fall back to preFocus
 		const topVisible = this.#getTopmostVisibleOverlay();
 		this.setFocus(topVisible?.component ?? overlay.preFocus);
-		if (this.overlayStack.length === 0) this.terminal.hideCursor();
+		if (this.overlayStack.length === 0) this.#hideCursor();
 		this.requestRender();
 	}
 
@@ -410,16 +411,62 @@ export class TUI extends Container {
 
 	start(): void {
 		this.#stopped = false;
+		this.#terminalUnavailable = false;
 		this.terminal.start(
 			data => this.#handleInput(data),
 			() => this.requestRender(),
 		);
-		this.terminal.hideCursor();
+		this.#hideCursor();
 		this.#querySixelSupport();
 		this.#queryCellSize();
 		this.requestRender(true);
 	}
 
+	get terminalAvailable(): boolean {
+		return !this.#terminalUnavailable && this.terminal.available;
+	}
+
+	#markTerminalUnavailable(): void {
+		this.#terminalUnavailable = true;
+		this.#stopped = true;
+		this.#renderRequested = false;
+		if (this.#renderTimer) {
+			clearTimeout(this.#renderTimer);
+			this.#renderTimer = undefined;
+		}
+		this.#clearSixelProbeState();
+	}
+
+	#writeTerminal(data: string): boolean {
+		return this.#guardTerminalOperation(() => this.terminal.write(data));
+	}
+
+	#hideCursor(): boolean {
+		return this.#guardTerminalOperation(() => this.terminal.hideCursor());
+	}
+
+	#showCursor(): boolean {
+		return this.#guardTerminalOperation(() => this.terminal.showCursor());
+	}
+
+	#guardTerminalOperation(operation: () => void): boolean {
+		if (!this.terminalAvailable) {
+			this.#markTerminalUnavailable();
+			return false;
+		}
+		try {
+			operation();
+		} catch {
+			this.#markTerminalUnavailable();
+			return false;
+		}
+		if (!this.terminal.available) {
+			this.#markTerminalUnavailable();
+			return false;
+		}
+		return true;
+	}
+
 	addInputListener(listener: InputListener): () => void {
 		this.#inputListeners.add(listener);
 		return () => {
@@ -441,8 +488,8 @@ export class TUI extends Container {
 		this.#sixelProbePendingDa = true;
 		this.#sixelProbePendingGraphics = true;
 		this.#sixelProbeUnsubscribe = this.addInputListener(data => this.#handleSixelProbeInput(data));
-		this.terminal.write("\x1b[c");
-		this.terminal.write("\x1b[?2;1;0S");
+		if (!this.#writeTerminal("\x1b[c")) return;
+		if (!this.#writeTerminal("\x1b[?2;1;0S")) return;
 		this.#sixelProbeTimeout = setTimeout(() => {
 			this.#finishSixelProbe(false);
 		}, 250);
@@ -563,7 +610,7 @@ export class TUI extends Container {
 		}
 		// Query terminal for cell size in pixels: CSI 16 t
 		// Response format: CSI 6 ; height ; width t
-		this.terminal.write("\x1b[16t");
+		this.#writeTerminal("\x1b[16t");
 	}
 
 	stop(): void {
@@ -578,18 +625,26 @@ export class TUI extends Container {
 			const targetRow = this.#previousLines.length; // Line after the last content
 			const lineDiff = targetRow - this.#hardwareCursorRow;
 			if (lineDiff > 0) {
-				this.terminal.write(`\x1b[${lineDiff}B`);
+				this.#writeTerminal(`\x1b[${lineDiff}B`);
 			} else if (lineDiff < 0) {
-				this.terminal.write(`\x1b[${-lineDiff}A`);
+				this.#writeTerminal(`\x1b[${-lineDiff}A`);
 			}
-			this.terminal.write("\r\n");
+			this.#writeTerminal("\r\n");
 		}
 
-		this.terminal.showCursor();
-		this.terminal.stop();
+		this.#showCursor();
+		try {
+			this.terminal.stop();
+		} catch {
+			this.#markTerminalUnavailable();
+		}
 	}
 
 	requestRender(force = false): void {
+		if (!this.terminalAvailable) {
+			this.#markTerminalUnavailable();
+			return;
+		}
 		if (force) {
 			this.#previousLines = [];
 			this.#previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
@@ -1040,7 +1095,7 @@ export class TUI extends Container {
 	}
 
 	#doRender(): void {
-		if (this.#stopped) return;
+		if (this.#stopped || !this.terminalAvailable) return;
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
 		let viewportTop = Math.max(0, this.#maxLinesRendered - height);
@@ -1091,7 +1146,7 @@ export class TUI extends Container {
 			this.#hardwareCursorRow = toRow;
 			buffer += seq;
 			buffer += "\x1b[?2026l"; // End synchronized output
-			this.terminal.write(buffer);
+			if (!this.#writeTerminal(buffer)) return;
 			// Reset max lines when clearing, otherwise track growth
 			if (clear) {
 				this.#maxLinesRendered = newLines.length;
@@ -1140,7 +1195,7 @@ export class TUI extends Container {
 			this.#hardwareCursorRow = cursorToRow;
 			buffer += cursorSeq;
 			buffer += "\x1b[?2026l";
-			this.terminal.write(buffer);
+			if (!this.#writeTerminal(buffer)) return;
 
 			if ($flag("PI_DEBUG_REDRAW")) {
 				const logPath = getDebugLogPath();
@@ -1274,7 +1329,7 @@ export class TUI extends Container {
 				this.#hardwareCursorRow = toRow;
 				buffer += seq;
 				buffer += "\x1b[?2026l";
-				this.terminal.write(buffer);
+				if (!this.#writeTerminal(buffer)) return;
 			}
 			this.#previousLines = newLines;
 			this.#previousWidth = width;
@@ -1415,7 +1470,7 @@ export class TUI extends Container {
 		}
 
 		// Write entire buffer at once
-		this.terminal.write(buffer);
+		if (!this.#writeTerminal(buffer)) return;
 
 		// Track cursor position for next render.
 		// cursorRow tracks end of content (for viewport calculation).
@@ -1471,11 +1526,11 @@ export class TUI extends Container {
 	 */
 	#writeCursorPosition(cursorPos: { row: number; col: number } | null, totalLines: number): void {
 		if (!cursorPos || totalLines <= 0) {
-			this.terminal.hideCursor();
+			this.#hideCursor();
 			return;
 		}
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
 		this.#hardwareCursorRow = toRow;
-		this.terminal.write(`\x1b[?2026h${seq}\x1b[?2026l`);
+		this.#writeTerminal(`\x1b[?2026h${seq}\x1b[?2026l`);
 	}
 }