@ironsoftware/ironpdf 2026.3.1 → 2026.5.1

package/src/public/pdfDocument.ts

@@ -4,6 +4,7 @@ import {
 	BarcodeType, ChangeTrackingModes,
 	ChromePdfRenderOptions,
 	DigitalSignature,
+	VerifiedSignature,
 	HtmlAffix,
 	HtmlFilePath,
 	HtmlStampOptions,
@@ -14,12 +15,14 @@ import {
 	ImageStampOptions,
 	ImageToPdfOptions,
 	ImageType,
+	LinearizationMode,
 	PageInfo,
 	PageRotation,
 	PdfInput,
 	PdfPageSelection,
 	PdfPaperSize,
 	PdfPassword, PdfPermission,
+	RenderedElementLocation,
 	SaveOptions,
 	TextAffix,
 	TextStampOptions,
@@ -64,7 +67,17 @@ import {mergePdfs, renderHtmlToPdf, renderHtmlZipToPdf, renderUrlToPdf, renderHt
 import {disposePdf, getBinaryData, openPdfFileBuffer} from "../internal/grpc_layer/pdfium/io";
 import {Access} from "../internal/access";
 import {renderImagesBufferToPdf, renderImagesFilesToPdf} from "../internal/grpc_layer/chrome/image";
-import {compressImage, compressInMemory, compressInMemoryStream, compressStructTree} from "../internal/grpc_layer/pdfium/compress";
+import {compressAndSaveAs, compressImage, compressInMemory, compressInMemoryStream, compressStructTree} from "../internal/grpc_layer/pdfium/compress";
+import {
+	isLinearizedFromBytes,
+	linearizeCoreFromBytes,
+	linearizeCoreFromId,
+	linearizeInMemoryFromIdStream
+} from "../internal/grpc_layer/pdfium/linearize";
+import {addLinkAnnotation, getAnnotationCount, getAnnotations} from "../internal/grpc_layer/pdfium/annotations";
+import {LinkAnnotation} from "./annotation";
+import {getBookmarks} from "../internal/grpc_layer/pdfium/bookmarks";
+import {Bookmark} from "./bookmark";
 import {Readable} from "stream";
 import {
 	duplicate,
@@ -77,9 +90,9 @@ import {
 import {extractRawImages, rasterizeToImageBuffers} from "../internal/grpc_layer/pdfium/image";
 import Jimp from "jimp";
 import {extractAllText, replaceText} from "../internal/grpc_layer/pdfium/text";
-import {PdfAVersions, PdfUAVersions, toPdfA, toPdfUA} from "../internal/grpc_layer/pdfium/pdfa";
+import {PdfAVersions, PdfUAVersions, toPdfA, toPdfUA, toPdfUAForScreenReader} from "../internal/grpc_layer/pdfium/pdfa";
 import {getMetadataDict, removeMetadata, setMetadata, setMetadataDict} from "../internal/grpc_layer/pdfium/metadata";
-import {getSignatureCount, signPdf} from "../internal/grpc_layer/pdfium/signing";
+import {getSignatureCount, getVerifiedSignatures, signPdf} from "../internal/grpc_layer/pdfium/signing";
 import {addHtmlAffix, addTextAffix} from "../internal/grpc_layer/pdfium/headerFooter";
 import {stampBarcode, stampHtml, stampImage, stampText} from "../internal/grpc_layer/chrome/stamp";
 import {addBackgroundForeground} from "../internal/grpc_layer/pdfium/BackgroundForeground";
@@ -373,7 +386,8 @@ export class PdfDocument{
 
 	//#region compress
 	/**
-	 * Compress existing PDF images using JPG encoding and the specified settings
+	 * Compress existing PDF images using JPG encoding and the specified settings.
+	 * @deprecated Use {@link compressAndSaveAs}, {@link compressPdfToBytes}, or {@link compressPdfToStream} instead for better compression results.
 	 * @param imageQuality Quality (1 - 100) to use during compression
 	 * @param scaleToVisibleSize Scale down the image resolution according to its visible size in the PDF document
 	 */
@@ -437,6 +451,233 @@ export class PdfDocument{
 			(imageQuality);
 	}
 
+	/**
+	 * Compress the PDF and save the result directly to a file.
+	 * Uses QPdf compression which can significantly reduce file size.
+	 * @param filePath The output file path to save the compressed PDF.
+	 * @param imageQuality Optional JPEG quality (1-100) for image compression. If omitted, default compression is applied.
+	 */
+	public async compressAndSaveAs(
+		filePath: string,
+		imageQuality?: number
+	): Promise<void> {
+		return await z.function()
+			.args(
+				stringSchema,
+				numberSchema.optional()
+			)
+			.returns(z.promise(z.void()))
+			.implement(this.internal_compressAndSaveAs.bind(this))
+			(filePath, imageQuality);
+	}
+
+	//#endregion
+
+	//#region linearize
+	/**
+	 * Linearize the current PDF document and return the result as a {@link Buffer} (byte array).
+	 * Produces a web-optimized PDF that can be viewed incrementally in a browser.
+	 *
+	 * @param mode Linearization strategy. Defaults to {@link LinearizationMode.Automatic}.
+	 * @returns A Promise resolving to a Buffer containing the linearized PDF bytes.
+	 */
+	public async linearizePdfToBytes(
+		mode: LinearizationMode = LinearizationMode.Automatic
+	): Promise<Buffer> {
+		return this.internal_linearizePdfToBytes(mode);
+	}
+
+	/**
+	 * Linearize the current PDF document and return the result as a {@link Readable} stream.
+	 * Useful for piping directly to file streams or HTTP responses without buffering the
+	 * entire PDF in memory.
+	 *
+	 * <b>Note:</b> Stream output is only supported with {@link LinearizationMode.InMemory}
+	 * (or {@link LinearizationMode.Automatic} when memory mode is selected). For
+	 * {@link LinearizationMode.FileBased} use {@link linearizePdfToBytes} or
+	 * {@link saveAsLinearized}.
+	 *
+	 * @returns A Promise resolving to a Readable stream of the linearized PDF bytes.
+	 */
+	public async linearizePdfToStream(): Promise<Readable> {
+		return this.internal_linearizePdfToStream();
+	}
+
+	/**
+	 * Linearize the current PDF document and save the result to the given output file path.
+	 *
+	 * @param outputFilePath The file path to save the linearized PDF.
+	 * @param mode Linearization strategy. Defaults to {@link LinearizationMode.Automatic}.
+	 */
+	public async saveAsLinearized(
+		outputFilePath: string,
+		mode: LinearizationMode = LinearizationMode.Automatic
+	): Promise<void> {
+		return await z.function()
+			.args(filePathSchema, z.nativeEnum(LinearizationMode).optional())
+			.returns(z.promise(z.void()))
+			.implement(async (filePath: string, m?: LinearizationMode): Promise<void> => {
+				return this.internal_saveAsLinearized(filePath, m ?? LinearizationMode.Automatic);
+			})
+			(outputFilePath, mode);
+	}
+
+	/**
+	 * Check whether the PDF file at the given path is linearized ("Fast Web View").
+	 *
+	 * @param pdfFilePath Path to a PDF file on disk.
+	 * @param password    Optional password for encrypted PDFs.
+	 * @returns A Promise resolving to true if the file is linearized, false otherwise.
+	 */
+	public static async isLinearized(
+		pdfFilePath: string,
+		password = ""
+	): Promise<boolean> {
+		return await z.function()
+			.args(pdfFilePathSchema, stringSchema.optional())
+			.returns(z.promise(booleanSchema))
+			.implement(async (filePath: string, pwd?: string): Promise<boolean> => {
+				const bytes = fs.readFileSync(filePath);
+				return await isLinearizedFromBytes(bytes, pwd ?? "");
+			})
+			(pdfFilePath, password);
+	}
+
+	/**
+	 * Linearize the given PDF bytes and return the linearized bytes.
+	 * Static helper for linearizing PDFs without creating a PdfDocument instance.
+	 *
+	 * @param pdfBytes Buffer containing the PDF data.
+	 * @param password Optional password to decrypt the PDF if encrypted.
+	 * @param mode     Linearization strategy. Defaults to {@link LinearizationMode.Automatic}.
+	 */
+	public static async linearizePdfBytesToBytes(
+		pdfBytes: Buffer,
+		password = "",
+		mode: LinearizationMode = LinearizationMode.Automatic
+	): Promise<Buffer> {
+		return await z.function()
+			.args(bufferSchema, stringSchema.optional(), z.nativeEnum(LinearizationMode).optional())
+			.returns(z.promise(z.instanceof(Buffer)))
+			.implement(async (bytes: Buffer, pwd?: string, m?: LinearizationMode): Promise<Buffer> => {
+				return await linearizeCoreFromBytes(bytes, pwd ?? "", m ?? LinearizationMode.Automatic);
+			})
+			(pdfBytes, password, mode);
+	}
+
+	/**
+	 * Linearize the given PDF bytes and save the result to the given output file path.
+	 * Static helper for linearizing PDFs without creating a PdfDocument instance.
+	 *
+	 * @param pdfBytes       Buffer containing the PDF data.
+	 * @param outputFilePath The file path to save the linearized PDF.
+	 * @param password       Optional password to decrypt the PDF if encrypted.
+	 * @param mode           Linearization strategy. Defaults to {@link LinearizationMode.Automatic}.
+	 */
+	public static async saveAsLinearizedFromBytes(
+		pdfBytes: Buffer,
+		outputFilePath: string,
+		password = "",
+		mode: LinearizationMode = LinearizationMode.Automatic
+	): Promise<void> {
+		return await z.function()
+			.args(bufferSchema, filePathSchema, stringSchema.optional(), z.nativeEnum(LinearizationMode).optional())
+			.returns(z.promise(z.void()))
+			.implement(async (bytes: Buffer, filePath: string, pwd?: string, m?: LinearizationMode): Promise<void> => {
+				const linearized = await linearizeCoreFromBytes(bytes, pwd ?? "", m ?? LinearizationMode.Automatic);
+				fs.writeFileSync(filePath, linearized);
+			})
+			(pdfBytes, outputFilePath, password, mode);
+	}
+	//#endregion
+
+	//#region elementLocations
+	/**
+	 * Retrieves the rendered page locations of HTML elements that were tracked during rendering.
+	 *
+	 * To use this feature, set {@link ChromePdfRenderOptions.elementQuerySelectors} with CSS
+	 * selectors before rendering. After rendering, call this method to retrieve the page index
+	 * and coordinates of each matched element.
+	 *
+	 * Results are cached on first call and reused on subsequent calls. If you modify the
+	 * document's annotations after rendering, call {@link resetElementLocationCache} to force
+	 * the cache to be rebuilt on next access.
+	 *
+	 * Mirrors {@code IronPdf.PdfDocument.GetElementLocations()} on the C# side.
+	 *
+	 * @returns A list of {@link RenderedElementLocation} objects, one per matched element,
+	 * sorted in document order. Returns an empty list if no element query selectors were
+	 * configured or no elements matched.
+	 */
+	public async getElementLocations(): Promise<RenderedElementLocation[]> {
+		return this.internal_getElementLocations();
+	}
+
+	/**
+	 * Clears the cached result of {@link getElementLocations}, forcing a fresh scan of the
+	 * document's annotations on the next call. Call this if you've modified the document's
+	 * annotations or structure after rendering.
+	 */
+	public resetElementLocationCache(): void {
+		this.cachedElementLocations = null;
+	}
+	//#endregion
+
+	//#region bookmarks
+	/**
+	 * Retrieves all outline bookmarks (table-of-contents entries) in this PDF document.
+	 *
+	 * <p>Bookmarks are returned as a flat list with parent linkage via
+	 * {@link Bookmark.parentItemId}. Roots have an empty {@code parentItemId}.
+	 * Use {@link Bookmark.hierarchy} for depth information.</p>
+	 *
+	 * <p>Auto-bookmarks generated from HTML headings (via
+	 * {@link ChromePdfRenderOptions.autoBookmarksFromHeadings}) are included.</p>
+	 *
+	 * <p>Mirrors {@code IronPdf.PdfDocument.Bookmarks} on the C# side.</p>
+	 *
+	 * @returns A list of {@link Bookmark} objects, sorted in document order.
+	 *          Returns an empty list if the document has no bookmarks.
+	 */
+	public async getBookmarks(): Promise<Bookmark[]> {
+		return this.internal_getBookmarks();
+	}
+	//#endregion
+
+	//#region annotation
+	/**
+	 * Adds a clickable internal hyperlink annotation that navigates to another page within
+	 * the same PDF document. Useful for building custom tables of contents, cross-references,
+	 * and in-document navigation.
+	 *
+	 * The target page and display options are configured via the {@link LinkAnnotation}
+	 * fields ({@code destinationPageIndex}, {@code destinationType}, etc.).
+	 *
+	 * Mirrors {@code IronPdf.Annotations.LinkAnnotation} on the C# side.
+	 *
+	 * @example
+	 * ```ts
+	 * await pdf.addLinkAnnotation({
+	 *     pageIndex: 0,
+	 *     destinationPageIndex: 3,
+	 *     x: 72, y: 700,
+	 *     width: 300, height: 18,
+	 *     contents: "Chapter 1",
+	 * });
+	 * ```
+	 */
+	public async addLinkAnnotation(link: LinkAnnotation): Promise<void> {
+		return this.internal_addLinkAnnotation(link);
+	}
+
+	/**
+	 * Retrieves the number of annotations contained on the specified page.
+	 *
+	 * @param pageIndex Zero-based page index. The first page has a page index of 0.
+	 */
+	public async getAnnotationCount(pageIndex: number): Promise<number> {
+		return this.internal_getAnnotationCount(pageIndex);
+	}
 	//#endregion
 
 	//#region page
@@ -713,6 +954,25 @@ export class PdfDocument{
 			(pdfaVersion, customICC);
 	}
 
+	/**
+	 * Render HTML to PDF and convert to PDF/UA format with screen reader support.
+	 * Produces a proper semantic structure tree (Sect → H1, P, etc.) for accessibility.
+	 * @param html The HTML string to render
+	 * @param naturalLanguages Document language for screen readers (default: English)
+	 * @param options Optional render options
+	 */
+	public static async fromHtmlAsPdfUA(
+		html: string,
+		naturalLanguages: NaturalLanguages = NaturalLanguages.English,
+		options?: {
+			renderOptions?: ChromePdfRenderOptions | undefined;
+		} | undefined
+	): Promise<PdfDocument> {
+		const pdf = await PdfDocument.fromHtml(html, options);
+		await toPdfUAForScreenReader(await pdf.internal_getId(), html, naturalLanguages);
+		return pdf;
+	}
+
 	/**
 	 * Convert the current document into the specified PDF/UA standard format
 	 */
@@ -805,6 +1065,15 @@ export class PdfDocument{
 		return this.internal_signatureCount()
 	}
 
+	/**
+	 * Get all verified digital signatures from this PdfDocument.
+	 * Returns details including signature name, signer contact, reason, location, date, and validity.
+	 * @returns A Promise resolving to an array of {@link VerifiedSignature} objects.
+	 */
+	public async getVerifiedSignatures(): Promise<VerifiedSignature[]> {
+		return this.internal_getVerifiedSignatures()
+	}
+
 	//#endregion
 
 	//#region header/footer (affix)
@@ -1549,6 +1818,153 @@ export class PdfDocument{
 		);
 	}
 
+	/**
+	 * Compress the PDF and save the result directly to a file.
+	 * Uses QPdf compression which can significantly reduce file size.
+	 * @param filePath The output file path to save the compressed PDF.
+	 * @param imageQuality Optional JPEG quality (1-100) for image compression. If omitted, default compression is applied.
+	 */
+	private async internal_compressAndSaveAs(
+		filePath: string,
+		imageQuality?: number
+	): Promise<void> {
+		if (imageQuality !== undefined && (imageQuality < 1 || imageQuality > 100))
+			throw new Error(
+				`Invalid quality specifier (${imageQuality}) when compressing PDF. Quality must be between 1 and 100.`
+			);
+		return await compressAndSaveAs(
+			await this.internal_getId(),
+			filePath,
+			imageQuality
+		);
+	}
+
+	//#endregion
+
+	//#region linearize
+	/**
+	 * Linearize the current PDF document and return the result as a Buffer.
+	 */
+	private async internal_linearizePdfToBytes(mode: LinearizationMode): Promise<Buffer> {
+		const id = await this.internal_getId();
+		return await linearizeCoreFromId(id, () => this.internal_saveAsBuffer(), "", mode);
+	}
+
+	/**
+	 * Linearize the current PDF document and return the result as a Readable stream.
+	 * Always uses the in-memory streaming RPC.
+	 */
+	private async internal_linearizePdfToStream(): Promise<Readable> {
+		return await linearizeInMemoryFromIdStream(await this.internal_getId());
+	}
+
+	/**
+	 * Linearize the current PDF document and save the result to the given output file path.
+	 */
+	private async internal_saveAsLinearized(outputFilePath: string, mode: LinearizationMode): Promise<void> {
+		const id = await this.internal_getId();
+		const linearized = await linearizeCoreFromId(id, () => this.internal_saveAsBuffer(), "", mode);
+		fs.writeFileSync(outputFilePath, linearized);
+	}
+	//#endregion
+
+	//#region elementLocations
+	/**
+	 * Prefix used by the engine-side element query JavaScript extension when injecting anchor
+	 * markers. Must match {@code IronPdf.TableOfContents.ElementQueryJavascriptExtension.ELEMENT_QUERY_PREFIX}
+	 * on the C# side.
+	 */
+	private static readonly ELEMENT_QUERY_PREFIX = "ironpdf-elq-";
+
+	/**
+	 * Cache for {@link getElementLocations}. Built lazily on first call.
+	 *
+	 * The underlying element-query anchor annotations are written during rendering and are
+	 * not expected to be mutated afterwards, so a simple populate-once cache is appropriate.
+	 * Callers who modify the document's annotations after rendering should call
+	 * {@link resetElementLocationCache} to force a rebuild.
+	 */
+	private cachedElementLocations: RenderedElementLocation[] | null = null;
+
+	private async internal_getElementLocations(): Promise<RenderedElementLocation[]> {
+		if (this.cachedElementLocations !== null) {
+			return this.cachedElementLocations;
+		}
+
+		const id = await this.internal_getId();
+		const pageInfos = await getPageInfo(id);
+		const locations: RenderedElementLocation[] = [];
+
+		for (let pageIdx = 0; pageIdx < pageInfos.length; pageIdx++) {
+			const annotations = await getAnnotations(id, pageIdx);
+
+			for (const wrapped of annotations) {
+				if (!wrapped.link) continue;
+				const dest = wrapped.link.dest;
+				if (!dest || !dest.startsWith(PdfDocument.ELEMENT_QUERY_PREFIX)) continue;
+
+				const remainder = dest.substring(PdfDocument.ELEMENT_QUERY_PREFIX.length);
+				const dashIdx = remainder.indexOf("-");
+				if (dashIdx <= 0) continue;
+
+				const indexStr = remainder.substring(0, dashIdx);
+				const elementIndex = parseInt(indexStr, 10);
+				if (isNaN(elementIndex)) continue;
+
+				const encodedText = remainder.substring(dashIdx + 1);
+				let text: string;
+				try {
+					text = decodeURIComponent(encodedText);
+				} catch {
+					text = encodedText;
+				}
+
+				const innerRect = wrapped.link.annotation?.rectangle;
+				const rectangle = innerRect
+					? {
+							x: innerRect.x ?? 0,
+							y: innerRect.y ?? 0,
+							width: innerRect.width ?? 0,
+							height: innerRect.height ?? 0,
+					  }
+					: {x: 0, y: 0, width: 0, height: 0};
+
+				locations.push({text, pageIndex: pageIdx, rectangle, elementIndex});
+			}
+		}
+
+		locations.sort((a, b) => a.elementIndex - b.elementIndex);
+		this.cachedElementLocations = locations;
+		return this.cachedElementLocations;
+	}
+	//#endregion
+
+	//#region annotation
+	private async internal_addLinkAnnotation(link: LinkAnnotation): Promise<void> {
+		if (!link) {
+			throw new Error("link annotation cannot be null or undefined");
+		}
+		if (link.pageIndex < 0) {
+			throw new Error("Invalid page index when adding link annotation");
+		}
+		if (link.destinationPageIndex < 0) {
+			throw new Error("Invalid destination page index when adding link annotation");
+		}
+		await addLinkAnnotation(await this.internal_getId(), link);
+	}
+
+	private async internal_getAnnotationCount(pageIndex: number): Promise<number> {
+		if (pageIndex < 0) {
+			throw new Error("Invalid page index when getting annotation count");
+		}
+		return await getAnnotationCount(await this.internal_getId(), pageIndex);
+	}
+	//#endregion
+
+	//#region bookmarks
+	private async internal_getBookmarks(): Promise<Bookmark[]> {
+		return await getBookmarks(await this.internal_getId());
+	}
 	//#endregion
 
 	//#region page
@@ -1875,6 +2291,13 @@ export class PdfDocument{
 		return await getSignatureCount(await this.internal_getId());
 	}
 
+	/**
+	 * Get all verified digital signatures from this PdfDocument.
+	 */
+	private async internal_getVerifiedSignatures(): Promise<VerifiedSignature[]> {
+		return await getVerifiedSignatures(await this.internal_getId());
+	}
+
 	//#endregion
 
 	//#region header/footer (affix)

package/src/public/render.d.ts

@@ -1,6 +1,72 @@
 import { PdfPaperOrientation, PdfPaperSize } from "./paper";
 import { HtmlAffix, TextAffix } from "./affix";
 import { CssMediaType, FitToPaperModes, MarginConfig, UseMargins, TableOfContentsTypes } from "./types";
+/**
+ * Represents the rendered location of an HTML element within a PDF document.
+ *
+ * Returned by {@code PdfDocument.getElementLocations()} after rendering HTML with
+ * {@link ChromePdfRenderOptions.elementQuerySelectors} configured.
+ *
+ * Mirrors {@code IronPdf.RenderedElementLocation} on the C# side.
+ */
+export interface RenderedElementLocation {
+    /**
+     * The text content of the matched element.
+     */
+    text: string;
+    /**
+     * The zero-based page index where the element was rendered.
+     */
+    pageIndex: number;
+    /**
+     * The bounding rectangle of the annotation marker on the page, in PDF points (1/72 inch).
+     * Coordinate origin is the bottom-left corner of the page. The rectangle corresponds to
+     * the injected anchor marker placed at the start of the matched element.
+     */
+    rectangle: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * The original index of the element in document order among all matched elements.
+     */
+    elementIndex: number;
+}
+/**
+ * Specifies the linearization strategy to use when producing a linearized
+ * (web-optimized) PDF.
+ *
+ * Mirrors {@code IronPdf.LinearizationMode} on the C# side.
+ */
+export declare enum LinearizationMode {
+    /**
+     * Automatically selects the optimal linearization method based on system capabilities.
+     *
+     * Behavior:
+     *   1. First attempts {@link FileBased} linearization.
+     *   2. If disk access is restricted (e.g. limited permissions, sandboxed environment),
+     *      automatically falls back to {@link InMemory}.
+     *
+     * Recommended default for most applications.
+     */
+    Automatic = 0,
+    /**
+     * Performs linearization entirely in memory without any disk I/O operations.
+     *
+     * Use when:
+     *   - Compliance requirements mandate zero disk I/O (e.g. HIPAA, PCI-DSS)
+     *   - Sandboxed or restricted environments without disk write permissions
+     *   - Cloud-based environments where disk I/O introduces latency
+     */
+    InMemory = 1,
+    /**
+     * Performs linearization using temporary file operations on disk.
+     * Requires write permissions to the system temporary directory.
+     */
+    FileBased = 2
+}
 /**
  * Html or Url To PDF output options for {@link PdfGenerator} and {@link PdfDocument} static method.
  * Specify options such as Paper-Size, DPI and other Chromium specific browser setup options.
@@ -101,6 +167,44 @@ export interface ChromePdfRenderOptions {
      *  @default {@link UseMargins.LeftAndRight}
      */
     useMarginsOnHeaderAndFooter?: UseMargins | undefined;
+    /**
+     * If true, auto-generate PDF outline (bookmarks) from the HTML heading structure.
+     * Use {@link autoBookmarkMinHeadingLevel} / {@link autoBookmarkMaxHeadingLevel} to control
+     * which heading levels are included (1 = h1, 6 = h6). Use {@link autoBookmarkCssSelectors}
+     * to include additional non-heading elements (e.g. {@code ".chapter-title"}).
+     *
+     * @default false
+     */
+    autoBookmarksFromHeadings?: boolean | undefined;
+    /**
+     * Minimum heading level (inclusive) to include in auto-generated bookmarks.
+     * Only used when {@link autoBookmarksFromHeadings} is true.
+     *
+     * @default 1
+     */
+    autoBookmarkMinHeadingLevel?: number | undefined;
+    /**
+     * Maximum heading level (inclusive) to include in auto-generated bookmarks.
+     * Only used when {@link autoBookmarksFromHeadings} is true.
+     *
+     * @default 6
+     */
+    autoBookmarkMaxHeadingLevel?: number | undefined;
+    /**
+     * Additional CSS selectors whose matching elements will be included as auto-bookmarks
+     * (in addition to the heading range). Only used when {@link autoBookmarksFromHeadings} is true.
+     * Example: {@code [".chapter-title", "[data-bookmark]"]}.
+     */
+    autoBookmarkCssSelectors?: string[] | undefined;
+    /**
+     * CSS selectors whose matching HTML elements should be tracked during rendering so their
+     * rendered page positions can later be retrieved by the engine.
+     *
+     * <b>Note:</b> retrieval of the per-element locations from the Node client is not yet
+     * supported. Setting this option still enables engine-side tracking (and any downstream
+     * effects such as auto-bookmarks for those selectors).
+     */
+    elementQuerySelectors?: string[] | undefined;
 }
 /**
  *  A managed wrapper of wait-for configurations. see {@link ChromePdfRenderOptions.waitFor}

package/src/public/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["render.ts"],"names":[],"mappings":"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"}

package/src/public/render.js

@@ -1,8 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultChromePdfRenderOptions = exports.WaitForType = void 0;
+exports.defaultChromePdfRenderOptions = exports.WaitForType = exports.LinearizationMode = void 0;
 const paper_1 = require("./paper");
 const types_1 = require("./types");
+/**
+ * Specifies the linearization strategy to use when producing a linearized
+ * (web-optimized) PDF.
+ *
+ * Mirrors {@code IronPdf.LinearizationMode} on the C# side.
+ */
+var LinearizationMode;
+(function (LinearizationMode) {
+    /**
+     * Automatically selects the optimal linearization method based on system capabilities.
+     *
+     * Behavior:
+     *   1. First attempts {@link FileBased} linearization.
+     *   2. If disk access is restricted (e.g. limited permissions, sandboxed environment),
+     *      automatically falls back to {@link InMemory}.
+     *
+     * Recommended default for most applications.
+     */
+    LinearizationMode[LinearizationMode["Automatic"] = 0] = "Automatic";
+    /**
+     * Performs linearization entirely in memory without any disk I/O operations.
+     *
+     * Use when:
+     *   - Compliance requirements mandate zero disk I/O (e.g. HIPAA, PCI-DSS)
+     *   - Sandboxed or restricted environments without disk write permissions
+     *   - Cloud-based environments where disk I/O introduces latency
+     */
+    LinearizationMode[LinearizationMode["InMemory"] = 1] = "InMemory";
+    /**
+     * Performs linearization using temporary file operations on disk.
+     * Requires write permissions to the system temporary directory.
+     */
+    LinearizationMode[LinearizationMode["FileBased"] = 2] = "FileBased";
+})(LinearizationMode = exports.LinearizationMode || (exports.LinearizationMode = {}));
 /**
  * A wait-for type. see {@link ChromePdfRenderOptions.waitFor} also {@link WaitFor}
  */

package/src/public/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["render.ts"],"names":[],"mappings":";;;AAAA,mCAAuE;AAEvE,mCAMiB;AAwHjB;;GAEG;AACH,IAAY,WAQX;AARD,WAAY,WAAW;IACtB,oCAAqB,CAAA;IACrB,wCAAyB,CAAA;IACzB,0CAA2B,CAAA;IAC3B,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,0CAA2B,CAAA;AAC5B,CAAC,EARW,WAAW,GAAX,mBAAW,KAAX,mBAAW,QAQtB;AAiGD,SAAgB,6BAA6B;IACrC,OAAO;QACC,YAAY,EAAE,oBAAY,CAAC,KAAK;QAChC,gBAAgB,EAAE,IAAI;QACtB,eAAe,EAAE,CAAC;QAClB,eAAe,EAAE,4BAAoB,CAAC,IAAI;QAC1C,cAAc,EAAE,uBAAe,CAAC,OAAO;QACrD,SAAS,EAAE,KAAK;QAChB,aAAa,EAAE,OAAO;QACtB,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;QAChD,SAAS,EAAE,iBAAS,CAAC,EAAE;QACvB,gBAAgB,EAAE,2BAAmB,CAAC,QAAQ;QAC9C,oBAAoB,EAAE,IAAI;QAC1B,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE;QACrD,uBAAuB;QACvB,wBAAwB;QACxB,aAAa;QACb,sBAAsB,EAAE,IAAI;QACd,YAAY,EAAE,EAAE;QAChB,2BAA2B,EAAE,kBAAU,CAAC,GAAG;KAClD,CAAC;AACV,CAAC;AArBD,sEAqBC"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["render.ts"],"names":[],"mappings":";;;AAAA,mCAAuE;AAEvE,mCAMiB;AA+BjB;;;;;GAKG;AACH,IAAY,iBA0BX;AA1BD,WAAY,iBAAiB;IAC5B;;;;;;;;;OASG;IACH,mEAAa,CAAA;IACb;;;;;;;OAOG;IACH,iEAAY,CAAA;IACZ;;;OAGG;IACH,mEAAa,CAAA;AACd,CAAC,EA1BW,iBAAiB,GAAjB,yBAAiB,KAAjB,yBAAiB,QA0B5B;AA8JD;;GAEG;AACH,IAAY,WAQX;AARD,WAAY,WAAW;IACtB,oCAAqB,CAAA;IACrB,wCAAyB,CAAA;IACzB,0CAA2B,CAAA;IAC3B,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,0CAA2B,CAAA;AAC5B,CAAC,EARW,WAAW,GAAX,mBAAW,KAAX,mBAAW,QAQtB;AAiGD,SAAgB,6BAA6B;IACrC,OAAO;QACC,YAAY,EAAE,oBAAY,CAAC,KAAK;QAChC,gBAAgB,EAAE,IAAI;QACtB,eAAe,EAAE,CAAC;QAClB,eAAe,EAAE,4BAAoB,CAAC,IAAI;QAC1C,cAAc,EAAE,uBAAe,CAAC,OAAO;QACrD,SAAS,EAAE,KAAK;QAChB,aAAa,EAAE,OAAO;QACtB,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;QAChD,SAAS,EAAE,iBAAS,CAAC,EAAE;QACvB,gBAAgB,EAAE,2BAAmB,CAAC,QAAQ;QAC9C,oBAAoB,EAAE,IAAI;QAC1B,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE;QACrD,uBAAuB;QACvB,wBAAwB;QACxB,aAAa;QACb,sBAAsB,EAAE,IAAI;QACd,YAAY,EAAE,EAAE;QAChB,2BAA2B,EAAE,kBAAU,CAAC,GAAG;KAClD,CAAC;AACV,CAAC;AArBD,sEAqBC"}