astroshot 0.2.1

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

@@ -0,0 +1,505 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import zlib from "node:zlib";
+import { MovieSession } from "../session.js";
+const SCREENCAPTURE = "/usr/sbin/screencapture";
+/** Known deep-links to the Screen Recording privacy pane (varies by macOS). */
+const SCREEN_RECORDING_SETTINGS_URLS = [
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",
+    "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_ScreenCapture",
+];
+function packageNativeSwift() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // dist/sources -> ../../native/macos
+    return path.resolve(here, "../../native/macos/WindowTools.swift");
+}
+function assertMacOS() {
+    if (process.platform !== "darwin") {
+        throw new Error("desktop.window is only implemented on macOS (CGWindowList + screencapture). " +
+            "On other platforms use --source frames and push your own captures. " +
+            "See: astroshot movie which-source");
+    }
+}
+function assertScreencapture() {
+    if (!fs.existsSync(SCREENCAPTURE)) {
+        throw new Error(`screencapture not found at ${SCREENCAPTURE}`);
+    }
+}
+function runWindowTools(args) {
+    const script = packageNativeSwift();
+    if (!fs.existsSync(script)) {
+        throw new Error(`WindowTools.swift missing at ${script}. Reinstall @archastro/movie-harness.`);
+    }
+    const result = spawnSync("swift", [script, ...args], {
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    if (result.error) {
+        throw new Error(`Could not run Swift window tools (${result.error.message}). ` +
+            "Install Xcode Command Line Tools (`xcode-select --install`).");
+    }
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+/**
+ * Open System Settings to the Screen Recording privacy list.
+ * Best-effort: URL schemes differ slightly across macOS versions.
+ */
+export function openScreenRecordingSettings() {
+    assertMacOS();
+    for (const url of SCREEN_RECORDING_SETTINGS_URLS) {
+        const result = spawnSync("open", [url], { encoding: "utf8" });
+        if (result.status === 0)
+            return true;
+    }
+    // Fallback: open the Privacy & Security root.
+    const fallback = spawnSync("open", ["x-apple.systempreferences:com.apple.preference.security"], { encoding: "utf8" });
+    return fallback.status === 0;
+}
+/**
+ * Name the app the human should toggle in Screen Recording settings.
+ * Prefer $TERM_PROGRAM (Ghostty, iTerm, vscode…) over the Swift runner process.
+ */
+export function resolveEnableAppName(swiftHostApp) {
+    const term = process.env.TERM_PROGRAM?.trim();
+    if (term) {
+        const map = {
+            ghostty: "Ghostty",
+            "iTerm.app": "iTerm",
+            Apple_Terminal: "Terminal",
+            vscode: "Code", // VS Code / Cursor often still set vscode
+            WarpTerminal: "Warp",
+            WezTerm: "WezTerm",
+            Alacritty: "Alacritty",
+        };
+        return map[term] ?? term;
+    }
+    if (process.env.CURSOR_TRACE_ID || process.env.VSCODE_PID) {
+        return process.env.CURSOR_TRACE_ID ? "Cursor" : "Code";
+    }
+    if (swiftHostApp && !/swift/i.test(swiftHostApp))
+        return swiftHostApp;
+    return "your terminal or IDE (the app that launched this command)";
+}
+/**
+ * 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 function checkScreenRecordingAccess(options) {
+    assertMacOS();
+    const args = ["screen-access"];
+    if (options?.request)
+        args.push("--request");
+    const result = runWindowTools(args);
+    const text = result.stdout.trim();
+    if (!text) {
+        throw new Error(`screen-access returned no JSON (status ${result.status}): ${result.stderr.slice(0, 400)}`);
+    }
+    const parsed = JSON.parse(text);
+    const enableApp = resolveEnableAppName(parsed.hostApp);
+    return {
+        granted: Boolean(parsed.granted),
+        requested: Boolean(parsed.requested),
+        hostApp: parsed.hostApp || "unknown",
+        hostBundleId: parsed.hostBundleId ?? null,
+        enableApp,
+        settingsHint: `System Settings → Privacy & Security → Screen Recording → enable ${enableApp}, then quit & reopen it`,
+    };
+}
+export function formatScreenRecordingDeniedHelp(report) {
+    const app = report?.enableApp ?? resolveEnableAppName();
+    const lines = [
+        `Screen Recording permission is required for --source desktop.window.`,
+        ``,
+        `Fix:`,
+        `  1. Open System Settings → Privacy & Security → Screen Recording`,
+        `     (or: astroshot movie open-screen-settings)`,
+        `  2. Enable "${app}"`,
+        `  3. Quit and reopen ${app} completely (TCC applies on next launch)`,
+        `  4. Re-run: astroshot movie check-screen-access`,
+        ``,
+        `Note: macOS may not always show an automatic prompt; the Settings toggle is the reliable path.`,
+        `browser / pty sources do not need this permission.`,
+    ];
+    return lines.join("\n");
+}
+function throwScreenRecordingDenied(report) {
+    // Best-effort: open Settings so the human does not have to hunt.
+    try {
+        openScreenRecordingSettings();
+    }
+    catch {
+        /* ignore */
+    }
+    throw new Error(formatScreenRecordingDeniedHelp(report));
+}
+/**
+ * Preflight Screen Recording; optionally request + open Settings on deny.
+ * Call before desktop.window capture.
+ */
+export function ensureScreenRecordingAccess(options) {
+    const report = checkScreenRecordingAccess({
+        request: options?.request ?? true,
+    });
+    if (report.granted)
+        return report;
+    if (options?.openSettings !== false) {
+        try {
+            openScreenRecordingSettings();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    throw new Error(formatScreenRecordingDeniedHelp(report));
+}
+/** List layer-0 windows as JSON via shipped Swift tool (interpreted by `swift`). */
+export function listDesktopWindows() {
+    assertMacOS();
+    const result = runWindowTools(["list"]);
+    if (result.status !== 0) {
+        throw new Error(`Window list failed (${result.status}): ${result.stderr.slice(0, 500)}`);
+    }
+    const text = result.stdout.trim();
+    if (!text)
+        return [];
+    const parsed = JSON.parse(text);
+    return parsed.map((row) => ({
+        ...row,
+        bundleId: row.bundleId ?? null,
+    }));
+}
+export function matchDesktopWindow(windows, match) {
+    let candidates = windows;
+    if (match.windowId !== undefined) {
+        candidates = candidates.filter((w) => w.id === match.windowId);
+    }
+    if (match.bundleId) {
+        const want = match.bundleId.toLowerCase();
+        candidates = candidates.filter((w) => (w.bundleId ?? "").toLowerCase() === want);
+    }
+    if (match.owner) {
+        const want = match.owner.toLowerCase();
+        candidates = candidates.filter((w) => w.owner.toLowerCase().includes(want));
+    }
+    if (match.pid !== undefined) {
+        candidates = candidates.filter((w) => w.pid === match.pid);
+    }
+    if (match.titleRegex) {
+        const re = new RegExp(match.titleRegex, "i");
+        candidates = candidates.filter((w) => re.test(w.title));
+    }
+    if (candidates.length === 0) {
+        const sample = windows
+            .slice(0, 8)
+            .map((w) => `  id=${w.id} pid=${w.pid} layer=${w.layer ?? "?"} bundle=${w.bundleId ?? "?"} owner=${JSON.stringify(w.owner)} title=${JSON.stringify(w.title)} ${w.width}x${w.height} onScreen=${w.onScreen}`)
+            .join("\n");
+        throw new Error(`No desktop window matched ${JSON.stringify(match)}.\n` +
+            `Run: astroshot movie list-windows\n` +
+            `Sample windows:\n${sample || "  (none)"}`);
+    }
+    const preferOnScreen = match.preferOnScreen !== false;
+    if (preferOnScreen && match.windowId === undefined) {
+        const onScreen = candidates.filter((w) => w.onScreen);
+        if (onScreen.length > 0)
+            candidates = onScreen;
+    }
+    if (match.pick === "first")
+        return candidates[0];
+    // Default: largest area, then lower layer (normal windows over floaters).
+    return [...candidates].sort((a, b) => {
+        const area = b.width * b.height - a.width * a.height;
+        if (area !== 0)
+            return area;
+        return (a.layer ?? 0) - (b.layer ?? 0);
+    })[0];
+}
+/** Human-readable manifest description for a captured window. */
+export function describeDesktopWindow(target) {
+    const name = target.bundleId?.split(".").pop() || target.owner || "window";
+    const title = target.title.trim();
+    const size = `${target.width}×${target.height}`;
+    const where = target.onScreen ? "on-screen" : "off-screen";
+    const layer = target.layer !== undefined && target.layer > 0
+        ? `, layer ${target.layer}`
+        : "";
+    if (title) {
+        return `${name}: “${title}” (${size}, ${where}${layer})`;
+    }
+    return `${name} window (${size}, ${where}${layer})`;
+}
+/**
+ * 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 function isNearlyBlankPng(filePath, options) {
+    const maxMeanLuma = options?.maxMeanLuma ?? 12;
+    const minDarkFraction = options?.minDarkFraction ?? 0.97;
+    let data;
+    try {
+        data = fs.readFileSync(filePath);
+    }
+    catch {
+        return true;
+    }
+    if (data.length < 33 || data.toString("ascii", 1, 4) !== "PNG")
+        return true;
+    // Minimal PNG scan: find IDAT chunks, inflate, average luma on a grid.
+    const width = data.readUInt32BE(16);
+    const height = data.readUInt32BE(20);
+    const bitDepth = data[24];
+    const colorType = data[25];
+    if (!width || !height || bitDepth !== 8)
+        return false;
+    // 2 = RGB, 6 = RGBA
+    if (colorType !== 2 && colorType !== 6)
+        return false;
+    const channels = colorType === 6 ? 4 : 3;
+    const idatParts = [];
+    let offset = 8;
+    while (offset + 8 <= data.length) {
+        const len = data.readUInt32BE(offset);
+        const type = data.toString("ascii", offset + 4, offset + 8);
+        const start = offset + 8;
+        const end = start + len;
+        if (end + 4 > data.length)
+            break;
+        if (type === "IDAT")
+            idatParts.push(data.subarray(start, end));
+        if (type === "IEND")
+            break;
+        offset = end + 4;
+    }
+    if (idatParts.length === 0)
+        return true;
+    let inflated;
+    try {
+        inflated = zlib.inflateSync(Buffer.concat(idatParts));
+    }
+    catch {
+        return false; // can't decode — don't claim blank
+    }
+    const stride = 1 + width * channels; // filter byte + row
+    const expected = stride * height;
+    if (inflated.length < expected)
+        return false;
+    // Only sample rows that use filter type 0 (None) for correct RGB bytes.
+    // For filtered rows, still sample raw bytes as a coarse darkness heuristic.
+    let samples = 0;
+    let dark = 0;
+    let lumaSum = 0;
+    const stepY = Math.max(1, Math.floor(height / 32));
+    const stepX = Math.max(1, Math.floor(width / 32));
+    for (let y = 0; y < height; y += stepY) {
+        const rowStart = y * stride;
+        const filter = inflated[rowStart] ?? 0;
+        for (let x = 0; x < width; x += stepX) {
+            const i = rowStart + 1 + x * channels;
+            const r = inflated[i] ?? 0;
+            const g = inflated[i + 1] ?? 0;
+            const b = inflated[i + 2] ?? 0;
+            // filter≠0 means bytes aren't raw RGB; still treat very low triples as dark.
+            const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+            lumaSum += luma;
+            if (luma <= maxMeanLuma)
+                dark += 1;
+            samples += 1;
+            void filter;
+        }
+    }
+    if (samples === 0)
+        return true;
+    const mean = lumaSum / samples;
+    const darkFraction = dark / samples;
+    return mean <= maxMeanLuma && darkFraction >= minDarkFraction;
+}
+function captureWindowPng(windowId, outPath, cursor) {
+    const finalArgs = cursor
+        ? ["-x", "-C", "-o", "-t", "png", "-l", String(windowId), outPath]
+        : ["-x", "-o", "-t", "png", "-l", String(windowId), outPath];
+    const result = spawnSync(SCREENCAPTURE, finalArgs, { encoding: "utf8" });
+    if (result.status !== 0) {
+        let access;
+        try {
+            access = checkScreenRecordingAccess({ request: false });
+        }
+        catch {
+            /* ignore */
+        }
+        if (access && !access.granted) {
+            throwScreenRecordingDenied(access);
+        }
+        throw new Error(`screencapture failed for window ${windowId} (${result.status}): ` +
+            `${result.stderr || result.stdout || "unknown error"}.\n` +
+            formatScreenRecordingDeniedHelp(access));
+    }
+    if (!fs.existsSync(outPath) || fs.statSync(outPath).size < 32) {
+        let access;
+        try {
+            access = checkScreenRecordingAccess({ request: false });
+        }
+        catch {
+            /* ignore */
+        }
+        if (access && !access.granted) {
+            throwScreenRecordingDenied(access);
+        }
+        throw new Error(`screencapture produced an empty image for window ${windowId}. ` +
+            "The window may have closed, or Screen Recording is denied.\n" +
+            formatScreenRecordingDeniedHelp(access));
+    }
+}
+function readPngSize(filePath) {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        const buf = Buffer.alloc(24);
+        fs.readSync(fd, buf, 0, 24, 0);
+        if (buf.toString("ascii", 1, 4) !== "PNG")
+            return null;
+        return {
+            width: buf.readUInt32BE(16),
+            height: buf.readUInt32BE(20),
+        };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Sample a macOS window at `fps` for `durationMs`, encode to movie + poster.
+ * Uses OS `screencapture` (already on every Mac) — no separate download.
+ */
+export async function recordDesktopWindowMovie(options) {
+    assertMacOS();
+    assertScreencapture();
+    const durationMs = options.durationMs ?? 3_000;
+    const fps = options.fps ?? 10;
+    if (!(durationMs > 0)) {
+        throw new Error("--duration-ms must be positive");
+    }
+    // Detect TCC up front (may prompt once; opens Settings if still denied).
+    ensureScreenRecordingAccess({ request: true, openSettings: true });
+    const windows = listDesktopWindows();
+    const target = matchDesktopWindow(windows, options.match);
+    if (!target.onScreen && !options.allowBlank) {
+        throw new Error(`Matched window id=${target.id} (${target.bundleId ?? target.owner}) is off-screen ` +
+            `(${target.width}×${target.height} at ${target.x},${target.y}). ` +
+            "Off-screen windows usually produce black movies. Bring the window on-screen " +
+            "(open the tray/popover) or pass --allow-blank to record anyway.\n" +
+            `Hint: ${describeDesktopWindow(target)}`);
+    }
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "astroshot-desktop-"));
+    const probe = path.join(tmp, "probe.png");
+    try {
+        captureWindowPng(target.id, probe, Boolean(options.cursor));
+    }
+    catch (error) {
+        fs.rmSync(tmp, { recursive: true, force: true });
+        throw error;
+    }
+    if (!options.allowBlank && isNearlyBlankPng(probe)) {
+        fs.rmSync(tmp, { recursive: true, force: true });
+        throw new Error(`Probe frame for window id=${target.id} is nearly blank/black. ` +
+            "Screen Recording may be denied for this host app, the window may be empty, " +
+            "or the popover may not be visible. Fix visibility/TCC, or pass --allow-blank.\n" +
+            `Window: ${describeDesktopWindow(target)}\n` +
+            "Run: astroshot movie check-screen-access");
+    }
+    const probed = readPngSize(probe);
+    const size = options.size ??
+        probed ?? {
+        width: target.width,
+        height: target.height,
+    };
+    const session = MovieSession.create({
+        ...options,
+        size,
+        fps,
+        source: "desktop.window",
+        description: options.description ?? describeDesktopWindow(target),
+    });
+    // Seed with probe frame so we never end empty if duration is tiny.
+    session.pushFrame(fs.readFileSync(probe));
+    const intervalMs = Math.max(50, Math.round(1000 / fps));
+    const deadline = Date.now() + durationMs;
+    let index = 1;
+    try {
+        while (Date.now() < deadline) {
+            const framePath = path.join(tmp, `f-${String(index).padStart(5, "0")}.png`);
+            const started = Date.now();
+            try {
+                captureWindowPng(target.id, framePath, Boolean(options.cursor));
+                session.pushFrameFile(framePath);
+            }
+            catch (error) {
+                // Window may close mid-recording; stop cleanly if we have frames.
+                if (session.listFrames().length > 0)
+                    break;
+                throw error;
+            }
+            index += 1;
+            const elapsed = Date.now() - started;
+            const sleep = Math.max(0, intervalMs - elapsed);
+            if (sleep > 0 && Date.now() + sleep < deadline) {
+                await new Promise((r) => setTimeout(r, sleep));
+            }
+        }
+        return await session.stop({ status: options.status ?? "running" });
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** Resolve match flags from CLI-style strings. */
+export function desktopMatchFromFlags(flags) {
+    const match = {};
+    if (flags["window-id"])
+        match.windowId = Number(flags["window-id"]);
+    if (flags["bundle-id"])
+        match.bundleId = flags["bundle-id"];
+    if (flags["title-regex"])
+        match.titleRegex = flags["title-regex"];
+    if (flags.owner)
+        match.owner = flags.owner;
+    if (flags.pid)
+        match.pid = Number(flags.pid);
+    if (flags.pick === "first" || flags.pick === "largest") {
+        match.pick = flags.pick;
+    }
+    if (match.windowId === undefined &&
+        !match.bundleId &&
+        !match.titleRegex &&
+        !match.owner &&
+        match.pid === undefined) {
+        throw new Error("desktop.window requires one of --window-id, --bundle-id, --title-regex, --owner, or --pid. " +
+            "Run: astroshot movie list-windows");
+    }
+    if (match.windowId !== undefined && Number.isNaN(match.windowId)) {
+        throw new Error("--window-id must be a number");
+    }
+    if (match.pid !== undefined && Number.isNaN(match.pid)) {
+        throw new Error("--pid must be a number");
+    }
+    return match;
+}
+/** Ensure Swift is runnable (for clearer errors at CLI start). */
+export function assertDesktopToolchain() {
+    assertMacOS();
+    try {
+        execFileSync("swift", ["--version"], { encoding: "utf8", stdio: "pipe" });
+    }
+    catch {
+        throw new Error("desktop.window requires the Swift toolchain (`swift` on PATH). " +
+            "Install Xcode Command Line Tools: xcode-select --install");
+    }
+    assertScreencapture();
+}

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

@@ -0,0 +1,19 @@
+import type { MovieArtifact, MovieFormat, PersistedFrameSession, Size } from "../types.js";
+/** Resolve the active frames session for a feature (latest if id omitted). */
+export declare function loadFrameSession(root: string, feature: string, id?: string): PersistedFrameSession;
+export declare function startFrameSession(options: {
+    feature: string;
+    slug: string;
+    root?: string;
+    runId?: string;
+    title?: string;
+    description?: string;
+    size?: Size;
+    fps?: number;
+    format?: MovieFormat;
+}): PersistedFrameSession;
+export declare function pushFrameToSession(state: PersistedFrameSession, imagePath: string): PersistedFrameSession;
+export declare function markFrameSession(state: PersistedFrameSession, slug: string, note?: string): PersistedFrameSession;
+export declare function stopFrameSession(state: PersistedFrameSession, options?: {
+    status?: "running" | "pass" | "fail" | "idle";
+}): Promise<MovieArtifact>;

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

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { encodeFrames, posterFromFrames } from "../encode.js";
+import { assertKebabCase, assertSlug, defaultRunId, ensureDir, movieStateDir, resolveRoot, } from "../paths.js";
+import { sinkMovie } from "../sink.js";
+const STATE_FILE = "session.json";
+function sessionDir(root, feature, id) {
+    return path.join(movieStateDir(root, feature), id);
+}
+function statePath(dir) {
+    return path.join(dir, STATE_FILE);
+}
+function writeState(state) {
+    const dir = sessionDir(state.root, state.feature, state.id);
+    ensureDir(dir);
+    ensureDir(state.frameDir);
+    const tmp = `${statePath(dir)}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+    fs.renameSync(tmp, statePath(dir));
+}
+function readState(dir) {
+    const raw = JSON.parse(fs.readFileSync(statePath(dir), "utf8"));
+    if (raw.version !== 1) {
+        throw new Error(`unsupported movie session version: ${raw.version}`);
+    }
+    return raw;
+}
+/** Resolve the active frames session for a feature (latest if id omitted). */
+export function loadFrameSession(root, feature, id) {
+    const resolvedRoot = resolveRoot(root);
+    assertKebabCase(feature, "feature");
+    const base = movieStateDir(resolvedRoot, feature);
+    if (!fs.existsSync(base)) {
+        throw new Error(`no movie session for feature ${feature}`);
+    }
+    if (id) {
+        const dir = sessionDir(resolvedRoot, feature, id);
+        if (!fs.existsSync(statePath(dir))) {
+            throw new Error(`movie session not found: ${id}`);
+        }
+        return readState(dir);
+    }
+    const ids = fs
+        .readdirSync(base)
+        .filter((name) => fs.existsSync(statePath(path.join(base, name))))
+        .sort();
+    if (ids.length === 0) {
+        throw new Error(`no movie session for feature ${feature}`);
+    }
+    return readState(path.join(base, ids.at(-1)));
+}
+export function startFrameSession(options) {
+    assertKebabCase(options.feature, "feature");
+    assertSlug(options.slug);
+    const root = resolveRoot(options.root);
+    const id = randomBytes(6).toString("hex");
+    const dir = sessionDir(root, options.feature, id);
+    const frameDir = path.join(dir, "frames");
+    ensureDir(frameDir);
+    const state = {
+        version: 1,
+        id,
+        feature: options.feature,
+        slug: options.slug,
+        root,
+        runId: options.runId ?? defaultRunId(options.feature),
+        title: options.title,
+        description: options.description,
+        size: options.size ?? { width: 1280, height: 720 },
+        fps: options.fps ?? 15,
+        format: options.format ?? "webm",
+        source: "frames",
+        startedAtMs: Date.now(),
+        frameDir,
+        frameCount: 0,
+        chapters: [],
+    };
+    writeState(state);
+    return state;
+}
+export function pushFrameToSession(state, imagePath) {
+    if (!fs.existsSync(imagePath)) {
+        throw new Error(`frame not found: ${imagePath}`);
+    }
+    const ext = path.extname(imagePath).toLowerCase().replace(".", "") || "png";
+    if (ext !== "png" && ext !== "jpg" && ext !== "jpeg") {
+        throw new Error(`unsupported frame extension .${ext}`);
+    }
+    const index = String(state.frameCount).padStart(6, "0");
+    const dest = path.join(state.frameDir, `${index}.${ext}`);
+    fs.copyFileSync(imagePath, dest);
+    const next = {
+        ...state,
+        frameCount: state.frameCount + 1,
+    };
+    writeState(next);
+    return next;
+}
+export function markFrameSession(state, slug, note) {
+    assertSlug(slug);
+    const chapter = {
+        slug,
+        tMs: Date.now() - state.startedAtMs,
+        note,
+    };
+    const next = {
+        ...state,
+        chapters: [...state.chapters, chapter],
+    };
+    writeState(next);
+    return next;
+}
+export async function stopFrameSession(state, options) {
+    const frames = fs
+        .readdirSync(state.frameDir)
+        .filter((name) => /\.(png|jpe?g)$/i.test(name))
+        .sort()
+        .map((name) => path.join(state.frameDir, name));
+    if (frames.length === 0) {
+        throw new Error("cannot stop movie session with zero frames");
+    }
+    const work = path.join(sessionDir(state.root, state.feature, state.id), "out");
+    ensureDir(work);
+    const outExt = state.format === "mp4" ? ".mp4" : ".webm";
+    const encoded = await encodeFrames({
+        framePaths: frames,
+        outPath: path.join(work, `movie${outExt}`),
+        size: state.size,
+        fps: state.fps,
+    });
+    const posterPath = posterFromFrames(frames, path.join(work, "poster.png"));
+    const durationMs = encoded.durationMs;
+    const published = sinkMovie({
+        root: state.root,
+        feature: state.feature,
+        slug: state.slug,
+        runId: state.runId,
+        title: state.title,
+        description: state.description,
+        status: options?.status ?? "running",
+        source: "frames",
+        posterPath,
+        videoPath: encoded.videoPath,
+        durationMs,
+        chapters: state.chapters,
+        size: state.size,
+    });
+    // Drop session state; artifacts live in .astroshot/.
+    fs.rmSync(sessionDir(state.root, state.feature, state.id), {
+        recursive: true,
+        force: true,
+    });
+    return {
+        videoPath: published.videoDest,
+        posterPath: published.posterDest,
+        durationMs,
+        chapters: state.chapters,
+        source: "frames",
+        feature: state.feature,
+        slug: state.slug,
+        sequence: published.sequence,
+        runId: state.runId,
+    };
+}