@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/preview/command.js

@@ -0,0 +1,758 @@
+import { createHash } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+import { validateMusicBed } from "@anvpx/motion-audio";
+import { AUDIO_DIR_NAME, CUSTOM_SCENE_TYPE, clipsFromManifest, frozenClips, frozenCopyProblems, frozenMusic, isContiguous, mixAtDeliveryLevel, parseAudioManifest, readRelativeClosure, resolveSceneDir, resolveTimeline, validateStoryboardFull, } from "@anvpx/motion-build";
+import { buildApprovalInputManifest, hashApprovalInput, storyboardHash, } from "../approval/hash.js";
+import { parseFlags, requireStoryboard, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { checkStoryboard, rootError } from "../storyboard/check.js";
+import { sceneContainment } from "../storyboard/containment.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatFindings } from "../storyboard/report.js";
+import { defaultEnv } from "../template/env.js";
+import { DRAFT_FPS } from "../verify/expectation.js";
+import { platformLookup } from "../verify/platform.js";
+import { makeDraftCommand } from "../workflow/draft.js";
+import { stillCommand } from "../workflow/still.js";
+import { CHECKLIST, defaultOut, PREVIEW_JSON, packDir, } from "./manifest.js";
+import { clearPngs, contactSheet, listPngs, nameStills, } from "./pack.js";
+import { CLIP_MAX_SEC, CLIP_SCENE_SEC, capClip, DARK_COUNT, distinctPicks, sceneInfos, shouldRunClip, stillCandidates, stillPlan, } from "./plan.js";
+import { readProvenance, resolvePair } from "./provenance.js";
+const USAGE = `mk preview <storyboard.json> [--stills 6 | --every] [--budget-sec 90] [--out <dir>] [--assets <dir>] [--ledger <assets.json>] [--audio <manifest>] [--music <bed.wav>] [--music-volume <n>] [--music-license <file>] [--json]
+
+Build the proposal pack the user approves, into <out>/<name>.preview, <name> = the storyboard file name without .json (default <out> = <storyboard dir>/out):
+  preview.json   hash, template, frame, scenes, stills, lint, estimate, approval checklist
+  contact.png    one image tiling the stills (look at this, show it to the user)
+  stills/NN-<scene>-<theme>.png
+  clip.mp4       each scene capped at ${CLIP_SCENE_SEC} s, whole clip <= ${CLIP_MAX_SEC} s, 960 px, ${DRAFT_FPS} fps
+Stills: first scene, last scene, each scene type once (an overlay off screen at its scene's still counts as a scene), then an even spread; ${DARK_COUNT} extra stills in the paired theme when
+the template has one. Order of work: stills, contact sheet, clip. If --budget-sec runs out the clip is skipped
+(preview.json says so, exit 0); stills are never skipped. Validation or lint errors exit 2.
+  --stills n       base stills (1-24, default 6)
+  --every          one still per base scene at 70% of it (instead of --stills); overlays show where they cover that moment
+  --budget-sec n   time budget (default 90)
+  --audio <manifest>
+               voice TimingManifest: mix each scene's wav (the manifest's sibling
+               audio/ dir, <id>.wav) under clip.mp4 with the same mix args as
+               the final render; absent means a silent clip (audible:false).
+               The audiovisual binding (manifest + wavs + mix) enters
+               inputManifestSha256.
+  --music <bed.wav> opt-in CC0 bed ducked under narration (needs --audio);
+               same buildMusicMixArgs as final; volume via --music-volume,
+               license receipt via --music-license. Bed + volume + licenseEvidenceSha256
+               enter inputManifestSha256.
+  --music-volume <n> bed level within (0, 1] (default 0.5)
+  --music-license <file> license-evidence file hashed into the receipt
+  --json           print preview.json instead of the summary line
+Scratch builds live in <out>/<name>.preview-work. Then show the pack and, after an explicit yes: mk approve <storyboard.json>
+`;
+const FLAGS = {
+    stills: { type: "string" },
+    every: { type: "boolean" },
+    "budget-sec": { type: "string" },
+    out: { type: "string" },
+    assets: { type: "string" },
+    ledger: { type: "string" },
+    audio: { type: "string" },
+    music: { type: "string" },
+    "music-volume": { type: "string" },
+    "music-license": { type: "string" },
+    json: { type: "boolean" },
+};
+const DEFAULT_STILLS = 6;
+const MAX_STILLS = 24;
+const DEFAULT_BUDGET_SEC = 90;
+const MAX_LINT_ITEMS = 10;
+/** The clip is a derived trailer; authored-work lint (reading time, hold) does not apply to it. */
+const clipDraft = makeDraftCommand({ lint: false });
+const ESTIMATE_NOTE = "estimate: measured draft ms per frame x total frames at the storyboard fps; delivery quality is slower";
+const MS = 1000;
+/** A copy of `io` whose stdout/stderr are captured, so wrapped commands stay quiet. */
+const captured = (io) => {
+    const out = [];
+    const err = [];
+    return { io: { ...io, stdout: (t) => out.push(t), stderr: (t) => err.push(t) }, out, err };
+};
+/** `--stills` as a count (1-24); an exit code on a bad value or a clash with `--every`. */
+function stillCount(flags, every, io) {
+    const given = textFlag(flags, "stills");
+    if (every && given !== undefined) {
+        return { code: usageError("preview", USAGE, "--every and --stills conflict", io).code };
+    }
+    const count = Number(given ?? DEFAULT_STILLS);
+    if (Number.isInteger(count) && count >= 1 && count <= MAX_STILLS)
+        return { count };
+    return {
+        code: usageError("preview", USAGE, `--stills must be an integer 1-${MAX_STILLS}`, io).code,
+    };
+}
+function readOptions(flags, storyboard, io) {
+    const every = flags.every === true;
+    const counted = stillCount(flags, every, io);
+    if ("code" in counted)
+        return counted.code;
+    const stills = counted.count;
+    const budgetSec = Number(textFlag(flags, "budget-sec") ?? DEFAULT_BUDGET_SEC);
+    if (!Number.isFinite(budgetSec) || budgetSec <= 0) {
+        return usageError("preview", USAGE, "--budget-sec must be a positive number", io).code;
+    }
+    const assets = textFlag(flags, "assets");
+    const ledger = textFlag(flags, "ledger");
+    const audio = textFlag(flags, "audio");
+    const music = textFlag(flags, "music");
+    const musicVolumeRaw = textFlag(flags, "music-volume");
+    const musicLicense = textFlag(flags, "music-license");
+    if (musicVolumeRaw !== undefined) {
+        const n = Number(musicVolumeRaw);
+        if (!Number.isFinite(n) || n <= 0 || n > 1) {
+            return usageError("preview", USAGE, "--music-volume must be within (0, 1]", io).code;
+        }
+    }
+    if (music !== undefined && audio === undefined) {
+        return usageError("preview", USAGE, "--music needs --audio", io).code;
+    }
+    if ((musicVolumeRaw !== undefined || musicLicense !== undefined) && music === undefined) {
+        return usageError("preview", USAGE, "--music-volume/--music-license need --music", io).code;
+    }
+    return {
+        stills,
+        every,
+        budgetSec,
+        out: resolve(textFlag(flags, "out") ?? defaultOut(storyboard)),
+        extra: [
+            ...(assets === undefined ? [] : ["--assets", assets]),
+            ...(ledger === undefined ? [] : ["--ledger", ledger]),
+        ],
+        ...(assets === undefined ? {} : { assetsDir: resolve(assets) }),
+        ...(ledger === undefined ? {} : { ledgerPath: ledger }),
+        ...(audio === undefined ? {} : { audioManifest: audio }),
+        ...(music === undefined ? {} : { musicPath: music }),
+        ...(musicVolumeRaw === undefined ? {} : { musicVolume: Number(musicVolumeRaw) }),
+        ...(musicLicense === undefined ? {} : { musicLicensePath: musicLicense }),
+    };
+}
+/** Copies every `<dir>/themes/*.json` of the project into a scratch project. */
+async function copyThemes(host, from, to) {
+    const dir = join(from, "themes");
+    const names = (await host.listDir(dir).catch(() => [])).filter((n) => n.endsWith(".json"));
+    for (const name of names)
+        await host.copyFile(join(dir, name), join(to, "themes", name));
+}
+const CUSTOM_FILES = ["scene.js", "fragment.html", "style.css"];
+/**
+ * Copies authored scene directories beside a derived storyboard, so a relative
+ * `props.dir` still resolves after the storyboard is rewritten into a scratch dir.
+ */
+export async function copyCustomScenes(host, board, origin, targetDir) {
+    const base = dirname(resolve(origin));
+    for (const scene of board.scenes) {
+        if (scene.type !== CUSTOM_SCENE_TYPE)
+            continue;
+        const dir = scene.props.dir;
+        if (typeof dir !== "string")
+            continue;
+        const resolved = resolveSceneDir(base, dir);
+        if (!resolved.ok)
+            continue;
+        // Never copy bytes that resolve outside the project through a link.
+        const containment = sceneContainment(base, resolved.dir, CUSTOM_FILES);
+        if (!containment.dirInside || containment.escapedFiles.length > 0) {
+            throw new Error(`custom scene "${dir}" resolves outside the storyboard directory (symlink)`);
+        }
+        for (const file of CUSTOM_FILES) {
+            const from = join(resolved.dir, file);
+            if (await host.exists(from))
+                await host.copyFile(from, join(targetDir, dir, file));
+        }
+        // Relative helpers emitted beside scene.js must resolve in the scratch copy too.
+        const jsPath = join(resolved.dir, "scene.js");
+        if (await host.exists(jsPath)) {
+            const closure = await readRelativeClosure(await host.readText(jsPath), async (helper) => {
+                const check = sceneContainment(base, resolved.dir, [helper]);
+                if (!check.dirInside || check.escapedFiles.length > 0) {
+                    throw new Error(`custom scene helper "${helper}" resolves outside the scene (symlink)`);
+                }
+                const full = join(resolved.dir, helper);
+                return (await host.exists(full)) ? host.readText(full) : undefined;
+            });
+            for (const helper of closure.files) {
+                await host.copyFile(join(resolved.dir, helper.path), join(targetDir, dir, helper.path));
+            }
+        }
+    }
+}
+/** Writes a derived storyboard (+ the project's themes, + extra theme files) into its own scratch dir. */
+async function scratch(io, work, name, board, projectDir, extraThemes = [], origin) {
+    const dir = join(work, name);
+    await io.host.writeTextAtomic(join(dir, "storyboard.json"), `${JSON.stringify(board, null, 2)}\n`);
+    if (origin !== undefined)
+        await copyCustomScenes(io.host, board, origin, dir);
+    await copyThemes(io.host, projectDir, dir);
+    for (const theme of extraThemes) {
+        await io.host.writeTextAtomic(join(dir, "themes", `${theme.id}.json`), theme.text);
+    }
+    return { storyboard: join(dir, "storyboard.json"), project: join(dir, "project") };
+}
+/** Runs `mk still` quietly; returns the PNGs it wrote (ordered like the `--at` list) or an exit code. */
+async function capture(io, scratchDir, picks, extra, clock, spent) {
+    const stillsDir = join(scratchDir.project, "stills");
+    await clearPngs(io.host, stillsDir);
+    const quiet = captured(io);
+    const began = clock();
+    const at = picks.map((p) => p.t).join(",");
+    const code = await stillCommand.run([scratchDir.storyboard, "--at", at, "--out", scratchDir.project, ...extra], quiet.io);
+    spent.ms += clock() - began;
+    if (code !== 0) {
+        io.stderr(quiet.err.join(""));
+        return code;
+    }
+    const files = await listPngs(io.host, stillsDir);
+    if (files.length !== picks.length) {
+        io.stderr(`mk preview: expected ${picks.length} stills, hyperframes wrote ${files.length}\n`);
+        return EXIT.ERROR;
+    }
+    return files;
+}
+const stripNarration = (board) => ({
+    ...board,
+    scenes: board.scenes.map((entry) => {
+        const { narration: _narration, ...scene } = entry;
+        return scene;
+    }),
+});
+/** Voice total for the full board, or undefined when the manifest cannot resolve yet. */
+async function voiceTotal(io, board, audioManifest) {
+    try {
+        const parsed = parseAudioManifest(JSON.parse(await io.host.readText(audioManifest)));
+        if (!parsed.ok)
+            return undefined;
+        const timeline = resolveTimeline(board, parsed.manifest);
+        return timeline.ok ? timeline.value.total : undefined;
+    }
+    catch {
+        // Unreadable/invalid manifests fail closed in clipDraft below.
+        return undefined;
+    }
+}
+/** Full-length audible clip: voice-timed build so clip video total equals narration total. */
+async function makeAudibleClip(io, board, projectDir, work, pack, extra, clock, audioManifest, origin) {
+    const clip = await scratch(io, work, "clip", stripNarration(board), projectDir, [], origin);
+    const quiet = captured(io);
+    const began = clock();
+    const code = await clipDraft.run([clip.storyboard, "--out", clip.project, ...extra, "--audio", audioManifest], quiet.io);
+    const ms = clock() - began;
+    if (code !== 0) {
+        const why = quiet.err.join("").trim().split("\n")[0] ?? "";
+        return {
+            result: {
+                status: "skipped",
+                reason: `draft failed (exit ${code}${why === "" ? "" : `: ${why}`})`,
+            },
+            msPerFrame: undefined,
+        };
+    }
+    await io.host.copyFile(join(clip.project, "draft.mp4"), join(pack, "clip.mp4"));
+    const voiceSec = await voiceTotal(io, board, audioManifest);
+    const fallback = resolveTimeline(board);
+    const sec = voiceSec ?? (fallback.ok ? fallback.value.total : 0);
+    return {
+        result: { status: "ok", file: "clip.mp4", sec },
+        msPerFrame: ms / Math.max(1, Math.round(sec * DRAFT_FPS)),
+    };
+}
+async function makeClip(io, board, projectDir, work, pack, extra, clock, audioManifest, origin) {
+    // With --audio the clip is the full audible review (not a capped trailer).
+    // Without --audio keep the capped trailer: byte-identical to today.
+    if (audioManifest !== undefined) {
+        return makeAudibleClip(io, board, projectDir, work, pack, extra, clock, audioManifest, origin);
+    }
+    const plan = capClip(board);
+    const clip = await scratch(io, work, "clip", plan.storyboard, projectDir, [], origin);
+    const quiet = captured(io);
+    const began = clock();
+    const code = await clipDraft.run([clip.storyboard, "--out", clip.project, ...extra], quiet.io);
+    const ms = clock() - began;
+    if (code !== 0) {
+        const why = quiet.err.join("").trim().split("\n")[0] ?? "";
+        const reason = `draft failed (exit ${code}${why === "" ? "" : `: ${why}`})`;
+        return { result: { status: "skipped", reason }, msPerFrame: undefined };
+    }
+    await io.host.copyFile(join(clip.project, "draft.mp4"), join(pack, "clip.mp4"));
+    const frames = Math.max(1, Math.round(plan.totalSec * DRAFT_FPS));
+    return {
+        result: { status: "ok", file: "clip.mp4", sec: plan.totalSec },
+        msPerFrame: ms / frames,
+    };
+}
+const summary = (m, pack, storyboard, overlays) => {
+    const paired = m.stills.filter((s) => s.theme !== m.theme).length;
+    const from = m.template === null
+        ? "free storyboard"
+        : `template ${m.template} ${m.blueprint} style ${m.style}`;
+    const clip = m.clip.status === "ok" ? `clip ${m.clip.sec}s` : "clip skipped";
+    const est = m.estFullRenderSec === null
+        ? "est render n/a"
+        : `est render ~${Math.max(1, Math.round(m.estFullRenderSec / 60))}m`;
+    return (`preview ok | ${from} | ${m.scenes.length} scenes + ${overlays} overlays ${m.totalSec}s ${m.frame.width}x${m.frame.height} | pack ${pack} | ` +
+        `contact.png ${m.stills.length - paired} stills (+${paired} paired) ${clip} | ${est} (estimate) | ` +
+        `lint ${m.lint.errors} err ${m.lint.warnings} warn | approve: mk approve ${storyboard}\n`);
+};
+const round = (value) => Math.round(value * 100) / 100;
+/** Reads, validates and lints the storyboard; findings go to stderr with exit 2. */
+async function loadBoard(storyboard, io) {
+    const loaded = await readJsonFile(storyboard, io.host);
+    if (!loaded.ok && loaded.kind === "io") {
+        io.stderr(`mk preview: ${loaded.message}\n`);
+        return EXIT.USAGE;
+    }
+    const report = loaded.ok
+        ? checkStoryboard(loaded.value, { platforms: await platformLookup(io.host) })
+        : { errors: [rootError(loaded.message)], warnings: [] };
+    const valid = loaded.ok ? validateStoryboardFull(loaded.value) : undefined;
+    if (report.errors.length > 0 || valid === undefined || !valid.ok) {
+        io.stderr(formatFindings([...report.errors, ...report.warnings]));
+        return EXIT.USAGE;
+    }
+    const infos = sceneInfos(valid.value);
+    if (infos === undefined)
+        return EXIT.USAGE;
+    const overlays = valid.value.scenes.filter((s) => s.layer === "overlay").length;
+    return {
+        board: valid.value,
+        report,
+        infos,
+        candidates: stillCandidates(valid.value),
+        overlays,
+    };
+}
+/** Stills in the storyboard's theme, plus the paired theme for the most distinct scenes. */
+async function shootStills(ctx, pair, spent) {
+    const { io, board, projectDir, options, work, clock } = ctx;
+    const theme = board.meta.theme;
+    const picks = options.every
+        ? stillPlan(ctx.infos, ctx.infos.length)
+        : stillPlan(ctx.candidates, options.stills);
+    const light = await scratch(io, work, "light", board, projectDir, [], ctx.storyboard);
+    const files = await capture(io, light, picks, options.extra, clock, spent);
+    if (typeof files === "number")
+        return files;
+    const taken = picks.map((pick, i) => ({ pick, theme, source: files[i] ?? "" }));
+    if (pair !== undefined) {
+        const extra = distinctPicks(picks, DARK_COUNT);
+        const paired = { ...board, meta: { ...board.meta, theme: pair.id } };
+        const scratchDir = await scratch(io, work, "paired", paired, projectDir, [pair], ctx.storyboard);
+        const darkFiles = await capture(io, scratchDir, extra, options.extra, clock, spent);
+        if (typeof darkFiles === "number")
+            return darkFiles;
+        for (const [i, pick] of extra.entries()) {
+            taken.push({ pick, theme: pair.id, source: darkFiles[i] ?? "" });
+        }
+    }
+    return nameStills(taken, theme);
+}
+/** Copies the named stills into the pack and tiles them into contact.png. */
+async function packStills(ctx, named) {
+    const { io, pack, work } = ctx;
+    const dir = join(pack, "stills");
+    await clearPngs(io.host, dir);
+    for (const still of named)
+        await io.host.copyFile(still.source, join(dir, still.name));
+    const files = named.map((s) => join(dir, s.name));
+    return contactSheet(io, files, join(work, "contact.txt"), join(pack, "contact.png"));
+}
+/** The clip, unless the stills already used the budget (then a labelled skip). */
+async function clipOrSkip(ctx, stillsMs) {
+    const { io, pack, options, clock, began } = ctx;
+    await io.host.remove(join(pack, "clip.mp4"));
+    const elapsed = clock() - began;
+    if (shouldRunClip(elapsed, stillsMs, options.budgetSec * MS)) {
+        return makeClip(io, ctx.board, ctx.projectDir, ctx.work, pack, options.extra, clock, options.audioManifest, ctx.storyboard);
+    }
+    const used = `${Math.round(elapsed / MS)} s used of ${options.budgetSec} s`;
+    return {
+        result: { status: "skipped", reason: `budget: ${used}; raise --budget-sec` },
+        msPerFrame: undefined,
+    };
+}
+const stillRow = (s) => ({
+    file: `stills/${s.name}`,
+    scene: s.pick.id,
+    t: s.pick.t,
+    theme: s.theme,
+});
+/** The invocation inputs recorded in the pack; absolute so a later `mk approve` matches exactly. */
+const inputsOf = (options) => ({
+    assetsDir: options.assetsDir ?? null,
+    ledger: options.ledgerPath === undefined ? null : resolve(options.ledgerPath),
+    audioManifest: options.audioManifest === undefined ? null : resolve(options.audioManifest),
+    music: options.musicPath === undefined ? null : resolve(options.musicPath),
+    musicVolume: options.musicVolume ?? null,
+    musicLicense: options.musicLicensePath === undefined ? null : resolve(options.musicLicensePath),
+});
+function manifestOf(ctx, facts) {
+    const { board, infos, report, options } = ctx;
+    const { provenance, clip } = facts;
+    const totalSec = round(Math.max(...infos.map((i) => i.start + i.duration)));
+    const estimate = clip.msPerFrame === undefined
+        ? null
+        : Math.round((clip.msPerFrame * totalSec * board.meta.fps) / MS);
+    const { width, height, fps } = board.meta;
+    const checklist = CHECKLIST.map((item) => item.id === "not-shown" && facts.audioMix.audible
+        ? {
+            ...item,
+            text: facts.audioMix.musicSha === null
+                ? "the user knows what is NOT previewed: motion between stills and any scene without a still"
+                : "the user knows what is NOT previewed: motion between stills and any scene without a still (music bed included in clip)",
+        }
+        : { ...item });
+    return {
+        hash: facts.hash,
+        inputManifest: facts.inputManifest,
+        inputManifestSha256: facts.inputManifestSha256,
+        storyboard: basename(ctx.storyboard),
+        inputs: inputsOf(options),
+        template: provenance?.template ?? null,
+        blueprint: provenance?.blueprint ?? null,
+        style: provenance?.style ?? null,
+        theme: board.meta.theme,
+        pair: facts.pair?.id ?? null,
+        frame: { width, height, fps },
+        totalSec,
+        scenes: infos.map((i) => ({ id: i.id, type: i.type, start: i.start, duration: i.duration })),
+        stills: facts.named.map(stillRow),
+        contact: "contact.png",
+        clip: clip.result,
+        estFullRenderSec: estimate,
+        estimateNote: ESTIMATE_NOTE,
+        lint: {
+            errors: report.errors.length,
+            warnings: report.warnings.length,
+            items: report.warnings.slice(0, MAX_LINT_ITEMS).map((w) => `${w.path || "/"}: ${w.message}`),
+        },
+        budgetSec: options.budgetSec,
+        elapsedSec: round((ctx.clock() - ctx.began) / MS),
+        audioMix: facts.audioMix,
+        checklist: checklist.map((item) => ({ ...item, done: false })),
+    };
+}
+/** Parses flags, loads and validates the storyboard; an exit code on any problem (or `--help`). */
+async function start(args, io, clock) {
+    const parsed = parseFlags("preview", USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const storyboard = requireStoryboard("preview", USAGE, parsed.positionals, io);
+    if (typeof storyboard !== "string")
+        return storyboard.code;
+    const options = readOptions(parsed.flags, storyboard, io);
+    if (typeof options === "number")
+        return options;
+    const began = clock();
+    const loaded = await loadBoard(storyboard, io);
+    if (typeof loaded === "number")
+        return loaded;
+    const ctx = {
+        ...loaded,
+        io,
+        storyboard,
+        options,
+        projectDir: dirname(resolve(storyboard)),
+        work: `${packDir(options.out, storyboard)}-work`,
+        pack: packDir(options.out, storyboard),
+        clock,
+        began,
+    };
+    return { ctx, json: parsed.flags.json === true };
+}
+/** `mk preview`; `env` and `clock` are injectable for tests. */
+const resolvePreview = async (io, ctx) => {
+    try {
+        const manifest = await buildApprovalInputManifest(io.host, ctx.storyboard, {
+            ...(ctx.options.assetsDir === undefined ? {} : { assetsDir: ctx.options.assetsDir }),
+            ...(ctx.options.ledgerPath === undefined ? {} : { ledgerPath: ctx.options.ledgerPath }),
+            ...(ctx.options.audioManifest === undefined
+                ? {}
+                : { audioManifest: ctx.options.audioManifest }),
+            ...(ctx.options.musicPath === undefined ? {} : { music: ctx.options.musicPath }),
+            ...(ctx.options.musicVolume === undefined ? {} : { musicVolume: ctx.options.musicVolume }),
+            ...(ctx.options.musicLicensePath === undefined
+                ? {}
+                : { musicLicense: ctx.options.musicLicensePath }),
+        });
+        return { manifest, sha: hashApprovalInput(manifest) };
+    }
+    catch (error) {
+        const hint = ctx.options.audioManifest === undefined
+            ? ""
+            : `; rerun \`mk preview ${ctx.storyboard} --audio ${ctx.options.audioManifest}\` after fixing the audio inputs`;
+        io.stderr(`mk preview: ${error.message}${hint}\n`);
+        return EXIT.USAGE;
+    }
+};
+const SILENT_AUDIO_MIX = {
+    manifestSha: null,
+    wavSha: null,
+    audible: false,
+    musicSha: null,
+    musicVolume: null,
+    musicLicenseSha: null,
+};
+/** Mixes the exact final wavs under the preview clip with the same args as the final render. */
+const mixPreviewClip = async (io, pack, work, audioManifest, storyboard, expected, musicOpts = {}) => {
+    const rerun = `rerun \`mk preview ${storyboard} --audio ${audioManifest}\` after fixing the audio inputs`;
+    let text;
+    try {
+        text = await io.host.readText(audioManifest);
+    }
+    catch (error) {
+        io.stderr(`mk preview: cannot read --audio manifest: ${error.message}; ${rerun}\n`);
+        return EXIT.USAGE;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        io.stderr(`mk preview: invalid --audio manifest: ${error.message}; ${rerun}\n`);
+        return EXIT.USAGE;
+    }
+    const parsed = parseAudioManifest(raw);
+    if (!parsed.ok) {
+        io.stderr(`mk preview: invalid --audio manifest: ${parsed.problems.join("; ")}; ${rerun}\n`);
+        return EXIT.USAGE;
+    }
+    const audioDir = join(dirname(resolve(audioManifest)), AUDIO_DIR_NAME);
+    const clips = clipsFromManifest(parsed.manifest, audioDir);
+    if (clips.length === 0) {
+        io.stderr(`mk preview: --audio manifest has no scenes; nothing to mix; ${rerun}\n`);
+        return EXIT.USAGE;
+    }
+    for (const clip of clips) {
+        const digest = await io.host.sha256File(clip.wav);
+        if (digest === undefined) {
+            io.stderr(`mk preview: missing narration wav for scene "${clip.id}": ${clip.wav}; ${rerun}\n`);
+            return EXIT.USAGE;
+        }
+        // AU-01 MEDIUM: ungated --audio must reject silent wavs like the manifest
+        // path does (EMPTY_SHA256); never mix silence as narration.
+        if (digest === "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855") {
+            io.stderr(`mk preview: narration wav is silent/empty for scene "${clip.id}": ${clip.wav}; ${rerun}\n`);
+            return EXIT.USAGE;
+        }
+    }
+    // RA-02: never certify audible from hashes alone. The clip must exist and
+    // the mix must succeed before audible:true is returned.
+    const clipFile = join(pack, "clip.mp4");
+    if (!(await io.host.exists(clipFile))) {
+        io.stderr(`mk preview: --audio requires an audible clip but ${clipFile} is missing (clip skipped or failed); raise --budget-sec and ${rerun}\n`);
+        return EXIT.USAGE;
+    }
+    const manifestSha = createHash("sha256").update(text).digest("hex");
+    const mixedFile = join(pack, "clip-audible.mp4");
+    // AU-01: freeze the exact bytes ffmpeg consumes (ABA-proof) and mix with the
+    // same build authority as the final render (no second pipeline).
+    const frozenDir = join(work, ".frozen-audio");
+    let mixBed;
+    let musicSha = null;
+    let musicVolume = null;
+    let musicLicenseSha = null;
+    const frozenNarration = frozenClips(clips, frozenDir);
+    const checks = [];
+    const frozenDigests = [];
+    try {
+        for (const [index, clip] of frozenNarration.entries()) {
+            const source = clips[index];
+            if (source === undefined)
+                continue;
+            await io.host.copyFile(source.wav, clip.wav);
+            const frozenSha = await io.host.sha256File(clip.wav);
+            frozenDigests.push(frozenSha ?? "");
+            checks.push({
+                label: `narration "${clip.id}"`,
+                actualSha256: frozenSha,
+                expectedSha256: expected.mix?.clips[index]?.wavSha,
+            });
+        }
+    }
+    catch (error) {
+        io.stderr(`mk preview: cannot freeze narration wavs: ${error.message}; ${rerun}\n`);
+        return EXIT.ERROR;
+    }
+    const wavSha = createHash("sha256").update(frozenDigests.join("\n")).digest("hex");
+    if (musicOpts.musicPath !== undefined) {
+        const validated = validateMusicBed(musicOpts.musicVolume === undefined
+            ? { wav: musicOpts.musicPath }
+            : { wav: musicOpts.musicPath, volume: musicOpts.musicVolume });
+        if (!validated.ok) {
+            io.stderr(`mk preview: invalid --music bed: ${validated.hint}; ${rerun}\n`);
+            return EXIT.USAGE;
+        }
+        const bedDigest = await io.host.sha256File(musicOpts.musicPath);
+        if (bedDigest === undefined) {
+            io.stderr(`mk preview: music bed wav not found: ${musicOpts.musicPath}; ${rerun}\n`);
+            return EXIT.USAGE;
+        }
+        if (bedDigest === "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855") {
+            io.stderr(`mk preview: music bed wav is silent/empty: ${musicOpts.musicPath}; ${rerun}\n`);
+            return EXIT.USAGE;
+        }
+        if (musicOpts.musicLicensePath !== undefined) {
+            const licDigest = await io.host.sha256File(musicOpts.musicLicensePath);
+            if (licDigest === undefined) {
+                io.stderr(`mk preview: cannot read --music-license ${musicOpts.musicLicensePath}: not found; ${rerun}\n`);
+                return EXIT.USAGE;
+            }
+            musicLicenseSha = licDigest;
+        }
+        const frozenBed = frozenMusic({ wav: musicOpts.musicPath, volume: validated.bed.volume }, frozenDir);
+        try {
+            await io.host.copyFile(musicOpts.musicPath, frozenBed.wav);
+        }
+        catch (error) {
+            io.stderr(`mk preview: cannot freeze music bed: ${error.message}; ${rerun}\n`);
+            return EXIT.ERROR;
+        }
+        const frozenBedSha = await io.host.sha256File(frozenBed.wav);
+        checks.push({
+            label: "music bed",
+            actualSha256: frozenBedSha,
+            expectedSha256: expected.music?.sha256,
+        });
+        if (musicLicenseSha !== null) {
+            checks.push({
+                label: "music license evidence",
+                actualSha256: musicLicenseSha,
+                expectedSha256: expected.music?.licenseEvidenceSha256 ?? undefined,
+            });
+        }
+        musicSha = frozenBedSha ?? null;
+        musicVolume = validated.bed.volume;
+        mixBed = frozenBed;
+    }
+    // ADR-0008 D2: the audible clip must mix the bytes the preview manifest
+    // describes. An edit during the copy that is restored before the post-media
+    // re-resolve is invisible to that re-resolve; the frozen copy is not. The
+    // clip list must also still line up with the manifest's mix (count, id,
+    // start, mode): the manifest is re-read for the mix, so an extra or reordered
+    // clip must not ride along on matching file digests.
+    const frozenProblems = frozenCopyProblems(checks);
+    if (expected.mix !== undefined) {
+        if (expected.mix.clips.length !== clips.length) {
+            frozenProblems.push(`the previewed mix has ${expected.mix.clips.length} clips but ${clips.length} were prepared`);
+        }
+        for (const [index, clip] of clips.entries()) {
+            const want = expected.mix.clips[index];
+            if (want !== undefined && (want.id !== clip.id || want.start !== clip.start)) {
+                frozenProblems.push(`narration ${index + 1} does not match the previewed clip "${want.id}" at ${want.start}s`);
+            }
+        }
+        const mode = clips.length === 1 ? "single" : isContiguous(clips) ? "concat" : "adelay";
+        if (expected.mix.mode !== mode) {
+            frozenProblems.push(`the previewed mix mode "${expected.mix.mode}" does not match "${mode}"`);
+        }
+    }
+    if (frozenProblems.length > 0) {
+        io.stderr(`mk preview: inputs changed while the pack was produced; the pack was not written (${frozenProblems.join("; ")}); ${rerun}\n`);
+        return EXIT.USAGE;
+    }
+    const delivery = await mixAtDeliveryLevel((argv) => io.run("ffmpeg", argv), {
+        videoIn: clipFile,
+        clips: frozenNarration,
+        ...(mixBed === undefined ? {} : { music: mixBed }),
+        out: mixedFile,
+        swap: async (from, to) => {
+            await io.host.copyFile(from, to);
+            await io.host.remove(from);
+        },
+    });
+    if (!delivery.ok) {
+        const why = delivery.problems[0] ?? "";
+        io.stderr(`mk preview: audible clip mix failed${why === "" ? "" : `: ${why}`}; ${rerun}\n`);
+        return EXIT.ERROR;
+    }
+    if (!(await io.host.exists(mixedFile))) {
+        io.stderr(`mk preview: audible clip mix produced no file; ${rerun}\n`);
+        return EXIT.ERROR;
+    }
+    await io.host.copyFile(mixedFile, clipFile);
+    await io.host.remove(mixedFile);
+    return { manifestSha, wavSha, audible: true, musicSha, musicVolume, musicLicenseSha };
+};
+export const makePreviewCommand = (env = defaultEnv, clock = () => performance.now()) => ({
+    name: "preview",
+    summary: "build the short proposal pack (contact sheet, stills, clip) for approval",
+    async run(args, io) {
+        const started = await start(args, io, clock);
+        if (typeof started === "number")
+            return started;
+        const { ctx, json } = started;
+        const { storyboard } = ctx;
+        const provenance = await readProvenance(io.host, storyboard);
+        const pair = resolvePair(env(), io, provenance, ctx.board.meta.theme);
+        const spent = { ms: 0 };
+        // RA-01: freeze the approval identity before any media is produced. The
+        // post-media re-resolve below must match, or the pack is unusable: the
+        // identity must describe the bytes the reviewer actually saw.
+        const snapshot = await resolvePreview(io, ctx);
+        if (typeof snapshot === "number")
+            return snapshot;
+        const frozenHash = await storyboardHash(io.host, storyboard);
+        const named = await shootStills(ctx, pair, spent);
+        if (typeof named === "number")
+            return named;
+        const packed = await packStills(ctx, named);
+        if (packed !== EXIT.OK)
+            return packed;
+        const clip = await clipOrSkip(ctx, spent.ms);
+        let audioMix;
+        if (ctx.options.audioManifest === undefined) {
+            audioMix = SILENT_AUDIO_MIX;
+        }
+        else {
+            // RA-02: an audiovisual pack is only audible after a playable mixed
+            // clip exists. A budget-skipped clip never certifies from hashes.
+            if (clip.result.status !== "ok") {
+                const why = clip.result.status === "skipped" ? ` (${clip.result.reason})` : " (missing)";
+                io.stderr(`mk preview: --audio requires an audible clip but the clip was skipped${why}; raise --budget-sec and rerun \`mk preview ${storyboard} --audio ${ctx.options.audioManifest}\`\n`);
+                return EXIT.USAGE;
+            }
+            const mixed = await mixPreviewClip(io, ctx.pack, ctx.work, ctx.options.audioManifest, storyboard, snapshot.manifest, {
+                ...(ctx.options.musicPath === undefined ? {} : { musicPath: ctx.options.musicPath }),
+                ...(ctx.options.musicVolume === undefined
+                    ? {}
+                    : { musicVolume: ctx.options.musicVolume }),
+                ...(ctx.options.musicLicensePath === undefined
+                    ? {}
+                    : { musicLicensePath: ctx.options.musicLicensePath }),
+            });
+            if (typeof mixed === "number")
+                return mixed;
+            audioMix = mixed;
+        }
+        // RA-01: an edit that landed while stills/clip/mix ran must not silently
+        // rebind the pack to bytes the reviewer never saw. Fail closed without
+        // writing preview.json; `mk approve` also rechecks the binding.
+        const reverified = await resolvePreview(io, ctx);
+        if (typeof reverified === "number")
+            return reverified;
+        if (reverified.sha !== snapshot.sha) {
+            io.stderr(`mk preview: inputs changed while the pack was produced; the pack was not written. Rerun \`mk preview ${storyboard}\`.\n`);
+            return EXIT.USAGE;
+        }
+        const manifest = manifestOf(ctx, {
+            hash: frozenHash,
+            inputManifest: snapshot.manifest,
+            inputManifestSha256: snapshot.sha,
+            provenance,
+            pair,
+            named,
+            clip,
+            audioMix,
+        });
+        const text = `${JSON.stringify(manifest, null, 2)}\n`;
+        await io.host.writeTextAtomic(join(ctx.pack, PREVIEW_JSON), text);
+        io.stdout(json ? text : summary(manifest, ctx.pack, storyboard, ctx.overlays));
+        io.stderr(formatFindings(ctx.report.warnings.slice(0, MAX_LINT_ITEMS)));
+        return EXIT.OK;
+    },
+});
+export const previewCommand = makePreviewCommand();