@m0saic/templates 0.2.0

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

@@ -0,0 +1,40 @@
+/**
+ * Card scenes — title / section-card / outro. One builder, three band
+ * configs (layout.ts CARD_BANDS). Every band is a REAL m0 cell (Rect
+ * Thesis); text is svg-rasterized (R9: static text never spawns drawtext),
+ * so fitting uses the same bundled font `measureText` measures — the 0.90
+ * caption safety factor is a drawtext concern, not ours; quote-card's 0.98
+ * usable-width convention applies.
+ */
+import type { MosaicColor, MosaicDocument, MosaicSource } from "@m0saic/types";
+import type { StoryPlan, StoryScene, StoryVariant } from "../plan";
+import type { StoryTheme } from "../theme";
+import type { MusicBed } from "./body";
+export declare function buildCardDoc(scene: StoryScene, variant: StoryVariant, plan: StoryPlan, theme: StoryTheme, music?: MusicBed): MosaicDocument;
+type TextCellOptions = {
+    maxFont: number;
+    maxW: number;
+    bandH: number;
+    color: MosaicColor;
+    bold?: boolean;
+    label: string;
+};
+/** Single svg text cell; empty text degrades to an invisible tile. */
+export declare function textCell(text: string, opts: TextCellOptions): MosaicSource;
+export type HeadingFit = {
+    text: string;
+    fontSize: number;
+};
+/**
+ * Real-metrics fitting (mirrors social/quote-card/v1/layout.ts): try one
+ * line at the cap, shrink to the width, fall to a two-line greedy wrap, and
+ * as the last resort wrap at the floor size and ellipsize what the band
+ * cannot hold — NEVER return unwrapped text that overflows the cell (svg
+ * lays glyphs at the exact given size; nothing downstream auto-shrinks).
+ * The readable floor tracks the cap: a tiny canvas whose cap sits below
+ * 16 px keeps its cap instead of being promoted above it.
+ */
+export declare function fitHeadingBlock(text: string, boxW: number, boxH: number, maxFont: number, bold: boolean): HeadingFit;
+/** Greedy word wrap against real metrics; null when a single word overflows. */
+export declare function greedyWrap(text: string, widthOf: (s: string) => number, maxW: number): string[] | null;
+export {};

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

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Card scenes — title / section-card / outro. One builder, three band
+ * configs (layout.ts CARD_BANDS). Every band is a REAL m0 cell (Rect
+ * Thesis); text is svg-rasterized (R9: static text never spawns drawtext),
+ * so fitting uses the same bundled font `measureText` measures — the 0.90
+ * caption safety factor is a drawtext concern, not ours; quote-card's 0.98
+ * usable-width convention applies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCardDoc = buildCardDoc;
+exports.textCell = textCell;
+exports.fitHeadingBlock = fitHeadingBlock;
+exports.greedyWrap = greedyWrap;
+const template_utils_1 = require("@m0saic/template-utils");
+const layout_1 = require("../layout");
+const body_1 = require("./body");
+const MIN_FONT_PX = 16;
+const USABLE_W = 0.98;
+const LINE_HEIGHT = 1.25; // measureText/textToPath default — svg mode is pinned to it
+function buildCardDoc(scene, variant, plan, theme, music) {
+    if (scene.kind === "body") {
+        throw new Error(`buildCardDoc: got a body scene ("${scene.name}")`);
+    }
+    const bands = layout_1.CARD_BANDS[scene.kind];
+    const spec = layout_1.ASPECT_TABLE[(0, layout_1.classifyAspect)(variant.width, variant.height)];
+    const S = Math.min(variant.width, variant.height);
+    const safeW = Math.floor(variant.width * spec.cardSafeW);
+    const totalWeight = bands.reduce((a, b) => a + b.weight, 0);
+    const sources = bands.map((band) => {
+        var _a;
+        const bandH = Math.floor((variant.height * band.weight) / totalWeight);
+        switch (band.kind) {
+            case "spacer":
+                return (0, template_utils_1.makeColorTile)(theme.canvas);
+            case "bar":
+                // A short centered accent bar: one tile, carved by inset — no extra cells.
+                return (0, template_utils_1.makeColorTile)(theme.accent, {
+                    placement: { inset: { left: 0.44, right: 0.44 } },
+                });
+            case "kicker":
+                return textCell(kickerText(scene), {
+                    maxFont: Math.round(S * spec.subScale),
+                    maxW: safeW,
+                    bandH,
+                    color: theme.accent,
+                    bold: true,
+                    label: `${scene.name}/kicker`,
+                });
+            case "heading":
+                return textCell(scene.heading, {
+                    maxFont: Math.round(S * spec.headingScale),
+                    maxW: safeW,
+                    bandH,
+                    color: theme.ink,
+                    bold: true,
+                    label: `${scene.name}/heading`,
+                });
+            case "sub":
+                return textCell((_a = scene.subheading) !== null && _a !== void 0 ? _a : "", {
+                    maxFont: Math.round(S * spec.subScale),
+                    maxW: safeW,
+                    bandH,
+                    color: theme.muted,
+                    label: `${scene.name}/sub`,
+                });
+        }
+    });
+    // The music bed rides every step (there is no pipeline-spanning audio
+    // track), offset into the file by the scene's global start.
+    const assets = {};
+    if (music !== undefined) {
+        assets[music.assetKey] = {
+            kind: "file",
+            path: music.path,
+            mediaType: "audio",
+        };
+        sources.push((0, body_1.musicSource)(music, scene, plan, `${scene.name}/music`));
+    }
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, layout_1.buildCardM0)(bands, music !== undefined ? 1 : 0),
+        assets,
+        sources,
+        size: { width: variant.width, height: variant.height },
+        fps: plan.fps,
+        durationMs: scene.visibleMs + scene.xfadeOutMs,
+        backgroundColor: theme.canvas,
+        editor: { label: `${variant.name}/${scene.name}` },
+    };
+}
+function kickerText(scene) {
+    var _a;
+    return `PART ${String(((_a = scene.sectionIndex) !== null && _a !== void 0 ? _a : 0) + 1).padStart(2, "0")}`;
+}
+/** Single svg text cell; empty text degrades to an invisible tile. */
+function textCell(text, opts) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+        return (0, template_utils_1.makeColorTile)("black@0");
+    }
+    const fit = fitHeadingBlock(trimmed, opts.maxW, Math.max(1, opts.bandH), opts.maxFont, opts.bold === true);
+    return {
+        type: "text",
+        rasterizer: "svg",
+        renderMode: { kind: "image" },
+        layers: [
+            {
+                content: { kind: "literal", text: fit.text },
+                style: {
+                    fontSize: fit.fontSize,
+                    fontColor: opts.color,
+                    ...(opts.bold ? { fontWeight: "bold" } : {}),
+                },
+                placement: { hAlign: "center", vAlign: "middle" },
+            },
+        ],
+        editor: { owner: "template", label: opts.label },
+    };
+}
+/**
+ * Real-metrics fitting (mirrors social/quote-card/v1/layout.ts): try one
+ * line at the cap, shrink to the width, fall to a two-line greedy wrap, and
+ * as the last resort wrap at the floor size and ellipsize what the band
+ * cannot hold — NEVER return unwrapped text that overflows the cell (svg
+ * lays glyphs at the exact given size; nothing downstream auto-shrinks).
+ * The readable floor tracks the cap: a tiny canvas whose cap sits below
+ * 16 px keeps its cap instead of being promoted above it.
+ */
+function fitHeadingBlock(text, boxW, boxH, maxFont, bold) {
+    var _a, _b;
+    const floor = Math.max(8, Math.min(MIN_FONT_PX, maxFont));
+    const fontPath = bold ? (_a = (0, template_utils_1.resolveFontFile)({ weight: "bold" })) === null || _a === void 0 ? void 0 : _a.path : undefined;
+    const usableW = Math.floor(boxW * USABLE_W);
+    const width = (s, f) => (0, template_utils_1.measureText)(s, { fontSize: f, ...(fontPath ? { fontPath } : {}) }).width;
+    const clampFont = (v) => Math.max(floor, Math.min(maxFont, v));
+    const fitToHeight = (lineCount) => clampFont(Math.floor(boxH / (lineCount * LINE_HEIGHT)));
+    // Single line at the largest size that fits both axes.
+    const oneLineFont = clampFont(Math.floor((maxFont * usableW) / Math.max(1, width(text, maxFont))));
+    if (width(text, oneLineFont) <= usableW && oneLineFont >= Math.round(maxFont * 0.62)) {
+        return { text, fontSize: Math.min(oneLineFont, fitToHeight(1)) };
+    }
+    // Two-line greedy wrap, then shrink to fit both axes.
+    for (let font = maxFont; font >= floor; font = Math.max(floor, Math.floor(font * 0.9))) {
+        const lines = greedyWrap(text, (s) => width(s, font), usableW);
+        if (lines !== null && lines.length <= 2 && font <= fitToHeight(lines.length)) {
+            return { text: lines.join("\n"), fontSize: font };
+        }
+        if (font === floor)
+            break; // Math.max keeps font pinned at floor — avoid looping forever
+    }
+    // Last resort: wrap at the floor, keep the lines the band can hold,
+    // ellipsize the remainder (quote-card's degrade posture).
+    const maxLines = Math.max(1, Math.floor(boxH / (floor * LINE_HEIGHT)));
+    const wrapped = (_b = greedyWrap(text, (s) => width(s, floor), usableW)) !== null && _b !== void 0 ? _b : hardSlice(text, (s) => width(s, floor), usableW);
+    if (wrapped.length > maxLines) {
+        const kept = wrapped.slice(0, maxLines);
+        kept[kept.length - 1] = `${kept[kept.length - 1].replace(/…$/, "")}…`;
+        return { text: kept.join("\n"), fontSize: floor };
+    }
+    return { text: wrapped.join("\n"), fontSize: floor };
+}
+/** Character-level fallback when a single word exceeds the box width. */
+function hardSlice(text, widthOf, maxW) {
+    const out = [];
+    let current = "";
+    for (const ch of text) {
+        if (widthOf(current + ch) > maxW && current.length > 0) {
+            out.push(current);
+            current = ch;
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.length > 0)
+        out.push(current);
+    return out.length > 0 ? out : [text];
+}
+/** Greedy word wrap against real metrics; null when a single word overflows. */
+function greedyWrap(text, widthOf, maxW) {
+    const out = [];
+    let current = "";
+    for (const word of text.split(/\s+/).filter((w) => w.length > 0)) {
+        const joined = current.length > 0 ? `${current} ${word}` : word;
+        if (widthOf(joined) <= maxW) {
+            current = joined;
+            continue;
+        }
+        if (current.length === 0)
+            return null; // single word wider than the box
+        out.push(current);
+        current = word;
+        if (widthOf(current) > maxW)
+            return null;
+    }
+    if (current.length > 0)
+        out.push(current);
+    return out.length > 0 ? out : null;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Pack theme for @m0saic/story — single dark preset, structured for
+ * extension (mirrors hero/ffmpeg-pulse/_shared/pulse-theme.ts). All brand
+ * colors flow from story.json's `brand` block; anything invalid falls back
+ * to the preset so a hostile manifest can't push garbage at ffmpeg.
+ */
+import type { MosaicColor } from "@m0saic/types";
+import type { StoryDocument } from "./props";
+export type StoryTheme = {
+    /** Canvas / letterbox fill (story.brand.backgroundColor). */
+    canvas: MosaicColor;
+    /** Card-scene panel wash — slightly lifted from the canvas. */
+    card: MosaicColor;
+    /** Headline ink (story.brand.textColor). */
+    ink: MosaicColor;
+    /** Subtitle / kicker ink. */
+    muted: MosaicColor;
+    /** Brand accent (story.brand.accentColor) — bars, kickers. */
+    accent: MosaicColor;
+};
+export declare const STORY_PRESETS: Record<"dark", StoryTheme>;
+export type StoryPreset = keyof typeof STORY_PRESETS;
+export declare function storyTheme(preset?: StoryPreset): StoryTheme;
+/** Brand colors from the manifest, preset for anything absent or invalid. */
+export declare function themeFromStory(story: StoryDocument): StoryTheme;

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

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Pack theme for @m0saic/story — single dark preset, structured for
+ * extension (mirrors hero/ffmpeg-pulse/_shared/pulse-theme.ts). All brand
+ * colors flow from story.json's `brand` block; anything invalid falls back
+ * to the preset so a hostile manifest can't push garbage at ffmpeg.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORY_PRESETS = void 0;
+exports.storyTheme = storyTheme;
+exports.themeFromStory = themeFromStory;
+const types_1 = require("@m0saic/types");
+exports.STORY_PRESETS = {
+    dark: {
+        canvas: "#0d0f12",
+        card: "#14171c",
+        ink: "#f4f6f8",
+        muted: "#8b94a1",
+        accent: "#2f6df6",
+    },
+};
+function storyTheme(preset) {
+    return exports.STORY_PRESETS[preset !== null && preset !== void 0 ? preset : "dark"];
+}
+/** Brand colors from the manifest, preset for anything absent or invalid. */
+function themeFromStory(story) {
+    const base = storyTheme();
+    const brand = story.brand;
+    return {
+        ...base,
+        canvas: asColor(brand === null || brand === void 0 ? void 0 : brand.backgroundColor, base.canvas),
+        ink: asColor(brand === null || brand === void 0 ? void 0 : brand.textColor, base.ink),
+        accent: asColor(brand === null || brand === void 0 ? void 0 : brand.accentColor, base.accent),
+    };
+}
+function asColor(value, fallback) {
+    return (0, types_1.isMosaicColor)(value) ? value : fallback;
+}

package/dist/m0saic/story/scrapbook/v1/document.d.ts

@@ -0,0 +1,41 @@
+import type { MosaicDocument } from "@m0saic/types";
+import { type ScrapbookPlan } from "./pipeline";
+/**
+ * The whole film as ONE `mosaic_document` instead of a pipeline.
+ *
+ * NOT SHIPPED — blocked on an engine defect. Kept because it is correct
+ * apart from that, and becomes viable the moment the defect is fixed.
+ *
+ * THE BLOCKER. Stacking layers is only affordable if the engine can skip a
+ * layer's work while it is off screen, which is what `overlay.window` is
+ * for. But a `window` on a nested child that holds an svg TEXT source
+ * renders that text as a solid block of the font colour — repro and full
+ * findings in `.scratch/claude/repro-overlay-window-text.mosaic`. Without
+ * the window the text is correct and the render is unusable: six layers of
+ * a 19-second film did not finish in ten minutes at 640 square, because
+ * every layer renders the whole film. So the optimisation that makes this
+ * form affordable is the one that corrupts it.
+ *
+ * Why anyone would want this: a document keeps its geometry. It opens in
+ * Layout, so the tilt, the pacing and the words stay inspectable and
+ * re-editable long after the render — and a Community M piece must be a
+ * single document, so this is the form that can BE someone's canvas rather
+ * than a film of one.
+ *
+ * What it costs: a pipeline renders one step at a time, so a hundred pages
+ * cost the same per frame as two. Here every page is a layer that is alive
+ * for the whole runtime, gated by a time window, so cost grows with the
+ * page count and eventually the engine starts degrading rather than
+ * failing. Hence {@link DOCUMENT_MAX_PAGES} — the bad case is loud.
+ *
+ * Every layer shares the parent's clock, so each is told when its own time
+ * begins (`originSec`) and its internal drift and arrivals are offset to
+ * match. Cross-fades become overlapping alpha ramps: a layer holds until
+ * its span ends, then fades out across exactly the window the next one
+ * fades in.
+ */
+/** Past this the layer stack stops being worth it — use the pipeline. */
+export declare const DOCUMENT_MAX_PAGES = 12;
+export declare function buildScrapbookDocument(plan: ScrapbookPlan): MosaicDocument;
+/** `1`, `1{1}`, `1{1{1}}` … — one frame per source, nested as overlays. */
+export declare function nestedOverlays(count: number): string;

package/dist/m0saic/story/scrapbook/v1/document.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCUMENT_MAX_PAGES = void 0;
+exports.buildScrapbookDocument = buildScrapbookDocument;
+exports.nestedOverlays = nestedOverlays;
+const template_utils_1 = require("@m0saic/template-utils");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const page_1 = require("./page");
+const pipeline_1 = require("./pipeline");
+/**
+ * The whole film as ONE `mosaic_document` instead of a pipeline.
+ *
+ * NOT SHIPPED — blocked on an engine defect. Kept because it is correct
+ * apart from that, and becomes viable the moment the defect is fixed.
+ *
+ * THE BLOCKER. Stacking layers is only affordable if the engine can skip a
+ * layer's work while it is off screen, which is what `overlay.window` is
+ * for. But a `window` on a nested child that holds an svg TEXT source
+ * renders that text as a solid block of the font colour — repro and full
+ * findings in `.scratch/claude/repro-overlay-window-text.mosaic`. Without
+ * the window the text is correct and the render is unusable: six layers of
+ * a 19-second film did not finish in ten minutes at 640 square, because
+ * every layer renders the whole film. So the optimisation that makes this
+ * form affordable is the one that corrupts it.
+ *
+ * Why anyone would want this: a document keeps its geometry. It opens in
+ * Layout, so the tilt, the pacing and the words stay inspectable and
+ * re-editable long after the render — and a Community M piece must be a
+ * single document, so this is the form that can BE someone's canvas rather
+ * than a film of one.
+ *
+ * What it costs: a pipeline renders one step at a time, so a hundred pages
+ * cost the same per frame as two. Here every page is a layer that is alive
+ * for the whole runtime, gated by a time window, so cost grows with the
+ * page count and eventually the engine starts degrading rather than
+ * failing. Hence {@link DOCUMENT_MAX_PAGES} — the bad case is loud.
+ *
+ * Every layer shares the parent's clock, so each is told when its own time
+ * begins (`originSec`) and its internal drift and arrivals are offset to
+ * match. Cross-fades become overlapping alpha ramps: a layer holds until
+ * its span ends, then fades out across exactly the window the next one
+ * fades in.
+ */
+/** Past this the layer stack stops being worth it — use the pipeline. */
+exports.DOCUMENT_MAX_PAGES = 12;
+function buildScrapbookDocument(plan) {
+    const { width: W, height: H, fps, props: p, pages } = plan;
+    const x = Math.round(p.xfadeMs);
+    const openMs = Math.round(p.introMs);
+    const pageMs = Math.round(p.perPageMs);
+    const closeMs = Math.round(p.outroMs);
+    const totalMs = openMs + pageMs * pages.length + closeMs;
+    const sec = (ms) => ms / 1000;
+    // Children run the parent's full length: their animation is written in
+    // absolute time, and the alpha window is what decides when they are seen.
+    const layers = [];
+    let at = 0;
+    if (openMs > 0) {
+        layers.push({
+            doc: (0, pipeline_1.cardDoc)({ width: W, height: H, fps, durationMs: totalMs, props: p, headline: p.title, sub: p.subtitle, headlineProp: "title", originSec: sec(at), entrances: false }),
+            startMs: at,
+            visibleMs: openMs,
+        });
+        at += openMs;
+    }
+    for (const page of pages) {
+        layers.push({
+            doc: (0, page_1.buildPageDoc)({ page, width: W, height: H, fps, durationMs: totalMs, props: p, originSec: sec(at), entrances: false }),
+            startMs: at,
+            visibleMs: pageMs,
+        });
+        at += pageMs;
+    }
+    if (closeMs > 0) {
+        layers.push({
+            doc: (0, pipeline_1.cardDoc)({ width: W, height: H, fps, durationMs: totalMs, props: p, headline: p.closing, sub: "", headlineProp: "closing", originSec: sec(at), entrances: false }),
+            startMs: at,
+            visibleMs: closeMs,
+        });
+    }
+    const children = {};
+    const sources = [{ type: "lavfi", color: p.paperColor }];
+    layers.forEach((layer, i) => {
+        const ref = `layer${i}`;
+        children[ref] = layer.doc;
+        const s = sec(layer.startMs);
+        const e = sec(layer.startMs + layer.visibleMs);
+        const f = sec(x);
+        const first = i === 0;
+        const last = i === layers.length - 1;
+        // Hold, then hand over across exactly the window the next one arrives in.
+        const keys = [
+            ...(first ? [] : [{ t: s, v: 0 }, { t: s + f, v: 1 }]),
+            ...(last ? [{ t: e, v: 1 }] : [{ t: e, v: 1 }, { t: e + f, v: 0 }]),
+        ];
+        // Alpha ONLY. A structured `overlay.window` here would let the engine
+        // skip each layer off-window, but a window on a nested child that holds
+        // an svg TEXT source renders that text as a solid block of the font
+        // colour (repro: `.scratch/claude/repro-overlay-window-text.mosaic`).
+        // So every layer runs the whole film — which is exactly the cost
+        // DOCUMENT_MAX_PAGES exists to bound.
+        sources.push({ type: "mosaic", ref, overlay: { alpha: (0, template_utils_1.keyframeExpr)(keys) } });
+    });
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        // One base plus a layer each, nested — the depth IS the layer count.
+        m0: (0, dsl_stdlib_1.toM0String)(nestedOverlays(sources.length), "Scrapbook-document"),
+        size: { width: W, height: H },
+        fps,
+        durationMs: totalMs,
+        backgroundColor: p.paperColor,
+        audio: { mode: "off" },
+        assets: {},
+        children,
+        sources,
+    };
+}
+/** `1`, `1{1}`, `1{1{1}}` … — one frame per source, nested as overlays. */
+function nestedOverlays(count) {
+    if (count <= 1)
+        return "1";
+    return `1{${nestedOverlays(count - 1)}}`;
+}

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

@@ -0,0 +1 @@
+export { ScrapbookV1, default } from "./scrapbook";

package/dist/m0saic/story/scrapbook/v1/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.ScrapbookV1 = void 0;
+var scrapbook_1 = require("./scrapbook");
+Object.defineProperty(exports, "ScrapbookV1", { enumerable: true, get: function () { return scrapbook_1.ScrapbookV1; } });
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(scrapbook_1).default; } });

package/dist/m0saic/story/scrapbook/v1/page.d.ts

@@ -0,0 +1,34 @@
+import type { MosaicDocument } from "@m0saic/types";
+import type { Page } from "./pages";
+import type { ResolvedProps } from "./props";
+/** Alternating tilt, so consecutive pages do not lean the same way. */
+export declare function tiltFor(index: number, tilt: number): number;
+export declare function buildPageDoc(o: {
+    page: Page;
+    width: number;
+    height: number;
+    fps: number;
+    durationMs: number;
+    props: ResolvedProps;
+    /**
+     * When the page's own time starts, in seconds of the PARENT clock.
+     *
+     * As a pipeline step a page owns its clock and this is 0. As one layer of
+     * a single document every layer shares the parent's clock, so the drift
+     * and the arriving note have to be told when their page begins — or every
+     * page animates at once, at the top of the film.
+     */
+    originSec?: number;
+    /**
+     * Whether the text arrives with its own entrance.
+     *
+     * FALSE as one layer of a single document. An svg text source carries its
+     * own alpha (the box around the glyphs is transparent), and an entrance
+     * overlay on top of that INSIDE a nested child replaces that alpha with
+     * the ramp — the box goes opaque and the line renders as a solid slab of
+     * the font colour. As a pipeline step, where the document owns its own
+     * clock, the same source is fine. In document mode the layer's own fade
+     * carries the arrival instead.
+     */
+    entrances?: boolean;
+}): MosaicDocument;

package/dist/m0saic/story/scrapbook/v1/page.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tiltFor = tiltFor;
+exports.buildPageDoc = buildPageDoc;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+/**
+ * One page of the scrapbook: a picture pinned slightly off square on paper,
+ * with its line underneath.
+ *
+ * Two engine facts shape this:
+ *
+ *  - `effects.rotate` turns the content-fitted BUFFER, so a rotated source
+ *    clips against its own box. The headroom has to be real geometry, so the
+ *    picture lives in a child sized to the whole cell with the picture inset
+ *    inside it — the empty margin is what the corners swing into. The child's
+ *    ground is the SAME paper as the page, so the rotated rectangle is
+ *    invisible and only the picture reads as tilted.
+ *  - The drift is a camera on that child (zoom easing outward over the hold),
+ *    not a resize: the picture keeps its native pixels and the move is
+ *    resolution-independent.
+ */
+/** The picture's share of the page's height; the rest is the note. */
+const PICTURE_ROWS = 7;
+const NOTE_ROWS = 2;
+/** The print's side, as a share of the picture band — the rest is paper. */
+const PRINT_SHARE = 0.9;
+/** The white mount around the picture, as a share of the print. */
+const MOUNT = 0.055;
+/** Alternating tilt, so consecutive pages do not lean the same way. */
+function tiltFor(index, tilt) {
+    if (tilt <= 0)
+        return 0;
+    const lean = index % 2 === 0 ? 1 : -1;
+    // A third of a degree of variation so it never looks mechanical.
+    const jitter = ((index * 37) % 7) / 7 - 0.5;
+    return Number((lean * tilt * (0.75 + jitter * 0.5)).toFixed(3));
+}
+function buildPageDoc(o) {
+    var _a;
+    const { page, width: W, height: H, fps, durationMs, props: p } = o;
+    const t0 = (_a = o.originSec) !== null && _a !== void 0 ? _a : 0;
+    const rows = PICTURE_ROWS + NOTE_ROWS;
+    const bandH = Math.round((H * PICTURE_ROWS) / rows);
+    const noteH = H - bandH;
+    const sec = durationMs / 1000;
+    const photoId = (0, types_1.asAssetId)(`photo_${page.index}`);
+    const printSide = Math.max(2, Math.round((bandH * PRINT_SHARE) / 2) * 2);
+    // The print: the picture on a white mount, the way a photograph is
+    // actually stuck into a book. A square mount takes portrait and landscape
+    // alike without either one dictating the page.
+    const print = {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)("1", `Scrapbook-print-${page.index}`),
+        size: { width: printSide, height: printSide },
+        fps,
+        durationMs,
+        backgroundColor: "#FBF8F1",
+        audio: { mode: "off" },
+        assets: {
+            [photoId]: page.image.kind === "file"
+                ? { kind: "file", path: page.image.path, mediaType: "image" }
+                : { kind: "data-uri", uri: page.image.uri, mediaType: "image" },
+        },
+        sources: [
+            { type: "media", mediaType: "image", assetId: photoId, placement: { fit: "contain", inset: MOUNT } },
+        ],
+    };
+    // The band the print is pinned to. `effects.rotate` turns the content
+    // BUFFER, so a rotated print would clip its own corners — the headroom
+    // has to be real geometry. This band is cell-sized with the print inset
+    // inside it, and its ground is the SAME paper as the page, so the band's
+    // own rotation is invisible and only the print reads as tilted.
+    const band = {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)("1", `Scrapbook-band-${page.index}`),
+        size: { width: W, height: bandH },
+        fps,
+        durationMs,
+        backgroundColor: p.paperColor,
+        audio: { mode: "off" },
+        assets: {},
+        children: { print },
+        sources: [{ type: "mosaic", ref: "print", placement: { fit: "contain" } }],
+    };
+    // The drift: the camera eases outward across the hold. Small on purpose —
+    // a scrapbook breathes, it does not zoom.
+    const camera = p.drift > 0
+        ? { zoom: (0, template_utils_1.keyframeExpr)([{ t: t0, v: 1 + p.drift * 0.1 }, { t: t0 + sec, v: 1 }]), focusX: 0.5, focusY: 0.45 }
+        : undefined;
+    const rotate = tiltFor(page.index, p.tilt);
+    const effects = { ...(rotate !== 0 ? { rotate } : {}), ...(camera ? { camera } : {}) };
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.weightedSplit)([PICTURE_ROWS, NOTE_ROWS], "row", { precision: rows }),
+        size: { width: W, height: H },
+        fps,
+        durationMs,
+        backgroundColor: p.paperColor,
+        audio: { mode: "off" },
+        assets: {},
+        children: { band },
+        sources: [
+            { type: "mosaic", ref: "band", ...(Object.keys(effects).length ? { effects } : {}) },
+            // The line lands after the picture has settled — and it IS `notes[i]`,
+            // so it can be written straight onto the page it belongs to.
+            (0, template_utils_1.bindProp)({
+                ...(0, template_utils_1.svgLabel)(page.note, W, noteH, {
+                    color: p.inkColor,
+                    maxPx: Math.round(noteH * 0.3),
+                    maxLines: 2,
+                }),
+                ...(o.entrances === false ? {} : { overlay: (0, template_utils_1.entrance)({ kind: "rise", durationMs: 620, atSec: t0 + 0.35, ease: "easeOut" }) }),
+            }, "notes", page.index),
+        ],
+    };
+}

package/dist/m0saic/story/scrapbook/v1/pages.d.ts

@@ -0,0 +1,29 @@
+import type { ClaimImageLike } from "./placeholder";
+import type { ResolvedProps } from "./props";
+/**
+ * What the film is actually made of: an ordered list of pages, each a
+ * picture and (maybe) a line about it.
+ *
+ * The two props are index-aligned lists rather than a list of objects
+ * because that is what the editor can bind: a note is `notes[i]`, editable
+ * in place on the page it belongs to. It also means either can arrive
+ * first — write the words before the pictures exist, or the other way.
+ */
+export type Page = {
+    index: number;
+    /** The picture: a file the author supplied, or a generated stand-in. */
+    image: ClaimImageLike;
+    /** The line under it. Empty = a wordless page, which is allowed. */
+    note: string;
+    /** True when nothing real backs this page yet. */
+    standIn: boolean;
+};
+/** How many pages to lay out when no pictures have arrived yet. */
+export declare const STAND_IN_PAGES = 4;
+/**
+ * Resolve pages from the props. With no photos the film is laid out with
+ * stand-ins so its pacing can be judged before any real picture exists;
+ * with photos, the count follows the photos and the notes fill in beside
+ * them (a missing note is a wordless page, never an error).
+ */
+export declare function resolvePages(p: ResolvedProps): Page[];