@m0saic/templates 0.2.0

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

@@ -0,0 +1,690 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreencapGrid = void 0;
+exports.buildTimestampSource = buildTimestampSource;
+exports.infoPaneTitleFontSize = infoPaneTitleFontSize;
+exports.infoPaneMetaFontSize = infoPaneMetaFontSize;
+exports.estimateInfoPaneHeight = estimateInfoPaneHeight;
+exports.formatInfoLines = formatInfoLines;
+exports.assembleScreencapM0 = assembleScreencapM0;
+exports.computeTimestamps = computeTimestamps;
+exports.renderScreencapGrid = renderScreencapGrid;
+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");
+// Import internal subtemplate for registration side-effect
+const info_pane_1 = require("../internal/info_pane");
+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)" },
+            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" },
+        },
+    },
+    rows: {
+        type: "number",
+        required: false,
+        description: "Number of rows in the screenshot grid.",
+        meta: { constraints: { min: 1, max: 20 }, ui: { label: "Rows" } },
+    },
+    cols: {
+        type: "number",
+        required: false,
+        description: "Number of columns in the screenshot grid.",
+        meta: { constraints: { min: 1, max: 20 }, ui: { label: "Cols" } },
+    },
+    withInfoPane: {
+        type: "boolean",
+        required: false,
+        description: "Show the info pane with filename + metadata above the grid.",
+        meta: { ui: { label: "Info Pane" } },
+    },
+    headerAlign: {
+        type: "string",
+        required: false,
+        description: "Alignment of the info-pane text (filename + metadata).",
+        meta: {
+            constraints: { oneOf: ["left", "center", "right"] },
+            ui: { label: "Header Align" },
+        },
+    },
+    withTileTimestamp: {
+        type: "boolean",
+        required: false,
+        description: "Overlay a timestamp in each tile.",
+        meta: { ui: { label: "Tile Timestamp" } },
+    },
+    timestampCorner: {
+        type: "string",
+        required: false,
+        description: "Which corner the per-tile timestamp sits in.",
+        meta: {
+            constraints: { oneOf: ["tl", "tr", "bl", "br"] },
+            ui: { label: "Timestamp Corner" },
+        },
+    },
+    timestampColor: {
+        type: "string",
+        required: false,
+        description: "Timestamp text color.",
+        meta: {
+            constraints: { isColor: true },
+            control: { colorPicker: true },
+            ui: { label: "Timestamp Color" },
+        },
+    },
+    timestampBgColor: {
+        type: "string",
+        required: false,
+        description: "Timestamp background color (chip behind the text).",
+        meta: {
+            constraints: { isColor: true },
+            control: { colorPicker: true },
+            ui: { label: "Timestamp Background" },
+        },
+    },
+    tileGapPx: {
+        type: "number",
+        required: false,
+        description: "Gap between tiles, in pixels.",
+        meta: {
+            constraints: { min: 0, max: 40 },
+            control: { flavor: "slider", step: 1, unit: "px" },
+            ui: { label: "Tile Gap" },
+        },
+    },
+    tileFit: {
+        type: "string",
+        required: false,
+        description: "How each frame fills its tile. Cover crops to fill; contain letterboxes the whole frame.",
+        meta: {
+            constraints: { oneOf: ["contain", "cover"] },
+            ui: { label: "Tile Fit" },
+        },
+    },
+    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" },
+        },
+    },
+});
+// ---- HELPERS ----
+function pad2(n) {
+    return n < 10 ? `0${n}` : `${n}`;
+}
+function formatTimestamp(ms) {
+    const h = Math.floor(ms / 3600000);
+    const m = Math.floor((ms % 3600000) / 60000);
+    const s = Math.floor((ms % 60000) / 1000);
+    const frac = Math.round(ms % 1000);
+    return `${pad2(h)}:${pad2(m)}:${pad2(s)}.${String(frac).padStart(3, "0")}`;
+}
+/**
+ * Build a per-tile timestamp overlay text source. Shared by screencap_grid and
+ * the aspect-safe variant so corner placement, text color, and the
+ * behind-glyphs box background (drawtext `box`, NOT a full-rect fill) stay
+ * identical across both. `bgColor === "none"` → no box.
+ */
+function buildTimestampSource(opts) {
+    const { t, mode, isVideo, corner, color, bgColor } = opts;
+    const startSec = (t / 1000).toFixed(3);
+    // HH:MM:SS.mmm via FFmpeg text expansion.
+    const expr = `%{eif\\:(t+${startSec})/3600\\:d\\:2}:%{eif\\:mod((t+${startSec})/60\\,60)\\:d\\:2}:%{eif\\:mod(t+${startSec}\\,60)\\:d\\:2}.%{eif\\:mod((t+${startSec})*1000\\,1000)\\:d\\:3}`;
+    const hasBg = bgColor !== "none";
+    const style = {
+        fontSize: 18,
+        fontColor: color,
+        borderWidth: 0.003,
+        borderColor: "black@0.8",
+        ...(hasBg ? { boxColor: bgColor, boxBorderWidth: 6 } : {}),
+    };
+    const visual = { backgroundColor: "none" };
+    const hAlign = corner === "tr" || corner === "br" ? "right" : "left";
+    const vAlign = corner === "tl" || corner === "tr" ? "top" : "bottom";
+    const placement = { hAlign, vAlign, padding: { x: 0.02, y: 0.03 } };
+    const layer = mode === "animated"
+        ? { content: { kind: "expr", expr, eval: "frame" }, style, visual, placement }
+        : {
+            content: {
+                kind: "literal",
+                text: isVideo ? formatTimestamp(t) : "00:00:00.000",
+            },
+            style,
+            visual,
+            placement,
+        };
+    return {
+        type: "text",
+        renderMode: mode === "animated" ? { kind: "video" } : { kind: "image" },
+        layers: [layer],
+        editor: { owner: "template" },
+    };
+}
+function formatDuration(ms) {
+    // keep your original format for Duration line
+    const totalSec = ms / 1000;
+    const h = Math.floor(totalSec / 3600);
+    const m = Math.floor((totalSec % 3600) / 60);
+    const s = (totalSec % 60).toFixed(2);
+    if (h > 0)
+        return `${h}h ${m}m ${s}s`;
+    if (m > 0)
+        return `${m}m ${s}s`;
+    return `${s}s`;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(2)} KiB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(2)} MiB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+}
+function formatBitrate(bps) {
+    if (bps >= 1000000)
+        return `${(bps / 1000000).toFixed(1)} Mbit/s`;
+    if (bps >= 1000)
+        return `${(bps / 1000).toFixed(0)} kbit/s`;
+    return `${bps} bit/s`;
+}
+function commaNumber(n) {
+    return n.toLocaleString("en-US");
+}
+/**
+ * Best-effort bit depth from ffprobe pix_fmt string.
+ * Returns undefined when the format is unrecognized.
+ */
+function bitDepthFromPixFmt(pixFmt) {
+    if (!pixFmt)
+        return undefined;
+    if (/10le|10be|p010|p210|y210/.test(pixFmt))
+        return 10;
+    if (/12le|12be|p012|p212/.test(pixFmt))
+        return 12;
+    if (/16le|16be/.test(pixFmt))
+        return 16;
+    // Most common 8-bit formats
+    if (/^(yuv|yuvj|nv|rgb|bgr|gray|pal8|ya8|rgba|bgra)/.test(pixFmt))
+        return 8;
+    return undefined;
+}
+function formatSampleRate(hz) {
+    if (hz >= 1000 && hz % 1000 === 0)
+        return `${hz / 1000} kHz`;
+    if (hz >= 1000)
+        return `${(hz / 1000).toFixed(1)} kHz`;
+    return `${hz} Hz`;
+}
+// ---- Font sizing (shared between height estimation and info_pane rendering) ----
+/** Title font size derived from output height, not pane height. */
+function infoPaneTitleFontSize(targetH) {
+    return Math.max(16, Math.min(48, Math.round(targetH * 0.022)));
+}
+/** Metadata font size derived from output height, not pane height. */
+function infoPaneMetaFontSize(targetH) {
+    return Math.max(9, Math.min(20, Math.round(targetH * 0.012)));
+}
+/**
+ * Estimate the pixel height needed for the info pane content.
+ * Uses the same font-sizing formulas as info_pane.ts rendering.
+ */
+function estimateInfoPaneHeight(targetH, metaLineCount) {
+    const titleFs = infoPaneTitleFontSize(targetH);
+    const metaFs = infoPaneMetaFontSize(targetH);
+    const topPad = 6;
+    const titleLineH = Math.round(titleFs * 1.3);
+    const gap = Math.round(titleFs * 0.35);
+    const metaBlockH = metaLineCount > 0 ? Math.round(metaLineCount * metaFs * 1.45) : 0;
+    const bottomPad = 8;
+    return topPad + titleLineH + gap + metaBlockH + bottomPad;
+}
+function formatInfoLines(sourceId, meta) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
+    const title = (_a = meta.originalFileName) !== null && _a !== void 0 ? _a : sourceId;
+    const lines = [];
+    // -- Summary line: Duration | Size | Bitrate | Container --
+    const summaryParts = [];
+    if (meta.durationMs != null)
+        summaryParts.push(`Duration: ${formatDuration(meta.durationMs)}`);
+    if (((_b = meta.format) === null || _b === void 0 ? void 0 : _b.sizeBytes) != null)
+        summaryParts.push(`Size: ${formatBytes(meta.format.sizeBytes)} (${commaNumber(meta.format.sizeBytes)} bytes)`);
+    if (((_c = meta.format) === null || _c === void 0 ? void 0 : _c.bitRate) != null)
+        summaryParts.push(`Bitrate: ${formatBitrate(meta.format.bitRate)}`);
+    const containerName = (_e = (_d = meta.format) === null || _d === void 0 ? void 0 : _d.formatLongName) !== null && _e !== void 0 ? _e : (_f = meta.format) === null || _f === void 0 ? void 0 : _f.formatName;
+    if (containerName)
+        summaryParts.push(`Container: ${containerName}`);
+    if (summaryParts.length > 0)
+        lines.push(summaryParts.join("  |  "));
+    // -- Video stream line --
+    if (((_g = meta.video) === null || _g === void 0 ? void 0 : _g.codecName) || meta.hasVideo) {
+        const vParts = [];
+        const idx = (_h = meta.video) === null || _h === void 0 ? void 0 : _h.streamIndex;
+        vParts.push(idx != null ? `Stream ${idx} Video:` : "Video:");
+        if (meta.width || meta.height)
+            vParts.push(`${meta.width}x${meta.height}`);
+        if ((_j = meta.video) === null || _j === void 0 ? void 0 : _j.pixFmt)
+            vParts.push(meta.video.pixFmt);
+        const bd = bitDepthFromPixFmt((_k = meta.video) === null || _k === void 0 ? void 0 : _k.pixFmt);
+        if (bd != null)
+            vParts.push(`${bd}-bit`);
+        if (meta.fps != null)
+            vParts.push(`${meta.fps.toFixed(2)} fps`);
+        const codecLabel = (_m = (_l = meta.video) === null || _l === void 0 ? void 0 : _l.codecLongName) !== null && _m !== void 0 ? _m : (_o = meta.video) === null || _o === void 0 ? void 0 : _o.codecName;
+        if (codecLabel)
+            vParts.push(codecLabel);
+        if ((_p = meta.video) === null || _p === void 0 ? void 0 : _p.profile)
+            vParts.push(`(${meta.video.profile})`);
+        lines.push(vParts.join(" "));
+    }
+    // -- Audio stream line --
+    if (((_q = meta.audio) === null || _q === void 0 ? void 0 : _q.codecName) || meta.hasAudio) {
+        const aParts = [];
+        const idx = (_r = meta.audio) === null || _r === void 0 ? void 0 : _r.streamIndex;
+        aParts.push(idx != null ? `Stream ${idx} Audio:` : "Audio:");
+        if ((_s = meta.audio) === null || _s === void 0 ? void 0 : _s.channelLayout)
+            aParts.push(meta.audio.channelLayout);
+        else if ((_t = meta.audio) === null || _t === void 0 ? void 0 : _t.channels)
+            aParts.push(`${meta.audio.channels}ch`);
+        if ((_u = meta.audio) === null || _u === void 0 ? void 0 : _u.sampleRate)
+            aParts.push(formatSampleRate(meta.audio.sampleRate));
+        if ((_v = meta.audio) === null || _v === void 0 ? void 0 : _v.bitRate)
+            aParts.push(formatBitrate(meta.audio.bitRate));
+        const aCodecLabel = (_x = (_w = meta.audio) === null || _w === void 0 ? void 0 : _w.codecLongName) !== null && _x !== void 0 ? _x : (_y = meta.audio) === null || _y === void 0 ? void 0 : _y.codecName;
+        if (aCodecLabel)
+            aParts.push(aCodecLabel);
+        lines.push(aParts.join(" "));
+    }
+    // -- Chapters / Programs --
+    const extras = [];
+    if (meta.chapters && meta.chapters.length > 0)
+        extras.push(`Chapters: ${meta.chapters.length}`);
+    if (meta.programs && meta.programs.length > 0)
+        extras.push(`Programs: ${meta.programs.length}`);
+    if (extras.length > 0)
+        lines.push(extras.join("  |  "));
+    const filteredLines = lines.filter(Boolean);
+    const metadata = filteredLines.join("\n");
+    return { title, metadata, metaLineCount: filteredLines.length };
+}
+/**
+ * Assemble the layout m0: an optional info-pane row on top of a gutterless
+ * grid that fills the canvas. Frame order is `[info-pane, tile, tile, …]` so
+ * the caller's source array maps positionally. The grid is gutterless (the
+ * compact `equalSplit` path) — the inter-tile gap is a per-tile inset on the
+ * media sources, so it costs no DSL tokens here.
+ *
+ * `gridM0` overrides the generated `rows × cols` grid with a caller-supplied
+ * layout (the custom-grid escape hatch); the timestamp overlay + info-pane
+ * wrapping still apply on top.
+ *
+ * `paneHeightPx` / `gridH` are pixel heights summing to the canvas height, so
+ * the `[pane, grid]` split lands the grid on exactly `gridH`.
+ */
+function assembleScreencapM0(args) {
+    const { rows, cols, paneHeightPx, gridH, withTileTimestamp, gridM0 } = args;
+    // gridM0 is a caller-validated m0; cast to the branded type for the builders.
+    const bareGrid = (gridM0 !== null && gridM0 !== void 0 ? gridM0 : (0, dsl_stdlib_1.grid)({ rows, cols }).m0);
+    const gridStr = withTileTimestamp ? (0, dsl_stdlib_1.addOverlayToAllFrames)(bareGrid) : bareGrid;
+    if (paneHeightPx <= 0)
+        return gridStr;
+    return (0, dsl_stdlib_1.weightedSplit)([paneHeightPx, gridH], "row", {
+        claimants: ["F", gridStr],
+    });
+}
+/**
+ * Compute deterministic seek timestamps for N grid tiles.
+ * Returns timestamps in ms, strictly in (0, durationMs).
+ */
+function computeTimestamps(n, durationMs) {
+    const d = Math.max(0, durationMs);
+    // If duration is extremely small, just return midpoints clamped
+    if (d <= 2)
+        return Array.from({ length: n }, () => 1);
+    return Array.from({ length: n }, (_, i) => {
+        const t = ((i + 1) / (n + 1)) * d;
+        // clamp to (0, d)
+        return Math.min(d - 1, Math.max(1, Math.round(t)));
+    });
+}
+/** 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 the tile gap in pixels. `tileGapPx` is the current prop; older docs
+ * may carry the deprecated fractional `tileGap` — bridge it to an approximate
+ * pixel value (≈ fraction of a 1080p-ish cell) so they don't snap to 0.
+ */
+function resolveTileGapPx(props) {
+    if (typeof props.tileGapPx === "number" && props.tileGapPx >= 0) {
+        return props.tileGapPx;
+    }
+    const legacyFraction = props.tileGap;
+    if (typeof legacyFraction === "number" && legacyFraction > 0) {
+        return Math.round(legacyFraction * 480);
+    }
+    return SHARED_DEFAULTS.tileGapPx;
+}
+/**
+ * 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 renderScreencapGrid(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 renderScreencapGrid} so the multi-input path can reuse it
+ * per input.
+ */
+async function renderScreencapGridForInput(sourceId, props, ctx, mode) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    // `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 = (_a = props.rows) !== null && _a !== void 0 ? _a : 4;
+    const cols = (_b = props.cols) !== null && _b !== void 0 ? _b : 4;
+    const withInfoPane = (_c = props.withInfoPane) !== null && _c !== void 0 ? _c : true;
+    const headerAlign = (_d = props.headerAlign) !== null && _d !== void 0 ? _d : SHARED_DEFAULTS.headerAlign;
+    const withTileTimestamp = (_e = props.withTileTimestamp) !== null && _e !== void 0 ? _e : true;
+    const timestampCorner = (_f = props.timestampCorner) !== null && _f !== void 0 ? _f : SHARED_DEFAULTS.timestampCorner;
+    const tileGapPx = resolveTileGapPx(props);
+    const timestampColor = (_g = props.timestampColor) !== null && _g !== void 0 ? _g : SHARED_DEFAULTS.timestampColor;
+    const timestampBgColor = (_h = props.timestampBgColor) !== null && _h !== void 0 ? _h : SHARED_DEFAULTS.timestampBgColor;
+    const tileFit = (_j = props.tileFit) !== null && _j !== void 0 ? _j : SHARED_DEFAULTS.tileFit;
+    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(props.customGrid);
+    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
+            ? formatInfoLines(sourceId, meta)
+            : { title: `No metadata for sourceId=${sourceId}`, metadata: "", metaLineCount: 0 };
+        const ratio = Math.max(0.03, Math.min(0.25, estimateInfoPaneHeight(canvasH, info.metaLineCount) / canvasH));
+        // Floor at 1px so `withInfoPane` always reserves a pane frame — keeps
+        // the source array ([info-pane, media…]) aligned with the rendered
+        // frames even on pathologically small canvases.
+        paneHeightPx = Math.max(1, Math.round(canvasH * ratio));
+        infoTitle = info.title;
+        infoMeta = info.metadata;
+    }
+    // The grid always fills the canvas: full width × the area below the info
+    // pane. Gutterless cells; the gap is a per-tile inset (below).
+    const gridW = canvasW;
+    const gridH = Math.max(1, canvasH - paneHeightPx);
+    // Cell count + per-cell gap inset. Custom grid: one tile per rendered cell,
+    // gap derived from each cell's own pixel size (so uneven cells still get an
+    // even pixel gap). Generated grid: uniform rows × cols via gridCellInset.
+    let cellCount;
+    let tileInsetFor;
+    if (customGridM0) {
+        const frames = (0, dsl_1.parseM0StringToRenderFrames)(customGridM0, gridW, gridH);
+        cellCount = frames.length;
+        const dimsByLogical = new Map();
+        for (const f of frames)
+            dimsByLogical.set(f.logicalIndex, { width: f.width, height: f.height });
+        tileInsetFor = (i) => {
+            const f = dimsByLogical.get(i);
+            if (!f || tileGapPx <= 0 || f.width <= 0 || f.height <= 0)
+                return undefined;
+            return { x: (tileGapPx / 2) / f.width, y: (tileGapPx / 2) / f.height };
+        };
+    }
+    else {
+        cellCount = rows * cols;
+        const cellInset = (0, template_utils_1.gridCellInset)({ rows, cols, gridW, gridH, gapPx: tileGapPx });
+        tileInsetFor = (i) => cellInset(Math.floor(i / cols), i % cols);
+    }
+    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 N = cellCount;
+    const isVideo = (meta === null || meta === void 0 ? void 0 : meta.kind) === "video" && meta.durationMs != null && meta.durationMs > 0;
+    const timestamps = isVideo ? 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 / ((_l = (_k = meta === null || meta === void 0 ? void 0 : meta.fps) !== null && _k !== void 0 ? _k : ctx.target.fps) !== null && _l !== void 0 ? _l : 30)));
+    const sources = [];
+    if (withInfoPane) {
+        // 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).
+        sources.push({ type: "mosaic", ref: "info-pane", placement: { fit: "cover", focusY: 0 } });
+    }
+    for (let i = 0; i < N; i++) {
+        const t = isVideo ? timestamps[i] : 0;
+        const tileInset = tileInsetFor(i);
+        // Media tile
+        sources.push({
+            type: "media",
+            mediaType,
+            assetId: sourceAssetId,
+            placement: { fit: tileFit, ...(tileInset ? { inset: tileInset } : {}) },
+            ...(isVideo
+                ? {
+                    playback: mode === "animated"
+                        ? { clipStartMs: t }
+                        : { clipStartMs: t, clipDurationMs: frameMs, loopMode: "freeze" },
+                    audio: { enabled: false },
+                }
+                : {}),
+            editor: { owner: "template" },
+        });
+        // Timestamp overlay (corner + color + behind-glyphs box per props).
+        if (withTileTimestamp) {
+            sources.push(buildTimestampSource({
+                t,
+                mode,
+                isVideo,
+                corner: timestampCorner,
+                color: timestampColor,
+                bgColor: timestampBgColor,
+            }));
+        }
+    }
+    const m0saic = assembleScreencapM0({
+        rows, cols, paneHeightPx, gridH, withTileTimestamp,
+        ...(customGridM0 ? { gridM0: customGridM0 } : {}),
+    });
+    // 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,
+        },
+    };
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        sources,
+        assets,
+        m0: (0, dsl_stdlib_1.toM0String)(m0saic, "ScreencapGrid"),
+        children,
+        format: formatForMode(mode),
+    };
+}
+// ---- TEMPLATE ----
+const SHARED_DEFAULTS = {
+    outputFormat: "png",
+    rows: 4,
+    cols: 4,
+    withInfoPane: true,
+    headerAlign: "left",
+    withTileTimestamp: true,
+    timestampCorner: "br",
+    timestampColor: "#ffffff",
+    timestampBgColor: "none",
+    tileGapPx: 2,
+    tileFit: "cover",
+};
+exports.ScreencapGrid = {
+    id: (0, types_1.asTemplateId)("@m0saic/media/screencap_grid/v1"),
+    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.",
+    version: 1,
+    capabilities: { tier: "core" },
+    deprecated: {
+        reason: "Approximate gap math: the inter-tile gap rides as gridCellInset fractions computed against the IDEAL cell size, but the engine floors them against the QUANTIZED cells the equal split actually produced — under the content-driven info pane a 2px gap wobbles between 2px and 0px row to row, and plain n/cell fractions floor-lose even on exact cells. Kept as the canonical 'ideal-cell gap inset' reference — it is the math a template author naturally reaches for first. Use v2: the SAME picture with every painted rect computed in integer pixels and emitted via inset-recovery placement (placeInsetPieces, handbook §3c) — pixel-exact gaps at every canvas, bounded precision.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/media/screencap_grid/v2"),
+        since: "2026-07-21",
+    },
+    tags: ["media", "screencap"],
+    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: {
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 5000,
+    },
+    defaultProps: { ...SHARED_DEFAULTS },
+    render(props, ctx) {
+        return renderScreencapGrid(props, ctx);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.ScreencapGrid);