@m0saic/templates 0.2.0

package/dist/m0saic/story/narrated-chapters/v1/demo-fixture.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Media-free built-in demo story — rendered on null/absent props so the
+ * template previews with zero setup (Templates page, null-props E2E case,
+ * `m0saic make` with no --props).
+ *
+ * Every section pins its length via `overrides.durationMs`, so no audio is
+ * probed. The values are deliberately unequal and non-round (they mirror the
+ * committed demo project's minted narration clips) — a timing model that
+ * divides time evenly instead of reading per-section durations fails
+ * visibly against this fixture.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEMO_STORY = void 0;
+exports.DEMO_STORY = {
+    schemaVersion: 1,
+    title: "Every Level of a City Block",
+    subtitle: "From the sidewalk to the skyline",
+    brand: {
+        accentColor: "#2f6df6",
+        backgroundColor: "#0d0f12",
+        textColor: "#f4f6f8",
+    },
+    // No `outputs` on purpose: the demo adopts the requested canvas
+    // orientation, so `-w 1080 -h 1920` previews portrait out of the box.
+    sections: [
+        {
+            id: "sidewalk",
+            title: "Street Level",
+            narrationText: "Start at the pavement. Everything a block does for a person happens in the first three metres.",
+            overrides: { durationMs: 2640 },
+        },
+        {
+            id: "storefront",
+            title: "The Storefront",
+            narrationText: "One step up, the block starts selling. Glass, signage, and a doorway that decides who comes in.",
+            overrides: { durationMs: 4120 },
+        },
+        {
+            id: "upper-floors",
+            title: "The Upper Floors",
+            narrationText: "Above the shopfront the block goes quiet: offices, apartments, and the windows nobody looks up at.",
+            overrides: { durationMs: 3360 },
+        },
+        {
+            id: "skyline",
+            title: "The Skyline",
+            narrationText: "At the top the block stops being architecture and becomes silhouette — the shape the city remembers.",
+            overrides: { durationMs: 5080 },
+        },
+    ],
+};

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

@@ -0,0 +1,2 @@
+export { NarratedChapters } from "./narrated-chapters";
+export type { NarratedChaptersProps } from "./narrated-chapters";

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

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NarratedChapters = void 0;
+var narrated_chapters_1 = require("./narrated-chapters");
+Object.defineProperty(exports, "NarratedChapters", { enumerable: true, get: function () { return narrated_chapters_1.NarratedChapters; } });

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

@@ -0,0 +1,50 @@
+/**
+ * Ken Burns — constant NUMERIC zoom, animated focus (perf rule R10:
+ * `applyCamera` emits a static `eval=init` scale for a number zoom and a
+ * per-frame `eval=frame` scale for a string zoom; never animate zoom).
+ *
+ * All variation flows from `hash32` (FNV-1a) over (salt, seed, section,
+ * image) — §9: no `Math.random`, identical seeds → identical cameras,
+ * byte-identical output. ~20% of shots are locked-off stills (no camera at
+ * all — the all-numeric zoom≤1 path is a plain `copy`).
+ *
+ * `keyframeExpr` holds the first value before t0, so the image is already
+ * framed during its fade-in — no jump. Ease defaults to linear (a drift
+ * wants constant velocity; smoothstep reads as stalling at both ends) and
+ * follows `story.motion.ease` when the manifest overrides it.
+ */
+import type { MotionEase } from "./plan";
+export type StoryCamera = {
+    zoom: number;
+    focusX: number | string;
+    focusY: number | string;
+};
+/** ~1.08–1.18× — the genre look; anything larger reads as a crash zoom. */
+export declare const ZOOMS: readonly [1.08, 1.1, 1.12, 1.15, 1.18];
+/** Drift directions (dx, dy) in focus space; 0 = no travel on that axis. */
+export declare const MOVES: ReadonlyArray<readonly [number, number]>;
+/** FNV-1a over the joined parts — deterministic across runtimes. */
+export declare function hash32(...parts: Array<string | number>): number;
+export type KenBurnsOptions = {
+    seed: number;
+    sectionIndex: number;
+    imageIndex: number;
+    /** Image's visible window on the scene-local clock, seconds. */
+    startSec: number;
+    endSec: number;
+    /** story.motion.intensity (default 1). */
+    intensity: number;
+    /** story.motion.ease (default "linear" — constant-velocity drift). */
+    ease?: MotionEase;
+    /** Aspect-table multiplier (portrait 0.75 — full amplitude reads as shake). */
+    ampScale: number;
+    /** Cover-crop anchor the drift orbits (defaults to center). */
+    subjectX?: number;
+    subjectY?: number;
+};
+/**
+ * The camera for one image, or undefined for a locked-off still.
+ * Zoom is always a NUMBER; focus axes are keyframed strings only when they
+ * actually travel.
+ */
+export declare function kenBurnsCamera(opts: KenBurnsOptions): StoryCamera | undefined;

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

@@ -0,0 +1,103 @@
+/**
+ * Aspect table + m0 assembly. ONE table keyed by aspect class — builders
+ * read it, they never branch on dimensions (the plan's aspect-adaptivity
+ * rule). Type scales off the short edge S = min(W, H).
+ *
+ * The body m0 is a nested image stack (`F{F{F}}` — nest, never chain:
+ * `F{F}{F}` is an illegal overlay chain). Overlay nesting IS the z-order:
+ * image k is the overlay of image k−1 and paints above it, which is what
+ * makes a single fade-in a true dissolve.
+ */
+import type { M0String } from "@m0saic/dsl";
+export type AspectClass = "landscape" | "portrait" | "square";
+/** Plan-mandated thresholds: landscape ar ≥ 1.2, portrait ar ≤ 0.85. */
+export declare function classifyAspect(width: number, height: number): AspectClass;
+export type AspectSpec = {
+    /** Ken Burns focus-travel multiplier — full amplitude reads as shake in a tight portrait crop. */
+    cameraAmpScale: number;
+    /** Default cover-crop vertical anchor (heads sit high in portrait shots). */
+    coverFocusY: number;
+    /** Headline font cap as a fraction of the short edge. */
+    headingScale: number;
+    /** Subtitle / kicker font cap as a fraction of the short edge. */
+    subScale: number;
+    /** Horizontal text-safe fraction of the canvas width on cards. */
+    cardSafeW: number;
+    /** Caption font cap as a fraction of the short edge. */
+    captionScale: number;
+    /** Max wrapped lines per cue. */
+    captionLines: number;
+    /**
+     * Caption band height as a fraction of H — a LIVE weight in every
+     * aspect's band split (buildBodyM0): portrait carves its bottom band
+     * directly; landscape/square carve a lower-third band whose top band is
+     * claimed by a transparent tile so the images show through. (Painting a
+     * strip via inset is illegal — the engine caps placement.inset at
+     * 0.49/side.)
+     */
+    captionBandFrac: number;
+};
+export declare const ASPECT_TABLE: Record<AspectClass, AspectSpec>;
+/**
+ * Card scenes carve REAL vertical bands (Rect Thesis — no drawtext
+ * positioning, no full-frame hacks). Weights are integer fractions of the
+ * height; every band is claimed (a "0" claimant would donate its space
+ * forward and inflate the next band).
+ */
+export type CardBand = {
+    kind: "spacer";
+    weight: number;
+} | {
+    kind: "kicker";
+    weight: number;
+} | {
+    kind: "heading";
+    weight: number;
+} | {
+    kind: "bar";
+    weight: number;
+} | {
+    kind: "sub";
+    weight: number;
+};
+export declare const CARD_BANDS: Record<"title" | "section-card" | "outro", CardBand[]>;
+/**
+ * Vertically stacked bands claiming every cell — exactly bands.length
+ * frames, plus an optional audio overlay leaf (the music bed rides every
+ * step). Axis "row" = horizontal rows stacked top-to-bottom (the m0
+ * `N[...]` form); "col" would lay the bands out side-by-side.
+ */
+export declare function buildCardM0(bands: CardBand[], audioCount?: number): M0String;
+export type BodyM0Options = {
+    aspect: AspectClass;
+    /** Frames in the visual base: image count, or 2 for the panel fallback. */
+    stackFrames: number;
+    /** Append plate + text caption frames. */
+    captions: boolean;
+    /** Trailing audio leaves (narration and/or music). */
+    audioCount: number;
+};
+/**
+ * The full body m0. Frame order is ALWAYS [stack…, captions?, audio…] —
+ * only the caption carve differs per aspect:
+ *
+ * - portrait: a real [12,56,32] band split — images in the top band,
+ *   plate+text in the bottom band, audio as the root overlay. Caption
+ *   frames: plate, text.
+ * - landscape/square: the innermost image's overlay carves a REAL
+ *   lower-third band split — the top band claimed by a transparent tile so
+ *   the images show through, the bottom band = plate{text}. Caption
+ *   frames: topSpacer, plate, text. (An inset-painted strip is illegal —
+ *   the engine caps placement.inset at 0.49 per side.)
+ */
+export declare function buildBodyM0(opts: BodyM0Options): M0String;
+/**
+ * Body scene: a nested full-canvas image stack, one frame per image.
+ * count 1 → "F"; count 3 → "F{F{F}}". Never chained.
+ */
+export declare function buildImageStackM0(count: number): M0String;
+/**
+ * Media-free body fallback (the built-in demo): a full-canvas panel with a
+ * centered heading block — panel base + heading overlay.
+ */
+export declare function buildPanelBodyM0(): M0String;

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

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Aspect table + m0 assembly. ONE table keyed by aspect class — builders
+ * read it, they never branch on dimensions (the plan's aspect-adaptivity
+ * rule). Type scales off the short edge S = min(W, H).
+ *
+ * The body m0 is a nested image stack (`F{F{F}}` — nest, never chain:
+ * `F{F}{F}` is an illegal overlay chain). Overlay nesting IS the z-order:
+ * image k is the overlay of image k−1 and paints above it, which is what
+ * makes a single fade-in a true dissolve.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CARD_BANDS = exports.ASPECT_TABLE = void 0;
+exports.classifyAspect = classifyAspect;
+exports.buildCardM0 = buildCardM0;
+exports.buildBodyM0 = buildBodyM0;
+exports.buildImageStackM0 = buildImageStackM0;
+exports.buildPanelBodyM0 = buildPanelBodyM0;
+const dsl_1 = require("@m0saic/dsl");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+/** Plan-mandated thresholds: landscape ar ≥ 1.2, portrait ar ≤ 0.85. */
+function classifyAspect(width, height) {
+    const ar = width / height;
+    if (ar >= 1.2)
+        return "landscape";
+    if (ar <= 0.85)
+        return "portrait";
+    return "square";
+}
+exports.ASPECT_TABLE = {
+    landscape: {
+        cameraAmpScale: 1.0, coverFocusY: 0.5, headingScale: 0.085, subScale: 0.036, cardSafeW: 0.72,
+        captionScale: 0.042, captionLines: 2, captionBandFrac: 0.22,
+    },
+    portrait: {
+        cameraAmpScale: 0.75, coverFocusY: 0.42, headingScale: 0.08, subScale: 0.036, cardSafeW: 0.84,
+        captionScale: 0.044, captionLines: 3, captionBandFrac: 0.32,
+    },
+    square: {
+        cameraAmpScale: 0.85, coverFocusY: 0.46, headingScale: 0.08, subScale: 0.036, cardSafeW: 0.8,
+        captionScale: 0.042, captionLines: 2, captionBandFrac: 0.24,
+    },
+};
+exports.CARD_BANDS = {
+    title: [
+        { kind: "spacer", weight: 30 },
+        { kind: "heading", weight: 14 },
+        { kind: "spacer", weight: 3 },
+        { kind: "bar", weight: 2 },
+        { kind: "spacer", weight: 5 },
+        { kind: "sub", weight: 8 },
+        { kind: "spacer", weight: 38 },
+    ],
+    "section-card": [
+        { kind: "spacer", weight: 32 },
+        { kind: "kicker", weight: 6 },
+        { kind: "spacer", weight: 2 },
+        { kind: "heading", weight: 12 },
+        { kind: "spacer", weight: 4 },
+        { kind: "bar", weight: 2 },
+        { kind: "spacer", weight: 42 },
+    ],
+    outro: [
+        { kind: "spacer", weight: 36 },
+        { kind: "heading", weight: 11 },
+        { kind: "spacer", weight: 3 },
+        { kind: "bar", weight: 2 },
+        { kind: "spacer", weight: 6 },
+        { kind: "sub", weight: 7 },
+        { kind: "spacer", weight: 35 },
+    ],
+};
+/**
+ * Vertically stacked bands claiming every cell — exactly bands.length
+ * frames, plus an optional audio overlay leaf (the music bed rides every
+ * step). Axis "row" = horizontal rows stacked top-to-bottom (the m0
+ * `N[...]` form); "col" would lay the bands out side-by-side.
+ */
+function buildCardM0(bands, audioCount = 0) {
+    const split = (0, dsl_stdlib_1.weightedSplit)(bands.map((b) => b.weight), "row", { claimants: bands.map(() => "1") });
+    const audio = audioLeaf(audioCount);
+    return audio === "" ? split : assertValid(`${split}{${audio}}`);
+}
+/** Nested audio leaves ("F", "F{F}") — audio-only sources still hold frames. */
+function audioLeaf(count) {
+    if (count <= 0)
+        return "";
+    let m0 = "F";
+    for (let i = 1; i < count; i++)
+        m0 = `F{${m0}}`;
+    return m0;
+}
+/**
+ * The full body m0. Frame order is ALWAYS [stack…, captions?, audio…] —
+ * only the caption carve differs per aspect:
+ *
+ * - portrait: a real [12,56,32] band split — images in the top band,
+ *   plate+text in the bottom band, audio as the root overlay. Caption
+ *   frames: plate, text.
+ * - landscape/square: the innermost image's overlay carves a REAL
+ *   lower-third band split — the top band claimed by a transparent tile so
+ *   the images show through, the bottom band = plate{text}. Caption
+ *   frames: topSpacer, plate, text. (An inset-painted strip is illegal —
+ *   the engine caps placement.inset at 0.49 per side.)
+ */
+function buildBodyM0(opts) {
+    const { aspect, stackFrames, captions, audioCount } = opts;
+    if (!Number.isInteger(stackFrames) || stackFrames < 1) {
+        throw new Error(`buildBodyM0: stackFrames must be a positive integer, got ${stackFrames}`);
+    }
+    const audio = audioLeaf(audioCount);
+    const bandWeight = Math.round(exports.ASPECT_TABLE[aspect].captionBandFrac * 100);
+    if (captions && aspect === "portrait") {
+        // [12, 56, 32]: the 12% top margin donates forward into the image band.
+        const stackClaimant = nest("1", stackFrames);
+        const split = (0, dsl_stdlib_1.weightedSplit)([12, 100 - 12 - bandWeight, bandWeight], "row", {
+            claimants: ["0", stackClaimant, "1{1}"],
+        });
+        return assertValid(audio === "" ? String(split) : `${split}{${audio}}`);
+    }
+    if (captions) {
+        const split = (0, dsl_stdlib_1.weightedSplit)([100 - bandWeight, bandWeight], "row", {
+            claimants: ["1", "1{1}"],
+        });
+        const tail = audio === "" ? String(split) : `${split}{${audio}}`;
+        return assertValid(nest("F", stackFrames, tail));
+    }
+    return assertValid(nest("F", stackFrames, audio));
+}
+/** token nested `count` deep, innermost carrying `tail` as its overlay. */
+function nest(token, count, tail = "") {
+    let m0 = tail === "" ? token : `${token}{${tail}}`;
+    for (let i = 1; i < count; i++)
+        m0 = `${token}{${m0}}`;
+    return m0;
+}
+/**
+ * Body scene: a nested full-canvas image stack, one frame per image.
+ * count 1 → "F"; count 3 → "F{F{F}}". Never chained.
+ */
+function buildImageStackM0(count) {
+    if (!Number.isInteger(count) || count < 1) {
+        throw new Error(`buildImageStackM0: count must be a positive integer, got ${count}`);
+    }
+    let m0 = "F";
+    for (let i = 1; i < count; i++)
+        m0 = `F{${m0}}`;
+    return assertValid(m0);
+}
+/**
+ * Media-free body fallback (the built-in demo): a full-canvas panel with a
+ * centered heading block — panel base + heading overlay.
+ */
+function buildPanelBodyM0() {
+    return assertValid("F{F}");
+}
+function assertValid(m0) {
+    if (!(0, dsl_1.isValidM0String)(m0)) {
+        throw new Error(`layout: generated invalid m0 "${m0}"`);
+    }
+    return m0;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @m0saic/story/narrated-chapters/v1 — the agentic-video flagship.
+ *
+ * A chaptered, narration-timed story pipeline: an upstream orchestrator
+ * (see `examples/story-studio`) turns a topic into `story.json` + assets;
+ * this template turns that manifest into one emit:"multi" pipeline with one
+ * output step per aspect variant. Phase-2 state: structural skeleton with
+ * placeholder colour scenes; card/body visuals, narration audio and
+ * captions land in later phases.
+ *
+ * Time authority: the CLI make path passes no durationMs/fps to the
+ * planner, `emit:"multi"` escapes assertTiming's stitched-length invariant,
+ * and the output stamp preserves a template-declared pipeline durationMs —
+ * so the story's length derives entirely from the manifest + probed
+ * narration durations. `ctx.target` stays the sole authority for canvas
+ * geometry and fps (its durationMs is only a default-5000ms hint and is
+ * deliberately ignored).
+ */
+import type { MosaicTemplate } from "@m0saic/types";
+import type { NarratedChaptersProps } from "./props";
+export type { NarratedChaptersProps };
+export declare const NarratedChapters: MosaicTemplate<NarratedChaptersProps>;

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

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * @m0saic/story/narrated-chapters/v1 — the agentic-video flagship.
+ *
+ * A chaptered, narration-timed story pipeline: an upstream orchestrator
+ * (see `examples/story-studio`) turns a topic into `story.json` + assets;
+ * this template turns that manifest into one emit:"multi" pipeline with one
+ * output step per aspect variant. Phase-2 state: structural skeleton with
+ * placeholder colour scenes; card/body visuals, narration audio and
+ * captions land in later phases.
+ *
+ * Time authority: the CLI make path passes no durationMs/fps to the
+ * planner, `emit:"multi"` escapes assertTiming's stitched-length invariant,
+ * and the output stamp preserves a template-declared pipeline durationMs —
+ * so the story's length derives entirely from the manifest + probed
+ * narration durations. `ctx.target` stays the sole authority for canvas
+ * geometry and fps (its durationMs is only a default-5000ms hint and is
+ * deliberately ignored).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NarratedChapters = void 0;
+const template_utils_1 = require("@m0saic/template-utils");
+const types_1 = require("@m0saic/types");
+const captions_1 = require("./captions");
+const demo_fixture_1 = require("./demo-fixture");
+const plan_1 = require("./plan");
+const props_1 = require("./props");
+const pipeline_1 = require("./pipeline");
+const body_1 = require("./scenes/body");
+const theme_1 = require("./theme");
+const TEMPLATE_ID = "@m0saic/story/narrated-chapters/v1";
+const TEMPLATE_TITLE = "Narrated Chapters";
+/** Demo storyMs: 3500 + 4×2000 + (3340+4820+4060+5780) + 3000 = 32500. */
+const DEMO_DURATION_MS = 32500;
+exports.NarratedChapters = {
+    id: (0, types_1.asTemplateId)(TEMPLATE_ID),
+    label: TEMPLATE_TITLE,
+    version: 1,
+    description: "Chaptered, narration-timed story video from a story.json manifest — title/section cards, per-chapter scenes, and one deliverable per aspect (landscape/portrait) from a single invocation. Omit props for the built-in demo story.",
+    capabilities: { tier: "core" },
+    tags: ["media", "story", "chapters", "narrated", "pipeline", "agentic", "animated", "creators", "educators", "social", "voice-over", "explainer"],
+    outputHints: {
+        format: { kind: "video", container: "mp4" },
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: DEMO_DURATION_MS,
+        note: "Duration derives from the story manifest (narration lengths), not from -t/--duration.",
+    },
+    propsSchema: props_1.narratedChaptersPropsSchema,
+    defaultProps: {},
+    async render(props, ctx) {
+        var _a, _b;
+        const width = Math.max(1, Math.round(ctx.target.width));
+        const height = Math.max(1, Math.round(ctx.target.height));
+        const fail = (message) => (0, template_utils_1.makeErrorMosaic)(message, { width, height, title: TEMPLATE_TITLE });
+        // The CLI calls render() directly — validateTemplateProps never runs on
+        // that path, so the props schema is documentation and this is the gate.
+        const coerced = (0, props_1.coerceStoryProp)(props === null || props === void 0 ? void 0 : props.story);
+        if (coerced.errors.length > 0)
+            return fail(coerced.errors.join("\n"));
+        // `--props @story.json` passes the manifest AS the props bag — accept it
+        // rather than silently rendering the demo over the user's story.
+        const story = (_b = (_a = coerced.story) !== null && _a !== void 0 ? _a : (0, props_1.sniffBareStory)(props)) !== null && _b !== void 0 ? _b : demo_fixture_1.DEMO_STORY;
+        const shapeErrors = (0, props_1.validateStoryShape)(story);
+        if (shapeErrors.length > 0)
+            return fail(shapeErrors.join("\n"));
+        const timing = (0, plan_1.resolveTiming)(story, {
+            fps: ctx.target.fps,
+            target: { width, height },
+            // Registry keys are the RAW trimmed prop strings; never normalize.
+            narrationDurationMs: (rawPath) => { var _a; return (_a = ctx.media[(0, types_1.asAssetId)(rawPath)]) === null || _a === void 0 ? void 0 : _a.durationMs; },
+        });
+        if ("error" in timing)
+            return fail(timing.error);
+        const media = resolveSectionMedia(story, ctx);
+        if (typeof media === "string")
+            return fail(media);
+        const music = timing.plan.audio.musicPath !== undefined
+            ? { path: timing.plan.audio.musicPath, assetKey: "music_bed" }
+            : undefined;
+        const pipeline = (0, pipeline_1.buildOuterPipeline)(timing.plan, { width, height, fps: ctx.target.fps }, (0, theme_1.themeFromStory)(story), media, music);
+        attachCaptionsSidecar(pipeline, timing.plan);
+        return pipeline;
+    },
+    sidecarsSchema: {
+        captions: {
+            type: "object",
+            required: false,
+            description: "Combined SubRip captions on the story timeline, written as {output-basename}.captions.srt next to the deliverable (cues are aspect-invariant, so one file serves every variant).",
+        },
+    },
+};
+/**
+ * The combined .srt rides as a text sidecar on the FIRST variant's first
+ * scene doc: the sidecar walker recurses nested pipelines and resolves an
+ * inner step's base to the primary `-o` path, and cue timing is identical
+ * across variants, so one attachment yields exactly one
+ * `{basename}.captions.srt`.
+ */
+function attachCaptionsSidecar(pipeline, plan) {
+    var _a, _b, _c, _d, _e, _f;
+    const absolute = [];
+    for (const scene of plan.scenes) {
+        for (const cue of (_a = scene.cues) !== null && _a !== void 0 ? _a : []) {
+            absolute.push({ startMs: scene.startMs + cue.startMs, endMs: scene.startMs + cue.endMs, text: cue.text });
+        }
+    }
+    if (absolute.length === 0)
+        return;
+    const outer = pipeline;
+    const firstSceneDoc = (_f = (_e = (_d = (_c = (_b = outer.steps) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.file) === null || _d === void 0 ? void 0 : _d.steps) === null || _e === void 0 ? void 0 : _e[0]) === null || _f === void 0 ? void 0 : _f.file;
+    if (firstSceneDoc === undefined)
+        return;
+    firstSceneDoc.sidecars = {
+        captions: { kind: "text", ext: "srt", content: (0, captions_1.serializeSrt)(absolute) },
+    };
+}
+/**
+ * Probe-verify every declared image against ctx.media and hand the scene
+ * builders resolved keys. Fail fast (one message naming every problem +
+ * the mediaPaths remedy) — a missing asset must never render as a black
+ * tile. Asset keys are positional (`img_<section>_<index>`), so key
+ * collisions are impossible by construction.
+ */
+function resolveSectionMedia(story, ctx) {
+    const sections = Array.isArray(story.sections) ? story.sections : [];
+    const problems = [];
+    const resolved = sections.map((section, i) => {
+        const paths = Array.isArray(section.images)
+            ? section.images.filter((p) => typeof p === "string" && p.trim().length > 0)
+            : [];
+        const images = paths.map((rawPath, k) => {
+            var _a;
+            const meta = ctx.media[(0, types_1.asAssetId)(rawPath.trim())];
+            if (meta === undefined) {
+                problems.push(`sections[${i}].images[${k}] ("${rawPath}") is not in ctx.media — this engine probes only top-level string/string[] props; run \`story-studio build\` so mediaPaths mirrors it.`);
+            }
+            else if (meta.kind !== "image") {
+                problems.push(`sections[${i}].images[${k}] ("${rawPath}") probed as ${(_a = meta.kind) !== null && _a !== void 0 ? _a : "unknown"} — images must be stills in v1.`);
+            }
+            return { path: rawPath.trim(), assetKey: `img_${i}_${k}` };
+        });
+        // Narration becomes a real audio source — the doc manifest is what the
+        // engine probes for audio correctness (it recurses nested pipelines),
+        // so this works even on routes where mediaPaths is absent.
+        const narrationPath = typeof section.narrationAudio === "string" && section.narrationAudio.trim().length > 0
+            ? section.narrationAudio.trim()
+            : undefined;
+        return {
+            images,
+            focus: (0, body_1.focusFromOverrides)(section.overrides, paths.length),
+            ...(narrationPath !== undefined ? { narration: { path: narrationPath, assetKey: `nar_${i}` } } : {}),
+        };
+    });
+    if (problems.length > 0)
+        return problems.join("\n");
+    return resolved;
+}
+(0, template_utils_1.registerTemplate)(exports.NarratedChapters);

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+import type { MosaicDocument, MosaicDocumentPipeline } from "@m0saic/types";
+import type { StoryPlan, StoryScene, StoryVariant } from "./plan";
+import type { MusicBed, SectionMedia } from "./scenes/body";
+import type { StoryTheme } from "./theme";
+export type StoryRenderTarget = {
+    width: number;
+    height: number;
+    fps: number;
+};
+/** Dispatch one scene to its builder. */
+export declare function buildSceneDoc(scene: StoryScene, variant: StoryVariant, plan: StoryPlan, theme: StoryTheme, media: SectionMedia[], music?: MusicBed): MosaicDocument;
+/** The INNER pipeline — the whole story at one variant's canvas. */
+export declare function buildStoryPipeline(plan: StoryPlan, variant: StoryVariant, theme: StoryTheme, media: SectionMedia[], music?: MusicBed): MosaicDocumentPipeline;
+/** The OUTER pipeline — one output step per variant. */
+export declare function buildOuterPipeline(plan: StoryPlan, target: StoryRenderTarget, theme: StoryTheme, media: SectionMedia[], music?: MusicBed): MosaicDocumentPipeline;