@bridge_gpt/mcp-server 0.2.18 → 0.2.19

package/build/visual-diff-worker.js

@@ -0,0 +1,313 @@
+/**
+ * visual-diff-worker.ts — deterministic PNG pixel-diff engine (BAPI-563).
+ *
+ * This module runs the CPU-heavy part of the `visual_diff` MCP tool: decode two
+ * PNG buffers with pngjs, apply mask boxes, diff them with pixelmatch (with an
+ * anti-aliasing-tolerant threshold so OS font rendering never inflates the
+ * mismatch), and derive coarse diff regions + a heatmap. Keeping this off the
+ * MCP server's event loop is why it is spawned as a worker thread from
+ * `visual-diff.ts` (see computeVisualDiffInWorker), but the actual logic lives
+ * in the exported pure function `computePngVisualDiff` so it can be unit-tested
+ * directly and reused inline as a fallback when worker spawning is unavailable.
+ *
+ * Dimensions are NEVER rescaled: a comp/render size mismatch is a hard signal
+ * (`dimension_match: false`) surfaced via a union canvas, not silently resized
+ * away.
+ */
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+import { isMainThread, parentPort, workerData } from "worker_threads";
+/** Anti-aliasing-tolerant pixelmatch color-distance threshold (0..1). */
+export const PIXELMATCH_COLOR_THRESHOLD = 0.1;
+/** Default pass budget (percent) — never 0%, since AA/font rendering makes a
+ *  true 0% mismatch impossible. Callers override via the `threshold` param. */
+export const DEFAULT_PASS_MISMATCH_PCT = 2;
+/** Maximum number of coarse diff regions returned (deterministic cap). */
+export const MAX_DIFF_REGIONS = 10;
+function decodePng(buffer, label) {
+    try {
+        const png = PNG.sync.read(Buffer.from(buffer));
+        if (!Number.isInteger(png.width) ||
+            !Number.isInteger(png.height) ||
+            png.width <= 0 ||
+            png.height <= 0) {
+            return {
+                ok: false,
+                error: "IMAGE_DECODE_FAILED",
+                status: 422,
+                message: `Decoded ${label} PNG has invalid dimensions.`,
+            };
+        }
+        return { width: png.width, height: png.height, data: png.data };
+    }
+    catch {
+        // Never surface a raw pngjs stack trace to the caller.
+        return {
+            ok: false,
+            error: "IMAGE_DECODE_FAILED",
+            status: 422,
+            message: `Failed to decode ${label} image as PNG.`,
+        };
+    }
+}
+/**
+ * Extract the top-left overlapW×overlapH region of a decoded RGBA image into a
+ * fresh contiguous RGBA buffer (no scaling).
+ */
+function extractOverlap(src, srcW, overlapW, overlapH) {
+    const out = new Uint8Array(overlapW * overlapH * 4);
+    for (let y = 0; y < overlapH; y++) {
+        const srcRow = y * srcW * 4;
+        const dstRow = y * overlapW * 4;
+        out.set(src.subarray(srcRow, srcRow + overlapW * 4), dstRow);
+    }
+    return out;
+}
+/** Build a union-sized boolean grid marking pixels covered by any mask box. */
+function buildMaskGrid(boxes, unionW, unionH) {
+    const grid = new Uint8Array(unionW * unionH);
+    for (const box of boxes) {
+        const x0 = Math.max(0, Math.floor(box.x));
+        const y0 = Math.max(0, Math.floor(box.y));
+        const x1 = Math.min(unionW, Math.floor(box.x + box.width));
+        const y1 = Math.min(unionH, Math.floor(box.y + box.height));
+        for (let y = y0; y < y1; y++) {
+            for (let x = x0; x < x1; x++) {
+                grid[y * unionW + x] = 1;
+            }
+        }
+    }
+    return grid;
+}
+/** Fill masked cells (within the overlap region) with opaque black in-place. */
+function applyMaskToOverlap(buf, overlapW, overlapH, maskGrid, unionW) {
+    for (let y = 0; y < overlapH; y++) {
+        for (let x = 0; x < overlapW; x++) {
+            if (maskGrid[y * unionW + x] === 1) {
+                const off = (y * overlapW + x) * 4;
+                buf[off] = 0;
+                buf[off + 1] = 0;
+                buf[off + 2] = 0;
+                buf[off + 3] = 255;
+            }
+        }
+    }
+}
+/**
+ * Group contiguous differing pixels into coarse bounding boxes via an iterative
+ * 4-connectivity flood fill. Deterministic: regions are sorted by pixel count
+ * descending, then y, then x, and capped at `maxRegions`.
+ */
+function extractDiffRegions(mask, width, height, maxRegions) {
+    const visited = new Uint8Array(width * height);
+    const regions = [];
+    const stack = [];
+    for (let start = 0; start < mask.length; start++) {
+        if (mask[start] === 0 || visited[start] === 1)
+            continue;
+        let minX = width;
+        let minY = height;
+        let maxX = -1;
+        let maxY = -1;
+        let pixels = 0;
+        stack.length = 0;
+        stack.push(start);
+        visited[start] = 1;
+        while (stack.length > 0) {
+            const idx = stack.pop();
+            const x = idx % width;
+            const y = (idx - x) / width;
+            pixels++;
+            if (x < minX)
+                minX = x;
+            if (y < minY)
+                minY = y;
+            if (x > maxX)
+                maxX = x;
+            if (y > maxY)
+                maxY = y;
+            // 4-connected neighbors.
+            if (x > 0) {
+                const n = idx - 1;
+                if (mask[n] === 1 && visited[n] === 0) {
+                    visited[n] = 1;
+                    stack.push(n);
+                }
+            }
+            if (x < width - 1) {
+                const n = idx + 1;
+                if (mask[n] === 1 && visited[n] === 0) {
+                    visited[n] = 1;
+                    stack.push(n);
+                }
+            }
+            if (y > 0) {
+                const n = idx - width;
+                if (mask[n] === 1 && visited[n] === 0) {
+                    visited[n] = 1;
+                    stack.push(n);
+                }
+            }
+            if (y < height - 1) {
+                const n = idx + width;
+                if (mask[n] === 1 && visited[n] === 0) {
+                    visited[n] = 1;
+                    stack.push(n);
+                }
+            }
+        }
+        regions.push({
+            x: minX,
+            y: minY,
+            width: maxX - minX + 1,
+            height: maxY - minY + 1,
+            pixels,
+        });
+    }
+    regions.sort((a, b) => {
+        if (b.pixels !== a.pixels)
+            return b.pixels - a.pixels;
+        if (a.y !== b.y)
+            return a.y - b.y;
+        return a.x - b.x;
+    });
+    return regions.slice(0, Math.max(0, maxRegions));
+}
+/**
+ * Pure deterministic PNG visual diff. Given two PNG buffers plus mask boxes and
+ * thresholds, returns mismatch percent, dimension-match signal, coarse diff
+ * regions, and a base64 heatmap — or a structured decode error. Never throws a
+ * raw stack to the caller.
+ */
+export function computePngVisualDiff(input) {
+    const comp = decodePng(input.compPngBuffer, "comp");
+    if ("ok" in comp && comp.ok === false)
+        return comp;
+    const render = decodePng(input.renderPngBuffer, "render");
+    if ("ok" in render && render.ok === false)
+        return render;
+    const compImg = comp;
+    const renderImg = render;
+    const dimensionMatch = compImg.width === renderImg.width && compImg.height === renderImg.height;
+    const unionW = Math.max(compImg.width, renderImg.width);
+    const unionH = Math.max(compImg.height, renderImg.height);
+    const overlapW = Math.min(compImg.width, renderImg.width);
+    const overlapH = Math.min(compImg.height, renderImg.height);
+    const maskGrid = buildMaskGrid(input.maskBoxes ?? [], unionW, unionH);
+    // Diff the OVERLAP region with pixelmatch (both images have real, opaque
+    // pixels there, so alpha-blending never distorts the comparison). Dimensions
+    // are NEVER rescaled: the non-overlap region is handled explicitly below.
+    const output = new Uint8Array(unionW * unionH * 4);
+    const diffMask = new Uint8Array(unionW * unionH);
+    let differingPixels = 0;
+    if (overlapW > 0 && overlapH > 0) {
+        const compOverlap = extractOverlap(compImg.data, compImg.width, overlapW, overlapH);
+        const renderOverlap = extractOverlap(renderImg.data, renderImg.width, overlapW, overlapH);
+        applyMaskToOverlap(compOverlap, overlapW, overlapH, maskGrid, unionW);
+        applyMaskToOverlap(renderOverlap, overlapW, overlapH, maskGrid, unionW);
+        const overlapOut = new Uint8Array(overlapW * overlapH * 4);
+        try {
+            differingPixels = pixelmatch(compOverlap, renderOverlap, overlapOut, overlapW, overlapH, {
+                threshold: input.pixelmatchColorThreshold,
+                // includeAA: false => anti-aliased pixels are detected and NOT counted
+                // as diffs, so OS font rendering does not inflate the mismatch.
+                includeAA: false,
+                diffColor: [255, 0, 0],
+                diffColorAlt: [255, 0, 0],
+                aaColor: [255, 255, 0],
+            });
+        }
+        catch {
+            return {
+                ok: false,
+                error: "DIFF_FAILED",
+                status: 500,
+                message: "Pixel comparison failed.",
+            };
+        }
+        // Copy the overlap heatmap into the union output's top-left; differing
+        // pixels are drawn pure red ([255,0,0]).
+        for (let y = 0; y < overlapH; y++) {
+            for (let x = 0; x < overlapW; x++) {
+                const so = (y * overlapW + x) * 4;
+                const uo = (y * unionW + x) * 4;
+                output[uo] = overlapOut[so];
+                output[uo + 1] = overlapOut[so + 1];
+                output[uo + 2] = overlapOut[so + 2];
+                output[uo + 3] = 255;
+                if (overlapOut[so] === 255 && overlapOut[so + 1] === 0 && overlapOut[so + 2] === 0) {
+                    diffMask[y * unionW + x] = 1;
+                }
+            }
+        }
+    }
+    // Non-overlap region: a union cell in-bounds for exactly ONE image is a hard
+    // dimension-mismatch difference (the render has area the comp does not account
+    // for, or vice versa) and is forced-counted — never rescaled away. Cells
+    // covered by a mask box are ignored.
+    for (let y = 0; y < unionH; y++) {
+        for (let x = 0; x < unionW; x++) {
+            const inComp = x < compImg.width && y < compImg.height;
+            const inRender = x < renderImg.width && y < renderImg.height;
+            if (inComp === inRender)
+                continue; // overlap (handled) or both-out (empty)
+            if (maskGrid[y * unionW + x] === 1)
+                continue;
+            const off = (y * unionW + x) * 4;
+            output[off] = 255;
+            output[off + 1] = 0;
+            output[off + 2] = 0;
+            output[off + 3] = 255;
+            diffMask[y * unionW + x] = 1;
+            differingPixels++;
+        }
+    }
+    const diffRegions = extractDiffRegions(diffMask, unionW, unionH, input.maxRegions ?? MAX_DIFF_REGIONS);
+    const totalPixels = unionW * unionH;
+    const mismatchPct = totalPixels > 0 ? (differingPixels / totalPixels) * 100 : 0;
+    const passed = dimensionMatch && mismatchPct <= input.passMismatchPct;
+    let heatmapBase64;
+    try {
+        const png = new PNG({ width: unionW, height: unionH });
+        png.data = Buffer.from(output);
+        heatmapBase64 = PNG.sync.write(png).toString("base64");
+    }
+    catch {
+        return {
+            ok: false,
+            error: "DIFF_FAILED",
+            status: 500,
+            message: "Failed to encode diff heatmap.",
+        };
+    }
+    return {
+        ok: true,
+        mismatch_pct: mismatchPct,
+        dimension_match: dimensionMatch,
+        passed,
+        diff_regions: diffRegions,
+        comp_dimensions: { width: compImg.width, height: compImg.height },
+        render_dimensions: { width: renderImg.width, height: renderImg.height },
+        differing_pixels: differingPixels,
+        total_pixels: totalPixels,
+        heatmap_base64: heatmapBase64,
+    };
+}
+// Worker-thread entrypoint: when spawned via new Worker(...), read the input
+// from workerData, run the pure diff, and post the structured result back. Any
+// unexpected failure is returned as a structured DIFF_FAILED envelope rather
+// than crashing the worker.
+if (!isMainThread && parentPort) {
+    try {
+        const result = computePngVisualDiff(workerData);
+        parentPort.postMessage(result);
+    }
+    catch (err) {
+        parentPort.postMessage({
+            ok: false,
+            error: "DIFF_FAILED",
+            status: 500,
+            message: `Diff worker failed: ${err instanceof Error ? err.message : "unknown error"}`,
+        });
+    }
+}