@ironsoftware/ironpdf 2026.4.1 → 2026.6.1

package/src/public/pdfDocument.ts

@@ -15,12 +15,14 @@ import {
 	ImageStampOptions,
 	ImageToPdfOptions,
 	ImageType,
+	LinearizationMode,
 	PageInfo,
 	PageRotation,
 	PdfInput,
 	PdfPageSelection,
 	PdfPaperSize,
 	PdfPassword, PdfPermission,
+	RenderedElementLocation,
 	SaveOptions,
 	TextAffix,
 	TextStampOptions,
@@ -65,7 +67,20 @@ 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 {compressAndSaveAs, compressImage, compressInMemory, compressInMemoryStream, compressStructTree} from "../internal/grpc_layer/pdfium/compress";
+import {compressAndSaveAs, compressImage, compressInMemory, compressInMemoryStream, compressStructTree, compressAndSaveAsAdvanced, compressAndSaveAsAdvancedFromBytes} from "../internal/grpc_layer/pdfium/compress";
+import {disableFormFontFallback, setFormFont} from "../internal/grpc_layer/pdfium/form";
+import {AdvancedCompressionOptions} from "./compression";
+import * as path from "path";
+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,
@@ -78,7 +93,7 @@ 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, getVerifiedSignatures, signPdf} from "../internal/grpc_layer/pdfium/signing";
 import {addHtmlAffix, addTextAffix} from "../internal/grpc_layer/pdfium/headerFooter";
@@ -459,6 +474,324 @@ export class PdfDocument{
 			(filePath, imageQuality);
 	}
 
+	/**
+	 * Apply the advanced compression pipeline and save the result to a file.
+	 *
+	 * Combines pdfium-side image DPI downsampling with qpdf-side structural
+	 * optimization in a single call.
+	 *
+	 * @param filePath the file path to save the compressed PDF
+	 * @param options  advanced compression options; pass an empty object `{}` to
+	 *                 reproduce the legacy compressAndSaveAs behaviour with no
+	 *                 image downsampling
+	 * @param password the PDF password (empty string if none)
+	 */
+	public async compressAndSaveAsAdvanced(
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<void> {
+		return this.internal_compressAndSaveAsAdvanced(filePath, options, password);
+	}
+
+	/**
+	 * Apply the advanced compression pipeline to byte[] input and save the
+	 * compressed result to a file. Returns the compressed bytes as well.
+	 */
+	public static async compressAndSaveAsAdvancedFromBytes(
+		pdfBytes: Buffer,
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<Buffer> {
+		if (!pdfBytes || pdfBytes.length === 0) {
+			throw new Error("pdfBytes must not be null or empty");
+		}
+		if (!options) {
+			throw new Error("options must not be null");
+		}
+		return compressAndSaveAsAdvancedFromBytes(pdfBytes, filePath, options, password ?? "");
+	}
+
+	//#endregion
+
+	//#region form (PDF-2184)
+
+	/**
+	 * Set the document-wide form font for subsequent form-field fills. When
+	 * set, the engine skips its automatic Tahoma/Arial fallback embed for
+	 * non-ASCII form values and registers the supplied font in the AcroForm
+	 * /DR /Font dictionary so default-appearance strings resolve correctly
+	 * at render time.
+	 *
+	 * File-size impact:
+	 * - Name-only mode (`fontData` omitted or empty): zero bytes added; the
+	 *   font must already be in the document.
+	 * - Bytes mode and the font is already embedded with usable glyph data:
+	 *   zero bytes added.
+	 * - Bytes mode and the font is missing or has no glyph data: the full
+	 *   font is embedded.
+	 * - Bytes mode with `forceEmbed = true`: a fresh font copy is added
+	 *   alongside any existing copy; the document grows on every call.
+	 *
+	 * @param fontName   PDF font name to register (e.g. "Poppins-Regular").
+	 *                   Allowed characters: letters, digits, `_`, `-`, `.`, `+`.
+	 * @param fontData   Raw TrueType/OpenType bytes; pass `undefined` or an
+	 *                   empty Buffer for name-only mode.
+	 * @param forceEmbed When true, embed `fontData` even if a font with the
+	 *                   same name and usable glyph data is already present.
+	 */
+	public async setFormFont(
+		fontName: string,
+		fontData?: Buffer,
+		forceEmbed = false
+	): Promise<void> {
+		return setFormFont(await this.internal_getId(), fontName, fontData, forceEmbed);
+	}
+
+	/**
+	 * Load a TrueType/OpenType font from disk and apply it as the
+	 * document-wide form font. The PDF font name is derived from the file
+	 * name (without extension) when `fontName` is omitted.
+	 *
+	 * @param fontFilePath Path to a TTF/OTF/TTC font file
+	 * @param fontName     Optional PDF font name. When omitted the file name
+	 *                     (without extension) is used.
+	 * @param forceEmbed   When true, embed even if the font is already present.
+	 */
+	public async setFormFontFromFile(
+		fontFilePath: string,
+		fontName?: string,
+		forceEmbed = false
+	): Promise<void> {
+		if (!fontFilePath) {
+			throw new Error("fontFilePath must not be empty");
+		}
+		const fontData = fs.readFileSync(fontFilePath);
+		const resolvedName = fontName ?? deriveFontNameFromPath(fontFilePath);
+		return setFormFont(await this.internal_getId(), resolvedName, fontData, forceEmbed);
+	}
+
+	/**
+	 * Suppress the automatic Tahoma/Arial fallback embed for non-ASCII form
+	 * values without registering any replacement font. Use when zero
+	 * file-size growth is required and the template's existing font
+	 * references are sufficient for the values being filled.
+	 *
+	 * Rendering of non-ASCII characters then depends entirely on the
+	 * viewer's font substitution.
+	 */
+	public async disableFormFontFallback(): Promise<void> {
+		return disableFormFontFallback(await this.internal_getId());
+	}
+
+	//#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
@@ -735,23 +1068,24 @@ export class PdfDocument{
 			(pdfaVersion, customICC);
 	}
 
-	// TODO: Re-enable once IronPdfEngine handler for Pdfium_ConvertToPdfUAForScreenReader
-	// is fixed to call HtmlHelper.HtmlStructTreeDOM() and ConvertToPdfUAForScreenReader().
-	// Currently the engine handler ignores the HTML and falls back to basic ConvertToPdfUA,
-	// producing a flat tag tree instead of proper semantic structure.
-	// See: IronPdfServiceHandler.cs:97-108
-	//
-	// 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;
-	// }
+	/**
+	 * 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
@@ -1619,6 +1953,160 @@ export class PdfDocument{
 		);
 	}
 
+	private async internal_compressAndSaveAsAdvanced(
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<void> {
+		if (!filePath || filePath.trim().length === 0) {
+			throw new Error("filePath must not be empty");
+		}
+		if (!options) {
+			throw new Error("options must not be null");
+		}
+		if (
+			options.jpegQuality !== undefined &&
+			options.jpegQuality !== null &&
+			(options.jpegQuality < 1 || options.jpegQuality > 100)
+		) {
+			throw new Error(
+				`Invalid jpegQuality (${options.jpegQuality}). Must be between 1 and 100.`
+			);
+		}
+		return await compressAndSaveAsAdvanced(
+			await this.internal_getId(),
+			filePath,
+			options,
+			password ?? ""
+		);
+	}
+
+	//#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
@@ -2224,3 +2712,14 @@ export class PdfDocument{
 
 	//#endregion
 }
+
+/**
+ * Derive a PDF font name from a font file path: strip the directory and the
+ * extension. Used by {@link PdfDocument.setFormFontFromFile} when no
+ * explicit name is supplied.
+ */
+function deriveFontNameFromPath(fontFilePath: string): string {
+	const base = path.basename(fontFilePath);
+	const dot = base.lastIndexOf(".");
+	return dot > 0 ? base.substring(0, dot) : base;
+}