@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/canvasValidate.d.ts

@@ -0,0 +1,76 @@
+import type { SceneFinding } from "./tools/validateScenes";
+/**
+ * validate_canvas_explainer: what validate_scenes does for a Remotion composition, for a canvas explainer. There is
+ * no composition to inspect, so the file is loaded in headless Chromium and driven through window.seek(t). The
+ * checks are the rules that make phone viewing work: a frame is a pure function of t, text is big enough, nothing
+ * sits under the platform's interface, the picture is not blank or still for long, the sound is not a pile-up, and
+ * nothing calls Math.random. Findings have the shape validate_scenes returns (beatId, scene, severity, check, message).
+ */
+/** The text minimums at the reference canvas (720 on the shorter side), in px. Headlines 44, labels 28, key numbers 64. */
+export declare const TEXT_MINIMUMS: {
+    readonly headline: 44;
+    readonly label: 28;
+    readonly number: 64;
+};
+/** The safe areas of a tall canvas: the top share and the bottom share kept clear. */
+export declare const SAFE_TOP = 0.14;
+export declare const SAFE_BOTTOM = 0.22;
+/** More sources than this playing at once is a pile-up. */
+export declare const MAX_SIMULTANEOUS_SOUNDS = 3;
+export interface CanvasValidateInput {
+    projectRoot?: string;
+    htmlPath: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    /** A project video: its beats become window.BEATS and its captions are drawn, as in the render. */
+    videoName?: string;
+    /** Also render the score and judge the sound. Default true. */
+    audio?: boolean;
+    /** Pixels at the reference size are scaled by min(width, height) / 720 unless this says otherwise. */
+    textScale?: number;
+    diagramWarnSeconds?: number;
+    diagramErrorSeconds?: number;
+    staticSeconds?: number;
+}
+export interface CanvasValidateResult {
+    /** False when any finding is an error. */
+    ok: boolean;
+    findings: SceneFinding[];
+    durationSeconds: number;
+    width: number;
+    height: number;
+    /** The scale the text minimums were multiplied by. */
+    textScale: number;
+    framesSampled: number;
+    /** Smallest non-caption text drawn, in px at the canvas size, or null when no text was drawn. */
+    minTextSize: number | null;
+    sound: {
+        maxSimultaneous: number;
+        peakDb: number | null;
+        sources: number;
+    } | null;
+    elapsedMs: number;
+}
+interface TextRecord {
+    text: string;
+    size: number;
+    x: number;
+    y: number;
+    caption: boolean;
+}
+interface SourceRecord {
+    start: number;
+    stop: number | null;
+    duration: number | null;
+    bufferSeconds: number | null;
+    loop: boolean;
+}
+/** Pure: is this text a figure (a number with at most a unit), which is held to the key number minimum when it is drawn big. */
+export declare function isKeyNumber(text: string): boolean;
+/** Pure: the most sources playing at once. A source with no stop and no length plays to `end`. */
+export declare function maxSimultaneous(sources: SourceRecord[], end: number): number;
+/** Pure: the text findings for the texts drawn in the sampled frames. */
+export declare function judgeText(texts: TextRecord[], width: number, height: number, scale: number, scene: string): SceneFinding[];
+export declare function validateCanvasExplainer(input: CanvasValidateInput): Promise<CanvasValidateResult>;
+export {};

package/dist/canvasValidate.js

@@ -0,0 +1,263 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SIMULTANEOUS_SOUNDS = exports.SAFE_BOTTOM = exports.SAFE_TOP = exports.TEXT_MINIMUMS = void 0;
+exports.isKeyNumber = isKeyNumber;
+exports.maxSimultaneous = maxSimultaneous;
+exports.judgeText = judgeText;
+exports.validateCanvasExplainer = validateCanvasExplainer;
+const crypto = __importStar(require("node:crypto"));
+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 canvasExplainer_1 = require("./canvasExplainer");
+const lessonArc_1 = require("./lessonArc");
+const util_1 = require("./util");
+/**
+ * validate_canvas_explainer: what validate_scenes does for a Remotion composition, for a canvas explainer. There is
+ * no composition to inspect, so the file is loaded in headless Chromium and driven through window.seek(t). The
+ * checks are the rules that make phone viewing work: a frame is a pure function of t, text is big enough, nothing
+ * sits under the platform's interface, the picture is not blank or still for long, the sound is not a pile-up, and
+ * nothing calls Math.random. Findings have the shape validate_scenes returns (beatId, scene, severity, check, message).
+ */
+/** The text minimums at the reference canvas (720 on the shorter side), in px. Headlines 44, labels 28, key numbers 64. */
+exports.TEXT_MINIMUMS = { headline: 44, label: 28, number: 64 };
+/** Text this much bigger than the label minimum was meant to be a headline or a number, and is held to its minimum. */
+const DISPLAY_FACTOR = 1.2;
+/** The safe areas of a tall canvas: the top share and the bottom share kept clear. */
+exports.SAFE_TOP = 0.14;
+exports.SAFE_BOTTOM = 0.22;
+/** More sources than this playing at once is a pile-up. */
+exports.MAX_SIMULTANEOUS_SOUNDS = 3;
+/** The shortest gap between frames sampled for the arc checks, and the most frames sampled. */
+const MIN_SAMPLE_GAP_SECONDS = 0.5;
+const MAX_SAMPLES = 120;
+const NUMERIC = /^\s*[-+−~]?\s*[$₹€£]?\s*\d[\d.,\s]*\s*(%|[a-zA-Zµ°/²³^]{0,6})\s*$/;
+/** Pure: is this text a figure (a number with at most a unit), which is held to the key number minimum when it is drawn big. */
+function isKeyNumber(text) {
+    return NUMERIC.test(text);
+}
+/** Pure: the most sources playing at once. A source with no stop and no length plays to `end`. */
+function maxSimultaneous(sources, end) {
+    const events = [];
+    for (const s of sources) {
+        let stop;
+        if (s.stop !== null)
+            stop = s.duration !== null ? Math.min(s.stop, s.start + s.duration) : s.stop;
+        else if (s.duration !== null)
+            stop = s.start + s.duration;
+        else if (s.bufferSeconds !== null && !s.loop)
+            stop = s.start + s.bufferSeconds;
+        else
+            stop = end;
+        if (stop > s.start) {
+            events.push([s.start, 1]);
+            events.push([stop, -1]);
+        }
+    }
+    // At the same instant, what ends counts before what begins.
+    events.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    let now = 0;
+    let max = 0;
+    for (const [, delta] of events) {
+        now += delta;
+        max = Math.max(max, now);
+    }
+    return max;
+}
+/** Pure: the text findings for the texts drawn in the sampled frames. */
+function judgeText(texts, width, height, scale, scene) {
+    // One finding per distinct text and rule, the worst one kept.
+    const found = new Map();
+    const add = (key, severity, check, message) => {
+        const have = found.get(key);
+        if (have && (have.severity === "error" || severity === "warning"))
+            return;
+        found.set(key, { beatId: "*", scene, severity, message, source: "render", check });
+    };
+    const label = exports.TEXT_MINIMUMS.label * scale;
+    const headline = exports.TEXT_MINIMUMS.headline * scale;
+    const number = exports.TEXT_MINIMUMS.number * scale;
+    const portrait = height > width;
+    const shown = (t) => `"${t.length > 36 ? `${t.slice(0, 36)}...` : t}"`;
+    for (const t of texts) {
+        if (t.caption || t.text.trim() === "")
+            continue;
+        const size = Math.round(t.size * 10) / 10;
+        const display = t.size >= label * DISPLAY_FACTOR;
+        const figure = isKeyNumber(t.text);
+        if (display && figure && t.size < number) {
+            add(`size:${t.text}`, t.size < number / 2 ? "error" : "warning", "text-size", `The figure ${shown(t.text)} is drawn at ${size}px, under the ${Math.round(number)}px a key number needs at this canvas size (${width}x${height}).`);
+        }
+        else if (display && !figure && t.size < headline) {
+            add(`size:${t.text}`, t.size < headline / 2 ? "error" : "warning", "text-size", `The headline ${shown(t.text)} is drawn at ${size}px, under the ${Math.round(headline)}px a headline needs at this canvas size (${width}x${height}).`);
+        }
+        else if (!display && t.size < label) {
+            add(`size:${t.text}`, t.size < label / 2 ? "error" : "warning", "text-size", `The label ${shown(t.text)} is drawn at ${size}px, under the ${Math.round(label)}px a label needs at this canvas size (${width}x${height}). On a phone it will not be readable.`);
+        }
+        if (portrait) {
+            const top = t.y - t.size * 0.8;
+            const bottom = t.y + t.size * 0.2;
+            if (top < height * exports.SAFE_TOP) {
+                add(`safe:${t.text}`, "warning", "safe-area", `The text ${shown(t.text)} is drawn at y=${Math.round(t.y)}, inside the top ${Math.round(exports.SAFE_TOP * 100)}% of the canvas that the platform's interface covers. Only captions belong there.`);
+            }
+            else if (bottom > height * (1 - exports.SAFE_BOTTOM)) {
+                add(`safe:${t.text}`, "warning", "safe-area", `The text ${shown(t.text)} is drawn at y=${Math.round(t.y)}, inside the bottom ${Math.round(exports.SAFE_BOTTOM * 100)}% of the canvas that captions and the platform's interface use. Only captions belong there.`);
+            }
+        }
+    }
+    return Array.from(found.values());
+}
+const hash = (b) => crypto.createHash("sha256").update(b).digest("hex");
+async function validateCanvasExplainer(input) {
+    const started = Date.now();
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const htmlPath = path.resolve(projectRoot, input.htmlPath);
+    if (!fs.existsSync(htmlPath))
+        throw new Error(`No explainer at ${htmlPath}.`);
+    const width = input.width ?? canvasExplainer_1.DEFAULT_CANVAS_WIDTH;
+    const height = input.height ?? canvasExplainer_1.DEFAULT_CANVAS_HEIGHT;
+    const fps = input.fps ?? canvasExplainer_1.DEFAULT_CANVAS_FPS;
+    const scale = input.textScale ?? Math.min(width, height) / 720;
+    const scene = path.basename(htmlPath);
+    const audioOn = input.audio !== false;
+    const project = input.videoName !== undefined ? (0, canvasExplainer_1.readCanvasProject)(projectRoot, input.videoName) : null;
+    const voiceover = project !== null && project.narration === "voice";
+    const thresholds = {
+        diagramWarnSeconds: input.diagramWarnSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.diagramWarnSeconds,
+        diagramErrorSeconds: input.diagramErrorSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.diagramErrorSeconds,
+        staticSeconds: input.staticSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.staticSeconds,
+    };
+    const findings = [];
+    const add = (severity, check, message) => findings.push({ beatId: "*", scene, severity, message, source: "render", check });
+    for (const w of (0, canvasExplainer_1.sourceWarnings)(fs.readFileSync(htmlPath, "utf8"), htmlPath))
+        add("warning", "randomness", w);
+    const browser = await (0, capture_1.launchChromium)();
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-canvas-validate-"));
+    try {
+        const opened = await (0, canvasExplainer_1.openExplainer)(browser, htmlPath, { width, height, fps, voiceover, project, probes: true, requireScore: audioOn });
+        const { page, durationSeconds } = opened;
+        const texts = [];
+        const takeTexts = async () => {
+            const got = await page.evaluate(() => {
+                const w = window;
+                const copy = w.__ovsTexts.slice();
+                w.__ovsTexts.length = 0;
+                return copy;
+            });
+            texts.push(...got);
+        };
+        if (opened.resized)
+            add("warning", "canvas-size", `The canvas was not ${width}x${height}. Size it from window.OVS.width and window.OVS.height.`);
+        // A frame is a pure function of t: three times, each drawn twice with another time drawn in between.
+        const probeTimes = [0.2, 0.5, 0.8].map((f) => f * durationSeconds);
+        for (const t of probeTimes) {
+            const first = hash(await (0, canvasExplainer_1.captureFrame)(page, t));
+            await (0, canvasExplainer_1.captureFrame)(page, (t + durationSeconds * 0.37) % durationSeconds);
+            const second = hash(await (0, canvasExplainer_1.captureFrame)(page, t));
+            if (first !== second) {
+                add("error", "purity", `Drawing t=${t.toFixed(2)}s twice gives two different frames. A frame must be a pure function of t: nothing may depend on how many frames were drawn before it, on the clock, or on a random number.`);
+            }
+        }
+        await takeTexts();
+        // Frames across the whole length, for the arc and the text.
+        const gap = Math.max(MIN_SAMPLE_GAP_SECONDS, durationSeconds / MAX_SAMPLES);
+        const times = [];
+        for (let t = 0; t < durationSeconds; t += gap)
+            times.push(t);
+        const samples = [];
+        let previous = null;
+        const beatAt = (t) => project?.beats.find((b) => t >= b.start && t < b.end)?.id ?? "*";
+        for (const [i, t] of times.entries()) {
+            await page.evaluate(() => (window.__ovsCaptionBoxes = []));
+            const png = await (0, canvasExplainer_1.captureFrame)(page, t);
+            const boxes = (await page.evaluate(() => window.__ovsCaptionBoxes));
+            const file = path.join(scratch, `f${i}.png`);
+            fs.writeFileSync(file, png);
+            const m = await (0, lessonArc_1.measureArcFrame)(file, boxes, previous);
+            previous = m.signature;
+            samples.push({ time: t, beatId: beatAt(t), drawn: m.drawn, changedFromPrevious: m.changedFromPrevious });
+            fs.rmSync(file, { force: true });
+        }
+        await takeTexts();
+        findings.push(...judgeText(texts, width, height, scale, scene));
+        for (const f of (0, lessonArc_1.judgeLessonArc)(samples, durationSeconds, thresholds)) {
+            findings.push({ beatId: f.beatId, scene, severity: f.severity, message: f.message, source: "render", check: f.check });
+        }
+        let sound = null;
+        if (audioOn) {
+            await page.evaluate(() => (window.__ovsSources.length = 0));
+            try {
+                const score = await (0, canvasExplainer_1.renderScore)(page, durationSeconds, canvasExplainer_1.AUDIO_SAMPLE_RATE, voiceover);
+                const sources = (await page.evaluate(() => window.__ovsSources));
+                let peak = 0;
+                for (let i = 0; i < score.data.length; i++)
+                    peak = Math.max(peak, Math.abs(score.data[i]));
+                const peakDb = peak > 0 ? 20 * Math.log10(peak) : null;
+                const most = maxSimultaneous(sources, durationSeconds);
+                sound = { maxSimultaneous: most, peakDb: peakDb === null ? null : Math.round(peakDb * 10) / 10, sources: sources.length };
+                if (most > exports.MAX_SIMULTANEOUS_SOUNDS) {
+                    add("warning", "sound-polyphony", `Up to ${most} sounds play at once (a source node each), over ${exports.MAX_SIMULTANEOUS_SOUNDS}. A pile-up of effects is mush under a voice; thin the score.`);
+                }
+                if (peak >= 1)
+                    add("warning", "sound-peak", `The score peaks at ${peakDb.toFixed(1)} dBFS, which clips. Lower the master level.`);
+                if (peak === 0)
+                    add("warning", "sound-silent", "The score renders as silence.");
+            }
+            catch (err) {
+                add("error", "sound-kit", err instanceof Error ? err.message : String(err));
+            }
+        }
+        await page.close().catch(() => undefined);
+        const own = texts.filter((t) => !t.caption && t.text.trim() !== "");
+        return {
+            ok: !findings.some((f) => f.severity === "error"),
+            findings,
+            durationSeconds,
+            width,
+            height,
+            textScale: scale,
+            framesSampled: times.length,
+            minTextSize: own.length === 0 ? null : Math.round(Math.min(...own.map((t) => t.size)) * 10) / 10,
+            sound,
+            elapsedMs: Date.now() - started,
+        };
+    }
+    finally {
+        await browser.close().catch(() => undefined);
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/dist/capture.d.ts

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

package/dist/capture.js

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

package/dist/config.d.ts

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

package/dist/config.js

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