@m0saic/templates 0.2.0

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

@@ -0,0 +1,67 @@
+/**
+ * Materialize the watermark mask as an on-disk RGBA PNG.
+ *
+ * Given the encoder's `CellPlan[]`, build a `cols × rows` RGBA buffer
+ * where each pixel encodes:
+ *
+ *   - RGB = white (255,255,255) when `polarity = +1`, black (0,0,0)
+ *     when `polarity = -1`
+ *   - alpha = round(α * 255)
+ *
+ * Composited via standard alpha-blend against a host frame of mean
+ * luminance Y₀, the output luminance shifts by `±α * (Y_extreme - Y₀)`
+ * — approximately `±α * 128` for mid-luminance host — matching the
+ * decoder's expected residual signal.
+ *
+ * Upscaled to canvas dims via nearest-neighbor (Sharp's `kernel:
+ * "nearest"`, `fit: "fill"` — the grid stretches onto the canvas whatever
+ * its aspect) so each grid cell becomes a sharp `cellWidth × cellHeight`
+ * pixel block. Sharp transforms here are lazy — `.toFile()` triggers
+ * the pipeline once.
+ *
+ * Output path is content-addressed (sha256 of cells + dims + seed +
+ * payload) so re-renders of the same inputs hit the cache; nothing
+ * is written if the file already exists.
+ */
+export interface BuildMaskAssetInputs {
+    /** Per-cell plan from `encodePayload()`. Row-major, length cols*rows. */
+    cells: ReadonlyArray<{
+        polarity: -1 | 1;
+        alpha: number;
+    }>;
+    /** Grid columns. */
+    cols: number;
+    /** Grid rows. */
+    rows: number;
+    /** Target canvas width (pixels). */
+    canvasW: number;
+    /** Target canvas height (pixels). */
+    canvasH: number;
+    /** Stable fingerprint used in the cache filename — typically a hash of seed + payload + dims. */
+    fingerprint: string;
+    /**
+     * Gaussian sigma (px) applied AFTER the nearest upscale, softening the
+     * hard step between neighbouring cells. 0 / undefined = hard cells. A
+     * per-cell constant 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 a cell's interior — what the area-average
+     * decoder integrates — keeps its full offset. Must be in the fingerprint.
+     */
+    blurSigmaPx?: number;
+}
+export interface BuildMaskAssetResult {
+    /** Absolute on-disk path to the materialized PNG. */
+    pngPath: string;
+    /** Whether the PNG was generated fresh (false = cache hit). */
+    fresh: boolean;
+}
+/**
+ * Build a deterministic cache fingerprint from the inputs that decide
+ * the PNG bytes. Callers typically combine seed + payload + grid dims
+ * + canvas dims + alpha curve params.
+ */
+export declare function makeFingerprint(parts: ReadonlyArray<string | number>): string;
+/**
+ * Build the mask PNG (cached). Async because Sharp's I/O is async.
+ */
+export declare function buildMaskPng(inputs: BuildMaskAssetInputs): Promise<BuildMaskAssetResult>;

package/dist/m0saic/forensic/watermark/video/v1/maskAsset.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Materialize the watermark mask as an on-disk RGBA PNG.
+ *
+ * Given the encoder's `CellPlan[]`, build a `cols × rows` RGBA buffer
+ * where each pixel encodes:
+ *
+ *   - RGB = white (255,255,255) when `polarity = +1`, black (0,0,0)
+ *     when `polarity = -1`
+ *   - alpha = round(α * 255)
+ *
+ * Composited via standard alpha-blend against a host frame of mean
+ * luminance Y₀, the output luminance shifts by `±α * (Y_extreme - Y₀)`
+ * — approximately `±α * 128` for mid-luminance host — matching the
+ * decoder's expected residual signal.
+ *
+ * Upscaled to canvas dims via nearest-neighbor (Sharp's `kernel:
+ * "nearest"`, `fit: "fill"` — the grid stretches onto the canvas whatever
+ * its aspect) so each grid cell becomes a sharp `cellWidth × cellHeight`
+ * pixel block. Sharp transforms here are lazy — `.toFile()` triggers
+ * the pipeline once.
+ *
+ * Output path is content-addressed (sha256 of cells + dims + seed +
+ * payload) so re-renders of the same inputs hit the cache; nothing
+ * is written if the file already exists.
+ */
+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.makeFingerprint = makeFingerprint;
+exports.buildMaskPng = buildMaskPng;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const paths_1 = require("@m0saic/platform/paths");
+const raster_1 = require("../../../../_shared/raster");
+const CACHE_DIR = path.join(os.tmpdir(), `${paths_1.M0SAIC_TMP_PREFIX}forensic-watermark-cache`);
+function ensureCacheDir() {
+    if (!fs.existsSync(CACHE_DIR))
+        fs.mkdirSync(CACHE_DIR, { recursive: true });
+}
+/**
+ * Build a deterministic cache fingerprint from the inputs that decide
+ * the PNG bytes. Callers typically combine seed + payload + grid dims
+ * + canvas dims + alpha curve params.
+ */
+function makeFingerprint(parts) {
+    return crypto
+        .createHash("sha256")
+        .update(parts.map(String).join("|"))
+        .digest("hex")
+        .slice(0, 16);
+}
+/**
+ * Build the mask PNG (cached). Async because Sharp's I/O is async.
+ */
+async function buildMaskPng(inputs) {
+    const { cells, cols, rows, canvasW, canvasH, fingerprint } = inputs;
+    const blurSigmaPx = inputs.blurSigmaPx && inputs.blurSigmaPx >= 0.3 ? inputs.blurSigmaPx : 0;
+    const cellCount = cols * rows;
+    if (cells.length !== cellCount) {
+        throw new Error(`buildMaskPng: expected ${cellCount} cells (${cols}×${rows}), got ${cells.length}`);
+    }
+    ensureCacheDir();
+    const pngPath = path.join(CACHE_DIR, `mask-${fingerprint}-${cols}x${rows}-${canvasW}x${canvasH}.png`);
+    if (fs.existsSync(pngPath)) {
+        return { pngPath, fresh: false };
+    }
+    // RGBA buffer at cell resolution.
+    const rgba = Buffer.alloc(cellCount * 4);
+    for (let i = 0; i < cellCount; i += 1) {
+        const c = cells[i];
+        const a = Math.max(0, Math.min(255, Math.round(c.alpha * 255)));
+        const v = c.polarity > 0 ? 255 : 0;
+        const off = i * 4;
+        rgba[off] = v;
+        rgba[off + 1] = v;
+        rgba[off + 2] = v;
+        rgba[off + 3] = a;
+    }
+    // STRETCH the cell grid onto the canvas — never preserve aspect, never crop.
+    // sharp's default (`cover`) center-cropped and silently threw away ~2/3 of
+    // the cells on any canvas whose aspect differed from cols:rows (a 64x36 grid
+    // on a 720x1280 portrait clip kept 20 columns, stretched) — the mark
+    // rendered, the decoder found noise (gate-34 catch).
+    let px = (0, raster_1.stretchNearestRgba)(rgba, cols, rows, canvasW, canvasH);
+    // Soft cell edges (see `blurSigmaPx`). All four channels blur together, so
+    // alpha ramps with the colour — exactly the low-frequency bump we want.
+    if (blurSigmaPx > 0)
+        px = (0, raster_1.blurRgba)(px, canvasW, canvasH, blurSigmaPx);
+    fs.writeFileSync(pngPath, (0, raster_1.encodePng)(px, canvasW, canvasH, 6));
+    return { pngPath, fresh: true };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Probe per-cell average luminance from the source video at render
+ * time. Populates the sidecar's `hostReference.luminanceGrid`, which
+ * lets the decoder subtract the host signal cleanly and recover the
+ * watermark with ~10 dB more SNR than blind correlation.
+ *
+ * This is the load-bearing "m0saic edge" the original plan called out
+ * — the engine authored the geometry, so we can also tell the decoder
+ * exactly what the host looked like before the watermark was applied.
+ *
+ * Implementation
+ * --------------
+ * A thin wrapper over the family's shared sampler
+ * (`../../_shared/cellLuminance` → `ctx.analysis.cellLuminance`). All this
+ * file adds is the options that make the probe see what the RENDER will
+ * see:
+ *
+ *  - **cover-scale + center-crop** (`coverTo`), because the pipeline fits
+ *    the source to the output canvas that way. Skip it and the cells
+ *    reported don't correspond to the pixels actually composited.
+ *  - **last-frame hold** (`holdLastFrame`), because when the requested
+ *    duration outlasts the source the pipeline holds the final frame for
+ *    the remainder. Skip it and the reference covers only the moving part
+ *    while the delivered video is largely a frozen frame.
+ *
+ * Either omission leaves residual host bias that swamps the watermark
+ * (α≈0.012 is only ~1.6 luma levels) and decode fails on real content.
+ *
+ * The cell-grid tail (`scale=COLS:ROWS:flags=area,format=gray`) and the
+ * frame-averaging live in the engine pass, so the verify template runs
+ * byte-identical sampling on the delivered file.
+ *
+ * Determinism
+ * -----------
+ * Deterministic given a deterministic source video. Re-encoded
+ * sources at different bitrates may shift per-cell luminance by ±1;
+ * BCH's error-correction tolerates this.
+ */
+import { CellSampleError, type CellLuminanceSampler } from "../../_shared/cellLuminance";
+export interface ProbeHostInputs {
+    videoPath: string;
+    cols: number;
+    rows: number;
+    /**
+     * Output canvas dimensions the watermark will be rendered at. The
+     * probe applies the same cover-scale (`scale=W:H:force_original_aspect_ratio=increase,crop=W:H`)
+     * the render pipeline does, so per-cell luminance matches exactly
+     * after the source is composited onto the canvas. Without this
+     * match, baseline subtraction leaves residual host bias and decode
+     * fails on real-content frames.
+     */
+    canvasW: number;
+    canvasH: number;
+    /** Output frame rate the render will use. Probe matches it to align frame counts. */
+    fps: number;
+    /** Output duration ms the render will use. Probe trims source to match. */
+    durationMs: number;
+}
+export interface ProbeHostResult {
+    /** Per-cell average luminance (0..255), row-major, length cols*rows. */
+    luminanceGrid: number[];
+    /** Number of frames the average was computed over. */
+    frameCount: number;
+}
+export declare class ProbeHostError extends Error {
+    readonly code: CellSampleError["code"];
+    constructor(code: CellSampleError["code"], message: string);
+}
+export declare function probeHostLuminance(sampler: CellLuminanceSampler | undefined, inputs: ProbeHostInputs): Promise<ProbeHostResult>;

package/dist/m0saic/forensic/watermark/video/v1/probeHost.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Probe per-cell average luminance from the source video at render
+ * time. Populates the sidecar's `hostReference.luminanceGrid`, which
+ * lets the decoder subtract the host signal cleanly and recover the
+ * watermark with ~10 dB more SNR than blind correlation.
+ *
+ * This is the load-bearing "m0saic edge" the original plan called out
+ * — the engine authored the geometry, so we can also tell the decoder
+ * exactly what the host looked like before the watermark was applied.
+ *
+ * Implementation
+ * --------------
+ * A thin wrapper over the family's shared sampler
+ * (`../../_shared/cellLuminance` → `ctx.analysis.cellLuminance`). All this
+ * file adds is the options that make the probe see what the RENDER will
+ * see:
+ *
+ *  - **cover-scale + center-crop** (`coverTo`), because the pipeline fits
+ *    the source to the output canvas that way. Skip it and the cells
+ *    reported don't correspond to the pixels actually composited.
+ *  - **last-frame hold** (`holdLastFrame`), because when the requested
+ *    duration outlasts the source the pipeline holds the final frame for
+ *    the remainder. Skip it and the reference covers only the moving part
+ *    while the delivered video is largely a frozen frame.
+ *
+ * Either omission leaves residual host bias that swamps the watermark
+ * (α≈0.012 is only ~1.6 luma levels) and decode fails on real content.
+ *
+ * The cell-grid tail (`scale=COLS:ROWS:flags=area,format=gray`) and the
+ * frame-averaging live in the engine pass, so the verify template runs
+ * byte-identical sampling on the delivered file.
+ *
+ * Determinism
+ * -----------
+ * Deterministic given a deterministic source video. Re-encoded
+ * sources at different bitrates may shift per-cell luminance by ±1;
+ * BCH's error-correction tolerates this.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProbeHostError = void 0;
+exports.probeHostLuminance = probeHostLuminance;
+const cellLuminance_1 = require("../../_shared/cellLuminance");
+class ProbeHostError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "ProbeHostError";
+        this.code = code;
+    }
+}
+exports.ProbeHostError = ProbeHostError;
+async function probeHostLuminance(sampler, inputs) {
+    try {
+        return await (0, cellLuminance_1.sampleCellLuminance)(sampler, inputs.videoPath, {
+            cols: inputs.cols,
+            rows: inputs.rows,
+            // Mirror the render pipeline's source-scale chain (cover-fit to
+            // canvas, then center-crop) ahead of the cell-grid downsample…
+            coverTo: { width: inputs.canvasW, height: inputs.canvasH },
+            // …and what it does when the render OUTLASTS the source: the
+            // pipeline holds the final frame for the remainder. Without this,
+            // `-t` simply stops the probe at the source's end, so the reference
+            // averages only the moving part while the delivered video is (often
+            // mostly) a frozen frame. The two then describe different videos,
+            // baseline subtraction leaves a large DC + per-cell bias, and
+            // decode fails — silently and only for renders longer than their
+            // source. A no-op when the source already covers the duration.
+            holdLastFrame: true,
+            // Pin rate + duration so the sampled frame count matches what the
+            // watermarked output will produce.
+            fps: inputs.fps,
+            durationMs: inputs.durationMs,
+        }, "probe");
+    }
+    catch (err) {
+        // Re-home onto this module's error class: `forensic-watermark.ts`
+        // branches on `instanceof ProbeHostError` to render an error card
+        // instead of throwing.
+        if (err instanceof cellLuminance_1.CellSampleError)
+            throw new ProbeHostError(err.code, err.message);
+        throw err;
+    }
+}

package/dist/m0saic/github/client.d.ts

@@ -0,0 +1,200 @@
+/**
+ * GitHub REST client for the `repo-facts-fetcher` (F5).
+ *
+ * Low-level transport ONLY — auth-header assembly, Link-header pagination,
+ * `202` warm-up retry for `stats/*`, a per-run call-budget ledger, and thin
+ * typed wrappers for the endpoints in the F5 plan (Seam B). It returns
+ * close-to-raw GitHub JSON; normalizing that into the bounded `GithubRepoFacts`
+ * sheet (coverage record, degradation ladder, star-Δ walk) is the fetcher's job
+ * (Phase 2), not this file's.
+ *
+ * `fetch` and `sleep` are INJECTABLE (constructor args, sane global defaults) so
+ * unit tests stub transport + retry timing without module hacks or real waits.
+ *
+ * GitHub-API only. `baseUrl` targets `api.github.com` or a GitHub Enterprise
+ * host that speaks the same REST API — NOT a Gitea/Forgejo forge (their `/api/v1`
+ * shapes differ; e.g. FFmpeg's `code.ffmpeg.org` uses `stars_count`, not
+ * `stargazers_count`). A forge connector is a separate, deferred publisher.
+ */
+/** Minimal structural `fetch` — compatible with `globalThis.fetch` AND the
+ *  host-connection probe's `fetchImpl` seam (which omits `headers`). */
+export type GithubFetchResponse = {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    headers?: {
+        get(name: string): string | null;
+    };
+};
+export type GithubFetch = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<GithubFetchResponse>;
+export type GithubClientOptions = {
+    /** API base. Default `https://api.github.com`. Trailing slash tolerated. */
+    baseUrl?: string;
+    /** PAT. When set, sent as `Authorization: Bearer`. Absent → anonymous. */
+    token?: string;
+    /** Injectable transport. Default `globalThis.fetch`. */
+    fetchImpl?: GithubFetch;
+    /** Injectable delay for 202 retries. Default real `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Hard cap on API calls this client makes. Default `Infinity`. */
+    callBudget?: number;
+    /** Sent as `User-Agent` (GitHub requires one). */
+    userAgent?: string;
+    /** Caller abort signal, forwarded to every request. */
+    signal?: AbortSignal;
+};
+/** Parsed rel-targets from a `Link` header. */
+export type GithubLinks = {
+    next?: string;
+    prev?: string;
+    first?: string;
+    last?: string;
+};
+/** One response the client hands back. `body` is parsed JSON (or `undefined`). */
+export type GithubResponse<T = unknown> = {
+    status: number;
+    ok: boolean;
+    body: T | undefined;
+    links: GithubLinks;
+    /** True when the call-budget was already spent — no request was made. */
+    budgetHit: boolean;
+};
+/** Parse a GitHub `Link` header into rel-targets. */
+export declare function parseLinkHeader(header: string | null | undefined): GithubLinks;
+/** Committer-date window → GitHub `since`/`until` query params.
+ *  `end` is inclusive Sunday, so `until` is `end + 1 day` at 00:00Z. */
+export declare function windowToSinceUntil(window: {
+    startISO: string;
+    endISO: string;
+}): {
+    since: string;
+    until: string;
+};
+export declare class GithubClient {
+    readonly baseUrl: string;
+    readonly authenticated: boolean;
+    private readonly token?;
+    private readonly fetchImpl;
+    private readonly sleep;
+    private readonly userAgent;
+    private readonly signal?;
+    readonly callBudget: number;
+    private calls;
+    /** Latest `x-ratelimit-{limit,remaining}` seen, if any. */
+    rateLimit?: {
+        limit: number;
+        remaining: number;
+    };
+    constructor(opts?: GithubClientOptions);
+    /** API calls made so far (for the fetcher's coverage/truncation record). */
+    callsMade(): number;
+    private headers;
+    /** One raw request. Never throws on HTTP status; budget-exhaustion returns a
+     *  `budgetHit` sentinel so the fetcher can record truncation instead of dying. */
+    request<T = unknown>(path: string, accept?: string): Promise<GithubResponse<T>>;
+    /** Walk `rel="next"` pages, concatenating arrays, until exhausted / capped /
+     *  budget-hit. Stops on the first non-200 or non-array page. */
+    paginate<T = unknown>(path: string, opts?: {
+        accept?: string;
+        maxItems?: number;
+    }): Promise<{
+        items: T[];
+        truncated: boolean;
+        budgetHit: boolean;
+    }>;
+    /** `stats/*` endpoints answer `202` while GitHub computes — bounded retry via
+     *  the injected `sleep`. Returns the last response (may still be 202/422). */
+    getStats<T = unknown>(path: string, opts?: {
+        retries?: number;
+        waitMs?: number;
+    }): Promise<GithubResponse<T>>;
+    getRepo(repo: string): Promise<GithubResponse<GithubRepoResponse>>;
+    /** Window commits (the API filters `since`/`until` on COMMITTER date). */
+    listCommits(repo: string, window: {
+        startISO: string;
+        endISO: string;
+    }, opts?: {
+        maxItems?: number;
+    }): Promise<{
+        items: GithubCommitListItem[];
+        truncated: boolean;
+        budgetHit: boolean;
+    }>;
+    getCommitDetail(repo: string, sha: string): Promise<GithubResponse<GithubCommitDetail>>;
+    getCommitActivity(repo: string): Promise<GithubResponse<GithubCommitActivityWeek[]>>;
+    getCodeFrequency(repo: string): Promise<GithubResponse<GithubCodeFrequencyWeek[]>>;
+    /** One page of stargazers WITH `starred_at` (the `star+json` media type).
+     *  Anonymous requests get `401` here — the fetcher degrades on that. */
+    getStargazersPage(repo: string, page: number): Promise<GithubResponse<GithubStargazer[]>>;
+    getRateLimit(): Promise<GithubResponse<GithubRateLimitResponse>>;
+}
+export type GithubRepoResponse = {
+    full_name: string;
+    name: string;
+    default_branch: string;
+    description: string | null;
+    stargazers_count: number;
+    forks_count: number;
+    subscribers_count: number;
+    open_issues_count: number;
+    has_issues: boolean;
+    pushed_at: string;
+};
+export type GithubGitUser = {
+    name?: string;
+    date?: string;
+};
+export type GithubAuthorRef = {
+    login?: string;
+    avatar_url?: string;
+} | null;
+export type GithubCommitListItem = {
+    sha: string;
+    commit: {
+        message: string;
+        author?: GithubGitUser;
+        committer?: GithubGitUser;
+    };
+    author?: GithubAuthorRef;
+};
+export type GithubCommitFile = {
+    filename: string;
+    additions: number;
+    deletions: number;
+    status: string;
+};
+export type GithubCommitDetail = GithubCommitListItem & {
+    stats?: {
+        additions: number;
+        deletions: number;
+        total: number;
+    };
+    files?: GithubCommitFile[];
+};
+export type GithubCommitActivityWeek = {
+    week: number;
+    days: number[];
+    total: number;
+};
+/** `stats/code_frequency` rows are `[weekUnixSeconds, additions, deletions]`. */
+export type GithubCodeFrequencyWeek = [number, number, number];
+export type GithubStargazer = {
+    starred_at: string;
+    user?: {
+        login?: string;
+    };
+};
+export type GithubRateLimitResponse = {
+    resources?: {
+        core?: {
+            limit: number;
+            remaining: number;
+        };
+    };
+};