@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/diffBeats.js

@@ -0,0 +1,226 @@
+"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.diffBeatsLogic = diffBeatsLogic;
+exports.runDiffBeats = runDiffBeats;
+exports.registerDiffBeats = registerDiffBeats;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const mcp_1 = require("./mcp");
+/**
+ * Turns an edited beats.json draft into a concrete rerun plan against the version
+ * already on disk, instead of leaving the calling agent to eyeball a JSON diff and
+ * guess what still needs redoing. Every capture/scaffold tool is already independently
+ * callable per beat (capture_screenshot, capture_screen_recording, scaffold_scene with
+ * overwrite: true); this tool is what tells the agent which beat ids actually need one
+ * of those calls after an edit, and which don't, so patching one field doesn't turn
+ * into re-running the whole pipeline. render_video always re-renders the full
+ * composition (Remotion has no partial-render mode), so `rerenderNeeded` is a single
+ * yes/no covering the whole video, not a per-beat field.
+ */
+const CAPTURE_RELEVANT_METHODS = new Set(["screenshot", "recording", "higgsfield"]);
+const RESCAFFOLD_FIELDS = new Set(["duration", "vo", "visual", "transition"]);
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const ak = Object.keys(a).sort();
+        const bk = Object.keys(b).sort();
+        if (ak.length !== bk.length || ak.some((k, i) => k !== bk[i]))
+            return false;
+        return ak.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+function indexById(beats) {
+    const map = new Map();
+    if (!Array.isArray(beats))
+        return map;
+    for (const raw of beats) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const beat = raw;
+        if (typeof beat.id === "string" && beat.id.length > 0)
+            map.set(beat.id, beat);
+    }
+    return map;
+}
+/** Mirrors PIPELINE.md's Asset conventions table / PLANNING.md §4.5's artifacts override. */
+function artifactPaths(beat, beatId) {
+    const artifacts = (beat?.artifacts ?? {});
+    return {
+        screenshotPath: typeof artifacts.screenshotPath === "string" ? artifacts.screenshotPath : path.join("public", "images", `${beatId}.png`),
+        recordingPath: typeof artifacts.recordingPath === "string" ? artifacts.recordingPath : path.join("public", "video", `${beatId}.mp4`),
+        voPath: typeof artifacts.voPath === "string" ? artifacts.voPath : path.join("public", "audio", "vo", `${beatId}.mp3`),
+    };
+}
+function artifactPresence(beat, beatId, projectRoot) {
+    const p = artifactPaths(beat, beatId);
+    const exists = (rel) => {
+        try {
+            return fs.existsSync(path.join(projectRoot, rel));
+        }
+        catch {
+            return false;
+        }
+    };
+    return { screenshot: exists(p.screenshotPath), recording: exists(p.recordingPath), vo: exists(p.voPath) };
+}
+/**
+ * Pure diff over two already-parsed beats.json documents. `projectRoot` is only used
+ * to check which artifact files actually exist on disk right now (a fresh checkout or
+ * a beat that's never been captured reports every path absent, which is correct, not
+ * a bug); it never reads oldBeatsJson/newBeatsJson from disk itself.
+ */
+function diffBeatsLogic(oldBeatsJson, newBeatsJson, projectRoot) {
+    const oldRoot = (typeof oldBeatsJson === "object" && oldBeatsJson !== null ? oldBeatsJson : {});
+    const newRoot = (typeof newBeatsJson === "object" && newBeatsJson !== null ? newBeatsJson : {});
+    const oldBeats = indexById(oldRoot.beats);
+    const newBeats = indexById(newRoot.beats);
+    const fpsChanged = !deepEqual(oldRoot.fps, newRoot.fps);
+    const titleChanged = !deepEqual(oldRoot.title, newRoot.title);
+    const ids = new Set([...oldBeats.keys(), ...newBeats.keys()]);
+    const beats = [];
+    for (const id of ids) {
+        const oldBeat = oldBeats.get(id);
+        const newBeat = newBeats.get(id);
+        if (!oldBeat && newBeat) {
+            const captureMethod = String(newBeat.visual?.captureMethod ?? "");
+            beats.push({
+                id,
+                status: "added",
+                changedFields: [],
+                needsRecapture: CAPTURE_RELEVANT_METHODS.has(captureMethod),
+                needsRescaffold: true,
+                artifactsOnDisk: artifactPresence(newBeat, id, projectRoot),
+            });
+            continue;
+        }
+        if (oldBeat && !newBeat) {
+            beats.push({
+                id,
+                status: "removed",
+                changedFields: [],
+                needsRecapture: false,
+                needsRescaffold: false,
+                artifactsOnDisk: { screenshot: false, recording: false, vo: false },
+            });
+            continue;
+        }
+        if (!oldBeat || !newBeat)
+            continue;
+        const changedFields = [];
+        for (const field of ["start", "duration", "vo", "transition"]) {
+            if (!deepEqual(oldBeat[field], newBeat[field]))
+                changedFields.push(field);
+        }
+        if (!deepEqual(oldBeat.visual, newBeat.visual))
+            changedFields.push("visual");
+        if (!deepEqual(oldBeat.artifacts, newBeat.artifacts))
+            changedFields.push("artifacts");
+        const status = changedFields.length > 0 ? "changed" : "unchanged";
+        const captureMethod = String(newBeat.visual?.captureMethod ?? "");
+        const needsRecapture = changedFields.includes("visual") && CAPTURE_RELEVANT_METHODS.has(captureMethod);
+        const needsRescaffold = changedFields.some((f) => RESCAFFOLD_FIELDS.has(f));
+        beats.push({
+            id,
+            status,
+            changedFields,
+            needsRecapture,
+            needsRescaffold,
+            artifactsOnDisk: artifactPresence(newBeat, id, projectRoot),
+        });
+    }
+    const summary = {
+        added: beats.filter((b) => b.status === "added").length,
+        removed: beats.filter((b) => b.status === "removed").length,
+        changed: beats.filter((b) => b.status === "changed").length,
+        unchanged: beats.filter((b) => b.status === "unchanged").length,
+    };
+    const rerenderNeeded = fpsChanged || summary.added + summary.removed + summary.changed > 0;
+    return { fpsChanged, titleChanged, beats, summary, rerenderNeeded };
+}
+function runDiffBeats(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const oldPath = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    let oldBeatsJson = { beats: [] };
+    let oldBeatsFileFound = false;
+    try {
+        oldBeatsJson = JSON.parse(fs.readFileSync(oldPath, "utf8"));
+        oldBeatsFileFound = true;
+    }
+    catch {
+        // No persisted beats.json yet: every beat in newBeatsJson diffs as "added", which is correct
+        // for a first draft (nothing to rerun selectively, the whole pipeline runs once).
+    }
+    const result = diffBeatsLogic(oldBeatsJson, input.newBeatsJson, projectRoot);
+    return { ...result, oldBeatsFileFound };
+}
+function registerDiffBeats(server) {
+    server.registerTool("diff_beats", {
+        title: "Turn an edited beats.json draft into a per-beat rerun plan",
+        description: "Compares a new beats.json draft (not yet written to disk) against the version already persisted " +
+            "at src/videos/<videoName>/beats.json, and returns a per-beat status (added/removed/unchanged/" +
+            "changed, with which fields changed) plus two rerun signals per beat: needsRecapture (true when " +
+            "visual.* changed on a screenshot/recording/higgsfield beat, meaning capture_screenshot/" +
+            "capture_screen_recording/import_higgsfield_clip should run again for that beat id) and " +
+            "needsRescaffold (true when duration/vo/visual/transition changed, meaning scaffold_scene should " +
+            "rerun with overwrite: true). Also reports artifactsOnDisk per beat (whether its screenshot/" +
+            "recording/vo file actually exists right now, per PIPELINE.md's convention paths or the beat's own " +
+            "artifacts override) and a single whole-video rerenderNeeded flag, since Remotion has no partial-" +
+            "render mode and always renders the full composition. If no beats.json exists yet at that path, " +
+            "every beat in the draft comes back \"added\" (a first draft has nothing to selectively rerun). " +
+            "This tool never writes anything: it's read-only comparison, meant to run before write_beats_file " +
+            "so the agent (and the dev, at the approval gate) know exactly which capture/scaffold calls the " +
+            "edit actually requires instead of redoing the whole pipeline for a one-field change.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            newBeatsJson: zod_1.z.unknown().describe("The edited beats.json draft (an object), not yet written to disk."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("diff_beats", () => runDiffBeats(input)));
+}

package/dist/tools/docsDrift.d.ts

@@ -0,0 +1,84 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Interaction, type Viewport } from "@openvidstudio/capture";
+/**
+ * Re-captures the pages a video documents and reports which clips no longer match them.
+ *
+ * The problem this solves is well known and nobody solves it: a docs video is accurate the
+ * day it is recorded and quietly wrong three releases later, because re-recording it by
+ * hand is expensive enough that nobody does it until a user complains. Once capture is
+ * automated, checking is cheap, and checking is most of the value: knowing which thirty
+ * seconds of a ten minute video are stale is nearly as useful as re-rendering them, and it
+ * is what makes re-rendering them affordable.
+ *
+ * The binding is docs route to beat id to reference frame. The reference is the frame the
+ * beat was built from, which is already on disk as the beat's capture. Nothing new has to
+ * be stored for a beat that was captured from a browser in the first place.
+ */
+export interface DriftBinding {
+    beatId: string;
+    url: string;
+    /** Replayed before capture, same as the original. A page behind a click needs the click. */
+    interactions?: Interaction[];
+    /**
+     * The CSS viewport to re-capture at. Defaults to the reference's own capture sidecar
+     * (`<referencePath>.capture.json`, written by capture_screenshot/capture_screen_recording);
+     * pass this explicitly for a reference that has no sidecar and isn't caught by the
+     * legacy-heuristic fallback (see resolveCaptureSettings), or for a beat captured with
+     * cropSelector, whose reference is a crop of a page rather than a view of one.
+     */
+    viewport?: Viewport;
+    /** Pixels per CSS pixel to re-capture at. Defaults to the sidecar's own value, else 2. */
+    deviceScaleFactor?: number;
+    /** Defaults to the beat's own capture at public/images/<beatId>.png. */
+    referencePath?: string;
+}
+export interface DocsDriftInput {
+    projectRoot?: string;
+    videoName: string;
+    bindings?: DriftBinding[];
+    outDir?: string;
+    changedRatioThreshold?: number;
+    meanDeltaThreshold?: number;
+}
+export interface DriftFinding {
+    beatId: string;
+    url: string;
+    drifted: boolean;
+    reason: string;
+    changedRatio: number;
+    meanDelta: number;
+    referencePath: string;
+    currentPath: string;
+    diffPath: string;
+}
+export interface DocsDriftResult {
+    ok: boolean;
+    checked: number;
+    driftedBeats: string[];
+    findings: DriftFinding[];
+    /** What to do about it, in the pipeline's own terms. */
+    nextSteps: string[];
+}
+interface BeatLike {
+    id: string;
+    visual?: {
+        captureMethod?: string;
+        source?: string;
+        url?: string;
+        interactions?: Interaction[];
+    };
+    artifacts?: {
+        screenshotPath?: string;
+    };
+}
+/**
+ * Bindings inferred from the manifest, for the common case where nobody wrote any.
+ *
+ * Every browser screenshot beat already records the URL it came from and the interactions
+ * that got it there, which is exactly a binding. Asking someone to restate that in a second
+ * file would be asking them to keep two copies of one fact in sync.
+ */
+export declare function inferBindings(beats: BeatLike[]): DriftBinding[];
+export declare function runDocsDrift(input: DocsDriftInput): Promise<DocsDriftResult>;
+export declare function registerDocsDrift(server: McpServer): void;
+export {};

package/dist/tools/docsDrift.js

@@ -0,0 +1,275 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferBindings = inferBindings;
+exports.runDocsDrift = runDocsDrift;
+exports.registerDocsDrift = registerDocsDrift;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const sharp_1 = __importDefault(require("sharp"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const capture_1 = require("@openvidstudio/capture");
+const frameDiff_1 = require("../frameDiff");
+const mcp_1 = require("./mcp");
+/**
+ * Bindings inferred from the manifest, for the common case where nobody wrote any.
+ *
+ * Every browser screenshot beat already records the URL it came from and the interactions
+ * that got it there, which is exactly a binding. Asking someone to restate that in a second
+ * file would be asking them to keep two copies of one fact in sync.
+ */
+function inferBindings(beats) {
+    return beats
+        .filter((b) => b.visual?.captureMethod === "screenshot" &&
+        (b.visual?.source ?? "browser") === "browser" &&
+        typeof b.visual?.url === "string" &&
+        b.visual.url.length > 0)
+        .map((b) => ({
+        beatId: b.id,
+        url: b.visual.url,
+        interactions: b.visual?.interactions,
+        referencePath: b.artifacts?.screenshotPath ?? path.join("public", "images", `${b.id}.png`),
+    }));
+}
+/**
+ * A common desktop CSS viewport a legacy (pre-sidecar) reference might have been captured
+ * at. Only ever checked against HALF the reference PNG's own pixel size, and only when that
+ * halving is exact -- this is deliberately the one narrow, checkable guess this tool is
+ * allowed to make. Guessing a viewport from the reference's full pixel size (treating a
+ * 2880x1800 PNG as a 2880x1800 viewport) is the exact bug this whole binding exists to kill.
+ */
+const COMMON_VIEWPORTS = [
+    capture_1.DEFAULT_VIEWPORT, // 1600x1000
+    { width: 1920, height: 1080 },
+    { width: 1440, height: 900 },
+    { width: 1366, height: 768 },
+    { width: 1280, height: 800 },
+    { width: 1280, height: 720 },
+    { width: 1536, height: 864 },
+    { width: 1600, height: 900 },
+];
+/**
+ * Works out what CSS viewport and scale to re-capture a reference frame at, in the same
+ * order of trust every time: an explicit binding, then the sidecar the original capture
+ * wrote, then (only for a legacy asset with neither) the one narrow heuristic above. Never
+ * the reference image's own pixel size read directly as a viewport -- that was the bug.
+ */
+async function resolveCaptureSettings(binding, referenceAbs) {
+    if (binding.viewport) {
+        return {
+            viewport: binding.viewport,
+            deviceScaleFactor: binding.deviceScaleFactor ?? capture_1.DEFAULT_DEVICE_SCALE,
+            interactions: binding.interactions,
+            source: "explicit",
+        };
+    }
+    const sidecar = (0, capture_1.readCaptureSidecar)(referenceAbs);
+    if (sidecar) {
+        return {
+            viewport: sidecar.viewport,
+            deviceScaleFactor: sidecar.deviceScaleFactor,
+            interactions: binding.interactions ?? sidecar.interactions,
+            source: "sidecar",
+        };
+    }
+    const meta = await (0, sharp_1.default)(referenceAbs).metadata();
+    if (meta.width && meta.height && meta.width % 2 === 0 && meta.height % 2 === 0) {
+        const halved = { width: meta.width / 2, height: meta.height / 2 };
+        const isCommon = COMMON_VIEWPORTS.some((v) => v.width === halved.width && v.height === halved.height);
+        if (isCommon) {
+            return {
+                viewport: halved,
+                deviceScaleFactor: 2,
+                interactions: binding.interactions,
+                source: "legacy-heuristic",
+            };
+        }
+    }
+    throw new Error(`Beat "${binding.beatId}" has no capture sidecar at ${(0, capture_1.captureSidecarPath)(referenceAbs)}, and its ` +
+        `reference image's pixel size (${meta.width ?? "?"}x${meta.height ?? "?"}) is not exactly double a ` +
+        `common CSS viewport, so there is no safe way to guess the viewport it was captured at -- treating the ` +
+        `pixel size itself as the viewport is exactly the bug this binding exists to avoid. Pass an explicit ` +
+        `viewport (and deviceScaleFactor, if not 2) in this binding.`);
+}
+async function runDocsDrift(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const beatsPath = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsPath))
+        throw new Error(`${beatsPath} does not exist.`);
+    const doc = JSON.parse(fs.readFileSync(beatsPath, "utf8"));
+    const beats = doc.beats ?? [];
+    const bindings = input.bindings?.length ? input.bindings : inferBindings(beats);
+    if (bindings.length === 0) {
+        throw new Error(`No drift bindings. This video has no browser screenshot beat carrying a url, and none were passed ` +
+            `in. Drift detection re-captures a page and compares it to the frame the beat was built from, so it ` +
+            `needs to know which page each beat came from.`);
+    }
+    const outRel = input.outDir ?? path.join("output", "drift", videoName);
+    const outAbs = path.join(projectRoot, outRel);
+    fs.mkdirSync(outAbs, { recursive: true });
+    const findings = [];
+    const browser = await (0, capture_1.launchChromium)();
+    try {
+        for (const binding of bindings) {
+            const referenceRel = binding.referencePath ?? path.join("public", "images", `${binding.beatId}.png`);
+            const referenceAbs = path.join(projectRoot, referenceRel);
+            if (!fs.existsSync(referenceAbs)) {
+                throw new Error(`Beat "${binding.beatId}" has no reference frame at ${referenceRel}. There is nothing to compare ` +
+                    `the live page against, so this is a missing capture rather than drift.`);
+            }
+            // The CSS viewport and scale to re-capture at come from the reference's own capture
+            // sidecar (or an explicit binding, or the legacy heuristic) -- never from the
+            // reference PNG's pixel size read directly as a viewport. See resolveCaptureSettings.
+            const { viewport: target, deviceScaleFactor, interactions } = await resolveCaptureSettings(binding, referenceAbs);
+            // deviceScaleFactor has to be set at context creation, matching capture_screenshot's
+            // own newContext({ deviceScaleFactor }) -- a plain browser.newPage() context defaults
+            // to 1x, which would make every re-capture a different pixel size than a reference
+            // taken at the pipeline's default of 2x even once the CSS viewport itself is right.
+            const context = await browser.newContext({ deviceScaleFactor });
+            try {
+                const page = await context.newPage();
+                try {
+                    await page.setViewportSize(target);
+                    await page.goto(binding.url, { waitUntil: "networkidle" });
+                    // Same zoom compensation the original capture used, measured fresh on whatever
+                    // machine is running this check rather than replayed from a stored ratio --
+                    // CAPTURE.md is explicit that the ratio differs per machine/profile. Skipping
+                    // this would make every comparison a comparison of two different viewports.
+                    await (0, capture_1.detectAndCompensateZoom)(page, target);
+                    await (0, capture_1.replayInteractions)(page, interactions);
+                    const currentRel = path.join(outRel, `${binding.beatId}.png`);
+                    // "device", not the default, so the re-capture lands on the reference's own pixel
+                    // size (viewport * deviceScaleFactor) rather than being resampled to CSS size --
+                    // matching scale is what "compare at the reference's own pixel size" means here.
+                    await page.screenshot({
+                        path: path.join(projectRoot, currentRel),
+                        fullPage: false,
+                        scale: "device",
+                    });
+                    const diffRel = path.join(outRel, `${binding.beatId}.diff.png`);
+                    const comparison = await (0, frameDiff_1.compareFrames)(referenceAbs, path.join(projectRoot, currentRel), {
+                        diffPath: path.join(projectRoot, diffRel),
+                    });
+                    const verdict = (0, frameDiff_1.judgeDrift)(comparison, {
+                        changedRatio: input.changedRatioThreshold,
+                        meanDelta: input.meanDeltaThreshold,
+                    });
+                    findings.push({
+                        beatId: binding.beatId,
+                        url: binding.url,
+                        drifted: verdict.drifted,
+                        reason: verdict.reason,
+                        changedRatio: comparison.changedRatio,
+                        meanDelta: comparison.meanDelta,
+                        referencePath: referenceRel,
+                        currentPath: currentRel,
+                        diffPath: diffRel,
+                    });
+                }
+                finally {
+                    await page.close();
+                }
+            }
+            finally {
+                await context.close();
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    const driftedBeats = findings.filter((f) => f.drifted).map((f) => f.beatId);
+    const nextSteps = driftedBeats.length === 0
+        ? ["Nothing has drifted. The clips still match the pages they document."]
+        : [
+            `Re-capture the drifted beats: capture_screenshot for ${driftedBeats.join(", ")}.`,
+            `Then render_video with incremental: true, which re-renders only those beats rather than the ` +
+                `whole composition.`,
+            `The diff images in ${outRel} show which part of each page moved, which is usually enough to tell ` +
+                `an intended redesign from an accident.`,
+        ];
+    return { ok: driftedBeats.length === 0, checked: findings.length, driftedBeats, findings, nextSteps };
+}
+function registerDocsDrift(server) {
+    server.registerTool("docs_drift", {
+        title: "Find the clips that no longer match the pages they document",
+        description: "Re-captures the pages a video's beats were built from and compares them against the frames that " +
+            "were captured at the time, reporting which beats have gone stale. A docs video is accurate the day " +
+            "it is recorded and quietly wrong three releases later, because re-recording by hand is expensive " +
+            "enough that nobody does it until a user complains. Checking is cheap once capture is automated, and " +
+            "knowing which thirty seconds of a ten minute video are stale is most of the value. Bindings are " +
+            "inferred from the manifest by default: every browser screenshot beat already records its url and " +
+            "the interactions that got there, which is exactly a binding, so keeping a second copy of that in " +
+            "another file would just be two things to keep in sync. The CSS viewport and deviceScaleFactor to " +
+            "re-capture at come from the reference's own `<referencePath>.capture.json` sidecar (written by " +
+            "capture_screenshot/capture_screen_recording), never from the reference PNG's pixel size read " +
+            "directly as a viewport -- that produces a different, usually much wider layout than the one that " +
+            "was actually captured, and reports drift on pages that never changed. A legacy reference with no " +
+            "sidecar falls back to one narrow, checkable guess (its pixel size is exactly double a common CSS " +
+            "viewport) and otherwise requires viewport (and deviceScaleFactor, if not 2) in an explicit binding, " +
+            "same as a beat captured with cropSelector, whose reference is a crop of a page rather than a view " +
+            "of one. The re-capture replays the same interactions and the same zoom compensation, measured fresh " +
+            "rather than reused, since CAPTURE.md is explicit that the ratio differs per machine/profile. Output " +
+            "is a per-beat verdict, a diff image showing where the page moved, and " +
+            "the exact next commands: re-capture the drifted beats, then render with incremental so only those " +
+            "beats are re-rendered. Run it on a schedule.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            bindings: zod_1.z
+                .array(zod_1.z.object({
+                beatId: zod_1.z.string().min(1),
+                url: zod_1.z.string().url(),
+                interactions: zod_1.z.array(capture_1.interactionSchema).optional(),
+                viewport: capture_1.viewportSchema
+                    .optional()
+                    .describe("Overrides the reference's capture sidecar / legacy heuristic. Required for a reference " +
+                    "with neither (e.g. captured with cropSelector)."),
+                deviceScaleFactor: zod_1.z.number().positive().optional().describe("Defaults to the sidecar's value, else 2."),
+                referencePath: zod_1.z.string().optional(),
+            }))
+                .optional()
+                .describe("Defaults to every browser screenshot beat in the manifest that carries a url."),
+            outDir: zod_1.z.string().optional(),
+            changedRatioThreshold: zod_1.z.number().positive().optional(),
+            meanDeltaThreshold: zod_1.z.number().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("docs_drift", () => runDocsDrift(input)));
+}