@prometheus-ai/tui 0.5.0

package/src/kitty-graphics.ts

@@ -0,0 +1,270 @@
+/**
+ * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE) and temp-file
+ * (`t=t`) image transmission, with runtime feature state and env overrides.
+ *
+ * Unicode placeholders let a transmitted image be displayed by writing ordinary
+ * text cells — the placeholder char U+10EEEE plus row/column combining
+ * diacritics — instead of a cursor-positioned `a=p` direct placement. The image
+ * then participates in the normal text grid, so it survives horizontal slicing,
+ * reflow and overlapping draws (each cell names its own row+column, so a sliced
+ * row still maps to the correct sub-region). See kitty
+ * `docs/graphics-protocol.rst` "Unicode placeholders for relative placements".
+ *
+ * This module is intentionally free of `./terminal-capabilities` imports so the
+ * dependency stays one-way (capabilities → kitty-graphics) and no import cycle
+ * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $env, logger } from "@prometheus-ai/utils";
+
+/** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
+export const KITTY_PLACEHOLDER = "\u{10eeee}";
+
+/**
+ * Row/column diacritics (Unicode combining class 230, no decomposition) used to
+ * name a placeholder cell's row and column. Index `i` → codepoint. Derived from
+ * kitty `gen/rowcolumn-diacritics.txt` (Unicode 6.0.0 NSM set). 297 entries, so
+ * a single image can address up to 297 rows/columns without ID-high-byte tricks.
+ */
+const ROWCOLUMN_DIACRITICS: readonly number[] = [
+	0x305, 0x30d, 0x30e, 0x310, 0x312, 0x33d, 0x33e, 0x33f, 0x346, 0x34a, 0x34b, 0x34c, 0x350, 0x351, 0x352, 0x357,
+	0x35b, 0x363, 0x364, 0x365, 0x366, 0x367, 0x368, 0x369, 0x36a, 0x36b, 0x36c, 0x36d, 0x36e, 0x36f, 0x483, 0x484,
+	0x485, 0x486, 0x487, 0x592, 0x593, 0x594, 0x595, 0x597, 0x598, 0x599, 0x59c, 0x59d, 0x59e, 0x59f, 0x5a0, 0x5a1,
+	0x5a8, 0x5a9, 0x5ab, 0x5ac, 0x5af, 0x5c4, 0x610, 0x611, 0x612, 0x613, 0x614, 0x615, 0x616, 0x617, 0x657, 0x658,
+	0x659, 0x65a, 0x65b, 0x65d, 0x65e, 0x6d6, 0x6d7, 0x6d8, 0x6d9, 0x6da, 0x6db, 0x6dc, 0x6df, 0x6e0, 0x6e1, 0x6e2,
+	0x6e4, 0x6e7, 0x6e8, 0x6eb, 0x6ec, 0x730, 0x732, 0x733, 0x735, 0x736, 0x73a, 0x73d, 0x73f, 0x740, 0x741, 0x743,
+	0x745, 0x747, 0x749, 0x74a, 0x7eb, 0x7ec, 0x7ed, 0x7ee, 0x7ef, 0x7f0, 0x7f1, 0x7f3, 0x816, 0x817, 0x818, 0x819,
+	0x81b, 0x81c, 0x81d, 0x81e, 0x81f, 0x820, 0x821, 0x822, 0x823, 0x825, 0x826, 0x827, 0x829, 0x82a, 0x82b, 0x82c,
+	0x82d, 0x951, 0x953, 0x954, 0xf82, 0xf83, 0xf86, 0xf87, 0x135d, 0x135e, 0x135f, 0x17dd, 0x193a, 0x1a17, 0x1a75,
+	0x1a76, 0x1a77, 0x1a78, 0x1a79, 0x1a7a, 0x1a7b, 0x1a7c, 0x1b6b, 0x1b6d, 0x1b6e, 0x1b6f, 0x1b70, 0x1b71, 0x1b72,
+	0x1b73, 0x1cd0, 0x1cd1, 0x1cd2, 0x1cda, 0x1cdb, 0x1ce0, 0x1dc0, 0x1dc1, 0x1dc3, 0x1dc4, 0x1dc5, 0x1dc6, 0x1dc7,
+	0x1dc8, 0x1dc9, 0x1dcb, 0x1dcc, 0x1dd1, 0x1dd2, 0x1dd3, 0x1dd4, 0x1dd5, 0x1dd6, 0x1dd7, 0x1dd8, 0x1dd9, 0x1dda,
+	0x1ddb, 0x1ddc, 0x1ddd, 0x1dde, 0x1ddf, 0x1de0, 0x1de1, 0x1de2, 0x1de3, 0x1de4, 0x1de5, 0x1de6, 0x1dfe, 0x20d0,
+	0x20d1, 0x20d4, 0x20d5, 0x20d6, 0x20d7, 0x20db, 0x20dc, 0x20e1, 0x20e7, 0x20e9, 0x20f0, 0x2cef, 0x2cf0, 0x2cf1,
+	0x2de0, 0x2de1, 0x2de2, 0x2de3, 0x2de4, 0x2de5, 0x2de6, 0x2de7, 0x2de8, 0x2de9, 0x2dea, 0x2deb, 0x2dec, 0x2ded,
+	0x2dee, 0x2def, 0x2df0, 0x2df1, 0x2df2, 0x2df3, 0x2df4, 0x2df5, 0x2df6, 0x2df7, 0x2df8, 0x2df9, 0x2dfa, 0x2dfb,
+	0x2dfc, 0x2dfd, 0x2dfe, 0x2dff, 0xa66f, 0xa67c, 0xa67d, 0xa6f0, 0xa6f1, 0xa8e0, 0xa8e1, 0xa8e2, 0xa8e3, 0xa8e4,
+	0xa8e5, 0xa8e6, 0xa8e7, 0xa8e8, 0xa8e9, 0xa8ea, 0xa8eb, 0xa8ec, 0xa8ed, 0xa8ee, 0xa8ef, 0xa8f0, 0xa8f1, 0xaab0,
+	0xaab2, 0xaab3, 0xaab7, 0xaab8, 0xaabe, 0xaabf, 0xaac1, 0xfe20, 0xfe21, 0xfe22, 0xfe23, 0xfe24, 0xfe25, 0xfe26,
+	0x10a0f, 0x10a38, 0x1d185, 0x1d186, 0x1d187, 0x1d188, 0x1d189, 0x1d1aa, 0x1d1ab, 0x1d1ac, 0x1d1ad, 0x1d242, 0x1d243,
+	0x1d244,
+];
+
+/** Largest row/column index expressible with the diacritic table (one cell each). */
+export const KITTY_PLACEHOLDER_MAX_CELLS = ROWCOLUMN_DIACRITICS.length;
+
+/** A minimal opaque 1x1 PNG (base64) used for the temp-file support probe. */
+const PROBE_PNG_BASE64 =
+	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+
+export type KittyTransmissionMedium = "direct" | "temp-file";
+
+export interface KittyGraphicsFeatures {
+	/** Display images via Unicode placeholders instead of direct `a=p` placement. */
+	unicodePlaceholders: boolean;
+	/** How image data reaches the terminal: in-band base64 or a temp file. */
+	transmissionMedium: KittyTransmissionMedium;
+}
+
+/** Explicit transmission medium from `PROMETHEUS_KITTY_IMAGE_TRANSMISSION`, else "auto". */
+function transmissionOverride(): KittyTransmissionMedium | "auto" {
+	const raw = $env.PROMETHEUS_KITTY_IMAGE_TRANSMISSION?.trim().toLowerCase();
+	if (raw === "temp-file") return "temp-file";
+	if (raw === "direct") return "direct";
+	return "auto";
+}
+
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Only `kitty` (the protocol's origin) and `ghostty` ship a working
+ * implementation; WezTerm advertises Kitty graphics but treats placeholder
+ * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
+ * still unchecked), and the tmux/screen fallback can land on any outer
+ * terminal. Enabling placeholders on those paths emits a `columns × rows`
+ * grid of U+10EEEE per image per frame; the cells render as boxed fallback
+ * glyphs and re-emit on every repaint, which is exactly the
+ * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ *
+ * `PROMETHEUS_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
+ * non-supporting outer terminal); `PROMETHEUS_KITTY_PLACEHOLDERS=1` forces on (e.g.
+ * for a wezterm nightly that has merged placeholder support).
+ */
+export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: NodeJS.ProcessEnv = Bun.env): boolean {
+	const offRaw = env.PROMETHEUS_NO_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (offRaw === "1" || offRaw === "true" || offRaw === "on" || offRaw === "yes" || offRaw === "y") return false;
+	const force = env.PROMETHEUS_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (force === "1" || force === "true" || force === "on" || force === "yes" || force === "y") return true;
+	if (force === "0" || force === "false" || force === "off" || force === "no" || force === "n") return false;
+	return terminalId === "kitty" || terminalId === "ghostty";
+}
+
+let features: KittyGraphicsFeatures = {
+	// Off until `terminal-capabilities` seeds it from the detected terminal id —
+	// the default-on path corrupts wezterm and tmux-passthrough sessions.
+	unicodePlaceholders: false,
+	// Start direct; a successful probe (or explicit `temp-file` override) promotes.
+	transmissionMedium: transmissionOverride() === "temp-file" ? "temp-file" : "direct",
+};
+
+export function getKittyGraphics(): Readonly<KittyGraphicsFeatures> {
+	return features;
+}
+
+export function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void {
+	features = { ...features, ...partial };
+}
+
+/**
+ * Whether temp-file transmission may be promoted at runtime: forced via env,
+ * disabled via env, otherwise auto (local sessions only — a temp file written
+ * locally is not readable by a terminal on the far side of an SSH link).
+ */
+export function kittyTempFileAllowed(): boolean {
+	const override = transmissionOverride();
+	if (override === "temp-file") return true;
+	if (override === "direct") return false;
+	// Auto: local sessions only — a temp file written here is not on the SSH peer.
+	return !$env.SSH_CONNECTION && !$env.SSH_CLIENT && !$env.SSH_TTY;
+}
+
+/** Whether a `columns`×`rows` placeholder grid fits within the diacritic table. */
+export function kittyPlaceholdersFit(columns: number, rows: number): boolean {
+	return columns >= 1 && rows >= 1 && columns <= KITTY_PLACEHOLDER_MAX_CELLS && rows <= KITTY_PLACEHOLDER_MAX_CELLS;
+}
+
+/** True when the base64 payload is a PNG (kitty `f=100` / temp-file path only). */
+export function isPngBase64(base64Data: string): boolean {
+	return base64Data.startsWith("iVBORw0KGgo");
+}
+
+function diacritic(index: number): string {
+	const cp = ROWCOLUMN_DIACRITICS[index];
+	return cp === undefined ? "" : String.fromCodePoint(cp);
+}
+
+/**
+ * Virtual placement APC (`a=p,U=1`): tells the terminal that placeholder cells
+ * carrying image id `i` should display the transmitted image, scaled to fit the
+ * `c`×`r` cell box. Re-emitting with a stable `placementId` replaces in place.
+ */
+export function encodeKittyVirtualPlacement(opts: {
+	imageId: number;
+	placementId?: number;
+	columns: number;
+	rows: number;
+}): string {
+	const params = ["a=p", "U=1", "q=2", `i=${opts.imageId}`];
+	if (opts.placementId) params.push(`p=${opts.placementId}`);
+	params.push(`c=${opts.columns}`, `r=${opts.rows}`);
+	return `\x1b_G${params.join(",")}\x1b\\`;
+}
+
+/**
+ * Build the placeholder cell grid as one string per row. The image id is carried
+ * in each row's foreground color and the placement id (if any) in its underline
+ * color; every cell names its explicit row+column diacritic (robust to slicing,
+ * unlike left-inheritance). Returns exactly `rows` strings.
+ */
+export function encodeKittyPlaceholderGrid(opts: {
+	imageId: number;
+	placementId?: number;
+	columns: number;
+	rows: number;
+}): string[] {
+	const fg = `\x1b[38;2;${(opts.imageId >> 16) & 0xff};${(opts.imageId >> 8) & 0xff};${opts.imageId & 0xff}m`;
+	const underline = opts.placementId
+		? `\x1b[58:2::${(opts.placementId >> 16) & 0xff}:${(opts.placementId >> 8) & 0xff}:${opts.placementId & 0xff}m`
+		: "";
+	const reset = "\x1b[39;59m";
+	const lead = fg + underline;
+	const out: string[] = [];
+	for (let r = 0; r < opts.rows; r++) {
+		const rowDiacritic = diacritic(r);
+		let row = lead;
+		for (let c = 0; c < opts.columns; c++) {
+			row += KITTY_PLACEHOLDER + rowDiacritic + diacritic(c);
+		}
+		out.push(row + reset);
+	}
+	return out;
+}
+
+/**
+ * Full placeholder render: the virtual-placement APC prefixes line 0, and every
+ * line carries placeholder cells. Returns exactly `rows` lines (no cursor moves).
+ */
+export function renderKittyPlaceholderLines(opts: {
+	imageId: number;
+	placementId?: number;
+	columns: number;
+	rows: number;
+}): string[] {
+	const grid = encodeKittyPlaceholderGrid(opts);
+	if (grid.length > 0) {
+		grid[0] = encodeKittyVirtualPlacement(opts) + grid[0];
+	}
+	return grid;
+}
+
+/**
+ * Path for a temp-file transmission. Kitty deletes a `t=t` file after reading it
+ * **only** when the path contains the substring `tty-graphics-protocol`, so it is
+ * embedded in the filename to keep the temp dir self-cleaning.
+ */
+function tempGraphicsPath(tag: string): string {
+	return path.join(os.tmpdir(), `tty-graphics-protocol-${tag}-${process.pid}-${Date.now()}.png`);
+}
+
+/**
+ * Transmit a PNG via a temp file (`t=t`): decode the base64 to bytes once, write
+ * them to a temp file, and send the base64-encoded file path as payload. Returns
+ * the APC string, or `null` on any failure (caller falls back to direct base64).
+ *
+ * Synchronous filesystem writes are mandated by the synchronous render pipeline
+ * (`Image.render` → `renderImage` are sync); there is no async seam here.
+ */
+export function encodeKittyTempFileTransmit(base64Png: string, imageId: number): string | null {
+	try {
+		const bytes = Buffer.from(base64Png, "base64");
+		if (bytes.length === 0) return null;
+		const file = tempGraphicsPath(`i${imageId}`);
+		fs.writeFileSync(file, bytes);
+		const encodedPath = Buffer.from(file, "utf8").toString("base64");
+		return `\x1b_Ga=t,f=100,t=t,S=${bytes.length},q=2,i=${imageId};${encodedPath}\x1b\\`;
+	} catch (err) {
+		logger.debug("Kitty temp-file transmit failed; using direct base64", { err: String(err) });
+		return null;
+	}
+}
+
+/**
+ * Encode a temp-file support probe: write a tiny PNG to a temp file and ask the
+ * terminal to query it (`a=q,t=t`). A conforming terminal replies
+ * `ESC _ G i=<probeId>;OK ESC \`. Returns the query APC plus a `cleanup` that
+ * removes the probe file (best-effort; kitty self-deletes the magic-named file).
+ * Returns `null` if the temp file cannot be written.
+ */
+export function encodeKittyTempFileProbe(probeId: number): { sequence: string; cleanup: () => void } | null {
+	try {
+		const bytes = Buffer.from(PROBE_PNG_BASE64, "base64");
+		const file = tempGraphicsPath(`probe${probeId}`);
+		fs.writeFileSync(file, bytes);
+		const encodedPath = Buffer.from(file, "utf8").toString("base64");
+		const sequence = `\x1b_Ga=q,t=t,f=100,S=${bytes.length},q=2,i=${probeId};${encodedPath}\x1b\\`;
+		const cleanup = () => {
+			try {
+				fs.rmSync(file, { force: true });
+			} catch {
+				// Best effort; kitty deletes tty-graphics-protocol files itself.
+			}
+		};
+		return { sequence, cleanup };
+	} catch (err) {
+		logger.debug("Kitty temp-file probe setup failed", { err: String(err) });
+		return null;
+	}
+}

package/src/stdin-buffer.ts

@@ -0,0 +1,423 @@
+/**
+ * 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";
+
+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";
+	}
+
+	// ESC-prefixed sequences (terminals with metaSendsEscape):
+	// Only when the inner ESC starts a CSI ('[') or SS3 ('O') sequence.
+	// Bare double-ESC (e.g. \x1b\x1bX) remains complete to avoid 10ms timeout lag.
+	if (afterEsc.startsWith(ESC)) {
+		const inner = data.slice(1);
+		const third = inner.charCodeAt(1);
+		if (third === 0x5b || third === 0x4f) {
+			return isCompleteSequence(inner);
+		}
+		return "complete";
+	}
+
+	// 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 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): { 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 one Unicode scalar, not a UTF-16 code unit.
+			const char = Array.from(remaining)[0] ?? "";
+			sequences.push(char);
+			pos += char.length;
+		}
+	}
+
+	return { sequences, remainder: "" };
+}
+
+export type StdinBufferOptions = {
+	/**
+	 * Maximum time to wait for sequence completion (default: 75ms).
+	 * After this time, a genuinely incomplete escape is flushed.
+	 */
+	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> {
+	#buffer: string = "";
+	#timeout?: NodeJS.Timeout;
+	readonly #timeoutMs: number;
+	#pasteMode: boolean = false;
+	#pasteBuffer: string = "";
+	#pendingKittyPrintableCodepoint: number | undefined;
+
+	constructor(options: StdinBufferOptions = {}) {
+		super();
+		this.#timeoutMs = options.timeout ?? 75;
+	}
+
+	process(data: string | Buffer): void {
+		// Clear any pending timeout
+		if (this.#timeout) {
+			clearTimeout(this.#timeout);
+			this.#timeout = undefined;
+		}
+
+		// 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.#emitDataSequence("");
+			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.#pendingKittyPrintableCodepoint = undefined;
+
+				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.#emitDataSequence(sequence);
+				}
+			}
+
+			this.#pendingKittyPrintableCodepoint = undefined;
+			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.#pendingKittyPrintableCodepoint = undefined;
+
+				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.#emitDataSequence(sequence);
+		}
+
+		if (this.#buffer.length > 0) {
+			this.#timeout = setTimeout(() => {
+				const flushed = this.flush();
+
+				for (const sequence of flushed) {
+					this.#emitDataSequence(sequence);
+				}
+			}, this.#timeoutMs);
+		}
+	}
+
+	#emitDataSequence(sequence: string): void {
+		const rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;
+		if (rawCodepoint !== undefined && rawCodepoint === this.#pendingKittyPrintableCodepoint) {
+			this.#pendingKittyPrintableCodepoint = undefined;
+			return;
+		}
+
+		this.#pendingKittyPrintableCodepoint = parseUnmodifiedKittyPrintableCodepoint(sequence);
+		this.emit("data", sequence);
+	}
+
+	flush(): string[] {
+		if (this.#timeout) {
+			clearTimeout(this.#timeout);
+			this.#timeout = undefined;
+		}
+
+		if (this.#buffer.length === 0) {
+			return [];
+		}
+
+		const sequences = [this.#buffer];
+		this.#buffer = "";
+		this.#pendingKittyPrintableCodepoint = undefined;
+		return sequences;
+	}
+
+	clear(): void {
+		if (this.#timeout) {
+			clearTimeout(this.#timeout);
+			this.#timeout = undefined;
+		}
+		this.#buffer = "";
+		this.#pasteMode = false;
+		this.#pasteBuffer = "";
+		this.#pendingKittyPrintableCodepoint = undefined;
+	}
+
+	getBuffer(): string {
+		return this.#buffer;
+	}
+
+	destroy(): void {
+		this.clear();
+	}
+}