@m0saic/templates 0.2.0

package/dist/m0saic/media/blur-regions/v1/blur-regions.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * Easy Blur — `@m0saic/media/blur-regions/v1`.
+ *
+ * Pick one video OR image, draw one or more rectangles over the areas
+ * to hide (the `picker: "regions"` draw-on-canvas editor, or
+ * hand-authored `--props` JSON), and get the same media back with those
+ * regions blurred or pixelated — audio intact on video, canvas matched
+ * to the probed source, container following the user's `-o` extension.
+ * Image inputs render as a single frame (watermark precedent).
+ *
+ * The result is a 1-step `emit:"multi"` pipeline, NOT a plain document:
+ * only a pipeline step's canvas tracks the input's probed dims (a plain
+ * document's `size` is overridden by explicit CLI `-w`/`-h`, which
+ * would misalign the mask regions against the re-fitted content). The
+ * planner collapses the single step to the bare `-o` file and the
+ * per-step format is inert — the `-o` extension wins (highlights
+ * single-range + watermark precedents).
+ *
+ * First adopter of the `picker: "regions"` prop contract
+ * (`MosaicRegionsValue` in `@m0saic/types`): integer px in the authored
+ * canvas, optional `canvas` wrapper for rescaling, missing `kind` =
+ * rect. Regions drawn in Make arrive in the preview canvas (= probed
+ * video dims once a source is picked); hand-authored regions may omit
+ * `canvas` and are read as px in the video's own canvas. The m0-native
+ * flavor (`{ m0 }` or a bare m0 string) takes a LAYOUT whose leaf cells
+ * are the regions — a series of rects is always expressible as m0.
+ *
+ * By default the regions become REAL m0 geometry (`geometry: "inset"`,
+ * via placeInsetPieces): each region is a cell whose source shows the
+ * exact media window underneath it (`placement.sourceRect` — this
+ * template is the primitive's first consumer) with the effect applied —
+ * visible and selectable in every m0 surface. `"exact"` trades DSL
+ * length for exact cells; `"mask"` keeps the original full-canvas
+ * inline-mask overlay (no geometry, cheapest for many regions).
+ *
+ * ZERO regions is the working BASE CASE, not an error: pick a source
+ * and the preview shows it untouched — that's the surface the user
+ * draws on. Fail-fast posture for what IS provided: any invalid region
+ * (entirely outside the canvas, degenerate size) fails the WHOLE render
+ * rather than silently dropping it — this is a privacy feature;
+ * partially-applied censoring must never ship quietly. Overshoot that
+ * still intersects the canvas is clamped, not rejected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlurRegions = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const tutorial_1 = require("./tutorial");
+const plan_1 = require("./plan");
+const onboarding_cover_1 = require("../../../_shared/onboarding-cover");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    sourceId: {
+        type: "media",
+        required: true,
+        description: "The video or image to blur regions of.",
+        meta: {
+            ui: { label: "Source", order: 1 },
+            control: { picker: "file", accept: ["video", "image"] },
+        },
+    },
+    regions: {
+        type: "json",
+        // Not required: "nothing drawn yet" is the working base case — the
+        // preview shows the untouched media as the drawing surface.
+        required: false,
+        description: "Areas to hide — draw them on the preview. For pixel-precise placement, " +
+            "the JSON escape hatch takes " +
+            '{ "canvas": { "w", "h" }, "regions": [{ "x", "y", "w", "h" }, …] }, ' +
+            "integer px (omit canvas to give px in the media's own canvas; overshoot " +
+            "is clamped). No regions = the media passes through untouched.",
+        meta: {
+            constraints: {
+                jsonSchema: {
+                    type: "object",
+                    properties: {
+                        canvas: {
+                            type: "object",
+                            required: ["w", "h"],
+                            properties: {
+                                w: { type: "integer", minimum: 1 },
+                                h: { type: "integer", minimum: 1 },
+                            },
+                        },
+                        regions: {
+                            type: "array",
+                            maxItems: plan_1.MAX_REGIONS,
+                            items: {
+                                type: "object",
+                                required: ["x", "y", "w", "h"],
+                                properties: {
+                                    kind: { type: "string", enum: ["rect"] },
+                                    x: { type: "integer", minimum: 0 },
+                                    y: { type: "integer", minimum: 0 },
+                                    w: { type: "integer", minimum: 1 },
+                                    h: { type: "integer", minimum: 1 },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            control: {
+                picker: "regions",
+                regions: { max: plan_1.MAX_REGIONS, shapes: ["rect", "ellipse", "polygon", "lasso", "brush"] },
+            },
+            ui: { label: "Blur regions", order: 2, primary: true },
+        },
+    },
+    mode: {
+        type: "string",
+        required: false,
+        description: 'Effect style: "blur" (gaussian, default) or "pixelate" (censor blocks).',
+        meta: {
+            constraints: { oneOf: ["blur", "pixelate"] },
+            ui: { label: "Style", order: 3 },
+        },
+    },
+    strength: {
+        type: "number",
+        required: false,
+        description: "Effect strength. Blur: gaussian sigma in px (1-200). Pixelate: block size in px (2-128). Default 24.",
+        meta: {
+            constraints: { min: plan_1.BLUR_SIGMA_MIN, max: plan_1.BLUR_SIGMA_MAX },
+            control: { flavor: "slider" },
+            ui: { label: "Strength", order: 4 },
+        },
+    },
+    geometry: {
+        type: "string",
+        required: false,
+        description: 'How regions become document structure. "inset" (default): real m0 cells on a compact lattice, insets recover exact bounds. ' +
+            '"exact": real m0 cells at exact px (longer DSL). "mask": one masked full-canvas overlay — no region geometry in the m0, ' +
+            "cheapest render for many regions, softest region edges.",
+        meta: {
+            constraints: { oneOf: ["inset", "exact", "mask"] },
+            ui: { label: "Geometry", order: 5 },
+        },
+    },
+});
+const DEFAULTS = {
+    mode: "blur",
+    strength: 24,
+    geometry: "inset",
+};
+const ERROR_TITLE = "Easy Blur";
+exports.BlurRegions = {
+    id: (0, types_1.asTemplateId)("@m0saic/media/blur-regions/v1"),
+    label: "Easy Blur",
+    description: "Pick a video or image, draw boxes over what should stay hidden — faces, plates, names — and get the same media back with those regions blurred or pixelated. Audio untouched.",
+    version: 1,
+    capabilities: { tier: "core" },
+    tags: ["media", "blur", "privacy", "redact", "pixelate", "creators", "animated", "face-blur", "anonymize", "video"],
+    // No `format` hint on purpose — the container follows the user's `-o`
+    // extension (highlights precedent).
+    outputHints: {
+        format: { kind: "video", container: "mp4" },
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 5000,
+    },
+    propsSchema,
+    defaultProps: { ...DEFAULTS },
+    async render(props, ctx) {
+        var _a;
+        const fail = (message) => (0, template_utils_1.makeErrorMosaic)(message, {
+            title: ERROR_TITLE,
+            width: ctx.target.width,
+            height: ctx.target.height,
+        });
+        const sourceId = props.sourceId;
+        if (!sourceId) {
+            return fail('Missing required "Source": pick the video or image to blur regions of.');
+        }
+        if (props.mode !== undefined && props.mode !== "blur" && props.mode !== "pixelate") {
+            return fail(`Unsupported mode "${String(props.mode)}" — use "blur" or "pixelate".`);
+        }
+        if (props.geometry !== undefined &&
+            props.geometry !== "inset" &&
+            props.geometry !== "exact" &&
+            props.geometry !== "mask") {
+            return fail(`Unsupported geometry "${String(props.geometry)}" — use "inset", "exact", or "mask".`);
+        }
+        const geometry = (_a = props.geometry) !== null && _a !== void 0 ? _a : "inset";
+        const parsed = (0, template_utils_1.parseRegionsValue)(props.regions);
+        if (!parsed.ok) {
+            return fail(parsed.error);
+        }
+        // Zero regions is NOT an error: it's the drawing base case — the
+        // media renders untouched so the user can see it and draw on it.
+        if (parsed.regions.length > plan_1.MAX_REGIONS) {
+            return fail(`Too many regions (${parsed.regions.length}) — the cap is ${plan_1.MAX_REGIONS}.`);
+        }
+        const meta = ctx.media[(0, types_1.asAssetId)(sourceId)];
+        if (!meta || !(meta.width > 0) || !(meta.height > 0)) {
+            return fail(`No probed dimensions for input: ${sourceId}`);
+        }
+        if (meta.kind !== "video" && meta.kind !== "image") {
+            return fail(`Easy Blur needs a video or image input (kind: ${meta.kind}): ${sourceId}`);
+        }
+        const isVideo = meta.kind === "video";
+        if (isVideo && !(meta.durationMs != null && meta.durationMs > 0)) {
+            return fail(`Video input has no probed duration: ${sourceId}`);
+        }
+        const size = { width: (0, plan_1.evenRound)(meta.width), height: (0, plan_1.evenRound)(meta.height) };
+        let rectsPx;
+        if (parsed.m0 !== undefined) {
+            // m0-native flavor: leaf cells at the media's canvas ARE the
+            // regions — resolution-independent, exact by construction.
+            rectsPx = (0, template_utils_1.regionRectsFromM0)(parsed.m0, size);
+            if (rectsPx.length > plan_1.MAX_REGIONS) {
+                return fail(`Too many regions (${rectsPx.length} m0 leaves) — the cap is ${plan_1.MAX_REGIONS}.`);
+            }
+        }
+        else {
+            const verdicts = (0, template_utils_1.resolveRegionsToPx)(parsed, size);
+            const firstBad = verdicts.findIndex((v) => !v.ok);
+            if (firstBad !== -1) {
+                const bad = verdicts[firstBad];
+                // Privacy posture: never silently drop a drawn region (see header).
+                return fail(`Region ${firstBad + 1} invalid: ${bad.ok ? "" : bad.reason}. Fix or remove it — regions are never silently dropped.`);
+            }
+            rectsPx = verdicts.map((v) => v.ok
+                ? { x: v.x, y: v.y, w: v.w, h: v.h, ...(v.mask ? { mask: v.mask } : {}) }
+                : { x: 0, y: 0, w: 0, h: 0 });
+        }
+        const knobs = (0, plan_1.resolveBlurRegionsKnobs)(props);
+        const fps = isVideo && meta.fps != null && meta.fps > 0
+            ? Math.max(1, Math.round(meta.fps))
+            : undefined;
+        let step;
+        try {
+            step = (0, plan_1.buildBlurRegionsStep)({
+                inputPath: sourceId,
+                stepBaseName: (0, template_utils_1.buildStepNames)([sourceId])[0],
+                mediaType: isVideo ? "video" : "image",
+                size,
+                ...(isVideo ? { durationMs: meta.durationMs } : {}),
+                rectsPx,
+                knobs,
+                geometry,
+            });
+        }
+        catch (err) {
+            return fail(`Region geometry failed (${geometry}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return {
+            kind: "mosaic_pipeline",
+            version: 1,
+            emit: "multi",
+            ...(fps !== undefined ? { fps } : {}),
+            steps: [step],
+        };
+    },
+    // Editor-only first-open cover. Without a picked source the default state is
+    // an error mosaic ("Missing Source") — the cover instead shows a synthetic
+    // demo: a scenic mock frame with two "pixelated" regions, above a welcome
+    // band (the metadata-stamp precedent). Adaptive band per the stat-card
+    // lesson: px-clamped height, single title-only row when the hint row can't
+    // make the engine's min-cell floor.
+    // Editor-only first-open cover — the mosaic-branding BAND: the synthetic
+    // scenic demo (sky/ridge/ground + two pixelated regions) full-bleed above
+    // the brand band (M mark · product name · title).
+    async renderCover(_props, ctx) {
+        // ── Synthetic "photo": sky / ridge / ground bands ──
+        const scene = String((0, dsl_stdlib_1.weightedSplit)([46, 22, 32], "row", { claimants: ["1", "1", "1"] }));
+        const sceneSources = [
+            (0, template_utils_1.makeColorTile)("#3b6ea5"), // sky
+            (0, template_utils_1.makeColorTile)("#5b8c5a"), // ridge
+            (0, template_utils_1.makeColorTile)("#8a7f66"), // ground
+        ];
+        // ── Two demo "pixelated" regions: 4x3 checker of two grays ──
+        const checkerRow = (a, b) => String((0, dsl_stdlib_1.weightedSplit)([1, 1, 1, 1], "col", { claimants: [a, b, a, b] }));
+        const checker = String((0, dsl_stdlib_1.weightedSplit)([1, 1, 1], "row", {
+            claimants: [checkerRow("1", "1"), checkerRow("1", "1"), checkerRow("1", "1")],
+        }));
+        const GRAYS = ["#9aa2ab", "#6f767e"];
+        const checkerSources = (flip) => Array.from({ length: 12 }, (_, i) => (0, template_utils_1.makeColorTile)(GRAYS[(i + (flip ? 1 : 0) + Math.floor(i / 4)) % 2]));
+        const placeRegion = (xPct, yPct, wPct, hPct, inner) => {
+            const col = String((0, dsl_stdlib_1.weightedSplit)([xPct, wPct, Math.max(1, 100 - xPct - wPct)], "col", { claimants: ["-", inner, "-"] }));
+            return String((0, dsl_stdlib_1.weightedSplit)([yPct, hPct, Math.max(1, 100 - yPct - hPct)], "row", { claimants: ["-", col, "-"] }));
+        };
+        const regionA = placeRegion(12, 18, 26, 30, checker);
+        const regionB = placeRegion(58, 52, 30, 34, checker);
+        const sceneStack = `${scene}{${regionA}{${regionB}}}`;
+        return (0, onboarding_cover_1.buildBrandedCover)({
+            ctx,
+            variant: "band",
+            copy: { productName: "Easy Blur", title: "Draw boxes; ship the media back censored." },
+            hero: (theme) => (0, onboarding_cover_1.onboardingFrame)({ m0: sceneStack, sources: [...sceneSources, ...checkerSources(false), ...checkerSources(true)] }, theme.borderStrong),
+        });
+    },
+    // Editor "?" tutorial: six directed beats — the draw-the-red-square action
+    // demonstrated, the brush stroke painting a mask, style/strength, render.
+    // Real Make screenshots slot in per beat via tutorial.ts's screenshot map
+    // when the founder provides captures.
+    renderTutorial(_props, ctx) {
+        return (0, tutorial_1.renderBlurRegionsTutorial)(ctx);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.BlurRegions);

package/dist/m0saic/media/blur-regions/v1/index.d.ts

@@ -0,0 +1,2 @@
+export { BlurRegions, type BlurRegionsV1Props } from "./blur-regions";
+export { buildBlurRegionsDocument, buildBlurRegionsStep, resolveBlurRegionsKnobs, stillContainer, BLUR_SIGMA_MAX, BLUR_SIGMA_MIN, DEFAULT_STRENGTH, IMAGE_STILL_MS, MAX_REGIONS, PIXELIZE_MAX, PIXELIZE_MIN, type BlurRegionRect, type BlurRegionsGeometry, type BlurRegionsKnobs, type BlurRegionsMode, } from "./plan";

package/dist/m0saic/media/blur-regions/v1/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PIXELIZE_MIN = exports.PIXELIZE_MAX = exports.MAX_REGIONS = exports.IMAGE_STILL_MS = exports.DEFAULT_STRENGTH = exports.BLUR_SIGMA_MIN = exports.BLUR_SIGMA_MAX = exports.stillContainer = exports.resolveBlurRegionsKnobs = exports.buildBlurRegionsStep = exports.buildBlurRegionsDocument = exports.BlurRegions = void 0;
+var blur_regions_1 = require("./blur-regions");
+Object.defineProperty(exports, "BlurRegions", { enumerable: true, get: function () { return blur_regions_1.BlurRegions; } });
+// NOTE: `evenRound` and `inputLabel` stay un-re-exported — trickplay's
+// and highlights' barrels already export those names and all three feed
+// the media pack's star exports.
+var plan_1 = require("./plan");
+Object.defineProperty(exports, "buildBlurRegionsDocument", { enumerable: true, get: function () { return plan_1.buildBlurRegionsDocument; } });
+Object.defineProperty(exports, "buildBlurRegionsStep", { enumerable: true, get: function () { return plan_1.buildBlurRegionsStep; } });
+Object.defineProperty(exports, "resolveBlurRegionsKnobs", { enumerable: true, get: function () { return plan_1.resolveBlurRegionsKnobs; } });
+Object.defineProperty(exports, "stillContainer", { enumerable: true, get: function () { return plan_1.stillContainer; } });
+Object.defineProperty(exports, "BLUR_SIGMA_MAX", { enumerable: true, get: function () { return plan_1.BLUR_SIGMA_MAX; } });
+Object.defineProperty(exports, "BLUR_SIGMA_MIN", { enumerable: true, get: function () { return plan_1.BLUR_SIGMA_MIN; } });
+Object.defineProperty(exports, "DEFAULT_STRENGTH", { enumerable: true, get: function () { return plan_1.DEFAULT_STRENGTH; } });
+Object.defineProperty(exports, "IMAGE_STILL_MS", { enumerable: true, get: function () { return plan_1.IMAGE_STILL_MS; } });
+Object.defineProperty(exports, "MAX_REGIONS", { enumerable: true, get: function () { return plan_1.MAX_REGIONS; } });
+Object.defineProperty(exports, "PIXELIZE_MAX", { enumerable: true, get: function () { return plan_1.PIXELIZE_MAX; } });
+Object.defineProperty(exports, "PIXELIZE_MIN", { enumerable: true, get: function () { return plan_1.PIXELIZE_MIN; } });

package/dist/m0saic/media/blur-regions/v1/plan.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Pure knobs + document builder for `@m0saic/media/blur-regions/v1`.
+ *
+ * No IO, no ffmpeg, no ctx — everything here is unit-testable in
+ * isolation (highlights' `plan.ts` precedent). Region parsing/resolving
+ * lives in `@m0saic/template-utils` (`parseRegionsValue` /
+ * `resolveRegionsToPx` / `regionsToMaskPathD`) so the next
+ * regions-consuming template reuses it; this module owns what is
+ * blur-specific: knob clamping and the two-source document shape.
+ *
+ * The mechanism (zero engine changes): `m0 "F{F}"` — the base cell shows
+ * the sharp video; ONE full-canvas overlay shows the SAME asset with the
+ * effect applied to the whole frame, alpha-clipped to the drawn regions
+ * by a multi-subpath `inline-mask`. The per-tile filter chain runs the
+ * content effect BEFORE the mask (core `applyTileEffects`), so the full
+ * frame blurs first and then clips — no crop-edge artifacts, and N
+ * regions cost one mask + one effect pass.
+ */
+import type { MosaicDocument, MosaicPipelineStep } from "@m0saic/types";
+import { type ResolvedRegionMask } from "@m0saic/template-utils";
+/** Hard cap on regions per invocation (mirrors the prop's jsonSchema). */
+export declare const MAX_REGIONS = 50;
+export type BlurRegionsMode = "blur" | "pixelate";
+/**
+ * How the regions become document structure:
+ *  - `"inset"` (default) — REAL m0 geometry via `placeInsetPieces`: cells
+ *    quantize outward to a divisor lattice (compact DSL even for
+ *    precision-pinned hand-drawn rects) and per-source `placement.inset`
+ *    recovers the exact bounds. The regions are visible/selectable in
+ *    every geometry surface (DSL view, Layout, wireframe, structure).
+ *  - `"exact"` — real m0 geometry via zero-drift `placeOptimizedPieces`
+ *    (byte-identical to `placeRects`): exact cells, no insets, DSL
+ *    length grows with the rects' pixel precision.
+ *  - `"mask"` — no region geometry: ONE full-canvas overlay of the same
+ *    media with the effect applied full-frame, alpha-clipped to the
+ *    regions by a multi-subpath inline-mask. Cheapest render for many
+ *    regions (one effect pass) and the softest region edges (the blur
+ *    samples the surrounding sharp content before clipping), but the
+ *    geometry is invisible to m0 surfaces.
+ */
+export type BlurRegionsGeometry = "inset" | "exact" | "mask";
+/** Resolved knobs the document builder needs (validated once by the template). */
+export type BlurRegionsKnobs = {
+    mode: BlurRegionsMode;
+    /** blur: gblur sigma px (1..200). pixelate: censor block px (2..128). */
+    strength: number;
+};
+export declare const DEFAULT_STRENGTH = 24;
+export declare const BLUR_SIGMA_MIN = 1;
+export declare const BLUR_SIGMA_MAX = 200;
+export declare const PIXELIZE_MIN = 2;
+export declare const PIXELIZE_MAX = 128;
+/** Resolve + clamp props to deterministic knobs. `mode` is validated
+ * (not silently coerced) by render() BEFORE this runs. */
+export declare function resolveBlurRegionsKnobs(props: {
+    mode?: BlurRegionsMode;
+    strength?: number;
+}): BlurRegionsKnobs;
+/** Nearest even integer ≥ 2 (yuv420p-safe dimensions; highlights precedent). */
+export declare function evenRound(v: number): number;
+/** Duration for image inputs — a single-frame render (watermark precedent). */
+export declare const IMAGE_STILL_MS = 40;
+/** Image container for a still input: jpeg in → jpeg out, else png
+ * (watermark's `imageOutputFormat: "match"` behavior). */
+export declare function stillContainer(inputPath: string): "png" | "jpeg";
+/**
+ * Build the document per the geometry strategy. Always: sharp base
+ * (audio passes through on video) below, effect content above, audio
+ * disabled on every effect copy so the track isn't doubled. Canvas
+ * comes from the probed source; duration and fps live on the wrapping
+ * pipeline step (see {@link buildBlurRegionsStep}).
+ *
+ * ZERO rects is the drawing base case — the user sees their media
+ * untouched and draws on the preview — so it emits a single-cell `"F"`
+ * document with only the base source regardless of strategy.
+ */
+export type BlurRegionRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Optional rect-local mask carved inside the region ("rect first,
+     * mask second") — rides onto the cell's / composite mask's geometry. */
+    mask?: ResolvedRegionMask;
+};
+export declare function buildBlurRegionsDocument(args: {
+    inputPath: string;
+    mediaType: "video" | "image";
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Integer px rects already resolved into `size` space. */
+    rectsPx: BlurRegionRect[];
+    knobs: BlurRegionsKnobs;
+    geometry: BlurRegionsGeometry;
+}): MosaicDocument;
+/**
+ * Wrap the document in ONE pipeline step. A pipeline step is the only
+ * vehicle where the output's canvas tracks the input's probed dims — a
+ * plain returned document's `size` is overridden by an explicit CLI
+ * `-w`/`-h` (or the app's Width/Height fields), which would misalign
+ * the mask regions against the re-fitted content (watermark precedent,
+ * its pipeline.ts header). Under a 1-output-step `emit:"multi"` the
+ * planner collapses to the bare `-o` file and the per-step format is
+ * inert — the user's `-o` extension wins (highlights single-range
+ * precedent).
+ */
+export declare function buildBlurRegionsStep(args: {
+    inputPath: string;
+    stepBaseName: string;
+    mediaType: "video" | "image";
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Probed video duration; ignored for images (IMAGE_STILL_MS). */
+    durationMs?: number;
+    rectsPx: BlurRegionRect[];
+    knobs: BlurRegionsKnobs;
+    geometry: BlurRegionsGeometry;
+}): MosaicPipelineStep;
+/** Input basename without directory or extension — the step label.
+ * Local (not node:path) so the template stays web-bundle clean. */
+export declare function inputLabel(p: string): string;

package/dist/m0saic/media/blur-regions/v1/plan.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Pure knobs + document builder for `@m0saic/media/blur-regions/v1`.
+ *
+ * No IO, no ffmpeg, no ctx — everything here is unit-testable in
+ * isolation (highlights' `plan.ts` precedent). Region parsing/resolving
+ * lives in `@m0saic/template-utils` (`parseRegionsValue` /
+ * `resolveRegionsToPx` / `regionsToMaskPathD`) so the next
+ * regions-consuming template reuses it; this module owns what is
+ * blur-specific: knob clamping and the two-source document shape.
+ *
+ * The mechanism (zero engine changes): `m0 "F{F}"` — the base cell shows
+ * the sharp video; ONE full-canvas overlay shows the SAME asset with the
+ * effect applied to the whole frame, alpha-clipped to the drawn regions
+ * by a multi-subpath `inline-mask`. The per-tile filter chain runs the
+ * content effect BEFORE the mask (core `applyTileEffects`), so the full
+ * frame blurs first and then clips — no crop-edge artifacts, and N
+ * regions cost one mask + one effect pass.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMAGE_STILL_MS = exports.PIXELIZE_MAX = exports.PIXELIZE_MIN = exports.BLUR_SIGMA_MAX = exports.BLUR_SIGMA_MIN = exports.DEFAULT_STRENGTH = exports.MAX_REGIONS = void 0;
+exports.resolveBlurRegionsKnobs = resolveBlurRegionsKnobs;
+exports.evenRound = evenRound;
+exports.stillContainer = stillContainer;
+exports.buildBlurRegionsDocument = buildBlurRegionsDocument;
+exports.buildBlurRegionsStep = buildBlurRegionsStep;
+exports.inputLabel = inputLabel;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+/** Hard cap on regions per invocation (mirrors the prop's jsonSchema). */
+exports.MAX_REGIONS = 50;
+exports.DEFAULT_STRENGTH = 24;
+exports.BLUR_SIGMA_MIN = 1;
+exports.BLUR_SIGMA_MAX = 200;
+exports.PIXELIZE_MIN = 2;
+exports.PIXELIZE_MAX = 128;
+const clamp = (v, min, max) => Math.min(max, Math.max(min, v));
+/** Resolve + clamp props to deterministic knobs. `mode` is validated
+ * (not silently coerced) by render() BEFORE this runs. */
+function resolveBlurRegionsKnobs(props) {
+    const mode = props.mode === "pixelate" ? "pixelate" : "blur";
+    const raw = props.strength != null && Number.isFinite(props.strength)
+        ? Math.round(props.strength)
+        : exports.DEFAULT_STRENGTH;
+    const strength = mode === "pixelate"
+        ? clamp(raw, exports.PIXELIZE_MIN, exports.PIXELIZE_MAX)
+        : clamp(raw, exports.BLUR_SIGMA_MIN, exports.BLUR_SIGMA_MAX);
+    return { mode, strength };
+}
+/** Nearest even integer ≥ 2 (yuv420p-safe dimensions; highlights precedent). */
+function evenRound(v) {
+    return Math.max(2, Math.round(v / 2) * 2);
+}
+/** Duration for image inputs — a single-frame render (watermark precedent). */
+exports.IMAGE_STILL_MS = 40;
+/** Image container for a still input: jpeg in → jpeg out, else png
+ * (watermark's `imageOutputFormat: "match"` behavior). */
+function stillContainer(inputPath) {
+    return /\.jpe?g$/i.test(inputPath) ? "jpeg" : "png";
+}
+function buildBlurRegionsDocument(args) {
+    const { inputPath, mediaType, size, rectsPx, knobs, geometry } = args;
+    const isVideo = mediaType === "video";
+    const assetId = (0, types_1.asAssetId)((0, template_utils_1.slugifyAssetKeyFromPath)(inputPath));
+    const assets = {
+        [assetId]: { kind: "file", path: inputPath, mediaType },
+    };
+    const effectKnob = knobs.mode === "pixelate" ? { pixelize: knobs.strength } : { blur: knobs.strength };
+    const base = {
+        type: "media",
+        mediaType,
+        assetId,
+        // Cell aspect == source aspect up to even-rounding, so cover is an
+        // exact fit (no visible crop). Audio left UNSET → passes through.
+        placement: { fit: "cover" },
+        editor: { owner: "template", label: "blur-regions:base" },
+    };
+    const docShell = {
+        kind: "mosaic_document",
+        version: 1,
+        assets,
+        size,
+        backgroundColor: "#000000",
+    };
+    if (rectsPx.length === 0) {
+        return { ...docShell, m0: (0, dsl_stdlib_1.toM0String)("F", "BlurRegions"), sources: [base] };
+    }
+    if (geometry === "mask") {
+        // Regions WITHOUT their own mask stay plain subpaths (byte-identical
+        // to the pre-mask-authoring output); regions WITH a rect-local mask
+        // become placed `parts` in the same composite.
+        const composite = (0, template_utils_1.regionsToCompositeMask)(rectsPx);
+        const overlay = {
+            type: "media",
+            mediaType,
+            assetId,
+            placement: { fit: "cover" },
+            ...(isVideo ? { audio: { enabled: false } } : {}),
+            effects: effectKnob,
+            mask: {
+                kind: "inline-mask",
+                localPath: composite.localPath,
+                bounds: { x: 0, y: 0, width: size.width, height: size.height },
+                ...(composite.parts ? { parts: composite.parts } : {}),
+            },
+            editor: { owner: "template", label: "blur-regions:regions" },
+        };
+        return { ...docShell, m0: (0, dsl_stdlib_1.toM0String)("F{F}", "BlurRegions"), sources: [base, overlay] };
+    }
+    // Real-geometry strategies: every region is an m0 CELL whose source
+    // shows the exact window of the media underneath it via
+    // `placement.sourceRect` (canvas ≡ source dims here, so the cell rect
+    // IS the source rect), with the effect applied to that window. Cover
+    // fit of a same-sized window is a 1:1 pixel mapping. The pieces
+    // helpers compose the layers and return frame-aligned sources.
+    const regionSource = (rect) => {
+        var _a;
+        return {
+            type: "media",
+            mediaType,
+            assetId,
+            placement: {
+                fit: "cover",
+                sourceRect: { x: rect.x, y: rect.y, w: rect.w, h: rect.h },
+            },
+            ...(isVideo ? { audio: { enabled: false } } : {}),
+            effects: effectKnob,
+            // Rect-local mask carves the cell: bounds = the AUTHORED rect (the
+            // path's design space), so the engine rescales the shape onto the
+            // cell's content box regardless of the resolved cell size.
+            ...(rect.mask
+                ? {
+                    mask: {
+                        kind: "inline-mask",
+                        localPath: (_a = rect.mask.path) !== null && _a !== void 0 ? _a : "",
+                        bounds: { x: 0, y: 0, width: rect.mask.bounds.w, height: rect.mask.bounds.h },
+                        ...(rect.mask.strokes ? { strokes: rect.mask.strokes } : {}),
+                    },
+                }
+                : {}),
+            editor: { owner: "template", label: "blur-regions:region" },
+        };
+    };
+    const pieces = [
+        // Base: full-canvas, lattice-aligned → placed untouched, painted first.
+        { rect: { x: 0, y: 0, w: size.width, h: size.height, importance: 0 }, source: base },
+        ...rectsPx.map((rect, i) => ({
+            rect: { ...rect, importance: i + 1 },
+            source: regionSource(rect),
+        })),
+    ];
+    const placed = geometry === "exact"
+        ? // Zero drift ⇒ byte-identical to placeRects: exact cells, DSL
+            // length grows with the rects' pixel precision.
+            (0, template_utils_1.placeOptimizedPieces)({ rootW: size.width, rootH: size.height, pieces })
+        : // Default: compact lattice cells + per-source insets recovering
+            // the exact bounds ("inset"). Hostile (prime) axes place exactly
+            // instead of throwing — a runtime template renders any canvas.
+            (0, template_utils_1.placeInsetPieces)({
+                rootW: size.width,
+                rootH: size.height,
+                pieces,
+                onHostile: "exact",
+            });
+    return { ...docShell, m0: placed.m0, sources: placed.sources };
+}
+/**
+ * Wrap the document in ONE pipeline step. A pipeline step is the only
+ * vehicle where the output's canvas tracks the input's probed dims — a
+ * plain returned document's `size` is overridden by an explicit CLI
+ * `-w`/`-h` (or the app's Width/Height fields), which would misalign
+ * the mask regions against the re-fitted content (watermark precedent,
+ * its pipeline.ts header). Under a 1-output-step `emit:"multi"` the
+ * planner collapses to the bare `-o` file and the per-step format is
+ * inert — the user's `-o` extension wins (highlights single-range
+ * precedent).
+ */
+function buildBlurRegionsStep(args) {
+    var _a;
+    const isVideo = args.mediaType === "video";
+    const doc = buildBlurRegionsDocument(args);
+    return {
+        name: args.stepBaseName,
+        label: inputLabel(args.inputPath),
+        durationMs: isVideo
+            ? Math.max(1, Math.round((_a = args.durationMs) !== null && _a !== void 0 ? _a : 1))
+            : exports.IMAGE_STILL_MS,
+        file: {
+            ...doc,
+            format: isVideo
+                ? { kind: "video", container: "mp4" }
+                : { kind: "image", container: stillContainer(args.inputPath) },
+        },
+    };
+}
+/** Input basename without directory or extension — the step label.
+ * Local (not node:path) so the template stays web-bundle clean. */
+function inputLabel(p) {
+    var _a;
+    const base = (_a = p.split(/[\\/]/).pop()) !== null && _a !== void 0 ? _a : p;
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(0, dot) : base;
+}