astroshot 0.2.1

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

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { chromium } from "playwright";
+import { ensureDir } from "./paths.js";
+function hasFfmpeg() {
+    const result = spawnSync("ffmpeg", ["-version"], { encoding: "utf8" });
+    return result.status === 0;
+}
+/**
+ * Encode a PNG sequence to WebM/MP4.
+ *
+ * Prefer ffmpeg when present (fast, high quality). Otherwise replay frames in
+ * headless Chromium with Playwright recordVideo — no native deps beyond the
+ * Chromium we already ship for stills.
+ */
+export async function encodeFrames(request) {
+    if (request.framePaths.length === 0) {
+        throw new Error("encodeFrames requires at least one frame");
+    }
+    for (const frame of request.framePaths) {
+        if (!fs.existsSync(frame)) {
+            throw new Error(`frame not found: ${frame}`);
+        }
+    }
+    const outPath = path.resolve(request.outPath);
+    ensureDir(path.dirname(outPath));
+    const ext = path.extname(outPath).toLowerCase();
+    const durationMs = request.durationMs ??
+        Math.max(1, Math.round((request.framePaths.length / request.fps) * 1000));
+    if (hasFfmpeg()) {
+        await encodeWithFfmpeg(request, outPath);
+        return { videoPath: outPath, durationMs };
+    }
+    if (ext === ".mp4") {
+        // Playwright emits WebM; without ffmpeg we cannot remux to MP4.
+        const webmPath = outPath.replace(/\.mp4$/i, ".webm");
+        await encodeWithPlaywright(request, webmPath);
+        return { videoPath: webmPath, durationMs };
+    }
+    await encodeWithPlaywright(request, outPath);
+    return { videoPath: outPath, durationMs };
+}
+async function encodeWithFfmpeg(request, outPath) {
+    const listDir = fs.mkdtempSync(path.join(os.tmpdir(), "astroshot-movie-ff-"));
+    try {
+        const listPath = path.join(listDir, "frames.txt");
+        const frameDuration = 1 / request.fps;
+        const lines = [];
+        for (const frame of request.framePaths) {
+            lines.push(`file '${frame.replaceAll("'", "'\\''")}'`);
+            lines.push(`duration ${frameDuration.toFixed(6)}`);
+        }
+        // Last frame needs a trailing file entry for concat demuxer.
+        const last = request.framePaths.at(-1);
+        lines.push(`file '${last.replaceAll("'", "'\\''")}'`);
+        fs.writeFileSync(listPath, `${lines.join("\n")}\n`);
+        const ext = path.extname(outPath).toLowerCase();
+        const args = ext === ".mp4"
+            ? [
+                "-y",
+                "-f",
+                "concat",
+                "-safe",
+                "0",
+                "-i",
+                listPath,
+                "-vf",
+                `scale=${request.size.width}:${request.size.height}:flags=neighbor`,
+                "-c:v",
+                "libx264",
+                "-pix_fmt",
+                "yuv420p",
+                "-movflags",
+                "+faststart",
+                outPath,
+            ]
+            : [
+                "-y",
+                "-f",
+                "concat",
+                "-safe",
+                "0",
+                "-i",
+                listPath,
+                "-vf",
+                `scale=${request.size.width}:${request.size.height}:flags=neighbor`,
+                "-c:v",
+                "libvpx-vp9",
+                "-b:v",
+                "2M",
+                "-pix_fmt",
+                "yuv420p",
+                outPath,
+            ];
+        const result = spawnSync("ffmpeg", args, { encoding: "utf8" });
+        if (result.status !== 0) {
+            throw new Error(`ffmpeg failed (${result.status}): ${result.stderr?.slice(0, 800) ?? ""}`);
+        }
+    }
+    finally {
+        fs.rmSync(listDir, { recursive: true, force: true });
+    }
+}
+async function encodeWithPlaywright(request, outPath) {
+    const videoDir = fs.mkdtempSync(path.join(os.tmpdir(), "astroshot-movie-pw-"));
+    const size = request.size;
+    const frameMs = Math.max(1, Math.round(1000 / request.fps));
+    let browser;
+    try {
+        browser = await chromium.launch({ headless: true });
+        const context = await browser.newContext({
+            viewport: size,
+            deviceScaleFactor: 1,
+            recordVideo: {
+                dir: videoDir,
+                size,
+            },
+        });
+        const page = await context.newPage();
+        for (const framePath of request.framePaths) {
+            const bytes = fs.readFileSync(framePath);
+            const b64 = bytes.toString("base64");
+            const mime = path.extname(framePath).toLowerCase() === ".jpg" ||
+                path.extname(framePath).toLowerCase() === ".jpeg"
+                ? "image/jpeg"
+                : "image/png";
+            await page.setContent(`<!doctype html>
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <style>
+              html, body {
+                margin: 0;
+                width: ${size.width}px;
+                height: ${size.height}px;
+                overflow: hidden;
+                background: #000;
+              }
+              img {
+                display: block;
+                width: ${size.width}px;
+                height: ${size.height}px;
+                object-fit: fill;
+                image-rendering: pixelated;
+              }
+            </style>
+          </head>
+          <body>
+            <img src="data:${mime};base64,${b64}" width="${size.width}" height="${size.height}" />
+          </body>
+        </html>`, { waitUntil: "load" });
+            await page.waitForTimeout(frameMs);
+        }
+        // Hold the last frame a beat so the encoder emits it.
+        await page.waitForTimeout(Math.max(frameMs, 100));
+        await context.close();
+        const videos = fs
+            .readdirSync(videoDir)
+            .filter((name) => name.endsWith(".webm"))
+            .map((name) => path.join(videoDir, name));
+        if (videos.length === 0) {
+            throw new Error("Playwright did not produce a WebM video");
+        }
+        // Prefer the newest file if multiple.
+        videos.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+        fs.copyFileSync(videos[0], outPath);
+    }
+    finally {
+        await browser?.close().catch(() => undefined);
+        fs.rmSync(videoDir, { recursive: true, force: true });
+    }
+}
+/** Copy the last frame as the poster PNG. */
+export function posterFromFrames(framePaths, outPath) {
+    if (framePaths.length === 0) {
+        throw new Error("posterFromFrames requires at least one frame");
+    }
+    const last = framePaths.at(-1);
+    ensureDir(path.dirname(outPath));
+    fs.copyFileSync(last, outPath);
+    return outPath;
+}

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

@@ -0,0 +1,14 @@
+export { encodeFrames, posterFromFrames } from "./encode.js";
+export { encodeSolidPng, encodeRgbPng } from "./png.js";
+export { assertKebabCase, assertSlug, defaultRunId, featureDir, humanize, resolveRoot, } from "./paths.js";
+export { MovieSession } from "./session.js";
+export { finalizeManifest, sinkMovie } from "./sink.js";
+export { formatSourceCatalog, recommendSource, SOURCE_CATALOG, SOURCE_DECISION_TABLE, sourceHintForError, } from "./source-help.js";
+export type { SourceAdvice, SourceKindHelp } from "./source-help.js";
+export { recordBrowserMovie } from "./sources/browser.js";
+export { assertDesktopToolchain, checkScreenRecordingAccess, describeDesktopWindow, desktopMatchFromFlags, ensureScreenRecordingAccess, formatScreenRecordingDeniedHelp, isNearlyBlankPng, listDesktopWindows, matchDesktopWindow, openScreenRecordingSettings, recordDesktopWindowMovie, } from "./sources/desktop-macos.js";
+export type { DesktopWindowInfo, DesktopWindowMatch, DesktopWindowMovieOptions, ScreenAccessReport, } from "./sources/desktop-macos.js";
+export { loadFrameSession, markFrameSession, pushFrameToSession, startFrameSession, stopFrameSession, } from "./sources/frames-store.js";
+export { loadPtyMovieFixture, recordPtyMovie, recordTruecolorDemoMovie, } from "./sources/pty.js";
+export { createHeadlessTerminal, terminalPlainText, terminalToHtml, writeTerminal, } from "./terminal-paint.js";
+export type { BrowserMovieOptions, EncodeFramesRequest, ManifestStatus, MovieArtifact, MovieChapter, MovieFormat, MovieSessionOptions, MovieSourceKind, PersistedFrameSession, PtyAction, PtyKey, PtyMovieFixture, SinkMovieRequest, SinkMovieResult, Size, } from "./types.js";

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

@@ -0,0 +1,11 @@
+export { encodeFrames, posterFromFrames } from "./encode.js";
+export { encodeSolidPng, encodeRgbPng } from "./png.js";
+export { assertKebabCase, assertSlug, defaultRunId, featureDir, humanize, resolveRoot, } from "./paths.js";
+export { MovieSession } from "./session.js";
+export { finalizeManifest, sinkMovie } from "./sink.js";
+export { formatSourceCatalog, recommendSource, SOURCE_CATALOG, SOURCE_DECISION_TABLE, sourceHintForError, } from "./source-help.js";
+export { recordBrowserMovie } from "./sources/browser.js";
+export { assertDesktopToolchain, checkScreenRecordingAccess, describeDesktopWindow, desktopMatchFromFlags, ensureScreenRecordingAccess, formatScreenRecordingDeniedHelp, isNearlyBlankPng, listDesktopWindows, matchDesktopWindow, openScreenRecordingSettings, recordDesktopWindowMovie, } from "./sources/desktop-macos.js";
+export { loadFrameSession, markFrameSession, pushFrameToSession, startFrameSession, stopFrameSession, } from "./sources/frames-store.js";
+export { loadPtyMovieFixture, recordPtyMovie, recordTruecolorDemoMovie, } from "./sources/pty.js";
+export { createHeadlessTerminal, terminalPlainText, terminalToHtml, writeTerminal, } from "./terminal-paint.js";

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

@@ -0,0 +1,9 @@
+export declare function resolveRoot(root?: string): string;
+export declare function assertKebabCase(name: string, label: string): void;
+export declare function assertSlug(slug: string): void;
+export declare function featureDir(root: string, feature: string): string;
+export declare function movieStateDir(root: string, feature: string): string;
+export declare function defaultRunId(feature: string): string;
+export declare function humanize(slug: string): string;
+export declare function ensureDir(dir: string): void;
+export declare function nextSequence(featureDirectory: string): string;

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

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+export function resolveRoot(root) {
+    if (root)
+        return path.resolve(root);
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+        }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+export function assertKebabCase(name, label) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+        throw new Error(`${label} must be kebab-case [a-z0-9-]+, got ${JSON.stringify(name)}`);
+    }
+}
+export function assertSlug(slug) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+        throw new Error(`slug must be kebab-case [a-z0-9-]+, got ${JSON.stringify(slug)}`);
+    }
+}
+export function featureDir(root, feature) {
+    return path.join(root, ".astroshot", feature);
+}
+export function movieStateDir(root, feature) {
+    return path.join(featureDir(root, feature), ".movie");
+}
+export function defaultRunId(feature) {
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+    return `${feature}-${stamp}-${process.pid}`;
+}
+export function humanize(slug) {
+    return slug
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+export function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function nextSequence(featureDirectory) {
+    const entries = fs.existsSync(featureDirectory)
+        ? fs.readdirSync(featureDirectory)
+        : [];
+    let max = 0;
+    for (const name of entries) {
+        const match = /^(\d{4})-/.exec(name);
+        if (match)
+            max = Math.max(max, Number(match[1]));
+    }
+    return String(max + 1).padStart(4, "0");
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Minimal truecolor PNG encoder (no deps). Used for synthetic frames in tests
+ * and demos when a full browser paint is not needed.
+ */
+export declare function encodeSolidPng(width: number, height: number, rgb: [number, number, number]): Buffer;
+export declare function encodeRgbPng(width: number, height: number, 
+/** Row-major RGB triples, length width*height*3 */
+pixels: Buffer | Uint8Array): Buffer;

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

@@ -0,0 +1,79 @@
+import zlib from "node:zlib";
+/**
+ * Minimal truecolor PNG encoder (no deps). Used for synthetic frames in tests
+ * and demos when a full browser paint is not needed.
+ */
+export function encodeSolidPng(width, height, rgb) {
+    const [r, g, b] = rgb;
+    const stride = 1 + width * 3;
+    const raw = Buffer.alloc(stride * height);
+    for (let y = 0; y < height; y++) {
+        const row = y * stride;
+        raw[row] = 0; // filter none
+        for (let x = 0; x < width; x++) {
+            const i = row + 1 + x * 3;
+            raw[i] = r;
+            raw[i + 1] = g;
+            raw[i + 2] = b;
+        }
+    }
+    return wrapPng(width, height, 2, raw); // 2 = truecolor
+}
+export function encodeRgbPng(width, height, 
+/** Row-major RGB triples, length width*height*3 */
+pixels) {
+    if (pixels.length < width * height * 3) {
+        throw new Error("pixel buffer too small");
+    }
+    const stride = 1 + width * 3;
+    const raw = Buffer.alloc(stride * height);
+    for (let y = 0; y < height; y++) {
+        const row = y * stride;
+        raw[row] = 0;
+        const src = y * width * 3;
+        for (let x = 0; x < width; x++) {
+            const di = row + 1 + x * 3;
+            const si = src + x * 3;
+            raw[di] = pixels[si];
+            raw[di + 1] = pixels[si + 1];
+            raw[di + 2] = pixels[si + 2];
+        }
+    }
+    return wrapPng(width, height, 2, raw);
+}
+function wrapPng(width, height, colorType, raw) {
+    const signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = colorType;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+    const compressed = zlib.deflateSync(raw);
+    return Buffer.concat([
+        signature,
+        chunk("IHDR", ihdr),
+        chunk("IDAT", compressed),
+        chunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+function chunk(type, data) {
+    const typeBuf = Buffer.from(type, "ascii");
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+    return Buffer.concat([len, typeBuf, data, crc]);
+}
+function crc32(buf) {
+    let c = 0xffff_ffff;
+    for (let i = 0; i < buf.length; i++) {
+        c ^= buf[i];
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xedb8_8320 ^ (c >>> 1) : c >>> 1;
+        }
+    }
+    return (c ^ 0xffff_ffff) >>> 0;
+}

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

@@ -0,0 +1,45 @@
+import type { ManifestStatus, MovieArtifact, MovieSessionOptions, MovieSourceKind, Size } from "./types.js";
+export declare class MovieSession {
+    readonly feature: string;
+    readonly slug: string;
+    readonly root: string;
+    readonly runId: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly size: Size;
+    readonly fps: number;
+    readonly format: "webm" | "mp4";
+    readonly source: MovieSourceKind;
+    private readonly workDir;
+    private readonly frameDir;
+    private readonly startedAtMs;
+    private frameCount;
+    private chapters;
+    private stopped;
+    private status;
+    private constructor();
+    static create(options: MovieSessionOptions): MovieSession;
+    /** Elapsed ms since session start (for chapter timestamps). */
+    elapsedMs(): number;
+    mark(slug: string, note?: string): void;
+    /**
+     * Push a PNG (or JPEG) frame into the session. Bytes are written to disk
+     * immediately so a crash still leaves a recoverable sequence.
+     */
+    pushFrame(image: Buffer, extension?: "png" | "jpg" | "jpeg"): string;
+    pushFrameFile(imagePath: string): string;
+    listFrames(): string[];
+    /**
+     * Encode collected frames, write poster + video into .astroshot/, update
+     * manifest. Cleans the temp work directory afterward.
+     */
+    stop(options?: {
+        status?: ManifestStatus;
+        /** Skip encode and only publish when frames already form the movie via another path. */
+        videoPath?: string;
+        posterPath?: string;
+        durationMs?: number;
+    }): Promise<MovieArtifact>;
+    finalize(status: "pass" | "fail" | "idle"): Promise<void>;
+    private assertOpen;
+}

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

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { encodeFrames, posterFromFrames } from "./encode.js";
+import { assertKebabCase, assertSlug, defaultRunId, ensureDir, resolveRoot, } from "./paths.js";
+import { finalizeManifest, sinkMovie } from "./sink.js";
+export class MovieSession {
+    feature;
+    slug;
+    root;
+    runId;
+    title;
+    description;
+    size;
+    fps;
+    format;
+    source;
+    workDir;
+    frameDir;
+    startedAtMs;
+    frameCount = 0;
+    chapters = [];
+    stopped = false;
+    status;
+    constructor(options, workDir) {
+        this.feature = options.feature;
+        this.slug = options.slug;
+        this.root = resolveRoot(options.root);
+        this.runId = options.runId ?? defaultRunId(options.feature);
+        this.title = options.title;
+        this.description = options.description;
+        this.size = options.size ?? { width: 1280, height: 720 };
+        this.fps = options.fps ?? 15;
+        this.format = options.format ?? "webm";
+        this.source = options.source;
+        this.status = options.status ?? "running";
+        this.workDir = workDir;
+        this.frameDir = path.join(workDir, "frames");
+        this.startedAtMs = Date.now();
+        ensureDir(this.frameDir);
+    }
+    static create(options) {
+        assertKebabCase(options.feature, "feature");
+        assertSlug(options.slug);
+        if (options.fps !== undefined && !(options.fps > 0 && options.fps <= 60)) {
+            throw new Error("fps must be in (0, 60]");
+        }
+        const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "astroshot-movie-"));
+        return new MovieSession(options, workDir);
+    }
+    /** Elapsed ms since session start (for chapter timestamps). */
+    elapsedMs() {
+        return Date.now() - this.startedAtMs;
+    }
+    mark(slug, note) {
+        this.assertOpen();
+        assertSlug(slug);
+        this.chapters.push({
+            slug,
+            tMs: this.elapsedMs(),
+            note,
+        });
+    }
+    /**
+     * Push a PNG (or JPEG) frame into the session. Bytes are written to disk
+     * immediately so a crash still leaves a recoverable sequence.
+     */
+    pushFrame(image, extension = "png") {
+        this.assertOpen();
+        if (image.length < 8) {
+            throw new Error("pushFrame: empty image buffer");
+        }
+        const index = String(this.frameCount).padStart(6, "0");
+        const file = path.join(this.frameDir, `${index}.${extension}`);
+        fs.writeFileSync(file, image);
+        this.frameCount += 1;
+        return file;
+    }
+    pushFrameFile(imagePath) {
+        this.assertOpen();
+        const bytes = fs.readFileSync(imagePath);
+        const ext = path.extname(imagePath).toLowerCase().replace(".", "");
+        if (ext !== "png" && ext !== "jpg" && ext !== "jpeg") {
+            throw new Error(`pushFrameFile: unsupported extension .${ext}`);
+        }
+        return this.pushFrame(bytes, ext);
+    }
+    listFrames() {
+        if (!fs.existsSync(this.frameDir))
+            return [];
+        return fs
+            .readdirSync(this.frameDir)
+            .filter((name) => /\.(png|jpe?g)$/i.test(name))
+            .sort()
+            .map((name) => path.join(this.frameDir, name));
+    }
+    /**
+     * Encode collected frames, write poster + video into .astroshot/, update
+     * manifest. Cleans the temp work directory afterward.
+     */
+    async stop(options) {
+        this.assertOpen();
+        this.stopped = true;
+        const status = options?.status ?? this.status;
+        try {
+            let videoPath = options?.videoPath;
+            let posterPath = options?.posterPath;
+            let durationMs = options?.durationMs;
+            const frames = this.listFrames();
+            if (!videoPath) {
+                if (frames.length === 0) {
+                    throw new Error("MovieSession.stop: no frames and no videoPath");
+                }
+                const outExt = this.format === "mp4" ? ".mp4" : ".webm";
+                const encoded = await encodeFrames({
+                    framePaths: frames,
+                    outPath: path.join(this.workDir, `movie${outExt}`),
+                    size: this.size,
+                    fps: this.fps,
+                });
+                videoPath = encoded.videoPath;
+                durationMs = encoded.durationMs;
+            }
+            if (!posterPath) {
+                if (frames.length === 0) {
+                    throw new Error("MovieSession.stop: no frames for poster");
+                }
+                posterPath = posterFromFrames(frames, path.join(this.workDir, "poster.png"));
+            }
+            durationMs ??= this.elapsedMs();
+            const published = sinkMovie({
+                root: this.root,
+                feature: this.feature,
+                slug: this.slug,
+                runId: this.runId,
+                title: this.title,
+                description: this.description,
+                status,
+                source: this.source,
+                posterPath,
+                videoPath,
+                durationMs,
+                chapters: this.chapters,
+                size: this.size,
+            });
+            return {
+                videoPath: published.videoDest,
+                posterPath: published.posterDest,
+                durationMs,
+                chapters: this.chapters,
+                source: this.source,
+                feature: this.feature,
+                slug: this.slug,
+                sequence: published.sequence,
+                runId: this.runId,
+            };
+        }
+        finally {
+            fs.rmSync(this.workDir, { recursive: true, force: true });
+        }
+    }
+    async finalize(status) {
+        finalizeManifest(this.root, this.feature, this.runId, status);
+    }
+    assertOpen() {
+        if (this.stopped) {
+            throw new Error("MovieSession is already stopped");
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { SinkMovieRequest, SinkMovieResult } from "./types.js";
+/**
+ * Publish poster + video into .astroshot/<feature>/ and append a movie shot
+ * to manifest.json. Poster basename is the review key (matches stills).
+ */
+export declare function sinkMovie(request: SinkMovieRequest): SinkMovieResult;
+export declare function finalizeManifest(root: string, feature: string, runId: string, status: "pass" | "fail" | "idle" | "running"): void;