@oh-my-pi/pi-tui 3.37.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-tui",
-	"version": "3.37.0",
+	"version": "4.0.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "src/index.ts",

package/src/components/input.ts

@@ -1,3 +1,4 @@
+import { getEditorKeybindings } from "../keybindings";
 import {
 	isAltBackspace,
 	isAltLeft,
@@ -13,7 +14,6 @@ import {
 	isCtrlU,
 	isCtrlW,
 	isDelete,
-	isEnter,
 } from "../keys";
 import type { Component } from "../tui";
 import { getSegmenter, isPunctuationChar, isWhitespaceChar, visibleWidth } from "../utils";
@@ -27,6 +27,7 @@ export class Input implements Component {
 	private value: string = "";
 	private cursor: number = 0; // Cursor position in the value
 	public onSubmit?: (value: string) => void;
+	public onEscape?: () => void;
 
 	// Bracketed paste mode buffering
 	private pasteBuffer: string = "";
@@ -78,8 +79,14 @@ export class Input implements Component {
 			}
 			return;
 		}
+		const kb = getEditorKeybindings();
+		if (kb.matches(data, "selectCancel")) {
+			this.onEscape?.();
+			return;
+		}
+
 		// Handle special keys
-		if (isEnter(data) || data === "\n") {
+		if (kb.matches(data, "submit") || data === "\n") {
 			// Enter - submit
 			if (this.onSubmit) {
 				this.onSubmit(this.value);

package/src/editor-component.ts

@@ -0,0 +1,65 @@
+import type { AutocompleteProvider } from "./autocomplete";
+import type { Component } from "./tui";
+
+/**
+ * Interface for custom editor components.
+ *
+ * This allows extensions to provide their own editor implementation
+ * (e.g., vim mode, emacs mode, custom keybindings) while maintaining
+ * compatibility with the core application.
+ */
+export interface EditorComponent extends Component {
+	// =========================================================================
+	// Core text access (required)
+	// =========================================================================
+
+	/** Get the current text content */
+	getText(): string;
+
+	/** Set the text content */
+	setText(text: string): void;
+
+	// =========================================================================
+	// Callbacks (required)
+	// =========================================================================
+
+	/** Called when user submits (e.g., Enter key) */
+	onSubmit?: (text: string) => void;
+
+	/** Called when text changes */
+	onChange?: (text: string) => void;
+
+	// =========================================================================
+	// History support (optional)
+	// =========================================================================
+
+	/** Add text to history for up/down navigation */
+	addToHistory?(text: string): void;
+
+	// =========================================================================
+	// Advanced text manipulation (optional)
+	// =========================================================================
+
+	/** Insert text at current cursor position */
+	insertTextAtCursor?(text: string): void;
+
+	/**
+	 * Get text with any markers expanded (e.g., paste markers).
+	 * Falls back to getText() if not implemented.
+	 */
+	getExpandedText?(): string;
+
+	// =========================================================================
+	// Autocomplete support (optional)
+	// =========================================================================
+
+	/** Set the autocomplete provider */
+	setAutocompleteProvider?(provider: AutocompleteProvider): void;
+
+	// =========================================================================
+	// Appearance (optional)
+	// =========================================================================
+
+	/** Border color function */
+	borderColor?: (str: string) => string;
+}

package/src/index.ts

@@ -21,6 +21,8 @@ export { Spacer } from "./components/spacer";
 export { type Tab, TabBar, type TabBarTheme } from "./components/tab-bar";
 export { Text } from "./components/text";
 export { TruncatedText } from "./components/truncated-text";
+// Editor component interface (for custom editors)
+export type { EditorComponent } from "./editor-component";
 // Keybindings
 export {
 	DEFAULT_EDITOR_KEYBINDINGS,
@@ -64,6 +66,9 @@ export {
 	isEnter,
 	isEscape,
 	isHome,
+	isKeyRelease,
+	isKeyRepeat,
+	isKittyProtocolActive,
 	isShiftBackspace,
 	isShiftCtrlD,
 	isShiftCtrlO,
@@ -74,10 +79,14 @@ export {
 	isShiftTab,
 	isTab,
 	Key,
+	type KeyEventType,
 	type KeyId,
 	matchesKey,
 	parseKey,
+	setKittyProtocolActive,
 } from "./keys";
+// Input buffering for batch splitting
+export { StdinBuffer, type StdinBufferEventMap, type StdinBufferOptions } from "./stdin-buffer";
 export type { BoxSymbols, SymbolTheme } from "./symbols";
 // Terminal interface and implementations
 export { emergencyTerminalRestore, ProcessTerminal, type Terminal } from "./terminal";

package/src/keys.ts

@@ -13,8 +13,31 @@
  * - matchesKey(data, keyId) - Check if input matches a key identifier
  * - parseKey(data) - Parse input and return the key identifier
  * - Key - Helper object for creating typed key identifiers
+ * - setKittyProtocolActive(active) - Set global Kitty protocol state
+ * - isKittyProtocolActive() - Query global Kitty protocol state
  */
 
+// =============================================================================
+// Global Kitty Protocol State
+// =============================================================================
+
+let kittyProtocolActive = false;
+
+/**
+ * Set the global Kitty keyboard protocol state.
+ * Called by ProcessTerminal after detecting protocol support.
+ */
+export function setKittyProtocolActive(active: boolean): void {
+	kittyProtocolActive = active;
+}
+
+/**
+ * Query whether Kitty keyboard protocol is currently active.
+ */
+export function isKittyProtocolActive(): boolean {
+	return kittyProtocolActive;
+}
+
 // =============================================================================
 // Type-Safe Key Identifiers
 // =============================================================================
@@ -271,33 +294,85 @@ const FUNCTIONAL_CODEPOINTS = {
 // Kitty Protocol Parsing
 // =============================================================================
 
+/**
+ * Event types from Kitty keyboard protocol (flag 2)
+ * 1 = key press, 2 = key repeat, 3 = key release
+ */
+export type KeyEventType = "press" | "repeat" | "release";
+
 interface ParsedKittySequence {
 	codepoint: number;
 	modifier: number;
+	eventType: KeyEventType;
+}
+
+/**
+ * Check if the last parsed key event was a key release.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ */
+export function isKeyRelease(data: string): boolean {
+	return (
+		data.includes(":3u") ||
+		data.includes(":3~") ||
+		data.includes(":3A") ||
+		data.includes(":3B") ||
+		data.includes(":3C") ||
+		data.includes(":3D") ||
+		data.includes(":3H") ||
+		data.includes(":3F")
+	);
+}
+
+/**
+ * Check if the last parsed key event was a key repeat.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ */
+export function isKeyRepeat(data: string): boolean {
+	return (
+		data.includes(":2u") ||
+		data.includes(":2~") ||
+		data.includes(":2A") ||
+		data.includes(":2B") ||
+		data.includes(":2C") ||
+		data.includes(":2D") ||
+		data.includes(":2H") ||
+		data.includes(":2F")
+	);
+}
+
+function parseEventType(eventTypeStr: string | undefined): KeyEventType {
+	if (!eventTypeStr) return "press";
+	const eventType = parseInt(eventTypeStr, 10);
+	if (eventType === 2) return "repeat";
+	if (eventType === 3) return "release";
+	return "press";
 }
 
 function parseKittySequence(data: string): ParsedKittySequence | null {
-	// CSI u format: \x1b[<num>u or \x1b[<num>;<mod>u
-	const csiUMatch = data.match(/^\x1b\[(\d+)(?:;(\d+))?u$/);
+	// CSI u format: \x1b[<num>u or \x1b[<num>;<mod>u or \x1b[<num>;<mod>:<event>u
+	const csiUMatch = data.match(/^\x1b\[(\d+)(?:;(\d+))?(?::(\d+))?u$/);
 	if (csiUMatch) {
 		const codepoint = parseInt(csiUMatch[1]!, 10);
 		const modValue = csiUMatch[2] ? parseInt(csiUMatch[2], 10) : 1;
-		return { codepoint, modifier: modValue - 1 };
+		const eventType = parseEventType(csiUMatch[3]);
+		return { codepoint, modifier: modValue - 1, eventType };
 	}
 
-	// Arrow keys with modifier: \x1b[1;<mod>A/B/C/D
-	const arrowMatch = data.match(/^\x1b\[1;(\d+)([ABCD])$/);
+	// Arrow keys with modifier: \x1b[1;<mod>A/B/C/D or \x1b[1;<mod>:<event>A/B/C/D
+	const arrowMatch = data.match(/^\x1b\[1;(\d+)(?::(\d+))?([ABCD])$/);
 	if (arrowMatch) {
 		const modValue = parseInt(arrowMatch[1]!, 10);
+		const eventType = parseEventType(arrowMatch[2]);
 		const arrowCodes: Record<string, number> = { A: -1, B: -2, C: -3, D: -4 };
-		return { codepoint: arrowCodes[arrowMatch[2]!]!, modifier: modValue - 1 };
+		return { codepoint: arrowCodes[arrowMatch[3]!]!, modifier: modValue - 1, eventType };
 	}
 
-	// Functional keys: \x1b[<num>~ or \x1b[<num>;<mod>~
-	const funcMatch = data.match(/^\x1b\[(\d+)(?:;(\d+))?~$/);
+	// Functional keys: \x1b[<num>~ or \x1b[<num>;<mod>~ or \x1b[<num>;<mod>:<event>~
+	const funcMatch = data.match(/^\x1b\[(\d+)(?:;(\d+))?(?::(\d+))?~$/);
 	if (funcMatch) {
 		const keyNum = parseInt(funcMatch[1]!, 10);
 		const modValue = funcMatch[2] ? parseInt(funcMatch[2], 10) : 1;
+		const eventType = parseEventType(funcMatch[3]);
 		const funcCodes: Record<number, number> = {
 			2: FUNCTIONAL_CODEPOINTS.insert,
 			3: FUNCTIONAL_CODEPOINTS.delete,
@@ -308,16 +383,17 @@ function parseKittySequence(data: string): ParsedKittySequence | null {
 		};
 		const codepoint = funcCodes[keyNum];
 		if (codepoint !== undefined) {
-			return { codepoint, modifier: modValue - 1 };
+			return { codepoint, modifier: modValue - 1, eventType };
 		}
 	}
 
-	// Home/End with modifier: \x1b[1;<mod>H/F
-	const homeEndMatch = data.match(/^\x1b\[1;(\d+)([HF])$/);
+	// Home/End with modifier: \x1b[1;<mod>H/F or \x1b[1;<mod>:<event>H/F
+	const homeEndMatch = data.match(/^\x1b\[1;(\d+)(?::(\d+))?([HF])$/);
 	if (homeEndMatch) {
 		const modValue = parseInt(homeEndMatch[1]!, 10);
-		const codepoint = homeEndMatch[2] === "H" ? FUNCTIONAL_CODEPOINTS.home : FUNCTIONAL_CODEPOINTS.end;
-		return { codepoint, modifier: modValue - 1 };
+		const eventType = parseEventType(homeEndMatch[2]);
+		const codepoint = homeEndMatch[3] === "H" ? FUNCTIONAL_CODEPOINTS.home : FUNCTIONAL_CODEPOINTS.end;
+		return { codepoint, modifier: modValue - 1, eventType };
 	}
 
 	return null;
@@ -402,17 +478,28 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 		case "enter":
 		case "return":
 			if (shift && !ctrl && !alt) {
-				return (
-					data === "\x1b\r" || // Legacy: some terminals send ESC+CR for shift+enter
+				if (
 					matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift) ||
 					matchesKittySequence(data, CODEPOINTS.kpEnter, MODIFIERS.shift)
-				);
+				) {
+					return true;
+				}
+				if (kittyProtocolActive) {
+					return data === "\x1b\r" || data === "\n";
+				}
+				return false;
 			}
 			if (alt && !ctrl && !shift) {
-				return (
+				if (
 					matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.alt) ||
 					matchesKittySequence(data, CODEPOINTS.kpEnter, MODIFIERS.alt)
-				);
+				) {
+					return true;
+				}
+				if (!kittyProtocolActive) {
+					return data === "\x1b\r";
+				}
+				return false;
 			}
 			if (modifier === 0) {
 				return (
@@ -534,7 +621,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			return matchesKittySequence(data, codepoint, modifier);
 		}
 
-		return data === key;
+		return data === key || matchesKittySequence(data, codepoint, 0);
 	}
 
 	return false;
@@ -577,14 +664,22 @@ export function parseKey(data: string): string | undefined {
 		}
 	}
 
-	// Legacy sequences
+	// Mode-aware legacy sequences
+	// When Kitty protocol is active, ambiguous sequences are interpreted as custom terminal mappings:
+	// - \x1b\r = shift+enter (Kitty mapping), not alt+enter
+	// - \n = shift+enter (Ghostty mapping)
+	if (kittyProtocolActive) {
+		if (data === "\x1b\r" || data === "\n") return "shift+enter";
+	}
+
+	// Legacy sequences (used when Kitty protocol is not active, or for unambiguous sequences)
 	if (data === "\x1b") return "escape";
 	if (data === "\t") return "tab";
 	if (data === "\r" || data === "\x1bOM") return "enter";
 	if (data === " ") return "space";
 	if (data === "\x7f" || data === "\x08") return "backspace";
 	if (data === "\x1b[Z") return "shift+tab";
-	if (data === "\x1b\r") return "shift+enter"; // Legacy: ESC+CR for shift+enter
+	if (!kittyProtocolActive && data === "\x1b\r") return "alt+enter";
 	if (data === "\x1b\x7f") return "alt+backspace";
 	if (data === "\x1b[A") return "up";
 	if (data === "\x1b[B") return "down";

package/src/stdin-buffer.ts

@@ -0,0 +1,386 @@
+/**
+ * StdinBuffer buffers input and emits complete sequences.
+ *
+ * This is necessary because stdin data events can arrive in partial chunks,
+ * especially for escape sequences like mouse events. Without buffering,
+ * partial sequences can be misinterpreted as regular keypresses.
+ *
+ * For example, the mouse SGR sequence `\x1b[<35;20;5m` might arrive as:
+ * - Event 1: `\x1b`
+ * - Event 2: `[<35`
+ * - Event 3: `;20;5m`
+ *
+ * The buffer accumulates these until a complete sequence is detected.
+ * Call the `process()` method to feed input data.
+ *
+ * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
+ * MIT License - Copyright (c) 2025 opentui
+ */
+
+import { EventEmitter } from "node:events";
+
+const ESC = "\x1b";
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+
+/**
+ * Check if a string is a complete escape sequence or needs more data
+ */
+function isCompleteSequence(data: string): "complete" | "incomplete" | "not-escape" {
+	if (!data.startsWith(ESC)) {
+		return "not-escape";
+	}
+
+	if (data.length === 1) {
+		return "incomplete";
+	}
+
+	const afterEsc = data.slice(1);
+
+	// CSI sequences: ESC [
+	if (afterEsc.startsWith("[")) {
+		// Check for old-style mouse sequence: ESC[M + 3 bytes
+		if (afterEsc.startsWith("[M")) {
+			// Old-style mouse needs ESC[M + 3 bytes = 6 total
+			return data.length >= 6 ? "complete" : "incomplete";
+		}
+		return isCompleteCsiSequence(data);
+	}
+
+	// OSC sequences: ESC ]
+	if (afterEsc.startsWith("]")) {
+		return isCompleteOscSequence(data);
+	}
+
+	// DCS sequences: ESC P ... ESC \ (includes XTVersion responses)
+	if (afterEsc.startsWith("P")) {
+		return isCompleteDcsSequence(data);
+	}
+
+	// APC sequences: ESC _ ... ESC \ (includes Kitty graphics responses)
+	if (afterEsc.startsWith("_")) {
+		return isCompleteApcSequence(data);
+	}
+
+	// SS3 sequences: ESC O
+	if (afterEsc.startsWith("O")) {
+		// ESC O followed by a single character
+		return afterEsc.length >= 2 ? "complete" : "incomplete";
+	}
+
+	// Meta key sequences: ESC followed by a single character
+	if (afterEsc.length === 1) {
+		return "complete";
+	}
+
+	// Unknown escape sequence - treat as complete
+	return "complete";
+}
+
+/**
+ * Check if CSI sequence is complete
+ * CSI sequences: ESC [ ... followed by a final byte (0x40-0x7E)
+ */
+function isCompleteCsiSequence(data: string): "complete" | "incomplete" {
+	if (!data.startsWith(`${ESC}[`)) {
+		return "complete";
+	}
+
+	// Need at least ESC [ and one more character
+	if (data.length < 3) {
+		return "incomplete";
+	}
+
+	const payload = data.slice(2);
+
+	// CSI sequences end with a byte in the range 0x40-0x7E (@-~)
+	// This includes all letters and several special characters
+	const lastChar = payload[payload.length - 1];
+	const lastCharCode = lastChar.charCodeAt(0);
+
+	if (lastCharCode >= 0x40 && lastCharCode <= 0x7e) {
+		// Special handling for SGR mouse sequences
+		// Format: ESC[<B;X;Ym or ESC[<B;X;YM
+		if (payload.startsWith("<")) {
+			// Must have format: <digits;digits;digits[Mm]
+			const mouseMatch = /^<\d+;\d+;\d+[Mm]$/.test(payload);
+			if (mouseMatch) {
+				return "complete";
+			}
+			// If it ends with M or m but doesn't match the pattern, still incomplete
+			if (lastChar === "M" || lastChar === "m") {
+				// Check if we have the right structure
+				const parts = payload.slice(1, -1).split(";");
+				if (parts.length === 3 && parts.every((p) => /^\d+$/.test(p))) {
+					return "complete";
+				}
+			}
+
+			return "incomplete";
+		}
+
+		return "complete";
+	}
+
+	return "incomplete";
+}
+
+/**
+ * Check if OSC sequence is complete
+ * OSC sequences: ESC ] ... ST (where ST is ESC \ or BEL)
+ */
+function isCompleteOscSequence(data: string): "complete" | "incomplete" {
+	if (!data.startsWith(`${ESC}]`)) {
+		return "complete";
+	}
+
+	// OSC sequences end with ST (ESC \) or BEL (\x07)
+	if (data.endsWith(`${ESC}\\`) || data.endsWith("\x07")) {
+		return "complete";
+	}
+
+	return "incomplete";
+}
+
+/**
+ * Check if DCS (Device Control String) sequence is complete
+ * DCS sequences: ESC P ... ST (where ST is ESC \)
+ * Used for XTVersion responses like ESC P >| ... ESC \
+ */
+function isCompleteDcsSequence(data: string): "complete" | "incomplete" {
+	if (!data.startsWith(`${ESC}P`)) {
+		return "complete";
+	}
+
+	// DCS sequences end with ST (ESC \)
+	if (data.endsWith(`${ESC}\\`)) {
+		return "complete";
+	}
+
+	return "incomplete";
+}
+
+/**
+ * Check if APC (Application Program Command) sequence is complete
+ * APC sequences: ESC _ ... ST (where ST is ESC \)
+ * Used for Kitty graphics responses like ESC _ G ... ESC \
+ */
+function isCompleteApcSequence(data: string): "complete" | "incomplete" {
+	if (!data.startsWith(`${ESC}_`)) {
+		return "complete";
+	}
+
+	// APC sequences end with ST (ESC \)
+	if (data.endsWith(`${ESC}\\`)) {
+		return "complete";
+	}
+
+	return "incomplete";
+}
+
+/**
+ * Split accumulated buffer into complete sequences
+ */
+function extractCompleteSequences(buffer: string): { sequences: string[]; remainder: string } {
+	const sequences: string[] = [];
+	let pos = 0;
+
+	while (pos < buffer.length) {
+		const remaining = buffer.slice(pos);
+
+		// Try to extract a sequence starting at this position
+		if (remaining.startsWith(ESC)) {
+			// Find the end of this escape sequence
+			let seqEnd = 1;
+			while (seqEnd <= remaining.length) {
+				const candidate = remaining.slice(0, seqEnd);
+				const status = isCompleteSequence(candidate);
+
+				if (status === "complete") {
+					sequences.push(candidate);
+					pos += seqEnd;
+					break;
+				} else if (status === "incomplete") {
+					seqEnd++;
+				} else {
+					// Should not happen when starting with ESC
+					sequences.push(candidate);
+					pos += seqEnd;
+					break;
+				}
+			}
+
+			if (seqEnd > remaining.length) {
+				return { sequences, remainder: remaining };
+			}
+		} else {
+			// Not an escape sequence - take a single character
+			sequences.push(remaining[0]!);
+			pos++;
+		}
+	}
+
+	return { sequences, remainder: "" };
+}
+
+export type StdinBufferOptions = {
+	/**
+	 * Maximum time to wait for sequence completion (default: 10ms)
+	 * After this time, the buffer is flushed even if incomplete
+	 */
+	timeout?: number;
+};
+
+export type StdinBufferEventMap = {
+	data: [string];
+	paste: [string];
+};
+
+/**
+ * Buffers stdin input and emits complete sequences via the 'data' event.
+ * Handles partial escape sequences that arrive across multiple chunks.
+ */
+export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
+	private buffer: string = "";
+	private timeout: ReturnType<typeof setTimeout> | null = null;
+	private readonly timeoutMs: number;
+	private pasteMode: boolean = false;
+	private pasteBuffer: string = "";
+
+	constructor(options: StdinBufferOptions = {}) {
+		super();
+		this.timeoutMs = options.timeout ?? 10;
+	}
+
+	public process(data: string | Buffer): void {
+		// Clear any pending timeout
+		if (this.timeout) {
+			clearTimeout(this.timeout);
+			this.timeout = null;
+		}
+
+		// Handle high-byte conversion (for compatibility with parseKeypress)
+		// If buffer has single byte > 127, convert to ESC + (byte - 128)
+		let str: string;
+		if (Buffer.isBuffer(data)) {
+			if (data.length === 1 && data[0]! > 127) {
+				const byte = data[0]! - 128;
+				str = `\x1b${String.fromCharCode(byte)}`;
+			} else {
+				str = data.toString();
+			}
+		} else {
+			str = data;
+		}
+
+		if (str.length === 0 && this.buffer.length === 0) {
+			this.emit("data", "");
+			return;
+		}
+
+		this.buffer += str;
+
+		if (this.pasteMode) {
+			this.pasteBuffer += this.buffer;
+			this.buffer = "";
+
+			const endIndex = this.pasteBuffer.indexOf(BRACKETED_PASTE_END);
+			if (endIndex !== -1) {
+				const pastedContent = this.pasteBuffer.slice(0, endIndex);
+				const remaining = this.pasteBuffer.slice(endIndex + BRACKETED_PASTE_END.length);
+
+				this.pasteMode = false;
+				this.pasteBuffer = "";
+
+				this.emit("paste", pastedContent);
+
+				if (remaining.length > 0) {
+					this.process(remaining);
+				}
+			}
+			return;
+		}
+
+		const startIndex = this.buffer.indexOf(BRACKETED_PASTE_START);
+		if (startIndex !== -1) {
+			if (startIndex > 0) {
+				const beforePaste = this.buffer.slice(0, startIndex);
+				const result = extractCompleteSequences(beforePaste);
+				for (const sequence of result.sequences) {
+					this.emit("data", sequence);
+				}
+			}
+
+			this.buffer = this.buffer.slice(startIndex + BRACKETED_PASTE_START.length);
+			this.pasteMode = true;
+			this.pasteBuffer = this.buffer;
+			this.buffer = "";
+
+			const endIndex = this.pasteBuffer.indexOf(BRACKETED_PASTE_END);
+			if (endIndex !== -1) {
+				const pastedContent = this.pasteBuffer.slice(0, endIndex);
+				const remaining = this.pasteBuffer.slice(endIndex + BRACKETED_PASTE_END.length);
+
+				this.pasteMode = false;
+				this.pasteBuffer = "";
+
+				this.emit("paste", pastedContent);
+
+				if (remaining.length > 0) {
+					this.process(remaining);
+				}
+			}
+			return;
+		}
+
+		const result = extractCompleteSequences(this.buffer);
+		this.buffer = result.remainder;
+
+		for (const sequence of result.sequences) {
+			this.emit("data", sequence);
+		}
+
+		if (this.buffer.length > 0) {
+			this.timeout = setTimeout(() => {
+				const flushed = this.flush();
+
+				for (const sequence of flushed) {
+					this.emit("data", sequence);
+				}
+			}, this.timeoutMs);
+		}
+	}
+
+	flush(): string[] {
+		if (this.timeout) {
+			clearTimeout(this.timeout);
+			this.timeout = null;
+		}
+
+		if (this.buffer.length === 0) {
+			return [];
+		}
+
+		const sequences = [this.buffer];
+		this.buffer = "";
+		return sequences;
+	}
+
+	clear(): void {
+		if (this.timeout) {
+			clearTimeout(this.timeout);
+			this.timeout = null;
+		}
+		this.buffer = "";
+		this.pasteMode = false;
+		this.pasteBuffer = "";
+	}
+
+	getBuffer(): string {
+		return this.buffer;
+	}
+
+	destroy(): void {
+		this.clear();
+	}
+}

package/src/terminal.ts

@@ -1,3 +1,6 @@
+import { setKittyProtocolActive } from "./keys";
+import { StdinBuffer } from "./stdin-buffer";
+
 /**
  * Minimal terminal interface for TUI
  */
@@ -40,6 +43,9 @@ export interface Terminal {
 	get columns(): number;
 	get rows(): number;
 
+	// Whether Kitty keyboard protocol is active
+	get kittyProtocolActive(): boolean;
+
 	// Cursor positioning (relative to current position)
 	moveBy(lines: number): void; // Move cursor up (negative) or down (positive) by N lines
 
@@ -63,6 +69,13 @@ export class ProcessTerminal implements Terminal {
 	private wasRaw = false;
 	private inputHandler?: (data: string) => void;
 	private resizeHandler?: () => void;
+	private _kittyProtocolActive = false;
+	private stdinBuffer?: StdinBuffer;
+	private stdinDataHandler?: (data: string) => void;
+
+	get kittyProtocolActive(): boolean {
+		return this._kittyProtocolActive;
+	}
 
 	start(onInput: (data: string) => void, onResize: () => void): void {
 		this.inputHandler = onInput;
@@ -82,15 +95,125 @@ export class ProcessTerminal implements Terminal {
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		process.stdout.write("\x1b[?2004h");
 
-		// Enable Kitty keyboard protocol (disambiguate escape codes)
-		// This makes terminals like Ghostty, Kitty, WezTerm send enhanced key sequences
-		// e.g., Shift+Enter becomes \x1b[13;2u instead of just \r
+		// Set up resize handler immediately
+		process.stdout.on("resize", this.resizeHandler);
+
+		// Query and enable Kitty keyboard protocol
+		// The query handler intercepts input temporarily, then installs the user's handler
 		// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
-		process.stdout.write("\x1b[>1u");
+		this.queryAndEnableKittyProtocol();
+	}
 
-		// Set up event handlers
-		process.stdin.on("data", this.inputHandler);
-		process.stdout.on("resize", this.resizeHandler);
+	/**
+	 * Set up StdinBuffer to split batched input into individual sequences.
+	 * This ensures components receive single events, making matchesKey/isKeyRelease work correctly.
+	 * Note: Does NOT register the stdin handler - that's done after the Kitty protocol query.
+	 */
+	private setupStdinBuffer(): void {
+		this.stdinBuffer = new StdinBuffer({ timeout: 10 });
+
+		// Forward individual sequences to the input handler
+		this.stdinBuffer.on("data", (sequence: string) => {
+			if (this.inputHandler) {
+				this.inputHandler(sequence);
+			}
+		});
+
+		// Re-wrap paste content with bracketed paste markers for existing editor handling
+		this.stdinBuffer.on("paste", (content: string) => {
+			if (this.inputHandler) {
+				this.inputHandler(`\x1b[200~${content}\x1b[201~`);
+			}
+		});
+
+		// Handler that pipes stdin data through the buffer
+		// Registration happens after Kitty protocol query completes
+		this.stdinDataHandler = (data: string) => {
+			this.stdinBuffer!.process(data);
+		};
+	}
+
+	/**
+	 * Query terminal for Kitty keyboard protocol support and enable if available.
+	 *
+	 * Sends CSI ? u to query current flags. If terminal responds with CSI ? <flags> u,
+	 * it supports the protocol and we enable it with CSI > 1 u.
+	 *
+	 * Non-supporting terminals won't respond, so we use a timeout.
+	 */
+	private queryAndEnableKittyProtocol(): void {
+		const QUERY_TIMEOUT_MS = 100;
+		let resolved = false;
+		let buffer = "";
+
+		// Kitty protocol response pattern: \x1b[?<flags>u
+		const kittyResponsePattern = /\x1b\[\?(\d+)u/;
+
+		const queryHandler = (data: string) => {
+			if (resolved) {
+				// Query phase done, forward to StdinBuffer
+				if (this.stdinBuffer) {
+					this.stdinBuffer.process(data);
+				}
+				return;
+			}
+
+			buffer += data;
+
+			// Check if we have a Kitty protocol response
+			const match = buffer.match(kittyResponsePattern);
+			if (match) {
+				resolved = true;
+				this._kittyProtocolActive = true;
+				setKittyProtocolActive(true);
+
+				// Enable Kitty keyboard protocol (push flags)
+				// Flag 1 = disambiguate escape codes
+				// Flag 2 = report event types (press/repeat/release)
+				process.stdout.write("\x1b[>3u");
+
+				// Remove the response from buffer, forward any remaining input through StdinBuffer
+				const remaining = buffer.replace(kittyResponsePattern, "");
+				if (remaining && this.stdinBuffer) {
+					this.stdinBuffer.process(remaining);
+				}
+
+				// Replace query handler with StdinBuffer handler
+				process.stdin.removeListener("data", queryHandler);
+				if (this.stdinDataHandler) {
+					process.stdin.on("data", this.stdinDataHandler);
+				}
+			}
+		};
+
+		// Set up StdinBuffer before query (it will receive input after query completes)
+		this.setupStdinBuffer();
+
+		// Temporarily intercept input for the query (before StdinBuffer)
+		process.stdin.on("data", queryHandler);
+
+		// Send query
+		process.stdout.write("\x1b[?u");
+
+		// Timeout: if no response, terminal doesn't support Kitty protocol
+		setTimeout(() => {
+			if (!resolved) {
+				resolved = true;
+				this._kittyProtocolActive = false;
+				setKittyProtocolActive(false);
+
+				// Forward any buffered input that wasn't a Kitty response through StdinBuffer
+				if (buffer && this.stdinBuffer) {
+					this.stdinBuffer.process(buffer);
+				}
+
+				// Replace query handler with StdinBuffer handler
+				process.stdin.removeListener("data", queryHandler);
+				if (this.stdinDataHandler) {
+					process.stdin.on("data", this.stdinDataHandler);
+				}
+			}
+		}, QUERY_TIMEOUT_MS);
 	}
 
 	stop(): void {
@@ -102,14 +225,25 @@ export class ProcessTerminal implements Terminal {
 		// Disable bracketed paste mode
 		process.stdout.write("\x1b[?2004l");
 
-		// Disable Kitty keyboard protocol (pop the flags we pushed)
-		process.stdout.write("\x1b[<u");
+		// Disable Kitty keyboard protocol (pop the flags we pushed) - only if we enabled it
+		if (this._kittyProtocolActive) {
+			process.stdout.write("\x1b[<u");
+			this._kittyProtocolActive = false;
+			setKittyProtocolActive(false);
+		}
+
+		// Clean up StdinBuffer
+		if (this.stdinBuffer) {
+			this.stdinBuffer.destroy();
+			this.stdinBuffer = undefined;
+		}
 
 		// Remove event handlers
-		if (this.inputHandler) {
-			process.stdin.removeListener("data", this.inputHandler);
-			this.inputHandler = undefined;
+		if (this.stdinDataHandler) {
+			process.stdin.removeListener("data", this.stdinDataHandler);
+			this.stdinDataHandler = undefined;
 		}
+		this.inputHandler = undefined;
 		if (this.resizeHandler) {
 			process.stdout.removeListener("resize", this.resizeHandler);
 			this.resizeHandler = undefined;

package/src/tui.ts

@@ -5,10 +5,10 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { isShiftCtrlD } from "./keys";
+import { isKeyRelease, isShiftCtrlD } from "./keys";
 import type { Terminal } from "./terminal";
 import { getCapabilities, setCellDimensions } from "./terminal-image";
-import { visibleWidth } from "./utils";
+import { extractSegments, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils";
 
 /**
  * Component interface - all components must implement this
@@ -26,6 +26,12 @@ export interface Component {
 	 */
 	handleInput?(data: string): void;
 
+	/**
+	 * If true, component receives key release events (Kitty protocol).
+	 * Default is false - release events are filtered out.
+	 */
+	wantsKeyRelease?: boolean;
+
 	/**
 	 * Optional cursor position within the rendered output (0-based row/col).
 	 */
@@ -105,6 +111,11 @@ export class TUI extends Container {
 	private previousCursor: { row: number; col: number } | null = null;
 	private inputBuffer = ""; // Buffer for parsing terminal responses
 	private cellSizeQueryPending = false;
+	private overlayStack: {
+		component: Component;
+		options?: { row?: number; col?: number; width?: number };
+		preFocus: Component | null;
+	}[] = [];
 	private inputQueue: string[] = []; // Queue input during cell size query to avoid interleaving
 
 	constructor(terminal: Terminal) {
@@ -116,6 +127,32 @@ export class TUI extends Container {
 		this.focusedComponent = component;
 	}
 
+	/** Show an overlay component centered (or at specified position). */
+	showOverlay(component: Component, options?: { row?: number; col?: number; width?: number }): void {
+		this.overlayStack.push({ component, options, preFocus: this.focusedComponent });
+		this.setFocus(component);
+		this.terminal.hideCursor();
+		this.requestRender();
+	}
+
+	/** Hide the topmost overlay and restore previous focus. */
+	hideOverlay(): void {
+		const overlay = this.overlayStack.pop();
+		if (!overlay) return;
+		this.setFocus(overlay.preFocus);
+		if (this.overlayStack.length === 0) this.terminal.hideCursor();
+		this.requestRender();
+	}
+
+	hasOverlay(): boolean {
+		return this.overlayStack.length > 0;
+	}
+
+	override invalidate(): void {
+		super.invalidate();
+		for (const overlay of this.overlayStack) overlay.component.invalidate?.();
+	}
+
 	start(): void {
 		this.terminal.start(
 			(data) => this.handleInput(data),
@@ -230,6 +267,9 @@ export class TUI extends Container {
 		// Pass input to focused component (including Ctrl+C)
 		// The focused component can decide how to handle Ctrl+C
 		if (this.focusedComponent?.handleInput) {
+			if (isKeyRelease(data) && !this.focusedComponent.wantsKeyRelease) {
+				return;
+			}
 			this.focusedComponent.handleInput(data);
 			this.requestRender();
 		}
@@ -282,6 +322,77 @@ export class TUI extends Container {
 		return line.includes("\x1b_G") || line.includes("\x1b]1337;File=");
 	}
 
+	/** Composite all overlays into content lines (in stack order, later = on top). */
+	private compositeOverlays(lines: string[], termWidth: number, termHeight: number): string[] {
+		if (this.overlayStack.length === 0) return lines;
+		const result = [...lines];
+		const viewportStart = Math.max(0, result.length - termHeight);
+
+		for (const { component, options } of this.overlayStack) {
+			const w =
+				options?.width !== undefined
+					? Math.max(1, Math.min(options.width, termWidth - 4))
+					: Math.max(1, Math.min(80, termWidth - 4));
+			const overlayLines = component.render(w);
+			const h = overlayLines.length;
+
+			const row = Math.max(0, Math.min(options?.row ?? Math.floor((termHeight - h) / 2), termHeight - h));
+			const col = Math.max(0, Math.min(options?.col ?? Math.floor((termWidth - w) / 2), termWidth - w));
+
+			for (let i = 0; i < h; i++) {
+				const idx = viewportStart + row + i;
+				if (idx >= 0 && idx < result.length) {
+					result[idx] = this.compositeLineAt(result[idx], overlayLines[i], col, w, termWidth);
+				}
+			}
+		}
+		return result;
+	}
+
+	private static readonly SEGMENT_RESET = "\x1b[0m\x1b]8;;\x07";
+
+	/** Splice overlay content into a base line at a specific column. Single-pass optimized. */
+	private compositeLineAt(
+		baseLine: string,
+		overlayLine: string,
+		startCol: number,
+		overlayWidth: number,
+		totalWidth: number,
+	): string {
+		if (this.containsImage(baseLine)) return baseLine;
+
+		// Single pass through baseLine extracts both before and after segments
+		const afterStart = startCol + overlayWidth;
+		const base = extractSegments(baseLine, startCol, afterStart, totalWidth - afterStart, true);
+
+		// Extract overlay with width tracking
+		const overlay = sliceWithWidth(overlayLine, 0, overlayWidth);
+
+		// Pad segments to target widths
+		const beforePad = Math.max(0, startCol - base.beforeWidth);
+		const overlayPad = Math.max(0, overlayWidth - overlay.width);
+		const actualBeforeWidth = Math.max(startCol, base.beforeWidth);
+		const actualOverlayWidth = Math.max(overlayWidth, overlay.width);
+		const afterTarget = Math.max(0, totalWidth - actualBeforeWidth - actualOverlayWidth);
+		const afterPad = Math.max(0, afterTarget - base.afterWidth);
+
+		// Compose result - widths are tracked so no final visibleWidth check needed
+		const r = TUI.SEGMENT_RESET;
+		const result =
+			base.before +
+			" ".repeat(beforePad) +
+			r +
+			overlay.text +
+			" ".repeat(overlayPad) +
+			r +
+			base.after +
+			" ".repeat(afterPad);
+
+		// Only truncate if wide char at after boundary caused overflow (rare)
+		const resultWidth = actualBeforeWidth + actualOverlayWidth + Math.max(afterTarget, base.afterWidth);
+		return resultWidth <= totalWidth ? result : sliceByColumn(result, 0, totalWidth, true);
+	}
+
 	private doRender(): void {
 		// Capture terminal dimensions at start to ensure consistency throughout render
 		const width = this.terminal.columns;
@@ -290,7 +401,13 @@ export class TUI extends Container {
 		const currentCursorRow = this.cursorRow;
 
 		// Render all components to get new lines
-		const newLines = this.render(width);
+		let newLines = this.render(width);
+
+		// Composite overlays into the rendered lines (before differential compare)
+		if (this.overlayStack.length > 0) {
+			newLines = this.compositeOverlays(newLines, width, height);
+		}
+
 		const cursorInfo = this.getCursorPosition(width);
 
 		// Width changed - need full re-render
@@ -417,7 +534,19 @@ export class TUI extends Container {
 				} catch {
 					// Ignore - crash log is best-effort
 				}
-				throw new Error(`Rendered line ${i} exceeds terminal width. Debug log written to ${crashLogPath}`);
+
+				// Clean up terminal state before throwing
+				this.stop();
+
+				const errorMsg = [
+					`Rendered line ${i} exceeds terminal width (${visibleWidth(line)} > ${width}).`,
+					"",
+					"This is likely caused by a custom TUI component not truncating its output.",
+					"Use visibleWidth() to measure and truncateToWidth() to truncate lines.",
+					"",
+					`Debug log written to: ${crashLogPath}`,
+				].join("\n");
+				throw new Error(errorMsg);
 			}
 			buffer += line;
 		}

package/src/utils.ts

@@ -135,21 +135,31 @@ export function visibleWidth(str: string): number {
 /**
  * Extract ANSI escape sequences from a string at the given position.
  */
-function extractAnsiCode(str: string, pos: number): { code: string; length: number } | null {
-	if (pos >= str.length || str[pos] !== "\x1b" || str[pos + 1] !== "[") {
-		return null;
-	}
+export function extractAnsiCode(str: string, pos: number): { code: string; length: number } | null {
+	if (pos >= str.length || str[pos] !== "\x1b") return null;
+
+	const next = str[pos + 1];
 
-	let j = pos + 2;
-	while (j < str.length && str[j] && !/[mGKHJ]/.test(str[j]!)) {
-		j++;
+	// CSI sequence: ESC [ ... m/G/K/H/J
+	if (next === "[") {
+		let j = pos + 2;
+		while (j < str.length && !/[mGKHJ]/.test(str[j]!)) j++;
+		if (j < str.length) return { code: str.substring(pos, j + 1), length: j + 1 - pos };
+		return null;
 	}
 
-	if (j < str.length) {
-		return {
-			code: str.substring(pos, j + 1),
-			length: j + 1 - pos,
-		};
+	// OSC sequence: ESC ] ... BEL or ESC ] ... ST (ESC \)
+	// Used for hyperlinks (OSC 8), window titles, etc.
+	if (next === "]") {
+		let j = pos + 2;
+		while (j < str.length) {
+			if (str[j] === "\x07") return { code: str.substring(pos, j + 1), length: j + 1 - pos };
+			if (str[j] === "\x1b" && str[j + 1] === "\\") {
+				return { code: str.substring(pos, j + 2), length: j + 2 - pos };
+			}
+			j++;
+		}
+		return null;
 	}
 
 	return null;
@@ -308,6 +318,11 @@ class AnsiCodeTracker {
 		this.bgColor = null;
 	}
 
+	/** Clear all state for reuse. */
+	clear(): void {
+		this.reset();
+	}
+
 	getActiveCodes(): string {
 		const codes: string[] = [];
 		if (this.bold) codes.push("1");
@@ -510,7 +525,7 @@ function wrapSingleLine(line: string, width: number): string[] {
 		const totalNeeded = currentVisibleLength + tokenVisibleLength;
 
 		if (totalNeeded > width && currentVisibleLength > 0) {
-			// Add specific reset for underline only (preserves background)
+			// Trim trailing whitespace, then add underline reset (not full reset, to preserve background)
 			let lineToWrap = currentLine.trimEnd();
 			const lineEndReset = tracker.getLineEndReset();
 			if (lineEndReset) {
@@ -539,7 +554,8 @@ function wrapSingleLine(line: string, width: number): string[] {
 		wrapped.push(currentLine);
 	}
 
-	return wrapped.length > 0 ? wrapped : [""];
+	// Trailing whitespace can cause lines to exceed the requested width
+	return wrapped.length > 0 ? wrapped.map((line) => line.trimEnd()) : [""];
 }
 
 const PUNCTUATION_REGEX = /[(){}[\]<>.,;:'"!?+\-=*/\\|&%^$#@~`]/;
@@ -722,3 +738,140 @@ export function truncateToWidth(text: string, maxWidth: number, ellipsis: string
 	// Add reset code before ellipsis to prevent styling leaking into it
 	return `${result}\x1b[0m${ellipsis}`;
 }
+
+/**
+ * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ * @param strict - If true, exclude wide chars at boundary that would extend past the range
+ */
+export function sliceByColumn(line: string, startCol: number, length: number, strict = false): string {
+	return sliceWithWidth(line, startCol, length, strict).text;
+}
+
+/** Like sliceByColumn but also returns the actual visible width of the result. */
+export function sliceWithWidth(
+	line: string,
+	startCol: number,
+	length: number,
+	strict = false,
+): { text: string; width: number } {
+	if (length <= 0) return { text: "", width: 0 };
+	const endCol = startCol + length;
+	let result = "",
+		resultWidth = 0,
+		currentCol = 0,
+		i = 0,
+		pendingAnsi = "";
+
+	while (i < line.length) {
+		const ansi = extractAnsiCode(line, i);
+		if (ansi) {
+			if (currentCol >= startCol && currentCol < endCol) result += ansi.code;
+			else if (currentCol < startCol) pendingAnsi += ansi.code;
+			i += ansi.length;
+			continue;
+		}
+
+		let textEnd = i;
+		while (textEnd < line.length && !extractAnsiCode(line, textEnd)) textEnd++;
+
+		for (const { segment } of segmenter.segment(line.slice(i, textEnd))) {
+			const w = graphemeWidth(segment);
+			const inRange = currentCol >= startCol && currentCol < endCol;
+			const fits = !strict || currentCol + w <= endCol;
+			if (inRange && fits) {
+				if (pendingAnsi) {
+					result += pendingAnsi;
+					pendingAnsi = "";
+				}
+				result += segment;
+				resultWidth += w;
+			}
+			currentCol += w;
+			if (currentCol >= endCol) break;
+		}
+		i = textEnd;
+		if (currentCol >= endCol) break;
+	}
+	return { text: result, width: resultWidth };
+}
+
+// Pooled tracker instance for extractSegments (avoids allocation per call)
+const pooledStyleTracker = new AnsiCodeTracker();
+
+/**
+ * Extract "before" and "after" segments from a line in a single pass.
+ * Used for overlay compositing where we need content before and after the overlay region.
+ * Preserves styling from before the overlay that should affect content after it.
+ */
+export function extractSegments(
+	line: string,
+	beforeEnd: number,
+	afterStart: number,
+	afterLen: number,
+	strictAfter = false,
+): { before: string; beforeWidth: number; after: string; afterWidth: number } {
+	let before = "",
+		beforeWidth = 0,
+		after = "",
+		afterWidth = 0;
+	let currentCol = 0,
+		i = 0;
+	let pendingAnsiBefore = "";
+	let afterStarted = false;
+	const afterEnd = afterStart + afterLen;
+
+	// Track styling state so "after" inherits styling from before the overlay
+	pooledStyleTracker.clear();
+
+	while (i < line.length) {
+		const ansi = extractAnsiCode(line, i);
+		if (ansi) {
+			// Track all SGR codes to know styling state at afterStart
+			pooledStyleTracker.process(ansi.code);
+			// Include ANSI codes in their respective segments
+			if (currentCol < beforeEnd) {
+				pendingAnsiBefore += ansi.code;
+			} else if (currentCol >= afterStart && currentCol < afterEnd && afterStarted) {
+				// Only include after we've started "after" (styling already prepended)
+				after += ansi.code;
+			}
+			i += ansi.length;
+			continue;
+		}
+
+		let textEnd = i;
+		while (textEnd < line.length && !extractAnsiCode(line, textEnd)) textEnd++;
+
+		for (const { segment } of segmenter.segment(line.slice(i, textEnd))) {
+			const w = graphemeWidth(segment);
+
+			if (currentCol < beforeEnd) {
+				if (pendingAnsiBefore) {
+					before += pendingAnsiBefore;
+					pendingAnsiBefore = "";
+				}
+				before += segment;
+				beforeWidth += w;
+			} else if (currentCol >= afterStart && currentCol < afterEnd) {
+				const fits = !strictAfter || currentCol + w <= afterEnd;
+				if (fits) {
+					// On first "after" grapheme, prepend inherited styling from before overlay
+					if (!afterStarted) {
+						after += pooledStyleTracker.getActiveCodes();
+						afterStarted = true;
+					}
+					after += segment;
+					afterWidth += w;
+				}
+			}
+
+			currentCol += w;
+			// Early exit: done with "before" only, or done with both segments
+			if (afterLen <= 0 ? currentCol >= beforeEnd : currentCol >= afterEnd) break;
+		}
+		i = textEnd;
+		if (afterLen <= 0 ? currentCol >= beforeEnd : currentCol >= afterEnd) break;
+	}
+
+	return { before, beforeWidth, after, afterWidth };
+}