@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/renderVideo.js

@@ -34,13 +34,18 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildRenderCommand = buildRenderCommand;
+exports.prepareRenderVideo = prepareRenderVideo;
 exports.runRenderVideo = runRenderVideo;
 exports.registerRenderVideo = registerRenderVideo;
 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 renderCache_1 = require("../renderCache");
 const mcp_1 = require("./mcp");
+const facts_1 = require("../facts");
+const jobs_1 = require("../jobs");
 const COMPOSITION_ID_RE = /^[A-Za-z0-9_-]+$/;
 /**
  * Pure argv builder, unit-testable without spawning a real process. On Windows, npx is
@@ -55,9 +60,23 @@ function buildRenderCommand(compositionId, outPath, opts = {}) {
         // timing; not enough to judge final text crispness.
         args.push("--scale=0.5", "--crf=32", "--x264-preset=veryfast");
     }
+    else {
+        // Remotion serialises every frame before encoding it, and its default for that step is
+        // JPEG at quality 80. On camera footage nobody would notice; on a demo video, which is
+        // text and flat UI and hard edges, it is a visible loss applied to every single frame
+        // before x264 ever sees it. PNG is lossless and costs render time, which is the right
+        // trade for the one pass whose output ships.
+        args.push("--image-format=png", "--crf=16");
+    }
     if (opts.concurrency && opts.concurrency > 0) {
         args.push(`--concurrency=${Math.floor(opts.concurrency)}`);
     }
+    if (opts.browserExecutable) {
+        // Reuses the project's configured browser (render.browserExecutable, normally pointed
+        // at the same Playwright-managed Chromium capture already launches) instead of Remotion
+        // downloading its own chrome-headless-shell, which fails outright with no network.
+        args.push(`--browser-executable=${opts.browserExecutable}`);
+    }
     // Remotion suppresses its progress bar when stdout is not a TTY, which is always
     // the case here, so a piped render writes an empty log for its whole run and an
     // agent watching it cannot tell progress from a hang.
@@ -67,23 +86,304 @@ function buildRenderCommand(compositionId, outPath, opts = {}) {
         args,
     };
 }
-async function runRenderVideo(input) {
+function readBeats(projectRoot, videoName) {
+    const beatsPath = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsPath)) {
+        throw new Error(`${beatsPath} does not exist. Call write_beats_file for "${videoName}" first.`);
+    }
+    return JSON.parse(fs.readFileSync(beatsPath, "utf8"));
+}
+/** Best-effort total frame count, for a progress denominator and the async estimate. Never
+ * throws: a render that isn't beats.json-driven (unusual, but not disallowed) just gets an
+ * unknown (0) total rather than failing the whole call over a progress nicety. */
+function tryReadTotalFrames(projectRoot, videoName) {
+    try {
+        const doc = readBeats(projectRoot, videoName);
+        const beats = doc.beats;
+        if (!Array.isArray(beats) || beats.length === 0)
+            return 0;
+        const last = beats[beats.length - 1];
+        return last.start + last.duration;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Rough wall-clock estimate for the async path's immediate response, in seconds. This is a
+ * placeholder constant, not a measurement: Phase B's preflight render benchmark (real
+ * frames/sec on this machine) is what plan_production uses for an estimate worth planning
+ * around. This one just needs to be in the right order of magnitude so a caller polling
+ * job_status knows roughly how long to expect, not exactly.
+ */
+function estimateRenderSeconds(totalFrames, draft) {
+    const secondsPerFrame = draft ? 0.15 : 0.6;
+    return Math.max(5, Math.round(totalFrames * secondsPerFrame));
+}
+/**
+ * Renders only the beats whose inputs changed, then concatenates every segment.
+ *
+ * The concat is a stream copy, so a reused segment's bytes reach the final file unchanged
+ * rather than being decoded and re-encoded. That is what makes this worth doing: a cache
+ * that costs a generation of quality on every reuse is not a cache anyone should want.
+ */
+async function runIncrementalRender(input, ctx) {
+    const { projectRoot, videoName, compositionId, outPathRel, brandLocked, started, onProgress } = ctx;
+    const doc = readBeats(projectRoot, videoName);
+    const beats = doc.beats;
+    if (!Array.isArray(beats) || beats.length === 0) {
+        throw new Error(`src/videos/${videoName}/beats.json has no beats.`);
+    }
+    const config = (0, config_1.loadConfig)(projectRoot);
+    const fps = doc.fps ?? config.videoConfig.fps;
+    const key = (0, renderCache_1.renderKey)({
+        draft: input.draft,
+        width: config.videoConfig.width,
+        height: config.videoConfig.height,
+        fps,
+    });
+    const { plan } = (0, renderCache_1.planSegments)({
+        projectRoot,
+        videoName,
+        compositionId,
+        beats,
+        renderKey: key,
+        cache: (0, renderCache_1.readCache)(projectRoot, videoName),
+    });
+    const dir = (0, renderCache_1.segmentsDir)(projectRoot, videoName);
+    fs.mkdirSync(dir, { recursive: true });
+    const last = beats[beats.length - 1];
+    const totalFrames = last.start + last.duration;
+    const log = [];
+    const errors = [];
+    // framesRendered (the result field, asserted by existing cache tests) counts only frames
+    // actually sent to the renderer this call -- a cache that reports "rendered" frames for a
+    // reused segment would make "did this run do any real work" unanswerable from the result.
+    // progressFramesDone is the separate, job_status/MCP-progress-facing number: how much of
+    // the FINAL video is accounted for so far, where a reused segment is already done.
+    let framesRendered = 0;
+    let progressFramesDone = 0;
+    onProgress?.({ framesRendered: 0, totalFrames, currentBeat: null });
+    for (const segment of plan) {
+        if (segment.reused) {
+            progressFramesDone += segment.lastFrame - segment.firstFrame + 1;
+            log.push(`reused  ${segment.beatId} (frames ${segment.firstFrame}-${segment.lastFrame})`);
+            onProgress?.({ framesRendered: progressFramesDone, totalFrames, currentBeat: segment.beatId });
+            continue;
+        }
+        const { command, args } = (0, renderCache_1.buildSegmentRenderArgs)(compositionId, segment.file, segment.firstFrame, segment.lastFrame, { draft: input.draft, concurrency: input.concurrency, browserExecutable: config.render.browserExecutable });
+        const result = await (0, util_1.spawnCapture)(command, args, projectRoot);
+        if (result.code !== 0 || !fs.existsSync(path.join(projectRoot, segment.file))) {
+            errors.push(`render of beat "${segment.beatId}" failed:\n${result.stderr.slice(-2000)}`);
+            break;
+        }
+        framesRendered += segment.lastFrame - segment.firstFrame + 1;
+        progressFramesDone += segment.lastFrame - segment.firstFrame + 1;
+        log.push(`rendered ${segment.beatId} (frames ${segment.firstFrame}-${segment.lastFrame})`);
+        onProgress?.({ framesRendered: progressFramesDone, totalFrames, currentBeat: segment.beatId });
+    }
+    if (errors.length > 0) {
+        return {
+            success: false,
+            outPath: path.join(projectRoot, outPathRel),
+            draft: Boolean(input.draft),
+            elapsedSeconds: Math.round((Date.now() - started) / 1000),
+            stdout: log.join("\n"),
+            stderr: errors.join("\n\n"),
+            brandLocked,
+        };
+    }
+    // Sample-exact audio join (see renderCache.ts's buildFinalMuxArgs doc comment): every
+    // segment's audio is decoded to raw PCM and trimmed/padded to duration/fps exactly, so
+    // stream-copying every segment's own (encoder-padded) AAC track under one concat demuxer
+    // -- the old approach -- can't stack drift beat over beat. The PCM file lives next to its
+    // segment and is reused whenever the segment itself is reused, so this costs nothing on a
+    // cache hit.
+    for (const segment of plan) {
+        const pcmAbs = path.join(dir, (0, renderCache_1.pcmFileName)(segment.beatId));
+        if (segment.reused && fs.existsSync(pcmAbs))
+            continue;
+        const extract = await (0, util_1.spawnCapture)("ffmpeg", (0, renderCache_1.buildExtractPcmArgs)(path.join(projectRoot, segment.file), pcmAbs), dir);
+        if (extract.code !== 0 || !fs.existsSync(pcmAbs)) {
+            errors.push(`audio extract for beat "${segment.beatId}" failed:\n${extract.stderr.slice(-2000)}`);
+            break;
+        }
+        const durationFrames = segment.lastFrame - segment.firstFrame + 1;
+        const fitted = (0, renderCache_1.fitPcmLength)(fs.readFileSync(pcmAbs), (0, renderCache_1.expectedPcmBytes)(durationFrames, fps));
+        fs.writeFileSync(pcmAbs, fitted);
+    }
+    if (errors.length > 0) {
+        return {
+            success: false,
+            outPath: path.join(projectRoot, outPathRel),
+            draft: Boolean(input.draft),
+            elapsedSeconds: Math.round((Date.now() - started) / 1000),
+            stdout: log.join("\n"),
+            stderr: errors.join("\n\n"),
+            brandLocked,
+        };
+    }
+    // Isolate each segment's video into its own fresh container first (see renderCache.ts's
+    // buildIsolateVideoArgs doc comment): a segment's own container duration reflects its
+    // longer, padded audio track, and the concat demuxer trusts that duration to place the
+    // next file, so concatenating the original segments with `-an` would still leave a
+    // silent gap at every join. Isolating drops that stale duration along with the audio.
+    const voNames = plan.map((p) => (0, renderCache_1.videoOnlyFileName)(p.beatId));
+    for (let i = 0; i < plan.length; i++) {
+        const isolate = await (0, util_1.spawnCapture)("ffmpeg", (0, renderCache_1.buildIsolateVideoArgs)(path.join(projectRoot, plan[i].file), voNames[i]), dir);
+        if (isolate.code !== 0 || !fs.existsSync(path.join(dir, voNames[i]))) {
+            errors.push(`video isolation for beat "${plan[i].beatId}" failed:\n${isolate.stderr.slice(-2000)}`);
+            break;
+        }
+    }
+    if (errors.length > 0) {
+        for (const name of voNames)
+            fs.rmSync(path.join(dir, name), { force: true });
+        return {
+            success: false,
+            outPath: path.join(projectRoot, outPathRel),
+            draft: Boolean(input.draft),
+            elapsedSeconds: Math.round((Date.now() - started) / 1000),
+            stdout: log.join("\n"),
+            stderr: errors.join("\n\n"),
+            brandLocked,
+        };
+    }
+    // The list lives beside the segments and names them by basename, so the whole segments
+    // directory stays relocatable and ffmpeg's -safe 0 has the least to swallow.
+    const listPath = path.join(dir, "concat.txt");
+    fs.writeFileSync(listPath, (0, renderCache_1.buildConcatList)(voNames), "utf8");
+    const videoOnlyName = "_video-only.mp4";
+    const videoOnly = await (0, util_1.spawnCapture)("ffmpeg", (0, renderCache_1.buildVideoOnlyConcatArgs)("concat.txt", videoOnlyName), dir);
+    const concatPcmName = "_concat-audio.pcm";
+    fs.writeFileSync(path.join(dir, concatPcmName), Buffer.concat(plan.map((p) => fs.readFileSync(path.join(dir, (0, renderCache_1.pcmFileName)(p.beatId))))));
+    const outAbs = path.join(projectRoot, outPathRel);
+    const concat = videoOnly.code === 0 && fs.existsSync(path.join(dir, videoOnlyName))
+        ? await (0, util_1.spawnCapture)("ffmpeg", (0, renderCache_1.buildFinalMuxArgs)(videoOnlyName, concatPcmName, path.relative(dir, outAbs)), dir)
+        : videoOnly;
+    const success = concat.code === 0 && fs.existsSync(outAbs);
+    for (const name of voNames)
+        fs.rmSync(path.join(dir, name), { force: true });
+    fs.rmSync(path.join(dir, videoOnlyName), { force: true });
+    fs.rmSync(path.join(dir, concatPcmName), { force: true });
+    if (success) {
+        const segments = {};
+        const renderedAt = new Date().toISOString();
+        for (const segment of plan) {
+            const beat = beats.find((b) => b.id === segment.beatId);
+            segments[segment.beatId] = {
+                hash: segment.hash,
+                file: segment.file,
+                start: beat?.start ?? segment.firstFrame,
+                duration: beat?.duration ?? segment.lastFrame - segment.firstFrame + 1,
+                renderedAt,
+            };
+        }
+        (0, renderCache_1.writeCache)(projectRoot, videoName, { version: renderCache_1.CACHE_VERSION, compositionId, renderKey: key, segments });
+    }
+    onProgress?.({ framesRendered: success ? totalFrames : progressFramesDone, totalFrames, currentBeat: null });
+    return {
+        success,
+        outPath: path.join(projectRoot, outPathRel),
+        draft: Boolean(input.draft),
+        elapsedSeconds: Math.round((Date.now() - started) / 1000),
+        stdout: log.join("\n") + "\n" + concat.stdout,
+        stderr: concat.stderr,
+        brandLocked,
+        reusedBeats: plan.filter((p) => p.reused).map((p) => p.beatId),
+        renderedBeats: plan.filter((p) => !p.reused).map((p) => p.beatId),
+        framesRendered,
+        totalFrames,
+    };
+}
+const SUPERNOVA_BRAND_LOCK_SKIP = "Brand-lock gate skipped: this is a supernova project, and a lesson has no brand to extract " +
+    "(its design is supernovaDesignSystem).";
+/**
+ * The synchronous half of render_video: validate input and the brand-lock gate, throwing
+ * immediately on anything wrong, before any real work (a render that will take 40+ minutes,
+ * possibly started detached under `async: true`) begins. Split out so the async path can
+ * fail a bad call synchronously too, instead of "succeeding" with a jobId that immediately
+ * errors.
+ */
+function prepareRenderVideo(input) {
     const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
     const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
     const compositionId = input.compositionId ?? `${(0, util_1.pascalCase)(videoName)}Demo`;
     if (!COMPOSITION_ID_RE.test(compositionId)) {
         throw new Error(`compositionId "${compositionId}" is not safe (letters, numbers, "-", "_" only).`);
     }
-    const outPathRel = input.outPath ?? path.join("out", `${videoName}.mp4`);
+    const outPathRel = input.outPath ?? path.join("output", `${videoName}.mp4`);
     (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const brandLocked = fs.existsSync(path.join(projectRoot, "src", "brand.ts"));
+    const brandLockSkipReason = !brandLocked && (0, config_1.productionMode)((0, config_1.loadConfig)(projectRoot)) === "supernova" ? SUPERNOVA_BRAND_LOCK_SKIP : undefined;
+    if (!brandLocked && input.skipBrandLock !== true && brandLockSkipReason === undefined) {
+        throw new Error(`Brand-lock gate: no src/brand.ts found in this project. Run extract_brand with ` +
+            `{ sourceRepo: "${projectRoot}" } before rendering. It writes src/brand.ts from the repo being filmed. ` +
+            "If this project deliberately has no brand to extract, pass skipBrandLock: true.");
+    }
     fs.mkdirSync(path.dirname(path.join(projectRoot, outPathRel)), { recursive: true });
+    return { videoName, projectRoot, compositionId, outPathRel, brandLocked, ...(brandLockSkipReason ? { brandLockSkipReason } : {}) };
+}
+/**
+ * Records what this render actually did next to what was asked: which beats were rendered
+ * and which came from the cache, and the size of the file that landed. The result's own
+ * stdout/stderr stay out of the record, they are logs, not facts.
+ */
+async function runRenderVideo(input, opts = {}) {
+    const result = await renderVideoUnrecorded(input, opts);
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    (0, facts_1.writeFactRecord)(projectRoot, {
+        tool: "render_video",
+        videoName: (0, util_1.sanitizeSegment)(input.videoName, "videoName"),
+        facts: {
+            success: result.success,
+            outPath: (0, facts_1.relToProject)(projectRoot, result.outPath),
+            bytes: result.success ? (0, facts_1.fileBytes)(result.outPath) : null,
+            draft: result.draft,
+            incremental: input.incremental === true,
+            elapsedSeconds: result.elapsedSeconds,
+            brandLocked: result.brandLocked,
+            ...(result.renderedBeats ? { renderedBeats: result.renderedBeats } : {}),
+            ...(result.reusedBeats ? { reusedBeats: result.reusedBeats } : {}),
+            ...(result.framesRendered !== undefined ? { framesRendered: result.framesRendered } : {}),
+            ...(result.totalFrames !== undefined ? { totalFrames: result.totalFrames } : {}),
+        },
+    });
+    return result;
+}
+async function renderVideoUnrecorded(input, opts) {
+    const prepared = prepareRenderVideo(input);
+    const result = await renderPrepared(input, opts, prepared);
+    return prepared.brandLockSkipReason ? { ...result, brandLockSkipReason: prepared.brandLockSkipReason } : result;
+}
+async function renderPrepared(input, opts, prepared) {
+    const { videoName, projectRoot, compositionId, outPathRel, brandLocked } = prepared;
     const started = Date.now();
+    if (input.incremental === true) {
+        return runIncrementalRender(input, {
+            projectRoot,
+            videoName,
+            compositionId,
+            outPathRel,
+            brandLocked,
+            started,
+            onProgress: opts.onProgress,
+        });
+    }
+    // No natural per-frame hook on the plain (non-incremental) Remotion CLI path without
+    // parsing its verbose stdout, so progress here is coarse: unknown/0, then done. The
+    // incremental path above is where real per-beat progress actually comes from.
+    const totalFrames = tryReadTotalFrames(projectRoot, videoName);
+    opts.onProgress?.({ framesRendered: 0, totalFrames, currentBeat: null });
+    const config = (0, config_1.loadConfig)(projectRoot);
     const { command, args } = buildRenderCommand(compositionId, outPathRel, {
         draft: input.draft,
         concurrency: input.concurrency,
+        browserExecutable: config.render.browserExecutable,
     });
     const result = await (0, util_1.spawnCapture)(command, args, projectRoot);
     const elapsedSeconds = Math.round((Date.now() - started) / 1000);
+    opts.onProgress?.({ framesRendered: result.code === 0 ? totalFrames : 0, totalFrames, currentBeat: null });
     return {
         success: result.code === 0,
         outPath: path.join(projectRoot, outPathRel),
@@ -91,6 +391,7 @@ async function runRenderVideo(input) {
         elapsedSeconds,
         stdout: result.stdout,
         stderr: result.stderr,
+        brandLocked,
     };
 }
 function registerRenderVideo(server) {
@@ -100,14 +401,36 @@ function registerRenderVideo(server) {
             "child_process.spawn with an argv array (never exec/execSync with a shell string), so a " +
             "user-controlled videoName/outPath can't inject shell syntax. Default compositionId is the video's " +
             "PascalCase name + \"Demo\" (matching stitch_composition's naming), default outPath is " +
-            "out/<videoName>.mp4. Pass draft for a half resolution, fast encode pass: a five minute video is " +
+            "output/<videoName>.mp4 -- the folder a finished render is meant to be picked up or uploaded from. " +
+            "Pass draft for a half resolution, fast encode pass: a five minute video is " +
             "9000 frames and tens of minutes at full quality, which is far too slow a loop for checking whether " +
             "the video is right, and draft is usually enough to judge framing, motion and timing. Pass " +
             "concurrency to cap the worker count; left unset Remotion takes as much of the machine as it can, " +
             "and one render here spawned 25 Chrome workers and starved a second pipeline step running " +
             "alongside it. Renders with verbose logging, because Remotion hides its progress bar when stdout " +
             "is not a TTY and a piped render otherwise writes an empty log for its entire run, leaving no way " +
-            "to tell progress from a hang. Returns the render's captured stdout/stderr and how long it took.",
+            "to tell progress from a hang. BRAND-LOCK GATE: refuses to run unless src/brand.ts exists (written " +
+            "by extract_brand), so a video never ships wearing openvidstudio's own default look by accident. " +
+            "Run extract_brand against the repo being filmed first; pass skipBrandLock: true only when the " +
+            "project deliberately has no brand to extract. A supernova project (production.mode in " +
+            "openvidstudio.config.json) skips the gate on its own and says why in brandLockSkipReason. Returns the render's captured stdout/stderr, how " +
+            "long it took, and brandLocked (whether src/brand.ts existed at render time). Pass incremental to render "
+            + "each beat to its own cached segment under output/segments/<videoName>/ and concatenate them with "
+            + "ffmpeg under stream copy, re-rendering only the beats whose inputs actually changed. A segment is "
+            + "reused only when the beat's JSON, its scene source, every artifact it references, its narration, and "
+            + "the project-wide inputs (brand tokens, the generated composition, the music bed) all hash identical "
+            + "to when it was rendered, so a false hit cannot ship a stale frame. This is what makes diff_beats "
+            + "actionable: editing one caption in a ten beat video re-renders one beat instead of all of them. The "
+            + "result then also reports reusedBeats, renderedBeats, and how many frames were actually rendered. "
+            + "Pass async: true to not block on the render at all: input is validated synchronously same as "
+            + "always (a bad call still fails immediately), then the render starts detached and this call "
+            + "returns { jobId, estimate } right away. Poll job_status with that jobId for progress (frames "
+            + "rendered, current beat, a log tail) and the eventual result, which is exactly the "
+            + "RenderVideoResult a synchronous call would have returned. Use this for anything that might run "
+            + "past about 60 seconds: MCP clients enforce their own request timeout (Claude Code's "
+            + "MCP_TOOL_TIMEOUT, or the SDK client default), and a 40-minute render will not survive one. On "
+            + "the synchronous path (async not set), real MCP progress notifications are emitted as the render "
+            + "progresses, for any client that attached a progressToken to the request.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
             videoName: zod_1.z.string().min(1),
@@ -115,6 +438,40 @@ function registerRenderVideo(server) {
             outPath: zod_1.z.string().optional(),
             draft: zod_1.z.boolean().optional(),
             concurrency: zod_1.z.number().positive().optional(),
+            skipBrandLock: zod_1.z.boolean().optional(),
+            incremental: zod_1.z.boolean().optional(),
+            async: zod_1.z.boolean().optional(),
         },
-    }, async (input) => (0, mcp_1.runTool)("render_video", () => runRenderVideo(input)));
+    }, async (input, extra) => (0, mcp_1.runTool)("render_video", async () => {
+        if (input.async === true) {
+            // Validate synchronously first (throws here, caught by runTool, same as any other
+            // tool failure) so a bad call never "succeeds" with a jobId that immediately errors.
+            const prepared = prepareRenderVideo(input);
+            const totalFrames = tryReadTotalFrames(prepared.projectRoot, prepared.videoName);
+            const job = (0, jobs_1.createJob)("render_video", totalFrames);
+            // Deliberately not awaited: this keeps running on the event loop after this
+            // handler returns, exactly what makes the "return now, finish later" contract work.
+            runRenderVideo(input, { onProgress: (p) => (0, jobs_1.updateJobProgress)(job.id, p) })
+                .then((result) => (0, jobs_1.completeJob)(job.id, result))
+                .catch((err) => (0, jobs_1.failJob)(job.id, err instanceof Error ? err.message : String(err)));
+            return { jobId: job.id, estimate: estimateRenderSeconds(totalFrames, Boolean(input.draft)) };
+        }
+        const progressToken = extra._meta?.progressToken;
+        const onProgress = progressToken === undefined
+            ? undefined
+            : (p) => {
+                void extra
+                    .sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                        progressToken,
+                        progress: p.framesRendered,
+                        total: p.totalFrames,
+                        message: p.currentBeat ? `rendering beat "${p.currentBeat}"` : undefined,
+                    },
+                })
+                    .catch(() => { });
+            };
+        return runRenderVideo(input, { onProgress });
+    }));
 }

package/dist/tools/scaffoldScene.d.ts

@@ -1,23 +1,48 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type SceneKind, type TemplateName } from "../scenes/templates";
 export type { SceneKind };
+/**
+ * C5: scaffold_scene is one option among three, not the only path to a scene file.
+ *  - "template" (default, and every behavior below this point in the file unless noted):
+ *    today's existing behavior, a scene that renders immediately from a fixed shape.
+ *  - "starter": a minimal file wired to the video's own design.ts (if one exists) and
+ *    facts.json (if one exists, C8), with no layout imposed -- a faster starting point
+ *    than a blank file for an agent authoring a bespoke scene at peak/mid.
+ *  - "blank": writes nothing. Just reports the path and component name stitch_composition
+ *    will expect, so the agent knows exactly what to create by hand.
+ */
+export type ScaffoldSceneMode = "template" | "starter" | "blank";
 export interface ScaffoldSceneInput {
     projectRoot?: string;
     videoName: string;
     beatId: string;
     kind: SceneKind;
     overwrite?: boolean;
-    /** Override the automatic template choice. */
+    /** Override the automatic template choice. Only meaningful for mode: "template". */
     template?: TemplateName;
+    /** Defaults to "template". */
+    mode?: ScaffoldSceneMode;
+    /** Return the generated source without writing a scene file. */
+    dryRun?: boolean;
 }
 export interface ScaffoldSceneResult {
-    written: true;
+    written: boolean;
     path: string;
     componentName: string;
-    template: TemplateName;
+    /** A template name for mode "template"; "starter" for mode "starter". */
+    template: TemplateName | "starter";
     /** True when the beat was found in beats.json and its content was used. */
     usedBeat: boolean;
     notes: string[];
+    /** Present for dry runs so callers can inspect the exact generated scene. */
+    source?: string;
 }
-export declare function runScaffoldScene(input: ScaffoldSceneInput): ScaffoldSceneResult;
+/** mode: "blank" never writes a file -- this is what it returns instead. */
+export interface ScaffoldSceneBlankResult {
+    written: false;
+    path: string;
+    componentName: string;
+    notes: string[];
+}
+export declare function runScaffoldScene(input: ScaffoldSceneInput): ScaffoldSceneResult | ScaffoldSceneBlankResult;
 export declare function registerScaffoldScene(server: McpServer): void;