@gajae-code/tui 0.7.7 → 0.7.9

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.7.9] - 2026-07-01
+
+### Fixed
+
+- Reverted the composer Enter/Shift+Enter handling to the 0.7.8 behavior. A recent restructure (#1298 and follow-ups) changed how plain Enter, Ctrl+Enter, and bare-LF Enter were routed and regressed prompt submission for some terminals; the submit/newline branches are now restored to their 0.7.8 form so Enter submits and Shift+Enter inserts a newline.
+
+## [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).
+- `truncateToWidth` now coerces its required napi `text` argument to a safe string, mirroring the existing nullish guards for `maxWidth`/`ellipsis`/`pad`. Renderers that passed an optional/possibly-undefined field no longer crash with a napi String conversion / `undefined is not an object` error (#1290).
+
+- 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, descriptionRows?: number);
     /** 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.9",
 	"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.9",
+		"@gajae-code/utils": "0.7.9",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/settings-list.ts

@@ -32,6 +32,8 @@ export class SettingsList implements Component {
 	#maxVisible: number;
 	#onChange: (id: string, newValue: string) => void;
 	#onCancel: () => void;
+	#onSelectionChange?: (item: SettingItem | undefined) => void;
+	#descriptionRows: number;
 
 	// Submenu state
 	#submenuComponent: Component | null = null;
@@ -43,12 +45,17 @@ export class SettingsList implements Component {
 		theme: SettingsListTheme,
 		onChange: (id: string, newValue: string) => void,
 		onCancel: () => void,
+		onSelectionChange?: (item: SettingItem | undefined) => void,
+		descriptionRows = 0,
 	) {
 		this.#items = items;
 		this.#maxVisible = maxVisible;
 		this.#theme = theme;
 		this.#onChange = onChange;
 		this.#onCancel = onCancel;
+		this.#onSelectionChange = onSelectionChange;
+		this.#descriptionRows = Math.max(0, descriptionRows);
+		this.#notifySelectionChange();
 	}
 
 	/** Update an item's currentValue */
@@ -73,12 +80,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) {
@@ -138,9 +150,18 @@ export class SettingsList implements Component {
 			lines.push(this.#theme.hint(truncateToWidth(scrollText, width - 2, Ellipsis.Omit)));
 		}
 
-		// Add description for selected item
+		// Add description for selected item. Some hosts reserve a fixed
+		// description area so keyboard navigation does not resize the TUI when
+		// moving between described and undescribed rows.
 		const selectedItem = this.#items[this.#selectedIndex];
-		if (selectedItem?.description) {
+		if (this.#descriptionRows > 0) {
+			lines.push("");
+			const wrappedDesc = selectedItem?.description ? wrapTextWithAnsi(selectedItem.description, width - 4) : [];
+			for (let i = 0; i < this.#descriptionRows; i++) {
+				const line = wrappedDesc[i] ?? "";
+				lines.push(line ? this.#theme.description(`  ${line}`) : "");
+			}
+		} else if (selectedItem?.description) {
 			lines.push("");
 			const wrappedDesc = wrapTextWithAnsi(selectedItem.description, width - 4);
 			for (const line of wrappedDesc) {
@@ -167,8 +188,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 +229,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;

package/src/utils.ts

@@ -45,14 +45,18 @@ export function truncateToWidth(
 	// Guard nullish napi inputs: napi-rs 3 on the Windows prebuilt rejects
 	// `null` for `Option<u8>` (Ellipsis) / `Option<bool>` (pad) (issue #848),
 	// and `maxWidth` is a required `u32` that throws on `null`/`undefined`
-	// everywhere. Pass concrete defaults that mirror the Rust `unwrap_or`s.
+	// everywhere. The `text` arg is a required `String` that likewise throws on
+	// `null`/`undefined` on every platform, which crashed renderers that passed
+	// an optional/possibly-undefined field. Pass concrete defaults that mirror
+	// the Rust `unwrap_or`s.
+	const safeText = typeof text === "string" ? text : String(text ?? "");
 	const safeWidth = Number.isFinite(maxWidth) ? Math.max(0, Math.trunc(maxWidth)) : 0;
 	let resolvedEllipsis: Ellipsis | null | undefined | string = ellipsisKind;
 	if (typeof resolvedEllipsis === "string") {
 		resolvedEllipsis = resolvedEllipsis === "" ? Ellipsis.Omit : Ellipsis.Unicode;
 	}
 	return nativeTruncateToWidth(
-		text,
+		safeText,
 		safeWidth,
 		resolvedEllipsis ?? Ellipsis.Unicode,
 		pad ?? false,