@gajae-code/tui 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.13.2] - 2026-08-13
+
+### Fixed
+
+- A fast double-Esc (or triple-Esc) whose ESC bytes coalesce into one stdin chunk — which tmux always produces within its escape-time window, and SSH batching produces routinely — is now emitted as individual Escape key presses instead of a single `"\x1b\x1b"` sequence that parsed as the unbound `alt+escape` and silently swallowed both presses. This restores the double-Esc draft-clear and double-Esc selector gestures under tmux/SSH. Option-as-Meta sequences with a real continuation (e.g. Option+Up as `ESC ESC [ A`) remain atomic, and an ESC-cancelled incomplete sequence is still emitted whole.
+- An ambiguous trailing run of Escape bytes now stays buffered until a continuation or the flush timeout resolves it, so `ESC ESC ESC` followed by `[A` in the next chunk still decodes as Escape then `alt+up` instead of two Escapes plus a plain Up that fired the destructive double-Escape gesture.
+- Escape presses immediately followed by a bracketed paste in the same read are now emitted as individual Escape presses instead of one coalesced sequence that parsed as the unbound `alt+escape` and swallowed every press.
+- A long run of Escape bytes arriving as many small reads no longer rescans the accumulated buffer on every read; only the two-byte ambiguous tail stays buffered, so 50,000 byte-by-byte Escape reads cost 50ms instead of 2.4s.
+- A long run of Escape bytes followed by another key now decodes in linear time instead of rescanning the remaining input on every step, which blocked the event loop for over a second on a 50,000-byte run.
+- Apple Terminal.app now retains its default keyboard mode when it does not support the Kitty keyboard protocol, avoiding the modifyOtherKeys fallback that breaks Korean/Hangul IME composition.
+
+## [0.13.1] - 2026-08-11
+
 ### Added
 
 - Added atomic same-line deletion APIs and an `Editor` undo callback for keeping application state synchronized with editor history.
@@ -10,6 +23,8 @@
 - macOS Terminal.app Option+Arrow input is now buffered and decoded as a single Meta-wrapped escape sequence, so Option+Up/Down can open and navigate queued-message selectors.
 - Terminal.app Meta-prefix decoding now covers legacy Option shortcuts for printable symbols, digits, spaces, and Ctrl+Option symbol chords while preserving enhanced Kitty and modifyOtherKeys Super/Command matching.
 - Kitty and modifyOtherKeys function-key sequences now match consistently for F1–F12, including unmodified CSI forms.
+- Kitty protocol release/repeat and modifyOtherKeys lock-mask handling now fail closed and stay symmetric across native and TypeScript key matching, including duplicate macOS modifier aliases.
+- TypeScript Kitty and modifyOtherKeys printable decoding now rejects surrogate and out-of-range Unicode code points before text extraction.
 
 ## [0.12.21] - 2026-08-09
 
@@ -26,6 +41,7 @@
 ### Changed
 
 - Native fuzzy matching and image encoding bindings now load only when their TUI feature is used instead of at module startup.
+- Kitty-protocol shortcuts can match modified Korean Dubeolsik compatibility-jamo input when terminals omit base-layout metadata, without treating unmodified or Shift-only text input as shortcuts.
 
 ### Fixed
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.13.0",
+	"version": "0.13.2",
 	"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.13.0",
-		"@gajae-code/utils": "0.13.0",
+		"@gajae-code/natives": "0.13.2",
+		"@gajae-code/utils": "0.13.2",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/keys.ts

@@ -301,7 +301,7 @@ export function parseKeyId(value: string): ParsedKeyId | undefined {
 					.map(part => part.trim());
 	const modifiers: KeyModifier[] = [];
 	for (const part of modifierParts) {
-		const modifier = KEY_MODIFIER_ALIASES[part];
+		const modifier = Object.hasOwn(KEY_MODIFIER_ALIASES, part) ? KEY_MODIFIER_ALIASES[part] : undefined;
 		if (!modifier || modifiers.includes(modifier)) return undefined;
 		modifiers.push(modifier);
 	}
@@ -427,9 +427,9 @@ interface ParsedKittySequence {
 
 // Regex for Kitty protocol event type detection
 // Matches CSI sequences with :2 (repeat) or :3 (release) event type
-// Format: \x1b[...;modifier:event_type<terminator> where terminator is u, ~, or A-F/H
-const KITTY_RELEASE_PATTERN = /^\x1b\[[\d:;]*:3[u~ABCDHF]$/;
-const KITTY_REPEAT_PATTERN = /^\x1b\[[\d:;]*:2[u~ABCDHF]$/;
+// Format: \x1b[...;modifier:event_type<terminator> where terminator is u, ~, navigation, or function-key finals
+const KITTY_RELEASE_PATTERN = /^\x1b\[[\d:;]*:3[u~ABCDEFHPQRS]$/;
+const KITTY_REPEAT_PATTERN = /^\x1b\[[\d:;]*:2[u~ABCDEFHPQRS]$/;
 const KITTY_CSI_U_PATTERN = /^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?(?:;([\d:]*))?u$/;
 const KITTY_MOD_SHIFT = 1;
 const KITTY_MOD_ALT = 2;
@@ -437,6 +437,77 @@ const KITTY_MOD_CTRL = 4;
 const KITTY_MOD_SUPER = 8;
 const KITTY_MOD_NUM_LOCK = 128;
 const KITTY_LOCK_MASK = 64 + 128; // Caps Lock + Num Lock
+const KOREAN_DUBEOLSIK_BASE_KEYS = new Map<number, BaseKey>(
+	[
+		["ㄱ", "r"],
+		["ㄲ", "r"],
+		["ㄴ", "s"],
+		["ㄷ", "e"],
+		["ㄸ", "e"],
+		["ㄹ", "f"],
+		["ㅁ", "a"],
+		["ㅂ", "q"],
+		["ㅃ", "q"],
+		["ㅅ", "t"],
+		["ㅆ", "t"],
+		["ㅇ", "d"],
+		["ㅈ", "w"],
+		["ㅉ", "w"],
+		["ㅊ", "c"],
+		["ㅋ", "z"],
+		["ㅌ", "x"],
+		["ㅍ", "v"],
+		["ㅎ", "g"],
+		["ㅏ", "k"],
+		["ㅐ", "o"],
+		["ㅑ", "i"],
+		["ㅒ", "o"],
+		["ㅓ", "j"],
+		["ㅔ", "p"],
+		["ㅕ", "u"],
+		["ㅖ", "p"],
+		["ㅗ", "h"],
+		["ㅛ", "y"],
+		["ㅜ", "n"],
+		["ㅠ", "b"],
+		["ㅡ", "m"],
+		["ㅣ", "l"],
+	].map(([character, key]) => [character.codePointAt(0)!, key as BaseKey]),
+);
+
+function matchesKoreanDubeolsikKittySequence(data: string, keyId: KeyId): boolean {
+	const event = parseKittySequence(data);
+	if (!event || event.eventType === 3 || event.baseLayoutKey !== undefined) return false;
+
+	const baseKey = KOREAN_DUBEOLSIK_BASE_KEYS.get(event.codepoint);
+	if (!baseKey) return false;
+
+	const expected = parseKeyId(keyId);
+	if (
+		!expected?.modifiers.some(modifier => modifier === "alt" || modifier === "ctrl" || modifier === "super") ||
+		expected.baseKey !== baseKey
+	)
+		return false;
+
+	let expectedModifier = 0;
+	for (const modifier of expected.modifiers) {
+		switch (modifier) {
+			case "shift":
+				expectedModifier |= KITTY_MOD_SHIFT;
+				break;
+			case "alt":
+				expectedModifier |= KITTY_MOD_ALT;
+				break;
+			case "ctrl":
+				expectedModifier |= KITTY_MOD_CTRL;
+				break;
+			case "super":
+				expectedModifier |= KITTY_MOD_SUPER;
+				break;
+		}
+	}
+	return (event.modifier & ~KITTY_LOCK_MASK) === expectedModifier;
+}
 const MODIFY_OTHER_KEYS_PATTERN = /^\x1b\[27;(\d+);(\d+)~$/;
 const KITTY_KEYPAD_OPERATOR_TEXT: Record<number, string> = {
 	57410: "/",
@@ -517,18 +588,37 @@ function hasControlChars(data: string): boolean {
 	});
 }
 
+function isValidProtocolNumber(value: number): boolean {
+	return Number.isSafeInteger(value) && value >= 0 && value <= 0xffffffff;
+}
+
+function isPrintableCodePoint(value: number): boolean {
+	return (
+		Number.isSafeInteger(value) &&
+		value >= 32 &&
+		value <= 0x10ffff &&
+		value !== 0x7f &&
+		!(value >= 0x80 && value <= 0x9f) &&
+		!(value >= 0xd800 && value <= 0xdfff)
+	);
+}
+
 function decodeKittyPrintable(data: string): string | undefined {
 	const match = data.match(KITTY_CSI_U_PATTERN);
 	if (!match) return undefined;
 
 	const codepoint = Number.parseInt(match[1] ?? "", 10);
-	if (!Number.isFinite(codepoint)) return undefined;
+	if (!isValidProtocolNumber(codepoint)) return undefined;
 
-	if (match[5] === "3") return undefined;
+	const eventTypeText = match[5];
+	const eventType =
+		eventTypeText === undefined || eventTypeText.length === 0 ? undefined : Number.parseInt(eventTypeText, 10);
+	if (eventType !== undefined && eventType !== 1 && eventType !== 2) return undefined;
 
 	const shiftedKey = match[2] && match[2].length > 0 ? Number.parseInt(match[2], 10) : undefined;
 	const modValue = match[4] ? Number.parseInt(match[4], 10) : 1;
-	const modifier = Number.isFinite(modValue) ? modValue - 1 : 0;
+	if (!isValidProtocolNumber(modValue) || modValue < 1) return undefined;
+	const modifier = modValue - 1;
 	const effectiveMod = modifier & ~KITTY_LOCK_MASK;
 	const supportedModifierMask = KITTY_MOD_SHIFT | KITTY_MOD_ALT | KITTY_MOD_CTRL | KITTY_MOD_SUPER;
 
@@ -541,7 +631,7 @@ function decodeKittyPrintable(data: string): string | undefined {
 			.split(":")
 			.filter(Boolean)
 			.map(value => Number.parseInt(value, 10))
-			.filter(value => Number.isFinite(value) && value >= 32);
+			.filter(value => isPrintableCodePoint(value));
 		if (codepoints.length > 0) {
 			try {
 				return String.fromCodePoint(...codepoints);
@@ -549,6 +639,7 @@ function decodeKittyPrintable(data: string): string | undefined {
 				return undefined;
 			}
 		}
+		return undefined;
 	}
 	const keypadOperatorText = KITTY_KEYPAD_OPERATOR_TEXT[codepoint];
 	if (keypadOperatorText) return keypadOperatorText;
@@ -567,7 +658,7 @@ function decodeKittyPrintable(data: string): string | undefined {
 		return undefined;
 	}
 
-	if (!Number.isFinite(effectiveCodepoint) || effectiveCodepoint < 32) return undefined;
+	if (!isPrintableCodePoint(effectiveCodepoint)) return undefined;
 
 	try {
 		return String.fromCodePoint(effectiveCodepoint);
@@ -584,7 +675,7 @@ function decodeKittyPrintable(data: string): string | undefined {
  */
 export function extractPrintableText(data: string): string | undefined {
 	const printable = decodePrintableKey(data);
-	if (printable !== undefined) return printable;
+	if (printable !== undefined && !hasControlChars(printable)) return printable;
 	if (data.length === 0 || hasControlChars(data)) return undefined;
 	return data;
 }
@@ -603,7 +694,7 @@ function parseModifyOtherKeysSequence(data: string): ParsedModifyOtherKeysSequen
 	if (!match) return null;
 	const modValue = Number.parseInt(match[1] ?? "", 10);
 	const codepoint = Number.parseInt(match[2] ?? "", 10);
-	if (!Number.isFinite(modValue) || !Number.isFinite(codepoint)) return null;
+	if (!isValidProtocolNumber(modValue) || modValue < 1 || !isValidProtocolNumber(codepoint)) return null;
 	return { codepoint, modifier: modValue - 1 };
 }
 
@@ -618,7 +709,7 @@ function decodeModifyOtherKeysPrintable(data: string): string | undefined {
 	if (!parsed) return undefined;
 	const modifier = parsed.modifier & ~KITTY_LOCK_MASK;
 	if ((modifier & ~KITTY_MOD_SHIFT) !== 0) return undefined;
-	if (!Number.isFinite(parsed.codepoint) || parsed.codepoint < 32) return undefined;
+	if (!isPrintableCodePoint(parsed.codepoint)) return undefined;
 	try {
 		return String.fromCodePoint(parsed.codepoint);
 	} catch {
@@ -653,7 +744,10 @@ export function decodePrintableKey(data: string): string | undefined {
  * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
  */
 export function matchesKey(data: string, keyId: KeyId): boolean {
-	return nativeKeys().matchesKey(data, keyId, kittyProtocolActive);
+	return (
+		nativeKeys().matchesKey(data, keyId, kittyProtocolActive) ||
+		(kittyProtocolActive && matchesKoreanDubeolsikKittySequence(data, keyId))
+	);
 }
 
 /**

package/src/stdin-buffer.ts

@@ -278,12 +278,33 @@ function continuesAsStringTerminator(remaining: string, index: number): boolean
 	return afterEsc === undefined || afterEsc === "\\";
 }
 
-function extractCompleteSequences(buffer: string): { sequences: string[]; remainder: string } {
+/**
+ * A buffered run of nothing but ESC bytes is N real Escape key presses, not an
+ * Option-as-Meta prefix. Emitting the run as one sequence parses as the unbound
+ * `alt+escape` and silently swallows every press, so any path that gives up on a
+ * continuation must split the run first.
+ */
+function splitResolvedEscapeRun(buffer: string): string[] {
+	return /^\x1b{2,}$/.test(buffer) ? buffer.split("") : [buffer];
+}
+
+/**
+ * `knownEscapeRunLength` is the number of leading ESC bytes a previous call
+ * already measured and returned as an all-Escape remainder. Resuming the scan
+ * there keeps a run delivered across many small reads linear overall instead of
+ * re-walking the whole accumulated prefix on every chunk.
+ */
+function extractCompleteSequences(
+	buffer: string,
+	knownEscapeRunLength = 0,
+): { sequences: string[]; remainder: string; escapeRunRemainder: number } {
 	const sequences: string[] = [];
 	let pos = 0;
 
 	while (pos < buffer.length) {
-		const remaining = buffer.slice(pos);
+		// Slicing at 0 would copy the whole buffer on every call, which is the
+		// dominant cost when a long Escape run arrives as many single-byte reads.
+		const remaining = pos === 0 ? buffer : buffer.slice(pos);
 
 		// Try to extract a sequence starting at this position
 		if (remaining.startsWith(ESC)) {
@@ -299,6 +320,37 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 				pos += 2;
 				continue;
 			}
+			// Measure the ESC run once. Testing the whole suffix on every iteration
+			// while the cut below advances only two bytes made a long run quadratic.
+			let runLength = pos === 0 ? Math.max(knownEscapeRunLength, 1) : 1;
+			while (runLength < remaining.length && remaining[runLength] === ESC) runLength++;
+			// A trailing run of nothing but ESC bytes is ambiguous: the next chunk
+			// may still deliver the continuation that turns its last ESC into a Meta
+			// prefix (ESC ESC ESC + "[A" is bare Escape then Option+Up). Splitting it
+			// now would emit an extra Escape and downgrade the wrapped key to a plain
+			// one, firing the destructive double-Escape gesture. Keep the whole run
+			// buffered; the flush timeout emits it as individual Escape presses.
+			if (runLength === remaining.length) {
+				// Only the last two bytes of the run are still ambiguous: a Meta prefix
+				// is at most ESC ESC, so any earlier ESC is already a settled press.
+				// Emitting them now keeps the retained buffer bounded; holding the whole
+				// run made every later read rescan it, which is quadratic for a long run
+				// delivered as many small chunks. Order of emitted presses is unchanged.
+				const settled = runLength - 2;
+				if (settled > 0) {
+					for (let index = 0; index < settled; index++) sequences.push(ESC);
+					return { sequences, remainder: remaining.slice(settled), escapeRunRemainder: 2 };
+				}
+				return { sequences, remainder: remaining, escapeRunRemainder: runLength };
+			}
+			// Only the final two ESC bytes can still form a Meta prefix for the
+			// continuation that follows the run; everything before them is a settled
+			// Escape press. Emitting them in one step keeps the walk linear.
+			if (runLength > 2) {
+				for (let index = 0; index < runLength - 2; index++) sequences.push(ESC);
+				pos += runLength - 2;
+				continue;
+			}
 			// Find the end of this escape sequence
 			let seqEnd = 1;
 			while (seqEnd <= remaining.length) {
@@ -315,7 +367,23 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 					// here keeps an unterminated sequence from swallowing the next key.
 					// seqEnd === 1 is excluded so Meta sequences (ESC ESC) still parse.
 					if (remaining[seqEnd] === ESC && seqEnd >= 2 && !continuesAsStringTerminator(remaining, seqEnd)) {
-						sequences.push(candidate);
+						// A bare Escape may be followed in the same read by a Meta-wrapped
+						// sequence (ESC ESC ESC [ A). Keep the final Meta prefix intact;
+						// splitting all three ESC bytes would turn the wrapped arrow into a
+						// plain arrow after a destructive double-Escape gesture.
+						const trailing = remaining.slice(seqEnd);
+						if (/^\x1b+$/.test(candidate) && /^\x1b[^\x1b]/.test(trailing)) {
+							sequences.push(...candidate.slice(0, -1).split(""));
+							pos += seqEnd - 1;
+							break;
+						}
+						// A cut candidate of nothing but ESC bytes is real Escape key
+						// presses, not an Option-as-Meta prefix: a following ESC proves
+						// no continuation (like "[A") belongs to it. Emitting the pair
+						// as one sequence would parse as the unbound "alt+escape" and
+						// silently swallow both presses.
+						if (/^\x1b+$/.test(candidate)) sequences.push(...candidate.split(""));
+						else sequences.push(candidate);
 						pos += seqEnd;
 						break;
 					}
@@ -329,7 +397,7 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 			}
 
 			if (seqEnd > remaining.length) {
-				return { sequences, remainder: remaining };
+				return { sequences, remainder: remaining, escapeRunRemainder: 0 };
 			}
 		} else {
 			// Not an escape sequence - take a single Unicode code point. Keep a
@@ -337,7 +405,7 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 			// complete it.
 			const firstCodeUnit = remaining.charCodeAt(0);
 			if (isHighSurrogate(firstCodeUnit)) {
-				if (remaining.length === 1) return { sequences, remainder: remaining };
+				if (remaining.length === 1) return { sequences, remainder: remaining, escapeRunRemainder: 0 };
 				const secondCodeUnit = remaining.charCodeAt(1);
 				if (isLowSurrogate(secondCodeUnit)) {
 					sequences.push(remaining.slice(0, 2));
@@ -350,7 +418,7 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 		}
 	}
 
-	return { sequences, remainder: "" };
+	return { sequences, remainder: "", escapeRunRemainder: 0 };
 }
 
 export type StdinBufferOptions = {
@@ -379,6 +447,9 @@ export type StdinBufferEventMap = {
  */
 export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	#buffer: string = "";
+	// Length of the leading all-Escape run already measured in #buffer, so a run
+	// arriving as many small reads is scanned once overall instead of per chunk.
+	#bufferedEscapeRunLength = 0;
 	#timeout?: NodeJS.Timeout;
 	readonly #timeoutMs: number;
 	#pasteMode: boolean = false;
@@ -486,6 +557,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		if (this.#pasteMode) {
 			this.#pasteBuffer += this.#buffer;
 			this.#buffer = "";
+			this.#bufferedEscapeRunLength = 0;
 
 			const endIndex = this.#pasteBuffer.indexOf(BRACKETED_PASTE_END);
 			if (endIndex !== -1) {
@@ -505,7 +577,11 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			return;
 		}
 
-		const startIndex = this.#buffer.indexOf(BRACKETED_PASTE_START);
+		// A known all-Escape prefix cannot contain the paste introducer, so start
+		// the scan just far enough back to catch a marker straddling the boundary.
+		// Rescanning the whole retained run on every read made a long run quadratic.
+		const pasteScanFrom = Math.max(0, this.#bufferedEscapeRunLength - BRACKETED_PASTE_START.length);
+		const startIndex = this.#buffer.indexOf(BRACKETED_PASTE_START, pasteScanFrom);
 		if (startIndex !== -1) {
 			if (startIndex > 0) {
 				const beforePaste = this.#buffer.slice(0, startIndex);
@@ -513,8 +589,12 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 				for (const sequence of result.sequences) {
 					this.#emitDataSequence(sequence);
 				}
+				// A bracketed paste start proves no Meta continuation is coming for a
+				// buffered Escape run, so resolve it into individual presses here too.
 				if (result.remainder.length > 0) {
-					this.#emitDataSequence(result.remainder);
+					for (const sequence of splitResolvedEscapeRun(result.remainder)) {
+						this.#emitDataSequence(sequence);
+					}
 				}
 			}
 
@@ -523,6 +603,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			this.#pasteMode = true;
 			this.#pasteBuffer = this.#buffer;
 			this.#buffer = "";
+			this.#bufferedEscapeRunLength = 0;
 
 			const endIndex = this.#pasteBuffer.indexOf(BRACKETED_PASTE_END);
 			if (endIndex !== -1) {
@@ -542,8 +623,11 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			return;
 		}
 
-		const result = extractCompleteSequences(this.#buffer);
+		const result = extractCompleteSequences(this.#buffer, this.#bufferedEscapeRunLength);
 		this.#buffer = result.remainder;
+		// Remember an all-Escape remainder so the next chunk resumes the run scan
+		// at its end rather than re-walking every byte received so far.
+		this.#bufferedEscapeRunLength = result.escapeRunRemainder;
 
 		for (const sequence of result.sequences) {
 			if (isSgrMousePrefix(sequence) && !isSgrMouseSequence(sequence)) continue;
@@ -574,11 +658,13 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			}
 			const remainder = suffix.slice(index);
 			this.#buffer = "";
+			this.#bufferedEscapeRunLength = 0;
 			this.#pendingKittyPrintableCodepoint = undefined;
 			if (remainder) this.process(remainder);
 			return;
 		}
 		this.#buffer = "";
+		this.#bufferedEscapeRunLength = 0;
 		this.#pendingKittyPrintableCodepoint = undefined;
 		this.#sgrQuarantine = true;
 		this.#sgrQuarantineBytes = suffix.length;
@@ -709,12 +795,23 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 
 		if (isSgrMousePrefix(this.#buffer)) {
 			this.#buffer = "";
+			this.#bufferedEscapeRunLength = 0;
 			this.#pendingKittyPrintableCodepoint = undefined;
 			return pendingMeta === undefined ? [] : [pendingMeta];
 		}
 
-		const sequences = pendingMeta === undefined ? [this.#buffer] : [pendingMeta, this.#buffer];
+		// A buffer of nothing but ESC bytes at flush time is N real Escape key
+		// presses that arrived faster than the flush window (tmux forwards a
+		// quick double-Esc as one "\x1b\x1b" chunk within escape-time). Keeping
+		// the pair atomic is only correct while a continuation can still turn it
+		// into an Option-as-Meta sequence (ESC ESC [ A); once the flush timeout
+		// fires, no continuation is coming, and emitting the pair as one
+		// sequence parses as the unbound "alt+escape" — silently swallowing
+		// both presses and breaking the double-Esc draft-clear gesture.
+		const flushedBuffer = splitResolvedEscapeRun(this.#buffer);
+		const sequences = pendingMeta === undefined ? flushedBuffer : [pendingMeta, ...flushedBuffer];
 		this.#buffer = "";
+		this.#bufferedEscapeRunLength = 0;
 		this.#pendingKittyPrintableCodepoint = undefined;
 		return sequences;
 	}
@@ -725,6 +822,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			this.#timeout = undefined;
 		}
 		this.#buffer = "";
+		this.#bufferedEscapeRunLength = 0;
 		this.#pasteMode = false;
 		this.#pasteBuffer = "";
 		this.#pendingKittyPrintableCodepoint = undefined;

package/src/terminal.ts

@@ -51,6 +51,10 @@ export function keyboardEnhancementEnabled(): boolean {
 	return $flag("GJC_TUI_KEYBOARD_PROTOCOL", true);
 }
 
+function isAppleTerminal(): boolean {
+	return $env.TERM_PROGRAM === "Apple_Terminal";
+}
+
 /**
  * Minimal terminal interface for TUI
  */
@@ -794,18 +798,18 @@ export class ProcessTerminal implements Terminal {
 		}
 		this.#safeWrite("\x1b[?u");
 		this.#stdinBuffer?.noteProbeIssued();
-		// Windows Terminal and conhost do not implement the Kitty keyboard
+		// Windows Terminal and Apple Terminal do not implement the Kitty keyboard
 		// protocol, so the query above never activates it there. They do honor the
-		// modifyOtherKeys fallback below — but that mode breaks Windows CJK/Hangul
-		// IME composition: Alt+Enter (and other chords) bypass the IME commit, so
-		// the syllable still being composed is never delivered to the app and the
+		// modifyOtherKeys fallback below — but that mode breaks CJK/Hangul IME
+		// composition: Alt+Enter (and other chords) bypass the IME commit, so the
+		// syllable still being composed is never delivered to the app and the
 		// action fires on empty text (e.g. queue-message no-ops unless the user
 		// types a trailing space to force a commit first). Skip the fallback on
-		// win32; legacy encodings still deliver Alt+Enter (ESC CR) and the newline
-		// chords, and IME composition works again. Opt back in with
+		// these terminals; legacy encodings still deliver Alt+Enter (ESC CR) and
+		// the newline chords, and IME composition works again. Opt back in with
 		// GJC_TUI_KEYBOARD_PROTOCOL=0 disabling all enhancement, or force-enable
-		// elsewhere if a Kitty-capable Windows terminal appears.
-		if (process.platform === "win32") {
+		// elsewhere if a Kitty-capable terminal appears.
+		if (process.platform === "win32" || isAppleTerminal()) {
 			return;
 		}
 		this.#modifyOtherKeysTimeout = setTimeout(() => {