@m0saic/templates 0.2.0

package/dist/m0saic/media/qr/code/v1/qr-code.js

@@ -0,0 +1,611 @@
+"use strict";
+/**
+ * @m0saic/media/qr/code/v1 — "QR Code"
+ *
+ * THE standalone QR template — the 2026-07-21/22 merge of the four QR cards
+ * that shared one engine with scattered knobs:
+ *
+ *   - `media/qr/basic/v1` ("Brand QR", deprecated): plain square modules via
+ *     `qrToRenderable` — now the `moduleStyle: "square"` path, byte-identical.
+ *   - `media/qr/rounded/v1` ("Brand QR — Rounded", deprecated): circle /
+ *     rounded-square modules with the 3-layer concentric eye treatment
+ *     (`eyes` channel + `makeQrEyeChildDoc` splice) and an optional carved
+ *     centre asset — now the styled path, byte-identical at its defaults.
+ *   - `media/qr/carve/v1` ("Brand QR — Carve", DELETED 2026-07-22): centre
+ *     media + pixelate spawn — now the `center` group + `animation` group
+ *     (the centre path additionally gains the eye treatment carve never
+ *     had). Deleted rather than archived: no parity anchor and no unique
+ *     consumer survived the fold.
+ *   - `media/qr/animate/v2` ("Brand QR — Spawn", deprecated): spawn → hold →
+ *     fade-out envelope + the caller-SVG hatch — now the `animation` group
+ *     (fade-out opt-in via fadeOutDurMs) + `advanced.svg`; the text path is
+ *     expression-identical.
+ *
+ * Dispatch: `moduleStyle: "square"` with no centre asset and no radius
+ * overrides takes basic's plain path (eyes render as ordinary matrix
+ * modules — the classic look). Any styling or a centre asset takes the
+ * channels path (square style there = radius 0 on modules and eyes). The
+ * spawn animation threads through BOTH paths (per-module rank alpha +
+ * settle offset from the shared animate/v1 expression engine; eyes fade in
+ * first as units; the centre stays visible from t=0), and `advanced.svg`
+ * bypasses QR generation entirely.
+ *
+ * Fully in-house on every QR path: no sharp, no PNG raster — every module
+ * is a lavfi tile in the document's m0.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QrCode = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const brandMCenter_1 = require("../../_shared/brandMCenter");
+const template_utils_1 = require("@m0saic/template-utils");
+// Spawn-animation expression builders — the same animate/v1 engine the
+// deprecated Carve and Spawn templates rode (and the attribution bake uses).
+const expressions_1 = require("../../animate/v1/expressions");
+const BRAND_ORANGE = "#f97316";
+const BG_LIGHT = "#ffffff";
+const BG_DARK = "#000000";
+/** Min version forced when the centre cutout is enabled (ECC H headroom). */
+const CUTOUT_MIN_VERSION = 6;
+const CENTER_CHILD_KEY = "center";
+function resolveCenter(center) {
+    var _a;
+    if (center.show === false)
+        return { kind: "none" };
+    const trimmed = (_a = center.assetPath) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!trimmed)
+        return { kind: "brandM" };
+    return { kind: "asset", path: trimmed };
+}
+const DEFAULTS = {
+    text: "https://www.m0saic.io",
+    mode: "light",
+    moduleColor: BRAND_ORANGE,
+    moduleStyle: "circle",
+    eyeOuterBorderRadius: 0.3,
+    eyeInnerDotBorderRadius: 0.5,
+    centerWidth: 272,
+    centerHeight: 272,
+    centerPaddingPct: 8,
+};
+function defaultModuleBorderRadius(style) {
+    if (style === "circle")
+        return 1.0;
+    if (style === "roundedSquare")
+        return 0.3;
+    return 0;
+}
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    text: {
+        type: "string",
+        required: false,
+        description: "Text to encode (URL, plain string, or structured payload). Defaults to https://www.m0saic.io.",
+        meta: { control: { flavor: "url", placeholder: "https://www.m0saic.io" }, ui: { label: "Text", order: 1 } },
+    },
+    // Reserved prop-bag convention (trickplay/screencap precedent): a prop
+    // named `outputFormat` holding a container name drives the Make page's
+    // Output Type + container + default output extension.
+    outputFormat: {
+        type: "string",
+        required: false,
+        description: 'Deliverable format. "png" renders the static QR image; "mp4" renders the spawn animation (modules pixelate in — tune it under Animation).',
+        meta: { constraints: { oneOf: ["png", "mp4"] }, ui: { label: "Output", order: 2 } },
+    },
+    mode: {
+        type: "string",
+        required: false,
+        description: "Background mode. transparent = alpha PNG for compositing.",
+        meta: { constraints: { oneOf: ["light", "dark", "transparent"] }, ui: { label: "Mode", order: 3 } },
+    },
+    moduleStyle: {
+        type: "string",
+        required: false,
+        description: "Module shape: circle dots (the branded default), roundedSquare, or square (the classic matrix look).",
+        meta: { constraints: { oneOf: ["square", "roundedSquare", "circle"] }, ui: { label: "Module Style", order: 4 } },
+    },
+    moduleColor: {
+        type: "string",
+        required: false,
+        description: "Fill colour for data modules and eye dark layers.",
+        meta: { constraints: { isColor: true }, control: { colorPicker: true, defaultColor: "#f97316" }, ui: { label: "Module Color", order: 5 } },
+    },
+    backgroundColor: {
+        type: "string",
+        required: false,
+        description: "Override the mode-derived background colour.",
+        meta: { constraints: { isColor: true }, control: { placeholder: "by mode", colorPicker: true }, ui: { label: "Background", order: 6 } },
+    },
+    style: {
+        type: "group",
+        required: false,
+        description: "Module/eye corner-radius fine-tuning (styled paths only).",
+        meta: { ui: { label: "Style", order: 7, collapsedByDefault: true } },
+        fields: {
+            moduleBorderRadius: {
+                type: "number", required: false,
+                description: "Override module corner radius (0..1). Default derives from Module Style.",
+                meta: { control: { placeholder: "by module style" }, constraints: { min: 0, max: 1 }, ui: { label: "Module radius" } },
+            },
+            eyeOuterBorderRadius: {
+                type: "number", required: false,
+                description: "Outer eye corner radius (0..1).",
+                meta: { control: { placeholder: "by module style" }, constraints: { min: 0, max: 1 }, ui: { label: "Eye outer radius" } },
+            },
+            eyeInnerDotBorderRadius: {
+                type: "number", required: false,
+                description: "Inner eye dot corner radius (0..1). 1.0 = circular dot.",
+                meta: { control: { placeholder: "by module style" }, constraints: { min: 0, max: 1 }, ui: { label: "Eye dot radius" } },
+            },
+        },
+    },
+    center: {
+        type: "group",
+        required: false,
+        description: "Carved centre asset: your image or video in the middle; modules carve a safe area around it (ECC H + version floor keep it scannable).",
+        meta: { ui: { label: "Center Asset", order: 8, collapsedByDefault: true } },
+        fields: {
+            show: {
+                type: "boolean", required: false,
+                description: "Carve a centre into the QR. Off = plain QR, no cutout. Default on.",
+                meta: { ui: { label: "Show Center" } },
+            },
+            assetPath: {
+                type: "media", required: false,
+                description: "Image or video that fills the centre safe area. Empty = the m0saic M (rendered in-house — no file involved); swap in your own logo path (and update the Text URL).",
+                meta: { control: { picker: "file", accept: ["image", "video"] }, ui: { label: "Asset" } },
+            },
+            width: {
+                type: "number", required: false,
+                description: "Safe-area width in canvas pixels.",
+                meta: { constraints: { min: 32, max: 4096 }, ui: { label: "Width (px)" } },
+            },
+            height: {
+                type: "number", required: false,
+                description: "Safe-area height in canvas pixels.",
+                meta: { constraints: { min: 32, max: 4096 }, ui: { label: "Height (px)" } },
+            },
+            paddingPct: {
+                type: "number", required: false,
+                description: "Padding between modules and the centre frame, % of max dim.",
+                meta: { constraints: { min: 0, max: 49 }, ui: { label: "Padding (%)" } },
+            },
+        },
+    },
+    animation: {
+        type: "group",
+        required: false,
+        description: 'Spawn-animation envelope (active when Output is "mp4"): modules pixelate in with a staggered fade. Size the render duration to at least spawn + fade + hold (+ fade out).',
+        meta: { ui: { label: "Animation", order: 9, collapsedByDefault: true } },
+        fields: {
+            spawnDurMs: {
+                type: "number", required: false,
+                description: "Stagger: time from first to last tile starting its fade-in.",
+                meta: { constraints: { min: 100, max: 60000 }, ui: { label: "Spawn (ms)" } },
+            },
+            tileFadeMs: {
+                type: "number", required: false,
+                description: "Per-tile fade-in duration.",
+                meta: { constraints: { min: 0, max: 10000 }, ui: { label: "Fade (ms)" } },
+            },
+            holdDurMs: {
+                type: "number", required: false,
+                description: "Hold at full alpha before fade-out (used when Fade out > 0).",
+                meta: { constraints: { min: 0, max: 60000 }, ui: { label: "Hold (ms)" } },
+            },
+            fadeOutDurMs: {
+                type: "number", required: false,
+                description: "Global fade-out. 0 = spawn in and hold to the end of the render.",
+                meta: { constraints: { min: 0, max: 10000 }, ui: { label: "Fade out (ms)" } },
+            },
+            tileOffsetPx: {
+                type: "number", required: false,
+                description: "Per-tile pixel offset that decays to 0 during fade-in.",
+                meta: { constraints: { min: 0, max: 100 }, ui: { label: "Settle (px)" } },
+            },
+            gleam: {
+                type: "boolean", required: false,
+                description: "Travelling per-cell shine over the data modules during the hold. Cells dip to a high alpha floor, so the code stays scannable. Eyes and the centre are untouched. Requires Output mp4.",
+                meta: { ui: { label: "Module Gleam" } },
+            },
+        },
+    },
+    advanced: {
+        type: "group",
+        required: false,
+        description: "Escape hatches.",
+        meta: { ui: { label: "Advanced", order: 10, collapsedByDefault: true } },
+        fields: {
+            svg: {
+                type: "string", required: false,
+                description: "Caller-supplied SVG string — bypasses QR generation (testing, non-QR vector content, pre-generated QRs). Styling/center are ignored; animation still applies.",
+                meta: { control: { placeholder: "from Text" }, ui: { label: "SVG string" } },
+            },
+            driftPercent: {
+                type: "number", required: false,
+                description: "Drift tolerance for SVG grid inference (% of min canvas dim).",
+                meta: { constraints: { min: 0, max: 5 }, ui: { label: "Drift %" } },
+            },
+        },
+    },
+    version: {
+        type: "number",
+        required: false,
+        description: "Force QR version (1–40). Default auto; a centre cutout forces ≥6. Bump higher if a printed code fails to scan.",
+        meta: { control: { placeholder: "auto (smallest that fits)" }, constraints: { min: 1, max: 40 }, ui: { label: "QR Version", order: 11 } },
+    },
+});
+const ANIM_DEFAULTS = {
+    spawnDurMs: 1000,
+    tileFadeMs: 220,
+    holdDurMs: 1200,
+    fadeOutDurMs: 0,
+    tileOffsetPx: 1,
+    gleam: false,
+};
+/**
+ * Resolve the animation group to expression-phase seconds. With
+ * `fadeOutDurMs: 0` (the default) the code spawns in and HOLDS forever —
+ * the Carve deliverable semantics (`exitStart` pushed past any real render).
+ * Non-zero fade-out gives the full Spawn envelope: spawn → hold → fade out.
+ */
+function resolveAnimation(cfg, on) {
+    var _a, _b, _c, _d, _e, _g;
+    const spawnDurMs = (_a = cfg === null || cfg === void 0 ? void 0 : cfg.spawnDurMs) !== null && _a !== void 0 ? _a : ANIM_DEFAULTS.spawnDurMs;
+    const tileFadeMs = (_b = cfg === null || cfg === void 0 ? void 0 : cfg.tileFadeMs) !== null && _b !== void 0 ? _b : ANIM_DEFAULTS.tileFadeMs;
+    const holdDurMs = (_c = cfg === null || cfg === void 0 ? void 0 : cfg.holdDurMs) !== null && _c !== void 0 ? _c : ANIM_DEFAULTS.holdDurMs;
+    const fadeOutDurMs = (_d = cfg === null || cfg === void 0 ? void 0 : cfg.fadeOutDurMs) !== null && _d !== void 0 ? _d : ANIM_DEFAULTS.fadeOutDurMs;
+    const spawnDurSec = spawnDurMs / 1000;
+    const tileFadeSec = tileFadeMs / 1000;
+    const holdForever = fadeOutDurMs <= 0;
+    return {
+        on,
+        spawnDurSec,
+        tileFadeSec,
+        exitStartSec: holdForever ? 1e9 : spawnDurSec + tileFadeSec + holdDurMs / 1000,
+        fadeOutSec: holdForever ? 0.001 : fadeOutDurMs / 1000,
+        tileOffsetPx: (_e = cfg === null || cfg === void 0 ? void 0 : cfg.tileOffsetPx) !== null && _e !== void 0 ? _e : ANIM_DEFAULTS.tileOffsetPx,
+        gleam: (_g = cfg === null || cfg === void 0 ? void 0 : cfg.gleam) !== null && _g !== void 0 ? _g : ANIM_DEFAULTS.gleam,
+    };
+}
+/** Per-module spawn overlay (alpha + settle offset) for rank `rank`. */
+function spawnOverlay(anim, rank) {
+    const baseAlpha = (0, expressions_1.buildModuleAlphaExpr)(rank, {
+        spawnDurSec: anim.spawnDurSec,
+        tileFadeSec: anim.tileFadeSec,
+        exitStartSec: anim.exitStartSec,
+        fadeOutSec: anim.fadeOutSec,
+    });
+    // Gleam MULTIPLIES the envelope alpha (animate/v1 discipline), so the
+    // shine only shows during the hold; data modules only — the eye layers
+    // take their own rank-0 path and never gleam.
+    const alpha = anim.gleam
+        ? `(${baseAlpha})*(${(0, expressions_1.buildModuleGleamFactor)(rank)})`
+        : baseAlpha;
+    const offset = (0, expressions_1.buildTileOffsetExpr)(rank, {
+        spawnDurSec: anim.spawnDurSec,
+        tileFadeSec: anim.tileFadeSec,
+        offsetPx: anim.tileOffsetPx,
+    });
+    return { alpha, xExpr: offset, yExpr: offset };
+}
+/** Ranks for the spawn stagger, index-aligned with the m0's logical frames. */
+function ranksForM0(m0, w, h) {
+    const frames = (0, dsl_stdlib_1.queryFrames)(m0, { width: w, height: h }).logical();
+    const tiles = frames.map((f) => ({
+        x: f.x,
+        y: f.y,
+        logicalIndex: f.logicalIndex,
+    }));
+    return (0, expressions_1.buildPseudoRanks)(tiles);
+}
+function backgroundFor(mode, override) {
+    if (override)
+        return override;
+    if (mode === "transparent")
+        return undefined;
+    return mode === "dark" ? BG_DARK : BG_LIGHT;
+}
+exports.QrCode = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/media/qr/code/v1"),
+    label: "QR Code",
+    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: "Scannable QR from any text (URL, plain string, or structured payload). Defaults to the branded look — circle modules on a light card with the m0saic M carved in the centre; swap the centre asset and URL to make it yours. Square/rounded/circle module styles, light/dark/transparent card, optional spawn animation (Output mp4). The one standalone QR template.",
+    capabilities: {
+        tier: "capability",
+        caps: { fs: { read: true, write: true, temp: true } },
+    },
+    tags: ["brand", "qr", "marketers", "designers", "link"],
+    // No `format` hint (screencap precedent): the animation knob picks
+    // png (static) vs mp4 (spawn) per render, and each rendered doc declares
+    // its own container.
+    outputHints: {
+        format: { kind: "image", container: "png" },
+        width: 1080,
+        height: 1080,
+        fps: 30,
+        durationMs: 2000,
+        note: "Square QR rendered as in-house m0 (no PNG raster). Spawn animation renders an mp4. " +
+            "Render at a SQUARE canvas — a non-square canvas stretches the code uniformly " +
+            "(accepted v1 behavior, founder ruling 08-27; no contain letterboxing here). " +
+            "Transparent mode: the card is truly transparent, but a centre child sits on an " +
+            "opaque box until the child-carrier engine candidate lands " +
+            "— use " +
+            "center.show:false for fully transparent output.",
+    },
+    propsSchema,
+    // The branded default look: circle modules on a light card with the
+    // m0saic M carved in the centre (resolved at render — see resolveCenter).
+    // Swap the centre asset + the URL to make it yours.
+    defaultProps: {
+        advanced: { driftPercent: 0 },
+        animation: { spawnDurMs: 1000, tileFadeMs: 220, holdDurMs: 1200, fadeOutDurMs: 0, tileOffsetPx: 1, gleam: false },
+        moduleColor: "#EF7525",
+        text: DEFAULTS.text,
+        outputFormat: "png",
+        mode: DEFAULTS.mode,
+        moduleStyle: DEFAULTS.moduleStyle,
+        // Seeds Make's form so the Show Center toggle starts visibly ON —
+        // the form renders an unset boolean as off, but the M renders by
+        // default; without this seed the toggle would lie.
+        center: { paddingPct: 8, height: 272, width: 272, show: true },
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
+        const text = (_a = props.text) !== null && _a !== void 0 ? _a : DEFAULTS.text;
+        const mode = (_b = props.mode) !== null && _b !== void 0 ? _b : DEFAULTS.mode;
+        const moduleColor = ((_c = props.moduleColor) !== null && _c !== void 0 ? _c : DEFAULTS.moduleColor);
+        const moduleStyle = (_d = props.moduleStyle) !== null && _d !== void 0 ? _d : DEFAULTS.moduleStyle;
+        const style = (_e = props.style) !== null && _e !== void 0 ? _e : {};
+        const center = (_g = props.center) !== null && _g !== void 0 ? _g : {};
+        const centerResolution = resolveCenter(center);
+        const hasCutout = centerResolution.kind !== "none";
+        const bg = backgroundFor(mode, props.backgroundColor);
+        const anim = resolveAnimation(props.animation, ((_h = props.outputFormat) !== null && _h !== void 0 ? _h : "png") === "mp4");
+        // Per-doc container: spawn animation renders a video; static a PNG.
+        // (Each rendered doc declares its own container so the Output pick
+        // follows the knob; the template-level hint mirrors the knob DEFAULT so
+        // a share link at defaults carries no format ask.)
+        const docFormat = anim.on
+            ? { kind: "video", container: "mp4" }
+            : mode === "transparent"
+                ? // Transparent mode MUST ship alpha — without the pixelFormat the
+                    // resolver defaults the PNG to rgb24 and the transparency silently
+                    // flattens to black (gate-22 battery catch; `--alpha` shouldn't be
+                    // required for a mode whose entire point is transparency).
+                    { kind: "image", container: "png", pixelFormat: "rgba" }
+                : { kind: "image", container: "png" };
+        const errTitle = "QR Code";
+        const fail = (err) => (0, template_utils_1.makeErrorMosaic)(`QrCode: ${err instanceof Error ? err.message : String(err)}`, { title: errTitle, width: ctx.target.width, height: ctx.target.height });
+        // ── SVG escape hatch (Spawn heritage): caller geometry, no QR gen ──
+        // Styling/center don't apply (the SVG is its own geometry); mode/bg and
+        // the animation group do.
+        if ((_j = props.advanced) === null || _j === void 0 ? void 0 : _j.svg) {
+            let m0;
+            try {
+                m0 = String((0, dsl_stdlib_1.svgToM0)(props.advanced.svg, {
+                    driftPercent: (_k = props.advanced.driftPercent) !== null && _k !== void 0 ? _k : 0,
+                    packing: "multi",
+                }));
+            }
+            catch (err) {
+                return fail(err);
+            }
+            const frames = (0, dsl_stdlib_1.queryFrames)(m0, {
+                width: ctx.output.width,
+                height: ctx.output.height,
+            }).logical();
+            if (frames.length === 0) {
+                return (0, template_utils_1.makeErrorMosaic)("QrCode: SVG produced no visible tiles.", {
+                    title: errTitle,
+                    width: ctx.target.width,
+                    height: ctx.target.height,
+                });
+            }
+            const ranks = anim.on
+                ? (0, expressions_1.buildPseudoRanks)(frames.map((f) => ({ x: f.x, y: f.y, logicalIndex: f.logicalIndex })))
+                : [];
+            const sources = frames.map((_f, i) => anim.on
+                ? (0, template_utils_1.makeColorTile)(moduleColor, { overlay: spawnOverlay(anim, ranks[i]) })
+                : (0, template_utils_1.makeColorTile)(moduleColor));
+            return {
+                kind: "mosaic_document",
+                version: 1,
+                m0: (0, dsl_stdlib_1.toM0String)(m0, "QrCode"),
+                sources,
+                assets: {},
+                format: docFormat,
+                ...(bg !== undefined ? { backgroundColor: (0, template_utils_1.solidBackground)(bg) } : {}),
+            };
+        }
+        // ── Plain path (basic-v1 heritage, byte-identical) ────────────────
+        // Square modules, no styling overrides, no cutout, no forced version:
+        // the eyes are ordinary matrix modules — the classic brand QR.
+        const isPlain = moduleStyle === "square" &&
+            !hasCutout &&
+            style.moduleBorderRadius === undefined &&
+            style.eyeOuterBorderRadius === undefined &&
+            style.eyeInnerDotBorderRadius === undefined &&
+            !props.version;
+        if (isPlain) {
+            let renderable;
+            try {
+                renderable = (0, template_utils_1.qrToRenderable)({
+                    text,
+                    moduleColor,
+                    errorCorrectionLevel: "H",
+                });
+            }
+            catch (err) {
+                return fail(err);
+            }
+            // Spawn animation: rebuild every module tile with its rank overlay
+            // (all frames are modules on the plain path).
+            let sources = renderable.sources;
+            if (anim.on) {
+                const ranks = ranksForM0(String(renderable.m0), renderable.canvasW, renderable.canvasH);
+                sources = sources.map((_src, i) => (0, template_utils_1.makeColorTile)(moduleColor, { overlay: spawnOverlay(anim, ranks[i]) }));
+            }
+            return {
+                kind: "mosaic_document",
+                version: 1,
+                m0: (0, dsl_stdlib_1.toM0String)(String(renderable.m0), "QrCode"),
+                sources,
+                assets: {},
+                ...(anim.on ? {} : { fps: 30, durationMs: 2000 }),
+                format: docFormat,
+                // `solidBackground` keeps the bg opaque on the rgba PNG output (the
+                // engine's bgFill otherwise defaults alpha-output bgs to transparent).
+                ...(bg !== undefined ? { backgroundColor: (0, template_utils_1.solidBackground)(bg) } : {}),
+            };
+        }
+        // ── Styled path (rounded-v1 heritage, byte-identical at its defaults) ──
+        const moduleBorderRadius = (_l = style.moduleBorderRadius) !== null && _l !== void 0 ? _l : defaultModuleBorderRadius(moduleStyle);
+        const eyeOuterBorderRadius = (_m = style.eyeOuterBorderRadius) !== null && _m !== void 0 ? _m : (moduleStyle === "square" ? 0 : DEFAULTS.eyeOuterBorderRadius);
+        const eyeInnerDotBorderRadius = (_o = style.eyeInnerDotBorderRadius) !== null && _o !== void 0 ? _o : (moduleStyle === "square" ? 0 : DEFAULTS.eyeInnerDotBorderRadius);
+        const safeAreaWidth = (_p = center.width) !== null && _p !== void 0 ? _p : DEFAULTS.centerWidth;
+        const safeAreaHeight = (_q = center.height) !== null && _q !== void 0 ? _q : DEFAULTS.centerHeight;
+        const paddingPct = (_r = center.paddingPct) !== null && _r !== void 0 ? _r : DEFAULTS.centerPaddingPct;
+        // Version: caller wins; a cutout floors at V6 for post-carve scannability.
+        const resolvedVersion = props.version && props.version > 0
+            ? props.version
+            : hasCutout
+                ? CUTOUT_MIN_VERSION
+                : undefined;
+        // The eyes channel needs a concrete background for its light layers even
+        // in transparent mode.
+        const eyeBackground = bg !== null && bg !== void 0 ? bg : (mode === "dark" ? BG_DARK : BG_LIGHT);
+        let qr;
+        try {
+            qr = (0, template_utils_1.qrToRenderable)({
+                text,
+                moduleColor,
+                errorCorrectionLevel: "H",
+                backgroundColor: eyeBackground,
+                eyes: {
+                    darkColor: moduleColor,
+                    outerBorderRadius: eyeOuterBorderRadius,
+                    innerLightBorderRadius: eyeOuterBorderRadius,
+                    innerDotBorderRadius: eyeInnerDotBorderRadius,
+                },
+                ...(resolvedVersion ? { version: resolvedVersion } : {}),
+                ...(hasCutout
+                    ? {
+                        safeArea: {
+                            width: safeAreaWidth,
+                            height: safeAreaHeight,
+                            paddingPct,
+                        },
+                    }
+                    : {}),
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+        if (qr.sources.length === 0) {
+            return (0, template_utils_1.makeErrorMosaic)("QrCode: composed QR has no renderable frames.", {
+                title: errTitle,
+                width: ctx.target.width,
+                height: ctx.target.height,
+            });
+        }
+        // Source order from the eye-splice mode:
+        //   [0..dataEnd)          data-cell tiles (re-styled below)
+        //   [dataEnd..dataEnd+9)  3 eye-child-doc sources per finder (pre-styled)
+        //   [last]                optional safe-area splice
+        const eyeBlockCount = ((_t = (_s = qr.channelByRole.eyes) === null || _s === void 0 ? void 0 : _s.frames.length) !== null && _t !== void 0 ? _t : 0) * 3;
+        const safeAreaCount = hasCutout && qr.safeAreaStableKey ? 1 : 0;
+        const dataCellEnd = qr.sources.length - eyeBlockCount - safeAreaCount;
+        // Spawn ranks over the final m0 (index-aligned with sources). Eyes get
+        // rank 0 — each finder fades in as a unit, first, so the code reads
+        // immediately (the animate/v1 eye discipline); the centre stays visible
+        // from t=0 (the Carve discipline).
+        const ranks = anim.on ? ranksForM0(String(qr.m0), qr.canvasW, qr.canvasH) : [];
+        const sources = qr.sources.map((src, i) => {
+            var _a;
+            if (i < dataCellEnd) {
+                return (0, template_utils_1.makeColorTile)(moduleColor, {
+                    effects: {
+                        rounding: {
+                            borderRadius: moduleBorderRadius,
+                            cornerStyle: "rounded",
+                        },
+                    },
+                    ...(anim.on ? { overlay: spawnOverlay(anim, ranks[i]) } : {}),
+                });
+            }
+            if (i >= qr.sources.length - safeAreaCount) {
+                return {
+                    type: "mosaic",
+                    ref: CENTER_CHILD_KEY,
+                    placement: { fit: "contain" },
+                };
+            }
+            // Eye block: qrToRenderable's pre-styled layers; under spawn they fade
+            // in as a unit at rank 0 (alpha only — no settle offset on the eyes).
+            if (anim.on) {
+                const eyeAlpha = (0, expressions_1.buildModuleAlphaExpr)(0, {
+                    spawnDurSec: anim.spawnDurSec,
+                    tileFadeSec: anim.tileFadeSec,
+                    exitStartSec: anim.exitStartSec,
+                    fadeOutSec: anim.fadeOutSec,
+                });
+                return {
+                    ...src,
+                    overlay: { ...((_a = src.overlay) !== null && _a !== void 0 ? _a : {}), alpha: eyeAlpha },
+                };
+            }
+            return src;
+        });
+        const children = {};
+        if (centerResolution.kind === "asset") {
+            const centerAssetId = (0, types_1.asAssetId)("qr_code_center");
+            const centerMediaType = (0, template_utils_1.determineMediaType)(centerResolution.path, ctx);
+            children[CENTER_CHILD_KEY] = {
+                kind: "mosaic_document",
+                version: 1,
+                m0: (0, dsl_stdlib_1.toM0String)("F", "QrCode-center"),
+                assets: {
+                    [centerAssetId]: {
+                        kind: "file",
+                        path: centerResolution.path,
+                        mediaType: centerMediaType,
+                    },
+                },
+                sources: [
+                    {
+                        type: "media",
+                        mediaType: centerMediaType,
+                        assetId: centerAssetId,
+                        placement: { fit: "contain" },
+                    },
+                ],
+                size: { width: safeAreaWidth, height: safeAreaHeight },
+            };
+        }
+        else if (centerResolution.kind === "brandM") {
+            children[CENTER_CHILD_KEY] = (0, brandMCenter_1.buildBrandMCenterDoc)({
+                mColor: moduleColor,
+                bgColor: bg,
+                width: safeAreaWidth,
+                height: safeAreaHeight,
+            });
+        }
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            m0: (0, dsl_stdlib_1.toM0String)(String(qr.m0), "QrCode"),
+            sources,
+            assets: {},
+            children,
+            size: { width: qr.canvasW, height: qr.canvasH },
+            format: docFormat,
+            ...(bg !== undefined ? { backgroundColor: (0, template_utils_1.solidBackground)(bg) } : {}),
+        };
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.QrCode);
+exports.default = exports.QrCode;

package/dist/m0saic/media/qr/index.d.ts

@@ -0,0 +1,7 @@
+export { QrCode } from "./code/v1";
+export { BrandQr } from "./basic/v1";
+export { QrAnimate } from "./animate/v1";
+export { QrAnimateV2 } from "./animate/v2";
+export { QrRounded } from "./rounded/v1";
+export { QrStampCustom } from "./stamp/v1/qr-stamp-custom";
+export { QrStampVideo } from "./stamp-video/v1";

package/dist/m0saic/media/qr/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QrStampVideo = exports.QrStampCustom = exports.QrRounded = exports.QrAnimateV2 = exports.QrAnimate = exports.BrandQr = exports.QrCode = void 0;
+/* media/qr — the user-facing QR pack (moved from brand/ 2026-07-21; the
+ * brand/ pack keeps only the internal QR Brand Attribution pair). */
+var v1_1 = require("./code/v1");
+Object.defineProperty(exports, "QrCode", { enumerable: true, get: function () { return v1_1.QrCode; } });
+var v1_2 = require("./basic/v1");
+Object.defineProperty(exports, "BrandQr", { enumerable: true, get: function () { return v1_2.BrandQr; } });
+var v1_3 = require("./animate/v1");
+Object.defineProperty(exports, "QrAnimate", { enumerable: true, get: function () { return v1_3.QrAnimate; } });
+var v2_1 = require("./animate/v2");
+Object.defineProperty(exports, "QrAnimateV2", { enumerable: true, get: function () { return v2_1.QrAnimateV2; } });
+var v1_4 = require("./rounded/v1");
+Object.defineProperty(exports, "QrRounded", { enumerable: true, get: function () { return v1_4.QrRounded; } });
+var qr_stamp_custom_1 = require("./stamp/v1/qr-stamp-custom");
+Object.defineProperty(exports, "QrStampCustom", { enumerable: true, get: function () { return qr_stamp_custom_1.QrStampCustom; } });
+var v1_5 = require("./stamp-video/v1");
+Object.defineProperty(exports, "QrStampVideo", { enumerable: true, get: function () { return v1_5.QrStampVideo; } });

package/dist/m0saic/media/qr/rounded/v1/index.d.ts

@@ -0,0 +1 @@
+export { QrRounded, default } from "./qr-rounded";

package/dist/m0saic/media/qr/rounded/v1/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.QrRounded = void 0;
+var qr_rounded_1 = require("./qr-rounded");
+Object.defineProperty(exports, "QrRounded", { enumerable: true, get: function () { return qr_rounded_1.QrRounded; } });
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(qr_rounded_1).default; } });