@gajae-code/tui 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [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
+
+- Added process-isolated deterministic render-golden capture fixtures and coverage for editor overlays, rich-text resize, multiplexer viewport repaint, sixel preservation, Termux height diffs, and transcript shrink/clear regressions.
+- Added layout/rendering benchmarks for editor layout, markdown rendering, and frame rendering.
+
+### Changed
+
+- Tightened markdown/editor rendering and terminal repaint behavior for the compact tool-block spacing and render-golden stability work.
+
 ## [0.4.5] - 2026-06-12
 
 - Version aligned with the 0.4.5 monorepo release; no functional changes in this package.

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

@@ -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.
@@ -78,6 +81,8 @@ export declare class Editor implements Component, Focusable {
     invalidate(): void;
     render(width: number): string[];
     handleInput(data: string): void;
+    /** Test-only seam: current wrap-cache entry count (memory-bound assertions). */
+    get wrappedLineCacheSize(): number;
     getText(): string;
     /**
      * Get text with paste markers expanded to their actual content.

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/dist/types/tui.d.ts

@@ -159,4 +159,10 @@ export declare class TUI extends Container {
     removeInputListener(listener: InputListener): void;
     stop(): void;
     requestRender(force?: boolean, source?: string): void;
+    getLineRenderCacheStats(): {
+        normalizationSize: number;
+        truncationSize: number;
+        normalizationLimit: number;
+        truncationLimit: number;
+    };
 }

package/dist/types/utils.d.ts

@@ -1,6 +1,7 @@
 import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@gajae-code/natives";
 export { Ellipsis } from "@gajae-code/natives";
 export { getDefaultTabWidth, getIndentation } from "@gajae-code/utils";
+export declare function isPrintableAscii(text: string): boolean;
 export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
 export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null, pad?: boolean | null): string;
 export declare function wrapTextWithAnsi(text: string, width: number): string[];

package/package.json

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

package/src/components/editor.ts

@@ -9,6 +9,7 @@ import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
 import {
 	getSegmenter,
 	getWordNavKind,
+	isPrintableAscii,
 	moveWordLeft,
 	moveWordRight,
 	padding,
@@ -53,6 +54,53 @@ interface TextChunk {
 	endIndex: number;
 }
 
+interface WrappedLine {
+	chunks: TextChunk[];
+	width: number;
+}
+
+interface CachedWrappedLine extends WrappedLine {
+	lineRef: string;
+	contentWidth: number;
+}
+
+function wordWrapAsciiLine(line: string, maxWidth: number): TextChunk[] {
+	if (line.length <= maxWidth) {
+		return [{ text: line, startIndex: 0, endIndex: line.length }];
+	}
+
+	const chunks: TextChunk[] = [];
+	let chunkStart = 0;
+	while (chunkStart < line.length) {
+		let chunkEnd = Math.min(line.length, chunkStart + maxWidth);
+		if (chunkEnd < line.length) {
+			let breakAt = -1;
+			for (let i = chunkEnd; i > chunkStart; i--) {
+				const code = line.charCodeAt(i - 1);
+				if (code === 0x20 || code === 0x09) {
+					breakAt = i - 1;
+					break;
+				}
+			}
+			if (breakAt > chunkStart) chunkEnd = breakAt;
+		}
+
+		const raw = line.slice(chunkStart, chunkEnd);
+		const text = raw.trimEnd();
+		if (text || chunks.length === 0) {
+			chunks.push({ text, startIndex: chunkStart, endIndex: chunkStart + raw.length });
+		}
+		chunkStart = chunkEnd;
+		while (chunkStart < line.length) {
+			const code = line.charCodeAt(chunkStart);
+			if (code !== 0x20 && code !== 0x09) break;
+			chunkStart++;
+		}
+	}
+
+	return chunks.length > 0 ? chunks : [{ text: "", startIndex: 0, endIndex: 0 }];
+}
+
 /**
  * Split a line into word-wrapped chunks.
  * Wraps at word boundaries when possible, falling back to character-level
@@ -66,6 +114,9 @@ function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
 	if (!line || maxWidth <= 0) {
 		return [{ text: "", startIndex: 0, endIndex: 0 }];
 	}
+	if (isPrintableAscii(line)) {
+		return wordWrapAsciiLine(line, maxWidth);
+	}
 
 	const lineWidth = visibleWidth(line);
 	if (lineWidth <= maxWidth) {
@@ -349,6 +400,7 @@ export class Editor implements Component, Focusable {
 	#paddingXOverride: number | undefined;
 	#maxHeight?: number;
 	#scrollOffset: number = 0;
+	#wrappedLineCache: CachedWrappedLine[] = [];
 
 	// Emacs-style kill ring
 	#killRing = new KillRing();
@@ -412,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.
@@ -566,10 +627,11 @@ export class Editor implements Component, Focusable {
 		if (this.onChange) {
 			this.onChange(this.getText());
 		}
+		this.#wrappedLineCache.length = 0;
 	}
 
 	invalidate(): void {
-		// No cached state to invalidate currently
+		this.#wrappedLineCache.length = 0;
 	}
 
 	#getEditorPaddingX(): number {
@@ -692,14 +754,18 @@ export class Editor implements Component, Focusable {
 		return Math.max(1, visibleHeight - 1);
 	}
 
-	#updateScrollOffset(layoutWidth: number, layoutLines: LayoutLine[], visibleHeight: number): void {
+	#findCurrentLayoutLine(layoutLines: LayoutLine[]): number {
+		const index = layoutLines.findIndex(line => line.hasCursor);
+		return index === -1 ? Math.max(0, layoutLines.length - 1) : index;
+	}
+
+	#updateScrollOffset(layoutLines: LayoutLine[], visibleHeight: number): void {
 		if (layoutLines.length <= visibleHeight) {
 			this.#scrollOffset = 0;
 			return;
 		}
 
-		const visualLines = this.#buildVisualLineMap(layoutWidth);
-		const cursorLine = this.#findCurrentVisualLine(visualLines);
+		const cursorLine = this.#findCurrentLayoutLine(layoutLines);
 		if (cursorLine < this.#scrollOffset) {
 			this.#scrollOffset = cursorLine;
 		} else if (cursorLine >= this.#scrollOffset + visibleHeight) {
@@ -730,7 +796,7 @@ export class Editor implements Component, Focusable {
 		// Layout the text
 		const layoutLines = this.#layoutText(layoutWidth);
 		const visibleContentHeight = this.#getVisibleContentHeight(layoutLines.length);
-		this.#updateScrollOffset(layoutWidth, layoutLines, visibleContentHeight);
+		this.#updateScrollOffset(layoutLines, visibleContentHeight);
 		const visibleLayoutLines = layoutLines.slice(this.#scrollOffset, this.#scrollOffset + visibleContentHeight);
 
 		const result: string[] = [];
@@ -1321,11 +1387,34 @@ export class Editor implements Component, Focusable {
 		}
 	}
 
+	#getWrappedLine(lineIndex: number, contentWidth: number): WrappedLine {
+		const line = this.#state.lines[lineIndex] || "";
+		const cached = this.#wrappedLineCache[lineIndex];
+		if (cached?.lineRef === line && cached.contentWidth === contentWidth) return cached;
+
+		const width = isPrintableAscii(line) ? line.length : visibleWidth(line);
+		const chunks =
+			width <= contentWidth
+				? [{ text: line, startIndex: 0, endIndex: line.length }]
+				: wordWrapLine(line, contentWidth);
+		const wrapped = { lineRef: line, contentWidth, width, chunks };
+		this.#wrappedLineCache[lineIndex] = wrapped;
+		return wrapped;
+	}
+
+	/** Test-only seam: current wrap-cache entry count (memory-bound assertions). */
+	get wrappedLineCacheSize(): number {
+		return this.#wrappedLineCache.length;
+	}
+
 	#layoutText(contentWidth: number): LayoutLine[] {
 		const layoutLines: LayoutLine[] = [];
 
 		if (this.#state.lines.length === 0 || (this.#state.lines.length === 1 && this.#state.lines[0] === "")) {
-			// Empty editor
+			// Empty editor — keep the wrap cache bounded by document size like
+			// the non-empty path below (stale entries from a previously large
+			// buffer must not be retained).
+			this.#wrappedLineCache.length = this.#state.lines.length;
 			layoutLines.push({
 				text: "",
 				hasCursor: true,
@@ -1338,9 +1427,9 @@ export class Editor implements Component, Focusable {
 		for (let i = 0; i < this.#state.lines.length; i++) {
 			const line = this.#state.lines[i] || "";
 			const isCurrentLine = i === this.#state.cursorLine;
-			const lineVisibleWidth = visibleWidth(line);
+			const wrappedLine = this.#getWrappedLine(i, contentWidth);
 
-			if (lineVisibleWidth <= contentWidth) {
+			if (wrappedLine.width <= contentWidth) {
 				// Line fits in one layout line
 				if (isCurrentLine) {
 					layoutLines.push({
@@ -1356,7 +1445,7 @@ export class Editor implements Component, Focusable {
 				}
 			} else {
 				// Line needs wrapping - use word-aware wrapping
-				const chunks = wordWrapLine(line, contentWidth);
+				const chunks = wrappedLine.chunks;
 
 				for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
 					const chunk = chunks[chunkIndex];
@@ -1406,6 +1495,7 @@ export class Editor implements Component, Focusable {
 			}
 		}
 
+		this.#wrappedLineCache.length = this.#state.lines.length;
 		return layoutLines;
 	}
 
@@ -1749,6 +1839,7 @@ export class Editor implements Component, Focusable {
 		this.#historyIndex = -1;
 		this.#scrollOffset = 0;
 		this.#undoStack.length = 0;
+		this.#wrappedLineCache.length = 0;
 
 		if (this.onChange) this.onChange("");
 		if (this.onSubmit) this.onSubmit(result);
@@ -2294,15 +2385,15 @@ export class Editor implements Component, Focusable {
 
 		for (let i = 0; i < this.#state.lines.length; i++) {
 			const line = this.#state.lines[i] || "";
-			const lineVisWidth = visibleWidth(line);
+			const wrappedLine = this.#getWrappedLine(i, width);
 			if (line.length === 0) {
 				// Empty line still takes one visual line
 				visualLines.push({ logicalLine: i, startCol: 0, length: 0 });
-			} else if (lineVisWidth <= width) {
+			} else if (wrappedLine.width <= width) {
 				visualLines.push({ logicalLine: i, startCol: 0, length: line.length });
 			} else {
 				// Line needs wrapping - use word-aware wrapping
-				const chunks = wordWrapLine(line, width);
+				const chunks = wrappedLine.chunks;
 				for (const chunk of chunks) {
 					visualLines.push({
 						logicalLine: i,
@@ -2340,8 +2431,10 @@ export class Editor implements Component, Focusable {
 
 	#moveCursor(deltaLine: number, deltaCol: number): void {
 		this.#resetKillSequence();
-		const visualLines = this.#buildVisualLineMap(this.#lastLayoutWidth);
-		const currentVisualLine = this.#findCurrentVisualLine(visualLines);
+		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
+		const needsVisualLines = deltaLine !== 0 || (deltaCol > 0 && this.#state.cursorCol >= currentLine.length);
+		const visualLines = needsVisualLines ? this.#buildVisualLineMap(this.#lastLayoutWidth) : [];
+		const currentVisualLine = needsVisualLines ? this.#findCurrentVisualLine(visualLines) : -1;
 
 		if (deltaLine !== 0) {
 			const targetVisualLine = currentVisualLine + deltaLine;
@@ -2352,15 +2445,18 @@ export class Editor implements Component, Focusable {
 		}
 
 		if (deltaCol !== 0) {
-			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
-
 			if (deltaCol > 0) {
 				// Moving right - move by one grapheme (handles emojis, combining characters, etc.)
 				if (this.#state.cursorCol < currentLine.length) {
-					const afterCursor = currentLine.slice(this.#state.cursorCol);
-					const graphemes = [...segmenter.segment(afterCursor)];
-					const firstGrapheme = graphemes[0];
-					this.#setCursorCol(this.#state.cursorCol + (firstGrapheme ? firstGrapheme.segment.length : 1));
+					const charCode = currentLine.charCodeAt(this.#state.cursorCol);
+					if (charCode >= 0x20 && charCode <= 0x7e) {
+						this.#setCursorCol(this.#state.cursorCol + 1);
+					} else {
+						const afterCursor = currentLine.slice(this.#state.cursorCol);
+						const graphemes = [...segmenter.segment(afterCursor)];
+						const firstGrapheme = graphemes[0];
+						this.#setCursorCol(this.#state.cursorCol + (firstGrapheme ? firstGrapheme.segment.length : 1));
+					}
 				} else if (this.#state.cursorLine < this.#state.lines.length - 1) {
 					// Wrap to start of next logical line
 					this.#state.cursorLine++;
@@ -2375,10 +2471,15 @@ export class Editor implements Component, Focusable {
 			} else {
 				// Moving left - move by one grapheme (handles emojis, combining characters, etc.)
 				if (this.#state.cursorCol > 0) {
-					const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
-					const graphemes = [...segmenter.segment(beforeCursor)];
-					const lastGrapheme = graphemes[graphemes.length - 1];
-					this.#setCursorCol(this.#state.cursorCol - (lastGrapheme ? lastGrapheme.segment.length : 1));
+					const charCode = currentLine.charCodeAt(this.#state.cursorCol - 1);
+					if (charCode >= 0x20 && charCode <= 0x7e) {
+						this.#setCursorCol(this.#state.cursorCol - 1);
+					} else {
+						const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
+						const graphemes = [...segmenter.segment(beforeCursor)];
+						const lastGrapheme = graphemes[graphemes.length - 1];
+						this.#setCursorCol(this.#state.cursorCol - (lastGrapheme ? lastGrapheme.segment.length : 1));
+					}
 				} else if (this.#state.cursorLine > 0) {
 					// Wrap to end of previous logical line
 					this.#state.cursorLine--;

package/src/components/markdown.ts

@@ -39,11 +39,25 @@ markdownParser.setOptions({
 // (Rust FFI) work for content/layout combinations already seen this session.
 
 const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
-const renderCache = new LRUCache<string, string[]>({ max: RENDER_CACHE_MAX });
+const renderCache = new LRUCache<string, { source: string; lines: string[] }>({ max: RENDER_CACHE_MAX });
+const PARSE_CACHE_MAX = 128;
+const parseCache = new LRUCache<string, { source: string; tokens: Token[] }>({ max: PARSE_CACHE_MAX });
+
+// Full-content 64-bit wyhash over every byte (no lossy sampling). Cache hits
+// additionally verify entry.source against the normalized text, so even a
+// hash collision can never return another message's render.
+function markdownContentKey(text: string): string {
+	return `${text.length}:${Bun.hash(text).toString(36)}`;
+}
+
+function wrapTextIfNeeded(line: string, width: number): string[] {
+	return wrapTextWithAnsi(line, width);
+}
 
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export function clearRenderCache(): void {
 	renderCache.clear();
+	parseCache.clear();
 }
 
 // Stable numeric IDs for structural theme/style objects (no ID field on type).
@@ -195,32 +209,36 @@ export class Markdown implements Component {
 		// Replace tabs with 3 spaces for consistent rendering
 		const normalizedText = replaceTabs(this.#text);
 
+		const contentKey = markdownContentKey(normalizedText);
+
 		// L2: module-level LRU — survives component disposal/recreation across
 		// session-tree navigations. Key encodes every dimension that affects the
-		// render output so different configurations never collide.
-		// Encode terminal capability state and theme/style function output samples
-		// so that capability shifts (image protocol changes, hyperlink toggle) or
-		// caller-supplied theme/bgColor functions that mutate their output without
-		// changing object identity invalidate the cache entry.
-		// bgColor probe uses \x01 (single non-printable byte): chalk/ANSI wrappers
-		// pass arbitrary bytes through verbatim, so this is safe and minimizes the
-		// risk of clashing with a function that returns text verbatim.
-		// theme.heading is used as the representative theme probe — it's required
-		// by MarkdownTheme and is one of the most styling-sensitive entries.
+		// render output so different configurations never collide. The markdown
+		// content dimension is a full-content hash; entries store the source text
+		// and verify it on hit so hash collisions can never serve wrong output.
 		const bgColorProbe = this.#defaultTextStyle?.bgColor ? this.#defaultTextStyle.bgColor("\x01") : "";
 		const headingProbe = this.#theme.heading("");
-		const cacheKey = `${normalizedText}\x00${width}\x00${this.#paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
+		const cacheKey = `${contentKey}\x00${width}\x00${this.#paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
 		const cached = renderCache.get(cacheKey);
-		if (cached !== undefined) {
+		if (cached !== undefined && cached.source === normalizedText) {
 			// Populate L1 so subsequent calls from this instance are O(1) map lookup.
 			this.#cachedText = this.#text;
 			this.#cachedWidth = width;
-			this.#cachedLines = cached;
-			return cached;
+			this.#cachedLines = cached.lines;
+			return cached.lines;
 		}
 
-		// Parse markdown to HTML-like tokens
-		const tokens = markdownParser.lexer(normalizedText);
+		// Parse markdown to marked tokens. Parse cache is width/theme independent,
+		// so the same content can be reused across resize/layout renders even when
+		// final wrapped output must differ by width.
+		const cachedParse = parseCache.get(contentKey);
+		let tokens: Token[];
+		if (cachedParse !== undefined && cachedParse.source === normalizedText) {
+			tokens = cachedParse.tokens;
+		} else {
+			tokens = markdownParser.lexer(normalizedText);
+			parseCache.set(contentKey, { source: normalizedText, tokens });
+		}
 
 		// Convert tokens to styled terminal output
 		const renderedLines: string[] = [];
@@ -235,11 +253,10 @@ export class Markdown implements Component {
 		// Wrap lines (NO padding, NO background yet)
 		const wrappedLines: string[] = [];
 		for (const line of renderedLines) {
-			// Skip wrapping for image protocol lines (would corrupt escape sequences)
 			if (TERMINAL.isImageLine(line)) {
 				wrappedLines.push(line);
 			} else {
-				wrappedLines.push(...wrapTextWithAnsi(line, contentWidth));
+				wrappedLines.push(...wrapTextIfNeeded(line, contentWidth));
 			}
 		}
 
@@ -287,7 +304,7 @@ export class Markdown implements Component {
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
-		renderCache.set(cacheKey, result);
+		renderCache.set(cacheKey, { source: normalizedText, lines: result });
 
 		return result;
 	}
@@ -495,7 +512,7 @@ export class Markdown implements Component {
 
 				for (const quoteLine of renderedQuoteLines) {
 					const styledLine = applyQuoteStyle(quoteLine);
-					const wrappedLines = wrapTextWithAnsi(styledLine, quoteContentWidth);
+					const wrappedLines = wrapTextIfNeeded(styledLine, quoteContentWidth);
 					for (const wrappedLine of wrappedLines) {
 						lines.push(this.#theme.quoteBorder(`${this.#theme.symbols.quoteBorder} `) + wrappedLine);
 					}
@@ -755,7 +772,7 @@ export class Markdown implements Component {
 	 * consistently with the rest of the renderer.
 	 */
 	#wrapCellText(text: string, maxWidth: number): string[] {
-		return wrapTextWithAnsi(text, Math.max(1, maxWidth));
+		return wrapTextIfNeeded(text, Math.max(1, maxWidth));
 	}
 
 	/**

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

@@ -12,6 +12,7 @@ import { ImageProtocol, setCellDimensions, setTerminalImageProtocol, TERMINAL }
 import {
 	Ellipsis,
 	extractSegments,
+	isPrintableAscii,
 	normalizeTerminalOutput,
 	sliceByColumn,
 	sliceWithWidth,
@@ -227,12 +228,21 @@ export class Container implements Component {
 	}
 }
 
+type LineNormalizationCacheEntry = {
+	normalized: string;
+	terminated: string;
+};
+
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
 export class TUI extends Container {
 	terminal: Terminal;
 	#previousLines: string[] = [];
+	#lineNormalizationCache = new Map<string, LineNormalizationCacheEntry>();
+	#lineTruncationCache = new Map<string, string>();
+	#lineNormalizationCacheLimit = 0;
+	#lineTruncationCacheLimit = 0;
 	#previousWidth = 0;
 	#previousHeight = 0;
 	#focusedComponent: Component | null = null;
@@ -244,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
@@ -648,6 +663,8 @@ export class TUI extends Container {
 		// focus/listener state is intentionally preserved so input routing survives
 		// a resume.
 		this.#previousLines = [];
+		this.#lineNormalizationCache.clear();
+		this.#lineTruncationCache.clear();
 		this.#previousWidth = 0;
 		this.#previousHeight = 0;
 	}
@@ -659,9 +676,15 @@ 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();
 			this.#previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
 			this.#previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
+			this.#lineNormalizationCacheLimit = 0;
+			this.#lineTruncationCacheLimit = 0;
 			this.#cursorRow = 0;
 			this.#hardwareCursorRow = 0;
 			this.#viewportTopRow = 0;
@@ -684,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());
@@ -713,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;
@@ -764,7 +821,7 @@ export class TUI extends Container {
 				return;
 			}
 			this.#focusedComponent.handleInput(data);
-			this.requestRender();
+			this.requestRender(false, "input");
 		}
 	}
 
@@ -1092,25 +1149,71 @@ export class TUI extends Container {
 	 * written to the terminal — without this, the diff cache disagrees with
 	 * emitted output and OSC 8 hyperlink state can leak across lines.
 	 */
-	#applyLineResets(lines: string[]): string[] {
-		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i];
-			if (TERMINAL.isImageLine(line)) continue;
-			const normalized = normalizeTerminalOutput(line);
-			// Only close OSC 8 hyperlinks when the line actually opened one;
-			// emitting `\x1b]8;;\x07` on every line just feeds the terminal's OSC
-			// parser for no reason (measurable cost in xterm.js parse loop).
-			lines[i] = normalized + (normalized.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+	#normalizeLineForRender(line: string): LineNormalizationCacheEntry {
+		const cached = this.#lineNormalizationCache.get(line);
+		if (cached !== undefined) return cached;
+		const normalized = normalizeTerminalOutput(line);
+		const terminated = normalized + (normalized.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+		this.#lineNormalizationCache.set(line, { normalized, terminated });
+		return { normalized, terminated };
+	}
+
+	#lineFitsWidth(normalizedLine: string, width: number): boolean {
+		return isPrintableAscii(normalizedLine) && normalizedLine.length <= width
+			? true
+			: visibleWidth(normalizedLine) <= width;
+	}
+
+	#truncateNormalizedLine(normalizedLine: string, width: number): string {
+		const key = `${width}\0${normalizedLine}`;
+		const cached = this.#lineTruncationCache.get(key);
+		if (cached !== undefined) return cached;
+		const truncated = truncateToWidth(normalizedLine, width, Ellipsis.Omit);
+		const terminated = truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+		this.#lineTruncationCache.set(key, terminated);
+		return terminated;
+	}
+
+	#trimLineCachesForRender(lineCount: number): void {
+		const limit = Math.max(1, lineCount * 2);
+		this.#lineNormalizationCacheLimit = limit;
+		this.#lineTruncationCacheLimit = limit;
+		while (this.#lineNormalizationCache.size > limit) {
+			const key = this.#lineNormalizationCache.keys().next().value;
+			if (key === undefined) break;
+			this.#lineNormalizationCache.delete(key);
 		}
-		return lines;
+		while (this.#lineTruncationCache.size > limit) {
+			const key = this.#lineTruncationCache.keys().next().value;
+			if (key === undefined) break;
+			this.#lineTruncationCache.delete(key);
+		}
+	}
+
+	getLineRenderCacheStats(): {
+		normalizationSize: number;
+		truncationSize: number;
+		normalizationLimit: number;
+		truncationLimit: number;
+	} {
+		return {
+			normalizationSize: this.#lineNormalizationCache.size,
+			truncationSize: this.#lineTruncationCache.size,
+			normalizationLimit: this.#lineNormalizationCacheLimit,
+			truncationLimit: this.#lineTruncationCacheLimit,
+		};
 	}
-	#truncateLinesToWidth(lines: string[], width: number): string[] {
+
+	#applyLineResetsAndTruncate(lines: string[], width: number): string[] {
 		for (let i = 0; i < lines.length; i++) {
 			const line = lines[i];
-			if (TERMINAL.isImageLine(line) || visibleWidth(line) <= width) continue;
-			const truncated = truncateToWidth(line, width, Ellipsis.Omit);
-			lines[i] = truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+			if (TERMINAL.isImageLine(line)) continue;
+			const { normalized, terminated } = this.#normalizeLineForRender(line);
+			lines[i] = this.#lineFitsWidth(normalized, width)
+				? terminated
+				: this.#truncateNormalizedLine(normalized, width);
 		}
+		this.#trimLineCachesForRender(lines.length);
 		return lines;
 	}
 
@@ -1144,8 +1247,7 @@ export class TUI extends Container {
 		// (closes SGR + OSC 8 hyperlink state). Must run after cursor extraction
 		// because the marker is embedded mid-line, and before any diff/full render
 		// path so cache comparisons stay byte-accurate.
-		newLines = this.#applyLineResets(newLines);
-		newLines = this.#truncateLinesToWidth(newLines, width);
+		newLines = this.#applyLineResetsAndTruncate(newLines, width);
 
 		// Width changed - need full re-render (line wrapping changes)
 		const widthChanged = this.#previousWidth !== 0 && this.#previousWidth !== width;

package/src/utils.ts

@@ -24,6 +24,14 @@ function recordTextHelper<T>(name: string, fn: () => T): T {
 	}
 }
 
+export function isPrintableAscii(text: string): boolean {
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		if (code < 0x20 || code > 0x7e) return false;
+	}
+	return true;
+}
+
 export function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult {
 	return nativeSliceWithWidth(line, startCol, length, strict ?? null, getDefaultTabWidth());
 }