@m0saic/templates 0.2.0

package/dist/m0saic/media/qr/stamp/v1/qr-stamp-custom.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * @m0saic/media/qr/stamp/v1 — "QR Stamp — Custom"
+ *
+ * The user-facing registry template that wraps `stampQrOnMedia` from
+ * `@m0saic/template-utils`. Drops a QR onto an arbitrary image or
+ * video the user supplies — same engine as the auto post-render
+ * watermark, but exposed as a discoverable template in the panel.
+ *
+ * The "Image" / "Video" stamp templates that ship today are bespoke,
+ * polished surfaces (still has light/dark pick, video has gleam +
+ * adaptive crossfade with custom-tuned timing). This template is the
+ * **primitive** — minimal knobs, sensible defaults, works against any
+ * input media.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QrStampCustom = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const brandMCenter_1 = require("../../_shared/brandMCenter");
+const onboarding_cover_1 = require("../../../../_shared/onboarding-cover");
+const DEFAULTS = {
+    text: "https://www.m0saic.io",
+    position: "br",
+    // The free-tier attribution stamp's size (brand/qr-stamp: qrSizePct 26, a
+    // 24 px inset ≈ 2.2 % at 1080p) — one stamp size across the product
+    // (founder, 2026-09-16). 26 % is also the scannability floor that stamp
+    // moved to: at 18 % a 512² render put ~3.2 px on a module, under the ~4 px
+    // practical threshold; and the branded code is a version-6+ carve now.
+    sizePct: 26,
+    marginPct: 2.2,
+    mode: "auto",
+    animation: "fade-in",
+    // The QR Code template's look (founder, 2026-09-16): the stamp shipped
+    // with the plain square matrix and read as a different product's code.
+    moduleStyle: "circle",
+    center: "m",
+};
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    mediaPath: {
+        type: "media",
+        required: true,
+        description: "Image or video to brand with a QR stamp.",
+        meta: { ui: { label: "Media" }, control: { picker: "file", accept: ["image", "video"] } },
+    },
+    text: {
+        type: "string",
+        required: false,
+        description: "Text encoded into the QR — URL, plain string, or structured payload (default: https://www.m0saic.io).",
+        meta: { ui: { label: "QR payload" }, control: { flavor: "url", placeholder: "https://www.m0saic.io" } },
+    },
+    position: {
+        type: "string",
+        required: false,
+        description: "Corner placement for the stamp.",
+        meta: { ui: { label: "Corner" }, constraints: { oneOf: ["br", "bl", "tr", "tl"] } },
+    },
+    sizePct: {
+        type: "number",
+        required: false,
+        description: "Stamp size as a percent of min(W, H).",
+        meta: { ui: { label: "Size (%)" }, constraints: { min: 1, max: 50 } },
+    },
+    marginPct: {
+        type: "number",
+        required: false,
+        description: "Margin between stamp and corner edges, % of min(W, H).",
+        meta: { ui: { label: "Margin (%)" }, constraints: { min: 0, max: 25 } },
+    },
+    mode: {
+        type: "string",
+        required: false,
+        description: "QR card mode. 'auto' uses scene luminance to pick light vs dark.",
+        meta: {
+            ui: { label: "Card mode" },
+            constraints: { oneOf: ["light", "dark", "transparent", "auto"] },
+        },
+    },
+    luminanceBuckets: {
+        type: "json",
+        required: false,
+        description: "Luminance-bucket override for auto mode. Omit to let the template probe the stamp corner itself (real renders only — design previews skip analysis and fall back to the light card).",
+        meta: { ui: { label: "Luminance override" } },
+    },
+    animation: {
+        type: "string",
+        required: false,
+        description: "Entrance animation for the stamp.",
+        meta: { ui: { label: "Entrance" }, constraints: { oneOf: ["none", "fade-in"] } },
+    },
+    moduleStyle: {
+        type: "string",
+        required: false,
+        description: "Module shape: circle dots (the branded default), roundedSquare, or square (the classic matrix look).",
+        meta: { ui: { label: "Module Style" }, constraints: { oneOf: ["square", "roundedSquare", "circle"] } },
+    },
+    center: {
+        type: "string",
+        required: false,
+        description: "What the carved centre holds: the m0saic M (the branded default), your own asset (pick it below), or off for a plain code.",
+        meta: { ui: { label: "Centre" }, constraints: { oneOf: ["m", "asset", "off"] } },
+    },
+    centerAsset: {
+        type: "media",
+        required: false,
+        description: "Image or video that fills the centre safe area when Centre is 'asset' — contain-fit, over the card colour.",
+        meta: {
+            ui: { label: "Centre asset", visibleWhen: { prop: "center", equals: "asset" } },
+            control: { picker: "file", accept: ["image", "video"] },
+        },
+    },
+});
+/** The caller's centre asset as a child document: one cell, the media contain-fit, its own manifest. */
+function assetCenterDoc(assetPath, ctx, cardColor) {
+    const assetId = (0, types_1.asAssetId)("qr_stamp_center");
+    const mediaType = (0, template_utils_1.determineMediaType)(assetPath, ctx);
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: "F",
+        assets: { [assetId]: { kind: "file", path: assetPath, mediaType } },
+        sources: [{ type: "media", mediaType, assetId, placement: { fit: "contain" } }],
+        size: { width: template_utils_1.STYLED_QR_DEFAULTS.centerWidth, height: template_utils_1.STYLED_QR_DEFAULTS.centerHeight },
+        ...(cardColor !== undefined ? { backgroundColor: (0, template_utils_1.solidBackground)(cardColor) } : {}),
+    };
+}
+/**
+ * The stamp's QR look, from its knobs: the QR Code template's radii for the
+ * modules and eyes, and the carved centre — the brand M (built per card
+ * colour so its brick gaps tone with the card), the caller's own asset, or
+ * none.
+ */
+function stampLook(moduleStyle, center, centerAsset, ctx) {
+    const square = moduleStyle === "square";
+    const docFor = center === "m"
+        ? (cardColor) => (0, brandMCenter_1.buildBrandMCenterDoc)({
+            mColor: "#f97316",
+            bgColor: cardColor,
+            width: template_utils_1.STYLED_QR_DEFAULTS.centerWidth,
+            height: template_utils_1.STYLED_QR_DEFAULTS.centerHeight,
+            label: "QrStampCustom",
+        })
+        : center === "asset" && centerAsset
+            ? (cardColor) => assetCenterDoc(centerAsset, ctx, cardColor)
+            : null;
+    return {
+        moduleBorderRadius: (0, template_utils_1.styledQrModuleRadius)(moduleStyle),
+        eyeOuterBorderRadius: square ? 0 : template_utils_1.STYLED_QR_DEFAULTS.eyeOuterBorderRadius,
+        eyeInnerDotBorderRadius: square ? 0 : template_utils_1.STYLED_QR_DEFAULTS.eyeInnerDotBorderRadius,
+        ...(docFor
+            ? {
+                center: {
+                    width: template_utils_1.STYLED_QR_DEFAULTS.centerWidth,
+                    height: template_utils_1.STYLED_QR_DEFAULTS.centerHeight,
+                    paddingPct: template_utils_1.STYLED_QR_DEFAULTS.centerPaddingPct,
+                    docFor,
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * Probe the stamp corner's luminance for `mode: "auto"` via
+ * `ctx.analysis` (the engine-mediated on-demand probe). Undefined when
+ * the host attached no analysis surface (design mode, no toolchain),
+ * the media has no probed dims, or the probe fails — auto then
+ * degrades to the light card, exactly the pre-probe behavior. A probe
+ * must never kill a render.
+ */
+async function probeStampLuma(mediaPath, position, sizePct, marginPct, ctx) {
+    const analysis = ctx.analysis;
+    if (!analysis)
+        return undefined;
+    const meta = ctx.media[(0, types_1.asAssetId)(mediaPath)];
+    if (!meta || !(meta.width > 0) || !(meta.height > 0))
+        return undefined;
+    if (meta.kind !== "video" && meta.kind !== "image")
+        return undefined;
+    // Stamp rect in OUTPUT canvas px. Naive corner math (side + margin off
+    // min(W,H)) — the engine's quantized cell can drift a few px from this,
+    // which the 10% over-sampling below absorbs; scene luminance doesn't
+    // move at that scale.
+    const W = ctx.output.width;
+    const H = ctx.output.height;
+    const minDim = Math.min(W, H);
+    const side = (sizePct / 100) * minDim;
+    const margin = (marginPct / 100) * minDim;
+    const x = position === "br" || position === "tr" ? W - margin - side : margin;
+    const y = position === "br" || position === "bl" ? H - margin - side : margin;
+    // The base media is cover-fit into the canvas, but the probe samples
+    // the input FILE — map the canvas-space rect through the centered
+    // cover crop into the media's own pixel space.
+    const s = Math.max(W / meta.width, H / meta.height);
+    const cropX = (meta.width - W / s) / 2;
+    const cropY = (meta.height - H / s) / 2;
+    const rx = cropX + x / s;
+    const ry = cropY + y / s;
+    const rSide = side / s;
+    // 10% total over-sampling per axis (same rationale as the watermark
+    // probe): content just outside the card bleeds under it during fades.
+    const xPct = Math.max(0, (rx - 0.05 * rSide) / meta.width);
+    const yPct = Math.max(0, (ry - 0.05 * rSide) / meta.height);
+    const region = {
+        xPct,
+        yPct,
+        wPct: Math.min(1 - xPct, (1.1 * rSide) / meta.width),
+        hPct: Math.min(1 - yPct, (1.1 * rSide) / meta.height),
+    };
+    try {
+        const r = await analysis.regionLuminance(mediaPath, region, {
+            bucketMs: 500,
+            smoothingMs: meta.kind === "video" ? 1500 : 500,
+        });
+        return r.buckets.length > 0 ? r.buckets : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+exports.QrStampCustom = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/media/qr/stamp/v1"),
+    label: "QR Stamp",
+    version: 1,
+    // BITMAP drafting mode (handbook §3c): the split counts ARE the QR module grid —
+    // never live-composed, so the latticeSmooth convention does not apply.
+    lattice: { mode: "bitmap" },
+    description: "Drop a QR onto any image or video. Same engine as the auto post-render watermark, exposed for direct use.",
+    capabilities: {
+        tier: "capability",
+        caps: { fs: { read: true, write: true, temp: true } },
+    },
+    tags: ["brand", "qr", "stamp", "custom", "marketers", "creators", "animated", "link", "video"],
+    outputHints: {
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 5000,
+        format: { kind: "video", container: "mp4" },
+    },
+    propsSchema,
+    defaultProps: DEFAULTS,
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        if (!props.mediaPath) {
+            return (0, template_utils_1.makeErrorMosaic)("QrStampCustom: mediaPath prop is required (the media to brand).", {
+                title: "QR Stamp",
+                width: ctx.target.width,
+                height: ctx.target.height,
+            });
+        }
+        const text = (_a = props.text) !== null && _a !== void 0 ? _a : DEFAULTS.text;
+        const position = (_b = props.position) !== null && _b !== void 0 ? _b : DEFAULTS.position;
+        const sizePctRaw = (_c = props.sizePct) !== null && _c !== void 0 ? _c : DEFAULTS.sizePct;
+        const marginPctRaw = (_d = props.marginPct) !== null && _d !== void 0 ? _d : DEFAULTS.marginPct;
+        const mode = (_e = props.mode) !== null && _e !== void 0 ? _e : DEFAULTS.mode;
+        const animation = (_f = props.animation) !== null && _f !== void 0 ? _f : DEFAULTS.animation;
+        const moduleStyle = (_g = props.moduleStyle) !== null && _g !== void 0 ? _g : DEFAULTS.moduleStyle;
+        const center = (_h = props.center) !== null && _h !== void 0 ? _h : DEFAULTS.center;
+        const centerAsset = ((_j = props.centerAsset) === null || _j === void 0 ? void 0 : _j.trim()) || undefined;
+        if (center === "asset" && !centerAsset) {
+            return (0, template_utils_1.makeErrorMosaic)("QrStampCustom: Centre is 'asset' but no centre asset was given — pick an image or video, or switch Centre to 'm' / 'off'.", { title: "QR Stamp", width: ctx.target.width, height: ctx.target.height });
+        }
+        const mediaType = (0, template_utils_1.determineMediaType)(props.mediaPath, ctx);
+        const baseAssetId = (0, types_1.asAssetId)("qr_stamp_custom_base");
+        const baseAssets = {
+            [baseAssetId]: {
+                kind: "file",
+                path: props.mediaPath,
+                mediaType,
+            },
+        };
+        // Build the minimal "base doc" that stampQrOnMedia composes around:
+        // a single F tile carrying the user media at cover-fit.
+        const baseDoc = {
+            kind: "mosaic_document",
+            version: 1,
+            // Bare "F" — stampQrOnMedia wraps this as its outer base layer.
+            m0: "F",
+            sources: [
+                {
+                    type: "media",
+                    mediaType,
+                    assetId: baseAssetId,
+                    placement: { fit: "cover" },
+                },
+            ],
+            assets: baseAssets,
+            size: { width: ctx.output.width, height: ctx.output.height },
+        };
+        // Auto mode pulls its own luma evidence (lazily — only when needed
+        // and not overridden by the prop). Everything else must skip the
+        // probe entirely.
+        const luminanceBuckets = (_k = props.luminanceBuckets) !== null && _k !== void 0 ? _k : (mode === "auto"
+            ? await probeStampLuma(props.mediaPath, position, sizePctRaw, marginPctRaw, ctx)
+            : undefined);
+        let stamped;
+        try {
+            stamped = (0, template_utils_1.stampQrOnMedia)({
+                baseDoc,
+                text,
+                position,
+                sizePct: sizePctRaw / 100,
+                marginPct: marginPctRaw / 100,
+                mode,
+                ...(luminanceBuckets ? { luminanceBuckets } : {}),
+                animation,
+                qr: stampLook(moduleStyle, center, centerAsset, ctx),
+                canvasW: ctx.output.width,
+                canvasH: ctx.output.height,
+            });
+        }
+        catch (err) {
+            return (0, template_utils_1.makeErrorMosaic)(`QrStampCustom: ${err instanceof Error ? err.message : String(err)}`, {
+                title: "QR Stamp",
+                width: ctx.target.width,
+                height: ctx.target.height,
+            });
+        }
+        // The QR is ONE `mosaic` rect per variant on the parent (the module grid
+        // lives inside the child) — bind that rect to `text` so Make's
+        // double-click on the code edits the encoded URL. Modules stay unbound.
+        for (const src of (_l = stamped.sources) !== null && _l !== void 0 ? _l : []) {
+            if (src.type === "mosaic")
+                (0, template_utils_1.bindProp)(src, "text");
+        }
+        return stamped;
+    },
+});
+// Editor-only first-open cover — the template previously had NONE, so the
+// default open rendered the mediaPath-required error card. The mosaic-
+// branding BAND instead: a REAL film still (Big Buck Bunny, bundled) with
+// the template's own corner stamp card composed on it via stampQrOnMedia
+// (mode "light", animation "none" — deterministic, no luma probe).
+exports.QrStampCustom.renderCover = async function renderCover(_props, ctx) {
+    var _a, _b;
+    const heroBox = (0, onboarding_cover_1.brandedCoverHeroBox)(ctx, "band");
+    const isNode = typeof process !== "undefined" && !!((_a = process.versions) === null || _a === void 0 ? void 0 : _a.node);
+    const unpackedAsar = (p) => p.includes("/app.asar/")
+        ? p.split("/app.asar/").join("/app.asar.unpacked/")
+        : p.split("\\app.asar\\").join("\\app.asar.unpacked\\");
+    const baseAssetId = (0, types_1.asAssetId)("qr-stamp-cover-frame");
+    const heroAssets = (isNode
+        ? {
+            [baseAssetId]: {
+                kind: "file",
+                path: unpackedAsar(`${__dirname}/assets/cover-frame.jpg`),
+                mediaType: "image",
+            },
+        }
+        : {});
+    const baseDoc = {
+        kind: "mosaic_document",
+        version: 1,
+        m0: "F",
+        sources: [
+            isNode
+                ? {
+                    type: "media",
+                    mediaType: "image",
+                    assetId: baseAssetId,
+                    placement: { fit: "cover" },
+                }
+                : { type: "lavfi", color: "#21262d" },
+        ],
+        assets: heroAssets,
+        size: { width: heroBox.width, height: heroBox.height },
+    };
+    const stamped = (0, template_utils_1.stampQrOnMedia)({
+        baseDoc,
+        text: DEFAULTS.text,
+        position: DEFAULTS.position,
+        sizePct: DEFAULTS.sizePct / 100,
+        marginPct: DEFAULTS.marginPct / 100,
+        mode: "light",
+        animation: "none",
+        canvasW: heroBox.width,
+        canvasH: heroBox.height,
+    });
+    return (0, onboarding_cover_1.buildBrandedCover)({
+        ctx,
+        variant: "band",
+        copy: { productName: "QR Stamp", title: "A scannable corner stamp on your media." },
+        hero: (theme) => (0, onboarding_cover_1.onboardingFrame)((0, onboarding_cover_1.inlineHeroDoc)(stamped), theme.borderStrong),
+        heroAssets: { ...heroAssets, ...((_b = stamped.assets) !== null && _b !== void 0 ? _b : {}) },
+        children: stamped.children,
+    });
+};
+(0, template_utils_1.registerTemplate)(exports.QrStampCustom);
+exports.default = exports.QrStampCustom;

package/dist/m0saic/media/qr/stamp-video/v1/expressions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Re-export shim — the pure helpers moved to `@m0saic/template-utils`
+ * (file: `qrStampExpressions.ts`) so the new `stampQrOnMedia` composer
+ * could share them without a `template-utils ← templates` cycle.
+ *
+ * Existing call sites (`./qr-stamp.ts`, sibling v2, the still v1
+ * template, and `expressions.test.ts`) keep importing from this path —
+ * they exercise the moved implementation transparently.
+ */
+export { bucketLightAlpha, buildAdaptiveAlphaExpr, buildEntranceExpr, composeAlpha, buildCornerStampM0, type CornerStampLayout, } from "@m0saic/template-utils";

package/dist/m0saic/media/qr/stamp-video/v1/expressions.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Re-export shim — the pure helpers moved to `@m0saic/template-utils`
+ * (file: `qrStampExpressions.ts`) so the new `stampQrOnMedia` composer
+ * could share them without a `template-utils ← templates` cycle.
+ *
+ * Existing call sites (`./qr-stamp.ts`, sibling v2, the still v1
+ * template, and `expressions.test.ts`) keep importing from this path —
+ * they exercise the moved implementation transparently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCornerStampM0 = exports.composeAlpha = exports.buildEntranceExpr = exports.buildAdaptiveAlphaExpr = exports.bucketLightAlpha = void 0;
+var template_utils_1 = require("@m0saic/template-utils");
+Object.defineProperty(exports, "bucketLightAlpha", { enumerable: true, get: function () { return template_utils_1.bucketLightAlpha; } });
+Object.defineProperty(exports, "buildAdaptiveAlphaExpr", { enumerable: true, get: function () { return template_utils_1.buildAdaptiveAlphaExpr; } });
+Object.defineProperty(exports, "buildEntranceExpr", { enumerable: true, get: function () { return template_utils_1.buildEntranceExpr; } });
+Object.defineProperty(exports, "composeAlpha", { enumerable: true, get: function () { return template_utils_1.composeAlpha; } });
+Object.defineProperty(exports, "buildCornerStampM0", { enumerable: true, get: function () { return template_utils_1.buildCornerStampM0; } });

package/dist/m0saic/media/qr/stamp-video/v1/gleamBand.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Diagonal "gleam band" PNG — a soft white stripe at an angle on a
+ * transparent canvas. The QR-stamp video template overlays this on
+ * top of the QR with `blendMode: "screen"` and animates its
+ * x-position so the band sweeps across the QR every `gleamPeriodSec` —
+ * matching the production-feel shimmer used by the render-hero M.
+ *
+ * Generated inline per render via the shared resvg rasterizer. Cheap
+ * (~30 ms on a tiny SVG) — orders of magnitude smaller than the
+ * stamp wrap's re-encode pass, so prebuilding the PNG into a shipped
+ * asset is not worth the build-step complexity.
+ *
+ * Pure procedural; deterministic given inputs.
+ */
+export type GleamBandOpts = {
+    /** Output PNG side length in pixels (square). Typically matches the QR's stampPx. */
+    sizePx: number;
+    /** Workspace directory the PNG is written into. */
+    workspaceDir: string;
+    /** Filename within workspaceDir. Defaults to "qr-stamp-gleam.png". */
+    outputName?: string;
+    /**
+     * Band rotation angle in degrees clockwise from vertical. Positive
+     * tilts the top of the band rightwards (the M render-hero shimmer
+     * uses ~20°). Default 20.
+     */
+    angleDeg?: number;
+    /**
+     * Half-width of the bright stripe as a fraction of the inner gradient
+     * bounding box (which is 3× the PNG side, since the inner rect is
+     * oversized to give the rotation room). Default 0.018 — so the visible
+     * stripe is roughly 11% of the PNG width: a tight specular line, not
+     * a wash. The premium read comes from a thin bright peak with a soft
+     * halo around it (see the 7-stop gradient in {@link buildGleamSvg}),
+     * matching how a real reflection on glass would look — not a soft
+     * full-bleed sweep, which is what the wider band reads as.
+     */
+    bandWidthFrac?: number;
+    /**
+     * Peak alpha at the band center (0..1). Default 0.4. Combined with
+     * `blendMode: "screen"`, this is how bright the shine looks against
+     * the orange QR modules. Lower than the previous 0.55 default
+     * because the new peaked-falloff gradient concentrates more of the
+     * brightness in a narrower core — same perceived "flash" intensity
+     * with less white-out across the modules.
+     */
+    peakAlpha?: number;
+};
+export declare function generateGleamBandPng(opts: GleamBandOpts): Promise<{
+    pngPath: string;
+}>;
+/**
+ * Build the ffmpeg overlay xExpr for a periodic gleam sweep.
+ *
+ * The band PNG is the same natural size as the QR (so `w` in the
+ * expression equals the band layer's width, which equals the QR's
+ * width). The sweep traverses the band from offscreen-left to
+ * offscreen-right over `sweepSec`, then the enable-gate on the
+ * overlay (set in qr-stamp.ts) hides the layer for the remaining
+ * `periodSec - sweepSec` — periodic rather than continuous.
+ *
+ * # Eased traversal
+ *
+ * The previous formula was linear (`min(1, mod(t,p)/sweep)`) — the
+ * band moved at constant velocity then snapped park at +0.35w. The
+ * constant velocity + hard park is what reads as "PowerPoint shine
+ * transition." Real reflections accelerate from rest, blow through
+ * the middle, decelerate at the other side — a cosine ease curve.
+ *
+ *   x_offset(t) = -X + X * (1 - cos(PI * t_norm))
+ *
+ *   where X = 0.7 * w
+ *   and   t_norm = clamp(mod(t, periodSec) / sweepSec, 0, 1)
+ *
+ * Endpoint check:
+ *   t_norm = 0    → cos(0)  =  1  → x = -X + X*(1-1)  = -X    (offscreen left)
+ *   t_norm = 0.5  → cos(PI/2) = 0 → x = -X + X*(1-0)  =  0    (centered)
+ *   t_norm = 1    → cos(PI) = -1  → x = -X + X*(1-(-1)) = +X  (offscreen right)
+ *
+ * Velocity (derivative of x w.r.t. t_norm):
+ *   v = X * PI * sin(PI * t_norm)
+ *   sin(0) = sin(PI) = 0 → v = 0 at the endpoints (smooth start / stop)
+ *   sin(PI/2) = 1        → v = X*PI at center (peak speed)
+ *
+ * # Why X = 0.7w (offscreen entry / exit is safe)
+ *
+ * `overlay.xExpr` is an OFFSET on the destination — ffmpeg's overlay
+ * filter does NOT clip the layer to its destination rect. For a
+ * naive flat composition that would mean any sweep wider than the
+ * band's footprint paints onto surrounding canvas content.
+ *
+ * BUT — the gleam in qr-stamp.ts is wrapped in a **nested mosaic**
+ * (see `children["qr_stamp_gleam"]`), so the engine renders the
+ * sweep into an intermediate framebuffer sized exactly to the QR
+ * cell. The framebuffer's finite extent does the clipping for us:
+ * any pixels the band tries to paint past the QR's bounds simply
+ * have no buffer to land in. That makes ±0.7w safe — the band can
+ * enter from fully offscreen-left and exit fully offscreen-right
+ * without leaking onto canvas content.
+ *
+ * At 20° tilt + bandWidthFrac=0.018, the band's full horizontal
+ * footprint is ~80% of sizePx (tilt's `sin(20°)` component dominates).
+ * X=0.7 plus that half-footprint (~0.4) means the band is fully
+ * offscreen at both extremes — clean enter, clean exit, no visible
+ * pop at the enable-gate boundary.
+ *
+ * # Footgun if you copy this pattern elsewhere
+ *
+ * The ±0.7w range is ONLY safe because of the nested-mosaic wrap.
+ * If you remove the nested mosaic and use a flat overlay, the band
+ * will bleed onto surrounding content at the sweep extremes. See
+ * the internal nested-mosaic-clip-pattern notes for the
+ * general pattern.
+ */
+export declare function buildGleamSweepXExpr(periodSec: number, sweepSec: number): string;