@m0saic/templates 0.2.0

package/dist/m0saic/media/watermark/v1/watermark.js

@@ -0,0 +1,452 @@
+"use strict";
+/**
+ * @m0saic/media/watermark/v1 — "Watermark"
+ *
+ * The canonical user-facing watermark: stamp your logo or wordmark onto
+ * any image or video. Nine standard positions or an exact m0-rect
+ * escape hatch, ratio-true sizing, opacity control, and an N-inputs →
+ * N-outputs folder batch flow (mixed image + video folders).
+ *
+ * Modes:
+ *   - "static"   — baked in, always visible (this phase).
+ *   - "adaptive" — luma-aware light/dark variant + animated time
+ *                  windows, parity with the free-tier QR stamp (P3).
+ *   - "page"     — diagonal repeated logo/wordmark across the whole
+ *                  page (P2).
+ *
+ * Distinct from `@m0saic/forensic/watermark/video/v1` (the invisible
+ * steganographic watermark) — this one is meant to be seen.
+ *
+ * Note: on the free tier, the post-render hook adds the m0saic QR at
+ * bottom-right on top of the deliverable — pick a different corner to
+ * avoid overlap.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WatermarkV1 = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const geometry_1 = require("./geometry");
+const adaptive_1 = require("./adaptive");
+const pipeline_1 = require("./pipeline");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    sourceIds: {
+        type: "media[]",
+        required: true,
+        description: "Media to watermark — pick a folder, one or more files, or drag-and-drop. One watermarked output per input.",
+        meta: {
+            ui: { label: "Source(s)", order: 1 },
+            control: { multiple: true, picker: "folder", accept: ["image", "video"] },
+        },
+    },
+    mode: {
+        type: "string",
+        required: false,
+        description: 'Watermark mode. "static" bakes it in; "adaptive" and "page" land in later phases.',
+        meta: {
+            constraints: { oneOf: ["static", "adaptive", "page"] },
+            ui: { label: "Mode", order: 1 },
+        },
+    },
+    content: {
+        type: "string",
+        required: false,
+        description: 'What the watermark shows: your logo image, a text wordmark, or both ("lockup", later phase).',
+        meta: {
+            constraints: { oneOf: ["logo", "text", "lockup"] },
+            ui: { label: "Content", order: 2 },
+        },
+    },
+    image: {
+        type: "media",
+        required: false,
+        description: "Logo image file — PNG with transparency recommended.",
+        meta: {
+            control: { picker: "file", accept: ["image"] },
+            ui: { label: "Logo", order: 3, primary: true },
+        },
+    },
+    text: {
+        type: "string",
+        required: false,
+        description: "Wordmark text (your brand or URL).",
+        meta: {
+            control: { placeholder: "yourbrand.com" },
+            ui: { label: "Text", order: 4 },
+        },
+    },
+    textColor: {
+        type: "string",
+        required: false,
+        description: "Wordmark color.",
+        meta: {
+            constraints: { isColor: true },
+            control: { colorPicker: true },
+            ui: { label: "Text Color", order: 5 },
+        },
+    },
+    imageDark: {
+        type: "media",
+        required: false,
+        description: "Dark-background logo variant, crossfaded in over dark scenes (adaptive mode; later phase).",
+        meta: {
+            control: { picker: "file", accept: ["image"] },
+            ui: { label: "Logo (dark)", order: 1, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    textColorOnLight: {
+        type: "string",
+        required: false,
+        description: "Wordmark color over bright regions (adaptive mode; later phase).",
+        meta: {
+            constraints: { isColor: true },
+            control: { colorPicker: true },
+            ui: { label: "Text Color (on light)", order: 2, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    variant: {
+        type: "string",
+        required: false,
+        description: '"auto" follows scene luminance (bright scenes get the on-light artwork, dark scenes your primary styling); "single" always uses the primary artwork. Auto degrades to single when no luma probe is available.',
+        meta: {
+            constraints: { oneOf: ["single", "auto"] },
+            ui: { label: "Variant", order: 3, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    windowing: {
+        type: "string",
+        required: false,
+        description: '"always" keeps the watermark on (entrance fade); "windows" fades it in and out over timed appearances whose count scales with clip duration.',
+        meta: {
+            constraints: { oneOf: ["always", "windows"] },
+            ui: { label: "Windowing", order: 4, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    coverageOverride: {
+        type: "number",
+        required: false,
+        description: "Windowed mode: fraction of the clip the watermark is on-screen (overrides the duration tier).",
+        meta: {
+            constraints: { min: 0, max: 1 },
+            control: { placeholder: "auto", flavor: "slider", step: 0.05 },
+            ui: { label: "Coverage", order: 5, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    fadeMs: {
+        type: "number",
+        required: false,
+        description: "Fade in/out duration at entrance and window boundaries, ms.",
+        meta: {
+            constraints: { min: 0, max: 5000 },
+            ui: { label: "Fade (ms)", order: 6, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    crossfadeMs: {
+        type: "number",
+        required: false,
+        description: "Light↔dark crossfade duration at scene brightness changes (always-on auto), ms.",
+        meta: {
+            constraints: { min: 0, max: 5000 },
+            ui: { label: "Crossfade (ms)", order: 7, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    lumaThreshold: {
+        type: "number",
+        required: false,
+        description: "Region luma (0..255) at/above which a scene counts as bright.",
+        meta: {
+            constraints: { min: 0, max: 255 },
+            control: { flavor: "slider", step: 1 },
+            ui: { label: "Luma Threshold", order: 8, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    minGapMs: {
+        type: "number",
+        required: false,
+        description: "Minimum gap between windowed appearances, ms.",
+        meta: {
+            constraints: { min: 0, max: 60000 },
+            ui: { label: "Min Gap (ms)", order: 9, visibleWhen: { prop: "mode", equals: "adaptive" } },
+        },
+    },
+    lumaByInput: {
+        type: "json",
+        required: false,
+        description: "Override hatch: per-input region-luminance results. Normally the template pulls these itself via ctx.analysis — set this only to bypass the probe (agents, tests).",
+        meta: {
+            ui: { label: "Luma By Input", hidden: true, consumer: "agent" },
+        },
+    },
+    lockupLayout: {
+        type: "string",
+        required: false,
+        description: "Lockup arrangement: wordmark beside the logo or beneath it.",
+        meta: {
+            constraints: { oneOf: ["text-right", "text-below"] },
+            ui: { label: "Lockup Layout", order: 7, visibleWhen: { prop: "content", equals: "lockup" } },
+        },
+    },
+    angleDeg: {
+        type: "number",
+        required: false,
+        description: "Pattern rotation angle, degrees clockwise (negative = up-slope).",
+        meta: {
+            constraints: { min: -90, max: 90 },
+            control: { flavor: "slider", step: 5 },
+            ui: { label: "Angle", order: 1, visibleWhen: { prop: "mode", equals: "page" } },
+        },
+    },
+    tileGapRatio: {
+        type: "number",
+        required: false,
+        description: "Gap between pattern instances, fraction of min(width, height).",
+        meta: {
+            constraints: { min: 0.01, max: 0.5 },
+            control: { flavor: "slider", step: 0.01 },
+            ui: { label: "Tile Gap", order: 2, visibleWhen: { prop: "mode", equals: "page" } },
+        },
+    },
+    stagger: {
+        type: "boolean",
+        required: false,
+        description: "Offset alternate pattern rows by half the pitch (brick layout).",
+        meta: {
+            ui: { label: "Stagger", order: 3, visibleWhen: { prop: "mode", equals: "page" } },
+        },
+    },
+    maxTiles: {
+        type: "number",
+        required: false,
+        description: "Hard cap on pattern instances (the gap grows to satisfy it).",
+        meta: {
+            constraints: { min: 1, max: 24 },
+            control: { flavor: "slider", step: 1 },
+            ui: { label: "Max Tiles", order: 4, visibleWhen: { prop: "mode", equals: "page" } },
+        },
+    },
+    debugLayout: {
+        type: "boolean",
+        required: false,
+        description: "Dev: verify the watermark's layout contract and render a violation card instead of a broken layout.",
+        meta: {
+            ui: { label: "Debug Layout", order: 1 },
+        },
+    },
+    opacity: {
+        type: "number",
+        required: false,
+        description: "Watermark opacity.",
+        meta: {
+            constraints: { min: 0.05, max: 1 },
+            control: { flavor: "slider", step: 0.05 },
+            ui: { label: "Opacity", order: 6 },
+        },
+    },
+    position: {
+        type: "string",
+        required: false,
+        description: "Standard placement on the canvas.",
+        meta: {
+            constraints: {
+                oneOf: [
+                    "top-left",
+                    "top-center",
+                    "top-right",
+                    "center-left",
+                    "center",
+                    "center-right",
+                    "bottom-left",
+                    "bottom-center",
+                    "bottom-right",
+                ],
+            },
+            ui: { label: "Position", order: 1 },
+        },
+    },
+    sizeRatio: {
+        type: "number",
+        required: false,
+        description: "Watermark width as a fraction of the size basis — match it to your brand assets.",
+        meta: {
+            constraints: { min: 0.02, max: 0.9 },
+            control: { flavor: "slider", step: 0.01 },
+            ui: { label: "Size", order: 2 },
+        },
+    },
+    sizeBasis: {
+        type: "string",
+        required: false,
+        description: "Which canvas dimension the size ratio measures against.",
+        meta: {
+            constraints: { oneOf: ["min", "width", "height"] },
+            ui: { label: "Size Basis", order: 3 },
+        },
+    },
+    marginRatio: {
+        type: "number",
+        required: false,
+        description: "Margin from the canvas edges, as a fraction of min(width, height).",
+        meta: {
+            constraints: { min: 0, max: 0.25 },
+            control: { flavor: "slider", step: 0.002 },
+            ui: { label: "Margin", order: 4 },
+        },
+    },
+    layoutM0: {
+        type: "m0",
+        required: false,
+        description: "Escape hatch: an m0 layout resolving to exactly ONE frame — the watermark is placed in that rect (content keeps its aspect, contain-fit). Overrides Position/Size/Margin.",
+        meta: {
+            control: { placeholder: "e.g. 4(-,-,-,2[-,F])" },
+            ui: { label: "Layout (m0)", order: 1 },
+        },
+    },
+    imageOutputFormat: {
+        type: "string",
+        required: false,
+        description: "Image outputs: match each input's container (jpg stays jpeg, else png), or force one.",
+        meta: {
+            constraints: { oneOf: ["match", "png", "jpeg"] },
+            ui: { label: "Image Format", order: 1 },
+        },
+    },
+});
+const DEFAULTS = {
+    mode: geometry_1.WATERMARK_DEFAULTS.mode,
+    content: geometry_1.WATERMARK_DEFAULTS.content,
+    text: geometry_1.WATERMARK_DEFAULTS.text,
+    textColor: geometry_1.WATERMARK_DEFAULTS.textColor,
+    textColorOnLight: geometry_1.WATERMARK_DEFAULTS.textColorOnLight,
+    lockupLayout: geometry_1.WATERMARK_DEFAULTS.lockupLayout,
+    position: geometry_1.WATERMARK_DEFAULTS.position,
+    sizeRatio: geometry_1.WATERMARK_DEFAULTS.sizeRatio,
+    sizeBasis: geometry_1.WATERMARK_DEFAULTS.sizeBasis,
+    marginRatio: geometry_1.WATERMARK_DEFAULTS.marginRatio,
+    opacity: geometry_1.WATERMARK_DEFAULTS.opacity,
+    variant: geometry_1.WATERMARK_DEFAULTS.variant,
+    windowing: geometry_1.WATERMARK_DEFAULTS.windowing,
+    fadeMs: geometry_1.WATERMARK_DEFAULTS.fadeMs,
+    crossfadeMs: geometry_1.WATERMARK_DEFAULTS.crossfadeMs,
+    lumaThreshold: geometry_1.WATERMARK_DEFAULTS.lumaThreshold,
+    minGapMs: geometry_1.WATERMARK_DEFAULTS.minGapMs,
+    angleDeg: geometry_1.WATERMARK_DEFAULTS.angleDeg,
+    tileGapRatio: geometry_1.WATERMARK_DEFAULTS.tileGapRatio,
+    stagger: geometry_1.WATERMARK_DEFAULTS.stagger,
+    maxTiles: geometry_1.WATERMARK_DEFAULTS.maxTiles,
+    imageOutputFormat: geometry_1.WATERMARK_DEFAULTS.imageOutputFormat,
+    debugLayout: geometry_1.WATERMARK_DEFAULTS.debugLayout,
+};
+// ---- TEMPLATE ----
+const ERROR_TITLE = "Watermark";
+exports.WatermarkV1 = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/media/watermark/v1"),
+    label: "Watermark",
+    version: 1,
+    description: "Stamp your logo or wordmark onto any image or video — 9 positions or an exact m0 rect, ratio-true sizing, opacity control. Point it at a folder for one watermarked output per input. (Free tier adds the m0saic QR at bottom-right — pick a different corner to avoid overlap.)",
+    capabilities: { tier: "core" },
+    tags: ["media", "watermark", "brand", "batch", "creators", "marketers", "animated", "logo", "overlay", "video"],
+    // No `format` hint on purpose: outputs are MIXED (mp4 for video
+    // inputs, png/jpeg for images). A template-level container hint wins
+    // over the user's output extension in `resolveOutputFormat` and
+    // rejects `-o out.png`; leaving it unset lets the extension drive the
+    // top-level format while each pipeline step declares its own.
+    outputHints: {
+        format: { kind: "video", container: "mp4" },
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 10000,
+    },
+    propsSchema,
+    defaultProps: DEFAULTS,
+    async 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, _y, _z;
+        const fail = (message) => (0, template_utils_1.makeErrorMosaic)(message, {
+            title: ERROR_TITLE,
+            width: ctx.target.width,
+            height: ctx.target.height,
+        });
+        const mode = (_a = props.mode) !== null && _a !== void 0 ? _a : DEFAULTS.mode;
+        if (mode !== "static" && mode !== "adaptive" && mode !== "page") {
+            return fail(`Watermark mode "${mode}" is not recognized — use "static", "adaptive", or "page".`);
+        }
+        const content = (_b = props.content) !== null && _b !== void 0 ? _b : DEFAULTS.content;
+        if (content !== "logo" && content !== "text" && content !== "lockup") {
+            return fail(`Watermark content "${content}" is not recognized — use "logo", "text", or "lockup".`);
+        }
+        const inputs = (_c = props.sourceIds) !== null && _c !== void 0 ? _c : [];
+        if (inputs.length === 0) {
+            return fail('Missing required "Source(s)": pick a folder, one or more files, or drag-and-drop.');
+        }
+        // Canvas-independent validation happens ONCE (a bad layout string or
+        // missing logo fails the whole render with a clear message); per-input
+        // problems degrade to per-step error mosaics inside the pipeline.
+        const layoutM0 = (0, geometry_1.normalizeLayoutM0)(props.layoutM0);
+        let contentInfo;
+        try {
+            if (layoutM0)
+                (0, geometry_1.validateLayoutM0)(layoutM0);
+            contentInfo = (0, geometry_1.resolveContentInfo)(props, ctx);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+        const knobs = {
+            mode,
+            content,
+            ...(props.image !== undefined ? { image: props.image } : {}),
+            ...(props.imageDark !== undefined ? { imageDark: props.imageDark } : {}),
+            text: ((_d = props.text) !== null && _d !== void 0 ? _d : DEFAULTS.text).trim(),
+            // isColor-constrained props; brand once here.
+            textColor: ((_e = props.textColor) !== null && _e !== void 0 ? _e : DEFAULTS.textColor),
+            textColorOnLight: ((_f = props.textColorOnLight) !== null && _f !== void 0 ? _f : DEFAULTS.textColorOnLight),
+            lockupLayout: (_g = props.lockupLayout) !== null && _g !== void 0 ? _g : DEFAULTS.lockupLayout,
+            position: (_h = props.position) !== null && _h !== void 0 ? _h : DEFAULTS.position,
+            sizeRatio: (_j = props.sizeRatio) !== null && _j !== void 0 ? _j : DEFAULTS.sizeRatio,
+            sizeBasis: (_k = props.sizeBasis) !== null && _k !== void 0 ? _k : DEFAULTS.sizeBasis,
+            marginRatio: (_l = props.marginRatio) !== null && _l !== void 0 ? _l : DEFAULTS.marginRatio,
+            opacity: (_m = props.opacity) !== null && _m !== void 0 ? _m : DEFAULTS.opacity,
+            layoutM0,
+            imageOutputFormat: (_o = props.imageOutputFormat) !== null && _o !== void 0 ? _o : DEFAULTS.imageOutputFormat,
+            contentInfo,
+            variant: (_p = props.variant) !== null && _p !== void 0 ? _p : DEFAULTS.variant,
+            windowing: (_q = props.windowing) !== null && _q !== void 0 ? _q : DEFAULTS.windowing,
+            fadeMs: (_r = props.fadeMs) !== null && _r !== void 0 ? _r : DEFAULTS.fadeMs,
+            crossfadeMs: (_s = props.crossfadeMs) !== null && _s !== void 0 ? _s : DEFAULTS.crossfadeMs,
+            lumaThreshold: (_t = props.lumaThreshold) !== null && _t !== void 0 ? _t : DEFAULTS.lumaThreshold,
+            minGapMs: (_u = props.minGapMs) !== null && _u !== void 0 ? _u : DEFAULTS.minGapMs,
+            ...(props.coverageOverride !== undefined ? { coverageOverride: props.coverageOverride } : {}),
+            angleDeg: (_v = props.angleDeg) !== null && _v !== void 0 ? _v : DEFAULTS.angleDeg,
+            tileGapRatio: (_w = props.tileGapRatio) !== null && _w !== void 0 ? _w : DEFAULTS.tileGapRatio,
+            stagger: (_x = props.stagger) !== null && _x !== void 0 ? _x : DEFAULTS.stagger,
+            maxTiles: (_y = props.maxTiles) !== null && _y !== void 0 ? _y : DEFAULTS.maxTiles,
+            debugLayout: (_z = props.debugLayout) !== null && _z !== void 0 ? _z : DEFAULTS.debugLayout,
+        };
+        // Adaptive auto pulls the region-luminance analysis through
+        // ctx.analysis (engine-mediated, absent in design mode / without a
+        // toolchain → auto degrades to single). The `lumaByInput` prop is
+        // the override hatch (agents, tests) and wins when set.
+        if (mode === "adaptive" && (0, geometry_1.watermarkNeedsLumaProbe)(props)) {
+            if (props.lumaByInput !== undefined) {
+                knobs.lumaByInput = props.lumaByInput;
+            }
+            else {
+                const probed = await (0, adaptive_1.probeLumaByInput)(props, inputs, ctx);
+                if (probed)
+                    knobs.lumaByInput = probed;
+            }
+        }
+        // Always a pipeline, even for one input: pipeline steps are the only
+        // vehicle where each output's canvas tracks its input's probed dims.
+        const stepNames = (0, template_utils_1.buildStepNames)(inputs);
+        const steps = inputs.map((inputPath, i) => (0, pipeline_1.buildWatermarkStep)({ inputPath, stepName: stepNames[i], knobs, ctx }));
+        const pipeline = {
+            kind: "mosaic_pipeline",
+            version: 1,
+            emit: "multi",
+            steps,
+        };
+        return pipeline;
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.WatermarkV1);
+exports.default = exports.WatermarkV1;

package/dist/m0saic/meta/camera-debug/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1/camera-debug";

package/dist/m0saic/meta/camera-debug/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/camera-debug"), exports);

package/dist/m0saic/meta/camera-debug/v1/camera-debug.d.ts

@@ -0,0 +1,98 @@
+/**
+ * ============================================================================
+ * @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.
+ * ============================================================================
+ */
+import type { MosaicTemplate } from "@m0saic/types";
+import type { M0String } from "@m0saic/dsl";
+import { type Keyframe } from "@m0saic/template-utils";
+/**
+ * The camera to verify. A superset of the engine's `MosaicCamera`: each
+ * field is a number (static), a t-expression string (paste a computed
+ * camera verbatim), or — the friendly authoring form — DECLARATIVE
+ * KEYFRAMES `[{t, v, ease?}]` compiled with `keyframeExpr`. The `t`s you
+ * write ARE the settle moments; between them the value eases (default
+ * smoothstep), before/after them it holds.
+ */
+export type CameraDebugCamera = {
+    /** Magnification. 1 = full frame; keyframes with varying values = an
+     *  animated zoom (renders as guide lines). */
+    zoom?: number | string | Keyframe[];
+    /** Horizontal crop center, 0..1 (0 = left edge, 0.5 = centered). */
+    focusX?: number | string | Keyframe[];
+    /** Vertical crop center, 0..1. */
+    focusY?: number | string | Keyframe[];
+};
+export type CameraDebugProps = {
+    /** The layout to debug the camera over. */
+    M0String: M0String;
+    /**
+     * RAW camera to verify (see {@link CameraDebugCamera} — every real
+     * `MosaicCamera` is valid here verbatim). When set, it WINS: the
+     * walk-recipe knobs below are ignored and the render simulates exactly
+     * this camera over the layout skeleton.
+     */
+    camera?: CameraDebugCamera;
+    /** Walk speed (>1 = faster). Same semantics as dsl-tutorial. Default 1. */
+    speedMultiplier?: number;
+    /**
+     * Camera zoom for the walk recipe. Omit → AUTO (legibility-driven,
+     * `autoZoomForLegibility`); 1 forces full view (static camera); >1 forces.
+     */
+    zoom?: number;
+    /** `smooth` = eased panning ring (the real camera path); `snap` = one ring
+     *  per settle window. Default `smooth`. Walk recipe only. */
+    mode?: "smooth" | "snap";
+};
+export declare const CameraDebug: MosaicTemplate<CameraDebugProps>;