astroshot 0.2.1

package/node_modules/@archastro/movie-harness/dist/sources/pty.d.ts

@@ -0,0 +1,15 @@
+import type { MovieArtifact, MovieSessionOptions, PtyMovieFixture } from "../types.js";
+export declare function loadPtyMovieFixture(fixturePath: string): PtyMovieFixture;
+export type PtyMovieSessionOptions = Omit<MovieSessionOptions, "source"> & {
+    fixturePath: string;
+};
+/**
+ * Run a PTY fixture, sample truecolor terminal frames into a MovieSession,
+ * and publish poster + video. Color path: SGR → xterm cells → HTML → Chromium.
+ */
+export declare function recordPtyMovie(options: PtyMovieSessionOptions): Promise<MovieArtifact>;
+/** Synthetic truecolor PTY-like movie without node-pty (for CI smoke). */
+export declare function recordTruecolorDemoMovie(options: Omit<MovieSessionOptions, "source"> & {
+    /** Hex color without #, default 7c5cff */
+    color?: string;
+}): Promise<MovieArtifact>;

package/node_modules/@archastro/movie-harness/dist/sources/pty.js

@@ -0,0 +1,330 @@
+import fs from "node:fs";
+import path from "node:path";
+import { chromium } from "playwright";
+import YAML from "yaml";
+import { MovieSession } from "../session.js";
+import { createHeadlessTerminal, terminalDocument, terminalPlainText, terminalToHtml, writeTerminal, } from "../terminal-paint.js";
+const KEYSTROKES = {
+    enter: "\r",
+    up: "\x1b[A",
+    down: "\x1b[B",
+    right: "\x1b[C",
+    left: "\x1b[D",
+    tab: "\t",
+    escape: "\x1b",
+    backspace: "\x7f",
+    space: " ",
+    "ctrl-c": "\x03",
+    "ctrl-d": "\x04",
+};
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function loadPtyMovieFixture(fixturePath) {
+    const absolute = path.resolve(fixturePath);
+    if (!fs.existsSync(absolute)) {
+        throw new Error(`PTY fixture not found: ${absolute}`);
+    }
+    const text = fs.readFileSync(absolute, "utf8");
+    const value = absolute.endsWith(".json") ? JSON.parse(text) : YAML.parse(text);
+    if (!isRecord(value)) {
+        throw new Error(`Invalid PTY fixture ${absolute}: document must be object`);
+    }
+    if (value.version !== 1) {
+        throw new Error(`Invalid PTY fixture ${absolute}: version must be 1`);
+    }
+    if (typeof value.command !== "string" || !value.command.trim()) {
+        throw new Error(`Invalid PTY fixture ${absolute}: command required`);
+    }
+    return value;
+}
+/**
+ * Run a PTY fixture, sample truecolor terminal frames into a MovieSession,
+ * and publish poster + video. Color path: SGR → xterm cells → HTML → Chromium.
+ */
+export async function recordPtyMovie(options) {
+    const fixture = loadPtyMovieFixture(options.fixturePath);
+    const fixtureDir = path.dirname(path.resolve(options.fixturePath));
+    const cols = fixture.cols ?? 80;
+    const rows = fixture.rows ?? 24;
+    const fontSize = fixture.fontSize ?? 14;
+    const lineHeight = fixture.lineHeight ?? 1.35;
+    const padding = fixture.padding ?? 16;
+    const borderRadius = fixture.borderRadius ?? 12;
+    const scale = fixture.scale ?? 2;
+    const background = fixture.background ?? "#090a12";
+    const foreground = fixture.foreground ?? "#e8e8f2";
+    const fontFamily = fixture.fontFamily ??
+        "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace";
+    const fps = fixture.movieFps ?? options.fps ?? 12;
+    const timeoutMs = fixture.timeoutMs ?? 30_000;
+    const settleMs = fixture.settleMs ?? 80;
+    const paint = {
+        cols,
+        rows,
+        foreground,
+        background,
+        fontFamily,
+        fontSize,
+        lineHeight,
+        padding,
+        borderRadius,
+        scale,
+    };
+    const { cssWidth, cssHeight } = terminalDocument("", paint);
+    const size = {
+        width: cssWidth + 32,
+        height: cssHeight + 32,
+    };
+    const session = MovieSession.create({
+        ...options,
+        size,
+        fps,
+        source: "pty",
+    });
+    const terminal = createHeadlessTerminal(cols, rows);
+    let browser;
+    let page;
+    let sampleTimer;
+    let sampling = Promise.resolve();
+    try {
+        browser = await chromium.launch({ headless: true });
+        page = await browser.newPage({
+            viewport: size,
+            deviceScaleFactor: scale,
+        });
+        const sample = async () => {
+            if (!page)
+                return;
+            const rowsHtml = terminalToHtml(terminal, {
+                cols,
+                rows,
+                foreground,
+                background,
+            });
+            const { html } = terminalDocument(rowsHtml, paint);
+            await page.setContent(html, { waitUntil: "load" });
+            const png = await page.locator("[data-tui-shot]").screenshot({
+                type: "png",
+                omitBackground: true,
+            });
+            session.pushFrame(png);
+        };
+        const intervalMs = Math.max(40, Math.round(1000 / fps));
+        sampleTimer = setInterval(() => {
+            sampling = sampling.then(sample).catch(() => undefined);
+        }, intervalMs);
+        await runPtyProgram({
+            fixture,
+            fixtureDir,
+            terminal,
+            cols,
+            rows,
+            timeoutMs,
+            settleMs,
+        });
+        clearInterval(sampleTimer);
+        sampleTimer = undefined;
+        await sampling;
+        // Final frame after settle — must match still-shot color path.
+        await sample();
+        return await session.stop({ status: options.status ?? "running" });
+    }
+    finally {
+        if (sampleTimer)
+            clearInterval(sampleTimer);
+        await page?.close().catch(() => undefined);
+        await browser?.close().catch(() => undefined);
+        terminal.dispose();
+    }
+}
+async function runPtyProgram(args) {
+    const { fixture, fixtureDir, terminal, cols, rows, timeoutMs, settleMs } = args;
+    let spawnPty;
+    try {
+        ({ spawn: spawnPty } = await import("node-pty"));
+    }
+    catch (error) {
+        throw new Error("PTY movie capture requires the optional node-pty native addon.", { cause: error });
+    }
+    const cwd = fixture.cwd
+        ? path.resolve(fixtureDir, fixture.cwd)
+        : fixtureDir;
+    const command = resolveCommand(fixture.command, cwd);
+    const childEnv = {
+        ...process.env,
+        TERM: "xterm-256color",
+        COLORTERM: "truecolor",
+        ...fixture.env,
+    };
+    let writes = Promise.resolve();
+    let exited = null;
+    let resolveExit = null;
+    const exitPromise = new Promise((resolve) => {
+        resolveExit = resolve;
+    });
+    const child = spawnPty(command, fixture.args ?? [], {
+        name: "xterm-256color",
+        cols,
+        rows,
+        cwd,
+        env: childEnv,
+    });
+    child.onData((data) => {
+        writes = writes.then(() => writeTerminal(terminal, data));
+    });
+    child.onExit((event) => {
+        exited = event;
+        resolveExit?.();
+    });
+    const deadline = Date.now() + timeoutMs;
+    const screen = () => terminalPlainText(terminal, rows);
+    const remaining = () => Math.max(0, deadline - Date.now());
+    try {
+        for (const action of fixture.actions ?? []) {
+            if (remaining() === 0) {
+                throw new Error(`PTY movie exceeded timeoutMs ${timeoutMs}`);
+            }
+            await runAction(action, {
+                child,
+                writes: () => writes,
+                screen,
+                remaining,
+                deadline,
+                exited: () => exited,
+                exitPromise,
+            });
+        }
+        await delay(Math.min(settleMs, remaining()));
+        await writes;
+    }
+    finally {
+        try {
+            child.kill();
+        }
+        catch {
+            /* already dead */
+        }
+        // Drain a short window so dispose is clean.
+        await Promise.race([exitPromise, delay(500)]);
+    }
+    for (const expected of fixture.expectText ?? []) {
+        if (!screen().includes(expected)) {
+            throw new Error(`PTY movie did not render expected text ${JSON.stringify(expected)}. ` +
+                `Visible:\n${screen().slice(0, 1200)}`);
+        }
+    }
+    // Exit code is advisory: we may kill the child after sampling. Non-zero
+    // before expectText is still surfaced via missing text / timeouts above.
+    void exited;
+    void fixture.allowNonZeroExit;
+}
+async function runAction(action, ctx) {
+    if ("waitFor" in action) {
+        const actionDeadline = Math.min(ctx.deadline, Date.now() + (action.timeoutMs ?? 120_000));
+        while (Date.now() <= actionDeadline) {
+            await ctx.writes();
+            if (ctx.screen().includes(action.waitFor))
+                return;
+            if (ctx.exited())
+                break;
+            await delay(20);
+        }
+        throw new Error(`Timed out waiting for ${JSON.stringify(action.waitFor)}. Visible:\n${ctx.screen().slice(0, 1200)}`);
+    }
+    if ("waitForExit" in action) {
+        const actionDeadline = Math.min(ctx.deadline, Date.now() + (action.timeoutMs ?? 120_000));
+        while (Date.now() <= actionDeadline) {
+            if (ctx.exited())
+                return;
+            await Promise.race([ctx.exitPromise, delay(20)]);
+        }
+        throw new Error("Timed out waiting for PTY exit");
+    }
+    if ("key" in action) {
+        ctx.child.write(KEYSTROKES[action.key]);
+        return;
+    }
+    if ("text" in action) {
+        ctx.child.write(action.text);
+        return;
+    }
+    await delay(Math.min(action.pauseMs, ctx.remaining()));
+}
+function resolveCommand(command, cwd) {
+    if (command.includes(path.sep) || command.startsWith(".")) {
+        return path.resolve(cwd, command);
+    }
+    // PATH lookup — node-pty resolves bare names on most platforms.
+    return command;
+}
+/** Synthetic truecolor PTY-like movie without node-pty (for CI smoke). */
+export async function recordTruecolorDemoMovie(options) {
+    const color = options.color ?? "7c5cff";
+    const r = Number.parseInt(color.slice(0, 2), 16);
+    const g = Number.parseInt(color.slice(2, 4), 16);
+    const b = Number.parseInt(color.slice(4, 6), 16);
+    if ([r, g, b].some((n) => Number.isNaN(n))) {
+        throw new Error(`invalid color ${color}`);
+    }
+    const cols = 40;
+    const rows = 8;
+    const paint = {
+        cols,
+        rows,
+        foreground: "#e8e8f2",
+        background: "#090a12",
+        fontFamily: "ui-monospace, monospace",
+        fontSize: 16,
+        lineHeight: 1.35,
+        padding: 16,
+        borderRadius: 12,
+        scale: 2,
+    };
+    const { cssWidth, cssHeight } = terminalDocument("", paint);
+    const size = { width: cssWidth + 32, height: cssHeight + 32 };
+    const session = MovieSession.create({
+        ...options,
+        size,
+        fps: options.fps ?? 10,
+        source: "pty",
+    });
+    const terminal = createHeadlessTerminal(cols, rows);
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage({
+            viewport: size,
+            deviceScaleFactor: 2,
+        });
+        const labels = ["truecolor", "movie", "harness", color];
+        for (const label of labels) {
+            await writeTerminal(terminal, `\x1b[2J\x1b[H\x1b[38;2;${r};${g};${b}m${label}\x1b[0m\r\n`);
+            const rowsHtml = terminalToHtml(terminal, {
+                cols,
+                rows,
+                foreground: paint.foreground,
+                background: paint.background,
+            });
+            if (!rowsHtml.includes(`color:#${color}`)) {
+                throw new Error(`truecolor path lost #${color}; html=${rowsHtml.slice(0, 200)}`);
+            }
+            const { html } = terminalDocument(rowsHtml, paint);
+            await page.setContent(html, { waitUntil: "load" });
+            const png = await page.locator("[data-tui-shot]").screenshot({
+                type: "png",
+                omitBackground: true,
+            });
+            session.pushFrame(png);
+            await delay(120);
+        }
+        await page.close();
+        return await session.stop({ status: options.status ?? "running" });
+    }
+    finally {
+        terminal.dispose();
+        await browser.close().catch(() => undefined);
+    }
+}

package/node_modules/@archastro/movie-harness/dist/terminal-paint.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Truecolor ANSI → HTML paint path (same model as tui-shot terminal-html).
+ * Color fidelity is a hard requirement for PTY movies.
+ */
+import { type Terminal as TerminalType } from "@xterm/headless";
+export type HeadlessTerminal = TerminalType;
+export interface TerminalPaintOptions {
+    cols: number;
+    rows: number;
+    foreground: string;
+    background: string;
+    fontFamily: string;
+    fontSize: number;
+    lineHeight: number;
+    padding: number;
+    borderRadius: number;
+    scale: number;
+}
+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: Pick<TerminalPaintOptions, "cols" | "rows" | "foreground" | "background">): string;
+export declare function terminalDocument(terminalRows: string, options: TerminalPaintOptions): {
+    html: string;
+    cssWidth: number;
+    cssHeight: number;
+};

package/node_modules/@archastro/movie-harness/dist/terminal-paint.js

@@ -0,0 +1,190 @@
+/**
+ * Truecolor ANSI → HTML paint path (same model as tui-shot terminal-html).
+ * Color fidelity is a hard requirement for PTY movies.
+ */
+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("");
+}
+export function terminalDocument(terminalRows, options) {
+    const cssWidth = Math.ceil(options.cols * options.fontSize * 0.62 + options.padding * 2);
+    const cssHeight = Math.ceil(options.rows * options.fontSize * options.lineHeight + options.padding * 2);
+    const html = `<!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: ${options.padding}px;
+        border: 1px solid rgba(185, 168, 255, .18);
+        border-radius: ${options.borderRadius}px;
+        background: ${options.background};
+        color: ${options.foreground};
+        box-shadow: 0 18px 44px rgba(0, 0, 0, .28);
+        font-family: ${options.fontFamily};
+        font-size: ${options.fontSize}px;
+        font-variant-ligatures: none;
+        font-weight: 400;
+        line-height: ${options.lineHeight};
+        text-rendering: geometricPrecision;
+      }
+      .tui-row {
+        height: ${options.lineHeight}em;
+        overflow: hidden;
+        white-space: pre;
+      }
+    </style>
+  </head>
+  <body>
+    <div data-tui-shot role="img" aria-label="Terminal screenshot">${terminalRows}</div>
+  </body>
+</html>`;
+    return { html, cssWidth, cssHeight };
+}

package/node_modules/@archastro/movie-harness/dist/types.d.ts

@@ -0,0 +1,140 @@
+export type MovieSourceKind = "frames" | "browser" | "pty" | "desktop.window" | "desktop.display" | "desktop.region";
+export type MovieFormat = "webm" | "mp4";
+export type ManifestStatus = "running" | "pass" | "fail" | "idle";
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface MovieChapter {
+    slug: string;
+    tMs: number;
+    note?: string;
+}
+export interface MovieArtifact {
+    videoPath: string;
+    posterPath: string;
+    durationMs: number;
+    chapters: MovieChapter[];
+    source: MovieSourceKind;
+    feature: string;
+    slug: string;
+    sequence: string;
+    runId: string;
+}
+export interface MovieSessionOptions {
+    /** Feature directory under .astroshot/ (kebab-case). */
+    feature: string;
+    /** Filename slug for this movie. */
+    slug: string;
+    /** Worktree / project root that contains (or will contain) .astroshot/. */
+    root?: string;
+    /** Stable run id; defaults to feature-timestamp-pid. */
+    runId?: string;
+    title?: string;
+    description?: string;
+    size?: Size;
+    /** Target encode frame rate. Default 15. */
+    fps?: number;
+    /** Output container. Default webm (Playwright-native). */
+    format?: MovieFormat;
+    /** Manifest status while recording. Default running. */
+    status?: ManifestStatus;
+    source: MovieSourceKind;
+}
+export interface EncodeFramesRequest {
+    framePaths: string[];
+    outPath: string;
+    size: Size;
+    fps: number;
+    /** Wall-clock duration override when frame timestamps are irregular. */
+    durationMs?: number;
+}
+export interface SinkMovieRequest {
+    root: string;
+    feature: string;
+    slug: string;
+    runId: string;
+    title?: string;
+    description?: string;
+    status?: ManifestStatus;
+    source: MovieSourceKind;
+    posterPath: string;
+    videoPath: string;
+    durationMs: number;
+    chapters: MovieChapter[];
+    size?: Size;
+}
+export interface SinkMovieResult {
+    sequence: string;
+    posterDest: string;
+    videoDest: string;
+    manifestPath: string;
+    featureDir: string;
+}
+/** On-disk state for multi-process frames CLI (start / push / mark / stop). */
+export interface PersistedFrameSession {
+    version: 1;
+    id: string;
+    feature: string;
+    slug: string;
+    root: string;
+    runId: string;
+    title?: string;
+    description?: string;
+    size: Size;
+    fps: number;
+    format: MovieFormat;
+    source: "frames";
+    startedAtMs: number;
+    frameDir: string;
+    frameCount: number;
+    chapters: MovieChapter[];
+}
+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 PtyMovieFixture {
+    version: 1;
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    timeoutMs?: number;
+    settleMs?: number;
+    allowNonZeroExit?: boolean;
+    actions?: PtyAction[];
+    expectText?: string[];
+    background?: string;
+    foreground?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    lineHeight?: number;
+    padding?: number;
+    borderRadius?: number;
+    scale?: number;
+    /** Sample rate for the movie. Defaults to session fps. */
+    movieFps?: number;
+}
+export interface BrowserMovieOptions {
+    /** Navigate here when the harness owns the page. */
+    url?: string;
+    /** Optional script module that exports `default` async (page) => void. */
+    scriptPath?: string;
+    /** Reuse an existing headed browser (debug). Default headless. */
+    headed?: boolean;
+    /** How long to keep recording after script ends (ms). Default 0. */
+    settleMs?: number;
+}

package/node_modules/@archastro/movie-harness/dist/types.js

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