@m0saic/templates 0.2.0

package/dist/m0saic/media/screencap_grid/v2/screencap-grid.js

@@ -0,0 +1,615 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreencapGridV2 = exports.fColor = exports.fEnum = exports.fNum = exports.fBool = void 0;
+exports.paneLineEmBudget = paneLineEmBudget;
+exports.ellipsizeMiddleEm = ellipsizeMiddleEm;
+exports.computeGridTileRects = computeGridTileRects;
+exports.customGridTileInset = customGridTileInset;
+exports.renderScreencapGridV2 = renderScreencapGridV2;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const dsl_1 = require("@m0saic/dsl");
+const template_utils_1 = require("@m0saic/template-utils");
+// Editor-only onboarding surfaces (renderCover / renderTutorial). Kept in
+// sibling modules so this file stays about the grid itself.
+const screencap_grid_cover_1 = require("./screencap-grid-cover");
+const screencap_grid_tutorial_1 = require("./screencap-grid-tutorial");
+// Import internal subtemplate for registration side-effect
+const info_pane_1 = require("../internal/info_pane");
+// Shared, math-neutral helpers hosted by the (deprecated) v1 module — the
+// same reuse the aspect-safe sibling does. The deprecated part of v1 is its
+// ideal-cell inset math, not these formatters.
+const screencap_grid_1 = require("../v1/screencap-grid");
+const SCREENCAP_GRID_V2_ID = "@m0saic/media/screencap_grid/v2";
+// Tiny field-entry helpers (the alpine `_shared/alpine-anim` shapes, kept
+// local — the media pack doesn't import alpine's shared module).
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const fBool = (label, description = "") => ({ type: "boolean", required: false, description, meta: { ui: { label } } });
+exports.fBool = fBool;
+const fNum = (label, description = "", control, constraints) => ({ type: "number", required: false, description, meta: { ...(constraints ? { constraints } : {}), ...(control ? { control } : {}), ui: { label } } });
+exports.fNum = fNum;
+const fEnum = (label, oneOf, description = "") => ({ type: "string", required: false, description, meta: { constraints: { oneOf }, ui: { label } } });
+exports.fEnum = fEnum;
+const fColor = (label, description = "") => ({ type: "string", required: false, description, meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label } } });
+exports.fColor = fColor;
+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. A single file renders one
+    // grid; multiple fan out as an `emit: "multi"` pipeline (one render per
+    // file).
+    sourceIds: {
+        type: "media[]",
+        required: true,
+        description: "Source video(s) for the grid — pick a folder, one or more files, or drag-and-drop. One render per file (emit:multi when >1).",
+        meta: {
+            ui: { label: "Source(s)", order: 1 },
+            control: { multiple: true, picker: "folder", accept: ["video"] },
+        },
+    },
+    // Reserved prop-bag convention (trickplay 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 a static contact sheet; "mp4" renders an animated grid where each tile plays from its timestamp.',
+        meta: {
+            constraints: { oneOf: ["png", "mp4"] },
+            ui: { label: "Output", order: 1 },
+        },
+    },
+    rows: {
+        type: "number",
+        required: false,
+        description: "Number of rows in the screenshot grid.",
+        meta: { constraints: { min: 1, max: 20 }, ui: { label: "Rows", order: 1 } },
+    },
+    cols: {
+        type: "number",
+        required: false,
+        description: "Number of columns in the screenshot grid.",
+        meta: { constraints: { min: 1, max: 20 }, ui: { label: "Cols", order: 2 } },
+    },
+    // ── Collapsible groups (`type:"group"` + `fields` — folds in Make AND
+    //    Compose; the one grouping mechanism). ──
+    infoPane: {
+        type: "group",
+        required: false,
+        description: "Info pane with filename + ffprobe metadata above the grid.",
+        meta: { ui: { label: "Info Pane", order: 3, collapsedByDefault: true } },
+        fields: {
+            show: (0, exports.fBool)("Show", "Show the info pane above the grid."),
+            align: (0, exports.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: 4, collapsedByDefault: true } },
+        fields: {
+            show: (0, exports.fBool)("Show", "Overlay a timestamp in each tile."),
+            corner: (0, exports.fEnum)("Corner", ["tl", "tr", "bl", "br"], "Which corner the chip sits in."),
+            color: (0, exports.fColor)("Color", "Timestamp text color."),
+            bgColor: (0, exports.fColor)("Background", "Chip background behind the glyphs. Defaults to black; \"none\" is transparent."),
+        },
+    },
+    tiles: {
+        type: "group",
+        required: false,
+        description: "Tile gap + fill behavior.",
+        meta: { ui: { label: "Tiles", order: 5, collapsedByDefault: true } },
+        fields: {
+            gapPx: (0, exports.fNum)("Gap (px)", "Gap between tiles, in pixels (exact at every canvas).", { flavor: "slider", step: 1, unit: "px" }, { min: 0, max: 40 }),
+            fit: (0, exports.fEnum)("Fit", ["cover", "contain"], "cover crops to fill; contain letterboxes the whole frame."),
+        },
+    },
+    advanced: {
+        type: "group",
+        required: false,
+        description: "Escape hatches.",
+        meta: { ui: { label: "Advanced", order: 6, collapsedByDefault: true } },
+        fields: {
+            customGrid: {
+                type: "m0",
+                required: false,
+                description: "Custom m0 layout for the grid (overrides rows/cols). One tile is bound per cell, in order — give some cells emphasis by sizing them. Other knobs still apply.",
+                meta: { control: { placeholder: "e.g. 2(3(F,F,F),3(F,>,F))" }, ui: { label: "Custom Grid" } },
+            },
+        },
+    },
+    debugGeometry: {
+        type: "boolean",
+        required: false,
+        description: "Dev-only geometry contract: assert every tile's computed rect survived to the pixels at this canvas; on violation render a GEOMETRY_CONTRACT error mosaic. Deterministic default false; production never sets it.",
+        meta: { ui: { label: "Debug geometry", order: 1, collapsedByDefault: true } },
+    },
+});
+// ---- INFO-PANE TEXT FIT ----
+/** The info pane's horizontal text padding fraction (info_pane.ts `padding.x`). */
+const PANE_PAD_X = 0.015;
+/** Average-glyph width heuristic — the tutorial text-fit contract constant. */
+const EM_WIDTH_RATIO = 0.62;
+/** Em budget for one pane line at this canvas width and font size. */
+function paneLineEmBudget(canvasW, fontSize) {
+    return (canvasW * (1 - 2 * PANE_PAD_X)) / (fontSize * EM_WIDTH_RATIO);
+}
+/**
+ * Middle-ellipsize to an em budget, keeping the TAIL — for filenames, where
+ * the extension and trailing qualifiers are the part worth preserving.
+ * Script-aware via `textEmUnits` (CJK counts wide). Half-unit tolerance so
+ * exact-budget strings keep their last char (the donut fitToHole lesson).
+ */
+function ellipsizeMiddleEm(text, maxUnits) {
+    if ((0, template_utils_1.textEmUnits)(text) <= maxUnits + 0.5)
+        return text;
+    const chars = [...text];
+    const tailChars = chars.slice(-10);
+    const tailUnits = (0, template_utils_1.textEmUnits)(tailChars.join(""));
+    let head = "";
+    let used = 1 + tailUnits; // the ellipsis + the kept tail
+    for (const ch of chars) {
+        const u = (0, template_utils_1.textEmUnits)(ch);
+        if (used + u > maxUnits)
+            break;
+        head += ch;
+        used += u;
+    }
+    return `${head}…${tailChars.join("")}`;
+}
+/**
+ * Exact integer tile rects for a rows × cols grid filling the region below
+ * the info pane. Cell boundaries are proportional rounds of the region
+ * (`round(i · span / n)` — cells differ by at most 1px); interior boundaries
+ * carve the gap `floor(gap/2)` / `ceil(gap/2)` between the two neighbors so
+ * adjacent painted tiles are EXACTLY `tileGapPx` apart (odd gaps included).
+ * Outer edges are full-bleed (row 0 hugs the pane; the grid runs edge to
+ * edge). The gap is clamped per axis so no tile collapses below 1px.
+ *
+ * Row-major order (matches the tile → timestamp source pairing).
+ */
+function computeGridTileRects(args) {
+    const { canvasW, canvasH, paneHeightPx, rows, cols, tileGapPx } = args;
+    const gridH = canvasH - paneHeightPx;
+    const xs = Array.from({ length: cols + 1 }, (_, c) => Math.round((c * canvasW) / cols));
+    const ys = Array.from({ length: rows + 1 }, (_, r) => paneHeightPx + Math.round((r * gridH) / rows));
+    const minSpan = (b) => Math.min(...b.slice(1).map((v, i) => v - b[i]));
+    const gapX = Math.max(0, Math.min(tileGapPx, minSpan(xs) - 1));
+    const gapY = Math.max(0, Math.min(tileGapPx, minSpan(ys) - 1));
+    const lead = (g) => Math.floor(g / 2);
+    const trail = (g) => Math.ceil(g / 2);
+    const rects = [];
+    for (let r = 0; r < rows; r++) {
+        const y = ys[r] + (r > 0 ? lead(gapY) : 0);
+        const y2 = ys[r + 1] - (r < rows - 1 ? trail(gapY) : 0);
+        for (let c = 0; c < cols; c++) {
+            const x = xs[c] + (c > 0 ? lead(gapX) : 0);
+            const x2 = xs[c + 1] - (c < cols - 1 ? trail(gapX) : 0);
+            rects.push({ x, y, w: x2 - x, h: y2 - y });
+        }
+    }
+    return rects;
+}
+/**
+ * Engine cap on a `placement.inset` edge fraction (core `assertFrac`).
+ * Mirrors `placeInsetRects`' guard — an emitted fraction above this would
+ * throw at render, so the carve is dropped on that axis instead.
+ */
+const INSET_CAP = 0.49;
+/**
+ * Per-frame gap inset for the CUSTOM-grid path, from the frame's ACTUAL
+ * rendered dims. Half-pixel-centered per side (`(n + 0.5) / dim` — plain
+ * `n / dim` floor-loses; see `placeInsetRects`), floor/ceil-split so a
+ * shared boundary's two carves sum to exactly `gapPx`, and edge-aware:
+ * sides on the grid-region boundary stay flush (full-bleed). Carves that
+ * would collapse the tile below 1px, or exceed the engine's inset cap,
+ * drop that axis's carve. Returns undefined when no side carves.
+ */
+function customGridTileInset(frame, gapPx, regionW, regionH) {
+    if (gapPx <= 0 || frame.width <= 0 || frame.height <= 0)
+        return undefined;
+    const lead = Math.floor(gapPx / 2);
+    const trail = Math.ceil(gapPx / 2);
+    // A frame's left/top edge carves `lead`, its right/bottom edge `trail` —
+    // the neighbor across the boundary carves the complement, summing to gapPx.
+    let left = frame.x > 0 ? lead : 0;
+    let right = frame.x + frame.width < regionW ? trail : 0;
+    let top = frame.y > 0 ? lead : 0;
+    let bottom = frame.y + frame.height < regionH ? trail : 0;
+    const frac = (n, dim) => (n === 0 ? 0 : (n + 0.5) / dim);
+    const axisOk = (a, b, dim) => a + b < dim && frac(a, dim) <= INSET_CAP && frac(b, dim) <= INSET_CAP;
+    if (!axisOk(left, right, frame.width)) {
+        left = 0;
+        right = 0;
+    }
+    if (!axisOk(top, bottom, frame.height)) {
+        top = 0;
+        bottom = 0;
+    }
+    if (left === 0 && right === 0 && top === 0 && bottom === 0)
+        return undefined;
+    return {
+        top: frac(top, frame.height),
+        right: frac(right, frame.width),
+        bottom: frac(bottom, frame.height),
+        left: frac(left, frame.width),
+    };
+}
+/** 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 document declares for its mode. Baked
+ * per-doc (watermark/trickplay's per-step-format precedent) so under
+ * `emit: "multi"` every step switches the command build into the right
+ * graph mode, and hosts reading the resolved renderable (e.g. the Run
+ * view's extension pick) see the authored container.
+ */
+function formatForMode(mode) {
+    return mode === "animated"
+        ? { kind: "video", container: "mp4" }
+        : { kind: "image", container: "png" };
+}
+/**
+ * Resolve the effective input list from props. Returns `[]` when
+ * `sourceIds` is empty/unset — callers surface that as a fail-fast error.
+ */
+function resolveInputs(props) {
+    if (props.sourceIds && props.sourceIds.length > 0)
+        return props.sourceIds;
+    return [];
+}
+/**
+ * Resolve grouped props → the flat internal knob shape. Precedence per knob:
+ * grouped value → legacy flat value (see {@link ScreencapGridV2LegacyProps})
+ * → default. The gap additionally bridges v1's even-older FRACTIONAL
+ * `tileGap` (≈ fraction of a 1080p-ish cell) so ancient docs don't snap to 0.
+ */
+function resolveV2Knobs(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;
+    const legacy = props;
+    const gapPx = (_b = (_a = props.tiles) === null || _a === void 0 ? void 0 : _a.gapPx) !== null && _b !== void 0 ? _b : legacy.tileGapPx;
+    const legacyFraction = typeof legacy.tileGap === "number" && legacy.tileGap > 0
+        ? Math.round(legacy.tileGap * 480)
+        : undefined;
+    return {
+        rows: (_c = props.rows) !== null && _c !== void 0 ? _c : 4,
+        cols: (_d = props.cols) !== null && _d !== void 0 ? _d : 4,
+        withInfoPane: (_g = (_f = (_e = props.infoPane) === null || _e === void 0 ? void 0 : _e.show) !== null && _f !== void 0 ? _f : legacy.withInfoPane) !== null && _g !== void 0 ? _g : true,
+        headerAlign: (_k = (_j = (_h = props.infoPane) === null || _h === void 0 ? void 0 : _h.align) !== null && _j !== void 0 ? _j : legacy.headerAlign) !== null && _k !== void 0 ? _k : "left",
+        withTileTimestamp: (_o = (_m = (_l = props.timestamps) === null || _l === void 0 ? void 0 : _l.show) !== null && _m !== void 0 ? _m : legacy.withTileTimestamp) !== null && _o !== void 0 ? _o : true,
+        timestampCorner: (_r = (_q = (_p = props.timestamps) === null || _p === void 0 ? void 0 : _p.corner) !== null && _q !== void 0 ? _q : legacy.timestampCorner) !== null && _r !== void 0 ? _r : "br",
+        timestampColor: (_u = (_t = (_s = props.timestamps) === null || _s === void 0 ? void 0 : _s.color) !== null && _t !== void 0 ? _t : legacy.timestampColor) !== null && _u !== void 0 ? _u : "#ffffff",
+        timestampBgColor: (_x = (_w = (_v = props.timestamps) === null || _v === void 0 ? void 0 : _v.bgColor) !== null && _w !== void 0 ? _w : legacy.timestampBgColor) !== null && _x !== void 0 ? _x : "#000000",
+        tileGapPx: typeof gapPx === "number" && gapPx >= 0 ? gapPx : (legacyFraction !== null && legacyFraction !== void 0 ? legacyFraction : 2),
+        tileFit: (_0 = (_z = (_y = props.tiles) === null || _y === void 0 ? void 0 : _y.fit) !== null && _z !== void 0 ? _z : legacy.tileFit) !== null && _0 !== void 0 ? _0 : "cover",
+        customGridRaw: (_2 = (_1 = props.advanced) === null || _1 === void 0 ? void 0 : _1.customGrid) !== null && _2 !== void 0 ? _2 : legacy.customGrid,
+    };
+}
+/**
+ * Resolve the optional custom-grid m0. Accepts a bare m0 or a pasted `.m0`
+ * file — strips `#` header comment lines and blank lines. Returns null when
+ * empty (use the generated rows × cols grid).
+ */
+function resolveCustomGrid(raw) {
+    if (!raw)
+        return null;
+    const m0 = raw
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith("#"))
+        .join("");
+    return m0.length > 0 ? m0 : null;
+}
+/**
+ * Top-level dispatcher.
+ *
+ * - 0 inputs → fail-fast error mosaic.
+ * - 1 input → single `MosaicDocument`.
+ * - N inputs → `MosaicDocumentPipeline` with `emit: "multi"`,
+ *              one step per input.
+ *
+ * The `outputFormat` knob picks the mode: png → static contact sheet,
+ * mp4 → animated grid.
+ */
+async function renderScreencapGridV2(props, ctx) {
+    const mode = resolveMode(props);
+    const inputs = resolveInputs(props);
+    if (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",
+            width: ctx.target.width,
+            height: ctx.target.height,
+        });
+    }
+    if (inputs.length === 1) {
+        return renderScreencapGridForInput(inputs[0], props, ctx, mode);
+    }
+    return buildMultiInputPipeline(inputs, props, ctx, mode);
+}
+/**
+ * Build the `emit: "multi"` pipeline that fans out to one render per
+ * input. Each step's `file` is a single-input MosaicDocument; the step's
+ * `name` and `label` are derived from the input filename so the CLI's
+ * `--output-pattern {{label}}` slot has something meaningful to write.
+ */
+async function buildMultiInputPipeline(inputs, props, ctx, mode) {
+    var _a;
+    const stepNames = (0, template_utils_1.buildStepNames)(inputs);
+    // Static sheets are single-frame renders — a fixed nominal duration
+    // (trickplay's image-step precedent); animated steps track the target.
+    const stepDurationMs = mode === "animated" ? ((_a = ctx.target.durationMs) !== null && _a !== void 0 ? _a : 5000) : 40;
+    const steps = [];
+    for (let i = 0; i < inputs.length; i++) {
+        const file = await renderScreencapGridForInput(inputs[i], props, ctx, mode);
+        steps.push({
+            name: stepNames[i],
+            label: stepNames[i],
+            durationMs: stepDurationMs,
+            file,
+        });
+    }
+    return {
+        kind: "mosaic_pipeline",
+        version: 1,
+        emit: "multi",
+        steps,
+    };
+}
+/**
+ * Render a single screencap-grid document for one input path. Pulled out
+ * of {@link renderScreencapGridV2} so the multi-input path can reuse it
+ * per input.
+ */
+async function renderScreencapGridForInput(sourceId, props, ctx, mode) {
+    var _a, _b, _c;
+    // `sourceId` is, by current convention, whatever string the caller
+    // passed (in the editor / CLI today this is an absolute filesystem path,
+    // not a clean id). `ctx.media` is keyed by that same raw string, so the
+    // metadata probe has to use it as-is. But the OUTGOING manifest key must
+    // be a safe slug — paths with spaces / drive letters / Unicode would fail
+    // ASSET_KEY_PATTERN at plan-build.
+    const ctxMediaKey = (0, types_1.asAssetId)(sourceId);
+    const sourceAssetId = (0, types_1.asAssetId)((0, template_utils_1.slugifyAssetKeyFromPath)(sourceId));
+    const meta = ctx.media[ctxMediaKey];
+    const { rows, cols, withInfoPane, headerAlign, withTileTimestamp, timestampCorner, timestampColor, timestampBgColor, tileGapPx, tileFit, customGridRaw, } = resolveV2Knobs(props);
+    const canvasW = ctx.target.width;
+    const canvasH = ctx.target.height;
+    // Escape hatch: a custom m0 layout replaces the generated rows × cols grid.
+    const customGridM0 = resolveCustomGrid(customGridRaw);
+    if (customGridM0 && !(0, dsl_1.isValidM0String)(customGridM0)) {
+        return (0, template_utils_1.makeErrorMosaic)("Custom Grid is not a valid m0 string.", {
+            title: "Screencap Grid",
+            width: canvasW,
+            height: canvasH,
+        });
+    }
+    const children = {};
+    // Info-pane header height (px). Content-driven; fonts are baked from the
+    // FULL canvas height (see info_pane.ts), so the pane height and its font
+    // sizes stay consistent.
+    let paneHeightPx = 0;
+    let infoTitle = "";
+    let infoMeta = "";
+    if (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));
+        // Floor at 1px so `withInfoPane` always reserves a pane frame — keeps
+        // the source array aligned with the rendered frames even on
+        // pathologically small canvases.
+        paneHeightPx = Math.max(1, Math.round(canvasH * ratio));
+        // Fit-first: the pane draws LITERAL text at fixed fonts — a long
+        // filename or a dense metadata line overruns the canvas silently in
+        // the CLI (the gate-16 text-clip class). Title keeps its tail (the
+        // extension is the informative part); metadata lines end-ellipsize.
+        // Never print a filesystem PATH as the title: when originalFileName is
+        // absent (thin host probes), formatInfoLines falls back to the raw
+        // sourceId — basename-ify before fitting (string split; node:path is
+        // web-forbidden here).
+        const titleBase = ((_a = info.title.split("/").pop()) === null || _a === void 0 ? void 0 : _a.split("\\").pop()) || info.title;
+        infoTitle = ellipsizeMiddleEm(titleBase, paneLineEmBudget(canvasW, (0, screencap_grid_1.infoPaneTitleFontSize)(canvasH)));
+        const metaBudget = paneLineEmBudget(canvasW, (0, screencap_grid_1.infoPaneMetaFontSize)(canvasH));
+        infoMeta = 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");
+    }
+    // The grid always fills the canvas: full width × the area below the info
+    // pane. Fail fast when the canvas cannot give every row/col at least 1px.
+    const gridH = canvasH - paneHeightPx;
+    if (!customGridM0 && (gridH < rows || canvasW < cols)) {
+        return (0, template_utils_1.makeErrorMosaic)(`Canvas ${canvasW}×${canvasH} is too small for a ${rows}×${cols} grid${withInfoPane ? " below the info pane" : ""}.`, { title: "Screencap Grid", width: canvasW, height: canvasH });
+    }
+    if (withInfoPane) {
+        // The info pane spans the full canvas width; height stays canvasH so
+        // 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: infoTitle, metadata: infoMeta, paneHeight: paneHeightPx, align: headerAlign }, ctx, { slot: { width: canvasW, height: canvasH } });
+        children["info-pane"] = infoPaneFile;
+    }
+    const isVideo = (meta === null || meta === void 0 ? void 0 : meta.kind) === "video" && meta.durationMs != null && meta.durationMs > 0;
+    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 mediaTileSource = (t, inset) => ({
+        type: "media",
+        mediaType,
+        assetId: sourceAssetId,
+        placement: { fit: tileFit, ...(inset ? { inset } : {}) },
+        ...(isVideo
+            ? {
+                playback: mode === "animated"
+                    ? { clipStartMs: t }
+                    : { clipStartMs: t, clipDurationMs: frameMs, loopMode: "freeze" },
+                audio: { enabled: false },
+            }
+            : {}),
+        editor: { owner: "template" },
+    });
+    const timestampSource = (t) => (0, screencap_grid_1.buildTimestampSource)({
+        t,
+        mode,
+        isVideo,
+        corner: timestampCorner,
+        color: timestampColor,
+        bgColor: timestampBgColor,
+    });
+    // Mint the file asset for the source media so this document is hermetic
+    // when used as the root renderable (e.g. via CLI `make`). When nested as
+    // a child, the parent's manifest entry under the same assetId is identical
+    // (path + mediaType derived from the same sourceId), so scope merge is a
+    // no-op rather than a conflict.
+    const assets = {
+        [sourceAssetId]: {
+            kind: "file",
+            path: sourceId,
+            mediaType,
+        },
+    };
+    const format = formatForMode(mode);
+    if (customGridM0) {
+        // ── Custom-grid path: authored m0 verbatim, gap as fixed per-frame inset ──
+        const frames = (0, dsl_1.parseM0StringToRenderFrames)(customGridM0, canvasW, gridH);
+        const rectByLogical = new Map();
+        for (const f of frames) {
+            rectByLogical.set(f.logicalIndex, { x: f.x, y: f.y, width: f.width, height: f.height });
+        }
+        const N = frames.length;
+        const timestamps = isVideo ? (0, screencap_grid_1.computeTimestamps)(N, meta.durationMs) : [];
+        const sources = [];
+        if (withInfoPane)
+            sources.push(paneSource);
+        for (let i = 0; i < N; i++) {
+            const t = isVideo ? timestamps[i] : 0;
+            const frame = rectByLogical.get(i);
+            const inset = frame
+                ? customGridTileInset(frame, tileGapPx, canvasW, gridH)
+                : undefined;
+            sources.push(mediaTileSource(t, inset));
+            if (withTileTimestamp) {
+                // Same inset on the chip so it hugs the visible (gap-carved) tile —
+                // wired at SOURCE level (layer-level placement ignores inset), the
+                // same clone-and-wire move placeInsetPieces does.
+                const ts = timestampSource(t);
+                sources.push(inset ? { ...ts, placement: { inset } } : ts);
+            }
+        }
+        const m0 = (0, screencap_grid_1.assembleScreencapM0)({
+            rows, cols, paneHeightPx, gridH, withTileTimestamp, gridM0: customGridM0,
+        });
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            sources,
+            assets,
+            m0: (0, dsl_stdlib_1.toM0String)(m0, "ScreencapGrid"),
+            children,
+            format,
+            // Doc-level disable STRIPS the track (`-an`). The source-level knob
+            // on each tile only mutes the mix contribution — alone, an animated
+            // grid ships a silent placeholder audio track (the gate-20 class).
+            ...(mode === "animated" ? { audio: { mode: "off" } } : {}),
+        };
+    }
+    // ── Generated-grid path: exact pixel rects → inset-recovery placement ──
+    const tileRects = computeGridTileRects({
+        canvasW, canvasH, paneHeightPx, rows, cols, tileGapPx,
+    });
+    const N = tileRects.length;
+    const timestamps = isVideo ? (0, screencap_grid_1.computeTimestamps)(N, meta.durationMs) : [];
+    const pieces = [];
+    if (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: mediaTileSource(t) });
+        if (withTileTimestamp) {
+            // Same rect at importance 1 → guaranteed to paint above its tile; the
+            // colliding cells spill to an overlay layer by design.
+            pieces.push({
+                rect: { x: r.x, y: r.y, w: r.w, h: r.h, importance: 1 },
+                source: timestampSource(t),
+            });
+        }
+    }
+    const placed = (0, template_utils_1.placeInsetPieces)({ rootW: canvasW, rootH: canvasH, pieces });
+    const doc = {
+        kind: "mosaic_document",
+        version: 1,
+        sources: placed.sources,
+        assets,
+        m0: placed.m0,
+        children,
+        format,
+        // Doc-level disable STRIPS the track (`-an`) — see the custom-grid
+        // return above for why the source-level mute alone isn't enough.
+        ...(mode === "animated" ? { audio: { mode: "off" } } : {}),
+    };
+    // Dev tripwire: `debugGeometry` falsy (the default) → returns `doc`
+    // untouched at zero cost.
+    return (0, template_utils_1.withGeometryContract)(doc, ctx, {
+        templateId: SCREENCAP_GRID_V2_ID,
+        expectations: placed.expectations,
+        debug: props.debugGeometry === true,
+    });
+}
+// ---- TEMPLATE ----
+const SHARED_DEFAULTS = {
+    outputFormat: "png",
+    rows: 4,
+    cols: 4,
+    infoPane: { show: true, align: "left" },
+    timestamps: { show: true, corner: "br", color: "#ffffff", bgColor: "#000000" },
+    tiles: { gapPx: 2, fit: "cover" },
+};
+exports.ScreencapGridV2 = {
+    id: (0, types_1.asTemplateId)(SCREENCAP_GRID_V2_ID),
+    label: "Screencap Grid",
+    description: "Displays formatted ffprobe info in a top pane with a rows x cols grid of the same media below. Renders a static PNG contact sheet or an animated MP4 grid via the Output knob. v2 lays the pane and tiles out as exact pixel rects via inset-recovery placement, so tile gaps are pixel-exact at every canvas.",
+    version: 2,
+    capabilities: { tier: "core" },
+    tags: ["media", "screencap", "creators", "developers", "contact-sheet", "thumbnails", "video"],
+    propsSchema,
+    // No `format` hint on purpose (watermark/trickplay 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 doc 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 renderScreencapGridV2(props, ctx);
+    },
+    // Onboarding surfaces. Both are editor-only stand-ins — they never enter the
+    // render path, and `render` above keeps its fail-fast contract untouched
+    // (CLI, nested renders, and Make after the first prop edit are unchanged).
+    renderCover(_props, ctx) {
+        return (0, screencap_grid_cover_1.renderScreencapGridV2Cover)(ctx);
+    },
+    renderTutorial(_props, ctx) {
+        return (0, screencap_grid_tutorial_1.renderScreencapGridV2Tutorial)(ctx);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.ScreencapGridV2);

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

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

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

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

package/dist/m0saic/media/screencap_grid_aspect_safe/v1/index.d.ts

@@ -0,0 +1 @@
+export { ScreencapGridAspectSafe, type ScreencapGridAspectSafeProps, } from "./screencap-grid-aspect-safe";

package/dist/m0saic/media/screencap_grid_aspect_safe/v1/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreencapGridAspectSafe = void 0;
+var screencap_grid_aspect_safe_1 = require("./screencap-grid-aspect-safe");
+Object.defineProperty(exports, "ScreencapGridAspectSafe", { enumerable: true, get: function () { return screencap_grid_aspect_safe_1.ScreencapGridAspectSafe; } });

package/dist/m0saic/media/screencap_grid_aspect_safe/v1/screencap-grid-aspect-safe-cover.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Aspect-safe screencap grid — the editor first-open cover.
+ *
+ * Mirrors the screencap_grid/v2 cover the founder approved (gate 24 —
+ * "i quite like this cover"): an instruction chat-pane beside a dominant
+ * sample, on the shared onboarding theme. The hero here is the template's
+ * OWN registered preview — the coordinated landscape + portrait pair —
+ * because the pair IS the pitch.
+ *
+ * Node contexts (CLI, electron main) read the bundled pair-sheet.jpg via
+ * __dirname string concat (the highlights web-safe pattern — no node:path,
+ * asar rewrite inlined); the browser uses the served template-assets URL.
+ */
+import type { MosaicDocument, MosaicEngineContext } from "@m0saic/types";
+/** The registered pair preview, served for browser contexts. */
+export declare const ASPECT_SAFE_COVER_PREVIEW_URL = "/template-assets/assets/templates/@m0saic__media__screencap_grid_aspect_safe__v1/preview.png";
+/** Production cover: an instruction pane beside the registered PAIR preview. */
+export declare function renderScreencapGridAspectSafeCover(ctx: MosaicEngineContext): MosaicDocument;