@sitelensapi/compare

PNG screenshot comparison for SiteLens: pixelmatch diff, changed-pixel metrics, threshold pass/fail, and optional diff image output.

What it does

• PNG visual diff — magenta highlights on mismatched pixels; unchanged areas show the current image
• Changed pixel count — raw count from pixelmatch
• Changed percentage — changedPixelCount / totalPixelCount, rounded to four decimal places
• Threshold pass/fail — passed when changedPercent <= thresholdPercent (0–100)
• diff.png generation — PNG buffer in diffPng (written by callers under screenshot-compare/)

Usage

import { readFile, writeFile } from "node:fs/promises";
import { comparePngBuffers } from "@sitelensapi/compare";

const baselinePng = await readFile("baseline.png");
const currentPng = await readFile("current.png");

const result = comparePngBuffers({
  baselinePng,
  currentPng,
  thresholdPercent: 0.5, // allow up to 0.5% changed pixels
});

console.log(result.passed, result.changedPercent, result.changedPixelCount);

if (result.diffPng.byteLength > 0) {
  await writeFile("screenshot-compare/diff.png", result.diffPng);
}

Constants for persisted artifacts: COMPARE_ARTIFACT_SUBDIR, COMPARE_RESULT_JSON_FILENAME, COMPARE_DIFF_FILENAME. Load inputs with loadPngFromSource() (path, URL, or buffer).

Artifact layout

Callers typically write:

screenshot-compare/compare-result.json
screenshot-compare/diff.png

compare-result.json shape is typed as ComparePersistedResult (schema version 1).

Used by

• SiteLens MCP (sitelens_compare_screenshots)
• SiteLens API (hosted compare jobs)
• SiteLens Desktop (local runtime compare)

Limits and edge cases

| Limit | Value | |-------|--------| | File size | 35 MB (MAX_COMPARE_FILE_BYTES) | | Image area | 14M pixels (MAX_COMPARE_PIXELS) |

Dimension mismatch: If baseline and current width/height differ, passed is false, dimensionsMatch is false, changedPercent is 100, and diffPng is empty (no diff image).

Install

npm install @sitelensapi/compare

Requires Node.js ≥ 20.

Monorepo

pnpm --filter @sitelensapi/compare run build
pnpm --filter @sitelensapi/compare test

SiteLens

Part of SiteLens — visual QA, screenshot compare, and MCP tooling.