@m0saic/templates 0.2.0

package/dist/m0saic/forensic/watermark/verify/v1/decode.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The check itself: sidecar + delivered video → verdict.
+ *
+ * Ported from the CLI's `decode-watermark` command, minus two things:
+ * the ffmpeg sampling now goes through the family's shared sampler — the
+ * engine's `ctx.analysis.cellLuminance`, so embed and verify provably run
+ * the same filtergraph on the host's toolchain ffmpeg — and nothing is
+ * written to disk — the template's render path owns output.
+ *
+ * Everything here is total: `runCheck` never throws. Expected failures
+ * (missing sidecar, unreadable video, un-decodable payload) come back as
+ * a report with `verdict: "error"` or `"fail"`, because the caller is a
+ * template `render()` that has to draw *something* either way.
+ */
+import type { ForensicWatermarkCheckReport, ForensicWatermarkSidecar } from "@m0saic/types";
+import { type CellLuminanceSampler } from "../../_shared/cellLuminance";
+/** Suffix `writeSidecars` gives the embed sidecar, next to the video. */
+export declare const SIDECAR_SUFFIX = ".watermark.json";
+/**
+ * Presence floor on the MEAN |score| (luma units summed over a bit's
+ * cells). The un-marked original subtracts against its own host
+ * reference to a zero residual; every score is 0, the all-zero codeword
+ * is syndrome-clean, and BCH alone "recovers" payload 0 — a `mismatch`
+ * that would read as "someone else's copy". A real mark at the default
+ * α puts ~1.5 luma × cellsPerBit into every score (mean ≈ 16 at 64×36
+ * on 720p; ≈ 2–6 on the coarsest grids / harshest re-encodes measured),
+ * so 0.25 is far below any legitimate decode and far above float noise.
+ */
+export declare const MIN_PRESENCE_MEAN_ABS_SCORE = 0.25;
+/** Sidecar problems carry a stable code so the report card can branch. */
+export declare class SidecarError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Where the embed sidecar lands by convention: same directory, same
+ * basename, `.watermark.json`. The render pipeline derives both from one
+ * output path, so `out.mp4` → `out.watermark.json` holds by construction.
+ *
+ * This is a convenience, not a guarantee — a leaked file is rarely still
+ * named after the render that produced it, which is why `sidecarPath`
+ * stays an explicit prop.
+ */
+export declare function discoverSidecarPath(videoPath: string): string;
+/**
+ * Read + validate the embed sidecar.
+ *
+ * @throws {SidecarError} not found, unreadable, not JSON, or a
+ * version/algorithm this build cannot decode.
+ */
+export declare function readSidecar(sidecarPath: string): ForensicWatermarkSidecar;
+export interface RunCheckInputs {
+    /** The delivered video to check. */
+    videoPath: string;
+    /** Embed sidecar. Discovered next to the video when omitted. */
+    sidecarPath?: string;
+    /**
+     * Payload to assert against. Defaults to whatever the sidecar says was
+     * embedded; set it to answer "is this specifically subscriber X's copy?"
+     * independent of the sidecar's own claim.
+     */
+    expectedHex?: string;
+    /**
+     * The engine sampling pass (`ctx.analysis.cellLuminance`). Undefined when
+     * the host attached no analysis surface — the check then reports an
+     * `ANALYSIS_UNAVAILABLE` error verdict instead of guessing at a binary.
+     */
+    sampler: CellLuminanceSampler | undefined;
+    /**
+     * Sample only this pixel rect of the delivered frame (a platform's
+     * letterbox / pillarbox bars sit outside it). Whole frame when omitted.
+     */
+    crop?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Run the check. Never throws — see the module header.
+ */
+export declare function runCheck(inputs: RunCheckInputs): Promise<ForensicWatermarkCheckReport>;

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

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * The check itself: sidecar + delivered video → verdict.
+ *
+ * Ported from the CLI's `decode-watermark` command, minus two things:
+ * the ffmpeg sampling now goes through the family's shared sampler — the
+ * engine's `ctx.analysis.cellLuminance`, so embed and verify provably run
+ * the same filtergraph on the host's toolchain ffmpeg — and nothing is
+ * written to disk — the template's render path owns output.
+ *
+ * Everything here is total: `runCheck` never throws. Expected failures
+ * (missing sidecar, unreadable video, un-decodable payload) come back as
+ * a report with `verdict: "error"` or `"fail"`, because the caller is a
+ * template `render()` that has to draw *something* either way.
+ */
+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.SidecarError = exports.MIN_PRESENCE_MEAN_ABS_SCORE = exports.SIDECAR_SUFFIX = void 0;
+exports.discoverSidecarPath = discoverSidecarPath;
+exports.readSidecar = readSidecar;
+exports.runCheck = runCheck;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const template_utils_1 = require("@m0saic/template-utils");
+const cellLuminance_1 = require("../../_shared/cellLuminance");
+/** Suffix `writeSidecars` gives the embed sidecar, next to the video. */
+exports.SIDECAR_SUFFIX = ".watermark.json";
+/**
+ * Presence floor on the MEAN |score| (luma units summed over a bit's
+ * cells). The un-marked original subtracts against its own host
+ * reference to a zero residual; every score is 0, the all-zero codeword
+ * is syndrome-clean, and BCH alone "recovers" payload 0 — a `mismatch`
+ * that would read as "someone else's copy". A real mark at the default
+ * α puts ~1.5 luma × cellsPerBit into every score (mean ≈ 16 at 64×36
+ * on 720p; ≈ 2–6 on the coarsest grids / harshest re-encodes measured),
+ * so 0.25 is far below any legitimate decode and far above float noise.
+ */
+exports.MIN_PRESENCE_MEAN_ABS_SCORE = 0.25;
+/** Sidecar problems carry a stable code so the report card can branch. */
+class SidecarError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "SidecarError";
+        this.code = code;
+    }
+}
+exports.SidecarError = SidecarError;
+/**
+ * Where the embed sidecar lands by convention: same directory, same
+ * basename, `.watermark.json`. The render pipeline derives both from one
+ * output path, so `out.mp4` → `out.watermark.json` holds by construction.
+ *
+ * This is a convenience, not a guarantee — a leaked file is rarely still
+ * named after the render that produced it, which is why `sidecarPath`
+ * stays an explicit prop.
+ */
+function discoverSidecarPath(videoPath) {
+    const dir = path.dirname(videoPath);
+    const base = path.basename(videoPath, path.extname(videoPath));
+    return path.join(dir, `${base}${exports.SIDECAR_SUFFIX}`);
+}
+/**
+ * Read + validate the embed sidecar.
+ *
+ * @throws {SidecarError} not found, unreadable, not JSON, or a
+ * version/algorithm this build cannot decode.
+ */
+function readSidecar(sidecarPath) {
+    if (!fs.existsSync(sidecarPath)) {
+        throw new SidecarError("SIDECAR_NOT_FOUND", `Sidecar not found: ${sidecarPath}`);
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(sidecarPath, "utf8");
+    }
+    catch (err) {
+        throw new SidecarError("SIDECAR_UNREADABLE", `Failed to read sidecar at ${sidecarPath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new SidecarError("SIDECAR_INVALID_JSON", `Sidecar at ${sidecarPath} is not valid JSON: ${err.message}`);
+    }
+    const sc = parsed;
+    if (sc.version !== "watermark/v1") {
+        throw new SidecarError("SIDECAR_VERSION_UNSUPPORTED", `Unsupported sidecar version "${sc.version}". This template handles watermark/v1.`);
+    }
+    if (sc.algorithm !== "spatio-temporal-ab-bch") {
+        throw new SidecarError("SIDECAR_ALGORITHM_UNSUPPORTED", `Unsupported algorithm "${sc.algorithm}". This template handles spatio-temporal-ab-bch.`);
+    }
+    return sc;
+}
+/**
+ * Build the per-cell host baseline the correlator subtracts.
+ *
+ * Non-blind (the sidecar carries a real grid) is the +10 dB path. Blind
+ * falls back to the global mean, which holds up on flat content and
+ * collapses on real content — worth knowing when a `fail` verdict shows
+ * a near-zero `worstAbsScore`.
+ */
+function buildHostLuminance(sidecar, sampled, cellCount) {
+    var _a, _b, _c;
+    const grid = (_b = (_a = sidecar.hostReference) === null || _a === void 0 ? void 0 : _a.luminanceGrid) !== null && _b !== void 0 ? _b : [];
+    if (grid.length === 0) {
+        let mean = 0;
+        for (let i = 0; i < cellCount; i += 1)
+            mean += sampled[i];
+        mean /= cellCount;
+        return new Array(cellCount).fill(mean);
+    }
+    // v1 writes exactly one slot.
+    const slot0 = grid[0];
+    if (!slot0 || slot0.length !== cellCount) {
+        throw new SidecarError("SIDECAR_HOST_REFERENCE_MALFORMED", `Sidecar hostReference is malformed: expected slot 0 to have ${cellCount} cells, got ${(_c = slot0 === null || slot0 === void 0 ? void 0 : slot0.length) !== null && _c !== void 0 ? _c : 0}.`);
+    }
+    return slot0.slice();
+}
+/** Shape an `error` verdict when the check could not run. */
+function errorReport(inputs, code, message) {
+    return {
+        ok: false,
+        recoveredHex: undefined,
+        expectedHex: inputs.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: inputs.videoPath,
+        sidecarPath: inputs.sidecarPath,
+        error: { code, message },
+    };
+}
+/**
+ * Run the check. Never throws — see the module header.
+ */
+async function runCheck(inputs) {
+    var _a, _b, _c;
+    const sidecarPath = ((_a = inputs.sidecarPath) === null || _a === void 0 ? void 0 : _a.trim())
+        ? inputs.sidecarPath.trim()
+        : discoverSidecarPath(inputs.videoPath);
+    const ctx = {
+        videoPath: inputs.videoPath,
+        sidecarPath,
+        expectedHex: (_b = inputs.expectedHex) !== null && _b !== void 0 ? _b : "",
+    };
+    let sidecar;
+    try {
+        sidecar = readSidecar(sidecarPath);
+    }
+    catch (err) {
+        if (err instanceof SidecarError) {
+            return errorReport(ctx, err.code, err.message);
+        }
+        return errorReport(ctx, "SIDECAR_UNREADABLE", err.message);
+    }
+    const { cols, rows } = sidecar.grid;
+    const cellCount = cols * rows;
+    const expectedHex = ((_c = inputs.expectedHex) === null || _c === void 0 ? void 0 : _c.trim())
+        ? inputs.expectedHex.trim().toLowerCase()
+        : sidecar.payload.valueHex;
+    const withPayload = { ...ctx, expectedHex };
+    let sampled;
+    let framesSampled;
+    try {
+        // The delivered file as-is: no cover-fit, no hold, the file's own rate
+        // and length. The embed side authored its reference over the same
+        // cell-grid tail, so the two grids subtract cleanly.
+        const res = await (0, cellLuminance_1.sampleCellLuminance)(inputs.sampler, inputs.videoPath, {
+            cols,
+            rows,
+            ...(inputs.crop ? { crop: inputs.crop } : {}),
+        });
+        sampled = res.luminanceGrid;
+        framesSampled = res.frameCount;
+    }
+    catch (err) {
+        const code = err instanceof cellLuminance_1.CellSampleError ? err.code : "SAMPLING_ERROR";
+        return errorReport(withPayload, code, err.message);
+    }
+    let hostLuminance;
+    try {
+        hostLuminance = buildHostLuminance(sidecar, sampled, cellCount);
+    }
+    catch (err) {
+        const code = err instanceof SidecarError ? err.code : "HOST_REFERENCE_ERROR";
+        return errorReport(withPayload, code, err.message);
+    }
+    let decoded;
+    try {
+        decoded = template_utils_1.forensic.decodePayload({
+            mode: sidecar.payload.mode,
+            seed: parseInt(sidecar.key.seedHex.replace(/^0x/, ""), 16),
+            cols,
+            rows,
+            sampledLuminance: sampled,
+            hostLuminance,
+        });
+    }
+    catch (err) {
+        return errorReport(withPayload, "DECODE_ERROR", err.message);
+    }
+    const meanAbsScore = decoded.scores.length > 0
+        ? decoded.scores.reduce((acc, v) => acc + Math.abs(v), 0) / decoded.scores.length
+        : 0;
+    // No watermark ENERGY → fail, whatever BCH made of the zero vector (see
+    // MIN_PRESENCE_MEAN_ABS_SCORE). Checked before the codeword verdict.
+    const present = meanAbsScore >= exports.MIN_PRESENCE_MEAN_ABS_SCORE;
+    const ok = decoded.ok && present;
+    const recoveredHex = ok ? decoded.payloadHex : undefined;
+    const matches = !!recoveredHex && recoveredHex === expectedHex;
+    // A clean codeword carrying someone else's payload is a `mismatch`, not
+    // a `fail` — the tool worked; the file just isn't the copy we expected.
+    const verdict = !ok ? "fail" : matches ? "pass" : "mismatch";
+    return {
+        ok,
+        recoveredHex,
+        expectedHex,
+        matches,
+        correctedBitCount: decoded.correctedBitCount,
+        errorPositions: decoded.errorPositions,
+        worstAbsScore: decoded.worstAbsScore,
+        meanAbsScore,
+        framesSampled,
+        mode: sidecar.payload.mode,
+        verdict,
+        grid: { cols, rows },
+        ecc: { n: sidecar.ecc.n, k: sidecar.ecc.k, t: sidecar.ecc.t },
+        videoPath: inputs.videoPath,
+        sidecarPath,
+    };
+}

package/dist/m0saic/forensic/watermark/verify/v1/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./verify";
+export { default } from "./verify";

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

@@ -0,0 +1,23 @@
+"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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+__exportStar(require("./verify"), exports);
+var verify_1 = require("./verify");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(verify_1).default; } });

package/dist/m0saic/forensic/watermark/verify/v1/report.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The report card: a check result → m0 + sources.
+ *
+ * Design intent — this render exists to be *read*, usually at a glance
+ * and often as a screenshot pasted into a ticket. Two things carry that:
+ *
+ *  1. A full-bleed status band across the top. It touches the canvas
+ *     edge deliberately (which is why this file builds its own chrome
+ *     instead of using `alpineCard`, whose `compose()` insets everything
+ *     by its padding). Colour reads before any text does.
+ *  2. The *reason* is always on the card. A verdict with no explanation
+ *     sends the reader back to a terminal, which defeats the point of
+ *     rendering a card at all — so the footnote row carries the ECC
+ *     diagnostic on a fail, and the actual error text on an error.
+ *
+ * Geometry follows the construction-strategy hard rule: real m0 cells
+ * via the shared Node combinator kit, not one full-frame drawtext. Text
+ * goes through the SVG glyph rasterizer (bundled deterministic font, no
+ * drawtext spawn, and it gives us font weight, which `textCell` in the
+ * Alpine kit does not expose).
+ *
+ * Weights are SMALL INTEGERS, deliberately
+ * ----------------------------------------
+ * `weightedSplit` makes a split's cell count equal the sum of its
+ * weights, so a "natural" pixel-weighted inset like `[40, 1520, 40]`
+ * becomes a 1600-cell split (clamped to 120 by the kit's basis cap, but
+ * still 120 cells for one margin). Nest a few of those and the m0 runs
+ * to thousands of cells. Every split here therefore uses a small basis,
+ * and inner spacing prefers text `placement.padding` over geometry.
+ */
+import type { ForensicWatermarkCheckReport, ForensicWatermarkCheckVerdict, MosaicColor } from "@m0saic/types";
+import { type Node } from "../../../../alpine/_shared/alpine-card";
+import type { AlpineTheme } from "../../../../alpine/_shared/alpine-theme";
+/**
+ * Four states, four colours. `mismatch` gets its own amber rather than
+ * collapsing into the fail red: a clean decode carrying a different
+ * payload means the tool worked perfectly and the file simply isn't the
+ * copy you expected — operationally the most interesting answer here,
+ * and one you should never have to squint at a hex string to notice.
+ */
+export declare function verdictPresentation(verdict: ForensicWatermarkCheckVerdict, theme: AlpineTheme): {
+    color: MosaicColor;
+    headline: string;
+};
+/** Wrap to `maxChars` and cap at `maxLines`, ellipsizing when truncated. */
+export declare function wrapCapped(s: string, maxChars: number, maxLines: number): string[];
+/** The footnote line — always the *reason*, never just a restatement. */
+export declare function footnoteText(report: ForensicWatermarkCheckReport): string;
+export interface BuildReportCardInputs {
+    report: ForensicWatermarkCheckReport;
+    theme: AlpineTheme;
+    W: number;
+    H: number;
+    title: string;
+    showPayload: boolean;
+    /** Asset id of the checked video, when it can be shown. */
+    videoAssetId?: string;
+    /** Poster frame offset for the input panel. */
+    posterFrameMs: number;
+    /** Human caption under the poster ("1920×1080 · 30 fps · 12.4 s"). */
+    inputCaption?: string;
+    /** Overrides the band — used by renderLite for the "not checked" state. */
+    bandOverride?: {
+        color: MosaicColor;
+        headline: string;
+    };
+    /** Blanks the decode-derived tiles (renderLite). */
+    pending?: boolean;
+}
+/** Build the whole card. Returns the root node; caller sets the doc background. */
+export declare function buildReportCard(inputs: BuildReportCardInputs): Node;