modern-pdf-lib 0.25.0 → 0.28.0

package/dist/pdfForm-Ca86NDWn.d.mts

@@ -0,0 +1,897 @@
+//#region src/core/pdfObjects.d.ts
+/**
+* @module core/pdfObjects
+*
+* Low-level PDF object model.  Every PDF value type has a class with a
+* `serialize(writer)` method that appends valid PDF syntax to a
+* {@link ByteWriter}.  The module also provides `PdfObjectRegistry` for
+* allocating indirect-object numbers.
+*
+* Reference: PDF 1.7 spec, §7.3 (Objects).
+*/
+/**
+* Minimal interface consumed by every `serialize()` method.
+* Implementations may write to a growing `Uint8Array`, a `WritableStream`,
+* etc.
+*/
+interface ByteWriter {
+  /** Append raw bytes. */
+  write(data: Uint8Array): void;
+  /** Append an ASCII / Latin-1 string — callers guarantee all chars < 0x100. */
+  writeString(str: string): void;
+}
+/** The PDF `null` object. */
+declare class PdfNull {
+  static readonly instance: PdfNull;
+  /** @internal */
+  readonly kind = "null";
+  private constructor();
+  /** Serialize as `null`. */
+  serialize(writer: ByteWriter): void;
+}
+/** A PDF boolean — `true` or `false`. */
+declare class PdfBool {
+  readonly value: boolean;
+  static readonly TRUE: PdfBool;
+  static readonly FALSE: PdfBool;
+  /** @internal */
+  readonly kind = "bool";
+  private constructor();
+  static of(value: boolean): PdfBool;
+  serialize(writer: ByteWriter): void;
+}
+/** A PDF numeric object (integer or real). */
+declare class PdfNumber {
+  readonly value: number;
+  /** @internal */
+  readonly kind = "number";
+  constructor(value: number);
+  static of(value: number): PdfNumber;
+  serialize(writer: ByteWriter): void;
+}
+/**
+* A PDF string — either literal `(…)` or hexadecimal `<…>`.
+*
+* By default the constructor produces a literal string.  Use the static
+* helpers for explicit control.
+*/
+declare class PdfString {
+  /** The raw string content (unescaped). */
+  readonly value: string;
+  /** When `true` the string is serialized in hexadecimal form `<…>`. */
+  readonly hex: boolean;
+  /** @internal */
+  readonly kind = "string";
+  private constructor();
+  /** Create a literal string `(…)`. */
+  static literal(value: string): PdfString;
+  /** Create a hexadecimal string `<…>` from a plain string. */
+  static hex(value: string): PdfString;
+  /** Create a hexadecimal string from raw bytes. */
+  static hexFromBytes(data: Uint8Array): PdfString;
+  serialize(writer: ByteWriter): void;
+}
+/**
+* A PDF name object — e.g. `/Type`, `/Page`.
+*
+* The leading `/` is stored and serialized.  Characters outside the
+* printable ASCII range (33–126) and `#` are encoded as `#XX`.
+*/
+declare class PdfName {
+  /** The name value *including* the leading `/`. */
+  readonly value: string;
+  /** @internal */
+  readonly kind = "name";
+  /** Cache for frequently used names. */
+  private static readonly cache;
+  private constructor();
+  /** Create or retrieve a cached `PdfName`. */
+  static of(name: string): PdfName;
+  serialize(writer: ByteWriter): void;
+}
+/** A PDF array `[…]`. */
+declare class PdfArray {
+  readonly items: PdfObject[];
+  /** @internal */
+  readonly kind = "array";
+  constructor(items?: PdfObject[]);
+  static of(items: PdfObject[]): PdfArray;
+  /** Convenience: create an array of PdfNumbers. */
+  static fromNumbers(values: number[]): PdfArray;
+  /** Add an item. */
+  push(item: PdfObject): void;
+  /** Number of items. */
+  get length(): number;
+  serialize(writer: ByteWriter): void;
+}
+/** A PDF dictionary `<< … >>`. */
+declare class PdfDict {
+  /** @internal */
+  readonly kind = "dict";
+  private readonly entries;
+  constructor(entries?: Iterable<readonly [string, PdfObject]>);
+  /**
+  * Set a key-value pair.  Keys are always stored / looked up *with*
+  * the leading `/`.
+  */
+  set(key: string, value: PdfObject): this;
+  /** Get a value by key. */
+  get(key: string): PdfObject | undefined;
+  /** Check if a key exists. */
+  has(key: string): boolean;
+  /** Delete a key. */
+  delete(key: string): boolean;
+  /** Number of entries. */
+  get size(): number;
+  /** Iterate over entries as `[key, value]` pairs. */
+  [Symbol.iterator](): IterableIterator<[string, PdfObject]>;
+  serialize(writer: ByteWriter): void;
+}
+/**
+* A PDF stream object — a dictionary followed by `stream … endstream`.
+*
+* The `data` field holds the (possibly compressed) payload.  The caller
+* is responsible for setting `/Length` in the dict before serialization.
+*/
+declare class PdfStream {
+  /** Stream metadata dictionary. */
+  readonly dict: PdfDict;
+  /** Raw stream data (already encoded / compressed). */
+  data: Uint8Array;
+  /** @internal */
+  readonly kind = "stream";
+  constructor(dict: PdfDict, data: Uint8Array);
+  /**
+  * Create a stream from a plain UTF-8 string (e.g. content-stream
+  * operators).  Sets `/Length` automatically.
+  */
+  static fromString(content: string, extraEntries?: PdfDict): PdfStream;
+  /**
+  * Create a stream from raw bytes.  Sets `/Length` automatically.
+  */
+  static fromBytes(data: Uint8Array, extraEntries?: PdfDict): PdfStream;
+  /** Update `/Length` to reflect the current data size. */
+  syncLength(): void;
+  serialize(writer: ByteWriter): void;
+}
+/** An indirect reference `N G R`. */
+declare class PdfRef {
+  /** Object number (≥ 1). */
+  readonly objectNumber: number;
+  /** Generation number (usually 0). */
+  readonly generationNumber: number;
+  /** @internal */
+  readonly kind = "ref";
+  constructor(objectNumber: number, generationNumber?: number);
+  static of(objectNumber: number, generationNumber?: number): PdfRef;
+  /** The string form used inside PDF bodies: `N G R`. */
+  serialize(writer: ByteWriter): void;
+  /** Return the `N G obj` header for an indirect-object definition. */
+  toObjectHeader(): string;
+  /** Return `endobj`. */
+  toObjectFooter(): string;
+  toString(): string;
+}
+/**
+* Union of all PDF object types.  Every member has a `serialize()` method
+* and a discriminating `kind` literal.
+*/
+type PdfObject = PdfNull | PdfBool | PdfNumber | PdfString | PdfName | PdfArray | PdfDict | PdfStream | PdfRef;
+/** Entry stored in the registry. */
+interface RegistryEntry {
+  /** Indirect reference (object number + generation). */
+  readonly ref: PdfRef;
+  /** The object itself. */
+  object: PdfObject;
+}
+/**
+* Allocates monotonically increasing object numbers and stores the
+* mapping from `PdfRef` → object value.
+*/
+declare class PdfObjectRegistry {
+  private nextObjectNumber;
+  private readonly entries;
+  private readonly refMap;
+  /**
+  * Register a new object, allocate an object number, and return its
+  * indirect reference.
+  */
+  register(object: PdfObject): PdfRef;
+  /**
+  * Register a pre-built `PdfRef` with an object.
+  * Useful when the ref must be known before the object is fully built
+  * (e.g. the catalog references the page tree, and vice-versa).
+  */
+  registerWithRef(ref: PdfRef, object: PdfObject): void;
+  /**
+  * Pre-allocate an object number and return the reference.
+  * Call {@link assign} later to attach the actual object.
+  */
+  allocate(): PdfRef;
+  /**
+  * Assign an object to a previously allocated (or registered) reference.
+  */
+  assign(ref: PdfRef, object: PdfObject): void;
+  /** Look up the object for a given reference. */
+  resolve(ref: PdfRef): PdfObject | undefined;
+  /** Iterate all entries in allocation order. */
+  [Symbol.iterator](): IterableIterator<RegistryEntry>;
+  /** Total number of registered objects (≥ 1 in a valid PDF because of
+  * the free entry at object 0). */
+  get size(): number;
+  /** The next object number that *would* be assigned. */
+  get nextNumber(): number;
+  /**
+  * Remove all registry entries that are not reachable from the given
+  * root references.  This is used after rebuilding the document
+  * structure so that orphaned objects from the original (loaded) PDF
+  * don't bloat the output.
+  *
+  * The walk follows every `PdfRef` found inside `PdfDict`, `PdfArray`,
+  * and `PdfStream` objects, handling cycles via a visited set.
+  */
+  filterReachable(rootRefs: PdfRef[]): void;
+}
+//#endregion
+//#region src/form/pdfField.d.ts
+/**
+* Minimal interface for a PDF page that can receive widget annotations.
+* Used by {@link PdfField.addToPage} to avoid importing PdfPage directly.
+*/
+interface WidgetAnnotationHost {
+  /** Add a raw widget annotation dictionary to this page. */
+  addWidgetAnnotation(widgetDict: PdfDict): void;
+}
+/** Discriminated union tag for PDF form field types. */
+type FieldType = "text" | "checkbox" | "radio" | "dropdown" | "listbox" | "button" | "signature";
+/** Common field flags (/Ff) — bit positions (0-indexed). */
+declare const FieldFlags: {
+  readonly ReadOnly: number;
+  readonly Required: number;
+  readonly NoExport: number;
+  readonly Multiline: number;
+  readonly Password: number;
+  readonly DoNotScroll: number;
+  readonly RichText: number;
+  readonly NoToggleToOff: number;
+  readonly Radio: number;
+  readonly Pushbutton: number;
+  readonly RadiosInUnison: number;
+  readonly Combo: number;
+  readonly Edit: number;
+  readonly Sort: number;
+  readonly MultiSelect: number;
+};
+/**
+* Abstract base class for all AcroForm field types.
+*
+* Each field holds a reference to the underlying field dictionary
+* (which may be a merged field+widget dictionary in simple forms)
+* and an optional separate widget annotation dictionary.
+*/
+declare abstract class PdfField {
+  /** Discriminator for the concrete field type. */
+  abstract readonly fieldType: FieldType;
+  /** The fully-qualified field name. */
+  readonly name: string;
+  /**
+  * The underlying field dictionary (may contain both field and widget
+  * entries for simple one-widget fields).
+  */
+  protected readonly dict: PdfDict;
+  /**
+  * The widget annotation dictionary. For merged field+widget dicts,
+  * this is the same object as `dict`.
+  */
+  protected readonly widgetDict: PdfDict;
+  /** Parent field dictionary chain for building full names. */
+  protected readonly parentNames: string[];
+  constructor(name: string, dict: PdfDict, widgetDict: PdfDict, parentNames?: string[]);
+  /** Get the partial field name (/T entry). */
+  getName(): string;
+  /**
+  * Get the fully qualified field name (Parent.Child.Name format).
+  * Per PDF spec SS12.7.3.2, the full name is formed by concatenating
+  * ancestor /T values with periods.
+  */
+  getFullName(): string;
+  /** Return the underlying field dictionary (for internal use by PdfForm). */
+  getDict(): PdfDict;
+  /** Get the raw /Ff (field flags) integer value. */
+  protected getFieldFlags(): number;
+  /** Set the raw /Ff (field flags) integer value. */
+  protected setFieldFlags(flags: number): void;
+  /** Check if a specific flag bit is set. */
+  protected hasFlag(flag: number): boolean;
+  /** Set or clear a specific flag bit. */
+  protected setFlag(flag: number, on: boolean): void;
+  /** Whether the field is read-only. */
+  isReadOnly(): boolean;
+  /** Set the read-only flag. */
+  setReadOnly(readOnly: boolean): void;
+  /** Whether the field is required. */
+  isRequired(): boolean;
+  /** Set the required flag. */
+  setRequired(required: boolean): void;
+  /** Whether the field should not be exported. */
+  isNoExport(): boolean;
+  /** Whether the field is exported (inverse of NoExport flag). */
+  isExported(): boolean;
+  /** Enable exporting this field (clear the NoExport flag). */
+  enableExporting(): void;
+  /** Disable exporting this field (set the NoExport flag). */
+  disableExporting(): void;
+  /**
+  * Get the field's widget rectangle as `[x1, y1, x2, y2]`.
+  * The /Rect entry comes from the widget annotation dictionary.
+  */
+  getRect(): [number, number, number, number];
+  /**
+  * Add this field's widget annotation to a page.
+  *
+  * Ensures the widget dict has `/Type /Annot` and `/Subtype /Widget`,
+  * then adds it to the page's annotation list so it appears in the
+  * rendered PDF.
+  *
+  * @param page  A page that implements {@link WidgetAnnotationHost}.
+  */
+  addToPage(page: WidgetAnnotationHost): void;
+  /**
+  * Get the underlying widget annotation dictionary.
+  * @internal
+  */
+  getWidgetDict(): PdfDict;
+  /** Get the current value of this field. */
+  abstract getValue(): string | boolean | string[];
+  /** Set the value of this field. */
+  abstract setValue(value: string | boolean | string[]): void;
+  /**
+  * Generate the /AP (appearance) stream for this field's current value.
+  * Returns a PdfStream suitable for the /N (normal) appearance.
+  */
+  abstract generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/fields/textField.d.ts
+/**
+* A PDF text form field (/FT /Tx).
+*
+* Stores a string value and supports properties like alignment,
+* multiline mode, password masking, and maximum length.
+*/
+declare class PdfTextField extends PdfField {
+  readonly fieldType: FieldType;
+  /** Get the text value of this field. */
+  getText(): string;
+  /**
+  * Set the text value of this field.
+  * Also updates /V and removes /AP to force regeneration.
+  */
+  setText(value: string): void;
+  /** Alias for getText(). */
+  getValue(): string;
+  /** Alias for setText(). */
+  setValue(value: string | boolean | string[]): void;
+  /**
+  * Get the font size from the /DA (default appearance) string.
+  * Returns 0 if the font size is not specified or is auto.
+  */
+  getFontSize(): number;
+  /**
+  * Set the font size in the /DA string.
+  * Creates or updates the /DA entry.
+  */
+  setFontSize(size: number): void;
+  /**
+  * Get the font name from the /DA string.
+  * Returns "Helv" (Helvetica) as default.
+  */
+  getFontName(): string;
+  /**
+  * Get the text alignment.
+  * /Q: 0 = left, 1 = center, 2 = right.
+  */
+  getAlignment(): "left" | "center" | "right";
+  /** Set the text alignment. */
+  setAlignment(align: "left" | "center" | "right"): void;
+  /** Whether this is a multiline text field. */
+  isMultiline(): boolean;
+  /** Set the multiline flag. */
+  setMultiline(multiline: boolean): void;
+  /** Whether this is a password field. */
+  isPassword(): boolean;
+  /** Get the maximum length, or undefined if no limit. */
+  getMaxLength(): number | undefined;
+  /** Set the maximum length. */
+  setMaxLength(maxLength: number): void;
+  /**
+  * Set an image on this text field.
+  *
+  * Creates an appearance stream that paints the image XObject scaled
+  * to fit the widget rectangle. This replaces the text appearance.
+  *
+  * @param imageRef  An object with `name` (resource name) and `ref` (PdfRef)
+  *                  pointing to the image XObject, plus `width` and `height`.
+  */
+  setImage(imageRef: {
+    name: string;
+    ref: PdfRef;
+    width: number;
+    height: number;
+  }): void;
+  /** Generate the appearance stream for this text field. */
+  generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/fields/checkboxField.d.ts
+/**
+* A PDF checkbox form field (/FT /Btn).
+*
+* The value is either the "on" name (typically "Yes") or "/Off".
+* The /AS (appearance state) entry controls which appearance is shown.
+*/
+declare class PdfCheckboxField extends PdfField {
+  readonly fieldType: FieldType;
+  /**
+  * Check whether the checkbox is currently checked.
+  *
+  * The checkbox is checked when /V or /AS is not "/Off".
+  */
+  isChecked(): boolean;
+  /** Check the checkbox (set to the "on" value). */
+  check(): void;
+  /** Uncheck the checkbox (set to /Off). */
+  uncheck(): void;
+  /** Toggle the checkbox. */
+  toggle(): void;
+  /**
+  * Get the "on" value name for this checkbox.
+  *
+  * Examines the /AP /N dictionary for a key that is not "/Off".
+  * Falls back to "Yes" if no appearance dictionary is found.
+  */
+  getOnValue(): string;
+  /** Get the value: "Yes"/"Off" as boolean for convenience. */
+  getValue(): boolean;
+  /** Set the value as boolean. */
+  setValue(value: string | boolean | string[]): void;
+  /** Generate the appearance stream for this checkbox. */
+  generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/fields/radioGroup.d.ts
+/**
+* A PDF radio button group (/FT /Btn with Radio flag).
+*
+* Multiple widget annotations represent the individual options.
+* The field's /V value is the name of the selected option.
+*/
+declare class PdfRadioGroup extends PdfField {
+  readonly fieldType: FieldType;
+  /** The individual widget annotation dictionaries. */
+  private readonly widgets;
+  constructor(name: string, dict: PdfDict, widgetDict: PdfDict, parentNames?: string[], widgets?: PdfDict[]);
+  /**
+  * Add all radio button widgets to a page.
+  *
+  * Unlike other field types that have a single widget, a radio group
+  * has multiple widget annotations (one per option). This override
+  * adds all of them.
+  */
+  override addToPage(page: WidgetAnnotationHost): void;
+  /**
+  * Get the currently selected option name.
+  * Returns undefined if no option is selected.
+  */
+  getSelected(): string | undefined;
+  /**
+  * Select an option by its name.
+  *
+  * Sets /V on the field and updates /AS on each widget to
+  * show the correct appearance state.
+  */
+  select(optionName: string): void;
+  /**
+  * Get the list of option names available in this radio group.
+  * Derived from the /AP /N dictionaries of each widget.
+  */
+  getOptions(): string[];
+  /** Get the widget annotation dictionaries. */
+  getWidgets(): PdfDict[];
+  /** Get the value: the selected option name or undefined. */
+  getValue(): string;
+  /** Set the value: select the named option. */
+  setValue(value: string | boolean | string[]): void;
+  /**
+  * Get the option name for a widget annotation.
+  * Looks in the /AP /N dictionary for a key that is not "Off".
+  */
+  private getWidgetOptionName;
+  /**
+  * Generate the appearance stream for the first widget.
+  * For full appearance generation, use generateAppearanceForWidget().
+  */
+  generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/fields/dropdownField.d.ts
+/**
+* A PDF dropdown (combo box) field (/FT /Ch with Combo flag).
+*
+* Options are stored in the /Opt array. The selected value is in /V.
+* Optionally editable (bit 18 of /Ff).
+*/
+declare class PdfDropdownField extends PdfField {
+  readonly fieldType: FieldType;
+  /** Get the currently selected value. */
+  getSelected(): string;
+  /** Select a value from the options. */
+  select(value: string): void;
+  /** Alias for getSelected(). */
+  getValue(): string;
+  /** Alias for select(). */
+  setValue(value: string | boolean | string[]): void;
+  /**
+  * Get the list of options.
+  *
+  * /Opt may be an array of strings, or an array of two-element arrays
+  * where element [0] is the export value and element [1] is the display
+  * value. We return the display values (or export values if no display).
+  */
+  getOptions(): string[];
+  /** Set the list of options. */
+  setOptions(options: string[]): void;
+  /** Whether the dropdown allows manual text entry. */
+  isEditable(): boolean;
+  /** Set whether the dropdown allows manual text entry. */
+  setEditable(editable: boolean): void;
+  /** Generate the appearance stream for this dropdown. */
+  generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/fields/listboxField.d.ts
+/**
+* A PDF listbox field (/FT /Ch without Combo flag).
+*
+* Displays a scrollable list of options. May allow multi-select.
+* The /V entry holds the selected value(s).
+*/
+declare class PdfListboxField extends PdfField {
+  readonly fieldType: FieldType;
+  /**
+  * Get the currently selected value(s).
+  *
+  * Returns an array of strings (may contain one element for
+  * single-select listboxes).
+  */
+  getSelected(): string[];
+  /** Select one or more values. */
+  select(values: string[]): void;
+  /** Get value as string array. */
+  getValue(): string[];
+  /** Set value from string array. */
+  setValue(value: string | boolean | string[]): void;
+  /** Get the list of options. */
+  getOptions(): string[];
+  /** Set the list of options. */
+  setOptions(options: string[]): void;
+  /** Generate the appearance stream for this listbox. */
+  generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/fields/buttonField.d.ts
+/**
+* A PDF pushbutton field (/FT /Btn with Pushbutton flag).
+*
+* Pushbuttons have no permanent value. They may have an associated
+* action (e.g. JavaScript, submit form, reset form) and display a
+* caption via the /MK dictionary.
+*/
+declare class PdfButtonField extends PdfField {
+  readonly fieldType: FieldType;
+  /**
+  * Get the button caption from the /MK dictionary.
+  * Returns undefined if no caption is set.
+  */
+  getCaption(): string | undefined;
+  /**
+  * Set the button caption in the /MK dictionary.
+  * Creates the /MK dictionary if it does not exist.
+  */
+  setCaption(caption: string): void;
+  /**
+  * Set an image on this button field.
+  *
+  * Creates an appearance stream that paints the image XObject scaled
+  * to fit the widget rectangle.
+  *
+  * @param imageRef  An object with `name` (resource name) and `ref` (PdfRef)
+  *                  pointing to the image XObject, plus `width` and `height`.
+  */
+  setImage(imageRef: {
+    name: string;
+    ref: PdfRef;
+    width: number;
+    height: number;
+  }): void;
+  /** Pushbuttons have no value; returns empty string. */
+  getValue(): string;
+  /** Pushbuttons have no value; no-op. */
+  setValue(_value: string | boolean | string[]): void;
+  /** Generate the appearance stream for this button. */
+  generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/fields/signatureField.d.ts
+/**
+* A PDF signature form field (/FT /Sig).
+*
+* The /V entry is a signature dictionary containing the cryptographic
+* signature data. This class provides read access to check whether the
+* field is signed, but does not implement signing (see Phase 6).
+*/
+declare class PdfSignatureField extends PdfField {
+  readonly fieldType: FieldType;
+  /**
+  * Whether this signature field has been signed.
+  * A signed field has a /V entry that is a dictionary.
+  */
+  isSigned(): boolean;
+  /**
+  * Get the signature dictionary, if signed.
+  * Returns undefined if the field has not been signed.
+  */
+  getSignatureValue(): PdfDict | undefined;
+  /** Get value: returns "signed" or "unsigned". */
+  getValue(): string;
+  /** Signature fields cannot be set via setValue. */
+  setValue(_value: string | boolean | string[]): void;
+  /** Generate the appearance stream for this signature field. */
+  generateAppearance(): PdfStream;
+}
+//#endregion
+//#region src/form/pdfForm.d.ts
+/**
+* Function that resolves a PdfRef to its underlying PdfObject.
+* Used when traversing the field tree from parsed PDF data.
+*/
+type RefResolver = (ref: PdfRef) => PdfObject;
+/**
+* Represents a PDF document's interactive form (AcroForm).
+*
+* Provides access to all form fields, bulk fill, and flatten operations.
+*/
+declare class PdfForm {
+  /** All fields in the form (flat list). */
+  private readonly fields;
+  /** The underlying /AcroForm dictionary. */
+  private readonly acroFormDict;
+  /** Map from field name to field for fast lookup. */
+  private readonly fieldsByName;
+  constructor(fields: PdfField[], acroFormDict: PdfDict);
+  /**
+  * Build a PdfForm from a parsed /AcroForm dictionary.
+  *
+  * Traverses the /Fields array and resolves indirect references to
+  * construct the field tree, then flattens it into a list of concrete
+  * field instances.
+  *
+  * @param acroFormDict  The /AcroForm dictionary from the document catalog.
+  * @param resolver      Function to resolve PdfRef to PdfObject.
+  */
+  static fromDict(acroFormDict: PdfDict, resolver: RefResolver): PdfForm;
+  /**
+  * Recursively traverse the field tree rooted at `dict`.
+  *
+  * The AcroForm field tree uses /Kids for both child fields and
+  * widget annotations. A node is a field if it has /FT; it is a
+  * widget annotation if it has /Subtype /Widget.
+  */
+  private static traverseFieldTree;
+  /** Get all fields in the form. */
+  getFields(): PdfField[];
+  /**
+  * Get a field by name (partial or fully-qualified).
+  * Returns undefined if not found.
+  */
+  getField(name: string): PdfField | undefined;
+  /**
+  * Get a text field by name.
+  * Throws if the field is not found or is not a text field.
+  */
+  getTextField(name: string): PdfTextField;
+  /**
+  * Get a checkbox field by name.
+  * Throws if the field is not found or is not a checkbox.
+  */
+  getCheckbox(name: string): PdfCheckboxField;
+  /**
+  * Get a radio group by name.
+  * Throws if the field is not found or is not a radio group.
+  */
+  getRadioGroup(name: string): PdfRadioGroup;
+  /**
+  * Get a dropdown field by name.
+  * Throws if the field is not found or is not a dropdown.
+  */
+  getDropdown(name: string): PdfDropdownField;
+  /**
+  * Get a listbox field by name.
+  * Throws if the field is not found or is not a listbox.
+  */
+  getListbox(name: string): PdfListboxField;
+  /**
+  * Get a button field by name.
+  * Throws if the field is not found or is not a button.
+  */
+  getButton(name: string): PdfButtonField;
+  /**
+  * Get a signature field by name.
+  * Throws if the field is not found or is not a signature field.
+  */
+  getSignatureField(name: string): PdfSignatureField;
+  /**
+  * Fill multiple fields at once.
+  *
+  * Accepts a record where keys are field names and values are the
+  * field values to set.  Strings map to text/dropdown/listbox values;
+  * booleans map to checkbox checked states.
+  *
+  * @param values  A mapping of field name to value.
+  * @throws        If a field name is not found.
+  */
+  fill(values: Record<string, string | boolean>): void;
+  /**
+  * Flatten the form: burn field values into the page content streams
+  * and remove the interactive form structure.
+  *
+  * After flattening, the document is no longer interactive — field
+  * values become static page content. This is done by:
+  *
+  * 1. Generating appearance streams for all fields that lack them
+  * 2. Removing the /AcroForm entry from the catalog
+  * 3. Removing /Widget annotations from page /Annots arrays
+  *
+  * Note: In this implementation, we mark the form as flattened by
+  * setting a flag and clearing the /Fields array. The appearance
+  * streams remain as page annotations will reference them.
+  */
+  flatten(): void;
+  /**
+  * Check whether the AcroForm dictionary contains XFA data.
+  *
+  * XFA (XML Forms Architecture) data causes PDF viewers to use the
+  * XFA renderer instead of the standard AcroForm renderer. Use
+  * {@link deleteXFA} to remove it.
+  *
+  * @returns `true` if the form has an /XFA entry.
+  */
+  hasXFA(): boolean;
+  /**
+  * Remove the /XFA entry from the AcroForm dictionary, if present.
+  *
+  * XFA (XML Forms Architecture) data can cause PDF viewers to use the
+  * XFA renderer instead of the standard AcroForm renderer, which is
+  * often undesirable.  Removing /XFA forces viewers to fall back to
+  * the AcroForm fields.
+  *
+  * After removing /XFA, `/NeedAppearances` is set to `true` so that
+  * the viewer knows it must generate appearances for the AcroForm
+  * fields (since XFA appearances are no longer available).
+  *
+  * This method is a no-op if the AcroForm dictionary does not contain
+  * an /XFA entry.
+  */
+  deleteXFA(): void;
+  /**
+  * Create a new text field and add it to the form.
+  *
+  * @param name  Field name.
+  * @param page  Page index (zero-based) where the widget appears.
+  * @param rect  Widget rectangle [x1, y1, x2, y2].
+  * @returns     The newly created text field.
+  */
+  createTextField(name: string, page: number, rect: [number, number, number, number]): PdfTextField;
+  /**
+  * Create a new checkbox and add it to the form.
+  *
+  * @param name  Field name.
+  * @param page  Page index (zero-based).
+  * @param rect  Widget rectangle [x1, y1, x2, y2].
+  * @returns     The newly created checkbox field.
+  */
+  createCheckbox(name: string, page: number, rect: [number, number, number, number]): PdfCheckboxField;
+  /**
+  * Create a new dropdown and add it to the form.
+  *
+  * @param name     Field name.
+  * @param page     Page index (zero-based).
+  * @param rect     Widget rectangle [x1, y1, x2, y2].
+  * @param options  The list of option strings.
+  * @returns        The newly created dropdown field.
+  */
+  createDropdown(name: string, page: number, rect: [number, number, number, number], options: string[]): PdfDropdownField;
+  /**
+  * Create a new radio button group and add it to the form.
+  *
+  * A radio group is a single field with multiple widget annotations,
+  * one per rectangle in `rects`.  Each widget corresponds to an
+  * option; if `options` is supplied the n-th option labels the n-th
+  * widget, otherwise options default to `"Option0"`, `"Option1"`, etc.
+  *
+  * @param name     Field name.
+  * @param page     The PdfPage where the widgets appear (unused for
+  *                 positioning in the low-level dict, but reserved
+  *                 for future page-level annotation linking).
+  * @param rects    Array of widget rectangles `{x, y, width, height}`.
+  * @param options  Optional option labels (one per rect).
+  * @returns        The newly created radio group.
+  */
+  createRadioGroup(name: string, page: unknown, rects: Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>, options?: string[]): PdfRadioGroup;
+  /**
+  * Create a new push button and add it to the form.
+  *
+  * @param name   Field name.
+  * @param page   The PdfPage where the widget appears.
+  * @param rect   Widget rectangle `{x, y, width, height}`.
+  * @param label  Optional button caption.
+  * @returns      The newly created button field.
+  */
+  createButton(name: string, page: unknown, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }, label?: string): PdfButtonField;
+  /**
+  * Create a new listbox and add it to the form.
+  *
+  * A listbox is a choice field (/FT /Ch) without the Combo flag,
+  * displaying a scrollable list of options.
+  *
+  * @param name     Field name.
+  * @param page     The PdfPage where the widget appears.
+  * @param rect     Widget rectangle `{x, y, width, height}`.
+  * @param options  The list of option strings.
+  * @returns        The newly created listbox field.
+  */
+  createListbox(name: string, page: unknown, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }, options: string[]): PdfListboxField;
+  /**
+  * Remove a field from the form by name.
+  *
+  * Removes the field from the internal field list, the name index,
+  * and the /Fields array in the AcroForm dictionary.
+  *
+  * @param name  The field name (partial or fully-qualified).
+  * @throws      If no field with the given name exists.
+  */
+  removeField(name: string): void;
+  /**
+  * Serialize the form back to a PdfDict.
+  *
+  * Updates /NeedAppearances if appearances need to be generated
+  * by the viewer.
+  */
+  toDict(_registry: PdfObjectRegistry): PdfDict;
+  /**
+  * Create a basic field dictionary with common entries.
+  */
+  private createFieldDict;
+  /**
+  * Add a field dictionary to the /Fields array in the AcroForm.
+  */
+  private addFieldToAcroForm;
+}
+//#endregion
+export { PdfRef as C, RegistryEntry as E, PdfObjectRegistry as S, PdfString as T, PdfDict as _, PdfListboxField as a, PdfNumber as b, PdfCheckboxField as c, FieldType as d, PdfField as f, PdfBool as g, PdfArray as h, PdfButtonField as i, PdfTextField as l, ByteWriter as m, RefResolver as n, PdfDropdownField as o, WidgetAnnotationHost as p, PdfSignatureField as r, PdfRadioGroup as s, PdfForm as t, FieldFlags as u, PdfName as v, PdfStream as w, PdfObject as x, PdfNull as y };
+//# sourceMappingURL=pdfForm-Ca86NDWn.d.mts.map