astroshot 0.2.1 → 0.2.2

package/node_modules/@archastro/astroshot-review/dist/ui/text-input.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Single-line composer used for feedback. Owns the keyboard while active. */
+import { Box, Text, useInput } from "ink";
+import { useState } from "react";
+import { theme } from "./theme.js";
+export function TextInput({ placeholder, width, onSubmit, onCancel, submitLabel }) {
+    const [value, setValue] = useState("");
+    const [cursor, setCursor] = useState(0);
+    useInput((input, key) => {
+        if (key.escape) {
+            onCancel();
+            return;
+        }
+        // A paste (or a fast PTY) delivers several characters at once, possibly
+        // ending in a newline. Insert the printable part, then submit if asked.
+        const pasted = input.replace(/[\r\n]/g, "");
+        const wantsSubmit = key.return || /[\r\n]/.test(input);
+        if (pasted.length > 1 && !key.ctrl && !key.meta) {
+            const next = value.slice(0, cursor) + pasted + value.slice(cursor);
+            setValue(next);
+            setCursor(cursor + pasted.length);
+            if (wantsSubmit)
+                onSubmit(next);
+            return;
+        }
+        if (wantsSubmit) {
+            onSubmit(value);
+            return;
+        }
+        if (key.backspace || key.delete) {
+            if (cursor > 0) {
+                setValue(value.slice(0, cursor - 1) + value.slice(cursor));
+                setCursor(cursor - 1);
+            }
+            return;
+        }
+        if (key.leftArrow) {
+            setCursor(Math.max(0, cursor - 1));
+            return;
+        }
+        if (key.rightArrow) {
+            setCursor(Math.min(value.length, cursor + 1));
+            return;
+        }
+        if (key.ctrl && input === "a") {
+            setCursor(0);
+            return;
+        }
+        if (key.ctrl && input === "e") {
+            setCursor(value.length);
+            return;
+        }
+        if (key.ctrl && input === "u") {
+            setValue("");
+            setCursor(0);
+            return;
+        }
+        if (key.ctrl || key.meta || key.tab || key.upArrow || key.downArrow)
+            return;
+        if (!input)
+            return;
+        setValue(value.slice(0, cursor) + input + value.slice(cursor));
+        setCursor(cursor + input.length);
+    });
+    const innerWidth = Math.max(4, width - 2);
+    // Keep the caret visible by scrolling the text horizontally.
+    const start = Math.max(0, cursor - innerWidth + 1);
+    const visible = value.slice(start, start + innerWidth);
+    const caretIndex = cursor - start;
+    const before = visible.slice(0, caretIndex);
+    const at = visible.charAt(caretIndex) || " ";
+    const after = visible.slice(caretIndex + 1);
+    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsx(Box, { borderStyle: "round", borderColor: theme.blue, paddingX: 1, width: width, children: value.length === 0 ? (_jsxs(Text, { children: [_jsx(Text, { inverse: true, children: " " }), _jsx(Text, { color: theme.muted, children: placeholder.slice(0, innerWidth - 1) })] })) : (_jsxs(Text, { children: [before, _jsx(Text, { inverse: true, children: at }), after] })) }), _jsxs(Text, { color: theme.muted, children: ["  ⏎ ", submitLabel ?? "send", "  ·  esc cancel"] })] }));
+}

package/node_modules/@archastro/astroshot-review/dist/ui/theme.d.ts

@@ -0,0 +1,21 @@
+/** Color tokens mirroring the macOS app's palette, expressed for chalk. */
+export declare const theme: {
+    readonly brand: "#54e0a0";
+    readonly amber: "#f0b86e";
+    readonly blue: "#7aa2f7";
+    readonly green: "#54e0a0";
+    readonly purple: "#b9a8ff";
+    readonly red: "#f0727a";
+    readonly muted: "#8a8a9a";
+    readonly faint: "#5a5a6a";
+    readonly text: "#e8e8f2";
+    readonly surface: "#1c1b19";
+    readonly stage: "#2a2a29";
+    readonly selection: "#2e3140";
+};
+export declare function relativeTime(fromMs: number, nowMs?: number): string;
+export declare function clockTime(ms: number): string;
+export declare function isoDateTime(ms: number): string;
+/** `Aug 11, 2026 at 2:54 PM` style, close to Foundation's abbreviated/short formats. */
+export declare function abbreviatedDateTime(input: number | string): string;
+export declare function truncate(text: string, width: number): string;

package/node_modules/@archastro/astroshot-review/dist/ui/theme.js

@@ -0,0 +1,63 @@
+/** Color tokens mirroring the macOS app's palette, expressed for chalk. */
+export const theme = {
+    brand: "#54e0a0",
+    amber: "#f0b86e",
+    blue: "#7aa2f7",
+    green: "#54e0a0",
+    purple: "#b9a8ff",
+    red: "#f0727a",
+    muted: "#8a8a9a",
+    faint: "#5a5a6a",
+    text: "#e8e8f2",
+    surface: "#1c1b19",
+    stage: "#2a2a29",
+    selection: "#2e3140",
+};
+export function relativeTime(fromMs, nowMs = Date.now()) {
+    const seconds = Math.max(0, Math.round((nowMs - fromMs) / 1000));
+    if (seconds < 45)
+        return "just now";
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours} hr ago`;
+    const days = Math.round(hours / 24);
+    if (days < 30)
+        return `${days} day${days === 1 ? "" : "s"} ago`;
+    const months = Math.round(days / 30);
+    if (months < 12)
+        return `${months} mo ago`;
+    return `${Math.round(months / 12)} yr ago`;
+}
+export function clockTime(ms) {
+    const date = new Date(ms);
+    return [date.getHours(), date.getMinutes(), date.getSeconds()]
+        .map((value) => String(value).padStart(2, "0"))
+        .join(":");
+}
+export function isoDateTime(ms) {
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** `Aug 11, 2026 at 2:54 PM` style, close to Foundation's abbreviated/short formats. */
+export function abbreviatedDateTime(input) {
+    const date = typeof input === "number" ? new Date(input) : new Date(input);
+    if (Number.isNaN(date.getTime()))
+        return typeof input === "string" ? input : "";
+    return date.toLocaleString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+    });
+}
+export function truncate(text, width) {
+    if (width <= 0)
+        return "";
+    const single = text.replace(/\s+/g, " ").trim();
+    if (single.length <= width)
+        return single;
+    return width <= 1 ? "…" : `${single.slice(0, width - 1)}…`;
+}

package/node_modules/@archastro/astroshot-review/dist/video/ffmpeg.d.ts

@@ -0,0 +1,54 @@
+import { type ImageSize } from "../images/png.js";
+export interface FfmpegInfo {
+    ffmpeg: string | null;
+    ffprobe: string | null;
+    version: string | null;
+}
+export declare function detectFfmpeg(env?: NodeJS.ProcessEnv): FfmpegInfo;
+export declare function resetFfmpegCache(): void;
+export interface VideoInfo {
+    width: number;
+    height: number;
+    durationMs: number | null;
+}
+export declare function probeVideo(videoPath: string, info?: FfmpegInfo): Promise<VideoInfo | null>;
+export interface VideoFrame {
+    png: Buffer;
+    width: number;
+    height: number;
+    /** Presentation time in milliseconds. */
+    tMs: number;
+    index: number;
+}
+export interface FramePlayerOptions {
+    videoPath: string;
+    /** Pixel box the frames must fit inside. */
+    bounds: ImageSize;
+    sourceSize: ImageSize;
+    fps?: number;
+    startMs?: number;
+    onFrame: (frame: VideoFrame) => void;
+    onEnd: () => void;
+    onError: (error: Error) => void;
+    ffmpegPath?: string;
+}
+/** Splits a concatenated PNG byte stream into whole files. */
+export declare function splitPngStream(buffer: Buffer): {
+    frames: Buffer[];
+    rest: Buffer;
+};
+export declare class FramePlayer {
+    private readonly options;
+    private child;
+    private pending;
+    private index;
+    private readonly fps;
+    private readonly startMs;
+    private stopped;
+    readonly frameSize: ImageSize;
+    constructor(options: FramePlayerOptions);
+    start(): void;
+    /** Time of the last delivered frame, in milliseconds. */
+    get positionMs(): number;
+    stop(): void;
+}

package/node_modules/@archastro/astroshot-review/dist/video/ffmpeg.js

@@ -0,0 +1,206 @@
+/**
+ * Movie playback through ffmpeg: decode the file at a modest frame rate,
+ * scaled to the stage, as a stream of PNG frames the terminal can draw with
+ * the graphics protocol. Seeking restarts the decoder at the new offset.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fitInside, readPngSize } from "../images/png.js";
+const EXTRA_BIN_DIRS = ["/opt/homebrew/bin", "/usr/local/bin"];
+const PNG_END = Buffer.from([0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82]);
+let cachedInfo = null;
+function findBinary(name, env) {
+    const dirs = [...(env.PATH ?? "").split(path.delimiter), ...EXTRA_BIN_DIRS].filter(Boolean);
+    for (const dir of dirs) {
+        const candidate = path.join(dir, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+export function detectFfmpeg(env = process.env) {
+    if (cachedInfo)
+        return cachedInfo;
+    const ffmpeg = env.ASTROSHOT_REVIEW_FFMPEG ?? findBinary("ffmpeg", env);
+    const ffprobe = findBinary("ffprobe", env);
+    let version = null;
+    if (ffmpeg) {
+        const result = spawnSync(ffmpeg, ["-version"], { encoding: "utf8" });
+        version = /ffmpeg version (\S+)/.exec(result.stdout ?? "")?.[1] ?? null;
+    }
+    cachedInfo = { ffmpeg, ffprobe, version };
+    return cachedInfo;
+}
+export function resetFfmpegCache() {
+    cachedInfo = null;
+}
+export async function probeVideo(videoPath, info = detectFfmpeg()) {
+    if (!info.ffprobe)
+        return null;
+    return new Promise((resolve) => {
+        const child = spawn(info.ffprobe, [
+            "-v",
+            "error",
+            "-select_streams",
+            "v:0",
+            "-show_entries",
+            "stream=width,height:format=duration",
+            "-of",
+            "json",
+            videoPath,
+        ]);
+        let output = "";
+        child.stdout.on("data", (chunk) => {
+            output += chunk.toString();
+        });
+        child.on("error", () => resolve(null));
+        child.on("close", () => {
+            try {
+                const parsed = JSON.parse(output);
+                const stream = parsed.streams?.[0];
+                if (!stream?.width || !stream.height)
+                    return resolve(null);
+                const duration = Number(parsed.format?.duration);
+                resolve({
+                    width: stream.width,
+                    height: stream.height,
+                    durationMs: Number.isFinite(duration) && duration > 0 ? Math.round(duration * 1000) : null,
+                });
+            }
+            catch {
+                resolve(null);
+            }
+        });
+    });
+}
+/** Splits a concatenated PNG byte stream into whole files. */
+export function splitPngStream(buffer) {
+    const frames = [];
+    let cursor = 0;
+    while (cursor < buffer.length) {
+        const end = buffer.indexOf(PNG_END, cursor);
+        if (end === -1)
+            break;
+        frames.push(buffer.subarray(cursor, end + PNG_END.length));
+        cursor = end + PNG_END.length;
+    }
+    return { frames, rest: buffer.subarray(cursor) };
+}
+export class FramePlayer {
+    options;
+    child = null;
+    pending = Buffer.alloc(0);
+    index = 0;
+    fps;
+    startMs;
+    stopped = false;
+    frameSize;
+    constructor(options) {
+        this.options = options;
+        this.fps = options.fps ?? 12;
+        this.startMs = options.startMs ?? 0;
+        this.frameSize = fitInside(options.sourceSize, options.bounds);
+        // Even dimensions keep every encoder happy.
+        this.frameSize = {
+            width: Math.max(2, this.frameSize.width - (this.frameSize.width % 2)),
+            height: Math.max(2, this.frameSize.height - (this.frameSize.height % 2)),
+        };
+    }
+    start() {
+        const ffmpeg = this.options.ffmpegPath ?? detectFfmpeg().ffmpeg;
+        if (!ffmpeg) {
+            this.options.onError(new Error("ffmpeg is not installed"));
+            return;
+        }
+        const args = [
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-nostdin",
+            "-re",
+            "-ss",
+            (this.startMs / 1000).toFixed(3),
+            "-i",
+            this.options.videoPath,
+            "-an",
+            "-vf",
+            `fps=${this.fps},scale=${this.frameSize.width}:${this.frameSize.height}:flags=fast_bilinear`,
+            "-f",
+            "image2pipe",
+            "-vcodec",
+            "png",
+            "-compression_level",
+            "3",
+            "-",
+        ];
+        const child = spawn(ffmpeg, args, { stdio: ["ignore", "pipe", "pipe"] });
+        this.child = child;
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.stdout?.on("data", (chunk) => {
+            if (this.stopped)
+                return;
+            this.pending = this.pending.length ? Buffer.concat([this.pending, chunk]) : chunk;
+            const { frames, rest } = splitPngStream(this.pending);
+            this.pending = rest;
+            for (const png of frames) {
+                const size = readPngSize(png);
+                if (!size)
+                    continue;
+                const frame = {
+                    png,
+                    width: size.width,
+                    height: size.height,
+                    tMs: this.startMs + Math.round((this.index * 1000) / this.fps),
+                    index: this.index,
+                };
+                this.index += 1;
+                this.options.onFrame(frame);
+            }
+        });
+        child.on("error", (error) => {
+            if (this.stopped)
+                return;
+            this.stopped = true;
+            this.options.onError(error);
+        });
+        child.on("close", (code) => {
+            if (this.stopped)
+                return;
+            this.stopped = true;
+            if (code && code !== 0) {
+                this.options.onError(new Error(`ffmpeg exited with ${code}: ${stderr.trim().slice(0, 300)}`));
+            }
+            else {
+                this.options.onEnd();
+            }
+        });
+    }
+    /** Time of the last delivered frame, in milliseconds. */
+    get positionMs() {
+        return this.startMs + Math.round((Math.max(0, this.index - 1) * 1000) / this.fps);
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        const child = this.child;
+        this.child = null;
+        if (child && child.exitCode === null) {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // Already gone.
+            }
+        }
+    }
+}

package/node_modules/@archastro/astroshot-review/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@archastro/astroshot-review",
+  "version": "0.2.2",
+  "description": "Terminal review tray for Astroshots: stream, review, and play .astroshot captures with Kitty graphics",
+  "keywords": [
+    "astroshots",
+    "ink",
+    "kitty",
+    "graphics",
+    "terminal",
+    "tui",
+    "screenshot",
+    "review"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArchAstro/astroshots.git",
+    "directory": "packages/astroshot-review"
+  },
+  "homepage": "https://github.com/ArchAstro/astroshots#readme",
+  "bugs": "https://github.com/ArchAstro/astroshots/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "astroshot-review": "bin/astroshot-review.mjs"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.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",
+    "pretest": "npm run build --workspace @archastro/tui-shot"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "ink": "^7.1.0",
+    "pngjs": "^7.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@archastro/tui-shot": "0.2.2",
+    "@types/node": "^22.0.0",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  }
+}

package/node_modules/@archastro/movie-harness/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archastro/movie-harness",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Universal movie capture harness for browser, PTY, desktop, and raw frames into .astroshot/",
   "keywords": [
     "astroshots",

package/node_modules/@archastro/react-shot/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archastro/react-shot",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Capture deterministic PNG screenshots from React and TSX fixtures",
   "keywords": [
     "react",
@@ -52,9 +52,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "test": "npm run build && vitest run",
-    "test:unit": "vitest run src/meta.test.ts",
-    "test:e2e": "npm run build && vitest run src/cli.e2e.test.ts",
+    "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 -p tsconfig.json --noEmit",
     "prepack": "npm run clean && npm run build"
   },

package/node_modules/@archastro/tui-shot/README.md

@@ -143,3 +143,12 @@ await closeSharedBrowser();
 ```
 
 Ink fixtures support Ink 7 and React 19 as peer dependencies.
+
+## Graphics-aware PTY captures
+
+Add `graphics: kitty` to a PTY fixture to emulate a terminal that supports the
+Kitty graphics protocol. The harness answers the capability query and cell-size
+reports, records transmitted images and their placements at the cursor, strips
+the escape sequences from the text, and paints the pictures into the PNG in
+cell units. `KittyGraphicsTracker` is exported for harnesses that drive a PTY
+themselves.

package/node_modules/@archastro/tui-shot/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { closeSharedBrowser, takeTuiShot } from "./shot.js";
 export { takePtyShot } from "./pty-shot.js";
+export { KittyGraphicsTracker, encodePng, overlaysToHtml } from "./kitty-graphics.js";
+export type { GraphicsOverlay } from "./kitty-graphics.js";
 export type { BatchEntry, BatchManifest, PtyAction, PtyKey, PtyShotFixture, PtyShotRequest, TuiShotFixture, TuiShotRequest, } from "./types.js";

package/node_modules/@archastro/tui-shot/dist/index.js

@@ -1,2 +1,3 @@
 export { closeSharedBrowser, takeTuiShot } from "./shot.js";
 export { takePtyShot } from "./pty-shot.js";
+export { KittyGraphicsTracker, encodePng, overlaysToHtml } from "./kitty-graphics.js";

package/node_modules/@archastro/tui-shot/dist/kitty-graphics.d.ts

@@ -0,0 +1,45 @@
+import type { HeadlessTerminal } from "./terminal-html.js";
+export interface GraphicsOverlay {
+    col: number;
+    row: number;
+    cols: number;
+    rows: number;
+    z: number;
+    /** PNG bytes as a data URL. */
+    dataUrl: string;
+}
+export interface KittyTrackerOptions {
+    terminal: HeadlessTerminal;
+    cols: number;
+    rows: number;
+    cellWidth: number;
+    cellHeight: number;
+    /** Where terminal replies (query answers, device attributes) are sent. */
+    reply: (data: string) => void;
+}
+/** Encode raw RGB/RGBA pixels as a PNG (filter type 0 on every scanline). */
+export declare function encodePng(pixels: Buffer, width: number, height: number, channels: 3 | 4): Buffer;
+export declare class KittyGraphicsTracker {
+    private readonly options;
+    private readonly images;
+    private readonly placements;
+    private pending;
+    private carry;
+    private queryLog;
+    constructor(options: KittyTrackerOptions);
+    /** Queries the child sent, for assertions. */
+    get queries(): readonly string[];
+    get imageCount(): number;
+    /** Feed child output: text goes to the terminal, graphics are recorded. */
+    write(data: string): Promise<void>;
+    private writeText;
+    private handleCommand;
+    private storeImage;
+    private place;
+    private delete;
+    private pngFor;
+    /** Pictures currently visible, ordered for painting. */
+    overlays(): GraphicsOverlay[];
+}
+/** HTML for overlays, positioned in cell units so they track the font metrics. */
+export declare function overlaysToHtml(overlays: GraphicsOverlay[], lineHeight: number): string;