@m0saic/templates 0.2.0

package/dist/m0saic/wireframe/base/v1/wireframe.js

@@ -0,0 +1,372 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Wireframe = void 0;
+exports.resolveTheme = resolveTheme;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+// ── Preset definitions ──────────────────────────────────────────────────────
+const PRESET_THEMES = {
+    "thumb-dark": {
+        backgroundColor: "#0f1116",
+        tileColor: "#141824",
+        tileColorAlt: "#101522",
+        borderColor: "#ffffff",
+        borderAlpha: 0.10,
+        borderWidthFrac: 0.0015,
+        rounding: { borderRadius: 0.04, cornerStyle: "rounded" },
+        useThumb: true,
+        useDebugText: false,
+    },
+    "thumb-light": {
+        backgroundColor: "#ffffff",
+        tileColor: "#f3f5f8",
+        tileColorAlt: "#eef1f5",
+        borderColor: "#000000",
+        borderAlpha: 0.12,
+        borderWidthFrac: 0.0015,
+        rounding: { borderRadius: 0.04, cornerStyle: "rounded" },
+        useThumb: true,
+        useDebugText: false,
+    },
+    "debug-contrast": {
+        backgroundColor: "#ffffff",
+        tileColor: "#ffffff",
+        tileColorAlt: "#fbfbfc",
+        borderColor: "#000000",
+        borderAlpha: 0.22,
+        borderWidthFrac: 0.0025,
+        rounding: { borderRadius: 0.015, cornerStyle: "rounded" },
+        useThumb: false,
+        useDebugText: true,
+    },
+    "heatmap-depth": {
+        backgroundColor: "#0f1116",
+        tileColor: "#141824",
+        tileColorAlt: "#141824",
+        borderColor: "#ffffff",
+        borderAlpha: 0.10,
+        borderWidthFrac: 0.0015,
+        rounding: { borderRadius: 0.04, cornerStyle: "rounded" },
+        heatmap: {
+            enabled: true,
+            shades: ["#141824", "#121b2a", "#0f2133", "#0b273d", "#072d47"],
+        },
+        useThumb: true,
+        useDebugText: false,
+    },
+    "grid-paper": {
+        backgroundColor: "#ffffff",
+        tileColor: "#f3f5f8",
+        tileColorAlt: "#eef1f5",
+        borderColor: "#000000",
+        borderAlpha: 0.12,
+        borderWidthFrac: 0.0015,
+        rounding: { borderRadius: 0.04, cornerStyle: "rounded" },
+        paperGrid: {
+            enabled: true,
+            stepFrac: 0.0625,
+            alpha: 0.08,
+        },
+        useThumb: true,
+        useDebugText: false,
+    },
+};
+// ── Theme resolver ──────────────────────────────────────────────────────────
+function resolveTheme(props) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    // Debug baseline — matches original behavior structurally
+    const resolved = {
+        backgroundColor: "#ffffff",
+        tileColor: "#ffffff",
+        tileColorAlt: "#ffffff",
+        borderColor: "#000000",
+        borderAlpha: 1.0,
+        borderWidthFrac: 0.005,
+        rounding: { borderRadius: 0, cornerStyle: "rounded" },
+        useThumb: false,
+        useDebugText: true,
+    };
+    // Layer 1: preset base
+    if (props.preset && props.preset in PRESET_THEMES) {
+        const p = PRESET_THEMES[props.preset];
+        Object.assign(resolved, p);
+        // Deep-merge rounding
+        if (p.rounding)
+            resolved.rounding = { ...resolved.rounding, ...p.rounding };
+    }
+    // Layer 2: explicit theme overrides
+    const t = props.theme;
+    if (t) {
+        if (t.backgroundColor != null)
+            resolved.backgroundColor = t.backgroundColor;
+        if (t.tileColor != null)
+            resolved.tileColor = t.tileColor;
+        if (t.tileColorAlt != null)
+            resolved.tileColorAlt = t.tileColorAlt;
+        if (t.borderColor != null)
+            resolved.borderColor = t.borderColor;
+        if (t.borderAlpha != null)
+            resolved.borderAlpha = t.borderAlpha;
+        if (t.borderWidthFrac != null)
+            resolved.borderWidthFrac = t.borderWidthFrac;
+        if (t.rounding)
+            resolved.rounding = { ...resolved.rounding, ...t.rounding };
+        if (t.dropShadow)
+            resolved.dropShadow = t.dropShadow;
+        if (t.heatmap) {
+            resolved.heatmap = {
+                enabled: (_c = (_a = t.heatmap.enabled) !== null && _a !== void 0 ? _a : (_b = resolved.heatmap) === null || _b === void 0 ? void 0 : _b.enabled) !== null && _c !== void 0 ? _c : false,
+                shades: (_f = (_d = t.heatmap.shades) !== null && _d !== void 0 ? _d : (_e = resolved.heatmap) === null || _e === void 0 ? void 0 : _e.shades) !== null && _f !== void 0 ? _f : [],
+            };
+        }
+        if (t.paperGrid) {
+            resolved.paperGrid = {
+                enabled: (_j = (_g = t.paperGrid.enabled) !== null && _g !== void 0 ? _g : (_h = resolved.paperGrid) === null || _h === void 0 ? void 0 : _h.enabled) !== null && _j !== void 0 ? _j : false,
+                stepFrac: (_m = (_k = t.paperGrid.stepFrac) !== null && _k !== void 0 ? _k : (_l = resolved.paperGrid) === null || _l === void 0 ? void 0 : _l.stepFrac) !== null && _m !== void 0 ? _m : 0.0625,
+                alpha: (_q = (_o = t.paperGrid.alpha) !== null && _o !== void 0 ? _o : (_p = resolved.paperGrid) === null || _p === void 0 ? void 0 : _p.alpha) !== null && _q !== void 0 ? _q : 0.08,
+            };
+        }
+    }
+    // Layer 3: `mode` decides thumb-vs-debug ONLY when no preset is chosen.
+    // A preset names its mode (thumb-* / heatmap-depth / grid-paper → thumb;
+    // debug-contrast → debug), and since gate 29 the base/v2 defaultProps
+    // carry an explicit `mode: "debug"` so the editor form reads the state
+    // it renders — a default value must never silently override a chosen
+    // preset (it would have turned every thumb preset into labelled debug
+    // tiles, incl. the Layout page's Dark/Light/Heatmap/Textbook styles).
+    if (!props.preset) {
+        if (props.mode === "thumb") {
+            resolved.useThumb = true;
+            resolved.useDebugText = false;
+        }
+        else if (props.mode === "debug") {
+            resolved.useThumb = false;
+            resolved.useDebugText = true;
+        }
+    }
+    return resolved;
+}
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    M0String: {
+        type: "m0",
+        required: true,
+        description: "m0 string to generate layout of",
+        meta: {
+            control: {
+                placeholder: "e.g., F, 2(1,1), 3[1,0,1]",
+            },
+            ui: {
+                label: "Mosaic Layout String",
+            },
+        },
+    },
+    labels: {
+        type: "string[]",
+        required: false,
+        description: "Optional labels for wireframe cells (1-based order). If omitted, dimensions and aspect ratio are rendered.",
+        meta: {
+            ui: {
+                label: "Cell Labels",
+            },
+        },
+    },
+    mode: {
+        type: "string",
+        required: false,
+        description: 'Render mode. "debug" (default) shows numbers/dims/AR. "thumb" shows clean tiles only.',
+        meta: {
+            constraints: { oneOf: ["debug", "thumb"] },
+            control: {
+                options: [
+                    { value: "debug", label: "Debug" },
+                    { value: "thumb", label: "Thumbnail" },
+                ],
+            },
+            ui: { label: "Mode" },
+        },
+    },
+    preset: {
+        type: "string",
+        required: false,
+        description: 'Named theme preset. Sets mode, colors, borders, and effects. Explicit mode/theme override preset values.',
+        meta: {
+            constraints: {
+                oneOf: ["none", "thumb-dark", "thumb-light", "debug-contrast", "heatmap-depth", "grid-paper"],
+            },
+            control: {
+                options: [
+                    { value: "none", label: "None (mode-driven)" },
+                    { value: "thumb-dark", label: "Thumb Dark" },
+                    { value: "thumb-light", label: "Thumb Light" },
+                    { value: "debug-contrast", label: "Debug Contrast" },
+                    { value: "heatmap-depth", label: "Heatmap Depth" },
+                    { value: "grid-paper", label: "Grid Paper" },
+                ],
+            },
+            ui: { label: "Preset" },
+        },
+    },
+    theme: {
+        type: "group",
+        required: false,
+        description: "Theme overrides applied on top of preset defaults. Colors, borders, rounding, shadows.",
+        meta: {
+            ui: {
+                label: "Theme",
+                collapsedByDefault: true,
+            },
+        },
+    },
+});
+// ── Adaptive debug-label density thresholds (px) ─────────────────────────────
+// Controls what auto-generated metadata is shown based on tile width.
+// Custom labels bypass these thresholds.
+const DEBUG_SHOW_DIMS_AND_AR = 220; // >= 220px: dimensions + AR
+const DEBUG_SHOW_DIMS_ONLY = 120; // >= 120px: dimensions only
+// < 120px:  index only (no center text)
+// ── Template ────────────────────────────────────────────────────────────────
+exports.Wireframe = {
+    id: (0, types_1.asTemplateId)("@m0saic/wireframe/base/v1"),
+    label: "Wireframe",
+    version: 1,
+    description: "Standard wireframe template for auto-gen docs",
+    capabilities: {
+        tier: "core"
+    },
+    // Superseded by v2, which renders the same wireframe in a single pass
+    // (each frame = one masked color tile; text + border as glyph outlines)
+    // instead of N nested cell documents with per-cell `drawtext`. Kept,
+    // fully callable, as the perf baseline and as living documentation of how
+    // the template evolved. Still requireable by id and via "Show deprecated".
+    deprecated: {
+        reason: "v1 renders N nested cell documents (one ffmpeg command + a drawtext pass per frame), so render time grows with the frame count. v2 collapses it to a single masked-tile pass.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/wireframe/base/v2"),
+        since: "2026-06-27",
+    },
+    tags: ["wireframe", "docs-only"],
+    outputHints: {
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 1000,
+        note: "Wireframe for documentation (layout visualization)",
+        format: {
+            kind: "image",
+            container: "png",
+            pixelFormat: "rgba",
+        }
+    },
+    propsSchema,
+    defaultProps: {
+        preset: "none",
+        mode: "debug",
+        M0String: "F",
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e;
+        // "none" is the visible unset state of the preset picker — identical to omitting it.
+        if (props.preset === "none") {
+            const { preset: _none, ...rest } = props;
+            props = rest;
+        }
+        const { M0String, labels } = props;
+        const hasTheming = !!props.preset || !!props.theme || props.mode === "thumb";
+        const resolved = hasTheming ? resolveTheme(props) : null;
+        const useThumb = (_a = resolved === null || resolved === void 0 ? void 0 : resolved.useThumb) !== null && _a !== void 0 ? _a : false;
+        const useDebugText = (_b = resolved === null || resolved === void 0 ? void 0 : resolved.useDebugText) !== null && _b !== void 0 ? _b : true;
+        const frames = (0, template_utils_1.parseMosaicFrames)(M0String, ctx);
+        const sources = [];
+        const children = {};
+        // Build cell theme only when theming is active
+        const baseCellTheme = resolved
+            ? {
+                tileBackgroundColor: resolved.tileColor,
+                borderColor: resolved.borderColor,
+                borderAlpha: resolved.borderAlpha,
+                borderWidthFrac: resolved.borderWidthFrac,
+                rounding: resolved.rounding,
+                dropShadow: resolved.dropShadow,
+            }
+            : undefined;
+        // Min text size: slightly higher for debug-contrast
+        const minTextSize = props.preset === "debug-contrast" ? 18 : 14;
+        let order = 0;
+        for (const frame of frames) {
+            if (frame.nullRender) {
+                continue;
+            }
+            order += 1;
+            // Text content
+            let textString = "";
+            let renderOrderNumberString = false;
+            if (useDebugText) {
+                const useCustomLabels = ((_c = labels === null || labels === void 0 ? void 0 : labels.length) !== null && _c !== void 0 ? _c : 0) > 0;
+                renderOrderNumberString = !useCustomLabels;
+                if (!useCustomLabels) {
+                    // Adaptive density: collapse metadata on narrow tiles
+                    const w = frame.width;
+                    if (w >= DEBUG_SHOW_DIMS_AND_AR) {
+                        const dimensionsString = `${frame.width}x${frame.height}`;
+                        const aspectRatio = frame.width / frame.height;
+                        textString = `${dimensionsString}\nAR: ${aspectRatio.toFixed(2)}`;
+                    }
+                    else if (w >= DEBUG_SHOW_DIMS_ONLY) {
+                        textString = `${frame.width}x${frame.height}`;
+                    }
+                    // else: w < DEBUG_SHOW_DIMS_ONLY → index only, no center text
+                }
+                else {
+                    textString = (_d = labels === null || labels === void 0 ? void 0 : labels[order - 1]) !== null && _d !== void 0 ? _d : "";
+                }
+            }
+            const smallerDim = Math.min(frame.width, frame.height);
+            const textSize = Math.max(minTextSize, Math.min(96, Math.round(smallerDim * 0.18)));
+            // Per-cell tile color
+            let tileCellTheme = baseCellTheme;
+            if (baseCellTheme && resolved) {
+                let tileBg = resolved.tileColor;
+                if (((_e = resolved.heatmap) === null || _e === void 0 ? void 0 : _e.enabled) && resolved.heatmap.shades.length > 0) {
+                    tileBg = resolved.heatmap.shades[(order - 1) % resolved.heatmap.shades.length];
+                }
+                else if (order % 2 === 0) {
+                    tileBg = resolved.tileColorAlt;
+                }
+                tileCellTheme = { ...baseCellTheme, tileBackgroundColor: tileBg };
+            }
+            const templateProps = {
+                orderString: String(order),
+                showOrderString: renderOrderNumberString,
+                text: textString,
+                textSize,
+                mode: useThumb ? "thumb" : "debug",
+                theme: tileCellTheme,
+            };
+            const childId = `cell-${frame.logicalIndex}`;
+            const childFile = await (0, template_utils_1.renderNestedTemplate)("@m0saic/wireframe/cell/v1", templateProps, ctx);
+            children[childId] = childFile;
+            sources.push({
+                type: "mosaic",
+                ref: childId
+            });
+        }
+        // TODO: templates should NOT set durationMs directly
+        const doc = {
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: (0, dsl_stdlib_1.toM0String)(M0String, "Wireframe"),
+            sources,
+            durationMs: 1000,
+            // `solidBackground` keeps the bg opaque on the rgba PNG output
+            // (see its docs for the engine bgFill branch that defaults
+            // alpha-output bgs to fully transparent).
+            ...((resolved === null || resolved === void 0 ? void 0 : resolved.backgroundColor) != null
+                ? { backgroundColor: (0, template_utils_1.solidBackground)(resolved.backgroundColor) }
+                : {}),
+            children,
+        };
+        return Promise.resolve(doc);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.Wireframe);

package/dist/m0saic/wireframe/base/v2/index.d.ts

@@ -0,0 +1,2 @@
+export { WireframeV2 } from "./wireframe";
+export { WireframeLabelContent, WireframeLabelOverflow, WireframeBackground, type WireframeLabelContentValue, type WireframeLabelOverflowValue, type WireframeBackgroundValue, } from "./wireframe";

package/dist/m0saic/wireframe/base/v2/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WireframeBackground = exports.WireframeLabelOverflow = exports.WireframeLabelContent = exports.WireframeV2 = void 0;
+var wireframe_1 = require("./wireframe");
+Object.defineProperty(exports, "WireframeV2", { enumerable: true, get: function () { return wireframe_1.WireframeV2; } });
+var wireframe_2 = require("./wireframe");
+Object.defineProperty(exports, "WireframeLabelContent", { enumerable: true, get: function () { return wireframe_2.WireframeLabelContent; } });
+Object.defineProperty(exports, "WireframeLabelOverflow", { enumerable: true, get: function () { return wireframe_2.WireframeLabelOverflow; } });
+Object.defineProperty(exports, "WireframeBackground", { enumerable: true, get: function () { return wireframe_2.WireframeBackground; } });

package/dist/m0saic/wireframe/base/v2/wireframe.d.ts

@@ -0,0 +1,166 @@
+import type { MosaicTemplate, MosaicPlacementFit } from "@m0saic/types";
+import { type WireframePreset, type WireframeTheme } from "../v1/wireframe";
+import type { M0Label } from "@m0saic/dsl-file-formats";
+/**
+ * Wireframe v2 — same look as v1, rendered in a single pass.
+ *
+ * # Why v2 exists (living documentation)
+ *
+ * v1 builds the wireframe out of N nested `@m0saic/wireframe/cell/v1`
+ * documents — one per frame. The engine renders each nested mosaic as its own
+ * ffmpeg command, and in **debug mode** each of those commands runs a
+ * `drawtext` filter (cold ffmpeg spawn + font init). For a 22-frame layout
+ * that's ~23 serial ffmpeg processes; render time grows linearly with the
+ * frame count (a high-fan-out layout is brutal).
+ *
+ * v2 collapses the whole thing into ONE flat document:
+ *   - Every m0 frame is a real source already, so each frame becomes a single
+ *     {@link makeColorTile} (lavfi `color=`) — these inline into one
+ *     filtergraph; no nested documents, no per-cell commands.
+ *   - In debug mode the per-cell text + border are baked into that tile's
+ *     **inline-mask** as glyph OUTLINES via {@link textToPath} — so a single
+ *     flat ink color shows through as the index / dimensions / label and the
+ *     frame outline. Zero `drawtext` passes. The masks for the whole document
+ *     rasterize in one batched child process.
+ *
+ * Net effect: the render is one ffmpeg command + one mask raster, flat in the
+ * frame count, instead of N serial spawns. Glyphs are vector outlines from a
+ * bundled font, so output is deterministic across platforms (no fontconfig).
+ */
+/** What to show in a tile. Cumulative: each value includes the ones above it. */
+export declare enum WireframeLabelContent {
+    /** Draw nothing inside the tile (just the frame outline). */
+    None = "none",
+    /** The tile's 1-based number only. */
+    Number = "number",
+    /** Number + pixel dimensions (W × H). */
+    Dimensions = "dimensions",
+    /** Number + dimensions + aspect ratio (e.g. `16:9 · 1.78`). */
+    AspectRatio = "aspect"
+}
+/** How to back off when {@link WireframeLabelContent} won't fit a tile. */
+export declare enum WireframeLabelOverflow {
+    /** All-or-nothing — show the full requested content, or leave the tile blank. */
+    Hide = "hide",
+    /** Drop the richest line at a time (aspect → dimensions → number) until what
+     *  remains fits. Small tiles still show at least their number when it fits. */
+    Degrade = "degrade",
+    /** Show the full content if it fits, otherwise fall straight back to just the
+     *  number (skipping the in-between levels) — the smallest always-useful label. */
+    NumberFloor = "number-floor"
+}
+/** Canvas backing for the wireframe (debug mode). */
+export declare enum WireframeBackground {
+    /** No fill — the canvas and every null / empty region stay transparent, so
+     *  the wireframe is just lines + labels and composites over anything. */
+    Transparent = "transparent",
+    /** Bake an opaque white fill behind everything — null / empty regions read
+     *  as solid white instead of transparent. */
+    White = "white"
+}
+/**
+ * Dev diagram knob (gate 29, founder). The final composite is every overlay
+ * LAYER stacked; "show" explodes it — an emit:multi pipeline with ONE still
+ * per overlay depth, each printing that depth's cells plus its `-` null
+ * holes (which the engine never paints) as dashed, muted cells.
+ */
+export declare enum WireframeNullFrames {
+    /** Normal single composite, null tiles skipped (the shipped default). */
+    Hide = "hide",
+    /** Layer explode: one PNG per overlay depth, null tiles drawn dashed + muted. */
+    Show = "show"
+}
+/** String-value unions accepted by the props (what the schema validates). */
+export type WireframeLabelContentValue = `${WireframeLabelContent}`;
+export type WireframeNullFramesValue = `${WireframeNullFrames}`;
+/** Text drawn inside a hole cell: the word `null`, or the m0 token `-`. */
+export type WireframeNullLabelValue = "null" | "-";
+/** What an UNLABELED cell shows once some cells carry custom labels. */
+export declare enum WireframeUnlabeledCells {
+    /** Keep the debug marks (number / dims / aspect) — label a few frames, the
+     *  rest still read their geometry. The default. */
+    Marks = "marks",
+    /** Leave it blank — labels are the only text on the board (the pre-gate-30
+     *  behaviour; opt-in). */
+    Empty = "empty"
+}
+export type WireframeUnlabeledCellsValue = `${WireframeUnlabeledCells}`;
+export type WireframeLabelOverflowValue = `${WireframeLabelOverflow}`;
+export type WireframeBackgroundValue = `${WireframeBackground}`;
+type WireframeSchemaProps = {
+    M0String: string;
+    labels?: string[];
+    /**
+     * Per-cell labels keyed by REAL stableKey (same shape as `M0cFile.labels`:
+     * `Record<StableKey, {text, color?}>`). Resolved to the positional `labels`
+     * array internally, so callers with a `.m0c` labels map (e.g. post-mortem's
+     * candidate geometry) can label cells by stable identity instead of fragile
+     * source order. Overrides positional `labels` when supplied.
+     */
+    labelsByStableKey?: Record<string, M0Label>;
+    /**
+     * Per-cell (1-based order, parallel to {@link WireframeSchemaProps.labels})
+     * body fill colour. When set, cell N's BODY is painted `cellColors[N-1]` at
+     * full opacity BENEATH the masked border/label ink — so the label still reads
+     * on top of the fill. An empty-string entry leaves that cell's body
+     * transparent (skip). The perf heatmap uses this to colour cells by render
+     * cost while keeping the time label legible. Debug mode only.
+     */
+    cellColors?: string[];
+    /** "debug" (default) renders numbers/dims/AR. "thumb" renders clean tiles. */
+    mode?: "debug" | "thumb";
+    /**
+     * Most detail to show per tile (cumulative ladder). Default "dimensions"
+     * (number + W × H); "aspect" is opt-in. A cell with a custom label shows the
+     * label instead; unlabeled cells keep this ladder (see `unlabeledCells`).
+     */
+    labelContent?: WireframeLabelContentValue;
+    /** How to back off when `labelContent` won't fit a tile. Default "degrade". */
+    labelOverflow?: WireframeLabelOverflowValue;
+    /**
+     * What a cell WITHOUT a custom label shows once `labels` are in play:
+     * "marks" (default — its number / dims / aspect per `labelContent`) or
+     * "empty" (blank; labels are the only text on the board).
+     */
+    unlabeledCells?: WireframeUnlabeledCellsValue;
+    /**
+     * Canvas backing (debug mode). "white" (default) bakes an opaque white fill
+     * behind everything; "transparent" leaves the canvas and null regions empty
+     * so the wireframe composites over anything (trace workflows).
+     * Ignored when a theme/preset supplies its own background.
+     */
+    background?: WireframeBackgroundValue;
+    /**
+     * Dev diagram knob: "show" returns an emit:multi PIPELINE — one still per
+     * overlay depth, each printing that depth's cells plus its `-` holes as
+     * dashed, muted cells labelled `null` + size. Default "hide" renders the
+     * normal single composite (byte-identical output).
+     */
+    nullFrames?: WireframeNullFramesValue;
+    /** Text inside a hole cell when null frames show: `null` (default) or the m0 token `-`. */
+    nullLabel?: WireframeNullLabelValue;
+    /**
+     * Translucent rect fill (debug mode), 0..1. A body wash in the tile's ink
+     * color drawn beneath the opaque border/labels — so the rects read as
+     * filled regions when composited over a background image. 0 (default) keeps
+     * the body transparent (lines/labels only). Ignored in thumb/themed modes.
+     */
+    fill?: number;
+    /**
+     * Image baked BENEATH the wireframe — the lines/labels render on top of it.
+     * A filesystem path OR an inline base64 `data:` URI (self-contained docs).
+     * The classic use is dropping a reference/source screenshot here and tracing
+     * the layout over it. Sets the document's `backgroundImage`.
+     */
+    backgroundImage?: string;
+    /** Background-image opacity, 0..1. Default 1 (fully opaque). */
+    backgroundImageOpacity?: number;
+    /** Background-image fit: "cover" (default, fill+crop) or "contain" (letterbox). */
+    backgroundImageFit?: MosaicPlacementFit;
+    /** Named theme preset. Overrides mode and theme defaults. */
+    preset?: WireframePreset | "none";
+    /** Theme overrides applied on top of preset defaults. */
+    theme?: WireframeTheme;
+};
+export declare const WireframeV2: MosaicTemplate<WireframeSchemaProps>;
+export {};