@gajae-code/tui 0.11.3 → 0.11.4

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.11.4] - 2026-07-20
+### Fixed
+
+- Keybinding configuration arrays are now defensively copied so external mutations cannot diverge snapshots from resolved key matches.
+- Supplementary Unicode terminal input now crosses the stdin decoding boundary as complete code points instead of separate UTF-16 surrogate events.
+- Bracketed-paste framing now preserves ordinary input before coalesced or split start markers, retains split end markers byte-for-byte, and reprocesses multiple framed pastes in order instead of dropping command prefixes.
+
 ## [0.11.3] - 2026-07-19
 ### Fixed
 

package/dist/types/bracketed-paste.d.ts

@@ -1,26 +1,20 @@
+export declare const BRACKETED_PASTE_FRAME_TIMEOUT_MS = 1000;
+export declare const BRACKETED_PASTE_FRAME_MAX_BYTES: number;
 export type PasteResult = {
     handled: false;
 } | {
     handled: true;
+    leading: string;
     pasteContent?: string;
     remaining: string;
 };
 /**
- * Handles bracketed paste mode buffering for terminal input components.
- *
- * Bracketed paste mode wraps pasted content between start (\x1b[200~) and
- * end (\x1b[201~) markers, which may arrive split across multiple chunks.
- * This class buffers incoming data and assembles complete paste payloads.
+ * Handles bracketed paste framing with bounded buffering. Leading ordinary
+ * input and split markers are retained byte-for-byte; stale or oversized
+ * incomplete frames are released as ordinary input on the next event.
  */
 export declare class BracketedPasteHandler {
     #private;
-    /**
-     * Process incoming terminal data for bracketed paste sequences.
-     *
-     * @returns `{ handled: false }` if the data contains no paste sequence and
-     *          should be processed normally. `{ handled: true }` if the data was
-     *          consumed by paste buffering — `pasteContent` is set when a complete
-     *          paste has been assembled; omitted when still buffering.
-     */
-    process(data: string): PasteResult;
+    get hasPendingFrame(): boolean;
+    process(data: string, now?: number): PasteResult;
 }

package/package.json

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

package/src/bracketed-paste.ts

@@ -1,47 +1,124 @@
 const PASTE_START = "\x1b[200~";
 const PASTE_END = "\x1b[201~";
 
-export type PasteResult = { handled: false } | { handled: true; pasteContent?: string; remaining: string };
+export const BRACKETED_PASTE_FRAME_TIMEOUT_MS = 1_000;
+export const BRACKETED_PASTE_FRAME_MAX_BYTES = 1024 * 1024;
+
+export type PasteResult =
+	| { handled: false }
+	| { handled: true; leading: string; pasteContent?: string; remaining: string };
+
+function partialStartSuffixLength(value: string): number {
+	const maxLength = Math.min(value.length, PASTE_START.length - 1);
+	for (let length = maxLength; length > 0; length -= 1) {
+		if (value.endsWith(PASTE_START.slice(0, length))) return length;
+	}
+	return 0;
+}
 
 /**
- * Handles bracketed paste mode buffering for terminal input components.
- *
- * Bracketed paste mode wraps pasted content between start (\x1b[200~) and
- * end (\x1b[201~) markers, which may arrive split across multiple chunks.
- * This class buffers incoming data and assembles complete paste payloads.
+ * Handles bracketed paste framing with bounded buffering. Leading ordinary
+ * input and split markers are retained byte-for-byte; stale or oversized
+ * incomplete frames are released as ordinary input on the next event.
  */
 export class BracketedPasteHandler {
 	#buffer = "";
+	#leading = "";
 	#active = false;
+	#pendingSince: number | undefined;
 
-	/**
-	 * Process incoming terminal data for bracketed paste sequences.
-	 *
-	 * @returns `{ handled: false }` if the data contains no paste sequence and
-	 *          should be processed normally. `{ handled: true }` if the data was
-	 *          consumed by paste buffering — `pasteContent` is set when a complete
-	 *          paste has been assembled; omitted when still buffering.
-	 */
-	process(data: string): PasteResult {
-		if (data.includes(PASTE_START)) {
-			this.#active = true;
-			this.#buffer = "";
-			data = data.replace(PASTE_START, "");
-		}
+	get hasPendingFrame(): boolean {
+		return this.#active || this.#buffer.length > 0 || this.#leading.length > 0;
+	}
 
-		if (!this.#active) return { handled: false };
+	#reset(): void {
+		this.#buffer = "";
+		this.#leading = "";
+		this.#active = false;
+		this.#pendingSince = undefined;
+	}
 
-		this.#buffer += data;
+	#flushBuffered(): string {
+		const buffered = this.#active
+			? `${this.#leading}${PASTE_START}${this.#buffer}`
+			: `${this.#leading}${this.#buffer}`;
+		this.#reset();
+		return buffered;
+	}
 
-		const endIndex = this.#buffer.indexOf(PASTE_END);
-		if (endIndex === -1) return { handled: true, remaining: "" };
+	#flushActive(remaining: string): PasteResult {
+		const leading = this.#leading;
+		const pasteContent = this.#buffer;
+		this.#reset();
+		return { handled: true, leading, pasteContent, remaining };
+	}
 
-		const pasteContent = this.#buffer.substring(0, endIndex);
-		const remaining = this.#buffer.substring(endIndex + PASTE_END.length);
+	process(data: string, now = Date.now()): PasteResult {
+		if (
+			this.hasPendingFrame &&
+			this.#pendingSince !== undefined &&
+			now - this.#pendingSince >= BRACKETED_PASTE_FRAME_TIMEOUT_MS
+		) {
+			return this.#active
+				? this.#flushActive(data)
+				: { handled: true, leading: `${this.#flushBuffered()}${data}`, remaining: "" };
+		}
+		if (this.hasPendingFrame && data === "\x1b") {
+			return this.#active
+				? this.#flushActive(data)
+				: { handled: true, leading: `${this.#flushBuffered()}${data}`, remaining: "" };
+		}
 
-		this.#buffer = "";
-		this.#active = false;
+		if (!this.#active) {
+			const hadBufferedInput = this.hasPendingFrame;
+			const combined = this.#buffer + data;
+			this.#buffer = "";
+			const startIndex = combined.indexOf(PASTE_START);
+			if (startIndex === -1) {
+				const partialLength = partialStartSuffixLength(combined);
+				if (partialLength > 0) {
+					const nextLeading = this.#leading + combined.slice(0, -partialLength);
+					const nextBuffer = combined.slice(-partialLength);
+					if (Buffer.byteLength(nextLeading) + Buffer.byteLength(nextBuffer) > BRACKETED_PASTE_FRAME_MAX_BYTES) {
+						this.#reset();
+						return { handled: true, leading: `${nextLeading}${nextBuffer}`, remaining: "" };
+					}
+					this.#leading = nextLeading;
+					this.#buffer = nextBuffer;
+					this.#pendingSince ??= now;
+					return { handled: true, leading: "", remaining: "" };
+				}
+				if (hadBufferedInput || this.#leading.length > 0) {
+					const leading = this.#leading + combined;
+					this.#reset();
+					return { handled: true, leading, remaining: "" };
+				}
+				return { handled: false };
+			}
+
+			this.#leading += combined.slice(0, startIndex);
+			this.#buffer = combined.slice(startIndex + PASTE_START.length);
+			this.#active = true;
+			this.#pendingSince ??= now;
+		} else {
+			this.#buffer += data;
+		}
+
+		const endIndex = this.#buffer.indexOf(PASTE_END);
+		if (endIndex === -1) {
+			if (
+				Buffer.byteLength(this.#leading) + Buffer.byteLength(PASTE_START) + Buffer.byteLength(this.#buffer) >
+				BRACKETED_PASTE_FRAME_MAX_BYTES
+			) {
+				return this.#flushActive("");
+			}
+			return { handled: true, leading: "", remaining: "" };
+		}
 
-		return { handled: true, pasteContent, remaining };
+		const leading = this.#leading;
+		const pasteContent = this.#buffer.slice(0, endIndex);
+		const remaining = this.#buffer.slice(endIndex + PASTE_END.length);
+		this.#reset();
+		return { handled: true, leading, pasteContent, remaining };
 	}
 }

package/src/components/editor.ts

@@ -1142,8 +1142,12 @@ export class Editor implements Component, Focusable {
 		}
 
 		// Handle bracketed paste mode
-		const paste = this.#pasteHandler.process(data);
+		const paste =
+			data === "\x1b" && !this.#pasteHandler.hasPendingFrame
+				? ({ handled: false } as const)
+				: this.#pasteHandler.process(data);
 		if (paste.handled) {
+			if (paste.leading.length > 0) this.handleInput(paste.leading);
 			if (paste.pasteContent !== undefined) {
 				this.#handlePaste(paste.pasteContent);
 				if (paste.remaining.length > 0) {

package/src/components/input.ts

@@ -64,8 +64,12 @@ export class Input implements Component, Focusable {
 
 	handleInput(data: string): void {
 		// Handle bracketed paste mode
-		const paste = this.#pasteHandler.process(data);
+		const paste =
+			data === "\x1b" && !this.#pasteHandler.hasPendingFrame
+				? ({ handled: false } as const)
+				: this.#pasteHandler.process(data);
 		if (paste.handled) {
+			if (paste.leading.length > 0) this.handleInput(paste.leading);
 			if (paste.pasteContent !== undefined) {
 				this.#handlePaste(paste.pasteContent);
 				if (paste.remaining.length > 0) {

package/src/components/secret-input.ts

@@ -90,8 +90,12 @@ export class SecretInput implements Component, Focusable {
 			return;
 		}
 
-		const paste = this.#pasteHandler.process(data);
+		const paste =
+			data === "\x1b" && !this.#pasteHandler.hasPendingFrame
+				? ({ handled: false } as const)
+				: this.#pasteHandler.process(data);
 		if (paste.handled) {
+			if (paste.leading.length > 0) this.handleInput(paste.leading);
 			if (paste.pasteContent !== undefined) {
 				this.#handlePaste(paste.pasteContent);
 				if (paste.remaining.length > 0) {

package/src/keybindings.ts

@@ -187,6 +187,14 @@ function normalizeKeys(keys: KeyId | KeyId[] | undefined): KeyId[] {
 	return result;
 }
 
+function cloneKeybindingsConfig(config: KeybindingsConfig): KeybindingsConfig {
+	const clone: KeybindingsConfig = {};
+	for (const [keybinding, keys] of Object.entries(config)) {
+		clone[keybinding] = Array.isArray(keys) ? [...keys] : keys;
+	}
+	return clone;
+}
+
 export class KeybindingsManager {
 	#definitions: KeybindingDefinitions;
 	#userBindings: KeybindingsConfig;
@@ -195,7 +203,7 @@ export class KeybindingsManager {
 
 	constructor(definitions: KeybindingDefinitions, userBindings: KeybindingsConfig = {}) {
 		this.#definitions = definitions;
-		this.#userBindings = userBindings;
+		this.#userBindings = cloneKeybindingsConfig(userBindings);
 		this.#rebuild();
 	}
 
@@ -253,12 +261,12 @@ export class KeybindingsManager {
 	}
 
 	setUserBindings(userBindings: KeybindingsConfig): void {
-		this.#userBindings = userBindings;
+		this.#userBindings = cloneKeybindingsConfig(userBindings);
 		this.#rebuild();
 	}
 
 	getUserBindings(): KeybindingsConfig {
-		return { ...this.#userBindings };
+		return cloneKeybindingsConfig(this.#userBindings);
 	}
 
 	getResolvedBindings(): KeybindingsConfig {

package/src/stdin-buffer.ts

@@ -35,6 +35,19 @@ export function isSgrMouseSequence(sequence: string): boolean {
 function isSgrMousePrefix(sequence: string): boolean {
 	return sequence.startsWith(`${ESC}[<`);
 }
+function isHighSurrogate(codeUnit: number): boolean {
+	return codeUnit >= 0xd800 && codeUnit <= 0xdbff;
+}
+
+function isLowSurrogate(codeUnit: number): boolean {
+	return codeUnit >= 0xdc00 && codeUnit <= 0xdfff;
+}
+
+function singleCodePoint(sequence: string): number | undefined {
+	const codepoint = sequence.codePointAt(0);
+	if (codepoint === undefined) return undefined;
+	return sequence.length === (codepoint > 0xffff ? 2 : 1) ? codepoint : undefined;
+}
 
 function isUtf8LeadByte(byte: number): boolean {
 	return byte >= 0xc2 && byte <= 0xf4;
@@ -114,9 +127,9 @@ function isCompleteSequence(data: string): "complete" | "incomplete" | "not-esca
 		return afterEsc.length >= 2 ? "complete" : "incomplete";
 	}
 
-	// Meta key sequences: ESC followed by a single character
+	// Meta key sequences: ESC followed by a single Unicode code point
 	if (afterEsc.length === 1) {
-		return "complete";
+		return isHighSurrogate(afterEsc.charCodeAt(0)) ? "incomplete" : "complete";
 	}
 
 	// Unknown escape sequence - treat as complete
@@ -234,6 +247,18 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 
 		// Try to extract a sequence starting at this position
 		if (remaining.startsWith(ESC)) {
+			// A split Meta + supplementary code point stays buffered after its high
+			// surrogate. If the next code unit cannot complete that pair, flush the
+			// malformed Meta sequence without consuming the following input.
+			if (
+				remaining.length >= 3 &&
+				isHighSurrogate(remaining.charCodeAt(1)) &&
+				!isLowSurrogate(remaining.charCodeAt(2))
+			) {
+				sequences.push(remaining.slice(0, 2));
+				pos += 2;
+				continue;
+			}
 			// Find the end of this escape sequence
 			let seqEnd = 1;
 			while (seqEnd <= remaining.length) {
@@ -258,7 +283,19 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 				return { sequences, remainder: remaining };
 			}
 		} else {
-			// Not an escape sequence - take a single character
+			// Not an escape sequence - take a single Unicode code point. Keep a
+			// trailing high surrogate buffered so a following string chunk can
+			// complete it.
+			const firstCodeUnit = remaining.charCodeAt(0);
+			if (isHighSurrogate(firstCodeUnit)) {
+				if (remaining.length === 1) return { sequences, remainder: remaining };
+				const secondCodeUnit = remaining.charCodeAt(1);
+				if (isLowSurrogate(secondCodeUnit)) {
+					sequences.push(remaining.slice(0, 2));
+					pos += 2;
+					continue;
+				}
+			}
 			sequences.push(remaining[0]!);
 			pos++;
 		}
@@ -552,7 +589,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		return legacyMetaSequence(byte);
 	}
 	#emitDataSequence(sequence: string): void {
-		const rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;
+		const rawCodepoint = singleCodePoint(sequence);
 		if (rawCodepoint !== undefined && rawCodepoint === this.#pendingKittyPrintableCodepoint) {
 			this.#pendingKittyPrintableCodepoint = undefined;
 			return;