@m0saic/templates 0.2.0

package/dist/m0saic/media/logo-animate/v1/expressions.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Animation-mode expression builders for `@m0saic/media/logo-animate/v1`.
+ *
+ * All builders return ffmpeg-evaluator-compatible strings of global `t`
+ * (wall-clock seconds). No filesystem, no random state — fully
+ * deterministic from inputs.
+ *
+ * The `assemble` mode re-uses the qr-animate v1 builders directly (the
+ * same cross-version import qr-animate/v2 already does). The other four
+ * modes are local ports of the module-private builders in
+ * `brand/logo/v3/logo.ts` — the same copy each brand/logo version
+ * carries; kept verbatim-shaped so the two stay diffable.
+ */
+export { buildModuleAlphaExpr, buildPseudoRanks, buildTileOffsetExpr, type ModulePhaseParams, type RankInputTile, } from "../../qr/animate/v1/expressions";
+/**
+ * `logo_loop` — loopable per-tile enable expression for `overlay.enable`.
+ * Reveal-in by rank, hold, then reveal-out by reverse rank; seamless over
+ * `loopSec`. Scalar per-frame gate (free — no alpha fold).
+ */
+export declare function buildLoopEnableExpr(rank: number, opts: {
+    loopSec: number;
+    inEnd: number;
+    outStart: number;
+    feather: number;
+    fps: number;
+    startDelay: number;
+    endDelay: number;
+    easing: "linear" | "smoothstep";
+}): string;
+/**
+ * `progress_fill` — enable when `(p + feather) >= rank`. `p` is a static
+ * `progress` value, a one-shot ramp over `progressSec`, or a repeating
+ * ramp. Rank MUST be a percentile rank in [0..1] across visible tiles.
+ */
+export declare function buildProgressFillEnableExpr(rank: number, opts: {
+    progress?: number;
+    progressSec: number;
+    oneShot: boolean;
+    feather: number;
+    fps: number;
+}): string;
+/**
+ * `breathing` — the loading-UI glow: base cos-pulse plus a rank-aware
+ * shimmer band, as an `overlay.alpha` value in [0..1].
+ */
+export declare function buildBreathingAlphaExpr(rank: number, opts: {
+    baseMin: number;
+    baseMax: number;
+    basePulseSec: number;
+    shimmerSec: number;
+    shimmerWidth: number;
+    shimmerAmp: number;
+    feather: number;
+    fps: number;
+}): string;
+/**
+ * `shimmer` — travelling highlight band as an `overlay.enable` gate:
+ * a tile is on while the band center is within `shimmerWidth/2` of its
+ * rank (cyclic wrap via the p±1 comparisons).
+ */
+export declare function buildShimmerEnableExpr(rank: number, opts: {
+    shimmerSec: number;
+    shimmerWidth: number;
+    feather: number;
+    fps: number;
+}): string;

package/dist/m0saic/media/logo-animate/v1/expressions.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Animation-mode expression builders for `@m0saic/media/logo-animate/v1`.
+ *
+ * All builders return ffmpeg-evaluator-compatible strings of global `t`
+ * (wall-clock seconds). No filesystem, no random state — fully
+ * deterministic from inputs.
+ *
+ * The `assemble` mode re-uses the qr-animate v1 builders directly (the
+ * same cross-version import qr-animate/v2 already does). The other four
+ * modes are local ports of the module-private builders in
+ * `brand/logo/v3/logo.ts` — the same copy each brand/logo version
+ * carries; kept verbatim-shaped so the two stay diffable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTileOffsetExpr = exports.buildPseudoRanks = exports.buildModuleAlphaExpr = void 0;
+exports.buildLoopEnableExpr = buildLoopEnableExpr;
+exports.buildProgressFillEnableExpr = buildProgressFillEnableExpr;
+exports.buildBreathingAlphaExpr = buildBreathingAlphaExpr;
+exports.buildShimmerEnableExpr = buildShimmerEnableExpr;
+var expressions_1 = require("../../qr/animate/v1/expressions");
+Object.defineProperty(exports, "buildModuleAlphaExpr", { enumerable: true, get: function () { return expressions_1.buildModuleAlphaExpr; } });
+Object.defineProperty(exports, "buildPseudoRanks", { enumerable: true, get: function () { return expressions_1.buildPseudoRanks; } });
+Object.defineProperty(exports, "buildTileOffsetExpr", { enumerable: true, get: function () { return expressions_1.buildTileOffsetExpr; } });
+/**
+ * `logo_loop` — loopable per-tile enable expression for `overlay.enable`.
+ * Reveal-in by rank, hold, then reveal-out by reverse rank; seamless over
+ * `loopSec`. Scalar per-frame gate (free — no alpha fold).
+ */
+function buildLoopEnableExpr(rank, opts) {
+    const { loopSec, inEnd, outStart, feather, fps, startDelay, endDelay } = opts;
+    const p = `mod(t,${loopSec})/${loopSec}`;
+    const pFrame = `(1/${fps})/${loopSec}`;
+    const startGate = `gte(${p},${pFrame})`;
+    const activeStart = `${startDelay}`;
+    const activeEnd = `(1-${endDelay})`;
+    const activeDur = `(${activeEnd}-${activeStart})`;
+    const activeGate = `gte(${p},${activeStart})*lt(${p},${activeEnd})`;
+    const pA = `(((${p})-${activeStart})/${activeDur})`;
+    const pE = opts.easing === "smoothstep"
+        ? `(${pA})*(${pA})*(3-2*(${pA}))`
+        : `${pA}`;
+    const outDur = `(1-${outStart})`;
+    const inProg = `min((${pE})/${inEnd},1)`;
+    const outProg = `min(max(((${pE})-${outStart})/${outDur},0),1)`;
+    return `${startGate}*${activeGate}*gte((${inProg})+${feather},${rank})*gte((1-(${outProg}))+${feather},${rank})`;
+}
+/**
+ * `progress_fill` — enable when `(p + feather) >= rank`. `p` is a static
+ * `progress` value, a one-shot ramp over `progressSec`, or a repeating
+ * ramp. Rank MUST be a percentile rank in [0..1] across visible tiles.
+ */
+function buildProgressFillEnableExpr(rank, opts) {
+    const { progress, progressSec, oneShot, feather, fps } = opts;
+    // Frame-0 guard (skip when progress is explicitly set — static fills
+    // should render at t=0 for single-image output, not wait a frame).
+    const isStaticProgress = progress !== undefined;
+    const startGate = isStaticProgress ? "1" : `gte(t,1/${fps})`;
+    const pExpr = progress !== undefined
+        ? String(Math.max(0, Math.min(1, progress)))
+        : oneShot
+            ? `min(max(t/${progressSec},0),1)`
+            : `mod(t,${progressSec})/${progressSec}`;
+    return `${startGate}*gte((${pExpr})+${feather},${rank})`;
+}
+/**
+ * `breathing` — the loading-UI glow: base cos-pulse plus a rank-aware
+ * shimmer band, as an `overlay.alpha` value in [0..1].
+ */
+function buildBreathingAlphaExpr(rank, opts) {
+    const { baseMin, baseMax, basePulseSec, shimmerSec, shimmerWidth, shimmerAmp, feather, fps } = opts;
+    const startGate = `gte(t,1/${fps})`;
+    // base breathing: baseMin + (baseMax-baseMin)*0.5*(1-cos(2*pi*t/basePulseSec))
+    const base = `(${baseMin})+(${baseMax}-${baseMin})*0.5*(1-cos(2*PI*t/${basePulseSec}))`;
+    // moving center p in [0..1)
+    const p = `mod(t,${shimmerSec})/${shimmerSec}`;
+    const halfW = `(${shimmerWidth}/2)`;
+    // wrap distance
+    const d0 = `abs(${rank}-(${p}))`;
+    const d1 = `abs(${rank}-((${p})-1))`;
+    const d2 = `abs(${rank}-((${p})+1))`;
+    const d = `min(min(${d0},${d1}),${d2})`;
+    // band strength u in [0..1]: u = clamp(1 - d/halfW, 0, 1)
+    const u = `max(min(1-(${d})/(${halfW}),1),0)`;
+    // smoothstep(u) = u*u*(3-2*u)
+    const band = `(${u})*(${u})*(3-2*(${u}))`;
+    const hi = `(${shimmerAmp})*${band}`;
+    const a = `max(min((${base})+(${hi})+${feather},1),0)`;
+    return `${startGate}*(${a})`;
+}
+/**
+ * `shimmer` — travelling highlight band as an `overlay.enable` gate:
+ * a tile is on while the band center is within `shimmerWidth/2` of its
+ * rank (cyclic wrap via the p±1 comparisons).
+ */
+function buildShimmerEnableExpr(rank, opts) {
+    const { shimmerSec, shimmerWidth, feather, fps } = opts;
+    const startGate = `gte(t,1/${fps})`;
+    const p = `mod(t,${shimmerSec})/${shimmerSec}`;
+    const halfW = `(${shimmerWidth}/2)`;
+    // d = min( abs(rank - p), abs(rank - (p-1)), abs(rank - (p+1)) )
+    const d0 = `abs(${rank}-(${p}))`;
+    const d1 = `abs(${rank}-((${p})-1))`;
+    const d2 = `abs(${rank}-((${p})+1))`;
+    const d = `min(min(${d0},${d1}),${d2})`;
+    return `${startGate}*lte(${d},(${halfW})+${feather})`;
+}

package/dist/m0saic/media/logo-animate/v1/index.d.ts

@@ -0,0 +1,2 @@
+export { LogoAnimateV1 } from "./logo-animate";
+export type { LogoAnimateV1Props, LogoAnimationMode, LogoRankSetMode, } from "./logo-animate";

package/dist/m0saic/media/logo-animate/v1/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogoAnimateV1 = void 0;
+var logo_animate_1 = require("./logo-animate");
+Object.defineProperty(exports, "LogoAnimateV1", { enumerable: true, get: function () { return logo_animate_1.LogoAnimateV1; } });

package/dist/m0saic/media/logo-animate/v1/layout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Aspect-correct placement for `@m0saic/media/logo-animate/v1`
+ * (`fit: "contain"`).
+ *
+ * The converted logo becomes a size-declared child mosaic; the parent
+ * carves ONE centered rect at the logo's aspect via `placeRect`
+ * (byte-exact at any canvas, null-tile margins — never `insetNode`,
+ * which spreads quantization into the rect) and references the child
+ * there. The remaining canvas is null tiles over the document
+ * background.
+ */
+export type ContainRect = {
+    w: number;
+    h: number;
+};
+/**
+ * Largest integer rect with the logo's aspect that fits the output
+ * canvas (centered by the caller via `placeRect`).
+ */
+export declare function computeContainRect(outW: number, outH: number, logoW: number, logoH: number): ContainRect;
+export type ContainLayout = {
+    /** Parent m0: exactly one rendered frame (the fit rect) + null margins. */
+    m0: string;
+    /** The carved fit rect (the child's declared size). */
+    rect: ContainRect;
+    /** True when the fit rect IS the canvas — nesting would be a no-op. */
+    exactFit: boolean;
+};
+export declare function buildContainLayout(outW: number, outH: number, logoW: number, logoH: number): ContainLayout;

package/dist/m0saic/media/logo-animate/v1/layout.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Aspect-correct placement for `@m0saic/media/logo-animate/v1`
+ * (`fit: "contain"`).
+ *
+ * The converted logo becomes a size-declared child mosaic; the parent
+ * carves ONE centered rect at the logo's aspect via `placeRect`
+ * (byte-exact at any canvas, null-tile margins — never `insetNode`,
+ * which spreads quantization into the rect) and references the child
+ * there. The remaining canvas is null tiles over the document
+ * background.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeContainRect = computeContainRect;
+exports.buildContainLayout = buildContainLayout;
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+/**
+ * Largest integer rect with the logo's aspect that fits the output
+ * canvas (centered by the caller via `placeRect`).
+ */
+function computeContainRect(outW, outH, logoW, logoH) {
+    const safeLogoW = logoW > 0 ? logoW : 1;
+    const safeLogoH = logoH > 0 ? logoH : 1;
+    const scale = Math.min(outW / safeLogoW, outH / safeLogoH);
+    return {
+        w: Math.min(outW, Math.max(1, Math.round(safeLogoW * scale))),
+        h: Math.min(outH, Math.max(1, Math.round(safeLogoH * scale))),
+    };
+}
+function buildContainLayout(outW, outH, logoW, logoH) {
+    const rect = computeContainRect(outW, outH, logoW, logoH);
+    const placed = (0, dsl_stdlib_1.placeRect)({
+        rootW: outW,
+        rootH: outH,
+        rectW: rect.w,
+        rectH: rect.h,
+    });
+    return {
+        m0: String(placed.m0),
+        rect,
+        exactFit: rect.w === outW && rect.h === outH,
+    };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * @m0saic/media/logo-animate/v1
+ *
+ * Drop in a company-logo SVG → get an animated logo video back.
+ *
+ * The SVG is decomposed into REAL m0 geometry at render time
+ * (`parseSvg → extractGeometry → inferGrid → rectsToM0`): one concrete
+ * cell per logo shape, per-shape silhouettes as inline masks bounded to
+ * their cells, per-tile ranks driving the animation. No overlay fakery,
+ * no baked pixels — the logo's geometry lives in the m0 string, so the
+ * DSL view, structure preview and Render Hero all see it.
+ *
+ * Sources: inline `svg` string (pure), or `svgPath` file (capability
+ * tier, `fs.read`). With neither, a baked placeholder mark (the m0saic
+ * M) renders so defaults are standalone-renderable.
+ *
+ * Scope (v1): rectilinear logos at moderate shape counts convert
+ * faithfully; non-rectilinear shapes still convert and carry best-effort
+ * silhouette masks. Single ink (per-shape SVG color preservation is a
+ * later phase). Logos fill the canvas — render at the logo's own aspect
+ * for an undistorted mark (see `outputHints`).
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type PackingMode } from "@m0saic/dsl-stdlib";
+export type LogoAnimationMode = "assemble" | "logo_loop" | "progress_fill" | "breathing" | "shimmer";
+export type LogoRankSetMode = "scatter" | "diag" | "cascade" | "radial";
+/** Bitmap-mode fidelity tiers (raster grid side length grows per tier). */
+export type LogoBitmapPrecision = "draft" | "balanced" | "crisp" | "fine" | "ultra";
+export type LogoAnimateV1Props = {
+    /**
+     * Path to the logo SVG file on disk (file picker). Read at render
+     * time via the template's `fs.read` capability. Provide this OR
+     * {@link svg}, not both. With neither, a placeholder mark renders.
+     */
+    svgPath?: string;
+    /**
+     * Inline SVG string (pure path — no filesystem). Only `<path>` and
+     * `<rect>` elements are parsed; run Inkscape "Object to Path" +
+     * ungroup on anything fancier.
+     */
+    svg?: string;
+    /** Drift tolerance for grid inference (% of min canvas dim). Default 0. */
+    driftPercent?: number;
+    /** Layer-packing strategy. Default "multi". */
+    packing?: PackingMode;
+    /**
+     * Bitmap mode — rasterize the SVG to a pixel grid and animate the pixels.
+     * Opt-in: a full grid of cells is a heavy render. Use for non-rectilinear
+     * marks that collapse to a single cell in the default (vector) path.
+     */
+    bitmap?: boolean;
+    /**
+     * Bitmap-mode fidelity (raster resolution tier). Higher = far more frames /
+     * slower renders; `ultra` (512²) is maximum fidelity — it renders but is too
+     * heavy for the live editor preview. Default "balanced" (64²).
+     */
+    bitmapPrecision?: LogoBitmapPrecision;
+    /** Animation mode. Default "assemble". */
+    animation?: LogoAnimationMode;
+    /**
+     * Tile ordering driving the animation: "scatter" (hash-shuffled),
+     * "diag" (top-left sweep), "cascade" (row cascade), "radial"
+     * (center-out). Default "scatter".
+     */
+    rankSet?: LogoRankSetMode;
+    /** assemble: stagger between first and last tile fade-in start, ms. */
+    spawnDurMs?: number;
+    /** assemble: per-tile fade-in duration, ms. */
+    tileFadeMs?: number;
+    /** assemble: hold at full alpha before the fade-out, ms. */
+    holdDurMs?: number;
+    /** assemble: global fade-out duration, ms. */
+    fadeOutDurMs?: number;
+    /** assemble: pixel offset each tile settles from. */
+    tileOffsetPx?: number;
+    /** logo_loop: seamless loop period, seconds. */
+    loopSec?: number;
+    /** progress_fill: freeze at a static fill level (0..1) — good for stills. */
+    progress?: number;
+    /** progress_fill: fill ramp duration, seconds. */
+    progressSec?: number;
+    /** progress_fill: fill once and hold instead of repeating. */
+    oneShot?: boolean;
+    /** shimmer + breathing: band sweep period, seconds. */
+    shimmerSec?: number;
+    /** shimmer + breathing: band width as a fraction of rank space (0..1). */
+    shimmerWidth?: number;
+    /** Rank-space tolerance softening mode boundaries. */
+    feather?: number;
+    /**
+     * Aspect handling. "contain" (default) letterboxes the logo at its
+     * own aspect inside any canvas — the logo nests as a size-declared
+     * child mosaic in a `placeRect`-carved fit rect. "fill" stretches the
+     * logo geometry across the whole canvas (correct when the canvas
+     * already matches the logo's aspect).
+     */
+    fit?: "contain" | "fill";
+    /** Hand-tuned ink/background duo. Default "light". */
+    preset?: "light" | "dark";
+    /** Ink override — the single fill color for every logo shape (MVP). */
+    color?: MosaicColor;
+    /** Canvas background override. */
+    backgroundColor?: MosaicColor;
+};
+export declare const LogoAnimateV1: MosaicTemplate<LogoAnimateV1Props>;
+export default LogoAnimateV1;