@archastro/astroshot 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,57 @@
+# `@archastro/astroshot`
+
+One command for deterministic React, Ink, and arbitrary terminal screenshots.
+
+```bash
+npx --@archastro:registry=https://registry.npmjs.org \
+  @archastro/astroshot init react
+npx --@archastro:registry=https://registry.npmjs.org \
+  @archastro/astroshot init ink
+npx --@archastro:registry=https://registry.npmjs.org \
+  @archastro/astroshot init pty
+
+npx --@archastro:registry=https://registry.npmjs.org \
+  @archastro/astroshot react ./react.shot.tsx -o ./react.png
+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 ./terminal.png
+```
+
+Use `react` for isolated browser components, `ink` for in-process Ink fixture
+trees, and `pty` for executable terminal applications such as Ratatui, Bubble
+Tea, Textual, and curses programs. `tui` remains an alias for `ink` for
+compatibility.
+
+Ink fixtures require project-local peers:
+
+```bash
+npm install --save-dev ink@^7.1 react@^19
+```
+
+Install the shared Chromium runtime once:
+
+```bash
+npx --@archastro:registry=https://registry.npmjs.org \
+  @archastro/astroshot install-browser
+```
+
+Use `react batch <manifest>` or `ink batch <manifest>` for maintained fixture
+sets. Run `<mode> --help` for mode-specific options.
+
+Fixture types are available from the unified package:
+
+```tsx
+import type { ReactShotFixture } from "@archastro/astroshot/react";
+import type { InkShotFixture } from "@archastro/astroshot/ink";
+```
+
+PTY YAML and JSON files launch `command` directly, without a shell. Their
+`actions` can wait for visible text, send named keys or literal text, and
+pause for bounded durations. Paths in `cwd` are relative to the fixture.
+On Windows, point `command` at an `.exe`; `.cmd` and `.bat` files are rejected
+because running them would introduce an implicit shell.
+
+Fixtures, imported modules, and PTY commands execute with the current user's
+permissions. Review untrusted files before capture and never include
+credentials or private customer data in fixtures or generated images.

package/bin/astroshot.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { writeFixtureTemplate } from "./templates.mjs";
+
+function help() {
+  console.log(`astroshot — one CLI for React, Ink, and PTY screenshots
+
+Usage:
+  astroshot init react [fixture.tsx] [--force]
+  astroshot init ink [fixture.tsx] [--force]
+  astroshot init pty [fixture.yaml] [--force]
+  astroshot react <fixture.tsx> -o <out.png> [options]
+  astroshot react shot <fixture.tsx> -o <out.png> [options]
+  astroshot react batch <manifest.yaml|json> [options]
+  astroshot ink <fixture.tsx> -o <out.png> [options]
+  astroshot ink batch <manifest.yaml|json> [options]
+  astroshot pty <fixture.yaml|json> -o <out.png> [options]
+  astroshot install-browser [--with-deps]
+
+Commands:
+  react              Capture an isolated React component
+  ink                Capture an Ink component fixture
+  pty                Capture any executable in a pseudoterminal
+  init               Generate a React, Ink, or PTY fixture template
+  install-browser    Install the shared Chromium runtime
+
+Compatibility: "astroshot tui" remains an alias for "astroshot ink".
+Run "astroshot <mode> --help" for mode options.`);
+}
+
+function modeHelp(mode) {
+  if (mode === "react") {
+    console.log(`astroshot react — deterministic React component screenshots
+
+Usage:
+  astroshot init react [fixture.tsx] [--force]
+  astroshot react <fixture.tsx> -o <out.png> [options]
+  astroshot react batch <manifest.yaml|json> [options]
+
+Options:
+  -o, --out <path>       Output PNG path
+  --root <dir>           Package root for imports and aliases
+  --config <path>        Fixture configuration path
+  --width <px>           Override viewport width
+  --height <px>          Override viewport height
+  --headed               Show Chromium for debugging
+  -h, --help             Show this help`);
+    return;
+  }
+
+  if (mode === "ink") {
+    console.log(`astroshot ink — deterministic Ink component screenshots
+
+Usage:
+  astroshot init ink [fixture.tsx] [--force]
+  astroshot ink <fixture.tsx> -o <out.png> [options]
+  astroshot ink 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 for debugging
+  -h, --help             Show this help`);
+    return;
+  }
+
+  console.log(`astroshot pty — screenshots of arbitrary terminal programs
+
+Usage:
+  astroshot init pty [fixture.yaml] [--force]
+  astroshot pty <fixture.yaml|json> -o <out.png> [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
+  --headed               Show Chromium for debugging
+  -h, --help             Show this help`);
+}
+
+function engineBin(mode) {
+  const packageName =
+    mode === "react" ? "@archastro/react-shot" : "@archastro/tui-shot";
+  const executable = mode === "react" ? "react-shot.mjs" : "tui-shot.mjs";
+  const entry = fileURLToPath(import.meta.resolve(packageName));
+  const packageRoot = path.dirname(path.dirname(entry));
+  return path.join(packageRoot, "bin", executable);
+}
+
+function runEngine(mode, arguments_) {
+  const engineMode = mode === "react" ? "react" : "tui";
+  const engineArguments =
+    mode === "pty" ? ["pty", ...arguments_] : arguments_;
+  const normalized =
+    mode !== "pty" &&
+    engineArguments[0] &&
+    /\.[cm]?tsx?$/.test(engineArguments[0])
+      ? ["shot", ...engineArguments]
+      : engineArguments;
+  const result = spawnSync(
+    process.execPath,
+    [engineBin(engineMode), ...normalized],
+    { stdio: "inherit" },
+  );
+  if (result.error) {
+    console.error(`astroshot could not start ${mode} capture: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.signal) process.kill(process.pid, result.signal);
+  process.exit(result.status ?? 1);
+}
+
+function initHelp() {
+  console.log(`astroshot init — generate a fixture template
+
+Usage:
+  astroshot init react [fixture.tsx] [--force]
+  astroshot init ink [fixture.tsx] [--force]
+  astroshot init pty [fixture.yaml] [--force]
+
+Defaults:
+  react.shot.tsx
+  ink.shot.tsx
+  pty.shot.yaml
+
+Existing files are never replaced unless --force is passed.`);
+}
+
+function runInit(arguments_) {
+  if (
+    arguments_.length === 0 ||
+    arguments_[0] === "help" ||
+    arguments_[0] === "-h" ||
+    arguments_[0] === "--help"
+  ) {
+    initHelp();
+    process.exit(arguments_.length === 0 ? 1 : 0);
+  }
+
+  const mode = arguments_[0];
+  const rest = arguments_.slice(1);
+  const force = rest.includes("--force") || rest.includes("-f");
+  const unknownFlags = rest.filter(
+    (value) => value.startsWith("-") && value !== "--force" && value !== "-f",
+  );
+  if (unknownFlags.length) {
+    throw new Error(`Unknown init flag: ${unknownFlags[0]}`);
+  }
+  const positionals = rest.filter((value) => !value.startsWith("-"));
+  if (positionals.length > 1) {
+    throw new Error("init accepts at most one output path");
+  }
+  const result = writeFixtureTemplate({
+    mode,
+    outputPath: positionals[0],
+    force,
+  });
+  console.log(`Created ${result.label} fixture: ${result.absolutePath}`);
+}
+
+const [command, ...arguments_] = process.argv.slice(2);
+
+if (command === "-v" || command === "--version") {
+  const packageJSON = JSON.parse(
+    fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  );
+  console.log(packageJSON.version);
+  process.exit(0);
+}
+
+if (!command || command === "help" || command === "-h" || command === "--help") {
+  help();
+  process.exit(command ? 0 : 1);
+}
+
+if (command === "install-browser") {
+  runEngine("react", ["install-browser", ...arguments_]);
+}
+
+if (command === "init") {
+  try {
+    runInit(arguments_);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (command === "react" || command === "ink" || command === "tui" || command === "pty") {
+  const canonicalMode = command === "tui" ? "ink" : command;
+  if (
+    arguments_.length === 0 ||
+    arguments_[0] === "help" ||
+    arguments_[0] === "-h" ||
+    arguments_[0] === "--help"
+  ) {
+    modeHelp(canonicalMode);
+    process.exit(arguments_.length === 0 ? 1 : 0);
+  }
+  runEngine(canonicalMode, arguments_);
+}
+
+console.error(`Unknown command: ${command}`);
+help();
+process.exit(1);

package/bin/templates.mjs

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const REACT_TEMPLATE = `import type { ReactShotFixture } from "@archastro/astroshot/react";
+
+function ExampleCard() {
+  return (
+    <article
+      data-astroshot
+      style={{
+        width: 420,
+        padding: 24,
+        borderRadius: 16,
+        background: "#f8fafc",
+        color: "#0f172a",
+        fontFamily: "system-ui, sans-serif",
+        boxShadow: "0 20px 50px rgba(15, 23, 42, 0.16)",
+      }}
+    >
+      <h1 style={{ margin: "0 0 8px", fontSize: 24 }}>React fixture</h1>
+      <p style={{ margin: 0 }}>Replace this component with the state you want to capture.</p>
+    </article>
+  );
+}
+
+export default {
+  width: 720,
+  height: 420,
+  background: "#e2e8f0",
+  selector: "[data-astroshot]",
+  waitFor: "text=React fixture",
+  component: <ExampleCard />,
+} satisfies ReactShotFixture;
+`;
+
+const INK_TEMPLATE = `import React from "react";
+import { Box, Text } from "ink";
+import type { InkShotFixture } from "@archastro/astroshot/ink";
+
+export default {
+  cols: 64,
+  rows: 12,
+  expectText: ["Ink fixture", "Ready to capture"],
+  component: (
+    <Box borderStyle="round" borderColor="cyan" paddingX={1} flexDirection="column">
+      <Text bold color="cyan">Ink fixture</Text>
+      <Text>Ready to capture</Text>
+    </Box>
+  ),
+} satisfies InkShotFixture;
+`;
+
+const PTY_TEMPLATE = `version: 1
+command: ./target/debug/my-tui
+args: []
+cwd: .
+cols: 100
+rows: 30
+timeoutMs: 15000
+actions:
+  - waitFor: "Choose an option"
+  - key: down
+  - key: enter
+  - waitFor: "Ready"
+expectText:
+  - "Ready"
+`;
+
+const PTY_JSON_TEMPLATE = `${JSON.stringify(
+  {
+    version: 1,
+    command: "./target/debug/my-tui",
+    args: [],
+    cwd: ".",
+    cols: 100,
+    rows: 30,
+    timeoutMs: 15000,
+    actions: [
+      { waitFor: "Choose an option" },
+      { key: "down" },
+      { key: "enter" },
+      { waitFor: "Ready" },
+    ],
+    expectText: ["Ready"],
+  },
+  null,
+  2,
+)}\n`;
+
+const TEMPLATES = {
+  react: {
+    defaultPath: "react.shot.tsx",
+    label: "React",
+    source: REACT_TEMPLATE,
+  },
+  ink: {
+    defaultPath: "ink.shot.tsx",
+    label: "Ink",
+    source: INK_TEMPLATE,
+  },
+  pty: {
+    defaultPath: "pty.shot.yaml",
+    label: "PTY",
+    source: PTY_TEMPLATE,
+  },
+};
+
+export function canonicalTemplateMode(mode) {
+  return mode === "tui" ? "ink" : mode;
+}
+
+export function writeFixtureTemplate({
+  mode,
+  outputPath,
+  force = false,
+  cwd = process.cwd(),
+}) {
+  const canonicalMode = canonicalTemplateMode(mode);
+  const template = TEMPLATES[canonicalMode];
+  if (!template) {
+    throw new Error("init requires one of: react, ink, pty");
+  }
+
+  const requestedPath = outputPath ?? template.defaultPath;
+  const absolutePath = path.resolve(cwd, requestedPath);
+  const expectedExtension = canonicalMode === "pty" ? /\.(?:ya?ml|json)$/i : /\.tsx$/i;
+  if (!expectedExtension.test(absolutePath)) {
+    throw new Error(
+      canonicalMode === "pty"
+        ? "PTY fixture templates must use .yaml, .yml, or .json"
+        : `${template.label} fixture templates must use .tsx`,
+    );
+  }
+
+  const parentDirectory = path.dirname(absolutePath);
+  fs.mkdirSync(parentDirectory, { recursive: true });
+  const source =
+    canonicalMode === "pty" && path.extname(absolutePath).toLowerCase() === ".json"
+      ? PTY_JSON_TEMPLATE
+      : template.source;
+  if (!force) {
+    try {
+      fs.writeFileSync(absolutePath, source, {
+        encoding: "utf8",
+        flag: "wx",
+      });
+    } catch (error) {
+      if (error?.code === "EEXIST") {
+        throw new Error(`Refusing to overwrite ${absolutePath}; pass --force to replace it`);
+      }
+      throw error;
+    }
+  } else {
+    let existing;
+    try {
+      existing = fs.lstatSync(absolutePath);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    if (existing?.isSymbolicLink()) {
+      throw new Error(`Refusing to replace symbolic link ${absolutePath}`);
+    }
+    if (existing?.isDirectory()) {
+      throw new Error(`Refusing to replace directory ${absolutePath}`);
+    }
+    const temporaryPath = path.join(
+      parentDirectory,
+      `.${path.basename(absolutePath)}.${process.pid}.${Date.now()}.tmp`,
+    );
+    try {
+      fs.writeFileSync(temporaryPath, source, {
+        encoding: "utf8",
+        flag: "wx",
+      });
+      fs.renameSync(temporaryPath, absolutePath);
+    } finally {
+      fs.rmSync(temporaryPath, { force: true });
+    }
+  }
+
+  return {
+    absolutePath,
+    label: template.label,
+    mode: canonicalMode,
+  };
+}

package/ink.d.ts

@@ -0,0 +1,5 @@
+export * from "@archastro/tui-shot";
+export type {
+  TuiShotFixture as InkShotFixture,
+  TuiShotRequest as InkShotRequest,
+} from "@archastro/tui-shot";

package/ink.js

@@ -0,0 +1 @@
+export * from "@archastro/tui-shot";

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@archastro/astroshot",
+  "version": "0.1.0",
+  "description": "One CLI for deterministic React and terminal UI screenshots",
+  "keywords": [
+    "react",
+    "ink",
+    "pty",
+    "ratatui",
+    "terminal",
+    "screenshot",
+    "visual-testing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArchAstro/astroshots.git",
+    "directory": "packages/astroshot"
+  },
+  "homepage": "https://github.com/ArchAstro/astroshots#readme",
+  "bugs": {
+    "url": "https://github.com/ArchAstro/astroshots/issues"
+  },
+  "type": "module",
+  "bin": {
+    "astroshot": "bin/astroshot.mjs"
+  },
+  "exports": {
+    "./react": {
+      "types": "./react.d.ts",
+      "import": "./react.js"
+    },
+    "./ink": {
+      "types": "./ink.d.ts",
+      "import": "./ink.js"
+    },
+    "./pty": {
+      "types": "./pty.d.ts",
+      "import": "./pty.js"
+    },
+    "./tui": {
+      "types": "./tui.d.ts",
+      "import": "./tui.js"
+    }
+  },
+  "files": [
+    "bin",
+    "react.d.ts",
+    "react.js",
+    "ink.d.ts",
+    "ink.js",
+    "pty.d.ts",
+    "pty.js",
+    "tui.d.ts",
+    "tui.js",
+    "README.md"
+  ],
+  "scripts": {
+    "pretest": "npm run build --workspace @archastro/react-shot && npm run build --workspace @archastro/tui-shot",
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@archastro/react-shot": "0.1.0",
+    "@archastro/tui-shot": "0.1.0"
+  }
+}

package/pty.d.ts

@@ -0,0 +1,8 @@
+export {
+  closeSharedBrowser,
+  takePtyShot,
+  type PtyAction,
+  type PtyKey,
+  type PtyShotFixture,
+  type PtyShotRequest,
+} from "@archastro/tui-shot";

package/pty.js

@@ -0,0 +1 @@
+export { closeSharedBrowser, takePtyShot } from "@archastro/tui-shot";

package/react.d.ts

@@ -0,0 +1 @@
+export * from "@archastro/react-shot";

package/react.js

@@ -0,0 +1 @@
+export * from "@archastro/react-shot";

package/tui.d.ts

@@ -0,0 +1 @@
+export * from "@archastro/tui-shot";

package/tui.js

@@ -0,0 +1 @@
+export * from "@archastro/tui-shot";