@m0saic/templates 0.2.0

package/dist/m0saic/brand/community-m/v1/preview.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREVIEW_PIECE_LONG_MS = exports.PREVIEW_PIECE_MS = void 0;
+exports.standInPhoto = standInPhoto;
+exports.simulatedClaims = simulatedClaims;
+exports.previewTileLine = previewTileLine;
+exports.previewPiece = previewPiece;
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const platform_1 = require("@m0saic/platform");
+const caption_1 = require("./caption");
+/** One tile's stand-in, as a data-uri image the engine rasterizes (same path as the claimed edges). */
+function standInPhoto(tileIndex, o) {
+    return {
+        // The shared bank builds the data URL — one form, read by both the DOM
+        // and the render engine's plain-SVG parser.
+        image: { kind: "data-uri", uri: (0, platform_1.placeholderArtUrl)(tileIndex, o.style, o.seed, o.logoShare) },
+        size: { ...platform_1.PLACEHOLDER_ART_SIZE },
+        focus: (0, platform_1.placeholderArtFocus)(tileIndex, o.style, o.seed, o.logoShare),
+    };
+}
+function standInClaim(tileIndex, o) {
+    const p = standInPhoto(tileIndex, o);
+    return { image: p.image, focus: { ...p.focus, zoom: 1 } };
+}
+/**
+ * Stand-ins for open tiles, dealt in the M's own claim order (so a
+ * half-full preview scatters exactly the way the real M will fill). Real
+ * claims are never overwritten; the subject tile is always included so
+ * `previewTile` can point anywhere.
+ */
+function simulatedClaims(entry, real, o) {
+    const out = new Map();
+    if (o.claims <= 0 && o.tile === null)
+        return out;
+    if (o.claims > 0) {
+        let filled = real.size;
+        for (const tileIndex of entry.claimOrder) {
+            if (filled >= o.claims)
+                break;
+            if (real.has(tileIndex) || out.has(tileIndex))
+                continue;
+            out.set(tileIndex, standInClaim(tileIndex, o));
+            filled++;
+        }
+    }
+    if (o.tile !== null && !real.has(o.tile) && !out.has(o.tile))
+        out.set(o.tile, standInClaim(o.tile, o));
+    return out;
+}
+/**
+ * "tile 20 - claim 1 of 32 - preview stand-in - mixed, unclaimed" — the real
+ * line's shape (`tileLine`), with the award number the lever was set by;
+ * without a claim number (the resolved slot, or the root) just the tile.
+ */
+function previewTileLine(tileIndex, style, claimNo = null, capacity = 32) {
+    const which = claimNo === null ? "" : ` - claim ${claimNo} of ${capacity}`;
+    return `tile ${tileIndex}${which} - preview stand-in - ${style === "logos" ? "logo" : style === "faces" ? "avatar" : "mixed"}, unclaimed`;
+}
+const PIECE_SIZES = {
+    "16:9": { width: 1920, height: 1080 },
+    "1:1": { width: 1080, height: 1080 },
+    "9:16": { width: 1080, height: 1920 },
+};
+/** Stand-in canvas duration — long enough to read, short enough to iterate. */
+exports.PREVIEW_PIECE_MS = 4000;
+/** The moving samples need room to actually move. */
+exports.PREVIEW_PIECE_LONG_MS = 6000;
+const LOREM_BODY = "Consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
+/** Sample palette — the accent plus four that sit beside it without fighting. */
+const PALETTE = ["#f97316", "#38bdf8", "#a78bfa", "#34d399", "#fbbf24"];
+/** One beat of the `reel` sample: an eyebrow over a headline, on its own. */
+function beatCard(W, H, o, eyebrow, headline, index) {
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.weightedSplit)([2, 5], "row", { precision: 7 }),
+        size: { width: W, height: H },
+        fps: o.fps,
+        durationMs: exports.PREVIEW_PIECE_LONG_MS,
+        backgroundColor: (index % 2 === 0 ? o.canvasColor : "#141a26"),
+        audio: { mode: "off" },
+        assets: {},
+        sources: [
+            (0, template_utils_1.svgLabel)((0, caption_1.asciiSafe)(eyebrow), W, Math.round((H * 2) / 7), { color: o.accentColor, maxPx: Math.round(H * 0.07), maxLines: 1 }),
+            (0, template_utils_1.svgLabel)((0, caption_1.asciiSafe)(headline), W, Math.round((H * 5) / 7), { color: o.textColor, maxPx: Math.round(H * 0.16), maxLines: 2 }),
+        ],
+    };
+}
+/**
+ * A generated contributor canvas: something designed-looking in the piece
+ * beat while the real one does not exist yet. Declares its own size (the
+ * aspect knob covers the portrait case the harness has to survive) and
+ * carries no assets, so it costs nothing to render.
+ */
+function previewPiece(o) {
+    const size = PIECE_SIZES[o.aspect];
+    const { width: W, height: H } = size;
+    const text = (s, rows, total, color, weight = 0.6) => (0, template_utils_1.svgLabel)((0, caption_1.asciiSafe)(s), W, Math.round((H * rows) / total), { color: color, maxPx: Math.round(((H * rows) / total) * weight), maxLines: rows > 2 ? 3 : 1 });
+    let m0;
+    let sources;
+    let children;
+    const long = o.style === "reel" || o.style === "grid";
+    const durationMs = long ? exports.PREVIEW_PIECE_LONG_MS : exports.PREVIEW_PIECE_MS;
+    const end = durationMs / 1000;
+    if (o.style === "bars") {
+        // A flat colour band — a busy, wordless canvas to read the harness against.
+        m0 = (0, dsl_stdlib_1.weightedSplit)([1, 1, 1, 1, 1], "col");
+        sources = PALETTE.map((c) => ({ type: "lavfi", color: c }));
+    }
+    else if (o.style === "card") {
+        // A stat card: label, a big number, a sublabel.
+        m0 = (0, dsl_stdlib_1.weightedSplit)([3, 6, 3], "row", { precision: 12 });
+        sources = [
+            text("CONTRIBUTORS", 3, 12, o.accentColor, 0.35),
+            text("1,284", 6, 12, o.textColor, 0.8),
+            text("+12% since last month", 3, 12, o.textColor, 0.3),
+        ];
+    }
+    else if (o.style === "reel") {
+        // Three beats in one canvas — the point of this sample is that a piece
+        // is a VIDEO, not a poster: each beat is its own nested card that fades
+        // in, holds and hands over. Complexity is welcome here.
+        const beats = [
+            ["THE CLAIM", "One tile, forever"],
+            ["THE WORK", "Your template, accepted"],
+            ["THE MARK", "You are in the M"],
+        ];
+        const span = end / beats.length;
+        children = {};
+        sources = [{ type: "lavfi", color: o.canvasColor }];
+        beats.forEach(([eyebrow, headline], i) => {
+            const ref = `beat${i}`;
+            children[ref] = beatCard(W, H, o, eyebrow, headline, i);
+            const t0 = i * span;
+            const fade = Math.min(0.45, span * 0.3);
+            const keys = [{ t: t0, v: 0 }, { t: t0 + fade, v: 1 }];
+            // Every beat but the last hands over; the last one holds to the end.
+            if (i < beats.length - 1)
+                keys.push({ t: t0 + span - fade, v: 1 }, { t: t0 + span, v: 0 });
+            sources.push({ type: "mosaic", ref, overlay: { alpha: (0, template_utils_1.keyframeExpr)(keys) } });
+        });
+        m0 = (0, dsl_stdlib_1.toM0String)("1{1{1{1}}}", "CommunityMV1-preview-reel");
+    }
+    else if (o.style === "grid") {
+        // A canvas that BUILDS itself: twelve cells landing on a stagger, then
+        // the line that names what was built. Density and rhythm, no assets.
+        // The cells are a CHILD so the parent has exactly two frames — a base
+        // and one overlay. (Cells + caption as siblings would make the caption
+        // the thirteenth cell; m0 counts frames, not intentions.)
+        const g = (0, dsl_stdlib_1.grid)({ rows: 3, cols: 4 });
+        const cells = 12;
+        const build = end * 0.6;
+        children = {
+            cells: {
+                kind: "mosaic_document",
+                version: 1,
+                m0: g.m0,
+                size: { width: W, height: H },
+                fps: o.fps,
+                durationMs,
+                backgroundColor: o.canvasColor,
+                audio: { mode: "off" },
+                assets: {},
+                sources: Array.from({ length: cells }, (_, i) => {
+                    const t0 = (i / cells) * build;
+                    return {
+                        type: "lavfi",
+                        color: PALETTE[i % PALETTE.length],
+                        overlay: { alpha: (0, template_utils_1.keyframeExpr)([{ t: t0, v: 0 }, { t: t0 + 0.35, v: 1 }]) },
+                    };
+                }),
+            },
+        };
+        sources = [
+            { type: "mosaic", ref: "cells" },
+            // The line lands once the grid is up.
+            {
+                ...(0, template_utils_1.svgLabel)((0, caption_1.asciiSafe)("thirty-three tiles, one mark"), W, Math.round(H * 0.2), {
+                    color: o.textColor,
+                    maxPx: Math.round(H * 0.11),
+                    maxLines: 2,
+                }),
+                placement: { fit: "contain", inset: { x: 0.06, y: 0.4 } },
+                overlay: { alpha: (0, template_utils_1.keyframeExpr)([{ t: build, v: 0 }, { t: build + 0.5, v: 1 }]) },
+            },
+        ];
+        m0 = (0, dsl_stdlib_1.toM0String)("1{1}", "CommunityMV1-preview-grid");
+    }
+    else {
+        // Lorem: eyebrow, headline, body, footer — the shape of most cards.
+        m0 = (0, dsl_stdlib_1.weightedSplit)([2, 4, 4, 2], "row", { precision: 12 });
+        sources = [
+            text("LOREM IPSUM", 2, 12, o.accentColor, 0.45),
+            text("Dolor sit amet, consectetur", 4, 12, o.textColor, 0.42),
+            text(LOREM_BODY, 4, 12, o.textColor, 0.22),
+            text("your canvas goes here", 2, 12, o.accentColor, 0.35),
+        ];
+    }
+    const doc = {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)(m0, "CommunityMV1-preview-piece"),
+        size,
+        fps: o.fps,
+        durationMs,
+        backgroundColor: o.canvasColor,
+        audio: { mode: "off" },
+        assets: {},
+        ...(children ? { children } : {}),
+        sources,
+    };
+    return { doc, declaredMs: durationMs, size };
+}

package/dist/m0saic/brand/community-m/v1/props.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `@m0saic/brand/community-m/v1` — props.
+ *
+ * The provenance video for one Community M tile: the M with its identity,
+ * a zoom into the tile, the tile's original image revealed, the
+ * contributor's own canvas (their `.mosaic` piece), then back out to the M
+ * and the brand closer. m0saic owns the harness; the piece is theirs.
+ *
+ * Every knob has a deterministic default or a placeholder (the
+ * `defaultProps` convention), and no default is a local path
+ * (`noLocalPaths`): `communityDir` defaults to `""` = the bundled seed; the
+ * host pre-fills the real cache path when it exists.
+ */
+export type CommunityMProvenanceProps = {
+    /** Community M id, e.g. "001". */
+    m?: string;
+    /** Which tile: a 1-based claim number ("7"), "root", or a handle ("@octocat"). */
+    tile?: string;
+    /** Local checkout / cache of the community-m repo. "" = the bundled seed. */
+    communityDir?: string;
+    /** Show the M as it stands now, or as it stood when this tile was claimed. */
+    asOf?: "now" | "claim";
+    /** Hold on the whole M before the zoom (ms). */
+    introMs?: number;
+    /** Zoom travel into the tile (ms). */
+    zoomMs?: number;
+    /** Hold on the zoomed tile (ms). */
+    holdMs?: number;
+    /** Reveal: the M fades out while the original image fades in (ms). */
+    revealMs?: number;
+    /** Slide: the original glides aside to make room for the canvas (ms); the same slide brings it back. */
+    slideMs?: number;
+    /** Pop: the contributor canvas scales into place (ms). */
+    popMs?: number;
+    /** Cap on the contributor piece's declared duration (ms). */
+    pieceMaxMs?: number;
+    /** Outro: zoom back out to the whole M (ms). */
+    outroMs?: number;
+    /** Brand closer beat (ms). 0 = no closer. */
+    closerMs?: number;
+    /** Crossfade between beats (ms). */
+    xfadeMs?: number;
+    /** Camera zoom into the tile. Unset = auto (the tile fills the frame's tighter axis). */
+    zoom?: number;
+    /** Accent (claimed edges, captions). */
+    accentColor?: string;
+    /** Dormant tile colour. */
+    dormantColor?: string;
+    /** Canvas colour behind everything. */
+    canvasColor?: string;
+    /** Caption text colour. */
+    textColor?: string;
+    /**
+     * Dev levers — design the harness before the M fills up. Off by default;
+     * see `preview.ts`.
+     */
+    preview?: {
+        /** Paint this many tiles as claimed using stand-in art. 0 = only real claims. */
+        claims?: number;
+        /** Which stand-in family fills open tiles. */
+        style?: "faces" | "logos" | "mix";
+        /** Re-deal the stand-in art. */
+        seed?: number;
+        /** Share of a mix that is logos rather than faces (0..1). */
+        mix?: number;
+        /**
+         * Make the video about claim N in the M's award order (1..32 — the order
+         * the Community page lists open tiles in, and the order "claims" deals
+         * stand-ins in); 0 = the root. Unset = the resolved slot.
+         */
+        tile?: number;
+        /** Replace the contributor piece with a generated card. */
+        piece?: "off" | "lorem" | "card" | "bars" | "reel" | "grid";
+        /** Shape of that generated card. */
+        aspect?: "16:9" | "1:1" | "9:16";
+    };
+};
+export declare const DEFAULT_PROPS: Required<Omit<CommunityMProvenanceProps, "zoom">>;
+export declare const propsSchema: Record<keyof CommunityMProvenanceProps, import("@m0saic/types").MosaicTemplatePropDefinition>;
+export type ResolvedPreview = {
+    claims: number;
+    style: "faces" | "logos" | "mix";
+    seed: number;
+    logoShare: number;
+    /** null = the video is about the tile the slot resolves to. */
+    tile: number | null;
+    piece: "off" | "lorem" | "card" | "bars" | "reel" | "grid";
+    pieceAspect: "16:9" | "1:1" | "9:16";
+};
+export type ResolvedProps = Required<Omit<CommunityMProvenanceProps, "zoom" | "preview">> & {
+    zoom: number | null;
+    preview: ResolvedPreview;
+};
+/** Merge defaults + fail-fast validation. Returns a list of problems when invalid. */
+export declare function resolveProps(props: CommunityMProvenanceProps): {
+    ok: true;
+    value: ResolvedProps;
+} | {
+    ok: false;
+    errors: string[];
+};

package/dist/m0saic/brand/community-m/v1/props.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.propsSchema = exports.DEFAULT_PROPS = void 0;
+exports.resolveProps = resolveProps;
+const template_utils_1 = require("@m0saic/template-utils");
+exports.DEFAULT_PROPS = {
+    m: "001",
+    tile: "root",
+    communityDir: "",
+    asOf: "now",
+    introMs: 2400,
+    zoomMs: 1800,
+    holdMs: 600,
+    revealMs: 2000,
+    slideMs: 900,
+    popMs: 450,
+    pieceMaxMs: 18000,
+    outroMs: 2000,
+    closerMs: 2500,
+    xfadeMs: 500,
+    accentColor: "#f97316",
+    dormantColor: "#34343A",
+    canvasColor: "#0E1220",
+    textColor: "#F4F4F5",
+    preview: { claims: 0, style: "mix", seed: 1, mix: 0.34, piece: "off", aspect: "16:9" },
+};
+exports.propsSchema = (0, template_utils_1.definePropsSchema)({
+    m: {
+        type: "string",
+        required: false,
+        description: "Community M id (three digits), e.g. 001.",
+        meta: { ui: { label: "Community M", order: 1 } },
+    },
+    tile: {
+        type: "string",
+        required: false,
+        description: 'Which tile the video is about: a claim number ("7"), "root" for the root award, or a GitHub handle ("@octocat").',
+        meta: { ui: { label: "Tile", order: 2 } },
+    },
+    communityDir: {
+        type: "string",
+        required: false,
+        description: "Folder holding the community-m repo (its index.json). Leave empty for the bundled seed; Mosaic Desktop and the CLI fill in the local cache automatically.",
+        meta: { control: { picker: "folder", placeholder: "bundled seed" }, ui: { label: "community-m folder", order: 3 } },
+    },
+    asOf: {
+        type: "string",
+        required: false,
+        description: "Show the M as it stands now (re-renders age into the record) or as it stood when this tile was claimed.",
+        meta: { constraints: { oneOf: ["now", "claim"] }, control: { options: [{ value: "now", label: "As it is now" }, { value: "claim", label: "As it was when claimed" }] }, ui: { label: "M as of", order: 4 } },
+    },
+    introMs: { type: "number", required: false, description: "Hold on the whole M before the zoom (ms).", meta: { constraints: { min: 200, max: 15000 }, ui: { label: "Intro hold" } } },
+    zoomMs: { type: "number", required: false, description: "Zoom travel into the tile (ms).", meta: { constraints: { min: 200, max: 10000 }, ui: { label: "Zoom" } } },
+    holdMs: { type: "number", required: false, description: "Hold on the zoomed tile (ms).", meta: { constraints: { min: 0, max: 10000 }, ui: { label: "Tile hold" } } },
+    revealMs: { type: "number", required: false, description: "The M fades out while the tile's original image fades in (ms).", meta: { constraints: { min: 400, max: 10000 }, ui: { label: "Reveal" } } },
+    slideMs: { type: "number", required: false, description: "The original slides aside for the canvas, and back again at the end (ms).", meta: { constraints: { min: 200, max: 5000 }, ui: { label: "Slide aside" } } },
+    popMs: { type: "number", required: false, description: "The contributor canvas pops into place (ms).", meta: { constraints: { min: 100, max: 3000 }, ui: { label: "Canvas pop" } } },
+    pieceMaxMs: { type: "number", required: false, description: "Longest the contributor piece may play (ms); shorter pieces play their declared length.", meta: { constraints: { min: 500, max: 60000 }, ui: { label: "Piece cap" } } },
+    outroMs: { type: "number", required: false, description: "Zoom back out to the whole M (ms).", meta: { constraints: { min: 200, max: 10000 }, ui: { label: "Outro" } } },
+    closerMs: { type: "number", required: false, description: "Brand closer at the end (ms). 0 removes it.", meta: { constraints: { min: 0, max: 10000 }, ui: { label: "Closer" } } },
+    xfadeMs: { type: "number", required: false, description: "Crossfade between beats (ms).", meta: { constraints: { min: 0, max: 2000 }, ui: { label: "Crossfade" } } },
+    zoom: {
+        type: "number",
+        required: false,
+        description: "Camera zoom into the tile (1–4). Unset = auto: the tile fills the frame's tighter axis, capped at 4.",
+        meta: { constraints: { min: 1, max: 4 }, control: { placeholder: "auto (fit the tile)" }, ui: { label: "Camera zoom" } },
+    },
+    accentColor: { type: "string", required: false, description: "Accent colour: claimed-tile edges and captions.", meta: { ui: { label: "Accent color" }, constraints: { isColor: true }, control: { colorPicker: true } } },
+    dormantColor: { type: "string", required: false, description: "Colour of open (unclaimed) tiles.", meta: { ui: { label: "Open tile color" }, constraints: { isColor: true }, control: { colorPicker: true } } },
+    canvasColor: { type: "string", required: false, description: "Canvas behind the M and the piece.", meta: { ui: { label: "Canvas color" }, constraints: { isColor: true }, control: { colorPicker: true } } },
+    textColor: { type: "string", required: false, description: "Caption text colour.", meta: { ui: { label: "Caption color" }, constraints: { isColor: true }, control: { colorPicker: true } } },
+    preview: {
+        type: "group",
+        required: false,
+        description: "Dev levers: stand in art for open tiles, point the video at any tile, and swap the contributor piece for a generated card — so the harness can be designed before real claims exist. All off by default.",
+        meta: { ui: { label: "Dev preview", order: 20, collapsedByDefault: true } },
+        fields: {
+            claims: { type: "number", required: false, description: "Paint this many tiles as claimed using stand-in art (the same bank the Community page previews with), dealt in the M's own claim order. 0 = only real claims.", meta: { constraints: { min: 0, max: 33 }, ui: { label: "Filled tiles" } } },
+            style: {
+                type: "string", required: false, description: "Which stand-in family fills open tiles.",
+                meta: { constraints: { oneOf: ["faces", "logos", "mix"] }, control: { options: [{ value: "mix", label: "Mix" }, { value: "faces", label: "Faces" }, { value: "logos", label: "Logos" }] }, ui: { label: "Stand-ins" } },
+            },
+            seed: { type: "number", required: false, description: "Re-deal the stand-in art (shuffle).", meta: { constraints: { min: 1, max: 9999 }, ui: { label: "Shuffle" } } },
+            mix: { type: "number", required: false, description: "Share of a mix that is logos rather than faces.", meta: { constraints: { min: 0, max: 1 }, ui: { label: "Logo share" } } },
+            tile: { type: "number", required: false, description: "Make the video about claim N in the M's award order (1..32 — the same order the Community page lists open tiles in, and the order Filled tiles deals stand-ins in) with stand-in art; 0 = the root. The way to exercise the zoom and crop on a wide, tall or diagonal tile instead of the root's V. Unset = the tile the slot resolves to.", meta: { constraints: { min: 0, max: 32 }, control: { placeholder: "the resolved tile" }, ui: { label: "Subject tile (claim #)" } } },
+            piece: {
+                type: "string", required: false, description: "Replace the contributor piece with a generated card, so the canvas beat has something in it before a real .mosaic exists.",
+                meta: {
+                    constraints: { oneOf: ["off", "lorem", "card", "bars", "reel", "grid"] },
+                    control: {
+                        options: [
+                            { value: "off", label: "Real piece" },
+                            { value: "lorem", label: "Lorem card" },
+                            { value: "card", label: "Stat card" },
+                            { value: "bars", label: "Colour bars" },
+                            { value: "reel", label: "Reel (3 beats)" },
+                            { value: "grid", label: "Grid (builds in)" },
+                        ],
+                    },
+                    ui: { label: "Canvas" },
+                },
+            },
+            aspect: {
+                type: "string", required: false, description: "Shape of that generated card — the portrait option is the one the harness has to survive.",
+                meta: { constraints: { oneOf: ["16:9", "1:1", "9:16"] }, control: { options: [{ value: "16:9", label: "Landscape 16:9" }, { value: "1:1", label: "Square" }, { value: "9:16", label: "Portrait 9:16" }] }, ui: { label: "Canvas shape" } },
+            },
+        },
+    },
+});
+/** Merge defaults + fail-fast validation. Returns a list of problems when invalid. */
+function resolveProps(props) {
+    var _a, _b, _c, _d;
+    const d = exports.DEFAULT_PROPS.preview;
+    const pv = { ...d, ...stripUndefined((_a = props.preview) !== null && _a !== void 0 ? _a : {}) };
+    const preview = {
+        claims: pv.claims,
+        style: pv.style,
+        seed: pv.seed,
+        logoShare: pv.mix,
+        tile: (_c = (_b = props.preview) === null || _b === void 0 ? void 0 : _b.tile) !== null && _c !== void 0 ? _c : null,
+        piece: pv.piece,
+        pieceAspect: pv.aspect,
+    };
+    const v = { ...exports.DEFAULT_PROPS, ...stripUndefined(props), zoom: (_d = props.zoom) !== null && _d !== void 0 ? _d : null, preview };
+    const errors = [];
+    if (!/^\d{3}$/.test(v.m))
+        errors.push(`m must be three digits (got "${v.m}")`);
+    if (typeof v.tile !== "string" || v.tile.trim() === "")
+        errors.push("tile is required");
+    if (v.asOf !== "now" && v.asOf !== "claim")
+        errors.push(`asOf must be "now" or "claim" (got "${String(v.asOf)}")`);
+    const num = (name, lo, hi) => {
+        const n = v[name];
+        if (!Number.isFinite(n) || n < lo || n > hi)
+            errors.push(`${name} must be ${lo}..${hi} ms (got ${String(n)})`);
+    };
+    num("introMs", 200, 15000);
+    num("zoomMs", 200, 10000);
+    num("holdMs", 0, 10000);
+    num("revealMs", 400, 10000);
+    num("slideMs", 200, 5000);
+    num("popMs", 100, 3000);
+    num("pieceMaxMs", 500, 60000);
+    num("outroMs", 200, 10000);
+    num("closerMs", 0, 10000);
+    num("xfadeMs", 0, 2000);
+    if (v.zoom !== null && !(Number.isFinite(v.zoom) && v.zoom >= 1 && v.zoom <= 4))
+        errors.push(`zoom must be 1..4 (got ${String(v.zoom)})`);
+    const rng = (name, n, lo, hi) => {
+        if (!Number.isFinite(n) || n < lo || n > hi)
+            errors.push(`preview.${name} must be ${lo}..${hi} (got ${String(n)})`);
+    };
+    rng("claims", preview.claims, 0, 33);
+    rng("seed", preview.seed, 1, 9999);
+    rng("mix", preview.logoShare, 0, 1);
+    if (preview.tile !== null && !(Number.isInteger(preview.tile) && preview.tile >= 0 && preview.tile <= 32))
+        errors.push(`preview.tile must be a claim number 1..32 in award order, or 0 for the root (got ${String(preview.tile)})`);
+    if (!["faces", "logos", "mix"].includes(preview.style))
+        errors.push(`preview.style must be faces, logos or mix (got "${String(preview.style)}")`);
+    if (!["off", "lorem", "card", "bars", "reel", "grid"].includes(preview.piece))
+        errors.push(`preview.piece must be off, lorem, card, bars, reel or grid (got "${String(preview.piece)}")`);
+    if (!["16:9", "1:1", "9:16"].includes(preview.pieceAspect))
+        errors.push(`preview.aspect must be 16:9, 1:1 or 9:16 (got "${String(preview.pieceAspect)}")`);
+    for (const c of ["accentColor", "dormantColor", "canvasColor", "textColor"]) {
+        if (!/^#[0-9a-fA-F]{6}$/.test(v[c]))
+            errors.push(`${c} must be #rrggbb (got "${v[c]}")`);
+    }
+    if (v.xfadeMs * 2 > Math.min(v.outroMs, v.pieceMaxMs))
+        errors.push("xfadeMs is too long for the outro / piece beats");
+    return errors.length ? { ok: false, errors } : { ok: true, value: v };
+}
+function stripUndefined(o) {
+    const out = {};
+    for (const k of Object.keys(o))
+        if (o[k] !== undefined)
+            out[k] = o[k];
+    return out;
+}

package/dist/m0saic/brand/community-m/v1/reveal.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The reveal's alignment math. The founder's rule: the un-clipped original
+ * must land EXACTLY where the tile's cover-crop sits once the camera is
+ * parked, so the crossfade reads as the mask dissolving — the face never
+ * moves. Everything here mirrors the engine byte for byte:
+ *   - cover crop (`coverCrop.ts`): scale = max(tileW/imgW, tileH/imgH),
+ *     crop offset = (scaled − tile) × focus;
+ *   - camera (`applyCamera.ts`): content scaled by Z, window top-left =
+ *     (box × (Z−1)) × focus, with `centerFocus` picking the focus that
+ *     centres the tile (clamped at the stage edge, like the engine).
+ */
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type ImageSize = {
+    width: number;
+    height: number;
+};
+export type AlignOptions = {
+    /** The tile in STAGE pixels (the camera's content box is the stage). */
+    tile: Rect;
+    stageW: number;
+    stageH: number;
+    zoom: number;
+    image: ImageSize;
+    focus: {
+        x: number;
+        y: number;
+    };
+};
+/** Where the tile's whole source image sits on the frame once the camera is parked at `zoom` (frame px, unrounded). */
+export declare function alignedPhotoRect(o: AlignOptions): Rect;
+/** Round a frame rect to whole pixels (even sides keep chroma happy). */
+export declare function roundRect(r: Rect): Rect;
+/**
+ * The largest zoom ≤ `maxZoom` at which the whole original fits inside the
+ * stage with `margin` px of air on every side (so the reveal can show all
+ * of it without moving). Monotone in Z → bisection; never below `minZoom`.
+ *
+ * Kept for callers that only need the stage fit; the provenance pipeline
+ * uses `zoomPartitionCap`, which adds the piece-beat partition.
+ */
+export declare function zoomFitCap(o: Omit<AlignOptions, "zoom"> & {
+    maxZoom: number;
+    minZoom?: number;
+    margin: number;
+}): number;
+/**
+ * THE PIECE-BEAT LAYOUT CONTRACT (founder, 2026-09-16): the parked original
+ * and the contributor canvas can NEVER overlap. Not "usually" — the frame is
+ * PARTITIONED on one axis, the piece gets exactly the remainder past a gap,
+ * and the zoom is chosen up front so that remainder is at least the
+ * legibility floor. There is no floor that can push the piece back under
+ * the photo (the old `max(0.3·W, remainder)` did exactly that whenever the
+ * parked photo was wide), and `assertPieceBeatDisjoint` re-checks the two
+ * rects before anything is placed — an impossible layout is an error
+ * mosaic, never a covered face. `reveal.test.ts` walks every tile × frame ×
+ * image aspect × focus × piece aspect and proves the cap always finds an
+ * axis.
+ *
+ *  - axis "x": photo parks at the left margin (pure horizontal slide — its
+ *    height and y never change), the piece takes the width to the right.
+ *  - axis "y": photo parks at the top margin (pure vertical slide — its x
+ *    and width never change), the piece takes the height below. The axis
+ *    that admits the LARGER zoom wins, so wide originals on wide frames
+ *    stay side by side and only go vertical when that shows more of them.
+ */
+export type PieceAxis = "x" | "y";
+export type PieceBeatBudget = {
+    margin: number;
+    gap: number;
+    /** The piece's area on the partition axis is never smaller than this. */
+    pieceMinW: number;
+    pieceMinH: number;
+    /** The parked photo may be at most this wide (axis x) / tall (axis y). */
+    photoMaxW: number;
+    photoMaxH: number;
+};
+/** Margins, gap and floors for a frame: everything the partition needs. */
+export declare function pieceBeatBudget(frameW: number, frameH: number): PieceBeatBudget;
+/** Which axis a photo of this size can share the frame on; null = neither (the cap prevents this). */
+export declare function pieceAxisFor(photo: ImageSize, b: PieceBeatBudget): PieceAxis | null;
+/**
+ * The zoom for the whole reveal → piece → return arc: the largest Z ≤
+ * `maxZoom` at which the original (a) fits inside the stage with `margin`
+ * of air (the reveal shows all of it without moving) AND (b) leaves the
+ * piece its floor on SOME axis. Every photo dimension grows with Z, so both
+ * are monotone and the largest Z on the better axis is the answer. When the
+ * stage fit alone is impossible even at `minZoom` (a very tall original in
+ * a small tile) it is tolerated exactly as before — the original overflows
+ * the frame edge — but the partition is never given up: the pinned
+ * dimension is bounded by the tile, so an axis always exists.
+ */
+export declare function zoomPartitionCap(o: Omit<AlignOptions, "zoom"> & {
+    frameW: number;
+    frameH: number;
+    maxZoom: number;
+    minZoom?: number;
+    margin: number;
+}): number;
+export type PieceBeatLayout = {
+    axis: PieceAxis;
+    /** The photo during the piece beat: same size as `photo`, moved to the margin on `axis`. */
+    parked: Rect;
+    parkedX: number;
+    parkedY: number;
+    /** parked − photo: the slide (one of them is always 0). */
+    dx: number;
+    dy: number;
+    pieceRect: Rect;
+    gap: number;
+};
+/** Throws unless the two rects are separated by at least `gap` on the partition axis. */
+export declare function assertPieceBeatDisjoint(axis: PieceAxis, parked: Rect, piece: Rect, gap: number): void;
+/**
+ * The piece beat's geometry. The photo keeps its size; the piece is
+ * contain-fit into the remainder on the chosen axis. Throws when neither
+ * axis has room — which `zoomPartitionCap` makes unreachable; the throw is
+ * the contract, not a code path.
+ */
+export declare function pieceBeatLayout(o: {
+    frameW: number;
+    frameH: number;
+    photo: Rect;
+    piece: ImageSize;
+}): PieceBeatLayout;