@gajae-code/tui 0.11.7 → 0.11.9

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [0.11.9] - 2026-07-24
+
 ## [0.11.7] - 2026-07-22
 ### 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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.11.7",
+	"version": "0.11.9",
 	"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.7",
-		"@gajae-code/utils": "0.11.7",
+		"@gajae-code/natives": "0.11.9",
+		"@gajae-code/utils": "0.11.9",
 		"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,13 +654,13 @@ 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");
 	// showHardwareCursor=false but cursor is shown for IME anchoring (macOS).
 	#imeCursorActive = false;
-	#clearOnShrink = $flag("PI_CLEAR_ON_SHRINK"); // Clear empty rows when content shrinks (default: off)
+	#clearOnShrink = $pickflag("GJC_CLEAR_ON_SHRINK", "PI_CLEAR_ON_SHRINK"); // Clear empty rows when content shrinks (default: off)
 	// Default-on: reuse the previous normalized off-screen prefix and only normalize/diff the
 	// visible window, bounding per-frame work on huge transcripts. Output stays byte-identical;
 	// set PI_TUI_VIRTUAL_VIEWPORT=0 to restore legacy full-transcript normalization.
@@ -693,7 +693,7 @@ export class TUI extends Container {
 
 	static #readDebugRedrawFlag(): boolean {
 		TUI.#renderCounters.debugRedrawEnvReads += 1;
-		return $flag("PI_DEBUG_REDRAW");
+		return $pickflag("GJC_DEBUG_REDRAW", "PI_DEBUG_REDRAW");
 	}
 
 	#appendDebugRedrawLog(message: string): void {
@@ -2451,7 +2451,7 @@ export class TUI extends Container {
 
 		// Content shrunk below the previous render and no overlays - re-render to clear empty rows
 		// (overlays need the padding, so only do this when no overlays are active)
-		// Configurable via setClearOnShrink() or PI_CLEAR_ON_SHRINK=0 env var
+		// Configurable via setClearOnShrink() or GJC_CLEAR_ON_SHRINK=0 env var
 		if (this.#clearOnShrink && newLines.length < this.#previousLines.length && this.overlayStack.length === 0) {
 			logRedraw(`clearOnShrink (prev=${this.#previousLines.length}, new=${newLines.length})`);
 			if (
@@ -2662,7 +2662,7 @@ export class TUI extends Container {
 		buffer += seq;
 		buffer += "\x1b[?2026l"; // End synchronized output
 
-		if ($flag("PI_TUI_DEBUG")) {
+		if ($pickflag("GJC_TUI_DEBUG", "PI_TUI_DEBUG")) {
 			const debugDir = "/tmp/tui";
 			fs.mkdirSync(debugDir, { recursive: true });
 			const debugPath = path.join(debugDir, `render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);