@openvidstudio/capture 0.0.0-stage → 1.3.1

package/dist/layers.d.ts

@@ -0,0 +1,44 @@
+import type { Page } from "playwright";
+/**
+ * Page-side helpers for splitting a capture into layers: a background with chosen elements
+ * gone, and one transparent image per element.
+ *
+ * Elements are isolated with `visibility`, never `display`, so nothing moves: every other box
+ * keeps its layout, and each element stays exactly where it was in the full screenshot. CSS
+ * visibility lets a child re-show itself inside a hidden parent, which is what makes "hide
+ * everything except this subtree" work without touching the subtree's own look. The shots
+ * themselves are ordinary full-viewport screenshots cropped afterwards, not Playwright's
+ * element-scoped ones, which CAPTURE.md explains re-measure and auto-scroll at shot time.
+ */
+/** One element a layer selector matched, in viewport CSS pixels, with the id used to find it again. */
+export interface LayerElement {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Tags every element a selector matches with a stable id and measures it. `group` keeps ids from
+ * different selectors apart. Throws a clear error naming the selector when it is not valid CSS;
+ * an empty result is the caller's to report, since only it knows what the layer was for.
+ */
+export declare function tagLayerElements(page: Page, selector: string, group: number): Promise<LayerElement[]>;
+/**
+ * Freezes every CSS and Web Animations animation where it stands, so the background, the layers
+ * and the full screenshot are all the same instant of a page that never stops moving.
+ */
+export declare function pauseAnimations(page: Page): Promise<void>;
+/**
+ * Leaves only one tagged element (and its subtree) visible, on a transparent page, ready for a
+ * screenshot with omitBackground. Everything else keeps its box, so the element does not move.
+ */
+export declare function showOnlyLayer(page: Page, id: string): Promise<void>;
+/** Hides every tagged element, leaving the page as it is otherwise: the background layer. */
+export declare function hideAllLayers(page: Page): Promise<void>;
+/**
+ * Undoes showOnlyLayer and hideAllLayers, so the page is as it was between shots. Transitions
+ * stay off (the isolate attribute is kept, with the page background back), because turning
+ * them on in the same step as un-hiding would start a fade-in on every element just restored.
+ */
+export declare function restoreLayers(page: Page): Promise<void>;

package/dist/layers.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagLayerElements = tagLayerElements;
+exports.pauseAnimations = pauseAnimations;
+exports.showOnlyLayer = showOnlyLayer;
+exports.hideAllLayers = hideAllLayers;
+exports.restoreLayers = restoreLayers;
+const LAYER_ATTR = "data-ovs-layer";
+const HIDE_ATTR = "data-ovs-hide";
+const SHOW_ATTR = "data-ovs-show";
+const ISOLATE_ATTR = "data-ovs-isolate";
+const STYLE_ID = "__ovs-layers-style";
+/**
+ * Tags every element a selector matches with a stable id and measures it. `group` keeps ids from
+ * different selectors apart. Throws a clear error naming the selector when it is not valid CSS;
+ * an empty result is the caller's to report, since only it knows what the layer was for.
+ */
+async function tagLayerElements(page, selector, group) {
+    try {
+        return await page.evaluate(({ selector: sel, group: g, attr }) => {
+            const found = Array.from(document.querySelectorAll(sel));
+            return found.map((el, i) => {
+                const id = `${g}-${i}`;
+                el.setAttribute(attr, id);
+                const r = el.getBoundingClientRect();
+                return { id, x: r.x, y: r.y, width: r.width, height: r.height };
+            });
+        }, { selector, group, attr: LAYER_ATTR });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`layers: selector "${selector}" could not be queried (${message.split("\n")[0]})`);
+    }
+}
+/**
+ * Freezes every CSS and Web Animations animation where it stands, so the background, the layers
+ * and the full screenshot are all the same instant of a page that never stops moving.
+ */
+async function pauseAnimations(page) {
+    await page.evaluate(() => {
+        for (const animation of document.getAnimations()) {
+            try {
+                animation.pause();
+            }
+            catch {
+                // An animation that cannot be paused is left running; the shots then differ in its region only.
+            }
+        }
+    });
+}
+async function installStyle(page) {
+    await page.evaluate(({ id, hide, show, isolate }) => {
+        if (document.getElementById(id))
+            return;
+        const style = document.createElement("style");
+        style.id = id;
+        // transition: none is what makes the toggles instant. A page with `transition: all` would
+        // otherwise keep a hidden element visible for the length of its transition, and the shot
+        // taken a frame later would still contain it.
+        style.textContent =
+            `html[${isolate}] *, html[${isolate}] *::before, html[${isolate}] *::after { transition: none !important; }` +
+                `[${hide}] { visibility: hidden !important; }` +
+                `[${show}] { visibility: visible !important; }` +
+                `html[${isolate}="clear"], html[${isolate}="clear"] body { background: transparent !important; background-image: none !important; }`;
+        document.head.appendChild(style);
+    }, { id: STYLE_ID, hide: HIDE_ATTR, show: SHOW_ATTR, isolate: ISOLATE_ATTR });
+}
+async function settleFrames(page) {
+    await page.evaluate(() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+}
+/**
+ * Leaves only one tagged element (and its subtree) visible, on a transparent page, ready for a
+ * screenshot with omitBackground. Everything else keeps its box, so the element does not move.
+ */
+async function showOnlyLayer(page, id) {
+    await installStyle(page);
+    await page.evaluate(({ id: target, layerAttr, hide, show, isolate }) => {
+        const active = document.querySelector(`[${layerAttr}="${target}"]`);
+        if (!active)
+            throw new Error(`layers: tagged element ${target} is gone from the page`);
+        for (const el of Array.from(document.querySelectorAll("*"))) {
+            if (el === active || active.contains(el))
+                continue;
+            el.setAttribute(hide, "");
+        }
+        active.setAttribute(show, "");
+        document.documentElement.setAttribute(isolate, "clear");
+    }, { id, layerAttr: LAYER_ATTR, hide: HIDE_ATTR, show: SHOW_ATTR, isolate: ISOLATE_ATTR });
+    await settleFrames(page);
+}
+/** Hides every tagged element, leaving the page as it is otherwise: the background layer. */
+async function hideAllLayers(page) {
+    await installStyle(page);
+    await page.evaluate(({ layerAttr, hide, isolate }) => {
+        document.documentElement.setAttribute(isolate, "keep");
+        for (const el of Array.from(document.querySelectorAll(`[${layerAttr}]`)))
+            el.setAttribute(hide, "");
+    }, { layerAttr: LAYER_ATTR, hide: HIDE_ATTR, isolate: ISOLATE_ATTR });
+    await settleFrames(page);
+}
+/**
+ * Undoes showOnlyLayer and hideAllLayers, so the page is as it was between shots. Transitions
+ * stay off (the isolate attribute is kept, with the page background back), because turning
+ * them on in the same step as un-hiding would start a fade-in on every element just restored.
+ */
+async function restoreLayers(page) {
+    await page.evaluate(({ hide, show, isolate }) => {
+        for (const el of Array.from(document.querySelectorAll(`[${hide}], [${show}]`))) {
+            el.removeAttribute(hide);
+            el.removeAttribute(show);
+        }
+        document.documentElement.setAttribute(isolate, "keep");
+    }, { hide: HIDE_ATTR, show: SHOW_ATTR, isolate: ISOLATE_ATTR });
+    await settleFrames(page);
+}

package/dist/native.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Capture backends that do not involve a browser.
+ *
+ * Playwright is the right tool for a web app and the wrong tool for everything else.
+ * A desktop application, a mobile app, a terminal, or an OS itself has no URL to
+ * navigate to, and until this module existed every beat about one of them degraded to
+ * `dom-demo`: a hand-drawn panel standing in for software the pipeline could not film.
+ * The Day 3 validation test made the cost concrete, producing shot plans for Omarchy
+ * (a Linux distribution) and Hermes Agent (a terminal agent) in which 100% of beats
+ * were reconstructions, against a product whose entire pitch is that nothing on screen
+ * is generated.
+ *
+ * Everything here is an argv builder plus a thin spawn wrapper. ffmpeg and adb are
+ * real executables, never shell shims, so `spawnCapture` runs them with shell:false and
+ * an argv array; no argument is ever concatenated into a command line. That is why a
+ * window title containing spaces or quotes is safe to pass through verbatim.
+ */
+import type { SpawnResult } from "./process";
+export type DesktopPlatform = "win32" | "darwin" | "linux";
+export interface Region {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type LinuxDisplayServer = "x11" | "wayland";
+/**
+ * pipewiregrab's own options. With neither `fd` nor `node`, the filter opens an
+ * xdg-desktop-portal ScreenCast session itself, which shows the desktop's consent dialog
+ * and lets the user pick the surface. That prompt is a Wayland design decision, not an
+ * ffmpeg one, and it cannot be suppressed: a Wayland capture is not headless.
+ */
+export interface PipewireOptions {
+    /** PipeWire node id, when the caller already negotiated a portal session. */
+    node?: number;
+    /** File descriptor for a remote PipeWire instance obtained from the portal. */
+    fd?: number;
+    /** Draw the pointer into the capture. Defaults to true, matching the other backends. */
+    drawMouse?: boolean;
+}
+export interface DesktopCaptureOptions {
+    /** Omit to capture the whole display. On win32 this maps to gdigrab's `title=` selector. */
+    window?: string;
+    /**
+     * Draw the pointer into the recording. Defaults to true.
+     *
+     * A desktop demo with no cursor is hard to follow: the viewer cannot tell what is being
+     * clicked, and the UI appears to react to nothing.
+     */
+    drawMouse?: boolean;
+    region?: Region;
+    /** Display index. win32 ignores this (gdigrab captures the virtual desktop). */
+    display?: number;
+    framerate: number;
+    durationSeconds: number;
+    outPath: string;
+    platform: DesktopPlatform;
+    /** Linux only. Defaults to x11, which is what x11grab needs. */
+    displayServer?: LinuxDisplayServer;
+    pipewire?: PipewireOptions;
+}
+/**
+ * Which display server this Linux session is actually running.
+ *
+ * Wayland is the default on current Fedora, Ubuntu, and most GNOME and KDE installs, so
+ * x11grab is now the minority case rather than the safe default. XDG_SESSION_TYPE is the
+ * documented signal; WAYLAND_DISPLAY is the fallback because some session managers and
+ * most containers leave XDG_SESSION_TYPE unset.
+ */
+export declare function detectLinuxDisplayServer(env?: NodeJS.ProcessEnv): LinuxDisplayServer;
+/** `ffmpeg -filters` output, for checking whether this build has pipewiregrab (ffmpeg 7.1+). */
+export declare function buildFilterProbeArgs(): string[];
+export declare function hasFilter(ffmpegFiltersOutput: string, name: string): boolean;
+/**
+ * Wayland capture through PipeWire.
+ *
+ * pipewiregrab is a libavfilter source rather than an input device, so it arrives through
+ * `-f lavfi` and the framerate is applied downstream with `fps` instead of being requested
+ * from the device. There is no equivalent of gdigrab's `title=`: on Wayland a client
+ * cannot enumerate or address another client's windows at all, which is the point of the
+ * design. The portal's own picker chooses the surface.
+ */
+export declare function buildPipewireCaptureArgs(opts: DesktopCaptureOptions): string[];
+/**
+ * Pure argv builder for a native screen/window recording, per platform.
+ *
+ * win32   gdigrab, which can address a window by title without it being focused
+ * darwin  avfoundation, which can only grab a whole display, so a region becomes a crop
+ * linux   x11grab, which takes the region directly in its input spec, or pipewiregrab on
+ *         a Wayland session, where no client may address another client's windows
+ */
+export declare function buildDesktopCaptureArgs(opts: DesktopCaptureOptions): string[];
+/**
+ * Android capture runs on the device and writes there, because `adb exec-out` streaming
+ * is unreliable across OEM builds in a way that silently truncates recordings.
+ * `screenrecord` self-terminates at --time-limit, so nothing here needs to kill a process.
+ */
+export declare function buildAdbRecordArgs(devicePath: string, durationSeconds: number, deviceId?: string): string[];
+export declare function buildAdbPullArgs(devicePath: string, localPath: string, deviceId?: string): string[];
+export declare function buildAdbCleanupArgs(devicePath: string, deviceId?: string): string[];
+/** iOS Simulator. `simctl recordVideo` runs until interrupted, so the caller stops it on a timer. */
+export declare function buildSimctlRecordArgs(outPath: string, udid?: string): string[];
+/**
+ * screenrecord and simctl both emit mp4 already, but neither writes a faststart atom,
+ * so Remotion can decode them and cannot seek them. This is a remux, not a re-encode:
+ * no quality is lost and it takes about a second.
+ */
+export declare function buildRemuxArgs(inputPath: string, outputPath: string): string[];
+/** The screen-tuned encode, exported so every other ffmpeg path in the pipeline matches it. */
+export declare function screenEncodeArgs(): string[];
+/**
+ * Spawn that stops the child after `timeoutMs` and treats that stop as success.
+ * `simctl recordVideo` has no duration flag: it records until it receives a signal, so
+ * "ran the full duration and was then stopped" is the normal, expected path here rather
+ * than a failure.
+ */
+export declare function spawnForDuration(command: string, args: string[], cwd: string, timeoutMs: number): Promise<SpawnResult & {
+    stoppedByTimer: boolean;
+}>;
+export declare function sanitizeDeviceId(value: string): string;
+/**
+ * gdigrab parses its input as `title=<everything after the equals sign>`, so a title
+ * containing a newline or a NUL truncates the selector and silently captures the wrong
+ * thing. Spaces and quotes are fine: shell:false means the argv entry is passed intact.
+ */
+export declare function sanitizeWindowTitle(value: string): string;

package/dist/native.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * Capture backends that do not involve a browser.
+ *
+ * Playwright is the right tool for a web app and the wrong tool for everything else.
+ * A desktop application, a mobile app, a terminal, or an OS itself has no URL to
+ * navigate to, and until this module existed every beat about one of them degraded to
+ * `dom-demo`: a hand-drawn panel standing in for software the pipeline could not film.
+ * The Day 3 validation test made the cost concrete, producing shot plans for Omarchy
+ * (a Linux distribution) and Hermes Agent (a terminal agent) in which 100% of beats
+ * were reconstructions, against a product whose entire pitch is that nothing on screen
+ * is generated.
+ *
+ * Everything here is an argv builder plus a thin spawn wrapper. ffmpeg and adb are
+ * real executables, never shell shims, so `spawnCapture` runs them with shell:false and
+ * an argv array; no argument is ever concatenated into a command line. That is why a
+ * window title containing spaces or quotes is safe to pass through verbatim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectLinuxDisplayServer = detectLinuxDisplayServer;
+exports.buildFilterProbeArgs = buildFilterProbeArgs;
+exports.hasFilter = hasFilter;
+exports.buildPipewireCaptureArgs = buildPipewireCaptureArgs;
+exports.buildDesktopCaptureArgs = buildDesktopCaptureArgs;
+exports.buildAdbRecordArgs = buildAdbRecordArgs;
+exports.buildAdbPullArgs = buildAdbPullArgs;
+exports.buildAdbCleanupArgs = buildAdbCleanupArgs;
+exports.buildSimctlRecordArgs = buildSimctlRecordArgs;
+exports.buildRemuxArgs = buildRemuxArgs;
+exports.screenEncodeArgs = screenEncodeArgs;
+exports.spawnForDuration = spawnForDuration;
+exports.sanitizeDeviceId = sanitizeDeviceId;
+exports.sanitizeWindowTitle = sanitizeWindowTitle;
+const node_child_process_1 = require("node:child_process");
+/**
+ * Which display server this Linux session is actually running.
+ *
+ * Wayland is the default on current Fedora, Ubuntu, and most GNOME and KDE installs, so
+ * x11grab is now the minority case rather than the safe default. XDG_SESSION_TYPE is the
+ * documented signal; WAYLAND_DISPLAY is the fallback because some session managers and
+ * most containers leave XDG_SESSION_TYPE unset.
+ */
+function detectLinuxDisplayServer(env = process.env) {
+    const declared = (env.XDG_SESSION_TYPE ?? "").toLowerCase();
+    if (declared === "wayland")
+        return "wayland";
+    if (declared === "x11")
+        return "x11";
+    return env.WAYLAND_DISPLAY ? "wayland" : "x11";
+}
+/** `ffmpeg -filters` output, for checking whether this build has pipewiregrab (ffmpeg 7.1+). */
+function buildFilterProbeArgs() {
+    return ["-hide_banner", "-filters"];
+}
+function hasFilter(ffmpegFiltersOutput, name) {
+    // ffmpeg prints one filter per line as "<flags> <name> <io> <description>".
+    const pattern = "^\\s*\\S+\\s+" + name + "\\s";
+    return new RegExp(pattern, "m").test(ffmpegFiltersOutput);
+}
+/**
+ * Wayland capture through PipeWire.
+ *
+ * pipewiregrab is a libavfilter source rather than an input device, so it arrives through
+ * `-f lavfi` and the framerate is applied downstream with `fps` instead of being requested
+ * from the device. There is no equivalent of gdigrab's `title=`: on Wayland a client
+ * cannot enumerate or address another client's windows at all, which is the point of the
+ * design. The portal's own picker chooses the surface.
+ */
+function buildPipewireCaptureArgs(opts) {
+    const { framerate, durationSeconds, outPath, region, pipewire } = opts;
+    const filterOpts = [`draw_mouse=${pipewire?.drawMouse === false || opts.drawMouse === false ? 0 : 1}`];
+    if (pipewire?.fd !== undefined)
+        filterOpts.push(`fd=${pipewire.fd}`);
+    if (pipewire?.node !== undefined)
+        filterOpts.push(`node=${pipewire.node}`);
+    const chain = [`fps=${framerate}`];
+    if (region)
+        chain.push(`crop=${region.width}:${region.height}:${region.x}:${region.y}`);
+    return [
+        "-nostdin",
+        "-f",
+        "lavfi",
+        "-i",
+        `pipewiregrab=${filterOpts.join(":")}`,
+        "-t",
+        String(durationSeconds),
+        ...encodeArgs(outPath, chain.join(",")),
+    ];
+}
+/**
+ * h264 in yuv420p requires even dimensions, and a hand-picked region is very often
+ * odd on one axis. Without this filter a 1365-wide capture fails at the encoder with
+ * an error that says nothing about the real cause.
+ */
+const EVEN_DIMENSIONS = "scale=trunc(iw/2)*2:trunc(ih/2)*2";
+/**
+ * Screen content is not film, and encoding it like film is why screen recordings look bad.
+ *
+ * x264's defaults (crf 23, preset medium, the film-tuned psy settings) are built for
+ * camera footage: grain, motion, no hard edges. A screen is the opposite. It is mostly
+ * static, mostly flat colour, and entirely made of hard edges and small text, which is
+ * exactly what those defaults spend their bitrate anywhere but on. The result is ringing
+ * around glyphs and mush in the flat areas.
+ *
+ * crf 18 is visually lossless for this material, `slow` buys real compression efficiency
+ * on content that is cheap to encode anyway, and `stillimage` turns down the psychovisual
+ * optimisations that assume film grain. yuv444p would be better still for text, but
+ * Remotion's decoder and most browsers want 4:2:0, so that is not on the table.
+ */
+const SCREEN_ENCODE = ["-c:v", "libx264", "-crf", "18", "-preset", "slow", "-tune", "stillimage"];
+/** Shared output encoding: matches buildFfmpegTranscodeArgs so Remotion's OffthreadVideo can seek the result. */
+function encodeArgs(outPath, extraFilter) {
+    const filter = extraFilter ? `${extraFilter},${EVEN_DIMENSIONS}` : EVEN_DIMENSIONS;
+    return ["-vf", filter, ...SCREEN_ENCODE, "-pix_fmt", "yuv420p", "-movflags", "+faststart", outPath, "-y"];
+}
+/**
+ * Pure argv builder for a native screen/window recording, per platform.
+ *
+ * win32   gdigrab, which can address a window by title without it being focused
+ * darwin  avfoundation, which can only grab a whole display, so a region becomes a crop
+ * linux   x11grab, which takes the region directly in its input spec, or pipewiregrab on
+ *         a Wayland session, where no client may address another client's windows
+ */
+function buildDesktopCaptureArgs(opts) {
+    const { platform, framerate, durationSeconds, outPath, region, window, display = 0 } = opts;
+    const args = ["-nostdin", "-f"];
+    const drawMouse = opts.drawMouse === false ? "0" : "1";
+    if (platform === "win32") {
+        // A generous input queue before the device: gdigrab drops frames at the start of a
+        // capture otherwise, which shows up as a visible stutter in the first second, which is
+        // the second a demo can least afford to lose.
+        args.push("gdigrab", "-thread_queue_size", "512", "-draw_mouse", drawMouse, "-framerate", String(framerate));
+        if (region && !window) {
+            args.push("-offset_x", String(region.x), "-offset_y", String(region.y), "-video_size", `${region.width}x${region.height}`);
+        }
+        args.push("-i", window ? `title=${window}` : "desktop");
+        args.push("-t", String(durationSeconds));
+        // A window capture plus a region means "crop within the window", which gdigrab
+        // cannot express in its input spec, so it becomes a filter instead.
+        return args.concat(encodeArgs(outPath, window && region ? `crop=${region.width}:${region.height}:${region.x}:${region.y}` : undefined));
+    }
+    if (platform === "darwin") {
+        args.push("avfoundation", "-thread_queue_size", "512", "-capture_cursor", drawMouse, "-framerate", String(framerate), "-i", `${display}:none`, "-t", String(durationSeconds));
+        return args.concat(encodeArgs(outPath, region ? `crop=${region.width}:${region.height}:${region.x}:${region.y}` : undefined));
+    }
+    if ((opts.displayServer ?? "x11") === "wayland")
+        return buildPipewireCaptureArgs(opts);
+    args.push("x11grab", "-thread_queue_size", "512", "-draw_mouse", drawMouse, "-framerate", String(framerate));
+    if (region) {
+        args.push("-video_size", `${region.width}x${region.height}`, "-i", `:${display}.0+${region.x},${region.y}`);
+    }
+    else {
+        args.push("-i", `:${display}.0`);
+    }
+    args.push("-t", String(durationSeconds));
+    return args.concat(encodeArgs(outPath));
+}
+/**
+ * Android capture runs on the device and writes there, because `adb exec-out` streaming
+ * is unreliable across OEM builds in a way that silently truncates recordings.
+ * `screenrecord` self-terminates at --time-limit, so nothing here needs to kill a process.
+ */
+function buildAdbRecordArgs(devicePath, durationSeconds, deviceId) {
+    const prefix = deviceId ? ["-s", deviceId] : [];
+    return [...prefix, "shell", "screenrecord", "--time-limit", String(durationSeconds), devicePath];
+}
+function buildAdbPullArgs(devicePath, localPath, deviceId) {
+    const prefix = deviceId ? ["-s", deviceId] : [];
+    return [...prefix, "pull", devicePath, localPath];
+}
+function buildAdbCleanupArgs(devicePath, deviceId) {
+    const prefix = deviceId ? ["-s", deviceId] : [];
+    return [...prefix, "shell", "rm", "-f", devicePath];
+}
+/** iOS Simulator. `simctl recordVideo` runs until interrupted, so the caller stops it on a timer. */
+function buildSimctlRecordArgs(outPath, udid = "booted") {
+    return ["simctl", "io", udid, "recordVideo", "--codec", "h264", "--force", outPath];
+}
+/**
+ * screenrecord and simctl both emit mp4 already, but neither writes a faststart atom,
+ * so Remotion can decode them and cannot seek them. This is a remux, not a re-encode:
+ * no quality is lost and it takes about a second.
+ */
+function buildRemuxArgs(inputPath, outputPath) {
+    return ["-nostdin", "-i", inputPath, "-c", "copy", "-movflags", "+faststart", outputPath, "-y"];
+}
+/** The screen-tuned encode, exported so every other ffmpeg path in the pipeline matches it. */
+function screenEncodeArgs() {
+    return [...SCREEN_ENCODE];
+}
+/**
+ * Spawn that stops the child after `timeoutMs` and treats that stop as success.
+ * `simctl recordVideo` has no duration flag: it records until it receives a signal, so
+ * "ran the full duration and was then stopped" is the normal, expected path here rather
+ * than a failure.
+ */
+function spawnForDuration(command, args, cwd, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(command, args, { cwd, shell: false });
+        let stdout = "";
+        let stderr = "";
+        let stoppedByTimer = false;
+        const timer = setTimeout(() => {
+            stoppedByTimer = true;
+            // SIGINT, not SIGKILL: simctl finalizes the mp4 container on interrupt, and a
+            // hard kill leaves an unplayable file.
+            child.kill("SIGINT");
+            setTimeout(() => child.kill("SIGKILL"), 5000).unref?.();
+        }, timeoutMs);
+        child.stdout?.on("data", (c) => (stdout += c.toString()));
+        child.stderr?.on("data", (c) => (stderr += c.toString()));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, stoppedByTimer });
+        });
+    });
+}
+const SAFE_DEVICE_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+function sanitizeDeviceId(value) {
+    if (!SAFE_DEVICE_ID.test(value)) {
+        throw new Error(`deviceId "${value}" is not a valid device identifier. Expected an adb serial or a simulator UDID ` +
+            `(letters, numbers, ".", "_", ":", "-").`);
+    }
+    return value;
+}
+/**
+ * gdigrab parses its input as `title=<everything after the equals sign>`, so a title
+ * containing a newline or a NUL truncates the selector and silently captures the wrong
+ * thing. Spaces and quotes are fine: shell:false means the argv entry is passed intact.
+ */
+function sanitizeWindowTitle(value) {
+    if (value.length === 0 || value.length > 256 || /[\r\n\0]/.test(value)) {
+        throw new Error(`window title is invalid: it must be 1-256 characters and contain no newlines.`);
+    }
+    return value;
+}

package/dist/process.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Child-process primitives shared by every capture backend and by the callers that
+ * post-process what a backend produced (ffmpeg remuxes, ffprobe reads, the Remotion CLI).
+ *
+ * Everything here spawns with an argv array. No caller ever builds a command line by
+ * concatenation, which is what makes a window title containing spaces safe to pass
+ * through verbatim.
+ */
+export interface SpawnResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Runs a child process to completion and captures its stdout/stderr in memory.
+ * `spawn` with an argv array, never `exec`/`execSync` with an interpolated shell string.
+ * Capturing the child's output here has nothing to do with *this* process's own stdout
+ * (which, under the MCP server, is the transport); it is returned to the caller as data.
+ */
+export declare function spawnCapture(command: string, args: string[], cwd: string): Promise<SpawnResult>;

package/dist/process.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnCapture = spawnCapture;
+const node_child_process_1 = require("node:child_process");
+// On Windows, spawning a `.cmd`/`.bat` shim (npx.cmd, the only such command any caller of
+// spawnCapture ever passes -- ffmpeg/ffprobe are real .exe) with shell:false throws a
+// synchronous EINVAL: CreateProcess cannot launch a batch file directly, and (verified
+// against this repo's actual Node runtime, Task 4's real end-to-end pipeline run) Node's
+// spawn() does not transparently shell out for it the way an older assumption believed.
+// shell:true routes exactly that one case through cmd.exe, which is also why the callers'
+// own sanitizers block shell metacharacters including `%^"` (cmd.exe's own specials)
+// everywhere a value can reach this function.
+const WINDOWS_SHIM_RE = /\.(cmd|bat)$/i;
+/**
+ * Runs a child process to completion and captures its stdout/stderr in memory.
+ * `spawn` with an argv array, never `exec`/`execSync` with an interpolated shell string.
+ * Capturing the child's output here has nothing to do with *this* process's own stdout
+ * (which, under the MCP server, is the transport); it is returned to the caller as data.
+ */
+function spawnCapture(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const shell = process.platform === "win32" && WINDOWS_SHIM_RE.test(command);
+        // Node's own shell:true + args-array combination does NOT escape/quote args for the
+        // caller (it just concatenates them into one command line before handing it to
+        // cmd.exe -- Node emits DEP0190 about exactly this), so an argument containing a space
+        // would silently word-split into two argv entries once shell:true is in effect. Every
+        // arg that reaches this function is already filtered by the caller's sanitizers, which
+        // block `"` itself, so wrapping each in double quotes here is always safe and closes
+        // that gap without touching the non-shell (ffmpeg/ffprobe) call path at all.
+        const finalArgs = shell ? args.map((a) => `"${a}"`) : args;
+        // The command gets the same treatment: a shim at C:\Program Files\... would otherwise be
+        // cut at its first space and cmd.exe would try to run "C:\Program".
+        const finalCommand = shell && /\s/.test(command) ? `"${command}"` : command;
+        const child = (0, node_child_process_1.spawn)(finalCommand, finalArgs, { cwd, shell });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code, stdout, stderr }));
+    });
+}

package/dist/settle.d.ts

@@ -0,0 +1,69 @@
+import type { Page } from "playwright";
+/**
+ * Waits for a page to finish becoming itself before anything is captured.
+ *
+ * This is the difference between a demo that looks deliberate and one that looks broken.
+ * A modern page is not finished when `load` fires: webfonts are still swapping, images are
+ * still decoding, and any entrance transition is mid-flight. Capture at that moment and you
+ * get a frame nobody ever sees in real use, with fallback type, a blank hero, and a panel
+ * frozen at 40% opacity halfway through its fade. The page was fine. The capture was early.
+ *
+ * Three waits, in the order they resolve in a real browser:
+ *
+ * 1. **Fonts.** `document.fonts.ready` resolves once every font actually used has loaded.
+ *    Skipping it is the single commonest cause of a capture rendered in Times New Roman.
+ * 2. **Images.** Decoded, not merely fetched. A fetched-but-undecoded image still paints
+ *    blank for a frame or two.
+ * 3. **Animations.** Every running animation and transition driven to its end.
+ *
+ * The third one has a trap in it: an infinite animation never finishes. A looping spinner,
+ * a pulsing dot, a permanently drifting gradient will all return a `finished` promise that
+ * never resolves, so waiting on everything indiscriminately hangs until the timeout on most
+ * real marketing pages. Those are filtered out by their computed timing, which is also the
+ * correct behaviour: a loop has no "settled" state to wait for, and the page is as ready as
+ * it will ever be while it keeps running.
+ */
+export interface SettleOptions {
+    /** Give up after this long and report what was still pending. Defaults to 5000ms. */
+    timeoutMs?: number;
+    /** Wait for webfonts. Defaults to true. */
+    fonts?: boolean;
+    /** Wait for images to decode. Defaults to true. */
+    images?: boolean;
+    /** Drive running transitions and animations to their end. Defaults to true. */
+    animations?: boolean;
+    /** A final quiet pause after everything else, for work no API reports. Defaults to 150ms. */
+    quietMs?: number;
+}
+export interface SettleReport {
+    /** False when the timeout fired with work still outstanding. */
+    settled: boolean;
+    waitedMs: number;
+    /** Animations still running when the wait ended, excluding infinite ones. */
+    pendingAnimations: number;
+    /** Infinite animations, which are never waited on and are not a problem. */
+    loopingAnimations: number;
+    fontsReady: boolean;
+    imagesReady: boolean;
+}
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 5000;
+export declare const DEFAULT_QUIET_MS = 150;
+/**
+ * Settles the page, then pauses briefly.
+ *
+ * The trailing pause is not superstition: a transition can finish one frame before the
+ * compositor has painted its final state, and `requestAnimationFrame` ordering means the
+ * screenshot can otherwise land on the frame before the last one.
+ */
+export declare function settlePage(page: Page, opts?: SettleOptions): Promise<SettleReport>;
+/** Sidecar path a SettleReport is written to, next to the capture artifact it describes. */
+export declare function settleSidecarPath(outPathAbs: string): string;
+/**
+ * Persists a SettleReport next to the artifact it describes. `settlePage`'s return value
+ * is otherwise only a field in a tool call's result, which nothing downstream keeps: a
+ * capture that timed out with animations still pending is a frame caught mid-transition,
+ * and this is what lets validate_scenes catch that statically (it reads scene sources and
+ * beats.json, it never launches a browser) instead of it going unnoticed until someone
+ * watches the render.
+ */
+export declare function writeSettleSidecar(outPathAbs: string, report: SettleReport): void;