pdf.ts

import { Size, Rect, Position, Rotation } from './geometry';
import { Task, TaskError } from './task';

/**
 * Representation of pdf page
 *
 * @public
 */
export interface PdfPageObject {
  /**
   * Index of this page, starts from 0
   */
  index: number;

  /**
   * Orignal size of this page
   */
  size: Size;

  /**
   * Rotation of this page
   */
  rotation: Rotation;
}

/**
 * Representation of pdf page with rotated size
 *
 * @public
 */
export interface PdfPageObjectWithRotatedSize extends PdfPageObject {
  /**
   * Rotated size of this page
   */
  rotatedSize: Size;
}

/**
 * Representation of pdf document
 *
 * @public
 */
export interface PdfDocumentObject {
  /**
   * Identity of document
   */
  id: string;

  /**
   * Count of pages in this document
   */
  pageCount: number;

  /**
   * Pages in this document
   */
  pages: PdfPageObject[];

  /**
   * Whether the document is encrypted
   */
  isEncrypted: boolean;

  /**
   * Whether owner permissions are currently unlocked
   */
  isOwnerUnlocked: boolean;

  /**
   * Raw permission flags from FPDF_GetDocPermissions.
   * Use PdfPermissionFlag to check individual permissions.
   */
  permissions: number;

  /**
   * Whether page rotation was normalized when opening the document.
   * When true, all page coordinates are in 0° space regardless of original rotation.
   */
  normalizedRotation: boolean;
}

/**
 * metadata of pdf document
 *
 * @public
 */
export interface PdfMetadataObject {
  /**
   * title of the document
   */
  title: string | null;
  /**
   * author of the document
   */
  author: string | null;
  /**
   * subject of the document
   */
  subject: string | null;
  /**
   * keywords of the document
   */
  keywords: string | null;
  /**
   * producer of the document
   */
  producer: string | null;
  /**
   * creator of the document
   */
  creator: string | null;
  /**
   * creation date of the document
   */
  creationDate: Date | null;
  /**
   * modification date of the document
   */
  modificationDate: Date | null;
  /**
   * trapped status of the document
   */
  trapped: PdfTrappedStatus | null;

  /**
   * Non-predefined Info dictionary entries.
   */
  custom?: Record<string, string | null>;
}

/**
 * Unicode **soft-hyphen** marker (`U+00AD`).
 * Often embedded by PDF generators as discretionary hyphens.
 *
 * @public
 */
export const PdfSoftHyphenMarker = '\u00AD';

/**
 * Unicode **zero-width space** (`U+200B`).
 *
 * @public
 */
export const PdfZeroWidthSpace = '\u200B';

/**
 * Unicode **word-joiner** (`U+2060`) – zero-width no-break.
 *
 * @public
 */
export const PdfWordJoiner = '\u2060';

/**
 * Unicode **byte-order mark / zero-width&nbsp;no-break space** (`U+FEFF`).
 *
 * @public
 */
export const PdfBomOrZwnbsp = '\uFEFF';

/**
 * Unicode non-character `U+FFFE`.
 *
 * @public
 */
export const PdfNonCharacterFFFE = '\uFFFE';

/**
 * Unicode non-character `U+FFFF`.
 *
 * @public
 */
export const PdfNonCharacterFFFF = '\uFFFF';

/**
 * **Frozen list** of all unwanted markers in canonical order.
 *
 * @public
 */
export const PdfUnwantedTextMarkers = Object.freeze([
  PdfSoftHyphenMarker,
  PdfZeroWidthSpace,
  PdfWordJoiner,
  PdfBomOrZwnbsp,
  PdfNonCharacterFFFE,
  PdfNonCharacterFFFF,
] as const);

/**
 * Compiled regular expression that matches any unwanted marker.
 *
 * @public
 */
export const PdfUnwantedTextRegex = new RegExp(`[${PdfUnwantedTextMarkers.join('')}]`, 'g');

/**
 * Remove all {@link PdfUnwantedTextMarkers | unwanted markers} from *text*.
 *
 * @param text - raw text extracted from PDF
 * @returns cleaned text
 *
 * @public
 */
export function stripPdfUnwantedMarkers(text: string): string {
  return text.replace(PdfUnwantedTextRegex, '');
}

/**
 * Zoom mode
 *
 * @public
 */
export enum PdfZoomMode {
  Unknown = 0,
  /**
   * Zoom level with specified offset.
   */
  XYZ = 1,
  /**
   * Fit both the width and height of the page (whichever smaller).
   */
  FitPage = 2,
  /**
   * Fit the entire page width to the window.
   */
  FitHorizontal = 3,
  /**
   * Fit the entire page height to the window.
   */
  FitVertical = 4,
  /**
   * Fit a specific rectangle area within the window.
   */
  FitRectangle = 5,
  /**
   * Fit bounding box of the entire page (including annotations).
   */
  FitBoundingBox = 6,
  /**
   * Fit the bounding box width of the page.
   */
  FitBoundingBoxHorizontal = 7,
  /**
   * Fit the bounding box height of the page.
   */
  FitBoundingBoxVertical = 8,
}

/**
 * Trapped status of the document.
 *
 * @public
 */
export enum PdfTrappedStatus {
  /**
   * No /Trapped key
   */
  NotSet = 0,
  /**
   * Explicitly /Trapped /True
   */
  True = 1,
  /**
   * Explicitly /Trapped /False
   */
  False = 2,
  /**
   * Explicitly /Trapped /Unknown or invalid
   */
  Unknown = 3,
}

/**
 *  12 default fonts for PDF
 */
export enum PdfStandardFont {
  Unknown = -1,
  Courier = 0,
  Courier_Bold = 1,
  Courier_BoldOblique = 2,
  Courier_Oblique = 3,
  Helvetica = 4,
  Helvetica_Bold = 5,
  Helvetica_BoldOblique = 6,
  Helvetica_Oblique = 7,
  Times_Roman = 8,
  Times_Bold = 9,
  Times_BoldItalic = 10,
  Times_Italic = 11,
  Symbol = 12,
  ZapfDingbats = 13,
}

/**
 * Text alignment
 */
export enum PdfTextAlignment {
  Left = 0,
  Center = 1,
  Right = 2,
}

/**
 * Vertical alignment
 */
export enum PdfVerticalAlignment {
  Top = 0,
  Middle = 1,
  Bottom = 2,
}

/**
 * Blend mode
 *
 * @public
 */
export enum PdfBlendMode {
  Normal = 0,
  Multiply = 1,
  Screen = 2,
  Overlay = 3,
  Darken = 4,
  Lighten = 5,
  ColorDodge = 6,
  ColorBurn = 7,
  HardLight = 8,
  SoftLight = 9,
  Difference = 10,
  Exclusion = 11,
  Hue = 12,
  Saturation = 13,
  Color = 14,
  Luminosity = 15,
}

/**
 * Stamp fit
 */
export enum PdfStampFit {
  Contain = 0,
  Cover = 1,
  Stretch = 2,
}

/**
 * Representation of the linked destination
 *
 * @public
 */
export interface PdfDestinationObject {
  /**
   * Index of target page
   */
  pageIndex: number;
  /**
   * zoom config for target destination
   */
  zoom:
    | {
        mode: PdfZoomMode.Unknown;
      }
    | { mode: PdfZoomMode.XYZ; params: { x: number; y: number; zoom: number } }
    | {
        mode: PdfZoomMode.FitPage;
      }
    | {
        mode: PdfZoomMode.FitHorizontal;
      }
    | {
        mode: PdfZoomMode.FitVertical;
      }
    | {
        mode: PdfZoomMode.FitRectangle;
      }
    | {
        mode: PdfZoomMode.FitBoundingBox;
      }
    | {
        mode: PdfZoomMode.FitBoundingBoxHorizontal;
      }
    | {
        mode: PdfZoomMode.FitBoundingBoxVertical;
      };
  view: number[];
}

/**
 * Type of pdf action
 *
 * @public
 */
export enum PdfActionType {
  Unsupported = 0,
  /**
   * Goto specified position in this document
   */
  Goto = 1,
  /**
   * Goto specified position in another document
   */
  RemoteGoto = 2,
  /**
   * Goto specified URI
   */
  URI = 3,
  /**
   * Launch specifed application
   */
  LaunchAppOrOpenFile = 4,
}

export type PdfImage = {
  data: Uint8ClampedArray<ArrayBuffer>;
  width: number;
  height: number;
};

/**
 * Image data type that matches both browser's ImageData and plain objects.
 * Used for raw rendering output that may include colorSpace from browser APIs.
 *
 * @public
 */
export type ImageDataLike = {
  data: Uint8ClampedArray<ArrayBuffer>;
  width: number;
  height: number;
  colorSpace?: PredefinedColorSpace;
};

/**
 * Bitmask constants for annotation appearance stream modes.
 * @public
 */
export const AP_MODE_NORMAL = 1; // bit 0
export const AP_MODE_ROLLOVER = 2; // bit 1
export const AP_MODE_DOWN = 4; // bit 2

/**
 * A rendered appearance stream image for a single mode of an annotation.
 * @public
 */
export interface AnnotationAppearanceImage<TImage = ImageDataLike> {
  data: TImage;
  rect: Rect;
}

/**
 * All available appearance stream images for one annotation,
 * keyed by mode (normal, rollover, down).
 * @public
 */
export interface AnnotationAppearances<TImage = ImageDataLike> {
  normal?: AnnotationAppearanceImage<TImage>;
  rollover?: AnnotationAppearanceImage<TImage>;
  down?: AnnotationAppearanceImage<TImage>;
}

/**
 * Map of annotation ID to its rendered appearance stream images.
 * @public
 */
export type AnnotationAppearanceMap<TImage = ImageDataLike> = Record<
  string,
  AnnotationAppearances<TImage>
>;

/**
 * Representation of pdf action
 *
 * @public
 */
export type PdfActionObject =
  | {
      type: PdfActionType.Unsupported;
    }
  | {
      type: PdfActionType.Goto;
      destination: PdfDestinationObject;
    }
  | {
      type: PdfActionType.RemoteGoto;
      destination: PdfDestinationObject;
    }
  | {
      type: PdfActionType.URI;
      uri: string;
    }
  | {
      type: PdfActionType.LaunchAppOrOpenFile;
      path: string;
    };

/**
 * target of pdf link
 *
 * @public
 */
export type PdfLinkTarget =
  | {
      type: 'action';
      action: PdfActionObject;
    }
  | {
      type: 'destination';
      destination: PdfDestinationObject;
    };

/**
 * PDF bookmark
 *
 * @public
 */
export interface PdfBookmarkObject {
  /**
   * title of bookmark
   */
  title: string;

  /**
   * target of bookmark
   */
  target?: PdfLinkTarget | undefined;

  /**
   * bookmarks in the next level
   */
  children?: PdfBookmarkObject[];
}

/**
 * Pdf Signature
 *
 * @public
 */
export interface PdfSignatureObject {
  /**
   * contents of signature
   */
  contents: ArrayBuffer;

  /**
   * byte range of signature
   */
  byteRange: ArrayBuffer;

  /**
   * sub filters of signature
   */
  subFilter: ArrayBuffer;

  /**
   * reason of signature
   */
  reason: string;

  /**
   * creation time of signature
   */
  time: string;

  /**
   * MDP
   */
  docMDP: number;
}

/**
 * Bookmark tree of pdf
 *
 * @public
 */
export interface PdfBookmarksObject {
  bookmarks: PdfBookmarkObject[];
}

/**
 * Text rectangle in pdf page
 *
 * @public
 */
export interface PdfTextRectObject {
  /**
   * Font of the text
   */
  font: {
    /**
     * font family
     */
    family: string;

    /**
     * font size
     */
    size: number;
  };

  /**
   * content in this rectangle area
   */
  content: string;

  /**
   * rectangle of the text
   */
  rect: Rect;
}

/**
 * Color
 *
 * @public
 */
export interface PdfAlphaColor {
  /**
   * red
   */
  red: number;
  /**
   * green
   */
  green: number;
  /**
   * blue
   */
  blue: number;
  /**
   * alpha
   */
  alpha: number;
}

/**
 * Color
 *
 * @public
 */
export interface PdfColor {
  red: number;
  green: number;
  blue: number;
}

/**
 * Annotation type
 *
 * @public
 */
export enum PdfAnnotationSubtype {
  UNKNOWN = 0,
  TEXT,
  LINK,
  FREETEXT,
  LINE,
  SQUARE,
  CIRCLE,
  POLYGON,
  POLYLINE,
  HIGHLIGHT,
  UNDERLINE,
  SQUIGGLY,
  STRIKEOUT,
  STAMP,
  CARET,
  INK,
  POPUP,
  FILEATTACHMENT,
  SOUND,
  MOVIE,
  WIDGET,
  SCREEN,
  PRINTERMARK,
  TRAPNET,
  WATERMARK,
  THREED,
  RICHMEDIA,
  XFAWIDGET,
  REDACT,
}

/**
 * Name of annotation type
 *
 * @public
 */
export const PdfAnnotationSubtypeName: Record<PdfAnnotationSubtype, string> = {
  [PdfAnnotationSubtype.UNKNOWN]: 'unknow',
  [PdfAnnotationSubtype.TEXT]: 'text',
  [PdfAnnotationSubtype.LINK]: 'link',
  [PdfAnnotationSubtype.FREETEXT]: 'freetext',
  [PdfAnnotationSubtype.LINE]: 'line',
  [PdfAnnotationSubtype.SQUARE]: 'square',
  [PdfAnnotationSubtype.CIRCLE]: 'circle',
  [PdfAnnotationSubtype.POLYGON]: 'polygon',
  [PdfAnnotationSubtype.POLYLINE]: 'polyline',
  [PdfAnnotationSubtype.HIGHLIGHT]: 'highlight',
  [PdfAnnotationSubtype.UNDERLINE]: 'underline',
  [PdfAnnotationSubtype.SQUIGGLY]: 'squiggly',
  [PdfAnnotationSubtype.STRIKEOUT]: 'strikeout',
  [PdfAnnotationSubtype.STAMP]: 'stamp',
  [PdfAnnotationSubtype.CARET]: 'caret',
  [PdfAnnotationSubtype.INK]: 'ink',
  [PdfAnnotationSubtype.POPUP]: 'popup',
  [PdfAnnotationSubtype.FILEATTACHMENT]: 'fileattachment',
  [PdfAnnotationSubtype.SOUND]: 'sound',
  [PdfAnnotationSubtype.MOVIE]: 'movie',
  [PdfAnnotationSubtype.WIDGET]: 'widget',
  [PdfAnnotationSubtype.SCREEN]: 'screen',
  [PdfAnnotationSubtype.PRINTERMARK]: 'printermark',
  [PdfAnnotationSubtype.TRAPNET]: 'trapnet',
  [PdfAnnotationSubtype.WATERMARK]: 'watermark',
  [PdfAnnotationSubtype.THREED]: 'threed',
  [PdfAnnotationSubtype.RICHMEDIA]: 'richmedia',
  [PdfAnnotationSubtype.XFAWIDGET]: 'xfawidget',
  [PdfAnnotationSubtype.REDACT]: 'redact',
};

/**
 * Context map for annotation subtypes
 *
 * @public
 */
export interface AnnotationContextMap {
  [PdfAnnotationSubtype.STAMP]:
    | {
        data: ArrayBuffer;
        mimeType?: import('./image-metadata').ImageMimeType;
        imageData?: never;
        appearance?: never;
      }
    | { imageData: ImageData; data?: never; mimeType?: never; appearance?: never }
    /** @deprecated Use `{ data: ArrayBuffer }` instead. */
    | { appearance: ArrayBuffer; imageData?: never; data?: never; mimeType?: never };
}

/**
 * Context type for annotation subtypes
 *
 * @public
 */
export type AnnotationCreateContext<A extends PdfAnnotationObject> =
  A['type'] extends keyof AnnotationContextMap ? AnnotationContextMap[A['type']] : undefined;

/**
 * Status of pdf annotation
 *
 * @public
 */
export enum PdfAnnotationObjectStatus {
  /**
   * Annotation is created
   */
  Created,
  /**
   * Annotation is committed to PDF file
   */
  Committed,
}

/**
 * Appearance mode
 *
 * @public
 */
export enum AppearanceMode {
  Normal = 0,
  Rollover = 1,
  Down = 2,
}

/**
 * State of pdf annotation
 *
 * @public
 */
export enum PdfAnnotationState {
  /**
   * Annotation is active
   */
  Marked = 'Marked',
  /**
   * Annotation is unmarked
   */
  Unmarked = 'Unmarked',
  /**
   * Annotation is ink
   */
  Accepted = 'Accepted',
  /**
   * Annotation is rejected
   */
  Rejected = 'Rejected',
  /**
   * Annotation is complete
   */
  Completed = 'Completed',
  /**
   * Annotation is cancelled
   */
  Cancelled = 'Cancelled',
  /**
   * Annotation is none
   */
  None = 'None',
}

/**
 * State model of pdf annotation
 *
 * @public
 */
export enum PdfAnnotationStateModel {
  /**
   * Annotation is marked
   */
  Marked = 'Marked',
  /**
   * Annotation is reviewed
   */
  Review = 'Review',
}

/**
 * Name (/Name entry) of a pdf annotation — identifies the icon for text/sound/file
 * annotations and the stamp type for stamp annotations.
 *
 * @public
 */
export enum PdfAnnotationName {
  Unknown = -1,
  Comment = 0,
  Key = 1,
  Note = 2,
  Help = 3,
  NewParagraph = 4,
  Paragraph = 5,
  Insert = 6,
  Graph = 7,
  PushPin = 8,
  Paperclip = 9,
  Tag = 10,
  Speaker = 11,
  Mic = 12,
  Approved = 13,
  Experimental = 14,
  NotApproved = 15,
  AsIs = 16,
  Expired = 17,
  NotForPublicRelease = 18,
  Confidential = 19,
  Final = 20,
  Sold = 21,
  Departmental = 22,
  ForComment = 23,
  TopSecret = 24,
  Draft = 25,
  ForPublicRelease = 26,
  Completed = 27,
  Void = 28,
  PreliminaryResults = 29,
  InformationOnly = 30,
  Rejected = 31,
  Witness = 32,
  InitialHere = 33,
  SignHere = 34,
  Accepted = 35,
  Custom = 36,
  Image = 37,
}

/** @deprecated Use PdfAnnotationName instead */
export type PdfAnnotationIcon = PdfAnnotationName;
/** @deprecated Use PdfAnnotationName instead */
export const PdfAnnotationIcon = PdfAnnotationName;

/**
 * Line ending of annotation
 */
export enum PdfAnnotationLineEnding {
  /**
   * No line ending
   */
  None = 0,
  /**
   * Square line ending
   */
  Square = 1,
  /**
   * Circle line ending
   */
  Circle = 2,
  /**
   * Diamond line ending
   */
  Diamond = 3,
  /**
   * Open arrow line ending
   */
  OpenArrow = 4,
  /**
   * Closed arrow line ending
   */
  ClosedArrow = 5,
  /**
   * Butt line ending
   */
  Butt = 6,
  /**
   * Right open arrow line ending
   */
  ROpenArrow = 7,
  /**
   * Right closed arrow line ending
   */
  RClosedArrow = 8,
  /**
   * Slash line ending
   */
  Slash = 9,
  /**
   * Unknown line ending
   */
  Unknown = 10,
}

/**
 * Reply type of annotation (RT property per ISO 32000-2)
 *
 * Specifies how an annotation relates to another annotation when it is
 * a reply (via IRT - In Reply To). Valid values are:
 * - Reply (/R): Normal comment reply (default if RT is missing)
 * - Group (/Group): Logical grouping of annotations
 *
 * @public
 */
export enum PdfAnnotationReplyType {
  /**
   * Unknown or invalid reply type
   */
  Unknown = 0,
  /**
   * /R - Comment reply (default if RT is missing)
   * The annotation is a child comment of the annotation referenced by IRT.
   * Used for comment threads, reviewer discussions, sticky-note replies.
   */
  Reply = 1,
  /**
   * /Group - Logical grouping
   * The annotation is grouped with the annotation referenced by IRT.
   * They represent the same logical object. Used when multiple annotations
   * act as one unit (e.g., visual shape + metadata/label).
   */
  Group = 2,
}

/**
 * Rectangle differences (/RD) defining the inset between an annotation's
 * /Rect and the actual drawn appearance.
 *
 * @public
 */
export interface PdfRectDifferences {
  left: number;
  top: number;
  right: number;
  bottom: number;
}

/**
 * Basic information of pdf annotation
 *
 * @public
 */
export interface PdfAnnotationObjectBase {
  /**
   * Author of the annotation
   */
  author?: string;

  /**
   * Modified date of the annotation
   */
  modified?: Date;

  /**
   * Created date of the annotation
   */
  created?: Date;

  /**
   * blend mode of annotation
   */
  blendMode?: PdfBlendMode;

  /**
   * intent of annotation
   */
  intent?: string;

  /**
   * Sub type of annotation
   */
  type: PdfAnnotationSubtype;

  /**
   * flags of the annotation
   */
  flags?: PdfAnnotationFlagName[];

  /**
   * The index of page that this annotation belong to
   */
  pageIndex: number;

  /**
   * contents of the annotation
   */
  contents?: string;

  /**
   * id of the annotation
   */
  id: string;

  /**
   * Rectangle of the annotation
   */
  rect: Rect;

  /**
   * Rotation angle in degrees (clockwise).
   * When set, the annotation is visually rotated around its center.
   * The rect becomes the axis-aligned bounding box after rotation.
   */
  rotation?: number;

  /**
   * The original unrotated rectangle of the annotation.
   * This is stored when rotation is applied, allowing accurate editing.
   */
  unrotatedRect?: Rect;

  /**
   * Custom data of the annotation
   */
  custom?: any;

  /**
   * Bitmask of available appearance stream modes.
   * bit 0 (1) = Normal, bit 1 (2) = Rollover, bit 2 (4) = Down.
   * 0 or undefined = no appearance stream.
   */
  appearanceModes?: number;

  /**
   * In reply to annotation id (IRT - for grouping or reply threads)
   */
  inReplyToId?: string;

  /**
   * Reply type (how this annotation relates to the parent via IRT)
   */
  replyType?: PdfAnnotationReplyType;

  /**
   * Subject of the annotation
   */
  subject?: string;
}

/**
 * Popup annotation
 *
 * @public
 */
export interface PdfPopupAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.POPUP;
  /**
   * Contents of the popup
   */
  contents: string;

  /**
   * Whether the popup is opened or not
   */
  open: boolean;
}

/**
 * Pdf Link annotation
 *
 * @public
 */
export interface PdfLinkAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.LINK;
  /**
   * target of the link
   */
  target: PdfLinkTarget | undefined;

  /**
   * Stroke color of the link border (e.g., "#00A5E4")
   */
  strokeColor?: string;

  /**
   * Width of the link border (default: 2)
   */
  strokeWidth?: number;

  /**
   * Style of the link border (default: UNDERLINE)
   */
  strokeStyle?: PdfAnnotationBorderStyle;

  /**
   * Dash pattern for dashed border style
   */
  strokeDashArray?: number[];
}

/**
 * Pdf Text annotation
 *
 * @public
 */
export interface PdfTextAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.TEXT;
  /**
   * Text contents of the annotation
   */
  contents: string;

  /**
   * Color of the text annotation (preferred over deprecated `color`)
   */
  strokeColor?: string;

  /**
   * @deprecated Use strokeColor instead. Will be removed in next major version.
   */
  color?: string;

  /**
   * opacity of text annotation
   */
  opacity?: number;

  /**
   * State of the text annotation
   */
  state?: PdfAnnotationState;

  /**
   * State model of the text annotation
   */
  stateModel?: PdfAnnotationStateModel;

  /**
   * Name (/Name entry) of the text annotation
   */
  name?: PdfAnnotationName;

  /** @deprecated Use name instead */
  icon?: PdfAnnotationIcon;
}

/**
 * Type of form field
 *
 * @public
 */
export enum PDF_FORM_FIELD_TYPE {
  /**
   * Unknow
   */
  UNKNOWN = 0,
  /**
   * push button type
   */
  PUSHBUTTON = 1,
  /**
   * check box type.
   */
  CHECKBOX = 2,
  /**
   * radio button type.
   */
  RADIOBUTTON = 3,
  /**
   * combo box type.
   */
  COMBOBOX = 4,
  /**
   * list box type.
   */
  LISTBOX = 5,
  /**
   *  text field type
   */
  TEXTFIELD = 6,
  /**
   * signature field type.
   */
  SIGNATURE = 7,
  /**
   * Generic XFA type.
   */
  XFA = 8,
  /**
   * XFA check box type.
   */
  XFA_CHECKBOX = 9,
  /**
   * XFA combo box type.
   */
  XFA_COMBOBOX = 10,
  /**
   * XFA image field type.
   */
  XFA_IMAGEFIELD = 11,
  /**
   * XFA list box type.
   */
  XFA_LISTBOX = 12,
  /**
   * XFA push button type.
   */
  XFA_PUSHBUTTON = 13,
  /**
   * XFA signture field type.
   */
  XFA_SIGNATURE = 14,
  /**
   * XFA text field type.
   */
  XFA_TEXTFIELD = 15,
}

export enum PdfAnnotationColorType {
  Color = 0,
  InteriorColor = 1,
  OverlayColor = 2,
  TextColor = 3,
}

/**
 * Border style of pdf annotation
 *
 * @public
 */
export enum PdfAnnotationBorderStyle {
  UNKNOWN = 0,
  SOLID = 1,
  DASHED = 2,
  BEVELED = 3,
  INSET = 4,
  UNDERLINE = 5,
  CLOUDY = 6,
}

/**
 * Flag of pdf annotation
 *
 * @public
 */
export enum PdfAnnotationFlags {
  NONE = 0,
  INVISIBLE = 1 << 0,
  HIDDEN = 1 << 1,
  PRINT = 1 << 2,
  NO_ZOOM = 1 << 3,
  NO_ROTATE = 1 << 4,
  NO_VIEW = 1 << 5,
  READ_ONLY = 1 << 6,
  LOCKED = 1 << 7,
  TOGGLE_NOVIEW = 1 << 8,
  LOCKED_CONTENTS = 1 << 9,
}

/**
 * Flag of form field
 *
 * @public
 */
export enum PDF_FORM_FIELD_FLAG {
  NONE = 0,
  // Common flags (PDF 1.7 Table 8.70)
  READONLY = 1 << 0,
  REQUIRED = 1 << 1,
  NOEXPORT = 1 << 2,
  // Text field flags (PDF 1.7 Table 8.77)
  TEXT_MULTIPLINE = 1 << 12,
  TEXT_PASSWORD = 1 << 13,
  TEXT_FILESELECT = 1 << 20,
  TEXT_DONOTSPELLCHECK = 1 << 22,
  TEXT_DONOTSCROLL = 1 << 23,
  TEXT_COMB = 1 << 24,
  TEXT_RICHTEXT = 1 << 25,
  // Button field flags (PDF 1.7 Table 8.75)
  BUTTON_NOTOGGLETOOFF = 1 << 14,
  BUTTON_RADIO = 1 << 15,
  BUTTON_PUSHBUTTON = 1 << 16,
  BUTTON_RADIOSINUNISON = 1 << 25,
  // Choice field flags (PDF 1.7 Table 8.79)
  CHOICE_COMBO = 1 << 17,
  CHOICE_EDIT = 1 << 18,
  CHOICE_SORT = 1 << 19,
  CHOICE_MULTL_SELECT = 1 << 21,
  CHOICE_DONOTSPELLCHECK = 1 << 22,
  CHOICE_COMMITONSELCHANGE = 1 << 26,
}

/**
 * Type of pdf object
 *
 * @public
 */
export enum PdfPageObjectType {
  UNKNOWN = 0,
  TEXT = 1,
  PATH = 2,
  IMAGE = 3,
  SHADING = 4,
  FORM = 5,
}

/**
 * Line points
 *
 * @public
 */
export interface LinePoints {
  start: Position;
  end: Position;
}

/**
 * Line endings
 *
 * @public
 */
export interface LineEndings {
  start: PdfAnnotationLineEnding;
  end: PdfAnnotationLineEnding;
}

/**
 * Options of pdf widget annotation
 *
 * @public
 */
export interface PdfWidgetAnnoOption {
  label: string;
  isSelected: boolean;
}

export type PdfAnnotationFlagName =
  | 'invisible'
  | 'hidden'
  | 'print'
  | 'noZoom'
  | 'noRotate'
  | 'noView'
  | 'readOnly'
  | 'locked'
  | 'toggleNoView'
  | 'lockedContents';

type FlagMap = Partial<
  Record<Exclude<PdfAnnotationFlags, PdfAnnotationFlags.NONE>, PdfAnnotationFlagName>
>;

export const PdfAnnotationFlagName: Readonly<FlagMap> = Object.freeze({
  [PdfAnnotationFlags.INVISIBLE]: 'invisible',
  [PdfAnnotationFlags.HIDDEN]: 'hidden',
  [PdfAnnotationFlags.PRINT]: 'print',
  [PdfAnnotationFlags.NO_ZOOM]: 'noZoom',
  [PdfAnnotationFlags.NO_ROTATE]: 'noRotate',
  [PdfAnnotationFlags.NO_VIEW]: 'noView',
  [PdfAnnotationFlags.READ_ONLY]: 'readOnly',
  [PdfAnnotationFlags.LOCKED]: 'locked',
  [PdfAnnotationFlags.TOGGLE_NOVIEW]: 'toggleNoView',
  [PdfAnnotationFlags.LOCKED_CONTENTS]: 'lockedContents',
} as const);

/** Build a reverse map once so look-ups are O(1)                      */
const PdfAnnotationFlagValue: Record<PdfAnnotationFlagName, PdfAnnotationFlags> = Object.entries(
  PdfAnnotationFlagName,
).reduce(
  (acc, [bit, name]) => {
    acc[name as PdfAnnotationFlagName] = Number(bit) as PdfAnnotationFlags;
    return acc;
  },
  {} as Record<PdfAnnotationFlagName, PdfAnnotationFlags>,
);

/**
 * Convert the raw bit-mask coming from `FPDFAnnot_GetFlags()` into
 * an array of human-readable flag names (“invisible”, “print”…).
 */
export function flagsToNames(raw: number): PdfAnnotationFlagName[] {
  return (
    Object.keys(PdfAnnotationFlagName) as unknown as Exclude<
      PdfAnnotationFlags,
      PdfAnnotationFlags.NONE
    >[]
  )
    .filter((flag) => (raw & flag) !== 0)
    .map((flag) => PdfAnnotationFlagName[flag]!);
}

/**
 * Convert an array of flag-names back into the numeric mask that
 * PDFium expects for `FPDFAnnot_SetFlags()`.
 */
export function namesToFlags(names: readonly PdfAnnotationFlagName[]): PdfAnnotationFlags {
  return names.reduce<PdfAnnotationFlags>(
    (mask, name) => mask | PdfAnnotationFlagValue[name],
    PdfAnnotationFlags.NONE,
  );
}

/**
 * Shared properties across all widget annotation field types
 *
 * @public
 */
export interface PdfWidgetAnnoFieldBase {
  flag: PDF_FORM_FIELD_FLAG;
  name: string;
  alternateName: string;
  value: string;
  fieldObjectId?: number;
}

/**
 * @public
 */
export interface PdfTextWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type: PDF_FORM_FIELD_TYPE.TEXTFIELD;
  maxLen?: number;
}

/**
 * @public
 */
export interface PdfCheckboxWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type: PDF_FORM_FIELD_TYPE.CHECKBOX;
}

/**
 * @public
 */
export interface PdfRadioButtonWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type: PDF_FORM_FIELD_TYPE.RADIOBUTTON;
  options: PdfWidgetAnnoOption[];
}

/**
 * @public
 */
export interface PdfComboboxWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type: PDF_FORM_FIELD_TYPE.COMBOBOX;
  options: PdfWidgetAnnoOption[];
}

/**
 * @public
 */
export interface PdfListboxWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type: PDF_FORM_FIELD_TYPE.LISTBOX;
  options: PdfWidgetAnnoOption[];
}

/**
 * @public
 */
export interface PdfPushButtonWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type: PDF_FORM_FIELD_TYPE.PUSHBUTTON;
}

/**
 * @public
 */
export interface PdfSignatureWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type: PDF_FORM_FIELD_TYPE.SIGNATURE;
}

/**
 * @public
 */
export interface PdfUnknownWidgetAnnoField extends PdfWidgetAnnoFieldBase {
  type:
    | PDF_FORM_FIELD_TYPE.UNKNOWN
    | PDF_FORM_FIELD_TYPE.XFA
    | PDF_FORM_FIELD_TYPE.XFA_CHECKBOX
    | PDF_FORM_FIELD_TYPE.XFA_COMBOBOX
    | PDF_FORM_FIELD_TYPE.XFA_IMAGEFIELD
    | PDF_FORM_FIELD_TYPE.XFA_LISTBOX
    | PDF_FORM_FIELD_TYPE.XFA_PUSHBUTTON
    | PDF_FORM_FIELD_TYPE.XFA_SIGNATURE
    | PDF_FORM_FIELD_TYPE.XFA_TEXTFIELD;
}

/**
 * Discriminated union of all widget annotation field types
 *
 * @public
 */
export type PdfWidgetAnnoField =
  | PdfTextWidgetAnnoField
  | PdfCheckboxWidgetAnnoField
  | PdfRadioButtonWidgetAnnoField
  | PdfComboboxWidgetAnnoField
  | PdfListboxWidgetAnnoField
  | PdfPushButtonWidgetAnnoField
  | PdfSignatureWidgetAnnoField
  | PdfUnknownWidgetAnnoField;

/**
 * PDF widget object
 *
 * @public
 */
export interface PdfWidgetAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.WIDGET;
  /**
   * Field of pdf widget object
   */
  field: PdfWidgetAnnoField;
  /**
   * The non-"Off" appearance state key from the widget's /AP/N dictionary.
   * For checkboxes this is typically "Yes"; for radio buttons it is a unique
   * identifier (usually the widget's NM). Checked state is derived:
   * `field.value === exportValue`.
   */
  exportValue?: string;
  /**
   * font family of pdf widget object
   */
  fontFamily: PdfStandardFont;
  /**
   * font size of pdf widget object
   */
  fontSize: number;
  /**
   * font color of pdf widget object
   */
  fontColor: string;
  /**
   * MK border color (BC) as web hex string, e.g. '#FF0000'
   */
  strokeColor?: string;
  /**
   * MK background color (BG) as web hex string, e.g. '#FFFFFF'
   */
  color?: string;
  /**
   * Border width in points (BS width)
   */
  strokeWidth?: number;
}

/**
 * Returns whether a toggle widget (checkbox / radio button) is currently
 * in its "on" state by comparing the shared field value against this
 * widget's unique export value from the /AP/N dictionary.
 *
 * @public
 */
export function isWidgetChecked(widget: PdfWidgetAnnoObject): boolean {
  return widget.exportValue != null && widget.field.value === widget.exportValue;
}

/**
 * Widget additional-action event types exposed by PDFium.
 *
 * @public
 */
export enum PDF_ANNOT_AACTION_EVENT {
  KEY_STROKE = 12,
  FORMAT = 13,
  VALIDATE = 14,
  CALCULATE = 15,
}

/**
 * Normalized widget JavaScript trigger names.
 *
 * @public
 */
export enum PdfJavaScriptWidgetEventType {
  Keystroke = 'keystroke',
  Format = 'format',
  Validate = 'validate',
  Calculate = 'calculate',
}

/**
 * Normalized JavaScript action trigger names.
 *
 * @public
 */
export enum PdfJavaScriptActionTrigger {
  DocumentNamed = 'document_named',
  WidgetKeystroke = 'widget_keystroke',
  WidgetFormat = 'widget_format',
  WidgetValidate = 'widget_validate',
  WidgetCalculate = 'widget_calculate',
}

/**
 * Base shape shared by extracted PDF JavaScript actions.
 *
 * @public
 */
export interface PdfJavaScriptActionObjectBase {
  /**
   * Stable identifier for the extracted action within the current document snapshot.
   */
  id: string;
  /**
   * Normalized trigger classification used by higher layers.
   */
  trigger: PdfJavaScriptActionTrigger;
  /**
   * Raw JavaScript source extracted from the PDF.
   */
  script: string;
}

/**
 * A named document-level JavaScript action from the document JavaScript name tree.
 *
 * @public
 */
export interface PdfDocumentJavaScriptActionObject extends PdfJavaScriptActionObjectBase {
  trigger: PdfJavaScriptActionTrigger.DocumentNamed;
  name: string;
}

/**
 * A widget-level JavaScript additional action.
 *
 * @public
 */
export interface PdfWidgetJavaScriptActionObject extends PdfJavaScriptActionObjectBase {
  trigger:
    | PdfJavaScriptActionTrigger.WidgetKeystroke
    | PdfJavaScriptActionTrigger.WidgetFormat
    | PdfJavaScriptActionTrigger.WidgetValidate
    | PdfJavaScriptActionTrigger.WidgetCalculate;
  eventType: PdfJavaScriptWidgetEventType;
  pageIndex: number;
  annotationId: string;
  fieldName: string;
}

/**
 * Discriminated union of supported extracted PDF JavaScript actions.
 *
 * @public
 */
export type PdfJavaScriptActionObject =
  | PdfDocumentJavaScriptActionObject
  | PdfWidgetJavaScriptActionObject;

/**
 * Pdf file attachments annotation
 *
 * @public
 */
export interface PdfFileAttachmentAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.FILEATTACHMENT;
}

/**
 * ink list in pdf ink annotation
 *
 * @public
 */
export interface PdfInkListObject {
  points: Position[];
}

/**
 * Pdf ink annotation
 *
 * @public
 */
export interface PdfInkAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.INK;
  /**
   * ink list of annotation
   */
  inkList: PdfInkListObject[];
  /**
   * Color of the ink stroke (preferred over deprecated `color`)
   */
  strokeColor?: string;
  /**
   * @deprecated Use strokeColor instead. Will be removed in next major version.
   */
  color?: string;

  /**
   * opacity of ink annotation
   */
  opacity: number;

  /**
   * stroke-width of ink annotation
   */
  strokeWidth: number;
}

/**
 * Pdf polygon annotation
 *
 * @public
 */
export interface PdfPolygonAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.POLYGON;

  /**
   * contents of polygon annotation
   */
  contents?: string;

  /**
   * vertices of annotation
   */
  vertices: Position[];

  /**
   * color of ink annotation
   */
  color: string;

  /**
   * opacity of ink annotation
   */
  opacity: number;

  /**
   * stroke-width of ink annotation
   */
  strokeWidth: number;

  /**
   * stroke color of polygon annotation
   */
  strokeColor: string;

  /**
   * stroke style of polygon annotation
   */
  strokeStyle: PdfAnnotationBorderStyle;

  /**
   * stroke dash array of polygon annotation
   */
  strokeDashArray?: number[];
  /**
   * cloudy border intensity of polygon annotation
   */
  cloudyBorderIntensity?: number;
  /**
   * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
   */
  rectangleDifferences?: PdfRectDifferences;
}

/**
 * PDF polyline annotation
 *
 * @public
 */
export interface PdfPolylineAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.POLYLINE;

  /**
   * contents of polyline annotation
   */
  contents?: string;

  /**
   * start and end line endings of polyline
   */
  lineEndings?: LineEndings;

  /**
   * vertices of annotation
   */
  vertices: Position[];

  /**
   * interior color of line annotation
   */
  color: string;

  /**
   * opacity of ink annotation
   */
  opacity: number;

  /**
   * stroke-width of ink annotation
   */
  strokeWidth: number;

  /**
   * stroke color of line annotation
   */
  strokeColor: string;

  /**
   * stroke style of polyline annotation
   */
  strokeStyle: PdfAnnotationBorderStyle;

  /**
   * stroke dash array of polyline annotation
   */
  strokeDashArray?: number[];
}

/**
 * PDF line annotation
 *
 * @public
 */
export interface PdfLineAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.LINE;

  /**
   * contents of line annotation
   */
  contents?: string;

  /**
   * start and end points of line
   */
  linePoints: LinePoints;

  /**
   * start and end line endings of line
   */
  lineEndings?: LineEndings;

  /**
   * interior color of line annotation
   */
  color: string;

  /**
   * opacity of ink annotation
   */
  opacity: number;

  /**
   * stroke-width of ink annotation
   */
  strokeWidth: number;

  /**
   * stroke color of line annotation
   */
  strokeColor: string;

  /**
   * stroke style of line annotation
   */
  strokeStyle: PdfAnnotationBorderStyle;

  /**
   * stroke dash array of line annotation
   */
  strokeDashArray?: number[];
}

/**
 * PDF highlight annotation
 *
 * @public
 */
export interface PdfHighlightAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.HIGHLIGHT;

  /**
   * Text contents of the highlight annotation
   */
  contents?: string;

  /**
   * Color of the highlight markup (preferred over deprecated `color`)
   */
  strokeColor?: string;
  /**
   * @deprecated Use strokeColor instead. Will be removed in next major version.
   */
  color?: string;

  /**
   * opacity of highlight annotation
   */
  opacity: number;

  /**
   * quads of highlight area
   */
  segmentRects: Rect[];
}

/**
 * Matrix for transformation, in the form [a b c d e f], equivalent to:
 * | a  b  0 |
 * | c  d  0 |
 * | e  f  1 |
 *
 * Translation is performed with [1 0 0 1 tx ty].
 * Scaling is performed with [sx 0 0 sy 0 0].
 * See PDF Reference 1.7, 4.2.2 Common Transformations for more.
 */
export interface PdfTransformMatrix {
  a: number;
  b: number;
  c: number;
  d: number;
  e: number;
  f: number;
}

/**
 * type of segment type in pdf path object
 *
 * @public
 */
export enum PdfSegmentObjectType {
  UNKNOWN = -1,
  LINETO = 0,
  BEZIERTO = 1,
  MOVETO = 2,
}

/**
 * segment of path object
 *
 * @public
 */
export interface PdfSegmentObject {
  type: PdfSegmentObjectType;
  /**
   * point of the segment
   */
  point: Position;
  /**
   * whether this segment close the path
   */
  isClosed: boolean;
}

/**
 * Pdf path object
 *
 * @public
 */
export interface PdfPathObject {
  type: PdfPageObjectType.PATH;
  /**
   * bound that contains the path
   */
  bounds: { left: number; bottom: number; right: number; top: number };
  /**
   * segments of the path
   */
  segments: PdfSegmentObject[];
  /**
   * transform matrix
   */
  matrix: PdfTransformMatrix;
}

/**
 * Pdf image object
 *
 * @public
 */
export interface PdfImageObject {
  type: PdfPageObjectType.IMAGE;
  /**
   * data of the image (cross-platform compatible, works in Node.js and browsers)
   */
  imageData: ImageDataLike;
  /**
   * transform matrix
   */
  matrix: PdfTransformMatrix;
}

/**
 * Pdf form object
 *
 * @public
 */
export interface PdfFormObject {
  type: PdfPageObjectType.FORM;
  /**
   * objects that in this form object
   */
  objects: (PdfImageObject | PdfPathObject | PdfFormObject)[];
  /**
   * transform matrix
   */
  matrix: PdfTransformMatrix;
}

/**
 * Contents type of pdf stamp annotation
 *
 * @public
 */
export type PdfStampAnnoObjectContents = Array<PdfPathObject | PdfImageObject | PdfFormObject>;

/**
 * Pdf stamp annotation
 *
 * @public
 */
export interface PdfStampAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.STAMP;
  /**
   * Name (/Name entry) of the stamp annotation
   */
  name?: PdfAnnotationName;

  /** @deprecated Use name instead */
  icon?: PdfAnnotationIcon;
}

/**
 * Pdf circle annotation
 *
 * @public
 */
export interface PdfCircleAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.CIRCLE;
  /**
   * flags of circle annotation
   */
  flags: PdfAnnotationFlagName[];
  /**
   * Text contents of the circle annotation
   */
  contents?: string;
  /**
   * color of circle annotation
   */
  color: string;
  /**
   * opacity of circle annotation
   */
  opacity: number;
  /**
   * stroke-width of circle annotation
   */
  strokeWidth: number;
  /**
   * stroke color of circle annotation
   */
  strokeColor: string;
  /**
   * stroke style of circle annotation
   */
  strokeStyle: PdfAnnotationBorderStyle;
  /**
   * stroke dash array of circle annotation
   */
  strokeDashArray?: number[];
  /**
   * cloudy border intensity of circle annotation
   */
  cloudyBorderIntensity?: number;
  /**
   * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
   */
  rectangleDifferences?: PdfRectDifferences;
}

/**
 * Pdf square annotation
 *
 * @public
 */
export interface PdfSquareAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.SQUARE;
  /**
   * Text contents of the square annotation
   */
  contents?: string;
  /**
   * flags of square annotation
   */
  flags: PdfAnnotationFlagName[];
  /**
   * color of square annotation
   */
  color: string;
  /**
   * opacity of square annotation
   */
  opacity: number;
  /**
   * stroke-width of square annotation
   */
  strokeWidth: number;
  /**
   * stroke color of square annotation
   */
  strokeColor: string;
  /**
   * stroke style of square annotation
   */
  strokeStyle: PdfAnnotationBorderStyle;
  /**
   * stroke dash array of square annotation
   */
  strokeDashArray?: number[];
  /**
   * cloudy border intensity of circle annotation
   */
  cloudyBorderIntensity?: number;
  /**
   * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
   */
  rectangleDifferences?: PdfRectDifferences;
}

/**
 * Pdf squiggly annotation
 *
 * @public
 */
export interface PdfSquigglyAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.SQUIGGLY;
  /**
   * Text contents of the squiggly annotation
   */
  contents?: string;
  /**
   * Color of the squiggly markup (preferred over deprecated `color`)
   */
  strokeColor?: string;
  /**
   * @deprecated Use strokeColor instead. Will be removed in next major version.
   */
  color?: string;

  /**
   * opacity of squiggly annotation
   */
  opacity: number;
  /**
   * quads of squiggly area
   */
  segmentRects: Rect[];
}

/**
 * Pdf underline annotation
 *
 * @public
 */
export interface PdfUnderlineAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.UNDERLINE;
  /**
   * Text contents of the underline annotation
   */
  contents?: string;
  /**
   * Color of the underline markup (preferred over deprecated `color`)
   */
  strokeColor?: string;
  /**
   * @deprecated Use strokeColor instead. Will be removed in next major version.
   */
  color?: string;

  /**
   * opacity of underline annotation
   */
  opacity: number;
  /**
   * quads of underline area
   */
  segmentRects: Rect[];
}

/**
 * Pdf strike out annotation
 *
 * @public
 */
export interface PdfStrikeOutAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.STRIKEOUT;
  /**
   * Text contents of the strike out annotation
   */
  contents?: string;

  /**
   * Color of the strikeout markup (preferred over deprecated `color`)
   */
  strokeColor?: string;
  /**
   * @deprecated Use strokeColor instead. Will be removed in next major version.
   */
  color?: string;

  /**
   * opacity of strike out annotation
   */
  opacity: number;

  /**
   * quads of strikeout area
   */
  segmentRects: Rect[];
}

/**
 * Pdf caret annotation
 *
 * @public
 */
export interface PdfCaretAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.CARET;
  /** Stroke color of the caret symbol */
  strokeColor?: string;
  /** Opacity (0-1) */
  opacity?: number;
  /**
   * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
   */
  rectangleDifferences?: PdfRectDifferences;
}

/**
 * Pdf free text annotation
 *
 * @public
 */
export interface PdfFreeTextAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.FREETEXT;
  /**
   * Text contents of the free text annotation
   */
  contents: string;
  /**
   * Font family of the free text annotation
   */
  fontFamily: PdfStandardFont;
  /**
   * Font size of the free text annotation
   */
  fontSize: number;
  /**
   * Font color of the free text annotation
   */
  fontColor: string;
  /**
   * Text alignment of the free text annotation
   */
  textAlign: PdfTextAlignment;
  /**
   * Vertical alignment of the free text annotation
   */
  verticalAlign: PdfVerticalAlignment;
  /**
   * Opacity of the free text annotation
   */
  opacity: number;
  /**
   * Background/fill color of the free text annotation (matches shape convention)
   */
  color?: string;
  /**
   * @deprecated Use color instead. Will be removed in next major version.
   */
  backgroundColor?: string;
  /**
   * Default style of the free text annotation
   */
  defaultStyle?: string;
  /**
   * Rich content of the free text annotation
   */
  richContent?: string;
  /**
   * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
   */
  rectangleDifferences?: PdfRectDifferences;
  /**
   * Callout line points (PDF /CL array).
   * 2 points for a simple leader line, 3 points for a knee-jointed leader line.
   * Points are in device coordinates (same as rect/vertices).
   * Present only when intent is 'FreeTextCallout'.
   */
  calloutLine?: Position[];
  /**
   * Line ending style for the callout leader line (PDF /LE).
   * Only meaningful when calloutLine is present.
   */
  lineEnding?: PdfAnnotationLineEnding;
  /**
   * Border / callout line stroke width (from /BS -> W).
   */
  strokeWidth?: number;
  /**
   * Border / callout line stroke color (from /DA rg color).
   */
  strokeColor?: string;
}

/**
 * Pdf redact annotation
 *
 * @public
 */
export interface PdfRedactAnnoObject extends PdfAnnotationObjectBase {
  /** {@inheritDoc PdfAnnotationObjectBase.type} */
  type: PdfAnnotationSubtype.REDACT;

  /**
   * Text contents of the redact annotation
   */
  contents?: string;

  /**
   * Quads defining the redaction areas (like markup annotations)
   */
  segmentRects: Rect[];

  /**
   * Interior color (IC) - the fill color used to paint the redacted area after redaction is applied
   */
  color?: string;

  /**
   * Overlay text color - the color of the overlay text displayed on the redacted area
   */
  overlayColor?: string;

  /**
   * Stroke/border color of the redaction box
   */
  strokeColor?: string;

  /**
   * Opacity of the redact annotation
   */
  opacity?: number;

  /**
   * Text displayed on the redacted area after applying the redaction
   */
  overlayText?: string;

  /**
   * Whether the overlay text repeats to fill the redaction area
   */
  overlayTextRepeat?: boolean;

  /**
   * Font family for the overlay text
   */
  fontFamily?: PdfStandardFont;

  /**
   * Font size for the overlay text
   */
  fontSize?: number;

  /**
   * Font color for the overlay text
   */
  fontColor?: string;

  /**
   * Text alignment for the overlay text
   */
  textAlign?: PdfTextAlignment;
}

/**
 * All annotation that support
 *
 * @public
 */
export type PdfSupportedAnnoObject =
  | PdfInkAnnoObject
  | PdfTextAnnoObject
  | PdfLinkAnnoObject
  | PdfPolygonAnnoObject
  | PdfPolylineAnnoObject
  | PdfHighlightAnnoObject
  | PdfLineAnnoObject
  | PdfWidgetAnnoObject
  | PdfFileAttachmentAnnoObject
  | PdfStampAnnoObject
  | PdfSquareAnnoObject
  | PdfCircleAnnoObject
  | PdfSquigglyAnnoObject
  | PdfUnderlineAnnoObject
  | PdfStrikeOutAnnoObject
  | PdfCaretAnnoObject
  | PdfFreeTextAnnoObject
  | PdfRedactAnnoObject;

/**
 * Pdf annotation that does not support
 *
 * @public
 */
export interface PdfUnsupportedAnnoObject extends PdfAnnotationObjectBase {
  type: Exclude<PdfAnnotationSubtype, PdfSupportedAnnoObject['type']>;
}

/**
 * all annotations
 *
 * @public
 */
export type PdfAnnotationObject = PdfSupportedAnnoObject | PdfUnsupportedAnnoObject;

/**
 * Extracts the concrete annotation object type for a specific subtype.
 *
 * @public
 */
export type PdfAnnotationOf<S extends PdfAnnotationSubtype> = Extract<
  PdfAnnotationObject,
  { type: S }
>;

/**
 * Pdf attachment
 *
 * @public
 */
export interface PdfAttachmentObject {
  index: number;
  name: string;
  description: string;
  mimeType: string;
  size?: number;
  creationDate?: Date;
  checksum: string;
}

/**
 * Font charset constants from PDFium (fpdf_sysfontinfo.h)
 * Used for font fallback system when PDFs require fonts not embedded in the document.
 *
 * @public
 */
export enum FontCharset {
  /** ANSI charset (Western European) */
  ANSI = 0,
  /** Default charset */
  DEFAULT = 1,
  /** Symbol charset */
  SYMBOL = 2,
  /** Japanese (Shift-JIS) */
  SHIFTJIS = 128,
  /** Korean (Hangeul) */
  HANGEUL = 129,
  /** Simplified Chinese (GB2312) */
  GB2312 = 134,
  /** Traditional Chinese (Big5) */
  CHINESEBIG5 = 136,
  /** Greek */
  GREEK = 161,
  /** Vietnamese */
  VIETNAMESE = 163,
  /** Hebrew */
  HEBREW = 177,
  /** Arabic */
  ARABIC = 178,
  /** Cyrillic (Russian, etc.) */
  CYRILLIC = 204,
  /** Thai */
  THAI = 222,
  /** Eastern European */
  EASTERNEUROPEAN = 238,
}

/**
 * Pdf engine features
 *
 * @public
 */
export enum PdfEngineFeature {
  RenderPage,
  RenderPageRect,
  Thumbnails,
  Bookmarks,
  Annotations,
}

/**
 * All operations for this engine
 *
 * @public
 */
export enum PdfEngineOperation {
  Create,
  Read,
  Update,
  Delete,
}

/**
 * flags to match the text during searching
 *
 * @public
 */
export enum MatchFlag {
  None = 0,
  MatchCase = 1,
  MatchWholeWord = 2,
  MatchConsecutive = 4,
}

/**
 * Union all the flags
 * @param flags - all the flags
 * @returns union of flags
 *
 * @public
 */
export function unionFlags(flags: MatchFlag[]) {
  return flags.reduce((flag, currFlag) => {
    return flag | currFlag;
  }, MatchFlag.None);
}

/**
 * Image conversion types
 *
 * @public
 */
export type ImageConversionTypes = 'image/webp' | 'image/png' | 'image/jpeg' | 'image/bmp';

/**
 * Targe for searching
 *
 * @public
 */
export interface SearchTarget {
  keyword: string;
  flags: MatchFlag[];
}

/**
 * compare 2 search target
 * @param targetA - first target for search
 * @param targetB - second target for search
 * @returns whether 2 search target are the same
 *
 * @public
 */
export function compareSearchTarget(targetA: SearchTarget, targetB: SearchTarget) {
  const flagA = unionFlags(targetA.flags);
  const flagB = unionFlags(targetB.flags);

  return flagA === flagB && targetA.keyword === targetB.keyword;
}

/** Context of one hit */
export interface TextContext {
  /** Complete words that come *before* the hit (no ellipsis)            */
  before: string;
  /** Exactly the text that matched (case-preserved)                      */
  match: string;
  /** Complete words that come *after* the hit (no ellipsis)             */
  after: string;
  /** `true` ⇢ there were more words on the left that we cut off         */
  truncatedLeft: boolean;
  /** `true` ⇢ there were more words on the right that we cut off        */
  truncatedRight: boolean;
}

/**
 * Text slice
 *
 * @public
 */
export interface PageTextSlice {
  /**
   * Index of the pdf page
   */
  pageIndex: number;
  /**
   * Index of the first character
   */
  charIndex: number;
  /**
   * Count of the characters
   */
  charCount: number;
}

/**
 * search result
 *
 * @public
 */
export interface SearchResult {
  /**
   * Index of the pdf page
   */
  pageIndex: number;
  /**
   * index of the first character
   */
  charIndex: number;
  /**
   * count of the characters
   */
  charCount: number;
  /**
   * highlight rects
   */
  rects: Rect[];
  /**
   * context of the hit
   */
  context: TextContext;
}

/**
 * Results of searching through the entire document
 */
export interface SearchAllPagesResult {
  /**
   * Array of all search results across all pages
   */
  results: SearchResult[];

  /**
   * Total number of results found
   */
  total: number;
}

/**
 * Glyph object
 *
 * @public
 */
export interface PdfGlyphObject {
  /**
   * Origin of the glyph (loose bounds from FPDFText_GetLooseCharBox)
   */
  origin: { x: number; y: number };
  /**
   * Size of the glyph (loose bounds from FPDFText_GetLooseCharBox)
   */
  size: { width: number; height: number };
  /**
   * Tight bounds origin (from FPDFText_GetCharBox, closely surrounds the actual glyph shape).
   * Used for hit-testing to match Chrome's FPDFText_GetCharIndexAtPos behaviour.
   */
  tightOrigin?: { x: number; y: number };
  /**
   * Tight bounds size (from FPDFText_GetCharBox)
   */
  tightSize?: { width: number; height: number };
  /**
   * Whether the glyph is a space
   */
  isSpace?: boolean;
  /**
   * Whether the glyph is a empty
   */
  isEmpty?: boolean;
}

/**
 * Glyph object
 *
 * @public
 */
export interface PdfGlyphSlim {
  /**
   * X coordinate of the glyph (loose bounds from FPDFText_GetLooseCharBox)
   */
  x: number;
  /**
   * Y coordinate of the glyph (loose bounds from FPDFText_GetLooseCharBox)
   */
  y: number;
  /**
   * Width of the glyph (loose bounds from FPDFText_GetLooseCharBox)
   */
  width: number;
  /**
   * Height of the glyph (loose bounds from FPDFText_GetLooseCharBox)
   */
  height: number;
  /**
   * Flags of the glyph
   */
  flags: number;
  /**
   * Tight X coordinate (from FPDFText_GetCharBox).
   * Used for hit-testing to match Chrome's FPDFText_GetCharIndexAtPos behaviour.
   */
  tightX?: number;
  /**
   * Tight Y coordinate (from FPDFText_GetCharBox)
   */
  tightY?: number;
  /**
   * Tight width (from FPDFText_GetCharBox)
   */
  tightWidth?: number;
  /**
   * Tight height (from FPDFText_GetCharBox)
   */
  tightHeight?: number;
}

/**
 * Run object
 *
 * @public
 */
export interface PdfRun {
  /**
   * Rectangle of the run
   */
  rect: { x: number; y: number; width: number; height: number };
  /**
   * Start index of the run
   */
  charStart: number;
  /**
   * Glyphs of the run
   */
  glyphs: PdfGlyphSlim[];
  /**
   * Font size of the run (all glyphs in a run share the same font size)
   */
  fontSize?: number;
}

/**
 * Page geometry
 *
 * @public
 */
export interface PdfPageGeometry {
  /**
   * Runs of the page
   */
  runs: PdfRun[];
}

/**
 * Font information extracted from a PDF text object.
 *
 * @public
 */
export interface PdfFontInfo {
  /** PostScript name (e.g. "HOEPNL+Arial,Bold"). */
  name: string;
  /** Font family name (e.g. "Arial"). */
  familyName: string;
  /** Weight 100-900 (400 = normal, 700 = bold). */
  weight: number;
  /** Whether the font is italic. */
  italic: boolean;
  /** Whether the font is monospaced (fixed-pitch). */
  monospaced: boolean;
  /** Whether the font data is embedded in the PDF. */
  embedded: boolean;
}

/**
 * A rich text run: consecutive characters sharing the same text object,
 * font, size, and color.
 *
 * @public
 */
export interface PdfTextRun {
  /** The text content (UTF-8). */
  text: string;
  /** Bounding box in PDF page coordinates (points). */
  rect: Rect;
  /** Font metadata (uniform within the run). */
  font: PdfFontInfo;
  /** Font size in points. */
  fontSize: number;
  /** Fill color (RGBA). */
  color: PdfAlphaColor;
  /** Start character index in the text page. */
  charIndex: number;
  /** Number of characters in this run. */
  charCount: number;
}

/**
 * Rich text runs for a single page.
 *
 * @public
 */
export interface PdfPageTextRuns {
  /** Text runs ordered by reading order. */
  runs: PdfTextRun[];
}

/**
 * form field value
 * @public
 */
export type FormFieldValue =
  | { kind: 'text'; text: string }
  | { kind: 'selection'; index: number; isSelected: boolean }
  | { kind: 'checked'; checked: boolean };

/**
 * Transformation that will be applied to annotation
 *
 * @public
 */
export interface PdfAnnotationTransformation {
  /**
   * Translated offset
   */
  offset: Position;
  /**
   * Scaled factors
   */
  scale: Size;
}

/**
 * source can be byte array contains pdf content
 *
 * @public
 */
export type PdfFileContent = ArrayBuffer;

/**
 * PDF permission flags per ISO 32000-1 Table 22
 * These are the flags to pass to setDocumentEncryption indicating what actions ARE ALLOWED.
 * Use buildPermissions() helper to combine flags.
 *
 * @public
 */
export enum PdfPermissionFlag {
  /** Bit 3: Print (possibly degraded quality) */
  Print = 1 << 2,
  /** Bit 4: Modify document contents */
  ModifyContents = 1 << 3,
  /** Bit 5: Copy/extract text and graphics */
  CopyContents = 1 << 4,
  /** Bit 6: Add/modify annotations, fill forms */
  ModifyAnnotations = 1 << 5,
  /** Bit 9: Fill in existing form fields */
  FillForms = 1 << 8,
  /** Bit 10: Extract for accessibility */
  ExtractForAccessibility = 1 << 9,
  /** Bit 11: Assemble document (insert, rotate, delete pages) */
  AssembleDocument = 1 << 10,
  /** Bit 12: High quality print */
  PrintHighQuality = 1 << 11,

  /** Common combination: Allow all permissions */
  AllowAll = Print |
    ModifyContents |
    CopyContents |
    ModifyAnnotations |
    FillForms |
    ExtractForAccessibility |
    AssembleDocument |
    PrintHighQuality,
}

/**
 * Helper function to combine permission flags for setDocumentEncryption.
 * Note: PrintHighQuality automatically includes Print (enforced in C++ layer as well).
 *
 * @param flags - Permission flags to combine
 * @returns Combined permission flags as a number
 *
 * @public
 */
export function buildPermissions(...flags: PdfPermissionFlag[]): number {
  let result = flags.reduce((acc, flag) => acc | flag, 0);
  // Enforce: PrintHighQuality implies Print
  if (result & PdfPermissionFlag.PrintHighQuality) {
    result |= PdfPermissionFlag.Print;
  }
  return result;
}

/**
 * Error thrown when a permission check fails.
 *
 * @public
 */
export class PermissionDeniedError extends Error {
  public readonly name = 'PermissionDeniedError';

  constructor(
    public readonly requiredFlags: PdfPermissionFlag[],
    public readonly currentPermissions: number,
  ) {
    const flagNames = requiredFlags.map((f) => PdfPermissionFlag[f]).join(', ');
    super(`Permission denied. Required: ${flagNames}`);
  }
}

export enum PdfPageFlattenFlag {
  Display = 0,
  Print = 1,
}

export enum PdfPageFlattenResult {
  Fail = 0,
  Success = 1,
  NothingToDo = 2,
}

/**
 * Pdf File without content
 *
 * @public
 */
export interface PdfFileWithoutContent {
  /**
   * id of file
   */
  id: string;
}

export interface PdfFileLoader extends PdfFileWithoutContent {
  /**
   * length of file
   */
  fileLength: number;
  /**
   * read block of file
   * @param offset - offset of file
   * @param length - length of file
   * @returns block of file
   */
  callback: (offset: number, length: number) => Uint8Array;
}

export interface PdfAnnotationsProgress {
  page: number;
  result: PdfAnnotationObject[];
}

/**
 * Progress of search all pages
 *
 * @public
 */
export type PdfPageSearchProgress = { page: number; results: SearchResult[] };

/**
 * Pdf File
 *
 * @public
 */
export interface PdfFile extends PdfFileWithoutContent {
  /**
   * content of file
   */
  content: PdfFileContent;
}

export interface PdfFileUrl extends PdfFileWithoutContent {
  url: string;
}

export enum PdfErrorCode {
  // ═══════════════════════════════════════════════════════
  // PDFium Error Codes (MUST NOT CHANGE ORDER - maps to C defines)
  // ═══════════════════════════════════════════════════════
  Ok = 0, // #define FPDF_ERR_SUCCESS 0
  Unknown = 1, // #define FPDF_ERR_UNKNOWN 1
  NotFound = 2, // #define FPDF_ERR_FILE 2
  WrongFormat = 3, // #define FPDF_ERR_FORMAT 3
  Password = 4, // #define FPDF_ERR_PASSWORD 4 - Password required or incorrect
  Security = 5, // #define FPDF_ERR_SECURITY 5
  PageError = 6, // #define FPDF_ERR_PAGE 6
  XFALoad = 7, // #define FPDF_ERR_XFALOAD 7
  XFALayout = 8, // #define FPDF_ERR_XFALAYOUT 8

  // ═══════════════════════════════════════════════════════
  // Custom Error Codes (Can add/modify freely)
  // ═══════════════════════════════════════════════════════
  Cancelled = 9,
  Initialization = 10,
  NotReady = 11,
  NotSupport = 12,
  LoadDoc = 13,
  DocNotOpen = 14,
  CantCloseDoc = 15,
  CantCreateNewDoc = 16,
  CantImportPages = 17,
  CantCreateAnnot = 18,
  CantSetAnnotRect = 19,
  CantSetAnnotContent = 20,
  CantRemoveInkList = 21,
  CantAddInkStoke = 22,
  CantReadAttachmentSize = 23,
  CantReadAttachmentContent = 24,
  CantFocusAnnot = 25,
  CantSelectText = 26,
  CantSelectOption = 27,
  CantCheckField = 28,
  CantSetAnnotString = 29,
  CantDeletePage = 30,
}

export interface PdfErrorReason {
  code: PdfErrorCode;
  message: string;
}

export type PdfEngineError = TaskError<PdfErrorReason>;

export type PdfTask<R, P = unknown> = Task<R, PdfErrorReason, P>;

export class PdfTaskHelper {
  /**
   * Create a task
   * @returns new task
   */
  static create<R, P = unknown>(): Task<R, PdfErrorReason, P> {
    return new Task<R, PdfErrorReason, P>();
  }

  /**
   * Create a task that has been resolved with value
   * @param result - resolved value
   * @returns resolved task
   */
  static resolve<R, P = unknown>(result: R): Task<R, PdfErrorReason, P> {
    const task = new Task<R, PdfErrorReason, P>();
    task.resolve(result);

    return task;
  }

  /**
   * Create a task that has been rejected with error
   * @param reason - rejected error
   * @returns rejected task
   */
  static reject<T = any, P = unknown>(reason: PdfErrorReason): Task<T, PdfErrorReason, P> {
    const task = new Task<T, PdfErrorReason, P>();
    task.reject(reason);

    return task;
  }

  /**
   * Create a task that has been aborted with error
   * @param reason - aborted error
   * @returns aborted task
   */
  static abort<T = any, P = unknown>(reason: PdfErrorReason): Task<T, PdfErrorReason, P> {
    const task = new Task<T, PdfErrorReason, P>();
    task.reject(reason);

    return task;
  }
}

export interface PdfOpenDocumentBufferOptions {
  /**
   * Password for the document
   */
  password?: string;
  /**
   * When true, normalizes page rotation so all coordinates are in 0° space.
   * The original rotation is preserved in page.rotation for reference.
   * @default false
   */
  normalizeRotation?: boolean;
}

export interface PdfRequestOptions {
  /**
   * Custom HTTP headers to include in all requests (HEAD, GET, range requests)
   * Example: { 'Authorization': 'Bearer token', 'X-Custom-Header': 'value' }
   */
  headers?: Record<string, string>;
  /**
   * Controls whether cookies are sent with requests
   * - 'omit': Never send cookies (default)
   * - 'same-origin': Send cookies for same-origin requests
   * - 'include': Always send cookies (requires CORS)
   */
  credentials?: RequestCredentials;
}

export interface PdfOpenDocumentUrlOptions {
  /**
   * Password for the document
   */
  password?: string;
  /**
   * Loading mode
   */
  mode?: 'auto' | 'range-request' | 'full-fetch';
  /**
   * HTTP request options for fetching the PDF
   */
  requestOptions?: PdfRequestOptions;
  /**
   * When true, normalizes page rotation so all coordinates are in 0° space.
   * The original rotation is preserved in page.rotation for reference.
   * @default false
   */
  normalizeRotation?: boolean;
}

/**
 * Scheduling priority for render operations (higher = more urgent).
 * Used by the orchestrator engine's task queue.
 */
export enum RenderPriority {
  LOW = 0,
  MEDIUM = 1,
  HIGH = 2,
  CRITICAL = 3,
}

export interface PdfRenderOptions {
  /**
   * Scale factor
   */
  scaleFactor?: number;
  /**
   * Rotation
   */
  rotation?: Rotation;
  /**
   * Device pixel ratio
   */
  dpr?: number;
  /**
   * Image type
   */
  imageType?: ImageConversionTypes;
  /**
   * Image quality (0-1) for jpeg and png
   */
  imageQuality?: number;
  /**
   * Scheduling priority.
   */
  priority?: RenderPriority;
}

export interface ConvertToBlobOptions {
  /**
   * Image type
   */
  type: ImageConversionTypes;
  /**
   * Image quality (0-1) for webp and jpeg and png
   */
  quality?: number;
}

export interface PdfRenderPageOptions extends PdfRenderOptions {
  /**
   * Whether to render annotations
   */
  withAnnotations?: boolean;
  /**
   * Whether to render interactive form widgets
   */
  withForms?: boolean;
  /**
   * When true, the background is transparent instead of white.
   * Useful for rendering stamp thumbnails or overlay content.
   */
  transparentBackground?: boolean;
}

export interface PdfRenderPageAnnotationOptions extends PdfRenderOptions {
  /**
   * Appearance mode normal down or rollover
   */
  mode?: AppearanceMode;
  /**
   * When true and annotation.unrotatedRect is present, render using the
   * unrotated path (ignores AP Matrix rotation). Falls back to normal
   * rendering if unrotatedRect is not available on the annotation.
   */
  unrotated?: boolean;
}

export interface PdfRenderThumbnailOptions extends PdfRenderOptions {
  /**
   * Whether to render annotations
   */
  withAnnotations?: boolean;
}

export interface PdfSearchAllPagesOptions {
  /**
   * Search flags
   */
  flags?: MatchFlag[];
}

export interface PdfRedactTextOptions {
  /**
   * Whether to recurse forms
   */
  recurseForms?: boolean;
  /**
   * Whether to draw black boxes
   */
  drawBlackBoxes?: boolean;
}

export interface PdfFlattenPageOptions {
  /**
   * Flatten flag
   */
  flag?: PdfPageFlattenFlag;
}

/**
 * Options for preparing a PDF document for printing
 */
export interface PdfPrintOptions {
  /**
   * Whether to include annotations in the printed document
   * @default true
   */
  includeAnnotations?: boolean;

  /**
   * Page range string defining which pages to include
   * Examples: "1,3,5-7" or "1-10,15,20-25"
   * If not specified, all pages are included
   * @default null (all pages)
   */
  pageRange?: string;
}

/**
 * Parameters for adding an attachment to a PDF document
 */
export interface PdfAddAttachmentParams {
  /**
   * Name of the attachment
   */
  name: string;
  /**
   * Description of the attachment
   */
  description: string;
  /**
   * MIME type of the attachment
   */
  mimeType: string;
  /**
   * Data of the attachment
   */
  data: ArrayBuffer | Uint8Array;
}

/**
 * Pdf engine
 *
 * @public
 */
export interface PdfEngine<T = Blob> {
  /**
   * Check whether pdf engine supports this feature
   * @param feature - which feature want to check
   * @returns support or not
   */
  isSupport?: (feature: PdfEngineFeature) => PdfTask<PdfEngineOperation[]>;
  /**
   * Destroy the engine
   * @returns task that indicate whether destroy is successful
   */
  destroy?: () => PdfTask<boolean>;
  /**
   * Open a PDF from a URL with specified mode
   * @param url - The PDF file URL
   * @param options - Additional options including mode (auto, range-request, full-fetch) and password
   * @returns Task that resolves with the PdfDocumentObject or an error
   */
  openDocumentUrl: (
    file: PdfFileUrl,
    options?: PdfOpenDocumentUrlOptions,
  ) => PdfTask<PdfDocumentObject>;
  /**
   * Open pdf document from buffer
   * @param file - pdf file
   * @param options - Additional options including password
   * @returns task that contains the file or error
   */
  openDocumentBuffer: (
    file: PdfFile,
    options?: PdfOpenDocumentBufferOptions,
  ) => PdfTask<PdfDocumentObject>;
  /**
   * Get the metadata of the file
   * @param doc - pdf document
   * @returns task that contains the metadata or error
   */
  getMetadata: (doc: PdfDocumentObject) => PdfTask<PdfMetadataObject>;
  /**
   * Set the metadata of the file
   * @param doc - pdf document
   * @param metadata - metadata to set
   * @returns task that contains the metadata or error
   */
  setMetadata: (doc: PdfDocumentObject, metadata: Partial<PdfMetadataObject>) => PdfTask<boolean>;
  /**
   * Get permissions of the file
   * @param doc - pdf document
   * @returns task that contains a 32-bit integer indicating permission flags
   */
  getDocPermissions: (doc: PdfDocumentObject) => PdfTask<number>;
  /**
   * Get the user permissions of the file
   * @param doc - pdf document
   * @returns task that contains a 32-bit integer indicating permission flags
   */
  getDocUserPermissions: (doc: PdfDocumentObject) => PdfTask<number>;
  /**
   * Get the signatures of the file
   * @param doc - pdf document
   * @returns task that contains the signatures or error
   */
  getSignatures: (doc: PdfDocumentObject) => PdfTask<PdfSignatureObject[]>;
  /**
   * Get the bookmarks of the file
   * @param doc - pdf document
   * @returns task that contains the bookmarks or error
   */
  getBookmarks: (doc: PdfDocumentObject) => PdfTask<PdfBookmarksObject>;
  /**
   * Set the bookmarks of the file
   * @param doc - pdf document
   * @param payload - bookmarks to set
   * @returns task that contains whether the bookmarks are set successfully or not
   */
  setBookmarks: (doc: PdfDocumentObject, payload: PdfBookmarkObject[]) => PdfTask<boolean>;
  /**
   * Remove all bookmarks from the document.
   * @param doc - pdf document
   * @returns task that contains whether the bookmarks are removed successfully or not
   */
  deleteBookmarks: (doc: PdfDocumentObject) => PdfTask<boolean>;
  /**
   * Render the specified pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @param options - render options
   * @returns task contains the rendered image or error
   */
  renderPage: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderPageOptions,
  ) => PdfTask<T>;
  /**
   * Render the specified rect of pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @param rect - target rect
   * @param options - render options
   * @returns task contains the rendered image or error
   */
  renderPageRect: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    rect: Rect,
    options?: PdfRenderPageOptions,
  ) => PdfTask<T>;
  /**
   * Render the specified pdf page and return raw pixel data (ImageDataLike)
   * without encoding to the output format T. Useful for AI/ML pipelines
   * that need direct pixel access.
   * @param doc - pdf document
   * @param page - pdf page
   * @param options - render options (imageType/imageQuality are ignored)
   * @returns task contains raw ImageDataLike or error
   */
  renderPageRaw: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderPageOptions,
  ) => PdfTask<ImageDataLike>;
  /**
   * Render the specified rect of a pdf page and return raw pixel data
   * (ImageDataLike) without encoding to the output format T.
   * @param doc - pdf document
   * @param page - pdf page
   * @param rect - target rect in PDF coordinate space
   * @param options - render options (imageType/imageQuality are ignored)
   * @returns task contains raw ImageDataLike or error
   */
  renderPageRectRaw: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    rect: Rect,
    options?: PdfRenderPageOptions,
  ) => PdfTask<ImageDataLike>;
  /**
   * Render the thumbnail of specified pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @param options - render options
   * @returns task contains the rendered image or error
   */
  renderThumbnail: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderThumbnailOptions,
  ) => PdfTask<T>;
  /**
   * Render a single annotation into an ImageData blob.
   *
   * Note:  • honours Display-Matrix, page rotation & DPR
   *        • you decide whether to include the page background
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - the annotation to render
   * @param options - render options
   */
  renderPageAnnotation(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
    options?: PdfRenderPageAnnotationOptions,
  ): PdfTask<T>;
  /**
   * Batch-render all annotation appearance streams for a page and encode
   * each rendered image to the output type of this engine.
   * Returns a map of annotation ID to rendered appearances (Normal/Rollover/Down).
   * @param doc - pdf document
   * @param page - pdf page
   * @param options - render options
   */
  renderPageAnnotations(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderPageAnnotationOptions,
  ): PdfTask<AnnotationAppearanceMap<T>>;
  /**
   * Batch-render all annotation appearance streams for a page.
   * Returns a map of annotation ID to rendered appearances (Normal/Rollover/Down).
   * Skips EmbedPDF-rotated annotations and annotations without appearance streams.
   * @param doc - pdf document
   * @param page - pdf page
   * @param options - render options (scaleFactor, dpr, rotation)
   */
  renderPageAnnotationsRaw(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderPageAnnotationOptions,
  ): PdfTask<AnnotationAppearanceMap<ImageDataLike>>;
  /**
   * Get annotations of pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @returns task contains the annotations or error
   */
  getPageAnnotations: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
  ) => PdfTask<PdfAnnotationObject[]>;
  /**
   * Extract named document JavaScript actions without executing them.
   * @param doc - pdf document
   * @returns task that contains all named document JavaScript actions
   */
  getDocumentJavaScriptActions: (
    doc: PdfDocumentObject,
  ) => PdfTask<PdfDocumentJavaScriptActionObject[]>;
  /**
   * Get form fields of pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @returns task contains the form fields or error
   */
  getPageAnnoWidgets: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
  ) => PdfTask<PdfWidgetAnnoObject[]>;
  /**
   * Extract widget additional JavaScript actions for a page without executing them.
   * @param doc - pdf document
   * @param page - pdf page
   * @returns task containing page widget JavaScript actions
   */
  getPageWidgetJavaScriptActions: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
  ) => PdfTask<PdfWidgetJavaScriptActionObject[]>;
  /**
   * Regenerate appearance streams for specific widget annotations on a page.
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotationIds - NM values of the annotations to regenerate
   * @returns task indicating whether any appearances were regenerated
   */
  regenerateWidgetAppearances: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotationIds: string[],
  ) => PdfTask<boolean>;
  /**
   * Create a annotation on specified page
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - new annotations
   * @param context - context of the annotation
   * @returns task whether the annotations is created successfully
   */
  createPageAnnotation: <A extends PdfAnnotationObject>(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: A,
    context?: AnnotationCreateContext<A>,
  ) => PdfTask<string>;
  /**
   * Update a annotation on specified page
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - new annotations
   * @returns task that indicates whether the operation succeeded
   */
  updatePageAnnotation: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
    options?: { regenerateAppearance?: boolean },
  ) => PdfTask<boolean>;
  /**
   * Remove a annotation on specified page
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - new annotations
   * @returns task whether the annotations is removed successfully
   */
  removePageAnnotation: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ) => PdfTask<boolean>;
  /**
   * get all text rects in pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @param options - get page text rects options
   * @returns task contains the text rects or error
   */
  getPageTextRects: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfTextRectObject[]>;
  /**
   * Search across all pages in the document
   * @param doc - pdf document
   * @param keyword - search keyword
   * @param options - search all pages options
   * @returns Task contains all search results throughout the document
   */
  searchAllPages: (
    doc: PdfDocumentObject,
    keyword: string,
    options?: PdfSearchAllPagesOptions,
  ) => PdfTask<SearchAllPagesResult, PdfPageSearchProgress>;
  /**
   * Get all annotations in this file
   * @param doc - pdf document
   * @returns task that contains the annotations or error
   */
  getAllAnnotations: (
    doc: PdfDocumentObject,
  ) => PdfTask<Record<number, PdfAnnotationObject[]>, PdfAnnotationsProgress>;
  /**
   * Get all attachments in this file
   * @param doc - pdf document
   * @returns task that contains the attachments or error
   */
  getAttachments: (doc: PdfDocumentObject) => PdfTask<PdfAttachmentObject[]>;
  /**
   * Add a attachment to the file
  /**
   * @param doc - pdf document
   * @param attachment - pdf attachment
   * @returns task that contains the attachment or error
   */
  addAttachment: (doc: PdfDocumentObject, params: PdfAddAttachmentParams) => PdfTask<boolean>;
  /**
   * Remove a attachment from the file
  /**
   * @param doc - pdf document
   * @param attachment - pdf attachment
   * @returns task that contains the attachment or error
   */
  removeAttachment: (doc: PdfDocumentObject, attachment: PdfAttachmentObject) => PdfTask<boolean>;
  /**
   * Read content of pdf attachment
   * @param doc - pdf document
   * @param attachment - pdf attachments
   * @returns task that contains the content of specified attachment or error
   */
  readAttachmentContent: (
    doc: PdfDocumentObject,
    attachment: PdfAttachmentObject,
  ) => PdfTask<ArrayBuffer>;
  /**
   * Set form field value
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - pdf annotation
   * @param text - text value
   */
  setFormFieldValue: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfWidgetAnnoObject,
    value: FormFieldValue,
  ) => PdfTask<boolean>;
  /**
   * Restore a widget annotation to the full field state described by `field`.
   * Unlike `setFormFieldValue`, this accepts a complete `PdfWidgetAnnoField`
   * snapshot and applies all writable state in a single call.
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - pdf widget annotation
   * @param field - the desired field state to apply
   */
  setFormFieldState: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfWidgetAnnoObject,
    field: PdfWidgetAnnoField,
  ) => PdfTask<boolean>;
  /**
   * Rename the logical form field associated with a widget annotation.
   * This updates the field dictionary rather than patching only a single widget snapshot.
   * @param doc - pdf document
   * @param page - pdf page containing the widget annotation
   * @param annotation - pdf widget annotation
   * @param name - the desired partial field name (/T)
   */
  renameWidgetField: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfWidgetAnnoObject,
    name: string,
  ) => PdfTask<boolean>;
  /**
   * Attach the source widget's logical field to the target widget's logical field.
   * This is a structural field operation and may merge multiple widget kids under one parent.
   * @param doc - pdf document
   * @param sourcePage - page containing the source widget annotation
   * @param sourceAnnotation - widget whose field should be shared into the target field
   * @param targetPage - page containing the target widget annotation
   * @param targetAnnotation - widget whose logical field should be reused
   */
  shareWidgetField: (
    doc: PdfDocumentObject,
    sourcePage: PdfPageObject,
    sourceAnnotation: PdfWidgetAnnoObject,
    targetPage: PdfPageObject,
    targetAnnotation: PdfWidgetAnnoObject,
  ) => PdfTask<boolean>;
  /**
   * Flatten annotations and form fields into the page contents.
   * @param doc - pdf document
   * @param page - pdf page
   * @param options - flatten page options
   */
  flattenPage: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfFlattenPageOptions,
  ) => PdfTask<PdfPageFlattenResult>;
  /**
   * Extract pdf pages to a new file
   * @param doc - pdf document
   * @param pageIndexes - indexes of pdf pages
   * @returns task contains the new pdf file content
   */
  extractPages: (doc: PdfDocumentObject, pageIndexes: number[]) => PdfTask<ArrayBuffer>;
  /**
   * Create a new empty PDF document
   * @param id - unique document identifier
   * @returns task contains the empty document object
   */
  createDocument: (id: string) => PdfTask<PdfDocumentObject>;
  /**
   * Import pages from a source document into a destination document
   * @param destDoc - destination document
   * @param srcDoc - source document
   * @param srcPageIndices - zero-based page indices in the source document
   * @param insertIndex - position to insert at (defaults to end)
   * @returns task contains the newly added page objects
   */
  importPages: (
    destDoc: PdfDocumentObject,
    srcDoc: PdfDocumentObject,
    srcPageIndices: number[],
    insertIndex?: number,
  ) => PdfTask<PdfPageObject[]>;
  /**
   * Delete a page from a document
   * @param doc - pdf document
   * @param pageIndex - zero-based index of the page to delete
   * @returns task contains the result
   */
  deletePage: (doc: PdfDocumentObject, pageIndex: number) => PdfTask<boolean>;
  /**
   * Extract text on specified pdf pages
   * @param doc - pdf document
   * @param pageIndexes - indexes of pdf pages
   * @returns task contains the text
   */
  extractText: (doc: PdfDocumentObject, pageIndexes: number[]) => PdfTask<string>;
  /**
   * Redact text by run slices
   * @param doc - pdf document
   * @param page - pdf page
   * @param rects - rects to redact
   * @param options - redact text options
   * @returns task contains the result
   */
  redactTextInRects: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    rects: Rect[],
    options?: PdfRedactTextOptions,
  ) => PdfTask<boolean>;
  /**
   * Apply a single REDACT annotation - removes content, flattens RO overlay, deletes annotation.
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - the REDACT annotation to apply
   * @returns task contains the result
   */
  applyRedaction: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ) => PdfTask<boolean>;
  /**
   * Apply all REDACT annotations on a page - removes content, flattens overlays, deletes annotations.
   * @param doc - pdf document
   * @param page - pdf page
   * @returns task contains the result
   */
  applyAllRedactions: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<boolean>;
  /**
   * Flatten an annotation's appearance (AP/N) to page content and remove the annotation.
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - the annotation to flatten
   * @returns task contains the result
   */
  flattenAnnotation: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ) => PdfTask<boolean>;
  /**
   * Export an annotation's appearance as a standalone PDF document
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotation - the annotation to export
   * @returns task contains the exported PDF as ArrayBuffer
   */
  exportAnnotationAppearanceAsPdf: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ) => PdfTask<ArrayBuffer>;
  /**
   * Export multiple annotations' appearances as a standalone single-page PDF
   * @param doc - pdf document
   * @param page - pdf page
   * @param annotations - the annotations to export
   * @returns task contains the exported PDF as ArrayBuffer
   */
  exportAnnotationsAppearanceAsPdf: (
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotations: PdfAnnotationObject[],
  ) => PdfTask<ArrayBuffer>;
  /**
   * Extract text on specified pdf pages
   * @param doc - pdf document
   * @param pageIndexes - indexes of pdf pages
   * @returns task contains the text
   */
  getTextSlices: (doc: PdfDocumentObject, slices: PageTextSlice[]) => PdfTask<string[]>;
  /**
   * Get all glyphs in the specified pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @returns task contains the glyphs
   */
  getPageGlyphs: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfGlyphObject[]>;
  /**
   * Get the geometry of the specified pdf page
   * @param doc - pdf document
   * @param page - pdf page
   * @returns task contains the geometry
   */
  getPageGeometry: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfPageGeometry>;
  /**
   * Get rich text runs for a page, grouped by text object with font and color info
   * @param doc - pdf document
   * @param page - pdf page
   * @returns task contains the text runs
   */
  getPageTextRuns: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfPageTextRuns>;
  /**
   * Merge multiple pdf documents
   * @param files - all the pdf files
   * @returns task contains the merged pdf file
   */
  merge: (files: PdfFile[]) => PdfTask<PdfFile>;
  /**
   * Merge specific pages from multiple PDF documents in a custom order
   * @param mergeConfigs Array of configurations specifying which pages to merge from which documents
   * @returns A PdfTask that resolves with the merged PDF file
   * @public
   */
  mergePages: (mergeConfigs: Array<{ docId: string; pageIndices: number[] }>) => PdfTask<PdfFile>;
  /**
   * Prepare a PDF document for printing
   * @param doc - pdf document
   * @param options - options for preparing the document for printing
   * @returns task contains the prepared pdf file content
   */
  preparePrintDocument: (doc: PdfDocumentObject, options?: PdfPrintOptions) => PdfTask<ArrayBuffer>;
  /**
   * Save a copy of pdf document
   * @param doc - pdf document
   * @returns task contains the new pdf file content
   */
  saveAsCopy: (doc: PdfDocumentObject) => PdfTask<ArrayBuffer>;
  /**
   * Close pdf document
   * @param doc - pdf document
   * @returns task that file is closed or not
   */
  closeDocument: (doc: PdfDocumentObject) => PdfTask<boolean>;
  /**
   * Close all documents
   * @returns task that all documents are closed or not
   */
  closeAllDocuments: () => PdfTask<boolean>;
  /**
   * Sets AES-256 encryption on a document.
   * Must be called before saveAsCopy() for encryption to take effect.
   * @param doc - pdf document
   * @param userPassword - Password to open document (empty = no open password)
   * @param ownerPassword - Password to change permissions (required)
   * @param allowedFlags - OR'd PdfPermissionFlag values indicating allowed actions
   * @returns task indicating success or failure
   */
  setDocumentEncryption: (
    doc: PdfDocumentObject,
    userPassword: string,
    ownerPassword: string,
    allowedFlags: number,
  ) => PdfTask<boolean>;
  /**
   * Marks document for encryption removal on save.
   * Call this to remove password protection when saving.
   * @param doc - pdf document
   * @returns task indicating success
   */
  removeEncryption: (doc: PdfDocumentObject) => PdfTask<boolean>;
  /**
   * Attempt to unlock owner permissions on an encrypted document.
   * Call this after opening a document with user-level access to gain full permissions.
   * @param doc - pdf document
   * @param ownerPassword - the owner password
   * @returns task that indicates whether unlock succeeded
   */
  unlockOwnerPermissions: (doc: PdfDocumentObject, ownerPassword: string) => PdfTask<boolean>;
  /**
   * Check if a document is encrypted.
   * @param doc - pdf document
   * @returns task that resolves to true if the document is encrypted
   */
  isEncrypted: (doc: PdfDocumentObject) => PdfTask<boolean>;
  /**
   * Check if owner permissions are currently unlocked.
   * @param doc - pdf document
   * @returns task that resolves to true if owner permissions are unlocked
   */
  isOwnerUnlocked: (doc: PdfDocumentObject) => PdfTask<boolean>;
}

/**
 * Method name of PdfEngine interface
 *
 * @public
 */
export type PdfEngineMethodName = keyof Required<PdfEngine>;

/**
 * Progress info for batch operations
 * Emitted per-page as the batch is processed
 *
 * @public
 */
export interface BatchProgress<T> {
  /** Index of the page that was just processed */
  pageIndex: number;
  /** Result for this page */
  result: T;
  /** Number of pages completed so far */
  completed: number;
  /** Total number of pages in this batch */
  total: number;
}

/**
 * Executor interface for PDFium implementations.
 * Can be either PdfiumNative (direct) or RemoteExecutor (worker proxy).
 *
 * @public
 */
export interface IPdfiumExecutor {
  // Core operations
  destroy(): void;
  openDocumentBuffer(
    file: PdfFile,
    options?: PdfOpenDocumentBufferOptions,
  ): PdfTask<PdfDocumentObject>;
  getMetadata(doc: PdfDocumentObject): PdfTask<PdfMetadataObject>;
  setMetadata(doc: PdfDocumentObject, metadata: Partial<PdfMetadataObject>): PdfTask<boolean>;
  getDocPermissions(doc: PdfDocumentObject): PdfTask<number>;
  getDocUserPermissions(doc: PdfDocumentObject): PdfTask<number>;
  getSignatures(doc: PdfDocumentObject): PdfTask<PdfSignatureObject[]>;
  getBookmarks(doc: PdfDocumentObject): PdfTask<PdfBookmarksObject>;
  setBookmarks(doc: PdfDocumentObject, bookmarks: PdfBookmarkObject[]): PdfTask<boolean>;
  deleteBookmarks(doc: PdfDocumentObject): PdfTask<boolean>;

  // Raw rendering (returns ImageDataLike, not Blob)
  renderPageRaw(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderPageOptions,
  ): PdfTask<ImageDataLike>;
  renderPageRect(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    rect: Rect,
    options?: PdfRenderPageOptions,
  ): PdfTask<ImageDataLike>;
  renderThumbnailRaw(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderThumbnailOptions,
  ): PdfTask<ImageDataLike>;
  renderPageAnnotationRaw(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
    options?: PdfRenderPageAnnotationOptions,
  ): PdfTask<ImageDataLike>;
  renderPageAnnotationsRaw(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfRenderPageAnnotationOptions,
  ): PdfTask<AnnotationAppearanceMap<ImageDataLike>>;

  // Single page operations
  getPageAnnotationsRaw(
    doc: PdfDocumentObject,
    page: PdfPageObject,
  ): PdfTask<PdfAnnotationObject[]>;
  getPageAnnotations(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfAnnotationObject[]>;
  createPageAnnotation<A extends PdfAnnotationObject>(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: A,
    context?: AnnotationCreateContext<A>,
  ): PdfTask<string>;
  updatePageAnnotation(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
    options?: { regenerateAppearance?: boolean },
  ): PdfTask<boolean>;
  removePageAnnotation(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ): PdfTask<boolean>;
  getPageTextRects(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfTextRectObject[]>;

  // Single page search
  searchInPage(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    keyword: string,
    flags: number,
  ): PdfTask<SearchResult[]>;

  // Batch operations (process multiple pages in one call for performance)
  getAnnotationsBatch(
    doc: PdfDocumentObject,
    pages: PdfPageObject[],
  ): PdfTask<Record<number, PdfAnnotationObject[]>, BatchProgress<PdfAnnotationObject[]>>;

  searchBatch(
    doc: PdfDocumentObject,
    pages: PdfPageObject[],
    keyword: string,
    flags: number,
  ): PdfTask<Record<number, SearchResult[]>, BatchProgress<SearchResult[]>>;

  // Other operations
  getAttachments(doc: PdfDocumentObject): PdfTask<PdfAttachmentObject[]>;
  addAttachment(doc: PdfDocumentObject, params: PdfAddAttachmentParams): PdfTask<boolean>;
  removeAttachment(doc: PdfDocumentObject, attachment: PdfAttachmentObject): PdfTask<boolean>;
  readAttachmentContent(
    doc: PdfDocumentObject,
    attachment: PdfAttachmentObject,
  ): PdfTask<ArrayBuffer>;
  getDocumentJavaScriptActions(
    doc: PdfDocumentObject,
  ): PdfTask<PdfDocumentJavaScriptActionObject[]>;
  getPageAnnoWidgets(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfWidgetAnnoObject[]>;
  getPageWidgetJavaScriptActions(
    doc: PdfDocumentObject,
    page: PdfPageObject,
  ): PdfTask<PdfWidgetJavaScriptActionObject[]>;
  regenerateWidgetAppearances(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotationIds: string[],
  ): PdfTask<boolean>;
  setFormFieldValue(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfWidgetAnnoObject,
    value: FormFieldValue,
  ): PdfTask<boolean>;
  setFormFieldState(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfWidgetAnnoObject,
    field: PdfWidgetAnnoField,
  ): PdfTask<boolean>;
  renameWidgetField(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfWidgetAnnoObject,
    name: string,
  ): PdfTask<boolean>;
  shareWidgetField(
    doc: PdfDocumentObject,
    sourcePage: PdfPageObject,
    sourceAnnotation: PdfWidgetAnnoObject,
    targetPage: PdfPageObject,
    targetAnnotation: PdfWidgetAnnoObject,
  ): PdfTask<boolean>;
  flattenPage(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    options?: PdfFlattenPageOptions,
  ): PdfTask<PdfPageFlattenResult>;
  extractPages(doc: PdfDocumentObject, pageIndexes: number[]): PdfTask<ArrayBuffer>;
  createDocument(id: string): PdfTask<PdfDocumentObject>;
  importPages(
    destDoc: PdfDocumentObject,
    srcDoc: PdfDocumentObject,
    srcPageIndices: number[],
    insertIndex?: number,
  ): PdfTask<PdfPageObject[]>;
  extractText(doc: PdfDocumentObject, pageIndexes: number[]): PdfTask<string>;
  redactTextInRects(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    rects: Rect[],
    options?: PdfRedactTextOptions,
  ): PdfTask<boolean>;
  applyRedaction(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ): PdfTask<boolean>;
  applyAllRedactions(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<boolean>;
  flattenAnnotation(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ): PdfTask<boolean>;
  exportAnnotationAppearanceAsPdf(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotation: PdfAnnotationObject,
  ): PdfTask<ArrayBuffer>;
  exportAnnotationsAppearanceAsPdf(
    doc: PdfDocumentObject,
    page: PdfPageObject,
    annotations: PdfAnnotationObject[],
  ): PdfTask<ArrayBuffer>;
  getTextSlices(doc: PdfDocumentObject, slices: PageTextSlice[]): PdfTask<string[]>;
  getPageGlyphs(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfGlyphObject[]>;
  getPageGeometry(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfPageGeometry>;
  getPageTextRuns(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfPageTextRuns>;
  merge(files: PdfFile[]): PdfTask<PdfFile>;
  mergePages(mergeConfigs: Array<{ docId: string; pageIndices: number[] }>): PdfTask<PdfFile>;
  preparePrintDocument(doc: PdfDocumentObject, options?: PdfPrintOptions): PdfTask<ArrayBuffer>;
  deletePage(doc: PdfDocumentObject, pageIndex: number): PdfTask<boolean>;
  saveAsCopy(doc: PdfDocumentObject): PdfTask<ArrayBuffer>;
  closeDocument(doc: PdfDocumentObject): PdfTask<boolean>;
  closeAllDocuments(): PdfTask<boolean>;

  // Security operations
  setDocumentEncryption(
    doc: PdfDocumentObject,
    userPassword: string,
    ownerPassword: string,
    allowedFlags: number,
  ): PdfTask<boolean>;
  removeEncryption(doc: PdfDocumentObject): PdfTask<boolean>;
  unlockOwnerPermissions(doc: PdfDocumentObject, ownerPassword: string): PdfTask<boolean>;
  isEncrypted(doc: PdfDocumentObject): PdfTask<boolean>;
  isOwnerUnlocked(doc: PdfDocumentObject): PdfTask<boolean>;
}

/**
 * Arguments of PdfEngine method
 *
 * @public
 */
export type PdfEngineMethodArgs<P extends PdfEngineMethodName> = Readonly<
  Parameters<Required<PdfEngine>[P]>
>;

/**
 * Return type of PdfEngine method
 *
 * @public
 */
export type PdfEngineMethodReturnType<P extends PdfEngineMethodName> = ReturnType<
  Required<PdfEngine>[P]
>;