@embedpdf/react 3.0.0-next.14 → 3.0.0-next.15

package/dist/AnnotationList-CkijRHet-HEFNUIZe.d.ts

@@ -0,0 +1,877 @@
+//#region ../../engine/core/dist/AnnotationList-CkijRHet.d.ts
+//#region src/dto/IsoDateTime.d.ts
+/**
+ * A moment, as an ISO 8601 string: `2017-07-12T21:44:38-07:00`.
+ *
+ * Every date in the engine's data has this type. A date read from the PDF
+ * keeps the offset it was written with (a PDF date without an offset reads
+ * without one); a date the engine makes itself is UTC (`…Z`). A date the PDF
+ * writes in a form that can't be parsed reads as `null`. PDF dates have whole
+ * seconds, so a fraction is dropped on write.
+ *
+ * Reads are strings, never `Date` objects: a read must go back into a write
+ * as it is, including through JSON, and a `Date` would also drop the offset.
+ */
+type IsoDateTime = string;
+//#endregion
+//#region src/identity/PageObjectNumber.d.ts
+/**
+ * PDF indirect object number for a page.
+ *
+ * Resolved via the PDFium runtime helper `EPDFPage_GetObjectNumber(pagePtr)`.
+ * Always > 0 for well-formed PDFs, and the primary addressing key. The
+ * page index is kept on `PageHandle` as display
+ * metadata only, because it can shift when pages are inserted, deleted, or
+ * reordered while a session is open.
+ */
+type PageObjectNumber = number;
+//#endregion
+//#region src/identity/PageRef.d.ts
+/**
+ * How callers address a page — the page-plane sibling of `AnnotationRef`
+ * and `FormFieldRef`.
+ *
+ * `objectNumber` is the indirect object number of the page dictionary.
+ * ISO 32000-1 §7.7.3.3 requires every `/Kids` entry to be an indirect
+ * reference, the layer runtime never renumbers (frozen base + incremental
+ * deltas), and a deleted page's number is retired, never recycled — so it
+ * is the durable identity for the lifetime of a document. It is what every
+ * `PageLayout.ref` and `PageHandle.ref` carries.
+ *
+ * It is deliberately the only kind. Pages are durable by construction (see
+ * `PagesMutator`): a display index is never an identity, a page without an
+ * object number is refused at open (`MalformedPdf`), and a `/Names /Pages`
+ * key is a registry entry the layout already maps to a number, not a second
+ * identity the engine would ever return. The discriminated shape keeps the
+ * address consistent with the other refs and leaves room for an additive
+ * kind should a real one ever appear.
+ *
+ * Records that mention a page (an annotation ref, event payloads, per-page
+ * results, destinations, search matches) carry the same `page: PageRef`;
+ * `toPageRef()` builds one from a page number you already hold.
+ */
+type PageRef = {
+  kind: 'objectNumber';
+  objectNumber: PageObjectNumber;
+};
+/**
+ * A destination (ISO 32000-1 §12.3.2.2): the page it goes to and where on
+ * that page, measured from the top-left of that page's visible box, y down.
+ * Outlines, links, actions and the document's open destination all resolve
+ * to one of these; named destinations are resolved by the engine, so only
+ * this explicit form is ever handed out.
+ *
+ * `null` keeps the viewer's current value, as in the file, and a value left
+ * out means the same; an `xyz` zoom of `0` means the same as `null`. The
+ * `fitB*` kinds fit the page's content bounding box rather than the whole
+ * page. Pass one straight to the stage's `reveal`.
+ */
+type PageDestination = {
+  kind: 'xyz';
+  page: PageRef;
+  x?: number | null;
+  y?: number | null;
+  zoom?: number | null;
+} | {
+  kind: 'fit';
+  page: PageRef;
+} | {
+  kind: 'fitH';
+  page: PageRef;
+  y?: number | null;
+} | {
+  kind: 'fitV';
+  page: PageRef;
+  x?: number | null;
+} | {
+  kind: 'fitR';
+  page: PageRef;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} | {
+  kind: 'fitB';
+  page: PageRef;
+} | {
+  kind: 'fitBH';
+  page: PageRef;
+  y?: number | null;
+} | {
+  kind: 'fitBV';
+  page: PageRef;
+  x?: number | null;
+};
+/**
+ * One Hide `/T` or ResetForm `/Fields` entry. Deliberately unscoped: a
+ * dictionary reference carries no page, so resolution (a name to widgets, an
+ * object number to an annotation or field) is the interpreter's job — never
+ * the extractor's.
+ */
+type PdfActionTargetRef = {
+  kind: 'name';
+  name: string;
+} | {
+  kind: 'objectNumber';
+  objectNumber: number;
+};
+/**
+ * Decoded SubmitForm `/Flags` word (ISO 32000-2:2020 Table 240) plus the raw
+ * value. `exclude` is derived from bit 1 — never stored separately, so the
+ * two cannot disagree. Note the two easily-missed positions verified against
+ * the spec: bit 12 is `ExclFKey` (not "ExclFDFTemplate") and bit 13 is
+ * reserved/undefined, so `EmbedForm` is bit 14.
+ */
+interface SubmitFormFlags {
+  raw: number;
+  /** Bit 1: set → `fields` lists excluded fields. */
+  exclude: boolean;
+  /** Bit 2: submit designated valueless fields too, as name-only entries. */
+  includeNoValueFields: boolean;
+  /** Bits 3/6/9 folded into one verdict: bit 9 SubmitPDF dominates ("all
+   *  other flags shall be ignored except GetMethod"), else bit 6 XFDF, else
+   *  bit 3 HTML Form format, else FDF (the Table 240 default). */
+  format: 'fdf' | 'html' | 'xfdf' | 'pdf';
+  /** Bit 4. ISO makes GetMethod meaningful only with ExportFormat set, and
+   *  the bit-9 rule keeps it alive for SubmitPDF — so `'get'` only for
+   *  `'html'` and `'pdf'`; everything else posts. */
+  method: 'post' | 'get';
+  /** Bit 5 (meaningful only with ExportFormat; passed through — this stack
+   *  does not capture click coordinates). */
+  submitCoordinates: boolean;
+  /** Bit 7 (FDF only): include incremental updates via FDF `Differences`. */
+  includeAppendSaves: boolean;
+  /** Bit 8 (FDF only): include markup annotations. */
+  includeAnnotations: boolean;
+  /** Bit 10: convert date-like values to the standard date format. */
+  canonicalFormat: boolean;
+  /** Bit 11 (FDF, with IncludeAnnotations): only the current user's
+   *  annotations. */
+  exclNonUserAnnots: boolean;
+  /** Bit 12: the submitted FDF excludes its `F` entry. */
+  exclFKey: boolean;
+  /** Bit 14 (bit 13 is reserved): the FDF `F` entry embeds the source PDF. */
+  embedForm: boolean;
+}
+/**
+ * SubmitForm's extracted intent. Atomic on purpose: either every required
+ * component resolved (a complete, executable payload) or the node carries no
+ * payload at all — partial states are unrepresentable. An unreadable
+ * required component (`/F`) degrades the whole node to `unknown` +
+ * `payload-dropped` at read time instead.
+ */
+interface SubmitFormPayload {
+  /** Resolved `/F` URL — a `<< /FS /URL >>` file specification (7.11.5,
+   *  `/UF` preferred over `/F` per 7.11.2); a bare string `/F` is accepted
+   *  as a producer-compat extension. */
+  url: string;
+  /**
+   * `null` = `/Fields` absent → Include/Exclude is ignored and every field
+   * except NoExport-flagged ones is submitted (Table 239). `[]` =
+   * present-but-empty: include mode submits nothing, exclude mode submits
+   * everything eligible — presence and emptiness are different states.
+   */
+  fields: PdfActionTargetRef[] | null;
+  flags: SubmitFormFlags;
+  /** `/CharSet` (PDF 2.0), extracted but not encoded by this stack. */
+  charSet?: string;
+}
+interface PdfActionNodeCommon<Destination> {
+  /** Raw `/S` name, retained for unknown and future action types. */
+  subtype: string;
+  /** Normalized `/Next` children in PDF order. */
+  next: PdfActionNode<Destination>[];
+}
+/**
+ * One detached node in a normalized PDF action tree, discriminated on the
+ * interpreter that would execute it. Every executable arm carries its full
+ * payload — a `goto` without a destination or a `uri` without a URI is
+ * unrepresentable. A payload the reader cannot materialize degrades the node
+ * to `unknown` (original `/S` kept on `subtype`) and appends the tree-level
+ * `'payload-dropped'` warning. A `goto` goes to a {@link PageDestination};
+ * the engine's own readers, which work in the file's coordinates, use
+ * `PdfActionNode<PdfDestination>`.
+ */
+type PdfActionNode<Destination = PageDestination> = PdfActionNodeCommon<Destination> & ({
+  type: 'javascript';
+  script: string;
+} | {
+  type: 'goto';
+  destination: Destination;
+} | {
+  type: 'uri';
+  uri: string;
+  isMap: boolean;
+} | {
+  type: 'named';
+  name: string;
+} | {
+  type: 'hide';
+  targets: PdfActionTargetRef[];
+  hide: boolean;
+} | {
+  type: 'reset-form';
+  /**
+   * `null` = `/Fields` absent → reset every field (`exclude` is
+   * meaningless). `[]` = present-but-empty: with `exclude` false reset
+   * nothing, with `exclude` true reset everything — PDFium's executor
+   * branches on presence first.
+   */
+  fields: PdfActionTargetRef[] | null;
+  exclude: boolean;
+} |
+/** Reported, never executed. */
+{
+  type: 'goto-remote';
+  filePath: string;
+} | {
+  type: 'goto-embedded';
+  filePath: string;
+} | {
+  type: 'launch';
+  filePath: string;
+} |
+/** ISO allows `/Rendition` to carry `/JS`; preserved, not collected. */
+{
+  type: 'rendition';
+  script?: string;
+} |
+/** Recognized; executable only when `payload` is present. Absent payload
+ *  = extracted by a runtime without the SubmitForm getters (version
+ *  skew) — the node stays recognized-inert. */
+{
+  type: 'submit-form';
+  payload?: SubmitFormPayload;
+} | {
+  type: 'thread';
+} | {
+  type: 'sound';
+} | {
+  type: 'movie';
+} | {
+  type: 'import-data';
+} | {
+  type: 'set-ocg-state';
+} | {
+  type: 'transition';
+} | {
+  type: 'goto-3d-view';
+} | {
+  type: 'unknown';
+});
+type PdfActionWarning = 'cycle-dropped' | 'malformed-next' | 'incomplete' |
+/** A node's payload could not be read; that node degraded to `unknown`. */
+'payload-dropped';
+/**
+ * One extracted action root plus the native reader's safety verdict.
+ * Consumers must never execute a tree whose `incomplete` flag is true.
+ */
+interface PdfActionTree<Destination = PageDestination> {
+  /** Null when the model was valid but its root exceeded a safety bound. */
+  root: PdfActionNode<Destination> | null;
+  incomplete: boolean;
+  /** Raw native bits, retained so newer warnings survive older SDKs.
+   *  TS-detected warnings (`payload-dropped`) appear only in `warnings`. */
+  warningFlags: number;
+  warnings: PdfActionWarning[];
+}
+interface PdfFieldActions<Destination = PageDestination> {
+  keystroke?: PdfActionTree<Destination>;
+  format?: PdfActionTree<Destination>;
+  validate?: PdfActionTree<Destination>;
+  calculate?: PdfActionTree<Destination>;
+}
+//#endregion
+//#region src/identity/AnnotationRef.d.ts
+/**
+ * How callers address an annotation, and how the engine names one. Every
+ * annotation has one name for life:
+ *
+ *   - `objectNumber`: an annotation born as a PDF object, in the uploaded
+ *     file or written later. Object numbers are never reused.
+ *   - `baseIndex`: an annotation born inline in the uploaded file (a
+ *     dictionary in the page's `/Annots`, with no object number of its own).
+ *     Its name is its position in that page's `/Annots` in the uploaded
+ *     file, which never changes. It keeps this name after a write gives it
+ *     an object number.
+ *
+ * An annotation's `/NM` is data, not a name: files can carry the same one
+ * twice. A ref that names no annotation on its page fails with `NotFound`.
+ */
+type AnnotationRef = {
+  kind: 'objectNumber';
+  page: PageRef;
+  objectNumber: number;
+} | {
+  kind: 'baseIndex';
+  page: PageRef;
+  baseIndex: number;
+};
+//#endregion
+//#region src/identity/FormFieldRef.d.ts
+/**
+ * How callers address a logical form field.
+ *
+ * - `objectNumber` — the indirect object number of the field dictionary.
+ *   ISO 32000 guarantees every real AcroForm field dictionary is an
+ *   indirect object, and the layer runtime never renumbers (frozen base +
+ *   incremental deltas), so this is the durable identity for the lifetime
+ *   of a document. Preferred for all engine calls.
+ * - `fqn` — the fully qualified field name ("billing.name"). The portable,
+ *   semantic identity used by interchange formats (FDF/XFDF) and analytics;
+ *   survives document rewrites but is only as unique as the producer made
+ *   it. The engine resolves it against the reconciled field tree.
+ */
+type FormFieldRef = {
+  kind: 'objectNumber';
+  objectNumber: number;
+} | {
+  kind: 'fqn';
+  name: string;
+};
+/**
+ * A widget annotation of a field, as the field tree sees it. The forms reader
+ * learns widgets from the field's `/Kids`, not from a page's `/Annots`, so it
+ * must be able to report widgets the annotation subsystem cannot reach.
+ *
+ * `ref` is the widget as an annotation address, computed once by the engine:
+ * present exactly when the widget is an indirect object (`objectNumber > 0`)
+ * placed on a page (`page !== null`). In a conforming PDF every widget has
+ * one. `objectNumber` stays beside it because a widget can be an object on no
+ * page: it has a number but no annotation address, and the field still owns
+ * it (signature checks join changed objects to fields by these numbers).
+ */
+interface FormWidget {
+  /** The widget as an annotation address, or null when it cannot be addressed as one. */
+  ref: AnnotationRef | null;
+  /**
+   * The widget annotation's object number, whether or not it is on a page.
+   * `0` when the widget is stored as a direct object (spec-violating; it
+   * cannot be addressed).
+   */
+  objectNumber: number;
+  /**
+   * The page whose /Annots array references the widget; `null` when the
+   * widget is not reachable from any page ("unplaced").
+   */
+  page: PageRef | null;
+}
+//#endregion
+//#region src/geometry/pageSpace.d.ts
+/** A point in page space: x from the visible page's left edge, y down from its top edge. */
+interface PagePoint {
+  x: number;
+  y: number;
+}
+/** A box in page space: `x, y` is its top-left corner. */
+interface PageBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/**
+ * A quad in page space, with `PdfQuad`'s corner names. The names belong to
+ * the text's frame, so the flip to page space keeps them.
+ */
+interface PageQuad {
+  upperLeft: PagePoint;
+  upperRight: PagePoint;
+  lowerLeft: PagePoint;
+  lowerRight: PagePoint;
+}
+//#endregion
+//#region src/pageSpace/coordinates.d.ts
+/**
+ * The types a value's positions take, for a type that exists in both spaces
+ * (`TextLayout<PageCoordinates>`): the file's coordinates or page space.
+ */
+interface Coordinates {
+  point: {
+    x: number;
+    y: number;
+  };
+  box: object;
+  quad: object;
+  destination: object;
+}
+interface PageCoordinates extends Coordinates {
+  point: PagePoint;
+  box: PageBox;
+  quad: PageQuad;
+  destination: PageDestination;
+}
+//#endregion
+//#region src/forms/value-entry.d.ts
+/** Lossless shape of a field's effective PDF `/V` or `/DV` object. */
+type FormValueEntry = {
+  kind: 'none';
+} | {
+  kind: 'scalar';
+  value: string;
+} | {
+  kind: 'array';
+  values: string[];
+} | {
+  kind: 'unsupported';
+};
+//#endregion
+//#region src/forms/field.d.ts
+/**
+ * The field family — the discriminant of {@link FormFieldDTO}. Narrowing on
+ * it reveals exactly the members that are meaningful for that family, the
+ * same way annotation DTOs narrow on `subtype`.
+ */
+type FormFieldFamily = 'text' | 'checkbox' | 'radio' | 'combobox' | 'listbox' | 'pushbutton' | 'signature' | 'unknown';
+/**
+ * Where the field was found.
+ *
+ * - `acroform` — reachable from the /AcroForm /Fields tree, as the spec
+ *   requires.
+ * - `recovered` — only reachable through a page's /Annots array (a common
+ *   producer bug). The engine reconciles these on every read so they work
+ *   like any other field, but other PDF processors will not see them until
+ *   {@link DocumentFormsService.repair} makes the fix durable.
+ */
+type FormFieldOrigin = 'acroform' | 'recovered';
+/**
+ * A widget of a field: its address and its page. Its place, look and state
+ * are its row in the form's `widgets`, joined by `ref`.
+ */
+type FormFieldWidget = FormWidget;
+/**
+ * A widget of a toggle (checkbox/radio) field. Toggle widgets always carry
+ * their appearance-state machinery — no nullable fields to probe.
+ */
+interface ToggleFieldWidget extends FormFieldWidget {
+  /**
+   * The widget's appearance state name in the file (the non-"Off" key of
+   * its /AP /N dictionary), usually its export value. Writes never need it.
+   */
+  onState: string;
+  /**
+   * The widget's export value (/Opt entry when present, else the
+   * on-state). The identity FDF/XFDF carry.
+   */
+  exportValue: string;
+  /** Whether this widget is currently checked. */
+  checked: boolean;
+}
+/** One option of a choice (combo/list box) field. */
+interface FormFieldOption {
+  /** Display label shown to the user. */
+  label: string;
+  /** Export value used by /V, interchange, and `FormFieldValue.choice`. */
+  value: string;
+  /** Whether the option is currently selected. */
+  selected: boolean;
+}
+/**
+ * The trunk every field family shares: identity, provenance, universal
+ * flags, and widget placement. A logical field is the document-scoped
+ * record that holds the value; its widgets are page-scoped views — join
+ * them to the annotation subsystem via each widget's `ref`.
+ */
+interface FormFieldBase<C extends Coordinates = PageCoordinates> {
+  /**
+   * Durable ref: the field dictionary's object number, or its full name when
+   * the dictionary is a direct object (spec-violating) and has no number.
+   */
+  ref: FormFieldRef;
+  /** Fully qualified name, e.g. `"billing.name"`. */
+  name: string;
+  family: FormFieldFamily;
+  origin: FormFieldOrigin;
+  /**
+   * The user must not change the value. The engine's write transactions
+   * still accept programmatic writes to read-only fields (calculated
+   * fields are read-only yet script-written); enforcing fill policy is
+   * the application's job.
+   */
+  readOnly: boolean;
+  /** PDF apps ask for a value before the form is submitted. */
+  required: boolean;
+  /** Left out when the form is submitted or exported. */
+  noExport: boolean;
+  /** /TU — the accessible tooltip / alternate name. */
+  alternateName: string | null;
+  /** /TM — the export mapping name. */
+  mappingName: string | null;
+  /** Exact effective `/V` object shape; family conveniences below are derived. */
+  valueEntry: FormValueEntry;
+  /** Exact effective `/DV` object shape, including absent and malformed values. */
+  defaultValueEntry: FormValueEntry;
+  /** Effective inherited field `/AA` actions. */
+  actions?: PdfFieldActions<C['destination']>;
+  /**
+   * The group the field belongs to: who fills it in (the buyer's fields).
+   * `fields:` scopes grant filling in and signing by group. `null` for a
+   * field in no group.
+   */
+  groupId: string | null;
+  /**
+   * The user who created the field, as the creating session's identity
+   * named them; `null` for a field another tool made, or an anonymous
+   * session.
+   */
+  createdBy: string | null;
+  /** When the field was created; `null` when nobody recorded it. */
+  createdAt: IsoDateTime | null;
+  /**
+   * The user whose write last changed the value: a fill, or the script that
+   * fill ran (a calculated total counts as filled by whoever's fill
+   * calculated it). `null` after a reset, or when an anonymous session
+   * filled it last.
+   */
+  filledBy: string | null;
+  /** That user's display name, as their session gave it. */
+  filledByName: string | null;
+  /** When the value last changed by a fill; `null` with `filledBy`. */
+  filledAt: IsoDateTime | null;
+  /** The session that restored this field's attribution in an import. */
+  importedBy: string | null;
+  /** The field's widget annotations, in control order. May be empty ("unplaced"). */
+  widgets: FormFieldWidget[];
+}
+/** A text field. Write with `{ value }`. */
+interface TextFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'text';
+  value: string;
+  /** /DV — restored by `reset()`. */
+  defaultValue: string;
+  /** /MaxLen; `null` when unlimited. Longer writes are truncated to this length. */
+  maxLength: number | null;
+  multiline: boolean;
+  password: boolean;
+  /** Fixed character cells; meaningful with `maxLength`. */
+  comb: boolean;
+}
+/** A checkbox. Write with `{ checked }`, or `{ value }` naming a widget's export value. */
+interface CheckboxFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'checkbox';
+  checked: boolean;
+  /** The export value reported while checked ("Off" is never exported). */
+  exportValue: string;
+  widgets: ToggleFieldWidget[];
+}
+/** A radio group: One field, N widgets. Write with `{ value }`, a button's export value. */
+interface RadioFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'radio';
+  /** The checked widget's export value, or `"Off"` when the group is clear. */
+  value: string;
+  /** Widgets sharing an export value check together. */
+  radiosInUnison: boolean;
+  /** The group cannot be cleared once a choice is made. */
+  noToggleToOff: boolean;
+  widgets: ToggleFieldWidget[];
+}
+/** A combo box (dropdown). Write with `{ value }`. */
+interface ComboBoxFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'combobox';
+  /** An option export value — or free text when `edit` is set. */
+  value: string;
+  /** /DV — restored by `reset()`. */
+  defaultValue: string;
+  /** Free text is allowed in addition to the options. */
+  edit: boolean;
+  options: FormFieldOption[];
+}
+/** A list box. Write with `{ selectedValues }`. */
+interface ListBoxFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'listbox';
+  /** Selected option export values, in option order. */
+  selectedValues: string[];
+  /** /DV — the option values `reset()` selects. */
+  defaultValue: string[];
+  /** Whether several options may be selected at once. */
+  multiSelect: boolean;
+  options: FormFieldOption[];
+  /** The option shown in the box's top row (`/TI`): its position in `options`. */
+  topIndex: number;
+}
+/** A push button: pure trigger, holds no value. Never written or exported. */
+interface PushButtonFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'pushbutton';
+}
+/**
+ * A signature field: identity and placement only. Form writes never set a
+ * signature value; signing goes through the signatures API.
+ */
+interface SignatureFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'signature';
+}
+/**
+ * Forward-compat placeholder for field types the engine does not model,
+ * mirroring the `unsupported` annotation kind. Round-trips safely.
+ */
+interface UnknownFieldDTO<C extends Coordinates = PageCoordinates> extends FormFieldBase<C> {
+  family: 'unknown';
+  /** The raw /V value as text, for diagnostics. */
+  rawValue: string;
+}
+/**
+ * A logical form field. Discriminated on `family`:
+ *
+ * ```ts
+ * if (field.family === 'listbox') {
+ *   field.selectedValues; // string[]
+ * }
+ * ```
+ */
+type FormFieldDTO<C extends Coordinates = PageCoordinates> = TextFieldDTO<C> | CheckboxFieldDTO<C> | RadioFieldDTO<C> | ComboBoxFieldDTO<C> | ListBoxFieldDTO<C> | PushButtonFieldDTO<C> | SignatureFieldDTO<C> | UnknownFieldDTO<C>;
+//#endregion
+//#region src/dto/CachePins.d.ts
+/**
+ * Per-page cache-busting integers embedded in immutable cloud/CDN leaf URLs.
+ *
+ * These are not page state. They are read coordinates for cacheable endpoints,
+ * one per read family: `/text` and plain renders use `contentVersion`; the
+ * page's annotations (every annotation except widgets) use
+ * `annotationVersion`; the page's widget images use `widgetVersion`.
+ */
+interface CachePins {
+  contentVersion: number;
+  /** The page's annotations except widgets: their list and their images. */
+  annotationVersion: number;
+  /** The page's widgets: their images (`form/pages/{p}/appearances@`). */
+  widgetVersion: number;
+}
+//#endregion
+//#region src/mutation/MutationMeta.d.ts
+/**
+ * Cache pin patch returned by cloud mutations after the durable DB transaction
+ * commits.
+ *
+ * `previousDocVersion` makes partial page deltas safe: clients may apply the
+ * patch only when their cached manifest is exactly at that version. Otherwise
+ * they must refresh instead of manufacturing a mixed-version manifest.
+ *
+ * Deliberately does not carry plane scopes: scopes only ever move
+ * base → layer, and each mutation kind knows exactly which planes it owns, so
+ * the client flips them locally when absorbing this delta (the monotone-flip
+ * rule); the manifest is the authoritative source and the 404 → refresh rail
+ * the backstop.
+ */
+interface CacheDelta {
+  previousDocVersion: number;
+  docVersion: number;
+  /**
+   * New doc-level bulk annotations pin, present when this mutation bumped
+   * it (annotation CRUD, page insert/delete, redaction, flatten — see
+   * `DocumentManifest.annotationsVersion`). Absorbing it keeps the client's
+   * cached manifest addressing the fresh bulk leaf without a 404-refresh
+   * round trip.
+   */
+  annotationsVersion?: number;
+  /** New form pin, present when this mutation bumped it (see `DocumentManifest.formsVersion`). */
+  formsVersion?: number;
+  /**
+   * New plane pins, present when this mutation bumped them: `layoutVersion`
+   * for a page-structure write (move, rotate, delete, insert, names),
+   * `metadataVersion` for a metadata write, `attachmentsVersion` for an
+   * attachment write. Absorbing them re-points the cached manifest's leaf
+   * without a refetch.
+   */
+  layoutVersion?: number;
+  metadataVersion?: number;
+  attachmentsVersion?: number;
+  /**
+   * The layer's write serial after this mutation and whether an artifact
+   * now exists (cloud only). Absorbing them keeps the client's cached
+   * manifest an honest `DocumentVersionRef` source between refreshes.
+   */
+  layerVersion?: number;
+  working?: boolean;
+  pages: Array<{
+    page: PageRef;
+    cache: CachePins;
+  }>;
+}
+/**
+ * Base envelope for every layer-mutating operation: the `meta` of every
+ * write result.
+ *
+ * `affectedPages` names the pages whose annotations or content the write
+ * changed. `cacheDelta` is the cloud/CDN URL pin delta and is `null` for
+ * local engines (and for a write that changed nothing).
+ */
+interface MutationMeta {
+  affectedPages: PageRef[];
+  cacheDelta: CacheDelta | null;
+  /**
+   * The write's id: the `opId` it was given, or the one minted for it. Its
+   * events carry it as `origin.tx.id`, and `doc.apply({ undoOf: opId })`
+   * undoes the write.
+   */
+  opId: string;
+  /**
+   * Whether `{ undoOf: opId }` can undo the write. False for a write that
+   * changed nothing, and for the final writes: redaction apply, flatten,
+   * signing and form repair. A final write also ends undo for every write
+   * before it on the layer.
+   */
+  undoable: boolean;
+}
+/** DocMDP / `/Lock /P` permission values (ISO 32000-2 Table 257). */
+type DocMdpPermission = 1 | 2 | 3;
+/**
+ * The modification level a signed document allows, as a product policy:
+ *   - `none`: no byte change at all (not a DocMDP value)
+ *   - `lta`: DSS and document timestamps only (P = 1)
+ *   - `fill`: + form fill, signatures, new signature fields (P = 2)
+ *   - `annotate`: + annotations (P = 3, and how a validator reads an approval
+ *     signature)
+ */
+type ModificationLevel = 'none' | 'lta' | 'fill' | 'annotate';
+type FieldLockAction = 'all' | 'include' | 'exclude';
+/** A FieldMDP transform or a field `/Lock`: which fields it freezes, and an optional `/P` tightening. */
+interface FieldLockSpec {
+  action: FieldLockAction;
+  /** Fully qualified names; a name covers its descendants (`group` covers `group.total`). Empty for `all`. */
+  fields: string[];
+  permission?: DocMdpPermission;
+}
+/** A lock an earlier signature established on the current bytes. */
+interface DocumentFieldLock {
+  signatureIndex: number;
+  source: 'fieldmdp' | 'lock';
+  spec: FieldLockSpec;
+}
+/**
+ * What the signatures already in a document mean for what comes after, in
+ * two separate answers:
+ *
+ *   - `enforced`: what a signer declared — a certification's /P, a signed
+ *     field's /Lock /P. The engine refuses what it forbids (mapped onto
+ *     capabilities like encryption permission bits). A plain approval
+ *     signature declares nothing: `null`.
+ *   - `judged`: what a validator holds later changes to — the declared level,
+ *     or the approval baseline (`annotate`: form fill-in, signing and
+ *     annotations keep the signature valid, anything else does not;
+ *     Acrobat's reading, ISO 32000 is silent) when only approval signatures
+ *     exist. Never refused, only judged.
+ */
+interface DocumentProtection {
+  /** Declared and enforced; `null` when nothing declared (unsigned, or approval signatures only). */
+  enforced: ModificationLevel | null;
+  /** Judged; `null` when nothing is signed. */
+  judged: ModificationLevel | null;
+  certification: {
+    signatureIndex: number;
+    permission: DocMdpPermission;
+  } | null;
+  fieldLocks: DocumentFieldLock[];
+  /** The versioned product policy that derived this. */
+  policyVersion: number;
+}
+//#endregion
+//#region src/forms/snapshot.d.ts
+/**
+ * What kind of interactive form the document declares.
+ *
+ * - `none` — no /AcroForm dictionary. Recovered fields may still exist
+ *   (see {@link FormFieldOrigin}); `repair()` can bootstrap the dictionary.
+ * - `acroform` — a standard AcroForm.
+ * - `xfa` — the /AcroForm carries an /XFA entry. The engine serves the
+ *   AcroForm shell read-only and never executes XFA.
+ */
+type FormKind = 'none' | 'acroform' | 'xfa';
+//#endregion
+//#region src/search/types.d.ts
+/**
+ * What to search for — the one shape, engine → wire → plugin state →
+ * search box. One flat object; the flags define behavior per mode instead
+ * of the mode changing the shape:
+ *
+ * | flag              | literal          | regex                          |
+ * |-------------------|------------------|--------------------------------|
+ * | `matchCase`       | fold case        | `i` flag                       |
+ * | `wholeWord`       | boundary check   | pattern is `\b(?:…)\b`-wrapped |
+ * | `matchDiacritics` | mark fold        | rejected (`InvalidArg`)        |
+ * | `ignoreWhitespace`| whitespace drop  | rejected (`InvalidArg`)        |
+ *
+ * Literal queries match over folded text; regex queries run the portable
+ * dialect against the raw page text — which is why `matchDiacritics` and
+ * `ignoreWhitespace` cannot apply to them (diacritic folding and whitespace
+ * dropping are properties of the folded text plane; a pattern spells its
+ * own `\s*`). Validate with `validateSearchQuery` for early UI feedback;
+ * engines re-validate and reject with `EngineErrorCode.InvalidArg`.
+ */
+interface SearchQuery {
+  /**
+   * The literal text — or, when `regex`, a pattern in the portable
+   * search-regex dialect: JavaScript `u`-mode syntax minus backreferences
+   * and lookaround, so every valid pattern also runs on RE2 (the
+   * server-side engine).
+   */
+  text: string;
+  /** Interpret `text` as a regex pattern. Default false (literal). */
+  regex?: boolean;
+  /** Exact-case matching. Default false (case-folded / `i` semantics). */
+  matchCase?: boolean;
+  /** Only match at word boundaries (letters/digits end the word). */
+  wholeWord?: boolean;
+  /**
+   * Treat diacritics as significant ("café" ≠ "cafe"). Default false —
+   * marks are stripped on both sides, which is what viewers ship.
+   * Literal only: combined with `regex` the query is rejected.
+   */
+  matchDiacritics?: boolean;
+  /**
+   * Drop whitespace on both sides instead of collapsing it, so "invoice"
+   * finds the letter-spaced "i n v o i c e" that OCR and tracked-out headings
+   * produce, and "total amount" finds "totalamount". Default false — the default
+   * fold collapses whitespace runs to one space, so a needle still has to
+   * carry a space wherever the page does. A hit spans the original text
+   * including the dropped whitespace; with `wholeWord` the boundaries are
+   * checked on the original text (the folded plane has no word gaps left).
+   * Literal only: combined with `regex` the query is rejected.
+   */
+  ignoreWhitespace?: boolean;
+}
+//#endregion
+//#region src/mutation/RedactionApplyResult.d.ts
+/** Whether a page was redacted, or had nothing to apply. A page that fails fails the whole call. */
+type RedactionApplyStatus = 'applied' | 'unchanged';
+/**
+ * What to apply. `pages` applies every redact annotation on each listed
+ * page; `annotations` applies exactly the referenced redact annotations
+ * (every `AnnotationRef` carries its page, so no separate page list is
+ * needed). Referencing a non-redact annotation fails that page with
+ * `InvalidArg` before anything is written.
+ */
+type RedactionApplyScope = {
+  pages: PageRef[];
+} | {
+  annotations: AnnotationRef[];
+};
+interface RedactionApplyItemResult {
+  page: PageRef;
+  status: RedactionApplyStatus;
+  /**
+   * Annotations other than redact ones removed on this page as a side
+   * effect (popup cascades and detached form widgets included). The
+   * consumed redact annotations themselves are never counted — this is
+   * the "collateral" signal for confirm dialogs and audit logs.
+   */
+  removedAnnotationCount: number;
+}
+/**
+ * Apply is a content + annotation mutation, never a layout mutation:
+ * content under each redacted region is destroyed, the configured overlay
+ * (`/RO`, else `/IC` + `/OverlayText`) is painted into page content, and
+ * the consumed redact annotations (plus intersecting collateral) are
+ * removed. All or nothing: a page that fails, or a cancel, leaves every page
+ * as it was.
+ */
+interface RedactionApplyResult {
+  /** The original request, retained for audit/event replay. */
+  scope: RedactionApplyScope;
+  results: RedactionApplyItemResult[];
+  /** Total {@link RedactionApplyItemResult.removedAnnotationCount} across all pages. */
+  removedAnnotationCount: number;
+  meta: MutationMeta;
+}
+//#endregion
+export { RedactionApplyResult as a, FormKind as i, FormFieldDTO as n, SearchQuery as o, FormFieldRef as r, DocumentProtection as t };
+//# sourceMappingURL=AnnotationList-CkijRHet-HEFNUIZe.d.ts.map