@libpdf/core 0.0.1-beta.5 → 0.0.1-beta.7

package/dist/index.d.mts

@@ -1212,7 +1212,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 +1228,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.
    */
@@ -2478,8 +2478,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 +2699,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 +2799,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 +2840,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 +2861,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 +2909,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 +2960,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 +3085,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 +3131,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  list(): Promise<Map<string, AttachmentInfo>>;
+  list(): Map<string, AttachmentInfo>;
   /**
    * Get the raw bytes of an attachment.
    *
@@ -3138,7 +3147,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  get(name: string): Promise<Uint8Array | null>;
+  get(name: string): Uint8Array | null;
   /**
    * Check if an attachment exists.
    *
@@ -3152,7 +3161,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  has(name: string): Promise<boolean>;
+  has(name: string): boolean;
   /**
    * Add a file attachment to the document.
    *
@@ -3176,7 +3185,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 +3200,7 @@ declare class PDFAttachments {
    * }
    * ```
    */
-  remove(name: string): Promise<boolean>;
+  remove(name: string): boolean;
 }
 //#endregion
 //#region src/helpers/colors.d.ts
@@ -3566,8 +3575,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 +3731,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 +3838,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 +3894,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 +4071,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 +4203,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 +4655,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 +4685,7 @@ declare class WidgetAnnotation {
  */
 interface AcroFormLike {
   defaultQuadding: number;
-  updateFieldAppearance?(field: TerminalField): Promise<void>;
+  updateFieldAppearance?(field: TerminalField): void;
 }
 /**
  * Field type identifiers.
@@ -4865,7 +4874,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 +4896,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 +4909,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 +4945,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 +4959,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 +5001,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 +5044,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 +5117,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 +5157,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
@@ -5535,13 +5544,13 @@ declare class PathBuilder {
  */
 interface Rectangle {
   /** Left x coordinate */
-  x1: number;
+  x: number;
   /** Bottom y coordinate */
-  y1: number;
-  /** Right x coordinate */
-  x2: number;
-  /** Top y coordinate */
-  y2: number;
+  y: number;
+  /** Width */
+  width: number;
+  /** Height */
+  height: number;
 }
 /**
  * Options for drawing an embedded page.
@@ -5743,7 +5752,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 +5937,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 +6135,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 +6151,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 +6236,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 +6245,7 @@ declare class PDFPage {
    * }
    * ```
    */
-  extractText(_options?: ExtractTextOptions): Promise<PageText>;
+  extractText(_options?: ExtractTextOptions): PageText;
   /**
    * Search for text on this page.
    *
@@ -6247,16 +6256,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 +6382,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 +6396,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 +6435,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.
@@ -6509,11 +6518,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 +6555,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 +6593,7 @@ declare class AcroForm implements AcroFormLike {
    * }
    * ```
    */
-  getFieldTree(): Promise<FieldTree>;
+  getFieldTree(): FieldTree;
   /**
    * Clear the fields cache.
    * Call this after modifying the form structure.
@@ -6635,7 +6644,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 +6655,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 +6693,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 +6718,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 +6900,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 +7120,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 +7182,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 +7219,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.
    *
@@ -7203,7 +7246,7 @@ declare class PDFForm {
    * const bytes = await pdf.save();
    * ```
    */
-  flatten(options?: FlattenOptions): Promise<void>;
+  flatten(options?: FlattenOptions): void;
   /**
    * Get the underlying AcroForm for low-level operations.
    *
@@ -7862,18 +7905,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 +7925,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 +8126,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 +8147,7 @@ declare class PDF {
    * });
    * ```
    */
-  embedJpeg(bytes: Uint8Array): Promise<PDFImage>;
+  embedJpeg(bytes: Uint8Array): PDFImage;
   /**
    * Embed a PNG image into the document.
    *
@@ -8115,7 +8166,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 +8195,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 +8204,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 +8213,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 +8224,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 +8233,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 +8281,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 +8297,7 @@ declare class PDF {
    * const nameField = form.createTextField("name", { fontSize: 12 });
    * ```
    */
-  getOrCreateForm(): Promise<PDFForm>;
+  getOrCreateForm(): PDFForm;
   /**
    * Sign the PDF document.
    *
@@ -8296,7 +8347,7 @@ declare class PDF {
    * }
    * ```
    */
-  hasLayers(): Promise<boolean>;
+  hasLayers(): boolean;
   /**
    * Get information about all layers in the document.
    *
@@ -8313,7 +8364,7 @@ declare class PDF {
    * }
    * ```
    */
-  getLayers(): Promise<LayerInfo[]>;
+  getLayers(): LayerInfo[];
   /**
    * Flatten all Optional Content Groups (layers) in the document.
    *
@@ -8343,7 +8394,7 @@ declare class PDF {
    * await pdf.sign({ signer });
    * ```
    */
-  flattenLayers(): Promise<FlattenLayersResult>;
+  flattenLayers(): FlattenLayersResult;
   /**
    * Extract text from all pages in the document.
    *
@@ -8360,7 +8411,7 @@ declare class PDF {
    * }
    * ```
    */
-  extractText(): Promise<PageText[]>;
+  extractText(): PageText[];
   /**
    * Search for text across all pages in the document.
    *
@@ -8383,7 +8434,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.
    */