@m0saic/templates 0.2.0

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

@@ -0,0 +1,461 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captionBandHeight = captionBandHeight;
+exports.frameLayout = frameLayout;
+exports.tileRectInStage = tileRectInStage;
+exports.resolveZoom = resolveZoom;
+exports.photoGeometry = photoGeometry;
+exports.buildIntroDoc = buildIntroDoc;
+exports.buildRevealDoc = buildRevealDoc;
+exports.buildPieceDoc = buildPieceDoc;
+exports.buildReturnDoc = buildReturnDoc;
+exports.buildOutroDoc = buildOutroDoc;
+exports.buildCloserDoc = buildCloserDoc;
+exports.buildProvenancePipeline = buildProvenancePipeline;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const camera_1 = require("./camera");
+const caption_1 = require("./caption");
+const geometry_1 = require("./geometry");
+const target_1 = require("./target");
+const mark_1 = require("./mark");
+const piece_1 = require("./piece");
+const reveal_1 = require("./reveal");
+const wordmark_1 = require("./wordmark");
+/** Slot ceiling for a frame split: past this the planner's px-per-weight floor bites. */
+const MAX_SPLIT_SLOTS = 64;
+function gcd(a, b) {
+    let x = Math.abs(a), y = Math.abs(b);
+    while (y) {
+        const t = x % y;
+        x = y;
+        y = t;
+    }
+    return x || 1;
+}
+/**
+ * Caption-band height: ~4.5 % of the frame, nudged to the value in that
+ * band that shares the LARGEST common factor with the frame height.
+ *
+ * Why not just round: the row split is expressed in slots, and feeding raw
+ * pixel counts in makes every frame a 2160-slot split — far past the
+ * planner's px-per-weight floor, where cells quantize and squash (the
+ * `safeMinimumCanvas` convention). Sharing a factor lets the same pixel
+ * boundaries be written as a couple of dozen slots instead.
+ * `gcd(capH, stageH) === gcd(capH, frameH)` because `stageH = frameH − 2·capH`.
+ */
+function captionBandHeight(frameH) {
+    const ideal = frameH * 0.045;
+    const lo = Math.max(20, Math.floor(frameH * 0.03));
+    const hi = Math.max(lo, Math.floor(frameH * 0.075));
+    let best = -1;
+    let bestDist = Infinity;
+    for (let c = lo; c <= hi; c++) {
+        if (frameH / gcd(c, frameH) > MAX_SPLIT_SLOTS)
+            continue; // exact: g divides frameH
+        const d = Math.abs(c - ideal);
+        if (d < bestDist) {
+            bestDist = d;
+            best = c;
+        }
+    }
+    // Nothing shares a factor (a prime frame height): fall back to raw pixels.
+    return best > 0 ? best : Math.max(20, Math.round(ideal));
+}
+/** Frame layout: the stage (the M, camera container) over two caption lines. */
+function frameLayout(frameW, frameH) {
+    const capH = captionBandHeight(frameH);
+    const stageH = frameH - 2 * capH;
+    const side = (0, geometry_1.markSideFor)(frameW, stageH, 0.97); // 4K: 7× = 1904; 720p: 2×; ≤360p: 1×
+    const markX = Math.floor((frameW - side) / 2);
+    const markY = Math.floor((stageH - side) / 2);
+    // Reduced weights: the same pixel boundaries in frameH/g slots, not frameH.
+    const g = gcd(capH, frameH);
+    const m0 = (0, dsl_stdlib_1.weightedSplit)([stageH / g, capH / g, capH / g], "row", { precision: frameH / g });
+    return { capH, stageH, side, markX, markY, m0 };
+}
+/** Where a tile sits inside the stage, in stage pixels. */
+function tileRectInStage(tileIndex, layout) {
+    const geo = (0, geometry_1.markGeometry)();
+    const r = geo.sourceRects[geo.tileToSource[tileIndex]];
+    const k = layout.side / 272;
+    return { x: layout.markX + r.x * k, y: layout.markY + r.y * k, width: r.width * k, height: r.height * k };
+}
+/** The community record: claimed tiles as their pictures with the orange edge, open tiles dormant. */
+function communityMarkDoc(plan, layout, durationMs) {
+    return (0, mark_1.buildMarkDoc)({
+        side: layout.side,
+        fps: plan.fps,
+        durationMs,
+        claims: plan.claims,
+        dormantColor: plan.props.dormantColor,
+        canvasColor: plan.props.canvasColor,
+        accentColor: plan.props.accentColor,
+        rootReserved: !plan.target.rootShown,
+    });
+}
+/**
+ * The stage: a frame-wide cell with an M (`mark`, side = `layout.side`)
+ * centred in it (own size → never resized by the parent). The same cell
+ * frames the community M in every beat and the brand logo in the closer, so
+ * the two dissolve into each other tile for tile.
+ */
+function stageDoc(plan, layout, durationMs, mark) {
+    const placed = (0, dsl_stdlib_1.placeRect)({ rootW: plan.frameW, rootH: layout.stageH, rectW: layout.side, rectH: layout.side });
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: placed.m0,
+        size: { width: plan.frameW, height: layout.stageH },
+        fps: plan.fps,
+        durationMs,
+        backgroundColor: plan.props.canvasColor,
+        audio: { mode: "off" },
+        assets: {},
+        children: { mark },
+        sources: [{ type: "mosaic", ref: "mark" }],
+    };
+}
+/**
+ * The brand field tint: the business card mixes NAVY → NAVY_SOFT at this
+ * share (`fieldOpacity`); here it is mixed over the video's canvas colour so
+ * a custom canvas keeps the same lift. Well under the dormant tile grey, so
+ * the M still reads as the figure.
+ */
+const FIELD_MIX = 0.28;
+/** The plate's hairline: the Home card's border, NAVY_SOFT mixed onto the surface at this share. */
+const PLATE_BORDER_MIX = 0.35;
+/** Plate air either side of the M, as a share of the M's side. */
+const PLATE_PAD = 0.08;
+/** Plate corner radius as a share of the frame's short side (the Home card's 2.8 %). */
+const PLATE_RADIUS = 0.028;
+/**
+ * The intro fades the field and plate out over this many seconds, ENDING as
+ * the dolly starts: a static ground under a zooming M reads as a mistake
+ * (founder, 2026-09-16), so the camera only ever moves over the clean canvas.
+ * Capped at half the hold so a short intro still shows the ground.
+ */
+const FIELD_FADE_SEC = 0.7;
+/**
+ * The brand field — the rect backdrop the Home screen and the business card
+ * sit on (`coverFitField`, transposed on portrait) — as one transparent
+ * child: every rect a tinted colour tile, nothing else painted. Under the
+ * first and last beats (founder, 2026-09-16) so the video opens and closes
+ * on the brand's own ground.
+ */
+function fieldDoc(plan, durationMs) {
+    const W = plan.frameW, H = plan.frameH;
+    const tint = (0, template_utils_1.mixHex)(plan.props.canvasColor, template_utils_1.NAVY_SOFT, FIELD_MIX);
+    const rects = (0, template_utils_1.coverFitField)(W, H, (0, template_utils_1.isPortraitField)(W, H));
+    const placed = (0, template_utils_1.placeInsetPieces)({
+        rootW: W,
+        rootH: H,
+        pieces: rects.map((r) => ({ rect: { ...r, importance: 0 }, source: (0, template_utils_1.tag)((0, template_utils_1.makeColorTile)(tint), "field") })),
+    });
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)(String(placed.m0), "CommunityMV1-field"),
+        size: { width: W, height: H },
+        fps: plan.fps,
+        durationMs,
+        audio: { mode: "off" },
+        assets: {},
+        sources: placed.sources,
+    };
+}
+/**
+ * The Home card's plate — the protective backdrop between the field and the
+ * content (founder, 2026-09-16): canvas-coloured, the card's hairline, the
+ * card's corner radius. A column the M's width plus air, the FULL frame
+ * height: at 4K the M already stands at 97 % of the stage, so there is no
+ * room for card air above it; a column reads the same at every size and
+ * keeps the captions on the plate too. The corners round off the frame's
+ * edges, so what shows is the two hairlines and calm ground.
+ */
+function plateRect(plan, layout) {
+    const pad = Math.round(layout.side * PLATE_PAD);
+    const x = Math.max(0, layout.markX - pad);
+    const right = Math.min(plan.frameW, layout.markX + layout.side + pad);
+    return { x, y: 0, width: right - x, height: plan.frameH };
+}
+function plateSource(plan, layout, alpha) {
+    const r = plateRect(plan, layout);
+    const at = layerAt(plan, r, alpha ? { alpha } : undefined);
+    const cardMin = Math.max(1, Math.min(r.width, r.height));
+    const radiusPx = Math.round(Math.min(plan.frameW, plan.frameH) * PLATE_RADIUS);
+    return (0, template_utils_1.tag)((0, template_utils_1.makeColorTile)(plan.props.canvasColor, {
+        placement: at.placement,
+        overlay: at.overlay,
+        effects: {
+            rounding: { cornerStyle: "rounded", borderRadius: Math.min(1, (2 * radiusPx) / cardMin) },
+            stroke: { width: 1.5 / cardMin, color: (0, template_utils_1.mixHex)(plan.props.canvasColor, template_utils_1.NAVY_SOFT, PLATE_BORDER_MIX) },
+        },
+    }), "plate");
+}
+/**
+ * A frame on the brand field: canvas colour, the field, the plate (both
+ * optionally fading together), then the rows layout as the top layer.
+ * Nested children paint no background (a plain `backgroundColor` on a child
+ * is transparent in the overlay path — verified 2026-09-16), so the field
+ * shows through the M's gaps and around the plate, exactly as the Home
+ * card sits on its field.
+ */
+function fieldedDoc(plan, layout, durationMs, children, rowSources, field) {
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)(`1{1{1{${layout.m0}}}}`, "CommunityMV1-fielded"),
+        size: { width: plan.frameW, height: plan.frameH },
+        fps: plan.fps,
+        durationMs,
+        backgroundColor: plan.props.canvasColor,
+        audio: { mode: "off" },
+        assets: {},
+        children: { field: fieldDoc(plan, durationMs), ...children },
+        sources: [
+            { type: "lavfi", color: plan.props.canvasColor },
+            { type: "mosaic", ref: "field", ...(field.alpha ? { overlay: { alpha: field.alpha } } : {}) },
+            plateSource(plan, layout, field.alpha),
+            ...rowSources,
+        ],
+    };
+}
+/** The framed M's row sources: the stage, then the two bound caption lines. */
+function framedSources(plan, layout, stageSource, line1, line2) {
+    return [
+        stageSource,
+        // The identity line shows `m`, the tile line shows `tile` — bound so
+        // Make can edit each in place (the `bindingsCover` convention).
+        (0, template_utils_1.bindProp)((0, caption_1.captionSource)(line1, plan.frameW, layout.capH, plan.props.textColor), "m"),
+        (0, template_utils_1.bindProp)((0, caption_1.captionSource)(line2, plan.frameW, layout.capH, plan.props.accentColor), "tile"),
+    ];
+}
+/**
+ * The framed M: stage row + two caption rows, at the full frame size. With
+ * `field` the frame sits on the brand field (the intro); without it the
+ * rows are the whole doc (reveal / return / outro — a clean canvas around
+ * the tile).
+ */
+function framedDoc(plan, layout, durationMs, stageSource, line1, line2, field) {
+    const children = { stage: stageDoc(plan, layout, durationMs, communityMarkDoc(plan, layout, durationMs)) };
+    const sources = framedSources(plan, layout, stageSource, line1, line2);
+    if (field)
+        return fieldedDoc(plan, layout, durationMs, children, sources, field);
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: layout.m0,
+        size: { width: plan.frameW, height: plan.frameH },
+        fps: plan.fps,
+        durationMs,
+        backgroundColor: plan.props.canvasColor,
+        audio: { mode: "off" },
+        assets: {},
+        children,
+        sources,
+    };
+}
+/** The framed M parked on the tile — the frame the reveal dissolves from and the return dissolves to. */
+function parkedFrameDoc(plan, g, durationMs) {
+    const camera = (0, camera_1.parkedCamera)({ tile: g.tile, stageW: plan.frameW, stageH: g.layout.stageH, zoom: g.zoom });
+    return framedDoc(plan, g.layout, durationMs, { type: "mosaic", ref: "stage", effects: { camera } }, (0, target_1.identityLine)(plan.target.entry), plan.tileCaption);
+}
+/**
+ * Zoom: the prop, else auto (the tile fills ~55 % of the tighter axis),
+ * then CAPPED so the whole original fits inside the stage with air — the
+ * reveal shows all of it without moving anything — AND so the piece beat
+ * can partition the frame (`zoomPartitionCap`): the parked original and
+ * the contributor canvas never share pixels. A `zoom` prop is a ceiling,
+ * not an override; the contract wins.
+ */
+function resolveZoom(plan, layout) {
+    var _a;
+    const tile = tileRectInStage(plan.tileIndex, layout);
+    const want = (_a = plan.props.zoom) !== null && _a !== void 0 ? _a : (0, camera_1.autoZoomForTile)(tile, plan.frameW, layout.stageH);
+    const margin = Math.round(layout.stageH * 0.04);
+    return (0, reveal_1.zoomPartitionCap)({ tile, stageW: plan.frameW, stageH: layout.stageH, frameW: plan.frameW, frameH: plan.frameH, image: plan.photo.size, focus: plan.photo.focus, maxZoom: want, margin });
+}
+/** All the reveal / slide / canvas geometry, computed once per render. */
+function photoGeometry(plan) {
+    const layout = frameLayout(plan.frameW, plan.frameH);
+    const tile = tileRectInStage(plan.tileIndex, layout);
+    const zoom = resolveZoom(plan, layout);
+    const aligned = (0, reveal_1.roundRect)((0, reveal_1.alignedPhotoRect)({ tile, stageW: plan.frameW, stageH: layout.stageH, zoom, image: plan.photo.size, focus: plan.photo.focus }));
+    const beat = (0, reveal_1.pieceBeatLayout)({ frameW: plan.frameW, frameH: plan.frameH, photo: aligned, piece: plan.piece.size });
+    return { layout, tile, zoom, aligned, parked: beat.parked, axis: beat.axis, dx: beat.dx, dy: beat.dy, pieceRect: beat.pieceRect };
+}
+function layerAt(plan, r, anim) {
+    const W = plan.frameW, H = plan.frameH;
+    const ix = (W - r.width) / 2 / W;
+    const iy = (H - r.height) / 2 / H;
+    const ox = r.x - Math.round(W * ix);
+    const oy = r.y - Math.round(H * iy);
+    const xExpr = (anim === null || anim === void 0 ? void 0 : anim.xKeys) ? (0, template_utils_1.keyframeExpr)(anim.xKeys.map((k) => ({ t: k.t, v: k.v + ox }))) : String(ox);
+    const yExpr = (anim === null || anim === void 0 ? void 0 : anim.yKeys) ? (0, template_utils_1.keyframeExpr)(anim.yKeys.map((k) => ({ t: k.t, v: k.v + oy }))) : String(oy);
+    return {
+        placement: { fit: "contain", inset: { x: ix, y: iy } },
+        overlay: { xExpr, yExpr, ...((anim === null || anim === void 0 ? void 0 : anim.alpha) ? { alpha: anim.alpha } : {}) },
+    };
+}
+/** The slide keyframes on the partition axis: `from`→`to` as a share of (dx, dy). */
+function slideKeys(g, t0, t1, from, to) {
+    const keys = [{ t: t0, v: from * (g.axis === "x" ? g.dx : g.dy) }, { t: t1, v: to * (g.axis === "x" ? g.dx : g.dy) }];
+    return g.axis === "x" ? { xKeys: keys } : { yKeys: keys };
+}
+const PHOTO = (0, types_1.asAssetId)("original");
+/** The tile's original, un-clipped, in a frame layer at `rect` (+ optional slide / fade). */
+function photoSource(plan, rect, anim) {
+    return { type: "media", mediaType: "image", assetId: PHOTO, ...layerAt(plan, rect, anim) };
+}
+/** A `1{1{1}}` frame: canvas colour, then two layers. */
+function layeredDoc(plan, durationMs, children, layers, audio = { mode: "off" }) {
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: "1{1{1}}",
+        size: { width: plan.frameW, height: plan.frameH },
+        fps: plan.fps,
+        durationMs,
+        backgroundColor: plan.props.canvasColor,
+        audio,
+        assets: { [PHOTO]: (0, mark_1.claimImageAsset)(plan.photo.image) },
+        children,
+        sources: [{ type: "lavfi", color: plan.props.canvasColor }, ...layers],
+    };
+}
+/** The dissolve share of a reveal beat (the rest is a hold on the original). */
+function dissolveSec(revealMs) {
+    return Math.max(0.4, Math.min(1.6, (revealMs / 1000) * 0.6));
+}
+/** Beat 1+2: the whole M with its identity, then the dolly into the tile. */
+function buildIntroDoc(plan, durationMs) {
+    const g = photoGeometry(plan);
+    const t = plan.timeline;
+    const s0 = t.introHoldMs / 1000, s1 = (t.introHoldMs + t.zoomMs) / 1000;
+    const camera = (0, camera_1.zoomToTileCamera)({ tile: g.tile, stageW: plan.frameW, stageH: g.layout.stageH, zoom: g.zoom, startSec: s0, endSec: s1 });
+    // No per-tile spotlight: a per-cell alpha pushes all 33 tiles off ffmpeg's
+    // grid sheet into a 33-deep overlay chain, past the depth where inline masks
+    // silently degrade (OVERLAY_CHAIN_DEEP). The dolly isolates the tile on its own.
+    // The brand field (and its plate) hold under the whole M, then fade out in
+    // the last part of the hold — gone the moment the dolly begins, so the
+    // camera moves over a clean canvas and the cut into the reveal is clean.
+    const fade = Math.min(FIELD_FADE_SEC, s0 / 2);
+    const field = { alpha: (0, template_utils_1.keyframeExpr)([{ t: s0 - fade, v: 1 }, { t: s0, v: 0 }]) };
+    return framedDoc(plan, g.layout, durationMs, { type: "mosaic", ref: "stage", effects: { camera } }, (0, target_1.identityLine)(plan.target.entry), plan.tileCaption, field);
+}
+/**
+ * Beat 3: parked on the tile, the framed M dissolves while the un-clipped
+ * original fades in EXACTLY over its crop (nothing moves), holds, then
+ * slides aside — left, or up on a frame where that shows more of it — to
+ * make room for the canvas (the partition contract in reveal.ts).
+ */
+function buildRevealDoc(plan, durationMs) {
+    const g = photoGeometry(plan);
+    const t = plan.timeline;
+    const fade = dissolveSec(t.revealMs);
+    const slide0 = t.revealMs / 1000, slide1 = (t.revealMs + t.slideMs) / 1000;
+    return layeredDoc(plan, durationMs, { framed: parkedFrameDoc(plan, g, durationMs) }, [
+        { type: "mosaic", ref: "framed", overlay: { alpha: (0, template_utils_1.keyframeExpr)([{ t: 0, v: 1 }, { t: fade, v: 0 }]) } },
+        photoSource(plan, g.aligned, {
+            alpha: (0, template_utils_1.keyframeExpr)([{ t: 0, v: 0 }, { t: fade, v: 1 }]),
+            ...slideKeys(g, slide0, slide1, 0, 1),
+        }),
+    ]);
+}
+/**
+ * Beat 4: the original parked aside; the contributor canvas pops into its
+ * box (camera 1 → POP_SCALE on the padded wrapper) and plays at its own
+ * declared size, fading out over the last crossfade.
+ */
+function buildPieceDoc(plan, durationMs) {
+    const g = photoGeometry(plan);
+    const t = plan.timeline;
+    const pop = t.popMs / 1000;
+    const x = t.xfadeMs / 1000;
+    const end = durationMs / 1000;
+    const wrapper = (0, piece_1.popWrapperDoc)({ fitW: g.pieceRect.width, fitH: g.pieceRect.height, fps: plan.fps, durationMs, piece: plan.piece, canvasColor: plan.props.canvasColor });
+    const zoom = (0, template_utils_1.keyframeExpr)([{ t: 0, v: 1 }, { t: pop, v: wrapper.size.width / g.pieceRect.width }]);
+    const at = layerAt(plan, g.pieceRect, x > 0 ? { alpha: (0, template_utils_1.keyframeExpr)([{ t: end - x, v: 1 }, { t: end, v: 0 }]) } : undefined);
+    const canvas = {
+        type: "mosaic",
+        ref: "canvas",
+        placement: at.placement,
+        effects: { camera: { zoom, focusX: 0.5, focusY: 0.5 } },
+        overlay: at.overlay,
+    };
+    return layeredDoc(plan, durationMs, { canvas: wrapper }, [photoSource(plan, g.parked), canvas], { mode: "auto" });
+}
+/** Beat 5: the original slides back over its tile, then dissolves into the parked M. */
+function buildReturnDoc(plan, durationMs) {
+    const g = photoGeometry(plan);
+    const t = plan.timeline;
+    const slide1 = t.slideMs / 1000;
+    const fade = dissolveSec(t.revealMs);
+    return layeredDoc(plan, durationMs, { framed: parkedFrameDoc(plan, g, durationMs) }, [
+        { type: "mosaic", ref: "framed", overlay: { alpha: (0, template_utils_1.keyframeExpr)([{ t: slide1, v: 0 }, { t: slide1 + fade, v: 1 }]) } },
+        photoSource(plan, g.aligned, {
+            alpha: (0, template_utils_1.keyframeExpr)([{ t: slide1, v: 1 }, { t: slide1 + fade, v: 0 }]),
+            ...slideKeys(g, 0, slide1, 1, 0),
+        }),
+    ]);
+}
+/** Beat 6: back out from the tile to the whole M. */
+function buildOutroDoc(plan, durationMs) {
+    const g = photoGeometry(plan);
+    const travel = Math.max(0.3, (plan.timeline.outroMs / 1000) * 0.75);
+    const camera = (0, camera_1.zoomToTileCamera)({ tile: g.tile, stageW: plan.frameW, stageH: g.layout.stageH, zoom: g.zoom, startSec: 0, endSec: travel, reverse: true });
+    return framedDoc(plan, g.layout, durationMs, { type: "mosaic", ref: "stage", effects: { camera } }, (0, target_1.identityLine)(plan.target.entry), plan.tileCaption);
+}
+/**
+ * Beat 7: the brand closer — the m0saic logo, the wordmark, where to claim a
+ * tile. The SAME frame as the outro it dissolves from: the stage row with
+ * the M at `layout.side` on the same pixels (the community M's tiles become
+ * the logo's tiles in place), the identity line becomes the wordmark, the
+ * tile line becomes the repo. Nothing jumps across the crossfade.
+ */
+function buildCloserDoc(plan, durationMs) {
+    const layout = frameLayout(plan.frameW, plan.frameH);
+    const logo = (0, mark_1.buildLogoDoc)({ side: layout.side, fps: plan.fps, durationMs, color: plan.props.accentColor, canvasColor: plan.props.canvasColor });
+    const wordmark = (0, wordmark_1.wordmarkRowDoc)({ rowW: plan.frameW, rowH: layout.capH, fps: plan.fps, durationMs, ink: plan.props.textColor, accent: plan.props.accentColor, canvasColor: plan.props.canvasColor });
+    // On the brand field, like the intro — the outro → closer crossfade fades it in.
+    return fieldedDoc(plan, layout, durationMs, { stage: stageDoc(plan, layout, durationMs, logo), wordmark }, [
+        { type: "mosaic", ref: "stage" },
+        { type: "mosaic", ref: "wordmark" },
+        (0, caption_1.captionSource)(`github.com/${plan.repo}`, plan.frameW, layout.capH, plan.props.accentColor),
+    ], {});
+}
+/**
+ * The whole provenance video as an emit:single pipeline under the timing
+ * law. Every join but the last is a CUT on an identical frame (the slide
+ * and the dissolves live inside their steps, so nothing jumps); only the
+ * outro → closer join is a crossfade, carried by the outgoing step.
+ */
+function buildProvenancePipeline(plan) {
+    const t = plan.timeline;
+    const x = t.xfadeMs;
+    const closer = t.closerMs > 0;
+    const steps = [];
+    const revealMs = t.revealMs + t.slideMs;
+    steps.push({ name: "intro", label: "The M", durationMs: t.introVisibleMs, file: buildIntroDoc(plan, t.introVisibleMs) });
+    steps.push({ name: "reveal", label: "Your tile", durationMs: revealMs, file: buildRevealDoc(plan, revealMs) });
+    steps.push({ name: "piece", label: "Your canvas", durationMs: t.pieceVisibleMs, file: buildPieceDoc(plan, t.pieceVisibleMs) });
+    steps.push({ name: "return", label: "Back to your tile", durationMs: revealMs, file: buildReturnDoc(plan, revealMs) });
+    const outroMs = t.outroMs + (closer ? x : 0);
+    steps.push({ name: "outro", label: "Back to the M", durationMs: outroMs, file: buildOutroDoc(plan, outroMs), ...(closer && x > 0 ? { transitionToNext: { type: "fade", durationMs: x } } : {}) });
+    if (closer)
+        steps.push({ name: "closer", label: "m0saic", durationMs: t.closerMs, file: buildCloserDoc(plan, t.closerMs) });
+    return {
+        kind: "mosaic_pipeline",
+        version: 1,
+        emit: "single",
+        size: { width: plan.frameW, height: plan.frameH },
+        fps: plan.fps,
+        durationMs: t.totalMs,
+        durationFit: "cut",
+        defaultTransition: { type: "cut" },
+        backgroundColor: plan.props.canvasColor,
+        steps,
+    };
+}

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

@@ -0,0 +1,75 @@
+import { type PlaceholderArtStyle } from "@m0saic/platform";
+import type { CommunityMEntry } from "@m0saic/types";
+import type { ClaimImage, MarkClaim } from "./mark";
+import type { LoadedPiece } from "./piece";
+import type { ImageSize } from "./reveal";
+/**
+ * DEV LEVERS — design the harness before the M fills up.
+ *
+ * The seed has ONE claim, so at defaults the video is a nearly-empty M with
+ * one real photo. These knobs stand the rest of it up: open tiles get art
+ * from the SAME bank the Community page previews with
+ * (`@m0saic/platform` `placeholderArt`), any tile can be the subject (so the
+ * crop maths gets exercised on wide, tall and diagonal tiles, not just the
+ * root's V), and the contributor canvas can be a generated card instead of
+ * a real `.mosaic` — so you can iterate on the harness without authoring
+ * one.
+ *
+ * All of it is off by default and fully deterministic: same knobs, same
+ * bytes. Nothing here reads the disk.
+ */
+export type PreviewPieceStyle = "off" | "lorem" | "card" | "bars" | "reel" | "grid";
+export type PreviewPieceAspect = "16:9" | "1:1" | "9:16";
+export type PreviewOptions = {
+    /** How many tiles the M paints as claimed (0 = off, real claims only). */
+    claims: number;
+    style: PlaceholderArtStyle;
+    seed: number;
+    /** Share of a `mix` that is logos rather than faces. */
+    logoShare: number;
+    /** Tile index the video is about, overriding the resolved slot. */
+    tile: number | null;
+    piece: PreviewPieceStyle;
+    pieceAspect: PreviewPieceAspect;
+};
+export type PreviewPhoto = {
+    image: ClaimImage;
+    size: ImageSize;
+    focus: {
+        x: number;
+        y: number;
+    };
+};
+/** One tile's stand-in, as a data-uri image the engine rasterizes (same path as the claimed edges). */
+export declare function standInPhoto(tileIndex: number, o: Pick<PreviewOptions, "style" | "seed" | "logoShare">): PreviewPhoto;
+/**
+ * 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.
+ */
+export declare function simulatedClaims(entry: CommunityMEntry, real: ReadonlySet<number>, o: PreviewOptions): Map<number, MarkClaim>;
+/**
+ * "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.
+ */
+export declare function previewTileLine(tileIndex: number, style: PlaceholderArtStyle, claimNo?: number | null, capacity?: number): string;
+/** Stand-in canvas duration — long enough to read, short enough to iterate. */
+export declare const PREVIEW_PIECE_MS = 4000;
+/** The moving samples need room to actually move. */
+export declare const PREVIEW_PIECE_LONG_MS = 6000;
+/**
+ * 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.
+ */
+export declare function previewPiece(o: {
+    style: Exclude<PreviewPieceStyle, "off">;
+    aspect: PreviewPieceAspect;
+    fps: number;
+    canvasColor: string;
+    accentColor: string;
+    textColor: string;
+}): LoadedPiece;