/**
 * Public model types of the engine API.
 *
 * PDF page coordinates are in points
 * (1/72 inch), origin at the bottom-left corner, y-axis pointing up.
 * Rects are `{left, top, right, bottom}` with `top >= bottom`.
 *
 */
/**
 * An axis-aligned rectangle in PDF page coordinates (points, y-up), where
 * `top >= bottom` and `right >= left`.
 *
 * PDF rectangle arrays are specified by ISO 32000-2:2020, 7.9.5.
 *
 * See {@link PdfRect} (the companion namespace-like value) for helpers that
 * operate on these rects.
 *
 */
export interface PdfRect {
    left: number;
    top: number;
    right: number;
    bottom: number;
}
/** Helper functions for {@link PdfRect} values (the coordinate system is y-up). */
export declare const PdfRect: {
    /** Width of the rect (`right - left`). */
    readonly width: (r: PdfRect) => number;
    /** Height of the rect (`top - bottom`, since the y-axis points up). */
    readonly height: (r: PdfRect) => number;
    /** True if the rect has non-positive width or height. */
    readonly isEmpty: (r: PdfRect) => boolean;
    /** True if `(x, y)` (page coordinates) lies within the rect, edges inclusive. */
    readonly containsPoint: (r: PdfRect, x: number, y: number) => boolean;
};
/**
 * Page rotation in clockwise 90-degree steps, corresponding to the page
 * dictionary's `/Rotate` entry in ISO 32000-2:2020, 7.7.3.3, Table 31.
 *
 */
export type PdfPageRotation = 0 | 90 | 180 | 270;
/**
 * Converts a rotation index (0-3) to a {@link PdfPageRotation}.
 * The index is masked to 0-3, so out-of-range values wrap around.
 * @param index - The 0-based index.
 * @returns The resulting PdfPageRotation.
 *
 */
export declare const pdfPageRotationFromIndex: (index: number) => PdfPageRotation;
/**
 * Inverse of {@link pdfPageRotationFromIndex}: converts a rotation to an index (0-3).
 *
 * @param rotation - The clockwise page rotation, in 90-degree steps.
 * @returns The converted number.
 *
 */
export declare const pdfPageRotationToIndex: (rotation: PdfPageRotation) => number;
/**
 * Encryption/permission information of a document. Present only for encrypted
 * documents; see {@link PdfDocument.permissions}.
 *
 * The permission flags follow ISO 32000-1:2008, Table 22. The `allows*` helpers
 * mirror the pdfrx semantics exactly, including the same bit masks, so a
 * document evaluates identically here and in upstream pdfrx.
 *
 */
export declare class PdfPermissions {
    /** Raw permission flags from the PDF security handler. */
    readonly permissions: number;
    /** Revision of the standard security handler that produced `permissions`. */
    readonly securityHandlerRevision: number;
    constructor(
    /** Raw permission flags from the PDF security handler. */
    permissions: number, 
    /** Revision of the standard security handler that produced `permissions`. */
    securityHandlerRevision: number);
    /** Whether the document allows copying/extracting its contents. */
    get allowsCopying(): boolean;
    /** Whether the document allows document assembly (insert/rotate/delete pages). */
    get allowsDocumentAssembly(): boolean;
    /** Whether the document allows printing its pages. */
    get allowsPrinting(): boolean;
    /** Whether the document allows modifying annotations and form fields. */
    get allowsModifyAnnotations(): boolean;
}
/** Opaque identity of a logical page placement within an open document. */
export type PdfPageId = string & {
    readonly __pdfPageId: unique symbol;
};
/**
 * Destination that follows a logical page when the page arrangement changes.
 *
 * The `pageId` is the opaque identity of a {@link PdfPage} placement, not a PDF
 * object number or page index. Normally, do not construct this object or handle
 * the ID directly; use {@link PdfPage.dest} on the target page:
 *
 * ```ts
 * const dest = document.pages[4]!.dest({
 *   by: 'id',
 *   command: 'fit',
 *   params: [],
 * });
 * ```
 *
 * The resulting destination follows that logical page through reordering.
 * When the same identity appears more than once, one matching placement is
 * selected; use {@link PdfPage.duplicate} when placements need distinct
 * identities.
 *
 */
export interface PdfDestById {
    readonly by: 'id';
    readonly pageId: PdfPageId;
    /** Lower-cased explicit-destination type such as `xyz`, `fit`, or `fitr`. */
    readonly command: string;
    /** Operands following the destination type; `null` retains the current value. */
    readonly params: readonly (number | null)[];
}
/**
 * Destination that keeps pointing at a fixed 1-based position.
 *
 * The simplest way to create one is {@link PdfPage.dest} on the page currently
 * occupying the desired position:
 *
 * ```ts
 * const dest = document.pages[4]!.dest({
 *   by: 'pageNumber',
 *   command: 'fit',
 *   params: [],
 * });
 * ```
 *
 * The resulting destination keeps page number 5 even if another logical page
 * later occupies that position.
 *
 */
export interface PdfDestByPageNumber {
    readonly by: 'pageNumber';
    /**
     * 1-based position to resolve when the destination is followed or encoded.
     *
     */
    readonly pageNumber: number;
    /**
     * Lower-cased explicit-destination type: `xyz`, `fit`, `fith`, `fitv`,
     * `fitr`, `fitb`, `fitbh`, or `fitbv`.
     *
     * The corresponding PDF names and their semantics are specified by
     * ISO 32000-2:2020, 12.3.2.2, Table 149.
     *
     */
    readonly command: string;
    /**
     * Operands following the destination type, in the order prescribed by
     * ISO 32000-2:2020, 12.3.2.2, Table 149. Depending on {@link command}, these
     * are `left`, `top`, `right`, `bottom`, and/or `zoom`; `null` represents a
     * PDF `null` operand, meaning that the corresponding current value is
     * retained.
     *
     */
    readonly params: readonly (number | null)[];
}
/**
 * A navigation destination inside a document. ID destinations follow a logical
 * page through rearrangement; page-number destinations keep pointing at a
 * fixed position.
 *
 * Use {@link PdfPage.dest} to create either form without handling opaque page
 * IDs or 1-based page numbers directly:
 *
 * ```ts
 * const followsPage = document.pages[4]!.dest({
 *   by: 'id',
 *   command: 'fit',
 *   params: [],
 * });
 * const keepsPosition = document.pages[4]!.dest({
 *   by: 'pageNumber',
 *   command: 'fit',
 *   params: [],
 * });
 * ```
 *
 */
export type PdfDest = PdfDestById | PdfDestByPageNumber;
/** A destination resolved against the document's current page arrangement. */
export interface PdfResolvedDest {
    readonly pageNumber: number;
    readonly command: string;
    readonly params: readonly (number | null)[];
}
/** Options accepted by `PdfPage.dest()`. */
export interface PdfDestOptions {
    readonly by: 'id' | 'pageNumber';
    readonly command: string;
    readonly params: readonly (number | null)[];
}
/**
 * A node of the document outline (a.k.a. bookmarks), corresponding to an
 * outline item dictionary in ISO 32000-2:2020, 12.3.3, Table 151.
 *
 */
export interface PdfOutlineNode {
    /** Human-readable label from the outline item's `Title` entry. */
    readonly title: string;
    /**
     * Destination from the outline item's `Dest` entry or Go-To action, or
     * `null` if it has none. See ISO 32000-2:2020, 12.3.3, Table 151 and
     * 12.6.4.2, Table 202.
     *
     */
    readonly dest: PdfDest | null;
    /** Nested outline items linked through the `First`/`Last` hierarchy. */
    readonly children: readonly PdfOutlineNode[];
}
/**
 * Markup metadata shared with link annotations. The represented PDF entries
 * are specified by ISO 32000-2:2020, 12.5.2, Table 166 and 12.5.6.2,
 * Table 172.
 *
 */
export interface PdfAnnotation {
    /** Markup annotation title from `/T`, or `null`; Table 172. */
    readonly title: string | null;
    /** Annotation contents from `/Contents`, or `null`; Table 166. */
    readonly content: string | null;
    /** Markup annotation subject from `/Subj`, or `null`; Table 172. */
    readonly subject: string | null;
    /**
     * Raw `/M` PDF date string (e.g. `D:20240131120000+09'00'`), if any.
     * See ISO 32000-2:2020, 7.9.4 and Table 166.
     *
     */
    readonly modificationDate: string | null;
    /**
     * Raw `/CreationDate` PDF date string, if any. See ISO 32000-2:2020,
     * 7.9.4 and Table 172.
     *
     */
    readonly creationDate: string | null;
}
/**
 * A link on a page, either an explicit link annotation or (when auto-detection
 * is enabled) a URL found in the page text.
 *
 * Explicit link annotations are defined by ISO 32000-2:2020, 12.5.6.5,
 * Table 176. Their destinations use 12.3.2; URI actions use 12.6.4.8.
 * See {@link PdfPage.loadLinks}.
 *
 */
export type PdfLinkTarget = {
    readonly kind: 'uri';
    readonly url: string;
} | {
    readonly kind: 'destination';
    readonly dest: PdfDest;
};
export interface PdfLink {
    /** PDF annotation or transient URL-like text detected from page contents. */
    readonly kind: 'annotation' | 'detected';
    /** Annotation `/NM` identity; `null` for detected links. */
    readonly id: string | null;
    /** Areas of the link in PDF page coordinates. */
    readonly rects: readonly PdfRect[];
    /** URI or in-document destination followed by this link. */
    readonly target: PdfLinkTarget;
    /** Annotation metadata for the link, if any. */
    readonly annotation: PdfAnnotation | null;
}
/**
 * Kind of an AcroForm field, mapped from PDFium's `FPDF_FORMFIELD_*` codes.
 * The corresponding PDF field types are specified by ISO 32000-2:2020,
 * 12.7.5 ("Field types").
 *
 */
export type PdfFormFieldType = 'unknown' | 'pushButton' | 'checkBox' | 'radioButton' | 'comboBox' | 'listBox' | 'textField' | 'signature';
/** Whether text follows page rotation or remains upright in the viewport. */
export type PdfTextOrientationBehavior = 'page' | 'upright';
/** Intrinsic clockwise text rotation and its relationship to page rotation. */
export interface PdfTextOrientation {
    /** Clockwise rotation intrinsic to the text/widget. */
    readonly rotation: PdfPageRotation;
    /** `page` follows page rotation; `upright` ignores it. */
    readonly behavior: PdfTextOrientationBehavior;
}
/**
 * Maps a raw `FPDF_FORMFIELD_*` code to a {@link PdfFormFieldType}.
 *
 * @param code - The machine-readable error code.
 * @returns The resulting PdfFormFieldType.
 *
 */
export declare const pdfFormFieldTypeFromCode: (code: number) => PdfFormFieldType;
/**
 * Decoded common AcroForm field flags from `/Ff`. See ISO 32000-2:2020,
 * 12.7.4.1, Tables 226 ("Entries common to all field dictionaries") and 227
 * ("Field flags common to all field types").
 *
 */
export interface PdfFormFieldFlags {
    /** The field cannot be edited by the user. */
    readonly readOnly: boolean;
    /** The field must have a value when the form is submitted. */
    readonly required: boolean;
    /** The field is excluded from form submission/export. */
    readonly noExport: boolean;
}
/**
 * Decodes the raw `FPDF_FORMFLAG_*` bitmask into {@link PdfFormFieldFlags}.
 *
 * @param flags - The flags value (number).
 * @returns The resulting PdfFormFieldFlags.
 *
 */
export declare const decodeFormFieldFlags: (flags: number) => PdfFormFieldFlags;
/**
 * One selectable option of a combo box or list box. Choice-field option arrays
 * are specified by ISO 32000-2:2020, 12.7.5.4, Table 234.
 *
 */
export interface PdfFormFieldOption {
    readonly label: string;
    readonly selected: boolean;
}
/**
 * An AcroForm field of a document. A field is identified by its fully-qualified
 * {@link name}; widgets that share a name (e.g. the buttons of a radio group)
 * are merged into one field with several {@link rects}. Obtain them via
 * {@link PdfPage.loadFormFields} / {@link PdfDocument.loadFormFields}, read
 * values here, and change them with {@link PdfDocument.setFormFieldValue}.
 *
 * Field dictionaries and fully-qualified field names are specified by
 * ISO 32000-2:2020, 12.7.4, especially Tables 226 and 227. Type-specific
 * entries are specified by 12.7.5.
 *
 */
export interface PdfFormField {
    /** Fully-qualified field name (`/T`); may be empty for unnamed fields. */
    readonly name: string;
    /** Field kind. */
    readonly type: PdfFormFieldType;
    /** 1-based page number the field's widget(s) sit on. */
    readonly pageNumber: number;
    /** Widget rectangles in PDF page coordinates (one per widget). */
    readonly rects: readonly PdfRect[];
    /** Text orientation for each widget, parallel to {@link rects}. */
    readonly textOrientations: readonly PdfTextOrientation[];
    /** Current value (`/V`): the text, the selected export value, or `''` for buttons. */
    readonly value: string;
    /** Alternate name / tooltip (`/TU`), or `null`. */
    readonly alternateName: string | null;
    /** Checkbox/radio: whether the field is currently checked/selected. */
    readonly isChecked?: boolean;
    /** Checkbox/radio: the export ("on") value; for a radio group, the selected one. */
    readonly exportValue?: string | null;
    /** Combo/list: the options and their selection state. */
    readonly options?: readonly PdfFormFieldOption[];
    /** Text fields: whether the field accepts multiple lines (`/Ff` Multiline bit). */
    readonly multiline?: boolean;
    /** Decoded field flags. */
    readonly flags: PdfFormFieldFlags;
}
/**
 * A value accepted by {@link PdfDocument.setFormFieldValue}. Interpretation
 * depends on the field type: `boolean` toggles a checkbox; a `string` sets text,
 * selects a radio export value, or selects one choice option by its label; and
 * a `string[]` selects choice options by label (including single-select
 * combo/list fields when replaying history).
 *
 */
export type PdfFormFieldValue = string | boolean | string[];
/**
 * One field value changed as part of a form mutation transaction. Choice-field
 * states use selected option-label arrays so they remain replayable when a
 * PDF's export value differs from its display label.
 *
 */
export interface PdfFormFieldChange {
    readonly name: string;
    readonly before: PdfFormFieldValue;
    readonly after: PdfFormFieldValue;
}
/** Where a form mutation originated. */
export type PdfFormChangeOrigin = 'user' | 'api' | 'remote' | 'restore' | 'history';
/** Options shared by form mutation APIs. */
export interface PdfFormMutationOptions {
    /** Defaults to `api`. */
    readonly origin?: PdfFormChangeOrigin;
    /** Application-defined id correlating the complete bulk mutation. */
    readonly transactionId?: string;
    /** Stable application/user id responsible for the mutation. */
    readonly actorId?: string;
}
/**
 * Raw text of a page: full text plus one rect per UTF-16 code unit.
 * See {@link PdfPage.loadText}.
 *
 */
export interface PdfPageRawText {
    readonly fullText: string;
    /** `charRects.length === fullText.length`; indices correspond 1:1. */
    readonly charRects: readonly PdfRect[];
}
/**
 * A font the engine could not find while loading or rendering a document.
 * Emitted via the {@link PdfDocumentEventMap.missingFonts | missingFonts} event;
 * supply a substitute with {@link PdfrxEngine.addFontData}.
 *
 * @see [Missing-font fallback](https://github.com/espresso3389/pdfrx_web/blob/master/docs/FONT-FALLBACK.md)
 *   — how the default resolver maps these queries to downloadable fonts.
 *
 */
export interface PdfFontQuery {
    /** Requested typeface (family) name. */
    readonly face: string;
    /** Requested weight (e.g. 400 for regular, 700 for bold). */
    readonly weight: number;
    readonly isItalic: boolean;
    /**
     * PDFium charset id of the requested font (the LOGFONT `lfCharSet` value).
     * Compare against the named ids in {@link PdfFontCharset} (e.g.
     * `query.charset === PdfFontCharset.shiftJis`), or turn it into a label with
     * {@link pdfFontCharsetName}. May be any value PDFium reports; the named set
     * covers the ones it commonly emits.
     *
     */
    readonly charset: number;
    /**
     * PDFium pitch-and-family byte of the requested font (the LOGFONT
     * `lfPitchAndFamily` value). The low two bits are pitch flags, while the high
     * nibble is one mutually exclusive family value. Use the helpers below
     * rather than treating all values as independent flags.
     *
     */
    readonly pitchFamily: number;
}
/**
 * Named PDFium font charset ids (LOGFONT `lfCharSet` values), mirroring pdfrx's
 * `PdfFontCharset` enum. Use these to interpret {@link PdfFontQuery.charset}:
 *
 * ```ts
 * if (query.charset === PdfFontCharset.shiftJis) { … } // Japanese
 * ```
 *
 */
export declare const PdfFontCharset: {
    /** Windows-1252 / Latin-1. */
    readonly ansi: 0;
    /** System default charset. */
    readonly default: 1;
    /** Symbol font charset. */
    readonly symbol: 2;
    /** Japanese (Shift-JIS). */
    readonly shiftJis: 128;
    /** Korean (Hangul). */
    readonly hangul: 129;
    /** Chinese Simplified (GB2312). */
    readonly gb2312: 134;
    /** Chinese Traditional (Big5). */
    readonly chineseBig5: 136;
    readonly greek: 161;
    readonly vietnamese: 163;
    readonly hebrew: 177;
    readonly arabic: 178;
    readonly cyrillic: 204;
    readonly thai: 222;
    readonly easternEuropean: 238;
};
/** One of the named charset ids in {@link PdfFontCharset}. */
export type PdfFontCharsetId = (typeof PdfFontCharset)[keyof typeof PdfFontCharset];
/**
 * Returns the {@link PdfFontCharset} name for a charset id (e.g. `128` →
 * `'shiftJis'`), or `undefined` if the id is not one of the named charsets.
 * @param charset - The charset value (number).
 * @returns The resulting string or undefined.
 *
 */
export declare const pdfFontCharsetName: (charset: number) => string | undefined;
/**
 * Values used by the PDFium LOGFONT-compatible `lfPitchAndFamily` byte. Pitch
 * occupies the low two bits; family occupies the high nibble and must be
 * compared after applying {@link PdfFontPitchFamily.familyMask}.
 *
 */
export declare const PdfFontPitchFamily: {
    /** Fixed-pitch (monospace) font. */
    readonly fixed: 1;
    readonly familyMask: 240;
    readonly dontCare: 0;
    /** Proportional serif font family. */
    readonly roman: 16;
    /** Proportional sans-serif font family. */
    readonly swiss: 32;
    /** Monospace font family. */
    readonly modern: 48;
    /** Script (handwriting-style) font family. */
    readonly script: 64;
    readonly decorative: 80;
};
/**
 * Whether a {@link PdfFontQuery.pitchFamily} value has the fixed-pitch (monospace) bit set.
 *
 * @param pitchFamily - The pitchFamily value (number).
 * @returns Whether the condition is satisfied.
 *
 */
export declare const isFixedPitch: (pitchFamily: number) => boolean;
/**
 * Whether a {@link PdfFontQuery.pitchFamily} value names the Roman (serif) family.
 *
 * @param pitchFamily - The pitchFamily value (number).
 * @returns Whether the condition is satisfied.
 *
 */
export declare const isRomanFamily: (pitchFamily: number) => boolean;
/**
 * Whether a {@link PdfFontQuery.pitchFamily} value names the Script family.
 *
 * @param pitchFamily - The pitchFamily value (number).
 * @returns Whether the condition is satisfied.
 *
 */
export declare const isScriptFamily: (pitchFamily: number) => boolean;
/**
 * A point in bounding-box-relative PDF page coordinates (points, y-up) — the
 * same space as {@link PdfRect} and {@link PdfFormField} rects.
 *
 */
export interface PdfAnnotationPoint {
    x: number;
    y: number;
}
/** A text-markup quadrilateral (one highlighted run) in page coordinates. */
export interface PdfAnnotationQuad {
    topLeft: PdfAnnotationPoint;
    topRight: PdfAnnotationPoint;
    bottomLeft: PdfAnnotationPoint;
    bottomRight: PdfAnnotationPoint;
}
/** An RGBA color, each channel 0-255. */
export interface PdfAnnotationColor {
    r: number;
    g: number;
    b: number;
    a: number;
}
/**
 * Subtype-specific geometry of an annotation, in bounding-box-relative page
 * coordinates. `none` covers subtypes whose shape is fully described by
 * {@link PdfAnnotationObject.rect} (square, circle, freeText, text, …).
 *
 */
export type PdfAnnotationGeometry = {
    kind: 'none';
} | {
    kind: 'ink';
    strokes: PdfAnnotationPoint[][];
} | {
    kind: 'markup';
    quads: PdfAnnotationQuad[];
} | {
    kind: 'line';
    start: PdfAnnotationPoint;
    end: PdfAnnotationPoint;
} | {
    kind: 'polygon';
    vertices: PdfAnnotationPoint[];
} | {
    kind: 'polyline';
    vertices: PdfAnnotationPoint[];
};
/**
 * PDF annotation subtype (`/Subtype`), lowercased; `unknown` for unmapped
 * types. Standard annotation types are listed by ISO 32000-2:2020, 12.5.6,
 * Table 171.
 *
 */
export type PdfAnnotationSubtype = 'link' | 'text' | 'freeText' | 'line' | 'square' | 'circle' | 'polygon' | 'polyline' | 'highlight' | 'underline' | 'squiggly' | 'strikeout' | 'stamp' | 'caret' | 'ink' | 'unknown';
/**
 * Maps a worker subtype string (lowercased `/Subtype`) to a
 * {@link PdfAnnotationSubtype}, falling back to `unknown` for anything not
 * surfaced (widgets, popups, and rarer types).
 * @param name - The name to look up.
 * @returns The resulting PdfAnnotationSubtype.
 *
 */
export declare const pdfAnnotationSubtypeFromName: (name: string) => PdfAnnotationSubtype;
/**
 * Bit masks for {@link PdfAnnotationObject.flags} (`/F`), matching PDFium's
 * `FPDF_ANNOT_FLAG_*`. Their meanings and bit positions are specified by
 * ISO 32000-2:2020, 12.5.3, Table 167 ("Annotation flags").
 *
 */
export declare const PdfAnnotationFlag: {
    readonly invisible: 1;
    readonly hidden: 2;
    readonly print: 4;
    readonly noZoom: 8;
    readonly noRotate: 16;
    readonly noView: 32;
    readonly readOnly: 64;
    readonly locked: 128;
    readonly toggleNoView: 256;
    readonly lockedContents: 512;
};
/**
 * An editable annotation on a page (not a widget/popup), as read by
 * {@link PdfPage.loadAnnotations} / {@link PdfDocument.loadAnnotations}. Rects and
 * geometry are in bounding-box-relative page coordinates (y-up).
 *
 * Standard annotation dictionary entries are specified by ISO 32000-2:2020,
 * 12.5.2, Table 166; markup entries by 12.5.6.2, Table 172; and
 * subtype-specific geometry by the applicable subclause of 12.5.6.
 *
 */
export interface PdfAnnotationObject {
    /**
     * Identifier accepted by `PdfPage.updateAnnotation()` and
     * `PdfPage.removeAnnotation()`.
     *
     * `/NM` is the PDF annotation dictionary's "annotation name": a PDF-standard
     * string intended to distinguish an annotation from other annotations on the
     * same page (ISO 32000-2:2020, 12.5.2, Table 166). It is an internal identity,
     * not the visible annotation contents or its page number. The engine stores
     * generated and caller-supplied ids in `/NM`, so they survive
     * `PdfDocument.encodePdf()` and can correlate update, remove, snapshot,
     * persistence, and synchronization operations.
     *
     * For an existing annotation without `/NM`, the engine returns a page-local
     * `@<index>` fallback. That fallback is positional rather than stable: after
     * adding, removing, or replacing annotations on the page, call
     * `PdfPage.loadAnnotations()` again before using it.
     *
     */
    readonly id: string;
    /** 1-based page number the annotation belongs to. */
    readonly pageNumber: number;
    readonly subtype: PdfAnnotationSubtype;
    /** URI or in-document destination for a Link annotation; null otherwise. */
    readonly linkTarget: PdfLinkTarget | null;
    /** Bounding rectangle in page coordinates. */
    readonly rect: PdfRect;
    /** Stroke/primary color, or null when unset. */
    readonly color: PdfAnnotationColor | null;
    /** Interior (fill) color, or null when unset. */
    readonly interiorColor: PdfAnnotationColor | null;
    /** Border width in points. */
    readonly borderWidth: number;
    /** Raw `FPDF_ANNOT_FLAG_*` bits (see {@link PdfAnnotationFlag}). */
    readonly flags: number;
    /** `/Contents` text (e.g. a note body or free-text content). */
    readonly contents: string | null;
    /** `/T` author/title. */
    readonly author: string | null;
    /** Stable application/user id of the last editor, separate from the display author. */
    readonly actorId: string | null;
    /** Monotonic per-annotation revision used for optimistic synchronization. */
    readonly revision: number;
    /** Text direction for FreeText content; harmless metadata on other subtypes. */
    readonly textOrientation: PdfTextOrientation;
    /** FreeText glyph color, or null when the annotation does not persist one. */
    readonly textColor: PdfAnnotationColor | null;
    /** FreeText font size in points, or null when inferred from an existing appearance. */
    readonly fontSize: number | null;
    /** Horizontal placement of FreeText content within its box. */
    readonly textAlign: 'left' | 'center' | 'right';
    /** Vertical placement of FreeText content within its box. */
    readonly textVerticalAlign: 'top' | 'middle' | 'bottom';
    readonly fontFace: string | null;
    readonly appearanceLines: readonly string[] | null;
    readonly appearanceRuns: readonly (readonly {
        text: string;
        fontFace: string | null;
        x: number;
        image?: {
            width: number;
            height: number;
            scale: number;
            pixels: Uint8Array;
        };
    }[])[] | null;
    /** RGBA image extracted from the annotation's normal appearance, or null. */
    readonly appearanceImage: {
        readonly width: number;
        readonly height: number;
        readonly pixels: Uint8Array;
    } | null;
    /** Vector paths extracted from the annotation's normal appearance stream. */
    readonly appearancePaths: readonly {
        readonly segments: readonly {
            readonly type: 'move' | 'line' | 'bezier';
            readonly point: PdfAnnotationPoint;
            readonly close: boolean;
        }[];
        readonly fillColor: PdfAnnotationColor | null;
        readonly strokeColor: PdfAnnotationColor | null;
        readonly strokeWidth: number;
        readonly fillMode: number;
        readonly stroke: boolean;
        readonly lineCap: number;
        readonly lineJoin: number;
    }[];
    /** Text placement/style extracted from the normal appearance stream. */
    readonly appearanceTextStyles: readonly {
        readonly origin: PdfAnnotationPoint;
        readonly fontSize: number;
        readonly fillColor: PdfAnnotationColor | null;
    }[];
    /** `/Subj` subject. */
    readonly subject: string | null;
    /** Raw PDF date string (`D:…`), if any. */
    readonly modificationDate: string | null;
    /** Raw PDF date string, if any. */
    readonly creationDate: string | null;
    /** Subtype-specific geometry. */
    readonly geometry: PdfAnnotationGeometry;
}
/** Filters shared by `PdfPage.loadAnnotations` and {@link PdfDocument.loadAnnotations}. */
export interface PdfLoadAnnotationsOptions {
    /** Return only this subtype, or any of these subtypes. Omit to return all annotations. */
    readonly subtype?: PdfAnnotationSubtype | readonly PdfAnnotationSubtype[];
}
/** Options for `PdfPage.loadHighlights` and {@link PdfDocument.loadHighlights}. */
export interface PdfLoadHighlightsOptions {
    /**
     * Extract the page text covered by each highlight's quadpoints. This loads
     * page text in addition to annotations, so it is disabled by default.
     *
     */
    readonly includeText?: boolean;
}
/** A highlight returned by page- or document-level `loadHighlights`. */
export interface PdfHighlightObject extends PdfAnnotationObject {
    readonly subtype: 'highlight';
    /** Highlighted page text, or `null` when text extraction was not requested or unavailable. */
    readonly text: string | null;
}
/**
 * Parameters to create or replace an annotation via
 * `PdfPage.addAnnotation` / `PdfPage.updateAnnotation`.
 *
 * Only these geometries are honored by the engine: `ink` (freehand; also how the
 * viewer realizes line/arrow), `markup` quads (highlight/underline/squiggly/
 * strikeout), and rect-defined `square`/`circle`. `freeText`/`text` use `rect` +
 * `contents`. Coordinates are bounding-box-relative page coordinates (y-up).
 *
 * FreeText requires language-aware font selection, measurement and wrapping;
 * emoji are rendered as image runs because PDF text appearances cannot
 * reliably represent modern color emoji. The normal authored-FreeText flow is
 * therefore:
 *
 * 1. Create a spec with `subtype`, `rect`, and `contents`.
 * 2. Call {@link PdfDocument.prepareFreeTextAppearance}.
 * 3. Pass that same spec to {@link PdfPage.addAnnotation} or
 *    {@link PdfPage.updateAnnotation}.
 *
 * `prepareFreeTextAppearance()` mutates the spec by filling `fontFace`,
 * `appearanceLines`, and `appearanceRuns`. It recognizes mixed scripts,
 * chooses language-specific CJK fonts when a resolver is available, wraps
 * using the selected fonts, and replaces supported emoji with embedded image
 * runs. Kana and Hangul normally identify Japanese and Korean themselves. For
 * ambiguous Han-only text, the engine uses an explicit BCP-47 hint such as
 * `ja`, `zh-Hant`, or `ko`, followed by the browser's locale when available.
 * Server integrations should obtain the hint from document metadata, the
 * signed-in user's locale, or a parsed `Accept-Language` preference.
 *
 * @example Add Japanese and emoji FreeText
 * ```ts
 * const spec: PdfAnnotationSpec = {
 *   subtype: 'freeText',
 *   rect: { left: 40, bottom: 700, right: 260, top: 750 },
 *   // Han-only text needs a language hint when no suitable browser locale exists.
 *   contents: '契約内容 😀',
 *   fontSize: 14,
 * };
 *
 * await document.prepareFreeTextAppearance(spec, { language: 'ja' });
 * const annotationId = await document.pages[0]!.addAnnotation(spec);
 * ```
 *
 * Most applications should let the preparation method create the appearance
 * fields. Set them directly only when an integration already performs its own
 * font resolution, measurement, line breaking, and emoji rasterization.
 *
 * For the reason language affects glyph shapes, the automatic browser/server
 * behavior, Linux font setup, offline assets, caches, and custom providers,
 * read the
 * [Text, language, and emoji appearance guide](https://github.com/espresso3389/pdfrx_web/blob/master/docs/TEXT-APPEARANCE.md).
 *
 * The corresponding PDF annotation dictionaries are defined by
 * ISO 32000-2:2020, 12.5.2 and the subtype-specific parts of 12.5.6.
 *
 */
export interface PdfAnnotationSpec {
    /**
     * Identity stored in the PDF annotation dictionary's `/NM` ("annotation
     * name") entry. Supply an application id when the annotation must correlate
     * with another representation, such as an external store. Omit it to let the
     * engine generate an id; {@link PdfPage.addAnnotation} returns the generated
     * value.
     *
     */
    id?: string;
    subtype: PdfAnnotationSubtype;
    /** Required when `subtype` is `link`; ignored for other annotation types. */
    linkTarget?: PdfLinkTarget;
    rect?: PdfRect;
    color?: PdfAnnotationColor | null;
    interiorColor?: PdfAnnotationColor | null;
    borderWidth?: number;
    flags?: number;
    /**
     * Annotation text. For authored FreeText, pass this spec through
     * {@link PdfDocument.prepareFreeTextAppearance} to resolve its fonts,
     * wrapping, and emoji image runs.
     *
     */
    contents?: string | null;
    author?: string | null;
    actorId?: string | null;
    revision?: number;
    /** Text direction for FreeText content. Defaults to page-relative, unrotated. */
    textOrientation?: PdfTextOrientation;
    /** FreeText glyph color. Defaults to black. */
    textColor?: PdfAnnotationColor | null;
    /** FreeText font size in points. Defaults to 12. */
    fontSize?: number;
    /** Horizontal placement of FreeText content within its box. Defaults to `left`. */
    textAlign?: 'left' | 'center' | 'right';
    /** Vertical placement of FreeText content within its box. Defaults to `top`. */
    textVerticalAlign?: 'top' | 'middle' | 'bottom';
    /**
     * Primary font face registered with the engine for a generated FreeText
     * appearance. Usually populated by
     * {@link PdfDocument.prepareFreeTextAppearance}.
     *
     */
    fontFace?: string | null;
    /**
     * Pre-wrapped lines used by the generated FreeText appearance. Usually
     * populated by {@link PdfDocument.prepareFreeTextAppearance}.
     *
     */
    appearanceLines?: string[];
    /**
     * Per-line positioned font and image runs used for mixed-script text and
     * emoji. Usually populated by
     * {@link PdfDocument.prepareFreeTextAppearance}; advanced integrations may
     * construct the runs directly.
     *
     */
    appearanceRuns?: {
        text: string;
        fontFace: string | null;
        x: number;
        image?: {
            width: number;
            height: number;
            scale: number;
            pixels: Uint8Array;
        };
    }[][];
    /** RGBA pixels used as the normal appearance of a `stamp` annotation. */
    appearanceImage?: {
        width: number;
        height: number;
        pixels: Uint8Array;
    };
    /**
     * Normalized vector paths used as the normal appearance of a `stamp`
     * annotation. Points are in a 0–1 box with an SVG-style y-down axis.
     *
     */
    appearancePaths?: {
        segments: {
            type: 'move' | 'line' | 'bezier';
            point: PdfAnnotationPoint;
            close: boolean;
        }[];
        fillColor: PdfAnnotationColor | null;
        strokeColor: PdfAnnotationColor | null;
        /** Stroke width as a fraction of the appearance width. */
        strokeWidth: number;
        fillMode: number;
        stroke: boolean;
        lineCap: number;
        lineJoin: number;
    }[];
    geometry?: PdfAnnotationGeometry;
}
/** A portable annotation record suitable for structured cloning or external storage. */
export interface PdfStoredAnnotation {
    readonly id: string;
    readonly pageNumber: number;
    readonly spec: PdfAnnotationSpec;
}
/** Versioned external representation returned by {@link PdfDocument.exportAnnotations}. */
export interface PdfAnnotationSnapshot {
    readonly version: 1;
    readonly annotations: readonly PdfStoredAnnotation[];
}
/** Where an annotation mutation originated; remote changes can be ignored by sync publishers. */
export type PdfAnnotationChangeOrigin = 'user' | 'api' | 'remote' | 'restore' | 'history';
/** One synchronization-friendly annotation mutation. */
export type PdfAnnotationChange = {
    readonly type: 'add' | 'update';
    readonly id: string;
    readonly pageNumber: number;
    readonly spec: PdfAnnotationSpec;
} | {
    readonly type: 'remove';
    readonly id: string;
    readonly pageNumber: number;
};
/**
 * A reversible annotation mutation. Unlike {@link PdfAnnotationChange}, this
 * carries both states so observers can build Undo/Redo history without having
 * to intercept the API call before it reaches {@link PdfDocument}.
 *
 */
export interface PdfAnnotationHistoryChange {
    readonly id: string;
    readonly pageNumber: number;
    readonly before: PdfAnnotationSpec | null;
    readonly after: PdfAnnotationSpec | null;
}
/** Options shared by annotation mutation APIs. */
export interface PdfAnnotationMutationOptions {
    /** Defaults to `api`. */
    readonly origin?: PdfAnnotationChangeOrigin;
    /** Application-defined id used to correlate or deduplicate a batch across viewers. */
    readonly transactionId?: string;
    /** Stable application/user id responsible for the mutation. */
    readonly actorId?: string;
    /**
     * Updates a raster Stamp's attributes and geometry without replacing its
     * existing appearance stream. Set this when the appearance pixels are
     * unchanged, so the existing image resources remain associated with the
     * annotation.
     *
     */
    readonly preserveAppearance?: boolean;
}
/** Options for restoring an external snapshot. */
export interface PdfRestoreAnnotationsOptions extends PdfAnnotationMutationOptions {
    /** `merge` upserts snapshot records; `replace` also removes records absent from it. Default: `replace`. */
    readonly mode?: 'merge' | 'replace';
}
/** Where a page-arrangement mutation originated. */
export type PdfPageChangeOrigin = 'user' | 'api' | 'remote' | 'restore' | 'history' | 'materialize';
/** Options shared by page-arrangement mutation APIs. */
export interface PdfPageMutationOptions {
    /** Defaults to `api`. */
    readonly origin?: PdfPageChangeOrigin;
    /** Application-defined id used to correlate or deduplicate a change. */
    readonly transactionId?: string;
    /** Stable application/user id responsible for the mutation. */
    readonly actorId?: string;
}
/** A position-independent description of one page in a local arrangement. */
export interface PdfPageArrangementEntry {
    /** Physical source identity within the current engine process. Not a persistent/session id. */
    readonly sourceKey: string;
    /** Source page index in its owning PDF, zero-based. */
    readonly sourcePageIndex: number;
    /** Effective clockwise rotation. */
    readonly rotation: PdfPageRotation;
}
/**
 * Whether/how annotations are drawn when rendering a page.
 *
 * - `none` — draw neither annotations nor form widgets.
 * - `annotation` — draw annotations (and static widget appearances).
 * - `annotationAndForms` — draw annotations plus interactive form widgets.
 * - `formsOnly` — draw interactive form widgets but *not* other annotations;
 *   used by the viewer when annotations are shown through the SVG overlay
 *   instead of the canvas.
 *
 */
export type PdfAnnotationRenderingMode = 'none' | 'annotation' | 'annotationAndForms' | 'formsOnly';
/**
 * Maps a {@link PdfAnnotationRenderingMode} to the numeric code used by the worker protocol.
 *
 * @param mode - The mode value (PdfAnnotationRenderingMode).
 * @returns The resulting number.
 *
 */
export declare const annotationRenderingModeToIndex: (mode: PdfAnnotationRenderingMode) => number;
/**
 * Function called when a document requires a password.
 * Return the password to try, or `null` to give up (aborts opening with a
 * {@link PdfPasswordException}).
 *
 * It is called repeatedly on each failed attempt until it returns `null` or a
 * correct password, so it may prompt the user anew each time.
 *
 */
export type PdfPasswordProvider = () => string | null | Promise<string | null>;
/**
 * Callback invoked while a document is being downloaded (see
 * {@link PdfOpenUrlOptions.progressCallback}). `bytesTotal` is omitted when the
 * total size is unknown (e.g. no `Content-Length`).
 *
 */
export type PdfDownloadProgressCallback = (bytesReceived: number, bytesTotal?: number) => void;
/**
 * Thrown when opening an encrypted document fails due to a missing/wrong
 * password (i.e. the {@link PdfPasswordProvider} returned `null` or ran out of
 * passwords to try).
 *
 */
export declare class PdfPasswordException extends Error {
    /**
     * Creates a password failure.
     *
     * @param message - The human-readable error message.
     */
    constructor(message: string);
}
/**
 * Result of rendering (a part of) a page: RGBA8888 pixels, ready for Canvas 2D
 * and WebGL without any channel conversion.
 *
 * The engine renders in native BGRA order, but the worker swaps channels while
 * copying the bitmap out (effectively free), so {@link pixels} is already
 * RGBA — the only pixel format the web can consume directly. See
 * {@link PdfPage.render}.
 *
 */
export declare class PdfImage {
    /** Width of the bitmap in pixels. */
    readonly width: number;
    /** Height of the bitmap in pixels. */
    readonly height: number;
    /** RGBA8888, tightly packed, `width * height * 4` bytes. */
    readonly pixels: Uint8Array;
    constructor(
    /** Width of the bitmap in pixels. */
    width: number, 
    /** Height of the bitmap in pixels. */
    height: number, 
    /** RGBA8888, tightly packed, `width * height * 4` bytes. */
    pixels: Uint8Array);
    /**
     * Wraps the RGBA pixels in an `ImageData` for Canvas 2D. Zero-copy: the
     * returned `ImageData` shares this image's pixel buffer, so do not mutate
     * {@link pixels} afterwards if you keep using the `ImageData`.
     *
     * @returns The converted ImageData.
     *
     */
    toImageData(): ImageData;
    /**
     * Creates an `ImageBitmap`, which is cheaper to draw repeatedly than `putImageData`.
     *
     * @returns The converted Promise.
     *
     */
    toImageBitmap(): Promise<ImageBitmap>;
}
/**
 * Payload types of the events emitted by {@link PdfDocument}, keyed by event
 * name. Subscribe with {@link PdfDocument.addEventListener}.
 *
 */
export interface PdfDocumentEventMap {
    /** All pages are loaded (fired immediately for non-progressive loading). */
    loadComplete: Record<string, never>;
    /** Page objects were replaced (progressive load / reload). */
    pageStatusChanged: {
        pageNumbers: number[];
    };
    /** The logical document outline was replaced through `PdfDocument.setOutline()`. */
    outlineChanged: Record<string, never>;
    /** Logical Link-annotation replacements were staged on the listed arranged pages. */
    linksChanged: {
        pageNumbers: number[];
    };
    /**
     * The *arrangement* of pages changed — order, rotation, or count — via
     * `PdfDocument.setPages` or `PdfDocument.materialize`. Always accompanied by
     * `pageStatusChanged`; listen to this one to invalidate things keyed by page
     * position, which a plain progressive-load update does not disturb.
     *
     */
    pagesRearranged: {
        origin: PdfPageChangeOrigin;
        transactionId?: string;
        actorId?: string;
        /** Arrangement immediately before the mutation. */
        before: readonly PdfPageArrangementEntry[];
        /** Arrangement immediately after the mutation. */
        after: readonly PdfPageArrangementEntry[];
        pageNumbers: number[];
    };
    /** The engine reported missing fonts; supply them via `PdfrxEngine.addFontData`. */
    missingFonts: {
        queries: PdfFontQuery[];
    };
    /**
     * One form transaction completed. `changes` contains the complete typed
     * before/after diff, including calculated fields changed as a consequence.
     * `source` is `'user'` for interactive edits in the viewer (relayed from the
     * form-fill module) and `'api'` for programmatic writes.
     *
     */
    formFieldsChanged: {
        /** Kept for UI consumers distinguishing interactive and programmatic writes. */
        source: 'user' | 'api';
        origin: PdfFormChangeOrigin;
        transactionId?: string;
        actorId?: string;
        /** Every direct and calculated field change produced by one transaction. */
        changes: readonly PdfFormFieldChange[];
        pageNumbers?: number[];
    };
    /**
     * Annotations were added, updated or removed. The exact synchronization-ready
     * changes are included. `origin: 'remote'` identifies changes that should not
     * be published back to the same synchronization channel. Page-scoped CRUD is
     * reported by the source document and by every open arrangement that places
     * that physical page; duplicate placements contribute each affected
     * arrangement page number.
     *
     */
    annotationsChanged: {
        origin: PdfAnnotationChangeOrigin;
        transactionId?: string;
        actorId?: string;
        changes: readonly PdfAnnotationChange[];
        /** Complete reversible states for the mutations in `changes`. */
        historyChanges: readonly PdfAnnotationHistoryChange[];
        pageNumbers: number[];
    };
}
/** Union of the event names in {@link PdfDocumentEventMap}. */
export type PdfDocumentEventName = keyof PdfDocumentEventMap;
//# sourceMappingURL=types.d.ts.map