@gajae-code/tui 0.7.10 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-07-04
+
+### Fixed
+
+- Added manual transcript viewport paging support so applications can repaint older terminal output with PageUp/PageDown without reusing editor history navigation.
+
+- Empty select/settings lists now still honor cancel while preserving populated-list keybinding precedence, and settings lists keep selection indices clamped when items disappear or submenus close after list shrinkage.
+
+- Fixed Windows Hangul/CJK IME composition breaking the queue-message shortcut (Alt+Enter/Alt+Q): the app no longer enables the xterm `modifyOtherKeys` fallback on win32, where Windows Terminal/conhost do not support the Kitty keyboard protocol anyway. `modifyOtherKeys` made modified-key chords bypass the IME commit, so a syllable still being composed was dropped and the queue action fired on empty text unless the user typed a trailing space first. Legacy encodings still deliver Alt+Enter and the newline chords; opt back into the enhancement with `GJC_TUI_KEYBOARD_PROTOCOL`.
+
+## [0.7.11] - 2026-07-03
+
+### Fixed
+
+- Kept the terminal stdout error handler armed briefly after TUI shutdown so late `EIO`/closed-PTY errors from SSH or Windows Terminal detach do not crash tmux-backed GJC panes.
+
 ## [0.7.9] - 2026-07-01
 
 ### Fixed

package/dist/types/components/editor.d.ts

@@ -39,6 +39,11 @@ export declare class Editor implements Component, Focusable {
     onChange?: (text: string) => void;
     onAutocompleteCancel?: () => void;
     onTabDeclined?: (text: string) => void;
+    /**
+     * Called before Tab opens/applies autocomplete. Return true to consume Tab
+     * for app-level behavior (for example, queueing a draft while a turn runs).
+     */
+    onTab?: (text: string) => boolean | undefined;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
     setAutocompleteProvider(provider: AutocompleteProvider): void;

package/dist/types/tui.d.ts

@@ -157,6 +157,8 @@ export declare class TUI extends Container {
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
     setBottomPinnedComponent(component: Component | null): void;
+    scrollViewportPages(direction: -1 | 1): boolean;
+    followLiveViewport(): boolean;
     /**
      * Show an overlay component with configurable positioning and sizing.
      * Returns a handle to control the overlay's visibility.
@@ -172,6 +174,19 @@ export declare class TUI extends Container {
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;
+    /**
+     * Multiplexer-aware resize render request.
+     *
+     * A forced full redraw (`requestRender(true)`) resets `#previousWidth`/`#previousHeight`
+     * to -1, which makes `#doRender` treat the frame as a width change and fall into the
+     * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
+     * `3J` escape (users navigate scrollback history), so replaying every transcript line
+     * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
+     * high speed" resize storm. Here we keep force off in multiplexers so `#doRender`'s
+     * height-change branch takes the viewport-only `multiplexerViewportRepaint` path instead.
+     * Set `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy forced redraw.
+     */
+    requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;
     getLineRenderCacheStats(): {
         normalizationSize: number;

package/package.json

@@ -1,9 +1,9 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.7.10",
+	"version": "0.8.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
-	"homepage": "https://gaebal-gajae.dev",
+	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
 	"contributors": [
 		"Mario Zechner"
@@ -11,11 +11,11 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/gajae-ai/gajae-code.git",
+		"url": "git+https://github.com/Yeachan-Heo/gajae-code.git",
 		"directory": "packages/tui"
 	},
 	"bugs": {
-		"url": "https://github.com/gajae-ai/gajae-code/issues"
+		"url": "https://github.com/Yeachan-Heo/gajae-code/issues"
 	},
 	"keywords": [
 		"tui",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.7.10",
-		"@gajae-code/utils": "0.7.10",
+		"@gajae-code/natives": "0.8.0",
+		"@gajae-code/utils": "0.8.0",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/editor.ts

@@ -450,6 +450,11 @@ export class Editor implements Component, Focusable {
 	onChange?: (text: string) => void;
 	onAutocompleteCancel?: () => void;
 	onTabDeclined?: (text: string) => void;
+	/**
+	 * Called before Tab opens/applies autocomplete. Return true to consume Tab
+	 * for app-level behavior (for example, queueing a draft while a turn runs).
+	 */
+	onTab?: (text: string) => boolean | undefined;
 	disableSubmit: boolean = false;
 
 	// Custom top border (for status line integration)
@@ -1076,6 +1081,10 @@ export class Editor implements Component, Focusable {
 			return;
 		}
 
+		if (kb.matches(data, "tui.input.tab") && this.onTab?.(this.getText())) {
+			return;
+		}
+
 		// Handle autocomplete special keys first (but don't block other input)
 		if (this.#autocompleteState && this.#autocompleteList) {
 			// Escape - cancel autocomplete
@@ -1505,10 +1514,34 @@ export class Editor implements Component, Focusable {
 					}
 
 					if (hasCursorInChunk) {
+						let displayChunkText = chunk.text;
+						let displayCursorPos = adjustedCursorPos;
+						if (displayCursorPos > displayChunkText.length) {
+							let hiddenWhitespaceWidth = displayCursorPos - displayChunkText.length;
+							const displayChunkWidth = visibleWidth(displayChunkText);
+							if (displayChunkWidth + hiddenWhitespaceWidth <= contentWidth) {
+								displayChunkText += padding(hiddenWhitespaceWidth);
+							} else {
+								layoutLines.push({
+									text: displayChunkText,
+									hasCursor: false,
+								});
+								hiddenWhitespaceWidth -= Math.max(0, contentWidth - displayChunkWidth);
+								while (hiddenWhitespaceWidth > contentWidth) {
+									layoutLines.push({
+										text: padding(contentWidth),
+										hasCursor: false,
+									});
+									hiddenWhitespaceWidth -= contentWidth;
+								}
+								displayChunkText = padding(hiddenWhitespaceWidth);
+								displayCursorPos = hiddenWhitespaceWidth;
+							}
+						}
 						layoutLines.push({
-							text: chunk.text,
+							text: displayChunkText,
 							hasCursor: true,
-							cursorPos: adjustedCursorPos,
+							cursorPos: displayCursorPos,
 						});
 					} else {
 						layoutLines.push({

package/src/components/input.ts

@@ -58,7 +58,8 @@ export class Input implements Component, Focusable {
 	setValue(value: string): void {
 		const normalized = value.normalize("NFC");
 		this.#value = normalized;
-		this.#cursor = Math.min(this.#cursor, normalized.length);
+		this.#cursor = normalized.length;
+		this.#lastAction = null;
 	}
 
 	handleInput(data: string): void {

package/src/components/select-list.ts

@@ -117,8 +117,15 @@ export class SelectList implements Component {
 	}
 
 	handleInput(keyData: string): void {
-		if (this.#filteredItems.length === 0) return;
 		const kb = getKeybindings();
+		if (this.#filteredItems.length === 0) {
+			if (kb.matches(keyData, "tui.select.cancel")) {
+				if (this.onCancel) {
+					this.onCancel();
+				}
+			}
+			return;
+		}
 		// Up arrow - wrap to bottom when at top
 		if (kb.matches(keyData, "tui.select.up")) {
 			this.#selectedIndex = this.#selectedIndex === 0 ? this.#filteredItems.length - 1 : this.#selectedIndex - 1;

package/src/components/settings-list.ts

@@ -58,6 +58,14 @@ export class SettingsList implements Component {
 		this.#notifySelectionChange();
 	}
 
+	#clampSelectedIndex(): void {
+		if (this.#items.length === 0) {
+			this.#selectedIndex = 0;
+			return;
+		}
+		this.#selectedIndex = Math.max(0, Math.min(this.#selectedIndex, this.#items.length - 1));
+	}
+
 	/** Update an item's currentValue */
 	updateValue(id: string, newValue: string): void {
 		const item = this.#items.find(i => i.id === id);
@@ -75,11 +83,7 @@ export class SettingsList implements Component {
 	 */
 	setItems(items: SettingItem[]): void {
 		this.#items = items;
-		if (this.#items.length === 0) {
-			this.#selectedIndex = 0;
-		} else if (this.#selectedIndex >= this.#items.length) {
-			this.#selectedIndex = this.#items.length - 1;
-		}
+		this.#clampSelectedIndex();
 		this.#notifySelectionChange();
 	}
 
@@ -186,6 +190,13 @@ export class SettingsList implements Component {
 
 		// Main list input handling
 		const kb = getKeybindings();
+		if (this.#items.length === 0) {
+			if (kb.matches(data, "tui.select.cancel")) {
+				this.#onCancel();
+			}
+			return;
+		}
+
 		if (kb.matches(data, "tui.select.up")) {
 			this.#selectedIndex = this.#selectedIndex === 0 ? this.#items.length - 1 : this.#selectedIndex - 1;
 			this.#notifySelectionChange();
@@ -228,6 +239,7 @@ export class SettingsList implements Component {
 		// Restore selection to the item that opened the submenu
 		if (this.#submenuItemIndex !== null) {
 			this.#selectedIndex = this.#submenuItemIndex;
+			this.#clampSelectedIndex();
 			this.#submenuItemIndex = null;
 			this.#notifySelectionChange();
 		}

package/src/terminal.ts

@@ -167,6 +167,7 @@ export function resolveTerminalRows(
 function isWindowsSubsystemForLinux(): boolean {
 	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
 }
+const STDOUT_ERROR_HANDLER_GRACE_MS = 250;
 
 /**
  * Real terminal using process.stdin/stdout
@@ -185,6 +186,7 @@ export class ProcessTerminal implements Terminal {
 	#detachLogPath = $env.PI_TUI_TERMINAL_DETACH_LOG || "";
 	#windowsVTInputRestore?: () => void;
 	#stdoutErrorHandler?: (err: Error) => void;
+	#stdoutErrorHandlerCleanupTimer?: Timer;
 	#appearanceCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
 	#appearance: TerminalAppearance | undefined;
 	#osc11Pending = false;
@@ -233,10 +235,16 @@ 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);
+		if (this.#stdoutErrorHandlerCleanupTimer) {
+			clearTimeout(this.#stdoutErrorHandlerCleanupTimer);
+			this.#stdoutErrorHandlerCleanupTimer = undefined;
+		}
+		if (!this.#stdoutErrorHandler) {
+			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.
@@ -578,6 +586,20 @@ export class ProcessTerminal implements Terminal {
 			return;
 		}
 		this.#safeWrite("\x1b[?u");
+		// Windows Terminal and conhost do not implement the Kitty keyboard
+		// protocol, so the query above never activates it there. They do honor the
+		// modifyOtherKeys fallback below — but that mode breaks Windows CJK/Hangul
+		// IME composition: Alt+Enter (and other chords) bypass the IME commit, so
+		// the syllable still being composed is never delivered to the app and the
+		// action fires on empty text (e.g. queue-message no-ops unless the user
+		// types a trailing space to force a commit first). Skip the fallback on
+		// win32; legacy encodings still deliver Alt+Enter (ESC CR) and the newline
+		// chords, and IME composition works again. Opt back in with
+		// GJC_TUI_KEYBOARD_PROTOCOL=0 disabling all enhancement, or force-enable
+		// elsewhere if a Kitty-capable Windows terminal appears.
+		if (process.platform === "win32") {
+			return;
+		}
 		this.#modifyOtherKeysTimeout = setTimeout(() => {
 			this.#modifyOtherKeysTimeout = undefined;
 			if (this.#kittyProtocolActive || this.#modifyOtherKeysActive) {
@@ -692,10 +714,7 @@ 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;
-		}
+		this.#scheduleStdoutErrorHandlerCleanup();
 
 		// 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
@@ -708,6 +727,23 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
+	#scheduleStdoutErrorHandlerCleanup(): void {
+		if (!this.#stdoutErrorHandler) return;
+		if (this.#stdoutErrorHandlerCleanupTimer) clearTimeout(this.#stdoutErrorHandlerCleanupTimer);
+		// Terminal restore writes above can fail asynchronously after stop() returns
+		// when an SSH/Windows Terminal PTY disappears. Keep the stdout error listener
+		// armed briefly so late EIO/EPIPE events mark the terminal unavailable instead
+		// of surfacing as uncaught exceptions that kill the tmux pane.
+		this.#stdoutErrorHandlerCleanupTimer = setTimeout(() => {
+			if (this.#stdoutErrorHandler) {
+				process.stdout.removeListener("error", this.#stdoutErrorHandler);
+				this.#stdoutErrorHandler = undefined;
+			}
+			this.#stdoutErrorHandlerCleanupTimer = undefined;
+		}, STDOUT_ERROR_HANDLER_GRACE_MS);
+		this.#stdoutErrorHandlerCleanupTimer.unref?.();
+	}
+
 	write(data: string): void {
 		this.#safeWrite(data);
 		if (this.#writeLogPath) {

package/src/tui.ts

@@ -341,6 +341,8 @@ export class TUI extends Container {
 	#cursorRow = 0; // Logical cursor row (end of rendered content)
 	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
 	#viewportTopRow = 0; // Content row currently mapped to screen row 0
+	#manualViewportTop: number | undefined;
+	#lastCursorPosition: { row: number; col: number } | null = null;
 	#sixelProbePendingDa = false;
 	#sixelProbePendingGraphics = false;
 	#sixelProbeBuffer = "";
@@ -427,6 +429,47 @@ export class TUI extends Container {
 		this.#bottomPinnedComponent = component;
 		this.requestRender();
 	}
+	scrollViewportPages(direction: -1 | 1): boolean {
+		const height = this.terminal.rows;
+		const width = this.terminal.columns;
+		if (height <= 0 || width <= 0 || this.#previousLines.length === 0) return false;
+		const maxViewportTop = Math.max(0, this.#previousLines.length - height);
+		const currentViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop ?? this.#viewportTopRow));
+		const pageStep = Math.max(1, height - 1);
+		const targetViewportTop = Math.max(0, Math.min(maxViewportTop, currentViewportTop + direction * pageStep));
+
+		if (targetViewportTop >= maxViewportTop) {
+			this.#manualViewportTop = undefined;
+		} else {
+			this.#manualViewportTop = targetViewportTop;
+		}
+
+		const cursorPos = this.#manualViewportTop === undefined ? this.#lastCursorPosition : null;
+		return this.#repaintViewportFromLines(
+			this.#previousLines,
+			width,
+			height,
+			targetViewportTop,
+			cursorPos,
+			"manual viewport scroll",
+		);
+	}
+
+	followLiveViewport(): boolean {
+		if (this.#manualViewportTop === undefined) return false;
+		const height = this.terminal.rows;
+		const width = this.terminal.columns;
+		const liveViewportTop = Math.max(0, this.#previousLines.length - height);
+		this.#manualViewportTop = undefined;
+		return this.#repaintViewportFromLines(
+			this.#previousLines,
+			width,
+			height,
+			liveViewportTop,
+			this.#lastCursorPosition,
+			"manual viewport follow live",
+		);
+	}
 
 	/**
 	 * Show an overlay component with configurable positioning and sizing.
@@ -526,7 +569,7 @@ export class TUI extends Container {
 			data => this.#handleInput(data),
 			() => {
 				this.invalidate();
-				this.requestRender(!(isMultiplexerSession() && !useLegacyMultiplexerFullRender()), "resize");
+				this.requestResizeRender();
 			},
 		);
 		this.#hideCursor();
@@ -770,6 +813,22 @@ export class TUI extends Container {
 		this.#previousHeight = 0;
 	}
 
+	/**
+	 * Multiplexer-aware resize render request.
+	 *
+	 * A forced full redraw (`requestRender(true)`) resets `#previousWidth`/`#previousHeight`
+	 * to -1, which makes `#doRender` treat the frame as a width change and fall into the
+	 * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
+	 * `3J` escape (users navigate scrollback history), so replaying every transcript line
+	 * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
+	 * high speed" resize storm. Here we keep force off in multiplexers so `#doRender`'s
+	 * height-change branch takes the viewport-only `multiplexerViewportRepaint` path instead.
+	 * Set `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy forced redraw.
+	 */
+	requestResizeRender(): void {
+		this.requestRender(!(isMultiplexerSession() && !useLegacyMultiplexerFullRender()), "resize");
+	}
+
 	requestRender(force = false, source = "unknown"): void {
 		if (!this.terminalAvailable) {
 			this.#markTerminalUnavailable();
@@ -1345,6 +1404,64 @@ export class TUI extends Container {
 		padded.splice(insertAt, 0, ...Array.from({ length: blankRows }, () => ""));
 		return padded;
 	}
+	#repaintViewportFromLines(
+		lines: string[],
+		width: number,
+		height: number,
+		viewportTop: number,
+		cursorPos: { row: number; col: number } | null,
+		reason: string,
+	): boolean {
+		if (height <= 0 || width <= 0) return false;
+		const maxViewportTop = Math.max(0, lines.length - height);
+		const nextViewportTop = Math.max(0, Math.min(maxViewportTop, viewportTop));
+		const currentScreenRow = Math.max(0, Math.min(height - 1, this.#hardwareCursorRow - this.#viewportTopRow));
+		let buffer = "\x1b[?2026h";
+		if (currentScreenRow > 0) {
+			buffer += `\x1b[${currentScreenRow}A`;
+		}
+		buffer += "\r";
+
+		for (let screenRow = 0; screenRow < height; screenRow++) {
+			if (screenRow > 0) buffer += "\r\n";
+			buffer += "\x1b[2K";
+			const lineIndex = nextViewportTop + screenRow;
+			if (lineIndex >= lines.length) continue;
+			const line = lines[lineIndex];
+			const isImage = TERMINAL.isImageLine(line);
+			if (!isImage && visibleWidth(line) > width) {
+				let truncatedLine = truncateToWidth(line, width, Ellipsis.Omit);
+				truncatedLine += truncatedLine.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET;
+				buffer += truncatedLine;
+			} else {
+				buffer += line;
+			}
+		}
+
+		const finalPhysicalRow = nextViewportTop + Math.max(0, height - 1);
+		let cursorSeq = "\x1b[?25l";
+		let cursorToRow = finalPhysicalRow;
+		if (cursorPos && cursorPos.row >= nextViewportTop && cursorPos.row < nextViewportTop + height) {
+			const cursor = this.#cursorControlSequence(cursorPos, lines.length, finalPhysicalRow);
+			cursorSeq = cursor.seq;
+			cursorToRow = cursor.toRow;
+		}
+		this.#hardwareCursorRow = cursorToRow;
+		buffer += cursorSeq;
+		buffer += "\x1b[?2026l";
+		if (!this.#writeTerminal(buffer)) return false;
+
+		if ($flag("PI_DEBUG_REDRAW")) {
+			const logPath = getDebugLogPath();
+			const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (lines=${lines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
+			fs.appendFileSync(logPath, msg);
+		}
+
+		this.#cursorRow = Math.max(0, lines.length - 1);
+		this.#maxLinesRendered = lines.length;
+		this.#viewportTopRow = nextViewportTop;
+		return true;
+	}
 
 	#doRender(): void {
 		if (this.#stopped || !this.terminalAvailable) return;
@@ -1375,6 +1492,7 @@ export class TUI extends Container {
 
 		// Extract cursor position (marker must be found before diff comparison)
 		const cursorPos = this.#extractCursorPosition(newLines, height);
+		this.#lastCursorPosition = cursorPos;
 
 		// Terminate every non-image line so #previousLines mirrors emitted bytes
 		// (closes SGR + OSC 8 hyperlink state). Must run after cursor extraction
@@ -1435,6 +1553,28 @@ export class TUI extends Container {
 			if (usedWindowNormalize) renderMetrics.recordLineCount("offscreenScan", diffStart);
 		}
 
+		if (this.#manualViewportTop !== undefined) {
+			const maxViewportTop = Math.max(0, newLines.length - height);
+			const nextViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop));
+			const followingLive = nextViewportTop >= maxViewportTop;
+			this.#manualViewportTop = followingLive ? undefined : nextViewportTop;
+			const repaintCursorPos = followingLive ? cursorPos : null;
+			if (
+				this.#repaintViewportFromLines(
+					newLines,
+					width,
+					height,
+					nextViewportTop,
+					repaintCursorPos,
+					"manual viewport render",
+				)
+			) {
+				this.#previousLines = newLines;
+				this.#previousWidth = width;
+				this.#previousHeight = height;
+			}
+			return;
+		}
 		// Helper to clear scrollback and viewport and render all new lines
 		const fullRender = (clear: boolean, reason = "full render"): void => {
 			this.#fullRedrawCount += 1;
@@ -1540,7 +1680,16 @@ export class TUI extends Container {
 		// Width changes always need a full re-render because wrapping changes.
 		if (widthChanged) {
 			logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
-			fullRender(true, "terminal width changed");
+			if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
+				// In multiplexers a full replay piles the whole transcript back onto
+				// scrollback (3J is intentionally skipped). Repaint the viewport only,
+				// mirroring the height-change branch. This also neutralizes the fake
+				// width change that requestRender(true) injects via #previousWidth = -1,
+				// so every force-render call site is safe in multiplexers too.
+				multiplexerViewportRepaint(`terminal width changed (${this.#previousWidth} -> ${width})`);
+			} else {
+				fullRender(true, "terminal width changed");
+			}
 			return;
 		}