@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/tools/validateScenes.js

@@ -33,22 +33,77 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.typedNumbers = typedNumbers;
+exports.lessonNumbers = lessonNumbers;
+exports.isLesson = isLesson;
 exports.runValidateScenes = runValidateScenes;
+exports.runValidateScenesFull = runValidateScenesFull;
 exports.registerValidateScenes = registerValidateScenes;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const zod_1 = require("zod");
 const util_1 = require("../util");
 const config_1 = require("../config");
+const capture_1 = require("@openvidstudio/capture");
 const mcp_1 = require("./mcp");
-const STAGE_W = 1920;
-const STAGE_H = 1080;
+const facts_1 = require("../facts");
+const renderStills_1 = require("./renderStills");
+const validateScenesRender_1 = require("./validateScenesRender");
+/**
+ * Reads the `<asset>.settle.json` sidecar capture_screenshot/capture_screen_recording
+ * write next to their output (see @openvidstudio/capture's writeSettleSidecar) and
+ * reports a timed-out settle loudly: that beat's frame may have been caught mid-
+ * transition, and the only previous evidence was a field in a tool result nobody kept.
+ * No sidecar (settle:false, or an asset captured before this existed) is not an error,
+ * it just means nothing to check.
+ */
+function checkSettleSidecar(assetPathAbs, beatId, component, findings) {
+    const sidecarPath = (0, capture_1.settleSidecarPath)(assetPathAbs);
+    if (!fs.existsSync(sidecarPath))
+        return;
+    let report;
+    try {
+        report = JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+    }
+    catch {
+        return; // Malformed sidecar: not this tool's job to diagnose, skip rather than crash validation.
+    }
+    if (!report.settled) {
+        const pending = [];
+        if (!report.fontsReady)
+            pending.push("fonts");
+        if (!report.imagesReady)
+            pending.push("images");
+        if (report.pendingAnimations > 0)
+            pending.push(`${report.pendingAnimations} animation(s)`);
+        findings.push({
+            beatId,
+            scene: `${component}.tsx`,
+            severity: "error",
+            message: `Capture timed out waiting to settle after ${report.waitedMs}ms, still pending: ` +
+                `${pending.join(", ") || "unknown"}. The frame may be caught mid-transition. Re-run the capture tool ` +
+                `with a larger settleTimeoutMs, or fix whatever on the page never finishes loading/animating.`,
+        });
+    }
+}
 /** Every numeric `scale:` in the camera array. */
 function cameraScales(src) {
     return [...src.matchAll(/scale:\s*([\d.]+)/g)]
         .map((m) => Number.parseFloat(m[1]))
         .filter((n) => Number.isFinite(n));
 }
+/**
+ * Core components that wrap `CinematicScene` with their own hardcoded internal camera
+ * keyframes (see e.g. RepoCta.tsx's `camera={[...]}`), so a scene built from one needs no
+ * external camera layered on top -- the generated .tsx just renders the component with
+ * content props and has no `scale:`/`camera` array of its own to find. Checked in packages/
+ * core/src for anything else similarly wrapping CinematicScene internally: RepoCta is the
+ * only one today. Extend this list if another one is added.
+ */
+const SELF_CAMERA_COMPONENTS = ["RepoCta"];
+function usesSelfManagedCamera(src) {
+    return SELF_CAMERA_COMPONENTS.some((name) => new RegExp(`\\b${name}\\b`).test(src));
+}
 /** Explicit pixel widths a scene declares, which is what gets cropped. */
 function declaredWidths(src) {
     const out = [];
@@ -60,10 +115,129 @@ function declaredWidths(src) {
         out.push(Number(m[1]));
     return out;
 }
+/**
+ * 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.
+ */
+function typedNumbers(src) {
+    const candidates = [];
+    for (const m of src.matchAll(/>([^<>{}]*\d[^<>{}]*)</g))
+        candidates.push(m[1]);
+    for (const m of src.matchAll(/\b(?:text|label|title|name|caption|value)\s*=\s*(?:"([^"]*\d[^"]*)"|'([^']*\d[^']*)')/g))
+        candidates.push((m[1] ?? m[2]));
+    const found = [];
+    for (const text of candidates) {
+        for (const m of text.matchAll(/(?<![\w.])(v?)(\d(?:[\d,]*\d)?(?:\.\d+)?)(?![\w])/g)) {
+            const token = m[2];
+            if (m[1] === "v")
+                continue;
+            if (/^(19|20)\d{2}$/.test(token))
+                continue;
+            if (/^\d$/.test(token))
+                continue;
+            if (/^\d+\.\d+\.\d+/.test(token))
+                continue;
+            found.push(token);
+        }
+    }
+    return [...new Set(found)];
+}
+/** A number as a comparable token: thousands separators dropped, so "1,200" and "1200" are the same. */
+const numberKey = (token) => token.replace(/,/g, "");
+/** The numbers a lesson's concept card and an Equation's TeX already account for. */
+function lessonNumbers(example, src) {
+    const allowed = new Set();
+    const add = (text) => {
+        // Every run of digits, however it is attached: "36x" in TeX and "20m/s" in prose both account for 36 and 20.
+        for (const m of text.matchAll(/\d+(?:,\d{3})*(?:\.\d+)?/g))
+            allowed.add(numberKey(m[0]));
+    };
+    if (example)
+        add(example);
+    // tex="...", tex={"..."}, tex={`...`}, tex={String.raw`...`}
+    for (const m of src.matchAll(/\btex\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:String\.raw)?\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)\s*\})/g)) {
+        add(m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? "");
+    }
+    return allowed;
+}
+function importsFacts(src) {
+    return /from\s+["'][^"']*facts(?:\.json)?["']/.test(src);
+}
+function expectedArtifact(beat, method, source) {
+    const a = beat.artifacts ?? {};
+    if (method === "existing-asset") {
+        const rel = beat.visual?.assetPath;
+        return rel
+            ? { rel, fix: `This beat shows an asset the project already publishes; put the real file at that path.` }
+            : null;
+    }
+    if (method === "screenshot") {
+        return {
+            rel: a.screenshotPath ?? `public/images/${beat.id}.png`,
+            fix: "Run capture_screenshot.",
+        };
+    }
+    if (method === "recording") {
+        if (source === "terminal") {
+            return {
+                rel: a.terminalPath ?? `public/terminal/${beat.id}.json`,
+                fix: "Run capture_terminal for this beat.",
+            };
+        }
+        const rel = a.recordingPath ?? `public/video/${beat.id}.mp4`;
+        if (source === "desktop")
+            return { rel, fix: "Run capture_desktop for this beat." };
+        if (source === "mobile")
+            return { rel, fix: "Run capture_mobile for this beat." };
+        return { rel, fix: "Run capture_screen_recording." };
+    }
+    if (method === "higgsfield") {
+        return {
+            rel: a.recordingPath ?? `public/video/${beat.id}.mp4`,
+            fix: "Run import_higgsfield_clip.",
+        };
+    }
+    return null;
+}
+/** True when the config or the beats file says this project is a Supernova lesson. */
+function isLesson(projectRoot, beats) {
+    return beats.production?.mode === "supernova" || (0, config_1.productionMode)((0, config_1.loadConfig)(projectRoot)) === "supernova";
+}
+function recordValidateScenes(input, result) {
+    (0, facts_1.writeFactRecord)((0, util_1.resolveProjectRoot)(input.projectRoot), {
+        tool: "validate_scenes",
+        videoName: (0, util_1.sanitizeSegment)(input.videoName, "videoName"),
+        facts: {
+            ok: result.ok,
+            scenesChecked: result.scenesChecked,
+            renderMode: result.render !== undefined,
+            errors: result.findings.filter((f) => f.severity === "error").length,
+            warnings: result.findings.filter((f) => f.severity === "warning").length,
+            findings: result.findings,
+            ...(result.render ? { render: result.render } : {}),
+        },
+    });
+}
 function runValidateScenes(input) {
+    const result = staticPass(input);
+    recordValidateScenes(input, result);
+    return result;
+}
+function staticPass(input) {
     const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
     const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
-    const config = (0, config_1.loadConfig)(projectRoot);
+    const { width: frameW, height: frameH } = (0, config_1.loadConfig)(projectRoot).videoConfig;
     const videoDir = path.join(projectRoot, "src", "videos", videoName);
     const scenesDir = path.join(videoDir, "scenes");
     const beatsFile = path.join(videoDir, "beats.json");
@@ -73,25 +247,45 @@ function runValidateScenes(input) {
     const doc = JSON.parse(fs.readFileSync(beatsFile, "utf8"));
     const findings = [];
     let checked = 0;
+    // A lesson (Supernova) is judged by its own rules: the numbers in an equation or a worked example are
+    // computed, not claims, and nothing in it is footage to disclose. The config or the beats file may say so.
+    const lesson = isLesson(projectRoot, doc);
+    let example;
+    if (lesson) {
+        try {
+            const card = JSON.parse(fs.readFileSync(path.join(videoDir, "concept.json"), "utf8"));
+            if (typeof card.example === "string")
+                example = card.example;
+        }
+        catch {
+            // No concept card, or not valid JSON: only the Equations' own numbers are accounted for.
+        }
+    }
     for (const beat of doc.beats) {
-        const component = (0, util_1.pascalCase)(beat.id);
-        const file = path.join(scenesDir, `${component}.tsx`);
+        // A beat can point at a bespoke scene (C5's `scene` field); stitch_composition imports that
+        // file instead of scenes/<Pascal>.tsx, so this has to read the same one.
+        const overridden = beat.scene ? path.join(videoDir, beat.scene.replace(/\.(tsx|ts|jsx|js)$/, "") + ".tsx") : null;
+        const component = overridden ? path.basename(overridden, ".tsx") : (0, util_1.pascalCase)(beat.id);
+        const file = overridden ?? path.join(scenesDir, `${component}.tsx`);
         if (!fs.existsSync(file)) {
             findings.push({
                 beatId: beat.id,
                 scene: `${component}.tsx`,
                 severity: "error",
-                message: `No scene file. Run scaffold_scene for this beat.`,
+                message: overridden
+                    ? `Scene override ${beat.scene} does not exist.`
+                    : `No scene file. Run scaffold_scene for this beat.`,
             });
             continue;
         }
         checked++;
         const src = fs.readFileSync(file, "utf8");
-        // Framing. The binding number is the scene's highest scale, not its first.
+        // Framing. The binding number is the scene's highest scale, not its first. The frame is the
+        // project's own composition size, so a 1080x1920 reel is judged against 1080 wide, not 1920.
         const scales = cameraScales(src);
         const maxScale = scales.length ? Math.max(...scales) : 1;
-        const visibleW = Math.round(STAGE_W / maxScale);
-        const visibleH = Math.round(STAGE_H / maxScale);
+        const visibleW = Math.round(frameW / maxScale);
+        const visibleH = Math.round(frameH / maxScale);
         for (const w of declaredWidths(src)) {
             if (w > visibleW) {
                 findings.push({
@@ -99,7 +293,7 @@ function runValidateScenes(input) {
                     scene: `${component}.tsx`,
                     severity: "error",
                     message: `Content declares ${w}px wide but the camera reaches scale ${maxScale}, which shows only ` +
-                        `${visibleW}x${visibleH} of the stage. It will be cropped at the frame edge and the render ` +
+                        `${visibleW}x${visibleH} of the ${frameW}x${frameH} stage. It will be cropped at the frame edge and the render ` +
                         `will not warn. Narrow the content or lower the camera scale.`,
                 });
             }
@@ -116,7 +310,7 @@ function runValidateScenes(input) {
                 });
             }
         }
-        if (scales.length < 2) {
+        if (scales.length < 2 && !usesSelfManagedCamera(src)) {
             findings.push({
                 beatId: beat.id,
                 scene: `${component}.tsx`,
@@ -125,40 +319,69 @@ function runValidateScenes(input) {
             });
         }
         // Capture assets the scene references but that are not on disk yet.
+        //
+        // Which artifact a beat needs, and which tool produces it, both depend on the beat's
+        // `source` as well as its captureMethod. Telling someone to run capture_screenshot
+        // for a `source: "desktop"` beat is worse than saying nothing: the suggested command
+        // cannot produce the missing file.
         const method = beat.visual?.captureMethod;
-        if (method === "screenshot") {
-            const asset = path.join(projectRoot, "public", "images", `${beat.id}.png`);
-            if (!fs.existsSync(asset)) {
+        const source = beat.visual?.source ?? "browser";
+        const expected = expectedArtifact(beat, method, source);
+        if (expected) {
+            const assetPathAbs = path.join(projectRoot, expected.rel);
+            if (!fs.existsSync(assetPathAbs)) {
                 findings.push({
                     beatId: beat.id,
                     scene: `${component}.tsx`,
                     severity: "error",
-                    message: `References public/images/${beat.id}.png, which does not exist. Run capture_screenshot.`,
+                    message: `References ${expected.rel}, which does not exist. ${expected.fix}`,
                 });
             }
+            else if (source === "browser" && (method === "screenshot" || method === "recording")) {
+                // Settling is a browser-capture concept: capture_desktop/mobile/terminal have no
+                // settlePage call and never write this sidecar.
+                checkSettleSidecar(assetPathAbs, beat.id, component, findings);
+            }
         }
-        if (method === "recording" || method === "higgsfield") {
-            const asset = path.join(projectRoot, "public", "video", `${beat.id}.mp4`);
-            if (!fs.existsSync(asset)) {
+        // C8: numbers shown on screen come from facts or a capture. A scene that types numbers into its
+        // own copy without importing facts.json is asserting them from memory. A file can opt out of the
+        // check with a `// ovs-numbers-ok: <reason>` comment (a step counter, a fixed price).
+        if (!importsFacts(src) && !src.includes("ovs-numbers-ok")) {
+            let typed = typedNumbers(src);
+            // In a lesson a number is fine when the concept card's worked example or an Equation's TeX has it;
+            // one that appears nowhere is still flagged.
+            if (lesson) {
+                const allowed = lessonNumbers(example, src);
+                typed = typed.filter((t) => !allowed.has(numberKey(t)));
+            }
+            if (typed.length > 0) {
                 findings.push({
                     beatId: beat.id,
                     scene: `${component}.tsx`,
-                    severity: "error",
-                    message: `References public/video/${beat.id}.mp4, which does not exist.`,
+                    severity: "warning",
+                    check: "numbers-sourcing",
+                    message: `Shows ${typed.length === 1 ? "a number" : "numbers"} typed into the scene (${typed.slice(0, 4).join(", ")}` +
+                        `${typed.length > 4 ? ", ..." : ""}) without importing facts.json. A number on screen should come from ` +
+                        `a real tool run (collect_facts merges them into src/videos/${videoName}/facts.json) or from a capture. ` +
+                        `If this one is a label rather than a claim, add "// ovs-numbers-ok: <why>" to the file.`,
                 });
             }
         }
-        if (/TODO/.test(src)) {
+        const todo = src.match(/TODO/g);
+        if (todo) {
+            const offset = src.indexOf("TODO");
+            const line = src.slice(0, offset).split("\n").length;
             findings.push({
                 beatId: beat.id,
                 scene: `${component}.tsx`,
                 severity: "warning",
-                message: `Still contains a TODO.`,
+                message: `Still contains a TODO at ${component}.tsx:${line}.`,
             });
         }
     }
-    // Narration, which stitch_composition skips silently when absent.
-    for (const beat of doc.beats) {
+    // Narration, which stitch_composition skips silently when absent. Not for a video that declares
+    // narration: "none", which has no voice to miss.
+    for (const beat of doc.narration === "none" ? [] : doc.beats) {
         const vo = path.join(projectRoot, "public", "audio", "vo", `${beat.id}.mp3`);
         if (!fs.existsSync(vo)) {
             findings.push({
@@ -170,22 +393,92 @@ function runValidateScenes(input) {
             });
         }
     }
-    void config;
-    return { ok: !findings.some((f) => f.severity === "error"), scenesChecked: checked, findings };
+    const tagged = findings.map((f) => ({ source: "static", ...f }));
+    return { mode: lesson ? "supernova" : "standard", ok: !tagged.some((f) => f.severity === "error"), scenesChecked: checked, findings: tagged };
+}
+/**
+ * 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.
+ */
+async function runValidateScenesFull(input) {
+    const result = staticPass(input);
+    if (!input.render) {
+        recordValidateScenes(input, result);
+        return result;
+    }
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const videoDir = path.join(projectRoot, "src", "videos", videoName);
+    const doc = JSON.parse(fs.readFileSync(path.join(videoDir, "beats.json"), "utf8"));
+    let beats = doc.beats;
+    if (input.beatIds && input.beatIds.length > 0) {
+        const known = new Set(beats.map((b) => b.id));
+        const unknown = input.beatIds.filter((id) => !known.has(id));
+        if (unknown.length > 0)
+            throw new Error(`beatIds not found in beats.json: ${unknown.join(", ")}`);
+        const wanted = new Set(input.beatIds);
+        beats = beats.filter((b) => wanted.has(b.id));
+    }
+    const compositionId = (0, renderStills_1.resolveCompositionId)(projectRoot, videoName, input.compositionId);
+    const rendered = await (0, validateScenesRender_1.runRenderChecks)({
+        projectRoot,
+        videoName,
+        compositionId,
+        beats,
+        fps: doc.fps ?? 30,
+        minimums: (0, validateScenesRender_1.readTypeMinimums)(videoDir),
+        deliberateHolds: (0, validateScenesRender_1.readDeliberateHolds)(videoDir),
+        glowBudget: isLesson(projectRoot, doc),
+    });
+    const findings = [...result.findings, ...rendered.findings];
+    const full = {
+        mode: result.mode,
+        ok: !findings.some((f) => f.severity === "error"),
+        scenesChecked: result.scenesChecked,
+        findings,
+        render: {
+            compositionId,
+            beatsMeasured: rendered.beatsMeasured,
+            beatsSkipped: rendered.beatsSkipped,
+            bundleMs: rendered.bundleMs,
+            totalMs: rendered.totalMs,
+        },
+    };
+    recordValidateScenes(input, full);
+    return full;
 }
 function registerValidateScenes(server) {
     server.registerTool("validate_scenes", {
         title: "Check scenes for problems that render without erroring",
         description: "Reads every scene for a video and reports what would otherwise only be caught by watching the " +
-            "output. Chiefly framing: content is laid out on a 1920x1080 stage but the camera shows stage " +
-            "divided by scale, so a panel wider than the visible box is cropped at the frame edge with no " +
-            "warning at all. Also flags scenes whose camera never moves (a static frame fails STYLE.md), " +
-            "capture assets a scene references that are not on disk, leftover TODOs, and beats with no " +
+            "output. Chiefly framing: content is laid out on a stage the size of the composition (1920x1080 by " +
+            "default, 1080x1920 for a native vertical project, read from the project's videoConfig) but the " +
+            "camera shows stage divided by scale, so a panel wider than the visible box is cropped at the frame " +
+            "edge with no warning at all. Also flags scenes whose camera never moves (a static frame fails STYLE.md), " +
+            "capture assets a scene references that are not on disk, a browser capture whose settle sidecar " +
+            "reports a timeout (the frame may be mid-transition -- see capture_screenshot/" +
+            "capture_screen_recording's settle/settleTimeoutMs), leftover TODOs, and beats with no " +
             "narration file, since stitch_composition skips those silently and the beat renders mute. Run it " +
-            "after scaffolding and again before rendering.",
+            "after scaffolding and again before rendering. Pass render: true to also mount the stitched composition " +
+            "in a real browser and measure what actually renders: text cropped at the frame edge (camera-" +
+            "transformed content only, found through the real DOM), text below the design system's minimum " +
+            "size (a Pill/ToolChip label gets its own, lower floor rather than body's), on-screen text that " +
+            "needs longer to read than the beat lasts (3.5 words/sec plus 0.8s, the same budget validate_beats " +
+            "applies), beats whose frames never change, em dashes in on-screen copy, text colour against the " +
+            "pixels rendered behind it (WCAG 4.5:1, 3:1 for large text), text outside the title-safe area, and " +
+            "scene text that overlaps the chapter HUD. In a Supernova lesson (production mode supernova) two checks change: " +
+            "a number typed into a scene passes when the concept card's worked example (concept.json) or an Equation's tex " +
+            "has it, and one that appears nowhere is still flagged, and render mode also counts the glowing elements in " +
+            "sampled frames (Void + Spark allows one at a time): more than one is a warning, more than two an error, " +
+            "except in a beat that holds a Nova. Needs stitch_composition to have run. A beat that cannot be mounted (a screen " +
+            "recording played through OffthreadVideo) is reported as render-skipped, never as clean.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
             videoName: zod_1.z.string().min(1),
+            render: zod_1.z.boolean().optional(),
+            compositionId: zod_1.z.string().optional(),
+            beatIds: zod_1.z.array(zod_1.z.string()).optional(),
         },
-    }, async (input) => (0, mcp_1.runTool)("validate_scenes", () => runValidateScenes(input)));
+    }, async (input) => (0, mcp_1.runTool)("validate_scenes", () => runValidateScenesFull(input)));
 }

package/dist/tools/validateScenesRender.d.ts

@@ -0,0 +1,178 @@
+import type { SceneFinding } from "./validateScenes";
+import { MAX_READING_WORDS_PER_SEC, READING_OVERHEAD_SEC } from "./validateBeats";
+/**
+ * validate_scenes's render mode: the checks a static read of scene source cannot make,
+ * because each one depends on what the camera and the layout actually produce.
+ *
+ *  - crop:        text inside the camera-transformed stage that lands outside the frame
+ *  - text size:   text that ends up below the design system's minimum on-screen size
+ *  - reading:     a beat that is on screen for less time than its text takes to read
+ *  - dead frames: a beat whose rendered pixels never change
+ *  - em dash:     an em dash anywhere in on-screen copy
+ *  - contrast:    text colour against the pixels actually rendered behind it
+ *  - safe area:   text inside the frame but outside the title-safe inset
+ *  - HUD overlap: scene text drawn over the chapter HUD
+ *
+ * Measurement is DOM-based, not pixel-based. The scene is mounted in a real browser through
+ * the remotionBridge, seeked to a handful of frames inside each beat, and measured with
+ * getBoundingClientRect. That gives exact coordinates with no anti-aliasing or colour
+ * threshold to tune. Dead frames are the one pixel check, since "nothing moved" has no DOM
+ * equivalent (a canvas or a video can change without a node changing).
+ *
+ * Stage content is told apart from screen-space overlay content through the two data
+ * attributes core writes (`data-ovs-camera-stage`, `data-ovs-overlay`). Overlay content
+ * (captions, HUD) is not transformed by the camera, so it cannot be cropped by it and is
+ * exempt from the crop check. It is still held to the size and reading checks.
+ */
+/**
+ * Silent reading budget for on-screen text: about 3.5 words a second plus 0.8 s to land on it,
+ * the same numbers validate_beats applies to onScreenText on a narration:"none" beat, imported
+ * so the two gates can never disagree about how long a card has to stay up. This is a different
+ * number from validateBeats's MIN_PACE/MAX_PACE, which is the pace of spoken narration.
+ */
+export { MAX_READING_WORDS_PER_SEC, READING_OVERHEAD_SEC };
+export interface TypeScaleMinimums {
+    body: number;
+    mono: number;
+    /** Small UI chips (Pill, ToolChip): never held to body's minimum, which they are not
+     * trying to meet, nor to mono's, which is about a different font role entirely. */
+    label: number;
+}
+/**
+ * Minimums used when a video has no design.ts. body/mono mirror DEFAULT_TYPE_SCALE in
+ * packages/core/src/designSystem.ts (body 26-34, mono 15-22); the values are copied rather
+ * than imported because this package does not depend on core, which is a template dependency.
+ * label has no DesignSystem.typeScale counterpart (that type has no label field) and is not
+ * read from design.ts below: it is a fixed floor, picked below Pill/ToolChip's own 18/20px
+ * defaults so a deliberately smaller label still passes, but a near-illegible one is flagged.
+ */
+export declare const DEFAULT_TYPE_MINIMUMS: TypeScaleMinimums;
+/**
+ * Reads the lower bound of `body` and `mono` from src/videos/<name>/design.ts when one
+ * exists. Regex rather than evaluating the file, since design.ts is TypeScript that imports
+ * core and cannot be loaded from here. Anything it cannot read falls back to the default.
+ */
+export declare function readTypeMinimums(videoDir: string): TypeScaleMinimums;
+export interface RenderBeat {
+    id: string;
+    start: number;
+    duration: number;
+}
+export interface RenderCheckInput {
+    projectRoot: string;
+    videoName: string;
+    compositionId: string;
+    beats: RenderBeat[];
+    fps: number;
+    minimums: TypeScaleMinimums;
+    /** An already-built bundle directory to measure against, instead of bundling the project again. */
+    bundleDir?: string;
+    /** Beat ids the brief marks as deliberate holds: unchanging frames there are not a dead-frames finding. */
+    deliberateHolds?: string[];
+    /** Count the glowing elements in each sampled frame against Supernova's one-at-a-time budget. Lessons only. */
+    glowBudget?: boolean;
+}
+export interface RenderCheckResult {
+    findings: SceneFinding[];
+    beatsMeasured: number;
+    beatsSkipped: {
+        beatId: string;
+        reason: string;
+    }[];
+    bundleMs: number;
+    totalMs: number;
+}
+interface TextProbe {
+    text: string;
+    /** Font size as it appears in the output frame, camera scale included. */
+    fontPx: number;
+    mono: boolean;
+    /** Inside a data-ovs-label element (Pill, ToolChip): held to its own, lower minimum. */
+    label: boolean;
+    inStage: boolean;
+    opacity: number;
+    /** Fraction of the text box outside the frame, 0 to 1. */
+    croppedRatio: number;
+    /** Furthest overhang past any frame edge, in output pixels. */
+    overhangPx: number;
+    /** Inside a data-ovs-hud element (ChapterHud): chrome, exempt from size and reading checks. */
+    hud?: boolean;
+    /** Furthest the text box reaches past the title-safe inset, in output pixels (0 if inside). */
+    safeOverhangPx?: number;
+    /** Largest share of the text box covered by a HUD element it is not part of, 0 to 1. */
+    hudOverlap?: number;
+    /** The CSS text colour, r/g/b 0-255 and alpha 0-1 (alpha 0 for gradient or clipped text). */
+    rgba?: [number, number, number, number];
+    /** The text box in the output frame, used to read the background out of the screenshot. */
+    box?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    /** Background colour behind the text, read from the screenshot after the probe. */
+    bg?: [number, number, number] | null;
+}
+/**
+ * WCAG contrast ratio of text against an opaque background. The text colour is first
+ * composited over that background with its own alpha times its ancestors' opacity, which is
+ * what actually reaches the screen.
+ */
+export declare function contrastAgainst(rgba: [number, number, number, number], opacity: number, bg: [number, number, number]): number;
+/**
+ * The colour behind a text box, read from the rendered frame. Taken from a ring just outside
+ * the box rather than from inside it, because inside it a large or bold string can cover more
+ * than half the pixels and the median would be the glyph colour, not the surface. The median of
+ * each channel keeps a gradient or a soft shadow from skewing it. Falls back to the box
+ * interior when there is no ring (a box that fills the frame).
+ */
+export declare function backgroundBehind(pixels: Uint8Array, width: number, height: number, channels: number, box: {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+}, ringPx: number): [number, number, number] | null;
+/**
+ * Beat ids the brief marks `deliberateHold: true` in its shotList. A missing or unreadable brief
+ * means no holds are declared, which is the strict reading: unchanging frames get reported.
+ */
+export declare function readDeliberateHolds(videoDir: string): string[];
+/**
+ * The #rrggbb colours src/brand.ts sets, minus pure black and white (which nearly any frame
+ * contains, so they could not tell a branded render from an unbranded one). Empty when there is
+ * no brand file or it carries no hex colours.
+ */
+export declare function brandHexColors(projectRoot: string): string[];
+/**
+ * Pure: for each colour, the share of sampled pixels in a frame that match it. A stride keeps
+ * this cheap on a 1920x1080 frame; a flat brand surface is far larger than any stride skips.
+ */
+export declare function colorShares(pixels: Uint8Array, width: number, height: number, channels: number, colors: string[]): Map<string, number>;
+/** Pure: the palette finding, given the largest share each brand colour reached in any sampled frame. */
+export declare function judgeBrandPalette(maxShare: Map<string, number>): SceneFinding[];
+/**
+ * Pure: turns what was measured in one beat's sampled frames into findings. Split out of the
+ * browser loop so the judgement is testable without a browser.
+ */
+export declare function judgeBeat(opts: {
+    beat: RenderBeat;
+    fps: number;
+    minimums: TypeScaleMinimums;
+    samples: TextProbe[][];
+    /** Largest changed-pixel ratio between any two sampled frames, or null if not measured. */
+    maxChangedRatio: number | null;
+    /** The brief marks this beat as a deliberate hold, so unchanging frames are intended. */
+    deliberateHold?: boolean;
+}): SceneFinding[];
+/** What the glow helper in @openvidstudio/stem leaves in the DOM: an element per glow, tagged with its kind and level. */
+interface GlowProbe {
+    kind: string;
+    level: number;
+}
+/**
+ * The glow budget: one glowing element at a time. More than one in a sampled frame is a warning, more
+ * than two an error. A beat that holds a Nova is exempt: the payoff is allowed to be the moment
+ * everything lights up. The worst frame in the beat is the one reported, once.
+ */
+export declare function judgeGlow(beat: RenderBeat, samples: GlowProbe[][], frames: number[]): SceneFinding[];
+export declare function runRenderChecks(input: RenderCheckInput): Promise<RenderCheckResult>;