pdfnative 1.0.5 → 1.2.0

package/dist/index.d.cts

@@ -149,6 +149,29 @@ interface ColumnDef {
     readonly mx: number;
     /** Max characters for header cells. */
     readonly mxH: number;
+    /**
+     * Minimum column width in points. When set, the resolved width is
+     * clamped to at least this value, redistributing the surplus across
+     * the remaining unconstrained columns (proportional to their `f`).
+     * @since 1.1.0
+     */
+    readonly minWidth?: number;
+    /**
+     * Maximum column width in points. When set, the resolved width is
+     * clamped to at most this value, redistributing the surplus across
+     * the remaining unconstrained columns (proportional to their `f`).
+     * @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()`.
@@ -383,6 +406,15 @@ interface WatermarkText {
     readonly opacity?: number;
     /** Rotation angle in degrees (counterclockwise). Default: -45. */
     readonly angle?: number;
+    /**
+     * Auto-fit: clamp `fontSize` so the rotated bounding box fits within the
+     * page minus a 24-pt safety margin. Default: `true` (added in v1.1.0).
+     *
+     * Set to `false` to preserve byte-stable output when callers depend on
+     * the exact `fontSize` even if it produces a watermark that overflows
+     * the page (legacy v1.0.x behaviour).
+     */
+    readonly autoFit?: boolean;
 }
 /**
  * Image watermark configuration.
@@ -752,6 +784,91 @@ interface TableBlock {
     readonly headers: readonly string[];
     readonly rows: readonly PdfRow[];
     readonly columns?: readonly ColumnDef[];
+    /**
+     * Clip cell contents to column bounds using PDF clip-path operators.
+     * When `true`, each header/data cell is wrapped in `q <rect> re W n ... Q` so
+     * over-long text cannot escape the column rectangle visually.
+     *
+     * When `false`, cells rely solely on the existing `truncate()` character cap
+     * (ColumnDef.mx / mxH) — variable-width glyphs may still overflow visually.
+     *
+     * Default: `true` (recommended for PDF/A and visual safety).
+     * @since 1.1.0
+     */
+    readonly clipCells?: boolean;
+    /**
+     * Auto-fit column widths to actual content widths, respecting per-column
+     * `minWidth` / `maxWidth` constraints. Surplus or deficit is redistributed
+     * across unconstrained columns proportional to their `f` fraction.
+     *
+     * When `false` (default), the explicit `f` fractions are used as-is.
+     *
+     * Note: byte-output is non-deterministic vs explicit widths because resolved
+     * widths depend on text content and font metrics. Use only when content-aware
+     * sizing is desired.
+     * @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 {
@@ -1108,6 +1225,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.
  *
@@ -1585,17 +1728,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). */
@@ -1607,6 +1746,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
@@ -1616,7 +1767,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.
  *
@@ -1637,6 +1788,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
  * ==================================
@@ -1713,6 +1929,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.
  *
@@ -1856,6 +2119,14 @@ declare const DEFAULT_COLORS: PdfColors;
 declare const DEFAULT_COLUMNS: ColumnDef[];
 /**
  * Compute column X positions and widths given columns and content width.
+ *
+ * Honours optional `minWidth` / `maxWidth` constraints (in points) by clamping
+ * each constrained column then redistributing the surplus or deficit across
+ * the unconstrained columns proportional to their fractional weight `f`.
+ * Falls back to a single uniform proration pass when all columns are
+ * constrained or the unconstrained weights sum to zero.
+ *
+ * @since 1.1.0 — added support for `minWidth` / `maxWidth` (additive).
  */
 declare function computeColumnPositions(columns: readonly ColumnDef[], marginLeft: number, contentWidth: number): {
     cx: number[];
@@ -1920,14 +2191,56 @@ 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;
-/** Truncate string to max characters, appending '..' if needed. */
+/**
+ * Truncate string to max characters, appending Unicode ellipsis (…, U+2026) if needed.
+ *
+ * The horizontal ellipsis is rendered correctly in both Latin/WinAnsi mode
+ * (mapped to byte 0x85) and Unicode/CIDFont mode. This produces typographically
+ * correct output and is ~50% narrower than ASCII "..." while remaining a single
+ * grapheme cluster.
+ *
+ * @since 1.1.0 — the ellipsis character changed from `'..'` (two ASCII dots)
+ *   to `'…'` (U+2026). Output is one character shorter for the same `max`.
+ */
 declare function truncate(str: string, max: number): string;
+/**
+ * Truncate string so that its rendered width does not exceed `maxWidthPt`,
+ * appending the Unicode ellipsis (…, U+2026) when truncation occurs.
+ *
+ * Unlike {@link truncate}, this measures actual glyph width using the encoding
+ * context — appropriate for proportional fonts and Unicode text.
+ *
+ * @since 1.1.0
+ */
+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
@@ -1945,8 +2258,13 @@ declare function helveticaWidth(str: string, sz: number): number;
  * Latin mode uses WinAnsi/Helvetica, Unicode mode uses CIDFont/Identity-H.
  *
  * @param fontEntries - Array of font entries (primary first). Empty = Latin mode.
+ * @param pdfA - When true and at least one font entry is registered, disables
+ *   WinAnsi/Helvetica fallback in mixed-content runs (Helvetica is unembedded
+ *   standard-14, forbidden by ISO 19005). When pdfA is true with no fontEntries,
+ *   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[]): EncodingContext;
+declare function createEncodingContext(fontEntries: FontEntry[], pdfA?: boolean): EncodingContext;
 
 /**
  * pdfnative — Font Loader
@@ -2173,7 +2491,7 @@ declare function detectFallbackLangs(texts: string[], primaryLang: string): Set<
  * Returns the language code of the font most appropriate for rendering.
  *
  * @param cp - Unicode codepoint
- * @returns Language code ('el', 'hi', 'th', 'ja', 'ko', 'zh', 'vi', 'pl', 'tr', 'he', 'ar', 'ru', 'ka', 'hy') or null for Latin/common
+ * @returns Language code ('el', 'hi', 'th', 'ja', 'ko', 'zh', 'vi', 'pl', 'tr', 'he', 'ar', 'ru', 'ka', 'hy', 'emoji') or null for Latin/common
  */
 declare function detectCharLang(cp: number): string | null;
 
@@ -2205,9 +2523,42 @@ interface BidiRun {
     readonly level: number;
     readonly start: number;
 }
+/**
+ * UAX #9 explicit embedding/override normalization (v1.2.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:
+ *
+ * - 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.
+ *
+ * @param text - Raw input text in logical order
+ * @returns Normalized text with embeddings mapped to isolates.
+ */
+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) 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
  */
@@ -2219,6 +2570,128 @@ declare function resolveBidiRuns(text: string): BidiRun[];
  * @returns True if text contains R or AL bidi types
  */
 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.2.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.
+ *   - 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[];
+}
+/**
+ * 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
@@ -2344,11 +2817,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. */
@@ -2522,6 +2995,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).
      */
@@ -2595,6 +3080,62 @@ declare function initNodeDecompression(): Promise<void>;
  */
 declare function inflateSync(data: Uint8Array): Uint8Array;
 
+/**
+ * pdfnative — PDF Stream Filter Decoders
+ * ========================================
+ * Pure, zero-dependency decoders for the standard PDF stream filters that
+ * are not handled by {@link inflateSync} (FlateDecode).
+ *
+ * Implemented filters (ISO 32000-1 §7.4):
+ *   - ASCIIHexDecode  (§7.4.2)
+ *   - ASCII85Decode   (§7.4.3)
+ *   - LZWDecode       (§7.4.4)  — variable-width 9..12 bit codes
+ *   - RunLengthDecode (§7.4.5)
+ *
+ * @since 1.1.0
+ */
+/**
+ * Decode an ASCIIHexDecode stream. Two hex digits encode one byte.
+ * Whitespace is ignored; `>` terminates the stream. An odd trailing digit
+ * is treated as if followed by `0` (per ISO 32000-1 §7.4.2).
+ */
+declare function decodeASCIIHex(data: Uint8Array): Uint8Array;
+/**
+ * Decode an ASCII85Decode stream (Adobe variant).
+ *
+ * Five base-85 digits in the range `!`..`u` encode four bytes. The shorthand
+ * `z` represents four zero bytes. The end-of-data marker is `~>`. Whitespace
+ * is ignored. A short final group (1..4 digits) decodes to (count-1) bytes
+ * with the missing digits taken as `u` (84) and the trailing bytes discarded.
+ */
+declare function decodeASCII85(data: Uint8Array): Uint8Array;
+/**
+ * Decode an LZWDecode stream with variable-width codes (9–12 bits) and
+ * automatic table reset on the CLEAR code (256). Terminates on the EOD
+ * code (257) per ISO 32000-1 §7.4.4. EarlyChange is fixed to 1 (the PDF
+ * default); callers that need a different value should pass it explicitly
+ * via `DecodeParms`, which is currently not honoured here (rare in PDF).
+ */
+declare function decodeLZW(data: Uint8Array): Uint8Array;
+/**
+ * Decode a RunLengthDecode stream. Each control byte `n`:
+ *   - 0..127: copy the next `n+1` bytes literally
+ *   - 128:    EOD
+ *   - 129..255: repeat the next byte `257 - n` times
+ */
+declare function decodeRunLength(data: Uint8Array): Uint8Array;
+/**
+ * Apply a single PDF stream filter by name. Returns the input unchanged
+ * for unsupported filters (callers should detect this via the return
+ * value being identical or by pre-checking against {@link KNOWN_FILTERS}).
+ *
+ * Supports: FlateDecode is NOT handled here (use `inflateSync` instead);
+ * this function dispatches the non-deflate filter family.
+ */
+declare function applyDecodeFilter(name: string, data: Uint8Array): Uint8Array;
+/** Known non-Flate decode filter names (for membership checks). */
+declare const KNOWN_DECODE_FILTERS: Set<string>;
+
 /**
  * pdfnative — Worker API
  * ========================
@@ -2635,4 +3176,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, 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, 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, decodeEcPublicKey, 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, 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 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 };