pdf-visual-compare 3.4.0 → 3.5.0

package/README.md

@@ -76,8 +76,8 @@ const isEqual = await comparePdf('./actual.pdf', './expected.pdf', {
   // 0 = pixel-perfect match required (default). Must be >= 0.
   compareThreshold: 200,
 
-  // Per-page exclusion zones, matched by array index (0-based).
-  // Index 0 → first page, index 1 → second page, etc.
+  // Per-page exclusion zones, matched by the `pageNumber` field (1-based).
+  // `pageNumber: 1` → first page, `pageNumber: 2` → second page, etc.
   // Pixel coordinates are relative to the rendered PNG at the configured viewportScale.
   excludedAreas: [
     {
@@ -128,11 +128,11 @@ const isEqual = await comparePdf(actual, expected);
 
 ### `comparePdf(actualPdf, expectedPdf, options?)`
 
-| Parameter     | Type                              | Description                               |
-| ------------- | --------------------------------- | ----------------------------------------- |
-| `actualPdf`   | `string \| Buffer`                | File path or buffer of the PDF under test |
-| `expectedPdf` | `string \| Buffer`                | File path or buffer of the reference PDF  |
-| `options`     | `ComparePdfOptions` _(optional)_  | Comparison configuration                  |
+| Parameter     | Type                                        | Description                               |
+| ------------- | ------------------------------------------- | ----------------------------------------- |
+| `actualPdf`   | `string \| Buffer \| ArrayBufferLike`       | File path or buffer of the PDF under test |
+| `expectedPdf` | `string \| Buffer \| ArrayBufferLike`       | File path or buffer of the reference PDF  |
+| `options`     | `ComparePdfOptions` _(optional)_            | Comparison configuration                  |
 
 Returns `Promise<boolean>` — `true` if the PDFs are visually equivalent within the configured threshold, `false` otherwise.
 
@@ -147,14 +147,14 @@ Returns `Promise<boolean>` — `true` if the PDFs are visually equivalent within
 | ------------------------ | --------------------- | -------------------- | --------------------------------------------------------------------------- |
 | `diffsOutputFolder`      | `string`              | `./comparePdfOutput` | Folder where diff PNG images are written                                    |
 | `compareThreshold`       | `number`              | `0`                  | Maximum number of differing pixels allowed before comparison fails          |
-| `excludedAreas`          | `ExcludedPageArea[]`  | `[]`                 | Per-page exclusion zones; array index corresponds to page index (0-based)   |
+| `excludedAreas`          | `ExcludedPageArea[]`  | `[]`                 | Per-page exclusion zones matched by the `pageNumber` field of each entry (1-based) |
 | `pdfToPngConvertOptions` | `PdfToPngOptions`     | see below            | Options forwarded to [`pdf-to-png-converter`](https://github.com/dichovsky/pdf-to-png-converter) |
 
 ### `ExcludedPageArea`
 
 | Property            | Type     | Description                                                                                         |
 | ------------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `pageNumber`        | `number` | Informational page number (matching is performed by array index, not this value)                    |
+| `pageNumber`        | `number` | 1-based page number this exclusion applies to (`1` = first page, `2` = second page, etc.)          |
 | `excludedAreas`     | `Area[]` | Rectangles to exclude. `Area` = `{ x1, y1, x2, y2 }` in pixels at the configured `viewportScale`  |
 | `excludedAreaColor` | `Color`  | Fill color for excluded regions in diff images. `Color` = `{ r, g, b }` with values 0–255          |
 | `diffFilePath`      | `string` | Override the diff image output path for this page                                                   |

package/out/comparePdf.js

@@ -27,50 +27,58 @@ async function comparePdf(actualPdf, expectedPdf, opts = {}) {
     if (!pdfToPngConvertOpts.outputFileMaskFunc) {
         pdfToPngConvertOpts.outputFileMaskFunc = (pageNumber) => `comparePdf_${pageNumber}.png`;
     }
-    const diffsOutputFolder = opts?.diffsOutputFolder ?? const_js_1.DEFAULT_DIFFS_FOLDER;
-    const compareThreshold = opts?.compareThreshold ?? 0;
-    const excludedAreas = opts?.excludedAreas ?? [];
+    const diffsOutputFolder = opts.diffsOutputFolder ?? const_js_1.DEFAULT_DIFFS_FOLDER;
+    const compareThreshold = opts.compareThreshold ?? 0;
+    const excludedAreas = opts.excludedAreas ?? [];
     if (compareThreshold < 0) {
         throw Error('Compare Threshold cannot be less than 0.');
     }
-    // Convert PDFs to PNGs
-    let [actualPdfPngPages, expectedPdfPngPages] = await Promise.all([
-        (0, pdf_to_png_converter_1.pdfToPng)(actualPdf, pdfToPngConvertOpts),
-        (0, pdf_to_png_converter_1.pdfToPng)(expectedPdf, pdfToPngConvertOpts),
-    ]);
-    // Ensure actualPdfPngPages is always the longer array to avoid index out of bounds errors
-    if (actualPdfPngPages.length < expectedPdfPngPages.length) {
-        [actualPdfPngPages, expectedPdfPngPages] = [expectedPdfPngPages, actualPdfPngPages];
-    }
+    // Convert PDFs to PNGs sequentially to avoid PDF.js worker state corruption.
+    // When two pdfToPng calls run concurrently via Promise.all, the pdfDocument.cleanup()
+    // in one call can corrupt the shared PDF.js worker state for the other call, causing
+    // "Invalid page request" errors — particularly when the two PDFs have different page counts.
+    const actualPdfPngPages = await (0, pdf_to_png_converter_1.pdfToPng)(actualPdf, { ...pdfToPngConvertOpts });
+    const expectedPdfPngPages = await (0, pdf_to_png_converter_1.pdfToPng)(expectedPdf, { ...pdfToPngConvertOpts });
     let documentCompareResult = true;
-    actualPdfPngPages.forEach((pngPage, index) => {
+    for (const [index, pngPage] of actualPdfPngPages.entries()) {
+        // Look up the exclusion zone for this page by 1-based page number.
+        const pageExcludedArea = excludedAreas.find((area) => area.pageNumber === index + 1);
+        if (!pngPage.content) {
+            throw new Error(`Page content is undefined for page: ${pngPage.name}`);
+        }
+        // Only forward the fields that ComparePngOptions actually recognises.
+        // The per-page diffFilePath override takes precedence over the auto-generated path.
         const comparePngOpts = {
-            ...opts?.pdfToPngConvertOptions,
-            ...excludedAreas[index],
+            excludedAreas: pageExcludedArea?.excludedAreas,
+            diffFilePath: pageExcludedArea?.diffFilePath ?? (0, node_path_1.resolve)(diffsOutputFolder, `diff_${pngPage.name}`),
             throwErrorOnInvalidInputData: false,
         };
-        comparePngOpts.diffFilePath = (0, node_path_1.resolve)(diffsOutputFolder, `diff_${pngPage.name}`);
         const pngPageOutputToCompareWith = expectedPdfPngPages.find((p) => p.name === pngPage.name);
         const pageCompareResult = (0, png_visual_compare_1.comparePng)(pngPage.content, pngPageOutputToCompareWith?.content ?? '', comparePngOpts);
-        if (pageCompareResult > compareThreshold) {
+        // Per-page matchingThreshold overrides the document-level compareThreshold when set.
+        const pageThreshold = pageExcludedArea?.matchingThreshold ?? compareThreshold;
+        if (pageCompareResult > pageThreshold) {
             documentCompareResult = false;
         }
-    });
+    }
+    // Extra pages present in expected but absent from actual are always a mismatch.
+    if (expectedPdfPngPages.length > actualPdfPngPages.length) {
+        documentCompareResult = false;
+    }
     return documentCompareResult;
 }
 /**
- * Validates the type of the input file. The input file can either be a Buffer or a string representing a file path.
- * If the input file is a Buffer, the function returns without any error.
- * If the input file is a string, the function checks if the file exists at the given path.
- * If the file does not exist, an error is thrown.
- * If the input file is neither a Buffer nor a string, an error is thrown.
+ * Validates the type of the input file.
+ *
+ * Accepts a `Buffer`, any `ArrayBufferLike` (`ArrayBuffer` / `SharedArrayBuffer`), or a
+ * string path that points to an existing file. Throws for any other input.
  *
- * @param inputFile - The input file to validate. It can be a Buffer or a string representing a file path.
- * @throws {Error} If the input file is a string and the file does not exist.
- * @throws {Error} If the input file is neither a Buffer nor a string.
+ * @param inputFile - The input to validate.
+ * @throws {Error} If the input is a string path that does not exist.
+ * @throws {Error} If the input is neither a recognised buffer type nor a string.
  */
 function validateInputFileType(inputFile) {
-    if (Buffer.isBuffer(inputFile)) {
+    if (Buffer.isBuffer(inputFile) || inputFile instanceof ArrayBuffer || inputFile instanceof SharedArrayBuffer) {
         return;
     }
     if (typeof inputFile === 'string') {

package/out/types/ExcludedPageArea.d.ts

@@ -2,13 +2,14 @@ import type { Area, Color } from 'png-visual-compare';
 /**
  * Defines a page-specific exclusion zone for PDF comparison.
  *
- * Elements in the `excludedAreas` array on {@link ComparePdfOptions} are matched to pages
- * by array index (0-based): index 0 targets the first page, index 1 the second, and so on.
+ * Each entry is matched to a PDF page by its `pageNumber` field (1-based):
+ * `pageNumber: 1` targets the first page, `pageNumber: 2` the second, and so on.
+ * Entries whose `pageNumber` does not correspond to any page are silently ignored.
  */
 export type ExcludedPageArea = {
     /**
-     * Informational page number for readability.
-     * Matching is performed by array index, not by this value.
+     * 1-based page number this exclusion applies to.
+     * Must match the page's position in the PDF (`1` = first page, `2` = second page, etc.).
      */
     pageNumber: number;
     /**
@@ -21,16 +22,21 @@ export type ExcludedPageArea = {
     /**
      * Fill color used to paint excluded regions in the diff output image.
      * Expressed as `{ r, g, b }` with channel values in the range 0–255.
+     *
+     * @remarks Currently reserved for future use. The underlying `png-visual-compare`
+     * library always paints excluded areas blue; this field has no effect at runtime.
      */
     excludedAreaColor?: Color;
     /**
      * Override the diff image output file path for this specific page.
-     * When omitted, the path is derived from the document-level `diffsOutputFolder`.
+     * When set, takes precedence over the path derived from `diffsOutputFolder`.
+     * When omitted, the path is auto-generated as `<diffsOutputFolder>/diff_<pageName>`.
      */
     diffFilePath?: string;
     /**
      * Per-page pixel difference threshold that overrides the document-level
-     * `compareThreshold` for this page only.
+     * `compareThreshold` for this page only. Must be >= 0.
+     * When omitted, the document-level `compareThreshold` applies.
      */
     matchingThreshold?: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-visual-compare",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Visual regression testing library for PDFs in Js/Ts without binary and OS dependencies.",
   "keywords": [
     "pdf",
@@ -9,7 +9,9 @@
     "pdf compare",
     "compare pdf",
     "pdf diff",
-    "visual regression"
+    "visual regression",
+    "pdf testing",
+    "visual-diff"
   ],
   "homepage": "https://github.com/dichovsky/pdf-visual-compare#readme",
   "bugs": {
@@ -38,6 +40,7 @@
     "./out"
   ],
   "scripts": {
+    "prepublishOnly": "npm test && npm run build",
     "prebuild": "npm run clean",
     "build": "tsc --pretty",
     "clean": "rimraf ./out ./coverage ./test-results ./comparePdfOutput",
@@ -53,23 +56,21 @@
     "test:license": "npx --yes license-checker --production --onlyAllow \"ISC; MIT; MIT OR X11; BSD; Apache-2.0; Unlicense\""
   },
   "dependencies": {
-    "pdf-to-png-converter": "~3.14.0",
-    "png-visual-compare": "~4.1.0"
+    "pdf-to-png-converter": "~3.18.0",
+    "png-visual-compare": "~5.1.0"
   },
   "devDependencies": {
-    "@types/node": "^25.3.2",
+    "@types/node": "^25.6.0",
     "@types/pngjs": "^6.0.5",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.2",
+    "@vitest/coverage-v8": "^4.1.4",
+    "eslint": "^10.2.0",
     "jiti": "^2.6.1",
     "rimraf": "^6.1.3",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "vitest": "^4.0.18"
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
+    "vitest": "^4.1.4"
   },
   "engines": {
-    "node": ">=20",
-    "yarn": "please-use-npm"
+    "node": ">=20"
   }
 }