@gajae-code/tui 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-06-14
+
+### Fixed
+
+- Fixed Korean/Hangul input composition breaking in Android Termius, where typing `안녕하세요` produced duplicated jamo/syllable residue (`ㅇ아안ㄴ녀녕…`). GJC's startup keyboard reprogramming (Kitty keyboard protocol query `CSI ? u` / push `CSI > 7 u`, and the xterm modifyOtherKeys fallback `CSI > 4 ; 2 m`) disrupts the Android IME's syllable composition. Added a `GJC_TUI_KEYBOARD_PROTOCOL` opt-out (enabled by default): set `GJC_TUI_KEYBOARD_PROTOCOL=0` to leave the keyboard in its default mode so IME composition works, matching terminals/TUIs that never enable these enhanced input modes.
+
 ## [0.5.0] - 2026-06-13
 
 ### Added

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

@@ -22,7 +22,7 @@ interface HistoryEntry {
 }
 interface HistoryStorage {
     add(prompt: string, cwd?: string): Promise<void>;
-    getRecent(limit: number): HistoryEntry[];
+    getRecent(limit: number, cwd?: string): HistoryEntry[];
 }
 export declare class Editor implements Component, Focusable {
     #private;
@@ -41,6 +41,9 @@ export declare class Editor implements Component, Focusable {
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
     setAutocompleteProvider(provider: AutocompleteProvider): void;
+    getAutocompleteProvider(): AutocompleteProvider | undefined;
+    /** Whether the autocomplete dropdown is currently open. */
+    isAutocompleteOpen(): boolean;
     /**
      * Set custom content for the top border (e.g., status line).
      * Pass undefined to use the default plain border.

package/dist/types/terminal.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Whether GJC may reprogram the keyboard with enhanced input protocols
+ * (the Kitty keyboard protocol and the xterm modifyOtherKeys fallback).
+ *
+ * Enabled by default. Set `GJC_TUI_KEYBOARD_PROTOCOL=0` to leave the keyboard in
+ * its default mode. Some terminals — notably Android Termius — break IME
+ * composition (e.g. Korean/Hangul syllable composition) while these enhanced
+ * modes are active, committing every intermediate composing jamo/syllable
+ * instead of only the final character. Disabling the protocol restores normal
+ * IME behavior, matching how other TUIs that leave the keyboard untouched render
+ * Korean correctly.
+ */
+export declare function keyboardEnhancementEnabled(): boolean;
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"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.5.0",
-		"@gajae-code/utils": "0.5.0",
+		"@gajae-code/natives": "0.5.2",
+		"@gajae-code/utils": "0.5.2",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/editor.ts

@@ -368,7 +368,7 @@ interface HistoryEntry {
 
 interface HistoryStorage {
 	add(prompt: string, cwd?: string): Promise<void>;
-	getRecent(limit: number): HistoryEntry[];
+	getRecent(limit: number, cwd?: string): HistoryEntry[];
 }
 
 type HistoryCursorAnchor = "start" | "end";
@@ -464,6 +464,15 @@ export class Editor implements Component, Focusable {
 		this.#autocompleteProvider = provider;
 	}
 
+	getAutocompleteProvider(): AutocompleteProvider | undefined {
+		return this.#autocompleteProvider;
+	}
+
+	/** Whether the autocomplete dropdown is currently open. */
+	isAutocompleteOpen(): boolean {
+		return this.#autocompleteState !== null && this.#autocompleteList !== undefined;
+	}
+
 	/**
 	 * Set custom content for the top border (e.g., status line).
 	 * Pass undefined to use the default plain border.
@@ -545,7 +554,7 @@ export class Editor implements Component, Focusable {
 
 	setHistoryStorage(storage: HistoryStorage): void {
 		this.#historyStorage = storage;
-		const recent = storage.getRecent(100);
+		const recent = storage.getRecent(100, getProjectDir());
 		this.#history = recent.map(entry => entry.prompt);
 		this.#historyIndex = -1;
 	}

package/src/terminal.ts

@@ -1,6 +1,6 @@
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as fs from "node:fs";
-import { $env } from "@gajae-code/utils";
+import { $env, $flag } from "@gajae-code/utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
 
@@ -8,6 +8,22 @@ const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
 const TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1b]9;4;0;\x07";
 
+/**
+ * Whether GJC may reprogram the keyboard with enhanced input protocols
+ * (the Kitty keyboard protocol and the xterm modifyOtherKeys fallback).
+ *
+ * Enabled by default. Set `GJC_TUI_KEYBOARD_PROTOCOL=0` to leave the keyboard in
+ * its default mode. Some terminals — notably Android Termius — break IME
+ * composition (e.g. Korean/Hangul syllable composition) while these enhanced
+ * modes are active, committing every intermediate composing jamo/syllable
+ * instead of only the final character. Disabling the protocol restores normal
+ * IME behavior, matching how other TUIs that leave the keyboard untouched render
+ * Korean correctly.
+ */
+export function keyboardEnhancementEnabled(): boolean {
+	return $flag("GJC_TUI_KEYBOARD_PROTOCOL", true);
+}
+
 /**
  * Minimal terminal interface for TUI
  */
@@ -513,6 +529,14 @@ export class ProcessTerminal implements Terminal {
 	#queryAndEnableKittyProtocol(): void {
 		this.#setupStdinBuffer();
 		process.stdin.on("data", this.#stdinDataHandler!);
+		// Leave the keyboard in its default mode when enhanced input protocols are
+		// disabled. Android Termius (and similar terminals) break IME/Hangul
+		// composition when the Kitty keyboard protocol or modifyOtherKeys is active,
+		// committing every intermediate composing jamo/syllable. Skipping the query
+		// and the modifyOtherKeys fallback restores normal IME composition.
+		if (!keyboardEnhancementEnabled()) {
+			return;
+		}
 		this.#safeWrite("\x1b[?u");
 		this.#modifyOtherKeysTimeout = setTimeout(() => {
 			this.#modifyOtherKeysTimeout = undefined;

package/src/tui.ts

@@ -254,6 +254,11 @@ export class TUI extends Container {
 	#renderTimer: NodeJS.Timeout | undefined;
 	#lastRenderAt = 0;
 	static readonly #MIN_RENDER_INTERVAL_MS = 16;
+	// Input-priority scheduling: an input keystroke must never be starved behind a
+	// pending normal (frame-budget) render timer. When set, an input-priority render
+	// is queued for the next tick and supersedes any pending normal timer.
+	#inputRenderPending = false;
+
 	#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
@@ -671,6 +676,8 @@ export class TUI extends Container {
 		}
 		if (renderMetrics.enabled) renderMetrics.recordRequest(source);
 		if (force) {
+			// A forced full redraw supersedes any queued input-priority render.
+			this.#inputRenderPending = false;
 			this.#previousLines = [];
 			this.#lineNormalizationCache.clear();
 			this.#lineTruncationCache.clear();
@@ -700,6 +707,19 @@ export class TUI extends Container {
 			});
 			return;
 		}
+		// Input-priority path: expedite so the keystroke echoes within the next tick
+		// instead of waiting for (or behind) the frame-budget timer. Re-entrant input
+		// requests in the same turn coalesce via #inputRenderPending, so at most one
+		// expedited render commits per event-loop turn (no repaint storms). This only
+		// changes WHEN #doRender runs; the render output path is unchanged.
+		if (source === "input" || source === "editor.input") {
+			if (!this.#inputRenderPending) {
+				this.#inputRenderPending = true;
+				this.#renderRequested = true;
+				process.nextTick(() => this.#commitExpeditedRender());
+			}
+			return;
+		}
 		if (this.#renderRequested) return;
 		this.#renderRequested = true;
 		process.nextTick(() => this.#scheduleRender());
@@ -729,6 +749,27 @@ export class TUI extends Container {
 		if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 1);
 	}
 
+	// Commit a single input-priority render on the next tick, cancelling any normal
+	// frame-budget timer scheduled in the same turn. nextTick always precedes a
+	// pending setTimeout, so the keystroke is never starved behind streaming renders.
+	#commitExpeditedRender(): void {
+		if (!this.#inputRenderPending) return; // cancelled (e.g., by a forced render)
+		this.#inputRenderPending = false;
+		if (this.#stopped || !this.#renderRequested) {
+			return;
+		}
+		if (this.#renderTimer) {
+			clearTimeout(this.#renderTimer);
+			this.#renderTimer = undefined;
+			if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 0);
+		}
+		this.#renderRequested = false;
+		this.#lastRenderAt = performance.now();
+		const t0 = renderMetrics.now();
+		this.#doRender();
+		if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
+	}
+
 	#handleInput(data: string): void {
 		if (this.#inputListeners.size > 0) {
 			let current = data;
@@ -780,7 +821,7 @@ export class TUI extends Container {
 				return;
 			}
 			this.#focusedComponent.handleInput(data);
-			this.requestRender();
+			this.requestRender(false, "input");
 		}
 	}