@linxiraos/pi-tui 1.0.0

package/src/stdin-buffer.ts

@@ -0,0 +1,781 @@
+/**
+ * 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 "events";
+import { isKittyProtocolActive } from "./keys";
+
+const ESC = "\x1b";
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+// Paste-mode recovery bounds: a lost/corrupted end marker (ssh/tmux
+// truncation) must not hang input forever or grow memory unboundedly.
+const PASTE_INACTIVITY_TIMEOUT_MS = 1000;
+const PASTE_MAX_BYTES = 64 * 1024 * 1024;
+// A buggy double-report (CSI-u event plus the bare printable for the same
+// keypress) arrives in the same terminal write; a bare char that shows up
+// later than this window is a real keystroke and must not be swallowed.
+const KITTY_PRINTABLE_DEDUP_WINDOW_MS = 25;
+// An SGR mouse report prefix is unambiguous: no keyboard sequence starts with
+// `\x1b[<`, so a buffer still matching this is always the head of a split
+// mouse report. Flushing it on timeout would deliver the tail as literal
+// typed text to whatever component is focused (fullscreen overlays enable
+// any-motion tracking, so report floods plus render stalls make the split
+// routine — see the settings search leaking `[<35;8;16M`).
+const SGR_MOUSE_PARTIAL = /^\x1b\[<[\d;]*$/;
+// Upper bound on how long an unambiguous partial is held past the flush
+// timeout before being delivered raw anyway (terminal died mid-sequence).
+// This is also the worst-case added latency for a partial that never
+// completes (e.g. a bare ESC delivered while the kitty-active flag is
+// stale); keep it small.
+const PARTIAL_HOLD_MAX_MS = 150;
+// Escape-sequence length caps. `resolveEscapeEnd` scans within these bounds
+// only, so a malformed CSI (missing final byte in `0x40-0x7E`) or a
+// terminator-less OSC/DCS/APC cannot force `extractCompleteSequences` to
+// re-inspect a growing prefix on every `process()` call — a single call
+// stays bounded work, and a streamed run of garbage bytes is flushed as
+// raw sequences instead of accumulated forever (issue #4073 case A).
+//
+// CSI is intentionally tight: real CSI keys, mouse reports, and DECRQM
+// replies are always well under 4 KiB. OSC/DCS/APC allow much larger
+// payloads (kitty OSC 5522 clipboard reads, Sixel DCS, kitty graphics APC),
+// so the string-terminator cap is generous.
+const MAX_CSI_BYTES = 4096;
+const MAX_STRING_SEQ_BYTES = 16 * 1024 * 1024;
+
+// SGR mouse report bodies live between `<` and the terminating `M`/`m`.
+// Matched only when the trailing byte is a valid terminator, so the regex
+// runs at most once per resolved report — never inside the growth loop.
+const SGR_MOUSE_COMPLETE = /^<\d+;\d+;\d+[Mm]$/;
+
+// Raw-paste classification holds CR/LF-bearing, ESC-free input briefly so
+// adjacent stdin reads from one unmarked paste can be considered together.
+// Fixed from the first break-bearing read (not an inactivity debounce): normal
+// Enter latency and candidate memory remain bounded even under a continuous
+// stream. Ten milliseconds spans adjacent PTY reads without becoming perceptible.
+const RAW_PASTE_CLASSIFICATION_TIMEOUT_MS = 10;
+
+/**
+ * Whether `text` has two completed logical line breaks (three line segments).
+ *
+ * A single Enter may be batched with surrounding keystrokes in one stdin read,
+ * so one break is ambiguous and must stay on the key path. CRLF counts as one
+ * logical break. Content after the second break completes the third segment;
+ * until then the classification window keeps buffering.
+ */
+function isRawMultilineBurst(text: string): boolean {
+	let breaks = 0;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		if (code === 0x0d) {
+			breaks++;
+			if (text.charCodeAt(i + 1) === 0x0a) i++;
+			continue;
+		}
+		if (code === 0x0a) {
+			breaks++;
+			continue;
+		}
+		if (breaks >= 2) return true;
+	}
+	return false;
+}
+
+/**
+ * Resolve the exclusive-end index of the escape sequence starting at `pos`
+ * (`buffer.charCodeAt(pos)` must be ESC). `resumeSearchFrom` is honored only
+ * for OSC/DCS/APC — it lets a chunked payload skip the prefix that a prior
+ * `process()` call already searched, so a large OSC 5522 image paste stays
+ * O(total) instead of O(total²).
+ *
+ * Meta-ESC (`\x1b\x1b…`) is not resolved here; the outer loop handles the
+ * disambiguation shared with the flush timer and the SGR mouse split. This
+ * helper returns -1 when the first byte after ESC is another ESC.
+ *
+ * Return codes:
+ *   `end > pos`  — complete sequence, exclusive end index.
+ *   `-1`         — incomplete, still under the per-type cap; buffer for more.
+ *   `-2`         — incomplete and the prefix already spans the per-type cap;
+ *                  the caller flushes it as raw bytes to guarantee progress.
+ */
+function resolveEscapeEnd(buffer: string, pos: number, length: number, resumeSearchFrom: number): number {
+	if (pos + 1 >= length) return -1;
+	const next = buffer.charCodeAt(pos + 1);
+
+	switch (next) {
+		case 0x1b /* ESC */:
+			// Meta-ESC handled by the caller.
+			return -1;
+		case 0x5b /* [ */:
+			{
+				// CSI: ESC [ ... final byte in 0x40-0x7E.
+				if (pos + 2 >= length) return -1;
+				// Old-style X10 mouse: ESC [ M + 3 arbitrary bytes.
+				if (buffer.charCodeAt(pos + 2) === 0x4d /* M */) {
+					if (pos + 6 <= length) return pos + 6;
+					// Fewer than 6 bytes buffered is always under MAX_CSI_BYTES,
+					// so this is a plain "wait for more", never a cap flush.
+					return -1;
+				}
+				const capEnd = Math.min(length, pos + MAX_CSI_BYTES);
+				const isSgrMouse = buffer.charCodeAt(pos + 2) === 0x3c /* < */;
+				// No resume hint for CSI: `extractCompleteSequences` records
+				// hints only for OSC/DCS/APC. A partial CSI rescans from its
+				// head, bounded by the tight MAX_CSI_BYTES cap.
+				let i = pos + 2;
+				while (i < capEnd) {
+					const code = buffer.charCodeAt(i);
+					if (code >= 0x40 && code <= 0x7e) {
+						if (isSgrMouse) {
+							// SGR mouse only terminates on M/m. Any other final
+							// byte would be a malformed body — keep scanning to
+							// match the prior `isCompleteCsiSequence` semantics.
+							if (code !== 0x4d && code !== 0x6d) {
+								i++;
+								continue;
+							}
+							const payload = buffer.slice(pos + 2, i + 1);
+							if (SGR_MOUSE_COMPLETE.test(payload)) return i + 1;
+							// Malformed body ending in M/m — keep scanning for a
+							// real terminator. Bounded by capEnd.
+							i++;
+							continue;
+						}
+						return i + 1;
+					}
+					i++;
+				}
+				return length - pos >= MAX_CSI_BYTES ? -2 : -1;
+			}
+		case 0x5d /* ] */:
+			{
+				// OSC: ESC ] ... BEL or ST (ESC \). Scan is bounded to
+				// [searchFrom, scanLimit): `String#indexOf` has no end bound, so
+				// an unterminated payload delivered as one huge chunk would
+				// otherwise be scanned to the end of the buffer — past the cap
+				// this function exists to enforce. `resumeSearchFrom - 1` keeps
+				// the one-byte overlap so an `ESC \` split across chunks is
+				// still found (the prior call's trailing ESC is re-inspected).
+				const searchFrom = Math.max(pos + 2, resumeSearchFrom - 1);
+				const scanLimit = Math.min(length, pos + MAX_STRING_SEQ_BYTES);
+				for (let i = searchFrom; i < scanLimit; i++) {
+					const code = buffer.charCodeAt(i);
+					if (code === 0x07 /* BEL */) return i + 1;
+					if (code === 0x1b /* ESC */) {
+						// `ESC \` (ST) must end within the cap; a lone trailing
+						// ESC at the buffer edge stays incomplete and is
+						// re-examined next call via the resume overlap.
+						if (i + 1 < scanLimit && buffer.charCodeAt(i + 1) === 0x5c /* \ */) return i + 2;
+					}
+				}
+				return length - pos >= MAX_STRING_SEQ_BYTES ? -2 : -1;
+			}
+		case 0x50 /* P */:
+		case 0x5f /* _ */:
+			{
+				// DCS / APC: ESC P/_ ... ST (ESC \). Same bounded scan and
+				// split-ST overlap as the OSC branch, minus BEL.
+				const searchFrom = Math.max(pos + 2, resumeSearchFrom - 1);
+				const scanLimit = Math.min(length, pos + MAX_STRING_SEQ_BYTES);
+				for (let i = searchFrom; i < scanLimit; i++) {
+					if (
+						buffer.charCodeAt(i) === 0x1b /* ESC */ &&
+						i + 1 < scanLimit &&
+						buffer.charCodeAt(i + 1) === 0x5c /* \ */
+					) {
+						return i + 2;
+					}
+				}
+				return length - pos >= MAX_STRING_SEQ_BYTES ? -2 : -1;
+			}
+		case 0x4f /* O */:
+			// SS3: ESC O + 1 char.
+			return pos + 3 <= length ? pos + 3 : -1;
+		default:
+			// Meta chord: ESC + 1 char.
+			return pos + 2;
+	}
+}
+
+/**
+ * Per-type cap used to flush the incomplete prefix when `resolveEscapeEnd`
+ * returns -2. The cap keeps issue-4073's malformed streamed CSI/OSC/…
+ * bounded in both work and memory.
+ */
+function escapeCapFor(next: number): number {
+	// OSC/DCS/APC carry the large payloads (image paste, Sixel); CSI stays
+	// tight because real CSI keys/mouse/responses fit comfortably below 4 KiB.
+	return next === 0x5d || next === 0x50 || next === 0x5f ? MAX_STRING_SEQ_BYTES : MAX_CSI_BYTES;
+}
+
+/**
+ * Split accumulated buffer into complete sequences
+ */
+function parseUnmodifiedKittyPrintableCodepoint(sequence: string): number | undefined {
+	const match = sequence.match(/^\x1b\[(\d+)(?::\d*)?(?::\d+)?u$/);
+	if (!match) return undefined;
+
+	const codepoint = parseInt(match[1]!, 10);
+	return codepoint >= 32 ? codepoint : undefined;
+}
+
+function extractCompleteSequences(
+	buffer: string,
+	resumeSearchFrom: number,
+): { sequences: string[]; remainder: string; resumeSearchFrom: number } {
+	const sequences: string[] = [];
+	const length = buffer.length;
+	let pos = 0;
+
+	// Index-based scanning: this is the input hot path. Slicing the remaining
+	// buffer (or Array.from-ing it) per iteration would make plain-text bursts
+	// O(n²) — a 100KB non-bracketed paste must stay O(n).
+	//
+	// `resumeSearchFrom` applies only when the buffer starts with an
+	// incomplete OSC/DCS/APC we buffered on the previous call; once any
+	// bytes are consumed (pos advances past the leading escape), the hint no
+	// longer maps to the current buffer offsets and is discarded.
+	let hint = resumeSearchFrom;
+
+	while (pos < length) {
+		if (buffer.charCodeAt(pos) !== 0x1b) {
+			// Not an escape sequence - take one Unicode scalar, not a UTF-16 code unit.
+			const codePoint = buffer.codePointAt(pos)!;
+			const charLength = codePoint > 0xffff ? 2 : 1;
+			sequences.push(buffer.slice(pos, pos + charLength));
+			pos += charLength;
+			hint = 0;
+			continue;
+		}
+
+		// `\x1b\x1b` is one of three things — see the outer switch below.
+		// Kept in the outer loop because it interacts with flush timing
+		// (bare `\x1b\x1b` is held for the timer chain) and with the SGR
+		// mouse split that splits `\x1b\x1b[<…` into `\x1b` + `\x1b[<…`.
+		if (pos + 1 < length && buffer.charCodeAt(pos + 1) === 0x1b) {
+			if (pos + 2 >= length) {
+				//   Two real Esc keypresses bursted by terminal input batching:
+				//   when the buffer ends here, hold the partial for the flush
+				//   window so cases 1/2 can still arrive; if no follower
+				//   arrives, `flush()` splits the held remainder into two ESC
+				//   events (#3857).
+				return { sequences, remainder: buffer.slice(pos), resumeSearchFrom: 0 };
+			}
+			const third = buffer.charCodeAt(pos + 2);
+			if (third !== 0x5b && third !== 0x4f) {
+				//   ESC followed by a legacy Alt chord (`\x1bd`, `\x1b\x7f`, …):
+				//   emit the first ESC, then restart at the second ESC so
+				//   downstream parsing still sees the Alt chord as one
+				//   keypress (#3860 review).
+				sequences.push(ESC);
+				pos += 1;
+				hint = 0;
+				continue;
+			}
+			//   ESC prefixing CSI/SS3 (meta-CSI, held Esc joined by a follower):
+			//   resolve the inner escape's end from `pos + 1`. Consuming two
+			//   bytes here would tear the follower and leak its tail as typed
+			//   text (settings search filling with "[B" or "[<35;22;17M").
+			const innerEnd = resolveEscapeEnd(buffer, pos + 1, length, 0);
+			if (innerEnd === -1) {
+				return { sequences, remainder: buffer.slice(pos), resumeSearchFrom: 0 };
+			}
+			if (innerEnd === -2) {
+				const cap = escapeCapFor(third);
+				const flushEnd = Math.min(length, pos + cap);
+				sequences.push(buffer.slice(pos, flushEnd));
+				pos = flushEnd;
+				hint = 0;
+				continue;
+			}
+			// ESC + SGR mouse is never a meta chord: alt-modified mouse
+			// reports carry the modifier in the button bits, not an ESC
+			// prefix. Deliver the bare ESC and the report separately.
+			if (third === 0x5b && buffer.charCodeAt(pos + 3) === 0x3c) {
+				sequences.push(ESC);
+				sequences.push(buffer.slice(pos + 1, innerEnd));
+				pos = innerEnd;
+				hint = 0;
+				continue;
+			}
+			sequences.push(buffer.slice(pos, innerEnd));
+			pos = innerEnd;
+			hint = 0;
+			continue;
+		}
+
+		// Single ESC — resolve directly. Hint carries over from the previous
+		// call only when we are still on the buffered escape (pos === 0).
+		const end = resolveEscapeEnd(buffer, pos, length, pos === 0 ? hint : 0);
+		if (end === -1) {
+			// Buffer for more. When this is the leading OSC/DCS/APC,
+			// remember how far we scanned so the next `process()` call
+			// resumes from there instead of rescanning the whole buffer.
+			const next = pos + 1 < length ? buffer.charCodeAt(pos + 1) : -1;
+			const nextHint = pos === 0 && (next === 0x5d || next === 0x50 || next === 0x5f) ? length : 0;
+			return { sequences, remainder: buffer.slice(pos), resumeSearchFrom: nextHint };
+		}
+		if (end === -2) {
+			const next = buffer.charCodeAt(pos + 1);
+			const cap = escapeCapFor(next);
+			const flushEnd = Math.min(length, pos + cap);
+			sequences.push(buffer.slice(pos, flushEnd));
+			pos = flushEnd;
+			hint = 0;
+			continue;
+		}
+		sequences.push(buffer.slice(pos, end));
+		pos = end;
+		hint = 0;
+	}
+
+	return { sequences, remainder: "", resumeSearchFrom: 0 };
+}
+
+export type StdinBufferOptions = {
+	/**
+	 * Maximum time to wait for sequence completion (default: 75ms).
+	 * After this time, a genuinely incomplete escape is flushed.
+	 */
+	timeout?: number;
+	/**
+	 * Maximum extra time (default: 150ms) an unambiguous escape partial — an
+	 * SGR mouse prefix, or any dangling escape while the kitty keyboard
+	 * protocol is active — is held past `timeout` waiting for its tail.
+	 */
+	partialHoldTimeout?: number;
+	/**
+	 * Paste-mode inactivity watchdog (default: 1000ms). If no input arrives for
+	 * this long while waiting for the bracketed-paste end marker, the paste is
+	 * assumed truncated: accumulated bytes are delivered and input recovers.
+	 */
+	pasteTimeout?: number;
+	/**
+	 * Paste-mode byte cap (default: 64 MiB). Exceeding it aborts paste mode the
+	 * same way, bounding memory when the end marker never arrives.
+	 */
+	pasteByteLimit?: 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> {
+	#buffer: string = "";
+	#timeout?: NodeJS.Timeout;
+	#flushDeferral?: NodeJS.Timeout;
+	#partialHoldStartMs = 0;
+	readonly #timeoutMs: number;
+	readonly #partialHoldMaxMs: number;
+	readonly #pasteTimeoutMs: number;
+	readonly #pasteByteLimit: number;
+	#pasteMode: boolean = false;
+	#pasteChunks: string[] = [];
+	#pasteOverlap: string = "";
+	#pasteBytes = 0;
+	#pasteWatchdog?: NodeJS.Timeout;
+	#pendingKittyPrintableCodepoint: number | undefined;
+	#pendingKittyPrintableAtMs = 0;
+	#escapeSearchOffset = 0;
+	#rawPasteCandidate = "";
+	#rawPasteTimer?: NodeJS.Timeout;
+
+	constructor(options: StdinBufferOptions = {}) {
+		super();
+		this.#timeoutMs = options.timeout ?? 75;
+		this.#partialHoldMaxMs = options.partialHoldTimeout ?? PARTIAL_HOLD_MAX_MS;
+		this.#pasteTimeoutMs = options.pasteTimeout ?? PASTE_INACTIVITY_TIMEOUT_MS;
+		this.#pasteByteLimit = options.pasteByteLimit ?? PASTE_MAX_BYTES;
+	}
+
+	process(data: string | Buffer): void {
+		// 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 (this.#flushDeferral && this.#isFreshEscapeAfterDeferredFlush(str)) {
+			// The buffered partial already hit its flush timeout. A new escape is
+			// a fresh sequence, not a tail; flush the stale partial first so the
+			// new sequence can be parsed from a clean buffer.
+			this.#flushExpired();
+		} else {
+			// Cancel any pending flush — new data may complete the buffered partial.
+			this.#clearFlushTimer();
+		}
+
+		if (str.length === 0 && this.#buffer.length === 0 && this.#rawPasteCandidate.length === 0) {
+			this.#emitDataSequence("");
+			return;
+		}
+
+		if (this.#pasteMode) {
+			this.#consumePasteChunk(str);
+			return;
+		}
+
+		if (this.#rawPasteCandidate.length > 0) {
+			if (str.indexOf(ESC) !== -1) {
+				// Escape-bearing input cannot belong to an unmarked raw paste.
+				// Replay the ambiguous prefix as keys before parsing the escape.
+				this.#flushRawPasteCandidate();
+			} else {
+				this.#rawPasteCandidate += str;
+				if (isRawMultilineBurst(this.#rawPasteCandidate)) {
+					this.#emitRawPasteCandidate();
+				}
+				return;
+			}
+		}
+
+		if (
+			this.#buffer.length === 0 &&
+			str.indexOf(ESC) === -1 &&
+			(str.indexOf("\r") !== -1 || str.indexOf("\n") !== -1)
+		) {
+			// Hold the first break-bearing read briefly. A split raw paste can
+			// then accumulate enough logical lines to classify; an ordinary
+			// Enter is replayed unchanged when the fixed window expires.
+			this.#rawPasteCandidate = str;
+			if (isRawMultilineBurst(str)) {
+				this.#emitRawPasteCandidate();
+			} else {
+				this.#armRawPasteTimer();
+			}
+			return;
+		}
+
+		this.#buffer += str;
+
+		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, 0);
+				for (const sequence of result.sequences) {
+					this.#emitDataSequence(sequence);
+				}
+			}
+
+			this.#escapeSearchOffset = 0;
+			this.#pendingKittyPrintableCodepoint = undefined;
+			this.#buffer = this.#buffer.slice(startIndex + BRACKETED_PASTE_START.length);
+			const firstChunk = this.#buffer;
+			this.#buffer = "";
+			this.#pasteMode = true;
+			this.#pasteChunks = [];
+			this.#pasteOverlap = "";
+			this.#pasteBytes = 0;
+			this.#consumePasteChunk(firstChunk);
+			return;
+		}
+
+		const result = extractCompleteSequences(this.#buffer, this.#escapeSearchOffset);
+		this.#buffer = result.remainder;
+		this.#escapeSearchOffset = result.resumeSearchFrom;
+
+		for (const sequence of result.sequences) {
+			this.#emitDataSequence(sequence);
+		}
+
+		if (this.#buffer.length > 0) {
+			this.#armFlushTimer();
+		} else {
+			this.#partialHoldStartMs = 0;
+		}
+	}
+
+	/**
+	 * Consume one chunk of paste-mode input. Chunks are accumulated in an array
+	 * and only joined once the end marker arrives, so a large paste delivered in
+	 * many small terminal reads stays O(total) instead of the O(total^2) cost of
+	 * re-concatenating and rescanning the whole buffer on every chunk. A short
+	 * overlap tail (end-marker length - 1) is carried across chunk boundaries so
+	 * a marker split between two reads is still detected without rescanning.
+	 */
+	#consumePasteChunk(chunk: string): void {
+		const probe = this.#pasteOverlap + chunk;
+		if (probe.indexOf(BRACKETED_PASTE_END) === -1) {
+			this.#pasteChunks.push(chunk);
+			this.#pasteBytes += chunk.length;
+			const keep = BRACKETED_PASTE_END.length - 1;
+			this.#pasteOverlap = probe.length > keep ? probe.slice(probe.length - keep) : probe;
+			if (this.#pasteBytes > this.#pasteByteLimit) {
+				this.#abortPaste();
+				return;
+			}
+			this.#armPasteWatchdog();
+			return;
+		}
+
+		// End marker arrived: join once and split at its first occurrence,
+		// matching the prior indexOf-from-start semantics exactly.
+		const flat = this.#pasteChunks.length > 0 ? `${this.#pasteChunks.join("")}${chunk}` : chunk;
+		const endIndex = flat.indexOf(BRACKETED_PASTE_END);
+		const pastedContent = flat.slice(0, endIndex);
+		const remaining = flat.slice(endIndex + BRACKETED_PASTE_END.length);
+
+		this.#clearPasteWatchdog();
+		this.#pasteMode = false;
+		this.#pasteChunks = [];
+		this.#pasteOverlap = "";
+		this.#pasteBytes = 0;
+		this.#pendingKittyPrintableCodepoint = undefined;
+
+		this.emit("paste", pastedContent);
+
+		if (remaining.length > 0) {
+			this.process(remaining);
+		}
+	}
+
+	/** Re-arm the paste-mode inactivity watchdog after each chunk. */
+	#armPasteWatchdog(): void {
+		if (this.#pasteWatchdog) clearTimeout(this.#pasteWatchdog);
+		this.#pasteWatchdog = setTimeout(() => {
+			this.#pasteWatchdog = undefined;
+			this.#abortPaste();
+		}, this.#pasteTimeoutMs);
+	}
+
+	#clearPasteWatchdog(): void {
+		if (this.#pasteWatchdog) {
+			clearTimeout(this.#pasteWatchdog);
+			this.#pasteWatchdog = undefined;
+		}
+	}
+
+	/**
+	 * Recover from a paste whose end marker never arrived (dropped or corrupted
+	 * in transit, or past the byte cap): exit paste mode and deliver the
+	 * accumulated bytes as a paste, so they are neither lost, replayed as
+	 * keystrokes, nor accumulated forever while input appears dead.
+	 */
+	#abortPaste(): void {
+		this.#clearPasteWatchdog();
+		const content = this.#pasteChunks.join("");
+		this.#pasteMode = false;
+		this.#pasteChunks = [];
+		this.#pasteOverlap = "";
+		this.#pasteBytes = 0;
+		this.emit("paste", content);
+	}
+
+	/** Start one fixed window from the first break-bearing raw read. */
+	#armRawPasteTimer(): void {
+		if (this.#rawPasteTimer) return;
+		this.#rawPasteTimer = setTimeout(() => {
+			this.#rawPasteTimer = undefined;
+			this.#flushRawPasteCandidate();
+		}, RAW_PASTE_CLASSIFICATION_TIMEOUT_MS);
+	}
+
+	#clearRawPasteTimer(): void {
+		if (this.#rawPasteTimer) {
+			clearTimeout(this.#rawPasteTimer);
+			this.#rawPasteTimer = undefined;
+		}
+	}
+
+	#takeRawPasteCandidate(): string {
+		this.#clearRawPasteTimer();
+		const content = this.#rawPasteCandidate;
+		this.#rawPasteCandidate = "";
+		return content;
+	}
+
+	/** Emit a classified raw multiline burst through the paste channel. */
+	#emitRawPasteCandidate(): void {
+		const content = this.#takeRawPasteCandidate();
+		this.#pendingKittyPrintableCodepoint = undefined;
+		this.emit("paste", content);
+	}
+
+	/** Replay an ambiguous raw candidate as the original per-key data events. */
+	#flushRawPasteCandidate(): void {
+		const content = this.#takeRawPasteCandidate();
+		if (content.length === 0) return;
+		const result = extractCompleteSequences(content, 0);
+		for (const sequence of result.sequences) {
+			this.#emitDataSequence(sequence);
+		}
+	}
+
+	#emitDataSequence(sequence: string): void {
+		const rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;
+		if (
+			rawCodepoint !== undefined &&
+			rawCodepoint === this.#pendingKittyPrintableCodepoint &&
+			Date.now() - this.#pendingKittyPrintableAtMs <= KITTY_PRINTABLE_DEDUP_WINDOW_MS
+		) {
+			this.#pendingKittyPrintableCodepoint = undefined;
+			return;
+		}
+
+		this.#pendingKittyPrintableCodepoint = parseUnmodifiedKittyPrintableCodepoint(sequence);
+		if (this.#pendingKittyPrintableCodepoint !== undefined) {
+			this.#pendingKittyPrintableAtMs = Date.now();
+		}
+		this.emit("data", sequence);
+	}
+
+	/**
+	 * setTimeout(0): when the event loop stalls past the timeout (heavy render)
+	 * while the tail of a split escape is already queued on stdin, expired
+	 * timers run before the poll phase that delivers the tail — flushing
+	 * straight from the timer would tear the sequence apart and leak the tail
+	 * as typed text. The zero-delay deferral runs on the next timers pass,
+	 * after poll has had a chance to deliver the pending chunk to process()
+	 * and cancel the deferral.
+	 */
+	#armFlushTimer(): void {
+		this.#timeout = setTimeout(() => {
+			this.#timeout = undefined;
+			this.#flushDeferral = setTimeout(() => {
+				this.#flushDeferral = undefined;
+				this.#flushExpired();
+			});
+		}, this.#timeoutMs);
+	}
+
+	#clearFlushTimer(): void {
+		if (this.#timeout) {
+			clearTimeout(this.#timeout);
+			this.#timeout = undefined;
+		}
+		if (this.#flushDeferral) {
+			clearTimeout(this.#flushDeferral);
+			this.#flushDeferral = undefined;
+		}
+	}
+
+	/**
+	 * A deferred flush means the current buffer already waited for the
+	 * incomplete-sequence timeout. If the next chunk starts a fresh escape, do
+	 * not merge it into the stale partial. Keep ESC-backslash as a continuation
+	 * for OSC/DCS/APC string terminators (`ST`).
+	 */
+	#isFreshEscapeAfterDeferredFlush(str: string): boolean {
+		if (!str.startsWith(ESC) || this.#buffer.length === 0) return false;
+		if (
+			str.startsWith(`${ESC}\\`) &&
+			(this.#buffer.startsWith(`${ESC}]`) ||
+				this.#buffer.startsWith(`${ESC}P`) ||
+				this.#buffer.startsWith(`${ESC}_`))
+		) {
+			return false;
+		}
+		return true;
+	}
+
+	/**
+	 * Whether the dangling partial cannot be a finished keypress and is worth
+	 * holding for its tail instead of flushing:
+	 * - SGR mouse prefixes (`\x1b[<…`) — no keyboard sequence uses them.
+	 * - Any partial while the kitty keyboard protocol is active — the ESC key
+	 *   arrives as `\x1b[27u` and alt-chords as CSI-u, so a bare `\x1b` (or
+	 *   any unterminated escape) is always a split sequence, never a key.
+	 */
+	#shouldHoldPartial(): boolean {
+		return SGR_MOUSE_PARTIAL.test(this.#buffer) || isKittyProtocolActive();
+	}
+
+	/** Timeout-driven flush: hold unambiguous partials (bounded), else deliver. */
+	#flushExpired(): void {
+		if (this.#buffer.length === 0) {
+			this.#partialHoldStartMs = 0;
+			return;
+		}
+		if (this.#shouldHoldPartial()) {
+			if (this.#partialHoldStartMs === 0) this.#partialHoldStartMs = Date.now();
+			if (Date.now() - this.#partialHoldStartMs < this.#partialHoldMaxMs) {
+				this.#armFlushTimer();
+				return;
+			}
+		}
+		this.#partialHoldStartMs = 0;
+		for (const sequence of this.flush()) {
+			this.#emitDataSequence(sequence);
+		}
+	}
+
+	flush(): string[] {
+		this.#clearFlushTimer();
+
+		const rawCandidate = this.#takeRawPasteCandidate();
+		const sequences = rawCandidate.length > 0 ? extractCompleteSequences(rawCandidate, 0).sequences : [];
+
+		if (this.#buffer.length === 0) {
+			this.#pendingKittyPrintableCodepoint = undefined;
+			return sequences;
+		}
+
+		const buffered = this.#buffer;
+		this.#buffer = "";
+		this.#escapeSearchOffset = 0;
+		this.#pendingKittyPrintableCodepoint = undefined;
+		// Bare double-ESC remainder (no disambiguating "[" / "O" arrived in time):
+		// two real Esc keypresses bursted by terminal batching, not a meta-CSI/SS3
+		// prefix. `parseKey` returns undefined for the combined chunk, so a single
+		// emission swallows the double-escape gesture (#3857). Mirror the inline
+		// split in `extractCompleteSequences` and deliver two ESC events.
+		if (buffered === `${ESC}${ESC}`) {
+			sequences.push(ESC, ESC);
+		} else {
+			sequences.push(buffered);
+		}
+		return sequences;
+	}
+
+	clear(): void {
+		this.#clearFlushTimer();
+		this.#clearPasteWatchdog();
+		this.#clearRawPasteTimer();
+		this.#buffer = "";
+		this.#rawPasteCandidate = "";
+		this.#pasteMode = false;
+		this.#pasteChunks = [];
+		this.#pasteOverlap = "";
+		this.#pasteBytes = 0;
+		this.#pendingKittyPrintableCodepoint = undefined;
+		this.#partialHoldStartMs = 0;
+		this.#escapeSearchOffset = 0;
+	}
+
+	getBuffer(): string {
+		return `${this.#rawPasteCandidate}${this.#buffer}`;
+	}
+
+	destroy(): void {
+		this.clear();
+	}
+}