@openvidstudio/capture 0.0.0-stage → 1.4.0

package/dist/settle.js

@@ -0,0 +1,124 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_QUIET_MS = exports.DEFAULT_SETTLE_TIMEOUT_MS = void 0;
+exports.settlePage = settlePage;
+exports.settleSidecarPath = settleSidecarPath;
+exports.writeSettleSidecar = writeSettleSidecar;
+const fs = __importStar(require("node:fs"));
+exports.DEFAULT_SETTLE_TIMEOUT_MS = 5000;
+exports.DEFAULT_QUIET_MS = 150;
+/**
+ * Runs in the page. Returns once fonts, images and finite animations are all done, or
+ * resolves early with what is still outstanding if the deadline passes first.
+ */
+/* c8 ignore start -- executes in the browser, covered by the real-browser E2E */
+const settleInPage = async (opts) => {
+    const deadline = Date.now() + opts.timeoutMs;
+    const left = () => Math.max(0, deadline - Date.now());
+    const withDeadline = (p, fallback) => Promise.race([p.catch(() => fallback), new Promise((r) => setTimeout(() => r(fallback), left()))]);
+    let fontsReady = true;
+    if (opts.fonts && typeof document.fonts !== "undefined") {
+        fontsReady = await withDeadline(document.fonts.ready.then(() => true), false);
+    }
+    let imagesReady = true;
+    if (opts.images) {
+        const pending = Array.from(document.images).filter((img) => !img.complete);
+        imagesReady = await withDeadline(Promise.all(pending.map((img) => img
+            .decode()
+            .catch(() => undefined)
+            .then(() => undefined))).then(() => true), false);
+    }
+    let pendingAnimations = 0;
+    let loopingAnimations = 0;
+    if (opts.animations && typeof document.getAnimations === "function") {
+        const running = document.getAnimations().filter((a) => a.playState === "running");
+        const finite = running.filter((a) => {
+            // An infinite animation has no end to wait for. Waiting on its `finished` promise
+            // hangs until the timeout, which on a page with a single looping spinner would make
+            // every capture pay the full deadline for nothing.
+            const timing = a.effect?.getComputedTiming?.();
+            const iterations = timing?.iterations;
+            return !(iterations === Infinity || iterations === null);
+        });
+        loopingAnimations = running.length - finite.length;
+        const allDone = await withDeadline(Promise.all(finite.map((a) => a.finished.catch(() => undefined))).then(() => true), false);
+        pendingAnimations = allDone
+            ? 0
+            : document.getAnimations().filter((a) => {
+                if (a.playState !== "running")
+                    return false;
+                const it = a.effect?.getComputedTiming?.()?.iterations;
+                return !(it === Infinity || it === null);
+            }).length;
+    }
+    return { settled: fontsReady && imagesReady && pendingAnimations === 0, pendingAnimations, loopingAnimations, fontsReady, imagesReady };
+};
+/* c8 ignore stop */
+/**
+ * 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.
+ */
+async function settlePage(page, opts = {}) {
+    const started = Date.now();
+    const report = await page.evaluate(settleInPage, {
+        timeoutMs: opts.timeoutMs ?? exports.DEFAULT_SETTLE_TIMEOUT_MS,
+        fonts: opts.fonts !== false,
+        images: opts.images !== false,
+        animations: opts.animations !== false,
+    });
+    const quiet = opts.quietMs ?? exports.DEFAULT_QUIET_MS;
+    if (quiet > 0)
+        await page.waitForTimeout(quiet);
+    return { ...report, waitedMs: Date.now() - started };
+}
+/** Sidecar path a SettleReport is written to, next to the capture artifact it describes. */
+function settleSidecarPath(outPathAbs) {
+    return `${outPathAbs}.settle.json`;
+}
+/**
+ * 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.
+ */
+function writeSettleSidecar(outPathAbs, report) {
+    fs.writeFileSync(settleSidecarPath(outPathAbs), JSON.stringify(report, null, 2) + "\n", "utf8");
+}

package/dist/terminal.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Records a real command run as timed text rather than as pixels.
+ *
+ * Two backends, same cast format:
+ *
+ * **pty** allocates a real pseudo-terminal through the optional `node-pty` module. The
+ * program under capture sees a terminal, so it keeps its colour, its progress bars, and
+ * its cursor addressing, which is what makes a recording look like the thing the user
+ * actually ran. A pty merges stdout and stderr onto one stream by construction, so every
+ * event in a pty cast is tagged "o": that is the pty's behaviour, not a loss of fidelity
+ * this module introduced.
+ *
+ * **pipe** is the fallback, and the only mode available when `node-pty` is not installed.
+ * It keeps stdout and stderr separate and needs no native build, at the cost that many
+ * programs detect no terminal is attached and suppress colour entirely, and a full-screen
+ * TUI replays only as far as the replay component understands its control sequences.
+ *
+ * `node-pty` is deliberately an optional peer dependency rather than a dependency: it
+ * compiles a native addon, and requiring one from everybody to record `npm test` would be
+ * a bad trade. The mode actually used is always reported back, so a dull, colourless
+ * recording has a visible cause rather than being a mystery.
+ */
+export type TerminalMode = "pty" | "pipe";
+export interface TerminalStep {
+    type: "type" | "wait";
+    text?: string;
+    ms?: number;
+}
+export type TerminalEvent = [number, "o" | "e", string];
+export interface TerminalCast {
+    version: 1;
+    command: string;
+    cols: number;
+    rows: number;
+    durationMs: number;
+    exitCode: number | null;
+    /** Which backend produced this cast. Absent in casts recorded before pty support existed. */
+    mode?: TerminalMode;
+    events: TerminalEvent[];
+}
+export interface RecordTerminalOptions {
+    command: string;
+    args?: string[];
+    cwd: string;
+    script?: TerminalStep[];
+    cols?: number;
+    rows?: number;
+    timeoutMs?: number;
+    /** "auto" uses a pty when node-pty is installed. "pipe" never does. "pty" fails if it is not. */
+    mode?: "auto" | "pty" | "pipe";
+    /**
+     * Stop recording after this many characters of output, and say so in the cast.
+     *
+     * The memory caps below are a safety net against a runaway process; this is a different
+     * thing, and a real one. A command whose output is genuinely enormous produces a cast
+     * nothing can replay: fetching one real installer for a demo returned 169,000 characters,
+     * which at any watchable typing speed is over an hour of screen time for a seven second
+     * beat. The first screenful is what a demo shows anyway, so bound it deliberately and
+     * mark the cast truncated rather than recording an unusable one or trimming it by hand
+     * afterwards, which would make the video stop matching the recording.
+     */
+    maxOutputChars?: number;
+}
+export interface RecordTerminalResult {
+    cast: TerminalCast;
+    truncated: boolean;
+    mode: TerminalMode;
+    /** Plain-language notices about the recording environment, for the caller to surface. */
+    warnings: string[];
+}
+/** A runaway process can emit output forever; cap what is retained rather than exhausting memory. */
+export declare const MAX_EVENTS = 20000;
+export declare const MAX_TOTAL_BYTES: number;
+interface PtyProcess {
+    onData(cb: (data: string) => void): void;
+    onExit(cb: (e: {
+        exitCode: number;
+        signal?: number;
+    }) => void): void;
+    write(data: string): void;
+    kill(signal?: string): void;
+}
+interface PtyModule {
+    spawn(file: string, args: string[], opts: {
+        name: string;
+        cols: number;
+        rows: number;
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+    }): PtyProcess;
+}
+/**
+ * Loads node-pty if it is present, and returns null rather than throwing if it is not.
+ *
+ * A native module can also be present but unloadable, typically after a Node version
+ * change rebuilt nothing, which throws a different error than "cannot find module". Both
+ * cases mean the same thing here: no pty is available, fall back.
+ */
+export declare function loadPty(): PtyModule | null;
+/**
+ * Python defaults that make a recorded run honest. Piped stdout is block-buffered, so without
+ * PYTHONUNBUFFERED a script's whole output arrives as one event at exit and the cast replays as
+ * a single dump; and on Windows the console code page is not UTF-8, so non-ASCII output is
+ * mangled or raises UnicodeEncodeError. These are the environment forms of `python -u` and
+ * `python -X utf8`, which means they apply however the program is launched. They sit below
+ * process.env so a caller who sets them deliberately still wins.
+ */
+export declare const PYTHON_RECORDING_ENV: Readonly<Record<string, string>>;
+export declare function childEnv(cols: number, rows: number): NodeJS.ProcessEnv;
+/**
+ * On Windows a bare `bash` on PATH is usually the WSL launcher (System32/bash.exe).
+ * It starts a Linux distro with its own filesystem and PATH, so `bash -c "npm test"` runs
+ * something other than what the author's Windows shell would. Returns a warning to show, or null.
+ */
+export declare function windowsShellWarning(command: string, platform?: NodeJS.Platform): string | null;
+export declare function recordTerminal(opts: RecordTerminalOptions): Promise<RecordTerminalResult>;
+export {};

package/dist/terminal.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PYTHON_RECORDING_ENV = exports.MAX_TOTAL_BYTES = exports.MAX_EVENTS = void 0;
+exports.loadPty = loadPty;
+exports.childEnv = childEnv;
+exports.windowsShellWarning = windowsShellWarning;
+exports.recordTerminal = recordTerminal;
+const node_child_process_1 = require("node:child_process");
+/** A runaway process can emit output forever; cap what is retained rather than exhausting memory. */
+exports.MAX_EVENTS = 20000;
+exports.MAX_TOTAL_BYTES = 4 * 1024 * 1024;
+const DEFAULT_COLS = 100;
+const DEFAULT_ROWS = 30;
+const DEFAULT_TIMEOUT_MS = 120000;
+/**
+ * Loads node-pty if it is present, and returns null rather than throwing if it is not.
+ *
+ * A native module can also be present but unloadable, typically after a Node version
+ * change rebuilt nothing, which throws a different error than "cannot find module". Both
+ * cases mean the same thing here: no pty is available, fall back.
+ */
+function loadPty() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require("node-pty");
+    }
+    catch {
+        return null;
+    }
+}
+/** Collects timestamped output chunks, enforcing the retention caps once for both backends. */
+class CastRecorder {
+    constructor(maxChars) {
+        this.maxChars = maxChars;
+        this.events = [];
+        this.truncated = false;
+        this.totalBytes = 0;
+        this.totalChars = 0;
+        this.started = Date.now();
+    }
+    record(stream, text) {
+        if (this.truncated)
+            return;
+        this.totalBytes += Buffer.byteLength(text);
+        // A deliberate character bound cuts mid-chunk, because a chunk can itself be the whole
+        // file. The memory caps below drop the chunk instead, since by then the goal is only to
+        // stop growing.
+        if (this.maxChars !== undefined && this.totalChars + text.length > this.maxChars) {
+            const room = Math.max(0, this.maxChars - this.totalChars);
+            if (room > 0)
+                this.events.push([this.elapsed(), stream, text.slice(0, room)]);
+            this.totalChars = this.maxChars;
+            this.truncated = true;
+            this.events.push([this.elapsed(), "e", "\n[openvidstudio: output truncated]\n"]);
+            return;
+        }
+        if (this.events.length >= exports.MAX_EVENTS || this.totalBytes > exports.MAX_TOTAL_BYTES) {
+            this.truncated = true;
+            this.events.push([this.elapsed(), "e", "\n[openvidstudio: output truncated]\n"]);
+            return;
+        }
+        this.totalChars += text.length;
+        this.events.push([this.elapsed(), stream, text]);
+    }
+    elapsed() {
+        return Date.now() - this.started;
+    }
+}
+/**
+ * Python defaults that make a recorded run honest. Piped stdout is block-buffered, so without
+ * PYTHONUNBUFFERED a script's whole output arrives as one event at exit and the cast replays as
+ * a single dump; and on Windows the console code page is not UTF-8, so non-ASCII output is
+ * mangled or raises UnicodeEncodeError. These are the environment forms of `python -u` and
+ * `python -X utf8`, which means they apply however the program is launched. They sit below
+ * process.env so a caller who sets them deliberately still wins.
+ */
+exports.PYTHON_RECORDING_ENV = {
+    PYTHONUNBUFFERED: "1",
+    PYTHONUTF8: "1",
+    PYTHONIOENCODING: "utf-8",
+};
+function childEnv(cols, rows) {
+    return {
+        ...exports.PYTHON_RECORDING_ENV,
+        ...process.env,
+        COLUMNS: String(cols),
+        LINES: String(rows),
+        TERM: "xterm-256color",
+    };
+}
+/**
+ * On Windows a bare `bash` on PATH is usually the WSL launcher (System32/bash.exe).
+ * It starts a Linux distro with its own filesystem and PATH, so `bash -c "npm test"` runs
+ * something other than what the author's Windows shell would. Returns a warning to show, or null.
+ */
+function windowsShellWarning(command, platform = process.platform) {
+    if (platform !== "win32")
+        return null;
+    const base = command.split(/[\\/]/).pop().toLowerCase().replace(/\.exe$/, "");
+    if (base !== "bash")
+        return null;
+    // A path the caller chose (Git Bash under Program Files, say) is taken at its word. Only a
+    // bare name, which Windows resolves through PATH, or the System32 launcher itself is the trap.
+    const hasPath = /[\\/]/.test(command);
+    if (hasPath && !/[\\/]system32[\\/]/i.test(command))
+        return null;
+    return (`"${command}" on Windows usually resolves to the WSL launcher (System32/bash.exe), which runs inside a ` +
+        `Linux distro with a different filesystem and PATH. Use Git Bash by full path, or run the program ` +
+        `directly (for example command "node" with args) so the recording shows what a Windows user would see.`);
+}
+/**
+ * Replays scripted input against the child's stdin. Typing is sent as one write per step
+ * rather than per character: the replay component controls on-screen typing cadence, so
+ * simulating keystroke timing at the process level would double it.
+ */
+async function replayScript(steps, write, done, isSettled) {
+    for (const step of steps ?? []) {
+        if (isSettled())
+            return;
+        if (step.type === "wait") {
+            await new Promise((r) => setTimeout(r, step.ms ?? 0));
+        }
+        else if (step.type === "type") {
+            write(step.text ?? "");
+        }
+    }
+    done();
+}
+async function recordWithPty(pty, opts, cols, rows, timeoutMs) {
+    const recorder = new CastRecorder(opts.maxOutputChars);
+    const child = pty.spawn(opts.command, opts.args ?? [], {
+        name: "xterm-256color",
+        cols,
+        rows,
+        cwd: opts.cwd,
+        env: childEnv(cols, rows),
+    });
+    const exitCode = await new Promise((resolve) => {
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(code);
+        };
+        const timer = setTimeout(() => {
+            recorder.record("e", `\n[openvidstudio: timed out after ${timeoutMs / 1000}s]\n`);
+            child.kill();
+        }, timeoutMs);
+        // A pty is one stream by construction: the program's stderr is written to the same
+        // terminal its stdout is, which is exactly why colour survives.
+        child.onData((data) => recorder.record("o", data));
+        child.onExit(({ exitCode: code }) => finish(code));
+        void replayScript(opts.script, (text) => child.write(text), () => {
+            /* A pty has no stdin to close: EOF is sent by the script itself, as Ctrl-D. */
+        }, () => settled);
+    });
+    return { recorder, exitCode };
+}
+async function recordWithPipes(opts, cols, rows, timeoutMs) {
+    const recorder = new CastRecorder(opts.maxOutputChars);
+    // shell:false with an argv array, same discipline as every other spawn in this package:
+    // `command` and `args` come from a beats.json a human approved, but they are still not
+    // concatenated into a command line.
+    const child = (0, node_child_process_1.spawn)(opts.command, opts.args ?? [], {
+        cwd: opts.cwd,
+        shell: false,
+        env: childEnv(cols, rows),
+    });
+    const exitCode = await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(code);
+        };
+        const timer = setTimeout(() => {
+            recorder.record("e", `\n[openvidstudio: timed out after ${timeoutMs / 1000}s]\n`);
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 3000).unref?.();
+        }, timeoutMs);
+        child.stdout?.on("data", (c) => recorder.record("o", c.toString("utf8")));
+        child.stderr?.on("data", (c) => recorder.record("e", c.toString("utf8")));
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const msg = /ENOENT/.test(String(err))
+                ? `Command not found: "${opts.command}". Check it is installed and on PATH for this process.`
+                : String(err);
+            reject(new Error(msg));
+        });
+        child.on("close", (code) => finish(code));
+        void replayScript(opts.script, (text) => child.stdin?.write(text), () => child.stdin?.end(), () => settled);
+    });
+    return { recorder, exitCode };
+}
+async function recordTerminal(opts) {
+    const cols = opts.cols ?? DEFAULT_COLS;
+    const rows = opts.rows ?? DEFAULT_ROWS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const requested = opts.mode ?? "auto";
+    const pty = requested === "pipe" ? null : loadPty();
+    if (requested === "pty" && !pty) {
+        throw new Error(`mode "pty" was requested but node-pty is not loadable. Install it in the project that runs this ` +
+            `capture ("npm install node-pty"), which compiles a native addon, or use mode "auto" to fall back to ` +
+            `piped stdout/stderr.`);
+    }
+    const mode = pty ? "pty" : "pipe";
+    const { recorder, exitCode } = pty
+        ? await recordWithPty(pty, opts, cols, rows, timeoutMs)
+        : await recordWithPipes(opts, cols, rows, timeoutMs);
+    return {
+        cast: {
+            version: 1,
+            command: [opts.command, ...(opts.args ?? [])].join(" "),
+            cols,
+            rows,
+            durationMs: recorder.elapsed(),
+            exitCode,
+            mode,
+            events: recorder.events,
+        },
+        truncated: recorder.truncated,
+        mode,
+        warnings: [windowsShellWarning(opts.command)].filter((w) => w !== null),
+    };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@openvidstudio/capture",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.4.0",
+  "description": "Zoom-compensated browser capture plus desktop, mobile, and terminal recording backends. No Remotion, no React, no video pipeline.",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "playwright": "^1.64.0",
+    "zod": "^4.6.6"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnayDhawan/openvidstudio.git",
+    "directory": "packages/capture"
+  },
+  "homepage": "https://github.com/AnayDhawan/openvidstudio#readme",
+  "bugs": {
+    "url": "https://github.com/AnayDhawan/openvidstudio/issues"
+  },
+  "keywords": [
+    "playwright",
+    "screenshot",
+    "screen-recording",
+    "capture",
+    "ffmpeg",
+    "adb"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
 }