@m0saic/templates 0.2.0

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

@@ -0,0 +1,147 @@
+/**
+ * Props + story.json contract for @m0saic/story/narrated-chapters/v1.
+ *
+ * The template renders from a `story` manifest (the boundary artifact of the
+ * agentic-video pipeline — see the internal agenticvideo notes
+ * narrated-chapters.md`). The example orchestrator `examples/story-studio`
+ * owns authoring-time validation (typo suggestions, path absolutization);
+ * this file owns the RENDER-time contract: the CLI make path calls
+ * `render()` directly, so the schema below is documentation and the
+ * template must re-validate defensively.
+ *
+ * `provenance` is deliberately absent from everything below: it records how
+ * the assets were generated and the renderer must never read it (the
+ * determinism firewall).
+ */
+export declare const STORY_SCHEMA_VERSION = 1;
+/**
+ * The story renders as 2 + 2N pipeline steps and the engine drops every
+ * xfade past 80 concat inputs; 30 sections (62 steps) leaves headroom.
+ */
+export declare const MAX_SECTIONS = 30;
+export declare const STORY_OUTPUT_NAMES: readonly ["landscape", "portrait"];
+export type StoryOutputName = (typeof STORY_OUTPUT_NAMES)[number];
+export type StoryBrand = {
+    accentColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+};
+export type StoryTimingDefaults = {
+    titleCardMs?: number;
+    sectionCardMs?: number;
+    outroMs?: number;
+    xfadeMs?: number;
+    narrationTailPadMs?: number;
+    minSectionMs?: number;
+    minImageDwellMs?: number;
+    imageFadeMs?: number;
+};
+export declare const DEFAULT_STORY_DEFAULTS: Required<StoryTimingDefaults>;
+export type StorySectionOverrides = StoryTimingDefaults & {
+    /** Explicit narration length — outranks the probed audio duration. */
+    durationMs?: number;
+    imageWeights?: number[];
+    imageFocus?: Array<{
+        x: number;
+        y: number;
+    }>;
+    caption?: string;
+};
+/**
+ * One caption cue, times relative to the SECTION'S NARRATION START (which
+ * is step-local t=0 — cards cut INTO narration by design).
+ */
+export type StoryCue = {
+    startMs: number;
+    endMs: number;
+    text: string;
+};
+export type StorySection = {
+    id?: string;
+    title?: string;
+    narrationText?: string;
+    narrationAudio?: string;
+    /**
+     * SubRip path — AUTHORING-time input. Templates are pure (no fs):
+     * `story-studio build` parses it and inlines `cues`; a template seeing
+     * `srt` without `cues` emits a diagnostic, never reads the file.
+     */
+    srt?: string;
+    /** Caption cues (narration-relative). Win over synthesized sentence cues. */
+    cues?: StoryCue[];
+    images?: string[];
+    overrides?: StorySectionOverrides;
+};
+export type StoryAudio = {
+    narrationVolume?: number;
+    /** Music-bed volume (default 0.10 — amix sums with no limiter). */
+    musicVolume?: number;
+    /** Music-bed file, project-relative at authoring time (absolute in props.json). */
+    music?: string;
+    /** Offset into the music file where the story starts (default 0). */
+    musicStartMs?: number;
+};
+export type StoryDocument = {
+    schemaVersion?: number;
+    title?: string;
+    subtitle?: string;
+    brand?: StoryBrand;
+    defaults?: StoryTimingDefaults;
+    motion?: {
+        seed?: number;
+        ease?: string;
+        intensity?: number;
+    };
+    captions?: {
+        enabled?: boolean;
+        minCueMs?: number;
+        cueGapMs?: number;
+        plate?: string;
+    };
+    audio?: StoryAudio;
+    outputs?: StoryOutputName[];
+    sections?: StorySection[];
+    [key: string]: unknown;
+};
+export type NarratedChaptersProps = {
+    /**
+     * The story manifest. `type:"json"` is validator-permissive by design —
+     * the value may arrive as an object or a JSON string; render() parses and
+     * shape-checks it. Omit for the built-in demo story.
+     */
+    story?: StoryDocument | string;
+    /**
+     * Flat probe mirror of every asset path inside `story` — the engine only
+     * probes TOP-LEVEL string/string[] props, so nested paths need this
+     * machine-generated twin (emitted by `story-studio build`, byte-identical
+     * to the in-story strings; never hand-authored).
+     */
+    mediaPaths?: string[];
+    /** Informational; shortens paths in error frames. */
+    projectDir?: string;
+};
+export declare const narratedChaptersPropsSchema: Record<keyof NarratedChaptersProps, import("@m0saic/types").MosaicTemplatePropDefinition>;
+/**
+ * Parse the `story` prop into a StoryDocument. `type:"json"` props can
+ * legally arrive as objects or JSON strings; anything else is an error.
+ * `undefined`/`null` means "no story given" (demo mode) and is NOT an error.
+ */
+export declare function coerceStoryProp(raw: unknown): {
+    story: StoryDocument | null;
+    errors: string[];
+};
+/**
+ * Render-time structural gate (fail fast → error frame). Deliberately
+ * narrower than story-studio's authoring validator: only what the renderer
+ * needs to proceed safely. Collects every problem, not just the first.
+ */
+export declare function validateStoryShape(story: StoryDocument): string[];
+/**
+ * Recognize a bare story document passed AS the props bag. `--props
+ * @story.json` hands the CLI the manifest itself, so `props.story` is
+ * undefined — without this sniff the render silently fell back to the demo
+ * (the worst outcome: a wrong video with zero diagnostics). A bag with a
+ * `sections` array and no `story` key IS the story; validateStoryShape
+ * still gates it fully afterwards.
+ */
+export declare function sniffBareStory(props: unknown): StoryDocument | null;

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

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Props + story.json contract for @m0saic/story/narrated-chapters/v1.
+ *
+ * The template renders from a `story` manifest (the boundary artifact of the
+ * agentic-video pipeline — see the internal agenticvideo notes
+ * narrated-chapters.md`). The example orchestrator `examples/story-studio`
+ * owns authoring-time validation (typo suggestions, path absolutization);
+ * this file owns the RENDER-time contract: the CLI make path calls
+ * `render()` directly, so the schema below is documentation and the
+ * template must re-validate defensively.
+ *
+ * `provenance` is deliberately absent from everything below: it records how
+ * the assets were generated and the renderer must never read it (the
+ * determinism firewall).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.narratedChaptersPropsSchema = exports.DEFAULT_STORY_DEFAULTS = exports.STORY_OUTPUT_NAMES = exports.MAX_SECTIONS = exports.STORY_SCHEMA_VERSION = void 0;
+exports.coerceStoryProp = coerceStoryProp;
+exports.validateStoryShape = validateStoryShape;
+exports.sniffBareStory = sniffBareStory;
+const template_utils_1 = require("@m0saic/template-utils");
+exports.STORY_SCHEMA_VERSION = 1;
+/**
+ * The story renders as 2 + 2N pipeline steps and the engine drops every
+ * xfade past 80 concat inputs; 30 sections (62 steps) leaves headroom.
+ */
+exports.MAX_SECTIONS = 30;
+exports.STORY_OUTPUT_NAMES = ["landscape", "portrait"];
+exports.DEFAULT_STORY_DEFAULTS = {
+    titleCardMs: 3500,
+    sectionCardMs: 2000,
+    outroMs: 3000,
+    xfadeMs: 600,
+    narrationTailPadMs: 700,
+    minSectionMs: 1500,
+    minImageDwellMs: 2200,
+    imageFadeMs: 500,
+};
+exports.narratedChaptersPropsSchema = (0, template_utils_1.definePropsSchema)({
+    story: {
+        type: "json",
+        required: false,
+        description: "story.json manifest — { title, sections: [{ narrationText, narrationAudio?, images?, overrides? }], defaults?, brand?, outputs? }. Omit for the built-in demo story.",
+        meta: { ui: { label: "Story manifest", order: 1 } },
+    },
+    mediaPaths: {
+        type: "media[]",
+        required: false,
+        description: "Machine-generated flat mirror of every asset path in the story (run `story-studio build`); needed so narration durations are probed before render.",
+        meta: { ui: { label: "Media paths", order: 2 } },
+    },
+    projectDir: {
+        type: "string",
+        required: false,
+        description: "Story project folder (informational; used to shorten paths in diagnostics).",
+        meta: { control: { placeholder: "none (full paths in diagnostics)" }, ui: { label: "Project folder", order: 3 } },
+    },
+});
+/**
+ * Parse the `story` prop into a StoryDocument. `type:"json"` props can
+ * legally arrive as objects or JSON strings; anything else is an error.
+ * `undefined`/`null` means "no story given" (demo mode) and is NOT an error.
+ */
+function coerceStoryProp(raw) {
+    if (raw === undefined || raw === null)
+        return { story: null, errors: [] };
+    let value = raw;
+    if (typeof raw === "string") {
+        if (raw.trim().length === 0)
+            return { story: null, errors: [] };
+        try {
+            value = JSON.parse(raw);
+        }
+        catch (e) {
+            return {
+                story: null,
+                errors: [`props.story is a string but not valid JSON — ${e.message}`],
+            };
+        }
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { story: null, errors: [`props.story must be a story object, got ${describe(value)}`] };
+    }
+    return { story: value, errors: [] };
+}
+/**
+ * Render-time structural gate (fail fast → error frame). Deliberately
+ * narrower than story-studio's authoring validator: only what the renderer
+ * needs to proceed safely. Collects every problem, not just the first.
+ */
+function validateStoryShape(story) {
+    const errors = [];
+    if (story.schemaVersion !== undefined && story.schemaVersion !== exports.STORY_SCHEMA_VERSION) {
+        errors.push(`story.schemaVersion ${String(story.schemaVersion)} is unsupported (this template understands ${exports.STORY_SCHEMA_VERSION}).`);
+    }
+    const sections = story.sections;
+    if (!Array.isArray(sections) || sections.length === 0) {
+        errors.push(`story.sections must be a non-empty array of section objects.`);
+    }
+    else {
+        if (sections.length > exports.MAX_SECTIONS) {
+            errors.push(`story.sections has ${sections.length} entries; the maximum is ${exports.MAX_SECTIONS} (the pipeline concat wall sits at 80 steps).`);
+        }
+        sections.forEach((section, i) => {
+            if (typeof section !== "object" || section === null || Array.isArray(section)) {
+                errors.push(`story.sections[${i}] must be an object, got ${describe(section)}.`);
+                return;
+            }
+            // Blank/non-string image entries would silently shift imageFocus and
+            // imageWeights indices after filtering — reject them instead.
+            if (section.images !== undefined) {
+                if (!Array.isArray(section.images)) {
+                    errors.push(`story.sections[${i}].images must be an array of path strings.`);
+                }
+                else {
+                    section.images.forEach((img, k) => {
+                        if (typeof img !== "string" || img.trim().length === 0) {
+                            errors.push(`story.sections[${i}].images[${k}] must be a non-empty path string, got ${describe(img)}.`);
+                        }
+                    });
+                }
+            }
+            validateCueShape(section.cues, i, errors);
+        });
+    }
+    if (story.audio !== undefined && story.audio !== null && typeof story.audio === "object") {
+        if (story.audio.music !== undefined && (typeof story.audio.music !== "string" || story.audio.music.trim().length === 0)) {
+            errors.push(`story.audio.music must be a non-empty path string.`);
+        }
+        if (story.audio.musicStartMs !== undefined &&
+            !(typeof story.audio.musicStartMs === "number" && Number.isFinite(story.audio.musicStartMs) && story.audio.musicStartMs >= 0)) {
+            errors.push(`story.audio.musicStartMs must be a number of milliseconds ≥ 0.`);
+        }
+    }
+    if (story.outputs !== undefined) {
+        if (!Array.isArray(story.outputs)) {
+            errors.push(`story.outputs must be an array; valid values: ${exports.STORY_OUTPUT_NAMES.join(", ")}.`);
+        }
+        else {
+            story.outputs.forEach((o, i) => {
+                if (!exports.STORY_OUTPUT_NAMES.includes(o)) {
+                    errors.push(`story.outputs[${i}] is ${JSON.stringify(o)}; valid values: ${exports.STORY_OUTPUT_NAMES.map((n) => `"${n}"`).join(", ")}.`);
+                }
+            });
+        }
+    }
+    return errors;
+}
+/**
+ * Recognize a bare story document passed AS the props bag. `--props
+ * @story.json` hands the CLI the manifest itself, so `props.story` is
+ * undefined — without this sniff the render silently fell back to the demo
+ * (the worst outcome: a wrong video with zero diagnostics). A bag with a
+ * `sections` array and no `story` key IS the story; validateStoryShape
+ * still gates it fully afterwards.
+ */
+function sniffBareStory(props) {
+    if (typeof props !== "object" || props === null || Array.isArray(props))
+        return null;
+    const bag = props;
+    if (bag.story !== undefined)
+        return null;
+    if (!Array.isArray(bag.sections))
+        return null;
+    return bag;
+}
+/** Same monotonic non-overlap rule the orchestrator enforces — defensive twin. */
+function validateCueShape(cues, sectionIndex, errors) {
+    if (cues === undefined)
+        return;
+    if (!Array.isArray(cues)) {
+        errors.push(`story.sections[${sectionIndex}].cues must be an array of { startMs, endMs, text }.`);
+        return;
+    }
+    let prevEnd = -1;
+    cues.forEach((cue, k) => {
+        const c = cue;
+        const ok = typeof cue === "object" &&
+            cue !== null &&
+            typeof c.startMs === "number" &&
+            Number.isFinite(c.startMs) &&
+            c.startMs >= 0 &&
+            typeof c.endMs === "number" &&
+            Number.isFinite(c.endMs) &&
+            c.endMs > c.startMs &&
+            typeof c.text === "string" &&
+            c.text.trim().length > 0;
+        if (!ok) {
+            errors.push(`story.sections[${sectionIndex}].cues[${k}] must be { startMs ≥ 0, endMs > startMs, text } (narration-relative ms).`);
+            return;
+        }
+        if (c.startMs < prevEnd) {
+            errors.push(`story.sections[${sectionIndex}].cues[${k}] starts before the previous cue ends — cues must be ordered and non-overlapping.`);
+        }
+        prevEnd = c.endMs;
+    });
+}
+function describe(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "an array";
+    return `a ${typeof v}`;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Body scenes — the section's images with restrained Ken Burns drift,
+ * windowed cross-dissolves, burned captions, and the audio bed.
+ *
+ * Z-order comes from the m0's nested overlay structure (image k is the
+ * overlay of k−1 and paints above it), never from source-array position.
+ * Each image only ever FADES IN — its predecessor sits opaque underneath,
+ * so one canonical alpha ramp is a true dissolve with no luminance dip
+ * (R4: alpha + typed window, both). Every covered image's window closes
+ * shortly after its successor is fully opaque, keeping the tail composite
+ * at 2 layers instead of M.
+ *
+ * Captions are DRAWTEXT by necessity (`buildSvgTextSource` merges every
+ * layer and drops per-layer `enable` — an svg caption source would show
+ * all cues at once, forever): ONE text source per section (R5), one layer
+ * per cue, each enable-gated `between(t, start, end)`, renderMode
+ * {kind:"video"} so the gates evaluate per frame. Cue times are
+ * narration-relative == step-local (cards cut INTO narration, so the
+ * body's t=0 is the narration's first sample).
+ *
+ * Narration is a `mediaType:"audio"` source on the top overlay leaf —
+ * mandatory even for real audio files (an MP3 with ID3 cover art probes
+ * hasVideo:true; the declaration keeps it out of the video composite while
+ * still contributing its audio). It starts at t=0 and the step's last
+ * xfadeOut ≤ tailPad milliseconds are pad silence, which is what makes a
+ * body step legal as the A side of a crossfade. The music bed is
+ * replicated per step with `playback.clipStartMs = musicStartMs +
+ * scene.startMs` (there is no pipeline-spanning audio track, no ducking,
+ * no afade — engine gaps by design, documented not faked).
+ */
+import type { MosaicDocument, MosaicSource } from "@m0saic/types";
+import type { StoryPlan, StoryScene, StoryVariant } from "../plan";
+import type { StorySectionOverrides } from "../props";
+import type { StoryTheme } from "../theme";
+/** One resolved, probe-verified image for a section. */
+export type ResolvedImage = {
+    /** Raw path string as it appears in the story (the ctx.media key). */
+    path: string;
+    /** Deterministic manifest key (positional — collision-free by construction). */
+    assetKey: string;
+};
+export type SectionMedia = {
+    images: ResolvedImage[];
+    /** Per-image subject anchors from overrides.imageFocus (0..1 fractions). */
+    focus: Array<{
+        x: number;
+        y: number;
+    } | undefined>;
+    /** Narration clip (raw path + manifest key) when the section declares one. */
+    narration?: ResolvedImage;
+};
+/** The music bed, shared by every scene (undefined = no music). */
+export type MusicBed = {
+    path: string;
+    assetKey: string;
+};
+export declare function buildBodyDoc(scene: StoryScene, media: SectionMedia | undefined, variant: StoryVariant, plan: StoryPlan, theme: StoryTheme, music?: MusicBed): MosaicDocument;
+/** The music-bed source for ANY scene: same file, per-step clip offset. */
+export declare function musicSource(music: MusicBed, scene: StoryScene, plan: StoryPlan, label: string): MosaicSource;
+/** Per-image subject anchors from a section's overrides, length-tolerant. */
+export declare function focusFromOverrides(overrides: StorySectionOverrides | undefined, imageCount: number): Array<{
+    x: number;
+    y: number;
+} | undefined>;

package/dist/m0saic/story/narrated-chapters/v1/scenes/body.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Body scenes — the section's images with restrained Ken Burns drift,
+ * windowed cross-dissolves, burned captions, and the audio bed.
+ *
+ * Z-order comes from the m0's nested overlay structure (image k is the
+ * overlay of k−1 and paints above it), never from source-array position.
+ * Each image only ever FADES IN — its predecessor sits opaque underneath,
+ * so one canonical alpha ramp is a true dissolve with no luminance dip
+ * (R4: alpha + typed window, both). Every covered image's window closes
+ * shortly after its successor is fully opaque, keeping the tail composite
+ * at 2 layers instead of M.
+ *
+ * Captions are DRAWTEXT by necessity (`buildSvgTextSource` merges every
+ * layer and drops per-layer `enable` — an svg caption source would show
+ * all cues at once, forever): ONE text source per section (R5), one layer
+ * per cue, each enable-gated `between(t, start, end)`, renderMode
+ * {kind:"video"} so the gates evaluate per frame. Cue times are
+ * narration-relative == step-local (cards cut INTO narration, so the
+ * body's t=0 is the narration's first sample).
+ *
+ * Narration is a `mediaType:"audio"` source on the top overlay leaf —
+ * mandatory even for real audio files (an MP3 with ID3 cover art probes
+ * hasVideo:true; the declaration keeps it out of the video composite while
+ * still contributing its audio). It starts at t=0 and the step's last
+ * xfadeOut ≤ tailPad milliseconds are pad silence, which is what makes a
+ * body step legal as the A side of a crossfade. The music bed is
+ * replicated per step with `playback.clipStartMs = musicStartMs +
+ * scene.startMs` (there is no pipeline-spanning audio track, no ducking,
+ * no afade — engine gaps by design, documented not faked).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBodyDoc = buildBodyDoc;
+exports.musicSource = musicSource;
+exports.focusFromOverrides = focusFromOverrides;
+const template_utils_1 = require("@m0saic/template-utils");
+const layout_1 = require("../layout");
+const kenburns_1 = require("../kenburns");
+const card_1 = require("./card");
+/** How long after a successor is fully opaque the covered image stays live. */
+const WINDOW_SLACK_SEC = 0.25;
+/** Drawtext is shaped by fontconfig while we measure bundled Roboto — leave margin. */
+const CAPTION_SAFE_W = 0.9;
+const CAPTION_MIN_FONT = 14;
+function buildBodyDoc(scene, media, variant, plan, theme, music) {
+    var _a, _b, _c;
+    if (scene.kind !== "body") {
+        throw new Error(`buildBodyDoc: got a ${scene.kind} scene ("${scene.name}")`);
+    }
+    const durationMs = scene.visibleMs + scene.xfadeOutMs;
+    const aspect = (0, layout_1.classifyAspect)(variant.width, variant.height);
+    const spec = layout_1.ASPECT_TABLE[aspect];
+    const schedule = (_a = scene.images) !== null && _a !== void 0 ? _a : [];
+    const hasImages = media !== undefined && media.images.length > 0 && schedule.length > 0;
+    const cues = (_b = scene.cues) !== null && _b !== void 0 ? _b : [];
+    const captionsOn = cues.length > 0;
+    const narration = media === null || media === void 0 ? void 0 : media.narration;
+    const assets = {};
+    const sources = [];
+    // -- visual stack: images or the media-free panel -------------------------
+    if (hasImages) {
+        const fadeSec = Math.max(0.05, ((_c = scene.imageFadeMs) !== null && _c !== void 0 ? _c : 500) / 1000);
+        schedule.forEach((slot, k) => {
+            var _a, _b, _c;
+            const image = media.images[slot.imageIndex];
+            if (image === undefined) {
+                throw new Error(`buildBodyDoc: ${scene.name} schedules images[${slot.imageIndex}] but only ${media.images.length} resolved`);
+            }
+            assets[image.assetKey] = {
+                kind: "file",
+                path: image.path,
+                mediaType: "image",
+            };
+            const subject = media.focus[slot.imageIndex];
+            const startSec = slot.startMs / 1000;
+            const next = schedule[k + 1];
+            const camera = (0, kenburns_1.kenBurnsCamera)({
+                seed: plan.motion.seed,
+                sectionIndex: (_a = scene.sectionIndex) !== null && _a !== void 0 ? _a : 0,
+                imageIndex: slot.imageIndex,
+                startSec,
+                endSec: (slot.startMs + slot.durationMs) / 1000,
+                intensity: plan.motion.intensity,
+                ease: plan.motion.ease,
+                ampScale: spec.cameraAmpScale,
+                ...(subject !== undefined ? { subjectX: subject.x, subjectY: subject.y } : {}),
+            });
+            const window = {
+                ...(k > 0 ? { startSec } : {}),
+                ...(next !== undefined ? { endSec: next.startMs / 1000 + fadeSec + WINDOW_SLACK_SEC } : {}),
+            };
+            sources.push({
+                type: "media",
+                mediaType: "image",
+                assetId: image.assetKey,
+                placement: {
+                    fit: "cover",
+                    focusX: (_b = subject === null || subject === void 0 ? void 0 : subject.x) !== null && _b !== void 0 ? _b : 0.5,
+                    focusY: (_c = subject === null || subject === void 0 ? void 0 : subject.y) !== null && _c !== void 0 ? _c : spec.coverFocusY,
+                },
+                ...(camera !== undefined ? { effects: { camera } } : {}),
+                overlay: {
+                    ...(k > 0 ? { alpha: (0, template_utils_1.fadeInExpr)(startSec, fadeSec, "linear") } : {}),
+                    ...(Object.keys(window).length > 0 ? { window } : {}),
+                },
+                editor: { owner: "template", label: `${scene.name}/img${slot.imageIndex}` },
+            });
+        });
+    }
+    else {
+        const S = Math.min(variant.width, variant.height);
+        sources.push((0, template_utils_1.makeColorTile)(theme.card), (0, card_1.textCell)(scene.heading, {
+            maxFont: Math.round(S * spec.headingScale * 0.7),
+            maxW: Math.floor(variant.width * spec.cardSafeW),
+            bandH: Math.floor(variant.height * 0.3),
+            color: theme.muted,
+            label: `${scene.name}/panel-heading`,
+        }));
+    }
+    // -- captions: plate + gated drawtext ------------------------------------
+    if (captionsOn) {
+        sources.push(...buildCaptionSources(scene, cues, variant, aspect, spec, plan, theme));
+    }
+    // -- audio leaves: narration, then music ----------------------------------
+    if (narration !== undefined) {
+        assets[narration.assetKey] = {
+            kind: "file",
+            path: narration.path,
+            mediaType: "audio",
+        };
+        sources.push({
+            type: "media",
+            mediaType: "audio",
+            assetId: narration.assetKey,
+            audio: { enabled: true, volume: plan.audio.narrationVolume },
+            editor: { owner: "template", label: `${scene.name}/narration` },
+        });
+    }
+    if (music !== undefined) {
+        assets[music.assetKey] = {
+            kind: "file",
+            path: music.path,
+            mediaType: "audio",
+        };
+        sources.push(musicSource(music, scene, plan, `${scene.name}/music`));
+    }
+    const stackFrames = hasImages ? schedule.length : 2;
+    const audioCount = (narration !== undefined ? 1 : 0) + (music !== undefined ? 1 : 0);
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, layout_1.buildBodyM0)({ aspect, stackFrames, captions: captionsOn, audioCount }),
+        assets,
+        sources,
+        size: { width: variant.width, height: variant.height },
+        fps: plan.fps,
+        durationMs,
+        backgroundColor: theme.canvas,
+        editor: { label: `${variant.name}/${scene.name}` },
+    };
+}
+/** The music-bed source for ANY scene: same file, per-step clip offset. */
+function musicSource(music, scene, plan, label) {
+    return {
+        type: "media",
+        mediaType: "audio",
+        assetId: music.assetKey,
+        audio: { enabled: true, volume: plan.audio.musicVolume },
+        playback: { clipStartMs: plan.audio.musicStartMs + scene.startMs },
+        editor: { owner: "template", label },
+    };
+}
+/**
+ * Caption frames for the band carved by buildBodyM0. Portrait: [plate,
+ * text]. Landscape/square get an extra leading TRANSPARENT tile claiming
+ * the split's top band so the images show through: [topSpacer, plate,
+ * text]. The plate fills its real band cell (small insets only — the
+ * engine caps inset at 0.49/side, which is why the band is carved, not
+ * painted).
+ */
+function buildCaptionSources(scene, cues, variant, aspect, spec, plan, theme) {
+    const S = Math.min(variant.width, variant.height);
+    const isBand = aspect === "portrait";
+    const plateColor = "#000000@0.55";
+    const plate = plan.captions.plate === "never"
+        ? (0, template_utils_1.makeColorTile)("black@0")
+        : (0, template_utils_1.makeColorTile)(plateColor, {
+            placement: { inset: { top: 0.05, left: 0.05, right: 0.05, bottom: 0.12 } },
+        });
+    // Fit once per section against every cue (no per-cue jitter): shrink the
+    // font until each cue wraps within the line budget. The wrap ALWAYS runs
+    // at least once — a tiny canvas whose cap starts below the floor must
+    // still produce layers, never an empty wrapped list.
+    const boxW = Math.floor(variant.width * 0.85 * CAPTION_SAFE_W);
+    let fontSize = Math.max(CAPTION_MIN_FONT, Math.round(S * spec.captionScale));
+    let wrapped = cues.map((cue) => wrapCue(cue.text, fontSize, boxW));
+    while (!wrapped.every((lines) => lines.length <= spec.captionLines) && fontSize > CAPTION_MIN_FONT) {
+        fontSize = Math.max(CAPTION_MIN_FONT, Math.floor(fontSize * 0.9));
+        wrapped = cues.map((cue) => wrapCue(cue.text, fontSize, boxW));
+    }
+    const text = {
+        type: "text",
+        renderMode: { kind: "video" }, // per-layer enable gates evaluate per FRAME
+        layers: cues.map((cue, i) => ({
+            content: { kind: "literal", text: wrapped[i].join("\n") },
+            style: { fontSize, fontColor: theme.ink },
+            placement: { hAlign: "center", vAlign: "middle", padding: { x: 0.07, y: 0.1 } },
+            overlay: { enable: `between(t,${(cue.startMs / 1000).toFixed(3)},${(cue.endMs / 1000).toFixed(3)})` },
+        })),
+        editor: { owner: "template", label: `${scene.name}/captions` },
+    };
+    return isBand ? [plate, text] : [(0, template_utils_1.makeColorTile)("black@0"), plate, text];
+}
+/** Greedy word-wrap against real metrics; oversized words stay whole (drawtext clips). */
+function wrapCue(text, fontSize, maxW) {
+    const width = (s) => (0, template_utils_1.measureText)(s, { fontSize }).width;
+    const out = [];
+    let current = "";
+    for (const word of text.replace(/\n/g, " ").split(/\s+/).filter((w) => w.length > 0)) {
+        const joined = current.length > 0 ? `${current} ${word}` : word;
+        if (width(joined) <= maxW || current.length === 0) {
+            current = joined;
+        }
+        else {
+            out.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0)
+        out.push(current);
+    return out.length > 0 ? out : [text];
+}
+/** Per-image subject anchors from a section's overrides, length-tolerant. */
+function focusFromOverrides(overrides, imageCount) {
+    const raw = overrides === null || overrides === void 0 ? void 0 : overrides.imageFocus;
+    const out = new Array(imageCount).fill(undefined);
+    if (!Array.isArray(raw))
+        return out;
+    for (let i = 0; i < imageCount && i < raw.length; i++) {
+        const f = raw[i];
+        if (typeof f === "object" &&
+            f !== null &&
+            typeof f.x === "number" &&
+            f.x >= 0 &&
+            f.x <= 1 &&
+            typeof f.y === "number" &&
+            f.y >= 0 &&
+            f.y <= 1) {
+            out[i] = { x: f.x, y: f.y };
+        }
+    }
+    return out;
+}