@gajae-code/tui 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [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 +12,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 +30,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.1",
 	"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.1",
+		"@gajae-code/utils": "0.13.1",
 		"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))
+	);
 }
 
 /**