@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/capture.d.ts

@@ -105,6 +105,39 @@ export declare class ZoomCompensationError extends Error {
  * silently proceeding.
  */
 export declare function detectAndCompensateZoom(page: Page, target: Viewport): Promise<ZoomCompensation>;
+/** Default budget for waitForSettle when a beat/tool call doesn't name its own. */
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 4000;
+export interface SettleResult {
+    settled: boolean;
+    timedOut: boolean;
+    /** Which categories were still not settled when this returned: "fonts", "images", "animations". */
+    pending: string[];
+    waitedMs: number;
+}
+/**
+ * Waits for the page to reach a state safe to capture: web fonts finished
+ * swapping, every `<img>` already in the DOM finished decoding, and any
+ * finite CSS/Web Animation has landed on its end state. An infinite
+ * animation (a spinner, a pulsing loader -- `iterations: Infinity`) is
+ * recognised and excluded from the wait rather than polled forever, which
+ * would otherwise burn the whole budget on most real pages, since almost
+ * any product has one running somewhere.
+ *
+ * Polls every `SETTLE_POLL_MS` up to `timeoutMs` rather than waiting on a
+ * single combined promise, because "settled" can regress: an interaction
+ * can kick off a new finite animation after fonts/images already cleared,
+ * and the loop needs to see all three conditions true at once, not each
+ * true at some point.
+ */
+export declare function waitForSettle(page: Page, timeoutMs: number): Promise<SettleResult>;
+/** Sidecar path a settle result is written to, next to the capture artifact it describes. */
+export declare function settleSidecarPath(outPathAbs: string): string;
+/**
+ * Persists a SettleResult next to the artifact it describes, so validate_scenes can
+ * report a timed-out settle statically (it reads scene sources and beats.json, it does
+ * not launch a browser) without re-running the capture.
+ */
+export declare function writeSettleSidecar(outPathAbs: string, result: SettleResult): void;
 /**
  * Playwright's bundled browser binary is not installed by a plain `npm
  * install`/`pnpm install` (it needs a separate `npx playwright install

package/dist/capture.js

@@ -1,9 +1,46 @@
 "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.ZoomCompensationError = exports.ZOOM_EPSILON = exports.interactionSchema = exports.viewportSchema = exports.DEFAULT_VIEWPORT = void 0;
+exports.DEFAULT_SETTLE_TIMEOUT_MS = exports.ZoomCompensationError = exports.ZOOM_EPSILON = exports.interactionSchema = exports.viewportSchema = exports.DEFAULT_VIEWPORT = void 0;
 exports.replayInteractions = replayInteractions;
 exports.detectAndCompensateZoom = detectAndCompensateZoom;
+exports.waitForSettle = waitForSettle;
+exports.settleSidecarPath = settleSidecarPath;
+exports.writeSettleSidecar = writeSettleSidecar;
 exports.launchChromium = launchChromium;
+const fs = __importStar(require("node:fs"));
 const playwright_1 = require("playwright");
 const zod_1 = require("zod");
 /** CAPTURE.md's worked example. */
@@ -124,6 +161,65 @@ async function detectAndCompensateZoom(page, target) {
     }
     return { viewport: compensated, zoom, effective: secondMeasurement };
 }
+const SETTLE_POLL_MS = 100;
+/** Default budget for waitForSettle when a beat/tool call doesn't name its own. */
+exports.DEFAULT_SETTLE_TIMEOUT_MS = 4000;
+/**
+ * Waits for the page to reach a state safe to capture: web fonts finished
+ * swapping, every `<img>` already in the DOM finished decoding, and any
+ * finite CSS/Web Animation has landed on its end state. An infinite
+ * animation (a spinner, a pulsing loader -- `iterations: Infinity`) is
+ * recognised and excluded from the wait rather than polled forever, which
+ * would otherwise burn the whole budget on most real pages, since almost
+ * any product has one running somewhere.
+ *
+ * Polls every `SETTLE_POLL_MS` up to `timeoutMs` rather than waiting on a
+ * single combined promise, because "settled" can regress: an interaction
+ * can kick off a new finite animation after fonts/images already cleared,
+ * and the loop needs to see all three conditions true at once, not each
+ * true at some point.
+ */
+async function waitForSettle(page, timeoutMs) {
+    const start = Date.now();
+    let pending = [];
+    do {
+        pending = await page.evaluate(() => {
+            const reasons = [];
+            if (document.fonts && document.fonts.status !== "loaded")
+                reasons.push("fonts");
+            if (Array.from(document.images).some((img) => !img.complete))
+                reasons.push("images");
+            const stillAnimating = document.getAnimations().some((anim) => {
+                const timing = anim.effect?.getComputedTiming();
+                if (timing?.iterations === Infinity)
+                    return false; // spinners: excluded, not waited on
+                return anim.playState === "running" || anim.pending;
+            });
+            if (stillAnimating)
+                reasons.push("animations");
+            return reasons;
+        });
+        if (pending.length === 0) {
+            return { settled: true, timedOut: false, pending: [], waitedMs: Date.now() - start };
+        }
+        if (Date.now() - start >= timeoutMs)
+            break;
+        await page.waitForTimeout(SETTLE_POLL_MS);
+    } while (Date.now() - start < timeoutMs);
+    return { settled: false, timedOut: true, pending, waitedMs: Date.now() - start };
+}
+/** Sidecar path a settle result is written to, next to the capture artifact it describes. */
+function settleSidecarPath(outPathAbs) {
+    return `${outPathAbs}.settle.json`;
+}
+/**
+ * Persists a SettleResult next to the artifact it describes, so validate_scenes can
+ * report a timed-out settle statically (it reads scene sources and beats.json, it does
+ * not launch a browser) without re-running the capture.
+ */
+function writeSettleSidecar(outPathAbs, result) {
+    fs.writeFileSync(settleSidecarPath(outPathAbs), JSON.stringify(result, null, 2) + "\n", "utf8");
+}
 const BROWSER_NOT_INSTALLED_RE = /Executable doesn't exist at/;
 /**
  * Playwright's bundled browser binary is not installed by a plain `npm

package/dist/config.d.ts

@@ -22,12 +22,52 @@ export interface NarrationConfig {
     engine: "edge-tts" | "say" | "espeak";
     voice: string;
 }
+export interface RenderConfig {
+    /**
+     * Absolute path to a Chromium/Chrome executable, passed to the Remotion CLI as
+     * --browser-executable so it reuses that browser instead of downloading its own
+     * chrome-headless-shell. Point this at the same build capture already launches
+     * (chromium.executablePath() from @openvidstudio/capture, which is what preflight's
+     * "chromium" check reports) so a render works on a machine that has Playwright's
+     * browser installed but no route to download Remotion's separate one. No default: an
+     * unset value means "let Remotion manage its own browser," today's existing behavior.
+     */
+    browserExecutable?: string;
+}
+export type CreativeLevel = "peak" | "mid" | "literal";
+/**
+ * "standard" is every product video: a story built from real captures, with a creative level.
+ * "supernova" is a STEM lesson: a script-first, narrated 1080x1920 explanation with no real
+ * product behind it. It is a different kind of production, not a fourth creative level.
+ */
+export type ProductionMode = "standard" | "supernova";
+export declare const PRODUCTION_MODES: readonly ProductionMode[];
+export interface ProductionConfig {
+    /**
+     * Stored only when it is "supernova": a standard project's config file never gains the key.
+     * Read it through productionMode(), which gives "standard" when it is absent.
+     */
+    mode?: ProductionMode;
+    /**
+     * peak: full creative liberty (bespoke story, design system, motion language, score).
+     * mid: strong defaults, template-leaning, lighter review. literal: do exactly what was
+     * specified, nothing added. Set once per video by plan_production's intake, mirrored
+     * into that video's beats.json so a tool reading beats.json alone (not this config)
+     * still knows the level. No default: unlike every other section here, there's no sane
+     * guess for this one, it has to come from asking.
+     */
+    creativeLevel?: CreativeLevel;
+    /** Wall-clock minutes the user is willing to wait for the finished video. Also no default. */
+    timeBudgetMinutes?: number;
+}
 export interface OpenvidstudioConfig {
     hasHiggsfield: boolean;
     targetDurationSeconds: number;
     videoConfig: VideoConfig;
     capture: CaptureConfig;
     narration: NarrationConfig;
+    render: RenderConfig;
+    production: ProductionConfig;
 }
 export interface ConfigPatch {
     hasHiggsfield?: boolean;
@@ -35,6 +75,8 @@ export interface ConfigPatch {
     videoConfig?: Partial<VideoConfig>;
     capture?: Partial<CaptureConfig>;
     narration?: Partial<NarrationConfig>;
+    render?: Partial<RenderConfig>;
+    production?: Partial<ProductionConfig>;
 }
 /**
  * Defaults chosen so a bare request works with no configuration.
@@ -45,6 +87,10 @@ export interface ConfigPatch {
  * entrance without making capture feel slow.
  */
 export declare const DEFAULT_CONFIG: OpenvidstudioConfig;
+/** A project's production mode: "standard" unless its config says "supernova". */
+export declare function productionMode(config: {
+    production?: ProductionConfig;
+}): ProductionMode;
 export declare const CONFIG_FILE_NAME = "openvidstudio.config.json";
 export declare function configPath(projectRoot: string): string;
 /** Reads openvidstudio.config.json, filling in defaults for any field it omits. */

package/dist/config.js

@@ -33,12 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONFIG_FILE_NAME = exports.DEFAULT_CONFIG = void 0;
+exports.CONFIG_FILE_NAME = exports.DEFAULT_CONFIG = exports.PRODUCTION_MODES = void 0;
+exports.productionMode = productionMode;
 exports.configPath = configPath;
 exports.loadConfig = loadConfig;
 exports.writeConfig = writeConfig;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+exports.PRODUCTION_MODES = ["standard", "supernova"];
 /**
  * Defaults chosen so a bare request works with no configuration.
  *
@@ -53,7 +55,13 @@ exports.DEFAULT_CONFIG = {
     videoConfig: { fps: 30, width: 1920, height: 1080 },
     capture: { appUrl: "http://localhost:3000", width: 1440, height: 900, settleMs: 1200 },
     narration: { engine: "edge-tts", voice: "en-US-AndrewNeural" },
+    render: {},
+    production: {},
 };
+/** A project's production mode: "standard" unless its config says "supernova". */
+function productionMode(config) {
+    return config.production?.mode === "supernova" ? "supernova" : "standard";
+}
 exports.CONFIG_FILE_NAME = "openvidstudio.config.json";
 function configPath(projectRoot) {
     return path.join(projectRoot, exports.CONFIG_FILE_NAME);
@@ -68,6 +76,8 @@ function loadConfig(projectRoot) {
             videoConfig: { ...exports.DEFAULT_CONFIG.videoConfig },
             capture: { ...exports.DEFAULT_CONFIG.capture },
             narration: { ...exports.DEFAULT_CONFIG.narration },
+            render: { ...exports.DEFAULT_CONFIG.render },
+            production: { ...exports.DEFAULT_CONFIG.production },
         };
     }
     let raw;
@@ -95,6 +105,14 @@ function loadConfig(projectRoot) {
             engine: raw.narration?.engine ?? exports.DEFAULT_CONFIG.narration.engine,
             voice: raw.narration?.voice ?? exports.DEFAULT_CONFIG.narration.voice,
         },
+        render: {
+            browserExecutable: raw.render?.browserExecutable ?? exports.DEFAULT_CONFIG.render.browserExecutable,
+        },
+        production: {
+            mode: raw.production?.mode ?? exports.DEFAULT_CONFIG.production.mode,
+            creativeLevel: raw.production?.creativeLevel ?? exports.DEFAULT_CONFIG.production.creativeLevel,
+            timeBudgetMinutes: raw.production?.timeBudgetMinutes ?? exports.DEFAULT_CONFIG.production.timeBudgetMinutes,
+        },
     };
 }
 /**
@@ -123,6 +141,14 @@ function writeConfig(projectRoot, patch) {
             engine: patch.narration?.engine ?? existing.narration.engine,
             voice: patch.narration?.voice ?? existing.narration.voice,
         },
+        render: {
+            browserExecutable: patch.render?.browserExecutable ?? existing.render.browserExecutable,
+        },
+        production: {
+            mode: patch.production?.mode ?? existing.production.mode,
+            creativeLevel: patch.production?.creativeLevel ?? existing.production.creativeLevel,
+            timeBudgetMinutes: patch.production?.timeBudgetMinutes ?? existing.production.timeBudgetMinutes,
+        },
     };
     fs.mkdirSync(projectRoot, { recursive: true });
     fs.writeFileSync(configPath(projectRoot), JSON.stringify(merged, null, 2) + "\n", "utf8");

package/dist/facts.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Run records: a small JSON file per tool call that did something worth verifying later.
+ *
+ * "A claim needs a visual" is a rule this pipeline can only follow by convention while the
+ * only record of what happened is beats.json and brief.json, which say what was intended.
+ * A run record is the other half: what a tool actually did (this beat was a real capture of
+ * that URL, that render reused three cached beats and rendered two, this validator flagged
+ * these findings). collect_facts merges them into src/videos/<name>/facts.json so a check, or
+ * a person, can hold a claim up against what really ran.
+ *
+ * Writing a record is best effort and never fails the tool that calls it: a read-only project
+ * directory must not turn a successful capture into an error.
+ */
+export declare const FACT_SCHEMA_VERSION = 1;
+/** Where records go, relative to the project root. Gitignored: they are evidence, not source. */
+export declare const RUNS_DIR_REL: string;
+export interface FactRecord {
+    schemaVersion: number;
+    tool: string;
+    /** ISO timestamp the record was written. */
+    recordedAt: string;
+    /** Set when the tool is scoped to one video (render, validate, stitch). */
+    videoName?: string;
+    /** Set when the tool is scoped to one beat (every capture). */
+    beatId?: string;
+    facts: Record<string, unknown>;
+}
+export interface FactRecordInput {
+    tool: string;
+    videoName?: string;
+    beatId?: string;
+    facts: Record<string, unknown>;
+}
+/** A project-relative path with forward slashes, so a record reads the same on every platform. */
+export declare function relToProject(projectRoot: string, abs: string): string;
+/**
+ * Writes one record and returns its absolute path, or null when it could not be written. The
+ * `wx` flag plus a counter keeps two records from the same millisecond (a batch of captures)
+ * from overwriting each other.
+ */
+export declare function writeFactRecord(projectRoot: string, input: FactRecordInput): string | null;
+/** Every readable record in the runs directory, oldest first. A malformed file is skipped, not fatal. */
+export declare function readFactRecords(projectRoot: string): FactRecord[];
+/** Size in bytes of a file that should exist, or null. Records state what is on disk, not what was asked for. */
+export declare function fileBytes(abs: string): number | null;

package/dist/facts.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.RUNS_DIR_REL = exports.FACT_SCHEMA_VERSION = void 0;
+exports.relToProject = relToProject;
+exports.writeFactRecord = writeFactRecord;
+exports.readFactRecords = readFactRecords;
+exports.fileBytes = fileBytes;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Run records: a small JSON file per tool call that did something worth verifying later.
+ *
+ * "A claim needs a visual" is a rule this pipeline can only follow by convention while the
+ * only record of what happened is beats.json and brief.json, which say what was intended.
+ * A run record is the other half: what a tool actually did (this beat was a real capture of
+ * that URL, that render reused three cached beats and rendered two, this validator flagged
+ * these findings). collect_facts merges them into src/videos/<name>/facts.json so a check, or
+ * a person, can hold a claim up against what really ran.
+ *
+ * Writing a record is best effort and never fails the tool that calls it: a read-only project
+ * directory must not turn a successful capture into an error.
+ */
+exports.FACT_SCHEMA_VERSION = 1;
+/** Where records go, relative to the project root. Gitignored: they are evidence, not source. */
+exports.RUNS_DIR_REL = path.join(".openvidstudio", "runs");
+/** A project-relative path with forward slashes, so a record reads the same on every platform. */
+function relToProject(projectRoot, abs) {
+    return path.relative(projectRoot, abs).split(path.sep).join("/");
+}
+function fileSafeTimestamp(iso) {
+    return iso.replace(/[:.]/g, "-");
+}
+/**
+ * Writes one record and returns its absolute path, or null when it could not be written. The
+ * `wx` flag plus a counter keeps two records from the same millisecond (a batch of captures)
+ * from overwriting each other.
+ */
+function writeFactRecord(projectRoot, input) {
+    try {
+        const recordedAt = new Date().toISOString();
+        const record = { schemaVersion: exports.FACT_SCHEMA_VERSION, recordedAt, ...input };
+        const dir = path.join(projectRoot, exports.RUNS_DIR_REL);
+        fs.mkdirSync(dir, { recursive: true });
+        const stem = `${input.tool}-${fileSafeTimestamp(recordedAt)}`;
+        for (let n = 0; n < 1000; n++) {
+            const file = path.join(dir, `${stem}${n === 0 ? "" : `-${n}`}.json`);
+            try {
+                fs.writeFileSync(file, JSON.stringify(record, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
+                return file;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        process.stderr.write(`openvidstudio-mcp: could not write a ${input.tool} run record: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+/** Every readable record in the runs directory, oldest first. A malformed file is skipped, not fatal. */
+function readFactRecords(projectRoot) {
+    const dir = path.join(projectRoot, exports.RUNS_DIR_REL);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const rec = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+            if (rec && typeof rec.tool === "string" && typeof rec.recordedAt === "string" && rec.facts)
+                out.push(rec);
+        }
+        catch {
+            // Half-written or hand-edited; not this tool's job to diagnose.
+        }
+    }
+    return out.sort((a, b) => a.recordedAt.localeCompare(b.recordedAt));
+}
+/** Size in bytes of a file that should exist, or null. Records state what is on disk, not what was asked for. */
+function fileBytes(abs) {
+    try {
+        return fs.statSync(abs).size;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/frameDiff.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Frame comparison, shared by visual regression and docs-drift detection.
+ *
+ * Both answer the same question, "has this picture changed enough to care", and both have
+ * the same failure mode if done naively: a strict byte comparison reports a difference on
+ * every run, because an encoder is not deterministic at the pixel level and antialiasing
+ * moves under a font update. A comparison that is useful has to separate "a few pixels
+ * shifted by one value" from "this panel is a different colour now".
+ *
+ * So there are two numbers, and they say different things. `meanDelta` is the average
+ * per-pixel difference across the frame, which catches a global change (a palette swap, a
+ * brightness shift) that moves everything slightly. `changedRatio` is the fraction of
+ * pixels that moved more than a per-pixel threshold, which catches a local change (one
+ * button, one line of text) that leaves the mean almost untouched. A threshold on either
+ * alone misses half the real cases.
+ */
+export interface FrameComparison {
+    /** Average absolute per-channel difference, 0 to 1. */
+    meanDelta: number;
+    /** Fraction of pixels whose worst channel moved past the per-pixel threshold, 0 to 1. */
+    changedRatio: number;
+    /** The size both frames were normalized to before comparing. */
+    width: number;
+    height: number;
+    /** True when the inputs were not the same size, which is itself usually the finding. */
+    resized: boolean;
+}
+export interface CompareOptions {
+    /**
+     * Per-channel difference, 0-255, above which a pixel counts as changed. 12 ignores
+     * encoder noise and subpixel antialiasing while still catching any real repaint.
+     */
+    pixelThreshold?: number;
+    /**
+     * Frames are compared at this width. Downscaling first is not a shortcut: it is what
+     * makes the comparison stable, since it averages away the single-pixel antialiasing
+     * differences that are not what anyone means by "the page changed".
+     */
+    compareWidth?: number;
+    /** When set, a PNG highlighting the changed pixels in red is written here. */
+    diffPath?: string;
+}
+export declare const DEFAULT_PIXEL_THRESHOLD = 12;
+export declare const DEFAULT_COMPARE_WIDTH = 640;
+/**
+ * An image's own width in pixels, for a caller that needs to compare at native resolution
+ * rather than at DEFAULT_COMPARE_WIDTH. visual_regression's `exact` mode is the one case:
+ * downscaling first is what makes an ordinary comparison stable, and it is exactly what a
+ * gate claiming to catch ANY pixel difference must not do.
+ */
+export declare function imageWidth(file: string): Promise<number>;
+/**
+ * Compares two image files and, optionally, writes a diff image.
+ *
+ * The second frame is forced to the first's dimensions rather than refused. A page that
+ * got taller has genuinely changed, and reporting that as an error instead of as a
+ * difference would hide the finding behind a crash.
+ */
+export declare function compareFrames(beforePath: string, afterPath: string, opts?: CompareOptions): Promise<FrameComparison>;
+export interface DriftVerdict {
+    drifted: boolean;
+    reason: string;
+}
+/**
+ * Turns the two numbers into one answer.
+ *
+ * Either signal alone is enough, because they catch different shapes of change: a
+ * repainted button barely moves the mean, and a palette shift barely moves the changed
+ * pixel count.
+ */
+export declare function judgeDrift(comparison: FrameComparison, thresholds?: {
+    changedRatio?: number;
+    meanDelta?: number;
+}): DriftVerdict;

package/dist/frameDiff.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_COMPARE_WIDTH = exports.DEFAULT_PIXEL_THRESHOLD = void 0;
+exports.imageWidth = imageWidth;
+exports.compareFrames = compareFrames;
+exports.judgeDrift = judgeDrift;
+const sharp_1 = __importDefault(require("sharp"));
+exports.DEFAULT_PIXEL_THRESHOLD = 12;
+exports.DEFAULT_COMPARE_WIDTH = 640;
+/**
+ * An image's own width in pixels, for a caller that needs to compare at native resolution
+ * rather than at DEFAULT_COMPARE_WIDTH. visual_regression's `exact` mode is the one case:
+ * downscaling first is what makes an ordinary comparison stable, and it is exactly what a
+ * gate claiming to catch ANY pixel difference must not do.
+ */
+async function imageWidth(file) {
+    const { width } = await (0, sharp_1.default)(file).metadata();
+    if (!width)
+        throw new Error(`Could not read the pixel width of "${file}".`);
+    return width;
+}
+async function normalize(input, width, height) {
+    const pipeline = (0, sharp_1.default)(input).removeAlpha();
+    const resized = height ? pipeline.resize(width, height, { fit: "fill" }) : pipeline.resize({ width });
+    const { data, info } = await resized.raw().toBuffer({ resolveWithObject: true });
+    return { data, width: info.width, height: info.height };
+}
+/**
+ * Compares two image files and, optionally, writes a diff image.
+ *
+ * The second frame is forced to the first's dimensions rather than refused. A page that
+ * got taller has genuinely changed, and reporting that as an error instead of as a
+ * difference would hide the finding behind a crash.
+ */
+async function compareFrames(beforePath, afterPath, opts = {}) {
+    const threshold = opts.pixelThreshold ?? exports.DEFAULT_PIXEL_THRESHOLD;
+    const compareWidth = opts.compareWidth ?? exports.DEFAULT_COMPARE_WIDTH;
+    const before = await normalize(beforePath, compareWidth);
+    const beforeMeta = await (0, sharp_1.default)(beforePath).metadata();
+    const afterMeta = await (0, sharp_1.default)(afterPath).metadata();
+    const after = await normalize(afterPath, before.width, before.height);
+    const pixels = before.width * before.height;
+    const channels = 3;
+    let sum = 0;
+    let changed = 0;
+    const diff = opts.diffPath ? Buffer.alloc(pixels * channels) : null;
+    for (let p = 0; p < pixels; p++) {
+        const i = p * channels;
+        const dr = Math.abs(before.data[i] - after.data[i]);
+        const dg = Math.abs(before.data[i + 1] - after.data[i + 1]);
+        const db = Math.abs(before.data[i + 2] - after.data[i + 2]);
+        sum += dr + dg + db;
+        const worst = Math.max(dr, dg, db);
+        const isChanged = worst > threshold;
+        if (isChanged)
+            changed++;
+        if (diff) {
+            if (isChanged) {
+                diff[i] = 255;
+                diff[i + 1] = 32;
+                diff[i + 2] = 32;
+            }
+            else {
+                // Unchanged pixels stay visible but dimmed, so the highlight reads as a mark on
+                // the page rather than as a red shape floating on nothing.
+                const grey = Math.round((after.data[i] + after.data[i + 1] + after.data[i + 2]) / 3 / 3);
+                diff[i] = grey;
+                diff[i + 1] = grey;
+                diff[i + 2] = grey;
+            }
+        }
+    }
+    if (diff && opts.diffPath) {
+        await (0, sharp_1.default)(diff, { raw: { width: before.width, height: before.height, channels: 3 } })
+            .png()
+            .toFile(opts.diffPath);
+    }
+    return {
+        meanDelta: sum / (pixels * channels) / 255,
+        changedRatio: changed / pixels,
+        width: before.width,
+        height: before.height,
+        resized: beforeMeta.width !== afterMeta.width || beforeMeta.height !== afterMeta.height,
+    };
+}
+/**
+ * Turns the two numbers into one answer.
+ *
+ * Either signal alone is enough, because they catch different shapes of change: a
+ * repainted button barely moves the mean, and a palette shift barely moves the changed
+ * pixel count.
+ */
+function judgeDrift(comparison, thresholds = {}) {
+    const changedLimit = thresholds.changedRatio ?? 0.02;
+    const meanLimit = thresholds.meanDelta ?? 0.01;
+    if (comparison.resized) {
+        return {
+            drifted: true,
+            reason: "the frame is a different size than the reference, which is a layout change by itself",
+        };
+    }
+    if (comparison.changedRatio > changedLimit) {
+        return {
+            drifted: true,
+            reason: `${(comparison.changedRatio * 100).toFixed(2)}% of pixels moved, past the ` +
+                `${(changedLimit * 100).toFixed(2)}% limit`,
+        };
+    }
+    if (comparison.meanDelta > meanLimit) {
+        return {
+            drifted: true,
+            reason: `the average pixel moved ${(comparison.meanDelta * 100).toFixed(2)}%, past the ` +
+                `${(meanLimit * 100).toFixed(2)}% limit, which is the shape of a palette or brightness change`,
+        };
+    }
+    return { drifted: false, reason: "within both thresholds" };
+}