pdf-visual-compare 3.4.0 → 4.0.0

package/out/internal/renderPdfPages.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listRenderedPageNumbers = listRenderedPageNumbers;
+exports.renderPdfPages = renderPdfPages;
+exports.renderPdfPage = renderPdfPage;
+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 ComparePdfConfigurationError_js_1 = require("../errors/ComparePdfConfigurationError.js");
+const ComparePdfRenderingError_js_1 = require("../errors/ComparePdfRenderingError.js");
+const securePath_js_1 = require("./securePath.js");
+async function listRenderedPageNumbers(pdfFile, pdfToPngConvertOpts, sourceLabel) {
+    const metadataPages = await runPdfToPng(pdfFile, {
+        ...pdfToPngConvertOpts,
+        returnMetadataOnly: true,
+        returnPageContent: false,
+    }, sourceLabel);
+    return {
+        pageNumbers: metadataPages.map((page) => page.pageNumber),
+        prefetchedPages: new Map(metadataPages.map((page) => [page.pageNumber, page])),
+    };
+}
+async function renderPdfPages(pdfFile, pdfToPngConvertOpts, sourceLabel) {
+    const renderedPages = await runPdfToPng(pdfFile, pdfToPngConvertOpts, sourceLabel);
+    const missingContentPage = renderedPages.find((page) => !Buffer.isBuffer(page.content));
+    if (missingContentPage) {
+        throw new ComparePdfRenderingError_js_1.ComparePdfRenderingError(`Rendered page content is missing for page: ${missingContentPage.name}.`);
+    }
+    return renderedPages;
+}
+async function renderPdfPage(pdfFile, pdfToPngConvertOpts, pageNumber, sourceLabel) {
+    clearStaleRenderTarget(pdfToPngConvertOpts, pageNumber, sourceLabel);
+    const renderedPages = await renderPdfPages(pdfFile, {
+        ...pdfToPngConvertOpts,
+        pagesToProcess: [pageNumber],
+    }, sourceLabel);
+    return renderedPages[0];
+}
+/**
+ * Removes the exact PNG file this page render is about to (re)create when an
+ * `outputFolder` is configured. The renderer opens output files with exclusive-create
+ * (`'wx'`) and refuses to overwrite, so a prior run's PNG at the same name would otherwise
+ * make re-rendering fail with `EEXIST`. This performs the "clear the output name before
+ * re-running the same conversion" step the renderer documents for callers, scoped to the
+ * single file the library owns and is regenerating.
+ *
+ * The removal is constrained to the library-owned render namespace: the resolved target must
+ * stay inside `<outputFolder>/<sourceLabel>`. A mask that escapes that directory is left
+ * untouched, so the renderer's own containment check (`savePNGfile`) remains the single
+ * source of truth for rejecting it. `force: true` ignores a missing file and unlinks a leaf
+ * symlink without following it. A caller-supplied `outputFileMaskFunc` that throws, and any
+ * other filesystem failure (for example a non-writable folder, or a directory occupying the
+ * target name), are surfaced as the library's typed `ComparePdfConfigurationError` rather than
+ * leaking a raw error out of the public surface.
+ */
+function clearStaleRenderTarget(pdfToPngConvertOpts, pageNumber, sourceLabel) {
+    const { outputFolder, outputFileMaskFunc } = pdfToPngConvertOpts;
+    if (!outputFolder || !outputFileMaskFunc) {
+        return;
+    }
+    let maskedFileName;
+    try {
+        maskedFileName = outputFileMaskFunc(pageNumber);
+    }
+    catch (cause) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`pdfToPngConvertOptions.outputFileMaskFunc threw while resolving the output file name for page ${pageNumber}.`, { cause });
+    }
+    const renderNamespace = (0, node_path_1.resolve)(outputFolder, sourceLabel);
+    const targetPath = (0, node_path_1.resolve)(renderNamespace, maskedFileName);
+    if (!(0, securePath_js_1.isPathWithinRoot)(targetPath, renderNamespace)) {
+        return;
+    }
+    try {
+        (0, node_fs_1.rmSync)(targetPath, { force: true });
+    }
+    catch (cause) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`pdfToPngConvertOptions.outputFolder must point to a writable directory: ${outputFolder}`, { cause });
+    }
+}
+function toRenderablePdfInput(pdfFile) {
+    if (typeof pdfFile === 'string' || Buffer.isBuffer(pdfFile)) {
+        return pdfFile;
+    }
+    return Uint8Array.from(new Uint8Array(pdfFile)).buffer;
+}
+async function runPdfToPng(pdfFile, pdfToPngConvertOpts, sourceLabel) {
+    try {
+        const renderedPages = await (0, pdf_to_png_converter_1.pdfToPng)(toRenderablePdfInput(pdfFile), {
+            ...pdfToPngConvertOpts,
+            outputFolder: pdfToPngConvertOpts.outputFolder
+                ? (0, node_path_1.join)(pdfToPngConvertOpts.outputFolder, sourceLabel)
+                : undefined,
+        });
+        if (!Array.isArray(renderedPages)) {
+            throw new ComparePdfRenderingError_js_1.ComparePdfRenderingError(`Failed to render ${sourceLabel} PDF pages.`);
+        }
+        return renderedPages;
+    }
+    catch (cause) {
+        if (cause instanceof ComparePdfRenderingError_js_1.ComparePdfRenderingError) {
+            throw cause;
+        }
+        throw new ComparePdfRenderingError_js_1.ComparePdfRenderingError(`Failed to render ${sourceLabel} PDF pages.`, { cause });
+    }
+}

package/out/internal/securePath.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared path-containment and symlink-rejection primitives used by every code path that
+ * lets a caller name a filesystem location. Two adapters were drifting before this seam
+ * existed (`src/internal/normalizePdfInput.ts` for `allowedInputRoot` and
+ * `src/internal/diffOutputGuards.ts` for `diffsOutputFolder`), and a third caller has
+ * since landed for `pdfToPngConvertOptions.outputFolder`. Centralizing the symlink-swap
+ * defense here keeps the CWE-59 / CWE-61 fix in one place.
+ */
+/**
+ * Returns `true` when `pathToCheck` is `rootPath` itself or a descendant of it. The
+ * comparison is purely lexical and operates on already-resolved absolute paths — callers
+ * resolve and (when relevant) canonicalize before calling.
+ */
+export declare function isPathWithinRoot(pathToCheck: string, rootPath: string): boolean;
+/**
+ * Reports whether a filesystem entry exists at `pathToCheck` without following symbolic
+ * links. Returning `true` does not imply the entry is a regular file or directory —
+ * callers must inspect the lstat result separately.
+ */
+export declare function pathExistsWithoutFollowingSymlinks(pathToCheck: string): boolean;
+/**
+ * Throws `ComparePdfConfigurationError` when `pathToCheck` itself is a symbolic link.
+ * The path must already exist — callers are expected to have established existence via
+ * {@link pathExistsWithoutFollowingSymlinks}.
+ */
+export declare function assertPathIsNotSymbolicLink(pathToCheck: string, errorMessage: string): void;
+/**
+ * Walks from `pathToCheck` up to the filesystem root and throws
+ * `ComparePdfConfigurationError` if any existing ancestor (or `pathToCheck` itself) is a
+ * symbolic link. Non-existent ancestors are skipped because they cannot redirect a write
+ * before they are created — and the leaf-creation paths in each caller separately defend
+ * against symlink swaps at creation time.
+ */
+export declare function assertPathAndAncestorsAreNotSymbolicLinks(pathToCheck: string, errorMessage: string): void;

package/out/internal/securePath.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPathWithinRoot = isPathWithinRoot;
+exports.pathExistsWithoutFollowingSymlinks = pathExistsWithoutFollowingSymlinks;
+exports.assertPathIsNotSymbolicLink = assertPathIsNotSymbolicLink;
+exports.assertPathAndAncestorsAreNotSymbolicLinks = assertPathAndAncestorsAreNotSymbolicLinks;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ComparePdfConfigurationError_js_1 = require("../errors/ComparePdfConfigurationError.js");
+/**
+ * Shared path-containment and symlink-rejection primitives used by every code path that
+ * lets a caller name a filesystem location. Two adapters were drifting before this seam
+ * existed (`src/internal/normalizePdfInput.ts` for `allowedInputRoot` and
+ * `src/internal/diffOutputGuards.ts` for `diffsOutputFolder`), and a third caller has
+ * since landed for `pdfToPngConvertOptions.outputFolder`. Centralizing the symlink-swap
+ * defense here keeps the CWE-59 / CWE-61 fix in one place.
+ */
+/**
+ * Returns `true` when `pathToCheck` is `rootPath` itself or a descendant of it. The
+ * comparison is purely lexical and operates on already-resolved absolute paths — callers
+ * resolve and (when relevant) canonicalize before calling.
+ */
+function isPathWithinRoot(pathToCheck, rootPath) {
+    const relativePath = (0, node_path_1.relative)(rootPath, pathToCheck);
+    return relativePath === '' || (!relativePath.startsWith('..') && !(0, node_path_1.isAbsolute)(relativePath));
+}
+/**
+ * Reports whether a filesystem entry exists at `pathToCheck` without following symbolic
+ * links. Returning `true` does not imply the entry is a regular file or directory —
+ * callers must inspect the lstat result separately.
+ */
+function pathExistsWithoutFollowingSymlinks(pathToCheck) {
+    try {
+        (0, node_fs_1.lstatSync)(pathToCheck);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Throws `ComparePdfConfigurationError` when `pathToCheck` itself is a symbolic link.
+ * The path must already exist — callers are expected to have established existence via
+ * {@link pathExistsWithoutFollowingSymlinks}.
+ */
+function assertPathIsNotSymbolicLink(pathToCheck, errorMessage) {
+    if (!(0, node_fs_1.lstatSync)(pathToCheck).isSymbolicLink()) {
+        return;
+    }
+    throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(errorMessage);
+}
+/**
+ * Walks from `pathToCheck` up to the filesystem root and throws
+ * `ComparePdfConfigurationError` if any existing ancestor (or `pathToCheck` itself) is a
+ * symbolic link. Non-existent ancestors are skipped because they cannot redirect a write
+ * before they are created — and the leaf-creation paths in each caller separately defend
+ * against symlink swaps at creation time.
+ */
+function assertPathAndAncestorsAreNotSymbolicLinks(pathToCheck, errorMessage) {
+    const existingAncestorPaths = [];
+    let currentPath = (0, node_path_1.resolve)(pathToCheck);
+    while (true) {
+        if (pathExistsWithoutFollowingSymlinks(currentPath)) {
+            existingAncestorPaths.push(currentPath);
+        }
+        const parentPath = (0, node_path_1.dirname)(currentPath);
+        if (parentPath === currentPath) {
+            break;
+        }
+        currentPath = parentPath;
+    }
+    for (const existingPath of existingAncestorPaths.reverse()) {
+        assertPathIsNotSymbolicLink(existingPath, errorMessage);
+    }
+}

package/out/internal/types.d.ts

@@ -0,0 +1,26 @@
+import type { PdfToPngOptions, PngPageOutput } from 'pdf-to-png-converter';
+import type { PageExclusion } from '../types/PageExclusion.js';
+export type RenderedPngPageOutput = Extract<PngPageOutput, {
+    kind: 'content' | 'file';
+}> & {
+    content: Buffer;
+};
+export type AllowedInputRoot = {
+    displayPath: string;
+    resolvedPath: string;
+    canonicalPath: string;
+};
+export type PageComparisonPlanEntry = {
+    pageNumber: number;
+    actualPage?: RenderedPngPageOutput;
+    expectedPage?: RenderedPngPageOutput;
+    pageExclusion?: PageExclusion;
+};
+export type NormalizedComparePdfOptions = {
+    allowedInputRoot?: AllowedInputRoot;
+    compareThreshold: number;
+    diffsOutputFolder: string;
+    excludedAreas: readonly PageExclusion[];
+    pdfToPngConvertOpts: PdfToPngOptions;
+    writeDiffs: boolean;
+};

package/out/internal/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/ComparePdfDetailedResult.d.ts

@@ -0,0 +1,35 @@
+import type { ComparePdfPageResult } from './ComparePdfPageResult.js';
+/**
+ * Structured document-level comparison result returned by `comparePdfDetailed()`.
+ */
+export type ComparePdfDetailedResult = {
+    /**
+     * `true` when every planned page comparison stays within its applicable threshold.
+     */
+    isEqual: boolean;
+    /**
+     * Number of rendered pages produced from the actual PDF input.
+     */
+    actualPageCount: number;
+    /**
+     * Number of rendered pages produced from the expected PDF input.
+     */
+    expectedPageCount: number;
+    /**
+     * Document-level threshold supplied to the comparison.
+     */
+    compareThreshold: number;
+    /**
+     * `true` when diff PNG files were written for compared pages.
+     */
+    writeDiffs: boolean;
+    /**
+     * Base diff output folder used when a page does not provide a custom diff path.
+     * `null` when diff writing was disabled.
+     */
+    diffsOutputFolder: string | null;
+    /**
+     * Page-level results sorted by `pageNumber`.
+     */
+    pages: ComparePdfPageResult[];
+};

package/out/types/ComparePdfDetailedResult.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/ComparePdfOptions.d.ts

@@ -1,30 +1,52 @@
-import type { PdfToPngOptions } from 'pdf-to-png-converter';
-import type { ExcludedPageArea } from './ExcludedPageArea.js';
+import type { PageExclusion } from './PageExclusion.js';
+import type { PdfRenderOptions } from './PdfRenderOptions.js';
 /**
  * Options for configuring the PDF comparison process.
  */
 export type ComparePdfOptions = {
     /**
-     * Folder path where diff PNG images are written when differences are found.
+     * When `true`, writes diff PNG images to disk.
+     * When omitted or `false`, comparison stays in memory and no diff files are produced.
+     * @default false
+     */
+    writeDiffs?: boolean;
+    /**
+     * Folder path that defines the allowed root for diff PNG images written when differences are found.
+     * Auto-generated diff paths and any per-page `diffFilePath` overrides must stay within this root.
+     * Callers should treat this as a trusted filesystem write location on a trusted local filesystem.
+     * If provided, it is validated even when `writeDiffs` is `false`; diff files are only written
+     * when `writeDiffs` is `true`.
      * @default "./comparePdfOutput"
      */
     diffsOutputFolder?: string;
     /**
-     * Options passed to the underlying PDF-to-PNG converter.
-     * Controls rendering scale, font handling, page selection, and more.
+     * Optional workspace root that constrains string PDF inputs.
+     *
+     * When set, `actualPdf` and `expectedPdf` string paths must resolve within this directory
+     * or `comparePdf()` throws a `ComparePdfConfigurationError`.
+     *
+     * When omitted, string paths are treated as trusted caller-controlled local file paths.
+     * Binary inputs (`Buffer`, `ArrayBuffer`, `SharedArrayBuffer`) are not affected.
+     */
+    allowedInputRoot?: string;
+    /**
+     * Options for rendering PDF pages before comparison.
      */
-    pdfToPngConvertOptions?: PdfToPngOptions;
+    pdfToPngConvertOptions?: PdfRenderOptions;
     /**
-     * Per-page areas to exclude from pixel comparison, matched by array index (0-based).
-     * The element at index 0 applies to the first page, index 1 to the second, and so on.
+     * Per-page areas to exclude from pixel comparison, matched by the rendered page's
+     * `pageNumber` field (1-based).
+     *
+     * Entries for pages that were not rendered are ignored. If multiple entries target the
+     * same `pageNumber`, the first entry wins and later duplicates are ignored.
      * @default []
      */
-    excludedAreas?: readonly ExcludedPageArea[];
+    excludedAreas?: readonly PageExclusion[];
     /**
      * Maximum number of differing pixels allowed before the comparison is considered a failure.
-     * A value of `0` requires a pixel-perfect match. Must be >= 0.
+     * A value of `0` requires a pixel-perfect match. Must be a finite non-negative integer.
      * @default 0
-     * @throws {Error} When set to a value less than 0.
+     * @throws {ComparePdfConfigurationError} When set to a negative, fractional, infinite, or `NaN` value.
      */
     compareThreshold?: number;
 };

package/out/types/ComparePdfPageResult.d.ts

@@ -0,0 +1,42 @@
+import type { ComparePdfPageStatus } from './ComparePdfPageStatus.js';
+/**
+ * Page-level comparison outcome reported by `comparePdfDetailed()`.
+ */
+export type ComparePdfPageResult = {
+    /**
+     * 1-based rendered page number used for planning and comparison.
+     */
+    pageNumber: number;
+    /**
+     * Final page outcome.
+     */
+    status: ComparePdfPageStatus;
+    /**
+     * `true` when this page is within its applicable threshold.
+     */
+    isEqual: boolean;
+    /**
+     * Threshold applied to this page after combining the document-level threshold with any
+     * page-specific override.
+     */
+    threshold: number;
+    /**
+     * Pixel mismatch count returned by the PNG comparator.
+     * `null` means the page was not compared because one rendered counterpart was missing.
+     */
+    mismatchCount: number | null;
+    /**
+     * Diff PNG output path chosen for this page comparison.
+     * `null` means no page comparison ran because one rendered counterpart was missing,
+     * or diff writing was disabled.
+     */
+    diffFilePath: string | null;
+    /**
+     * Renderer-reported actual page image name, when the actual PDF produced this page.
+     */
+    actualPageName: string | null;
+    /**
+     * Renderer-reported expected page image name, when the expected PDF produced this page.
+     */
+    expectedPageName: string | null;
+};

package/out/types/ComparePdfPageResult.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/ComparePdfPageStatus.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Page-level outcome reported by `comparePdfDetailed()`.
+ */
+export type ComparePdfPageStatus = 'matched' | 'mismatched' | 'missing-actual' | 'missing-expected';

package/out/types/ComparePdfPageStatus.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/ExcludedPageArea.d.ts

@@ -1,36 +1,6 @@
-import type { Area, Color } from 'png-visual-compare';
 /**
- * Defines a page-specific exclusion zone for PDF comparison.
+ * Backwards-compatible alias of {@link PageExclusion}.
  *
- * 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.
+ * Exclusions are matched by rendered `pageNumber` (1-based), not by array position.
  */
-export type ExcludedPageArea = {
-    /**
-     * Informational page number for readability.
-     * Matching is performed by array index, not by this value.
-     */
-    pageNumber: number;
-    /**
-     * Rectangular regions to exclude from pixel comparison on this page.
-     * Coordinates (`x1`, `y1`, `x2`, `y2`) are in pixels relative to the rendered PNG
-     * at the configured `viewportScale`. `(x1, y1)` is the top-left corner and
-     * `(x2, y2)` is the bottom-right corner.
-     */
-    excludedAreas?: Area[];
-    /**
-     * 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.
-     */
-    excludedAreaColor?: Color;
-    /**
-     * Override the diff image output file path for this specific page.
-     * When omitted, the path is derived from the document-level `diffsOutputFolder`.
-     */
-    diffFilePath?: string;
-    /**
-     * Per-page pixel difference threshold that overrides the document-level
-     * `compareThreshold` for this page only.
-     */
-    matchingThreshold?: number;
-};
+export type { PageExclusion as ExcludedPageArea } from './PageExclusion.js';

package/out/types/PageArea.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Defines a rectangular region on a rendered PDF page by its pixel coordinates.
+ */
+export type PageArea = {
+    /** X coordinate of the left edge (pixels from left). */
+    x1: number;
+    /** Y coordinate of the top edge (pixels from top). */
+    y1: number;
+    /** X coordinate of the right edge (pixels from left, inclusive). */
+    x2: number;
+    /** Y coordinate of the bottom edge (pixels from top, inclusive). */
+    y2: number;
+};

package/out/types/PageArea.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/PageExclusion.d.ts

@@ -0,0 +1,46 @@
+import type { PageArea } from './PageArea.js';
+import type { RgbColor } from './RgbColor.js';
+/**
+ * Defines a page-specific exclusion zone for PDF comparison.
+ *
+ * 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 rendered page are silently ignored.
+ * If multiple entries target the same `pageNumber`, only the first matching entry is used.
+ */
+export type PageExclusion = {
+    /**
+     * 1-based page number this exclusion applies to.
+     * Must be a finite positive integer matching the page's position in the PDF
+     * (`1` = first page, `2` = second page, etc.).
+     */
+    pageNumber: number;
+    /**
+     * Rectangular regions to exclude from pixel comparison on this page.
+     * Coordinates (`x1`, `y1`, `x2`, `y2`) are in pixels relative to the rendered PNG
+     * at the configured `viewportScale`. `(x1, y1)` is the top-left corner and
+     * `(x2, y2)` is the bottom-right corner.
+     */
+    excludedAreas?: PageArea[];
+    /**
+     * Colour used to paint excluded regions before comparison.
+     * Expressed as `{ r, g, b }` with channel values in the range 0–255.
+     *
+     * When omitted, the downstream PNG comparator uses its default blue fill colour.
+     */
+    excludedAreaColor?: RgbColor;
+    /**
+     * Override the diff image output file path for this specific page.
+     * When set, takes precedence over the path derived from `diffsOutputFolder`.
+     * When omitted, the path is auto-generated as `<diffsOutputFolder>/diff_<pageName>`.
+     * When diff writing is enabled, the resolved path must stay within `diffsOutputFolder`,
+     * otherwise `comparePdf` throws `ComparePdfConfigurationError`.
+     */
+    diffFilePath?: string;
+    /**
+     * Per-page pixel difference threshold that overrides the document-level
+     * `compareThreshold` for this page only. Must be a finite non-negative integer.
+     * When omitted, the document-level `compareThreshold` applies.
+     */
+    matchingThreshold?: number;
+};

package/out/types/PageExclusion.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/PdfInput.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Supported PDF input sources for `comparePdf()` and `comparePdfDetailed()`.
+ *
+ * - `string`: trusted path to a PDF file on disk, opened and read before rendering
+ * - `Buffer`: Node.js binary PDF content
+ * - `ArrayBufferLike`: binary PDF content, including `ArrayBuffer` and `SharedArrayBuffer`
+ *
+ * `SharedArrayBuffer` inputs are normalized to `ArrayBuffer` before being passed to the PDF renderer.
+ * For untrusted environments, prefer binary inputs or configure `allowedInputRoot`.
+ */
+export type PdfInput = string | Buffer | ArrayBufferLike;

package/out/types/PdfInput.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/PdfRenderOptions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Options for rendering PDF pages before visual comparison.
+ *
+ * These options are part of this library's public contract and are adapted internally
+ * to the current PDF rendering dependency. Options that disable page content or enable
+ * parallel rendering are intentionally excluded because this library always renders
+ * page images sequentially for safe comparison.
+ */
+export type PdfRenderOptions = {
+    /**
+     * Scale factor applied to each page viewport before rendering.
+     * Values above `1` produce larger, higher-resolution images; values below `1` produce smaller images.
+     */
+    viewportScale?: number;
+    /**
+     * When `true`, embedded fonts are not loaded and built-in fonts are used instead.
+     */
+    disableFontFace?: boolean;
+    /**
+     * When `true`, system-installed fonts may be used as fallbacks for missing embedded fonts.
+     */
+    useSystemFonts?: boolean;
+    /**
+     * When `true`, XFA (XML Forms Architecture) form data is rendered.
+     */
+    enableXfa?: boolean;
+    /**
+     * Password used to open an encrypted PDF.
+     */
+    pdfFilePassword?: string;
+    /**
+     * Folder path where intermediate PNG files are written.
+     * This library namespaces the renderer output under `actual/` and `expected/` subfolders
+     * to avoid filename collisions between the two compared PDFs.
+     * When omitted, rendered pages stay in memory unless another option writes them to disk.
+     */
+    outputFolder?: string;
+    /**
+     * Custom naming function for output PNG files.
+     * Receives the 1-based page number and must return a filename ending with `.png`.
+     */
+    outputFileMaskFunc?: (pageNumber: number) => string;
+    /**
+     * 1-based page numbers to render. When omitted, all pages are rendered.
+     */
+    pagesToProcess?: number[];
+    /**
+     * Renderer verbosity level. `0` logs errors only, `1` warnings, and `5` informational output.
+     */
+    verbosityLevel?: number;
+};

package/out/types/PdfRenderOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/types/RgbColor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * An RGB colour used in diff output images.
+ */
+export type RgbColor = {
+    /** Red channel (0–255). */
+    r: number;
+    /** Green channel (0–255). */
+    g: number;
+    /** Blue channel (0–255). */
+    b: number;
+};

package/out/types/RgbColor.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });