@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/validateScenesRender.js

@@ -0,0 +1,772 @@
+"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.DEFAULT_TYPE_MINIMUMS = exports.READING_OVERHEAD_SEC = exports.MAX_READING_WORDS_PER_SEC = void 0;
+exports.readTypeMinimums = readTypeMinimums;
+exports.contrastAgainst = contrastAgainst;
+exports.backgroundBehind = backgroundBehind;
+exports.readDeliberateHolds = readDeliberateHolds;
+exports.brandHexColors = brandHexColors;
+exports.colorShares = colorShares;
+exports.judgeBrandPalette = judgeBrandPalette;
+exports.judgeBeat = judgeBeat;
+exports.judgeGlow = judgeGlow;
+exports.runRenderChecks = runRenderChecks;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const capture_1 = require("@openvidstudio/capture");
+const remotionBridge_1 = require("../remotionBridge");
+const sharp_1 = __importDefault(require("sharp"));
+const frameDiff_1 = require("../frameDiff");
+const lessonArc_1 = require("../lessonArc");
+const util_1 = require("../util");
+const validateBeats_1 = require("./validateBeats");
+Object.defineProperty(exports, "MAX_READING_WORDS_PER_SEC", { enumerable: true, get: function () { return validateBeats_1.MAX_READING_WORDS_PER_SEC; } });
+Object.defineProperty(exports, "READING_OVERHEAD_SEC", { enumerable: true, get: function () { return validateBeats_1.READING_OVERHEAD_SEC; } });
+/** WCAG 2.x contrast minimums: ordinary text, and large text (24px and up on screen). */
+const MIN_CONTRAST = 4.5;
+const MIN_CONTRAST_LARGE = 3;
+const LARGE_TEXT_PX = 24;
+/** Below this ratio the text is close to unreadable rather than merely weak: an error. */
+const ILLEGIBLE_CONTRAST = 3;
+/**
+ * The title-safe inset: text closer than this to a frame edge risks being clipped by a
+ * player, a crop to another aspect ratio, or a platform's own UI. Fractions of width/height.
+ * Not the layout grid's margins (those are a design choice), but a floor under them.
+ */
+const SAFE_INSET_X = 0.04;
+const SAFE_INSET_Y = 0.05;
+/** Sub-pixel and antialiasing slop before overhang past the safe area counts. */
+const SAFE_SLOP_PX = 2;
+/** Share of a text box covered by a HUD element before it counts as an overlap. */
+const HUD_OVERLAP_RATIO = 0.08;
+/** Frames of a beat that get measured, as fractions of its duration. */
+const SAMPLE_FRACTIONS = [0.1, 0.3, 0.5, 0.7, 0.9];
+/** A crop counts only when it shows in at least this many samples, so a slide-in is not one. */
+const MIN_CROPPED_SAMPLES = 3;
+/** Share of a text's box that is outside the frame before it counts as cropped. */
+const CROP_RATIO = 0.02;
+/** And the least overhang, in output pixels, so sub-pixel antialiasing never counts. */
+const CROP_MIN_PX = 4;
+/**
+ * Two sampled frames of a dead beat are compared at this changed-pixel ratio. Real motion,
+ * even a slow camera push, moves far more than this; film grain and encoder noise are
+ * averaged out by frameDiff's downscale before it is measured.
+ */
+const DEAD_CHANGED_RATIO = 0.002;
+/** Seek and mount timeout per beat. Short on purpose: a beat that cannot mount is skipped. */
+const BEAT_TIMEOUT_MS = 12000;
+/**
+ * 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.
+ */
+exports.DEFAULT_TYPE_MINIMUMS = { body: 26, mono: 15, label: 16 };
+/**
+ * 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.
+ */
+function readTypeMinimums(videoDir) {
+    const out = { ...exports.DEFAULT_TYPE_MINIMUMS };
+    const file = path.join(videoDir, "design.ts");
+    if (!fs.existsSync(file))
+        return out;
+    const src = fs.readFileSync(file, "utf8");
+    for (const key of ["body", "mono"]) {
+        const m = src.match(new RegExp(`\\b${key}\\s*:\\s*\\[\\s*(\\d+(?:\\.\\d+)?)\\s*,`));
+        if (m)
+            out[key] = Number.parseFloat(m[1]);
+    }
+    return out;
+}
+/**
+ * Runs in the page. Written as a self-contained function because page.evaluate serializes
+ * it: nothing from this module's scope exists on the other side.
+ */
+function probePage(args) {
+    const W = window.innerWidth;
+    const H = window.innerHeight;
+    const safe = { l: W * args.safeX, t: H * args.safeY, r: W * (1 - args.safeX), b: H * (1 - args.safeY) };
+    const stage = document.querySelector("[data-ovs-camera-stage]");
+    let stageScale = 1;
+    if (stage) {
+        const m = new DOMMatrixReadOnly(getComputedStyle(stage).transform);
+        stageScale = Math.hypot(m.m11, m.m12) || 1;
+    }
+    const area = (b) => Math.max(0, b.r - b.l) * Math.max(0, b.b - b.t);
+    const intersect = (a, b) => ({
+        l: Math.max(a.l, b.l),
+        t: Math.max(a.t, b.t),
+        r: Math.min(a.r, b.r),
+        b: Math.min(a.b, b.b),
+    });
+    // HUD elements (ChapterHud) are chrome that other text must stay clear of.
+    const huds = [];
+    document.querySelectorAll("[data-ovs-hud]").forEach((h) => {
+        const r = h.getBoundingClientRect();
+        let o = 1;
+        for (let a = h; a && a !== document.body; a = a.parentElement) {
+            o *= Number.parseFloat(getComputedStyle(a).opacity);
+        }
+        if (r.width > 0 && r.height > 0 && o >= 0.3)
+            huds.push({ l: r.left, t: r.top, r: r.right, b: r.bottom });
+    });
+    const out = [];
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    let node;
+    while ((node = walker.nextNode())) {
+        const text = (node.textContent ?? "").replace(/\s+/g, " ").trim();
+        const el = node.parentElement;
+        if (!text || !el)
+            continue;
+        if (["SCRIPT", "STYLE", "NOSCRIPT"].includes(el.tagName))
+            continue;
+        const inStage = !!stage && stage.contains(el);
+        let opacity = 1;
+        let hidden = false;
+        let label = false;
+        let hud = false;
+        const clips = [];
+        for (let a = el; a && a !== document.body; a = a.parentElement) {
+            const cs = getComputedStyle(a);
+            if (cs.display === "none" || cs.visibility === "hidden")
+                hidden = true;
+            if (a.hasAttribute("data-ovs-label"))
+                label = true;
+            if (a.hasAttribute("data-ovs-hud"))
+                hud = true;
+            opacity *= Number.parseFloat(cs.opacity);
+            // An overflow clip inside the stage hides text on purpose (a scrolling terminal, a
+            // masked reveal). The stage's own parent is the camera viewport and is the crop this
+            // check exists to find, so the walk stops being a clip source at the stage itself.
+            if (inStage && a !== stage && stage.contains(a) && cs.overflow !== "visible") {
+                const r = a.getBoundingClientRect();
+                clips.push({ l: r.left, t: r.top, r: r.right, b: r.bottom });
+            }
+            if (a === stage)
+                break;
+        }
+        if (hidden || opacity < 0.15)
+            continue;
+        const range = document.createRange();
+        range.selectNodeContents(node);
+        const rr = range.getBoundingClientRect();
+        let box = { l: rr.left, t: rr.top, r: rr.right, b: rr.bottom };
+        if (area(box) === 0)
+            continue;
+        for (const c of clips)
+            box = intersect(box, c);
+        if (area(box) === 0)
+            continue; // clipped away entirely by an internal container
+        const inFrame = intersect(box, { l: 0, t: 0, r: W, b: H });
+        const croppedRatio = 1 - area(inFrame) / area(box);
+        const overhangPx = Math.max(-box.l, -box.t, box.r - W, box.b - H, 0);
+        const cs = getComputedStyle(el);
+        const safeOverhangPx = Math.max(safe.l - box.l, safe.t - box.t, box.r - safe.r, box.b - safe.b, 0);
+        let hudOverlap = 0;
+        if (!hud) {
+            for (const h of huds)
+                hudOverlap = Math.max(hudOverlap, area(intersect(box, h)) / area(box));
+        }
+        // SVG text is painted with `fill`; its CSS `color` is just what it inherited and is not what is drawn.
+        const paint = el instanceof SVGElement ? cs.fill : cs.color;
+        const nums = (paint.match(/[\d.]+/g) ?? []).map(Number);
+        const rgba = nums.length >= 3 ? [nums[0], nums[1], nums[2], nums.length >= 4 ? nums[3] : 1] : undefined;
+        out.push({
+            text,
+            fontPx: Number.parseFloat(cs.fontSize) * (inStage ? stageScale : 1),
+            mono: /mono|courier|consolas|menlo|code/i.test(cs.fontFamily),
+            label,
+            inStage,
+            opacity,
+            croppedRatio,
+            overhangPx,
+            hud,
+            safeOverhangPx,
+            hudOverlap,
+            rgba,
+            box,
+        });
+    }
+    return out;
+}
+/** A weak-contrast text must show it in this many sampled frames, so a fade-in is not one. */
+const MIN_CONTRAST_SAMPLES = 2;
+function channelLuminance(c) {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+function luminance(rgb) {
+    return 0.2126 * channelLuminance(rgb[0]) + 0.7152 * channelLuminance(rgb[1]) + 0.0722 * channelLuminance(rgb[2]);
+}
+/**
+ * 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.
+ */
+function contrastAgainst(rgba, opacity, bg) {
+    const a = Math.min(1, Math.max(0, rgba[3] * opacity));
+    const fg = [
+        rgba[0] * a + bg[0] * (1 - a),
+        rgba[1] * a + bg[1] * (1 - a),
+        rgba[2] * a + bg[2] * (1 - a),
+    ];
+    const l1 = luminance(fg);
+    const l2 = luminance(bg);
+    return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+/**
+ * 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).
+ */
+function backgroundBehind(pixels, width, height, channels, box, ringPx) {
+    const outer = {
+        l: Math.max(0, Math.floor(box.l - ringPx)),
+        t: Math.max(0, Math.floor(box.t - ringPx)),
+        r: Math.min(width, Math.ceil(box.r + ringPx)),
+        b: Math.min(height, Math.ceil(box.b + ringPx)),
+    };
+    const collect = (wantInside) => {
+        const reg = wantInside
+            ? { l: Math.max(0, Math.floor(box.l)), t: Math.max(0, Math.floor(box.t)), r: Math.min(width, Math.ceil(box.r)), b: Math.min(height, Math.ceil(box.b)) }
+            : outer;
+        const step = Math.max(1, Math.floor(Math.sqrt(((reg.r - reg.l) * (reg.b - reg.t)) / 4000)));
+        const ch = [[], [], []];
+        for (let y = reg.t; y < reg.b; y += step) {
+            for (let x = reg.l; x < reg.r; x += step) {
+                const inside = x >= box.l && x < box.r && y >= box.t && y < box.b;
+                if (!wantInside && inside)
+                    continue;
+                const i = (y * width + x) * channels;
+                ch[0].push(pixels[i]);
+                ch[1].push(pixels[i + 1]);
+                ch[2].push(pixels[i + 2]);
+            }
+        }
+        return ch;
+    };
+    let ch = collect(false);
+    if (ch[0].length < 8)
+        ch = collect(true);
+    if (ch[0].length === 0)
+        return null;
+    const median = (v) => v.sort((a, b) => a - b)[Math.floor(v.length / 2)];
+    return [median(ch[0]), median(ch[1]), median(ch[2])];
+}
+/**
+ * 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.
+ */
+function readDeliberateHolds(videoDir) {
+    try {
+        const brief = JSON.parse(fs.readFileSync(path.join(videoDir, "brief.json"), "utf8"));
+        if (!Array.isArray(brief.shotList))
+            return [];
+        return brief.shotList
+            .filter((s) => typeof s === "object" && s !== null && s.deliberateHold === true && typeof s.beatId === "string")
+            .map((s) => s.beatId);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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.
+ */
+function brandHexColors(projectRoot) {
+    const file = path.join(projectRoot, "src", "brand.ts");
+    if (!fs.existsSync(file))
+        return [];
+    const found = fs.readFileSync(file, "utf8").match(/#[0-9a-fA-F]{6}\b/g) ?? [];
+    const unique = [...new Set(found.map((h) => h.toLowerCase()))];
+    return unique.filter((h) => {
+        const [r, g, b] = hexToRgb(h);
+        const nearBlack = r < 12 && g < 12 && b < 12;
+        const nearWhite = r > 243 && g > 243 && b > 243;
+        return !nearBlack && !nearWhite;
+    });
+}
+function hexToRgb(hex) {
+    const n = Number.parseInt(hex.slice(1), 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+/** Colour distance, per channel, within which a rendered pixel counts as "that brand colour". */
+const BRAND_TOLERANCE = 22;
+/** A brand colour is present in a frame when at least this share of its pixels match. */
+const BRAND_MIN_SHARE = 0.0002;
+/**
+ * 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.
+ */
+function colorShares(pixels, width, height, channels, colors) {
+    const rgb = colors.map(hexToRgb);
+    const hits = new Array(colors.length).fill(0);
+    const step = 3;
+    let total = 0;
+    for (let y = 0; y < height; y += step) {
+        for (let x = 0; x < width; x += step) {
+            const i = (y * width + x) * channels;
+            const r = pixels[i];
+            const g = pixels[i + 1];
+            const b = pixels[i + 2];
+            total++;
+            for (let c = 0; c < rgb.length; c++) {
+                const [cr, cg, cb] = rgb[c];
+                if (Math.abs(r - cr) <= BRAND_TOLERANCE && Math.abs(g - cg) <= BRAND_TOLERANCE && Math.abs(b - cb) <= BRAND_TOLERANCE)
+                    hits[c]++;
+            }
+        }
+    }
+    return new Map(colors.map((c, i) => [c, total === 0 ? 0 : hits[i] / total]));
+}
+/**
+ * Reads the frame once and does both per-frame measurements: the background behind each text
+ * box (for contrast) and how much of each brand colour is on screen (for the palette check).
+ */
+async function measureFrame(shot, probes, brandColors) {
+    const { data, info } = await (0, sharp_1.default)(shot).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+    for (const p of probes) {
+        if (!p.box || p.hud)
+            continue;
+        p.bg = backgroundBehind(data, info.width, info.height, info.channels, p.box, Math.max(4, Math.round(p.fontPx * 0.25)));
+    }
+    return brandColors.length > 0 ? colorShares(data, info.width, info.height, info.channels, brandColors) : new Map();
+}
+/** Pure: the palette finding, given the largest share each brand colour reached in any sampled frame. */
+function judgeBrandPalette(maxShare) {
+    if (maxShare.size === 0)
+        return [];
+    const present = [...maxShare].filter(([, share]) => share >= BRAND_MIN_SHARE);
+    if (present.length > 0)
+        return [];
+    return [
+        {
+            beatId: "*",
+            scene: "brand.ts",
+            source: "render",
+            check: "brand-palette",
+            severity: "warning",
+            message: `src/brand.ts sets ${[...maxShare.keys()].join(", ")}, but none of those colours appears in any rendered ` +
+                `frame, so the palette never reached the picture and the video is still in the default colours. Usual ` +
+                `causes: brand.ts is not the FIRST import in Root.tsx, so scenes evaluated before applyBrand ran, or a ` +
+                `bundler dropped the import as side-effect free (package.json "sideEffects" must list ./src/brand.ts).`,
+        },
+    ];
+}
+function wordsIn(text) {
+    return /[\p{L}]/u.test(text) ? text.split(/\s+/).filter((w) => /[\p{L}\p{N}]/u.test(w)).length : 0;
+}
+function examples(items) {
+    const shown = items.slice(0, 3).map((t) => `"${t.length > 40 ? `${t.slice(0, 40)}...` : t}"`);
+    return shown.join(", ") + (items.length > 3 ? `, and ${items.length - 3} more` : "");
+}
+/**
+ * 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.
+ */
+function judgeBeat(opts) {
+    const { beat, fps, minimums, samples, maxChangedRatio } = opts;
+    const scene = `${(0, util_1.pascalCase)(beat.id)}.tsx`;
+    const base = { beatId: beat.id, scene, source: "render" };
+    const findings = [];
+    // Crop: stage text outside the frame in most of the samples.
+    const croppedIn = new Map();
+    for (const probes of samples) {
+        const seen = new Set();
+        for (const p of probes) {
+            if (p.inStage && p.opacity >= 0.5 && p.croppedRatio > CROP_RATIO && p.overhangPx > CROP_MIN_PX) {
+                seen.add(p.text);
+            }
+        }
+        for (const t of seen)
+            croppedIn.set(t, (croppedIn.get(t) ?? 0) + 1);
+    }
+    const cropped = [...croppedIn].filter(([, n]) => n >= Math.min(MIN_CROPPED_SAMPLES, samples.length)).map(([t]) => t);
+    if (cropped.length > 0) {
+        findings.push({
+            ...base,
+            check: "crop",
+            severity: "error",
+            message: `Rendered text is cut off at the frame edge in ${cropped.length} place(s): ${examples(cropped)}. ` +
+                `Measured on the real rendered DOM, not the source. Narrow the content, move it inward, or lower the camera scale.`,
+        });
+    }
+    // Text size: the smallest on-screen size, against the design system's minimum.
+    const small = new Map();
+    for (const probes of samples) {
+        for (const p of probes) {
+            if (p.hud)
+                continue; // HUD chrome is deliberately small
+            const min = p.mono ? minimums.mono : p.label ? minimums.label : minimums.body;
+            if (p.fontPx < min - 0.5)
+                small.set(p.text, Math.min(small.get(p.text) ?? Infinity, p.fontPx));
+        }
+    }
+    if (small.size > 0) {
+        const worst = Math.min(...small.values());
+        findings.push({
+            ...base,
+            check: "text-size",
+            severity: "warning",
+            message: `${small.size} text run(s) render below the minimum size (body ${minimums.body}px, mono ${minimums.mono}px, ` +
+                `label ${minimums.label}px for a Pill/ToolChip, body/mono taken from this video's design.ts or the ` +
+                `default type scale): ${examples([...small.keys()])}. The smallest is ${worst.toFixed(1)}px on screen, ` +
+                `camera scale included. Raise the font size or the minimum.`,
+        });
+    }
+    // Reading time: unique non-code text seen in the beat, against how long the beat is up.
+    const unique = new Set();
+    for (const probes of samples)
+        for (const p of probes)
+            if (!p.mono && !p.hud)
+                unique.add(p.text);
+    const words = [...unique].reduce((n, t) => n + wordsIn(t), 0);
+    const seconds = beat.duration / fps;
+    const needed = words / validateBeats_1.MAX_READING_WORDS_PER_SEC + validateBeats_1.READING_OVERHEAD_SEC;
+    if (words > 0 && needed > seconds) {
+        findings.push({
+            ...base,
+            check: "reading-time",
+            severity: "warning",
+            message: `${words} words of on-screen text need about ${needed.toFixed(1)}s to read ` +
+                `(${validateBeats_1.MAX_READING_WORDS_PER_SEC} words/sec plus ${validateBeats_1.READING_OVERHEAD_SEC}s to land on it), but the beat is on ` +
+                `screen for ${seconds.toFixed(1)}s. Cut the copy or lengthen the beat.`,
+        });
+    }
+    // Em dashes in on-screen copy. The house rule is absolute, and a render is the one place the
+    // source cannot give it away: copy assembled from variables or facts only exists here.
+    const withEmDash = new Set();
+    for (const probes of samples)
+        for (const p of probes)
+            if (p.text.includes("\u2014"))
+                withEmDash.add(p.text);
+    if (withEmDash.size > 0) {
+        findings.push({
+            ...base,
+            check: "em-dash",
+            severity: "error",
+            message: `${withEmDash.size} on-screen text run(s) contain an em dash: ${examples([...withEmDash])}. ` +
+                `Rewrite with a comma, colon, period or parentheses.`,
+        });
+    }
+    // Safe area: text that fits the frame but sits closer to its edge than a player or platform
+    // reliably shows. Separate from crop, which is text actually cut off.
+    const unsafe = new Map();
+    for (const probes of samples) {
+        const seen = new Set();
+        for (const p of probes) {
+            if (!p.hud && p.opacity >= 0.5 && (p.safeOverhangPx ?? 0) > SAFE_SLOP_PX && p.overhangPx <= CROP_MIN_PX)
+                seen.add(p.text);
+        }
+        for (const t of seen)
+            unsafe.set(t, (unsafe.get(t) ?? 0) + 1);
+    }
+    const outsideSafe = [...unsafe].filter(([, n]) => n >= Math.min(MIN_CROPPED_SAMPLES, samples.length)).map(([t]) => t);
+    if (outsideSafe.length > 0) {
+        findings.push({
+            ...base,
+            check: "safe-area",
+            severity: "warning",
+            message: `${outsideSafe.length} text run(s) sit outside the title-safe area (${SAFE_INSET_X * 100}% in from the sides, ` +
+                `${SAFE_INSET_Y * 100}% from top and bottom): ${examples(outsideSafe)}. They are inside the frame, but a ` +
+                `player, a crop to another aspect ratio or a platform's own UI can clip them. Move them inward.`,
+        });
+    }
+    // HUD overlap: text drawn over the chapter HUD, which is chrome the viewer reads as a fixed layer.
+    const hudHits = new Map();
+    for (const probes of samples) {
+        const seen = new Set();
+        for (const p of probes)
+            if (!p.hud && p.opacity >= 0.5 && (p.hudOverlap ?? 0) > HUD_OVERLAP_RATIO)
+                seen.add(p.text);
+        for (const t of seen)
+            hudHits.set(t, (hudHits.get(t) ?? 0) + 1);
+    }
+    const overHud = [...hudHits].filter(([, n]) => n >= Math.min(MIN_CROPPED_SAMPLES, samples.length)).map(([t]) => t);
+    if (overHud.length > 0) {
+        findings.push({
+            ...base,
+            check: "hud-overlap",
+            severity: "warning",
+            message: `${overHud.length} text run(s) overlap the chapter HUD: ${examples(overHud)}. Keep scene copy clear of the ` +
+                `HUD's top-left label and bottom rail, or move the HUD.`,
+        });
+    }
+    // Contrast: the text colour against the background actually rendered behind it.
+    const weak = new Map();
+    for (const probes of samples) {
+        const seen = new Map();
+        for (const p of probes) {
+            if (p.hud || p.opacity < 0.5 || !p.rgba || !p.bg || p.rgba[3] < 0.2)
+                continue;
+            const ratio = contrastAgainst(p.rgba, p.opacity, p.bg);
+            const min = p.fontPx >= LARGE_TEXT_PX ? MIN_CONTRAST_LARGE : MIN_CONTRAST;
+            if (ratio < min)
+                seen.set(p.text, Math.min(seen.get(p.text) ?? Infinity, ratio));
+        }
+        for (const [t, r] of seen) {
+            const prev = weak.get(t);
+            weak.set(t, { ratio: Math.min(prev?.ratio ?? Infinity, r), n: (prev?.n ?? 0) + 1 });
+        }
+    }
+    const lowContrast = [...weak].filter(([, v]) => v.n >= Math.min(MIN_CONTRAST_SAMPLES, samples.length));
+    if (lowContrast.length > 0) {
+        const worst = Math.min(...lowContrast.map(([, v]) => v.ratio));
+        findings.push({
+            ...base,
+            check: "contrast",
+            severity: worst < ILLEGIBLE_CONTRAST ? "error" : "warning",
+            message: `${lowContrast.length} text run(s) fall below the contrast minimum (${MIN_CONTRAST}:1 for text under ` +
+                `${LARGE_TEXT_PX}px, ${MIN_CONTRAST_LARGE}:1 above): ${examples(lowContrast.map(([t]) => t))}. The weakest is ` +
+                `${worst.toFixed(2)}:1, measured against the pixels rendered behind the text. Change the text colour or the ` +
+                `surface behind it.`,
+        });
+    }
+    // Dead frames.
+    if (!opts.deliberateHold && maxChangedRatio !== null && maxChangedRatio < DEAD_CHANGED_RATIO) {
+        findings.push({
+            ...base,
+            check: "dead-frames",
+            severity: "warning",
+            message: `Frames sampled across this beat are identical (largest change ${(maxChangedRatio * 100).toFixed(3)}% ` +
+                `of pixels). Nothing moves for ${seconds.toFixed(1)}s. STYLE.md fails a static frame.`,
+        });
+    }
+    return findings;
+}
+/**
+ * Runs in the page. Reads the `data-ovs-glow` / `data-ovs-glow-level` attributes that stem's Glow helper
+ * writes, which is how a frame's glowing elements are counted without guessing from pixels. Self-contained
+ * for the same reason as probePage.
+ */
+function probeGlow() {
+    return Array.from(document.querySelectorAll("[data-ovs-glow]")).map((el) => ({
+        kind: el.getAttribute("data-ovs-glow") ?? "",
+        level: Number.parseFloat(el.getAttribute("data-ovs-glow-level") ?? "0") || 0,
+    }));
+}
+/** An element counts as glowing above this level, the same threshold stem's countGlowing uses. */
+const GLOW_VISIBLE_LEVEL = 0.05;
+/**
+ * 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.
+ */
+function judgeGlow(beat, samples, frames) {
+    const base = { beatId: beat.id, scene: `${(0, util_1.pascalCase)(beat.id)}.tsx`, source: "render" };
+    if (samples.some((s) => s.some((g) => g.kind === "nova")))
+        return [];
+    let worst = 0;
+    let worstFrame = frames[0] ?? beat.start;
+    samples.forEach((s, i) => {
+        const glowing = s.filter((g) => g.level > GLOW_VISIBLE_LEVEL).length;
+        if (glowing > worst) {
+            worst = glowing;
+            worstFrame = frames[i] ?? worstFrame;
+        }
+    });
+    if (worst <= 1)
+        return [];
+    return [
+        {
+            ...base,
+            check: "glow-budget",
+            severity: worst > 2 ? "error" : "warning",
+            message: `${worst} elements glow at once (frame ${worstFrame - beat.start} of the beat). Void + Spark allows one glowing ` +
+                `element at a time: light is meaning, so when everything glows nothing is the point. ` +
+                `${worst > 2 ? "More than two is an error. " : ""}Dim all but the one the viewer must look at. ` +
+                `(A beat with a Nova is exempt.)`,
+        },
+    ];
+}
+/** Runs in the page: the boxes of the lesson's captions (LessonCaptions marks them), in frame pixels. */
+function probeCaptionBoxes() {
+    return Array.from(document.querySelectorAll("[data-ovs-captions]")).map((el) => {
+        const r = el.getBoundingClientRect();
+        return { x: r.x, y: r.y, width: r.width, height: r.height };
+    });
+}
+function sampleFrames(beat) {
+    const last = Math.max(0, beat.duration - 1);
+    const frames = SAMPLE_FRACTIONS.map((f) => beat.start + Math.min(last, Math.round(beat.duration * f)));
+    return [...new Set(frames)];
+}
+async function runRenderChecks(input) {
+    const started = Date.now();
+    const bundleStarted = Date.now();
+    // A caller that already bundled (render_stills) passes its bundle in, so the project is not
+    // run through webpack twice in one call.
+    const bundleDir = input.bundleDir ?? (await (0, remotionBridge_1.bundleProject)(input.projectRoot));
+    const bundleMs = input.bundleDir ? 0 : Date.now() - bundleStarted;
+    const server = await (0, remotionBridge_1.serveBundleDirectory)(bundleDir);
+    const remotionBrowser = await (0, remotionBridge_1.openRenderBrowser)();
+    let browser = null;
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-validate-scenes-"));
+    const findings = [];
+    const skipped = [];
+    let measured = 0;
+    // Largest share of each brand colour seen in any sampled frame, for the palette check.
+    const brandColors = brandHexColors(input.projectRoot);
+    const brandSeen = new Map(brandColors.map((c) => [c, 0]));
+    const arcSamples = [];
+    let arcPrevious = null;
+    try {
+        const composition = await (0, remotionBridge_1.resolveComposition)(bundleDir, input.compositionId, remotionBrowser);
+        browser = await (0, capture_1.launchChromium)();
+        // Opened lazily on the beat being measured, at that beat's own first sample frame, never up
+        // front at frame 0: a page that mounts the first beat of the composition fails for every
+        // beat if that one beat cannot render (a capture that was never taken holds its render open).
+        const openPage = async (initialFrame) => {
+            const opened = await browser.newPage({
+                viewport: { width: composition.width, height: composition.height },
+                deviceScaleFactor: 1,
+            });
+            try {
+                await (0, remotionBridge_1.openSeekablePage)({ page: opened, bundleUrl: server.url, composition, timeoutMs: BEAT_TIMEOUT_MS, initialFrame });
+            }
+            catch (err) {
+                await opened.close().catch(() => undefined);
+                throw err;
+            }
+            return opened;
+        };
+        let page = null;
+        for (const beat of input.beats) {
+            try {
+                const samples = [];
+                const glowSamples = [];
+                const shots = [];
+                const frames = sampleFrames(beat);
+                if (!page)
+                    page = await openPage(frames[0]);
+                for (const [i, frame] of frames.entries()) {
+                    await (0, remotionBridge_1.seekToFrame)(page, composition.id, frame, BEAT_TIMEOUT_MS);
+                    const probes = await page.evaluate(probePage, { safeX: SAFE_INSET_X, safeY: SAFE_INSET_Y });
+                    if (input.glowBudget)
+                        glowSamples.push(await page.evaluate(probeGlow));
+                    const shot = path.join(scratch, `${beat.id}-${i}.png`);
+                    await page.screenshot({ path: shot });
+                    shots.push(shot);
+                    if (input.arc) {
+                        const arc = await (0, lessonArc_1.measureArcFrame)(shot, await page.evaluate(probeCaptionBoxes), arcPrevious);
+                        arcPrevious = arc.signature;
+                        arcSamples.push({ time: frame / input.fps, beatId: beat.id, drawn: arc.drawn, changedFromPrevious: arc.changedFromPrevious });
+                    }
+                    const shares = await measureFrame(shot, probes, brandColors);
+                    for (const [hex, share] of shares)
+                        brandSeen.set(hex, Math.max(brandSeen.get(hex) ?? 0, share));
+                    samples.push(probes);
+                }
+                let maxChangedRatio = null;
+                if (shots.length >= 2) {
+                    maxChangedRatio = 0;
+                    for (let i = 1; i < shots.length; i++) {
+                        const cmp = await (0, frameDiff_1.compareFrames)(shots[0], shots[i]);
+                        maxChangedRatio = Math.max(maxChangedRatio, cmp.changedRatio);
+                    }
+                }
+                if (input.glowBudget)
+                    findings.push(...judgeGlow(beat, glowSamples, frames));
+                findings.push(...judgeBeat({
+                    beat,
+                    fps: input.fps,
+                    minimums: input.minimums,
+                    samples,
+                    maxChangedRatio,
+                    deliberateHold: input.deliberateHolds?.includes(beat.id),
+                }));
+                measured++;
+            }
+            catch (err) {
+                // A beat that cannot mount (a recording through OffthreadVideo is the known case, see
+                // openSeekablePage) is reported as skipped. It is never treated as "no findings".
+                const reason = err instanceof Error ? err.message : String(err);
+                skipped.push({ beatId: beat.id, reason: err instanceof remotionBridge_1.RemotionBridgeProtocolError ? reason.split(" Original:")[0] : reason });
+                findings.push({
+                    beatId: beat.id,
+                    scene: `${(0, util_1.pascalCase)(beat.id)}.tsx`,
+                    source: "render",
+                    check: "render-skipped",
+                    severity: "warning",
+                    message: `Render-based checks could not run for this beat, so it was NOT measured: ${skipped[skipped.length - 1].reason}`,
+                });
+                arcPrevious = null;
+                // The page may be wedged mid-mount; the next beat gets a fresh one.
+                await page?.close().catch(() => undefined);
+                page = null;
+            }
+        }
+        await page?.close().catch(() => undefined);
+        // Only judged when at least one beat was actually measured: with nothing rendered there is
+        // no frame to find the palette in, and saying it is missing would be a false alarm.
+        if (measured > 0)
+            findings.push(...judgeBrandPalette(brandSeen));
+        // A lesson that skipped a beat has a hole in its samples, and a hole reads as a static stretch or a late
+        // diagram that may not be there. Judged only when every beat was measured.
+        if (input.arc && measured === input.beats.length && measured > 0) {
+            const lessonSeconds = input.lessonSeconds ?? Math.max(...input.beats.map((b) => b.start + b.duration)) / input.fps;
+            for (const f of (0, lessonArc_1.judgeLessonArc)(arcSamples, lessonSeconds, input.arc)) {
+                findings.push({
+                    beatId: f.beatId,
+                    scene: f.beatId === "*" ? "beats.json" : `${(0, util_1.pascalCase)(f.beatId)}.tsx`,
+                    source: "render",
+                    check: f.check,
+                    severity: f.severity,
+                    message: f.message,
+                });
+            }
+        }
+    }
+    finally {
+        await browser?.close().catch(() => undefined);
+        await remotionBrowser.close({ silent: true });
+        await server.close();
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+    return { findings, beatsMeasured: measured, beatsSkipped: skipped, bundleMs, totalMs: Date.now() - started };
+}