@m0saic/templates 0.2.0

package/dist/m0saic/forensic/watermark/verify/v1/verify.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * `@m0saic/forensic/watermark/verify/v1`
+ *
+ * The decode half of the forensic watermarking family. Point it at a
+ * delivered video plus the `.watermark.json` the embed wrote, and it
+ * samples the video, recovers the payload, and renders a report card
+ * stating the verdict and why.
+ *
+ * This used to be `m0saic decode-watermark`. It moved because a CLI
+ * cannot grow a bespoke command per template family — the decoder is a
+ * template like everything else, reached through `m0saic make`, and it
+ * shows up in the Templates UI instead of being buried in `--help`.
+ *
+ * Exit codes vs. the verdict
+ * --------------------------
+ * `make` exits 0 whenever the *render* succeeds, so a FAIL verdict is a
+ * successful render of a FAIL card. Scripts that need to branch read the
+ * `watermarkCheck` sidecar (`verdict` / `ok`), which is written on every
+ * path for exactly that reason.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verdictPresentation = exports.ForensicWatermarkVerifyV1 = void 0;
+exports.parseContentRect = parseContentRect;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const alpine_theme_1 = require("../../../../alpine/_shared/alpine-theme");
+const cellLuminance_1 = require("../../_shared/cellLuminance");
+const decode_1 = require("./decode");
+const report_1 = require("./report");
+Object.defineProperty(exports, "verdictPresentation", { enumerable: true, get: function () { return report_1.verdictPresentation; } });
+const TEMPLATE_ID = "@m0saic/forensic/watermark/verify/v1";
+const VIDEO_ASSET_ID = "verify_input";
+const DEFAULTS = {
+    title: "Watermark check",
+    preset: "light",
+    showPayload: true,
+    posterFrameMs: 0,
+};
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    videoPath: {
+        type: "media",
+        required: true,
+        description: "The delivered video to check for an embedded payload.",
+        meta: {
+            ui: { label: "Video to check", order: 1 },
+            control: { picker: "file", accept: ["video"] },
+        },
+    },
+    sidecarPath: {
+        type: "string",
+        required: false,
+        description: "The `.watermark.json` written at embed time. Defaults to the same basename next to the video — set it explicitly when the delivered file has been renamed.",
+        // No `accept` — it only narrows media kinds (video/audio/image), and
+        // this is a JSON sidecar.
+        meta: {
+            ui: { label: "Sidecar", order: 2 },
+            control: { placeholder: "auto (next to the video)", picker: "file" },
+        },
+    },
+    expectedHex: {
+        type: "string",
+        required: false,
+        description: "Assert a specific payload (hex). Defaults to whatever the sidecar says was embedded; set it to ask whether this is one particular recipient's copy.",
+        meta: { control: { placeholder: "from sidecar" }, ui: { label: "Expected payload", order: 3 } },
+    },
+    contentRect: {
+        type: "string",
+        required: false,
+        description: "Pixel rect `x,y,w,h` of the marked content inside the delivered frame. Set it when a platform letterboxed or pillarboxed the copy (e.g. a 16:9 clip inside a 1080×1920 Reel: `0,420,1080,608`). Empty = the whole frame.",
+        meta: { control: { placeholder: "whole frame" }, ui: { label: "Content rect", order: 8 } },
+    },
+    title: {
+        type: "string",
+        required: false,
+        description: "Card title.",
+        meta: { ui: { label: "Title", order: 4 } },
+    },
+    preset: {
+        type: "string",
+        required: false,
+        description: "Chrome preset (light | dark).",
+        meta: { ui: { label: "Preset", order: 5 }, constraints: { oneOf: ["light", "dark"] } },
+    },
+    showPayload: {
+        type: "boolean",
+        required: false,
+        description: "Print payload hexes in full. Turn off when the card will be shared — payloads identify recipients.",
+        meta: { ui: { label: "Show payload", order: 6 } },
+    },
+    posterFrameMs: {
+        type: "number",
+        required: false,
+        description: "Offset of the frame shown in the input panel.",
+        meta: { ui: { label: "Poster frame (ms)", order: 7 }, constraints: { min: 0 } },
+    },
+});
+// ── Helpers ───────────────────────────────────────────────────────
+/** "1920×1080 · 30 fps · 12.4 s" from what the engine already probed. */
+function inputCaption(ctx, videoPath) {
+    var _a;
+    const meta = (_a = ctx.media) === null || _a === void 0 ? void 0 : _a[(0, types_1.asAssetId)(videoPath)];
+    if (!meta)
+        return undefined;
+    const bits = [];
+    if (meta.width && meta.height)
+        bits.push(`${meta.width}×${meta.height}`);
+    if (meta.fps)
+        bits.push(`${Math.round(meta.fps)} fps`);
+    if (meta.durationMs)
+        bits.push(`${(meta.durationMs / 1000).toFixed(1)} s`);
+    return bits.length ? bits.join(" · ") : undefined;
+}
+/** `"x,y,w,h"` → crop rect; undefined when blank, null when malformed. */
+function parseContentRect(raw) {
+    const t = raw === null || raw === void 0 ? void 0 : raw.trim();
+    if (!t)
+        return undefined;
+    const parts = t.split(/[,\s]+/).map((v) => Number(v));
+    if (parts.length !== 4 || parts.some((v) => !Number.isFinite(v) || v < 0))
+        return null;
+    const [x, y, width, height] = parts;
+    if (width < 2 || height < 2)
+        return null;
+    return { x: Math.round(x), y: Math.round(y), width: Math.round(width), height: Math.round(height) };
+}
+/** A report shell for states where no decode has run. */
+function blankReport(videoPath, sidecarPath) {
+    return {
+        ok: false,
+        recoveredHex: undefined,
+        expectedHex: "",
+        matches: false,
+        correctedBitCount: 0,
+        errorPositions: [],
+        worstAbsScore: 0,
+        framesSampled: 0,
+        mode: "id32",
+        verdict: "error",
+        grid: { cols: 0, rows: 0 },
+        ecc: { n: 0, k: 0, t: 0 },
+        videoPath,
+        sidecarPath,
+    };
+}
+// ── Template ──────────────────────────────────────────────────────
+exports.ForensicWatermarkVerifyV1 = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)(TEMPLATE_ID),
+    label: "Forensic Watermark — Verify",
+    version: 1,
+    description: "Check a delivered video against its `.watermark.json` and render a report card: PASS / MISMATCH / FAIL / ERROR, the recovered payload, ECC headroom and confidence, plus the reason. Emits a `watermarkCheck` sidecar carrying the same result as JSON. The decode half of `@m0saic/forensic/watermark/video/v1`.",
+    capabilities: {
+        tier: "capability",
+        // Read-only by design: the sidecar is read, the video is sampled
+        // through the engine's `ctx.analysis.cellLuminance` pass (the host's
+        // toolchain ffmpeg), nothing is written or staged. Narrower than the
+        // embed template, which needs write+temp for its mask PNG.
+        caps: { fs: { read: true }, exec: { spawn: true } },
+    },
+    tags: ["utility", "forensic", "watermark", "verify", "provenance", "attribution", "creators", "developers", "video"],
+    outputHints: {
+        width: 1600,
+        height: 1000,
+        // A verdict has no time dimension — as a video this would be N
+        // identical frames. `doc.format` stays unset so an explicit
+        // `-o out.mp4` still works; it just holds one frame.
+        format: { kind: "image", container: "png" },
+    },
+    propsSchema,
+    defaultProps: DEFAULTS,
+    sidecarsSchema: {
+        watermarkCheck: {
+            type: "object",
+            required: true,
+            description: "Decode verdict + full stats → `{output-basename}.watermarkCheck.json`. Written unconditionally: the render exits 0 regardless of verdict, so this is the machine-readable channel.",
+        },
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        if (!props.videoPath) {
+            // ASCII only in this card: makeErrorMosaic renders via drawtext,
+            // which has no unicode support (an em-dash comes out as "?"). The
+            // report card itself uses the SVG rasterizer and is unicode-safe.
+            return (0, template_utils_1.makeErrorMosaic)("ForensicWatermarkVerifyV1: set `videoPath` to the video you want to check. " +
+                "The `.watermark.json` sidecar is found next to it automatically, or set `sidecarPath`.", { title: "Forensic Watermark - Verify", width: W, height: H });
+        }
+        const theme = await (0, alpine_theme_1.resolveAlpineTheme)((_a = props.preset) !== null && _a !== void 0 ? _a : "light", ctx);
+        const contentRect = parseContentRect(props.contentRect);
+        if (((_b = props.contentRect) === null || _b === void 0 ? void 0 : _b.trim()) && !contentRect) {
+            return (0, template_utils_1.makeErrorMosaic)(`ForensicWatermarkVerifyV1: contentRect must be "x,y,w,h" in pixels (got "${props.contentRect}").`, { title: "Forensic Watermark - Verify", width: W, height: H });
+        }
+        const report = await (0, decode_1.runCheck)({
+            videoPath: props.videoPath,
+            sidecarPath: props.sidecarPath,
+            expectedHex: props.expectedHex,
+            ...(contentRect ? { crop: contentRect } : {}),
+            // The engine's sampling pass, bound to the host's toolchain ffmpeg.
+            // Absent (no toolchain) → the check reports ANALYSIS_UNAVAILABLE on
+            // the card instead of guessing at a binary on PATH.
+            sampler: (0, cellLuminance_1.cellLuminanceSampler)(ctx),
+        });
+        const assets = {
+            [(0, types_1.asAssetId)(VIDEO_ASSET_ID)]: {
+                kind: "file",
+                path: props.videoPath,
+                mediaType: "video",
+            },
+        };
+        const root = (0, report_1.buildReportCard)({
+            report,
+            theme,
+            W,
+            H,
+            title: (_c = props.title) !== null && _c !== void 0 ? _c : DEFAULTS.title,
+            showPayload: (_d = props.showPayload) !== null && _d !== void 0 ? _d : true,
+            videoAssetId: VIDEO_ASSET_ID,
+            posterFrameMs: (_e = props.posterFrameMs) !== null && _e !== void 0 ? _e : 0,
+            inputCaption: inputCaption(ctx, props.videoPath),
+        });
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            m0: root.m0,
+            backgroundColor: theme.canvas,
+            assets,
+            sources: root.sources,
+            sidecars: { watermarkCheck: report },
+        };
+    },
+    /**
+     * Preview stand-in. Shows the real layout so the operator can size and
+     * theme the card, but never samples the video and never emits a
+     * sidecar — a design-mode preview must not look like a verdict.
+     */
+    renderLite(props, ctx) {
+        var _a, _b, _c, _d, _e, _f;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        // Sync preset lookup — renderLite is synchronous, so it takes the
+        // preset chrome directly rather than awaiting token resolution.
+        const theme = (0, alpine_theme_1.alpineTheme)((_a = props.preset) !== null && _a !== void 0 ? _a : "light");
+        const videoPath = (_b = props.videoPath) !== null && _b !== void 0 ? _b : "";
+        const sidecarPath = ((_c = props.sidecarPath) === null || _c === void 0 ? void 0 : _c.trim())
+            ? props.sidecarPath.trim()
+            : videoPath
+                ? (0, decode_1.discoverSidecarPath)(videoPath)
+                : "";
+        const report = blankReport(videoPath, sidecarPath);
+        const assets = (videoPath
+            ? {
+                [(0, types_1.asAssetId)(VIDEO_ASSET_ID)]: {
+                    kind: "file",
+                    path: videoPath,
+                    mediaType: "video",
+                },
+            }
+            : {});
+        const root = (0, report_1.buildReportCard)({
+            report,
+            theme,
+            W,
+            H,
+            title: (_d = props.title) !== null && _d !== void 0 ? _d : DEFAULTS.title,
+            showPayload: (_e = props.showPayload) !== null && _e !== void 0 ? _e : true,
+            videoAssetId: videoPath ? VIDEO_ASSET_ID : undefined,
+            posterFrameMs: (_f = props.posterFrameMs) !== null && _f !== void 0 ? _f : 0,
+            bandOverride: {
+                color: theme.muted,
+                headline: "NOT CHECKED — run Make to sample the video",
+            },
+            pending: true,
+        });
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            m0: root.m0,
+            backgroundColor: theme.canvas,
+            assets,
+            sources: root.sources,
+        };
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.ForensicWatermarkVerifyV1);
+exports.default = exports.ForensicWatermarkVerifyV1;

package/dist/m0saic/forensic/watermark/video/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1";

package/dist/m0saic/forensic/watermark/video/index.js

@@ -0,0 +1,17 @@
+"use strict";
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1"), exports);

package/dist/m0saic/forensic/watermark/video/v1/forensic-watermark.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `@m0saic/forensic/watermark/video/v1`
+ *
+ * Embed an imperceptible per-render payload (subscriber ID, install
+ * UUID, …) into a base video using a spatial-cell BCH-coded
+ * watermark. The decoder is its sibling template,
+ * `@m0saic/forensic/watermark/verify/v1` — run it through `make` like
+ * any other template; it renders a verdict card and emits the result
+ * as a `watermarkCheck` sidecar.
+ *
+ * Algorithm
+ * ---------
+ *  1. Encode the payload via BCH(127, 36, 15) (id32) or
+ *     BCH(255, 131, 18) (uuid128).
+ *  2. Build a cell-grid mask from the PRNG seed; each cell carries
+ *     one codeword bit with a per-cell sign flip.
+ *  3. Materialize an RGBA PNG (cells → upscaled to canvas) with
+ *     near-transparent ±luminance overlays.
+ *  4. Composite the PNG over the base video at full alpha (the PNG's
+ *     own alpha channel does the blending).
+ *  5. Emit a `ForensicWatermarkSidecar` describing every parameter
+ *     the decoder needs.
+ *
+ * Output envelope — the deliverable IS the source video
+ * -----------------------------------------------------
+ * The result is a 1-step `emit:"multi"` pipeline (the media-pack
+ * pattern: blur-regions, highlights, the visible watermark), so the
+ * output tracks the SOURCE's dimensions, frame rate and duration
+ * instead of the template's 1920×1080 / 10 s hints — a 720p 12 s clip
+ * comes back as a 720p 12 s clip with an invisible mark, audio intact.
+ * An explicit duration / fps ask (CLI `--durationMs`/`--fps`, the Make
+ * Duration override) still wins over the follow.
+ *
+ * Determinism: identical (payload, seed, grid, canvas, α curve, host
+ * grid when adaptive) produces byte-identical PNG bytes and a
+ * byte-identical sidecar.
+ *
+ * Robustness target (v1)
+ *  - Survives single/double H.264 re-encodes at ≥ 4 Mbps for 1080p.
+ *  - Does NOT survive crop, rotation, scale change, or
+ *    screen-recording / camcorder capture.
+ *
+ * See the internal forensic-watermarking notes for the design.
+ */
+import type { ForensicWatermarkPayloadMode, ForensicWatermarkSidecar, MosaicEngineContext, MosaicMediaMetadata } from "@m0saic/types";
+export type ForensicWatermarkVideoV1Props = {
+    /** Path to the base video file. Required. */
+    videoPath?: string;
+    /** `"id32"` (32-bit payload) or `"uuid128"` (128-bit). */
+    payloadMode?: ForensicWatermarkPayloadMode;
+    /** Hex-encoded payload value. Length must match the chosen mode. */
+    payloadHex?: string;
+    /**
+     * PRNG seed driving the cell→bit assignment and sign mask. Hex
+     * string (1–8 chars). Optional — auto-derived from a hash of
+     * `payloadHex` when omitted. **Different renders MUST use different
+     * keys**, otherwise distinct payloads share the same cell layout
+     * and a leaker who recovered one mark can de-stamp others.
+     */
+    keyHex?: string;
+    /** Cell grid columns. Default 64. */
+    gridCols?: number;
+    /** Cell grid rows. Default 36. */
+    gridRows?: number;
+    /** Uniform α (luminance shift, 0..1) when `luminanceAdaptive` is off. Default 0.012. */
+    alphaBase?: number;
+    /**
+     * Scale α per cell by the host: a luminance bell (peaking at `alphaMax`
+     * on mid-greys, `alphaMin` at near-black / near-white) multiplied by a
+     * TEXTURE mask (flat cells — walls, sky, gradients, where a constant
+     * step reads as a checkerboard — fall to `alphaMin`; textured cells
+     * keep the bell). Probed from the source at 2× the grid. Default ON;
+     * off = uniform `alphaBase`.
+     */
+    luminanceAdaptive?: boolean;
+    /** Floor α of the adaptive curve (dark/bright cells). Default 0.004. */
+    alphaMin?: number;
+    /** Ceiling α of the adaptive curve (textured mid-grey cells). Default 0.02. */
+    alphaMax?: number;
+    /**
+     * Soft cell edges: Gaussian blur of the mask, as a fraction of the cell
+     * size (0 = hard cells, 0.5 = a full half-cell ramp). A hard per-cell
+     * step on a smooth gradient reads as a faint checkerboard; softened over
+     * a few px it becomes a low-frequency bump the eye ignores while the
+     * cell interior the decoder integrates keeps its offset. Default 0.15.
+     */
+    edgeSoftness?: number;
+    /**
+     * Pre-probed per-cell host luminance (row-major, length cols*rows).
+     * When supplied, the template skips the engine probe and uses this
+     * directly as the sidecar's `hostReference.luminanceGrid`. Agent /
+     * test hatch — hidden from the Make form.
+     */
+    hostLuminanceGrid?: number[];
+};
+/**
+ * The output envelope: follow the SOURCE (dims / fps / duration) when the
+ * host probed it, else fall back to the target the host handed us. An
+ * explicit user ask (`ctx.userIntent`) wins over the follow for the
+ * fields a user can ask for.
+ */
+export declare function resolveOutputEnvelope(meta: MosaicMediaMetadata | undefined, ctx: Pick<MosaicEngineContext, "target" | "userIntent">): {
+    width: number;
+    height: number;
+    fps: number;
+    durationMs: number;
+    followed: boolean;
+};
+type Sidecars = {
+    watermark: ForensicWatermarkSidecar;
+};
+export declare const ForensicWatermarkVideoV1: import("@m0saic/types").MosaicTemplate<ForensicWatermarkVideoV1Props, {}, {}, {}, Sidecars>;
+/**
+ * Per-cell activity from a 2×-resolution luminance grid: the spread
+ * (max − min) of each cell's four sub-cell means, in luma units. A smooth
+ * gradient reads ~1–4, real texture ≥ 24 (see `ACTIVITY_FULL_GAIN`).
+ */
+export declare function cellActivity(fine: ReadonlyArray<number>, cols: number, rows: number): number[];
+export default ForensicWatermarkVideoV1;