@m0saic/templates 0.2.0

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

@@ -0,0 +1,71 @@
+/**
+ * Candidate enumeration — the bounded lattice search space.
+ *
+ * A candidate is a (cols, rows) unit lattice derived from a unit-aspect
+ * target. Targets come from the image mix (median landscape aspect; a
+ * portrait-fit target so 1×2 suits the portrait median; 1.0 when squares
+ * dominate). Column counts come from the cell-scale bounds; rows follow from
+ * the canvas and the target. Everything is filtered for area-achievability
+ * and pre-scored so the solver only tiles a capped, ordered list.
+ */
+import type { LatticeCandidate, SpanClass } from "./types";
+export type EnumerateCandidatesOptions = {
+    canvasW: number;
+    canvasH: number;
+    /** Image count on this sheet. */
+    count: number;
+    gutterXPx: number;
+    gutterYPx: number;
+    marginPx: number;
+    /** Readability bounds on the typical cell scale √(unitW·unitH). */
+    minCellPx: number;
+    maxCellPx: number;
+    /** Intrinsic aspects (drives unit-aspect targets + the crop pre-score). */
+    aspects: number[];
+    /** Hard cap on the returned list. Default 64. */
+    maxCandidates?: number;
+    /** Soft crop budget (pre-score prefers within-budget menus). Default 0.3. */
+    cropBudget?: number;
+};
+/**
+ * Unit-aspect targets from the aspect histogram. Deduplicated, deterministic
+ * order (most-load-bearing first).
+ */
+export declare function unitAspectTargets(aspects: number[]): number[];
+/**
+ * Exact-cover ACHIEVABILITY of a lattice area: N spans with areas from the
+ * fitting menu summing to exactly C·R. Areas form {1,…,maxA} minus gaps (the
+ * full menu's areas are {1,2,3,4,6} — no 5). Unreachable sums are those in
+ * a gap above the second-largest achievable ceiling: with the full menu only
+ * `6N−1` (all-but-one at max 6, one needing the nonexistent 5). Computed
+ * generically so lattice-limited menus (e.g. a 1-column lattice) stay honest.
+ */
+export declare function coverAchievable(count: number, units: number, spans: SpanClass[]): boolean;
+/**
+ * `maxCellPx` is a taste PREFERENCE, not a floor — with few images on a big
+ * canvas it must yield, or the only lattices in the window are far denser
+ * than the images can cover (2 images at the 320px default on 1600×900 has
+ * NO achievable lattice at all). Relax it toward the scale a density-2 pack
+ * of `count` images actually needs, with headroom for lattice quantization.
+ */
+export declare function relaxedMaxCellPx(maxCellPx: number, canvasW: number, canvasH: number, count: number): number;
+/**
+ * The largest unit count any lattice in the cell-scale window offers —
+ * the geometric CAPACITY of a sheet (each image needs ≥1 unit). Drives the
+ * paging trigger: more images than this cannot fit one sheet at readable
+ * cell sizes. `0` = no lattice fits at all (canvas below the cell floor).
+ */
+export declare function maxLatticeUnits(opts: {
+    canvasW: number;
+    canvasH: number;
+    gutterXPx: number;
+    gutterYPx: number;
+    marginPx: number;
+    minCellPx: number;
+    maxCellPx: number;
+}): number;
+/**
+ * Enumerate, filter, pre-score, and cap the lattice candidates.
+ * Deterministic: stable ordering by (preScore, cols, rows, target).
+ */
+export declare function enumerateCandidates(opts: EnumerateCandidatesOptions): LatticeCandidate[];

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

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Candidate enumeration — the bounded lattice search space.
+ *
+ * A candidate is a (cols, rows) unit lattice derived from a unit-aspect
+ * target. Targets come from the image mix (median landscape aspect; a
+ * portrait-fit target so 1×2 suits the portrait median; 1.0 when squares
+ * dominate). Column counts come from the cell-scale bounds; rows follow from
+ * the canvas and the target. Everything is filtered for area-achievability
+ * and pre-scored so the solver only tiles a capped, ordered list.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unitAspectTargets = unitAspectTargets;
+exports.coverAchievable = coverAchievable;
+exports.relaxedMaxCellPx = relaxedMaxCellPx;
+exports.maxLatticeUnits = maxLatticeUnits;
+exports.enumerateCandidates = enumerateCandidates;
+const classify_1 = require("./classify");
+const score_1 = require("./score");
+const median = (xs) => {
+    if (xs.length === 0)
+        return undefined;
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.floor(s.length / 2)];
+};
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/**
+ * Unit-aspect targets from the aspect histogram. Deduplicated, deterministic
+ * order (most-load-bearing first).
+ */
+function unitAspectTargets(aspects) {
+    var _a;
+    const landscape = aspects.filter((a) => a > 1.15);
+    const portrait = aspects.filter((a) => a < 0.87);
+    const squares = aspects.length - landscape.length - portrait.length;
+    const targets = [];
+    const push = (u) => {
+        if (u == null)
+            return;
+        const c = clamp(u, 0.6, 2.0);
+        if (!targets.some((t) => Math.abs(t - c) < 0.05))
+            targets.push(c);
+    };
+    // The modal-landscape unit (the seed's 1.27): 1×1 near-free for the modal class.
+    push((_a = median(landscape)) !== null && _a !== void 0 ? _a : 1.27);
+    // Portrait-fit: A(1,2) ≈ u/2 (gutters shift it slightly; the R±1 sweep absorbs that).
+    const mp = median(portrait);
+    if (mp != null)
+        push(2 * mp);
+    // Square-heavy mixes want a square-ish unit on the menu too.
+    if (squares >= aspects.length * 0.3)
+        push(1.0);
+    return targets;
+}
+/**
+ * Exact-cover ACHIEVABILITY of a lattice area: N spans with areas from the
+ * fitting menu summing to exactly C·R. Areas form {1,…,maxA} minus gaps (the
+ * full menu's areas are {1,2,3,4,6} — no 5). Unreachable sums are those in
+ * a gap above the second-largest achievable ceiling: with the full menu only
+ * `6N−1` (all-but-one at max 6, one needing the nonexistent 5). Computed
+ * generically so lattice-limited menus (e.g. a 1-column lattice) stay honest.
+ */
+function coverAchievable(count, units, spans) {
+    const areas = [...new Set(spans.map(classify_1.spanArea))].sort((a, b) => a - b);
+    if (areas.length === 0)
+        return false;
+    const maxA = areas[areas.length - 1];
+    if (units < count || units > maxA * count)
+        return false;
+    // Greedy-safe check: walk down from the largest area; a sum is achievable
+    // iff after taking k spans at maxA the remainder fits the smaller menu.
+    // Small search (areas ≤ 5 distinct, count can be large) — DP over remainder
+    // mod nothing needed: since 1 ∈ areas always (1x1 fits any lattice), any
+    // remainder r with 0 ≤ r ≤ (count−k)·secondMax… simplest exact rule: take
+    // k = max spans at maxA, rest flexible in [count−k, (count−k)·nextMax].
+    if (areas[0] === 1 && areas.length >= 2) {
+        const next = areas[areas.length - 2];
+        for (let k = 0; k <= count; k++) {
+            const rest = units - k * maxA;
+            const others = count - k;
+            if (rest < others * areas[0])
+                break; // too many maxed spans already
+            if (rest <= others * next)
+                return true;
+        }
+        return false;
+    }
+    // Degenerate menus (only 1x1): exact only.
+    return units === count;
+}
+/**
+ * `maxCellPx` is a taste PREFERENCE, not a floor — with few images on a big
+ * canvas it must yield, or the only lattices in the window are far denser
+ * than the images can cover (2 images at the 320px default on 1600×900 has
+ * NO achievable lattice at all). Relax it toward the scale a density-2 pack
+ * of `count` images actually needs, with headroom for lattice quantization.
+ */
+function relaxedMaxCellPx(maxCellPx, canvasW, canvasH, count) {
+    const densityTwoScale = Math.sqrt((canvasW * canvasH) / (2 * Math.max(1, count)));
+    return Math.max(maxCellPx, Math.ceil(densityTwoScale * 1.25));
+}
+/**
+ * The largest unit count any lattice in the cell-scale window offers —
+ * the geometric CAPACITY of a sheet (each image needs ≥1 unit). Drives the
+ * paging trigger: more images than this cannot fit one sheet at readable
+ * cell sizes. `0` = no lattice fits at all (canvas below the cell floor).
+ */
+function maxLatticeUnits(opts) {
+    const { canvasW, canvasH, gutterXPx, gutterYPx, marginPx, minCellPx, maxCellPx } = opts;
+    let best = 0;
+    for (let cols = 1; cols <= 64; cols++) {
+        const unitW = (canvasW - 2 * marginPx - (cols - 1) * gutterXPx) / cols;
+        if (unitW < 1)
+            break;
+        for (let rows = 1; rows <= 64; rows++) {
+            const unitH = (canvasH - 2 * marginPx - (rows - 1) * gutterYPx) / rows;
+            if (unitH < 1)
+                break;
+            const scale = Math.sqrt(unitW * unitH);
+            if (scale > maxCellPx)
+                continue;
+            if (scale < minCellPx)
+                break;
+            best = Math.max(best, cols * rows);
+        }
+    }
+    return best;
+}
+/**
+ * Enumerate, filter, pre-score, and cap the lattice candidates.
+ * Deterministic: stable ordering by (preScore, cols, rows, target).
+ */
+function enumerateCandidates(opts) {
+    var _a, _b;
+    const { canvasW, canvasH, count, gutterXPx, gutterYPx, marginPx, minCellPx, maxCellPx, aspects, } = opts;
+    const maxCandidates = (_a = opts.maxCandidates) !== null && _a !== void 0 ? _a : 64;
+    const cropBudget = (_b = opts.cropBudget) !== null && _b !== void 0 ? _b : 0.3;
+    if (count <= 0)
+        throw new Error("enumerateCandidates: count must be ≥ 1");
+    // `aspects` is the MIX the lattice must suit (unit-aspect targets + the
+    // min-crop pre-score); `count` is how many images actually land on the
+    // sheet. They're equal for a single sheet; uniform paging passes the FULL
+    // mix with a per-page count so every page shares one statistics-fitted
+    // lattice.
+    if (aspects.length < count)
+        throw new Error(`enumerateCandidates: aspects.length ${aspects.length} < count ${count}`);
+    if (!(minCellPx > 0) || !(maxCellPx >= minCellPx))
+        throw new Error(`enumerateCandidates: bad cell-scale bounds [${minCellPx}, ${maxCellPx}]`);
+    const targets = unitAspectTargets(aspects);
+    const rough = [];
+    for (let cols = 1; cols <= 64; cols++) {
+        const unitW = (canvasW - 2 * marginPx - (cols - 1) * gutterXPx) / cols;
+        if (unitW < 1)
+            break;
+        for (let rows = 1; rows <= 64; rows++) {
+            const unitH = (canvasH - 2 * marginPx - (rows - 1) * gutterYPx) / rows;
+            if (unitH < 1)
+                break;
+            const scale = Math.sqrt(unitW * unitH);
+            if (scale > maxCellPx)
+                continue; // rows too few — keep growing
+            if (scale < minCellPx)
+                break; //    rows too many — smaller from here on
+            const units = cols * rows;
+            if (units > 6 * count)
+                break;
+            if (!coverAchievable(count, units, (0, classify_1.fittingSpans)(cols, rows)))
+                continue;
+            const unitAspect = unitW / unitH;
+            const aspectTerm = Math.min(...targets.map((t) => Math.abs(Math.log(unitAspect / t))));
+            const nearest = targets.reduce((best, t) => Math.abs(Math.log(unitAspect / t)) < Math.abs(Math.log(unitAspect / best)) ? t : best);
+            const areaPrior = Math.abs(units - 2 * count) / count;
+            rough.push({ cols, rows, unitW, unitH, target: nearest, rough: aspectTerm + 0.25 * areaPrior + 0.03 * (0, score_1.roughAxes)(cols, rows) });
+        }
+    }
+    // The emitted m0's basis IS the lattice, so a lattice whose unit count is
+    // rough (14 = 2·7) composes with nothing — the packer only proposes lattices
+    // on the 5-smooth lattice (or ≤ 12 units per axis: content fill), which is
+    // dense enough (1–12, 15, 16, 18, 20, 24, 25, 27, 30, 32, 36, 40, …) that a
+    // sheet loses nothing; the whole window is the fallback if nothing fits.
+    const onLattice = rough.filter((r) => (0, score_1.roughAxes)(r.cols, r.rows) === 0);
+    const pool = onLattice.length > 0 ? onLattice : rough;
+    pool.sort((a, b) => a.rough - b.rough || a.cols - b.cols || a.rows - b.rows);
+    // Stage 2 — classify the surviving slice for the real pre-score (min-crop
+    // estimate: each image at its cheapest fitting span) + the CR ≈ 2N prior.
+    const out = [];
+    for (const r of pool.slice(0, Math.max(maxCandidates, 96))) {
+        const spans = (0, classify_1.fittingSpans)(r.cols, r.rows);
+        const visibleAspect = {};
+        for (const s of spans)
+            visibleAspect[s] = (0, classify_1.spanVisibleAspect)(s, r.unitW, r.unitH, gutterXPx, gutterYPx);
+        const menus = (0, classify_1.classifySpans)(aspects, visibleAspect, cropBudget);
+        const minCrop = menus.reduce((a, m) => a + m.options[0].cost, 0) / Math.max(1, menus.length);
+        const areaPrior = Math.abs(r.cols * r.rows - 2 * count) / count;
+        out.push({
+            cols: r.cols,
+            rows: r.rows,
+            unitAspectTarget: r.target,
+            unitW: r.unitW,
+            unitH: r.unitH,
+            visibleAspect,
+            canvasW, canvasH, gutterXPx, gutterYPx, marginPx,
+            preScore: minCrop + 0.05 * areaPrior + 0.03 * (0, score_1.roughAxes)(r.cols, r.rows),
+        });
+    }
+    out.sort((a, b) => a.preScore - b.preScore ||
+        a.cols - b.cols ||
+        a.rows - b.rows ||
+        a.unitAspectTarget - b.unitAspectTarget);
+    return out.slice(0, maxCandidates);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Aspect classification — per-image crop costs against a candidate lattice.
+ *
+ * Cover-fit keeps `min(a, A)/max(a, A)` of an image's area when an image of
+ * aspect `a` fills a cell of visible aspect `A`; the crop cost is the lost
+ * fraction. The budget is SOFT (founder decision): every fitting span stays
+ * on the menu with its cost — the planner prefers within-budget options and
+ * reports overage, it never letterboxes and never leaves holes.
+ */
+import type { ImageSpanOptions, SpanClass, SpanDim } from "./types";
+/** Canonical menu order (deterministic tie-breaking keys off this). */
+export declare const SPAN_CLASSES: readonly SpanClass[];
+export declare const SPAN_MENU: Record<SpanClass, SpanDim>;
+export declare const spanArea: (s: SpanClass) => number;
+/** Menu spans that fit a C×R lattice, canonical order. */
+export declare function fittingSpans(cols: number, rows: number): SpanClass[];
+/** Area fraction cover-fit crops when aspect `a` fills a cell of aspect `A`. */
+export declare function cropCost(imageAspect: number, cellAspect: number): number;
+/** Visible aspect of a span on a lattice with the given unit + gutters. */
+export declare function spanVisibleAspect(span: SpanClass, unitW: number, unitH: number, gutterXPx: number, gutterYPx: number): number;
+/**
+ * Per-image span menu against a candidate's visible aspects, cost-ascending.
+ * Ties break by smaller area then canonical menu order — an image never gets
+ * a bigger cell than an equally-good smaller one for free.
+ */
+export declare function classifySpans(aspects: number[], visibleAspect: Partial<Record<SpanClass, number>>, cropBudget: number): ImageSpanOptions[];

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

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Aspect classification — per-image crop costs against a candidate lattice.
+ *
+ * Cover-fit keeps `min(a, A)/max(a, A)` of an image's area when an image of
+ * aspect `a` fills a cell of visible aspect `A`; the crop cost is the lost
+ * fraction. The budget is SOFT (founder decision): every fitting span stays
+ * on the menu with its cost — the planner prefers within-budget options and
+ * reports overage, it never letterboxes and never leaves holes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spanArea = exports.SPAN_MENU = exports.SPAN_CLASSES = void 0;
+exports.fittingSpans = fittingSpans;
+exports.cropCost = cropCost;
+exports.spanVisibleAspect = spanVisibleAspect;
+exports.classifySpans = classifySpans;
+/** Canonical menu order (deterministic tie-breaking keys off this). */
+exports.SPAN_CLASSES = [
+    "1x1", "2x1", "3x1", "4x1", "1x2", "2x2", "3x2", "1x3",
+];
+exports.SPAN_MENU = {
+    "1x1": { c: 1, r: 1 },
+    "2x1": { c: 2, r: 1 },
+    "3x1": { c: 3, r: 1 },
+    "4x1": { c: 4, r: 1 },
+    "1x2": { c: 1, r: 2 },
+    "2x2": { c: 2, r: 2 },
+    "3x2": { c: 3, r: 2 },
+    "1x3": { c: 1, r: 3 },
+};
+const spanArea = (s) => exports.SPAN_MENU[s].c * exports.SPAN_MENU[s].r;
+exports.spanArea = spanArea;
+/** Menu spans that fit a C×R lattice, canonical order. */
+function fittingSpans(cols, rows) {
+    return exports.SPAN_CLASSES.filter((s) => exports.SPAN_MENU[s].c <= cols && exports.SPAN_MENU[s].r <= rows);
+}
+/** Area fraction cover-fit crops when aspect `a` fills a cell of aspect `A`. */
+function cropCost(imageAspect, cellAspect) {
+    if (!(imageAspect > 0) || !(cellAspect > 0))
+        return 1;
+    return 1 - Math.min(imageAspect, cellAspect) / Math.max(imageAspect, cellAspect);
+}
+/** Visible aspect of a span on a lattice with the given unit + gutters. */
+function spanVisibleAspect(span, unitW, unitH, gutterXPx, gutterYPx) {
+    const { c, r } = exports.SPAN_MENU[span];
+    return (c * unitW + (c - 1) * gutterXPx) / (r * unitH + (r - 1) * gutterYPx);
+}
+/**
+ * Per-image span menu against a candidate's visible aspects, cost-ascending.
+ * Ties break by smaller area then canonical menu order — an image never gets
+ * a bigger cell than an equally-good smaller one for free.
+ */
+function classifySpans(aspects, visibleAspect, cropBudget) {
+    const spans = exports.SPAN_CLASSES.filter((s) => visibleAspect[s] != null);
+    return aspects.map((aspect, imageIndex) => {
+        if (!Number.isFinite(aspect) || aspect <= 0)
+            throw new Error(`classifySpans: aspects[${imageIndex}] must be a positive finite number, got ${aspect}`);
+        const options = spans
+            .map((span) => ({ span, cost: cropCost(aspect, visibleAspect[span]) }))
+            .sort((a, b) => a.cost - b.cost ||
+            (0, exports.spanArea)(a.span) - (0, exports.spanArea)(b.span) ||
+            exports.SPAN_CLASSES.indexOf(a.span) - exports.SPAN_CLASSES.indexOf(b.span));
+        return {
+            imageIndex,
+            aspect,
+            options,
+            withinBudget: options.filter((o) => o.cost <= cropBudget).length,
+        };
+    });
+}

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

@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./classify";
+export * from "./candidates";
+export * from "./tiler";
+export * from "./score";
+export * from "./solve";
+export * from "./paging";

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

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./classify"), exports);
+__exportStar(require("./candidates"), exports);
+__exportStar(require("./tiler"), exports);
+__exportStar(require("./score"), exports);
+__exportStar(require("./solve"), exports);
+__exportStar(require("./paging"), exports);

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

@@ -0,0 +1,39 @@
+/**
+ * Paging — spill N images across balanced sheets.
+ *
+ * Pages split in INPUT ORDER with balanced sizes (N/P, first N mod P pages
+ * one heavier). Two lattice modes (founder decision, 2026-07-11):
+ *
+ * - `"uniform"` (default): ONE lattice fitted to the global aspect mix is
+ *   shared by every page — the sheets read as a designed set. Per-page span
+ *   assignment still varies, and the exact-cover upgrade budget automatically
+ *   gives lighter pages bigger heroes. The lattice is chosen by solving the
+ *   heaviest page against the mix-fitted candidates, then cross-scoring the
+ *   top few across ALL pages.
+ * - `"independent"`: every page runs its own full search — best per-page crop
+ *   numbers, less sibling consistency.
+ *
+ * Paging triggers when `maxImagesPerSheet` says so, or geometrically when N
+ * exceeds the sheet's capacity (`maxLatticeUnits` — each image needs ≥1 unit).
+ */
+import { type SolveCollageOptions } from "./solve";
+import type { SolveResult } from "./types";
+export type PageLatticeMode = "uniform" | "independent";
+export type SolvePagesOptions = Omit<SolveCollageOptions, "keep"> & {
+    maxImagesPerSheet?: number;
+    pageLattice?: PageLatticeMode;
+};
+export type PageSolve = {
+    /** Global input indexes on this page, in input order. */
+    imageIndexes: number[];
+    /** The page's solve — image indexes inside are PAGE-LOCAL (0..n−1). */
+    solve: SolveResult;
+};
+/** Balanced page split: input order, sizes differ by at most 1. */
+export declare function planPages(count: number, perSheet: number): number[][];
+/**
+ * Solve the full input as one or more pages. Deterministic. Throws only when
+ * not even one image fits the canvas (capacity 0) or a page search finds no
+ * lattice — both are caller-facing configuration errors.
+ */
+export declare function solvePages(opts: SolvePagesOptions): PageSolve[];

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

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Paging — spill N images across balanced sheets.
+ *
+ * Pages split in INPUT ORDER with balanced sizes (N/P, first N mod P pages
+ * one heavier). Two lattice modes (founder decision, 2026-07-11):
+ *
+ * - `"uniform"` (default): ONE lattice fitted to the global aspect mix is
+ *   shared by every page — the sheets read as a designed set. Per-page span
+ *   assignment still varies, and the exact-cover upgrade budget automatically
+ *   gives lighter pages bigger heroes. The lattice is chosen by solving the
+ *   heaviest page against the mix-fitted candidates, then cross-scoring the
+ *   top few across ALL pages.
+ * - `"independent"`: every page runs its own full search — best per-page crop
+ *   numbers, less sibling consistency.
+ *
+ * Paging triggers when `maxImagesPerSheet` says so, or geometrically when N
+ * exceeds the sheet's capacity (`maxLatticeUnits` — each image needs ≥1 unit).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planPages = planPages;
+exports.solvePages = solvePages;
+const template_utils_1 = require("@m0saic/template-utils");
+const candidates_1 = require("./candidates");
+const solve_1 = require("./solve");
+const pageSeed = (seed, page) => Math.floor((0, template_utils_1.splitmix32)((seed ^ (page * 0x9e3779b1)) >>> 0)() * 4294967296);
+/** Balanced page split: input order, sizes differ by at most 1. */
+function planPages(count, perSheet) {
+    const pages = Math.max(1, Math.ceil(count / perSheet));
+    const base = Math.floor(count / pages);
+    const heavy = count % pages;
+    const out = [];
+    let at = 0;
+    for (let p = 0; p < pages; p++) {
+        const size = base + (p < heavy ? 1 : 0);
+        out.push(Array.from({ length: size }, (_, i) => at + i));
+        at += size;
+    }
+    return out;
+}
+/**
+ * Solve the full input as one or more pages. Deterministic. Throws only when
+ * not even one image fits the canvas (capacity 0) or a page search finds no
+ * lattice — both are caller-facing configuration errors.
+ */
+function solvePages(opts) {
+    var _a, _b, _c, _d;
+    const { aspects } = opts;
+    const count = aspects.length;
+    const seed = (_a = opts.seed) !== null && _a !== void 0 ? _a : 1;
+    if (count === 0)
+        throw new Error("solvePages: no images");
+    const capacity = (0, candidates_1.maxLatticeUnits)(opts);
+    if (capacity === 0)
+        throw new Error(`solvePages: no lattice fits ${opts.canvasW}×${opts.canvasH} within cell bounds ` +
+            `[${opts.minCellPx}, ${opts.maxCellPx}]px`);
+    const perSheet = Math.max(1, Math.min((_b = opts.maxImagesPerSheet) !== null && _b !== void 0 ? _b : Infinity, capacity));
+    const pages = planPages(count, perSheet);
+    if (pages.length === 1) {
+        const [solve] = (0, solve_1.solveCollage)({ ...opts, seed });
+        return [{ imageIndexes: pages[0], solve }];
+    }
+    const mode = (_c = opts.pageLattice) !== null && _c !== void 0 ? _c : "uniform";
+    const pageAspects = pages.map((idxs) => idxs.map((i) => aspects[i]));
+    if (mode === "independent") {
+        return pages.map((imageIndexes, p) => {
+            const [solve] = (0, solve_1.solveCollage)({ ...opts, aspects: pageAspects[p], seed: pageSeed(seed, p) });
+            return { imageIndexes, solve };
+        });
+    }
+    // ── uniform: one mix-fitted lattice shared across the set ──
+    const heaviest = pages[0].length;
+    const cropBudget = (_d = opts.cropBudget) !== null && _d !== void 0 ? _d : 0.3;
+    const candidates = (0, candidates_1.enumerateCandidates)({
+        canvasW: opts.canvasW,
+        canvasH: opts.canvasH,
+        count: heaviest,
+        gutterXPx: opts.gutterXPx,
+        gutterYPx: opts.gutterYPx,
+        marginPx: opts.marginPx,
+        minCellPx: opts.minCellPx,
+        // Pages hold `heaviest` images each — the taste bound yields accordingly.
+        maxCellPx: (0, candidates_1.relaxedMaxCellPx)(opts.maxCellPx, opts.canvasW, opts.canvasH, heaviest),
+        aspects, // the FULL mix — the shared lattice must suit everyone
+        maxCandidates: opts.maxCandidates,
+        cropBudget,
+    });
+    if (candidates.length === 0)
+        throw new Error(`solvePages: no shared lattice fits ${heaviest} images per sheet on ${opts.canvasW}×${opts.canvasH}`);
+    // Rank lattices on the heaviest page, then cross-score the top few over
+    // every page (clean pages first, then summed score).
+    const page0 = candidates
+        .map((candidate) => {
+        try {
+            return { candidate, solve: (0, solve_1.solveCandidate)(candidate, pageAspects[0], cropBudget, pageSeed(seed, 0)) };
+        }
+        catch {
+            return undefined;
+        }
+    })
+        .filter((x) => !!x)
+        .sort((a, b) => (a.solve.metrics.fillerCount > 0 ? 1 : 0) - (b.solve.metrics.fillerCount > 0 ? 1 : 0) ||
+        a.solve.score - b.solve.score);
+    if (page0.length === 0)
+        throw new Error("solvePages: every shared-lattice candidate failed the heaviest page");
+    let best;
+    for (const { candidate, solve: first } of page0.slice(0, 3)) {
+        const solves = [first];
+        let total = first.score;
+        let dirty = first.metrics.fillerCount > 0 ? 1 : 0;
+        let failed = false;
+        for (let p = 1; p < pages.length; p++) {
+            try {
+                const s = (0, solve_1.solveCandidate)(candidate, pageAspects[p], cropBudget, pageSeed(seed, p));
+                solves.push(s);
+                total += s.score;
+                if (s.metrics.fillerCount > 0)
+                    dirty++;
+            }
+            catch {
+                failed = true;
+                break;
+            }
+        }
+        if (failed)
+            continue;
+        if (!best || dirty < best.dirty || (dirty === best.dirty && total < best.total))
+            best = { total, dirty, solves };
+    }
+    if (!best) {
+        // No shared lattice covers every page (rare density corners) — fall back
+        // to independent pages rather than failing the render.
+        return pages.map((imageIndexes, p) => {
+            const [solve] = (0, solve_1.solveCollage)({ ...opts, aspects: pageAspects[p], seed: pageSeed(seed, p) });
+            return { imageIndexes, solve };
+        });
+    }
+    return pages.map((imageIndexes, p) => ({ imageIndexes, solve: best.solves[p] }));
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Solve metrics + the candidate score (lower = better).
+ *
+ * The score is the search's taste function: crop fidelity dominates, the
+ * soft-budget overage is punished hard (it exists but should be rare), fillers
+ * are punished harder (they should not exist), and small bonuses reward the
+ * seed collage's look (span variety + staggered row rhythm). Weights are
+ * module constants, not props — the Phase 7 sandbox loop is where they get
+ * tuned against the founder's eye.
+ */
+import type { LatticeCandidate, PlacedSpan, SolveMetrics, SpanAssignment } from "./types";
+export declare const DEFAULT_SCORE_WEIGHTS: {
+    readonly meanCrop: 1;
+    readonly maxCrop: 0.25;
+    readonly overBudgetTotal: 3;
+    readonly overBudgetCount: 0.05;
+    readonly fillerUnit: 0.5;
+    readonly sizeDiversity: -0.06;
+    readonly stagger: -0.04;
+    readonly latticeRough: 0.03;
+};
+export declare function computeMetrics(candidate: LatticeCandidate, placed: PlacedSpan[], assignments: SpanAssignment[], cropBudget: number): SolveMetrics;
+export declare function scoreCandidate(metrics: SolveMetrics, weights?: typeof DEFAULT_SCORE_WEIGHTS): number;
+/** How many of a lattice's axes are off the 5-smooth lattice (counts ≤ 12 pass as content fill). */
+export declare function roughAxes(cols: number, rows: number): number;