@m0saic/templates 0.2.0

package/dist/m0saic/social/quote-card/v1/quote-card.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ============================================================================
+ * @m0saic/social/quote-card/v1 — pull-quote social cards
+ * ============================================================================
+ *
+ * A pull-quote graphic for social: quote text + attribution + optional
+ * circular avatar over a hand-tuned themed card — emitted as a lossless PNG
+ * still. Square by default; the layout re-derives from `ctx.target` every
+ * render, so 4:5 / 9:16 / 16:9 exports come from `-w`/`-h` alone.
+ *
+ * Everything is real geometry (the Rect Thesis): the decorative quote mark,
+ * the wrapped quote block, the accent bar, the avatar circle and the
+ * name/role lines are m0 cells with StableKeys; margins and gaps are `-`
+ * null tiles. Text is rendered with the svg glyph rasterizer (bundled
+ * deterministic font — no host fontconfig, no drawtext spawn); the quote is
+ * greedy word-wrapped in the layout against that same font, since the
+ * rasterizer has no auto-wrap. The avatar is a media source clipped to a
+ * circle via `effects.rounding` (pill in a square cell).
+ *
+ * Still-first by design: `outputHints.format` container-locks the CLI
+ * output, so an animated sibling ships as its own video-hinted template id
+ * (the qr-stamp still/video precedent) — see TEMPLATE-NOTES.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+export type QuoteCardProps = {
+    /** The quote body. Wrapped automatically; supports any length (shrinks to fit). */
+    quote?: string;
+    /** Who said it (rendered bold under the accent bar). Empty = no attribution. */
+    attribution?: string;
+    /** Second attribution line — title, handle, book, episode. Empty = none. */
+    role?: string;
+    /** Avatar image, clipped to a circle beside the attribution. */
+    avatar?: string;
+    /** Card composition: "center" (classic) or "left" (editorial). Default "center". */
+    align?: "center" | "left";
+    /** Show the decorative opening-quote glyph above the quote. Default true. */
+    quoteMark?: boolean;
+    /** Accent color (quote mark + bar). Default m0saic orange. */
+    accent?: MosaicColor;
+    /** Hand-tuned background/ink duo. Default "light". */
+    preset?: "light" | "dark";
+    /** Background override (the card color). */
+    background?: MosaicColor;
+    /** Ink override (quote + attribution name). */
+    ink?: MosaicColor;
+    /** Outer margin, as a fraction of the canvas short edge. Default 0.09. */
+    margin?: number;
+};
+export declare const QuoteCard: MosaicTemplate<QuoteCardProps>;
+export default QuoteCard;

package/dist/m0saic/social/quote-card/v1/quote-card.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/social/quote-card/v1 — pull-quote social cards
+ * ============================================================================
+ *
+ * A pull-quote graphic for social: quote text + attribution + optional
+ * circular avatar over a hand-tuned themed card — emitted as a lossless PNG
+ * still. Square by default; the layout re-derives from `ctx.target` every
+ * render, so 4:5 / 9:16 / 16:9 exports come from `-w`/`-h` alone.
+ *
+ * Everything is real geometry (the Rect Thesis): the decorative quote mark,
+ * the wrapped quote block, the accent bar, the avatar circle and the
+ * name/role lines are m0 cells with StableKeys; margins and gaps are `-`
+ * null tiles. Text is rendered with the svg glyph rasterizer (bundled
+ * deterministic font — no host fontconfig, no drawtext spawn); the quote is
+ * greedy word-wrapped in the layout against that same font, since the
+ * rasterizer has no auto-wrap. The avatar is a media source clipped to a
+ * circle via `effects.rounding` (pill in a square cell).
+ *
+ * Still-first by design: `outputHints.format` container-locks the CLI
+ * output, so an animated sibling ships as its own video-hinted template id
+ * (the qr-stamp still/video precedent) — see TEMPLATE-NOTES.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuoteCard = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const layout_1 = require("./layout");
+const TEMPLATE_ID = "@m0saic/social/quote-card/v1";
+/** Hand-tuned card duos (dark is retuned, not derived). `subtle` inks the role line. */
+const PRESETS = {
+    light: { bg: "#faf9f7", ink: "#17181c", subtle: "#6b6f76" },
+    dark: { bg: "#101014", ink: "#e8e8ee", subtle: "#a3a7b0" },
+};
+const DEFAULT_ACCENT = "#f97316"; // m0saic brand orange
+const DEFAULT_MARGIN = 0.09;
+const DEFAULT_QUOTE = "Everything is rectangles on a canvas.";
+const DEFAULT_ATTRIBUTION = "The m0saic Thesis";
+/** Blank-string color pickers mean "unset" — fall back to the preset. */
+function pickColor(value, fallback) {
+    const s = typeof value === "string" ? value.trim() : value;
+    return s ? s : fallback;
+}
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    quote: {
+        type: "string",
+        required: true,
+        description: "The quote body. Wrapped and sized to fit automatically — long quotes shrink, short quotes render large.",
+        meta: { ui: { label: "Quote", order: 1, primary: true } },
+    },
+    attribution: {
+        type: "string",
+        required: false,
+        description: "Who said it — rendered bold under the accent bar. Empty removes the attribution.",
+        meta: { ui: { label: "Attribution", order: 2 } },
+    },
+    role: {
+        type: "string",
+        required: false,
+        description: "Second attribution line — a title, handle, book or episode. Empty removes it.",
+        meta: { control: { placeholder: "none" }, ui: { label: "Role / source", order: 3 } },
+    },
+    avatar: {
+        type: "media",
+        required: false,
+        description: "Avatar image, clipped to a circle beside the attribution.",
+        meta: {
+            ui: { label: "Avatar", order: 4 },
+            control: { picker: "file", accept: ["image"] },
+        },
+    },
+    align: {
+        type: "string",
+        required: false,
+        description: 'Card composition: "center" (classic quote card) or "left" (editorial).',
+        meta: {
+            constraints: { oneOf: ["center", "left"] },
+            ui: { label: "Alignment", order: 1 },
+        },
+    },
+    quoteMark: {
+        type: "boolean",
+        required: false,
+        description: "Show the decorative opening-quote glyph above the quote.",
+        meta: { ui: { label: "Quote mark", order: 2 } },
+    },
+    accent: {
+        type: "string",
+        required: false,
+        description: "Accent color for the quote mark and the divider bar.",
+        meta: {
+            constraints: { isColor: true },
+            control: { colorPicker: true },
+            ui: { label: "Accent", order: 3 },
+        },
+    },
+    preset: {
+        type: "string",
+        required: false,
+        description: 'Hand-tuned card duo: "light" (default) or "dark".',
+        meta: {
+            constraints: { oneOf: ["light", "dark"] },
+            ui: { label: "Preset", order: 4 },
+        },
+    },
+    background: {
+        type: "string",
+        required: false,
+        description: "Card background override.",
+        meta: {
+            constraints: { isColor: true },
+            control: { placeholder: "preset background", colorPicker: true },
+            ui: { label: "Background", order: 5 },
+        },
+    },
+    ink: {
+        type: "string",
+        required: false,
+        description: "Ink override (quote body and attribution name).",
+        meta: {
+            constraints: { isColor: true },
+            control: { placeholder: "preset ink", colorPicker: true },
+            ui: { label: "Ink", order: 6 },
+        },
+    },
+    margin: {
+        type: "number",
+        required: false,
+        description: "Outer margin, as a fraction of the canvas short edge.",
+        meta: {
+            constraints: { min: 0.02, max: 0.2 },
+            control: { flavor: "slider", step: 0.005 },
+            ui: { label: "Margin", order: 1 },
+        },
+    },
+});
+/** SVG-glyph text cell (bundled deterministic font; no drawtext spawn). */
+function textCell(opts) {
+    return {
+        type: "text",
+        rasterizer: "svg",
+        renderMode: { kind: "image" },
+        layers: [
+            {
+                content: { kind: "literal", text: opts.text },
+                style: {
+                    fontSize: opts.fontSize,
+                    fontColor: opts.color,
+                    ...(opts.bold ? { fontWeight: "bold" } : {}),
+                },
+                placement: { hAlign: opts.hAlign, vAlign: "middle" },
+            },
+        ],
+        editor: { owner: "template", label: opts.label },
+    };
+}
+exports.QuoteCard = {
+    id: (0, types_1.asTemplateId)(TEMPLATE_ID),
+    label: "Quote Card",
+    version: 1,
+    description: "Pull-quote social card — auto-wrapped quote, accent bar, attribution with an optional circular avatar; hand-tuned light/dark presets; lossless PNG still, aspect-safe from square to stories.",
+    capabilities: { tier: "core" },
+    tags: ["social", "quote", "card", "pull-quote", "promo", "creators", "marketers", "testimonial"],
+    outputHints: { width: 1080, height: 1080, format: { kind: "image", container: "png" } },
+    propsSchema,
+    defaultProps: {
+        quote: DEFAULT_QUOTE,
+        attribution: DEFAULT_ATTRIBUTION,
+        align: "center",
+        quoteMark: true,
+        accent: DEFAULT_ACCENT,
+        preset: "light",
+        margin: DEFAULT_MARGIN,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        const fail = (message) => (0, template_utils_1.makeErrorMosaic)(message, { title: "Quote Card", width: W, height: H });
+        // ── knobs ──
+        const preset = props.preset === "dark" ? "dark" : "light";
+        const duo = PRESETS[preset];
+        const bg = pickColor(props.background, duo.bg);
+        const ink = pickColor(props.ink, duo.ink);
+        const accent = pickColor(props.accent, DEFAULT_ACCENT);
+        const align = props.align === "left" ? "left" : "center";
+        const quoteMark = props.quoteMark !== false;
+        const marginFrac = Math.min(0.2, Math.max(0.02, (_a = props.margin) !== null && _a !== void 0 ? _a : DEFAULT_MARGIN));
+        const quote = ((_b = props.quote) !== null && _b !== void 0 ? _b : "").trim();
+        if (quote.length === 0)
+            return fail("quote must not be empty");
+        const attribution = ((_c = props.attribution) !== null && _c !== void 0 ? _c : "").trim();
+        const role = ((_d = props.role) !== null && _d !== void 0 ? _d : "").trim();
+        // ── optional avatar (probed by the host; the template does no I/O) ──
+        const avatarId = ((_e = props.avatar) !== null && _e !== void 0 ? _e : "").trim();
+        let avatarAssetKey = null;
+        if (avatarId.length > 0) {
+            const meta = ctx.media[(0, types_1.asAssetId)(avatarId)];
+            if (!meta || !(meta.width > 0) || !(meta.height > 0))
+                return fail(`no probed dimensions for avatar "${avatarId}"`);
+            if (meta.kind !== "image")
+                return fail(`avatar "${avatarId}" is ${(_f = meta.kind) !== null && _f !== void 0 ? _f : "unknown"} — the avatar must be an image`);
+            avatarAssetKey = String((0, template_utils_1.slugifyAssetKeyFromPath)(avatarId));
+        }
+        // ── source factory: one source per cell. Fed into the layout's
+        //    inset-recovery packer, which returns them in the m0's frame order.
+        //    The quote / name / role cells each DISPLAY one prop, so they carry
+        //    a `bindProp` (Make's double-click → inline-edit handle). Colour
+        //    props bind the rect they PAINT: `accent` inks the mark and fills the
+        //    bar; `ink` rides the quote / name rects as a second (stacked) entry.
+        //    `background` is `doc.backgroundColor` — no rect, nothing to bind;
+        //    the role line's `subtle` ink is preset-derived, never a prop. ──
+        const sourceForCell = (cell) => {
+            switch (cell.kind) {
+                case "mark":
+                    return (0, template_utils_1.bindProp)(textCell({
+                        text: cell.text,
+                        fontSize: cell.fontSize,
+                        color: accent,
+                        bold: true,
+                        hAlign: cell.hAlign,
+                        label: "mark",
+                    }), "accent");
+                case "quote":
+                    return (0, template_utils_1.bindProps)(textCell({
+                        text: cell.text,
+                        fontSize: cell.fontSize,
+                        color: ink,
+                        hAlign: cell.hAlign,
+                        label: "quote",
+                    }), [{ propKey: "quote" }, { propKey: "ink" }]);
+                case "accent-bar":
+                    return (0, template_utils_1.bindProp)({
+                        type: "lavfi",
+                        color: accent,
+                        editor: { owner: "template", label: "accent" },
+                    }, "accent");
+                case "avatar":
+                    return {
+                        type: "media",
+                        mediaType: "image",
+                        assetId: avatarAssetKey,
+                        placement: { fit: "cover" },
+                        // Pill in a square cell = circle; the cell IS square by construction.
+                        effects: { rounding: { cornerStyle: "pill" } },
+                        editor: { owner: "template", label: "avatar" },
+                    };
+                case "name":
+                    return (0, template_utils_1.bindProps)(textCell({
+                        text: cell.text,
+                        fontSize: cell.fontSize,
+                        color: ink,
+                        bold: true,
+                        hAlign: cell.hAlign,
+                        label: "name",
+                    }), [{ propKey: "attribution" }, { propKey: "ink" }]);
+                case "role":
+                    return (0, template_utils_1.bindProp)(textCell({
+                        text: cell.text,
+                        fontSize: cell.fontSize,
+                        color: duo.subtle,
+                        hAlign: cell.hAlign,
+                        label: "role",
+                    }), "role");
+            }
+        };
+        // ── geometry + composed sources (ratio m0 + frame-ordered inset sources) ──
+        let layout;
+        try {
+            layout = (0, layout_1.buildQuoteCardLayout)({
+                W,
+                H,
+                quote,
+                attribution: attribution.length > 0 ? attribution : null,
+                role: role.length > 0 ? role : null,
+                hasAvatar: avatarAssetKey != null,
+                align,
+                quoteMark,
+                marginFrac,
+            }, sourceForCell);
+        }
+        catch (e) {
+            if (e instanceof layout_1.QuoteLayoutError)
+                return fail(e.message);
+            throw e;
+        }
+        const sources = layout.sources;
+        const assets = {};
+        if (avatarAssetKey != null)
+            assets[avatarAssetKey] = { kind: "file", path: avatarId, mediaType: "image" };
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            assets,
+            m0: layout.m0,
+            sources,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+            size: { width: W, height: H },
+            backgroundColor: bg,
+            editor: {
+                label: `Quote Card · ${attribution.length > 0 ? attribution : "unattributed"} · ${preset}`,
+            },
+        };
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.QuoteCard);
+exports.default = exports.QuoteCard;

package/dist/m0saic/story/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./narrated-chapters";
+export * from "./scrapbook/v1";

package/dist/m0saic/story/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* Story — narrated multi-chapter pipeline pack (the agentic-video flagship). */
+__exportStar(require("./narrated-chapters"), exports);
+/* Scrapbook — a short personal film: photos, a line each, paper and drift. */
+__exportStar(require("./scrapbook/v1"), exports);

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

@@ -0,0 +1 @@
+export * from "./v1";

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

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1"), exports);

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

@@ -0,0 +1,42 @@
+/**
+ * Caption cue engine.
+ *
+ * Cue precedence per section: explicit `cues` (inlined by story-studio from
+ * .srt or emitted directly by a timestamp-capable TTS provider) → synthesized
+ * sentence cues from `narrationText`. All times are narration-relative,
+ * which equals step-local time because cards CUT into narration (the body
+ * step's t=0 is the narration's first sample).
+ *
+ * Synthesis (the brief's algorithm): sentence split with an abbreviation
+ * suppression set → sub-split long sentences at clause boundaries →
+ * Hamilton distribution over the NARRATION SPAN (captions track speech, not
+ * the padded body) with w[j] = max(12, len) → merge any cue below minCueMs
+ * into its shorter neighbour and re-run → trim cueGapMs off each end.
+ *
+ * Rendering stays drawtext (`buildSvgTextSource` drops per-layer enable —
+ * an svg caption source would show every cue at once, forever) and is
+ * assembled in scenes/body.ts; this module is pure cue math + SRT text.
+ */
+import type { StoryCue, StorySection } from "./props";
+/** Hard cap per section — drawtext's expression budget is finite. */
+export declare const MAX_CUES_PER_SECTION = 96;
+export type CaptionsConfig = {
+    enabled: boolean;
+    minCueMs: number;
+    cueGapMs: number;
+    plate: "always" | "never";
+};
+export declare const DEFAULT_CAPTIONS: CaptionsConfig;
+export declare function resolveSectionCues(section: StorySection, narrationMs: number | undefined, config: CaptionsConfig): StoryCue[];
+/** Provided cues: keep order, clamp into the narration span, cap the count. */
+export declare function clampCues(cues: StoryCue[], narrationMs: number): StoryCue[];
+export declare function synthesizeCues(narrationText: string, narrationMs: number, config: CaptionsConfig): StoryCue[];
+/** Sentence split at .!?… + whitespace + an upper/digit/quote opener, ABBREV-protected. */
+export declare function splitSentences(text: string): string[];
+/** Sub-split an over-long sentence at clause boundaries (, ; : —). */
+export declare function splitClauses(sentence: string): string[];
+/** Largest-remainder integer split; ties → lower index. (Shared with plan.ts.) */
+export declare function hamilton(total: number, weights: number[]): number[];
+/** A cue placed on the global story timeline (for the .srt sidecar). */
+export type AbsoluteCue = StoryCue;
+export declare function serializeSrt(cues: AbsoluteCue[]): string;

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

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * Caption cue engine.
+ *
+ * Cue precedence per section: explicit `cues` (inlined by story-studio from
+ * .srt or emitted directly by a timestamp-capable TTS provider) → synthesized
+ * sentence cues from `narrationText`. All times are narration-relative,
+ * which equals step-local time because cards CUT into narration (the body
+ * step's t=0 is the narration's first sample).
+ *
+ * Synthesis (the brief's algorithm): sentence split with an abbreviation
+ * suppression set → sub-split long sentences at clause boundaries →
+ * Hamilton distribution over the NARRATION SPAN (captions track speech, not
+ * the padded body) with w[j] = max(12, len) → merge any cue below minCueMs
+ * into its shorter neighbour and re-run → trim cueGapMs off each end.
+ *
+ * Rendering stays drawtext (`buildSvgTextSource` drops per-layer enable —
+ * an svg caption source would show every cue at once, forever) and is
+ * assembled in scenes/body.ts; this module is pure cue math + SRT text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CAPTIONS = exports.MAX_CUES_PER_SECTION = void 0;
+exports.resolveSectionCues = resolveSectionCues;
+exports.clampCues = clampCues;
+exports.synthesizeCues = synthesizeCues;
+exports.splitSentences = splitSentences;
+exports.splitClauses = splitClauses;
+exports.hamilton = hamilton;
+exports.serializeSrt = serializeSrt;
+/** Hard cap per section — drawtext's expression budget is finite. */
+exports.MAX_CUES_PER_SECTION = 96;
+exports.DEFAULT_CAPTIONS = {
+    enabled: true,
+    minCueMs: 900,
+    cueGapMs: 80,
+    plate: "always",
+};
+/** Abbreviations whose trailing "." must not end a sentence. */
+const ABBREV = new Set([
+    "mr.", "mrs.", "ms.", "dr.", "prof.", "st.", "jr.", "sr.",
+    "vs.", "etc.", "e.g.", "i.e.", "no.", "inc.", "ltd.", "co.",
+    "a.m.", "p.m.", "u.s.", "u.k.",
+]);
+/** Sentences longer than this get sub-split at clause boundaries. */
+const LONG_SENTENCE_CHARS = 110;
+function resolveSectionCues(section, narrationMs, config) {
+    var _a;
+    if (!config.enabled || narrationMs === undefined || narrationMs <= 0)
+        return [];
+    // Precedence: timed data first (cues, incl. srt-inlined), then the
+    // explicit per-section caption override (one cue over the whole span),
+    // then synthesis from narrationText.
+    if (Array.isArray(section.cues) && section.cues.length > 0) {
+        return clampCues(section.cues, narrationMs);
+    }
+    const captionOverride = (_a = section.overrides) === null || _a === void 0 ? void 0 : _a.caption;
+    if (typeof captionOverride === "string" && captionOverride.trim().length > 0) {
+        return [{ startMs: 0, endMs: narrationMs, text: captionOverride.trim() }];
+    }
+    if (typeof section.narrationText === "string" && section.narrationText.trim().length > 0) {
+        return synthesizeCues(section.narrationText, narrationMs, config);
+    }
+    return [];
+}
+/** Provided cues: keep order, clamp into the narration span, cap the count. */
+function clampCues(cues, narrationMs) {
+    const out = [];
+    for (const cue of cues) {
+        const startMs = Math.max(0, Math.round(cue.startMs));
+        const endMs = Math.min(narrationMs, Math.round(cue.endMs));
+        if (endMs <= startMs)
+            continue;
+        const text = cue.text.trim();
+        if (text.length === 0)
+            continue;
+        out.push({ startMs, endMs, text });
+        if (out.length >= exports.MAX_CUES_PER_SECTION)
+            break;
+    }
+    return out;
+}
+function synthesizeCues(narrationText, narrationMs, config) {
+    const pieces = splitSentences(narrationText)
+        .flatMap((s) => (s.length > LONG_SENTENCE_CHARS ? splitClauses(s) : [s]))
+        .slice(0, exports.MAX_CUES_PER_SECTION);
+    if (pieces.length === 0)
+        return [];
+    // Hamilton over the narration span — captions track speech, not padding.
+    let texts = pieces;
+    let durations = hamilton(narrationMs, texts.map((t) => Math.max(12, t.length)));
+    // Merge any cue below minCueMs into its SHORTER neighbour and re-run.
+    for (let guard = 0; guard < exports.MAX_CUES_PER_SECTION; guard++) {
+        if (texts.length <= 1)
+            break;
+        const idx = durations.findIndex((d) => d < config.minCueMs);
+        if (idx === -1)
+            break;
+        const left = idx > 0 ? durations[idx - 1] : Infinity;
+        const right = idx < durations.length - 1 ? durations[idx + 1] : Infinity;
+        const into = left <= right ? idx - 1 : idx + 1;
+        const [a, b] = into < idx ? [into, idx] : [idx, into];
+        texts = [...texts.slice(0, a), `${texts[a]} ${texts[b]}`, ...texts.slice(b + 1)];
+        durations = hamilton(narrationMs, texts.map((t) => Math.max(12, t.length)));
+    }
+    // Lay out sequentially, then trim the gap off each end — clamped per cue
+    // so an oversized cueGapMs can never invert an interval and silently
+    // delete a caption.
+    const cues = [];
+    let cursor = 0;
+    for (let i = 0; i < texts.length; i++) {
+        const rawStart = cursor;
+        const rawEnd = cursor + durations[i];
+        cursor = rawEnd;
+        const gap = Math.min(config.cueGapMs, Math.floor((durations[i] - 1) / 2));
+        const startMs = rawStart + (i > 0 ? gap : 0);
+        const endMs = rawEnd - (i < texts.length - 1 ? gap : 0);
+        if (endMs > startMs)
+            cues.push({ startMs, endMs, text: texts[i] });
+    }
+    return cues;
+}
+/** Sentence split at .!?… + whitespace + an upper/digit/quote opener, ABBREV-protected. */
+function splitSentences(text) {
+    var _a, _b;
+    const normalized = text.trim().replace(/\s+/g, " ");
+    if (normalized.length === 0)
+        return [];
+    const out = [];
+    let start = 0;
+    const re = /[.!?…]+["'”’]?(?=\s+["'“‘]?[A-Z0-9])/g;
+    let m;
+    while ((m = re.exec(normalized)) !== null) {
+        const end = m.index + m[0].length;
+        const candidate = normalized.slice(start, end).trim();
+        const lastWord = (_b = (_a = candidate.split(" ").pop()) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== null && _b !== void 0 ? _b : "";
+        if (ABBREV.has(lastWord))
+            continue; // "Dr." — not a boundary
+        if (candidate.length > 0)
+            out.push(candidate);
+        start = end;
+    }
+    const tail = normalized.slice(start).trim();
+    if (tail.length > 0)
+        out.push(tail);
+    return out;
+}
+/** Sub-split an over-long sentence at clause boundaries (, ; : —). */
+function splitClauses(sentence) {
+    const parts = sentence
+        .split(/(?<=[,;:—])\s+/)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    if (parts.length <= 1)
+        return [sentence];
+    // Greedily rejoin so fragments stay caption-sized, not comma-confetti.
+    const out = [];
+    let current = "";
+    for (const part of parts) {
+        const joined = current.length > 0 ? `${current} ${part}` : part;
+        if (joined.length <= LONG_SENTENCE_CHARS) {
+            current = joined;
+        }
+        else {
+            if (current.length > 0)
+                out.push(current);
+            current = part;
+        }
+    }
+    if (current.length > 0)
+        out.push(current);
+    return out;
+}
+/** Largest-remainder integer split; ties → lower index. (Shared with plan.ts.) */
+function hamilton(total, weights) {
+    const sum = weights.reduce((a, b) => a + b, 0);
+    const raw = weights.map((w) => (total * w) / sum);
+    const base = raw.map(Math.floor);
+    let remainder = total - base.reduce((a, b) => a + b, 0);
+    const order = raw
+        .map((r, i) => ({ frac: r - Math.floor(r), i }))
+        .sort((a, b) => b.frac - a.frac || a.i - b.i);
+    for (let n = 0; n < order.length && remainder > 0; n++, remainder--) {
+        base[order[n].i] += 1;
+    }
+    return base;
+}
+function serializeSrt(cues) {
+    return cues
+        .map((cue, i) => `${i + 1}\n${srtTime(cue.startMs)} --> ${srtTime(cue.endMs)}\n${cue.text}\n`)
+        .join("\n");
+}
+function srtTime(ms) {
+    const clamped = Math.max(0, Math.round(ms));
+    const h = Math.floor(clamped / 3600000);
+    const m = Math.floor((clamped % 3600000) / 60000);
+    const s = Math.floor((clamped % 60000) / 1000);
+    const rem = clamped % 1000;
+    const pad = (v, len) => String(v).padStart(len, "0");
+    return `${pad(h, 2)}:${pad(m, 2)}:${pad(s, 2)},${pad(rem, 3)}`;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+import type { StoryDocument } from "./props";
+export declare const DEMO_STORY: StoryDocument;