@libpdf/core 0.2.12 → 0.3.1

package/dist/index.d.mts

@@ -1659,6 +1659,143 @@ declare class Operator {
   byteLength(): number;
 }
 //#endregion
+//#region src/fonts/font-descriptor.d.ts
+interface FontDescriptorData {
+  fontName: string;
+  flags: number;
+  fontBBox: [number, number, number, number];
+  italicAngle: number;
+  ascent: number;
+  descent: number;
+  leading: number;
+  capHeight: number;
+  xHeight: number;
+  stemV: number;
+  stemH: number;
+  avgWidth: number;
+  maxWidth: number;
+  missingWidth: number;
+}
+/**
+ * FontDescriptor contains font metrics and flags.
+ */
+declare class FontDescriptor {
+  readonly fontName: string;
+  readonly flags: number;
+  readonly fontBBox: [number, number, number, number];
+  readonly italicAngle: number;
+  readonly ascent: number;
+  readonly descent: number;
+  readonly leading: number;
+  readonly capHeight: number;
+  readonly xHeight: number;
+  readonly stemV: number;
+  readonly stemH: number;
+  readonly avgWidth: number;
+  readonly maxWidth: number;
+  readonly missingWidth: number;
+  constructor(data: FontDescriptorData);
+  /** Check if font is fixed-pitch (monospace) */
+  get isFixedPitch(): boolean;
+  /** Check if font is serif */
+  get isSerif(): boolean;
+  /** Check if font is symbolic (uses custom encoding) */
+  get isSymbolic(): boolean;
+  /** Check if font is script (cursive) */
+  get isScript(): boolean;
+  /** Check if font is non-symbolic (uses standard encoding) */
+  get isNonSymbolic(): boolean;
+  /** Check if font is italic */
+  get isItalic(): boolean;
+  /** Check if font is all caps */
+  get isAllCap(): boolean;
+  /** Check if font is small caps */
+  get isSmallCap(): boolean;
+  /** Check if font should be bold */
+  get isForceBold(): boolean;
+  /**
+   * Parse FontDescriptor from a PDF dictionary.
+   */
+  static parse(dict: PdfDict): FontDescriptor;
+}
+//#endregion
+//#region src/fonts/font-program/base.d.ts
+/**
+ * FontProgram - Interface bridging PDF fonts to fontbox font parsers.
+ *
+ * This provides a unified interface for accessing font data regardless
+ * of the underlying font format (TrueType, CFF, Type1).
+ */
+/**
+ * Font program types that can be embedded in PDFs.
+ */
+type FontProgramType = "truetype" | "cff" | "cff-cid" | "type1";
+/**
+ * Common interface for all font program types.
+ *
+ * Provides access to metrics and glyph mapping without needing
+ * to know the underlying font format.
+ */
+interface FontProgram {
+  /** Type of font program */
+  readonly type: FontProgramType;
+  /** Number of glyphs in the font */
+  readonly numGlyphs: number;
+  /** Units per em (typically 1000 for PostScript, 2048 for TrueType) */
+  readonly unitsPerEm: number;
+  /** Font bounding box [xMin, yMin, xMax, yMax] */
+  readonly bbox: readonly [number, number, number, number];
+  /** PostScript name of the font */
+  readonly postScriptName: string | undefined;
+  /** Family name */
+  readonly familyName: string | undefined;
+  /** Whether font is fixed-pitch (monospace) */
+  readonly isFixedPitch: boolean;
+  /** Italic angle in degrees */
+  readonly italicAngle: number;
+  /** Ascent in font units */
+  readonly ascent: number;
+  /** Descent in font units (typically negative) */
+  readonly descent: number;
+  /** Cap height in font units */
+  readonly capHeight: number;
+  /** x-height in font units */
+  readonly xHeight: number;
+  /** Stem vertical width (for hinting) */
+  readonly stemV: number;
+  /**
+   * Get glyph ID for a Unicode code point.
+   * Returns 0 (.notdef) if the character is not in the font.
+   */
+  getGlyphId(codePoint: number): number;
+  /**
+   * Get advance width for a glyph ID in font units.
+   */
+  getAdvanceWidth(glyphId: number): number;
+  /**
+   * Check if the font has a glyph for the given code point.
+   */
+  hasGlyph(codePoint: number): boolean;
+  /**
+   * Check if the font has renderable glyph outlines.
+   *
+   * Some PDF subsetted fonts are "crippled" — they contain glyph metrics
+   * and cmap data but no actual outline data (0 contours for all glyphs).
+   * These fonts are used only for text extraction and cannot render text.
+   *
+   * Returns true if at least some common glyphs have actual outline data.
+   */
+  hasRenderableGlyphs(): boolean;
+  /**
+   * Check if a specific glyph has renderable outlines or charstring data.
+   */
+  hasRenderableGlyph(glyphId: number): boolean;
+  /**
+   * Get the raw font data.
+   */
+  getData(): Uint8Array;
+}
+//#endregion
 //#region src/io/binary-scanner.d.ts
 /**
  * Scanner extended with big-endian binary reading methods.
@@ -2461,127 +2598,181 @@ declare class TrueTypeFont implements TrueTypeFontAccess {
   private parseTable;
 }
 //#endregion
-//#region src/fonts/font-descriptor.d.ts
-interface FontDescriptorData {
-  fontName: string;
-  flags: number;
-  fontBBox: [number, number, number, number];
-  italicAngle: number;
-  ascent: number;
-  descent: number;
-  leading: number;
-  capHeight: number;
-  xHeight: number;
-  stemV: number;
-  stemH: number;
-  avgWidth: number;
-  maxWidth: number;
-  missingWidth: number;
-}
+//#region src/fonts/to-unicode.d.ts
 /**
- * FontDescriptor contains font metrics and flags.
+ * ToUnicode CMap parser for text extraction.
+ *
+ * ToUnicode CMaps map character codes to Unicode strings, enabling
+ * text extraction from PDF content streams.
+ *
+ * Format (from PDF spec):
+ * - beginbfchar/endbfchar: Individual character mappings
+ *   <srcCode> <dstString>
+ *
+ * - beginbfrange/endbfrange: Range mappings
+ *   <srcCodeLo> <srcCodeHi> <dstString>  - incrementing range
+ *   <srcCodeLo> <srcCodeHi> [<dst1> <dst2> ...] - array of destinations
  */
-declare class FontDescriptor {
-  readonly fontName: string;
-  readonly flags: number;
-  readonly fontBBox: [number, number, number, number];
-  readonly italicAngle: number;
-  readonly ascent: number;
-  readonly descent: number;
-  readonly leading: number;
-  readonly capHeight: number;
-  readonly xHeight: number;
-  readonly stemV: number;
-  readonly stemH: number;
-  readonly avgWidth: number;
-  readonly maxWidth: number;
-  readonly missingWidth: number;
-  constructor(data: FontDescriptorData);
-  /** Check if font is fixed-pitch (monospace) */
-  get isFixedPitch(): boolean;
-  /** Check if font is serif */
-  get isSerif(): boolean;
-  /** Check if font is symbolic (uses custom encoding) */
-  get isSymbolic(): boolean;
-  /** Check if font is script (cursive) */
-  get isScript(): boolean;
-  /** Check if font is non-symbolic (uses standard encoding) */
-  get isNonSymbolic(): boolean;
-  /** Check if font is italic */
-  get isItalic(): boolean;
-  /** Check if font is all caps */
-  get isAllCap(): boolean;
-  /** Check if font is small caps */
-  get isSmallCap(): boolean;
-  /** Check if font should be bold */
-  get isForceBold(): boolean;
+/**
+ * ToUnicode map for converting character codes to Unicode strings.
+ */
+declare class ToUnicodeMap {
+  private readonly map;
+  constructor(map?: Map<number, string>);
   /**
-   * Parse FontDescriptor from a PDF dictionary.
+   * Get the Unicode string for a character code.
    */
-  static parse(dict: PdfDict): FontDescriptor;
+  get(code: number): string | undefined;
+  /**
+   * Check if a character code has a mapping.
+   */
+  has(code: number): boolean;
+  /**
+   * Set a mapping from character code to Unicode string.
+   */
+  set(code: number, unicode: string): void;
+  /**
+   * Get the number of mappings.
+   */
+  get size(): number;
+  /**
+   * Iterate over all mappings.
+   */
+  forEach(callback: (unicode: string, code: number) => void): void;
+  /**
+   * Get the underlying map (for advanced use).
+   */
+  getMap(): Map<number, string>;
 }
 //#endregion
-//#region src/fonts/font-program/base.d.ts
+//#region src/fonts/cid-font.d.ts
+type CIDFontSubtype = "CIDFontType0" | "CIDFontType2";
 /**
- * FontProgram - Interface bridging PDF fonts to fontbox font parsers.
- *
- * This provides a unified interface for accessing font data regardless
- * of the underlying font format (TrueType, CFF, Type1).
+ * CID System Info describes the character collection.
  */
+interface CIDSystemInfo {
+  registry: string;
+  ordering: string;
+  supplement: number;
+}
 /**
- * Font program types that can be embedded in PDFs.
+ * CIDFont handles CID-keyed fonts (descendants of Type0).
  */
-type FontProgramType = "truetype" | "cff" | "cff-cid" | "type1";
+declare class CIDFont {
+  /** Font subtype (CIDFontType0 = CFF, CIDFontType2 = TrueType) */
+  readonly subtype: CIDFontSubtype;
+  /** Base font name */
+  readonly baseFontName: string;
+  /** CID System Info */
+  readonly cidSystemInfo: CIDSystemInfo;
+  /** Font descriptor with metrics */
+  readonly descriptor: FontDescriptor | null;
+  /** Default width for CIDs not in /W array */
+  readonly defaultWidth: number;
+  /** Width map from /W array */
+  private readonly widths;
+  /** CID to GID mapping (null = Identity, Uint16Array = explicit map) */
+  private readonly cidToGidMap;
+  /** Inverse CID to GID map: GID → CID (built lazily for stream-based maps) */
+  private gidToCidMap;
+  /** Embedded font program (if available) */
+  private readonly embeddedProgram;
+  /** ToUnicode map from the parent Type0 font, if available */
+  private readonly toUnicodeMap;
+  /** Reverse ToUnicode map: Unicode code point -> character code */
+  private unicodeToCharCodeMap;
+  constructor(options: {
+    subtype: CIDFontSubtype;
+    baseFontName: string;
+    cidSystemInfo?: CIDSystemInfo;
+    descriptor?: FontDescriptor | null;
+    defaultWidth?: number;
+    widths?: CIDWidthMap;
+    cidToGidMap?: "Identity" | Uint16Array | null;
+    embeddedProgram?: FontProgram | null;
+    toUnicodeMap?: ToUnicodeMap | null;
+  });
+  /**
+   * Check if an embedded font program is available.
+   */
+  get hasEmbeddedProgram(): boolean;
+  /**
+   * Check if the embedded font program has renderable glyph outlines.
+   *
+   * Some PDFs embed fonts with metrics and cmap data but stripped outlines.
+   * These fonts are usable for text extraction but cannot render new text.
+   */
+  get hasRenderableGlyphs(): boolean;
+  /**
+   * Check whether the embedded program can render a glyph for the given CID.
+   */
+  hasRenderableGlyphForCID(cid: number): boolean;
+  /**
+   * Get the embedded font program, if available.
+   */
+  getEmbeddedProgram(): FontProgram | null;
+  /**
+   * Get width for a CID in glyph units (1000 = 1 em).
+   */
+  getWidth(cid: number): number;
+  /**
+   * Get GID (glyph index) for a CID.
+   * Used when accessing embedded font data.
+   */
+  getGid(cid: number): number;
+  /**
+   * Whether the CIDToGIDMap is Identity (or absent, which defaults to Identity).
+   */
+  get isIdentityCidToGid(): boolean;
+  /**
+   * Get the character code (= CID for Identity-H) to write in a PDF string
+   * for a given Unicode code point.
+   *
+   * The encoding pipeline for Identity-H is:
+   *   character code (in PDF string) = CID (because Identity-H maps 1:1)
+   *   CID → GID (via CIDToGIDMap)
+   *   GID → glyph in font file
+   *
+   * We need to find the character code such that after the CIDToGIDMap
+   * transformation, we get the GID corresponding to the desired Unicode
+   * character in the embedded font program.
+   *
+   * For Identity CIDToGIDMap: charCode = CID = GID = fontProgram.getGlyphId(unicode)
+   * For stream CIDToGIDMap: charCode = CID where CIDToGIDMap[CID] = desired GID
+   */
+  getCharCodeForUnicode(unicode: number): number;
+  /**
+   * Try to resolve the character code (= CID for Identity-H) for a Unicode
+   * code point. Returns null when the mapping cannot be proven.
+   */
+  tryGetCharCodeForUnicode(unicode: number): number | null;
+  private getCharCodeForGid;
+}
 /**
- * Common interface for all font program types.
- *
- * Provides access to metrics and glyph mapping without needing
- * to know the underlying font format.
+ * Efficient storage for CID width mappings.
+ * Handles the complex /W array format from PDF.
  */
-interface FontProgram {
-  /** Type of font program */
-  readonly type: FontProgramType;
-  /** Number of glyphs in the font */
-  readonly numGlyphs: number;
-  /** Units per em (typically 1000 for PostScript, 2048 for TrueType) */
-  readonly unitsPerEm: number;
-  /** Font bounding box [xMin, yMin, xMax, yMax] */
-  readonly bbox: readonly [number, number, number, number];
-  /** PostScript name of the font */
-  readonly postScriptName: string | undefined;
-  /** Family name */
-  readonly familyName: string | undefined;
-  /** Whether font is fixed-pitch (monospace) */
-  readonly isFixedPitch: boolean;
-  /** Italic angle in degrees */
-  readonly italicAngle: number;
-  /** Ascent in font units */
-  readonly ascent: number;
-  /** Descent in font units (typically negative) */
-  readonly descent: number;
-  /** Cap height in font units */
-  readonly capHeight: number;
-  /** x-height in font units */
-  readonly xHeight: number;
-  /** Stem vertical width (for hinting) */
-  readonly stemV: number;
+declare class CIDWidthMap {
+  /** Individual CID -> width mappings */
+  private readonly individual;
+  /** Range mappings: all CIDs in range have same width */
+  private readonly ranges;
   /**
-   * Get glyph ID for a Unicode code point.
-   * Returns 0 (.notdef) if the character is not in the font.
+   * Get width for a CID.
    */
-  getGlyphId(codePoint: number): number;
+  get(cid: number): number | undefined;
   /**
-   * Get advance width for a glyph ID in font units.
+   * Set width for a single CID.
    */
-  getAdvanceWidth(glyphId: number): number;
+  set(cid: number, width: number): void;
   /**
-   * Check if the font has a glyph for the given code point.
+   * Add a range where all CIDs have the same width.
    */
-  hasGlyph(codePoint: number): boolean;
+  addRange(start: number, end: number, width: number): void;
   /**
-   * Get the raw font data.
+   * Get the number of individual mappings.
    */
-  getData(): Uint8Array;
+  get size(): number;
 }
 //#endregion
 //#region src/fonts/pdf-font.d.ts
@@ -2922,53 +3113,6 @@ interface FontEncoding {
   getCode(unicode: number): number | undefined;
 }
 //#endregion
-//#region src/fonts/to-unicode.d.ts
-/**
- * ToUnicode CMap parser for text extraction.
- *
- * ToUnicode CMaps map character codes to Unicode strings, enabling
- * text extraction from PDF content streams.
- *
- * Format (from PDF spec):
- * - beginbfchar/endbfchar: Individual character mappings
- *   <srcCode> <dstString>
- *
- * - beginbfrange/endbfrange: Range mappings
- *   <srcCodeLo> <srcCodeHi> <dstString>  - incrementing range
- *   <srcCodeLo> <srcCodeHi> [<dst1> <dst2> ...] - array of destinations
- */
-/**
- * ToUnicode map for converting character codes to Unicode strings.
- */
-declare class ToUnicodeMap {
-  private readonly map;
-  constructor(map?: Map<number, string>);
-  /**
-   * Get the Unicode string for a character code.
-   */
-  get(code: number): string | undefined;
-  /**
-   * Check if a character code has a mapping.
-   */
-  has(code: number): boolean;
-  /**
-   * Set a mapping from character code to Unicode string.
-   */
-  set(code: number, unicode: string): void;
-  /**
-   * Get the number of mappings.
-   */
-  get size(): number;
-  /**
-   * Iterate over all mappings.
-   */
-  forEach(callback: (unicode: string, code: number) => void): void;
-  /**
-   * Get the underlying map (for advanced use).
-   */
-  getMap(): Map<number, string>;
-}
-//#endregion
 //#region src/fonts/simple-font.d.ts
 type SimpleFontSubtype = "TrueType" | "Type1" | "Type3" | "MMType1";
 /**
@@ -3059,31 +3203,60 @@ type FormFont = EmbeddedFont | ExistingFont;
  * This is a lightweight wrapper for fonts already present in the PDF,
  * typically from the AcroForm's /DR (Default Resources) dictionary.
  *
- * Provides limited metrics based on Standard 14 font data for common fonts.
+ * Supports both simple fonts (Type1, TrueType) and CID fonts (Type0).
+ * CID fonts use 2-byte character codes and are commonly used with
+ * Identity-H/Identity-V encoding for CJK and Unicode text.
  */
 declare class ExistingFont {
-  /** Font name as it appears in the PDF (e.g., "Helv", "ZaDb") */
+  /** Font name as it appears in the PDF (e.g., "Helv", "ZaDb", "F0") */
   readonly name: string;
   /** Reference to font object in PDF (may be null for inline Standard 14 fonts) */
   readonly ref: PdfRef | null;
-  /** Underlying SimpleFont if resolved from PDF */
+  /** Whether this is a CID-keyed font (Type0 with Identity-H/V encoding) */
+  readonly isCIDFont: boolean;
+  /** Underlying SimpleFont if resolved from PDF (for non-CID fonts) */
   private readonly simpleFont;
+  /** Underlying CIDFont if resolved from PDF (for CID fonts) */
+  private readonly cidFont;
   /** Standard 14 font name if this maps to one (e.g., "Helvetica" for "Helv") */
   private readonly standardFontName;
-  constructor(name: string, ref: PdfRef | null, simpleFont?: SimpleFont | null);
+  constructor(name: string, ref: PdfRef | null, simpleFont?: SimpleFont | null, isCIDFont?: boolean, cidFont?: CIDFont | null);
+  /**
+   * Check whether this font can be safely used to generate an appearance for
+   * the given text.
+   */
+  canUseForAppearance(text: string): boolean;
   /**
    * Check if font can encode the given text.
    *
-   * For existing fonts, this is always true for ASCII text.
-   * For non-ASCII, returns false (can't verify without full font data).
+   * CID fonts with Identity-H/V encoding can encode any BMP character.
+   * Simple fonts are limited to their encoding (typically Latin-1).
    */
   canEncode(text: string): boolean;
   /**
    * Encode text to character codes for this font.
    *
-   * For existing fonts, uses WinAnsi encoding (0-255).
+   * For CID fonts: returns 2-byte Unicode code points (Identity-H/V encoding).
+   * For simple fonts: uses the font's encoding (WinAnsi, custom, etc.).
    */
   encodeText(text: string): number[];
+  /**
+   * Encode text as bytes for use in a PdfString.
+   *
+   * For CID fonts with Identity-H/V encoding, the character codes in the
+   * PDF string are CIDs. With Identity CIDToGIDMap, CID = GID, so the
+   * character code must equal the glyph ID in the font program.
+   *
+   * The encoding pipeline is:
+   *   Unicode code point → GID (via font program cmap)
+   *   → character code to write (= CID that maps to that GID)
+   *
+   * For Identity CIDToGIDMap: write GID directly (CID = GID)
+   * For stream CIDToGIDMap: find CID where CIDToGIDMap[CID] = GID
+   *
+   * For simple fonts, produces single-byte codes.
+   */
+  encodeTextToBytes(text: string): Uint8Array;
   /**
    * Get width of text in points at a given font size.
    */
@@ -3100,6 +3273,10 @@ declare class ExistingFont {
    * Get cap height in points at a given font size.
    */
   getCapHeight(fontSize: number): number;
+  /**
+   * Look up a font metric from the descriptor, Standard 14 tables, or a fallback ratio.
+   */
+  private getMetric;
 }
 //#endregion
 //#region src/document/forms/widget-annotation.d.ts
@@ -10178,6 +10355,8 @@ declare class CryptoKeySigner implements Signer {
 //#region src/signatures/signers/google-kms.d.ts
 /** KMS client type - dynamically imported */
 type KeyManagementServiceClient = _google_cloud_kms0.KeyManagementServiceClient;
+/** Subset of methods actually used for signing */
+type KmsClient = Pick<KeyManagementServiceClient, "asymmetricSign" | "getCryptoKeyVersion" | "getPublicKey">;
 /** Secret Manager client type - dynamically imported */
 type SecretManagerServiceClient = _google_cloud_secret_manager0.SecretManagerServiceClient;
 /** Base options shared by both key reference styles */
@@ -10191,7 +10370,7 @@ interface GoogleKmsSignerBaseOptions {
   /** Timeout for AIA chain building in ms (default: 15000) */
   chainTimeout?: number;
   /** Pre-configured KMS client (optional, uses ADC if not provided) */
-  client?: KeyManagementServiceClient;
+  client?: KmsClient;
 }
 /** Full resource name style */
 interface GoogleKmsSignerFullNameOptions extends GoogleKmsSignerBaseOptions {
@@ -10329,6 +10508,8 @@ declare class GoogleKmsSigner implements Signer {
   /**
    * Hash data using the specified algorithm.
    *
+   * Uses the Web Crypto API for native-speed hashing.
+   *
    * @returns The digest bytes and the KMS digest key name
    */
   private hashData;