pdfnative 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -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 {
@@ -301,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).
@@ -1997,6 +2135,36 @@ declare function buildPDFStreamPageByPage(params: PdfParams, layoutOptions?: Par
  * ```
  */
 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.
  *
@@ -2079,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;
@@ -2264,7 +2438,7 @@ declare function helveticaBoldWidth(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
@@ -2360,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. */
@@ -2372,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;
 
@@ -2437,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
  * ====================================
@@ -2524,29 +2907,30 @@ interface BidiRun {
     readonly start: number;
 }
 /**
- * UAX #9 explicit embedding/override normalization (v1.2.0).
+ * UAX #9 explicit embedding normalization (v1.2.0, refined v1.3.0).
  *
- * Maps the legacy explicit directional formatting characters into their
- * sealed-isolate equivalents so the rest of the pipeline can process
- * them via the existing isolate machinery:
+ * 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)
- * - LRO (U+202D) → LRI (U+2066) — base direction L (character-level
- *   override staged for v1.3)
- * - RLO (U+202E) → RLI (U+2067) — base direction R (character-level
- *   override staged for v1.3)
- * - PDF (U+202C) → PDI (U+2069), but only when popping a matched
- *   LRE/RLE/LRO/RLO from the stack (otherwise dropped)
- *
- * This is a pragmatic simplification: full UAX #9 embeddings allow
- * neutral resolution to leak across the embedding boundary, while
- * isolates are sealed. In real-world inputs the two are
- * interchangeable for ≥ 95 % of cases. Strict UAX #9 conformance with
- * embedding leakage and character-level override is staged for v1.3.
+ * - 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 Normalized text with embeddings mapped to isolates.
+ * @returns Text with embeddings mapped to isolates; overrides preserved.
  */
 declare function normalizeBidiEmbeddings(text: string): string;
 /**
@@ -2564,10 +2948,13 @@ declare function normalizeBidiEmbeddings(text: string): string;
  */
 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;
 /**
@@ -2602,19 +2989,20 @@ declare function stripBidiControls(text: string): string;
  * Based on the Universal Shaping Engine specification:
  *   https://learn.microsoft.com/en-us/typography/script-development/use
  *
- * Scope (v1.2.0):
+ * 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.
- *
- * Not in scope (deferred to v1.3):
- *   - Rewiring the bundled Devanagari/Bengali/Tamil shapers to drive
- *     their reordering from this module. The shapers currently use
- *     hand-tuned per-script logic that the existing 1700+ vitest
- *     cases pin in place; switching them over is a separate refactor
- *     gated on the v1.3 shaping benchmark harness.
+ *   - 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.
  */
@@ -2656,6 +3044,12 @@ interface UseCluster {
     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.
@@ -2729,6 +3123,148 @@ declare function classifyClusters(codePoints: readonly number[]): UseCluster[];
  */
 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
  * ===============================
@@ -3029,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)
  * ======================================================
@@ -3176,4 +3750,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 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, 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 PdfValue, type QRErrorLevel, ROW_H, type RadioGroupContext, type RsaPrivateKey, type RsaPublicKey, type ShapedGlyph, type SigDictMetadata, type SignatureAlgorithm, 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, buildEmbeddedFiles, buildFormWidget, buildImageOperators, buildImageXObject, buildInternalLinkAnnotation, buildLinkAnnotation, buildPDF, buildPDFBytes, buildPDFStream, buildPDFStreamPageByPage, buildRadioGroupParent, buildSMaskXObject, buildSigDict, buildWatermarkState, chunkBinaryString, classifyClusters, classifyUseCategory, 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, helveticaBoldWidth, 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, normalizeBidiEmbeddings, 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, stripBidiControls, 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 };