@m0saic/templates 0.2.0

package/dist/m0saic/collage/image-collage/v1/emit.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * DSL emission — packed spans → a ratio m0 + inset-wired sources.
+ *
+ * The base is a nested `weightedSplit` tree in UNIT WEIGHTS (basis ≤ the
+ * lattice dims, GCD-collapsed) reconstructed from the placed spans by n-ary
+ * guillotine decomposition: at every region, split at ALL full uncrossed
+ * lattice lines of one axis at once, alternate axes, recurse. Resolution-
+ * independent and composable — the polar opposite of the pixel-baked trace
+ * this template replaces (launder-ladder rung 1 + rung 2's gap-as-inset).
+ *
+ * Gutters and margins live entirely in the fiber: the emitted m0 is
+ * gutterless; each source carries a `latticeCellInset` retargeted inset that
+ * recovers the exact painted grid under the engine's floor math (pixel-exact
+ * gutters/margins at the emit canvas).
+ *
+ * Fillers (imageIndex < 0 — the tiler's never-expected escape) emit as `-`
+ * null tiles: no frame, no source, background shows through.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitLatticeM0 = emitLatticeM0;
+exports.emitCollageLayout = emitCollageLayout;
+const dsl_1 = require("@m0saic/dsl");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const isFiller = (p) => p.imageIndex < 0;
+/**
+ * Emit the unit-weight guillotine m0 for an exact cover of a cols×rows
+ * lattice. Throws on a non-exact or non-guillotine cover (the tiler
+ * guarantees both; a throw here means a tiler bug, not a render-time state).
+ */
+function emitLatticeM0(placed, cols, rows) {
+    if (placed.length === 0)
+        throw new Error("emitLatticeM0: no spans");
+    const area = placed.reduce((a, p) => a + p.cs * p.rs, 0);
+    if (area !== cols * rows)
+        throw new Error(`emitLatticeM0: cover area ${area} ≠ lattice ${cols}×${rows} = ${cols * rows}`);
+    const rects = placed.map((p) => ({
+        x0: p.c0,
+        y0: p.r0,
+        x1: p.c0 + p.cs,
+        y1: p.r0 + p.rs,
+        placed: p,
+    }));
+    const m0 = emitRegion(rects, 0, 0, cols, rows);
+    const v = (0, dsl_1.validateM0String)(m0);
+    if (!v.ok)
+        throw new Error(`emitLatticeM0: emitted invalid m0 (internal): ${JSON.stringify(v)}`);
+    return m0;
+}
+function emitRegion(rects, x0, y0, x1, y1) {
+    if (rects.length === 1) {
+        const r = rects[0];
+        if (r.x0 !== x0 || r.y0 !== y0 || r.x1 !== x1 || r.y1 !== y1)
+            throw new Error(`emitRegion: leaf span does not fill its region (internal)`);
+        return isFiller(r.placed) ? "-" : "1";
+    }
+    // Full uncrossed lattice lines per axis inside this region.
+    const vLines = [];
+    for (let x = x0 + 1; x < x1; x++)
+        if (rects.every((r) => r.x1 <= x || r.x0 >= x))
+            vLines.push(x);
+    const hLines = [];
+    for (let y = y0 + 1; y < y1; y++)
+        if (rects.every((r) => r.y1 <= y || r.y0 >= y))
+            hLines.push(y);
+    if (vLines.length === 0 && hLines.length === 0)
+        throw new Error(`emitRegion: region (${x0},${y0})–(${x1},${y1}) with ${rects.length} spans has no guillotine cut ` +
+            `(non-guillotine cover — tiler bug)`);
+    // n-ary split at ALL lines of the richer axis (rows win ties: shelf-first).
+    const useRows = hLines.length >= vLines.length;
+    const cuts = useRows ? hLines : vLines;
+    const bounds = useRows ? [y0, ...cuts, y1] : [x0, ...cuts, x1];
+    const weights = [];
+    const claimants = [];
+    for (let i = 0; i + 1 < bounds.length; i++) {
+        const lo = bounds[i];
+        const hi = bounds[i + 1];
+        weights.push(hi - lo);
+        const subset = rects.filter((r) => (useRows ? r.y0 >= lo && r.y1 <= hi : r.x0 >= lo && r.x1 <= hi));
+        if (subset.reduce((a, r) => a + (r.x1 - r.x0) * (r.y1 - r.y0), 0) !== (useRows ? (hi - lo) * (x1 - x0) : (hi - lo) * (y1 - y0)))
+            throw new Error("emitRegion: segment subset does not tile its slice (internal)");
+        claimants.push(useRows ? emitRegion(subset, x0, lo, x1, hi) : emitRegion(subset, lo, y0, hi, y1));
+    }
+    return String((0, dsl_stdlib_1.weightedSplit)(weights, useRows ? "row" : "col", { claimants }));
+}
+/**
+ * Emit the complete layout: m0, logicalIndex-aligned sources with retargeted
+ * insets, per-cell targets, and the null-space accounting. Pure; parses the
+ * emitted m0 once at the render canvas to bind frames ↔ spans ↔ insets.
+ */
+function emitCollageLayout(opts) {
+    const { placed, cols, rows, canvasW, canvasH, gutterXPx, gutterYPx, marginPx, sourceFor } = opts;
+    const m0 = emitLatticeM0(placed, cols, rows);
+    // The COMPLETE parse: its path-style stableKeys are the engine's canonical
+    // identity space — doc.labels keyed any other way would never resolve in
+    // the app or merge with the contract's backfill.
+    const parsed = (0, dsl_1.parseM0StringComplete)(m0, canvasW, canvasH);
+    if (!parsed.ok)
+        throw new Error("emitCollageLayout: emitted m0 failed to parse (internal)");
+    const frames = parsed.ir.renderFrames;
+    const real = placed.filter((p) => !isFiller(p));
+    if (frames.length !== real.length)
+        throw new Error(`emitCollageLayout: ${frames.length} parsed frames ≠ ${real.length} painted spans (internal)`);
+    // Bind each frame to its span by unit-space center containment — immune to
+    // the ±1px outside-in remainder placement of the raw split.
+    const spanAt = (cx, cy) => {
+        const uc = Math.min(cols - 1, Math.floor((cx / canvasW) * cols));
+        const ur = Math.min(rows - 1, Math.floor((cy / canvasH) * rows));
+        return real.find((p) => p.c0 <= uc && uc < p.c0 + p.cs && p.r0 <= ur && ur < p.r0 + p.rs);
+    };
+    const byLogical = [];
+    const seen = new Set();
+    for (const f of frames) {
+        const span = spanAt(f.x + f.width / 2, f.y + f.height / 2);
+        if (!span || seen.has(span))
+            throw new Error(`emitCollageLayout: frame↔span binding failed at logicalIndex ${f.logicalIndex} (internal)`);
+        seen.add(span);
+        byLogical[f.logicalIndex] = { frame: f, span };
+    }
+    const inset = (0, template_utils_1.latticeCellInset)({
+        cols,
+        rows,
+        canvasW,
+        canvasH,
+        gutterXPx,
+        gutterYPx,
+        marginPx,
+        cells: byLogical.map(({ frame, span }) => ({
+            unit: { c0: span.c0, r0: span.r0, cs: span.cs, rs: span.rs },
+            raw: { x: frame.x, y: frame.y, w: frame.width, h: frame.height },
+        })),
+    });
+    const sources = [];
+    const cells = [];
+    byLogical.forEach(({ frame, span }, li) => {
+        const base = sourceFor(span.imageIndex);
+        const placement = base.placement;
+        if ((placement === null || placement === void 0 ? void 0 : placement.inset) != null)
+            throw new Error(`emitCollageLayout: sourceFor(${span.imageIndex}) already carries placement.inset — the emitter owns it`);
+        const box = inset.insetAt(li);
+        sources.push({
+            ...base,
+            placement: { fit: "cover", ...(placement !== null && placement !== void 0 ? placement : {}), ...(box ? { inset: box } : {}) },
+        });
+        cells.push({
+            imageIndex: span.imageIndex,
+            span,
+            stableKey: String(frame.meta.stableKey),
+            target: inset.targets[li],
+            raw: { x: frame.x, y: frame.y, w: frame.width, h: frame.height },
+        });
+    });
+    const painted = inset.targets.reduce((a, t) => a + t.w * t.h, 0);
+    return {
+        m0,
+        sources,
+        cells,
+        expectedNullFrac: 1 - painted / (canvasW * canvasH),
+        maxClampPx: inset.maxClampPx,
+        clampedEdges: inset.clampedEdges,
+    };
+}

package/dist/m0saic/collage/image-collage/v1/image-collage.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ============================================================================
+ * @m0saic/collage/image-collage/v1 — the layout-solver contact sheet
+ * ============================================================================
+ *
+ * Point it at N images (any sizes, any aspects) and get back a designed
+ * collage: a unit-lattice pack with consistent pixel gutters, cover-cropped
+ * cells sized to each image's intrinsic aspect within a soft crop budget,
+ * hero/portrait/panorama spans, and staggered masonry rhythm.
+ *
+ * The template SEARCHES: it enumerates lattice candidates, solves each
+ * (span assignment + staggered-shelf tiling), scores, and keeps the best —
+ * then emits a tiny ratio m0 (unit weights, gutters in the fiber) and
+ * declares its intent through the layout contract: per-image planned aspect,
+ * 2-D lattice gutters, null-space coverage, and equal-size span classes.
+ * `debugLayout: true` verifies all of it at render time and stamps
+ * `editor.layoutContract` (the `audit:layout-envelope` sweep keys off this).
+ *
+ * PAGING: when the set exceeds one sheet (`maxImagesPerSheet`, or
+ * geometrically when N images can't fit at readable cell sizes), the render
+ * returns an `emit:"multi"` pipeline — one PNG page per step, balanced counts
+ * in input order. `pageLattice` picks whether pages share one mix-fitted
+ * lattice (default — the sheets read as a set) or each search their own.
+ *
+ * Every render surfaces its crop accounting: `doc.labels` carries a per-image
+ * `img:k · span · crop N%` display entry and the doc's editor label carries
+ * the page's mean crop — visible in Make, File Details, and the `--report`
+ * sidecar.
+ *
+ * Intrinsic dimensions come from `ctx.media` (the host probes before render);
+ * the template performs no I/O. With no `sourceIds` it packs a deterministic
+ * demo set of colored tiles — the zero-setup preview.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+export type ImageCollageProps = {
+    /** The images to pack — files or a folder (the host expands folders). */
+    sourceIds?: string[];
+    /** Gutter between images as a fraction of the canvas short edge. Default 0.01. */
+    gutter?: number;
+    /** Outer margin as a fraction of the gutter (0..1). Default 1 (margin = gutter). */
+    margin?: number;
+    /** Explicit gutter in pixels (wins over `gutter`; 0 = flush collage). */
+    gutterPx?: number;
+    /** Explicit outer margin in pixels (wins over `margin`; must not exceed the gutter). */
+    marginPx?: number;
+    /** Max fraction an image may be cover-cropped — SOFT: exceeded minimally when nothing fits, and reported. Default 0.3. */
+    cropBudget?: number;
+    /** Readability bounds on the typical cell scale √(cellW·cellH), px. Defaults 120 / 320. */
+    minCellPx?: number;
+    maxCellPx?: number;
+    /** Cap images per sheet — beyond it the render pages into an emit:multi pipeline. */
+    maxImagesPerSheet?: number;
+    /** Paged sets: share one mix-fitted lattice ("uniform", default) or search per page ("independent"). */
+    pageLattice?: "uniform" | "independent";
+    /** Seed for the layout search's taste tie-breaks (hero picks, band rhythm). Default 1. */
+    seed?: number;
+    /** Canvas background (shows in gutters and margins). */
+    background?: MosaicColor;
+    /** Dev-only: verify the declared layout contract at render and stamp editor.layoutContract. */
+    debugLayout?: boolean;
+};
+export declare const ImageCollage: MosaicTemplate<ImageCollageProps>;

package/dist/m0saic/collage/image-collage/v1/image-collage.js

@@ -0,0 +1,386 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/collage/image-collage/v1 — the layout-solver contact sheet
+ * ============================================================================
+ *
+ * Point it at N images (any sizes, any aspects) and get back a designed
+ * collage: a unit-lattice pack with consistent pixel gutters, cover-cropped
+ * cells sized to each image's intrinsic aspect within a soft crop budget,
+ * hero/portrait/panorama spans, and staggered masonry rhythm.
+ *
+ * The template SEARCHES: it enumerates lattice candidates, solves each
+ * (span assignment + staggered-shelf tiling), scores, and keeps the best —
+ * then emits a tiny ratio m0 (unit weights, gutters in the fiber) and
+ * declares its intent through the layout contract: per-image planned aspect,
+ * 2-D lattice gutters, null-space coverage, and equal-size span classes.
+ * `debugLayout: true` verifies all of it at render time and stamps
+ * `editor.layoutContract` (the `audit:layout-envelope` sweep keys off this).
+ *
+ * PAGING: when the set exceeds one sheet (`maxImagesPerSheet`, or
+ * geometrically when N images can't fit at readable cell sizes), the render
+ * returns an `emit:"multi"` pipeline — one PNG page per step, balanced counts
+ * in input order. `pageLattice` picks whether pages share one mix-fitted
+ * lattice (default — the sheets read as a set) or each search their own.
+ *
+ * Every render surfaces its crop accounting: `doc.labels` carries a per-image
+ * `img:k · span · crop N%` display entry and the doc's editor label carries
+ * the page's mean crop — visible in Make, File Details, and the `--report`
+ * sidecar.
+ *
+ * Intrinsic dimensions come from `ctx.media` (the host probes before render);
+ * the template performs no I/O. With no `sourceIds` it packs a deterministic
+ * demo set of colored tiles — the zero-setup preview.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageCollage = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const paging_1 = require("./packer/paging");
+const emit_1 = require("./emit");
+const demo_fixture_1 = require("./demo-fixture");
+const tutorial_1 = require("./tutorial");
+const TEMPLATE_ID = "@m0saic/collage/image-collage/v1";
+const DEFAULT_BACKGROUND = "#101014";
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    sourceIds: {
+        type: "media[]",
+        required: true,
+        description: "Images to pack — pick a folder, one or more files, or drag-and-drop. Empty renders a built-in demo set so you can preview the layout before adding photos.",
+        meta: {
+            ui: { label: "Images", order: 1 },
+            control: { multiple: true, picker: "folder", accept: ["image"] },
+        },
+    },
+    // ── Layout (optional sliders — safe, bounded ranges) ──
+    gutter: {
+        type: "number",
+        required: false,
+        description: "Space between images, as a fraction of the canvas short edge.",
+        meta: {
+            constraints: { min: 0, max: 0.1 },
+            control: { flavor: "slider", step: 0.005 },
+            ui: { label: "Gutter", order: 1 },
+        },
+    },
+    margin: {
+        type: "number",
+        required: false,
+        description: "Outer margin as a fraction of the gutter — 1 matches the gutter, 0 runs the images to the canvas edge.",
+        meta: {
+            constraints: { min: 0, max: 1 },
+            control: { flavor: "slider", step: 0.05 },
+            ui: { label: "Margin", order: 2 },
+        },
+    },
+    cropBudget: {
+        type: "number",
+        required: false,
+        description: "How much of an image the cover-crop may trim. Soft — exceeded minimally when nothing else fits.",
+        meta: {
+            constraints: { min: 0, max: 0.6 },
+            control: { flavor: "slider", step: 0.05 },
+            ui: { label: "Crop budget", order: 3 },
+        },
+    },
+    seed: {
+        type: "number",
+        required: true,
+        description: "Seed for the layout search's taste tie-breaks (which images become heroes, band rhythm). Same seed → same layout.",
+        meta: {
+            constraints: { min: 0, max: 9999 },
+            ui: { label: "Seed", order: 4 },
+        },
+    },
+    // ── Paging ──
+    maxImagesPerSheet: {
+        type: "number",
+        required: true,
+        description: "Images per sheet. Sets larger than this page into a multi-file pipeline (one PNG per page). 30 is a tuned default.",
+        meta: {
+            constraints: { min: 1, max: 200 },
+            ui: { label: "Max per sheet", order: 1 },
+        },
+    },
+    pageLattice: {
+        type: "string",
+        required: false,
+        description: 'Paged sets: "uniform" shares one mix-fitted lattice across pages (a designed set); "independent" re-searches per page (best per-page crops).',
+        meta: {
+            constraints: { oneOf: ["uniform", "independent"] },
+            ui: { label: "Page lattice", order: 2 },
+        },
+    },
+    // ── Style ──
+    background: {
+        type: "string",
+        required: false,
+        description: "Canvas background color (shows in gutters and margins).",
+        meta: {
+            constraints: { isColor: true },
+            control: { colorPicker: true },
+            ui: { label: "Background", order: 1 },
+        },
+    },
+    // ── Sizing (readability bounds — advanced) ──
+    minCellPx: {
+        type: "number",
+        required: false,
+        description: "Smallest typical cell scale in px (readability floor). Default 120.",
+        meta: { constraints: { min: 16, max: 2000 }, ui: { label: "Min cell (px)", order: 1 } },
+    },
+    maxCellPx: {
+        type: "number",
+        required: false,
+        description: "Largest typical cell scale in px. Default 320.",
+        meta: { constraints: { min: 16, max: 4000 }, ui: { label: "Max cell (px)", order: 2 } },
+    },
+    // ── Advanced px overrides (win over the ratio sliders above) ──
+    gutterPx: {
+        type: "number",
+        required: false,
+        description: "Explicit gutter in pixels (overrides Gutter; 0 = flush collage).",
+        meta: { control: { placeholder: "from Gutter fraction" }, constraints: { min: 0, max: 200 }, ui: { label: "Gutter (px)", order: 1 } },
+    },
+    marginPx: {
+        type: "number",
+        required: false,
+        description: "Explicit outer margin in pixels (overrides Margin; must not exceed the gutter).",
+        meta: { control: { placeholder: "from Margin fraction" }, constraints: { min: 0, max: 200 }, ui: { label: "Margin (px)", order: 2 } },
+    },
+    debugLayout: {
+        type: "boolean",
+        required: false,
+        description: "Dev-only layout contract: verify per-image aspect, lattice gutters, coverage and equal-size classes; on violation render a LAYOUT_CONTRACT error mosaic and stamp editor.layoutContract. Deterministic default false.",
+        meta: { ui: { label: "Debug layout", order: 1, collapsedByDefault: true } },
+    },
+});
+/** Demo mode: deterministic synthetic photos as labeled lavfi tiles. */
+function demoInput() {
+    return {
+        aspects: demo_fixture_1.DEMO_IMAGES.map((d) => d.aspect),
+        sourceFor: (i) => ({
+            type: "lavfi",
+            color: demo_fixture_1.DEMO_IMAGES[i].color,
+            editor: { owner: "template", label: `img:${i}` },
+        }),
+        assetEntryFor: () => undefined,
+    };
+}
+/** Real mode: probed images from ctx.media, fail-fast on anything unusable. */
+function mediaInput(sourceIds, ctx) {
+    var _a;
+    const problems = [];
+    const aspects = [];
+    const assetIds = [];
+    const entries = [];
+    for (const id of sourceIds) {
+        const meta = ctx.media[(0, types_1.asAssetId)(id)];
+        if (!meta || !(meta.width > 0) || !(meta.height > 0)) {
+            problems.push(`no probed dimensions for "${id}"`);
+            continue;
+        }
+        if (meta.kind !== "image") {
+            problems.push(`"${id}" is ${(_a = meta.kind) !== null && _a !== void 0 ? _a : "unknown"} - the collage packs images only (for now)`);
+            continue;
+        }
+        const assetId = String((0, types_1.asAssetId)((0, template_utils_1.slugifyAssetKeyFromPath)(id)));
+        aspects.push(meta.width / meta.height);
+        assetIds.push(assetId);
+        entries.push([assetId, { kind: "file", path: id, mediaType: "image" }]);
+    }
+    if (problems.length > 0)
+        return problems.join("; ");
+    return {
+        aspects,
+        sourceFor: (i) => ({
+            type: "media",
+            mediaType: "image",
+            assetId: assetIds[i],
+            editor: { owner: "template", label: `img:${i}` },
+        }),
+        assetEntryFor: (i) => entries[i],
+    };
+}
+/** The declared design intent, generated from the solved layout (GLOBAL labels). */
+function collageContract(cells, expectedNullFrac, gutterPx) {
+    var _a;
+    const constraints = cells.map((c) => ({
+        label: `img:${c.imageIndex}`,
+        aspect: c.target.w / c.target.h,
+        aspectTolerance: 0.02,
+    }));
+    const allLabels = cells.map((c) => `img:${c.imageIndex}`);
+    const relations = [
+        { label: allLabels, lattice: { gutterXPx: gutterPx, gutterYPx: gutterPx } },
+        { label: allLabels, coverage: { expectedNullFrac } },
+    ];
+    const byClass = new Map();
+    for (const c of cells) {
+        const entry = (_a = byClass.get(c.span.span)) !== null && _a !== void 0 ? _a : { labels: [], minPx: Infinity };
+        entry.labels.push(`img:${c.imageIndex}`);
+        entry.minPx = Math.min(entry.minPx, c.target.w, c.target.h);
+        byClass.set(c.span.span, entry);
+    }
+    for (const { labels, minPx } of byClass.values()) {
+        if (labels.length >= 2)
+            relations.push({ label: labels, equal: "size", tolerance: Math.max(0.02, 3 / Math.max(1, minPx)) });
+    }
+    return { constraints, relations };
+}
+/** Build one sheet's document from a page solve (labels/assets in GLOBAL indexes). */
+function buildPageDoc(pageSolve, input, ctx, knobs) {
+    const { imageIndexes, solve } = pageSolve;
+    const layout = (0, emit_1.emitCollageLayout)({
+        placed: solve.placed,
+        cols: solve.candidate.cols,
+        rows: solve.candidate.rows,
+        canvasW: knobs.W,
+        canvasH: knobs.H,
+        gutterXPx: knobs.gutterPx,
+        gutterYPx: knobs.gutterPx,
+        marginPx: knobs.marginPx,
+        sourceFor: (local) => input.sourceFor(imageIndexes[local]),
+    });
+    // Globalize the cell mapping (the solve works in page-local indexes).
+    const cells = layout.cells.map((c) => ({ ...c, imageIndex: imageIndexes[c.imageIndex] }));
+    // Crop surfacing: per-image display labels + a page summary on the doc.
+    const cropByLocal = new Map(solve.assignments.map((a) => [a.imageIndex, a.cost]));
+    const labels = {};
+    layout.cells.forEach((c, i) => {
+        var _a;
+        const crop = (_a = cropByLocal.get(c.imageIndex)) !== null && _a !== void 0 ? _a : 0;
+        labels[c.stableKey] = `img:${cells[i].imageIndex} · ${c.span.span} · crop ${(crop * 100).toFixed(0)}%`;
+    });
+    const meanCropPct = (solve.metrics.meanCrop * 100).toFixed(1);
+    const pageNote = knobs.pageCount > 1 ? ` — page ${knobs.page}/${knobs.pageCount}` : "";
+    const editorLabel = `Image Collage${pageNote} · ${imageIndexes.length} images · mean crop ${meanCropPct}%`;
+    const assets = {};
+    for (const g of imageIndexes) {
+        const entry = input.assetEntryFor(g);
+        if (entry)
+            assets[entry[0]] = entry[1];
+    }
+    const doc = {
+        kind: "mosaic_document",
+        version: 1,
+        assets,
+        m0: layout.m0,
+        sources: layout.sources,
+        labels,
+        fps: ctx.target.fps,
+        durationMs: ctx.target.durationMs,
+        size: { width: knobs.W, height: knobs.H },
+        backgroundColor: knobs.background,
+        // Gate-26 convention: every rendered doc declares its format. A contact
+        // sheet is an opaque PNG still (the background is a solid fill).
+        format: { kind: "image", container: "png" },
+        editor: { label: editorLabel },
+    };
+    const { constraints, relations } = collageContract(cells, layout.expectedNullFrac, knobs.gutterPx);
+    return (0, template_utils_1.withLayoutContract)(doc, ctx, {
+        templateId: TEMPLATE_ID,
+        constraints,
+        relations,
+        debug: knobs.debugLayout,
+    });
+}
+exports.ImageCollage = {
+    id: (0, types_1.asTemplateId)(TEMPLATE_ID),
+    label: "Image Collage",
+    version: 1,
+    description: "Packs any set of photos into a designed contact sheet: a searched layout with hero, portrait and panorama cells sized to each image's aspect, even pixel gutters, and a soft crop budget so nothing is trimmed too hard. Big sets page into one PNG per sheet. With no images it shows a demo set.",
+    capabilities: { tier: "core" },
+    tags: ["media", "collage", "image", "layout-solver", "contact-sheet", "creators", "designers", "photos", "grid", "social"],
+    outputHints: { width: 1920, height: 1080, format: { kind: "image", container: "png" } },
+    propsSchema,
+    defaultProps: {
+        maxCellPx: 320,
+        minCellPx: 120,
+        pageLattice: "uniform",
+        gutter: 0.01,
+        margin: 1,
+        cropBudget: 0.3,
+        maxImagesPerSheet: 30,
+        seed: 1,
+        background: DEFAULT_BACKGROUND,
+        debugLayout: false,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        const fail = (message) => (0, template_utils_1.makeErrorMosaic)(message, { title: "Image Collage", width: W, height: H });
+        // ── knobs ──
+        const gutterPx = props.gutterPx != null
+            ? Math.max(0, Math.round(props.gutterPx))
+            : Math.max(0, Math.round(((_a = props.gutter) !== null && _a !== void 0 ? _a : 0.01) * Math.min(W, H)));
+        const marginPx = props.marginPx != null
+            ? Math.max(0, Math.round(props.marginPx))
+            : Math.round(Math.max(0, Math.min(1, (_b = props.margin) !== null && _b !== void 0 ? _b : 1)) * gutterPx);
+        if (marginPx > gutterPx && props.marginPx != null)
+            return fail(
+            // ASCII only: makeErrorMosaic's drawtext card maps non-ASCII to "?".
+            `marginPx ${marginPx} exceeds the gutter ${gutterPx}px - margins beyond the gutter need an m0-level wrapper (not supported yet).`);
+        const cropBudget = Math.min(0.9, Math.max(0, (_c = props.cropBudget) !== null && _c !== void 0 ? _c : 0.3));
+        const minCellPx = Math.max(16, Math.round((_d = props.minCellPx) !== null && _d !== void 0 ? _d : 120));
+        const maxCellPx = Math.max(minCellPx, Math.round((_e = props.maxCellPx) !== null && _e !== void 0 ? _e : 320));
+        const seed = Math.floor((_f = props.seed) !== null && _f !== void 0 ? _f : 1);
+        const maxImagesPerSheet = Math.max(1, Math.round((_g = props.maxImagesPerSheet) !== null && _g !== void 0 ? _g : 30));
+        const background = (_h = props.background) !== null && _h !== void 0 ? _h : DEFAULT_BACKGROUND;
+        const debugLayout = props.debugLayout === true;
+        // ── inputs ──
+        const ids = ((_j = props.sourceIds) !== null && _j !== void 0 ? _j : []).map((s) => String(s).trim()).filter((s) => s.length > 0);
+        const input = ids.length === 0 ? demoInput() : mediaInput(ids, ctx);
+        if (typeof input === "string")
+            return fail(input);
+        // ── search (pages when the set outgrows one sheet) ──
+        let pages;
+        try {
+            pages = (0, paging_1.solvePages)({
+                canvasW: W,
+                canvasH: H,
+                gutterXPx: gutterPx,
+                gutterYPx: gutterPx,
+                marginPx,
+                minCellPx,
+                maxCellPx,
+                aspects: input.aspects,
+                seed,
+                cropBudget,
+                maxImagesPerSheet,
+                pageLattice: props.pageLattice === "independent" ? "independent" : "uniform",
+            });
+        }
+        catch {
+            return fail(`no lattice fits any sheet of ${input.aspects.length} image(s) on ${W}x${H} within cell bounds ` +
+                `[${minCellPx}, ${maxCellPx}]px - lower minCellPx or enlarge the canvas.`);
+        }
+        const knobs = { W, H, gutterPx, marginPx, background, debugLayout, pageCount: pages.length };
+        if (pages.length === 1)
+            return buildPageDoc(pages[0], input, ctx, { ...knobs, page: 1 });
+        const durationMs = (_k = ctx.target.durationMs) !== null && _k !== void 0 ? _k : 40;
+        const steps = pages.map((p, i) => ({
+            name: `page_${String(i + 1).padStart(2, "0")}`,
+            label: `page_${String(i + 1).padStart(2, "0")}`,
+            durationMs,
+            file: buildPageDoc(p, input, ctx, { ...knobs, page: i + 1 }),
+        }));
+        const pipeline = {
+            kind: "mosaic_pipeline",
+            version: 1,
+            emit: "multi",
+            steps,
+        };
+        return pipeline;
+    },
+    // The Make "?" walkthrough (gate 31, founder: "prepare a render tutorial.
+    // keep it simple on how to use. select images, or a folder of images").
+    // Three beats: pick photos or a folder → the sheet lays itself out → big
+    // sets page. Deterministic, media-free, own step timing.
+    renderTutorial(_props, ctx) {
+        return (0, tutorial_1.renderImageCollageTutorial)(ctx);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.ImageCollage);

package/dist/m0saic/collage/image-collage/v1/index.d.ts

@@ -0,0 +1,2 @@
+export { ImageCollage } from "./image-collage";
+export type { ImageCollageProps } from "./image-collage";

package/dist/m0saic/collage/image-collage/v1/index.js

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