@archastro/tui-shot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArchAstro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @archastro/tui-shot
+
+The terminal rendering engine behind `@archastro/astroshot`. It supports two
+capture boundaries:
+
+- Ink fixture trees rendered in-process and interpreted with xterm.
+- Arbitrary executables launched in a real pseudoterminal, driven by scripted
+  input, interpreted with the same xterm model, and captured in Chromium.
+
+Use the unified `@archastro/astroshot` package for command-line capture.
+
+## Quick start
+
+Run from a Node.js 22.14 or newer project. Install the project-local peers only
+when using Ink mode:
+
+```bash
+npm install --save-dev ink@^7.1 react@^19
+npx --@archastro:registry=https://registry.npmjs.org @archastro/astroshot install-browser
+npx --@archastro:registry=https://registry.npmjs.org @archastro/astroshot init ink
+npx --@archastro:registry=https://registry.npmjs.org @archastro/astroshot init pty
+```
+
+Then capture either boundary:
+
+```bash
+npx --@archastro:registry=https://registry.npmjs.org \
+  @archastro/astroshot ink ./ink.shot.tsx -o ./ink.png
+npx --@archastro:registry=https://registry.npmjs.org \
+  @archastro/astroshot pty ./pty.shot.yaml -o ./ratatui.png
+```
+
+On Linux hosts missing Chromium's system libraries, install the browser with
+`install-browser --with-deps`.
+
+## Ink fixture contract
+
+```tsx
+import { Box, Text } from "ink";
+import React from "react";
+import type { InkShotFixture } from "@archastro/astroshot/ink";
+
+export default {
+  cols: 80,
+  rows: 12,
+  background: "#090a12",
+  scale: 2,
+  expectText: ["Ready to deploy"],
+  component: (
+    <Box borderStyle="round">
+      <Text color="#b9a8ff">Ready to deploy</Text>
+    </Box>
+  ),
+} satisfies InkShotFixture;
+```
+
+`expectText` makes capture fail unless every listed string exists in the final
+terminal screen. `--cols`, `--rows`, and `--scale` override fixture values.
+Ink capture also supports `batch <manifest.yaml|json>`; manifest paths resolve
+relative to the manifest.
+
+## PTY fixture contract
+
+PTY fixtures work with any executable that behaves like a terminal program:
+
+```yaml
+version: 1
+command: ./target/debug/my-ratatui-app
+args: []
+cwd: .
+cols: 100
+rows: 30
+timeoutMs: 15000
+settleMs: 100
+actions:
+  - waitFor: Choose an option
+  - key: down
+  - key: enter
+  - waitFor: Ready
+expectText:
+  - Ready
+```
+
+The child receives `TERM=xterm-256color`, a fixed terminal grid, and the
+fixture environment. `command` is spawned directly—not through a shell—and
+`cwd` resolves relative to the fixture. On Windows, use an `.exe`; `.cmd` and
+`.bat` scripts are rejected because they require a shell. Supported actions
+are:
+
+- `waitFor` with an optional per-action `timeoutMs`;
+- `waitForExit: true` with an optional `timeoutMs` when the documented program
+  is expected to terminate before capture;
+- `key`: `enter`, arrows, `tab`, `escape`, `backspace`, `space`, `ctrl-c`, or
+  `ctrl-d`;
+- `text` for literal input;
+- `pauseMs` for a bounded delay.
+
+Actions run in order. The final xterm screen must contain every `expectText`
+value before Chromium captures it. Astroshot terminates a still-running child
+after the screenshot.
+
+A child that exits nonzero before capture fails by default, even when expected
+text rendered. Set `allowNonZeroExit: true` only to document an intentional
+failure state. Use a final `waitForExit: true` action when process completion is
+part of the documented state; this waits for the authoritative child status
+instead of relying on a fixed settle delay.
+
+The renderer targets text and ANSI/VT terminal interfaces. Mouse events,
+mid-journey resize actions, and terminal graphics protocols such as Sixel or
+Kitty images are not currently modeled.
+
+`node-pty` is an optional, lazily loaded native dependency so React and Ink
+capture still work on an unsupported PTY host. This release pins the exact
+official `1.2.0-beta.14` build; PTY capture reports an actionable error if its
+native addon is unavailable.
+
+## Reproducibility and trust
+
+Playwright is pinned so each release selects one Chromium version. PNG bytes
+can still differ across operating systems because the default stage uses host
+fonts. Set `fontFamily` and use a consistent OS/container for pixel baselines.
+
+Ink fixture modules and PTY commands are executable code with the current
+user's permissions. Only capture trusted repositories. A PTY is an I/O
+boundary, not a security sandbox; use a container for untrusted programs.
+
+## Programmatic API
+
+```ts
+import {
+  closeSharedBrowser,
+  takePtyShot,
+  takeTuiShot,
+} from "@archastro/tui-shot";
+
+await takeTuiShot({
+  fixturePath: "./screenshots/welcome.tsx",
+  outPath: "./screenshots/welcome.png",
+});
+await takePtyShot({
+  fixturePath: "./screenshots/ratatui.yaml",
+  outPath: "./screenshots/ratatui.png",
+});
+await closeSharedBrowser();
+```
+
+Ink fixtures support Ink 7 and React 19 as peer dependencies.

package/bin/tui-shot.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const cli = path.join(root, "dist", "cli.js");
+const require = createRequire(import.meta.url);
+const tsx = require.resolve("tsx/cli");
+const result = spawnSync(process.execPath, [tsx, cli, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(`tui-shot could not start: ${result.error.message}`);
+  process.exit(1);
+}
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+process.exit(result.status ?? 1);

package/dist/batch-paths.d.ts

@@ -0,0 +1,3 @@
+import type { BatchEntry } from "./types.js";
+/** Resolve batch destinations once, rejecting traversal and overwrite risks. */
+export declare function resolveBatchOutputPaths(entries: BatchEntry[], manifestDir: string, outDir: string | null): string[];

package/dist/batch-paths.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+function collisionKey(filePath) {
+    // Reject case-only collisions on every platform so a manifest behaves the
+    // same on case-sensitive and case-insensitive filesystems.
+    return path.resolve(filePath).normalize("NFC").toLowerCase();
+}
+function safeRelativeOutput(output) {
+    const portable = output.replaceAll("\\", "/");
+    const normalized = path.posix.normalize(portable);
+    if (path.posix.isAbsolute(normalized) ||
+        path.win32.isAbsolute(output) ||
+        normalized === ".." ||
+        normalized.startsWith("../")) {
+        throw new Error(`Batch output must be a safe relative path when --out-dir is used: ${output}`);
+    }
+    return normalized;
+}
+/** Resolve batch destinations once, rejecting traversal and overwrite risks. */
+export function resolveBatchOutputPaths(entries, manifestDir, outDir) {
+    const destinations = entries.map((entry) => outDir
+        ? path.resolve(outDir, safeRelativeOutput(entry.out))
+        : path.resolve(manifestDir, entry.out));
+    const seen = new Map();
+    for (const destination of destinations) {
+        const key = collisionKey(destination);
+        const previous = seen.get(key);
+        if (previous) {
+            throw new Error(`Batch outputs resolve to the same destination: ${previous} and ${destination}`);
+        }
+        seen.set(key, destination);
+    }
+    return destinations;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import YAML from "yaml";
+import { resolveBatchOutputPaths } from "./batch-paths.js";
+import { takePtyShot } from "./pty-shot.js";
+import { closeSharedBrowser, takeTuiShot } from "./shot.js";
+const localRequire = createRequire(import.meta.url);
+function help() {
+    console.log(`tui-shot — deterministic PNG screenshots of terminal interfaces
+
+Usage:
+  tui-shot install-browser [--with-deps]
+  tui-shot shot <fixture.tsx> -o <out.png> [options]
+  tui-shot pty <fixture.yaml|json> -o <out.png> [options]
+  tui-shot batch <manifest.yaml|json> [options]
+
+Options:
+  -o, --out <path>       Output PNG path
+  --cols <count>         Override terminal columns
+  --rows <count>         Override terminal rows
+  --scale <factor>       Override PNG device scale factor
+  --out-dir <path>       Override batch output directory
+  --headed               Show Chromium while capturing
+  --with-deps            Install Chromium system dependencies (Linux)
+  -h, --help             Show this help
+`);
+}
+function takeValue(args, flag) {
+    const value = args.shift();
+    if (!value || value.startsWith("-")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function parseArgs(argv) {
+    const args = [...argv];
+    const flags = {};
+    const positionals = [];
+    while (args.length) {
+        const value = args.shift();
+        if (value === "-h" || value === "--help")
+            flags.help = true;
+        else if (value === "--headed")
+            flags.headed = true;
+        else if (value === "--with-deps")
+            flags.withDeps = true;
+        else if (value === "-o" || value === "--out")
+            flags.out = takeValue(args, value);
+        else if (value === "--cols")
+            flags.cols = takeValue(args, value);
+        else if (value === "--rows")
+            flags.rows = takeValue(args, value);
+        else if (value === "--scale")
+            flags.scale = takeValue(args, value);
+        else if (value === "--out-dir")
+            flags.outDir = takeValue(args, value);
+        else if (value.startsWith("-"))
+            throw new Error(`Unknown flag: ${value}`);
+        else
+            positionals.push(value);
+    }
+    return { flags, positionals };
+}
+function numberFlag(flags, key, options) {
+    const raw = flags[key];
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) ||
+        value <= 0 ||
+        value > options.maximum ||
+        (options.integer && !Number.isInteger(value))) {
+        const kind = options.integer ? "positive integer" : "positive number";
+        throw new Error(`--${key} must be a ${kind} no greater than ${options.maximum}`);
+    }
+    return value;
+}
+function captureOverrides(flags) {
+    return {
+        cols: numberFlag(flags, "cols", { integer: true, maximum: 1_000 }),
+        rows: numberFlag(flags, "rows", { integer: true, maximum: 1_000 }),
+        scale: numberFlag(flags, "scale", { maximum: 4 }),
+    };
+}
+function assertPngPath(outPath) {
+    if (path.extname(outPath).toLowerCase() !== ".png") {
+        throw new Error(`Output must use a .png extension: ${outPath}`);
+    }
+}
+function installBrowser(withDeps) {
+    const playwrightRoot = path.dirname(localRequire.resolve("playwright/package.json"));
+    const result = spawnSync(process.execPath, [
+        path.join(playwrightRoot, "cli.js"),
+        "install",
+        ...(withDeps ? ["--with-deps"] : []),
+        "chromium",
+    ], { stdio: "inherit" });
+    if (result.error) {
+        throw new Error(`Could not start Playwright installer: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`Playwright browser installation exited with status ${result.status}`);
+    }
+}
+async function shot(fixturePath, flags) {
+    const outPath = flags.out;
+    if (typeof outPath !== "string") {
+        throw new Error("shot requires -o <out.png>");
+    }
+    assertPngPath(outPath);
+    const written = await takeTuiShot({
+        fixturePath,
+        outPath,
+        headed: Boolean(flags.headed),
+        ...captureOverrides(flags),
+    });
+    console.log(`wrote ${written}`);
+}
+async function pty(fixturePath, flags) {
+    const outPath = flags.out;
+    if (typeof outPath !== "string") {
+        throw new Error("pty requires -o <out.png>");
+    }
+    assertPngPath(outPath);
+    const written = await takePtyShot({
+        fixturePath,
+        outPath,
+        headed: Boolean(flags.headed),
+        ...captureOverrides(flags),
+    });
+    console.log(`wrote ${written}`);
+}
+function parseManifest(absolute) {
+    const raw = fs.readFileSync(absolute, "utf8");
+    const value = absolute.endsWith(".json")
+        ? JSON.parse(raw)
+        : YAML.parse(raw);
+    if (!value || typeof value !== "object" || !Array.isArray(value.shots)) {
+        throw new Error(`No shots listed in ${absolute}`);
+    }
+    const manifest = value;
+    if (manifest.shots.length === 0 ||
+        manifest.shots.some((entry) => !entry ||
+            typeof entry.fixture !== "string" ||
+            !entry.fixture ||
+            typeof entry.out !== "string" ||
+            !entry.out)) {
+        throw new Error(`Every shot in ${absolute} needs fixture and out paths`);
+    }
+    return manifest;
+}
+async function batch(manifestPath, flags) {
+    const absolute = path.resolve(manifestPath);
+    const manifest = parseManifest(absolute);
+    const base = path.dirname(absolute);
+    const outDir = typeof flags.outDir === "string" ? path.resolve(flags.outDir) : null;
+    const outPaths = resolveBatchOutputPaths(manifest.shots, base, outDir);
+    for (const outPath of outPaths)
+        assertPngPath(outPath);
+    const overrides = captureOverrides(flags);
+    let completed = 0;
+    for (const [index, entry] of manifest.shots.entries()) {
+        const fixturePath = path.resolve(base, entry.fixture);
+        const outPath = outPaths[index];
+        process.stdout.write(`shot ${path.relative(process.cwd(), fixturePath)} … `);
+        await takeTuiShot({
+            fixturePath,
+            outPath,
+            headed: Boolean(flags.headed),
+            ...overrides,
+        });
+        console.log(`→ ${path.relative(process.cwd(), outPath)}`);
+        completed++;
+    }
+    console.log(`done: ${completed}/${manifest.shots.length} shots`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    if (!command || command === "help" || command === "-h" || command === "--help") {
+        help();
+        if (!command)
+            process.exitCode = 1;
+        return;
+    }
+    const { flags, positionals } = parseArgs(argv.slice(1));
+    if (flags.help) {
+        help();
+        return;
+    }
+    if (command === "install-browser") {
+        if (positionals.length) {
+            throw new Error("install-browser does not accept arguments");
+        }
+        installBrowser(Boolean(flags.withDeps));
+    }
+    else if (command === "shot") {
+        if (!positionals[0])
+            throw new Error("shot requires a fixture path");
+        await shot(positionals[0], flags);
+    }
+    else if (command === "pty") {
+        if (!positionals[0])
+            throw new Error("pty requires a fixture path");
+        await pty(positionals[0], flags);
+    }
+    else if (command === "batch") {
+        if (!positionals[0])
+            throw new Error("batch requires a manifest path");
+        await batch(positionals[0], flags);
+    }
+    else {
+        throw new Error(`Unknown command: ${command}`);
+    }
+}
+main()
+    .catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+})
+    .finally(closeSharedBrowser);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { closeSharedBrowser, takeTuiShot } from "./shot.js";
+export { takePtyShot } from "./pty-shot.js";
+export type { BatchEntry, BatchManifest, PtyAction, PtyKey, PtyShotFixture, PtyShotRequest, TuiShotFixture, TuiShotRequest, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { closeSharedBrowser, takeTuiShot } from "./shot.js";
+export { takePtyShot } from "./pty-shot.js";

package/dist/pty-exit-wrapper.d.ts

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

package/dist/pty-exit-wrapper.js

@@ -0,0 +1,50 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+const [, , token, statusPath, command, ...args] = process.argv;
+if (!token || !statusPath || !command) {
+    process.stderr.write("Astroshot PTY status wrapper requires a token, status path, and command.\n");
+    process.exit(2);
+}
+const child = spawn(command, args, {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+    windowsHide: true,
+});
+let reported = false;
+// Terminal-generated signals are delivered to the PTY process group. Keep the
+// bridge alive so the target's exit callback can report its authoritative code.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => { });
+}
+function reportExit(code) {
+    if (reported)
+        return;
+    reported = true;
+    const temporaryStatusPath = `${statusPath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temporaryStatusPath, String(code), { mode: 0o600 });
+        fs.renameSync(temporaryStatusPath, statusPath);
+    }
+    catch (error) {
+        process.stderr.write(`Unable to write PTY program exit status: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    const marker = `\x1b]777;astroshot-exit-${token}=${code}\x07`;
+    const writeMarker = () => {
+        process.stdout.write(marker, () => process.exit(0));
+    };
+    const markerDelay = Number(process.env.ASTROSHOT_TEST_DELAY_PTY_EXIT_MARKER_MS ?? 0);
+    if (Number.isFinite(markerDelay) && markerDelay > 0) {
+        setTimeout(writeMarker, markerDelay);
+    }
+    else {
+        writeMarker();
+    }
+}
+child.once("error", (error) => {
+    process.stderr.write(`Unable to launch PTY program: ${error.message}\n`);
+    reportExit(127);
+});
+child.once("exit", (code) => {
+    reportExit(code ?? 1);
+});

package/dist/pty-shot.d.ts

@@ -0,0 +1,2 @@
+import type { PtyShotRequest } from "./types.js";
+export declare function takePtyShot(request: PtyShotRequest): Promise<string>;