@gajae-code/tui 0.11.6 → 0.11.8

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.11.8] - 2026-07-23
+
+## [0.11.7] - 2026-07-22
+### Fixed
+
+- Internal transcript PageUp/PageDown now continues through tool-output and other non-semantic rows instead of intermittently becoming a no-op after a semantic viewport anchor was established.
+
+### Fixed
+
+- Spurious resize events with unchanged terminal dimensions (iTerm2 tab switches and window focus changes deliver SIGWINCH without a size change) no longer trigger a forced full redraw. On hosts still using the full clear+replay path (legacy multiplexer opt-in, non-process terminals) that redraw cleared scrollback (`2J`/`H`/`3J`) and replayed the entire transcript, which could park the native viewport at the top of the thread when returning to the tab. `requestResizeRender()` now forces only when the grid size actually changed since the last committed frame; same-size events fall through to a no-op diff render.
+
 ## [0.11.4] - 2026-07-20
 ### Fixed
 

package/dist/types/keys.d.ts

@@ -41,11 +41,11 @@ export declare function setKittyProtocolActive(active: boolean): void;
 export declare function isKittyProtocolActive(): boolean;
 type Letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
 type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
-type SymbolKey = "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | "," | "." | "/" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "+" | "|" | "~" | "{" | "}" | ":" | "<" | ">" | "?";
+type SymbolKey = "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | '"' | "," | "." | "/" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "+" | "|" | "~" | "{" | "}" | ":" | "<" | ">" | "?";
 type SpecialKey = "escape" | "esc" | "enter" | "return" | "tab" | "space" | "backspace" | "delete" | "insert" | "clear" | "home" | "end" | "pageUp" | "pageDown" | "up" | "down" | "left" | "right" | "f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "f10" | "f11" | "f12";
-type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
-type ModifierName = "ctrl" | "shift" | "alt" | "super";
-type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+export type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+export type KeyModifier = "ctrl" | "shift" | "alt" | "super";
+type ModifiedKeyId<Key extends string, RemainingModifiers extends KeyModifier = KeyModifier> = {
     [M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
 }[RemainingModifiers];
 /**
@@ -53,6 +53,19 @@ type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName =
  * Provides autocomplete and catches typos at compile time.
  */
 export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
+export interface ParsedKeyId {
+    keyId: KeyId;
+    modifiers: KeyModifier[];
+    baseKey: BaseKey;
+}
+/**
+ * Parse a case-insensitive key identifier into normalized dispatch parts.
+ * The legacy `plus` base-key alias normalizes to `+`; the trailing `+` in
+ * values such as `ctrl++` is the literal plus base.
+ */
+export declare function parseKeyId(value: string): ParsedKeyId | undefined;
+/** Whether a value is a valid canonical key identifier. */
+export declare function isKeyId(value: string): value is KeyId;
 /**
  * Typed helper for constructing key identifiers with autocomplete.
  *

package/dist/types/tui.d.ts

@@ -281,6 +281,15 @@ export declare class TUI extends Container {
      * the transcript top during streaming redraws, so viewport-repaint sessions
      * keep force off and let `#doRender` repaint only the live viewport. Set
      * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
+     *
+     * Spurious resize events (SIGWINCH with unchanged dimensions — iTerm2 tab
+     * switches and window focus changes, the self-sent SIGWINCH after resume)
+     * must not force either: on hosts still using the `fullRender` path (legacy
+     * multiplexer opt-in, non-process terminals) the forced redraw clears
+     * scrollback (`2J`/`H`/`3J`) and replays the whole transcript, which can
+     * park the native viewport at the transcript top. Only force when the grid
+     * size actually changed since the last committed frame; a plain diff render
+     * is a no-op otherwise.
      */
     requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.11.6",
+	"version": "0.11.8",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.11.6",
-		"@gajae-code/utils": "0.11.6",
+		"@gajae-code/natives": "0.11.8",
+		"@gajae-code/utils": "0.11.8",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/keybindings.ts

@@ -170,7 +170,16 @@ const SHIFTED_SYMBOL_KEYS = new Set<string>([
 	"~",
 ]);
 
-const normalizeKeyId = (key: KeyId): KeyId => key.toLowerCase() as KeyId;
+const normalizeKeyId = (key: KeyId): KeyId => {
+	const normalized = key.toLowerCase();
+	if (normalized.endsWith("pageup")) {
+		return `${normalized.slice(0, -6)}pageUp` as KeyId;
+	}
+	if (normalized.endsWith("pagedown")) {
+		return `${normalized.slice(0, -8)}pageDown` as KeyId;
+	}
+	return normalized as KeyId;
+};
 
 function normalizeKeys(keys: KeyId | KeyId[] | undefined): KeyId[] {
 	if (keys === undefined) return [];

package/src/keys.ts

@@ -117,6 +117,7 @@ type SymbolKey =
 	| "\\"
 	| ";"
 	| "'"
+	| '"'
 	| ","
 	| "."
 	| "/"
@@ -173,10 +174,10 @@ type SpecialKey =
 	| "f11"
 	| "f12";
 
-type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
-type ModifierName = "ctrl" | "shift" | "alt" | "super";
+export type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+export type KeyModifier = "ctrl" | "shift" | "alt" | "super";
 
-type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+type ModifiedKeyId<Key extends string, RemainingModifiers extends KeyModifier = KeyModifier> = {
 	[M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
 }[RemainingModifiers];
 
@@ -186,6 +187,123 @@ type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName =
  */
 export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
 
+export interface ParsedKeyId {
+	keyId: KeyId;
+	modifiers: KeyModifier[];
+	baseKey: BaseKey;
+}
+
+const BASE_KEYS = new Set<string>([
+	..."abcdefghijklmnopqrstuvwxyz",
+	..."0123456789",
+	"`",
+	"-",
+	"=",
+	"[",
+	"]",
+	"\\",
+	";",
+	"'",
+	'"',
+	",",
+	".",
+	"/",
+	"!",
+	"@",
+	"#",
+	"$",
+	"%",
+	"^",
+	"&",
+	"*",
+	"(",
+	")",
+	"_",
+	"+",
+	"|",
+	"~",
+	"{",
+	"}",
+	":",
+	"<",
+	">",
+	"?",
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+	"f1",
+	"f2",
+	"f3",
+	"f4",
+	"f5",
+	"f6",
+	"f7",
+	"f8",
+	"f9",
+	"f10",
+	"f11",
+	"f12",
+]);
+
+const KEY_MODIFIERS: readonly KeyModifier[] = ["ctrl", "alt", "shift", "super"];
+
+/**
+ * Parse a case-insensitive key identifier into normalized dispatch parts.
+ * The legacy `plus` base-key alias normalizes to `+`; the trailing `+` in
+ * values such as `ctrl++` is the literal plus base.
+ */
+export function parseKeyId(value: string): ParsedKeyId | undefined {
+	if (hasControlChars(value) || value.length === 0) return undefined;
+
+	const lowerCaseValue = value
+		.trim()
+		.toLowerCase()
+		.replace(/\s*\+\s*/g, "+");
+	const normalized = lowerCaseValue === "plus" ? "+" : lowerCaseValue.replace(/\+plus$/, "++");
+	const baseKey = normalized.endsWith("+") ? "+" : normalized.split("+").pop();
+	if (!baseKey || !BASE_KEYS.has(baseKey)) return undefined;
+
+	const modifierSource = normalized.slice(0, normalized.length - baseKey.length);
+	const modifierParts =
+		modifierSource.length === 0
+			? []
+			: modifierSource
+					.slice(0, -1)
+					.split("+")
+					.map(part => part.trim());
+	if (modifierParts.some(part => !KEY_MODIFIERS.includes(part as KeyModifier))) return undefined;
+
+	const modifiers = modifierParts as KeyModifier[];
+	if (new Set(modifiers).size !== modifiers.length) return undefined;
+
+	const canonicalBase = baseKey === "pageup" ? "pageUp" : baseKey === "pagedown" ? "pageDown" : baseKey;
+	return {
+		keyId: [...modifiers, canonicalBase].join("+") as KeyId,
+		modifiers,
+		baseKey: canonicalBase as BaseKey,
+	};
+}
+
+/** Whether a value is a valid canonical key identifier. */
+export function isKeyId(value: string): value is KeyId {
+	return parseKeyId(value)?.keyId === value;
+}
+
 /**
  * Typed helper for constructing key identifiers with autocomplete.
  *

package/src/terminal-capabilities.ts

@@ -1,5 +1,5 @@
 import { encodeSixel } from "@gajae-code/natives";
-import { $env } from "@gajae-code/utils";
+import { $env, $pickenv } from "@gajae-code/utils";
 
 export enum ImageProtocol {
 	Kitty = "\x1b_G",
@@ -125,7 +125,7 @@ export function isCursorNeutralImagePermittedInFallback(): boolean {
 }
 
 function getForcedImageProtocol(): ImageProtocol | null | undefined {
-	const raw = $env.PI_FORCE_IMAGE_PROTOCOL?.trim().toLowerCase();
+	const raw = $pickenv("GJC_FORCE_IMAGE_PROTOCOL", "PI_FORCE_IMAGE_PROTOCOL")?.trim().toLowerCase();
 	if (!raw) return undefined;
 	if (raw === "kitty") return ImageProtocol.Kitty;
 	if (raw === "iterm2" || raw === "iterm") return ImageProtocol.Iterm2;

package/src/terminal.ts

@@ -1,6 +1,6 @@
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as fs from "node:fs";
-import { $env, $flag } from "@gajae-code/utils";
+import { $env, $flag, $pickenv } from "@gajae-code/utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
 import { isUnderTerminalMultiplexer } from "./terminal-capabilities";
@@ -209,7 +209,7 @@ export class ProcessTerminal implements Terminal {
 	#stdinBuffer?: StdinBuffer;
 	#stdinDataHandler?: (data: string | Buffer) => void;
 	#dead = false;
-	#writeLogPath = $env.PI_TUI_WRITE_LOG || "";
+	#writeLogPath = $pickenv("GJC_TUI_WRITE_LOG", "PI_TUI_WRITE_LOG") || "";
 	#detachLogPath = $env.PI_TUI_TERMINAL_DETACH_LOG || "";
 	#windowsVTInputRestore?: () => void;
 	#stdoutErrorHandler?: (err: Error) => 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, logger, onDefaultTabWidthChange } from "@gajae-code/utils";
+import { $flag, $pickflag, getDebugLogPath, logger, onDefaultTabWidthChange } from "@gajae-code/utils";
 import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
@@ -654,7 +654,7 @@ export class TUI extends Container {
 	#sixelProbeBuffer = "";
 	#sixelProbeTimeout?: NodeJS.Timeout;
 	#sixelProbeUnsubscribe?: () => void;
-	#showHardwareCursor = $flag("PI_HARDWARE_CURSOR");
+	#showHardwareCursor = $pickflag("GJC_HARDWARE_CURSOR", "PI_HARDWARE_CURSOR");
 	#debugRedraw = TUI.#readDebugRedrawFlag();
 	// macOS: steady-block cursor anchors CJK IME overlays; disable with GJC_TUI_IME_CURSOR=0.
 	readonly #useImeBlockCursor = $flag("GJC_TUI_IME_CURSOR", process.platform === "darwin");
@@ -895,7 +895,14 @@ export class TUI extends Container {
 					selected = { row, anchor };
 			}
 			if (selected === undefined) {
-				if (this.#manualViewportAnchor !== null) return false;
+				// A page can consist entirely of non-semantic rows such as tool output,
+				// transient panels, or pinned chrome. Fall back to numeric viewport
+				// ownership so PageUp/PageDown can continue through those rows instead
+				// of becoming an intermittent no-op. A later page with an eligible row
+				// will establish a fresh semantic anchor.
+				this.#manualViewportAnchor = null;
+				this.#manualViewportFallbackAnchors = [];
+				this.#reconcileMissingViewportAnchor = false;
 			} else {
 				this.#manualViewportAnchor = {
 					id: selected.anchor.id,
@@ -1339,9 +1346,20 @@ export class TUI extends Container {
 	 * the transcript top during streaming redraws, so viewport-repaint sessions
 	 * keep force off and let `#doRender` repaint only the live viewport. Set
 	 * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
+	 *
+	 * Spurious resize events (SIGWINCH with unchanged dimensions — iTerm2 tab
+	 * switches and window focus changes, the self-sent SIGWINCH after resume)
+	 * must not force either: on hosts still using the `fullRender` path (legacy
+	 * multiplexer opt-in, non-process terminals) the forced redraw clears
+	 * scrollback (`2J`/`H`/`3J`) and replays the whole transcript, which can
+	 * park the native viewport at the transcript top. Only force when the grid
+	 * size actually changed since the last committed frame; a plain diff render
+	 * is a no-op otherwise.
 	 */
 	requestResizeRender(): void {
-		this.requestRender(!useViewportRepaintPath(this.terminal), "resize");
+		const dimensionsChanged =
+			this.#previousWidth !== this.terminal.columns || this.#previousHeight !== this.terminal.rows;
+		this.requestRender(dimensionsChanged && !useViewportRepaintPath(this.terminal), "resize");
 	}
 
 	requestRender(force = false, source = "unknown"): void {