@m0saic/templates 0.2.0

package/dist/m0saic/code/snippet-morph/v1/snippet-morph.d.ts

@@ -0,0 +1,61 @@
+/** @m0saic/code/snippet-morph/v1 — deterministic code-state video template. */
+import { type MosaicTemplate } from "@m0saic/types";
+import { type CodeThemePreset, type CodeTokenKind } from "../../_shared/code-theme";
+import type { CodeLanguage } from "../../_shared/code-lexer";
+import { type SnippetFrameGeometry } from "./internal/chrome";
+import { type SnippetMorphPlan } from "./internal/plan";
+import { type SnippetAddEntrance, type SnippetCodeAlign, type SnippetStepVisualOptions } from "./internal/steps";
+export declare const SNIPPET_MORPH_V1_ID = "@m0saic/code/snippet-morph/v1";
+export interface SnippetTypographyConfig {
+    fontSize?: number;
+    lineHeight?: number;
+    tabWidth?: number;
+}
+export interface SnippetTimingConfig {
+    morphMs?: number;
+    holdMs?: number;
+    leadMs?: number;
+    trailMs?: number;
+}
+export type SnippetThemeConfig = {
+    preset?: CodeThemePreset;
+} & Partial<Record<CodeTokenKind, string | null>>;
+export interface SnippetChromeConfig {
+    show?: boolean;
+    title?: string;
+    trafficLights?: boolean;
+    lineNumbers?: boolean;
+    codeAlign?: SnippetCodeAlign;
+    /** Card fills the canvas edge to edge (default). Off = framed card with a margin. */
+    fullBleed?: boolean;
+}
+export interface SnippetAnimationConfig {
+    reduceMotion?: boolean;
+    addEntrance?: SnippetAddEntrance;
+}
+export interface SnippetMorphV1Props {
+    [key: string]: unknown;
+    states: string[];
+    language?: CodeLanguage;
+    typography?: SnippetTypographyConfig;
+    timing?: SnippetTimingConfig;
+    theme?: SnippetThemeConfig;
+    chrome?: SnippetChromeConfig;
+    animation?: SnippetAnimationConfig;
+    /** Human-facing derived control; the editor syncs it to animation.reduceMotion. */
+    animate?: boolean;
+    debugLayout?: boolean;
+}
+export interface SnippetResolvedVisualLayout {
+    visual: SnippetStepVisualOptions;
+    geometry: SnippetFrameGeometry;
+    fits: boolean;
+    overflowX: boolean;
+    overflowY: boolean;
+}
+/** Resolve one shared integer font size against the worst state at this canvas. */
+export declare function resolveSnippetVisualLayout(states: SnippetMorphPlan["states"], target: {
+    width: number;
+    height: number;
+}, preferredVisual: SnippetStepVisualOptions): SnippetResolvedVisualLayout;
+export declare const SnippetMorphV1: MosaicTemplate<SnippetMorphV1Props>;

package/dist/m0saic/code/snippet-morph/v1/snippet-morph.js

@@ -0,0 +1,462 @@
+"use strict";
+/** @m0saic/code/snippet-morph/v1 — deterministic code-state video template. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnippetMorphV1 = exports.SNIPPET_MORPH_V1_ID = void 0;
+exports.resolveSnippetVisualLayout = resolveSnippetVisualLayout;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const code_theme_1 = require("../../_shared/code-theme");
+const code_metrics_1 = require("../../_shared/code-metrics");
+const chrome_1 = require("./internal/chrome");
+const plan_1 = require("./internal/plan");
+const steps_1 = require("./internal/steps");
+exports.SNIPPET_MORPH_V1_ID = "@m0saic/code/snippet-morph/v1";
+const DEFAULT_STATE = [
+    "type Launch = {",
+    "  product: string;",
+    "  audience: \"developers\";",
+    "};",
+    "",
+    "const launch: Launch = {",
+    "  product: \"m0saic\",",
+    "  audience: \"developers\",",
+    "};",
+].join("\n");
+// Gate 31/32 ruling class ("the default face is a real layout"): a MORPH
+// template's default must show a morph, so the default carries a second
+// state — two inserted fields and a new function, so lines move, lines are
+// added, and the reveal reads on first open. 2 × (750 + 3000) = 7.5s.
+const DEFAULT_STATE_2 = [
+    "type Launch = {",
+    "  product: string;",
+    "  audience: \"developers\";",
+    "  date?: string;",
+    "};",
+    "",
+    "const launch: Launch = {",
+    "  product: \"m0saic\",",
+    "  audience: \"developers\",",
+    "  date: \"2026-09\",",
+    "};",
+    "",
+    "export function announce(l: Launch) {",
+    "  console.log(l.product + \" ships \" + l.date);",
+    "}",
+].join("\n");
+function fBool(label, description, consumer) {
+    return {
+        type: "boolean",
+        required: false,
+        description,
+        meta: { ui: { label, ...(consumer ? { consumer } : {}) } },
+    };
+}
+function fNum(label, description, min, max, step, unit) {
+    return {
+        type: "number",
+        required: false,
+        description,
+        meta: {
+            constraints: { min, max },
+            control: { flavor: "slider", step, ...(unit ? { unit } : {}) },
+            ui: { label },
+        },
+    };
+}
+function fEnum(label, options, description) {
+    return {
+        type: "string",
+        required: false,
+        description,
+        meta: { constraints: { oneOf: [...options] }, ui: { label } },
+    };
+}
+function fColor(label, description, placeholder) {
+    return {
+        type: "string",
+        required: false,
+        description,
+        meta: {
+            constraints: { isColor: true },
+            control: { colorPicker: true, ...(placeholder ? { placeholder } : {}) },
+            ui: { label },
+        },
+    };
+}
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    states: {
+        type: "string[]",
+        required: true,
+        description: "Ordered TypeScript/JavaScript source states.",
+        meta: {
+            constraints: { minItems: 1 },
+            // Each state is a whole source file: line breaks are the value. A
+            // single-line input strips them on the first keystroke (2026-09-16).
+            control: { placeholder: "const answer = 42;", multiline: true, mono: true },
+            ui: { label: "Code states", order: 1 },
+        },
+    },
+    language: {
+        type: "string",
+        required: false,
+        description: "Syntax lexer.",
+        meta: {
+            constraints: { oneOf: ["ts", "js"] },
+            ui: { label: "Language", order: 2 },
+        },
+    },
+    typography: {
+        type: "group",
+        required: false,
+        description: "JetBrains Mono sizing and source normalization.",
+        meta: { ui: { label: "Typography", order: 3, collapsedByDefault: true } },
+        fields: {
+            fontSize: fNum("Font size", "Preferred font size; auto-fits down to 8px.", 10, 48, 1, "px"),
+            lineHeight: fNum("Line height", 
+            // Floor 1.35: the line box must contain the mono font's ink height
+            // (JetBrains Mono ≈ 1.32em) or block PNGs stop tiling seamlessly.
+            "Code line-height multiplier.", 1.35, 2, 0.05),
+            tabWidth: fNum("Tab width", "Spaces used to expand each tab.", 1, 8, 1),
+        },
+    },
+    timing: {
+        type: "group",
+        required: false,
+        description: "Per-state morph, hold, lead, and trail timing.",
+        meta: { ui: { label: "Timing", order: 4, collapsedByDefault: true } },
+        fields: {
+            morphMs: fNum("Morph", "Morph window per state.", 100, 2000, 50, "ms"),
+            holdMs: fNum("Hold", "Rest window per state.", 500, 10000, 100, "ms"),
+            leadMs: fNum("Lead", "Lead-in before the first reveal.", 0, 10000, 100, "ms"),
+            trailMs: fNum("Trail", "Trail after the final hold.", 0, 10000, 100, "ms"),
+        },
+    },
+    theme: {
+        type: "group",
+        required: false,
+        description: "Editor preset plus optional syntax-token overrides.",
+        meta: { ui: { label: "Theme", order: 5, collapsedByDefault: true } },
+        fields: {
+            preset: fEnum("Preset", code_theme_1.CODE_THEME_PRESET_KEYS, "Built-in editor colorway."),
+            keyword: fColor("Keywords", "Override keyword tokens; clear to use the preset.", "preset palette"),
+            string: fColor("Strings", "Override string tokens; clear to use the preset.", "preset palette"),
+            comment: fColor("Comments", "Override comment tokens; clear to use the preset.", "preset palette"),
+            number: fColor("Numbers", "Override numeric tokens; clear to use the preset.", "preset palette"),
+            fnCall: fColor("Function calls", "Override function-call tokens; clear to use the preset.", "preset palette"),
+            ident: fColor("Identifiers", "Override identifier tokens; clear to use the preset.", "preset palette"),
+            operator: fColor("Operators", "Override operator tokens; clear to use the preset.", "preset palette"),
+            punct: fColor("Punctuation", "Override punctuation tokens; clear to use the preset.", "preset palette"),
+            plain: fColor("Plain text", "Override plain tokens; clear to use the preset.", "preset palette"),
+        },
+    },
+    chrome: {
+        type: "group",
+        required: false,
+        description: "Editor card, title bar, controls, gutter, and code alignment.",
+        meta: { ui: { label: "Chrome", order: 6, collapsedByDefault: true } },
+        fields: {
+            show: fBool("Show", "Show editor chrome."),
+            title: {
+                type: "string",
+                required: false,
+                description: "Filename shown in the editor title bar.",
+                meta: { ui: { label: "Title" } },
+            },
+            trafficLights: fBool("Traffic lights", "Show the three editor window controls."),
+            lineNumbers: fBool("Line numbers", "Show a line-number gutter."),
+            codeAlign: fEnum("Code alignment", ["left", "center"], "Horizontal alignment inside the code area."),
+            fullBleed: fBool("Full bleed", "Fill the canvas edge to edge (default). Off restores the framed card with a margin around it."),
+        },
+    },
+    animation: {
+        type: "group",
+        required: false,
+        description: "Motion accessibility and addition entrance.",
+        meta: { ui: { label: "Animation", order: 7, collapsedByDefault: true } },
+        fields: {
+            reduceMotion: fBool("Reduce motion", "Use hard cuts with every code state at rest.", "agent"),
+            addEntrance: fEnum("Added code entrance", ["fade", "rise"], "How newly added code enters during each morph."),
+        },
+    },
+    animate: {
+        type: "boolean",
+        required: false,
+        description: "Animate code changes.",
+        meta: {
+            control: {
+                syncsTo: [
+                    { prop: "animation.reduceMotion", map: { kind: "boolInvert" } },
+                ],
+            },
+            ui: { label: "Animate", order: 8, consumer: "human", primary: true },
+        },
+    },
+    debugLayout: {
+        type: "boolean",
+        required: false,
+        description: "Assert the card/code-area/gutter/title layout contract.",
+        meta: { ui: { label: "Debug layout", order: 9, collapsedByDefault: true } },
+    },
+});
+function dimensions(ctx) {
+    var _a;
+    return {
+        width: Math.max(1, Math.round(ctx.target.width)),
+        height: Math.max(1, Math.round(ctx.target.height)),
+        fps: Math.max(1, Math.round((_a = ctx.target.fps) !== null && _a !== void 0 ? _a : 30)),
+    };
+}
+function visualOptions(props) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const typography = (_a = props.typography) !== null && _a !== void 0 ? _a : {};
+    const chrome = (_b = props.chrome) !== null && _b !== void 0 ? _b : {};
+    return {
+        fontSize: (_c = typography.fontSize) !== null && _c !== void 0 ? _c : 16,
+        lineHeight: (_d = typography.lineHeight) !== null && _d !== void 0 ? _d : 1.5,
+        fontFamily: "JetBrains Mono",
+        fontWeight: "normal",
+        fontStyle: "normal",
+        title: (_e = chrome.title) !== null && _e !== void 0 ? _e : "snippet.ts",
+        showChrome: (_f = chrome.show) !== null && _f !== void 0 ? _f : true,
+        trafficLights: (_g = chrome.trafficLights) !== null && _g !== void 0 ? _g : true,
+        lineNumbers: (_h = chrome.lineNumbers) !== null && _h !== void 0 ? _h : true,
+        codeAlign: (_j = chrome.codeAlign) !== null && _j !== void 0 ? _j : "left",
+        // Gate 32 (founder): the card takes the whole canvas by default; the
+        // framed look with a margin is one toggle away.
+        fullBleed: (_k = chrome.fullBleed) !== null && _k !== void 0 ? _k : true,
+    };
+}
+function planFor(props, targetDurationMs) {
+    var _a, _b, _c, _d;
+    const typography = (_a = props.typography) !== null && _a !== void 0 ? _a : {};
+    const timing = (_b = props.timing) !== null && _b !== void 0 ? _b : {};
+    return (0, plan_1.buildSnippetMorphPlan)({
+        states: props.states,
+        language: (_c = props.language) !== null && _c !== void 0 ? _c : "ts",
+        tabWidth: (_d = typography.tabWidth) !== null && _d !== void 0 ? _d : 2,
+        timing: {
+            morphMs: timing.morphMs,
+            holdMs: timing.holdMs,
+            leadMs: timing.leadMs,
+            trailMs: timing.trailMs,
+        },
+        targetDurationMs,
+    });
+}
+function resolvedTheme(props) {
+    var _a;
+    const config = (_a = props.theme) !== null && _a !== void 0 ? _a : {};
+    const base = (0, code_theme_1.codeTheme)(config.preset);
+    const overrides = Object.fromEntries(code_theme_1.CODE_TOKEN_KINDS.map((kind) => [kind, config[kind]]));
+    return {
+        ...base,
+        syntax: (0, code_theme_1.resolveCodeSyntaxTheme)(base, overrides),
+    };
+}
+/** Resolve one shared integer font size against the worst state at this canvas. */
+function resolveSnippetVisualLayout(states, target, preferredVisual) {
+    var _a;
+    const preferredFontSize = Math.max(code_metrics_1.MIN_AUTOFIT_FONT_SIZE, Math.floor(preferredVisual.fontSize));
+    let floorResult;
+    for (let fontSize = preferredFontSize; fontSize >= code_metrics_1.MIN_AUTOFIT_FONT_SIZE; fontSize -= 1) {
+        const visual = { ...preferredVisual, fontSize };
+        const geometry = (0, chrome_1.computeSnippetFrameGeometry)({
+            width: target.width,
+            height: target.height,
+            fontSize,
+            showChrome: visual.showChrome,
+            lineNumbers: visual.lineNumbers,
+            fullBleed: (_a = visual.fullBleed) !== null && _a !== void 0 ? _a : false,
+        });
+        const metrics = states.map((state) => (0, code_metrics_1.measureCodeGrid)(state.lines, {
+            fontSize,
+            lineHeight: visual.lineHeight,
+        }));
+        const overflowX = metrics.some((stateMetrics) => stateMetrics.width > geometry.codeArea.w);
+        const overflowY = metrics.some((stateMetrics) => stateMetrics.height > geometry.codeArea.h);
+        const result = {
+            visual,
+            geometry,
+            fits: !overflowX && !overflowY,
+            overflowX,
+            overflowY,
+        };
+        if (result.fits)
+            return result;
+        if (fontSize === code_metrics_1.MIN_AUTOFIT_FONT_SIZE)
+            floorResult = result;
+    }
+    if (floorResult)
+        return floorResult;
+    throw new Error("resolveSnippetVisualLayout: autofit search produced no result");
+}
+function snippetLayoutConstraints(visual) {
+    const constraints = [
+        {
+            label: "card",
+            minWidthFrac: 0.65,
+            // 1.0 = the full-bleed default (the card IS the canvas); the framed
+            // card sits at ~0.86 × 0.84.
+            maxWidthFrac: 1,
+            minHeightFrac: 0.65,
+            maxHeightFrac: 1,
+            within: { xFrac: [0, 1], yFrac: [0, 1] },
+        },
+        {
+            label: "code-area",
+            minWidthFrac: 0.4,
+            minHeightFrac: 0.45,
+            within: { xFrac: [0, 1], yFrac: [0, 1] },
+        },
+    ];
+    if (visual.lineNumbers) {
+        constraints.push({
+            label: "gutter",
+            maxWidthFrac: 0.2,
+            minHeightFrac: 0.45,
+            within: { xFrac: [0, 1], yFrac: [0, 1] },
+        });
+    }
+    if (visual.showChrome) {
+        constraints.push({
+            label: "title",
+            minWidthFrac: 0.2,
+            maxHeightFrac: 0.15,
+            within: { xFrac: [0, 1], yFrac: [0, 1] },
+        });
+    }
+    return constraints;
+}
+function withSnippetLayoutContract(doc, ctx, visual, debug, durationMs) {
+    const stepCtx = durationMs == null
+        ? ctx
+        : {
+            ...ctx,
+            target: { ...ctx.target, durationMs },
+        };
+    return (0, template_utils_1.withLayoutContract)(doc, stepCtx, {
+        templateId: exports.SNIPPET_MORPH_V1_ID,
+        constraints: snippetLayoutConstraints(visual),
+        flatten: false,
+        debug,
+    });
+}
+function prepareSnippetRender(props, ctx, target) {
+    try {
+        const plan = planFor(props, (0, template_utils_1.resolvePinnedDurationMs)(ctx));
+        const layout = resolveSnippetVisualLayout(plan.states, target, visualOptions(props));
+        if (layout.overflowY) {
+            throw new Error(`Code exceeds the ${layout.geometry.codeArea.h}px code-area height at the ${code_metrics_1.MIN_AUTOFIT_FONT_SIZE}px autofit floor; use fewer lines`);
+        }
+        return { ok: true, plan, layout };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: (0, template_utils_1.makeErrorMosaic)(message, {
+                width: target.width,
+                height: target.height,
+                title: "Code Snippet Morph",
+                errorCode: "SNIPPET_MORPH_INVALID_INPUT",
+            }),
+        };
+    }
+}
+exports.SnippetMorphV1 = {
+    id: (0, types_1.asTemplateId)(exports.SNIPPET_MORPH_V1_ID),
+    label: "Code Snippet Morph",
+    description: "Morphs ordered TypeScript/JavaScript code states into a deterministic editor-frame video with moving, added, and removed lines.",
+    version: 1,
+    // Core tier since the svg-text promotion (09-05): every code line is a
+    // native svg text source the ENGINE rasterizes (one coloured RGBA image per
+    // line) — no template-side sharp, no workspace files, no renderLite. The
+    // document Make previews is the document ffmpeg renders.
+    capabilities: { tier: "core" },
+    tags: ["developer", "code", "snippet", "animated", "developers", "diff", "tutorial"],
+    outputHints: {
+        width: 1280,
+        height: 720,
+        fps: 30,
+        // The natural length of the 2-state default (2 × (morph 750 + hold 3000)).
+        // A HINT only: the plan authors its own length from states × timing, and
+        // an explicit --durationMs / form duration pins it (resolvePinnedDurationMs).
+        durationMs: 7500,
+        format: { kind: "video", container: "mp4" },
+    },
+    propsSchema,
+    defaultProps: {
+        states: [DEFAULT_STATE, DEFAULT_STATE_2],
+        language: "ts",
+        typography: {
+            fontSize: 16,
+            lineHeight: 1.5,
+            tabWidth: 2,
+        },
+        timing: {
+            morphMs: 750,
+            holdMs: 3000,
+            leadMs: 0,
+            trailMs: 0,
+        },
+        theme: { preset: "dark" },
+        chrome: {
+            show: true,
+            title: "snippet.ts",
+            trafficLights: true,
+            lineNumbers: true,
+            codeAlign: "left",
+            fullBleed: true,
+        },
+        animation: {
+            reduceMotion: false,
+            addEntrance: "rise",
+        },
+        debugLayout: false,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f;
+        const target = dimensions(ctx);
+        const prepared = prepareSnippetRender(props, ctx, target);
+        if (!prepared.ok)
+            return prepared.error;
+        const { plan, layout: { visual, geometry } } = prepared;
+        const theme = resolvedTheme(props);
+        const animation = (_a = props.animation) !== null && _a !== void 0 ? _a : {};
+        // One doc per state, each carrying the morph INTO it (lines slide from
+        // their old row, adds fade + rise, removals fade out). Every code line is
+        // one svg text source with a layer per token run; core rasterizes it to a
+        // coloured image. Pure: the same pipeline serves an explicit make and
+        // Make's live preview (no renderLite).
+        const pipeline = (0, steps_1.buildSnippetPipeline)({
+            plan,
+            // Raw states → each code line binds ITS line of its state (Make ranged
+            // inline edit: double-click a line, Enter splices just that line back).
+            rawStates: props.states,
+            tabWidth: (_c = (_b = props.typography) === null || _b === void 0 ? void 0 : _b.tabWidth) !== null && _c !== void 0 ? _c : 2,
+            geometry,
+            theme,
+            visual,
+            width: target.width,
+            height: target.height,
+            fps: target.fps,
+            motion: {
+                reduceMotion: (_d = animation.reduceMotion) !== null && _d !== void 0 ? _d : false,
+                addEntrance: (_e = animation.addEntrance) !== null && _e !== void 0 ? _e : "rise",
+            },
+        });
+        const debugLayout = (_f = props.debugLayout) !== null && _f !== void 0 ? _f : false;
+        return {
+            ...pipeline,
+            steps: pipeline.steps.map((step) => {
+                if (!("file" in step) || step.file == null)
+                    return step;
+                return {
+                    ...step,
+                    file: withSnippetLayoutContract(step.file, ctx, visual, debugLayout, step.durationMs),
+                };
+            }),
+        };
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.SnippetMorphV1);

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

@@ -0,0 +1,18 @@
+/**
+ * Demo fixture — the zero-setup collage.
+ *
+ * When no images are supplied the template packs this deterministic set of
+ * synthetic "photos" (aspect + tile color) instead of erroring. That gives a
+ * meaningful defaultProps render everywhere it matters: the Templates-page
+ * preview, the media-free CLI E2E case, and the `audit:layout-envelope`
+ * sweep (which renders defaultProps at 51 canvases and needs the contract to
+ * have real geometry to judge).
+ *
+ * The mix mirrors the founder's traced seed collage proportionally:
+ * landscape-dominant with a few portraits and a square.
+ */
+export type DemoImage = {
+    aspect: number;
+    color: string;
+};
+export declare const DEMO_IMAGES: readonly DemoImage[];

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

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Demo fixture — the zero-setup collage.
+ *
+ * When no images are supplied the template packs this deterministic set of
+ * synthetic "photos" (aspect + tile color) instead of erroring. That gives a
+ * meaningful defaultProps render everywhere it matters: the Templates-page
+ * preview, the media-free CLI E2E case, and the `audit:layout-envelope`
+ * sweep (which renders defaultProps at 51 canvases and needs the contract to
+ * have real geometry to judge).
+ *
+ * The mix mirrors the founder's traced seed collage proportionally:
+ * landscape-dominant with a few portraits and a square.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEMO_IMAGES = void 0;
+exports.DEMO_IMAGES = [
+    { aspect: 1.5, color: "#2d4f67" },
+    { aspect: 1.33, color: "#5a3e5d" },
+    { aspect: 1.78, color: "#3e5c46" },
+    { aspect: 0.67, color: "#7a5230" },
+    { aspect: 1.5, color: "#37556e" },
+    { aspect: 1.25, color: "#6e4444" },
+    { aspect: 0.75, color: "#44606a" },
+    { aspect: 1.6, color: "#585a38" },
+    { aspect: 1.0, color: "#4f4668" },
+    { aspect: 1.45, color: "#2f5f58" },
+    { aspect: 0.56, color: "#6a3f52" },
+    { aspect: 1.33, color: "#3f5a2f" },
+];

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

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+import { type M0String } from "@m0saic/dsl";
+import type { MosaicSource } from "@m0saic/types";
+import type { PlacedSpan } from "./packer/types";
+/**
+ * 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).
+ */
+export declare function emitLatticeM0(placed: PlacedSpan[], cols: number, rows: number): M0String;
+export type EmitCollageOptions = {
+    placed: PlacedSpan[];
+    cols: number;
+    rows: number;
+    /** The render target (insets are computed exactly for this canvas). */
+    canvasW: number;
+    canvasH: number;
+    gutterXPx: number;
+    gutterYPx: number;
+    marginPx: number;
+    /**
+     * Source factory per image. Must NOT set `placement.inset` (the emitter
+     * owns it — same contract as `placeInsetPieces`); `fit` defaults to
+     * `"cover"` when the factory leaves placement unset.
+     */
+    sourceFor: (imageIndex: number) => MosaicSource;
+};
+export type EmitCollageResult = {
+    m0: M0String;
+    /** logicalIndex-aligned (the engine binds `sources[frame.logicalIndex]`). */
+    sources: MosaicSource[];
+    /** Per-SOURCE mapping back to the pack (same order as `sources`). */
+    cells: Array<{
+        imageIndex: number;
+        span: PlacedSpan;
+        /** The frame's stableKey (for doc.labels display entries). */
+        stableKey: string;
+        /** Exact intended painted rect (px) — what the contract asserts. */
+        target: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        };
+        /** The raw parsed cell the inset recovers the target from. */
+        raw: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        };
+    }>;
+    /** Planned unpainted fraction (gutters + margins + any filler area). */
+    expectedNullFrac: number;
+    /** Inset degradation report (0 on healthy lattices — see latticeCellInset). */
+    maxClampPx: number;
+    clampedEdges: number;
+};
+/**
+ * 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.
+ */
+export declare function emitCollageLayout(opts: EmitCollageOptions): EmitCollageResult;