@m0saic/templates 0.2.0

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

@@ -0,0 +1,1181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WireframeV2 = exports.WireframeUnlabeledCells = exports.WireframeNullFrames = exports.WireframeBackground = exports.WireframeLabelOverflow = exports.WireframeLabelContent = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const wireframe_1 = require("../v1/wireframe");
+const dsl_1 = require("@m0saic/dsl");
+const paperGrid_1 = require("../../utils/paperGrid");
+/**
+ * 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).
+ */
+// ── Label content / overflow API (mirrors the editor's view-frame) ──
+//
+// Two orthogonal knobs, both string enums so they read nicely in the UI:
+//
+//   1. labelContent — the *most* you want to show in a tile, as a cumulative
+//      ladder. Each level includes the ones below it:
+//        none → number → dimensions (number + W×H) → aspect (+ ratio).
+//   2. labelOverflow — what to do when the requested content can't fit a tile.
+//      Tiles in a real layout vary wildly in size, so a fixed request can't
+//      always be honoured. This says how to back off (see the enum docs).
+//
+// The fit math mirrors `apps/mosaic/web/src/components/viewframe/FrameInfo.tsx`
+// (the editor's per-tile annotation), so the wireframe export looks like what
+// you see while editing: a centered vertical stack — number (primary), W×H
+// (secondary), ratio (tertiary) — that grows the font when fewer items show.
+/** What to show in a tile. Cumulative: each value includes the ones above it. */
+var WireframeLabelContent;
+(function (WireframeLabelContent) {
+    /** Draw nothing inside the tile (just the frame outline). */
+    WireframeLabelContent["None"] = "none";
+    /** The tile's 1-based number only. */
+    WireframeLabelContent["Number"] = "number";
+    /** Number + pixel dimensions (W × H). */
+    WireframeLabelContent["Dimensions"] = "dimensions";
+    /** Number + dimensions + aspect ratio (e.g. `16:9 · 1.78`). */
+    WireframeLabelContent["AspectRatio"] = "aspect";
+})(WireframeLabelContent || (exports.WireframeLabelContent = WireframeLabelContent = {}));
+/** How to back off when {@link WireframeLabelContent} won't fit a tile. */
+var WireframeLabelOverflow;
+(function (WireframeLabelOverflow) {
+    /** All-or-nothing — show the full requested content, or leave the tile blank. */
+    WireframeLabelOverflow["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. */
+    WireframeLabelOverflow["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. */
+    WireframeLabelOverflow["NumberFloor"] = "number-floor";
+})(WireframeLabelOverflow || (exports.WireframeLabelOverflow = WireframeLabelOverflow = {}));
+/** Canvas backing for the wireframe (debug mode). */
+var WireframeBackground;
+(function (WireframeBackground) {
+    /** No fill — the canvas and every null / empty region stay transparent, so
+     *  the wireframe is just lines + labels and composites over anything. */
+    WireframeBackground["Transparent"] = "transparent";
+    /** Bake an opaque white fill behind everything — null / empty regions read
+     *  as solid white instead of transparent. */
+    WireframeBackground["White"] = "white";
+})(WireframeBackground || (exports.WireframeBackground = WireframeBackground = {}));
+/**
+ * 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.
+ */
+var WireframeNullFrames;
+(function (WireframeNullFrames) {
+    /** Normal single composite, null tiles skipped (the shipped default). */
+    WireframeNullFrames["Hide"] = "hide";
+    /** Layer explode: one PNG per overlay depth, null tiles drawn dashed + muted. */
+    WireframeNullFrames["Show"] = "show";
+})(WireframeNullFrames || (exports.WireframeNullFrames = WireframeNullFrames = {}));
+/** What an UNLABELED cell shows once some cells carry custom labels. */
+var WireframeUnlabeledCells;
+(function (WireframeUnlabeledCells) {
+    /** Keep the debug marks (number / dims / aspect) — label a few frames, the
+     *  rest still read their geometry. The default. */
+    WireframeUnlabeledCells["Marks"] = "marks";
+    /** Leave it blank — labels are the only text on the board (the pre-gate-30
+     *  behaviour; opt-in). */
+    WireframeUnlabeledCells["Empty"] = "empty";
+})(WireframeUnlabeledCells || (exports.WireframeUnlabeledCells = WireframeUnlabeledCells = {}));
+const DEFAULT_UNLABELED_CELLS = "marks";
+/** Per-cell label decision shared by the composite and the layer-explode
+ *  paths: a non-blank custom label wins; otherwise the cell falls back to its
+ *  debug marks (`undefined`) unless `unlabeledCells: "empty"` asks for a blank
+ *  cell (`""`) while ANY custom label is in play. */
+function cellLabelFor(labels, order, unlabeledCells) {
+    var _a;
+    const custom = labels === null || labels === void 0 ? void 0 : labels[order - 1];
+    if (custom && custom.trim())
+        return custom;
+    const anyCustom = ((_a = labels === null || labels === void 0 ? void 0 : labels.length) !== null && _a !== void 0 ? _a : 0) > 0;
+    return anyCustom && unlabeledCells === "empty" ? "" : undefined;
+}
+// Default matches the wireframe's historical behaviour — number + dimensions,
+// degrading to just the number on tiles too small for both. Aspect ratio is
+// opt-in via `labelContent: "aspect"`.
+const DEFAULT_LABEL_CONTENT = "dimensions";
+const DEFAULT_LABEL_OVERFLOW = "degrade";
+// White by default (founder ruling, gate 29 take 4: "transparent bg is poor
+// when the background is also black" — black ink on the editor's dark
+// stage read as an empty canvas). Opt into a transparent canvas — lines +
+// labels that composite over anything, null regions empty — with
+// `background: "transparent"` (the Layout page's trace styles do).
+const DEFAULT_BACKGROUND = "white";
+const DEFAULT_NULL_FRAMES = "hide";
+const DEFAULT_NULL_LABEL = "null";
+// Null-frame treatment: muted ink + a dashed ring so a hole never reads as a
+// painted cell. Dash/gap scale with the pen so the rhythm holds at any size.
+const NULL_FRAME_ALPHA = 0.55;
+// Each layer still is a 1s image step (emit:multi needs a step length).
+const LAYER_STILL_MS = 1000;
+const NULL_DASH_PER_PEN = 6;
+// Default layout: a basic 2×2 grid (founder ruling, gate 29 take 3 — a dev
+// template gets no cover; the default face is a real grid, not a bare cell).
+const DEFAULT_LAYOUT = "2(2[1,1],2[1,1])";
+// Sub-readable glyphs are noise in a baked export — a candidate that would draw
+// any line below this px size is treated as "doesn't fit" and backs off.
+const MIN_LEGIBLE_PX = 9;
+// Debug frame outlines use ONE uniform pen width across every tile (a wireframe
+// wants a single line weight, not a border that thins out on smaller tiles).
+// The weight is a fraction of the CANVAS's smaller side, so it scales with
+// render resolution but stays identical from tile to tile. 0.0015 ≈ 3px at
+// 2160p / 2px at 1080p, matching the thumb presets' line weight.
+const DEBUG_BORDER_FRAC = 0.0015;
+// resolveTheme's debug *baseline* borderWidthFrac (0.005) is a legacy
+// tile-relative value — far too heavy read canvas-relative — so we ignore it and
+// only honour preset/explicit fracs at or below this sane canvas-relative cap.
+const MAX_CANVAS_BORDER_FRAC = 0.003;
+// FrameInfo line-size ratios (kept identical so the proportions match the
+// editor): the number is the primary, dimensions ride at 65%, aspect at 55%,
+// with a gap of 25% of the number size between stacked lines.
+const SECONDARY_RATIO = 0.65; // dimensions size = numPx * this
+const TERTIARY_RATIO = 0.55; // aspect size     = numPx * this
+const STACK_GAP_RATIO = 0.25; // gap between lines = numPx * this
+// Fraction of tile HEIGHT the stack aims to fill. Unlike FrameInfo (a subtle
+// DOM overlay sized off a screen-space constant), a baked wireframe wants the
+// label to read at a glance, so we size to fill the tile and then shrink to fit
+// width. Fewer requested lines ⇒ the number divides the fill among fewer items
+// ⇒ it grows — the same "boost when less is shown" behaviour FrameInfo gets
+// from its numBoost constant.
+const STACK_FILL_FRAC = 0.6;
+// Absolute ceiling so huge canvases don't produce monster glyphs.
+const MAX_NUM_PX = 240;
+function gcd(a, b) {
+    a = Math.abs(Math.round(a));
+    b = Math.abs(Math.round(b));
+    while (b) {
+        [a, b] = [b, a % b];
+    }
+    return a || 1;
+}
+function simplifyRatio(w, h) {
+    const g = gcd(w, h);
+    return [Math.round(w) / g, Math.round(h) / g];
+}
+function fmtDec(n) {
+    return parseFloat(n.toFixed(2)).toString();
+}
+/** Numeric rung for a content level (0 = none). Higher = more detail. */
+function contentLevel(c) {
+    return c === "aspect" ? 3 : c === "dimensions" ? 2 : c === "number" ? 1 : 0;
+}
+/** The lines a given level wants, richest item last. `order` is 1-based. */
+function linesForLevel(level, order, cellW, cellH) {
+    const out = [];
+    if (level >= 1)
+        out.push({ key: "num", text: String(order) });
+    if (level >= 2)
+        out.push({ key: "dims", text: `${cellW} × ${cellH}` });
+    if (level >= 3) {
+        const [rw, rh] = simplifyRatio(cellW, cellH);
+        out.push({ key: "aspect", text: `${rw}:${rh} · ${fmtDec(cellW / cellH)}` });
+    }
+    return out;
+}
+/** Ladder of content levels to try, richest first, per overflow policy. */
+function candidateLevels(target, overflow) {
+    if (target <= 0)
+        return [];
+    if (overflow === "hide")
+        return [target];
+    if (overflow === "number-floor")
+        return target > 1 ? [target, 1] : [1];
+    // degrade: every rung from target down to 1
+    const out = [];
+    for (let l = target; l >= 1; l--)
+        out.push(l);
+    return out;
+}
+/**
+ * Try to fit `items` in a `cellW`×`cellH` tile using FrameInfo's sizing math.
+ * Returns sized lines (+ stacking gap/pad) if every line is legible and the
+ * stack fits both axes, else `null` so the caller can back off to fewer lines.
+ */
+function fitLines(items, cellW, cellH, minTextSize) {
+    const count = items.length;
+    if (count === 0)
+        return null;
+    const minSide = Math.min(cellW, cellH);
+    const pad = Math.max(4, Math.round(minSide * 0.04));
+    const availW = cellW - 2 * pad;
+    if (availW <= 0)
+        return null;
+    const relOf = (key) => key === "num" ? 1.0 : key === "dims" ? SECONDARY_RATIO : TERTIARY_RATIO;
+    // 1) Size to fill the tile height. The number divides the fill budget among
+    //    all lines (weighted) + the inter-line gaps, so fewer lines ⇒ bigger
+    //    number (the boost effect).
+    const sumRel = items.reduce((a, it) => a + relOf(it.key), 0);
+    const gapUnits = STACK_GAP_RATIO * (count - 1);
+    let numPx = Math.min(MAX_NUM_PX, (cellH * STACK_FILL_FRAC) / (sumRel + gapUnits));
+    // 2) Shrink to fit width — scale the whole stack down by the tightest line.
+    let scale = 1;
+    for (const it of items) {
+        const w = (0, template_utils_1.measureText)(it.text, { fontSize: numPx * relOf(it.key) }).width;
+        if (w > availW)
+            scale = Math.min(scale, availW / w);
+    }
+    numPx *= scale;
+    // 3) Legibility floors — primary clears minTextSize, nothing is sub-legible.
+    //    Failing here backs the caller off to fewer (hence larger) lines.
+    if (numPx < minTextSize)
+        return null;
+    const sized = items.map((it) => ({ ...it, size: numPx * relOf(it.key) }));
+    if (sized.some((s) => s.size < MIN_LEGIBLE_PX))
+        return null;
+    return { lines: sized, gap: numPx * STACK_GAP_RATIO, pad };
+}
+/** Resolve the label that fits this tile, walking the overflow ladder. */
+function resolveLabel(content, overflow, order, cellW, cellH, minTextSize) {
+    const target = contentLevel(content);
+    for (const level of candidateLevels(target, overflow)) {
+        const fitted = fitLines(linesForLevel(level, order, cellW, cellH), cellW, cellH, minTextSize);
+        if (fitted)
+            return fitted;
+    }
+    return null;
+}
+/**
+ * The per-LINE rects (in the cell's local coords) the label this cell WOULD draw
+ * actually inks — each line centered exactly as {@link buildDebugCellMaskPath}
+ * lays it out. Testing these (not their union bounding box) against higher-z
+ * tiles is what makes a small corner overlay leave a big hero label alone: the
+ * dead space between the centered number and the wide dimensions line isn't part
+ * of any line rect, so only a tile that truly covers a glyph row suppresses it.
+ * Returns [] when the cell draws no label.
+ */
+function labelLineRects(opts) {
+    const { cellW, cellH, order, label, content, overflow, minTextSize } = opts;
+    const smallerDim = Math.min(cellW, cellH);
+    const pad = Math.max(4, Math.round(smallerDim * 0.04));
+    if (label != null) {
+        const t = label.trim();
+        if (!t)
+            return [];
+        const availW = Math.max(1, cellW - 2 * pad);
+        let size = clampSize(minTextSize, smallerDim * 0.16, 72);
+        let w = (0, template_utils_1.measureText)(t, { fontSize: size }).width;
+        if (w > availW) {
+            size = Math.max(MIN_LEGIBLE_PX, Math.floor((size * availW) / w));
+            w = (0, template_utils_1.measureText)(t, { fontSize: size }).width;
+        }
+        // Custom label is vertically centered (vAlign "middle").
+        return [{ x: (cellW - w) / 2, y: (cellH - size) / 2, w, h: size }];
+    }
+    const fitted = resolveLabel(content, overflow, order, cellW, cellH, minTextSize);
+    if (!fitted)
+        return [];
+    let totalH = 0;
+    fitted.lines.forEach((l, i) => {
+        totalH += l.size;
+        if (i > 0)
+            totalH += fitted.gap;
+    });
+    const rects = [];
+    let cursor = (cellH - totalH) / 2;
+    for (const line of fitted.lines) {
+        const w = (0, template_utils_1.measureText)(line.text, { fontSize: line.size }).width;
+        rects.push({ x: (cellW - w) / 2, y: cursor, w, h: line.size });
+        cursor += line.size + fitted.gap;
+    }
+    return rects;
+}
+/** Axis-aligned rect overlap (strict: edge-touching is not an overlap). */
+function rectsIntersect(ax, ay, aw, ah, bx, by, bw, bh) {
+    return ax < bx + bw && bx < ax + aw && ay < by + bh && by < ay + ah;
+}
+// ── Debug-mode geometry helpers ──
+/**
+ * SVG path for a rectangular border ring (frame outline) of stroke width `t`
+ * inside a `w`×`h` cell. Outer contour clockwise + inner counter-clockwise so
+ * the non-zero fill rule punches the center out, leaving just the border. Baked
+ * into the cell's inline-mask so the outline is the SAME ink as the text — one
+ * masked color source draws both.
+ */
+function rectRingPath(w, h, t) {
+    const ti = Math.min(t, w / 2, h / 2);
+    const outer = `M0 0 L${w} 0 L${w} ${h} L0 ${h} Z`;
+    const inner = `M${ti} ${ti} L${ti} ${h - ti} L${w - ti} ${h - ti} L${w - ti} ${ti} Z`;
+    return `${outer} ${inner}`;
+}
+/**
+ * Dashed rectangular ring of pen `t` inside a `w`×`h` cell: `dash`-long
+ * strokes separated by `gap` along each edge (corners always inked so the
+ * rectangle reads). Same ink path as the solid ring — one masked tile.
+ */
+function dashedRingPath(w, h, t, dash, gap) {
+    const ti = Math.max(1, Math.min(t, w / 2, h / 2));
+    const step = Math.max(2, dash + gap);
+    const parts = [];
+    // top + bottom edges
+    for (let x = 0; x < w; x += step) {
+        const x1 = Math.min(w, x + dash);
+        parts.push(`M${x} 0 L${x1} 0 L${x1} ${ti} L${x} ${ti} Z`);
+        parts.push(`M${x} ${h - ti} L${x1} ${h - ti} L${x1} ${h} L${x} ${h} Z`);
+    }
+    // left + right edges
+    for (let y = 0; y < h; y += step) {
+        const y1 = Math.min(h, y + dash);
+        parts.push(`M0 ${y} L${ti} ${y} L${ti} ${y1} L0 ${y1} Z`);
+        parts.push(`M${w - ti} ${y} L${w} ${y} L${w} ${y1} L${w - ti} ${y1} Z`);
+    }
+    return parts.join(" ");
+}
+/**
+ * ONE null tile's inline-mask path: a dashed ring + a centered `null` /
+ * `W × H` stack (the same FrameInfo sizing math as painted cells, degrading
+ * to just `null` on small holes). Drawn muted via the tile's overlay alpha.
+ */
+function buildNullCellMaskPath(opts) {
+    var _a, _b;
+    const { cellW, cellH, borderPx, minTextSize, ringOnly } = opts;
+    const nullText = (_a = opts.label) !== null && _a !== void 0 ? _a : DEFAULT_NULL_LABEL;
+    const dash = Math.max(6, borderPx * NULL_DASH_PER_PEN);
+    const parts = [dashedRingPath(cellW, cellH, borderPx, dash, dash)];
+    if (ringOnly)
+        return parts.join(" ");
+    const canvas = { width: cellW, height: cellH };
+    const items = [
+        { key: "num", text: nullText },
+        { key: "dims", text: `${cellW} × ${cellH}` },
+    ];
+    const fitted = (_b = fitLines(items, cellW, cellH, minTextSize)) !== null && _b !== void 0 ? _b : fitLines(items.slice(0, 1), cellW, cellH, minTextSize);
+    if (fitted) {
+        let totalH = 0;
+        fitted.lines.forEach((l, i) => {
+            totalH += l.size;
+            if (i > 0)
+                totalH += fitted.gap;
+        });
+        let cursor = (cellH - totalH) / 2;
+        for (const line of fitted.lines) {
+            parts.push((0, template_utils_1.textToPath)(line.text, { fontSize: line.size, hAlign: "center", vAlign: "top", padding: { x: fitted.pad, y: cursor } }, canvas));
+            cursor += line.size + fitted.gap;
+        }
+    }
+    return parts.filter(Boolean).join(" ");
+}
+/** Alpha-0 tile: occupies a leaf slot, paints nothing (a leaf on another layer). */
+function ghostTile(ink) {
+    return (0, template_utils_1.makeColorTile)(ink, { overlay: { alpha: "0" } });
+}
+/** The dashed, muted `null` + size cell for one hole. */
+function nullTile(opts) {
+    return (0, template_utils_1.makeColorTile)(opts.ink, {
+        mask: {
+            kind: "inline-mask",
+            localPath: buildNullCellMaskPath(opts),
+            bounds: { x: 0, y: 0, width: opts.cellW, height: opts.cellH },
+        },
+        overlay: { alpha: String(NULL_FRAME_ALPHA) },
+    });
+}
+/**
+ * One painted cell — thumb: a flat colour tile with rounding/stroke effects;
+ * debug: one ink tile masked to border ring + label glyphs. Shared by the
+ * single composite and the layer explode so a cell looks identical in both.
+ */
+function paintedTile(opts) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const { cellW, cellH, order, useThumb, resolved } = opts;
+    if (useThumb) {
+        let tileColor = (_a = resolved === null || resolved === void 0 ? void 0 : resolved.tileColor) !== null && _a !== void 0 ? _a : "#141824";
+        if (((_b = resolved === null || resolved === void 0 ? void 0 : resolved.heatmap) === null || _b === void 0 ? void 0 : _b.enabled) && resolved.heatmap.shades.length > 0) {
+            tileColor = resolved.heatmap.shades[(order - 1) % resolved.heatmap.shades.length];
+        }
+        else if (resolved && order % 2 === 0) {
+            tileColor = resolved.tileColorAlt;
+        }
+        const effects = {
+            rounding: (_c = resolved === null || resolved === void 0 ? void 0 : resolved.rounding) !== null && _c !== void 0 ? _c : { borderRadius: 0.04, cornerStyle: "rounded" },
+            stroke: {
+                width: (_d = resolved === null || resolved === void 0 ? void 0 : resolved.borderWidthFrac) !== null && _d !== void 0 ? _d : 0.0015,
+                color: ((_e = resolved === null || resolved === void 0 ? void 0 : resolved.borderColor) !== null && _e !== void 0 ? _e : "#ffffff"),
+                alpha: (_f = resolved === null || resolved === void 0 ? void 0 : resolved.borderAlpha) !== null && _f !== void 0 ? _f : 0.1,
+                position: "inner",
+            },
+        };
+        if (resolved === null || resolved === void 0 ? void 0 : resolved.dropShadow)
+            effects.dropShadow = resolved.dropShadow;
+        return (0, template_utils_1.makeColorTile)(tileColor, { effects });
+    }
+    const ink = ((_g = resolved === null || resolved === void 0 ? void 0 : resolved.borderColor) !== null && _g !== void 0 ? _g : "#000000");
+    const localPath = buildDebugCellMaskPath({
+        cellW,
+        cellH,
+        order,
+        label: opts.label,
+        content: opts.labelContent,
+        overflow: opts.labelOverflow,
+        borderPx: opts.borderPx,
+        minTextSize: opts.minTextSize,
+        suppressLabel: opts.suppressLabel,
+    });
+    return (0, template_utils_1.makeColorTile)(ink, {
+        mask: {
+            kind: "inline-mask",
+            localPath,
+            bounds: { x: 0, y: 0, width: cellW, height: cellH },
+            ...(opts.fillAlpha > 0 ? { matte: opts.fillAlpha } : {}),
+        },
+    });
+}
+/**
+ * LAYER EXPLODE (dev diagram, gate 29): the composite is every overlay depth
+ * stacked, so emit ONE still per depth. Every still carries the SAME m0
+ * geometry (so a cell keeps its number and position across the set) — leaves
+ * at the requested depth paint (cells as usual, `-` holes as dashed muted
+ * `null` cells, their `-` swapped to `1` positionally via the parse span so
+ * the engine binds a source), painted leaves at other depths ride as alpha-0
+ * ghosts, and other depths' holes stay `-` (no source). Returns null when
+ * the full parse fails (caller falls back to the composite).
+ */
+function buildLayerExplode(args) {
+    var _a, _b, _c, _d, _e, _f;
+    const canon = String((0, dsl_1.toCanonicalM0String)(args.m0));
+    const full = (0, dsl_1.parseM0StringComplete)(canon, args.canvasW, args.canvasH);
+    if (!full.ok)
+        return null;
+    const nodes = ((_b = (_a = full.ir) === null || _a === void 0 ? void 0 : _a.editorFrames) !== null && _b !== void 0 ? _b : [])
+        .filter((n) => n.kind === "frame" || n.kind === "null")
+        .slice()
+        .sort((a, b) => { var _a, _b, _c, _d; return ((_b = (_a = a.meta.span) === null || _a === void 0 ? void 0 : _a.start) !== null && _b !== void 0 ? _b : 0) - ((_d = (_c = b.meta.span) === null || _c === void 0 ? void 0 : _c.start) !== null && _d !== void 0 ? _d : 0); });
+    if (nodes.length === 0)
+        return null;
+    // A hole must be addressable in the canonical string to become a slot.
+    if (nodes.some((n) => n.kind === "null" && (n.meta.span == null || canon[n.meta.span.start] !== "-"))) {
+        return null;
+    }
+    const maxDepth = nodes.reduce((m, n) => Math.max(m, n.overlayDepth), 0);
+    const ink = ((_d = (_c = args.resolved) === null || _c === void 0 ? void 0 : _c.borderColor) !== null && _d !== void 0 ? _d : "#000000");
+    const steps = [];
+    for (let depth = 0; depth <= maxDepth; depth++) {
+        const chars = canon.split("");
+        const sources = [];
+        let order = 0;
+        for (const n of nodes) {
+            if (n.kind === "frame") {
+                order += 1; // composite numbering — identical on every still
+                if (n.overlayDepth !== depth) {
+                    sources.push(ghostTile(ink));
+                    continue;
+                }
+                sources.push(paintedTile({
+                    cellW: n.width,
+                    cellH: n.height,
+                    order,
+                    useThumb: args.useThumb,
+                    resolved: args.resolved,
+                    label: cellLabelFor(args.labels, order, args.unlabeledCells),
+                    labelContent: args.labelContent,
+                    labelOverflow: args.labelOverflow,
+                    borderPx: args.borderPx,
+                    minTextSize: args.minTextSize,
+                    fillAlpha: args.fillAlpha,
+                    // one depth per still — nothing on this still covers a label
+                    suppressLabel: false,
+                }));
+            }
+            else if (n.overlayDepth === depth && n.meta.span) {
+                chars[n.meta.span.start] = "1";
+                sources.push(nullTile({
+                    ink,
+                    cellW: n.width,
+                    cellH: n.height,
+                    borderPx: args.borderPx,
+                    minTextSize: args.minTextSize,
+                    ringOnly: args.useThumb,
+                    label: args.nullLabel,
+                }));
+            }
+        }
+        let layerM0 = chars.join("");
+        if (depth === 0 && ((_f = (_e = args.resolved) === null || _e === void 0 ? void 0 : _e.paperGrid) === null || _f === void 0 ? void 0 : _f.enabled)) {
+            sources.push((0, paperGrid_1.makePaperGridSource)({
+                width: args.canvasW,
+                height: args.canvasH,
+                ink,
+                stepFrac: args.resolved.paperGrid.stepFrac,
+                alpha: args.resolved.paperGrid.alpha,
+            }));
+            layerM0 = (0, paperGrid_1.appendTopOverlay)(layerM0);
+        }
+        const file = {
+            kind: "mosaic_document",
+            version: 1,
+            assets: args.assets,
+            m0: (0, dsl_stdlib_1.toM0String)(layerM0, `Wireframe layer ${depth}`),
+            sources,
+            size: { width: args.canvasW, height: args.canvasH },
+            fps: args.fps,
+            durationMs: LAYER_STILL_MS,
+            format: { kind: "image", container: "png", pixelFormat: "rgba" },
+            ...(args.bg != null ? { backgroundColor: (0, template_utils_1.solidBackground)(args.bg) } : {}),
+            ...(args.backgroundImage ? { backgroundImage: args.backgroundImage } : {}),
+        };
+        steps.push({
+            name: `layer-${depth}`,
+            label: `Layer ${depth} of ${maxDepth + 1}`,
+            durationMs: LAYER_STILL_MS,
+            file,
+        });
+    }
+    return { kind: "mosaic_pipeline", version: 1, emit: "multi", steps };
+}
+function clampSize(min, value, max) {
+    return Math.max(min, Math.min(max, Math.round(value)));
+}
+/**
+ * Build ONE cell's inline-mask path — border ring + the centered label stack —
+ * all as glyph/vector outlines authored in the cell's local pixel box. The
+ * consuming `makeColorTile` paints a single flat ink color through this mask.
+ *
+ * A custom `label` (from the `labels` prop) bypasses the content/overflow ladder
+ * and is drawn centered, shrunk to fit the tile width. Otherwise the label is
+ * resolved from `content` + `overflow` and laid out as a centered vertical stack
+ * (number / dimensions / aspect), mirroring the editor's FrameInfo.
+ */
+function buildDebugCellMaskPath(opts) {
+    const { cellW, cellH, order, label, content, overflow, borderPx, minTextSize, suppressLabel } = opts;
+    const canvas = { width: cellW, height: cellH };
+    const smallerDim = Math.min(cellW, cellH);
+    const pad = Math.max(4, Math.round(smallerDim * 0.04));
+    const parts = [];
+    // Border ring — same ink as the text, one uniform pen width across all tiles.
+    // Always drawn (it reads the structure even where the label is suppressed).
+    parts.push(rectRingPath(cellW, cellH, borderPx));
+    if (suppressLabel) {
+        return parts.filter(Boolean).join(" ");
+    }
+    if (label != null) {
+        // Custom label: one centered line, shrunk so it fits the padded width.
+        const t = label.trim();
+        if (t) {
+            const availW = Math.max(1, cellW - 2 * pad);
+            let size = clampSize(minTextSize, smallerDim * 0.16, 72);
+            const w = (0, template_utils_1.measureText)(t, { fontSize: size }).width;
+            if (w > availW)
+                size = Math.max(MIN_LEGIBLE_PX, Math.floor((size * availW) / w));
+            parts.push((0, template_utils_1.textToPath)(t, { fontSize: size, hAlign: "center", vAlign: "middle", padding: pad }, canvas));
+        }
+    }
+    else {
+        // Adaptive stack: pick the richest content level that fits, then center it.
+        const fitted = resolveLabel(content, overflow, order, cellW, cellH, minTextSize);
+        if (fitted) {
+            let totalH = 0;
+            fitted.lines.forEach((l, i) => {
+                totalH += l.size;
+                if (i > 0)
+                    totalH += fitted.gap;
+            });
+            let cursor = (cellH - totalH) / 2;
+            for (const line of fitted.lines) {
+                // vAlign "top" + padding.y = cursor places this line's top at `cursor`.
+                parts.push((0, template_utils_1.textToPath)(line.text, { fontSize: line.size, hAlign: "center", vAlign: "top", padding: { x: pad, y: cursor } }, canvas));
+                cursor += line.size + fitted.gap;
+            }
+        }
+    }
+    return parts.filter(Boolean).join(" ");
+}
+/**
+ * Resolve a stableKey-keyed labels map (Record<StableKey, M0Label>, same shape
+ * as `M0cFile.labels`) to the positional `labels` array the debug labeler
+ * consumes (1-based source order). REAL stableKeys require the full parse — the
+ * logical frames used for rendering carry only synthetic placeholder keys — so
+ * this parses with `parseM0StringComplete`. Folded in from the old
+ * `@m0saic/meta/m0-snapshot` wrapper (which existed solely for this conversion).
+ * Keys that don't match a frame are dropped; returns `undefined` when nothing
+ * resolves, so callers fall back to the default dim/AR text.
+ */
+function stableKeyLabelsToPositional(labels, m0, width, height) {
+    var _a, _b;
+    const result = (0, dsl_1.parseM0StringComplete)(m0, width, height);
+    if (!result.ok)
+        return undefined;
+    const frames = ((_b = (_a = result.ir) === null || _a === void 0 ? void 0 : _a.renderFrames) !== null && _b !== void 0 ? _b : [])
+        .slice()
+        .sort((a, b) => a.logicalIndex - b.logicalIndex);
+    const out = new Array(frames.length).fill("");
+    let anyHit = false;
+    for (let i = 0; i < frames.length; i++) {
+        const sk = frames[i].meta.stableKey;
+        const entry = labels[sk];
+        if (entry && typeof entry.text === "string" && entry.text.trim() !== "") {
+            out[i] = entry.text;
+            anyHit = true;
+        }
+    }
+    return anyHit ? out : undefined;
+}
+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). A labeled cell shows its label; cells without one keep their number and pixel size (see Label Content / Unlabeled Cells).",
+        meta: { ui: { label: "Cell Labels" } },
+    },
+    unlabeledCells: {
+        type: "string",
+        required: false,
+        description: 'What a cell without a custom label shows once some cells are labeled: "marks" (default — its number / dims per Label Content) or "empty" (blank — labels are the only text on the board).',
+        meta: {
+            constraints: { oneOf: ["marks", "empty"] },
+            control: {
+                options: [
+                    { value: "marks", label: "Keep marks" },
+                    { value: "empty", label: "Leave empty" },
+                ],
+            },
+            ui: { label: "Unlabeled Cells" },
+        },
+    },
+    labelsByStableKey: {
+        type: "group",
+        required: false,
+        description: "Per-cell labels keyed by stableKey (Record<StableKey, {text, color?}>, same shape as M0cFile.labels). Resolved to positional labels internally; overrides `labels`. Agent/programmatic prop.",
+        meta: { ui: { label: "Labels by stableKey", collapsedByDefault: true, consumer: "agent" } },
+    },
+    cellColors: {
+        type: "string[]",
+        required: false,
+        description: "Optional per-cell body fill colors (1-based order, parallel to labels). Cell N's body is painted cellColors[N-1] beneath the border/label ink; an empty string leaves it transparent. Used by the perf heatmap. Debug mode only.",
+        meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Cell Colors", consumer: "agent" } },
+    },
+    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" },
+        },
+    },
+    labelContent: {
+        type: "string",
+        required: false,
+        description: "Most detail to show per tile (cumulative): none → number → dimensions → aspect. Default dimensions.",
+        meta: {
+            constraints: { oneOf: ["none", "number", "dimensions", "aspect"] },
+            control: {
+                options: [
+                    { value: "none", label: "None" },
+                    { value: "number", label: "Number" },
+                    { value: "dimensions", label: "Dimensions" },
+                    { value: "aspect", label: "Aspect ratio" },
+                ],
+            },
+            ui: { label: "Label Content" },
+        },
+    },
+    labelOverflow: {
+        type: "string",
+        required: false,
+        description: "How to back off when the content won't fit a tile: hide (all-or-nothing), degrade (drop richest lines), number-floor (fall back to just the number). Default degrade.",
+        meta: {
+            constraints: { oneOf: ["hide", "degrade", "number-floor"] },
+            control: {
+                options: [
+                    { value: "hide", label: "Hide" },
+                    { value: "degrade", label: "Degrade" },
+                    { value: "number-floor", label: "Number floor" },
+                ],
+            },
+            ui: { label: "Label Overflow" },
+        },
+    },
+    background: {
+        type: "string",
+        required: false,
+        description: 'Canvas backing: "white" (default — an opaque white fill) or "transparent" (lines/labels only, null regions empty — composites over anything). Ignored when a theme/preset sets its own background.',
+        meta: {
+            constraints: { oneOf: ["transparent", "white"] },
+            control: {
+                options: [
+                    { value: "transparent", label: "Transparent" },
+                    { value: "white", label: "White" },
+                ],
+            },
+            ui: { label: "Background" },
+        },
+    },
+    nullFrames: {
+        type: "string",
+        required: false,
+        description: 'Dev: "show" explodes the layout into LAYERS — one PNG per overlay depth (emit:multi), each printing that depth\'s cells plus its null (-) holes as dashed, muted cells labelled "null" + size. "hide" (default) renders the normal single composite.',
+        meta: {
+            constraints: { oneOf: ["hide", "show"] },
+            control: {
+                options: [
+                    { value: "hide", label: "Hide" },
+                    { value: "show", label: "Show" },
+                ],
+            },
+            ui: { label: "Null Frames" },
+        },
+    },
+    nullLabel: {
+        type: "string",
+        required: false,
+        description: 'Dev: the text drawn inside a hole cell when null frames show — the word "null" (default) or the m0 token "-".',
+        meta: {
+            constraints: { oneOf: ["null", "-"] },
+            control: {
+                options: [
+                    { value: "null", label: "null" },
+                    { value: "-", label: "- (m0 token)" },
+                ],
+            },
+            ui: { label: "Null Label" },
+        },
+    },
+    fill: {
+        type: "number",
+        required: false,
+        description: "Translucent rect fill (debug mode), 0..1. Body wash beneath the borders/labels so rects read as filled regions over a traced image. 0 = lines only.",
+        meta: {
+            constraints: { min: 0, max: 1 },
+            ui: { label: "Rect Fill" },
+        },
+    },
+    backgroundImage: {
+        type: "media",
+        required: false,
+        description: "Image baked beneath the wireframe — lines/labels render on top. A file path or an inline base64 data: URI. Drop a reference screenshot here to trace a layout over it.",
+        meta: {
+            control: { picker: "file", accept: ["image"] },
+            ui: { label: "Background Image" },
+        },
+    },
+    backgroundImageOpacity: {
+        type: "number",
+        required: false,
+        description: "Background-image opacity, 0..1. Default 1 (fully opaque).",
+        meta: {
+            control: { placeholder: "1 (opaque)" },
+            constraints: { min: 0, max: 1 },
+            ui: { label: "Background Image Opacity" },
+        },
+    },
+    backgroundImageFit: {
+        type: "string",
+        required: false,
+        description: 'How the background image fills the canvas: "cover" (default, fill + crop) or "contain" (letterbox, pad reveals the canvas background).',
+        meta: {
+            constraints: { oneOf: ["cover", "contain"] },
+            control: {
+                options: [
+                    { value: "cover", label: "Cover" },
+                    { value: "contain", label: "Contain" },
+                ],
+            },
+            ui: { label: "Background Image Fit" },
+        },
+    },
+    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 } },
+    },
+});
+// ── Template ──
+exports.WireframeV2 = {
+    id: (0, types_1.asTemplateId)("@m0saic/wireframe/base/v2"),
+    label: "Wireframe v2",
+    version: 2,
+    description: "Wireframe of any m0 layout string: every cell drawn as an outlined rectangle with its number, pixel size and aspect ratio on a white canvas. Switch the background to transparent to composite over anything or trace a reference screenshot, or pick the thumb, heatmap or paper presets for clean tiles.",
+    capabilities: { tier: "core" },
+    tags: ["wireframe", "docs-only", "designers", "developers", "layout", "blueprint"],
+    outputHints: {
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 1000,
+        note: "Wireframe for documentation (layout visualization)",
+        format: { kind: "image", container: "png", pixelFormat: "rgba" },
+    },
+    propsSchema,
+    // Explicit debug style (gate 29, founder: "we need the props to default
+    // to this style of debug. other forms dont read as obvious in editor"):
+    // every knob the default look depends on is spelled out so the Make
+    // form shows the state it renders. Byte-identical to the implicit
+    // defaults; a chosen `preset` still decides thumb-vs-debug (v1
+    // resolveTheme, layer 3).
+    defaultProps: {
+        preset: "none",
+        backgroundImageFit: "cover",
+        M0String: DEFAULT_LAYOUT,
+        mode: "debug",
+        labelContent: "dimensions",
+        labelOverflow: "degrade",
+        unlabeledCells: "marks",
+        background: "white",
+        nullFrames: "hide",
+        nullLabel: "null",
+        fill: 0,
+    },
+    render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x;
+        // "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, cellColors } = props;
+        // stableKey-keyed labels (folded in from the old m0-snapshot wrapper)
+        // resolve to the same positional array and take precedence over the
+        // positional `labels` prop when supplied.
+        const positionalFromStableKeys = props.labelsByStableKey
+            ? stableKeyLabelsToPositional(props.labelsByStableKey, M0String, ctx.target.width, ctx.target.height)
+            : undefined;
+        const effectiveLabels = positionalFromStableKeys !== null && positionalFromStableKeys !== void 0 ? positionalFromStableKeys : labels;
+        const unlabeledCells = (_a = props.unlabeledCells) !== null && _a !== void 0 ? _a : DEFAULT_UNLABELED_CELLS;
+        const hasTheming = !!props.preset || !!props.theme || props.mode === "thumb";
+        const resolved = hasTheming ? (0, wireframe_1.resolveTheme)(props) : null;
+        const useThumb = (_b = resolved === null || resolved === void 0 ? void 0 : resolved.useThumb) !== null && _b !== void 0 ? _b : false;
+        const frames = (0, template_utils_1.parseMosaicFrames)(M0String, ctx);
+        const sources = [];
+        // Nested child docs for heat-coloured cells (see the `cellColors` branch
+        // in the debug path below). Empty unless `cellColors` is supplied — so
+        // the default wireframe stays one flat single-command document.
+        const childDocs = {};
+        const useCellColors = ((_c = cellColors === null || cellColors === void 0 ? void 0 : cellColors.length) !== null && _c !== void 0 ? _c : 0) > 0;
+        // Paint-order (z) + global geometry per tile, so a tile whose label is
+        // covered by a higher-z tile (an overlay) can suppress that label — the
+        // wireframe is built from transparent-body masks, so without this a base
+        // tile's glyphs bleed straight through whatever overlays it. Joined to
+        // the logical frames below by logicalIndex.
+        const renderFrames = (0, template_utils_1.parseMosaicRenderFrames)(M0String, ctx);
+        const zByLogical = new Map();
+        const zRects = [];
+        for (const rf of renderFrames) {
+            const li = rf.logicalIndex;
+            if (li != null)
+                zByLogical.set(li, rf.paintOrder);
+            zRects.push({ z: rf.paintOrder, x: rf.x, y: rf.y, w: rf.width, h: rf.height });
+        }
+        const minTextSize = props.preset === "debug-contrast" ? 18 : 14;
+        const labelContent = (_d = props.labelContent) !== null && _d !== void 0 ? _d : DEFAULT_LABEL_CONTENT;
+        const labelOverflow = (_e = props.labelOverflow) !== null && _e !== void 0 ? _e : DEFAULT_LABEL_OVERFLOW;
+        const showNullFrames = ((_f = props.nullFrames) !== null && _f !== void 0 ? _f : DEFAULT_NULL_FRAMES) === "show";
+        // Translucent rect fill (debug mode): a body wash beneath the opaque
+        // border/labels so the rects read as filled regions over a traced
+        // image. Clamped 0..1; 0 (default) = transparent body (lines only).
+        const fillAlpha = Math.max(0, Math.min(1, (_g = props.fill) !== null && _g !== void 0 ? _g : 0));
+        // Canvas size from the frame bounds (frames tile the whole canvas), used
+        // for ONE uniform debug border weight across every tile — see
+        // DEBUG_BORDER_FRAC. Honour a preset/explicit borderWidthFrac only when
+        // it's a sane canvas-relative value (≤ MAX_CANVAS_BORDER_FRAC); the
+        // legacy 0.005 tile-relative baseline falls back to the v2 default.
+        let canvasW = 0;
+        let canvasH = 0;
+        for (const f of frames) {
+            canvasW = Math.max(canvasW, f.x + f.width);
+            canvasH = Math.max(canvasH, f.y + f.height);
+        }
+        const themedFrac = resolved === null || resolved === void 0 ? void 0 : resolved.borderWidthFrac;
+        const borderFrac = themedFrac != null && themedFrac <= MAX_CANVAS_BORDER_FRAC ? themedFrac : DEBUG_BORDER_FRAC;
+        const uniformBorderPx = Math.max(1, Math.round(Math.min(canvasW, canvasH) * borderFrac));
+        let order = 0;
+        for (const frame of frames) {
+            if (frame.nullRender)
+                continue;
+            order += 1;
+            const cellW = frame.width;
+            const cellH = frame.height;
+            if (useThumb) {
+                // ── Thumb: flat color tile, border/rounding via effects. ──
+                let tileColor = (_h = resolved === null || resolved === void 0 ? void 0 : resolved.tileColor) !== null && _h !== void 0 ? _h : "#141824";
+                if (((_j = resolved === null || resolved === void 0 ? void 0 : resolved.heatmap) === null || _j === void 0 ? void 0 : _j.enabled) && resolved.heatmap.shades.length > 0) {
+                    tileColor = resolved.heatmap.shades[(order - 1) % resolved.heatmap.shades.length];
+                }
+                else if (resolved && order % 2 === 0) {
+                    tileColor = resolved.tileColorAlt;
+                }
+                const effects = {
+                    rounding: (_k = resolved === null || resolved === void 0 ? void 0 : resolved.rounding) !== null && _k !== void 0 ? _k : { borderRadius: 0.04, cornerStyle: "rounded" },
+                    stroke: {
+                        width: (_l = resolved === null || resolved === void 0 ? void 0 : resolved.borderWidthFrac) !== null && _l !== void 0 ? _l : 0.0015,
+                        color: ((_m = resolved === null || resolved === void 0 ? void 0 : resolved.borderColor) !== null && _m !== void 0 ? _m : "#ffffff"),
+                        alpha: (_o = resolved === null || resolved === void 0 ? void 0 : resolved.borderAlpha) !== null && _o !== void 0 ? _o : 0.1,
+                        position: "inner",
+                    },
+                };
+                if (resolved === null || resolved === void 0 ? void 0 : resolved.dropShadow)
+                    effects.dropShadow = resolved.dropShadow;
+                sources.push((0, template_utils_1.makeColorTile)(tileColor, { effects }));
+            }
+            else {
+                // ── Debug: one ink tile masked to border + glyph outlines. ──
+                // Every debug cell is bound to `labels[order-1]` (Make's
+                // double-click → inline edit) — the same positional mapping
+                // the labeler reads, so a cell with no custom label yet is
+                // still a handle to ADD one. Thumb tiles carry no labels and
+                // stay unbound.
+                const ink = ((_p = resolved === null || resolved === void 0 ? void 0 : resolved.borderColor) !== null && _p !== void 0 ? _p : "#000000");
+                const label = cellLabelFor(effectiveLabels, order, unlabeledCells);
+                // Suppress this tile's label if a higher-z tile covers where the
+                // label would sit — so overlaid tiles don't bleed their numbers
+                // through (closer to a real composited render).
+                const myZ = (_r = zByLogical.get((_q = frame.logicalIndex) !== null && _q !== void 0 ? _q : -1)) !== null && _r !== void 0 ? _r : -1;
+                let suppressLabel = false;
+                if (myZ >= 0) {
+                    const lineRects = labelLineRects({
+                        cellW,
+                        cellH,
+                        order,
+                        label,
+                        content: labelContent,
+                        overflow: labelOverflow,
+                        minTextSize,
+                    });
+                    outer: for (const lr of lineRects) {
+                        const gx = frame.x + lr.x;
+                        const gy = frame.y + lr.y;
+                        for (const r of zRects) {
+                            if (r.z <= myZ)
+                                continue;
+                            if (rectsIntersect(gx, gy, lr.w, lr.h, r.x, r.y, r.w, r.h)) {
+                                suppressLabel = true;
+                                break outer;
+                            }
+                        }
+                    }
+                }
+                const localPath = buildDebugCellMaskPath({
+                    cellW,
+                    cellH,
+                    order,
+                    label,
+                    content: labelContent,
+                    overflow: labelOverflow,
+                    borderPx: uniformBorderPx,
+                    minTextSize,
+                    suppressLabel,
+                });
+                const maskedInk = (0, template_utils_1.makeColorTile)(ink, {
+                    mask: {
+                        kind: "inline-mask",
+                        localPath,
+                        bounds: { x: 0, y: 0, width: cellW, height: cellH },
+                        // Translucent ink wash over the whole cell (the rect
+                        // "fill") beneath the opaque border/labels — lets the
+                        // rects read as filled regions when tracing over an
+                        // image. 0 (default) keeps the body fully transparent.
+                        ...(fillAlpha > 0 ? { matte: fillAlpha } : {}),
+                    },
+                });
+                // Per-cell heat colour (perf heatmap): paint an opaque body in
+                // `cellColors[order-1]` BENEATH the masked border/label ink so the
+                // label reads on top of the heat colour. A flat two-tile-per-cell
+                // push is impossible — the engine binds sources 1:1 with m0 leaves,
+                // and alphamerge is single-colour, so one masked tile can't carry a
+                // contrasting body + ink. Compose the two colours in a nested child
+                // mosaic instead: `F{F}` = body tile (beneath) + masked ink tile
+                // (border/label, on top). The child declares its own `size` so the
+                // engine renders it at the cell resolution (exact-fit, no stretch)
+                // and the inline-mask bounds line up. Absent/empty `cellColors[i]`
+                // keeps the original flat single-source path (no golden regression).
+                const heatColor = useCellColors ? ((_s = cellColors === null || cellColors === void 0 ? void 0 : cellColors[order - 1]) !== null && _s !== void 0 ? _s : "") : "";
+                const heatHasLabel = !!(label && label.trim());
+                if (heatColor && heatColor.trim() && !heatHasLabel) {
+                    // Heat-only cell (colours-only mode — the flattened perf image):
+                    // a single flat colour tile with the frame border as a stroke
+                    // effect. NO nested child + NO inline-mask, so a ~500-cell
+                    // flattened heatmap renders in ONE cheap pass instead of ~500
+                    // nested mosaics (which choked the flattened image entirely).
+                    sources.push((0, template_utils_1.bindProp)((0, template_utils_1.makeColorTile)(heatColor, {
+                        effects: {
+                            stroke: { width: borderFrac, color: ink, alpha: 0.5, position: "inner" },
+                        },
+                    }), "labels", order - 1));
+                }
+                else if (heatColor && heatColor.trim()) {
+                    // Body colour + label (the top perf image, few big cells): the
+                    // two colours can't share one masked tile (alphamerge is
+                    // single-colour), so compose them in a nested child `F{F}` =
+                    // body tile (beneath) + masked border/label ink (on top). The
+                    // child declares its own `size` so it renders at cell resolution
+                    // (exact-fit) and the mask bounds line up.
+                    const childRef = `heatcell${order}`;
+                    childDocs[childRef] = {
+                        kind: "mosaic_document",
+                        version: 1,
+                        assets: {},
+                        m0: "F{F}",
+                        size: {
+                            width: Math.max(1, Math.round(cellW)),
+                            height: Math.max(1, Math.round(cellH)),
+                        },
+                        sources: [(0, template_utils_1.makeColorTile)(heatColor), maskedInk],
+                        durationMs: 1000,
+                    };
+                    sources.push((0, template_utils_1.bindProp)({ type: "mosaic", ref: childRef }, "labels", order - 1));
+                }
+                else {
+                    sources.push((0, template_utils_1.bindProp)(maskedInk, "labels", order - 1));
+                }
+            }
+        }
+        // Background resolution, in priority order:
+        //   1. an explicit theme/preset backgroundColor, else
+        //   2. the `background` prop: "white" (default) bakes an opaque white
+        //      fill, "transparent" leaves it unfilled.
+        // A transparent wireframe is just lines + labels — it composites over
+        // anything and null tiles render *nothing* — but on a dark stage black
+        // ink reads as an empty canvas, hence the white default (take 4).
+        const background = (_t = props.background) !== null && _t !== void 0 ? _t : DEFAULT_BACKGROUND;
+        const bg = (_u = resolved === null || resolved === void 0 ? void 0 : resolved.backgroundColor) !== null && _u !== void 0 ? _u : (background === "white" ? "#ffffff" : null);
+        // Optional baked background image: register it as a file asset and point
+        // the document's `backgroundImage` at it. The engine composites it once,
+        // beneath every tile — so the wireframe lines/labels draw on top.
+        const assets = {};
+        let backgroundImage;
+        if (props.backgroundImage) {
+            const bgAssetId = (0, types_1.asAssetId)("wireframe_background_image");
+            // Accept either a filesystem path or an inline base64 `data:` URI —
+            // the latter keeps the document self-contained (e.g. an agent baking
+            // a reference image inline, no external file dependency).
+            assets[bgAssetId] = props.backgroundImage.startsWith("data:")
+                ? { kind: "data-uri", uri: props.backgroundImage, mediaType: "image" }
+                : { kind: "file", path: props.backgroundImage, mediaType: "image" };
+            const opacity = props.backgroundImageOpacity;
+            backgroundImage = {
+                assetId: bgAssetId,
+                ...(opacity != null ? { opacity } : {}),
+                ...(props.backgroundImageFit ? { fit: props.backgroundImageFit } : {}),
+            };
+        }
+        // Dev diagram: layer explode — one still per overlay depth, as a
+        // pipeline (founder: "layers must be emitted as separate files").
+        // Falls through to the composite only if the full parse fails.
+        if (showNullFrames) {
+            // The composite derives its canvas from the PAINTED frames' bounds; a
+            // hole on the canvas edge would shrink that (a null right column →
+            // 960 wide). The explode paints holes too, so it takes the real canvas.
+            const explodeW = ctx.output.width;
+            const explodeH = ctx.output.height;
+            const exploded = buildLayerExplode({
+                m0: M0String,
+                canvasW: explodeW,
+                canvasH: explodeH,
+                fps: ctx.output.fps,
+                useThumb,
+                resolved,
+                labels: effectiveLabels,
+                unlabeledCells,
+                labelContent,
+                labelOverflow,
+                borderPx: Math.max(1, Math.round(Math.min(explodeW, explodeH) * borderFrac)),
+                minTextSize,
+                fillAlpha,
+                bg,
+                assets,
+                backgroundImage,
+                nullLabel: (_v = props.nullLabel) !== null && _v !== void 0 ? _v : DEFAULT_NULL_LABEL,
+            });
+            if (exploded)
+                return Promise.resolve(exploded);
+        }
+        // Paper grid (the `grid-paper` preset / `theme.paperGrid`): ONE extra
+        // lattice source appended as a full-canvas TOP overlay leaf so the
+        // graph-paper reads over the opaque, rounded thumb tiles. Off → the
+        // m0 is the caller's string verbatim (consumers read it back).
+        let finalM0 = M0String;
+        if ((_w = resolved === null || resolved === void 0 ? void 0 : resolved.paperGrid) === null || _w === void 0 ? void 0 : _w.enabled) {
+            sources.push((0, paperGrid_1.makePaperGridSource)({
+                width: canvasW,
+                height: canvasH,
+                ink: ((_x = resolved.borderColor) !== null && _x !== void 0 ? _x : "#000000"),
+                stepFrac: resolved.paperGrid.stepFrac,
+                alpha: resolved.paperGrid.alpha,
+            }));
+            finalM0 = (0, paperGrid_1.appendTopOverlay)(finalM0);
+        }
+        const doc = {
+            kind: "mosaic_document",
+            version: 1,
+            assets: assets,
+            m0: (0, dsl_stdlib_1.toM0String)(finalM0, "Wireframe"),
+            sources,
+            // Gate-26 convention: every rendered doc declares its format. A
+            // wireframe is a still, alpha-carrying PNG (the transparent default
+            // is the whole point) — the same values outputHints seeds.
+            format: { kind: "image", container: "png", pixelFormat: "rgba" },
+            // No authored durationMs: the registry stamp owns it (gate 26 —
+            // authored doc durations now SURVIVE the stamp, and this 1000
+            // was a stale value that had silently relied on being clobbered;
+            // keeping it would pin every wireframe video render to 1s).
+            ...(Object.keys(childDocs).length ? { children: childDocs } : {}),
+            ...(bg != null ? { backgroundColor: (0, template_utils_1.solidBackground)(bg) } : {}),
+            ...(backgroundImage ? { backgroundImage } : {}),
+        };
+        return Promise.resolve(doc);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.WireframeV2);