@m0saic/templates 0.2.0

package/dist/m0saic/media/qr/animate/v1/expressions.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Pure expression builders for the brand QR spawn-in animation.
+ *
+ * All builders return ffmpeg-evaluator-compatible strings using `t`
+ * (global wall-clock seconds). No filesystem, no random state —
+ * fully deterministic from inputs.
+ */
+/** Tile geometry slice consumed by ranking. */
+export type RankInputTile = {
+    /** Tile's top-left x in canvas pixels. */
+    x: number;
+    /** Tile's top-left y in canvas pixels. */
+    y: number;
+    /** DFS-order index of this visible tile — used to break ties deterministically. */
+    logicalIndex: number;
+};
+/**
+ * Build percentile ranks (0..1) for a set of tiles using a diagonal sweep
+ * score `(x + y)`. The tile closest to (0, 0) gets rank 0; the tile
+ * farthest along the diagonal gets rank 1. Ties on the same diagonal are
+ * broken by ascending `x`, then by ascending `logicalIndex` — both stable
+ * across runs.
+ *
+ * Returned array is aligned with the input: `ranks[i]` is the rank of
+ * `tiles[i]`. So callers can keep tiles in their original DFS order when
+ * emitting sources and just look up the rank by source index.
+ */
+export declare function buildDiagonalRanks(tiles: ReadonlyArray<RankInputTile>): number[];
+export type SpawnTimingParams = {
+    /** Total seconds from rank-0 tile starting its fade to rank-1 tile starting its fade. */
+    spawnDurSec: number;
+    /** Per-tile fade duration in seconds (each tile's 0→1 ramp). */
+    tileFadeSec: number;
+};
+/**
+ * Smoothstep-eased fade-in alpha for a single tile.
+ *
+ * Returns an expression in `[0, 1]`:
+ *   - 0 for `t < rank * spawnDurSec`
+ *   - smoothstep((t - startSec) / tileFadeSec) for the ramp
+ *   - 1 once the tile's local progress reaches 1
+ *
+ * Smoothstep gives the entrance a softer, "premium watch" feel vs. a
+ * raw linear ramp — matches the convention used by `buildEntranceExpr`
+ * in `qr-stamp/video/v1/expressions.ts`.
+ */
+export declare function buildTileAlphaExpr(rank: number, params: SpawnTimingParams): string;
+export type OffsetParams = SpawnTimingParams & {
+    /** Pixel offset the tile starts from (positive = down/right). Decays to 0 over `tileFadeSec`. */
+    offsetPx: number;
+};
+/**
+ * Pixelate-in rank: each tile gets a deterministic-but-shuffled rank in
+ * [0, 1] based on a hash of its `logicalIndex`. Unlike the diagonal
+ * sweep, this produces a "noise resolving to image" feel — tiles appear
+ * scattered across the canvas, all converging at the same end-time.
+ *
+ * Uses a simple integer-hash (Knuth's multiplicative) → normalized.
+ * Stable for a given logicalIndex; no randomness, no seed needed
+ * (the logicalIndex itself acts as the seed input).
+ */
+export declare function buildPseudoRanks(tiles: ReadonlyArray<RankInputTile>): number[];
+export type ModulePhaseParams = SpawnTimingParams & {
+    /** Wall-clock seconds when the idle phase ends and fade-out begins. */
+    exitStartSec: number;
+    /** Smoothstep fade-out duration in seconds. */
+    fadeOutSec: number;
+};
+/**
+ * Full-timeline alpha for a module tile:
+ *
+ * 1. **Spawn** (`rank·spawnDurSec ≤ t < rank·spawnDurSec + tileFadeSec`):
+ *    smoothstep 0 → 1.
+ * 2. **Hold** (until `exitStartSec`): 1.
+ * 3. **Exit** (`exitStartSec ≤ t < exitStartSec + fadeOutSec`):
+ *    smoothstep 1 → 0.
+ * 4. After: 0.
+ *
+ * One expression, three phases. The exit gate is built with `if(lt(t,...))`
+ * so the spawn smoothstep is never evaluated during the exit (avoids
+ * floating-point surprises near the boundary).
+ */
+export declare function buildModuleAlphaExpr(rank: number, params: ModulePhaseParams): string;
+/** Tuning for the optional per-cell QR-module gleam. */
+export type ModuleGleamParams = {
+    /** Seconds for the shimmer band to sweep once through rank space. */
+    sweepSec?: number;
+    /** Floor alpha between band passes — keeps modules legible/scannable. */
+    minAlpha?: number;
+    /** Band width in rank space (0..1). */
+    width?: number;
+};
+/**
+ * Per-cell "gleam" factor in `[minAlpha, 1]` for a QR module cell — a travelling
+ * shine. A shimmer band sweeps through rank space; the cell the band is over
+ * reaches 1, the rest sit at `minAlpha`. MULTIPLY a module's base alpha by this
+ * for a premium per-cell gleam (same shape as the brand-M loading shimmer, but
+ * generic — works for any QR since rank comes from the module's own position).
+ *
+ * `minAlpha` stays high so the QR remains scannable; and because each cell only
+ * dips while the band is elsewhere, any contrast loss is transient (a few
+ * frames), so a sparing gleam doesn't break scanning. Cyclic wrap distance
+ * (the p±1 terms) makes the sweep seamless across the rank-space boundary.
+ */
+export declare function buildModuleGleamFactor(rank: number, params?: ModuleGleamParams): string;
+export type MTilePhaseParams = {
+    /** Wall-clock seconds when the M phase begins (modulesEnd + mDelay). */
+    mStartSec: number;
+    /** Total M entrance window in seconds (all 33 tiles converge by `mStartSec + mInDurSec`). */
+    mInDurSec: number;
+    /** Per-tile entrance smoothstep duration in seconds. */
+    mTileFadeSec: number;
+    /** Loading-UI base breathing — minimum alpha. */
+    baseMin: number;
+    /** Loading-UI base breathing — maximum alpha. */
+    baseMax: number;
+    /** Loading-UI base breathing — cycle period (sec). */
+    basePulseSec: number;
+    /** Loading-UI shimmer sweep — cycle period (sec). */
+    shimmerSec: number;
+    /** Loading-UI shimmer band width — fraction of the rank axis (0..1). */
+    shimmerWidth: number;
+    /** Loading-UI shimmer amplitude — how much the band boosts a tile (0..1). */
+    shimmerAmp: number;
+    /** Wall-clock seconds when the idle phase ends and fade-out begins. */
+    exitStartSec: number;
+    /** Smoothstep fade-out duration in seconds. */
+    fadeOutSec: number;
+};
+/**
+ * Full-timeline alpha for a single M-rect tile.
+ *
+ * Combines three phases in one expression, switched by `if(lt(t, ...))`:
+ *
+ * 1. **M entrance** (`mStartSec + rank·(mInDurSec - mTileFadeSec) ≤ t <
+ *    + mTileFadeSec`): smoothstep 0 → loading-base-peak. Per-rank
+ *    staggered so the M assembles "rect by rect" — exactly the editor's
+ *    loading-shimmer aesthetic.
+ *
+ * 2. **Loading-UI idle** (`mInEndSec ≤ t < exitStartSec`): base breathing
+ *    (cos pulse) plus a rank-aware shimmer band sweeping across the
+ *    33 rects. Each rect carries its own phase offset via its rank,
+ *    so the 33 rects animate independently. Replicates
+ *    `buildLoadingUiAlphaExpr` from `brand/logo/v3` verbatim.
+ *
+ * 3. **Exit** (`exitStartSec ≤ t < exitStartSec + fadeOutSec`):
+ *    smoothstep loading-alpha → 0.
+ *
+ * Before `mStartSec` the entrance smoothstep clamps to 0. After
+ * `exitStartSec + fadeOutSec` everything clamps to 0.
+ */
+export declare function buildMTileAlphaExpr(rank: number, params: MTilePhaseParams): string;
+/**
+ * Per-tile pixel-offset expression for the entrance settle.
+ *
+ * Returns `offsetPx * (1 - smoothstep(u))` where `u` is the same clamped
+ * progress used by {@link buildTileAlphaExpr}. So the tile starts shifted
+ * `offsetPx` pixels and eases back to 0 by the time it finishes fading in.
+ *
+ * The same expression works for both `xExpr` and `yExpr` — callers pass
+ * positive `offsetPx` to start down/right and decay to the tile's natural
+ * position.
+ */
+export declare function buildTileOffsetExpr(rank: number, params: OffsetParams): string;

package/dist/m0saic/media/qr/animate/v1/expressions.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Pure expression builders for the brand QR spawn-in animation.
+ *
+ * All builders return ffmpeg-evaluator-compatible strings using `t`
+ * (global wall-clock seconds). No filesystem, no random state —
+ * fully deterministic from inputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDiagonalRanks = buildDiagonalRanks;
+exports.buildTileAlphaExpr = buildTileAlphaExpr;
+exports.buildPseudoRanks = buildPseudoRanks;
+exports.buildModuleAlphaExpr = buildModuleAlphaExpr;
+exports.buildModuleGleamFactor = buildModuleGleamFactor;
+exports.buildMTileAlphaExpr = buildMTileAlphaExpr;
+exports.buildTileOffsetExpr = buildTileOffsetExpr;
+/**
+ * Format a number to 3 decimal places for deterministic expression output.
+ * Keeps the rendered expressions byte-identical across runs.
+ * (Same shape as `fixed()` in the qr-stamp video expressions.)
+ */
+function fixed(n) {
+    return n.toFixed(3);
+}
+/**
+ * Build percentile ranks (0..1) for a set of tiles using a diagonal sweep
+ * score `(x + y)`. The tile closest to (0, 0) gets rank 0; the tile
+ * farthest along the diagonal gets rank 1. Ties on the same diagonal are
+ * broken by ascending `x`, then by ascending `logicalIndex` — both stable
+ * across runs.
+ *
+ * Returned array is aligned with the input: `ranks[i]` is the rank of
+ * `tiles[i]`. So callers can keep tiles in their original DFS order when
+ * emitting sources and just look up the rank by source index.
+ */
+function buildDiagonalRanks(tiles) {
+    const n = tiles.length;
+    if (n === 0)
+        return [];
+    if (n === 1)
+        return [0];
+    // Build a sort order with input-index attached so we can scatter back.
+    const order = tiles.map((t, i) => ({ i, t }));
+    order.sort((a, b) => {
+        const sa = a.t.x + a.t.y;
+        const sb = b.t.x + b.t.y;
+        if (sa !== sb)
+            return sa - sb;
+        if (a.t.x !== b.t.x)
+            return a.t.x - b.t.x;
+        return a.t.logicalIndex - b.t.logicalIndex;
+    });
+    const ranks = new Array(n);
+    for (let pos = 0; pos < n; pos += 1) {
+        // Even spread across [0, 1] — first tile rank 0, last tile rank 1.
+        ranks[order[pos].i] = pos / (n - 1);
+    }
+    return ranks;
+}
+/**
+ * Smoothstep-eased fade-in alpha for a single tile.
+ *
+ * Returns an expression in `[0, 1]`:
+ *   - 0 for `t < rank * spawnDurSec`
+ *   - smoothstep((t - startSec) / tileFadeSec) for the ramp
+ *   - 1 once the tile's local progress reaches 1
+ *
+ * Smoothstep gives the entrance a softer, "premium watch" feel vs. a
+ * raw linear ramp — matches the convention used by `buildEntranceExpr`
+ * in `qr-stamp/video/v1/expressions.ts`.
+ */
+function buildTileAlphaExpr(rank, params) {
+    const startSec = rank * params.spawnDurSec;
+    const fadeSec = Math.max(0.001, params.tileFadeSec);
+    // u = clamp((t - startSec) / fadeSec, 0, 1)
+    const u = `min(1,max(0,(t-${fixed(startSec)})/${fixed(fadeSec)}))`;
+    // smoothstep(u) = u² * (3 - 2u)
+    return `(${u}*${u}*(3-2*${u}))`;
+}
+/**
+ * Pixelate-in rank: each tile gets a deterministic-but-shuffled rank in
+ * [0, 1] based on a hash of its `logicalIndex`. Unlike the diagonal
+ * sweep, this produces a "noise resolving to image" feel — tiles appear
+ * scattered across the canvas, all converging at the same end-time.
+ *
+ * Uses a simple integer-hash (Knuth's multiplicative) → normalized.
+ * Stable for a given logicalIndex; no randomness, no seed needed
+ * (the logicalIndex itself acts as the seed input).
+ */
+function buildPseudoRanks(tiles) {
+    const n = tiles.length;
+    if (n === 0)
+        return [];
+    if (n === 1)
+        return [0];
+    // Score each tile by Knuth's multiplicative hash on logicalIndex.
+    // Spread is uniform mod 2^32 — good enough for visually-random ordering.
+    const KNUTH = 2654435761;
+    const order = tiles.map((t, i) => ({
+        i,
+        score: ((t.logicalIndex * KNUTH) >>> 0) / 0x100000000,
+        logicalIndex: t.logicalIndex,
+    }));
+    order.sort((a, b) => {
+        if (a.score !== b.score)
+            return a.score - b.score;
+        return a.logicalIndex - b.logicalIndex;
+    });
+    const ranks = new Array(n);
+    for (let pos = 0; pos < n; pos += 1) {
+        ranks[order[pos].i] = pos / (n - 1);
+    }
+    return ranks;
+}
+/**
+ * Full-timeline alpha for a module tile:
+ *
+ * 1. **Spawn** (`rank·spawnDurSec ≤ t < rank·spawnDurSec + tileFadeSec`):
+ *    smoothstep 0 → 1.
+ * 2. **Hold** (until `exitStartSec`): 1.
+ * 3. **Exit** (`exitStartSec ≤ t < exitStartSec + fadeOutSec`):
+ *    smoothstep 1 → 0.
+ * 4. After: 0.
+ *
+ * One expression, three phases. The exit gate is built with `if(lt(t,...))`
+ * so the spawn smoothstep is never evaluated during the exit (avoids
+ * floating-point surprises near the boundary).
+ */
+function buildModuleAlphaExpr(rank, params) {
+    const { spawnDurSec, tileFadeSec, exitStartSec, fadeOutSec } = params;
+    const startSec = rank * spawnDurSec;
+    const fadeSec = Math.max(0.001, tileFadeSec);
+    const exitFade = Math.max(0.001, fadeOutSec);
+    // Spawn smoothstep.
+    const u = `min(1,max(0,(t-${fixed(startSec)})/${fixed(fadeSec)}))`;
+    const spawn = `(${u}*${u}*(3-2*${u}))`;
+    // Exit smoothstep — reverses to 0 as t crosses exitStartSec.
+    const v = `min(1,max(0,(t-${fixed(exitStartSec)})/${fixed(exitFade)}))`;
+    const exit = `(1-(${v}*${v}*(3-2*${v})))`;
+    // Multiply: spawn fades in, exit fades back out. Both clamped, so they
+    // hold at 1 during the middle.
+    return `(${spawn})*(${exit})`;
+}
+const GLEAM_DEFAULTS = { sweepSec: 2.4, minAlpha: 0.82, width: 0.22 };
+/**
+ * Per-cell "gleam" factor in `[minAlpha, 1]` for a QR module cell — a travelling
+ * shine. A shimmer band sweeps through rank space; the cell the band is over
+ * reaches 1, the rest sit at `minAlpha`. MULTIPLY a module's base alpha by this
+ * for a premium per-cell gleam (same shape as the brand-M loading shimmer, but
+ * generic — works for any QR since rank comes from the module's own position).
+ *
+ * `minAlpha` stays high so the QR remains scannable; and because each cell only
+ * dips while the band is elsewhere, any contrast loss is transient (a few
+ * frames), so a sparing gleam doesn't break scanning. Cyclic wrap distance
+ * (the p±1 terms) makes the sweep seamless across the rank-space boundary.
+ */
+function buildModuleGleamFactor(rank, params = {}) {
+    var _a, _b, _c;
+    const sweepSec = Math.max(0.1, (_a = params.sweepSec) !== null && _a !== void 0 ? _a : GLEAM_DEFAULTS.sweepSec);
+    const minAlpha = Math.max(0, Math.min(1, (_b = params.minAlpha) !== null && _b !== void 0 ? _b : GLEAM_DEFAULTS.minAlpha));
+    const width = Math.max(0.01, (_c = params.width) !== null && _c !== void 0 ? _c : GLEAM_DEFAULTS.width);
+    const p = `mod(t,${fixed(sweepSec)})/${fixed(sweepSec)}`;
+    const halfW = `(${fixed(width)}/2)`;
+    const d0 = `abs(${fixed(rank)}-(${p}))`;
+    const d1 = `abs(${fixed(rank)}-((${p})-1))`;
+    const d2 = `abs(${fixed(rank)}-((${p})+1))`;
+    const d = `min(min(${d0},${d1}),${d2})`;
+    const u = `max(min(1-(${d})/(${halfW}),1),0)`;
+    const band = `(${u})*(${u})*(3-2*(${u}))`;
+    return `(${fixed(minAlpha)}+(1-${fixed(minAlpha)})*${band})`;
+}
+/**
+ * Full-timeline alpha for a single M-rect tile.
+ *
+ * Combines three phases in one expression, switched by `if(lt(t, ...))`:
+ *
+ * 1. **M entrance** (`mStartSec + rank·(mInDurSec - mTileFadeSec) ≤ t <
+ *    + mTileFadeSec`): smoothstep 0 → loading-base-peak. Per-rank
+ *    staggered so the M assembles "rect by rect" — exactly the editor's
+ *    loading-shimmer aesthetic.
+ *
+ * 2. **Loading-UI idle** (`mInEndSec ≤ t < exitStartSec`): base breathing
+ *    (cos pulse) plus a rank-aware shimmer band sweeping across the
+ *    33 rects. Each rect carries its own phase offset via its rank,
+ *    so the 33 rects animate independently. Replicates
+ *    `buildLoadingUiAlphaExpr` from `brand/logo/v3` verbatim.
+ *
+ * 3. **Exit** (`exitStartSec ≤ t < exitStartSec + fadeOutSec`):
+ *    smoothstep loading-alpha → 0.
+ *
+ * Before `mStartSec` the entrance smoothstep clamps to 0. After
+ * `exitStartSec + fadeOutSec` everything clamps to 0.
+ */
+function buildMTileAlphaExpr(rank, params) {
+    const { mStartSec, mInDurSec, mTileFadeSec, baseMin, baseMax, basePulseSec, shimmerSec, shimmerWidth, shimmerAmp, exitStartSec, fadeOutSec, } = params;
+    // ── Entrance: per-rank staggered smoothstep into loading-baseline ──
+    // Each rect's start = mStartSec + rank * (mInDurSec - mTileFadeSec)
+    // so the last rect just finishes by mInDurSec.
+    const tileFade = Math.max(0.001, mTileFadeSec);
+    const stagger = Math.max(0, mInDurSec - tileFade);
+    const entStart = mStartSec + rank * stagger;
+    const u = `min(1,max(0,(t-${fixed(entStart)})/${fixed(tileFade)}))`;
+    const entrance = `(${u}*${u}*(3-2*${u}))`;
+    // ── Loading-UI idle (verbatim from brand/logo/v3 buildLoadingUiAlphaExpr) ──
+    // base = baseMin + (baseMax - baseMin) * 0.5 * (1 - cos(2*PI*t/basePulseSec))
+    const base = `(${fixed(baseMin)})+(${fixed(baseMax)}-${fixed(baseMin)})*0.5*` +
+        `(1-cos(2*PI*t/${fixed(Math.max(0.01, basePulseSec))}))`;
+    // shimmer center p ∈ [0..1)
+    const p = `mod(t,${fixed(Math.max(0.01, shimmerSec))})/${fixed(Math.max(0.01, shimmerSec))}`;
+    const halfW = `(${fixed(Math.max(0.001, shimmerWidth))}/2)`;
+    // wrap distance (handles cyclic rank space)
+    const d0 = `abs(${fixed(rank)}-(${p}))`;
+    const d1 = `abs(${fixed(rank)}-((${p})-1))`;
+    const d2 = `abs(${fixed(rank)}-((${p})+1))`;
+    const d = `min(min(${d0},${d1}),${d2})`;
+    // band strength: u' = clamp(1 - d/halfW, 0, 1)
+    const u2 = `max(min(1-(${d})/(${halfW}),1),0)`;
+    // smoothstep(u') for soft band edges
+    const band = `(${u2})*(${u2})*(3-2*(${u2}))`;
+    const hi = `(${fixed(shimmerAmp)})*${band}`;
+    const loadingAlpha = `max(min((${base})+(${hi}),1),0)`;
+    // ── Exit smoothstep: loading → 0 ──
+    const v = `min(1,max(0,(t-${fixed(exitStartSec)})/${fixed(Math.max(0.001, fadeOutSec))}))`;
+    const exitFactor = `(1-(${v}*${v}*(3-2*${v})))`;
+    // Entrance phase ramps the loading alpha in. We compute the COMBINED
+    // value as entrance * loadingAlpha — during the entrance, loadingAlpha
+    // is whatever it is at that moment, and entrance scales it from 0 to 1.
+    // After entrance completes (u = 1), entrance = 1, so we get pure
+    // loadingAlpha. Exit multiplies the whole thing down to 0.
+    return `(${entrance})*(${loadingAlpha})*${exitFactor}`;
+}
+/**
+ * Per-tile pixel-offset expression for the entrance settle.
+ *
+ * Returns `offsetPx * (1 - smoothstep(u))` where `u` is the same clamped
+ * progress used by {@link buildTileAlphaExpr}. So the tile starts shifted
+ * `offsetPx` pixels and eases back to 0 by the time it finishes fading in.
+ *
+ * The same expression works for both `xExpr` and `yExpr` — callers pass
+ * positive `offsetPx` to start down/right and decay to the tile's natural
+ * position.
+ */
+function buildTileOffsetExpr(rank, params) {
+    if (params.offsetPx === 0)
+        return "0";
+    const startSec = rank * params.spawnDurSec;
+    const fadeSec = Math.max(0.001, params.tileFadeSec);
+    const u = `min(1,max(0,(t-${fixed(startSec)})/${fixed(fadeSec)}))`;
+    const smooth = `(${u}*${u}*(3-2*${u}))`;
+    return `(${fixed(params.offsetPx)}*(1-${smooth}))`;
+}

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

@@ -0,0 +1,2 @@
+export { QrAnimate, default } from "./qr-animate";
+export type { QrAnimateProps } from "./qr-animate";

package/dist/m0saic/media/qr/animate/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.QrAnimate = void 0;
+var qr_animate_1 = require("./qr-animate");
+Object.defineProperty(exports, "QrAnimate", { enumerable: true, get: function () { return qr_animate_1.QrAnimate; } });
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(qr_animate_1).default; } });

package/dist/m0saic/media/qr/animate/v1/qr-animate.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @m0saic/media/qr/animate/v1
+ *
+ * Deterministic two-phase animation for the m0saic brand QR.
+ *
+ * **Phase 1 — modules** (always): every visible module tile fades + settles
+ * into place on a diagonal TL→BR stagger.
+ *
+ * **Phase 2 — M region** (when `qrLabels` includes a label whose text
+ * matches {@link QrAnimateProps.centreLabel}): the labeled cell hosts a
+ * nested sub-doc rendering the canonical m0saic M (from the
+ * `brand/m-33` dictionary entry, masked per its rank tiles). The M
+ * smoothstep-fades in after modules complete, then breathes gently as a
+ * passive idle while the QR is held.
+ *
+ * When labels are absent or no label matches `centreLabel`, the template
+ * degrades to Phase-1-only behavior: every visible cell renders as a
+ * module tile.
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+export type QrAnimateProps = {
+    /**
+     * The m0 string describing the QR layout. Required.
+     * Plain m0 or the m0 field of an m0c file.
+     */
+    qrM0?: string;
+    /**
+     * Optional m0c labels map (`stableKey → { text, color? }`) used to
+     * locate the centre safe-area cell. When provided AND a label's `text`
+     * matches {@link centreLabel}, that cell hosts the M sub-doc. When
+     * absent, the template renders modules only.
+     *
+     * Typical call site: `qrLabels: registry.byId["brand/qr"].labels`.
+     */
+    qrLabels?: Record<string, {
+        text: string;
+        color?: string;
+    }>;
+    /** Time (ms) from rank-0 tile starting its fade to rank-1 tile starting its fade. */
+    spawnDurMs?: number;
+    /** Per-tile fade-in duration (ms). Each tile takes this long to go 0→1. */
+    tileFadeMs?: number;
+    /**
+     * Idle duration (ms) — how long the M holds in its loading-UI breathing
+     * phase after entrance, before the global fade-out starts. Modules sit
+     * at full alpha during this window.
+     */
+    idleDurMs?: number;
+    /**
+     * Global fade-out duration (ms). Every visible tile (modules + M)
+     * smoothstep-fades to 0 over this window. Lets the rendered asset be
+     * dropped into a stamp pipeline that resizes / time-warps it without
+     * having to author the entrance / exit separately.
+     */
+    fadeOutDurMs?: number;
+    /**
+     * Pixel offset (down + right) each tile starts from, decays to 0 by
+     * the time the tile finishes fading in. 1–2 px reads as "luxury watch";
+     * >3 starts to feel ad-like.
+     */
+    tileOffsetPx?: number;
+    /**
+     * Brand variant selecting the canvas background:
+     * - `"light"` → white background (the default; contrast against dark scenes when stamped).
+     * - `"dark"`  → black background (contrast against light scenes).
+     *
+     * Modules and the centre M stay brand orange in both variants. Override
+     * via {@link bgColor} when you need a custom plate.
+     */
+    variant?: "light" | "dark";
+    /**
+     * Solid background colour. Overrides {@link variant}'s default.
+     * Use `"none"` for a transparent base (caller composites their own plate).
+     */
+    bgColor?: MosaicColor;
+    /** Solid colour for module tiles (brand orange by default). */
+    tileColor?: MosaicColor;
+    /** Solid colour for the centre M region (brand orange by default). */
+    mColor?: MosaicColor;
+    /**
+     * Gap (ms) between the last module finishing its fade and the M
+     * starting its entrance. Small (~200ms) so the QR doesn't feel laggy.
+     */
+    mDelayMs?: number;
+    /** M entrance window (ms) — all 33 rects converge by `mDelayMs + mInDurMs`. */
+    mInDurMs?: number;
+    /**
+     * Per-rect smoothstep duration during the M's staggered entrance (ms).
+     * Together with `mInDurMs` and the rank set, controls how "assembled"
+     * the rect arrival feels.
+     */
+    mTileFadeMs?: number;
+    /**
+     * Label text identifying the centre safe-area cell in `qrLabels`.
+     * Defaults to `"safe-area"`. No-op when `qrLabels` is absent.
+     */
+    centreLabel?: string;
+    /**
+     * Optional per-cell gleam over the QR MODULE cells — a travelling shine
+     * (same shimmer shape as the M, but ranked over the modules). Off by
+     * default. Stacks under the M's own gleam. Used by the qr-stamp seed bake.
+     */
+    gleam?: boolean;
+    /**
+     * Human-readable URL label rendered in a strip beneath the QR.
+     * Lets viewers reach m0saic.io even when they can't scan the QR
+     * (e.g. watching a video on the same device they'd scan from).
+     *
+     * Activated when the rendering context's canvas is taller than
+     * wide: `ctx.output.height > ctx.output.width`. The QR fills the
+     * top `canvasWidth × canvasWidth` square; the URL strip fills the
+     * remaining `canvasWidth × (canvasHeight - canvasWidth)` band at
+     * the bottom. Stays inert at square canvases (existing
+     * 1222×1222 builds keep their behavior unchanged).
+     *
+     * Defaults to `"https://m0saic.io"`. Pass the empty string to
+     * suppress the strip even on tall canvases.
+     *
+     * Text fades on the same envelope as the QR modules (spawn-in
+     * over the modules' spawn window, hold through the idle, fade
+     * out on the global exit).
+     */
+    urlLabel?: string;
+    /**
+     * Optional per-module corner radius (0..1). Default `0` = square tiles
+     * (the canonical look). Set `1.0` for circular dots — each finder cell
+     * also becomes a circle, giving a "dot matrix" QR look. Doesn't affect
+     * the centre M sub-doc or the URL strip text.
+     *
+     * Backwards-compatible: omitting this prop keeps the existing square
+     * tiles, so committed brand-asset mp4s rebuild byte-identical until
+     * the build script opts in.
+     */
+    moduleBorderRadius?: number;
+    /**
+     * Render the three finder patterns as single "Instagram-style" rounded
+     * eyes — an outer rounded square, an inner light ring, and a rounded
+     * centre dot — instead of the raw grid of per-cell dots. The underlying
+     * per-cell finder modules are suppressed so their circles don't poke
+     * past the rounded ring.
+     *
+     * Pass `true` for the defaults ({@link DEFAULT_EYE_OUTER_RADIUS} outer /
+     * circular centre dot), or an object to tune the corner radii (0..1).
+     *
+     * Requires the QR's finder geometry — see {@link matrixSize} /
+     * {@link quietZone} (defaulted to the brand QR's version-6 layout).
+     * Backwards-compatible: omitting this prop leaves the QR m0 untouched, so
+     * committed builds without eyes rebuild byte-identical.
+     */
+    eyes?: boolean | {
+        /** Outer rounded-square corner radius (0..1). Default 0.35. */
+        outerBorderRadius?: number;
+        /** Inner light-ring corner radius (0..1). Default matches outer. */
+        innerLightBorderRadius?: number;
+        /** Centre dot corner radius (0..1). Default 1.0 (circle). */
+        innerDotBorderRadius?: number;
+    };
+    /**
+     * QR matrix side length in modules (no quiet zone). Used only when
+     * {@link eyes} is set, to locate the finder patterns. Default 41 (the
+     * brand QR's version 6).
+     */
+    matrixSize?: number;
+    /**
+     * Quiet-zone modules per side. Used only when {@link eyes} is set, to
+     * locate the finder patterns. Default 4 (the brand QR).
+     */
+    quietZone?: number;
+};
+export declare const QrAnimate: MosaicTemplate<QrAnimateProps>;
+export default QrAnimate;