@linxiraos/pi-tui 1.0.0

package/src/bracketed-paste.ts

@@ -0,0 +1,123 @@
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+
+export type PasteResult = { handled: false } | { handled: true; pasteContent?: string; remaining: string };
+
+// Some terminals re-encode the control bytes inside a bracketed paste as key-event
+// escape sequences (observed with tmux extended-keys passthrough under kitty). tmux
+// emits one of two formats depending on `extended-keys-format`:
+//   - csi-u:  ESC [ <codepoint> ; 5 u        (Ctrl+J → ESC [ 106 ; 5 u)
+//   - xterm:  ESC [ 27 ; 5 ; <codepoint> ~   (Ctrl+J → ESC [ 27 ; 5 ; 106 ~)
+// Callers must decode these back to the literal control byte (Ctrl+J → "\n") before
+// stripping control chars; otherwise ESC is dropped and the printable tail
+// ("[106;5u" / "[27;5;106~") leaks into the editor.
+//
+// Only Ctrl+<letter> is decoded (codepoint a-z/A-Z → 0x01..0x1A). That is the set tmux
+// actually re-encodes from paste content in practice — TAB (Ctrl+I), LF (Ctrl+J), CR
+// (Ctrl+M), VT (Ctrl+K), FF (Ctrl+L), … Non-letter Ctrl combos (NUL, ESC, FS-US, DEL)
+// never appear as re-encoded paste bytes, so they are left untouched rather than
+// synthesized into raw control bytes. Callers still strip leftover control characters
+// after decoding (the editor keeps "\n"; the single-line input strips all of them).
+const REENCODED_CTRL_CSI_U = /\x1b\[(\d+);5u/g;
+const REENCODED_CTRL_XTERM = /\x1b\[27;5;(\d+)~/g;
+
+function decodeReencodedCtrlByte(match: string, code: string): string {
+	const cp = Number(code);
+	if (cp >= 97 && cp <= 122) return String.fromCharCode(cp - 96); // a-z → Ctrl+A..Ctrl+Z
+	if (cp >= 65 && cp <= 90) return String.fromCharCode(cp - 64); // A-Z → Ctrl+A..Ctrl+Z
+	return match;
+}
+
+/**
+ * Decode tmux's re-encoded control bytes (both `extended-keys-format` variants) inside a
+ * bracketed-paste payload back to their literal byte (e.g. Ctrl+J → "\n"). Leaves the rest of
+ * the text untouched. Call before any control-character stripping so newlines/tabs survive
+ * instead of leaking the printable escape tail into the buffer.
+ */
+export function decodeReencodedPasteControls(text: string): string {
+	return text
+		.replace(REENCODED_CTRL_CSI_U, decodeReencodedCtrlByte)
+		.replace(REENCODED_CTRL_XTERM, decodeReencodedCtrlByte);
+}
+
+/**
+ * Options for {@link BracketedPasteHandler}.
+ */
+export type BracketedPasteHandlerOptions = {
+	/**
+	 * Byte cap for buffered paste content (default: 64 MiB). When exceeded,
+	 * paste mode is aborted and the accumulated content is delivered as
+	 * `pasteContent` on the same `process()` call so a lost/corrupted end
+	 * marker cannot consume unbounded memory. Mirrors `StdinBuffer#abortPaste`
+	 * — defense in depth for callers that bypass `StdinBuffer` (issue #4073
+	 * case B). The normal `ProcessTerminal` path re-wraps `StdinBuffer`'s
+	 * bounded paste with both markers, so this cap only fires on alternate
+	 * callers.
+	 */
+	byteLimit?: number;
+};
+
+const DEFAULT_BYTE_LIMIT = 64 * 1024 * 1024;
+
+/**
+ * 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.
+ */
+export class BracketedPasteHandler {
+	#buffer = "";
+	#active = false;
+	readonly #byteLimit: number;
+
+	constructor(options: BracketedPasteHandlerOptions = {}) {
+		this.#byteLimit = options.byteLimit ?? DEFAULT_BYTE_LIMIT;
+	}
+
+	/**
+	 * 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 (or the byte cap has aborted a runaway
+	 *          buffer); omitted when still buffering.
+	 */
+	process(data: string): PasteResult {
+		if (data.includes(PASTE_START)) {
+			this.#active = true;
+			this.#buffer = "";
+			data = data.replace(PASTE_START, "");
+		}
+
+		if (!this.#active) return { handled: false };
+
+		this.#buffer += data;
+
+		const endIndex = this.#buffer.indexOf(PASTE_END);
+		if (endIndex !== -1) {
+			const pasteContent = this.#buffer.substring(0, endIndex);
+			const remaining = this.#buffer.substring(endIndex + PASTE_END.length);
+
+			this.#buffer = "";
+			this.#active = false;
+
+			return { handled: true, pasteContent, remaining };
+		}
+
+		// Byte cap: a lost/corrupted end marker (ssh/tmux truncation) must not
+		// consume unbounded memory. Deliver the accumulated bytes so they are
+		// neither lost nor held forever, and reset paste mode so subsequent
+		// input recovers. See `StdinBuffer#abortPaste` for the sibling recovery
+		// semantics inside `StdinBuffer`.
+		if (this.#buffer.length > this.#byteLimit) {
+			const pasteContent = this.#buffer;
+			this.#buffer = "";
+			this.#active = false;
+			return { handled: true, pasteContent, remaining: "" };
+		}
+
+		return { handled: true, remaining: "" };
+	}
+}

package/src/components/box.ts

@@ -0,0 +1,236 @@
+import type { Component } from "../tui";
+import {
+	getPaddingX,
+	getPublishedLineWidths,
+	getWidthConfigEpoch,
+	padding,
+	publishLineWidths,
+	visibleWidth,
+} from "../utils";
+
+type Cache = {
+	width: number;
+	widthEpoch: number;
+	bgSample: string | undefined;
+	borderSample: string | undefined;
+	childLines: (readonly string[])[];
+	childWidths: (readonly number[] | undefined)[];
+	childSnapshots: (readonly string[] | undefined)[];
+	result: string[];
+};
+
+/** Box-drawing glyphs plus an optional colorizer for an outline drawn around a {@link Box}. */
+export interface BoxBorder {
+	chars: {
+		topLeft: string;
+		topRight: string;
+		bottomLeft: string;
+		bottomRight: string;
+		horizontal: string;
+		vertical: string;
+	};
+	color?: (text: string) => string;
+}
+
+/**
+ * Box component - a container that applies padding and background to all children
+ */
+export class Box implements Component {
+	children: Component[] = [];
+	#paddingX: number;
+	#paddingY: number;
+	#bgFn?: (text: string) => string;
+	#border?: BoxBorder;
+
+	#ignoreTight = false;
+
+	setIgnoreTight(ignore: boolean): this {
+		this.#ignoreTight = ignore;
+		this.#invalidateCache();
+		return this;
+	}
+
+	// Cache for rendered output
+	#cached?: Cache;
+
+	constructor(paddingX = 1, paddingY = 1, bgFn?: (text: string) => string, border?: BoxBorder) {
+		this.#paddingX = paddingX;
+		this.#paddingY = paddingY;
+		this.#bgFn = bgFn;
+		this.#border = border;
+	}
+
+	addChild(component: Component): void {
+		this.children.push(component);
+		if (this.#ignoreTight) {
+			component.setIgnoreTight?.(true);
+		}
+		this.#invalidateCache();
+	}
+
+	removeChild(component: Component): void {
+		const index = this.children.indexOf(component);
+		if (index !== -1) {
+			this.children.splice(index, 1);
+			this.#invalidateCache();
+		}
+	}
+
+	clear(): void {
+		this.children = [];
+		this.#invalidateCache();
+	}
+
+	setPaddingX(paddingX: number): void {
+		if (this.#paddingX === paddingX) return;
+		this.#paddingX = paddingX;
+		this.#invalidateCache();
+	}
+
+	setPaddingY(paddingY: number): void {
+		if (this.#paddingY === paddingY) return;
+		this.#paddingY = paddingY;
+		this.#invalidateCache();
+	}
+
+	setBgFn(bgFn?: (text: string) => string): void {
+		this.#bgFn = bgFn;
+		// Don't invalidate here - we'll detect bgFn changes by sampling output
+	}
+
+	setBorder(border?: BoxBorder): void {
+		this.#border = border;
+		this.#invalidateCache();
+	}
+
+	#invalidateCache(): void {
+		this.#cached = undefined;
+	}
+
+	invalidate(): void {
+		this.#invalidateCache();
+		for (const child of this.children) {
+			child.invalidate?.();
+		}
+	}
+
+	render(width: number): readonly string[] {
+		const children = this.children;
+		const count = children.length;
+		const paddingX = this.#ignoreTight ? this.#paddingX : getPaddingX(this.#paddingX);
+		// A border eats one column on each side; skip it unless the interior can still
+		// hold the horizontal padding plus at least one content column, so a bordered
+		// Box never overflows the width it was given.
+		const border = this.#border && width - 2 >= paddingX * 2 + 1 ? this.#border : undefined;
+		const innerWidth = border ? width - 2 : width;
+		const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+		// bgFn / border output can change without the function reference changing
+		// (theme mutation); sample both so a silent palette swap still misses the cache.
+		const bgSample = this.#bgFn ? this.#bgFn("test") : undefined;
+		const borderSample = border
+			? `${border.color ? border.color("|") : "|"}${border.chars.topLeft}${border.chars.vertical}`
+			: undefined;
+
+		// Render every child every frame (renders may carry side effects); the
+		// memo only skips re-deriving the padded/background rows.
+		const widthEpoch = getWidthConfigEpoch();
+		let contentRows = 0;
+		const childLines = children.map(child => {
+			const lines = child.render(contentWidth);
+			contentRows += lines.length;
+			return lines;
+		});
+		const childWidths = childLines.map(lines => getPublishedLineWidths(lines));
+		const cached = this.#cached;
+		if (
+			cached !== undefined &&
+			cached.width === width &&
+			cached.widthEpoch === widthEpoch &&
+			cached.widthEpoch === getWidthConfigEpoch() &&
+			cached.bgSample === bgSample &&
+			cached.borderSample === borderSample &&
+			cached.childLines.length === count &&
+			childLines.every((lines, i) => {
+				if (cached.childLines[i] !== lines) return false;
+				const published = childWidths[i];
+				const cachedPublished = cached.childWidths[i];
+				if (published !== undefined || cachedPublished !== undefined) {
+					return published === cachedPublished;
+				}
+				const snapshot = cached.childSnapshots[i];
+				return (
+					snapshot !== undefined &&
+					snapshot.length === lines.length &&
+					lines.every((line, j) => snapshot[j] === line)
+				);
+			})
+		) {
+			return cached.result;
+		}
+
+		const result: string[] = [];
+		// Exact visible widths of `result` rows, published only when the row
+		// bytes are `content + spaces` (no bg/border transform of unknown width).
+		const resultWidths: number[] | undefined = !border && !this.#bgFn ? [] : undefined;
+		if (contentRows > 0) {
+			const leftPad = padding(paddingX);
+			const interior: string[] = [];
+			const pushRow = (row: string, visLen: number): void => {
+				const padNeeded = Math.max(0, innerWidth - visLen);
+				const padded = padNeeded > 0 ? row + padding(padNeeded) : row;
+				interior.push(this.#bgFn ? this.#bgFn(padded) : padded);
+				resultWidths?.push(visLen + padNeeded);
+			};
+			// Top padding
+			for (let i = 0; i < this.#paddingY; i++) {
+				pushRow("", 0);
+			}
+			// Content
+			let childIndex = 0;
+			for (const lines of childLines) {
+				const widths = childWidths[childIndex++];
+				for (let j = 0; j < lines.length; j++) {
+					const line = lines[j] ?? "";
+					const row = paddingX > 0 ? leftPad + line : line;
+					const carried = widths?.[j];
+					const visLen = carried !== undefined && paddingX === 0 ? carried : visibleWidth(row);
+					pushRow(row, visLen);
+				}
+			}
+			// Bottom padding
+			for (let i = 0; i < this.#paddingY; i++) {
+				pushRow("", 0);
+			}
+
+			if (border) {
+				const paint = border.color ?? (s => s);
+				const rule = border.chars.horizontal.repeat(Math.max(0, innerWidth));
+				const side = paint(border.chars.vertical);
+				result.push(paint(border.chars.topLeft + rule + border.chars.topRight));
+				for (const row of interior) {
+					result.push(side + row + side);
+				}
+				result.push(paint(border.chars.bottomLeft + rule + border.chars.bottomRight));
+			} else {
+				for (const row of interior) {
+					result.push(row);
+				}
+			}
+		}
+
+		const finalWidthEpoch = getWidthConfigEpoch();
+		if (resultWidths !== undefined) publishLineWidths(result, resultWidths);
+		const childSnapshots = childLines.map((lines, i) => (childWidths[i] === undefined ? [...lines] : undefined));
+		this.#cached = {
+			width,
+			widthEpoch: finalWidthEpoch,
+			bgSample,
+			borderSample,
+			childLines,
+			childWidths,
+			childSnapshots,
+			result,
+		};
+		return result;
+	}
+}

package/src/components/cancellable-loader.ts

@@ -0,0 +1,40 @@
+import { getKeybindings } from "../keybindings";
+import { Loader } from "./loader";
+
+/**
+ * Loader that can be cancelled with Escape.
+ * Extends Loader with an AbortSignal for cancelling async operations.
+ *
+ * @example
+ * const loader = new CancellableLoader(tui, cyan, dim, "Working...");
+ * loader.onAbort = () => done(null);
+ * doWork(loader.signal).then(done);
+ */
+export class CancellableLoader extends Loader {
+	#abortController = new AbortController();
+
+	/** Called when user presses Escape */
+	onAbort?: () => void;
+
+	/** AbortSignal that is aborted when user presses Escape */
+	get signal(): AbortSignal {
+		return this.#abortController.signal;
+	}
+
+	/** Whether the loader was aborted */
+	get aborted(): boolean {
+		return this.#abortController.signal.aborted;
+	}
+
+	handleInput(data: string): void {
+		const kb = getKeybindings();
+		if (kb.matches(data, "tui.select.cancel")) {
+			this.#abortController.abort();
+			this.onAbort?.();
+		}
+	}
+
+	override dispose(): void {
+		this.stop();
+	}
+}