@openvidstudio/capture 0.0.0-stage → 1.3.1

package/dist/browser.js

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chromium = exports.ZoomCompensationError = exports.ZOOM_EPSILON = exports.interactionSchema = exports.viewportSchema = exports.DEFAULT_DEVICE_SCALE = exports.DEFAULT_VIEWPORT = void 0;
+exports.replayInteractions = replayInteractions;
+exports.detectAndCompensateZoom = detectAndCompensateZoom;
+exports.launchChromium = launchChromium;
+exports.resolvedPlaywrightVersion = resolvedPlaywrightVersion;
+const playwright_1 = require("playwright");
+Object.defineProperty(exports, "chromium", { enumerable: true, get: function () { return playwright_1.chromium; } });
+const settle_1 = require("./settle");
+const zod_1 = require("zod");
+/** CAPTURE.md's worked example. */
+exports.DEFAULT_VIEWPORT = { width: 1600, height: 1000 };
+/**
+ * Capture at twice the CSS resolution by default.
+ *
+ * This is the single biggest quality lever in the pipeline and it used to be missing.
+ * A capture taken at 1x is exactly as many pixels as the viewport, and the video then
+ * puts it on a 1920x1080 stage and pushes a camera into it. Every one of those steps
+ * is an upscale, so a 1440x900 capture shown at a 1.33 camera scale is being asked for
+ * roughly 1.8x the pixels it has, and the result is the soft, slightly smeared text
+ * that makes a demo look cheap.
+ *
+ * At 2x there are pixels to spare for both the stage and the push-in, so the frame stays
+ * sharp all the way through. The cost is memory and file size during capture, which is
+ * the right trade for an asset that gets rendered once and watched many times.
+ */
+exports.DEFAULT_DEVICE_SCALE = 2;
+exports.viewportSchema = zod_1.z.object({
+    width: zod_1.z.number().int().positive(),
+    height: zod_1.z.number().int().positive(),
+});
+exports.interactionSchema = zod_1.z.discriminatedUnion("type", [
+    zod_1.z.object({ type: zod_1.z.literal("click"), selector: zod_1.z.string().min(1) }),
+    zod_1.z.object({ type: zod_1.z.literal("fill"), selector: zod_1.z.string().min(1), value: zod_1.z.string() }),
+    zod_1.z.object({ type: zod_1.z.literal("select"), selector: zod_1.z.string().min(1), value: zod_1.z.string() }),
+    zod_1.z.object({ type: zod_1.z.literal("hover"), selector: zod_1.z.string().min(1) }),
+    zod_1.z.object({
+        type: zod_1.z.literal("scroll"),
+        selector: zod_1.z.string().optional(),
+        x: zod_1.z.number().optional(),
+        y: zod_1.z.number().optional(),
+        // Undefined/0 keeps the old instant scrollTo -- an unrequested behaviour change would
+        // silently retime every beat that already has a scroll interaction. Positive is an
+        // eased scroll (see easedScrollInPage below) driven by requestAnimationFrame, since
+        // CSS's `behavior: "smooth"` gives no control over duration or curve and browsers are
+        // free to shorten or skip it, neither of which is acceptable for video timing.
+        durationMs: zod_1.z.number().positive().optional(),
+    }),
+    zod_1.z.object({ type: zod_1.z.literal("wait"), ms: zod_1.z.number().optional(), selector: zod_1.z.string().optional() }),
+    // Not a timed guess. "settle" drives whatever the previous step started (a modal
+    // transition, a route change, a lazily loaded image) to completion before the next step
+    // runs, which is what stops a capture landing halfway through a fade.
+    zod_1.z.object({ type: zod_1.z.literal("settle"), ms: zod_1.z.number().optional() }),
+]);
+/**
+ * Runs in the page against a scrollable element. `behavior: "smooth"` was rejected on
+ * purpose: it has no duration/easing parameters, a page can override its own
+ * scroll-behavior CSS out from under it, and browsers are free to shorten or skip a smooth
+ * scroll under reduced-motion or heavy load -- none of which is acceptable when the
+ * duration has to match the video's timeline exactly. Driven by requestAnimationFrame
+ * instead, resolving its own promise so replayInteractions can await the real end of the
+ * animation rather than a fixed sleep.
+ */
+/* c8 ignore start -- executes in the browser, covered by the real-browser E2E */
+function easedScrollElementInPage(el, args) {
+    const target = el;
+    const startX = target.scrollLeft;
+    const startY = target.scrollTop;
+    const endX = args.x ?? startX;
+    const endY = args.y ?? startY;
+    const duration = args.durationMs;
+    return new Promise((resolve) => {
+        const start = performance.now();
+        const step = (now) => {
+            const t = Math.min(1, (now - start) / duration);
+            // Cubic ease-in-out: slow away from the start, fast through the middle, slow into
+            // the landing point -- a linear scroll reads as mechanical on camera in a way an
+            // eased one does not.
+            const eased = t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+            target.scrollTo(startX + (endX - startX) * eased, startY + (endY - startY) * eased);
+            if (t < 1)
+                requestAnimationFrame(step);
+            else
+                resolve();
+        };
+        requestAnimationFrame(step);
+    });
+}
+/* c8 ignore stop */
+/** Same easing as easedScrollElementInPage, against the window instead of an element. */
+/* c8 ignore start -- executes in the browser, covered by the real-browser E2E */
+function easedScrollWindowInPage(args) {
+    const startX = window.scrollX;
+    const startY = window.scrollY;
+    const endX = args.x ?? startX;
+    const endY = args.y ?? startY;
+    const duration = args.durationMs;
+    return new Promise((resolve) => {
+        const start = performance.now();
+        const step = (now) => {
+            const t = Math.min(1, (now - start) / duration);
+            const eased = t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+            window.scrollTo(startX + (endX - startX) * eased, startY + (endY - startY) * eased);
+            if (t < 1)
+                requestAnimationFrame(step);
+            else
+                resolve();
+        };
+        requestAnimationFrame(step);
+    });
+}
+/* c8 ignore stop */
+/**
+ * Measures a click/hover/fill/select target's real on-screen center right before the
+ * action runs -- same rect-measurement style as captureScreenshot.ts's cropSelector code.
+ * Scrolls the target into view first, matching the auto-scroll every one of these
+ * Playwright actions already does internally, so the coordinate lands in the same
+ * effective viewport space the final screenshot/recording is captured in rather than
+ * wherever the element happened to sit before the action's own scroll would have moved it.
+ *
+ * Best-effort and silent on failure: a selector that doesn't resolve here is about to make
+ * the action itself throw a real, clearer error a moment later, and this is not the call
+ * that should report it first.
+ */
+/* c8 ignore start -- executes in the browser, covered by the real-browser E2E */
+async function recordCursorPoint(page, points, index, type, selector, replayStartedAt) {
+    try {
+        const center = await page.$eval(selector, (el) => {
+            el.scrollIntoView({ block: "center", inline: "center" });
+            const r = el.getBoundingClientRect();
+            return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+        });
+        points.push({ index, type, selector, x: center.x, y: center.y, atMs: Date.now() - replayStartedAt });
+    }
+    catch {
+        // Selector didn't resolve or wasn't measurable -- not this function's job to report.
+    }
+}
+/* c8 ignore stop */
+/**
+ * Replays a beat's interactions in array order. Shared verbatim by both capture
+ * tools so their replay semantics never drift apart -- called after navigation
+ * and (for both tools) after the zoom-desync compensation below, in the same
+ * effective CSS-pixel viewport CAPTURE.md measured.
+ *
+ * Returns every click/hover/fill/select target's real measured center, in replay order,
+ * for capture_screenshot/capture_screen_recording to persist as a cursor sidecar (see
+ * cursor.ts) -- this is what lets scaffold_scene's cursor overlay land on real coordinates
+ * instead of a hand-authored guess.
+ */
+async function replayInteractions(page, interactions) {
+    const points = [];
+    const replayStartedAt = Date.now();
+    let index = 0;
+    for (const interaction of interactions ?? []) {
+        switch (interaction.type) {
+            case "click":
+                await recordCursorPoint(page, points, index, "click", interaction.selector, replayStartedAt);
+                await page.click(interaction.selector);
+                break;
+            case "fill":
+                await recordCursorPoint(page, points, index, "fill", interaction.selector, replayStartedAt);
+                await page.fill(interaction.selector, interaction.value);
+                break;
+            case "select":
+                await recordCursorPoint(page, points, index, "select", interaction.selector, replayStartedAt);
+                await page.selectOption(interaction.selector, interaction.value);
+                break;
+            case "hover":
+                await recordCursorPoint(page, points, index, "hover", interaction.selector, replayStartedAt);
+                await page.hover(interaction.selector);
+                break;
+            case "scroll":
+                if (interaction.durationMs && interaction.durationMs > 0) {
+                    const args = { x: interaction.x, y: interaction.y, durationMs: interaction.durationMs };
+                    if (interaction.selector) {
+                        await page.$eval(interaction.selector, easedScrollElementInPage, args);
+                    }
+                    else {
+                        await page.evaluate(easedScrollWindowInPage, args);
+                    }
+                }
+                else if (interaction.selector) {
+                    await page.$eval(interaction.selector, (el, coords) => el.scrollTo(coords.x ?? 0, coords.y ?? 0), { x: interaction.x, y: interaction.y });
+                }
+                else {
+                    await page.evaluate((coords) => window.scrollTo(coords.x ?? 0, coords.y ?? 0), { x: interaction.x, y: interaction.y });
+                }
+                break;
+            case "wait":
+                if (interaction.selector) {
+                    await page.waitForSelector(interaction.selector, { timeout: interaction.ms });
+                }
+                else {
+                    await page.waitForTimeout(interaction.ms ?? 500);
+                }
+                break;
+            case "settle":
+                await (0, settle_1.settlePage)(page, { timeoutMs: interaction.ms });
+                break;
+        }
+        index++;
+    }
+    return points;
+}
+exports.ZOOM_EPSILON = 0.01;
+/**
+ * Thrown when a single compensation attempt doesn't converge -- CAPTURE.md
+ * doesn't explicitly cover this case (it assumes the desync ratio is
+ * consistent), so this is surfaced as a real error rather than silently
+ * proceeding with a crop rect measured against the wrong effective viewport.
+ */
+class ZoomCompensationError extends Error {
+    constructor(target, zoom, effective) {
+        super(`Zoom-desync compensation did not converge: requested ${target.width}x${target.height}, measured zoom ` +
+            `${zoom.toFixed(4)} (per CAPTURE.md, this ratio is not hardcoded, it can differ per machine/profile), ` +
+            `but after one compensation attempt the effective viewport was ${effective.width}x${effective.height}, ` +
+            `not ${target.width}x${target.height} within ${(exports.ZOOM_EPSILON * 100).toFixed(0)}%. Refusing to proceed ` +
+            `with a screenshot/crop measured against the wrong effective viewport -- see packages/docs/CAPTURE.md.`);
+        this.target = target;
+        this.zoom = zoom;
+        this.effective = effective;
+        this.name = "ZoomCompensationError";
+    }
+}
+exports.ZoomCompensationError = ZoomCompensationError;
+async function measureEffectiveViewport(page) {
+    const [width, height] = await page.evaluate(() => [window.innerWidth, window.innerHeight]);
+    return { width, height };
+}
+function relativeDiff(actual, target) {
+    return Math.abs(actual - target) / target;
+}
+/**
+ * CAPTURE.md's zoom-desync detection + compensation (protocol steps 1-2).
+ * Assumes the caller already called `page.setViewportSize(target)` and
+ * `page.goto(...)` -- this only measures and, if needed, re-requests a
+ * compensated viewport and re-verifies once.
+ *
+ * Never hardcodes a zoom constant (CAPTURE.md is explicit the ratio "can
+ * differ per machine/profile") -- it is measured live on every call. If the
+ * one compensation attempt doesn't bring the effective viewport back to
+ * `target` within `ZOOM_EPSILON`, throws `ZoomCompensationError` rather than
+ * silently proceeding.
+ */
+async function detectAndCompensateZoom(page, target) {
+    const firstMeasurement = await measureEffectiveViewport(page);
+    const zoom = target.width / firstMeasurement.width;
+    if (Math.abs(zoom - 1) <= exports.ZOOM_EPSILON) {
+        return { viewport: target, zoom, effective: firstMeasurement };
+    }
+    const compensated = {
+        width: Math.round(target.width * zoom),
+        height: Math.round(target.height * zoom),
+    };
+    await page.setViewportSize(compensated);
+    const secondMeasurement = await measureEffectiveViewport(page);
+    const converged = relativeDiff(secondMeasurement.width, target.width) <= exports.ZOOM_EPSILON &&
+        relativeDiff(secondMeasurement.height, target.height) <= exports.ZOOM_EPSILON;
+    if (!converged) {
+        throw new ZoomCompensationError(target, zoom, secondMeasurement);
+    }
+    return { viewport: compensated, zoom, effective: secondMeasurement };
+}
+const BROWSER_NOT_INSTALLED_RE = /Executable doesn't exist at/;
+/**
+ * Playwright's bundled browser binary is not installed by a plain `npm
+ * install`/`pnpm install` (it needs a separate `npx playwright install
+ * chromium`, deliberately not wired as a postinstall script -- see this
+ * package's README/tool descriptions). Rather than let that surface as a
+ * cryptic native-binary launch error, catch it here and return a clear,
+ * actionable message.
+ */
+async function launchChromium() {
+    try {
+        return await playwright_1.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (BROWSER_NOT_INSTALLED_RE.test(message)) {
+            throw new Error(`Playwright's Chromium browser is not installed. Run "npx playwright install chromium" (in the ` +
+                `project, or wherever @openvidstudio/mcp-server is installed) and retry. Original error: ${message}`);
+        }
+        throw err;
+    }
+}
+/**
+ * The version of the `chromium` BrowserType re-exported above, read from that same resolved
+ * package rather than a fresh "playwright" lookup, so a report naming this version can never
+ * name a different install than the one executablePath() below actually resolved against.
+ */
+function resolvedPlaywrightVersion() {
+    // A plain require for one field off a package.json, not a code import -- this package's
+    // commonjs target has no resolveJsonModule story that would make `import ... from
+    // "playwright/package.json"` resolve the same way `import { chromium } from "playwright"`
+    // above already does.
+    return require("playwright/package.json").version;
+}

package/dist/captureSidecar.d.ts

@@ -0,0 +1,43 @@
+import type { Interaction, Viewport } from "./browser";
+/**
+ * What docs_drift and release_diff need to re-capture a reference frame the SAME way it
+ * was captured the first time, instead of guessing a CSS viewport back out of the reference
+ * image's own pixel dimensions.
+ *
+ * That guess is the bug this sidecar exists to kill: a screenshot taken at a 1440x900 CSS
+ * viewport with deviceScaleFactor 2 is a 2880x1800 PNG on disk, and treating 2880x1800 as
+ * the viewport to re-navigate to is a completely different, much wider layout -- not the
+ * page that was actually captured, just a bigger one. Every re-capture built on that guess
+ * reports drift on a page that never changed.
+ *
+ * `viewport` here is the *requested* CSS viewport (the same value passed to
+ * `detectAndCompensateZoom` as `target`), not the compensated size that call returned.
+ * Re-feeding the request through that same live zoom-detection path on whatever machine
+ * does the re-capture is what CAPTURE.md's "never hardcode the ratio, it differs per
+ * machine/profile" rule requires -- baking in one machine's already-compensated size would
+ * just move the guessing problem, not remove it. `zoom` is carried along anyway, purely as
+ * a record of what this capture measured; nothing re-derives a viewport from it.
+ */
+export interface CaptureSidecar {
+    url: string;
+    viewport: Viewport;
+    deviceScaleFactor: number;
+    /** The zoom-desync ratio measured at capture time. Informational: a re-capture measures its own. */
+    zoom: number;
+    /** Replayed before the capture. Absent when there were none. */
+    interactions?: Interaction[];
+    /** ISO-8601 timestamp of the capture. */
+    capturedAt: string;
+}
+/** Sidecar path for a capture artifact, mirroring settle's/cursor's `<outPath>.*.json` convention. */
+export declare function captureSidecarPath(outPathAbs: string): string;
+/**
+ * Persists a CaptureSidecar next to the artifact it describes. Written for every capture,
+ * cropSelector-based ones included: docs_drift already requires an explicit binding for a
+ * cropSelector beat (its reference is a crop of a page, not a view of one), and this sidecar
+ * does not change that, it just gives every OTHER beat a real binding to read instead of a
+ * guess.
+ */
+export declare function writeCaptureSidecar(outPathAbs: string, sidecar: CaptureSidecar): void;
+/** Reads the sidecar for a capture artifact, or undefined when there isn't one (a legacy asset). */
+export declare function readCaptureSidecar(outPathAbs: string): CaptureSidecar | undefined;

package/dist/captureSidecar.js

@@ -0,0 +1,65 @@
+"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.captureSidecarPath = captureSidecarPath;
+exports.writeCaptureSidecar = writeCaptureSidecar;
+exports.readCaptureSidecar = readCaptureSidecar;
+const fs = __importStar(require("node:fs"));
+/** Sidecar path for a capture artifact, mirroring settle's/cursor's `<outPath>.*.json` convention. */
+function captureSidecarPath(outPathAbs) {
+    return `${outPathAbs}.capture.json`;
+}
+/**
+ * Persists a CaptureSidecar next to the artifact it describes. Written for every capture,
+ * cropSelector-based ones included: docs_drift already requires an explicit binding for a
+ * cropSelector beat (its reference is a crop of a page, not a view of one), and this sidecar
+ * does not change that, it just gives every OTHER beat a real binding to read instead of a
+ * guess.
+ */
+function writeCaptureSidecar(outPathAbs, sidecar) {
+    fs.writeFileSync(captureSidecarPath(outPathAbs), JSON.stringify(sidecar, null, 2) + "\n", "utf8");
+}
+/** Reads the sidecar for a capture artifact, or undefined when there isn't one (a legacy asset). */
+function readCaptureSidecar(outPathAbs) {
+    const sidecarPath = captureSidecarPath(outPathAbs);
+    if (!fs.existsSync(sidecarPath))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cursor.d.ts

@@ -0,0 +1,53 @@
+import type { Viewport } from "./browser";
+/**
+ * Real cursor coordinates recorded during replayInteractions, so scaffold_scene's cursor
+ * overlay can show the actor landing where the product was actually clicked instead of a
+ * hand-drawn guess.
+ *
+ * The old way: a scene author who wanted a cursor built one from primitives, picking x/y
+ * keyframes by eye against a static screenshot. Nothing tied those numbers to where the
+ * real click during capture happened, so a redesign that moved a button left the cursor
+ * pointing at empty space with no error anywhere -- the same silent-wrongness failure mode
+ * validate_scenes exists to catch for framing, just uncaught for this.
+ */
+export type CursorPointType = "click" | "hover" | "fill" | "select";
+export interface CursorPoint {
+    /** Index into the interactions array this point came from, in replay order. */
+    index: number;
+    type: CursorPointType;
+    selector: string;
+    /**
+     * The target's bounding-rect center, in the CSS-pixel viewport space the capture ran in
+     * (the same effective, zoom-compensated space captureWidth/captureHeight describe) --
+     * NOT multiplied by deviceScaleFactor. Measured after scrolling the target into view,
+     * matching what a real click/hover action does before it acts.
+     */
+    x: number;
+    y: number;
+    /**
+     * Milliseconds since replayInteractions started measuring this beat's interactions.
+     * capture_screen_recording rewrites this to be relative to the RECORDING's own start
+     * (adding back the navigation+settle time that ran before replay began) before writing
+     * the sidecar, so a consumer can turn it into a frame via fps directly. capture_screenshot
+     * leaves it replay-relative: a still has no video timeline for it to be relative to.
+     */
+    atMs: number;
+}
+export interface CursorSidecar {
+    /**
+     * The CSS-pixel viewport the points were measured in. Carried here explicitly rather
+     * than assumed, so a consumer can convert a point into its own stage/frame geometry
+     * without having to reprobe or guess the capture's own viewport.
+     */
+    viewport: Viewport;
+    points: CursorPoint[];
+}
+export declare function cursorSidecarPath(outPathAbs: string): string;
+/**
+ * Persists recorded cursor points next to the artifact they describe, mirroring settle's
+ * `<outPath>.settle.json` sidecar convention. Writes nothing when there are no points, so a
+ * beat with no click/hover/fill/select interactions (most `dom-demo`-adjacent capture
+ * beats, or one that only scrolls/waits) produces no sidecar rather than an empty,
+ * meaningless file that scaffold_scene would otherwise have to special-case around.
+ */
+export declare function writeCursorSidecar(outPathAbs: string, viewport: Viewport, points: CursorPoint[]): void;

package/dist/cursor.js

@@ -0,0 +1,54 @@
+"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.cursorSidecarPath = cursorSidecarPath;
+exports.writeCursorSidecar = writeCursorSidecar;
+const fs = __importStar(require("node:fs"));
+function cursorSidecarPath(outPathAbs) {
+    return `${outPathAbs}.cursor.json`;
+}
+/**
+ * Persists recorded cursor points next to the artifact they describe, mirroring settle's
+ * `<outPath>.settle.json` sidecar convention. Writes nothing when there are no points, so a
+ * beat with no click/hover/fill/select interactions (most `dom-demo`-adjacent capture
+ * beats, or one that only scrolls/waits) produces no sidecar rather than an empty,
+ * meaningless file that scaffold_scene would otherwise have to special-case around.
+ */
+function writeCursorSidecar(outPathAbs, viewport, points) {
+    if (points.length === 0)
+        return;
+    const sidecar = { viewport, points };
+    fs.writeFileSync(cursorSidecarPath(outPathAbs), JSON.stringify(sidecar, null, 2) + "\n", "utf8");
+}

package/dist/determinism.d.ts

@@ -0,0 +1,34 @@
+import type { Page } from "playwright";
+/**
+ * Opt-in determinism for capture_screenshot/capture_screen_recording, so two captures of
+ * an unchanged page are byte-identical instead of differing on whatever the page derived
+ * from the real clock or Math.random() (a timestamp-based id, a typewriter effect keyed off
+ * Date.now(), a randomly ordered list).
+ *
+ * Deliberately uses `clock.setFixedTime`, not `clock.install`/`pauseAt`: those replace
+ * setTimeout/setInterval/requestAnimationFrame with fake, manually-driven timers, which
+ * would also freeze settlePage's own real-time deadline race (it runs *inside* the page via
+ * page.evaluate) and every CSS/JS animation settlePage is waiting on -- exactly the two
+ * things a capture still needs to actually finish. `setFixedTime` freezes only what
+ * `Date.now()`/`new Date()` report, and "keeps all the timers running" (Playwright's own
+ * wording), so nothing about settle or animation timing changes.
+ *
+ * Forcing a CSS animation to a specific phase, or a JS-driven one to a deterministic state,
+ * is a separate, harder problem (reducedMotion emulation gets partway there but does not
+ * solve it) and is intentionally out of scope here.
+ */
+export interface DeterminismOptions {
+    /** Fixed value Date.now()/new Date() report for the whole capture. */
+    epochMs?: number;
+    /** Seed for the Math.random() override. */
+    seed?: number;
+}
+/** An arbitrary fixed instant -- any constant works, what matters is that it never changes. */
+export declare const DEFAULT_DETERMINISTIC_EPOCH_MS: number;
+export declare const DEFAULT_DETERMINISTIC_SEED = 49734321;
+/**
+ * Installs both overrides. Call after the page exists but before navigation -- same timing
+ * rule as colorScheme/reducedMotion: applied after the first paint, this would race a page
+ * that reads Math.random()/Date.now() once at load and caches the result.
+ */
+export declare function installDeterminism(page: Page, opts?: DeterminismOptions): Promise<void>;

package/dist/determinism.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DETERMINISTIC_SEED = exports.DEFAULT_DETERMINISTIC_EPOCH_MS = void 0;
+exports.installDeterminism = installDeterminism;
+/** An arbitrary fixed instant -- any constant works, what matters is that it never changes. */
+exports.DEFAULT_DETERMINISTIC_EPOCH_MS = Date.UTC(2024, 0, 1);
+exports.DEFAULT_DETERMINISTIC_SEED = 0x2f6e2b1;
+/**
+ * Runs in the page, injected via addInitScript before any page script. A small fixed-seed
+ * PRNG (mulberry32) so the override needs no dependency and stays reproducible across Node
+ * versions/platforms, unlike reseeding whatever RNG the JS engine's own Math.random() uses
+ * internally (which isn't seedable at all).
+ */
+/* c8 ignore start -- executes in the browser, covered by the real-browser E2E */
+function seedMathRandomInPage(seed) {
+    let state = seed >>> 0;
+    Math.random = () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/* c8 ignore stop */
+/**
+ * Installs both overrides. Call after the page exists but before navigation -- same timing
+ * rule as colorScheme/reducedMotion: applied after the first paint, this would race a page
+ * that reads Math.random()/Date.now() once at load and caches the result.
+ */
+async function installDeterminism(page, opts = {}) {
+    await page.addInitScript(seedMathRandomInPage, opts.seed ?? exports.DEFAULT_DETERMINISTIC_SEED);
+    await page.clock.setFixedTime(opts.epochMs ?? exports.DEFAULT_DETERMINISTIC_EPOCH_MS);
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @openvidstudio/capture
+ *
+ * The half of openvidstudio that has nothing to do with video: getting a true frame out
+ * of a running product. A real browser with the per-origin zoom desync measured and
+ * compensated rather than assumed, interaction replay, and ffmpeg/adb/simctl backends for
+ * the desktop, mobile, and terminal surfaces a browser cannot reach.
+ *
+ * Deliberately free of Remotion, React, and @openvidstudio/core: a team that wants
+ * trustworthy capture and does not want to make videos should be able to take this alone.
+ */
+export * from "./process";
+export * from "./browser";
+export * from "./determinism";
+export * from "./settle";
+export * from "./cursor";
+export * from "./captureSidecar";
+export * from "./native";
+export * from "./terminal";
+export * from "./layers";

package/dist/index.js

@@ -0,0 +1,36 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @openvidstudio/capture
+ *
+ * The half of openvidstudio that has nothing to do with video: getting a true frame out
+ * of a running product. A real browser with the per-origin zoom desync measured and
+ * compensated rather than assumed, interaction replay, and ffmpeg/adb/simctl backends for
+ * the desktop, mobile, and terminal surfaces a browser cannot reach.
+ *
+ * Deliberately free of Remotion, React, and @openvidstudio/core: a team that wants
+ * trustworthy capture and does not want to make videos should be able to take this alone.
+ */
+__exportStar(require("./process"), exports);
+__exportStar(require("./browser"), exports);
+__exportStar(require("./determinism"), exports);
+__exportStar(require("./settle"), exports);
+__exportStar(require("./cursor"), exports);
+__exportStar(require("./captureSidecar"), exports);
+__exportStar(require("./native"), exports);
+__exportStar(require("./terminal"), exports);
+__exportStar(require("./layers"), exports);