@m0saic/templates 0.2.0

package/dist/m0saic/meta/camera-debug/v1/camera-debug.js

@@ -0,0 +1,490 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/meta/camera-debug/v1 — see what the camera does
+ * ============================================================================
+ *
+ * Renders any m0 layout as gray boxes and draws the CAMERA's crop viewport
+ * over it as a red rectangle, so authors can debug camera behavior without
+ * rendering real content.
+ *
+ * THE input is the `camera` prop ({@link CameraDebugCamera}) — the rolled-up
+ * value a template attaches to `effects.camera`, with each field a number, a
+ * t-expression pasted verbatim, or declarative KEYFRAMES `[{t, v, ease?}]`
+ * (compiled via `keyframeExpr` — the `t`s you assign ARE the settle moments;
+ * eased between them, held outside them). Paste the camera your template
+ * computed, put your layout skeleton behind it, and the render simulates
+ * what your final output's camera will do — math verification, no content.
+ * CLI debug flow: `m0saic make @m0saic/meta/camera-debug/v1
+ * --props '{"M0String":"…","camera":{…}}'` (pin --durationMs to the length
+ * the camera was compiled for). Rendering:
+ *   - numbers/keyframes (the normal case): the FILMSTRIP — one gated-drawbox
+ *     track of ring rects sampled at the output fps (midpoint-sampled,
+ *     holds merged, rate degraded uniformly past the argv budget). ONLY the
+ *     red rect, exactly where the camera is, panning AND resizing — no
+ *     per-frame scaling, no geq. Frame-exact: the output is fps-quantized
+ *     anyway, so the strip equals the compiled expressions at render time.
+ *   - a pasted t-EXPRESSION focus with constant zoom: a closed ring panned
+ *     by the expression itself (overlay offsets).
+ *   - a pasted t-EXPRESSION zoom (animated): the one unsampleable case —
+ *     falls back to four full-length guide lines whose central intersection
+ *     is the viewport. Prefer keyframes to get the closed rect.
+ *
+ * When no `camera` is given, the follow-walk RECIPE builds one (UI-helper
+ * model: knobs drive motion-kit function invocation): walk the leaves via
+ * `computeTimeline` → `followCamera`, zoom from the prop or
+ * `autoZoomForLegibility`. Recipe-only modes:
+ *   - `smooth` (default): ONE red ring pans along the true eased camera path
+ *     (`overlay.xExpr/yExpr` = the followCamera focus exprs × the pixel
+ *     travel). The ring's size is the constant-zoom viewport, so it is gated
+ *     OFF when the pull-back starts (an animated-zoom ring would need
+ *     per-frame scaling — R10's expensive path, not worth it for a debugger).
+ *   - `snap`: one enable-gated ring per settle window (a gatedBoxTrackSource)
+ *     — shows WHERE the camera settles and WHEN, discrete and readable.
+ *
+ * In both recipe modes a full-frame ring appears when the pull-back's full
+ * view ARRIVES (`resolvePullBackEnvelope().zoomEndSec`) and holds to the end;
+ * the gap between the walking ring vanishing and the full-frame ring
+ * appearing IS the pull-back transit. When the camera never moves (zoom ≤ 1,
+ * e.g. auto-zoom on an already-legible layout), the full-frame ring is
+ * static from t=0 — an honest "the camera does nothing here".
+ *
+ * Timeline: one step per leaf in logical order via `computeTimeline`
+ * (duration-fit: a pinned render length rescales the walk uniformly, per
+ * `resolvePinnedDurationMs`). Note the recipe walks LEAVES — it does not
+ * model dsl-tutorial's passthrough-following walk semantics.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CameraDebug = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_1 = require("@m0saic/dsl");
+const template_utils_1 = require("@m0saic/template-utils");
+const BG_COLOR = "#0E1220";
+const TILE_COLOR = "#2A3140";
+const TILE_BORDER_COLOR = "#4E5B76";
+const VIEWPORT_COLOR = "#FF3B30";
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    M0String: {
+        type: "m0",
+        required: true,
+        description: "The layout to debug the camera over.",
+        meta: {
+            control: { placeholder: 'e.g. "2(2[1,1],2[1,1])"' },
+            ui: { label: "Layout (m0 string)" },
+        },
+    },
+    camera: {
+        type: "json",
+        required: false,
+        description: 'Raw camera to verify ({zoom, focusX, focusY}) — each field a number, a t-expression, or keyframes [{t, v, ease?}] (eased between the moments you assign; holds outside them). Wins over the walk-recipe knobs. Example: {"zoom":2,"focusX":[{"t":1,"v":0},{"t":2,"v":1}],"focusY":0.5} pans left→right across 1s..2s.',
+        meta: { ui: { label: "Raw camera", collapsedByDefault: true } },
+    },
+    speedMultiplier: {
+        type: "number",
+        required: false,
+        description: "Walk speed multiplier (>1 = faster).",
+        meta: {
+            constraints: { min: 0.1, max: 8 },
+            control: { flavor: "slider", step: 0.1 },
+            ui: { label: "Speed" },
+        },
+    },
+    zoom: {
+        type: "number",
+        required: false,
+        description: "Camera zoom. Omit = auto (legibility-driven); 1 = fixed full view.",
+        meta: {
+            constraints: { min: 1, max: 8 },
+            control: { placeholder: "from camera", flavor: "slider", step: 0.25 },
+            ui: { label: "Zoom" },
+        },
+    },
+    mode: {
+        type: "string",
+        required: false,
+        description: "Viewport visualization: smooth eased pan, or snap-per-settle rings.",
+        meta: {
+            constraints: { oneOf: ["smooth", "snap"] },
+            control: {
+                options: [
+                    { value: "smooth", label: "Smooth pan" },
+                    { value: "snap", label: "Snap rings" },
+                ],
+            },
+            ui: { label: "Mode" },
+        },
+    },
+});
+exports.CameraDebug = {
+    id: (0, types_1.asTemplateId)("@m0saic/meta/camera-debug/v1"),
+    label: "Camera Debugger",
+    version: 1,
+    description: "Gray-box wireframe of any layout with the camera's crop viewport drawn as a red rectangle — debug follow-camera motion without rendering real content.",
+    capabilities: { tier: "core" },
+    // Dev/debug tool — keep off the shelves.
+    internal: true,
+    tags: ["developer", "meta", "camera", "debug"],
+    outputHints: {
+        width: 1280,
+        height: 720,
+        fps: 30,
+        durationMs: 5000,
+        note: "Camera viewport visualized over a gray-box layout walk.",
+    },
+    propsSchema,
+    defaultProps: {
+        mode: "smooth",
+        speedMultiplier: 1,
+        M0String: "2(2[1,1],2[1,1])",
+        // Default demo: a four-corner X tour (TL → BR → BL → TR) at zoom 2 —
+        // the rect visibly pans corner to corner then holds. Clear the Raw
+        // camera field to fall back to the walk recipe (auto zoom).
+        camera: {
+            zoom: 2,
+            focusX: [
+                { t: 0.5, v: 0 },
+                { t: 1.5, v: 1 },
+                { t: 2.5, v: 0 },
+                { t: 3.5, v: 1 },
+            ],
+            focusY: [
+                { t: 0.5, v: 0 },
+                { t: 1.5, v: 1 },
+                { t: 2.5, v: 1 },
+                { t: 3.5, v: 0 },
+            ],
+        },
+    },
+    render(props, ctx) {
+        var _a, _b, _c, _d;
+        const W = ctx.target.width;
+        const H = ctx.target.height;
+        const m0 = String(props.M0String);
+        const parsed = (0, dsl_1.parseM0StringComplete)(m0, W, H);
+        if (!parsed.ok) {
+            throw new Error(`camera-debug: m0 parse failed — ${(_b = (_a = parsed.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : "unknown"}`);
+        }
+        const rects = parsed.ir.renderFrames.slice().sort((a, b) => a.logicalIndex - b.logicalIndex);
+        const timeline = (0, template_utils_1.computeTimeline)({
+            stepCount: rects.length,
+            speedMultiplier: (_c = props.speedMultiplier) !== null && _c !== void 0 ? _c : 1,
+            targetDurationMs: (0, template_utils_1.resolvePinnedDurationMs)(ctx),
+        });
+        const endSec = timeline.durationMs / 1000;
+        const settle = (i) => timeline.stepStartSec(i) + timeline.stepDurSec / 2;
+        const zoom = props.zoom != null
+            ? props.zoom
+            : (0, template_utils_1.autoZoomForLegibility)(rects.map((r) => ({ width: r.width, height: r.height })), W, H, W, H);
+        const ringT = Math.max(2, Math.round(Math.min(W, H) * 0.005));
+        const sources = [];
+        // ── Gray tiles with DISTINCT BORDERS, still O(1) sources at any tile
+        // count (the dsl-canvas two-atlas idiom): a border-colored silhouette
+        // underneath + the fill silhouette inset by a hairline (radius reduced
+        // to stay concentric), so the underlayer reads as an inner stroke and
+        // the geometry outline is visible. Combined subpaths across both
+        // atlases ride ONE resolver arg → borders drop first past budget, then
+        // the masked fill degrades to a flat fill. ──
+        const N = rects.length;
+        const drawBorders = N > 0 && 2 * N <= template_utils_1.MASK_SUBPATH_BUDGET;
+        const drawTiles = N > 0 && N <= template_utils_1.MASK_SUBPATH_BUDGET;
+        const tileRadius = (w, h) => Math.max(0, Math.floor(Math.min(w, h) * 0.04));
+        if (drawTiles) {
+            if (drawBorders) {
+                const borderPaths = rects.map((r) => {
+                    const w = Math.round(r.width);
+                    const h = Math.round(r.height);
+                    if (w <= 0 || h <= 0)
+                        return "";
+                    return (0, template_utils_1.roundedRectPathD)(Math.round(r.x), Math.round(r.y), w, h, tileRadius(w, h));
+                });
+                sources.push((0, template_utils_1.maskAtlasSource)(borderPaths, TILE_BORDER_COLOR, { width: W, height: H }));
+            }
+            const fillPaths = rects.map((r) => {
+                const iw = Math.round(r.width);
+                const ih = Math.round(r.height);
+                if (iw <= 0 || ih <= 0)
+                    return "";
+                const outerR = tileRadius(iw, ih);
+                const bw = drawBorders ? Math.max(1, Math.floor(0.004 * Math.min(iw, ih))) : 0;
+                const w = iw - 2 * bw;
+                const h = ih - 2 * bw;
+                if (w <= 0 || h <= 0)
+                    return "";
+                const r2 = drawBorders ? Math.max(outerR - bw, 0) : outerR;
+                return (0, template_utils_1.roundedRectPathD)(Math.round(r.x) + bw, Math.round(r.y) + bw, w, h, r2);
+            });
+            sources.push((0, template_utils_1.maskAtlasSource)(fillPaths, TILE_COLOR, { width: W, height: H }));
+        }
+        else if (N > 0) {
+            sources.push((0, template_utils_1.makeColorTile)(TILE_COLOR));
+        }
+        // Normalize a camera field (number | expr | keyframes | absent) to ONE
+        // expr string. Keyframes are the friendly form: the template compiles
+        // them with keyframeExpr (the .m0t-shaped declarative input).
+        const fieldExpr = (v, fallback) => Array.isArray(v)
+            ? v.length > 0
+                ? (0, template_utils_1.keyframeExpr)(v)
+                : fallback
+            : v == null
+                ? fallback
+                : typeof v === "number"
+                    ? v.toFixed(5)
+                    : String(v);
+        // Keyframed zoom that never changes value is CONSTANT (→ the closed
+        // ring); varying values compile to an animated-zoom expr (→ guides).
+        const zoomOf = (z) => Array.isArray(z)
+            ? z.length === 0
+                ? undefined
+                : z.every((k) => k.v === z[0].v)
+                    ? z[0].v
+                    : (0, template_utils_1.keyframeExpr)(z)
+            : z;
+        // The closed viewport ring at a CONSTANT zoom: a full-canvas tile whose
+        // mask is a viewport-sized hollow rect at the canvas top-left (outer CW +
+        // inner CCW cuts the hole under both fill rules), panned by offset exprs.
+        // Overlay x/y exprs are NOT auto-rebalanced by the engine funnels (only
+        // enable/alpha/camera are) — rebalance here or dense walks hit the ~100-
+        // term parse cliff.
+        const pushViewportRing = (z, fxExpr, fyExpr, enable) => {
+            const vw = Math.max(2 * ringT, Math.round(W / z));
+            const vh = Math.max(2 * ringT, Math.round(H / z));
+            const travelX = W - W / z;
+            const travelY = H - H / z;
+            const outer = `M0 0 H${vw} V${vh} H0 Z`;
+            const inner = `M${ringT} ${ringT} V${vh - ringT} H${vw - ringT} V${ringT} Z`;
+            sources.push((0, template_utils_1.makeColorTile)(VIEWPORT_COLOR, {
+                mask: {
+                    kind: "inline-mask",
+                    localPath: `${outer} ${inner}`,
+                    bounds: { x: 0, y: 0, width: W, height: H },
+                },
+                overlay: {
+                    xExpr: (0, template_utils_1.rebalanceAdditiveChains)(`(${travelX.toFixed(4)})*(${fxExpr})`),
+                    yExpr: (0, template_utils_1.rebalanceAdditiveChains)(`(${travelY.toFixed(4)})*(${fyExpr})`),
+                    ...(enable ? { enable } : {}),
+                },
+            }));
+        };
+        // Camera never moves → an honest static full-frame viewport ring.
+        const pushStaticRing = () => {
+            sources.push((0, template_utils_1.gatedBoxTrackSource)([{ x: 0, y: 0, w: W, h: H, thicknessPx: ringT }], {
+                color: VIEWPORT_COLOR,
+            }));
+        };
+        // ── JS-side keyframe sampling (mirrors keyframeExpr semantics: hold
+        // before first / after last, per-key ease shapes the segment LEAVING the
+        // key, 1e-4 duration floor). Sampling lets the debugger draw the ONE
+        // thing a constant-size source can't: a closed rect that RESIZES. ──
+        const easeU = (ease, u) => ease === "linear"
+            ? u
+            : ease === "easeOut"
+                ? 1 - (1 - u) * (1 - u)
+                : u * u * (3 - 2 * u); // smoothstep / easeInOut / default
+        const sampleKeys = (keys, t) => {
+            if (t < keys[0].t || keys.length === 1)
+                return keys[0].v;
+            for (let i = 0; i < keys.length - 1; i++) {
+                const a = keys[i];
+                const b = keys[i + 1];
+                if (t >= a.t && t < b.t) {
+                    const dur = Math.max(1e-4, b.t - a.t);
+                    const u = Math.min(1, Math.max(0, (t - a.t) / dur));
+                    return a.v + (b.v - a.v) * easeU(a.ease, u);
+                }
+            }
+            return keys[keys.length - 1].v;
+        };
+        // A camera field is SAMPLEABLE when it's a number or keyframes; a pasted
+        // expression string is opaque to JS (no evaluator) → null.
+        const samplerOf = (v, fallback) => v == null
+            ? () => fallback
+            : typeof v === "number"
+                ? () => v
+                : Array.isArray(v)
+                    ? v.length > 0
+                        ? (t) => sampleKeys(v, t)
+                        : () => fallback
+                    : null;
+        // ── The FILMSTRIP: the whole camera as ONE gated drawbox track — a ring
+        // per frame-slice at the exact sampled viewport rect (midpoint-sampled),
+        // consecutive identical rects merged (holds cost one box). This is what
+        // the render shows anyway (the output is fps-quantized), so the strip is
+        // frame-exact, and the rect both PANS and RESIZES — no guides, no grid.
+        // Slice rate = output fps, degraded uniformly past the argv budget. ──
+        const pushFilmstrip = (zoomAt, fxAt, fyAt, durSec) => {
+            const fps = ctx.target.fps > 0 ? ctx.target.fps : 30;
+            const rate = Math.ceil(durSec * fps) > template_utils_1.GATED_BOX_BUDGET ? template_utils_1.GATED_BOX_BUDGET / durSec : fps;
+            const n = Math.max(1, Math.ceil(durSec * rate));
+            const boxes = [];
+            for (let i = 0; i < n; i++) {
+                const t0 = (i / n) * durSec;
+                const t1 = ((i + 1) / n) * durSec;
+                const tm = (t0 + t1) / 2;
+                const z = Math.max(1, zoomAt(tm));
+                const vp = (0, template_utils_1.cameraViewportRect)(fxAt(tm), fyAt(tm), z, W, H);
+                const x = Math.round(vp.x);
+                const y = Math.round(vp.y);
+                const w = Math.max(2 * ringT, Math.round(vp.width));
+                const h = Math.max(2 * ringT, Math.round(vp.height));
+                const prev = boxes[boxes.length - 1];
+                if (prev && prev.x === x && prev.y === y && prev.w === w && prev.h === h) {
+                    prev.toSec = t1; // hold → extend the previous ring's window
+                }
+                else {
+                    boxes.push({ x, y, w, h, fromSec: t0, toSec: t1, thicknessPx: ringT });
+                }
+            }
+            // The last ring holds to the end of the clip (gte-only gate).
+            if (boxes.length > 0)
+                delete boxes[boxes.length - 1].toSec;
+            sources.push((0, template_utils_1.gatedBoxTrackSource)(boxes, { color: VIEWPORT_COLOR }));
+        };
+        // ── The viewport ──
+        const raw = props.camera;
+        if (raw) {
+            // RAW mode: simulate exactly the supplied camera, full duration. The
+            // recipe knobs (zoom/speed/mode) are ignored — the math to verify is
+            // already rolled up inside the camera value.
+            const zAt = samplerOf(raw.zoom, 1);
+            const xAt = samplerOf(raw.focusX, 0.5);
+            const yAt = samplerOf(raw.focusY, 0.5);
+            if (zAt && xAt && yAt) {
+                // Numbers/keyframes → the filmstrip: ONLY the red rect, exactly
+                // where the camera is, panning AND resizing. A static camera merges
+                // down to a single always-on ring.
+                pushFilmstrip(zAt, xAt, yAt, endSec);
+            }
+            else {
+                // Some field is a pasted EXPRESSION STRING — opaque to JS, so the
+                // filmstrip can't sample it.
+                const fx = fieldExpr(raw.focusX, "0.5");
+                const fy = fieldExpr(raw.focusY, "0.5");
+                const rawZoom = zoomOf(raw.zoom);
+                if (typeof rawZoom === "string") {
+                    // Animated expression zoom: the window resizes but its size can't
+                    // be sampled OR carried by a constant-size ring — the one case
+                    // that falls back to four guide lines (their central intersection
+                    // IS the viewport). Prefer keyframes to get the closed rect.
+                    const zE = `(${rawZoom})`;
+                    const xL = `(${fx})*(${W}-${W}/${zE})`;
+                    const yT = `(${fy})*(${H}-${H}/${zE})`;
+                    const vStripe = `M0 0 H${ringT} V${H} H0 Z`;
+                    const hStripe = `M0 0 H${W} V${ringT} H0 Z`;
+                    const guide = (stripe, ov) => (0, template_utils_1.makeColorTile)(VIEWPORT_COLOR, {
+                        mask: {
+                            kind: "inline-mask",
+                            localPath: stripe,
+                            bounds: { x: 0, y: 0, width: W, height: H },
+                        },
+                        overlay: {
+                            ...(ov.xExpr ? { xExpr: (0, template_utils_1.rebalanceAdditiveChains)(ov.xExpr) } : {}),
+                            ...(ov.yExpr ? { yExpr: (0, template_utils_1.rebalanceAdditiveChains)(ov.yExpr) } : {}),
+                        },
+                    });
+                    sources.push(guide(vStripe, { xExpr: xL }));
+                    sources.push(guide(vStripe, { xExpr: `${xL}+${W}/${zE}-${ringT}` }));
+                    sources.push(guide(hStripe, { yExpr: yT }));
+                    sources.push(guide(hStripe, { yExpr: `${yT}+${H}/${zE}-${ringT}` }));
+                }
+                else if (rawZoom != null && rawZoom > 1) {
+                    // Constant zoom: the closed ring pans on the raw focus exprs.
+                    pushViewportRing(rawZoom, fx, fy);
+                }
+                else {
+                    // zoom absent / ≤ 1 → the camera is a no-op by contract.
+                    pushStaticRing();
+                }
+            }
+        }
+        else if (zoom > 1 && rects.length > 0) {
+            const targets = rects.map((r, i) => ({
+                rect: { x: r.x, y: r.y, width: r.width, height: r.height },
+                atSec: settle(i + 1),
+            }));
+            const pullBack = {
+                endSec,
+                earliestStartSec: timeline.stepStartSec(targets.length),
+                settleOutSec: Math.min(settle(targets.length) + timeline.stepDurSec / 2, endSec),
+            };
+            const env = (0, template_utils_1.resolvePullBackEnvelope)(pullBack);
+            if (((_d = props.mode) !== null && _d !== void 0 ? _d : "smooth") === "snap") {
+                const boxes = [];
+                for (let i = 0; i < targets.length; i++) {
+                    const tg = targets[i];
+                    const fx = (0, template_utils_1.centerFocus)((tg.rect.x + tg.rect.width / 2) / W, zoom);
+                    const fy = (0, template_utils_1.centerFocus)((tg.rect.y + tg.rect.height / 2) / H, zoom);
+                    const vp = (0, template_utils_1.cameraViewportRect)(fx, fy, zoom, W, H);
+                    const from = timeline.stepStartSec(i + 1);
+                    const to = i + 1 < targets.length
+                        ? timeline.stepStartSec(i + 2)
+                        : env.active
+                            ? env.outStartSec
+                            : endSec;
+                    boxes.push({
+                        x: Math.round(vp.x),
+                        y: Math.round(vp.y),
+                        w: Math.max(2 * ringT, Math.round(vp.width)),
+                        h: Math.max(2 * ringT, Math.round(vp.height)),
+                        fromSec: from,
+                        toSec: to,
+                        thicknessPx: ringT,
+                    });
+                }
+                // Full view ARRIVES: a full-frame ring holds from zoomEnd to the
+                // end. The gap after the last settle ring is the pull-back transit.
+                if (env.active) {
+                    boxes.push({ x: 0, y: 0, w: W, h: H, fromSec: env.zoomEndSec, thicknessPx: ringT });
+                }
+                if (boxes.length > 0) {
+                    sources.push((0, template_utils_1.gatedBoxTrackSource)(boxes, { color: VIEWPORT_COLOR }));
+                }
+            }
+            else {
+                // Smooth mode = the filmstrip over the SAME keys the follow camera
+                // compiles: settle keyframes per target, then a clean pull-back
+                // envelope (hold the last focus until the pull-back starts, ease to
+                // center + zoom 1 by zoomEnd, hold full frame to the end). The rect
+                // follows the walk AND grows during the pull-back — no transit gap.
+                // (On squeezed tails the ENGINE's envelope emits overlapping gates —
+                // the characterized F2 quirk; the filmstrip shows the intended path.)
+                const xs = targets.map((tg) => ({
+                    t: tg.atSec,
+                    v: (0, template_utils_1.centerFocus)((tg.rect.x + tg.rect.width / 2) / W, zoom),
+                }));
+                const ys = targets.map((tg) => ({
+                    t: tg.atSec,
+                    v: (0, template_utils_1.centerFocus)((tg.rect.y + tg.rect.height / 2) / H, zoom),
+                }));
+                let zoomKeys = [{ t: 0, v: zoom }];
+                if (env.active) {
+                    const pbStart = Math.min(endSec, Math.max(env.outStartSec, xs[xs.length - 1].t));
+                    const pbEnd = Math.min(endSec, Math.max(env.zoomEndSec, pbStart + 0.3));
+                    if (pbEnd > pbStart) {
+                        xs.push({ t: pbStart, v: xs[xs.length - 1].v }, { t: pbEnd, v: 0.5 });
+                        ys.push({ t: pbStart, v: ys[ys.length - 1].v }, { t: pbEnd, v: 0.5 });
+                        zoomKeys = [
+                            { t: pbStart, v: zoom },
+                            { t: pbEnd, v: 1 },
+                        ];
+                    }
+                }
+                pushFilmstrip((t) => sampleKeys(zoomKeys, t), (t) => sampleKeys(xs, t), (t) => sampleKeys(ys, t), endSec);
+            }
+        }
+        else {
+            // Camera never moves (zoom ≤ 1): static full-frame viewport ring.
+            pushStaticRing();
+        }
+        return Promise.resolve({
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: (0, template_utils_1.buildOverlayStack)(sources.length),
+            sources,
+            backgroundColor: BG_COLOR,
+            durationMs: timeline.durationMs,
+        });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.CameraDebug);

package/dist/m0saic/meta/fixture-fetcher/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1/fixture-fetcher";

package/dist/m0saic/meta/fixture-fetcher/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1/fixture-fetcher"), exports);

package/dist/m0saic/meta/fixture-fetcher/v1/fixture-fetcher.d.ts

@@ -0,0 +1,76 @@
+import type { MosaicTemplateUpstreamData, MosaicTemplateUpstreamVariables } from "@m0saic/types";
+/**
+ * `@m0saic/meta/fixture-fetcher/v1` — the capability-layer PROOF fixture.
+ *
+ * A deterministic, network-free, fs-free stand-in for a real data
+ * fetcher (the GitHub fetcher lands in F5). Its only job is to
+ * exercise the capability plumbing end-to-end and anchor the
+ * regression suites:
+ *
+ *  - publishes a fixed payload as an aliased `MosaicDataSource` in a
+ *    data-only `mosaic_document` (pipeline-step-0 shape);
+ *  - when `secretRef` is set, resolves it via `ctx.secrets` (which
+ *    only reaches this template because it declares
+ *    `tier: "capability"` — the Level 1 gate strips it otherwise) and
+ *    publishes a DERIVED, non-secret marker: `{ secretResolved: true,
+ *    secretLength }`. Cleartext never enters the document, the
+ *    upstream channel, or the sidecar;
+ *  - mirrors the published payload to `sidecars` so the jobs / CLI
+ *    e2e suites can byte-assert what flowed through the pipeline.
+ *
+ * The returned doc pairs the data source with a minimal 1-cell black
+ * CARRIER (the documented "data + renderable coexistence" shape from
+ * `MosaicDataSource`'s contract): a `.mosaicx` wrapper installs the
+ * rendered doc as a child behind a `mosaic` ref, and a ref's cell
+ * must point at something renderable — a strictly data-only child is
+ * unplannable behind a ref today. The carrier renders a black tile;
+ * when the owning pipeline step is `intermediate: true` (the intended
+ * wiring) that tile never reaches the deliverable. The strictly
+ * data-only INLINE step shape (no carrier) is covered by the planner
+ * unit tests (clean skip / PIPELINE_DATA_ONLY_STEP_NOT_INTERMEDIATE).
+ *
+ * Defaults are fully self-contained: no env var, no secret, no
+ * network — the default e2e sweep stays green.
+ */
+/**
+ * The fixed deterministic payload published when `payload` is not
+ * supplied. The e2e suites byte-assert against this exact object —
+ * change it and the sidecar-equality fixtures change with it.
+ */
+export declare const FIXTURE_FETCHER_DEFAULT_PAYLOAD: {
+    readonly dataset: "m0saic-fixture";
+    readonly version: 1;
+    readonly series: readonly [3, 5, 8, 13];
+    readonly label: "deterministic fixture payload";
+};
+export type FixtureFetcherProps = {
+    /** Alias the data block publishes under. Default `"fixtureData"`. */
+    alias?: string;
+    /**
+     * Payload to publish instead of the built-in fixture object. Must be
+     * a plain JSON object (it becomes `MosaicDataSource.variables`).
+     */
+    payload?: Record<string, unknown>;
+    /**
+     * Optional `SecretRef` (e.g. `env:M0SAIC_FIXTURE_SECRET`). When set,
+     * the ref is resolved via `ctx.secrets` and a derived non-secret
+     * marker is published under the `secret` key of the data block.
+     * Fails fast when the ref is unresolvable or `ctx.secrets` is absent.
+     */
+    secretRef?: string;
+};
+type FixtureFetcherOutputs = {
+    dataset: string;
+    version: number;
+    series: number[];
+    label: string;
+    secret: {
+        secretResolved: boolean;
+        secretLength: number;
+    };
+};
+type FixtureFetcherSidecars = {
+    fixtureData: Record<string, unknown>;
+};
+export declare const FixtureFetcher: import("@m0saic/types").MosaicTemplate<FixtureFetcherProps, FixtureFetcherOutputs, MosaicTemplateUpstreamVariables, MosaicTemplateUpstreamData, FixtureFetcherSidecars>;
+export default FixtureFetcher;