@gajae-code/tui 0.7.7 → 0.7.8

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.7.8] - 2026-06-30
+
+### Fixed
+
+- The render loop now isolates a component whose `render()` throws: the failure is logged once and replaced with a `[render error: <Name>]` fallback line instead of escaping the frame and tripping the process-level fail-fast `uncaughtException` exit. Previously any unguarded renderer fault (e.g. a tool renderer fed an undefined field) crashed the whole app on whatever triggered the next frame — a keystroke, resize, or command such as `/background` (#1291).
+
+- Resolved terminal dimensions from the live TTY window size before stream defaults so wide Windows Terminal/PowerShell sessions render against the actual viewport width (#1239).
+
 ## [0.7.4] - 2026-06-27
 
 ### Fixed

package/dist/types/components/settings-list.d.ts

@@ -22,7 +22,7 @@ export interface SettingsListTheme {
 }
 export declare class SettingsList implements Component {
     #private;
-    constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void);
+    constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void, onSelectionChange?: (item: SettingItem | undefined) => void);
     /** Update an item's currentValue */
     updateValue(id: string, newValue: string): void;
     /**

package/dist/types/terminal.d.ts

@@ -50,6 +50,13 @@ export interface Terminal {
     /** The last detected terminal appearance, or undefined if not yet known. */
     get appearance(): TerminalAppearance | undefined;
 }
+interface TerminalSizeStream {
+    columns?: number;
+    rows?: number;
+    getWindowSize?: () => [number, number] | number[];
+}
+export declare function resolveTerminalColumns(stream?: TerminalSizeStream, envColumns?: string | undefined): number;
+export declare function resolveTerminalRows(stream?: TerminalSizeStream, envRows?: string | undefined): number;
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -74,3 +81,4 @@ export declare class ProcessTerminal implements Terminal {
     setTitle(title: string): void;
     setProgress(active: boolean): void;
 }
+export {};

package/package.json

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

package/src/components/settings-list.ts

@@ -32,6 +32,7 @@ export class SettingsList implements Component {
 	#maxVisible: number;
 	#onChange: (id: string, newValue: string) => void;
 	#onCancel: () => void;
+	#onSelectionChange?: (item: SettingItem | undefined) => void;
 
 	// Submenu state
 	#submenuComponent: Component | null = null;
@@ -43,12 +44,15 @@ export class SettingsList implements Component {
 		theme: SettingsListTheme,
 		onChange: (id: string, newValue: string) => void,
 		onCancel: () => void,
+		onSelectionChange?: (item: SettingItem | undefined) => void,
 	) {
 		this.#items = items;
 		this.#maxVisible = maxVisible;
 		this.#theme = theme;
 		this.#onChange = onChange;
 		this.#onCancel = onCancel;
+		this.#onSelectionChange = onSelectionChange;
+		this.#notifySelectionChange();
 	}
 
 	/** Update an item's currentValue */
@@ -73,12 +77,17 @@ export class SettingsList implements Component {
 		} else if (this.#selectedIndex >= this.#items.length) {
 			this.#selectedIndex = this.#items.length - 1;
 		}
+		this.#notifySelectionChange();
 	}
 
 	invalidate(): void {
 		this.#submenuComponent?.invalidate?.();
 	}
 
+	#notifySelectionChange(): void {
+		this.#onSelectionChange?.(this.#items[this.#selectedIndex]);
+	}
+
 	render(width: number): string[] {
 		// If submenu is active, render it instead
 		if (this.#submenuComponent) {
@@ -167,8 +176,10 @@ export class SettingsList implements Component {
 		const kb = getKeybindings();
 		if (kb.matches(data, "tui.select.up")) {
 			this.#selectedIndex = this.#selectedIndex === 0 ? this.#items.length - 1 : this.#selectedIndex - 1;
+			this.#notifySelectionChange();
 		} else if (kb.matches(data, "tui.select.down")) {
 			this.#selectedIndex = this.#selectedIndex === this.#items.length - 1 ? 0 : this.#selectedIndex + 1;
+			this.#notifySelectionChange();
 		} else if (kb.matches(data, "tui.select.confirm") || data === " " || data === "\n") {
 			this.#activateItem();
 		} else if (kb.matches(data, "tui.select.cancel")) {
@@ -206,6 +217,7 @@ export class SettingsList implements Component {
 		if (this.#submenuItemIndex !== null) {
 			this.#selectedIndex = this.#submenuItemIndex;
 			this.#submenuItemIndex = null;
+			this.#notifySelectionChange();
 		}
 	}
 }

package/src/terminal.ts

@@ -124,6 +124,46 @@ export interface Terminal {
 	get appearance(): TerminalAppearance | undefined;
 }
 
+interface TerminalSizeStream {
+	columns?: number;
+	rows?: number;
+	getWindowSize?: () => [number, number] | number[];
+}
+
+function positiveDimension(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	const dimension = Math.trunc(value);
+	return dimension > 0 ? dimension : undefined;
+}
+
+export function resolveTerminalColumns(
+	stream: TerminalSizeStream = process.stdout,
+	envColumns: string | undefined = Bun.env.COLUMNS,
+): number {
+	try {
+		const windowSize = stream.getWindowSize?.();
+		const liveColumns = positiveDimension(windowSize?.[0]);
+		if (liveColumns !== undefined) return liveColumns;
+	} catch {
+		// Fall back below when the stream cannot report a live TTY size.
+	}
+	return positiveDimension(stream.columns) ?? positiveDimension(Number(envColumns)) ?? 80;
+}
+
+export function resolveTerminalRows(
+	stream: TerminalSizeStream = process.stdout,
+	envRows: string | undefined = Bun.env.LINES,
+): number {
+	try {
+		const windowSize = stream.getWindowSize?.();
+		const liveRows = positiveDimension(windowSize?.[1]);
+		if (liveRows !== undefined) return liveRows;
+	} catch {
+		// Fall back below when the stream cannot report a live TTY size.
+	}
+	return positiveDimension(stream.rows) ?? positiveDimension(Number(envRows)) ?? 24;
+}
+
 function isWindowsSubsystemForLinux(): boolean {
 	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
 }
@@ -740,11 +780,11 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	get columns(): number {
-		return process.stdout.columns || Number(Bun.env.COLUMNS) || 80;
+		return resolveTerminalColumns();
 	}
 
 	get rows(): number {
-		return process.stdout.rows || Number(Bun.env.LINES) || 24;
+		return resolveTerminalRows();
 	}
 
 	moveBy(lines: number): void {

package/src/tui.ts

@@ -4,7 +4,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
-import { $flag, getDebugLogPath } from "@gajae-code/utils";
+import { $flag, getDebugLogPath, logger } from "@gajae-code/utils";
 import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
@@ -257,7 +257,7 @@ export class Container implements Component {
 		width = Math.max(1, width);
 		const lines: string[] = [];
 		for (const child of this.children) {
-			const childLines = child.render(width);
+			const childLines = safeRenderComponent(child, width, "container-child");
 			for (let i = 0; i < childLines.length; i++) {
 				lines.push(childLines[i]);
 			}
@@ -266,6 +266,40 @@ export class Container implements Component {
 	}
 }
 
+const MAX_REPORTED_RENDER_ERRORS = 200;
+const reportedRenderErrors = new Set<string>();
+
+/**
+ * Render a component's lines without letting a thrown error escape the frame.
+ *
+ * The TUI render loop ({@link TUI.#doRender}) runs inside a `nextTick`/`setTimeout`
+ * with no try/catch, and the process installs a fail-fast `uncaughtException`
+ * handler that exits. So a single component whose `render()` throws (e.g. a tool
+ * renderer fed an optional/undefined field) used to take down the whole app —
+ * fatal on whatever happened to trigger the frame (a keystroke, resize, or a
+ * command such as `/background`). Isolate the failure: log it once, emit a
+ * visible fallback line, and keep rendering the rest of the tree.
+ */
+function safeRenderComponent(component: Component, width: number, where: string): string[] {
+	try {
+		return component.render(width);
+	} catch (err) {
+		const name = component?.constructor?.name ?? "Component";
+		const key = `${where}:${name}:${err instanceof Error ? err.message : String(err)}`;
+		if (!reportedRenderErrors.has(key)) {
+			if (reportedRenderErrors.size >= MAX_REPORTED_RENDER_ERRORS) reportedRenderErrors.clear();
+			reportedRenderErrors.add(key);
+			logger.error("Component render failed; emitting fallback line", {
+				where,
+				component: name,
+				error: err instanceof Error ? err.message : String(err),
+				stack: err instanceof Error ? err.stack : undefined,
+			});
+		}
+		return [`[render error: ${name}]`];
+	}
+}
+
 type LineNormalizationCacheEntry = {
 	normalized: string;
 	terminated: string;
@@ -1071,7 +1105,7 @@ export class TUI extends Container {
 			const { width, maxHeight } = this.#resolveOverlayLayout(options, 0, termWidth, termHeight);
 
 			// Render component at calculated width
-			let overlayLines = component.render(width);
+			let overlayLines = safeRenderComponent(component, width, "overlay");
 
 			// Apply maxHeight if specified
 			if (maxHeight !== undefined && overlayLines.length > maxHeight) {
@@ -1302,7 +1336,7 @@ export class TUI extends Container {
 
 		let pinnedLineCount = 0;
 		for (let i = pinnedStart; i < this.children.length; i++) {
-			pinnedLineCount += this.children[i].render(this.terminal.columns).length;
+			pinnedLineCount += safeRenderComponent(this.children[i], this.terminal.columns, "pinned").length;
 		}
 
 		const blankRows = height - lines.length;