pdf-visual-compare 3.4.0 → 4.0.0

package/out/comparePdf.js

@@ -1,85 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.comparePdf = comparePdf;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const pdf_to_png_converter_1 = require("pdf-to-png-converter");
-const png_visual_compare_1 = require("png-visual-compare");
-const const_js_1 = require("./const.js");
-/**
- * Compares two PDF files or buffers and returns a boolean indicating whether they are similar.
- *
- * @param actualPdf - The file path or buffer of the actual PDF to compare.
- * @param expectedPdf - The file path or buffer of the expected PDF to compare against.
- * @param opts - Optional comparison options.
- * @returns A promise that resolves to a boolean indicating whether the PDFs are similar.
- * @throws Will throw an error if the compare threshold is less than 0.
- */
-async function comparePdf(actualPdf, expectedPdf, opts = {}) {
-    // Validate input file types
-    validateInputFileType(actualPdf);
-    validateInputFileType(expectedPdf);
-    // Set default options
-    const pdfToPngConvertOpts = { ...opts.pdfToPngConvertOptions };
-    if (!pdfToPngConvertOpts.viewportScale) {
-        pdfToPngConvertOpts.viewportScale = 2.0;
-    }
-    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 ?? [];
-    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];
-    }
-    let documentCompareResult = true;
-    actualPdfPngPages.forEach((pngPage, index) => {
-        const comparePngOpts = {
-            ...opts?.pdfToPngConvertOptions,
-            ...excludedAreas[index],
-            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) {
-            documentCompareResult = false;
-        }
-    });
-    return documentCompareResult;
+exports.comparePdfDetailed = comparePdfDetailed;
+const comparePlannedPage_js_1 = require("./internal/comparePlannedPage.js");
+const pageComparisonPlan_js_1 = require("./internal/pageComparisonPlan.js");
+const normalizeComparisonOptions_js_1 = require("./internal/normalizeComparisonOptions.js");
+const normalizePdfInput_js_1 = require("./internal/normalizePdfInput.js");
+const renderPdfPages_js_1 = require("./internal/renderPdfPages.js");
+async function comparePdf(actualPdf, expectedPdf, opts) {
+    const result = await comparePdfDetailed(actualPdf, expectedPdf, opts);
+    return result.isEqual;
 }
-/**
- * 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.
- *
- * @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.
- */
-function validateInputFileType(inputFile) {
-    if (Buffer.isBuffer(inputFile)) {
-        return;
+async function comparePdfDetailed(actualPdf, expectedPdf, opts) {
+    const normalizedOptions = (0, normalizeComparisonOptions_js_1.normalizeComparisonOptions)(opts);
+    const normalizedActualPdf = (0, normalizePdfInput_js_1.normalizePdfInput)(actualPdf, 'actualPdf', normalizedOptions.allowedInputRoot);
+    const normalizedExpectedPdf = (0, normalizePdfInput_js_1.normalizePdfInput)(expectedPdf, 'expectedPdf', normalizedOptions.allowedInputRoot);
+    const actualPlanningPages = await (0, renderPdfPages_js_1.listRenderedPageNumbers)(normalizedActualPdf, normalizedOptions.pdfToPngConvertOpts, 'actual');
+    const expectedPlanningPages = await (0, renderPdfPages_js_1.listRenderedPageNumbers)(normalizedExpectedPdf, normalizedOptions.pdfToPngConvertOpts, 'expected');
+    const actualPageNumberSet = new Set(actualPlanningPages.pageNumbers);
+    const expectedPageNumberSet = new Set(expectedPlanningPages.pageNumbers);
+    const comparisonPlan = (0, pageComparisonPlan_js_1.buildPageNumberComparisonPlan)(actualPlanningPages.pageNumbers, expectedPlanningPages.pageNumbers, normalizedOptions.excludedAreas);
+    const pages = [];
+    for (const planEntry of comparisonPlan) {
+        const actualPage = actualPageNumberSet.has(planEntry.pageNumber)
+            ? await resolvePlannedPage(actualPlanningPages.prefetchedPages.get(planEntry.pageNumber), normalizedActualPdf, normalizedOptions.pdfToPngConvertOpts, planEntry.pageNumber, 'actual')
+            : undefined;
+        const expectedPage = expectedPageNumberSet.has(planEntry.pageNumber)
+            ? await resolvePlannedPage(expectedPlanningPages.prefetchedPages.get(planEntry.pageNumber), normalizedExpectedPdf, normalizedOptions.pdfToPngConvertOpts, planEntry.pageNumber, 'expected')
+            : undefined;
+        pages.push((0, comparePlannedPage_js_1.comparePlannedPage)({ ...planEntry, actualPage, expectedPage }, normalizedOptions));
     }
-    if (typeof inputFile === 'string') {
-        if ((0, node_fs_1.existsSync)(inputFile)) {
-            return;
-        }
-        else {
-            throw Error(`PDF file not found: ${inputFile}`);
-        }
+    return {
+        isEqual: pages.every((page) => page.isEqual),
+        actualPageCount: actualPlanningPages.pageNumbers.length,
+        expectedPageCount: expectedPlanningPages.pageNumbers.length,
+        compareThreshold: normalizedOptions.compareThreshold,
+        diffsOutputFolder: normalizedOptions.writeDiffs ? normalizedOptions.diffsOutputFolder : null,
+        pages,
+        writeDiffs: normalizedOptions.writeDiffs,
+    };
+}
+async function resolvePlannedPage(prefetchedPage, pdfInput, pdfToPngConvertOpts, pageNumber, sourceLabel) {
+    if (prefetchedPage && isRenderedPngPageOutput(prefetchedPage)) {
+        return prefetchedPage;
     }
-    throw Error(`Unknown input file type.`);
+    return (0, renderPdfPages_js_1.renderPdfPage)(pdfInput, pdfToPngConvertOpts, pageNumber, sourceLabel);
+}
+function isRenderedPngPageOutput(page) {
+    return page.kind !== 'metadata' && Buffer.isBuffer(page.content);
 }

package/out/const.d.ts

@@ -1,2 +1,2 @@
-/** Default folder path for diff PNG images produced during PDF comparison. */
-export declare const DEFAULT_DIFFS_FOLDER: string;
+/** Resolves the default folder path for diff PNG images produced during PDF comparison. */
+export declare function getDefaultDiffsFolder(): string;

package/out/const.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DIFFS_FOLDER = void 0;
+exports.getDefaultDiffsFolder = getDefaultDiffsFolder;
 const node_path_1 = require("node:path");
-/** Default folder path for diff PNG images produced during PDF comparison. */
-exports.DEFAULT_DIFFS_FOLDER = (0, node_path_1.resolve)(`./comparePdfOutput`);
+/** Resolves the default folder path for diff PNG images produced during PDF comparison. */
+function getDefaultDiffsFolder() {
+    return (0, node_path_1.resolve)('./comparePdfOutput');
+}

package/out/errors/ComparePdfComparisonError.d.ts

@@ -0,0 +1,6 @@
+import { ComparePdfError } from './ComparePdfError.js';
+/**
+ * Thrown when rendered PDF pages cannot be compared reliably.
+ */
+export declare class ComparePdfComparisonError extends ComparePdfError {
+}

package/out/errors/ComparePdfComparisonError.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComparePdfComparisonError = void 0;
+const ComparePdfError_js_1 = require("./ComparePdfError.js");
+/**
+ * Thrown when rendered PDF pages cannot be compared reliably.
+ */
+class ComparePdfComparisonError extends ComparePdfError_js_1.ComparePdfError {
+}
+exports.ComparePdfComparisonError = ComparePdfComparisonError;

package/out/errors/ComparePdfConfigurationError.d.ts

@@ -0,0 +1,6 @@
+import { ComparePdfError } from './ComparePdfError.js';
+/**
+ * Thrown when comparePdf receives invalid runtime configuration values.
+ */
+export declare class ComparePdfConfigurationError extends ComparePdfError {
+}

package/out/errors/ComparePdfConfigurationError.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComparePdfConfigurationError = void 0;
+const ComparePdfError_js_1 = require("./ComparePdfError.js");
+/**
+ * Thrown when comparePdf receives invalid runtime configuration values.
+ */
+class ComparePdfConfigurationError extends ComparePdfError_js_1.ComparePdfError {
+}
+exports.ComparePdfConfigurationError = ComparePdfConfigurationError;

package/out/errors/ComparePdfError.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Base error for all public library exceptions thrown by `comparePdf`.
+ */
+export declare class ComparePdfError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/out/errors/ComparePdfError.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComparePdfError = void 0;
+/**
+ * Base error for all public library exceptions thrown by `comparePdf`.
+ */
+class ComparePdfError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+exports.ComparePdfError = ComparePdfError;

package/out/errors/ComparePdfInputError.d.ts

@@ -0,0 +1,6 @@
+import { ComparePdfError } from './ComparePdfError.js';
+/**
+ * Thrown when comparePdf receives invalid PDF input arguments.
+ */
+export declare class ComparePdfInputError extends ComparePdfError {
+}

package/out/errors/ComparePdfInputError.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComparePdfInputError = void 0;
+const ComparePdfError_js_1 = require("./ComparePdfError.js");
+/**
+ * Thrown when comparePdf receives invalid PDF input arguments.
+ */
+class ComparePdfInputError extends ComparePdfError_js_1.ComparePdfError {
+}
+exports.ComparePdfInputError = ComparePdfInputError;

package/out/errors/ComparePdfRenderingError.d.ts

@@ -0,0 +1,6 @@
+import { ComparePdfError } from './ComparePdfError.js';
+/**
+ * Thrown when PDF rendering fails before visual comparison can start.
+ */
+export declare class ComparePdfRenderingError extends ComparePdfError {
+}

package/out/errors/ComparePdfRenderingError.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComparePdfRenderingError = void 0;
+const ComparePdfError_js_1 = require("./ComparePdfError.js");
+/**
+ * Thrown when PDF rendering fails before visual comparison can start.
+ */
+class ComparePdfRenderingError extends ComparePdfError_js_1.ComparePdfError {
+}
+exports.ComparePdfRenderingError = ComparePdfRenderingError;

package/out/index.d.ts

@@ -3,10 +3,24 @@
  *
  * Visual regression testing library for PDFs in JavaScript/TypeScript.
  * Converts PDF pages to PNG images and performs pixel-level comparison,
- * requiring no native binaries or OS-level dependencies.
+ * without requiring external system packages. The current renderer uses
+ * prebuilt native `@napi-rs/canvas` binaries bundled through its dependency tree.
  *
  * @module pdf-visual-compare
  */
-export { comparePdf } from './comparePdf.js';
+export { comparePdf, comparePdfDetailed } from './comparePdf.js';
+export { ComparePdfComparisonError } from './errors/ComparePdfComparisonError.js';
+export { ComparePdfConfigurationError } from './errors/ComparePdfConfigurationError.js';
+export { ComparePdfError } from './errors/ComparePdfError.js';
+export { ComparePdfInputError } from './errors/ComparePdfInputError.js';
+export { ComparePdfRenderingError } from './errors/ComparePdfRenderingError.js';
 export type { ComparePdfOptions } from './types/ComparePdfOptions.js';
+export type { ComparePdfDetailedResult } from './types/ComparePdfDetailedResult.js';
+export type { ComparePdfPageResult } from './types/ComparePdfPageResult.js';
+export type { ComparePdfPageStatus } from './types/ComparePdfPageStatus.js';
 export type { ExcludedPageArea } from './types/ExcludedPageArea.js';
+export type { PageArea } from './types/PageArea.js';
+export type { PageExclusion } from './types/PageExclusion.js';
+export type { PdfInput } from './types/PdfInput.js';
+export type { PdfRenderOptions } from './types/PdfRenderOptions.js';
+export type { RgbColor } from './types/RgbColor.js';

package/out/index.js

@@ -1,14 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.comparePdf = void 0;
+exports.ComparePdfRenderingError = exports.ComparePdfInputError = exports.ComparePdfError = exports.ComparePdfConfigurationError = exports.ComparePdfComparisonError = exports.comparePdfDetailed = exports.comparePdf = void 0;
 /**
  * pdf-visual-compare
  *
  * Visual regression testing library for PDFs in JavaScript/TypeScript.
  * Converts PDF pages to PNG images and performs pixel-level comparison,
- * requiring no native binaries or OS-level dependencies.
+ * without requiring external system packages. The current renderer uses
+ * prebuilt native `@napi-rs/canvas` binaries bundled through its dependency tree.
  *
  * @module pdf-visual-compare
  */
 var comparePdf_js_1 = require("./comparePdf.js");
 Object.defineProperty(exports, "comparePdf", { enumerable: true, get: function () { return comparePdf_js_1.comparePdf; } });
+Object.defineProperty(exports, "comparePdfDetailed", { enumerable: true, get: function () { return comparePdf_js_1.comparePdfDetailed; } });
+var ComparePdfComparisonError_js_1 = require("./errors/ComparePdfComparisonError.js");
+Object.defineProperty(exports, "ComparePdfComparisonError", { enumerable: true, get: function () { return ComparePdfComparisonError_js_1.ComparePdfComparisonError; } });
+var ComparePdfConfigurationError_js_1 = require("./errors/ComparePdfConfigurationError.js");
+Object.defineProperty(exports, "ComparePdfConfigurationError", { enumerable: true, get: function () { return ComparePdfConfigurationError_js_1.ComparePdfConfigurationError; } });
+var ComparePdfError_js_1 = require("./errors/ComparePdfError.js");
+Object.defineProperty(exports, "ComparePdfError", { enumerable: true, get: function () { return ComparePdfError_js_1.ComparePdfError; } });
+var ComparePdfInputError_js_1 = require("./errors/ComparePdfInputError.js");
+Object.defineProperty(exports, "ComparePdfInputError", { enumerable: true, get: function () { return ComparePdfInputError_js_1.ComparePdfInputError; } });
+var ComparePdfRenderingError_js_1 = require("./errors/ComparePdfRenderingError.js");
+Object.defineProperty(exports, "ComparePdfRenderingError", { enumerable: true, get: function () { return ComparePdfRenderingError_js_1.ComparePdfRenderingError; } });

package/out/internal/adapters/comparePngOptions.d.ts

@@ -0,0 +1,3 @@
+import type { ComparePngOptions } from 'png-visual-compare';
+import type { PageExclusion } from '../../types/PageExclusion.js';
+export declare function toComparePngOptions(pageExclusion: PageExclusion | undefined, diffsOutputFolder: string, pageName: string, writeDiffs?: boolean): ComparePngOptions;

package/out/internal/adapters/comparePngOptions.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toComparePngOptions = toComparePngOptions;
+const node_path_1 = require("node:path");
+const ComparePdfConfigurationError_js_1 = require("../../errors/ComparePdfConfigurationError.js");
+function toComparePngOptions(pageExclusion, diffsOutputFolder, pageName, writeDiffs = true) {
+    const diffFilePath = writeDiffs
+        ? resolveDiffFilePath(pageExclusion?.diffFilePath, diffsOutputFolder, pageName)
+        : undefined;
+    return {
+        excludedAreas: pageExclusion?.excludedAreas?.map((area) => ({ ...area })),
+        excludedAreaColor: pageExclusion?.excludedAreaColor && { ...pageExclusion.excludedAreaColor },
+        diffFilePath,
+        throwErrorOnInvalidInputData: true,
+    };
+}
+function resolveDiffFilePath(configuredDiffFilePath, diffsOutputFolder, pageName) {
+    if (configuredDiffFilePath !== undefined) {
+        if (typeof configuredDiffFilePath !== 'string' || configuredDiffFilePath.trim() === '') {
+            throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('diffFilePath must be a non-empty string.');
+        }
+        return assertPathWithinDiffsOutputFolder(configuredDiffFilePath, diffsOutputFolder);
+    }
+    assertSafePageName(pageName, diffsOutputFolder);
+    return assertPathWithinDiffsOutputFolder((0, node_path_1.resolve)(diffsOutputFolder, `diff_${pageName}`), diffsOutputFolder);
+}
+function assertSafePageName(pageName, diffsOutputFolder) {
+    if (pageName.trim() !== '' && pageName === (0, node_path_1.basename)(pageName)) {
+        return;
+    }
+    throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output path must stay within diffsOutputFolder: ${(0, node_path_1.resolve)(diffsOutputFolder)}`);
+}
+function assertPathWithinDiffsOutputFolder(candidatePath, diffsOutputFolder) {
+    const resolvedDiffsOutputFolder = (0, node_path_1.resolve)(diffsOutputFolder);
+    const resolvedCandidatePath = (0, node_path_1.resolve)(candidatePath);
+    const relativePath = (0, node_path_1.relative)(resolvedDiffsOutputFolder, resolvedCandidatePath);
+    if (relativePath === '' || (!relativePath.startsWith('..') && !(0, node_path_1.isAbsolute)(relativePath))) {
+        return resolvedCandidatePath;
+    }
+    throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output path must stay within diffsOutputFolder: ${resolvedDiffsOutputFolder}`);
+}

package/out/internal/adapters/pdfRenderOptions.d.ts

@@ -0,0 +1,3 @@
+import type { PdfToPngOptions } from 'pdf-to-png-converter';
+import type { PdfRenderOptions } from '../../types/PdfRenderOptions.js';
+export declare function toPdfToPngOptions(options: PdfRenderOptions | undefined): PdfToPngOptions;

package/out/internal/adapters/pdfRenderOptions.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPdfToPngOptions = toPdfToPngOptions;
+function toPdfToPngOptions(options) {
+    return {
+        viewportScale: options?.viewportScale,
+        disableFontFace: options?.disableFontFace,
+        useSystemFonts: options?.useSystemFonts,
+        enableXfa: options?.enableXfa,
+        pdfFilePassword: options?.pdfFilePassword,
+        outputFolder: options?.outputFolder,
+        outputFileMaskFunc: options?.outputFileMaskFunc,
+        pagesToProcess: options?.pagesToProcess,
+        verbosityLevel: options?.verbosityLevel,
+        returnPageContent: true,
+        returnMetadataOnly: false,
+        processPagesInParallel: false,
+    };
+}

package/out/internal/comparePlannedPage.d.ts

@@ -0,0 +1,3 @@
+import type { ComparePdfPageResult } from '../types/ComparePdfPageResult.js';
+import type { NormalizedComparePdfOptions, PageComparisonPlanEntry } from './types.js';
+export declare function comparePlannedPage(planEntry: PageComparisonPlanEntry, normalizedOptions: NormalizedComparePdfOptions): ComparePdfPageResult;

package/out/internal/comparePlannedPage.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.comparePlannedPage = comparePlannedPage;
+const png_visual_compare_1 = require("png-visual-compare");
+const ComparePdfComparisonError_js_1 = require("../errors/ComparePdfComparisonError.js");
+const comparePngOptions_js_1 = require("./adapters/comparePngOptions.js");
+const diffOutputGuards_js_1 = require("./diffOutputGuards.js");
+function comparePlannedPage(planEntry, normalizedOptions) {
+    const threshold = planEntry.pageExclusion?.matchingThreshold ?? normalizedOptions.compareThreshold;
+    const actualPageName = planEntry.actualPage?.name ?? null;
+    const expectedPageName = planEntry.expectedPage?.name ?? null;
+    if (!planEntry.actualPage || !planEntry.expectedPage) {
+        return {
+            pageNumber: planEntry.pageNumber,
+            status: planEntry.actualPage ? 'missing-expected' : 'missing-actual',
+            isEqual: false,
+            threshold,
+            mismatchCount: null,
+            diffFilePath: null,
+            actualPageName,
+            expectedPageName,
+        };
+    }
+    const resolvedComparePngOptions = (0, comparePngOptions_js_1.toComparePngOptions)(planEntry.pageExclusion, normalizedOptions.diffsOutputFolder, planEntry.actualPage.name, normalizedOptions.writeDiffs);
+    const diffFilePath = resolvedComparePngOptions.diffFilePath ?? null;
+    let stagedTempfilePath;
+    let scopedComparePngOptions = resolvedComparePngOptions;
+    if (diffFilePath) {
+        (0, diffOutputGuards_js_1.assertDiffOutputPathUsesRealFilesystemEntries)(diffFilePath, normalizedOptions.diffsOutputFolder);
+        (0, diffOutputGuards_js_1.ensureDiffOutputDirectory)(diffFilePath, normalizedOptions.diffsOutputFolder);
+        (0, diffOutputGuards_js_1.assertDiffOutputPathUsesRealFilesystemEntries)(diffFilePath, normalizedOptions.diffsOutputFolder);
+        (0, diffOutputGuards_js_1.assertCanonicalDiffOutputPath)(diffFilePath, normalizedOptions.diffsOutputFolder);
+        // Stage the comparator's write at a securely-created random-named tempfile in the
+        // same directory, then atomically rename into diffFilePath afterwards. rename()
+        // replaces any symlink planted at diffFilePath during the write window without
+        // following it, which is the only way to actually prevent — not just detect — a
+        // redirected write when the comparator's API takes a path rather than an fd
+        // (CWE-61 / CWE-367).
+        stagedTempfilePath = (0, diffOutputGuards_js_1.createSecureDiffOutputTempfile)(diffFilePath, normalizedOptions.diffsOutputFolder);
+        scopedComparePngOptions = { ...resolvedComparePngOptions, diffFilePath: stagedTempfilePath };
+    }
+    let mismatchCount;
+    try {
+        mismatchCount = (0, png_visual_compare_1.comparePng)(planEntry.actualPage.content, planEntry.expectedPage.content, scopedComparePngOptions);
+    }
+    catch (cause) {
+        // Roll back the staged tempfile so a zero-byte file does not leak into the diffs
+        // folder on the comparator's error path (would otherwise confuse CI artifacts).
+        if (stagedTempfilePath) {
+            (0, diffOutputGuards_js_1.discardDiffOutputLeaf)(stagedTempfilePath);
+        }
+        throw new ComparePdfComparisonError_js_1.ComparePdfComparisonError(`Failed to compare rendered PDF page ${planEntry.pageNumber}.`, {
+            cause,
+        });
+    }
+    if (stagedTempfilePath && diffFilePath) {
+        (0, diffOutputGuards_js_1.publishDiffOutputTempfile)(stagedTempfilePath, diffFilePath, normalizedOptions.diffsOutputFolder, {
+            expectDiffWritten: mismatchCount > threshold,
+        });
+    }
+    const isEqual = mismatchCount <= threshold;
+    return {
+        pageNumber: planEntry.pageNumber,
+        status: isEqual ? 'matched' : 'mismatched',
+        isEqual,
+        threshold,
+        mismatchCount,
+        diffFilePath,
+        actualPageName,
+        expectedPageName,
+    };
+}

package/out/internal/diffOutputGuards.d.ts

@@ -0,0 +1,56 @@
+import type { ComparePdfOptions } from '../types/ComparePdfOptions.js';
+export declare function validateDiffsOutputFolder(diffsOutputFolder: ComparePdfOptions['diffsOutputFolder']): string;
+export declare function ensureDiffOutputDirectory(outputPath: string, diffsOutputFolder: string): void;
+export declare function assertDiffOutputPathUsesRealFilesystemEntries(diffFilePath: string, diffsOutputFolder: string): void;
+/**
+ * Atomically creates a fresh, randomly-named tempfile in the same directory as the diff leaf
+ * and returns its path. The third-party comparator is then directed at this tempfile, and the
+ * result is later promoted into `diffFilePath` via {@link publishDiffOutputTempfile}.
+ *
+ * This two-step "stage then rename" pattern is materially stronger than writing directly to
+ * `diffFilePath`:
+ * - The tempfile name carries an unpredictable random suffix, so an attacker with write
+ *   access in `diffsOutputFolder` cannot pre-plant a symlink at the future tempfile path.
+ * - The tempfile is opened with `O_CREAT | O_EXCL | O_NOFOLLOW`, so any racing attempt to
+ *   pre-create a regular file or symlink at the same path during the open is rejected
+ *   (CWE-61 / CWE-367).
+ * - The eventual atomic `renameSync` (see {@link publishDiffOutputTempfile}) replaces any
+ *   pre-existing entry at `diffFilePath` — including a symlink planted there during the
+ *   write window — without ever following the destination's symlink.
+ */
+export declare function createSecureDiffOutputTempfile(diffFilePath: string, diffsOutputFolder: string): string;
+export type PublishDiffOutputTempfileOptions = {
+    /**
+     * `true` when the comparator was expected to produce a diff PNG (mismatched pages above
+     * threshold). A missing or empty tempfile in that case becomes a
+     * `ComparePdfConfigurationError` because the diff bytes must already be on disk; their
+     * absence implies attacker deletion, a symlink-redirected write, or a silent comparator
+     * failure that callers must surface.
+     *
+     * `false` when the comparator was expected to skip writing (matching pages). Missing or
+     * empty tempfile is then the normal "no diff to report" case; any stale leaf at the final
+     * path is removed so on-disk state matches the pre-fix behavior.
+     */
+    expectDiffWritten: boolean;
+};
+/**
+ * Promotes the staged tempfile to `diffFilePath` via atomic `renameSync`. This is the
+ * core anti-TOCTOU primitive: `rename()` replaces any pre-existing file or symlink at
+ * the destination as a single directory-entry operation without ever following the
+ * destination. A symlink planted at `diffFilePath` during the write window is therefore
+ * harmlessly overwritten — the attacker's chosen target is never opened by this library.
+ *
+ * Throws `ComparePdfConfigurationError` when:
+ * - the tempfile is no longer a regular file (symlink swap during the comparator's write
+ *   — bytes may have leaked through the swapped symlink to an attacker-chosen target);
+ * - a diff was expected but the tempfile is missing or zero bytes;
+ * - the tempfile cannot be inspected, or rename fails for reasons other than absence.
+ */
+export declare function publishDiffOutputTempfile(tempfilePath: string, diffFilePath: string, diffsOutputFolder: string, options: PublishDiffOutputTempfileOptions): void;
+/**
+ * Best-effort removal of a diff output file. Callers use this to roll back the staged
+ * tempfile when the third-party comparator throws before writing, and to clear stale
+ * leaves at the published path when no diff was produced for matching pages.
+ */
+export declare function discardDiffOutputLeaf(diffFilePath: string): void;
+export declare function assertCanonicalDiffOutputPath(diffFilePath: string, diffsOutputFolder: string): void;