astroshot 0.2.1

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

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertKebabCase, assertSlug, ensureDir, featureDir, humanize, nextSequence, } from "./paths.js";
+function readManifest(manifestPath) {
+    if (!fs.existsSync(manifestPath))
+        return null;
+    const raw = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    if (!raw || typeof raw !== "object")
+        return null;
+    if (!Array.isArray(raw.shots))
+        raw.shots = [];
+    return raw;
+}
+function writeAtomic(filePath, contents) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    const tmp = path.join(dir, `.${path.basename(filePath)}.tmp.${process.pid}.${Date.now()}`);
+    fs.writeFileSync(tmp, contents);
+    fs.renameSync(tmp, filePath);
+}
+/**
+ * Publish poster + video into .astroshot/<feature>/ and append a movie shot
+ * to manifest.json. Poster basename is the review key (matches stills).
+ */
+export function sinkMovie(request) {
+    assertKebabCase(request.feature, "feature");
+    assertSlug(request.slug);
+    const dir = featureDir(request.root, request.feature);
+    ensureDir(dir);
+    const sequence = nextSequence(dir);
+    const posterName = `${sequence}-${request.slug}.png`;
+    const videoExt = path.extname(request.videoPath).toLowerCase() || ".webm";
+    const videoName = `${sequence}-${request.slug}${videoExt}`;
+    const posterDest = path.join(dir, posterName);
+    const videoDest = path.join(dir, videoName);
+    if (!fs.existsSync(request.posterPath)) {
+        throw new Error(`poster not found: ${request.posterPath}`);
+    }
+    if (!fs.existsSync(request.videoPath)) {
+        throw new Error(`video not found: ${request.videoPath}`);
+    }
+    fs.copyFileSync(request.posterPath, posterDest);
+    fs.copyFileSync(request.videoPath, videoDest);
+    const manifestPath = path.join(dir, "manifest.json");
+    const existing = readManifest(manifestPath);
+    const continueRun = existing &&
+        existing.run_id === request.runId &&
+        existing.status === "running";
+    const shot = {
+        id: sequence,
+        file: posterName,
+        slug: request.slug,
+        title: request.title ?? humanize(request.slug),
+        description: request.description,
+        captured_at: new Date().toISOString(),
+        viewport: request.size
+            ? `${request.size.width}x${request.size.height}`
+            : undefined,
+        kind: "movie",
+        video: videoName,
+        duration_ms: Math.round(request.durationMs),
+        source: request.source,
+        chapters: request.chapters.map((chapter) => ({
+            slug: chapter.slug,
+            t_ms: Math.round(chapter.tMs),
+            note: chapter.note,
+        })),
+    };
+    const manifest = continueRun
+        ? {
+            ...existing,
+            status: request.status ?? existing.status,
+            description: request.description ?? existing.description,
+            shots: [...existing.shots, shot],
+        }
+        : {
+            version: 1,
+            feature: request.feature,
+            run_id: request.runId,
+            status: request.status ?? "running",
+            description: request.description,
+            shots: [shot],
+        };
+    writeAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return {
+        sequence,
+        posterDest,
+        videoDest,
+        manifestPath,
+        featureDir: dir,
+    };
+}
+export function finalizeManifest(root, feature, runId, status) {
+    assertKebabCase(feature, "feature");
+    const dir = featureDir(root, feature);
+    const manifestPath = path.join(dir, "manifest.json");
+    const existing = readManifest(manifestPath);
+    if (!existing) {
+        writeAtomic(manifestPath, `${JSON.stringify({
+            version: 1,
+            feature,
+            run_id: runId,
+            status,
+            shots: [],
+        }, null, 2)}\n`);
+        return;
+    }
+    if (existing.run_id !== runId) {
+        throw new Error(`manifest run_id ${JSON.stringify(existing.run_id)} does not match ${JSON.stringify(runId)}`);
+    }
+    existing.status = status;
+    writeAtomic(manifestPath, `${JSON.stringify(existing, null, 2)}\n`);
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Source selection guidance for humans and coding agents.
+ * Keep this the single source of truth for "which --source should I use?"
+ */
+export declare const SOURCE_DECISION_TABLE: string;
+export type SourceKindHelp = "browser" | "pty" | "pty-demo" | "desktop.window" | "desktop.display" | "desktop.region" | "frames";
+export interface SourceAdvice {
+    source: SourceKindHelp;
+    summary: string;
+    useWhen: string[];
+    neverWhen: string[];
+    requiredFlags: string[];
+    example: string;
+}
+export declare const SOURCE_CATALOG: Record<SourceKindHelp, SourceAdvice>;
+/** Short one-liner for errors when source is wrong/missing. */
+export declare function sourceHintForError(kind?: string): string;
+export declare function formatSourceCatalog(): string;
+/**
+ * Lightweight advisor for agents: pass free-text intent, get a recommended source.
+ * This is heuristic — the decision table is authoritative.
+ *
+ * Order matters: TUI beats native (don't desktop Terminal.app); native/menu-bar
+ * beats browser so "record the Astroshots tray" never defaults to Chromium.
+ */
+export declare function recommendSource(intent: string): {
+    source: SourceKindHelp;
+    reason: string;
+};

package/node_modules/@archastro/movie-harness/dist/source-help.js

@@ -0,0 +1,222 @@
+/**
+ * Source selection guidance for humans and coding agents.
+ * Keep this the single source of truth for "which --source should I use?"
+ */
+export const SOURCE_DECISION_TABLE = `
+Which --source should I use?
+============================
+
+Pick the FIRST row that matches the thing you need to record:
+
+| You need to record…                              | Use --source        | Why |
+|--------------------------------------------------|---------------------|-----|
+| A web page / SPA / agent-browser session         | browser             | Headless Chromium; no Screen Recording TCC; deterministic viewport |
+| An isolated React component (not a full app)     | browser (or still)  | Prefer stills via \`astroshot react\` unless motion matters |
+| A TUI / CLI / Ink / Ratatui / truecolor terminal | pty                 | SGR→xterm truecolor path; NEVER screenshot Terminal.app |
+| Color-critical terminal (brand purple, etc.)     | pty                 | Host terminal themes remapping 16 colors would lie |
+| A native macOS app window (SwiftUI, Electron…)   | desktop.window      | Real window pixels via screencapture; needs Screen Recording |
+| Menu-bar / tray / status-item / LSUIElement app  | desktop.window      | Real app chrome; list-windows may include popover layers |
+| The whole monitor / multi-window desktop         | desktop.display     | (not implemented yet — use desktop.window or frames) |
+| Frames from any other tool (Unity, remote, custom)| frames              | You push PNG/JPEG; harness only encodes + sinks |
+| You already have PNG frames on disk              | frames              | Multi-process start/push-frame/stop |
+
+Hard rules for agents
+---------------------
+1. Terminal/TUI color → always \`pty\` (or \`pty-demo\` for a truecolor smoke test).
+   Do NOT use desktop.window on Terminal.app / iTerm / Ghostty for TUI review.
+2. Web UI → \`browser\`, not desktop of a browser window (loses headless CI + viewport control).
+3. Native Mac app chrome → \`desktop.window\` with --bundle-id or --window-id.
+4. Unknown engine that can dump images → \`frames\`.
+5. Always write into .astroshot/ via this harness (poster PNG + video) so Astroshots can stream posters today.
+
+Permission / environment
+------------------------
+| Source          | Needs                  | CI-friendly? |
+|-----------------|------------------------|--------------|
+| browser         | Playwright Chromium    | yes (headless) |
+| pty / pty-demo  | node-pty (optional)    | yes |
+| frames          | nothing special        | yes |
+| desktop.window  | macOS + Screen Recording TCC + WindowTools (Swift) | hard |
+
+Quick commands
+--------------
+  # Web journey
+  astroshot movie run --source browser --feature f --slug s --url https://…
+
+  # Truecolor TUI fixture
+  astroshot movie run --source pty --feature f --slug s --fixture ./flow.pty.yaml
+
+  # Native app window (largest window of bundle, 3s)
+  astroshot movie run --source desktop.window --feature f --slug s \\
+    --bundle-id com.example.App --duration-ms 3000
+
+  # List windows (macOS)
+  astroshot movie list-windows
+
+  # Push your own frames
+  astroshot movie start --feature f --slug s
+  astroshot movie push-frame --feature f --file ./frame.png
+  astroshot movie stop --feature f --status pass
+`.trim();
+export const SOURCE_CATALOG = {
+    browser: {
+        source: "browser",
+        summary: "Headless Chromium viewport movie via Playwright recordVideo.",
+        useWhen: [
+            "Recording a web app, SPA, or agent-browser session",
+            "You need a fixed viewport and no OS permissions",
+            "CI / headless environments",
+        ],
+        neverWhen: [
+            "Recording a TUI (use pty)",
+            "Recording native app chrome (use desktop.window)",
+        ],
+        requiredFlags: ["--feature", "--slug"],
+        example: "astroshot movie run --source browser --feature web --slug home --url https://example.com --settle-ms 500",
+    },
+    pty: {
+        source: "pty",
+        summary: "Truecolor terminal movie: node-pty → xterm SGR cells → Chromium frames.",
+        useWhen: [
+            "Ink, Ratatui, Bubble Tea, curses, or any CLI TUI",
+            "Color accuracy matters (truecolor / 256-color)",
+            "Deterministic fixture YAML/JSON journeys",
+        ],
+        neverWhen: [
+            "Screenshotting Terminal.app/iTerm/Ghostty with desktop.window",
+            "Web UIs",
+        ],
+        requiredFlags: ["--feature", "--slug", "--fixture"],
+        example: "astroshot movie run --source pty --feature tui --slug flow --fixture ./flow.pty.yaml",
+    },
+    "pty-demo": {
+        source: "pty-demo",
+        summary: "Built-in truecolor SGR smoke test (no external program).",
+        useWhen: [
+            "Verifying the truecolor paint/encode path",
+            "CI smoke without a real TUI binary",
+        ],
+        neverWhen: ["Production journey capture (use pty + fixture)"],
+        requiredFlags: ["--feature", "--slug"],
+        example: "astroshot movie run --source pty-demo --feature tui --slug brand",
+    },
+    "desktop.window": {
+        source: "desktop.window",
+        summary: "macOS native window pixels via CGWindowList + screencapture -l sampling.",
+        useWhen: [
+            "SwiftUI / AppKit / Electron / any real Mac window",
+            "Menu-bar / tray / status-item / LSUIElement apps (e.g. Astroshots)",
+            "You need the actual app chrome and OS rendering",
+        ],
+        neverWhen: [
+            "TUIs (use pty — terminal themes lie about color)",
+            "Web-only journeys you can drive headlessly (use browser)",
+            "Linux/Windows CI without a Mac (not supported yet)",
+        ],
+        requiredFlags: [
+            "--feature",
+            "--slug",
+            "one of: --window-id | --bundle-id | --title-regex | --owner | --pid",
+        ],
+        example: "astroshot movie run --source desktop.window --feature app --slug onboard --bundle-id com.example.App --duration-ms 4000 --fps 10",
+    },
+    "desktop.display": {
+        source: "desktop.display",
+        summary: "Full display capture (planned).",
+        useWhen: ["Whole-monitor demos"],
+        neverWhen: ["Prefer desktop.window when a single app matters"],
+        requiredFlags: ["(not implemented)"],
+        example: "astroshot movie run --source desktop.window …  # until desktop.display ships",
+    },
+    "desktop.region": {
+        source: "desktop.region",
+        summary: "Display region crop (planned).",
+        useWhen: ["Fixed rectangle on a display"],
+        neverWhen: ["Prefer desktop.window when possible"],
+        requiredFlags: ["(not implemented)"],
+        example: "astroshot movie start --feature x --slug region  # push cropped frames for now",
+    },
+    frames: {
+        source: "frames",
+        summary: "Encode a PNG/JPEG sequence you already produce.",
+        useWhen: [
+            "Custom engines, remote desktops, game captures",
+            "Multi-process producers that write images over time",
+            "Synthetic / test patterns",
+        ],
+        neverWhen: [
+            "You have a first-class source above that fits — use it instead",
+        ],
+        requiredFlags: ["--feature", "--slug", "then push-frame or --demo-frames"],
+        example: "astroshot movie start --feature x --slug walk && astroshot movie push-frame --feature x --file f.png && astroshot movie stop --feature x",
+    },
+};
+/** Short one-liner for errors when source is wrong/missing. */
+export function sourceHintForError(kind) {
+    if (kind && kind in SOURCE_CATALOG) {
+        const entry = SOURCE_CATALOG[kind];
+        return `${entry.summary}\n  example: ${entry.example}`;
+    }
+    return ("See `astroshot movie which-source` or `astroshot movie --help` for the decision table.");
+}
+export function formatSourceCatalog() {
+    const blocks = Object.values(SOURCE_CATALOG).map((entry) => {
+        const use = entry.useWhen.map((line) => `    • ${line}`).join("\n");
+        const never = entry.neverWhen.map((line) => `    • ${line}`).join("\n");
+        return [
+            `--source ${entry.source}`,
+            `  ${entry.summary}`,
+            `  Use when:`,
+            use,
+            `  Never when:`,
+            never,
+            `  Required: ${entry.requiredFlags.join(", ")}`,
+            `  Example: ${entry.example}`,
+        ].join("\n");
+    });
+    return `${SOURCE_DECISION_TABLE}\n\nSource catalog\n--------------\n\n${blocks.join("\n\n")}\n`;
+}
+/**
+ * Lightweight advisor for agents: pass free-text intent, get a recommended source.
+ * This is heuristic — the decision table is authoritative.
+ *
+ * Order matters: TUI beats native (don't desktop Terminal.app); native/menu-bar
+ * beats browser so "record the Astroshots tray" never defaults to Chromium.
+ */
+export function recommendSource(intent) {
+    const text = intent.toLowerCase();
+    if (/\b(tui|pty|terminal|ink|ratatui|curses|bubbletea|cli app|truecolor|ansi)\b/.test(text)) {
+        return {
+            source: "pty",
+            reason: "Terminal/TUI intent detected — use pty for truecolor SGR fidelity (not desktop of a terminal app).",
+        };
+    }
+    if (/\b(swiftui|appkit|electron|native app|macos app|mac app|native mac|menu[- ]?bar|menubar|status[- ]?item|lsuielement|popover|desktop window|bundle[- ]?id|window id|window[- ]?id)\b/.test(text) ||
+        // "tray" alone is ambiguous (web trays exist); with an app name / menu-bar
+        // product context, treat as native desktop capture.
+        /\b(tray|menu bar tray)\b/.test(text) ||
+        /\bastroshots?\b/.test(text) ||
+        (/\bnative\b/.test(text) &&
+            /\b(window|app|desktop|macos|mac|chrome|ui)\b/.test(text))) {
+        return {
+            source: "desktop.window",
+            reason: "Native desktop window intent detected — use desktop.window with --bundle-id or --window-id.",
+        };
+    }
+    if (/\b(browser|web|spa|playwright|agent-browser|http|react page|url)\b/.test(text)) {
+        return {
+            source: "browser",
+            reason: "Web/browser intent detected — use browser (headless Chromium), not a desktop capture of Chrome.",
+        };
+    }
+    if (/\b(frame|png|jpeg|sequence|custom|unity|remote)\b/.test(text)) {
+        return {
+            source: "frames",
+            reason: "Custom frame producer intent — use frames and push-frame.",
+        };
+    }
+    return {
+        source: "browser",
+        reason: "No strong signal; defaulting to browser for web-shaped work. Run `astroshot movie which-source` and match the decision table.",
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { BrowserMovieOptions, MovieArtifact, MovieSessionOptions } from "../types.js";
+export type BrowserMovieSessionOptions = Omit<MovieSessionOptions, "source"> & BrowserMovieOptions;
+/**
+ * Record a headless (or headed) browser journey with Playwright recordVideo.
+ * Optional `scriptPath` should export `default async function(page)`.
+ */
+export declare function recordBrowserMovie(options: BrowserMovieSessionOptions): Promise<MovieArtifact>;

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

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { chromium } from "playwright";
+import { MovieSession } from "../session.js";
+/**
+ * Record a headless (or headed) browser journey with Playwright recordVideo.
+ * Optional `scriptPath` should export `default async function(page)`.
+ */
+export async function recordBrowserMovie(options) {
+    const size = options.size ?? { width: 1280, height: 720 };
+    const session = MovieSession.create({
+        ...options,
+        size,
+        source: "browser",
+    });
+    const videoDir = fs.mkdtempSync(path.join(os.tmpdir(), "astroshot-bw-"));
+    let browser;
+    try {
+        browser = await chromium.launch({ headless: !options.headed });
+        const context = await browser.newContext({
+            viewport: size,
+            deviceScaleFactor: 1,
+            recordVideo: {
+                dir: videoDir,
+                size,
+            },
+        });
+        const page = await context.newPage();
+        if (options.url) {
+            await page.goto(options.url, {
+                waitUntil: "domcontentloaded",
+                timeout: 60_000,
+            });
+        }
+        if (options.scriptPath) {
+            await runScript(options.scriptPath, page);
+        }
+        else if (!options.url) {
+            // Default demo surface so a bare call still produces a movie.
+            await page.setContent(`<!doctype html>
+        <html><body style="margin:0;display:grid;place-items:center;height:100vh;background:#090a12;color:#b9a8ff;font:28px ui-monospace,monospace">
+          <div>astroshot-movie browser</div>
+        </body></html>`, { waitUntil: "load" });
+            await page.waitForTimeout(400);
+        }
+        if (options.settleMs && options.settleMs > 0) {
+            await page.waitForTimeout(options.settleMs);
+        }
+        const posterPath = path.join(videoDir, "poster.png");
+        await page.screenshot({ path: posterPath, type: "png" });
+        // Keep a frame so stop() has a poster fallback even if video path is set.
+        session.pushFrame(fs.readFileSync(posterPath));
+        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 browser video");
+        }
+        videos.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+        return await session.stop({
+            videoPath: videos[0],
+            posterPath,
+            durationMs: session.elapsedMs(),
+            status: options.status ?? "running",
+        });
+    }
+    finally {
+        await browser?.close().catch(() => undefined);
+        fs.rmSync(videoDir, { recursive: true, force: true });
+    }
+}
+async function runScript(scriptPath, page) {
+    const absolute = path.resolve(scriptPath);
+    if (!fs.existsSync(absolute)) {
+        throw new Error(`browser script not found: ${absolute}`);
+    }
+    const mod = (await import(pathToFileURL(absolute).href));
+    const runner = mod.default ?? mod.run;
+    if (typeof runner !== "function") {
+        throw new Error(`browser script must export default or run async function(page): ${absolute}`);
+    }
+    await runner(page);
+}

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

@@ -0,0 +1,110 @@
+import type { MovieArtifact, MovieSessionOptions } from "../types.js";
+export interface DesktopWindowInfo {
+    id: number;
+    pid: number;
+    owner: string;
+    title: string;
+    bundleId: string | null;
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    onScreen: boolean;
+    /** CGWindow layer; 0 = normal, >0 = floating/popover chrome. */
+    layer?: number;
+}
+export interface DesktopWindowMatch {
+    windowId?: number;
+    bundleId?: string;
+    titleRegex?: string;
+    owner?: string;
+    pid?: number;
+    /** When multiple match, pick largest (default) or first. */
+    pick?: "largest" | "first";
+    /**
+     * Prefer on-screen windows when several match (default true).
+     * Off-screen / empty host windows often produce black frames.
+     */
+    preferOnScreen?: boolean;
+}
+export type DesktopWindowMovieOptions = Omit<MovieSessionOptions, "source"> & {
+    match: DesktopWindowMatch;
+    /** How long to sample. Default 3000. */
+    durationMs?: number;
+    /** Include cursor in frames (screencapture -C). Default false. */
+    cursor?: boolean;
+    /**
+     * Allow mostly-blank / black posters to encode (default false).
+     * Off-screen windows and denied Screen Recording often produce black frames.
+     */
+    allowBlank?: boolean;
+};
+export interface ScreenAccessReport {
+    granted: boolean;
+    requested: boolean;
+    hostApp: string;
+    hostBundleId: string | null;
+    settingsHint: string;
+    /** Best-effort name of the app the user should enable (terminal/IDE). */
+    enableApp: string;
+}
+/**
+ * Open System Settings to the Screen Recording privacy list.
+ * Best-effort: URL schemes differ slightly across macOS versions.
+ */
+export declare function openScreenRecordingSettings(): boolean;
+/**
+ * Name the app the human should toggle in Screen Recording settings.
+ * Prefer $TERM_PROGRAM (Ghostty, iTerm, vscode…) over the Swift runner process.
+ */
+export declare function resolveEnableAppName(swiftHostApp?: string): string;
+/**
+ * Detect Screen Recording TCC (best-effort).
+ *
+ * Uses CoreGraphics preflight via Swift. Note: the Swift process identity may
+ * differ from `screencapture`'s responsible app (your terminal). Capture
+ * failure remains authoritative; this steers the human to Settings early.
+ */
+export declare function checkScreenRecordingAccess(options?: {
+    /** Call CGRequestScreenCaptureAccess when not already granted. */
+    request?: boolean;
+}): ScreenAccessReport;
+export declare function formatScreenRecordingDeniedHelp(report?: ScreenAccessReport): string;
+/**
+ * Preflight Screen Recording; optionally request + open Settings on deny.
+ * Call before desktop.window capture.
+ */
+export declare function ensureScreenRecordingAccess(options?: {
+    request?: boolean;
+    /** Open System Settings when denied (default true). */
+    openSettings?: boolean;
+}): ScreenAccessReport;
+/** List layer-0 windows as JSON via shipped Swift tool (interpreted by `swift`). */
+export declare function listDesktopWindows(): DesktopWindowInfo[];
+export declare function matchDesktopWindow(windows: DesktopWindowInfo[], match: DesktopWindowMatch): DesktopWindowInfo;
+/** Human-readable manifest description for a captured window. */
+export declare function describeDesktopWindow(target: DesktopWindowInfo): string;
+/**
+ * True when a PNG is almost entirely very dark (typical failed/off-screen capture).
+ * Samples up to ~4k pixels across a simple grid; supports 8-bit RGB/RGBA.
+ */
+export declare function isNearlyBlankPng(filePath: string, options?: {
+    maxMeanLuma?: number;
+    minDarkFraction?: number;
+}): boolean;
+/**
+ * Sample a macOS window at `fps` for `durationMs`, encode to movie + poster.
+ * Uses OS `screencapture` (already on every Mac) — no separate download.
+ */
+export declare function recordDesktopWindowMovie(options: DesktopWindowMovieOptions): Promise<MovieArtifact>;
+/** Resolve match flags from CLI-style strings. */
+export declare function desktopMatchFromFlags(flags: {
+    "window-id"?: string;
+    "bundle-id"?: string;
+    "title-regex"?: string;
+    owner?: string;
+    pid?: string;
+    pick?: string;
+}): DesktopWindowMatch;
+/** Ensure Swift is runnable (for clearer errors at CLI start). */
+export declare function assertDesktopToolchain(): void;