@m0saic/templates 0.2.0

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

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * Per-input step builder for the watermark batch pipeline.
+ *
+ * The template ALWAYS returns an `emit: "multi"` pipeline (even for one
+ * input): pipeline steps are the only vehicle where each output's
+ * canvas tracks its input's probed dims (`step.file.size` wins; a plain
+ * top-level doc plans at the CLI `--width/--height`).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_STEP_MS = exports.IMAGE_STEP_MS = void 0;
+exports.buildWatermarkStep = buildWatermarkStep;
+const path = __importStar(require("node:path"));
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const geometry_1 = require("./geometry");
+const content_1 = require("./content");
+const pageGrid_1 = require("./pageGrid");
+const adaptive_1 = require("./adaptive");
+/** Fixed duration for image steps — a single-frame render. */
+exports.IMAGE_STEP_MS = 40;
+/** Duration used for error-mosaic steps (input problems). */
+exports.ERROR_STEP_MS = 1000;
+const ERROR_TITLE = "Watermark";
+function imageContainer(inputPath, pref) {
+    if (pref !== "match")
+        return pref;
+    const ext = path.extname(inputPath).toLowerCase();
+    return ext === ".jpg" || ext === ".jpeg" ? "jpeg" : "png";
+}
+function errorStep(stepName, label, message, ctx) {
+    return {
+        name: stepName,
+        label,
+        durationMs: exports.ERROR_STEP_MS,
+        file: (0, template_utils_1.makeErrorMosaic)(message, {
+            title: ERROR_TITLE,
+            width: ctx.target.width,
+            height: ctx.target.height,
+        }),
+    };
+}
+/**
+ * Build one pipeline step: the input watermarked at its own dims, with
+ * a per-step output format (video → mp4; image → png/jpeg per knob).
+ * Input problems degrade to an error-mosaic step so one bad file never
+ * kills a batch.
+ */
+function buildWatermarkStep(args) {
+    var _a;
+    const { inputPath, stepName, knobs, ctx } = args;
+    const label = path.parse(inputPath).name;
+    const meta = ctx.media[(0, types_1.asAssetId)(inputPath)];
+    if (!meta || !(meta.width > 0) || !(meta.height > 0)) {
+        return errorStep(stepName, label, `No probed dimensions for input: ${inputPath}`, ctx);
+    }
+    if (meta.kind !== "video" && meta.kind !== "image") {
+        return errorStep(stepName, label, `Input is not an image or video (kind: ${meta.kind}): ${inputPath}`, ctx);
+    }
+    const isVideo = meta.kind === "video";
+    if (isVideo && !(meta.durationMs != null && meta.durationMs > 0)) {
+        return errorStep(stepName, label, `Video input has no probed duration: ${inputPath}`, ctx);
+    }
+    const canvasW = meta.width;
+    const canvasH = meta.height;
+    let step;
+    try {
+        const baseAssetId = (0, types_1.asAssetId)((0, template_utils_1.slugifyAssetKeyFromPath)(inputPath));
+        const baseAssets = {
+            [baseAssetId]: { kind: "file", path: inputPath, mediaType: meta.kind },
+        };
+        const baseSource = {
+            type: "media",
+            mediaType: meta.kind,
+            assetId: baseAssetId,
+            // Canvas == input dims, so cover is an exact fit (no crop).
+            placement: { fit: "cover" },
+            editor: { owner: "template", label: "wm:base" },
+        };
+        let doc = knobs.mode === "page"
+            ? buildPageDoc({ baseSource, baseAssets, canvasW, canvasH, knobs })
+            : buildStampDoc({
+                baseSource,
+                baseAssets,
+                canvasW,
+                canvasH,
+                knobs,
+                isVideo,
+                ...(isVideo ? { videoDurMs: meta.durationMs } : {}),
+                ...(((_a = knobs.lumaByInput) === null || _a === void 0 ? void 0 : _a[inputPath]) ? { lumaEntry: knobs.lumaByInput[inputPath] } : {}),
+            });
+        if (knobs.debugLayout) {
+            const constraints = debugConstraints(knobs);
+            if (constraints.length > 0) {
+                // The contract evaluates at ctx.target — shim it to this step's
+                // own canvas so ratio invariants resolve against the real dims.
+                const stepCtx = { ...ctx, target: { ...ctx.target, width: canvasW, height: canvasH } };
+                doc = (0, template_utils_1.withLayoutContract)(doc, stepCtx, {
+                    templateId: "@m0saic/media/watermark/v1",
+                    constraints,
+                    // Constraints target only the parent's own top-level geometry
+                    // (the stamp cell / pattern slot) — don't let a nested child's
+                    // flatten quirk collapse the check.
+                    flatten: false,
+                    debug: true,
+                });
+            }
+        }
+        const format = isVideo
+            ? { kind: "video", container: "mp4" }
+            : { kind: "image", container: imageContainer(inputPath, knobs.imageOutputFormat) };
+        step = {
+            name: stepName,
+            label,
+            durationMs: isVideo ? Math.max(1, Math.round(meta.durationMs)) : exports.IMAGE_STEP_MS,
+            file: { ...doc, format },
+        };
+    }
+    catch (err) {
+        return errorStep(stepName, label, `Watermark step failed for ${inputPath}: ${err instanceof Error ? err.message : String(err)}`, ctx);
+    }
+    return step;
+}
+/**
+ * Watermark artwork child at (w, h) for the resolved content.
+ * `artwork` substitutes the adaptive variant's image/text color; absent
+ * = the user's primary styling. `imageDark` may have a different aspect
+ * than the logo — it contain-fits the same rect (letterboxed if so; the
+ * rect always derives from the PRIMARY logo's probed aspect).
+ */
+function buildContentChild(knobs, w, h, artwork) {
+    var _a, _b;
+    const image = (_a = artwork === null || artwork === void 0 ? void 0 : artwork.image) !== null && _a !== void 0 ? _a : knobs.image;
+    const color = (_b = artwork === null || artwork === void 0 ? void 0 : artwork.textColor) !== null && _b !== void 0 ? _b : knobs.textColor;
+    if (knobs.content === "logo") {
+        return (0, content_1.buildLogoChild)({ logoPath: image, w, h });
+    }
+    if (knobs.content === "lockup") {
+        return (0, content_1.buildLockupChild)({
+            logoPath: image,
+            logoAspect: knobs.contentInfo.logoAspect,
+            text: knobs.text,
+            textAspect: knobs.contentInfo.textAspect,
+            color,
+            layout: knobs.lockupLayout,
+            w,
+            h,
+        });
+    }
+    return (0, content_1.buildTextChild)({ text: knobs.text, color, w, h });
+}
+/**
+ * Bind the wordmark rect (the `wm:text` source of a content child) to the
+ * `text` prop — Make's double-click → inline-edit handle — with the colour
+ * prop that inks THIS layer (`textColor` for the primary artwork,
+ * `textColorOnLight` for the adaptive on-light variant) stacked beside it.
+ * Stamp path only: the corner/adaptive stamp shows the wordmark as ONE rect
+ * per layer, while page mode scatters the same art across the whole canvas
+ * (no single rect displays the prop). Logo-only content has no text rect →
+ * nothing to bind.
+ */
+function bindWordmark(child, colorProp) {
+    var _a, _b;
+    for (const src of (_a = child.sources) !== null && _a !== void 0 ? _a : []) {
+        if (((_b = src.editor) === null || _b === void 0 ? void 0 : _b.label) === "wm:text") {
+            (0, template_utils_1.bindProps)(src, [{ propKey: "text" }, { propKey: colorProp }]);
+        }
+    }
+    return child;
+}
+/** Static/adaptive stamp: one placed cell hosting 1..2 artwork layers. */
+function buildStampDoc(args) {
+    var _a, _b;
+    const { baseSource, baseAssets, canvasW, canvasH, knobs, isVideo, videoDurMs, lumaEntry } = args;
+    const rect = (0, geometry_1.resolveWatermarkRect)({
+        position: knobs.position,
+        sizeRatio: knobs.sizeRatio,
+        sizeBasis: knobs.sizeBasis,
+        marginRatio: knobs.marginRatio,
+        layoutM0: knobs.layoutM0,
+    }, canvasW, canvasH, knobs.contentInfo.aspect);
+    let layers;
+    if (knobs.mode === "adaptive") {
+        // The planner hands each layer's artwork back BY REFERENCE, so identity
+        // tells which colour prop inks that layer's wordmark.
+        const artworkPrimary = {
+            ...(((_a = knobs.imageDark) !== null && _a !== void 0 ? _a : knobs.image) ? { image: (_b = knobs.imageDark) !== null && _b !== void 0 ? _b : knobs.image } : {}),
+            textColor: knobs.textColor,
+        };
+        const artworkOnLight = {
+            ...(knobs.image ? { image: knobs.image } : {}),
+            textColor: knobs.textColorOnLight,
+        };
+        const specs = (0, adaptive_1.buildAdaptiveLayerSpecs)({
+            isVideo,
+            ...(videoDurMs !== undefined ? { videoDurMs } : {}),
+            ...(lumaEntry !== undefined ? { entry: lumaEntry } : {}),
+            knobs: {
+                variant: knobs.variant,
+                windowing: knobs.windowing,
+                opacity: knobs.opacity,
+                fadeMs: knobs.fadeMs,
+                crossfadeMs: knobs.crossfadeMs,
+                lumaThreshold: knobs.lumaThreshold,
+                minGapMs: knobs.minGapMs,
+                ...(knobs.coverageOverride !== undefined
+                    ? { coverageOverride: knobs.coverageOverride }
+                    : {}),
+                artworkPrimary,
+                artworkOnLight,
+            },
+        });
+        layers = specs.map((spec) => ({
+            child: bindWordmark(buildContentChild(knobs, rect.w, rect.h, spec.artwork), spec.artwork === artworkOnLight ? "textColorOnLight" : "textColor"),
+            key: spec.key,
+            ...(spec.alphaExpr !== undefined ? { alphaExpr: spec.alphaExpr } : {}),
+            ...(spec.opacity !== undefined ? { opacity: spec.opacity } : {}),
+        }));
+    }
+    else {
+        layers = [{ child: bindWordmark(buildContentChild(knobs, rect.w, rect.h), "textColor"), opacity: knobs.opacity, key: "wm" }];
+    }
+    if (layers.length === 0) {
+        // Defensive — the planners always yield ≥1 window, but stampOnMedia
+        // rejects empty layers; fall back to the static stamp.
+        layers = [{ child: bindWordmark(buildContentChild(knobs, rect.w, rect.h), "textColor"), opacity: knobs.opacity, key: "wm" }];
+    }
+    return (0, template_utils_1.stampOnMedia)({
+        baseSource,
+        baseAssets,
+        canvasW,
+        canvasH,
+        rect,
+        layers,
+    });
+}
+/**
+ * Page mode: the diagonal repeated pattern as ONE full-canvas nested
+ * child (its own engine command — parent overlay depth stays 1), with
+ * the pattern opacity applied once at the parent source.
+ */
+function buildPageDoc(args) {
+    const { baseSource, baseAssets, canvasW, canvasH, knobs } = args;
+    const basisPx = knobs.sizeBasis === "width" ? canvasW : knobs.sizeBasis === "height" ? canvasH : Math.min(canvasW, canvasH);
+    const contentW = Math.max(1, Math.round(knobs.sizeRatio * basisPx));
+    const contentH = Math.max(1, Math.round(contentW / knobs.contentInfo.aspect));
+    const plan = (0, pageGrid_1.planPageGrid)({
+        canvasW,
+        canvasH,
+        contentW,
+        contentH,
+        angleDeg: knobs.angleDeg,
+        tileGapRatio: knobs.tileGapRatio,
+        stagger: knobs.stagger,
+        maxTiles: knobs.maxTiles,
+    });
+    // The art is built at the (possibly clamped) plan content dims, then
+    // padded to CELL dims as real geometry — the cell-sized nested child
+    // is what keeps the rotation from clipping (see pageGrid.ts header).
+    const art = buildContentChild(knobs, plan.contentW, plan.contentH);
+    const instance = (0, pageGrid_1.buildPaddedInstanceChild)({ plan, art });
+    const pattern = (0, pageGrid_1.buildPagePatternChild)({
+        canvasW,
+        canvasH,
+        plan,
+        angleDeg: knobs.angleDeg,
+        instance,
+    });
+    return (0, template_utils_1.stampOnMedia)({
+        baseSource,
+        baseAssets,
+        canvasW,
+        canvasH,
+        rect: { x: 0, y: 0, w: canvasW, h: canvasH },
+        layers: [{ child: pattern, opacity: knobs.opacity, key: "pattern" }],
+    });
+}
+/**
+ * Debug-mode layout-contract constraints per mode. Skipped for the m0
+ * hatch (the cell aspect is user-chosen) and for adaptive mode (layer
+ * labels vary with the variant plan — wm:light / wm:dark / wm:wm — and
+ * an unmatched label would false-fire).
+ */
+function debugConstraints(knobs) {
+    if (knobs.mode === "page") {
+        return [{ label: "wm:pattern", minWidthFrac: 0.99, minHeightFrac: 0.99 }];
+    }
+    if (knobs.mode === "adaptive" || knobs.layoutM0)
+        return [];
+    return [{ label: "wm:wm", aspect: knobs.contentInfo.aspect, aspectTolerance: 0.06 }];
+}

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

@@ -0,0 +1,88 @@
+/**
+ * @m0saic/media/watermark/v1 — "Watermark"
+ *
+ * The canonical user-facing watermark: stamp your logo or wordmark onto
+ * any image or video. Nine standard positions or an exact m0-rect
+ * escape hatch, ratio-true sizing, opacity control, and an N-inputs →
+ * N-outputs folder batch flow (mixed image + video folders).
+ *
+ * Modes:
+ *   - "static"   — baked in, always visible (this phase).
+ *   - "adaptive" — luma-aware light/dark variant + animated time
+ *                  windows, parity with the free-tier QR stamp (P3).
+ *   - "page"     — diagonal repeated logo/wordmark across the whole
+ *                  page (P2).
+ *
+ * Distinct from `@m0saic/forensic/watermark/video/v1` (the invisible
+ * steganographic watermark) — this one is meant to be seen.
+ *
+ * Note: on the free tier, the post-render hook adds the m0saic QR at
+ * bottom-right on top of the deliverable — pick a different corner to
+ * avoid overlap.
+ */
+import { type StampPosition } from "@m0saic/template-utils";
+import { type WatermarkLumaEntry } from "./adaptive";
+export type WatermarkMode = "static" | "adaptive" | "page";
+export type WatermarkContent = "logo" | "text" | "lockup";
+export type WatermarkV1Props = {
+    /** Inputs to watermark — a folder, one or more files, or drag-and-drop. One output per input. */
+    sourceIds?: string[];
+    /** Watermark mode. "adaptive" and "page" land in later phases. */
+    mode?: WatermarkMode;
+    /** What the watermark shows. "lockup" lands in a later phase. */
+    content?: WatermarkContent;
+    /** Logo image file (PNG with alpha recommended). */
+    image?: string;
+    /** Dark-background logo variant (adaptive mode; later phase). */
+    imageDark?: string;
+    /** Wordmark text (content: "text"). */
+    text?: string;
+    /** Wordmark color. */
+    textColor?: string;
+    /** Wordmark color over bright regions (adaptive mode; later phase). */
+    textColorOnLight?: string;
+    /** Lockup arrangement (content: "lockup"). */
+    lockupLayout?: "text-below" | "text-right";
+    /** Standard placement. */
+    position?: StampPosition;
+    /** Watermark width as a fraction of the size basis. */
+    sizeRatio?: number;
+    /** Which canvas dimension sizeRatio measures against. */
+    sizeBasis?: "min" | "width" | "height";
+    /** Margin from the canvas edges, fraction of min(W, H). */
+    marginRatio?: number;
+    /** Watermark opacity. */
+    opacity?: number;
+    /** Escape hatch: an m0 layout resolving to exactly ONE frame — the watermark cell. Overrides position/size/margin. */
+    layoutM0?: string;
+    /** Adaptive variant pick: follow scene luminance or always use the primary artwork. */
+    variant?: "single" | "auto";
+    /** Adaptive visibility: always on (entrance fade) or timed appearance windows. */
+    windowing?: "always" | "windows";
+    /** Windowed mode: override the duration-based coverage tier (fraction 0..1). */
+    coverageOverride?: number;
+    /** Fade in/out duration at window boundaries / entrance, ms. */
+    fadeMs?: number;
+    /** Light↔dark crossfade duration at scene changes (always-on auto), ms. */
+    crossfadeMs?: number;
+    /** Region luma (0..255) at/above which a scene counts as bright. */
+    lumaThreshold?: number;
+    /** Minimum gap between windowed appearances, ms. */
+    minGapMs?: number;
+    /** Override hatch: per-input luma results (normally pulled via ctx.analysis). */
+    lumaByInput?: Record<string, WatermarkLumaEntry>;
+    /** Page mode: rotation angle, degrees clockwise. */
+    angleDeg?: number;
+    /** Page mode: gap between instances, fraction of min(W, H). */
+    tileGapRatio?: number;
+    /** Page mode: offset alternate rows by half the pitch. */
+    stagger?: boolean;
+    /** Page mode: hard instance budget. */
+    maxTiles?: number;
+    /** Image outputs: match the input's container, or force png/jpeg. */
+    imageOutputFormat?: "match" | "png" | "jpeg";
+    /** Dev tripwire: run the layout contract on each step doc. */
+    debugLayout?: boolean;
+};
+export declare const WatermarkV1: import("@m0saic/types").MosaicTemplate<WatermarkV1Props, import("@m0saic/types").MosaicTemplateOutputs, import("@m0saic/types").MosaicTemplateUpstreamVariables, import("@m0saic/types").MosaicTemplateUpstreamData, import("@m0saic/types").MosaicTemplateSidecars>;
+export default WatermarkV1;