pdfnative 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -33,6 +33,93 @@ interface FontData {
         readonly mark1Anchors: Record<number, Record<number, [number, number]>>;
         readonly mark2Classes: Record<number, [number, number, number]>;
     } | null;
+    /**
+     * Colour glyph table (COLR/CPAL), keyed by base glyph id. Present only
+     * for colour fonts such as Noto Color Emoji (opt-in via the
+     * `'emoji-color'` lang). Each entry is an ordered list of paint layers
+     * resolved against the font's CPAL palette (painter's algorithm).
+     * `undefined`/`null` for ordinary monochrome fonts. (v1.3.0)
+     */
+    readonly colorGlyphs?: Record<number, ColorGlyph> | null;
+}
+/** An sRGB colour with alpha, each channel 0–255. Resolved from CPAL. */
+type CpalColor = readonly [number, number, number, number];
+/** A gradient colour stop: `offset` in [0,1] with a resolved colour. */
+interface ColorStop {
+    readonly offset: number;
+    readonly color: CpalColor;
+}
+/** How a gradient extends beyond its [0,1] range (COLR Extend / PDF Extend). */
+type GradientExtend = 'pad' | 'repeat' | 'reflect';
+/** A flat colour fill (COLR PaintSolid / COLRv0 layer). */
+interface SolidPaint {
+    readonly kind: 'solid';
+    readonly color: CpalColor;
+}
+/** A linear (axial) gradient fill (COLR PaintLinearGradient → PDF Shading 2). */
+interface LinearGradientPaint {
+    readonly kind: 'linear';
+    readonly p0: readonly [number, number];
+    readonly p1: readonly [number, number];
+    readonly stops: readonly ColorStop[];
+    readonly extend: GradientExtend;
+}
+/** A radial gradient fill (COLR PaintRadialGradient → PDF Shading 3). */
+interface RadialGradientPaint {
+    readonly kind: 'radial';
+    readonly c0: readonly [number, number];
+    readonly r0: number;
+    readonly c1: readonly [number, number];
+    readonly r1: number;
+    readonly stops: readonly ColorStop[];
+    readonly extend: GradientExtend;
+}
+/** A paint used to fill a colour-glyph layer. */
+type ColorPaint = SolidPaint | LinearGradientPaint | RadialGradientPaint;
+/** 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). */
+    readonly glyphId: number;
+    /** The fill applied to the outline. */
+    readonly paint: ColorPaint;
+    /**
+     * Optional affine transform `[a b c d e f]` (font-unit space) applied to
+     * both the outline and the paint geometry of this layer — flattened from
+     * COLRv1 `PaintTransform`/`PaintTranslate`/`PaintScale`. Identity when
+     * absent.
+     */
+    readonly transform?: readonly [number, number, number, number, number, number];
+}
+/** A resolved colour glyph: ordered layers painted back-to-front. */
+interface ColorGlyph {
+    readonly layers: readonly ColorLayer[];
+}
+/** A colour-emoji Form XObject collected during content building. */
+interface ColorEmojiForm {
+    /** Resource name (without leading `/`), e.g. `CEm0`. */
+    readonly name: string;
+    /** Form XObject content stream (font-unit space). */
+    readonly content: string;
+    /** Inline `/Resources` body (shadings + ExtGStates), may be empty. */
+    readonly resources: string;
+    /** Form BBox `[x0 y0 x1 y1]` in font units. */
+    readonly bbox: readonly [number, number, number, number];
+}
+/**
+ * Collects unique colour-emoji glyphs encountered while building a document's
+ * content streams, de-duplicating them into a shared set of Form XObjects.
+ * Present on the {@link EncodingContext} only when an `'emoji-color'` font
+ * (a {@link FontData} carrying `colorGlyphs`) is registered. (v1.3.0)
+ */
+interface ColorEmojiCollector {
+    /**
+     * Register use of a colour glyph and return its Form resource name, or
+     * `null` when `gid` is not a colour glyph (caller falls back to normal
+     * text rendering).
+     */
+    useGlyph(fontData: FontData, gid: number): string | null;
+    /** The de-duplicated colour-emoji forms, in first-use order. */
+    readonly forms: ColorEmojiForm[];
 }
 /** A font entry binding FontData to a PDF font reference. */
 interface FontEntry {
@@ -67,6 +154,12 @@ interface EncodingContext {
     readonly f2: string;
     readonly fontData?: FontData;
     readonly getUsedGids?: () => Map<string, Set<number>>;
+    /**
+     * Colour-emoji collector — present only when an `'emoji-color'` font
+     * (carrying `colorGlyphs`) is registered. Used by the text emitter to
+     * draw colour-emoji Form XObjects inline. (v1.3.0)
+     */
+    readonly colorEmoji?: ColorEmojiCollector;
 }
 /** A single row in the PDF table. */
 interface PdfRow {
@@ -163,6 +256,15 @@ interface ColumnDef {
      * @since 1.1.0
      */
     readonly maxWidth?: number;
+    /**
+     * Semantic kind for the column. When set to `'amount'`, data cells in
+     * this column render in Helvetica-Bold with credit/debit colouring
+     * driven by `row.type`. Opt-in replacement for the pre-1.2.0
+     * hardcoded `i === 3` heuristic in `renderTable`. Default: plain text
+     * in `colors.text` and `enc.f1` (Helvetica-Regular).
+     * @since 1.2.0
+     */
+    readonly kind?: 'amount';
 }
 /**
  * Options for generating a PDF in a Web Worker via `generatePDFInWorker()`.
@@ -292,6 +394,51 @@ interface PdfLayoutOptions {
      * Default: undefined (no attachments).
      */
     readonly attachments?: readonly PdfAttachment[];
+    /**
+     * Maximum number of document blocks `buildDocumentPDF` / `buildDocumentPDFBytes`
+     * (and the streaming variants) will accept before throwing. This is a
+     * safety rail against accidental unbounded input, not a hard engine limit —
+     * raise it for very large generated reports (e.g. multi-thousand-page
+     * medical or financial documents).
+     *
+     * Default: `DEFAULT_MAX_BLOCKS` (100 000), matching the table builder's
+     * 100 000-row ceiling. Has no effect on the table builder (`buildPDF`).
+     *
+     * @since 1.3.0
+     */
+    readonly maxBlocks?: number;
+    /**
+     * Apply Unicode normalization to all rendered text before shaping and
+     * encoding. Uses the native `String.prototype.normalize` (zero dependency).
+     *
+     * Useful when input text may contain decomposed combining sequences (e.g.
+     * Vietnamese, some Indic input, or text copied from macOS which favours
+     * NFD) so that base + combining marks compose to the precomposed code
+     * points a font's cmap is most likely to cover, maximising glyph coverage.
+     *
+     * - `'NFC'` (recommended): canonical composition
+     * - `'NFD'`: canonical decomposition
+     * - `'NFKC'` / `'NFKD'`: compatibility (de)composition
+     * - `false` / omitted: no normalization (default — output is byte-identical)
+     *
+     * Default: `false` (backward compatible, byte-stable).
+     *
+     * @since 1.3.0
+     */
+    readonly normalize?: 'NFC' | 'NFD' | 'NFKC' | 'NFKD' | false;
+    /**
+     * Override the PDF creation date embedded in `/Info /CreationDate` and
+     * XMP metadata. Accepts any `Date` object.
+     *
+     * When omitted, defaults to `new Date()` at build time. Pinning this
+     * value makes output byte-identical across repeated calls — useful for
+     * deterministic tests and content-addressable storage.
+     *
+     * Default: `undefined` (current wall-clock time).
+     *
+     * @since 1.3.0
+     */
+    readonly creationDate?: Date;
 }
 /**
  * Relationship of an embedded file to the PDF document (ISO 19005-3 §6.8).
@@ -800,6 +947,66 @@ interface TableBlock {
      * @since 1.1.0
      */
     readonly autoFitColumns?: boolean;
+    /**
+     * Cell text wrapping policy.
+     *
+     * - `'auto'` (default) — wrap a cell's text only when its measured width
+     *   exceeds the column's available width. Cells that fit stay on a single
+     *   line, preserving byte-identical output with v1.1 for tables sized correctly.
+     * - `'always'` — wrap every cell using the available column width.
+     * - `'never'` — never wrap; fall back to v1.1 behaviour (character truncation
+     *   via `ColumnDef.mx` / `mxH`, plus the clipping rectangle when `clipCells`
+     *   is `true`). Useful when byte-identical v1.1 output is required.
+     *
+     * @since 1.2.0
+     */
+    readonly wrap?: 'auto' | 'always' | 'never';
+    /**
+     * Repeat the table header row on every continuation page when the table
+     * spans multiple pages. Default: `true`.
+     *
+     * Single-page tables are unaffected and byte-identical to v1.1.
+     *
+     * @since 1.2.0
+     */
+    readonly repeatHeader?: boolean;
+    /**
+     * Alternate-row background (zebra striping).
+     *
+     * - `false` (default) — no zebra background.
+     * - `true` — fill every other data row with a default light tint
+     *   (`'0.969 0.973 0.984'`, matching the default header background).
+     * - `PdfColor` — fill every other data row with the provided color.
+     *
+     * Uses a static (non-transparent) fill so the table remains PDF/A-1b safe.
+     *
+     * @since 1.2.0
+     */
+    readonly zebra?: boolean | PdfColor;
+    /**
+     * Optional caption rendered immediately above the table.
+     *
+     * In tagged mode, the caption is emitted as a `/Caption` structure element
+     * inside the `/Table` (ISO 14289-1 §7.10.6) for assistive-technology access.
+     *
+     * @since 1.2.0
+     */
+    readonly caption?: string;
+    /**
+     * Minimum row height in points. Rows shorter than this are padded.
+     * Defaults to the v1.1 `ROW_H` constant (`12`pt). Rows that wrap to
+     * multiple lines grow as needed; this only sets the floor.
+     *
+     * @since 1.2.0
+     */
+    readonly minRowHeight?: number;
+    /**
+     * Horizontal cell padding in points (applied to both the left and right
+     * insets inside each cell). Defaults to the v1.1 constant (`3`pt).
+     *
+     * @since 1.2.0
+     */
+    readonly cellPadding?: number;
 }
 /** List block — bullet or numbered items. */
 interface ListBlock {
@@ -1156,6 +1363,32 @@ interface PdfAConfig {
     /** OutputIntent /S name. */
     readonly outputIntentSubtype: string;
 }
+/**
+ * Canonical list of PDF/A conformance targets accepted by the `tagged`
+ * layout option. Useful as a single source of truth for tooling — most
+ * notably the `pdfnative-mcp` server's tool-schema `enum:` field — so
+ * agents like Gemini-CLI can autocomplete the legal values without
+ * hardcoding string literals.
+ *
+ * @example
+ * ```ts
+ * import { PDF_A_CONFORMANCE_TARGETS, type PdfAConformanceTarget } from 'pdfnative';
+ *
+ * function pickTarget(input: string): PdfAConformanceTarget | undefined {
+ *   return (PDF_A_CONFORMANCE_TARGETS as readonly string[]).includes(input)
+ *     ? input as PdfAConformanceTarget
+ *     : undefined;
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+declare const PDF_A_CONFORMANCE_TARGETS: readonly ["pdfa1b", "pdfa2b", "pdfa2u", "pdfa3b"];
+/**
+ * Type alias for the string literal members of {@link PDF_A_CONFORMANCE_TARGETS}.
+ * @since 1.2.0
+ */
+type PdfAConformanceTarget = typeof PDF_A_CONFORMANCE_TARGETS[number];
 /**
  * Parse the `tagged` layout option into a resolved PDF/A configuration.
  *
@@ -1633,17 +1866,13 @@ declare function estimateCmsSize(certSizes: readonly number[], algorithm: Signat
  * Foxit, and other PDF validators can verify.
  */
 
-interface PdfSignOptions {
-    /** Signer's X.509 certificate (DER-parsed). */
-    readonly signerCert: X509Certificate;
-    /** Optional certificate chain (intermediate CAs). */
-    readonly certChain?: readonly X509Certificate[];
-    /** RSA private key (for 'rsa-sha256'). */
-    readonly rsaKey?: RsaPrivateKey;
-    /** ECDSA private key (for 'ecdsa-sha256'). */
-    readonly ecKey?: EcPrivateKey;
-    /** Algorithm to use. Default: 'rsa-sha256'. */
-    readonly algorithm?: SignatureAlgorithm;
+/**
+ * Metadata-only subset of {@link PdfSignOptions} used by
+ * {@link buildSigDict} and {@link addSignaturePlaceholder}. None of
+ * these fields require key material — they just go into the `/Sig`
+ * dictionary as descriptive entries.
+ */
+interface SigDictMetadata {
     /** Signing time (defaults to current time). */
     readonly signingTime?: Date;
     /** Signer display name (for /Name field). */
@@ -1655,6 +1884,18 @@ interface PdfSignOptions {
     /** Contact info (for /ContactInfo field). */
     readonly contactInfo?: string;
 }
+interface PdfSignOptions extends SigDictMetadata {
+    /** Signer's X.509 certificate (DER-parsed). */
+    readonly signerCert: X509Certificate;
+    /** Optional certificate chain (intermediate CAs). */
+    readonly certChain?: readonly X509Certificate[];
+    /** RSA private key (for 'rsa-sha256'). */
+    readonly rsaKey?: RsaPrivateKey;
+    /** ECDSA private key (for 'ecdsa-sha256'). */
+    readonly ecKey?: EcPrivateKey;
+    /** Algorithm to use. Default: 'rsa-sha256'. */
+    readonly algorithm?: SignatureAlgorithm;
+}
 /**
  * Build a /Sig signature dictionary string for embedding in a PDF.
  * The /Contents and /ByteRange fields use placeholders that will be
@@ -1664,7 +1905,7 @@ interface PdfSignOptions {
  * @param contentsSize - Size of /Contents hex string in bytes.
  * @returns The /Sig dictionary string and the contentsHexLen.
  */
-declare function buildSigDict(options: PdfSignOptions, contentsSize?: number): string;
+declare function buildSigDict(options: SigDictMetadata, contentsSize?: number): string;
 /**
  * Sign a PDF that contains a signature placeholder.
  *
@@ -1685,6 +1926,71 @@ declare function signPdfBytes(pdfBytes: Uint8Array, options: PdfSignOptions): Ui
  */
 declare function estimateContentsSize(certSizes: readonly number[], algorithm?: SignatureAlgorithm): number;
 
+/**
+ * pdfnative — Signature Placeholder Injector
+ * ============================================
+ * Inject an AcroForm + invisible signature widget placeholder into an
+ * existing PDF via incremental update (ISO 32000-1 §7.5.6, §12.7.4.5,
+ * §12.8). The resulting PDF can be fed straight to
+ * {@link signPdfBytes} without any further preparation.
+ *
+ * Closes issue [#45](https://github.com/Nizoka/pdfnative/issues/45) —
+ * removes the need for downstream tooling (pdfnative-cli) to ship a
+ * local placeholder injector that duplicates the byte layout dictated
+ * by `BYTERANGE_PLACEHOLDER` and `buildSigDict()` in
+ * [pdf-signature.ts](./pdf-signature.ts).
+ */
+/**
+ * Options for {@link addSignaturePlaceholder}.
+ */
+interface AddSignaturePlaceholderOptions {
+    /**
+     * Reserved bytes for the future CMS blob. The on-disk
+     * `/Contents` hex string will be twice this size.
+     *
+     * @default 16384
+     */
+    readonly placeholderBytes?: number;
+    /**
+     * `/T` field name on the signature widget. Must be unique across
+     * the AcroForm `/Fields` array — throws on collision with an
+     * existing non-signature field.
+     *
+     * @default 'Signature1'
+     */
+    readonly fieldName?: string;
+    /**
+     * Page index (0-based) to attach the (invisible) widget to.
+     *
+     * @default 0
+     */
+    readonly pageIndex?: number;
+    /**
+     * `/Rect` for the widget annotation. `[0, 0, 0, 0]` makes the
+     * signature invisible — the default. Pass explicit coordinates if
+     * you want a visible signature appearance.
+     *
+     * @default [0, 0, 0, 0]
+     */
+    readonly rect?: readonly [number, number, number, number];
+}
+/**
+ * Inject an AcroForm + signature widget placeholder into an existing
+ * PDF via incremental update. Returns a NEW byte array. Idempotent:
+ * if the PDF already carries a `/FT /Sig` widget, the input is
+ * returned unchanged.
+ *
+ * @example
+ * ```ts
+ * import { buildDocumentPDFBytes, addSignaturePlaceholder, signPdfBytes } from 'pdfnative';
+ *
+ * const unsigned   = buildDocumentPDFBytes(params);
+ * const placeheld  = addSignaturePlaceholder(unsigned, { fieldName: 'Author' });
+ * const signed     = await signPdfBytes(placeheld, { privateKey, certificate });
+ * ```
+ */
+declare function addSignaturePlaceholder(pdfBytes: Uint8Array, options?: AddSignaturePlaceholderOptions): Uint8Array;
+
 /**
  * pdfnative — Streaming PDF Output
  * ==================================
@@ -1761,6 +2067,53 @@ declare function chunkBinaryString(str: string, chunkSize: number): Generator<Ui
  * ```
  */
 declare function buildDocumentPDFStream(params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions): AsyncGenerator<Uint8Array>;
+/**
+ * Build a free-form PDF document and yield Uint8Array chunks aligned
+ * at PDF object boundaries (one indirect object per chunk, plus a
+ * header chunk and a trailing xref/trailer chunk).
+ *
+ * Use this variant when the consumer benefits from receiving
+ * semantically meaningful PDF segments rather than fixed-size byte
+ * slices — for example, persisting each page object directly to disk
+ * before the next one is produced, or for diagnostic tooling that
+ * wants to inspect individual objects.
+ *
+ * **Scope note (v1.2.x):** the underlying assembler still buffers the
+ * full PDF binary in memory before chunking; constant-memory
+ * generation (true progressive assembly) is staged for v1.3. The
+ * public API surface, however, is stable from v1.2 onward — code
+ * written against `buildDocumentPDFStreamPageByPage()` will keep
+ * working without changes when the internal refactor lands.
+ *
+ * Constraints (same as `buildDocumentPDFStream`):
+ * - TOC blocks are not allowed (require multi-pass pagination)
+ * - `{pages}` placeholder is not allowed in header/footer templates
+ *
+ * @param params - Document content (title, blocks, footer, fonts)
+ * @param layoutOptions - Optional layout customization
+ * @yields Uint8Array chunks of the PDF, one PDF indirect object per chunk
+ *
+ * @example
+ * ```ts
+ * import { createWriteStream } from 'fs';
+ * const out = createWriteStream('large.pdf');
+ * for await (const chunk of buildDocumentPDFStreamPageByPage(params)) {
+ *     out.write(chunk);
+ * }
+ * out.end();
+ * ```
+ */
+declare function buildDocumentPDFStreamPageByPage(params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>): AsyncGenerator<Uint8Array>;
+/**
+ * Build a table-centric PDF and yield Uint8Array chunks aligned at
+ * PDF object boundaries. See {@link buildDocumentPDFStreamPageByPage}
+ * for the full semantic contract.
+ *
+ * @param params - PDF content (title, rows, headers, etc.)
+ * @param layoutOptions - Optional layout customization
+ * @yields Uint8Array chunks of the PDF, one PDF indirect object per chunk
+ */
+declare function buildPDFStreamPageByPage(params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>): AsyncGenerator<Uint8Array>;
 /**
  * Build a table-centric PDF and yield Uint8Array chunks progressively.
  *
@@ -1782,6 +2135,36 @@ declare function buildDocumentPDFStream(params: DocumentParams, layoutOptions?:
  * ```
  */
 declare function buildPDFStream(params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions): AsyncGenerator<Uint8Array>;
+/**
+ * Build a free-form PDF document with **true constant-memory streaming**.
+ *
+ * Unlike {@link buildDocumentPDFStream} (which assembles the full binary
+ * then chunks it), this variant assembles the PDF into its raw parts and
+ * yields them progressively, freeing each part as it is emitted. The
+ * fully-joined PDF binary never exists in memory at once. Byte output is
+ * identical to {@link buildDocumentPDFBytes}.
+ *
+ * Constraints (same as `buildDocumentPDFStream`):
+ * - TOC blocks are not allowed (require multi-pass pagination)
+ * - `{pages}` placeholder is not allowed in header/footer templates
+ *
+ * @param params - Document content (title, blocks, footer, fonts)
+ * @param layoutOptions - Optional layout customization
+ * @param streamOptions - Chunk size configuration
+ * @yields Uint8Array chunks of the PDF
+ */
+declare function buildDocumentPDFStreamTrue(params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions): AsyncGenerator<Uint8Array>;
+/**
+ * Build a table-centric PDF with **true constant-memory streaming**.
+ * See {@link buildDocumentPDFStreamTrue} for the full contract. Byte
+ * output is identical to {@link buildPDFBytes}.
+ *
+ * @param params - PDF content (title, rows, headers, etc.)
+ * @param layoutOptions - Optional layout customization
+ * @param streamOptions - Chunk size configuration
+ * @yields Uint8Array chunks of the PDF
+ */
+declare function buildPDFStreamTrue(params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions): AsyncGenerator<Uint8Array>;
 /**
  * Concatenate an array of Uint8Array chunks into a single Uint8Array.
  *
@@ -1864,6 +2247,12 @@ declare const DEFAULT_MARGINS: {
     l: number;
 };
 declare const DEFAULT_CW: number;
+/**
+ * Default ceiling for `buildDocumentPDF` block count, overridable per call via
+ * `PdfLayoutOptions.maxBlocks`. Matches the table builder's 100 000-row cap.
+ * @since 1.3.0
+ */
+declare const DEFAULT_MAX_BLOCKS = 100000;
 declare const ROW_H = 12;
 declare const TH_H = 15;
 declare const INFO_LN = 13;
@@ -1976,6 +2365,11 @@ declare function encodePdfTextString(str: string): string;
 declare function toWinAnsi(str: string): string;
 /**
  * Create a PDF string literal: encode to WinAnsi and escape (, ), \.
+ *
+ * Invisible BiDi directional controls (LRM/RLM, LRE/RLE/PDF/LRO/RLO,
+ * LRI/RLI/FSI/PDI) are stripped before encoding — they carry no
+ * visible width per UAX #9 and would otherwise become '?' under
+ * WinAnsi.
  */
 declare function pdfString(str: string): string;
 /**
@@ -2002,8 +2396,25 @@ declare function truncate(str: string, max: number): string;
 declare function truncateToWidth(str: string, maxWidthPt: number, sz: number, enc: EncodingContext): string;
 /**
  * Approximate text width in points using Helvetica character metrics.
+ *
+ * Invisible BiDi controls are stripped before measuring (zero-width
+ * per UAX #9).
  */
 declare function helveticaWidth(str: string, sz: number): number;
+/**
+ * Approximate text width in points using **Helvetica-Bold** character
+ * metrics. Required for right- and centre-aligned bold text (table headers,
+ * captions) where measuring with the regular {@link helveticaWidth}
+ * would position the rendered glyphs slightly past the intended right edge —
+ * Helvetica-Bold advances are ~16% wider on average than Helvetica-Regular.
+ *
+ * Widths are derived from the Adobe Helvetica-Bold AFM file (Type 1 standard
+ * PostScript font, base-14 PDF). Invisible BiDi controls are stripped before
+ * measuring (zero-width per UAX #9).
+ *
+ * @since 1.2.0
+ */
+declare function helveticaBoldWidth(str: string, sz: number): number;
 
 /**
  * pdfnative — Encoding Context Factory
@@ -2027,7 +2438,7 @@ declare function helveticaWidth(str: string, sz: number): number;
  *   Latin mode is used as before — strict PDF/A conformance requires the caller
  *   to register a Latin font (e.g. Noto Sans VF).
  */
-declare function createEncodingContext(fontEntries: FontEntry[], pdfA?: boolean): EncodingContext;
+declare function createEncodingContext(fontEntries: FontEntry[], pdfA?: boolean, normalize?: 'NFC' | 'NFD' | 'NFKC' | 'NFKD' | false): EncodingContext;
 
 /**
  * pdfnative — Font Loader
@@ -2123,6 +2534,18 @@ declare function isArmenianCodepoint(cp: number): boolean;
 declare function isBengaliCodepoint(cp: number): boolean;
 /** Check if a codepoint falls in the Tamil Unicode block. */
 declare function isTamilCodepoint(cp: number): boolean;
+/** Check if a codepoint falls in the Telugu Unicode block. */
+declare function isTeluguCodepoint(cp: number): boolean;
+/** Check if a codepoint falls in any Ethiopic Unicode block. */
+declare function isEthiopicCodepoint(cp: number): boolean;
+/** Check if a codepoint falls in the Sinhala Unicode block. */
+declare function isSinhalaCodepoint(cp: number): boolean;
+/** Check if a codepoint falls in the Tibetan Unicode block. */
+declare function isTibetanCodepoint(cp: number): boolean;
+/** Check if a codepoint falls in any Khmer Unicode block. */
+declare function isKhmerCodepoint(cp: number): boolean;
+/** Check if a codepoint falls in any Myanmar Unicode block. */
+declare function isMyanmarCodepoint(cp: number): boolean;
 /** Check if a codepoint falls in any Devanagari Unicode block. */
 declare function isDevanagariCodepoint(cp: number): boolean;
 /** Check if text contains Arabic characters requiring shaping. */
@@ -2135,6 +2558,18 @@ declare function containsThai(str: string): boolean;
 declare function containsBengali(str: string): boolean;
 /** Check whether a string contains any Tamil characters. */
 declare function containsTamil(str: string): boolean;
+/** Check whether a string contains any Telugu characters. */
+declare function containsTelugu(str: string): boolean;
+/** Check whether a string contains any Ethiopic characters. */
+declare function containsEthiopic(str: string): boolean;
+/** Check whether a string contains any Sinhala characters. */
+declare function containsSinhala(str: string): boolean;
+/** Check whether a string contains any Tibetan characters. */
+declare function containsTibetan(str: string): boolean;
+/** Check whether a string contains any Khmer characters. */
+declare function containsKhmer(str: string): boolean;
+/** Check whether a string contains any Myanmar characters. */
+declare function containsMyanmar(str: string): boolean;
 /** Check whether a string contains any Devanagari characters. */
 declare function containsDevanagari(str: string): boolean;
 
@@ -2200,6 +2635,191 @@ declare function shapeBengaliText(str: string, fontData: FontData): ShapedGlyph[
  */
 declare function shapeTamilText(str: string, fontData: FontData): ShapedGlyph[];
 
+/**
+ * pdfnative — Telugu Mini-Shaper
+ * ================================
+ * Pure JS OpenType GSUB + GPOS shaping for Telugu script.
+ * Zero external dependency.
+ *
+ * Handles:
+ *   - Syllable cluster building (base + virama-mediated conjuncts / subjoined
+ *     consonants — Telugu stacks the dependent consonant below the base)
+ *   - GSUB LigatureSubst: conjunct / subjoined-consonant formation
+ *     (C + Virama + C → ligature glyph)
+ *   - GSUB SingleSubst: contextual glyph substitution
+ *   - GPOS MarkToBase: combining-mark positioning (above/below vowel signs,
+ *     anusvara, candrabindu, length marks)
+ *
+ * Telugu is structurally close to Devanagari but:
+ *   - has **no reph** (Ra forms a subjoined glyph, not a top mark),
+ *   - has **no pre-base matra reordering** — every Telugu vowel sign attaches
+ *     to the right of, or above/below, the base (nothing renders to its left),
+ *   - has **no nukta**.
+ *
+ * References:
+ *   - Unicode Standard §12.8 Telugu
+ *   - OpenType spec: Script-specific shaping for Telugu (tel2 / Indic2)
+ *   - ISO 15924 script code: Telu
+ */
+
+/**
+ * Shape a string of Telugu text into an array of positioned glyphs.
+ *
+ * @param str - Raw Telugu string
+ * @param fontData - Font data with cmap, ligatures, markAnchors, metrics, widths
+ * @returns Array of positioned glyphs
+ */
+declare function shapeTeluguText(str: string, fontData: FontData): ShapedGlyph[];
+
+/**
+ * pdfnative — Sinhala Mini-Shaper
+ * ================================
+ * Pure JS OpenType GSUB + GPOS shaping for the Sinhala script (Sri Lanka).
+ * Zero external dependency.
+ *
+ * Handles:
+ *   - Syllable cluster building (base + al-lakuna-mediated conjuncts)
+ *   - GSUB LigatureSubst: conjunct / touching-form ligatures
+ *     (C + Al-lakuna + ZWJ + Ya/Ra → yansaya / rakaaransaya, C+C conjuncts)
+ *   - Pre-base (left-side) vowel reordering — the kombuva family
+ *     (U+0DD9 / U+0DDB and the left half of the two-part vowels U+0DDA,
+ *     U+0DDC, U+0DDD, U+0DDE) renders to the LEFT of its base consonant, so
+ *     the shaper emits that glyph BEFORE the base in visual order.
+ *   - Two-part dependent vowels are decomposed into their left + right halves.
+ *   - GPOS MarkToBase: above / below pilla positioning.
+ *
+ * Known limitations (documented):
+ *   - Complex multi-consonant stacks beyond the font's pre-baked ligature
+ *     table fall back to sequential base + al-lakuna rendering.
+ *   - GSUB MultipleSubst (LookupType 2) is not consumed; two-part vowels are
+ *     instead decomposed by this shaper's own table.
+ *
+ * References:
+ *   - Unicode Standard §13.2 Sinhala
+ *   - OpenType spec: Script-specific shaping for Sinhala (sinh)
+ *   - ISO 15924 script code: Sinh
+ */
+
+/**
+ * Shape a string of Sinhala text into an array of positioned glyphs.
+ *
+ * @param str - Raw Sinhala string
+ * @param fontData - Font data with cmap, ligatures, markAnchors, metrics, widths
+ * @returns Array of positioned glyphs
+ */
+declare function shapeSinhalaText(str: string, fontData: FontData): ShapedGlyph[];
+
+/**
+ * pdfnative — Tibetan Mini-Shaper
+ * ================================
+ * Pure JS OpenType GSUB + GPOS shaping for the Tibetan script.
+ * Zero external dependency.
+ *
+ * Tibetan builds vertical stacks: a head consonant with zero or more
+ * *subjoined* consonants (U+0F90–U+0FBC) stacked beneath it, plus vowel
+ * signs above / below and spacing marks to the right.
+ *
+ * Handles:
+ *   - Stack building (head consonant + subjoined consonants + vowels + marks)
+ *   - GSUB LigatureSubst: pre-baked stacked-consonant ligatures when the font
+ *     provides them (head + subjoined → single stack glyph)
+ *   - GPOS MarkToBase: subjoined consonants and above/below vowel signs are
+ *     anchored on the base when no ligature exists
+ *
+ * Known limitations (documented):
+ *   - Deep stacks beyond the font's ligature coverage fall back to GPOS
+ *     below-base anchoring of each subjoined consonant, which approximates but
+ *     may not perfectly match a native stacking engine.
+ *   - GSUB contextual substitution (LookupType 5/6) is not consumed.
+ *
+ * References:
+ *   - Unicode Standard §13.4 Tibetan
+ *   - OpenType spec: Script-specific shaping for Tibetan (tibt)
+ *   - ISO 15924 script code: Tibt
+ */
+
+/**
+ * Shape a string of Tibetan text into an array of positioned glyphs.
+ *
+ * @param str - Raw Tibetan string
+ * @param fontData - Font data with cmap, ligatures, markAnchors, metrics, widths
+ * @returns Array of positioned glyphs
+ */
+declare function shapeTibetanText(str: string, fontData: FontData): ShapedGlyph[];
+
+/**
+ * pdfnative — Khmer Mini-Shaper
+ * ==============================
+ * Pure JS OpenType GSUB + GPOS shaping for the Khmer script (Cambodia).
+ * Zero external dependency.
+ *
+ * Khmer is a USE-class (Universal Shaping Engine) script. This is a pragmatic
+ * USE-lite implementation that covers the common cases:
+ *   - Coeng (U+17D2) + consonant → subscript consonant (stacked below / behind)
+ *   - Pre-base (left-side) vowel reordering — U+17C1 (e), U+17C2 (ae),
+ *     U+17C3 (ai) render to the LEFT of their base, so they are emitted first.
+ *   - Two-part vowels (U+17BE, U+17BF, U+17C0, U+17C4, U+17C5) are decomposed
+ *     into their pre-base + post-base halves.
+ *   - GSUB LigatureSubst: coeng-form subscript ligatures when the font provides
+ *     them; GPOS MarkToBase for above / below vowel signs and diacritics.
+ *
+ * Known limitations (documented):
+ *   - This is not a full USE implementation. Robat (U+17CC), complex
+ *     multi-coeng stacks beyond the font's ligature coverage, and contextual
+ *     GSUB (LookupType 5/6) are approximated, not fully reordered.
+ *
+ * References:
+ *   - Unicode Standard §16.4 Khmer
+ *   - OpenType spec: Universal Shaping Engine; Khmer (khmr)
+ *   - ISO 15924 script code: Khmr
+ */
+
+/**
+ * Shape a string of Khmer text into an array of positioned glyphs.
+ *
+ * @param str - Raw Khmer string
+ * @param fontData - Font data with cmap, ligatures, markAnchors, metrics, widths
+ * @returns Array of positioned glyphs
+ */
+declare function shapeKhmerText(str: string, fontData: FontData): ShapedGlyph[];
+
+/**
+ * pdfnative — Myanmar Mini-Shaper
+ * ================================
+ * Pure JS OpenType GSUB + GPOS shaping for the Myanmar (Burmese) script.
+ * Zero external dependency.
+ *
+ * Myanmar is a USE-class (Universal Shaping Engine) script. This is a pragmatic
+ * USE-lite implementation covering the common cases:
+ *   - Medial consonants: medial ya (U+103B), ra (U+103C), wa (U+103D),
+ *     ha (U+103E). Medial **ra** renders to the LEFT of its base (pre-base)
+ *     and is therefore emitted first.
+ *   - Virama / stacker (U+1039): C + U+1039 + C → stacked subscript consonant.
+ *   - Asat (U+103A, visible killer) is preserved.
+ *   - GSUB LigatureSubst for medial / stacked forms when the font provides
+ *     them; GPOS MarkToBase for above / below vowel signs and tone marks.
+ *
+ * Known limitations (documented):
+ *   - This is not a full USE implementation. Kinzi (U+1004 U+103A U+1039),
+ *     deep stacks beyond the font's ligature coverage, and contextual GSUB
+ *     (LookupType 5/6) are approximated, not fully reordered. Kinzi is rendered
+ *     via its stacking sequence rather than a dedicated reordering pass.
+ *
+ * References:
+ *   - Unicode Standard §16.3 Myanmar
+ *   - OpenType spec: Universal Shaping Engine; Myanmar (mymr)
+ *   - ISO 15924 script code: Mymr
+ */
+
+/**
+ * Shape a string of Myanmar text into an array of positioned glyphs.
+ *
+ * @param str - Raw Myanmar string
+ * @param fontData - Font data with cmap, ligatures, markAnchors, metrics, widths
+ * @returns Array of positioned glyphs
+ */
+declare function shapeMyanmarText(str: string, fontData: FontData): ShapedGlyph[];
+
 /**
  * pdfnative — Devanagari Mini-Shaper
  * ====================================
@@ -2286,25 +2906,186 @@ interface BidiRun {
     readonly level: number;
     readonly start: number;
 }
+/**
+ * UAX #9 explicit embedding normalization (v1.2.0, refined v1.3.0).
+ *
+ * Maps the legacy explicit *embedding* characters into their sealed-isolate
+ * equivalents so the rest of the pipeline can process them via the existing
+ * isolate machinery:
+ *
+ * - LRE (U+202A) → LRI (U+2066)
+ * - RLE (U+202B) → RLI (U+2067)
+ * - PDF (U+202C) → PDI (U+2069), but only when popping a matched LRE/RLE
+ *   from the stack (otherwise preserved or dropped, see below)
+ *
+ * The explicit *override* characters LRO (U+202D) / RLO (U+202E) and the
+ * PDF (U+202C) that closes them are **preserved verbatim** — they carry
+ * character-level type-override semantics (UAX #9 X4/X5) that the isolate
+ * machinery cannot express. They are resolved separately by
+ * {@link resolveBidiRuns} via the override pre-pass, which forces every
+ * inner code point to L (LRO) or R (RLO). A PDF that would pop an override
+ * frame is therefore left in place for that pre-pass to consume.
+ *
+ * This split keeps the ≥ 95 % common embedding cases on the fast isolate
+ * path while giving LRO/RLO faithful character-level override behaviour.
+ *
+ * @param text - Raw input text in logical order
+ * @returns Text with embeddings mapped to isolates; overrides preserved.
+ */
+declare function normalizeBidiEmbeddings(text: string): string;
 /**
  * Resolve bidirectional text into ordered runs with embedding levels.
  *
- * Implements UAX #9 with isolate support (LRI/RLI/FSI ... PDI). When the
- * input contains matched isolate pairs, the inner content is resolved as
- * a sealed sub-paragraph with its own forced or auto-detected direction,
- * preventing the outer context from leaking into it (and vice versa).
+ * Implements UAX #9 with isolate support (LRI/RLI/FSI ... PDI) and
+ * explicit-embedding/override normalization (LRE/RLE/LRO/RLO/PDF →
+ * isolate-equivalent). When the input contains matched isolate pairs,
+ * the inner content is resolved as a sealed sub-paragraph with its
+ * own forced or auto-detected direction, preventing the outer context
+ * from leaking into it (and vice versa).
  *
  * @param text - Input text in logical order
  * @returns Array of BidiRun objects in visual order
  */
 declare function resolveBidiRuns(text: string): BidiRun[];
 /**
- * Check if text contains any RTL characters (Arabic or Hebrew).
+ * Check if text contains any RTL characters (Arabic or Hebrew) or an explicit
+ * directional override (LRO U+202D / RLO U+202E). The override markers are
+ * included so a direct caller that has not yet stripped controls still routes
+ * through the bidi resolver, where the X4/X5 override pass applies.
  *
  * @param text - Input text string
- * @returns True if text contains R or AL bidi types
+ * @returns True if text contains R/AL bidi types or an LRO/RLO override
  */
 declare function containsRTL(text: string): boolean;
+/**
+ * Strip invisible Unicode bidirectional formatting characters.
+ *
+ * The BiDi resolver consumes these characters when it runs, but the
+ * resolver is only invoked when `containsRTL()` is true. For pure-LTR
+ * paragraphs that nonetheless contain directional formatters (e.g. an
+ * orphan PDF U+202C left over after `normalizeBidiEmbeddings()`), the
+ * marker would reach the font encoder as a regular codepoint and
+ * render as `.notdef` (tofu) since no font ships a glyph for it.
+ *
+ * Stripped codepoints:
+ * - LRM / RLM (U+200E, U+200F)
+ * - LRE / RLE / PDF / LRO / RLO (U+202A–U+202E)
+ * - LRI / RLI / FSI / PDI (U+2066–U+2069)
+ *
+ * Safe to call unconditionally — these characters carry no visible
+ * width per UAX #9, so removing them never changes layout.
+ *
+ * @since 1.2.0
+ */
+declare function stripBidiControls(text: string): string;
+
+/**
+ * pdfnative — Universal Shaping Engine (USE) lite
+ * =================================================
+ * Cluster classification utility for Indic and related complex scripts
+ * (Devanagari, Bengali, Tamil, Gujarati, Gurmukhi, Telugu, Kannada,
+ * Malayalam, Sinhala, Khmer, Myanmar, Tibetan).
+ *
+ * Based on the Universal Shaping Engine specification:
+ *   https://learn.microsoft.com/en-us/typography/script-development/use
+ *
+ * Scope (v1.3.0):
+ *   - Public API for cluster classification: callers can run their own
+ *     reordering / GSUB pipelines on top of the cluster categories.
+ *   - 11 cluster categories sufficient for the four scripts pdfnative
+ *     ships shaping for (Devanagari, Bengali, Tamil) plus a generic
+ *     fallback that classifies any USE-eligible code point.
+ *   - Marathi eyelash-ra (Ra + virama + ZWJ) is recognised as a distinct
+ *     reph variant (`UseCluster.eyelash`).
+ *   - The bundled Devanagari/Bengali/Tamil shapers consume
+ *     `classifyUseCategory` as the single source of truth for joiner
+ *     (ZWJ/ZWNJ) and half-form/eyelash decisions; their hand-tuned
+ *     happy-path reordering (pinned by the vitest suite) is preserved.
+ *
+ * Not in scope (deferred):
+ *   - State-table classification for Khmer/Myanmar/Tibetan/Sinhala/
+ *     other USE-required scripts not currently bundled.
+ */
+/**
+ * USE-lite cluster categories. A subset of the full USE category set
+ * sufficient for the four scripts pdfnative ships shaping for.
+ *
+ * - `B` — Base consonant
+ * - `V` — Independent vowel
+ * - `N` — Number
+ * - `H` — Halant / Virama
+ * - `M` — Vowel sign / Matra (combining mark)
+ * - `Mpre` — Pre-base matra (reorders before base in visual order)
+ * - `Mabv` — Above-base matra
+ * - `Mblw` — Below-base matra
+ * - `Mpst` — Post-base matra
+ * - `R` — Reph (the special "ra + virama" cluster head)
+ * - `ZWJ` — Zero-width joiner (forms half / conjunct)
+ * - `ZWNJ` — Zero-width non-joiner (breaks conjunct)
+ * - `O` — Other (default)
+ */
+type UseCategory = 'B' | 'V' | 'N' | 'H' | 'M' | 'Mpre' | 'Mabv' | 'Mblw' | 'Mpst' | 'R' | 'ZWJ' | 'ZWNJ' | 'O';
+/** Classified code point with its USE-lite category. */
+interface UseClassifiedCp {
+    readonly cp: number;
+    readonly category: UseCategory;
+}
+/** A USE-lite cluster: a base plus its prefixed/suffixed marks and signs. */
+interface UseCluster {
+    /** Pre-base reordering elements (e.g. Devanagari ि matra). */
+    readonly prebase: UseClassifiedCp[];
+    /** The cluster base (consonant or vowel). */
+    readonly base: UseClassifiedCp | null;
+    /** Above-base marks. */
+    readonly above: UseClassifiedCp[];
+    /** Below-base marks. */
+    readonly below: UseClassifiedCp[];
+    /** Post-base marks. */
+    readonly post: UseClassifiedCp[];
+    /** Halant + consonant chains attached after the base (conjunct tail). */
+    readonly tail: UseClassifiedCp[];
+    /**
+     * True when the cluster head is a Marathi eyelash-ra — `Ra + virama + ZWJ`
+     * — which renders as the eyelash (rakar) form rather than a reph. The
+     * leading `Ra` is still recorded in {@link prebase} with category `'R'`.
+     */
+    readonly eyelash?: boolean;
+}
+/**
+ * Classify a single Unicode code point into a USE-lite category.
+ * Dispatches to per-script tables; falls back to `'O'` for code points
+ * outside the supported ranges.
+ *
+ * Special cases:
+ *   - U+200C ZWNJ → 'ZWNJ'
+ *   - U+200D ZWJ  → 'ZWJ'
+ *
+ * @param cp - Unicode code point
+ * @returns USE-lite category
+ */
+declare function classifyUseCategory(cp: number): UseCategory;
+/**
+ * Split a code-point sequence into USE-lite clusters. Each cluster
+ * carries a single base (consonant or independent vowel) plus all its
+ * attached marks classified by their position relative to the base.
+ *
+ * Reph detection: when the sequence starts with consonant + virama
+ * (or contains a "Ra + virama + consonant" prefix where Ra is U+0930
+ * for Devanagari or U+09B0 for Bengali), the leading Ra-virama is
+ * collected as a special pre-base reph element (category 'R').
+ *
+ * @param codePoints - Logical-order code points
+ * @returns Array of UseCluster objects
+ *
+ * @example
+ * ```ts
+ * import { classifyClusters } from 'pdfnative';
+ * const cps = Array.from('प्रकार').map(c => c.codePointAt(0)!);
+ * const clusters = classifyClusters(cps);
+ * // → one cluster per visible aksara, with reph/conjunct info
+ * ```
+ */
+declare function classifyClusters(codePoints: readonly number[]): UseCluster[];
 
 /**
  * pdfnative — Arabic Text Shaper
@@ -2342,6 +3123,148 @@ declare function containsRTL(text: string): boolean;
  */
 declare function shapeArabicText(str: string, fontData: FontData): ShapedGlyph[];
 
+/**
+ * pdfnative — TrueType `glyf` Outline Extractor
+ * ==============================================
+ * Pure-JS reader that turns a TrueType glyph outline into ordered contours
+ * of quadratic on/off-curve points. Zero external dependency.
+ *
+ * Used by the colour-glyph renderer (COLR/CPAL) to fill a base glyph's
+ * outline as a native PDF path. Handles both simple and composite glyphs
+ * (the latter via recursive 2×2 + translate component transforms).
+ *
+ * References:
+ *   - ISO/IEC 14496-22 (OpenType) §5.3.3 `glyf`
+ *   - Apple TrueType Reference Manual — Glyph data format
+ */
+/** A single outline point in font units. */
+interface OutlinePoint {
+    readonly x: number;
+    readonly y: number;
+    /** True for on-curve points; false for quadratic control (off-curve). */
+    readonly onCurve: boolean;
+}
+/** A closed contour: an ordered ring of on/off-curve points. */
+type Contour = OutlinePoint[];
+/** A parsed TrueType font exposing just enough to read glyph outlines. */
+interface GlyfFont {
+    readonly view: DataView;
+    readonly glyfOffset: number;
+    readonly locaOffsets: number[];
+    readonly unitsPerEm: number;
+}
+/**
+ * Parse the table directory, `head`, `maxp` and `loca` so that subsequent
+ * {@link extractGlyphContours} calls are O(1) lookups.
+ *
+ * @param bytes - Raw TrueType/OpenType (glyf-flavoured) font bytes.
+ * @returns A {@link GlyfFont}, or `null` if the font has no `glyf` outlines
+ *          (e.g. a CFF font) or is structurally invalid.
+ */
+declare function parseGlyfFont(bytes: Uint8Array): GlyfFont | null;
+/**
+ * Extract the contours of a single glyph in font units. Composite glyphs are
+ * flattened by recursively transforming their components.
+ *
+ * @param font  - Parsed {@link GlyfFont}.
+ * @param gid   - Glyph id.
+ * @param depth - Internal recursion guard for composite glyphs.
+ * @returns Array of contours (empty for whitespace / empty glyphs).
+ */
+declare function extractGlyphContours(font: GlyfFont, gid: number, depth?: number): Contour[];
+
+/**
+ * pdfnative — COLR / CPAL Colour-Font Parser
+ * ===========================================
+ * Pure-JS reader for the OpenType COLR (colour layers) and CPAL (colour
+ * palette) tables. Resolves each base colour glyph into a flat list of
+ * {@link ColorLayer}s (base outline + paint), painted back-to-front.
+ *
+ * Supported:
+ *   - COLR v0 — layered solid fills.
+ *   - COLR v1 — PaintColrLayers, PaintGlyph, PaintColrGlyph, PaintSolid,
+ *     PaintLinearGradient, PaintRadialGradient, PaintTransform,
+ *     PaintTranslate, PaintScale (+ around-center).
+ *
+ * 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.
+ *
+ * Zero external dependency.
+ *
+ * References:
+ *   - ISO/IEC 14496-22 (OpenType) §5.7.11 COLR, §5.7.12 CPAL
+ *   - https://learn.microsoft.com/typography/opentype/spec/colr
+ */
+
+/**
+ * Parse the CPAL table's first palette into an array of {@link CpalColor}s
+ * (sRGB + alpha, each channel 0–255), indexed by palette entry.
+ */
+declare function parseCpal(bytes: Uint8Array): CpalColor[] | null;
+/**
+ * Parse the COLR + CPAL tables of a font into a colour-glyph map keyed by
+ * base glyph id. Returns `null` when the font has no COLR table.
+ *
+ * @param bytes - Raw OpenType font bytes.
+ */
+declare function parseColrCpal(bytes: Uint8Array): Record<number, ColorGlyph> | null;
+
+/**
+ * pdfnative — Colour Glyph Renderer (COLR/CPAL → native PDF)
+ * ==========================================================
+ * Renders a resolved {@link ColorGlyph} as a native PDF Form XObject: each
+ * layer's base-glyph outline is emitted as a vector path and filled with a
+ * flat colour or a `/Shading` gradient. No rasterisation, zero dependency.
+ *
+ *   - Solid layers → `r g b rg … f` (with `/ca` ExtGState for alpha < 1).
+ *   - Linear gradients → `/Shading` Type 2 (axial) painted via `sh`,
+ *     clipped to the glyph outline.
+ *   - Radial gradients → `/Shading` Type 3, likewise.
+ *
+ * The Form XObject's user space is font units; the caller scales it onto the
+ * page with a `cm` and draws it with `Do`.
+ *
+ * References:
+ *   - ISO 32000-1 §8.7.4.5 (Shadings), §7.10.2 (Type 2 functions),
+ *     §8.10 (Form XObjects)
+ */
+
+/** A rendered colour glyph ready to be assembled into a Form XObject. */
+interface ColorGlyphForm {
+    /** Form XObject content stream (font-unit user space). */
+    readonly content: string;
+    /** Form BBox `[x0 y0 x1 y1]` in font units. */
+    readonly bbox: readonly [number, number, number, number];
+    /** Named `/Shading` resources referenced by the content stream. */
+    readonly shadings: ReadonlyArray<{
+        readonly name: string;
+        readonly dict: string;
+    }>;
+    /** Named `/ExtGState` resources (constant alpha) referenced by content. */
+    readonly extGStates: ReadonlyArray<{
+        readonly name: string;
+        readonly dict: string;
+    }>;
+}
+/** Provider of glyph outlines (decoupled from the font parser for testing). */
+type OutlineProvider = (glyphId: number) => Contour[];
+type Mat = readonly [number, number, number, number, number, number];
+/**
+ * Convert a set of TrueType quadratic contours into PDF path operators
+ * (cubic Béziers), applying matrix `m`. Each contour is closed (`h`).
+ */
+declare function contoursToPath(contours: Contour[], m?: Mat): string;
+/**
+ * Render a colour glyph into a {@link ColorGlyphForm}.
+ *
+ * @param glyph    - Resolved colour glyph (ordered layers).
+ * @param outlines - Provides the contours for a given base glyph id.
+ * @param unitsPerEm - Font units per em (defines the BBox).
+ */
+declare function renderColorGlyph(glyph: ColorGlyph, outlines: OutlineProvider, unitsPerEm: number): ColorGlyphForm;
+
 /**
  * pdfnative — PDF Token Scanner
  * ===============================
@@ -2430,11 +3353,11 @@ type PdfArray = PdfValue[];
  * ```
  */
 type PdfValue = null | boolean | number | string | PdfName | PdfRef | PdfArray | PdfDict | PdfStream;
-declare function isRef(v: PdfValue): v is PdfRef;
+declare function isRef(v: PdfValue | undefined): v is PdfRef;
 declare function isName(v: PdfValue | undefined): v is PdfName;
 declare function isStream(v: PdfValue): v is PdfStream;
 declare function isDict(v: PdfValue): v is PdfDict;
-declare function isArray(v: PdfValue): v is PdfArray;
+declare function isArray(v: PdfValue | undefined): v is PdfArray;
 declare function dictGet(dict: PdfDict, key: string): PdfValue | undefined;
 declare function dictGetName(dict: PdfDict, key: string): string | undefined;
 /** Extract the string value from a PdfName, or undefined if not a name. */
@@ -2608,6 +3531,18 @@ interface PdfModifier {
      * Returns the new object number.
      */
     addObject(value: PdfValue): number;
+    /**
+     * Allocate a new object number whose body is emitted **verbatim**
+     * between `num gen obj` and `endobj`. The caller is responsible
+     * for the body's PDF syntactic validity — used for objects that
+     * need an exact byte layout the PdfValue serialiser cannot
+     * express (e.g. signature `/Sig` dictionaries whose
+     * `/Contents <00…>` and `/ByteRange [0 …]` placeholders must be
+     * preserved byte-for-byte for `signPdfBytes()` to patch them).
+     *
+     * Returns the new object number.
+     */
+    addRawObject(body: string): number;
     /**
      * Get the current value of an object (modified or original).
      */
@@ -2630,6 +3565,44 @@ interface PdfModifier {
  */
 declare function createModifier(reader: PdfReader): PdfModifier;
 
+/**
+ * pdfnative — PDF/UA structural validator (ISO 14289-1)
+ * ======================================================
+ * A lightweight, read-only conformance checker for tagged-PDF (PDF/UA)
+ * structural prerequisites. It does **not** render or rasterise; it parses the
+ * document with the native reader and inspects the catalog, structure tree and
+ * per-page marked-content.
+ *
+ * Scope (what this validator can verify from structure alone):
+ *   - Catalog `/MarkInfo << /Marked true >>`            (ISO 14289-1 §7.1)
+ *   - Catalog `/StructTreeRoot`                          (ISO 14289-1 §7.1)
+ *   - Catalog `/Metadata` (XMP) and `/Lang`              (ISO 14289-1 §7.2, §7.3)
+ *   - `/StructTreeRoot /ParentTree`                      (ISO 32000-1 §14.7.4.4)
+ *   - MCID uniqueness within each page's content stream  (ISO 32000-1 §14.7.4.3)
+ *
+ * It is intended as a fast developer-time gate, not a substitute for a full
+ * reference validator (e.g. veraPDF) which also checks fonts, colour and
+ * rendering. A `valid` result here means the structural prerequisites hold.
+ *
+ * @since 1.3.0
+ */
+/** Result of a PDF/UA structural validation. */
+interface PdfUAValidationResult {
+    /** True when no blocking errors were found. */
+    readonly valid: boolean;
+    /** Blocking conformance violations. */
+    readonly errors: readonly string[];
+    /** Non-blocking recommendations (PDF/UA best practices). */
+    readonly warnings: readonly string[];
+}
+/**
+ * Validate the PDF/UA (ISO 14289-1) structural prerequisites of a tagged PDF.
+ *
+ * @param bytes - Complete PDF file bytes (e.g. from `buildDocumentPDFBytes`).
+ * @returns A structured result with `valid`, `errors` and `warnings`.
+ */
+declare function validatePdfUA(bytes: Uint8Array): PdfUAValidationResult;
+
 /**
  * pdfnative — DEFLATE Decompressor (FlateDecode reader)
  * ======================================================
@@ -2777,4 +3750,4 @@ declare function createPDF(pdfParams: PdfParams, options?: {
     layoutOptions?: Partial<PdfLayoutOptions>;
 }): Promise<Uint8Array>;
 
-export { type Annotation, type Asn1Node, BAL_H, type BarcodeBlock, type BarcodeFormat, type BidiRun, type CmsSignOptions, type ColumnDef, DEFAULT_COLORS, DEFAULT_COLUMNS, DEFAULT_CW, DEFAULT_FONT_SIZES, DEFAULT_MARGINS, 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, HEADER_H, type HeadingBlock, INFO_LN, type ImageBlock, type InternalLink, KNOWN_DECODE_FILTERS, type LinkAnnotation, type LinkBlock, type ListBlock, MAX_PARSE_DEPTH, MAX_XREF_CHAIN, PAGE_SIZES, PG_H, PG_W, type PageBreakBlock, type PageTemplate, type ParagraphBlock, type PdfArray as ParsedArray, type PdfDict as ParsedDict, type ParsedImage, type PdfAConfig, 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 PdfValue, type QRErrorLevel, ROW_H, type RadioGroupContext, type RsaPrivateKey, type RsaPublicKey, type ShapedGlyph, type SignatureAlgorithm, type SpacerBlock, type StreamOptions, type SvgBlock, type SvgRenderOptions, type SvgSegment, TH_H, TITLE_LN, type TableBlock, type TextRun, type TocBlock, type TokenType, 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, applyDecodeFilter, buildAcroFormDict, buildAppearanceStreamDict, buildCmsSignedData, buildDocumentPDF, buildDocumentPDFBytes, buildDocumentPDFStream, buildEmbeddedFiles, buildFormWidget, buildImageOperators, buildImageXObject, buildInternalLinkAnnotation, buildLinkAnnotation, buildPDF, buildPDFBytes, buildPDFStream, buildRadioGroupParent, buildSMaskXObject, buildSigDict, buildWatermarkState, chunkBinaryString, clearFontCache, computeColumnPositions, concatChunks, containsArabic, containsBengali, containsDevanagari, containsHebrew, containsRTL, containsTamil, containsThai, 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, findStartxref, generateDataMatrix, generatePDFInWorker, generatePDFMainThread, generateQR, getMaxInflateOutputSize, getRegisteredLangs, getTrailerRef, getTrailerValue, hasFontLoader, helveticaWidth, hmacSha256, inflateSync, initCrypto, initNodeCompression, initNodeDecompression as initNodeDecompression_parser, isArmenianCodepoint, isArray, isBengaliCodepoint, isCyrillicCodepoint, isDevanagariCodepoint, isDict, isGeorgianCodepoint, isLinkAnnotation, isName, isRef, isSelfSigned, isStream, isTamilCodepoint, isValidPdfRgb, loadFontData, nameValue, needsUnicodeFont, normalizeColors, openPdf, parseCertificate, parseColor, parseImage, parseIndirectObject, parseJPEG, parsePNG, parseRsaPrivateKey, parseRsaPublicKey, parseSvgPath, parseValue, parseXrefTable, pdfString, registerFont, registerFonts, renderBarcode, renderCode128, renderDataMatrix, renderEAN13, renderPDF417, renderQR, renderSvg, resetFontRegistry, resolveBidiRuns, resolveLayout, resolvePdfAConfig, resolveTemplate, rsaSign, rsaSignHash, rsaVerify, rsaVerifyHash, setDeflateImpl, setInflateImpl, setMaxInflateOutputSize, sha384, sha512, shapeArabicText, shapeBengaliText, shapeDevanagariText, shapeTamilText, shapeThaiText, signPdfBytes, slugify, splitTextByFont, streamByteLength, toBytes, toWinAnsi, truncate, truncateToWidth, validateAttachments, validateDocumentStreamable, validateTableStreamable, validateURL, validateWatermark, verifyCertSignature, wrapText };
+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 };