pdfnative 1.3.0 → 1.4.0

package/dist/index.d.cts

@@ -74,8 +74,26 @@ interface RadialGradientPaint {
     readonly stops: readonly ColorStop[];
     readonly extend: GradientExtend;
 }
+/**
+ * A sweep (conic/angular) gradient fill (COLR PaintSweepGradient).
+ *
+ * PDF has no native conic shading, so the renderer approximates it as a fan
+ * of flat-colour triangular wedges clipped to the glyph outline — pure path
+ * operators, no shading resource. Angles are in counter-clockwise degrees
+ * from the positive x-axis.
+ *
+ * @since 1.4.0
+ */
+interface SweepGradientPaint {
+    readonly kind: 'sweep';
+    readonly center: readonly [number, number];
+    readonly startAngle: number;
+    readonly endAngle: number;
+    readonly stops: readonly ColorStop[];
+    readonly extend: GradientExtend;
+}
 /** A paint used to fill a colour-glyph layer. */
-type ColorPaint = SolidPaint | LinearGradientPaint | RadialGradientPaint;
+type ColorPaint = SolidPaint | LinearGradientPaint | RadialGradientPaint | SweepGradientPaint;
 /** A single colour-glyph layer: a base outline filled by a paint. */
 interface ColorLayer {
     /** Glyph id of the base outline (in the font's `glyf` table). */
@@ -89,6 +107,17 @@ interface ColorLayer {
      * absent.
      */
     readonly transform?: readonly [number, number, number, number, number, number];
+    /**
+     * Optional PDF blend mode name (`/BM`) for this layer, flattened from a
+     * COLRv1 `PaintComposite` whose composite mode maps to a separable or
+     * non-separable PDF blend mode (e.g. `Multiply`, `Screen`, `Overlay`,
+     * `Darken`, `Lighten`, `Difference`, `Hue`, `Luminosity`). Absent =
+     * `Normal`. Porter-Duff structural modes (Clear/Src/Dest/Xor) are not
+     * mapped — those glyphs fall back to the monochrome font instead.
+     *
+     * @since 1.4.0
+     */
+    readonly blendMode?: string;
 }
 /** A resolved colour glyph: ordered layers painted back-to-front. */
 interface ColorGlyph {
@@ -265,6 +294,14 @@ interface ColumnDef {
      * @since 1.2.0
      */
     readonly kind?: 'amount';
+    /**
+     * Vertical alignment of this column's cell content within the row band
+     * (`'top'` | `'middle'` | `'bottom'`). Overrides the table-level
+     * `TableBlock.cellVAlign`. When omitted, the historic baseline placement is
+     * preserved (byte-identical to pre-1.4.0).
+     * @since 1.4.0
+     */
+    readonly vAlign?: 'top' | 'middle' | 'bottom';
 }
 /**
  * Options for generating a PDF in a Web Worker via `generatePDFInWorker()`.
@@ -439,6 +476,67 @@ interface PdfLayoutOptions {
      * @since 1.3.0
      */
     readonly creationDate?: Date;
+    /**
+     * How a conforming viewer should present the document when it is first
+     * opened: initial page layout, page mode (bookmark/thumbnail panel, full
+     * screen…), window fit/centering, UI-chrome visibility, and whether the
+     * window title shows the document title. Maps to catalog `/PageLayout`,
+     * `/PageMode`, and the `/ViewerPreferences` dictionary (ISO 32000-1 §12.2).
+     *
+     * Purely presentational, PDF/A-safe, and fully optional. When the document
+     * also has an outline, an explicit `pageMode` here overrides the outline's
+     * default `/UseOutlines`.
+     *
+     * Default: `undefined` (viewer default presentation).
+     *
+     * @since 1.4.0
+     */
+    readonly viewerPreferences?: ViewerPreferences;
+}
+/**
+ * Viewer presentation preferences (ISO 32000-1 §12.2, Table 150 + §7.7.2).
+ * Every field is optional; omitted fields leave the viewer's default behaviour
+ * unchanged. Purely presentational and PDF/A-safe.
+ *
+ * @since 1.4.0
+ */
+interface ViewerPreferences {
+    /**
+     * Initial page layout (catalog `/PageLayout`):
+     * - `'singlePage'`: one page at a time
+     * - `'oneColumn'`: continuous single column
+     * - `'twoColumnLeft'` / `'twoColumnRight'`: continuous two columns, odd pages on the left/right
+     * - `'twoPageLeft'` / `'twoPageRight'`: two pages at a time, odd pages on the left/right
+     */
+    readonly pageLayout?: 'singlePage' | 'oneColumn' | 'twoColumnLeft' | 'twoColumnRight' | 'twoPageLeft' | 'twoPageRight';
+    /**
+     * Initial page mode (catalog `/PageMode`):
+     * - `'useNone'`: neither bookmarks nor thumbnails visible
+     * - `'useOutlines'`: bookmark panel open
+     * - `'useThumbs'`: thumbnail panel open
+     * - `'fullScreen'`: full-screen, no menu/panel
+     * - `'useOC'`: optional-content (layers) panel
+     * - `'useAttachments'`: attachments panel
+     */
+    readonly pageMode?: 'useNone' | 'useOutlines' | 'useThumbs' | 'fullScreen' | 'useOC' | 'useAttachments';
+    /** Hide the viewer's tool bars. */
+    readonly hideToolbar?: boolean;
+    /** Hide the viewer's menu bar. */
+    readonly hideMenubar?: boolean;
+    /** Hide UI elements (scrollbars, navigation controls), leaving only the page. */
+    readonly hideWindowUI?: boolean;
+    /** Resize the document window to fit the first displayed page. */
+    readonly fitWindow?: boolean;
+    /** Centre the document window on the screen. */
+    readonly centerWindow?: boolean;
+    /** Show the document title (from `/Info /Title`) in the window title bar. */
+    readonly displayDocTitle?: boolean;
+    /** Page mode to use when exiting full-screen (`/NonFullScreenPageMode`). */
+    readonly nonFullScreenPageMode?: 'useNone' | 'useOutlines' | 'useThumbs' | 'useOC';
+    /** Predominant reading order: left-to-right (default) or right-to-left. */
+    readonly direction?: 'l2r' | 'r2l';
+    /** Page-scaling default for the Print dialog (`/PrintScaling`). */
+    readonly printScaling?: 'none' | 'appDefault';
 }
 /**
  * Relationship of an embedded file to the PDF document (ISO 19005-3 §6.8).
@@ -892,6 +990,31 @@ declare function buildAppearanceStreamDict(w: number, h: number, streamLength: n
  */
 declare function buildRadioGroupParent(name: string, selectedValue: string, childObjNums: readonly number[], readOnly: boolean, required: boolean): string;
 
+/**
+ * pdfnative — Page Labels (ISO 32000-1 §12.4.2)
+ * ==============================================
+ * Builds the `/PageLabels` number tree placed in the document catalog.
+ * Page labels control the page numbering shown in a viewer's page-number
+ * box and thumbnails (e.g. roman-numeral front matter `i, ii, iii`,
+ * decimal body `1, 2, 3`, prefixed appendices `A-1, A-2`).
+ *
+ * The builder is **pure** and emits an inline dictionary string — page
+ * labels require no indirect objects. Output is PDF/A-safe.
+ */
+/** Page-numbering style for a {@link PageLabelRange}. */
+type PageLabelStyle = 'decimal' | 'roman' | 'Roman' | 'alpha' | 'Alpha' | 'none';
+/** A contiguous run of pages sharing a numbering scheme. */
+interface PageLabelRange {
+    /** 0-based index of the first page in this range. */
+    readonly startPage: number;
+    /** Numbering style. Omit or use `'none'` for prefix-only labels. */
+    readonly style?: PageLabelStyle;
+    /** Optional label prefix (e.g. `'A-'`). */
+    readonly prefix?: string;
+    /** First numeric value in the range (default `1`). */
+    readonly start?: number;
+}
+
 /**
  * pdfnative — Document Content Model Types
  * ==========================================
@@ -1007,14 +1130,77 @@ interface TableBlock {
      * @since 1.2.0
      */
     readonly cellPadding?: number;
+    /**
+     * Draw borders around each header/data cell. When omitted, no cell borders
+     * are drawn (byte-identical to pre-1.4.0 — the table keeps only its header
+     * underline and row separators). See {@link CellBorders}.
+     *
+     * @since 1.4.0
+     */
+    readonly cellBorders?: CellBorders;
+    /**
+     * Vertical alignment of cell content within the row band: `'top'`,
+     * `'middle'`, or `'bottom'`. A per-column {@link ColumnDef.vAlign} overrides
+     * this. When omitted, the historic baseline placement is preserved exactly
+     * (byte-identical to pre-1.4.0).
+     *
+     * @since 1.4.0
+     */
+    readonly cellVAlign?: 'top' | 'middle' | 'bottom';
+}
+/**
+ * Per-cell border configuration for a {@link TableBlock}. All sides are off by
+ * default; enable individual sides or use `all: true`. Pure vector strokes
+ * (`re`/`l`/`S`), so output stays PDF/A-safe.
+ *
+ * @since 1.4.0
+ */
+interface CellBorders {
+    /** Draw the top edge of each cell. */
+    readonly top?: boolean;
+    /** Draw the right edge of each cell. */
+    readonly right?: boolean;
+    /** Draw the bottom edge of each cell. */
+    readonly bottom?: boolean;
+    /** Draw the left edge of each cell. */
+    readonly left?: boolean;
+    /** Draw all four edges (shorthand; overrides the individual side flags). */
+    readonly all?: boolean;
+    /** Stroke colour. Default: `'0.8 0.8 0.8'` (light grey). */
+    readonly color?: PdfColor;
+    /** Stroke width in points. Default: `0.5`. */
+    readonly width?: number;
+    /** Stroke style. Default: `'solid'`. */
+    readonly style?: 'solid' | 'dashed' | 'dotted';
 }
 /** List block — bullet or numbered items. */
 interface ListBlock {
     readonly type: 'list';
-    readonly items: readonly string[];
+    /**
+     * List entries. Each entry is either a plain string (leaf item) or a
+     * {@link ListItem} object that can carry its own nested sub-list, enabling
+     * hierarchical (multi-level) bullet/numbered lists. Plain strings and
+     * nested objects may be freely mixed. Passing only strings is byte-identical
+     * to the pre-1.4.0 flat-list behaviour.
+     */
+    readonly items: readonly (string | ListItem)[];
     readonly style: 'bullet' | 'numbered';
     readonly fontSize?: number;
 }
+/**
+ * A single hierarchical list entry: text plus an optional nested sub-list.
+ * Used by {@link ListBlock} to build multi-level outlines (bullets within
+ * bullets, numbered sub-items, …). Sub-items inherit the parent list's
+ * `style`; numbered sub-lists restart their numbering at 1.
+ *
+ * @since 1.4.0
+ */
+interface ListItem {
+    /** The item's text content. */
+    readonly text: string;
+    /** Optional nested child entries (recursive). */
+    readonly items?: readonly (string | ListItem)[];
+}
 /** Spacer block — vertical whitespace. */
 interface SpacerBlock {
     readonly type: 'spacer';
@@ -1131,6 +1317,38 @@ interface DocumentMetadata {
     readonly subject?: string;
     readonly keywords?: string;
 }
+/**
+ * A document outline (bookmark) entry — ISO 32000-1 §12.3.3.
+ *
+ * Outline items form a navigable tree shown in a viewer's bookmarks
+ * panel. Each item points at a 0-based page index and may nest children.
+ * Bookmarks are purely navigational and PDF/A-safe.
+ *
+ * @since 1.4.0
+ */
+interface OutlineItem {
+    /** Bookmark label (UTF-16BE encoded automatically). */
+    readonly title: string;
+    /** 0-based destination page index. */
+    readonly pageIndex: number;
+    /** Destination Y coordinate in points (default: top of page). */
+    readonly y?: number;
+    /** Render the label bold (`/F` flag bit 2). */
+    readonly bold?: boolean;
+    /** Render the label italic (`/F` flag bit 1). */
+    readonly italic?: boolean;
+    /** Label colour (`/C`). Accepts hex, RGB tuple, or PDF operator string. */
+    readonly color?: PdfColor;
+    /**
+     * Initial expansion state. `true` (default) renders the bookmark expanded
+     * (positive `/Count`); `false` renders it collapsed (negative `/Count`),
+     * hiding its children until the reader expands it. Only meaningful when the
+     * item has `children`.
+     */
+    readonly open?: boolean;
+    /** Nested child bookmarks. */
+    readonly children?: readonly OutlineItem[];
+}
 /**
  * Parameters for the free-form document PDF builder.
  *
@@ -1154,6 +1372,26 @@ interface DocumentParams {
     readonly fontEntries?: readonly FontEntry[];
     readonly metadata?: DocumentMetadata;
     readonly layout?: Partial<PdfLayoutOptions>;
+    /**
+     * Document outline / bookmarks (ISO 32000-1 §12.3.3).
+     *
+     * - An array of {@link OutlineItem}s builds an explicit bookmark tree.
+     * - The literal `'auto'` derives a flat outline from every `heading`
+     *   block in document order, using each heading's page and position.
+     *
+     * Adds `/Outlines` + `/PageMode /UseOutlines` to the catalog. PDF/A-safe.
+     *
+     * @since 1.4.0
+     */
+    readonly outline?: readonly OutlineItem[] | 'auto';
+    /**
+     * Page labels (ISO 32000-1 §12.4.2) — controls the page numbering shown
+     * in a viewer's page box and thumbnails (e.g. roman front matter then
+     * decimal body). Emitted as an inline `/PageLabels` number tree. PDF/A-safe.
+     *
+     * @since 1.4.0
+     */
+    readonly pageLabels?: readonly PageLabelRange[];
 }
 
 /**
@@ -1808,6 +2046,83 @@ declare function verifyCertSignature(cert: X509Certificate, issuerCert: X509Cert
  */
 declare function isSelfSigned(cert: X509Certificate): boolean;
 
+/**
+ * pdfnative — Pluggable Signature Crypto Provider
+ * ================================================
+ * pdfnative ships its own pure-TypeScript RSA (PKCS#1 v1.5) and ECDSA (P-256)
+ * implementations so that signing works in any runtime with **zero
+ * dependencies**. Those pure-JS primitives are built on JavaScript `BigInt`
+ * arithmetic, which V8/SpiderMonkey do **not** execute in constant time — see
+ * the timing-side-channel caveat in `SECURITY.md`.
+ *
+ * For high-security, high-frequency server pipelines (a backend signing many
+ * PDFs/s with one key under adversarial timing observation), this module lets
+ * you inject a hardware-backed, **constant-time** signer — Node.js
+ * `node:crypto` or a Web Crypto wrapper — without giving up the zero-dependency
+ * default. The pure-JS path remains the fallback when no provider is set.
+ *
+ * The provider produces the raw CMS signature value over the **DER-encoded
+ * signed attributes** (`tbs`, "to be signed"), matching the requested
+ * algorithm:
+ *  - `'rsa-sha256'`  → RSASSA-PKCS1-v1_5 signature over `SHA-256(tbs)`.
+ *  - `'ecdsa-sha256'`→ a **DER-encoded** ECDSA (P-256) signature over
+ *    `SHA-256(tbs)` (i.e. `SEQUENCE { r INTEGER, s INTEGER }`).
+ *
+ * @example Node.js `node:crypto` (constant-time, hardware-backed)
+ * ```ts
+ * import { setCryptoProvider } from 'pdfnative';
+ * import { createSign, createPrivateKey } from 'node:crypto';
+ *
+ * const key = createPrivateKey(pemPrivateKey);
+ * setCryptoProvider({
+ *   sign(tbs, algorithm) {
+ *     // node:crypto hashes `tbs` internally and returns a DER ECDSA sig.
+ *     return new Uint8Array(createSign('sha256').update(tbs).sign(key));
+ *   },
+ * });
+ * ```
+ *
+ * @since 1.4.0
+ */
+
+/**
+ * A pluggable signer that replaces pdfnative's pure-JS RSA/ECDSA math with a
+ * native, constant-time implementation.
+ */
+interface CryptoProvider {
+    /**
+     * Sign the DER-encoded CMS SignedAttributes (`tbs`) and return the raw
+     * signature value to embed in the CMS `SignerInfo`.
+     *
+     * The implementation MUST hash `tbs` with SHA-256 internally (native
+     * `crypto.sign('sha256', …)` does this for you) and produce a signature
+     * matching `algorithm`:
+     *  - `'rsa-sha256'`   → RSASSA-PKCS1-v1_5 over `SHA-256(tbs)`.
+     *  - `'ecdsa-sha256'` → DER-encoded ECDSA-P256 over `SHA-256(tbs)`.
+     */
+    readonly sign: (tbs: Uint8Array, algorithm: SignatureAlgorithm) => Uint8Array;
+}
+/**
+ * Install (or clear) a global signature {@link CryptoProvider}. When set, every
+ * `signPdfBytes()` call that does not pass an explicit per-call provider routes
+ * its signature math through `provider` instead of pdfnative's pure-JS RSA/ECDSA
+ * primitives. Pass `null` to restore the zero-dependency default.
+ *
+ * A per-call `PdfSignOptions.provider` always takes precedence over the global
+ * one set here.
+ *
+ * @param provider The native signer, or `null` to revert to pure-JS.
+ * @since 1.4.0
+ */
+declare function setCryptoProvider(provider: CryptoProvider | null): void;
+/**
+ * The currently-installed global {@link CryptoProvider}, or `null` if none.
+ * Primarily for internal dispatch and testing.
+ *
+ * @since 1.4.0
+ */
+declare function getCryptoProvider(): CryptoProvider | null;
+
 /**
  * pdfnative — CMS SignedData Builder (RFC 5652)
  * ==============================================
@@ -1832,6 +2147,14 @@ interface CmsSignOptions {
     readonly signingTime?: Date;
     /** Signature algorithm. */
     readonly algorithm: SignatureAlgorithm;
+    /**
+     * Optional native signer. When supplied (or when a global provider is set
+     * via {@link setCryptoProvider}), the signature value is produced by the
+     * provider instead of the pure-JS RSA/ECDSA primitives, and `rsaKey` /
+     * `ecKey` are not required.
+     * @since 1.4.0
+     */
+    readonly provider?: CryptoProvider;
 }
 /**
  * Build a CMS SignedData structure for a PDF detached signature.
@@ -1895,6 +2218,15 @@ interface PdfSignOptions extends SigDictMetadata {
     readonly ecKey?: EcPrivateKey;
     /** Algorithm to use. Default: 'rsa-sha256'. */
     readonly algorithm?: SignatureAlgorithm;
+    /**
+     * Optional native signature provider (e.g. `node:crypto` / Web Crypto). When
+     * set — or when a global provider is installed via {@link setCryptoProvider}
+     * — the constant-time native signer replaces pdfnative's pure-JS RSA/ECDSA
+     * math, and `rsaKey` / `ecKey` become optional. A per-call provider takes
+     * precedence over the global one.
+     * @since 1.4.0
+     */
+    readonly provider?: CryptoProvider;
 }
 /**
  * Build a /Sig signature dictionary string for embedding in a PDF.
@@ -2179,6 +2511,37 @@ declare function concatChunks(chunks: readonly Uint8Array[]): Uint8Array;
  * @returns Total byte count
  */
 declare function streamByteLength(stream: AsyncGenerator<Uint8Array>): Promise<number>;
+/** Result of {@link streamToFile}. */
+interface StreamToFileResult {
+    /** Total number of bytes written to the file. */
+    readonly bytesWritten: number;
+    /** The path the stream was written to. */
+    readonly path: string;
+}
+/**
+ * Write a streaming PDF (any of the `streamPdf`/`buildPDFStream*` generators)
+ * directly to a file on disk in **constant memory**, honouring write
+ * back-pressure. Node.js-only convenience wrapper.
+ *
+ * The dependency on `node:fs` is loaded **dynamically** so this module stays
+ * tree-shakeable and bundler-safe for the browser; calling `streamToFile` in
+ * a non-Node environment throws a descriptive error.
+ *
+ * @example
+ * ```ts
+ * await streamToFile(streamDocumentPdf({ blocks }), './out.pdf');
+ * ```
+ *
+ * @param stream   An async generator of PDF byte chunks.
+ * @param filePath Destination path. The caller is responsible for validating
+ *                 untrusted paths (path traversal, allowed directories).
+ * @param opts     Optional `AbortSignal` to cancel mid-write.
+ * @returns Bytes written and the destination path.
+ * @since 1.4.0
+ */
+declare function streamToFile(stream: AsyncGenerator<Uint8Array>, filePath: string, opts?: {
+    readonly signal?: AbortSignal;
+}): Promise<StreamToFileResult>;
 
 /**
  * pdfnative — SHA-384, SHA-512, HMAC-SHA256
@@ -2498,6 +2861,47 @@ declare function clearFontCache(): void;
  */
 declare function resetFontRegistry(): void;
 
+/**
+ * pdfnative — Font Data Validator
+ * ================================
+ * `validateFontData()` performs a read-only structural sanity check on a
+ * {@link FontData} module before it is used for rendering. The bundled font
+ * modules under `pdfnative/fonts/*` are already trusted; this validator exists
+ * for consumers who **build their own** font data (via `tools/build-font-data.cjs`
+ * or by hand) from an untrusted or unfamiliar TTF/OTF.
+ *
+ * It catches the common failure modes — a corrupt/empty base64 payload, a
+ * non-SFNT binary, an empty `cmap`, glyph ids that point outside the metrics,
+ * a malformed `pdfWidthArray`, or non-finite metrics — and reports them as
+ * descriptive errors instead of letting a cryptic `.notdef`/`NaN` failure
+ * surface deep inside the encoding/subsetting pipeline.
+ *
+ * The check is **opt-in and standalone**: it is NOT invoked automatically by
+ * `registerFont()` (that would add cost to every load and risks false-rejecting
+ * edge-valid fonts). Call it yourself when ingesting third-party font data.
+ *
+ * @since 1.4.0
+ */
+/** Result of {@link validateFontData}. */
+interface FontValidationResult {
+    /** True when no blocking errors were found. */
+    readonly valid: boolean;
+    /** Blocking structural problems that would break rendering. */
+    readonly errors: readonly string[];
+    /** Non-blocking concerns (suspicious but not necessarily fatal). */
+    readonly warnings: readonly string[];
+}
+/**
+ * Structurally validate a {@link FontData} module. Returns `{ valid, errors,
+ * warnings }`; `valid` is `false` when any blocking problem is found. Does not
+ * throw on malformed input — it reports.
+ *
+ * @param data The font data to validate (typically the default export of a
+ *             generated `*-data.js` module).
+ * @since 1.4.0
+ */
+declare function validateFontData(data: unknown): FontValidationResult;
+
 /**
  * pdfnative — Thai Mini-Shaper
  * =============================
@@ -3183,13 +3587,15 @@ declare function extractGlyphContours(font: GlyfFont, gid: number, depth?: numbe
  * Supported:
  *   - COLR v0 — layered solid fills.
  *   - COLR v1 — PaintColrLayers, PaintGlyph, PaintColrGlyph, PaintSolid,
- *     PaintLinearGradient, PaintRadialGradient, PaintTransform,
- *     PaintTranslate, PaintScale (+ around-center).
+ *     PaintLinearGradient, PaintRadialGradient, PaintSweepGradient,
+ *     PaintTransform, PaintTranslate, PaintScale (+ around-center),
+ *     PaintComposite (blend-mode-mappable composite modes).
  *
- * Unsupported paints (sweep gradients, compositing, variable paints) cause
- * the affected glyph to be skipped so the caller can fall back to the
- * monochrome emoji font. This keeps output correct (never garbled) while
- * covering the overwhelming majority of Noto Color Emoji glyphs.
+ * Unsupported paints (variable paints, Porter-Duff structural composite
+ * modes Clear/Src/Dest/Xor/…) cause the affected glyph to be skipped so the
+ * caller can fall back to the monochrome emoji font. This keeps output
+ * correct (never garbled) while covering the overwhelming majority of
+ * Noto Color Emoji glyphs.
  *
  * Zero external dependency.
  *
@@ -3222,6 +3628,10 @@ declare function parseColrCpal(bytes: Uint8Array): Record<number, ColorGlyph> |
  *   - Linear gradients → `/Shading` Type 2 (axial) painted via `sh`,
  *     clipped to the glyph outline.
  *   - Radial gradients → `/Shading` Type 3, likewise.
+ *   - Sweep (conic) gradients → a fan of flat-colour triangular wedges
+ *     clipped to the outline (PDF has no native conic shading). (v1.4.0)
+ *   - Per-layer blend modes (`/BM`, from COLRv1 `PaintComposite`) via an
+ *     ExtGState applied around the layer's fill. (v1.4.0)
  *
  * The Form XObject's user space is font units; the caller scales it onto the
  * page with a `cm` and draws it with `Do`.
@@ -3565,6 +3975,99 @@ interface PdfModifier {
  */
 declare function createModifier(reader: PdfReader): PdfModifier;
 
+/**
+ * pdfnative — Page-Tree Manipulation API (ISO 32000-1 §7.7.3)
+ * ============================================================
+ * Safe, **faithful** page-level document assembly: merge, split, and
+ * extract pages across PDF documents.
+ *
+ * Unlike the incremental modifier (`createModifier`), these operations
+ * **rebuild** a brand-new document from scratch: every kept page and its
+ * transitive object graph (`/Contents`, `/Resources`, fonts, XObjects,
+ * ExtGState, …) is deep-copied into a fresh, contiguous object-number
+ * space, then wired into a new flat `/Pages` tree, `/Catalog`, xref, and
+ * trailer. This avoids production-unsafe in-place surgery (relocating
+ * `/Kids`, rewriting `/Parent` chains, merging resource pools).
+ *
+ * Safety guarantees (documented behaviour):
+ *  - **Encrypted sources are rejected** (no Standard Security Handler
+ *    writer yet) — throws.
+ *  - **Signatures are always removed** — any page-tree edit invalidates a
+ *    document signature's `/ByteRange`, so signature/Widget annotations and
+ *    the `/AcroForm` are dropped. The `dropSignatures` flag is accepted for
+ *    API clarity but the behaviour is unconditional.
+ *  - **Annotations** default to URI-`/Link`-only (self-contained). Cross-page
+ *    GoTo links and form widgets are dropped to guarantee no dangling
+ *    references. `dropAnnotations: true` removes all annotations.
+ *  - Output is **not** claimed to be PDF/A — merged OutputIntents / XMP
+ *    cannot be reconciled safely.
+ *
+ * @since 1.4.0
+ */
+/** A contiguous, inclusive page range (0-based). */
+interface PageRange {
+    /** First page index (0-based, inclusive). */
+    readonly start: number;
+    /** Last page index (0-based, inclusive). Defaults to `start`. */
+    readonly end?: number;
+}
+/**
+ * Options for the page-tree manipulation API ({@link mergePdfs},
+ * {@link splitPdf}, {@link extractPages}).
+ */
+interface MergeOptions {
+    /**
+     * Drop signature fields/widgets. Accepted for clarity; merging always
+     * removes signatures because the operation invalidates `/ByteRange`.
+     */
+    readonly dropSignatures?: boolean;
+    /** Drop **all** annotations (default keeps self-contained URI links). */
+    readonly dropAnnotations?: boolean;
+    /**
+     * Maximum size, in bytes, of the assembled output document. The operation
+     * throws as soon as the copied object graph would exceed this limit — even
+     * mid-copy, before a multi-gigabyte stream is materialised — so a malicious
+     * or accidentally huge source cannot exhaust process memory.
+     *
+     * Defaults to `268435456` (256 MiB). Pass `Infinity` to disable the guard
+     * (not recommended for untrusted input).
+     *
+     * @defaultValue 268435456 (256 MiB)
+     */
+    readonly maxOutputSize?: number;
+}
+/**
+ * Concatenate multiple PDF documents into one, preserving page order.
+ *
+ * @param sources 1–50 PDF byte arrays.
+ * @param opts    See {@link MergeOptions}.
+ * @returns A new, self-contained PDF.
+ * @throws If `sources` is empty/too large, or any source is encrypted.
+ */
+declare function mergePdfs(sources: readonly Uint8Array[], opts?: MergeOptions): Uint8Array;
+/**
+ * Extract a subset of pages from a single document into a new PDF.
+ * Indices may repeat and need not be ordered — output follows the given order.
+ *
+ * @param src         Source PDF bytes.
+ * @param pageIndices 0-based page indices to keep.
+ * @param opts        See {@link MergeOptions} (e.g. `maxOutputSize`,
+ *                    `dropAnnotations`).
+ * @throws If `src` is encrypted, indices is empty, or an index is out of range.
+ */
+declare function extractPages(src: Uint8Array, pageIndices: readonly number[], opts?: MergeOptions): Uint8Array;
+/**
+ * Split a document into multiple PDFs, one per page range.
+ *
+ * @param src    Source PDF bytes.
+ * @param ranges Inclusive 0-based page ranges.
+ * @param opts   See {@link MergeOptions} (e.g. `maxOutputSize`,
+ *               `dropAnnotations`); applied to every emitted document.
+ * @returns One PDF per range, in order.
+ * @throws If `src` is encrypted, ranges is empty, or a range is invalid.
+ */
+declare function splitPdf(src: Uint8Array, ranges: readonly PageRange[], opts?: MergeOptions): Uint8Array[];
+
 /**
  * pdfnative — PDF/UA structural validator (ISO 14289-1)
  * ======================================================
@@ -3750,4 +4253,4 @@ declare function createPDF(pdfParams: PdfParams, options?: {
     layoutOptions?: Partial<PdfLayoutOptions>;
 }): Promise<Uint8Array>;
 
-export { type AddSignaturePlaceholderOptions, type Annotation, type Asn1Node, BAL_H, type BarcodeBlock, type BarcodeFormat, type BidiRun, type CmsSignOptions, type ColorGlyph, type ColorGlyphForm, type ColorLayer, type ColorPaint, type ColorStop, type ColumnDef, type Contour, type CpalColor, DEFAULT_COLORS, DEFAULT_COLUMNS, DEFAULT_CW, DEFAULT_FONT_SIZES, DEFAULT_MARGINS, DEFAULT_MAX_BLOCKS, DEFAULT_MAX_INFLATE_OUTPUT, type DocumentBlock, type DocumentMetadata, type DocumentParams, type EcPrivateKey, type EcPublicKey, type EmbeddedFilesResult, type EncodingContext, type EncryptionOptions, FT_H, type FontData, type FontEntry, type FontLoader, type FontMetrics, type FontRun, type FormField, type FormFieldBlock, type FormFieldType, type FormWidgetResult, type GlyfFont, type GradientExtend, HEADER_H, type HeadingBlock, INFO_LN, type ImageBlock, type InternalLink, KNOWN_DECODE_FILTERS, type LinearGradientPaint, type LinkAnnotation, type LinkBlock, type ListBlock, MAX_PARSE_DEPTH, MAX_XREF_CHAIN, type OutlinePoint, type OutlineProvider, PAGE_SIZES, PDF_A_CONFORMANCE_TARGETS, PG_H, PG_W, type PageBreakBlock, type PageTemplate, type ParagraphBlock, type PdfArray as ParsedArray, type PdfDict as ParsedDict, type ParsedImage, type PdfAConfig, type PdfAConformanceTarget, type PdfAttachment, type PdfAttachmentRelationship, type PdfColor, type PdfColors, type PdfIndirectObject, type PdfInfoItem, type PdfLayoutOptions, type PdfModifier, type PdfName, type PdfParams, type PdfReader, type PdfRef, type PdfRgbString, type PdfRgbTuple, type PdfRow, type PdfSignOptions, type PdfStream, type PdfToken, type PdfTokenizer, type PdfUAValidationResult, type PdfValue, type QRErrorLevel, ROW_H, type RadialGradientPaint, type RadioGroupContext, type RsaPrivateKey, type RsaPublicKey, type ShapedGlyph, type SigDictMetadata, type SignatureAlgorithm, type SolidPaint, type SpacerBlock, type StreamOptions, type SvgBlock, type SvgRenderOptions, type SvgSegment, TH_H, TITLE_LN, type TableBlock, type TextRun, type TocBlock, type TokenType, type UseCategory, type UseClassifiedCp, type UseCluster, WORKER_THRESHOLD, WORKER_TIMEOUT_MS, type WatermarkImage, type WatermarkOptions, type WatermarkState, type WatermarkText, type WorkerGenerationOptions, type WorkerInputMessage, type WorkerOutputMessage, type X509Certificate, type X509Name, type XrefEntry, type XrefTable, addSignaturePlaceholder, applyDecodeFilter, buildAcroFormDict, buildAppearanceStreamDict, buildCmsSignedData, buildDocumentPDF, buildDocumentPDFBytes, buildDocumentPDFStream, buildDocumentPDFStreamPageByPage, buildDocumentPDFStreamTrue, buildEmbeddedFiles, buildFormWidget, buildImageOperators, buildImageXObject, buildInternalLinkAnnotation, buildLinkAnnotation, buildPDF, buildPDFBytes, buildPDFStream, buildPDFStreamPageByPage, buildPDFStreamTrue, buildRadioGroupParent, buildSMaskXObject, buildSigDict, buildWatermarkState, chunkBinaryString, classifyClusters, classifyUseCategory, clearFontCache, computeColumnPositions, concatChunks, containsArabic, containsBengali, containsDevanagari, containsEthiopic, containsHebrew, containsKhmer, containsMyanmar, containsRTL, containsSinhala, containsTamil, containsTelugu, containsThai, containsTibetan, contoursToPath, createEncodingContext, createModifier, createPDF, createTokenizer, decodeASCII85, decodeASCIIHex, decodeEcPublicKey, decodeLZW, decodeRunLength, defaultFieldHeight, derBitString, derDecode, derInteger, derOctetString, derOid, derSequence, detectCharLang, detectFallbackLangs, detectImageFormat, dictGet, dictGetArray, dictGetDict, dictGetName, dictGetNum, dictGetRef, downloadBlob, ean13CheckDigit, ecPublicKeyFromPrivate, ecdsaSign, ecdsaVerify, encodeCode128, encodeEcPublicKey, encodePDF417, encodePdfTextString, estimateCmsSize, estimateContentsSize, extractGlyphContours, findStartxref, generateDataMatrix, generatePDFInWorker, generatePDFMainThread, generateQR, getMaxInflateOutputSize, getRegisteredLangs, getTrailerRef, getTrailerValue, hasFontLoader, helveticaBoldWidth, helveticaWidth, hmacSha256, inflateSync, initCrypto, initNodeCompression, initNodeDecompression as initNodeDecompression_parser, isArmenianCodepoint, isArray, isBengaliCodepoint, isCyrillicCodepoint, isDevanagariCodepoint, isDict, isEthiopicCodepoint, isGeorgianCodepoint, isKhmerCodepoint, isLinkAnnotation, isMyanmarCodepoint, isName, isRef, isSelfSigned, isSinhalaCodepoint, isStream, isTamilCodepoint, isTeluguCodepoint, isTibetanCodepoint, isValidPdfRgb, loadFontData, nameValue, needsUnicodeFont, normalizeBidiEmbeddings, normalizeColors, openPdf, parseCertificate, parseColor, parseColrCpal, parseCpal, parseGlyfFont, parseImage, parseIndirectObject, parseJPEG, parsePNG, parseRsaPrivateKey, parseRsaPublicKey, parseSvgPath, parseValue, parseXrefTable, pdfString, registerFont, registerFonts, renderBarcode, renderCode128, renderColorGlyph, renderDataMatrix, renderEAN13, renderPDF417, renderQR, renderSvg, resetFontRegistry, resolveBidiRuns, resolveLayout, resolvePdfAConfig, resolveTemplate, rsaSign, rsaSignHash, rsaVerify, rsaVerifyHash, setDeflateImpl, setInflateImpl, setMaxInflateOutputSize, sha384, sha512, shapeArabicText, shapeBengaliText, shapeDevanagariText, shapeKhmerText, shapeMyanmarText, shapeSinhalaText, shapeTamilText, shapeTeluguText, shapeThaiText, shapeTibetanText, signPdfBytes, slugify, splitTextByFont, streamByteLength, stripBidiControls, toBytes, toWinAnsi, truncate, truncateToWidth, validateAttachments, validateDocumentStreamable, validatePdfUA, validateTableStreamable, validateURL, validateWatermark, verifyCertSignature, wrapText };
+export { type AddSignaturePlaceholderOptions, type Annotation, type Asn1Node, BAL_H, type BarcodeBlock, type BarcodeFormat, type BidiRun, type CellBorders, type CmsSignOptions, type ColorGlyph, type ColorGlyphForm, type ColorLayer, type ColorPaint, type ColorStop, type ColumnDef, type Contour, type CpalColor, type CryptoProvider, DEFAULT_COLORS, DEFAULT_COLUMNS, DEFAULT_CW, DEFAULT_FONT_SIZES, DEFAULT_MARGINS, DEFAULT_MAX_BLOCKS, DEFAULT_MAX_INFLATE_OUTPUT, type DocumentBlock, type DocumentMetadata, type DocumentParams, type EcPrivateKey, type EcPublicKey, type EmbeddedFilesResult, type EncodingContext, type EncryptionOptions, FT_H, type FontData, type FontEntry, type FontLoader, type FontMetrics, type FontRun, type FontValidationResult, type FormField, type FormFieldBlock, type FormFieldType, type FormWidgetResult, type GlyfFont, type GradientExtend, HEADER_H, type HeadingBlock, INFO_LN, type ImageBlock, type InternalLink, KNOWN_DECODE_FILTERS, type LinearGradientPaint, type LinkAnnotation, type LinkBlock, type ListBlock, type ListItem, MAX_PARSE_DEPTH, MAX_XREF_CHAIN, type MergeOptions, type OutlineItem, type OutlinePoint, type OutlineProvider, PAGE_SIZES, PDF_A_CONFORMANCE_TARGETS, PG_H, PG_W, type PageBreakBlock, type PageLabelRange, type PageLabelStyle, type PageRange, type PageTemplate, type ParagraphBlock, type PdfArray as ParsedArray, type PdfDict as ParsedDict, type ParsedImage, type PdfAConfig, type PdfAConformanceTarget, type PdfAttachment, type PdfAttachmentRelationship, type PdfColor, type PdfColors, type PdfIndirectObject, type PdfInfoItem, type PdfLayoutOptions, type PdfModifier, type PdfName, type PdfParams, type PdfReader, type PdfRef, type PdfRgbString, type PdfRgbTuple, type PdfRow, type PdfSignOptions, type PdfStream, type PdfToken, type PdfTokenizer, type PdfUAValidationResult, type PdfValue, type QRErrorLevel, ROW_H, type RadialGradientPaint, type RadioGroupContext, type RsaPrivateKey, type RsaPublicKey, type ShapedGlyph, type SigDictMetadata, type SignatureAlgorithm, type SolidPaint, type SpacerBlock, type StreamOptions, type StreamToFileResult, type SvgBlock, type SvgRenderOptions, type SvgSegment, TH_H, TITLE_LN, type TableBlock, type TextRun, type TocBlock, type TokenType, type UseCategory, type UseClassifiedCp, type UseCluster, type ViewerPreferences, WORKER_THRESHOLD, WORKER_TIMEOUT_MS, type WatermarkImage, type WatermarkOptions, type WatermarkState, type WatermarkText, type WorkerGenerationOptions, type WorkerInputMessage, type WorkerOutputMessage, type X509Certificate, type X509Name, type XrefEntry, type XrefTable, addSignaturePlaceholder, applyDecodeFilter, buildAcroFormDict, buildAppearanceStreamDict, buildCmsSignedData, buildDocumentPDF, buildDocumentPDFBytes, buildDocumentPDFStream, buildDocumentPDFStreamPageByPage, buildDocumentPDFStreamTrue, buildEmbeddedFiles, buildFormWidget, buildImageOperators, buildImageXObject, buildInternalLinkAnnotation, buildLinkAnnotation, buildPDF, buildPDFBytes, buildPDFStream, buildPDFStreamPageByPage, buildPDFStreamTrue, buildRadioGroupParent, buildSMaskXObject, buildSigDict, buildWatermarkState, chunkBinaryString, classifyClusters, classifyUseCategory, clearFontCache, computeColumnPositions, concatChunks, containsArabic, containsBengali, containsDevanagari, containsEthiopic, containsHebrew, containsKhmer, containsMyanmar, containsRTL, containsSinhala, containsTamil, containsTelugu, containsThai, containsTibetan, contoursToPath, createEncodingContext, createModifier, createPDF, createTokenizer, decodeASCII85, decodeASCIIHex, decodeEcPublicKey, decodeLZW, decodeRunLength, defaultFieldHeight, derBitString, derDecode, derInteger, derOctetString, derOid, derSequence, detectCharLang, detectFallbackLangs, detectImageFormat, dictGet, dictGetArray, dictGetDict, dictGetName, dictGetNum, dictGetRef, downloadBlob, ean13CheckDigit, ecPublicKeyFromPrivate, ecdsaSign, ecdsaVerify, encodeCode128, encodeEcPublicKey, encodePDF417, encodePdfTextString, estimateCmsSize, estimateContentsSize, extractGlyphContours, extractPages, findStartxref, generateDataMatrix, generatePDFInWorker, generatePDFMainThread, generateQR, getCryptoProvider, getMaxInflateOutputSize, getRegisteredLangs, getTrailerRef, getTrailerValue, hasFontLoader, helveticaBoldWidth, helveticaWidth, hmacSha256, inflateSync, initCrypto, initNodeCompression, initNodeDecompression as initNodeDecompression_parser, isArmenianCodepoint, isArray, isBengaliCodepoint, isCyrillicCodepoint, isDevanagariCodepoint, isDict, isEthiopicCodepoint, isGeorgianCodepoint, isKhmerCodepoint, isLinkAnnotation, isMyanmarCodepoint, isName, isRef, isSelfSigned, isSinhalaCodepoint, isStream, isTamilCodepoint, isTeluguCodepoint, isTibetanCodepoint, isValidPdfRgb, loadFontData, mergePdfs, nameValue, needsUnicodeFont, normalizeBidiEmbeddings, normalizeColors, openPdf, parseCertificate, parseColor, parseColrCpal, parseCpal, parseGlyfFont, parseImage, parseIndirectObject, parseJPEG, parsePNG, parseRsaPrivateKey, parseRsaPublicKey, parseSvgPath, parseValue, parseXrefTable, pdfString, registerFont, registerFonts, renderBarcode, renderCode128, renderColorGlyph, renderDataMatrix, renderEAN13, renderPDF417, renderQR, renderSvg, resetFontRegistry, resolveBidiRuns, resolveLayout, resolvePdfAConfig, resolveTemplate, rsaSign, rsaSignHash, rsaVerify, rsaVerifyHash, setCryptoProvider, setDeflateImpl, setInflateImpl, setMaxInflateOutputSize, sha384, sha512, shapeArabicText, shapeBengaliText, shapeDevanagariText, shapeKhmerText, shapeMyanmarText, shapeSinhalaText, shapeTamilText, shapeTeluguText, shapeThaiText, shapeTibetanText, signPdfBytes, slugify, splitPdf, splitTextByFont, streamByteLength, streamToFile, stripBidiControls, toBytes, toWinAnsi, truncate, truncateToWidth, validateAttachments, validateDocumentStreamable, validateFontData, validatePdfUA, validateTableStreamable, validateURL, validateWatermark, verifyCertSignature, wrapText };