@m0saic/templates 0.2.0

package/dist/geometry-audit.d.ts

@@ -0,0 +1,149 @@
+/**
+ * geometry-audit — the PURE, testable core shared by `gen-geometry-matrix`
+ * (the curated everyday sweep) and `gen-geometry-proof` (the sloth-tier
+ * exhaustive per-template proof).
+ *
+ * Everything here is deterministic and side-effect-free: canvas-set builders,
+ * the estimator's projection math, verdict tiering, hostile-canvas
+ * classification, §3c routing hints, and violation clustering. The gen-scripts
+ * wire the impure parts (template resolve, wall-clock timing, file I/O) to
+ * these; the logic lives here so it is unit-tested with synthetic data.
+ *
+ * See the internal template-geometry-contract notes and handbook
+ * `feasibility-precision-quantization.md` §3c (the launder ladder the routing
+ * hints point at) + `composition-arithmetic.md` §2 (the canvas families the
+ * matrix tiers come from).
+ */
+import type { MosaicGeometryViolation } from "@m0saic/types";
+export declare const MATRIX_TIERS: {
+    tier: string;
+    canvases: [number, number][];
+}[];
+/** The matrix canvas set for a template: the fixed tiers + its own `outputHints`. */
+export declare function matrixCanvases(outputHints?: {
+    width?: number;
+    height?: number;
+}): {
+    w: number;
+    h: number;
+    tier: string;
+}[];
+export type ProofSpec = {
+    /** Explicit list: `"480x480,386x277,..."`. */
+    canvases?: string;
+    /** Cartesian range: `"wMin:wMax x hMin:hMax"` (step via `step`). */
+    range?: string;
+    step?: number;
+    /** Aspect families `"16:9,9:16,1:1"` swept over `scales` (height range). */
+    ar?: string;
+    scales?: string;
+    scaleStep?: number;
+};
+/** Deterministic iterator over the proof canvas set (lazy — never materializes millions). */
+export declare function proofCanvases(spec: ProofSpec): Generator<[number, number]>;
+/** Count without materializing — for the estimator projection. */
+export declare function proofCanvasCount(spec: ProofSpec): number;
+/** Three representative canvases (smallest / mid / largest) for auto-seeding the
+ *  estimator — computed from the spec BOUNDS, so it never iterates a huge set. */
+export declare function proofSeedCanvases(spec: ProofSpec): [number, number][];
+/** projectedMs ≈ count × (resolve + parse) + overhead. Uses the WORST seed's parse. */
+export declare function projectProofTime(resolveMs: number, parseMs: number, count: number, overheadMs?: number): number;
+export type ProofTier = "quick" | "minutes" | "sloth";
+/** quick <60s (just run) · minutes <10min (notice) · sloth ≥10min (refuses without --yes). */
+export declare function verdictTier(projectedMs: number): {
+    tier: ProofTier;
+    label: string;
+};
+/** An axis is hostile when it shares little with the modern lattice (gcd(dim,120) < 8):
+ *  primes and coprime strays — where placeInsetPieces degrades to exact placement. */
+export declare function isHostileCanvas(w: number, h: number, basis?: number): boolean;
+export declare function routingHint(kind: MosaicGeometryViolation["kind"], allHostile: boolean): string;
+/** One resolved canvas result (from reading `editor.geometryContract`). */
+export type CanvasResult = {
+    w: number;
+    h: number;
+    tier?: string;
+    ok?: boolean;
+    violations?: MosaicGeometryViolation[];
+    floors?: {
+        feasible: boolean;
+        meetsPrecision: boolean;
+        maxSpreadPx: number;
+    };
+    error?: string;
+};
+export type ViolationCluster = {
+    name?: string;
+    kind: MosaicGeometryViolation["kind"];
+    axis?: "x" | "y";
+    /** Canvases affected by this (piece, kind, axis). */
+    count: number;
+    maxDeltaPx: number;
+    maxCanvas: string;
+    minDeltaPx: number;
+    minCanvas: string;
+    /** Up to 8 example canvases. */
+    examples: string[];
+    hint: string;
+};
+/** Group violations across canvases by (piece, kind, axis) — the point is to
+ *  PROVE the contract without emitting a row per canvas over a million-pair run. */
+export declare function clusterViolations(results: CanvasResult[]): ViolationCluster[];
+export type ProofFloors = {
+    firstInfeasible: string | null;
+    firstSubPrec: string | null;
+    maxSpread: number;
+    maxSpreadCanvas: string;
+};
+export type ProofHostile = {
+    total: number;
+    passed: number;
+    examples: string[];
+};
+export type ProofReportInput = {
+    templateId: string;
+    specStr: string;
+    total: number;
+    propsHash: string;
+    wallMs: number;
+    projectedMs: number;
+    tier: ProofTier;
+    passes: number;
+    /** Only the canvases that violated or errored (a PROVEN run passes an empty array). */
+    failures: CanvasResult[];
+    floors: ProofFloors;
+    hostile: ProofHostile;
+};
+/** Build the clustered PROVEN/FAILED report markdown. Pure — the gen-script wires
+ *  the resolve loop + timing to it; tested directly with synthetic failures. */
+export declare function buildProofReport(input: ProofReportInput): {
+    md: string;
+    proven: boolean;
+};
+/** One swept canvas: which `label|rule` invariants were violated there. */
+export type EnvelopeSample = {
+    w: number;
+    h: number;
+    violated: string[];
+};
+export type InvariantEnvelope = {
+    /** `label|rule`. */
+    key: string;
+    label: string;
+    rule: string;
+    /** Canvases (by ascending min-dim) where it holds / breaks. */
+    holdCount: number;
+    breakCount: number;
+    /** Monotone "breaks below/above a scale" boundary when detectable; else null. */
+    boundary: string | null;
+    /** Up to 6 example break canvases. */
+    examples: string[];
+};
+/**
+ * From per-canvas violation samples, compute — for every invariant that broke
+ * anywhere — the canvas range where it holds vs breaks, with a boundary when the
+ * break region is monotone (breaks below/above a scale). PURE.
+ */
+export declare function computeEnvelopes(samples: EnvelopeSample[]): InvariantEnvelope[];
+/** The `LAYOUT-ENVELOPE.md` body for one template's sweep. Pure. */
+export declare function buildEnvelopeReport(templateId: string, sweepDesc: string, samples: EnvelopeSample[]): string;

package/dist/geometry-audit.js

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * geometry-audit — the PURE, testable core shared by `gen-geometry-matrix`
+ * (the curated everyday sweep) and `gen-geometry-proof` (the sloth-tier
+ * exhaustive per-template proof).
+ *
+ * Everything here is deterministic and side-effect-free: canvas-set builders,
+ * the estimator's projection math, verdict tiering, hostile-canvas
+ * classification, §3c routing hints, and violation clustering. The gen-scripts
+ * wire the impure parts (template resolve, wall-clock timing, file I/O) to
+ * these; the logic lives here so it is unit-tested with synthetic data.
+ *
+ * See the internal template-geometry-contract notes and handbook
+ * `feasibility-precision-quantization.md` §3c (the launder ladder the routing
+ * hints point at) + `composition-arithmetic.md` §2 (the canvas families the
+ * matrix tiers come from).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATRIX_TIERS = void 0;
+exports.matrixCanvases = matrixCanvases;
+exports.proofCanvases = proofCanvases;
+exports.proofCanvasCount = proofCanvasCount;
+exports.proofSeedCanvases = proofSeedCanvases;
+exports.projectProofTime = projectProofTime;
+exports.verdictTier = verdictTier;
+exports.isHostileCanvas = isHostileCanvas;
+exports.routingHint = routingHint;
+exports.clusterViolations = clusterViolations;
+exports.buildProofReport = buildProofReport;
+exports.computeEnvelopes = computeEnvelopes;
+exports.buildEnvelopeReport = buildEnvelopeReport;
+// ── Matrix canvas tiers (composition-arithmetic §2) ──────────
+exports.MATRIX_TIERS = [
+    // the modern family; exactness lifts by integer scaling — one ×2 member
+    // (3840×2160) catches scale-dependent JS math.
+    { tier: "modern-core", canvases: [[1920, 1080], [1080, 1920], [1080, 1080], [3840, 2160]] },
+    // 720p pair (gcd 40), 4:5 social (gcd 10).
+    { tier: "adjacent", canvases: [[1280, 720], [1080, 1350]] },
+    // primes / coprime pairs; 386×277 is the stat-card audit aspect that bit.
+    // Degradation is EXPECTED here — the contract asserts the DEGRADED (exact) intent.
+    { tier: "hostile", canvases: [[997, 720], [1001, 733], [483, 379], [386, 277]] },
+];
+/** The matrix canvas set for a template: the fixed tiers + its own `outputHints`. */
+function matrixCanvases(outputHints) {
+    const out = [];
+    const seen = new Set();
+    for (const t of exports.MATRIX_TIERS) {
+        for (const [w, h] of t.canvases) {
+            const k = `${w}x${h}`;
+            if (!seen.has(k)) {
+                seen.add(k);
+                out.push({ w, h, tier: t.tier });
+            }
+        }
+    }
+    if ((outputHints === null || outputHints === void 0 ? void 0 : outputHints.width) && (outputHints === null || outputHints === void 0 ? void 0 : outputHints.height)) {
+        const k = `${outputHints.width}x${outputHints.height}`;
+        if (!seen.has(k))
+            out.push({ w: outputHints.width, h: outputHints.height, tier: "declared" });
+    }
+    return out;
+}
+function parseList(s) {
+    return s
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean)
+        .map((t) => {
+        const [w, h] = t.toLowerCase().split("x").map(Number);
+        return [w, h];
+    });
+}
+function parseRange(s) {
+    const [wPart, hPart] = s.toLowerCase().split("x");
+    const [wMin, wMax] = wPart.split(":").map(Number);
+    const [hMin, hMax] = hPart.split(":").map(Number);
+    return { wMin, wMax, hMin, hMax };
+}
+/** Deterministic iterator over the proof canvas set (lazy — never materializes millions). */
+function* proofCanvases(spec) {
+    var _a, _b;
+    if (spec.canvases) {
+        for (const c of parseList(spec.canvases))
+            yield c;
+        return;
+    }
+    if (spec.range) {
+        const { wMin, wMax, hMin, hMax } = parseRange(spec.range);
+        const step = Math.max(1, (_a = spec.step) !== null && _a !== void 0 ? _a : 1);
+        for (let w = wMin; w <= wMax; w += step)
+            for (let h = hMin; h <= hMax; h += step)
+                yield [w, h];
+        return;
+    }
+    if (spec.ar && spec.scales) {
+        const ars = spec.ar.split(",").map((s) => s.trim()).filter(Boolean).map((s) => s.split(":").map(Number));
+        const [sMin, sMax] = spec.scales.split(":").map(Number);
+        const step = Math.max(1, (_b = spec.scaleStep) !== null && _b !== void 0 ? _b : 120);
+        for (const [aw, ah] of ars)
+            for (let h = sMin; h <= sMax; h += step)
+                yield [Math.round((h * aw) / ah), h];
+        return;
+    }
+    for (const c of matrixCanvases())
+        yield [c.w, c.h];
+}
+/** Count without materializing — for the estimator projection. */
+function proofCanvasCount(spec) {
+    var _a, _b;
+    if (spec.canvases)
+        return parseList(spec.canvases).length;
+    if (spec.range) {
+        const { wMin, wMax, hMin, hMax } = parseRange(spec.range);
+        const step = Math.max(1, (_a = spec.step) !== null && _a !== void 0 ? _a : 1);
+        return Math.max(0, Math.floor((wMax - wMin) / step) + 1) * Math.max(0, Math.floor((hMax - hMin) / step) + 1);
+    }
+    if (spec.ar && spec.scales) {
+        const ars = spec.ar.split(",").map((s) => s.trim()).filter(Boolean).length;
+        const [sMin, sMax] = spec.scales.split(":").map(Number);
+        const step = Math.max(1, (_b = spec.scaleStep) !== null && _b !== void 0 ? _b : 120);
+        return ars * Math.max(0, Math.floor((sMax - sMin) / step) + 1);
+    }
+    return matrixCanvases().length;
+}
+/** Three representative canvases (smallest / mid / largest) for auto-seeding the
+ *  estimator — computed from the spec BOUNDS, so it never iterates a huge set. */
+function proofSeedCanvases(spec) {
+    var _a;
+    const uniq = (arr) => {
+        const seen = new Set();
+        const out = [];
+        for (const c of arr) {
+            const k = `${c[0]}x${c[1]}`;
+            if (!seen.has(k)) {
+                seen.add(k);
+                out.push(c);
+            }
+        }
+        return out;
+    };
+    if (spec.canvases) {
+        const list = [...proofCanvases(spec)].sort((a, b) => a[0] * a[1] - b[0] * b[1]);
+        if (list.length === 0)
+            return [];
+        return uniq([list[0], list[Math.floor(list.length / 2)], list[list.length - 1]]);
+    }
+    if (spec.range) {
+        const { wMin, wMax, hMin, hMax } = parseRange(spec.range);
+        return uniq([[wMin, hMin], [Math.round((wMin + wMax) / 2), Math.round((hMin + hMax) / 2)], [wMax, hMax]]);
+    }
+    if (spec.ar && spec.scales) {
+        const [aw, ah] = ((_a = spec.ar.split(",")[0]) !== null && _a !== void 0 ? _a : "1:1").split(":").map(Number);
+        const [sMin, sMax] = spec.scales.split(":").map(Number);
+        const mid = Math.round((sMin + sMax) / 2);
+        return uniq([sMin, mid, sMax].map((h) => [Math.round((h * aw) / ah), h]));
+    }
+    const m = matrixCanvases();
+    const byArea = [...m].sort((a, b) => a.w * a.h - b.w * b.h);
+    return uniq([byArea[0], byArea[Math.floor(byArea.length / 2)], byArea[byArea.length - 1]].map((c) => [c.w, c.h]));
+}
+// ── Estimator projection (pure; timing is measured by the script) ──
+/** projectedMs ≈ count × (resolve + parse) + overhead. Uses the WORST seed's parse. */
+function projectProofTime(resolveMs, parseMs, count, overheadMs = 50) {
+    return count * (Math.max(0, resolveMs) + Math.max(0, parseMs)) + overheadMs;
+}
+/** quick <60s (just run) · minutes <10min (notice) · sloth ≥10min (refuses without --yes). */
+function verdictTier(projectedMs) {
+    if (projectedMs < 60000)
+        return { tier: "quick", label: "quick (<60s) — just run it" };
+    if (projectedMs < 600000)
+        return { tier: "minutes", label: "minutes (<10min) — runs with a notice" };
+    return { tier: "sloth", label: "sloth (≥10min) — prints the projection and refuses without --yes" };
+}
+// ── Hostile-canvas classification (heuristic; prime / coprime axis) ──
+function gcd2(a, b) {
+    a = Math.abs(a);
+    b = Math.abs(b);
+    while (b) {
+        const t = b;
+        b = a % b;
+        a = t;
+    }
+    return a;
+}
+/** An axis is hostile when it shares little with the modern lattice (gcd(dim,120) < 8):
+ *  primes and coprime strays — where placeInsetPieces degrades to exact placement. */
+function isHostileCanvas(w, h, basis = 120) {
+    const axisHostile = (n) => gcd2(n, basis) < 8;
+    return axisHostile(w) || axisHostile(h);
+}
+// ── §3c routing hints (the ladder comes first; branching is the last rung) ──
+function routingHint(kind, allHostile) {
+    switch (kind) {
+        case "size":
+        case "position":
+            return allHostile
+                ? "hostile canvas — if persistent, add a §3c fix#1 per-canvas ratio branch (return a cleanly-dividing m0 for this dim)."
+                : "off-grid placement — launder ladder: uniform grid → gutterless grid() + latticeCellInset (retargeted exact insets; gridCellInset is deprecated — ideal-cell fractions wobble ±1px); independent chrome → placeInsetPieces (inset-recovery) or placeOptimizedPieces (drift).";
+        case "inset-recovery":
+            return "inset recovery did NOT reproduce intent — an ENGINE (applyInsetToRect) or EMITTER (placeInsetRects half-pixel-centering) bug. File it; do not paper over.";
+        case "mask-scale":
+            return "mask bounds distort into the painted box — author the mark as a mask-in-a-cell with bounds = the cell aspect (§3c), or fix the rect aspect.";
+        case "min-size":
+            return "element clipped below its min — enlarge its cell / raise the font floor; a fixed-font band must not shrink below its glyph run.";
+        case "aspect":
+            return "realized aspect ≠ intended — pin the cell aspect via the ratio structure, or check the source's fit/pad.";
+        case "missing-frame":
+            return "no frame matched — expectations drifted from the m0 (paint order / count changed) or a piece was dropped; re-derive expectations from the front door.";
+        default:
+            return "see feasibility §3c (the launder ladder).";
+    }
+}
+/** Group violations across canvases by (piece, kind, axis) — the point is to
+ *  PROVE the contract without emitting a row per canvas over a million-pair run. */
+function clusterViolations(results) {
+    var _a, _b, _c;
+    const map = new Map();
+    for (const r of results) {
+        if (!r.violations || r.violations.length === 0)
+            continue;
+        const wh = `${r.w}x${r.h}`;
+        const hostile = isHostileCanvas(r.w, r.h);
+        for (const v of r.violations) {
+            const key = `${(_a = v.name) !== null && _a !== void 0 ? _a : "?"}|${v.kind}|${(_b = v.axis) !== null && _b !== void 0 ? _b : "-"}`;
+            let g = map.get(key);
+            if (!g) {
+                g = { name: v.name, kind: v.kind, axis: v.axis, canvases: [] };
+                map.set(key, g);
+            }
+            g.canvases.push({ wh, delta: Math.abs((_c = v.deltaPx) !== null && _c !== void 0 ? _c : 0), hostile });
+        }
+    }
+    const clusters = [];
+    for (const g of map.values()) {
+        const bySeverity = [...g.canvases].sort((a, b) => b.delta - a.delta || a.wh.localeCompare(b.wh));
+        clusters.push({
+            name: g.name,
+            kind: g.kind,
+            axis: g.axis,
+            count: g.canvases.length,
+            maxDeltaPx: bySeverity[0].delta,
+            maxCanvas: bySeverity[0].wh,
+            minDeltaPx: bySeverity[bySeverity.length - 1].delta,
+            minCanvas: bySeverity[bySeverity.length - 1].wh,
+            examples: g.canvases.slice(0, 8).map((c) => c.wh),
+            hint: routingHint(g.kind, g.canvases.every((c) => c.hostile)),
+        });
+    }
+    clusters.sort((a, b) => { var _a, _b, _c, _d; return b.count - a.count || ((_a = a.name) !== null && _a !== void 0 ? _a : "").localeCompare((_b = b.name) !== null && _b !== void 0 ? _b : "") || a.kind.localeCompare(b.kind) || ((_c = a.axis) !== null && _c !== void 0 ? _c : "").localeCompare((_d = b.axis) !== null && _d !== void 0 ? _d : ""); });
+    return clusters;
+}
+/** Build the clustered PROVEN/FAILED report markdown. Pure — the gen-script wires
+ *  the resolve loop + timing to it; tested directly with synthetic failures. */
+function buildProofReport(input) {
+    var _a;
+    const { templateId, specStr, total, propsHash, wallMs, projectedMs, tier, failures, floors, hostile } = input;
+    const proven = failures.length === 0;
+    const errored = failures.filter((f) => f.error);
+    const clusters = clusterViolations(failures);
+    const out = [];
+    out.push(`# Geometry proof — ${templateId}\n`);
+    out.push("> Auto-generated by `gen-geometry-proof` (sloth tier; NOT in the merge gate).\n");
+    out.push(`- **set:** ${specStr} · **|canvases|** ${total.toLocaleString()}`);
+    out.push(`- **props hash:** \`${propsHash}\``);
+    out.push(`- **wall:** ${(wallMs / 1000).toFixed(1)}s · **estimator projected** ${(projectedMs / 1000).toFixed(1)}s (${tier})`);
+    out.push("");
+    if (proven)
+        out.push(`## ✅ PROVEN — all ${total.toLocaleString()} canvases meet the contract\n`);
+    else
+        out.push(`## ❌ FAILED — ${failures.length.toLocaleString()} of ${total.toLocaleString()} canvases violate\n`);
+    if (clusters.length > 0) {
+        out.push("### Failure clusters (grouped by piece · kind · axis)\n");
+        out.push("| piece | kind | axis | canvases | Δpx (min…max) | example canvases | routing |");
+        out.push("|---|---|---|---:|---|---|---|");
+        for (const c of clusters) {
+            out.push(`| ${c.name ? `\`${c.name}\`` : "—"} | ${c.kind} | ${(_a = c.axis) !== null && _a !== void 0 ? _a : "—"} | ${c.count} | ${c.minDeltaPx}…${c.maxDeltaPx} (worst @ ${c.maxCanvas}) | ${c.examples.join(", ")}${c.count > c.examples.length ? " …" : ""} | ${c.hint} |`);
+        }
+        out.push("");
+    }
+    if (errored.length > 0) {
+        out.push(`### Resolve errors (${errored.length})\n`);
+        for (const e of errored.slice(0, 12))
+            out.push(`- \`${e.w}x${e.h}\` — ${e.error}`);
+        if (errored.length > 12)
+            out.push(`- …and ${errored.length - 12} more`);
+        out.push("");
+    }
+    out.push("### Floors summary\n");
+    out.push(`- **infeasible canvases:** ${floors.firstInfeasible ? `first at ${floors.firstInfeasible}` : "none"}`);
+    out.push(`- **sub-precision canvases:** ${floors.firstSubPrec ? `first at ${floors.firstSubPrec}` : "none"}`);
+    out.push(`- **max quantization spread:** ${floors.maxSpread.toFixed(1)}px${floors.maxSpreadCanvas ? ` @ ${floors.maxSpreadCanvas}` : ""}`);
+    out.push("");
+    out.push("### Hostile-degradation ledger\n");
+    out.push(`- ${hostile.total.toLocaleString()} hostile canvas(es) (prime / coprime axis; heuristic gcd(dim,120)<8) — ` +
+        `${hostile.passed.toLocaleString()} passed via exact-placement degradation (expected).`);
+    if (hostile.examples.length)
+        out.push(`- examples: ${hostile.examples.join(", ")}${hostile.total > hostile.examples.length ? " …" : ""}`);
+    out.push("");
+    return { md: out.join("\n") + "\n", proven };
+}
+const minDim = (s) => Math.min(s.w, s.h);
+const wh = (s) => `${s.w}x${s.h}`;
+/**
+ * From per-canvas violation samples, compute — for every invariant that broke
+ * anywhere — the canvas range where it holds vs breaks, with a boundary when the
+ * break region is monotone (breaks below/above a scale). PURE.
+ */
+function computeEnvelopes(samples) {
+    const sorted = [...samples].sort((a, b) => minDim(a) - minDim(b) || a.w - b.w || a.h - b.h);
+    const keys = new Set();
+    for (const s of samples)
+        for (const k of s.violated)
+            keys.add(k);
+    const envs = [];
+    for (const key of keys) {
+        const sep = key.indexOf("|");
+        const label = sep >= 0 ? key.slice(0, sep) : key;
+        const rule = sep >= 0 ? key.slice(sep + 1) : "";
+        const breaks = sorted.filter((s) => s.violated.includes(key));
+        const holds = sorted.filter((s) => !s.violated.includes(key));
+        let boundary = null;
+        if (breaks.length && holds.length) {
+            const maxBreak = Math.max(...breaks.map(minDim));
+            const minBreak = Math.min(...breaks.map(minDim));
+            const maxHold = Math.max(...holds.map(minDim));
+            const minHold = Math.min(...holds.map(minDim));
+            if (maxBreak < minHold)
+                boundary = `breaks ≤ ${maxBreak}px, holds ≥ ${minHold}px`;
+            else if (minBreak > maxHold)
+                boundary = `holds ≤ ${maxHold}px, breaks ≥ ${minBreak}px`;
+        }
+        else if (holds.length === 0) {
+            boundary = "breaks across the whole sweep";
+        }
+        envs.push({
+            key, label, rule,
+            holdCount: holds.length,
+            breakCount: breaks.length,
+            boundary,
+            examples: breaks.slice(0, 6).map(wh),
+        });
+    }
+    return envs.sort((a, b) => b.breakCount - a.breakCount || a.key.localeCompare(b.key));
+}
+/** The `LAYOUT-ENVELOPE.md` body for one template's sweep. Pure. */
+function buildEnvelopeReport(templateId, sweepDesc, samples) {
+    var _a;
+    const envs = computeEnvelopes(samples);
+    const fullyOk = samples.filter((s) => s.violated.length === 0).length;
+    const out = [];
+    out.push(`# Layout envelope — ${templateId}\n`);
+    out.push(`> Auto-generated by \`gen-layout-envelope\`. Sweep: ${sweepDesc} · ${samples.length} canvases · resolve-only, no ffmpeg.\n`);
+    out.push(`- **Fully satisfied** at ${fullyOk}/${samples.length} swept canvases.\n`);
+    if (envs.length === 0) {
+        out.push(`## ✅ Every declared invariant held at every swept canvas.\n`);
+        return out.join("\n") + "\n";
+    }
+    out.push(`## ⚠ Invariants that break somewhere (${envs.length})\n`);
+    out.push("| invariant | holds | breaks | boundary | example break canvases |");
+    out.push("|---|---:|---:|---|---|");
+    for (const e of envs) {
+        out.push(`| \`${e.label}\` · ${e.rule} | ${e.holdCount} | ${e.breakCount} | ${(_a = e.boundary) !== null && _a !== void 0 ? _a : "mixed (see examples)"} | ${e.examples.join(", ")}${e.breakCount > e.examples.length ? " …" : ""} |`);
+    }
+    out.push("");
+    out.push("_A monotone boundary (`breaks ≤ Npx`) means: restrict the template's declared output range to the holding side, or fix the geometry math for the range you need._");
+    out.push("");
+    return out.join("\n") + "\n";
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import "./m0saic";
+export { requireTemplate, getTemplate, listRegisteredTemplateIds, } from "@m0saic/template-utils";
+export * from "./m0saic";
+export * from "./repo";
+export * from "./webTemplateIds";

package/dist/index.js

@@ -0,0 +1,29 @@
+"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 });
+exports.listRegisteredTemplateIds = exports.getTemplate = exports.requireTemplate = void 0;
+// IMPORTANT: side-effect import that registers all templates
+require("./m0saic");
+// Re-export registry helpers
+var template_utils_1 = require("@m0saic/template-utils");
+Object.defineProperty(exports, "requireTemplate", { enumerable: true, get: function () { return template_utils_1.requireTemplate; } });
+Object.defineProperty(exports, "getTemplate", { enumerable: true, get: function () { return template_utils_1.getTemplate; } });
+Object.defineProperty(exports, "listRegisteredTemplateIds", { enumerable: true, get: function () { return template_utils_1.listRegisteredTemplateIds; } });
+// Optional: still export template modules/types
+__exportStar(require("./m0saic"), exports);
+__exportStar(require("./repo"), exports);
+// Which ids the BROWSER entry registers (node-only reader of web-template-ids.json).
+__exportStar(require("./webTemplateIds"), exports);

package/dist/m0saic/_shared/onboarding-cover.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The mosaic-branding cover kit — the ONE cover theme every shipped
+ * template's editor first-open face is built on.
+ *
+ * Born on screencap_grid/v2 (gate 24), reused by aspect_safe (gate 25) and
+ * subtitle-burn (gate 26); hoisted here per the founder's gate-26 directive
+ * ("i want the other shipped templates to rework their cover to match this
+ * theme. the mosaic branding cover") so alpine/charts consumers stop
+ * importing across `media/screencap_grid/…` (wrong-way coupling).
+ *
+ * The theme contract (the internal mosaic-branding-covers notes):
+ *   left CHAT PANE — brand row (m0saic M + product name), headline +
+ *   one-sentence overview, three accent message bubbles (the template's
+ *   3-step mental model), a framed START HERE tip;
+ *   right HERO — REAL MATERIAL: the template's own output, never abstract
+ *   placeholder art.
+ *
+ * Everything from the v2 kit re-exports UNCHANGED below (byte-identical
+ * pass-throughs — existing consumers can migrate imports without churn);
+ * `buildBrandedCover` is the new copy-parameterized assembler that turns a
+ * per-template cover into a ~40-line copy declaration + a hero composition.
+ */
+import type { MosaicAssetManifest, MosaicDocument, MosaicEngineContext, MosaicThemeTokens } from "@m0saic/types";
+import { type OnboardingComposition, type OnboardingTypeRamp } from "../media/screencap_grid/v2/screencap-grid-cover";
+export { SCREENCAP_ONBOARDING_THEME as ONBOARDING_THEME, resolveScreencapOnboardingTheme as resolveOnboardingTheme, onboardingTypeRamp, coverTypeRamp, onboardingLeaf, onboardingSplit, onboardingOverlay, onboardingGuttered, onboardingTextSource, onboardingTextBlock, onboardingSolid, onboardingFrame, onboardingTimestampTile, } from "../media/screencap_grid/v2/screencap-grid-cover";
+export type { OnboardingComposition, OnboardingTypeRamp, } from "../media/screencap_grid/v2/screencap-grid-cover";
+export { tutorialAssets as onboardingBrandAssets, tutorialBrand as onboardingBrandRow, } from "../media/screencap_grid/v2/screencap-grid-tutorial";
+/** One accent message bubble: micro label + one-line body. */
+export type BrandedCoverMessage = {
+    label: string;
+    body: string;
+    /** Shorter body used under 480px min-dim. Falls back to `body`. */
+    bodyCompact?: string;
+};
+export type BrandedCoverCopy = {
+    /** Brand-row product name (beside the m0saic M mark). */
+    productName: string;
+    /** Short declarative headline. */
+    title: string;
+    /** Pane variant only: one-sentence overview under the headline. */
+    overview?: string;
+    /** Shorter overview used under 480px min-dim. Falls back to `overview`. */
+    overviewCompact?: string;
+    /** Pane variant only: the template's 3-step mental model. */
+    messages?: BrandedCoverMessage[];
+    /** Pane variant only: the one action that produces output. */
+    tip?: string;
+    /** Tip micro label — theme default "START HERE". */
+    tipLabel?: string;
+};
+/**
+ * Inline-flat hero from a rendered document — the gate-15/21 keeper path:
+ * procedural masked content (donut rings, rounded shapes) must NEVER ride a
+ * nested `type:"mosaic"` child (the child composite pass bleeds seams and
+ * distorts); its m0 + sources inline directly as the hero cell's claimant.
+ */
+export declare function inlineHeroDoc(doc: MosaicDocument): OnboardingComposition;
+/**
+ * Assemble the branded cover document: chat pane + hero on the onboarding
+ * theme surface, landscape `[4,30,3,59,4]` columns / stacked portrait /
+ * compact copy under 480px min-dim — the exact layout shipped on gates
+ * 24-26.
+ *
+ * `hero` receives the resolved theme + type ramp and the layout flags and
+ * returns the right-side composition (REAL MATERIAL — often the template's
+ * own static render nested via `children`). `heroAssets` merge over the
+ * brand assets; `children` attach to the returned document for nested-doc
+ * heroes (`{type:"mosaic", ref:"…"}` leaves).
+ */
+export declare function buildBrandedCover(args: {
+    ctx: MosaicEngineContext;
+    copy: BrandedCoverCopy;
+    hero: (theme: MosaicThemeTokens, type: OnboardingTypeRamp, layout: {
+        stacked: boolean;
+        compact: boolean;
+    }) => OnboardingComposition;
+    heroAssets?: MosaicAssetManifest;
+    children?: Record<string, MosaicDocument>;
+    /**
+     * "band" (founder ruling 08-30): the SIMPLE brand view for basic viz
+     * templates — hero full-bleed + a px-clamped brand band (M mark, product
+     * name, title). "pane" (default) keeps the full chat-pane conversation —
+     * defensible for media-class templates that genuinely need explaining.
+     */
+    variant?: "pane" | "band";
+}): MosaicDocument;
+/**
+ * The approximate pixel box the landscape hero composition paints into —
+ * for sizing a nested child render so its internal proportions match the
+ * tile it lands in (page row 90% × content hero column 59%).
+ */
+export declare function brandedCoverHeroBox(ctx: MosaicEngineContext, variant?: "pane" | "band"): {
+    width: number;
+    height: number;
+};