@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/validateBeats.js

@@ -1,18 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.READING_OVERHEAD_SEC = exports.MAX_READING_WORDS_PER_SEC = exports.MAX_PACE = exports.MIN_PACE = void 0;
+exports.wordCount = wordCount;
+exports.voPaceCheck = voPaceCheck;
 exports.validateBeatsLogic = validateBeatsLogic;
+exports.runValidateBeats = runValidateBeats;
 exports.registerValidateBeats = registerValidateBeats;
 const zod_1 = require("zod");
-const capture_1 = require("../capture");
+const capture_1 = require("@openvidstudio/capture");
 const mcp_1 = require("./mcp");
+const util_1 = require("../util");
+const facts_1 = require("../facts");
 const EM_DASH = "—";
-const MIN_PACE = 2.3;
-const MAX_PACE = 2.9;
-const CAPTURE_METHODS = ["screenshot", "recording", "dom-demo", "higgsfield"];
+/** Fewer beats than this is not a rhythm yet, so shot lengths are not compared. */
+const RHYTHM_MIN_BEATS = 4;
+/** The longest beat should be at least this many times the shortest, or the shots read as evenly spaced ticks. */
+const RHYTHM_MIN_SPREAD = 2.5;
+exports.MIN_PACE = 2.3;
+exports.MAX_PACE = 2.9;
+/** SCRIPT.md's reading-time budget for onScreenText on a narration:"none" beat. */
+exports.MAX_READING_WORDS_PER_SEC = 3.5;
+exports.READING_OVERHEAD_SEC = 0.8;
+const NARRATION_MODES = ["voice", "none"];
+const CREATIVE_LEVELS = ["peak", "mid", "literal"];
+const PRODUCTION_MODES = ["standard", "supernova"];
+const CAPTURE_METHODS = ["screenshot", "recording", "dom-demo", "higgsfield", "existing-asset"];
+const TRANSITIONS = ["cut", "whip", "fade", "push", "wipe", "light-leak"];
+const ARTIFACT_KEYS = ["screenshotPath", "recordingPath", "voPath", "terminalPath"];
+const CAPTURE_SOURCES = ["browser", "desktop", "mobile", "terminal"];
+const CROP_FOCUSES = ["left", "center", "right"];
+const LANGUAGE_TAG = /^[A-Za-z]{2,8}(-[A-Za-z0-9]{2,8})*$/;
+const MOBILE_DEVICES = ["android", "ios-simulator"];
+/** Android's screenrecord truncates silently past this, so a longer beat is a latent bug. */
+const ANDROID_MAX_SECONDS = 180;
 function wordCount(text) {
     const trimmed = text.trim();
     return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
 }
+/**
+ * SCRIPT.md's pacing rule for one spoken line: 2.3 to 2.9 words per second over the beat's length.
+ * `message` is the failure to report, or null when the line is inside the budget. validate_beats and
+ * check_script both read the budget from here, so there is one number.
+ */
+function voPaceCheck(vo, seconds) {
+    const words = wordCount(vo);
+    const pace = words / seconds;
+    const message = pace < exports.MIN_PACE || pace > exports.MAX_PACE
+        ? `VO pace ${pace.toFixed(2)} words/sec is outside the ${exports.MIN_PACE}-${exports.MAX_PACE} words/sec ` +
+            `budget (${words} words over ${seconds.toFixed(2)}s, per SCRIPT.md)`
+        : null;
+    return { words, pace, message };
+}
 /**
  * Mechanically enforces packages/docs/PLANNING.md §4 (captureMethod field spec) and
  * packages/docs/SCRIPT.md (VO pacing, no em dashes). Takes the drafted beats.json
@@ -22,19 +60,52 @@ function wordCount(text) {
  */
 function validateBeatsLogic(beatsJson) {
     const errors = [];
+    const warnings = [];
     if (typeof beatsJson !== "object" || beatsJson === null) {
-        return { valid: false, errors: ["beatsJson must be an object"] };
+        return { valid: false, errors: ["beatsJson must be an object"], warnings: [] };
     }
     const root = beatsJson;
     const fps = typeof root.fps === "number" && root.fps > 0 ? root.fps : 30;
+    const narrationRaw = root.narration;
+    if (narrationRaw !== undefined && !NARRATION_MODES.includes(narrationRaw)) {
+        errors.push(`narration must be one of ${NARRATION_MODES.map((n) => `"${n}"`).join(", ")} (omit for "voice")`);
+    }
+    const narration = narrationRaw === "none" ? "none" : "voice";
+    // Mirrored from openvidstudio.config.json's production field (PLANNING.md §0) so a tool
+    // reading beats.json alone still knows the level a video was planned at. Shape-checked
+    // only: this file doesn't enforce what a level implies about content, that's the agent's
+    // job at authoring time (plan_production, scaffold_scene's template-vs-custom choice).
+    if (root.production !== undefined) {
+        if (typeof root.production !== "object" || root.production === null || Array.isArray(root.production)) {
+            errors.push(`production must be an object: { mode?, creativeLevel?, timeBudgetMinutes? }`);
+        }
+        else {
+            const production = root.production;
+            if (production.mode !== undefined && !PRODUCTION_MODES.includes(production.mode)) {
+                errors.push(`production.mode must be one of ${PRODUCTION_MODES.map((m) => `"${m}"`).join(", ")} (omit for "standard")`);
+            }
+            if (production.mode === "supernova" && narrationRaw === "none") {
+                warnings.push(`production.mode is "supernova" but narration is "none": a lesson is carried by its voice, so a silent one has nothing to teach with.`);
+            }
+            if (production.creativeLevel !== undefined &&
+                !CREATIVE_LEVELS.includes(production.creativeLevel)) {
+                errors.push(`production.creativeLevel must be one of ${CREATIVE_LEVELS.map((l) => `"${l}"`).join(", ")}`);
+            }
+            if (production.timeBudgetMinutes !== undefined &&
+                (typeof production.timeBudgetMinutes !== "number" || production.timeBudgetMinutes <= 0)) {
+                errors.push(`production.timeBudgetMinutes must be a positive number`);
+            }
+        }
+    }
     if (!Array.isArray(root.beats)) {
-        return { valid: false, errors: ["beatsJson.beats must be an array"] };
+        return { valid: false, errors: ["beatsJson.beats must be an array"], warnings: [] };
     }
     const beats = root.beats;
     if (beats.length === 0) {
         errors.push("beats array is empty");
     }
     const seenIds = new Set();
+    const lengths = [];
     let expectedStart = 0;
     beats.forEach((raw, i) => {
         if (typeof raw !== "object" || raw === null) {
@@ -66,32 +137,128 @@ function validateBeatsLogic(beatsJson) {
         if (!hasDuration) {
             errors.push(`${label}: missing or invalid "duration" (must be a positive number)`);
         }
+        else {
+            lengths.push({ id: typeof beat.id === "string" ? beat.id : `beat[${i}]`, duration: duration });
+        }
         if (hasStart && hasDuration) {
             expectedStart = start + duration;
         }
         else if (hasDuration) {
             expectedStart += duration;
         }
+        // C5: an explicit scene file path, for a hand-authored bespoke scene that doesn't live
+        // at stitch_composition's `./scenes/<PascalId>` convention. Shape-checked only -- whether
+        // the file actually exists is stitch_composition's own concern at stitch time, not
+        // validate_beats's (this runs on drafted beats.json, often before a scene is written).
+        const scene = beat.scene;
+        if (scene !== undefined && (typeof scene !== "string" || scene.length === 0)) {
+            errors.push(`${label}: "scene" must be a non-empty string if present (a path relative to the video directory)`);
+        }
         const vo = beat.vo;
-        if (typeof vo !== "string" || vo.length === 0) {
-            errors.push(`${label}: missing or invalid "vo"`);
+        const hasVo = typeof vo === "string" && vo.length > 0;
+        if (narration === "voice") {
+            if (!hasVo) {
+                errors.push(`${label}: missing or invalid "vo"`);
+            }
+            else {
+                if (vo.includes(EM_DASH)) {
+                    errors.push(`${label}: "vo" contains an em dash, rewrite with commas/periods`);
+                }
+                if (hasDuration) {
+                    const seconds = duration / fps;
+                    if (seconds > 0) {
+                        const pace = voPaceCheck(vo, seconds);
+                        if (pace.message !== null)
+                            errors.push(`${label}: ${pace.message}`);
+                    }
+                }
+            }
         }
         else {
-            if (vo.includes(EM_DASH)) {
+            // narration: "none". vo is optional and, if present at all, not held to the spoken
+            // words/sec budget -- nothing is going to speak it. onScreenText is the thing that
+            // actually needs a duration check here, against reading time rather than speech pace.
+            if (hasVo && vo.includes(EM_DASH)) {
                 errors.push(`${label}: "vo" contains an em dash, rewrite with commas/periods`);
             }
-            if (hasDuration) {
-                const seconds = duration / fps;
-                if (seconds > 0) {
-                    const words = wordCount(vo);
-                    const pace = words / seconds;
-                    if (pace < MIN_PACE || pace > MAX_PACE) {
-                        errors.push(`${label}: VO pace ${pace.toFixed(2)} words/sec is outside the ${MIN_PACE}-${MAX_PACE} words/sec ` +
-                            `budget (${words} words over ${seconds.toFixed(2)}s, per SCRIPT.md)`);
+            const onScreenText = beat.onScreenText;
+            if (onScreenText !== undefined) {
+                if (typeof onScreenText !== "string" || onScreenText.length === 0) {
+                    errors.push(`${label}: "onScreenText" must be a non-empty string if present`);
+                }
+                else {
+                    if (onScreenText.includes(EM_DASH)) {
+                        errors.push(`${label}: "onScreenText" contains an em dash, rewrite with commas/periods`);
+                    }
+                    if (hasDuration) {
+                        const seconds = duration / fps;
+                        const words = wordCount(onScreenText);
+                        const minSeconds = words / exports.MAX_READING_WORDS_PER_SEC + exports.READING_OVERHEAD_SEC;
+                        if (seconds < minSeconds) {
+                            errors.push(`${label}: onScreenText needs at least ${minSeconds.toFixed(2)}s to read (${words} words at ` +
+                                `${exports.MAX_READING_WORDS_PER_SEC} words/sec plus ${exports.READING_OVERHEAD_SEC}s overhead), beat is only ` +
+                                `${seconds.toFixed(2)}s`);
+                        }
+                    }
+                }
+            }
+        }
+        // Translated narration lines. Only the shape is checked here, never the pacing: the
+        // 2.3-2.9 words/sec budget in SCRIPT.md is an English number, and the same sentence is
+        // routinely 20 to 30 percent longer in German or Hindi. Holding a translation to
+        // English pacing would reject correct translations.
+        const translations = beat.voTranslations;
+        if (translations !== undefined) {
+            if (typeof translations !== "object" || translations === null || Array.isArray(translations)) {
+                errors.push(`${label}: "voTranslations" must be an object keyed by language tag`);
+            }
+            else {
+                for (const [tag, line] of Object.entries(translations)) {
+                    if (!LANGUAGE_TAG.test(tag)) {
+                        errors.push(`${label}: voTranslations key "${tag}" is not a BCP-47 language tag, and it becomes a ` +
+                            `directory name under public/audio/vo/`);
+                    }
+                    if (typeof line !== "string" || line.trim().length === 0) {
+                        errors.push(`${label}: voTranslations.${tag} must be a non-empty string`);
+                    }
+                    else if (line.includes(EM_DASH)) {
+                        errors.push(`${label}: voTranslations.${tag} contains an em dash, rewrite with commas/periods`);
+                    }
+                }
+            }
+        }
+        // reformat_vertical's per-beat override. Checked here rather than left to that tool
+        // because a typo in it would otherwise be silent: the reformat would fall back to the
+        // inferred crop and look almost right.
+        const vertical = beat.vertical;
+        if (vertical !== undefined) {
+            if (typeof vertical !== "object" || vertical === null) {
+                errors.push(`${label}: "vertical" must be an object with a focus and/or a crop`);
+            }
+            else {
+                const vert = vertical;
+                if (vert.focus !== undefined &&
+                    (typeof vert.focus !== "string" || !CROP_FOCUSES.includes(vert.focus))) {
+                    errors.push(`${label}: vertical.focus must be one of ${CROP_FOCUSES.map((f) => `"${f}"`).join(", ")}`);
+                }
+                if (vert.crop !== undefined) {
+                    const crop = vert.crop;
+                    const ok = typeof crop === "object" &&
+                        crop !== null &&
+                        ["x", "y", "width", "height"].every((k) => typeof crop[k] === "number" && crop[k] >= 0);
+                    if (!ok) {
+                        errors.push(`${label}: vertical.crop must be { x, y, width, height } with non-negative numbers`);
                     }
                 }
             }
         }
+        // Checked before the visual rules: those return early for desktop, mobile and terminal
+        // beats, and a typo in a beat's transition is just as wrong on one of those.
+        if ("transition" in beat && beat.transition !== undefined) {
+            if (typeof beat.transition !== "string" || !TRANSITIONS.includes(beat.transition)) {
+                errors.push(`${label}: transition must be one of ${TRANSITIONS.map((t) => `"${t}"`).join(", ")} (omit for "cut")`);
+            }
+        }
         const visual = beat.visual;
         if (typeof visual !== "object" || visual === null) {
             errors.push(`${label}: missing or invalid "visual"`);
@@ -108,10 +275,74 @@ function validateBeatsLogic(beatsJson) {
             errors.push(`${label}: visual.captureMethod must be one of ${CAPTURE_METHODS.map((m) => `"${m}"`).join(", ")}`);
             return;
         }
+        const rawSource = v.source;
+        if (rawSource !== undefined && (typeof rawSource !== "string" || !CAPTURE_SOURCES.includes(rawSource))) {
+            errors.push(`${label}: visual.source must be one of ${CAPTURE_SOURCES.map((s) => `"${s}"`).join(", ")} (omit for "browser")`);
+            return;
+        }
+        const source = rawSource ?? "browser";
+        if (source !== "browser" && captureMethod !== "recording") {
+            errors.push(`${label}: visual.source "${source}" is only valid with captureMethod "recording" (got "${captureMethod}"). ` +
+                `A still from a non-browser source is an existing-asset beat, not a screenshot beat.`);
+            return;
+        }
+        if (source === "desktop") {
+            if (typeof v.durationSeconds !== "number" || v.durationSeconds <= 0) {
+                errors.push(`${label}: visual.durationSeconds (positive number) is required for source "desktop": a screen has no natural end`);
+            }
+            if (v.window !== undefined && (typeof v.window !== "string" || v.window.length === 0)) {
+                errors.push(`${label}: visual.window must be a non-empty window title when present`);
+            }
+            return;
+        }
+        if (source === "mobile") {
+            if (typeof v.device !== "string" || !MOBILE_DEVICES.includes(v.device)) {
+                errors.push(`${label}: visual.device must be one of ${MOBILE_DEVICES.map((d) => `"${d}"`).join(", ")} for source "mobile"`);
+            }
+            if (typeof v.durationSeconds !== "number" || v.durationSeconds <= 0) {
+                errors.push(`${label}: visual.durationSeconds (positive number) is required for source "mobile"`);
+            }
+            else if (v.device === "android" && v.durationSeconds > ANDROID_MAX_SECONDS) {
+                errors.push(`${label}: visual.durationSeconds ${v.durationSeconds} exceeds Android screenrecord's ${ANDROID_MAX_SECONDS}s ` +
+                    `hard limit, which truncates silently rather than failing. Split this into multiple beats.`);
+            }
+            return;
+        }
+        if (source === "terminal") {
+            if (typeof v.command !== "string" || v.command.length === 0) {
+                errors.push(`${label}: visual.command is required for source "terminal"`);
+            }
+            else if (/[\s;&|<>]/.test(v.command)) {
+                errors.push(`${label}: visual.command "${v.command}" must be an executable name only. Put arguments in visual.args; ` +
+                    `this is never run through a shell, so a command line here would be treated as one long filename.`);
+            }
+            if (v.args !== undefined && (!Array.isArray(v.args) || v.args.some((a) => typeof a !== "string"))) {
+                errors.push(`${label}: visual.args must be an array of strings when present`);
+            }
+            return;
+        }
         if (captureMethod === "screenshot" || captureMethod === "recording") {
             if (typeof v.url !== "string" || v.url.length === 0) {
                 errors.push(`${label}: visual.url is required for captureMethod "${captureMethod}"`);
             }
+            if (v.settle !== undefined && typeof v.settle !== "boolean") {
+                errors.push(`${label}: visual.settle must be a boolean if present`);
+            }
+            if (v.settleTimeoutMs !== undefined && (typeof v.settleTimeoutMs !== "number" || v.settleTimeoutMs <= 0)) {
+                errors.push(`${label}: visual.settleTimeoutMs must be a positive number if present`);
+            }
+            if (v.waitUntil !== undefined && v.waitUntil !== "load" && v.waitUntil !== "networkidle") {
+                errors.push(`${label}: visual.waitUntil must be "load" or "networkidle" if present`);
+            }
+            if (v.colorScheme !== undefined && v.colorScheme !== "light" && v.colorScheme !== "dark") {
+                errors.push(`${label}: visual.colorScheme must be "light" or "dark" if present`);
+            }
+            if (v.reducedMotion !== undefined && typeof v.reducedMotion !== "boolean") {
+                errors.push(`${label}: visual.reducedMotion must be a boolean if present`);
+            }
+            if (v.deterministic !== undefined && typeof v.deterministic !== "boolean") {
+                errors.push(`${label}: visual.deterministic must be a boolean if present`);
+            }
             if (!Array.isArray(v.interactions)) {
                 errors.push(`${label}: visual.interactions (array, may be empty) is required for captureMethod "${captureMethod}"`);
             }
@@ -135,9 +366,89 @@ function validateBeatsLogic(beatsJson) {
                 errors.push(`${label}: visual.higgsfieldPrompt is required for captureMethod "higgsfield"`);
             }
         }
+        else if (captureMethod === "existing-asset") {
+            if (typeof v.assetPath !== "string" || v.assetPath.length === 0) {
+                errors.push(`${label}: visual.assetPath is required for captureMethod "existing-asset"`);
+            }
+            // Attribution is mandatory by design: a frame this pipeline did not capture is only
+            // honest on screen if the video can say where it came from.
+            if (typeof v.attribution !== "string" || v.attribution.length === 0) {
+                errors.push(`${label}: visual.attribution is required for captureMethod "existing-asset" (say where the asset came ` +
+                    `from, e.g. "from the project's own README"). An unattributed borrowed frame reads as a real capture.`);
+            }
+        }
         // dom-demo: no additional required fields.
+        if ("artifacts" in beat && beat.artifacts !== undefined) {
+            const artifacts = beat.artifacts;
+            if (typeof artifacts !== "object" || artifacts === null || Array.isArray(artifacts)) {
+                errors.push(`${label}: artifacts must be an object`);
+            }
+            else {
+                const a = artifacts;
+                for (const key of Object.keys(a)) {
+                    if (!ARTIFACT_KEYS.includes(key)) {
+                        errors.push(`${label}: artifacts.${key} is not a recognized key (expected one of ${ARTIFACT_KEYS.join(", ")})`);
+                        continue;
+                    }
+                    const val = a[key];
+                    if (typeof val !== "string" || val.length === 0) {
+                        errors.push(`${label}: artifacts.${key} must be a non-empty string path`);
+                    }
+                    else if (val.includes(EM_DASH)) {
+                        errors.push(`${label}: artifacts.${key} contains an em dash, rewrite with commas/periods`);
+                    }
+                }
+            }
+        }
     });
-    return { valid: errors.length === 0, errors };
+    const rhythm = rhythmWarning(lengths, fps);
+    if (rhythm)
+        warnings.push(rhythm);
+    return { valid: errors.length === 0, errors, warnings };
+}
+/**
+ * Uniform shot lengths read as a metronome: a cut every few seconds on the same count, whatever
+ * the content is doing. Warn-only, because plenty of good videos are deliberately even and the
+ * numbers cannot tell those from an unconsidered default. Needs enough beats to be a pattern, and
+ * a longest beat under 2.5x the shortest.
+ */
+function rhythmWarning(lengths, fps) {
+    if (lengths.length < RHYTHM_MIN_BEATS)
+        return null;
+    const longest = lengths.reduce((a, b) => (b.duration > a.duration ? b : a));
+    const shortest = lengths.reduce((a, b) => (b.duration < a.duration ? b : a));
+    const spread = longest.duration / shortest.duration;
+    if (spread >= RHYTHM_MIN_SPREAD)
+        return null;
+    const seconds = (frames) => `${(frames / fps).toFixed(1)}s`;
+    return (`Shot lengths are nearly uniform: across ${lengths.length} beats the longest ("${longest.id}", ` +
+        `${longest.duration} frames, ${seconds(longest.duration)}) is only ${spread.toFixed(2)}x the shortest ` +
+        `("${shortest.id}", ${shortest.duration} frames, ${seconds(shortest.duration)}). Evenly sized shots read as a ` +
+        `metronome. Give the strongest beat one long hold, and make another a short punch of a second or two, so ` +
+        `the longest is at least ${RHYTHM_MIN_SPREAD}x the shortest. This is a note, not an error.`);
+}
+function runValidateBeats(input) {
+    const result = validateBeatsLogic(input.beatsJson);
+    if (input.videoName !== undefined) {
+        (0, facts_1.writeFactRecord)((0, util_1.resolveProjectRoot)(input.projectRoot), {
+            tool: "validate_beats",
+            videoName: (0, util_1.sanitizeSegment)(input.videoName, "videoName"),
+            facts: {
+                ok: result.valid,
+                errors: result.errors.length,
+                warnings: result.warnings.length,
+                // Errors are labelled `beat "<id>": ...` when they belong to one beat.
+                findings: [
+                    ...result.errors.map((message) => {
+                        const m = message.match(/^beat "([^"]+)": ([\s\S]*)$/);
+                        return m ? { beatId: m[1], severity: "error", message: m[2] } : { severity: "error", message };
+                    }),
+                    ...result.warnings.map((message) => ({ severity: "warning", message })),
+                ],
+            },
+        });
+    }
+    return result;
 }
 function registerValidateBeats(server) {
     server.registerTool("validate_beats", {
@@ -149,16 +460,39 @@ function registerValidateBeats(server) {
             "word-count vs the 2.3-2.9 words/sec budget checked in both directions (too many words for the " +
             "duration and suspiciously few), every beat has a captureMethod, and method-specific required " +
             "fields (url + interactions for screenshot/recording, higgsfieldPrompt for higgsfield, nothing extra " +
-            "for dom-demo). For screenshot/recording beats, every interactions[] entry is also validated against " +
+            "for dom-demo). Top-level narration (\"voice\" or \"none\", \"voice\" assumed if omitted) controls " +
+            "whether vo is required and pace-checked at all: under \"none\", vo is optional and unpaced, and an " +
+            "optional per-beat onScreenText is checked instead against a reading-time budget (about 3.5 words/sec " +
+            "plus 0.8s overhead) rather than a spoken-pace budget. Top-level production (optional: { creativeLevel " +
+            "(\"peak\"/\"mid\"/\"literal\"), timeBudgetMinutes }), mirrored from openvidstudio.config.json by " +
+            "plan_production (PLANNING.md §0), is shape-checked only -- what a level implies about content is the " +
+            "agent's job, not this tool's. waitUntil (\"load\" or \"networkidle\"), colorScheme (\"light\" or \"dark\"), " +
+            "reducedMotion (boolean), and deterministic (boolean) are type-checked if present on a screenshot/" +
+            "recording beat. For screenshot/" +
+            "recording beats, every interactions[] entry is also validated against " +
             "the exact schema capture_screenshot/capture_screen_recording enforce at replay time (click, fill, " +
             "select, hover, scroll, wait), so a shape mismatch fails here at draft time instead of at capture " +
-            "time. Returns { valid, errors } with every failure found, never just the first -- this is " +
-            "the tool's normal answer for an invalid draft, not an exceptional case, so it never throws for a " +
-            "validation failure.",
+            "time. Also validates two optional per-beat fields if present: transition (cut, whip, fade, push, wipe " +
+            "or light-leak; cut assumed if omitted; everything but cut is drawn over the cut by stitch_composition " +
+            "without moving any beat boundary) and artifacts (screenshotPath/recordingPath/voPath overrides of the convention output " +
+            "paths, each a non-empty string). For browser screenshot/recording beats, settle (boolean) and " +
+            "settleTimeoutMs (positive number) are also type-checked if present -- see capture_screenshot/" +
+            "capture_screen_recording for what they control. Returns { valid, errors, warnings } with every failure found, " +
+            "never just the first -- this is the tool's normal answer for an invalid draft, not an exceptional case, so " +
+            "it never throws for a validation failure. warnings never make a draft invalid: with four or more beats, " +
+            "if the longest is less than 2.5x the shortest, one warns that uniform shot lengths read as a metronome " +
+            "and suggests one long hold and one short punch.",
         inputSchema: {
             beatsJson: zod_1.z
                 .unknown()
                 .describe("The drafted beats.json content (an object), not a file path."),
+            videoName: zod_1.z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional. When given, the outcome is also kept as a run record for this video (see collect_facts). " +
+                "Validation itself never touches the disk without it."),
+            projectRoot: zod_1.z.string().optional().describe("Only used with videoName."),
         },
-    }, async ({ beatsJson }) => (0, mcp_1.runTool)("validate_beats", () => validateBeatsLogic(beatsJson)));
+    }, async (input) => (0, mcp_1.runTool)("validate_beats", () => runValidateBeats(input)));
 }

package/dist/tools/validateCanvasExplainer.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerValidateCanvasExplainer(server: McpServer): void;

package/dist/tools/validateCanvasExplainer.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerValidateCanvasExplainer = registerValidateCanvasExplainer;
+const zod_1 = require("zod");
+const canvasValidate_1 = require("../canvasValidate");
+const mcp_1 = require("./mcp");
+function registerValidateCanvasExplainer(server) {
+    server.registerTool("validate_canvas_explainer", {
+        title: "Check a canvas explainer for problems that render without erroring",
+        description: "What validate_scenes does for a Remotion composition, for a canvas explainer (see render_canvas_explainer). Loads the HTML " +
+            "in headless Chromium and samples frames through window.seek(t). Checks: purity, three times drawn twice with another time " +
+            "between, the frames must match (error); text size, by intercepting fillText and strokeText: labels 28px, headlines 44px and " +
+            "key numbers 64px at 720 on the shorter side, scaled to the canvas (warning below, error below half; captions drawn through " +
+            "window.CAPTIONS are exempt); safe areas, on a tall canvas no text in the top 14% or bottom 22% except captions (warning); the " +
+            "lesson arc through the same code as validate_scenes, the first frame with anything drawn beyond the background and the captions " +
+            "(diagram-late: warning after 15 s, error after 25 s) and any run of frames that do not change longer than 8 s " +
+            "(static-stretch, warning); the sound, by scheduling window.scoreSound into an offline context: the most source nodes " +
+            "playing at once (warning above 3) and the peak level (warning at clipping); and Math.random in the source (warning). " +
+            "Findings have validate_scenes' shape (beatId, scene, severity, check, message). Pass videoName to use the project's beats " +
+            "and captions as render_canvas_explainer does. Returns ok, the findings, the length, the smallest text size and the sound figures.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            htmlPath: zod_1.z.string().min(1),
+            width: zod_1.z.number().int().positive().optional().describe("Default 1280."),
+            height: zod_1.z.number().int().positive().optional().describe("Default 720. Use 720 wide by 1280 high for a Reel."),
+            fps: zod_1.z.number().positive().optional(),
+            videoName: zod_1.z.string().optional(),
+            audio: zod_1.z.boolean().optional().describe("Judge the sound too. Default true."),
+            textScale: zod_1.z.number().positive().optional().describe("Multiply the text minimums by this instead of min(width, height) / 720."),
+            diagramWarnSeconds: zod_1.z.number().positive().optional(),
+            diagramErrorSeconds: zod_1.z.number().positive().optional(),
+            staticSeconds: zod_1.z.number().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("validate_canvas_explainer", () => (0, canvasValidate_1.validateCanvasExplainer)(input)));
+}

package/dist/tools/validateScenes.d.ts

@@ -3,9 +3,11 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * The worst failure class in this pipeline is silent wrongness: a scene renders
  * successfully and is simply wrong.
  *
- * The commonest instance is framing. Scenes lay content out on a 1920x1080 stage, but
- * the camera only ever shows stage divided by scale, so at 1.4 that is 1371x771 and
- * anything wider is cropped at the frame edge. Nothing errors. Building one real video
+ * The commonest instance is framing. Scenes lay content out on a stage the size of the
+ * composition (1920x1080 by default, 1080x1920 for a native vertical project: whatever
+ * videoConfig in openvidstudio.config.json says), but the camera only ever shows stage
+ * divided by scale, so at 1.4 a 1920x1080 stage shows 1371x771 and anything wider is
+ * cropped at the frame edge. Nothing errors. Building one real video
  * this cropped three scenes, and it was only caught by rendering stills and looking.
  *
  * This reads the scene sources and reports the mismatches that are visible statically:
@@ -15,17 +17,83 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export interface ValidateScenesInput {
     projectRoot?: string;
     videoName: string;
+    /**
+     * Also mount the composition in a real browser and measure the rendered frames. Slower
+     * (it bundles the project) and needs the video stitched, but it is the only way to see
+     * cropping, text size, reading time and dead frames as they actually render.
+     */
+    render?: boolean;
+    /** With render: overrides the composition id resolved from src/videos/.registry.json. */
+    compositionId?: string;
+    /** With render: limit the measurement to these beats. Static checks always cover every beat. */
+    beatIds?: string[];
+    /** Lessons, with render: warn when the first drawn element is later than this many seconds. Default 15. */
+    diagramWarnSeconds?: number;
+    /** Lessons, with render: an error when the first drawn element is later than this. Default 25. */
+    diagramErrorSeconds?: number;
+    /** Lessons, with render: warn when nothing changes for longer than this. Default 8. */
+    staticSeconds?: number;
 }
 export interface SceneFinding {
     beatId: string;
     scene: string;
     severity: "error" | "warning";
     message: string;
+    /** Which pass produced this: reading the source, or measuring the real render. */
+    source?: "static" | "render";
+    /**
+     * For render findings, which check: crop, text-size, reading-time, dead-frames, em-dash,
+     * contrast, safe-area, hud-overlap or render-skipped.
+     */
+    check?: string;
 }
 export interface ValidateScenesResult {
+    /** "supernova" when the project is a STEM lesson, whose numbers and glow are judged by lesson rules. */
+    mode?: "standard" | "supernova";
     ok: boolean;
     scenesChecked: number;
     findings: SceneFinding[];
+    /** Present only when render mode ran. */
+    render?: {
+        compositionId: string;
+        beatsMeasured: number;
+        beatsSkipped: {
+            beatId: string;
+            reason: string;
+        }[];
+        bundleMs: number;
+        totalMs: number;
+    };
 }
+/**
+ * The one artifact a beat actually needs, plus the command that produces it.
+ *
+ * Returns null for beats that need no capture at all (dom-demo), so the caller does not
+ * have to special-case them. Honours an `artifacts` override, since a beat is allowed to
+ * put its capture somewhere other than the convention path.
+ */
+/**
+ * Numbers a scene types into its own copy. C8: a scene that shows a number must get it from
+ * facts.json (what collect_facts merged out of the real tool runs) or from a capture, never
+ * from the author's memory, because a retyped number is the one that goes stale or was never
+ * true. This reads the scene source for numbers inside visible text (JSX text, and the string
+ * props text, label, title, name, caption, value) and returns them. Years, version strings
+ * and single digits are not claims and are skipped.
+ */
+export declare function typedNumbers(src: string): string[];
+/** The numbers a lesson's concept card and an Equation's TeX already account for. */
+export declare function lessonNumbers(example: string | undefined, src: string): Set<string>;
+/** True when the config or the beats file says this project is a Supernova lesson. */
+export declare function isLesson(projectRoot: string, beats: {
+    production?: {
+        mode?: string;
+    };
+}): boolean;
 export declare function runValidateScenes(input: ValidateScenesInput): ValidateScenesResult;
+/**
+ * The static pass plus, when `render` is set, the render-based pass. Async because the
+ * render pass bundles the project and drives a browser; runValidateScenes stays synchronous
+ * for every caller that only wants the static read.
+ */
+export declare function runValidateScenesFull(input: ValidateScenesInput): Promise<ValidateScenesResult>;
 export declare function registerValidateScenes(server: McpServer): void;