@m0saic/templates 0.2.0

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

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SCORE_WEIGHTS = void 0;
+exports.computeMetrics = computeMetrics;
+exports.scoreCandidate = scoreCandidate;
+exports.roughAxes = roughAxes;
+const template_utils_1 = require("@m0saic/template-utils");
+const classify_1 = require("./classify");
+exports.DEFAULT_SCORE_WEIGHTS = {
+    meanCrop: 1,
+    maxCrop: 0.25,
+    overBudgetTotal: 3,
+    overBudgetCount: 0.05,
+    fillerUnit: 0.5,
+    sizeDiversity: -0.06,
+    stagger: -0.04,
+    // A nudge, not a veto: between near-equal crops, prefer the lattice whose
+    // unit counts are 5-smooth (or ≤ 12) so the collage composes and every
+    // guillotine sub-split stays on the lattice too.
+    latticeRough: 0.03,
+};
+function computeMetrics(candidate, placed, assignments, cropBudget) {
+    const real = assignments.filter((a) => a.imageIndex >= 0);
+    const crops = real.map((a) => a.cost);
+    const n = Math.max(1, crops.length);
+    const meanCrop = crops.reduce((a, c) => a + c, 0) / n;
+    const maxCrop = crops.length > 0 ? Math.max(...crops) : 0;
+    const over = crops.map((c) => Math.max(0, c - cropBudget));
+    const overBudgetCount = over.filter((o) => o > 0).length;
+    const overBudgetTotal = over.reduce((a, o) => a + o, 0);
+    const fillerCount = placed.filter((p) => p.imageIndex < 0).reduce((a, p) => a + p.cs * p.rs, 0);
+    const used = new Set(real.map((a) => a.span));
+    const sizeDiversity = used.size / (0, classify_1.fittingSpans)(candidate.cols, candidate.rows).length;
+    // Fraction of interior row boundaries crossed by at least one span — the
+    // seed collage crosses all of them; plain full-width shelves cross none.
+    let crossed = 0;
+    const interior = Math.max(0, candidate.rows - 1);
+    for (let r = 1; r < candidate.rows; r++) {
+        if (placed.some((p) => p.r0 < r && r < p.r0 + p.rs))
+            crossed++;
+    }
+    const stagger = interior > 0 ? crossed / interior : 0;
+    const latticeRough = roughAxes(candidate.cols, candidate.rows);
+    return { meanCrop, maxCrop, overBudgetCount, overBudgetTotal, fillerCount, sizeDiversity, stagger, latticeRough };
+}
+function scoreCandidate(metrics, weights = exports.DEFAULT_SCORE_WEIGHTS) {
+    return (weights.meanCrop * metrics.meanCrop +
+        weights.maxCrop * metrics.maxCrop +
+        weights.overBudgetTotal * metrics.overBudgetTotal +
+        weights.overBudgetCount * metrics.overBudgetCount +
+        weights.fillerUnit * metrics.fillerCount +
+        weights.sizeDiversity * metrics.sizeDiversity +
+        weights.stagger * metrics.stagger +
+        weights.latticeRough * metrics.latticeRough);
+}
+/** How many of a lattice's axes are off the 5-smooth lattice (counts ≤ 12 pass as content fill). */
+function roughAxes(cols, rows) {
+    return [cols, rows].filter((n) => n > template_utils_1.LATTICE_SMALL_BASIS && !(0, template_utils_1.isSmooth)(n)).length;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The solver front door: enumerate lattice candidates, solve each
+ * (classify → upgrade plan → staggered tiling), score, keep the best.
+ *
+ * Pure and deterministic: all variation flows from `seed` via mulberry32,
+ * with per-candidate streams seeded off the candidate's position so one
+ * candidate's consumption never shifts another's picks. The caller (the
+ * template shell, Phase 4) adds the layout-contract gate on finalists —
+ * this module is pixel-free beyond the candidate geometry.
+ */
+import { type EnumerateCandidatesOptions } from "./candidates";
+import type { LatticeCandidate, SolveResult } from "./types";
+export type SolveCollageOptions = Omit<EnumerateCandidatesOptions, "count"> & {
+    cropBudget?: number;
+    seed?: number;
+    /** How many top-scored solves to return (the best is `[0]`). Default 1. */
+    keep?: number;
+};
+/** Solve one candidate lattice. Deterministic per (inputs, rngSeed). */
+export declare function solveCandidate(candidate: LatticeCandidate, aspects: number[], cropBudget: number, rngSeed: number): SolveResult;
+/**
+ * Solve a sheet: N images (their aspects) onto the best lattice for this
+ * canvas. Returns the `keep` best solves, best first. Throws when no lattice
+ * candidate exists (canvas/cell bounds impossible for this N — the caller
+ * pages or errors).
+ */
+export declare function solveCollage(opts: SolveCollageOptions): SolveResult[];

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

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * The solver front door: enumerate lattice candidates, solve each
+ * (classify → upgrade plan → staggered tiling), score, keep the best.
+ *
+ * Pure and deterministic: all variation flows from `seed` via mulberry32,
+ * with per-candidate streams seeded off the candidate's position so one
+ * candidate's consumption never shifts another's picks. The caller (the
+ * template shell, Phase 4) adds the layout-contract gate on finalists —
+ * this module is pixel-free beyond the candidate geometry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.solveCandidate = solveCandidate;
+exports.solveCollage = solveCollage;
+const template_utils_1 = require("@m0saic/template-utils");
+const classify_1 = require("./classify");
+const candidates_1 = require("./candidates");
+const score_1 = require("./score");
+const tiler_1 = require("./tiler");
+/** Solve one candidate lattice. Deterministic per (inputs, rngSeed). */
+function solveCandidate(candidate, aspects, cropBudget, rngSeed) {
+    const rng = (0, template_utils_1.mulberry32)(rngSeed);
+    const menus = (0, classify_1.classifySpans)(aspects, candidate.visibleAspect, cropBudget);
+    const plan = (0, tiler_1.planUpgrades)(candidate.cols, candidate.rows, menus, rng);
+    const tiled = (0, tiler_1.tileStaggered)(plan, candidate.cols, candidate.rows, menus, rng);
+    const metrics = (0, score_1.computeMetrics)(candidate, tiled.placed, tiled.assignments, cropBudget);
+    return {
+        candidate,
+        placed: tiled.placed,
+        assignments: tiled.assignments,
+        metrics,
+        repairs: tiled.repairs,
+        score: (0, score_1.scoreCandidate)(metrics),
+    };
+}
+/**
+ * Solve a sheet: N images (their aspects) onto the best lattice for this
+ * canvas. Returns the `keep` best solves, best first. Throws when no lattice
+ * candidate exists (canvas/cell bounds impossible for this N — the caller
+ * pages or errors).
+ */
+function solveCollage(opts) {
+    var _a, _b, _c, _d;
+    const cropBudget = (_a = opts.cropBudget) !== null && _a !== void 0 ? _a : 0.3;
+    const seed = (_b = opts.seed) !== null && _b !== void 0 ? _b : 1;
+    const keep = Math.max(1, (_c = opts.keep) !== null && _c !== void 0 ? _c : 1);
+    // Adaptive search width: big sheets cost more per solve and benefit less
+    // from lattice variety (mix statistics dominate), so the default candidate
+    // budget shrinks with N to keep the search interactive.
+    const n = opts.aspects.length;
+    const maxCandidates = (_d = opts.maxCandidates) !== null && _d !== void 0 ? _d : (n > 240 ? 24 : n > 120 ? 40 : 64);
+    // Few images on a big canvas need big cells — the max-cell taste bound
+    // yields to the density-2 scale (see relaxedMaxCellPx).
+    const maxCellPx = (0, candidates_1.relaxedMaxCellPx)(opts.maxCellPx, opts.canvasW, opts.canvasH, n);
+    const candidates = (0, candidates_1.enumerateCandidates)({ ...opts, count: n, cropBudget, maxCandidates, maxCellPx });
+    if (candidates.length === 0)
+        throw new Error(`solveCollage: no lattice fits ${opts.aspects.length} images on ${opts.canvasW}×${opts.canvasH} ` +
+            `within cell bounds [${opts.minCellPx}, ${opts.maxCellPx}]px`);
+    // One decorrelated rng seed per candidate, independent of list order
+    // churn: keyed off the candidate's identity, not its index. A candidate
+    // whose plan/tiling proves infeasible (rare geometric corners the area
+    // filter can't see) is skipped — the search moves on; only an all-fail
+    // search surfaces the error.
+    const results = [];
+    let lastError;
+    for (const c of candidates) {
+        const streamSeed = Math.floor((0, template_utils_1.splitmix32)((seed ^ (c.cols * 131 + c.rows * 17)) >>> 0)() * 4294967296);
+        try {
+            results.push(solveCandidate(c, opts.aspects, cropBudget, streamSeed));
+        }
+        catch (e) {
+            lastError = e;
+        }
+    }
+    if (results.length === 0)
+        throw lastError !== null && lastError !== void 0 ? lastError : new Error("solveCollage: every candidate failed");
+    // A filler-bearing solve (background holes) must never outrank a clean one,
+    // regardless of score — the founder's no-filler guarantee lives here.
+    results.sort((a, b) => (a.metrics.fillerCount > 0 ? 1 : 0) - (b.metrics.fillerCount > 0 ? 1 : 0) ||
+        a.score - b.score ||
+        a.candidate.cols - b.candidate.cols ||
+        a.candidate.rows - b.candidate.rows);
+    return results.slice(0, keep);
+}

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

@@ -0,0 +1,65 @@
+/**
+ * The tiler — exact cover of the unit lattice by menu spans.
+ *
+ * Three stages, all deterministic under a seeded rng:
+ *
+ * 1. `planUpgrades` — every image starts at 1×1 and the extra area
+ *    E = C·R − N is spent as span upgrades: cost-driven first (portraits buy
+ *    1×2, panoramas buy 3×1), then taste-driven (seeded picks among
+ *    near-neutral upgrades — this is where the hero 2×2s come from). Every
+ *    move preserves the BAND-FEASIBILITY invariant (`bandFeasible`): the
+ *    aggregate shelf accounting 3·⌈W₃/C⌉ + 2·⌈W₂/C⌉ ≤ R must keep holding,
+ *    so the plan never demands more tall bands than the lattice has rows —
+ *    without this, portrait-heavy mixes plan themselves into unrepairable
+ *    F2 loops.
+ * 2. Group split — the columns are cut into 1–3 vertical groups, each
+ *    shelf-tiled independently. Bands never align across groups, which is the
+ *    staggered-masonry look the seed collage has (plain shelves cannot
+ *    produce it: the seed crosses EVERY interior row boundary).
+ * 3. Shelf tiling per group with a bounded repair loop: on a packing failure
+ *    the culprit downgrades one step — FAILURE-AWARE (F2 prefers shorter
+ *    replacement spans, F1/F3 narrower ones) — and the freed area re-spends
+ *    on untouched images under the same band-feasibility filter (never
+ *    re-upgrading a downgraded image), so the touched set only grows and
+ *    every image's area only shrinks after first touch. The terminal state
+ *    (all 1×1 + fillers) always tiles row-major; under the soft crop budget
+ *    fillers should never survive the candidate search (tests assert zero on
+ *    realistic densities).
+ */
+import type { SeededRng } from "@m0saic/template-utils";
+import type { ImageSpanOptions, PlacedSpan, RepairEvent, SpanAssignment, SpanClass, SpanPlan } from "./types";
+/** Aggregate shelf accounting: the tall bands demanded must fit the rows. */
+export declare function bandFeasible(W2: number, W3: number, cols: number, rows: number): boolean;
+/**
+ * Spend E = cols·rows − count as upgrades, keeping band feasibility. The rng
+ * only picks among near-equivalent taste upgrades. O(E·N·menu).
+ */
+export declare function planUpgrades(cols: number, rows: number, menus: ImageSpanOptions[], rng: SeededRng): SpanPlan;
+/**
+ * Candidate column-group splits, stagger-first. G1 (no split) is always last:
+ * it always partitions, so the pipeline cannot dead-end.
+ */
+export declare function groupPlans(cols: number, maxSpanWidth: number, rng: SeededRng): number[][];
+type DowngradePrefs = {
+    /** F2 wants SHORTER replacements (height pressure); F1/F3 want narrower. */
+    preferLowHeight?: boolean;
+    /** Reject replacements that break an invariant (e.g. band feasibility). */
+    feasible?: (span: SpanClass) => boolean;
+};
+/** One step down the ladder: the largest strictly-smaller area with a fitting span. */
+export declare function downgradeOf(span: SpanClass, fitting: readonly SpanClass[], costOf: (s: SpanClass) => number, prefs?: DowngradePrefs): SpanClass | null;
+export type TileResult = {
+    placed: PlacedSpan[];
+    /** Final per-image assignment after any repairs (imageIndex-ordered; fillers excluded). */
+    assignments: SpanAssignment[];
+    repairs: RepairEvent[];
+    fillerCount: number;
+};
+/**
+ * Tile the plan onto the lattice: try stagger-first group plans, shelf-tile
+ * each group, repair on failure (failure-aware downgrade + band-feasible
+ * group-local re-spend + fillers-as-last-resort), fall back to the single
+ * group. Total; the all-1×1 terminal always tiles.
+ */
+export declare function tileStaggered(plan: SpanPlan, cols: number, rows: number, menus: ImageSpanOptions[], rng: SeededRng): TileResult;
+export {};