@hyperframes/engine 0.7.59 → 0.7.60

package/dist/utils/gpuParityDiff.js

@@ -0,0 +1,205 @@
+/**
+ * GPU Parity Diff — diagnostic helpers for detecting shape-dependent
+ * hardware-GPU capture bugs by comparing frames captured via the two
+ * capture paths (hardware-GPU vs software-GPU / screenshot bypass).
+ *
+ * Field pattern this exists to catch:
+ *
+ *   • ts=1784049136 · hardware-GPU capture emitted intermittent black
+ *     rectangles in one scene; `--no-browser-gpu --low-memory-mode
+ *     --workers 1` (software-GPU screenshot mode) resolved it.
+ *   • ts=1784032286 · animated `clip-path` on a large image → intermittent
+ *     black rectangles from Chrome capture; deterministic precomposited
+ *     swipe states removed the artifact.
+ *   • Baseline · JetBrains Mono glyph-drop on parallel/BeginFrame text
+ *     capture.
+ *
+ * Common shape: hardware-GPU writes solid-black regions where content
+ * should exist; software-GPU / screenshot fallback renders the same
+ * region correctly. A raw per-pixel diff is a coarse signal for this —
+ * on its own it fires on every animation frame's compositor jitter, so
+ * this module also isolates the *asymmetric* black-in-A-only pattern
+ * that is the diagnostic fingerprint of the bug.
+ *
+ * This module is the reduced-scope first pass: a pure helper + unit
+ * tests. Wiring a `hyperframes verify-gpu-parity` CLI surface, capture
+ * orchestration, and integration coverage is intentionally deferred to
+ * a follow-up so the diagnostic primitive can land and be exercised
+ * against real captured frames in isolation.
+ */
+import { decodePng } from "./alphaBlit.js";
+// ── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_PIXEL_CHANNEL_TOLERANCE = 8;
+const DEFAULT_BLACK_SUM_THRESHOLD = 12;
+const DEFAULT_CONTENT_SUM_THRESHOLD = 32;
+const DEFAULT_BLACK_ONLY_FRACTION_THRESHOLD = 0.001;
+// ── Core diff ───────────────────────────────────────────────────────────────
+/**
+ * Compare two RGBA frames captured via different GPU paths.
+ *
+ * The two inputs must have identical dimensions; on mismatch this throws
+ * (with the mismatched sizes surfaced in the message) so callers cannot
+ * silently compare misaligned frames.
+ *
+ * Alpha channel is *not* considered for the black-only detection — Chrome's
+ * capture output is opaque along the code paths this diagnostic targets,
+ * and considering alpha would false-positive on legitimately transparent
+ * pixels. `pixelChannelTolerance` also compares only R/G/B for the same
+ * reason.
+ */
+export function diffGpuParityFrames(a, b, options = {}) {
+    if (a.width !== b.width || a.height !== b.height) {
+        throw new Error(`diffGpuParityFrames: frame size mismatch — A is ${a.width}x${a.height}, ` +
+            `B is ${b.width}x${b.height}`);
+    }
+    const expectedLen = a.width * a.height * 4;
+    if (a.data.length !== expectedLen) {
+        throw new Error(`diffGpuParityFrames: frame A data length ${a.data.length} does not match ` +
+            `expected ${expectedLen} (${a.width}x${a.height} * 4)`);
+    }
+    if (b.data.length !== expectedLen) {
+        throw new Error(`diffGpuParityFrames: frame B data length ${b.data.length} does not match ` +
+            `expected ${expectedLen} (${b.width}x${b.height} * 4)`);
+    }
+    const tol = options.pixelChannelTolerance ?? DEFAULT_PIXEL_CHANNEL_TOLERANCE;
+    const blackSum = options.blackSumThreshold ?? DEFAULT_BLACK_SUM_THRESHOLD;
+    const contentSum = options.contentSumThreshold ?? DEFAULT_CONTENT_SUM_THRESHOLD;
+    if (contentSum <= blackSum) {
+        throw new Error(`diffGpuParityFrames: contentSumThreshold (${contentSum}) must be strictly greater ` +
+            `than blackSumThreshold (${blackSum}) — overlapping thresholds would double-classify ` +
+            `borderline pixels`);
+    }
+    const total = a.width * a.height;
+    const aData = a.data;
+    const bData = b.data;
+    let diffPixels = 0;
+    let blackOnlyAPixels = 0;
+    let blackOnlyBPixels = 0;
+    let aMinX = a.width;
+    let aMinY = a.height;
+    let aMaxX = -1;
+    let aMaxY = -1;
+    let bMinX = a.width;
+    let bMinY = a.height;
+    let bMaxX = -1;
+    let bMaxY = -1;
+    for (let y = 0; y < a.height; y++) {
+        for (let x = 0; x < a.width; x++) {
+            const i = (y * a.width + x) * 4;
+            const ar = aData[i] ?? 0;
+            const ag = aData[i + 1] ?? 0;
+            const ab = aData[i + 2] ?? 0;
+            const br = bData[i] ?? 0;
+            const bg = bData[i + 1] ?? 0;
+            const bb = bData[i + 2] ?? 0;
+            if (Math.abs(ar - br) > tol || Math.abs(ag - bg) > tol || Math.abs(ab - bb) > tol) {
+                diffPixels++;
+            }
+            const aSum = ar + ag + ab;
+            const bSum = br + bg + bb;
+            if (aSum <= blackSum && bSum >= contentSum) {
+                blackOnlyAPixels++;
+                if (x < aMinX)
+                    aMinX = x;
+                if (y < aMinY)
+                    aMinY = y;
+                if (x > aMaxX)
+                    aMaxX = x;
+                if (y > aMaxY)
+                    aMaxY = y;
+            }
+            else if (bSum <= blackSum && aSum >= contentSum) {
+                blackOnlyBPixels++;
+                if (x < bMinX)
+                    bMinX = x;
+                if (y < bMinY)
+                    bMinY = y;
+                if (x > bMaxX)
+                    bMaxX = x;
+                if (y > bMaxY)
+                    bMaxY = y;
+            }
+        }
+    }
+    return {
+        width: a.width,
+        height: a.height,
+        totalPixels: total,
+        diffPixels,
+        diffFraction: diffPixels / total,
+        blackOnlyInA: {
+            pixels: blackOnlyAPixels,
+            fraction: blackOnlyAPixels / total,
+            boundingBox: blackOnlyAPixels === 0
+                ? null
+                : { x: aMinX, y: aMinY, width: aMaxX - aMinX + 1, height: aMaxY - aMinY + 1 },
+        },
+        blackOnlyInB: {
+            pixels: blackOnlyBPixels,
+            fraction: blackOnlyBPixels / total,
+            boundingBox: blackOnlyBPixels === 0
+                ? null
+                : { x: bMinX, y: bMinY, width: bMaxX - bMinX + 1, height: bMaxY - bMinY + 1 },
+        },
+    };
+}
+/**
+ * PNG-buffer convenience wrapper around `diffGpuParityFrames`. Decodes
+ * both inputs via `decodePng` and delegates. Errors from the decoder are
+ * re-thrown with `cause` preserved so the failing side (A or B) is
+ * obvious in the stack.
+ */
+export function diffGpuParityPngs(pngA, pngB, options = {}) {
+    let a;
+    let b;
+    try {
+        a = decodePng(pngA);
+    }
+    catch (err) {
+        throw new Error(`diffGpuParityPngs: failed to decode frame A`, { cause: err });
+    }
+    try {
+        b = decodePng(pngB);
+    }
+    catch (err) {
+        throw new Error(`diffGpuParityPngs: failed to decode frame B`, { cause: err });
+    }
+    return diffGpuParityFrames(a, b, options);
+}
+/**
+ * Verdict wrapper — returns `{ ok, reason }` suitable for a follow-up
+ * CLI or gate to emit. `ok === false` when either black-only fraction
+ * exceeds `blackOnlyFractionThreshold`. Raw diff numbers are always
+ * included on both branches so callers can log or gate on their own
+ * metrics without a second pass.
+ */
+export function verifyGpuParity(a, b, options = {}) {
+    const diff = diffGpuParityFrames(a, b, options);
+    const threshold = options.blackOnlyFractionThreshold ?? DEFAULT_BLACK_ONLY_FRACTION_THRESHOLD;
+    if (diff.blackOnlyInA.fraction > threshold) {
+        const bb = diff.blackOnlyInA.boundingBox;
+        const region = bb ? ` (bbox ${bb.x},${bb.y} ${bb.width}x${bb.height})` : "";
+        return {
+            ok: false,
+            reason: `hardware-GPU frame has ${diff.blackOnlyInA.pixels} pixel(s) ` +
+                `(${(diff.blackOnlyInA.fraction * 100).toFixed(3)}%) that are solid-black ` +
+                `while software-GPU frame has content there${region} — likely shape-dependent ` +
+                `hardware-GPU capture bug`,
+            diff,
+        };
+    }
+    if (diff.blackOnlyInB.fraction > threshold) {
+        const bb = diff.blackOnlyInB.boundingBox;
+        const region = bb ? ` (bbox ${bb.x},${bb.y} ${bb.width}x${bb.height})` : "";
+        return {
+            ok: false,
+            reason: `software-GPU frame has ${diff.blackOnlyInB.pixels} pixel(s) ` +
+                `(${(diff.blackOnlyInB.fraction * 100).toFixed(3)}%) that are solid-black ` +
+                `while hardware-GPU frame has content there${region} — unexpected inverse ` +
+                `pattern, worth investigating`,
+            diff,
+        };
+    }
+    return { ok: true, reason: "", diff };
+}
+//# sourceMappingURL=gpuParityDiff.js.map

package/dist/utils/gpuParityDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpuParityDiff.js","sourceRoot":"","sources":["../../src/utils/gpuParityDiff.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.7.59",
+  "version": "0.7.60",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "^0.7.59"
+    "@hyperframes/core": "^0.7.60"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",