modern-pdf-lib 0.29.0 → 0.30.0

package/dist/{src-Ci9ZjqhP.mjs → src-s9zNsZAT.mjs}

@@ -1,4 +1,4 @@
-import { A as encodeUTCTime, Br as rectangle, Bt as PageSizes, C as encodeInteger, E as encodeOctetString, F as parseDerTlv, Gr as setLineWidth, H as mergePdfs, I as toBuffer, Jr as beginText, Kn as applyFillColor, L as computeSignatureHash, M as extractIssuerAndSerial, N as extractSubjectPublicKeyInfo, O as encodeSequence, P as getSubtle, Pr as fill, Rn as restoreState, Rr as lineTo, S as encodeContextTag, Sn as formatPdfDate, T as encodeOID, Vn as saveState, Vr as setDashPattern, Xr as moveText, Yn as cmykToRgb, Yr as endText, at as sha256, b as detectKeyAlgorithm, ei as setFont, gn as buildAnnotationDict, gt as PdfParseError, k as encodeSet, mn as PdfAnnotation, n as StandardFonts, oi as setWordSpacing, qn as applyStrokeColor, qr as stroke, r as createPdf, s as setPageLabels, si as showText$1, t as PdfDocument, x as detectNamedCurve, y as decodeOidBytes, z as findSignatures, zr as moveTo } from "./pdfDocument-B6czyaVI.mjs";
+import { A as encodeUTCTime, Br as rectangle, Bt as PageSizes, C as encodeInteger, E as encodeOctetString, F as parseDerTlv, Gr as setLineWidth, H as mergePdfs, I as toBuffer, Jr as beginText, Kn as applyFillColor, L as computeSignatureHash, M as extractIssuerAndSerial, N as extractSubjectPublicKeyInfo, O as encodeSequence, P as getSubtle, Pr as fill, Rn as restoreState, Rr as lineTo, S as encodeContextTag, Sn as formatPdfDate, T as encodeOID, Vn as saveState, Vr as setDashPattern, Xr as moveText, Yn as cmykToRgb, Yr as endText, at as sha256, b as detectKeyAlgorithm, ei as setFont, gn as buildAnnotationDict, gt as PdfParseError, k as encodeSet, mn as PdfAnnotation, n as StandardFonts, oi as setWordSpacing, qn as applyStrokeColor, qr as stroke, r as createPdf, s as setPageLabels, si as showText$1, t as PdfDocument, x as detectNamedCurve, y as decodeOidBytes, z as findSignatures, zr as moveTo } from "./pdfDocument-Cgkkk8F8.mjs";
 import { c as PdfRef, i as PdfName, l as PdfStream, n as PdfBool, o as PdfNumber, r as PdfDict, t as PdfArray, u as PdfString } from "./pdfObjects-CB7TEdbW.mjs";
 import { n as decodeStreamData, r as getStreamFilters } from "./streamDecode-DCpgTocN.mjs";
 import { g as FieldFlags, v as numVal } from "./pdfForm-CfLnlsj-.mjs";
@@ -277,7 +277,7 @@ function compressStream(stream, level) {
 * @returns              The incremental save result.
 */
 async function saveDocumentIncremental(originalBytes, doc, options) {
-	const { buildDocumentStructure } = await import("./pdfDocument-B6czyaVI.mjs").then((n) => n.Cn);
+	const { buildDocumentStructure } = await import("./pdfDocument-Cgkkk8F8.mjs").then((n) => n.Cn);
 	const registry = doc.getRegistry();
 	const structure = buildDocumentStructure(doc.getInternalPages().map((p) => p.finalize()), {
 		producer: doc.getProducer(),
@@ -29946,6 +29946,476 @@ var RenderCache = class {
 	}
 };
 //#endregion
+//#region src/compliance/afAttach.ts
+/**
+* @module compliance/afAttach
+*
+* Attach embedded / associated files to any PDF object.
+*
+* The Associated Files mechanism (`/AF`) lets a PDF declare that one or more
+* embedded files are *associated* with a given object.  ISO 32000-2 allows the
+* `/AF` key on the document catalog (§7.11.4) as well as on individual objects
+* — page dictionaries, annotation dictionaries, Form/Image XObject stream
+* dictionaries, and structure elements (§14.13).  Because every one of those
+* targets is a plain {@link PdfDict}, the same helper attaches `/AF` uniformly.
+*
+* In addition, a *document-level* associated file must also be reachable
+* through the catalog's embedded-files name tree
+* (`/Names` → `/EmbeddedFiles` → `/Names`).  {@link createAssociatedFile} (in
+* `associatedFiles.ts`) intentionally leaves that wiring to the caller;
+* {@link registerEmbeddedFile} completes it.
+*
+* These are pure builders: they mutate the supplied dictionaries in place and
+* return nothing.  Object numbers / serialization remain the writer's concern.
+*
+* Reference: ISO 32000-2:2020, §7.11.4 (embedded file streams) and §14.13
+* (associated files).
+*/
+/**
+* Attach one or more associated files to any PDF object via its `/AF` key.
+*
+* Works uniformly for the document catalog, a page dictionary, an annotation
+* dictionary, a Form/Image XObject stream's dictionary, or a structure-element
+* dictionary — all of which are plain {@link PdfDict} instances.
+*
+* If `target` has no `/AF` yet, a fresh array (built with
+* {@link buildAfArray}) is set.  If `/AF` is already a {@link PdfArray}, the
+* new refs are appended to it, preserving the existing entries and order.  Any
+* other (malformed) `/AF` value is replaced with a fresh array.
+*
+* @param target        The object dictionary to attach the files to.
+* @param fileSpecRefs  Indirect references to file-specification dictionaries.
+*/
+function attachAssociatedFiles(target, fileSpecRefs) {
+	const existing = target.get("/AF");
+	if (existing instanceof PdfArray) {
+		for (const ref of fileSpecRefs) existing.push(ref);
+		return;
+	}
+	target.set("/AF", buildAfArray([...fileSpecRefs]));
+}
+/**
+* Locate the `/EmbeddedFiles` name-tree `/Names` array on the catalog,
+* creating the intermediate `/Names` and `/EmbeddedFiles` dictionaries (and
+* the leaf `/Names` array) if they do not yet exist.  Existing dictionaries
+* are reused in place rather than replaced.
+*/
+function ensureEmbeddedFilesNames(catalog) {
+	const namesEntry = catalog.get("/Names");
+	const namesDict = namesEntry instanceof PdfDict ? namesEntry : new PdfDict();
+	if (namesDict !== namesEntry) catalog.set("/Names", namesDict);
+	const efEntry = namesDict.get("/EmbeddedFiles");
+	const efDict = efEntry instanceof PdfDict ? efEntry : new PdfDict();
+	if (efDict !== efEntry) namesDict.set("/EmbeddedFiles", efDict);
+	const leafEntry = efDict.get("/Names");
+	const leaf = leafEntry instanceof PdfArray ? leafEntry : new PdfArray();
+	if (leaf !== leafEntry) efDict.set("/Names", leaf);
+	return leaf;
+}
+/**
+* Insert a `[name, fileSpecRef]` pair into an embedded-files name-tree `/Names`
+* array, keeping the array sorted by name.  The array is a flat sequence of
+* alternating key/value entries: `[ name0, ref0, name1, ref1, … ]`.
+*/
+function insertNamePairSorted(leaf, name, fileSpecRef) {
+	const items = leaf.items;
+	let insertAt = items.length;
+	for (let i = 0; i < items.length; i += 2) {
+		const entry = items[i];
+		if ((entry instanceof PdfString ? entry.value : "") > name) {
+			insertAt = i;
+			break;
+		}
+	}
+	items.splice(insertAt, 0, PdfString.literal(name), fileSpecRef);
+}
+/**
+* Complete {@link createAssociatedFile}'s "caller responsibility" by wiring a
+* file-specification reference into the document catalog at the *document
+* level*.
+*
+* Two things happen:
+*  1. The pair `[PdfString.literal(name), fileSpecRef]` is added to the
+*     catalog's `/Names` → `/EmbeddedFiles` → `/Names` array, keeping the
+*     array's name/value pairs sorted by name (as required for a name tree).
+*     The intermediate dictionaries and the leaf array are created on demand
+*     and reused if already present.
+*  2. `fileSpecRef` is added to the catalog's `/AF` array (via
+*     {@link attachAssociatedFiles}).
+*
+* @param catalog      The document catalog dictionary.
+* @param name         The name under which the file is registered in the tree.
+* @param fileSpecRef  Indirect reference to the file-specification dictionary.
+*/
+function registerEmbeddedFile(catalog, name, fileSpecRef) {
+	insertNamePairSorted(ensureEmbeddedFilesNames(catalog), name, fileSpecRef);
+	attachAssociatedFiles(catalog, [fileSpecRef]);
+}
+//#endregion
+//#region src/compliance/pageOutputIntent.ts
+/**
+* @module compliance/pageOutputIntent
+*
+* Per-page and per-stream output intents (ISO 32000-2 §14.11.5).
+*
+* In addition to the document-level `/OutputIntents` array carried on the
+* catalog, PDF 2.0 permits an `/OutputIntents` array on individual *page*
+* dictionaries and on *Form XObject* stream dictionaries.  These narrower
+* intents override the document intent for the colour-managed content of that
+* page or form, which is essential for documents that mix output conditions
+* (for example, a PDF/X job whose individual pages target different print
+* presses).
+*
+* This module provides two pure builders:
+*
+*  - {@link buildPageOutputIntent} constructs a single `/OutputIntent`
+*    dictionary (reusing {@link buildOutputIntent} for the embedded ICC
+*    `/DestOutputProfile`) and registers it as an indirect object.
+*  - {@link attachOutputIntents} sets — or, when one already exists, appends
+*    to — the `/OutputIntents` array on a target dictionary (a page dict for
+*    per-page intents, or a Form XObject stream's dict for per-stream).
+*
+* Reference: ISO 32000-2:2020, §14.11.5 (Output intents).
+*/
+/**
+* Attach output-intent references to a target dictionary's `/OutputIntents`
+* array.
+*
+* If the target has no `/OutputIntents` entry, a fresh {@link PdfArray} is
+* created and populated with `intentRefs`.  If one already exists (and is an
+* array), the references are appended to it in order, preserving the existing
+* array instance.
+*
+* The target may be a page dictionary (for per-page intents) or a Form
+* XObject stream's dictionary (for per-stream intents).
+*
+* @param target      The page or Form XObject dictionary to mutate.
+* @param intentRefs  Indirect references to `/OutputIntent` dictionaries.
+*/
+function attachOutputIntents(target, intentRefs) {
+	const existing = target.get("/OutputIntents");
+	const array = existing instanceof PdfArray ? existing : new PdfArray();
+	for (const ref of intentRefs) array.push(ref);
+	if (!(existing instanceof PdfArray)) target.set("/OutputIntents", array);
+}
+/**
+* Build a per-page / per-stream `/OutputIntent` dictionary and register it.
+*
+* The embedded ICC `/DestOutputProfile` is produced by reusing
+* {@link buildOutputIntent}; this builder then layers the per-page subtype
+* (`/S`), output-condition identifier and optional `/Info` string on top.
+* The resulting dictionary carries `/Type /OutputIntent` and may be attached
+* to a page or Form XObject dictionary via {@link attachOutputIntents}.
+*
+* @param registry  The PDF object registry to register objects into.
+* @param options   Output-intent configuration.
+* @returns         An indirect reference to the `/OutputIntent` dictionary.
+*/
+function buildPageOutputIntent(registry, options = {}) {
+	const intentRef = buildOutputIntent(registry, {
+		subtype: options.subtype ?? "/GTS_PDFA1",
+		...options.iccProfile !== void 0 ? { iccProfile: options.iccProfile } : {},
+		...options.components !== void 0 ? { components: options.components } : {},
+		...options.outputConditionIdentifier !== void 0 ? { outputConditionIdentifier: options.outputConditionIdentifier } : {}
+	});
+	const intentDict = registry.resolve(intentRef);
+	if (intentDict !== void 0 && intentDict.kind === "dict") {
+		intentDict.set("/Type", PdfName.of("OutputIntent"));
+		if (options.outputConditionIdentifier !== void 0) intentDict.set("/OutputConditionIdentifier", PdfString.literal(options.outputConditionIdentifier));
+		if (options.info !== void 0) intentDict.set("/Info", PdfString.literal(options.info));
+	}
+	return intentRef;
+}
+//#endregion
+//#region src/compliance/encryptedPayload.ts
+/**
+* @module compliance/encryptedPayload
+*
+* Unencrypted wrapper documents and encrypted payloads
+* (ISO 32000-2:2020 §7.6.7).
+*
+* A PDF 2.0 *unencrypted wrapper document* is an ordinary, viewable PDF that
+* carries an *encrypted payload* as an embedded file.  The wrapper itself is
+* not encrypted (so any conforming reader can open it and show a cover page),
+* while the sensitive content lives in the embedded payload, which is
+* protected by an external/handler-specific crypto filter.
+*
+* The payload is declared through an *Encrypted Payload* dictionary
+* (`/Type /EncryptedPayload`).  Its `/Subtype` names the crypto filter used to
+* protect the payload (for example `/AESV3`), and an optional `/Version`
+* records the version of that filter.  The Encrypted Payload dictionary is
+* attached to the embedded file's *file specification* dictionary via the
+* `/EP` key, and that file specification is also marked with
+* `/AFRelationship /EncryptedPayload`.
+*
+* This module provides two pure builders:
+*
+*  - {@link buildEncryptedPayload} — build the `/EncryptedPayload` dictionary.
+*  - {@link buildUnencryptedWrapper} — embed the payload bytes as an
+*    associated file and attach the `/EP` dictionary to its file
+*    specification, returning the file-spec reference.
+*
+* The caller attaches the returned file-spec reference to the catalog `/AF`
+* array and to the `/Names /EmbeddedFiles` name tree (for example via
+* `afAttach`).
+*
+* Reference: ISO 32000-2:2020, §7.6.7 (Unencrypted wrapper document).
+*/
+/**
+* Build an `/EncryptedPayload` dictionary (ISO 32000-2 §7.6.7).
+*
+* The returned dictionary has:
+*  - `/Type /EncryptedPayload`
+*  - `/Subtype /<subtype>` — the crypto filter name
+*  - `/Version /<version>` — only when {@link EncryptedPayloadOptions.version}
+*    is supplied
+*
+* @param options - The crypto-filter subtype and optional version.
+* @returns A spec-shaped `/EncryptedPayload` {@link PdfDict}.
+*/
+function buildEncryptedPayload(options) {
+	const dict = new PdfDict();
+	dict.set("/Type", PdfName.of("EncryptedPayload"));
+	dict.set("/Subtype", PdfName.of(options.subtype));
+	if (options.version !== void 0) dict.set("/Version", PdfName.of(options.version));
+	return dict;
+}
+/**
+* Build the embedded encrypted-payload file for an unencrypted wrapper
+* document and return its file-specification reference.
+*
+* The payload bytes are embedded via {@link createAssociatedFile} with an
+* `/AFRelationship` of `/EncryptedPayload` and an `application/octet-stream`
+* MIME type.  The resolved file-specification dictionary then receives an
+* `/EP` entry holding the {@link buildEncryptedPayload} dictionary.
+*
+* The caller is responsible for attaching the returned file-spec reference to
+* the catalog `/AF` array and the `/Names /EmbeddedFiles` name tree.
+*
+* @param registry - The PDF object registry to register objects into.
+* @param options  - The payload bytes, filename, crypto subtype/version, and
+*                   optional description.
+* @returns An indirect reference to the file-specification dictionary.
+*/
+function buildUnencryptedWrapper(registry, options) {
+	const { fileSpecRef } = createAssociatedFile(registry, {
+		data: options.data,
+		filename: options.filename,
+		mimeType: "application/octet-stream",
+		relationship: "EncryptedPayload",
+		description: options.description
+	});
+	const fileSpec = registry.resolve(fileSpecRef);
+	if (fileSpec instanceof PdfDict) {
+		const ep = buildEncryptedPayload({
+			subtype: options.subtype,
+			version: options.version
+		});
+		fileSpec.set("/EP", ep);
+	}
+	return fileSpecRef;
+}
+//#endregion
+//#region src/core/softMask.ts
+/**
+* @module core/softMask
+*
+* Soft-mask groups in graphics state (ISO 32000-1 §11.6.5.2).
+*
+* A *soft mask* defines a per-pixel shape/opacity for subsequent painting
+* operations.  It is carried in an `ExtGState` dictionary under the `/SMask`
+* key.  The mask is derived from a *transparency-group XObject* (a form
+* XObject whose `/Group` dictionary has `/S /Transparency`):
+*
+*  - A **luminosity** mask (`/S /Luminosity`) computes the mask value from the
+*    luminosity of the group's composited result.  An optional `/BC` backdrop
+*    color sets the colour against which the group is composited before the
+*    luminosity is measured.
+*  - An **alpha** mask (`/S /Alpha`) computes the mask value from the group's
+*    accumulated alpha (shape/opacity).  `/BC` is not meaningful and is omitted.
+*
+* An optional `/TR` *transfer function* remaps the computed mask values; it may
+* be an indirect reference to a function object or the name `/Identity`.
+*
+* These are pure builders: they return spec-shaped `ExtGState` dictionaries.
+* Registering the result and naming it in a page's `/Resources /ExtGState`
+* (e.g. via `page.registerExtGState(name, registry.register(extGState))`) is
+* the caller's concern.
+*
+* Reference: ISO 32000-1:2008, §11.6.5.2 (Mask shape and opacity);
+*            ISO 32000-1:2008, §8.4.5 (Graphics state, `/SMask`).
+*/
+/**
+* Build an `ExtGState` dictionary that installs a soft-mask group.
+*
+* The returned dictionary has `/Type /ExtGState` and an `/SMask` mask
+* dictionary:
+*
+*  - `/Type /Mask`
+*  - `/S /Luminosity` or `/S /Alpha` (per {@link SoftMaskGroupOptions.type},
+*    defaulting to `Luminosity`)
+*  - `/G` → the supplied group XObject reference
+*  - `/BC [ … ]` — backdrop colour, **only** for luminosity masks and only
+*    when {@link SoftMaskGroupOptions.backdropColor} is provided
+*  - `/TR` → the transfer function (indirect reference) or the name
+*    `/Identity`, only when {@link SoftMaskGroupOptions.transferFunction} is
+*    provided
+*
+* @param options - The soft-mask group description.
+* @returns A spec-shaped `ExtGState` {@link PdfDict}.
+*/
+function buildSoftMaskGroupExtGState(options) {
+	const subtype = options.type ?? "Luminosity";
+	const smask = new PdfDict();
+	smask.set("/Type", PdfName.of("Mask"));
+	smask.set("/S", PdfName.of(subtype));
+	smask.set("/G", options.groupXObject);
+	if (subtype === "Luminosity" && options.backdropColor !== void 0 && options.backdropColor.length > 0) smask.set("/BC", PdfArray.fromNumbers([...options.backdropColor]));
+	if (options.transferFunction !== void 0) smask.set("/TR", options.transferFunction === "Identity" ? PdfName.of("Identity") : options.transferFunction);
+	const extGState = new PdfDict();
+	extGState.set("/Type", PdfName.of("ExtGState"));
+	extGState.set("/SMask", smask);
+	return extGState;
+}
+/**
+* Build an `ExtGState` dictionary that clears any active soft mask by setting
+* `/SMask /None`.  Apply this after a masked region to restore unmasked
+* painting.
+*
+* @returns An `ExtGState` {@link PdfDict} with `/SMask /None`.
+*/
+function buildSoftMaskNone() {
+	const extGState = new PdfDict();
+	extGState.set("/Type", PdfName.of("ExtGState"));
+	extGState.set("/SMask", PdfName.of("None"));
+	return extGState;
+}
+//#endregion
+//#region src/core/imageMask.ts
+/**
+* @module core/imageMask
+*
+* Image masks and black-point compensation per ISO 32000-2 §8.9.6
+* (Masked images) and §8.6.5.9 (Black-point compensation).
+*
+* PDF supports three ways of masking an image XObject:
+*
+* - **Stencil mask** — a 1-bit-per-component `/ImageMask` image whose sample
+*   values select which areas of the page are painted with the current fill
+*   colour and which are left untouched (§8.9.6.2). The mask data is packed
+*   one bit per sample, each row byte-aligned (`ceil(width / 8)` bytes per
+*   row); the caller supplies the already-packed bytes.
+* - **Colour-key mask** — a `/Mask` array of `[min0 max0 min1 max1 …]`
+*   integer ranges (two per colour component) that makes matching sample
+*   colours transparent (§8.9.6.4).
+* - **Soft mask** — a separate DeviceGray image referenced from a base
+*   image's `/SMask` entry, giving per-pixel opacity (§11.6.5.2).
+*
+* Black-point compensation (§8.6.5.9) is controlled through an ExtGState's
+* `/UseBlackPtComp` entry, which selects whether the conversion between
+* colour spaces maps source black to destination black.
+*
+* These are pure builders: they construct (and, for the stream variants,
+* register) PDF objects but do not wire them into a page or resource
+* dictionary — that is the caller's concern.
+*
+* Reference: ISO 32000-2:2020, §8.9.6 (Masked images), §8.6.5.9
+*            (Black-point compensation).
+*/
+/**
+* Build a stencil mask: a 1-bit `/ImageMask` image XObject (§8.9.6.2).
+*
+* The returned stream has `/Type /XObject`, `/Subtype /Image`,
+* `/ImageMask true`, `/BitsPerComponent 1`, and the supplied `/Width` and
+* `/Height`. When a `decode` pair is given it is emitted as a `/Decode`
+* array, allowing the mask polarity to be inverted (`[1 0]`).
+*
+* The `bits` buffer must already be packed one bit per sample with each row
+* byte-aligned (`ceil(width / 8)` bytes per row); this builder stores it
+* verbatim and does not repack it.
+*
+* @param registry - Registry to register the stream into.
+* @param bits     - Packed, byte-aligned 1-bpc mask data.
+* @param width    - Image width in samples.
+* @param height   - Image height in samples.
+* @param decode   - Optional `[d0, d1]` decode pair.
+* @returns An indirect reference to the registered image XObject stream.
+*/
+function buildStencilMask(registry, bits, width, height, decode) {
+	const dict = new PdfDict();
+	dict.set("/Type", PdfName.of("XObject"));
+	dict.set("/Subtype", PdfName.of("Image"));
+	dict.set("/ImageMask", PdfBool.TRUE);
+	dict.set("/BitsPerComponent", PdfNumber.of(1));
+	dict.set("/Width", PdfNumber.of(width));
+	dict.set("/Height", PdfNumber.of(height));
+	if (decode !== void 0) dict.set("/Decode", PdfArray.fromNumbers([decode[0], decode[1]]));
+	dict.set("/Length", PdfNumber.of(bits.length));
+	return registry.register(new PdfStream(dict, bits));
+}
+/**
+* Build a colour-key masking array (§8.9.6.4).
+*
+* The `ranges` list holds two integers — a minimum and a maximum — per
+* colour component, laid out as `[min0 max0 min1 max1 …]`. Sample colours
+* whose every component falls within its range become transparent. The
+* returned {@link PdfArray} is assigned to a base image's `/Mask` entry.
+*
+* @param ranges - An even-length list of `[min, max]` integer pairs.
+* @returns A `/Mask` {@link PdfArray} of {@link PdfNumber}s.
+* @throws RangeError if `ranges` is empty or has an odd length.
+*/
+function buildColorKeyMask(ranges) {
+	if (ranges.length === 0 || ranges.length % 2 !== 0) throw new RangeError(`colour-key mask requires a non-empty even number of values (min/max pairs); got ${ranges.length}`);
+	return new PdfArray(ranges.map((v) => PdfNumber.of(v)));
+}
+/**
+* Build an image soft mask: a DeviceGray image XObject usable as a base
+* image's `/SMask` (§11.6.5.2).
+*
+* The returned stream has `/Type /XObject`, `/Subtype /Image`,
+* `/ColorSpace /DeviceGray`, the supplied `/Width` and `/Height`, and
+* `/BitsPerComponent` (defaulting to 8). Each grayscale sample provides the
+* opacity of the corresponding base-image pixel.
+*
+* @param registry          - Registry to register the stream into.
+* @param gray              - Grayscale opacity samples.
+* @param width             - Image width in samples.
+* @param height            - Image height in samples.
+* @param bitsPerComponent  - Bits per sample; defaults to 8.
+* @returns An indirect reference to the registered soft-mask image XObject.
+*/
+function buildImageSoftMask(registry, gray, width, height, bitsPerComponent) {
+	const dict = new PdfDict();
+	dict.set("/Type", PdfName.of("XObject"));
+	dict.set("/Subtype", PdfName.of("Image"));
+	dict.set("/Width", PdfNumber.of(width));
+	dict.set("/Height", PdfNumber.of(height));
+	dict.set("/ColorSpace", PdfName.of("DeviceGray"));
+	dict.set("/BitsPerComponent", PdfNumber.of(bitsPerComponent ?? 8));
+	dict.set("/Length", PdfNumber.of(gray.length));
+	return registry.register(new PdfStream(dict, gray));
+}
+/**
+* Build an ExtGState that controls black-point compensation (§8.6.5.9).
+*
+* The returned dictionary has `/Type /ExtGState` and `/UseBlackPtComp` set
+* to the requested mode:
+*
+* - `Default` — leave the choice to the conforming reader.
+* - `ON`      — always apply black-point compensation.
+* - `OFF`     — never apply black-point compensation.
+*
+* @param mode - The `/UseBlackPtComp` mode.
+* @returns An ExtGState {@link PdfDict}.
+*/
+function buildBlackPointCompensationExtGState(mode) {
+	const gs = new PdfDict();
+	gs.set("/Type", PdfName.of("ExtGState"));
+	gs.set("/UseBlackPtComp", PdfName.of(mode));
+	return gs;
+}
+//#endregion
 //#region src/index.ts
 /** Whether initWasm has already completed successfully. */
 let wasmInitialized = false;
@@ -29972,15 +30442,15 @@ async function initWasm(options) {
 	if (wasmInitialized) return;
 	const inits = [];
 	if (options.deflate || options.deflateWasm) inits.push((async () => {
-		const { initDeflateWasm } = await import("./pdfDocument-B6czyaVI.mjs").then((n) => n.zt);
+		const { initDeflateWasm } = await import("./pdfDocument-Cgkkk8F8.mjs").then((n) => n.zt);
 		await initDeflateWasm(options.deflateWasm);
 	})());
 	if (options.png || options.pngWasm) inits.push((async () => {
-		const { initPngWasm } = await import("./pdfDocument-B6czyaVI.mjs").then((n) => n.At);
+		const { initPngWasm } = await import("./pdfDocument-Cgkkk8F8.mjs").then((n) => n.At);
 		await initPngWasm(options.pngWasm);
 	})());
 	if (options.fonts || options.fontWasm) inits.push((async () => {
-		const { initSubsetWasm } = await import("./pdfDocument-B6czyaVI.mjs").then((n) => n.Pt);
+		const { initSubsetWasm } = await import("./pdfDocument-Cgkkk8F8.mjs").then((n) => n.Pt);
 		await initSubsetWasm(options.fontWasm);
 	})());
 	if (options.jpeg || options.jpegWasm) inits.push((async () => {
@@ -29991,6 +30461,6 @@ async function initWasm(options) {
 	wasmInitialized = true;
 }
 //#endregion
-export { setFieldValue as $, appendIncrementalUpdate as $i, formatDate$1 as $n, extractJpegMetadata as $r, buildLab as $t, buildPdfXOutputIntent as A, generateSquigglyAppearance as Aa, validatePdfA as Ai, flattenField as An, ean13ToOperators as Ar, levenshtein as At, decodeTile as B, buildSeparationColorSpace as Ba, hasLtvData as Bi, ForeignPageError as Bn, encodeCode128 as Br, buildType1Halftone as Bt, validateKeyUsage as C, PdfFreeTextAnnotation as Ca, getToUnicodeCmap as Ci, batchFlatten as Cn, pdf417ToOperators as Cr, generateOrderX as Ct, layoutColumns as D, generateInkAppearance as Da, detectTransparency as Di, getBookmarks as Dn, encodeUpcA as Dr, buildFunctionShading as Dt, findHyphenationPoints as E, generateHighlightAppearance as Ea, generateSrgbIccProfile as Ei, addBookmark as En, calculateUpcCheckDigit as Er, pdfA4Rules as Et, normalizeComponentDepth as F, buildXmpMetadata as Fa, computeObjectHash as Fi, EncryptedPdfError as Fn, itfToOperators as Fr, buildPdfX6OutputIntent as Ft, downloadCrl as G, buildFieldLockDict as Gi, NoSuchFieldError as Gn, embedTiffDirect as Gr, markdownToPdf as Gt, parseTileInfo as H, saveDocumentIncremental as Ha, getCounterSignatures as Hi, InvalidFieldNamePartError as Hn, valuesToModules as Hr, identityTransferFunction as Ht, offsetSignedToUnsigned as I, createXmpStream as Ia, findChangedObjects as Ii, ExceededMaxLengthError as In, code39ToOperators as Ir, validateBoxGeometry as It, checkCertificateStatus as J, MdpPermission as Ji, RichTextFieldReadError as Jn, webpToJpeg as Jr, reconstructParagraphs as Jt, extractCrlUrls as K, getFieldLocks as Ki, PluginError as Kn, encodePngFromPixels as Kr, buildCollection as Kt, summarizeBitDepth as L, parseXmpMetadata$1 as La, optimizeIncrementalSave as Li, FieldAlreadyExistsError as Ln, computeCode39CheckDigit as Lr, STANDARD_SPOT_FUNCTIONS as Lt, validatePdfX as M, generateUnderlineAppearance as Ma, getLinearizationInfo as Mi, flattenForm as Mn, encodeEan13 as Mr, generateCiiXml as Mt, downscale16To8 as N, PdfLinkAnnotation as Na, isLinearized as Ni, BatchProcessingError as Nn, encodeEan8 as Nr, buildBoxDict as Nt, layoutParagraph as O, generateLineAppearance as Oa, flattenTransparency as Oi, removeAllBookmarks as On, upcAToOperators as Or, sampleShadingColor as Ot, getComponentDepths as P, PdfTextAnnotation as Pa, linearizePdf as Pi, CombedTextLayoutError as Pn, encodeItf as Pr, buildGtsPdfxVersion as Pt, resolveFieldReference as Q, validateSignatureChain as Qi, applyHeaderFooterToPage as Qn, isCmykTiff as Qr, buildCalRGB as Qt, upscale8To16 as R, PDFOperator as Ra, buildDssDictionary as Ri, FieldExistsAsNonTerminalError as Rn, encodeCode39 as Rr, buildSampledTransferFunction as Rt, validateExtendedKeyUsage as S, PdfUnderlineAnnotation as Sa, generateZapfDingbatsToUnicodeCmap as Si, validatePdfUa as Sn, encodePdf417 as Sr, splitByScript as St, validateCertificateChain as T, generateFreeTextAppearance as Ta, SRGB_ICC_PROFILE as Ti, processBatch as Tn, encodeDataMatrix as Tr, buildPdfA4Xmp as Tt, verifySignatureDetailed as U, saveIncremental as Ua, diffSignedContent as Ui, InvalidPageSizeError as Un, PdfWorker as Ur, nameHalftone as Ut, decodeTileRegion as V, ChangeTracker as Va, addCounterSignature as Vi, InvalidColorError as Vn, encodeCode128Values as Vr, buildType5Halftone as Vt, TrustStore as W, addFieldLock as Wi, MissingOnValueCheckError as Wn, canDirectEmbed as Wr, evaluateFunction as Wt, createSandbox as X, getCertificationLevel as Xi, UnexpectedFieldTypeError as Xn, convertTiffCmykToRgb as Xr, buildDocTimeStampDict as Xt, extractOcspUrl as Y, buildDocMdpReference as Yi, StreamingParseError as Yn, webpToPng as Yr, DEFAULT_DOC_TIMESTAMP_CONTENTS_SIZE as Yt, getFieldValue as Z, setCertificationLevel as Zi, applyHeaderFooter as Zn, embedTiffCmyk as Zr, buildCalGray as Zt, interpretPage as _, PdfPolygonAnnotation as _a, getProfile as _i, metadataPlugin as _n, readCode39 as _r, gtsPdfVtVersion as _t, redactRegions as a, parseTimestampResponse as aa, recompressImage as ai, MATHML_NAMESPACE as an, estimateTextWidth as ar, formatDate as at, EKU_OIDS as b, PdfSquigglyAnnotation as ba, generateSymbolToUnicodeCmap as bi, PdfDocumentBuilder as bn, calculateBarcodeDimensions as br, createRangeFetcher as bt, comparePages as c, PdfFileAttachmentAnnotation as ca, generatePdfAXmp as ci, buildNamespacesArray as cn, wrapText$2 as cr, formatNumber$1 as ct, generateThumbnail as d, PdfRedactAnnotation as da, stripProhibitedFeatures as di, buildRequirements as dn, borderedPreset as dr, isWoff2 as dt, findExistingSignatures as ea, injectJpegMetadata as ei, labToRgb as en, replaceTemplateVariables as er, addVisibilityAction as et, renderDisplayListToCanvas as f, PdfInkAnnotation as fa, buildAfArray as fi, buildDPartRoot as fn, minimalPreset as fr, readWoffHeader as ft, interpretContentStream as g, PdfPolyLineAnnotation as ga, validateXmpMetadata as gi, accessibilityPlugin as gn, readCode128 as gr, buildVtDpm as gt, renderPageToImage as h, PdfLineAnnotation as ha, parseXmpMetadata as hi, tableToJson as hn, readBarcode as hr, buildPdfVtDParts as ht, renderPageTile as i, buildTimestampRequest as ia, optimizeImage as ii, toSarif as in, ellipsisText as ir, AFDate_FormatEx as it, enforcePdfX as j, generateStrikeOutAppearance as ja, delinearizePdf as ji, flattenFields as jn, ean8ToOperators as jr, renderCodeFrame as jt, layoutTextFlow as k, generateSquareAppearance as ka, enforcePdfA as ki, removeBookmark as kn, calculateEanCheckDigit as kr, didYouMean as kt, extractFonts as l, PdfCaretAnnotation as la, generatePdfAXmpBytes as li, buildPieceInfo as ln, applyPreset as lr, decodeWoff as lt, rasterize as m, PdfCircleAnnotation as ma, extractXmpMetadata as mi, tableToCsv as mn, stripedPreset as mr, createWorkerPool as mt, RenderCache as n, saveIncrementalWithSignaturePreservation as na, downscaleImage as ni, SARIF_SCHEMA_URI as nn, toRoman as nr, validateFieldValue as nt, applyOcr as o, requestTimestamp as oa, applyRedaction as oi, PDF2_NAMESPACE as on, shrinkFontSize as or, parseAcrobatDate as ot, renderPageToCanvas as p, PdfStampAnnotation as pa, createAssociatedFile as pi, extractTables as pn, professionalPreset as pr, signDeferred as pt, isCertificateRevoked as q, detectModifications as qi, RemovePageFromEmptyDocumentError as qn, recompressWebP as qr, reconstructLines as qt, computeTileGrid as r, validateByteRangeIntegrity as ra, estimateJpegQuality as ri, toJsonReport as rn, applyOverflow as rr, AFSpecial_Format as rt, compareImages as s, searchTextItems as sa, enforcePdfAFull as si, buildNamespace as sn, truncateText as sr, AFNumber_Format as st, initWasm as t, parseExistingTrailer as ta, analyzeJpegMarkers as ti, DEFAULT_SARIF_TOOL_NAME as tn, toAlpha as tr, setFieldVisibility as tt, extractImages as u, PdfPopupAnnotation as ua, countOccurrences as ui, buildRequirement as un, applyTablePreset as ur, isWoff as ut, extractEmbeddedRevocationData as v, PdfSquareAnnotation as va, getSupportedLevels as vi, timestampPlugin as vn, readEan13 as vr, h as vt, buildCertificateChain as w, generateCircleAppearance as wa, buildOutputIntent as wi, batchMerge as wn, dataMatrixToOperators as wr, generateXRechnungCii as wt, validateCertificatePolicy as x, PdfStrikeOutAnnotation as xa, generateWinAnsiToUnicodeCmap as xi, enforcePdfUa as xn, renderStyledBarcode as xr, resolveFallback as xt, verifyOfflineRevocation as y, PdfHighlightAnnotation as ya, isValidLevel as yi, StreamingPdfParser as yn, readEan8 as yr, renderToPdf as yt, assembleTiles as z, buildDeviceNColorSpace as za, embedLtvData as zi, FontNotEmbeddedError as zn, code128ToOperators as zr, buildThresholdHalftone as zt };
+export { decodeTileRegion as $, ChangeTracker as $a, addCounterSignature as $i, InvalidColorError as $n, encodeCode128Values as $r, buildType5Halftone as $t, extractEmbeddedRevocationData as A, PdfSquareAnnotation as Aa, getSupportedLevels as Ai, timestampPlugin as An, readEan13 as Ar, h as At, layoutParagraph as B, generateLineAppearance as Ba, flattenTransparency as Bi, removeAllBookmarks as Bn, upcAToOperators as Br, sampleShadingColor as Bt, generateThumbnail as C, PdfRedactAnnotation as Ca, stripProhibitedFeatures as Ci, buildRequirements as Cn, borderedPreset as Cr, isWoff2 as Ct, renderPageToImage as D, PdfLineAnnotation as Da, parseXmpMetadata as Di, tableToJson as Dn, readBarcode as Dr, buildPdfVtDParts as Dt, rasterize as E, PdfCircleAnnotation as Ea, extractXmpMetadata as Ei, tableToCsv as En, stripedPreset as Er, createWorkerPool as Et, validateKeyUsage as F, PdfFreeTextAnnotation as Fa, getToUnicodeCmap as Fi, batchFlatten as Fn, pdf417ToOperators as Fr, generateOrderX as Ft, downscale16To8 as G, PdfLinkAnnotation as Ga, isLinearized as Gi, BatchProcessingError as Gn, encodeEan8 as Gr, buildBoxDict as Gt, buildPdfXOutputIntent as H, generateSquigglyAppearance as Ha, validatePdfA as Hi, flattenField as Hn, ean13ToOperators as Hr, levenshtein as Ht, buildCertificateChain as I, generateCircleAppearance as Ia, buildOutputIntent as Ii, batchMerge as In, dataMatrixToOperators as Ir, generateXRechnungCii as It, offsetSignedToUnsigned as J, createXmpStream as Ja, findChangedObjects as Ji, ExceededMaxLengthError as Jn, code39ToOperators as Jr, validateBoxGeometry as Jt, getComponentDepths as K, PdfTextAnnotation as Ka, linearizePdf as Ki, CombedTextLayoutError as Kn, encodeItf as Kr, buildGtsPdfxVersion as Kt, validateCertificateChain as L, generateFreeTextAppearance as La, SRGB_ICC_PROFILE as Li, processBatch as Ln, encodeDataMatrix as Lr, buildPdfA4Xmp as Lt, EKU_OIDS as M, PdfSquigglyAnnotation as Ma, generateSymbolToUnicodeCmap as Mi, PdfDocumentBuilder as Mn, calculateBarcodeDimensions as Mr, createRangeFetcher as Mt, validateCertificatePolicy as N, PdfStrikeOutAnnotation as Na, generateWinAnsiToUnicodeCmap as Ni, enforcePdfUa as Nn, renderStyledBarcode as Nr, resolveFallback as Nt, interpretContentStream as O, PdfPolyLineAnnotation as Oa, validateXmpMetadata as Oi, accessibilityPlugin as On, readCode128 as Or, buildVtDpm as Ot, validateExtendedKeyUsage as P, PdfUnderlineAnnotation as Pa, generateZapfDingbatsToUnicodeCmap as Pi, validatePdfUa as Pn, encodePdf417 as Pr, splitByScript as Pt, decodeTile as Q, buildSeparationColorSpace as Qa, hasLtvData as Qi, ForeignPageError as Qn, encodeCode128 as Qr, buildType1Halftone as Qt, findHyphenationPoints as R, generateHighlightAppearance as Ra, generateSrgbIccProfile as Ri, addBookmark as Rn, calculateUpcCheckDigit as Rr, pdfA4Rules as Rt, extractImages as S, PdfPopupAnnotation as Sa, countOccurrences as Si, buildRequirement as Sn, applyTablePreset as Sr, isWoff as St, renderPageToCanvas as T, PdfStampAnnotation as Ta, createAssociatedFile as Ti, extractTables as Tn, professionalPreset as Tr, signDeferred as Tt, enforcePdfX as U, generateStrikeOutAppearance as Ua, delinearizePdf as Ui, flattenFields as Un, ean8ToOperators as Ur, renderCodeFrame as Ut, layoutTextFlow as V, generateSquareAppearance as Va, enforcePdfA as Vi, removeBookmark as Vn, calculateEanCheckDigit as Vr, didYouMean as Vt, validatePdfX as W, generateUnderlineAppearance as Wa, getLinearizationInfo as Wi, flattenForm as Wn, encodeEan13 as Wr, generateCiiXml as Wt, upscale8To16 as X, PDFOperator as Xa, buildDssDictionary as Xi, FieldExistsAsNonTerminalError as Xn, encodeCode39 as Xr, buildSampledTransferFunction as Xt, summarizeBitDepth as Y, parseXmpMetadata$1 as Ya, optimizeIncrementalSave as Yi, FieldAlreadyExistsError as Yn, computeCode39CheckDigit as Yr, STANDARD_SPOT_FUNCTIONS as Yt, assembleTiles as Z, buildDeviceNColorSpace as Za, embedLtvData as Zi, FontNotEmbeddedError as Zn, code128ToOperators as Zr, buildThresholdHalftone as Zt, redactRegions as _, parseTimestampResponse as _a, recompressImage as _i, MATHML_NAMESPACE as _n, estimateTextWidth as _r, formatDate as _t, buildStencilMask as a, detectModifications as aa, recompressWebP as ai, reconstructLines as an, RemovePageFromEmptyDocumentError as ar, isCertificateRevoked as at, comparePages as b, PdfFileAttachmentAnnotation as ba, generatePdfAXmp as bi, buildNamespacesArray as bn, wrapText$2 as br, formatNumber$1 as bt, buildEncryptedPayload as c, getCertificationLevel as ca, convertTiffCmykToRgb as ci, buildDocTimeStampDict as cn, UnexpectedFieldTypeError as cr, createSandbox as ct, buildPageOutputIntent as d, appendIncrementalUpdate as da, extractJpegMetadata as di, buildLab as dn, formatDate$1 as dr, setFieldValue as dt, getCounterSignatures as ea, valuesToModules as ei, identityTransferFunction as en, saveDocumentIncremental as eo, InvalidFieldNamePartError as er, parseTileInfo as et, attachAssociatedFiles as f, findExistingSignatures as fa, injectJpegMetadata as fi, labToRgb as fn, replaceTemplateVariables as fr, addVisibilityAction as ft, renderPageTile as g, buildTimestampRequest as ga, optimizeImage as gi, toSarif as gn, ellipsisText as gr, AFDate_FormatEx as gt, computeTileGrid as h, validateByteRangeIntegrity as ha, estimateJpegQuality as hi, toJsonReport as hn, applyOverflow as hr, AFSpecial_Format as ht, buildImageSoftMask as i, getFieldLocks as ia, encodePngFromPixels as ii, buildCollection as in, PluginError as ir, extractCrlUrls as it, verifyOfflineRevocation as j, PdfHighlightAnnotation as ja, isValidLevel as ji, StreamingPdfParser as jn, readEan8 as jr, renderToPdf as jt, interpretPage as k, PdfPolygonAnnotation as ka, getProfile as ki, metadataPlugin as kn, readCode39 as kr, gtsPdfVtVersion as kt, buildUnencryptedWrapper as l, setCertificationLevel as la, embedTiffCmyk as li, buildCalGray as ln, applyHeaderFooter as lr, getFieldValue as lt, RenderCache as m, saveIncrementalWithSignaturePreservation as ma, downscaleImage as mi, SARIF_SCHEMA_URI as mn, toRoman as mr, validateFieldValue as mt, buildBlackPointCompensationExtGState as n, addFieldLock as na, canDirectEmbed as ni, evaluateFunction as nn, MissingOnValueCheckError as nr, TrustStore as nt, buildSoftMaskGroupExtGState as o, MdpPermission as oa, webpToJpeg as oi, reconstructParagraphs as on, RichTextFieldReadError as or, checkCertificateStatus as ot, registerEmbeddedFile as p, parseExistingTrailer as pa, analyzeJpegMarkers as pi, DEFAULT_SARIF_TOOL_NAME as pn, toAlpha as pr, setFieldVisibility as pt, normalizeComponentDepth as q, buildXmpMetadata as qa, computeObjectHash as qi, EncryptedPdfError as qn, itfToOperators as qr, buildPdfX6OutputIntent as qt, buildColorKeyMask as r, buildFieldLockDict as ra, embedTiffDirect as ri, markdownToPdf as rn, NoSuchFieldError as rr, downloadCrl as rt, buildSoftMaskNone as s, buildDocMdpReference as sa, webpToPng as si, DEFAULT_DOC_TIMESTAMP_CONTENTS_SIZE as sn, StreamingParseError as sr, extractOcspUrl as st, initWasm as t, diffSignedContent as ta, PdfWorker as ti, nameHalftone as tn, saveIncremental as to, InvalidPageSizeError as tr, verifySignatureDetailed as tt, attachOutputIntents as u, validateSignatureChain as ua, isCmykTiff as ui, buildCalRGB as un, applyHeaderFooterToPage as ur, resolveFieldReference as ut, applyOcr as v, requestTimestamp as va, applyRedaction as vi, PDF2_NAMESPACE as vn, shrinkFontSize as vr, parseAcrobatDate as vt, renderDisplayListToCanvas as w, PdfInkAnnotation as wa, buildAfArray as wi, buildDPartRoot as wn, minimalPreset as wr, readWoffHeader as wt, extractFonts as x, PdfCaretAnnotation as xa, generatePdfAXmpBytes as xi, buildPieceInfo as xn, applyPreset as xr, decodeWoff as xt, compareImages as y, searchTextItems as ya, enforcePdfAFull as yi, buildNamespace as yn, truncateText as yr, AFNumber_Format as yt, layoutColumns as z, generateInkAppearance as za, detectTransparency as zi, getBookmarks as zn, encodeUpcA as zr, buildFunctionShading as zt };
 
-//# sourceMappingURL=src-Ci9ZjqhP.mjs.map
+//# sourceMappingURL=src-s9zNsZAT.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modern-pdf-lib",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "A modern, WASM-accelerated PDF engine to create, parse, extract, fill, merge, and sign PDFs in every JavaScript runtime",
   "type": "module",
   "exports": {