@m0saic/templates 0.2.0

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

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCKUP_TEXT_BAND = exports.LOCKUP_LOGO_BAND = exports.LOCKUP_GAP = exports.LOCKUP_TEXT_TO_LOGO = exports.WATERMARK_DEFAULTS = exports.TEXT_WIDTH_PAD = exports.REF_FONT_PX = void 0;
+exports.lockupAspect = lockupAspect;
+exports.textContentAspect = textContentAspect;
+exports.resolveContentInfo = resolveContentInfo;
+exports.resolveContentAspect = resolveContentAspect;
+exports.normalizeLayoutM0 = normalizeLayoutM0;
+exports.validateLayoutM0 = validateLayoutM0;
+exports.resolveWatermarkRect = resolveWatermarkRect;
+exports.watermarkNeedsLumaProbe = watermarkNeedsLumaProbe;
+exports.resolveWatermarkProbeRegion = resolveWatermarkProbeRegion;
+const types_1 = require("@m0saic/types");
+const dsl_1 = require("@m0saic/dsl");
+const template_utils_1 = require("@m0saic/template-utils");
+// ── Constants ─────────────────────────────────────────────────
+/** Reference size text is measured at; fit-to-box scales linearly from it. */
+exports.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.
+ */
+exports.TEXT_WIDTH_PAD = 1.04;
+/** Canonical defaults — exported so the host prep step resolves props identically. */
+exports.WATERMARK_DEFAULTS = {
+    mode: "static",
+    content: "logo",
+    text: "yourbrand.com",
+    textColor: "#ffffff",
+    textColorOnLight: "#111111",
+    lockupLayout: "text-right",
+    position: "bottom-right",
+    sizeRatio: 0.18,
+    sizeBasis: "min",
+    marginRatio: 0.022,
+    opacity: 0.85,
+    imageOutputFormat: "match",
+    // adaptive
+    variant: "auto",
+    windowing: "always",
+    fadeMs: 400,
+    crossfadeMs: 400,
+    lumaThreshold: 128,
+    minGapMs: 3000,
+    // page mode
+    angleDeg: -30,
+    tileGapRatio: 0.08,
+    stagger: true,
+    maxTiles: 24,
+    debugLayout: false,
+};
+// ── Lockup geometry constants ─────────────────────────────────
+/** Text height as a fraction of the lockup's logo height. */
+exports.LOCKUP_TEXT_TO_LOGO = 0.28;
+/** Gap between logo and text (text-right), fraction of lockup height. */
+exports.LOCKUP_GAP = 0.15;
+/** Logo band height (text-below), fraction of lockup height. */
+exports.LOCKUP_LOGO_BAND = 0.78;
+/** Text band height (text-below), fraction of lockup height. */
+exports.LOCKUP_TEXT_BAND = 0.22;
+/**
+ * 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.
+ */
+function lockupAspect(aL, aT, layout) {
+    if (layout === "text-below") {
+        return Math.max(aL * exports.LOCKUP_LOGO_BAND, aT * exports.LOCKUP_TEXT_BAND);
+    }
+    return aL + exports.LOCKUP_GAP + aT * exports.LOCKUP_TEXT_TO_LOGO;
+}
+// ── Content aspect ────────────────────────────────────────────
+/** Measured intrinsic aspect (w/h) of a text wordmark. */
+function textContentAspect(text) {
+    const m = (0, template_utils_1.measureText)(text, { fontSize: exports.REF_FONT_PX });
+    if (!(m.width > 0) || !(m.height > 0)) {
+        throw new Error("Watermark text measures to an empty box — provide non-empty text.");
+    }
+    return (m.width * exports.TEXT_WIDTH_PAD) / m.height;
+}
+function resolveLogoAspect(image, media, logoDims) {
+    if (!image) {
+        throw new Error('Watermark needs a logo image for this content — pick your logo file, or switch content to "text".');
+    }
+    const dims = logoDims !== null && logoDims !== void 0 ? logoDims : media[(0, types_1.asAssetId)(image)];
+    if (!dims || !(dims.width > 0) || !(dims.height > 0)) {
+        throw new Error(`Watermark logo has no probed dimensions (${image}) — is it a readable image file?`);
+    }
+    const kind = dims.kind;
+    if (kind !== undefined && kind !== "image") {
+        throw new Error(`Watermark logo must be an image, got kind "${kind}" (${image}).`);
+    }
+    return dims.width / dims.height;
+}
+function resolveTextAspect(props) {
+    var _a;
+    const text = ((_a = props.text) !== null && _a !== void 0 ? _a : exports.WATERMARK_DEFAULTS.text).trim();
+    if (!text) {
+        throw new Error('Watermark text is empty — provide the wordmark text.');
+    }
+    return textContentAspect(text);
+}
+/**
+ * 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.
+ */
+function resolveContentInfo(props, ctx, logoDims) {
+    var _a;
+    const content = (_a = props.content) !== null && _a !== void 0 ? _a : exports.WATERMARK_DEFAULTS.content;
+    if (content === "logo") {
+        const logoAspect = resolveLogoAspect(props.image, ctx.media, logoDims);
+        return { aspect: logoAspect, logoAspect };
+    }
+    if (content === "text") {
+        const textAspect = resolveTextAspect(props);
+        return { aspect: textAspect, textAspect };
+    }
+    if (content === "lockup") {
+        const logoAspect = resolveLogoAspect(props.image, ctx.media, logoDims);
+        const textAspect = resolveTextAspect(props);
+        const layout = props.lockupLayout === "text-below" ? "text-below" : "text-right";
+        return { aspect: lockupAspect(logoAspect, textAspect, layout), logoAspect, textAspect };
+    }
+    throw new Error(`Watermark content "${content}" is not recognized.`);
+}
+/** Back-compat shim: the artwork's combined intrinsic aspect. */
+function resolveContentAspect(props, ctx, logoDims) {
+    return resolveContentInfo(props, ctx, logoDims).aspect;
+}
+// ── m0 escape hatch ───────────────────────────────────────────
+/**
+ * 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`.)
+ */
+function normalizeLayoutM0(raw) {
+    if (!raw)
+        return null;
+    const m0 = raw
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith("#"))
+        .join("");
+    return m0.length > 0 ? m0 : null;
+}
+/**
+ * Validate the escape-hatch layout string (canvas-independent checks).
+ * Throws a user-facing error on invalid strings or frame counts.
+ */
+function validateLayoutM0(m0) {
+    if (!(0, dsl_1.isValidM0String)(m0)) {
+        throw new Error("Watermark layout is not a valid m0 string.");
+    }
+    const frames = (0, dsl_1.getFrameCount)(m0);
+    if (frames !== 1) {
+        throw new Error(`Watermark layout must resolve to exactly ONE frame (got ${frames !== null && frames !== void 0 ? frames : "unknown"}) — carve the box with \`-\` null tiles.`);
+    }
+}
+/**
+ * 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.
+ */
+function resolveWatermarkRect(knobs, canvasW, canvasH, contentAspect) {
+    if (knobs.layoutM0) {
+        validateLayoutM0(knobs.layoutM0);
+        const f = (0, dsl_1.parseM0StringToRenderFrames)(knobs.layoutM0, canvasW, canvasH)[0];
+        if (!f) {
+            throw new Error("Watermark layout produced no frame at this canvas size.");
+        }
+        const x = clamp(Math.round(f.x), 0, canvasW - 1);
+        const y = clamp(Math.round(f.y), 0, canvasH - 1);
+        const w = clamp(Math.round(f.width), 1, canvasW - x);
+        const h = clamp(Math.round(f.height), 1, canvasH - y);
+        return { x, y, w, h };
+    }
+    return (0, template_utils_1.resolveStampRect)({
+        canvasW,
+        canvasH,
+        position: knobs.position,
+        sizeRatio: knobs.sizeRatio,
+        sizeBasis: knobs.sizeBasis,
+        marginRatio: knobs.marginRatio,
+        contentAspect,
+    });
+}
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}
+// ── Host prep gating (adaptive luma) ──────────────────────────
+/**
+ * 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).
+ */
+function watermarkNeedsLumaProbe(props) {
+    var _a, _b;
+    const mode = (_a = props.mode) !== null && _a !== void 0 ? _a : exports.WATERMARK_DEFAULTS.mode;
+    const variant = (_b = props.variant) !== null && _b !== void 0 ? _b : exports.WATERMARK_DEFAULTS.variant;
+    return mode === "adaptive" && variant === "auto";
+}
+/**
+ * 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.
+ */
+function resolveWatermarkProbeRegion(props, canvasW, canvasH, logoDims) {
+    var _a, _b, _c, _d;
+    const aspect = resolveContentAspect(props, { media: {} }, logoDims);
+    const rect = resolveWatermarkRect({
+        position: (_a = props.position) !== null && _a !== void 0 ? _a : exports.WATERMARK_DEFAULTS.position,
+        sizeRatio: (_b = props.sizeRatio) !== null && _b !== void 0 ? _b : exports.WATERMARK_DEFAULTS.sizeRatio,
+        sizeBasis: (_c = props.sizeBasis) !== null && _c !== void 0 ? _c : exports.WATERMARK_DEFAULTS.sizeBasis,
+        marginRatio: (_d = props.marginRatio) !== null && _d !== void 0 ? _d : exports.WATERMARK_DEFAULTS.marginRatio,
+        layoutM0: normalizeLayoutM0(props.layoutM0),
+    }, canvasW, canvasH, aspect);
+    const xPct = Math.max(0, (rect.x - 0.05 * rect.w) / canvasW);
+    const yPct = Math.max(0, (rect.y - 0.05 * rect.h) / canvasH);
+    return {
+        xPct,
+        yPct,
+        wPct: Math.min(1 - xPct, (1.1 * rect.w) / canvasW),
+        hPct: Math.min(1 - yPct, (1.1 * rect.h) / canvasH),
+    };
+}

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

@@ -0,0 +1,3 @@
+export { WatermarkV1 } from "./watermark";
+export type { WatermarkV1Props, WatermarkMode, WatermarkContent } from "./watermark";
+export type { WatermarkLumaEntry } from "./adaptive";

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

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

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

@@ -0,0 +1,105 @@
+/**
+ * Page-mode grid planner + pattern-child builder: the diagonal repeated
+ * logo/wordmark across the whole canvas (document-style DRAFT /
+ * CONFIDENTIAL watermark).
+ *
+ * # Geometry (why per-instance rotation)
+ *
+ * `effects.rotate` runs AFTER scale-to-cell, in place, with transparent
+ * corner fill — rotating one full-canvas layer would leave transparent
+ * corner triangles. Instead each instance cell holds the content's
+ * envelope across BOTH rotation phases: the content is drawn unrotated
+ * first (needs w×h), then rotated in place (needs the rotated bbox
+ * w·|cosθ|+h·|sinθ| × w·|sinθ|+h·|cosθ| — which for slender content at
+ * shallow angles is NARROWER than w, so neither box alone suffices):
+ *
+ *   cw = ceil(max(w, w·|cosθ| + h·|sinθ|))
+ *   ch = ceil(max(h, w·|sinθ| + h·|cosθ|))
+ *
+ * The centering CANNOT use `placement.inset` or contain-letterboxing:
+ * the engine shrinks the destination box (inset/padding) BEFORE the
+ * scale, and `contain` scales to content-fitted dims — either way the
+ * buffer `effects.rotate` runs on is CONTENT-sized and the rotation
+ * clips at the content box (ffmpegCommands.ts: inset at ~1055, scale
+ * `decrease` at ~1185, applyTileEffects on the scaled label at ~1196;
+ * the pad-to-cell happens after the effects chain). The only cell-sized
+ * pre-rotation buffer is a NESTED CHILD whose declared `size` equals
+ * the cell — children render at their declared dims, so the padding is
+ * baked in as real geometry (a centered placeRect + null tiles) and the
+ * 1:1 contain scale preserves it through the rotation.
+ *
+ * # Walls
+ *
+ * The pattern renders as its OWN engine command (nested child), so the
+ * parent's overlay depth stays 1. Inside the pattern, cells are
+ * non-overlapping structural siblings (placeRects single layer) capped
+ * at `maxTiles ≤ 24` — under the ~25-overlay mask-drop wall (W3), and
+ * with no per-cell alpha/enable/blend they stay xstack-sheet-eligible.
+ * Text/lockup content is ONE shared nested child referenced per cell,
+ * so its inline-mask path travels once (W6 argv budget).
+ */
+import type { MosaicDocument } from "@m0saic/types";
+import type { StampRectPx } from "@m0saic/template-utils";
+export type PageGridKnobs = {
+    canvasW: number;
+    canvasH: number;
+    /** Unrotated instance content size (from the sizeRatio math). */
+    contentW: number;
+    contentH: number;
+    /** Rotation angle, degrees clockwise. */
+    angleDeg: number;
+    /** Gap between instance cells, fraction of min(W, H). */
+    tileGapRatio: number;
+    /** Offset alternate rows by half the horizontal pitch. */
+    stagger: boolean;
+    /** Hard instance budget (W3 wall). */
+    maxTiles: number;
+};
+export type PageGridPlan = {
+    /** Instance cells (envelope sized), row-major. */
+    cells: StampRectPx[];
+    /** Cell dims (the content's two-phase rotation envelope). */
+    cellW: number;
+    cellH: number;
+    /** Effective unrotated content dims (may shrink so the envelope fits the canvas). */
+    contentW: number;
+    contentH: number;
+    /** Resolved gap (grows deterministically to satisfy maxTiles). */
+    gapPx: number;
+    rows: number;
+    cols: number;
+};
+/**
+ * Plan the staggered instance grid. Deterministic: the tile budget is
+ * enforced by growing the gap (strictly increasing), and cells that
+ * would cross the canvas edge are dropped — the edge margin is the
+ * classic page-watermark look.
+ */
+export declare function planPageGrid(k: PageGridKnobs): PageGridPlan;
+/**
+ * Wrap the content child in a cell-sized child with the padding baked
+ * in as real geometry: a centered `placeRect` frame holds the art, the
+ * null tiles ARE the (transparent) rotation headroom. This child's
+ * declared size == the cell, so the pre-rotation buffer is cell-sized
+ * (see header). When the envelope equals the content (angle 0), the
+ * wrapper is skipped — the art child is already cell-sized.
+ */
+export declare function buildPaddedInstanceChild(opts: {
+    plan: PageGridPlan;
+    /** The watermark art child at (plan.contentW × plan.contentH). */
+    art: MosaicDocument;
+}): MosaicDocument;
+/**
+ * Build the full-canvas pattern child: the planned grid of rotated
+ * instances, each referencing ONE shared cell-sized instance child.
+ * The parent composites this ONE pattern child (its own engine
+ * command) with the pattern opacity applied at the parent source.
+ */
+export declare function buildPagePatternChild(opts: {
+    canvasW: number;
+    canvasH: number;
+    plan: PageGridPlan;
+    angleDeg: number;
+    /** Cell-sized instance child (see {@link buildPaddedInstanceChild}). */
+    instance: MosaicDocument;
+}): MosaicDocument;

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

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Page-mode grid planner + pattern-child builder: the diagonal repeated
+ * logo/wordmark across the whole canvas (document-style DRAFT /
+ * CONFIDENTIAL watermark).
+ *
+ * # Geometry (why per-instance rotation)
+ *
+ * `effects.rotate` runs AFTER scale-to-cell, in place, with transparent
+ * corner fill — rotating one full-canvas layer would leave transparent
+ * corner triangles. Instead each instance cell holds the content's
+ * envelope across BOTH rotation phases: the content is drawn unrotated
+ * first (needs w×h), then rotated in place (needs the rotated bbox
+ * w·|cosθ|+h·|sinθ| × w·|sinθ|+h·|cosθ| — which for slender content at
+ * shallow angles is NARROWER than w, so neither box alone suffices):
+ *
+ *   cw = ceil(max(w, w·|cosθ| + h·|sinθ|))
+ *   ch = ceil(max(h, w·|sinθ| + h·|cosθ|))
+ *
+ * The centering CANNOT use `placement.inset` or contain-letterboxing:
+ * the engine shrinks the destination box (inset/padding) BEFORE the
+ * scale, and `contain` scales to content-fitted dims — either way the
+ * buffer `effects.rotate` runs on is CONTENT-sized and the rotation
+ * clips at the content box (ffmpegCommands.ts: inset at ~1055, scale
+ * `decrease` at ~1185, applyTileEffects on the scaled label at ~1196;
+ * the pad-to-cell happens after the effects chain). The only cell-sized
+ * pre-rotation buffer is a NESTED CHILD whose declared `size` equals
+ * the cell — children render at their declared dims, so the padding is
+ * baked in as real geometry (a centered placeRect + null tiles) and the
+ * 1:1 contain scale preserves it through the rotation.
+ *
+ * # Walls
+ *
+ * The pattern renders as its OWN engine command (nested child), so the
+ * parent's overlay depth stays 1. Inside the pattern, cells are
+ * non-overlapping structural siblings (placeRects single layer) capped
+ * at `maxTiles ≤ 24` — under the ~25-overlay mask-drop wall (W3), and
+ * with no per-cell alpha/enable/blend they stay xstack-sheet-eligible.
+ * Text/lockup content is ONE shared nested child referenced per cell,
+ * so its inline-mask path travels once (W6 argv budget).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planPageGrid = planPageGrid;
+exports.buildPaddedInstanceChild = buildPaddedInstanceChild;
+exports.buildPagePatternChild = buildPagePatternChild;
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+// ── planPageGrid ──────────────────────────────────────────────
+/**
+ * Plan the staggered instance grid. Deterministic: the tile budget is
+ * enforced by growing the gap (strictly increasing), and cells that
+ * would cross the canvas edge are dropped — the edge margin is the
+ * classic page-watermark look.
+ */
+function planPageGrid(k) {
+    const { canvasW: W, canvasH: H, angleDeg, tileGapRatio, stagger, maxTiles } = k;
+    if (!(k.contentW > 0) || !(k.contentH > 0)) {
+        throw new Error(`planPageGrid: content dims must be positive, got ${k.contentW}x${k.contentH}`);
+    }
+    if (!Number.isInteger(maxTiles) || maxTiles < 1) {
+        throw new Error(`planPageGrid: maxTiles must be a positive integer, got ${maxTiles}`);
+    }
+    const rad = (angleDeg * Math.PI) / 180;
+    const cos = Math.abs(Math.cos(rad));
+    const sin = Math.abs(Math.sin(rad));
+    // Envelope across both rotation phases (see header) — never smaller
+    // than the content on either axis, so insets stay non-negative.
+    const envW = (w, h) => Math.ceil(Math.max(w, w * cos + h * sin));
+    const envH = (w, h) => Math.ceil(Math.max(h, w * sin + h * cos));
+    // Shrink the content (aspect preserved) until its cell envelope fits
+    // the canvas — a large sizeRatio at a steep angle can overflow.
+    let contentW = Math.max(1, Math.round(k.contentW));
+    let contentH = Math.max(1, Math.round(k.contentH));
+    {
+        const scale = Math.min(1, W / envW(contentW, contentH), H / envH(contentW, contentH));
+        if (scale < 1) {
+            contentW = Math.max(1, Math.floor(contentW * scale));
+            contentH = Math.max(1, Math.floor(contentH * scale));
+        }
+    }
+    const cellW = Math.min(W, envW(contentW, contentH));
+    const cellH = Math.min(H, envH(contentW, contentH));
+    const min2 = Math.min(W, H);
+    let gapPx = Math.max(0, Math.round(tileGapRatio * min2));
+    const gridFor = (gap) => {
+        const pitchX = cellW + gap;
+        const pitchY = cellH + gap;
+        const cols = Math.max(1, Math.floor((W - cellW) / pitchX) + 1);
+        const rows = Math.max(1, Math.floor((H - cellH) / pitchY) + 1);
+        return { pitchX, pitchY, cols, rows };
+    };
+    // Deterministic budget loop: strictly-increasing gap → rows*cols
+    // shrinks monotonically toward 1×1 ≤ maxTiles.
+    let grid = gridFor(gapPx);
+    while (grid.rows * grid.cols > maxTiles) {
+        gapPx = Math.max(gapPx + 1, Math.ceil(gapPx * 1.25));
+        grid = gridFor(gapPx);
+    }
+    const { pitchX, pitchY, cols, rows } = grid;
+    const spanW = cols * cellW + (cols - 1) * gapPx;
+    const spanH = rows * cellH + (rows - 1) * gapPx;
+    const x0 = Math.max(0, Math.floor((W - spanW) / 2));
+    const y0 = Math.max(0, Math.floor((H - spanH) / 2));
+    const cells = [];
+    for (let r = 0; r < rows; r++) {
+        const rowOffset = stagger && r % 2 === 1 ? Math.floor(pitchX / 2) : 0;
+        for (let c = 0; c < cols; c++) {
+            const x = x0 + c * pitchX + rowOffset;
+            const y = y0 + r * pitchY;
+            if (x + cellW > W || y + cellH > H)
+                continue; // stagger pushes the row's last cell out
+            cells.push({ x, y, w: cellW, h: cellH });
+        }
+    }
+    return { cells, cellW, cellH, contentW, contentH, gapPx, rows, cols };
+}
+// ── buildPaddedInstanceChild ──────────────────────────────────
+/**
+ * Wrap the content child in a cell-sized child with the padding baked
+ * in as real geometry: a centered `placeRect` frame holds the art, the
+ * null tiles ARE the (transparent) rotation headroom. This child's
+ * declared size == the cell, so the pre-rotation buffer is cell-sized
+ * (see header). When the envelope equals the content (angle 0), the
+ * wrapper is skipped — the art child is already cell-sized.
+ */
+function buildPaddedInstanceChild(opts) {
+    const { plan, art } = opts;
+    if (plan.cellW === plan.contentW && plan.cellH === plan.contentH)
+        return art;
+    const { m0 } = (0, dsl_stdlib_1.placeRect)({
+        rootW: plan.cellW,
+        rootH: plan.cellH,
+        rectW: plan.contentW,
+        rectH: plan.contentH,
+        // centered (placeRect default) — rotation is about the cell center
+    });
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)(String(m0), "WatermarkPageInstance"),
+        sources: [
+            {
+                type: "mosaic",
+                ref: "wm_art",
+                placement: { fit: "contain" },
+                editor: { owner: "template", label: "wm:art" },
+            },
+        ],
+        assets: {},
+        children: { wm_art: art },
+        size: { width: plan.cellW, height: plan.cellH },
+    };
+}
+// ── buildPagePatternChild ─────────────────────────────────────
+/**
+ * Build the full-canvas pattern child: the planned grid of rotated
+ * instances, each referencing ONE shared cell-sized instance child.
+ * The parent composites this ONE pattern child (its own engine
+ * command) with the pattern opacity applied at the parent source.
+ */
+function buildPagePatternChild(opts) {
+    const { canvasW, canvasH, plan, angleDeg, instance } = opts;
+    if (plan.cells.length === 0) {
+        throw new Error("buildPagePatternChild: the grid plan produced no cells");
+    }
+    const declared = instance.size;
+    if (!declared || declared.width !== plan.cellW || declared.height !== plan.cellH) {
+        throw new Error(`buildPagePatternChild: instance child must declare size ${plan.cellW}x${plan.cellH} ` +
+            `(got ${declared === null || declared === void 0 ? void 0 : declared.width}x${declared === null || declared === void 0 ? void 0 : declared.height}) — a non-cell-sized child re-letterboxes and the rotation clips`);
+    }
+    const placed = (0, dsl_stdlib_1.placeRects)({
+        rootW: canvasW,
+        rootH: canvasH,
+        rects: plan.cells.map((c) => ({ x: c.x, y: c.y, w: c.w, h: c.h, claimant: "F" })),
+    });
+    const effects = angleDeg !== 0 ? { rotate: angleDeg } : undefined;
+    const instanceSource = (i) => ({
+        type: "mosaic",
+        ref: "wm_content",
+        // 1:1 — instance size == cell size, so contain is an exact fit and
+        // the effects chain sees the full cell-sized buffer.
+        placement: { fit: "contain" },
+        ...(effects ? { effects } : {}),
+        editor: { owner: "template", label: `wm:tile:${i}` },
+    });
+    // sources[i] binds to the i-th PAINTED frame: within a placeRects
+    // layer, frames paint in band order (top→bottom, left→right) — sort
+    // each layer's rect indices by y then x (the commit-feed idiom).
+    const sources = [];
+    for (const layer of placed.layers) {
+        const ordered = [...layer.rectIndices].sort((a, b) => plan.cells[a].y - plan.cells[b].y || plan.cells[a].x - plan.cells[b].x);
+        for (const idx of ordered)
+            sources.push(instanceSource(idx));
+    }
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)(String(placed.m0), "WatermarkPagePattern"),
+        sources,
+        assets: {},
+        children: { wm_content: instance },
+        size: { width: canvasW, height: canvasH },
+    };
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 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`).
+ */
+import type { MosaicColor, MosaicEngineContext, MosaicPipelineStep } from "@m0saic/types";
+import { type StampPosition } from "@m0saic/template-utils";
+import { type LockupLayout, type WatermarkContentInfo } from "./geometry";
+import { type WatermarkLumaEntry } from "./adaptive";
+/** Fixed duration for image steps — a single-frame render. */
+export declare const IMAGE_STEP_MS = 40;
+/** Duration used for error-mosaic steps (input problems). */
+export declare const ERROR_STEP_MS = 1000;
+/** Resolved knobs a step needs (validated once by the template). */
+export type WatermarkStepKnobs = {
+    mode: "static" | "adaptive" | "page";
+    content: "logo" | "text" | "lockup";
+    /** Logo file path (content: "logo" | "lockup"). */
+    image?: string;
+    /** Dark-scene logo variant (adaptive auto). */
+    imageDark?: string;
+    /** Wordmark text (content: "text" | "lockup"). */
+    text: string;
+    textColor: MosaicColor;
+    /** Wordmark color over bright regions (adaptive auto). */
+    textColorOnLight: MosaicColor;
+    lockupLayout: LockupLayout;
+    position: StampPosition;
+    sizeRatio: number;
+    sizeBasis: "min" | "width" | "height";
+    marginRatio: number;
+    opacity: number;
+    /** Normalized escape-hatch m0 (already string-validated; stamp modes only). */
+    layoutM0: string | null;
+    imageOutputFormat: "match" | "png" | "jpeg";
+    /** Intrinsic aspect facts of the watermark artwork (resolved once). */
+    contentInfo: WatermarkContentInfo;
+    variant: "single" | "auto";
+    windowing: "always" | "windows";
+    fadeMs: number;
+    crossfadeMs: number;
+    lumaThreshold: number;
+    minGapMs: number;
+    coverageOverride?: number;
+    /** Host-injected per-input luma probe results, keyed by raw input path. */
+    lumaByInput?: Record<string, WatermarkLumaEntry>;
+    angleDeg: number;
+    tileGapRatio: number;
+    stagger: boolean;
+    maxTiles: number;
+    /** Dev tripwire: run the layout contract on each step doc. */
+    debugLayout: boolean;
+};
+/**
+ * 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.
+ */
+export declare function buildWatermarkStep(args: {
+    inputPath: string;
+    stepName: string;
+    knobs: WatermarkStepKnobs;
+    ctx: MosaicEngineContext;
+}): MosaicPipelineStep;