@silvery/examples 0.17.3 → 0.17.5

package/dist/backends-Dj-11kZF.mjs

@@ -0,0 +1,1179 @@
+import { n as __esmMin, o as __toESM } from "./chunk-BSw8zbkd.mjs";
+import { n as keyToAnsi, r as parseKey, t as init_key_mapping } from "./key-mapping-D4LR1go6.mjs";
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+//#region ../../termless/src/spawn.ts
+/**
+* Portable PTY spawn abstraction.
+*
+* Detects the runtime (Bun vs Node.js) and uses the appropriate PTY backend:
+* - Bun: native `Bun.spawn()` with `terminal` option
+* - Node.js: `node-pty` (optional peer dependency — throws if not installed)
+*/
+/**
+* Spawn a process with a PTY, using the appropriate runtime backend.
+*
+* - On Bun: uses `Bun.spawn()` with the `terminal` option (built-in PTY support).
+* - On Node.js: uses `node-pty` (loaded via createRequire). Throws a clear error if not installed.
+*/
+function spawnPortablePty(options) {
+	if (isBun) return spawnBunPty(options);
+	return spawnNodePty(options);
+}
+function spawnBunPty(options) {
+	const { argv, cols, rows, cwd, env, onData } = options;
+	const proc = Bun.spawn(argv, {
+		cwd,
+		env: {
+			...process.env,
+			...env
+		},
+		terminal: {
+			cols,
+			rows,
+			data: (_terminal, data) => {
+				try {
+					onData(data);
+				} catch {}
+			}
+		}
+	});
+	const pty = proc.terminal;
+	return {
+		write(data) {
+			pty.write(data);
+		},
+		resize(newCols, newRows) {
+			pty.resize(newCols, newRows);
+		},
+		closePty() {
+			try {
+				pty.close();
+			} catch {}
+		},
+		kill(signal) {
+			proc.kill(signal);
+		},
+		get exitCode() {
+			return proc.exitCode;
+		},
+		get exited() {
+			return proc.exited;
+		},
+		get pid() {
+			return proc.pid;
+		}
+	};
+}
+/**
+* Load node-pty synchronously using createRequire.
+*
+* node-pty is a CommonJS native addon, so createRequire is the correct way
+* to load it from ESM. This keeps spawnPortablePty() synchronous.
+*/
+function loadNodePty() {
+	try {
+		return createRequire(import.meta.url)("node-pty");
+	} catch {
+		throw new Error("node-pty is required for PTY support on Node.js but was not found.\nInstall it with: npm install node-pty\nNote: node-pty requires native compilation tools (Python, C++ compiler).");
+	}
+}
+function spawnNodePty(options) {
+	const { argv, cols, rows, cwd, env, onData } = options;
+	const ptyProcess = loadNodePty().spawn(argv[0], argv.slice(1), {
+		name: "xterm-256color",
+		cols,
+		rows,
+		cwd,
+		env: {
+			...process.env,
+			...env
+		}
+	});
+	const encoder = new TextEncoder();
+	ptyProcess.onData((data) => {
+		try {
+			onData(encoder.encode(data));
+		} catch {}
+	});
+	let _exitCode = null;
+	let _exitResolve = null;
+	const exitedPromise = new Promise((resolve) => {
+		_exitResolve = resolve;
+	});
+	ptyProcess.onExit((e) => {
+		_exitCode = e.exitCode;
+		_exitResolve?.(e.exitCode);
+	});
+	return {
+		write(data) {
+			ptyProcess.write(data);
+		},
+		resize(newCols, newRows) {
+			ptyProcess.resize(newCols, newRows);
+		},
+		closePty() {
+			try {
+				ptyProcess.destroy();
+			} catch {}
+		},
+		kill(signal) {
+			const sig = signal === 9 ? "SIGKILL" : "SIGTERM";
+			try {
+				ptyProcess.kill(sig);
+			} catch {}
+		},
+		get exitCode() {
+			return _exitCode;
+		},
+		get exited() {
+			return exitedPromise;
+		},
+		get pid() {
+			return ptyProcess.pid;
+		}
+	};
+}
+var isBun;
+var init_spawn = __esmMin((() => {
+	isBun = typeof globalThis.Bun !== "undefined";
+}));
+//#endregion
+//#region ../../termless/src/pty.ts
+/**
+* Spawn a child process with a PTY and return a handle for interacting with it.
+*
+* The command is spawned directly (no shell wrapper) to avoid shell injection.
+* Sets FORCE_COLOR=1 and TERM=xterm-256color to ensure proper color output.
+*
+* Runtime support:
+* - Bun: uses native `Bun.spawn()` with `terminal` option (built-in PTY)
+* - Node.js: uses `node-pty` (must be installed as a peer dependency)
+*/
+function spawnPty(options) {
+	const { env, cwd, cols, rows, onData } = options;
+	const proc = spawnPortablePty({
+		argv: "shellCommand" in options ? [
+			"bash",
+			"-c",
+			options.shellCommand
+		] : options.command,
+		cols,
+		rows,
+		cwd,
+		env: {
+			FORCE_COLOR: "1",
+			TERM: "xterm-256color",
+			...env
+		},
+		onData
+	});
+	let closed = false;
+	let exitCode = null;
+	(async () => {
+		try {
+			exitCode = await proc.exited;
+		} catch {}
+	})();
+	async function close() {
+		if (closed) return;
+		closed = true;
+		proc.closePty();
+		try {
+			proc.kill();
+			if (!await Promise.race([proc.exited.then(() => true), new Promise((resolve) => setTimeout(() => resolve(false), 2e3))])) proc.kill(9);
+		} catch {}
+	}
+	return {
+		write(data) {
+			if (closed) throw new Error("PTY is closed");
+			proc.write(data);
+		},
+		resize(newCols, newRows) {
+			if (closed) throw new Error("PTY is closed");
+			proc.resize(newCols, newRows);
+		},
+		get alive() {
+			return !closed && proc.exitCode === null;
+		},
+		get exitInfo() {
+			if (exitCode !== null) return `exit=${exitCode}`;
+			return null;
+		},
+		close
+	};
+}
+var init_pty = __esmMin((() => {
+	init_spawn();
+}));
+//#endregion
+//#region ../../termless/src/svg.ts
+function rgbToHex(color) {
+	return `#${color.r.toString(16).padStart(2, "0")}${color.g.toString(16).padStart(2, "0")}${color.b.toString(16).padStart(2, "0")}`;
+}
+function rgbToString(color, fallback) {
+	return color ? rgbToHex(color) : fallback;
+}
+function escapeXml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function cellFgBg(cell, themeFg, themeBg) {
+	let fg = rgbToString(cell.fg, themeFg);
+	let bg = rgbToString(cell.bg, themeBg);
+	if (cell.inverse) [fg, bg] = [bg, fg];
+	return {
+		fg,
+		bg
+	};
+}
+function spansMatch(a, fg, bold, italic, dim, underline, strikethrough) {
+	return a.fill === fg && a.bold === bold && a.italic === italic && a.dim === dim && a.underline === underline && a.strikethrough === strikethrough;
+}
+function buildBgRects(lines, cellWidth, cellHeight, themeFg, themeBg) {
+	const rects = [];
+	for (let row = 0; row < lines.length; row++) {
+		const cells = lines[row];
+		let runStart = -1;
+		let runColor = "";
+		for (let col = 0; col < cells.length; col++) {
+			const cell = cells[col];
+			const { bg } = cellFgBg(cell, themeFg, themeBg);
+			if (bg !== themeBg) if (runStart >= 0 && runColor === bg) {} else {
+				if (runStart >= 0) rects.push({
+					x: runStart * cellWidth,
+					y: row * cellHeight,
+					width: (col - runStart) * cellWidth,
+					height: cellHeight,
+					fill: runColor
+				});
+				runStart = col;
+				runColor = bg;
+			}
+			else if (runStart >= 0) {
+				rects.push({
+					x: runStart * cellWidth,
+					y: row * cellHeight,
+					width: (col - runStart) * cellWidth,
+					height: cellHeight,
+					fill: runColor
+				});
+				runStart = -1;
+				runColor = "";
+			}
+		}
+		if (runStart >= 0) rects.push({
+			x: runStart * cellWidth,
+			y: row * cellHeight,
+			width: (cells.length - runStart) * cellWidth,
+			height: cellHeight,
+			fill: runColor
+		});
+	}
+	return rects;
+}
+function buildTextSpans(cells, themeFg, themeBg) {
+	const spans = [];
+	for (let col = 0; col < cells.length; col++) {
+		const cell = cells[col];
+		if (cell.char === "" && col > 0 && cells[col - 1]?.wide) continue;
+		const { fg } = cellFgBg(cell, themeFg, themeBg);
+		const char = cell.char || " ";
+		const underline = cell.underline !== false;
+		const current = spans.length > 0 ? spans[spans.length - 1] : null;
+		if (current && spansMatch(current, fg, cell.bold, cell.italic, cell.dim, underline, cell.strikethrough)) current.text += char;
+		else spans.push({
+			text: char,
+			fill: fg,
+			bold: cell.bold,
+			italic: cell.italic,
+			dim: cell.dim,
+			underline,
+			strikethrough: cell.strikethrough,
+			startCol: col
+		});
+	}
+	return spans;
+}
+function resolveOptions(options) {
+	return {
+		fontFamily: options?.fontFamily ?? DEFAULT_FONT_FAMILY,
+		fontSize: options?.fontSize ?? DEFAULT_FONT_SIZE,
+		cellWidth: options?.cellWidth ?? DEFAULT_CELL_WIDTH,
+		cellHeight: options?.cellHeight ?? DEFAULT_CELL_HEIGHT,
+		themeFg: options?.theme?.foreground ?? DEFAULT_THEME.foreground,
+		themeBg: options?.theme?.background ?? DEFAULT_THEME.background,
+		themeCursor: options?.theme?.cursor ?? DEFAULT_THEME.cursor,
+		padding: options?.padding ?? 0,
+		borderRadius: options?.borderRadius ?? 0,
+		windowBar: options?.windowBar ?? "none",
+		windowBarSize: options?.windowBarSize ?? 40,
+		margin: options?.margin ?? 0,
+		marginFill: options?.marginFill ?? null
+	};
+}
+function spanToTspan(span, cellWidth, themeFg) {
+	const attrs = [`x="${span.startCol * cellWidth}"`];
+	if (span.fill !== themeFg) attrs.push(`fill="${span.fill}"`);
+	if (span.bold) attrs.push(`font-weight="bold"`);
+	if (span.italic) attrs.push(`font-style="italic"`);
+	if (span.dim) attrs.push(`opacity="0.5"`);
+	const decorations = [];
+	if (span.underline) decorations.push("underline");
+	if (span.strikethrough) decorations.push("line-through");
+	if (decorations.length > 0) attrs.push(`text-decoration="${decorations.join(" ")}"`);
+	return `<tspan ${attrs.join(" ")}>${escapeXml(span.text)}</tspan>`;
+}
+function renderTextRows(lines, opts) {
+	const parts = [];
+	const { cellHeight, cellWidth, fontSize, fontFamily, themeFg, themeBg } = opts;
+	for (let row = 0; row < lines.length; row++) {
+		const cells = lines[row];
+		if (!cells || cells.length === 0) continue;
+		const spans = buildTextSpans(cells, themeFg, themeBg);
+		if (spans.length === 0) continue;
+		const y = row * cellHeight + fontSize;
+		parts.push(`<text x="0" y="${y}" font-family="${escapeXml(fontFamily)}" font-size="${fontSize}" fill="${themeFg}">`);
+		for (const span of spans) parts.push(spanToTspan(span, cellWidth, themeFg));
+		parts.push(`</text>`);
+	}
+	return parts;
+}
+function renderCursor(cursor, opts) {
+	if (!cursor.visible) return null;
+	const cx = cursor.x * opts.cellWidth;
+	const cy = cursor.y * opts.cellHeight;
+	switch (cursor.style ?? "block") {
+		case "block": return `<rect x="${cx}" y="${cy}" width="${opts.cellWidth}" height="${opts.cellHeight}" fill="${opts.themeCursor}" opacity="0.5"/>`;
+		case "underline": return `<rect x="${cx}" y="${cy + opts.cellHeight - 2}" width="${opts.cellWidth}" height="2" fill="${opts.themeCursor}"/>`;
+		case "beam": return `<rect x="${cx}" y="${cy}" width="2" height="${opts.cellHeight}" fill="${opts.themeCursor}"/>`;
+	}
+}
+function renderWindowBar(barWidth, barHeight, style, borderRadius) {
+	if (style === "none") return [];
+	const parts = [];
+	parts.push(`<rect width="${barWidth}" height="${barHeight}" rx="${borderRadius}" ry="${borderRadius}" fill="#333333"/>`);
+	if (borderRadius > 0) parts.push(`<rect y="${barHeight - borderRadius}" width="${barWidth}" height="${borderRadius}" fill="#333333"/>`);
+	const dotRadius = 6;
+	const dotY = barHeight / 2;
+	const dotStartX = 20;
+	if (style === "rings") {
+		parts.push(`<circle cx="${dotStartX}" cy="${dotY}" r="${dotRadius}" fill="none" stroke="#ff5f57" stroke-width="1.5"/>`);
+		parts.push(`<circle cx="${dotStartX + 20}" cy="${dotY}" r="${dotRadius}" fill="none" stroke="#febc2e" stroke-width="1.5"/>`);
+		parts.push(`<circle cx="${dotStartX + 40}" cy="${dotY}" r="${dotRadius}" fill="none" stroke="#28c840" stroke-width="1.5"/>`);
+	} else {
+		parts.push(`<circle cx="${dotStartX}" cy="${dotY}" r="${dotRadius}" fill="#ff5f57"/>`);
+		parts.push(`<circle cx="${dotStartX + 20}" cy="${dotY}" r="${dotRadius}" fill="#febc2e"/>`);
+		parts.push(`<circle cx="${dotStartX + 40}" cy="${dotY}" r="${dotRadius}" fill="#28c840"/>`);
+	}
+	return parts;
+}
+function screenshotSvg(terminal, options) {
+	const opts = resolveOptions(options);
+	const { cellWidth, cellHeight, themeFg, themeBg, padding, borderRadius, windowBar, windowBarSize, margin, marginFill } = opts;
+	const lines = terminal.getLines();
+	const rows = lines.length;
+	const contentWidth = (rows > 0 ? Math.max(...lines.map((l) => l.length)) : 0) * cellWidth;
+	const contentHeight = rows * cellHeight;
+	if (!(padding > 0 || borderRadius > 0 || windowBar !== "none" || margin > 0)) {
+		const totalWidth = contentWidth;
+		const totalHeight = contentHeight;
+		const parts = [];
+		parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="${totalHeight}">`);
+		parts.push(`<rect width="100%" height="100%" fill="${themeBg}"/>`);
+		for (const rect of buildBgRects(lines, cellWidth, cellHeight, themeFg, themeBg)) parts.push(`<rect x="${rect.x}" y="${rect.y}" width="${rect.width}" height="${rect.height}" fill="${rect.fill}"/>`);
+		parts.push(...renderTextRows(lines, opts));
+		const cursorSvg = renderCursor(terminal.getCursor(), opts);
+		if (cursorSvg) parts.push(cursorSvg);
+		parts.push(`</svg>`);
+		return parts.join("\n");
+	}
+	const barHeight = windowBar !== "none" ? windowBarSize : 0;
+	const innerWidth = contentWidth + padding * 2;
+	const innerHeight = contentHeight + padding * 2 + barHeight;
+	const totalWidth = innerWidth + margin * 2;
+	const totalHeight = innerHeight + margin * 2;
+	const parts = [];
+	parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="${totalHeight}">`);
+	if (margin > 0 && marginFill) parts.push(`<rect width="100%" height="100%" fill="${marginFill}"/>`);
+	if (borderRadius > 0) {
+		parts.push(`<defs>`);
+		parts.push(`<clipPath id="terminal-clip">`);
+		parts.push(`<rect x="${margin}" y="${margin}" width="${innerWidth}" height="${innerHeight}" rx="${borderRadius}" ry="${borderRadius}"/>`);
+		parts.push(`</clipPath>`);
+		parts.push(`</defs>`);
+		parts.push(`<g clip-path="url(#terminal-clip)">`);
+	}
+	const bgAttrs = borderRadius > 0 ? `x="${margin}" y="${margin}" width="${innerWidth}" height="${innerHeight}" rx="${borderRadius}" ry="${borderRadius}"` : `x="${margin}" y="${margin}" width="${innerWidth}" height="${innerHeight}"`;
+	parts.push(`<rect ${bgAttrs} fill="${themeBg}"/>`);
+	if (windowBar !== "none") {
+		parts.push(`<g transform="translate(${margin}, ${margin})">`);
+		parts.push(...renderWindowBar(innerWidth, barHeight, windowBar, borderRadius));
+		parts.push(`</g>`);
+	}
+	const contentOffsetX = margin + padding;
+	const contentOffsetY = margin + padding + barHeight;
+	parts.push(`<g transform="translate(${contentOffsetX}, ${contentOffsetY})">`);
+	for (const rect of buildBgRects(lines, cellWidth, cellHeight, themeFg, themeBg)) parts.push(`<rect x="${rect.x}" y="${rect.y}" width="${rect.width}" height="${rect.height}" fill="${rect.fill}"/>`);
+	parts.push(...renderTextRows(lines, opts));
+	const cursorSvg = renderCursor(terminal.getCursor(), opts);
+	if (cursorSvg) parts.push(cursorSvg);
+	parts.push(`</g>`);
+	if (borderRadius > 0) parts.push(`</g>`);
+	parts.push(`</svg>`);
+	return parts.join("\n");
+}
+var DEFAULT_FONT_FAMILY, DEFAULT_FONT_SIZE, DEFAULT_CELL_WIDTH, DEFAULT_CELL_HEIGHT, DEFAULT_THEME;
+var init_svg = __esmMin((() => {
+	DEFAULT_FONT_FAMILY = "'Menlo', 'Monaco', 'Courier New', monospace";
+	DEFAULT_FONT_SIZE = 16;
+	DEFAULT_CELL_WIDTH = 9.6;
+	DEFAULT_CELL_HEIGHT = 20;
+	DEFAULT_THEME = {
+		foreground: "#d4d4d4",
+		background: "#1e1e1e",
+		cursor: "#aeafad"
+	};
+}));
+//#endregion
+//#region ../../termless/src/png.ts
+async function loadResvg() {
+	if (resvgModule) return resvgModule;
+	try {
+		resvgModule = await import("./resvg-js-Cnk2o49d.mjs").then((m) => /* @__PURE__ */ __toESM(m.default, 1));
+		return resvgModule;
+	} catch {
+		throw new Error("screenshotPng() requires @resvg/resvg-js. Install it:\n  bun add -d @resvg/resvg-js");
+	}
+}
+/**
+* Render a terminal screenshot as a PNG buffer.
+*
+* Requires `@resvg/resvg-js` as an optional dependency:
+*   bun add -d @resvg/resvg-js
+*/
+async function screenshotPng(terminal, options) {
+	const svg = screenshotSvg(terminal, options);
+	const scale = options?.scale ?? 2;
+	const { Resvg } = await loadResvg();
+	return new Resvg(svg, {
+		fitTo: {
+			mode: "zoom",
+			value: scale
+		},
+		font: {
+			loadSystemFonts: true,
+			defaultFontFamily: "Menlo"
+		}
+	}).render().asPng();
+}
+var resvgModule;
+var init_png = __esmMin((() => {
+	init_svg();
+	resvgModule = null;
+}));
+//#endregion
+//#region ../../termless/src/views.ts
+/** Convert a Cell[] to trimmed text. */
+function cellsToText(cells) {
+	return cells.map((c) => c.char || " ").join("").trimEnd();
+}
+/** Get rows of text from a TerminalReadable for an absolute row range. */
+function getRowTexts(readable, startRow, endRow) {
+	const lines = [];
+	for (let i = startRow; i < endRow; i++) lines.push(cellsToText(readable.getLine(i)));
+	return lines;
+}
+/**
+* Create a lazy RegionView from a row-range resolver.
+* The resolver is called on every getText()/getLines() access,
+* so the view always reflects current terminal state.
+*/
+function createLazyRegionView(readable, resolveRange) {
+	return {
+		getText() {
+			const [start, end] = resolveRange();
+			return getRowTexts(readable, start, end).join("\n");
+		},
+		getLines() {
+			const [start, end] = resolveRange();
+			return getRowTexts(readable, start, end);
+		},
+		containsText(text) {
+			return this.getText().includes(text);
+		}
+	};
+}
+/** Create a CellView from a Cell with positional context. */
+function createCellView(cell, row, col) {
+	return {
+		char: cell.char,
+		row,
+		col,
+		fg: cell.fg,
+		bg: cell.bg,
+		bold: cell.bold,
+		dim: cell.dim,
+		italic: cell.italic,
+		underline: cell.underline,
+		underlineColor: cell.underlineColor,
+		strikethrough: cell.strikethrough,
+		inverse: cell.inverse,
+		blink: cell.blink,
+		hidden: cell.hidden,
+		wide: cell.wide,
+		continuation: cell.continuation,
+		hyperlink: cell.hyperlink
+	};
+}
+/** Create a RegionView for a fixed absolute row range [startRow, endRow). */
+function createRegionView(readable, startRow, endRow) {
+	return createLazyRegionView(readable, () => [startRow, endRow]);
+}
+/** Create a RowView for an absolute row position. screenRow is the display row number. */
+function createRowView(readable, absRow, screenRow) {
+	return {
+		get row() {
+			return screenRow;
+		},
+		get cells() {
+			return readable.getLine(absRow);
+		},
+		getText() {
+			return cellsToText(readable.getLine(absRow));
+		},
+		getLines() {
+			return [this.getText()];
+		},
+		containsText(text) {
+			return this.getText().includes(text);
+		},
+		cellAt(col) {
+			return createCellView(readable.getCell(absRow, col), screenRow, col);
+		}
+	};
+}
+/**
+* Screen view: the fixed rows × cols grid at the bottom of the buffer.
+* In alt mode, this is the entire alt buffer.
+*/
+function createScreenView(readable) {
+	return createLazyRegionView(readable, () => {
+		const { totalLines, screenLines } = readable.getScrollback();
+		const base = totalLines - screenLines;
+		return [base, base + screenLines];
+	});
+}
+/**
+* Scrollback view: history lines above the screen.
+* Empty in alt screen mode.
+* @param n - If provided, only the last N scrollback lines.
+*/
+function createScrollbackView(readable, n) {
+	return createLazyRegionView(readable, () => {
+		const { totalLines, screenLines } = readable.getScrollback();
+		const base = totalLines - screenLines;
+		if (base <= 0) return [0, 0];
+		return [n != null ? Math.max(0, base - n) : 0, base];
+	});
+}
+/**
+* Buffer view: everything (scrollback + screen).
+* Uses readable.getText() directly — not row-based.
+*/
+function createBufferView(readable) {
+	return {
+		getText() {
+			return readable.getText();
+		},
+		getLines() {
+			return readable.getText().split("\n");
+		},
+		containsText(text) {
+			return readable.getText().includes(text);
+		}
+	};
+}
+/**
+* Viewport view: what's visible at the current scroll position.
+* At bottom (viewportOffset = totalLines - screenLines): same as screen.
+* Scrolled up: shows older scrollback lines.
+*/
+function createViewportView(readable) {
+	return createLazyRegionView(readable, () => {
+		const { viewportOffset, screenLines } = readable.getScrollback();
+		return [viewportOffset, viewportOffset + screenLines];
+	});
+}
+/**
+* Range view: a rectangular region of the screen.
+* Coordinates are screen-relative. Uses getTextRange() — not row-based.
+*/
+function createRangeView(readable, r1, c1, r2, c2) {
+	return {
+		getText() {
+			const { totalLines, screenLines } = readable.getScrollback();
+			const base = totalLines - screenLines;
+			return readable.getTextRange(base + r1, c1, base + r2, c2);
+		},
+		getLines() {
+			return this.getText().split("\n");
+		},
+		containsText(text) {
+			return this.getText().includes(text);
+		}
+	};
+}
+var init_views = __esmMin((() => {}));
+//#endregion
+//#region ../../termless/src/terminal.ts
+/**
+* Create a Terminal instance wrapping a backend with optional PTY support.
+*
+* The terminal initializes the backend immediately and provides methods for:
+* - Feeding data directly (no PTY)
+* - Spawning a child process with a PTY
+* - Sending key presses and typed text to the PTY
+* - Waiting for terminal content to appear or stabilize
+* - Searching terminal text
+* - Taking SVG and PNG screenshots
+*/
+function createTerminal(options) {
+	const { backend, scrollbackLimit } = options;
+	let cols = options.cols ?? DEFAULT_COLS;
+	let rows = options.rows ?? DEFAULT_ROWS;
+	backend.init({
+		cols,
+		rows,
+		scrollbackLimit
+	});
+	let ptyHandle = null;
+	let closed = false;
+	/** OSC 52 regex: \x1b]52;c;<base64>\x07 or \x1b]52;c;<base64>\x1b\\ */
+	const osc52Re = /\x1b\]52;[a-z]*;([A-Za-z0-9+/=]+)(?:\x07|\x1b\\)/g;
+	const clipboardWrites = [];
+	function scanOsc52(data) {
+		osc52Re.lastIndex = 0;
+		let match;
+		while ((match = osc52Re.exec(data)) !== null) try {
+			const decoded = atob(match[1]);
+			clipboardWrites.push(decoded);
+		} catch {}
+	}
+	function getText() {
+		return backend.getText();
+	}
+	function getTextRange(startRow, startCol, endRow, endCol) {
+		return backend.getTextRange(startRow, startCol, endRow, endCol);
+	}
+	function getCell(row, col) {
+		return backend.getCell(row, col);
+	}
+	function getLine(row) {
+		return backend.getLine(row);
+	}
+	function getLines() {
+		return backend.getLines();
+	}
+	function getCursor() {
+		return backend.getCursor();
+	}
+	function getMode(mode) {
+		return backend.getMode(mode);
+	}
+	function getTitle() {
+		return backend.getTitle();
+	}
+	function getScrollback() {
+		return backend.getScrollback();
+	}
+	function feed(data) {
+		if (closed) throw new Error("Terminal is closed");
+		scanOsc52(typeof data === "string" ? data : new TextDecoder().decode(data));
+		const bytes = typeof data === "string" ? encoder.encode(data) : data;
+		backend.feed(bytes);
+	}
+	async function spawn(command, spawnOpts) {
+		if (closed) throw new Error("Terminal is closed");
+		if (ptyHandle) throw new Error("Terminal already has a spawned process");
+		ptyHandle = spawnPty({
+			command,
+			env: spawnOpts?.env,
+			cwd: spawnOpts?.cwd,
+			cols,
+			rows,
+			onData: (data) => {
+				scanOsc52(new TextDecoder().decode(data));
+				backend.feed(data);
+			}
+		});
+		backend.onResponse = (data) => {
+			if (ptyHandle?.alive) ptyHandle.write(new TextDecoder().decode(data));
+		};
+	}
+	function press(key) {
+		if (closed) throw new Error("Terminal is closed");
+		if (!ptyHandle) throw new Error("No PTY spawned — call spawn() first");
+		const desc = parseKey(key);
+		const encoded = backend.encodeKey(desc);
+		if (encoded.length > 0) ptyHandle.write(new TextDecoder().decode(encoded));
+		else {
+			const ansi = keyToAnsi(desc);
+			if (ansi) ptyHandle.write(ansi);
+		}
+	}
+	function type(text) {
+		if (closed) throw new Error("Terminal is closed");
+		if (!ptyHandle) throw new Error("No PTY spawned — call spawn() first");
+		ptyHandle.write(text);
+	}
+	/** Encode SGR button byte: button number + modifier bits. */
+	function sgrButton(options) {
+		let btn = options?.button ?? 0;
+		if (options?.shift) btn += 4;
+		if (options?.alt) btn += 8;
+		if (options?.ctrl) btn += 16;
+		return btn;
+	}
+	function requirePty() {
+		if (closed) throw new Error("Terminal is closed");
+		if (!ptyHandle) throw new Error("No PTY spawned — call spawn() first");
+		return ptyHandle;
+	}
+	function click(x, y, options) {
+		const pty = requirePty();
+		const col = x + 1;
+		const row = y + 1;
+		const btn = sgrButton(options);
+		pty.write(`\x1b[<${btn};${col};${row}M`);
+		pty.write(`\x1b[<${btn};${col};${row}m`);
+	}
+	async function dblclick(x, y, options) {
+		const delay = options?.delay ?? 50;
+		click(x, y, options);
+		await new Promise((r) => setTimeout(r, delay));
+		click(x, y, options);
+	}
+	function mouseDown(x, y, options) {
+		const pty = requirePty();
+		const btn = sgrButton(options);
+		pty.write(`\x1b[<${btn};${x + 1};${y + 1}M`);
+	}
+	function mouseUp(x, y, options) {
+		const pty = requirePty();
+		const btn = sgrButton(options);
+		pty.write(`\x1b[<${btn};${x + 1};${y + 1}m`);
+	}
+	function mouseMove(x, y, options) {
+		const pty = requirePty();
+		const btn = 32 + sgrButton(options);
+		pty.write(`\x1b[<${btn};${x + 1};${y + 1}M`);
+	}
+	function wheel(deltaX, deltaY, options) {
+		const pty = requirePty();
+		const col = (options?.x ?? 0) + 1;
+		const row = (options?.y ?? 0) + 1;
+		let mods = 0;
+		if (options?.shift) mods += 4;
+		if (options?.alt) mods += 8;
+		if (options?.ctrl) mods += 16;
+		if (deltaY < 0) for (let i = 0; i < Math.abs(deltaY); i++) pty.write(`\x1b[<${64 + mods};${col};${row}M`);
+		else if (deltaY > 0) for (let i = 0; i < deltaY; i++) pty.write(`\x1b[<${65 + mods};${col};${row}M`);
+	}
+	/** @deprecated Use `await expect(term.screen).toContainText("text", { timeout })` instead. */
+	async function waitFor(text, timeout = DEFAULT_WAIT_TIMEOUT) {
+		const start = Date.now();
+		while (Date.now() - start < timeout) {
+			if (getText().includes(text)) return;
+			await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+		}
+		throw new Error(`Timeout waiting for "${text}" after ${timeout}ms`);
+	}
+	async function waitForStable(stableMs = DEFAULT_STABLE_MS, timeout = DEFAULT_WAIT_TIMEOUT) {
+		const start = Date.now();
+		let lastContent = "";
+		let stableStart = Date.now();
+		while (Date.now() - start < timeout) {
+			const content = getText();
+			if (content === lastContent) {
+				if (Date.now() - stableStart >= stableMs) return;
+			} else {
+				lastContent = content;
+				stableStart = Date.now();
+			}
+			await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+		}
+		throw new Error(`Terminal did not stabilize within ${timeout}ms`);
+	}
+	function find(text) {
+		const lines = getText().split("\n");
+		for (let row = 0; row < lines.length; row++) {
+			const col = lines[row].indexOf(text);
+			if (col !== -1) return {
+				row,
+				col,
+				text
+			};
+		}
+		return null;
+	}
+	function findAll(pattern) {
+		const lines = getText().split("\n");
+		const results = [];
+		for (let row = 0; row < lines.length; row++) {
+			const line = lines[row];
+			const re = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+			let match;
+			while ((match = re.exec(line)) !== null) {
+				results.push({
+					row,
+					col: match.index,
+					text: match[0]
+				});
+				if (match[0].length === 0) re.lastIndex++;
+			}
+		}
+		return results;
+	}
+	function screenshot(svgOptions) {
+		return screenshotSvg(terminal, svgOptions);
+	}
+	function screenshotAsPng(pngOptions) {
+		return screenshotPng(terminal, pngOptions);
+	}
+	function resize(newCols, newRows) {
+		if (closed) throw new Error("Terminal is closed");
+		cols = newCols;
+		rows = newRows;
+		backend.resize(newCols, newRows);
+		if (ptyHandle?.alive) ptyHandle.resize(newCols, newRows);
+	}
+	async function close() {
+		if (closed) return;
+		closed = true;
+		backend.onResponse = void 0;
+		if (ptyHandle) {
+			await ptyHandle.close();
+			ptyHandle = null;
+		}
+		backend.destroy();
+	}
+	const terminal = {
+		get cols() {
+			return cols;
+		},
+		get rows() {
+			return rows;
+		},
+		get backend() {
+			return backend;
+		},
+		getText,
+		getTextRange,
+		getCell,
+		getLine,
+		getLines,
+		getCursor,
+		getMode,
+		getTitle,
+		getScrollback,
+		get screen() {
+			return createScreenView(backend);
+		},
+		get scrollback() {
+			return createScrollbackView(backend);
+		},
+		get buffer() {
+			return createBufferView(backend);
+		},
+		get viewport() {
+			return createViewportView(backend);
+		},
+		row(n) {
+			const { totalLines, screenLines } = backend.getScrollback();
+			const base = totalLines - screenLines;
+			const screenRow = n >= 0 ? n : screenLines + n;
+			return createRowView(backend, base + screenRow, screenRow);
+		},
+		cell(r, c) {
+			const { totalLines, screenLines } = backend.getScrollback();
+			const base = totalLines - screenLines;
+			const screenRow = r >= 0 ? r : screenLines + r;
+			return createCellView(backend.getCell(base + screenRow, c), screenRow, c);
+		},
+		range(r1, c1, r2, c2) {
+			return createRangeView(backend, r1, c1, r2, c2);
+		},
+		firstRow() {
+			return this.row(0);
+		},
+		lastRow() {
+			return this.row(-1);
+		},
+		feed,
+		spawn,
+		get alive() {
+			return ptyHandle?.alive ?? false;
+		},
+		get exitInfo() {
+			return ptyHandle?.exitInfo ?? null;
+		},
+		press,
+		type,
+		clipboardWrites,
+		click,
+		dblclick,
+		mouseDown,
+		mouseUp,
+		mouseMove,
+		wheel,
+		waitFor,
+		waitForStable,
+		find,
+		findAll,
+		screenshotSvg: screenshot,
+		screenshotPng: screenshotAsPng,
+		resize,
+		close,
+		[Symbol.asyncDispose]: close
+	};
+	return terminal;
+}
+var POLL_INTERVAL, DEFAULT_COLS, DEFAULT_ROWS, DEFAULT_WAIT_TIMEOUT, DEFAULT_STABLE_MS, encoder;
+var init_terminal = __esmMin((() => {
+	init_key_mapping();
+	init_pty();
+	init_svg();
+	init_png();
+	init_views();
+	POLL_INTERVAL = 50;
+	DEFAULT_COLS = 80;
+	DEFAULT_ROWS = 24;
+	DEFAULT_WAIT_TIMEOUT = 5e3;
+	DEFAULT_STABLE_MS = 200;
+	encoder = new TextEncoder();
+}));
+//#endregion
+//#region ../../termless/src/backends.ts
+/**
+* Backend registry — one function, everything derived.
+*
+* @example
+* ```typescript
+* import { backend } from "termless"
+*
+* const b = await backend("ghostty")
+* const b = await backend("xtermjs", { version: "5.4.0" })
+* ```
+*/
+function manifest() {
+	if (_manifest) return _manifest;
+	const raw = JSON.parse(readFileSync(MANIFEST_PATH, "utf-8"));
+	const backends = {};
+	for (const [name, entry] of Object.entries(raw.backends)) backends[name] = {
+		package: entry.package,
+		upstream: entry.upstream ?? null,
+		version: entry.upstreamVersion ?? null,
+		type: entry.type,
+		default: entry.default,
+		platforms: entry.platforms,
+		label: entry.label,
+		description: entry.description,
+		url: entry.url,
+		caveat: entry.caveat,
+		slug: entry.slug,
+		terminal: entry.terminal
+	};
+	_manifest = {
+		version: raw.version,
+		backends
+	};
+	return _manifest;
+}
+function hasFilesWithExt(dir, ext, subdirs = []) {
+	const dirs = [dir, ...subdirs.map((s) => join(dir, s))];
+	for (const d of dirs) {
+		if (!existsSync(d)) continue;
+		try {
+			for (const f of readdirSync(d)) if (f.endsWith(ext)) return true;
+		} catch {}
+	}
+	return false;
+}
+function resolveModule(pkg, opts) {
+	return async () => {
+		const mod = await import(pkg);
+		return typeof mod.resolve === "function" ? mod.resolve(opts) : mod[Object.keys(mod).find((k) => k.startsWith("create"))](opts);
+	};
+}
+/** Run a backend's build/build.sh, falling back to nix if tools aren't in PATH. */
+function runBuildScript(pkgDir) {
+	if (!existsSync(join(pkgDir, "build", "build.sh"))) return;
+	console.log(`  Building in ${pkgDir}...`);
+	try {
+		execSync(`bash build/build.sh`, {
+			cwd: pkgDir,
+			stdio: "inherit"
+		});
+	} catch {
+		const flakeDir = join(__dirname, "..");
+		if (existsSync(join(flakeDir, "flake.nix"))) execSync(`nix develop ${flakeDir} --command bash build/build.sh`, {
+			cwd: pkgDir,
+			stdio: "inherit"
+		});
+		else throw new Error(`Build failed. Install dependencies or use the nix flake: nix develop`);
+	}
+}
+/** Build a backend's native artifacts if not already ready. */
+function buildBackend(name) {
+	const e = manifest().backends[name];
+	if (!e) throw new Error(`Unknown backend: ${name}`);
+	const type = backendTypes[e.type];
+	if (!type) return;
+	const pkgDir = findPackageDir(e.package);
+	if (!pkgDir) return;
+	if (!type.isReady(pkgDir)) type.build(pkgDir);
+}
+/**
+* Resolve a backend by name. The one function you need.
+*
+* @example
+* ```typescript
+* const b = await backend("ghostty")
+* const b = await backend("xtermjs", { version: "5.4.0" })
+* ```
+*/
+async function backend(name, opts) {
+	const m = manifest();
+	const entry = m.backends[name];
+	if (!entry) throw new Error(`Unknown backend "${name}". Available: ${Object.keys(m.backends).join(", ")}`);
+	const type = backendTypes[entry.type];
+	if (!type) throw new Error(`Unknown backend type "${entry.type}" for "${name}"`);
+	if (opts?.version && opts.version !== entry.version) return resolveVersioned(name, entry, type, opts.version, opts);
+	try {
+		import.meta.resolve(entry.package);
+	} catch {
+		throw new Error(`Backend "${name}" is not installed.\nRun: bunx termless backend install ${name}`);
+	}
+	const pkgDir = findPackageDir(entry.package);
+	if (pkgDir && !type.isReady(pkgDir)) throw new Error(`Backend "${name}" is installed but not built.\nRun: cd ${pkgDir} && ${getBuildHint(entry)}`);
+	return type.resolve(entry.package, opts);
+}
+/** Check if a backend is installed and ready. */
+function isReady(name) {
+	const entry = manifest().backends[name];
+	if (!entry) return false;
+	try {
+		import.meta.resolve(entry.package);
+	} catch {
+		return false;
+	}
+	const type = backendTypes[entry.type];
+	if (!type) return false;
+	const pkgDir = findPackageDir(entry.package);
+	return pkgDir ? type.isReady(pkgDir) : false;
+}
+/** List all backend names. */
+function backends() {
+	return Object.keys(manifest().backends);
+}
+/** Get entry for a backend. */
+function entry(name) {
+	return manifest().backends[name];
+}
+/** Create a Terminal by backend name. */
+async function createTerminalByName(name, opts) {
+	return createTerminal({
+		backend: await backend(name, opts),
+		...opts
+	});
+}
+async function resolveVersioned(name, entry, type, version, opts) {
+	if (entry.type === "native") throw new Error(`Version-pinned resolution for native backend "${name}" requires nix.\nRun: nix develop .#${name}-${version.replace(/\./g, "_")}`);
+	if (!entry.upstream) throw new Error(`Backend "${name}" has no upstream to version-pin.`);
+	const cacheDir = ensureCachedVersion(entry.upstream, version);
+	const origNodePath = process.env.NODE_PATH;
+	process.env.NODE_PATH = join(cacheDir, "node_modules") + (origNodePath ? `:${origNodePath}` : "");
+	try {
+		return await type.resolve(entry.package, opts);
+	} finally {
+		if (origNodePath) process.env.NODE_PATH = origNodePath;
+		else delete process.env.NODE_PATH;
+	}
+}
+/**
+* Install an upstream package at a specific version to the cache directory.
+* Returns the cache dir path (contains node_modules/).
+* Shared by backend() version-pinned resolution and census versioned runs.
+*/
+function ensureCachedVersion(upstream, version) {
+	const cacheDir = join(CACHE_DIR, `${upstream.replace(/[/@]/g, "_")}-${version}`);
+	if (!existsSync(join(cacheDir, "node_modules"))) {
+		mkdirSync(cacheDir, { recursive: true });
+		writeFileSync(join(cacheDir, "package.json"), JSON.stringify({
+			private: true,
+			dependencies: { [upstream]: version }
+		}));
+		execSync("bun install --no-save", {
+			cwd: cacheDir,
+			stdio: "pipe"
+		});
+	}
+	return cacheDir;
+}
+function findPackageDir(packageName) {
+	try {
+		let dir = dirname(fileURLToPath(import.meta.resolve(packageName)));
+		for (let i = 0; i < 10; i++) {
+			if (existsSync(join(dir, "package.json"))) try {
+				if (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")).name === packageName) return dir;
+			} catch {}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	} catch {}
+	return null;
+}
+function getBuildHint(entry) {
+	if (entry.type === "native") return "cargo build --release";
+	if (entry.type === "wasm") return "bash build/build.sh";
+	return "bun install";
+}
+var __dirname, MANIFEST_PATH, _manifest, backendTypes, CACHE_DIR;
+var init_backends = __esmMin((() => {
+	init_terminal();
+	__dirname = dirname(fileURLToPath(import.meta.url));
+	MANIFEST_PATH = join(__dirname, "..", "backends.json");
+	_manifest = null;
+	backendTypes = {
+		js: {
+			isReady: () => true,
+			build: () => {},
+			resolve: async (pkg, opts) => resolveModule(pkg, opts)()
+		},
+		wasm: {
+			isReady: (pkgDir) => {
+				return hasFilesWithExt(pkgDir, ".wasm", ["wasm", "build"]) || !existsSync(join(pkgDir, "build"));
+			},
+			build: (pkgDir) => runBuildScript(pkgDir),
+			resolve: async (pkg, opts) => resolveModule(pkg, opts)()
+		},
+		native: {
+			isReady: (pkgDir) => hasFilesWithExt(pkgDir, ".node", ["build", "native"]),
+			build: (pkgDir) => runBuildScript(pkgDir),
+			resolve: async (pkg, opts) => resolveModule(pkg, opts)()
+		},
+		os: {
+			isReady: () => true,
+			build: () => {},
+			resolve: async (pkg, opts) => resolveModule(pkg, opts)()
+		}
+	};
+	CACHE_DIR = join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "termless", "backends");
+}));
+//#endregion
+export { screenshotPng as _, ensureCachedVersion as a, isReady as c, init_terminal as d, createCellView as f, init_png as g, init_views as h, createTerminalByName as i, manifest as l, createRowView as m, backends as n, entry as o, createRegionView as p, buildBackend as r, init_backends as s, backend as t, createTerminal as u, init_svg as v, screenshotSvg as y };