@m0saic/templates 0.2.0

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

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Adaptive-mode layer assembly: which artwork variant(s) the stamp
+ * shows, and the alpha expression that drives each.
+ *
+ * Variant vocabulary (cohesion mapping, same as the QR stamp):
+ *   - "light" artwork = made FOR bright regions → `image` + `textColorOnLight`
+ *   - primary artwork = made FOR dark regions  → `imageDark ?? image` + `textColor`
+ *     (the user's explicitly-chosen styling — white text by default)
+ *
+ * Degradation rule: `variant: "auto"` needs luma evidence. With no
+ * probe data (host prep skipped / unavailable), auto degrades to
+ * "single" — the user's explicit styling with no evidence-free flip.
+ * (This intentionally differs from `buildAdaptiveAlphaExpr`'s
+ * empty-buckets behavior, which would pin the LIGHT variant on.)
+ *
+ * Pure math — no IO, no engine types beyond LuminanceBucket.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTIVE_HIGH_LUMA = exports.ADAPTIVE_LOW_LUMA = exports.WATERMARK_SLOT_MS = void 0;
+exports.probeLumaByInput = probeLumaByInput;
+exports.buildAdaptiveLayerSpecs = buildAdaptiveLayerSpecs;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const geometry_1 = require("./geometry");
+/** One appearance slot for windowed mode — the watermark artwork is
+ *  static, so the slot width is a taste constant, not a clip length. */
+exports.WATERMARK_SLOT_MS = 4000;
+/** Crossfade band for always-on adaptive (same as the QR stamp v1). */
+exports.ADAPTIVE_LOW_LUMA = 100;
+exports.ADAPTIVE_HIGH_LUMA = 156;
+/**
+ * Pull the per-input region-luminance analysis through `ctx.analysis`
+ * (the engine-mediated on-demand probe). Undefined when the host
+ * attached no analysis surface (design mode, no toolchain) or every
+ * probe failed — adaptive `auto` then degrades to single-variant.
+ * Per-input failures drop that input's entry; a probe must never kill
+ * a render.
+ */
+async function probeLumaByInput(props, inputs, ctx) {
+    const analysis = ctx.analysis;
+    if (!analysis)
+        return undefined;
+    // Logo dims for the region math (content "logo"/"lockup") — the image
+    // prop is media-typed, so the host registry has probed it.
+    const logoMeta = props.image ? ctx.media[(0, types_1.asAssetId)(props.image)] : undefined;
+    const logoDims = logoMeta && logoMeta.width > 0 && logoMeta.height > 0
+        ? { width: logoMeta.width, height: logoMeta.height }
+        : undefined;
+    const out = {};
+    for (const inputPath of inputs) {
+        const meta = ctx.media[(0, types_1.asAssetId)(inputPath)];
+        if (!meta || !(meta.width > 0) || !(meta.height > 0))
+            continue;
+        if (meta.kind !== "video" && meta.kind !== "image")
+            continue;
+        try {
+            const region = (0, geometry_1.resolveWatermarkProbeRegion)(props, meta.width, meta.height, logoDims);
+            const r = await analysis.regionLuminance(inputPath, region, {
+                bucketMs: 500,
+                smoothingMs: meta.kind === "video" ? 1500 : 500,
+            });
+            out[inputPath] = {
+                buckets: r.buckets,
+                overallAvgLuma: r.overallAvgLuma,
+                durationMs: r.durationMs,
+            };
+        }
+        catch {
+            // Per-input degrade: this step falls back to single-variant.
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Assemble the adaptive layers for one step.
+ *
+ * Video: windows mode plans slot-aligned appearances (coverage tiers,
+ * gap constraint) with per-window variant picks; always mode keeps the
+ * stamp on with an entrance fade and (auto) a per-scene crossfade
+ * between the two artworks. Image: no time axis — one constant layer,
+ * variant picked once from the overall region luma.
+ */
+function buildAdaptiveLayerSpecs(args) {
+    var _a;
+    const { isVideo, videoDurMs, entry, knobs } = args;
+    const buckets = (_a = entry === null || entry === void 0 ? void 0 : entry.buckets) !== null && _a !== void 0 ? _a : [];
+    const hasLuma = entry != null && (buckets.length > 0 || entry.overallAvgLuma != null);
+    // Auto needs evidence; degrade to the user's explicit styling without it.
+    const effectiveVariant = knobs.variant === "auto" && hasLuma ? "auto" : "single";
+    const opacityStr = knobs.opacity.toFixed(4);
+    // ── Image steps: one constant layer, variant picked once ──────────
+    if (!isVideo) {
+        const artwork = effectiveVariant === "auto" && entry.overallAvgLuma >= knobs.lumaThreshold
+            ? knobs.artworkOnLight
+            : knobs.artworkPrimary;
+        return [{ key: "wm", artwork, opacity: knobs.opacity }];
+    }
+    const durMs = Math.max(1, Math.round(videoDurMs !== null && videoDurMs !== void 0 ? videoDurMs : 0));
+    const fadeSec = knobs.fadeMs / 1000;
+    // ── Windowed appearances ───────────────────────────────────────────
+    if (knobs.windowing === "windows") {
+        const plan = (0, template_utils_1.planStampWindows)({
+            videoDurMs: durMs,
+            slotDurMs: exports.WATERMARK_SLOT_MS,
+            luminanceBuckets: buckets,
+            variantThreshold: knobs.lumaThreshold,
+            minGapMs: knobs.minGapMs,
+            ...(knobs.coverageOverride !== undefined
+                ? { coverageOverride: knobs.coverageOverride }
+                : {}),
+        });
+        if (effectiveVariant === "single") {
+            const alpha = (0, template_utils_1.buildWindowsAlphaExpr)(plan.windows, {
+                peakAlpha: knobs.opacity,
+                fadeInSec: fadeSec,
+                fadeOutSec: fadeSec,
+            });
+            return alpha ? [{ key: "wm", artwork: knobs.artworkPrimary, alphaExpr: alpha }] : [];
+        }
+        const groups = (0, template_utils_1.groupWindowsByVariant)(plan.windows);
+        const specs = [];
+        for (const [variant, windows] of [
+            ["light", groups.light],
+            ["dark", groups.dark],
+        ]) {
+            const alpha = (0, template_utils_1.buildWindowsAlphaExpr)(windows, {
+                peakAlpha: knobs.opacity,
+                fadeInSec: fadeSec,
+                fadeOutSec: fadeSec,
+            });
+            if (!alpha)
+                continue;
+            specs.push({
+                key: variant,
+                artwork: variant === "light" ? knobs.artworkOnLight : knobs.artworkPrimary,
+                alphaExpr: alpha,
+            });
+        }
+        return specs;
+    }
+    // ── Always-on ──────────────────────────────────────────────────────
+    const entrance = (0, template_utils_1.buildEntranceExpr)(0, fadeSec);
+    if (effectiveVariant === "single") {
+        return [
+            { key: "wm", artwork: knobs.artworkPrimary, alphaExpr: (0, template_utils_1.composeAlpha)(entrance, opacityStr) },
+        ];
+    }
+    const crossfadeSec = knobs.crossfadeMs / 1000;
+    return [
+        {
+            key: "light",
+            artwork: knobs.artworkOnLight,
+            alphaExpr: (0, template_utils_1.composeAlpha)((0, template_utils_1.buildAdaptiveAlphaExpr)(buckets, "light", exports.ADAPTIVE_LOW_LUMA, exports.ADAPTIVE_HIGH_LUMA, crossfadeSec), entrance, opacityStr),
+        },
+        {
+            key: "dark",
+            artwork: knobs.artworkPrimary,
+            alphaExpr: (0, template_utils_1.composeAlpha)((0, template_utils_1.buildAdaptiveAlphaExpr)(buckets, "dark", exports.ADAPTIVE_LOW_LUMA, exports.ADAPTIVE_HIGH_LUMA, crossfadeSec), entrance, opacityStr),
+        },
+    ];
+}

package/dist/m0saic/media/watermark/v1/content.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Watermark artwork child-document builders.
+ *
+ * Each builder returns a self-contained, hermetic `MosaicDocument`
+ * sized to the stamp rect (children MUST declare `size` — a size-less
+ * nested child renders at parent tile size and stretches). The child
+ * renders at exactly the cell size, so no oversized raster work.
+ */
+import type { MosaicColor, MosaicDocument, MosaicSource } from "@m0saic/types";
+import { type LockupLayout } from "./geometry";
+/** Logo child: the user's image at contain-fit on a transparent canvas. */
+export declare function buildLogoChild(opts: {
+    logoPath: string;
+    w: number;
+    h: number;
+}): MosaicDocument;
+/**
+ * SVG-glyph text source, font fit-to-box: measured at
+ * {@link REF_FONT_PX} and scaled so the padded width and block height
+ * both fit the (w, h) box. Deterministic bundled font, no drawtext
+ * spawn (W5). Shared by the text child and the lockup child.
+ */
+export declare function makeSvgTextSource(opts: {
+    text: string;
+    color: MosaicColor;
+    w: number;
+    h: number;
+}): MosaicSource;
+/**
+ * Text child: the wordmark as SVG glyph outlines on a transparent
+ * canvas.
+ */
+export declare function buildTextChild(opts: {
+    text: string;
+    color: MosaicColor;
+    w: number;
+    h: number;
+}): MosaicDocument;
+/**
+ * Lockup child: logo + wordmark in one transparent canvas.
+ * `text-right`: logo at full height, text at {@link LOCKUP_TEXT_TO_LOGO}
+ * of it, vertically centered after a {@link LOCKUP_GAP} gap.
+ * `text-below`: logo in the top {@link LOCKUP_LOGO_BAND} band, text in
+ * the bottom {@link LOCKUP_TEXT_BAND} band, both horizontally centered.
+ * Contain-fit + fit-to-box text absorb the integer rounding.
+ */
+export declare function buildLockupChild(opts: {
+    logoPath: string;
+    logoAspect: number;
+    text: string;
+    textAspect: number;
+    color: MosaicColor;
+    layout: LockupLayout;
+    w: number;
+    h: number;
+}): MosaicDocument;

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

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Watermark artwork child-document builders.
+ *
+ * Each builder returns a self-contained, hermetic `MosaicDocument`
+ * sized to the stamp rect (children MUST declare `size` — a size-less
+ * nested child renders at parent tile size and stretches). The child
+ * renders at exactly the cell size, so no oversized raster work.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLogoChild = buildLogoChild;
+exports.makeSvgTextSource = makeSvgTextSource;
+exports.buildTextChild = buildTextChild;
+exports.buildLockupChild = buildLockupChild;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const geometry_1 = require("./geometry");
+/** Logo child: the user's image at contain-fit on a transparent canvas. */
+function buildLogoChild(opts) {
+    const { logoPath, w, h } = opts;
+    const logoAssetId = (0, types_1.asAssetId)("wm_logo");
+    const assets = {
+        [logoAssetId]: { kind: "file", path: logoPath, mediaType: "image" },
+    };
+    const sources = [
+        {
+            type: "media",
+            mediaType: "image",
+            assetId: logoAssetId,
+            placement: { fit: "contain" },
+            editor: { owner: "template", label: "wm:logo" },
+        },
+    ];
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: "F",
+        sources,
+        assets,
+        size: { width: w, height: h },
+    };
+}
+/**
+ * SVG-glyph text source, font fit-to-box: measured at
+ * {@link REF_FONT_PX} and scaled so the padded width and block height
+ * both fit the (w, h) box. Deterministic bundled font, no drawtext
+ * spawn (W5). Shared by the text child and the lockup child.
+ */
+function makeSvgTextSource(opts) {
+    const { text, color, w, h } = opts;
+    const m = (0, template_utils_1.measureText)(text, { fontSize: geometry_1.REF_FONT_PX });
+    if (!(m.width > 0) || !(m.height > 0)) {
+        throw new Error("Watermark text measures to an empty box — provide non-empty text.");
+    }
+    const scale = Math.min(w / (m.width * geometry_1.TEXT_WIDTH_PAD), h / m.height);
+    const fontSize = Math.max(4, Math.floor(geometry_1.REF_FONT_PX * scale));
+    return {
+        type: "text",
+        rasterizer: "svg",
+        renderMode: { kind: "image" },
+        layers: [
+            {
+                content: { kind: "literal", text },
+                style: { fontSize, fontColor: color },
+                // placement defaults center the block (hAlign "center", vAlign "middle")
+            },
+        ],
+        editor: { owner: "template", label: "wm:text" },
+    };
+}
+/**
+ * Text child: the wordmark as SVG glyph outlines on a transparent
+ * canvas.
+ */
+function buildTextChild(opts) {
+    const { text, color, w, h } = opts;
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: "F",
+        sources: [makeSvgTextSource({ text, color, w, h })],
+        assets: {},
+        size: { width: w, height: h },
+    };
+}
+// ── Lockup (logo + wordmark) ──────────────────────────────────
+/**
+ * Lockup child: logo + wordmark in one transparent canvas.
+ * `text-right`: logo at full height, text at {@link LOCKUP_TEXT_TO_LOGO}
+ * of it, vertically centered after a {@link LOCKUP_GAP} gap.
+ * `text-below`: logo in the top {@link LOCKUP_LOGO_BAND} band, text in
+ * the bottom {@link LOCKUP_TEXT_BAND} band, both horizontally centered.
+ * Contain-fit + fit-to-box text absorb the integer rounding.
+ */
+function buildLockupChild(opts) {
+    const { logoPath, logoAspect, text, textAspect, color, layout, w, h } = opts;
+    if (!(w > 0) || !(h > 0)) {
+        throw new Error(`buildLockupChild: dims must be positive, got ${w}x${h}`);
+    }
+    let logoRect;
+    let textRect;
+    if (layout === "text-below") {
+        const logoH = clampInt(Math.round(h * geometry_1.LOCKUP_LOGO_BAND), 1, h);
+        const logoW = clampInt(Math.round(logoH * logoAspect), 1, w);
+        const textH = clampInt(Math.round(h * geometry_1.LOCKUP_TEXT_BAND), 1, h - logoH || 1);
+        const textW = clampInt(Math.round(textH * textAspect), 1, w);
+        logoRect = { x: Math.floor((w - logoW) / 2), y: 0, w: logoW, h: logoH };
+        textRect = { x: Math.floor((w - textW) / 2), y: h - textH, w: textW, h: textH };
+    }
+    else {
+        const logoW = clampInt(Math.round(h * logoAspect), 1, w);
+        const gap = Math.round(h * geometry_1.LOCKUP_GAP);
+        const textH = clampInt(Math.round(h * geometry_1.LOCKUP_TEXT_TO_LOGO), 1, h);
+        const textW = clampInt(Math.round(textH * textAspect), 1, Math.max(1, w - logoW - gap));
+        logoRect = { x: 0, y: 0, w: logoW, h };
+        textRect = {
+            x: Math.min(logoW + gap, w - textW),
+            y: Math.floor((h - textH) / 2),
+            w: textW,
+            h: textH,
+        };
+    }
+    const placed = (0, dsl_stdlib_1.placeRects)({
+        rootW: w,
+        rootH: h,
+        rects: [logoRect, textRect].map((r) => ({ ...r, claimant: "F" })),
+    });
+    const logoAssetId = (0, types_1.asAssetId)("wm_logo");
+    const pieces = [
+        {
+            type: "media",
+            mediaType: "image",
+            assetId: logoAssetId,
+            placement: { fit: "contain" },
+            editor: { owner: "template", label: "wm:logo" },
+        },
+        makeSvgTextSource({ text, color, w: textRect.w, h: textRect.h }),
+    ];
+    const rects = [logoRect, textRect];
+    const sources = [];
+    for (const layer of placed.layers) {
+        const ordered = [...layer.rectIndices].sort((a, b) => rects[a].y - rects[b].y || rects[a].x - rects[b].x);
+        for (const idx of ordered)
+            sources.push(pieces[idx]);
+    }
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)(String(placed.m0), "WatermarkLockup"),
+        sources,
+        assets: {
+            [logoAssetId]: { kind: "file", path: logoPath, mediaType: "image" },
+        },
+        size: { width: w, height: h },
+    };
+}
+function clampInt(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}

package/dist/m0saic/media/watermark/v1/geometry.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Pure geometry + gating helpers for `@m0saic/media/watermark/v1`.
+ *
+ * Everything here is deterministic and engine-free (types-only imports)
+ * so the HOST can call the same math the template uses — the adaptive
+ * luma prep step (packages/product) resolves the probe region through
+ * {@link resolveWatermarkProbeRegion} and the template's `render`
+ * resolves the stamp rect through {@link resolveWatermarkRect}; because
+ * both go through the same functions, host math can't drift from
+ * template math.
+ *
+ * User-facing failures throw plain `Error`s with presentable messages;
+ * `render` catches them into error mosaics.
+ */
+import type { MosaicEngineContext, RegionPctRect } from "@m0saic/types";
+import { type StampPosition, type StampRectPx } from "@m0saic/template-utils";
+import type { WatermarkV1Props } from "./watermark";
+/** Reference size text is measured at; fit-to-box scales linearly from it. */
+export declare const REF_FONT_PX = 100;
+/**
+ * Width safety pad on measured text. The app fits text slightly wider
+ * than the CLI (known drift); the pad keeps the wordmark inside its
+ * box on both.
+ */
+export declare const TEXT_WIDTH_PAD = 1.04;
+/** Canonical defaults — exported so the host prep step resolves props identically. */
+export declare const WATERMARK_DEFAULTS: {
+    readonly mode: "static";
+    readonly content: "logo";
+    readonly text: "yourbrand.com";
+    readonly textColor: "#ffffff";
+    readonly textColorOnLight: "#111111";
+    readonly lockupLayout: "text-right";
+    readonly position: "bottom-right";
+    readonly sizeRatio: 0.18;
+    readonly sizeBasis: "min";
+    readonly marginRatio: 0.022;
+    readonly opacity: 0.85;
+    readonly imageOutputFormat: "match";
+    readonly variant: "auto";
+    readonly windowing: "always";
+    readonly fadeMs: 400;
+    readonly crossfadeMs: 400;
+    readonly lumaThreshold: 128;
+    readonly minGapMs: 3000;
+    readonly angleDeg: -30;
+    readonly tileGapRatio: 0.08;
+    readonly stagger: true;
+    readonly maxTiles: 24;
+    readonly debugLayout: false;
+};
+/** Text height as a fraction of the lockup's logo height. */
+export declare const LOCKUP_TEXT_TO_LOGO = 0.28;
+/** Gap between logo and text (text-right), fraction of lockup height. */
+export declare const LOCKUP_GAP = 0.15;
+/** Logo band height (text-below), fraction of lockup height. */
+export declare const LOCKUP_LOGO_BAND = 0.78;
+/** Text band height (text-below), fraction of lockup height. */
+export declare const LOCKUP_TEXT_BAND = 0.22;
+export type LockupLayout = "text-right" | "text-below";
+/**
+ * Intrinsic w/h aspect of a lockup composed from logo aspect `aL` and
+ * text aspect `aT` (both intrinsic w/h). Mirrors the rect math in
+ * `buildLockupChild` (content.ts) — unit-tested together so they can't
+ * drift.
+ */
+export declare function lockupAspect(aL: number, aT: number, layout: LockupLayout): number;
+/** Measured intrinsic aspect (w/h) of a text wordmark. */
+export declare function textContentAspect(text: string): number;
+/** Resolved content facts the step builders consume. */
+export type WatermarkContentInfo = {
+    /** Intrinsic w/h of the whole watermark artwork. */
+    aspect: number;
+    /** Intrinsic logo w/h (content: "logo" | "lockup"). */
+    logoAspect?: number;
+    /** Intrinsic text w/h (content: "text" | "lockup"). */
+    textAspect?: number;
+};
+/**
+ * Resolve the watermark artwork's intrinsic aspect facts from the
+ * resolved content props. Logo dims come from the host-probed media
+ * registry (`ctx.media`); pass them explicitly via `logoDims` when
+ * calling from a host that has the registry but no engine context.
+ */
+export declare function resolveContentInfo(props: WatermarkV1Props, ctx: Pick<MosaicEngineContext, "media">, logoDims?: {
+    width: number;
+    height: number;
+}): WatermarkContentInfo;
+/** Back-compat shim: the artwork's combined intrinsic aspect. */
+export declare function resolveContentAspect(props: WatermarkV1Props, ctx: Pick<MosaicEngineContext, "media">, logoDims?: {
+    width: number;
+    height: number;
+}): number;
+/**
+ * Normalize the `layoutM0` prop: accepts a bare m0 or a pasted `.m0`
+ * file (header `#` comment lines are stripped). Returns null when
+ * empty. (Same convention as screencap-grid's `customGrid`.)
+ */
+export declare function normalizeLayoutM0(raw: string | undefined): string | null;
+/**
+ * Validate the escape-hatch layout string (canvas-independent checks).
+ * Throws a user-facing error on invalid strings or frame counts.
+ */
+export declare function validateLayoutM0(m0: string): void;
+/** Resolved placement knobs the rect derives from. */
+export type WatermarkRectKnobs = {
+    position: StampPosition;
+    sizeRatio: number;
+    sizeBasis: "min" | "width" | "height";
+    marginRatio: number;
+    /** Normalized escape-hatch m0 (see {@link normalizeLayoutM0}); overrides everything else. */
+    layoutM0?: string | null;
+};
+/**
+ * Resolve the stamp cell for one canvas. The escape hatch parses the
+ * user's single-frame m0 at this canvas and clamps to integer bounds;
+ * otherwise the nine-position math applies. The rect is the stamp
+ * CELL — content keeps its intrinsic aspect via `fit: "contain"`
+ * inside it.
+ */
+export declare function resolveWatermarkRect(knobs: WatermarkRectKnobs, canvasW: number, canvasH: number, contentAspect: number): StampRectPx;
+/**
+ * Whether the host should run the region-luminance probe for these
+ * props. True only for `mode: "adaptive"` with `variant: "auto"` —
+ * anything else needs no luma, and the host must skip the probe
+ * entirely (the laziness guarantee).
+ */
+export declare function watermarkNeedsLumaProbe(props: WatermarkV1Props): boolean;
+/**
+ * The region the host's luma probe samples for one input canvas: the
+ * resolved stamp rect expanded 10% total per axis (over-sampling
+ * catches content just outside the stamp that bleeds under it after
+ * fades), clamped to [0, 1] fractions.
+ */
+export declare function resolveWatermarkProbeRegion(props: WatermarkV1Props, canvasW: number, canvasH: number, logoDims?: {
+    width: number;
+    height: number;
+}): RegionPctRect;