mergestory 0.0.0-stage → 1.0.0

package/dist/narration/wav.js

@@ -0,0 +1,170 @@
+/**
+ * Minimal WAV reading and writing. Every clip MergeStory stores is mono, 48 kHz, 16-bit PCM,
+ * so writing is one fixed layout; reading is tolerant because speech engines differ in the
+ * chunks they add and in the sample format they use.
+ */
+/** Sample rate of every stored clip and of the final narration track. */
+export const CANONICAL_RATE = 48_000;
+const WAVE_FORMAT_PCM = 1;
+const WAVE_FORMAT_FLOAT = 3;
+const WAVE_FORMAT_EXTENSIBLE = 0xfffe;
+/** Parse the header of a RIFF/WAVE file. Throws a plain Error when the file is not a usable WAV. */
+export function parseWavHeader(buf) {
+    if (buf.length < 12 || buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WAVE') {
+        throw new Error('Not a RIFF/WAVE file');
+    }
+    let fmt = null;
+    let offset = 12;
+    while (offset + 8 <= buf.length) {
+        const id = buf.toString('ascii', offset, offset + 4);
+        const declared = buf.readUInt32LE(offset + 4);
+        const body = offset + 8;
+        if (id === 'fmt ') {
+            if (declared < 16 || body + 16 > buf.length)
+                throw new Error('Truncated WAV format chunk');
+            let tag = buf.readUInt16LE(body);
+            const channels = buf.readUInt16LE(body + 2);
+            const sampleRate = buf.readUInt32LE(body + 4);
+            const bits = buf.readUInt16LE(body + 14);
+            if (tag === WAVE_FORMAT_EXTENSIBLE && declared >= 26 && body + 26 <= buf.length) {
+                tag = buf.readUInt16LE(body + 24);
+            }
+            fmt = { tag, channels, sampleRate, bits };
+        }
+        else if (id === 'data') {
+            if (!fmt)
+                throw new Error('WAV data chunk before format chunk');
+            // Streamed files may declare 0 or 0xFFFFFFFF; use what is actually there.
+            const available = buf.length - body;
+            const dataBytes = declared === 0 || declared === 0xffffffff || declared > available ? available : declared;
+            const encoding = fmt.tag === WAVE_FORMAT_FLOAT ? 'float' : fmt.tag === WAVE_FORMAT_PCM ? 'pcm' : null;
+            if (!encoding)
+                throw new Error(`Unsupported WAV encoding ${fmt.tag}`);
+            const validBits = encoding === 'float' ? [32, 64] : [8, 16, 24, 32];
+            if (!validBits.includes(fmt.bits))
+                throw new Error(`Unsupported WAV sample size ${fmt.bits}`);
+            if (fmt.channels < 1 || fmt.sampleRate < 1)
+                throw new Error('Invalid WAV format chunk');
+            return {
+                encoding,
+                bitsPerSample: fmt.bits,
+                channels: fmt.channels,
+                sampleRate: fmt.sampleRate,
+                dataOffset: body,
+                dataBytes,
+            };
+        }
+        offset = body + declared + (declared % 2);
+    }
+    throw new Error('WAV file has no audio data');
+}
+/** Encode samples as a 16-bit PCM WAV file. */
+export function encodeWavPcm16(samples, sampleRate, channels = 1) {
+    const dataBytes = samples.length * 2;
+    const out = Buffer.alloc(44 + dataBytes);
+    out.write('RIFF', 0, 'ascii');
+    out.writeUInt32LE(36 + dataBytes, 4);
+    out.write('WAVE', 8, 'ascii');
+    out.write('fmt ', 12, 'ascii');
+    out.writeUInt32LE(16, 16);
+    out.writeUInt16LE(WAVE_FORMAT_PCM, 20);
+    out.writeUInt16LE(channels, 22);
+    out.writeUInt32LE(sampleRate, 24);
+    out.writeUInt32LE(sampleRate * channels * 2, 28);
+    out.writeUInt16LE(channels * 2, 32);
+    out.writeUInt16LE(16, 34);
+    out.write('data', 36, 'ascii');
+    out.writeUInt32LE(dataBytes, 40);
+    for (let i = 0; i < samples.length; i++)
+        out.writeInt16LE(samples[i] ?? 0, 44 + i * 2);
+    return out;
+}
+/** Encode mono samples as a 32-bit float WAV (lossless for neural voices that produce floats). */
+export function encodeWavFloat32(samples, sampleRate) {
+    const dataBytes = samples.length * 4;
+    const out = Buffer.alloc(44 + dataBytes);
+    out.write('RIFF', 0, 'ascii');
+    out.writeUInt32LE(36 + dataBytes, 4);
+    out.write('WAVE', 8, 'ascii');
+    out.write('fmt ', 12, 'ascii');
+    out.writeUInt32LE(16, 16);
+    out.writeUInt16LE(WAVE_FORMAT_FLOAT, 20);
+    out.writeUInt16LE(1, 22);
+    out.writeUInt32LE(sampleRate, 24);
+    out.writeUInt32LE(sampleRate * 4, 28);
+    out.writeUInt16LE(4, 32);
+    out.writeUInt16LE(32, 34);
+    out.write('data', 36, 'ascii');
+    out.writeUInt32LE(dataBytes, 40);
+    for (let i = 0; i < samples.length; i++)
+        out.writeFloatLE(samples[i] ?? 0, 44 + i * 4);
+    return out;
+}
+/** Little-endian 16-bit PCM bytes for the given samples. */
+export function int16ToPcmS16le(samples) {
+    const out = Buffer.alloc(samples.length * 2);
+    for (let i = 0; i < samples.length; i++)
+        out.writeInt16LE(samples[i] ?? 0, i * 2);
+    return out;
+}
+/** Convert little-endian 16-bit PCM bytes to floats in [-1, 1). A trailing odd byte is ignored. */
+export function pcmS16leToFloat(bytes) {
+    const count = Math.floor(bytes.length / 2);
+    const out = new Float32Array(count);
+    for (let i = 0; i < count; i++)
+        out[i] = bytes.readInt16LE(i * 2) / 32768;
+    return out;
+}
+/** Decode any PCM or float WAV to mono floats at its own sample rate (channels are averaged). */
+export function decodeWavToMono(buf) {
+    const info = parseWavHeader(buf);
+    const bytesPerSample = info.bitsPerSample / 8;
+    const frameBytes = bytesPerSample * info.channels;
+    const frames = Math.floor(info.dataBytes / frameBytes);
+    const out = new Float32Array(frames);
+    const read = sampleReader(info);
+    for (let f = 0; f < frames; f++) {
+        let sum = 0;
+        const base = info.dataOffset + f * frameBytes;
+        for (let c = 0; c < info.channels; c++)
+            sum += read(buf, base + c * bytesPerSample);
+        out[f] = sum / info.channels;
+    }
+    return { samples: out, sampleRate: info.sampleRate };
+}
+function sampleReader(info) {
+    if (info.encoding === 'float') {
+        return info.bitsPerSample === 32 ? (b, at) => b.readFloatLE(at) : (b, at) => b.readDoubleLE(at);
+    }
+    switch (info.bitsPerSample) {
+        case 8:
+            return (b, at) => ((b[at] ?? 128) - 128) / 128;
+        case 16:
+            return (b, at) => b.readInt16LE(at) / 32768;
+        case 24:
+            return (b, at) => b.readIntLE(at, 3) / 8388608;
+        default:
+            return (b, at) => b.readInt32LE(at) / 2147483648;
+    }
+}
+/** Read a clip written by this module: mono, 48 kHz, 16-bit PCM. Throws for any other layout. */
+export function readCanonicalWav(buf) {
+    const info = parseWavHeader(buf);
+    if (info.encoding !== 'pcm' ||
+        info.bitsPerSample !== 16 ||
+        info.channels !== 1 ||
+        info.sampleRate !== CANONICAL_RATE) {
+        throw new Error('Clip is not mono 48 kHz 16-bit PCM');
+    }
+    const count = Math.floor(info.dataBytes / 2);
+    const out = new Int16Array(count);
+    for (let i = 0; i < count; i++)
+        out[i] = buf.readInt16LE(info.dataOffset + i * 2);
+    return out;
+}
+/** Duration in seconds of a WAV file, from its header. */
+export function wavDurationSec(buf) {
+    const info = parseWavHeader(buf);
+    return info.dataBytes / (info.channels * (info.bitsPerSample / 8)) / info.sampleRate;
+}
+//# sourceMappingURL=wav.js.map

package/dist/pipeline/authoring.d.ts

@@ -0,0 +1,8 @@
+import { type ValidationResult } from '../storyboard/index.ts';
+import type { AuthoringOptions, AuthoringResult, GenerateHooks, GenerateOptions } from './types.ts';
+/** Analyse a change and write everything an agent needs to author a storyboard itself. Free and offline (besides reading the PR). */
+export declare function prepareAuthoring(options: AuthoringOptions, hooks?: GenerateHooks): Promise<AuthoringResult>;
+/** Validate a storyboard against a change without rendering (mergestory validate). */
+export declare function checkStoryboard(options: Omit<GenerateOptions, 'dryRun'> & {
+    storyboard: unknown;
+}, hooks?: GenerateHooks): Promise<ValidationResult>;

package/dist/pipeline/authoring.js

@@ -0,0 +1,117 @@
+/**
+ * For callers that write the storyboard themselves (a coding agent, or a person): prepare the
+ * evidence and the guide, then check what they wrote without rendering anything.
+ */
+import { writeFile } from 'node:fs/promises';
+import { estimateTokens } from '../core/cost.js';
+import { runFolder, writeRunJson } from '../core/run-folder.js';
+import { wordBudget } from '../core/storyboard-facts.js';
+import { storyboardJsonSchema } from '../core/storyboard-schema.js';
+import { AUTHORING_GUIDE, validateStoryboard } from '../storyboard/index.js';
+import { commandLine } from './commands.js';
+import { describeFit } from './fit-duration.js';
+import { packFor, prepare } from './prepare.js';
+import { changeLabel, repoLabel } from './presentation.js';
+import { fitStoryboard } from './storyboard-choice.js';
+/** The evidence pack for an author may be larger than the one for a model: nobody pays per token here. */
+const AUTHOR_PACK_TOKENS = 40_000;
+/** Analyse a change and write everything an agent needs to author a storyboard itself. Free and offline (besides reading the PR). */
+export async function prepareAuthoring(options, hooks = {}) {
+    const p = await prepare({ ...options, dryRun: true }, hooks, options.outDir ?? null);
+    const { ctx } = p;
+    const pack = packFor(p, Math.max(AUTHOR_PACK_TOKENS, p.config.llm.maxInputTokens));
+    const folder = runFolder(ctx.runDir);
+    const files = {
+        analysis: folder.analysis,
+        evidence: folder.evidence,
+        guide: folder.guide,
+        schema: folder.schema,
+    };
+    await writeFile(files.evidence, pack.markdown, { mode: 0o600 });
+    await writeFile(files.guide, authoringDocument(p, options.followUp ?? null), { mode: 0o600 });
+    await writeRunJson(files.schema, storyboardJsonSchema());
+    ctx.progress({
+        stage: 'analyze',
+        status: 'done',
+        message: `Wrote the evidence pack (${pack.includedHunks.length} hunks, about ${estimateTokens(pack.markdown)} tokens)`,
+    });
+    return {
+        runId: ctx.runId,
+        runDir: ctx.runDir,
+        files,
+        summary: {
+            title: p.changeSet.pr?.title ?? p.changeSet.commits[0]?.subject ?? changeLabel(p.changeSet),
+            changeLabel: `${repoLabel(p.changeSet)} ${changeLabel(p.changeSet)}`,
+            size: p.analysis.size,
+            files: p.changeSet.stats.files,
+            suggestedDurationSec: p.targetSec,
+            evidenceItems: p.analysis.evidence.length,
+        },
+    };
+}
+/**
+ * The text of AUTHORING.md. Steps 3 and 4 show `validate` and `generate` with the source and flags
+ * that `analyze` ran with. Task, notes, test results and screenshots are what create the ids TASK,
+ * NOTES, T1 and SS1, so a command that leaves them out would remove every line that cites them.
+ */
+function authoringDocument(p, followUp) {
+    const storyboard = runFolder(p.ctx.runDir).storyboard;
+    const validate = followUp
+        ? commandLine(['mergestory', 'validate', storyboard, followUp.source, ...followUp.args])
+        : 'mergestory validate storyboard.json <source>';
+    const generate = followUp
+        ? commandLine(['mergestory', 'generate', followUp.source, ...followUp.args, '--storyboard', storyboard])
+        : 'mergestory generate <source> --storyboard storyboard.json';
+    return [
+        '# Writing the storyboard',
+        '',
+        `Target length: about ${p.targetSec} seconds (about ${wordBudget(p.targetSec)} words of narration in total).`,
+        `Longest video: ${p.config.maxDurationSec} seconds. When a storyboard is estimated to be longer, \`generate\` leaves out the least important scenes and lines (never the mission or the review scene).`,
+        `Style: ${p.config.style}. Narration language: ${p.config.language}.`,
+        '',
+        '1. Read `evidence.md` in this folder. It lists every fact you may use, each with an id.',
+        '2. Write `storyboard.json` that matches `storyboard.schema.json`, following the rules below.',
+        `3. Check it: \`${validate}\` (fix every error it reports).`,
+        `4. Render it: \`${generate}\`.`,
+        ...(followUp
+            ? []
+            : [
+                '',
+                'Give both commands the same source and the same `--base`, `--head`, `--task-file`, `--notes-file`, `--tests-file`',
+                'and `--screenshot` flags as the analysis. They create the ids TASK, NOTES, T1 and SS1. Without them those ids do not',
+                'exist, and lines that cite only them are removed.',
+            ]),
+        '',
+        'You know why the change was made. Put that in the narration, but only claim what the evidence shows.',
+        'Decisions and context that are not in the diff belong in the task or notes (`--task-file`, `--notes-file`),',
+        'so they become citable evidence (TASK, NOTES).',
+        '',
+        AUTHORING_GUIDE,
+    ].join('\n');
+}
+/** Validate a storyboard against a change without rendering (mergestory validate). */
+export async function checkStoryboard(options, hooks = {}) {
+    // Nothing here reads analysis.json, so no run folder is made.
+    const p = await prepare({ ...options, dryRun: true }, hooks, undefined, { writeAnalysis: false });
+    const result = await validateStoryboard(options.storyboard, {
+        changeSet: p.changeSet,
+        analysis: p.analysis,
+        inputs: p.inputs,
+        reader: p.reader,
+        config: p.config,
+    });
+    if (!result.storyboard)
+        return result;
+    // Say what rendering would do when the storyboard is over the maximum length.
+    const messages = describeFit(fitStoryboard(p, result.storyboard), p.config.maxDurationSec, 'would');
+    if (messages.length === 0)
+        return result;
+    return {
+        ...result,
+        warnings: [
+            ...result.warnings,
+            ...messages.map((message) => ({ path: 'scenes', code: 'over-length', message })),
+        ],
+    };
+}
+//# sourceMappingURL=authoring.js.map

package/dist/pipeline/commands.d.ts

@@ -0,0 +1,9 @@
+/** Command lines that hints and documents show to people. Quoted, so they can be pasted into a shell. */
+import type { Config } from '../core/config.ts';
+/** The words of a command, quoted and joined. */
+export declare function commandLine(args: readonly string[]): string;
+/**
+ * The command that uploads a rendered run again, with the settings that this run used, so that
+ * a command line that was only typed once (flags are not stored) is not needed to try again.
+ */
+export declare function publishCommand(runDir: string, config: Config): string;

package/dist/pipeline/commands.js

@@ -0,0 +1,21 @@
+import { shellQuote } from '../core/text.js';
+/** The words of a command, quoted and joined. */
+export function commandLine(args) {
+    return args.map(shellQuote).join(' ');
+}
+/**
+ * The command that uploads a rendered run again, with the settings that this run used, so that
+ * a command line that was only typed once (flags are not stored) is not needed to try again.
+ */
+export function publishCommand(runDir, config) {
+    const { provider, visibility } = config.publish;
+    const args = ['mergestory', 'publish', runDir, '--publish', provider === 'none' ? 'local' : provider];
+    if (provider === 's3')
+        args.push('--visibility', visibility);
+    if (config.github.comment)
+        args.push('--comment');
+    if (config.github.updateDescription)
+        args.push('--update-description');
+    return commandLine(args);
+}
+//# sourceMappingURL=commands.js.map

package/dist/pipeline/fit-duration.d.ts

@@ -0,0 +1,41 @@
+import { type SceneRole, type Storyboard } from '../core/storyboard-schema.ts';
+export interface EstimateOptions {
+    /** Narration language, which decides how identifiers are spoken. */
+    language: string;
+    /** Whether e-mail addresses are masked, as they are in narration and captions. */
+    maskEmails: boolean;
+}
+export interface FitOptions extends EstimateOptions {
+    /** The limit in seconds. */
+    maxSec: number;
+    /** Ids of the changed files, hunks and symbols. A simulated scene keeps a line that cites one of them. */
+    backingEvidence: ReadonlySet<string>;
+}
+export interface FitResult {
+    /** The storyboard to use: the one that was given when it already fits, else a trimmed copy. */
+    storyboard: Storyboard;
+    /** Estimated length before and after trimming, in seconds. */
+    beforeSec: number;
+    afterSec: number;
+    droppedScenes: {
+        id: string;
+        title: string;
+        role: SceneRole;
+    }[];
+    /** Lines that were dropped from scenes that stayed. */
+    droppedLines: number;
+    /** false when only the scenes that are never dropped are left and they are still too long. */
+    fits: boolean;
+}
+/** Estimated length of the finished video, in seconds, including the title and the end card. */
+export declare function estimateVideoSeconds(storyboard: Storyboard, options: EstimateOptions): number;
+/**
+ * Trim a storyboard until its estimated length is at most `options.maxSec`, or until only the
+ * scenes that must stay are left. The given storyboard is never changed.
+ */
+export declare function fitToMaxDuration(storyboard: Storyboard, options: FitOptions): FitResult;
+/**
+ * What to tell the person about a trim. Nothing when the storyboard already fit. `would` is for
+ * `validate`, which only checks: it says what rendering would drop.
+ */
+export declare function describeFit(result: FitResult, maxSec: number, mode?: 'trimmed' | 'would'): string[];

package/dist/pipeline/fit-duration.js

@@ -0,0 +1,150 @@
+/**
+ * Keeping a storyboard within the maximum video length (--max-duration).
+ *
+ * The real length is only known once speech exists, and speech is the step that can cost money. So
+ * the storyboard is trimmed before narration, against an estimate: every line takes as long as its
+ * words need at the speaking rate of the silent provider, and the title, pauses, minimum scene
+ * lengths, transitions and end card are added the way the real timeline adds them.
+ *
+ * Whole scenes go first, the least important first: the wrap-up, the overview, then the code
+ * scenes, later ones before earlier ones. When a scene only has to lose a little, it loses its last
+ * lines instead of disappearing. The mission and review scenes are never dropped, and every scene
+ * keeps at least one line. If those scenes alone are too long, the result says so.
+ *
+ * What this guarantees: the estimate fits, or the result says that it cannot. It does not
+ * guarantee the length of the finished video, because a real voice is a little faster or slower than
+ * the estimate.
+ */
+import { beatHolders, isSimulated } from '../core/storyboard-facts.js';
+import { STORYBOARD_LIMITS } from '../core/storyboard-schema.js';
+import { naturalList, plural } from '../core/text.js';
+import { estimateNarration } from '../narration/index.js';
+import { buildTimeline } from '../visuals/timeline.js';
+/** Scenes of these roles are never dropped. */
+const PROTECTED_ROLES = new Set(['mission', 'review']);
+/** Which scenes go first: a lower number is dropped earlier. Scenes with the same number go last to first. */
+const DROP_ORDER = {
+    conclusion: 0,
+    'big-picture': 1,
+    'under-the-hood': 2,
+    'before-after': 2,
+    mission: 3,
+    review: 3,
+};
+/** Estimated length of the finished video, in seconds, including the title and the end card. */
+export function estimateVideoSeconds(storyboard, options) {
+    return buildTimeline(storyboard, estimateNarration(storyboard, options)).durationSec;
+}
+/** Whether the last line of a scene can go. A simulated scene must stay backed by a changed file, hunk or symbol. */
+function canDropLastLine(scene, backing) {
+    if (scene.narration.length < 2)
+        return false;
+    if (!isSimulated(scene.visual))
+        return true;
+    return scene.narration.slice(0, -1).some((line) => line.evidence.some((id) => backing.has(id)));
+}
+/** Drop the last line. Elements that appeared on it appear on the new last line instead. */
+function dropLastLine(scene) {
+    scene.narration.pop();
+    const last = scene.narration.length - 1;
+    for (const holder of beatHolders(scene.visual)) {
+        if (holder.beat > last)
+            holder.beat = last;
+    }
+}
+/** The next thing to leave out, or null when only what must stay is left. */
+function nextStep(storyboard, excessSec, options, estimate, currentSec) {
+    const { scenes } = storyboard;
+    const canDropScene = scenes.length > STORYBOARD_LIMITS.minScenes;
+    const optional = scenes
+        .map((scene, index) => ({ scene, index }))
+        .filter(({ scene }) => !PROTECTED_ROLES.has(scene.role))
+        .sort((a, b) => DROP_ORDER[a.scene.role] - DROP_ORDER[b.scene.role] || b.index - a.index);
+    for (const { scene, index } of optional) {
+        if (canDropLastLine(scene, options.backingEvidence)) {
+            // Dropping lines is gentler than dropping the scene, so it is used whenever it is enough.
+            const trial = structuredClone(storyboard);
+            const trialScene = trial.scenes[index];
+            while (canDropLastLine(trialScene, options.backingEvidence))
+                dropLastLine(trialScene);
+            if (!canDropScene || currentSec - estimate(trial) >= excessSec)
+                return { kind: 'line', index };
+        }
+        if (canDropScene)
+            return { kind: 'scene', index };
+    }
+    // Only the scenes that stay are left: shorten the one with the most lines, the later one on a tie.
+    const longest = scenes
+        .map((scene, index) => ({ scene, index }))
+        .filter(({ scene }) => canDropLastLine(scene, options.backingEvidence))
+        .sort((a, b) => b.scene.narration.length - a.scene.narration.length || b.index - a.index)[0];
+    return longest ? { kind: 'line', index: longest.index } : null;
+}
+/**
+ * Trim a storyboard until its estimated length is at most `options.maxSec`, or until only the
+ * scenes that must stay are left. The given storyboard is never changed.
+ */
+export function fitToMaxDuration(storyboard, options) {
+    const estimate = (candidate) => estimateVideoSeconds(candidate, options);
+    const beforeSec = estimate(storyboard);
+    if (beforeSec <= options.maxSec) {
+        return { storyboard, beforeSec, afterSec: beforeSec, droppedScenes: [], droppedLines: 0, fits: true };
+    }
+    const work = structuredClone(storyboard);
+    // A length hint can only stretch a scene, so it is the first thing to give up.
+    for (const scene of work.scenes)
+        scene.targetSeconds = null;
+    let seconds = estimate(work);
+    const droppedScenes = [];
+    while (seconds > options.maxSec) {
+        const step = nextStep(work, seconds - options.maxSec, options, estimate, seconds);
+        if (!step)
+            break;
+        if (step.kind === 'scene') {
+            const [scene] = work.scenes.splice(step.index, 1);
+            droppedScenes.push({ id: scene.id, title: scene.title, role: scene.role });
+        }
+        else {
+            dropLastLine(work.scenes[step.index]);
+        }
+        seconds = estimate(work);
+    }
+    // Lines that went with a scene that was dropped later are not counted twice.
+    const linesBefore = new Map(storyboard.scenes.map((scene) => [scene.id, scene.narration.length]));
+    const droppedLines = work.scenes.reduce((sum, scene) => sum + ((linesBefore.get(scene.id) ?? scene.narration.length) - scene.narration.length), 0);
+    return {
+        storyboard: work,
+        beforeSec,
+        afterSec: seconds,
+        droppedScenes,
+        droppedLines,
+        fits: seconds <= options.maxSec,
+    };
+}
+/**
+ * What to tell the person about a trim. Nothing when the storyboard already fit. `would` is for
+ * `validate`, which only checks: it says what rendering would drop.
+ */
+export function describeFit(result, maxSec, mode = 'trimmed') {
+    if (result.beforeSec <= maxSec)
+        return [];
+    const sec = (value) => `${Math.round(value)} s`;
+    const dropped = [];
+    if (result.droppedScenes.length > 0) {
+        dropped.push(`${result.droppedScenes.length === 1 ? 'the scene' : 'the scenes'} ${naturalList(result.droppedScenes.map((s) => `"${s.title}"`))}`);
+    }
+    if (result.droppedLines > 0)
+        dropped.push(plural(result.droppedLines, 'narration line'));
+    let message = `The storyboard is estimated at ${sec(result.beforeSec)}, over the maximum of ${sec(maxSec)} (--max-duration).`;
+    if (dropped.length > 0) {
+        message +=
+            mode === 'trimmed'
+                ? ` Left out to shorten it: ${dropped.join(', and ')}. It is now estimated at ${sec(result.afterSec)}.`
+                : ` Rendering would leave out ${dropped.join(', and ')}, which brings it to ${sec(result.afterSec)}.`;
+    }
+    if (!result.fits) {
+        message += ` The mission and review scenes are never dropped, so the maximum of ${sec(maxSec)} cannot be reached with this storyboard. Raise --max-duration, or write shorter narration.`;
+    }
+    return [message];
+}
+//# sourceMappingURL=fit-duration.js.map

package/dist/pipeline/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The pipeline: source -> analysis -> storyboard -> grounding -> narration -> visuals -> render
+ * -> publish -> notify. This is the engine's main entry point; the CLI, the HTTP API, the job
+ * runner and library users all call these functions.
+ */
+export { checkStoryboard, prepareAuthoring } from './authoring.ts';
+export { publishRun } from './publish-run.ts';
+export { generate } from './run.ts';
+export type { AuthoringOptions, AuthoringResult, ContextOptions, GenerateHooks, GenerateOptions, PublishRunOptions, } from './types.ts';

package/dist/pipeline/index.js

@@ -0,0 +1,9 @@
+/**
+ * The pipeline: source -> analysis -> storyboard -> grounding -> narration -> visuals -> render
+ * -> publish -> notify. This is the engine's main entry point; the CLI, the HTTP API, the job
+ * runner and library users all call these functions.
+ */
+export { checkStoryboard, prepareAuthoring } from './authoring.js';
+export { publishRun } from './publish-run.js';
+export { generate } from './run.js';
+//# sourceMappingURL=index.js.map

package/dist/pipeline/inputs.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import type { Storyboard } from '../core/storyboard-schema.ts';
+import type { ContextInputs, TestEvidence } from '../core/types.ts';
+import type { ContextOptions } from './types.ts';
+/** Limits of the context. Longer lists and texts are cut or refused here, so every caller sees the same ones. */
+export declare const MAX_TEXT: number;
+export declare const MAX_SCREENSHOTS = 6;
+/** Test results that reach the evidence. A longer list is cut, with a warning. */
+export declare const MAX_TESTS = 10;
+/** Most entries accepted in a list of test results at all. */
+export declare const MAX_TEST_ENTRIES = 200;
+export declare const TEST_SOURCES: readonly ['agent', 'ci', 'user'];
+/**
+ * One test result the caller reports. Strict on purpose: a typo such as "pass" for "passed", or the
+ * string "false" for false, must never turn into a made-up result. The messages complete the
+ * sentence "entry 3 ...".
+ */
+export declare const TestResultSchema: z.ZodObject<{
+    command: z.ZodString;
+    passed: z.ZodBoolean;
+    summary: z.ZodString;
+    source: z.ZodDefault<z.ZodEnum<{
+        agent: "agent";
+        ci: "ci";
+        user: "user";
+    }>>;
+}, z.core.$strict>;
+/** Check a list of test results. `label` names the input in the error ("--tests-file", "tests"). */
+export declare function checkTestResults(value: unknown, label?: string): Omit<TestEvidence, 'id'>[];
+/**
+ * Check a screenshot the way the video does: PNG or JPEG by content (never by file name), at most
+ * 4 MiB and 40 megapixels. A file that the video could not draw is refused here, at once, and not
+ * after narration has been paid for. Returns the absolute path. `label` names the input in errors.
+ */
+export declare function checkScreenshotFile(path: string, cwd: string, label?: string): Promise<string>;
+export declare function buildContextInputs(options: ContextOptions | undefined, cwd: string, warn?: (message: string) => void): Promise<ContextInputs>;
+/**
+ * A warning when screenshots were supplied but the storyboard does not show them all, or null.
+ * The offline storyboard never uses screenshots, which is worth saying because the person did
+ * pass them on purpose.
+ */
+export declare function unusedScreenshotWarning(storyboard: Storyboard, inputs: ContextInputs, source: 'llm' | 'agent' | 'heuristic'): string | null;