ptywright 0.1.0 → 0.2.0

package/dist/terminal_session-DopC7Xg6.mjs

@@ -0,0 +1,893 @@
+import { Terminal } from "@xterm/headless";
+//#region src/terminal/keys.ts
+const CSI = "\x1B[";
+const SS3 = "\x1BO";
+function ctrlChar(letter) {
+	const code = letter.toUpperCase().charCodeAt(0);
+	if (code < 65 || code > 90) throw new Error(`Unsupported ctrl key: ${letter}`);
+	return String.fromCharCode(code - 64);
+}
+function encodeKey(key) {
+	const normalized = key.trim();
+	if (normalized.length === 1) return normalized;
+	const ctrlMatch = /^c-(.)$/i.exec(normalized);
+	if (ctrlMatch) return ctrlChar(ctrlMatch[1] ?? "");
+	const parsed = parseKeySpec(normalized);
+	const mod = modifierParam(parsed.modifiers);
+	const keyName = parsed.key.toLowerCase();
+	if (keyName === "enter" || keyName === "return") return "\r";
+	if (keyName === "esc" || keyName === "escape") return "\x1B";
+	if (keyName === "backspace") return "";
+	if (keyName === "space") return " ";
+	if (keyName === "tab") return parsed.modifiers.shift ? `${CSI}Z` : "	";
+	if (keyName === "backtab" || keyName === "btab") return `${CSI}Z`;
+	const arrowFinal = arrowKeyFinal(keyName);
+	if (arrowFinal) {
+		if (mod === null) return `${CSI}${arrowFinal}`;
+		return `${CSI}1;${mod}${arrowFinal}`;
+	}
+	const homeEndFinal = homeEndFinalChar(keyName);
+	if (homeEndFinal) {
+		if (mod === null) return `${CSI}${homeEndFinal}`;
+		return `${CSI}1;${mod}${homeEndFinal}`;
+	}
+	const tildeCode = tildeKeyCode(keyName);
+	if (tildeCode) {
+		if (mod === null) return `${CSI}${tildeCode}~`;
+		return `${CSI}${tildeCode};${mod}~`;
+	}
+	const functionKey = functionKeySpec(keyName);
+	if (functionKey) {
+		if (mod === null) return functionKey.base;
+		return functionKey.modified(mod);
+	}
+	if (parsed.key.length === 1) {
+		let outChar = parsed.key;
+		if (parsed.modifiers.shift && /^[a-z]$/i.test(outChar)) outChar = outChar.toUpperCase();
+		let encoded = outChar;
+		if (parsed.modifiers.ctrl && /^[a-z]$/i.test(outChar)) encoded = ctrlChar(outChar);
+		if (parsed.modifiers.alt) encoded = `\x1b${encoded}`;
+		return encoded;
+	}
+	throw new Error(`Unsupported key: ${key}`);
+}
+function parseKeySpec(spec) {
+	const tokens = spec.trim().split(/[+-]/g).map((t) => t.trim()).filter(Boolean);
+	const modifiers = {
+		shift: false,
+		alt: false,
+		ctrl: false
+	};
+	const keys = [];
+	for (const token of tokens) {
+		const lower = token.toLowerCase();
+		if (lower === "shift") {
+			modifiers.shift = true;
+			continue;
+		}
+		if (lower === "alt" || lower === "meta") {
+			modifiers.alt = true;
+			continue;
+		}
+		if (lower === "ctrl" || lower === "control") {
+			modifiers.ctrl = true;
+			continue;
+		}
+		keys.push(token);
+	}
+	const key = keys.join("+").trim();
+	if (!key) throw new Error(`Unsupported key: ${spec}`);
+	return {
+		modifiers,
+		key
+	};
+}
+function modifierParam(mods) {
+	if (!mods.shift && !mods.alt && !mods.ctrl) return null;
+	return 1 + (mods.shift ? 1 : 0) + (mods.alt ? 2 : 0) + (mods.ctrl ? 4 : 0);
+}
+function arrowKeyFinal(key) {
+	if (key === "up") return "A";
+	if (key === "down") return "B";
+	if (key === "right") return "C";
+	if (key === "left") return "D";
+	return null;
+}
+function homeEndFinalChar(key) {
+	if (key === "home") return "H";
+	if (key === "end") return "F";
+	return null;
+}
+function tildeKeyCode(key) {
+	if (key === "pageup" || key === "pgup") return "5";
+	if (key === "pagedown" || key === "pgdn") return "6";
+	if (key === "insert" || key === "ins") return "2";
+	if (key === "delete" || key === "del") return "3";
+	return null;
+}
+function functionKeySpec(key) {
+	const match = /^f(\d{1,2})$/.exec(key);
+	if (!match) return null;
+	const n = Number(match[1]);
+	if (!Number.isFinite(n) || n < 1 || n > 12) return null;
+	if (n === 1) return {
+		base: `${SS3}P`,
+		modified: (m) => `${CSI}1;${m}P`
+	};
+	if (n === 2) return {
+		base: `${SS3}Q`,
+		modified: (m) => `${CSI}1;${m}Q`
+	};
+	if (n === 3) return {
+		base: `${SS3}R`,
+		modified: (m) => `${CSI}1;${m}R`
+	};
+	if (n === 4) return {
+		base: `${SS3}S`,
+		modified: (m) => `${CSI}1;${m}S`
+	};
+	const code = {
+		5: "15",
+		6: "17",
+		7: "18",
+		8: "19",
+		9: "20",
+		10: "21",
+		11: "23",
+		12: "24"
+	}[n];
+	if (!code) return null;
+	return {
+		base: `${CSI}${code}~`,
+		modified: (m) => `${CSI}${code};${m}~`
+	};
+}
+//#endregion
+//#region src/terminal/style.ts
+const DEFAULT_STYLE = {
+	fg: { mode: "default" },
+	bg: { mode: "default" },
+	bold: false,
+	dim: false,
+	italic: false,
+	underline: false,
+	inverse: false,
+	strikethrough: false
+};
+function extractStyle(cell) {
+	const style = {
+		fg: extractColor(cell.isFgDefault(), cell.isFgPalette(), cell.isFgRGB(), cell.getFgColor()),
+		bg: extractColor(cell.isBgDefault(), cell.isBgPalette(), cell.isBgRGB(), cell.getBgColor()),
+		bold: cell.isBold() !== 0,
+		dim: cell.isDim() !== 0,
+		italic: cell.isItalic() !== 0,
+		underline: cell.isUnderline() !== 0,
+		inverse: cell.isInverse() !== 0,
+		strikethrough: cell.isStrikethrough() !== 0
+	};
+	return isDefaultStyle(style) ? DEFAULT_STYLE : style;
+}
+function isDefaultStyle(style) {
+	return style.fg.mode === "default" && style.bg.mode === "default" && !style.bold && !style.dim && !style.italic && !style.underline && !style.inverse && !style.strikethrough;
+}
+function styleKey(style) {
+	return [
+		style.fg.mode === "default" ? "d" : `${style.fg.mode}:${style.fg.value}`,
+		style.bg.mode === "default" ? "d" : `${style.bg.mode}:${style.bg.value}`,
+		style.bold ? "b" : "",
+		style.dim ? "d" : "",
+		style.italic ? "i" : "",
+		style.underline ? "u" : "",
+		style.inverse ? "r" : "",
+		style.strikethrough ? "s" : ""
+	].join("|");
+}
+function findMeaningfulEndCol(line, cols, nullCell) {
+	if (!line) return 0;
+	for (let x = cols - 1; x >= 0; x -= 1) {
+		const cell = line.getCell(x, nullCell);
+		if (!cell) continue;
+		if (cell.getWidth() === 0) continue;
+		const chars = cell.getChars();
+		const style = extractStyle(cell);
+		if (chars !== "" && chars !== " " || !isDefaultStyle(style)) return x + 1;
+	}
+	return 0;
+}
+function extractColor(isDefault, isPalette, isRgb, value) {
+	if (isDefault) return { mode: "default" };
+	if (isRgb) return {
+		mode: "rgb",
+		value
+	};
+	if (isPalette) return {
+		mode: "palette",
+		value
+	};
+	return { mode: "default" };
+}
+//#endregion
+//#region src/terminal/ansi.ts
+const ESC$2 = "\x1B";
+const SGR_RESET = `${ESC$2}[0m`;
+function renderAnsiLines(terminal, options) {
+	const scope = options?.scope ?? "visible";
+	const trimRight = options?.trimRight ?? false;
+	const buffer = terminal.buffer.active;
+	const nullCell = buffer.getNullCell();
+	let startY = 0;
+	let count = buffer.length;
+	if (scope === "visible") {
+		startY = buffer.viewportY;
+		count = terminal.rows;
+	}
+	const out = [];
+	for (let i = 0; i < count; i += 1) {
+		const y = startY + i;
+		const line = buffer.getLine(y);
+		out.push(renderLine(line, terminal.cols, nullCell, trimRight));
+	}
+	return out;
+}
+function renderLine(line, cols, nullCell, trimRight) {
+	let endCol = cols;
+	if (trimRight) endCol = findMeaningfulEndCol(line, cols, nullCell);
+	let ansi = "";
+	let plain = "";
+	let hasStyle = false;
+	let usedSgr = false;
+	const defaultKey = styleKey(DEFAULT_STYLE);
+	let currentKey = defaultKey;
+	for (let x = 0; x < endCol; x += 1) {
+		const cell = line?.getCell(x, nullCell);
+		if (!cell) {
+			plain += " ";
+			ansi += " ";
+			continue;
+		}
+		if (cell.getWidth() === 0) continue;
+		const chars = cell.getChars() || " ";
+		const style = extractStyle(cell);
+		const isDefault = isDefaultStyle(style);
+		if (!isDefault) hasStyle = true;
+		const key = styleKey(style);
+		if (key !== currentKey) {
+			ansi += isDefault ? SGR_RESET : toSgr(style);
+			usedSgr = true;
+			currentKey = key;
+		}
+		ansi += chars;
+		plain += chars;
+	}
+	if (usedSgr && currentKey !== defaultKey) ansi += SGR_RESET;
+	return {
+		ansi,
+		plain,
+		hasStyle
+	};
+}
+function toSgr(style) {
+	const codes = ["0"];
+	if (style.bold) codes.push("1");
+	if (style.dim) codes.push("2");
+	if (style.italic) codes.push("3");
+	if (style.underline) codes.push("4");
+	if (style.inverse) codes.push("7");
+	if (style.strikethrough) codes.push("9");
+	if (style.fg.mode === "palette") codes.push(`38;5;${style.fg.value}`);
+	else if (style.fg.mode === "rgb") {
+		const [r, g, b] = rgb(style.fg.value);
+		codes.push(`38;2;${r};${g};${b}`);
+	}
+	if (style.bg.mode === "palette") codes.push(`48;5;${style.bg.value}`);
+	else if (style.bg.mode === "rgb") {
+		const [r, g, b] = rgb(style.bg.value);
+		codes.push(`48;2;${r};${g};${b}`);
+	}
+	return `${ESC$2}[${codes.join(";")}m`;
+}
+function rgb(value) {
+	return [
+		value >> 16 & 255,
+		value >> 8 & 255,
+		value & 255
+	];
+}
+//#endregion
+//#region src/terminal/mouse.ts
+const ESC$1 = "\x1B";
+function encodeSgrMouse(event) {
+	const x = clampInt(event.x, 1, 500);
+	const y = clampInt(event.y, 1, 300);
+	if (event.action === "click") return `${encodeSingleSgrMouse({
+		...event,
+		action: "down"
+	}, x, y)}${encodeSingleSgrMouse({
+		...event,
+		action: "up"
+	}, x, y)}`;
+	return encodeSingleSgrMouse(event, x, y);
+}
+function encodeSingleSgrMouse(event, x, y) {
+	const modifiers = event.modifiers;
+	const modifierBits = (modifiers?.shift ? 4 : 0) + (modifiers?.alt ? 8 : 0) + (modifiers?.ctrl ? 16 : 0);
+	const buttonCode = buttonToCode(event.button ?? "left");
+	if (event.action === "down") return `${ESC$1}[<${buttonCode + modifierBits};${x};${y}M`;
+	if (event.action === "up") return `${ESC$1}[<${buttonCode + modifierBits};${x};${y}m`;
+	if (event.action === "scroll_up") return `${ESC$1}[<${64 + modifierBits};${x};${y}M`;
+	if (event.action === "scroll_down") return `${ESC$1}[<${65 + modifierBits};${x};${y}M`;
+	return `${ESC$1}[<${32 + (event.button ? buttonCode : 3) + modifierBits};${x};${y}M`;
+}
+function buttonToCode(button) {
+	if (button === "left") return 0;
+	if (button === "middle") return 1;
+	return 2;
+}
+function clampInt(value, min, max) {
+	if (!Number.isFinite(value)) return min;
+	const int = Math.trunc(value);
+	if (int < min) return min;
+	if (int > max) return max;
+	return int;
+}
+//#endregion
+//#region src/terminal/snapshot.ts
+function snapshotVisibleLines(terminal, trimRight) {
+	const buffer = terminal.buffer.active;
+	const nullCell = buffer.getNullCell();
+	const startY = buffer.viewportY;
+	const lines = [];
+	for (let row = 0; row < terminal.rows; row += 1) {
+		const line = buffer.getLine(startY + row);
+		lines.push(snapshotPlainLine(line, terminal.cols, nullCell, trimRight));
+	}
+	return lines;
+}
+function snapshotVisibleStyleRuns(terminal, trimRight) {
+	const buffer = terminal.buffer.active;
+	const nullCell = buffer.getNullCell();
+	const startY = buffer.viewportY;
+	const out = [];
+	for (let row = 0; row < terminal.rows; row += 1) {
+		const line = buffer.getLine(startY + row);
+		out.push(snapshotStyleRuns(line, terminal.cols, nullCell, trimRight));
+	}
+	return out;
+}
+function snapshotBufferLines(terminal, trimRight) {
+	const buffer = terminal.buffer.active;
+	const lines = [];
+	for (let y = 0; y < buffer.length; y += 1) {
+		const line = buffer.getLine(y);
+		lines.push(line ? line.translateToString(trimRight, 0, terminal.cols) : "");
+	}
+	return lines;
+}
+function snapshotLines(terminal, options) {
+	const trimRight = options?.trimRight ?? true;
+	return (options?.scope ?? "visible") === "buffer" ? snapshotBufferLines(terminal, trimRight) : snapshotVisibleLines(terminal, trimRight);
+}
+function snapshotGrid(terminal, options) {
+	const trimRight = options?.trimRight ?? true;
+	const includeStyles = options?.includeStyles ?? false;
+	const buffer = terminal.buffer.active;
+	const lines = snapshotVisibleLines(terminal, trimRight);
+	return {
+		cols: terminal.cols,
+		rows: terminal.rows,
+		bufferType: buffer.type,
+		cursorX: buffer.cursorX,
+		cursorY: buffer.cursorY,
+		viewportY: buffer.viewportY,
+		lines,
+		styleRuns: includeStyles ? snapshotVisibleStyleRuns(terminal, trimRight) : void 0
+	};
+}
+function snapshotPlainLine(line, cols, nullCell, trimRight) {
+	let endCol = cols;
+	if (trimRight) endCol = findMeaningfulEndCol(line, cols, nullCell);
+	let out = "";
+	for (let x = 0; x < endCol; x += 1) {
+		const cell = line?.getCell(x, nullCell);
+		if (!cell) {
+			out += " ";
+			continue;
+		}
+		if (cell.getWidth() === 0) continue;
+		out += cell.getChars() || " ";
+	}
+	return out;
+}
+function snapshotStyleRuns(line, cols, nullCell, trimRight) {
+	let endCol = cols;
+	if (trimRight) endCol = findMeaningfulEndCol(line, cols, nullCell);
+	const out = [];
+	let currentKey = null;
+	let currentRun = null;
+	for (let x = 0; x < endCol; x += 1) {
+		const cell = line?.getCell(x, nullCell);
+		if (!cell) {
+			if (currentRun) {
+				out.push(currentRun);
+				currentRun = null;
+				currentKey = null;
+			}
+			continue;
+		}
+		const width = cell.getWidth();
+		if (width === 0) continue;
+		const style = extractStyle(cell);
+		if (isDefaultStyle(style)) {
+			if (currentRun) {
+				out.push(currentRun);
+				currentRun = null;
+				currentKey = null;
+			}
+			continue;
+		}
+		const key = styleKey(style);
+		if (currentRun && key === currentKey) {
+			currentRun.endCol = x + width;
+			continue;
+		}
+		if (currentRun) out.push(currentRun);
+		currentKey = key;
+		currentRun = {
+			startCol: x,
+			endCol: x + width,
+			style
+		};
+	}
+	if (currentRun) out.push(currentRun);
+	return out;
+}
+//#endregion
+//#region src/terminal/mask.ts
+function applyTextMaskRules(lines, rules) {
+	if (!rules || rules.length === 0) return lines;
+	const compiled = compileMaskRules(rules);
+	if (compiled.length === 0) return lines;
+	return lines.map((line) => applyCompiledMaskRules(line, compiled));
+}
+function compileMaskRules(rules) {
+	const compiled = [];
+	for (const rule of rules) {
+		if (!rule.regex.trim()) continue;
+		const preserveLength = rule.preserveLength ?? false;
+		const replacement = preserveLength ? firstChar(rule.replacement) : rule.replacement ?? "<masked>";
+		const flags = normalizeFlags(rule.flags);
+		let regex;
+		try {
+			regex = new RegExp(rule.regex, flags);
+		} catch (error) {
+			throw new Error(`invalid mask rule regex=${JSON.stringify(rule.regex)} flags=${JSON.stringify(rule.flags ?? "")}: ${error.message}`);
+		}
+		compiled.push({
+			regex,
+			replacement,
+			preserveLength
+		});
+	}
+	return compiled;
+}
+function normalizeFlags(flags) {
+	const value = flags?.trim() ? flags.trim() : "g";
+	const set = new Set(value.split(""));
+	set.add("g");
+	return [...set].join("");
+}
+function firstChar(value) {
+	const trimmed = value?.trim();
+	return trimmed && trimmed.length > 0 ? trimmed[0] : "█";
+}
+function applyCompiledMaskRules(line, rules) {
+	let out = line;
+	for (const rule of rules) out = out.replace(rule.regex, (match) => rule.preserveLength ? rule.replacement.repeat(match.length) : rule.replacement);
+	return out;
+}
+//#endregion
+//#region src/util/hash.ts
+function fnv1a32(text) {
+	let hash = 2166136261;
+	for (let i = 0; i < text.length; i += 1) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+//#endregion
+//#region src/util/sleep.ts
+async function sleep(ms) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+//#region src/trace/asciicast.ts
+function encodeAsciicast(header, events) {
+	const lines = [JSON.stringify(header)];
+	for (const event of events) lines.push(JSON.stringify(event));
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/trace/recorder.ts
+const DEFAULT_MAX_EVENTS = 5e4;
+const DEFAULT_MAX_DATA_CHARS = 5e6;
+const DEFAULT_TIME_PRECISION_MS = 1;
+var TraceRecorder = class {
+	header;
+	startedAtMs;
+	maxEvents;
+	maxDataChars;
+	mergeOutput;
+	timePrecisionMs;
+	events = [];
+	dataChars = 0;
+	droppedEvents = 0;
+	droppedDataChars = 0;
+	constructor(header, options) {
+		this.header = header;
+		this.startedAtMs = performance.now();
+		this.maxEvents = Math.max(1, Math.trunc(options?.maxEvents ?? DEFAULT_MAX_EVENTS));
+		this.maxDataChars = Math.max(1, Math.trunc(options?.maxDataChars ?? DEFAULT_MAX_DATA_CHARS));
+		this.mergeOutput = options?.mergeOutput ?? true;
+		this.timePrecisionMs = Math.max(1, Math.trunc(options?.timePrecisionMs ?? DEFAULT_TIME_PRECISION_MS));
+	}
+	recordOutput(data) {
+		this.addEvent("o", data);
+	}
+	recordInput(data) {
+		this.addEvent("i", data);
+	}
+	recordResize(cols, rows) {
+		this.addEvent("r", `${cols}x${rows}`);
+	}
+	mark(label) {
+		this.addEvent("m", label ?? "");
+	}
+	snapshot(options) {
+		const tailEvents = options?.tailEvents;
+		const events = tailEvents ? this.events.slice(-Math.max(0, Math.trunc(tailEvents))) : [...this.events];
+		return {
+			header: this.header,
+			events,
+			cast: encodeAsciicast(this.header, events),
+			droppedEvents: this.droppedEvents,
+			droppedDataChars: this.droppedDataChars
+		};
+	}
+	addEvent(type, data) {
+		const timeSeconds = this.nowSeconds();
+		const last = this.events.at(-1);
+		if (this.mergeOutput && type === "o" && last && last[1] === "o" && last[0] === timeSeconds) {
+			last[2] += data;
+			this.dataChars += data.length;
+			this.trim();
+			return;
+		}
+		this.events.push([
+			timeSeconds,
+			type,
+			data
+		]);
+		this.dataChars += data.length;
+		this.trim();
+	}
+	nowSeconds() {
+		const elapsedMs = performance.now() - this.startedAtMs;
+		return Math.round(elapsedMs / this.timePrecisionMs) * this.timePrecisionMs / 1e3;
+	}
+	trim() {
+		while (this.events.length > this.maxEvents || this.dataChars > this.maxDataChars) {
+			const removed = this.events.shift();
+			if (!removed) break;
+			const chars = removed[2].length;
+			this.dataChars -= chars;
+			this.droppedEvents += 1;
+			this.droppedDataChars += chars;
+		}
+	}
+};
+//#endregion
+//#region src/session/terminal_session.ts
+const ESC = "\x1B";
+var TerminalSession = class {
+	id;
+	pty;
+	terminal;
+	snapshotRingSize;
+	trace;
+	writeChain = Promise.resolve();
+	disposables = [];
+	rawOutputRing = [];
+	snapshotRing = [];
+	closed = null;
+	constructor(options) {
+		this.id = options.id;
+		this.pty = options.pty;
+		this.snapshotRingSize = options.snapshotRingSize;
+		this.terminal = new Terminal({
+			cols: options.cols,
+			rows: options.rows,
+			allowProposedApi: true,
+			scrollback: 2e3,
+			convertEol: true
+		});
+		this.trace = new TraceRecorder({
+			version: 2,
+			width: options.cols,
+			height: options.rows,
+			timestamp: Math.floor(Date.now() / 1e3),
+			env: options.trace?.env,
+			title: options.trace?.title ?? options.id,
+			command: options.trace?.command,
+			term: options.trace?.env?.TERM
+		});
+		this.disposables.push(this.terminal.parser.registerCsiHandler({ final: "n" }, (params) => this.handleCsiDsr(params)));
+		this.disposables.push(this.terminal.parser.registerCsiHandler({ final: "c" }, (params) => this.handleCsiDa(params)));
+		this.disposables.push(this.pty.onData((data) => {
+			this.appendRawOutput(data);
+			this.trace.recordOutput(data);
+			this.enqueueWrite(data);
+		}));
+		this.disposables.push(this.pty.onExit((event) => {
+			this.closed = {
+				type: "process_exit",
+				exitCode: event.exitCode,
+				signal: event.signal
+			};
+		}));
+	}
+	get cols() {
+		return this.terminal.cols;
+	}
+	get rows() {
+		return this.terminal.rows;
+	}
+	isClosed() {
+		return this.closed !== null;
+	}
+	getCloseReason() {
+		return this.closed;
+	}
+	resize(cols, rows) {
+		this.trace.recordResize(cols, rows);
+		this.pty.resize(cols, rows);
+		this.terminal.resize(cols, rows);
+	}
+	sendText(text, options) {
+		const payload = options?.enter ?? false ? `${text}\r` : text;
+		this.trace.recordInput(payload);
+		this.pty.write(payload);
+	}
+	pressKey(key) {
+		const encoded = encodeKey(key);
+		this.trace.recordInput(encoded);
+		this.pty.write(encoded);
+	}
+	sendMouse(event) {
+		const encoded = encodeSgrMouse(event);
+		this.trace.recordInput(encoded);
+		this.pty.write(encoded);
+	}
+	async flush() {
+		await this.writeChain;
+	}
+	getMeta() {
+		const buffer = this.terminal.buffer.active;
+		return {
+			cols: this.terminal.cols,
+			rows: this.terminal.rows,
+			bufferType: buffer.type,
+			viewportY: buffer.viewportY,
+			baseY: buffer.baseY,
+			length: buffer.length,
+			cursorX: buffer.cursorX,
+			cursorY: buffer.cursorY
+		};
+	}
+	async snapshotText(options) {
+		await this.flush();
+		if (options?.maxLines !== void 0 && options.tailLines !== void 0) throw new Error("snapshotText: maxLines and tailLines are mutually exclusive");
+		let lines = snapshotLines(this.terminal, {
+			scope: options?.scope,
+			trimRight: options?.trimRight
+		});
+		if (options?.trimBottom ?? true) lines = trimBottomEmptyLines(lines);
+		if (options?.maxLines !== void 0) {
+			const max = Math.max(0, Math.trunc(options.maxLines));
+			lines = lines.slice(0, max);
+		}
+		if (options?.tailLines !== void 0) {
+			const tail = Math.max(0, Math.trunc(options.tailLines));
+			lines = lines.slice(Math.max(0, lines.length - tail));
+		}
+		lines = applyTextMaskRules(lines, options?.mask);
+		const text = lines.join("\n");
+		const hash = fnv1a32(text);
+		if (options?.captureFrame ?? true) this.captureFrame(text, hash);
+		return {
+			text,
+			hash
+		};
+	}
+	async snapshotAnsi(options) {
+		await this.flush();
+		if (options?.maxLines !== void 0 && options.tailLines !== void 0) throw new Error("snapshotAnsi: maxLines and tailLines are mutually exclusive");
+		let lines = renderAnsiLines(this.terminal, {
+			scope: options?.scope,
+			trimRight: options?.trimRight
+		});
+		if (options?.trimBottom ?? true) lines = trimBottomEmptyAnsiLines(lines);
+		if (options?.maxLines !== void 0) {
+			const max = Math.max(0, Math.trunc(options.maxLines));
+			lines = lines.slice(0, max);
+		}
+		if (options?.tailLines !== void 0) {
+			const tail = Math.max(0, Math.trunc(options.tailLines));
+			lines = lines.slice(Math.max(0, lines.length - tail));
+		}
+		if (options?.mask && options.mask.length > 0) {
+			const maskedPlain = applyTextMaskRules(lines.map((line) => line.plain), options.mask);
+			const maskedAnsi = applyTextMaskRules(lines.map((line) => line.ansi), options.mask);
+			lines = lines.map((line, idx) => ({
+				...line,
+				plain: maskedPlain[idx] ?? "",
+				ansi: maskedAnsi[idx] ?? ""
+			}));
+		}
+		const ansi = lines.map((l) => l.ansi).join("\n");
+		return {
+			ansi,
+			plain: lines.map((l) => l.plain).join("\n"),
+			hash: fnv1a32(ansi),
+			lines
+		};
+	}
+	async snapshotGrid(options) {
+		await this.flush();
+		const grid = snapshotGrid(this.terminal, {
+			trimRight: options?.trimRight,
+			includeStyles: options?.includeStyles
+		});
+		const hash = fnv1a32(JSON.stringify(grid));
+		if (options?.captureFrame ?? true) this.captureFrame(grid.lines.join("\n"), hash);
+		return {
+			grid,
+			hash
+		};
+	}
+	async snapshotCast(options) {
+		await this.flush();
+		return this.trace.snapshot({ tailEvents: options?.tailEvents });
+	}
+	mark(label) {
+		this.trace.mark(label);
+	}
+	getSnapshotFrames() {
+		return [...this.snapshotRing];
+	}
+	getRawOutputChunks() {
+		return [...this.rawOutputRing];
+	}
+	async waitForText(args) {
+		const startedAt = Date.now();
+		let closedSince = null;
+		while (Date.now() - startedAt <= args.timeoutMs) {
+			const snapshot = await this.snapshotText({
+				captureFrame: true,
+				scope: args.scope
+			});
+			if (args.text && snapshot.text.includes(args.text)) return {
+				found: true,
+				...snapshot
+			};
+			if (args.regex && args.regex.test(snapshot.text)) return {
+				found: true,
+				...snapshot
+			};
+			if (this.isClosed()) {
+				closedSince ??= Date.now();
+				const drainMs = Math.max(500, args.intervalMs * 4);
+				if (Date.now() - closedSince >= drainMs) break;
+			}
+			await sleep(args.intervalMs);
+		}
+		return {
+			found: false,
+			...await this.snapshotText({
+				captureFrame: true,
+				scope: args.scope
+			})
+		};
+	}
+	async waitForStableScreen(args) {
+		const startedAt = Date.now();
+		let stableSince = null;
+		let lastHash = null;
+		while (Date.now() - startedAt <= args.timeoutMs) {
+			const snapshot = await this.snapshotText({ captureFrame: true });
+			if (snapshot.hash === lastHash) stableSince ??= Date.now();
+			else {
+				stableSince = null;
+				lastHash = snapshot.hash;
+			}
+			if (stableSince !== null && Date.now() - stableSince >= args.quietMs) return {
+				stable: true,
+				...snapshot
+			};
+			await sleep(args.intervalMs);
+		}
+		return {
+			stable: false,
+			...await this.snapshotText({ captureFrame: true })
+		};
+	}
+	close() {
+		if (this.closed === null) this.closed = { type: "closed_by_user" };
+		this.pty.kill();
+		for (const d of this.disposables) d.dispose();
+		this.terminal.dispose();
+	}
+	enqueueWrite(data) {
+		this.writeChain = this.writeChain.then(() => new Promise((resolve) => {
+			this.terminal.write(data, resolve);
+		}));
+	}
+	appendRawOutput(data) {
+		this.rawOutputRing.push(data);
+		if (this.rawOutputRing.length > 2e3) this.rawOutputRing.splice(0, this.rawOutputRing.length - 2e3);
+	}
+	captureFrame(text, hash) {
+		this.snapshotRing.push({
+			atMs: Date.now(),
+			hash,
+			text
+		});
+		if (this.snapshotRing.length > this.snapshotRingSize) this.snapshotRing.splice(0, this.snapshotRing.length - this.snapshotRingSize);
+	}
+	writePtySafely(data) {
+		if (this.isClosed()) return;
+		try {
+			this.pty.write(data);
+		} catch {}
+	}
+	handleCsiDsr(params) {
+		if (params.length !== 1) return false;
+		const raw = params[0];
+		const value = Array.isArray(raw) ? raw[0] : raw;
+		if (value === 5) {
+			this.writePtySafely(`${ESC}[0n`);
+			return true;
+		}
+		if (value !== 6) return false;
+		const meta = this.getMeta();
+		const row = meta.baseY + meta.cursorY - meta.viewportY + 1;
+		const col = meta.cursorX + 1;
+		this.writePtySafely(`${ESC}[${row};${col}R`);
+		return true;
+	}
+	handleCsiDa(params) {
+		if (params.length > 1) return false;
+		const raw = params[0];
+		if ((raw === void 0 ? 0 : Array.isArray(raw) ? raw[0] : raw) !== 0) return false;
+		this.writePtySafely(`${ESC}[?1;2c`);
+		return true;
+	}
+};
+function trimBottomEmptyLines(lines) {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1] === "") end -= 1;
+	return end === lines.length ? lines : lines.slice(0, end);
+}
+function trimBottomEmptyAnsiLines(lines) {
+	let end = lines.length;
+	while (end > 0) {
+		const line = lines[end - 1];
+		if (!(!line?.hasStyle && (line?.plain ?? "").trim() === "")) break;
+		end -= 1;
+	}
+	return end === lines.length ? lines : lines.slice(0, end);
+}
+//#endregion
+export { applyTextMaskRules as a, encodeSgrMouse as c, isDefaultStyle as d, styleKey as f, fnv1a32 as i, extractStyle as l, TraceRecorder as n, snapshotGrid as o, encodeKey as p, sleep as r, snapshotLines as s, TerminalSession as t, findMeaningfulEndCol as u };