@libpdf/core 0.0.1-beta.6 → 0.0.1-beta.8

package/dist/index.d.mts

@@ -1,4 +1,3 @@
-import { z } from "zod";
 import * as _google_cloud_kms0 from "@google-cloud/kms";
 import * as _google_cloud_secret_manager0 from "@google-cloud/secret-manager";
 
@@ -1212,7 +1211,7 @@ declare class PdfStream extends PdfDict {
    * @returns Decoded data
    * @throws {Error} if a filter fails or is unknown
    */
-  getDecodedData(): Promise<Uint8Array>;
+  getDecodedData(): Uint8Array;
   /**
    * Get the encoded (compressed) stream data.
    *
@@ -1228,7 +1227,7 @@ declare class PdfStream extends PdfDict {
    *
    * @returns Encoded data (compressed if filters are specified)
    */
-  getEncodedData(): Promise<Uint8Array>;
+  getEncodedData(): Uint8Array;
   /**
    * Build filter specs from /Filter and /DecodeParms entries.
    */
@@ -1931,6 +1930,12 @@ interface Permissions {
 }
 //#endregion
 //#region src/security/schemas.d.ts
+/**
+ * Zod schemas for PDF encryption dictionary validation.
+ *
+ * These schemas provide type-safe parsing of encryption parameters
+ * with proper validation and TypeScript type inference.
+ */
 /**
  * Valid encryption versions (V entry).
  *
@@ -1940,8 +1945,7 @@ interface Permissions {
  * - 4: AES-128 or RC4 with crypt filters (PDF 1.5)
  * - 5: AES-256 (PDF 2.0)
  */
-declare const VersionSchema: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
-type Version = z.infer<typeof VersionSchema>;
+type EncryptionVersion = 1 | 2 | 3 | 4 | 5;
 /**
  * Valid encryption revisions (R entry).
  *
@@ -1951,25 +1955,31 @@ type Version = z.infer<typeof VersionSchema>;
  * - 5: V=5, AES-256 (draft, Adobe Extension Level 3)
  * - 6: V=5, AES-256 (final, ISO 32000-2)
  */
-declare const RevisionSchema: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>;
-type Revision = z.infer<typeof RevisionSchema>;
+type EncryptionRevision = 2 | 3 | 4 | 5 | 6;
+/**
+ * Crypt filter methods (CFM entry).
+ *
+ * - None: Identity (no encryption)
+ * - V2: RC4
+ * - AESV2: AES-128
+ * - AESV3: AES-256
+ */
+type CryptFilterMethod = "None" | "V2" | "AESV2" | "AESV3";
+/**
+ * Authentication events (AuthEvent entry).
+ *
+ * - DocOpen: Authentication when document is opened
+ * - EFOpen: Authentication when embedded file is accessed
+ */
+type AuthEvent = "DocOpen" | "EFOpen";
 /**
  * Complete crypt filter configuration.
  */
-declare const CryptFilterSchema: z.ZodObject<{
-  cfm: z.ZodEnum<{
-    None: "None";
-    V2: "V2";
-    AESV2: "AESV2";
-    AESV3: "AESV3";
-  }>;
-  authEvent: z.ZodOptional<z.ZodEnum<{
-    DocOpen: "DocOpen";
-    EFOpen: "EFOpen";
-  }>>;
-  length: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-type CryptFilter = z.infer<typeof CryptFilterSchema>;
+interface CryptFilter {
+  cfm: CryptFilterMethod;
+  authEvent?: AuthEvent;
+  length?: number;
+}
 /**
  * Supported encryption algorithms.
  *
@@ -1977,12 +1987,7 @@ type CryptFilter = z.infer<typeof CryptFilterSchema>;
  * - AES-128: AES with 128-bit key (R4)
  * - AES-256: AES with 256-bit key (R5-R6)
  */
-declare const EncryptionAlgorithmSchema: z.ZodEnum<{
-  RC4: "RC4";
-  "AES-128": "AES-128";
-  "AES-256": "AES-256";
-}>;
-type EncryptionAlgorithm = z.infer<typeof EncryptionAlgorithmSchema>;
+type EncryptionAlgorithm = "RC4" | "AES-128" | "AES-256";
 //#endregion
 //#region src/security/errors.d.ts
 /**
@@ -2021,9 +2026,9 @@ interface EncryptionDict {
   /** Security handler filter (always "Standard" for this implementation) */
   filter: "Standard";
   /** Algorithm version: 1, 2, 3, 4, or 5 */
-  version: Version;
+  version: EncryptionVersion;
   /** Standard security handler revision: 2, 3, 4, 5, or 6 */
-  revision: Revision;
+  revision: EncryptionRevision;
   /** Key length in bits (40-256) */
   keyLengthBits: number;
   /** Owner password verification value (32 bytes for R2-R4, 48 bytes for R5-R6) */
@@ -2120,11 +2125,11 @@ declare class StandardSecurityHandler {
   /**
    * Get the encryption version.
    */
-  get version(): Version;
+  get version(): EncryptionVersion;
   /**
    * Get the encryption revision.
    */
-  get revision(): Revision;
+  get revision(): EncryptionRevision;
   /**
    * Get document permissions.
    */
@@ -2478,8 +2483,8 @@ interface SignOptions {
  * Warning emitted during signing.
  */
 interface SignWarning {
-  /** Warning code */
-  code: "MDP_VIOLATION" | "CHAIN_INCOMPLETE" | string;
+  /** Warning code (e.g., "MDP_VIOLATION", "CHAIN_INCOMPLETE") */
+  code: "MDP_VIOLATION" | "CHAIN_INCOMPLETE" | (string & {});
   /** Human-readable message */
   message: string;
 }
@@ -2699,8 +2704,12 @@ interface FindTextOptions {
 /**
  * Function to resolve objects not yet in the registry.
  * Called when resolve() encounters an unknown reference.
+ *
+ * This is synchronous because all PDF data is loaded into memory
+ * at parse time. The resolver simply parses objects on demand from
+ * the in-memory buffer.
  */
-type ObjectResolver = (ref: PdfRef) => Promise<PdfObject | null>;
+type ObjectResolver = (ref: PdfRef) => PdfObject | null;
 /**
  * Registry for managing PDF objects and their references.
  *
@@ -2795,7 +2804,7 @@ declare class ObjectRegistry {
    * @param ref - The reference to resolve
    * @returns The object, or null if not found
    */
-  resolve(ref: PdfRef): Promise<PdfObject | null>;
+  resolve(ref: PdfRef): PdfObject | null;
   /**
    * Add a warning message.
    */
@@ -2836,8 +2845,10 @@ declare class ObjectRegistry {
 //#region src/document/name-tree.d.ts
 /**
  * Function to resolve a reference to its object.
+ *
+ * Synchronous because all PDF data is loaded into memory at parse time.
  */
-type Resolver = (ref: PdfRef) => Promise<PdfObject | null>;
+type Resolver = (ref: PdfRef) => PdfObject | null;
 /**
  * PDF Name Tree reader.
  *
@@ -2855,20 +2866,20 @@ declare class NameTree {
    *
    * @returns The value if found, null otherwise
    */
-  get(key: string): Promise<PdfObject | null>;
+  get(key: string): PdfObject | null;
   /**
    * Check if a key exists in the tree.
    */
-  has(key: string): Promise<boolean>;
+  has(key: string): boolean;
   /**
    * Iterate all entries (lazy, yields [key, value] pairs).
    * Uses BFS traversal with cycle detection.
    */
-  entries(): AsyncGenerator<[string, PdfObject]>;
+  entries(): Generator<[string, PdfObject]>;
   /**
    * Load all entries into a Map (cached after first call).
    */
-  getAll(): Promise<ReadonlyMap<string, PdfObject>>;
+  getAll(): ReadonlyMap<string, PdfObject>;
   /**
    * Check if all entries have been loaded into cache.
    */
@@ -2903,24 +2914,24 @@ declare class PDFCatalog {
   /**
    * Get the /Names dictionary.
    */
-  getNames(): Promise<PdfDict | null>;
+  getNames(): PdfDict | null;
   /**
    * Get or create the /Names dictionary.
    */
-  getOrCreateNames(): Promise<PdfDict>;
+  getOrCreateNames(): PdfDict;
   /**
    * Get the EmbeddedFiles name tree.
    * Caches the result for repeated access.
    */
-  getEmbeddedFilesTree(): Promise<NameTree | null>;
+  getEmbeddedFilesTree(): NameTree | null;
   /**
    * Set the EmbeddedFiles name tree.
    */
-  setEmbeddedFilesTree(treeDict: PdfDict): Promise<void>;
+  setEmbeddedFilesTree(treeDict: PdfDict): void;
   /**
    * Remove the EmbeddedFiles entry from /Names.
    */
-  removeEmbeddedFilesTree(): Promise<void>;
+  removeEmbeddedFilesTree(): void;
   /**
    * Clear all cached name trees.
    * Call this after modifying the catalog structure.
@@ -2954,9 +2965,8 @@ declare class PDFPageTree {
   private constructor();
   /**
    * Load and build the page tree by walking from the root.
-   * This is the only async operation.
    */
-  static load(pagesRef: PdfRef, getObject: (ref: PdfRef) => Promise<PdfObject | null>): Promise<PDFPageTree>;
+  static load(pagesRef: PdfRef, getObject: (ref: PdfRef) => PdfObject | null): PDFPageTree;
   /**
    * Create an empty page tree.
    * Note: This creates a minimal tree without a backing PDF structure.
@@ -3080,9 +3090,13 @@ declare class PDFContext {
    */
   register(obj: PdfObject): PdfRef;
   /**
-   * Resolve an object by reference (async, fetches if needed).
+   * Resolve an object by reference.
+   *
+   * Synchronously resolves the reference, parsing from the in-memory
+   * buffer if not already cached. All PDF data is loaded at parse time,
+   * so this operation never requires I/O.
    */
-  resolve(ref: PdfRef): Promise<PdfObject | null>;
+  resolve(ref: PdfRef): PdfObject | null;
   /**
    * Get an object by reference (sync, only if already loaded).
    */
@@ -3122,7 +3136,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  list(): Promise<Map<string, AttachmentInfo>>;
+  list(): Map<string, AttachmentInfo>;
   /**
    * Get the raw bytes of an attachment.
    *
@@ -3138,7 +3152,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  get(name: string): Promise<Uint8Array | null>;
+  get(name: string): Uint8Array | null;
   /**
    * Check if an attachment exists.
    *
@@ -3152,7 +3166,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  has(name: string): Promise<boolean>;
+  has(name: string): boolean;
   /**
    * Add a file attachment to the document.
    *
@@ -3176,7 +3190,7 @@ declare class PDFAttachments {
    * await pdf.attachments.add("report.pdf", newBytes, { overwrite: true });
    * ```
    */
-  add(name: string, data: Uint8Array, options?: AddAttachmentOptions): Promise<void>;
+  add(name: string, data: Uint8Array, options?: AddAttachmentOptions): void;
   /**
    * Remove an attachment from the document.
    *
@@ -3191,7 +3205,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  remove(name: string): Promise<boolean>;
+  remove(name: string): boolean;
 }
 //#endregion
 //#region src/helpers/colors.d.ts
@@ -3566,8 +3580,8 @@ interface PolylineAnnotationOptions {
 interface StampAnnotationOptions {
   /** Annotation rectangle */
   rect: Rect;
-  /** Standard stamp name */
-  name?: StampName | string;
+  /** Stamp name (use StampName constants for standard stamps, or any string for custom) */
+  name?: StampName | (string & {});
   /** Text content/comment */
   contents?: string;
 }
@@ -3722,15 +3736,15 @@ declare class PDFAnnotation {
   /**
    * Get the normal appearance stream.
    */
-  getNormalAppearance(): Promise<PdfStream | null>;
+  getNormalAppearance(): PdfStream | null;
   /**
    * Get the rollover appearance stream.
    */
-  getRolloverAppearance(): Promise<PdfStream | null>;
+  getRolloverAppearance(): PdfStream | null;
   /**
    * Get the down appearance stream.
    */
-  getDownAppearance(): Promise<PdfStream | null>;
+  getDownAppearance(): PdfStream | null;
   /**
    * Set the normal appearance stream.
    */
@@ -3829,7 +3843,7 @@ declare class PDFMarkupAnnotation extends PDFAnnotation {
   /**
    * Get the associated popup annotation, if any.
    */
-  getPopup(): Promise<PDFPopupAnnotation | null>;
+  getPopup(): PDFPopupAnnotation | null;
   /**
    * Create a popup annotation associated with this annotation.
    * The popup is added to the parent annotation and registered.
@@ -3885,11 +3899,11 @@ declare class PDFFileAttachmentAnnotation extends PDFMarkupAnnotation {
   /**
    * Get the file specification dictionary.
    */
-  getFileSpec(): Promise<PdfDict | null>;
+  getFileSpec(): PdfDict | null;
   /**
    * Get the file name from the file specification.
    */
-  getFileName(): Promise<string | null>;
+  getFileName(): string | null;
 }
 //#endregion
 //#region src/annotations/free-text.d.ts
@@ -4062,7 +4076,7 @@ declare class PDFLinkAnnotation extends PDFAnnotation {
   /**
    * Get the parsed link action.
    */
-  getAction(): Promise<LinkAction>;
+  getAction(): LinkAction;
   /**
    * Highlight mode when the link is clicked.
    */
@@ -4194,7 +4208,7 @@ declare class PDFStampAnnotation extends PDFMarkupAnnotation {
   /**
    * Set the stamp name.
    */
-  setStampName(name: StampName | string): void;
+  setStampName(name: StampName | (string & {})): void;
   /**
    * Check if this is a standard stamp.
    */
@@ -4646,15 +4660,15 @@ declare class WidgetAnnotation {
    * Get normal appearance stream.
    * For stateful widgets (checkbox/radio), pass the state name.
    */
-  getNormalAppearance(state?: string): Promise<PdfStream | null>;
+  getNormalAppearance(state?: string): PdfStream | null;
   /**
    * Get rollover appearance stream (shown on mouse hover).
    */
-  getRolloverAppearance(state?: string): Promise<PdfStream | null>;
+  getRolloverAppearance(state?: string): PdfStream | null;
   /**
    * Get down appearance stream (shown when clicked).
    */
-  getDownAppearance(state?: string): Promise<PdfStream | null>;
+  getDownAppearance(state?: string): PdfStream | null;
   /**
    * Get border style.
    */
@@ -4676,7 +4690,7 @@ declare class WidgetAnnotation {
  */
 interface AcroFormLike {
   defaultQuadding: number;
-  updateFieldAppearance?(field: TerminalField): Promise<void>;
+  updateFieldAppearance?(field: TerminalField): void;
 }
 /**
  * Field type identifiers.
@@ -4865,7 +4879,7 @@ declare abstract class TerminalField extends FormField {
    *
    * @internal
    */
-  resolveWidgets(): Promise<void>;
+  resolveWidgets(): void;
   /**
    * Resolve MK dictionary if it's a reference.
    * This ensures getAppearanceCharacteristics() can work synchronously.
@@ -4887,7 +4901,7 @@ declare abstract class TerminalField extends FormField {
    * This method is async because it regenerates the field's appearance
    * stream after resetting the value.
    */
-  resetValue(): Promise<void>;
+  resetValue(): void;
   /**
    * Check read-only and throw if set.
    */
@@ -4900,7 +4914,7 @@ declare abstract class TerminalField extends FormField {
    *
    * @internal
    */
-  protected applyChange(): Promise<void>;
+  protected applyChange(): void;
 }
 //#endregion
 //#region src/document/forms/fields/checkbox-field.d.ts
@@ -4936,11 +4950,11 @@ declare class CheckboxField extends TerminalField {
   /**
    * Check the checkbox (sets to the on-value).
    */
-  check(): Promise<void>;
+  check(): void;
   /**
    * Uncheck the checkbox (sets to "Off").
    */
-  uncheck(): Promise<void>;
+  uncheck(): void;
   /**
    * Set the checkbox value.
    *
@@ -4950,7 +4964,7 @@ declare class CheckboxField extends TerminalField {
    * @param value "Off" or one of the on-values
    * @throws {Error} if field is read-only or value is invalid
    */
-  setValue(value: string): Promise<void>;
+  setValue(value: string): void;
 }
 //#endregion
 //#region src/document/forms/fields/choice-fields.d.ts
@@ -4992,7 +5006,7 @@ declare class DropdownField extends TerminalField {
    * @param value The value to select
    * @throws {Error} if field is read-only or value is invalid (for non-editable dropdowns)
    */
-  setValue(value: string): Promise<void>;
+  setValue(value: string): void;
 }
 /**
  * List box field.
@@ -5035,7 +5049,7 @@ declare class ListBoxField extends TerminalField {
    * @param values Array of values to select
    * @throws {Error} if field is read-only, multiple selection not allowed, or values are invalid
    */
-  setValue(values: string[]): Promise<void>;
+  setValue(values: string[]): void;
 }
 //#endregion
 //#region src/document/forms/fields/other-fields.d.ts
@@ -5108,7 +5122,7 @@ declare class RadioField extends TerminalField {
    * @param option One of getOptions() or null to deselect
    * @throws {Error} if field is read-only, option is invalid, or deselection not allowed
    */
-  setValue(option: string | null): Promise<void>;
+  setValue(option: string | null): void;
 }
 //#endregion
 //#region src/document/forms/fields/text-field.d.ts
@@ -5148,7 +5162,7 @@ declare class TextField extends TerminalField {
    * @param value The new text value
    * @throws {Error} if field is read-only
    */
-  setValue(value: string): Promise<void>;
+  setValue(value: string): void;
 }
 //#endregion
 //#region src/fonts/standard-14.d.ts
@@ -5743,7 +5757,7 @@ declare class PDFPage {
    * await page.drawField(paymentRadio, { x: 100, y: 520, width: 16, height: 16, option: "PayPal" });
    * ```
    */
-  drawField(field: FormField, options: DrawFieldOptions): Promise<void>;
+  drawField(field: FormField, options: DrawFieldOptions): void;
   /**
    * Build a widget annotation dictionary for a field.
    */
@@ -5928,84 +5942,84 @@ declare class PDFPage {
    *
    * @example
    * ```typescript
-   * const annotations = await page.getAnnotations();
+   * const annotations = page.getAnnotations();
    * for (const annot of annotations) {
    *   console.log(annot.type, annot.contents);
    * }
    * ```
    */
-  getAnnotations(): Promise<PDFAnnotation[]>;
+  getAnnotations(): PDFAnnotation[];
   /**
    * Get all popup annotations on this page.
    *
    * Popups are typically accessed via their parent markup annotation
    * using `annotation.getPopup()`, but this method allows direct access.
    */
-  getPopupAnnotations(): Promise<PDFPopupAnnotation[]>;
+  getPopupAnnotations(): PDFPopupAnnotation[];
   /**
    * Get all highlight annotations on this page.
    */
-  getHighlightAnnotations(): Promise<PDFHighlightAnnotation[]>;
+  getHighlightAnnotations(): PDFHighlightAnnotation[];
   /**
    * Get all underline annotations on this page.
    */
-  getUnderlineAnnotations(): Promise<PDFUnderlineAnnotation[]>;
+  getUnderlineAnnotations(): PDFUnderlineAnnotation[];
   /**
    * Get all strikeout annotations on this page.
    */
-  getStrikeOutAnnotations(): Promise<PDFStrikeOutAnnotation[]>;
+  getStrikeOutAnnotations(): PDFStrikeOutAnnotation[];
   /**
    * Get all squiggly annotations on this page.
    */
-  getSquigglyAnnotations(): Promise<PDFSquigglyAnnotation[]>;
+  getSquigglyAnnotations(): PDFSquigglyAnnotation[];
   /**
    * Get all link annotations on this page.
    */
-  getLinkAnnotations(): Promise<PDFLinkAnnotation[]>;
+  getLinkAnnotations(): PDFLinkAnnotation[];
   /**
    * Get all text annotations (sticky notes) on this page.
    */
-  getTextAnnotations(): Promise<PDFTextAnnotation[]>;
+  getTextAnnotations(): PDFTextAnnotation[];
   /**
    * Get all free text annotations on this page.
    */
-  getFreeTextAnnotations(): Promise<PDFFreeTextAnnotation[]>;
+  getFreeTextAnnotations(): PDFFreeTextAnnotation[];
   /**
    * Get all line annotations on this page.
    */
-  getLineAnnotations(): Promise<PDFLineAnnotation[]>;
+  getLineAnnotations(): PDFLineAnnotation[];
   /**
    * Get all square annotations on this page.
    */
-  getSquareAnnotations(): Promise<PDFSquareAnnotation[]>;
+  getSquareAnnotations(): PDFSquareAnnotation[];
   /**
    * Get all circle annotations on this page.
    */
-  getCircleAnnotations(): Promise<PDFCircleAnnotation[]>;
+  getCircleAnnotations(): PDFCircleAnnotation[];
   /**
    * Get all stamp annotations on this page.
    */
-  getStampAnnotations(): Promise<PDFStampAnnotation[]>;
+  getStampAnnotations(): PDFStampAnnotation[];
   /**
    * Get all ink annotations on this page.
    */
-  getInkAnnotations(): Promise<PDFInkAnnotation[]>;
+  getInkAnnotations(): PDFInkAnnotation[];
   /**
    * Get all polygon annotations on this page.
    */
-  getPolygonAnnotations(): Promise<PDFPolygonAnnotation[]>;
+  getPolygonAnnotations(): PDFPolygonAnnotation[];
   /**
    * Get all polyline annotations on this page.
    */
-  getPolylineAnnotations(): Promise<PDFPolylineAnnotation[]>;
+  getPolylineAnnotations(): PDFPolylineAnnotation[];
   /**
    * Get all caret annotations on this page.
    */
-  getCaretAnnotations(): Promise<PDFCaretAnnotation[]>;
+  getCaretAnnotations(): PDFCaretAnnotation[];
   /**
    * Get all file attachment annotations on this page.
    */
-  getFileAttachmentAnnotations(): Promise<PDFFileAttachmentAnnotation[]>;
+  getFileAttachmentAnnotations(): PDFFileAttachmentAnnotation[];
   /**
    * Add a highlight annotation.
    *
@@ -6126,11 +6140,11 @@ declare class PDFPage {
    *
    * @example
    * ```typescript
-   * const highlights = await page.getHighlightAnnotations();
-   * await page.removeAnnotation(highlights[0]);
+   * const highlights = page.getHighlightAnnotations();
+   * page.removeAnnotation(highlights[0]);
    * ```
    */
-  removeAnnotation(annotation: PDFAnnotation): Promise<void>;
+  removeAnnotation(annotation: PDFAnnotation): void;
   /**
    * Remove annotations from the page.
    *
@@ -6142,13 +6156,13 @@ declare class PDFPage {
    * @example
    * ```typescript
    * // Remove all highlights
-   * await page.removeAnnotations({ type: "Highlight" });
+   * page.removeAnnotations({ type: "Highlight" });
    *
    * // Remove all annotations
-   * await page.removeAnnotations();
+   * page.removeAnnotations();
    * ```
    */
-  removeAnnotations(options?: RemoveAnnotationsOptions): Promise<void>;
+  removeAnnotations(options?: RemoveAnnotationsOptions): void;
   /**
    * Add an annotation reference to the page's /Annots array.
    * Internal method - also invalidates the annotation cache.
@@ -6227,7 +6241,7 @@ declare class PDFPage {
    *
    * @example
    * ```typescript
-   * const pageText = await page.extractText();
+   * const pageText = page.extractText();
    * console.log(pageText.text); // Plain text
    *
    * // Access structured content
@@ -6236,7 +6250,7 @@ declare class PDFPage {
    * }
    * ```
    */
-  extractText(_options?: ExtractTextOptions): Promise<PageText>;
+  extractText(_options?: ExtractTextOptions): PageText;
   /**
    * Search for text on this page.
    *
@@ -6247,16 +6261,16 @@ declare class PDFPage {
    * @example
    * ```typescript
    * // String search
-   * const matches = await page.findText("{{ name }}");
+   * const matches = page.findText("{{ name }}");
    * for (const match of matches) {
    *   console.log(`Found at:`, match.bbox);
    * }
    *
    * // Regex search
-   * const placeholders = await page.findText(/\{\{\s*\w+\s*\}\}/g);
+   * const placeholders = page.findText(/\{\{\s*\w+\s*\}\}/g);
    * ```
    */
-  findText(query: string | RegExp, options?: FindTextOptions): Promise<TextMatch[]>;
+  findText(query: string | RegExp, options?: FindTextOptions): TextMatch[];
   /**
    * Get the concatenated content stream bytes.
    */
@@ -6373,11 +6387,11 @@ declare class PDFFonts {
    *
    * @param subsetFonts - Whether to subset fonts (only include used glyphs)
    */
-  finalize(subsetFonts: boolean): Promise<void>;
+  finalize(subsetFonts: boolean): void;
   /**
    * @deprecated Use `finalize()` instead. This method exists for backwards compatibility.
    */
-  prepare(): Promise<void>;
+  prepare(): void;
 }
 //#endregion
 //#region src/document/forms/field-tree.d.ts
@@ -6387,7 +6401,7 @@ declare class PDFFonts {
 interface FieldTreeSource {
   getDict(): PdfDict;
   defaultQuadding: number;
-  updateFieldAppearance?(field: TerminalField): Promise<void>;
+  updateFieldAppearance?(field: TerminalField): void;
 }
 /**
  * FieldTree provides safe, synchronous iteration over the form field hierarchy.
@@ -6426,7 +6440,7 @@ declare class FieldTree implements Iterable<FormField> {
    * @param registry The object registry for resolving references
    * @returns A fully-loaded FieldTree
    */
-  static load(acroForm: FieldTreeSource, registry: ObjectRegistry): Promise<FieldTree>;
+  static load(acroForm: FieldTreeSource, registry: ObjectRegistry): FieldTree;
   /**
    * Iterate over all fields (terminal and non-terminal).
    * Fields are yielded in breadth-first order.
@@ -6483,6 +6497,16 @@ interface FlattenOptions {
   font?: FormFont;
   /** Font size to use (0 = auto) */
   fontSize?: number;
+  /**
+   * Skip signature fields during flattening.
+   *
+   * When true, signature fields are preserved as interactive fields while
+   * all other fields are flattened. This is useful when you want to flatten
+   * filled form data but keep signature fields available for signing.
+   *
+   * @default false
+   */
+  skipSignatures?: boolean;
 }
 //#endregion
 //#region src/document/forms/acro-form.d.ts
@@ -6509,11 +6533,11 @@ declare class AcroForm implements AcroFormLike {
    * @param registry The object registry for resolving references
    * @param pageTree Optional page tree for efficient page lookups during flattening
    */
-  static load(catalog: PdfDict, registry: ObjectRegistry, pageTree?: PDFPageTree): Promise<AcroForm | null>;
+  static load(catalog: PdfDict, registry: ObjectRegistry, pageTree?: PDFPageTree): AcroForm | null;
   /**
    * Default resources dictionary (fonts, etc.).
    */
-  getDefaultResources(): Promise<PdfDict | null>;
+  getDefaultResources(): PdfDict | null;
   /**
    * Default appearance string.
    */
@@ -6546,16 +6570,16 @@ declare class AcroForm implements AcroFormLike {
    * Get all terminal fields (flattened).
    * Non-terminal fields (containers) are not included.
    */
-  getFields(): Promise<TerminalField[]>;
+  getFields(): TerminalField[];
   /**
    * Get field by fully-qualified name.
    * Returns null if not found.
    */
-  getField(name: string): Promise<TerminalField | null>;
+  getField(name: string): TerminalField | null;
   /**
    * Get all fields of a specific type.
    */
-  getFieldsOfType<T extends TerminalField>(type: T["type"]): Promise<T[]>;
+  getFieldsOfType<T extends TerminalField>(type: T["type"]): T[];
   /**
    * Get the underlying dictionary.
    */
@@ -6584,7 +6608,7 @@ declare class AcroForm implements AcroFormLike {
    * }
    * ```
    */
-  getFieldTree(): Promise<FieldTree>;
+  getFieldTree(): FieldTree;
   /**
    * Clear the fields cache.
    * Call this after modifying the form structure.
@@ -6635,7 +6659,7 @@ declare class AcroForm implements AcroFormLike {
    *
    * @internal
    */
-  updateFieldAppearance(field: TerminalField): Promise<void>;
+  updateFieldAppearance(field: TerminalField): void;
   /**
    * Update appearances for all fields that need it.
    *
@@ -6646,11 +6670,11 @@ declare class AcroForm implements AcroFormLike {
    */
   updateAppearances(options?: {
     forceRegenerate?: boolean;
-  }): Promise<void>;
+  }): void;
   /**
    * Mark all fields as needing appearance update.
    */
-  markAllNeedAppearanceUpdate(): Promise<void>;
+  markAllNeedAppearanceUpdate(): void;
   /**
    * Collect all terminal fields from a /Kids or /Fields array.
    */
@@ -6684,6 +6708,16 @@ declare class AcroForm implements AcroFormLike {
    * @param fieldRef Reference to the field dictionary
    */
   addField(fieldRef: PdfRef): void;
+  /**
+   * Remove a field reference from the Fields array.
+   *
+   * This only removes the field from the AcroForm's /Fields array.
+   * Widget removal from pages must be handled separately.
+   *
+   * @param fieldRef Reference to the field dictionary to remove
+   * @returns true if the field was found and removed, false otherwise
+   */
+  removeField(fieldRef: PdfRef): boolean;
   /**
    * Flatten all form fields into static page content.
    *
@@ -6699,7 +6733,7 @@ declare class AcroForm implements AcroFormLike {
    *
    * @param options Flattening options
    */
-  flatten(options?: FlattenOptions): Promise<void>;
+  flatten(options?: FlattenOptions): void;
 }
 //#endregion
 //#region src/helpers/rotations.d.ts
@@ -6881,7 +6915,7 @@ declare class PDFForm {
    * @param ctx The PDF context
    * @returns PDFForm instance, or null if no form exists
    */
-  static load(ctx: PDFContext): Promise<PDFForm | null>;
+  static load(ctx: PDFContext): PDFForm | null;
   /**
    * Get all form fields.
    */
@@ -7101,6 +7135,30 @@ declare class PDFForm {
    * ```
    */
   createListbox(name: string, options: ListboxOptions): ListBoxField;
+  /**
+   * Remove a form field from the document.
+   *
+   * This removes the field from the AcroForm and all its widget annotations
+   * from their respective pages.
+   *
+   * @param fieldOrName - The field instance or field name to remove
+   * @returns true if the field was found and removed, false otherwise
+   *
+   * @example
+   * ```typescript
+   * // Remove by field instance
+   * const nameField = form.getTextField("name");
+   * form.removeField(nameField);
+   *
+   * // Remove by name
+   * form.removeField("email");
+   * ```
+   */
+  removeField(fieldOrName: FormField | string): boolean;
+  /**
+   * Remove all widgets of a field from their respective pages.
+   */
+  private removeWidgetsFromPages;
   /**
    * Validate that a field name is unique.
    */
@@ -7139,14 +7197,14 @@ declare class PDFForm {
    * // result.skipped: ["nonexistent"]
    * ```
    */
-  fill(values: Record<string, FieldValue>): Promise<{
+  fill(values: Record<string, FieldValue>): {
     filled: string[];
     skipped: string[];
-  }>;
+  };
   /**
    * Reset all fields to their default values.
    */
-  resetAll(): Promise<void>;
+  resetAll(): void;
   /**
    * Get form-level properties.
    */
@@ -7176,14 +7234,14 @@ declare class PDFForm {
    * Call this if the form structure has been modified externally
    * (e.g., fields added or removed via low-level API).
    */
-  reloadFields(): Promise<void>;
+  reloadFields(): void;
   /**
    * Update appearance streams for all modified fields.
    *
    * This regenerates the visual appearance of fields whose values have changed.
    * Called automatically during `flatten()`.
    */
-  updateAppearances(): Promise<void>;
+  updateAppearances(): void;
   /**
    * Flatten all form fields into static page content.
    *
@@ -7202,8 +7260,15 @@ declare class PDFForm {
    * await pdf.form.flatten();
    * const bytes = await pdf.save();
    * ```
+   *
+   * @example Flatten while preserving signature fields
+   * ```typescript
+   * await pdf.form.fill({ name: "John Doe" });
+   * await pdf.form.flatten({ skipSignatures: true });
+   * // Signature fields remain interactive for signing
+   * ```
    */
-  flatten(options?: FlattenOptions): Promise<void>;
+  flatten(options?: FlattenOptions): void;
   /**
    * Get the underlying AcroForm for low-level operations.
    *
@@ -7862,18 +7927,18 @@ declare class PDF {
    *
    * Objects are cached and tracked for modifications.
    */
-  getObject(ref: PdfRef): Promise<PdfObject | null>;
+  getObject(ref: PdfRef): PdfObject | null;
   /**
    * Get the document catalog dictionary.
    *
    * Note: For internal use, prefer accessing the catalog via context which
    * provides higher-level methods for working with catalog structures.
    */
-  getCatalog(): Promise<PdfDict | null>;
+  getCatalog(): PdfDict;
   /**
    * Get all pages in document order.
    */
-  getPages(): Promise<PDFPage[]>;
+  getPages(): PDFPage[];
   /**
    * Get page count.
    */
@@ -7882,7 +7947,15 @@ declare class PDF {
    * Get a single page by index (0-based).
    * Returns null if index out of bounds.
    */
-  getPage(index: number): Promise<PDFPage | null>;
+  getPage(index: number): PDFPage | null;
+  /**
+   * Ensure page resources are resolved (not a reference).
+   *
+   * Pages may have Resources as a PdfRef pointing to a shared resources dict.
+   * The sync getResources() method on PDFPage needs the actual dict, not a ref.
+   * This resolves the reference and replaces it in the page dict.
+   */
+  private ensurePageResourcesResolved;
   /**
    * Add a new blank page.
    *
@@ -8075,7 +8148,7 @@ declare class PDF {
    * page.drawImage(image, { x: 50, y: 500 });
    * ```
    */
-  embedImage(bytes: Uint8Array): Promise<PDFImage>;
+  embedImage(bytes: Uint8Array): PDFImage;
   /**
    * Embed a JPEG image into the document.
    *
@@ -8096,7 +8169,7 @@ declare class PDF {
    * });
    * ```
    */
-  embedJpeg(bytes: Uint8Array): Promise<PDFImage>;
+  embedJpeg(bytes: Uint8Array): PDFImage;
   /**
    * Embed a PNG image into the document.
    *
@@ -8115,7 +8188,7 @@ declare class PDF {
    * page.drawImage(logo, { x: 100, y: 700, width: 150 });
    * ```
    */
-  embedPng(bytes: Uint8Array): Promise<PDFImage>;
+  embedPng(bytes: Uint8Array): PDFImage;
   /**
    * Access the attachments API for managing file attachments.
    *
@@ -8144,7 +8217,7 @@ declare class PDF {
    *
    * @returns Map of attachment name to attachment info
    */
-  getAttachments(): Promise<Map<string, AttachmentInfo>>;
+  getAttachments(): Map<string, AttachmentInfo>;
   /**
    * Get the raw bytes of an attachment.
    *
@@ -8153,7 +8226,7 @@ declare class PDF {
    * @param name The attachment name (key in the EmbeddedFiles tree)
    * @returns The attachment bytes, or null if not found
    */
-  getAttachment(name: string): Promise<Uint8Array | null>;
+  getAttachment(name: string): Uint8Array | null;
   /**
    * Check if an attachment exists.
    *
@@ -8162,7 +8235,7 @@ declare class PDF {
    * @param name The attachment name
    * @returns True if the attachment exists
    */
-  hasAttachment(name: string): Promise<boolean>;
+  hasAttachment(name: string): boolean;
   /**
    * Add a file attachment to the document.
    *
@@ -8173,7 +8246,7 @@ declare class PDF {
    * @param options - Attachment options (description, MIME type, dates)
    * @throws {Error} If name already exists and overwrite !== true
    */
-  addAttachment(name: string, data: Uint8Array, options?: AddAttachmentOptions): Promise<void>;
+  addAttachment(name: string, data: Uint8Array, options?: AddAttachmentOptions): void;
   /**
    * Remove an attachment from the document.
    *
@@ -8182,7 +8255,7 @@ declare class PDF {
    * @param name The attachment name
    * @returns True if the attachment was removed, false if not found
    */
-  removeAttachment(name: string): Promise<boolean>;
+  removeAttachment(name: string): boolean;
   /**
    * Check if the document has an interactive form (AcroForm).
    *
@@ -8230,7 +8303,7 @@ declare class PDF {
    * await pdf.save({ incremental: true });
    * ```
    */
-  getForm(): Promise<PDFForm | null>;
+  getForm(): PDFForm | null;
   /**
    * Get or create the document's interactive form.
    *
@@ -8246,7 +8319,7 @@ declare class PDF {
    * const nameField = form.createTextField("name", { fontSize: 12 });
    * ```
    */
-  getOrCreateForm(): Promise<PDFForm>;
+  getOrCreateForm(): PDFForm;
   /**
    * Sign the PDF document.
    *
@@ -8296,7 +8369,7 @@ declare class PDF {
    * }
    * ```
    */
-  hasLayers(): Promise<boolean>;
+  hasLayers(): boolean;
   /**
    * Get information about all layers in the document.
    *
@@ -8313,7 +8386,7 @@ declare class PDF {
    * }
    * ```
    */
-  getLayers(): Promise<LayerInfo[]>;
+  getLayers(): LayerInfo[];
   /**
    * Flatten all Optional Content Groups (layers) in the document.
    *
@@ -8343,7 +8416,7 @@ declare class PDF {
    * await pdf.sign({ signer });
    * ```
    */
-  flattenLayers(): Promise<FlattenLayersResult>;
+  flattenLayers(): FlattenLayersResult;
   /**
    * Extract text from all pages in the document.
    *
@@ -8360,7 +8433,7 @@ declare class PDF {
    * }
    * ```
    */
-  extractText(): Promise<PageText[]>;
+  extractText(): PageText[];
   /**
    * Search for text across all pages in the document.
    *
@@ -8383,7 +8456,7 @@ declare class PDF {
    * const placeholders = await pdf.findText(/\{\{\s*\w+\s*\}\}/g);
    * ```
    */
-  findText(query: string | RegExp, options?: FindTextOptions): Promise<TextMatch[]>;
+  findText(query: string | RegExp, options?: FindTextOptions): TextMatch[];
   /**
    * Check if the document has unsaved changes.
    */