@m0saic/templates 0.2.0

package/dist/m0saic/media/screencap_grid_aspect_safe/v1/screencap-grid-aspect-safe.js

@@ -0,0 +1,544 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreencapGridAspectSafe = exports.CELL_SHAPE_RATIOS = void 0;
+exports.targetShapeDistance = targetShapeDistance;
+exports.enumerateAspectSafePairs = enumerateAspectSafePairs;
+exports.renderScreencapGridAspectSafe = renderScreencapGridAspectSafe;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+// Reuse formatting + sizing helpers from the screen grid — same info
+// pane / timestamps semantics, just at per-orientation canvases.
+const screencap_grid_1 = require("../../screencap_grid/v1/screencap-grid");
+// The exact-layout core + group-config shapes + field helpers shared with
+// screencap_grid/v2 (the canonical family member).
+const screencap_grid_2 = require("../../screencap_grid/v2/screencap-grid");
+const info_pane_1 = require("../../screencap_grid/internal/info_pane");
+// Editor-only onboarding surfaces (renderCover / renderTutorial) — gate-25
+// founder ruling ("it needs a cover and tutorial"). Kept in sibling modules
+// so this file stays about the pair machinery.
+const screencap_grid_aspect_safe_cover_1 = require("./screencap-grid-aspect-safe-cover");
+const screencap_grid_aspect_safe_tutorial_1 = require("./screencap-grid-aspect-safe-tutorial");
+const ASPECT_SAFE_ID = "@m0saic/media/screencap_grid_aspect_safe/v1";
+/** The aspect ratio each preset targets (width / height). */
+exports.CELL_SHAPE_RATIOS = {
+    landscape: 16 / 9,
+    square: 1,
+    portrait: 9 / 16,
+};
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    // The one source input. One required "Source(s)" field that takes a
+    // folder, one or many files, or drag-and-drop — per-file emit:multi
+    // fan-out (2 outputs per file: landscape + portrait).
+    sourceIds: {
+        type: "media[]",
+        required: true,
+        description: "Source video(s) for the grid — pick a folder, one or more files, or drag-and-drop. 2 outputs per file (landscape + portrait).",
+        meta: {
+            ui: { label: "Source(s)", order: 1 },
+            control: { multiple: true, picker: "folder", accept: ["video"] },
+        },
+    },
+    // Reserved prop-bag convention (trickplay/screencap precedent): a prop
+    // named `outputFormat` holding a container name drives the Make page's
+    // Output Type + container + default output extension.
+    outputFormat: {
+        type: "string",
+        required: false,
+        description: 'Deliverable format. "png" renders static contact sheets; "mp4" renders animated grids where each tile plays from its timestamp.',
+        meta: {
+            constraints: { oneOf: ["png", "mp4"] },
+            ui: { label: "Output", order: 1 },
+        },
+    },
+    cellShape: {
+        type: "string",
+        required: false,
+        description: "What shape should the cells be? landscape = 16:9 (the natural shape for video frames), square, portrait = 9:16. Both orientations' grids are chosen so their cells realize this shape at the same cell count.",
+        meta: {
+            constraints: { oneOf: ["landscape", "square", "portrait"] },
+            ui: { label: "Cell Shape", order: 1 },
+        },
+    },
+    gridChoice: {
+        type: "number",
+        required: false,
+        description: "Index into the ranked list of coordinated landscape/portrait grid pairs. 0 = best-ranked (both orientations' cells closest to the wanted cell shape). Out-of-range clamps to the last available pair.",
+        meta: {
+            constraints: { min: 0, max: 24 },
+            control: { flavor: "slider", step: 1 },
+            ui: { label: "Grid Choice", order: 3 },
+        },
+    },
+    // ── Collapsible groups (`type:"group"` + `fields` — folds in Make AND
+    //    Compose; the one grouping mechanism). ──
+    search: {
+        type: "group",
+        required: false,
+        description: "Pair-search tuning: exact cell aspect + the cell-count window the ranked list sweeps.",
+        meta: { ui: { label: "Grid Search", order: 4, collapsedByDefault: true } },
+        fields: {
+            cellAspect: (0, screencap_grid_2.fNum)("Cell Aspect (exact)", "Exact target cell aspect ratio (width/height) — overrides Cell Shape when set. E.g. 1.5 for 3:2 cells, 0.8 for 4:5.", { placeholder: "from Cell shape" }, { min: 0.1, max: 10 }),
+            minCells: (0, screencap_grid_2.fNum)("Min Cells", "Lower bound for the cell-count sweep.", undefined, { min: 1, max: 64 }),
+            maxCells: (0, screencap_grid_2.fNum)("Max Cells", "Upper bound for the cell-count sweep.", undefined, { min: 1, max: 64 }),
+        },
+    },
+    canvas: {
+        type: "group",
+        required: false,
+        description: "Output canvas dimensions per orientation.",
+        meta: { ui: { label: "Canvas", order: 5, collapsedByDefault: true } },
+        fields: {
+            landscapeW: (0, screencap_grid_2.fNum)("Landscape W", "Landscape canvas width — desktop output.", undefined, { min: 16, max: 8192 }),
+            landscapeH: (0, screencap_grid_2.fNum)("Landscape H", "Landscape canvas height — desktop output.", undefined, { min: 16, max: 8192 }),
+            portraitW: (0, screencap_grid_2.fNum)("Portrait W", "Portrait canvas width — mobile output.", undefined, { min: 16, max: 8192 }),
+            portraitH: (0, screencap_grid_2.fNum)("Portrait H", "Portrait canvas height — mobile output.", undefined, { min: 16, max: 8192 }),
+        },
+    },
+    infoPane: {
+        type: "group",
+        required: false,
+        description: "Info pane with filename + ffprobe metadata above the grid.",
+        meta: { ui: { label: "Info Pane", order: 6, collapsedByDefault: true } },
+        fields: {
+            show: (0, screencap_grid_2.fBool)("Show", "Show the info pane above the grid."),
+            align: (0, screencap_grid_2.fEnum)("Align", ["left", "center", "right"], "Alignment of the pane text (filename + metadata)."),
+        },
+    },
+    timestamps: {
+        type: "group",
+        required: false,
+        description: "Per-tile timestamp chip.",
+        meta: { ui: { label: "Timestamps", order: 7, collapsedByDefault: true } },
+        fields: {
+            show: (0, screencap_grid_2.fBool)("Show", "Overlay a timestamp in each tile."),
+            corner: (0, screencap_grid_2.fEnum)("Corner", ["tl", "tr", "bl", "br"], "Which corner the chip sits in."),
+            color: (0, screencap_grid_2.fColor)("Color", "Timestamp text color."),
+            bgColor: (0, screencap_grid_2.fColor)("Background", "Chip background behind the glyphs (\"none\" = transparent)."),
+        },
+    },
+    tiles: {
+        type: "group",
+        required: false,
+        description: "Tile gap + fill behavior.",
+        meta: { ui: { label: "Tiles", order: 8, collapsedByDefault: true } },
+        fields: {
+            gapPx: (0, screencap_grid_2.fNum)("Gap (px)", "Gap between tiles, in pixels (exact at every canvas).", { flavor: "slider", step: 1, unit: "px" }, { min: 0, max: 40 }),
+            fit: (0, screencap_grid_2.fEnum)("Fit", ["cover", "contain"], "cover crops to fill; contain letterboxes the whole frame."),
+        },
+    },
+    debugGeometry: {
+        type: "boolean",
+        required: false,
+        description: "Dev-only geometry contract: assert every tile's computed rect survived to the pixels at each orientation canvas; on violation that step renders a GEOMETRY_CONTRACT error mosaic. Deterministic default false; production never sets it.",
+        meta: { ui: { label: "Debug geometry", order: 1, collapsedByDefault: true } },
+    },
+});
+// ---- DEFAULTS ----
+const SHARED_DEFAULTS = {
+    outputFormat: "png",
+    cellShape: "landscape",
+    gridChoice: 0,
+    search: { minCells: 4, maxCells: 32 },
+    canvas: { landscapeW: 1920, landscapeH: 1080, portraitW: 1080, portraitH: 1920 },
+    infoPane: { show: true, align: "left" },
+    timestamps: { show: true, corner: "br", color: "#ffffff", bgColor: "none" },
+    tiles: { gapPx: 2, fit: "cover" },
+};
+function resolveInputs(props) {
+    if (props.sourceIds && props.sourceIds.length > 0)
+        return props.sourceIds;
+    return [];
+}
+/**
+ * Resolve grouped props → the flat internal config the render body consumes.
+ * Precedence per knob: grouped value → legacy flat value (see
+ * {@link ScreencapGridAspectSafeLegacyProps}) → default.
+ */
+function resolveConfig(props) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18, _19, _20, _21, _22;
+    const legacy = props;
+    // The numeric escape hatch overrides the preset; the preset defaults
+    // to landscape (16:9 cells), so a target is ALWAYS in play. Unknown
+    // shape strings (schema-invalid, but this is a public function) fall
+    // back to the landscape default rather than poisoning the log math.
+    const exactAspect = (_b = (_a = props.search) === null || _a === void 0 ? void 0 : _a.cellAspect) !== null && _b !== void 0 ? _b : legacy.targetCellAspect;
+    return {
+        inputs: resolveInputs(props),
+        targetCellAspect: typeof exactAspect === "number" && exactAspect > 0
+            ? exactAspect
+            : ((_d = exports.CELL_SHAPE_RATIOS[(_c = props.cellShape) !== null && _c !== void 0 ? _c : "landscape"]) !== null && _d !== void 0 ? _d : exports.CELL_SHAPE_RATIOS.landscape),
+        gridChoice: (_e = props.gridChoice) !== null && _e !== void 0 ? _e : 0,
+        countMin: (_h = (_g = (_f = props.search) === null || _f === void 0 ? void 0 : _f.minCells) !== null && _g !== void 0 ? _g : legacy.targetCellCountMin) !== null && _h !== void 0 ? _h : 4,
+        countMax: (_l = (_k = (_j = props.search) === null || _j === void 0 ? void 0 : _j.maxCells) !== null && _k !== void 0 ? _k : legacy.targetCellCountMax) !== null && _l !== void 0 ? _l : 32,
+        landscapeW: (_p = (_o = (_m = props.canvas) === null || _m === void 0 ? void 0 : _m.landscapeW) !== null && _o !== void 0 ? _o : legacy.landscapeW) !== null && _p !== void 0 ? _p : 1920,
+        landscapeH: (_s = (_r = (_q = props.canvas) === null || _q === void 0 ? void 0 : _q.landscapeH) !== null && _r !== void 0 ? _r : legacy.landscapeH) !== null && _s !== void 0 ? _s : 1080,
+        portraitW: (_v = (_u = (_t = props.canvas) === null || _t === void 0 ? void 0 : _t.portraitW) !== null && _u !== void 0 ? _u : legacy.portraitW) !== null && _v !== void 0 ? _v : 1080,
+        portraitH: (_y = (_x = (_w = props.canvas) === null || _w === void 0 ? void 0 : _w.portraitH) !== null && _x !== void 0 ? _x : legacy.portraitH) !== null && _y !== void 0 ? _y : 1920,
+        withInfoPane: (_1 = (_0 = (_z = props.infoPane) === null || _z === void 0 ? void 0 : _z.show) !== null && _0 !== void 0 ? _0 : legacy.withInfoPane) !== null && _1 !== void 0 ? _1 : true,
+        headerAlign: (_4 = (_3 = (_2 = props.infoPane) === null || _2 === void 0 ? void 0 : _2.align) !== null && _3 !== void 0 ? _3 : legacy.headerAlign) !== null && _4 !== void 0 ? _4 : "left",
+        withTileTimestamp: (_7 = (_6 = (_5 = props.timestamps) === null || _5 === void 0 ? void 0 : _5.show) !== null && _6 !== void 0 ? _6 : legacy.withTileTimestamp) !== null && _7 !== void 0 ? _7 : true,
+        timestampCorner: (_10 = (_9 = (_8 = props.timestamps) === null || _8 === void 0 ? void 0 : _8.corner) !== null && _9 !== void 0 ? _9 : legacy.timestampCorner) !== null && _10 !== void 0 ? _10 : "br",
+        timestampColor: (_13 = (_12 = (_11 = props.timestamps) === null || _11 === void 0 ? void 0 : _11.color) !== null && _12 !== void 0 ? _12 : legacy.timestampColor) !== null && _13 !== void 0 ? _13 : "#ffffff",
+        timestampBgColor: (_16 = (_15 = (_14 = props.timestamps) === null || _14 === void 0 ? void 0 : _14.bgColor) !== null && _15 !== void 0 ? _15 : legacy.timestampBgColor) !== null && _16 !== void 0 ? _16 : "none",
+        tileGapPx: (_19 = (_18 = (_17 = props.tiles) === null || _17 === void 0 ? void 0 : _17.gapPx) !== null && _18 !== void 0 ? _18 : legacy.tileGapPx) !== null && _19 !== void 0 ? _19 : 2,
+        tileFit: (_22 = (_21 = (_20 = props.tiles) === null || _20 === void 0 ? void 0 : _20.fit) !== null && _21 !== void 0 ? _21 : legacy.tileFit) !== null && _22 !== void 0 ? _22 : "cover",
+        debugGeometry: props.debugGeometry === true,
+    };
+}
+/**
+ * How far BOTH orientations' cells sit from the target shape — the sum of
+ * per-orientation log-distances. Log space keeps 1.5 and 1/1.5 equally far
+ * from square; summing both orientations means a pair only ranks well when
+ * EACH canvas realizes the wanted shape (and then the cross-orientation
+ * match follows by the triangle inequality: delta ≤ distL + distP).
+ */
+function targetShapeDistance(pair, target) {
+    const t = Math.log(target);
+    return (Math.abs(Math.log(pair.landscape.cellAspectRatio) - t) +
+        Math.abs(Math.log(pair.portrait.cellAspectRatio) - t));
+}
+/**
+ * Enumerate coordinated landscape/portrait pairs across the cell-count
+ * window. Each `targetCellCount` is tried with tolerance 0 (exact
+ * count). Failures (no feasible pair) are silently dropped. Results
+ * are sorted so the best pair lands at index 0:
+ *
+ * With `targetCellAspect` set (shape-first — the shape question decides):
+ *   1. Smallest {@link targetShapeDistance} first (both orientations'
+ *      cells closest to the wanted shape).
+ *   2. Then smallest `cellAspectLogDelta` (cross-orientation match).
+ *   3. Then larger cellCount (denser grid).
+ * The target is also passed INTO `aspectSafeGrid` per cell count, so each
+ * count picks its shape-aligned (rows, cols) factorization — ranking alone
+ * could not recover a factorization the builder didn't pick.
+ *
+ * Without a target (legacy):
+ *   1. Smallest `cellAspectLogDelta` first (best cross-orientation
+ *      cell-shape match).
+ *   2. Tied AR match → larger cellCount wins (more cells = denser
+ *      grid, which is usually what the user wants).
+ */
+function enumerateAspectSafePairs(cfg) {
+    var _a;
+    const target = (_a = cfg.targetCellAspect) !== null && _a !== void 0 ? _a : null;
+    const out = [];
+    for (let n = cfg.countMin; n <= cfg.countMax; n++) {
+        try {
+            const pair = (0, dsl_stdlib_1.aspectSafeGrid)({
+                landscapeW: cfg.landscapeW,
+                landscapeH: cfg.landscapeH,
+                portraitW: cfg.portraitW,
+                portraitH: cfg.portraitH,
+                targetCellCount: n,
+                cellCountTolerance: 0,
+                ...(target != null ? { targetCellAspectRatio: target } : {}),
+                // Gutterless: cells are pure, so the aspect-match is computed on the
+                // same cells we actually render (gutterless fill). The gap is a
+                // cosmetic per-cell carve and doesn't affect cell aspect. `letterbox:
+                // true` keeps the widest pool of aspect-matched (rows, cols) pairs —
+                // since we always fill, this never adds bars, it just maximizes the
+                // candidate set for the best cross-orientation aspect match.
+                letterbox: true,
+            });
+            out.push(pair);
+        }
+        catch {
+            // No feasible pair for this exact cell count — drop and continue.
+        }
+    }
+    out.sort((a, b) => {
+        if (target != null) {
+            const dTarget = targetShapeDistance(a, target) - targetShapeDistance(b, target);
+            if (Math.abs(dTarget) > 1e-9)
+                return dTarget;
+        }
+        const dDelta = a.cellAspectLogDelta - b.cellAspectLogDelta;
+        if (Math.abs(dDelta) > 1e-9)
+            return dDelta;
+        return b.cellCount - a.cellCount;
+    });
+    return out;
+}
+/**
+ * Pick the gridChoice-th ranked pair. Returns null when the sweep
+ * produced no feasible candidates — caller surfaces that as an error
+ * mosaic.
+ */
+function pickAspectSafePair(cfg) {
+    const candidates = enumerateAspectSafePairs(cfg);
+    if (candidates.length === 0)
+        return null;
+    const idx = Math.max(0, Math.min(candidates.length - 1, cfg.gridChoice));
+    return candidates[idx];
+}
+/** Resolve the render mode from the `outputFormat` knob (default png/static). */
+function resolveMode(props) {
+    return props.outputFormat === "mp4" ? "animated" : "static";
+}
+/**
+ * The output format each rendered step document declares for its mode
+ * (watermark/trickplay/screencap precedent) — under `emit: "multi"` every
+ * step switches the command build into the right graph mode.
+ */
+function formatForMode(mode) {
+    return mode === "animated"
+        ? { kind: "video", container: "mp4" }
+        : { kind: "image", container: "png" };
+}
+/**
+ * Render one orientation (landscape OR portrait) of one input file.
+ * Returns a MosaicDocument with the orientation's canvas + tiles +
+ * optional info pane. Layout is the screencap_grid/v2 machinery:
+ * integer gap-carved rects → one `placeInsetPieces` call, timestamps
+ * as same-rect pieces at importance 1 (guaranteed above their tile).
+ */
+async function renderOrientationForInput(sourceId, cfg, pair, orientation, ctx, mode) {
+    var _a, _b, _c;
+    const canvasW = orientation === "landscape" ? cfg.landscapeW : cfg.portraitW;
+    const canvasH = orientation === "landscape" ? cfg.landscapeH : cfg.portraitH;
+    const oriented = orientation === "landscape" ? pair.landscape : pair.portrait;
+    const rows = oriented.rows;
+    const cols = oriented.cols;
+    const N = rows * cols;
+    const ctxMediaKey = (0, types_1.asAssetId)(sourceId);
+    const sourceAssetId = (0, types_1.asAssetId)((0, template_utils_1.slugifyAssetKeyFromPath)(sourceId));
+    const meta = ctx.media[ctxMediaKey];
+    let paneHeightPx = 0;
+    const children = {};
+    if (cfg.withInfoPane) {
+        const info = meta
+            ? (0, screencap_grid_1.formatInfoLines)(sourceId, meta)
+            : { title: `No metadata for sourceId=${sourceId}`, metadata: "", metaLineCount: 0 };
+        const ratio = Math.max(0.03, Math.min(0.25, (0, screencap_grid_1.estimateInfoPaneHeight)(canvasH, info.metaLineCount) / canvasH));
+        paneHeightPx = Math.max(1, Math.round(canvasH * ratio));
+        // Fit-first (the gate-24 screencap_grid/v2 fix, shared semantics): the
+        // pane draws LITERAL text at fixed fonts — basename-ify the title (never
+        // print a filesystem path), middle-ellipsize it keeping the extension
+        // tail, and end-ellipsize dense metadata lines. Per-orientation: the
+        // portrait canvas is narrower, so each orientation fits its own budget.
+        const titleBase = ((_a = info.title.split("/").pop()) === null || _a === void 0 ? void 0 : _a.split("\\").pop()) || info.title;
+        const fitTitle = (0, screencap_grid_2.ellipsizeMiddleEm)(titleBase, (0, screencap_grid_2.paneLineEmBudget)(canvasW, (0, screencap_grid_1.infoPaneTitleFontSize)(canvasH)));
+        const metaBudget = (0, screencap_grid_2.paneLineEmBudget)(canvasW, (0, screencap_grid_1.infoPaneMetaFontSize)(canvasH));
+        const fitMeta = info.metadata
+            .split("\n")
+            .map((l) => ((0, template_utils_1.textEmUnits)(l) <= metaBudget + 0.5 ? l : (0, template_utils_1.fitEmUnits)(l, metaBudget)))
+            .join("\n");
+        // Slot height stays canvasH so the drawtext font sizes match
+        // estimateInfoPaneHeight's assumptions (the child rasterizes at its
+        // parent frame size regardless).
+        const infoPaneFile = await (0, template_utils_1.renderNestedTemplate)(info_pane_1.INFO_PANE_TEMPLATE_ID, { title: fitTitle, metadata: fitMeta, paneHeight: paneHeightPx, align: cfg.headerAlign }, ctx, { slot: { width: canvasW, height: canvasH } });
+        children["info-pane"] = infoPaneFile;
+    }
+    const gridH = canvasH - paneHeightPx;
+    if (gridH < rows || canvasW < cols) {
+        return (0, template_utils_1.makeErrorMosaic)(`${orientation} canvas ${canvasW}×${canvasH} is too small for the ${rows}×${cols} grid${cfg.withInfoPane ? " below the info pane" : ""}.`, { title: "Screencap Grid — Aspect Safe", width: canvasW, height: canvasH });
+    }
+    const isVideo = (meta === null || meta === void 0 ? void 0 : meta.kind) === "video" && meta.durationMs != null && meta.durationMs > 0;
+    const timestamps = isVideo ? (0, screencap_grid_1.computeTimestamps)(N, meta.durationMs) : [];
+    const mediaType = (meta === null || meta === void 0 ? void 0 : meta.kind) === "video"
+        ? "video"
+        : (meta === null || meta === void 0 ? void 0 : meta.kind) === "audio"
+            ? "audio"
+            : "image";
+    const frameMs = Math.max(1, Math.round(1000 / ((_c = (_b = meta === null || meta === void 0 ? void 0 : meta.fps) !== null && _b !== void 0 ? _b : ctx.target.fps) !== null && _c !== void 0 ? _c : 30)));
+    // The pane child rasterizes at full canvas height with its text in the
+    // top strip; a top-anchored cover crop (focusY: 0) shows exactly that
+    // strip in the ~paneHeightPx cell. The default contain fit would scale
+    // the whole full-height frame down into the cell (≈2px text).
+    const paneSource = {
+        type: "mosaic",
+        ref: "info-pane",
+        placement: { fit: "cover", focusY: 0 },
+    };
+    const tileRects = (0, screencap_grid_2.computeGridTileRects)({
+        canvasW, canvasH, paneHeightPx, rows, cols, tileGapPx: cfg.tileGapPx,
+    });
+    const pieces = [];
+    if (cfg.withInfoPane) {
+        pieces.push({ rect: { x: 0, y: 0, w: canvasW, h: paneHeightPx }, source: paneSource });
+    }
+    for (let i = 0; i < N; i++) {
+        const t = isVideo ? timestamps[i] : 0;
+        const r = tileRects[i];
+        pieces.push({
+            rect: { x: r.x, y: r.y, w: r.w, h: r.h },
+            source: {
+                type: "media",
+                mediaType,
+                assetId: sourceAssetId,
+                placement: { fit: cfg.tileFit },
+                ...(isVideo
+                    ? {
+                        playback: mode === "animated"
+                            ? { clipStartMs: t }
+                            : { clipStartMs: t, clipDurationMs: frameMs, loopMode: "freeze" },
+                        audio: { enabled: false },
+                    }
+                    : {}),
+                editor: { owner: "template" },
+            },
+        });
+        if (cfg.withTileTimestamp) {
+            pieces.push({
+                rect: { x: r.x, y: r.y, w: r.w, h: r.h, importance: 1 },
+                source: (0, screencap_grid_1.buildTimestampSource)({
+                    t,
+                    mode,
+                    isVideo,
+                    corner: cfg.timestampCorner,
+                    color: cfg.timestampColor,
+                    bgColor: cfg.timestampBgColor,
+                }),
+            });
+        }
+    }
+    const placed = (0, template_utils_1.placeInsetPieces)({ rootW: canvasW, rootH: canvasH, pieces });
+    const assets = {
+        [sourceAssetId]: {
+            kind: "file",
+            path: sourceId,
+            mediaType,
+        },
+    };
+    const doc = {
+        kind: "mosaic_document",
+        version: 1,
+        sources: placed.sources,
+        assets,
+        m0: placed.m0,
+        children,
+        size: { width: canvasW, height: canvasH },
+        format: formatForMode(mode),
+        // Doc-level disable STRIPS the track (`-an`). The source-level knob on
+        // each tile only mutes the mix contribution — alone, every animated
+        // orientation shipped a silent placeholder audio track (the gate-20
+        // class, third family member after highlights and screencap_grid/v2).
+        ...(mode === "animated" ? { audio: { mode: "off" } } : {}),
+    };
+    // Dev tripwire (zero cost when off). The doc renders at its OWN declared
+    // canvas (each orientation differs from ctx.target), so the contract is
+    // checked against an orientation-sized target.
+    return (0, template_utils_1.withGeometryContract)(doc, { ...ctx, target: { ...ctx.target, width: canvasW, height: canvasH } }, {
+        templateId: ASPECT_SAFE_ID,
+        expectations: placed.expectations,
+        debug: cfg.debugGeometry,
+    });
+}
+/**
+ * Build the emit:multi pipeline. Two steps per input file
+ * (`{slug}__landscape`, `{slug}__portrait`). With 1 input that's 2
+ * steps; with N inputs, 2N steps.
+ */
+async function buildAspectSafePipeline(cfg, pair, ctx, mode) {
+    var _a;
+    // Static sheets are single-frame renders — a fixed nominal duration
+    // (trickplay/screencap precedent); animated steps track the target.
+    const stepDurationMs = mode === "animated" ? ((_a = ctx.target.durationMs) !== null && _a !== void 0 ? _a : 5000) : 40;
+    // Dedupe step names when multiple inputs share a basename.
+    const usedNames = new Set();
+    const claim = (name) => {
+        let candidate = name;
+        let i = 2;
+        while (usedNames.has(candidate)) {
+            candidate = `${name.slice(0, 128 - String(i).length - 1)}_${i}`;
+            i++;
+        }
+        usedNames.add(candidate);
+        return candidate;
+    };
+    const steps = [];
+    for (const input of cfg.inputs) {
+        const slug = (0, template_utils_1.slugifyAssetKeyFromPath)(input);
+        const landscapeName = claim(`${slug}__landscape`);
+        const portraitName = claim(`${slug}__portrait`);
+        const landscapeDoc = await renderOrientationForInput(input, cfg, pair, "landscape", ctx, mode);
+        const portraitDoc = await renderOrientationForInput(input, cfg, pair, "portrait", ctx, mode);
+        steps.push({
+            name: landscapeName,
+            label: landscapeName,
+            durationMs: stepDurationMs,
+            file: landscapeDoc,
+        });
+        steps.push({
+            name: portraitName,
+            label: portraitName,
+            durationMs: stepDurationMs,
+            file: portraitDoc,
+        });
+    }
+    return {
+        kind: "mosaic_pipeline",
+        version: 1,
+        emit: "multi",
+        steps,
+    };
+}
+/**
+ * Top-level dispatcher. Always returns a pipeline on success (even
+ * for a single input — 2 orientations means 2 steps). Returns an
+ * error mosaic when inputs are missing or no feasible grid pair
+ * exists in the search range. The `outputFormat` knob picks the mode:
+ * png → static contact sheets, mp4 → animated grids.
+ */
+async function renderScreencapGridAspectSafe(props, ctx) {
+    const mode = resolveMode(props);
+    const cfg = resolveConfig(props);
+    if (cfg.inputs.length === 0) {
+        return (0, template_utils_1.makeErrorMosaic)('Missing required "Source(s)": pick a folder, one or more files, or drag-and-drop.', {
+            title: "Screencap Grid — Aspect Safe",
+            width: ctx.target.width,
+            height: ctx.target.height,
+        });
+    }
+    if (cfg.countMax < cfg.countMin) {
+        return (0, template_utils_1.makeErrorMosaic)(`targetCellCountMax (${cfg.countMax}) must be >= targetCellCountMin (${cfg.countMin}).`, {
+            title: "Screencap Grid — Aspect Safe",
+            width: ctx.target.width,
+            height: ctx.target.height,
+        });
+    }
+    const pair = pickAspectSafePair(cfg);
+    if (!pair) {
+        return (0, template_utils_1.makeErrorMosaic)(`No feasible (landscape, portrait) grid pair found in cell-count range [${cfg.countMin}, ${cfg.countMax}] at landscape ${cfg.landscapeW}×${cfg.landscapeH} / portrait ${cfg.portraitW}×${cfg.portraitH}. Widen the range or enable letterbox.`, {
+            title: "Screencap Grid — Aspect Safe",
+            width: ctx.target.width,
+            height: ctx.target.height,
+        });
+    }
+    return buildAspectSafePipeline(cfg, pair, ctx, mode);
+}
+// ---- TEMPLATE ----
+exports.ScreencapGridAspectSafe = {
+    id: (0, types_1.asTemplateId)(ASPECT_SAFE_ID),
+    label: "Screencap Grid — Aspect Safe",
+    description: "Per source video, renders a coordinated landscape + portrait grid pair (same cell count, cells steered to the wanted shape — landscape/square/portrait presets or an exact ratio, default landscape 16:9). Multi-input renders 2 outputs per file. Renders static PNG contact sheets or animated MP4 grids via the Output knob.",
+    version: 1,
+    capabilities: { tier: "core" },
+    tags: ["media", "screencap", "aspect-safe", "multi-orientation", "creators", "developers", "contact-sheet", "thumbnails", "video"],
+    propsSchema,
+    // No `format` hint on purpose (watermark/trickplay/screencap precedent):
+    // the `outputFormat` knob picks png vs mp4 per render, and a template-level
+    // container hint would override the user's `-o` extension in
+    // `resolveOutputFormat`. Each rendered step document declares its own format.
+    outputHints: {
+        format: { kind: "image", container: "png" },
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 5000,
+    },
+    defaultProps: { debugGeometry: false, ...SHARED_DEFAULTS },
+    render(props, ctx) {
+        return renderScreencapGridAspectSafe(props, ctx);
+    },
+    // Onboarding surfaces. Editor-only stand-ins — they never enter the render
+    // path, and `render` keeps its fail-fast contract untouched.
+    renderCover(_props, ctx) {
+        return (0, screencap_grid_aspect_safe_cover_1.renderScreencapGridAspectSafeCover)(ctx);
+    },
+    renderTutorial(_props, ctx) {
+        return (0, screencap_grid_aspect_safe_tutorial_1.renderScreencapGridAspectSafeTutorial)(ctx);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.ScreencapGridAspectSafe);

package/dist/m0saic/media/scroll_wall/index.d.ts

@@ -0,0 +1 @@
+export { ScrollWallV1, type ScrollWallProps } from "./v1";

package/dist/m0saic/media/scroll_wall/index.js

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