@m0saic/templates 0.2.0

package/dist/m0saic/story/narrated-chapters/v1/pipeline.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Pipeline assembly — the structural core of the template.
+ *
+ * OUTER: emit:"multi", one step per output VARIANT (aspect). Authored
+ * emit:"multi" escapes assertTiming's stitched-length invariant, which is
+ * what makes narration-derived duration legal. One variant collapses to the
+ * bare `-o` path (no concat is planned for a single video output step); two
+ * variants fan out to `<out>-landscape.mp4` / `<out>-portrait.mp4`.
+ *
+ * INNER: one emit:"single" story pipeline per variant, at that variant's
+ * own canvas. Scenes are plain builders (scenes/card.ts, scenes/body.ts) —
+ * pure functions, not registered subtemplates; each pipeline STEP is its
+ * own ffmpeg command, so every scene gets a fresh overlay-depth budget.
+ *
+ * ⚠ Stamp hazard (the reason for every seemingly redundant field below):
+ * `stampStepInlineDoc` treats a step's `file` like a document — it writes
+ * `size: doc.size ?? outerTarget`, `fps: doc.fps ?? src.fps`, and
+ * `durationMs: step.durationMs` UNCONDITIONALLY, and it does NOT recurse
+ * into inner steps. So the nested pipeline MUST self-declare `size`/`fps`/
+ * `durationMs` (an undeclared size silently renders the portrait cut at the
+ * landscape canvas), every outer `step.durationMs` MUST equal the nested
+ * natural length (the default durationFit is "loop" — a mismatch loops or
+ * trims the entire video), and every scene doc self-declares all three too.
+ * `durationFit:"cut"` at both levels makes any drift underrun VISIBLY
+ * rather than loop silently. `plan.storyMs` is a positive integer by
+ * construction — `isValidPipelineDurationMs` rejects fractional values and
+ * the declaration would be silently dropped.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSceneDoc = buildSceneDoc;
+exports.buildStoryPipeline = buildStoryPipeline;
+exports.buildOuterPipeline = buildOuterPipeline;
+const body_1 = require("./scenes/body");
+const card_1 = require("./scenes/card");
+/** Dispatch one scene to its builder. */
+function buildSceneDoc(scene, variant, plan, theme, media, music) {
+    if (scene.kind === "body") {
+        const sectionMedia = scene.sectionIndex !== undefined ? media[scene.sectionIndex] : undefined;
+        return (0, body_1.buildBodyDoc)(scene, sectionMedia, variant, plan, theme, music);
+    }
+    return (0, card_1.buildCardDoc)(scene, variant, plan, theme, music);
+}
+/** The INNER pipeline — the whole story at one variant's canvas. */
+function buildStoryPipeline(plan, variant, theme, media, music) {
+    const steps = plan.scenes.map((scene) => ({
+        name: scene.name,
+        label: scene.name,
+        // The step CARRIES its own overlap: durationMs = visible + xfadeOut, so
+        // the stitched natural length is Σ visible === storyMs exactly.
+        durationMs: scene.visibleMs + scene.xfadeOutMs,
+        file: buildSceneDoc(scene, variant, plan, theme, media, music),
+        ...(scene.xfadeOutMs > 0
+            ? { transitionToNext: { type: "fade", durationMs: scene.xfadeOutMs } }
+            : {}),
+    }));
+    return {
+        kind: "mosaic_pipeline",
+        version: 1,
+        emit: "single", // explicit — never rely on the nested-emit downgrade
+        size: { width: variant.width, height: variant.height }, // MANDATORY (stamp hazard)
+        fps: plan.fps, // MANDATORY
+        durationMs: plan.storyMs, // MANDATORY — equals the stitched natural
+        durationFit: "cut", // drift underruns VISIBLY, never silently loops
+        defaultTransition: { type: "cut" },
+        backgroundColor: theme.canvas,
+        steps,
+    };
+}
+/** The OUTER pipeline — one output step per variant. */
+function buildOuterPipeline(plan, target, theme, media, music) {
+    return {
+        kind: "mosaic_pipeline",
+        version: 1,
+        emit: "multi", // escapes the stitched-length invariant (assertTiming)
+        fps: target.fps, // must equal ctx.target.fps
+        size: { width: target.width, height: target.height },
+        durationMs: plan.storyMs, // preserved by the stamp as authoring intent
+        durationFit: "cut",
+        // Templates have no first-class warning channel; parking the STORY_*
+        // diagnostics on meta.note makes them inspectable via --save-mosaic
+        // instead of vanishing (a proper surface is an open engine question).
+        ...(plan.diagnostics.length > 0 ? { meta: { note: plan.diagnostics.join("\n") } } : {}),
+        steps: plan.variants.map((variant) => ({
+            name: variant.name, // → <out>-landscape.mp4 / <out>-portrait.mp4
+            label: variant.name,
+            durationMs: plan.storyMs, // MUST equal the nested natural
+            // The step type says MosaicDocument; the planner dispatches on
+            // file.kind === "mosaic_pipeline" at runtime — same cast the engine
+            // itself uses for nested pipelines.
+            file: buildStoryPipeline(plan, variant, theme, media, music),
+        })),
+    };
+}

package/dist/m0saic/story/narrated-chapters/v1/plan.d.ts

@@ -0,0 +1,144 @@
+/**
+ * resolveTiming — story → StoryPlan, the template's single source of time.
+ *
+ * The timing model (verbatim from the brief):
+ *
+ *   X    = min(xfadeMs, tailPadMs, floor(min(all visible durations) / 2))
+ *
+ *   title            visible = titleCardMs      xfadeOut = X
+ *   for each i:
+ *     s{i}-card      visible = sectionCardMs    xfadeOut = 0   ← CUT into narration
+ *     s{i}-body      visible = max(minSectionMs, narrationMs_i + tailPadMs)
+ *                                               xfadeOut = X
+ *   outro            visible = outroMs          xfadeOut = 0
+ *
+ *   step.durationMs = visible + xfadeOut   (the step CARRIES its own overlap)
+ *   storyMs         = Σ visible            (exact, INTEGER ms — a fractional
+ *                                           declared durationMs is silently
+ *                                           dropped by the output stamp)
+ *   scene.startMs   = Σ_{j<k} visible_j
+ *
+ * The transition rule: a body step is never the B side of an xfade (its head
+ * carries narration from t=0); it may be the A side because its last
+ * X ≤ tailPadMs are padding. Cards cut into narration by design.
+ *
+ * narrationMs_i = overrides.durationMs (explicit wins) → probed audio
+ * durationMs → FAIL FAST. A section with no narration at ALL is not an
+ * error: it falls back to minSectionMs with a STORY_SECTION_NO_NARRATION
+ * diagnostic.
+ *
+ * Pure and provenance-blind: reads nothing but the fields it names.
+ */
+import { hamilton } from "./captions";
+import type { CaptionsConfig } from "./captions";
+import type { StoryCue, StoryDocument, StoryOutputName, StorySection, StoryTimingDefaults } from "./props";
+export { hamilton };
+export type SceneKind = "title" | "section-card" | "body" | "outro";
+/** One image's slot in a body scene, on the SCENE-LOCAL clock. */
+export type SceneImageSlot = {
+    /** Index into the section's `images` array. */
+    imageIndex: number;
+    startMs: number;
+    /** Hamilton-distributed so Σ durations === the step's full length exactly. */
+    durationMs: number;
+};
+export type StoryScene = {
+    kind: SceneKind;
+    /** Stable step slug: "title", "s0-card", "s0-body", …, "outro". */
+    name: string;
+    /** Present on section-card/body scenes. */
+    sectionIndex?: number;
+    sectionId?: string;
+    /** Text the scene leads with (title text / section heading / outro line). */
+    heading: string;
+    /** Secondary line on title/outro cards (the story subtitle). */
+    subheading?: string;
+    /** Integer ms this scene owns on the timeline. */
+    visibleMs: number;
+    /** Integer ms of crossfade INTO the next scene (0 = hard cut). */
+    xfadeOutMs: number;
+    /** Σ of all previous scenes' visibleMs. */
+    startMs: number;
+    /** True when a body length came from the minSectionMs fallback. */
+    noNarration?: boolean;
+    /** Body scenes: dwell schedule over the step's FULL duration (visible + xfadeOut). */
+    images?: SceneImageSlot[];
+    /** Body scenes: cross-dissolve length for images after the first. */
+    imageFadeMs?: number;
+    /** Body scenes: resolved narration length (explicit or probed), ms. */
+    narrationMs?: number;
+    /** Body scenes: final caption cues, narration-relative (== step-local). */
+    cues?: StoryCue[];
+};
+export declare const MOTION_EASES: readonly ["linear", "smoothstep", "easeOut", "easeInOut"];
+export type MotionEase = (typeof MOTION_EASES)[number];
+export type StoryMotionPlan = {
+    seed: number;
+    intensity: number;
+    /** Drift ease — "linear" is the genre default (constant velocity). */
+    ease: MotionEase;
+};
+export type StoryVariant = {
+    name: StoryOutputName;
+    width: number;
+    height: number;
+};
+export type StoryAudioPlan = {
+    narrationVolume: number;
+    musicVolume: number;
+    /** Raw music path string (the ctx.media key) — undefined = no music bed. */
+    musicPath?: string;
+    musicStartMs: number;
+};
+export type StoryPlan = {
+    fps: number;
+    /** Σ visible — integer, the length of every emitted deliverable. */
+    storyMs: number;
+    scenes: StoryScene[];
+    variants: StoryVariant[];
+    motion: StoryMotionPlan;
+    captions: CaptionsConfig;
+    audio: StoryAudioPlan;
+    /** Non-fatal notes, e.g. STORY_SECTION_NO_NARRATION. */
+    diagnostics: string[];
+};
+export type ResolveTimingOptions = {
+    fps: number;
+    target: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Probed audio duration for a raw (trimmed) asset-path string, or
+     * undefined when the path was never probed / has no duration.
+     */
+    narrationDurationMs: (rawPath: string) => number | undefined;
+};
+export type ResolveTimingResult = {
+    plan: StoryPlan;
+} | {
+    error: string;
+};
+export declare function resolveTiming(story: StoryDocument, options: ResolveTimingOptions): ResolveTimingResult;
+/**
+ * Images share the step's FULL duration D (including the crossfading tail,
+ * so the dissolve never freezes) via Hamilton largest-remainder, so
+ * Σ dwell === D exactly. Meff = min(M, max(1, floor(D / minImageDwellMs)));
+ * dropped images and mismatched weight lists get named diagnostics, never
+ * silence.
+ */
+export declare function scheduleImages(section: StorySection, sectionIndex: number, stepMs: number, eff: Required<StoryTimingDefaults>, diagnostics: string[]): SceneImageSlot[];
+/**
+ * One deliverable per outputs entry. The requested canvas gives the base
+ * geometry: the landscape cut uses (long × short), the portrait cut
+ * (short × long) — so `-w 1920 -h 1080` yields 1920×1080 / 1080×1920.
+ *
+ * When `outputs` is omitted, the default variant ADOPTS the requested
+ * canvas orientation (a bare `-w 1080 -h 1920` renders portrait) — the
+ * absolute landscape/portrait names only re-orient when the manifest asks
+ * for an aspect explicitly.
+ */
+export declare function resolveVariants(outputs: StoryOutputName[] | undefined, target: {
+    width: number;
+    height: number;
+}): StoryVariant[];

package/dist/m0saic/story/narrated-chapters/v1/plan.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * resolveTiming — story → StoryPlan, the template's single source of time.
+ *
+ * The timing model (verbatim from the brief):
+ *
+ *   X    = min(xfadeMs, tailPadMs, floor(min(all visible durations) / 2))
+ *
+ *   title            visible = titleCardMs      xfadeOut = X
+ *   for each i:
+ *     s{i}-card      visible = sectionCardMs    xfadeOut = 0   ← CUT into narration
+ *     s{i}-body      visible = max(minSectionMs, narrationMs_i + tailPadMs)
+ *                                               xfadeOut = X
+ *   outro            visible = outroMs          xfadeOut = 0
+ *
+ *   step.durationMs = visible + xfadeOut   (the step CARRIES its own overlap)
+ *   storyMs         = Σ visible            (exact, INTEGER ms — a fractional
+ *                                           declared durationMs is silently
+ *                                           dropped by the output stamp)
+ *   scene.startMs   = Σ_{j<k} visible_j
+ *
+ * The transition rule: a body step is never the B side of an xfade (its head
+ * carries narration from t=0); it may be the A side because its last
+ * X ≤ tailPadMs are padding. Cards cut into narration by design.
+ *
+ * narrationMs_i = overrides.durationMs (explicit wins) → probed audio
+ * durationMs → FAIL FAST. A section with no narration at ALL is not an
+ * error: it falls back to minSectionMs with a STORY_SECTION_NO_NARRATION
+ * diagnostic.
+ *
+ * Pure and provenance-blind: reads nothing but the fields it names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOTION_EASES = exports.hamilton = void 0;
+exports.resolveTiming = resolveTiming;
+exports.scheduleImages = scheduleImages;
+exports.resolveVariants = resolveVariants;
+const captions_1 = require("./captions");
+Object.defineProperty(exports, "hamilton", { enumerable: true, get: function () { return captions_1.hamilton; } });
+const props_1 = require("./props");
+exports.MOTION_EASES = ["linear", "smoothstep", "easeOut", "easeInOut"];
+function resolveTiming(story, options) {
+    var _a, _b, _c;
+    const sections = Array.isArray(story.sections) ? story.sections : [];
+    if (sections.length === 0 || sections.length > props_1.MAX_SECTIONS) {
+        return { error: `story.sections must contain 1–${props_1.MAX_SECTIONS} sections, got ${sections.length}.` };
+    }
+    const defaults = {
+        ...props_1.DEFAULT_STORY_DEFAULTS,
+        ...pickTimingDefaults(story.defaults),
+    };
+    const diagnostics = [];
+    // -- narration length per section (the load-bearing derivation) -----------
+    const bodyVisible = [];
+    const cardVisible = [];
+    const noNarration = [];
+    const narrationLen = [];
+    for (let i = 0; i < sections.length; i++) {
+        const section = (_a = sections[i]) !== null && _a !== void 0 ? _a : {};
+        const eff = { ...defaults, ...pickTimingDefaults(section.overrides) };
+        cardVisible.push(Math.round(eff.sectionCardMs));
+        noteDocumentLevelOverrides(section, i, diagnostics);
+        const explicit = (_b = section.overrides) === null || _b === void 0 ? void 0 : _b.durationMs;
+        let narrationMs;
+        if (typeof explicit === "number" && Number.isFinite(explicit) && explicit > 0) {
+            narrationMs = explicit;
+            // The override wins, but a large disagreement with the probed audio is
+            // usually a stale manifest — say so instead of drifting silently.
+            if (typeof section.narrationAudio === "string" && section.narrationAudio.trim().length > 0) {
+                const probed = options.narrationDurationMs(section.narrationAudio.trim());
+                if (probed !== undefined && Math.abs(probed - explicit) > 250) {
+                    diagnostics.push(`STORY_DURATION_OVERRIDE_DISAGREES: ${sectionLabel(section, i)} overrides.durationMs (${explicit} ms) disagrees with the probed narration (${Math.round(probed)} ms) by more than 250 ms — the override wins.`);
+                }
+            }
+        }
+        else if (typeof section.narrationAudio === "string" && section.narrationAudio.trim().length > 0) {
+            narrationMs = options.narrationDurationMs(section.narrationAudio.trim());
+            if (narrationMs === undefined) {
+                return { error: missingNarrationError(section, i) };
+            }
+        }
+        narrationLen.push(narrationMs === undefined ? undefined : Math.round(narrationMs));
+        if (narrationMs === undefined) {
+            // No narration at all — legal; the section holds for minSectionMs.
+            diagnostics.push(`STORY_SECTION_NO_NARRATION: ${sectionLabel(section, i)} has neither narrationAudio nor overrides.durationMs — holding for minSectionMs (${eff.minSectionMs} ms).`);
+            bodyVisible.push(Math.round(eff.minSectionMs));
+            noNarration.push(true);
+        }
+        else {
+            bodyVisible.push(Math.max(Math.round(eff.minSectionMs), Math.round(narrationMs + eff.narrationTailPadMs)));
+            noNarration.push(false);
+        }
+    }
+    const titleVisible = Math.round(defaults.titleCardMs);
+    const outroVisible = Math.round(defaults.outroMs);
+    // Fail fast on zero-length scenes: the engine hard-rejects a 0ms pipeline
+    // step (PIPELINE_BAD_DURATION) and a 0 in the visible set would collapse X
+    // to 0, silently deleting every crossfade — better to name the field here.
+    if (titleVisible < 1)
+        return { error: badDurationError("defaults.titleCardMs", titleVisible) };
+    if (outroVisible < 1)
+        return { error: badDurationError("defaults.outroMs", outroVisible) };
+    for (let i = 0; i < sections.length; i++) {
+        if (cardVisible[i] < 1) {
+            return { error: badDurationError(`sections[${i}]'s effective sectionCardMs`, cardVisible[i]) };
+        }
+        if (bodyVisible[i] < 1) {
+            return {
+                error: `${sectionLabel((_c = sections[i]) !== null && _c !== void 0 ? _c : {}, i)}: resolves to a ${bodyVisible[i]} ms scene (no narration and minSectionMs too small). Every scene needs at least 1 ms.`,
+            };
+        }
+    }
+    const allVisible = [titleVisible, outroVisible, ...cardVisible, ...bodyVisible];
+    const xfadeMs = Math.max(0, Math.min(Math.floor(defaults.xfadeMs), Math.floor(defaults.narrationTailPadMs), Math.floor(Math.min(...allVisible) / 2)));
+    // -- scene list ------------------------------------------------------------
+    const scenes = [];
+    let startMs = 0;
+    const push = (scene) => {
+        scenes.push({ ...scene, startMs });
+        startMs += scene.visibleMs;
+    };
+    const captions = resolveCaptions(story);
+    noteUnknownPlate(story, diagnostics);
+    const audio = resolveAudio(story);
+    // Interim advisory while the founder decides the mix-headroom rule: only
+    // fires when a music bed actually exists (nothing can sum otherwise).
+    if (audio.musicPath !== undefined && audio.narrationVolume + audio.musicVolume > 1) {
+        diagnostics.push(`STORY_AUDIO_SUM: narrationVolume (${audio.narrationVolume}) + musicVolume (${audio.musicVolume}) exceeds 1.0 — the mixer sums with no limiter; simultaneous peaks may clip.`);
+    }
+    const title = typeof story.title === "string" ? story.title : "Untitled story";
+    const subtitle = typeof story.subtitle === "string" && story.subtitle.trim().length > 0 ? story.subtitle : undefined;
+    push({
+        kind: "title",
+        name: "title",
+        heading: title,
+        ...(subtitle !== undefined ? { subheading: subtitle } : {}),
+        visibleMs: titleVisible,
+        xfadeOutMs: xfadeMs,
+    });
+    sections.forEach((section, i) => {
+        var _a;
+        const id = typeof section.id === "string" && section.id.trim().length > 0 ? section.id : `section-${i + 1}`;
+        const heading = typeof section.title === "string" && section.title.trim().length > 0
+            ? section.title
+            : (_a = firstWords(section.narrationText, 6)) !== null && _a !== void 0 ? _a : id;
+        const eff = { ...defaults, ...pickTimingDefaults(section.overrides) };
+        push({
+            kind: "section-card",
+            name: `s${i}-card`,
+            sectionIndex: i,
+            sectionId: id,
+            heading,
+            visibleMs: cardVisible[i],
+            xfadeOutMs: 0, // hard cut — the narration's first word stays intact
+        });
+        if (typeof section.srt === "string" && section.srt.trim().length > 0 && !Array.isArray(section.cues)) {
+            diagnostics.push(`STORY_SRT_NOT_INLINED: ${sectionLabel(section, i)} declares "srt" but no inlined "cues" — templates never read files; run \`story-studio build\` to inline the cues.`);
+        }
+        push({
+            kind: "body",
+            name: `s${i}-body`,
+            sectionIndex: i,
+            sectionId: id,
+            heading,
+            visibleMs: bodyVisible[i],
+            xfadeOutMs: xfadeMs,
+            ...(noNarration[i] ? { noNarration: true } : {}),
+            images: scheduleImages(section, i, bodyVisible[i] + xfadeMs, eff, diagnostics),
+            imageFadeMs: Math.round(eff.imageFadeMs),
+            ...(narrationLen[i] !== undefined ? { narrationMs: narrationLen[i] } : {}),
+            cues: (0, captions_1.resolveSectionCues)(section, narrationLen[i], captions),
+        });
+    });
+    push({
+        kind: "outro",
+        name: "outro",
+        heading: title,
+        ...(subtitle !== undefined ? { subheading: subtitle } : {}),
+        visibleMs: outroVisible,
+        xfadeOutMs: 0, // final step — nothing to fade into
+    });
+    const storyMs = scenes.reduce((sum, s) => sum + s.visibleMs, 0);
+    return {
+        plan: {
+            fps: options.fps,
+            storyMs,
+            scenes,
+            variants: resolveVariants(story.outputs, options.target),
+            motion: resolveMotion(story, diagnostics),
+            captions,
+            audio,
+            diagnostics,
+        },
+    };
+}
+function resolveCaptions(story) {
+    const c = story.captions;
+    return {
+        enabled: typeof (c === null || c === void 0 ? void 0 : c.enabled) === "boolean" ? c.enabled : captions_1.DEFAULT_CAPTIONS.enabled,
+        minCueMs: typeof (c === null || c === void 0 ? void 0 : c.minCueMs) === "number" && Number.isFinite(c.minCueMs) && c.minCueMs >= 0
+            ? Math.round(c.minCueMs)
+            : captions_1.DEFAULT_CAPTIONS.minCueMs,
+        cueGapMs: typeof (c === null || c === void 0 ? void 0 : c.cueGapMs) === "number" && Number.isFinite(c.cueGapMs) && c.cueGapMs >= 0
+            ? Math.round(c.cueGapMs)
+            : captions_1.DEFAULT_CAPTIONS.cueGapMs,
+        plate: (c === null || c === void 0 ? void 0 : c.plate) === "never" ? "never" : "always",
+    };
+}
+function noteUnknownPlate(story, diagnostics) {
+    var _a;
+    const plate = (_a = story.captions) === null || _a === void 0 ? void 0 : _a.plate;
+    if (plate !== undefined && plate !== "always" && plate !== "never") {
+        diagnostics.push(`STORY_CAPTIONS_PLATE_UNKNOWN: captions.plate ${JSON.stringify(plate)} is not "always" or "never" — using "always".`);
+    }
+}
+function resolveAudio(story) {
+    const a = story.audio;
+    const vol = (v, fallback) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1 ? v : fallback;
+    return {
+        narrationVolume: vol(a === null || a === void 0 ? void 0 : a.narrationVolume, 1),
+        musicVolume: vol(a === null || a === void 0 ? void 0 : a.musicVolume, 0.1),
+        ...(typeof (a === null || a === void 0 ? void 0 : a.music) === "string" && a.music.trim().length > 0 ? { musicPath: a.music.trim() } : {}),
+        musicStartMs: typeof (a === null || a === void 0 ? void 0 : a.musicStartMs) === "number" && Number.isFinite(a.musicStartMs) && a.musicStartMs >= 0
+            ? Math.round(a.musicStartMs)
+            : 0,
+    };
+}
+function resolveMotion(story, diagnostics) {
+    const motion = story.motion;
+    const seed = typeof (motion === null || motion === void 0 ? void 0 : motion.seed) === "number" && Number.isFinite(motion.seed) ? Math.trunc(motion.seed) : 7;
+    const intensity = typeof (motion === null || motion === void 0 ? void 0 : motion.intensity) === "number" && Number.isFinite(motion.intensity) && motion.intensity >= 0
+        ? Math.min(motion.intensity, 2)
+        : 1;
+    let ease = "linear";
+    if ((motion === null || motion === void 0 ? void 0 : motion.ease) !== undefined) {
+        if (exports.MOTION_EASES.includes(motion.ease)) {
+            ease = motion.ease;
+        }
+        else {
+            diagnostics.push(`STORY_MOTION_EASE_UNKNOWN: motion.ease ${JSON.stringify(motion.ease)} is not one of ${exports.MOTION_EASES.join(", ")} — using "linear".`);
+        }
+    }
+    return { seed, intensity, ease };
+}
+/**
+ * Images share the step's FULL duration D (including the crossfading tail,
+ * so the dissolve never freezes) via Hamilton largest-remainder, so
+ * Σ dwell === D exactly. Meff = min(M, max(1, floor(D / minImageDwellMs)));
+ * dropped images and mismatched weight lists get named diagnostics, never
+ * silence.
+ */
+function scheduleImages(section, sectionIndex, stepMs, eff, diagnostics) {
+    var _a;
+    const images = Array.isArray(section.images)
+        ? section.images.filter((p) => typeof p === "string" && p.trim().length > 0)
+        : [];
+    const total = images.length;
+    if (total === 0)
+        return [];
+    const minDwell = Math.max(1, Math.round(eff.minImageDwellMs));
+    const effective = Math.min(total, Math.max(1, Math.floor(stepMs / minDwell)));
+    if (effective < total) {
+        diagnostics.push(`STORY_IMAGES_DROPPED: sections[${sectionIndex}] declares ${total} images but the scene (${stepMs} ms) fits only ${effective} at minImageDwellMs ${minDwell} — the last ${total - effective} are not shown.`);
+    }
+    const rawWeights = (_a = section.overrides) === null || _a === void 0 ? void 0 : _a.imageWeights;
+    let weights;
+    if (Array.isArray(rawWeights) && rawWeights.length > 0) {
+        if (rawWeights.length !== effective || !rawWeights.every((w) => typeof w === "number" && Number.isFinite(w) && w > 0)) {
+            diagnostics.push(`STORY_IMAGE_WEIGHTS_IGNORED: sections[${sectionIndex}].overrides.imageWeights must be ${effective} positive numbers (one per shown image); using equal weights.`);
+            weights = new Array(effective).fill(1);
+        }
+        else {
+            weights = rawWeights;
+        }
+    }
+    else {
+        weights = new Array(effective).fill(1);
+    }
+    let durations = (0, captions_1.hamilton)(stepMs, weights);
+    // Extreme weight ratios can starve a slot to 0 ms (the engine rejects
+    // zero-length anything). Degrade to equal weights, never silently.
+    if (durations.some((d) => d < 1)) {
+        diagnostics.push(`STORY_IMAGE_WEIGHTS_IGNORED: sections[${sectionIndex}].overrides.imageWeights are so extreme an image gets 0 ms; using equal weights.`);
+        durations = (0, captions_1.hamilton)(stepMs, new Array(effective).fill(1));
+    }
+    const slots = [];
+    let startMs = 0;
+    for (let k = 0; k < effective; k++) {
+        slots.push({ imageIndex: k, startMs, durationMs: durations[k] });
+        startMs += durations[k];
+    }
+    return slots;
+}
+/**
+ * One deliverable per outputs entry. The requested canvas gives the base
+ * geometry: the landscape cut uses (long × short), the portrait cut
+ * (short × long) — so `-w 1920 -h 1080` yields 1920×1080 / 1080×1920.
+ *
+ * When `outputs` is omitted, the default variant ADOPTS the requested
+ * canvas orientation (a bare `-w 1080 -h 1920` renders portrait) — the
+ * absolute landscape/portrait names only re-orient when the manifest asks
+ * for an aspect explicitly.
+ */
+function resolveVariants(outputs, target) {
+    const long = Math.max(target.width, target.height);
+    const short = Math.min(target.width, target.height);
+    const dims = {
+        landscape: { width: long, height: short },
+        portrait: { width: short, height: long },
+    };
+    const requestedOrientation = target.height > target.width ? "portrait" : "landscape";
+    const names = [];
+    for (const o of Array.isArray(outputs) && outputs.length > 0 ? outputs : [requestedOrientation]) {
+        if (!names.includes(o))
+            names.push(o);
+    }
+    return names.map((name) => ({ name, ...dims[name] }));
+}
+function pickTimingDefaults(bag) {
+    if (bag === undefined || bag === null || typeof bag !== "object")
+        return {};
+    const out = {};
+    for (const key of Object.keys(props_1.DEFAULT_STORY_DEFAULTS)) {
+        const v = bag[key];
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+            out[key] = v;
+    }
+    return out;
+}
+/**
+ * Per-section overrides accept any defaults key, but three of them are
+ * structurally document-level in the v1 timing model (one title card, one
+ * outro, one global X). Accepting-and-ignoring a typed knob is forbidden —
+ * name the inert key instead. (minImageDwellMs / imageFadeMs are consumed
+ * per-section by the Phase-4 image machinery, so they get no note here.)
+ */
+const DOCUMENT_LEVEL_OVERRIDE_KEYS = ["titleCardMs", "outroMs", "xfadeMs"];
+function noteDocumentLevelOverrides(section, i, diagnostics) {
+    const overrides = section.overrides;
+    if (overrides === null || typeof overrides !== "object")
+        return;
+    for (const key of DOCUMENT_LEVEL_OVERRIDE_KEYS) {
+        if (overrides[key] !== undefined) {
+            diagnostics.push(`STORY_OVERRIDE_DOCUMENT_LEVEL: sections[${i}].overrides.${key} is ignored — "${key}" is document-level in v1; set story.defaults.${key} instead.`);
+        }
+    }
+}
+function badDurationError(field, value) {
+    return `${field} resolves to ${value} ms — every scene needs at least 1 ms (zero-length scenes are not supported in v1).`;
+}
+function missingNarrationError(section, i) {
+    return [
+        `${sectionLabel(section, i)}: can't determine its length.`,
+        `  narrationAudio = ${JSON.stringify(section.narrationAudio)}`,
+        `  · not in ctx.media — this engine probes only TOP-LEVEL string/string[] props,`,
+        `    so a path nested inside sections[] is never probed`,
+        `  · and sections[${i}].overrides.durationMs is not set`,
+        `Fix any one of:`,
+        `  (a) run \`story-studio build <project>\` to regenerate props.json (emits mediaPaths)`,
+        `  (b) set sections[${i}].overrides.durationMs to the clip length in ms`,
+        `  (c) add the path to the top-level \`mediaPaths\` array`,
+    ].join("\n");
+}
+function sectionLabel(section, i) {
+    const name = typeof section.title === "string" && section.title.trim().length > 0 ? section.title : section.id;
+    return typeof name === "string" && name.length > 0 ? `Section ${i} ("${name}")` : `Section ${i}`;
+}
+function firstWords(text, count) {
+    if (typeof text !== "string" || text.trim().length === 0)
+        return undefined;
+    return text.trim().split(/\s+/).slice(0, count).join(" ");
+}