@archastro/tui-shot 0.1.0

package/dist/shot.js

@@ -0,0 +1,250 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { chromium } from "playwright";
+import { tsImport } from "tsx/esm/api";
+import { renderInkFrame } from "./render-ink.js";
+import { ansiFrameToHtml } from "./terminal-html.js";
+let sharedBrowser = null;
+let sharedBrowserHeaded = null;
+let shotQueue = Promise.resolve();
+async function browserFor(headed) {
+    if (sharedBrowser?.isConnected() && sharedBrowserHeaded === headed) {
+        return sharedBrowser;
+    }
+    if (sharedBrowser)
+        await closeBrowserNow();
+    try {
+        sharedBrowser = await chromium.launch({ headless: !headed });
+        sharedBrowserHeaded = headed;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (detail.includes("Executable doesn't exist")) {
+            throw new Error("Chromium is not installed. Run `npx --@archastro:registry=https://registry.npmjs.org @archastro/astroshot install-browser` and retry.", { cause: error });
+        }
+        throw error;
+    }
+    return sharedBrowser;
+}
+async function closeBrowserNow() {
+    if (!sharedBrowser)
+        return;
+    try {
+        await sharedBrowser.close();
+    }
+    finally {
+        sharedBrowser = null;
+        sharedBrowserHeaded = null;
+    }
+}
+export function closeSharedBrowser() {
+    const close = shotQueue.then(closeBrowserNow);
+    shotQueue = close.then(() => undefined, () => undefined);
+    return close;
+}
+async function loadFixture(fixturePath) {
+    const absolute = path.resolve(fixturePath);
+    if (!fs.existsSync(absolute)) {
+        throw new Error(`Fixture not found: ${absolute}`);
+    }
+    const fixtureRequire = createRequire(absolute);
+    let inkEntry;
+    let reactEntry;
+    try {
+        inkEntry = fixtureRequire.resolve("ink");
+        reactEntry = fixtureRequire.resolve("react");
+    }
+    catch (error) {
+        throw new Error(`Could not resolve Ink and React next to fixture ${absolute}. Install ink@7 and react@19 in the fixture project.`, { cause: error });
+    }
+    const inkRequire = createRequire(inkEntry);
+    const [module, inkModule, reactModule, chalkModule] = await Promise.all([
+        tsImport(absolute, import.meta.url),
+        import(pathToFileURL(inkEntry).href),
+        import(pathToFileURL(reactEntry).href),
+        import(pathToFileURL(inkRequire.resolve("chalk")).href),
+    ]);
+    const fixtureModule = module;
+    const fixture = fixtureModule.default ?? fixtureModule.fixture;
+    if (!fixture?.component) {
+        throw new Error(`Fixture ${absolute} must default-export a TuiShotFixture with a component.`);
+    }
+    return {
+        fixture,
+        ink: { render: inkModule.render, chalk: chalkModule.default },
+        react: reactModule.default ?? reactModule,
+    };
+}
+export function validPositive(value, name, options) {
+    if (!Number.isFinite(value) ||
+        value <= 0 ||
+        value > options.maximum ||
+        (options.integer && !Number.isInteger(value))) {
+        throw new Error(`${name} must be a positive${options.integer ? " integer" : ""} no greater than ${options.maximum}`);
+    }
+    return value;
+}
+export async function captureTerminalHtml(request) {
+    const { terminalRows, cols, rows, scale, background, foreground, fontFamily, fontSize, lineHeight, padding, borderRadius, } = request;
+    const cssWidth = Math.ceil(cols * fontSize * 0.62 + padding * 2);
+    const cssHeight = Math.ceil(rows * fontSize * lineHeight + padding * 2);
+    const outPath = path.resolve(request.outPath);
+    if (path.extname(outPath).toLowerCase() !== ".png") {
+        throw new Error(`Output must use a .png extension: ${outPath}`);
+    }
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    const browser = await browserFor(Boolean(request.headed));
+    let page;
+    try {
+        page = await browser.newPage({
+            viewport: { width: cssWidth + 32, height: cssHeight + 32 },
+            deviceScaleFactor: scale,
+        });
+    }
+    catch (error) {
+        await closeBrowserNow();
+        throw error;
+    }
+    try {
+        await page.setContent(`<!doctype html>
+      <html>
+        <head>
+          <meta charset="utf-8" />
+          <style>
+            html, body { margin: 0; padding: 0; background: transparent; }
+            body { display: inline-block; padding: 16px; }
+            [data-tui-shot] {
+              box-sizing: border-box;
+              width: ${cssWidth}px;
+              height: ${cssHeight}px;
+              overflow: hidden;
+              padding: ${padding}px;
+              border: 1px solid rgba(185, 168, 255, .18);
+              border-radius: ${borderRadius}px;
+              background: ${background};
+              color: ${foreground};
+              box-shadow: 0 18px 44px rgba(0, 0, 0, .28);
+              font-family: ${fontFamily};
+              font-size: ${fontSize}px;
+              font-variant-ligatures: none;
+              font-weight: 400;
+              line-height: ${lineHeight};
+              text-rendering: geometricPrecision;
+            }
+            .tui-row {
+              height: ${lineHeight}em;
+              overflow: hidden;
+              white-space: pre;
+            }
+          </style>
+        </head>
+        <body>
+          <div data-tui-shot role="img" aria-label="Terminal screenshot">${terminalRows}</div>
+        </body>
+      </html>`, { waitUntil: "load" });
+        await page.locator("[data-tui-shot]").screenshot({
+            path: outPath,
+            omitBackground: true,
+        });
+    }
+    finally {
+        await page.close();
+    }
+    return outPath;
+}
+async function takeIsolatedTuiShot(request) {
+    const context = await loadFixture(request.fixturePath);
+    const previousReact = Object.getOwnPropertyDescriptor(globalThis, "React");
+    Object.defineProperty(globalThis, "React", {
+        configurable: true,
+        value: context.react,
+        writable: true,
+    });
+    try {
+        return await renderTuiShot(request, context);
+    }
+    finally {
+        if (previousReact) {
+            Object.defineProperty(globalThis, "React", previousReact);
+        }
+        else {
+            Reflect.deleteProperty(globalThis, "React");
+        }
+    }
+}
+async function renderTuiShot(request, context) {
+    const { fixture } = context;
+    const cols = validPositive(request.cols ?? fixture.cols ?? 100, "cols", {
+        integer: true,
+        maximum: 1_000,
+    });
+    const rows = validPositive(request.rows ?? fixture.rows ?? 30, "rows", {
+        integer: true,
+        maximum: 1_000,
+    });
+    const scale = validPositive(request.scale ?? fixture.scale ?? 2, "scale", {
+        maximum: 4,
+    });
+    const background = fixture.background ?? "#090a12";
+    const foreground = fixture.foreground ?? "#e8e8f2";
+    const fontFamily = fixture.fontFamily ??
+        '"SFMono-Regular", "Cascadia Code", "Roboto Mono", Menlo, Consolas, monospace';
+    const fontSize = validPositive(fixture.fontSize ?? 15, "fontSize", {
+        maximum: 200,
+    });
+    const lineHeight = validPositive(fixture.lineHeight ?? 1.32, "lineHeight", {
+        maximum: 10,
+    });
+    const padding = fixture.padding ?? 22;
+    const borderRadius = fixture.borderRadius ?? 12;
+    if (!Number.isFinite(padding) || padding < 0 || padding > 1_000) {
+        throw new Error("padding must be between 0 and 1000");
+    }
+    if (!Number.isFinite(borderRadius) ||
+        borderRadius < 0 ||
+        borderRadius > 1_000) {
+        throw new Error("borderRadius must be between 0 and 1000");
+    }
+    const ansi = renderInkFrame(fixture, cols, rows, context.ink);
+    const plainFrame = ansi
+        .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/\x1b[@-_]/g, "");
+    for (const expected of fixture.expectText ?? []) {
+        if (!plainFrame.includes(expected)) {
+            throw new Error(`Fixture did not render expected text ${JSON.stringify(expected)}. ` +
+                `Visible frame:\n${plainFrame.slice(0, 1_200)}`);
+        }
+    }
+    const terminalRows = await ansiFrameToHtml(ansi, {
+        cols,
+        rows,
+        foreground,
+        background,
+    });
+    return captureTerminalHtml({
+        terminalRows,
+        outPath: request.outPath,
+        headed: request.headed,
+        cols,
+        rows,
+        scale,
+        background,
+        foreground,
+        fontFamily,
+        fontSize,
+        lineHeight,
+        padding,
+        borderRadius,
+    });
+}
+export function queueTerminalShot(task) {
+    const shot = shotQueue.then(task);
+    shotQueue = shot.then(() => undefined, () => undefined);
+    return shot;
+}
+export function takeTuiShot(request) {
+    return queueTerminalShot(() => takeIsolatedTuiShot(request));
+}

package/dist/terminal-html.d.ts

@@ -0,0 +1,14 @@
+import { type Terminal as TerminalType } from "@xterm/headless";
+export type HeadlessTerminal = TerminalType;
+export interface TerminalHtmlOptions {
+    cols: number;
+    rows: number;
+    foreground: string;
+    background: string;
+}
+export declare function createHeadlessTerminal(cols: number, rows: number): HeadlessTerminal;
+export declare function writeTerminal(terminal: HeadlessTerminal, data: string): Promise<void>;
+export declare function terminalPlainText(terminal: HeadlessTerminal, rows: number): string;
+export declare function terminalToHtml(terminal: HeadlessTerminal, options: TerminalHtmlOptions): string;
+/** Interpret a real ANSI frame and return styled HTML rows from xterm's cells. */
+export declare function ansiFrameToHtml(ansi: string, options: TerminalHtmlOptions): Promise<string>;

package/dist/terminal-html.js

@@ -0,0 +1,144 @@
+import xtermHeadless from "@xterm/headless";
+const { Terminal } = xtermHeadless;
+const ANSI_16 = [
+    "#2b2f3a", "#f0727a", "#54e0a0", "#f0b86e",
+    "#7aa2f7", "#b9a8ff", "#5bd6e0", "#e8e8f2",
+    "#5a5a7a", "#ff8d94", "#78efb6", "#ffd08a",
+    "#9bbcff", "#d1c5ff", "#86eaf0", "#ffffff",
+];
+function rgb(red, green, blue) {
+    return `#${[red, green, blue]
+        .map((value) => value.toString(16).padStart(2, "0"))
+        .join("")}`;
+}
+function paletteColor(index) {
+    if (index < ANSI_16.length)
+        return ANSI_16[index];
+    if (index < 232) {
+        const value = index - 16;
+        const levels = [0, 95, 135, 175, 215, 255];
+        return rgb(levels[Math.floor(value / 36)], levels[Math.floor((value % 36) / 6)], levels[value % 6]);
+    }
+    const gray = 8 + (index - 232) * 10;
+    return rgb(gray, gray, gray);
+}
+function packedRgb(value) {
+    return rgb((value >> 16) & 255, (value >> 8) & 255, value & 255);
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function cellStyle(cell, defaultForeground, defaultBackground) {
+    let foreground = cell.isFgRGB()
+        ? packedRgb(cell.getFgColor())
+        : cell.isFgPalette()
+            ? paletteColor(cell.getFgColor())
+            : defaultForeground;
+    let background = cell.isBgRGB()
+        ? packedRgb(cell.getBgColor())
+        : cell.isBgPalette()
+            ? paletteColor(cell.getBgColor())
+            : defaultBackground;
+    if (cell.isInverse())
+        [foreground, background] = [background, foreground];
+    return {
+        foreground,
+        background,
+        bold: Boolean(cell.isBold()),
+        dim: Boolean(cell.isDim()),
+        italic: Boolean(cell.isItalic()),
+        underline: Boolean(cell.isUnderline()),
+        strike: Boolean(cell.isStrikethrough()),
+        invisible: Boolean(cell.isInvisible()),
+    };
+}
+function styleAttribute(style) {
+    return [
+        `color:${style.invisible ? style.background : style.foreground}`,
+        `background:${style.background}`,
+        style.bold ? "font-weight:700" : "",
+        style.dim ? "opacity:.62" : "",
+        style.italic ? "font-style:italic" : "",
+        style.underline && style.strike
+            ? "text-decoration:underline line-through"
+            : style.underline
+                ? "text-decoration:underline"
+                : style.strike
+                    ? "text-decoration:line-through"
+                    : "",
+    ]
+        .filter(Boolean)
+        .join(";");
+}
+export function createHeadlessTerminal(cols, rows) {
+    return new Terminal({
+        cols,
+        rows,
+        allowProposedApi: true,
+        convertEol: true,
+        scrollback: 0,
+    });
+}
+export function writeTerminal(terminal, data) {
+    return new Promise((resolve) => terminal.write(data, resolve));
+}
+export function terminalPlainText(terminal, rows) {
+    const buffer = terminal.buffer.active;
+    const lines = [];
+    for (let y = 0; y < rows; y++) {
+        const line = buffer.getLine(buffer.viewportY + y);
+        lines.push(line?.translateToString(true) ?? "");
+    }
+    return lines.join("\n").trimEnd();
+}
+export function terminalToHtml(terminal, options) {
+    const buffer = terminal.buffer.active;
+    const rows = [];
+    for (let y = 0; y < options.rows; y++) {
+        const line = buffer.getLine(buffer.viewportY + y);
+        const runs = [];
+        for (let x = 0; x < options.cols; x++) {
+            const cell = line?.getCell(x);
+            if (cell?.getWidth() === 0)
+                continue;
+            const style = cell
+                ? cellStyle(cell, options.foreground, options.background)
+                : {
+                    foreground: options.foreground,
+                    background: options.background,
+                    bold: false,
+                    dim: false,
+                    italic: false,
+                    underline: false,
+                    strike: false,
+                    invisible: false,
+                };
+            const key = JSON.stringify(style);
+            const text = cell?.getChars() || " ";
+            const previous = runs.at(-1);
+            if (previous?.key === key)
+                previous.text += text;
+            else
+                runs.push({ key, style, text });
+        }
+        rows.push(`<div class="tui-row">${runs
+            .map((run) => `<span style="${styleAttribute(run.style)}">${escapeHtml(run.text)}</span>`)
+            .join("")}</div>`);
+    }
+    return rows.join("");
+}
+/** Interpret a real ANSI frame and return styled HTML rows from xterm's cells. */
+export async function ansiFrameToHtml(ansi, options) {
+    const terminal = createHeadlessTerminal(options.cols, options.rows);
+    try {
+        await writeTerminal(terminal, `\x1b[?7l${ansi}`);
+        return terminalToHtml(terminal, options);
+    }
+    finally {
+        terminal.dispose();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+import type { ReactElement } from "react";
+export interface TuiShotFixture {
+    /** Real Ink tree rendered into the terminal frame. */
+    component: ReactElement;
+    /** Visible strings that must exist before a PNG is accepted. */
+    expectText?: string[];
+    /** Terminal grid dimensions, not image pixels. */
+    cols?: number;
+    rows?: number;
+    background?: string;
+    foreground?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    lineHeight?: number;
+    padding?: number;
+    borderRadius?: number;
+    /** PNG device scale factor. Defaults to 2. */
+    scale?: number;
+}
+export interface TuiShotRequest {
+    fixturePath: string;
+    outPath: string;
+    headed?: boolean;
+    cols?: number;
+    rows?: number;
+    scale?: number;
+}
+export type PtyKey = "enter" | "up" | "down" | "left" | "right" | "tab" | "escape" | "backspace" | "space" | "ctrl-c" | "ctrl-d";
+export type PtyAction = {
+    waitFor: string;
+    timeoutMs?: number;
+} | {
+    waitForExit: true;
+    timeoutMs?: number;
+} | {
+    key: PtyKey;
+} | {
+    text: string;
+} | {
+    pauseMs: number;
+};
+export interface PtyShotFixture {
+    version: 1;
+    /** Executable launched directly, without an intermediary shell. */
+    command: string;
+    args?: string[];
+    /** Working directory, relative to the fixture file by default. */
+    cwd?: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    timeoutMs?: number;
+    settleMs?: number;
+    /** Permit a child that exits nonzero before capture. Defaults to false. */
+    allowNonZeroExit?: boolean;
+    actions?: PtyAction[];
+    expectText?: string[];
+    background?: string;
+    foreground?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    lineHeight?: number;
+    padding?: number;
+    borderRadius?: number;
+    scale?: number;
+}
+export interface PtyShotRequest {
+    fixturePath: string;
+    outPath: string;
+    headed?: boolean;
+    cols?: number;
+    rows?: number;
+    scale?: number;
+}
+export interface BatchEntry {
+    fixture: string;
+    out: string;
+}
+export interface BatchManifest {
+    shots: BatchEntry[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@archastro/tui-shot",
+  "version": "0.1.0",
+  "description": "Deterministic PNG screenshots of Ink fixtures and arbitrary PTY programs",
+  "keywords": [
+    "ink",
+    "pty",
+    "ratatui",
+    "terminal",
+    "screenshot",
+    "testing",
+    "tui"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArchAstro/astroshots.git",
+    "directory": "packages/tui-shot"
+  },
+  "homepage": "https://github.com/ArchAstro/astroshots#readme",
+  "bugs": "https://github.com/ArchAstro/astroshots/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "tui-shot": "bin/tui-shot.mjs"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node scripts/clean.mjs",
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "vitest run",
+    "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run clean && npm run build"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@xterm/headless": "^5.5.0",
+    "playwright": "1.61.1",
+    "tsx": "^4.20.0",
+    "yaml": "^2.8.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "1.2.0-beta.14"
+  },
+  "peerDependencies": {
+    "ink": "^7.1.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ink": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "ink": "^7.1.0",
+    "react": "^19.2.0",
+    "sharp": "^0.35.3",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  }
+}